@dikolab/kbdb 0.3.2 → 0.4.1

package/docs/details/mcp-server.md

@@ -8,7 +8,7 @@ agents over stdio using JSON-RPC 2.0.
 
 Configure kbdb as an MCP server for your AI agent
 platform. The server requires a database path via
-`--db` or the `KBDB_DIR` environment variable.
+`--db` or the `KBDB_DB_DIR` environment variable.
 
 ### Claude Code (CLI)
 
@@ -131,9 +131,9 @@ deno run -A jsr:@dikolab/kbdb/cli mcp \
    --db /path/to/.kbdb
 ```
 
-### Using `KBDB_DIR` Environment Variable
+### Using `KBDB_DB_DIR` Environment Variable
 
-The `--db` flag can be replaced by the `KBDB_DIR`
+The `--db` flag can be replaced by the `KBDB_DB_DIR`
 environment variable in any configuration:
 
 ```json
@@ -143,20 +143,66 @@ environment variable in any configuration:
          "command": "npx",
          "args": ["-y", "@dikolab/kbdb", "mcp"],
          "env": {
-            "KBDB_DIR": "/path/to/.kbdb"
+            "KBDB_DB_DIR": "/path/to/.kbdb"
          }
       }
    }
 }
 ```
 
-Resolution order: `--db` flag, then `KBDB_DIR`
+Resolution order: `--db` flag, then `KBDB_DB_DIR`
 env var. If neither is set, the server exits with
 an error. The server does not fall back to the
 current working directory because the server's cwd
 is determined by the host application, not the
 user.
 
+### `KBDB_DAEMON_TIMEOUT`
+
+Per-request daemon timeout in milliseconds.
+Defaults to `30000` (30 seconds). Overridden by
+the `--timeout-ms` flag.
+
+### `KBDB_RETRY`
+
+Maximum number of retries with daemon respawn when
+a request times out. Defaults to `1`. Overridden
+by the `--retry` flag.
+
+### `KBDB_LOG_LEVEL`
+
+Log verbosity: `debug`, `info`, `warning`, `error`
+(case-insensitive). Defaults to `error`. Overridden
+by `-v`/`-vv`/`-vvv` flags. The level is forwarded
+to the worker daemon via `--log-level`.
+
+### `KBDB_NON_INTERACTIVE`
+
+Suppress interactive prompts. Accepts `1` or
+`true`. The MCP server does not prompt interactively
+(it reads JSON-RPC from stdin), but the variable is
+inherited by the worker daemon for consistency.
+
+These variables can be set in the `env` block of
+your MCP configuration:
+
+```json
+{
+   "mcpServers": {
+      "kbdb": {
+         "command": "npx",
+         "args": ["-y", "@dikolab/kbdb", "mcp"],
+         "env": {
+            "KBDB_DB_DIR": "/path/to/.kbdb",
+            "KBDB_DAEMON_TIMEOUT": "60000",
+            "KBDB_RETRY": "2",
+            "KBDB_LOG_LEVEL": "warning"
+         }
+      }
+   }
+}
+```
+
 ### Multiple Knowledge Bases
 
 Register multiple server instances pointing to
@@ -213,7 +259,7 @@ daemon via JSON-RPC 2.0 over IPC.
 
 | Tool | Parameters | Description | Read-only | Destructive |
 |------|-----------|-------------|-----------|-------------|
-| `skill-learn` | `name` (string, required), `description` (string, required), `body` (string, required), `arguments` (array) | Create a new skill definition. Body supports `{{argName}}` template placeholders. | no | no |
+| `skill-learn` | `name` (string, required), `description` (string), `body` (string, required) | Create or update a skill definition. Body supports `{{argName}}` template placeholders. | no | no |
 | `skill-list` | (none) | List all skill definitions. Returns array of summaries with kbid, name, description, argumentCount. | yes | no |
 | `skill-get` | `name` (string), `kbid` (string) | Retrieve a single skill by name or kb-id. At least one required; `kbid` takes precedence. | yes | no |
 | `skill-delete` | `kbid` (string, required) | Remove a skill by kb-id. Agent documents referencing this skill will have dangling references. | no | yes |
@@ -222,7 +268,7 @@ daemon via JSON-RPC 2.0 over IPC.
 
 | Tool | Parameters | Description | Read-only | Destructive |
 |------|-----------|-------------|-----------|-------------|
-| `agent-create` | `name` (string, required), `description` (string, required), `persona` (string, required), `skills` (string[], required) | Create an agent document with a persona and ordered skill references. | no | no |
+| `agent-create` | `name` (string, required), `description` (string), `persona` (string, required), `skills` (string[]) | Create an agent with a persona and optional skill references. | no | no |
 | `agent-list` | (none) | List all agent documents. Returns array of summaries with docid, name, description, skillCount. | yes | no |
 | `agent-get` | `docid` (string, required) | Retrieve an agent with resolved skill definitions. Deleted skills appear with `name: null`. | yes | no |
 | `agent-delete` | `docid` (string, required) | Remove an agent document. Referenced skill sections are preserved. | no | yes |

package/docs/details/search-and-ranking.md

@@ -2,11 +2,13 @@
 
 When you search, kbdb finds the sections that best
 match your query and ranks them by relevance. By
-default it matches keywords (like a search engine).
-You can also enable AI-powered similarity search
-or combine both with `--algo hybrid`. The rest of
-this page explains how ranking works under the hood
--- you don't need to read it to use kbdb.
+default it uses keyword search -- matching terms with
+stemming, synonym expansion, and BM25F ranking. Use
+`--algo hybrid` to combine keyword matching with
+AI-powered similarity for broader recall. The rest
+of this page explains how ranking
+works under the hood -- you don't need to read it
+to use kbdb.
 
 ---
 
@@ -529,12 +531,11 @@ Neither standalone module calls the other directly.
 kbdb supports three search algorithms, selected
 with `--algo` (CLI) or the `algo` parameter (MCP).
 
-### Lexical (default)
+### Lexical
 
 Keyword matching with stemming and synonym
 expansion, scored by BM25F as described above.
 Fast, works offline, and gives consistent results.
-This is the default when no `--algo` flag is given.
 
 ### Vector
 
@@ -551,7 +552,7 @@ because of JSONB" even though none of the words
 overlap.
 
 Requires an embedding provider to be configured.
-Without one, vector mode falls back to lexical.
+Without one, vector mode returns an error.
 
 ### Hybrid
 
@@ -559,12 +560,16 @@ Runs both lexical and vector searches in parallel,
 then merges the two ranked lists using Reciprocal
 Rank Fusion (RRF). This combines the precision of
 keyword matching with the associative recall of
-embeddings.
+embeddings. Use `--algo hybrid` to enable.
 
 RRF works by converting each result's rank position
 into a score (`1 / (k + rank)` with k=60), then
 summing scores across both lists. Results that rank
 well in both lists get the highest combined scores.
 
-Hybrid mode requires an embedding provider. Without
-one, it falls back to lexical.
+Hybrid mode uses a built-in TF-IDF embedding provider
+by default. Configure `provider = "onnx"` or
+`provider = "api"` in `worker.toml` for higher
+quality embeddings. Setting `provider = "none"`
+explicitly disables embeddings and returns an error
+for hybrid and vector searches.

package/docs/goals/cli.md

@@ -49,7 +49,10 @@ All commands and their canonical forms:
 
 ```
 kbdb --help | -h
