Kb Init

KB Init

One-time setup, migration, and repair for the review-gated workflow.

Quick Start

For a fresh vault, the happy path is four steps:

1. Init — run kb-init to create the support layer (raw/, wiki/, outputs/, AGENTS.md) 2. Ingest — run kb-ingest to register raw sources into raw/_manifest.yaml 3. Compile — run kb-compile to build reviewable drafts 4. Review — run kb-review to approve drafts into the permanent wiki under wiki/live/

After that, use kb-query to ask questions, kb-render to generate deterministic outward artifacts, and kb-review maintenance mode to audit drift.

This mirrors Karpathy's LLM Wiki pattern: raw sources are immutable evidence, the LLM compiles and maintains the wiki, and you curate by sourcing documents and asking the right questions.

Read before writing

Read these shared references first:

• ../obsidian-notes-karpathy/scripts/skill-contract-registry.json
• ../obsidian-notes-karpathy/references/file-model.md
• ../obsidian-notes-karpathy/references/lifecycle-matrix.md
• ../obsidian-notes-karpathy/references/schema-template.md
• ../obsidian-notes-karpathy/references/summary-template.md
• ../obsidian-notes-karpathy/references/review-template.md
• ../obsidian-notes-karpathy/references/briefing-template.md
• ../obsidian-notes-karpathy/references/activity-log-template.md
• ../obsidian-notes-karpathy/references/index-home-template.md
• ../obsidian-notes-karpathy/references/questions-template.md
• ../obsidian-notes-karpathy/references/provenance-and-alias-policy.md
• ../obsidian-notes-karpathy/references/query-writeback-lifecycle.md
• ../obsidian-notes-karpathy/references/taxonomy-and-hubs.md
• ../obsidian-notes-karpathy/references/memory-lifecycle.md
• ../obsidian-notes-karpathy/references/graph-contract.md
• ../obsidian-notes-karpathy/references/source-manifest-contract.md
• ../obsidian-notes-karpathy/references/topic-template.md
• ../obsidian-notes-karpathy/references/profile-contract.md
• ../obsidian-notes-karpathy/references/automation-hooks.md
• ../obsidian-notes-karpathy/references/procedure-template.md
• ../obsidian-notes-karpathy/references/episode-template.md

Treat skill-contract-registry.json as the canonical source for role, baseline script, required references, and expected write surfaces.

If ../obsidian-notes-karpathy/scripts/detect_lifecycle.py exists, run it first to distinguish setup, repair, and needs-migration / legacy-layout migration.

If ../obsidian-notes-karpathy/scripts/bootstrap_review_gated_vault.py exists, use it for fresh setup and non-destructive repair scaffolding.

If ../obsidian-notes-karpathy/scripts/migrate_legacy_vault.py exists, use it for legacy single-layer vault migration so old files are preserved and the report is deterministic.

If ../obsidian-notes-karpathy/scripts/build_governance_indices.py exists and the user wants optional governance scaffolding, use it to generate starter QUESTIONS.md, GAPS.md, and ALIASES.md content after the support layer exists.

Profile choice

Surface the operating profile during init or repair:

• governed-team for the strictest default governance
• standard for lighter maintenance noise without widening truth
• fast-personal for solo use where briefings can stay out of default query scope

Persist the chosen profile in scaffolded starter files so later lifecycle and query tooling can see it deterministically.

Create or repair the canonical structure

Create the required support layer:

raw/human/{articles,papers,podcasts,repos,assets}
raw/human/data
raw/agents/{role}/
raw/_manifest.yaml
wiki/drafts/{summaries,topics,concepts,entities,procedures,overviews,comparisons,indices}
wiki/live/{summaries,topics,concepts,entities,procedures,overviews,comparisons,indices}
wiki/briefings/
wiki/index.md
wiki/log.md
outputs/reviews/
AGENTS.md
CLAUDE.md

