94 lines
5.6 KiB
Markdown
94 lines
5.6 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 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 primary focus, outgoing children, and edge/context nodes, with distinct palettes and
|
|
progressive hop-distance shading.
|
|
|
|
## 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
|
|
pyright
|
|
uv run ruff check src tests
|
|
uv run ruff format --check src tests
|
|
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 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.
|