repo-system-map

# Repo System Map

Build an explorable model of what the repository actually implements. Treat the
map as a teaching interface backed by code evidence, not as decorative
architecture art.

## Contract

Accept:

- a repository URL, or an existing checkout with a configured remote;
- an optional subsystem or user journey to emphasize;
- an optional output path and serve port.

At the start, tell the user that this skill submits eligible public maps to
`tamdogood/CodeTerrain` after verification unless they opt out. Continue without
waiting, but honor an opt-out at any time before pushing. Never publish a
private, access-controlled, local-only, or confidentiality-uncertain repository.
Follow the runtime's authorization rules for external writes.

Default to remote `main` at the time analysis begins. Work from an isolated
shallow clone so the user's checkout and uncommitted changes remain untouched.
If `main` does not exist, use the remote default branch and state that deviation
prominently.

Produce one interactive HTML map named `<repo>-system-map.html`, plus the exact
commit SHA and a command or live URL that opens it. Use a user-supplied output
path first. Otherwise use the runtime's durable visualization directory outside
the analyzed checkout; use `~/visualizations/` when it is writable.

For an eligible public GitHub repository, also add or update its map in
`https://github.com/tamdogood/CodeTerrain` and return the pull-request URL. The
local HTML artifact remains required even when publication succeeds or fails.

The artifact must include:

- a dominant isometric grid with varied 3D buildings for runtime roles;
- visible dependency, control, data, event, build, or deploy paths that the code
  supports;
- payload names and important fields on the paths that carry them;
- a compact legend and repository/branch/commit snapshot;
- selectable buildings and connections with a learner-focused explainer panel;
- immutable file-and-line citations for material claims;
- keyboard, pointer, pan, zoom, filter, and flow-step interactions.

Do not substitute Mermaid, a screenshot, a directory tree, or a dependency list.

## Workflow

### 1. Pin the Repository Snapshot

Normalize links to the repository root while preserving any requested subsystem
scope. Confirm that `refs/heads/main` exists, then shallow-clone that branch into
a task-specific temporary directory. For an existing checkout, inspect its
remote URL and still use an isolated clone unless the user explicitly asks to
analyze local uncommitted work.

Record before analysis:

```text
repository URL
branch
full commit SHA
commit timestamp
analysis timestamp
requested focus, if any
```

Use authenticated tooling already available for a private repository. Never ask
the user to paste a token, copy credentials into the artifact, or read `.env`
and secret files.

### 2. Trace the Implemented System

Read repository guidance, the root README, manifests, the top-level tree,
entrypoints, configuration, schemas or migrations, infrastructure and deploy
files, and representative integration tests. Then follow the real code paths.

Identify runtime roles rather than drawing one building per directory. Merge
packages that act as one runtime unit. Include an external dependency only when
code or configuration proves that the system calls, publishes to, reads from,
writes to, builds with, or deploys through it.

Trace at least:

1. one representative control path from an entrypoint through the core logic;
2. one data or event path, including serialization, transport, persistence, and
   the important payload fields;
3. the deployment path when it materially changes the runtime model.

Use `rg` to find callers, callees, message producers and consumers, schema use,
and configuration references. Follow shared functions to their callers before
assigning ownership. A README states intent; implementation and tests establish
behavior.

For every major node and visible edge, capture a file, exact line range, what
that evidence proves, and whether the conclusion is `observed` or `inferred`.
Build immutable forge links using the pinned commit. If a claim lacks evidence,
mark it unknown or omit it.

### 3. Model the Map and Lesson

Read [references/system-map-spec.md](references/system-map-spec.md) before
authoring the artifact. Use its node, edge, flow, citation, terminology, visual,
interaction, and validation contracts.

Keep a standard map to 8-18 load-bearing buildings. For a larger monorepo, show
one coherent vertical slice and group supporting units by runtime role. More
source files belong in citations, not as more buildings.

Define each technical or repository-specific term used by the map. Give the
learner four things in the explainer panel: a plain meaning, how this repository
uses it, why it matters, and where to trace it in code. Prefer the repository's
own names; expand acronyms on first use.

### 4. Build the Interactive UI

When the `visualize` skill is available, read it completely and follow its HTML
fragment, layout, theme, and accessibility contract. Use native HTML, CSS, SVG,
and JavaScript; do not add a dependency for the isometric effect.

Keep all analyzed data inline and the first render useful. Use SVG polygons and
groups for the grid, extruded buildings, paths, arrows, and payload markers.
Let the map dominate. Place one compact legend near it and one explainer panel
beside it, stacking the panel below the map on narrow screens.

Required interactions:

- select a building or connection to update the explainer and citations;
- hover or focus a building to emphasize its immediate incoming and outgoing
  paths without hiding its label;
- toggle relationship kinds from the legend;
- choose a named end-to-end flow and step forward or backward through it;
- drag to pan, use wheel or labeled controls to zoom, and reset the view;
- expose every pointer action through native keyboard-accessible controls;
- stop nonessential motion under `prefers