Codebase Atlas

Turn docs/architecture-analysis/architecture.graph.json into one interactive
HTML file you can open, read, and reason with. Built for the problem of losing
the shape of a codebase that agents are changing faster than anyone reads diffs.

This is a rendering skill. Every fact it displays comes from artifacts
/refresh-architecture already produces; it never parses source itself. If the
graph is wrong or narrow, the atlas says so rather than hiding it.

Arguments

$ARGUMENTS — optional flags, forwarded to scripts/build_atlas.py:

Flag	Effect
(none)	Write docs/architecture-analysis/atlas/index.html
--check	Read-only; exit 2 if the written page is stale
--output PATH	Write somewhere else
--json-only	Print the view-model as JSON; render nothing
--no-coverage	Skip the on-disk coverage scan (faster, drops the banner)
--graph PATH	Read a different graph artifact
--tree TARGET	Print an indented call/callee tree for a symbol or file
--hops N	Hop depth for --tree (default 2, max 4)
--direction in|out|both	Callers, callees, or both for --tree (default out)

Usage

The skill is portable, so the script invocation is canonical — it works from a
runtime copy in any consumer repository:

python3 "<skill-base-dir>/scripts/build_atlas.py" $ARGUMENTS
python3 "<skill-base-dir>/scripts/build_atlas.py" --tree acquire_lock --hops 2

Requires only the Python standard library. In this repository the Makefile wraps
the same script as a source-checkout convenience:

make atlas          # build docs/architecture-analysis/atlas/index.html
make atlas-check    # read-only drift check (exit 0 fresh / 2 stale)

Those targets are not available in consumer repositories — install.sh copies
the skill directory, not this repo's root Makefile — so prefer the script form
unless you know you are in a source checkout.

Then open the output file. It needs no server, no build step, and makes zero
network requests — it works offline and under a strict CSP.

What the page gives you

Structure pane (left) — foldable tree: language → file → symbol, with SQL
columns nested under their tables. Live filter across files and symbols;
expand/collapse all. Counts at every level.

Dependency pane (centre) — animated force-directed graph, one node per
source file, sized by symbol count and coloured by language. Scroll to zoom,
drag to pan, drag a node to pin it, double-click to re-frame. The simulation
pre-warms before the first paint so the page opens on a settled layout, then
stops once relaxed, so an open tab costs no CPU.

Cross-connections pane (right) — select anything and see what calls it and
what it calls. Callers render orange, dependencies teal, with arrowheads and hop
distance; everything else dims. The hop slider widens the neighbourhood to 4.
Every entry is clickable, so you can walk the call graph without leaving the
page. Selecting a symbol gives symbol-level precision; selecting a file gives
the aggregated module view.

Any view is a URL: selection, hop depth, filter text, and disabled
language/edge-type filters all round-trip through the location hash, so a view
can be pasted into a PR or an issue.

Coverage honesty

The banner at the top is the most important thing on the page, and it cannot be
dismissed. The analyzer only examines the roots configured in the Makefile
(PYTHON_SRC_DIR, TS_SRC_DIR), so the graph can describe a small fraction of
the repository while looking authoritative. The banner reports, per language:

• how many on-disk files the graph actually covers, as a percentage;
• which top-level directories contain files the graph never saw;
• how many files the graph names that no longer exist on disk — a direct
  staleness signal, since it means the graph outlived its source.

Coverage is matched by file name, not full path, because the analyzer records
bare basenames. One graph name can match several on-disk files, so the reported
percentage is an optimistic upper bound. Treat it as a ceiling.

Determinism

Output is byte-stable for a fixed input graph: collections are sorted, JSON is
serialised with sorted keys, and initial node positions are seeded from a hash of
each module key rather than from a random generator. Re-running without upstream
changes produces an identical file, which is what makes --check meaningful.

Selecting a node deliberately does not re-heat the simulation. A node must
not move because it was clicked, or the reader loses their mental map.

Relationship to other skills

• /refresh-architecture produces the graph this reads. Run it first; if the
  atlas reports staleness, that is the fix.
• project-context-refresh owns deterministic documentation inventories
  (documentation.inventory, api.contracts). The atlas is the visual
  counterpart and shares its generate/check exit-code contract
  (0 fresh · 1 error · 2 drift).
• The generated HTML is gitignored: it is derived, ~650 KB, and not
  meaningfully diffable. Regenerate it with make atlas instead of committing it.

Scope

This skill renders what the graph contains: files, symbols, call edges, and
import edges. It does not add extraction, a graph database, a server, or an
LLM-backed query surface. Those are later phases of
docs/proposals/codebase-visualization-tool.md, deliberately not prerequisites
for the page existing.