-kbdb --version | -v
+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>...
@@ -61,6 +64,8 @@ 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|->
@@ -104,10 +109,9 @@ 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.
+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.
@@ -116,11 +120,18 @@ specification.
 
 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  |
+| 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`
 
@@ -135,16 +146,31 @@ kbdb -h
 When no command is given (`kbdb` with no arguments),
 the help text is printed as the default behaviour.
 
-### `--version`, `-v`
+### `--version`
 
 Print the package version string and exit. No database
 connection is made.
 
 ```
 kbdb --version
-kbdb -v
 ```
 
+### `--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
@@ -156,12 +182,13 @@ 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.
+- **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
 
@@ -300,7 +327,10 @@ Remove knowledge base sections by their kb-id.
 
 **Arguments:**
 - `<kbid>...` -- one or more 26-character kb-id
-  strings. Each is processed independently.
+  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
@@ -360,6 +390,7 @@ Search the knowledge base by keywords or phrases.
 | `--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`
@@ -406,8 +437,8 @@ 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. |
+| `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. |
 
 ```
@@ -553,7 +584,10 @@ more knowledge base identifiers and output it to
 stdout.
 
 **Arguments:**
-- `<id>...` -- one or more kbid or docid identifiers.
+- `<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
@@ -600,7 +634,9 @@ expansion depths.
 
 **Arguments:**
 - `<kbid>...` -- one or more 26-character kb-id
-  strings.
+  strings (or unique prefixes -- kbdb resolves
+  short prefixes to full identifiers, similar to
+  git short hashes).
 
 **Options:**
 
@@ -722,9 +758,9 @@ 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.
+- 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
@@ -734,8 +770,8 @@ Start a long-lived MCP server on stdio.
   a shutdown signal.
 
 **Environment variables:**
-- `KBDB_DIR` -- fallback database directory path when
-  `--db` is not specified.
+- `KBDB_DB_DIR` -- fallback database directory path
+  when `--db` is not specified.
 
 **Exit code:** `0` on clean shutdown, `1` on error.
 
@@ -943,6 +979,43 @@ src/cli.ts  parseArgs()
   -> 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
@@ -1658,6 +1731,13 @@ storage directory via `findDb()`.
    - 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:
@@ -1721,18 +1801,21 @@ processes the raw argument vector
    deprecation warning to stderr, and continues
    parsing.
 4. When the first positional token is `db`, `skill`,
-   or `agent`, the parser consumes the next positional
+   `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'`, etc.
+   `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`) 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[]`.
+   `--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.
@@ -1802,6 +1885,10 @@ interface CliOptions {
    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[];
 }
@@ -1883,6 +1970,10 @@ 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)
 
@@ -2114,6 +2205,8 @@ Routing table:
 | `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
@@ -2504,9 +2597,21 @@ kbdb search "machine learning" --limit 5
 
 ## Environment Variables
 
-| Variable   | Used by  | Description                |
-|------------|----------|----------------------------|
-| `KBDB_DIR` | MCP mode | Fallback database directory when `--db` is not specified. Not used in CLI mode. |
+| 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
 

package/docs/goals/content-parser.md

@@ -138,7 +138,7 @@ preserved; the caller should normalise whitespace
 if needed.
 
 This function replaces the current implementation
-in `query-parser/src/pipeline/markers.rs`. The
+in `shared/src/pipeline/markers.rs`. The
 existing `strip_content_markers()` recognizes only
 `$(image:)` and `$(code:)`. The shared version
 recognizes all six marker types.