@jacebenson/jsn 3.2.0 → 3.3.0

package/bin/jsn.js

@@ -1,5 +1,17 @@
 #!/usr/bin/env node
 
-import { cli } from '../src/cli.js';
+// Suppress the node:sqlite experimental warning on Node 22.x.
+// SQLite is stable in Node 24+. The patch must be applied before any
+// module imports node:sqlite, so we use a dynamic import after patching.
+const originalEmitWarning = process.emitWarning;
+process.emitWarning = function emitWarning(warning, ...args) {
+  const message = typeof warning === 'string'
+    ? warning
+    : (warning?.message || '');
+  if (message.includes('SQLite')) {
+    return;
+  }
+  return originalEmitWarning.apply(this, [warning, ...args]);
+};
 
-cli.parse();
+import('../src/cli.js').then((m) => m.cli.parse());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {
@@ -8,10 +8,10 @@
   },
   "main": "src/cli.js",
   "scripts": {
-    "test": "node --test $(find test -name '*.test.js')",
+    "test": "NODE_OPTIONS=--require=./suppress-warnings.cjs node --test $(find test -name '*.test.js')",
     "lint": "npx eslint src/ bin/ test/",
     "postinstall": "node scripts/postinstall.mjs",
-    "start": "node bin/jsn.js",
+    "start": "NODE_OPTIONS=--require=./suppress-warnings.cjs node bin/jsn.js",
     "tag-reminder": "node scripts/tag-reminder.js",
     "release": "node scripts/release.js"
   },
