wiki-context/CLAUDE.md

# CLAUDE.md — HomeLab Wiki Vault Spec

This file is the spec for this Obsidian vault. Any agent operating
on this vault reads this file first to understand the structure,
the page types, and the rules. Procedures (compile, lint,
migration) live in the `wiki-maintenance` skill on herbydev — this
file is the spec they reference.

## Purpose

This vault is Travis's personal knowledge wiki. It holds project
plans, session notes, entity pages for recurring people/systems/
tools, topic landing pages, and synthesis pages.

The vault is organized for **human browsing in Obsidian**, not for
autonomous agent consumption. Agents update the wiki on explicit
human invocation. Agents reference the wiki only when explicitly
pointed at a file.

## Vault structure

Flat structure under four ownership domains. No `Projects/`,
`Sessions/`, or `Reference/` subfolders within domains.

```
HomeLab/
├── CLAUDE.md          # this file
├── index.md           # top-level catalog
├── log.md             # append-only event log
│
├── Dev/
│   ├── index.md       # Dev domain landing
│   └── *.md           # all Dev pages, flat
│
├── Content/
│   ├── index.md       # Content domain landing
│   └── *.md           # all Content pages, flat
│
├── Homelab/
│   ├── index.md       # Homelab domain landing
│   └── *.md           # all Homelab pages, flat
│
└── Reference/
    ├── index.md       # cross-domain entity landing
    └── *.md           # cross-domain entity pages, flat
```

A fourth ownership domain may be added later (likely `Personal`).
Reserved space; not active yet.

## Folder ownership rules

- **Dev** — coding projects, dev environment, language explorations,
  AI/ML experiments, DeFi research, tooling
- **Content** — PBS planning, recipes, brand assets, content
  campaigns, anything Jenny might eventually touch
- **Homelab** — infrastructure, networking, hardware, sysadmin,
  storage, deployments
- **Reference** — cross-domain entities (Lovebug, OB1, herbydev,
  Jenny, Sunnie, KeePassXC, Tailscale, etc.) — things that span
  multiple domains and don't sit cleanly in one

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

## Page types

Five types. No others without explicit user request.

### Project page

A project page is the primary unit. One per active or recently
active project. The 30-second orientation document.

**Frontmatter:**
```yaml
---
project: <slug>          # unique slug, lowercase-dashes, matches filename
type: project
status: active           # active | paused | completed | archived
path: <domain>           # Dev | Content | Homelab | Reference
tags:
  - <tag>
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
```

**Required sections:**

- **Current state** — 2-4 sentences, what's happening right now
- **Decisions locked** — bulleted, dated as needed
- **Open questions** — what's stuck or deferred
- **Sessions** — backlinked list of related session notes
- **Related** — wikilinks to entities, topics, other projects

**Filename:** `<slug>.md` (e.g., `ob1-deployment.md`,
`wiki-construct.md`)

### Session note

What happened in a working session. Top-level artifact, not a
child of any project. May reference a project via wikilinks but
does not live inside it.

**Frontmatter:**
```yaml
---
project: <slug>          # if related to a project; otherwise omit
type: session-notes
status: active           # usually active; occasionally archived
path: <domain>
tags:
  - <tag>
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
```

**Required sections:**

- **Outcomes** — what came out of the session
- **Topics covered** — what was discussed
- **Key learnings** — what was learned, briefly
- **Follow-ons** — checkbox list of follow-up tasks, if any

**Filename:** `YYYY-MM-DD-<slug>.md` (date prefix for chronological
sort)

### Entity page

A recurring character in Travis's world. People, systems, tools,
hardware, services that show up across multiple projects or
sessions and benefit from a stable home page.

**Frontmatter:**
```yaml
---
type: entity
path: <domain>           # or Reference for cross-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` (e.g., `lovebug.md`, `herbydev.md`,
`ob1.md`)

### Topic landing / index

Domain-level catalog and prose overview. One per ownership
domain (`<domain>/index.md`). Plus the top-level `index.md` that
spans all domains.

**Frontmatter:**
```yaml
---
type: topic-landing
path: <domain>
tags:
  - landing
updated: YYYY-MM-DD
---
```

**Required sections:**

- **Current state** — agent-written prose, 3-5 sentences, what's
  going on across this domain right now
- **Active projects** — list of projects with `status: active`,
  one-line current state for each, link to project page
- **Recent sessions** — most recent session notes (last ~10 or
  last 30 days, whichever is shorter)
- **Key entities** — entity pages relevant to this domain
- **Synthesis pages** — list of any synthesis pages scoped to
  this domain
- **Completed projects** — collapsed or smaller section,
  `status: completed` or `archived`

The agent maintains these on every compile pass. They are
generated from frontmatter queries plus a short prose
"current state" the agent updates.

### Synthesis page

Cross-cutting analysis. Pulls from multiple existing pages and
produces a synthesized view. Generated by the agent during
compile when it identifies a worth-synthesizing pattern.

**Frontmatter (sources field is required):**
```yaml
---
type: synthesis
path: <domain>           # or Reference for cross-domain
tags:
  - <tag>
sources:
  - "[[<wikilink-to-source-1>]]"
  - "[[<wikilink-to-source-2>]]"
  - "[[<wikilink-to-source-3>]]"
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
```

**Required sections:**

- **Synthesis** — the cross-cutting analysis itself
- **Sources** — narrative discussion of what each source
  contributed; each claim should be traceable to one or more
  sources
- **Open questions** — gaps or contradictions surfaced during
  synthesis

