Every serious project gets a .navin/metadata/ folder at its root: a machine-readable\nmap of what each file is, what it does, and what it depends on. The Dev\nworkbench renders it as an interactive metagraph (nodes = files, colored by\nnature; edges = dependencies). Your job: build it once, keep it truthful, and\nconsult it before grepping when the user asks \"where is X handled?\".
metagraph toolYou have a dedicated tool named metagraph that builds this graph live\n(parsed imports + your .navin/metadata/index.json annotations). Use it FIRST:
metagraph(action=\"overview\") - file counts by kind, the most connected\nhub files, and whether .navin/metadata/ exists yet.metagraph(action=\"file\", path=\"navin/agent/loop.py\") - one file's kind,\nrole, what it depends on, and what depends on it.metagraph(action=\"find\", query=\"checkpoint\", kind=\"back\") - locate files\nby path fragment, role text, and/or kind\n(front/back/sql/config/test/docs).metagraph(action=\"annotate\", files={...}) - record roles. This is the only\nway to write .navin/metadata/index.json: it merges the entries you pass into\nwhatever is already there, validates them, and stamps each one with the file's\ncurrent size so a later run can tell which roles went stale. Never write that\nfile with write_file - a hand-written entry carries no stamp and is invisible\nto staleness reporting.Reach for grep only when the graph cannot answer (string literals, exact\ncode contents). The tool reads roles from .navin/metadata/index.json, so the\nricher you keep the index, the better find answers become.
.navin/metadata/\n index.json # the knowledge base (format below)\n ARCHITECTURE.md # human-readable summary: layers, entry points, data flow\n{\n \"version\": 1,\n \"updated\": \"2026-07-22T10:00:00Z\",\n \"files\": {\n \"webui/src/App.tsx\": {\n \"kind\": \"front\",\n \"role\": \"Root React component: routing, view state, session wiring\",\n \"depends_on\": [\"webui/src/lib/api.ts\", \"webui/src/components/Sidebar.tsx\"],\n \"tags\": [\"entry\"]\n },\n \"navin/webui/ws_http.py\": {\n \"kind\": \"back\",\n \"role\": \"Gateway HTTP routes: sessions, files, settings, studio APIs\",\n \"depends_on\": [\"navin/webui/file_tree.py\"],\n \"tags\": [\"api\"]\n }\n }\n}\nkind: one of front, back, sql, config, test, docs, asset, other.role: ONE sentence, concrete - what the file does, not what it is named.depends_on: project-relative paths this file imports/reads/calls. The\nbackend already parses Python/JS imports automatically; only list what static\nparsing cannot see (SQL tables used, config files read, templates rendered,\nHTTP endpoints called).tags: optional, short (entry, api, schema, hot-path, deprecated).Init (new or existing project) - when starting work on a project that has\nno .navin/metadata/:
metagraph(action=\"overview\") and read the root and discovery line it\nprints back. A count only means \"the whole project\" if the root is the project\nyou were asked about; when discovery says gitignored files were included, or\nthe file count is far below what you expect from the tree, say so instead of\nreporting coverage as if the map were complete.metagraph(action=\"annotate\", files={...}), in batches, then\nwrite ARCHITECTURE.md. Report coverage against the root you named in step 1\n(\"214 of 226 files described, 12 skipped as assets\").Maintain - the runtime context tells you, every turn, which recorded roles\nhave gone stale and which code files have none. Annotate the files you touched as\npart of finishing the work, in the same turn. Do not stop a task to work through\nthe whole backlog. A stale index is worse than none.
\nAnswer questions - when the user asks where something lives or how parts\nconnect: call metagraph(action=\"find\", ...) or metagraph(action=\"file\", ...)\nfirst, answer with the exact file list and the dependency chain. Grep only to\nverify or when the graph lacks the answer, then backfill what you learned into\nthe index.
role at ~120 chars; this is a map, not documentation.dist/, lockfiles get kind config, no role needed).ARCHITECTURE.md stays under one page: layers, entry points, main flows, where to start reading.