mellos-mapping 0.20.0 → 0.20.2

package/README.md

@@ -93,7 +93,43 @@ claude plugin marketplace add GuangminJu/mellos-mapping && claude plugin install
 ```
 
 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.
+already have it). 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
+`dist/store-paths.mjs` (the store's path vocabulary, which the plain-node pane
+launcher imports instead of restating filenames).
+
+The first session after installing asks you **one** question — how eager
+mapping should be — and records the answer for every project you will ever
+open. From then on the hook carries it into each new session by itself; there
+is no per-project setup step. See
+[Setup: choose when maps open](#setup-choose-when-maps-open).
+
+The `mmap` terminal command (the pane's open/close toggle) installs itself on
+Windows: the same hook notices on session start when the shim is missing or
+points at an older install, writes `mmap.cmd` (cmd, PowerShell) and `mmap`
+(git-bash) into `%LOCALAPPDATA%\mellos-mapping\bin`, appends that one
+directory to your **user** PATH, and tells you so through the assistant. The
+PATH change reaches only new processes — and a new tab of a running Windows
+Terminal inherits the old environment, so close the terminal app entirely and
+reopen it before the first `mmap`. The PATH edit keeps the
+installer's guarantees: nothing happens when the entry is already there, and
+a PATH that `setx` would damage (flattened `%VARIABLE%` references, truncation
+past its limit) is refused outright, with the entry to add by hand named
+instead.
+
+The step behind it is still a command of its own, for the cases the hook does
+not cover — `--uninstall`, or re-adding a PATH entry you removed while the
+shims stayed put:
+
+```
+node "<plugin dir>/scripts/install-mmap-command.mjs" [--uninstall]
+```
+
+(`--json` prints the install outcome as one JSON line instead of prose — the
+mode the hook itself calls it in.) `npm i -g mellos-mapping` provides the
+same `mmap` via `bin`, no shims involved.
 
 ## Update
 
@@ -106,6 +142,30 @@ 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.)
 
+### Upgrading from 0.19
+
+0.20 moved the store out of `.claude/` — the map belongs to this tool, not to
+one client — into `.mellos/`. The server and the watcher each perform the move
+once at startup, and print exactly one line on stderr when they do
+(`mellos-mapping: moved the legacy .claude map store to .mellos/ — commit the
+move.`):
+
+| 0.19 and earlier | 0.20 and later |
+| --- | --- |
+| `.claude/mellos-mapping.json` | `.mellos/map.json` |
+| `.claude/mellos-mapping.pages/` | `.mellos/pages/` |
+| `.claude/mellos-mapping.config.json` | `.mellos/config.json` |
+
+Nothing is merged and nothing is overwritten: a project that already has a
+`.mellos/` store (map, pages or config) is left untouched, whatever the legacy
+directory still holds. If you keep your maps in git, commit the move —
+`git add -A .claude .mellos` records it as renames rather than as a pile of
+deletions plus untracked files.
+
+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
 
 The same repo doubles as a Codex plugin (codex-cli 0.147+). Three lines:
@@ -134,8 +194,9 @@ rerunning with `--page` retargets it instead of opening another. 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
-`node <plugin root>/dist/watch.mjs` (same `--page` / `--no-follow` flags)
-from the project directory in a second terminal (or any terminal split).
+`node <plugin root>/dist/watch.mjs` from the project directory in a second
+terminal (or any terminal split). Both take the same flags — see
+[Pane flags](#pane-flags).
 
 ## Any MCP client
 
@@ -153,19 +214,30 @@ The map file lands in the client session's working directory
 npx -y -p mellos-mapping mellos-mapping-watch
 ```
 
+The server picks its project directory in this order: `MELLOS_MAPPING_CWD`
+(an explicit override, for clients that spawn servers from a fixed
+directory), then `CLAUDE_PROJECT_DIR` (what Claude Code sets for plugin MCP
+servers), then the server process's own working directory. Set
+`MELLOS_MAPPING_CWD` when your client would otherwise start the server
+somewhere other than the project you are working in.
+
 The skill/discipline layer is Claude Code + Codex specific; other clients
