Skip to content

fix: point a new install at the map instead of at CI - #63

Merged
TheCrazyAnt merged 1 commit into
mainfrom
fix/first-run-shows-the-map
Sep 3, 2026
Merged

TheCrazyAnt merged 1 commit into
mainfrom
fix/first-run-shows-the-map

Conversation

@TheCrazyAnt

Copy link
Copy Markdown
Owner

Closes the gap you flagged: a user installs, finishes setup, and never sees the map.

What was wrong

Every documented path out of init ended in a CI round trip:

init --github  →  commit  →  push  →  wait for the run  →  download artifact
               →  unzip  →  npx serve .  →  finally, the map

The command that opens the viewer in one step existed, but init only mentioned it as a suggested package.json script — where nothing tells you it opens anything:

Suggested package.json scripts (add them yourself if you want them):
  "map:build": "agent-runtime-map build ."
  "map:watch": "agent-runtime-map watch ."

And the README filed it under "Local development: watch mode", below the Action it calls the "primary way to use". The strongest surface in the product was reachable only by reading past the section that told you to go to CI instead.

The fix

init now closes by naming the command that ends with a map on screen — on both paths and in both languages. Actual output now:

Created …/agent-runtime-map.config.json.
Added .agent-runtime-map/ to …/.gitignore, so the generated map stays out of version control.
Suggested package.json scripts (add them yourself if you want them):
  "map:build": "agent-runtime-map build ."
  "map:watch": "agent-runtime-map watch ."
Created …/.github/workflows/agent-runtime-map.yml.
Next: commit agent-runtime-map.config.json and .github/workflows/agent-runtime-map.yml.
Every push, pull request, and a weekly schedule will then rebuild the map on GitHub:
the run's Summary shows what changed, and the full map (report.html) is attached as an artifact.
To see the map right now, without committing or waiting for CI:
  npx agent-runtime-map watch .
That analyzes this project, opens the interactive viewer in your browser, and keeps
both current as you edit. Use `build .` for the files alone, without a viewer.

It is last on purpose: it is the only instruction that ends with something visible, and the --github path otherwise signs off pointing at CI.

The README (both languages) now opens its usage section with that one command and links to it from the header. The Action section stays immediately below — it answers "keep this current", not "show me the thing".

Evidence

The test fails without the fix. Three mutations were applied in turn, each had to turn it red, and the implementation was restored byte-identical after each:

Mutation Result
A — hint names build . instead of watch . (no viewer) 1 red
B — Chinese hint left as the English string (missed translation) 1 red
C — hint drops the promise of a viewer 1 red
restored 3 green

Both paths run. Verified against real temp projects with the built CLI: init under LANG=zh_CN.UTF-8 and init --github under LANG=en_US.UTF-8 — output above.

No dead anchors. Renaming the Chinese section broke the header link to it (#一次设置github-持续更新主路径). Every internal anchor in both READMEs is now checked by slug against every heading — 4 links, 4 resolve. docs/marketing/LAUNCH_KIT.md points at the English anchor, which is unchanged.

Full npm run check: typecheck, 24 files / 214 tests (213 before, 1 new), build.

Not in this PR

The Action's Step Summary already documents how to open report.html from the artifact, and is honest that opening the file directly degrades to a static summary (file:// blocks its ES modules). Making the Action surface the map without a download — e.g. a PR comment with affected features — is a product decision, not this fix.

🤖 Generated with Claude Code

Every documented route out of `init` ended in a CI round trip: commit, push,
wait for the run, download the artifact, unzip it, serve the folder. The one
command that puts the map on screen was listed only as a suggested package.json
script, where nothing says it opens a viewer. So a person could install the
tool, finish setup, and never once see the map it exists to draw.

`init` now closes by naming that command on both paths — plain and `--github` —
in both languages. It goes last deliberately: it is the only instruction that
ends with something on screen, and the `--github` path otherwise signs off on a
round trip through CI.

The README (both languages) now opens its usage section with the same one
command and links to it from the header. The Action keeps its section directly
below, which is where it belongs: it answers "keep this current", not "show me
the thing".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@TheCrazyAnt
TheCrazyAnt merged commit e91674a into main Sep 3, 2026
8 checks passed
@TheCrazyAnt
TheCrazyAnt deleted the fix/first-run-shows-the-map branch September 3, 2026 14:05
@TheCrazyAnt TheCrazyAnt mentioned this pull request Sep 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant