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:

Init — run kb-init to create the support layer (raw/, wiki/, outputs/, AGENTS.md)
Ingest — run kb-ingest to register raw sources into raw/_manifest.yaml
Compile — run kb-compile to build reviewable drafts
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:

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