@dikolab/kbdb 0.4.0 → 0.4.3

package/docs/details/agent-tooling.md

@@ -37,6 +37,16 @@ file for your tool.
 `@dikolab/kbdb` with `deno` / `run` / `-A` /
 `jsr:@dikolab/kbdb/cli`.
 
+Environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `KBDB_DB_DIR` | Database path (replaces `--db`) |
+| `KBDB_LOG_LEVEL` | `debug`, `info`, `warning`, `error` |
+| `KBDB_NON_INTERACTIVE` | Suppress prompts (`1` / `true`) |
+| `KBDB_DAEMON_TIMEOUT` | Request timeout in ms |
+| `KBDB_RETRY` | Max retries on timeout |
+
 See the [MCP Server Guide](mcp-server.md) for
 environment variable config, multiple knowledge
 bases, and the full 20-tool reference.

package/docs/details/cli.md

@@ -21,6 +21,10 @@ deno install -Agf jsr:@dikolab/kbdb/cli
 kbdb [options]
 kbdb <command> [options] ...[parameters]
 kbdb <command> <subcommand> [options] ...[parameters]
+kbdb --version
+kbdb -v <command>          (verbose: warnings)
+kbdb -vv <command>         (verbose: info)
+kbdb -vvv <command>        (verbose: debug)
 ```
 
 ## Command Groups
@@ -74,11 +78,15 @@ docid and want rendered Markdown output.
 | Option | Short | Default | Description |
 |--------|-------|---------|-------------|
 | `--help` | `-h` | | Print help text and exit |
-| `--version` | `-v` | | Print version 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>` | | cwd | Database directory path (optional) |
 | `--format <fmt>` | `-f` | `json` (text when interactive) | Output format (`json`, `text`, `mcp`) |
 | `--timeout-ms <ms>` | | `30000` | Per-request daemon timeout in milliseconds |
 | `--retry <n>` | | `1` | Max retries with daemon respawn on timeout |
+| `--non-interactive` | | | Suppress prompts; use defaults |
 
 ### `--db <path>`
 
@@ -116,25 +124,23 @@ These options apply to the `search` command.
 | Algorithm | Description |
 |-----------|-------------|
 | `lexical` | Keyword matching with stemming and synonyms |
-| `vector` | AI-powered similarity search using embeddings (requires a configured embedding provider) |
+| `vector` | Similarity search using embeddings |
 | `hybrid` | Combines keyword and similarity results for best coverage |
 
 ### Configuring Hybrid Search
 
-Hybrid and vector search require an embedding provider.
-kbdb supports pluggable providers configured via the
-`EmbeddingConfig` interface:
+Hybrid and vector search use a built-in TF-IDF
+embedding provider by default -- no configuration
+needed. For higher quality embeddings, configure a
+provider via `worker.toml`:
 
 | Provider | Description |
 |----------|-------------|
-| `none` | No embeddings; hybrid and vector return an error |
+| *(none)* | Built-in TF-IDF (256 dimensions, works offline) |
+| `none` | Explicitly disabled; hybrid and vector return an error |
 | `onnx` | Local ONNX model (no network required) |
 | `api` | Remote embedding API (OpenAI-compatible endpoint) |
 
-When no provider is configured, `--algo hybrid` and
-`--algo vector` return an error prompting you to
-configure an embedding provider.
-
 ### Search Modes
 
 | Mode | Description |
@@ -720,6 +726,8 @@ kbdb agent delete agent-code-reviewer
 | `KBDB_DB_DIR` | CLI + MCP | cwd (CLI) / none (MCP) | Fallback database directory path when `--db` is not specified. |
 | `KBDB_DAEMON_TIMEOUT` | CLI + MCP | `30000` | Per-request daemon timeout in milliseconds. Overridden by `--timeout-ms`. |
 | `KBDB_RETRY` | CLI + MCP | `1` | Max retries with daemon respawn on timeout. Overridden by `--retry`. |
