How the graph gets built

Layers

The graft map is built in layers. Tier 1 is tree-sitter: every symbol and call edge, no model, no key. trail build --deep adds two language-model passes on top:

Read each file. Every source file is summarized once into a short description of what it does.
Group into nodes. Those summaries are grouped into a curated set of nodes (subsystems, key files, and concepts) with typed links between them. The graft map chooses the right level of detail for you instead of making one node per file, so a big repo becomes a few dozen readable nodes.

Source files flow into Tier 1 tree-sitter (no model, no key), which produces graft/.graph/wiring.json, the per-symbol code graph. With –deep, Pass 1 has an LLM summarize each file, and Pass 2 groups them into nodes with typed links, producing graft/*.md, the markdown node graph.

The code graph

Alongside the markdown graph, trail build builds graft/.graph/wiring.json (a per-symbol code graph) plus a per-file wiring card mirroring your source tree.

Tier	What it produces	Requires
Tier 1 (tree-sitter)	Every function, class, and call edge; deterministic	No model, no network, no key
`--deep` (LLM)	A one-line summary and a crux excerpt per symbol, cached by body hash	Your provider key

Caching

Every pass is cached by content hash, the LLM ones and the tree-sitter parse alike. Re-running only touches the files that changed, so the second build is fast and cheap. On the Trail-code repo itself, 312 files:

Scenario	Time
Cold build	about 5s
One edited file, or nothing changed	about 0.6s

trail build --no-reuse forces a cold re-parse.

Every query refreshes first

That cheapness is what lets every query refresh the graph before it answers. A retrieval call stats the tree against the last build’s fingerprint (about 50ms on the Trail-code repo), and rebuilds only if something moved, so ask/grep/callers/skeleton/map describe the code as it is right now, including edits that are unsaved to git: uncommitted, unstaged, or staged all look the same to the graft map.

Git determines the visible file set; freshness compares the working-tree bytes rather than commit or index state.