@cavelang/cli 0.32.3 → 0.34.0

package/dist/src/cli.d.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,7 +39,7 @@ export type Output = {
     readonly out: string;
     readonly err: string;
 };
-export declare const usage = "cave \u2014 Compressed Atomic Verb Expressions\n\nUsage:\n  cave parse [file...] [--json]            lint CAVE text (stdin when no file)\n  cave highlight [file...]                 print CAVE text with ANSI syntax colors\n  cave add [--db <path>] [file...]         ingest into a store [--strict] [--check] [--no-prelude] [--no-src]\n  cave import [--db <path>] [file...]      restore/merge from CAVE text (add without @src: stamping)\n  cave query [--db <path>] <pattern>       run a bounded CAVE-Q page [--limit <n>] [--cursor <token>] [--json]\n  cave resolve [--db <path>]               contested facts + winners (spec \u00A726) [--aliases] [--policy] [--json]\n  cave derive [--db <path>] [rules.cave..] declare + fire rules (spec \u00A724) [--dry-run] [--full] [--list] [--retract <rule>]\n  cave act [--db <path>] <name> [p=v...]   execute an action (spec \u00A725) [--dry-run] [--no-check] [--hooks <file>]\n  cave act --declare [file...]             declare actions from a CAVE document; --list / --retract <name> manage them\n  cave automate [--db <path>]              event-driven loop (spec \u00A729): new claims fire rules/actions/hooks/agent prompts [--once]\n  cave check [--db <path>]                 knowledge health report (spec \u00A720) [--stale <days>] [--json]\n  cave backup [--db <path>] --out <file>   exact verified SQLite snapshot [--force]\n  cave restore <snapshot> --db <path>      verify and atomically restore an exact snapshot [--force]\n  cave generate [--db <path>]              generate a typed client from EXPECTS [--out <file>] [--version <n>]\n  cave suggest-alias [--db <path>]         propose same-entity ALIAS candidates (spec \u00A727) [--min <s>] [--agent] [--write]\n  cave sync [--db <path>] <source>         merge another store by row identity (spec \u00A728) [--dry-run] [--as] [--into]\n  cave export [--db <path>] [--out <file>] emit filtered canonical CAVE text [--max-sensitivity <level>]\n  cave serve [--db <path>]                 browse a filtered store (spec \u00A730) [--max-sensitivity <level>]\n  cave report [--db <path>] [template...]  render filtered cited markdown (spec \u00A731) [--max-sensitivity <level>]\n  cave mcp [--db <path>]                   serve the engine as an MCP server on stdio [--no-prelude]\n  cave ingest [--db <path>] <globs/urls..> LLM-driven ingestion of files and web pages\n  cave eval <suite..> --agent '<command>'  golden-fixture extraction/query/reconstruction evals\n  cave connect <source> --map <file>       deterministic structured ingestion (CSV/JSON/SQLite/URL, spec \u00A723)\n  cave reconstruct [--db <path>] <seed..>  reconstruct memory from seed cues (spec \u00A718) [--agent] [--query] [--trace]\n  cave doctor [--db <path>]                diagnose runtime, installation, and store health [--hooks <file>] [--json]\n  cave demo                                run the cave-loop reconstruction demo\n  cave version                             print the cave version\n  cave help [command]                      this text, or one command's options and examples\n\nEvery command answers --help. --db defaults to $CAVE_DB, or cave.db in\nthe current directory. The spec lives in the .claude/skills/ directory at\nthe repository root (section index in README.md).";
+export declare const usage = "cave \u2014 Compressed Atomic Verb Expressions\n\nUsage:\n  cave parse [file...] [--json]            lint CAVE text (stdin when no file)\n  cave highlight [file...]                 print CAVE text with ANSI syntax colors\n  cave add [--db <path>] [file...]         ingest into a store [--strict] [--check] [--no-prelude] [--no-src]\n  cave import [--db <path>] [file...]      restore/merge from CAVE text (add without @src: stamping)\n  cave query [--db <path>] <pattern>       run a bounded CAVE-Q page [--limit <n>] [--cursor <token>] [--json]\n  cave search [--db <path>] <terms..>      full-text search over claims and comments (FTS5) [--raw] [--limit <n>] [--json]\n  cave resolve [--db <path>]               contested facts + winners (spec \u00A726) [--aliases] [--policy] [--json]\n  cave derive [--db <path>] [rules.cave..] declare + fire rules (spec \u00A724) [--dry-run] [--full] [--list] [--retract <rule>]\n  cave act [--db <path>] <name> [p=v...]   execute an action (spec \u00A725) [--dry-run] [--no-check] [--hooks <file>]\n  cave act --declare [file...]             declare actions from a CAVE document; --list / --retract <name> manage them\n  cave automate [--db <path>]              event-driven loop (spec \u00A729): new claims fire rules/actions/hooks/agent prompts [--once]\n  cave check [--db <path>]                 knowledge health report (spec \u00A720) [--stale <days>] [--json]\n  cave backup [--db <path>] --out <file>   exact verified store snapshot [--force]\n  cave restore <snapshot> --db <path>      verify and atomically restore an exact snapshot [--force]\n  cave generate [--db <path>]              generate a typed client from EXPECTS [--out <file>] [--version <n>]\n  cave suggest-alias [--db <path>]         propose same-entity ALIAS candidates (spec \u00A727) [--min <s>] [--agent] [--write]\n  cave sync [--db <path>] <source>         merge another store by row identity (spec \u00A728) [--dry-run] [--as] [--into]\n  cave export [--db <path>] [--out <file>] emit filtered canonical CAVE text [--max-sensitivity <level>]\n  cave serve [--db <path>]                 browse a filtered store (spec \u00A730) [--max-sensitivity <level>]\n  cave report [--db <path>] [template...]  render filtered cited markdown (spec \u00A731) [--max-sensitivity <level>]\n  cave mcp [--db <path>]                   serve the engine as an MCP server on stdio [--no-prelude]\n  cave ingest [--db <path>] <globs/urls..> LLM-driven ingestion of files and web pages\n  cave eval <suite..> --agent '<command>'  golden-fixture extraction/query/reconstruction evals\n  cave connect <source> --map <file>       deterministic structured ingestion (CSV/JSON/SQLite/URL, spec \u00A723)\n  cave reconstruct [--db <path>] <seed..>  reconstruct memory from seed cues (spec \u00A718) [--agent] [--query] [--trace]\n  cave doctor [--db <path>]                diagnose runtime, installation, and store health [--hooks <file>] [--json]\n  cave demo                                run the cave-loop reconstruction demo\n  cave version                             print the cave version\n  cave help [command]                      this text, or one command's options and examples\n\nEvery command answers --help. --db defaults to $CAVE_DB, or cave.db in\nthe current directory, and names a SQLite store or a CAVE text file: text\nreplays into an in-memory store for commands that only read (writes refuse\nit), and a read never creates a missing database. The spec lives in the .claude/skills/ directory at\nthe repository root (section index in README.md).";
 /** Per-command help, printed for \`cave <command> --help\` and \`cave help <command>\`. */
 export declare const commandHelp: Record<string, string>;
 export declare const parseCommand: (argv: readonly string[]) => Output;