-get the four `mmap_*` tools and the pane, and bring their own prompting.
+get the five `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). On Windows the pane opens in the terminal window
-   hosting YOUR session, even with several windows open; pass `--window` to
-   put the map in its own dedicated window instead. Prefer `--ascii` if
-   your font lacks box-drawing glyphs.
+2. The pane opens itself. Every write tells Claude whether anybody is
+   actually looking (see [Who is watching](#who-is-watching)), and Claude
+   opens or retargets the pane with `mmap_open` when nobody is — you never
+   have to remember to. Open or close it yourself with `mmap` in any
+   terminal, or `/mellos-mapping:mmap` in the conversation (Windows
+   Terminal split on Windows, tmux split inside tmux, or a printed command
+   to run in any second terminal). On Windows the pane opens in the terminal
+   window hosting YOUR session, even with several windows open; pass
+   `--window` to put the map in its own dedicated window instead. 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.
 
@@ -180,22 +252,33 @@ htop and tmux speak):
 | 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 |
+| wheel tilt (horizontal) | pan sideways |
 | `hjkl` / arrows | nudge the view |
 | `Tab` / `Shift+Tab` / `1-9` / click a tab | switch pages (parallel maps) |
+| wheel on the tab row / click `‹` `›` | browse an overflowing tab strip without switching pages |
+| `f` | toggle auto-follow (see [Pages](#pages)) |
+| `x`, or click the `×` on the active tab | ask to delete the page on screen; press again inside the window and its file is removed (see [Pages](#pages)) |
 | 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 |
+| `q` / `Ctrl+C` | quit the pane |
+
+Every other key is inert, on purpose: an escape sequence the pane does not
+know (F-keys, Home/End, PgUp/PgDn, Insert/Delete, modified arrows) is
+consumed whole and does nothing, rather than having its payload bytes read
+as hotkeys.
 
 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
+detail+ ← detail ← 100% ← 85% ← 70% ← 55% ← overview
 ```
 
-- **zoom in past 100%** — evidence and design notes unfold inside the boxes;
+- **zoom in past 100%** — `detail` unfolds evidence and the first three lines
+  of the design notes inside the boxes; `detail+` widens them into reading
+  cards (up to twelve note rows);
 - **85–55%** — whitespace tightens and labels truncate proportionally, boxes
   stay boxes;
 - **below 55%** — labels would stop meaning anything, so the map AGGREGATES:
@@ -206,27 +289,133 @@ detail ← 100% ← 85% ← 70% ← 55% ← overview
   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.
+Below the map, between it and the hint line, sits a fixed-height detail
+panel: a separator you can drag, a status-colored header, the focused node's
+evidence, both wire directions (`uses → … · used by ← …`, each neighbour
+carrying its own status glyph) and its design notes, word-wrapped. With
+nothing focused it shows the map's dashboard instead. Fixed height — details
+never float over the map and the layout never jumps.
+
+### Glyphs
+
+One status, one glyph, everywhere a map is drawn — the pane's boxes, its tab
+strip and detail panel, and any other client reading the same store:
+
+| Unicode | ASCII | Meaning |
+| --- | --- | --- |
+| `·` | `.` | planned — declared, not started |
+| `⠿` | `*` | in-progress, at rest — a box that can animate spins through the braille frames (`⠋⠙⠹…`) instead, or a four-bar cycle in ASCII |
+| `■` | `#` | done, with evidence |
+| `□` | `o` | done, with **no** evidence recorded — same claim, nothing behind it |
+| `✗` | `X` | regressed: was done, now broken |
+| `⊞` | `+` | badge: the node links a sub-map; double-click dives in |
+
+The legend under the picture names the four statuses; `□ done, no evidence`
+joins it only on a map that actually contains one — the four are the
+vocabulary, that one is a rule being broken here and now. Documentation
+diagram kinds replace the status legend with their node-kind glyphs.
 
