v0.9.2

Patch release: a new install is pointed at the map, not at CI.

Changed

• init now ends by naming the one command that puts the map on screen — on both the plain and --github paths, in both languages:

  To see the map right now, without committing or waiting for CI:
    npx agent-runtime-map watch .
  

  Every route out of init previously ended in a CI round trip — commit, push, wait for the run, download the artifact, unzip it, serve the folder. The command that opens the viewer in one step was mentioned only as a suggested package.json script, where nothing says it opens anything. Someone could install the tool, finish setup, and never see the map it exists to draw. (#63)

• The README (both languages) opens its usage section with that same one-command run and links to it from the header. The GitHub Action keeps its section directly below — it answers "keep this current", not "show me the thing".

Install

npx agent-runtime-map@latest .

That analyzes the current project and opens the interactive map. For continuous updates, see the README's Action section. No registry access? The three CI-validated tarballs below install directly.

Upgrading

Nothing to change. v1 points at this release, so repositories using the GitHub Action pick it up on their next run.

Full diff: v0.9.1...v0.9.2

v0.9.1

Patch release: the Python adapter names each route after its own decorator.

Fixed

• routeFromDecorators resolved a route's path with a file-wide lookup by the decorator's dotted name, so every same-method route in a module took the first one's path. A route now reads the decorator call that sits above its own declaration. file:line, symbol, and edges were always correct — the damage was to name and metadata.path, which is what documentedCapabilityLabel matches on, so a single-module app's feature list collapsed. (#61, closes #60)

One route per file hid this: the file-wide lookup and the per-declaration lookup return the same call. The TypeScript adapter reads the path off the call expression it is iterating and never had this bug.

Install

npm install --save-dev agent-runtime-map

No registry access? The three CI-validated tarballs below install directly.

Upgrading

Nothing to change. v1 points at this release, so repositories using the GitHub Action pick it up on their next run.

Full diff: v0.9.0...v0.9.1

v0.9.0 — bilingual semantics, finished end to end

Bilingual semantics, finished end to end

0.8.2 introduced Chinese and English business names compiled from evidence. Four places still showed the technical reading, or the wrong language, depending on how you looked at the same map. 0.9.0 closes them.

What changed for you

MCP answers in your language. Every tool (analyze_project, list_features, describe_feature, get_evidence) accepts an optional locale: zh-CN or en, default en. Names and descriptions follow it together, so an agent talking to a Chinese reader now sees exactly the names the Viewer shows. A name the compiler could not confirm from evidence is marked once, in the reader's language, instead of passing for a confirmed one. Unknown locales are refused rather than answered in the wrong language.

report.html reads the same whichever way you open it. Served over HTTP it always showed business names; double-clicked as a local file, the inline fallback printed technical names. The fallback now resolves the locale the way the Viewer does (?locale=, then your browser languages) and reads the same semantic slot, with the technical name kept beside the business name.

The optional LLM layer's feature names are visible again. With --semantic openai, a model's feature name was written into a field the Viewer never reads, while the lowered confidence it attached was shown. Feature names now land in the same slot as node names, under the same rule: only a name the deterministic pass could not read is filled; a name read from evidence is never overwritten.

Naming evidence is per language. SemanticLabel.evidence is now one list per locale. When the Chinese name comes from a README line and the English name is read off the identifier, each cites its own source; previously the document stood behind both. Older graph.json files still load; the first continuous build after upgrading reports every localized node as modified once.

Also in this release

• The Python adapter needs Python 3.10 or newer (ast.Match); it now says so instead of failing with an AttributeError, and both READMEs document it.
• tsconfig.json uses ./-relative paths without baseUrl, the form TypeScript 7 requires.
• docs/ROADMAP.md is aligned with the code and docs/CC_HANDOFF.md.
• Repository only: the Action E2E workflow no longer holds GitHub Pages permissions, so it can never publish the fixture map to this repository's demo site again.
• Dependencies: elkjs 0.12, lucide-react 1.37, @xyflow/react 12.11.5, vite 8.

Compatibility

The GitHub Action's inputs and outputs are unchanged, so TheCrazyAnt/agent-runtime-map@v1 moves to this release. The SemanticLabel.evidence shape changed from a flat array to { "zh-CN": [], "en": [] }; nothing published read that field, but if you consume graph.json directly, adjust accordingly.

All three packages are published to npm with signed provenance from GitHub Actions.

v0.8.3 — keep the generated map out of your commits

Keep the generated map out of your commits

init now writes the map's output directory into .gitignore. Without it, running map:build or map:watch locally and then git add -A committed roughly 600KB of generated output — graph, report, history, and the bundled Viewer assets — into the repository.

The rule matches the directory actually configured: a custom outDir gets that path, not a hardcoded default.

If you are a new user

Nothing to do. npx agent-runtime-map init (or init --github) configures it as part of setup.

If you already installed Agent Runtime Map

The fix ships inside the CLI, so an existing project does not pick it up on its own. Either:

npx agent-runtime-map@latest init .

init is idempotent — it appends the rule if it is missing, changes nothing if it is already there, and never reorders or removes anything you wrote.

Or add the line yourself:

.agent-runtime-map/

(Use your own outDir if you configured one.)

Already committed the map by accident? git rm -r --cached .agent-runtime-map untracks it without deleting your local copy.

Nothing else changed

No analyzer, Viewer, Schema, GitHub Action, or publishing changes. All three packages are published to npm with signed provenance from GitHub Actions.

v0.8.2 — bilingual semantics, consumer runtime fixes

Bilingual business semantics, and a release path that verifies itself

Chinese readers see Chinese business logic, English readers see English — derived at compile time from the project's own documents, configuration, and identifiers, with the evidence and confidence behind each name kept alongside it. A name that cannot be read from evidence is marked 待确认 rather than invented, and that judgement is per language.

Since 0.8.1

• Per-locale uncertainty. English is no longer told a name is unconfirmed when English read it perfectly well.
• Consumer runtimes off Node 20. The composite action moves to cache v6, upload-artifact v7, upload-pages-artifact v5, deploy-pages v5; the workflow init --github generates moves to checkout v7.
• The CLI installs from npm. It previously installed from a GitHub Release asset — and v0.8.1 was tagged and published to npm with no Release created, so that URL 404'd. Moving @v1 onto it would have broken every consumer at the install step. The registry is where a published version actually lives.
• Version consistency is enforced, in both a test and release:check. Seven declarations must agree, including the action's cli-version default — the one that broke.
• The Pages branch is tested. upload-pages-artifact@v5 runs for real and its artifact is unpacked and inspected; the default is asserted to leave Pages alone; a failed analysis is asserted to publish the last successful map rather than a half-built one.

Runner requirement

The action runs on Node 24, which needs Actions Runner 2.327.1 or newer. GitHub-hosted runners are already there. A pinned self-hosted runner must be updated first.

Install

npm install --save-dev agent-runtime-map
npx agent-runtime-map init --github

All three packages are published to npm with signed provenance from GitHub Actions.

v0.8.0 — GitHub Continuous Map

Set it up once; GitHub keeps the map current.

npm install --save-dev https://github.com/TheCrazyAnt/agent-runtime-map/releases/download/v0.8.0/agent-runtime-map-0.8.0.tgz
npx agent-runtime-map init --github
git add agent-runtime-map.config.json .github/workflows/agent-runtime-map.yml && git commit

Every push and pull request then rebuilds the map on GitHub automatically — plus a weekly scheduled run so compatible analyzer updates re-map the repository even without a push.

New

• init --github generates .github/workflows/agent-runtime-map.yml next to the config: push/PR/dispatch/weekly triggers, contents: read only, per-ref concurrency, full-history checkout, and the repository's real default branch (detected from git, never assumed to be main). An unmodified generated workflow updates on re-init; your edits are never silently overwritten.
• The TheCrazyAnt/agent-runtime-map@v1 composite action: restores the previous map from cache as the diff baseline, builds, verifies the artifact contains only map files, writes a Step Summary (status, buildId, commit + baseline SHAs, node/flow/feature changes, affected features, appeared/resolved diagnostics, real trigger file paths), uploads the map as a private artifact, and saves the new baseline. Official actions/* steps only; never executes the analyzed project; never commits to your branch.
• Honest provenance across commits: the baseline SHA comes from the restored manifest, an unchanged map still advances to the analyzed commit, and a failed run reports Run commit and Map commit separately while preserving the last successful map.
• publish: pages exists as an explicit opt-in behind a loud warning; the default output stays private.

The exact tool version behind every build is recorded in manifest.json and status.json. @v1 receives backward-compatible updates only; breaking changes will ship as v2.

v0.7.0 — Continuous Map Foundation

The main line changes: install Agent Runtime Map into your project and it keeps the map current.

npm install --save-dev https://github.com/tangyishun9846/agent-runtime-map/releases/download/v0.7.0/agent-runtime-map-0.7.0.tgz
npx agent-runtime-map init
npx agent-runtime-map watch .

New

• init / build / watch commands. watch monitors source, README, docs, PRD, prompts, and configuration (debounced ~800ms, output directory always ignored), re-analyzes fully, and serves the Viewer over the live map.
• .agent-runtime-map/current/ — graph.json, raw-graph.json, manifest.json, status.json (updated | stale | failed with reason and timestamps), changes.json (what appeared/disappeared/changed, affected features, appeared/resolved diagnostics, triggering files), and report.html; plus history/<timestamp>/ snapshots.
• Never lose the map: builds stage and promote atomically; a failed analysis keeps the last successful map and only updates status.json.
• Live views: the open Viewer polls manifest.json and refreshes in place; report.html is a standalone interactive viewer over the embedded graph (static summary on file://).
• Embedding references: examples/nextjs-embed (admin-panel <LogicMap /> with allow-list API route), examples/report-embed (static hosting / iframe / CI artifact).

Skill and MCP integrations remain available as optional agent integrations.

Full verification log in #30.

v0.6.0

Any agent can now read a repository as a map.

For agents

@agent-runtime-map/mcp is a Model Context Protocol server. Register it:

{
  "mcpServers": {
    "agent-runtime-map": {
      "command": "node",
      "args": ["/absolute/path/to/agent-runtime-map/packages/mcp/dist/index.js"]
    }
  }
}

Four tools — analyze_project, list_features, describe_feature, get_evidence — each answering one question and naming the tool that answers the next. No tool returns the whole graph: a compiled map of a real repository is hundreds of kilobytes, and an agent that receives it spends its context on JSON punctuation.

Every answer keeps the source location and confidence behind each step, reports a documented-capability match separately from code confidence, and says in the answer itself that a route is statically inferred rather than recorded.

The server writes nothing into the analyzed project unless asked, does not execute it, and is not a file reader: get_evidence returns source lines only for a path the graph already points at, inside the project, bounded.

For humans

Unchanged:

npm install --save-dev https://github.com/tangyishun9846/agent-runtime-map/releases/download/v0.6.0/agent-runtime-map-0.6.0.tgz
npx agent-runtime-map .

v0.5.0

From outside feedback: helper functions were taking Agent slots, and most node types never appeared.

Install

npm install --save-dev https://github.com/tangyishun9846/agent-runtime-map/releases/download/v0.5.0/agent-runtime-map-0.5.0.tgz
npx agent-runtime-map .

A folder no longer promotes the plumbing inside it

Every function under agents/ became an Agent at 72%, so isRecord, optionalText, and parseJsonBlock held four slots on a compressed map — and because an Agent outranks almost everything, they pushed real steps off it.

A predicate, a converter, or a function returning a bare primitive is plumbing wherever it sits. A name that says …Tool is still evidence about the function itself, so searchTool in tools/ is still a tool.

The map shows data and outbound calls again

Data access required the receiver to be literally db, prisma, supabase, drizzle, or knex; an outbound call required a literal https:// URL. An ordinary project showed neither.

prisma.order.findMany   → order data          0.88   named client
pool.query              → pool data           0.70   receiver convention
fetch("https://vendor") → vendor.example.com  0.92   host known
got.post(endpoint)      → got request         0.68   host computed

Confidence carries the difference rather than the two being reported as equally certain.

<LogicMap positions={…} />

For a host that already computes its layout: pass coordinates by node id and the layout engine is never imported. Verified — a map rendered from supplied positions makes no request for elkjs at all.

v0.4.1

Two crashes in the Viewer, and the reason nothing caught them.

Install

npm install --save-dev https://github.com/tangyishun9846/agent-runtime-map/releases/download/v0.4.1/agent-runtime-map-0.4.1.tgz
npx agent-runtime-map .

Fixed

Searching blanked the whole Viewer. The search read a value declared 142 lines further down the component, so the first keystroke hit the temporal dead zone and took React's tree with it. Present since 0.3.2 — search has been unusable since then. Upgrade if you are on 0.3.2, 0.3.3, or 0.4.0.

Flying to a node the map had not measured threw. Every node hidden by focus is unmeasured, so searching from inside a focus and clicking a result outside it hit this.

Changed

npm run typecheck now checks the Viewer. Nothing did before — the root project never included apps/**, and vite build does not run tsc. TypeScript had been reporting one of the bugs above for as long as the line existed, with nobody reading it.