# Knowledge vault — router This repo is a flat Obsidian vault, read on the reader's behalf. What it's about, what a note is, how links resolve, and who may write what live in one place: [`meta/contract.md`](meta/contract.md) — read it before writing anything. This file is the **router**: establish what brings the user, then follow the **ask** path (read the vault and answer) or the **contribute** path (help them add to it). --- ## Step 0 — first run If `meta/contract.md` is missing, the vault isn't initialized. Conduct the **identity interview** in the main session with `AskUserQuestion` (the agents can't ask questions): 1. What is this vault called, and what is it about? (one sentence) 2. Who reads it? Up to four reader types — for each: a short name, what they come for, and a default answer depth (crisp / working / deep). 3. What do readers come to do? 3–6 "I want to…" intents for the front-door lanes. Then dispatch the **kb-init** agent with the answers verbatim, and continue once it hands back. --- ## Opening — establish path and reader Establish two things from the **first message** when it already says them; interview only for what's missing: - **Path.** A question → *ask*. Something to add ("here are my notes from…", "we decided X") → *contribute*. A blank arrival ("hi", just looking around) → ask both questions with `AskUserQuestion`: what brings them (ask / contribute), and which reader type from `meta/genres/` fits. - **Genre** is a soft prior on the reader, never a gate: consult the matching `meta/genres/` template when the genre is known, use plain working depth when it isn't, and ask at most once — only when the depth of the answer genuinely turns on it. Carry both through the session; don't re-interview on follow-ups. --- ## The ask path — read-only The only write on this path is the session log. **Never edit a note.** 1. **Enter** via [`meta/index.md`](meta/index.md) — the lane matching the question's intent — and the genre template's "Start from" pointers. 2. **Search before declaring anything missing.** Grep the whole vault for the question's terms. Found by search but not reachable from the lanes → that's a **navigation gap** (the knowledge exists; the paths don't) — say so in the log. Truly absent → a **content gap**. 3. **Traverse** the `[[wikilinks]]` both ways — up toward summaries, down into detail. Lead with `canonical` notes; `canonical: false` is background. A `visibility: hidden` note may inform an answer only with explicit disclosure — never present it as the vault's position to an external-facing reader. 4. **Synthesize** at the genre's default depth, then follow the asker — deeper when they reach, compressed when they want the headline. Depth shapes the answer, never which notes exist. 5. **Cite** the notes used. Before citing, check `meta/proposals/` for `status: open` items flagging those notes (stale, superseded, collision) — disclose any flag. 6. **Log the session** to `meta/sessions/` per its README — honestly, including whether the vault could answer. Only a search-verified miss is logged as a gap. If the vault can't answer, say so plainly and log it. **Never invent an answer the notes don't support.** **"Where is the knowledge gap?"** is a deliberate ask for the coverage goal, not a side effect: answer instantly from [`meta/gaps.md`](meta/gaps.md); if the ledger is stale against the vault (notes or sessions committed since it last changed) or the user wants a live sweep, dispatch **kb-audit** scoped to coverage and relay the refreshed ledger. ## The contribute path — the human steers The user is adding knowledge. Drafting and placement happen here; the human decides. Every write is theirs, and every write is a git commit. 1. **Orient** with `meta/contract.md` (the note model, where things belong) and the target folder's `Readme.md`. For "what does the vault want next?", read `meta/gaps.md` and any unprocessed session logs. 2. **Check for a rival before placing.** Search for an existing note on the topic. One exists → the human picks: extend it, supersede it (demote the old to `canonical: false` **in the same commit**), or link the new note as background. 3. **Draft per the contract** — one idea per note, light frontmatter, linked to its neighbours. Links form during drafting. --- ## Upkeep — deliberate, never a side effect - **kb-audit** (six goals: coverage, descriptions, freshness, graph, entrances, shape) audits and writes a **proposal** to `meta/proposals/` plus the gap ledger — never canon. Run it when asked, whole or scoped. - **kb-apply** executes exactly one human-reviewed proposal — the only agent that writes canon. **Never run it unprompted.** - The derived graph `meta/_derived/graph.json` is regenerated by `node .claude/scripts/kb-export.mjs` — never hand-edited, by anyone. Everything is git-checked-in: any write is reviewable and reversible. When anything here seems to conflict with `meta/contract.md`, the contract wins. ## Delegation Governs sub-agent dispatch — when to fan out, at what tier, how far to trust the result. No dispatch mechanism ⇒ inline. - **Delegate bulk vault work.** Whole-vault greps, multi-note traversals, corpus sweeps, and audits (`kb-audit`, `kb-init`) are self-contained hand-offs that cost less than doing them in the main session — a sub-agent's raw output dies with it, while the same output read inline is re-read and re-billed on every later turn. Independent sweeps run in parallel. - **Small or judgment work stays inline** — a handful of tool calls, a single note's placement call (extend / supersede / background). Judgment is never delegated by reflex: a second opinion is for a high-stakes call or an explicit request. - **A delegated result is a report, not verifiable ground truth** — a citation or claim drawn from a sub-agent's findings still resolves to the actual note before it reaches the user. - **Tiers**: mechanical fan-out (sweeps, grep passes, batch classification) runs on the cheapest capable tier; judgment-heavy delegation (audit synthesis, proposal drafting) runs on the standard tier; the strongest tier only on explicit user request. - **An explicit user directive about tier, cost, or delegation overrides this section.**