@dikolab/kbdb 0.4.3 → 0.6.0

package/docs/goals/cli.md

@@ -1,2654 +0,0 @@
-# CLI -- The kbdb Command
-
-*A globally installed command that manages knowledge
-base entries in CLI mode and serves as an MCP server
-for AI agents in MCP mode.*
-
-## Goal
-
-The `kbdb` executable is a Deno or Node.js command
-that operates in two run modes:
-
-1. **CLI mode** (default) -- Short-lived commands for
-   content management and search.
-2. **MCP mode** (`kbdb mcp`) -- Long-lived MCP server
-   for AI agent integration.
-
-The run mode is determined by the first argument. If
-the first argument is `mcp`, the executable starts in
-MCP mode (see [MCP](mcp.md)). Otherwise, it runs in
-CLI mode.
-
-In CLI mode, the executable is a thin pass-through.
-It parses command-line arguments, creates a worker
-client (see [Worker Client](worker-client.md)),
-delegates all computation to the daemon, prints
-results to stdout, and prints errors to stderr. The
-CLI does not perform keyword extraction, indexing,
-ranking, or database I/O itself -- the daemon and its
-WASM modules handle all of it.
-
-## Installation
-
-- **Node.js**: `npm install -g @dikolab/kbdb`
-- **Deno**: `deno install` or `deno add @dikolab/kbdb`
-  (via [jsr.io](https://jsr.io))
-
-After installation, the `kbdb` command is available
-globally in the user's shell.
-
-## Synopsis
-
-```
-kbdb [options]
-kbdb <command> [options] ...[parameters]
-kbdb <command> <subcommand> [options] ...[parameters]
-```
-
-All commands and their canonical forms:
-
-```
-kbdb --help | -h
-kbdb --version
-kbdb -v <command>          (verbose: warnings)
-kbdb -vv <command>         (verbose: info)
-kbdb -vvv <command>        (verbose: debug)
-kbdb learn [options] <path | ->...
-kbdb unlearn [options] <kbid>...
-kbdb search [options] <query>...
-kbdb recall [options] <kbid>...
-kbdb content [options] <id>...
-kbdb mcp [options]
-kbdb check [options]
-kbdb gc [options]
-kbdb rebuild [options]
-kbdb status [options]
-kbdb export [options] [<path>]
-kbdb worker stop [options]
-kbdb worker restart [options]
-kbdb db init [options]
-kbdb db migrate [options]
-kbdb skill learn [options] --name <n> --body <file|->
-kbdb skill list [options]
-kbdb skill get [options] <name-or-kbid>
-kbdb skill delete [options] <kbid>
-kbdb agent create [options] --name <n>
-   --persona <file|-> --skills <kbid,...>
-kbdb agent list [options]
-kbdb agent get [options] <docid>
-kbdb agent delete [options] <docid>
-```
-
-The help manual shows `[options]` immediately after
-the command or subcommand to emphasise the canonical
-form. The parser accepts options at any position in
-the command line.
-
-## Run Modes
-
-The `kbdb` executable inspects its first argument to
-determine the run mode:
-
-```
-kbdb mcp [--db <path>]       -> MCP server mode
-kbdb <command> [options]      -> CLI mode (default)
-```
-
-### CLI Mode
-
-All commands except `mcp` run in CLI mode. The
-executable parses arguments, delegates to the worker
-daemon via the worker client module, prints results,
-and exits. Each invocation is a short-lived process.
-
-### MCP Mode
-
-When the first argument is `mcp`, the executable
-starts as a long-lived MCP server. It communicates
-with the AI agent host over stdio using JSON-RPC 2.0,
-and delegates all operations to the worker daemon via
-the same worker client module.
-
-MCP mode accepts `--db <path>` or the `KBDB_DB_DIR`
-environment variable. When neither is set, it falls
-back to the current working directory.
-
-See [MCP](mcp.md) for the full MCP mode
-specification.
-
-## Global Options
-
-These options apply to all commands.
-
-| Option             | Short | Description              |
-|--------------------|-------|--------------------------|
-| `--help`           | `-h`  | Print help text and exit |
-| `--version`        |       | Print version and exit   |
-| `--verbose`        | `-v`  | Set log level to WARNING (errors + warnings) |
-| `--verbose-info`   | `-vv` | Set log level to INFO    |
-| `--verbose-debug`  | `-vvv`| Set log level to DEBUG (all messages) |
-| `--db <path>`      |       | Database directory path (optional) |
-| `--format <fmt>`   | `-f`  | Output format (json default; text when stdout is a TTY) |
-| `--timeout-ms <ms>`|       | Request timeout in ms    |
-| `--retry <n>`      |       | Max retries on timeout   |
-| `--non-interactive` |       | Suppress prompts; use defaults |
-
-### `--help`, `-h`
-
-Print the help text and exit immediately. No database
-connection is made.
-
-```
-kbdb --help
-kbdb -h
-```
-
-When no command is given (`kbdb` with no arguments),
-the help text is printed as the default behaviour.
-
-### `--version`
-
-Print the package version string and exit. No database
-connection is made.
-
-```
-kbdb --version
-```
-
-### `--verbose`, `-v` / `-vv` / `-vvv`
-
-Increase log verbosity on stderr. Each additional `v`
-raises the level by one step.
-
-```
-kbdb -v <command>    # WARNING: errors + warnings
-kbdb -vv <command>   # INFO: errors, warnings, info
-kbdb -vvv <command>  # DEBUG: all messages
-```
-
-The default level is ERROR. The `KBDB_LOG_LEVEL`
-environment variable sets the base level; CLI flags
-override it. Log lines are prefixed with per-level
-icons (✖⚠ℹ▸) and ANSI colors.
-
-### `--db <path>`
-
-Set the path to the directory that contains (or will
-contain) the `.kbdb` database folder. The database
-directory is always `${path}/.kbdb`.
-
-```
-kbdb search "query" --db /path/to/project
-```
-
-When omitted:
-- **CLI mode**: falls back to the `KBDB_DB_DIR`
-  environment variable when `--db` is omitted,
-  then to the current working directory
-  (`process.cwd()`).
-- **MCP mode**: falls back to the `KBDB_DB_DIR`
-  environment variable, then to the current
-  working directory.
-
-## Commands
-
-### `learn` -- import documents
-
-```
-kbdb learn [options] <path | ->...
-```
-
-Import and index documents into the knowledge base.
-
-**Arguments:**
-- `<path | ->...` -- one or more file paths, directory
-  paths, or `-` for stdin. When a path is a directory,
-  it is scanned recursively for supported **text**
-  files only (`.md`, `.txt`, `.rst`, `.adoc`). Dotfiles
-  and dot-directories are skipped at every level.
-  Unsupported extensions are silently skipped. Multiple
-  paths can be specified. When a path is `-`, content
-  is read from stdin until EOF and ingested as a text
-  section. The `-` argument can appear alongside
-  file/directory paths. Stdin is consumed once -- if
-  `-` appears multiple times, only the first reads
-  stdin. Subsequent `-` arguments are silently ignored.
-
-**Options:**
-- `--title <title>` -- Section title. Optional for all
-  section types. Applies to all sections ingested in
-  this invocation.
-- `--description <desc>` -- Section description.
-  Optional for all section types. Applies to all
-  sections ingested in this invocation.
-- `--docid <docid>` -- Attach imported section(s)
-  to this document ID. If the document does not
-  exist, it is created. Applies to all sections
-  ingested in this invocation.
-- `--tags <t,...>` -- Comma-separated tags for scoping
-  and filtering. Applies to all sections ingested in
-  this invocation. Example: `--tags auth,api,v2`.
-- `--replace` -- Enable supersession. When set, the
-  system matches each incoming section by source key
-  (source path + heading). If an existing section has
-  the same source key, it is superseded: the old
-  section's document references are transferred to the
-  new one and the old section becomes eligible for GC.
-  Without this flag, re-learning edited content creates
-  a sibling rather than replacing the original.
-
-**Supported file extensions:**
-
-| Extension | Directory Scan |
-|-----------|----------------|
-| `.md`     | yes            |
-| `.txt`    | yes            |
-| `.rst`    | yes            |
-| `.adoc`   | yes            |
-
-Extensions are defined in
-`src/shared/cli/constants/defaults.constant.ts` as
-`SUPPORTED_EXTENSIONS`. Unsupported extensions are
-silently skipped. Image files are not supported.
-
-**Behaviour:**
-
-The `learn` command collects files from each argument:
-
-1. **Directory path** -- Recursive scan picks up
-   supported text files (`.md`, `.txt`, `.rst`,
-   `.adoc`). Dotfiles and dot-directories are skipped
-   at every level.
-2. **Text file path** -- Reads the file as UTF-8. If
-   the extension is not in `SUPPORTED_EXTENSIONS`, the
-   file is silently skipped.
-3. **Stdin (`-`)** -- Reads text content from stdin
-   until EOF. Stdin is consumed only once regardless of
-   how many `-` arguments appear.
-
-Each collected file is ingested by calling
-`client.addSection()`. The `docid`, `title`, and
-`description` options from the CLI apply to all
-sections in the same invocation.
-
-**Output:**
-- **stdout**: JSON array of `LearnResult` objects:
-  ```json
-  [
-     {
-        "kbid": "abcdef1234567890abcdef1234",
-        "path": "/absolute/path/to/file.md",
-        "size": 1234,
-        "skipped": false,
-        "superseded": null,
-        "warnings": [],
-        "near_duplicates": []
-     }
-  ]
-  ```
-  For stdin input, `path` is `"-"`. The `size` field
-  is the UTF-8 character count of the content. The
-  `skipped` field is always `false` for results that
-  appear in the array -- files that are skipped produce
-  no entry. `superseded` is the kbid of the section
-  that was replaced via `--replace` (null when no
-  supersession occurred). `warnings` is an array of
-  warning strings (e.g. `"heading_missing"` when no
-  title is provided). `near_duplicates` lists sections
-  with similarity >= 0.85 as `{kbid, similarity}`.
-- **stderr**: errors only.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runLearn(client, options, io?)
-            -> client.addSection({
-                 sectionType, content,
-                 title?, description?, docid? })
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> query-parser.wasm (tokenize)
-                           -> fs-database.wasm (store + index)
-```
-
-### `unlearn` -- remove sections
-
-```
-kbdb unlearn [options] <kbid>...
-```
-
-Remove knowledge base sections by their kb-id.
-
-**Arguments:**
-- `<kbid>...` -- one or more 26-character kb-id
-  strings (or unique prefixes -- kbdb resolves
-  short prefixes to full identifiers, similar to
-  git short hashes). Each is processed
-  independently.
-
-**Behaviour:**
-- The engine removes the referenced content and
-  cascades the deletion to associated index entries
-  and ranking data.
-- If a kb-id does not exist, the result shows
-  `"removed": false` rather than throwing an error.
-
-**Output:**
-- **stdout**: JSON array of `UnlearnResult` objects:
-  ```json
-  [
-     {
-        "kbid": "abcdef1234567890abcdef1234",
-        "removed": true
-     }
-  ]
-  ```
-- **stderr**: errors only.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runUnlearn(client, options)
-            -> client.removeSection(kbid)
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm
-                                (delete + re-index)
-```
-
-### `search` -- query the knowledge base
-
-```
-kbdb search [options] <query>...
-```
-
-Search the knowledge base by keywords or phrases.
-
-**Arguments:**
-- `<query>...` -- one or more query terms. All terms
-  are joined with spaces into a single query string.
-  Returns an empty result set if no terms are given.
-
-**Search options:**
-
-| Option           | Short | Default    | Description        |
-|------------------|-------|------------|--------------------|
-| `--mode <mode>`  | `-m`  | `sections` | Result granularity |
-| `--limit <n>`    | `-l`  | `20`       | Max results        |
-| `--offset <n>`   | `-o`  | `0`        | Result offset      |
-| `--format <fmt>` | `-f`  | `json`     | Output format      |
-| `--content`      | `-c`  |            | Hydrate previews   |
-| `--algo <algo>`  |       | `lexical`  | Search algorithm   |
-| `--db <path>`    |       | cwd        | Database directory |
-
-#### `--mode`, `-m`
-
-Controls the granularity of search results.
-
-| Mode        | Description                          |
-|-------------|--------------------------------------|
-| `sections`  | Individual matching sections (default). |
-| `documents` | Complete documents containing matches. |
-| `stats`     | Index statistics and result counts.  |
-
-```
-kbdb search "machine learning" --mode documents
-kbdb search "API endpoint" -m stats
-```
-
-#### `--limit`, `-l`
-
-Maximum number of results to return. Must be a
-positive integer. Non-numeric values fall back to the
-default (20).
-
-```
-kbdb search "query" --limit 50
-kbdb search "query" -l 5
-```
-
-#### `--offset`, `-o`
-
-Zero-based offset into the ranked result set. Used
-for pagination alongside `--limit`. Must be a
-non-negative integer. Non-numeric values fall back
-to the default (0).
-
-```
-kbdb search "query" --offset 20
-kbdb search "query" -o 40 -l 20
-```
-
-#### `--format`, `-f`
-
-Controls the output format printed to stdout.
-
-| Format | Description                             |
-|--------|-----------------------------------------|
-| `json` | Pretty-printed JSON array (default when stdout is piped). |
-| `text` | Numbered human-readable list with scores and matched terms (default when stdout is a TTY). |
-| `mcp`  | JSON envelope for MCP protocol consumers. |
-
-```
-kbdb search "query" --format text
-kbdb search "query" -f mcp
-```
-
-#### `--content`, `-c`
-
-When specified, hydrates each result's `preview` field
-with the actual section content fetched from the
-worker daemon via `client.content()`. Without this
-flag, `preview` is an empty string.
-
-```
-kbdb search "query" --content
-kbdb search "query" -c
-```
-
-Failures to fetch content for individual results are
-suppressed -- the result is still returned with an
-empty `preview`.
-
-**Output shape:**
-
-All search output is formatted from a `SearchDisplay[]`
-array (see [SearchDisplay type](#searchdisplay-type)).
-
-`--format json` (default):
-```json
-{
-   "items": [
-      {
-         "kbid": "abcdef1234567890abcdef1234",
-         "heading": "Machine Learning Basics",
-         "type": "text/markdown",
-         "docids": ["doc-intro-ml"],
-         "score": 8.7432,
-         "confidence": 1.0,
-         "snippet": "Machine learning is a subfield...",
-         "matched_terms": ["machine", "learning"],
-         "matched_fields": ["heading", "body"],
-         "created_at": "2026-06-15T10:00:00Z",
-         "preview": ""
-      }
-   ],
-   "total": 42,
-   "offset": 0,
-   "limit": 20,
-   "has_more": true,
-   "relaxed": false
-}
-```
-
-When `--content` is used, `preview` contains the
-section text:
-```json
-{
-   "items": [
-      {
-         "kbid": "abcdef1234567890abcdef1234",
-         "heading": "Machine Learning Basics",
-         "type": "text/markdown",
-         "docids": ["doc-intro-ml"],
-         "score": 8.7432,
-         "confidence": 1.0,
-         "snippet": "Machine learning is a subfield...",
-         "matched_terms": ["machine", "learning"],
-         "matched_fields": ["heading", "body"],
-         "created_at": "2026-06-15T10:00:00Z",
-         "preview": "Machine learning is a subfield..."
-      }
-   ],
-   "total": 42,
-   "offset": 0,
-   "limit": 20,
-   "has_more": true,
-   "relaxed": false
-}
-```
-
-`--format text`:
-```
-1. [abcdef1234567890abcdef1234] (score: 8.7432)
-   Machine Learning Basics [text/markdown]
-   Machine learning is a subfield...
-   matches: machine, learning
-
-2. [fedcba9876543210fedcba9876] (score: 6.1200)
-   Neural Networks [text/markdown]
-   Neural networks are computing systems...
-   matches: machine
-
-Showing 1-20 of 42 results
-```
-
-When `--content` is also used, each entry includes
-the preview text between the kbid line and the
-matches line.
-
-`--format mcp`:
-```json
-{
-   "type": "text",
-   "text": "[abcdef...] score=8.7432 — ..."
-}
-```
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runSearch(client, options)
-            -> client.search({
-                    query, mode, limit, offset })
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> query-parser.wasm
-                                (parse query)
-                           -> fs-database.wasm
-                                (index lookup)
-                           -> query-parser.wasm
-                                (rank results)
-       -> hydrateSearchPreviews(client, results)
-            (only when options.content === true)
-       -> formatOutput(results, options.format)
-  -> stdout
-```
-
-### `content` -- compose rendered document
-
-```
-kbdb content [options] <id>...
-```
-
-Compose a rendered Markdown document from one or
-more knowledge base identifiers and output it to
-stdout.
-
-**Arguments:**
-- `<id>...` -- one or more kbid or docid identifiers
-  (or unique prefixes -- kbdb resolves short
-  prefixes to full identifiers, similar to git
-  short hashes).
-
-**Output:**
-- **stdout**: JSON envelope containing the composed
-  Markdown text:
-  ```json
-  {
-     "type": "text/markdown",
-     "data": "# Rendered Markdown\n\nContent here...",
-     "total": 42
-  }
-  ```
-- **stderr**: errors only.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runContent(client, options)
-            -> client.content(ids)
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm (fetch)
-```
-
-See [Content Composer](content-composer.md) for the
-full composition specification.
-
-### `recall` -- progressive context retrieval
-
-```
-kbdb recall [options] <kbid>...
-```
-
-Retrieve full content and progressive context for one
-or more sections by kbid. Use after `search` to drill
-into relevant results. Returns section text, metadata,
-references, and back-references at configurable
-expansion depths.
-
-**Arguments:**
-- `<kbid>...` -- one or more 26-character kb-id
-  strings (or unique prefixes -- kbdb resolves
-  short prefixes to full identifiers, similar to
-  git short hashes).
-
-**Options:**
-
-| Flag            | Alias | Description                    |
-|-----------------|-------|--------------------------------|
-| `--depth <n>`   | `-d`  | Expansion depth (0--3,         |
-|                 |       | default: 0, clamped to 3)      |
-| `--db <path>`   |       | Database directory path        |
-
-**Expansion levels:**
-
-| Depth | Returns                               |
-|-------|---------------------------------------|
-| 0     | Full section content with heading,    |
-|       | type, and docids.                     |
-| 1     | Depth-0 content, plus parent document |
-|       | manifests (title, all section kbids   |
-|       | with headings and types) for each     |
-|       | docid, plus back-references (sections |
-|       | that reference this section, from the |
-|       | reference graph index, each with      |
-|       | marker_type and context_snippet).     |
-| 2     | Depth-1 content, plus full text of    |
-|       | sibling sections (other sections in   |
-|       | the same documents), plus forward     |
-|       | references from the section's own     |
-|       | content markers.                      |
-| 3     | Depth-2 content, plus full text of    |
-|       | referenced sections (one level deep), |
-|       | plus their back-references.           |
-
-Depth values above 3 are clamped to 3.
-
-**Output:**
-- **stdout**: JSON `RecallResult` object (single kbid)
-  or `RecallResult[]` array (multiple kbids).
-
-Single result shape (depth 0):
-
-```json
-{
-   "kbid": "a1b2c3d4e5f6g7h8j9k0l1m2n3",
-   "heading": "Architecture Overview",
-   "type": "text/markdown",
-   "content": "Full section text...",
-   "docids": ["doc-5678"]
-}
-```
-
-Single result shape (depth 1+):
-
-```json
-{
-   "kbid": "a1b2c3d4e5f6g7h8j9k0l1m2n3",
-   "heading": "Architecture Overview",
-   "type": "text/markdown",
-   "content": "Full section text...",
-   "docids": ["doc-5678"],
-   "documents": [
-      {
-         "docid": "doc-5678",
-         "title": "System Architecture",
-         "sections": [
-            {
-               "kbid": "...",
-               "heading": "...",
-               "type": "..."
-            }
-         ]
-      }
-   ],
-   "back_references": [
-      {
-         "kbid": "ref-section-kbid",
-         "heading": "Related Section",
-         "type": "text/markdown",
-         "marker_type": "link",
-         "context_snippet": "For details, see ...",
-         "direction": "back"
-      }
-   ],
-   "siblings": [ ... ],
-   "references": [ ... ]
-}
-```
-
-Fields beyond `content` and `docids` are present only
-at the corresponding depth level. At depth 0,
-`documents`, `back_references`, `siblings`, and
-`references` are absent. At depth 1, `siblings` and
-`references` are absent. And so on.
-
-- **stderr**: errors only.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runRecall(client, options)
-            -> client.recall({ kbids, depth })
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm (fetch)
-```
-
-### `mcp` -- start MCP server
-
-```
-kbdb mcp [options]
-```
-
-Start a long-lived MCP server on stdio.
-
-**Behaviour:**
-- Communicates with the AI agent host over stdio
-  using JSON-RPC 2.0.
-- Accepts `--db <path>` or the `KBDB_DB_DIR`
-  environment variable. Falls back to the current
-  working directory when neither is set.
-- Runs a version gate before starting: exits with an
-  error if the database needs migration or is too new.
-- The MCP server does not prompt, does not print
-  banners, and does not write to stdout except for
-  JSON-RPC responses.
-- Runs until the host closes the stdio stream or sends
-  a shutdown signal.
-
-**Environment variables:**
-- `KBDB_DB_DIR` -- fallback database directory path
-  when `--db` is not specified.
-
-**Exit code:** `0` on clean shutdown, `1` on error.
-
-See [MCP](mcp.md) for the full specification of
-tools, resources, and protocol details.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb(rawDbPath)
-  -> createWorkerClient({ contextPath: dbDir })
-  -> versionGate(client, dbDir)
-  -> deps.startMcpServer(dbDir)
-       (stdio JSON-RPC 2.0 loop)
-```
-
-### CLI vs MCP tool coverage
-
-The MCP server exposes `retrieve` (section/document
-lookup by ID) and `status` (database metadata) tools
-that have no CLI equivalents. These are programmatic
-operations suited to MCP clients (AI agents). CLI
-users use `kbdb search` to find content,
-`kbdb recall` to expand context progressively, and
-`kbdb content` to compose documents by ID.
-
-### `check` -- integrity check
-
-```
-kbdb check [options]
-```
-
-Verify the integrity of the database. Checks section
-file checksums, document manifest references, type
-consistency, and divergent content (sections sharing
-the same source key with different content).
-
-**Output:**
-- **stdout**: JSON integrity report:
-  ```json
-  {
-     "ok": false,
-     "errors": [
-        {
-           "type": "orphan_section",
-           "entity": "x9y8z7w6v5u4t3s2r1q0p9o8n7",
-           "detail": "Section not referenced by any document"
-        }
-     ]
-  }
-  ```
-  When all checks pass, `ok` is `true` and `errors`
-  is empty.
-- **stderr**: errors only.
-
-**Exit code:** `0` when `ok` is `true`, `1` when
-errors are found or the command itself fails.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runCheck(client, options)
-            -> client.integrityCheck()
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm
-  -> stdout
-```
-
-See [Database -- Integrity and
-Maintenance](database.md) for the full list of
-checks and error types.
-
-### `gc` -- garbage collection
-
-```
-kbdb gc [options]
-```
-
-Remove unreferenced sections from the database.
-A section is eligible for removal when no document
-manifest references it (empty `docids` array).
-
-**Output:**
-- **stdout**: JSON report:
-  ```json
-  {
-     "removed_sections": 3,
-     "removed_bytes": 15360,
-     "stale_sources": 1
-  }
-  ```
-  When no sections are eligible, `removed_sections`
-  is `0` and `removed_bytes` is `0`.
-  `stale_sources` reports sections whose
-  `source_path` file no longer contains their heading
-  text (advisory, not automatically removed).
-- **stderr**: errors only.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runGc(client, options)
-            -> client.gc()
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm
-  -> stdout
-```
-
-### `rebuild` -- rebuild indexes
-
-```
-kbdb rebuild [options]
-```
-
-Reconstruct all index files from section files and
-document manifests on disk.
-
-**Output:**
-- **stdout**: JSON report:
-  ```json
-  {
-     "sections_reindexed": 39,
-     "terms_indexed": 1500
-  }
-  ```
-- **stderr**: errors only.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runRebuild(client, options)
-            -> client.rebuildIndexes()
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> query-parser.wasm (tokenize)
-                           -> fs-database.wasm
-                                (store indexes)
-  -> stdout
-```
-
-### `export` -- snapshot database
-
-```
-kbdb export [options] [<path>]
-```
-
-Export the database as a self-contained directory
-snapshot for backup, transfer, or version control.
-The export includes sections, documents, and the
-catalog. Indexes are excluded -- they are derived
-data and can be rebuilt with `kbdb rebuild` after
-importing.
-
-**Arguments:**
-- `<path>` -- Output directory path. Defaults to
-  `./kbdb-export/` in the current working directory.
-  If the directory exists, it is overwritten.
-
-**Options:**
-- `--db <path>` -- Source database directory.
-
-**Output:**
-- **stdout**: JSON report:
-  ```json
-  {
-     "path": "/absolute/path/kbdb-export",
-     "sections_exported": 42,
-     "documents_exported": 5
-  }
-  ```
-- **stderr**: errors only.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runExport(client, options)
-            -> client.export({ path })
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm
-  -> stdout
-```
-
-### `kbdb worker` -- daemon lifecycle
-
-The `worker` command group manages the background
-worker daemon process.
-
-#### `worker stop` -- stop the daemon
-
-```
-kbdb worker stop [options]
-```
-
-Stop the running worker daemon for the current
-database. If no daemon is running, prints a message
-and exits successfully.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> dispatchCommand(client, options)
-       -> runWorkerStop(client, options)
-            -> sends shutdown signal via IPC
-```
-
-#### `worker restart` -- restart the daemon
-
-```
-kbdb worker restart [options]
-```
-
-Stop and restart the worker daemon. Equivalent to
-`worker stop` followed by the next command
-auto-spawning a new daemon.
-
-**Exit code:** `0` on success, `1` on error.
-
-### `kbdb db` -- database management
-
-The `db` command group manages the `.kbdb` database
-directory lifecycle. It replaces the deprecated
-`--init` and `--migrate` flags with a consistent
-`kbdb db <subcommand>` pattern.
-
-#### `db init` -- initialise database
-
-```
-kbdb db init [options]
-```
-
-Create a blank `.kbdb` database directory at the
-target path. This is an explicit initialisation
-command -- it does not silently create directories.
-
-`db init` sets `options.command = 'db-init'` and is
-handled before the data-command path (no daemon
-required).
-
-**Options:**
-
-| Option        | Description                              |
-|---------------|------------------------------------------|
-| `--db <path>` | Path to create `.kbdb` in. Defaults to cwd. |
-
-**Behaviour:**
-- Resolves target path from `--db` or `process.cwd()`.
-- Creates the `.kbdb` directory scaffold directly on
-  disk (no daemon required): `catalog.toml`,
-  `corpus.bin`, `inverted.idx`, `positional.idx`,
-  `sections/`, `documents/`, `worker.toml`,
-  `.gitignore`.
-- The database is stamped with `DB_FORMAT_VERSION = 1`.
-- If `.kbdb` already exists: prints error to stderr,
-  exits non-zero.
-- Implemented by `runDbInit()` in
-  `src/shared/cli/functions/run-db-init.function.ts`.
-
-**Output:**
-- **stdout**: JSON object on success:
-  ```json
-  { "path": "/absolute/path/.kbdb", "created": true }
-  ```
-- **stderr**: error message on failure.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> dispatchCommand(options)
-       -> runDbInit(options)
-            -> createScaffold(dbDir)
-                 (writes files directly to disk)
-```
-
-**Examples:**
-```sh
-# Initialise in the current directory
-kbdb db init
-
-# Initialise in a specific directory
-kbdb db init --db /path/to/project
-```
-
-#### `db migrate` -- migrate database
-
-```
-kbdb db migrate [options]
-```
-
-Run sequential migration scripts to upgrade a `.kbdb`
-database directory from an older format version to the
-current version.
-
-`db migrate` sets `options.command = 'db-migrate'`.
-
-**Options:**
-
-| Option        | Description                              |
-|---------------|------------------------------------------|
-| `--db <path>` | Path containing `.kbdb`. Defaults to cwd. |
-
-**Behaviour:**
-- Resolves target path from `--db` or `process.cwd()`.
-- Requires an existing `.kbdb` directory. Returns an
-  error if none is found.
-- Calls `client.checkVersion(dbDir)` to read the
-  catalog version:
-  - `needs_migration` (DB version < WASM version):
-    calls `client.migrateDatabase(dbDir)`, prints the
-    JSON `MigrateResult`, exits 0.
-  - `ok` (DB version == WASM version): prints
-    "already up to date", exits 0.
-  - `too_new` (DB version > WASM version): prints
-    error to stderr, exits 1.
-
-**Output:**
-- **stdout**: `MigrateResult` JSON on success, or
-  "already up to date" when already current.
-- **stderr**: error message on failure.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> dispatchCommand(client, options)
-       -> runDbMigrate(client, options)
-            -> client.checkVersion(dbDir)
-            -> client.migrateDatabase(dbDir)
-                 -> IPC -> worker daemon
-                      -> fs-migration.wasm
-                           (db_migrate -> migration chain)
-```
-
-**Examples:**
-```sh
-# Migrate the database in the current directory
-kbdb db migrate
-
-# Migrate a database at a specific path
-kbdb db migrate --db /path/to/project
-```
-
-### `--init` -- initialise database (deprecated)
-
-> **Deprecated.** Use `kbdb db init` instead.
-> `kbdb --init` still works but emits a deprecation
-> warning to stderr:
-> `warning: --init is deprecated, use "kbdb db init"`
-
-```
-kbdb --init [--db <path>]
-```
-
-Create a blank `.kbdb` database directory at the
-target path. This is an explicit initialisation
-command -- it does not silently create directories.
-
-`--init` sets `options.command = 'init'` and is
-handled before the data-command path.
-
-**Behaviour:**
-- Resolves target path from `--db` or `process.cwd()`.
-- Creates the `.kbdb` directory scaffold directly on
-  disk (no daemon required): `catalog.toml`,
-  `corpus.bin`, `inverted.idx`, `positional.idx`,
-  `sections/`, `documents/`, `worker.toml`,
-  `.gitignore`.
-- The database is stamped with `DB_FORMAT_VERSION = 1`.
-- If `.kbdb` already exists: prints error to stderr,
-  exits non-zero.
-- Implemented by `runDbInit()` in
-  `src/shared/cli/functions/run-db-init.function.ts`.
-
-**Output:**
-- **stdout**: the absolute path to the created `.kbdb`
-  directory on success.
-- **stderr**: error message on failure.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> handleInit(options, deps)
-       -> deps.runDbInit(options)
-            -> createScaffold(dbDir)
-                 (writes files directly to disk)
-```
-
-### `--migrate` -- migrate database (deprecated)
-
-> **Deprecated.** Use `kbdb db migrate` instead.
-> `kbdb --migrate` still works but emits a
-> deprecation warning to stderr:
-> `warning: --migrate is deprecated, use "kbdb db migrate"`
-
-```
-kbdb --migrate [--db <path>]
-```
-
-Run sequential migration scripts to upgrade a `.kbdb`
-database directory from an older format version to the
-current version.
-
-`--migrate` sets `options.command = 'migrate'` and is
-handled before the data-command path.
-
-**Behaviour:**
-- Resolves target path from `--db` or
-  `process.cwd()`.
-- Requires an existing `.kbdb` directory. Returns an
-  error if none is found.
-- Calls `client.checkVersion(dbDir)` to read the
-  catalog version:
-  - `needs_migration` (DB version < WASM version):
-    calls `client.migrateDatabase(dbDir)`, prints the
-    JSON result, exits 0.
-  - `ok` (DB version == WASM version): prints
-    "already up to date", exits 0.
-  - `too_new` (DB version > WASM version): prints
-    error to stderr, exits 1.
-
-**Output:**
-- **stdout**: migration result JSON on success, or
-  "already up to date" string when already current.
-- **stderr**: error message on failure.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> handleMigrate(options, deps)
-       -> deps.findDb(options.dbPath)
-       -> deps.createWorkerClient({ contextPath })
-       -> client.checkVersion(dbDir)
-       -> client.migrateDatabase(dbDir)
-            -> IPC -> worker daemon
-                 -> fs-migration.wasm
-                      (db_migrate -> migration chain)
-```
-
-### `kbdb skill` -- skill management
-
-The `skill` command group manages reusable AI agent
-skill definitions stored as sections with
-`sectionType: 'skill'`. See [Skills](skills.md) for
-the full skill specification.
-
-#### `skill learn` -- create a skill
-
-```
-kbdb skill learn [options] --name <n> --body <file|->
-```
-
-Read a skill body from a file or stdin, extract
-`{{argName}}` placeholders, and store the skill as
-an indexed section.
-
-`skill learn` sets `options.command = 'skill-learn'`.
-
-**Options:**
-
-| Option              | Required | Description                       |
-|---------------------|----------|-----------------------------------|
-| `--name <n>`        | yes      | Skill name (kebab-case)           |
-| `--description <d>` | no       | Human-readable skill description  |
-| `--body <file\|->`  | yes      | Template body file path or stdin  |
-| `--db <path>`       | no       | Path to `.kbdb` directory         |
-
-**Behaviour:**
-- Reads the body text from the file path given to
-  `--body`, or from stdin when `--body` is `-`.
-- Scans the body for `{{argName}}` placeholders and
-  auto-detects the argument list.
-- Constructs the skill JSON and calls
-  `client.addSection()` with `sectionType: 'skill'`.
-- The skill `name` is used as the section `title`
-  (2.0x index weight), `description` as the section
-  description.
-
-**Output:**
-- **stdout**: JSON object on success:
-  ```json
-  {
-     "kbid": "abcdef1234567890abcdef1234",
-     "name": "summarize-document",
-     "arguments": ["docid", "max_points"]
-  }
-  ```
-- **stderr**: errors only.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runSkillLearn(client, options)
-            -> client.addSection({
-                 sectionType: 'skill',
-                 content: skillJson,
-                 title: name,
-                 description })
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm (store)
-```
-
-**Examples:**
-```sh
-# Learn a skill from a file
-kbdb skill learn --name summarize-document \
-   --description "Summarize a document" \
-   --body ./prompts/summarize.txt
-
-# Learn a skill from stdin
-cat summarize.txt | kbdb skill learn \
-   --name summarize-document --body -
-
-# Learn a skill in a specific database
-kbdb skill learn --name my-skill \
-   --body ./skill.txt --db /path/to/project
-```
-
-#### `skill list` -- list all skills
-
-```
-kbdb skill list [options]
-```
-
-List all skill definitions stored in the database.
-
-`skill list` sets `options.command = 'skill-list'`.
-
-**Output:**
-- **stdout**: JSON array of skill summaries:
-  ```json
-  [
-     {
-        "kbid": "abcdef1234567890abcdef1234",
-        "name": "summarize-document",
-        "description": "Summarize a document...",
-        "argumentCount": 2
-     }
-  ]
-  ```
-  Empty array when no skills exist.
-- **stderr**: errors only.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runSkillList(client, options)
-            -> client.listByType('skill')
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm (scan)
-```
-
-#### `skill get` -- retrieve a skill
-
-```
-kbdb skill get [options] <name-or-kbid>
-```
-
-Retrieve a single skill definition by name or kbid.
-
-`skill get` sets `options.command = 'skill-get'`.
-
-**Arguments:**
-- `<name-or-kbid>` -- (required) the skill name
-  (e.g. `summarize-document`) or a 26-character kbid.
-  When looked up by name, returns the most recently
-  created skill with that name.
-
-**Output:**
-- **stdout**: JSON `SkillDefinition` object:
-  ```json
-  {
-     "kbid": "abcdef1234567890abcdef1234",
-     "name": "summarize-document",
-     "description": "Summarize a document...",
-     "arguments": [
-        {
-           "name": "docid",
-           "type": "string",
-           "description": "Document identifier",
-           "required": true
-        }
-     ],
-     "body": "Summarize the document {{docid}}..."
-  }
-  ```
-- **stderr**: errors only.
-
-**Exit code:** `0` on success, `1` when not found or
-on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runSkillGet(client, options)
-            -> client.listByType('skill')
-               (filter by name or kbid)
-            -> client.content([kbid])
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm (fetch)
-```
-
-#### `skill delete` -- remove a skill
-
-```
-kbdb skill delete [options] <kbid>
-```
-
-Remove a skill section by its kbid. The skill body
-and index entries are permanently deleted.
-
-`skill delete` sets `options.command = 'skill-delete'`.
-
-**Arguments:**
-- `<kbid>` -- (required) the 26-character kbid of the
-  skill to remove.
-
-**Output:**
-- **stdout**: JSON result:
-  ```json
-  { "kbid": "abcdef1234567890abcdef1234", "removed": true }
-  ```
-  `"removed"` is `false` when the kbid does not exist.
-- **stderr**: errors only.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runSkillDelete(client, options)
-            -> client.removeSection(kbid)
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm (delete)
-```
-
-### `kbdb agent` -- agent management
-
-The `agent` command group manages AI agent persona
-definitions stored as document manifests with
-`type: 'agent'`. See [Agents](agents.md) for the
-full agent specification.
-
-#### `agent create` -- create an agent
-
-```
-kbdb agent create [options] --name <n>
-   --persona <file|-> --skills <kbid,...>
-```
-
-Read a persona from a file or stdin, validate the
-referenced skill kbids, and create an agent document
-manifest.
-
-`agent create` sets `options.command = 'agent-create'`.
-
-**Options:**
-
-| Option              | Required | Description                       |
-|---------------------|----------|-----------------------------------|
-| `--name <n>`        | yes      | Agent name (kebab-case)           |
-| `--description <d>` | no       | Human-readable agent description  |
-| `--persona <file\|->` | yes    | Persona file path or stdin        |
-| `--skills <kbid,...>` | yes    | Comma-separated ordered skill kbids |
-| `--db <path>`       | no       | Path to `.kbdb` directory         |
-
-**Behaviour:**
-- Reads the persona text from the file path given to
-  `--persona`, or from stdin when `--persona` is `-`.
-- Splits `--skills` on commas to produce an ordered
-  list of skill kbids. Each kbid is validated to
-  exist in the database before the agent is created.
-- Creates a document manifest with `type = "agent"`,
-  the persona text, and ordered `[[sections]]`
-  entries referencing each skill kbid.
-
-**Output:**
-- **stdout**: JSON object on success:
-  ```json
-  {
-     "docid": "agent-code-reviewer",
-     "name": "code-reviewer",
-     "skills": [
-        "abcdef1234567890abcdef1234",
-        "fedcba9876543210fedcba9876"
-     ]
-  }
-  ```
-- **stderr**: errors only.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runAgentCreate(client, options)
-            -> client.listByType('skill')
-               (validate skill kbids)
-            -> client.createDocument({
-                 type: 'agent',
-                 title: name,
-                 description,
-                 persona,
-                 skills: kbids })
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm (write)
-```
-
-**Examples:**
-```sh
-# Create an agent from a persona file
-kbdb agent create --name code-reviewer \
-   --description "Reviews code for best practices" \
-   --persona ./personas/reviewer.txt \
-   --skills abc123,def456
-
-# Create an agent with persona from stdin
-cat persona.txt | kbdb agent create \
-   --name my-agent --persona - \
-   --skills abc123
-
-# Create an agent in a specific database
-kbdb agent create --name my-agent \
-   --persona ./persona.txt --skills abc123 \
-   --db /path/to/project
-```
-
-#### `agent list` -- list all agents
-
-```
-kbdb agent list [options]
-```
-
-List all agent definitions stored in the database.
-
-`agent list` sets `options.command = 'agent-list'`.
-
-**Output:**
-- **stdout**: JSON array of agent summaries:
-  ```json
-  [
-     {
-        "docid": "agent-code-reviewer",
-        "name": "code-reviewer",
-        "description": "Reviews code for best practices",
-        "skillCount": 2
-     }
-  ]
-  ```
-  Empty array when no agents exist.
-- **stderr**: errors only.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runAgentList(client, options)
-            -> client.listDocumentsByType('agent')
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm (scan)
-```
-
-#### `agent get` -- retrieve an agent
-
-```
-kbdb agent get [options] <docid>
-```
-
-Retrieve a single agent definition by its document
-ID, with resolved skill definitions.
-
-`agent get` sets `options.command = 'agent-get'`.
-
-**Arguments:**
-- `<docid>` -- (required) the agent document ID
-  (e.g. `agent-code-reviewer`).
-
-**Output:**
-- **stdout**: JSON `AgentDefinition` object with
-  resolved skills:
-  ```json
-  {
-     "docid": "agent-code-reviewer",
-     "name": "code-reviewer",
-     "description": "Reviews code for best practices",
-     "persona": "You are an expert code reviewer...",
-     "skills": [
-        {
-           "kbid": "abcdef1234567890abcdef1234",
-           "name": "review-style",
-           "position": 0
-        },
-        {
-           "kbid": "fedcba9876543210fedcba9876",
-           "name": null,
-           "position": 1
-        }
-     ]
-  }
-  ```
-  A `null` skill name indicates a dangling reference
-  (the referenced skill was deleted). This is a
-  warning, not an error.
-- **stderr**: errors only.
-
-**Exit code:** `0` on success, `1` when not found or
-on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runAgentGet(client, options)
-            -> client.listDocumentsByType('agent')
-               (find by docid)
-            -> client.listByType('skill')
-               (resolve skill kbids)
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm (fetch)
-```
-
-#### `agent delete` -- remove an agent
-
-```
-kbdb agent delete [options] <docid>
-```
-
-Remove an agent document manifest by its document ID.
-Only the agent manifest is removed -- the referenced
-skill sections are not deleted.
-
-`agent delete` sets `options.command = 'agent-delete'`.
-
-**Arguments:**
-- `<docid>` -- (required) the agent document ID to
-  remove.
-
-**Output:**
-- **stdout**: JSON result:
-  ```json
-  { "docid": "agent-code-reviewer", "removed": true }
-  ```
-  `"removed"` is `false` when the docid does not exist.
-- **stderr**: errors only.
-
-**Exit code:** `0` on success, `1` on error.
-
-**Delegation chain:**
-```
-src/cli.ts  parseArgs()
-  -> findDb() / promptUser() / runDbInit()
-  -> createWorkerClient({ contextPath })
-  -> versionGate(client, dbDir)
-  -> dispatchCommand(client, options)
-       -> runAgentDelete(client, options)
-            -> client.removeDocument(docid)
-                 -> IPC -> worker daemon
-                      -> kb-worker.wasm
-                           -> fs-database.wasm (delete)
-```
-
-## Database Initialisation
-
-Before executing any data command (`learn`, `unlearn`,
-`search`, etc.) the CLI checks for the `.kbdb`
-storage directory via `findDb()`.
-
-### Current behaviour
-
-1. **Explicit init** -- `kbdb db init` creates the
-   database directory with the full scaffold. This is
-   the only way to create a new database without being
-   prompted.
-
-2. **Interactive prompt** -- when a data command finds
-   no `.kbdb` directory:
-   - If stdin is a TTY (`isStdinTty()` returns `true`):
-     prompt "No .kbdb database found. Create one in
-     \<path>? [y/N]"
-     - On "y": call `runDbInit()`, continue with the
-       command.
-     - Otherwise: print "aborted: no database created"
-       to stderr, exit 1.
-   - If stdin is not a TTY (piped / CI): print error to
-     stderr, exit 1. No prompt.
-
-2b. **Non-interactive override** -- when
-    `--non-interactive` is passed or
-    `KBDB_NON_INTERACTIVE` is set to `1` or `true`,
-    the CLI overrides `isStdinTty()` to return
-    `false`. This forces the non-interactive path
-    (error + exit 1) regardless of terminal type.
-
-3. **Version check gate** -- when `.kbdb` exists, the
-   CLI calls `client.checkVersion(dbDir)` before
-   dispatching any data command:
-   - `needs_migration`: print error ("database needs
-     migration -- run `kbdb db migrate`"), exit 1.
-   - `too_new`: print error ("database version X is
-     newer than kbdb version Y -- upgrade kbdb"),
-     exit 1.
-   - `ok`: proceed.
-
-4. **MCP mode** -- does NOT prompt. Requires an
-   existing `.kbdb` directory and passes the same
-   version gate.
-
-## CLI Mode Execution Model
-
-The CLI follows a strict pass-through architecture:
-
-1. Parse command-line arguments (`parseArgs()`).
-2. Handle `help` or empty command: return `HELP_TEXT`,
-   exit 0.
-3. Handle `version`: return `VERSION` string, exit 0.
-4. Handle `db-init`: call `runDbInit()` directly (no
-   daemon needed).
-5. Handle `mcp`: find DB, create client, version gate,
-   start MCP server.
-6. Handle `db-migrate`: find DB, create client, call
-   `checkVersion` and `migrateDatabase`.
-7. For data commands: find DB (prompt if missing),
-   create client, version gate, call
-   `dispatchCommand()`.
-8. `dispatchCommand()` routes to the appropriate
-   `run*` function and returns a `CommandResult`.
-9. The entry point (`src/cli.ts`) writes
-   `result.output` to stdout and `result.error` to
-   stderr, then exits with `result.exitCode`.
-
-The CLI prints nothing else. No banners, no progress
-bars, no decorative output unless explicitly requested
-via flag. Stdout contains only the result. Stderr
-contains only errors. This makes the CLI composable
-with pipes, scripts, and programmatic callers.
-
-## Argument Parsing
-
-The `parseArgs(argv)` function in
-`src/shared/cli/functions/parse-args.function.ts`
-processes the raw argument vector
-(`process.argv.slice(2)` on Node.js,
-`Deno.args` on Deno) into a `CliOptions` object.
-
-### Parsing rules
-
-1. `--help` / `-h` and `--version` / `-v` are
-   **early-exit flags** -- they set the command and
-   return immediately, ignoring all other arguments.
-2. `--init` sets `command = 'init'`, emits a
-   deprecation warning to stderr, and continues
-   parsing (does not return early).
-3. `--migrate` sets `command = 'migrate'`, emits a
-   deprecation warning to stderr, and continues
-   parsing.
-4. When the first positional token is `db`, `skill`,
-   `agent`, or `worker`, the parser consumes the next positional
-   token as the subcommand and combines them into a
-   hyphenated command string: `db init` →
-   `'db-init'`, `skill learn` → `'skill-learn'`,
-   `agent create` → `'agent-create'`,
-   `worker stop` → `'worker-stop'`, etc.
-5. All other flags (`--db`, `--format`, `--mode`,
-   `--limit`, `--offset`, `--title`, `--description`,
-   `--docid`, `--name`, `--persona`, `--body`,
-   `--skills`, `--depth` / `-d`, `--tags`,
-   `--timeout-ms`, `--retry`) consume the next token
-   as their value. `--depth` is parsed as a number
-   and clamped to the range 0--3. `--tags` splits its
-   value on commas into a `string[]`. `--timeout-ms`
-   and `--retry` are parsed as numbers.
-6. `--content` / `-c` and `--replace` are boolean
-   flags; they set their respective option to `true`
-   without consuming the next token.
-7. The first non-flag, non-group token becomes the
-   **command**.
-8. Subsequent non-flag tokens become **positional
-   arguments** (`args`).
-9. Unknown flags are treated as positional arguments.
-
-### `CliOptions` type
-
-Defined in
-`src/shared/cli/typings/cli-options.interface.ts`:
-
-```typescript
-/** Supported output formats for CLI results. */
-type OutputFormat = 'json' | 'text' | 'mcp';
-
-/**
- * Controls which entity type is returned by a search.
- */
-type SearchMode = 'sections' | 'documents' | 'stats';
-
-/** Parsed representation of all CLI arguments. */
-interface CliOptions {
-   /** Sub-command to execute. Simple commands use the
-    *  command name directly (e.g. 'search', 'learn').
-    *  Compound commands use a hyphenated form
-    *  (e.g. 'db-init', 'skill-learn', 'agent-create').
-    *  Legacy flag commands use 'init' and 'migrate'.
-    *  Empty string when no command is given. */
-   command: string;
-   /** Path to the knowledge-base root directory. */
-   dbPath?: string;
-   /** Output format for results. Defaults to 'json'. */
-   format: OutputFormat;
-   /** Search mode. Defaults to 'sections'. */
-   mode: SearchMode;
-   /** Maximum number of results. Defaults to 20. */
-   limit: number;
-   /** Zero-based result offset for pagination.
-    *  Defaults to 0. */
-   offset: number;
-   /** Section title for learn command. */
-   title?: string;
-   /** Section description for learn command. */
-   description?: string;
-   /** Document ID to attach sections to (learn). */
-   docid?: string;
-   /** When true, hydrates search result previews
-    *  with actual section content. */
-   content?: boolean;
-   /** Skill or agent name (skill learn, agent create). */
-   name?: string;
-   /** Persona file path or '-' for stdin
-    *  (agent create). */
-   persona?: string;
-   /** Skill body file path or '-' for stdin
-    *  (skill learn). */
-   body?: string;
-   /** Comma-separated skill kbids
-    *  (agent create). Parsed to string[]. */
-   skills?: string[];
-   /** Recall expansion depth (0-3). Defaults to 0. */
-   depth?: number;
-   /** Comma-separated tags for scoping (learn). */
-   tags?: string[];
-   /** Enable supersession by source key (learn). */
-   replace?: boolean;
-   /** Request timeout in ms. */
-   timeoutMs?: number;
-   /** Max retry count on timeout. */
-   retry?: number;
-   /** Positional arguments following the sub-command. */
-   args: string[];
-}
-```
-
-`command` is a plain `string`, not a union type. The
-value is whatever the first non-flag token is (or the
-compound form for `db`/`skill`/`agent` groups), or the
-special values `'help'`, `'version'`, `'init'`, and
-`'migrate'` set by flags.
-
-`OutputFormat` and `SearchMode` are string literal
-union type aliases, not enums.
-
-### Defaults
-
-| Field    | Default      | Constant          |
-|----------|--------------|-------------------|
-| `format` | `'json'`     | `DEFAULT_FORMAT`  |
-| `mode`   | `'sections'` | `DEFAULT_MODE`    |
-| `limit`  | `20`         | `DEFAULT_LIMIT`   |
-| `offset` | `0`          | `DEFAULT_OFFSET`  |
-
-Constants are defined in
-`src/shared/cli/constants/defaults.constant.ts`.
-The same file exports `SUPPORTED_EXTENSIONS` listing
-the file extensions accepted by the learn command.
-
-## Help Text
-
-The CLI implements a three-level contextual help
-system. The level of detail depends on how many
-command tokens precede `--help`.
-
-### Level 1: `kbdb --help` (global)
-
-Shows all commands grouped by category, global
-options, and a footer pointing to per-command help.
-
-```
-kbdb - File-based knowledge base database for AI agents
-
-Usage: kbdb [options]
-       kbdb <command> [options] ...[parameters]
-       kbdb <command> <subcommand> [options] ...[params]
-
-Options:
-   -h, --help          Show this help message
-   -v, --version       Show version information
-
-Knowledge Base:
-   learn               Import content from files/stdin
-   unlearn             Remove sections by kbid
-   search              Query the knowledge base
-   recall              Retrieve section context by kbid
-   content             Compose rendered content from ids
-
-Database:
-   db init             Initialise a new .kbdb directory
-   db migrate          Migrate database to current format
-
-Maintenance:
-   check               Verify knowledge base integrity
-   gc                  Garbage collect unreferenced
-                       sections
-   rebuild             Reconstruct all index files
-   status              Show database status
-   export              Snapshot database for backup
-
-Skills:
-   skill learn         Create a new skill definition
-   skill list          List all skills
-   skill get           Retrieve a skill by name or kbid
-   skill delete        Remove a skill
-
-Agents:
-   agent create        Create an agent with skill refs
-   agent list          List all agents
-   agent get           Retrieve an agent by docid
-   agent delete        Remove an agent
-
-Worker:
-   worker stop         Stop the background daemon
-   worker restart      Restart the background daemon
-
-Server:
-   mcp                 Start MCP server mode (stdio)
-
-Global Options:
-   --db <path>         Path to .kbdb directory
-   --format <fmt>      Output format (json|text|mcp)
-
-Run "kbdb <command> --help" for detailed information.
-```
-
-### Level 2: `kbdb <command> --help` (command)
-
-**For commands with subcommands** (`db`, `skill`,
-`agent`): shows subcommand listing with one-line
-descriptions, global options, and a footer:
-`Run "kbdb <cmd> <subcmd> --help" for detailed
-information.`
-
-**For commands without subcommands** (`learn`,
-`search`, `check`, etc.): shows full detail including:
-- Description paragraph
-- Arguments section with semantics
-- Options section with defaults and value descriptions
-- Output section showing both text and json format
-  examples
-- Two to three usage examples
-
-### Level 3: `kbdb <cmd> <subcmd> --help` (subcommand)
-
-Same detail level as Level 2 command help but scoped
-to a single subcommand. Includes: usage line,
-description paragraph, options with defaults,
-arguments, output format examples, and usage examples.
-
-### Help text principles
-
-- Every help level shows `[options]` immediately after
-  the command or subcommand in usage lines.
-- Options show short and long forms, value placeholder,
-  and default when applicable.
-- The output section shows both `text` and `json`
-  formats where relevant.
-- Examples progress from simple to complex.
-- Global options (`--db`, `--format`, `--help`) appear
-  in every help level for discoverability.
-
-## Output Types
-
-### `SearchDisplay` type
-
-Defined in
-`src/shared/cli/typings/search-display.model.ts`.
-This is the type that `formatOutput` and all search
-output handlers operate on. It is produced by
-`runSearch()` and optionally enriched by
-`hydrateSearchPreviews()`.
-
-```typescript
-interface SearchDisplay {
-   /** Knowledge-base identifier of the matched section. */
-   kbid: string;
-   /** Section title text, or null when the section
-    *  has no title. */
-   heading: string | null;
-   /** Section MIME type (e.g. "text/markdown"). */
-   type: string;
-   /** Document identifiers this section belongs to.
-    *  May be empty for standalone sections. */
-   docids: string[];
-   /** Relevance score from the ranking engine. */
-   score: number;
-   /** Normalized score (0.0-1.0) relative to the top
-    *  result in this result set. */
-   confidence: number;
-   /** KWIC excerpt (~150 chars) centered on the
-    *  highest-scoring matched term. Empty string
-    *  for image sections. */
-   snippet: string;
-   /** Query terms that matched, as a flat string[]. */
-   matched_terms: string[];
-   /** Fields that contained matches: subset of
-    *  ["heading", "body", "code"]. */
-   matched_fields: string[];
-   /** ISO 8601 creation timestamp. */
-   created_at: string;
-   /** Full section text. Empty string when --content
-    *  is not used. */
-   preview: string;
-}
-```
-
-`heading`, `type`, `docids`, `snippet`, and
-`matched_terms` are always populated from the search
-result. `preview` is always an empty string unless
-`--content` / `-c` is supplied, in which case
-`hydrateSearchPreviews()` fills it with the actual
-section text fetched from `client.content()`.
-`heading` is `null` when the section has no title.
-
-### `LearnResult` type
-
-Defined in
-`src/shared/cli/typings/learn-result.model.ts`.
-Produced by `runLearn()` for each file ingested.
-
-```typescript
-interface LearnResult {
-   /** Knowledge-base identifier assigned to the section. */
-   kbid: string;
-   /** Absolute path to the source file (or "-" for
-    *  stdin). */
-   path: string;
-   /** UTF-8 character count of the ingested content. */
-   size: number;
-   /** true when the file was skipped. */
-   skipped: boolean;
-   /** Kbid of the section this one superseded via
-    *  --replace, or null. */
-   superseded: string | null;
-   /** Warning strings (e.g. "heading_missing"). */
-   warnings: string[];
-   /** Sections with similarity >= 0.85. */
-   near_duplicates: Array<{
-      kbid: string;
-      similarity: number;
-   }>;
-}
-```
-
-### `CommandResult` type
-
-Defined in
-`src/shared/cli/typings/command-result.model.ts`.
-Returned by `runCli()` and `dispatchCommand()` so the
-entry point can write output and exit without those
-functions touching process globals.
-
-```typescript
-interface CommandResult {
-   /** Text to write to stdout (if any). */
-   output?: string;
-   /** Error message to write to stderr (if any). */
-   error?: string;
-   /** Process exit code. 0 means success. */
-   exitCode: number;
-}
-```
-
-## Key Functions
-
-### `runCli`
-
-Source:
-`src/shared/cli/functions/run-cli.function.ts`
-
-Full CLI orchestrator. Takes the raw argument vector
-and an injectable `CliDeps` object. Returns a
-`CommandResult`. Never touches process globals.
-
-```typescript
-async function runCli(
-   argv: string[],
-   deps: CliDeps,
-): Promise<CommandResult>
-```
-
-`CliDeps` contains:
-
-| Field               | Description                          |
-|---------------------|--------------------------------------|
-| `isStdinTty`        | Returns `true` when stdin is a TTY   |
-| `promptUser`        | Prompts the user and returns input   |
-| `createWorkerClient`| Creates a connected worker client    |
-| `findDb`            | Looks up the `.kbdb` directory       |
-| `runDbInit`         | Creates the `.kbdb` scaffold on disk |
-| `startMcpServer`    | (Optional) Starts the MCP server     |
-
-Routing within `runCli`:
-- `command === 'help'` or empty: return `HELP_TEXT`
-- `command === 'version'`: return `VERSION`
-- `command === 'db-init'`: `handleDbInit` (no client)
-- `command === 'init'`: `handleDbInit` (no client,
-  deprecated -- emits warning)
-- `command === 'mcp'`: `handleMcp` (requires client)
-- `command === 'db-migrate'`: `handleDbMigrate`
-  (requires client)
-- `command === 'migrate'`: `handleDbMigrate` (requires
-  client, deprecated -- emits warning)
-- anything else: `handleDataCommand` (requires client,
-  runs version gate, then `dispatchCommand`)
-
-### `dispatchCommand`
-
-Source:
-`src/shared/cli/functions/dispatch-command.function.ts`
-
-Routes a parsed command to the appropriate `run*`
-handler. Returns `CommandResult` without throwing.
-Wraps each handler call in a try/catch so errors are
-captured as `error` fields with a non-zero exit code.
-
-```typescript
-async function dispatchCommand(
-   client: DispatchClient,
-   options: CliOptions,
-   io?: LearnIO,
-): Promise<CommandResult>
-```
-
-Routing table:
-
-| command          | handler            | requires client |
-|------------------|--------------------|-----------------|
-| `learn`          | `runLearn`         | yes             |
-| `unlearn`        | `runUnlearn`       | yes             |
-| `search`         | `runSearch`        | yes             |
-| `recall`         | `runRecall`        | yes             |
-| `content`        | `runContent`       | yes             |
-| `check`          | `runCheck`         | yes             |
-| `gc`             | `runGc`            | yes             |
-| `rebuild`        | `runRebuild`       | yes             |
-| `export`         | `runExport`        | yes             |
-| `db-init`        | `runDbInit`        | no              |
-| `db-migrate`     | `runDbMigrate`     | yes             |
-| `skill-learn`    | `runSkillLearn`    | yes             |
-| `skill-list`     | `runSkillList`     | yes             |
-| `skill-get`      | `runSkillGet`      | yes             |
-| `skill-delete`   | `runSkillDelete`   | yes             |
-| `agent-create`   | `runAgentCreate`   | yes             |
-| `agent-list`     | `runAgentList`     | yes             |
-| `agent-get`      | `runAgentGet`      | yes             |
-| `worker-stop`    | `runWorkerStop`    | yes             |
-| `worker-restart` | `runWorkerRestart` | yes             |
-| `agent-delete`   | `runAgentDelete`   | yes             |
-
-Unknown commands return exit code 1 with an "unknown
-command" error.
-
-For `search`, `dispatchCommand` also:
-1. Calls `runSearch()` to get `SearchDisplay[]`.
-2. When `options.content === true`, calls
-   `hydrateSearchPreviews(client, results)` to fill
-   each `preview` field.
-3. Calls `formatOutput(results, options.format)` to
-   produce the final output string.
-
-### `formatOutput`
-
-Source:
-`src/shared/cli/functions/format-output.function.ts`
-
-Serialises a `SearchDisplay[]` to a string in the
-requested format.
-
-```typescript
-function formatOutput(
-   results: SearchDisplay[],
-   format: OutputFormat,
-): string
-```
-
-- `'json'` -- `JSON.stringify(results, null, 2)`
-- `'text'` -- numbered list with kbid, score, preview,
-  and matched terms
-- `'mcp'` -- `{ type: 'text', text: '...' }` envelope
-  with one line per result
-
-### `runDbInit`
-
-Source:
-`src/shared/cli/functions/run-db-init.function.ts`
-
-Creates the `.kbdb` directory scaffold directly on
-disk without a daemon. Replaces the former `runInit`.
-
-```typescript
-async function runDbInit(
-   options: CliOptions,
-): Promise<CommandResult>
-```
-
-Writes `catalog.toml`, `corpus.bin`, `inverted.idx`,
-`positional.idx`, `sections/`, `documents/`,
-`worker.toml`, and `.gitignore` under the resolved
-database directory. Returns a JSON result with `path`
-and `created: true` on success.
-
-### `runDbMigrate`
-
-Source:
-`src/shared/cli/functions/run-db-migrate.function.ts`
-
-Runs the database migration path via the worker
-client. Replaces the former `runMigrate`.
-
-```typescript
-async function runDbMigrate(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult>
-```
-
-Calls `client.checkVersion(dbDir)`, then
-`client.migrateDatabase(dbDir)` when migration is
-needed. Returns the `MigrateResult` JSON.
-
-### `runSkillLearn`
-
-Source:
-`src/shared/cli/functions/run-skill-learn.function.ts`
-
-Reads the skill body, extracts `{{argName}}`
-placeholders, and stores the skill as a section.
-
-```typescript
-async function runSkillLearn(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult>
-```
-
-Reads body from `options.body` (file path or `-` for
-stdin). Calls `client.addSection()` with
-`sectionType: 'skill'`. Returns JSON with `kbid`,
-`name`, and `arguments`.
-
-### `runSkillList`
-
-Source:
-`src/shared/cli/functions/run-skill-list.function.ts`
-
-Lists all skill sections in the database.
-
-```typescript
-async function runSkillList(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult>
-```
-
-Calls `client.listByType('skill')` and returns a JSON
-array of skill summaries.
-
-### `runSkillGet`
-
-Source:
-`src/shared/cli/functions/run-skill-get.function.ts`
-
-Retrieves a single skill by name or kbid.
-
-```typescript
-async function runSkillGet(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult>
-```
-
-Uses `options.args[0]` as the name-or-kbid. Calls
-`client.listByType('skill')` to find the section,
-then `client.content([kbid])` to fetch the body.
-Returns a full `SkillDefinition` JSON.
-
-### `runSkillDelete`
-
-Source:
-`src/shared/cli/functions/run-skill-delete.function.ts`
-
-Removes a skill section by kbid.
-
-```typescript
-async function runSkillDelete(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult>
-```
-
-Uses `options.args[0]` as the kbid. Calls
-`client.removeSection(kbid)`. Returns JSON with
-`kbid` and `removed`.
-
-### `runAgentCreate`
-
-Source:
-`src/shared/cli/functions/run-agent-create.function.ts`
-
-Reads the persona, validates skill kbids, and creates
-an agent document manifest.
-
-```typescript
-async function runAgentCreate(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult>
-```
-
-Reads persona from `options.persona` (file path or
-`-` for stdin). Splits `options.skills` on commas.
-Validates each skill kbid exists via
-`client.listByType('skill')`. Calls
-`client.createDocument()` with `type: 'agent'`.
-Returns JSON with `docid`, `name`, and `skills`.
-
-### `runAgentList`
-
-Source:
-`src/shared/cli/functions/run-agent-list.function.ts`
-
-Lists all agent document manifests in the database.
-
-```typescript
-async function runAgentList(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult>
-```
-
-Calls `client.listDocumentsByType('agent')` and
-returns a JSON array of agent summaries.
-
-### `runAgentGet`
-
-Source:
-`src/shared/cli/functions/run-agent-get.function.ts`
-
-Retrieves a single agent by docid with resolved
-skill definitions.
-
-```typescript
-async function runAgentGet(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult>
-```
-
-Uses `options.args[0]` as the docid. Fetches the
-agent manifest via `client.listDocumentsByType()`,
-then resolves each skill kbid via
-`client.listByType('skill')`. Returns a full
-`AgentDefinition` JSON. Dangling skill kbids appear
-with `name: null`.
-
-### `runAgentDelete`
-
-Source:
-`src/shared/cli/functions/run-agent-delete.function.ts`
-
-Removes an agent document manifest by docid. Does
-not delete the referenced skill sections.
-
-```typescript
-async function runAgentDelete(
-   client: DispatchClient,
-   options: CliOptions,
-): Promise<CommandResult>
-```
-
-Uses `options.args[0]` as the docid. Calls
-`client.removeDocument(docid)`. Returns JSON with
-`docid` and `removed`.
-
-## Architecture -- How CLI Connects to WASM
-
-The CLI never loads WASM modules or accesses the
-`.kbdb` directory directly. The architecture is a
-four-layer delegation chain:
-
-```
-User
-  |
-  v
-src/cli.ts (TypeScript)         Layer 1: CLI
-  |  parseArgs(), runCli(),
-  |  dispatchCommand(), formatOutput()
-  |
-  v
-worker-client/ (TypeScript)      Layer 2: IPC Client
-  |  createWorkerClient()
-  |  JSON-RPC 2.0 over IPC
-  |
-  v
-src/worker.ts (TypeScript)  Layer 3: Daemon
-  |  loads WASM modules,
-  |  manages cache,
-  |  serves IPC requests
-  |
-  v
-WASM modules (Rust)              Layer 4: Engine
-  kb-worker.wasm  (orchestration)
-    -> query-parser.wasm  (tokenize, parse, rank)
-    -> fs-database.wasm   (storage, indexes)
-    -> fs-migration.wasm  (version migration)
-```
-
-### Layer 1: CLI (`src/cli.ts`)
-
-The entry point. Responsibilities:
-- Parse command-line arguments
-- Dispatch to the correct command handler via `runCli`
-- Format output for stdout via `dispatchCommand` /
-  `formatOutput`
-- Handle errors to stderr
-- Exit with appropriate code
-
-Source: `src/cli.ts`
-Module: `src/shared/cli/`
-
-### Layer 2: Worker Client
-
-The IPC bridge. Responsibilities:
-- Resolve database directory path
-- Compute context ID (SHA-256 of path)
-- Discover running daemon or spawn a new one
-- Connect to daemon over IPC socket
-- Expose typed async methods that send JSON-RPC 2.0
-  requests
-
-Source: `src/shared/worker-client/`
-See: [Worker Client](worker-client.md)
-
-### Layer 3: Worker Daemon
-
-The background process. Responsibilities:
-- Compile and load WASM modules once at startup
-- Maintain in-memory LRU cache
-- Process IPC requests through WASM modules
-- Manage daemon lifecycle (idle timeout, shutdown)
-
-Source: `src/worker.ts`
-Module: `src/shared/worker-daemon/`
-See: [Worker Daemon](worker-daemon.md)
-
-### Layer 4: WASM Engine
-
-The Rust engine compiled to WebAssembly.
-Responsibilities vary by module:
-
-| Module              | Responsibility                    |
-|---------------------|-----------------------------------|
-| `kb-worker.wasm`    | Orchestrates the other modules, manages cache and async result tokens |
-| `query-parser.wasm` | Tokenization pipeline, query parsing, keyword extraction, ranking (BM25F, TF-IDF, RAKE) |
-| `fs-database.wasm`  | `.kbdb` directory I/O: section CRUD, document manifests, B+ tree indexes, integrity checks |
-| `fs-migration.wasm` | Database format versioning, sequential migration scripts |
-
-See: [Database](database.md),
-[Query Parser](query-parser.md)
-
-### Which WASM module handles what
-
-| CLI command       | WASM modules involved                     |
-|-------------------|-------------------------------------------|
-| `learn`           | `query-parser` (tokenize) + `fs-database` (store + index) via `kb-worker` |
-| `unlearn`         | `fs-database` (delete + re-index) via `kb-worker` |
-| `search`          | `query-parser` (parse + rank) + `fs-database` (index lookup) via `kb-worker` |
-| `content`         | `fs-database` (fetch sections/docs) via `kb-worker` |
-| `check`           | `fs-database` (verify checksums, scan manifests) via `kb-worker` |
-| `gc`              | `fs-database` (scan + remove unreferenced) via `kb-worker` |
-| `rebuild`         | `query-parser` (retokenize) + `fs-database` (rebuild indexes) via `kb-worker` |
-| `db init`         | None -- `runDbInit()` writes files directly |
-| `db migrate`      | `fs-migration` (`db_migrate`) via daemon  |
-| `skill learn`     | `fs-database` (store section) via `kb-worker` |
-| `skill list`      | `fs-database` (scan by type) via `kb-worker` |
-| `skill get`       | `fs-database` (fetch section) via `kb-worker` |
-| `skill delete`    | `fs-database` (delete section) via `kb-worker` |
-| `agent create`    | `fs-database` (write manifest) via `kb-worker` |
-| `agent list`      | `fs-database` (scan documents by type) via `kb-worker` |
-| `agent get`       | `fs-database` (fetch manifest + sections) via `kb-worker` |
-| `agent delete`    | `fs-database` (remove manifest) via `kb-worker` |
-
-### Data flow: search
-
-```
-kbdb search "machine learning" --limit 5
-
-1. parseArgs() -> { command: 'search',
-      args: ['machine', 'learning'],
-      mode: 'sections', limit: 5, offset: 0,
-      format: 'json', content: undefined }
-
-2. handleDataCommand():
-      findDb() -> '/home/user/project/.kbdb'
-
-3. createWorkerClient({ contextPath })
-      -> discovers daemon, connects via IPC
-
-4. versionGate(client, dbDir)
-      -> client.checkVersion(dbDir)
-      -> status 'ok', proceed
-
-5. dispatchCommand(client, options)
-      -> runSearch(client, options)
-         -> client.search({
-               query: 'machine learning',
-               mode: 'sections', limit: 5,
-               offset: 0 })
-         -> JSON-RPC: { method: 'search', params: {...} }
-
-6. Worker daemon receives request:
-      -> kb-worker.wasm orchestrates:
-         a. query-parser.wasm: parse query into
-            retrieval plan
-         b. fs-database.wasm: execute plan against
-            indexes, return raw matches
-         c. query-parser.wasm: rank results (BM25F,
-            proximity, zone, freshness scoring)
-      -> returns ranked results via IPC
-
-7. runSearch() maps to SearchDisplay[]:
-      [{ kbid, heading, type, docids, score,
-         snippet, matched_terms, preview: '' }]
-
-8. options.content is falsy -> skip hydration
-
-9. formatOutput(results, 'json')
-      -> JSON.stringify(results, null, 2)
-
-10. CommandResult: { output, exitCode: 0 }
-
-11. src/cli.ts writes output to stdout
-    client.disconnect()
-```
-
-## Environment Variables
-
-| Variable              | Used by   | Description             |
-|-----------------------|-----------|-------------------------|
-| `KBDB_DB_DIR`         | CLI + MCP | Fallback database directory when `--db` is not specified |
-| `KBDB_DAEMON_TIMEOUT` | CLI + MCP | Request timeout fallback (ms) |
-| `KBDB_RETRY`          | CLI + MCP | Retry count fallback    |
-
-### Resolution Priority
-
-When multiple sources set the same option, the
-most specific source wins:
-
-- **timeout**: `--timeout-ms` >
-  `KBDB_DAEMON_TIMEOUT` > `30000`
-- **retry**: `--retry` > `KBDB_RETRY` > `5`
-- **db path**: `--db` > `KBDB_DB_DIR` > cwd
-
-## Exit Codes
-
-| Code | Meaning                                |
-|------|----------------------------------------|
-| `0`  | Success                                |
-| `1`  | Error (invalid args, missing DB, WASM error, version mismatch, unknown command) |
-
-All new commands (`db init`, `db migrate`, `skill`
-subcommands, `agent` subcommands) follow the same two
-exit code convention. No additional codes are needed.
-
-## Design Constraints
-
-- The CLI is a **thin pass-through**. It does not
-  perform keyword extraction, indexing, ranking, or
-  database I/O itself.
-- **stdout** contains only the command result. No
-  banners, progress bars, or decorative output.
-- **stderr** contains only errors (and deprecation
-  warnings for `--init` / `--migrate`).
-- The CLI does not read or write `.kbdb` files
-  directly (except `db init`, which creates the
-  scaffold without a daemon). All other database
-  operations go through the worker client -> daemon ->
-  WASM chain.
-- The CLI works on both **Deno and Node.js**. Runtime
-  differences (argument access, process spawning) are
-  abstracted in `src/shared/runtime/` and
-  `src/shared/platform/`.
-- Output format is controlled by `--format`, not by
-  detecting whether stdout is a TTY.
-- The `--init` and `--migrate` flags are kept for
-  backward compatibility but are deprecated. They emit
-  a warning to stderr and delegate to the same
-  `runDbInit` / `runDbMigrate` handlers as the new
-  `kbdb db init` / `kbdb db migrate` commands.
-- `kbdb db init` is the canonical way to create a
-  new database. `kbdb db migrate` is the canonical
-  way to migrate.