Wiki Forge is a decision provenance engine. It compiles your source code, git history, and PRs into a living knowledge base — not just docs, but the why behind every engineering decision. When code changes, it detects drift and rewrites only what changed.

Why

Software engineering has 23-25% annual turnover. Each departure costs 4-8 weeks of delivery time — not because the code is lost, but because the context behind it is. Why was this module built this way? What incident prompted the retry logic? Who knows how the payment flow actually works?

Wiki Forge treats institutional memory as a compiled artifact. The code + git history is the source of truth, the LLM is the compiler, and three types of output serve three audiences:

| Output | Audience | What it contains | |---|---|---| | Wiki pages | PMs, designers, new engineers | Business rules, architecture, decision context | | AI context files | Claude Code, Cursor, Copilot | CLAUDE.md, AGENTS.md, llms.txt | | Knowledge risk reports | Engineering managers | Bus factor per module, onboarding readiness |

| | 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: | | Decision archaeology | :x: | :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 |

Three 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-query "how do fees work" # ask questions, save answers as wiki pages
/wf-brief                    # weekly shipping brief for leadership

No API key needed — Claude Code is the LLM.

3. MCP server (for AI assistants)

Give Claude direct access to your compiled wiki. One server, reads whatever repos it's pointed at:

# Local repo (engineer with git checkout)
claude mcp add wiki-forge -- wiki-forge-mcp --repo ./docs

# Remote repo (PM, no git needed)
claude mcp add wiki-forge -- wiki-forge-mcp --github acme/platform

# Multi-repo
claude mcp add wiki-forge -- wiki-forge-mcp --repo /path/to/repo1/docs --repo /path/to/repo2/docs

Claude gets four tools:

| Tool | What it does | |---|---| | wiki_forge_why | "Why is this file this way?" — maps source file to wiki page, returns decision context | | wiki_forge_who | "Who has context?" — returns ranked contributors with ownership % and bus factor | | wiki_forge_search | Search the compiled wiki by keyword — returns matching pages with excerpts | | wiki_forge_status | Brain health dashboard — coverage metrics, knowledge risk, action items |

No LLM calls, no database, no accounts. The MCP server reads markdown files — the compiled wiki is the product, the server is just the read layer. Works across all Claude surfaces: Claude Code, Cowork, Desktop.

What it produces

docs/
  .doc-map.json           # config — maps docs to source directories
  INDEX.md                # master index with summaries
  _status.md              # brain health dashboard
  ARCHITECTURE.md         # compiled docs (user-defined)
  entities/               # auto-extracted services, APIs, models
  concepts/               # auto-extracted cross-cutting themes
  _reports/               # weekly engineering digests

Each compiled doc includes YAML frontmatter, Mermaid diagrams, inline citations, and is written for PMs — not engineers.

How it works — init interview, two-pass compilation, structured output, queries, health checks

Configuration & CLI reference — doc map schema, LLM providers, all commands and flags

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