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 on herbydev — this file is the spec they reference.

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 homelab MCP server. 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

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: active          # active | paused | completed | archived
path: Sources/<Domain>
tags:
  - <tag>
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

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>
type: session-notes
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