DocForge2/README.md

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

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

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

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