mellos-mapping 0.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mellos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,286 @@
+# Mellos Mapping
+
+[![CI](https://github.com/GuangminJu/mellos-mapping/actions/workflows/ci.yml/badge.svg)](https://github.com/GuangminJu/mellos-mapping/actions/workflows/ci.yml)
+
+English | [简体中文](README.zh-CN.md)
+
+A live, terminal-native map of bottom-up development for
+[Claude Code](https://claude.com/claude-code) and Codex CLI.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: light)" srcset="docs/demo-light.svg">
+    <img alt="A Mellos map building itself: ghost design first, spinners climbing the layers, a cracked foundation spreading upward, honest recovery" src="docs/demo.svg" width="620">
+  </picture>
+</p>
+
+While Claude builds your system, a split pane beside the conversation shows
+the system's **layered dependency map**: primitive layers at the bottom,
+dependency edges that may only point downward, ghost nodes for what is
+designed, a spinner on what is being built right now, and solid green for
+what is built *and verified*.
+
+```
+  Mellos Mapping · the plugin itself
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━ orchestration
+
+  ╭╌╌╌╌╌╌╌╌╌╌╌╌╌╌╮
+  ╎ · MCP Server ╎
+  ╰╌╌╌╌┬╌┬╌╌┬╌╌╌╌╯
+       │ │  │
+       └─┼──┼─────────────┐
+         │  └──────┐      │
+         │         │      │
+━━━━━━━━━┿━━━━━━━━━┿━━━━━━┿━━━ contracts
+         │         │      │
+  ┏━━━━━━┷━━━━━━━━┓│ ╭╌╌╌╌┴╌╌╌╌╌╌╮
+  ┃ ■ State Store ┃│ ╎ · Watcher ╎
+  ┗━━━━━┯━━━━━━━━━┛│ ╰╌╌╌╌╌┬╌╌╌╌╌╯
+        │          │       │
+        │ ┌────────┘       │
+        │ │                │
+━━━━━━━━┿━┿━━━━━━━━━━━━━━━━┿━ primitives
+        │ │                │
+  ┏━━━━━┷━┷━━━━━━┓  ╭──────┴───────────╮
+  ┃ ■ Map Domain ┃  │ ⠋ ASCII Renderer │
+  ┗━━━━━━━━━━━━━━┛  ╰──────────────────╯
+
+  · planned   ⠋ in-progress   ■ done   ✗ regressed
+```
+
+In a real terminal the wiring and band bars render FAINT while node boxes
+glow in their status colors with bold labels — a dark circuit board where
+the components are the bright things. Skip-level edges thread through gaps
+between boxes (watch the line dive between State Store and Watcher above);
+non-overlapping wire segments share track rows to keep the bands close.
+
+*(This is the plugin's own map, mid-development. The spinner really spins.)*
+
+## Why
+
+Most progress reporting is a task list — a top-down worldview. A Mellos map
+grows the other way: an upper node can only stand on nodes below it, and the
+picture makes the discipline visible:
+
+- **The ghost design appears before any code.** Claude declares the whole
+  intended structure as dashed ghost nodes first; you can veto a bad design
+  while it is still only a picture.
+- **The spinner is where Claude's attention is.** One glance answers "what is
+  it doing right now, and on top of what?"
+- **Done means verified.** A node turns solid green only with evidence (a
+  passing test run). If later work cracks a foundation, the node turns red —
+  a cracked foundation under a spinning upper floor is the most honest status
+  report there is.
+- **The map is a ledger, not a judge.** The tools refuse only structural
+  corruption (an edge pointing upward, a duplicate rank). Workflow is
+  Claude's discipline, defined in the bundled skill; violations are made
+  *visible*, never silently blocked.
+
+## Install
+
+Two lines inside any Claude Code conversation:
+
+```
+/plugin marketplace add GuangminJu/mellos-mapping
+/plugin install mellos-mapping@mellos-mapping
+```
+
+Or one line in a terminal:
+
+```
+claude plugin marketplace add GuangminJu/mellos-mapping && claude plugin install mellos-mapping@mellos-mapping
+```
+
+Requires Node.js 18+ on PATH (Claude Code itself requires Node, so you
+already have it). No build step: the MCP server and watcher ship pre-bundled.
+
+## Update
+
+```
+claude plugin marketplace update mellos-mapping && claude plugin update mellos-mapping@mellos-mapping
+```
+
+Two steps because `plugin update` compares against the locally cached
+marketplace clone — the first command is what actually pulls this repo.
+Restart Claude Code to apply. Releases are version bumps on `master`.
+(In-app, `/plugin` opens the same management UI.)
+
+## Codex CLI
+
+The same repo doubles as a Codex plugin (codex-cli 0.147+). Three lines:
+
+```
+codex plugin marketplace add GuangminJu/mellos-mapping
+codex plugin add mellos-mapping@mellos-mapping
+node ~/.codex/plugins/cache/mellos-mapping/mellos-mapping/<version>/scripts/codex-register.mjs
+```
+
+The first two install the skill (the map discipline) as a Codex plugin. The
+third registers the MCP server at user level — needed because Codex spawns
+plugin-bundled MCP servers inside the plugin cache with no way to see your
+workspace, so a bundled server would write the map into the cache. A
+user-level `codex mcp add` entry (which the script writes) inherits each
+session's working directory instead: the state file lands in your project,
+same as under Claude Code. The registered path is version-specific — re-run
+the script after updating the plugin.
+
+To watch the live pane beside a Codex session, run
+`node <plugin root>/dist/watch.mjs` from the project directory in a second
+terminal (or any terminal split).
+
+## Any MCP client
+
+The server ships on npm, so any MCP client (Cursor, Windsurf, Zed,
+Gemini CLI, …) can run it with a standard stdio entry:
+
+```
+npx -y mellos-mapping
+```
+
+The map file lands in the client session's working directory
+(`.claude/mellos-mapping.json`). Open the live pane from the same project:
+
+```
+npx -y -p mellos-mapping mellos-mapping-watch
+```
+
+The skill/discipline layer is Claude Code + Codex specific; other clients
+get the four `mmap_*` tools and the pane, and bring their own prompting.
+
+## Use
+
+1. Ask Claude to build something non-trivial. The bundled skill has Claude
+   declare the ghost design and keep the map current as it works.
+2. Run `/mellos-mapping:mmap` to open the live pane (Windows Terminal split
+   on Windows, tmux split inside tmux, or a printed command to run in any
+   second terminal). Prefer `--ascii` if your font lacks box-drawing glyphs.
+3. Watch nodes light up from the bottom. Interrupt when the picture worries
+   you — that is what it is for.
+
+The pane is mouse-aware (xterm SGR any-event tracking — the same protocol
+htop and tmux speak):
+
+| Input | Action |
+| --- | --- |
+| hover a node | spotlight its wires; preview its details below the map |
+| click a node | pin it — details stay resident after the mouse leaves |
+| click empty space / `Esc` | unpin; with nothing pinned, `Esc` climbs out of a dive |
+| wheel / `+` `-` | zoom, anchored on the focused node (see the ladder below) |
+| left-drag | grab and pan when the map outgrows the pane |
+| shift+wheel | scroll vertically |
+| `hjkl` / arrows | nudge the view |
+| `Tab` / `Shift+Tab` / `1-9` / click a tab | switch pages (parallel maps) |
+| double-click a `⊞` node | dive into its sub-map (a child page) |
+| `Backspace` / `Esc` | climb back out of the last dive |
+| drag the `⋯` divider | resize the detail panel — pull it up to read long design notes in full |
+| `0` | reset pan and zoom |
+| `q` | quit the pane |
+
+Zooming scales the picture first and switches display mode only at the ends
+of the ladder, so every level still shows meaningful data:
+
+```
+detail ← 100% ← 85% ← 70% ← 55% ← overview
+```
+
+- **zoom in past 100%** — evidence and design notes unfold inside the boxes;
+- **85–55%** — whitespace tightens and labels truncate proportionally, boxes
+  stay boxes;
+- **below 55%** — labels would stop meaning anything, so the map AGGREGATES:
+  each declared group (a labeled subsystem within a band) becomes one box
+  named `foundation subsystem 1/2` with its status derived from the members, edges
+  collapse onto the groups, ungrouped nodes stay themselves. Like a real
+  map, zooming out shows province names — not anonymous dots. (A map with
+  no groups falls back to a pure glyph constellation with per-band counts.)
+  The footer always names the level.
+
+The two detail rows live at a fixed spot between map and hint line, showing
+the focused node's status, layer, evidence and both wire directions
+(`uses → … · used by ← …`) — nothing ever floats over the map.
+
+`--no-mouse` disables mouse reporting if your terminal multiplexer wants the
+mouse for itself.
+
+### Pages
+
+A project can keep several maps side by side — **one effort = one page**.
+Claude targets a page by passing `page` to any `mmap_*` tool; the pane grows
+a tab bar as soon as a second page exists. The active tab is bold in its
+map's aggregate status color; when a background page's file changes, its tab
+lights up in status color instead of stealing your view. Each page remembers
+its own pan, zoom and pinned node. Because every page is its own file, two
+Claude sessions writing two pages can never clobber each other — this is
+also the answer to running several Claude sessions in one project.
+
+State lives in `.claude/mellos-mapping.json` (the default page) plus
+`.claude/mellos-mapping.pages/<page>.json` for named pages — plain JSON,
+safe to commit if you want the maps' history in git.
+
+### Diagram kinds
+
+The default kind, `dev`, is the living progress ledger described above. The
+same layered-DAG machinery also draws documentation diagrams: pass `kind`
+in `mmap_declare` and the page renders neutrally — plain solid boxes, no
+ghosts, no spinners, no progress counts.
+
+| Kind | Reading | Extras |
+| --- | --- | --- |
+| `architecture` | layered components (also module deps, call graphs) | edge labels for protocols |
+| `dataflow` | pipeline stages as layers, sources at the bottom | edge labels for the data |
+| `behavior-tree` | leaves (actions) at the bottom, root on top (also mind maps, WBS) | node kinds `selector` `sequence` `parallel` `decorator` `condition` `action` render as glyphs |
+| `sequence` | classic call/return: time flows top-down, participants as lane headers; every call and every return is an event in the acting participant's lane | `lanes` are participants; edge labels are messages |
+
+Node kinds and edge labels work on `dev` maps too. State machines are out
+of scope on purpose: transitions cycle, and edges here only point downward.
+
+### Sub-maps
+
+A node can link a child page with `submap: <page-slug>` — the pane badges it
+`⊞`; double-click dives into the child map, `Backspace` climbs back out. A
+map of maps, built entirely from pages: no new storage, no new invariants.
+Whether a node deserves a sub-map is the AI's judgment call — most don't.
+
+Sub-maps are interior detail, not siblings: a page referenced as a submap
+never occupies a tab. Inside a dive the tab row becomes a breadcrumb —
+`⌫ parent map ▸ node` — and clicking it (or `Backspace`) climbs back out.
+When a hidden sub-map changes in the background, the footer says so.
+
+## MCP tools
+
+| Tool | Purpose |
+| --- | --- |
+| `mmap_declare` | Grow the map: title, diagram kind, layer bands, lanes, groups (subsystems), nodes, edges — optionally labeled (all-or-nothing batch) |
+| `mmap_update` | Record progress: `planned → in-progress → done` (+evidence), `regressed`, group/lane membership, node kind |
+| `mmap_remove` | Revise: drop edges, nodes, groups, lanes, empty bands |
+| `mmap_view` | Render the current map as text inline (optional `zoom`) |
+
+Structural invariants enforced by the tools: layers form a total order by
+rank; every node lives in exactly one layer; edges point **strictly
+downward** — which makes the graph acyclic by construction; nodes may not
+depend on same-layer siblings (if A needs sibling B, either B is really a
+lower concept or A and B are one node).
+
+## Development
+
+```
+npm install
+npm run verify   # typecheck + tests + bundle
+```
+
+The repo is itself layered bottom-up, and each layer has its spec:
+
+| Layer | Code | Owns |
+| --- | --- | --- |
+| 0 domain | `src/domain/` | the map value, structural invariants, pure ops |
+| 1 store | `src/store/` | atomic state-file persistence, boundary validation |
+| 2 apply | `src/server/apply.ts` | tool inputs → transactional op sequences |
+| 3 server | `src/server/server.ts` | the four MCP tools over stdio |
+| 4 render | `src/render/`, `src/watch/` | ASCII renderer and the polling pane |
+
+`dist/` is committed deliberately: plugin installation clones this repo and
+runs nothing, so entry points ship bundled.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,263 @@
+# Mellos Mapping · 梅勒斯地图
+
+[![CI](https://github.com/GuangminJu/mellos-mapping/actions/workflows/ci.yml/badge.svg)](https://github.com/GuangminJu/mellos-mapping/actions/workflows/ci.yml)
+
+[English](README.md) | 简体中文
+
+给 [Claude Code](https://claude.com/claude-code) 与 Codex CLI 的自下而上
+开发实况地图，原生运行在终端里。
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: light)" srcset="docs/demo-light.svg">
+    <img alt="一张梅勒斯地图的自我构建：幽灵设计先行，spinner 逐层攀升，地基开裂向上传染，诚实修复" src="docs/demo.svg" width="620">
+  </picture>
+</p>
+
+Claude 为你构建系统时，对话旁边的分屏实时显示这个系统的**分层依赖地图**：
+最底层是原语，依赖边只允许向下指；虚线幽灵节点是已设计未实现的部分，
+转圈的是此刻正在构建的模块，实心绿色代表已构建**且已验证**。
+
+```
+  梅勒斯地图 · mellos-mapping 插件
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 编排层
+
+  ╭╌╌╌╌╌╌╌╌╌╌╌╌╌╌╮
+  ╎ · MCP Server ╎
+  ╰╌╌╌┬┬╌╌╌╌┬╌╌╌╌╯
+      ││    │
+      └┼────┼───────────┐
+       │    └───┐       │
+       │        │       │
+━━━━━━━┿━━━━━━━━┿━━━━━━━┿━━━ 契约层
+       │        │       │
+  ┏━━━━┷━━━━━━━┓│ ╭╌╌╌╌╌┴╌╌╌╌╌╮
+  ┃ ■ 状态存储 ┃│ ╎ · Watcher ╎
+  ┗━━━━━┯━━━━━━┛│ ╰╌╌╌╌╌╌┬╌╌╌╌╯
+        │       │        │
+        │ ┌─────┘        │
+        │ │              │
+━━━━━━━━┿━┿━━━━━━━━━━━━━━┿━━ 原语层
+        │ │              │
+  ┏━━━━━┷━┷━━━━━━┓  ╭────┴────────╮
+  ┃ ■ 图领域模型 ┃  │ ⠋ ASCII渲染 │
+  ┗━━━━━━━━━━━━━━┛  ╰─────────────╯
+
+  · planned   ⠋ in-progress   ■ done   ✗ regressed
+```
+
+在真实终端里，连线和层级横条以暗色渲染，节点盒子按状态发光、标签加粗——
+像一块黑色电路板，元件是亮的。跨层的边会从中间层的盒子缝隙里穿过去
+（看上图 状态存储 和 Watcher 之间下潜的那根线）；互不重叠的走线段共享
+轨道行，让层与层贴得更近。
+
+*（这就是本插件自己的地图，开发中途的样子。转圈的 spinner 是真的在转。）*
+
+## 为什么
+
+大多数进度汇报是一张任务清单——那是自上而下的世界观。梅勒斯地图反过来生长：
+上层节点只能站在下层节点之上，这张图让纪律变得可见：
+
+- **代码写出来之前，幽灵设计先出现。** Claude 先把完整的设计声明成虚线
+  幽灵节点；你可以在它还只是一张图的时候就否掉一个坏设计。
+- **spinner 在哪，Claude 的注意力就在哪。** 一眼回答"它现在在做什么、
+  站在什么之上？"
+- **done 意味着已验证。** 节点只有带着证据（一次通过的测试）才会变成
+  实心绿色。如果后续工作弄裂了地基，那个节点会变红——转圈的上层楼板
+  下面压着一块红色地基，是最诚实的状态汇报。
+- **地图是账本，不是法官。** 工具只拒绝结构性破坏（向上指的边、重复的
+  rank）。工作流是 Claude 的纪律，写在随插件捆绑的 skill 里；违反纪律
+  会被*看见*，而不是被悄悄拦截。
+
+## 安装
+
+在 Claude Code 对话里输入两行：
+
+```
+/plugin marketplace add GuangminJu/mellos-mapping
+/plugin install mellos-mapping@mellos-mapping
+```
+
+或者在终端里一条命令装完：
+
+```
+claude plugin marketplace add GuangminJu/mellos-mapping && claude plugin install mellos-mapping@mellos-mapping
+```
+
+需要 PATH 上有 Node.js 18+（Claude Code 本身就依赖 Node，所以你已经有了）。
+没有构建步骤：MCP 服务器和 watcher 都已预打包在 `dist/` 里，克隆即用。
+
+## 更新
+
+```
+claude plugin marketplace update mellos-mapping && claude plugin update mellos-mapping@mellos-mapping
+```
+
+要两步是因为 `plugin update` 只对比本地缓存的 marketplace 克隆——真正
+拉取本仓库的是第一条命令。重启 Claude Code 生效。发布即 `master` 分支
+上的版本号提升。（在对话里输入 `/plugin` 也能打开同一个管理界面。）
+
+## Codex CLI
+
+同一个仓库也是 Codex 插件（codex-cli 0.147+）。三行装完：
+
+```
+codex plugin marketplace add GuangminJu/mellos-mapping
+codex plugin add mellos-mapping@mellos-mapping
+node ~/.codex/plugins/cache/mellos-mapping/mellos-mapping/<版本>/scripts/codex-register.mjs
+```
+
+前两行把技能（地图纪律）装成 Codex 插件。第三行在用户级注册 MCP
+服务器——必须这么做，因为 Codex 把插件自带的 MCP 服务器拉起在插件缓存里，
+且不给它任何感知工作区的途径，捆绑的服务器会把地图写进缓存。脚本写入的
+用户级 `codex mcp add` 条目会继承每个会话的工作目录：状态文件落在你的
+项目里，与 Claude Code 下行为一致。注册的是版本相关的绝对路径——插件
+更新后重跑一次脚本即可。
+
+要在 Codex 会话旁边看实况面板，在项目目录下的第二个终端（或任意分屏）
+运行 `node <插件根>/dist/watch.mjs`。
+
+## 任意 MCP 客户端
+
+服务器已发布到 npm，任何 MCP 客户端（Cursor、Windsurf、Zed、Gemini
+CLI……）都能用标准 stdio 条目接入：
+
+```
+npx -y mellos-mapping
+```
+
+地图文件落在客户端会话的工作目录（`.claude/mellos-mapping.json`）。在同
+一项目里打开实况面板：
+
+```
+npx -y -p mellos-mapping mellos-mapping-watch
+```
+
+技能/纪律层是 Claude Code 与 Codex 专属的；其他客户端获得四个 `mmap_*`
+工具和面板，提示词自备。
+
+## 使用
+
+1. 让 Claude 构建一个非平凡的东西。捆绑的 skill 会让 Claude 先声明幽灵
+   设计，并在工作过程中保持地图与现实一致。
+2. 运行 `/mellos-mapping:mmap` 打开实况分屏（Windows 上是 Windows
+   Terminal 分屏，tmux 里是 tmux 分屏，其他环境会打印一条命令让你在
+   第二个终端里运行）。字体缺少制表符字形时用 `--ascii`。
+3. 看着节点从底部一路亮起。图让你不安的时候就打断它——这正是它存在的
+   意义。
+
+分屏支持鼠标（xterm SGR any-event 协议——htop 和 tmux 说的同一种话）：
+
+| 输入 | 动作 |
+| --- | --- |
+| 悬停节点 | 高亮它的关系线；在地图下方预览节点详情 |
+| 点击节点 | 钉住——鼠标移开后详情仍然常驻 |
+| 点击空白 / `Esc` | 取消钉住；无钉住时 `Esc` 从下潜返回 |
+| 滚轮 / `+` `-` | 缩放，以焦点节点为锚（阶梯见下） |
+| 按住左键拖动 | 地图超出面板时抓取平移 |
+| shift+滚轮 | 垂直滚动 |
+| `hjkl` / 方向键 | 微移视口 |
+| `Tab` / `Shift+Tab` / `1-9` / 点击标签 | 切换页（并行的多张地图） |
+| 双击带 `⊞` 的节点 | 下潜进它的子图（一个子页面） |
+| `Backspace` / `Esc` | 从上一次下潜爬回父图 |
+| 拖动 `⋯` 分隔线 | 调整详情面板高度——向上拉，完整阅读长设计笔记 |
+| `0` | 重置平移和缩放 |
+| `q` | 退出面板 |
+
+缩放先做几何缩小，只在阶梯两端才切换显示模式——每一级都能看到有意义的
+数据：
+
+```
+细读 ← 100% ← 85% ← 70% ← 55% ← 概览
+```
+
+- **放大过 100%**——验证证据和设计笔记直接在盒子里展开；
+- **85–55%**——留白收紧、标签按比例截断，盒子还是盒子；
+- **低于 55%**——标签已短到无意义，此时地图**聚合**：每个已声明的分组
+  （层内的具名子系统）变成一个盒子，如 `地基子系统 1/2`，状态由成员推导，
+  边收拢到分组上，未分组节点保持原样。就像真地图缩小后显示省名，而不是
+  把城市变成无名光点。（没有声明分组的地图退化为纯字形星座 + 每层计数。）
+  页脚始终显示当前级别。
+
+详情面板固定在地图和提示行之间，显示焦点节点的状态、所在层、验证证据、
+两个方向的连线（`uses → … · used by ← …`）以及设计笔记——任何东西都
+不会悬浮遮挡地图。
+
+`--no-mouse` 关闭鼠标上报，把鼠标留给你的终端复用器。
+
+### 页
+
+一个项目可以并排保有多张地图——**一个工作努力 = 一页**。Claude 在任何
+`mmap_*` 工具里传 `page` 参数即可定向到某页；出现第二页时面板顶部自动长出
+标签栏。当前页加粗、按整图状态着色；后台页的文件有变化时，它的标签会亮起
+状态色提示你，而不是抢走你的视线。每页记住自己的平移/缩放/钉住状态。因为
+每页就是一个独立文件，两个 Claude 会话各写各页永远不会互相覆盖——这也是
+同一项目里跑多个 Claude 会话的正确姿势。
+
+地图状态存在 `.claude/mellos-mapping.json`（默认页）和
+`.claude/mellos-mapping.pages/<页名>.json`（命名页）——纯 JSON，想在 git
+里留下地图的历史就把它们提交进去。
+
+### 图种
+
+缺省图种 `dev` 就是上文那本活的进度账本。同一套分层 DAG 机器也能画文档型
+图：在 `mmap_declare` 里传 `kind`，该页即以中性方式渲染——素色实线盒子，
+没有幽灵、没有 spinner、不数进度。
+
+| 图种 | 读法 | 专属能力 |
+| --- | --- | --- |
+| `architecture` | 分层组件（也适合模块依赖、调用图） | 边标签标协议 |
+| `dataflow` | 管线阶段即层，源头在最底 | 边标签标数据 |
+| `behavior-tree` | 叶子（动作）在最底，根在顶（也适合思维导图、WBS） | 节点 kind `selector` `sequence` `parallel` `decorator` `condition` `action` 渲染为字形 |
+| `sequence` | 经典的调用/返回时序：时间自上而下流，参与者是顶部泳道表头；每次进入和每次返回都是"当事参与者泳道里"的一个事件 | `lanes` 即参与者泳道；边标签即消息 |
+
+节点 kind 和边标签在 `dev` 图上同样可用。状态机是有意不支持的：状态迁移
+成环，而这里的边只许向下。
+
+### 子图
+
+节点可以用 `submap: <页名>` 链接一个子页面——面板给它戴上 `⊞` 徽标；双击
+下潜进子图，`Backspace` 爬回父图。图中图，完全由页组合而成：没有新存储、
+没有新不变量。一个节点值不值得配子图，由 AI 自行判断——大多数不需要。
+
+子图是节点的内部细节，不是兄弟页：被引用为子图的页**不占标签栏**。下潜
+之后标签行变成面包屑——`⌫ 父图 ▸ 节点`——点击它（或按 `Backspace`）爬
+回去。隐藏的子图在后台有变化时，底栏会提示。
+
+## MCP 工具
+
+| 工具 | 用途 |
+| --- | --- |
+| `mmap_declare` | 生长地图：标题、图种、层级横条、泳道、分组（子系统）、节点、边（可带标签；批量，全有或全无） |
+| `mmap_update` | 记录进度：`planned → in-progress → done`（附证据）、`regressed`、分组/泳道归属、节点 kind |
+| `mmap_remove` | 修订：删除边、节点、分组、泳道、空层 |
+| `mmap_view` | 把当前地图渲染成文本，直接在对话里看（可选 `zoom` 参数） |
+
+工具强制的结构不变量：层按 rank 构成全序；每个节点恰好属于一层；边**严格
+向下**——因此图从构造上就是无环的；节点不能依赖同层兄弟（如果 A 需要
+兄弟 B，要么 B 其实是更低层的概念，要么 A 和 B 本来就是一个节点）。
+
+## 开发
+
+```
+npm install
+npm run verify   # 类型检查 + 测试 + 打包
+```
+
+这个仓库本身就是自下而上分层的，每一层都有自己的规格测试：
+
+| 层 | 代码 | 职责 |
+| --- | --- | --- |
+| 0 domain | `src/domain/` | 地图值、结构不变量、纯操作 |
+| 1 store | `src/store/` | 原子化状态文件持久化、边界校验 |
+| 2 apply | `src/server/apply.ts` | 工具输入 → 事务性操作序列 |
+| 3 server | `src/server/server.ts` | stdio 上的四个 MCP 工具 |
+| 4 render | `src/render/`、`src/watch/` | ASCII 渲染器和轮询面板 |
+
+`dist/` 是刻意提交的：插件安装就是克隆本仓库、不运行任何东西，所以入口
+文件以打包形式随仓库分发。
+
+## 许可证
+
+MIT