wiki-vault/CLAUDE.md

CLAUDE.md — Wiki Vault Spec

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 — 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

This vault holds Travis's project plans, session notes, and a compiled LLM-maintained wiki. It consolidates what was previously split across pbs-projects and homelab-projects into a single repository with a two-layer structure.

Two-Layer Structure

Layer 1: Sources

Raw project plans and session notes. Written by Travis, Jenny, and LLM 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>/

Page types in Sources:

• project-plan — what a project is, decisions, phases, tasks
• session-notes — what happened in a working session

Layer 2: Wiki

Compiled output. Generated and maintained by the wiki-maintenance compile skill. Never written to directly by the MCP server or agents outside the compile loop.

Location: Wiki/<Domain>/

Page types in Wiki:

• entity — recurring people, systems, tools with stable home pages
• topic-landing — domain-level catalog and prose overview (index.md)
• synthesis — cross-cutting analysis with source provenance

Spec Layer

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

Domain	Scope
Dev	Coding projects, dev environment, AI/ML, DeFi, tooling
Venture	PBS business + content: recipes, video, brand, membership, marketing, revenue
Homelab	Infrastructure, networking, hardware, sysadmin, deployments
Reference	Cross-domain entities that span multiple domains

Cross-domain content: prefer the domain where primary ownership lives. If genuinely cross-cutting and entity-shaped, put in Reference. If project- shaped, pick one domain and tag with the others.

Page Types

Project page (Sources only)

Frontmatter:

---
project: <slug>
type: project-plan
status: <status>        # see canonical statuses below
path: Sources/<Domain>
tags:
  - <tag>
created: YYYY-MM-DD
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
• ## Open Items — what's unresolved
• ## Phases or ## Tasks — work breakdown
• ## Notes — learnings, context, references

Filename: <slug>.md

Session note (Sources only)

Frontmatter:

---
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:
  - <tag>
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

Required sections:

• ## Outcome — what came out of the session
• ## Topics Covered — what was discussed
• ## Key Learnings — what was learned
• ## Follow-ons — checkbox list of next steps

Filename: YYYY-MM-DD-<slug>.md

Entity page (Wiki only)

Frontmatter:

---
type: entity
path: Wiki/<Domain>
tags:
  - <tag>
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

Required sections:

• What it is — one paragraph
• Current state — present-tense status
• Where it lives — host, repo, URL, path as applicable
• Related projects — wikilinks
• History — terse, dated notes of significant events

Filename: <entity-slug>.md

Topic landing (both layers)

Index pages at <layer>/<Domain>/index.md and at Sources/index.md, Wiki/index.md, and the root index.md.

Frontmatter:

---
type: topic-landing
path: <layer>/<Domain>
tags:
  - landing
updated: YYYY-MM-DD
---

Required sections (Sources landing):

• Active Projects — list with one-line status, links
• Recent Sessions — last 10 or last 30 days
• Completed Projects — collapsed section

Required sections (Wiki landing):

• Entities — list with one-line descriptions
• Synthesis Pages — list with topics covered

Synthesis page (Wiki only)

Frontmatter:

---
type: synthesis
path: Wiki/<Domain>
tags:
  - <tag>
sources:
  - "[[<wikilink-to-source-1>]]"
  - "[[<wikilink-to-source-2>]]"
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

Required sections:

• Synthesis — the cross-cutting analysis
• Sources — narrative discussion of what each source contributed
• Open questions — gaps or contradictions surfaced

Tag Conventions

Tags answer "what is this about." Wikilinks answer "what specific thing."

Topics: claude-code, mcp, dispatch, tailscale, proxmox, docker, ansible, authentik, traefik, obsidian, n8n, pgvector, embeddings, terminal, automation, git, cloudflare, python, go, fish, starship

Handles: ob1, lovebug, sunnie, wiki, pbs

New tags require explicit user approval or 3+ page usage.

Entity Promotion Rules

A topic earns an entity page when referenced in 2+ projects or 3+ sessions. Below threshold, references stay as inline text or tags.

Git Protocol

Two-commit pattern per compile run:

• pre-compile: <reason> — captures vault state before writes
• compile: <summary> — body includes pages touched/created/promoted

Lint: lint: <summary> if auto-fixes were made.

MCP writes: mcp: <note-type> — <title>

Navigation

All browsing happens through index pages. The root index.md is the front door, linking into Sources and Wiki indexes, which link into domain indexes. No one should need to browse the file tree.

The compile loop maintains all index pages automatically.

What Agents Do and Don't Do

Do:

• Write project plans and session notes to Sources/ via MCP
• Run compile/lint via the wiki-maintenance skill when invoked
• Maintain indexes and entity pages during compile runs

Don't:

• Write directly to Wiki/ outside the compile loop
• Delete pages without explicit confirmation
• Add tags silently
• Run autonomously — every operation is human-initiated
• Modify files outside the vault