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