mellos-mapping 0.26.1 → 0.27.0

package/dist/server.mjs

@@ -24650,7 +24650,7 @@ function launcherViewerPid(run) {
 
 // src/server/server.ts
 var SERVER_NAME = "mellos-mapping";
-var SERVER_VERSION = "0.26.1";
+var SERVER_VERSION = "0.27.0";
 function text(s, isError = false) {
   return { content: [{ type: "text", text: s }], ...isError ? { isError: true } : {} };
 }

package/dist/web/terminal.css

@@ -4,8 +4,11 @@ header{display:flex;align-items:center;justify-content:space-between;gap:12px;pa
 .brand{color:#e5edf7;text-decoration:none;font-weight:650;white-space:nowrap}.brand span{font-weight:400;color:#97a7bd;font-size:12px;margin-left:12px}.brand:hover span{color:#81dbae}
 .tools{display:flex;align-items:center;gap:8px;font-size:12px;color:#aab8cb}button,select{font:inherit;color:#d9e2ed;background:#202b3a;border:1px solid #3b4b60;border-radius:5px;padding:4px 7px;cursor:pointer}button:hover,select:hover{border-color:#81dbae}button:focus-visible,select:focus-visible,a:focus-visible{outline:2px solid #81dbae;outline-offset:2px}
 #terminal{min-width:0;min-height:0;padding:0;overflow:hidden;user-select:none;background:#10151c}#terminal .xterm{height:100%;padding:8px 10px 0}#terminal .xterm-viewport{overscroll-behavior:contain}
+#terminal .xterm-helper-textarea:disabled{pointer-events:none}
 footer{min-height:32px;display:flex;flex-wrap:wrap;align-items:center;gap:8px 12px;padding:5px 14px;border-top:1px solid #283343;color:#8c9eb5;font-size:11px}#connection{overflow-wrap:anywhere}#connection[data-state="connected"]{color:#81dbae}#connection[data-state="error"]{color:#ffaf87}.hint{margin-left:auto}[hidden]{display:none!important}
-@media(max-width:440px){.brand span{margin-left:6px}.hint{margin-left:0;width:100%}header{padding:0 10px}#terminal .xterm{padding-left:4px;padding-right:4px}}
+button:disabled{opacity:.65;cursor:default}
+@media(max-width:600px){.brand span{display:none}}
+@media(max-width:440px){.tools label{display:none}.hint{margin-left:0;width:100%}header{padding:0 10px}#terminal .xterm{padding-left:4px;padding-right:4px}}
 dialog{max-width:min(420px,90vw);border:1px solid #3b4b60;border-radius:10px;background:#151c25;color:#d9e2ed;padding:24px}dialog::backdrop{background:#0009}dialog h2{font-size:18px;margin-top:0}dialog p{line-height:1.9;font-size:13px}dialog form{text-align:right}
 
 #star-reminder {

package/dist/web/terminal.html

@@ -1,7 +1,7 @@
 <!doctype html>
 <html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Mellos · 终端地图</title><link rel="icon" href="data:,"><link rel="stylesheet" href="./xterm.css"><link rel="stylesheet" href="./terminal.css"><script type="module" src="./terminal.js"></script></head>
-<body><header><a class="brand" id="graphic" href="./" title="切换到图形地图">Mellos <span>图形地图 ↗</span></a><div class="tools"><label for="font-size">字号</label><select id="font-size" aria-label="终端字号"><option>10</option><option>11</option><option>12</option><option selected>13</option><option>14</option><option>15</option><option>16</option><option>18</option><option>20</option><option>24</option><option>28</option></select><button id="help" aria-label="操作帮助">?</button></div></header>
+<body><header><a class="brand" id="graphic" href="./" title="切换到图形地图">Mellos <span>图形地图 ↗</span></a><div class="tools"><button id="keyboard">启用快捷键</button><label for="font-size">字号</label><select id="font-size" aria-label="终端字号"><option>10</option><option>11</option><option>12</option><option selected>13</option><option>14</option><option>15</option><option>16</option><option>18</option><option>20</option><option>24</option><option>28</option></select><button id="help" aria-label="操作帮助">?</button></div></header>
 <main id="terminal" aria-label="Mellos 终端地图"></main>
-<footer><span id="connection" role="status" aria-live="polite">正在连接…</span><button id="restart" hidden>重新连接</button><span class="hint">点击地图启用快捷键 · 滚轮缩放 · 拖动平移 · ? 帮助</span><aside id="star-reminder" aria-label="支持 Mellos Mapping" hidden><span>地图有帮到你？欢迎在 GitHub 点个 Star。</span><a href="https://github.com/GuangminJu/mellos-mapping" target="_blank" rel="noopener noreferrer">去点 Star ↗</a><button type="button">不再提醒</button></aside></footer>
-<dialog id="help-dialog"><h2>终端地图操作</h2><p>滚轮 / + / −：总览 → 模块 → 细节<br>拖动：平移 · 单击：固定详情<br>双击带 ⊞ 的节点：进入子地图<br>Backspace：返回父地图<br>Tab / 数字 1–9：切换页面<br>f：自动跟随 · 0：重置视图<br>x 按两次：确认删除当前页<br>q：关闭地图，可用「重新连接」再次打开</p><p>右上角字号只影响此网页终端。</p><form method="dialog"><button>关闭帮助</button></form></dialog>
+<footer><span id="connection" role="status" aria-live="polite">正在连接…</span><button id="restart" hidden>重新连接</button><span class="hint">滚轮缩放 · 拖动平移 · 快捷键需手动启用，离开地图即释放</span><aside id="star-reminder" aria-label="支持 Mellos Mapping" hidden><span>地图有帮到你？欢迎在 GitHub 点个 Star。</span><a href="https://github.com/GuangminJu/mellos-mapping" target="_blank" rel="noopener noreferrer">去点 Star ↗</a><button type="button">不再提醒</button></aside></footer>
+<dialog id="help-dialog"><h2>终端地图操作</h2><p>鼠标操作可直接使用。键盘操作请先点击「启用快捷键」；Esc 或离开地图后释放，需再次启用。</p><p>滚轮 / + / −：总览 → 模块 → 细节<br>拖动：平移 · 单击：固定详情<br>双击带 ⊞ 的节点：进入子地图<br>Backspace：返回父地图<br>Tab / 数字 1–9：切换页面<br>f：自动跟随 · 0：重置视图<br>x 按两次：确认删除当前页<br>q：关闭地图，可用「重新连接」再次打开</p><p>右上角字号只影响此网页终端。</p><form method="dialog"><button>关闭帮助</button></form></dialog>
 </body></html>

package/dist/web/terminal.js

@@ -9213,6 +9213,36 @@ function createStarNotice(base2) {
   };
 }
 
+// src/web/terminal-input.ts
+function bindTerminalInput(textarea, button, surface) {
+  const listeners = new AbortController();
+  const options = { signal: listeners.signal };
+  const release = () => {
+    textarea.blur();
+    textarea.disabled = true;
+    button.disabled = false;
+    button.textContent = "\u542F\u7528\u5FEB\u6377\u952E";
+  };
+  button.addEventListener("click", () => {
+    textarea.disabled = false;
+    textarea.focus({ preventScroll: true });
+    button.disabled = true;
+    button.textContent = "\u5FEB\u6377\u952E\u5DF2\u542F\u7528";
+  }, options);
+  textarea.addEventListener("blur", release, options);
+  window.addEventListener("blur", release, options);
+  surface.addEventListener("pointerleave", release, options);
+  document.documentElement.addEventListener("pointerleave", release, options);
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState !== "visible") release();
+  }, options);
+  release();
+  return { release, dispose: () => {
+    release();
+    listeners.abort();
+  } };
+}
+
 // src/web/terminal-app.ts
 var element = (id) => document.getElementById(id);
 var container = element("terminal");
@@ -9246,6 +9276,8 @@ var terminal = new Dl({
 var fit = new o();
 terminal.loadAddon(fit);
 terminal.open(container);
+var keyboard = element("keyboard");
+var input = bindTerminalInput(terminal.textarea, keyboard, container);
 function setStatus(text, state) {
   status.textContent = text;
   status.dataset.state = state;
@@ -9293,15 +9325,20 @@ font.addEventListener("change", () => {
 var help = element("help-dialog");
 element("help").addEventListener("click", () => help.showModal());
 terminal.attachCustomKeyEventHandler((event) => {
+  if (terminal.textarea.disabled || !document.hasFocus()) return false;
   if (event.isComposing || event.keyCode === 229) return true;
-  if (event.key === "?") {
-    if (event.type === "keydown" && !help.open) help.showModal();
+  if (event.key === "Escape" || event.key === "?") {
+    if (event.type === "keydown") {
+      input.release();
+      keyboard.focus();
+      if (event.key === "?" && !help.open) help.showModal();
+    }
     return false;
   }
   return true;
 });
 restart.addEventListener("click", () => {
-  terminal.focus();
+  input.release();
   retries = 0;
   connect();
 });
@@ -9352,12 +9389,16 @@ function connect() {
   });
 }
 window.addEventListener("pagehide", (event) => {
+  input.release();
   disposed = true;
   clearTimeout(retryTimer);
   cancelAnimationFrame(resizeFrame);
   observer.disconnect();
   socket?.close();
-  if (!event.persisted) terminal.dispose();
+  if (!event.persisted) {
+    input.dispose();
+    terminal.dispose();
+  }
 });
 window.addEventListener("pageshow", (event) => {
   if (event.persisted) {

package/docs/codex.md

@@ -66,10 +66,13 @@ changes remeasure terminal cells rather than stretching an image, and do not
 change the host's global terminal font. The terminal uses xterm.js cell rendering;
 the graphical mode remains native SVG and supports SVG export.
 
-Click the map or Tab into it to use map keyboard shortcuts. Loading, automatic
-reconnection and page restoration preserve the current keyboard focus, so the
-viewer can remain open while typing in the conversation. Font selection keeps
-its own focus, and closing help returns to the control that opened it.
+Mouse zoom, dragging and selection work immediately. To use keyboard shortcuts,
+click **启用快捷键**, or Tab to that button and press Enter. The hidden terminal
+input stays disabled until this explicit action. Escape, leaving the map, losing
+focus or hiding the page releases keyboard input; enable it again when needed.
+Loading, reconnecting and restoring the page do not activate keyboard input.
+Font selection keeps its own focus; closing keyboard help returns to the
+activation button without reactivating the terminal.
 
 Both modes use the same project maps. Terminal input/output goes over a local
 WebSocket to a dedicated mmap worker. Each connected browser owns its own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mellos-mapping",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "mcpName": "io.github.GuangminJu/mellos-mapping",
   "description": "A live layered dependency map for bottom-up development — MCP server + terminal pane. Ghost the design first, then light nodes up from the bottom as they are built and verified.",
   "type": "module",
@@ -70,9 +70,22 @@
       "./dist/omp-extension.mjs"
     ]
   },
+  "pi": {
+    "extensions": [
+      "./dist/pi-extension.mjs"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./commands"
+    ]
+  },
   "files": [
     "dist",
     "lib",
+    "skills",
+    "commands",
     "README.zh-CN.md",
     "docs/codex.md",
     "docs/map-api.md",

package/skills/mellos-mapping/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: mellos-mapping
+description: >-
+  Maintain a live layered dependency map (Mellos map) while doing bottom-up
+  development. Use when starting any non-trivial implementation or
+  architecture task — multiple modules, layers, or more than roughly an hour
+  of work. Resume existing maps first; declare missing design, then light nodes up
+  bottom-to-top as they are built and verified. Also use when the user asks
+  for a mellos map, /mmap, a dependency map, or wants to see development
+  progress as a picture. The user's mmap_setup policy decides how eager
+  mapping is — always / complex tasks only / on-request.
+---
+
+# Mellos Mapping — the map discipline
+
+Eight MCP tools (`mmap_declare`, `mmap_update`, `mmap_remove`, `mmap_view`,
+`mmap_setup`, `mmap_open`, `mmap_read`, `mmap_batch`)
+maintain a **Mellos map**: a layered dependency map of the system under
+construction, persisted in `.mellos/map.json` (default page) plus
+`.mellos/pages/<slug>.json` (named pages) and rendered live in
+a terminal split pane, a desktop Markdown file panel, or an interactive local web viewer beside the conversation. To learn whether a map already
+exists — and under which page slugs — call `mmap_view`: every response ends
+with a `pages:` line naming the pages this project has and which one you are
+looking at. Never probe the default file to decide: it is absent whenever all
+work lives on named pages.
+
+With current servers, prefer mmap_read {resource: "pages"}: it returns page
+summaries, saved context and revisions. A new conversation or compaction is not
+a new effort. Resume the matching page, read relevant nodes by ID/filter and
+request detail/evidence only when needed. Use the IDs returned by mmap_read,
+not display labels. Declare only missing structure. Keep context.summary and
+context.next current so another conversation can continue without rebuilding.
+Pass expectedRevision on writes; reread on CONFLICT. mmap_batch applies mixed
+changes atomically to one page. mmap_read changes checks linked source hashes;
+record sources[].sha256 only after verification. Older servers can fall back
+to mmap_view discovery and the saved JSON for precise IDs.
+
+The map is a **ledger, not a judge**: the tools only refuse structural
+corruption; *when* to declare, start, or complete nodes is YOUR discipline,
+spelled out here. Report honestly — an unflattering map is doing its job.
+
+## When to open a map
+
+The USER chooses how eager mapping is — once, for themselves, not once per
+project. Where the host runs a session adapter, the answer is already in this
+session's context, stated before the conversation begins, so there is nothing to
+probe: Claude Code runs the plugin's `SessionStart` hook, and omp (Oh My Pi) and
+pi load the same paragraph through the plugin's host adapters
+(`dist/omp-extension.mjs` and `dist/pi-extension.mjs`, declared in
+`package.json#omp.extensions` and `package.json#pi.extensions`, read from the
+same store). In hosts without one (Codex CLI, a bare MCP client) call
+`mmap_setup` with no arguments before the first map decision of the session; the
+reply names both scopes and which one governs.
+
+- `always` — map every structured task: workflows, designs, architecture,
+  technical dependencies. Small effort, small map — but a map.
+- `complex` — map only medium or complex tasks: several interacting modules,
+  a new subsystem, layered refactoring — roughly an hour of work or more.
+  Skip trivial edits; a map of one node is noise. When unsure, ask.
+- `on-request` — open a map only when the user explicitly asks.
+
+Under `always` and `complex`, the recorded policy is STANDING CONSENT: on a
+task it covers, declare the ghost design and open the pane yourself, without
+asking first. Re-asking for permission the user has already given is the
+failure mode this policy exists to remove.
+
+If the policy is not set anywhere, ask the USER to choose — present the three
+options, never pick for them — then persist the answer with
+`mmap_setup {policy, scope: "user"}`. That is asked ONCE EVER: the choice is
+saved in the user's own `.mellos/config.json` and applies to every project.
+A project that genuinely needs to differ takes
+`mmap_setup {policy, scope: "project"}`, which overrides the user choice
+there; `/mmap setup` reruns the question for either scope. Until they answer,
+act as `complex`. Two things always outrank the policy: an explicit user
+request for a map wins under any policy, and a map that is already open keeps
+getting honest updates whatever the policy says.
+
+Caught mid-implementation without a map on work that deserves one? Stop and
+declare it with honest statuses (written-but-unverified is `in-progress`, not
+`done`). If the mmap tools are missing from the session, explain that mapping
+is unavailable and continue the user's implementation. In Codex, look for
+tools by their `mmap_*` suffix: a host may add a server namespace. Installing
+or repairing the plugin includes running
+`node <plugin root>/scripts/codex-register.mjs`, then starting a new
+conversation. Existing installation authorization covers this registration;
+ordinary implementation work alone does not authorize changing host config.
+The plugin root is two directories above this skill's directory. See
+`<plugin root>/docs/codex.md` for Codex packaging and installation details.
+
+## Automatic desktop terminal in a browser
+
+In ChatGPT desktop Codex mode, prefer `mmap_open {surface: "web-terminal", page}`
+when no other surface was chosen. Pass its `hostOpen` object to `open_in_codex`
+in the current conversation: right placement, browser target, returned URL.
+The page starts the existing mmap terminal automatically, with independent font
+size. No manual paste or Computer Use is needed. An older schema can use
+`node "<plugin root>/dist/web.mjs" "<project>" --terminal --page <slug>`.
+Respect manually pinned pages and report queued opening honestly. Native Claude
+Code terminal placement remains the default for terminal hosts.
+
+## Desktop document panel
+
+When the current host exposes a file side panel (for example Codex desktop's
+`open_in_codex`) and the user requests a document or no browser panel is available, use the Markdown
+surface. This replaces the terminal-placement instructions in step 2 below.
+
+1. Call `mmap_open {surface: "markdown", page: "<effort-slug>"}`. This generates
+   local Markdown with a colored SVG map and enables automatic preview updates
+   after successful map mutations in this project. It starts no terminal or web
+   server. Keep the JSON maps as the source; generated documents are not inputs.
+2. Pass the returned absolute `markdown:` path to the host's file-opening tool,
+   in the current conversation's right panel. With `open_in_codex`, use
+   `placement: "right"` and `target: {type: "file", path: "<returned path>"}`.
+   Do not set another conversation id unless the user asked for that placement.
+3. A generated file is not evidence that the user sees it. Report `queued`
+   opening as queued, and do not claim a live viewer or automatic UI refresh.
+   If the preview stays stale, regenerate with `mmap_open` and reopen the same
+   file. Avoid reopening after every write when the viewer already refreshes.
+4. `preview: STALE` means the map mutation succeeded but export failed. Fix
+   the export problem and regenerate; do not repeat the map mutation. A terminal
+   `pane:` report does not describe the desktop file panel.
+
+If this conversation still has the previous MCP schema after a local upgrade,
+use `node "<plugin root>/dist/preview.mjs" "<project directory>" --page <slug>`
+to generate the same files. Until a new conversation loads the updated server,
+rerun this command after map writes. Use the actual installed runtime path from
+`docs/codex.md` when the skill cache differs from the runtime install.
+
+The document contains a static vector image, module details, evidence and
+links to existing child pages. Image nodes do not support dragging, hover
+details, animated spinners or double-click navigation. Desktop rendering and
+refresh behavior belong to the host, not the plugin.
+
+## Optional interactive web panel
+
+Keep the user's chosen surface. Markdown/SVG remains available with its existing
+workflow; adding the web viewer never disables or replaces it. When the user
+asks for a web map or live interaction, call `mmap_open {surface: "web", page:
+"<effort-slug>"}`. Pass the returned `web:` URL to the host's browser-opening
+tool. In Codex use `open_in_codex` with `placement: "right"` and
+`target: {type: "browser", url: "<returned URL>"}` in the current conversation.
+Report queued opening honestly; a running local service does not prove visibility.
+
+The viewer reads the same project maps and refreshes automatically, including
+writes from older MCP clients. It supports zoom/pan, hover and pinned details,
+dependency highlighting, search/status filters, page selection, child-map
+navigation, groups, lanes, light/dark themes and confirmed page deletion.
+Manual page selection disables auto-follow; do not override a pinned page.
+Web page deletion also refreshes enabled Markdown previews.
+
+If this conversation has an older schema, run
+`node "<plugin root>/dist/web.mjs" "<project directory>" --page <slug>` and open
+the JSON response's `url`. It reuses a local service for that project; no public
+hosting or dependency download is required. Close an unused service with the
+same command plus `--stop` instead of `--page <slug>`. It also exits after five
+minutes without browser requests. Reopen with the tool/CLI after that, or after
+a plugin update. A `web: configured` report describes a runtime record, not a
+confirmed open desktop panel. See `docs/codex.md` for transport and lifecycle details.
+
+## The working loop
+
+1. **Resume first, then fill gaps.** Read existing pages and the matching effort's
+   records. For a new effort, declare its intended design with `mmap_declare`: `title`,
+   layer bands (rank 0 = most primitive, at the bottom), every planned node,
+   and the edges. Everything starts `planned` — the user can veto the ghost
+   design before any code exists.
+2. **Put the map on screen — that is YOUR job, not the user's.** Use the
+   desktop document flow above when applicable. For terminal hosts, at the first
+   map decision in a session, ensure the requested placement with `mmap_open`
+   even if a project viewer is already reported. Use no page for this initial
+   placement check so an existing pane pinned by the user keeps its view;
+   subsequent opens name the effort's page as usual. A project-wide viewer
+   report alone does not prove this session has its right split. Every
+   declare, update, remove and view answers with a `pane:` line telling you
+   who is actually looking. Read it and act on it:
+   - `pane: CLOSED` — nobody is. Call `mmap_open {page: "<slug>"}` at once,
+     without asking first: a recorded mapping policy IS the user's standing
+     consent to see the map. Confirm it is live only after the tool succeeds.
+     If automatic opening already failed, relay the reason and copyable command
+     once; retry only after the environment changes or the user asks.
+   - `pane: open on this page` — they are watching this land. Carry on.
+   - `pane: open on <other>, auto-follow on` — the pane follows the page
+     last written, so your next write brings the audience along by itself.
+   - `pane: open on <other>, auto-follow OFF` — the user pinned that page by
+     hand. Your changes are real and NOT on their screen: say so, and
+     retarget with `mmap_open {page}` only if they want it moved. A pane
+     with follow off is a deliberate choice — don't fight it.
+   Default open means a right split beside THIS conversation. A live viewer in
+   another window is not proof of that placement. If opening reports that the
+   source tab is inactive or Windows refused focus, relay it and ask the user
+   to activate this conversation's terminal tab before retrying. Do not retry
+   with `window: true` unless the user chose a separate window.
+   Always pass the page your effort lives on. Without it a fresh pane opens
+   on whichever page was written last, which after a gap is rarely the one
+   under discussion — and declaring on a named page makes YOU responsible
+   for the audience, rather than telling the user which tab to click.
+   `mmap_open {window: true}` puts the map in its own window instead of
+   splitting the conversation's, for users who want it separate. It never
+   CLOSES a pane: that is the user's (the `q` key, or `mmap` in any terminal
+   of the project, which toggles) — so a pane that vanishes is them, not a
+   fault.
+   On Linux/macOS, the same tool automatically opens tmux, using the inherited
+   session/pane or the single attached session when `TMUX` is missing. Multiple
+   attached sessions require `MELLOS_MAPPING_TMUX_TARGET`; custom sockets use
+   `MELLOS_MAPPING_TMUX_SOCKET` in the MCP server environment. `window: true`
+   requests a new tmux window. Do not guess between attached sessions.
+   Under omp (Oh My Pi) nothing about this changes: the same tool runs the same
+   launcher, splitting the Windows Terminal window hosting the omp session
+   (tmux split on Linux/macOS) and reusing the pane already bound to it. omp has
+   no pane of its own inside its TUI, so the split IS the map's home there —
+   never claim a map is visible when the tool reported it could not open one.
+   Where the tool cannot help — a client without it, or a machine without
+   Windows Terminal or an attached tmux session — relay the launcher's complete
+   quoted watcher command for a visible terminal, or use:
+   `node <plugin root>/dist/watch.mjs --file <project>/.mellos/map.json
+   --page <slug>` in a second terminal or tmux split (this skill file lives
+   under `<plugin root>/skills/mellos-mapping/`). `mmap_view` shows the map
+   inline anywhere.
+3. **Work bottom-up.** Set a node `in-progress` before implementing it, and
+   prefer finishing its lower dependencies first. Independent same-band
+   siblings need no artificial queue — building them together (several
+   spinners at once) is honest reporting, not a violation. If you
+   deliberately build above an unfinished dependency, say why in
+   conversation.
+4. **`done` requires evidence.** Mark `done` only when verification actually
+   passed, with what passed in `evidence` (e.g. `vitest: 23 passed`). No
+   evidence, no done.
+5. **Regression spreads upward.** If later work breaks a `done` node, set it
+   `regressed` (breakage in `evidence`) BEFORE fixing. Then walk every node
+   that uses it, directly or transitively: their `done` was proven against a
+   foundation that no longer holds. Default them to `regressed` too; keep one
+   green only with a stated reason (its own verification re-ran green, or it
+   never touches the broken behavior). After the fix, restore each node only
+   as its own verification passes again.
+6. **Revise the ghost honestly.** The design is a hypothesis, and everything
+   it declared can be revised. When a node splits, a primitive appears, or a
+   band was wrong, fix the map in the same turn you change the plan:
+   `mmap_update` moves a node to another band (`layer`), renames or re-ranks
+   a band, relabels a group or a lane, and clears any optional field with
+   `null` (never an empty string); it also edits title, kind and edge labels.
+   `mmap_declare` grows the map; `mmap_remove` drops edges, nodes, groups, lanes
+   and bands you have emptied. A map that no longer matches your intent is
+   the one failure mode this system cannot survive.
+7. **Clean up a finished effort.** Pages accumulate — one effort, one page —
+   so when an effort is over and its map has served its purpose, offer to
+   remove it: `mmap_remove {pages: ["slug"]}` deletes those page files for
+   good. Only with the user behind it, never on your own initiative, and
+   never a page someone might still be reading. (In the pane the user can do
+   it themselves: `x` twice, or the `×` on the active tab.)
+
+## Modeling guidance
+
+- **Nodes are units of buildable, verifiable work** (a module, a contract, a
+  renderer) — not tasks like "write tests" and not files.
+- **Declare groups when one band grows crowded** (`groups` in
+  `mmap_declare`, `group` on members): labeled subsystems within that band,
+  worth declaring once a single band holds roughly five or more nodes — the
+  far zoom renders groups, and a crowded band without them degrades into
+  anonymous glyphs. A group must be a strict subset of its band: a group
+  holding the whole band merely renames it. A map spread thin across many
+  bands needs no groups at all. Group status is derived from members —
+  never invent it.
+- **Every node carries `detail`**: one to three sentences on responsibility,
+  contract, and the key decision. Update it when the design shifts — a stale
+  detail is a small lie on the map.
+- **Push state to the top.** Lower layers take values in, give values out;
+  mutable state concentrates in the topmost orchestrator, which owns it
+  explicitly and hands it down as parameters. Stateless layers are cheap to
+  maintain: testable with values alone, rewritable without ceremony. A lower
+  node whose `detail` must describe state it keeps between calls is a design
+  smell — restructure before building on it.
+- **Layers encode dependency direction, nothing else.** If A needs sibling B,
+  either B is really lower-layer or A and B are one node — restructure rather
+  than force an edge.
+- **Edges mean "uses"** — the upper node genuinely calls, composes, or reads
+  the lower one. No aspirational edges.
+- Ids are stable kebab-case slugs; labels are short display names (CJK fine),
+  renameable without breaking edges.
+- **One effort = one page.** A genuinely separate effort (parallel session,
+  unrelated subsystem) gets its own page via the `page` parameter — don't mix
+  efforts or overwrite a finished map.
+- **Sub-maps: dive, don't cram.** When a node's internals genuinely deserve
+  their own picture, declare a separate page and set `submap: <page-slug>` on
+  the node — the pane badges it ⊞; double-click dives in, Backspace climbs
+  back. Your judgment: most nodes need no sub-map; create one only when the
+  child map would carry a handful of nodes of its own.
+
+## Diagram kinds
+
+The default kind is `dev` — the living progress ledger described above.
+`mmap_declare` also accepts documentation kinds, rendered neutrally (no
+ghosts, no spinners, no progress counts). Use them when the user asks for a
+picture of a system rather than a picture of work; one diagram = one page.
+
+- `architecture` — layered components; also module dependencies, call graphs.
+- `dataflow` — pipeline stages as layers, sources at rank 0; label edges
+  with the data that flows.
+- `behavior-tree` — leaves (actions) at rank 0, root on top; node `kind`
+  selector | sequence | parallel | decorator | condition | action renders
+  as a glyph. Also fits mind maps and WBS.
+- `sequence` — the classic call/return diagram. rank = time step, rank 0 =
+  earliest; the pane draws sequence pages TOP-DOWN (earliest step on top,
+  under the participant headers). Declare participants as `lanes`; every
+  call AND every return is its own event node in the ACTING participant's
+  lane, so a round trip zigzags into the callee's lane and back out. Label
+  each edge with the message.
+- State machines are out of scope: transitions cycle, and edges here only
+  point downward. Say so rather than forcing one in.
+
+Edge labels and node kinds work on `dev` maps too.
+
+## Standing state
+
+At any moment the pane should answer at a glance: what is designed, what is
+built and verified, what is in progress RIGHT NOW, and whether any foundation
+is cracked. If a glance would mislead on any of these, fix the map first.