# Typed Graph Agent Playbook

Decantr's typed graph gives AI coding assistants a queryable model of the product contract, current route context, evidence, and repair surface. Use it when an agent needs structured context instead of prose-heavy markdown packs.

## Operating Model

The graph is local to the app and generated by:

```bash
decantr graph --project apps/web
```

That command writes:

- `.decantr/graph/graph.snapshot.json`
- `.decantr/graph/snapshots/<snapshot-id>.json`
- `.decantr/graph/graph.manifest.json`
- `.decantr/graph/graph.diff.json`
- `.decantr/graph/contract-capsule.json`

The Contract capsule is the cache-friendly session artifact. Route context and impact context are follow-up reads against the snapshot.

## Default Agent Flow

1. Call `decantr_get_project_state`.
2. If graph artifacts are ready, call `decantr_get_contract_capsule` near session start; its bounded `source_artifacts` list shows project-relative file paths that can be used as `file_path` handles in graph tools. If `source_artifacts_truncated` is true, use `decantr_get_project_state` or graph queries for narrower source-file discovery.
3. Before route work, call `decantr_get_graph_snapshot` with `route` and `task`.
4. Before changing a shared node or known source file, call `decantr_query_graph` with `node_ids` or `file_path` and `include_impact: true`.
5. For an already-dirty workspace, read `decantr_prepare_task_context`; its typed graph block includes changed-file impact when git changed files map to SourceArtifact nodes.
6. After edits, run `decantr verify` or `decantr ci --project apps/web --fail-on error`.

Evidence Bundles include provenance for the graph snapshot, manifest, diff, and contract capsule. Treat a missing provenance entry with `present: false` as "the graph has not been generated for this repair loop yet," and treat changed graph hashes as a reason to refresh graph context before applying a repair.

## Route Context

Use route context when the task is page-scoped:

```json
{
  "project_path": "apps/web",
  "route": "/feed",
  "task": "improve recipe card loading"
}
```

The response returns the route, page, shell, composed patterns, components, tokens, local rules, style bridge mappings, findings, evidence, provenance, and ranked nodes boosted by the task text.

CLI equivalent:

```bash
decantr graph --project apps/web --route /feed --task "improve recipe card loading" --json
```

## Impact Context

Use impact context when the task touches a shared component, token, rule, finding, or source artifact:

```json
{
  "project_path": "apps/web",
  "node_id": "cmp:button",
  "task": "change button disabled styling"
}
```

When the agent knows a source path but not the internal graph node ID, pass `file_path`; Decantr resolves it to the matching `SourceArtifact` node:

```json
{
  "project_path": "apps/web",
  "file_path": "src/app/page.tsx",
  "task": "edit page source"
}
```

For query-first workflows, use the same impact extractor through `decantr_query_graph`:

```json
{
  "project_path": "apps/web",
  "node_ids": ["cmp:button"],
  "include_impact": true,
  "task": "change button disabled styling"
}
```

```json
{
  "project_path": "apps/web",
  "file_path": "src/app/page.tsx",
  "include_impact": true,
  "task": "edit page source"
}
```

The response answers graph-shaped blast-radius questions: affected routes, pages, patterns, components, tokens, local rules, findings, evidence, repairs, and source artifacts.

Use traversal when the agent needs a precise relation walk instead of a ranked impact subgraph. For example, this returns graph nodes that point at a route implementation file:

```json
{
  "project_path": "apps/web",
  "file_path": "src/app/page.tsx",
  "direction": "in",
  "relations": ["NODE_DERIVED_FROM_SOURCE"]
}
```

CLI equivalent:

```bash
decantr graph --project apps/web --node cmp:button --impact --task "change button disabled styling" --json
decantr graph --project apps/web --file src/app/page.tsx --impact --task "edit page source" --json
```

## Historical Reads

Use `snapshot_id` to query a previous graph reality:

```json
{
  "project_path": "apps/web",
  "snapshot_id": "graph:previous",
  "route": "/feed"
}
```

Use `compare_to` when the agent needs the diff between snapshots:

```json
{
  "project_path": "apps/web",
  "compare_to": "graph:previous",
  "include_diff_ops": true,
  "limit": 50
}
```

This is the temporal foundation for proving whether an AI edit introduced, resolved, or moved drift.

## Repair Plans

When Project Health findings have graph anchors, `decantr_get_repair_plan` includes the anchor and an impact context for the anchored node. Agents should use that impact context to preserve adjacent routes, components, tokens, local rules, and evidence while applying the typed repair action.