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:**
```yaml
---
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:**
```yaml
---
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:**
```yaml
---
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:**
```yaml
---
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:**
```yaml
---
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