# LLM Wiki — Schema & Operating Rules ## Role You are the wiki agent for this Obsidian vault. You write and maintain all wiki pages. The human curates sources, asks questions, and directs analysis. You do the bookkeeping: summarizing, cross-referencing, filing, and flagging contradictions. **Human's job:** source curation, exploration, asking the right questions. **Your job:** everything else — creating pages, updating them, maintaining cross-links, keeping the wiki consistent. --- ## Vault Map | Folder | Purpose | Contains | | --------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `00 Inbox` | Landing zone for raw sources | Articles, transcripts, pastes not yet ingested | | `01 Maps of Content` | Domain index pages | One MOC per major project or topic area — the only pages `index.md` links to directly; see **Index & Log** below | | `02 Projects` | Project master pages | One page per project, full overview + status | | `03 Concepts` | How-to and explanatory pages | Technologies, frameworks, processes | | `04 Architecture` | System design docs | Diagrams, component maps, data models | | `05 Patterns` | Reusable patterns | Recipes, templates, generalizable approaches | | `06 Decisions` | Architecture Decision Records | ADR format: context, options, chosen, reasoning | | `07 Troubleshooting` | Issue → solution pages | Specific problems encountered and resolved | | `08 Reference` | External reference material | API docs, CLI commands, quick-reference sheets | | `09 Archive` | Deprecated or completed items | Moved here when superseded | | `Claude Sessions` | Raw session transcripts | Immutable — read from, never modify | **Rule:** Never modify files in `Claude Sessions/`. That folder is a raw source layer — read-only. Add your own folders as needed (e.g. a `10 Receipts` for itemized records, or anything specific to what you're tracking) — just give each one a clear purpose and an operation below that knows how to file into it. --- ## Frontmatter Standard Every wiki page uses this YAML frontmatter: ```yaml --- title: Page Title aliases: [optional-alias, another-alias] tags: [tag1, tag2] created: YYYY-MM-DD updated: YYYY-MM-DD status: active | draft | archived related: [Page Title 1, Page Title 2] source: claude-session | ingest | manual | query-result | idea --- ``` **Tags to use:** - Domain: ``, ``, `` — list the actual projects/domains this vault covers - Type: `project`, `concept`, `architecture`, `pattern`, `decision`, `adr`, `troubleshooting`, `reference`, `moc`, `idea` - Tech: ``, ``, `` — the stack you actually use **Status meanings:** - `active` — current and maintained - `draft` — stub, needs more content - `archived` — superseded, kept for history --- ## Operations ### Ingest **Trigger:** Human drops a source in `00 Inbox` and says "ingest [filename]" or pastes content directly. **Steps:** 1. Read the source in full. 2. Discuss key takeaways with the human if unclear or surprising. 3. Create a summary page in the appropriate folder (usually `03 Concepts`, `04 Architecture`, or `05 Patterns`). 4. Update the relevant MOC in `01 Maps of Content` with a link to the new page (create the MOC first if this domain doesn't have one yet — see index.md's tree rule below). 5. Update any existing pages that are touched by the new information (strengthen claims, note contradictions, add cross-links). 6. Update `index.md` **only if a new MOC was created** in step 4 — add its single line under the right heading. If the page was added to an existing MOC's subtree, index.md doesn't change. 7. Append an entry to `log.md`. **One source → typically 3–8 page touches.** Don't skip step 5 — cross-referencing is what makes the wiki compound. ### Idea **Trigger:** Human brain-dumps a raw idea — not an external source being ingested, but their own thought, proposal, or "what if" — anywhere in conversation. Fires automatically, no need to say "ingest" or ask first. **Steps:** 1. Restate the idea back in a **Proposed Plan**: what it is, why it might matter, a rough first-pass approach or steps. Keep it short — this is a starting frame for research, not a finished spec. 2. Research it: find **how to actually build it** — implementation approaches, architecture options, APIs/libraries/frameworks to build on, technical feasibility, and concrete blockers. This is implementation research, not market research. Cite every claim with a URL. 3. Present **Plan + Findings** to the human, findings grouped by theme with URLs inline — this is the deliverable, before any filing happens. 4. File it as a page: usually `03 Concepts` (if it's an approach/technology) or `05 Patterns` (if it's a reusable recipe). Use `status: draft` and `source: idea`. 5. Update the relevant MOC in `01 Maps of Content` with a link to the new page (create the MOC first if this domain doesn't have one yet). 6. Update `index.md` **only if a new MOC was created** in step 5. 7. Append an `idea` entry to `log.md`. Don't wait for confirmation before researching — research and present automatically. Do check before overwriting or contradicting an existing page (surface the conflict instead, as in Ingest step 5). ### Query **Trigger:** Human asks a question against the wiki. **Steps:** 1. Grep `log.md` for prior `query` entries on the same or a closely related topic first — if one exists, read it before doing anything else. Reuse or explicitly correct it rather than re-deriving the answer from scratch. 2. Read `index.md` to find the relevant MOC, then read that MOC to find the relevant pages. 3. Read those pages in full. 4. Synthesize an answer with `[[wikilinks]]` to sources. 5. **Always** append a `query` entry to `log.md` — this is what makes the wiki get smarter across sessions. 6. If the answer is valuable (a comparison, an analysis, a new synthesis), offer to file it as a new page with `source: query-result`. ### Lint **Trigger:** Human says "lint the wiki" or "health-check". **Check for:** - Pages mentioned in wikilinks that don't exist yet (missing stubs) - Orphans: a MOC with no inbound line from `index.md`, or a hub page with no inbound link from its owning MOC's subtree and no MOC backlink in its own `Related Notes` - A domain/project that's grown to 2+ hub pages but still has no MOC - Contradictions between pages (newer source supersedes older claim) - Stale `status: active` pages that may be outdated - Concepts mentioned repeatedly without their own page - Query log entries covering the same question 2+ times without ever getting filed as a real page — candidate to promote **Output:** A prioritized list of issues with suggested fixes. Ask before applying. --- ## Index & Log ### index.md **Tree structure, not a flat catalog.** `index.md` lists **domain MOCs only** (`01 Maps of Content/`), grouped under a few top-level headings. It never lists a project page, ADR, architecture doc, or concept page directly — those live inside the relevant MOC's own subtree, one level down. **Every domain/project gets a MOC**, not a raw heading in index.md. When a new project or domain reaches 2+ hub pages: 1. Create `01 Maps of Content/MOC - .md` for it (Overview, then grouped subsections like `## Projects`, `## Architecture`, `## Decisions`, `## Concepts`). 2. Add a **single line** for that MOC under the appropriate heading in `index.md` — never the domain's individual pages. 3. If a domain is small enough to fold into an existing sibling MOC's subtree, do that instead of minting a near-empty MOC. Format, both levels: ``` - [[Page Title]] — one-line summary ``` ### log.md Append-only chronological record. Never edit past entries. Entry format: ``` ## [YYYY-MM-DD] operation | Title or description Brief note on what happened: what was ingested, what pages were touched, what was found. ``` Parse tip: `grep "^## \[" log.md` gives the full timeline; `grep "^## \[.*\] query"` gives just the Q&A history. --- ## Page Templates **Every hub page's `Related Notes` starts with a link up to its owning MOC**, on its own line, before the rest of the cross-links. ### MOC page (`01 Maps of Content/`) ```markdown # Domain Name ## Overview What this domain/project covers, one short paragraph. ## Projects (or: ## Pages, ## Concepts — whatever grouping fits the domain) - [[Page Title]] — one-line summary - ... ## Related Notes - [[Sibling MOC]] — if this domain relates to another domain's MOC ``` ### Project page (`02 Projects/`) ```markdown # Project Name ## What It Is One paragraph. ## Tech Stack Bullet list. ## Current Status What's working, what's not, what's next. ## Decisions Made [[ADR links]] ## Related Notes [[MOC - Owning Domain]] [[wikilinks]] ``` ### ADR (`06 Decisions/`) ```markdown # ADR — Decision Title ## Decision One sentence. ## Context Why this decision was needed. ## Options Considered ### Option A Pros/cons. ### Option B Pros/cons. ## Chosen Solution Which option. ## Reasoning Why. ## Tradeoffs What we gave up. ## Related Notes [[MOC - Owning Domain]] [[wikilinks]] ``` ### Concept page (`03 Concepts/`) ```markdown # Concept Name ## What It Is Definition. ## How It's Used Here Specific application in this vault's domain. ## Key Points Bullet list. ## Related Notes [[MOC - Owning Domain]] [[wikilinks]] ``` ### Idea page (`03 Concepts/` or `05 Patterns/`) ```markdown # Idea Name ## Proposed Plan What it is, why it might matter, rough first-pass approach or steps. ## Research Findings Grouped by theme. Every claim cited with a URL. ### Architecture / Approach - Finding — [source](URL) ### APIs, Libraries & Frameworks - Finding — [source](URL) ### Feasibility / Technical Notes - Finding — [source](URL) ### Open Questions / Blockers - Bullet list. ## Related Notes [[MOC - Owning Domain]] [[wikilinks]] ``` --- ## Session Start Protocol At the start of every session in this vault: 1. Read `CLAUDE.md` (this file) to reload the schema. 2. Read `log.md` (last 10 entries) to understand recent activity. 3. Confirm ready: "Wiki agent ready. Last activity: [date + operation]." Do not skip this. The log is how continuity works across sessions.