@@ -24,13 +24,14 @@
   "author": "Jace Benson",
   "license": "MIT",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.5.0"
   },
   "dependencies": {
     "@inquirer/core": "^10.1.0",
     "@inquirer/prompts": "^7.5.1",
     "chalk": "^5.4.1",
     "cli-table3": "^0.6.5",
+    "gray-matter": "^4.0.3",
     "yargs": "^17.7.2"
   },
   "devDependencies": {
@@ -40,6 +41,7 @@
   },
   "files": [
     "bin/jsn.js",
+    "suppress-warnings.cjs",
     "src/",
     "skills/",
     "scripts/",

package/skills/servicenow/SKILL.md

@@ -54,9 +54,10 @@ Pick the most specific tool for the job. **Never default to eval** — it's the
 
 1. **Specific commands** — `jsn flows`, `jsn rules`, `jsn catalogitems`, etc.
 2. **`jsn records --table <name>`** — generic CRUD on any table
-3. **`jsn rest`** — raw Table API escape hatch
-4. **`jsn eval`** — ⚠️ **LAST RESORT ONLY**
-5. **Ask the human** — if none of the above work
+3. **`jsn docs search <query>`** — offline ServiceNow documentation search (no instance needed)
+4. **`jsn rest`** — raw Table API escape hatch
+5. **`jsn eval`** — ⚠️ **LAST RESORT ONLY**
+6. **Ask the human** — if none of the above work
 
 ## Key Commands
 
@@ -69,6 +70,7 @@ Pick the most specific tool for the job. **Never default to eval** — it's the
 | **UX** | `forms` (section/element layout), `lists`, `clientscripts`, `uipolicies` |
 | **Data** | `tables`, `columns`, `includes`, `logs`, `properties`, `records` |
 | **Config** | `setup`, `auth`, `profiles`, `updatesets`, `scopes` |
+| **Docs** | `docs sync`, `docs status`, `docs search`, `docs serve` |
 | **Developer** | `eval`, `rest`, `skill`, `version` |
 
 ### `jsn rest` examples
@@ -84,6 +86,32 @@ jsn rest --table incident --sys-id abc123... --json
 jsn rest "/api/now/table/incident?sysparm_limit=3" --json
 ```
 
+### `jsn docs` — offline documentation search
+
+No ServiceNow instance required. Searches the full ServiceNow docs locally with FTS5 + semantic hybrid search.
+
+```bash
+# First run: download docs and build the index (~45k files, ~3-5 min)
+jsn docs sync
+
+# Check state
+jsn docs status
+
+# Search (keyword + semantic hybrid)
+jsn docs search "GlideRecord query" --limit 5 --json
+
+# Filter by bundle
+jsn docs search "REST API" --bundle it-service-management --json
+
+# Start the web UI
+jsn docs serve
+
+# Share on your network
+jsn docs serve --expose
+```
+
+**Re-running `jsn docs sync`** does a smart incremental refresh — pulls latest docs and only rebuilds changed files (seconds, not minutes).
+
 ## Troubleshooting Field Behavior
 
 Check order (priority):

package/src/cli.js

@@ -27,8 +27,9 @@ import { groupRolesCmd } from './commands/grouproles.js';
 import { ticketsCmd } from './commands/tickets.js';
 import { versionCmd } from './commands/version.js';
 import { devCmd } from './commands/dev.js';
-import { skillCmd } from './commands/skill.js';
+import { skillCmd, checkSkill } from './commands/skill.js';
 import { getVersion, checkLatest } from './commands/version.js';
+import { docsCmd } from './commands/docs/docs.js';
 
 // Dev subcommands promoted to root level for progressive disclosure
 import {
@@ -178,7 +179,7 @@ export function buildCLI() {
       // Guard mutation commands when no instance configured
       (argv) => {
         const cmd = (argv._[0] || '').toString();
-        if (!cmd || ['help', 'version', 'completion', 'setup', 'auth', 'profiles', 'skill'].includes(cmd)) {
+        if (!cmd || ['help', 'version', 'completion', 'setup', 'auth', 'profiles', 'skill', 'docs'].includes(cmd)) {
           return;
         }
         // Check for --instance override
@@ -204,10 +205,15 @@ export function buildCLI() {
 
       // Daily npm version check (fire-and-forget, non-blocking)
       // Checks npm for newer jsn releases, at most once per 24 hours.
-      const skipNpmCheck = ['help', 'version', 'completion', 'skill'].includes(cmd)
+      const skipNpmCheck = ['help', 'version', 'completion', 'skill', 'docs'].includes(cmd)
         || process.env.JSN_NO_VERSION_CHECK === '1'
         || argv.json
         || argv.quiet;
+
+      // Auto-check skill on every command (fire-and-forget, non-blocking)
+      const skipSkillCheck = ['help', 'version', 'completion', 'skill', 'docs'].includes(cmd)
+        || process.env.JSN_NO_SKILL_CHECK === '1'
+        || argv['no-skill-check']
       if (!skipNpmCheck) {
         const cacheFile = path.join(globalConfigDir(), '.last-npm-check');
         let shouldCheck = true;
@@ -239,7 +245,7 @@ export function buildCLI() {
       }
 
       // Print context header for interactive terminals
-      if (!['help', 'version', 'completion', 'skill'].includes(cmd)) {
+      if (!['help', 'version', 'completion', 'skill', 'docs'].includes(cmd)) {
         await argv.app.printContextHeader(argv);
       }
     })
@@ -322,6 +328,7 @@ export function buildCLI() {
     .command(evalCmd(wrap))
     .command(restCmd(wrap))
     .command(skillCmd(wrap))
+    .command(docsCmd(wrap))
     .command(versionCmd(wrap))
     // Legacy
     .command(devCmd(wrap))

package/src/commands/docs/db.js

@@ -0,0 +1,140 @@
+// Docs DB path resolution and schema helpers.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { DatabaseSync } from 'node:sqlite';
+
+const DOCS_DIR_NAME = 'servicenow-cli/docs';
+
+function xdgCacheHome() {
+  if (process.env.XDG_CACHE_HOME) return process.env.XDG_CACHE_HOME;
+  return path.join(os.homedir(), '.cache');
+}
+
+export function getDocsCacheDir() {
+  return path.join(xdgCacheHome(), DOCS_DIR_NAME);
+}
+
+export function getDocsDbPath() {
+  return path.join(getDocsCacheDir(), 'docs.db');
+}
+
+export function getDocsSourceDir() {
+  return path.join(getDocsCacheDir(), 'source');
+}
+
+export function getDocsSourceMarkdownDir() {
+  return path.join(getDocsSourceDir(), 'markdown');
+}
+
+export function ensureDocsCacheDir() {
+  const dir = getDocsCacheDir();
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function openDocsDb(opts = {}) {
+  const dbPath = opts.dbPath || getDocsDbPath();
+  ensureDocsCacheDir();
+  const db = new DatabaseSync(dbPath);
+  db.exec('PRAGMA journal_mode = WAL');
+  return db;
+}
+
+export function closeDocsDb(db) {
+  try {
+    db.close();
+  } catch {
+    // ignore
+  }
+}
+
+export function docsDbExists() {
+  return fs.existsSync(getDocsDbPath());
+}
+
+export function getSchemaVersion(db) {
+  try {
+    const row = db.prepare("SELECT value FROM meta WHERE key='schema_version'").get();
+    return row ? parseInt(row.value, 10) : 0;
+  } catch {
+    return 0;
+  }
+}
+
+export function setSchemaVersion(db, version) {
+  db.exec("CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT)");
+  db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES('schema_version', ?)").run(String(version));
+}
+
+export function initDocsSchema(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS docs (
+      id          INTEGER PRIMARY KEY,
+      path        TEXT NOT NULL UNIQUE,
+      title       TEXT,
+      release     TEXT,
+      bundle      TEXT,
+      doc_type    TEXT,
+      locale      TEXT,
+      frontmatter TEXT,
+      body        TEXT,
+      size        INTEGER,
+      mtime       INTEGER,
+      hash        TEXT,
+      hrr_vector  BLOB
+    );
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS docs_fts USING fts5(
+      title, body,
+      content='docs',
+      content_rowid='id',
+      tokenize='porter unicode61'
+    );
+
+    CREATE TRIGGER IF NOT EXISTS docs_ai AFTER INSERT ON docs BEGIN
+      INSERT INTO docs_fts(rowid, title, body) VALUES (new.id, new.title, new.body);
+    END;
+    CREATE TRIGGER IF NOT EXISTS docs_ad AFTER DELETE ON docs BEGIN
+      INSERT INTO docs_fts(docs_fts, rowid, title, body) VALUES('delete', old.id, old.title, old.body);
+    END;
+    CREATE TRIGGER IF NOT EXISTS docs_au AFTER UPDATE ON docs BEGIN
+      INSERT INTO docs_fts(docs_fts, rowid, title, body) VALUES('delete', old.id, old.title, old.body);
+      INSERT INTO docs_fts(rowid, title, body) VALUES (new.id, new.title, new.body);
+    END;
+
+    CREATE INDEX IF NOT EXISTS idx_docs_bundle   ON docs(bundle);
+    CREATE INDEX IF NOT EXISTS idx_docs_doc_type ON docs(doc_type);
+    CREATE INDEX IF NOT EXISTS idx_docs_release  ON docs(release);
+
+    CREATE TABLE IF NOT EXISTS meta (
+      key TEXT PRIMARY KEY,
+      value TEXT
+    );
+  `);
+  setSchemaVersion(db, 1);
+}
+
+export function hasEmbeddings(db) {
+  try {
+    const cols = db.prepare('PRAGMA table_info(docs)').all();
+    if (!cols.some((c) => c.name === 'hrr_vector')) return false;
+    return db.prepare('SELECT COUNT(*) AS n FROM docs WHERE hrr_vector IS NOT NULL').get().n > 0;
+  } catch {
+    return false;
+  }
+}
+
+export function getMeta(db, key, defaultValue = null) {
+  try {
+    const row = db.prepare('SELECT value FROM meta WHERE key = ?').get(key);
+    return row ? row.value : defaultValue;
+  } catch {
+    return defaultValue;
+  }
+}
+
+export function setMeta(db, key, value) {
+  db.prepare('INSERT OR REPLACE INTO meta(key, value) VALUES(?, ?)').run(key, value);
+}

