@jacebenson/jsn 4.3.13 → 4.4.0-dev.114.1

package/src/commands/cmdb-search.js

@@ -0,0 +1,38 @@
+import { assertSafeExactMatch, quoteShellArg } from '../helpers.js';
+import { errAPI, errUsage } from '../errors.js';
+
+const FIELDS = ['name', 'fqdn', 'ip_address', 'serial_number'];
+const raw = v => v && typeof v === 'object' ? v.value : v;
+
+export function cmdbSearchCmd(wrap) {
+  return { command: 'search <text>', describe: 'Find CIs by name, FQDN, IP address, or serial number',
+    builder: y => y.positional('text', { type: 'string', describe: 'Literal text; quote multiple words' })
+      .option('class', { type: 'string', describe: 'Exact CI class name (not descendants)' })
+      .option('limit', { type: 'number', default: 20, describe: 'Maximum CIs (1–100)' })
+      .option('offset', { type: 'number', default: 0, describe: 'Starting result offset' }),
+    handler: wrap(async (argv, app) => {
+      if (typeof argv.text !== 'string' || !argv.text.trim()) throw errUsage('Provide nonempty CI search text.');
+      const text = argv.text.trim();
+      assertSafeExactMatch(text);
+      if ([...text].some(c => c.codePointAt(0) < 32 || c.codePointAt(0) === 127) || /javascript:/i.test(text)) throw errUsage('Search text must not contain query scripts or control characters.');
+      if (argv.class !== undefined && !/^[a-z][a-z0-9_]*$/.test(argv.class)) throw errUsage('--class must be an exact CI table name.');
+      if (!Number.isInteger(argv.limit) || argv.limit < 1 || argv.limit > 100) throw errUsage('--limit must be from 1 to 100.');
+      if (!Number.isInteger(argv.offset) || argv.offset < 0) throw errUsage('--offset must be a nonnegative integer.');
+      // Repeat the class restriction in each OR branch: no branch may escape it.
+      const query = FIELDS.map(f => `${f}LIKE${text}${argv.class ? `^sys_class_name=${argv.class}` : ''}`).join('^NQ') + '^ORDERBYname^ORDERBYsys_id';
+      const params = new URLSearchParams({ sysparm_query: query, sysparm_limit: String(argv.limit + 1), sysparm_offset: String(argv.offset),
+        sysparm_fields: 'sys_id,name,sys_class_name,fqdn,ip_address,serial_number', sysparm_display_value: 'all' });
+      const rows = await app.sdk.listStrict('cmdb_ci', params);
+      if (!Array.isArray(rows) || rows.some(r => !r || typeof r !== 'object' || Array.isArray(r))) throw errAPI(200, 'CMDB search returned no valid record list.');
+      const hasMore = rows.length > argv.limit, records = rows.slice(0, argv.limit);
+      const connection = argv.profile ? ` --profile ${quoteShellArg(argv.profile)}` : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : '';
+      const breadcrumbs = records.flatMap(r => /^[a-f0-9]{32}$/i.test(raw(r.sys_id) || '') ? [
+        { action: 'show', cmd: `jsn cmdb show ${raw(r.sys_id)}`, description: String(raw(r.name) || 'Inspect CI') },
+        { action: 'relationships', cmd: `jsn cmdb relationships --ci ${raw(r.sys_id)}`, description: 'Inspect CI dependencies' },
+      ] : []);
+      if (hasMore) breadcrumbs.push({ action: 'next', cmd: `jsn cmdb search ${quoteShellArg(text)} --limit ${argv.limit} --offset ${argv.offset + argv.limit}${argv.class ? ` --class ${argv.class}` : ''}`, description: 'Next matching CIs' });
+      app.ok({ table: 'cmdb_ci', search: text, fields: FIELDS, records, count: records.length,
+        pagination: { limit: argv.limit, offset: argv.offset, has_more: hasMore } },
+      { summary: `${records.length} matching CI(s)`, breadcrumbs: breadcrumbs.map(h => ({ ...h, cmd: h.cmd + connection })) });
+    }) };
+}

package/src/commands/cmdb.js

@@ -15,6 +15,7 @@ import {
   resolveFieldsParam,
 } from '../helpers.js';
 import { errNotFound, errUsage } from '../errors.js';
+import { cmdbSearchCmd } from './cmdb-search.js';
 
 const SYS_ID_RE = /^[0-9a-f]{32}$/i;
 const MAX_DEPTH = 5;
