DocForge2/README.md

DocForge

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 graph/search index, and returns bounded context with source provenance.

The canonical manual remains the project’s source of truth. DocForge does not apply canonical changes, select project work, run project commands, commit, push, deploy, or publish. It may write only configured derived output and isolated proposal previews through explicit boundaries.

This README is the complete setup and command reference. docs/NEW_PROJECT_QUICKSTART.md is kept only as a compatibility link for existing bookmarks.

What DocForge provides

• A project-bound CLI for validation, indexing, graph queries, context, and declared renders.
• A stdio MCP server with a fixed, project-scoped read surface.
• Optional isolated documentation proposal changesets. Canonical application stays in the owning project’s normal editing and review workflow.
• 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.

The generic adapter reads only declared Markdown and TOML nodes. It does not infer application modules, functions, calls, routes, tables, tests, or ownership. Projects that need those facts provide a deterministic, project-owned source adapter.

Install and verify

Requirements: Python 3.12+, uv, and Node/npm for browser-asset validation. Install Pyright once globally.

git clone forgejo@repo.andraxion.net:administrator/DocForge.git /absolute/path/DocForge
cd /absolute/path/DocForge
uv sync
npm ci
npm install -g pyright

pyright --pythonpath .venv/bin/python
npm run lint:web
uv run ruff check src tests tools
uv run ruff format --check src tests tools
uv run python -m unittest discover -s tests -v

npm run lint:web validates the exact HTML, CSS, and JavaScript served by the graph browser, plus a freshly rendered fixture manual.

Connect a generic project

1. Create the project descriptor

Create /absolute/path/MyProject/.docforge/project.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 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:

+++
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:

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

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:

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:

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.

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:

{
  "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:

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:

docforge-viewer-manager install-user-service

Its lifecycle commands are:

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:

{
  "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:

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