75 lines
2.5 KiB
Markdown
75 lines
2.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.
|
|
- 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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|