diff --git a/.gitignore b/.gitignore
index f4401f1..6e8cda1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -48,3 +48,6 @@ app.*.map.json
 **/node_modules/
 **/.next/
 **/dist/
+
+# Graphify code knowledge graph (regenerated locally via git hooks)
+graphify-out/
diff --git a/CLAUDE.md b/CLAUDE.md
index f81a0dc..c5e0722 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -64,6 +64,29 @@ See `backend/CLAUDE.md` for the Next.js app commands (`npm run dev/build/lint`),
 
 `backend/` contains real client business data committed to source (SKU/vendor/customer master data, scanned DO photos, hand-labeled ground truth) — see `backend/CLAUDE.md`'s Confidentiality section before exporting, logging, or sharing anything from `backend/sources/` or `backend/uploads/`.
 
+## Code structure queries (Graphify)
+
+An AST-derived knowledge graph of this repo lives in `graphify-out/` (gitignored;
+rebuilt automatically by `.git/hooks/post-commit`/`post-checkout`). It is pure
+tree-sitter AST + local graph algorithms — no LLM/API key involved (clustering was
+run with `--no-label` to skip the optional LLM community-naming step).
+
+- **Prefer it for structural/relationship questions** — "what calls X", "what
+  breaks if Y is renamed", "where is Z used" — via `graphify query "..."` /
+  `graphify explain "X"` / `graphify affected "X"` against `graphify-out/graph.json`.
+  These return a small, token-budgeted slice of the graph, which is usually cheaper
+  than Grep-then-Read across several files for broad/architectural questions.
+- **Still Read the actual file** before editing it, or whenever the question
+  depends on exact logic/values — the graph captures structure (nodes/edges/call
+  relationships), not full source text.
+- Not wired in automatically: the global skill+hook (`graphify install --platform
+  claude`) that would nudge every Claude Code session toward the graph is
+  deliberately not installed — it would write into `~/.claude/skills/`, which
+  auto-loads as instructions across *all* future sessions/projects, sourced from a
+  third-party pip package. Using the graph here is a deliberate per-task choice.
+- `graphify.exe` is not on PATH (Windows user pip install) — invoke via full path
+  `%APPDATA%\Roaming\Python\Python312\Scripts\graphify.exe` or add that dir to PATH.
+
 ## Agents Settings Kit
 
 @AGENTS.md