docs: refresh CLAUDE.md spec + add README

CLAUDE.md drift fixes (25 commits since last touch):
- "homelab MCP server" → vault-mcp (renamed homelab-mcp-server →
  herbydev-mcp → vault-mcp)
- Project-status vocabulary was `active|paused|completed|archived`
  but vault-mcp/vault_mcp/core/schema.py is canonical and uses
  idea|planned|on_deck|active|blocked|completed|killed. Replaced
  the inline list with a status table matching the schema and a
  pointer to schema.py as the authoritative source
- Session-note frontmatter: noted that `session-notes` (plural) is
  canonical; a handful of legacy files use `session-note` singular
- Spec layer: added migrate.py to the inventory (one-shot)
- NOTIFY-fires-on-status-change call-out for the n8n/Trello path

README (new): vault overview, where-to-start file map, two-layer
structure, who-writes-what table, git commit-prefix protocol, quick
operational do-nots, repo origin.

Working tree retains the untracked Source file
(Sources/Dev/2026-05-16-vault-integration-test-multi.md) — verified
pre-commit; intentionally not part of this commit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -2,7 +2,15 @@
 
 This file is the spec for this vault. Any agent operating on this vault
 reads this file first. Procedures (compile, lint, migration) live in the
-`wiki-maintenance` skill on herbydev — this file is the spec they reference.
+`wiki-maintenance` skill — this file is the spec they reference.
+
+> **Canonical schema source.** The `vault-mcp` server's
+> `vault_mcp/core/schema.py` (returned via the `vault:get_schema` MCP
+> tool) is the **authoritative** vocabulary for note types, statuses,
+> domains, and folder paths. If this CLAUDE.md and that schema
+> disagree, the schema wins — update this file. The
+> vocabulary listed below mirrors `schema.py` as of the last touch;
+> bump in sync.
 
 ## Purpose
 
@@ -16,7 +24,10 @@ two-layer structure.
 ### Layer 1: Sources
 
 Raw project plans and session notes. Written by Travis, Jenny, and LLM
-agents via the homelab MCP server. These are the input to the compile loop.
+agents via the `vault-mcp` server (formerly called `homelab-mcp-server`
+/ `herbydev-mcp`). New writes flow through `vault:create_artifact` —
+which dual-writes a Postgres row in `petalbrain.wiki` and a markdown
+file here. These are the input to the compile loop.
 
 Location: `Sources/<Domain>/`
 
@@ -43,6 +54,9 @@ At the vault root:
 - `CLAUDE.md` — this file
 - `index.md` — navigation front door
 - `log.md` — append-only compile audit trail
+- `migrate.py` — one-shot migration script from the prior
+  pbs-projects / homelab-projects layout (run once on
+  initial vault creation; not part of the steady-state)
 
 ## Four Ownership Domains
 
@@ -66,7 +80,7 @@ shaped, pick one domain and tag with the others.
 ---
 project: <slug>
 type: project-plan
-status: active          # active | paused | completed | archived
+status: <status>        # see canonical statuses below
 path: Sources/<Domain>
 tags:
   - <tag>
@@ -75,6 +89,24 @@ updated: YYYY-MM-DD
 ---
 ```
 
+**Canonical statuses** (from `vault-mcp/vault_mcp/core/schema.py`):
+
+| Status      | Meaning                                                 |
+|-------------|---------------------------------------------------------|
+| `idea`      | Captured, not yet committed to                          |
+| `planned`   | Committed but not started                               |
+| `on_deck`   | Next up — default for newly-created projects            |
+| `active`    | Currently in progress                                   |
+| `blocked`   | Waiting on something external                           |
+| `completed` | Finished — no further work expected                     |
+| `killed`    | Abandoned (vs. `completed`, which implies success)      |
+
+`vault-mcp` fires a Postgres `NOTIFY` on project-status changes that
+n8n turns into Trello card moves — so changing a status via
+`vault:update_artifact` propagates downstream. Hand-editing the
+frontmatter does **not** fire the NOTIFY; use the MCP tool when
+possible.
+
 **Required sections:**
 - `## Goal` — one paragraph, what this project achieves
 - `## Locked Decisions` — bulleted, dated as needed
