wiki-init

wiki-init

Stand up a standalone LLM-maintained wiki, step by step, as a guided expert session. The developer should finish understanding exactly what was created, why it matters, and how to use it — with every artifact reviewed and tweakable.

This wiki is not a project artifact. It is a durable knowledge base about a domain and your general architecture best practices — knowledge that spans projects. It lives outside any app codebase, in its own git repo. Its audience is you, the human: the point is to build your mental model of the problem space so that when you reach /intent, you can express sharper intent.

The pattern (and the credit)

The shape here is Andrej Karpathy's "LLM Wiki" idea: rather than RAG (retrieve-augment-generate at query time), you do the synthesis once, at ingest time, into a persistent, cross-linked set of markdown pages that compound as sources accumulate. The bookkeeping that makes humans abandon wikis — updating cross-references, reconciling pages, keeping the map current — is exactly what an LLM is good at. The human curates sources and asks questions; the LLM does the maintenance. Credit the idea to Karpathy's LLM Wiki by name when you explain it.

What wiki-init ships is the hardened version of that idea — the disciplines that keep it from rotting past ~100 sources. See references/llm-wiki-pattern.md for the provenance and what we kept vs. changed, and references/hardening-lessons.md for the disciplines and why each one earns its place.

The philosophy (read this; teach it as you work)

Don't recite these — embody them, and surface the relevant one in plain language when it explains a move you're making.

• P1 — Synthesis at ingest, not at query. The whole value is that connections are drawn once when a source lands, into durable pages — not re-derived on every question. /query reads the synthesized wiki/, never the raw/ sources. If a question can't be answered from wiki/, the answer is "ingest more," not "let me go read the raw docs."
• P2 — The wiki is for the human. Pages are written to be read by you (and browsed in Obsidian), to build your model of the domain and its architecture. This is deliberately the opposite of an "AI-first vault." It is also the bright line against the project Expert, which is agent-first code memory: wiki = cross-project domain + architecture knowledge; Expert = per-project code memory.
• P3 — Cite or stay silent. Every non-trivial claim on a wiki page traces to at least one [[source]]. If you can't cite it, you don't write it — you say so and name a source to ingest. This is what makes the wiki trustworthy rather than a pile of confident guesses.
• P4 — Plan before you write; everything reversible. /ingest proposes a concrete change plan and waits for approval (unless --yolo). Combined with the wiki being its own git repo, nothing is ever an irreversible mutation — you can always see what changed and revert. Automation is "everything reversibly," not "everything always."
• P5 — Three layers, one rule each. raw/ is immutable source material (never edited, except /ingest saving a URL fetch). wiki/ is LLM-synthesized, cross-linked pages. _meta/ is the ingest log + lint reports. The layering is what lets /query trust wiki/ and lets you trace any claim back to its raw origin.
• P6 — The wiki compounds; the lint keeps it honest. Pages get rewritten as new evidence arrives (a superseded claim is updated, the old version preserved as a dated note — not silently appended-around). /lint is the periodic garbage-collector: broken links, orphans, stale claims, contradictions — surfaced for review, only the safe categories auto-fixed.
• P7 — Understanding feeds Intent. This is why you're building it. A richer wiki means a sharper /intent: you arrive at the PRD conversation already understanding the domain's concepts, the regulatory/architectural constraints, the trade-offs. Name this payoff to the user — it's the reason the phase exists.
• P8 — Transparent, shared understanding. Explain → confirm → act → take feedback. The user ends able to drive the wiki themselves and knows why each piece is there.