diff --git a/.gitignore b/.gitignore
index 6eb84f4..93e32cf 100644
--- a/.gitignore
+++ b/.gitignore
@@ -42,10 +42,18 @@ Thumbs.db
 # AI
 CLAUDE.md
 GEMINI.md
+.gemini/
 .claude/
+.cursor/
+.mcp.json
+opencode.json
+.github/copilot-instructions.md
 
 # Migrations & Plans
 *[mM]igration*.md
 *MIGRATION*.md
 *[pP]lan*.md
-*PLAN*.md
\ No newline at end of file
+*PLAN*.md
+
+# graft's local graph cache — regenerable, not committed (run `graft build`).
+/graft/
diff --git a/.ignore b/.ignore
new file mode 100644
index 0000000..615e581
--- /dev/null
+++ b/.ignore
@@ -0,0 +1,5 @@
+# graft's cards are gitignored but should stay greppable: ripgrep reads
+# .ignore before .gitignore, so this re-admits the tree to search only.
+!graft/
+graft/.cache/
+graft/.graph/
diff --git a/AGENTS.md b/AGENTS.md
index 0d2a378..f9198f2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -270,3 +270,45 @@ GitHub Actions runs `python -m pytest tests/ -v` on Python 3.10–3.12 (CPU). Te
 You will know it is when diffs contain only what was asked for, when reviews
 stop turning into rewrites, and when questions arrive before the work rather
 than after the mistake.
+
+<!-- graft:start -->
+## Graft — repo context graph
+
+This repo is indexed in `graft/`: small linked markdown nodes that explain each
+system and carry exact file:line spans, kept in sync with the code through git.
+
+For ANY task here — understanding how something works, finding where code lives,
+or scoping a change — get context from the graph before grepping or opening
+source files. Re-ask freely (it's cheap) and reuse literal identifiers you
+already have (symbol, error string, file name) as the query. New to this repo?
+Run `graft map` first — a token-budgeted orientation (dir clusters, hubs,
+hotspots), no LLM, no key.
+
+- Run `graft ask "<your question>" --source` → ranked nodes with the relevant
+  code spans inlined (each hit's ≤8-line crux by default; `--full` for whole
+  definitions when the crux isn't enough). Match the tool to the task shape:
+  for understanding or editing, the top node IS the answer — cite its
+  `covers:` file:line spans and edit straight from `--source`. For
+  exhaustive tasks ("every occurrence / every caller of this pattern"), ranked
+  results are top-N, not complete — run `graft grep "<literal>"` instead
+  (exhaustive over indexed files, grouped by enclosing symbol), falling back
+  to raw `grep -rn` only for unindexed files.
+- `graft skeleton <file>` → every definition's signature + span, ~10× cheaper
+  than reading the file; use it to skim an API surface.
+- `graft callers <symbol>` gives precomputed, exact edges — who calls this.
+  Add `--direction out` for what it calls, or `--depth N` to walk
+  transitively for the full blast radius. For structural questions, skip
+  ranking and use this directly.
+- Or browse: `graft/INDEX.md` lists every node; follow the links.
+- Monorepos and folders of multiple repos rank fairly across sub-projects —
+  hits carry `[scope/]` labels naming which one they're from. Narrow with
+  `graft ask "<task>" --in <scope>/` once you know where you're working.
+
+If a returned span is truncated ("+N more lines"), open the file at that exact
+range before finalizing. Only open source files when a node genuinely lacks a
+needed detail, and then at the exact file:line the node points to — never
+re-read whole files.
+
+After big code changes, refresh the graph with `graft build` (deterministic,
+no API key, $0).
+<!-- graft:end -->