package/src/commands/docs/docs.js

@@ -0,0 +1,166 @@
+// jsn docs — ServiceNow documentation search.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import net from 'node:net';
+import process from 'node:process';
+import {
+  getDocsDbPath, getDocsSourceDir, getDocsSourceMarkdownDir, docsDbExists,
+  openDocsDb, closeDocsDb, getMeta,
+} from './db.js';
+import { syncDocs } from './sync.js';
+import { refreshDocs } from './refresh.js';
+import { embedDocs } from './embed.js';
+import { searchDocs } from './search.js';
+import { serveDocs } from './serve.js';
+
+function formatBytes(n) {
+  if (n == null) return '-';
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+export function docsCmd(wrap) {
+  return {
+    command: 'docs [subcommand]',
+    describe: 'Search ServiceNow documentation locally (sync, status, search, serve)',
+    builder: (yargs) => {
+      return yargs
+        .command({
+          command: 'sync',
+          describe: 'Clone/update ServiceNowDocs and build the docs.db index',
+          builder: (y) => y
+            .option('no-embed', { type: 'boolean', describe: 'Skip HRR semantic embeddings' })
+            .option('no-ingest', { type: 'boolean', describe: 'Clone/pull only; do not rebuild index' }),
+          handler: wrap(async (argv, app) => {
+            const result = syncDocs({
+              markdownDir: getDocsSourceMarkdownDir(),
+              dbPath: getDocsDbPath(),
+              embed: argv['no-embed'] !== true,
+              noIngest: argv['no-ingest'] === true,
+            });
+            app.ok(result, { summary: 'Docs sync complete' });
+          }),
+        })
+        .command({
+          command: 'status',
+          describe: 'Show docs database status',
+          handler: wrap(async (argv, app) => {
+            const dbPath = getDocsDbPath();
+            const repoDir = getDocsSourceDir();
+            const markdownDir = getDocsSourceMarkdownDir();
+            const downloaded = fs.existsSync(path.join(repoDir, '.git')) && fs.existsSync(markdownDir);
+            const dbExists = docsDbExists();
+
+            let state, embedded, documents, bundles, docTypes, syncedAt, dbSize;
+            if (dbExists) {
+              const db = openDocsDb();
+              documents = db.prepare('SELECT COUNT(*) AS n FROM docs').get().n;
+              bundles = db.prepare('SELECT COUNT(DISTINCT bundle) AS n FROM docs').get().n;
+              docTypes = db.prepare('SELECT COUNT(DISTINCT doc_type) AS n FROM docs').get().n;
+              const embCount = db.prepare('SELECT COUNT(*) AS n FROM docs WHERE hrr_vector IS NOT NULL').get().n;
+              syncedAt = getMeta(db, 'synced_at');
+              const stat = fs.statSync(dbPath);
+              dbSize = stat.size;
+              closeDocsDb(db);
+
+              embedded = embCount >= documents && documents > 0;
+              if (embedded) state = 'ready';
+              else if (documents > 0) state = 'indexed (not embedded)';
+              else state = 'empty';
+            } else {
+              state = downloaded ? 'not indexed' : 'not downloaded';
+              embedded = false;
+            }
+
+            // Quick probe to see if the server is running on the default port.
+            const served = await new Promise((resolve) => {
+              const sock = new net.Socket();
+              sock.setTimeout(500);
+              sock.on('connect', () => { sock.destroy(); resolve(true); });
+              sock.on('error', () => resolve(false));
+              sock.on('timeout', () => { sock.destroy(); resolve(false); });
+              sock.connect(3000, '127.0.0.1');
+            });
+
+            app.ok({
+              state,
+              downloaded: { ok: downloaded, path: repoDir },
+              db: { ok: dbExists, path: dbPath },
+              embedded: { ok: embedded },
+              ...(documents != null && { documents, bundles, docTypes, syncedAt: syncedAt ? new Date(parseInt(syncedAt, 10)).toISOString() : null }),
+              ...(dbSize != null && { dbSizeHuman: formatBytes(dbSize) }),
+              ...(served && { served: 'http://127.0.0.1:3000' }),
+            }, { summary: `Docs database: ${state}` });
+          }),
+        })
+        .command({
+          command: 'search <query>',
+          describe: 'Search docs (FTS5 + optional HRR hybrid rerank)',
+          builder: (y) => y
+            .positional('query', { type: 'string', describe: 'Search query' })
+            .option('limit', { type: 'number', default: 20, describe: 'Max results' })
+            .option('offset', { type: 'number', default: 0, describe: 'Result offset' })
+            .option('bundle', { type: 'string', describe: 'Filter by bundle' })
+            .option('doc-type', { type: 'string', describe: 'Filter by doc type' })
+            .option('mode', { type: 'string', choices: ['keyword', 'hybrid'], default: 'hybrid', describe: 'Search mode' }),
+          handler: wrap(async (argv, app) => {
+            const result = searchDocs({
+              query: argv.query,
+              limit: argv.limit,
+              offset: argv.offset,
+              bundle: argv.bundle,
+              docType: argv['doc-type'],
+              mode: argv.mode,
+            });
+            app.ok(result, { summary: `${result.count} result(s) for "${result.query}" (${result.mode})` });
+          }),
+        })
+        .command({
+          command: 'serve',
+          describe: 'Start the docs search web UI',
+          builder: (y) => y
+            .option('port', { type: 'number', default: 3000, describe: 'HTTP port' })
+            .option('host', { type: 'string', default: '127.0.0.1', describe: 'Bind address' })
+            .option('expose', { type: 'boolean', default: false, describe: 'Bind to 0.0.0.0 to expose on the network' }),
+          handler: wrap(async (argv, _app) => {
+            try {
+              const host = argv.expose ? '0.0.0.0' : argv.host;
+              await serveDocs({ port: argv.port, host });
+            } catch (err) {
+              process.stderr.write(`Error: ${err.message}\n`);
+              process.exit(1);
+            }
+          }),
+        })
+        .command({
+          command: 'embed',
+          describe: 'Backfill or refresh HRR semantic embeddings',
+          handler: wrap(async (argv, app) => {
+            const result = embedDocs();
+            app.ok(result, { summary: `Embedded ${result.embedded} of ${result.total} docs` });
+          }),
+        })
+        .command({
+          command: 'refresh',
+          describe: 'Incrementally refresh docs.db from existing source clone',
+          handler: wrap(async (argv, app) => {
+            const result = refreshDocs({ docsDir: getDocsSourceMarkdownDir() });
+            app.ok(result, { summary: `Refresh complete: +${result.added} ~${result.updated} -${result.removed} =${result.unchanged}` });
+          }),
+        });
+    },
+    handler: () => {
+      process.stdout.write('jsn docs — ServiceNow documentation search\n\n');
+      process.stdout.write('Available subcommands:\n');
+      process.stdout.write('  sync      Download docs and build a searchable index (handles updates too)\n');
+      process.stdout.write('  status    Show whether docs are downloaded, indexed, embedded, or served\n');
+      process.stdout.write('  search    Full-text + semantic search across the local docs index\n');
+      process.stdout.write('  serve     Start a local web UI for browsing and searching docs\n');
+      process.stdout.write('\n');
+      process.stdout.write('Tip: use "jsn docs serve --expose" to bind to 0.0.0.0 and share on your network.\n');
+      process.stdout.write('\nRun "jsn docs <command> --help" for details.\n');
+    },
+  };
+}

package/src/commands/docs/embed.js

@@ -0,0 +1,46 @@
+// Populate HRR phase-vector embeddings for semantic reranking.
+
+import fs from 'node:fs';
+import { openDocsDb, closeDocsDb, getDocsDbPath } from './db.js';
+import { encodeText, phasesToBytes, docSurface, DEFAULT_DIM } from './hrr.js';
+
+export function embedDocs(opts = {}) {
+  const dbPath = opts.dbPath || getDocsDbPath();
+
+  if (!fs.existsSync(dbPath)) {
+    throw new Error(`Database not found: ${dbPath}. Run "jsn docs sync" first.`);
+  }
+
+  const db = openDocsDb({ dbPath });
+
+  const cols = db.prepare('PRAGMA table_info(docs)').all();
+  if (!cols.some((c) => c.name === 'hrr_vector')) {
+    db.exec('ALTER TABLE docs ADD COLUMN hrr_vector BLOB');
+  }
+
+  db.exec("CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT)");
+  db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES('hrr_dim', ?)").run(String(DEFAULT_DIM));
+
+  const rows = db.prepare('SELECT id, title, body FROM docs WHERE hrr_vector IS NULL').all();
+  const total = db.prepare('SELECT COUNT(*) AS n FROM docs').get().n;
+
+  const update = db.prepare('UPDATE docs SET hrr_vector = ? WHERE id = ?');
+  const started = Date.now();
+  let n = 0;
+
+  db.exec('BEGIN');
+  for (const row of rows) {
+    const surface = docSurface(row.title, row.body);
+    const vec = encodeText(surface, DEFAULT_DIM);
+    update.run(phasesToBytes(vec), row.id);
+    n++;
+    if (n % 5000 === 0) process.stderr.write(`  ...${n}\n`);
+  }
+  db.exec('COMMIT');
+  db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+  db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES('embeddings', ?)").run('true');
+  closeDocsDb(db);
+
+  const secs = ((Date.now() - started) / 1000).toFixed(1);
+  return { embedded: n, total, secs, dbPath };
+}

package/src/commands/docs/hrr.js

@@ -0,0 +1,95 @@
+// Holographic Reduced Representations (HRR) — phase-vector encoding.
+//
+// Pure-JS port of Hermes' plugins/memory/holographic/holographic.py.
+// A concept is a fixed-width vector of phases in [0, 2π). Tokens become
+// deterministic phase vectors (SHA-256 -> uint16 -> angle); a text is the
+// "bundle" (circular mean) of its token vectors. Similarity is mean(cos(a-b)).
+
+import { createHash } from 'node:crypto';
+
+const TWO_PI = 2 * Math.PI;
+export const DEFAULT_DIM = 512;
+
+export function encodeAtom(word, dim = DEFAULT_DIM) {
+  const valuesPerBlock = 16;
+  const blocks = Math.ceil(dim / valuesPerBlock);
+  const phases = new Float64Array(dim);
+  let idx = 0;
+  for (let i = 0; i < blocks && idx < dim; i++) {
+    const digest = createHash('sha256').update(`${word}:${i}`).digest();
+    for (let j = 0; j < 32 && idx < dim; j += 2) {
+      const v = digest.readUInt16LE(j);
+      phases[idx++] = v * (TWO_PI / 65536);
+    }
+  }
+  return phases;
+}
+
+export function tokenize(text) {
+  return (text || '')
+    .toLowerCase()
+    .split(/\s+/)
+    .map((t) => t.replace(/^[.,!?;:"'()[\]{}]+|[.,!?;:"'()[\]{}]+$/g, ''))
+    .filter(Boolean);
+}
+
+export function bundle(vectors, dim = DEFAULT_DIM) {
+  const re = new Float64Array(dim);
+  const im = new Float64Array(dim);
+  for (const v of vectors) {
+    for (let k = 0; k < dim; k++) {
+      re[k] += Math.cos(v[k]);
+      im[k] += Math.sin(v[k]);
+    }
+  }
+  const out = new Float64Array(dim);
+  for (let k = 0; k < dim; k++) {
+    let a = Math.atan2(im[k], re[k]);
+    if (a < 0) a += TWO_PI;
+    out[k] = a;
+  }
+  return out;
+}
+
+export function encodeText(text, dim = DEFAULT_DIM) {
+  const tokens = tokenize(text);
+  if (tokens.length === 0) return encodeAtom('__hrr_empty__', dim);
+  return bundle(tokens.map((t) => encodeAtom(t, dim)), dim);
+}
+
+export function similarity(a, b) {
+  const dim = a.length;
+  let sum = 0;
+  for (let k = 0; k < dim; k++) sum += Math.cos(a[k] - b[k]);
+  return sum / dim;
+}
+
+export function phasesToBytes(phases) {
+  const buf = Buffer.allocUnsafe(phases.length * 2);
+  for (let k = 0; k < phases.length; k++) {
+    let q = Math.round((phases[k] / TWO_PI) * 65536) % 65536;
+    if (q < 0) q += 65536;
+    buf.writeUInt16LE(q, k * 2);
+  }
+  return buf;
+}
+
+export function bytesToPhases(buf) {
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  const dim = buf.byteLength / 2;
+  const phases = new Float64Array(dim);
+  for (let k = 0; k < dim; k++) {
+    phases[k] = view.getUint16(k * 2, true) * (TWO_PI / 65536);
+  }
+  return phases;
+}
+
+export function docSurface(title, body, maxBodyTokens = 40) {
+  const headings = (body || '')
+    .split('\n')
+    .filter((l) => /^#{1,6}\s/.test(l))
+    .map((l) => l.replace(/^#{1,6}\s+/, ''))
+    .join(' ');
+  const bodyStart = tokenize(body).slice(0, maxBodyTokens).join(' ');
+  return [title || '', headings, bodyStart].filter(Boolean).join(' ');
+}