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 neighborhood, semantic Flow, convergence Web, source inspection, and branch-aware 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.

Graph views

The browser presents the same indexed graph through three complementary views:

Nodes shows a bounded, relation-neutral neighborhood around the focus. It is the broad inspection view for seeing stored incoming and outgoing relationships without changing their direction. Semantic cards distinguish structure, behavior, dependencies, execution, data, evidence, context, and other relationships.
Flow shows semantic origin-to-destination paths that terminate at the focus. DocForge reverses prerequisite-style relationships for presentation, so imports, dependencies, reads, inheritance, definitions, and tests flow toward the thing they help create or exercise.
Web shows the larger convergence picture: Flow contributors plus contextual relationships, callers, containers, and direct members or execution dependencies owned by the focus.

Graph cards show the node's readable leaf name and kind without clipping either value. The full qualified identity remains available in the tooltip, compact descriptor, and full inspector.

Hide node removes noise without changing the index. In Flow and Web, hiding a contributor also removes upstream ancestors that no longer have a path to the focus. Nodes between the hidden contributor and the focus stay visible, and alternate ancestor paths remain intact. Restore hidden restores the presentation.

Five-minute start

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

git clone forgejo@repo.andraxion.net:administrator/DocForge.git /absolute/path/DocForge
cd /absolute/path/DocForge
uv sync --group dev
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

npx pyright
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 pytest -q

See AGENTS.md before changing core boundaries.

3.9 KiB Raw Blame History