-`--no-mouse` disables mouse reporting if your terminal multiplexer wants the
-mouse for itself.
+### Pane flags
+
+Both the pane launcher (`scripts/open-pane.mjs <project dir>`) and the
+watcher (`dist/watch.mjs`) take the same watcher flags; the launcher forwards
+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 |
+| `--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 |
+| `--no-follow` | start with auto-follow off |
+| `--interval <ms>` | poll interval; default 250, floored at 50 |
+
+Launcher-only: `--window` opens the dedicated "mellos-mapping" window instead
+of splitting the session's window, and `--force` opens another pane even
+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).
+
+### The mmap command
+
+`mmap`, typed in any terminal, is a **toggle**: it opens the map pane for the
+project you are standing in, or closes the one that is already open.
+
+| You type | What it does |
+| --- | --- |
+| `mmap` | nothing watching this project → open the pane; something watching → close it |
+| `mmap <page-slug>` | open on that page, or retarget an already-open pane to it — never closes |
+| `mmap --window` | open in the dedicated "mellos-mapping" window instead of splitting this one |
+| `mmap --force` | open another pane even though one is already running |
+
+The project is found the way git finds its root: from the current directory
+upwards, to the nearest one holding a `.mellos/` store. Standing in a project
+that has no map yet is fine — the pane opens on its standby screen and says so
+until the first `mmap_declare`.
+
+Closing goes through the store rather than through a signal: `mmap` writes a
+one-shot request beside the map, the pane consumes it on its next poll (250 ms
+by default) and exits, handing the terminal back exactly as it found it — mouse
+reporting off, cursor visible. A pane still on the standby screen closes the
+same way. The request is deleted as it is read, and a leftover from a pane that
+died is swept when the next one starts, so a stale request can never close a
+fresh pane.
+
+Every watcher flag above works here too, forwarded verbatim; an unknown one is
+a usage error, never dropped in silence. `mmap` needs
+[installing once](#install) unless you have the npm package. Inside a Claude
+Code conversation, `/mellos-mapping:mmap` opens the same pane.
 
 ### 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 `.mellos/map.json` (the default page) plus
-`.mellos/pages/<page>.json` for named pages — plain JSON,
-safe to commit if you want the maps' history in git.
+map's aggregate status color. Each page remembers its own pan, zoom and
+pinned node.
+
+By default the pane **follows the page being written** — the map the agent is
+operating on right now — so declares and updates bring the audience along by
+themselves. `f` toggles that, a manual page switch turns it off, and
+`--no-follow` starts it off; with follow off, a background page's change
+lights its tab in status color instead of stealing your view. An explicit
+`--page` outranks follow, and a page requested before it exists is shown the
+moment it appears.
+
+**Deleting a page.** An effort ends; its page does not have to stay. In the
+pane, `x` — or the `×` the active tab carries when the mouse is on — *asks*:
+the footer says `press x again to delete <page>`, and a second press within
+three seconds removes that page's file. Switching page, `Esc` or simply
+waiting takes the request back. The `×` sits on the active tab only, so
+clicking an inactive one switches to it first and offers its `×` on the next
+frame. From a tool call it is `mmap_remove {pages: ["slug", …]}`, applied
+after that call's map edits. Either way the file is gone for good — the maps
+are plain JSON, so committing them is the only undo there is.
+
+State lives in the tool-owned `.mellos/` directory at the project root:
+
+| Path | What it is |
+| --- | --- |
+| `.mellos/map.json` | the default page — optional; a project whose work lives on named pages has none |
+| `.mellos/pages/<slug>.json` | one file per named page |
+| `.mellos/config.json` | the project's mapping policy (see [Setup](#setup-choose-when-maps-open)) |
+| `.mellos/focus` | one-shot "show this page" request from a launcher to a running pane; the pane consumes it and deletes it within a poll tick |
+| `.mellos/quit` | one-shot "close yourself" request from the `mmap` toggle, consumed and deleted the same way |
+| `.mellos/viewers/<pid>.json` | one report per live pane — the page it is showing, whether auto-follow is on — refreshed every second while it runs (see [Who is watching](#who-is-watching)) |
+| `<any of the above>.<pid>.<random>.tmp` | a save in flight; it is renamed over its target or removed. A leftover means a write failed (and was reported) and even its cleanup could not run |
+
+The map files are plain JSON, safe to commit if you want the maps' history in
+git. The other three are runtime chatter between a pane and whoever is talking
+to it — gitignore `focus`, `quit` and `viewers/` if you commit the store.
+
+**Concurrency, stated plainly.** Every save is atomic — written to a private
+sibling temp file and renamed over the target — so a reader polling the store
+sees the previous complete map or the new one, never a torn write. There is
+no lost-update protection: two writers saving the *same* page race, and the
+last rename wins, silently discarding what the other computed from an older
+read. Pages are the isolation unit — two sessions that must not clobber each
+other belong on two pages, which is also the answer to running several Claude
+sessions in one project.
 
 ### Diagram kinds
 
@@ -252,8 +441,11 @@ A node can link a child page with `submap: <page-slug>` — the pane badges it
 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 —
+Sub-maps are interior detail, not siblings: a page some *other* page dives
+into never occupies a tab. Two refinements keep the tab strip from erasing
+itself — a page whose own node names itself hides nobody, and a link cycle
+keeps its tabs unless a page outside the cycle dives in, because a cycle has
+no outside to climb back to. 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.
 
@@ -261,64 +453,169 @@ When a hidden sub-map changes in the background, the footer says so.
 
 | 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`) |
