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 gate

DFG-1 through DFG-7 are complete. Worldforge now uses two explicit read-only sessions for its main
documentation and AssetForge documentation. Real-task retrieval, bounded context, cross-session
isolation, stale-state rejection, and rollback to the existing manual index are measured. DFG-8 is
the active gate: allow AssetForge-only proposals through a separate reviewed changeset workflow.
Canonical application remains external and closed to MCP.

## Development

```bash
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.