@dikolab/kbdb 0.2.2 → 0.3.0

package/docs/goals/query-result.md

@@ -434,6 +434,34 @@ order** (highest relevance first). Ties are broken
 by kbid lexicographic order for deterministic
 ordering.
 
+## Score Normalization
+
+Raw BM25F scores vary in magnitude across queries and
+corpora, making them difficult to interpret in
+isolation. The ranking pipeline produces a
+**normalized confidence** score alongside the raw
+score:
+
+```
+confidence = final_score / max_score_in_result_set
+```
+
+- The top-ranked result always has `confidence = 1.0`.
+- A result with half the raw score of the top result
+  has `confidence = 0.5`.
+- When the result set is empty, no normalization is
+  needed.
+
+`confidence` is a relative measure within a single
+query's result set -- it does not compare across
+different queries. Its purpose is to let the caller
+distinguish strong matches from weak tail results
+without needing to understand BM25F score magnitudes.
+
+The CLI exposes `confidence` in `SearchDisplay` for
+human inspection. The MCP projection omits it --
+result ordering is the ranking signal for AI agents.
+
 ## Result Truncation and Pagination
 
 After sorting, results are windowed by `offset` and
@@ -452,6 +480,7 @@ interface PagedSearchResult {
    offset: number;
    limit: number;
    has_more: boolean;
+   relaxed: boolean;
 }
 ```
 
@@ -462,6 +491,7 @@ interface PagedSearchResult {
 | `offset`   | Echo of requested offset (or 0)   |
 | `limit`    | Echo of effective limit (or 20)   |
 | `has_more` | `true` when `offset + items.length < total` |
+| `relaxed`  | `true` when results came from relaxed-match fallback (see below) |
 
 `has_more` is a convenience boolean so the caller
 does not need to compute whether more pages exist.
@@ -489,14 +519,26 @@ interface SectionMatch {
    type: string;
    heading: string;
    score: number;
+   confidence: number;
    snippet: string;
    matched_terms: string[];
+   matched_fields: string[];
+   created_at: string;
 }
 ```
 
 `heading` is `string | null` -- `null` when the
-section has no title. `snippet` is always populated
-for text and code sections using KWIC
+section has no title. `confidence` is the normalized
+score (0.0--1.0) relative to the top result (see
+Score Normalization above). `matched_fields` is a
+subset of `["heading", "body", "code"]` indicating
+which fields contained term matches -- lets the
+caller see whether the match was in a title vs body
+text. `created_at` is the section's ISO 8601
+creation timestamp.
+
+`snippet` is always populated for text and code
+sections using KWIC
 (keyword-in-context): ~150 characters centered on
 the highest-scoring matched term position, with
 `...` ellipsis at boundaries. If the best match is