+| `KBDB_LOG_LEVEL` | CLI + MCP + Daemon | `error` | Log verbosity: `debug`, `info`, `warning`, `error`. Overridden by `-v`/`-vv`/`-vvv`. |
+| `KBDB_NON_INTERACTIVE` | CLI + MCP + Daemon | off | Suppress interactive prompts. Accepts `1` or `true`. Overridden by `--non-interactive`. |
 
 ## Exit Codes
 
@@ -738,6 +746,12 @@ Before any data command (`learn`, `unlearn`,
    prompts to create one.
 2. **No `.kbdb` found + non-interactive** -- prints
    error and exits.
+
+The `--non-interactive` flag (or
+`KBDB_NON_INTERACTIVE=1`) forces the non-interactive
+path regardless of terminal type. This is useful in
+scripts, CI pipelines, and automated testing.
+
 3. **`.kbdb` found** -- runs a version gate before
    proceeding. If migration is needed, prints an
    error directing the user to run `kbdb db migrate`.
@@ -753,9 +767,11 @@ database creation.
   modules.
 - **stdout** contains only command output. No
   banners, progress bars, or decorative text.
-- **stderr** contains only errors (and deprecation
-  warnings for the legacy `--init`/`--migrate`
-  flags).
+- **stderr** contains log messages. Default level is
+  ERROR (errors only). Use `-v`/`-vv`/`-vvv` or
+  `KBDB_LOG_LEVEL` to increase verbosity. Log lines
+  are prefixed with per-level icons (✖⚠ℹ▸) and ANSI
+  colors.
 - Works on both Deno and Node.js (>= 20).
 - The `--init` and `--migrate` flags are deprecated.
   Use `kbdb db init` and `kbdb db migrate` instead.

package/docs/details/knowledge-base.md

@@ -74,11 +74,11 @@ of creating duplicates.
 | `--algo hybrid` | hybrid | Keyword + AI similarity |
 | `--algo vector` | vector | AI similarity only |
 
-Hybrid and vector modes need an embedding provider.
-Without one, they return an error prompting you to
-configure an embedding provider.
-See the [CLI Reference](cli.md) for provider
-configuration.
+Hybrid and vector modes work out of the box using a
+built-in TF-IDF embedding provider. For higher
+quality, configure an ONNX or API provider in
+`worker.toml`. See the [CLI Reference](cli.md) for
+provider configuration.
 
 When a query returns no exact matches, kbdb
 automatically loosens the search (OR instead of AND)
@@ -159,10 +159,17 @@ two global flags:
 |------|---------|-------------|
 | `--timeout-ms <ms>` | `30000` | Per-request daemon timeout |
 | `--retry <n>` | `1` | Retries with daemon respawn on timeout |
+| `--non-interactive` | off | Suppress prompts; use defaults |
 
-These can also be set via the `KBDB_DAEMON_TIMEOUT`
-and `KBDB_RETRY` environment variables. The flags
-take priority over env vars.
+These can also be set via environment variables.
+The flags take priority over env vars.
+
+| Variable | Description |
+|----------|-------------|
+| `KBDB_DAEMON_TIMEOUT` | Per-request daemon timeout (ms) |
+| `KBDB_RETRY` | Max retry count |
+| `KBDB_LOG_LEVEL` | Log verbosity: `debug`, `info`, `warning`, `error` |
+| `KBDB_NON_INTERACTIVE` | Suppress prompts (`1` or `true`) |
 
 ## Deep Dives
 

package/docs/details/mcp-server.md

@@ -169,6 +169,20 @@ 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:
 
@@ -181,7 +195,8 @@ your MCP configuration:
          "env": {
             "KBDB_DB_DIR": "/path/to/.kbdb",
             "KBDB_DAEMON_TIMEOUT": "60000",
-            "KBDB_RETRY": "2"
+            "KBDB_RETRY": "2",
+            "KBDB_LOG_LEVEL": "warning"
          }
       }
    }

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

