@dikolab/kbdb 0.2.2 → 0.3.1

package/docs/goals/query-parser.md

@@ -115,9 +115,11 @@ Stages:
    decomposition).
 5. **Case folding** (lowercase).
 6. **Stop word removal** (configurable list).
-7. **Stemming** (Snowball / Porter2 -- stores both
+7. **Synonym expansion** (bidirectional synonym map --
+   inserts synonym tokens alongside originals).
+8. **Stemming** (Snowball / Porter2 -- stores both
    stemmed and original forms).
-8. **N-gram extraction** (bigrams, trigrams for phrase
+9. **N-gram extraction** (bigrams, trigrams for phrase
    indexing and multi-word term matching).
 
 `kb-worker.wasm` calls the tokenization pipeline for
@@ -126,6 +128,71 @@ and search (when a query is submitted). It feeds the
 tokenized output to `fs-database.wasm` for index
 storage or index lookups as needed.
 
+### Synonym Expansion (Stage 7)
+
+Bridges the lexical gap between user vocabulary and
+indexed content. Without synonym expansion, a search
+for `"login credentials"` returns zero results when
+the indexed document uses "signs in" and "identity"
+instead -- different root words with the same meaning.
+
+**Placement rationale:** Applied after stop-word
+removal (stage 6) and before stemming (stage 8). This
+ensures synonyms are expanded on lowercased,
+stop-word-filtered tokens, and both the original and
+synonym tokens are then stemmed consistently.
+
+**Built-in synonym map:** A small, curated
+`HashMap<String, Vec<String>>` of bidirectional
+synonym pairs. Bidirectional means if `login` maps to
+`sign-in`, then `sign-in` also maps to `login`.
+
+**Example map entries:**
+
+| Term         | Synonyms                           |
+|--------------|------------------------------------|
+| login        | sign-in, sign_in, signin           |
+| auth         | authentication, authenticate       |
+| remove       | delete, erase                      |
+| create       | add, insert                        |
+| update       | modify, change, edit               |
+| error        | exception, fault, failure          |
+| config       | configuration, settings            |
+| credential   | password, identity                 |
+| user         | account, member                    |
+| deploy       | release, publish, ship             |
+| search       | query, find, lookup                |
+| doc          | document, documentation            |
+| api          | endpoint, interface                |
+| db           | database                           |
+| env          | environment                        |
+| repo         | repository                         |
+| param        | parameter, argument                |
+| dir          | directory, folder                  |
+| msg          | message                            |
+| info         | information                        |
+
+**Expansion behaviour:** For each token in the stream,
+look up the synonym map. If found, insert the synonym
+tokens at the same position as the original. Both the
+original and its synonyms proceed to the stemming
+stage. This preserves the original token's position
+for proximity/zone scoring while adding synonym
+coverage.
+
+**Applied symmetrically:** The same synonym expansion
+applies during both `learn` (indexing) and `search`
+(querying). If a document uses "login" and the user
+searches "sign-in", the expansion during indexing
+produced "sign-in" tokens from "login", and the
+expansion during querying produced "login" tokens
+from "sign-in".
+
+**Not user-configurable in v1.** The built-in map is
+hardcoded. Future versions may allow user-defined
+synonym maps via a `synonyms.toml` configuration file
+in the `.kbdb` directory.
+
 ## Query Parsing
 
 Search queries are parsed into a structured query plan
@@ -148,8 +215,35 @@ Parsing stages:
 The query plan is the query parser's output --
 `kb-worker.wasm` receives it and passes it to
 `fs-database.wasm` for index lookups, then calls the
-query parser's ranking functions to score and order the raw
-results.
+query parser's ranking functions to score and order
+the raw results.
+
+### Relaxed Query Mode
+
+When a multi-term AND query returns zero results,
+`kb-worker.wasm` retries the query in **relaxed
+mode** -- OR semantics where any term matches, not
+all required.
+
+The query parser generates both the primary (AND)
+plan and a relaxed (OR) plan from the same parsed
+query. `kb-worker.wasm` executes the AND plan first.
+If the AND plan produces zero matches, it falls back
+to the OR plan. No new WASM export is needed --
+`qp_parse_query` returns a `QueryPlan` that supports
+mode switching via a `match_mode` field
+(`All` | `Any`).
+
+Relaxed results are flagged with `relaxed: true` in
+the `PagedSearchResult` envelope (see
+[Query Result -- Relaxed-Match
+Fallback](query-result.md)). The fallback is
+transparent to the caller.
+
+Single-term queries are unaffected (AND and OR are
+equivalent for one term). Phrase queries and
+exclusions are preserved in both modes -- only the
+inter-term combination changes.
 
 ## Query Cache
 

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/semantic-dedup.md

@@ -0,0 +1,229 @@
+# Semantic Near-Duplicate Detection
+
+*Cosine similarity on embeddings as a complementary
+detection layer alongside Jaccard -- closes the
+vocabulary-gap ceiling identified in gap #6.*
+
+## Goal
+
+The existing near-duplicate detection computes a Jaccard
+coefficient on stemmed term sets of the incoming section
+versus all indexed sections. Sections that exceed a
+similarity threshold of 0.85 are reported as
+near-duplicates in `AddSectionResult.near_duplicates`.
+
+This mechanism catches lexically similar content
+reliably. It does not catch semantically equivalent
+sections that use different vocabulary. Example: a
+section stored as "We selected PostgreSQL for its JSONB
+support" and a later section written as "Chose Postgres
+due to native JSON column type" express the same
+decision. Their stemmed term sets share few tokens --
+Jaccard produces a low score, no duplicate is flagged,
+and the knowledge base silently accumulates redundant
+content.
+
+This gap is identified as the semantic dedup ceiling in
+[Opus 4.8 Second Brain Review](../issues/2026-06-23-opus-48-second-brain-review.md)
+(gap #6). Semantic dedup closes it by adding a cosine
+similarity pass on embedding vectors as a complementary
+detection method when an embedding provider is
+configured. The feature is conditional on
+[Hybrid Search](hybrid-search.md) -- if no
+`EmbeddingProvider` is configured, only the Jaccard pass
+runs and behaviour is identical to today.
+
+## Two-Pass Detection Algorithm
+
+Detection proceeds in two sequential passes on every
+`add_section` call.
+
+### Pass 1: Jaccard (always runs)
+
+Compute the Jaccard coefficient between the incoming
+section's stemmed term set and each existing section's
+term set. The term sets are derived from the inverted
+index -- no section files are read.
+
+Sections whose Jaccard score meets or exceeds 0.85 are
+flagged as lexical near-duplicates and appended to
+`near_duplicates` with `method: "jaccard"`.
+
+Sections whose Jaccard score falls in the range
+[0.40, 0.85) -- the gray zone -- are retained as
+candidates for Pass 2.
+
+Sections with a Jaccard score below 0.40 are discarded
+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.
+
+For each gray-zone candidate from Pass 1, retrieve the
+candidate's embedding from `vectors.idx`. If the
+candidate's embedding is missing (e.g. the embedding
+provider failed when that section was learned), skip
+that candidate silently. Compute cosine similarity
+between the incoming section's embedding and the
+candidate's embedding.
+
+The incoming section's embedding is computed by the
+daemon as part of the same learn operation that triggers
+the add (see the embedding lifecycle in
+[Hybrid Search](hybrid-search.md)). If the embedding
+computation for the incoming section itself failed, Pass
+2 is skipped entirely for that call.
+
+Candidates whose cosine similarity meets or exceeds 0.92
+are flagged as semantic near-duplicates and appended to
+`near_duplicates` with `method: "cosine"`.
+
+### Efficiency Rationale
+
+Jaccard operates on integer set intersections over the
+inverted index -- it is cheap. Cosine operates on
+floating-point vector dot products and requires reading
+from `vectors.idx` -- it is more expensive. Restricting
+cosine to the gray zone (Jaccard >= 0.40) means cosine
+is invoked only for sections that already share moderate
+lexical overlap with the candidate. Sections with very
+low Jaccard scores are unlikely to be semantic
+duplicates, so skipping them avoids unnecessary work
+without meaningful loss in detection coverage.
+
+## Detection Thresholds
+
+| Method           | Threshold | Meaning                      |
+|------------------|-----------|------------------------------|
+| Jaccard          | >= 0.85   | Lexical near-duplicate       |
+| Jaccard pre-filter | >= 0.40 | Candidate for cosine pass    |
+| Cosine           | >= 0.92   | Semantic near-duplicate      |
+
+Thresholds are not configurable in v1. They are
+hardcoded constants. If operational experience shows
+that the defaults produce excessive false positives or
+false negatives, they can be exposed as `worker.toml`
+configuration keys in a later version.
+
+## Response Format
+
+The `near_duplicates` array in `AddSectionResult` gains
+a `method` field on every entry. The field identifies
+which detection pass produced the entry.
+
+```json
+{
+   "kbid": "<26-char hash>",
+   "near_duplicates": [
+      {
+         "kbid": "abc123...",
+         "similarity": 0.89,
+         "method": "jaccard"
+      },
+      {
+         "kbid": "def456...",
+         "similarity": 0.95,
+         "method": "cosine"
+      }
+   ]
+}
+```
+
+The `method` field is always present on every
+near-duplicate entry, including in responses from
+deployments where only Jaccard runs. Callers can rely
+on the field being present unconditionally.
+
+Entries produced by Pass 1 always carry `method:
+"jaccard"`. Entries produced by Pass 2 always carry
+`method: "cosine"`. No entry can carry both methods --
+a section that crosses the Jaccard threshold of 0.85
+is already flagged in Pass 1 and is not re-evaluated
+in Pass 2.
+
+## Dependency on Hybrid Search
+
+Semantic dedup reuses the infrastructure introduced by
+[Hybrid Search](hybrid-search.md) without adding any
+new infrastructure of its own.
+
+- The `EmbeddingProvider` interface defined in Hybrid
+  Search provides the embedding computation at learn
+  time.
+- `vectors.idx` provides the embedding lookup at
+  duplicate-detection time. No second embedding call is
+  made -- the stored vectors are read directly.
+- When `NullEmbeddingProvider` is active (no `[embedding]`
+  section in `worker.toml`), Pass 2 never runs. The
+  `near_duplicates` array may still contain Jaccard
+  entries; it will never contain cosine entries.
+- Stale vector index conditions (model name mismatch
+  between `vectors-meta.toml` and the configured
+  provider) are treated the same as a missing
+  `vectors.idx`: Pass 2 is skipped for that call.
+
+## Contradiction Detection Enhancement
+
+The existing `divergent_content` integrity check
+identifies sections that share the same `source_key`
+but have different content -- contradictory knowledge
+from the same origin that supersession should have
+resolved.
+
+With embeddings available, integrity check can extend
+this check to surface potential semantic contradictions
+that lack a shared source key: sections with high cosine
+similarity (>= 0.92) and conflicting content signals.
+This is a secondary, advisory output in the integrity
+check response -- it does not block any operation.
+
+The enhancement runs only when the integrity check is
+invoked and `vectors.idx` is present and not stale. It
+adds a new `semantic_contradictions` array to the
+integrity check response, alongside the existing
+`divergent_content` error entries:
+
+```json
+{
+   "semantic_contradictions": [
+      {
+         "kbid_a": "abc123...",
+         "kbid_b": "def456...",
+         "cosine_similarity": 0.94
+      }
+   ]
+}
+```
+
+When no embedding provider is configured or
+`vectors.idx` is absent, `semantic_contradictions` is
+an empty array.
+
+## Design Constraints
+
+- Semantic dedup is additive. It never replaces the
+  Jaccard pass. Both passes coexist, and the Jaccard
+  pass always runs regardless of embedding configuration.
+- The `method` field is always present on
+  `near_duplicates` entries, even in responses from
+  deployments where only Jaccard runs.
+- Cosine similarity computation reuses existing
+  embedding vectors stored in `vectors.idx`. No
+  additional embedding API call is made during
+  duplicate detection.
+- If Pass 2 is skipped (no provider, stale index, or
+  embedding failure for the incoming section), the
+  response omits cosine entries silently. No warning
+  field is added for a skipped cosine pass -- the
+  absence of cosine entries is not an error condition
+  and is expected in lexical-only deployments.
+- Thresholds are hardcoded in v1. Exposure as
+  configuration keys is deferred to a later version
+  after operational validation.
+- The `semantic_contradictions` enhancement to integrity
+  check is advisory. It does not change `ok` to `false`
+  on its own -- it provides supplementary information
+  for human review.

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