@cavelang/cli 0.32.3 → 0.34.0

package/src/cli.ts

@@ -9,12 +9,13 @@
  * - `cave highlight [file]` — ANSI syntax colors (async)
  * - `cave add [--db <path>] [file…]` — ingest into a store (`--strict`, `--check`)
  * - `cave query [--db <path>] '<pattern>'` — CAVE-Q (`--json`, `--all`, `--aliases`, `--as-of`, `--resolve`)
+ * - `cave search [--db <path>] <terms..>` — FTS5 full-text search over claims and comments (`--raw`, `--limit`, `--json`)
  * - `cave resolve [--db <path>]` — contested facts under the §26 policy (`--aliases`, `--policy`, `--json`)
  * - `cave derive [--db <path>] [rules.cave…]` — fire rules (`--dry-run`, `--full`, `--list`, `--retract`)
  * - `cave act [--db <path>] <name> [param=value…]` — execute an action (spec §25; `--declare`, `--list`, `--retract`)
  * - `cave automate [--db <path>]` — the event-driven loop (spec §29; async)
  * - `cave check [--db <path>]` — knowledge health report (`--stale`, `--json`)
- * - `cave backup [--db <path>] --out <path>` — exact verified SQLite snapshot
+ * - `cave backup [--db <path>] --out <path>` — exact verified store snapshot
  * - `cave restore <snapshot> --db <path>` — verify and atomically restore a snapshot
  * - `cave generate [--db <path>]` — versioned TypeScript client from EXPECTS declarations
  * - `cave suggest-alias [--db <path>]` — same-entity candidates (spec §27; async)
