How It Works: Retrieval & Delivery
Once knowledge is in the fabric, two commands make it useful — and both are deterministic: no LLM, no API bill, no hallucinated summaries. This page tells the story of a question and a task moving through them.
Query: the question with a citation
An agent (or you) asks: "Why does the write path batch?" Four layers run:
1. Type detection. The question is routed by intent — verify questions boost claims and locators, decision questions boost decisions and experience events, gap questions surface open questions and contradictions, and changed questions (#189) get the temporal axis: capture-date is the ranking (keyword match stays the candidate filter) and the answer renders as an ordered evolution — earliest state → latest, each step with its locator, contested entries flagged. Type is auto-detected or forced with --type.
2. Lexical scoring. Every page scores by concept overlap — words are normalized and stemmed (rotation matches rotating), so morphological variants still match. Pure string operations.
3. Graph expansion. Pages aren't scored in isolation: a claim that supports or contradicts another claim pulls its neighbor in; with the graphify integration, call/import edges also surface code-reachable claims (ranking boost + a symbol-discovery tier for lexically-invisible claims).
3b. Provenance (the evidence graph). With a thread index present (registry/threads.json, derived at rebuild), lineage-shaped queries ("where did this come from?") gain a Lineage section: which session or PR each top claim came from, with the files those sessions touched. wf thread <session-or-claim-id> is the deterministic audit surface — claims citing the node, files touched, continuation edges. Provenance is display only: never ranked above lexical evidence, never scored into truth.
4. Structured answer. The result isn't prose soup — it's bottom line / evidence / caveats / confidence / next action, and every evidence item links to the locator you can open and verify yourself.
When an answer is worth keeping, --save files it as a synthesis page — the query result promoted to a citable page.
Context compilation: precedence at work
wf context is the delivery end of the same machinery — scoring, scope precedence (project > domain > global), status/freshness filtering, and per-item reasons. The full contract — manifest guarantees, receipts, commitments surfacing, code navigation — has its own deep-dive: Task Context.
Why deterministic matters
Retrieval that costs tokens gets rationed; agents stop asking questions when questions cost money. Deterministic retrieval inverts that: asking is free, so agents ask constantly, and every answer is auditable after the fact — the same input always produces the same manifest, which is exactly what a regression gate needs.
Optional layers (off by default)
Three optional additions sit on top of this deterministic base — see Integrations — each has its own deep page —: the semantic re-rank boost (integrations.embeddings, top-40 fusion), the System One fusion rerank (a local decision model — ollama's /v1/systemone, Tev/Nimble-class — judging which top-k lexical candidates actually answer the question; latency-budgeted ~2s, silent fall-back to lexical order when disabled or unreachable), and the judged borderline re-rank (wf context --judge-borderline). All self-report in the output when active; the deterministic base never requires them. A decision model is a judge — it never writes content, and humans still gate every merge.
The human layer stays out of the machine context
wf query and wf context retrieve only atoms — claims, patterns, decisions, concepts, experience events — never the generated human layer. wiki/ topics and syntheses/ are OpenWiki-style paraphrases of claims: their prose is for humans to read, not for a model to re-ingest (which would be context bloat plus drift risk). Both retrieval surfaces skip wiki/ and syntheses/.
The wiki still gives the machine real value, but through its derived edges, not its prose: wf export wiki writes registry/wiki-graph.json — the topic/project → claim citation edges with staleness tiers and claim provenance, as deterministic JSON alongside catalog.json. A model or agent that wants the wiki's aggregation reads the graph for edges and cites the claim for the content. Prose is read by people; edges are read by machines.
The human exploration surface
For people, wf export wiki enriches every generated page with consistent, OpenWiki-style anatomy — a SUMMARY: lead, a deterministic ## Key Takeaways (from the page's own top-tier claims, never hallucinated), a ## Sources backtrace to the cited claims, a generated: {by, at} provenance stamp, and validated/auto-repaired Mermaid diagrams. Explore the resulting [[wikilinks]] in Obsidian's native Graph view — it renders the topic↔topic↔project network. No separate HTML viewer is shipped; Obsidian is the human graph surface.
Delta-mode refresh (#187). Regeneration is signature-gated: each article's generation inputs (mode + the tier-classified claim files' hashes + a project page's decisions) hash into an input signature, recorded in the wiki-export manifest's inputs: section. An article whose inputs are unchanged is left byte-identical — 0 tokens, and it survives the reconcile that precedes generation. Changed inputs get a delta prompt (the previous article + the new/removed claims) whose section edits are spliced mechanically: the model names headings and bodies; the code decides placement, and preamble/tail sections pass through verbatim from disk — the model never edits what it cannot name. The Hindsight lesson this encodes: told to "preserve the unchanged parts" a generative model will still drift (bullets become numbers, casing shifts) — untouched text must come from the previous FILE, never from the model's re-emission. --full forces wholesale regeneration; --check (0 tokens) reports unchanged / regenerable-stale / never-generated. Human wiki edits keep winning: harvest-before-export runs before any of it.