@@ -62,6 +63,14 @@ export declare const addCommand: (argv: readonly string[]) => Output;
  */
 export declare const importCommand: (argv: readonly string[]) => Output;
 export declare const queryCommand: (argv: readonly string[]) => Output;
+export declare const searchFormat: "cave.search";
+export declare const searchVersion: 1;
+/**
+ * `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 declare const searchCommand: (argv: readonly string[]) => Output;
 /**
  * `cave resolve` — the human view of contradiction resolution (spec §26.4):
  * contested facts with their candidates ranked as the policy sees them,
@@ -71,7 +80,7 @@ export declare const resolveCommand: (argv: readonly string[]) => Output;
 export declare const deriveCommand: (argv: readonly string[]) => Output;
 export declare const actCommand: (argv: readonly string[]) => Output;
 export declare const checkCommand: (argv: readonly string[]) => Output;
-/** `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 declare const backupCommand: (argv: readonly string[]) => Output;
 /** `cave restore` — verify and atomically restore an exact snapshot (§13.2.2). */
 export declare const restoreCommand: (argv: readonly string[]) => Output;
@@ -109,8 +118,8 @@ export declare const generateCommand: (argv: readonly string[]) => Output;
 export declare const reconstructCommand: (argv: readonly string[], runtime?: {
     readonly signal?: AbortSignal;
 }) => Promise<Output>;