@@ -89,8 +121,9 @@ updated: YYYY-MM-DD
 **Frontmatter:**
 ```yaml
 ---
-project: <slug>
+project: <slug>          # parent project's slug — required
-type: session-notes
+type: session-notes      # plural form is canonical (some legacy files
+                         # have `session-note` singular; lint should fix)
 status: active
 path: Sources/<Domain>
 tags:

README.md

@@ -0,0 +1,87 @@
+# wiki-vault
+
+Travis's personal knowledge vault — project plans, session notes, and
+a compiled LLM-maintained wiki. Two layers, four ownership domains,
+versioned in git, indexed in `petalbrain` Postgres, and embedded for
+semantic search via Ollama.
+
+## Where to start
+
+| File         | Purpose                                                  |
+|--------------|----------------------------------------------------------|
+| `CLAUDE.md`  | **The spec.** Vault structure, page types, frontmatter, status vocabulary, git protocol. Agents read this first. |
+| `index.md`   | Navigation front door — links into Sources and Wiki indexes. |
+| `log.md`     | Append-only audit log of compile / lint / migration runs. |
+
+If you're an agent acting on this vault, read `CLAUDE.md`. If you're a
+human browsing, start at `index.md`.
+
+## Two-layer structure
+
+```
+wiki-vault/
+├── Sources/           # Raw — input to the compile loop
+│   ├── Dev/
+│   ├── Venture/
+│   ├── Homelab/
+│   └── Reference/
+└── Wiki/              # Compiled output — generated by wiki-maintenance
+    ├── Dev/
+    ├── Venture/
+    ├── Homelab/
+    └── Reference/
+```
+
+- **Sources** = raw project plans + session notes, written by Travis,
+  Jenny, and LLM agents through `vault-mcp`.
+- **Wiki** = compiled entity pages, topic landings, and synthesis —
+  produced and maintained by the `wiki-maintenance` skill. Never
+  written to directly outside the compile loop.
+
+## How it gets written
+
+| Path                                | Who writes it                                                |
+|-------------------------------------|--------------------------------------------------------------|
+| `Sources/<Domain>/<slug>.md`        | `vault-mcp:create_artifact` (project plans)                  |
+| `Sources/<Domain>/YYYY-MM-DD-*.md`  | `vault-mcp:create_artifact` (session notes)                  |
+| `Wiki/...`                          | `wiki-maintenance` skill, during compile runs only           |
+| `index.md`, `Sources/index.md`, `Wiki/index.md`, `<Domain>/index.md` | Compile loop |
+| `log.md`                            | Compile / lint / migration runs (append-only)                |
+
+`vault-mcp` dual-writes: Postgres row in `petalbrain.wiki` for index +
+embeddings, markdown file here for canonical content. The repo is
+configured for HTTPS push to gitea via a PAT-backed credential helper
+— see `vault-mcp/CLAUDE.md` for the mechanics.
+
+## Git protocol
+
+Every mutation lands as a tracked commit with a typed prefix:
+
+| Prefix             | Source                                          |
+|--------------------|-------------------------------------------------|
+| `mcp: <kind> — …`  | `vault-mcp` writes (project-plan or session-notes) |
+| `pre-compile: …`   | Snapshot before a compile run touches anything  |
+| `compile: …`       | Compile run body — pages touched/created/promoted |
+| `lint: …`          | Auto-fixes from the linter                      |
+
+Two-commit pattern on compile runs (`pre-compile` then `compile`) so
+the diff of the run is reviewable in isolation.
+
+## Quick operational notes
+
+- **Don't edit `Wiki/` by hand.** The compile loop owns it. Edits get
+  overwritten on the next run.
+- **Don't add tags silently.** New tags need explicit user approval
+  or 3+ pages of usage.
+- **Don't delete pages without confirmation.** The compile loop has
+  archive semantics — work through it, not around it.
+- **Status changes flow through `vault-mcp:update_artifact`** when
+  possible — that's what fires the Postgres `NOTIFY` that n8n turns
+  into Trello card moves. Hand-edits to frontmatter skip the
+  automation.
+
+## Repo
+
+- Origin: gitea `petal-power/wiki-vault` (HTTPS push via `vault-mcp`'s
+  PAT credential helper).
+- This vault is mounted into the `vault-mcp` container at `/vault`.