@dikolab/kbdb 0.1.5 → 0.2.0

package/docs/goals/cli.md

@@ -0,0 +1,2308 @@
+# 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 | -v
+kbdb learn [options] <path | ->...
+kbdb unlearn [options] <kbid>...
+kbdb search [options] <query>...
+kbdb content [options] <id>...
+kbdb mcp [options]
+kbdb check [options]
+kbdb gc [options]
+kbdb rebuild [options]
+kbdb status [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 requires `--db <path>` or the `KBDB_DIR`
+environment variable. It does not fall back to the
+current working directory because the server's cwd is
+determined by the host application, not the user.
+
+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`   | `-v`  | Print version and exit   |
+| `--db <path>` |       | Database directory path  |
+
+### `--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`, `-v`
+
+Print the package version string and exit. No database
+connection is made.
+
+```
+kbdb --version
+kbdb -v
+```
+
+### `--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**: defaults to the current working
+  directory (`process.cwd()`).
+- **MCP mode**: falls back to the `KBDB_DIR`
+  environment variable. If neither `--db` nor
+  `KBDB_DIR` is set, the MCP server prints an error
+  and exits non-zero.
+
+## 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.
+
+**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
+     }
+  ]
+  ```
+  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.
+- **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. 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   |
+| `--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).    |
+| `text` | Numbered human-readable list with scores and matched terms. |
+| `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,
+         "snippet": "Machine learning is a subfield...",
+         "matched_terms": ["machine", "learning"],
+         "preview": ""
+      }
+   ],
+   "total": 42,
+   "offset": 0,
+   "limit": 20,
+   "has_more": true
+}
+```
+
+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,
+         "snippet": "Machine learning is a subfield...",
+         "matched_terms": ["machine", "learning"],
+         "preview": "Machine learning is a subfield..."
+      }
+   ],
+   "total": 42,
+   "offset": 0,
+   "limit": 20,
+   "has_more": true
+}
+```
+
+`--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.
+
+**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.
+
+### `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.
+- Requires `--db <path>` or the `KBDB_DIR` environment
+  variable. Does NOT fall back to the current working
+  directory.
+- 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_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 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, and
+type consistency.
+
+**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
+  }
+  ```
+  When no sections are eligible, `removed_sections`
+  is `0` and `removed_bytes` is `0`.
+- **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
+```
+
+### `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.
+
+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`,
+   or `agent`, 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'`, etc.
+5. All other flags (`--db`, `--format`, `--mode`,
+   `--limit`, `--offset`, `--title`, `--description`,
+   `--docid`, `--name`, `--persona`, `--body`,
+   `--skills`) consume the next token as their value.
+6. `--content` / `-c` is a boolean flag; it sets
+   `options.content = 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[];
+   /** 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
+   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
+
+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
+
+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;
+   /** 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[];
+   /** 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 without being ingested. */
+   skipped: boolean;
+}
+```
+
+### `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             |
+| `content`        | `runContent`       | yes             |
+| `check`          | `runCheck`         | yes             |
+| `gc`             | `runGc`            | yes             |
+| `rebuild`        | `runRebuild`       | 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             |
+| `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_DIR` | MCP mode | Fallback database directory when `--db` is not specified. Not used in CLI mode. |
+
+## 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.