Obsidian Notes Karpathy

Obsidian Notes Karpathy

Use this skill when the user talks about the workflow as a whole, not just one operation. Diagnose the lifecycle stage first, then route to the correct operational skill. If the operation is already obvious, skip the router and go straight to the matching kb-* skill.

Archive semantics stay split: raw/** plus raw/_manifest.yaml are source retention archive, while durable outputs under outputs/** are artifact archive. Neither archive surface bypasses the draft -> review -> live truth boundary.

When the user brings in the simpler raw/wiki/output vocabulary from Chinese-LLM-Wiki, route by meaning rather than mirroring that older structure literally.

Minimal loop

• kb-ingest registers raw sources into raw/_manifest.yaml
• kb-compile builds reviewable candidates from immutable captures
• kb-review decides what deserves durable truth
• kb-query reuses approved knowledge for search, grounded answers, creator-facing publish artifacts, archived Q&A reuse, and static web export
• kb-render turns approved knowledge into deterministic derivative artifacts
• kb-review also owns the maintenance lane when approved knowledge drifts or backlog accumulates

Karpathy alignment

This package implements the LLM Wiki pattern: "Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase." The user curates sources, asks questions, and thinks about meaning. The LLM handles summarizing, cross-referencing, filing, and bookkeeping that makes knowledge compound over time.

The key extension beyond Karpathy's original idea is an explicit review gate: unreviewed drafts never silently harden into long-term truth. This adds a draft → review → live promotion step that Karpathy's pattern leaves implicit.

The creator-ready extension is that compile should behave like a knowledge compiler, not just a summarizer: collect -> ingest -> compile (浓缩 -> 质疑 -> 对标) -> review -> query/publish -> maintenance.

Read before routing

Read these shared references first:

• ./scripts/skill-contract-registry.json
• ./references/chinese-llm-wiki-compat.md
• ./references/archive-model.md
• ./references/file-model.md
• ./references/lifecycle-matrix.md
• ./references/search-upgrades.md
• ./references/activity-log-template.md
• ./references/provenance-and-alias-policy.md
• ./references/questions-and-reflection-policy.md
• ./references/memory-lifecycle.md
• ./references/graph-contract.md
• ./references/source-manifest-contract.md
• ./references/profile-contract.md
• ./references/automation-hooks.md

Treat skill-contract-registry.json as the canonical list of package roles, required shared references, baseline commands, and output surfaces.

If the target vault already exists, inspect:

• local AGENTS.md
• local CLAUDE.md if present
• the top of wiki/index.md
• the most recent entries in wiki/log.md when available

If onkb is available, run onkb --json status <vault-root> first and treat its JSON output as the deterministic baseline.

If onkb is missing, follow the install fallback in ./references/lifecycle-matrix.md, then rerun the same command.

If the user mainly wants a concise "where am I and what next?" summary, prefer onkb status <vault-root>.

Lifecycle signals

Init signals

Route to kb-init when:

• the support layer does not exist yet
• AGENTS.md is missing
• wiki/index.md or wiki/log.md is missing
• wiki/drafts/, wiki/live/, wiki/briefings/, or outputs/reviews/ is missing
• the vault is a needs-migration / legacy-layout case that must be migrated first
• optional governance scaffolding such as QUESTIONS.md or ALIASES.md is explicitly requested

Compile signals

Route to kb-compile when:

• new or changed raw captures exist under raw/human/**, raw/agents/{role}/**, or directly under raw/ in a bootstrap vault
• the draft summary matching a raw capture is missing or outdated
• alias candidates, duplicate candidates, or source-integrity drift need to be surfaced before review
• a legacy-layout raw source still needs to be converted into the draft layer during migration

Ingest signals

Route to kb-ingest when:

• raw/_manifest.yaml exists but is stale relative to raw/**
• the user explicitly wants to refresh the source registry or inspect deferred raw sources
• a paper PDF, image asset, or data asset should be registered before compile runs
• a manifest drift signal appears before draft compilation work starts

Review signals

Route to kb-review when:

• draft knowledge exists under wiki/drafts/** and still has review_state: pending
• the user explicitly asks to run the quality gate, approve drafts, reject drafts, or rebuild briefings
• briefings are stale relative to the live layer and the next immediate step is to rebuild them through the gate
• a draft has unresolved contradiction, alias-alignment, or duplication-risk questions that require approval judgment

kb-review owns the immediate gate: pending draft decisions, promotion into wiki/live/, and briefing rebuilds that should happen as part of the current review pass.

Query signals

Route to kb-query when:

• wiki/live/** is trustworthy and current
• the user wants an answer, report, thread, slides, or other artifact grounded in the approved brain
• the user wants to reuse prior approved coverage or archived outputs before drafting a new outward-facing artifact
• the user wants to archive a substantive answer or reuse a prior archived answer/content artifact
• the user wants question-resolution candidates or reflection outputs that should stay outside live until re-reviewed
• the user explicitly uses older kb-search wording for local-first retrieval or candidate ranking

Render signals

Route to kb-render when:

• the user explicitly wants slides, a report, chart brief, or canvas output
• the task is deterministic format generation from approved knowledge rather than a normal grounded answer
• the user already has the source pages or archived answer and now wants a derivative artifact

Health signals

Route to kb-review in maintenance mode when:

• the live layer feels contradictory, weakly linked, or poorly provenanced
• approved pages appear to have bypassed review
• review backlog, stale briefings, or writeback pressure have become longer-horizon maintenance issues rather than the next immediate gate
• archived answers have pending writeback work
• archived outputs need hygiene work such as stale reuse, archive backlog cleanup, or private/shared scope leakage
• collaboration memory and approved knowledge appear to be mixing
• the user wants a maintenance baseline, drift audit, duplicate pass, alias audit, coverage-gap review, or report-first cleanup pass across approved surfaces
• the user wants planning surfaces such as curated hubs or editorial-gap views refreshed without widening the truth boundary
• the user wants to know which repeated outputs, question clusters, or weakly connected topics should become syntheses or hubs next

kb-review owns both the immediate gate and the longer-horizon maintenance lane: approved-layer drift, backlog pressure, archived-output hygiene, source-integrity drift, alias splits, graph weakness, hub backlog, and safe mechanical fixes after the immediate review gate has passed.

Companion skills

These skills are referenced by the lifecycle but live outside this bundle and are not maintained here:

• paper-workbench — external companion for paper PDF intake and normalization. Any raw/**/papers/*.pdf defers to this skill; when it is absent, kb-ingest surfaces the PDF as ingest_status: deferred and kb-compile refuses to treat it as a normal source.
• web-access / Obsidian Web Clipper — upstream collection lane for web sources before they land under raw/**. Routed through kb-ingest once the capture is on disk.

Companion skills are declared in scripts/skill-contract-registry.json under the top-level companion_skills field. Audit tooling treats them as external and does not report them as missing from the bundle.

Contract rules

• Treat raw/ as immutable evidence intake.
• Treat raw/_manifest.yaml as the canonical source registry.
• Treat wiki/drafts/ as reviewable knowledge, not query truth.
• Treat wiki/live/ as the only approved long-term brain.
• Treat wiki/live/topics/ as the default browse layer over approved knowledge.
• Treat wiki/live/procedures/ as approved procedural memory, not just another concept bucket.
• Treat wiki/briefings/ as per-role context generated from live only.
• Treat outputs/episodes/ as episodic memory and outputs/audit/operations.jsonl as the machine-readable audit trail.
• Treat archived outputs/qa/** and outputs/content/** as reusable artifact archive, not as approved truth.
• Treat outputs/reviews/ as the durable decision ledger.
• Keep wiki/index.md and wiki/log.md as complementary navigation surfaces.
• Absorb stronger governance signals such as source integrity, alias alignment, stale-page checks, and question tracking without collapsing the review gate.

Output requirements

When the user asks what to do next, answer with:

1. the lifecycle stage you detected 2. the concrete signals that led you there 3. the operational skill you are routing to 4. the next concrete action in the vault 5. any assumption you had to make 6. any repair target, migration warning, or missing companion guidance

Activity Log Template

Use wiki/log.md as the append-only activity ledger for the whole knowledge-base lifecycle.

Ingest / compile batch

## [{date}] ingest | {batch-slug}

- Raw captures scanned: {count}
- Draft summaries created: {count}
- Draft summaries updated: {count}
- Draft concepts touched: {count}
- Draft entities touched: {count}
- Touched files:
  - [[wiki/drafts/summaries/human/articles/source-a]]
  - [[wiki/drafts/concepts/concept-b]]

Review pass

## [{date}] review | {batch-slug}

- Review report:
  - [[outputs/reviews/{file}]]
- Decisions: approve={count} reject={count} needs-human={count}
- Promoted to live:
  - [[wiki/live/summaries/human/articles/source-a]]
- Rejected drafts:
  - [[wiki/drafts/summaries/agents/researcher/source-b]]

Briefing refresh

## [{date}] brief | {role}

- Briefing: [[wiki/briefings/{role}]]
- Rebuilt from:
  - [[wiki/live/concepts/concept-a]]
  - [[wiki/live/summaries/human/articles/source-b]]

Query archive

## [{date}] query | {question-slug}

- Question: {human-readable question}
- Consulted live pages:
  - [[wiki/live/concepts/concept-a]]
  - [[wiki/live/summaries/human/articles/source-b]]
- Used briefing: [[wiki/briefings/{role}]]
- Archived answer: [[outputs/qa/{file}]]

Archived artifact reuse

## [{date}] query | reuse-{reuse-slug}

- Reused artifact:
  - [[outputs/qa/{file}]]
- Reuse target:
  - [[outputs/content/articles/{file}]]
- Grounding still checked against:
  - [[wiki/live/concepts/concept-a]]

Publish artifact

## [{date}] publish | {artifact-slug}

- Artifact: [[outputs/content/threads/{file}]]
- Channel: thread | article | talk | report | slides | chart
- Derived from:
  - [[outputs/qa/{file}]]

Publish archive

## [{date}] publish | archive-{artifact-slug}

- Archived artifact:
  - [[outputs/content/articles/{file}]]
- Prior archived coverage reused:
  - [[outputs/qa/{file}]]
- Follow-up route: none | draft | review

Health pass

## [{date}] health | {run-slug}

- Report: [[outputs/health/health-check-{date}]]
- Overall score: {score}/100
- Critical issues: {count}
- Review backlog items: {count}
- Stale briefings: {count}

Archived backlog escalation

## [{date}] health | archive-backlog-{run-slug}

- Escalated archived outputs:
  - [[outputs/qa/{file}]]
  - [[outputs/content/articles/{file}]]
- Reason: writeback backlog | stale archive | reuse gap | scope leak
- Routed to: kb-review (maintenance)

Rules:

• append only
• log batch-level work, not every micro-edit
• include enough paths that later diagnosis can trace a promotion chain

Archive Model

Use this reference whenever the workflow talks about archiving, reusing archived work, or cleaning archive backlog.

Core idea

This bundle uses archive in two different but related senses:

1. source retention archive 2. artifact archive

Both are durable surfaces. Neither one overrides the approved truth boundary.

Source retention archive

The source retention archive is:

• raw/**
• raw/_manifest.yaml

It means the vault keeps original evidence and its registry.

It does not mean:

• moving sources into raw/09-archive/
• deleting or rewriting source files after compile
• treating retained raw captures as query-time truth

The current contract keeps raw sources in place. The archive behavior here is retention plus registration, not physical relocation.

Artifact archive

The artifact archive is the set of downstream durable outputs:

• outputs/qa/**
• outputs/content/**
• outputs/episodes/**
• outputs/reviews/**
• outputs/health/**
• outputs/web/**

These are durable working surfaces for reuse, review, maintenance, and export.

Truth boundary

Archive is not the same thing as approved knowledge.

• wiki/live/** remains the approved truth layer.
• archived artifacts may be reused, ranked, inspected, and audited.
• archived artifacts may generate writeback_candidates, followup_route, and maintenance pressure.
• archived artifacts do not become approved truth unless the durable knowledge re-enters draft -> review -> live.

Reuse boundary

Archive is valuable because it prevents repeated work.

Expected reuse order:

1. approved live pages 2. relevant live indices and briefings 3. prior archived Q&A 4. prior archived publish artifacts when they already reuse approved coverage cleanly

Archive reuse should reduce duplicated explanation, not bypass live grounding.

Maintenance boundary

Archived artifacts are first-class maintenance inputs.

Maintenance should inspect archived artifacts for:

• stale outputs relative to newer live pages
• writeback backlog
• reuse gaps
• scope leaks such as private/shared mismatches
• creator consistency drift

Maintenance should fix archive hygiene, not silently upgrade archived artifacts into live truth.

Physical archive note

This contract intentionally does not introduce a physical raw/09-archive/ move step.

If a future workflow wants true source-file relocation after processing, treat that as a separate architecture change:

• it needs new directory rules
• it needs migration guidance
• it needs explicit lifecycle updates
• it should not be mixed into the current archive-surface clarification work

Automation Hooks

Use this reference when designing CLI-first automation around the review-gated bundle.

Near-term hooks

Start with file-system and command driven hooks before deeper runtime integration.

• on_new_source
• detect new or changed captures
• refresh compile delta
• optionally precompute draft and graph candidates
• on_session_end
• crystallize substantive outputs into outputs/episodes/**
• append an audit event
• on_query_archive
• ensure archived Q&A/content records source_live_pages, writeback_candidates, followup_route, and confidence_posture
• optionally generate/update a linked episode page
• scheduled_health
• run health lint
• refresh governance indices
• refresh outputs/health/graph-snapshot.json

Audit requirement

Automation should leave a machine-readable breadcrumb in outputs/audit/operations.jsonl:

• timestamp
• action
• payload

Boundary discipline

Automation can:

• create drafts
• refresh indices
• emit episodes
• export graph snapshots
• append audit events

Automation must not:

• mutate raw/**
• bypass draft -> review -> live
• silently promote candidate or episodic surfaces into approved truth

Invocation

The CLI harness for these hooks is onkb review automation <vault-root> --mode <hook> [--write].

Usage pattern:

onkb --json review automation <vault> --mode <hook> [--write]

Supported --mode values mirror the hook names above: on_new_source, on_session_end, on_query_archive, scheduled-health. Without --write, the command runs as a dry report.

Treat onkb as the CI and automation entrypoint. Human-driven lifecycle work still goes through the corresponding kb-* skill rather than this harness.

Append responsibility

Who may append to outputs/audit/operations.jsonl:

Every appended line must carry timestamp (ISO-8601 UTC, e.g. 2026-04-20T11:32:00Z), action (hook or skill event name), and a payload object describing the effect. Skills that do not append directly rely on the automation harness to attribute events. operations.jsonl is append-only; compaction or rotation belongs to maintenance work, not to the emitting skill.

Briefing Template

Use this structure for wiki/briefings/{role}.md.

---
title: "{Role} Briefing"
brief_for: "{role}"
built_from: "wiki/live/"
updated_at: "{datetime}"
staleness_after: "{datetime}"
source_live_pages:
  - "[[wiki/live/concepts/concept-a]]"
  - "[[wiki/live/summaries/human/articles/source-b]]"
open_questions_touched:
  - "{question this role should keep in mind}"
---

# {Role} Briefing

## Mission Context

- {what this role should keep in working memory}

## Approved Facts to Reuse

- [[wiki/live/concepts/concept-a]] - {why it matters}
- [[wiki/live/summaries/human/articles/source-b]] - {why it matters}

## Open Questions

- {what still needs new evidence}

## Guardrails

- Never treat drafts as approved truth.
- Prefer approved summaries when citing evidence trails.
- Never cite raw captures unless a human explicitly asks for source evidence.

Rules:

• briefings must be generated only from live pages
• briefings should be short, role-specific, and easy to regenerate
• use open_questions_touched when the role should track unresolved decisions or evidence gaps

Chinese LLM Wiki Compatibility

Use this reference when a user speaks in the simpler raw/wiki/output vocabulary from Chinese-LLM-Wiki, but this bundle still needs to keep the review-gated contract intact.

Hard boundary

• do not collapse the bundle back into a single canonical wiki/ layer
• keep wiki/live/** as the only approved truth surface
• keep outputs/** as reusable artifact archive, not approved truth
• keep raw/** immutable and retained in place

Term mapping

Routing hints

• if the user says 先读 wiki/index.md or asks which step should run next, route through the package skill first
• if the user wants to turn new raw material into 来源页 / 主题页 / 实体页, treat that as compile work before review
• if the user wants a lint report, orphan-page check, contradiction pass, or stale-claim audit, treat that as kb-review maintenance
• if the user wants a grounded analysis saved to something like output/analyses, treat that as kb-query
• if the user wants a deterministic report deck or chart from already approved knowledge, treat that as kb-render

Language and evidence posture

• 中文优先 is a presentation rule, not a routing change
• 原文证据摘录 still means short evidence excerpts, not long raw copy-paste
• 先读 wiki/index.md remains the default navigation posture for router, query, and review work

Example translations

• 请把 raw 里的文章整理成来源页，并更新主题页和实体页
• compile the raw capture into draft summaries, topics, and entities, then hand it to review
• 请做一份 lint 报告放到 output/reports
• run review maintenance; do not confuse this with deterministic report rendering
• 请基于现有 wiki 做一份综合分析，先放 output/analyses
• run grounded query mode and archive the result under outputs/qa/**

Compile Method

Use this reference whenever kb-compile needs the public contract for turning raw captures into draft knowledge.

Core posture

Compile should not stop at summarization. The default creator-ready method is:

浓缩 -> 质疑 -> 对标

The goal is to turn raw evidence into reusable draft packages that preserve signal, surface fragility, and identify durable transfer value.

Step 1: 浓缩

Reduce the source to the minimum set of claims that would materially change understanding.

Output expectations:

• no more than 3 core conclusions
• each conclusion paired with the key evidence that justifies it
• direct source claims kept separate from compiler-added framing

Good compression should make it obvious what the source is really saying without flattening all nuance into one vague paragraph.

Step 2: 质疑

Stress-test each core conclusion before it hardens into reusable draft knowledge.

Check explicitly:

• which assumptions must hold for the conclusion to remain valid
• boundary conditions such as market, industry, scale, geography, or time horizon
• sample-size, source-quality, and freshness limits
• counterexamples, failure cases, or reasons the conclusion may not transfer

Output expectations:

• assumption_flags
• boundary_conditions
• review notes when evidence is thin, outdated, or context-bound

Step 3: 对标

Look for cross-domain analogies and migration value.

Ask:

• what similar phenomenon exists in another domain
• which workflows, concepts, or hubs this source should strengthen
• whether the durable delta is semantic knowledge, a procedure, or a hub/relationship upgrade

Output expectations:

• transfer_targets
• concept / procedure / hub candidates
• relationship candidates when the best durable improvement is connective rather than page-creating

Promotion guidance

• If the durable delta is a repeatable workflow, prefer wiki/drafts/procedures/**.
• If the durable delta is a cross-domain pattern or reusable idea, prefer concept or hub candidates.
• If the source is valuable mainly because it strengthens links between existing approved pages, prefer relationship or hub upgrades over another standalone page.

Machine-readable posture

Draft summaries should expose these compile-time outputs in frontmatter when available:

• boundary_conditions
• assumption_flags
• transfer_targets

Those fields are review inputs. They do not widen the truth boundary by themselves.

Concept Template

---
title: "{Concept Title}"
concept_id: "{concept-slug}"
aliases:
  - "{common alias}"
visibility_scope: private | shared
confidence_score: 0.84
confidence_band: strong | moderate | weak
support_count: 3
contradiction_count: 0
updated_at: "{datetime}"
last_reviewed_at: "{datetime}"
last_confirmed_at: "{datetime}"
next_review_due_at: "{datetime}"
decay_class: architecture | workflow | transient
status: active | draft | conflicting
supersedes:
  - "[[wiki/live/concepts/older-concept]]"
superseded_by: []
superseded_at: "{datetime}"
supersession_reason: "{why this concept replaced or narrowed an older one}"
sources:
  - "[[wiki/live/summaries/source-a]]"
related:
  - "[[wiki/live/concepts/related-concept]]"
  - "[[wiki/live/entities/related-entity]]"
---

# {Concept Title}

## Definition

{one concise definition grounded in the current evidence}

## Why It Matters

{why this concept deserves its own page}

## Established

- {current statement you are willing to reuse}
- {second stable statement grounded in the evidence}

## Inference

- {synthesis or framing added on top of the source material}

## Evidence

- [[wiki/live/summaries/source-a]] - {claim or support}
- [[wiki/live/summaries/source-b]] - {claim or contrast}

## Related Concepts

- [[wiki/live/concepts/related-concept]] - {relationship}

## Related Entities

- [[wiki/live/entities/related-entity]] - {relationship}

## Tensions and Contradictions

- {disagreement between sources, if any}

## Open Questions

- {what remains uncertain}

Rules:

• Merge evidence instead of duplicating concept pages.
• When used under wiki/drafts/**, point sources and related at draft pages; when promoted under wiki/live/**, point them at approved live pages.
• Use aliases aggressively so backlinks and unlinked mentions still work when terminology shifts.
• Use related for real relationships to concepts or entities, not speculative link spam.
• Keep confidence_*, support counts, and supersession metadata explicit once a page has moved onto the latest lifecycle contract.
• Set status: conflicting when unresolved disagreement remains.

Content Output Template

Use this when the user wants to turn the knowledge base into publishable content.

---
title: "{Artifact Title}"
created_at: "{datetime}"
artifact_type: article | thread | newsletter | talk-outline
channel: "{channel}"
sources:
  - "[[wiki/live/concepts/concept-a]]"
  - "[[wiki/live/entities/entity-b]]"
  - "[[outputs/qa/question-a]]"
source_live_pages:
  - "[[wiki/live/concepts/concept-a]]"
  - "[[wiki/live/entities/entity-b]]"
derived_from:
  - "[[outputs/qa/question-a]]"
reused_prior_coverage:
  - "[[wiki/live/indices/topic-hub]]"
related_pages:
  - "[[wiki/live/concepts/concept-c]]"
topic_hubs:
  - "[[wiki/live/indices/hub-a]]"
open_questions_touched:
  - "[[wiki/live/indices/QUESTIONS#question-a]]"
writeback_candidates:
  - "create or expand curated hub for topic-x"
writeback_status: none | pending | triaged | drafted | reviewed | rejected
followup_route: none | draft | review
confidence_posture: grounded | mixed-evidence | exploratory
compounding_value: low | medium | high
crystallized_from_episode: "[[outputs/episodes/example-episode]]"
visibility_scope: private | shared
---

# {Artifact Title}

## Brief

- Audience: {audience}
- Goal: {goal}
- Angle: {angle}
- Prior coverage reused: {existing approved page or archived artifact reused instead of re-explaining from scratch}
- Topic hub or program touched: {hub / coverage surface when relevant}
- Reusable payoff: {how this artifact should make future query, drafting, or hub-building easier}

## Core Claims

1. {claim 1}
2. {claim 2}
3. {claim 3}

## Draft

{full draft}

## Provenance

- [[wiki/live/concepts/concept-a]] - {what it contributed}
- [[wiki/live/entities/entity-b]] - {what it contributed}
- [[outputs/qa/question-a]] - {what it contributed}

## Relationship Notes

- Related pages worth linking or updating: {pages that should gain `related`, alias, or hub connections}
- Hub impact: {whether this artifact strengthens an existing hub or suggests a new one}

## Proposed Durable Delta

- Preferred move: {update live page | draft new page | strengthen relationships | create / expand curated hub}
- Target: {page or hub}
- Why this compounds the wiki: {future reuse, navigation gain, or reduced duplication}

## Writeback Candidates

- {new concept, entity, relationship, hub, or source gap discovered while drafting}

Rules:

• Publish artifacts should stay grounded in the wiki instead of drifting away from the evidence.
• Prefer reusing prior approved coverage or archived outputs explicitly before restating the same background explanation in a new artifact.
• If the draft introduces a new synthesis worth preserving, pair the artifact with explicit writeback_candidates or a supporting Q&A note.
• When the artifact came out of a larger research/debugging thread, keep the episodic breadcrumb through crystallized_from_episode.
• Writeback candidates may be relationship or hub upgrades, not only new pages.
• Keep raw source captures immutable; editorial shaping belongs in the artifact, Q&A archive, or the later draft/review lane.
• Prefer the smallest durable delta that improves the wiki after publication: sometimes this is a new synthesis page, but often it is a hub update, relationship upgrade, or governed question.

Draft Schema

Use this reference as the single-source schema for wiki/drafts/** pages. kb-compile writes drafts that match this schema; kb-review reads and gates them.

Type-specific templates (summary-template.md, concept-template.md, entity-template.md, topic-template.md, procedure-template.md) layer their own fields on top of this baseline.

Required fields

Every draft, regardless of type, must include:

Conditional fields

Include these only when the described signal is present; omit otherwise so review gets a clean surface.

Provenance and timestamps

Every draft that touches compiled_at, last_verified_at, last_source_check_at, or last_confirmed_at must use ISO-8601 UTC with second precision, e.g. 2026-04-20T11:32:00Z. Avoid local time zones in draft frontmatter.

Type-specific layering

On top of this schema, each draft type adds its own fields:

• summary-template.md — adds title, source_file, source_hash or source_mtime, possibly_outdated.
• concept-template.md — adds canonical_name, aliases, domain_volatility candidates.
• entity-template.md — adds entity-specific identity and role fields.
• topic-template.md — adds topic_hub candidates and hub-level aggregation fields.
• procedure-template.md — adds procedure-specific fields (procedure_id, confidence_band, decay_class, next_review_due_at).

When a field appears here and also in a type template, this reference is authoritative for the naming and conditional rules; the type template only specifies its incremental fields.

Write-time checklist

Before handing a draft to kb-review, confirm:

• every required field is present with a non-placeholder value
• each conditional field is either populated with real signal or omitted
• compiled_from and capture_sources actually exist under raw/**
• promotion_target matches the content shape (workflow → procedural, definition/concept → semantic)
• blocking_flags is an empty list if and only if the draft is safe for auto-approval

Entity Template

Use dedicated entity pages only when the named thing is durable enough to deserve one page of its own.

Good candidates:

• people
• organizations
• products
• tools
• projects
• repositories

---
title: "{Entity Title}"
entity_id: "{entity-slug}"
entity_type: person | organization | product | tool | project | repo | other
aliases:
  - "{common alias}"
visibility_scope: private | shared
confidence_score: 0.82
confidence_band: strong | moderate | weak
support_count: 2
contradiction_count: 0
updated_at: "{datetime}"
last_reviewed_at: "{datetime}"
last_confirmed_at: "{datetime}"
next_review_due_at: "{datetime}"
decay_class: architecture | workflow | transient
status: active | draft | conflicting
supersedes: []
superseded_by: []
superseded_at: "{datetime}"
supersession_reason: "{why this entity record superseded an older representation}"
sources:
  - "[[wiki/live/summaries/source-a]]"
related:
  - "[[wiki/live/concepts/related-concept]]"
  - "[[wiki/live/entities/related-entity]]"
---

# {Entity Title}

## Who or What It Is

{one concise definition grounded in the evidence}

## Why It Matters Here

{why this entity deserves a stable page in this vault}

## Established

- {stable fact grounded in the approved evidence}
- {second stable fact that should remain reusable}

## Inference

- {synthesis or interpretation added on top of the evidence}

## Evidence

- [[wiki/live/summaries/source-a]] - {claim or support}
- [[wiki/live/summaries/source-b]] - {claim or contrast}

## Related Concepts

- [[wiki/live/concepts/related-concept]] - {relationship}

## Related Entities

- [[wiki/live/entities/related-entity]] - {relationship}

## Tensions and Contradictions

- {disagreement between sources, if any}

## Open Questions

- {what remains uncertain}

Rules:

• Prefer entity pages only for named things that recur, anchor multiple notes, or clearly deserve stable provenance.
• When used under wiki/drafts/**, point sources and related at draft pages; when promoted under wiki/live/**, point them at approved live pages.
• If the evidence is thin, keep the item in summaries or concept aliases rather than creating a weak entity page.
• Carry visibility_scope and confidence metadata explicitly once the entity participates in the latest lifecycle contract.
• Set status: conflicting when unresolved disagreement remains.

Episode Template

Use this structure for outputs/episodes/**.

---
title: "Episode: {Episode Title}"
episode_id: "{episode-slug}"
memory_tier: episodic
captured_at: "{datetime}"
episode_scope: qa | content | session
source_artifacts:
  - "[[outputs/qa/example-output]]"
source_live_pages:
  - "[[wiki/live/concepts/example-concept]]"
open_questions_touched:
  - "{standing question}"
writeback_candidates:
  - "{durable follow-up}"
followup_route: none | draft | review
consolidation_status: pending | drafted | reviewed | completed
visibility_scope: private | shared
---

# Episode: {Episode Title}

## What Happened

{Short narrative of the work arc}

## Durable Signals

- {reusable pattern}
- {question that should feed back into the wiki}

Rules:

• Episode pages are reusable memory, not approved topic truth.
• Prefer compact summaries over raw transcripts.
• Link back to the originating Q&A or content output so later audit and supersession work stays traceable.

File Model

Table of Contents

• Core rules
• Archive model
• Creator workflow mapping
• Required vs optional support
• Expected directories
• Raw capture classes
• Compile method
• Draft summaries
• Live pages
• Briefings
• Collaboration memory
• Review records
• Query outputs
• Naming and graph conventions

Canonical review-gated layering:

raw/            -> immutable capture intake
raw/_manifest.yaml -> canonical source registry
MEMORY.md       -> collaboration memory and editorial context
wiki/drafts/    -> compiled but unapproved draft knowledge
wiki/live/      -> approved long-term brain
wiki/live/topics/ -> approved browse-layer topics
wiki/briefings/ -> role-specific context built from live only
outputs/        -> reviews, Q&A, health reports, and publishable derivatives

Archive model:

• source retention archive -> raw/** + raw/_manifest.yaml
• artifact archive -> outputs/**
• approved truth -> wiki/live/**

Treat the vault like a codebase with a promotion gate:

• raw/ is source evidence and the durable source library.
• raw/_manifest.yaml is the canonical source registry for tracked inputs.
• MEMORY.md is the coordination surface for preferences, priorities, and collaboration rules.
• wiki/drafts/ is build output waiting for review.
• wiki/live/ is the deployed truth layer.
• wiki/live/topics/ is the default browse layer over approved knowledge.
• wiki/briefings/ is generated runtime context for agents.
• outputs/reviews/ is the decision ledger for promotion.
• outputs/** is the durable artifact archive.
• outputs/qa/ and outputs/content/ can surface writeback candidates, unresolved questions, and creator-facing derivatives, but they still re-enter the system through draft -> review -> live.

Archive model

This bundle uses archive in two senses:

1. source retention archive — retained raw evidence plus its manifest 2. artifact archive — durable downstream outputs under outputs/**

The contract intentionally does not use archive to mean "move raw files into raw/09-archive/".

Archive surfaces can be reused and audited, but they do not outrank the truth boundary:

• raw/** is retained evidence
• outputs/** is reusable artifact archive
• wiki/live/** is approved truth

Core rules

1. raw/ is read-only from the workflow's point of view. 2. kb-compile writes only to wiki/drafts/, never directly to wiki/live/. 3. kb-review is the only skill that can promote draft knowledge into wiki/live/. 4. kb-query reads wiki/live/, wiki/briefings/, and prior outputs/qa/; it must not treat raw/ or wiki/drafts/ as retrieval truth. 5. kb-query must not treat MEMORY.md as domain knowledge truth; it is only for collaboration or editorial context. 6. wiki/index.md is the content-oriented landing page for the whole contract, including live, draft, question, and briefing state. 7. wiki/log.md is the append-only activity ledger for ingest, review, brief, query, publish, render, and maintenance work. 8. outputs/qa/ stores durable research answers, not disposable chat residue. 9. outputs/** is artifact archive, not approved truth. 10. outputs/reviews/ stores reviewer decisions and scoring details. 11. Existing older vaults using wiki/summaries/ and wiki/concepts/ directly should be detected as legacy-layout and migrated before normal operation. 12. Alias alignment, source integrity, stale-page checks, and duplicate detection are part of governance, but they must respect the review gate rather than bypass it.

Creator workflow mapping

For creator-style vaults, map common working surfaces onto the contract like this:

• source library / clipped research -> raw/
• web collection before raw intake -> web-access or Obsidian Web Clipper, then kb-ingest
• source registry / tracked intake -> raw/_manifest.yaml
• retained source archive -> raw/** + raw/_manifest.yaml
• editorial memory / collaboration preferences -> MEMORY.md
• temporary research answers or drafting notes worth preserving -> outputs/qa/
• publish-ready outward artifacts -> outputs/content/
• durable artifact archive -> outputs/**
• reusable approved concepts, entities, and summaries -> wiki/live/
• curated topic maps, hubs, or editorial navigation surfaces -> wiki/live/indices/ or approved hub-style live pages when review says they are durable enough
• actionable writeback backlog and editorial triage surfaces -> governance indices, health reports, or a maintained backlog note derived from archived outputs rather than hidden inside one-off artifacts

The key boundary is that creator convenience must not widen the truth boundary. Reusable planning or publish surfaces can exist, but durable topic knowledge is still approved only through draft -> review -> live.

A compounding wiki should therefore keep both:

• a truth layer in wiki/live/
• a visible follow-up layer where archived outputs, open questions, and maintenance signals can be triaged into the next draft, review, or health pass

Required vs optional support

The minimum support layer for kb-init is:

• raw/
• raw/_manifest.yaml
• wiki/drafts/
• wiki/live/
• wiki/briefings/
• wiki/index.md
• wiki/log.md
• outputs/reviews/
• AGENTS.md
• CLAUDE.md

Downstream output surfaces such as outputs/qa/, outputs/health/, outputs/reports/, outputs/slides/, outputs/charts/, outputs/web/, and outputs/content/** are valid parts of the full contract, but they are created on demand when later stages need them. MEMORY.md is recommended collaboration scaffolding rather than a blocking support-layer requirement.

Optional governance scaffolding should be treated as the recommended default for mature vaults that want recurring maintenance surfaces:

• wiki/live/indices/QUESTIONS.md
• wiki/live/indices/GAPS.md
• wiki/live/indices/ALIASES.md

Expected directories

vault/
├── raw/
│   ├── human/
│   │   ├── articles/
│   │   ├── papers/
│   │   ├── podcasts/
│   │   ├── repos/
│   │   ├── assets/
│   │   └── data/
│   ├── agents/
│   │   └── {role}/
│   └── _manifest.yaml
├── wiki/
│   ├── drafts/
│   │   ├── summaries/
│   │   ├── topics/
│   │   ├── concepts/
│   │   ├── entities/
│   │   ├── overviews/
│   │   ├── comparisons/
│   │   └── indices/
│   ├── live/
│   │   ├── summaries/
│   │   ├── topics/
│   │   ├── concepts/
│   │   ├── entities/
│   │   ├── overviews/
│   │   ├── comparisons/
│   │   └── indices/
│   ├── briefings/
│   ├── index.md
│   └── log.md
├── outputs/
│   ├── reviews/
│   ├── qa/
│   ├── health/
│   ├── reports/
│   ├── slides/
│   ├── charts/
│   ├── web/
│   └── content/
│       ├── articles/
│       ├── threads/
│       └── talks/
├── AGENTS.md
├── MEMORY.md
└── CLAUDE.md

Raw capture classes

Human captures

Live under raw/human/**.

• treated as curated evidence
• may be markdown notes or PDFs under a papers/ subtree
• should preserve source metadata only
• may carry last_verified_at and possibly_outdated as intake hints
• may record optional manifest metadata such as capture_method, linked_assets, and source_profile

Agent captures

Live under raw/agents/{role}/**.

• treated as untrusted until reviewed
• should preserve provenance and role identity
• must never be promoted directly into the live brain

Legacy captures

Older vaults may still use legacy-layout paths such as raw/articles/ or raw/papers/.

• continue to detect them for migration
• do not silently reinterpret them as fully valid review-gated support layers

Bootstrap root captures

Some partially bootstrapped vaults may place markdown directly under raw/.

• accept these files as valid compile inputs
• preserve raw immutability exactly as with nested capture classes
• surface any missing support-layer directories separately instead of rejecting the source format itself

Image and data raw source posture

• image assets under raw/**/assets/ are valid tracked sources
• structured data files under raw/**/data/ are valid tracked sources
• both should be registered in raw/_manifest.yaml
• both can generate deterministic draft packages without becoming retrieval truth directly
• compile should read markdown first and only pull linked local assets or attachments when the source actually depends on them