@@ -576,17 +618,25 @@ interface McpSearchResult {
    docids: string[];
    snippet: string;
    matched_terms: string[];
+   matched_fields: string[];
+   created_at: string;
    content?: string;
 }
 ```
 
-The `score` field from `SectionMatch` is
-intentionally omitted. Results are ordered by
-relevance descending; the position in the array
-is the ranking signal. Exposing uncalibrated BM25F
-scores provides no actionable information to the
-agent and risks confusing score magnitudes across
-different queries.
+The `score` and `confidence` fields from
+`SectionMatch` are intentionally omitted. Results
+are ordered by relevance descending; the position
+in the array is the ranking signal. Exposing
+uncalibrated BM25F scores provides no actionable
+information to the agent and risks confusing score
+magnitudes across different queries.
+
+`matched_fields` is included because it tells the
+agent whether the match was in a heading (strong
+topical signal) vs body text (weaker). `created_at`
+is included to let agents prefer recent results
+when multiple sections cover the same topic.
 
 `matched_terms` is a flat `string[]` of the query
 terms that matched -- no per-term frequency counts.
@@ -609,7 +659,40 @@ inspection and debugging.
 
 The MCP result uses the same `PagedSearchResult`
 envelope with `items`, `total`, `offset`, `limit`,
-and `has_more`.
+`has_more`, and `relaxed`.
+
+## Relaxed-Match Fallback
+
+When the primary query (implicit AND -- all terms
+required) returns **zero results**, the ranking
+engine automatically retries with relaxed matching:
+
+1. **OR mode** -- any query term may match, not all
+   required. The query plan is re-executed with OR
+   semantics using the same tokenized terms.
+
+2. Results from the relaxed retry are flagged:
+   `relaxed: true` in the `PagedSearchResult`
+   envelope. Normal (AND) results have
+   `relaxed: false`.
+
+Relaxed mode is transparent to the caller -- no
+special syntax or parameters are needed. The engine
+tries AND first and falls back to OR only when AND
+produces zero matches. This converts a silent miss
+("nothing found") into a soft hit ("weaker matches
+found") that the caller can reason about.
+
+The AI agent (or human user) can check the `relaxed`
+flag to know that the results are partial-term
+matches rather than full-term matches. Relaxed
+results typically have lower relevance -- the
+ordering and confidence scores still reflect relative
+quality within the relaxed set.
+
+When the primary AND query returns at least one
+result, no fallback is attempted. The `relaxed` flag
+is always `false` for non-empty AND results.
 
 ## References Resolution
 
@@ -691,3 +774,87 @@ of the ranking coin:
 
 See [Query Parser](query-parser.md) for the full
 tokenization pipeline and extraction algorithms.
+
+## Content Authoring Best Practices
+
+### How Field Weights Affect Searchability
+
+kbdb uses three weighted fields for ranking (see
+the [Field Weight Mapping](#field-weight-mapping)
+table above). Content authors can influence how
+well their content is found by understanding these
+weights:
+
+- **Title / heading text** carries **2.0x** the
+  ranking weight of body text. A match in a heading
+  has twice the influence on ranking as the same
+  match in the body.
+- **Code blocks** carry **1.5x** weight. Code
+  identifiers (function names, variable names, class
+  names) are split on camelCase/snake_case boundaries
+  and indexed as separate terms.
+- **Body text and descriptions** are the baseline at
+  **1.0x**.
+- **Binary content** (images, attachments) is not
+  indexed at all -- searchability depends entirely on
+  the `title` (required) and `description` (optional)
+  attributes.
+
+### Writing Index-Friendly Headings
+
+The heading is the single highest-impact field for
+searchability. Follow these guidelines:
+
+- Use **descriptive, keyword-rich headings**. Prefer
+  "Authentication and Login Flow" over just "Auth
+  Flow" -- the expanded heading gives the search
+  engine more term surface.
+- Include **synonyms and alternative phrasing** in
+  headings when natural. If a section covers logging
+  in, mention both "login" and "sign-in" if
+  applicable.
+- Avoid generic headings like "Overview",
+  "Introduction", or "Notes" that carry no
+  discriminative value for search.
+- Stemming is automatic ("connections" matches
+  "connect"), but different root words are NOT
+  equivalent without synonym expansion --
+  "login" does not match "sign-in" by default.
+
+### Structuring Content for Recall
+
+Content structure affects the progressive context
+expansion provided by the `recall` command:
+
+- Place the most important terms in the **first 20%**
+  of a section. The zone scoring algorithm gives
+  extra weight to terms in this heading zone.
+- Use explicit cross-references (`$(link:kbid)`
+  markers) between related sections. The reference
+  graph enables progressive context expansion via
+  `recall` at depth 1+.
+- Group related sections into documents. The `recall`
+  command at depth 2+ returns sibling sections,
+  giving AI agents full surrounding context.
+- For code sections: use meaningful identifiers.
+  camelCase and snake_case names are automatically
+  split and indexed. `getUserById` produces four
+  searchable terms: "get", "user", "by", "id".
+
+### Leveraging the Query Syntax
+
+Guidance for AI agents and human users on writing
+effective queries:
+
+- Use **multiple short keyword queries** rather than
+  one long natural-language question. Lexical search
+  matches on token overlap, not semantic meaning.
+- Use **exact phrases** (`"error handling"`) when term
+  order matters.
+- Use **boolean operators** (`auth AND token`,
+  `cache OR redis`) to broaden or narrow results.
+- Use **term exclusion** (`auth -oauth`) to filter out
+  irrelevant matches.
+- After finding results with `search`, use `recall`
+  with increasing depth to progressively expand
+  context.

package/docs/goals/skills.md

@@ -719,12 +719,84 @@ dangling kbid. The agent is not deleted. See
 [Agents](agents.md) for how dangling references are
 handled at retrieval time.
 
+## Default Skills
+
+### Overview
+
+When a new database is created via `kbdb db init`, a
+set of default skills are automatically installed.
+These skills provide baseline capabilities that
+improve AI agent effectiveness. Default skills are
+stored as regular skill sections (no special treatment
+in the engine) and can be deleted by users if not
+needed.
+
+### `query-guidance` Default Skill
+
+A built-in skill that teaches AI agents how to
+effectively search the knowledge base. This addresses
+the limitation that lexical search requires
+disciplined query generation for good recall.
+
+**Skill definition:**
+
+```json
+{
+   "name": "query-guidance",
+   "description": "How to effectively search this knowledge base. Read this before issuing search queries.",
+   "arguments": [],
+   "body": "This knowledge base uses lexical search (stemmed BM25F), not semantic/vector search. Follow these guidelines for effective retrieval:\n\n1. Issue MULTIPLE short keyword queries rather than one long natural-language question. Each query should target 2-3 specific terms.\n\n2. EXPAND SYNONYMS yourself. \"login\" will not match \"sign-in\" unless both terms appear in the content. Try alternative phrasings: search for \"login\", then \"sign-in\", then \"authentication\".\n\n3. USE BOOLEAN AND PHRASE SYNTAX:\n   - Exact phrases: \"error handling\"\n   - Boolean AND: auth AND token\n   - Boolean OR: cache OR redis\n   - Exclusion: auth -oauth\n\n4. LEAN ON HEADINGS. Headings carry 2x weight in ranking. Search for terms that are likely in section titles.\n\n5. STEMMING IS AUTOMATIC. \"connections\" matches \"connect\", \"running\" matches \"run\". You do not need to try inflected forms.\n\n6. USE RECALL AFTER SEARCH. After finding relevant sections with search, use recall with increasing depth (0-3) to progressively expand context: depth 0 = full content, depth 1 = parent documents + back-references, depth 2 = siblings + forward references, depth 3 = referenced sections.\n\n7. CODE IDENTIFIERS ARE SPLIT. camelCase and snake_case names are decomposed: getUserById becomes searchable as \"get\", \"user\", \"by\", \"id\".\n\n8. PAGINATION. Default limit is 20 results. Use offset for additional pages if total > limit."
+}
+```
+
+### Installation Behaviour
+
+Default skills are installed during `kbdb db init`.
+The `runDbInit` function installs each default skill
+via `client.addSection({ sectionType: 'skill', ... })`
+after creating the database scaffold.
+
+Default skills receive kbids via the same
+content-addressing scheme as user-created skills.
+Re-running `db init` on a fresh database produces
+identical kbids for the same default skill content.
+
+### `memory-protocol` Default Skill
+
+A built-in skill that teaches AI agents *when* and
+*what* to store in the knowledge base. This addresses
+the risk of the brain filling with transient junk or
+failing to capture durable facts.
+
+**Skill definition:**
+
+```json
+{
+   "name": "memory-protocol",
+   "description": "Guidelines for what to store in this knowledge base and when. Read this before using the learn tool.",
+   "arguments": [],
+   "body": "Follow these guidelines to keep the knowledge base accurate and useful:\n\n1. STORE DURABLE FACTS: decisions, architecture choices, configuration values, corrections to prior knowledge, API contracts, and resolved incidents. These are the facts that matter weeks later.\n\n2. DO NOT STORE: transient conversation context, debugging output, ephemeral task state, raw log dumps, or information that changes every session. The brain should contain knowledge, not activity logs.\n\n3. SEARCH BEFORE STORING. Always search the knowledge base before adding new content. If a section already covers the topic, use learn with --replace to update it rather than creating a duplicate.\n\n4. USE --replace FOR CORRECTIONS. When a fact changes (e.g., rate limit updated from 100 to 200 req/min), re-learn the corrected content with --replace so the old version is superseded. Without --replace, both the old and new versions coexist with equal ranking.\n\n5. ATTACH TAGS for scoping. Use tags like project name, domain, or topic (e.g., --tags auth,api,v2) so queries can be filtered by scope later.\n\n6. PREFER RECENT RESULTS. When search returns multiple sections covering the same topic, prefer the one with the most recent created_at timestamp -- it is more likely to reflect the current state.\n\n7. USE RECALL AFTER SEARCH. After finding relevant sections, use recall with increasing depth (0-3) to expand context progressively before making decisions.\n\n8. INCLUDE HEADINGS. Always provide a descriptive title when storing content. Headings carry 2x ranking weight -- omitting them significantly reduces searchability."
+}
+```
+
+### Future Default Skills
+
+Additional default skills may be added in future
+versions (e.g. `content-authoring-tips`,
+`search-syntax-reference`). Each follows the same
+installation pattern and is a regular skill section.
+
 ## Design Constraints
 
 - **Skills are plain sections.** No separate entity
   type, storage schema, or index is introduced. Skills
   use `sectionType = 'skill'` within the existing
   section infrastructure.
+- **Default skills are regular sections.** They use
+  the same storage, indexing, and retrieval
+  infrastructure. There is no distinction between a
+  default skill and a user-created skill beyond the
+  installation source.
 - **No skill versioning.** Updating a skill means
   creating a new skill section (new kbid) and
   optionally deleting the old one. The kbid changes

package/docs/goals/worker-daemon.md

@@ -107,6 +107,34 @@ Each database directory is an independent context with
 its own daemon, its own cache, and its own WASM module
 instance. There is no shared state across contexts.
 
+## Write Serialization
+
+The daemon serializes write operations using an
+exclusive file lock on `kbdb-{ctx}.lock` in the OS
+temporary directory. The lock file uses the same
+context ID as the PID file and IPC socket.
+
+- **Read operations** proceed without acquiring the
+  lock. Concurrent reads are fully parallel.
+- **Write operations** acquire the exclusive lock
+  before calling the WASM write export. If another
+  write is already in progress, the new write queues
+  behind the lock and waits.
+- **Lock duration** -- the lock is held only for the
+  duration of the single write operation and released
+  immediately after it completes. It is not held
+  across multiple operations or across client
+  connections.
+
+This serialization model is equivalent to SQLite's
+default locking: readers never block, and writers
+take turns one at a time.
+
+Write methods subject to this lock are:
+`addSection`, `updateSection`, `removeSection`,
+`groupSections`, `removeGrouping`, `initDirectory`,
+`gc`, and `rebuildIndexes`.
+
 ## Daemon Startup
 
 When the worker client spawns a new daemon (see
@@ -127,15 +155,23 @@ daemon process performs the following startup sequence:
    module (see WASM Module below).
 5. Calls `worker_init` on the WASM module to open the
    database context.
-6. Writes its PID to `kbdb-{ctx}.pid` in the OS
+6. Calls `db_check_integrity` on the WASM module to
+   run a startup health check. If `ok` is false, the
+   daemon logs a structured warning to stderr listing
+   the error count and error types. The daemon
+   continues operating -- health issues are not fatal
+   to startup. The health status (`integrity_ok`,
+   `integrity_errors`) is included in subsequent
+   `status` responses.
+7. Writes its PID to `kbdb-{ctx}.pid` in the OS
    temporary directory.
-7. Creates the IPC socket (`kbdb-{ctx}.sock` on Unix,
+8. Creates the IPC socket (`kbdb-{ctx}.sock` on Unix,
    named pipe on Windows).
-8. Begins listening for connections.
+9. Begins listening for connections.
 
 The daemon only writes its PID file and creates the
 IPC socket after all preconditions pass and the WASM
-module is loaded. If the daemon exits before step 6,
+module is loaded. If the daemon exits before step 7,
 the worker client's PID-file poll times out, and the
 worker client reads the crash log (or the daemon's
 stderr) to report the failure reason.
@@ -494,6 +530,7 @@ for each WASM operation:
 | `listByType`, `list_by_type`            | `worker_list_by_type`    |
 | `listDocumentsByType`                   | `worker_list_docs_by_type` |
 | `recall`                                | `worker_recall`          |
+| `export`                                | `db_export`              |
 
 `migrateDatabase` is listed in the map but throws
 `IpcError(-32601, 'migrateDatabase is not yet
@@ -520,12 +557,22 @@ Returns the daemon's current state.
 // Response
 {
    "jsonrpc": "2.0", "id": 1,
-   "result": "busy"
+   "result": {
+      "state": "busy",
+      "integrity_ok": true,
+      "integrity_errors": []
+   }
 }
 ```
 
-Result: `"busy"` if the connection count is greater
-than zero, `"idle"` otherwise.
+Result fields:
+
+| Field              | Type     | Description                               |
+|--------------------|----------|-------------------------------------------|
+| `state`            | string   | `"busy"` if connections > 0, else `"idle"` |
+| `integrity_ok`     | boolean  | `true` if startup health check passed     |
+| `integrity_errors` | string[] | Error types from `db_check_integrity`;    |
+|                    |          | empty when `integrity_ok` is `true`       |
 
 ### `idle_at`
 

package/docs/modules/rust/fs-database/functions/integrity.md

@@ -44,12 +44,23 @@ pub fn rebuild_indexes()
     manifest must exist.
 - Detect circular references in `$(text:)` and
   `$(document:)` marker chains.
+- Detect **divergent content**: sections sharing the
+  same `source_key` that have different content.
+  Indicates contradictory versions that should be
+  resolved via supersession. Reported as
+  `divergent_content` entries in `IntegrityReport`.
 
 ### `garbage_collect`
 
 Remove section files not referenced by any document
 manifest. Returns the number of removed files.
 
+Also reports `stale_sources` -- an advisory count of
+sections whose `source_path` points to a file that no
+longer contains their heading text. Stale sections
+are not automatically removed (they may still be
+referenced by documents); the count is informational.
+
 ### `rebuild_indexes`
 
 Reconstruct all index files (`terms.idx`,

package/docs/modules/rust/fs-database/functions/section.md

@@ -30,17 +30,34 @@ pub fn remove_section(kbid: &KbId)
 ### `add_section`
 
 1. Compute kb-id from content via `compute_kbid`.
-2. Create shard directory if needed (`host_mkdir`).
-3. Serialize TOML header + `---` separator + body.
+2. **Supersession check**: if `source_key` is
+   provided and a section with the same `source_key`
+   already exists, set `supersedes` to the old
+   section's kbid, set `updated_at` to the current
+   timestamp, remove the old kbid from document
+   manifests, and mark the old section for GC. The
+   new section replaces the old one as the current
+   version.
+3. Create shard directory if needed (`host_mkdir`).
+4. Serialize TOML header + `---` separator + body.
    TOML header includes: kbid, docids, section_type,
    title, description, size, created_at, checksum,
    token_count, heading_token_count,
-   body_token_count, code_token_count.
-4. Write atomically via `atomic_write`.
-5. Update catalog via `increment_sections(1)`.
+   body_token_count, code_token_count, source_key,
+   source_path, source_mtime, updated_at, tags,
+   supersedes.
+5. Write atomically via `atomic_write`.
+6. **Near-duplicate detection**: compute Jaccard
+   coefficient on stemmed term sets against existing
+   sections. Sections with similarity >= 0.85 are
+   reported as `near_duplicates` in the result
+   (advisory, not a block).
+7. Update catalog via `increment_sections(1)`.
 
 Validation: image sections (`image/*` type) require
-a `title` in `AddSectionParams`.
+a `title` in `AddSectionParams`. Text sections
+without a `title` emit a `heading_missing` warning
+in the result.
 
 ### `update_section`
 

package/docs/modules/rust/fs-database/module.md

@@ -120,6 +120,7 @@ engine/crates/fs-database/
 | `db_status`            | Return database metadata   |
 | `db_check_integrity`   | Run integrity checks       |
 | `db_garbage_collect`   | Remove orphaned sections   |
+| `db_export`            | Export database snapshot    |
 | `alloc` / `free`       | Memory management (from `kbdb-shared`) |
 
 ## Dependencies

package/docs/modules/rust/fs-database/types/section.md

@@ -26,6 +26,12 @@ pub struct SectionHeader {
    pub heading_token_count: u32,
    pub body_token_count: u32,
    pub code_token_count: u32,
+   pub source_key: Option<String>,
+   pub source_path: Option<String>,
+   pub source_mtime: Option<String>,
+   pub updated_at: Option<String>,
+   pub tags: Vec<String>,
+   pub supersedes: Option<KbId>,
 }
 ```
 
@@ -43,6 +49,21 @@ and stored in the header for query-time retrieval.
 See [FieldTokenCounts](../../shared/query/types.md)
 for the shared struct.
 
+`source_key` is a stable logical identity derived
+from `sha256("${source_path}\0${heading}")`,
+truncated to 16 hex chars. Separate from `kbid`
+(content hash) -- identifies *what the section is
+about* rather than *what it currently says*. `null`
+for stdin input. `source_path` is the original file
+path that was learned. `source_mtime` is the ISO 8601
+modified time of the source file at learn time.
+`updated_at` is the ISO 8601 timestamp of the last
+supersession (`null` on first create). `tags` are
+user-supplied strings for scoping and filtering.
+`supersedes` is the kbid of the section this one
+replaced (`null` on first create). See
+[Database -- Logical Identity](../../../goals/database.md).
+
 ### `IntegrityReport`
 
 ```rust
@@ -53,6 +74,7 @@ pub struct IntegrityReport {
    pub broken_refs: Vec<(KbId, String, KbId)>,
    pub type_mismatches: Vec<(KbId, String, KbId)>,
    pub circular_refs: Vec<(KbId, Vec<KbId>)>,
+   pub divergent_content: Vec<(String, Vec<KbId>)>,
 }
 ```
 
@@ -64,7 +86,11 @@ covering all six marker types (`text`, `code`,
 target_kbid)` where the target section type does
 not match the marker type. `circular_refs` are
 `(start_kbid, cycle_path)` for reference chains
-that form loops.
+that form loops. `divergent_content` entries are
+`(source_key, conflicting_kbids)` -- sections
+sharing the same `source_key` that have different
+content, indicating contradictory versions that
+should be resolved via supersession.
 
 ## Functions
 

package/docs/modules/rust/overview.md

@@ -266,7 +266,7 @@ engine/crates/query-parser/
     ├── lib.rs               ← WASM exports
     ├── mem.rs               ← shared-memory helpers
     │
-    ├── pipeline/            ← 8-stage tokenizer
+    ├── pipeline/            ← 9-stage tokenizer
     │   ├── mod.rs
     │   ├── markers.rs
     │   ├── unicode.rs
@@ -274,6 +274,7 @@ engine/crates/query-parser/
     │   ├── identifiers.rs
     │   ├── case.rs
     │   ├── stopwords.rs
+    │   ├── synonyms.rs
     │   ├── stem.rs
     │   └── ngram.rs
     │

package/docs/modules/rust/query-parser/functions/module.md

@@ -5,9 +5,9 @@ extraction, and ranking.*
 
 ## Modules
 
-- **[pipeline](pipeline.md)** -- 8-stage tokenization
+- **[pipeline](pipeline.md)** -- 9-stage tokenization
   pipeline. Converts raw text into normalized, stemmed
-  tokens with n-grams.
+  tokens with synonym expansion and n-grams.
 - **[parse](parse.md)** -- Query string parsing into
   structured `QueryPlan`.
 - **[extract](extract.md)** -- RAKE keyphrase

package/docs/modules/rust/query-parser/functions/pipeline.md

@@ -1,8 +1,8 @@
 # functions::pipeline -- Tokenization Pipeline
 
-*8-stage pipeline that converts raw text into
-normalized, stemmed tokens. Used for both indexing
-and query processing.*
+*9-stage pipeline that converts raw text into
+normalized, stemmed tokens with synonym expansion.
+Used for both indexing and query processing.*
 
 ## Source
 
@@ -14,7 +14,7 @@ and query processing.*
 pub fn tokenize(input: &str) -> TokenStream;
 ```
 
-Runs all eight stages in sequence. Each stage is a
+Runs all nine stages in sequence. Each stage is a
 pure function.
 
 ## Stages
@@ -83,7 +83,32 @@ pub fn remove_stop_words(
 Filters common function words. Single-character
 tokens also removed.
 
-### 7. Stemming (`stem.rs`)
+### 7. Synonym Expansion (`synonyms.rs`)
+
+```rust
+pub fn expand_synonyms(
+   word: &str,
+   map: &SynonymMap,
+) -> Vec<String>;
+```
+
+Looks up the lowercased word in the built-in synonym
+map. Returns a vector containing the original word
+plus any synonyms. When no synonyms exist, returns a
+single-element vector containing only the original.
+
+The synonym map is a bidirectional
+`HashMap<String, Vec<String>>` built at compile time.
+Expansion is applied after stop-word removal and
+before stemming, so both original and synonym tokens
+are stemmed consistently.
+
+The map is small (~30-50 entries) and focused on
+common IT/development vocabulary mismatches:
+login/sign-in, auth/authentication, remove/delete,
+config/configuration, credential/password, etc.
+
+### 8. Stemming (`stem.rs`)
 
 ```rust
 pub fn stem_word(word: &str) -> StemResult;
@@ -92,7 +117,7 @@ pub fn stem_word(word: &str) -> StemResult;
 Snowball / Porter2. Preserves both original and
 stemmed forms.
 
-### 8. N-gram Extraction (`ngram.rs`)
+### 9. N-gram Extraction (`ngram.rs`)
 
 ```rust
 pub fn extract_ngrams(
@@ -101,3 +126,16 @@ pub fn extract_ngrams(
 ```
 
 Bigrams and trigrams for phrase indexing.
+
+## Relaxed Query Mode
+
+The tokenization pipeline is used for both the
+primary AND-mode query plan and the relaxed OR-mode
+fallback plan. `qp_parse_query` produces a
+`QueryPlan` with a `match_mode` field (`All` | `Any`).
+When the AND plan returns zero matches,
+`kb-worker.wasm` retries with the OR plan using the
+same tokenized terms. No additional pipeline stage or
+WASM export is needed. See
+[Query Parser -- Relaxed Query
+Mode](../../../goals/query-parser.md).