@@ -567,5 +567,9 @@ 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 returns an error.
+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>...
@@ -120,11 +123,15 @@ These options apply to all commands.
 | Option             | Short | Description              |
 |--------------------|-------|--------------------------|
 | `--help`           | `-h`  | Print help text and exit |
-| `--version`        | `-v`  | Print version 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`
 
@@ -139,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
@@ -1709,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:

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.

package/docs/goals/hybrid-search.md

@@ -34,8 +34,9 @@ both modes.
 ## Architecture
 
 Two retrieval paths run in parallel. The vector path
-runs entirely in TypeScript. No WASM code is added or
-modified.
+runs in TypeScript, backed by a lightweight WASM crate
+(`kbdb-default-embedding`) for the built-in TF-IDF
+provider.
 
 ```
 Query → ┌─ Lexical path (WASM) ─→ BM25F ranked list ─┐
@@ -43,12 +44,19 @@ Query → ┌─ Lexical path (WASM) ─→ BM25F ranked list ─┐
         └─ Vector path (TS)   ─→ Cosine ranked list ──┘
 ```
 
-The WASM boundary is untouched. `query-parser.wasm`
-remains a pure-computation lexical module. `kb-worker.wasm`
-continues to orchestrate lexical retrieval via
-`fs-database.wasm` exactly as today. No new WASM crate,
-no new WASM export, and no new host import is needed for
-the vector path.
+The existing WASM modules are untouched.
+`query-parser.wasm` remains a pure-computation lexical
+module. `kb-worker.wasm` continues to orchestrate
+lexical retrieval via `fs-database.wasm` exactly as
+today. No new exports or host imports are added to
+any existing WASM module.
+
+A new standalone WASM crate, `kbdb-default-embedding`,
+provides the built-in TF-IDF embedding computation.
+It depends only on `kbdb-shared` and requires no host
+imports -- pure computation. It is loaded as an
+independent WASM instance by the worker daemon
+alongside the existing three modules.
 
 The TypeScript daemon layer adds the vector path as an
 independent retrieval step that runs after the lexical
@@ -93,15 +101,29 @@ interface EmbeddingProvider {
 
 ### Implementations
 
-Three concrete implementations are specified.
+Four concrete implementations are specified.
+
+**`TfidfEmbeddingProvider`** -- lightweight built-in
+provider backed by the `kbdb-default-embedding` WASM
+crate. Computes feature-hashed sublinear TF vectors
+(256 dimensions, L2-normalized) using kbdb-shared's
+tokenization pipeline (NFC normalization, Unicode
+segmentation, camelCase splitting, stop-word removal,
+synonym expansion, Snowball stemming). This ensures
+token consistency between the lexical index and the
+TF-IDF vectors -- hybrid search fuses two views of
+the same vocabulary. The default when no `[embedding]`
+section is present in `worker.toml`. Enables hybrid
+search out of the box with zero configuration and
+zero external dependencies. Uses FNV-1a feature
+hashing with the sign trick (Weinberger et al., 2009).
+Model name: `tfidf-v1`.
 
 **`NullEmbeddingProvider`** -- no-op, returns empty
-arrays. The default when no `[embedding]` section is
-present in `worker.toml`. Requesting `vector` or
-`hybrid` search mode with this provider returns a
-structured error rather than silently returning empty
-results. Satisfies POLA: the absence of configuration
-does not silently degrade results.
+arrays. Available for explicit use but no longer the
+default. Returns 0 dimensions, which causes
+`assertProvider` to reject hybrid/vector search
+requests with a structured error.
 
 **`OnnxEmbeddingProvider`** -- local offline inference
 using ONNX Runtime. Default model: `all-MiniLM-L6-v2`
@@ -305,9 +327,12 @@ The default is `lexical`. Existing integrations that do
 not supply `search_mode` are unchanged. This is a
 strict backward-compatibility guarantee.
 
-Requesting `vector` or `hybrid` when no embedding
-provider is configured (i.e. `NullEmbeddingProvider` is
-active) returns a structured error:
+When `[embedding]` is absent from `worker.toml`, the
+`TfidfEmbeddingProvider` is active as the default.
+Hybrid and vector search work out of the box using
+feature-hashed TF vectors. If the user explicitly sets
+`provider = "none"`, `NullEmbeddingProvider` is used
+and hybrid/vector search returns a structured error:
 
 ```json
 {
@@ -320,21 +345,21 @@ active) returns a structured error:
 
 ### CLI
 
