@jacebenson/jsn 3.1.5 → 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.1.5",
+  "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/app.js

@@ -3,7 +3,7 @@
 import { AuthManager } from './auth.js';
 import { SDKClient } from './sdk.js';
 import { OutputWriter, FormatAuto, FormatJSON, FormatMarkdown, FormatQuiet, FormatStyled } from './output.js';
-import { getEffectiveInstance } from './config.js';
+import { getEffectiveInstance, normalizeInstanceURL } from './config.js';
 import { extractProfileName } from './helpers.js';
 import { getCurrentUser, getCurrentApplication, getCurrentUpdateSet } from './context.js';
 import { errUsage, errAuth } from './errors.js';
@@ -55,6 +55,8 @@ export class App {
   }
 
   getEffectiveInstance() {
+    // Command-line override (--instance, --profile) takes precedence
+    if (this._overrideInstance) return this._overrideInstance;
     return getEffectiveInstance(this.config);
   }
 
@@ -191,6 +193,18 @@ export class App {
       throw errAuth('Not authenticated');
     }
   }
+
+  /**
+   * Override the effective instance for this command run.
+   * Rebuilds the SDK client for the new instance.
+   */
+  setEffectiveInstance(url) {
+    const normalizedUrl = normalizeInstanceURL(url);
+    if (normalizedUrl) {
+      this._overrideInstance = normalizedUrl;
+      this.sdk = new SDKClient(normalizedUrl, this.auth);
+    }
+  }
 }
 
 function resolveFormat(fmt) {

package/src/auth.js

@@ -58,6 +58,24 @@ function removePKCEState(instance) {
 const DEFAULT_OAUTH_CLIENT_ID = '543e5655f77746a28228c6009a599dfb';
 const REDIRECT_URI = '/sdk-oauth.do';
 
+// ─── WSL detection ───
+
+/**
+ * Detect if running under Windows Subsystem for Linux.
+ * Reads /proc/version which contains "Microsoft" or "WSL" on WSL.
+ */
+let _cachedIsWSL = null;
+async function isWSLEnv() {
+  if (_cachedIsWSL !== null) return _cachedIsWSL;
+  try {
+    const data = fs.readFileSync('/proc/version', 'utf-8');
+    _cachedIsWSL = /microsoft|wsl/i.test(data);
+  } catch {
+    _cachedIsWSL = false;
+  }
+  return _cachedIsWSL;
+}
+
 // ─── Basic auth from environment variables ───
 // SN_USERNAME / SN_PASSWORD — global credentials
 // SN_<INSTANCE>_USERNAME / SN_<INSTANCE>_PASSWORD — instance-specific (e.g. SN_DEV328604_USERNAME)
@@ -386,10 +404,23 @@ export class AuthManager {
       args = [authURL];
     } else if (platform === 'win32') {
       cmd = 'cmd';
-      args = ['/c', 'start', authURL];
+      // Windows: cmd.exe interprets & as a command separator, which truncates
+      // the URL after the first parameter. Passing an empty string as the first
+      // arg to `start` serves as the window title, and spawn auto-quotes the
+      // URL arg, protecting & and other special chars from cmd.exe's parser.
+      args = ['/c', 'start', '', authURL];
     } else {
-      cmd = 'xdg-open';
-      args = [authURL];
+      // WSL detection: check if we're running under Windows Subsystem for Linux
+      // On WSL, xdg-open delegates to cmd.exe /C start <url>, which truncates
+      // on &. We call cmd.exe directly with proper quoting instead.
+      const isWSL = platform === 'linux' && (await isWSLEnv());
+      if (isWSL) {
+        cmd = 'cmd.exe';
+        args = ['/c', 'start', '', authURL];
+      } else {
+        cmd = 'xdg-open';
+        args = [authURL];
+      }
     }
     const child = open(cmd, args, { detached: true, stdio: 'ignore' });
     child.on('error', () => {

package/src/cli.js

@@ -3,7 +3,9 @@
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import process from 'node:process';
-import { loadConfig, getEffectiveInstance } from './config.js';
+import path from 'node:path';
+import fs from 'node:fs';
+import { loadConfig, getEffectiveInstance, globalConfigDir } from './config.js';
 import { App } from './app.js';
 import { renderHelp } from './help.js';
 import { isMutationCommand } from './mutations.js';
@@ -26,6 +28,8 @@ import { ticketsCmd } from './commands/tickets.js';
 import { versionCmd } from './commands/version.js';
 import { devCmd } from './commands/dev.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 {
@@ -153,19 +157,35 @@ export function buildCLI() {
         if (argv.format) {
           app.output.setFormat(argv.format);
         }
+        // --profile: resolve profile name to its instance URL
+        // --instance wins if both are specified (explicit URL > profile reference)
+        if (argv.profile) {
+          const profile = (cfg.profiles || {})[argv.profile];
+          if (!profile) {
+            process.stderr.write(`Error: Unknown profile "${argv.profile}"\n`);
+            process.exit(1);
+          }
+          const url = profile.instance_url;
+          app._overrideInstance = url;
+          argv._overrideInstance = url;
+          // Temporarily switch active profile so auth picks up the right user
+          cfg.activeProfile = argv.profile;
+        }
         if (argv.instance) {
           app._overrideInstance = argv.instance;
+          argv._overrideInstance = argv.instance;
         }
       },
       // 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
         if (argv.instance) {
           app._overrideInstance = argv.instance;
+          argv._overrideInstance = argv.instance;
         }
         // Determine if this is a mutation
         const subcommand = (argv._[1] || '').toString();
@@ -183,22 +203,49 @@ export function buildCLI() {
 
       const cmd = (argv._[0] || '').toString();
 
+      // 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', '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'].includes(cmd)
+      const skipSkillCheck = ['help', 'version', 'completion', 'skill', 'docs'].includes(cmd)
         || process.env.JSN_NO_SKILL_CHECK === '1'
         || argv['no-skill-check']
-        || argv.json
-        || argv.quiet;
-      if (!skipSkillCheck) {
-        checkSkill().then(result => {
-          if (result && !result.current && result.error) {
-            process.stderr.write(`\n⚠ ${result.error}\n\n`);
+      if (!skipNpmCheck) {
+        const cacheFile = path.join(globalConfigDir(), '.last-npm-check');
+        let shouldCheck = true;
+        try {
+          const mtime = fs.statSync(cacheFile).mtimeMs;
+          const elapsed = Date.now() - mtime;
+          // Only check if >= 24 hours since last check
+          if (elapsed < 86400000) shouldCheck = false;
+        } catch {
+          // File doesn't exist — check
+        }
+
+        if (shouldCheck) {
+          const version = getVersion();
+          checkLatest().then(latest => {
+            if (latest && version !== latest) {
+              process.stderr.write(`\n⚠ jsn ${latest} available (you have ${version}) — run "npm install -g @jacebenson/jsn" to update\n\n`);
+            }
+          }).catch(() => {});
+
+          // Stamp the cache file (write async, don't block)
+          try {
+            fs.mkdirSync(globalConfigDir(), { recursive: true });
+            fs.writeFileSync(cacheFile, String(Date.now()), 'utf-8');
+          } catch {
+            // Non-fatal
           }
-        }).catch(() => {});
+        }
       }
 
       // 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);
       }
     })
@@ -281,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');
+    },
+  };
+}