Skip to content

Guides and resources for AI engineers: an agents course, five handbooks, a hands-on second-brain project and a vetted reading list.

docs: concepts, outputs, maintenance, troubleshooting

undefined-ui15c83e2ee341
diff --git a/README.md b/README.md
index 606d695..1d77b7a 100644
--- a/README.md
+++ b/README.md
@@ -99,27 +99,22 @@ them separate matters more than it sounds.
## The guide
-[Setup](docs/02-setup/README.md) is written in full: Obsidian, Claude Code,
-`CLAUDE.md`, MCP, the two-layer vault structure, project scoping, live data
-connectors, git. That plus the vault template, skills and scripts in this repo
-is everything you need to have the system running tonight.
-
-The remaining sections are being written one at a time. The
-[roadmap](docs/ROADMAP.md) lists every planned page and what it will cover, so
-you can see exactly what is coming and open a pull request against any of it.
-
-| Section | What it covers | Status |
-|---|---|---|
-| [Concepts](docs/01-concepts/README.md) | what the pattern is and why the old note systems died | partial |
-| [Setup](docs/02-setup/README.md) | Obsidian, Claude Code, `CLAUDE.md`, MCP, projects, git | **written** |
-| [Ingestion](docs/03-ingestion/README.md) | articles, video, PDFs, chat exports, voice, backfilling | **written** |
-| [Structuring](docs/04-structuring/README.md) | page types, linking rules, schema, contradictions | **written** |
-| [Graphs](docs/05-graphs/README.md) | what the graph is for, typed links, GraphRAG, metrics | **written** |
-| [Agents](docs/06-agents/README.md) | roles, schedules, hooks, guardrails | **written** |
-| [Retrieval](docs/07-retrieval/README.md) | query patterns, search, context budget | **written** |
-| [Outputs](docs/08-outputs/README.md) | writing, reports, publishing, learning | in progress |
-| [Maintenance](docs/09-maintenance/README.md) | linting, review cadence, git, privacy, scaling | in progress |
-| [Troubleshooting](docs/10-troubleshooting/README.md) | the failures everyone hits, with fixes | in progress |
+Ten sections, 77 pages, written to be followed rather than skimmed. From the
+concept through setup, capture, structure, the graph, automation, retrieval,
+publishing, and what to do when each of them breaks.
+
+| Section | What it covers |
+|---|---|
+| [Concepts](docs/01-concepts/README.md) | what the pattern is and why the old note systems died|
+| [Setup](docs/02-setup/README.md) | Obsidian, Claude Code, `CLAUDE.md`, MCP, projects, git|
+| [Ingestion](docs/03-ingestion/README.md) | articles, video, PDFs, chat exports, voice, backfilling|
+| [Structuring](docs/04-structuring/README.md) | page types, linking rules, schema, contradictions|
+| [Graphs](docs/05-graphs/README.md) | what the graph is for, typed links, GraphRAG, metrics|
+| [Agents](docs/06-agents/README.md) | roles, schedules, hooks, guardrails|
+| [Retrieval](docs/07-retrieval/README.md) | query patterns, search, context budget|
+| [Outputs](docs/08-outputs/README.md) | writing, reports, publishing, learning|
+| [Maintenance](docs/09-maintenance/README.md) | linting, review cadence, git, privacy, scaling|
+| [Troubleshooting](docs/10-troubleshooting/README.md) | the failures everyone hits, with fixes|
## Design decisions
diff --git a/docs/01-concepts/README.md b/docs/01-concepts/README.md
index 831db7e..bf534ee 100644
--- a/docs/01-concepts/README.md
+++ b/docs/01-concepts/README.md
@@ -1,22 +1,22 @@
# Concepts
-Why an LLM-maintained knowledge base beats the note system you abandoned, and what the pattern actually is.
+Why an LLM-maintained knowledge base beats the note system you abandoned, and
+what the pattern actually is.
+
+Read this section if you want to understand why the rules in the rest of the
+guide are the way they are. Skip to [Setup](../02-setup/README.md) if you would
+rather have the thing running first and understand it after.
## Pages
+- [What a second brain actually is](what-is-a-second-brain.md)
+- [The save-for-later paradox](the-save-for-later-paradox.md)
+- [The LLM wiki pattern](llm-wiki-pattern.md)
- [The two layers](two-layers.md)
-
-## Planned
-
-Being written. Outlines for each are in the [roadmap](../ROADMAP.md), and pull requests are welcome.
-
-- What a second brain actually is
-- The save-for-later paradox
-- The LLM wiki pattern
-- Why markdown and plain text
-- Zettelkasten, PARA, evergreen notes
-- Wiki vs RAG
-- What good looks like
+- [Why markdown and plain text](why-markdown-and-plain-text.md)
+- [Zettelkasten, PARA, evergreen notes](pkm-lineage.md)
+- [Wiki vs RAG](wiki-vs-rag.md)
+- [What good looks like](what-good-looks-like.md)
---
diff --git a/docs/01-concepts/llm-wiki-pattern.md b/docs/01-concepts/llm-wiki-pattern.md
new file mode 100644
index 0000000..630eb14
--- /dev/null
+++ b/docs/01-concepts/llm-wiki-pattern.md
@@ -0,0 +1,56 @@
+# The LLM wiki pattern
+
+The specific pattern this guide implements, published by Andrej Karpathy as a
+gist on 2026-04-04.
+
+The inversion in one sentence: instead of you maintaining notes and occasionally
+asking an AI about them, the AI maintains the wiki and you read it.
+
+## What the pattern specifies
+
+**The wiki is primary.** Raw sources are an archive you keep and rarely open.
+The wiki is what you and the agent both work from, written in plain language,
+one idea per page, densely linked.
+
+**Compilation, not summarization.** Each new source is integrated into existing
+pages rather than added beside them as another summary. A page about a concept
+improves as sources accumulate; it does not turn into a list of what each source
+said.
+
+**Three operations.** Ingest brings new material in. Lint keeps the structure
+sound. Query answers from the wiki. Everything else is variation on those.
+
+## Why it holds up
+
+Because it removes the one task that killed every previous system. Linking fifty
+notes to each other every time you read a paper is genuinely boring work that
+humans stop doing, and the wiki dies when the maintainer gets tired.
+
+The other reason is that it needs no infrastructure. Markdown files, wikilinks,
+an agent that can read and write files. No database, no index to keep fresh, no
+service to depend on.
+
+## Where the gist stops
+
+It describes intent, not implementation. Integrate new sources, lint
+periodically, treat the wiki as primary.
+
+The mechanics are left open, which is why every implementation of it differs.
+How integration handles contradictions, what a page must contain, when lint
+runs, who the wiki is written for. This guide's answers to those are in
+[Structuring](../04-structuring/README.md), and they are opinions, not the
+pattern itself.
+
+## What people build on top
+
+The common extensions are a journal layer, a project layer, and scheduled
+automation. This guide covers the second and third as [the two
+layers](two-layers.md) and [Agents](../06-agents/README.md).
+
+The pattern also spread quickly because the primitives are ordinary: anyone with
+an agent and a folder can run it, and the implementations are all readable
+markdown. See [resources](../../resources/repos.md) for the ones worth reading.
+
+## Next
+
+[The two layers](two-layers.md)
diff --git a/docs/01-concepts/pkm-lineage.md b/docs/01-concepts/pkm-lineage.md
new file mode 100644
index 0000000..4622e16
--- /dev/null
+++ b/docs/01-concepts/pkm-lineage.md
@@ -0,0 +1,68 @@
+# Zettelkasten, PARA, evergreen notes
+
+None of this is new. The methods people abandoned were mostly right, and it is
+worth knowing which parts of them still apply, because the good ideas came with a
+cost that has now changed.
+
+## Zettelkasten
+
+Niklas Luhmann's slip-box, popularised for a modern audience by Sönke Ahrens in
+"How to Take Smart Notes". Atomic notes, one idea each, densely cross-referenced,
+written in your own words.
+
+**Still right:** atomic notes, dense linking, rewriting in your own words rather
+than clipping quotes. All three are in this guide's [structuring
+rules](../04-structuring/README.md).
+
+**The cost:** every link was manual. Reading one paper meant deciding where it
+connected among hundreds of existing notes, which is real cognitive work and the
+reason most slip-boxes die in month three.
+
+## PARA
+
+Tiago Forte's system from "Building a Second Brain": Projects, Areas, Resources,
+Archive. Organise by actionability rather than by subject.
+
+**Still right:** the insight that project material and reference material want
+different structures. That is exactly [the two layers](two-layers.md), arrived at
+from a different direction.
+
+**The cost:** constant filing decisions, and the fact that actionability changes,
+so the same note moves between categories over time.
+
+## Evergreen notes
+
+Andy Matuschak's approach: notes written to be reread and improved over years,
+concept-oriented, densely linked, developed slowly.
+
+**Still right:** the standard for what a good concept page is. Matuschak's
+argument that notes should be written for your future self, not as a record of
+having read something, is the bar this guide's concept pages aim at.
+
+**The counterweight:** his position is that the writing is the thinking, and
+delegating it means not doing the thinking. That is a real objection to this
+whole approach and worth sitting with rather than dismissing.
+
+## What changed
+
+One thing: the maintenance is now delegable.
+
+Every system above works. Every one of them failed for the same reason, which is
+that they required a human to do boring linking work forever. An agent doing it
+does not get tired in month three.
+
+## What did not change
+
+You still have to choose what to read. You still have to decide what matters.
+The agent files and connects; it does not have taste, and a vault fed
+indiscriminately is a well-organised pile.
+
+And Matuschak's objection stands: understanding comes from writing. The way to
+keep it is to write the concept pages that matter to you yourself, and let the
+agent handle sources, entities and the linking. That split is a preference this
+guide does not enforce, and it is worth deciding deliberately rather than by
+default.
+
+## Next
+
+[Wiki vs RAG](wiki-vs-rag.md)
diff --git a/docs/01-concepts/the-save-for-later-paradox.md b/docs/01-concepts/the-save-for-later-paradox.md
new file mode 100644
index 0000000..2ffdf9c
--- /dev/null
+++ b/docs/01-concepts/the-save-for-later-paradox.md
@@ -0,0 +1,46 @@
+# The save-for-later paradox
+
+You screenshot the post. You bookmark the article. You save the video to a
+playlist named "watch later" that has four hundred items in it.
+
+You do not go back. Almost nobody does.
+
+## Why saving fails
+
+Saving feels like an action, and it discharges the feeling that made you want to
+save. The intention gets spent at the moment of saving rather than at the moment
+of reading, which is why the queue grows and the reading does not.
+
+Then retrieval costs more than it is worth. Finding the thing you saved means
+remembering that you saved it, remembering where, and searching wording you no
+longer recall. Compared to a fresh search, the saved item loses, so you search
+again and save again.
+
+And the pile itself becomes a deterrent. Four hundred unread items is not a
+resource, it is a debt you avoid looking at.
+
+## What actually changes it
+
+Not better tagging. Not a better read-later app. Not discipline, which is the
+thing that already failed.
+
+What changes it is removing the step you keep failing at. If the filing and
+connecting happen without you, the queue stops being a queue: the material is
+already processed, already linked, already reachable by asking a question in
+plain language.
+
+The retrieval cost inverts too. You no longer need to remember that you saved
+something, or where. You ask what you know about a topic, and things you had
+forgotten saving come back.
+
+## The honest limit
+
+The system does not make you read things. It processes what you feed it, and
+what you feed it is still your choice.
+
+What it does is make saving worth doing. That is a smaller claim than most
+second-brain pitches make, and it is the one that holds up after a month.
+
+## Next
+
+[The LLM wiki pattern](llm-wiki-pattern.md)
diff --git a/docs/01-concepts/what-good-looks-like.md b/docs/01-concepts/what-good-looks-like.md
new file mode 100644
index 0000000..c3cae6c
--- /dev/null
+++ b/docs/01-concepts/what-good-looks-like.md
@@ -0,0 +1,63 @@
+# What good looks like
+
+Concrete criteria, so you can tell whether yours is working rather than guessing.
+
+## The test
+
+Ask it something you half-remember reading about, months ago, that you cannot
+name precisely.
+
+If it comes back with the idea, the sources, and two related things you had
+forgotten, it works. If it returns nothing, or returns a general explanation that
+could have come from any model, it does not.
+
+## Signals of health
+
+**You reach for it before searching the web.** The strongest signal, and it
+happens on its own once the vault is dense enough.
+
+**Answers cite pages you can open,** and the pages say what the answer said.
+
+**The graph has clusters you did not plan.** Evidence it is tracking what you
+actually pay attention to rather than what you told it to.
+
+**New sources mostly update existing pages** rather than creating new ones. That
+means the vault has the concepts already and is deepening rather than sprawling.
+
+**It contradicts you occasionally,** because you have material on both sides of
+something.
+
+## Signals of trouble
+
+**Orphan rate climbing.** Ingestion has stopped linking. See
+[metrics](../05-graphs/metrics.md).
+
+**Pages that read as summaries** rather than explanations. The page contract in
+`CLAUDE.md` needs tightening.
+
+**Concept pages untouched for months while sources keep arriving.** New material
+is landing in new pages instead of updating existing ones, which produces four
+pages about one thing.
+
+**You stopped opening it.** The honest one. Usually means capture broke, not that
+the idea failed.
+
+## A realistic timeline
+
+**Week one.** Setup, ten or twenty sources. Feels like a folder with extra steps.
+This is normal and it is where most people quit.
+
+**Week two to four.** Fifty to a hundred sources. First moment of the vault
+connecting two things you read weeks apart. This is when it starts being worth
+the setup.
+
+**Month three.** A few hundred pages. It answers questions faster than you could
+by rereading, and it surfaces things you had forgotten saving.
+
+**Month six.** It knows things you do not remember learning. That is the state
+everyone describes as the payoff, and it is real, and it takes six months of
+feeding it.
+
+## Next
+
+[Setup](../02-setup/README.md).
diff --git a/docs/01-concepts/what-is-a-second-brain.md b/docs/01-concepts/what-is-a-second-brain.md
new file mode 100644
index 0000000..1778a47
--- /dev/null
+++ b/docs/01-concepts/what-is-a-second-brain.md
@@ -0,0 +1,52 @@
+# What a second brain actually is
+
+One local folder of plain text that an agent reads and writes, holding what you
+have read and understood, that you can ask questions.
+
+That is the whole definition. Everything else in this guide is detail about
+making it work.
+
+## What it is not
+
+**Not a prettier notes app.** The point is not organisation. You can organise
+notes beautifully and still never reopen them.
+
+**Not a chatbot with your PDFs attached.** Attaching documents to a chat gets you
+answers about those documents in that session. Nothing accumulates, nothing
+connects, and next week you attach them again.
+
+**Not a memory feature.** Assistants that remember facts about you are useful and
+are a different thing. This is a body of knowledge you own, that outlives any
+particular tool.
+
+## The three jobs
+
+**Capture.** Everything you read, watch and write down lands in one place with
+near-zero friction. If capture takes effort, nothing else matters, because there
+will be nothing to organise.
+
+**Connect.** New material gets linked into what is already there. This is the job
+humans stop doing after two weeks and the reason every previous note system
+failed. It is also the entire value: unconnected notes are a folder.
+
+**Answer.** You ask questions across everything at once, and get answers grounded
+in your own sources with citations you can open.
+
+## Where the value comes from
+
+Not from any single page. A page is a slightly better version of a note you could
+have written.
+
+It comes from density. At fifty sources, the vault starts connecting things you
+read months apart. At five hundred, it answers questions you could not have
+answered yourself, because nobody holds five hundred sources in their head at
+once.
+
+That is why the first two weeks feel underwhelming and why most people quit
+before the payoff. The system is not broken at thirty pages, it is just
+early. See [what good looks like](what-good-looks-like.md) for a realistic
+timeline.
+
+## Next
+
+[The save-for-later paradox](the-save-for-later-paradox.md)
diff --git a/docs/01-concepts/why-markdown-and-plain-text.md b/docs/01-concepts/why-markdown-and-plain-text.md
new file mode 100644
index 0000000..f297a95
--- /dev/null
+++ b/docs/01-concepts/why-markdown-and-plain-text.md
@@ -0,0 +1,67 @@
+# Why markdown and plain text
+
+The format looks like a detail. It decides whether the system works.
+
+## Agents handle files better than APIs
+
+An agent reading a folder does what it is best at: reading text and writing text.
+No schema to learn, no API to call correctly, no failure mode where a request
+half-succeeds.
+
+That reliability compounds over thousands of operations. A pipeline that writes
+markdown files fails in ways you can see in a diff; one that writes through an
+API fails in ways you find out about later.
+
+## Portability is not theoretical
+
+Every previous notes tool people trusted either shut down, changed pricing, or
+made export deliberately awkward.
+
+Plain files remove the question. Your vault opens in any text editor, syncs with
+any tool, and works with any agent that reads files. Switch models, switch
+editors, switch operating systems, and the vault is unaffected because it was
+never in anything.
+
+This matters more than usual here, because a second brain accumulates value over
+years. A format that traps you is a format that eventually costs you the whole
+thing.
+
+## Wikilinks as a graph format
+
+`[[Page name]]` is a two-character convention that produces a real graph, is
+readable as text, and survives every tool that does not understand it, because
+in the worst case it is still just words in a sentence.
+
+You can parse it with a regex, which is what `scripts/graph_export.py` does. Try
+that with a proprietary block reference format.
+
+## Git works on it
+
+Text diffs. That single property is what makes an agent safe to run unattended:
+every change it makes is reviewable, revertible, and attributable to a run.
+
+Binary formats and database-backed apps give you no equivalent. You either trust
+the automation completely or you do not automate.
+
+## The limits
+
+Plain text is bad at a few things, and pretending otherwise is how people end up
+frustrated.
+
+**Structured queries at scale.** Dataview covers a lot, but past a few thousand
+pages, relational questions want a real database. Export the graph rather than
+abandoning markdown; see [exporting the
+graph](../05-graphs/exporting-your-graph.md).
+
+**Rich media.** Images live beside the text as files, not in it. Diagrams are
+attachments.
+
+**Concurrent editing.** Two agents writing the same file conflict in the way
+files conflict, which is to say badly.
+
+None of those outweigh portability for a personal vault. All of them are worth
+knowing before you hit them.
+
+## Next
+
+[Zettelkasten, PARA, evergreen notes](pkm-lineage.md)
diff --git a/docs/01-concepts/wiki-vs-rag.md b/docs/01-concepts/wiki-vs-rag.md
new file mode 100644
index 0000000..a0d54fc
--- /dev/null
+++ b/docs/01-concepts/wiki-vs-rag.md
@@ -0,0 +1,60 @@
+# Wiki vs RAG
+
+The default advice for asking questions of your own documents is to embed them
+in a vector database. This guide does something else, and the reason is
+structural rather than a preference about tools.
+
+## The two approaches
+
+**RAG** stores your documents as chunks with embeddings. A question retrieves the
+most similar chunks and the model answers from them. Nothing is written; the
+corpus stays as it was.
+
+**A wiki** processes documents once, into pages an agent wrote and linked.
+Questions are answered by navigating those pages. The corpus is transformed and
+keeps improving.
+
+The difference is where the work happens. RAG does it at query time, every time,
+from scratch. A wiki does it once, at ingest, and the result is reused.
+
+## What that buys
+
+**Understanding accumulates.** The tenth source about a topic improves the page
+the first nine built. In RAG, the tenth document is just another chunk, and
+nothing gets better as the corpus grows, only larger.
+
+**Contradictions are visible.** Two documents disagreeing produce two chunks that
+may never be retrieved together. On a page, the disagreement is written down,
+dated, and unavoidable.
+
+**Answers are checkable.** The page cites sources you can open. Retrieved chunks
+are fragments without the reasoning that connected them.
+
+**No infrastructure.** No index, no re-embedding, no drift between the store and
+the files.
+
+## What it costs
+
+**Ingest is expensive.** Writing and linking pages costs model time up front,
+where RAG's ingest is nearly free.
+
+**Quality depends on the ingest.** A bad page contract produces a bad vault, and
+you find out later. RAG's failures are at query time and are more visible.
+
+**Recall depends on linking.** A page nobody linked is a page the graph cannot
+reach. RAG will find it by similarity regardless.
+
+## The honest position
+
+This trade is right for a personal, curated corpus of a few thousand pages and
+wrong for a million documents nobody organised.
+
+Which is to say it is right for a second brain and wrong for a search product,
+and most advice about RAG is written for the second case. See [adding RAG when
+you need it](../07-retrieval/rag-on-top.md) for the threshold where the answer
+flips, and [graph vs embeddings](../05-graphs/graph-vs-vectors.md) for the
+retrieval mechanics.
+
+## Next
+
+[What good looks like](what-good-looks-like.md)
diff --git a/docs/08-outputs/README.md b/docs/08-outputs/README.md
index 75cb614..e3be470 100644
--- a/docs/08-outputs/README.md
+++ b/docs/08-outputs/README.md
@@ -2,14 +2,17 @@
The vault earns its keep when things come out of it.
-## Planned
+A knowledge base that only answers questions is a reference book you built
+yourself. The point at which it starts paying for the effort is when articles,
+reports, decisions and understanding come out the other side, and when your own
+finished work goes back in.
-Being written. Outlines for each are in the [roadmap](../ROADMAP.md), and pull requests are welcome.
+## Pages
-- Writing from the vault
-- Research reports
-- Publishing and export
-- Learning from your own vault
+- [Writing from the vault](writing-from-the-vault.md)
+- [Research reports](research-reports.md)
+- [Publishing and export](publishing-and-export.md)
+- [Learning from your own vault](teaching-yourself.md)
---
diff --git a/docs/08-outputs/publishing-and-export.md b/docs/08-outputs/publishing-and-export.md
new file mode 100644
index 0000000..6b74038
--- /dev/null
+++ b/docs/08-outputs/publishing-and-export.md
@@ -0,0 +1,56 @@
+# Publishing and export
+
+Some of your vault is worth showing to other people. Most of it is not, and the
+mechanics of that split are worth setting up before you publish anything.
+
+## Deciding what is public
+
+The simplest reliable approach is an explicit opt-in: a `publish: true` field in
+frontmatter, and nothing without it ever leaves.
+
+Opt-out is the alternative and it is a mistake. Under opt-out, one forgotten flag
+publishes something private, and the failure is silent and permanent because it
+is already indexed.
+
+## Static site options
+
+Obsidian Publish is the official route and the least work. Quartz and Obsidian
+Digital Garden are the common open-source ones, both build a static site from a
+vault and both understand wikilinks and backlinks, which matters because a
+published wiki with broken links is worse than a blog.
+
+Whatever you use, check what happens to a link pointing at an unpublished page.
+It should degrade to plain text rather than to a 404.
+
+## Publishing a subset safely
+
+The pattern that works: a build step copies only `publish: true` pages into a
+separate folder, rewrites links to unpublished pages as plain text, and builds
+from that copy.
+
+Never point a publishing tool at your live vault directly. One misconfigured
+include pattern publishes everything, and there is no way to unpublish something
+that was crawled.
+
+## What publishing does to your writing
+
+A public wiki changes how you write pages, and not entirely for the better. You
+start writing for an audience: hedging more, explaining more, keeping tentative
+thoughts out.
+
+Tentative thoughts are exactly what a personal vault is for. If you publish,
+consider keeping the private vault primary and publishing a deliberately selected
+subset, rather than making the whole thing public and unconsciously sanitising
+it.
+
+## Other exports
+
+PDF and HTML for a single report, straight from markdown with pandoc. Fine for
+sharing one document.
+
+Do not export the vault as a whole to any format you cannot regenerate. The
+markdown is the artifact.
+
+## Next
+
+[Learning from your own vault](teaching-yourself.md)
diff --git a/docs/08-outputs/research-reports.md b/docs/08-outputs/research-reports.md
new file mode 100644
index 0000000..e3530d8
--- /dev/null
+++ b/docs/08-outputs/research-reports.md
@@ -0,0 +1,51 @@
+# Research reports
+
+A research report is what you produce when a question needs more than the vault
+currently holds. The vault is the starting point, not the whole answer.
+
+## Scope against what exists first
+
+```
+I need to understand how companies are deploying agent harnesses in production.
+What does my vault already cover, what is thin, and what is missing entirely?
+```
+
+That answer is your research plan. Most of the work in a good report is knowing
+what you do not need to look up, and starting from the vault means you are not
+re-reading things you read last year.
+
+## Fill the gaps deliberately
+
+Go find sources for the gaps, ingest them properly through `raw/`, and let them
+build pages the same way everything else does.
+
+Resisting the shortcut matters. Pasting a fresh article straight into the report
+draft gets the report written and leaves the vault no better, which means the
+next report on an adjacent topic starts from the same place.
+
+## Structure
+
+```
+Question
+What I found (with page citations)
+Where sources disagree
+What I could not establish
+What would change the conclusion
+```
+
+The last two sections are what make a report worth rereading. A report that
+presents only findings looks stronger and is less useful, because the reader
+cannot tell where it is load-bearing and where it is thin.
+
+## Store it as a source
+
+Reports go in `output/`, then get ingested back as sources.
+
+A report is a dated snapshot of your understanding, and having it in the vault as
+a source means later material can contradict it explicitly rather than quietly
+superseding it. See
+[supersession](../04-structuring/contradictions-and-supersession.md).
+
+## Next
+
+[Publishing and export](publishing-and-export.md)
diff --git a/docs/08-outputs/teaching-yourself.md b/docs/08-outputs/teaching-yourself.md
new file mode 100644
index 0000000..705dd7f
--- /dev/null
+++ b/docs/08-outputs/teaching-yourself.md
@@ -0,0 +1,64 @@
+# Learning from your own vault
+
+Reading something is not learning it. A vault full of well-written pages you
+never revisit is a library, and libraries do not make anyone knowledgeable.
+
+## Questions from your own pages
+
+```
+Generate ten questions from my concept pages on prediction markets. Mix recall
+and application. Do not include the answers.
+```
+
+Answer them without looking. The ones you cannot answer are things you saved and
+never actually learned, which is most of what anyone saves.
+
+This is more useful than generic quizzing because the questions come from
+material you chose, at the depth you recorded it.
+
+## Spaced repetition, without the card-writing
+
+The reason spaced repetition has low adoption is that writing cards is tedious.
+The vault removes that step: concept pages are the source material, and the agent
+can generate cards from them.
+
+The Obsidian spaced repetition plugins read cards written in your notes, so the
+cards live alongside the concept rather than in a separate app that drifts out of
+sync.
+
+Keep it to a small number of pages that actually matter. Reviewing everything you
+ever saved is a job, not a habit.
+
+## Find what you saved and did not understand
+
+```
+Which of my concept pages are written in language copied from the source rather
+than explained in my own words? Those are the ones I probably did not understand.
+```
+
+A page that reproduces the source's phrasing is a page nobody digested. That is a
+real signal, and it is invisible until you ask.
+
+## Explain it back
+
+The oldest test there is:
+
+```
+Ask me to explain [[GraphRAG]] as if to someone who has not read about it. Then
+compare what I said to my page and tell me what I left out.
+```
+
+Gaps between what you can say and what your page contains are precise, and they
+are exactly the thing rereading never reveals.
+
+## Measure learning, not collection
+
+Page count goes up whether or not you know more. What is worth tracking is
+whether you can answer questions from your own material without opening it.
+
+Once a quarter is enough. The result reliably surprises people, in both
+directions.
+
+## Next
+
+[Maintenance](../09-maintenance/README.md), for keeping all of it alive.
diff --git a/docs/08-outputs/writing-from-the-vault.md b/docs/08-outputs/writing-from-the-vault.md
new file mode 100644
index 0000000..e1bce6e
--- /dev/null
+++ b/docs/08-outputs/writing-from-the-vault.md
@@ -0,0 +1,53 @@
+# Writing from the vault
+
+Writing is where the vault stops being an input and starts being leverage. The
+research is already done, cited, and connected. What is left is the argument.
+
+## Outline from concept pages, not from a prompt
+
+```
+I want to write about why context length does not replace retrieval. Which of my
+concept pages are relevant, what do they collectively argue, and where do my
+sources disagree?
+```
+
+That gives you an outline grounded in things you read, with the weak points
+marked. Asking a model to outline the topic from scratch gives you the consensus
+view of the internet, which is what everyone else is also writing.
+
+The disagreements are the most useful part. They are where you have something to
+say that is not the consensus.
+
+## Cite your own sources
+
+Every claim in a draft traces back through a concept page to a source page to a
+URL. That chain is what makes fact-checking a five-minute job instead of an
+afternoon.
+
+It also protects you from the specific failure of writing with a model: fluent
+sentences containing invented specifics. If a number in the draft has no source
+page behind it, it did not come from your research.
+
+## Keep your voice
+
+Drafting from the vault produces the model's phrasing over your material. That is
+fine as a first pass and bad as a final one.
+
+The practical split: let the agent assemble structure and evidence, write the
+sentences yourself. Or draft with it and rewrite every paragraph. What does not
+work is publishing the assembly, which reads exactly like what it is.
+
+## Close the loop
+
+Ingest your own finished work back into the vault.
+
+Your published pieces are sources like any other: they contain your positions,
+stated clearly, at a date. Six months later the vault can tell you what you
+argued and whether you still believe it.
+
+This is the step almost everyone skips, and it is what makes the second piece in
+a domain meaningfully faster than the first.
+
+## Next
+
+[Research reports](research-reports.md)
diff --git a/docs/09-maintenance/README.md b/docs/09-maintenance/README.md
index 015c0bf..947da38 100644
--- a/docs/09-maintenance/README.md
+++ b/docs/09-maintenance/README.md
@@ -2,16 +2,18 @@
What keeps the thing alive after the novelty wears off.
-## Planned
+Month one is easy because it is new. The vault that still works in year two is
+the one where maintenance is automated, cheap, and produces something you
+actually read.
-Being written. Outlines for each are in the [roadmap](../ROADMAP.md), and pull requests are welcome.
+## Pages
-- Linting the vault
-- Review cadence
-- Versioning
-- Backups and portability
-- Privacy
-- Scaling past a thousand pages
+- [Linting the vault](lint-and-health.md)
+- [Review cadence](review-cadence.md)
+- [Versioning](versioning-with-git.md)
+- [Backups and portability](backups-and-portability.md)
+- [Privacy](privacy-and-secrets.md)
+- [Scaling past a thousand pages](scaling.md)
---
diff --git a/docs/09-maintenance/backups-and-portability.md b/docs/09-maintenance/backups-and-portability.md
new file mode 100644
index 0000000..ef26f50
--- /dev/null
+++ b/docs/09-maintenance/backups-and-portability.md
@@ -0,0 +1,61 @@
+# Backups and portability
+
+## Sync is not backup
+
+This is the whole page, and it is the mistake almost everyone makes.
+
+Sync propagates. If an automation rewrites two hundred pages badly, sync
+faithfully copies the damage to every device within seconds. If a file is
+deleted, it is deleted everywhere.
+
+Backup means a copy that does not follow. At least one, disconnected from the
+sync path.
+
+## A workable arrangement
+
+**Git remote,** private, pushed after every run. Versioned, so it covers the
+"what did it look like three weeks ago" case that a file backup does not.
+
+**Sync** for working across machines, whichever kind you already use.
+
+**A periodic archive** to external or separate cloud storage, not connected to
+either of the above. Monthly is enough.
+
+Three copies, one of which is dumb and slow, is the arrangement that survives the
+failure modes that actually happen.
+
+## Test a restore
+
+Once. Take the archive, restore it somewhere else, open it in Obsidian, and check
+the links work.
+
+Untested backups fail at a reliably bad moment, and the common failure is not
+corruption. It is discovering that the archive excluded a folder, or captured the
+vault mid-sync in a half-written state.
+
+## What you are protecting against
+
+Not disk failure, which is rare and which sync handles.
+
+The real risk is an automation that quietly did something wrong three weeks ago,
+which you notice now. That needs history, which is why git carries more of the
+load here than file backups.
+
+## Portability
+
+The vault is markdown and wikilinks, so leaving any particular tool costs
+nothing structural. What is worth checking occasionally:
+
+**Nothing important lives outside the files.** Plugin-specific metadata, canvas
+files, database exports. All fine as extras, none of it should carry knowledge
+that exists nowhere else.
+
+**Links resolve without Obsidian.** `scripts/link_check.py` verifies this, since
+it parses wikilinks itself.
+
+**The agent instructions are in the vault,** not in a chat history or an app
+setting. `CLAUDE.md`, skills and commands travel with the folder.
+
+## Next
+
+[Privacy](privacy-and-secrets.md)
diff --git a/docs/09-maintenance/lint-and-health.md b/docs/09-maintenance/lint-and-health.md
new file mode 100644
index 0000000..7fd6e69
--- /dev/null
+++ b/docs/09-maintenance/lint-and-health.md
@@ -0,0 +1,61 @@
+# Linting the vault
+
+Structural rot is silent. Nothing errors. The vault just slowly stops answering
+well because a third of its pages are unreachable and nobody noticed.
+
+## What a lint checks
+
+**Broken links.** Two distinct cases: a typo or rename, which gets fixed, and a
+genuine gap, which goes into `index.md` under Gaps.
+
+**Orphans.** Pages nothing links to. Either find where they belong and link
+them, or delete them.
+
+**Stubs.** Pages under about forty words with no links, usually a failed ingest.
+Flag for re-ingest from the original in `raw/`.
+
+**Schema violations.** Missing frontmatter, wrong type, tags outside the
+vocabulary.
+
+**Near-duplicates.** Similar titles, overlapping aliases, shared inbound links.
+
+**Index drift.** Pages missing from `index.md`, entries pointing nowhere.
+
+## Report before repairing
+
+Mechanical fixes happen automatically. Anything requiring judgement gets
+proposed and waits for you.
+
+That line matters because a linter that merges pages on its own judgement
+destroys work, and one that only reports produces a list nobody acts on. Broken
+links and schema errors are mechanical. Merges and deletions are not.
+
+## Running it
+
+```
+/lint
+```
+
+Weekly, or after any import of more than about twenty sources. Not after every
+ingest, where it costs more than it catches.
+
+Run it on a clean git state, so a wrong repair is one `git checkout` away.
+
+For a fast read without invoking the agent:
+
+```bash
+python3 scripts/link_check.py ~/brain
+```
+
+## Reading the output
+
+The counts matter more than the individual items. Three broken links after a
+week is normal. Forty means something in the ingest instructions changed and is
+producing links to pages it never creates.
+
+Track the rates over time rather than the raw numbers, since both grow with the
+vault. See [metrics](../05-graphs/metrics.md).
+
+## Next
+
+[Review cadence](review-cadence.md)
diff --git a/docs/09-maintenance/privacy-and-secrets.md b/docs/09-maintenance/privacy-and-secrets.md
new file mode 100644
index 0000000..d5eccbb
--- /dev/null
+++ b/docs/09-maintenance/privacy-and-secrets.md
@@ -0,0 +1,65 @@
+# Privacy
+
+A mature second brain is one of the highest-signal documents about a person that
+exists. Everything you read, worked on, worried about and asked, connected and
+indexed.
+
+That is the point, and it is the reason to be deliberate about what goes in and
+where it lives.
+
+## Decide at capture, not later
+
+Redaction after ingest does not work. By the time you decide something should not
+be there, it has propagated into concept pages, links and synthesis pages, and
+removing it means finding all of them.
+
+Decide before the file lands in `raw/`. See [chat
+exports](../03-ingestion/chat-exports.md), which is where this bites hardest,
+because chat history contains more than any other source and is imported in bulk.
+
+## What does not belong
+
+**Credentials of any kind.** Not because the agent leaks them, but because the
+vault gets synced, committed, backed up and occasionally shared. Every copy is
+another place the key exists.
+
+**Other people's private information.** Meeting transcripts, personal messages,
+anything told to you in confidence. Your notes are not the right home for
+someone else's confidences, and they did not consent to being ingested.
+
+**Material you are contractually bound to keep confidential.** Client work under
+NDA in a vault that syncs to a personal cloud account is a real exposure.
+
+## Separate vaults over careful filtering
+
+If you have material that must not mix, use a separate vault rather than tags or
+folders inside one.
+
+A single vault with a private section relies on every query, every export and
+every publish step respecting the boundary. Two vaults cannot leak into each
+other, and the cost is having to pick which one to open.
+
+## Local models for sensitive material
+
+If a category of material should not leave your machine at all, a local model
+handles ingestion for that vault. Quality is lower than a frontier model, which
+is the trade.
+
+Worth it for medical, legal or financial material. Usually not worth it for
+articles about software.
+
+## Publishing
+
+Explicit opt-in only. See [publishing and
+export](../08-outputs/publishing-and-export.md).
+
+## Before sharing a vault
+
+Search it for keys, run through the frontmatter for personal identifiers, and
+read the log for what was ingested from where. Once shared, it is out, and the
+graph makes it easy for a reader to assemble a picture you did not intend to
+give.
+
+## Next
+
+[Scaling past a thousand pages](scaling.md)
diff --git a/docs/09-maintenance/review-cadence.md b/docs/09-maintenance/review-cadence.md
new file mode 100644
index 0000000..28c03c1
--- /dev/null
+++ b/docs/09-maintenance/review-cadence.md
@@ -0,0 +1,65 @@
+# Review cadence
+
+Lint keeps the structure sound. Review is what keeps you in the loop, and it is
+the only maintenance task that produces something you read rather than something
+that happens.
+
+## Weekly, ten minutes
+
+The agent prepares it; you read it.
+
+```
+/review
+```
+
+What comes back: what was added, which concepts gained the most links,
+contradictions recorded and still unresolved, open questions, and three specific
+things to read or write next.
+
+The clusters are the part worth attention. Where your links went last week is
+where your attention actually was, which is reliably different from where you
+think it was.
+
+## Monthly, structurally
+
+Once a month, look at the vault rather than the week:
+
+- The four [metrics](../05-graphs/metrics.md), appended to a note so you have a
+ trend
+- Concept pages untouched in ninety days while their topic kept getting sources
+- The Gaps list in `index.md`, which is a reading list you generated without
+ trying
+- One local graph of a page you wrote recently, as a spot check on linking
+ quality
+
+## Quarterly, honestly
+
+Two questions.
+
+**What have I changed my mind about?** Only answerable because of the
+[supersession rules](../04-structuring/contradictions-and-supersession.md), and
+worth the whole system on its own.
+
+**What am I keeping that I will never use?** Archive it. A vault carrying dead
+material makes every query slightly worse, forever.
+
+## What to prune
+
+Sources for topics you no longer care about: archive rather than delete, they
+cost nothing in `raw/` and the wiki pages can go.
+
+Concept pages that never got a second source: usually means the idea was not
+actually important to you.
+
+Nothing that is linked. A page five others depend on is load-bearing regardless
+of how it reads.
+
+## Keep the review short
+
+A review that lists everything gets skimmed and then ignored. Three
+recommendations, not ten. If a week produced nothing worth reporting, one line
+saying so is the correct output.
+
+## Next
+
+[Versioning](versioning-with-git.md)
diff --git a/docs/09-maintenance/scaling.md b/docs/09-maintenance/scaling.md
new file mode 100644
index 0000000..6c713e9
--- /dev/null
+++ b/docs/09-maintenance/scaling.md
@@ -0,0 +1,71 @@
+# Scaling past a thousand pages
+
+Most of this guide assumes a vault of a few hundred to a few thousand pages,
+which is where personal vaults live for years. Past that, some things strain.
+
+## What actually breaks
+
+**Not search.** Ripgrep over ten thousand markdown files is still instant.
+
+**Not Obsidian,** although the global graph view stops being usable somewhere
+around a thousand nodes.
+
+**Retrieval economy.** The index gets long enough that reading it costs real
+context, which is the first genuine constraint.
+
+**Your attention.** A thousand pages is more than you can hold a mental map of,
+which is precisely when the vault becomes more useful and also when you stop
+noticing that parts of it have rotted.
+
+## Summary layers
+
+The fix for the index problem: one level between the master index and the pages.
+
+A short page per topic area, listing what is in it and what each page covers. The
+agent reads the master index, opens the one topic index that matters, then opens
+pages. Three cheap reads instead of one expensive one.
+
+Two levels is enough. Three means summaries of summaries, which drift from what
+they describe and get read instead of it.
+
+## Splitting vaults
+
+Split by domain when two areas genuinely do not inform each other: work and a
+hobby, two unrelated fields.
+
+Do not split by date or by size. The whole value is that old material connects to
+new, and a vault split chronologically severs exactly the connections worth
+having.
+
+The cost of splitting is that cross-domain connections stop happening, and those
+are often the interesting ones. Split late and reluctantly.
+
+## Archiving
+
+Move cold material to an `archive/` folder outside `wiki/`: still on disk, still
+searchable with ripgrep, no longer in the index or the graph.
+
+Reversible, which matters, because "cold" is a guess. A topic you archived can be
+brought back if it turns out to matter again.
+
+## Pruning what never mattered
+
+Concept pages with one source and no inbound links after a year were never
+concepts, they were paragraphs. Deleting them improves everything else by
+reducing what queries have to read past.
+
+Run this once a year, not continuously.
+
+## The honest ceiling
+
+Somewhere past ten thousand pages, a curated wiki stops being the right structure
+for a single person, because nobody can curate at that rate and the curation is
+what made it work.
+
+If you are there, either the vault has stopped being personal, or ingestion has
+been running without judgement for a long time. The second is far more common,
+and the fix is upstream, in what you feed it.
+
+## Next
+
+[Troubleshooting](../10-troubleshooting/README.md).
diff --git a/docs/09-maintenance/versioning-with-git.md b/docs/09-maintenance/versioning-with-git.md
new file mode 100644
index 0000000..401210d
--- /dev/null
+++ b/docs/09-maintenance/versioning-with-git.md
@@ -0,0 +1,65 @@
+# Versioning
+
+Git is what makes an agent safe to run unattended. Without it, a bad run is a
+mystery; with it, every change is a diff you can read and revert in one command.
+
+## Commit granularity
+
+One commit per run, with the run named:
+
+```
+ingest 2026-09-07: 4 sources, 9 pages
+lint 2026-09-07: 3 broken links, 1 merge
+```
+
+Not one commit per file, which buries the history, and not one commit per week,
+which makes reverting a single bad run impossible without losing the good ones.
+
+Scheduled tasks commit their own work as part of the run. See
+[scheduling](../06-agents/scheduled-maintenance.md).
+
+## Reading diffs of generated pages
+
+Worth doing in the first weeks, and occasionally after.
+
+You are looking for two things: pages that changed when they should not have,
+and rewrites where an update was expected. An agent quietly rewriting a page it
+was asked to append to is the kind of behaviour that only shows up in a diff.
+
+`git log --stat` after a week tells you which pages your automation touches most,
+which is usually informative.
+
+## Reverting
+
+```bash
+git revert HEAD # undo one run, keep the history
+git checkout . # discard uncommitted work
+git checkout HEAD~3 -- wiki/concepts/some-page.md # one page back
+```
+
+The middle one is the reason to commit before any large operation. A backfill
+that went wrong halfway costs you the run rather than the vault.
+
+## Branches
+
+Worth it for experiments that touch structure: a new page contract, a schema
+change, a bulk re-ingest under different instructions.
+
+```bash
+git checkout -b new-schema
+```
+
+Run it, read the result, merge or delete the branch. Doing this on `main` and
+deciding afterwards is how vaults end up in a half-migrated state that nobody
+wants to finish.
+
+## What not to commit
+
+`.obsidian/workspace*`, caches, and anything containing a key. The Local REST API
+key lives in plugin data, so check `.obsidian/plugins/` before the first push.
+
+Keep the remote private unless you have deliberately made the vault public.
+
+## Next
+
+[Backups and portability](backups-and-portability.md)
diff --git a/docs/10-troubleshooting/README.md b/docs/10-troubleshooting/README.md
index b79968f..9564e82 100644
--- a/docs/10-troubleshooting/README.md
+++ b/docs/10-troubleshooting/README.md
@@ -2,15 +2,16 @@
Concrete failures, with fixes.
-## Planned
+Every one of these is common. If your vault is doing something on this list, it
+is not because you set it up wrong in some unrecoverable way.
-Being written. Outlines for each are in the [roadmap](../ROADMAP.md), and pull requests are welcome.
+## Pages
-- The failures everyone hits
-- The agent writes garbage
-- Broken links and orphans
-- The vault got too big
-- FAQ
+- [The failures everyone hits](common-failures.md)
+- [The agent writes garbage](agent-writes-garbage.md)
+- [Broken links and orphans](broken-links.md)
+- [The vault got too big](vault-too-big.md)
+- [FAQ](faq.md)
---
diff --git a/docs/10-troubleshooting/agent-writes-garbage.md b/docs/10-troubleshooting/agent-writes-garbage.md
new file mode 100644
index 0000000..bce8bd1
--- /dev/null
+++ b/docs/10-troubleshooting/agent-writes-garbage.md
@@ -0,0 +1,62 @@
+# The agent writes garbage
+
+Pages that are technically about the right thing and useless to read.
+
+## Diagnose the source first
+
+Before touching instructions, check the input. Open the file in `raw/` and read
+it.
+
+Half of the bad pages people blame on the agent come from a bad extraction: a PDF
+whose columns interleaved, an auto-caption transcript with no punctuation, a
+clipped page that captured the cookie banner instead of the article.
+
+The agent cannot write a good page from mangled text, and it will not tell you it
+is struggling. See [PDFs](../03-ingestion/pdfs-and-books.md) and
+[transcripts](../03-ingestion/youtube-transcripts.md).
+
+## Then check CLAUDE.md
+
+If the source is clean, the page contract is the problem.
+
+The specific things that produce vague pages: no definition of what each page
+type contains, the word "summarise" anywhere, no instruction to write for a
+reader who has not seen the source, no requirement to link.
+
+Rewrite the contract with the shape spelled out. See [page
+types](../04-structuring/page-types.md).
+
+## Add an example, not another rule
+
+The highest-leverage fix and the least used. Put one good concept page in
+`CLAUDE.md`, in full, as the target.
+
+Rules describe the output abstractly and each new rule interacts with the others.
+One example communicates the target directly, and it is what a person would ask
+for if you told them to match a style.
+
+## Ask what it was working from
+
+```
+You wrote [[page]]. Which parts of the source did you use, and what did you leave
+out?
+```
+
+The answer usually identifies the problem immediately: it read a fragment, it
+could not tell what the source claimed versus reported, or the instructions
+pulled it toward summarising.
+
+## Roll back and re-run
+
+Fix the contract, revert the bad pages, re-ingest.
+
+```bash
+git checkout HEAD~1 -- wiki/
+```
+
+Do not patch the bad pages by hand. If the contract was wrong, every page from
+that run has the same flaw, and hand-fixing the three you noticed leaves the rest.
+
+## Next
+
+[Broken links and orphans](broken-links.md)
diff --git a/docs/10-troubleshooting/broken-links.md b/docs/10-troubleshooting/broken-links.md
new file mode 100644
index 0000000..372d7ac
--- /dev/null
+++ b/docs/10-troubleshooting/broken-links.md
@@ -0,0 +1,61 @@
+# Broken links and orphans
+
+```bash
+python3 scripts/link_check.py ~/brain
+```
+
+## Why renames break links
+
+Obsidian updates links when you rename inside the app. An agent renaming a file
+directly does not, and that is the most common cause of broken links in an
+agent-maintained vault.
+
+Prevent it with a rule in `CLAUDE.md`: renames update every inbound link, add the
+old name as an alias, and get recorded in `log.md`. See [naming and
+aliases](../04-structuring/naming-and-aliases.md).
+
+## Fixing in bulk
+
+Two categories, handled differently.
+
+**Typos and renames** get fixed: point the link at the right page. Safe to
+automate.
+
+**Genuine gaps**, where the target never existed, go into `index.md` under Gaps.
+Do not create empty pages to satisfy them; an empty page is worse than a
+recorded gap because it looks like coverage.
+
+Always on a clean git state, so a bad bulk fix is one command to undo.
+
+## Orphans
+
+Pages nothing links to. Three cases.
+
+**Should be linked and is not.** Find the pages that ought to reference it and
+add the links. This is the common case after a bulk import.
+
+**Genuinely standalone.** Rare and usually a sign the material does not belong in
+the wiki. Reference material and checklists belong in a project folder.
+
+**Failed ingest.** A stub that never got connected. Re-ingest from the original
+in `raw/`.
+
+## Preventing both at ingest
+
+The rule that removes most of this work: nothing is ingested until it is linked,
+in both directions, in the same run.
+
+An ingest that ends with unlinked pages is an ingest that did not finish. Enforce
+it in the skill rather than cleaning up weekly.
+
+## After a big import
+
+Always lint. A large backfill reliably produces orphans and near-duplicates,
+because the agent was moving fast through material that overlapped.
+
+Budget for it: a thousand-source import is followed by a lint pass and a merge
+review, and skipping that step is what leaves a vault permanently messy.
+
+## Next
+
+[The vault got too big](vault-too-big.md)
diff --git a/docs/10-troubleshooting/common-failures.md b/docs/10-troubleshooting/common-failures.md
new file mode 100644
index 0000000..71f4b6c
--- /dev/null
+++ b/docs/10-troubleshooting/common-failures.md
@@ -0,0 +1,61 @@
+# The failures everyone hits
+
+## The vault stalls after two weeks
+
+Almost always capture, not the system. Clipping takes three clicks instead of
+one, or the phone has no path into the vault, so material stops arriving and
+there is nothing to process.
+
+Fix the capture path, not the vault. See
+[Ingestion](../03-ingestion/README.md).
+
+The other cause is expecting the payoff too early. At thirty pages there is
+nothing to connect. See [what good looks
+like](../01-concepts/what-good-looks-like.md) for the real timeline.
+
+## Pages are summaries of summaries
+
+Source pages that summarise the article, concept pages that summarise the source
+pages. Each layer loses information and the bottom layer is what gets read.
+
+The cause is a page contract that says "summarise" anywhere in it. Concept pages
+explain an idea in plain language, in your words, standing on their own. Rewrite
+the contract in `CLAUDE.md` and re-ingest a few sources to check.
+
+## The agent rewrites work you did by hand
+
+Infuriating and preventable. Mark hand-written pages in frontmatter:
+
+```yaml
+maintained_by: human
+```
+
+And in `CLAUDE.md`: never rewrite a page marked `maintained_by: human`, only
+append links and flag issues for the owner.
+
+## Ingest quality drops as the vault grows
+
+Real, and the cause is usually context. Ingesting into a vault of three hundred
+pages means the agent should be checking what exists first, and if it is not, it
+creates new pages instead of updating.
+
+Check that ingestion reads `index.md` before writing. That one step is what keeps
+quality flat as the vault grows.
+
+## Everything connects to everything
+
+A few hub pages have accumulated every link, so the graph says nothing. Split
+the hubs into the specific ideas people are actually linking to. See [linking
+rules](../04-structuring/linking-rules.md).
+
+## You stopped opening it
+
+The honest failure. Usually capture broke months ago and the vault has been
+static, or the review is too long to read.
+
+Both are fixable. Neither is a reason to start over with a different tool, which
+is the instinct and always costs another month.
+
+## Next
+
+[The agent writes garbage](agent-writes-garbage.md)
diff --git a/docs/10-troubleshooting/faq.md b/docs/10-troubleshooting/faq.md
new file mode 100644
index 0000000..5b99b54
--- /dev/null
+++ b/docs/10-troubleshooting/faq.md
@@ -0,0 +1,68 @@
+# FAQ
+
+**Do I need MCP?**
+
+No. Claude Code started inside the vault folder reads and writes it directly.
+MCP adds the ability to reach the vault from sessions not running in it, which
+matters mainly for scheduled tasks. See [MCP for
+Obsidian](../02-setup/mcp-obsidian.md).
+
+**Does this work with agents other than Claude Code?**
+
+Yes. The vault is markdown and the skills are `SKILL.md` files, a format several
+agents read. Anything that can read and write files in a folder can maintain the
+vault; the instructions in `CLAUDE.md` may need renaming for other tools.
+
+**How much does it cost to run?**
+
+Depends entirely on volume. A daily ingest of a handful of articles is small. A
+one-time backfill of a thousand sources is not, which is why the
+[backfill](../03-ingestion/bulk-backfill.md) page insists on batches with visible
+costs.
+
+**Can I use a local model?**
+
+For ingestion of sensitive material, yes, with lower quality. Local models are
+weaker at the judgement calls that matter here: what deserves its own page, when
+two sources genuinely disagree. A workable split is a local model for private
+material and a frontier model for everything else.
+
+**Do I need Obsidian?**
+
+No. The vault is a folder of markdown files. Obsidian is a good viewer for the
+graph and has the Web Clipper, which is the strongest practical reason to use it.
+Logseq, Foam, or a plain editor all work.
+
+**What if I already have a Notion or Evernote full of notes?**
+
+Export to markdown, drop it in `raw/`, and backfill oldest first. Expect the
+export to be messy. Fix extraction before ingesting rather than hoping the agent
+copes.
+
+**How is this different from a memory feature?**
+
+Memory features remember facts about you across sessions and belong to the tool.
+This is a body of knowledge you own as files, that outlives the tool, and that
+you can read, edit and publish yourself.
+
+**Will the agent make things up?**
+
+It can, which is why every rule in [structuring](../04-structuring/README.md) is
+about attribution: claims recorded as claims, sources attached, gaps stated
+rather than filled. A page with no source behind a specific number is the thing
+to watch for.
+
+**Is the graph view actually useful or is it just pretty?**
+
+The global view is mostly pretty. The local graph is genuinely useful as a
+five-second quality check on any page. See [reading the graph
+view](../05-graphs/obsidian-graph-view.md).
+
+**How long before it is worth it?**
+
+Weeks two to four for the first real payoff, month six for the state people
+describe as the whole point.
+
+---
+
+Something missing here? Open an issue.
diff --git a/docs/10-troubleshooting/vault-too-big.md b/docs/10-troubleshooting/vault-too-big.md
new file mode 100644
index 0000000..5c682bf
--- /dev/null
+++ b/docs/10-troubleshooting/vault-too-big.md
@@ -0,0 +1,62 @@
+# The vault got too big
+
+## Symptoms
+
+Answers get slower and vaguer. The agent reads twenty pages and returns something
+general. The graph view is a hairball. You cannot remember whether a topic is
+covered, and checking takes longer than searching the web.
+
+## What it usually is not
+
+Disk, search speed, or Obsidian. Those all scale fine.
+
+What it actually is: retrieval economy. The index is long enough that reading it
+costs real context, so the agent either skips it or spends its budget there
+instead of on pages.
+
+## First, check it is size and not rot
+
+Run the [metrics](../05-graphs/metrics.md). A vault with a twenty percent orphan
+rate does not have a size problem, it has a linking problem, and splitting it
+will not help.
+
+Genuinely large and healthy looks like: low orphan rate, one dominant component,
+average degree in range, and an index over a few hundred entries.
+
+## Summary layers
+
+The first fix and usually enough. One index per topic area between the master
+index and the pages, so the agent makes three cheap reads instead of one
+expensive one. See [scaling](../09-maintenance/scaling.md).
+
+## Splitting
+
+By domain, never by date. Two vaults that genuinely do not inform each other.
+
+Accept that cross-domain connections stop happening. Those are often the
+interesting ones, which is why splitting is a late move rather than a first
+response.
+
+## Archiving
+
+Cold material to `archive/`, outside `wiki/`. Still searchable, out of the index
+and the graph, reversible.
+
+Better than deleting, because "cold" is a guess and archived material can come
+back.
+
+## Rebuild the index
+
+Sometimes the index has simply drifted: entries for pages that moved, missing
+entries for pages added by runs that failed halfway.
+
+```
+Rebuild index.md from the actual contents of wiki/. Group by type and theme, one
+line of description per entry, and list gaps at the bottom.
+```
+
+Cheap, and it fixes a surprising share of "the vault feels broken" complaints.
+
+## Next
+
+[FAQ](faq.md)
diff --git a/docs/README.md b/docs/README.md
index cfa2cf6..2816fbf 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,20 +2,20 @@
Ten sections, ordered the way you would actually build the system: understand the pattern, set it up, feed it, shape it, make the graph work, automate it, query it, get things out of it, keep it alive, and fix it when it breaks.
-Setup is written in full. The rest is being written section by section; see the [roadmap](ROADMAP.md) for what each one will cover.
+All ten sections are written. The [roadmap](ROADMAP.md) maps every page in one place, and is where to propose new ones.
-| Section | What it covers | Status |
-|---|---|---|
-| [Concepts](01-concepts/README.md) | what the pattern is and why the old note systems died | partial |
-| [Setup](02-setup/README.md) | Obsidian, Claude Code, CLAUDE.md, MCP, projects, git | **written** |
-| [Ingestion](03-ingestion/README.md) | articles, video, PDFs, chat exports, voice, backfilling | **written** |
-| [Structuring](04-structuring/README.md) | page types, linking rules, schema, contradictions | **written** |
-| [Graphs](05-graphs/README.md) | what the graph is for, typed links, GraphRAG, metrics | **written** |
-| [Agents](06-agents/README.md) | roles, schedules, hooks, guardrails | **written** |
-| [Retrieval](07-retrieval/README.md) | query patterns, search, context budget | **written** |
-| [Outputs](08-outputs/README.md) | writing, reports, publishing, learning | in progress |
-| [Maintenance](09-maintenance/README.md) | linting, review cadence, git, privacy, scaling | in progress |
-| [Troubleshooting](10-troubleshooting/README.md) | the failures everyone hits, with fixes | in progress |
+| Section | What it covers |
+|---|---|
+| [Concepts](01-concepts/README.md) | what the pattern is and why the old note systems died|
+| [Setup](02-setup/README.md) | Obsidian, Claude Code, CLAUDE.md, MCP, projects, git|
+| [Ingestion](03-ingestion/README.md) | articles, video, PDFs, chat exports, voice, backfilling|
+| [Structuring](04-structuring/README.md) | page types, linking rules, schema, contradictions|
+| [Graphs](05-graphs/README.md) | what the graph is for, typed links, GraphRAG, metrics|
+| [Agents](06-agents/README.md) | roles, schedules, hooks, guardrails|
+| [Retrieval](07-retrieval/README.md) | query patterns, search, context budget|
+| [Outputs](08-outputs/README.md) | writing, reports, publishing, learning|
+| [Maintenance](09-maintenance/README.md) | linting, review cadence, git, privacy, scaling|
+| [Troubleshooting](10-troubleshooting/README.md) | the failures everyone hits, with fixes|
---
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 78abc93..384f43f 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -1,52 +1,52 @@
# Roadmap
-What each planned page will cover. Sections marked done are written in full; the rest are outlines.
+Every section is written. This page stays as a map of what each page covers, and as the place to propose new ones.
Pull requests against any outline are welcome. Read [CONTRIBUTING.md](../CONTRIBUTING.md) first: every factual claim needs a primary source.
---
-## Concepts (1 of 7 written)
+## Concepts (done)
Why an LLM-maintained knowledge base beats the note system you abandoned, and what the pattern actually is.
-- [ ] **What a second brain actually is**
+- [x] **What a second brain actually is**
- The definition that matters here: one local, plain-text place your agent can read and write
- What it is not: a prettier Notion, a chatbot with your PDFs attached
- The three jobs it does: capture, connect, answer
- The compounding effect and why it only shows up after ~50 sources
-- [ ] **The save-for-later paradox**
+- [x] **The save-for-later paradox**
- Why you save things you never reopen
- Cost of retrieval vs cost of capture
- Where bookmarks, read-later apps and screenshots break down
- What changes when something else does the filing
-- [ ] **The LLM wiki pattern**
+- [x] **The LLM wiki pattern**
- Karpathy's llm-wiki gist (published April 4, 2026) and what it specifies
- Compilation over summarization: the wiki is primary, raw sources are the archive
- Ingest, lint, query as the three operations
- Where the gist stops and implementation begins
-- [ ] **Why markdown and plain text**
+- [x] **Why markdown and plain text**
- Agents read and write files better than they drive APIs
- Portability: no lock-in, no export step, git-friendly
- Wikilinks as a graph format that survives any tool
- Limits of plain text and when to add a database
-- [ ] **Zettelkasten, PARA, evergreen notes**
+- [x] **Zettelkasten, PARA, evergreen notes**
- What each system got right and what it demanded from you
- Why maintenance load is the thing that kills note systems
- Which parts of the old methods still apply
- What the LLM removes from the workload and what it does not
-- [ ] **Wiki vs RAG**
+- [x] **Wiki vs RAG**
- Why a personal corpus rarely needs a vector database
- Retrieval quality: structured pages vs chunk similarity
- Cost, latency and debuggability compared
- When RAG genuinely earns its place
-- [ ] **What good looks like**
+- [x] **What good looks like**
- Concrete success criteria for a working vault
- Health signals: orphan rate, link density, page freshness
- Failure signals you should catch early
- A realistic timeline for the first month
-## Setup (9 of 7 written)
+## Setup (done)
From zero to a vault your agent maintains, in one evening.
@@ -276,91 +276,91 @@ How to actually ask your vault things and get answers worth trusting.
- Summary layers
- Measuring what the agent actually read
-## Outputs (outline)
+## Outputs (done)
The vault earns its keep when things come out of it.
-- [ ] **Writing from the vault**
+- [x] **Writing from the vault**
- Outlining from concept pages
- Keeping citations to your own sources
- Voice: your notes, not the model's
- Publishing loop back into the vault
-- [ ] **Research reports**
+- [x] **Research reports**
- Scoping a question against existing pages
- Filling gaps with new ingestion
- Report structure that survives review
- Storing outputs so they become sources
-- [ ] **Publishing and export**
+- [x] **Publishing and export**
- Static site options for a public wiki
- Deciding what stays private
- HTML and PDF export
- Keeping public and private in one vault
-- [ ] **Learning from your own vault**
+- [x] **Learning from your own vault**
- Generating questions from concept pages
- Spaced repetition against your notes
- Finding what you saved but never understood
- Measuring learning instead of collecting
-## Maintenance (outline)
+## Maintenance (done)
What keeps the thing alive after the novelty wears off.
-- [ ] **Linting the vault**
+- [x] **Linting the vault**
- Broken links, orphan pages, empty stubs
- Schema violations
- Automating the lint run
- Reading a lint report
-- [ ] **Review cadence**
+- [x] **Review cadence**
- Weekly review that takes ten minutes
- Monthly structural review
- What to prune and what to archive
- Reviews that the agent prepares for you
-- [ ] **Versioning**
+- [x] **Versioning**
- Commit granularity for agent runs
- Reading diffs of generated pages
- Reverting a bad ingest
- Branching for experiments
-- [ ] **Backups and portability**
+- [x] **Backups and portability**
- Local, cloud and offline copies
- Testing a restore
- Moving to another editor or agent
- Avoiding formats that trap you
-- [ ] **Privacy**
+- [x] **Privacy**
- Deciding what never enters the vault
- Redaction before ingest
- Local models for sensitive material
- Sharing a vault safely
-- [ ] **Scaling past a thousand pages**
+- [x] **Scaling past a thousand pages**
- Where the plain-text approach strains
- Splitting vaults by domain
- Summary layers and hierarchical indexes
- Performance tuning
-## Troubleshooting (outline)
+## Troubleshooting (done)
Concrete failures, with fixes.
-- [ ] **The failures everyone hits**
+- [x] **The failures everyone hits**
- Vault stalls after two weeks
- Pages that are summaries of summaries
- The agent rewrites work you did by hand
- Ingest quality drops as the vault grows
-- [ ] **The agent writes garbage**
+- [x] **The agent writes garbage**
- Diagnosing whether it is CLAUDE.md or the source
- Tightening page contracts
- Adding examples instead of adding rules
- Rolling back and re-running
-- [ ] **Broken links and orphans**
+- [x] **Broken links and orphans**
- Why renames break wikilinks
- Bulk fixing safely
- Preventing orphans at ingest time
- Auditing after a big import
-- [ ] **The vault got too big**
+- [x] **The vault got too big**
- Symptoms
- Splitting vs summarizing
- Archiving cold material
- Rebuilding the index
-- [ ] **FAQ**
+- [x] **FAQ**
- Do I need MCP
- Does this work with other agents
- How much does it cost to run