**Filename:** `synthesis-<topic-slug>.md` (e.g.,
`synthesis-memory-architecture.md`)

**Synthesis page rules:**

- Sources are required; no synthesis page without them
- Every substantive claim should trace to a source via prose
  attribution
- Claims that are agent inference (not directly in any source)
  must be flagged as such in the prose
- Synthesis pages are the highest-risk page type for lossy
  compression and get extra lint scrutiny
- The agent generates synthesis pages during compile when a
  pattern emerges; do not generate one per compile run by
  default

## Tag conventions

Tags answer "what is this about." Wikilinks answer "what
specific thing does this involve." Prefer wikilinks for
specific named things; use tags for topical categories.

### Starter tag list (curated)

**Topics:**
`claude-code`, `mcp`, `dispatch`, `tailscale`, `proxmox`,
`docker`, `ansible`, `authelia`, `traefik`, `obsidian`, `n8n`,
`pgvector`, `embeddings`, `terminal`, `automation`, `git`

**Lifecycle (also valid as `status:` frontmatter values):**
`active`, `paused`, `completed`, `archived`

**Project / system handles (rare — prefer wikilinks for these):**
`ob1`, `lovebug`, `sunnie`, `wiki`, `pbs`

### Adding a new tag

A new tag requires:

1. The user explicitly asks for it, OR
2. The agent encounters a recurring topical category that
   appears in 3+ pages and would benefit from cross-referencing,
   AND raises it for confirmation in the compile session summary

Do not add tags silently. Do not let the tag list grow
unconstrained.

## Entity promotion rules

A topic earns its own entity page when:

- It's referenced by name in 2+ projects, OR
- It's referenced in 3+ session notes, OR
- It's a piece of infrastructure (host, service, tool) that
  Travis uses recurringly

Below this threshold, references stay as inline text or tags.

When promoting a topic to an entity page, the agent:

1. Creates the entity page with the standard sections
2. Updates referencing pages to use wikilinks instead of plain
   text
3. Notes the promotion in the compile session summary

## Git protocol

The vault is a git repo. Compile runs use a two-commit pattern.

### Pre-compile commit

Before any compile-run writes:

```
pre-compile: <human-readable reason>
```

This captures the vault state before the agent touches anything.
If the compile run produces unwanted output, `git reset --hard`
to this commit to roll back.

### Post-compile commit

After all compile-run writes:

```
compile: <one-line summary>

Pages touched: <list>
Pages created: <list>
Entities promoted: <list>
Synthesis pages written: <list>
Contradictions flagged: <list>
Tags proposed: <list>
```

The body is the audit trail. `git log --oneline` shows the
compile history; `git show <commit>` shows what changed and why.

### Other commits

Lint runs commit as `lint: <summary>` if they make automatic
fixes (broken wikilinks, missing frontmatter fields). Manual
edits by Travis commit with whatever message Travis writes.

## What the agent does and does not do

**Agent does:**

- Compile runs when invoked
- Lint runs when invoked
- One-time migration when invoked
- Generates the five page types per spec
- Maintains topic landings and indexes
- Promotes entities when threshold is met (with notification)
- Writes synthesis pages when a worth-synthesizing pattern
  emerges (with full source provenance)
- Two-commit git protocol on every compile run
- Reports findings in session summary

**Agent does not:**

- Run autonomously. Every operation is human-initiated.
- Restructure folders without explicit confirmation
- Delete pages without explicit confirmation
- Add new tags silently (proposes them in the compile summary)
- Generate concept pages or comparison pages (not in spec)
- Write synthesis pages on every compile run by default
- Modify pages outside the wiki (no edits to source code, no
  changes to OB1, no changes outside the vault path)
- Skip the git protocol

## Lint scope

When invoked for a lint pass, the agent checks:

- **Broken wikilinks** — links to pages that don't exist
- **Orphan pages** — pages with no inbound wikilinks (may be
  legitimate; flag for review, do not auto-delete)
- **Missing required frontmatter fields** — per page type spec
- **Inconsistent frontmatter values** — `status:` not in valid
  set, `path:` not matching folder, `type:` not in valid set
- **Stale `updated:` dates** — pages whose content has changed
  but `updated:` is older than the most recent edit
- **Synthesis page integrity** — sources still exist, sources
  still say what the synthesis claims they say, no source has
  been substantially edited since synthesis was written
- **Cross-page contradictions** — the same fact stated
  differently across pages
- **Index/landing freshness** — landing pages reflect current
  vault state

Lint reports findings. It auto-fixes only mechanical issues
(missing dates, broken wikilinks where the target is obvious).
Anything substantive goes to the user for review.

## Operational invariants

- The vault is the source of truth for itself. The agent reads
  the vault, computes changes, writes the vault.
- `log.md` is append-only. Never edit existing entries.
- `index.md` files are agent-maintained. Travis can edit them,
  but the agent will reconcile on the next compile.
- Project pages, session notes, and entity pages may be edited
  by either Travis or the agent. The most recent `updated:` date
  wins for "current state" sections; structural changes by the
  agent should preserve any user-added content unless explicitly
  instructed otherwise.
- Synthesis pages are agent-authored but human-reviewed. Travis
  may edit them; the agent should respect those edits and not
  silently overwrite.

## Versioning

This file evolves with the vault. Changes to CLAUDE.md commit
with message `spec: <what changed>`. Major spec changes (new
page type, new folder, new operation) warrant a session note
documenting the rationale.