petal-power/wiki-vault
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
27 Commits 1 Branch 0 Tags 1,021 KiB
Python 100%
570e96fff8
Go to file
Travis Herbranson 570e96fff8 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>
2026-05-20 07:57:29 -04:00
Sources mcp: project-plan — PBS Hub — Vector Search 2026-05-19 22:04:59 +00:00
Wiki compile: first compile — 17 entities, 2 synthesis, all indexes rebuilt 2026-05-08 18:15:31 -04:00
.gitignore migration: copy 62 notes from pbs-projects and homelab-projects 2026-05-08 17:21:13 -04:00
CLAUDE.md docs: refresh CLAUDE.md spec + add README 2026-05-20 07:57:29 -04:00
index.md compile: first compile — 17 entities, 2 synthesis, all indexes rebuilt 2026-05-08 18:15:31 -04:00
log.md compile: first compile — 17 entities, 2 synthesis, all indexes rebuilt 2026-05-08 18:15:31 -04:00
migrate.py migration: copy 62 notes from pbs-projects and homelab-projects 2026-05-08 17:21:13 -04:00
README.md docs: refresh CLAUDE.md spec + add README 2026-05-20 07:57:29 -04:00

README.md

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.