# 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`](../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:** ```yaml --- project: # unique slug, lowercase-dashes, matches filename type: project status: active # active | paused | completed | archived path: # Dev | Content | Homelab | Reference tags: - 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:** `.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: # if related to a project; otherwise omit type: session-notes status: active # usually active; occasionally archived path: tags: - 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-.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: # or Reference for cross-domain tags: - 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:** `.md` (e.g., `lovebug.md`, `herbydev.md`, `ob1.md`) ### Topic landing / index Domain-level catalog and prose overview. One per ownership domain (`/index.md`). Plus the top-level `index.md` that spans all domains. **Frontmatter:** ```yaml --- type: topic-landing path: 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: # or Reference for cross-domain tags: - sources: - "[[]]" - "[[]]" - "[[]]" 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-.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: ``` 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: Pages touched: Pages created: Entities promoted: Synthesis pages written: Contradictions flagged: Tags proposed: ``` The body is the audit trail. `git log --oneline` shows the compile history; `git show ` shows what changed and why. ### Other commits Lint runs commit as `lint: ` 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: `. Major spec changes (new page type, new folder, new operation) warrant a session note documenting the rationale.