# Obsidian Notes Karpathy
Review-gated, multi-agent-friendly Obsidian knowledge-base skills inspired by Karpathy-style markdown wikis and extended toward a creator-ready LLM Wiki workflow.
This bundle is aimed at users who may ask for an `LLM Wiki`, a `Karpathy wiki`, an `Obsidian IDE` for notes, a `knowledge compiler`, a personal knowledge base, or a markdown-first `second brain` without knowing the internal `kb-*` command names yet.
It also accepts the simpler `Chinese-LLM-Wiki` vocabulary. Requests phrased as `来源页`, `主题页`, `实体页`, `综合页`, `output/analyses`, or `output/reports` are translated onto the review-gated contract instead of forcing the repo back into a single-layer wiki.
```text
raw/ -> immutable human + agent captures
raw/_manifest.yaml -> canonical source registry
MEMORY.md -> collaboration memory and editorial context
outputs/episodes/ -> episodic memory / crystallized work arcs
wiki/drafts/ -> compiled draft knowledge
wiki/live/ -> approved long-term brain
wiki/live/topics/ -> approved browse-layer topic maps
wiki/live/procedures/ -> approved procedural memory
wiki/briefings/ -> role-specific context generated from live
outputs/ -> reviews, Q&A, health reports, audit logs, and publishable artifacts
```
The core idea is no longer just "compile notes into a wiki". It is "separate production from judgment so unreviewed drafts never become compound retrieval truth," and make compile itself strong enough to produce creator-ready knowledge assets.
## Rust CLI
`onkb` is the deterministic Rust CLI for this bundle.
- normal lifecycle operations should use `onkb` directly
- skills remain the intelligent contract layer, but their baseline command is now `onkb`
- repo-local Python remains only as migration or repo-maintenance fallback while the Rust surface settles
Key commands:
- `onkb version`
- `onkb doctor`
- `onkb --json status <vault-root>`
- `onkb --json ingest scan <vault-root>`
- `onkb --json compile scan <vault-root>`
- `onkb --json review queue <vault-root>`
- `onkb --json query scope <vault-root>`
- `onkb --json render <vault-root> --mode <mode> --source <path>`
## Skill set
- `obsidian-notes-karpathy` - lifecycle router
- `kb-init` - initialize, repair, or migrate a vault into the review-gated layout
- `kb-ingest` - register raw sources into `raw/_manifest.yaml`
- `kb-compile` - compile raw markdown captures into `wiki/drafts/`
- `kb-review` - approve, reject, or escalate drafts; rebuild `wiki/briefings/`
- `kb-query` - canonical read-side lane for search, grounded answers, archived Q&A reuse, and static web export from `wiki/live/`
- `kb-render` - deterministic slides, reports, charts, and canvas derivatives from approved knowledge
## Companion skill matrix
| Need | Core route | Companion route |
| ----------------------------------------------------------------------------------------------------------------------- | -------------------- | --------------------------------------------------------- |
| Fresh setup, repair, or legacy migration | `kb-init` | none |
| Register raw markdown, assets, or data into the manifest | `kb-ingest` | none |
| Collect a webpage into the vault before manifest registration | not a core route yet | `web-access` or Obsidian Web Clipper |
| Compile raw markdown into drafts | `kb-compile` | none |
| Review and promote draft knowledge | `kb-review` | none |
| Query, rank approved candidates, reuse archived answers, or export a static knowledge site from approved live knowledge | `kb-query` | none |
| Render deterministic slides, reports, charts, or canvas artifacts from approved knowledge | `kb-render` | none |
| Legacy `kb-search` wording | `kb-query` | literal wording is absorbed by the canonical query skill |
| Legacy `kb-health` wording, approved-layer drift, or backlog maintenance | `kb-review` | use maintenance mode under the canonical governance skill |
| Ingest `raw/**/papers/*.pdf` | not a core route | `paper-workbench` |
The core bundle should own the review-gated lifecycle. Companion skills take over only for clearly external lanes such as paper PDFs or canvas-specific authoring.
For the vocabulary bridge from the simpler Chinese single-layer wiki model into this bundle's draft/live contract, see [Chinese-LLM-Wiki Compatibility](docs/architecture/chinese-llm-wiki-compat.md).
## Contract highlights
- `raw/` is immutable.
- treat `raw/` as the durable source library; editorial notes, Q&A, and publish artifacts belong in downstream surfaces rather than mutating source captures.
- `raw/_manifest.yaml` is the canonical source registry for tracked inputs.
- `MEMORY.md` is collaboration memory, not retrieval truth.
- `outputs/episodes/` stores episodic memory, not approved topic truth.
- `kb-compile` writes only to `wiki/drafts/`.
- raw paper PDFs under `raw/**/papers/*.pdf` remain a `paper-workbench` routing exception, not a normal `kb-compile` ingest.
- `kb-review` is the only promotion gate into `wiki/live/`.
- `wiki/live/procedures/` is the procedural-memory lane for approved workflows and playbooks.
- `wiki/live/topics/` is the browse-layer entry surface over approved knowledge clusters.
- `wiki/briefings/` is generated from approved live pages only.
- `kb-query` reads `wiki/live/`, briefings, and prior Q&A, not drafts.
- `outputs/audit/operations.jsonl` is the machine-readable audit trail for automation and derived exports.
- legacy-layout vaults are detected and should be migrated before normal operation.
- alias alignment, source integrity, stale-page checks, and question tracking are absorbed as governance rules without collapsing the review gate.
- curated hubs and creator-planning surfaces may exist, but they remain navigation/maintenance layers rather than truth-boundary shortcuts.
## Archive Surfaces
This bundle uses `archive` in two distinct senses:
- **source retention archive** - `raw/**` plus `raw/_manifest.yaml`
- **artifact archive** - durable downstream outputs under `outputs/**`
That split is intentional.
- The source retention archive means original captures stay retained and registered.
- It does **not** mean moving files into `raw/09-archive/`.
- The artifact archive is where durable answers, publish artifacts, episodes, review records, health reports, and static exports accumulate for reuse and maintenance.
The truth boundary stays the same:
- `wiki/live/**` = approved truth
- `outputs/**` = reusable archive surfaces
- archived outputs can trigger maintenance and writeback
- archived outputs do not become approved truth automatically
## Why this is not a single-layer source/concept/synthesis wiki
This package deliberately does **not** treat a freshly generated `wiki/` page as durable truth.
Instead:
- raw captures are first registered into `raw/_manifest.yaml`
- raw captures become reviewable drafts
- drafts become approved live notes only after `kb-review`
- query and publish work stay grounded in approved summaries and live pages
- health and reflection outputs surface governance work, but durable changes still re-enter draft -> review -> live
This keeps provenance visible and prevents fast ingest from silently hardening into long-term truth.
## Karpathy alignment
This project implements [Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) with one key extension: an explicit review gate.
| Karpathy's pattern | This project | Why the extension |
| ------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| Raw sources (immutable) | `raw/` + `raw/_manifest.yaml` | Added a canonical manifest for tracked intake |
| The wiki (LLM-maintained) | `wiki/drafts/` → `wiki/live/` | Split into draft and approved layers with a promotion gate |
| The schema (CLAUDE.md) | `AGENTS.md` + `CLAUDE.md` + shared `references/` | Expanded into a full contract registry |
| Ingest | `kb-ingest` + `kb-compile` | Separated source registration from draft compilation |
| Query / publish | `kb-query` + `kb-render` | Kept creator-facing prose in the read-side lane and deterministic derivatives in the render lane |
| Lint | `kb-review` maintenance mode | Made the health check a first-class governance lane |
| Index upkeep | `onkb review indices` | Retrieval-entry indices are rebuilt deterministically instead of relying on cross-session LLM sync |
| Answers filed back | `onkb compile writeback` | "Good answers can be filed back into the wiki" gets a deterministic `pending -> drafted` lane that still routes through the review gate |
The core metaphor is preserved: "Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase." The user curates sources and asks questions. The LLM handles all the bookkeeping that makes knowledge compound over time.
## Required support vs optional outputs
The required support layer is `raw/`, `wiki/drafts/`, `wiki/live/`, `wiki/briefings/`, `wiki/index.md`, `wiki/log.md`, `outputs/reviews/`, `AGENTS.md`, and `CLAUDE.md`.
Downstream output surfaces are created when the later stages need them:
- `outputs/qa/` - durable research answers from `kb-query`
- `outputs/content/` - publish artifacts from `kb-query`
- `outputs/slides/`, `outputs/reports/`, and `outputs/charts/` - deterministic derivative artifacts from `kb-render`
- `outputs/web/` - static browseable exports from `kb-query`
- `outputs/health/` - maintenance reports from `kb-review` maintenance mode
- `MEMORY.md` - recommended collaboration memory and editorial context
The archive posture across those surfaces is:
| Surface | Archive type | Truth status | Reusable | Can trigger maintenance |
| ------------------------------- | ------------------------ | ------------ | -------- | ----------------------- |
| `raw/**` + `raw/_manifest.yaml` | source retention archive | no | yes | yes |
| `outputs/qa/**` | artifact archive | no | yes | yes |
| `outputs/content/**` | artifact archive | no | yes | yes |
| `outputs/episodes/**` | artifact archive | no | yes | yes |
| `outputs/reviews/**` | artifact archive | no | yes | yes |
| `outputs/health/**` | artifact archive | no | yes | yes |
| `outputs/web/**` | artifact archive | no | yes | yes |
Optional governance indices such as `wiki/live/indices/QUESTIONS.md`, `GAPS.md`, and `ALIASES.md` may be created when the user wants richer maintenance surfaces.
Substantive answers and publish artifacts may also carry structured writeback candidates so later compile/review passes can decide whether they should feed back into the wiki. Candidates left at `writeback_status: pending` with `followup_route: draft` are picked up by `onkb --json compile writeback <vault-root>`, which scaffolds a reviewable draft grounded in the recorded approved pages and advances the status to `drafted`.
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/`
- durable approved knowledge -> `wiki/live/`
- durable approved workflows -> `wiki/live/procedures/`
- curated topic maps / planning surfaces -> `wiki/live/indices/` or approved hub pages
## Route ownership
- `kb-init` owns setup, repair, and legacy-layout migration.
- `kb-ingest` owns source registration, manifest refresh, and deferred intake surfacing.
- `kb-compile` owns raw-to-draft updates, including bootstrap `raw/*.md` captures.
- `kb-review` owns the governance lane: immediate draft promotion plus maintenance-mode drift checks, backlog pressure, provenance audits, alias drift, question/gap resurfacing, and safe mechanical fixes in approved surfaces only.
- `kb-query` reads approved live knowledge only and owns search, grounded answers, explicit `publish` mode, archived Q&A reuse, and static web export.
- `kb-render` owns deterministic derivatives from approved knowledge.
## Deterministic helpers
Rust-first CLI surface:
- `onkb version`
- `onkb doctor`
- `onkb --json doctor`
- `onkb skill install|list|show`
- `onkb --json status <vault-root>`
- `onkb --json init <vault-root> ...`
- `onkb --json migrate <vault-root> ...`
- `onkb --json ingest scan|sync <vault-root>`
- `onkb --json compile scan|build <vault-root>`
- `onkb --json compile writeback <vault-root> [--write]`
- `onkb --json review queue|lint|governance|indices|graph <vault-root>`
- `onkb --json query scope|rank <vault-root>`
- `onkb --json render <vault-root> --mode <mode> --source <path>`
Compatibility and repo-maintenance scripts:
- `skills/obsidian-notes-karpathy/scripts/skill-contract-registry.json`
- `onkb --json dev contract-validate`
- `onkb --json dev audit-skills`
- `onkb --json dev render-reference-block <skill>`
- `onkb --json dev eval-trigger [--dry-run] [--skill <name>]`
- `onkb --json dev eval-runtime [--dry-run] [--skill <name>] [--eval-id <id>] [--reuse-baseline-from <workspace>]`
Skill contracts load references in two layers, both declared canonically in `skill-contract-registry.json`: a small unconditional core set (capped at 6 files per skill, enforced by `dev contract-validate`) plus on-demand references that each carry an explicit trigger condition in the SKILL's `Load on demand` section.
## Install
```bash
cargo install --locked --git https://github.com/bahayonghang/obsidian-notes-karpathy.git onkb
onkb skill install
```
By default, `onkb skill install` installs the embedded runtime skills into the
current workspace only:
- `.claude/skills`
- `.agents/skills`
Additional local agent homes are explicit:
```bash
onkb skill install --cursor --windsurf --kiro --pi
onkb skill install --all-local
```
Global user-home installs are opt-in:
```bash
onkb skill install --global --claude --codex --gemini --agents
```
Use `--overwrite` to replace existing installed skill directories. Without it,
existing skill directories are skipped and reported in the JSON `targets[]`
payload. This command copies the embedded skills only; it does not write
bootstrap files, Cursor rules, or Kiro steering files.
For local development from a checked-out repo, use:
```bash
cargo install --path . --locked
```
If a skill step says `onkb` is not installed, use the GitHub install command above as the default fallback, then retry the same lifecycle command.
## Docs site maintenance
The contributor docs site lives under `docs/` and is built with VitePress.
- from the repo root, use `just install`, `just docs`, and `just docs-build`
- keep `docs/package-lock.json` committed when the docs toolchain changes
- the docs package uses npm `overrides` to keep transitive `vite` on a patched release line
- after changing docs dependencies, rerun `npm audit` and `npm run build` in `docs/`