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

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes are documented here.
 
+## Unreleased
+
+### Changed
+
+- `init` now ends by naming the one command that puts the map on screen
+  (`npx agent-runtime-map watch .`), in both languages and on both the plain and
+  `--github` paths. Every route out of `init` previously ended in a CI round trip
+  — commit, push, wait, download the artifact, serve it — so someone could finish
+  setup without ever seeing the map the tool exists to draw.
+- The README (both languages) opens the usage section with that same one-command
+  run instead of the GitHub Action, and the header links to it. The Action stays
+  documented right below it as the way to keep the map current.
+
 ## 0.9.1 - 2026-09-03
 
 ### Fixed

README.md

@@ -12,6 +12,7 @@
 
 <p align="center">
   <a href="https://thecrazyant.github.io/agent-runtime-map/"><strong>Open the live demo</strong></a>
+  · <a href="#start-here-your-own-map-one-command">Map your own project</a>
   · <a href="#set-it-up-once-github-keeps-the-map-current">Install in a repository</a>
   · <a href="https://www.npmjs.com/package/agent-runtime-map">npm</a>
 </p>
@@ -113,11 +114,24 @@ frames, edge-state tokens, and boundary measurement helpers for embedding the
 same map in another product. See [Visual Components](docs/VISUAL_COMPONENTS.md)
 for the component contract and integration example.
 
+## Start here: your own map, one command
+
+Point it at a project and the interactive map opens in your browser. Nothing to
+configure, no commit, no CI:
+
+```bash
+npx agent-runtime-map@latest .
+```
+
+That is the whole first run. Add `watch` instead to keep the map live while you
+edit, or `--no-open` to skip the browser. Once you have seen your own map, set up
+the section below so it stays current without you asking.
+
 ## Set it up once, GitHub keeps the map current
 
-The primary way to use Agent Runtime Map: install it, run one init, commit the
-workflow it generates — and from then on every push and pull request rebuilds the
-map on GitHub automatically.
+For continuous updates: install it, run one init, commit the workflow it
+generates — and from then on every push and pull request rebuilds the map on
+GitHub automatically.
 
 ```bash
 npm install --save-dev agent-runtime-map

README.zh-CN.md

@@ -12,7 +12,8 @@
 
 <p align="center">
   <a href="https://thecrazyant.github.io/agent-runtime-map/?locale=zh-CN"><strong>打开在线 Demo</strong></a>
-  · <a href="#一次设置github-持续更新主路径">接入仓库</a>
+  · <a href="#从这里开始一条命令看到自己的图">一条命令看到自己的图</a>
+  · <a href="#一次设置github-持续更新">接入仓库</a>
   · <a href="https://www.npmjs.com/package/agent-runtime-map">npm</a>
 </p>
 
@@ -80,10 +81,21 @@ Viewer 采用开源的工程蓝图视觉系统：细密网格画布、图标型
 后台可以复用节点、分区边框、链路状态 token 和自动边界计算工具。组件接口和
 嵌入示例见 [Visual Components](docs/VISUAL_COMPONENTS.md)。
 
-## 一次设置，GitHub 持续更新（主路径）
+## 从这里开始：一条命令看到自己的图
 
-主用法：安装、执行一次 init、提交它生成的 workflow——之后每次 push 和 Pull
-Request 都会在 GitHub 上自动重建地图。
+指向任意项目，交互式地图就在浏览器里打开。无需配置、无需提交、不用等 CI：
+
+```bash
+npx agent-runtime-map@latest .
+```
+
+第一次就这一步。想让地图随代码改动一直刷新，把命令换成 `watch`；不想自动开
+浏览器，加 `--no-open`。看过自己的图之后，再按下一节配置持续更新。
+
+## 一次设置，GitHub 持续更新
+
+需要持续更新时：安装、执行一次 init、提交它生成的 workflow——之后每次 push 和
+Pull Request 都会在 GitHub 上自动重建地图。
 
 ```bash
 npm install --save-dev agent-runtime-map

packages/cli/src/continuous.ts