-The `search` subcommand gains an optional `--mode` flag:
+The `search` subcommand gains an optional `--algo` flag:
 
 ```
 kbdb search "database rationale"
-kbdb search --mode hybrid "database rationale"
-kbdb search --mode vector "database rationale"
+kbdb search --algo hybrid "database rationale"
+kbdb search --algo vector "database rationale"
 ```
 
-Omitting `--mode` defaults to `lexical`. The flag is
+Omitting `--algo` defaults to `lexical`. The flag is
 not shown in the short help unless an embedding provider
 is configured.
 
 ### MCP
 
-The `search` MCP tool gains an optional `mode` parameter
+The `search` MCP tool gains an optional `algo` parameter
 (string enum: `"lexical" | "vector" | "hybrid"`). The
 parameter is documented as optional in the tool schema
 with a default of `"lexical"`.
@@ -378,8 +403,10 @@ api_key_env = "KBDB_API_KEY"
 | `api_key_env` | `"KBDB_API_KEY"`     | Environment variable holding the API key |
 
 When `[embedding]` is absent from `worker.toml`,
-`provider` defaults to `"none"` and `NullEmbeddingProvider`
-is used.
+`provider` defaults to `"none"` and the built-in
+`TfidfEmbeddingProvider` is used (256-dimensional
+feature-hashed TF vectors). To fully disable
+embeddings, set `provider = "none"` explicitly.
 
 ## Fallback Behaviour
 
@@ -388,11 +415,12 @@ in the search response with a specific warning field
 rather than silently degrading.
 
 **No embedding provider configured.**
-`search_mode` defaults to `lexical`. Requesting `hybrid`
-or `vector` returns a structured error with code
-`EMBEDDING_PROVIDER_NOT_CONFIGURED`. No silent fallback
-occurs -- the caller receives an actionable error
-message.
+The built-in `TfidfEmbeddingProvider` is active by
+default, so hybrid and vector search work without
+configuration. If the user explicitly sets
+`provider = "none"`, requesting `hybrid` or `vector`
+returns a structured error with code
+`EMBEDDING_PROVIDER_NOT_CONFIGURED`.
 
 **Stale vector index (model mismatch).**
 When `vectors-meta.toml` model name does not match the
@@ -413,24 +441,25 @@ results until a rebuild is run.
 
 ## Provider Tradeoffs
 
-| Aspect        | ONNX (local)              | API (cloud)                  |
-|---------------|---------------------------|------------------------------|
-| Latency       | ~10 ms/embed              | ~100 ms/embed                |
-| Offline       | Yes                       | No                           |
-| Cost          | Free                      | Per-token                    |
-| Quality       | Good (384 dimensions)     | Excellent (1536+ dimensions) |
-| Setup         | Model download on first use | API key required            |
-| Dual runtime  | Deno + Node.js >= 20      | Deno + Node.js >= 20         |
-
-Both providers implement the same `EmbeddingProvider`
+| Aspect        | TF-IDF (built-in)         | ONNX (local)              | API (cloud)                  |
+|---------------|---------------------------|---------------------------|------------------------------|
+| Latency       | < 1 ms/embed              | ~10 ms/embed              | ~100 ms/embed                |
+| Offline       | Yes                       | Yes                       | No                           |
+| Cost          | Free                      | Free                      | Per-token                    |
+| Quality       | Adequate (256 dimensions) | Good (384 dimensions)     | Excellent (1536+ dimensions) |
+| Setup         | None (default)            | Model download on first use | API key required            |
+| Dependencies  | None                      | onnxruntime-node          | None                         |
+| Dual runtime  | Deno + Node.js >= 20      | Deno + Node.js >= 20      | Deno + Node.js >= 20         |
+
+All providers implement the same `EmbeddingProvider`
 interface. The daemon interacts only with the interface.
 
 ## Design Constraints
 
 | Constraint            | Details                                        |
 |-----------------------|------------------------------------------------|
