/repo-map — see the repo instead of reading about it

The findings report is prose and the index is JSON. Neither answers "what shape is this codebase" in the two seconds a picture takes. This renders the index Cortex already built into one page.

node "${CLAUDE_PLUGIN_ROOT}/index/cortex-view.mjs" .

This skill exists because that command does not work when a user types it themselves. ${CLAUDE_PLUGIN_ROOT} is set inside a skill and nowhere else, so a plugin user in their own terminal has to know a version-pinned path into the plugin cache — one that changes on every update. /repo-map is the address they can actually remember.

No server, no CDN, no runtime: the data is inlined, so the page works offline and copies anywhere.

Before the first write

If .cortex/ does not exist, ask before running anything — the index comes first, and that is the write ADR 0005 gates. Generated and gitignored is not the same as invisible. The .gitignore entry is written for you at creation time; the asking is not.

How to run it

1. Check the index. If .cortex/index/index.json is missing or older than the working tree, re-run node "${CLAUDE_PLUGIN_ROOT}/index/cortex-index.mjs" . first — a picture of a stale index is worse than no picture, because it looks current.
2. Run the viewer. It writes .cortex/view/repo.html and opens it in the default browser. Pass --no-open when the user is on a headless machine or has said not to open windows.
3. Print the path. The browser may not surface on every setup, and the file is the deliverable.
4. Say what the numbers mean, using the summary line the CLI prints — files, import edges, areas, orphans, files in cycles, modules with no test found. Do not re-count anything yourself.

What is on the page

Any Overview fact that could not be read — no git, no memory yet, no findings pass — says not available and why. Report it that way; never read a missing value as zero. Churn and the timeline end at the indexed commit, not at today, so the page is the same on every machine.

A red outline on a node means no test was found. Pointing at a file lights its imports and importers, and a click keeps them lit. Click a row in the legend to hide that box; / focuses search; scroll zooms and drag pans. On the Map, arrow keys pan, plus and minus zoom, and zero resets. On the Overview, drag turns the cloud and a click opens the file. The theme follows the OS; the button in the top bar overrides it and is remembered.

What you must not claim about the picture

A graph is persuasive in a way prose is not, so the hedges matter more here, not less.

• An orphan is a question. Import resolution is regex-based (ADR 0004 rules out a parser), so a dynamically loaded or framework-discovered file looks exactly like a dead one. Never present the Gaps tab as a delete list.
• "No test found" is a floor. Coverage uses three signals — a test named for the file, importing it, or naming it in a quoted string — so a file exercised only through a subprocess reads as untested. Wrong in the safe direction, and say so.
• Markdown and config are not drawn. They have no imports; on one repo 171 isolated nodes buried the 98 connected ones. They are still in the Files tab, and the legend says how many.
• A bridge is a link worth a look, not a defect. The score ranks imports between clusters by how unexpected they look, and its reasons say why. Every hub's link count is a floor. The same report prints as text with node "${CLAUDE_PLUGIN_ROOT}/index/cortex-graph.mjs" .. For one file's neighbours, its cluster, or the import path between two files, ask the graph MCP tool (or node "${CLAUDE_PLUGIN_ROOT}/mcp/ai-os.js" graph <op>) instead of opening the page.
• Depth is a floor too. An unresolved import makes a file look shallower than it is, so the layer count is the smallest honest answer rather than a verdict on the architecture.

Related

• /setup-repo builds the index this renders; run it first on a repo Cortex has never seen.
• /summarize-files adds a summary to every file card — what the file does, not just how it is wired. Optional and costs tokens.
• /resume-work answers the same "where am I" question in text, and is what the Next steps tab shows.