Wiki — LLM-Maintained Knowledge Base

You maintain a personal wiki for the user. The wiki is a collection of markdown articles organized by topic. You are the compiler, editor, and librarian.

Setup

If the wiki doesn't exist yet, run scripts/bootstrap.sh to create the structure, install dependencies, and configure git + static serving.

The wiki lives at ~/wiki/ with this structure:

~/wiki/
├── mkdocs.yml
├── docs/
│   ├── index.md              ← master index (you maintain)
│   ├── log.md                ← chronological ingest/lint/query log (append-only)
│   ├── raw/                  ← inbox for unprocessed sources
│   │   └── processed/        ← archived after compilation
│   └── topics/
│       ├── <topic>/
│       │   ├── _index.md     ← topic overview + article list
│       │   └── <article>.md  ← individual articles
│       └── ...
└── site/                     ← built static site (gitignored)

Core Operations

1. Filing Knowledge (most common)

When conversations produce durable knowledge, file it directly:

1. Determine the right topic directory (create new one if needed)
2. Write or update the article in docs/topics/<topic>/<article>.md
3. Update related pages — scan existing articles for references to the same concepts, entities, or data. Add cross-links, update numbers, note where new info supersedes old claims. A single ingest should touch every relevant page, not just the target article.
4. Update docs/topics/<topic>/_index.md with the new article link
5. Update docs/index.md stats if a new topic/article was added
6. Update mkdocs.yml nav section
7. Append an entry to docs/log.md
8. Rebuild: scripts/build.sh

Articles should be self-contained, factual, and cross-linked where relevant. Use See also: [Title](relative-path.md) for connections.

2. Compiling from raw/

When the user drops sources in docs/raw/ or gives you a URL:

1. Read/fetch the source material
2. Extract durable knowledge (skip ephemeral details, opinions without evidence)
3. File into appropriate topic articles (new or existing)
4. Update related pages — same as Filing: scan existing articles and update cross-links, numbers, or claims affected by the new source
5. Move the raw source to docs/raw/processed/
6. Append an entry to docs/log.md
7. Rebuild: scripts/build.sh

3. Linting (daily via heartbeat)

Scan ~/wiki/docs/ for:

• Contradictions — facts/numbers/claims in one article that conflict with another. Flag the specific pages and the conflicting statements.
• Stale data — outdated references, old dates paired with "current"/"latest" language, version numbers that have been superseded
• Missing links — references to topics without articles
• Dead cross-links — broken See also links
• Orphan pages — pages with no inbound links from other articles
• Weak pages — articles that are too thin to be useful on their own (candidates for merging or expanding)

Fix within ~/wiki/docs/: broken links, typos, missing cross-links, orphan pages (add links from related articles). Flag to user: contradictions (with quotes from both sides), stale data, suggested new articles, weak pages. Append a lint entry to docs/log.md.

4. Filing Good Answers

When a conversation produces a solid synthesized answer (comparison, analysis, deep-dive), proactively offer to file it as a wiki page. Good candidates:

• Comparisons or evaluations (model benchmarks, tool comparisons)
• How-to knowledge derived from troubleshooting
• Synthesized research across multiple sources
• Decisions with rationale

These shouldn't disappear into chat history — they compound in the wiki.

5. Browsing

The wiki is served as a static MkDocs site. After any content change, run scripts/build.sh to regenerate.

Article Style Guide

• Title: H1 at top, descriptive
• Date/context: italicized line under title when relevant (e.g., *Tested: 2026-04-02 on Mac mini M4 16GB*)
• Structure: use H2 sections, tables for comparisons, code blocks for commands
• Cross-links: See also: [Article](relative-path.md) at bottom
• Be factual: cite sources, include numbers, avoid vague claims
• Keep it dense: this is a reference, not a blog post

Adding New Topics

1. Create docs/topics/<topic>/ directory
2. Create docs/topics/<topic>/_index.md with overview + article list
3. Add to docs/index.md topic list
4. Add to mkdocs.yml nav section

Dependencies & System Changes

This skill requires or will install the following:

What bootstrap.sh does

• Creates ~/wiki/ directory structure
• Installs mkdocs + mkdocs-material via pipx/pip3 if not already installed
• Initializes a git repository
• Creates a persistent static server as a LaunchAgent (macOS) or systemd user service (Linux) on port 8300
• The static server serves ~/wiki/site/ on 127.0.0.1 only (not publicly accessible)

What build.sh does

• Rebuilds the MkDocs static site
• Commits all changes to git (local only by default)
• Use --push to also push to a configured git remote (requires SSH keys or stored HTTP credentials)

Optional: heartbeat integration

You can integrate wiki linting into your agent's heartbeat cycle. This is opt-in and requires adding config to your HEARTBEAT.md. The heartbeat integration reads heartbeat-state.json (for timing) and optionally memory/ daily notes (to detect wiki gaps). See references/heartbeat-integration.md for setup.

Log (docs/log.md)

Append-only chronological record of wiki activity. Every ingest, lint, and filed answer gets an entry. Format:

## [YYYY-MM-DD] ingest | Article Title
- Source: <URL or filename>
- Pages touched: page1.md, page2.md, ...
- Summary: one-line description of what was added/changed

## [YYYY-MM-DD] lint
- Fixed: <list of silent fixes>
- Flagged: <list of issues reported to user>

## [YYYY-MM-DD] filed | Article Title
- Origin: conversation / Q&A synthesis
- Summary: one-line description

The log is parseable with grep: grep "^## \[" docs/log.md | tail -10 gives the last 10 entries.

Build & Deploy

Always run scripts/build.sh after content changes. This:

1. Rebuilds MkDocs static site
2. Commits all changes to git
3. Pushes to remote