570e96fff8
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>
88 lines
3.8 KiB
Markdown
88 lines
3.8 KiB
Markdown
# 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`.
|