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>
This commit is contained in:
Travis Herbranson
parent
c634612ad2
commit
570e96fff8
43
CLAUDE.md
43
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>
|
||||
type: session-notes
|
||||
project: <slug> # 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/<Domain>
|
||||
tags:
|
||||
|
||||
87
README.md
Normal file
87
README.md
Normal file
@ -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`.
|
||||
Loading…
Reference in New Issue
Block a user