Create downstream output directories such as outputs/qa/, outputs/health/, outputs/reports/, outputs/slides/, outputs/charts/, and outputs/content/** only when the user wants full scaffolding or the later stages need them.

Treat MEMORY.md as recommended collaboration scaffolding. It should hold preferences, editorial priorities, and coordination context, not source-grounded topic knowledge.

Optional governance scaffolding may include:

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

Optional latest-capability scaffolding may include:

• outputs/episodes/
• outputs/audit/operations.jsonl
• outputs/health/graph-snapshot.json

Migration posture

For legacy-layout vaults:

• preserve legacy content
• explain that direct wiki/summaries/ / wiki/concepts/ pages must move into wiki/live/
• scaffold the review-gated directories first
• treat migration as a repair step, not as a normal compile or query pass

Contract guarantees

• raw/ stays immutable
• kb-compile writes only to wiki/drafts/
• kb-review owns promotion into wiki/live/ and briefing refresh
• kb-query must not read drafts as truth
• AGENTS.md and CLAUDE.md stay aligned on the review-gated file model
• downstream outputs beyond outputs/reviews/ are optional scaffolding, not minimum support-layer requirements

Starter files

Create:

• wiki/index.md
• wiki/log.md
• MEMORY.md
• raw/_manifest.yaml
• wiki/live/indices/INDEX.md
• wiki/live/indices/CONCEPTS.md
• wiki/live/indices/SOURCES.md
• wiki/live/indices/TOPICS.md
• wiki/live/indices/RECENT.md
• wiki/live/indices/EDITORIAL-PRIORITIES.md
• optional wiki/live/indices/QUESTIONS.md when the user wants governance scaffolding
• optional wiki/live/indices/ENTITIES.md and RELATIONSHIPS.md when the user wants graph-friendly navigation
• at least one example briefing or a placeholder in wiki/briefings/
• a review template example in outputs/reviews/ when the user wants a demonstrable starter

Output to the user

Report:

1. what was created or migrated 2. whether a legacy-layout / needs-migration state was detected 3. what existing content was preserved 4. the next recommended command, usually kb-compile or kb-review

Vault Guidance

This Obsidian vault follows the review-gated Karpathy LLM Wiki contract.

Active Profile

• {{KB_PROFILE}}

Truth Boundary

• raw/ is immutable evidence intake.
• raw/_manifest.yaml is the canonical source registry.
• wiki/drafts/ contains reviewable, unapproved knowledge.
• wiki/live/ contains approved long-term knowledge.
• wiki/briefings/ is generated from approved live pages only.
• outputs/reviews/ is the decision ledger.
• MEMORY.md is collaboration context, not topic truth.

Safe Next Steps

1. Register new sources with kb-ingest. 2. Compile raw captures into wiki/drafts/ with kb-compile. 3. Promote only reviewed knowledge with kb-review. 4. Query or render only from approved live knowledge.

Migration Note

• If legacy wiki/summaries/, wiki/concepts/, or raw/articles/ paths still exist, treat them as migration surfaces rather than normal active layers.

{{VAULT_NAME}} Contract

This vault is a review-gated Obsidian knowledge base inspired by the Karpathy LLM Wiki pattern.

Core Rules

• Keep raw/ immutable.
• Keep raw/_manifest.yaml as the canonical source registry.
• Treat wiki/drafts/ as compiler output, not truth.
• Treat wiki/live/ as the approved brain.
• Treat wiki/briefings/ as generated runtime context from live only.
• Treat MEMORY.md as editorial and collaboration context only.

Operating Profile

• kb_profile: {{KB_PROFILE}}

Recommended Loop

1. kb-ingest 2. kb-compile 3. kb-review 4. kb-query or kb-render 5. kb-review maintenance mode

Deterministic Helpers

• Use lifecycle/status tooling before guessing the next step.
• Prefer migration tooling when legacy direct-compiled paths still exist.

Collaboration Memory

This file stores collaboration context, preferences, and editorial priorities.

Guardrails

• Do not treat this file as approved topic truth.
• Do not cite this file as evidence for domain claims.
• Use this file for preferences, workflow choices, and operator notes only.

Current Profile

• {{KB_PROFILE}}

Preferences

• Preferred output style:
• Preferred briefing roles:
• Preferred artifact formats:

Editorial Priorities

• Topic clusters to strengthen:
• Repeated questions worth turning into durable pages:
• Maintenance backlog worth revisiting:

Researcher Briefing

This briefing should be rebuilt from approved live pages during review.

Active Focus

• No approved live pages have been linked yet.

Reminder

• Use live knowledge as truth.
• Treat drafts, raw captures, and MEMORY notes as non-default retrieval surfaces.

{{VAULT_NAME}} Index

This vault uses the review-gated Karpathy LLM Wiki workflow.

Current Stage

• Start with kb-ingest when raw sources are waiting to be registered.
• Start with kb-compile after the manifest is current.
• Start with kb-review before any new knowledge becomes long-term truth.
• Start with kb-query or kb-render only after review passes.

Approved Live Indices

• [[wiki/live/indices/INDEX]]
• [[wiki/live/indices/CONCEPTS]]
• [[wiki/live/indices/SOURCES]]
• [[wiki/live/indices/TOPICS]]
• [[wiki/live/indices/RECENT]]
• [[wiki/live/indices/EDITORIAL-PRIORITIES]]

Notes

• MEMORY.md is collaboration context.
• raw/ is immutable evidence.
• wiki/live/ is the only approved truth boundary.

Alias Alignment

• No alias sets have been registered yet.

Approved Concepts

List approved concept pages here after review promotes them into wiki/live/concepts/.

Editorial Priorities

Use this page to track which approved clusters, gaps, or maintenance tasks should compound the wiki next.

Approved Entities

List approved entity pages here after review promotes them into wiki/live/entities/.

Coverage Gaps

• No approved coverage gaps have been surfaced yet.

Approved Knowledge Index

Use this page as the browse-layer home for approved knowledge.

Index Family

• [[wiki/live/indices/CONCEPTS]]
• [[wiki/live/indices/SOURCES]]
• [[wiki/live/indices/TOPICS]]
• [[wiki/live/indices/RECENT]]
• [[wiki/live/indices/EDITORIAL-PRIORITIES]]

Open Questions

• What governance scaffolding should kb-init generate?

Recently Approved Changes

Track the latest approved live edits and review outcomes here.

Relationship Index

Use this page for high-signal relationship edges and graph maintenance notes.

Approved Sources

Track the source summaries and approved evidence trail here.

Approved Topics

Use topic pages as the browse-layer entry surface over approved knowledge clusters.

Activity Log

• [{{GENERATED_AT}}] kb-init scaffold created for {{VAULT_NAME}} with profile {{KB_PROFILE}}.