wiki-context/wiki-construct-context.md

# Wiki Construct — Project Context

This file captures the reasoning behind the wiki-construct project
decisions. Future conversations in this Claude.ai project should
read this to understand *why* the decisions are what they are, not
just what they are. This is project context, not a deliverable.

## Origin

The project came out of two converging conversations:

1. A review of Karpathy's LLM Wiki gist (April 2026) — an idea
   for using an LLM to incrementally compile a structured wiki
   from raw sources, sitting between the user and their corpus.
   The gist is intentionally abstract; it describes the pattern
   and tells the reader to instantiate it with their LLM.

2. A research session on AI memory architecture — established
   that Travis's "build my own harness" instinct was actually a
   "build my own memory layer" need. OB1 (NateBJones-Projects/OB1)
   was identified as the right adoption target for the Lovebug-
   facing memory layer.

The wiki and OB1 ended up framed as **two complementary memory
systems with mostly disjoint audiences**:

- **Wiki = Travis's interface to his own thinking.** Slow,
  deliberate, organized for human browsing in Obsidian. Lovebug
  reads it only when explicitly pointed at a file.
- **OB1 = Lovebug's working memory.** Fast, voluminous,
  semantic search via MCP, captured automatically from sessions.

This framing is the load-bearing decision. It collapsed
architectural confusion that had built up about "should the wiki
be agent-readable" — answer: no, not in the first-class sense.
It's a human tool. Agents can read files when pointed at them,
but the wiki is not designed for autonomous agent consumption.

## Why flat structure won

Earlier drafts had nested subfolders inside each ownership
domain: `Dev/Projects/<slug>/`, `Dev/Sessions/`, `Dev/Reference/`.
Travis pushed back on this with a use case: "I won't navigate
folders — I'll go to an index." Fine-grained folders solve a
problem he doesn't have.

The flat structure works because:

- The index page (`<domain>/index.md`) is the navigation surface,
  not the file tree
- Frontmatter (`type:`, `tags:`, `status:`) does categorization
  better than folders, because it's multi-dimensional
- Obsidian's graph view and backlinks panel make wikilink-based
  navigation more useful than folder-based
- Folders only matter to the agent (where to write new files)
  and to git, both of which are happy with flat

Travis's user story: "I built a PBS CLI tool, where did I put
that project plan?" → flat structure means it's listed on
`Content/index.md`, found in seconds. Not buried four folders
deep.

## Why five page types (synthesis included)

The Karpathy spec has entity, concept, comparison, synthesis as
page types. Earlier draft proposed dropping all but entity and
adding project, session-notes, topic-landing — four types total.

Travis pushed back on dropping synthesis. Reasoning he gave:
"It's the thing I want. I'd rather turn it off later than have
to adjust to include it." Plus git-as-recovery mitigates the
silent-corruption risk.

So the final spec includes synthesis as a real page type, with
two safety controls:

1. **Sources required** — every synthesis page lists the pages
   it pulled from, so provenance is traceable
2. **Lint scrutiny** — synthesis pages get extra checks during
   lint (sources still exist, sources still say what synthesis
   claims they say, no source has been substantially edited)

Concept pages and comparison pages are dropped. They felt like
spec extras for a research-paper-heavy corpus, not an
operational vault of project plans and session notes. Add them
later if a gap is felt.

## Why the skill pattern won

Earlier proposed: a `CLAUDE.md` at the vault root holding both
spec and procedures, invoked via session plans through Dispatch
that pointed at it explicitly.

Travis pushed back: how is that different from a skill? You're
just doing the trigger-routing manually instead of letting the
runtime do it.

He was right. Lovebug confirmed Claude Code on herbydev does
load skills from `~/.claude/skills/`, so the skill pattern works
through Dispatch. The split is:

- **Skill** (`~/.claude/skills/wiki-maintenance/`) — procedures
  (compile, lint, migration). Vault-agnostic. Loaded by the
  runtime when trigger phrases match.
- **CLAUDE.md** (vault root) — spec (page types, frontmatter,
  folder ownership, tags, git protocol). Vault-specific. Read
  by the skill at the start of every operation.

This means session plans through Dispatch can be one-line
trigger phrases ("update the wiki"). The skill description
handles routing. CLAUDE.md handles the spec. No
session-plan-with-pointer required.

## Sessions are top-level, not children of projects

Travis clarified: a session note is whatever happened in a
working session that produced enough learning to capture but
didn't crystallize into a project. Sessions may reference
projects via wikilinks but do not live inside them.

There are *also* coding-session notes captured by the agent
during code execution — those live in the coding project's repo
(eventually OB1), not in the wiki. The wiki holds Travis's
sessions. OB1 will hold the agent's session captures.

This distinction kept getting blurred and finally settled here.

## What's deferred

These were considered and explicitly deferred:

- **Wiki-aware extraction** — extractor doesn't read the wiki.
  Phase 2 if at all.
- **OB1 integration** — the wiki is decoupled from OB1. They
  feed the same eventual context-assembler but don't share
  infrastructure now.
- **Jenny's interface** — a future PBS-public web surface that
  reads from the wiki. Out of scope.
- **Public template repo** — `trucktrav/homelab-templates` for
  hosting the schema doc publicly. Phase 2.
- **Pre-compact hook for Dispatch transcript capture** — that's
  OB1 territory.
- **Concept and comparison pages** — Karpathy spec extras. Add
  if a gap is felt.

## Success metric

Travis's metric, restated: *"The wiki is working when I can go
to it, find info, without starting at a bunch of files in a
bunch of different folders and trying to remember what is
what."*

Concrete version: he can answer "what's going on with X?" for
any active project in under 30 seconds, without grepping. If
the user story above (PBS CLI tool) takes more than two clicks,
the wiki is failing.

## Naming / labels worth keeping consistent

- **The project:** `wiki-construct`. The construction phase,
  distinct from the wiki itself once operational.
- **The vault:** "the wiki vault" or "the HomeLab vault". Same
  thing.
- **The skill:** `wiki-maintenance`. Lives at
  `~/.claude/skills/wiki-maintenance/` on herbydev.
- **The spec file:** `CLAUDE.md` at the vault root. Always
  capitalized that way (per Anthropic convention).
- **The harness:** Dispatch (which invokes Claude Code on
  herbydev). When discussing the agent that performs operations,
  call it Lovebug or "the agent" — both are fine.
- **The two memory systems:** "the wiki" and "OB1". Don't try
  to rename them or unify the framing.

## Open items (deferred decisions)

- Fourth ownership folder name (likely `Personal`, decided when
  needed)
- Dataview vs. agent-maintained indexes — Dataview is native to
  Obsidian and handles frontmatter queries; agent-maintained
  gives more control over prose sections. Pick during Phase B
  deploy.
- Whether top-level `Reference/` stays or folds into a domain
  later. Lean: keep it.
- Exact tag list. Will emerge during Phase C migration.

## Related projects

- **`ob1-deployment`** — the parallel memory system for
  Lovebug. Six-phase deployment plan, Tailscale-only initially,
  Authelia deferred until Jenny's interface lands.
- **`second-brain`** (older project plan) — the extraction
  pipeline + LLM wiki idea, before the wiki/OB1 split was
  cleanly framed. Some of its scope rolled into wiki-construct
  (the wiki side) and some into ob1-deployment (the harness
  memory side). The "context assembler" concept from
  second-brain remains relevant for Phase 2 future work.