@@ -38,11 +39,11 @@ import { readFileSync, readSync, statSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { parseArgs } from 'node:util'
 import { Version } from '@cavelang/core'
-import { parseDocument } from '@cavelang/parser'
+import { parseDocument, Token } from '@cavelang/parser'
 import { Registry, standardRegistry } from '@cavelang/canonical'
-import { Sensitivity, backup as backupStore, defaultDbPath, open, restoreBackup, verifyBackup } from '@cavelang/store'
-import type { Store } from '@cavelang/store'
-import { defaultLimit as defaultQueryLimit, page as caveQueryPage } from '@cavelang/query'
+import { LocateError, Sensitivity, backup as backupStore, defaultDbPath, openAt, restoreBackup, verifyBackup } from '@cavelang/store'
+import type { OpenIntent, Store } from '@cavelang/store'
+import { defaultLimit as defaultQueryLimit, maxLimit as maxQueryLimit, page as caveQueryPage } from '@cavelang/query'
 import {
   check as caveCheck, defaultMinScore, defaultStaleDays, gatedIngest, judgePrompt, parseJudgeReply,
   generateClient, suggestAliases, writeSuggestions
@@ -115,13 +116,14 @@ Usage:
   cave add [--db <path>] [file...]         ingest into a store [--strict] [--check] [--no-prelude] [--no-src]
   cave import [--db <path>] [file...]      restore/merge from CAVE text (add without @src: stamping)
   cave query [--db <path>] <pattern>       run a bounded CAVE-Q page [--limit <n>] [--cursor <token>] [--json]
+  cave search [--db <path>] <terms..>      full-text search over claims and comments (FTS5) [--raw] [--limit <n>] [--json]
   cave resolve [--db <path>]               contested facts + winners (spec §26) [--aliases] [--policy] [--json]
   cave derive [--db <path>] [rules.cave..] declare + fire rules (spec §24) [--dry-run] [--full] [--list] [--retract <rule>]
   cave act [--db <path>] <name> [p=v...]   execute an action (spec §25) [--dry-run] [--no-check] [--hooks <file>]
   cave act --declare [file...]             declare actions from a CAVE document; --list / --retract <name> manage them
   cave automate [--db <path>]              event-driven loop (spec §29): new claims fire rules/actions/hooks/agent prompts [--once]
   cave check [--db <path>]                 knowledge health report (spec §20) [--stale <days>] [--json]
-  cave backup [--db <path>] --out <file>   exact verified SQLite snapshot [--force]
+  cave backup [--db <path>] --out <file>   exact verified store snapshot [--force]
   cave restore <snapshot> --db <path>      verify and atomically restore an exact snapshot [--force]
   cave generate [--db <path>]              generate a typed client from EXPECTS [--out <file>] [--version <n>]
   cave suggest-alias [--db <path>]         propose same-entity ALIAS candidates (spec §27) [--min <s>] [--agent] [--write]
@@ -140,10 +142,12 @@ Usage:
   cave help [command]                      this text, or one command's options and examples
 
 Every command answers --help. --db defaults to $CAVE_DB, or cave.db in
-the current directory. The spec lives in the .claude/skills/ directory at
+the current directory, and names a SQLite store or a CAVE text file: text
+replays into an in-memory store for commands that only read (writes refuse
+it), and a read never creates a missing database. The spec lives in the .claude/skills/ directory at
 the repository root (section index in README.md).`
 
-const dbHelp = `--db <path>    database file (default: $CAVE_DB, or cave.db)`
+const dbHelp = `--db <path>    store: a SQLite file, or CAVE text read into memory (default: $CAVE_DB, or cave.db)`
 
 /** Per-command help, printed for \`cave <command> --help\` and \`cave help <command>\`. */
 export const commandHelp: Record<string, string> = {
@@ -278,10 +282,13 @@ Options:
 
 Patterns are claim triples with ?variables and optional metadata filters
 (spec §12). A second positional starting with WHERE filters on conf,
-value or tx.
+value or tx. A binding line carries the matched claim's comment
+(?x = value  ; comment), so evidence written next to a claim travels
+with the answer; fully bound patterns print the raw line, comment included.
 
 Examples:
   cave query '?x USES jwt'
+  cave query --db notes.cave '?x USES jwt'
   cave query --db k.db '?x HAS bug: ?bug #security'
   cave query --db k.db '?cause CAUSE app/crash' 'WHERE conf >= 0.5'
   cave query --db k.db 'terrier EXTENDS+ animal'
@@ -292,6 +299,39 @@ Examples:
   cave query --db k.db 'service HAS owner: ?who' --resolve
   cave query --db k.db '?x ?verb ?y @production' --json`,
 
+  search: `cave search — full-text search over claims and comments (spec §13.2)
+
+Usage:
+  cave search [--db <path>] <terms...> [--raw] [--limit <n>] [--json] [--no-prelude]
+
+Options:
+  ${dbHelp}
+  --raw          treat the terms as FTS5 MATCH syntax: AND / OR / NOT,
+                 NEAR(a b), prefix* and column filters such as
+                 comment:heap or subject:auth
+  --limit <n>    matches to print (default ${defaultQueryLimit}, maximum ${maxQueryLimit})
+  --json         emit a versioned cave.search/v1 JSON object whose matches
+                 are cave.claim/v1 records
+  --no-prelude   open the store without the standard verb registry
+
+Searches the full-text index the store maintains over every claim:
+subject, verb, object, attribute name, value text, comment, and the raw
+line as written (so tags, contexts, and inverse spellings match too).
+Terms are one literal phrase by default — safe for hyphenated names such
+as token-expiry, which raw FTS5 syntax would read as a column filter.
+Tokens split on punctuation, so heap-dump also matches "heap dump" and
+auth/middleware matches auth middleware. Results are newest first, one
+raw line each, comments included; retracted and superseded rows stay
+searchable (spec §9.6), so pair a hit with cave query or cave export
+--current when currency matters.
+
+Examples:
+  cave search 'heap dump'
+  cave search --db k.db token-expiry
+  cave search --db k.db --raw 'comment:heap AND subject:auth'
+  cave search --db k.db --raw 'jwt OR oauth*' --limit 20
+  cave search --db k.db 'rotated weekly' --json`,
+
   resolve: `cave resolve — contested facts and their winners (spec §26)
 
 Usage:
@@ -434,7 +474,7 @@ Examples:
   cave check --db k.db --stale 30
   cave check --db k.db --json | jq '.violations'`,
 
-  backup: `cave backup — exact, verified SQLite snapshot (spec §13.2.2)
+  backup: `cave backup — exact, verified store snapshot (spec §13.2.2)
 
 Usage:
   cave backup [--db <path>] --out <file> [--force]
@@ -456,7 +496,7 @@ Examples:
   cave backup --db k.db --out backups/k.db
   cave backup --verify backups/k.db --sha256 <hex>`,
 
-  restore: `cave restore — verify and atomically restore an exact SQLite snapshot (spec §13.2.2)
+  restore: `cave restore — verify and atomically restore an exact store snapshot (spec §13.2.2)
 
 Usage:
   cave restore <snapshot> --db <path> [--force] [--sha256 <hex>]
@@ -712,7 +752,19 @@ topic → fix over a small in-memory store.`,
   version: `cave version — print the cave version
 
 Usage:
-  cave version`
+  cave version`,
+
+  help: `cave help — the overview, or one command's options and examples
+
+Usage:
+  cave help
+  cave help <command>
+
+Every command answers --help with the same text as cave help <command>.
+
+Examples:
+  cave help query
+  cave help serve`
 }
 
 const readStdin = (): string => {
@@ -733,6 +785,21 @@ const readStdin = (): string => {
   }
 }
 
+/**
+ * Opens the store `--db` names (spec §13.7): a SQLite file, or a CAVE text
+ * file replayed into memory. `read` never creates, migrates, or changes a
+ * file — a missing path is an error, not an empty database; `scratch` is a
+ * dry run that appends inside a rolled-back transaction, so it may write
+ * but creates and migrates nothing; `write` creates a missing SQLite store,
+ * migrates an older one, and refuses text files with the materialization
+ * hint.
+ */
+const openDb = (values: { db?: string, 'no-prelude'?: boolean }, intent: OpenIntent): Store =>
+  openAt(values.db ?? defaultDbPath(), {
+    intent,
+    ...values['no-prelude'] === true ? { registry: Registry.empty } : {}
+  })
+
 const readInput = (files: readonly string[]): string =>
   files.length === 0 || (files.length === 1 && files[0] === '-') ?
     readStdin() :
@@ -816,7 +883,7 @@ const ingestCommand = (name: 'add' | 'import') => (argv: readonly string[]): Out
     allowPositionals: true
   })
   const input = readInput(positionals)
-  const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  const store = openDb(values, 'write')
   try {
     const options = {
       strict: values.strict === true,
@@ -883,7 +950,7 @@ export const queryCommand = (argv: readonly string[]): Output => {
     return fail('cave query: a pattern is required (spec §12.1)\n')
   }
   const pattern = positionals.join('\n')
-  const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  const store = openDb(values, 'read')
   try {
     const limit = values.limit === undefined ? defaultQueryLimit : Number(values.limit)
     const result = caveQueryPage(store, pattern, {
@@ -908,7 +975,14 @@ export const queryCommand = (argv: readonly string[]): Output => {
         .join('  ')
       // A fully bound pattern has no bindings to print; transitive matches
       // additionally carry no row — confirm with the pattern itself.
-      const line = bindings !== '' ? bindings : match.claim?.claim.raw ?? pattern.split('\n')[0]!
+      // Bindings carry the matched claim's comment so the evidence written
+      // next to a claim travels with the answer; raw lines already do. A
+      // multi-line comment (§6.4) opens above the binding line, as it does
+      // above a claim.
+      const comment = match.claim?.claim.comment
+      const line = bindings !== '' ?
+        comment === undefined ? bindings : Token.joinComment(`${bindings} `, comment) :
+        match.claim?.claim.raw ?? pattern.split('\n')[0]!
       // An interpolated trajectory shows its value at the anchor
       // (spec §32.4) — bindings already carry it in the value slot.
       return match.at !== undefined && bindings === '' ?
@@ -923,6 +997,66 @@ export const queryCommand = (argv: readonly string[]): Output => {
   }
 }
 
+export const searchFormat = 'cave.search' as const
+export const searchVersion = 1 as const
+
+/**
+ * `cave search` — the store's FTS5 index (spec §13.2) from the shell:
+ * one literal phrase by default, raw MATCH syntax on request, newest
+ * matches first. Lines print as written, so comments come along.
+ */
+export const searchCommand = (argv: readonly string[]): Output => {
+  const { values, positionals } = parseArgs({
+    args: [...argv],
+    options: {
+      db: { type: 'string' },
+      raw: { type: 'boolean' },
+      limit: { type: 'string' },
+      json: { type: 'boolean' },
+      'no-prelude': { type: 'boolean' }
+    },
+    allowPositionals: true
+  })
+  const query = positionals.join(' ').trim()
+  if (query === '') {
+    return fail('cave search: search terms are required\n')
+  }
+  const limit = values.limit === undefined ? defaultQueryLimit : Number(values.limit)
+  if (!Number.isInteger(limit) || limit < 1 || limit > maxQueryLimit) {
+    return fail(`cave search: --limit must be an integer from 1 to ${maxQueryLimit}\n`)
+  }
+  const store = openDb(values, 'read')
+  try {
+    const raw = values.raw === true
+    const found = store.search(query, { raw, limit: limit + 1 })
+    const matches = found.slice(0, limit)
+    const truncated = found.length > limit
+    if (values.json === true) {
+      return ok(`${JSON.stringify({
+        format: searchFormat,
+        version: searchVersion,
+        query,
+        raw,
+        limit,
+        truncated,
+        matches: matches.map(row => store.recordOf(row))
+      }, undefined, 2)}\n`)
+    }
+    if (matches.length === 0) {
+      return ok('no matches\n')
+    }
+    const lines = matches.map(row => row.raw_line)
+    if (truncated) {
+      lines.push(`more matches beyond ${limit}; raise --limit`)
+    }
+    return ok(`${lines.join('\n')}\n`)
+  } catch (error) {
+    return fail(`${error instanceof Error ? error.message : String(error)}\n`)
+  } finally {
+    store.close()
+  }
+}
+
 /**
  * `cave resolve` — the human view of contradiction resolution (spec §26.4):
  * contested facts with their candidates ranked as the policy sees them,
@@ -941,7 +1075,7 @@ export const resolveCommand = (argv: readonly string[]): Output => {
     allowPositionals: false
   })
   const percent = (value: number): string => `${Math.round(value * 1000) / 10}%`
-  const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  const store = openDb(values, 'read')
   try {
     if (values.policy === true) {
       const policy = store.resolutionPolicy()
@@ -1004,7 +1138,12 @@ export const deriveCommand = (argv: readonly string[]): Output => {
   if (maxPasses !== undefined && (!Number.isInteger(maxPasses) || maxPasses < 1)) {
     return fail(`cave derive: --max-passes expects a positive integer, got ${JSON.stringify(values['max-passes'])}\n`)
   }
-  const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  // The intent follows the branch order below: listing reads, retracting
+  // writes, a dry run appends inside a rolled-back transaction.
+  const store = openDb(values,
+    values.list === true ? 'read' :
+      values.retract !== undefined ? 'write' :
+        values['dry-run'] === true ? 'scratch' : 'write')
   try {
     if (values.list === true) {
       const rules = listRules(store)
@@ -1158,7 +1297,14 @@ export const actCommand = (argv: readonly string[]): Output => {
     },
     allowPositionals: true
   })
-  const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  // The intent follows the branch order below: declaring and retracting
+  // write, listing reads, a dry-run execution appends inside a rolled-back
+  // transaction.
+  const store = openDb(values,
+    values.declare === true ? 'write' :
+      values.list === true ? 'read' :
+        values.retract !== undefined ? 'write' :
+          values['dry-run'] === true ? 'scratch' : 'write')
   try {
     if (values.declare === true) {
       const declaration = declareActions(store, readInput(positionals))
@@ -1279,7 +1425,7 @@ export const checkCommand = (argv: readonly string[]): Output => {
   if (!Number.isFinite(staleDays) || staleDays < 0) {
     return fail(`cave check: --stale expects a non-negative number of days, got ${JSON.stringify(values.stale)}\n`)
   }
-  const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  const store = openDb(values, 'read')
   try {
     const report = caveCheck(store, { staleDays })
     const out = values.json === true ?
@@ -1299,7 +1445,7 @@ const snapshotLine = (
   `${action} exact backup (${snapshot.rows} row(s), schema v${snapshot.schemaVersion}, ` +
   `${snapshot.bytes} bytes, sha256:${snapshot.sha256}) at ${snapshot.path}\n`
 
-/** `cave backup` — create or verify an exact SQLite snapshot (§13.2.2). */
+/** `cave backup` — create or verify an exact store snapshot (§13.2.2). */
 export const backupCommand = (argv: readonly string[]): Output => {
   const { values } = parseArgs({
     args: [...argv],
@@ -1328,7 +1474,15 @@ export const backupCommand = (argv: readonly string[]): Output => {
     if (values.out === undefined) {
       return fail('cave backup: --out <file> is required\n')
     }
-    const store = open(values.db ?? defaultDbPath())
+    const dbPath = values.db ?? defaultDbPath()
+    // A text store is replayed into memory, so the backup API cannot see that
+    // the destination aliases the source: refuse before the file could be
+    // replaced by a SQLite snapshot of itself (a SQLite source is covered by
+    // the API's own check).
+    if (sameFile(dbPath, values.out)) {
+      return fail(`cave backup: --out '${values.out}' is the source database — refusing to overwrite it\n`)
+    }
+    const store = openAt(dbPath, { intent: 'read' })
     try {
       return ok(snapshotLine('created', backupStore(store, values.out, { force: values.force === true })))
     } finally {
@@ -1411,7 +1565,7 @@ export const suggestAliasCommand = async (
     if (timeoutSeconds !== undefined && (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)) {
       return fail(`cave suggest-alias: --timeout must be a positive number of seconds, got '${values.timeout}'\n`)
     }
-    const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+    const store = openDb(values, values.write === true ? 'write' : 'read')
     try {
       let suggestions = suggestAliases(store, { minScore, ...limit === undefined ? {} : { limit } })
       if (values.agent !== undefined && suggestions.length > 0) {
@@ -1468,7 +1622,7 @@ export const syncCommand = (argv: readonly string[]): Output => {
     return fail('cave sync: exactly one source is required — a CAVE store file, ;@-annotated text, or - for stdin (spec §28.5)\n')
   }
   const dbPath = values.db ?? defaultDbPath()
-  const store = open(dbPath, values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  const store = openDb(values, values['dry-run'] === true ? 'scratch' : 'write')
   try {
     const options = {
       into: values.into === undefined ? labelOf(dbPath) : sanitizeLabel(values.into),
@@ -1529,7 +1683,10 @@ export const reportCommand = (argv: readonly string[]): Output => {
   if (maximum === undefined) {
     return fail(`cave report: --max-sensitivity expects ${Sensitivity.levels.join(', ')}, got ${JSON.stringify(values['max-sensitivity'])}\n`)
   }
-  const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  if (values.out !== undefined && sameFile(values.db ?? defaultDbPath(), values.out)) {
+    return fail(`cave report: --out '${values.out}' is the source database — refusing to overwrite it\n`)
+  }
+  const store = openDb(values, 'read')
   try {
     const rendered = caveReport(store, template, {
       aliases: values.aliases === true,
@@ -1597,7 +1754,7 @@ export const exportCommand = (argv: readonly string[]): Output => {
   if (values.out !== undefined && sameFile(db, values.out)) {
     return fail(`cave export: --out '${values.out}' is the source database — refusing to overwrite it\n`)
   }
-  const store = open(db, values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  const store = openDb(values, 'read')
   try {
     const text = store.exportText({ current: values.current === true, tx: values.tx === true, maxSensitivity: maximum })
     if (values.out === undefined) {
@@ -1636,7 +1793,7 @@ export const generateCommand = (argv: readonly string[]): Output => {
   if (values.out !== undefined && sameFile(db, values.out)) {
     return fail(`cave generate: --out '${values.out}' is the source database — refusing to overwrite it\n`)
   }
-  const store = open(db, values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  const store = openDb(values, 'read')
   try {
     const generated = generateClient(store, version === undefined ? {} : { version })
     if (!generated.ok) {
@@ -1701,7 +1858,7 @@ export const reconstructCommand = async (
     if (timeoutSeconds !== undefined && (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)) {
       return fail(`cave reconstruct: --timeout must be a positive number of seconds, got '${values.timeout}'\n`)
     }
-    const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+    const store = openDb(values, 'read')
     try {
       const graph = sqliteStore(store)
       const result = values.agent === undefined ?
@@ -1717,9 +1874,11 @@ export const reconstructCommand = async (
           ),
           positionals
         )
+      // The trace is a documentary comment block: the blank line after it
+      // keeps it off the first claim when the output is added back (§6.4).
       const lines = [
-        ...values.trace === true ?
-          result.trace.map(step => `; ${step.step}. ${step.cue.entity} @ ${step.cue.score.toFixed(2)} +${step.collected} claim(s)`) :
+        ...values.trace === true && result.trace.length > 0 ?
+          [...result.trace.map(step => `; ${step.step}. ${step.cue.entity} @ ${step.cue.score.toFixed(2)} +${step.collected} claim(s)`), ''] :
           [],
         ...result.claims.map(claim => emitClaim(claim))
       ]
@@ -1732,15 +1891,36 @@ export const reconstructCommand = async (
   }
 }
 
-export const demoCommand = (): Output =>
-  ok(`${Demo.run().lines.join('\n')}\n`)
+/**
+ * Positional arguments of a command that declares no options: an unknown
+ * option throws, which the dispatcher reports as an ordinary problem
+ * (status 1).
+ */
+const positionalsOf = (argv: readonly string[]): readonly string[] =>
+  parseArgs({ args: [...argv], options: {}, allowPositionals: true }).positionals
+
+/** The usage error (status 2) for more positionals than a command takes. */
+const surplusPositionals = (command: string, positionals: readonly string[], max: number): Output | undefined =>
+  positionals.length > max ? fail(`cave ${command}: unexpected positional arguments\n`, 2) : undefined
 
-export const versionCommand = (): Output =>
-  ok(`${Version.current()}\n`)
+export const demoCommand = (argv: readonly string[] = []): Output => {
+  const problem = surplusPositionals('demo', positionalsOf(argv), 0)
+  if (problem !== undefined) return problem
+  return ok(`${Demo.run().lines.join('\n')}\n`)
+}
+
+export const versionCommand = (argv: readonly string[] = []): Output => {
+  const problem = surplusPositionals('version', positionalsOf(argv), 0)
+  if (problem !== undefined) return problem
+  return ok(`${Version.current()}\n`)
+}
 
 /** `cave help [command]` — the overview, or one command's help text. */
 export const helpCommand = (argv: readonly string[]): Output => {
-  const [topic] = argv
+  const positionals = positionalsOf(argv)
+  const problem = surplusPositionals('help', positionals, 1)
+  if (problem !== undefined) return problem
+  const [topic] = positionals
   if (topic === undefined) {
     return ok(`${usage}\n`)
   }
@@ -1763,6 +1943,19 @@ export const cave = (argv: readonly string[]): Output => {
       (rest.includes('--help') || rest.includes('-h'))) {
     return ok(`${commandHelp[canonical]}\n`)
   }
+  try {
+    return run(canonical, rest)
+  } catch (error) {
+    // A --db path that is not what the command needs (spec §13.7) is a
+    // usage failure, reported the way dispatch reports thrown errors.
+    if (error instanceof LocateError) {
+      return fail(`cave ${canonical}: ${error.message}\n`)
+    }
+    throw error
+  }
+}
+
+const run = (canonical: undefined | string, rest: readonly string[]): Output => {
   switch (canonical) {
     case 'parse':
       return parseCommand(rest)
@@ -1772,6 +1965,8 @@ export const cave = (argv: readonly string[]): Output => {
       return importCommand(rest)
     case 'query':
       return queryCommand(rest)
+    case 'search':
+      return searchCommand(rest)
     case 'resolve':
       return resolveCommand(rest)
     case 'derive':
@@ -1795,11 +1990,11 @@ export const cave = (argv: readonly string[]): Output => {
     case 'doctor':
       return doctorCommand(rest)
     case 'demo':
-      return demoCommand()
+      return demoCommand(rest)
     case 'version':
     case '--version':
     case '-v':
-      return versionCommand()
+      return versionCommand(rest)
     case 'help':
       return helpCommand(rest)
     case undefined:
@@ -1807,6 +2002,6 @@ export const cave = (argv: readonly string[]): Output => {
     case '-h':
       return ok(`${usage}\n`)
     default:
-      return fail(`cave: unknown command ${JSON.stringify(command)}\n\n${usage}\n`, 2)
+      return fail(`cave: unknown command ${JSON.stringify(canonical)}\n\n${usage}\n`, 2)
   }
 }

package/src/commands.ts

@@ -19,6 +19,7 @@ export const commandRegistry = [
   { name: 'add', importantOptions: ['--strict', '--check', '--no-prelude', '--no-src'] },
   { name: 'import', importantOptions: ['--strict', '--no-prelude'] },
   { name: 'query', importantOptions: ['--json', '--limit', '--cursor', '--all', '--aliases', '--as-of', '--at', '--resolve', '--no-prelude'] },
+  { name: 'search', importantOptions: ['--raw', '--limit', '--json', '--no-prelude'] },
   { name: 'resolve', importantOptions: ['--aliases', '--policy', '--json', '--no-prelude'] },
   { name: 'derive', importantOptions: ['--dry-run', '--full', '--aliases', '--min-conf', '--max-passes', '--list', '--retract', '--json', '--no-prelude'] },
   { name: 'act', importantOptions: ['--declare', '--list', '--retract', '--dry-run', '--no-check', '--aliases', '--hooks', '--json', '--no-prelude'] },

package/src/dispatch.ts

@@ -22,8 +22,10 @@ const processRuntime = (): CommandRuntime => ({
 
 const delegatedHelp = new Set<string>(delegatedCommandNames)
 
+// Exactly `help <delegated command>` becomes `<command> --help`; anything
+// longer stays with `cave help`, which rejects the surplus as a usage error.
 const normalizedArgs = (raw: readonly string[]): readonly string[] =>
-  raw[0] === 'help' && raw[1] !== undefined && delegatedHelp.has(raw[1]) ? [raw[1], '--help'] : raw
+  raw.length === 2 && raw[0] === 'help' && delegatedHelp.has(raw[1]!) ? [raw[1]!, '--help'] : raw
 
 const write = (runtime: CommandRuntime, output: Output): number => {
   if (output.out !== '') runtime.stdout.write(output.out)

package/src/doctor.ts

@@ -249,7 +249,7 @@ const inspectDatabase = (path: string, source: DatabaseConfiguration['source']):
         configuration,
         checks: [check('store.database', 'warn',
           `Database schema ${version} needs migration to schema ${Schema.currentVersion}`,
-          'Back up the database, then open it with a normal cave command to migrate it.')]
+          'Close every user and copy the database file as a rollback point, then open it with a writing command such as cave add to migrate it; reads never migrate.')]
       }
     }
 

package/src/index.ts

@@ -1,10 +1,10 @@
 /**
- * `@cavelang/cli` — the `cave` command (parse / add / query / resolve / derive / act / check / suggest-alias / sync / export / report / reconstruct / demo).
+ * `@cavelang/cli` — the `cave` command (parse / add / query / search / resolve / derive / act / check / suggest-alias / sync / export / report / reconstruct / demo).
  * Programmatic access to the same implementations lives here; `dispatch`
  * and `runCli` expose the shared awaited command lifecycle.
  */
 
-export { actCommand, addCommand, backupCommand, cave, checkCommand, commandHelp, demoCommand, deriveCommand, exportCommand, generateCommand, helpCommand, highlightCommand, importCommand, parseCommand, queryCommand, reconstructCommand, reportCommand, resolveCommand, restoreCommand, suggestAliasCommand, syncCommand, usage, versionCommand } from './cli.ts'
+export { actCommand, addCommand, backupCommand, cave, checkCommand, commandHelp, demoCommand, deriveCommand, exportCommand, generateCommand, helpCommand, highlightCommand, importCommand, parseCommand, queryCommand, reconstructCommand, reportCommand, resolveCommand, restoreCommand, searchCommand, suggestAliasCommand, syncCommand, usage, versionCommand } from './cli.ts'
 export { dispatch, runCli } from './dispatch.ts'
 export type { CommandRuntime } from './dispatch.ts'
 export { commandRegistry } from './commands.ts'