pmx-canvas 0.7.2 → 0.8.0

package/docs/mcp.md

@@ -42,6 +42,196 @@ Add to your agent's MCP config:
 
 The canvas auto-starts on first tool call.
 
+## Private MCP App preview
+
+`pmx-canvas --mcp-app` runs a **separate, experimental stdio profile**; the
+24-tool `--mcp` profile above is unchanged. Build from this checkout first:
+
+```bash
+bun run build
+PMX_CANVAS_WORKSPACE_ROOT=/absolute/project bun run src/cli/index.ts --mcp-app
+```
+
+Configure a compatible MCP Apps host to launch that command. Pin the workspace
+root explicitly; `PMX_CANVAS_URL` can attach it to an existing same-workspace
+daemon. This profile shares the daemon's **one active board** across all app
+instances and conversations. Choose or create a board in the app toolbar.
+
+Attached daemons must advertise `pmx-embedded-workbench-v4` in `/health` on every
+access. Matching package versions alone do not prove support for board/revision
+guards and embedded execution restrictions. An incompatible daemon is refused
+before any operation; restart it with this preview build and retry.
+
+The standard `ui://pmx/canvas` resource is self-contained HTML with MIME type
+`text/html;profile=mcp-app`. Only the launcher descriptor has ChatGPT-specific
+`openai/ui` metadata, advertising both `global` (sidebar/fullscreen) and `thread`
+(conversation panel) entrypoints. Actual availability depends on the host.
+
+The embedded view sends selected, pinned and AX-focused nodes to the host,
+including summaries of structured cards. Its context badge sits at the bottom
+left to avoid the host composer. Export downloads use the host's `downloadFile`
+capability; hosts without it show a local-retrieval message. Local-only trace
+capture and shared undo/redo are unavailable in the embedded view. Save a
+snapshot before restoring another one. Local surfaces can be expanded or
+exported, but cannot be opened as public sites without a public URL.
+
+| Tool | Input | Effect |
+|------|-------|--------|
+| `pmx_open_canvas` | `{}` | Open the real PMX workbench; standard UI resource plus ChatGPT entrypoints |
+| `pmx_read_canvas` | `{}` | Read board list, identity, projection revision, node IDs/titles/types/content revisions, counts and pin IDs |
+| `pmx_read_node` | `boardId`, `id` | Read one standalone note's full editable content, revision, position, size and incident edges in model-visible results |
+| `pmx_add_note` | `boardId`, `title`, `content`, `x`, `y` | Add Markdown through `node.add`; rejects a stale board ID |
+| `pmx_connect_nodes` | `boardId`, `from`, `to`, `type`, optional `label` | Add a `flow`, `depends-on`, `relation` or `references` edge through `edge.add` |
+| `pmx_create_board` | `name` | Create an empty board without opening it |
+| `pmx_open_board` | `id` (or null for Home), `expectedBoardId` | Switch the shared active board, refusing if it changed since the last read |
+| `pmx_update_note` | `boardId`, `id`, `expectedContentRevision`, `title`, `content` | Edit standalone Markdown; reject stale revisions, file-linked notes and oversized originals |
+| `pmx_move_node` | `boardId`, `id`, `x`, `y` | Move through `node.update`; group children follow |
+| `pmx_pin_nodes` | `boardId`, `nodeIds`, `mode` (`add` or `remove`) | Curate pins without replacing unrelated pins |
+
+Read tools declare read-only, non-destructive, closed-world annotations; the
+three additive tools declare non-read-only, non-destructive, closed-world
+annotations. Editing, moving, pin changes and board switching conservatively
+declare destructive writes. These assistant tools are closed-world. Writes retain the
+operation registry's scope fences, locks and attribution. **App clicks are
+agent-attributed**: MCP does not prove a human clicked, so the app cannot bypass
+these safeguards or acquire workbench authority.
+
+An eleventh tool, **`pmx_workbench_request`**, is app-only (`ui.visibility: ["app"]`),
+not an assistant tool. It accepts a relative PMX path, method, optional JSON body,
+and captured `expectedBoardId`. An explicit allowlist routes workbench operations
+through the same canonical registry; raw reads hydrate local assets. Replies stay
+in `_meta.response`. It is not an arbitrary HTTP proxy, shell executor, external
+MCP tool dispatcher, or human-authority bypass. This app-only tool declares
+open-world behavior because webpage/image actions may fetch external URLs.
+
+Embedded writes cannot supply external MCP launch metadata. App startup, board
+switches and snapshot restore cannot launch saved external backends; open them
+explicitly in local PMX. Undo/redo, flow materialization and approval resolve/reopen
+(including node interactions) stay local. Embedded source attribution is fixed
+to `mcp`. Child updates require permission for auto-sizing parent frames too;
+the fence and human-lock checks share that target calculation. Manual frames
+do not inherit child-update restrictions because their bounds remain fixed.
+Child geometry changes re-fit only affected automatic ancestors, not unrelated
+frames. PATCH aliases and partial coordinates resolve before destination checks;
+bulk guards and execution filter invalid patches identically before deciding
+which child positions override group translation.
+Rendered Markdown is sanitized before entering the workbench document; active
+HTML remains confined to sandboxed node frames.
+
+The app bundles the **existing PMX workbench**, not a second editor: Home, board
+navigation, tool rail, spatial nodes, edges, dragging, grouping, pins, themes,
+and the full Markdown editor use their normal components. A transport adapter
+replaces HTTP with host `tools/call`; the existing workbench poll cursor supplies
+live updates every two seconds. Local assets travel over MCP, not localhost URLs
+in the user's browser. Standalone Markdown edits carry captured board/content
+revisions; a refused save keeps the current editor draft. Copy that draft before
+closing the editor or switching boards; unsaved drafts do not survive remounts.
+
+**Host constraints still apply.** Native PMX controls work without child frames.
+HTML, Mermaid, JSON/graph and nested app renderers need the host to permit local
+`srcdoc` frames. The portable MCP Apps default with empty `frameDomains` is
+`frame-src 'none'`; there is no portable local-frame permission, so full rich
+rendering in ChatGPT is an outstanding native-host check. The local browser test
+explicitly enables local frames for that case. External assets remain subject
+to host CSP. File uploads, file-linked editing, shell/webview automation, external
+MCP tool calls, approval resolution, and trusted-human operations such as board
+deletion require the local workbench. Unsupported writes are refused, never
+silently granted human authority.
+
+Selecting nodes shares up to 20 selections plus 20 pins, with 700 characters
+per node, through `ui/update-model-context` when supported. This does **not**
+start inference. Use **ChatGPT's own composer** to ask about the canvas; the
+embedded workbench has no second composer and sends no `ui/message` requests.
+The normal local PMX composer remains unchanged. Multiple conversations may
+connect, but share one active board and the `mcp` writer label; distinct
+ChatGPT conversation identities are not yet represented in PMX presence.
+Board switches clear selection.
+Context synchronization runs behind the scenes, with no hosted footer. Failed
+updates retry automatically, including unchanged context, and only a host
+acknowledgement marks a delivery successful. Launcher results do not hydrate
+the workbench, so a delayed result cannot roll back the polling stream.
+
+Bulk preview and image hydration stay in `_meta.canvas`, not model-visible
+`structuredContent`; the canvas revision is a projection digest, not a content
+cursor. Before editing or appending a note, the assistant must use `pmx_read_node`
+for its complete source and content revision. Never replace content from a
+700-character selection excerpt. File-linked, oversized and non-Markdown nodes
+are not editable through the assistant's focused note tools.
+
+This is not a published or hosted ChatGPT plugin. Private ChatGPT testing needs
+an account-supported local MCP connection or Secure MCP Tunnel; no HTTP MCP
+endpoint is added here. Public deployment, authentication, tenant isolation,
+directory submission and real ChatGPT validation remain separate work. Do not
+expose the local workbench HTTP API as a public service.
+
+### Test privately in ChatGPT
+
+This is the MCP connection test, not a directory publication or packaged marketplace
+plugin. No plugin manifest or invented plugin ID is needed for this step. Follow
+OpenAI's [connection guide](https://developers.openai.com/plugins/deploy/connect-chatgpt)
+and [Secure MCP Tunnel guide](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels):
+
+1. Enable **Settings → Security and login → Developer mode** in ChatGPT (subject
+   to your account/workspace policy).
+2. Create a tunnel in [Platform tunnel settings](https://platform.openai.com/settings/organization/tunnels)
+   and associate it with your target **ChatGPT workspace**. Tunnel creation needs
+   Tunnels Read + Manage; running/selecting it needs Read + Use.
+3. Install `tunnel-client` from the download link in those settings or its
+   [latest release](https://github.com/openai/tunnel-client/releases/latest).
+   Supply its runtime key privately as `CONTROL_PLANE_API_KEY` in your shell.
+   Do not paste the key into chat, commit it or put it in a command argument.
+4. Run the following from the root of **this modified checkout**, with Bun installed:
+
+   ```bash
+   bun install --frozen-lockfile
+   bun run build
+   export PMX_CANVAS_WORKSPACE_ROOT="$HOME/pmx-chatgpt-test"
+   mkdir -p "$PMX_CANVAS_WORKSPACE_ROOT"
+   export PMX_CANVAS_ALLOW_WORKSPACE_SPLIT=1
+   export PMX_CANVAS_DISABLE_BROWSER_OPEN=1
+   unset PMX_CANVAS_URL PMX_CANVAS_DB_PATH PMX_CANVAS_STATE_FILE
+   tunnel-client init \
+     --sample sample_mcp_stdio_local \
+     --profile pmx-canvas \
+     --tunnel-id "<your actual tunnel ID>" \
+     --mcp-command "bun run '$PWD/src/cli/index.ts' --mcp-app"
+   tunnel-client doctor --profile pmx-canvas --explain
+   tunnel-client run --profile pmx-canvas
+   ```
+
+   Keep the process running in this shell with the workspace variables set. Run
+   only one client for this stdio tunnel. This uses a disposable test workspace;
+   its data persists under `~/pmx-chatgpt-test/.pmx-canvas/`. To test an existing
+   board instead, explicitly set that project's workspace root.
+
+   For an **unpublished preview tarball**, install it into a clean directory with
+   `bun add /absolute/path/pmx-canvas-chatgpt-preview.tgz`; skip the checkout build
+   and use `bun run '$PWD/node_modules/pmx-canvas/src/cli/index.ts' --mcp-app` as
+   the MCP command above. The tarball includes the built app HTML. Do not use
+   `bunx pmx-canvas` for this preview: that fetches the published version.
+5. Open [ChatGPT Plugins](https://chatgpt.com/plugins), select **+**, name it
+   **PMX Canvas**, choose **Connection → Tunnel**, select your tunnel and create
+   the connection. Confirm discovery of **ten assistant tools**, including
+   `pmx_open_canvas`, plus the app-only `pmx_workbench_request` transport (eleven
+   descriptors in `tools/list`), then start a new conversation with it enabled.
+
+Test both the conversation entrypoint and navigation sidebar launcher. Create a
+board, add/edit/move a note, pin it, select it and send a question using
+**ChatGPT's composer**. Selection alone must not start an answer. Ask ChatGPT to add a second
+note using `pmx_add_note`; it should appear within a few seconds without replacing
+the first. Reopen the app and verify persistence. With a second app/workbench
+instance, verify that board switches clear selection and stale saves refuse
+instead of overwriting another edit. Test HTML, Mermaid, and JSON/graph cards
+separately and record any CSP frame denial; native controls passing does not
+prove rich-frame support.
+
+If a launcher is missing, record the ChatGPT account/workspace and discovered
+`pmx_open_canvas` metadata; host entrypoint support is not proven by local tests.
+After changing the server, restart the tunnel client, use **Refresh** on the
+ChatGPT connection and start a new conversation. If the tunnel is missing, check
+its workspace association and permissions first. Do not substitute the workbench
+HTTP URL for an MCP endpoint.
+
 ## Composite tools (recommended)
 
 Action-discriminated tools that consolidate the single-purpose tools. Each maps
@@ -62,7 +252,7 @@ its `action` to the same operation the legacy tool used, so results are identica
 | `canvas_ax_state` | `get` · `set-focus` · `set-policy` · `report-capability` · `presence` · `set-presence` | `canvas_get_ax`, `canvas_set_ax_focus`, `canvas_set_ax_policy`, `canvas_report_host_capability` |
 | `canvas_ax_work` | `add` · `update` · `annotate` | `canvas_add_work_item`, `canvas_update_work_item`, `canvas_add_review_annotation` |
 | `canvas_ax_gate` | `request` · `resolve` · `await` × kind `approval` \| `elicitation` \| `mode` | `canvas_request_approval`, `canvas_resolve_approval`, `canvas_await_approval`, `canvas_request_elicitation`, `canvas_respond_elicitation`, `canvas_await_elicitation`, `canvas_request_mode`, `canvas_resolve_mode`, `canvas_await_mode` (9 → 1) |
-| `canvas_ax_timeline` | `read` · `record-event` · `add-evidence` · `send-steering` · `reads` | `canvas_get_ax_timeline`, `canvas_record_ax_event`, `canvas_add_evidence`, `canvas_send_steering` (`reads` is new — the context read log) |
+| `canvas_ax_timeline` | `read` · `record-event` · `add-evidence` · `send-steering` · `reads` · `read-status` | `canvas_get_ax_timeline`, `canvas_record_ax_event`, `canvas_add_evidence`, `canvas_send_steering` (`reads` is the context read log; `read-status` is per node: last read, by whom, at which content revision) |
 | `canvas_ax_delivery` | `claim` (long-polls with `timeoutMs`) · `mark` | `canvas_claim_ax_delivery`, `canvas_mark_ax_delivery` |
 | `canvas_intent` | `signal` · `update` · `clear` | _(new — Ghost Cursor of Intent; no legacy standalone tool)_ |
 | `canvas_board` | `list` · `get` · `create` · `create-from` · `open` · `update` | Boards, explicit shared-workbench switching, README designation, and transactional inactive copies |
@@ -133,7 +323,7 @@ Announce the spatial move you are **about** to make so the canvas paints a faint
 pre-commit placeholder (a "ghost"). The human sees the next move forming — and can
 veto it — before the mutation lands.
 
-- `signal` — register an intent: `kind` (`create` \| `move` \| `connect` \| `remove` \| `edit`) plus the anchor it renders against (`position` for create/move, `nodeId` for move/edit/remove, `edge` for connect). Optional `label`, `reason`, `confidence` (0..1 → ghost opacity), `seq` (staged-batch ordering), `ttlMs` (default ~8s), and a stable `id` to update/clear later.
+- `signal` — register an intent: `kind` (`create` \| `move` \| `connect` \| `remove` \| `edit`) plus the anchor it renders against (`position` for move, optional for create; `nodeId` for move/edit/remove; `edge` for connect). A create without `position` forms where the canvas will auto-place the node, and the linked create lands there. Optional `label`, `reason`, `confidence` (0..1 → ghost opacity), `seq` (staged-batch ordering), `ttlMs` (default ~8s), and a stable `id` to update/clear later.
 - `update` — patch a live intent by `id` (position/label/reason/confidence/ttlMs).
 - `clear` — abandon/dissolve it explicitly. Normal linked mutations settle automatically.
 
@@ -172,6 +362,11 @@ as a writer operation or refreshing agent presence. Viewport translation uses
 screen-space canvas-area coordinates (`screen = world * scale + viewport`). Fit
 dimensions and padding likewise refer to the canvas area after excluding the
 tool rail, top bar, and surrounding page chrome—not the full browser window.
+The canvas area starts right of the 52 px tool rail and below the 44 px top bar
+in the default layout, so world `(wx, wy)` lands at browser window point
+`(52 + wx * scale + x, 44 + wy * scale + y)`. To set the camera directly, use
+HTTP `POST /api/canvas/viewport` with `{x, y, scale}` or with `{center: {x, y},
+scale?}` to centre a world point in the canvas area (see `docs/http-api.md`).
 Use `canvas_ax_state { action: "set-presence", cursor, focusNodeId }` when the
 agent intends to publish its own cursor or attention target.
 
@@ -185,7 +380,7 @@ legacy tools the composites replaced.
 | Tool | Description |
 |------|-------------|
 | `canvas_batch` | Run a batch of canvas operations with `$ref` support |
-| `canvas_pin_nodes` | Pin nodes to include in agent context |
+| `canvas_pin_nodes` | Pin nodes to include in agent context (`nodeIds`, `mode` set/add/remove, optional `reason` shown to the human) |
 | `canvas_invoke_command` | Invoke a registry command (`pmx.plan`, `pmx.execute`, `pmx.promote-context`, `pmx.summarize`, `pmx.review`); records a `command` agent-event, unknown names rejected |
 | `canvas_ax_interaction` | Submit one capability-gated AX interaction envelope (`{ type, sourceNodeId, payload }`) that maps onto an AX operation; the server re-validates and clamps sandboxed surfaces to their own node |
 | `canvas_ingest_activity` | Ingest a harness-forwarded agent activity (tool/session event); the board auto-reacts with kind-driven, overridable defaults (failure → work item + review + evidence; `tool-result`+success → evidence). Makes AX bidirectional |

package/docs/node-types.md

@@ -228,15 +228,39 @@ Specs preserve top-level `state` and element-level `repeat`, `watch`, and
 `$state` only reads a value. Nested repeats can use `statePath: { "$item": "tasks" }`
 to iterate the current item's tasks. Watchers run after changes, not on mount.
 
-**Seed form values through bindings, not literal `value` props.** In shadcn
-0.21, `Input`, `Textarea`, `Select`, `Radio`, `Slider`, `ToggleGroup`, and
-`Tabs` ignore an unbound `value`; `ButtonGroup` ignores unbound `selected`.
-This includes read-only `$state` expressions. PMX returns a `warnings` array
-from `POST /api/canvas/json-render`, `POST /api/canvas/schema/validate`, and
-`canvas_render` actions `add-json-render` and `validate`. Warnings name the
-element/property; they do not reject or rewrite the spec. PMX does not invent
-state paths because repeated controls and existing actions may need distinct
-or deliberately shared state.
+**Literal form values are bound for you.** In shadcn 0.21, `Input`,
+`Textarea`, `Select`, `Radio`, `Slider`, `ToggleGroup`, and `Tabs` ignore an
+unbound `value`, and `ButtonGroup` ignores an unbound `selected`, so the control
+would render empty. During validation PMX rewrites a literal value on these
+props into `{ "$bindState": "/form/<elementKey>" }` and seeds
+`state.form.<elementKey>` with it (adding `-2`, `-3`, … if that field already
+exists). This input:
+
+```json
+{ "type": "Input", "props": { "label": "Postcode", "value": "nw1 6xe" } }
+```
+
+is stored as (bare elements are wrapped under the key `root`):
+
+```json
+{
+  "root": "root",
+  "state": { "form": { "root": "nw1 6xe" } },
+  "elements": {
+    "root": {
+      "type": "Input",
+      "props": { "label": "Postcode", "name": "root", "value": { "$bindState": "/form/root" } }
+    }
+  }
+}
+```
+
+PMX does not rewrite `$state` or other expressions, controls inside a `repeat`
+(one path would be shared by every item), or specs whose `state.form` is not an
+object. For those it returns a `warnings` array naming the element/property from
+`POST /api/canvas/json-render`, `POST /api/canvas/schema/validate`, and
+`canvas_render` actions `add-json-render` and `validate`. Bind them yourself
+when the field needs a known path for actions, watchers, or `$state` reads:
 
 ```json
 {
@@ -259,7 +283,7 @@ Inside repeats, use `$bindItem` with seeded item data. `Checkbox`/`Switch`
 honor literal `checked`, `Toggle` honors literal `pressed`, and `Tabs` honors
 `defaultValue` for an uncontrolled initial tab. `Pagination` reads `page`
 directly; `DropdownMenu.value` is an output binding for selection, not a
-displayed selection. These do not require the same ignored-value warning.
+displayed selection. These are neither rewritten nor warned about.
 Use two-way bindings whenever edits or form checks must participate in state.
 
 Cards keep their body in `children` and accept

package/docs/plans/plan-009-tech-debt-backlog.md

@@ -82,7 +82,7 @@ The remaining items were re-analyzed with pros/cons and tiered; the maintainer a
 
 ## Added during rail-chrome-v2 (2026-08-23, phases 1–5)
 
-Recorded while the redesign's phases land so nothing rides in silently. Plan: `design/rail-chrome-v2/PLAN.md`.
+Recorded while the redesign's phases land so nothing rides in silently. The redesign's plan was retired into `docs/design.md` and `docs/ax-state-contract.md` (2026-10-04).
 
 | Item | What's open |
 |---|---|

package/docs/plans/plan-015-design-foundation-wave-0.md

@@ -0,0 +1,177 @@
+# Plan 015 — Design foundation (wave 0)
+
+**Status:** Wave 0 done (2026-10-05): steps 1–4 are on main.
+**Date:** 2026-10-05
+**Source:** [design.md](../design.md#build-plan) wave 0 ("ships alone, first"); vision moves 5, 9, 10.
+Drawings: [`TokenSystem`](../design/TokenSystem.dc.html), [`Tokens`](../design/Tokens.dc.html),
+[`Themes`](../design/Themes.dc.html), [`Chrome`](../design/Chrome.dc.html),
+[`Context`](../design/Context.dc.html), [`Main`](../design/Main.dc.html) / [`Light`](../design/Light.dc.html).
+
+## Why first
+
+Every later wave paints with the meaning colours, the scale and the font. Today none of them
+exist: pins and agent attention borrow `--c-warn`, the light theme hard-codes `#4BBCFF` for pins,
+Plex is named in `--font` but not bundled (controls fall back to Arial or the system font), and
+there is no type, spacing, radius or elevation scale and no check that keeps any of it honest.
+
+## Wave done when (from design.md)
+
+No control renders in a fallback font; the token test passes for all nine themes; the reference
+cases pass at 600, 1024 and 1920 px; the demo board is regenerated.
+
+## Steps
+
+Each step is its own commit and leaves the suite green.
+
+### 1. Meaning and scale tokens, with the token test (no component changes)
+
+- Add the meaning layer to every theme block in `global.css` and `surface-theme.css`:
+  `--c-pin`, `--c-agent`, `--c-rel-supports`, `--c-rel-contradicts`, `--c-rel-cites`,
+  `--c-rel-derived`, `--c-rel-informs`, `--c-rel-related`. `--c-warn` already exists; it takes the
+  drawn value (changes Light `#c89b2a` → `#94600A` and Sepia `#A97B1E` → `#8A5A00`, with their
+  fixed `--c-warn-*` copies; every other theme already matches).
+- Values come from `Themes.dc.html` `renderVals()`. Where the drawing is silent (cites, derived,
+  informs, related outside Harbor) they are tuned here — see the table below.
+- Add the scale to `:root` in both files: `--fs-meta|ui|body|title|heading` (11/12/13/15/20),
+  `--space-1|2|3|4|6|8` (4/8/12/16/24/32), `--r-control|node|overlay|pill` (6/10/14/999),
+  `--e-1`, `--e-2` (shadows as drawn on `Tokens.dc.html`).
+- Token test (`tests/unit/theme-meaning-tokens.test.ts`), all nine themes:
+  - every meaning token is present, in both files, with the same value;
+  - each has at least 3:1 contrast on that theme's `--c-panel`;
+  - meaning colours are apart: OKLab distance ≥ 0.06 (≈3× a just-noticeable difference)
+    between `pin`/`agent`/`warn`, between each of those and every relation ink, and between
+    relation inks.
+- Nothing consumes the new tokens yet, so nothing on screen changes except the warning amber in
+  Light and Sepia.
+
+**Verify:** `bun run test:unit` (token + surface sync tests), `bun run build`, `bun run lint`.
+
+### 2. Bundle IBM Plex; every control inherits the font
+
+- Ship Plex Sans (400/500/600) and Plex Mono (400/500) woff2 with the client bundle, `@font-face`
+  in `global.css`, no CDN. Confirm the npm `files` list carries them.
+  *Done:* `@fontsource` packages are dev dependencies; `scripts/copy-fonts.ts` copies the latin
+  and latin-ext subsets (192 KB) and the OFL licence to `dist/canvas/fonts/`, which ships. The
+  single-file MCP app inlines them as data URIs. HTML nodes, json-render and exports still use the
+  `--font-sans`/`--font-mono` aliases without the faces until the frame host (wave 4).
+- Rename `--font`/`--mono` to `--font-ui`/`--font-code` (no aliases); `button, input, select,
+  textarea { font: inherit }`; remove Arial fallbacks.
+- Check: a browser test that every visible control computes `--font-ui` and that the Plex faces
+  are loaded (`document.fonts`).
+  *Done:* in `reference-pane.pw.ts`. Before: 365 of 400 controls on the demo board rendered in
+  Arial and no Plex face loaded; after: 0 of 389, all five faces loaded.
+
+### 3. Pins and agent marks move to their meaning tokens
+
+Split into three slices after reading the code (2026-10-05):
+
+**3a. Node states and the context pin (done).** Built to `Context.dc.html` and `Chrome.dc.html`:
+- In context: 1.5 px `--c-pin` border, header tinted 12% pin, pin-blue kind icon, and the header
+  pin control always visible — outline pin in a circle when out of context, the filled `--c-pin`
+  badge (`--c-on-pin` glyph, new token) when in. The light theme's hard-coded `#4BBCFF` overrides
+  are gone.
+- The amber "attention" halo was not agent activity: it was semantic attention derived from pins
+  (primary = the pinned nodes, secondary = their unpinned neighbours, plus a glow around pinned
+  clusters). Decided with the maintainer: pin style only — the halos, neighbour halos and the
+  focus field (`FocusFieldLayer`) are removed. The change pulse stays, in the neutral accent.
+- The violet agent bar (2.5 px `--c-agent` across the header) marks live agent edits
+  (`agent-mutating`), replacing the accent-blue shimmer; wave 1 extends it to read, created and
+  edited. The design session corrected the Context board's "Today" row to match.
+- Selection is a ring with a gap (3 px background, 2 px accent) outside the border, so pin styling
+  survives it; base nodes take `--r-node` and `--e-1`.
+
+**3b. Node header overflow (done).** Per `Chrome.dc.html`: expand and the context pin always show;
+⋯ and × appear on hover or keyboard focus. ⋯ opens the existing node menu (the same one as
+right-click), which already holds Collapse, Rename and Delete; "Open in new tab" (open as site)
+moves into it from the header. The drawn "Ask agent" entry has no function yet and waits for one;
+"Set as README" stays in the markdown card footer for now.
+
+**3c. The rest of the old colours (done).**
+- Every remaining `--c-warn` use was sorted by meaning. Pin blue: the command-bar chips, the
+  context pin bar, the expanded overlay's pinned state and toggle, the pin HUD and the "Context
+  updated" toast. Agent violet: the "agent yielded" pill and a status node's active tool.
+  `--c-rel-informs`: `depends-on` edges. Neutral (accent or muted): generic toast and history
+  borders, cluster/neighbourhood toasts, group drop feedback, the budget bar at rest, "saving",
+  webpage loading, the "required" source tag. Real warnings stay amber: approval gates and
+  waiting phases, blocked status, reconnecting, budget warnings, image and app warnings, pending
+  asks.
+- Tints are `color-mix(in srgb, var(--c-…) N%, transparent)`; the fixed alpha copies,
+  `--c-warn-alt`, `--c-glow-accent` and `--c-thinking` are gone (`--c-agent` replaces it).
+- `tests/unit/raw-hex-guard.test.ts`: no hex colour in client code or outside `global.css`'s theme
+  blocks. Allowlisted as content, not theme: group frame colours, the annotation default, the
+  white behind webpage previews, and the embedded Mermaid viewer's fallback (goes in wave 4).
+
+**3d. Kind colours and the writer palette (done).** Per the design session's rule in `design.md`
+(2b74c7b4): kinds carry no colour. Type icons, group kind dots and minimap rectangles are
+`--c-muted`; the minimap marks only meaning — pinned nodes in `--c-pin`, nodes an agent is
+editing in `--c-agent`. `KIND_COLOR`, the `--kind-accent` rules and `--c-purple` are gone (agent
+chrome that borrowed purple now uses `--c-agent`). Writers are told apart by name and initial: the
+writer palette and the per-agent `agentIdentityHue` are gone; an agent's cursor, chip, minimap dot
+and activity rows take `--c-agent`, a subagent's `--c-subagent`. Trace categories go neutral except
+subagent rows.
+
+### 4. Theme renames and the wave's definition of done (done)
+
+- `dark` → `harbor` (label Harbor, still the default) and `light` → `daylight` (label Daylight) in
+  `src/shared/themes.ts`, the CSS selectors, the defaults (state, persistence, client), the command
+  palette toggle (now by scheme), the CLI help, the bundled Copilot extension (`?theme=daylight`),
+  docs, skills, CLAUDE.md and AGENTS.md. No aliases: a stored or passed `dark`/`light` falls back
+  to Harbor, so anyone who had chosen the light theme picks Daylight once.
+- Viewer scheme parameters stay `dark`/`light` (the json-render viewer and embedded MCP apps speak
+  schemes, not theme ids); the static export maps its scheme to Harbor or Daylight for surface
+  documents.
+- Daylight takes the drawn neutral surfaces from `Main.dc.html` (`#F6F7F9` / `#FFFFFF` /
+  `#F2F4F7` / `#DDE2E9`, text `#0B1726`, ok `#1E7F51`, danger `#B8344A`) instead of beige.
+- Definition of done: reference cases at 600, 1024 and 1920 px in the e2e gate; the token test
+  covers all nine themes; the demo board regenerated (deterministic: two runs, same file).
+
+## Step 1 colour table
+
+Drawn values are from `Themes.dc.html`; *tuned* values are chosen in this plan.
+
+| Theme | pin | agent | warn | supports | contradicts | cites | derived | informs | related |
+|---|---|---|---|---|---|---|---|---|---|
+| Harbor (`dark`) | `#4BBCFF` | `#B388FF` | `#f4c542` | `#5FCFC0` | `#E59B6B` | `#7C9CFF` | `#D5DEEA` | `#E58FB0` | `#8ea3bd` |
+| Daylight (`light`) | `#1A7ABF` | `#7C4DDB` | `#94600A` | `#1E8C80` | `#B8572A` | *`#4257C9`* | *`#4A5566`* | *`#B03F72`* | *`#5c6b80`* |
+| High contrast | `#00ffff` | `#e040fb` | `#ffff00` | `#00e5c0` | `#ff8a00` | *`#8c9eff`* | *`#ffffff`* | *`#ff80ab`* | *`#aaaaaa`* |
+| Midnight | Harbor | Harbor | `#F5C452` | Harbor | Harbor | Harbor | Harbor | Harbor | *`#8D96BC`* |
+| Sepia | `#1F6FA8` | `#7046A6` | `#8A5A00` | `#1E8C80` | `#A3461C` | *`#3D50B0`* | *`#4E4433`* | *`#9C3A66`* | *`#6B6A66`* |
+| Arctic | `#6EC1F5` | Harbor | `#E8C476` | Harbor | Harbor | Harbor | Harbor | Harbor | *`#939DB1`* |
+| Ember | Harbor | Harbor | `#F5B944` | Harbor | Harbor | Harbor | Harbor | Harbor | *`#96948D`* |
+| Forest | Harbor | Harbor | `#E0B84F` | `#4FC9D9` | Harbor | Harbor | Harbor | Harbor | *`#8BA695`* |
+| Volt | Harbor | Harbor | `#E4C465` | Harbor | Harbor | Harbor | Harbor | Harbor | *`#9CA49C`* |
+
+"Related" is the theme's own `--c-muted` except in Sepia, where muted brown sits too close to the
+warning amber.
+
+## Decided 2026-10-05
+
+- **Tight pairs stay as drawn.** The closest drawn pairs (OKLab distance) pass the 0.06 floor:
+  Forest supports/pin 0.075, Daylight contradicts/warning 0.075, Sepia contradicts/warning 0.070.
+  The alternatives were compared side by side and rejected: Forest teal `#5FCFC0` lands on the
+  done green (0.062), and a redder contradicts in the light themes lands on `--c-danger`. Sepia
+  contradicts is already close to its error red (0.038); red is not a meaning colour, so the
+  test allows it.
+- **Light-theme elevation.** Daylight and Sepia override `--e-1`/`--e-2` with ink-tinted shadows
+  (10/8% and 18%) instead of the drawn black ones; recorded as the one per-theme scale exception
+  in `design.md`.
+
+## Decided 2026-10-06
+
+- **Folders, not levels.** Folders are the one browsing hierarchy; portals and links stay a graph
+  the agent navigates (links/backlinks on `canvas://boards`) and Map/Graph draw (vision move 0,
+  `design.md`). Unblocks wave 2.
+- **The theme rename ships as a breaking change** (no aliases): the release changelog lists it
+  under Breaking, with `--theme=light`, `PMX_CANVAS_THEME=light`, a saved Light choice and
+  `?theme=light` all falling back to Harbor.
+
+## Open
+
+- **Near a pin (decided 2026-10-05).** Nodes near a pin (up to 5 within 600 px,
+  `findNeighborhoods`) are treated as related, but the agent gets them only as titles, in
+  `canvas://pinned-context` and `canvas://spatial-context`; the main brief `canvas://context` does
+  not include them. Decided with the maintainer: no near-a-pin mark on the board until the brief
+  carries neighbours (vision move 1's ranker). The mark and that brief change ship together, in
+  wave 1; the design session draws the state ahead of it. Not part of wave 0. **Built** in plan 016
+  slice 4a (brief + chip); the hover lines, drag preview and Updates entry follow in 4b.
+

package/docs/plans/plan-016-context-made-visible-wave-1.md

@@ -0,0 +1,148 @@
+# Plan 016 — Context made visible (wave 1)
+
+**Status:** Slices 1–3 and 4a done (2026-10-05); 4b (tethers, drag preview, Updates entry) next.
+**Date:** 2026-10-05
+**Source:** [design.md](../design.md#build-plan) wave 1; vision Part 1 bet (item 4), moves 0a, 2, 7.
+Drawings: [`AgentContext`](../design/AgentContext.dc.html), [`Context`](../design/Context.dc.html),
+[`NearPin`](../design/NearPin.dc.html), [`BoardPins`](../design/BoardPins.dc.html),
+[`Home`](../design/Home.dc.html) (Folders).
+
+## Done when (from design.md)
+
+From the board alone, a person can answer "did the agent read what I pinned, and is its copy
+current?" The evaluation in `docs/evals/` reads the same data.
+
+## What exists and what is missing
+
+| Need | Today | Gap |
+|---|---|---|
+| Who wrote a node | `createdBy` / `lastEditedBy` per node, per-board `contentRevision` (plan 014) | none |
+| What an agent read | `context_reads`: per read, which **pinned** ids were in the payload (plan 011) | every delivered node, and the content revision it had when delivered |
+| Who pinned a node | `context_pins (board_id, node_id)` | who, when, and an optional why |
+| Board pins | none | `board_pins`, brief tiers, `canvas_board pin/unpin` in all four layers |
+| Neighbours in the brief | titles only, in `canvas://pinned-context` / `spatial-context` | the brief carries them (title + summary, reason "near <pin>") |
+
+## Slices
+
+Each slice is its own commit and leaves the suite green. Design ships with its function: no mark
+appears before the data that backs it.
+
+### 1. Data: what was read, at which revision, and who pinned (no UI)
+
+Split in two: 1a (reads) is enough for read / not read / changed since read; 1b (pin attribution)
+adds "pinned by the agent".
+
+- **1a, done.** `context_reads` records every node whose serialized form was delivered (not just
+  pins) and its `contentRevision` at read time, in a `read_nodes` column. Same "delivered" rule as
+  plan 011 (a serialized node carrying the id; a bare id list or a title does not count). The reader
+  side reports every node-shaped id it delivered (`readNodeIds`, so an MCP server attached to a
+  daemon only posts the record); the server keeps the ids that are nodes on the read board and
+  stamps their revisions. `ax.reads.status` (`GET /api/canvas/ax/context-status`,
+  `canvas_ax_timeline { action: "read-status" }`, `PmxCanvas.getNodeReadStatus`) returns, per node,
+  the latest agent read: when, by whom, at which revision.
+- **1b, done.** Pins record who pinned them (`pinnedBy`, the same actor attribution as node
+  authorship: a person only with the workbench token), when, and an optional `reason`
+  (`canvas_pin_nodes` / `POST /api/canvas/context-pins` / `setContextPins(..., reason)`). Pins that
+  stay keep their attribution; undo restores it; it persists with the board and its snapshots
+  (`meta` on `context_pins` and `snapshot_pins`). Pins from before have an unknown pinner. The read
+  status returns `pins` alongside `nodes`.
+- `context_pins` gains `pinned_by` (actor attribution, same shape as `createdBy`), `pinned_at` and an
+  optional `reason`. Pins made before this have an unknown pinner, not a guessed human.
+- One server read model, `nodeContextStatus(boardId)`: per node, last read (when, by whom, revision
+  read), current revision, pinned (by whom, when, why). Served over HTTP and SDK and MCP alongside
+  the existing context-reads surface (four layers in step); the workbench reads it through SSE.
+- **Check:** unit tests for delivered-all-nodes, revision capture, pin attribution through every
+  write path (workbench → human, agent writes → agent id/source), and the status model.
+
+### 2. Node marks: read, not read yet, changed since read, pinned by the agent, created, edited
+
+Built to `AgentContext.dc.html`: eye + "read" (hover: who, when); eye-off + "not read" on a pin the
+agent has not loaded since it was pinned; amber warn + "changed since read" when the current revision
+is newer than the revision read; violet dot on the pin badge when an agent pinned it (hover: why);
+"by <agent>" byline on agent-created nodes until a person edits them; violet bar + "edited" for the
+session, with "see change" opening the diff and undo.
+- **Check:** client tests per state; e2e at 600/1024/1920 that a pinned-then-changed node shows
+  "changed since read" after an agent read, and clears after the next read.
+- **Done.** Decided with the maintainer (2026-10-05): the read / not read / changed since read marks
+  show on **pinned** nodes only (a full-layout read delivers every node, so marking all of them
+  would cover the board); unpinned reads go to the lens (slice 3). "by <agent>" and "edited" stay
+  until a person edits the node. One chip per node (`NodeContextMark`), glyph + word, explained
+  on hover; agent pins get the violet dot. The workbench refetches the read status on connect, on
+  pin changes and when a read lands (`context-status-changed`, sent to the browser only), and
+  ignores an answer for a board it has left. Not built: "see change" (diff and undo of an agent
+  edit) needs stored previous content, which revisions do not keep yet.
+- **Note.** The demo board is generated through the API as agent writes, so its nodes show
+  "by sdk" until edited.
+
+### 3. After a session: the agent-activity lens and receipt
+
+The lens from `AgentContext.dc.html`: counts (read, created, edited, pinned) and the receipt rows
+with their actions (Unpin, Undo). Data from presence activity, revisions and slice 1.
+- **Done.** The existing session receipt (`agent-session-ended`) gains `context`: nodes read since
+  the session attached (presence now records `startedAt`), pins the agent made with their reason,
+  nodes it created and edited (the pre-session snapshot diff, filtered by authorship), and pinned
+  nodes changed since their latest read. A session that only read or pinned now gets a receipt.
+  The receipt card shows an amber line for out-of-date pins, Read / Pinned / Created / Edited rows
+  (Unpin on agent pins) and the lens switch "Dim untouched nodes". The read mark's hover says how
+  many times a node was read. Reads are counted per board in the session window, not per reader:
+  on a board with two agents at once, each receipt includes the other's reads.
+  The receipt also reads the board open when the session ends; a session whose board the person
+  switched away from mid-session reports the newly open board (known limit, 0.8.0 review).
+- **Not built:** per-row Undo of an edit (needs stored previous content); the pre-session snapshot
+  restore still undoes the whole session. The drawn bottom-bar placement of the lens is folded into
+  the receipt card, which already sits where session results appear.
+
+### 4. Near a pin: neighbours in the brief, and the near mark
+
+- The brief (`canvas://context`) carries each pin's neighbours (up to 5 within 600 px, nearest
+  first) as title + short summary, reason "near <pin title>", never full content; they share the
+  budget after pinned cards.
+- The `NearPin.dc.html` mark: dotted "near" chip, tethers on hovering a pin, the drag preview and
+  the single Updates entry that replaces "Neighborhood changed". "read" from slice 2 then also
+  covers neighbours honestly (title + summary delivered).
+- **4a, done.** The brief carries `near` entries right after the pinned cards (each whole or
+  absent, title + summary capped at 280 characters, `near: { pinNodeId, pinTitle }`); a neighbour
+  that changed since the cursor arrives in full as `changed` instead; a first read delivers every
+  node in full, so it has no near entries. The client computes the same `findNeighborhoods` and
+  shows the dotted "near" / "near N" chip on unpinned nodes, with the pins and distances on hover.
+- **4b, next.** Tethers and the 600 px radius when hovering a pin, the drag preview, the single
+  Updates entry that replaces "Neighborhood changed", the context chip's "N cards · M near" count,
+  and "Pin to send content" in the chip's hover. The maintainer agreed the design (2026-10-06) on
+  the condition that performance stays good:
+  - **Budget.** No added work per drag frame beyond the neighbour calculation for the board
+    (measured 0.8 ms at 1,000 nodes / 40 pins; guarded at < 8 ms by
+    `tests/unit/near-pin-performance.test.ts`) and the dragged card against the pins (O(pins)).
+  - **No fan-out.** The near map keeps its identity while no card's set of pins changes, so the
+    chips re-render only when a neighbourhood does, not on every frame (done ahead of 4b, guarded
+    by a client test). Distances, which change every frame, are computed only for an open hover.
+  - **Lines and radius** are drawn only while a pin is hovered or selected, for that pin alone, in
+    one SVG layer; nothing renders for pins at rest.
+  - **Check.** A headed drag on a 300-node board with 20 pins records no long task (> 50 ms)
+    attributable to near-a-pin.
+
+### 5. Board pins
+
+Per vision move 0a and `BoardPins.dc.html`: `board_pins` table (board, who, when); `canvas_board`
+`pin`/`unpin` across PmxCanvas, HTTP, MCP and CLI; the tiered brief (active board's pins, then each
+pinned board's README + pinned cards, then discovery); the context chip counts "N cards · M boards";
+Home's pinned-boards section per `Home.dc.html`. Read status per board from slice 1.
+
+### 6. The curation evaluation
+
+`docs/evals/curation-effect.md`: one fixed task, run with the brief delivered on a curated and an
+uncurated board, scored on criteria written before the first run (vision Part 1, item 4). It reads
+the same `context_reads` data as slice 1 to confirm delivery before scoring effect. Running it
+needs the maintainer's real agent sessions; the decision rule is the vision's.
+
+## Out of wave 1
+
+- "Suggested by the agent" (dashed node, accept/reject): needs agent suggestions as a function
+  (vision move 3, wave 5). The drawing exists; it ships with that function.
+- Home Map and Graph (wave 2).
+
+## Defaults (change if the maintainer disagrees)
+
+- **Read by whom.** Any agent reader on that board counts; the mark shows the most recent reader
+  and time on hover. The workbench's own reads never count.
+- **Changed since read** compares against the most recent read of that node by any agent.
+- **Unknown pinner.** Existing pins show no agent dot; only pins attributed to an agent get it.