@@ -39,7 +39,12 @@ export async function runInit(
     .map(([name, command]) => `  "${name}": "${command}"`)
     .join("\n");
   process.stdout.write(`${text.initScripts(scripts)}\n`);
-  if (!options.github) return 0;
+  // The view hint goes last on both paths: it is the one instruction that ends with
+  // the map on screen, and `init --github` otherwise closes on a CI round trip.
+  if (!options.github) {
+    process.stdout.write(`${text.initViewHint}\n`);
+    return 0;
+  }
 
   try {
     const workflow = await initGithubWorkflow(projectPath, { force: options.force });
@@ -50,7 +55,7 @@ export async function runInit(
         : workflow.outcome === "overwritten"
           ? text.githubWorkflowOverwritten(workflow.workflowFile)
           : text.githubWorkflowUpdated(workflow.workflowFile);
-    process.stdout.write(`${line}\n${text.githubNextSteps}\n`);
+    process.stdout.write(`${line}\n${text.githubNextSteps}\n${text.initViewHint}\n`);
     return 0;
   } catch (error) {
     if (error instanceof WorkflowModifiedError) {

packages/cli/src/i18n.ts

@@ -26,6 +26,7 @@ export interface CliText {
   initUnchanged(file: string): string;
   initScripts(scripts: string): string;
   initIgnored(rule: string, file: string): string;
+  initViewHint: string;
   configWarning(warning: string): string;
   buildUpdated(dir: string, buildId: string, ms: number): string;
   buildUnchanged(buildId: string): string;
@@ -84,6 +85,11 @@ const TEXT: Record<CliLocale, CliText> = {
     githubWorkflowUnchanged: (file) => `${file} is already current; nothing changed.`,
     githubWorkflowModified: (file) => `${file} exists and has local modifications, so it was NOT touched. Re-run with --force to overwrite it.`,
     githubNextSteps: `Next: commit agent-runtime-map.config.json and .github/workflows/agent-runtime-map.yml.\nEvery push, pull request, and a weekly schedule will then rebuild the map on GitHub:\nthe run's Summary shows what changed, and the full map (report.html) is attached as an artifact.`,
+    // Init is the moment someone has just installed and is still at the terminal.
+    // Without this line every documented path from here ends in CI: commit, push,
+    // wait, download an artifact, serve it — so a new user can finish setup having
+    // never once seen the map. The viewer is a single command away; say so here.
+    initViewHint: `To see the map right now, without committing or waiting for CI:\n  npx agent-runtime-map watch .\nThat analyzes this project, opens the interactive viewer in your browser, and keeps\nboth current as you edit. Use \`build .\` for the files alone, without a viewer.`,
     forceRequiresGithub: "--force is only meaningful together with init --github",
   },
   "zh-CN": {
@@ -126,6 +132,7 @@ const TEXT: Record<CliLocale, CliText> = {
     githubWorkflowUnchanged: (file) => `${file} 已是最新，未做修改。`,
     githubWorkflowModified: (file) => `${file} 已存在且包含你的手动修改，因此没有改动它。如需覆盖，请使用 --force 重新执行。`,
     githubNextSteps: `下一步：提交 agent-runtime-map.config.json 和 .github/workflows/agent-runtime-map.yml。\n之后每次 push、Pull Request 以及每周一次的定时任务都会在 GitHub 上自动重建地图：\n运行的 Summary 会显示变更摘要，完整地图（report.html）会作为 artifact 附在运行结果里。`,
+    initViewHint: `想立刻看到地图，无需提交、也不用等 CI：\n  npx agent-runtime-map watch .\n该命令会分析当前项目，在浏览器中打开交互式界面，并随你改代码自动刷新。\n只要产物文件、不需要界面时，用 \`build .\`。`,
     forceRequiresGithub: "--force 只能与 init --github 一起使用",
   },
 };

tests/i18n.test.ts

@@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
 import { analyzeTypeScriptProject } from "@agent-runtime-map/typescript";
 import { compileLogicGraph } from "@agent-runtime-map/logic-compiler";
-import { helpText, localizedViewerUrl, resolveCliLocale } from "../packages/cli/src/i18n.js";
+import { cliText, helpText, localizedViewerUrl, resolveCliLocale } from "../packages/cli/src/i18n.js";
 import {
   localizeDiagnostic,
   localizeFeatureLabel,
@@ -25,6 +25,19 @@ describe("localization", () => {
     expect(localizedViewerUrl("http://127.0.0.1:4173", "zh-CN")).toBe("http://127.0.0.1:4173/?locale=zh-CN");
   });
 
+  it("tells a freshly initialized project how to open the viewer, in both languages", () => {
+    // Every other path out of init ends in CI — commit, push, wait, download an
+    // artifact, serve it — so without this line a user can finish setup having
+    // never seen the map. The command has to be runnable as printed.
+    for (const locale of ["en", "zh-CN"] as const) {
+      const hint = cliText(locale).initViewHint;
+      expect(hint).toContain("npx agent-runtime-map watch .");
+      // A hint that does not promise a viewer does not fix the problem it exists for.
+      expect(hint).toMatch(locale === "en" ? /viewer/i : /界面/);
+    }
+    expect(cliText("zh-CN").initViewHint).not.toBe(cliText("en").initViewHint);
+  });
+
   it("localizes generated graph semantics while preserving code-backed metadata", async () => {
     const raw = await analyzeTypeScriptProject(fixture);
     const graph = compileLogicGraph(raw, { maxNodes: 40 });