diff --git a/CLAUDE.md b/CLAUDE.md index feb99f4..eeccd33 100644 --- a/CLAUDE.md +++ b/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//` @@ -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: type: project-plan -status: active # active | paused | completed | archived +status: # see canonical statuses below path: Sources/ tags: - @@ -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: -type: session-notes +project: # parent project's slug — required +type: session-notes # plural form is canonical (some legacy files + # have `session-note` singular; lint should fix) status: active path: Sources/ tags: diff --git a/README.md b/README.md new file mode 100644 index 0000000..42ad738 --- /dev/null +++ b/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//.md` | `vault-mcp:create_artifact` (project plans) | +| `Sources//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`, `/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: — …` | `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`.