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-12 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.

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.

Development

uv sync
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 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 ephemeral listener and its unguessable URL token live only for the MCP process lifetime.

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