@@ -371,6 +372,7 @@ export function cmdbCmd(wrap) {
     }),
     builder: (yargs) => {
       return yargs
+        .command(cmdbSearchCmd(wrap))
         .command({
           command: 'list',
           describe: 'List CIs from the CMDB (cmdb_ci)',

package/src/commands/columns.js

@@ -1,9 +1,10 @@
+import { fieldBehaviorHelp } from '../field-behavior.js';
 import { buildDevCmd } from './_generic.js';
 
 export const columnsCmd = (wrap) => {
   const base = buildDevCmd('columns', 'sys_dictionary', ['column', 'col'],
     ['element', 'column_label', 'internal_type', 'mandatory', 'max_length', 'active'],
-    wrap, { singular: 'column', scopeValidation: true });
+    wrap, { singular: 'column', scopeValidation: true, help: fieldBehaviorHelp });
 
   // Add --table filter
   const origBuilder = base.builder;

package/src/commands/customizations.js

@@ -4,6 +4,7 @@ import { canUsePicker } from '../helpers.js';
 import { paginatedSearch } from '../paginated-search.js';
 import { captureReport, listReports, getReport, compareReports, formatReport, formatReportList, formatReportComparison } from '../customizations.js';
 import { buildActionableReport, writeCustomizationHtml } from '../customizations-report.js';
+import { customizationGuidance, formatCustomizationGuidance } from '../customization-guidance.js';
 
 // Only capture needs an instance. Saved reports never need network access.
 declareCapabilities('customizations', { noInstance: true, skipDailyChecks: true, mutationSubcommands: [] });
@@ -25,7 +26,7 @@ async function pickReport(app, argv, exclude = null, message = 'Select a customi
 function show(app, report, options = {}) {
   const actionable = buildActionableReport(report);
   const triage = actionable.artifacts.map(({ category, category_label, identity, triage: classification }) => ({ category, category_label, identity, ...classification }));
-  app.ok({ ...report, triage, _formatted: formatReport(report, options) }, { summary: `Customization capture ${report.run_id}: ${report.status}`, breadcrumbs: [listHint, showHint(report.run_id), compareHint(report.run_id)] });
+  app.ok({ ...report, interpretation: customizationGuidance(), triage, _formatted: formatReport(report, options) }, { summary: `Customization capture ${report.run_id}: ${report.status}`, breadcrumbs: [listHint, showHint(report.run_id), compareHint(report.run_id)] });
 }
 export function customizationsCmd(wrap) {
   return {
@@ -36,7 +37,8 @@ export function customizationsCmd(wrap) {
         builder: b => b.option('label', { type: 'string', describe: 'Label for this capture' })
           .option('customer-scope', { type: 'string', array: true, default: [], describe: 'Declared customer-owned scope value or sys_id, repeatable; ownership is not inferred' })
           .option('page-size', { type: 'number', default: 100, describe: 'Records per table page, 1..1000' })
-          .option('max-pages', { type: 'number', default: 10, describe: 'Maximum pages per source, 1..100' }),
+          .option('max-pages', { type: 'number', default: 10, describe: 'Maximum pages per source, 1..100' })
+          .epilogue(`${customizationGuidance().capture}\n${formatCustomizationGuidance()}\nExample: jsn customizations capture --label review --customer-scope x_acme_app --json`),
         handler: wrap(async (argv, app) => {
           app.requireInstance();
           if (!Number.isInteger(argv.pageSize) || argv.pageSize < 1 || argv.pageSize > 1000 || !Number.isInteger(argv.maxPages) || argv.maxPages < 1 || argv.maxPages > 100) throw errUsage('page-size must be 1..1000 and max-pages 1..100');
@@ -55,18 +57,21 @@ export function customizationsCmd(wrap) {
       })
       .command({ command: 'show [run_id]', describe: 'Review a saved capture offline', builder: b => b
         .option('group-by', { type: 'string', choices: ['type', 'scope', 'updated-by'], default: 'type', describe: 'Group summary by file type, scope or last updater' })
-        .option('filter', { type: 'string', describe: 'Expand a group shown in the summary (friendly or table name for file types)' }), handler: wrap(async (argv, app) => {
+        .option('filter', { type: 'string', describe: 'Expand a group shown in the summary (friendly or table name for file types)' })
+        .epilogue(`Offline review: inspect coverage, interpretation and triage in --json output.\n${formatCustomizationGuidance()}\nExample: jsn customizations show <run_id> --get data.triage`), handler: wrap(async (argv, app) => {
         const report = argv.run_id ? requireReport(argv.run_id) : await pickReport(app, argv);
         if (report) show(app, report, { groupBy: argv.groupBy, filter: argv.filter || '' });
       }) })
       .command({ command: 'html [run_id]', describe: 'Write a searchable, self-contained HTML review of a saved capture', builder: b => b
-        .option('out', { type: 'string', describe: 'Output HTML path (must not already exist)' }), handler: wrap(async (argv, app) => {
+        .option('out', { type: 'string', describe: 'Output HTML path (must not already exist)' })
+        .epilogue('Offline review with the same interpretation and coverage as show; writes a local file without changing instance records.\nExample: jsn customizations html <run_id> --out review.html'), handler: wrap(async (argv, app) => {
         const report = argv.run_id ? requireReport(argv.run_id) : await pickReport(app, argv);
         if (!report) return;
         const file = writeCustomizationHtml(report, { out: argv.out });
-        app.ok({ run_id: report.run_id, file, artifacts: Object.values(report.categories).reduce((total, items) => total + items.length, 0) }, { summary: `Wrote offline customization review: ${file}`, breadcrumbs: [listHint, showHint(report.run_id)] });
+        app.ok({ run_id: report.run_id, file, artifacts: Object.values(report.categories).reduce((total, items) => total + items.length, 0), interpretation: customizationGuidance() }, { summary: `Wrote offline customization review: ${file}`, breadcrumbs: [listHint, showHint(report.run_id)] });
       }) })
-      .command({ command: 'compare [baseline] [new]', describe: 'Compare two saved captures from the same instance', handler: wrap(async (argv, app) => {
+      .command({ command: 'compare [baseline] [new]', describe: 'Compare two saved captures from the same instance',
+        builder: b => b.epilogue(`Offline metadata/evidence comparison; inspect both captures' coverage before interpreting changes.\n${formatCustomizationGuidance()}\nExample: jsn customizations compare <baseline_id> <new_id> --json`), handler: wrap(async (argv, app) => {
         if (!!argv.baseline !== !!argv.new) throw errUsage('Compare requires exactly two report IDs');
         if (argv.baseline && argv.baseline === argv.new) throw errUsage('Compare requires two different report IDs');
         const baseline = argv.baseline ? requireReport(argv.baseline) : await pickReport(app, argv, null, 'Select the baseline capture');
@@ -76,7 +81,8 @@ export function customizationsCmd(wrap) {
         if (baseline.instance !== newer.instance) throw errUsage('Customization reports must describe the same instance');
         const result = compareReports(baseline, newer);
         app.ok({ ...result, _formatted: formatReportComparison(result) }, { summary: `Customization comparison: ${result.status}`, breadcrumbs: [listHint, showHint(baseline.run_id), showHint(newer.run_id)] });
-      }) }),
+      }) })
+      .epilogue(`${customizationGuidance().capture}\n${formatCustomizationGuidance()}\nStart: jsn customizations capture --help\nReview: jsn customizations show --help\nCompare: jsn customizations compare --help`),
     handler: wrap(async (_argv, app) => app.ok({ command: 'customizations', subcommands: ['capture', 'list', 'show', 'html', 'compare'] }, { summary: 'Use `jsn customizations <subcommand> --help` for details.' })),
   };
 }

package/src/commands/discover.js

@@ -0,0 +1,54 @@
+import { declareCapabilities } from '../capabilities.js';
+
+declareCapabilities('discover', { noInstance: true, skipDailyChecks: true });
+
+// The live registrations supply names, descriptions, aliases, actions, and
+// factory configuration. No separate inventory of table commands lives here.
+export function discoverCommands(registry, { query = '', table = '' } = {}) {
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+  return registry.commands.filter(command => {
+    const metadata = command.discovery;
+    if (table && metadata?.table !== table) return false;
+    const haystack = [command.name, ...command.aliases, command.description,
+      metadata?.table, ...(metadata?.benefits || []),
+      ...(command.actions || []).map(action => `${action.name} ${action.description}`)].join(' ').toLowerCase();
+    return words.every(word => haystack.includes(word));
+  });
+}
+
+export function discoverCmd(wrap, getRegistry) {
+  return {
+    command: 'discover [query]',
+    describe: 'Find commands by words in their names, aliases, descriptions, or configured table',
+    builder: y => y
+      .positional('query', { type: 'string', describe: 'Search words (quote multiple words)' })
+      .option('table', { type: 'string', describe: 'Find specialized commands configured for this exact table' })
+      .epilogue([
+        'Choose by intent:',
+        '  Cross-table tasks: jsn records list --table task --query "active=true" --json',
+        '  Custom tables: jsn records list --table x_example_record --limit 5 --json',
+        '  Table-specific defaults and views: jsn discover --table incident',
+        '  Rich request views (attachments and variables): jsn requests show --help',
+        '  Raw endpoints when needed: jsn rest --help',
+        'Generic records supports any accessible table; specialized commands provide configured defaults and table-specific behavior.',
+        'Discovery matches registered text; try fewer words if there are no matches.',
+        'Use --json for structured results or --json --get data.commands for only matches.',
+      ].join('\n')),
+    handler: wrap(async (argv, app) => {
+      const commands = discoverCommands(getRegistry(argv), { query: argv.query, table: argv.table });
+      const lines = commands.flatMap(command => [
+        `${command.name}: ${command.description}`,
+        ...(command.discovery ? [
+          `  Table: ${command.discovery.table}; default columns: ${command.discovery.defaultColumns.join(', ')}`,
+          ...command.discovery.benefits.map(benefit => `  ${benefit}`),
+        ] : []),
+        `  ${command.help}`,
+        ...(command.actions || []).map(action => `  ${action.help} — ${action.description}`),
+      ]);
+      if (!commands.length) lines.push('No registered matches. Try fewer words or use generic records for any accessible table: jsn records list --help');
+      app.ok({ commands, _formatted: lines.join('\n') }, {
+        summary: `${commands.length} matching command(s). Use jsn discover --help for guidance by intent.`,
+      });
+    }),
+  };
+}

package/src/commands/docs/db.js

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import Database from 'better-sqlite3';
+import { docsReaderLease } from './locks.js';
 
 const LEGACY_DOCS_DIR_NAME = 'servicenow-cli/docs';
 const DOCS_DIR_NAME = 'docs';
@@ -131,7 +132,14 @@ export function defaultDocsRoots(opts = {}) {
 export function openDocsDb(opts = {}) {
   const dbPath = opts.dbPath || getDocsDbPath();
   ensureDocsCacheDir();
-  const db = new Database(dbPath);
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+  const release = docsReaderLease(dbPath);
+  let db;
+  try {
+    db = new Database(dbPath);
+  } catch (error) { release(); throw error; }
+  const close = db.close.bind(db);
+  db.close = () => { try { return close(); } finally { release(); } };
   try {
     db.exec('PRAGMA journal_mode = WAL');
     return db;

package/src/commands/docs/docs.js

@@ -19,9 +19,24 @@ function formatBytes(n) {
 export function docsCmd(wrap) {
   return {
     command: 'docs [subcommand]',
-    describe: 'Search ServiceNow documentation locally (sync, status, search, serve)',
+    describe: 'Search ServiceNow documentation locally (install, sync, status, search, serve)',
     builder: (yargs) => {
       return yargs
+        .command({ command: 'install', describe: 'Install optional docs: raw GitHub files or a verified prebuilt searchable database',
+          builder: y => y.option('source', { type: 'string', choices: ['snapshot', 'github', 'skip'], describe: 'Explicit source; raw GitHub estimated ~5 minutes; snapshot estimate comes from manifest' })
+            .option('manifest-url', { type: 'string', describe: 'HTTPS snapshot manifest mirror' }),
+          handler: wrap(async (argv, app) => {
+            const { installDocumentation, offerDocumentation } = await import('./install.js');
+            const { canUsePicker } = await import('../../helpers.js');
+            const result = argv.source ? await installDocumentation(argv.source, { manifestURL: argv['manifest-url'] })
+              : canUsePicker(app, argv) ? await offerDocumentation(app, argv) : await installDocumentation(undefined);
+            app.ok(result, { summary: result.skipped ? 'Documentation skipped' : 'Documentation installed' });
+          }),
+        })
+        .command({ command: 'rollback', describe: 'Restore the previously installed local docs database', handler: wrap(async (_argv, app) => {
+          const { rollbackSnapshot } = await import('./snapshot.js');
+          app.ok(rollbackSnapshot(), { summary: 'Previous documentation index restored' });
+        }) })
         .command({
           command: 'sync',
           describe: 'Clone/update ServiceNowDocs and build the docs.db index',
@@ -77,8 +92,14 @@ export function docsCmd(wrap) {
               sock.connect(3000, '127.0.0.1');
             });
 
+            const { docsSnapshotStatus } = await import('./snapshot.js');
+            const snapshot = docsSnapshotStatus();
+            let available = null;
+            try { available = JSON.parse(fs.readFileSync(`${dbPath}.available.json`, 'utf8')); } catch { /* No background update information. */ }
             app.ok({
               state,
+              ...(snapshot ? { snapshot: { revision: snapshot.revision, schema: snapshot.schema } } : {}),
+              ...(snapshot && available?.installed === snapshot.revision && available.revision !== snapshot.revision ? { updateAvailable: { revision: available.revision, command: 'jsn docs install --source snapshot' } } : {}),
               downloaded: { ok: downloaded, path: repoDir },
               db: { ok: dbExists, path: dbPath },
               embedded: { ok: embedded },
@@ -99,6 +120,8 @@ export function docsCmd(wrap) {
             .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 { ensureDocumentation } = await import('./install.js');
+            await ensureDocumentation(app, argv);
             const { searchDocs } = await import('./search.js');
             const result = searchDocs({
               query: argv.query,
@@ -259,7 +282,7 @@ export function docsCmd(wrap) {
     handler: wrap(async (argv, app) => {
       const { getDocsDbPath } = await import('./db.js');
       const subcommands = argv.subcommands || [];
-      const summary = 'jsn docs — ServiceNow documentation search (sync, status, search, show, serve).';
+      const summary = 'jsn docs — optional local documentation (install, sync, status, search, show, serve, rollback).';
       app.ok({
         command: 'docs',
         subcommands,

package/src/commands/docs/ingest.js

@@ -1,18 +1,35 @@
 // Ingest ServiceNow markdown docs into a SQLite database with FTS5 full-text search.
 
 import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { docsReaderLease } from './locks.js';
+import { installDatabase } from './replace.js';
 import { createHash } from 'node:crypto';
 import { parseFrontmatter } from '../../frontmatter.js';
-import { withDocsDb, initDocsSchema, getDocsDbPath, walkDocs, defaultDocsRoots } from './db.js';
+import { withDocsDb, initDocsSchema, getDocsDbPath, walkDocs, defaultDocsRoots, getDocsSourceDir } from './db.js';
 import { encodeText, phasesToBytes, docSurface, DEFAULT_DIM } from './hrr.js';
 
 export function ingestDocs(opts = {}) {
+  const dbPath = opts.dbPath || getDocsDbPath();
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+  const staging = `${dbPath}.${randomUUID()}.building`;
+  const resource = opts.sourceResource || (!opts.roots ? getDocsSourceDir() : null);
+  if (resource) fs.mkdirSync(path.dirname(resource), { recursive: true });
+  const releaseSource = resource && !opts.sourceLeaseHeld ? docsReaderLease(resource) : () => {};
+  try {
+    const result = ingestStagedDocs({ ...opts, dbPath: staging });
+    if (result.errors) throw new Error(`Documentation ingestion failed for ${result.errors} files; existing index retained`);
+    installDatabase(staging, dbPath, { afterInstall: () => fs.rmSync(`${dbPath}.snapshot.json`, { force: true }) });
+    return { ...result, dbPath };
+  } finally { releaseSource(); fs.rmSync(staging, { force: true }); }
+}
+function ingestStagedDocs(opts = {}) {
   const dbPath = opts.dbPath || getDocsDbPath();
   const embed = opts.embed !== false;
   const roots = opts.roots || defaultDocsRoots(opts);
 
-  // Fresh build each run.
-  if (fs.existsSync(dbPath)) fs.rmSync(dbPath);
+  // The caller provides a fresh staging path; never unlink the installed index.
 
   return withDocsDb({ dbPath }, (db) => {
     initDocsSchema(db);

package/src/commands/docs/install.js

@@ -0,0 +1,86 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { docsReaderLease } from './locks.js';
+import { getDocsDbPath, getDocsCacheDir, getDocsSourceDir } from './db.js';
+import { fetchManifest, installSnapshot, snapshotEstimate, validateDatabase, installDatabase, docsSnapshotStatus, DEFAULT_MANIFEST_URL } from './snapshot.js';
+import { canUsePicker } from '../../helpers.js';
+import { errUsageHint } from '../../errors.js';
+
+export async function installDocumentation(source, options = {}) {
+  if (source === 'skip') return { source, skipped: true };
+  if (source === 'snapshot') {
+    const manifestURL = options.manifestURL || DEFAULT_MANIFEST_URL;
+    const manifest = options.manifest || await fetchManifest(manifestURL);
+    process.stderr.write(`Prebuilt searchable database: ${snapshotEstimate(manifest)}.\n`);
+    return installSnapshot({ manifestURL, manifest });
+  }
+  if (source !== 'github') throw errUsageHint('Choose a documentation source.', 'Use jsn docs install --source snapshot|github|skip');
+  process.stderr.write('Raw GitHub source: approximately 51,000 files plus local indexing; estimated 5–25 minutes including semantic indexing (prior runs ~5 minutes; validation full build ~21 minutes; actual time and size vary).\n');
+  fs.mkdirSync(getDocsCacheDir(), { recursive: true });
+  const staging = fs.mkdtempSync(path.join(getDocsCacheDir(), '.github-install-'));
+  try {
+    const { syncDocs } = await import('./sync.js');
+    const { ingestDocs } = await import('./ingest.js');
+    const repoDir = getDocsSourceDir(), dbPath = path.join(staging, 'docs.db');
+    syncDocs({ repoDir, markdownDir: path.join(repoDir, 'markdown'), noIngest: true, embed: false });
+    const releaseSource = docsReaderLease(repoDir);
+    let result;
+    try { result = ingestDocs({ dbPath, roots: [{ dir: path.join(repoDir, 'markdown'), prefix: '' }], embed: true }); }
+    finally { releaseSource(); }
+    if (result.errors) throw new Error('Raw documentation indexing failed; existing index retained');
+    validateDatabase(dbPath);
+    installDatabase(dbPath, getDocsDbPath(), { afterInstall: () => fs.rmSync(`${getDocsDbPath()}.snapshot.json`, { force: true }) });
+    return { source, documents: result.count, dbPath: getDocsDbPath() };
+  } finally { fs.rmSync(staging, { recursive: true, force: true }); }
+}
+export async function chooseDocumentationSource() {
+  const { select } = await import('../../prompts.js');
+  return select({ message: 'Install optional offline documentation?', choices: [
+    { name: 'Skip for now (first search will explain installation)', value: 'skip' },
+    { name: 'Prebuilt searchable database from jsn.jace.pro (size and estimate before approval)', value: 'snapshot' },
+    { name: 'GitHub raw source + local indexing (~51,000 files; estimated 5–25 minutes)', value: 'github' },
+  ] });
+}
+export async function offerDocumentation(_app, _argv = {}) {
+  let source = await chooseDocumentationSource();
+  let approvedManifest;
+  if (source === 'snapshot') {
+    try {
+      const manifest = await fetchManifest(DEFAULT_MANIFEST_URL, { fetchFn: (url, options) => fetch(url, { ...options, signal: AbortSignal.timeout(5000) }) });
+      approvedManifest = manifest;
+      const { confirm } = await import('../../prompts.js');
+      if (!await confirm({ message: `Download prebuilt searchable database: ${snapshotEstimate(manifest)}?`, default: false })) source = 'skip';
+    } catch {
+      throw errUsageHint('Prebuilt documentation is unavailable; nothing downloaded.', 'Choose GitHub raw source with jsn docs install --source github, or retry the snapshot later.');
+    }
+  }
+  return installDocumentation(source, { manifest: approvedManifest });
+}
+export async function ensureDocumentation(app, argv) {
+  if (fs.existsSync(getDocsDbPath())) { scheduleFreshnessCheck(); return; }
+  if (!canUsePicker(app, argv)) throw errUsageHint('No local documentation index. Documentation installation is optional and requires a source choice.',
+    'Run jsn docs install --source snapshot for a verified prebuilt database, or --source github for raw files + local indexing (estimated 5–25 minutes). Use --source skip to defer.');
+  const result = await offerDocumentation(app, argv);
+  if (result.skipped) throw errUsageHint('Documentation installation skipped.', 'Run jsn docs install --source snapshot|github when ready.');
+}
+export function scheduleFreshnessCheck() {
+  if (process.env.JSN_NO_DOCS_CHECK === '1') return;
+  const receipt = docsSnapshotStatus();
+  if (!receipt) return;
+  try {
+    const stamp = `${getDocsDbPath()}.check-stamp`;
+    try {
+      if (Date.now() - fs.statSync(stamp).mtimeMs < 86400000) return;
+      fs.rmSync(stamp);
+    } catch (error) { if (error.code !== 'ENOENT') return; }
+    fs.writeFileSync(stamp, '', { flag: 'wx' });
+    // A separate bounded worker prevents network from delaying local search.
+    const child = spawn(process.execPath, [fileURLToPath(new URL('./snapshot-check.js', import.meta.url)), getDocsDbPath()], {
+      detached: true, stdio: 'ignore', windowsHide: true,
+    });
+    child.on('error', () => {});
+    child.unref();
+  } catch { /* Local search remains available offline. */ }
+}

package/src/commands/docs/locks.js

@@ -0,0 +1,34 @@
+// Coordinate atomic snapshot replacement with short-lived local search readers.
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code !== 'ESRCH'; }
+}
+function clearStale(filename) {
+  try {
+    const pid = Number(fs.readFileSync(filename, 'utf8'));
+    if (pid > 0 && alive(pid)) return false;
+    if (!(pid > 0) && Date.now() - fs.statSync(filename).mtimeMs < 120000) return false;
+    fs.rmSync(filename, { force: true });
+    return true;
+  } catch (error) { if (error.code === 'ENOENT') return true; throw error; }
+}
+export function docsReaderLease(dbPath) {
+  const lock = `${dbPath}.install-lock`;
+  if (!clearStale(lock)) throw new Error('Docs snapshot installation is in progress; retry shortly');
+  const lease = `${dbPath}.reader-${process.pid}-${randomUUID()}`;
+  fs.writeFileSync(lease, String(process.pid), { flag: 'wx', mode: 0o600 });
+  if (fs.existsSync(lock)) { fs.rmSync(lease, { force: true }); throw new Error('Docs snapshot installation is in progress; retry shortly'); }
+  return () => fs.rmSync(lease, { force: true });
+}
+export function docsInstallLease(dbPath) {
+  const lock = `${dbPath}.install-lock`;
+  clearStale(lock);
+  fs.writeFileSync(lock, String(process.pid), { flag: 'wx', mode: 0o600 });
+  return () => fs.rmSync(lock, { force: true });
+}
+export function docsHaveReaders(dbPath) {
+  return fs.readdirSync(path.dirname(dbPath)).filter(name => name.startsWith(path.basename(dbPath) + '.reader-'))
+    .some(name => !clearStale(path.join(path.dirname(dbPath), name)));
+}

package/src/commands/docs/refresh.js

@@ -2,20 +2,36 @@
 // after a ServiceNow docs update (e.g. `git pull` in the docs repo).
 
 import fs from 'node:fs';
+import path from 'node:path';
+import { docsReaderLease } from './locks.js';
+import { errUsageHint } from '../../errors.js';
 import { createHash } from 'node:crypto';
 import { parseFrontmatter } from '../../frontmatter.js';
-import { withDocsDb, getDocsDbPath, walkDocs, defaultDocsRoots } from './db.js';
+import { withDocsDb, getDocsDbPath, walkDocs, defaultDocsRoots, getDocsSourceDir } from './db.js';
 import { encodeText, phasesToBytes, docSurface, DEFAULT_DIM } from './hrr.js';
 
 export function refreshDocs(opts = {}) {
+  const resource = opts.sourceResource || (!opts.roots ? getDocsSourceDir() : null);
+  if (resource) fs.mkdirSync(path.dirname(resource), { recursive: true });
+  const release = resource && !opts.sourceLeaseHeld ? docsReaderLease(resource) : () => {};
+  try { return refreshDocsLocked(opts); } finally { release(); }
+}
+function refreshDocsLocked(opts = {}) {
   const dbPath = opts.dbPath || getDocsDbPath();
   const roots = opts.roots || defaultDocsRoots(opts);
 
+  if (roots.some(root => (!root.prefix || opts.roots) && (!fs.existsSync(root.dir) || !fs.statSync(root.dir).isDirectory()))) {
+    throw errUsageHint('Raw documentation source is missing; existing index retained.', 'Use jsn docs install --source snapshot to update a prebuilt index, or --source github to install raw source before refreshing.');
+  }
+
   if (!fs.existsSync(dbPath)) {
     throw new Error(`Database not found: ${dbPath}. Run "jsn docs sync" first for the initial build.`);
   }
 
   return withDocsDb({ dbPath }, (db) => {
+    if (!opts.sourceLeaseHeld && db.prepare("SELECT value FROM meta WHERE key='snapshot_revision'").get()) {
+      throw errUsageHint('A prebuilt snapshot cannot refresh from an unrelated raw clone; existing index retained.', 'Use jsn docs install --source snapshot, or jsn docs sync to explicitly update raw source and rebuild.');
+    }
     db.exec('PRAGMA journal_mode = WAL');
 
     const cols = db.prepare('PRAGMA table_info(docs)').all().map((c) => c.name);
@@ -48,9 +64,11 @@ export function refreshDocs(opts = {}) {
     const seen = new Set();
     const started = Date.now();
 
+    const missingPrefixes = roots.filter(root => root.prefix && !fs.existsSync(root.dir)).map(root => root.prefix);
     const files = [...walkDocs(roots)];
 
     db.exec('BEGIN');
+    db.prepare("DELETE FROM meta WHERE key='snapshot_revision'").run();
     for (const { file, rel } of files) {
       try {
         seen.add(rel);
@@ -105,7 +123,7 @@ export function refreshDocs(opts = {}) {
     }
 
     for (const [rel, row] of existing) {
-      if (!seen.has(rel)) {
+      if (!missingPrefixes.some(prefix => rel.startsWith(prefix)) && !seen.has(rel)) {
         del.run(row.id);
         removed++;
       }
@@ -116,6 +134,8 @@ export function refreshDocs(opts = {}) {
     db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
     db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES('synced_at', ?)").run(String(Date.now()));
 
+    fs.rmSync(`${dbPath}.snapshot.json`, { force: true });
+    fs.rmSync(`${dbPath}.available.json`, { force: true });
     const secs = ((Date.now() - started) / 1000).toFixed(1);
     return { added, updated, removed, unchanged, errors, secs, dbPath, embeddingsEnabled };
   });

package/src/commands/docs/replace.js

@@ -0,0 +1,30 @@
+import fs from 'node:fs';
+import Database from 'better-sqlite3';
+import { docsInstallLease, docsHaveReaders } from './locks.js';
+import { errUsageHint } from '../../errors.js';
+
+export function installDatabase(staged, dbPath, { afterInstall = () => {} } = {}) {
+  let release;
+  try {
+    release = docsInstallLease(dbPath);
+    // Refuse active databases rather than detach a WAL from its live database.
+    if (docsHaveReaders(dbPath)) throw errUsageHint('Docs index is in use; existing index retained.', 'Close other jsn docs commands and retry installation.');
+    if (['-wal', '-shm'].some(suffix => fs.existsSync(dbPath + suffix))) {
+      // Recover an interrupted reader/writer through SQLite, never by unlinking WAL.
+      const previous = new Database(dbPath, { fileMustExist: true });
+      try {
+        previous.pragma('busy_timeout = 2000');
+        const [checkpoint] = previous.pragma('wal_checkpoint(TRUNCATE)');
+        if (checkpoint.busy || previous.pragma('journal_mode = DELETE', { simple: true }) !== 'delete') {
+          throw errUsageHint('Docs index is in use; existing index retained.', 'Close other jsn docs commands and retry installation.');
+        }
+      } finally { previous.close(); }
+    }
+    if (fs.existsSync(dbPath)) fs.copyFileSync(dbPath, `${dbPath}.previous`);
+    fs.renameSync(staged, dbPath);
+    fs.rmSync(`${dbPath}.available.json`, { force: true });
+    afterInstall();
+  } finally {
+    release?.();
+  }
+}

package/src/commands/docs/snapshot-check.js

@@ -0,0 +1,11 @@
+// Detached read-only freshness worker. Never replaces the installed index.
+import fs from 'node:fs';
+import { fetchManifest } from './snapshot.js';
+const dbPath = process.argv[2];
+try {
+  const receipt = JSON.parse(fs.readFileSync(`${dbPath}.snapshot.json`, 'utf8'));
+  const manifest = await fetchManifest(receipt.manifestURL, { fetchFn: (url, options) => fetch(url, { ...options, signal: AbortSignal.timeout(5000) }) });
+  const filename = `${dbPath}.available.json`;
+  fs.writeFileSync(`${filename}.${process.pid}.tmp`, JSON.stringify({ revision: manifest.revision, installed: receipt.revision, checkedAt: Date.now() }));
+  fs.renameSync(`${filename}.${process.pid}.tmp`, filename);
+} catch { /* Offline and interrupted freshness checks leave the local index intact. */ }