-export declare const demoCommand: () => Output;
-export declare const versionCommand: () => Output;
+export declare const demoCommand: (argv?: readonly string[]) => Output;
+export declare const versionCommand: (argv?: readonly string[]) => Output;
 /** `cave help [command]` — the overview, or one command's help text. */
 export declare const helpCommand: (argv: readonly string[]) => Output;
 /** Dispatches one invocation. */

package/dist/src/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AA8BH,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB,CAAA;AAyCD,eAAO,MAAM,KAAK,+rGAkCgC,CAAA;AAIlD,2FAA2F;AAC3F,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAujB9C,CAAA;AAyBD,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAyBtD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAU,MAAM,SAAS,MAAM,EAAE,KAAG,OAAO,CAAC,MAAM,CAM9E,CAAA;AAuED,eAAO,MAAM,UAAU,SA1CkC,SAAS,MAAM,EAAE,KAAG,MA0C/B,CAAA;AAE9C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,SAxD+B,SAAS,MAAM,EAAE,KAAG,MAwDzB,CAAA;AAEpD,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MA2DtD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MA+CxD,CAAA;AAED,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAsHvD,CAAA;AA8CD,eAAO,MAAM,UAAU,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAsFpD,CAAA;AAqCD,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MA0BtD,CAAA;AASD,2EAA2E;AAC3E,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAqCvD,CAAA;AAED,kFAAkF;AAClF,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MA2BxD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC9B,MAAM,SAAS,MAAM,EAAE,EACvB,UAAS;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,KAC9C,OAAO,CAAC,MAAM,CAgEhB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAmDrD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MA+CvD,CAAA;AAoBD,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAsCvD,CAAA;AAED,2EAA2E;AAC3E,eAAO,MAAM,eAAe,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAoCzD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC7B,MAAM,SAAS,MAAM,EAAE,EACvB,UAAS;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,KAC9C,OAAO,CAAC,MAAM,CAmEhB,CAAA;AAED,eAAO,MAAM,WAAW,QAAO,MACS,CAAA;AAExC,eAAO,MAAM,cAAc,QAAO,MACJ,CAAA;AAE9B,wEAAwE;AACxE,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAcrD,CAAA;AAED,iCAAiC;AACjC,eAAO,MAAM,IAAI,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAqD9C,CAAA"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/src/cli.js

@@ -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)
@@ -37,10 +38,10 @@ 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 { defaultLimit as defaultQueryLimit, page as caveQueryPage } from '@cavelang/query';
+import { LocateError, Sensitivity, backup as backupStore, defaultDbPath, openAt, restoreBackup, verifyBackup } 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 } from '@cavelang/cli/shape';
 import { declareRules, defaultMaxPasses, defaultMinConf, derive, listRules, retractRule } from '@cavelang/cli/rules';
 import { act, declareActions, listActions, retractAction } from '@cavelang/cli/act';
