feat: add Atlas — the architecture map lives in the repo

README.md

@@ -44,12 +44,13 @@ It ends with a three-bullet recap (cause, fix, how it was verified) you could sa
 
 | plugin | source | role |
 |---|---|---|
-| `engineer` | builtin (protoAgent ≥ 0.180.0) | the navigator skills: `repo-onboard` (setup + guided tour) and `debug-loop` (seven guided steps, plus an appendix on why LLM/agent apps "stop without answering"). Off for every other agent. |
+| `engineer` | builtin (protoAgent ≥ 0.180.0) | the navigator skills: `repo-onboard` (setup, architecture overview — the Atlas model when there is one — and a guided tour) and `debug-loop` (seven guided steps, plus an appendix on why LLM/agent apps "stop without answering"). Off for every other agent. |
 | `craft` | builtin | `/code-review`, `/grill`, `/due-diligence` and friends, rituals you type |
 | `friction` | builtin | harness-friction ledger: a rough edge leaves evidence instead of vanishing |
 | `delegates` | builtin | `delegate_to`, for an optional coding agent, used only when you say so |
 | `terminal` | [terminal-plugin](https://github.com/protoLabsAI/terminal-plugin) | **your** terminal: a real PTY shell in a console view beside chat |
 | `github` | [github-plugin](https://github.com/protoLabsAI/github-plugin) | GitHub over the `gh` CLI, **read-only by default**: issues, PRs, diffs, CI status, repo files |
+| `atlas` | [atlas-plugin](https://github.com/protoLabsAI/atlas-plugin) | a drill-down **architecture map** of the repo, from a LikeC4 model in the repo's `architecture/`, with guided tours in presenter mode |
 
 The persona is protoAgent's `engineer` soul preset (`config/soul-presets/engineer.md` in
 core). The skills are core's in-tree `engineer` plugin. Both ship with protoAgent, and this
@@ -72,6 +73,34 @@ so it also works on a fleet member behind the hub (terminal-plugin v0.5.1+; the
 `pywinpty` (declared with a `sys_platform == 'win32'` marker; the install dialog offers it).
 macOS and Linux use the stdlib PTY and need nothing.
 
+### Atlas: the architecture map lives in the repo
+
+[Atlas](https://github.com/protoLabsAI/atlas-plugin) renders a repo's architecture as a
+diagram you drill into (system → containers → components), from a [LikeC4](https://likec4.dev)
+model: a few `.c4` files in the repo's **`architecture/`** folder, committed and reviewed with
+the code like any other file. Click an element to zoom in; its code links open the exact
+lines in the console's **code pane**. Tours (`architecture/atlas.tours.json`) play as
+slides in presenter mode.
+
+How the navigator uses it (core's `repo-onboard`, protoAgent ≥ the release with #4242):
+
+- **The repo already has `architecture/`** → that model *is* the onboarding overview: it
+  validates it (problems are findings, not fixes), opens it beside chat, and offers to
+  extend it where it's missing what the code shows.
+- **No model yet** → you get today's code-linked Mermaid overview, plus a one-line offer to
+  write the Atlas model. It writes into your repo, so it asks first, and writes only on your
+  yes. It validates the model until it's clean (`atlas_validate`), opens it, and leaves the
+  files uncommitted for you to review and commit.
+- **The guided tour** becomes an Atlas tour, one slide per turn, with `show_code` on the
+  lines behind each slide, so the next person can replay it.
+- **Mermaid stays** for one-off pictures (this bug's call sequence). Without Atlas enabled,
+  onboarding is exactly the Mermaid flow.
+
+**Needs Node.js 20+** to lay out diagrams: the `node` on PATH, or protoAgent's managed Node
+runtime. If neither is there, Atlas shows a setup banner with a one-click **Install Node
+runtime** button; the rest of the archetype works without it. The model directory is
+`model_dir` (default `architecture`) in Settings ▸ Plugins ▸ Atlas.
+
 ### GitHub: read by default, write when you decide
 
 The github plugin gives the agent **read** tools over the `gh` CLI (issues, PRs and their
@@ -108,9 +137,13 @@ Pick **Engineer** in the new-agent picker (Fleet ▸ New agent, or the setup wiz
 python -m server plugin install https://github.com/protoLabsAI/engineer-archetype
 ```
 
-**Core floor: protoAgent ≥ 0.180.0.** Bundles can't enforce a minimum version, so here's
+**Core floor: protoAgent ≥ 0.182.0.** Bundles can't enforce a minimum version, so here's
 what an older core misses:
 
+- the `atlas` member needs 0.182.0 (its manifest's `min_protoagent_version`; code links use
+  the `protoagent:code:open` view bridge). The Atlas-aware onboarding (use or offer the
+  `architecture/` model, Atlas tours) ships in core with protoAgent #4242; on an older core
+  Atlas still works by hand, but onboarding draws only the Mermaid overview;
 - the `engineer` skill pack is missing (it ships in core);
 - before 0.180.0 (#3618) the plugin dependency check ignored PEP 508 markers, so the
   terminal's Windows-only `pywinpty` showed as a **missing dependency** on macOS/Linux;
@@ -247,7 +280,7 @@ you're debugging.
 
 ## Pin lifecycle (ADR 0049)
 
-The one external member (`terminal`) is pinned to a release tag, which is a **floor**:
+The external members (`terminal`, `github`, `atlas`) are pinned to release tags, each a **floor**:
 installs take its newest *compatible* release (caret semantics; for 0.x the minor is the
 boundary). `scripts/verify_bundle.py`, run by `.github/workflows/verify-bundle.yml` on
 every PR and weekly, installs this manifest into a scratch agent on a fresh protoAgent

protoagent.bundle.yaml

@@ -12,8 +12,13 @@
 # hypothesis first, reviews their diff, and runs the checks. It edits or commits only
 # when the operator's latest message says so. See README.md for why.
 #
-# CORE FLOOR — protoAgent >= 0.180.0 (bundles carry no min-version, so it is stated
+# CORE FLOOR — protoAgent >= 0.182.0 (bundles carry no min-version, so it is stated
 # here and in the README, not enforced):
+#   * the atlas member's manifest declares min_protoagent_version 0.182.0 (the
+#     `protoagent:code:open` view bridge its code links use); the Atlas-aware
+#     repo-onboard / engineer persona ships in core with protoAgent #4242 — on a core
+#     without it Atlas still loads and works by hand, but onboarding draws the Mermaid
+#     overview and never offers the model;
 #   * the in-tree `engineer` skill pack ships with the core (protoAgent PR that added
 #     this archetype's catalog row); on an older core that `builtin` member is missing
 #     and the agent boots without its skills;
@@ -50,7 +55,11 @@
 # Host). A navigator turn reads a lot of code; a strong model with prompt caching is
 # the comfortable choice.
 #
-# PIN LIFECYCLE (ADR 0049): the external member is pinned to a release TAG; on core
+# ATLAS needs Node.js >= 20 to lay out diagrams: the `node` on PATH, or protoAgent's
+# managed Node runtime (one click on the setup banner Atlas raises when neither is there).
+# Without it the view shows that banner; the rest of the archetype is unaffected.
+#
+# PIN LIFECYCLE (ADR 0049): the external members are pinned to a release TAG; on core
 # >= 0.146 that pin is a FLOOR (installs take the newest COMPATIBLE tag — caret
 # semantics, so for 0.x the minor is the boundary). Bump it deliberately only to adopt
 # an out-of-range release; the verify workflow proves each pin set. Keep member
@@ -62,7 +71,7 @@ name: Engineer
 # plugin-release.yml (.github/workflows/release.yml); protoAgent's bundle loader ignores it.
 # Bump it in the PR that ships the release, then merge as `chore: release vX.Y.Z` (or
 # run the Release workflow by hand).
-version: 0.1.3
+version: 0.2.0
 description: >-
   A hands-on pair-programming navigator for the operator's own machine. Point it at a
   repo (a git URL or a folder) and it clones or registers it, proves the toolchain,
@@ -71,7 +80,9 @@ description: >-
   you write the fix, it reviews and runs the checks, you commit. It points at code in
   the console's code pane, opens your editor on the line when you're about to type,
   gives you a real terminal beside chat, and reads GitHub (issues, PRs, CI) to get up to
-  speed. It never edits, commits, or posts to GitHub unless you ask.
+  speed. With Atlas it maps the repo's architecture as a drill-down diagram that lives in
+  the repo (architecture/, committed with the code) and tours it in presenter mode. It
+  never edits, commits, or posts to GitHub unless you ask.
 
 # The core version this pin set was last verified against (ADR 0049) — metadata, not
 # enforced. See CORE FLOOR above.
@@ -84,8 +95,9 @@ plugins:
   - { id: delegates, builtin: true }                                                  # delegate_to — an optional coding agent, only on the operator's say-so
   - { id: terminal,  url: https://github.com/protoLabsAI/terminal-plugin, ref: v0.9.0 }  # the OPERATOR's shell beside chat; the agent may READ it (agent_access: read)
   - { id: github,    url: https://github.com/protoLabsAI/github-plugin,   ref: v0.8.0 }  # READ tools over `gh` (issues, PRs, diffs, CI, files); writes off by default
+  - { id: atlas,     url: https://github.com/protoLabsAI/atlas-plugin,    ref: v0.2.0 }  # drill-down architecture map from the repo's architecture/*.c4 (LikeC4); tours + presenter, live agent navigation, recording mode; needs Node >= 20
 
-enabled: [engineer, craft, friction, delegates, terminal, github]   # suggested turn-on list
+enabled: [engineer, craft, friction, delegates, terminal, github, atlas]   # suggested turn-on list
 
 # Create-time setup prompts (#2934, core >= 0.144.0) — the set-up step in the Setup
 # Wizard and the New Agent panel renders these and writes each answer at its key.
@@ -160,6 +172,12 @@ config:                                              # recommended defaults (you
     # run_command is this persona's main instrument, not an escape hatch (cores before
     # 0.180.0 logged every call as friction).
     escape_hatch_exempt: [run_command]
+  # Atlas: the architecture model LIVES IN THE REPO — `architecture/` under the project
+  # root, committed and reviewed with the code. The persona offers to write it (asking
+  # first) and uses an existing one as the onboarding overview. `project` blank = the
+  # console's current project. Node: blank `node_path` = PATH, then the managed runtime.
+  atlas:
+    model_dir: architecture
 
 # Agent archetype (ADR 0042 / 0100) — presents this bundle as the "Engineer" agent type
 # in the new-agent picker. `soul_preset` gives a DIRECT `plugin install <url>` the
@@ -168,7 +186,9 @@ config:                                              # recommended defaults (you
 # No `requires_tools` (capability contract) on purpose: every tool the persona commits to
 # (show_code, run_command, open_in_editor, onboard_project, memory_ingest) is a CORE tool
 # bound by the recommended `filesystem`/`onboarding` config above, not by a member plugin,
-# and it never commits to a GitHub write. A contract naming core tools would fail
+# and it never commits to a GitHub write. The atlas tools are used when bound and skipped
+# when not (onboarding falls back to a Mermaid overview), so they aren't a contract either.
+# A contract naming core tools would fail
 # scripts/verify_bundle.py (which loads members only) without catching anything new.
 archetype:
   label: Engineer