Forgedocs

Appearance

ForgedocsArchitecture Documentation That Stays Accurate

Auto-discovered from your repos. Verified by invariant checks. Maintained by AI-assisted commands.

Get Started
View on GitHub

MCP Server for Claude

Claude queries your docs mid-task via MCP — search across repos, read any doc, check freshness. Your doc site becomes an active knowledge base.

Verifiable Invariants

Each architectural rule includes a check command. /doc-review executes them and reports pass/fail — documentation that proves it's correct.

AI Agent-Aware

CLAUDE.md gives your AI coding agent real context. It reads the docs at every session, knows the invariants, and respects the rules.

CI Freshness Checks

GitHub Action warns on PRs when structural changes need doc updates. No stale docs slipping through.

Auto-Discovery

Any repo with an ARCHITECTURE.md is detected. Hot-reload, full-text search, dynamic sidebar — no config needed.

8 Claude Commands

/doc-init, /doc-review, /doc-sync, /doc-feature, /doc-adr, /doc-pr, /doc-onboard, /doc-ci — generate, audit, and maintain docs from Claude Code.

Quick Start ​

bash
npm install -g forgedocs
forgedocs init        # discover repos
forgedocs dev         # start the doc server

Or bootstrap a new repo's documentation:

bash
forgedocs install ~/path/to/your-repo   # install Claude Code commands
cd ~/path/to/your-repo
claude                                   # open Claude Code
# Type: /doc-init                        # generate everything

Documentation Structure ​

For a repo to appear in this site, it needs an ARCHITECTURE.md at its root. The more docs you add, the richer the sidebar becomes.

Minimum (required) ​

my-service/
├── ARCHITECTURE.md       ← Detection marker — codemap, invariants
└── README.md             ← Shown as the service home page
my-service/
├── ARCHITECTURE.md       ← Codemap, data flow, verifiable invariants
├── CLAUDE.md             ← AI agent entry point (conventions, anti-patterns)
├── README.md             ← Setup, deployment, usage
└── docs/
    ├── glossary.md       ← Domain vocabulary
    ├── service-map.md    ← Inter-service communication
    ├── security.md       ← Security rules
    ├── features/         ← One file per complex feature
    │   └── my-feature.md
    └── adr/              ← Architecture Decision Records
        ├── README.md
        └── 001-some-decision.md

The sidebar is generated automatically from whatever files exist — no manual config needed.

File Roles ​

FilePurposeSidebar Section
README.mdService overview, setup instructionsHome
ARCHITECTURE.mdHigh-level codemap, data flow, verifiable invariantsArchitecture
CLAUDE.mdAI agent conventions (not shown in sidebar)—
docs/*.mdGuides (glossary, security, service map, etc.)Guides
docs/features/*.mdFeature documentation (what a feature does, how it works)Features
docs/adr/*.mdArchitecture Decision RecordsADRs

CLI Reference ​

CommandDescription
forgedocs initInteractive setup — discover repos, create symlinks
forgedocs devStart the documentation dev server
forgedocs buildBuild static site
forgedocs add <path>Add a specific repo
forgedocs remove <name>Remove a repo
forgedocs statusShow tracked repos and their doc coverage
forgedocs install <path>Install Claude Code commands into a repo
forgedocs doctorDiagnose common issues
forgedocs mcpStart MCP server for Claude Code integration
forgedocs helpShow help and list all commands

Claude Code Commands ​

Installed into your repo via forgedocs install — available in any Claude Code session.

CommandWhat it doesWhen to use
/doc-initGenerates full documentation structure by exploring codeBootstrapping a new repo
/doc-featureCreates feature doc with invariants, preconditions, failure modesAfter building a complex feature
/doc-syncChecks if docs need updating after code changesAfter a PR that changes architecture
/doc-reviewFull audit — executes invariant checks, compares docs against codeQuarterly, or before a release
/doc-onboardGenerates personalized reading path with estimated timesOnboarding a new developer
/doc-adrCreates a numbered ADR by researching codebase and git historyAfter a significant architectural decision
/doc-prChecks all PR changes against docs, proposes updatesBefore merging a PR
/doc-ciGenerates GitHub Actions workflow for doc freshness checksOnce per repo — CI setup

Feature docs convention ​

Place one markdown file per feature under docs/features/. The sidebar title is extracted from the first # Heading in the file:

markdown
# Go Back In Time (GBIT)

## What it does
...