DocForge2/README.md

DocForge

DocForge is a project-scoped documentation graph for people and AI agents. It validates canonical documentation, builds a disposable search and relationship index, compiles bounded context, renders declared manuals, visualizes project structure, and manages reviewable documentation changesets.

What it does

• Validates stable Markdown/TOML nodes and typed relationships.
• Builds a deterministic SQLite search and graph index.
• Exposes project-bound CLI and MCP query surfaces.
• Creates, validates, diffs, and previews isolated changesets.
• Applies one explicitly approved changeset hash through CLI or gated MCP.
• Runs a managed loopback graph browser with Flow, source inspection, and node hiding.
• Supports generic documentation projects and project-owned source adapters.

DocForge never treats indexed text as instructions. It does not run shell commands, mutate Git, build applications, deploy, publish, or select projects globally.

Five-minute start

Requirements are Python 3.12+, uv, Node.js/npm, and Pyright.

git clone forgejo@repo.andraxion.net:administrator/DocForge.git /absolute/path/DocForge
cd /absolute/path/DocForge
uv sync
npm ci

PROJECT=/absolute/path/MyProject
.venv/bin/docforge --project-root "$PROJECT" validate
.venv/bin/docforge --project-root "$PROJECT" reindex
.venv/bin/docforge --project-root "$PROJECT" visualize

Install the persistent per-user graph viewer once:

.venv/bin/docforge-viewer-manager install-user-service

Start an MCP server for one project:

.venv/bin/docforge-mcp \
  --project-root "$PROJECT" \
  --proposal-writer project-editor

Add --canonical-applier project-editor only when that MCP integration should expose the hash-bound docforge_apply_changeset tool.

Documentation

• User manual — features, setup, visualization, CLI, MCP, apply, adapters, and troubleshooting.
• Core contract — invariants and security boundary.
• MCP contract — exact tool and process boundary.
• Viewer manager — native service setup and lifecycle.
• Adapter decision — why custom adapters own canonical serialization.

Development

pyright --pythonpath .venv/bin/python
npm run lint:web
uv run ruff check src tests tools
uv run ruff format --check src tests tools
uv run python -m compileall -q src tests tools
uv run python -W error -m unittest discover -s tests -v

See AGENTS.md before changing core boundaries.