diff --git a/.gitignore b/.gitignore
index 6cf19827..cb424128 100644
--- a/.gitignore
+++ b/.gitignore
@@ -180,5 +180,8 @@ src/SupportingFiles/Booket/GoogleService-Info.plist
 # Performance traces and local probe workspace (large, generated)
 .perf/
 
+# CodeGraph local index (generated, per-working-tree SQLite data)
+.codegraph/
+
 # Claude Code scheduled-task runtime lock (per-machine, not shared)
 .claude/scheduled_tasks.lock
diff --git a/AGENTS.md b/AGENTS.md
index 14885ed0..c7f208fb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -107,6 +107,26 @@ If a referenced doc is missing, ask before assuming its contents.
 
 ---
 
+## Repository intelligence
+
+When CodeGraph is available, use it for broad repository exploration, symbol
+relationship discovery, and impact analysis before falling back to wide
+`rg`/file-reading sweeps.
+
+Use this workflow:
+
+- For architecture or unfamiliar-area questions, start with CodeGraph
+  `context`, `query`, `impact`, `callers`, or `callees`.
+- For exact literal searches, narrow symbol lookups, and final evidence, use
+  `rg` and direct file reads.
+- If CodeGraph reports stale or pending files, verify those files directly
+  before relying on the indexed result.
+- Do not commit `.codegraph/`; it is a generated local SQLite index. Regenerate
+  it with `codegraph init -i` when missing, and use `codegraph sync` only when
+  working outside an active MCP watcher or after a branch switch / batch edit.
+
+---
+
 ## Architecture guardrails
 
 ### Feature structure