-| WASM purity           | `query-parser.wasm` remains pure lexical computation with no I/O. No new WASM crate or export is added. |
+| WASM purity           | `query-parser.wasm` remains pure lexical computation with no I/O. A new standalone crate, `kbdb-default-embedding`, is added for TF-IDF embedding but has no host imports. Existing WASM modules are unchanged. |
 | Backward compatibility | Default `search_mode` is `lexical`. Callers that do not supply the parameter receive identical behaviour to today. |
 | File-based storage    | `vectors.idx` and `vectors-meta.toml` follow the same derived-and-rebuildable pattern as all other index files. |
 | Dual runtime          | `EmbeddingProvider` and all embedding logic must work on Deno and Node.js >= 20. No Node-specific or Deno-specific APIs in the implementation. |
-| No new WASM deps      | All new dependencies are TypeScript-side only. The WASM modules (`fs-database.wasm`, `query-parser.wasm`, `kb-worker.wasm`) are not recompiled for this feature. |
+| No new deps on existing WASM | The existing WASM modules (`fs-database.wasm`, `query-parser.wasm`, `kb-worker.wasm`) are not modified or recompiled. A new standalone module (`default-embedding.wasm`) is added, bringing the total to four WASM modules. |

package/docs/goals/mcp.md

@@ -28,7 +28,7 @@ identically.
 
 ```
 kbdb mcp [--db <path>] [--timeout-ms <ms>]
-   [--retry <n>]
+   [--retry <n>] [--non-interactive]
 ```
 
 All flags are optional. `--db` specifies the path
@@ -49,6 +49,8 @@ Resolution order:
 | `KBDB_DB_DIR`         | Fallback database directory when `--db` is not specified |
 | `KBDB_DAEMON_TIMEOUT` | Request timeout fallback (ms); default 30 000 |
 | `KBDB_RETRY`          | Retry count fallback; default 5 |
