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: ingestion

undefined-ui244e36448594
diff --git a/second-brain-os/.gitignore b/second-brain-os/.gitignore
new file mode 100644
index 0000000..04c6899
--- /dev/null
+++ b/second-brain-os/.gitignore
@@ -0,0 +1,9 @@
+.DS_Store
+.obsidian/workspace*
+.obsidian/cache
+*.pyc
+__pycache__/
+.venv/
+node_modules/
+*.graphml
+*.csv
diff --git a/second-brain-os/CONTRIBUTING.md b/second-brain-os/CONTRIBUTING.md
new file mode 100644
index 0000000..a925d02
--- /dev/null
+++ b/second-brain-os/CONTRIBUTING.md
@@ -0,0 +1,28 @@
+# Contributing
+
+## What is wanted
+
+- Fixes to the guide where it is wrong or out of date
+- Resources that are genuinely worth someone's time
+- Examples: real vault structures, real output, screenshots
+- Skills and commands that solve a problem the existing ones do not
+
+## What is not
+
+- Tool listings with no explanation of why the tool is worth using
+- Affiliate or referral links
+- Pages padded with general advice that applies to any note system
+
+## Standards
+
+Every factual claim needs a source, and the source has to be the primary one:
+the README, the paper, the release note, not somebody's summary of it. Numbers
+that appear only in secondary coverage get dropped. If two sources disagree,
+say so rather than picking the one that reads better.
+
+Write plainly. No marketing language, no emoji, no filler.
+
+## Pull requests
+
+One topic per PR. If you are adding a docs page, follow the shape of the
+existing pages in that section and update the section `README.md` index.
diff --git a/second-brain-os/LICENSE b/second-brain-os/LICENSE
new file mode 100644
index 0000000..14fac91
--- /dev/null
+++ b/second-brain-os/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/second-brain-os/README.md b/second-brain-os/README.md
new file mode 100644
index 0000000..78ddb43
--- /dev/null
+++ b/second-brain-os/README.md
@@ -0,0 +1,175 @@
+# AI Second Brain
+
+A knowledge base that an AI agent builds and maintains for you, in plain
+markdown files you own. Everything you read, watch and save gets turned into
+linked wiki pages, connected to everything already there, and you can ask it
+questions.
+
+This repo is the full version of the guide: the concepts, the setup, the vault
+template, the agent skills, the scripts, and the resources. Free, no signup,
+nothing to install beyond Obsidian and an agent.
+
+## The problem it solves
+
+You save things with the intention of coming back. You never do. Bookmarks,
+screenshots, read-later queues and half-filled Notion pages accumulate without
+compounding, because filing and linking them is boring work that humans stop
+doing after two weeks.
+
+Hand that work to an agent and the system stays alive. That is the whole idea.
+
+## Quickstart
+
+One evening. Nine steps, each with a full page behind it.
+
+```bash
+# copy the starter vault, skills, commands and agents
+git clone https://github.com/undefined-ui/second-brain-os.git
+cp -r second-brain-os/vault-template ~/brain
+
+mkdir -p ~/brain/.claude
+cp -r second-brain-os/skills ~/brain/.claude/skills
+cp -r second-brain-os/commands ~/brain/.claude/commands
+cp -r second-brain-os/agents ~/brain/.claude/agents
+
+cd ~/brain && claude
+```
+
+1. [Install Obsidian](docs/02-setup/obsidian-install-and-vault.md) and open
+ `~/brain` with "Open folder as vault"
+2. [Set up Claude Code](docs/02-setup/claude-code-setup.md), in the terminal or
+ the Code tab of the desktop app
+3. [Connect over MCP](docs/02-setup/mcp-obsidian.md) if you want the agent to
+ reach the vault from anywhere. Optional, skip it on day one
+4. [Get interviewed for your CLAUDE.md](docs/02-setup/claude-md.md) instead of
+ writing it by hand
+5. [Set up the two layers](docs/02-setup/vault-structure.md): a wiki for what
+ you know, projects for what you are doing
+6. [Scope down to one project](docs/02-setup/project-scoping.md) when you want
+ to ship something
+7. Install the [Web Clipper](https://obsidian.md/clipper), clip an article to
+ `raw/`, run `/ingest`
+8. [Connect live data](docs/02-setup/live-data.md): calendar, email, chat
+9. [Put maintenance on a schedule](docs/06-agents/scheduled-maintenance.md) and
+ wake up to a vault that filed itself
+
+Then feed it ten more sources before judging it. The graph is not interesting
+at five pages and it is hard to look away from at fifty.
+
+Full walkthrough: [Setup](docs/02-setup/README.md).
+
+## How it works
+
+```
+ you raw/ agent wiki/
+ ┌───────┐ ┌──────────────┐ ┌────────────┐ ┌──────────────┐
+ │ clip │ ──────> │ articles │ ───> │ ingest │ ───> │ sources/ │
+ │ save │ │ transcripts │ │ extract │ │ concepts/ │
+ │ dump │ │ pdfs │ │ link │ │ entities/ │
+ └───────┘ │ chat exports │ │ lint │ │ synthesis/ │
+ └──────────────┘ └────────────┘ └──────────────┘
+ │ │
+ │ ask anything │
+ └─────────────────────┘
+```
+
+Raw material is an archive you never read. The wiki is the artifact, written in
+plain language, one idea per page, densely linked. New sources update existing
+pages instead of piling up beside them, which is why the vault gets better as
+it grows rather than just bigger.
+
+Alongside the wiki sits a project layer: one folder per project, each with its
+own `CLAUDE.md` and an `Inputs / Process / Outputs / Feedback` pipeline. The
+wiki holds what you know, the projects hold what you are doing, and they feed
+each other. [The two layers](docs/01-concepts/two-layers.md) covers why keeping
+them separate matters more than it sounds.
+
+## What is in here
+
+| Folder | What it holds |
+|---|---|
+| [`docs/`](docs/README.md) | The guide. Ten sections, from the concept to troubleshooting |
+| [`vault-template/`](vault-template/) | A starter vault: wiki structure, project pipeline, `CLAUDE.md` and page templates |
+| [`skills/`](skills/README.md) | Agent skills: ingest, lint, query, review |
+| [`commands/`](commands/README.md) | Slash commands for Claude Code |
+| [`agents/`](agents/README.md) | Subagent definitions, two of them read-only by design |
+| [`scripts/`](scripts/README.md) | Dependency-free Python for link checking, stats and graph export |
+| [`resources/`](resources/README.md) | Tools, repos, papers and reading worth your time |
+| [`examples/`](examples/README.md) | Real vaults and real output |
+
+## 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 | in progress |
+| [Graphs](docs/05-graphs/README.md) | what the graph is for, typed links, GraphRAG, metrics | in progress |
+| [Agents](docs/06-agents/README.md) | roles, schedules, hooks, guardrails | in progress |
+| [Retrieval](docs/07-retrieval/README.md) | query patterns, search, context budget | in progress |
+| [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 |
+
+## Design decisions
+
+This setup is opinionated. The three rules that matter most, and why:
+
+**Nothing is ingested until it is linked.** A page that lands unconnected is
+invisible within a week. Linking is the entire value, so it happens in the same
+run or the ingest is not finished.
+
+**Contradictions are recorded, never overwritten.** When a new source disagrees
+with a page, both positions stay, with dates and sources. The history of what
+you believed and why is the one thing your vault has that a search engine does
+not.
+
+**No vector database until you need one.** A personal corpus is small and
+already structured. Structured pages plus links answer questions that chunk
+similarity cannot, at zero infrastructure cost. [When RAG earns its
+place](docs/07-retrieval/rag-on-top.md) covers the threshold.
+
+## Who this is for
+
+Anyone who reads a lot and retains less than they want to: researchers,
+engineers, writers, students, people who watch three hours of technical video a
+week and remember none of it.
+
+It is not for team wikis, it is not a Notion replacement, and it will not
+organise a vault you never add to.
+
+## Portability
+
+Everything here is markdown files, wikilinks and `SKILL.md` files. It works with
+Claude Code, and with any agent that reads files. Obsidian is a viewer for the
+graph, not a dependency. If you walk away from every tool named in this repo,
+you keep the folder and everything in it.
+
+## Contributing
+
+Corrections, resources and real examples are welcome. Read
+[CONTRIBUTING.md](CONTRIBUTING.md) first: every factual claim needs a primary
+source, and tool listings need a reason to exist.
+
+## Credit
+
+The LLM wiki pattern is Andrej Karpathy's, published as a gist on 2026-04-04.
+This repo is one implementation of it, plus the parts the gist deliberately
+leaves undefined.
+
+<!-- TODO before publishing:
+ - add the link to the original article
+ - add the direct Karpathy gist URL, verified by hand
+ - screenshots: graph view at 30 days, an example concept page -->
+
+MIT licensed.
diff --git a/second-brain-os/agents/README.md b/second-brain-os/agents/README.md
new file mode 100644
index 0000000..d68510e
--- /dev/null
+++ b/second-brain-os/agents/README.md
@@ -0,0 +1,18 @@
+# agents
+
+Subagent definitions for Claude Code. Copy into `.claude/agents/` in your
+vault.
+
+| Agent | Writes | Runs |
+|---|---|---|
+| `ingestor` | yes | when material lands in `raw/` |
+| `linker` | links only | after imports, or weekly |
+| `reviewer` | no | weekly |
+| `researcher` | no | on demand |
+
+Two of the four are read-only by design. Splitting write access this way means
+a bad research run cannot damage the vault, and it keeps the git history
+readable: every content change traces back to an ingest or a link pass.
+
+See [scheduling](../docs/06-agents/scheduled-maintenance.md) for wiring these
+to a cadence.
diff --git a/second-brain-os/agents/ingestor.md b/second-brain-os/agents/ingestor.md
new file mode 100644
index 0000000..93652f8
--- /dev/null
+++ b/second-brain-os/agents/ingestor.md
@@ -0,0 +1,11 @@
+---
+name: ingestor
+description: Processes new material in raw/ into linked wiki pages. Use when unprocessed sources are waiting.
+tools: Read, Write, Edit, Glob, Grep
+---
+
+You process new sources. Follow the `second-brain-ingest` skill exactly.
+
+You do not answer questions, restructure existing pages beyond adding links, or
+delete anything. When a source is ambiguous, write what it says and note the
+ambiguity on the page rather than resolving it yourself.
diff --git a/second-brain-os/agents/linker.md b/second-brain-os/agents/linker.md
new file mode 100644
index 0000000..1e6dad4
--- /dev/null
+++ b/second-brain-os/agents/linker.md
@@ -0,0 +1,14 @@
+---
+name: linker
+description: Finds and adds missing connections between existing wiki pages. Use after bulk imports or on a schedule.
+tools: Read, Edit, Glob, Grep
+---
+
+You connect pages that should be linked and are not.
+
+Work concept by concept. For each page, read it, search the vault for related
+material, and add links in both directions where the relationship is real.
+
+Do not create pages. Do not rewrite content. A link you add must be one the
+owner would agree with on reading the two pages side by side, because a graph
+padded with weak links is harder to use than a sparse one.
diff --git a/second-brain-os/agents/researcher.md b/second-brain-os/agents/researcher.md
new file mode 100644
index 0000000..3deb290
--- /dev/null
+++ b/second-brain-os/agents/researcher.md
@@ -0,0 +1,11 @@
+---
+name: researcher
+description: Answers a research question from the vault and flags what is missing. Use for questions that span many pages.
+tools: Read, Glob, Grep
+---
+
+You answer questions from the vault, following the `second-brain-query` skill.
+
+You are read-only. When the vault cannot answer, say what is missing and name
+the kind of source that would fill the gap. Do not fill the gap from your own
+knowledge without labelling it clearly as outside the vault.
diff --git a/second-brain-os/agents/reviewer.md b/second-brain-os/agents/reviewer.md
new file mode 100644
index 0000000..b70856f
--- /dev/null
+++ b/second-brain-os/agents/reviewer.md
@@ -0,0 +1,10 @@
+---
+name: reviewer
+description: Produces the periodic review of what the vault learned. Use weekly or when asked what changed.
+tools: Read, Glob, Grep
+---
+
+You are read-only. You never modify the vault.
+
+Follow the `second-brain-review` skill. Your output goes to the owner, not into
+the wiki, unless they ask you to save it to `output/`.
diff --git a/second-brain-os/assets/.gitkeep b/second-brain-os/assets/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/second-brain-os/commands/README.md b/second-brain-os/commands/README.md
new file mode 100644
index 0000000..4e8d11a
--- /dev/null
+++ b/second-brain-os/commands/README.md
@@ -0,0 +1,15 @@
+# commands
+
+Slash commands for Claude Code. Copy them into `.claude/commands/` inside your
+vault:
+
+```bash
+cp commands/*.md ~/second-brain/.claude/commands/
+```
+
+Then `/ingest`, `/ask`, `/lint`, `/review` and `/backfill` are available in any
+session started in the vault.
+
+Commands are thin on purpose: each one points at a skill. The behaviour lives
+in the skill, so it stays consistent whether it was triggered by a command, by
+a schedule, or by you asking in plain language.
diff --git a/second-brain-os/commands/ask.md b/second-brain-os/commands/ask.md
new file mode 100644
index 0000000..695e5cf
--- /dev/null
+++ b/second-brain-os/commands/ask.md
@@ -0,0 +1,8 @@
+---
+description: Ask a question answered only from the vault
+---
+
+Answer $ARGUMENTS using only pages in this vault.
+
+Follow the `second-brain-query` skill. Start from `wiki/index.md`, cite every
+page you use, and name what the vault does not cover.
diff --git a/second-brain-os/commands/backfill.md b/second-brain-os/commands/backfill.md
new file mode 100644
index 0000000..d80dc48
--- /dev/null
+++ b/second-brain-os/commands/backfill.md
@@ -0,0 +1,13 @@
+---
+description: Bulk import a large batch of old material
+---
+
+Import the material in $ARGUMENTS into the vault.
+
+Work in batches of ten sources. After each batch: update `index.md`, append to
+`log.md`, and report progress. Order matters, so process oldest material first
+and let later sources update the pages earlier ones created, which mirrors how
+the owner's understanding actually developed.
+
+Stop after each batch and wait for a go-ahead. Bulk imports are where cost and
+quality both go wrong quietly.
diff --git a/second-brain-os/commands/ingest.md b/second-brain-os/commands/ingest.md
new file mode 100644
index 0000000..66b5257
--- /dev/null
+++ b/second-brain-os/commands/ingest.md
@@ -0,0 +1,13 @@
+---
+description: Ingest new material from raw/ into the wiki
+---
+
+Process uningested sources in `raw/`.
+
+$ARGUMENTS is an optional file path. With no argument, find every file in
+`raw/` that has no corresponding page in `wiki/sources/` and process them
+oldest first.
+
+Follow the `second-brain-ingest` skill. Stop and report if more than twenty
+files are pending, so the owner can decide on batching rather than discovering
+a large bill afterwards.
diff --git a/second-brain-os/commands/lint.md b/second-brain-os/commands/lint.md
new file mode 100644
index 0000000..bf92522
--- /dev/null
+++ b/second-brain-os/commands/lint.md
@@ -0,0 +1,8 @@
+---
+description: Audit the vault for broken links, orphans and schema problems
+---
+
+Run a full structural audit following the `second-brain-lint` skill.
+
+$ARGUMENTS may narrow the scope to a folder. Fix mechanical problems, propose
+anything that requires a judgement call, and append the run to `log.md`.
diff --git a/second-brain-os/commands/review.md b/second-brain-os/commands/review.md
new file mode 100644
index 0000000..7681999
--- /dev/null
+++ b/second-brain-os/commands/review.md
@@ -0,0 +1,6 @@
+---
+description: Weekly review of what the vault learned
+---
+
+Produce a review for the period in $ARGUMENTS, defaulting to the last seven
+days, following the `second-brain-review` skill.
diff --git a/second-brain-os/docs/01-concepts/README.md b/second-brain-os/docs/01-concepts/README.md
new file mode 100644
index 0000000..831db7e
--- /dev/null
+++ b/second-brain-os/docs/01-concepts/README.md
@@ -0,0 +1,23 @@
+# Concepts
+
+Why an LLM-maintained knowledge base beats the note system you abandoned, and what the pattern actually is.
+
+## Pages
+
+- [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
+
+---
+
+[Back to the full guide](../README.md)
diff --git a/second-brain-os/docs/01-concepts/two-layers.md b/second-brain-os/docs/01-concepts/two-layers.md
new file mode 100644
index 0000000..2c818d8
--- /dev/null
+++ b/second-brain-os/docs/01-concepts/two-layers.md
@@ -0,0 +1,44 @@
+# The two layers
+
+Most second-brain setups fail because they pick one shape and try to make it do
+two jobs.
+
+**The knowledge layer** answers "what do I know about X". It is organised by
+idea, it grows forever, and its value is in the links between pages. This is the
+LLM wiki pattern: sources in, concepts out, everything connected.
+
+**The project layer** answers "what am I doing this week". It is organised as a
+pipeline, inputs to outputs, and most of it goes cold the moment the project
+ships.
+
+They fail differently when merged. A wiki with project folders in it fills up
+with dead task lists that make every search worse. A project system with
+conceptual notes in it buries the working files under material nobody opens
+while working.
+
+## How they connect
+
+Projects consume the knowledge layer and feed it back:
+
+```
+ wiki/concepts ──────> project Inputs/
+ ▲ │
+ │ ▼
+ ingest what Process/ ──> Outputs/
+ you learned │
+ └──────────────────────────────────┘
+```
+
+Work produces material worth keeping. Ingesting your own finished work is the
+step almost everyone skips, and it is the one that makes the second project in
+a domain meaningfully faster than the first.
+
+## Which to build first
+
+The knowledge layer, if you read a lot and retain little.
+
+The project layer, if your problem is that you re-explain your situation to a
+chat window every morning.
+
+Both eventually. See [vault structure](../02-setup/vault-structure.md) for the
+layout that keeps them separate inside one folder.
diff --git a/second-brain-os/docs/02-setup/README.md b/second-brain-os/docs/02-setup/README.md
new file mode 100644
index 0000000..a27689f
--- /dev/null
+++ b/second-brain-os/docs/02-setup/README.md
@@ -0,0 +1,21 @@
+# Setup
+
+From zero to a vault your agent maintains, in one evening. Follow the pages in
+order the first time. Nine steps, roughly twenty minutes of typing and however
+long the interview in step four takes you.
+
+## Pages
+
+- [Obsidian and your first vault](obsidian-install-and-vault.md)
+- [Claude Code in the vault](claude-code-setup.md)
+- [MCP for Obsidian](mcp-obsidian.md)
+- [Writing your CLAUDE.md](claude-md.md)
+- [Vault structure](vault-structure.md)
+- [Project scoping](project-scoping.md)
+- [Live data connectors](live-data.md)
+- [Plugins worth installing](obsidian-plugins.md)
+- [Git, sync and backups](git-and-sync.md)
+
+---
+
+[Back to the full guide](../README.md)
diff --git a/second-brain-os/docs/02-setup/claude-code-setup.md b/second-brain-os/docs/02-setup/claude-code-setup.md
new file mode 100644
index 0000000..7e006e3
--- /dev/null
+++ b/second-brain-os/docs/02-setup/claude-code-setup.md
@@ -0,0 +1,73 @@
+# Claude Code in the vault
+
+Claude Code is the half that reads and writes. Two ways to run it, and the
+choice only affects where you type, not what happens.
+
+## Option A: the desktop app
+
+Download Claude Desktop from [claude.com/download](https://claude.com/download)
+and sign in. The app has a **Code** tab, which is Claude Code without a
+terminal. If you have never used a command line, start here.
+
+## Option B: the terminal
+
+Install Claude Code and run `claude` from inside the vault folder:
+
+```bash
+cd ~/brain
+claude
+```
+
+Started this way, the agent reads and writes the vault directly through the
+filesystem, with no plugin and no MCP server involved. This is the simplest
+possible setup and it is enough for everything in the ingestion, structuring
+and retrieval sections of this guide.
+
+Installation instructions for each platform are in the [official setup
+docs](https://code.claude.com/docs/en/setup).
+
+## Plan requirement
+
+Claude Code needs a paid account: Pro, Max, Team, Enterprise, or a Console
+account billed per token. The free Claude.ai plan does not include Claude Code
+access, per Anthropic's own setup documentation. If the Code tab prompts you to
+upgrade, that is why.
+
+## Filesystem or MCP
+
+Both work. The difference is narrow and worth knowing before you pick:
+
+| | Filesystem | MCP |
+|---|---|---|
+| Setup | none, just `cd` into the vault | plugin plus a config command |
+| Obsidian open | not required | required, the plugin serves the API |
+| Scope | whatever folder you started in | the whole vault, from anywhere |
+| Failure mode | none to speak of | plugin off, app closed, wrong port |
+
+Start on the filesystem. Move to [MCP](mcp-obsidian.md) when you want the agent
+to reach the vault from sessions that are not running inside it, which mostly
+matters once you add scheduled tasks.
+
+## First run
+
+Point it at the structure before asking for anything else:
+
+```
+Read CLAUDE.md and wiki/index.md, then tell me what this vault currently
+contains and what is missing.
+```
+
+The answer tells you immediately whether the agent understood its instructions.
+If it starts inventing a structure you did not ask for, your `CLAUDE.md` is too
+vague. See [writing your CLAUDE.md](claude-md.md).
+
+## Permissions
+
+The agent will ask before editing files. Grant it write access to the vault and
+nothing else. Do not grant blanket shell access on a folder that holds anything
+you cannot lose, and read [guardrails](../06-agents/safety-and-guardrails.md)
+before you automate anything on a schedule.
+
+## Next
+
+[MCP for Obsidian](mcp-obsidian.md)
diff --git a/second-brain-os/docs/02-setup/claude-md.md b/second-brain-os/docs/02-setup/claude-md.md
new file mode 100644
index 0000000..8378783
--- /dev/null
+++ b/second-brain-os/docs/02-setup/claude-md.md
@@ -0,0 +1,64 @@
+# Writing your CLAUDE.md
+
+`CLAUDE.md` at the vault root is the file the agent reads at the start of every
+session. It is the difference between an assistant that knows your situation and
+one you brief from scratch every time.
+
+An empty vault with a good `CLAUDE.md` is more useful than a full vault without
+one, because context about you shapes every page the agent writes afterwards.
+
+## Do not type it, get interviewed
+
+Writing this file cold produces a thin, generic version. Answering questions
+produces a specific one. Paste this into the agent:
+
+```
+You are setting up my second brain. Interview me ONE question at a time to
+build my profile. Ask about: who I am and what I do, my goals for this year,
+how I want you to talk to me, my strengths and weaknesses, and my current
+projects. Wait for each answer before the next question. When finished, write
+everything into CLAUDE.md at the vault root, structured with headers.
+```
+
+Answer as if briefing a co-founder on their first day. Vague answers produce a
+vague file, and every session inherits it.
+
+## What belongs in it
+
+- **Who you are and what you work on.** Enough that a stranger could act on it.
+- **Goals with a horizon.** This year, this quarter. Undated goals age badly.
+- **How to talk to you.** Length, tone, how much pushback you want.
+- **Your strengths and weak spots.** This is what lets the agent know when to
+ challenge you rather than agree.
+- **Current projects,** one line each, linked to their folders.
+- **The vault's own rules:** folder layout, page contracts, linking rules. The
+ version in [`vault-template/CLAUDE.md`](../../vault-template/CLAUDE.md) is a
+ working starting point.
+
+## What does not belong in it
+
+- Anything that changes weekly. That goes in the project files.
+- Long explanations of things the model already knows.
+- Credentials of any kind.
+- Aspirational statements you will not act on. The agent takes them literally.
+
+## Two levels
+
+The root `CLAUDE.md` is the strategy layer: who you are, what you are aiming
+at, how the vault works. Each project folder gets its own `CLAUDE.md` covering
+that project only. When you open a project as its own vault, the agent reads
+just that one and stops carrying your entire life into every task. See
+[project scoping](project-scoping.md).
+
+## Iterate on it
+
+When the agent does something wrong twice, that is a `CLAUDE.md` problem, not a
+prompting problem. Add the rule, with the reason attached, because a rule
+without a reason gets applied too literally in the cases you did not anticipate.
+
+Re-read the file monthly. Goals move, projects close, and a stale profile
+quietly degrades everything the agent writes.
+
+## Next
+
+[Vault structure](vault-structure.md)
diff --git a/second-brain-os/docs/02-setup/git-and-sync.md b/second-brain-os/docs/02-setup/git-and-sync.md
new file mode 100644
index 0000000..7b1d674
--- /dev/null
+++ b/second-brain-os/docs/02-setup/git-and-sync.md
@@ -0,0 +1,61 @@
+# Git, sync and backups
+
+A vault is a folder of text files, which makes it close to an ideal git
+repository, and git is what makes an agent safe to run unattended.
+
+Without version control, a bad run is a mystery. With it, every change the agent
+made is a diff you can read and revert in one command.
+
+```bash
+cd ~/brain
+git init
+git add .
+git commit -m "initial vault"
+```
+
+## What to ignore
+
+```
+.obsidian/workspace*
+.obsidian/cache
+.DS_Store
+.trash/
+```
+
+Commit the rest of `.obsidian/`, so your plugin list and settings travel with
+the vault. Never commit API keys; the Local REST API key lives in plugin data,
+so check what `.obsidian/plugins/` contains before the first push.
+
+If any part of the vault is private, keep the remote private. A second brain is
+one of the highest-signal documents about a person that exists.
+
+## Commit around agent runs
+
+Commit before a big ingest and after it. Then a bad batch is
+`git checkout .` rather than an afternoon of manual repair. Scheduled tasks
+should commit their own work with a message naming the run, so the history stays
+readable months later.
+
+## Sync across machines
+
+- **Git remote:** free, versioned, works everywhere, needs a pull and push
+ habit.
+- **Obsidian Sync:** paid, end-to-end encrypted, handles mobile properly.
+- **Generic cloud drives:** work, with a caveat. A sync client rewriting files
+ while an agent writes them produces conflict copies. If you go this route,
+ keep long-running agent work to one machine.
+
+## Backups
+
+Sync is not backup. Sync propagates a bad delete to every device.
+
+Keep one copy that is not connected to the sync path: a periodic archive to
+external storage or a separate remote. Test a restore once, before you need it.
+The failure mode you are protecting against is not disk death, it is an
+automation that quietly rewrote two hundred pages three weeks ago.
+
+## Next
+
+The vault is set up. Go to [Ingestion](../03-ingestion/README.md) to start
+feeding it, or [Structuring](../04-structuring/README.md) for the rules that
+decide what the pages look like.
diff --git a/second-brain-os/docs/02-setup/live-data.md b/second-brain-os/docs/02-setup/live-data.md
new file mode 100644
index 0000000..613361c
--- /dev/null
+++ b/second-brain-os/docs/02-setup/live-data.md
@@ -0,0 +1,59 @@
+# Live data connectors
+
+Static notes are half a brain. The other half is what is changing: your
+calendar, your inbox, the channels where decisions actually get made.
+
+MCP connects those the same way it connects Obsidian.
+
+## Calendar
+
+```bash
+claude mcp add google-workspace uvx workspace-mcp --tools calendar
+```
+
+An OAuth sign-in opens in the browser. Grant read access.
+
+Then the vault can act on it:
+
+```
+Read my calendar for today, log what I committed to in each meeting into my
+tasks project, and flag anything without a clear next step.
+```
+
+Email, Slack and Notion connect through their own MCP servers, registered the
+same way.
+
+## Grant read, not write
+
+Give every connector the narrowest scope that does the job, and prefer read-only
+wherever the option exists. The brain should read your data, not delete it or
+send things on your behalf.
+
+## The rule that matters most
+
+**Keys, not prompts.**
+
+Telling an agent "do not delete this" is a suggestion. It is not a safety
+setting. If the agent technically can delete a file, empty a folder or send an
+email, then one day, in some context you did not predict, it will.
+
+Control what is possible at the permission level: read-only tokens, scoped keys,
+separate credentials per connector. Then the instruction in your `CLAUDE.md` is
+a preference on top of a boundary, rather than the only thing standing between
+your inbox and a bad run.
+
+This applies to your own vault too. See
+[guardrails](../06-agents/safety-and-guardrails.md).
+
+## What is worth connecting
+
+Connect the sources where decisions and commitments live: calendar first, then
+whichever of email or chat you actually use for work.
+
+Skip the ones that produce volume without signal. A connector that floods the
+vault with notifications makes every future query worse, because the agent has
+to read past all of it.
+
+## Next
+
+[Plugins worth installing](obsidian-plugins.md)
diff --git a/second-brain-os/docs/02-setup/mcp-obsidian.md b/second-brain-os/docs/02-setup/mcp-obsidian.md
new file mode 100644
index 0000000..0597908
--- /dev/null
+++ b/second-brain-os/docs/02-setup/mcp-obsidian.md
@@ -0,0 +1,72 @@
+# MCP for Obsidian
+
+MCP is the standard way Claude talks to other applications. For a vault, it
+adds a door into Obsidian itself rather than into the folder underneath, which
+means the agent can work with the vault from any session, not only one started
+inside that directory.
+
+You do not need this to start. Add it when you want scheduled tasks, or when
+you are working from the desktop app rather than a terminal in the vault.
+
+## Step 1: enable the plugin
+
+In Obsidian: **Settings** (gear, bottom left) → **Community plugins** → **Turn
+on community plugins** → **Browse** → search `Local REST API` → **Install** →
+**Enable**.
+
+Open the plugin's settings. There is an **API Key**, a long string of letters
+and numbers. Copy it.
+
+Obsidian displays the key with the word `Bearer` in front of it. That word is
+not part of the key. Copy only the string after it. This is the single most
+common reason the connection fails on the first try.
+
+## Step 2: register the server
+
+In the Claude Code tab or terminal, with your key pasted in place of
+`PASTE-YOUR-KEY-HERE`:
+
+```bash
+claude mcp add-json obsidian-vault '{
+ "type": "stdio",
+ "command": "uvx",
+ "args": ["mcp-obsidian"],
+ "env": {
+ "OBSIDIAN_API_KEY": "PASTE-YOUR-KEY-HERE",
+ "OBSIDIAN_HOST": "127.0.0.1",
+ "OBSIDIAN_PORT": "27124"
+ }
+}'
+```
+
+`uvx` runs the server without a permanent install. If the command is not found,
+install `uv` first.
+
+## Step 3: test it
+
+```
+List every file in my Obsidian vault.
+```
+
+If the agent reads your notes back, the connection works.
+
+## When it does not work
+
+- **Obsidian is closed.** The plugin serves the API from inside the app, so the
+ connection only exists while Obsidian is running.
+- **`Bearer` in the key.** Strip it.
+- **Wrong port.** Check the port shown in the plugin settings against the value
+ in your config. The default is 27124.
+- **Plugin disabled.** Community plugins get turned off when restricted mode is
+ re-enabled after an update.
+
+## Security
+
+This opens a local HTTP server with a key that grants full read and write access
+to your notes. Keep it on `127.0.0.1`, never expose the port, and treat the key
+like a password. If you paste it anywhere public, rotate it in the plugin
+settings.
+
+## Next
+
+[Writing your CLAUDE.md](claude-md.md)
diff --git a/second-brain-os/docs/02-setup/obsidian-install-and-vault.md b/second-brain-os/docs/02-setup/obsidian-install-and-vault.md
new file mode 100644
index 0000000..0ba51e3
--- /dev/null
+++ b/second-brain-os/docs/02-setup/obsidian-install-and-vault.md
@@ -0,0 +1,50 @@
+# Obsidian and your first vault
+
+Obsidian is the storage half of the system. It is free, it keeps everything as
+plain text files on your own machine, and it renders the links between notes as
+a graph. Nothing here is stored in a company's cloud, and the files stay
+readable in any text editor if you ever walk away from the app.
+
+## Install
+
+Download from [obsidian.md](https://obsidian.md) and install it.
+
+On the welcome screen, click **Create new vault**. Name it something short you
+will type often, `brain` works. Pick a folder on your machine and click
+**Create**.
+
+That folder is now your second brain. Everything the agent writes lands there
+as markdown files.
+
+## Make one note by hand
+
+Do this once before automating anything, so the mechanic is not abstract.
+
+Click the new-note icon, type a sentence, then type `[[goals]]`. The bracketed
+word becomes a link to a page called `goals`, whether or not that page exists
+yet. Click it and Obsidian creates the page.
+
+That is the entire data model: notes pointing at notes. Everything the agent
+does later is this, at volume, without you doing it.
+
+## Where to put the vault
+
+Somewhere with a stable path you can type from a terminal. Avoid a folder your
+cloud sync client rewrites aggressively, because an agent writing files while a
+sync client rewrites them produces conflict copies that are genuinely painful
+to untangle. See [git and sync](git-and-sync.md) for the options that work.
+
+Avoid spaces in the folder name. You will be pasting this path into commands.
+
+## Settings worth changing now
+
+- **Files and links → New link format:** relative path or shortest path,
+ consistently. Mixed link formats are the most common cause of broken links
+ after a rename.
+- **Files and links → Automatically update internal links:** on.
+- **Editor → Show frontmatter:** on. You want to see the metadata the agent
+ writes, at least for the first weeks.
+
+## Next
+
+[Claude Code in the vault](claude-code-setup.md)
diff --git a/second-brain-os/docs/02-setup/obsidian-plugins.md b/second-brain-os/docs/02-setup/obsidian-plugins.md
new file mode 100644
index 0000000..dd6d1ce
--- /dev/null
+++ b/second-brain-os/docs/02-setup/obsidian-plugins.md
@@ -0,0 +1,48 @@
+# Plugins worth installing
+
+Obsidian works fine with none of these. Add them when you hit the specific
+problem each one solves.
+
+## Local REST API
+
+Required only for the [MCP path](mcp-obsidian.md). Serves your vault over a
+local HTTP API so the agent can reach it while Obsidian is open, from any
+session.
+
+## Dataview
+
+Queries over frontmatter, rendered inside a note. Worth it once you have enough
+pages to want dashboards:
+
+````
+```dataview
+TABLE updated, tags
+FROM "wiki/concepts"
+WHERE updated < date(today) - dur(90 days)
+SORT updated ASC
+```
+````
+
+That one lists concept pages nobody has touched in three months, which is the
+most useful review query in the vault.
+
+## Templater
+
+Templates with variables and dates, for the page shapes in
+[`vault-template/templates/`](../../vault-template/templates/). Useful for the
+notes you write by hand. The agent does not need it, it writes frontmatter
+directly.
+
+## What to avoid
+
+Plugins that rewrite files in the background. Anything that auto-formats,
+auto-sorts frontmatter, or renames on a schedule will fight the agent, and you
+will spend an evening working out which of the two mangled a page.
+
+Also avoid heavy graph or dashboard plugins until you have material worth
+looking at. An empty vault with fifteen plugins is a procrastination artifact,
+not a system.
+
+## Next
+
+[Git, sync and backups](git-and-sync.md)
diff --git a/second-brain-os/docs/02-setup/project-scoping.md b/second-brain-os/docs/02-setup/project-scoping.md
new file mode 100644
index 0000000..ddaa83d
--- /dev/null
+++ b/second-brain-os/docs/02-setup/project-scoping.md
@@ -0,0 +1,55 @@
+# Project scoping
+
+This is the step that most setups skip and then wonder why output quality drops
+as the vault grows.
+
+When the agent is pointed at the whole vault, every task competes with
+everything you have ever saved. It reads a root `CLAUDE.md` covering your entire
+life, plus whatever else it decides is relevant. Answers get broader and
+shallower.
+
+When it is pointed at one project, it reads that project's `CLAUDE.md`, sees
+that project's files, and does the job in front of it.
+
+## How to scope
+
+In Obsidian, click the vault name in the bottom left, then:
+
+**Manage vaults → Open folder as a vault → pick your project folder → Trust**
+
+From a terminal, the same thing is just:
+
+```bash
+cd ~/brain/projects/youtube-channel
+claude
+```
+
+The agent now reads only that project's instructions.
+
+## When to use which
+
+**The full vault** for anything that spans domains: planning, review, asking
+what you know about a topic, weekly maintenance, ingestion. The knowledge layer
+is the whole point of a wide view.
+
+**A single project** for producing anything: drafting, building, analysing this
+week's numbers. Narrow context, one goal, no drift.
+
+The rough rule: the full vault plans, a single project ships.
+
+## Passing knowledge into a project
+
+Scoping down cuts the agent off from the wiki, which is usually what you want
+and occasionally not. Two ways to bridge it:
+
+- Link the relevant concept pages from the project's `CLAUDE.md`, and copy the
+ handful that genuinely matter into the project's `Inputs/`.
+- Or run the research question against the full vault first, save the answer
+ into the project's `Inputs/`, then scope down and work.
+
+The second is better. It keeps the decision about what matters with you, which
+is the part you should not be delegating.
+
+## Next
+
+[Live data connectors](live-data.md)
diff --git a/second-brain-os/docs/02-setup/vault-structure.md b/second-brain-os/docs/02-setup/vault-structure.md
new file mode 100644
index 0000000..4e8a723
--- /dev/null
+++ b/second-brain-os/docs/02-setup/vault-structure.md
@@ -0,0 +1,71 @@
+# Vault structure
+
+The vault does two different jobs, and they want different shapes. Keeping them
+in one folder tree while keeping the shapes separate is what makes the system
+hold up past the first month.
+
+**The knowledge layer** is what you have read and understood. It grows forever
+and it is organised by idea.
+
+**The project layer** is what you are working on now. It is organised by
+pipeline and most of it goes cold when the project ships.
+
+```
+brain/
+ CLAUDE.md who you are, how the vault works
+ raw/ source material, never edited after it lands
+ assets/
+ wiki/ the knowledge layer
+ sources/ one page per ingested item
+ entities/ people, organisations, products, tools
+ concepts/ ideas, methods, frameworks
+ synthesis/ comparisons, themes, open questions
+ index.md catalog of every page
+ log.md what the agent did, chronologically
+ projects/ the project layer
+ youtube-channel/
+ CLAUDE.md this project only
+ Inputs/ ideas, briefs, raw material
+ Process/ work in progress
+ Outputs/ finished work
+ Feedback/ results, metrics, what happened
+ output/ generated reports and drafts
+```
+
+## Why the split
+
+A project pipeline answers "what am I doing this week". A wiki answers "what do
+I know about X". Force one structure to do both and you get either a knowledge
+base full of dead task folders, or projects buried under conceptual pages
+nobody opens while working.
+
+They connect through links. A project page links to the concepts it depends on;
+concept pages accumulate references from the projects that used them. That is
+where the compounding shows up: the second time you start a project in a domain,
+the knowledge layer already has it.
+
+## Set the projects up by asking
+
+```
+Create a project folder in my vault called youtube-channel. Inside it, create
+four folders: Inputs, Process, Outputs, Feedback. Then write a CLAUDE.md inside
+that project folder describing what this project is, its one goal, and your
+specific role in helping me hit it. Interview me if you need details.
+```
+
+Repeat per area: content, finances, clients. One goal per project, stated in
+the project's own `CLAUDE.md`. Projects with three goals produce work that
+serves none of them.
+
+## Rules that keep it working
+
+- **Never edit `raw/`.** It is the archive. If a source is wrong, replace the
+ file and re-ingest, so it stays a faithful record of what you actually saved.
+- **Do not nest deeply.** Folders four levels down stop getting opened. The
+ graph is the navigation, not the tree.
+- **Everything the agent generates for outside use goes to `output/` or the
+ project's `Outputs/`,** never loose in the vault root.
+
+## Next
+
+[Project scoping](project-scoping.md)
diff --git a/second-brain-os/docs/03-ingestion/README.md b/second-brain-os/docs/03-ingestion/README.md
new file mode 100644
index 0000000..011f7ff
--- /dev/null
+++ b/second-brain-os/docs/03-ingestion/README.md
@@ -0,0 +1,26 @@
+# Ingestion
+
+Getting everything you read, watch and write into `raw/` with as little
+friction as possible, then into the wiki without flooding it.
+
+Capture is the part that decides whether the vault survives. Every step between
+seeing something and having it saved is a step where you will stop doing it, so
+the goal is one click or one command, always the same one.
+
+The second half matters as much: what you feed the vault sets its ceiling. A
+hundred clipped listicles produce a hundred thin pages and a graph that says
+nothing.
+
+## Pages
+
+- [Web articles](web-clipper.md)
+- [YouTube and podcasts](youtube-transcripts.md)
+- [PDFs, papers and books](pdfs-and-books.md)
+- [Chat exports](chat-exports.md)
+- [Voice notes and meetings](voice-and-meetings.md)
+- [Newsletters and email](newsletters-and-email.md)
+- [Backfilling years of material](bulk-backfill.md)
+
+---
+
+[Back to the full guide](../README.md)
diff --git a/second-brain-os/docs/03-ingestion/bulk-backfill.md b/second-brain-os/docs/03-ingestion/bulk-backfill.md
new file mode 100644
index 0000000..4f10ac3
--- /dev/null
+++ b/second-brain-os/docs/03-ingestion/bulk-backfill.md
@@ -0,0 +1,98 @@
+# Backfilling years of material
+
+At some point you will want to import everything: the bookmark folder, the
+downloads directory, three years of chat history, the read-later queue with
+eight hundred unread items.
+
+This is the run that goes wrong. It is expensive, it takes hours, and done in
+the wrong order it produces a wiki that reads like a pile rather than a
+structure. It is also the run that makes the vault genuinely useful in one
+sitting, so it is worth doing carefully.
+
+## Order matters
+
+Process oldest first.
+
+The reason is that later sources should update pages that earlier sources
+created. Run it that way and the wiki records how your understanding developed:
+the early page on a topic, then the correction, then the current position.
+
+Run it newest first and every old source arrives as a contradiction to be
+reconciled against a page that already has the final answer. The agent spends
+its work reconciling, the history comes out inverted, and you lose the one thing
+this structure gives you over a search index.
+
+## Batch, always
+
+Ten sources per batch. After each batch: update `index.md`, append to `log.md`,
+commit, report.
+
+```
+/backfill raw/archive/2024
+```
+
+The `backfill` command in [`commands/`](../../commands/README.md) works this
+way and stops between batches for a go-ahead.
+
+Batching exists for three reasons. Cost stays visible while you can still stop.
+Quality stays checkable, so you catch a bad page contract on page ten rather
+than page four hundred. And a crash costs you one batch instead of the run.
+
+## Check the first batch properly
+
+Read every page the first batch produced. All of them.
+
+This is the moment to catch systematic problems: pages that are summaries rather
+than explanations, concepts that are too granular, links that are decorative,
+frontmatter that is wrong. Fix `CLAUDE.md` and re-run the batch before
+continuing.
+
+A flaw you let through in batch one is a flaw in four hundred pages by the end,
+and fixing it afterwards costs more than the original run.
+
+## Cost control
+
+Backfilling a thousand sources is a real bill. Ways to keep it sane:
+
+- **Filter first.** Most archives are half dead links and things you saved and
+ never opened. Have the agent triage titles before ingesting anything.
+- **Cap the batch size** and watch what the first few cost before scaling.
+- **Skip the archive tier.** Not everything needs a wiki page; leaving material
+ in `raw/` still leaves it searchable.
+
+## Dead links
+
+Old bookmark exports are full of pages that no longer exist. Check before
+ingesting rather than discovering it halfway:
+
+```bash
+python3 -c "import sys,urllib.request as u;[print(l.strip()) for l in sys.stdin]"
+```
+
+For anything valuable that is gone, the Internet Archive usually has a copy.
+Clip from there and note in the frontmatter that the original is dead, because a
+source page whose URL 404s is unverifiable a year later.
+
+## Resuming
+
+Record progress in `log.md` as you go, one line per batch with the folder and
+range covered. When the run stops halfway, and it will, you resume from the log
+instead of guessing which files were done.
+
+## After the backfill
+
+Run a full lint. A large import always leaves orphans, near-duplicates and
+broken links.
+
+```
+/lint
+```
+
+Then run a review to see what the vault now contains, because after a backfill
+it knows things you have forgotten you saved. That moment is the payoff for the
+whole exercise.
+
+## Next
+
+[Structuring](../04-structuring/README.md), for the rules that decide what all
+these pages actually look like.
diff --git a/second-brain-os/docs/03-ingestion/chat-exports.md b/second-brain-os/docs/03-ingestion/chat-exports.md
new file mode 100644
index 0000000..d7953b4
--- /dev/null
+++ b/second-brain-os/docs/03-ingestion/chat-exports.md
@@ -0,0 +1,84 @@
+# Chat exports
+
+Your chat history is the most underrated source you own and the most sensitive.
+Years of problems you worked through, decisions you reasoned about, and
+explanations tailored to what you did not understand at the time.
+
+It is also full of things you would not want in a file you might later share.
+Read the privacy section below before running anything here.
+
+## Exporting
+
+Both Claude and ChatGPT export the full history as JSON from account settings.
+The export arrives by email as a download link, usually within minutes.
+
+## Converting to markdown
+
+One JSON blob is not ingestible. Split it into one file per conversation:
+
+```bash
+python3 scripts/chat_export_to_md.py conversations.json ./raw --min-words 150
+```
+
+The script is in [`scripts/`](../../scripts/README.md). It handles the common
+export shapes, writes frontmatter with the title and date, and skips
+conversations shorter than the word threshold.
+
+Raise `--min-words` if the output is dominated by one-line exchanges. Most
+people's history is roughly ninety percent short throwaway questions, and those
+add nothing but volume.
+
+## Filter before ingesting
+
+Do not ingest the whole export. A thousand conversations produce a thousand
+source pages and a wiki where everything is faintly connected to everything.
+
+Sort into three piles:
+
+- **Worth ingesting.** Conversations where you worked something out, decided
+ something, or got an explanation that landed. These carry your reasoning, not
+ just facts.
+- **Worth keeping, not ingesting.** Leave them in `raw/` as an archive. The
+ agent can search them on demand without every one having a wiki page.
+- **Delete.** Debugging sessions, one-off lookups, anything you would be
+ annoyed to find in a search result.
+
+Have the agent help with the sort rather than doing it by hand:
+
+```
+Read the titles and first exchange of every file in raw/chats/. Group them into
+worth-ingesting, archive, and delete, with one line of reasoning each. Do not
+move or delete anything, just give me the lists.
+```
+
+## What makes these sources different
+
+A chat log is a record of you thinking, which means the useful extraction is
+often not the answer. It is the question you asked, the thing you had wrong at
+the start, and what changed your mind.
+
+Tell the agent so:
+
+```
+These are my own past conversations. Build pages around what I was trying to
+work out and what conclusion I reached, not around the assistant's explanations.
+Note where I changed position, and record the date, because my views may have
+moved since.
+```
+
+## Privacy
+
+Chat history contains more about you than any other file in the vault: health,
+money, work you cannot discuss, other people's information you happened to
+mention.
+
+Before ingesting, decide what does not belong in the vault at all and delete
+those files from `raw/`. Redaction after the fact is unreliable, because the
+material will already have propagated into concept pages and links.
+
+If the vault lives in a git repo, keep the remote private. See
+[privacy](../09-maintenance/privacy-and-secrets.md).
+
+## Next
+
+[Voice notes and meetings](voice-and-meetings.md)
diff --git a/second-brain-os/docs/03-ingestion/newsletters-and-email.md b/second-brain-os/docs/03-ingestion/newsletters-and-email.md
new file mode 100644
index 0000000..c6edeb9
--- /dev/null
+++ b/second-brain-os/docs/03-ingestion/newsletters-and-email.md
@@ -0,0 +1,66 @@
+# Newsletters and email
+
+Newsletters are the easiest source to automate and the easiest to over-ingest.
+Automate the capture, then be strict about what gets a wiki page, because a feed
+that files itself will happily fill your vault with a hundred pages a month that
+you never asked for.
+
+## A dedicated address
+
+Make an address that exists only for the vault, and resubscribe your newsletters
+to it. That single move separates the material you want to keep from everything
+else in your inbox, and it means automation never touches your real mail.
+
+From there, forward that address into `raw/` with whatever automation you
+already use. Any rule that can write a file works.
+
+## Deduplicate
+
+Newsletters repeat themselves. The same launch appears in four different digests
+in the same week, each with the same facts and a different opening line.
+
+Ingested straight, you get four source pages saying one thing and a concept page
+citing all four as if that were corroboration. Cross-references between
+newsletters are not independent confirmation, and a wiki that treats them as
+such will overstate how well established something is.
+
+Instruct the ingest explicitly:
+
+```
+These are newsletters. Several will cover the same item. Group them by topic
+first, write one source page per actual item citing every newsletter that
+mentioned it, and note where they disagree. Do not treat repetition across
+newsletters as confirmation.
+```
+
+## What deserves a page
+
+Newsletters are mostly links with commentary. The commentary is rarely worth a
+concept page; the thing being linked sometimes is.
+
+The useful pattern is to let the agent read the digests and hand you a shortlist:
+
+```
+Read this week's newsletters in raw/newsletters/. List anything worth reading in
+full, with one line on why. Ingest nothing yet.
+```
+
+Then clip the two or three primary sources properly and ingest those. The
+newsletter did its job as a filter, and the vault ends up with the actual source
+instead of a summary of it.
+
+## Regular email
+
+Most email should not be in a second brain. Threads about scheduling, receipts,
+back and forth about logistics: none of it is knowledge, all of it is volume.
+
+Worth ingesting: threads where a real decision was made or something was
+explained properly. Route those in by forwarding to the capture address, one
+thread at a time, deliberately.
+
+Never wire your whole inbox into `raw/` on a schedule. It ingests everything
+about everyone you correspond with, most of it not yours to keep.
+
+## Next
+
+[Backfilling years of material](bulk-backfill.md)
diff --git a/second-brain-os/docs/03-ingestion/pdfs-and-books.md b/second-brain-os/docs/03-ingestion/pdfs-and-books.md
new file mode 100644
index 0000000..d8c9e6e
--- /dev/null
+++ b/second-brain-os/docs/03-ingestion/pdfs-and-books.md
@@ -0,0 +1,72 @@
+# PDFs, papers and books
+
+PDFs are the format most likely to arrive in your vault as garbage. Two columns
+become interleaved lines, tables collapse, footnotes land mid-sentence, and the
+agent quietly builds pages on top of the mess.
+
+Check extraction quality before ingesting. It takes ten seconds and saves
+rewriting pages later.
+
+## Extraction
+
+```bash
+# text, layout preserved reasonably well
+pdftotext -layout paper.pdf raw/paper.md
+```
+
+For anything structured, `pymupdf` gives better control and can pull images and
+tables separately. Whatever you use, open the output and read a paragraph from
+the middle. If the sentences do not flow, fix extraction rather than hoping the
+agent copes.
+
+## Scanned documents
+
+A scan is an image, and text extraction returns nothing or near-nothing. Run OCR
+first with `ocrmypdf`, which adds a text layer without changing the visible
+document. Expect errors in proper nouns and numbers, and treat any figure from
+an OCR'd source as needing verification before it goes into a wiki page as
+fact.
+
+## Papers
+
+Papers deserve different handling than articles, because the parts you will
+want later are not spread evenly. Abstract, method, results and limitations
+carry almost everything.
+
+A useful ingest instruction:
+
+```
+This is an academic paper. Build the source page around: the question it asks,
+the method, the result with its actual numbers, and the limitations the authors
+state themselves. Record sample sizes. Do not report a finding without the
+condition it holds under.
+```
+
+That last rule is what keeps a wiki honest. Findings stripped of their
+conditions become confident nonsense two years later.
+
+Zotero is worth using if you read papers regularly. It handles metadata and
+exports markdown, which lands in `raw/` cleanly.
+
+## Books
+
+A full book is too large to ingest as one source and mostly not worth it. What
+is worth it is your highlights.
+
+Kindle highlights export from the Kindle app or through Readwise, which syncs
+into Obsidian directly. Highlights arrive as a list of quoted passages, so
+ingest them as one source page per book, and let the agent build concept pages
+from the ideas rather than from the quotes.
+
+Keep the quotes short in the wiki and keep the citation. A page that reproduces
+half a chapter is a copyright problem and a retrieval problem at the same time.
+
+## Figures and tables
+
+Text extraction drops both. When a figure carries the argument, screenshot it
+into `raw/assets/` and reference it from the source page, so the claim on the
+page has something behind it.
+
+## Next
+
+[Chat exports](chat-exports.md)
diff --git a/second-brain-os/docs/03-ingestion/voice-and-meetings.md b/second-brain-os/docs/03-ingestion/voice-and-meetings.md
new file mode 100644
index 0000000..2e9bb9a
--- /dev/null
+++ b/second-brain-os/docs/03-ingestion/voice-and-meetings.md
@@ -0,0 +1,69 @@
+# Voice notes and meetings
+
+The ideas worth capturing rarely arrive at your desk. Voice is the only capture
+method that works while walking, driving or standing in a queue, and it is the
+one most vaults never wire up.
+
+## Capture
+
+Any recorder app works, as long as the file ends up somewhere the vault can
+reach. The friction to eliminate is the transfer: if getting audio from phone to
+vault takes more than one action, you will stop.
+
+Simplest reliable setup: record in the phone's default app, share to a cloud
+folder, and have a scheduled task transcribe anything new into `raw/`.
+
+Obsidian's mobile app can record directly into the vault, which removes the
+transfer entirely if you already sync mobile.
+
+## Transcription
+
+Whisper runs locally and is good enough for a voice note recorded at arm's
+length. Local matters more here than for other sources, because voice notes
+carry half-formed thoughts and meeting audio carries other people's words.
+
+Expect names and technical terms to come out wrong. Correct them at ingest, not
+later, while you still remember what you said.
+
+## Voice notes are drafts, not sources
+
+A voice note is you thinking out loud, with false starts and abandoned
+sentences. Ingesting it verbatim produces an incoherent source page.
+
+Treat the transcript as raw input to a single idea:
+
+```
+This is a voice note, my own thinking out loud. Extract the actual idea, drop
+the false starts and repetition, and write it as one short concept page in my
+words. If there are two unrelated ideas, make two pages. Keep the recording date.
+```
+
+## Meetings
+
+Meetings produce three things worth keeping and a great deal that is not: the
+decisions, the commitments with owners, and the open questions.
+
+```
+This is a meeting transcript. Extract decisions made, commitments with who owns
+each one, and open questions. Link every person mentioned to their entity page.
+Skip discussion that did not lead anywhere.
+```
+
+Route the commitments into the relevant project's `Inputs/` rather than the
+wiki. A commitment is work, not knowledge, and it goes stale in a week. The
+[two layers](../01-concepts/two-layers.md) page covers why that separation
+matters.
+
+## Consent and other people
+
+Recording other people has legal requirements that vary by jurisdiction, and
+they are not a formality. Some places require every participant to consent.
+
+Separately from legality: a meeting transcript contains other people's
+unguarded words. Keep those out of any vault you might share, and think about
+whether the meeting needs to be in the knowledge layer at all, or whether the
+three extracted decisions are enough.
+
+## Next
+
+[Newsletters and email](newsletters-and-email.md)
diff --git a/second-brain-os/docs/03-ingestion/web-clipper.md b/second-brain-os/docs/03-ingestion/web-clipper.md
new file mode 100644
index 0000000..11a2f57
--- /dev/null
+++ b/second-brain-os/docs/03-ingestion/web-clipper.md
@@ -0,0 +1,73 @@
+# Web articles
+
+Articles are the bulk of what most people save, and the browser is where the
+decision to save happens. Anything that requires switching windows loses.
+
+## Obsidian Web Clipper
+
+The [official extension](https://obsidian.md/clipper) from the Obsidian team.
+Chrome, Firefox, Safari, Edge, Brave and Arc. It extracts the readable content
+of a page using Mozilla Readability, the same engine behind Firefox Reader View,
+and saves it as markdown straight into your vault.
+
+Install it, open the settings, and set the destination folder to `raw/`.
+
+## Template
+
+The default template saves the page body. Add frontmatter so the agent knows
+what it is holding without re-reading the whole file:
+
+```
+---
+title: {{title}}
+source: {{url}}
+author: {{author}}
+published: {{published}}
+clipped: {{date}}
+type: article
+---
+
+{{content}}
+```
+
+`{{author}}` and `{{published}}` come back empty on plenty of sites. That is
+fine, an empty field is better than a guessed one, and the agent handles the
+gap by saying the source is undated rather than inventing a date.
+
+## What to clip
+
+Clip what you would want to find again in a year: primary sources, engineering
+posts, papers, documentation, arguments you disagree with and want to answer
+later.
+
+Skip news that will be stale in a week, listicles, and anything you are saving
+out of guilt. Every low-value page you ingest costs twice: once at ingest, and
+again every time the agent reads past it looking for something else.
+
+The honest test at clip time is whether you can name what you would ask this
+source later. If you cannot, do not clip it.
+
+## Awkward pages
+
+- **Paywalls.** The clipper saves what the browser rendered. If you can read it,
+ it can save it. If you cannot, it saves the paywall notice, so check before
+ moving on.
+- **Documentation sites.** Clipping page by page is a losing game. Save the
+ entry point and let the agent fetch the rest, or clone the docs repo into
+ `raw/` if it is open source.
+- **Single-page apps and dynamic content.** Readability sometimes returns a
+ fragment. Look at the file before ingest.
+- **Threads and comment sections.** The value is usually in the replies, which
+ the clipper drops. Copy the thread manually or screenshot it into
+ `raw/assets/`.
+
+## Clip now, ingest later
+
+Clipping and ingesting are separate steps on purpose. Clip freely during the
+day, run `/ingest` in one batch later, because ingesting one source at a time
+gives the agent no chance to spot that three things you saved this week are
+about the same idea.
+
+## Next
+
+[YouTube and podcasts](youtube-transcripts.md)
diff --git a/second-brain-os/docs/03-ingestion/youtube-transcripts.md b/second-brain-os/docs/03-ingestion/youtube-transcripts.md
new file mode 100644
index 0000000..2636870
--- /dev/null
+++ b/second-brain-os/docs/03-ingestion/youtube-transcripts.md
@@ -0,0 +1,82 @@
+# YouTube and podcasts
+
+Video is the highest-volume, lowest-retention source most people have. An hour
+of a conference talk leaves almost nothing behind a week later. Transcripts fix
+that, and a transcript is just text, which is exactly what the vault wants.
+
+## Pulling a transcript
+
+Most videos have captions, auto-generated or uploaded. Two dependable routes:
+
+```bash
+# yt-dlp: subtitles only, no video download
+yt-dlp --write-auto-sub --skip-download --sub-format vtt --sub-lang en URL
+```
+
+```python
+# youtube-transcript-api, if you want it in a script
+from youtube_transcript_api import YouTubeTranscriptApi
+lines = YouTubeTranscriptApi.get_transcript("VIDEO_ID")
+```
+
+Save the result into `raw/` with frontmatter naming the video, the channel and
+the URL. Without the URL, a transcript is an anonymous wall of text and the
+agent cannot cite it properly.
+
+## Keep the timestamps
+
+Auto-generated transcripts arrive as timestamped fragments. Strip the
+formatting, keep coarse timestamps every few minutes.
+
+The reason is retrieval: when the wiki says a claim came from minute 34 of a
+talk, you can verify it in ten seconds. Without that, checking means rewatching,
+which means you will not check.
+
+## Clean before ingest
+
+Auto-captions have no punctuation, no speaker labels, and mangle technical
+terms. Have the agent do a pass first:
+
+```
+Read raw/talk-transcript.md. Add punctuation and paragraph breaks, label
+speakers where they change, and fix obvious mistranscriptions of technical
+terms. Do not summarise, do not cut anything, and flag anything you could not
+make sense of.
+```
+
+Do not skip to ingesting the raw caption dump. Concept pages built from
+unpunctuated text come out noticeably worse, because the model spends its
+attention reconstructing sentence boundaries instead of understanding claims.
+
+## Long videos
+
+A three-hour podcast is not one source. Split it by topic before ingesting,
+either by chapter markers if the uploader added them, or by asking the agent to
+propose split points from the transcript.
+
+Ingested whole, a long interview produces one bloated source page and two or
+three vague concepts. Split, it produces the four ideas that were actually in
+it.
+
+## Podcasts and audio
+
+Podcasts rarely ship transcripts. Options, in order of effort: check the show
+notes, many now publish one; run local transcription with Whisper; or use a
+transcription service.
+
+Local transcription is worth setting up if you listen daily. The audio never
+leaves your machine, which matters more for meeting recordings than for
+podcasts.
+
+## What is worth transcribing
+
+Talks, lectures, interviews with practitioners, anything with a specific claim
+you might need later.
+
+Not tutorials you watched to do a task once, and not anything you would not
+reread as an article. Video feels valuable while watching because it takes an
+hour. That feeling is not a signal about the content.
+
+## Next
+
+[PDFs, papers and books](pdfs-and-books.md)
diff --git a/second-brain-os/docs/04-structuring/README.md b/second-brain-os/docs/04-structuring/README.md
new file mode 100644
index 0000000..0c64fe5
--- /dev/null
+++ b/second-brain-os/docs/04-structuring/README.md
@@ -0,0 +1,20 @@
+# Structuring
+
+The rules that decide whether your vault becomes a graph or a landfill.
+
+## Planned
+
+Being written. Outlines for each are in the [roadmap](../ROADMAP.md), and pull requests are welcome.
+
+- One page, one idea
+- The four page types
+- Linking rules
+- Frontmatter schema
+- Naming and aliases
+- Deduplication and merging
+- Contradictions and supersession
+- index.md and log.md
+
+---
+
+[Back to the full guide](../README.md)
diff --git a/second-brain-os/docs/05-graphs/README.md b/second-brain-os/docs/05-graphs/README.md
new file mode 100644
index 0000000..5d9bcb2
--- /dev/null
+++ b/second-brain-os/docs/05-graphs/README.md
@@ -0,0 +1,19 @@
+# Graphs
+
+The part most second-brain guides skip: what the graph is for and how to make it do work.
+
+## Planned
+
+Being written. Outlines for each are in the [roadmap](../ROADMAP.md), and pull requests are welcome.
+
+- Graph basics for a knowledge base
+- Reading the Obsidian graph view
+- Typed links
+- Graph vs embeddings
+- GraphRAG and where it fits
+- Exporting the graph
+- Graph metrics worth tracking
+
+---
+
+[Back to the full guide](../README.md)
diff --git a/second-brain-os/docs/06-agents/README.md b/second-brain-os/docs/06-agents/README.md
new file mode 100644
index 0000000..4315d03
--- /dev/null
+++ b/second-brain-os/docs/06-agents/README.md
@@ -0,0 +1,18 @@
+# Agents
+
+Turning a one-off setup into a system that maintains itself.
+
+## Planned
+
+Being written. Outlines for each are in the [roadmap](../ROADMAP.md), and pull requests are welcome.
+
+- Agent roles
+- Scheduling
+- Subagents and parallel work
+- Hooks
+- Skills and slash commands
+- Guardrails
+
+---
+
+[Back to the full guide](../README.md)
diff --git a/second-brain-os/docs/07-retrieval/README.md b/second-brain-os/docs/07-retrieval/README.md
new file mode 100644
index 0000000..ab1e4e5
--- /dev/null
+++ b/second-brain-os/docs/07-retrieval/README.md
@@ -0,0 +1,17 @@
+# Retrieval
+
+How to actually ask your vault things and get answers worth trusting.
+
+## Planned
+
+Being written. Outlines for each are in the [roadmap](../ROADMAP.md), and pull requests are welcome.
+
+- Asking the vault
+- Query patterns
+- Search tools
+- Adding RAG when you need it
+- Context budget
+
+---
+
+[Back to the full guide](../README.md)
diff --git a/second-brain-os/docs/08-outputs/README.md b/second-brain-os/docs/08-outputs/README.md
new file mode 100644
index 0000000..75cb614
--- /dev/null
+++ b/second-brain-os/docs/08-outputs/README.md
@@ -0,0 +1,16 @@
+# Outputs
+
+The vault earns its keep when things come out of it.
+
+## Planned
+
+Being written. Outlines for each are in the [roadmap](../ROADMAP.md), and pull requests are welcome.
+
+- Writing from the vault
+- Research reports
+- Publishing and export
+- Learning from your own vault
+
+---
+
+[Back to the full guide](../README.md)
diff --git a/second-brain-os/docs/09-maintenance/README.md b/second-brain-os/docs/09-maintenance/README.md
new file mode 100644
index 0000000..015c0bf
--- /dev/null
+++ b/second-brain-os/docs/09-maintenance/README.md
@@ -0,0 +1,18 @@
+# Maintenance
+
+What keeps the thing alive after the novelty wears off.
+
+## Planned
+
+Being written. Outlines for each are in the [roadmap](../ROADMAP.md), and pull requests are welcome.
+
+- Linting the vault
+- Review cadence
+- Versioning
+- Backups and portability
+- Privacy
+- Scaling past a thousand pages
+
+---
+
+[Back to the full guide](../README.md)
diff --git a/second-brain-os/docs/10-troubleshooting/README.md b/second-brain-os/docs/10-troubleshooting/README.md
new file mode 100644
index 0000000..b79968f
--- /dev/null
+++ b/second-brain-os/docs/10-troubleshooting/README.md
@@ -0,0 +1,17 @@
+# Troubleshooting
+
+Concrete failures, with fixes.
+
+## Planned
+
+Being written. Outlines for each are in the [roadmap](../ROADMAP.md), and pull requests are welcome.
+
+- The failures everyone hits
+- The agent writes garbage
+- Broken links and orphans
+- The vault got too big
+- FAQ
+
+---
+
+[Back to the full guide](../README.md)
diff --git a/second-brain-os/docs/README.md b/second-brain-os/docs/README.md
new file mode 100644
index 0000000..dd6338d
--- /dev/null
+++ b/second-brain-os/docs/README.md
@@ -0,0 +1,22 @@
+# The guide
+
+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.
+
+| 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 | in progress |
+| [Graphs](05-graphs/README.md) | what the graph is for, typed links, GraphRAG, metrics | in progress |
+| [Agents](06-agents/README.md) | roles, schedules, hooks, guardrails | in progress |
+| [Retrieval](07-retrieval/README.md) | query patterns, search, context budget | in progress |
+| [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 |
+
+---
+
+[Back to the repo](../README.md)
diff --git a/second-brain-os/docs/ROADMAP.md b/second-brain-os/docs/ROADMAP.md
new file mode 100644
index 0000000..60d6fd0
--- /dev/null
+++ b/second-brain-os/docs/ROADMAP.md
@@ -0,0 +1,371 @@
+# Roadmap
+
+What each planned page will cover. Sections marked done are written in full; the rest are outlines.
+
+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)
+
+Why an LLM-maintained knowledge base beats the note system you abandoned, and what the pattern actually is.
+
+- [ ] **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**
+ - 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**
+ - 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**
+ - 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**
+ - 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**
+ - 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**
+ - 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)
+
+From zero to a vault your agent maintains, in one evening.
+
+- [x] **Obsidian and your first vault**
+ - Install and create a local vault
+ - Why the vault is just a folder
+ - Settings worth changing on day one
+ - Mobile and sync considerations
+- [x] **Vault structure**
+ - raw/, wiki/, output/ and what belongs in each
+ - Page-type folders: sources, entities, concepts, synthesis
+ - index.md and log.md as the agent's control surface
+ - Structures to avoid and why deep folder trees fight the graph
+- [x] **Claude Code in the vault**
+ - Installing and starting Claude Code inside the vault folder
+ - Permissions and what to allow
+ - First run: pointing it at the structure
+ - Working sessions vs scheduled runs
+- [x] **Writing your CLAUDE.md**
+ - What belongs in the instruction file and what does not
+ - Page contracts: shape of each page type
+ - Linking rules the agent must follow every time
+ - Iterating on CLAUDE.md as the vault grows
+- [x] **Plugins worth installing**
+ - Web Clipper
+ - Dataview and what it buys you
+ - Templater
+ - Plugins that conflict with agent-maintained files
+- [x] **MCP for Obsidian**
+ - When you need MCP and when files are enough
+ - Local REST API plugin plus claude mcp add
+ - What MCP unlocks: working while Obsidian is closed
+ - Security notes for a local server
+- [x] **Git, sync and backups**
+ - Why a vault is an ideal git repo
+ - What to commit and what to ignore
+ - Sync options across machines
+ - Recovering from a bad agent run
+
+## Ingestion (done)
+
+Getting everything you read, watch and write into raw/ with as little friction as possible.
+
+- [x] **Web articles**
+ - Obsidian Web Clipper setup and templates
+ - Clipping to raw/ with consistent frontmatter
+ - Paywalls, newsletters and dynamic pages
+ - What to clip and what to skip
+- [x] **YouTube and podcasts**
+ - Pulling transcripts reliably
+ - Timestamps and why to keep them
+ - Long videos: chunking before ingest
+ - Audio-only sources and transcription options
+- [x] **PDFs, papers and books**
+ - Text extraction that preserves structure
+ - Scanned documents and OCR
+ - Highlights from ebook readers
+ - Handling papers with figures and tables
+- [x] **Chat exports**
+ - Exporting Claude and ChatGPT history
+ - Converting a JSON export into per-conversation markdown
+ - Filtering noise: which conversations are worth ingesting
+ - Privacy pass before anything enters the vault
+- [x] **Voice notes and meetings**
+ - Capture on mobile
+ - Transcription pipeline
+ - Turning a meeting into decisions and entities
+ - Keeping personal audio out of shared vaults
+- [x] **Newsletters and email**
+ - A dedicated capture address
+ - Automated forwarding into raw/
+ - Deduplicating recurring newsletters
+ - When email is not worth ingesting
+- [x] **Backfilling years of material**
+ - Ordering the backfill so early pages do not get overwritten
+ - Batching: how many sources per run
+ - Cost control on large imports
+ - Checkpoints and resuming
+
+## Structuring (outline)
+
+The rules that decide whether your vault becomes a graph or a landfill.
+
+- [ ] **One page, one idea**
+ - What atomic means in practice
+ - Splitting a source into concepts
+ - How long a page should be
+ - When to merge instead of split
+- [ ] **The four page types**
+ - Sources: one page per ingested item
+ - Entities: people, orgs, products, tools
+ - Concepts: ideas, frameworks, methods
+ - Synthesis: comparisons, themes, open questions
+- [ ] **Linking rules**
+ - Link on first mention, every page type
+ - Minimum and maximum links per page
+ - Links as claims, not decoration
+ - Preventing hub pages from swallowing the graph
+- [ ] **Frontmatter schema**
+ - Required fields per page type
+ - Dates, source URLs, confidence
+ - Tags: a small controlled vocabulary
+ - Keeping the schema stable as the vault grows
+- [ ] **Naming and aliases**
+ - Canonical titles and why they matter for wikilinks
+ - Aliases for acronyms and alternate names
+ - Disambiguating two things with the same name
+ - Renaming without breaking links
+- [ ] **Deduplication and merging**
+ - Detecting near-duplicate pages
+ - Merge procedure that preserves backlinks
+ - Redirect stubs
+ - Scheduling dedupe rather than doing it live
+- [ ] **Contradictions and supersession**
+ - Two sources disagree: what the page should say
+ - Marking superseded claims instead of deleting them
+ - Confidence and provenance fields
+ - Why silent overwrites are the worst failure mode
+- [ ] **index.md and log.md**
+ - The index as a navigable catalog, not a dump
+ - What the agent must record in the log
+ - Using the log to audit and roll back
+ - Keeping both files from growing unbounded
+
+## Graphs (outline)
+
+The part most second-brain guides skip: what the graph is for and how to make it do work.
+
+- [ ] **Graph basics for a knowledge base**
+ - Nodes, edges, direction and weight in plain terms
+ - Why a knowledge base is a graph whether you plan it or not
+ - Density, clustering, path length and what they tell you
+ - The failure shapes: stars, chains and islands
+- [ ] **Reading the Obsidian graph view**
+ - Local vs global graph
+ - Filters and groups that make it useful
+ - Spotting orphans and over-linked hubs
+ - Why a pretty graph is not a healthy one
+- [ ] **Typed links**
+ - Untyped wikilinks lose meaning at scale
+ - A minimal relation vocabulary: supports, contradicts, extends, part-of
+ - Encoding types in frontmatter or inline
+ - Querying by relation type
+- [ ] **Graph vs embeddings**
+ - What each retrieval method is actually good at
+ - Why similarity misses reasoning across sources
+ - Hybrid setups
+ - Cost and maintenance compared
+- [ ] **GraphRAG and where it fits**
+ - The idea in one page
+ - Entity and relation extraction from your own vault
+ - Community detection and summary layers
+ - Whether a personal vault is big enough to need it
+- [ ] **Exporting the graph**
+ - Parsing wikilinks into an edge list
+ - Loading into Kuzu, Neo4j or NetworkX
+ - Visualizing outside Obsidian
+ - Keeping the export in sync
+- [ ] **Graph metrics worth tracking**
+ - Orphan rate
+ - Average degree and its healthy range
+ - Clusters as evidence of your real interests
+ - Tracking metrics over time
+
+## Agents (outline)
+
+Turning a one-off setup into a system that maintains itself.
+
+- [ ] **Agent roles**
+ - Ingestor, linker, reviewer, researcher
+ - One job per agent and why
+ - Handoffs between agents
+ - Roles that are not worth automating
+- [ ] **Scheduling**
+ - Cadence per job: hourly, daily, weekly
+ - Scheduled tasks, cron and CI options
+ - What a run should produce
+ - Detecting silent failures
+- [ ] **Subagents and parallel work**
+ - When to fan out
+ - Context isolation between subagents
+ - Merging parallel edits without conflicts
+ - Cost of parallelism
+- [ ] **Hooks**
+ - Triggering on file changes in raw/
+ - Pre-write validation
+ - Post-run linting
+ - Keeping hooks fast
+- [ ] **Skills and slash commands**
+ - Skills for repeated behavior, commands for repeated tasks
+ - Where to store them so any agent can use them
+ - Versioning your skills alongside the vault
+ - Testing a skill before trusting it with the vault
+- [ ] **Guardrails**
+ - Never let an agent delete without a log entry
+ - Write scopes: which folders are off limits
+ - Dry-run mode
+ - Reviewing agent output in git diffs
+
+## Retrieval (outline)
+
+How to actually ask your vault things and get answers worth trusting.
+
+- [ ] **Asking the vault**
+ - Question shapes that work
+ - Anchoring answers to pages and sources
+ - Requiring citations from your own vault
+ - What to do when the answer is not in there
+- [ ] **Query patterns**
+ - What do I know about X
+ - What connects X and Y
+ - What have I changed my mind about
+ - What is missing from my understanding of X
+- [ ] **Search tools**
+ - ripgrep as the default
+ - Dataview queries
+ - Full-text index options
+ - When search is slow enough to matter
+- [ ] **Adding RAG when you need it**
+ - The size threshold where it starts to pay
+ - Chunking a wiki that is already chunked
+ - Keeping the index fresh
+ - Hybrid: graph for structure, vectors for recall
+- [ ] **Context budget**
+ - Why you should not paste the whole vault
+ - Progressive disclosure: index first, pages second
+ - Summary layers
+ - Measuring what the agent actually read
+
+## Outputs (outline)
+
+The vault earns its keep when things come out of it.
+
+- [ ] **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**
+ - 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**
+ - 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**
+ - Generating questions from concept pages
+ - Spaced repetition against your notes
+ - Finding what you saved but never understood
+ - Measuring learning instead of collecting
+
+## Maintenance (outline)
+
+What keeps the thing alive after the novelty wears off.
+
+- [ ] **Linting the vault**
+ - Broken links, orphan pages, empty stubs
+ - Schema violations
+ - Automating the lint run
+ - Reading a lint report
+- [ ] **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**
+ - Commit granularity for agent runs
+ - Reading diffs of generated pages
+ - Reverting a bad ingest
+ - Branching for experiments
+- [ ] **Backups and portability**
+ - Local, cloud and offline copies
+ - Testing a restore
+ - Moving to another editor or agent
+ - Avoiding formats that trap you
+- [ ] **Privacy**
+ - Deciding what never enters the vault
+ - Redaction before ingest
+ - Local models for sensitive material
+ - Sharing a vault safely
+- [ ] **Scaling past a thousand pages**
+ - Where the plain-text approach strains
+ - Splitting vaults by domain
+ - Summary layers and hierarchical indexes
+ - Performance tuning
+
+## Troubleshooting (outline)
+
+Concrete failures, with fixes.
+
+- [ ] **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**
+ - 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**
+ - Why renames break wikilinks
+ - Bulk fixing safely
+ - Preventing orphans at ingest time
+ - Auditing after a big import
+- [ ] **The vault got too big**
+ - Symptoms
+ - Splitting vs summarizing
+ - Archiving cold material
+ - Rebuilding the index
+- [ ] **FAQ**
+ - Do I need MCP
+ - Does this work with other agents
+ - How much does it cost to run
+ - Can I use a local model
+
+---
+
+[Back to the guide](README.md)
diff --git a/second-brain-os/examples/.gitkeep b/second-brain-os/examples/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/second-brain-os/examples/README.md b/second-brain-os/examples/README.md
new file mode 100644
index 0000000..ee56b74
--- /dev/null
+++ b/second-brain-os/examples/README.md
@@ -0,0 +1,13 @@
+# Examples
+
+Real vaults and real output, so you can see what the system produces before
+committing an evening to it.
+
+Planned:
+
+- A worked ingest: one article in, the exact pages that came out
+- A vault at 30 days: structure, graph, what it can answer
+- A vault at 6 months: what changed, what broke, what was worth it
+- A research report generated from a vault, with the pages it drew on
+
+Contributions welcome. Screenshots and anonymised page samples are enough.
diff --git a/second-brain-os/resources/README.md b/second-brain-os/resources/README.md
new file mode 100644
index 0000000..31d505e
--- /dev/null
+++ b/second-brain-os/resources/README.md
@@ -0,0 +1,12 @@
+# Resources
+
+Curated, not exhaustive. Everything here is something worth the time it takes
+to read or install.
+
+- [Tools](tools.md) - editors, capture, agents, graph and search
+- [Repositories](repos.md) - open-source implementations worth reading
+- [Reading](reading.md) - the ideas behind the pattern
+- [Papers](papers.md) - retrieval, graphs and memory research
+
+Links are checked before they go in. If something here has gone stale or a
+better option exists, open a pull request.
diff --git a/second-brain-os/resources/papers.md b/second-brain-os/resources/papers.md
new file mode 100644
index 0000000..99b4017
--- /dev/null
+++ b/second-brain-os/resources/papers.md
@@ -0,0 +1,18 @@
+# Papers
+
+Research relevant to how a knowledge base retrieves and reasons. Read these if
+you want to understand why the wiki approach works, or to decide whether you
+need a vector database at all.
+
+- **From Local to Global: A Graph RAG Approach to Query-Focused
+ Summarization** (Microsoft Research). Introduces GraphRAG: build an entity
+ graph from a corpus, summarise communities, answer global questions the
+ chunk-retrieval approach cannot.
+- **HippoRAG**. Memory-inspired retrieval using a knowledge graph and
+ personalised PageRank, aimed at multi-hop questions.
+- **Lost in the Middle: How Language Models Use Long Contexts**. Why dumping a
+ whole vault into context degrades answers, and the argument for structured
+ retrieval over long-context stuffing.
+
+<!-- TODO before publishing: verify each citation against the arXiv listing and
+ add direct links. Nothing goes in this file from secondary coverage. -->
diff --git a/second-brain-os/resources/reading.md b/second-brain-os/resources/reading.md
new file mode 100644
index 0000000..137928b
--- /dev/null
+++ b/second-brain-os/resources/reading.md
@@ -0,0 +1,26 @@
+# Reading
+
+## The pattern
+
+- Karpathy's `llm-wiki` gist (2026-04-04). The spec everything else builds on:
+ the LLM maintains the wiki, the wiki is primary, raw sources are archive.
+
+## The tradition it comes from
+
+- **Building a Second Brain**, Tiago Forte. Where the term comes from, and the
+ PARA method. Written before agents existed, which is exactly what makes it
+ useful to read now: most of the book is about the maintenance work that an
+ agent removes.
+- **How to Take Smart Notes**, Sönke Ahrens. The Zettelkasten method. The
+ argument for atomic notes and dense linking still holds; the manual labour it
+ demands is the part that killed it for most people.
+- **Andy Matuschak's evergreen notes**. The strongest case for notes written to
+ be reread, and a useful counterweight: not everything should be delegated to
+ a machine.
+
+## Why the maintenance argument matters
+
+Every note system in the list above works. They fail on the same thing, which
+is that the person maintaining them gets tired. That is the entire reason this
+pattern is different, and it is worth reading the originals to see how much of
+the design was shaped by that constraint.
diff --git a/second-brain-os/resources/repos.md b/second-brain-os/resources/repos.md
new file mode 100644
index 0000000..bb3b3de
--- /dev/null
+++ b/second-brain-os/resources/repos.md
@@ -0,0 +1,26 @@
+# Repositories
+
+Open-source implementations of the pattern. Reading other people's page
+contracts and prompts is the fastest way to improve your own.
+
+- **claude-obsidian** by AgriciDaniel. A self-organizing second brain on the
+ Karpathy wiki pattern. Scaffolds the vault, sets up the connection, and ships
+ presets for different roles: executive, builder, creator, researcher.
+- **obsidian-second-brain** by eugeniughelbur. Around 43 ready commands such as
+ `/obsidian-save`, `/obsidian-daily` and `/obsidian-find`. Works across Claude,
+ Codex and Gemini, so you are not locked to one agent.
+- **second-brain-starter** by coleam00. Interviews you, generates a plan for a
+ proactive assistant, then builds it from plain text files, Python and an
+ Obsidian vault.
+- **second-brain** by NicholasSpisak. Skills for ingest, lint and query,
+ installable through npm, close to the original gist.
+
+All of them are text files and scripts. Clone one and reshape it, or take the
+parts you like and keep your own structure.
+
+Karpathy's original `llm-wiki` gist is the source document for all of these. It
+was published on 2026-04-04 and describes the pattern at the level of intent
+rather than implementation, which is why every repo above fills the gaps
+differently.
+
+<!-- TODO before publishing: add direct URLs, verified by hand, for all five. -->
diff --git a/second-brain-os/resources/tools.md b/second-brain-os/resources/tools.md
new file mode 100644
index 0000000..031c12c
--- /dev/null
+++ b/second-brain-os/resources/tools.md
@@ -0,0 +1,42 @@
+# Tools
+
+## The core stack
+
+- **[Obsidian](https://obsidian.md)** - local markdown editor. The vault is a
+ plain folder, which is the whole reason agents work well with it.
+- **[Obsidian Web Clipper](https://obsidian.md/clipper)** - official browser
+ extension for saving articles into the vault. Built by the Obsidian team.
+- **[Claude Code](https://claude.com/claude-code)** - the agent that maintains
+ the wiki. Runs in the vault folder and edits files directly.
+
+## Obsidian plugins
+
+- **Dataview** - queries over frontmatter. Useful for dashboards of what needs
+ review.
+- **Templater** - templates with variables, for the page shapes in
+ `vault-template/templates/`.
+- **Local REST API** - required only if you want the agent to reach the vault
+ over MCP rather than through the filesystem.
+
+## Capture
+
+- **yt-dlp** - subtitles and audio from video platforms.
+- **youtube-transcript-api** - Python library for pulling transcripts directly.
+- **Zotero** - reference manager with a markdown export path for papers.
+- **Readwise** - highlights from Kindle and read-later apps, exports to
+ Obsidian.
+
+## Search and graph
+
+- **ripgrep** - fast enough that most vaults never need an index.
+- **NetworkX** - graph analysis in Python once you have exported an edge list.
+- **Kuzu** - embedded graph database, no server to run.
+- **Neo4j** - full graph database, worth it only at scale.
+- **Gephi** - visual graph exploration beyond what Obsidian's graph view does.
+
+## Alternatives to Obsidian
+
+- **Logseq** - outliner, also plain markdown, block-level references.
+- **Foam** - the same pattern inside VS Code.
+- **Plain folders plus git** - genuinely viable. Obsidian is a viewer for the
+ graph, not a requirement of it.
diff --git a/second-brain-os/scripts/README.md b/second-brain-os/scripts/README.md
new file mode 100644
index 0000000..aa8017c
--- /dev/null
+++ b/second-brain-os/scripts/README.md
@@ -0,0 +1,21 @@
+# scripts
+
+Small, dependency-free Python scripts. Everything here reads the vault as
+plain files, so nothing breaks if you switch editors or agents.
+
+| Script | What it does |
+|---|---|
+| `link_check.py` | Broken wikilinks, orphan pages, stubs |
+| `vault_stats.py` | Page counts, link density, orphan rate, most-linked pages |
+| `graph_export.py` | Wikilink graph as CSV edges or GraphML for Gephi |
+| `chat_export_to_md.py` | Chat history export into per-conversation markdown |
+
+```bash
+python3 scripts/vault_stats.py ~/second-brain
+python3 scripts/link_check.py ~/second-brain
+python3 scripts/graph_export.py ~/second-brain graph.graphml --format graphml
+```
+
+The agent can do all of this in natural language, but a script gives the same
+answer every time and costs nothing to run, which is what you want for anything
+you check weekly.
diff --git a/second-brain-os/scripts/chat_export_to_md.py b/second-brain-os/scripts/chat_export_to_md.py
new file mode 100644
index 0000000..6f85d7e
--- /dev/null
+++ b/second-brain-os/scripts/chat_export_to_md.py
@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Convert an exported chat history JSON into one markdown file per conversation.
+
+Usage:
+ python3 chat_export_to_md.py conversations.json ./raw --min-words 150
+
+Works with the common export shape used by Claude and ChatGPT: a JSON array of
+conversations, each with a name/title and a list of messages. Unknown shapes are
+skipped with a warning rather than guessed at.
+
+Read the privacy page before running this on a real export. Chat history is the
+single most sensitive thing most people would put in a vault.
+"""
+import argparse
+import json
+import os
+import re
+import sys
+
+
+def slug(text, limit=60):
+ s = re.sub(r"[^\w\s-]", "", text.lower()).strip()
+ s = re.sub(r"[\s_]+", "-", s)
+ return (s[:limit] or "untitled").strip("-")
+
+
+def text_of(message):
+ content = message.get("content", message.get("text", ""))
+ if isinstance(content, str):
+ return content
+ if isinstance(content, list):
+ parts = []
+ for c in content:
+ if isinstance(c, str):
+ parts.append(c)
+ elif isinstance(c, dict):
+ parts.append(c.get("text", ""))
+ return "\n".join(p for p in parts if p)
+ if isinstance(content, dict):
+ return "\n".join(content.get("parts", []) or [])
+ return ""
+
+
+def main():
+ ap = argparse.ArgumentParser()
+ ap.add_argument("export")
+ ap.add_argument("outdir")
+ ap.add_argument("--min-words", type=int, default=150,
+ help="skip conversations shorter than this")
+ args = ap.parse_args()
+
+ with open(args.export, encoding="utf-8") as fh:
+ data = json.load(fh)
+
+ if isinstance(data, dict):
+ data = data.get("conversations", [])
+ if not isinstance(data, list):
+ sys.exit("unrecognised export shape: expected a list of conversations")
+
+ os.makedirs(args.outdir, exist_ok=True)
+ written = skipped = 0
+
+ for conv in data:
+ if not isinstance(conv, dict):
+ continue
+ title = conv.get("name") or conv.get("title") or "untitled"
+ created = (conv.get("created_at") or conv.get("create_time") or "")
+ messages = conv.get("chat_messages") or conv.get("messages") or []
+ if isinstance(messages, dict):
+ messages = list(messages.values())
+
+ body = []
+ for m in messages:
+ if not isinstance(m, dict):
+ continue
+ role = m.get("sender") or m.get("role") or "unknown"
+ t = text_of(m).strip()
+ if t:
+ body.append(f"**{role}**\n\n{t}\n")
+
+ joined = "\n".join(body)
+ if len(joined.split()) < args.min_words:
+ skipped += 1
+ continue
+
+ front = (f"---\ntitle: {title}\nsource: chat export\n"
+ f"created: {str(created)[:10]}\n---\n\n# {title}\n\n")
+ path = os.path.join(args.outdir, f"{slug(str(title))}.md")
+ n = 2
+ while os.path.exists(path):
+ path = os.path.join(args.outdir, f"{slug(str(title))}-{n}.md")
+ n += 1
+ with open(path, "w", encoding="utf-8") as fh:
+ fh.write(front + joined)
+ written += 1
+
+ print(f"wrote {written} files to {args.outdir}, skipped {skipped} short conversations")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/second-brain-os/scripts/graph_export.py b/second-brain-os/scripts/graph_export.py
new file mode 100644
index 0000000..65b540b
--- /dev/null
+++ b/second-brain-os/scripts/graph_export.py
@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Export a vault's wikilink graph as CSV edges or GraphML.
+
+Usage:
+ python3 graph_export.py /path/to/vault edges.csv
+ python3 graph_export.py /path/to/vault graph.graphml --format graphml
+
+CSV loads into NetworkX, Kuzu, Neo4j or a spreadsheet. GraphML opens in Gephi.
+No dependencies.
+"""
+import argparse
+import csv
+import os
+import re
+from xml.sax.saxutils import escape
+
+LINK = re.compile(r"\[\[([^\]|#]+)(?:#[^\]|]+)?(?:\|[^\]]+)?\]\]")
+TYPE = re.compile(r"^type:\s*(\S+)", re.M)
+SKIP_DIRS = {".git", ".obsidian", ".trash", "node_modules", "raw"}
+
+
+def load(vault):
+ pages = {}
+ for dirpath, dirnames, filenames in os.walk(vault):
+ dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+ for name in filenames:
+ if name.endswith(".md"):
+ path = os.path.join(dirpath, name)
+ with open(path, encoding="utf-8", errors="replace") as fh:
+ pages[path] = fh.read()
+ return pages
+
+
+def main():
+ ap = argparse.ArgumentParser()
+ ap.add_argument("vault")
+ ap.add_argument("out")
+ ap.add_argument("--format", choices=["csv", "graphml"], default="csv")
+ args = ap.parse_args()
+
+ pages = load(args.vault)
+ stems = {os.path.splitext(os.path.basename(p))[0]: p for p in pages}
+ lower = {k.lower(): k for k in stems}
+
+ nodes = {}
+ for stem, path in stems.items():
+ m = TYPE.search(pages[path])
+ nodes[stem] = m.group(1) if m else "untyped"
+
+ edges = []
+ for stem, path in stems.items():
+ for target in LINK.findall(pages[path]):
+ key = lower.get(target.strip().lower())
+ if key and key != stem:
+ edges.append((stem, key))
+
+ if args.format == "csv":
+ with open(args.out, "w", newline="", encoding="utf-8") as fh:
+ w = csv.writer(fh)
+ w.writerow(["source", "target"])
+ w.writerows(edges)
+ else:
+ with open(args.out, "w", encoding="utf-8") as fh:
+ fh.write('<?xml version="1.0" encoding="UTF-8"?>\n')
+ fh.write('<graphml xmlns="http://graphml.graphdrawing.org/xmlns">\n')
+ fh.write('<key id="t" for="node" attr.name="type" attr.type="string"/>\n')
+ fh.write('<graph edgedefault="directed">\n')
+ for n, t in nodes.items():
+ fh.write(f'<node id="{escape(n)}"><data key="t">{escape(t)}</data></node>\n')
+ for i, (s, t) in enumerate(edges):
+ fh.write(f'<edge id="e{i}" source="{escape(s)}" target="{escape(t)}"/>\n')
+ fh.write("</graph>\n</graphml>\n")
+
+ print(f"{len(nodes)} nodes, {len(edges)} edges -> {args.out}")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/second-brain-os/scripts/link_check.py b/second-brain-os/scripts/link_check.py
new file mode 100644
index 0000000..1f88807
--- /dev/null
+++ b/second-brain-os/scripts/link_check.py
@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Check a second-brain vault for broken wikilinks, orphan pages and stubs.
+
+Usage:
+ python3 link_check.py /path/to/vault [--json]
+
+No dependencies. Reads only; never modifies the vault.
+"""
+import argparse
+import json
+import os
+import re
+import sys
+
+LINK = re.compile(r"\[\[([^\]|#]+)(?:#[^\]|]+)?(?:\|[^\]]+)?\]\]")
+SKIP_DIRS = {".git", ".obsidian", ".trash", "node_modules", "raw"}
+STUB_WORDS = 40
+
+
+def collect(vault):
+ pages = {}
+ for dirpath, dirnames, filenames in os.walk(vault):
+ dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+ for name in filenames:
+ if not name.endswith(".md"):
+ continue
+ path = os.path.join(dirpath, name)
+ with open(path, encoding="utf-8", errors="replace") as fh:
+ text = fh.read()
+ pages[path] = text
+ return pages
+
+
+def title_of(path, text):
+ stem = os.path.splitext(os.path.basename(path))[0]
+ return stem
+
+
+def aliases_of(text):
+ m = re.search(r"^---\n(.*?)\n---", text, re.S)
+ if not m:
+ return []
+ m2 = re.search(r"^aliases:\s*\[(.*?)\]", m.group(1), re.M)
+ if not m2:
+ return []
+ return [a.strip().strip("\"'") for a in m2.group(1).split(",") if a.strip()]
+
+
+def main():
+ ap = argparse.ArgumentParser()
+ ap.add_argument("vault")
+ ap.add_argument("--json", action="store_true")
+ args = ap.parse_args()
+
+ if not os.path.isdir(args.vault):
+ sys.exit(f"not a directory: {args.vault}")
+
+ pages = collect(args.vault)
+ names = {}
+ for path, text in pages.items():
+ names[title_of(path, text).lower()] = path
+ for a in aliases_of(text):
+ names.setdefault(a.lower(), path)
+
+ outbound = {p: set() for p in pages}
+ inbound = {p: set() for p in pages}
+ broken = []
+
+ for path, text in pages.items():
+ for target in LINK.findall(text):
+ key = target.strip().lower()
+ if key in names:
+ dest = names[key]
+ if dest != path:
+ outbound[path].add(dest)
+ inbound[dest].add(path)
+ else:
+ broken.append((path, target.strip()))
+
+ orphans = [p for p in pages if not inbound[p] and not p.endswith(("index.md", "log.md", "README.md"))]
+ stubs = [p for p, t in pages.items() if len(t.split()) < STUB_WORDS]
+ links = sum(len(v) for v in outbound.values())
+
+ result = {
+ "pages": len(pages),
+ "links": links,
+ "avg_links_per_page": round(links / len(pages), 2) if pages else 0,
+ "broken": [{"page": os.path.relpath(p, args.vault), "target": t} for p, t in broken],
+ "orphans": [os.path.relpath(p, args.vault) for p in sorted(orphans)],
+ "stubs": [os.path.relpath(p, args.vault) for p in sorted(stubs)],
+ }
+
+ if args.json:
+ print(json.dumps(result, indent=2))
+ return
+
+ print(f"pages: {result['pages']}")
+ print(f"links: {result['links']} (avg {result['avg_links_per_page']} per page)")
+ print(f"broken links: {len(result['broken'])}")
+ for b in result["broken"][:40]:
+ print(f" {b['page']} -> [[{b['target']}]]")
+ print(f"orphans: {len(result['orphans'])}")
+ for o in result["orphans"][:40]:
+ print(f" {o}")
+ print(f"stubs (<{STUB_WORDS} words): {len(result['stubs'])}")
+ for s in result["stubs"][:40]:
+ print(f" {s}")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/second-brain-os/scripts/vault_stats.py b/second-brain-os/scripts/vault_stats.py
new file mode 100644
index 0000000..db2d3c3
--- /dev/null
+++ b/second-brain-os/scripts/vault_stats.py
@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Print health metrics for a second-brain vault.
+
+Usage:
+ python3 vault_stats.py /path/to/vault
+
+Reports page counts by type, link density, orphan rate and the most connected
+pages. Track these over time: a rising orphan rate means ingestion is running
+without linking, which is the usual way a vault stops being useful.
+"""
+import os
+import re
+import sys
+from collections import Counter, defaultdict
+
+LINK = re.compile(r"\[\[([^\]|#]+)(?:#[^\]|]+)?(?:\|[^\]]+)?\]\]")
+TYPE = re.compile(r"^type:\s*(\S+)", re.M)
+SKIP_DIRS = {".git", ".obsidian", ".trash", "node_modules", "raw"}
+
+
+def main():
+ if len(sys.argv) != 2:
+ sys.exit("usage: vault_stats.py /path/to/vault")
+ vault = sys.argv[1]
+
+ pages, types = {}, Counter()
+ for dirpath, dirnames, filenames in os.walk(vault):
+ dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+ for name in filenames:
+ if name.endswith(".md"):
+ path = os.path.join(dirpath, name)
+ with open(path, encoding="utf-8", errors="replace") as fh:
+ text = fh.read()
+ pages[path] = text
+ m = TYPE.search(text)
+ types[m.group(1) if m else "untyped"] += 1
+
+ if not pages:
+ sys.exit("no markdown files found")
+
+ stems = {os.path.splitext(os.path.basename(p))[0].lower(): p for p in pages}
+ indeg = defaultdict(int)
+ total = 0
+ for path, text in pages.items():
+ for target in LINK.findall(text):
+ dest = stems.get(target.strip().lower())
+ if dest and dest != path:
+ indeg[dest] += 1
+ total += 1
+
+ orphans = [p for p in pages if indeg[p] == 0]
+ words = sum(len(t.split()) for t in pages.values())
+
+ print(f"pages {len(pages)}")
+ for t, c in types.most_common():
+ print(f" {t:<12} {c}")
+ print(f"words {words:,}")
+ print(f"links {total}")
+ print(f"avg degree {total / len(pages):.2f}")
+ print(f"orphan rate {100 * len(orphans) / len(pages):.1f}%")
+ print("\nmost linked:")
+ for path, n in sorted(indeg.items(), key=lambda kv: -kv[1])[:10]:
+ print(f" {n:>4} {os.path.relpath(path, vault)}")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/second-brain-os/skills/README.md b/second-brain-os/skills/README.md
new file mode 100644
index 0000000..37fd07f
--- /dev/null
+++ b/second-brain-os/skills/README.md
@@ -0,0 +1,30 @@
+# skills
+
+Agent skills for running the vault. They are plain `SKILL.md` files, so they
+work with Claude Code, and with any other agent that supports the Agent Skills
+format.
+
+| Skill | What it does | When it fires |
+|---|---|---|
+| `second-brain-ingest` | Raw source into linked wiki pages | New material lands in `raw/` |
+| `second-brain-lint` | Structural audit and repair | Weekly, or after a bulk import |
+| `second-brain-query` | Answers grounded in your own pages | You ask the vault something |
+| `second-brain-review` | Periodic review of what changed | Weekly or monthly |
+
+## Install
+
+Copy the folders into your skills directory:
+
+```bash
+cp -r skills/* ~/.claude/skills/
+```
+
+Or keep them inside the vault at `.claude/skills/` so they travel with it and
+get versioned alongside your notes.
+
+## Editing them
+
+These are opinionated. The linking rules in `second-brain-ingest` and the
+citation rule in `second-brain-query` are the two that matter most; loosen
+those and the vault degrades into a folder of summaries. Everything else is
+fair game to adapt.
diff --git a/second-brain-os/skills/second-brain-ingest/SKILL.md b/second-brain-os/skills/second-brain-ingest/SKILL.md
new file mode 100644
index 0000000..e7c59f0
--- /dev/null
+++ b/second-brain-os/skills/second-brain-ingest/SKILL.md
@@ -0,0 +1,81 @@
+---
+name: second-brain-ingest
+description: >-
+ Turn raw source material in a second-brain vault into linked wiki pages:
+ read the source, split it into concepts and entities, write or update pages,
+ connect them to existing pages, and record the run in the log. Use this skill
+ whenever the user drops a file into raw/, pastes an article, transcript or
+ PDF and asks to add it to the vault, says "ingest this", "add this to my
+ second brain", "process raw", or asks to catch up on unprocessed sources,
+ even if they do not name the ingest command. Do NOT use for answering
+ questions from an existing vault, for linting or repairing pages, or for
+ editing notes the user wrote by hand.
+---
+
+# Ingest a source
+
+An ingest that only writes a summary page produces a vault that grows without
+getting smarter. The whole value is in the second half of the job: connecting
+the new material to what is already there. A page that lands unlinked is
+invisible within a week.
+
+## Core rule
+
+Nothing is ingested until it is linked. Every run ends with the new pages
+connected to existing pages in both directions.
+
+## Workflow
+
+1. **Read the source completely** before writing anything. Partial reads
+ produce pages built from the introduction, which is where sources are least
+ specific.
+2. **Check what already exists.** Search the wiki for the main entities and
+ concepts. Ingesting into an empty vault and ingesting into a vault of 300
+ pages are different jobs: in the second, most of your work is updating
+ pages, not creating them.
+3. **Write the source page** in `wiki/sources/`. Record claims as claims, with
+ the source attached.
+4. **Extract concepts and entities.** One page per idea. If a concept page
+ exists, add what this source contributes and update `updated:`. If it
+ contradicts what is there, record both positions rather than replacing.
+5. **Link in both directions.** The source page links to every concept and
+ entity it touches; each of those links back. Add any missing target pages,
+ or list them under Gaps in `index.md`.
+6. **Update `index.md` and append to `log.md`** in the same run, because an
+ index that lags is how a vault starts drifting.
+7. **Report** what changed.
+
+## Output format
+
+End every run with this exact shape:
+
+```
+Ingested: <source name>
+New pages: <n> (list)
+Updated pages: <n> (list)
+Links added: <n>
+Contradictions found: <none | description>
+Gaps created: <list of linked pages that do not exist yet>
+```
+
+## Calibration
+
+Over-extraction is the common failure: ten thin concept pages from one article,
+each a restated paragraph. A source usually yields one to three concepts worth
+their own page. If a candidate concept cannot be explained without referring
+back to this one source, it belongs inside the source page instead.
+
+Under-extraction shows up as source pages that contain three separate ideas and
+link to nothing. If a page needs section headings for unrelated topics, split
+it.
+
+## Example
+
+Input: the user drops `raw/karpathy-llm-wiki.md`, a clipped gist, into a vault
+that already has pages for `[[Obsidian]]` and `[[Claude Code]]`.
+
+Output: one source page; a new concept page `[[LLM wiki]]` explaining the
+pattern in plain language; an entity page `[[Andrej Karpathy]]`; updates to
+`[[Obsidian]]` and `[[Claude Code]]` noting their role in the pattern; a link
+from the existing `[[Personal knowledge management]]` concept to the new one;
+index and log updated; report showing 3 new, 3 updated, 11 links.
diff --git a/second-brain-os/skills/second-brain-lint/SKILL.md b/second-brain-os/skills/second-brain-lint/SKILL.md
new file mode 100644
index 0000000..3f0b0f6
--- /dev/null
+++ b/second-brain-os/skills/second-brain-lint/SKILL.md
@@ -0,0 +1,68 @@
+---
+name: second-brain-lint
+description: >-
+ Audit a second-brain vault for structural problems and repair them: broken
+ wikilinks, orphan pages, empty stubs, frontmatter that violates the schema,
+ near-duplicate pages, and stale index entries. Use this skill whenever the
+ user asks to lint, clean, audit or check the health of their vault, says
+ pages feel messy or links are broken, after a large bulk import, or when a
+ scheduled maintenance run fires. Do NOT use for ingesting new sources, for
+ answering questions from the vault, or for rewriting page content that is
+ structurally fine but reads badly.
+---
+
+# Lint the vault
+
+Structural rot is silent. Nothing errors, nothing crashes, the vault just
+slowly stops answering questions well because a third of its pages are
+unreachable. Linting is the only thing that catches it before the owner does.
+
+## Core rule
+
+Report before repairing. Fix the mechanical problems automatically, but never
+delete or merge a page without listing it first and getting a yes, because the
+owner may have written it by hand.
+
+## Workflow
+
+1. **Inventory.** Count pages by type. Build the link graph by parsing every
+ `[[wikilink]]`.
+2. **Broken links.** Links pointing at pages that do not exist. Distinguish
+ two cases: a typo or rename, which you fix, and a genuine gap, which goes
+ into `index.md` under Gaps.
+3. **Orphans.** Pages with no inbound links. For each, either find where it
+ should be linked from and add the link, or flag it as a candidate for
+ deletion.
+4. **Stubs.** Pages under roughly 40 words with no links. Usually a failed
+ ingest. Flag for re-ingest from the original source in `raw/`.
+5. **Schema.** Missing or malformed frontmatter, wrong `type`, missing dates,
+ tags outside the existing vocabulary.
+6. **Near-duplicates.** Pages with very similar titles or aliases. Propose
+ merges; do not perform them unsolicited.
+7. **Index drift.** Pages missing from `index.md`, index entries pointing
+ nowhere.
+8. **Repair**, then append the run to `log.md`.
+
+## Output format
+
+```
+Vault: <n> pages (<n> sources, <n> concepts, <n> entities, <n> synthesis)
+Link graph: <n> links, average <n> per page, <n> orphans
+
+Fixed automatically:
+- <list>
+
+Needs a decision:
+- <list, each with the recommended action>
+
+Health: orphan rate <n>%, broken link rate <n>%, stub rate <n>%
+```
+
+## Calibration
+
+An aggressive linter that merges pages on its own judgement destroys work. A
+timid one that only reports produces a list nobody acts on. The split above is
+the useful line: mechanical fixes happen, semantic decisions get proposed.
+
+Do not run a full lint after every ingest. Weekly, or after an import of more
+than about twenty sources.
diff --git a/second-brain-os/skills/second-brain-query/SKILL.md b/second-brain-os/skills/second-brain-query/SKILL.md
new file mode 100644
index 0000000..4ef4a4e
--- /dev/null
+++ b/second-brain-os/skills/second-brain-query/SKILL.md
@@ -0,0 +1,55 @@
+---
+name: second-brain-query
+description: >-
+ Answer a question from a second-brain vault by reading its own pages, citing
+ the pages used, and saying plainly when the vault does not contain the
+ answer. Use this skill whenever the user asks what they know about a topic,
+ what they have read on something, what connects two ideas, what they have
+ changed their mind about, or asks any question that should be answered from
+ their own notes rather than general knowledge. Do NOT use for ingesting new
+ material, for general questions the vault has nothing to do with, or when the
+ user explicitly wants an answer from the open web.
+---
+
+# Query the vault
+
+A query that quietly falls back on general knowledge is the most damaging thing
+this system can do. The owner built the vault so answers would be grounded in
+what they actually read, and an answer that blends the model's priors with
+their notes is worse than no answer, because it cannot be checked.
+
+## Core rule
+
+Every claim in the answer comes from a page in the vault and names that page.
+Anything you know but the vault does not is labelled as outside knowledge or
+left out.
+
+## Workflow
+
+1. **Start from `index.md`**, not from a full-text sweep. The index is the map;
+ reading it first keeps the context budget for actual pages.
+2. **Follow links outward** from the most relevant pages, one hop at a time.
+ Stop when new pages stop adding anything.
+3. **Answer in plain language**, with `[[page]]` references inline.
+4. **Name the gaps.** If the question has three parts and the vault covers two,
+ say which one it does not.
+5. **Offer the next move** when there is an obvious one: a source worth
+ ingesting, a synthesis page worth writing.
+
+## Output format
+
+Plain prose, then:
+
+```
+Read: <pages consulted>
+Not covered: <what the vault does not answer>
+```
+
+## Calibration
+
+Reading too little is the common failure: answering from three pages when the
+vault has fifteen relevant ones. Reading everything is the opposite failure and
+burns the budget on pages that add nothing.
+
+If the vault has nothing on the topic, say so in one sentence and stop. Do not
+pad the answer with general knowledge to avoid an empty result.
diff --git a/second-brain-os/skills/second-brain-review/SKILL.md b/second-brain-os/skills/second-brain-review/SKILL.md
new file mode 100644
index 0000000..50938ee
--- /dev/null
+++ b/second-brain-os/skills/second-brain-review/SKILL.md
@@ -0,0 +1,64 @@
+---
+name: second-brain-review
+description: >-
+ Produce a periodic review of a second-brain vault: what was added, which
+ topics are growing, what contradicts what, which questions are still open,
+ and what is worth reading next. Use this skill whenever the user asks for a
+ weekly or monthly review, asks what changed in their vault, what they have
+ been learning about lately, or what they should look at next, and when a
+ scheduled review task fires. Do NOT use for structural linting, for ingesting
+ sources, or for answering a specific factual question.
+---
+
+# Review the vault
+
+Capture systems fail at the point where nothing comes back out. A review is the
+loop that closes: it turns a week of ingestion into something the owner reads
+and acts on, and it is what makes the vault feel alive rather than archival.
+
+## Core rule
+
+A review reports on the vault, not on the agent's activity. Nobody needs to
+know how many tool calls ran; they need to know what they now know.
+
+## Workflow
+
+1. **Diff the period.** New and updated pages since the last review, from
+ `log.md` and frontmatter dates.
+2. **Find the clusters.** Which concepts gained the most links. That is where
+ the owner's attention actually went, which is often not where they think it
+ went.
+3. **Surface contradictions** recorded during the period and still unresolved.
+4. **List open questions** from concept and synthesis pages.
+5. **Find the neglected.** Pages linked often but thin, or gaps in `index.md`
+ that keep getting referenced.
+6. **Recommend three things to read or write next**, each tied to a specific
+ page.
+
+## Output format
+
+```
+## Week of <date>
+
+Added: <n> pages, <n> sources ingested
+
+### Where your attention went
+<two or three sentences on the clusters>
+
+### Unresolved
+<contradictions and open questions, each linked>
+
+### Thin spots
+<pages that are referenced more than they deserve given their content>
+
+### Next
+1. <specific action tied to a page>
+2.
+3.
+```
+
+## Calibration
+
+Reviews that list everything get skimmed and then ignored. Keep it under a
+page. Three recommendations, not ten. If a week produced nothing worth
+reporting, say that in one line instead of manufacturing insight.
diff --git a/second-brain-os/vault-template/CLAUDE.md b/second-brain-os/vault-template/CLAUDE.md
new file mode 100644
index 0000000..bb0e14f
--- /dev/null
+++ b/second-brain-os/vault-template/CLAUDE.md
@@ -0,0 +1,102 @@
+# This vault
+
+You maintain this vault. The owner drops raw material into `raw/` and asks
+questions. Everything in `wiki/` is yours to write and keep correct.
+
+The wiki is the primary artifact. `raw/` is an archive you can always re-read,
+but nobody reads it day to day. If something matters, it has to end up on a
+wiki page, in your own words, linked to everything related.
+
+## Folders
+
+```
+raw/ source material, never edited after it lands
+ assets/ images and attachments
+wiki/
+ sources/ one page per ingested item
+ entities/ people, organisations, products, tools
+ concepts/ ideas, methods, frameworks, arguments
+ synthesis/ comparisons, themes, open questions
+ index.md catalog of every page
+ log.md chronological record of what you did
+output/ reports, drafts, anything generated for use outside the vault
+```
+
+Never write to `raw/`. Never delete a wiki page without recording it in
+`log.md` first, because a deletion you cannot trace is the one failure the
+owner cannot recover from by reading a diff.
+
+## Page contracts
+
+Every page starts with frontmatter:
+
+```yaml
+---
+title: Canonical name
+type: source | entity | concept | synthesis
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+aliases: [other names this is known by]
+tags: [two or three, from the existing vocabulary]
+---
+```
+
+**Source pages** record what one item said. Include the URL or file path, the
+author, the date, and what it claims. Keep the claims attributable: this
+source says X, not X is true. End with links to every concept and entity it
+touches.
+
+**Entity pages** describe a person, company, product or tool: what it is, why
+it appears in this vault, and every source page that mentions it.
+
+**Concept pages** are the ones that compound. One idea per page, explained in
+plain language, with where it came from, what supports it, what argues against
+it, and what is still unclear. A concept page written well is readable by
+someone who has never seen the sources.
+
+**Synthesis pages** exist only when they say something no single source did:
+two sources disagree, three sources describe the same pattern, a question keeps
+recurring. Do not write a synthesis page just to have one.
+
+## Linking rules
+
+Link the first mention of any concept or entity on every page, using
+`[[wikilinks]]`. A page with no outbound links is a dead end and a page with no
+inbound links is invisible, so at ingest time connect the new page to what is
+already here before you finish.
+
+If the target page does not exist yet, still write the link, then create the
+page in the same run or add it to the gaps list in `index.md`. Links to pages
+that will never exist are worse than no links.
+
+Prefer a link over a restatement. If you find yourself explaining a concept
+that already has a page, link it and move on.
+
+## Handling disagreement
+
+When a new source contradicts an existing page, do not overwrite. Record both
+positions on the page, note which source says what and when, and mark the older
+claim as superseded if the new source is clearly better evidence. Silent
+overwrites destroy the one thing this vault has that a search engine does not:
+the history of what the owner believed and why.
+
+Never invent a fact to fill a gap. An explicit "not covered by any source here"
+is useful. A plausible sentence with no source behind it poisons everything
+downstream.
+
+## Voice
+
+Plain sentences. No marketing language, no hedging filler, no bullet lists
+where a paragraph is clearer. Write for the owner in six months, who will not
+remember the source at all.
+
+## Logging
+
+Append one line per operation to `log.md`:
+
+```
+2026-09-07 ingest raw/some-article.md -> 1 source, 3 concepts, 2 entities, 7 links
+```
+
+Keep `index.md` current in the same run. An index that lags behind is the
+first sign the system is drifting.
diff --git a/second-brain-os/vault-template/README.md b/second-brain-os/vault-template/README.md
new file mode 100644
index 0000000..341f5ac
--- /dev/null
+++ b/second-brain-os/vault-template/README.md
@@ -0,0 +1,16 @@
+# vault-template
+
+A starting vault. Copy this folder somewhere on your machine, open it in
+Obsidian as a vault, and start Claude Code inside it.
+
+```bash
+cp -r vault-template ~/second-brain
+cd ~/second-brain
+claude
+```
+
+`CLAUDE.md` is the instruction sheet the agent reads every session. Read it
+before your first run and edit the parts that do not match how you think. The
+default rules are deliberately strict about linking and about never
+overwriting a contradiction, because those two are what separate a vault that
+compounds from a folder of summaries.
diff --git a/second-brain-os/vault-template/output/README.md b/second-brain-os/vault-template/output/README.md
new file mode 100644
index 0000000..124fda9
--- /dev/null
+++ b/second-brain-os/vault-template/output/README.md
@@ -0,0 +1,6 @@
+# output/
+
+Generated artifacts: research reports, article drafts, exports.
+
+Anything here that turns out to be worth keeping should be ingested back into
+the wiki as a source, so your own writing becomes part of what the vault knows.
diff --git a/second-brain-os/vault-template/projects/README.md b/second-brain-os/vault-template/projects/README.md
new file mode 100644
index 0000000..e0d20aa
--- /dev/null
+++ b/second-brain-os/vault-template/projects/README.md
@@ -0,0 +1,20 @@
+# projects/
+
+One folder per project. Each holds its own `CLAUDE.md` and the four-stage
+pipeline:
+
+```
+project-name/
+ CLAUDE.md what this project is, its one goal, the agent's role
+ Inputs/ ideas, briefs, source material for this project
+ Process/ work in progress
+ Outputs/ finished work
+ Feedback/ results, metrics, what actually happened
+```
+
+`Feedback/` is the folder people skip and the one that makes the system
+improve. Without it the agent has no idea whether last month's output worked.
+
+Open a project as its own vault when you are working in it, so the agent sees
+one goal instead of your whole life. See
+[project scoping](../../docs/02-setup/project-scoping.md).
diff --git a/second-brain-os/vault-template/projects/example-project/CLAUDE.md b/second-brain-os/vault-template/projects/example-project/CLAUDE.md
new file mode 100644
index 0000000..70bfef4
--- /dev/null
+++ b/second-brain-os/vault-template/projects/example-project/CLAUDE.md
@@ -0,0 +1,27 @@
+# Project: <name>
+
+## What this is
+
+One paragraph. What this project produces and for whom.
+
+## The one goal
+
+A single measurable outcome with a date. If there are three goals, this is
+three projects.
+
+## Your role
+
+What the agent does here specifically: drafts, reviews, analyses, researches.
+Name what it should not do as well, because scope creep inside a project is
+what turns a focused assistant back into a general chat window.
+
+## Working rules
+
+- Where finished work goes
+- What format outputs take
+- What to check before calling something done
+
+## Current state
+
+Updated as the project moves. What is done, what is in progress, what is
+blocked.
diff --git a/second-brain-os/vault-template/projects/example-project/Feedback/.gitkeep b/second-brain-os/vault-template/projects/example-project/Feedback/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/second-brain-os/vault-template/projects/example-project/Inputs/.gitkeep b/second-brain-os/vault-template/projects/example-project/Inputs/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/second-brain-os/vault-template/projects/example-project/Outputs/.gitkeep b/second-brain-os/vault-template/projects/example-project/Outputs/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/second-brain-os/vault-template/projects/example-project/Process/.gitkeep b/second-brain-os/vault-template/projects/example-project/Process/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/second-brain-os/vault-template/raw/README.md b/second-brain-os/vault-template/raw/README.md
new file mode 100644
index 0000000..5a8fcb2
--- /dev/null
+++ b/second-brain-os/vault-template/raw/README.md
@@ -0,0 +1,10 @@
+# raw/
+
+Drop source material here: clipped articles, transcripts, PDFs, exported chats,
+voice notes, anything.
+
+Nothing in this folder is edited after it lands. The agent reads from here and
+writes to `wiki/`. If a file is wrong, replace it and re-ingest rather than
+patching it in place, so the source stays a faithful record of what you saved.
+
+`assets/` holds images and attachments referenced by raw files.
diff --git a/second-brain-os/vault-template/raw/assets/.gitkeep b/second-brain-os/vault-template/raw/assets/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/second-brain-os/vault-template/templates/concept.md b/second-brain-os/vault-template/templates/concept.md
new file mode 100644
index 0000000..5e73a55
--- /dev/null
+++ b/second-brain-os/vault-template/templates/concept.md
@@ -0,0 +1,22 @@
+---
+title:
+type: concept
+created:
+updated:
+aliases: []
+tags: []
+---
+
+# {{title}}
+
+## In one paragraph
+
+## Where it came from
+
+## What supports it
+
+## What argues against it
+
+## Open questions
+
+## Related
diff --git a/second-brain-os/vault-template/templates/entity.md b/second-brain-os/vault-template/templates/entity.md
new file mode 100644
index 0000000..f524c46
--- /dev/null
+++ b/second-brain-os/vault-template/templates/entity.md
@@ -0,0 +1,17 @@
+---
+title:
+type: entity
+kind: person | org | product | tool
+created:
+updated:
+aliases: []
+tags: []
+---
+
+# {{title}}
+
+## What it is
+
+## Why it appears here
+
+## Mentioned in
diff --git a/second-brain-os/vault-template/templates/source.md b/second-brain-os/vault-template/templates/source.md
new file mode 100644
index 0000000..90c61be
--- /dev/null
+++ b/second-brain-os/vault-template/templates/source.md
@@ -0,0 +1,21 @@
+---
+title:
+type: source
+created:
+updated:
+url:
+author:
+published:
+aliases: []
+tags: []
+---
+
+# {{title}}
+
+## What it is
+
+## Claims
+
+## Why it matters here
+
+## Links
diff --git a/second-brain-os/vault-template/templates/synthesis.md b/second-brain-os/vault-template/templates/synthesis.md
new file mode 100644
index 0000000..a9b3534
--- /dev/null
+++ b/second-brain-os/vault-template/templates/synthesis.md
@@ -0,0 +1,20 @@
+---
+title:
+type: synthesis
+created:
+updated:
+aliases: []
+tags: []
+---
+
+# {{title}}
+
+## The question
+
+## What the sources say
+
+## Where they disagree
+
+## Current position
+
+## What would change it
diff --git a/second-brain-os/vault-template/wiki/concepts/.gitkeep b/second-brain-os/vault-template/wiki/concepts/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/second-brain-os/vault-template/wiki/entities/.gitkeep b/second-brain-os/vault-template/wiki/entities/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/second-brain-os/vault-template/wiki/index.md b/second-brain-os/vault-template/wiki/index.md
new file mode 100644
index 0000000..e96fed6
--- /dev/null
+++ b/second-brain-os/vault-template/wiki/index.md
@@ -0,0 +1,31 @@
+---
+title: Index
+type: index
+updated: 1970-01-01
+---
+
+# Index
+
+Catalog of every page in this vault. The agent keeps this current.
+
+## Concepts
+
+_Nothing yet._
+
+## Entities
+
+_Nothing yet._
+
+## Synthesis
+
+_Nothing yet._
+
+## Sources
+
+_Nothing yet._
+
+## Gaps
+
+Pages that are linked but do not exist yet.
+
+_Nothing yet._
diff --git a/second-brain-os/vault-template/wiki/log.md b/second-brain-os/vault-template/wiki/log.md
new file mode 100644
index 0000000..6e39294
--- /dev/null
+++ b/second-brain-os/vault-template/wiki/log.md
@@ -0,0 +1,12 @@
+---
+title: Log
+type: log
+---
+
+# Log
+
+One line per operation, newest at the bottom. Format:
+
+```
+DATE OPERATION target -> result
+```
diff --git a/second-brain-os/vault-template/wiki/sources/.gitkeep b/second-brain-os/vault-template/wiki/sources/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/second-brain-os/vault-template/wiki/synthesis/.gitkeep b/second-brain-os/vault-template/wiki/synthesis/.gitkeep
new file mode 100644
index 0000000..e69de29