114 lines
5 KiB
Markdown
114 lines
5 KiB
Markdown
# DocForge
|
|
|
|
DocForge is a project-scoped documentation graph for people and AI agents. It validates canonical
|
|
documentation, builds a disposable search and relationship index, compiles bounded context, renders
|
|
declared manuals, visualizes project structure, and manages reviewable documentation changesets.
|
|
|
|
## What it does
|
|
|
|
- Validates stable Markdown/TOML nodes and typed relationships.
|
|
- Builds a deterministic SQLite search and graph index.
|
|
- Exposes project-bound CLI and MCP query surfaces.
|
|
- Creates, validates, diffs, and previews isolated changesets.
|
|
- Applies one explicitly approved changeset hash through CLI or gated MCP.
|
|
- Supports opt-in incremental adapters with reverse-dependency invalidation and full-build
|
|
equivalence checks.
|
|
- Keeps function-scoped control-flow projections separate from the primary architecture graph.
|
|
- Runs a managed loopback graph browser with neighborhood, semantic Flow, convergence Web,
|
|
source inspection, and branch-aware node hiding.
|
|
- Supports generic documentation projects and project-owned source adapters.
|
|
|
|
DocForge never treats indexed text as instructions. It does not run shell commands, mutate Git,
|
|
build applications, deploy, publish, or select projects globally.
|
|
|
|
## Release 1
|
|
|
|
DocForge 1.0.0 is the first stable product release. It combines the project-scoped graph, CLI and
|
|
MCP query surfaces, reviewable hash-approved changesets, generic and project-owned adapters,
|
|
declared rendering, and the complete Nodes/Flow/Web visualization model in one supported release.
|
|
|
|
The post-1.0 incremental compiler is a backward-compatible, optional enhancement. Existing Release
|
|
1 adapters that implement only `load_projection()` continue to use the original complete-projection
|
|
path without modification. Adapters gain incremental performance only when they additionally
|
|
implement the source manifest and extraction methods. Incremental adapters must retain
|
|
`load_projection()` as their clean-rebuild fallback and equivalence oracle.
|
|
|
|
## Graph views
|
|
|
|
The browser presents the same indexed graph through three complementary views:
|
|
|
|
- **Nodes** shows a bounded, relation-neutral neighborhood around the focus. It is the broad
|
|
inspection view for seeing stored incoming and outgoing relationships without changing their
|
|
direction. Semantic cards distinguish structure, behavior, dependencies, execution, data,
|
|
evidence, context, and other relationships.
|
|
- **Flow** shows semantic origin-to-destination paths that terminate at the focus. DocForge
|
|
reverses prerequisite-style relationships for presentation, so imports, dependencies, reads,
|
|
inheritance, definitions, and tests flow toward the thing they help create or exercise.
|
|
- **Web** shows the larger convergence picture: Flow contributors plus contextual relationships,
|
|
callers, containers, and direct members or execution dependencies owned by the focus.
|
|
|
|
Graph cards show the node's readable leaf name and kind without clipping either value. The full
|
|
qualified identity remains available in the tooltip, compact descriptor, and full inspector.
|
|
|
|
**Hide node** removes noise without changing the index. In Flow and Web, hiding a contributor also
|
|
removes upstream ancestors that no longer have a path to the focus. Nodes between the hidden
|
|
contributor and the focus stay visible, and alternate ancestor paths remain intact. **Restore
|
|
hidden** restores the presentation.
|
|
|
|
## Five-minute start
|
|
|
|
Requirements are Python 3.12+, `uv`, and Node.js/npm.
|
|
|
|
```bash
|
|
git clone forgejo@repo.andraxion.net:administrator/DocForge.git /absolute/path/DocForge
|
|
cd /absolute/path/DocForge
|
|
uv sync --group dev
|
|
npm ci
|
|
|
|
PROJECT=/absolute/path/MyProject
|
|
.venv/bin/docforge --project-root "$PROJECT" validate
|
|
.venv/bin/docforge --project-root "$PROJECT" reindex
|
|
.venv/bin/docforge --project-root "$PROJECT" visualize
|
|
```
|
|
|
|
Install the persistent per-user graph viewer once:
|
|
|
|
```bash
|
|
.venv/bin/docforge-viewer-manager install-user-service
|
|
```
|
|
|
|
Start an MCP server for one project:
|
|
|
|
```bash
|
|
.venv/bin/docforge-mcp \
|
|
--project-root "$PROJECT" \
|
|
--proposal-writer project-editor
|
|
```
|
|
|
|
Add `--canonical-applier project-editor` only when that MCP integration should expose the
|
|
hash-bound `docforge_apply_changeset` tool.
|
|
|
|
## Documentation
|
|
|
|
- [User manual](docs/USER_MANUAL.md) — features, setup, visualization, CLI, MCP, apply, adapters,
|
|
and troubleshooting.
|
|
- [Core contract](docs/CONTRACT.md) — invariants and security boundary.
|
|
- [MCP contract](docs/MCP_CONTRACT.md) — exact tool and process boundary.
|
|
- [Viewer manager](docs/VIEWER_MANAGER.md) — native service setup and lifecycle.
|
|
- [Adapter decision](docs/APPLICATION_DECISION.md) — why custom adapters own canonical
|
|
serialization.
|
|
- [Incremental adapter indexing](docs/INCREMENTAL_INDEXING.md) — source-scoped extraction,
|
|
invalidation, equivalence, relationship changes, and the lazy Logic boundary.
|
|
|
|
## Development
|
|
|
|
```bash
|
|
npx pyright
|
|
npm run lint:web
|
|
uv run ruff check src tests tools
|
|
uv run ruff format --check src tests tools
|
|
uv run python -m compileall -q src tests tools
|
|
uv run pytest -q
|
|
```
|
|
|
|
See [AGENTS.md](AGENTS.md) before changing core boundaries.
|