Compile method

The default compile contract is:

浓缩 -> 质疑 -> 对标

That means draft summaries should preserve:

• compressed conclusions plus key evidence
• assumption and boundary-condition checks
• cross-domain transfer targets
• promotion hints about whether the durable delta is semantic, procedural, or relationship / hub oriented

Draft summaries

Live under wiki/drafts/summaries/** and mirror raw captures.

Expected properties:

• title
• source_file
• source_hash or source_mtime
• last_verified_at
• possibly_outdated
• compiled_at
• draft_id
• compiled_from
• capture_sources
• review_state
• review_score
• blocking_flags
• alias_candidates
• duplicate_candidates
• boundary_conditions
• assumption_flags
• transfer_targets

Live pages

Live under wiki/live/{summaries,concepts,entities,overviews,comparisons}/.

Expected properties:

• title
• canonical_name
• aliases
• domain_volatility
• approved_at
• approved_from
• review_record
• trust_level: approved
• updated_at
• last_reviewed_at
• last_source_check_at when freshness needs to be audited explicitly
• sources
• related
• optional relationship_notes when the vault wants lightweight semantics such as supports, contrasts, extends, supersedes, or related-question
• optional evidence_strength or source_density when the vault tracks thin-support risk
• optional question_links or open_questions when the page participates in a standing governance thread
• optional topic_hub when the page belongs to a curated hub / MOC-like surface
• optional latest lifecycle fields such as confidence_score, confidence_band, support_count, contradiction_count, last_confirmed_at, next_review_due_at, decay_class, supersedes, superseded_by, superseded_at, supersession_reason, and visibility_scope

wiki/live/procedures/ is the procedural memory surface. Use it for durable workflows, playbooks, and repeated decision patterns that should remain distinct from semantic concept pages.

Expected procedure properties:

• title
• procedure_id
• visibility_scope
• confidence_score
• confidence_band
• support_count
• contradiction_count
• updated_at
• last_reviewed_at
• last_confirmed_at
• next_review_due_at
• decay_class
• approved_at
• approved_from
• review_record
• trust_level: approved
• sources
• related

Briefings

Live under wiki/briefings/.

Expected properties:

• title
• brief_for
• built_from
• updated_at
• staleness_after
• source_live_pages
• open_questions_touched
• optional brief_scope or brief_focus when the same role has multiple stable briefing lenses

Collaboration memory

MEMORY.md lives at the vault root.

Expected content:

• stable preferences
• editorial priorities
• collaboration rules
• current focus areas

It should not become a shadow knowledge base full of topic conclusions or source-grounded claims.

Review records

Live under outputs/reviews/.

Expected properties:

• title
• decision
• accuracy
• provenance
• conflict_risk
• composability
• source_integrity
• alias_alignment
• duplication_risk
• staleness_risk
• reviewed_at

Query outputs

outputs/qa/ remains the durable answer archive, but all cited knowledge should trace back to wiki/live/ and the relevant approved summaries whenever possible.

Expected operational fields for substantive Q&A and publish outputs:

• source_live_pages when specific approved pages grounded the output
• open_questions_touched when the output materially advances standing questions
• writeback_candidates when the output discovers durable follow-up worth re-entering the wiki
• writeback_status to show whether that follow-up is still pending
• followup_route as none | draft | review
• optional confidence_posture when the answer should advertise uncertainty explicitly
• optional compounding_value when the artifact should advertise expected long-term reuse value
• optional crystallized_from_episode when the answer or artifact came out of a broader episodic thread
• optional visibility_scope when the artifact is intentionally private or shared

These outputs can inform governance and maintenance surfaces, but they never become approved truth automatically.

Prefer concrete operational values over placeholders. For example, writeback_candidates should describe the exact durable delta proposed, and compounding_value should reflect whether the artifact meaningfully improves future reuse, navigation, or synthesis.

Naming and graph conventions

• use stable lowercase kebab-case paths
• keep wiki/live/indices/ as the canonical derived navigation directory
• allow a promoted draft to keep the same basename when moved into wiki/live/
• keep alias-style wikilinks out of Markdown table cells
• treat review_record and approved_from as first-class provenance edges
• use aliases and canonical names to support cross-language linking without creating parallel truth pages

Episodic and audit surfaces

outputs/episodes/ is the episodic memory surface.

Use it for:

• session-level crystallizations
• compacted debugging/research arcs
• reusable context that is stronger than raw evidence but not yet approved semantic truth

Expected episode properties:

• title
• episode_id
• memory_tier: episodic
• captured_at
• episode_scope
• source_artifacts
• source_live_pages
• open_questions_touched
• writeback_candidates
• followup_route
• consolidation_status
• visibility_scope

outputs/audit/operations.jsonl is the machine-readable audit trail.

Each line should record:

• timestamp
• action
• payload

Tier mapping

The latest lifecycle contract keeps tiers explicit:

• raw/** = working evidence
• outputs/episodes/** = episodic memory
• wiki/live/** = semantic memory
• wiki/live/procedures/** = procedural memory
• MEMORY.md = collaboration/editorial context only

Creator workflow mapping

For creator-style workflows, a practical mapping is:

• source library / clipped research -> raw/
• web collection before raw intake -> web-access or Obsidian Web Clipper, then kb-ingest
• editorial memory -> MEMORY.md
• session crystallization -> outputs/episodes/
• reusable research answers or drafting notes -> outputs/qa/
• outward-facing publish artifacts -> outputs/content/
• static browseable web exports -> outputs/web/
• durable approved knowledge -> wiki/live/
• durable workflows / playbooks -> wiki/live/procedures/
• machine-readable audit -> outputs/audit/operations.jsonl
• graph export for local candidate retrieval -> outputs/health/graph-snapshot.json

Graph Contract

Use this reference when adding the latest graph structure without replacing the markdown wiki.

Graph surfaces

• Page body and frontmatter remain the primary human-readable source.
• related, topic_hub, question_links, relationship_notes, supersedes, and superseded_by are the canonical explicit graph hints in markdown.
• wiki/live/indices/ENTITIES.md and wiki/live/indices/RELATIONSHIPS.md are derived navigation views.
• outputs/health/graph-snapshot.json is a machine-readable export for local candidate retrieval, audits, and tooling.

Edge types

Prefer typed edges over vague adjacency:

• related
• supports
• contrasts
• extends
• supersedes
• superseded_by
• related-question

relationship_notes may carry the human-readable nuance, but durable traversal should still land on explicit related or supersession fields when possible.

Retrieval boundary

The graph augments retrieval. It does not widen truth.

• The graph can help discover candidate pages.
• Final answers should still cite approved wiki/live/** pages.
• Episode nodes and graph snapshot exports are candidate-only surfaces.

Health posture

Surface graph_gap when a page clearly signals graph intent but lacks durable edges, for example:

• relationship_notes exists without related
• graph-required pages remain disconnected
• repeated hub signals never become explicit links

Health Rubric

Use this structure for outputs/health/health-check-{date}.md.

---
title: "Health Check Report"
date: "{datetime}"
scope: "wiki/live/, wiki/briefings/, outputs/qa/, outputs/content/, outputs/reviews/"
health_score: {overall}
---

# Knowledge Base Health Check

## Health Score: {overall}/100

| Dimension | Score | Notes |
|-----------|-------|-------|
| Completeness | {score} | {notes} |
| Consistency | {score} | {notes} |
| Connectivity | {score} | {notes} |
| Freshness | {score} | {notes} |
| Provenance | {score} | {notes} |

## Critical Issues

- {issue}

## Warnings

- {warning}

## Duplicate and Alias Drift

- {duplicate concept/entity or alias split}

## Creator Consistency

- {editorial drift across CLAUDE.md, MEMORY.md, style guides, or briefings}
- {profile conflict between account guidance surfaces}

## Review Backlog

- {pending draft or human review queue item}

## Briefing Staleness

- {stale briefing}

## Writeback Backlog

- {qa or content artifact with pending writeback candidates}

## Reuse Signals

- {reuse gap in archived creator outputs}
- {underused approved source that is not showing up in reusable outputs}

## Open Questions and Gaps

- {source gap or ambiguity}

## Growth Opportunities

### Compile Next

- {capture or question cluster that should re-enter draft creation}

### Review Next

- {draft, promotion boundary, or disputed interpretation needing review}

### Hub Build Next

- {topic / program / question cluster that now deserves a curated hub}

### Source Acquisition Next

- {missing source that would reduce uncertainty or fill a recurring gap}

## Search Upgrade Recommendation

- Current stage: {1 | 2 | 3 | 4}
- Why: {why this stage fits the current vault}
- Next tool or pattern: {Backlinks | Properties | qmd | DuckDB | Dataview | vector retrieval}

## Fix Now

- {safe automatic fix}

## Propose Fix

- {fix that is likely correct but should be reviewed}

## Human Review Needed

- {judgment call}

Suggested weighting:

• Completeness: 20%
• Consistency: 25%
• Connectivity: 15%
• Freshness: 15%
• Provenance: 25%

What to grade

Completeness

• live concept or entity gaps relative to approved summaries
• missing briefings for active roles
• review outputs that never generated the corresponding live page or briefing
• open questions or writeback candidates that recur without an owner
• repeated archived outputs that imply a missing synthesis or curated hub
• procedural candidates that never graduated into wiki/drafts/procedures/ or wiki/live/procedures/
• episodic notes that never re-entered the semantic/procedural lanes despite durable signals

Consistency

• conflicting approved concepts or entities
• duplicate approved concepts or entities
• approved claims contradicted by newer approved sources
• aliases split across multiple live notes that should converge
• supersession chains that are missing reciprocal links, timestamps, or reasons

Connectivity

• orphan live summaries, concepts, entities, or Q&A
• weak cross-linking between live pages and briefings
• missing approved_from / review_record provenance edges
• weakly connected live pages that should likely participate in a synthesis, relationship edge, or curated hub
• graph-signaled pages with relationship_notes or graph requirements but no durable related edges

Freshness

• stale briefings
• approved pages that should have been rebuilt after new reviews
• old Q&A that should be refreshed against newer approved knowledge
• pending writeback candidates that have not re-entered the draft/review loop
• pages whose domain_volatility suggests they should be reviewed sooner
• repeated question clusters that remain unresolved without visible progress
• confidence decay windows that have passed without a fresh source check or review

Provenance

• live pages missing review_record
• live pages missing trust_level: approved
• answers or briefings that cite drafts or raw captures as truth
• approved pages with empty or missing sources
• source hash drift or outdated verification metadata
• pages using the latest lifecycle metadata missing core confidence metadata (confidence_score, confidence_band, support_count, contradiction_count)
• missing machine-readable audit events for automation surfaces that claim to be governed

Creator consistency checks

Treat these as first-class maintenance diagnostics when the vault has creator-facing outputs:

• CLAUDE.md, MEMORY.md, account _style-guide.md files, and account-facing briefings drifting apart
• forbidden terms, tone rules, or publishing constraints present in one creator surface but missing from another
• creator/account profile collisions where two guidance surfaces disagree on voice, positioning, or audience
• archived creator outputs that fail to record reuse of prior approved coverage
• approved sources that have not been reused in archived Q&A or publish outputs despite remaining central to the topic area
• archived outputs whose wording or scope implies they are being mistaken for approved truth

Mechanical integrity

Treat these as report-worthy mechanical issues even though they do not add a new scored dimension:

• alias-style wikilinks inside Markdown table cells
• unapproved pages under wiki/live/
• pending review backlog that is aging without resolution
• collaboration memory mixing with approved knowledge surfaces
• broken wikilinks in approved surfaces
• curated hubs that are stale, orphaned, or badly imbalanced toward a small portion of the approved graph
• missing or empty outputs/audit/operations.jsonl when audit scaffolding exists

Index Home Template

Use this structure for wiki/index.md.

# {Vault Title}

> [!summary] What this vault is
> `raw/` stores immutable human and agent captures.
> `wiki/drafts/` stores compiled knowledge waiting for review.
> `wiki/live/` stores approved long-term knowledge.
> `wiki/briefings/` stores per-role context built from live pages.
> `outputs/` stores reviews, Q&A, health reports, and publishable derivatives.

## Lifecycle

1. Add captures into `raw/human/` or `raw/agents/{role}/`
2. Compile into `wiki/drafts/`
3. Review and promote into `wiki/live/`
4. Rebuild affected briefings
5. Query or publish from the live layer
6. Run health checks to catch drift, stale briefings, duplicate concepts, and backlog

## Current State

- Raw captures: {count}
- Draft summaries: {count}
- Live summaries: {count}
- Live concepts: {count}
- Briefings: {count}
- Review backlog: {count}
- Archived Q&A: {count}
- Open questions: {count}

## Entry Points

- [[wiki/live/indices/INDEX]]
- [[wiki/live/indices/CONCEPTS]]
- [[wiki/live/indices/SOURCES]]
- [[wiki/briefings/researcher]]

## Draft Queue

- {pending draft 1}
- {pending draft 2}

## Open Questions

- {question 1}
- {question 2}

## Recent Activity

- {recent event 1}
- {recent event 2}

Rules:

• keep wiki/index.md content-oriented rather than chronological
• show live and draft state separately
• do not imply drafts are queryable truth
• optional governance sections such as Open Questions or Health Highlights should summarize, not replace, the canonical live indices

Lifecycle Matrix

Use this table as the shared routing contract for the package entry skill and the operational skills.

Structural diagnosis first

Prefer a structural diagnosis over user phrasing alone.

If onkb is available, run onkb --json status <vault-root> before deciding how to route.

If the shell reports onkb is not installed, install it from GitHub first, then rerun the same command:

• cargo install --locked --git https://github.com/bahayonghang/obsidian-notes-karpathy.git onkb
• repo maintainers working from a local clone may use cargo install --path . --locked instead

The CLI is the deterministic baseline for:

• setup-needed vault detection
• repair-needed vault detection
• legacy-layout migration detection
• compile-delta detection
• source-manifest drift detection
• pending review queue detection
• briefing refresh detection
• maintenance-needed integrity flags over the approved layer
• latest lifecycle health flags such as confidence gaps, supersession gaps, episodic backlog, graph gaps, procedural promotion gaps, and audit trail gaps

Routing table

Symptom overrides

These symptoms should push routing toward kb-review maintenance mode even when the structure alone might allow kb-query:

• the live notes feel contradictory or unreliable
• briefings seem wrong even after a recent review pass
• there are obvious duplicate live concepts or approved conflicts
• aliases appear split across multiple live notes
• source hashes or verification timestamps suggest provenance drift
• the approved layer renders badly in Obsidian
• archived answers have pending writeback work piling up
• archived outputs need hygiene work such as reuse drift, stale claims, or scope leakage
• collaboration memory and approved knowledge appear to be mixing
• open questions and gap reports are accumulating without clear ownership
• pages using the latest lifecycle metadata are missing confidence metadata, supersession bookkeeping, or due-date refreshes
• episodic or audit scaffolding exists but is falling behind

These symptoms should push routing toward kb-init even when raw/ and wiki/ both exist:

• AGENTS.md is missing
• wiki/index.md or wiki/log.md is missing
• the review-gated directories wiki/drafts/, wiki/live/, wiki/briefings/, or outputs/reviews/ are missing
• a vault is still clearly legacy-layout and has not been migrated

These symptoms should be surfaced as repair targets without blocking compile/query/review/health by themselves:

• only CLAUDE.md is missing
• a single noncanonical filename such as agents.md or claude.md exists but the contract is otherwise usable
• optional governance indices like QUESTIONS.md or ALIASES.md are absent

Operational reminders

• kb-init owns contract creation, migration, repair, and optional governance scaffolding.
• kb-ingest owns source registration, manifest refresh, and deferred-source visibility.
• kb-compile owns source-to-draft updates, source metadata normalization, and alias-candidate surfacing.
• kb-review owns draft promotion, rejection, contradiction handling, briefing refresh, and maintenance-mode governance passes.
• kb-query owns synthesis, local-first retrieval, archival, and static web export from the approved layer only.
• kb-render owns deterministic derivative rendering from approved knowledge.
• backward compatibility rule: old vaults do not become needs-repair just because they lack the latest lifecycle fields; this drift is surfaced through kb-review maintenance flags instead.

Memory Lifecycle

Use this reference when the bundle needs to talk about the latest lifecycle behavior without collapsing the review gate.

Core posture

• raw/** stays immutable working evidence.
• outputs/episodes/** stores episodic memory: compacted chains of work, not approved truth.
• wiki/live/** stores semantic memory: approved reusable topic knowledge.
• wiki/live/procedures/** stores procedural memory: approved workflows and repeated decision patterns.
• MEMORY.md remains collaboration/editorial context only.

Confidence

Treat confidence as explicit metadata, not an implied vibe.

Preferred fields on approved pages using the latest lifecycle metadata:

• confidence_score
• confidence_band
• support_count
• contradiction_count
• last_confirmed_at
• next_review_due_at
• decay_class

Confidence should strengthen with repeated support and weaken with time or contradiction. Old vaults can adopt this gradually; missing fields are maintenance issues, not structural repair failures.

Supersession

When a newer page replaces or narrows an older one, prefer explicit supersession over silent overwrite.

Preferred fields:

• supersedes
• superseded_by
• superseded_at
• supersession_reason

Promotion posture

• Promote to semantic memory when the durable delta is topical knowledge.
• Promote to procedural memory when the durable delta is a reusable workflow, playbook, or decision pattern.
• Keep the smallest durable delta possible: often the right move is a relationship edge, a hub update, or a question promotion rather than a brand-new page.

Episodic backlog

Episode pages should not pile up forever at consolidation_status: pending.

Common next moves:

• draft when the episode points to a missing semantic or procedural note
• health when the episode mainly exposes drift, duplicate risk, or graph weakness
• review when a concrete candidate already exists and needs a decision

Obsidian-Safe Markdown

Use this reference whenever the KB workflow writes or repairs markdown that will be rendered inside Obsidian.

Hard rules

1. Never place alias-style wikilinks such as [[note|Alias]] inside Markdown table cells. 2. In tables, use one of these instead:

• plain wikilinks without an alias, such as [[wiki/live/concepts/rag]]
• standard Markdown links, such as [RAG](../concepts/rag.md)

3. Prefer lists over tables when several cells would otherwise need many note links or display aliases. 4. Treat malformed table rendering as a mechanical correctness bug, not a cosmetic issue.

Why this exists

Markdown tables parse | before Obsidian resolves wikilink aliases. A cell like [[note|Alias]] therefore splits the row and breaks rendering even though the text looks superficially correct.

Where this rule applies

• wiki/live/indices/*.md
• wiki/index.md when it contains tables
• outputs/qa/*.md
• outputs/content/**/*
• outputs/reports/*.md
• outputs/slides/*.md
• any health-report remediation that rewrites table rows

Safe replacements

Bad:

| Concept | [[retrieval-augmented-generation|RAG]] |

Good:

| Concept | [[retrieval-augmented-generation]] |
| Concept | [RAG](../concepts/retrieval-augmented-generation.md) |

Repair posture

When you detect alias-style wikilinks inside table cells:

• treat the issue as safe to repair when the target note is clear
• preserve the visible label using a standard Markdown link when an alias matters
• mention the repair in the compile or health summary if the file was changed

Paper Ingestion Lifecycle

Use this reference when the vault includes literature or paper captures under raw/**/papers/ and the workflow needs to explain how those sources integrate without bypassing the review gate.

