## Code Graph First (mandatory)

Before any cross-file understanding or change, query the code graph first. Do
NOT grep + read whole files to reconstruct relationships.

- **Session start**: run `codegraph_status` to confirm the graph is built; if
  empty, run `codegraph init -i` from the project root once. The graph persists
  and is reused for the whole session.
- **Trust but verify stats**: `codegraph_status` can return a stale or partial
  snapshot. If counts look low, run `codegraph_status` again — codegraph
  auto-syncs on file changes (2s debounce via native OS file watcher).
  Do not run structural queries against a graph you suspect is incomplete.
- **Structural questions** ("who calls / what depends on / where defined / what
  breaks if I change this") MUST use `codegraph_explore` (primary, for flows and
  surveys), `codegraph_search` (locate symbols), `codegraph_callers` (every call
  site).
  Do not piece relationships together from grep + read output.
- **Reading an implementation**: use `read(filePath, symbol: "<name>")` to fetch
  only the target symbol's line range. Do not read an entire large file to see
  one function.
- **grep is the fallback, not the default**: use grep only for fuzzy text the
  graph cannot answer (comments, string literals, config text). Use
  `codegraph_node` with `symbolsOnly: true` for a cheap structural overview instead of Glob.
- **Delegate exploration**: prefer running graph + read inside an Explorer
  subagent and returning only `file:line` results and conclusions, to keep the
  main context lean.

## Per-worktree indexes (mandatory for worktree sessions)

The main checkout's `.codegraph/` indexes ONLY that tree. A git worktree lives
outside the repo path, so nearest-`.codegraph/` resolution finds nothing under
it — graph queries in a workflow worktree silently degrade to grep+read
(the [org-internal #2561] / TD-006 gap).

- `script/session-worktree.sh create` and `script/scratch-worktree.sh create`
  build a per-worktree index automatically: `codegraph init -i <path>` runs in
  the background (best-effort — missing CLI, existing index, or init failure
  never blocks worktree creation). Set `CODEGRAPH_SKIP=1` to disable
  (selftests / CI).
- Worktrees created BEFORE this hook landed have no index: run
  `codegraph init -i` once from inside them.
- First query after creating a worktree may hit a still-building index; if
  results look empty, check `codegraph status` inside the worktree, then retry.
- Kickoff readiness (`checkCodegraph`) checks `<root>/.codegraph/codegraph.db`
  per root, and `codegraph serve --mcp` resolves from the session's cwd — both
  pick the worktree's own index once it exists.