wiki-forge

The open-source docs compiler that lives in your repo, runs in your CI, and never phones home.

Wiki Forge compiles your source code into a plain-language wiki that PMs, designers, and new engineers can actually understand. When code changes, it detects drift and rewrites only what changed.

Your code ──→ Wiki Forge ──→ Up-to-date wiki
  (source)     (compiler)      (docs, entities, concepts, index)

Why

Documentation rots because maintaining it is manual work that competes with shipping features. Wiki Forge treats docs as compiled artifacts — the code is the source of truth, the LLM is the compiler, the docs are the build output.

	Manual Docs	RAG / Chatbot	Google Code Wiki	Wiki Forge
Output you own	:white_check_mark:	:x:	:x:	:white_check_mark:
Version-controlled	:white_check_mark:	:x:	:x:	:white_check_mark:
Works offline / air-gapped	:white_check_mark:	:x:	:x:	:white_check_mark:
Auto-updates	:x:	:white_check_mark:	:white_check_mark:	:white_check_mark:
Reviewable as a PR	:white_check_mark:	:x:	:x:	:white_check_mark:
Cost	time	per query	freemium	per compile

Your code stays yours

With --provider local, Wiki Forge pipes prompts through your local claude or ollama CLI. Nothing leaves your machine.

Provider	Where your code goes
gemini / claude / openai	API call to vendor
local	Stays on your machine, always

Two ways to use it

1. GitHub Action (for CI/CD)

Automatically compiles docs on every push to main:

# .github/workflows/docs-sync.yml
name: Docs Sync

on:
  push:
    branches: [main]
    paths-ignore: ["docs/**"]

permissions:
  contents: write
  pull-requests: write

jobs:
  compile:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: thevrus/wiki-forge@v1
        id: forge
        with:
          api_key: ${{ secrets.GEMINI_API_KEY }}

      - uses: peter-evans/create-pull-request@v7
        if: steps.forge.outputs.docs_changed == 'true'
        with:
          title: "docs: sync with codebase changes"
          body: |
            **Updated:** ${{ steps.forge.outputs.updated_docs }}

            ${{ steps.forge.outputs.diff_summary }}
          branch: docs/auto-sync
          delete-branch: true

2. Claude Code slash commands

npx wiki-forge install-commands

That's it. No cloning, no config. Now open any project in Claude Code and type /wf-init.

Then in any project:

/wf-init                     # interview + scan → creates .doc-map.json
/wf-compile --force          # compile all docs from scratch
/wf-compile                  # incremental — only recompile drifted docs
/wf-check                    # preview what drifted (read-only)
/wf-health                   # check human-written docs for contradictions
/wf-validate                 # check config for missing sources
/wf-index                    # regenerate INDEX.md
/wf-query "how do fees work" # ask questions, save answers as wiki pages

No API key needed — Claude Code is the LLM.

What it produces

docs/
  .doc-map.json           # config — maps docs to source directories
  .last-sync              # git commit hash of last compilation
  INDEX.md                # master index with summaries of everything
  log.md                  # compilation changelog
  ARCHITECTURE.md         # compiled docs (user-defined)
  PRODUCT.md
  BUSINESS_RULES.md
  entities/               # auto-extracted from compiled docs
    booking-service.md
    payment-gateway.md
  concepts/               # auto-extracted cross-cutting themes
    authentication-flow.md
    fee-calculation.md

Each compiled doc includes:

• YAML frontmatter with sources and compilation timestamp
• Mermaid diagrams for architecture, data flows, and state machines
• Inline citations like (source: auth module) — plain language, not file paths
• No code snippets — written for PMs, not engineers

How it works

Init: interview-first setup

/wf-init doesn't just scan directories. It asks:

• "What does this project do?" (proposes answer from README)
• "Who's this wiki for, and what do they ask about?"

Then scans the codebase and suggests docs informed by both your answers and the code structure — including custom docs like INJECTION.md that don't fit standard templates.

Compile: two-pass, cost-optimized

• Triage (cheap model) — "Did this doc drift?" Most pushes stop here.
• Recompile (expensive model) — Only runs on drifted docs.

With --force, it does a deeper two-pass:

• Summarize — Reads all source, extracts structured facts
• Compile — Writes the doc from the summary

Estimated cost per compile

Repo size	Triage cost	Full recompile
Small (~10 files)	~$0.01	~$0.10
Medium (~100 files)	~$0.05	~$0.50
Large (~500 files)	~$0.10	~$2.00

Structured wiki output

After compilation, Wiki Forge reads all compiled docs and automatically extracts:

• Entities — concrete things (services, APIs, models, UI components)
• Concepts — abstract patterns (auth flow, booking lifecycle, fee rules)

Each gets its own wiki page. The INDEX.md links everything together.

Query with persistence

/wf-query "how does the booking flow work?" reads the wiki and answers with citations back to specific docs.

Health checks

For human-written docs (ADRs, decision logs), Wiki Forge doesn't rewrite — it checks for contradictions:

Warning: DECISIONS.md:
  - Decision #3 says "no database" but src/db/ directory now exists
  - Decision #7 references "XState FSM" but the cart now uses Zustand

Configuration

Doc map

docs/.doc-map.json maps documentation to source code:

{
  "docs": {
    "ARCHITECTURE.md": {
      "description": "System architecture: services, APIs, data flows",
      "type": "compiled",
      "sources": ["src/api/", "src/services/"],
      "context_files": ["package.json"]
    },
    "DECISIONS.md": {
      "description": "Architectural decision records",
      "type": "health-check",
      "sources": ["src/"],
      "context_files": []
    }
  },
  "style": "Write for a technical audience. Include code examples."
}

Field	What it does
description	Tells the LLM what the doc covers
type	"compiled" = LLM writes it. "health-check" = human writes it, LLM checks it
sources	Directories the LLM reads
context_files	Always-included files for broader context
style	Optional — override the default writing style

LLM providers (CLI / GitHub Action)

Provider	Triage model	Compile model	Env var
gemini	gemini-2.5-flash	gemini-2.5-pro	GEMINI_API_KEY
claude	claude-haiku-4-5	claude-sonnet-4-6	ANTHROPIC_API_KEY
openai	gpt-4.1-mini	gpt-4.1	OPENAI_API_KEY
local	claude -p	claude -p	(none needed)

The local provider pipes prompts through the claude CLI. Use --local-cmd for other tools:

wiki-forge compile --provider local --local-cmd "codex -q"

CLI Reference

wiki-forge <command> [flags]

Commands:
  init              Scaffold .doc-map.json (--interactive for guided setup)
  compile           Compile drifted docs (--force for full recompile)
  check             Report drift without writing
  health            Check human-written docs for contradictions
  index             Regenerate INDEX.md
  validate          Check config for missing sources
  install-commands  Install /wf-* slash commands for Claude Code

Flags:
  --provider <gemini|claude|openai|local>  LLM provider (default: gemini)
  --api-key <key>             API key (or set env var)
  --repo <path>               Repository root (default: cwd)
  --docs-dir <path>           Docs directory (default: docs)
  --force                     Recompile all docs
  --interactive, -i           Interactive setup (for init)
  --local-cmd <cmd>           CLI command for local provider (default: "claude -p")

Examples

See examples/ for:

• .doc-map.json — starter config for a typical web app
• docs-sync.yml — GitHub Action workflow with auto-PR and diff preview

Used by

Using Wiki Forge? Open a PR to add your project here.

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT