DocForge2/README.md

# DocForge

DocForge is a project-scoped documentation service for people and AI agents. It loads canonical
Markdown and TOML from one repository, validates stable nodes and relationships, builds a disposable
search index, and returns bounded context with source provenance.

DocForge does not own project facts. It does not select project work, apply proposals, run project
commands, or perform Git and deployment operations. It may write only configured derived output and
isolated previews through the explicit render boundary.

## Current state

DFG-0 through DFG-14 are complete. Worldforge uses separate read-only sessions and an optional
AssetForge-only proposal process. OpenClaw can propose updates to existing AssetForge chapter prose
through isolated, validated changesets and escaped previews. Canonical integration remains a
developer review step through Worldforge's established builder. DFG-9 found no measured need for an
application command, so manual canonical integration is the permanent DocForge 0.x policy.
Canonical application remains external and closed to the library, CLI, and MCP server. See
[`docs/APPLICATION_DECISION.md`](docs/APPLICATION_DECISION.md).

DFG-10 adds one generic `docforge_visualize` MCP tool. It validates the configured project and
derived index, then starts a token-protected read-only graph browser on `127.0.0.1`. The browser
supports project counts, family filtering, lexical search, exact node inspection, and bounded
incoming-and-outgoing neighborhoods. It accepts no project path, database path, SQL, external bind
address, or write operation.

DFG-11 upgrades the fixed browser template with pointer-centered mouse-wheel zoom, left-button drag
pan, zoom buttons, a reset control, and a live zoom percentage. These controls operate only on the
client-side SVG viewport and do not broaden the read-only HTTP or project authority boundary.

DFG-12 makes graph-node activation open a modal inspector without replacing the current
neighborhood. The dialog exposes the node's complete validated content and offers a separate
Explore neighborhood action when the user wants to recenter the graph.

DFG-13 makes pointer activation reliable by delaying SVG pointer capture until an actual drag
crosses the movement threshold. It also ensures the empty-canvas instruction disappears whenever a
neighborhood is rendered.

DFG-14 makes the viewer useful as a durable project-manual navigator. An open browser page renews
the loopback listener lease across short-lived MCP transactions. Resizable side panels and a
draggable, resizable inspector support dense material. Neighborhoods are grouped generically by
topology into the focus node, outgoing paths, and incoming or lateral context, with distinct
palettes and progressive hop-distance shading.

DFG-17 makes relationship meaning visible without changing project graph facts. Nodes displays
relation-specific colors, line patterns, directional symbols, and an exact visible key. Flow
constructs a bounded upstream lineage with semantic direction for execution, data, and dependency
relations while excluding structural and evidence context.

## Development

Install Pyright once with `npm install -g pyright`. DocForge configures it to use the repository
virtual environment and treats a clean strict run as a required development gate.

```bash
uv sync
npm ci
pyright
npm run lint:web
uv run ruff check src tests tools
uv run ruff format --check src tests tools
uv run python -m unittest discover -s tests -v
uv run docforge --project-root tests/fixtures/alpha validate
uv run docforge --project-root tests/fixtures/alpha render-status manual
uv run docforge --project-root tests/fixtures/alpha render manual
uv run docforge-mcp --project-root tests/fixtures/alpha --proposal-writer alpha-editor
```

The web gate validates the exact graph-browser HTML, CSS, and JavaScript served by DocForge. It also
renders the fixture manual into a temporary project and validates that final HTML document.

The command prints deterministic JSON. Derived indexes live under each project's configured cache
directory and are never canonical input.

Proposal writers are declared by ID in `.docforge/project.toml`. Each writer receives explicit node
families and operation types. The MCP process binds to one writer at startup; tools cannot select or
impersonate another writer. Create, update, move, and delete tools write only isolated JSON
changesets below the configured changeset root.

Projects may also declare render views with confined template, preview, and output paths. The first
built-in renderer converts CommonMark to escaped HTML through strict template tokens. MCP may render
validated changesets only into isolated preview paths. Declared project output is generated through
the explicit local CLI command and is never an MCP operation.

Project adapters implement `AdapterLoader` and return one ordered, immutable `AdapterProjection`.
`AdapterProject` validates the projection and exposes it through the same disposable index used by
generic projects. Project-specific context, query ordering, and render-model policy remain in the
adapter. Shadow adapters are local integration tools; the normal MCP server does not discover or
execute them. An explicit integration may bind a validated adapter project to DocForge's read-only
MCP surface without enabling proposal tools.

Proposal-enabled adapters supply confined project settings and a project-owned validator. The core
still owns hashes, permissions, changeset storage, conflict checks, graph validation, diffs, and
preview confinement. The adapter owns source-format rules and may only narrow the allowed proposal
surface.

Both generic and explicit adapter MCP servers expose the same visualization tool because it reads
the validated `ProjectIndex` supplied by the project binding. Invoking it again refreshes the
browser only after a complete index check. The unguessable loopback URL remains usable while its
browser page renews the lease. Explicit process termination closes it immediately; an abandoned
page expires after a bounded inactivity grace period.

See [`docs/NEW_PROJECT_QUICKSTART.md`](docs/NEW_PROJECT_QUICKSTART.md) for a complete generic MCP
setup, continuous-agent policy, visualization instructions, and a project-adapter checklist.