Core rule

Paper PDFs are valid evidence inputs, but they do not follow the normal markdown-only compile lane directly.

raw/**/papers/*.pdf should still route through paper-workbench or the dedicated paper-processing workflow before the resulting knowledge can enter normal draft compilation.

Intake posture

Papers may appear under:

• raw/human/papers/
• legacy paper subtrees inside raw during migration

The intake layer should preserve:

• source identity
• title when known
• author or venue metadata when available
• publication year / date when available
• paper handle such as DOI, arXiv ID, or other stable locator when available
• last_verified_at and possibly_outdated when useful

Normalized downstream path

1. ingest paper artifact into raw/**/papers/ 2. route through paper-processing workflow 3. produce markdown evidence notes or structured extraction outputs 4. compile those normalized outputs into wiki/drafts/ 5. review through kb-review 6. promote approved synthesis into wiki/live/

Provenance expectations

Paper-derived summaries, concepts, and entities should preserve enough provenance to answer:

• which paper artifact or extraction they came from
• which stable paper locator identifies the source
• when the source was last checked
• where uncertainty or interpretation remains

Where practical, preserve section-, page-, or excerpt-level evidence cues instead of only citing the paper at a coarse level.

Review posture

Paper-derived knowledge is often interpretation-heavy.

Review should be especially careful about:

