Discovery — how to explore an md-graph you just arrived in

You have a grant and a token. This page is how to find your way around before you ask anyone anything. Read it once on arrival.

Know your root first

Your token roots your entire world at one node. Every path you use is relative to that root — there is no absolute, whole-graph addressing from where you stand. If you were told "read bejike/eng/platform" but your grant is rooted at bejike/, the path you pass is eng/platform. A path that names your root prefix will not resolve.

Corollary, and a trap worth stating plainly: not_found is ambiguous. It means either "no such node" or "outside your grant" — the two are deliberately indistinguishable (no capability may confirm what exists beyond its scope). So a not_found on arrival is not proof something is missing; it may be one segment past your root. Re-root your path and try again before concluding anything is absent.

Read INDEX-first, descend selectively

The convention everywhere in md-graph: a folder's INDEX.md describes that subtree and names the paths worth fetching. So:

cat INDEX.md at your root. It orients you and points onward.
Follow its pointers; at each folder, read its INDEX.md before listing blindly.
Follow [[wikilinks]] in prose — they are real edges; refs on a node shows what links to and from it.

Descend toward what your task needs; do not read the whole tree. The graph is built to be traversed selectively, not enumerated.

Doctrine vs. implementation

Two kinds of context answer two different questions, and knowing which you're in saves confusion:

Doctrine — "how do we do X org-wide" — lives in the org tree (e.g. an eng/platform/ area holds release/deploy/other patterns every project follows).
Implementation — "how does THIS project do X" — lives with the project (its repo, its own context subtree).

When they seem to conflict, doctrine is the standing rule and the project states its deviations. Read doctrine to learn the pattern; read the project to learn its instance.

Which tool for what

An agent typically has two surfaces onto the same graph. They are not interchangeable:

MCP tools (mdg_ls, mdg_cat, mdg_write, mdg_mkdir, mdg_link, mdg_refs, mdg_facet_* …) — content operations: reading and writing nodes, edges, facets. Paths are grant-root relative. This is your default surface for the work.
The mdg CLI — everything MCP covers plus logistics that MCP does not surface: recency (who acted when — the fleet's liveness), agent who (attachment/lease state), changes (the poll feed), log (revision history with author/origin), grant/ principal/budget administration. Reach for the CLI when you need to see the fleet, the history, or the plumbing — not just content.

If a capability seems missing from your MCP tools, it is probably a logistics verb: use the CLI. Content is MCP; logistics and administration are CLI.

Read first, escalate narrow

Exhaust the graph before you ask a human or another agent. When you genuinely must escalate, escalate the specific gap: the exact path you tried, what you expected, and why the graph didn't answer — not "I need help with X." A narrow, path-level question is answerable in one reply; a broad one starts a conversation. The goal is that the graph answered you and no one had to.