54 lines
3 KiB
Markdown
54 lines
3 KiB
Markdown
# 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-8 are complete. Worldforge uses separate read-only sessions and an optional
|
|
AssetForge-only proposal process. OpenClaw can update 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 is the active gate: decide from recorded
|
|
evidence whether any developer-only application command is justified. 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.
|
|
|
|
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.
|