wiki-context/wiki-construct-project-plan.md

Subject: [n8n] -t Tech/Projects -p wiki-construct

---
project: wiki-construct
type: project-plan
status: active
path: Tech/Projects
tags:
  - homelab
  - obsidian
  - knowledge-management
  - claude-code
  - skill
  - llm-wiki
created: 2026-05-04
updated: 2026-05-04
---

# Wiki Construct — Project Plan

## Concept

Build the personal LLM-maintained wiki construct on the homelab,
based on the Karpathy LLM Wiki pattern. Scoped to be the visible
face of personal knowledge — organized synthesis I can browse and
reference in Obsidian, not a memory layer for agents. Lovebug and
other agents may reference the wiki when explicitly pointed at it,
but the wiki is not designed for autonomous agent consumption.

The wiki is one of two complementary memory systems being built:

- **Wiki** — my curated knowledge journey, slow, deliberate,
  organized for human browsing.
- **OB1** — Lovebug's working memory, fast, voluminous, organized
  for semantic recall via MCP.

The two systems are parallel, not unified. They share no
infrastructure beyond eventually feeding the same context-assembler
in some Phase 2 future.

## Architecture

Three layers, per the Karpathy pattern:

1. **Raw sources** — existing markdown files captured via the
   email-to-vault pipeline. Immutable.
2. **Wiki** — LLM-maintained markdown files in the Obsidian vault.
   Five page types, flat structure under four ownership domains.
3. **Spec + procedures** — `CLAUDE.md` at the vault root holds the
   spec; a `wiki-maintenance` skill on herbydev holds the procedures
   (compile, lint, migration). The skill is invoked through Dispatch.

## Decisions locked

### Scope

- [x] Phase 1 deliverable: working wiki with all five page types,
  migrated from existing vault content
- [x] Phase 2 deferred: OB1 integration, wiki-aware extraction,
  Jenny's interface, public template repo
- [x] Wiki is for me. Agents reference it when I point at them at
  it, not autonomously.

### Structure

- [x] Four ownership domains: `Dev`, `Content`, `Homelab`, plus one
  reserved slot (likely `Personal`, decided later)
- [x] Flat structure below the ownership domain — no `Projects/`,
  `Sessions/`, `Reference/` subfolders. All files live directly
  under the domain folder.
- [x] Top-level `Reference/` for cross-domain entities that don't
  fit cleanly in one domain (Lovebug, OB1, herbydev, Jenny, Sunnie)
- [x] Categorization handled by frontmatter (`type:`, `tags:`),
  not by folder hierarchy
- [x] Indexes and topic landings are auto-maintained, generated
  from frontmatter queries

### Page types (five)

- [x] **Project page** — what I'm working on, current state,
  decisions, open questions, sessions, related
- [x] **Session note** — what I did or thought through. Sessions
  are top-level artifacts, not children of projects. They may
  link to projects via wikilinks.
- [x] **Entity page** — recurring characters in my world (Lovebug,
  OB1, herbydev, Sunnie, Jenny, Tailscale, KeePassXC, etc.)
- [x] **Topic landing / index** — domain-level catalog and prose
  overview, mostly machine-maintained
- [x] **Synthesis page** — cross-cutting analysis with required
  source provenance. Agent generates during compile when it
  identifies a worth-synthesizing pattern. Subject to lint
  scrutiny.

### Operations

- [x] **Capture** — existing email-to-vault pipeline, no changes
- [x] **Compile** — agent-driven, on demand, invoked through
  Dispatch via the wiki-maintenance skill
- [x] **Lint** — agent-driven, on demand, invoked through Dispatch
- [x] **Reference** — I navigate Obsidian indexes and pages; agents
  read files when pointed at them
- [x] No autonomous agent behavior. Every wiki maintenance
  operation is human-initiated.

### Skill pattern

- [x] Skill lives at `~/.claude/skills/wiki-maintenance/` on
  herbydev
- [x] Trigger phrases: "update the wiki", "compile the wiki",
  "lint the wiki", "migrate the wiki"
- [x] Skill bundle: `SKILL.md`, `compile.md`, `lint.md`,
  `migration.md`
- [x] Procedures live in the skill (vault-agnostic). Spec lives
  at `<vault-root>/CLAUDE.md` (vault-specific). They reference
  each other.
- [x] Session plans through Dispatch are thin — just the trigger
  phrase; the skill handles routing

### Git protocol

- [x] Two commits per compile run: `pre-compile: <reason>` and
  `compile: <summary>`
- [x] Compile commit body includes reasoning: pages touched,
  pages created, entities promoted, contradictions flagged,
  synthesis pages written
- [x] Git log is the audit trail; `git reset` is the rollback
- [x] Lint pass after suspicious compile runs; review diffs
  before pushing