+| `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_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 |
+
+A batch applies bands → groups → lanes → node updates, and within one node
+update `layer` moves the node before its other fields, so a node can move and
+join a group on its new band in one item.
+
+What the boundary refuses, so the ledger never records something it did not
+mean:
+
+- **an unknown key**, naming it — a misspelled `evidance` is an error, not a
+  silently dropped field, at every nesting depth;
+- **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;
+- **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;
+- **a node whose `submap` names the page the call itself targets** — a link
+  with no bottom, not a parent link;
+- **a page deletion aimed at the page the same call targets, or at a slug the
+  project does not have** — one call must not edit a map it is deleting, and
+  a name matching no page is a typo far more often than a race; the refusal
+  lists the pages that do exist.
+
+A write that does not land answers `save failed, nothing changed (retry)`:
+the previous file is intact and calling again is the whole recovery.
+
+### Who is watching
+
+A map nobody has on screen is a file, not a map — and nothing in the system
+used to be able to tell the difference. An assistant would declare a design,
+light nodes up as it built them, and report all of it into a store you had
+never opened a pane for.
+
+Every pane now publishes a small report while it runs — `.mellos/viewers/`,
+one file per pane, refreshed once a second — and every write and every view
+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: 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 |
+
+The same reports answer "is a pane already open?" for `mmap` and for the
+launcher — a question that used to cost a Windows-only process scan and could
+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.
 
 ### Setup: choose when maps open
 
-Each project chooses how eager mapping is, once, via `/mmap setup` (or the
-first time the assistant declares a map — the reply nudges it to ask you):
+How eager mapping should be is a habit, not a property of a repository — so it
+is chosen **once, for you**, in the first session after you install:
 
 - `always` — map every structured task: workflows, designs, architecture,
-  technical dependencies.
-- `complex` — map only medium or complex tasks (the default until configured).
-- `on-request` — map only when you explicitly ask.
-
-The choice is stored in `.claude/mellos-mapping.config.json` and guides the
-assistant; it never blocks the tools, and asking for a map explicitly always
-works under any policy.
+  technical dependencies. The assistant opens the pane on its own initiative;
+  your recorded answer is its standing consent, so it stops asking.
+- `complex` — the same, but only for medium or complex tasks: several modules,
+  a new subsystem, roughly an hour of work or more.
+- `on-request` — map only when you explicitly ask. In a project with no map,
+  the plugin then says nothing at all — zero noise is the point.
+
+The answer lands in `<your home>/.mellos/config.json` and reaches every session
+through the plugin's `SessionStart` hook, which reads it and hands the
+assistant the matching instruction before you have typed anything. Nothing has
+to be set up per project, ever again.
+
+One project can still differ: `mmap_setup {policy, scope: "project"}` records
+a policy in that project's `.mellos/config.json`, and a project policy
+overrides the user one. `/mmap setup` re-runs the question for either scope
+whenever you want to change your mind. The policy guides the assistant; it
+never blocks the tools, and asking for a map explicitly always works under any
+policy.
+
+Hosts without hooks (Codex CLI, a bare MCP client) get the question another
+way: while no policy exists in either scope, every `mmap_declare` reply carries
+a note telling the assistant to ask you. That note goes quiet for good — in
+every project — the moment you have answered anywhere.
 
 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).
+rank (an integer in 0..99, 0 = bottom, unique per map); 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);
+a group clusters nodes within one band; and node ids and group ids share
+**one namespace** — an id names a node or a group, never both, because both
+render as boxes and one id must mean one box.
 
 ## Development
 
 ```
 npm install
