106 lines
4.8 KiB
Markdown
106 lines
4.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`.
|
|
|
|
## Status (as of 2026-05-24)
|
|
|
|
- **88 source files** across Dev / Venture / Homelab; **26 compiled Wiki
|
|
pages** (22 entities, 4 domain landings) + 2 synthesis pages.
|
|
- **First steady-state compile** since launch ran 2026-05-24, clearing a
|
|
34-source backlog (indexes rebuilt, 5 entities refreshed, the
|
|
`ai-memory-architecture` synthesis updated for the `petalbrain`
|
|
consolidation). The first **lint pass** ran the same night (broken
|
|
wikilinks + `session-note→session-notes` fixes).
|
|
- **5 entities promoted** that session: [[Wiki/Reference/trellis]],
|
|
[[Wiki/Reference/vault-mcp]], [[Wiki/Homelab/petalbrain]],
|
|
[[Wiki/Homelab/knot-dns]], [[Wiki/Dev/herbyeos]].
|
|
- **Compile cadence (planned, not yet live):** an n8n workflow nudges via
|
|
Google Chat when ≥10 new sources accrue or ≥7 days pass since the last
|
|
compile. Depends on a `wiki.compile_runs` table and a one-line addition
|
|
to the compile procedure's Step 8. See
|
|
`docker/n8n/workflows/wiki-compile-nudge.json`.
|
|
|
|
## 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`.
|