Graph structure

Files under graft/

Path	What it holds
graft/*.md	The markdown node graph, linked nodes your agent opens and greps like any other file
graft/.graph/wiring.json	The per-symbol code graph
Per-file wiring cards	A per-file wiring card mirroring your source tree
graft/workspace.json	In a folder of separate repos, the parent’s index of child graphs

graft/ is a local cache like node_modules and is added to .gitignore.

What’s in a node

A node is a single markdown file. Most code maps stop at an address: this thing lives in that file, on that line. That tells an agent where to look, not what it will find, so it still has to open the source and read. A graft map node holds the meaning inline, so the agent learns what it needs up front and opens the file only when it wants more.

Part	What it holds
Summary	A plain-English explanation of what the code does, written by the model and cached. It is there whether or not the code was ever documented, and it is regenerated when the source changes.
Crux	The handful of lines that actually carry the logic: the guard, the skip condition, the state change. Lifted straight from the source and stored inline, so the agent sees how it works, not just what.
Sources	The exact files the node is built from, each tracked by a content hash, so the graft map can tell precisely when a node has gone stale.
Links	Typed connections to other nodes (depends_on, part_of, uses, implements, produces), written as [[wikilinks]] your agent can follow.
Your text	Anything you write below the generated block. It is preserved across regenerations, so your own context is never overwritten.

That is three depths in one file: the summary says what the code does, the crux shows how, and the sources point to the rest if the agent needs it. A plain index makes it read a whole file to learn one thing. A graft map node hands it the answer inline, and the follow-up read often never happens.

The crux is stored as the code itself, not as a line range, on purpose. Line numbers drift whenever unrelated code above them shifts, but the lines that matter do not. Keeping the text, not the numbers, means the crux stays correct even as the file around it moves.

Note

Summary, sources, links, and your text ship today in markdown nodes. The crux ships per-symbol in the code graph (trail build --deep); inlining it into markdown nodes is next.

Edge verbs

Edges speak the code’s language. Every link is one of a closed set of verbs, each answering a question someone building or reviewing code actually asks:

Verb	The question it answers
part_of / contains	where does this live?
uses / calls / imports / depends_on	what breaks if I change this?
produces	where does this output come from?
configures	what changes its behavior without a code change?
validates	what checks or judges this? (tests, drift checks, scoring)
extends / implements	what contract must this honor?
references	what names this without calling it? (drawn as faint dots in the viewer)