+| `KBDB_LOG_LEVEL`      | Log verbosity: `debug`, `info`, `warning`, `error` |
+| `KBDB_NON_INTERACTIVE`| Suppress prompts (`1` or `true`) |
 
 See [CLI -- Run Modes](cli.md#run-modes) for how
 the `kbdb` executable dispatches to MCP mode.

package/docs/goals/overview.md

@@ -114,7 +114,7 @@ for both the Rust engine and the TypeScript layer.
   lands in the TypeScript source tree, and gets
   bundled into `dist/`. Start here.
 - **[Rust/WASM Modules](../modules/rust/overview.md)**
-  -- Cargo workspace, 4 crates, module namespaces,
+  -- Cargo workspace, 5 crates, module namespaces,
   WASM exports/imports, size optimization, and
   testing.
 - **[TypeScript Modules](../modules/typescript/overview.md)**

package/docs/goals/query-parser.md

@@ -195,7 +195,7 @@ in the `.kbdb` directory.
 
 **Implementation status:** Synonym expansion is
 implemented in the Rust pipeline
-(`query-parser/src/pipeline/synonyms.rs`). The
+(`shared/src/pipeline/synonyms.rs`). The
 built-in map covers common technical synonyms.
 The `query-guidance` default skill complements this
 by instructing AI agents to rephrase queries with

package/docs/goals/semantic-dedup.md

@@ -58,9 +58,13 @@ with no further processing.
 
 ### Pass 2: Cosine (when embeddings available)
 
-Pass 2 runs only when an `EmbeddingProvider` other than
-`NullEmbeddingProvider` is active and
-`vectors.idx` is present and not stale.
+Pass 2 runs when the active `EmbeddingProvider` has
+non-zero dimensions and `vectors.idx` is present and
+not stale. With the built-in `TfidfEmbeddingProvider`
+as the default (256 dimensions), Pass 2 runs
+automatically without configuration. It is skipped
+only when embeddings are explicitly disabled
+(`provider = "none"` in `worker.toml`).
 
 For each gray-zone candidate from Pass 1, retrieve the
 candidate's embedding from `vectors.idx`. If the

package/docs/goals/worker-daemon.md

@@ -14,8 +14,9 @@ retrieval and caching management. It is accessible
 
 The daemon:
 
-1. Loads and compiles the `kb-worker` WASM module once
-   at startup.
+1. Loads and compiles the WASM modules once at startup
+   (`kb-worker` for database operations, `embedding`
+   for default TF-IDF vector computation).
 2. Holds indexes and content objects in an in-memory
    cache managed by the WASM module.
 3. Listens for IPC requests from worker client
@@ -299,24 +300,28 @@ the daemon:
    exists.
 7. Calls `process.exit(0)`.
 
-## WASM Module
+## WASM Modules
 
-The daemon loads a single WASM module: `kb-worker.wasm`
-(file: `kbdb_worker_bg.wasm`). This module statically
-links the `fs-database` and `query-parser` crates, so
-only one module needs to be compiled and instantiated.
+The daemon loads four WASM modules at startup. Three
+share a single `WebAssembly.Memory` and are wired
+together via imports; the fourth is a standalone
+pure-computation module.
 
 ```
-kbdb_worker_bg.wasm
-  (statically links fs-database + query-parser)
+query-parser.wasm  (standalone)
+fs-database.wasm   (standalone)
+default-embedding.wasm (standalone, no host imports)
+       ↓
+kb-worker.wasm
+  (imports query-parser + fs-database)
        ↕
   host I/O imports (TypeScript)
 ```
 
 ### WASM Module: kb-worker.wasm
 
-`kb-worker.wasm` is the single module loaded by the
-daemon. Its responsibilities:
+`kb-worker.wasm` is the orchestration module. Its
+responsibilities:
 
 - **Query orchestration** -- Parses queries, performs
   index lookups, scores and ranks results.
@@ -1523,14 +1528,20 @@ The worker daemon (`src/worker.ts` and its compiled
 `kbdb-worker.js`) ships as part of the npm/JSR package.
 No per-platform native binaries are required.
 
-The package includes one WASM module:
-
-- `kb-worker/kbdb_worker_bg.wasm` -- single module
-  that statically links the query-parser and
-  fs-database crates
-
-It is compiled from Rust via `wasm-pack` and works on
-all platforms. The daemon loads and compiles it at
-startup using the runtime's `WebAssembly` API. The
+The package includes four WASM modules:
+
+- `kb-worker/kbdb_worker_bg.wasm` -- orchestration
+  module that imports query-parser and fs-database
+- `query-parser/query_parser_bg.wasm` -- tokenization
+  and query parsing
+- `fs-database/fs_database_bg.wasm` -- filesystem
+  storage engine
+- `default-embedding/kbdb_default_embedding_bg.wasm`
+  -- built-in TF-IDF embedding (standalone, no host
+  imports)
+
+All are compiled from Rust via `wasm-pack` and work
+on all platforms. The daemon loads and compiles them
+at startup using the runtime's `WebAssembly` API. The
 daemon runs on the same runtime (Node.js or Deno) as
 the worker client that spawns it.