• separating source claims from synthesis
• preserving uncertainty
• avoiding overconfident concept promotion from a single paper
• distinguishing evidence from speculation or future work sections

Query posture

Once approved, literature-derived live pages are queried the same way as other approved knowledge.

But paper artifacts or raw PDFs do not become retrieval truth directly unless a human is explicitly inspecting source evidence.

Procedure Template

Use this structure for wiki/drafts/procedures/** and wiki/live/procedures/**.

---
title: "{Procedure Title}"
procedure_id: "{procedure-slug}"
visibility_scope: private | shared
confidence_score: 0.81
confidence_band: strong | moderate | weak
support_count: 2
contradiction_count: 0
updated_at: "{datetime}"
last_reviewed_at: "{datetime}"
last_confirmed_at: "{datetime}"
next_review_due_at: "{datetime}"
decay_class: workflow
status: active | draft | conflicting
approved_at: "{datetime}"
approved_from:
  - "[[wiki/drafts/procedures/{procedure-slug}]]"
review_record: "[[outputs/reviews/procedures--{procedure-slug}]]"
trust_level: approved
sources:
  - "[[wiki/live/summaries/source-a]]"
related:
  - "[[wiki/live/concepts/related-concept]]"
---

# {Procedure Title}

## Trigger

{When this workflow should be used}

## Steps

1. {step one}
2. {step two}
3. {step three}

## Failure Modes

- {where this procedure usually goes wrong}

## Evidence

- [[wiki/live/summaries/source-a]] - {what supported this workflow}

Rules:

• Use procedures for repeated workflows, playbooks, and decision patterns.
• Keep procedures grounded in approved evidence, not just habit.
• Prefer procedural pages over semantic pages when the durable delta is "how to do it" rather than "what it means".

Profile Contract

Use this reference when the workflow needs different operating postures without changing the truth boundary.

Supported profiles

• governed-team
• standard
• fast-personal

Default: governed-team

Behavior

governed-team

• strict review gate
• briefings participate in default query scope
• health surfaces the full governance signal set

standard

• same truth boundary as governed-team
• lighter maintenance noise for non-critical backlog signals
• briefings still participate in default query scope

fast-personal

• same truth boundary as governed-team
• briefings do not participate in default query scope
• stale briefing and low-severity health noise may be delayed
• batch compile is acceptable, but draft -> review -> live still holds

Configuration posture

The profile may be stored in raw/_manifest.yaml as a top-level profile field or in wiki/index.md frontmatter as kb_profile.

Provenance and Alias Policy

Use this policy whenever compile, review, query, or health logic must decide whether two notes refer to the same underlying concept or whether a page still has trustworthy source grounding.

Goals

• keep the review gate intact
• reduce duplicate concept and entity pages
• surface cross-language overlap without inventing silent merges
• make provenance drift visible before it pollutes the approved layer
• improve relationship quality so the wiki behaves like an explorable graph instead of a pile of isolated pages

Provenance rules

• source_hash is the strongest compile-time indicator that a raw capture has changed.
• source_mtime is a fallback when a hash is unavailable.
• last_verified_at records the most recent time the workflow checked the raw source against the current draft or live representation.
• possibly_outdated is a hint that the source may need freshness review; it is not an automatic rejection.
• keep source captures immutable; editorial summaries, drafting notes, and publish artifacts should live in downstream surfaces rather than being written back into raw/.
• if a hash mismatch appears after promotion, the note should re-enter draft -> review rather than being silently rewritten in place.

Alias rules

• every durable live concept or entity should prefer one canonical_name in lowercase kebab-case
• aliases should include cross-language names, common spelling variants, and stable terminology shifts
• compile may propose alias_candidates, but review decides whether they join the approved alias set
• if two approved pages share aliases or normalized identities, health should flag them as duplicate or merge candidates rather than auto-merging them

Merge posture

• never silently merge conflicting approved pages
• merge candidates should preserve provenance edges and reviewer visibility
• cross-language overlap is a governance issue, not a reason to bypass review

Relationship posture

Prefer a small number of durable, explainable relationship types over ad hoc backlinks.

Common relationship intents include:

• supports — one page strengthens or evidences another claim
• contrasts — pages disagree or frame the issue differently
• extends — one page deepens or broadens another
• supersedes — a newer approved page should be preferred over an older framing
• related-question — a page materially participates in an unresolved or governed question thread

These relationship cues should improve navigation and synthesis quality, not become a hidden ontology project.

Query posture

• answers should prefer approved summaries and review-backed live pages for evidence trails
• aliases improve retrieval and backlink coverage, but they do not widen the truth boundary beyond wiki/live/
• source_live_pages should be recorded on substantive Q&A or publish artifacts when specific approved pages grounded the output
• writeback_candidates and followup_route should be used when archived outputs expose durable follow-up work or governance drift

Curated hubs and taxonomy posture

• use one canonical live page as the durable identity anchor for a concept or entity
• use aliases and curated hubs / topic maps to improve navigation rather than creating parallel truth pages for every wording variant
• if a cross-cutting topic needs a hub, treat that hub as a navigation surface backed by approved live pages rather than as a shortcut around provenance
• when relation edges are weak or missing, prefer strengthening links between approved pages before creating new parallel notes

Q and A Archive Template

Persist substantive research answers to outputs/qa/.

---
question: "{original-question}"
asked_at: "{datetime}"
sources:
  - "[[wiki/live/concepts/concept-a]]"
  - "[[wiki/live/entities/entity-b]]"
  - "[[wiki/live/summaries/source-b]]"
source_live_pages:
  - "[[wiki/live/concepts/concept-a]]"
  - "[[wiki/live/summaries/source-b]]"
tags:
  - qa
  - topic/subtopic
open_questions_touched:
  - "Which findings should be promoted into permanent notes?"
writeback_candidates:
  - "update [[wiki/live/concepts/concept-a]] with a sharper distinction"
writeback_status: none | pending | triaged | drafted | reviewed | rejected
followup_route: none | draft | review
confidence_posture: grounded | mixed-evidence | exploratory
compounding_value: low | medium | high
crystallized_from_episode: "[[outputs/episodes/example-episode]]"
visibility_scope: private | shared
---

# {title}

## TL;DR

{one sentence answer}

## Conclusions

{2-4 paragraphs}

## Key Findings

1. **{finding 1}** - {explanation}
   - Sources: [[wiki/live/summaries/source-b]]

2. **{finding 2}** - {explanation}
   - Sources: [[wiki/live/concepts/concept-a]], [[wiki/live/summaries/source-c]]

## Evidence Trail

- [[wiki/live/concepts/concept-a]] - {contribution}
- [[wiki/live/entities/entity-b]] - {contribution}
- [[wiki/live/summaries/source-b]] - {contribution}
- [[raw/human/articles/source-file]] - {specific excerpt or locator}

## Uncertainty

- {open question}
- {where sources disagree}
- {what new source would reduce uncertainty}

## Proposed Durable Delta

- Preferred move: {update live page | draft new page | strengthen relationships | create / expand curated hub}
- Target: {page or hub}
- Why this compounds the wiki: {future reuse, navigation gain, or reduced duplication}

## Writeback Candidates

- {concept page to update}
- {entity page to create or update}
- {new link or relationship to add}
- {hub or synthesis page to create or expand}
- {question worth promoting to a permanent concept note}

Rules:

• Archive only substantive answers.
• If the answer becomes the basis for a publishable artifact, link that artifact back here.
• If the answer reveals durable knowledge work, express that as writeback_candidates plus a concrete writeback section instead of leaving it implicit.
• If the answer is part of a longer chain of work, point it at the supporting episodic note through crystallized_from_episode.
• Prefer the smallest durable delta that improves future retrieval: sometimes the right move is a new page, but often it is a stronger related edge, a hub update, or a promoted governed question.

Query Writeback Lifecycle

Use this reference when kb-query, publish outputs, or governance maintenance needs to decide how durable follow-up work should re-enter the review-gated workflow.

Core rule

Every substantive query should either improve the wiki or explicitly record why it does not need to. This is the Karpathy compounding principle: the wiki grows richer with every source added and every question answered.

Archived Q&A and publish outputs may surface durable follow-up work, but they never mutate wiki/live/ directly.

Treat them as artifact archive:

• reusable
• inspectable
• maintenance-visible
• still outside approved truth

If an output discovers reusable long-term knowledge, the change must still re-enter through:

draft -> review -> live

If an output mainly reveals governance drift, alias problems, stale archives, or maintenance backlog, route that work to kb-review maintenance mode instead of pretending it is already approved knowledge.

Compounding doctrine: treat archived outputs as reusable working memory for the system rather than as dead-end deliverables. A good output should either stand on its own for reuse or leave behind clear next actions that help the vault become denser, better linked, and easier to query later.

Archive reuse order should stay disciplined:

1. approved live pages first 2. archived Q&A next 3. archived publish artifacts only when they already reuse approved coverage cleanly

Required writeback signals for substantive outputs

Substantive Q&A or publish artifacts should record these fields when relevant:

• source_live_pages — the approved live pages that grounded the output
• open_questions_touched — standing questions materially advanced or reframed by the output
• writeback_candidates — concrete long-term follow-up worth re-entering the wiki
• writeback_status — none | pending | triaged | drafted | reviewed | rejected
• followup_route — none | draft | review
• optional confidence_posture — when the answer should advertise uncertainty or source disagreement explicitly
• optional compounding_value — low | medium | high to indicate how strongly the artifact is expected to pay off for future reuse, navigation, or follow-up drafting
• optional crystallized_from_episode — when the answer or artifact came out of an explicit episodic note

How to choose followup_route

none

Use when the output is grounded, complete enough for archival reuse, and does not create durable follow-up work.

draft

Use when the output suggests:

• a new concept/entity/summary note
• a durable update to an approved live page
• a reusable synthesis that should be promoted only after normal review
• a new curated hub/topic page backed by approved evidence
• a creator-facing brief or publish synthesis that discovered durable knowledge worth formalizing beyond the artifact itself

review

Use when the next step is an immediate human decision on an already-prepared candidate, disputed interpretation, or promotion boundary question.

review

Use review when the next step is an immediate human decision or a governance pass on already-prepared maintenance work, including:

• writeback backlog
• alias drift or duplicate approved pages
• stale archived Q&A relative to newer live sources
• stale briefings
• recurring unresolved question clusters
• provenance drift or thin-source maintenance work
• relationship gaps where approved pages should be linked, grouped, or surfaced through a curated hub before more new prose is written

Writeback status semantics

Use these statuses as a lightweight lifecycle for durable follow-up:

• none — no durable follow-up was created
• pending — follow-up exists but nobody has triaged it yet
• triaged — next route and target are clear, but no draft or maintenance action has started
• drafted — the candidate has re-entered the draft lane or has been converted into an explicit maintenance target
• reviewed — the resulting draft or maintenance action has completed review or explicit disposition
• rejected — the follow-up was examined and deliberately not carried forward

Prefer advancing status explicitly instead of leaving old artifacts forever at pending.

Writeback candidate posture

writeback_candidates should be concrete and reviewable.

Prefer candidates such as:

• [[wiki/live/concepts/...]] to update
• a missing concept/entity page to draft
• a new durable link or relationship to capture
• a standing question worth promoting into a governed note or index
• a curated hub or coverage map that should be refreshed because repeated outputs keep touching the same topic

Avoid vague placeholders like "update the wiki later".

When substantive outputs create durable follow-up work, surface that work somewhere operators can triage repeatedly rather than leaving it stranded inside a single archived artifact. Valid surfaces include governance indices, health reports, or another maintained backlog note that points back to the archived output.

Archive backlog is therefore a normal maintenance concern, not a reason to treat archive as truth.

Relationship-first compounding

Before proposing a brand-new page, check whether the durable value is actually one of these lighter-weight moves:

• add related edges between existing live pages
• add a page to an existing topic_hub
• strengthen alias coverage for a page that is already the right canonical identity
• promote a recurring question into QUESTIONS.md
• record a missing bridge between prior approved coverage and the new artifact

Prefer the smallest durable writeback that improves future retrieval and synthesis without creating redundant pages.

Governance relationship

Archived outputs can feed governance indices and health reports, especially:

• QUESTIONS.md
• GAPS.md
• ALIASES.md

But those surfaces remain maintenance/navigation views. They do not widen the truth boundary beyond approved live pages.

Episode relationship

When an answer or publish artifact came from a broader chain of work, keep the breadcrumb:

• the episode captures the work arc
• the Q&A or content artifact captures the reusable answer
• durable knowledge still re-enters through draft -> review -> live

The episode is not the truth source. It is the reusable memory wrapper around the work that produced the artifact.

Example posture

• grounded answer with no new follow-up -> archive with followup_route: none
• answer discovers a missing long-term concept -> archive with writeback_candidates and followup_route: draft
• answer reveals duplicate aliases across approved pages -> archive with followup_route: review
• answer mainly shows that three approved pages need stronger related links and a shared hub -> archive with writeback_candidates, followup_route: review, and compounding_value: high
• answer reframes an unresolved governance question -> archive with open_questions_touched and review

Simple writeback for personal vaults

The full 6-status lifecycle (none → pending → triaged → drafted → reviewed → rejected) is valuable for team or enterprise vaults with formal review cadence. For personal vaults where the same person sources, queries, and reviews, a lighter path is usually enough:

1. Query produces an answer grounded in live pages 2. Writeback signal — the output records followup_route and writeback_candidates 3. Draft — the candidate re-enters through wiki/drafts/ (or a relationship / hub upgrade) 4. Approve — the owner reviews and promotes to wiki/live/

In this mode, pending → drafted is the common happy path. Use triaged and rejected only when the backlog grows large enough to need triage.

The key Karpathy principle still applies: every substantive query should leave the wiki at least slightly better — whether through a new page, a stronger link, an updated hub, or even just a promoted question in QUESTIONS.md.

Questions and Reflection Policy

Use this policy when the user wants open questions, synthesis, gap analysis, or reflective maintenance work without collapsing the review gate.

Core rule

Questions, gap reports, and reflection outputs may be archived directly to outputs/qa/ or outputs/health/, but they only become reusable long-term knowledge after re-entering draft -> review -> live.

Use query-writeback-lifecycle.md for the detailed field-level contract when a query or publish output discovers durable follow-up work.

Open questions

• open questions should be tracked in governance indices such as wiki/live/indices/QUESTIONS.md for mature vaults, but that live-layer index should stay grounded in approved live pages rather than archived outputs
• Q&A artifacts should record open_questions_touched when they materially advance a standing question
• unresolved gaps should be explicit rather than implied in prose
• archived outputs may contribute question signals, but they do not become approved truth on their own

Reflection posture

• reflection should start from approved live pages, not drafts or raw captures by default
• when reflection finds a new durable synthesis, capture it as a writeback candidate and set a followup_route
• when reflection finds contradiction or missing evidence, route the follow-up to health or review instead of silently rewriting live notes
• when reflection grew out of a larger chain of work, prefer pairing the archived output with an episode page instead of leaving that context stranded in chat

Follow-up routing

Use:

• none when the output is grounded and does not create durable follow-up work
• draft when the output suggests new or updated long-term knowledge that must re-enter draft -> review -> live
• review when the next action is an immediate human decision on a prepared candidate or unresolved interpretation
• health when the output primarily reveals governance drift, stale outputs, alias problems, or backlog maintenance work

Gap analysis

Useful gap signals include:

• repeated question themes across archived Q&A
• concepts with thin source support
• duplicate aliases split across multiple live pages
• stale pages in volatile domains
• briefings that keep surfacing the same unresolved evidence hole
• archived outputs with writeback_candidates that remain pending or untriaged
• topic programs or curated hubs that show repeated coverage gaps, imbalance, or over-reliance on the same prior explanation

When those signals recur, prefer moving them into a visible maintenance or editorial surface rather than leaving them scattered across one-off artifacts. A compounding wiki should make repeated open work easy to notice and easy to route.

Human involvement

• if a synthesis materially changes an approved interpretation, prefer needs-human review instead of auto-promoting confidence
• if a reflective output only summarizes existing approved knowledge, it may stay in outputs/qa/ or outputs/content/ without mutating live

Questions Template

Use this structure for wiki/live/indices/QUESTIONS.md when the user wants optional governance scaffolding.

# Open Questions

- [ ] {question 1}
- [ ] {question 2}

# Recently Resolved

- [x] {resolved question} - resolved by [[outputs/qa/{artifact}]]

Rules:

• keep this page as an index, not a substitute for review-backed concept notes
• link to approved outputs or review records when a question becomes materially resolved
• unresolved questions should feed query, health, or future compile/review work rather than bypassing the workflow

Render Template

Use this reference when generating deterministic outward-facing artifacts from approved knowledge.

Supported modes

• slides
• charts
• canvas
• report
• web

Output posture

• Slides should be Marp-compatible markdown.
• Charts should be markdown chart briefs or chart specs, not binary renders.
• Canvas outputs should be .canvas JSON files.
• Reports should be markdown.
• Web outputs should be static packages rooted at outputs/web/{slug}/index.html with local assets and manifest payloads.

Required metadata for markdown render outputs

• title
• render_mode
• source_live_pages
• followup_route

Render outputs are downstream derivatives. They do not become approved truth automatically.

Mode-specific skeletons

slides

• output path: outputs/slides/
• file type: Marp-compatible markdown
• required frontmatter extras: marp: true, paginate: true
• preferred shape: title slide -> 3-5 content slides -> provenance slide

report

• output path: outputs/reports/
• file type: markdown
• required sections: Executive Summary, Key Findings, Analysis, Provenance
• if the report is governance or drift-oriented rather than deterministic rendering, route back to kb-review

charts

• output path: outputs/charts/
• file type: markdown chart brief or spec
• required sections: Data, Spec, Interpretation
• prefer tabular data plus a small machine-readable spec block

canvas

• output path: outputs/charts/ unless the user gives a better destination
• file type: Obsidian .canvas JSON
• keep nodes grounded in approved live pages or short derived text blocks

web

• output path: outputs/web/{slug}/index.html
• owner: kb-query, not kb-render
• listed here only to make the boundary explicit

Review Template

Use this structure for outputs/reviews/*.md.

---
title: "Review Record: {Source Title}"
decision: approve | reject | needs-human
accuracy: 0.91
provenance: 0.95
conflict_risk: 0.18
composability: 0.89
fact_inference_separation: 0.90
source_integrity: 0.93
alias_alignment: 0.88
duplication_risk: 0.12
staleness_risk: 0.20
promotion_reason: "{why this should or should not persist in the long-term brain}"
reviewed_at: "{datetime}"
confidence_outcome: promote-confidence | keep-confidence | reduce-confidence
supersession_decision: none | supersede-existing | superseded-by-existing | needs-human
---

# Review Record: {Source Title}

## Inputs Reviewed

- Draft: [[wiki/drafts/summaries/{file}]]
- Raw captures:
  - [[raw/human/articles/{file}]]
- Overlapping live pages:
  - [[wiki/live/concepts/{file}]]

## Decision

- Decision: {approve | reject | needs-human}
- Why: {short reason}
- Promotion reason: {why this deserves durable retention, or why it does not}

## Governance Checks

- Source integrity: {pass | warning | fail}
- Alias alignment: {aligned | needs-merge | unresolved}
- Duplicate risk: {low | medium | high}
- Staleness risk: {low | medium | high}
- Contradictions recorded: {yes | no}

## Blocking Flags

- {flag or "none"}

## Promotion Result

- Promoted live pages:
  - [[wiki/live/summaries/{file}]]
- Rebuilt briefings:
  - [[wiki/briefings/{role}]]

Rules:

• reviewers judge the draft package, not the generating agent
• include whether fact and inference are cleanly separated enough for safe reuse
• include enough context to reproduce the decision later
• call out alias, contradiction, and duplicate concerns explicitly instead of silently merging or overwriting
• when the reviewed page participates in the latest lifecycle contract, record whether confidence increased, decayed, or caused supersession

Schema Template Notes

Keep AGENTS.md and CLAUDE.md aligned when both exist. AGENTS.md is the required contract surface; CLAUDE.md is the generated companion and should mirror it rather than introducing a second policy.

When present, MEMORY.md is the coordination surface for preferences, editorial priorities, and long-running collaboration context. It is not part of the default knowledge retrieval truth layer.

Use ISO dates whenever possible:

• date only: YYYY-MM-DD
• datetime: YYYY-MM-DDTHH:mm:ssZ

Use one property vocabulary consistently across the vault. Global property consistency matters because routing, review, briefing regeneration, integrity checks, alias matching, and stale-page detection all depend on it.

Raw capture frontmatter

---
title: "Source Title"
source: "https://example.com"
author: "Author Name"
date: 2026-04-01
type: article | paper | repo | dataset | tweet | video | book | podcast | other
tags:
  - topic/subtopic
clipped_at: 2026-04-01T12:00:00Z
last_verified_at: 2026-04-02T08:00:00Z
possibly_outdated: false
---

Rules:

• use raw/human/** for curated captures
• use raw/agents/{role}/** for untrusted agent captures
• do not add compile or review state to raw captures
• possibly_outdated is a source-quality hint, not a replacement for review judgment

Draft summary frontmatter

---
title: "Draft Summary: Source Title"
source_file: "[[raw/human/articles/2026-04-01-source-title]]"
source_hash: "stable-hash"
source_mtime: "2026-04-01T12:00:00Z"
compiled_at: "2026-04-02T08:00:00Z"
last_verified_at: "2026-04-02T08:00:00Z"
possibly_outdated: false
draft_id: "draft-source-title"
compiled_from:
  - "[[raw/human/articles/2026-04-01-source-title]]"
capture_sources:
  - "[[raw/human/articles/2026-04-01-source-title]]"
review_state: pending | promoted | rejected
review_score: 0.88
blocking_flags:
  - live_conflict
alias_candidates:
  - "value-investing"
duplicate_candidates:
  - "wiki/live/concepts/value-investing"
evidence_coverage: 0.85
uncertainty_level: medium
---

Live page frontmatter

---
title: "Source Title"
canonical_name: "value-investing"
aliases:
  - "Value Investing"
  - "价值投资"
domain_volatility: low | medium | high
approved_at: "2026-04-02T10:00:00Z"
approved_from: "[[wiki/drafts/summaries/human/articles/2026-04-01-source-title]]"
review_record: "[[outputs/reviews/source-title]]"
trust_level: approved
updated_at: "2026-04-02T10:00:00Z"
last_reviewed_at: "2026-04-02T10:00:00Z"
status: active | conflicting
sources:
  - "[[wiki/live/summaries/human/articles/2026-04-01-source-title]]"
related:
  - "[[wiki/live/concepts/review-gate]]"
---

Briefing frontmatter

---
title: "Researcher Briefing"
brief_for: "researcher"
built_from: "wiki/live/"
updated_at: "2026-04-02T11:00:00Z"
staleness_after: "2026-04-16T11:00:00Z"
source_live_pages:
  - "[[wiki/live/concepts/review-gate]]"
  - "[[wiki/live/summaries/human/articles/2026-04-01-source-title]]"
open_questions_touched:
  - "Should we split briefing freshness by role?"
---

Review record frontmatter

---
title: "Review Record: Source Title"
decision: approve | reject | needs-human
accuracy: 0.92
provenance: 0.95
conflict_risk: 0.18
composability: 0.90
fact_inference_separation: 0.90
source_integrity: 0.93
alias_alignment: 0.88
duplication_risk: 0.12
staleness_risk: 0.20
promotion_reason: "The page cleanly separates direct evidence from synthesis and is worth reusing."
reviewed_at: "2026-04-02T10:00:00Z"
---

Q&A frontmatter

---
question: "When should I rebuild briefings?"
asked_at: "2026-04-05T11:15:00Z"
sources:
  - "[[wiki/live/concepts/review-gate]]"
  - "[[wiki/live/summaries/human/articles/2026-04-01-source-title]]"
tags:
  - qa
  - review
open_questions_touched:
  - "When is a stale briefing worth rebuilding immediately?"
source_live_pages:
  - "[[wiki/live/concepts/review-gate]]"
writeback_candidates:
  - "[[wiki/live/concepts/review-gate]]"
writeback_status: pending
followup_route: draft
confidence_posture: mixed-evidence
---

Health report frontmatter

---
title: "Health Check Report"
date: "2026-04-05T12:00:00Z"
scope: "wiki/live/, wiki/briefings/, outputs/qa/, outputs/reviews/"
health_score: 84
---

Episode frontmatter

---
title: "Episode: review-gate-refresh"
episode_id: "review-gate-refresh"
memory_tier: episodic
captured_at: "2026-04-05T12:15:00Z"
episode_scope: "qa"
source_artifacts:
  - "[[outputs/qa/2026-04-05-review-gate-runtime]]"
source_live_pages:
  - "[[wiki/live/concepts/review-gate]]"
open_questions_touched:
  - "When should governance refresh happen automatically?"
writeback_candidates:
  - "expand [[wiki/live/procedures/review-gate-refresh]]"
followup_route: draft
consolidation_status: pending
visibility_scope: shared
---

Procedure frontmatter

---
title: "Review Gate Refresh Procedure"
procedure_id: "review-gate-refresh"
visibility_scope: shared
confidence_score: 0.83
confidence_band: moderate
support_count: 2
contradiction_count: 0
updated_at: "2026-04-05T12:30:00Z"
last_reviewed_at: "2026-04-05T12:30:00Z"
last_confirmed_at: "2026-04-05T12:30:00Z"
next_review_due_at: "2026-07-05T00:00:00Z"
decay_class: workflow
approved_at: "2026-04-05T12:30:00Z"
approved_from:
  - "[[wiki/drafts/procedures/review-gate-refresh]]"
review_record: "[[outputs/reviews/procedures--review-gate-refresh]]"
trust_level: approved
sources:
  - "[[wiki/live/summaries/human/articles/2026-04-05-approved-summary]]"
related:
  - "[[wiki/live/concepts/review-gate]]"
---

Naming rules

• keep raw capture filenames stable and lowercase kebab-case
• preserve relative capture structure under wiki/drafts/summaries/**
• keep promoted live slugs stable even when titles evolve
• use aliases to capture cross-language and terminology drift without creating duplicate pages
• any generated tables must obey obsidian-safe-markdown.md; never emit alias-style wikilinks inside table cells
• keep concept/entity canonical names in lowercase kebab-case when possible so duplicate detection stays deterministic
• keep procedural ids in lowercase kebab-case and align episode basenames with their archived output when possible

Search Upgrades

Default posture: stay local-first, markdown-first, metadata-aware, and auditable.

Do not jump straight to RAG or a vector database just because the user mentions AI search.

For repository or vault text search, prefer rg (ripgrep) over grep because it is faster and scales better across large markdown trees. On Windows, avoid using rg against wildcarded absolute paths; prefer exact file paths or platform-native alternatives when needed.

Retrieval ladder

Use the cheapest layer that solves the problem while preserving traceability.

1. wiki/index.md 2. wiki/live/indices/* 3. wiki/live/topics/* 4. governance indices such as QUESTIONS.md, GAPS.md, and ALIASES.md 5. role-specific wiki/briefings/* 6. prior outputs/qa/ 7. local structured / metadata-driven search 8. optional semantic retrieval only as candidate surfacing

Approved live pages remain the truth source throughout the ladder. outputs/episodes/** and outputs/health/graph-snapshot.json are candidate-retrieval surfaces only. They can improve discovery, but they never override wiki/live/** as approved truth.

Stage 1: Native markdown navigation

Use this first for small to medium vaults.

• read wiki/index.md
• read wiki/live/indices/INDEX.md, wiki/live/indices/CONCEPTS.md, and wiki/live/indices/SOURCES.md
• read wiki/live/topics/* when the request is thematic rather than source-specific
• check governance indices such as wiki/live/indices/QUESTIONS.md, GAPS.md, and ALIASES.md when they exist
• check role briefings when the request maps to a stable audience or workflow
• reuse prior outputs/qa/ when a substantive grounded answer already exists
• use ordinary file search over markdown, preferring rg when CLI search is needed
• follow real wikilinks between summaries, concepts, entities, prior Q&A, and approved question pages

This stage is enough for many vaults with hundreds of high-signal notes.

Stage 2: Obsidian-native graph and metadata affordances

Use this before introducing extra infrastructure.

• use Backlinks to inspect linked mentions and unlinked mentions
• use Properties view and property search to find notes by type, tags, author, aliases, domain_volatility, question_links, topic_hub, or other standardized metadata
• use alias coverage on concept and entity pages to improve linkability and discoverability
• use derived indices such as RECENT.md, alias maps, question registries, and gap views to surface drift

Recommend this stage when the problem is disconnected notes, weak links, metadata inconsistency, or unresolved question clusters rather than raw search scale.

Stage 3: Local structured search

Use this when plain markdown navigation is no longer enough but the user still wants local, transparent search.

Suggested upgrades:

1. qmd for local markdown search with BM25 or hybrid retrieval 2. DuckDB markdown parsing for frontmatter, links, images, and section-level analysis 3. DuckDB full-text search for vault-wide text retrieval 4. Dataview or Datacore for metadata-driven views inside Obsidian

Recommend this stage when:

• the vault has grown large enough that manual indices lag behind
• the user wants structured audits, metadata reports, section-level retrieval, or question-gap analysis
• full-text retrieval is needed but auditability still matters
• the user wants better local retrieval without jumping straight to a hosted vector stack

Stage 4: Hybrid or vector retrieval

Only suggest this when earlier stages stop being sufficient.

Use this stage when:

• the vault is very large
• semantic recall is the main bottleneck
• the user explicitly wants embeddings, reranking, or RAG infrastructure

If you suggest this stage, explain why the earlier markdown-first and metadata-first stages are no longer enough.

Semantic retrieval can help surface candidate notes, but it should not silently widen the truth boundary beyond wiki/live/.

When a local hybrid layer exists, prefer this posture:

• BM25 / local text search for lexical recall
• optional vector search for semantic candidate surfacing
• graph traversal over explicit related, supersedes, and hub membership edges
• reciprocal-rank-fusion style merge only for candidate ordering

Episodes and graph snapshots may participate in candidate surfacing, but any final synthesis should still cite approved live pages.

Decision rule

Prefer the cheapest stage that solves the user's problem while preserving traceability:

• navigation problem -> Stage 1 or 2
• metadata/reporting problem -> Stage 2 or 3
• search-scale problem -> Stage 3
• semantic-recall-at-scale problem -> Stage 4

If the user's problem is malformed indices, broken table rendering, syntactically wrong markdown, provenance drift, writeback backlog, or duplicate approved notes, do not treat it as a search-upgrade problem first. Route that work through health or repair before adding more retrieval infrastructure.

Source Manifest Contract

Use this reference whenever the workflow needs a canonical raw-source registry.

Canonical path

• raw/_manifest.yaml

This file is the user-visible source registry for the vault. It does not replace raw/; it indexes raw/.

Required fields per source entry

• source_id
• path
• source_type
• capture_origin
• source_url_or_handle
• content_hash
• first_seen_at
• last_seen_at
• ingest_status
• normalized_outputs

Optional fields may include:

• deferred_to
• metadata_path
• capture_method
• linked_assets
• source_profile

Status posture

• ready-for-compile means the source is tracked and can enter the compile lane.
• deferred means the source is tracked but must be handled by a companion workflow first.
• deferred-missing-skill means the source is valid but blocked on a missing companion skill.

Boundary rules

• Updating the manifest must not rewrite raw/** source files.
• The manifest can point at candidate downstream outputs, but it does not widen the truth boundary.
• Paper PDFs under raw/**/papers/*.pdf must be recorded in the manifest even when compile cannot process them yet.
• capture_method should help distinguish Web Clipper, browser/CDP capture, manual markdown, agent capture, or file-drop intake without changing the truth boundary.
• linked_assets should list local image or attachment paths when the markdown source depends on them.
• source_profile can record the originating creator/account/profile context when the vault needs downstream editorial consistency checks.

Draft Summary Template

Use this structure for wiki/drafts/summaries/**.

---
title: "Draft Summary: {Source Title}"
source_file: "[[{raw-link}]]"
source_hash: "{optional-hash}"
source_mtime: "{mtime}"
compiled_at: "{datetime}"
last_verified_at: "{datetime}"
possibly_outdated: false
draft_id: "{stable-draft-id}"
compiled_from:
  - "[[{raw-link}]]"
capture_sources:
  - "[[{raw-link}]]"
review_state: "pending"
review_score: 0.88
blocking_flags: []
alias_candidates:
  - "value-investing"
duplicate_candidates:
  - "wiki/live/concepts/value-investing"
accuracy: 0.90
provenance: 0.92
composability: 0.84
conflict_risk: 0.12
evidence_coverage: 0.85
uncertainty_level: low | medium | high
promotion_target: semantic | procedural
candidate_entities:
  - "entity-a"
candidate_relationships:
  - "concept-a --supports--> concept-b"
topic_candidates:
  - "topic-a"
review_package_meta: "[[wiki/drafts/indices/packages/example-package]]"
confidence_inputs:
  - "support_count=2"
  - "contradiction_count=0"
  - "last_confirmed_at={datetime}"
boundary_conditions:
  - "North America DTC market"
assumption_flags:
  - "depends on paid acquisition remaining efficient"
transfer_targets:
  - "creator-economy pricing"
---

# Draft Summary: {Source Title}

## Thesis

{one-paragraph statement of what the source is really saying}

## Compression

### Core Conclusions

- {core conclusion 1}
- {core conclusion 2}
- {core conclusion 3}

### Key Evidence

- "{quote or datapoint}" - {how it supports conclusion 1}
- "{quote or datapoint}" - {how it supports conclusion 2}

## Source Claims

- {claim the source directly supports}
- {second claim the source directly supports}

## Compiler Inferences

- {synthesis, implication, or comparison added by the compiler}
- {second inference that may need review}

## Assumption Checks

### Assumption Flags

- {assumption that must hold}
- {second assumption that may fail}

### Boundary Conditions

- {market / scale / geography / time constraint}
- {counterexample or failure mode}

## Evidence

- "{quote or concrete datapoint}" - {where it appears}
- "{second datapoint}" - {why it matters}

## Proposed Concepts

- [[wiki/drafts/concepts/concept-a]] - {relationship}
- [[wiki/drafts/concepts/concept-b]] - {relationship}

## Proposed Entities

- [[wiki/drafts/entities/entity-a]] - {relationship}

## Proposed Topics

- [[wiki/drafts/topics/topic-a]] - {browse-layer role}

## Transfer Targets

- {cross-domain analogy or migration target}
- {hub / procedure / concept candidate}

## Alias and Duplicate Signals

- Alias candidates: {candidate slugs or names}
- Duplicate candidates: {existing draft/live pages that may overlap}

## Open Questions

- {what remains uncertain}
- {what new source or review step would reduce uncertainty}

## Tensions and Review Notes

- {uncertainty, contradiction, or reason this may need human review}

Rules:

• draft summaries are reviewable evidence packages, not polished prose
• compile should follow the public 浓缩 -> 质疑 -> 对标 method instead of writing a generic abstract only
• keep provenance explicit enough that a reviewer can judge the draft without agent-specific production context
• keep direct source claims separate from compiler-added inferences
• surface alias or duplicate risk rather than silently creating competing long-term notes
• use boundary_conditions, assumption_flags, and transfer_targets as machine-readable review inputs when the source makes them visible
• use promotion_target: procedural when the durable delta should become a reusable workflow instead of another semantic page
• omit entity sections when the source does not introduce durable named entities

Taxonomy and Hubs

Use this reference when compile, review, query, or health work needs lightweight guidance on what kind of note should exist in wiki/live/, when to add relationships, and when to create a curated hub.

Goal

Improve consistency and navigation without turning the vault into a rigid ontology project.

Keep this guidance review-enforced rather than compile-enforced.

Core note classes

Summary

Use a summary page when the note primarily preserves source-backed conclusions from one capture or a tightly related capture bundle.

Good fit:

• article summaries
• source briefings
• paper takeaways
• repo walkthrough summaries

Concept

Use a concept page when the note captures a reusable idea, mechanism, or abstraction that should outlive any single source.

Good fit:

• review gate
• writeback loop
• provenance drift
• retrieval ladder

Entity

Use an entity page when the note centers on a durable named thing.

Good fit:

• people
• organizations
• projects
• tools
• libraries
• datasets

Overview

Use an overview page when the note synthesizes the high-level state of an entire topic area from approved live pages. Karpathy's LLM Wiki concept emphasizes overview.md as a birds-eye view that ties the whole knowledge area together.

Good fit:

• topic-area synthesis that evolves as the live layer grows
• research-program status pages that summarize where coverage stands
• onboarding summaries that help new readers orient before diving deeper

An overview should stay grounded in approved live pages and update when the underlying pages change. It is a synthesis view, not a shortcut around provenance.

Comparison

Use a comparison page when the note systematically contrasts two or more approved concepts, entities, or approaches side by side. Karpathy explicitly lists comparisons/ as a first-class wiki directory.

Good fit:

• tool-vs-tool or framework-vs-framework comparisons
• approach tradeoff analyses grounded in approved summaries
• methodology contrasts that recur across multiple queries

A comparison should cite the approved pages it draws from and flag where evidence is thin or contested.

Relationship-first posture

Before creating a new live page, ask whether the durable improvement is better expressed as one of these smaller moves:

• add or strengthen related links between existing pages
• add aliases to the existing canonical page
• connect a page to a topic_hub
• expand question_links for a page participating in an open thread
• update an approved summary so it points more clearly at the concept or entity pages it already supports

Prefer relationship upgrades before page proliferation when the underlying knowledge already exists.

Pattern posture

If a repeated structure or operating principle keeps appearing across approved notes, it may be worth documenting as a concept or pattern-style concept page before adding a new filesystem class.

Prefer lightweight documentation first over structural expansion.

When to create a curated hub

Create a curated hub / MOC-like page when:

• several approved pages belong to the same durable theme
• users repeatedly need a stable entry point into a topic
• navigation or onboarding suffers without a human-curated map
• aliases alone are not enough to explain how pages relate
• a creator program needs a durable planning or coverage surface that should stay navigational rather than pretending to be a new truth page
• the main missing value is synthesis of relationships across approved pages rather than new evidence

A curated hub should:

• point to approved live pages
• explain the organizing logic briefly
• remain a navigation surface, not a shortcut around provenance
• support creator planning, topic balance, or prior-coverage reuse without pretending the hub itself is new evidence
• avoid restating unsupported conclusions without linking back to the underlying approved pages
• make obvious which pages are central, adjacent, unresolved, or thinly supported

Curated hub relationship posture

To keep a compounding wiki navigable, a curated hub should usually make the underlying relationships explicit instead of just listing links.

Good hub relationships include:

• canonical entry pages for the topic
• adjacent concepts that readers often confuse
• durable entities, sources, or summaries that anchor the topic
• linked open questions, gaps, or backlog themes when the topic still has unresolved coverage debt
• prior approved coverage that new publish artifacts should reuse instead of restating from scratch

Relationship heuristics

Use related links when pages should stay separate but future readers should traverse between them quickly.

Good fit:

• adjacent mechanisms that are often confused
• a summary and the concepts it materially supports
• an entity and the concepts most central to its role
• sibling topic pages within the same hub

Prefer a hub over many pairwise related links when several pages need a stable shared map.

Prefer aliases over related when two names are really the same durable identity.

Prefer merge review over either approach when two live pages appear to duplicate the same concept or entity.

For ordinary live pages, prefer lightweight minimum relationships over a heavy ontology:

• summaries should link outward to the main concepts, entities, or hubs they materially support
• concept pages should link to nearby concepts and to a hub when the concept belongs to a broader durable program
• entity pages should link to the concepts, summaries, or hubs that explain why the entity matters

Naming posture

• keep one canonical durable identity for each approved concept or entity
• use aliases to absorb terminology variation and cross-language overlap
• avoid creating multiple live truth pages for wording variants that should share one identity
• keep hub names stable and human-browsable; they should feel like entry points, not internal implementation details

Review posture

Review should decide:

• whether a page is really a summary, concept, or entity
• whether a relationship should stay as related, become a merge, or be represented through a hub
• whether a topic deserves a curated hub
• whether overlapping pages should be merged, linked, or kept distinct

Health should surface drift, duplicates, alias collisions, weak relationship coverage, and hub maintenance needs, but should not silently reclassify notes with semantic judgment.

Topic Template

Use this reference when compile or review work creates browse-layer topic pages.

Purpose

Topic pages are the default browse layer for the wiki.

They are not shortcut truth pages. They organize approved knowledge and point to the summaries, concepts, entities, procedures, overviews, and comparisons that make a topic navigable.

Draft posture

Draft topic pages may begin as lightweight stubs compiled from repeated source packages.

Minimum draft fields:

• title
• draft_id
• review_state
• review_score
• source_refs

Live posture

Approved topic pages should:

• explain the organizing logic briefly
• point to approved live pages
• avoid restating unsupported claims without links back to approved pages
• help search and browsing, not bypass provenance

Web Export Template

Use this reference when kb-query runs in web mode to export a static browseable site from the approved live layer.

This template covers what render-template.md deliberately omits. Static web export is owned by kb-query, not kb-render, because it is a navigational surface over approved knowledge, not a deterministic outward artifact.

Output root

• package root: outputs/web/{slug}/
• entrypoint: outputs/web/{slug}/index.html
• per-page path: outputs/web/{slug}/pages/{page-slug}.html
• search manifest: outputs/web/{slug}/search.json
• asset folder: outputs/web/{slug}/assets/

A single export is self-contained. Do not cross-link between different {slug} packages.

Slug rules

• {slug} is a stable lowercase kebab-case identifier, derived from user intent or a primary live topic.
• {page-slug} mirrors the approved live page's basename, preserving kebab-case.
• Do not mint new slugs for pages that already exist under wiki/live/; reuse the live basename so future exports stay stable.
• If a live page is renamed, the export should follow — never maintain a divergent slug history.

Source boundary

• only read wiki/live/**, wiki/live/indices/**, wiki/live/topics/**, wiki/live/procedures/**, and approved wiki/briefings/**
• never read wiki/drafts/** or raw/**
• archived outputs/qa/** may be referenced only when the Q&A is already grounded in approved live pages; cite the live page, not the archive
• MEMORY.md is not a web export source

Per-page frontmatter

Each exported page must declare:

• title
• canonical_slug
• source_live_page (relative path under wiki/live/)
• exported_at
• last_source_check_at
• export_mode: web
• optional topic_hub when the page belongs to a curated hub
• optional visibility_scope when the page is intentionally private or shared

Navigation structure

• index.html shows the top-level table of contents derived from wiki/live/indices/INDEX.md or the curated hub list
• left or top nav mirrors wiki/live/indices/TOPICS.md when present, else the approved concept list
• every page carries a "source" link back to its wiki/live/ path so provenance stays one click away
• breadcrumbs follow topic -> concept -> page when the live graph supports it
• search is keyword-only; populate search.json with {title, slug, summary, tags} per page

Asset handling

• render markdown to HTML at export time; do not copy raw Obsidian-style wikilinks
• convert alias-style wikilinks into plain anchor tags pointing to the exported {page-slug}.html
• inline images and diagrams resolve through assets/
• do not pull binary assets from raw/**; use only assets already linked from approved live pages

Metadata footer

Every exported page should end with a small metadata footer:

• approved-at date
• last-reviewed-at date
• source live page link
• export run id (matches the query log entry in wiki/log.md)

Log and writeback

• append a query entry in wiki/log.md with mode: web, slug, page_count, and source_live_pages
• if the export surfaces durable follow-up (gaps, alias splits, stale pages), record them as writeback_candidates in the run log, not inside the exported HTML
• web exports must not claim or promote knowledge; they are read-only views over approved truth

Boundary with kb-render

• kb-render still owns slides, reports, chart briefs, and canvas
• kb-query owns web export
• if the user asks for "a report site", disambiguate: deterministic report goes to kb-render; browseable site stays here

Minimal output checklist

Before handing the export back to the user, confirm:

• index.html renders and links to every exported page
• every page carries the required frontmatter fields
• no draft or raw content leaked into the package
• search.json covers all exported pages
• the wiki/log.md query entry references the export