wiki-context/CLAUDE.md

CLAUDE.md — HomeLab Wiki Vault Spec (draft, superseded)

Important context for agents: this is the wiki-context repo, which is the planning workspace for the wiki-construct project, not a deployed vault. The vault structure described below is an early design draft that didn't survive contact with implementation — when the wiki was actually built, the structure became a two-layer Sources/ + Wiki/ split, and the Content domain was renamed to Venture.

Canonical implementation spec: wiki-vault/CLAUDE.md. Read that one when you're operating on the live vault.

Why this draft is kept: as wiki-construct-context.md explains, the planning conversation captured why decisions were made. Mutating this CLAUDE.md to match the live spec would erase that design history. Leave it as a frozen record of the design state at 2026-05-04; tracker is the live wiki-vault/CLAUDE.md.

The rest of this file is the original draft, unmodified below this point.

---

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:

---
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:

---
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:

---
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:

---
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):

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