# agent-wiki-kit

[![CI](https://github.com/AvalancheAI-labs/agent-wiki-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/AvalancheAI-labs/agent-wiki-kit/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)

**One engine for every LLM wiki you'll ever run.** A wiki is a folder of
Markdown files with frontmatter plus a `wiki.yaml` registry — wikikit makes it
**lintable** (contracts, links, freshness), **publishable** (`llms.txt`,
`llms-full.txt`, `index.json`, plain no-JS HTML), and **consumable by any
agent over MCP**. Zero dependencies: Python 3 stdlib only.

The pattern follows the Karpathy LLM-wiki idea and the agentwikis.com serving
model: knowledge is *compiled once and kept current*, not re-derived per query.
Compilation is agent work (the `wiki-ingest` skill / `wikikit ingest`); the
engine itself is deterministic.

**See it live:** [`examples/corporate-brain-patterns`](examples/corporate-brain-patterns)
is a real wiki built with wikikit — read [`INDEX.md`](examples/corporate-brain-patterns/INDEX.md)
for the source pages, or the generated [`_site/`](examples/corporate-brain-patterns/_site)
for what `wikikit build` emits (llms.txt, llms-full.txt, index.json, HTML).

## Why not just a vector DB / RAG over raw docs?

Raw-text retrieval re-derives an answer from whatever chunks happen to match
a query, every single time — no page ever gets *better*, corrections don't
stick, and nothing tells you a source went stale. wikikit's bet: a small,
governed, continuously-curated wiki that an agent reads directly beats
re-deriving from an ever-growing pile of raw source documents, both on
accuracy and on maintenance cost. See
[`reference/curated-vs-raw-retrieval`](examples/corporate-brain-patterns/reference/curated-vs-raw-retrieval.md)
for the evidence. It isn't a replacement for a vector DB on unstructured
search — it's for the slice of knowledge worth compiling once and keeping
current, the same slice a human onboarding doc or runbook already covers.

## Quick start

```bash
pip install -e .            # or: pip install wikikit, once published

# scaffold a wiki (constitution + registry + meta)
wikikit init ~/wikis/my-domain --name my-domain

# compile a source into it (uses the claude CLI; or use skills/wiki-ingest interactively)
wikikit ingest ~/wikis/my-domain ~/Downloads/some-research.md

# health
wikikit lint ~/wikis/my-domain      # errors exit 1 — CI-able
wikikit status ~/wikis/my-domain

# publish for agents + humans
wikikit build ~/wikis/my-domain     # -> _site/llms.txt, index.json, HTML

# serve to any MCP client
wikikit serve ~/wikis/my-domain
```

No install? Every command also runs as `python3 wikikit_cli.py <cmd> ...`
from a clone of this repo.

Register with Claude Code / Claude Desktop:

```json
{"mcpServers": {"my-domain-wiki": {
  "command": "wikikit",
  "args": ["serve", "/path/to/wikis/my-domain"]}}}
```

MCP tools exposed: `wiki_list_pages`, `wiki_read_page`, `wiki_read_section`
(cheap targeted reads), `wiki_search`, `wiki_recent`. Pages are re-read on each
call, so edits are live without restarting.

## Page contract

```yaml
---
title: GitLab's Public Handbook
type: entity          # from wiki.yaml page_types
status: live          # live | draft | deprecated | planned
last_verified: 2026-07-07   # a claim: checked against reality on this date
summary: One line for llms.txt listings and search results.
sources: [where this came from]
tags: [a, b]
---
```

`[[wikilinks]]` are first-class (lint checks them both in `[[slug]]` and
relative `.md` link form). Dirs starting with `_` (`_raw`, `_meta`, `_site`)
are operational, never served.

## Lint rules

MALFORMED, MISSING_FIELD, BAD_STATUS, BAD_DATE, UNKNOWN_TYPE, BROKEN_LINK
(errors — exit 1) · STALE, ORPHAN, NO_SUMMARY (warnings).

## Layout

```
wikikit/            engine (frontmatter, wiki model, lint, search, build, mcp_server, ingest, cli)
templates/          scaffolding used by `init` (CONSTITUTION.md, wiki.yaml)
skills/wiki-ingest/ Claude Code skill: how to compile sources into a wiki
examples/corporate-brain-patterns/  working demo — public case studies in compiled organizational knowledge (lints clean, serves over MCP)
```

## Instance profiles (roadmap)

The same engine backs different products by choosing page types + ingest sources:

- **Market/competitor wiki** — entities + synthesis + weekly signals, for tracking a competitive landscape.
- **Key-account wiki** — snapshot, buying map, tech stack, angle, and signals per account.
- **Data-asset wiki** — tables, semantic models, pipelines, and agents, feeding downstream analytics agents.
- **Ops wiki** — runbooks + known-error DB.