-npm run verify   # typecheck + tests + bundle
+npm run verify
 ```
 
+`verify` is five steps, in this order: `typecheck` (the repo's own sources),
+`typecheck:packages` (the dsh plugin packages' framework-free modules, with
+`mellos-mapping/*` pointed at these sources), `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.
+
 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 format | `src/store/format.ts` | the state-file format: replay-validated parse, serialize — I/O-free |
-| 1 store | `src/store/store.ts` | atomic state-file persistence on Node |
-| 1 semantics | `src/semantics/` | medium-neutral view semantics: zoom ladder, group aggregation, sequence flip |
-| 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 |
+| Layer | Code | Spec | Owns |
+| --- | --- | --- | --- |
+| 0 domain | `src/domain/` | `ops.test.ts` | the map value, structural invariants, pure ops |
+| 1 format | `src/store/format.ts` | `store.test.ts` | the state-file format: replay-validated parse, serialize — I/O-free |
+| 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 |
+| 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 |
+| — packaging | `package.json`, `packages/` | `tests/lockfile.test.ts`, `tests/packages.test.ts`, `browser-safe.test.ts` | what ships, and to whom |
 
 `dist/` is committed deliberately: plugin installation clones this repo and
-runs nothing, so entry points ship bundled.
+runs nothing, so entry points ship bundled. CI diffs the committed `dist/`
+against a fresh build, so a source change that forgets the rebuild fails.
+
+### The dsh packages
+
+`packages/dsh` and `packages/dsh-client` are the DeepSeek Harness surface: a
+host plugin that reads and watches a workspace's `.mellos/` store, and the
+browser map panel that draws it with these same semantics. They are
+*developed* inside a dsh workspace checkout (its toolchain builds them) and
+*published* from here — sources, specs and `lib/` committed, refreshed by
+`node scripts/sync-dsh-plugin.mjs <path-to-deepseek-harness>`, which rewrites
+the dsh-internal package names to the published ones. This repo cannot build
+them, so it proves what it can: `typecheck:packages` and the framework-free
+specs run in CI, and `tests/packages.test.ts` guards the src↔lib structure,
+the shared version line, and the MCP row's spawn form. Specs that need the
+`@deepseek-ai` framework or a DOM are named, with their reason, in
+`vitest.config.ts`. See [`packages/dsh/README.md`](packages/dsh/README.md).
 
 ### Library
 
 The lower layers are also a library (`npm run build` emits `lib/` with type
 declarations; npm packs it). Subpath exports mirror the source:
-`mellos-mapping/domain/types`, `/domain/ops`, `/format`, `/semantics` are
-**browser-safe** — no Node builtins in their import closure, gated by a test —
-so a graphical client (a web panel, an editor view) can parse state files and
-reuse the exact aggregation and zoom semantics the terminal pane draws with.
-`/store` (Node filesystem persistence) and `/render` (the terminal renderer)
-complete the surface for Node hosts.
+
+| Subpath | Contents | Browser-safe |
+| --- | --- | --- |
+| `mellos-mapping/domain/types` | the map value, ids, ranks, statuses, errors | yes |
+| `mellos-mapping/domain/ops` | pure operations over a map | yes |
+| `mellos-mapping/format` | state-file parse / serialize, page ids | yes |
+| `mellos-mapping/semantics` | zoom ladder, group aggregation, focus and page-set rules, the shared glyph vocabulary | yes |
+| `mellos-mapping/render` | the terminal renderer | gated the same way (it is pure), but its output is character cells — for terminal hosts |
+| `mellos-mapping/store` | filesystem persistence, atomic saves, focus file, policy | Node only |
+| `mellos-mapping/server` | the bundled MCP server entry — a spawn target, not a module to import | Node only |
+
+**Browser-safe** means no Node builtins anywhere in the import closure, gated
+by a test, so a graphical client (a web panel, an editor view) can parse state
+files and reuse the exact aggregation, zoom and glyph semantics the terminal
+pane draws with. `packages/dsh-client` is that client.
 
 ## License