mellos-mapping 0.20.3 → 0.23.0

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 eight 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 eight 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 eight `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
@@ -451,12 +494,19 @@ When a hidden sub-map changes in the background, the footer says so.
 
 ## MCP tools
 
+Start with `mmap_read` to resume an existing page; a new conversation is not a
+new effort. Use stable IDs, filtered reads and revision-checked writes. The
+[persistent-map API guide](docs/map-api.md) covers complete CRUD, atomic mixed
+batches, context checkpoints, source hashes and worktree boundaries.
+
 | Tool | Purpose |
 | --- | --- |
 | `mmap_declare` | Grow the map: title (`null` removes it), diagram kind, layer bands, lanes, groups (subsystems), nodes — with `status`, `evidence`, `detail`, `kind`, `group`, `lane`, `submap` — and edges, optionally labeled (all-or-nothing batch) |
 | `mmap_update` | Record progress **and revise**: status (`planned → in-progress → done` +evidence, `regressed`), relabel a node, move it to another band (`layer`), join/leave a group or lane, set a node kind or a `submap`; rename and re-rank bands (`layers`), relabel groups (`groups`) and lanes (`lanes`); `null` clears any clearable field |
 | `mmap_remove` | Revise: drop edges, nodes, groups, lanes, empty bands — and, with `pages`, whole pages, file and all (permanent; applied after this call's map edits) |
 | `mmap_view` | Render the current map as text inline (optional `zoom`, `-4`…`2`), ending with a `pages:` line naming every page the project has and which one you are looking at |
+| `mmap_read` | Structured page discovery, precise IDs, filtered/paginated reads, context and source changes |
+| `mmap_batch` | One-page mixed create/update/remove transaction with a revision check |
 | `mmap_setup` | Get/set the project's mapping policy — when maps open |
 | `mmap_open` | Put the map on your screen: open the pane, or retarget an open one to a `page` (`window: true` for the dedicated window). It answers with whether a pane actually reported in afterwards, not merely that a command ran — and it can never close one |
 
@@ -472,7 +522,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 +553,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 +563,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 +609,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 +631,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 eight 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 |