### Tags

- [x] Curated starter list, not a free-for-all
- [x] New tags require a real reason
- [x] Anything that looks like a tag but feels like an entity
  should be a wikilink to an entity page instead

## Out of scope

- Wiki-aware extraction (extractor doesn't read the wiki)
- OB1 integration (separate project; deferred until OB1 baseline
  is operational)
- Jenny's interface (separate project; PBS-public web surface,
  served from PBS site eventually)
- Pre-compact hook for Dispatch transcript capture (OB1 territory)
- Public GitHub template repo
- Automated synthesis page generation outside compile runs
- Concept pages and comparison pages (Karpathy spec extras —
  skip until felt as a gap)

## Open items

- [ ] Fourth ownership folder name (deferred until needed; likely
  `Personal`)
- [ ] Dataview vs. agent-maintained indexes — Dataview is native
  to Obsidian and lighter; agent-maintained gives more control.
  Decide during deployment.
- [ ] Exact tag list (will emerge during migration; start small)
- [ ] Whether to keep top-level `Reference/` or fold cross-domain
  entities into `Homelab/` (lean toward keeping it separate)

## Build phases

### Phase A — Draft artifacts

Produce the three deliverables: the project plan (this file),
`CLAUDE.md` for the vault root, and the `wiki-maintenance` skill
bundle (`SKILL.md`, `compile.md`, `lint.md`, `migration.md`). All
drafted in the Claude.ai project session preceding the build.

### Phase B — Deploy artifacts

Hand-off session through Dispatch. Lovebug:

- Creates the new four-folder structure in the vault
- Drops `CLAUDE.md`, `index.md`, `log.md` at the vault root
- Installs the `wiki-maintenance` skill at `~/.claude/skills/`
- Initializes the vault git repo (if not already)
- Verifies the skill loads correctly with a smoke-test invocation
  ("test the wiki skill" or similar)

### Phase C — Migration

Three-step, agent-driven, user-confirmed at each step:

1. **Survey** — agent walks current vault, produces report:
   what's there, current folder, proposed new home in
   four-folder structure. User reviews and corrects.
2. **Move** — agent moves files according to confirmed plan,
   fixes wikilinks as it goes, commits.
3. **Compile** — first compile run on migrated vault. Generates
   project pages from existing project plans, entity pages for
   obvious characters, topic landings. User reviews, corrects,
   agent updates.

## Tasks

### Phase A — Draft

- [ ] Draft `wiki-construct.md` project plan (this file)
- [ ] Draft `CLAUDE.md` for vault root
- [ ] Draft `SKILL.md` for wiki-maintenance skill
- [ ] Draft `compile.md` procedure
- [ ] Draft `lint.md` procedure
- [ ] Draft `migration.md` runbook
- [ ] Project knowledge file for the Claude.ai project context

### Phase B — Deploy

- [ ] Hand off draft artifacts to Lovebug via Dispatch session
- [ ] Lovebug creates four-folder structure in vault
- [ ] Lovebug deploys `CLAUDE.md`, `index.md`, `log.md` to vault
  root
- [ ] Lovebug installs skill at `~/.claude/skills/wiki-maintenance/`
- [ ] Initialize vault git repo (or confirm existing one)
- [ ] Smoke-test the skill: invoke "test the wiki skill" through
  Dispatch and verify it loads, reads CLAUDE.md, and reports back

### Phase C — Migration

- [ ] Trigger migration: "migrate the wiki to the new structure"
- [ ] Review survey report from agent
- [ ] Confirm move plan
- [ ] Review post-move state
- [ ] Trigger first compile run
- [ ] Review compile output (project pages, entity pages, topic
  landings, synthesis pages if any)
- [ ] Iterate on prompts if any page type is consistently wrong

### Phase 1 done when

- [ ] Vault is reorganized into four ownership domains, flat
- [ ] All five page types exist in the vault with real content
- [ ] At least one synthesis page exists with proper source
  provenance
- [ ] Topic landing pages list active projects, recent sessions,
  key entities
- [ ] Top-level `index.md` orients across all four domains
- [ ] Git history shows clean compile commits with usable
  reasoning
- [ ] **Success metric:** I can answer "what's going on with X"
  for any active project in under 30 seconds, without grepping

## Notes

- The skill pattern means session plans through Dispatch can be
  one-line trigger phrases. The skill description does the
  routing.
- CLAUDE.md is portable across vaults (each vault gets its own).
  The skill is vault-agnostic and works against any vault that
  has a CLAUDE.md following the spec.
- Synthesis pages are the one place where lossy compression risk
  is real. Sources-required + lint pass + git diff review are
  the three controls.
- Migration is one-shot. After migration, the wiki is
  operational and compile runs are the steady-state operation.