Build Structured Markdown Knowledge Wiki

---
name: build-structured-markdown-knowledge-wiki
description: "LLM-maintained personal knowledge base. Compile raw sources into a structured markdown wiki, auto-lint for consistency, serve as a browsable website. Inspired by Karpathy's 'LLM Knowledge Bases' workflow. Use when: user asks to create/manage a wiki, 'wiki this', 'add to wiki', '…"
category: "AI & Agents"
author: community
version: "1.2.0"
icon: bot
---

# 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:

| Dependency | Purpose | Installed by |
|---|---|---|
| Python 3 | MkDocs runtime | Must be pre-installed |
| mkdocs + mkdocs-material | Static site generator | `bootstrap.sh` via pipx or pip3 |
| git | Version control | Must be pre-installed |

### 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:

```markdown
## [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