mellos-mapping 0.20.3 → 0.22.1

package/README.md

@@ -1,16 +1,20 @@
 # 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)
+[![npm](https://img.shields.io/npm/v/mellos-mapping?logo=npm&logoColor=white&label=npm&color=cb3837)](https://www.npmjs.com/package/mellos-mapping)
+[![downloads](https://img.shields.io/npm/dm/mellos-mapping?label=downloads&color=cb3837)](https://www.npmjs.com/package/mellos-mapping)
+[![MCP registry](https://img.shields.io/badge/MCP_registry-listed-2f6feb)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.GuangminJu/mellos-mapping)
+[![CI](https://img.shields.io/github/actions/workflow/status/GuangminJu/mellos-mapping/ci.yml?branch=main&label=CI)](https://github.com/GuangminJu/mellos-mapping/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-444)](LICENSE)
 
 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.
+[Claude Code](https://claude.com/claude-code), ChatGPT desktop Codex mode 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">
+    <img alt="One declare puts the whole ghost design on screen, then the nodes light up from the bottom — a foundation cracks, the damage spreads upward, and green is earned back" src="docs/demo.svg" width="620">
   </picture>
 </p>
 
@@ -20,42 +24,12 @@ 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.
+<p align="center">
+  <img alt="A Claude Code session with the Mellos map pane beside it: a six-layer game engine design, L0 and L1 nodes solid green, the upper layers still dashed ghost nodes" src="docs/session-claude-code.png">
+</p>
 
-*(This is the plugin's own map, mid-development. The spinner really spins.)*
+*A real session: Claude Code on the left, the map pane on the right. L0 is
+verified, L1 just lit up, everything above is still a ghost.*
 
 ## Why
 
@@ -79,6 +53,21 @@ picture makes the discipline visible:
 
 ## Install
 
+Clone the branch for your host, then run one command. No build is required.
+
+| Branch | Audience | Command from the clone |
+| --- | --- | --- |
+| `main` | Shared source / either host | `node install.mjs chatgpt-app` or `node install.mjs claude` |
+| `claude` | Claude Code | `node install.mjs` |
+| `chatgpt-app` | ChatGPT desktop, Codex mode | `node install.mjs` |
+
+Requires Node.js 18+ and the corresponding host CLI on PATH. The installer checks
+release integrity and all six MCP tools, retains the runtime outside the clone,
+and configures the host. Start a new conversation after installation.
+See [release and branch instructions](docs/releasing.md).
+
+Claude Code's marketplace installation is also available:
+
 Two lines inside any Claude Code conversation:
 
 ```
@@ -92,8 +81,7 @@ 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: `dist/` is committed, so a clone runs as-is —
+Requires Node.js 18+ on PATH (install Node separately when using native Claude Code). No build step: `dist/` is committed, so a clone runs as-is —
 `dist/server.mjs` (the MCP server), `dist/watch.mjs` (the pane),
 `dist/mmap.mjs` (the `mmap` toggle), `dist/hook-session-start.mjs` (the
 `SessionStart` hook that `hooks/hooks.json` registers) and
@@ -139,7 +127,7 @@ claude plugin marketplace update mellos-mapping && claude plugin update mellos-m
 
 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`.
+Restart Claude Code to apply. Releases are version bumps on `main`.
 (In-app, `/plugin` opens the same management UI.)
 
 ### Upgrading from 0.19
@@ -166,31 +154,34 @@ That one move is the only time either process touches `.claude/`. Afterwards
 the tools write nowhere but `.mellos/`, and never outside the project
 directory they resolved at startup.
 
-## Codex CLI
+## ChatGPT App · Codex mode
 
-The same repo doubles as a Codex plugin (codex-cli 0.147+). Three lines:
+This is Codex mode in the ChatGPT desktop app (also called Codex App).
+From the source branch run the following command; on `chatgpt-app`, omit the
+host argument. It configures the desktop skill, marketplace and six MCP tools.
 
 ```
-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
+node install.mjs chatgpt-app
 ```
 
-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 on Windows, run
+Start a new conversation. The desktop skill defaults to **web-terminal**:
+`mmap_open {surface: "web-terminal", page: "<slug>"}` starts a local service,
+then the AI opens its URL in the current conversation's right browser panel.
+The mmap terminal starts automatically, with its own font-size selector;
+no manual paste or Computer Use is needed. Graphical SVG, native terminal and
+Markdown remain available. With an older MCP schema, run
+`node "<plugin root>/dist/web.mjs" "<project>" --terminal --page <slug>`.
+A queued panel request does not prove that the user can see it.
+See [desktop installation and limitations](docs/codex.md).
+
+For Codex CLI inside Windows Terminal (not the desktop integrated terminal), run
 `node <plugin root>/scripts/open-pane.mjs <project dir>` — it splits the
-terminal window hosting the session (or falls back to a dedicated
-"mellos-mapping" window; `--window` picks that on purpose). Add
+terminal window hosting the session, keeping keyboard focus on the conversation.
+If that window cannot be identified or focused, it reports failure without
+opening elsewhere. `--window` explicitly chooses a separate window. Add
 `--page <slug>` to open on a particular page — and with a pane already open,
-rerunning with `--page` retargets it instead of opening another. The pane
+rerunning with `--page` retargets the pane belonging to this console. A map
+open in another session or a separate window does not count as this split. The pane
 auto-follows the page being written — the map the agent is operating on
 right now; press `f` to toggle that (a manual page switch also turns it
 off), or start with `--no-follow`. Elsewhere run
@@ -198,6 +189,32 @@ off), or start with `--no-follow`. Elsewhere run
 terminal (or any terminal split). Both take the same flags — see
 [Pane flags](#pane-flags).
 
+### Desktop Markdown map
+
+When the user chooses the document surface, the skill uses
+`mmap_open {surface: "markdown", page: "<slug>"}` and opens the returned file
+beside the current conversation. The document embeds a colored SVG dependency
+map plus module details, evidence, and child-page links. It needs no web server,
+browser rendering process, Mermaid support, or additional runtime dependencies.
+
+Successful MCP map writes regenerate enabled previews in `.mellos/previews/`;
+JSON remains the source of truth. Image nodes are static. File visibility and
+automatic viewer refresh belong to the desktop host. See the
+[desktop map guide](docs/codex.md#desktop-right-side-map) for regeneration,
+cache behavior, and limitations.
+
+### Optional interactive web viewer
+
+An additional interactive web viewer is available with
+`mmap_open {surface: "web", page: "<slug>"}` or
+`node "<plugin root>/dist/web.mjs" "<project directory>" --page <slug>`.
+Open its returned URL in the host's right browser panel. It provides live
+updates, pan/zoom, hover and pinned details, search, dependency highlighting,
+filters, group overview, submaps and themes. Stop it with
+`node "<plugin root>/dist/web.mjs" "<project directory>" --stop`.
+Markdown/SVG and terminal workflows remain available; all surfaces share the
+same map data. See [web viewer details](docs/codex.md#optional-interactive-web-viewer).
+
 ## Any MCP client
 
 The server ships on npm, so any MCP client (Cursor, Windsurf, Zed,
@@ -222,7 +239,7 @@ servers), then the server process's own working directory. Set
 somewhere other than the project you are working in.
 
 The skill/discipline layer is Claude Code + Codex specific; other clients
-get the five `mmap_*` tools and the pane, and bring their own prompting.
+get the six `mmap_*` tools and the pane, and bring their own prompting.
 
 ## Use
 
@@ -241,6 +258,25 @@ get the five `mmap_*` tools and the pane, and bring their own prompting.
 3. Watch nodes light up from the bottom. Interrupt when the picture worries
    you — that is what it is for.
 
+On Linux and macOS, `mmap_open` and `mmap` automatically use tmux. The launcher
+targets the inherited `TMUX`/`TMUX_PANE`; if the tool process lost those variables,
+it discovers the single attached session on the default tmux server. The default
+is a right split that preserves input focus; `--window` creates a new tmux window.
+Repeated opens reuse the watcher bound to that source pane or session window.
+
+For multiple attached sessions or a custom tmux socket, set these variables in
+the environment of the MCP server (restart it after changing them):
+
+| Variable | Meaning |
+| --- | --- |
+| `MELLOS_MAPPING_TMUX_TARGET` | Explicit tmux session or pane, such as `work:2.1` or `%7` |
+| `MELLOS_MAPPING_TMUX_SOCKET` | Absolute socket path, for example `/tmp/my-tmux/socket` |
+
+Ambiguous sessions, detached sessions and missing tmux produce a concrete error
+and a fully quoted watcher command, including the project and requested page,
+to paste into any visible terminal. Map writes remain available; after an open
+failure the assistant retries only when the environment changes or you ask.
+
 The pane is mouse-aware (xterm SGR any-event tracking — the same protocol
 htop and tmux speak):
 
@@ -323,7 +359,7 @@ them verbatim and rejects anything it does not know rather than dropping it.
 
 | Flag | Effect |
 | --- | --- |
-| `--page <slug>` | open on this page; with a pane already running, retarget that pane instead of opening another |
+| `--page <slug>` | open on this page; with this console’s pane already running, retarget it instead of opening another |
 | `--ascii` | pure-ASCII repertoire, for fonts without box-drawing glyphs |
 | `--no-color` | no ANSI color |
 | `--no-mouse` | no mouse reporting, if your terminal multiplexer wants the mouse for itself |
@@ -336,6 +372,13 @@ though one is already running for this project. Watcher-only: `--file <path>`
 names the default page's state file (the launcher derives it from the project
 directory).
 
+Pane ownership is carried by the internal watcher flag `--owner <token>` and
+the optional `owner` field in viewer reports. Launchers derive the token from
+the source console process and its creation time; manual watchers can omit it.
+Focus and quit requests to a bound viewer use its PID, so another window of
+the same project cannot consume them. Bare `mmap` toggles only the pane bound
+to the current console; `mmap --window` toggles the separate project window.
+
 ### The mmap command
 
 `mmap`, typed in any terminal, is a **toggle**: it opens the map pane for the
@@ -472,7 +515,10 @@ mean:
 - **control characters** in text fields — an ESC sequence stored in a label
   would let a map repaint the terminal of everyone who opens it. `detail` is
   the exception: newlines and tabs are how a note is written, everything else
-  (ESC, BEL, lone CR) is still refused;
+  (ESC, BEL, lone CR) is still refused. File loading and library saves apply
+  the same control-character rules, retaining multiline evidence in older
+  files. Terminal rendering also neutralizes controls in maps constructed
+  directly by library callers;
 - **an empty string** where a field is optional — `null` is how a field is
   cleared, never a blank that renders as a box nobody can tell from a real
   one;
@@ -500,7 +546,7 @@ ends with what those reports say:
 | The line | What it means |
 | --- | --- |
 | `pane: CLOSED` | nobody is seeing this map; the assistant opens one with `mmap_open` instead of asking you to |
-| `pane: open on this page` | you are watching this land |
+| `pane: running on this page` | a live process reports this page; its terminal may be hidden |
 | `pane: open on <other>, auto-follow on` | the pane follows the page last written, so it arrives here by itself |
 | `pane: open on <other>, auto-follow OFF` | you pinned that page by hand: the change is real and NOT on your screen. The assistant is told to say so rather than move your view |
 
@@ -510,6 +556,11 @@ not say which page was on screen. A report whose pane stopped refreshing it is
 ignored after five seconds and deleted after a minute, so a killed pane cannot
 go on claiming an audience.
 
+A heartbeat does not establish screen visibility. An explicit tmux open also
+selects the existing watcher's window, reveals it if another pane was zoomed,
+and verifies the attached session's active window before reporting visibility.
+Focusing that watcher in a shell without `TMUX` reuses its original owner.
+
 ### Setup: choose when maps open
 
 How eager mapping should be is a habit, not a property of a repository — so it
@@ -551,15 +602,18 @@ render as boxes and one id must mean one box.
 
 ## Development
 
+See [contributing](CONTRIBUTING.md) and the
+[project structure, branch and recovery guide](docs/project-maintenance.md).
+
 ```
-npm install
+npm ci
 npm run verify
 ```
 
-`verify` is four steps, in this order: `typecheck`, `test`, `build` (bundles
-`dist/`, emits `lib/` with declarations, cleaning both first), and
-`check:package` — which packs the tarball through the real `prepack`
-lifecycle and fails if any `exports` or `bin` target is missing from it.
+Use Node.js 22.12+ for development. `verify` runs `typecheck`, `test`, `build`
+(bundles `dist/` and emits `lib/` with declarations), `check:package`,
+`check:codex`, and `check:release`. These check npm entrypoints, the Codex
+package and both installable editions, including their MCP handshake.
 
 The repo is itself layered bottom-up, and each layer has its spec:
 
@@ -570,7 +624,7 @@ The repo is itself layered bottom-up, and each layer has its spec:
 | 1 store | `src/store/store.ts` | `store.test.ts`, `atomic-save.test.ts` | atomic state-file persistence on Node |
 | 1 semantics | `src/semantics/` | `semantics.test.ts` | medium-neutral view semantics: zoom ladder, group aggregation, page-set rules, sequence flip, the shared glyph vocabulary |
 | 2 apply | `src/server/apply.ts` | `apply.test.ts` | tool inputs → transactional op sequences |
-| 3 server | `src/server/server.ts` | `server.test.ts`, `save-failure.test.ts` | the five MCP tools over stdio |
+| 3 server | `src/server/server.ts` | `server.test.ts`, `save-failure.test.ts` | the six MCP tools over stdio |
 | 4 render | `src/render/` | `render.test.ts`, `routing.test.ts` | the ASCII renderer and its wire routing |
 | 4 pane | `src/watch/` | `watch.test.ts`, `pane-state.test.ts`, `input.test.ts` | the polling pane: page set, input parsing, panel and chrome |
 | — launchers | `scripts/` | `open-pane.test.mjs`, `codex-register.test.mjs` | plain-node entry points |

package/README.zh-CN.md

@@ -1,16 +1,20 @@
 # 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)
+[![npm](https://img.shields.io/npm/v/mellos-mapping?logo=npm&logoColor=white&label=npm&color=cb3837)](https://www.npmjs.com/package/mellos-mapping)
+[![downloads](https://img.shields.io/npm/dm/mellos-mapping?label=downloads&color=cb3837)](https://www.npmjs.com/package/mellos-mapping)
+[![MCP registry](https://img.shields.io/badge/MCP_registry-listed-2f6feb)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.GuangminJu/mellos-mapping)
+[![CI](https://img.shields.io/github/actions/workflow/status/GuangminJu/mellos-mapping/ci.yml?branch=main&label=CI)](https://github.com/GuangminJu/mellos-mapping/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-444)](LICENSE)
 
 [English](README.md) | 简体中文
 
-给 [Claude Code](https://claude.com/claude-code) 与 Codex CLI 的自下而上
+给 [Claude Code](https://claude.com/claude-code) 、ChatGPT 桌面 Codex 模式与 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">
+    <img alt="一次 declare 铺开整张幽灵设计，节点自下而上逐个点亮 —— 地基开裂向上传染，绿色再被挣回来" src="docs/demo.svg" width="620">
   </picture>
 </p>
 
@@ -18,41 +22,11 @@ Claude 为你构建系统时，对话旁边的分屏实时显示这个系统的*
 最底层是原语，依赖边只允许向下指；虚线幽灵节点是已设计未实现的部分，
 转圈的是此刻正在构建的模块，实心绿色代表已构建**且已验证**。
 
-```
-  梅勒斯地图 · mellos-mapping 插件
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 编排层
-
-  ╭╌╌╌╌╌╌╌╌╌╌╌╌╌╌╮
-  ╎ · MCP Server ╎
-  ╰╌╌╌┬┬╌╌╌╌┬╌╌╌╌╯
-      ││    │
-      └┼────┼───────────┐
-       │    └───┐       │
-       │        │       │
-━━━━━━━┿━━━━━━━━┿━━━━━━━┿━━━ 契约层
-       │        │       │
-  ┏━━━━┷━━━━━━━┓│ ╭╌╌╌╌╌┴╌╌╌╌╌╮
-  ┃ ■ 状态存储 ┃│ ╎ · Watcher ╎
-  ┗━━━━━┯━━━━━━┛│ ╰╌╌╌╌╌╌┬╌╌╌╌╯
-        │       │        │
-        │ ┌─────┘        │
-        │ │              │
-━━━━━━━━┿━┿━━━━━━━━━━━━━━┿━━ 原语层
-        │ │              │
-  ┏━━━━━┷━┷━━━━━━┓  ╭────┴────────╮
-  ┃ ■ 图领域模型 ┃  │ ⠋ ASCII渲染 │
-  ┗━━━━━━━━━━━━━━┛  ╰─────────────╯
-
-  · planned   ⠋ in-progress   ■ done   ✗ regressed
-```
-
-在真实终端里，连线和层级横条以暗色渲染，节点盒子按状态发光、标签加粗——
-像一块黑色电路板，元件是亮的。跨层的边会从中间层的盒子缝隙里穿过去
-（看上图 状态存储 和 Watcher 之间下潜的那根线）；互不重叠的走线段共享
-轨道行，让层与层贴得更近。
+<p align="center">
+  <img alt="Claude Code 会话旁边的梅勒斯地图面板：六层游戏引擎设计，L0 与 L1 节点实心绿色，上面几层仍是虚线幽灵节点" src="docs/session-claude-code.png">
+</p>
 
-*（这就是本插件自己的地图，开发中途的样子。转圈的 spinner 是真的在转。）*
+*真实会话：左边 Claude Code，右边地图面板。L0 已验证，L1 刚点亮，上面还是幽灵节点。*
 
 ## 为什么
 
@@ -72,6 +46,20 @@ Claude 为你构建系统时，对话旁边的分屏实时显示这个系统的*
 
 ## 安装
 
+克隆适合自己宿主的分支，运行一个安装命令即可；无需构建。
+
+| 分支 | 使用对象 | 在克隆目录运行 |
+| --- | --- | --- |
+| `main` | 共用源码／任一宿主 | `node install.mjs chatgpt-app` 或 `node install.mjs claude` |
+| `claude` | Claude Code | `node install.mjs` |
+| `chatgpt-app` | ChatGPT 桌面 App 的 Codex 模式 | `node install.mjs` |
+
+前置要求为 Node.js 18+ 和对应宿主的 CLI，并确保命令在 PATH 中。安装器检查
+发行文件和六个 MCP 工具，将运行时保留到克隆目录之外，完成宿主配置。
+安装后开启新对话。详见[发布与分支说明](docs/releasing.md)。
+
+Claude Code 也可以通过插件市场安装：
+
 在 Claude Code 对话里输入两行：
 
 ```
@@ -125,7 +113,7 @@ claude plugin marketplace update mellos-mapping && claude plugin update mellos-m
 ```
 
 要两步是因为 `plugin update` 只对比本地缓存的 marketplace 克隆——真正
-拉取本仓库的是第一条命令。重启 Claude Code 生效。发布即 `master` 分支
+拉取本仓库的是第一条命令。重启 Claude Code 生效。发布即 `main` 分支
 上的版本号提升。（在对话里输入 `/plugin` 也能打开同一个管理界面。）
 
 ### 从 0.19 升级
@@ -149,34 +137,71 @@ the move.`）：
 这一次搬迁是两个进程唯一会碰 `.claude/` 的时刻。此后工具只往 `.mellos/`
 里写，也绝不会写到启动时解析出的项目目录之外。
 
-## Codex CLI
+## ChatGPT App · Codex 模式
 
-同一个仓库也是 Codex 插件（codex-cli 0.147+）。三行装完：
+本版用于 ChatGPT 桌面 App 的 Codex 模式（也称 Codex App）。在源码分支运行
+以下命令；在 `chatgpt-app` 分支运行时省略宿主参数。它会一次配置桌面专用技能、
+插件市场与六个 MCP 工具。
 
 ```
-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
+node install.mjs chatgpt-app
 ```
 
-前两行把技能（地图纪律）装成 Codex 插件。第三行在用户级注册 MCP
-服务器——必须这么做，因为 Codex 把插件自带的 MCP 服务器拉起在插件缓存里，
-且不给它任何感知工作区的途径，捆绑的服务器会把地图写进缓存。脚本写入的
-用户级 `codex mcp add` 条目会继承每个会话的工作目录：状态文件落在你的
-项目里，与 Claude Code 下行为一致。注册的是版本相关的绝对路径——插件
-更新后重跑一次脚本即可。
+安装完成后开启新对话。技能默认使用 **web-terminal 网页终端**：
+`mmap_open {surface: "web-terminal", page: "<slug>"}` 启动本地服务后，
+AI 自动把 URL 打开到当前对话右侧浏览器，直接显示 mmap 终端地图。
+不需要粘贴命令或 Computer Use；网页有独立字号调节。
+图形 SVG 网页、原生终端和 Markdown 仍然保留。旧 MCP 对话可使用
+`node "<插件根>/dist/web.mjs" "<项目>" --terminal --page <slug>`。
+面板排队打开不等于地图已经可见。
+详见[桌面安装与限制](docs/codex.md)。
 
-要在 Codex 会话旁边看实况面板，Windows 上运行
+在 Windows Terminal 使用 Codex CLI 时（不指桌面 App 内置终端），运行
 `node <插件根>/scripts/open-pane.mjs <项目目录>`——它会在承载本会话的
-终端窗口里分屏（识别不到就确定性地开到专属的 "mellos-mapping" 窗口；
-`--window` 则是主动选择专属窗口）。加 `--page <slug>` 指定打开哪一页；
-面板已经开着时，带 `--page` 重跑一次不会再开新面板，而是让现有面板
-切到那一页。面板默认**自动跟随**正在被写入的页——AI 此刻操作哪张图，
+终端窗口右侧分屏，并保留左侧对话的键盘焦点。识别或聚焦失败时会明确报错，
+不会改开其他窗口；`--window` 用于明确选择独立窗口。加 `--page <slug>` 指定打开哪一页；
+当前会话的面板已经开着时，带 `--page` 重跑会让它切到那一页。其他会话
+或独立窗口中的面板不算当前会话已分屏。面板默认**自动跟随**正在被写入的页——AI 此刻操作哪张图，
 就看哪张图；按 `f` 开关（手动切页也会关掉），或用 `--no-follow` 启动。
 其他环境在项目目录下的第二个终端（或任意分屏）运行
 `node <插件根>/dist/watch.mjs`。两者接受同一套参数，见
 [面板参数](#面板参数)。
 
+### 桌面对话右侧：Markdown 地图
+
+用户选择文档方式时，技能会使用 `mmap_open` 的
+`surface: "markdown"`，生成地图文档后交给宿主在当前对话右侧打开。
+文档包含彩色 SVG 分层依赖图、模块状态、设计说明、验证记录和子图链接。
+不需要网页服务或 Mermaid 支持，图像放大仍保持清晰。
+
+首次打开后，本项目中成功的地图工具写入会自动重新生成预览。JSON 仍是
+唯一数据源，`.mellos/previews/` 是可重新生成的输出。图片里的节点没有
+拖拽、悬停、双击下潜和动画；用文档链接打开子图。侧栏是否自动刷新由
+桌面应用决定，生成成功不代表已显示。手动刷新或旧会话可以运行：
+
+```sh
+node "<插件根>/dist/preview.mjs" "<项目目录>" --page <页名>
+```
+
+完整说明见 [Codex 桌面地图](docs/codex.md#desktop-right-side-map)。
+
+### 可选：交互网页版
+
+现有 Markdown/SVG 用法继续保留。需要缩放拖动、悬停/固定节点详情、依赖
+高亮、搜索、状态筛选、分组概览、页面和子地图切换时，使用新增的
+`mmap_open {surface: "web", page: "<页名>"}`，将返回的网址交给宿主在右侧
+浏览器打开。网页直接读取项目地图并自动更新，也支持明暗主题和确认后删页。
+
+```sh
+node "<插件根>/dist/web.mjs" "<项目目录>" --page <页名>
+# 关闭该项目的网页服务：
+node "<插件根>/dist/web.mjs" "<项目目录>" --stop
+```
+
+服务仅在本机运行，不需要部署或下载网页依赖。Markdown 和网页共用原来的
+JSON 数据，能够同时使用；手动切页会固定当前页面。详见
+[网页版功能与运行方式](docs/codex.md#optional-interactive-web-viewer)。
+
 ## 任意 MCP 客户端
 
 服务器已发布到 npm，任何 MCP 客户端（Cursor、Windsurf、Zed、Gemini
@@ -198,7 +223,7 @@ npx -y -p mellos-mapping mellos-mapping-watch
 插件 MCP 服务器设置的约定），最后才是服务器进程自己的工作目录。如果你的
 客户端会在你实际工作的项目之外启动服务器，就设 `MELLOS_MAPPING_CWD`。
 
-技能/纪律层是 Claude Code 与 Codex 专属的；其他客户端获得五个 `mmap_*`
+技能/纪律层是 Claude Code 与 Codex 专属的；其他客户端获得六个 `mmap_*`
 工具和面板，提示词自备。
 
 ## 使用
@@ -216,6 +241,23 @@ npx -y -p mellos-mapping mellos-mapping-watch
 3. 看着节点从底部一路亮起。图让你不安的时候就打断它——这正是它存在的
    意义。
 
+在 Linux 和 macOS 上，`mmap_open` 与 `mmap` 会自动使用 tmux。启动器优先
+定位继承的 `TMUX`/`TMUX_PANE`；工具进程丢失这些变量时，会自动发现默认
+tmux 服务中唯一已连接的会话。默认在右侧分屏并保留输入焦点；`--window`
+创建一个新的 tmux 窗口。再次打开会复用属于该源面板或会话窗口的 watcher。
+
+如果有多个已连接的会话，或使用自定义 tmux socket，在 MCP 服务进程的
+环境中设置以下变量（修改后重启该进程）：
+
+| 环境变量 | 含义 |
+| --- | --- |
+| `MELLOS_MAPPING_TMUX_TARGET` | 指定 tmux 会话或面板，例如 `work:2.1` 或 `%7` |
+| `MELLOS_MAPPING_TMUX_SOCKET` | socket 的绝对路径，例如 `/tmp/my-tmux/socket` |
+
+目标不明确、会话未连接或没有安装 tmux 时，启动器会返回具体原因，以及
+包含项目、页面和正确引号的一条完整 watcher 命令，可以粘贴到可见终端。
+地图仍可正常写入；打开失败后，助手只在环境变化或你要求重试时再次打开。
+
 分屏支持鼠标（xterm SGR any-event 协议——htop 和 tmux 说的同一种话）：
 
 | 输入 | 动作 |
@@ -301,14 +343,19 @@ used by ← …`，每个邻居各带自己的状态字形），以及自动折
 watcher 的：`--file <path>` 指定默认页的状态文件（启动脚本会从项目目录
 自己推导出来）。
 
+内部 watcher 参数 `--owner <token>` 和面板报告的可选 `owner` 字段承载会话绑定。
+启动器用源控制台进程及创建时间生成身份；手动运行 watcher 可省略。切页和关闭
+请求按面板 PID 定向投递，同项目其他窗口不会抢走请求。普通 `mmap` 只切换当前
+会话的面板；`mmap --window` 切换本项目的独立窗口。
+
 ### mmap 命令
 
-在任何终端里敲 `mmap`，它是一个**开关**：本项目还没有面板就开一个，已经
-有面板就把它关掉。
+在终端里敲 `mmap`，它是当前会话地图的**开关**：本会话还没有面板就开一个，
+已经有面板就把它关掉。
 
 | 你敲的 | 发生什么 |
 | --- | --- |
-| `mmap` | 本项目没有面板在跑 → 开一个；有 → 关掉它 |
+| `mmap` | 当前会话没有面板在跑 → 开一个；有 → 关掉它 |
 | `mmap <页 slug>` | 打开时定位到这一页，或者让已开的面板切过去——永远不关 |
 | `mmap --window` | 开到专属的 "mellos-mapping" 窗口，而不是把当前窗口分屏 |
 | `mmap --force` | 即使已经有面板在跑也再开一个 |
@@ -420,7 +467,9 @@ Claude 会话的正确姿势。
   丢掉的字段；任何嵌套深度都一样；
 - 文本字段里的**控制字符**——藏在标签里的 ESC 序列，会让这张图重绘每一个
   打开它的人的终端。`detail` 是例外：换行和制表符本来就是写笔记的方式，
-  其余（ESC、BEL、单独的 CR）照样拒绝；
+  其余（ESC、BEL、单独的 CR）照样拒绝。文件加载和公共库保存也校验控制字符，
+  同时兼容旧文件中的多行证据。直接通过公共库构造地图时，终端渲染仍会消除
+  控制字符的执行效果；
 - 可选字段上的**空字符串**——清空字段用 `null`，而不是一个渲染出来跟真盒子
   分不清的空白；
 - **`submap` 指向本次调用所针对的那一页的节点**——那是个没有底的环，不是
@@ -445,7 +494,7 @@ Claude 会话的正确姿势。
 | 这一行 | 意思 |
 | --- | --- |
 | `pane: CLOSED` | 没人在看这张图；助手会用 `mmap_open` 自己开，而不是回过头来要求你开 |
-| `pane: open on this page` | 你正看着它落地 |
+| `pane: running on this page` | 活跃进程报告正在显示这一页，但终端可能被隐藏 |
 | `pane: open on <其他页>, auto-follow on` | 面板跟随最后被写入的那一页，它自己会过来 |
 | `pane: open on <其他页>, auto-follow OFF` | 那一页是你亲手钉住的：这次改动是真的，但**不在**你屏幕上。助手被要求把这件事说出来，而不是把你的视图搬走 |
 
@@ -454,6 +503,10 @@ Claude 会话的正确姿势。
 超过五秒没被刷新的报告不再算数，超过一分钟就被读到它的人删掉，所以被强杀
 的面板不会一直冒领观众。
 
+心跳不等于屏幕可见。显式调用 tmux 打开操作时，启动器还会切回已有地图所在的
+窗口，解除遮挡地图的面板缩放，并检查已连接会话的活动窗口后再报告可见。
+缺少 `TMUX` 环境变量、焦点又落在地图面板上时，会沿用原来的归属，避免重复打开。
+
 ### Setup：选择什么时候建图
 
 建图要多积极，是一个人的工作习惯，不是某个仓库的属性——所以它**只为你选
@@ -488,14 +541,16 @@ AI。从此再也不需要按项目设置什么。
 
 ## 开发
 
+先阅读[贡献说明](CONTRIBUTING.md)和[项目结构、分支与恢复指南](docs/project-maintenance.md)。
+
 ```
-npm install
+npm ci
 npm run verify
 ```
 
-`verify` 是按顺序的四步：`typecheck`、`test`、`build`（打包 `dist/`、产出带声明的 `lib/`，两个
-目录都先清空），以及 `check:package`——它按真实的 `prepack` 生命周期打出
-tarball，只要 `exports` 或 `bin` 里有任何目标没被打进去就失败。
+开发环境使用 Node.js 22.12+。`verify` 依次运行 `typecheck`、`test`、`build`
+（打包 `dist/`、产出带声明的 `lib/`）、`check:package`、`check:codex` 和
+`check:release`，检查 npm 入口、Codex 包和两个可安装发行包，包括 MCP 握手。
 
 这个仓库本身就是自下而上分层的，每一层都有自己的规格测试：
 
@@ -506,7 +561,7 @@ tarball，只要 `exports` 或 `bin` 里有任何目标没被打进去就失败
 | 1 store | `src/store/store.ts` | `store.test.ts`、`atomic-save.test.ts` | Node 上的原子化状态文件持久化 |
 | 1 semantics | `src/semantics/` | `semantics.test.ts` | 媒介无关的视图语义：缩放阶梯、分组聚合、页集规则、时序翻转、共享字形词汇表 |
 | 2 apply | `src/server/apply.ts` | `apply.test.ts` | 工具输入 → 事务性操作序列 |
-| 3 server | `src/server/server.ts` | `server.test.ts`、`save-failure.test.ts` | stdio 上的五个 MCP 工具 |
+| 3 server | `src/server/server.ts` | `server.test.ts`、`save-failure.test.ts` | stdio 上的六个 MCP 工具 |
 | 4 render | `src/render/` | `render.test.ts`、`routing.test.ts` | ASCII 渲染器与它的走线 |
 | 4 pane | `src/watch/` | `watch.test.ts`、`pane-state.test.ts`、`input.test.ts` | 轮询面板：页集、输入解析、详情面板与外框 |
 | — 启动脚本 | `scripts/` | `open-pane.test.mjs`、`codex-register.test.mjs` | 纯 node 的入口 |