# 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`.