administrator/DocForge2
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions Pages

Consolidate DocForge setup and command reference

Browse source
This commit is contained in:
Andraxion 2026-07-25 01:16:05 -04:00
parent e405326334
commit 3c15e26283
4 changed files with 337 additions and 445 deletions
Download patch file Download diff file Expand all files Collapse all files

412
README.md
View file

@ -1,108 +1,356 @@
# DocForge # DocForge
DocForge is a project-scoped documentation service for people and AI agents. It loads canonical DocForge is a project-scoped documentation service for people and AI agents. It reads canonical
Markdown and TOML from one repository, validates stable nodes and relationships, builds a disposable Markdown and TOML from one repository, validates stable nodes and relationships, builds a
search index, and returns bounded context with source provenance. disposable graph/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 The canonical manual remains the project’s source of truth. DocForge does not apply canonical
commands, or perform Git and deployment operations. It may write only configured derived output and changes, select project work, run project commands, commit, push, deploy, or publish. It may write
isolated previews through the explicit render boundary. only configured derived output and isolated proposal previews through explicit boundaries.
## Current state This README is the complete setup and command reference. `docs/NEW_PROJECT_QUICKSTART.md` is kept
only as a compatibility link for existing bookmarks.
DFG-0 through DFG-14 are complete. Worldforge uses separate read-only sessions and an optional ## What DocForge provides
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 - A project-bound CLI for validation, indexing, graph queries, context, and declared renders.
derived index, then starts a token-protected read-only graph browser on `127.0.0.1`. The browser - A stdio MCP server with a fixed, project-scoped read surface.
supports project counts, family filtering, lexical search, exact node inspection, and bounded - Optional isolated documentation proposal changesets. Canonical application stays in the owning
incoming-and-outgoing neighborhoods. It accepts no project path, database path, SQL, external bind project’s normal editing and review workflow.
address, or write operation. - A loopback-only graph browser with a native per-user viewer manager.
- A generic manual adapter and a contract for project-owned source-code adapters.
DFG-11 upgrades the fixed browser template with pointer-centered mouse-wheel zoom, left-button drag The generic adapter reads only declared Markdown and TOML nodes. It does not infer application
pan, zoom buttons, a reset control, and a live zoom percentage. These controls operate only on the modules, functions, calls, routes, tables, tests, or ownership. Projects that need those facts
client-side SVG viewport and do not broaden the read-only HTTP or project authority boundary. provide a deterministic, project-owned source adapter.
DFG-12 makes graph-node activation open a modal inspector without replacing the current ## Install and verify
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 Requirements: Python 3.12+, [`uv`](https://docs.astral.sh/uv/), and Node/npm for browser-asset
crosses the movement threshold. It also ensures the empty-canvas instruction disappears whenever a validation. Install Pyright once globally.
neighborhood is rendered.
DFG-14 makes the viewer useful as a durable project-manual navigator. 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.
DFG-18 makes the viewer a managed project-bound local service. A native per-user supervisor owns
the viewer manager, which survives MCP process turnover, reuses the current snapshot URL, exposes
status and explicit stop tools, and reclaims only genuinely idle workers.
## 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 ```bash
git clone forgejo@repo.andraxion.net:administrator/DocForge.git /absolute/path/DocForge
cd /absolute/path/DocForge
uv sync uv sync
npm ci npm ci
pyright npm install -g pyright
pyright --pythonpath .venv/bin/python
npm run lint:web npm run lint:web
uv run ruff check src tests tools uv run ruff check src tests tools
uv run ruff format --check src tests tools uv run ruff format --check src tests tools
uv run python -m unittest discover -s tests -v 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 `npm run lint:web` validates the exact HTML, CSS, and JavaScript served by the graph browser, plus
renders the fixture manual into a temporary project and validates that final HTML document. a freshly rendered fixture manual.
The command prints deterministic JSON. Derived indexes live under each project's configured cache ## Connect a generic project
directory and are never canonical input.
Proposal writers are declared by ID in `.docforge/project.toml`. Each writer receives explicit node ### 1. Create the project descriptor
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 Create `/absolute/path/MyProject/.docforge/project.toml`:
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`. ```toml
`AdapterProject` validates the projection and exposes it through the same disposable index used by schema_version = 1
generic projects. Project-specific context, query ordering, and render-model policy remain in the project_id = "my-project"
adapter. Shadow adapters are local integration tools; the normal MCP server does not discover or title = "My Project"
execute them. An explicit integration may bind a validated adapter project to DocForge's read-only adapter = "generic"
MCP surface without enabling proposal tools.
Proposal-enabled adapters supply confined project settings and a project-owned validator. The core [sources]
still owns hashes, permissions, changeset storage, conflict checks, graph validation, diffs, and content_roots = ["Docs/Manual"]
preview confinement. The adapter owns source-format rules and may only narrow the allowed proposal authority_files = []
surface.
Both generic and explicit adapter MCP servers expose the same visualization tools because they read [derived]
the validated `ProjectIndex` supplied by the project binding. `docforge_visualize` reuses its cache_root = ".docforge/cache"
unguessable loopback URL when the current snapshot remains valid, or replaces the worker after a index = ".docforge/cache/index.sqlite3"
complete index check when it does not. The per-user viewer manager retains active workers across
MCP process turnover, reports state through `docforge_visualization_status`, and reclaims idle
workers after one hour. See [`docs/VIEWER_MANAGER.md`](docs/VIEWER_MANAGER.md) for installation.
See [`docs/NEW_PROJECT_QUICKSTART.md`](docs/NEW_PROJECT_QUICKSTART.md) for a complete generic MCP [changesets]
setup, continuous-agent policy, visualization instructions, and a project-adapter checklist. root = ".docforge/changesets"
[[changesets.writers]]
id = "project-editor"
families = ["architecture", "core", "system", "function", "operations", "roadmap"]
operations = ["create", "update", "move", "delete"]
[graph]
allowed_relations = ["depends_on", "owns", "calls", "reads", "writes", "tested_by", "relates_to"]
[limits]
max_source_bytes = 500000
max_nodes = 10000
max_query_chars = 500
max_results = 100
max_traversal_depth = 6
max_context_tokens = 12000
max_changesets = 100
max_changeset_operations = 100
max_changeset_bytes = 1000000
[[profiles]]
id = "development"
families = ["architecture", "core", "system", "function", "operations", "roadmap"]
statuses = ["current", "active", "open", "verified"]
required_nodes = ["architecture.overview"]
token_budget = 8000
dependency_depth = 3
```
Choose only family names, relations, limits, and required root nodes that the actual project can
support truthfully.
### 2. Add canonical nodes
Create `/absolute/path/MyProject/Docs/Manual/architecture-overview.md`:
```markdown
+++
schema_version = 1
id = "architecture.overview"
title = "Architecture overview"
family = "architecture"
authority = "authoritative"
status = "current"
tags = ["architecture", "ownership"]
summary = "Defines the top-level systems and ownership boundaries."
+++
# Architecture overview
Describe the project’s core authorities, system boundaries, persistence owners, runtime flow,
failure behavior, tests, and operational entry points.
```
Every node needs a stable, unique `id`. Declare relationships in the same front matter:
```toml
depends_on = ["core.database"]
calls = ["system.metadata"]
tested_by = ["function.test-metadata-publication"]
```
Targets must already exist in the graph. Keep each node focused enough that an agent can retrieve
relevant facts without loading the entire manual.
### 3. Build and check the derived graph
```bash
DOCFORGE=/absolute/path/DocForge/.venv/bin/docforge
PROJECT=/absolute/path/MyProject
"$DOCFORGE" --project-root "$PROJECT" validate
"$DOCFORGE" --project-root "$PROJECT" build
"$DOCFORGE" --project-root "$PROJECT" check
"$DOCFORGE" --project-root "$PROJECT" context development
```
`build` creates the disposable SQLite index in the configured cache path. Canonical Markdown and
TOML remain authoritative. Rebuild after canonical documentation changes. A stale or altered index
fails closed.
## CLI command reference
Every command emits deterministic JSON and begins with:
```bash
docforge --project-root /absolute/path/MyProject <command>
```
| Command | Purpose |
| --- | --- |
| `info` | Report the bound project and descriptor facts. |
| `validate` | Validate the descriptor and canonical source graph. |
| `build` | Build the disposable index. |
| `check` | Validate source and confirm the index matches it. |
| `validate-index` | Validate the existing derived index’s schema and identity. |
| `show NODE_ID` | Return one complete node. |
| `search QUERY [--limit N]` | Lexically search nodes. |
| `filter [--family X] [--authority X] [--status X] [--tag X] [--limit N]` | Filter nodes by declared fields. |
| `backlinks NODE_ID [--relation RELATION]` | Return incoming relationships. |
| `dependencies NODE_ID [--depth N]` | Traverse declared dependencies. |
| `impact NODE_ID [--depth N]` | Traverse likely downstream impact. |
| `context PROFILE [--budget N]` | Return bounded, cited context for one configured profile. |
| `render-status [VIEW_ID]` | Report declared render output state. |
| `render VIEW_ID` | Generate one configured canonical render output. |
| `preview CHANGESET_ID VIEW_ID` | Render one isolated changeset preview. |
Examples:
```bash
docforge --project-root "$PROJECT" show architecture.overview
docforge --project-root "$PROJECT" search metadata --limit 20
docforge --project-root "$PROJECT" filter --family system --status current
docforge --project-root "$PROJECT" backlinks system.metadata --relation calls
docforge --project-root "$PROJECT" dependencies system.metadata --depth 3
docforge --project-root "$PROJECT" impact system.metadata --depth 3
docforge --project-root "$PROJECT" render-status manual
docforge --project-root "$PROJECT" render manual
```
## MCP server
Run one MCP server per project. Use absolute paths.
```bash
docforge-mcp --project-root /absolute/path/MyProject --proposal-writer project-editor
```
Omit `--proposal-writer` for a read-only integration. The writer value is a configured writer ID,
not a shell command.
For an MCP client that uses JSON configuration:
```json
{
"mcpServers": {
"my-project-docforge": {
"command": "/absolute/path/DocForge/.venv/bin/docforge-mcp",
"args": [
"--project-root",
"/absolute/path/MyProject",
"--proposal-writer",
"project-editor"
]
}
}
}
```
### Fixed read tools
| MCP tool | Purpose |
| --- | --- |
| `docforge_project_info` | Project identity, index health, and capabilities. |
| `docforge_get_contract` | Bound project contract and excluded operations. |
| `docforge_get_node` | One exact node with full validated content. |
| `docforge_search` | Lexical node search. |
| `docforge_filter_nodes` | Filter by family, authority, status, or tag. |
| `docforge_backlinks` | Incoming graph relationships. |
| `docforge_dependencies` | Declared dependency traversal. |
| `docforge_impact` | Downstream impact traversal. |
| `docforge_get_context` | Bounded, cited context for a configured profile. |
| `docforge_validate_project` | Validate source and derived index state. |
| `docforge_render_status` | Declared render-output state. |
| `docforge_visualize` | Start or reuse the project’s managed, read-only graph viewer. |
| `docforge_visualization_status` | Viewer state, URL, and lifecycle information. |
| `docforge_stop_visualization` | Explicitly stop the project viewer. |
When a proposal writer is configured, the server additionally exposes:
```text
docforge_create_changeset
docforge_list_changesets
docforge_get_changeset
docforge_propose_node_create
docforge_propose_node_update
docforge_propose_node_move
docforge_propose_node_delete
docforge_validate_changeset
docforge_get_changeset_diff
docforge_preview_changeset
```
MCP proposals write only isolated changesets. Review the diff, apply the approved text through the
project’s normal workflow, then run `validate`, `build`, and `check`.
## Managed graph viewer
Install the per-user manager once:
```bash
docforge-viewer-manager install-user-service
```
Its lifecycle commands are:
```bash
docforge-viewer-manager serve
docforge-viewer-manager uninstall-user-service
```
The native supervisor is systemd on Linux, a LaunchAgent on macOS, and Task Scheduler on Windows.
The manager owns one loopback-only viewer worker per project snapshot. `docforge_visualize` starts
or reuses it. Active browser requests renew its one-hour idle timeout. Stop it explicitly through
`docforge_stop_visualization` when it is no longer wanted.
The viewer is read-only, token-protected, and bound to `127.0.0.1`. It shows both:
- **Nodes:** the bounded local graph with original stored relationship direction.
- **Flow:** the complete bounded directed ancestry of the selected node. It follows every incoming
stored edge recursively, preserving `source → target`; it does not infer or reverse arrows based
on relationship names.
## Project-owned source adapters
Use the generic adapter when a declared manual graph is sufficient. Build a project-owned adapter
when the graph must include source files, modules, functions, routes, tables, tests, or other
code-derived facts.
An adapter must:
1. Read source as data. Never import or execute the application to discover facts.
2. Use a deterministic, project-confined source set. For Git repositories, start with
`git ls-files` and exclude generated output, caches, secrets, and binaries.
3. Emit only evidence-backed nodes and edges with stable IDs, safe relative anchors, and hashes.
4. Sort nodes, edges, and metadata deterministically.
5. Return one immutable `AdapterProjection` through `AdapterLoader.load_projection()`.
6. Keep its cache within the project and build/check through `ProjectIndex`.
7. Bind the projection to `create_read_only_server()` unless an explicit proposal policy exists.
8. Reject proposal operations against derived nodes and adapter-created edges.
The project owns its adapter and launches it rather than generic `docforge-mcp`:
```json
{
"mcpServers": {
"my-project-docforge": {
"command": "/absolute/path/MyProject/.venv/bin/python",
"args": [
"-m",
"docforge_adapter.server",
"serve",
"--project-root",
"/absolute/path/MyProject"
]
}
}
}
```
Require deterministic build, staleness, malformed-input, project-isolation, MCP-protocol, and
project full-gate tests before relying on an adapter.
## Agent policy
Add a project-specific version of this to `AGENTS.md`:
```markdown
## Canonical documentation and DocForge
- `/Docs/Manual/` is the canonical systems manual and architecture source of truth.
- Before a systems-level, persistence, API, worker, plugin, operational, or mainline change, call
`docforge_project_info` or `docforge_validate_project`, then retrieve relevant nodes with
`docforge_search`, `docforge_get_context`, or `docforge_get_node`.
- Inspect dependencies, backlinks, and impact at ownership boundaries. Read implementation and
tests as well as the manual. Treat a code/manual disagreement as a defect.
- After implementation, create and validate an isolated DocForge changeset. Review its diff.
- Apply approved text through the normal editing workflow, then run `validate`, `build`, and
`check`. Do not commit derived caches, changesets, or previews unless the project explicitly says
otherwise.
- When asked to visualize a project or node, call `docforge_visualize`.
```
## Normal development loop
1. Validate the DocForge project.
2. Retrieve relevant context, backlinks, dependencies, and impact.
3. Inspect the corresponding implementation and tests.
4. Implement and test the change.
5. Create and validate a DocForge proposal when manual changes are needed.
6. Review the proposal diff and apply approved text through the normal project workflow.
7. Run `validate`, `build`, and `check`.
8. Run the project’s complete test gate.
9. Commit code, tests, and canonical manual updates together.
DocForge never applies, commits, pushes, builds, deploys, or publishes on the project’s behalf.

2
docs/CONTRACT.md
View file

@ -106,7 +106,7 @@ incoming-and-outgoing neighborhoods. Descriptor filtering accepts only
family, authority, status, or tag plus one exact value. There is no write endpoint, arbitrary query family, authority, status, or tag plus one exact value. There is no write endpoint, arbitrary query
endpoint, static filesystem handler, external asset, or project-selection control. endpoint, static filesystem handler, external asset, or project-selection control.
The `graph-browser@8` template provides mouse-wheel zoom centered on the pointer, left-button drag The `graph-browser@11` template provides mouse-wheel zoom centered on the pointer, left-button drag
pan, explicit zoom-in and zoom-out buttons, a reset-view button, and a live zoom percentage. A pan, explicit zoom-in and zoom-out buttons, a reset-view button, and a live zoom percentage. A
four-pixel drag threshold defers pointer capture and preserves node activation for ordinary clicks. four-pixel drag threshold defers pointer capture and preserves node activation for ordinary clicks.
Loading another root node fits the viewport to the returned neighborhood, including a useful Loading another root node fits the viewport to the returned neighborhood, including a useful

2
docs/MCP_CONTRACT.md
View file

@ -63,7 +63,7 @@ only through the explicit local CLI integration command.
## Visualization boundary ## Visualization boundary
`docforge_visualize` starts the fixed built-in `graph-browser@8` template against the currently `docforge_visualize` starts the fixed built-in `graph-browser@11` template against the currently
validated derived index. It may focus one stable node, run one bounded lexical query, or open the validated derived index. It may focus one stable node, run one bounded lexical query, or open the
project overview. The tool returns a loopback URL and exact snapshot identity. project overview. The tool returns a loopback URL and exact snapshot identity.

366
docs/NEW_PROJECT_QUICKSTART.md
View file

@ -1,363 +1,7 @@
# DocForge: New Project Quickstart # DocForge setup moved to the README
This guide connects one project to DocForge so an AI agent can read its documentation graph before The complete installation, project setup, CLI, MCP, viewer-manager, adapter, and agent-policy
development work, propose documentation updates during development, inspect impact, and keep the reference now lives in the [DocForge README](../README.md).
canonical manual synchronized with the code.
DocForge is project-bound. Run one MCP server per project. Its MCP tools can read the validated This file remains only so existing bookmarks and links continue to resolve. Update links to point
graph and write isolated proposals, but they cannot directly edit canonical documentation, run to `README.md`.
builds, use Git, or deploy software. Canonical changes must be applied through the project's normal
editing and review workflow.
## What this installs
The DocForge repository contains the complete generic CLI and stdio MCP server. Launching
`docforge-mcp` as shown below exposes:
- Project identity, validation, exact-node retrieval, lexical search, and filtering.
- Backlinks, dependency traversal, impact traversal, and bounded context profiles.
- `docforge_visualize`, which starts the token-protected, loopback-only `graph-browser@8` viewer.
The viewer supports search, family filtering, exact-node inspection, bounded neighborhoods,
exact descriptor-pill filtering, compact left-click descriptors, full right-click inspection,
fixed search and neighborhood side panels, explicit neighborhood exploration, fitted single- and
multi-node framing, visible node selection, Space-to-center, mouse-wheel zoom, left-button drag
panning, zoom controls, viewport reset, relationship color and symbol keys, and an upstream
lineage Flow view.
- `docforge_stop_visualization`, which explicitly stops the current project's persistent viewer.
- `docforge_visualization_status`, which reports the manager-owned viewer state.
- Isolated documentation changesets, proposal validation, diffs, and escaped HTML previews when a
proposal writer and render view are configured.
The generic adapter graphs the Markdown and TOML nodes and relationships declared by the project.
It does **not** inspect arbitrary source code or automatically infer modules, functions, calls,
routes, database tables, tests, or ownership.
A project that needs automatic source-code graph extraction must provide a project-specific
DocForge adapter. The adapter deterministically projects those code facts into DocForge nodes and
edges, then binds that projection to DocForge's standard index and MCP tools. Ani-web's large code
graph is an example of a custom adapter; it is not behavior supplied by the generic quickstart.
## 1. Install DocForge
Requirements:
- Python 3.12 or newer.
- `uv`.
- Access to the DocForge repository.
```bash
git clone forgejo@repo.andraxion.net:administrator/DocForge.git /absolute/path/DocForge
cd /absolute/path/DocForge
uv sync
uv run python -m unittest discover -s tests -v
```
Use absolute paths in all MCP configuration.
## 2. Configure the project
Create `/absolute/path/MyProject/.docforge/project.toml`:
```toml
schema_version = 1
project_id = "my-project"
title = "My Project"
adapter = "generic"
[sources]
content_roots = ["Docs/Manual"]
authority_files = []
[derived]
cache_root = ".docforge/cache"
index = ".docforge/cache/index.sqlite3"
[changesets]
root = ".docforge/changesets"
[[changesets.writers]]
id = "project-editor"
families = ["architecture", "core", "system", "function", "operations", "roadmap"]
operations = ["create", "update", "move", "delete"]
[graph]
allowed_relations = [
"depends_on",
"owns",
"calls",
"reads",
"writes",
"tested_by",
"relates_to",
]
[limits]
max_source_bytes = 500000
max_nodes = 10000
max_query_chars = 500
max_results = 100
max_traversal_depth = 6
max_context_tokens = 12000
max_changesets = 100
max_changeset_operations = 100
max_changeset_bytes = 1000000
[[profiles]]
id = "development"
families = ["architecture", "core", "system", "function", "operations", "roadmap"]
statuses = ["current", "active", "open", "verified"]
required_nodes = ["architecture.overview"]
token_budget = 8000
dependency_depth = 3
```
Choose family names, relationship names, limits, and the required root node for the actual project.
Do not copy relationships that the project cannot support truthfully.
## 3. Create canonical nodes
Create `/absolute/path/MyProject/Docs/Manual/architecture-overview.md`:
```markdown
+++
schema_version = 1
id = "architecture.overview"
title = "Architecture overview"
family = "architecture"
authority = "authoritative"
status = "current"
tags = ["architecture", "ownership"]
summary = "Defines the top-level systems and ownership boundaries."
+++
# Architecture overview
Describe the project, its core authorities, system boundaries, persistence owners, runtime flow,
failure behavior, tests, and operational entry points.
```
Every node needs a stable, unique `id`. Relationships are declared in the same front matter:
```toml
depends_on = ["core.database"]
calls = ["system.metadata"]
tested_by = ["function.test-metadata-publication"]
```
The relationship target must already exist in the project graph. Keep nodes focused enough that an
agent can retrieve the relevant facts without loading the whole manual.
## 4. Validate and build the graph
```bash
DOCFORGE=/absolute/path/DocForge/.venv/bin/docforge
PROJECT=/absolute/path/MyProject
"$DOCFORGE" --project-root "$PROJECT" validate
"$DOCFORGE" --project-root "$PROJECT" build
"$DOCFORGE" --project-root "$PROJECT" check
"$DOCFORGE" --project-root "$PROJECT" context development
```
`build` creates the disposable SQLite index under `.docforge/cache/`. Canonical Markdown remains the
source of truth. Rebuild after canonical documentation changes. A stale or altered index fails
closed.
## 5. Register the MCP server
Add a project-specific stdio MCP server to the agent host:
```json
{
"mcpServers": {
"my-project-docforge": {
"command": "/absolute/path/DocForge/.venv/bin/docforge-mcp",
"args": [
"--project-root",
"/absolute/path/MyProject",
"--proposal-writer",
"project-editor"
]
}
}
}
```
Restart or reload the agent host. Confirm that it exposes tools beginning with
`docforge_project_info`, `docforge_get_node`, `docforge_search`, `docforge_dependencies`,
`docforge_impact`, `docforge_get_context`, `docforge_visualize`, and
`docforge_stop_visualization`, `docforge_visualization_status`, and `docforge_create_changeset`.
Omit `--proposal-writer` for a read-only integration.
## 5A. Optional source-code adapter
The generic setup above is complete when the project only needs a graph of its declared manual
nodes. Build a project-specific adapter when the graph must also contain source files, modules,
functions, routes, tables, tests, services, plugins, or other facts derived from the codebase.
Tell Codex to keep the adapter inside the owning project, for example:
```text
MyProject/
docforge_adapter/
__init__.py
graph.py # Parse tracked source as data and produce project facts.
integration.py # Translate facts into DocForge nodes, edges, and policy.
server.py # Build, check, report, and serve the bound MCP process.
tests/
test_docforge_adapter.py
```
The adapter must:
1. Read source files as data. It must not import or execute the application to discover facts.
2. Select a deterministic, project-confined source set. A Git project should normally begin with
`git ls-files`; exclude generated manuals, caches, build output, secrets, and binary artifacts.
3. Parse each supported language or format with deterministic parsers. Emit only relationships
backed by direct evidence. Omit uncertain calls, ownership, or persistence edges instead of
guessing.
4. Give every node a stable ID, family, authority, status, summary, safe relative source path,
optional source anchor, and SHA-256 content hash.
5. Give every edge stable source and target IDs, a declared relation, and adapter metadata that
records its evidence and origin.
6. Sort nodes by node ID, edges by source/relation/target, and metadata by key.
7. Implement `AdapterLoader.load_projection()` and return one immutable `AdapterProjection` with a
resolved project root, revision, adapter ID/version, and lowercase SHA-256 source hash.
8. Wrap the loader in `AdapterProject`, place its cache inside the project, and build/check it
through `ProjectIndex`.
9. Bind the project to `create_read_only_server()`. Use `create_project_server()` only after adding
explicit `AdapterProjectSettings`, a startup-bound proposal writer, confined canonical sources,
and a validator that prevents proposals from changing derived source nodes or adapter edges.
10. Supply a project context provider if `docforge_get_context` needs project-specific profiles.
Search, node retrieval, traversal, impact, and visualization work directly from the standard
index.
The essential integration shape is:
```python
from pathlib import Path
from docforge.adapter_contract import AdapterProject
from docforge.index import ProjectIndex
from docforge.mcp_server import create_read_only_server
from .graph import ProjectAdapterLoader
def open_project(root: Path):
loader = ProjectAdapterLoader(root.resolve(strict=True))
project = AdapterProject(
loader,
cache_root=loader.root / ".docforge" / "cache" / "project-adapter",
)
return project, ProjectIndex(project)
def serve(root: Path) -> None:
project, index = open_project(root)
index.check() # Build explicitly before serving; never hide stale state.
create_read_only_server(project).run(transport="stdio")
```
The project-owned `server.py` should provide explicit `build`, `check`, and `serve` operations. The
MCP host then launches that module instead of the generic `docforge-mcp` command:
```json
{
"mcpServers": {
"my-project-docforge": {
"command": "/absolute/path/MyProject/.venv/bin/python",
"args": [
"-m",
"docforge_adapter.server",
"serve",
"--project-root",
"/absolute/path/MyProject"
]
}
}
}
```
If the adapter combines canonical manual nodes with derived code nodes, load the generic manual
through `Project.open(project_root)`, translate its canonical nodes and edges into `AdapterNode` and
`AdapterEdge`, merge them with the derived projection, and reject proposal operations against all
derived node IDs and adapter-created relationships.
Require these adapter acceptance checks:
- Two unchanged builds produce the same ordered nodes, edges, source hash, and projection identity.
- A tracked source change changes the source hash and makes the old index stale.
- Missing targets, duplicate IDs, unsafe paths, unsorted metadata, and invalid hashes fail closed.
- Building the graph does not import the application or cause runtime, network, database, or
filesystem side effects.
- Read-only MCP exposes only the fixed DocForge read surface, including visualization start and
explicit viewer shutdown.
- Proposal-enabled MCP cannot modify derived source facts or write outside confined changeset and
preview roots.
- Build, check, MCP protocol tests, adapter tests, and the owning project's full test gate pass.
### Ready-to-give Codex setup request
```text
Install and configure DocForge for this repository using the new-project quickstart. Use the
generic adapter for the canonical manual, and create a project-owned source adapter if source-code
graph extraction is required. Inspect the repository languages and formats before choosing
parsers. Read tracked source as data; never import or execute the application for discovery.
Produce deterministic, evidence-backed nodes and edges with stable IDs and safe source anchors.
Omit relationships that cannot be proven. Bind one project-scoped MCP server with visualization,
build and check the index explicitly, add adapter contract and staleness tests, and add the supplied
DocForge policy to AGENTS.md. Keep canonical manual writes outside MCP: use isolated proposals,
review their diffs, apply them through the normal project workflow, then rebuild and check the
index. Do not report completion until DocForge validation, adapter tests, MCP protocol checks, and
the project's complete test gate pass.
```
## 6. Tell the agent to use DocForge automatically
Place this policy in the project's `AGENTS.md` and adjust the manual path and profile if needed:
```markdown
## Canonical documentation and DocForge
- `/Docs/Manual/` is the canonical systems manual and architecture source of truth.
- Use the project-bound DocForge MCP server for every systems-level, architectural, persistence,
plugin, worker, API, operational, or mainline change.
- Before editing, call `docforge_project_info` or `docforge_validate_project`. Retrieve the relevant
nodes with `docforge_search`, `docforge_get_context`, or `docforge_get_node`. Inspect dependencies,
backlinks, and impact when changing an owned boundary.
- Read the implementation and tests as well as the manual. Treat a code/manual disagreement as a
defect. Do not silently choose one side.
- During implementation, preserve explicit ownership, inputs, outputs, state writes, failure
behavior, callers, tests, and operational consequences.
- After implementation, create an isolated DocForge changeset. Propose every required manual
update, validate the changeset, and inspect its diff.
- DocForge proposals do not edit canonical files. Apply the reviewed proposal through the project's
normal file-editing workflow, then run DocForge `validate`, `build`, and `check`.
- Commit code, tests, and canonical documentation together. Never commit `.docforge/cache/`,
`.docforge/changesets/`, or previews unless the project explicitly declares otherwise.
- If DocForge reports stale state, missing nodes, invalid edges, or an index mismatch, stop and
repair or rebuild the graph before claiming the work complete.
- When asked to “visualize” the project or a node, call `docforge_visualize`. The viewer is
loopback-only and read-only. Its native per-user manager keeps active pages alive across MCP
transactions, reports state through `docforge_visualization_status`, and reclaims only workers
idle for an hour. See `docs/VIEWER_MANAGER.md` for one-time installation.
```
The policy is what makes DocForge part of normal development rather than an optional lookup tool.
## 7. Normal development loop
1. Validate the DocForge project.
2. Retrieve the relevant context and impact graph.
3. Inspect the corresponding code and tests.
4. Implement and test the change.
5. Create and validate a DocForge proposal.
6. Review the proposal diff.
7. Apply the approved text through normal project editing.
8. Run `validate`, `build`, and `check`.
9. Run the project's complete test gate.
10. Commit code, tests, and canonical manual updates together.
DocForge never applies, commits, pushes, builds, deploys, or publishes on the project's behalf.