@@ -88,13 +89,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]
@@ -113,9 +115,11 @@ 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 = {
     doctor: `cave doctor — diagnose runtime, installation, and store health
@@ -244,10 +248,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'
@@ -257,6 +264,38 @@ Examples:
   cave query --db k.db 'alice WORKS-AT ?org' --at 2021
   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:
@@ -395,7 +434,7 @@ Examples:
   cave check --db k.db
   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]
@@ -416,7 +455,7 @@ the restore verification token.
 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>]
@@ -664,7 +703,18 @@ 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 = () => {
     const chunks = [];
@@ -686,6 +736,19 @@ const readStdin = () => {
         }
     }
 };
+/**
+ * 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, intent) => openAt(values.db ?? defaultDbPath(), {
+    intent,
+    ...values['no-prelude'] === true ? { registry: Registry.empty } : {}
+});
 const readInput = (files) => files.length === 0 || (files.length === 1 && files[0] === '-') ?
     readStdin() :
     files.map(file => readFileSync(file, 'utf8')).join('\n');
@@ -762,7 +825,7 @@ const ingestCommand = (name) => (argv) => {
         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,
@@ -828,7 +891,7 @@ export const queryCommand = (argv) => {
         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, {
@@ -853,7 +916,14 @@ export const queryCommand = (argv) => {
                 .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 === '' ?
@@ -869,6 +939,66 @@ export const queryCommand = (argv) => {
         store.close();
     }
 };
+export const searchFormat = 'cave.search';
+export const searchVersion = 1;
+/**
+ * `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) => {
+    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,
@@ -887,7 +1017,7 @@ export const resolveCommand = (argv) => {
         allowPositionals: false
     });
     const percent = (value) => `${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();
@@ -949,7 +1079,11 @@ export const deriveCommand = (argv) => {
     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);
@@ -1103,7 +1237,13 @@ export const actCommand = (argv) => {
         },
         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));
@@ -1221,7 +1361,7 @@ export const checkCommand = (argv) => {
     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 ?
@@ -1236,7 +1376,7 @@ export const checkCommand = (argv) => {
 };
 const snapshotLine = (action, snapshot) => `${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) => {
     const { values } = parseArgs({
         args: [...argv],
@@ -1265,7 +1405,15 @@ export const backupCommand = (argv) => {
         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 })));
         }
@@ -1346,7 +1494,7 @@ export const suggestAliasCommand = async (argv, runtime = {}) => {
         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) {
@@ -1402,7 +1550,7 @@ export const syncCommand = (argv) => {
         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),
@@ -1464,7 +1612,10 @@ export const reportCommand = (argv) => {
     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,
@@ -1533,7 +1684,7 @@ export const exportCommand = (argv) => {
     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) {
@@ -1573,7 +1724,7 @@ export const generateCommand = (argv) => {
     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) {
@@ -1636,7 +1787,7 @@ export const reconstructCommand = async (argv, runtime = {}) => {
         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 ?
@@ -1645,9 +1796,11 @@ export const reconstructCommand = async (argv, runtime = {}) => {
                     ...timeoutSeconds === undefined ? {} : { timeoutSeconds },
                     ...runtime.signal === undefined ? {} : { signal: runtime.signal }
                 }), { ...values.query === undefined ? {} : { query: values.query }, ...budgets }), 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))
             ];
@@ -1661,11 +1814,33 @@ export const reconstructCommand = async (argv, runtime = {}) => {
         return fail(`${error instanceof Error ? error.message : String(error)}\n`);
     }
 };
-export const demoCommand = () => ok(`${Demo.run().lines.join('\n')}\n`);
-export const versionCommand = () => ok(`${Version.current()}\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) => parseArgs({ args: [...argv], options: {}, allowPositionals: true }).positionals;
+/** The usage error (status 2) for more positionals than a command takes. */
+const surplusPositionals = (command, positionals, max) => positionals.length > max ? fail(`cave ${command}: unexpected positional arguments\n`, 2) : undefined;
+export const demoCommand = (argv = []) => {
+    const problem = surplusPositionals('demo', positionalsOf(argv), 0);
+    if (problem !== undefined)
+        return problem;
+    return ok(`${Demo.run().lines.join('\n')}\n`);
+};
+export const versionCommand = (argv = []) => {
+    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) => {
-    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`);
     }
@@ -1687,6 +1862,19 @@ export const cave = (argv) => {
         (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, rest) => {
     switch (canonical) {
         case 'parse':
             return parseCommand(rest);
@@ -1696,6 +1884,8 @@ export const cave = (argv) => {
             return importCommand(rest);
         case 'query':
             return queryCommand(rest);
+        case 'search':
+            return searchCommand(rest);
         case 'resolve':
             return resolveCommand(rest);
         case 'derive':
@@ -1719,11 +1909,11 @@ export const cave = (argv) => {
         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:
@@ -1731,7 +1921,7 @@ export const cave = (argv) => {
         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);
     }
 };
 //# sourceMappingURL=cli.js.map