beehaven 0.8.35 → 0.8.37

package/dist/relay.js

@@ -10,6 +10,7 @@ import { join, dirname, resolve, sep } from 'path';
 import { execSync, execFileSync } from 'child_process';
 import WebSocket from 'ws';
 import { logger } from './logger.js';
+import { ReconnectBackoff } from './reconnect-backoff.js';
 import { TerminalBlockParser } from './terminal/block-parser.js';
 import { writeIntegration, cleanupIntegration } from './terminal/shell-integration.js';
 import { transformPath } from './daemon-path-transform.js';
@@ -73,11 +74,16 @@ export class Relay {
     // ── WebSocket ─────────────────────────────────────────────────────────
     ws = null;
     wsConnecting = false;
-    reconnectAttempts = 0;
+    /** ⚠ PPO-532: resets only after a connection stays open 60 s, not when one opens — see
+     *  reconnect-backoff.ts. `reconnectAttempts` (read by the daemon's status.json) reads it. */
+    backoff = new ReconnectBackoff();
+    get reconnectAttempts() {
+        return this.backoff.attempts;
+    }
     reconnectTimer = null;
     /** Watchdog timer + the moment we first noticed we were disconnected. If the
      *  relay stays down past the threshold, the watchdog forces a HARD reconnect
-     *  (terminate any zombie socket + reset backoff + redial). This is the
+     *  (terminate any zombie socket + redial now; PPO-532 keeps the backoff). This is the
      *  self-heal a HEADLESS / orphaned daemon needs — it has no Mac-app tray
      *  parent to restart it, so a wedged WS (e.g. a half-open socket after system
      *  sleep) would otherwise leave it "stuck reconnecting" forever. */
@@ -388,6 +394,8 @@ export class Relay {
             return;
         // Re-enable auto-reconnect in case a previous stop() set it.
         this.stopped = false;
+        // An explicit start (daemon boot, sign-in) is not a retry: no inherited backoff.
+        this.backoff.reset();
         // Validate endpoint against whitelist
         try {
             const endpointHost = new URL(this.config.endpoint.replace('wss://', 'https://').replace('ws://', 'http://')).hostname;
@@ -534,6 +542,8 @@ export class Relay {
             params.set('deviceId', String(this.deviceId).slice(0, 64));
         const url = `${this.wsBase()}/my/workspace/ws?${params.toString()}`;
         const ws = new WebSocket(url);
+        // This socket's healthy clock (PPO-532); null until it opens.
+        let openedAt = null;
         // Wait for open or first error/close before resolving
         await new Promise((resolve) => {
             const done = () => {
@@ -543,7 +553,10 @@ export class Relay {
                 this.ws = ws;
                 this.wsConnecting = false;
                 this.connected = true;
-                this.reconnectAttempts = 0;
+                // ⚠ PPO-532: opening is not recovering. A workspace that runs out of memory while
+                // hydrating accepts the socket and drops it seconds later; resetting here made every
+                // retry the first (~1 s), a reconnect loop. The backoff resets after 60 s open.
+                openedAt = this.backoff.opened();
                 console.log(`[relay] WebSocket connected to ${this.config.endpoint}`);
                 // Notify subscribers that the WebSocket is open so they
                 // can pull fresh state. Wrapped because the callback
@@ -764,12 +777,17 @@ export class Relay {
             this.heartbeatInterval = null;
             this.wsPingInterval = null;
             this.wsWakeDetector = null;
-            // Reject pending requests
-            for (const [, pending] of this.pendingRequests) {
+            // Reject pending requests.
+            // ⚠ CAN2-175 — SAY THE OUTCOME IS UNKNOWN, as the timeout does. A dropped socket loses the REPLY,
+            // not the request: a canvas batch carries on and lands on the workspace. A bare "WebSocket closed"
+            // read as "nothing happened", the caller resent at once, and could not tell which state was real.
+            for (const [requestId, pending] of this.pendingRequests) {
                 clearTimeout(pending.timer);
-                pending.reject(new Error('WebSocket closed'));
+                pending.reject(new Error(`WebSocket closed (code ${code ?? '?'}) before the reply (action=${pending.action ?? '?'}, requestId=${requestId}); outcome unknown: `
+                    + 'the request may still be running on the workspace or may already have landed. Read its state before resending.'));
             }
             this.pendingRequests.clear();
+            this.backoff.closed(openedAt);
             // Always schedule reconnect while we're still configured and not
             // stopped. Previous guard `if (wasConnected)` broke the chain: if
             // a reconnect attempt failed to open, the new ws's close handler
@@ -1084,12 +1102,12 @@ export class Relay {
                 return reject(new Error('WebSocket not connected'));
             }
             const requestId = Math.random().toString(36).slice(2) + Date.now().toString(36);
+            const action = msg.type === 'agent-invoke' ? msg.action : msg.type;
             const timer = setTimeout(() => {
                 this.pendingRequests.delete(requestId);
-                const action = msg.type === 'agent-invoke' ? msg.action : msg.type;
                 reject(new Error(`Request timeout after ${timeout}ms (action=${action}, requestId=${requestId}); outcome unknown`));
             }, timeout);
-            this.pendingRequests.set(requestId, { resolve, reject, timer });
+            this.pendingRequests.set(requestId, { resolve, reject, timer, action });
             // Send both rid (legacy) and requestId (workspace actions) for compatibility
             if (!this.wsSend({ ...msg, rid: requestId, requestId })) {
                 clearTimeout(timer);
@@ -1100,28 +1118,21 @@ export class Relay {
     }
     // ── Reconnection ──────────────────────────────────────────────────────
     /**
-     * Reconnect with exponential backoff + jitter.
+     * Reconnect with exponential backoff + FULL jitter (PPO-532, reconnect-backoff.ts).
      *
-     * Backoff: 1s → 2s → 4s → 8s → 16s → 32s → 60s (capped). Jitter adds
-     * 0-25% of the base delay so a fleet of clients reconnecting after a
-     * server outage doesn't synchronize into a thundering herd. The cap
-     * keeps idle daemons polling at most once a minute.
+     * Delay: uniform over [0, min(30s, 1s·2^attempt)). The ±25% jitter this replaced kept the
+     * daemon socket and its agent sockets — which drop together — reconnecting together. The
+     * attempt count resets only once a connection has stayed open 60 s, so a socket that opens
+     * and dies (an out-of-memory workspace) keeps backing off instead of retrying every second.
      *
-     * Single-flight: a reconnect already scheduled is a no-op. The timer
-     * is cleared on successful connect (reconnectAttempts → 0) and on
-     * stop().
+     * Single-flight: a reconnect already scheduled is a no-op. The timer is cleared by stop()
+     * and forceReconnect().
      */
     scheduleReconnect() {
         if (this.reconnectTimer)
             return;
-        const baseDelay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 60_000);
-        // Add 0-25% random jitter — `delay * (1 + 0..0.25)` keeps the
-        // floor at the exponential value so we never reconnect FASTER
-        // than the backoff intends, only slower.
-        const jitter = Math.random() * 0.25 * baseDelay;
-        const delay = Math.round(baseDelay + jitter);
-        this.reconnectAttempts++;
-        console.log(`[relay] Reconnecting in ${(delay / 1000).toFixed(1)}s (attempt ${this.reconnectAttempts})`);
+        const delay = this.backoff.next();
+        console.log(`[relay] Reconnecting in ${(delay / 1000).toFixed(1)}s (attempt ${this.backoff.attempts})`);
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
             if (this.useWebSocket) {
@@ -1151,6 +1162,10 @@ export class Relay {
                 this.disconnectedSince = Date.now();
                 return;
             }
+            // ⚠ PPO-532: a scheduled retry means the backoff chain is alive (≤30 s away). Forcing
+            // past it turned a workspace that keeps dropping new sockets back into rapid redials.
+            if (this.reconnectTimer)
+                return;
             if (Date.now() - this.disconnectedSince > maxDownMs) {
                 console.warn(`[relay] Watchdog: relay down ${Math.round((Date.now() - this.disconnectedSince) / 1000)}s — forcing hard reconnect`);
                 this.disconnectedSince = Date.now();
@@ -1159,7 +1174,8 @@ export class Relay {
         }, 30_000);
     }
     /** Hard reconnect: drop any (possibly zombie) socket, clear pending reconnect
-     *  state, reset the backoff so the next dial is immediate, then redial. */
+     *  state, then redial at once. The attempt count is kept (PPO-532): if this dial
+     *  fails too, the next retry continues the backoff instead of restarting at 1 s. */
     forceReconnect() {
         try {
             this.ws?.terminate();
@@ -1172,7 +1188,6 @@ export class Relay {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
-        this.reconnectAttempts = 0;
         if (this.useWebSocket)
             this.connectWs();
         else
@@ -1182,7 +1197,7 @@ export class Relay {
         const ok = await this.sendHeartbeatHttp();
         if (ok) {
             this.connected = true;
-            this.reconnectAttempts = 0;
+            this.backoff.reset(); // legacy HTTP has no socket to watch: a good heartbeat is recovery
             console.log(`[relay] Reconnected (tier: ${this.tier})`);
             if (this.heartbeatInterval)
                 clearInterval(this.heartbeatInterval);

package/dist/utf8-stream.js

@@ -0,0 +1,23 @@
+/**
+ * utf8-stream — decode a socket's bytes ONCE PER CHARACTER, not once per chunk (CA-63).
+ *
+ * ⚠⚠ WHY THIS EXISTS (staging, 2026-10-23). A 402-step `beehaven call canvas-act @build.json` (90,714
+ * bytes, the file holding the correct C2 B7) stored ONE text node's middle dot as "��" — the
+ * same node, the same character, on every resend — while dozens of identical dots elsewhere in the batch
+ * were stored intact. Every IPC reader did `buffer += chunk.toString()`. A local socket hands the reader
+ * the stream in pieces (8 KB on macOS, 64 KB on Linux), so any multi-byte character that straddles a
+ * piece boundary was decoded as two halves, each half an invalid sequence, each a U+FFFD. Which character
+ * lands on a boundary depends only on the bytes before it, so the same payload broke the same character
+ * every time. The CLI → daemon direction corrupted what was STORED; the daemon → CLI direction corrupted
+ * what a reader was SHOWN (a long scene read could carry U+FFFD the canvas does not have).
+ *
+ * A `StringDecoder` holds an incomplete trailing sequence until its remaining bytes arrive, so the text is
+ * exactly what one decode of the whole stream would give. One decoder per stream (it carries state), and
+ * never shared between two sockets.
+ */
+import { StringDecoder } from 'node:string_decoder';
+/** A stateful UTF-8 decoder for ONE byte stream. A string chunk (a socket with an encoding set) passes through. */
+export function utf8Stream() {
+    const decoder = new StringDecoder('utf8');
+    return (chunk) => (typeof chunk === 'string' ? chunk : decoder.write(chunk));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beehaven",
-  "version": "0.8.35",
+  "version": "0.8.37",
   "description": "Beehaven CLI — command your Clearly workspace, agents, and canvas from the terminal",
   "private": false,
   "type": "module",

package/scripts/sync-skills.mjs

@@ -46,6 +46,7 @@ const SOURCES = {
   'clearly-docs':      'apps/mcp-server/plugin/skills/clearly-docs/SKILL.md',
   'clearly-init':      'apps/mcp-server/plugin/skills/clearly-init/SKILL.md',
   'clearly-workflows': 'apps/mcp-server/plugin/skills/clearly-workflows/SKILL.md',
+  'clearly-artifacts': 'apps/mcp-server/plugin/skills/clearly-artifacts/SKILL.md',
 };
 
 let missing = 0;

package/skills/clearly-artifacts/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: clearly-artifacts
+description: >-
+  Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini CLI); in a chat with only the Clearly connector, say so: the connector cannot make a running page.
+  Put a self-contained interactive HTML page into a Clearly workspace, the way a
+  Claude artifact works: an explainer, an animation, a small tool, a calculator, a
+  chart that runs. Covers which of the three HTML homes runs scripts (a SITE does,
+  a canvas ARTIFACT card does but cannot be clicked, a NOTE never does), the exact
+  CLI calls, the sandbox limits, updating, filing in a project, how a person opens
+  it, and QA. Use when asked to publish, host or add an HTML page, demo or animation
+  to the workspace. Triggers: "make an artifact", "publish this HTML", "add this page /
+  animation / explainer to the workspace", "host this demo", "interactive page",
+  "put this HTML on the canvas", "why doesn't my page's script run".
+---
+
+# Clearly artifacts — a running HTML page in the workspace
+
+Sign in first (`clearly-agent`). `beehaven env` must name the environment you mean; staging and
+production hold different workspaces.
+
+## 1. Pick the home — only two of the three run code
+
+| Home | Make it with | Scripts and CSS animation | Clickable | Search, history | Opens at |
+|---|---|---|---|---|---|
+| **Site** | `compose-upload-init` → `file-teleport-inline` → `compose-upload-finalize` | run | yes | not in `document-search`; no version history; a re-upload overwrites | Recents or project card → `/compositions/detail?id=<id>` |
+| **Canvas artifact** | `canvas-act` `canvas.add-artifact` | run | **no**: the card never takes pointer events, so it pans like a picture | no; it is part of the canvas and is deleted with it | the canvas, `/c/<compositionId>` |
+| **Note** | `document-create {html}`; `page-write` (in-app chat only) | **never**: it opens in the document editor, which drops `<script>`, `<style>` and inline `<svg>` | n/a | yes, both | `/documents/<id>` |
+
+- An interactive page someone opens, clicks through or comes back to is a **site**. This is the
+  Claude-artifact equivalent and the default.
+- A page that only needs to be **seen** beside other cards (a looping animation, a live chart in a
+  review board) is a **canvas artifact**. Buttons inside it cannot be pressed.
+- Prose the team will read, search and edit is a **note**. Never put a script in a note: it
+  is stored, and then nothing ever runs it. Editing the note in the app rewrites its body.
+
+No home gives a public link that runs. Every share link (`/r/…`) is served with
+`script-src 'none'`, and a shared composition renders as a static picture. Say so when someone asks to
+publish an interactive page outside the workspace.
+
+## 2. Write it self-contained
+
+Both running homes inject the page with `srcdoc` into `<iframe sandbox="allow-scripts">`, with no
+`allow-same-origin`. The page gets an opaque origin (`window.origin === "null"`).
+
+- **One file.** `<!doctype html>`, `<meta name="viewport" content="width=device-width, initial-scale=1">`,
+  CSS in `<style>`, JS in `<script>`, art as inline SVG, images and fonts as `data:` URIs,
+  system font stacks. Make no network requests and load no CDN scripts.
+- **The sandbox blocks:** `localStorage`, `sessionStorage`, cookies and IndexedDB (accessing them
+  throws), `alert`/`confirm`/`prompt`, form submission, popups, `window.open` and top-level
+  navigation. Keep state in memory, and wrap any storage access in `try`.
+- **A site's other files are rarely reached.** The preview rewrites only `src="…"`/`href="…"`
+  in the entry HTML that name a build file exactly (up to 60 files). It does not rewrite `url()`
+  inside CSS, `import`, or `fetch` of a sibling file. Inline them.
+- **Size:** a canvas artifact is at most 512 KB. A site file is at most 6 MB inline. Over the CLI
+  WebSocket, keep a single `beehaven call` under about 900 KB, or use `beehaven compose push`,
+  which switches to a presigned upload.
+- **Motion:** honour `@media (prefers-reduced-motion: reduce)`. A canvas card lays the page out
+  at `designWidth` (default 1280) and grows to the document's full height. A `100vh` layout
+  makes it grow again on every fit, so size sections in px or by content.
+
+## 3. Make it (CLI)
+
+Build JSON payloads with a script and pass them as `@file`. Do not hand-escape HTML into a shell
+argument.
+
+**Site, from one file** (one `file-teleport-inline` per file; `entryPoint` and each path are
+relative to `build/`):
+
+```sh
+beehaven call compose-upload-init '{"name":"MCP tokens explained","sourceType":"static","entryPoint":"index.html","projectId":"<projectId>"}'
+# → { "id": "cmp_…", "created": true }
+node -e 'const fs=require("fs"),b=fs.readFileSync("page.html");fs.writeFileSync("up.json",JSON.stringify({key:"compositions/<id>/build/index.html",composition:true,name:"index.html",mimeType:"text/html",size:b.length,data:b.toString("base64")}))'
+beehaven call file-teleport-inline @up.json
+beehaven call compose-upload-finalize '{"compositionId":"<id>","totalBytes":<bytes>,"entryPoint":"index.html"}'
+beehaven call composition-fs '{"compositionId":"<id>","action":"list"}'   # one row per file, sizes match
+```
+
+Both parts of the upload are load-bearing. A `key` outside `compositions/<id>/build/`, or a
+missing `composition:true`, still answers ok, and the site then renders nothing.
+
+**Site, from a folder** that holds only the page and its assets:
+`cd <folder> && beehaven compose create --name "<title>" && beehaven compose push`. Every file in
+the folder is uploaded. A Vite, Next, Astro or SvelteKit `package.json` there runs its build first.
+To push to an existing site, run `beehaven compose push --composition <id>` from the folder; there
+is no `--dir` flag. `compose create` cannot file the site, so file it afterwards (§4). Ignore the
+URL that `push` prints, because it does not open the site.
+
+**Canvas artifact** (create or reuse the canvas with `composition-create {title, projectId}`):
+
+```sh
+# payload: {"compositionId":"<canvasId>","action":"canvas.add-artifact",
+#           "args":{"html":"<!doctype html>…","title":"…","name":"explainer","x":0,"y":0,"w":1000,"designWidth":1000}}
+beehaven call canvas-act @artifact.json
+```
+
+`w` is the card's width on the board; `designWidth` is the viewport the page lays out at. Use 390
+for a phone design. `canvas.place {kind:"site", id}` puts an existing site on a canvas as an
+artifact card. It copies the entry HTML at that moment: later re-uploads do not reach the card,
+and the site's other files do not load.
+
+**Connector only (MCP):** no tool makes a site or an artifact. `clearly_file_upload` cannot choose
+a site path, and `clearly_create` stores a document body as markdown. `clearly_canvas_place
+{target, kind:"site", id}` can place a site that already exists. Otherwise, tell the person the
+running page needs the CLI.
+
+## 4. Update, file, link
+
+- **Update a site:** upload to the same `key`, then `compose-upload-finalize` again. Only someone
+  who may manage the site (its creator) can overwrite it. A file you stop shipping stays in the
+  build. Agents are refused `composition-fs … "action":"delete"`, so ask the person to remove it,
+  or stop referencing it. There is no history, so keep the source in the repository or a note.
+- **Update a canvas artifact:** there is no edit verb. Add the new version at the old card's
+  `x`/`y`/`w`, then remove the old card with `canvas.delete {ids:[…]}`.
+- **File:** `projectId` on `compose-upload-init` (to file later, call it again with
+  `{"compositionId","projectId"}`). For a canvas, `composition-create {projectId}`. For a note,
+  `document-create {projectId}` or `document-update {id, projectId}`. Unfiled agent work is
+  private to its author.
+- **Link it to the ticket:** `beehaven call work-link '{"ticketId":"…","kind":"design","refKind":"composition","refId":"<id>"}'`.
+
+## 5. Hand it over
+
+Give the person the place to click, not just an id.
+
+- A site: "Recents (or the project) → the card", which opens `/compositions/detail?id=<id>`.
+  Do not hand over `/c/<siteId>`. That is what `beehaven open`, ticket links and workspace-ref
+  chips build for a site, and it opens an empty canvas instead of the page.
+- A canvas artifact: `/c/<canvasId>`. Double-clicking the card opens its stored file in a new tab,
+  which shows source text or an access error, never the running page.
+
+## 6. QA — open it, read the console, check mobile
+
+1. **Render it in the real frame model** before uploading. Use Playwright: an
+   `<iframe sandbox="allow-scripts" srcdoc>` at 1280 and 390 wide. Confirm there are no console
+   errors and no requests from the frame, that `scrollWidth === clientWidth`, that the animation
+   advances by itself, and that its controls respond.
+2. **Read the stored copy back:** check that `composition-fs list` shows the size you sent.
+3. **See the server render it.** For a canvas artifact, run
+   `canvas-act {"compositionId":"<canvasId>","action":"canvas.review","args":{"ids":["<artifactId>"]}}`.
+   It returns a filmstrip of four frames across about 5.4 s; inspect the PNG. For a site, place it on a scratch canvas
+   (`canvas.place {kind:"site", id}`), review that card the same way, and then archive the scratch
+   canvas (`composition-set-archived {id, archived:true}`).
+4. Report what you checked and what you could not check. Opening the signed-in page itself needs a
+   person's session.

package/skills/clearly-canvas/SKILL.md

@@ -32,7 +32,7 @@ For a new composition or substantial redesign, use the workflow below.
 
 Keep the requested scope. A landing concept with a logo needs its page layouts and a usable
 logo; add application boards or a full guideline system only when the brief calls for them.
-Read only relevant references. Save large tool responses once and print compact summaries.
+Read only relevant references. Save large tool responses once (`beehaven call … --out file.json`) and print compact summaries.
 
 ## The studio bar — what "done" means, every time
 
@@ -46,7 +46,8 @@ A composition is done when every requested artboard meets all five conditions:
    remains: text colliding or covered, contrast under WCAG (4.5:1 body, 3:1 display),
    type below the artboard's legible floor, missing media, text overflowing its box,
    placeholder copy. Fix it. For an intentional finding, use
-   `accept:[{check,ids:[node IDs],reason}]`. Accepted findings stay visible and return `look`.
+   `accept:[{check,ids:[node IDs],reason}]`; one rule may name every layer with the same
+   deliberate finding. Accepted findings stay visible and return `look`.
    Legacy `ignore` can suppress multiple checks and is not an unconditional pass.
 2. **Every `look` finding was looked at**: type-size and palette sprawl, near-miss
    alignment, copy against the trim, text over imagery. Act on it or say why not.
@@ -117,8 +118,9 @@ Read `clearly-agent` before your first workspace call. Pin the intended workspac
 sign in once. Do not switch a user's explicit workspace to `home`.
 
 Your surface: the shell. The `beehaven` examples in this skill are literal commands to
-run; they are not shapes to translate into an MCP canvas-action tool. MCP artifact tools
-can read and edit artifact records, while canvas-specific actions use the CLI.
+run; they are not shapes to translate into an MCP canvas-action tool. The Clearly connector
+has its own canvas tools for agents without a shell (batched per kind of step, see
+authoring.md); in a shell the CLI's mixed `canvas-act` batch takes fewer calls.
 
 ```sh
 beehaven env
@@ -156,7 +158,7 @@ builds on the last and can be reviewed alone. Build ONE commit per canvas-act ba
 `canvas.review` of the artboard and carries
 `"ticket":{"id":"<key>","status":"done","resolution":"<what changed>"}` — it lands only if that
 review is clean or look; `result.ticket` says whether it did, and the ticket logs the canvas
-revision and the layers the commit changed. Auto-layout, gradients, shadows, drawing and placeholders:
+revision, the layers the commit changed and a link to its frame. Auto-layout, gradients, shadows, drawing and placeholders:
 see "Technique" in [authoring.md](authoring.md).
 
 `composition-board-get {compositionId}` reads the plan back. `design-start` with a project, ticket or
@@ -279,7 +281,7 @@ a detail view catches collisions, wrapping, cropping and legibility.
 The bundled helper saves pixels directly to disk so base64 does not fill your context:
 
 ```sh
-node <skill-directory>/review.mjs <composition-id> <frame-id-or-unique-name> /tmp/canvas-review/01
+node <skill-directory>/review.mjs <composition-id> <frame-id-or-unique-name> canvas-review/01
 # Open the returned PNG using your image-viewing tool; read the JSON findings.
 ```
 
@@ -300,9 +302,15 @@ The helper prints the verdict and every finding. Work until the verdict is `clea
 use a real frame ID with `--perceive` for a preview-only check and run the text measurement
 and audit separately. A failed or missing render means visual verification is incomplete.
 
+A deliberate finding (say why in the handoff): write the findings you are keeping to a file and
+pass it to the same helper. They stay visible in the report and return `look`.
+
+```json
+[{"check":"text-over-image","ids":["<text-id>","<image-id>"],"reason":"Intentional type over this photograph; rendered contrast was inspected."}]
+```
+
 ```sh
-# A deliberate finding — say why in the handoff:
-beehaven call canvas-act '{"compositionId":"<id>","action":"canvas.review","args":{"ids":["<frame>"],"accept":[{"check":"text-over-image","ids":["<text-id>","<image-id>"],"reason":"Intentional type over this photograph; rendered contrast was inspected."}]}}'
+node <skill-directory>/review.mjs <composition-id> <frame> canvas-review/02 --accept accepted.json
 ```
 
 Asset storage is a reference-aware pipeline: an SVG may have `svgRef` instead of inline markup.

package/skills/clearly-canvas/authoring.md

@@ -38,15 +38,34 @@ add('canvas.update-nodes', { ids: ['opening-title', 'opening-deck'], patch: { la
 add('canvas.auto-layout', { id: 'hero-copy', direction: 'v', gap: 24, sizingH: 'fixed', sizingV: 'hug' });
 add('canvas.auto-layout', { id: '01-opening', direction: 'v', gap: 64, padding: grid.margin, sizingH: 'fixed', sizingV: 'hug' });
 // Continue with the brief's central visual, supporting evidence and footer.
-writeFileSync('/tmp/canvas-build.json', JSON.stringify({ compositionId, batch }));
+writeFileSync('canvas-build.json', JSON.stringify({ compositionId, batch }));
 ```
 
 ```sh
 beehaven call composition-create '{"title":"Project — concept","projectId":"<project-id>"}'
 node build.mjs <returned-id>
-beehaven call canvas-act @/tmp/canvas-build.json > /tmp/canvas-build-result.json
+beehaven call canvas-act @canvas-build.json --brief
 ```
 
+`--brief` prints a short receipt instead of the full JSON:
+- step counts by kind;
+- layers added, changed and removed;
+- every failed step with its error;
+- rollbacks and skips;
+- lint to fix and review verdicts.
+
+The exit code stays the same. Use it for routine batches instead of piping the JSON through a
+summariser of your own. Drop it when you need a step's full value.
+
+Keep builders, payloads and results in your **working directory**:
+- Write files with your file-writing tool, not shell heredocs or `>` redirects into `/tmp`.
+- Run each `beehaven` command on its own rather than chained with `&&`, `;`, `| tee` or `| head`.
+- Save a large result with `beehaven call <action> '…' --out scene.json` (add `--brief` for the
+  receipt), not `> file`: the whole JSON goes to the file and only a line reaches the console.
+
+Agent hosts that gate shell commands (Claude Code, Codex) refuse heredocs containing JSON and
+compound pipelines outright. One recorded run lost four tool calls that way (MCP2-20).
+
 Check `ok`, each `results[].ok`, `count`, `skipped` and `rolledBack`. A failed headless
 batch may roll back its scene writes. Re-read the scene before deciding what to retry;
 do not blindly resend only skipped operations. Mixed live/headless actions may have
@@ -155,6 +174,7 @@ The same rules the in-app assistant works to (canvas-catalog returns them as `te
 - COMPUTED GEOMETRY: shapes from math (radial petals, spirals, grids) are computed and drawn in ONE call: canvas-act { compositionId, script } runs JavaScript with geo.petal/circle/arc/star/polygon/spiral/smooth/rotate/radial/grid/bounds (degrees, 0 = 3 o'clock, clockwise) and a read-only scene list, then applies the { action, args } steps it returns. Never copy numbers from one tool result into another call. A new top-level artboard goes beside or below what scene already holds (or leave out both x and y), never at 0,0 over an existing one.
 - SHEETS: several concepts or variants go on canvas.sheet { name, title, subtitle, cards or count, cols, cardW, cardH }: a live wrap grid of card frames that own their captions, so rows never overlap. Draw into a card with parentId = its id.
 - MEASURE: answer spacing, overlap and alignment questions with canvas.measure { frame } or { ids } and quote its numbers, never from memory or a preview.
+- REFERENCES: canvas.link {id:<exact frame/item id>} returns a stable URL and Markdown for tickets, documents, comments and inbox refs. Use the returned link instead of a screenshot or a guessed canvas URL. It preserves the parent canvas permissions; rename/move retains the layer id.
 - PLACEHOLDERS: until real imagery exists, draw a native placeholder at the final size in a muted brand tone, never a flat accent block: a rect with the slot radius plus a simple motif (an ellipse sun, a vector.create mountain), grouped with canvas.group and named "<section> image placeholder", with any label in its own text node.
 - SECTIONS: one frame per page section, named exactly as its ticket says, inside the page artboard. Build a section in one canvas-act batch that ends with canvas.review of the artboard and carries ticket: { id: "<its key>", status: "done", resolution: "<what changed>" }. The ticket moves only when that review is clean or look; result.ticket says whether it did. Then start the next section.
 
@@ -215,15 +235,13 @@ the backing shows through as dark wedges at the corners.
 
 ### Images from MCP
 
-The artifact MCP tools do not upload local binary files or dispatch `canvas-act`.
-For an image already reachable by an absolute URL, read the composition with
-`clearly_read {type:"composition",target:<id>}`; append an image node
-`{id,type:"image",src,x,y,w,h,fit:"contain",parentId?}` to the returned complete node
-array; then call `clearly_replace {type:"composition",target:<id>,content:<JSON array>,
-expectedRev:<canvasNodesRev>}`. Preserve every existing node. A stale revision is a
-merge prompt, never a reason to drop `expectedRev`. `clearly_edit` can change an
-existing image's `src`, `fit` or geometry, but cannot create a node. For a local file,
-use the CLI upload path first; an MCP-only client needs a URL it can already access.
+A connector-only agent places an image already reachable by an absolute URL (or a
+`data:` URI) as an `image` node in `clearly_canvas_add_nodes`:
+`{id,type:"image",name,src,x,y,w,h,fit:"contain",parentId?}`. Use PNG or JPEG: the headless
+review cannot draw WebP yet and does not say so (CAN2-188), so a WebP image looks blank in the
+review PNG while the editor shows it. `clearly_canvas_update_nodes`
+changes an existing image's `src`, `fit` or geometry. For a local file in a shell, use the
+CLI upload path first.
 
 Current headless rendering can resolve images, including workspace media. A blank image
 can indicate fetch, decoding or budget failure; check its source and inspect a live view.
@@ -236,8 +254,8 @@ design. Verify the returned artifact in a browser at realistic viewport sizes.
 ## Review and scoped perception
 
 ```sh
-beehaven call canvas-act '{"compositionId":"<id>","action":"canvas.review","args":{"ids":["<frame-id>"]}}' > /tmp/review.json
-beehaven call canvas-perceive '{"compositionId":"<id>","includePixels":true,"fitNodeIds":["<frame-id>"],"pixelScale":1}' > /tmp/perceive.json
+beehaven call canvas-act '{"compositionId":"<id>","action":"canvas.review","args":{"ids":["<frame-id>"]}}' --brief
+beehaven call canvas-perceive '{"compositionId":"<id>","includePixels":true,"fitNodeIds":["<frame-id>"],"pixelScale":1}' > perceive.json
 ```
 
 Use the bundled `review.mjs` to decode the PNG and keep base64 out of the conversation.
@@ -268,7 +286,12 @@ MCP's artifact tools are split by operation:
   node array — pass `expectedRev` from the read.
 - `clearly_edit` patches existing nodes with `changes:{ids,patch}`.
 
-Canvas action dispatch and targeted pixels use the CLI. Do not invent
-`clearly_canvas_act`/`clearly_canvas_perceive` tools. If only MCP is available, use the
-artifact schemas for supported edits and state that pixel review remains unverified.
-Do not claim the design was visually checked from scene JSON alone.
+The connector also has native canvas tools for agents without a shell, batched per kind of
+step rather than mixed (MCP2-22): `clearly_canvas_add_nodes` builds a section per call (up to
+300 frames, shapes, text, pen paths and groups of its own new layers),
+`clearly_canvas_update_nodes {edits:[{ids,patch}]}` revises many layers at once,
+`clearly_canvas_measure_text {texts:[…]}` measures several lines, and
+`clearly_canvas_review` returns the saved artboard as an MCP image to inspect. There is no
+`clearly_canvas_act`: a mixed batch is the CLI's `canvas-act`. In a shell, use the CLI; it
+is fewer calls for the same scene. Do not claim the design was visually checked from scene
+JSON alone.

package/skills/clearly-canvas/review.mjs

@@ -123,14 +123,35 @@ export async function saveReviewPixels(report, prefix, fetchImage = fetch) {
   return saveReview({ ...report, preview: { ...report.preview, dataUrl: `data:image/png;base64,${bytes.toString('base64')}` } }, prefix);
 }
 
+/**
+ * `--accept <findings.json>`: findings you have looked at and are keeping, each
+ * `{ check, ids: [node IDs], reason }`. They stay visible in the report and return `look`.
+ * Without this, a deliberate overlap (steam rising out of a bowl) could only be accepted by
+ * hand-writing the canvas.review call — agents did exactly that (MCP2-20).
+ */
+export function takeAccept(argv) {
+  const i = argv.indexOf('--accept');
+  if (i < 0) return { argv, accept: undefined };
+  const file = argv[i + 1];
+  if (!file || file.startsWith('--')) throw new Error('--accept needs a JSON file: [{"check":"text-over-image","ids":["…"],"reason":"…"}]');
+  const accept = JSON.parse(readFileSync(file, 'utf8'));
+  if (!Array.isArray(accept) || !accept.every(a => a && typeof a.check === 'string' && Array.isArray(a.ids) && a.ids.length && typeof a.reason === 'string' && a.reason.trim())) {
+    throw new Error('--accept file must be an array of { check, ids: [node IDs], reason } with a non-empty reason.');
+  }
+  return { argv: argv.filter((_, j) => j !== i && j !== i + 1), accept };
+}
+
 export async function main(argv = process.argv.slice(2)) {
+  const taken = takeAccept(argv);
+  argv = taken.argv;
+  const accept = taken.accept ? { accept: taken.accept } : {};
   if (argv.includes('--many')) {
     const args = argv.filter(a => a !== '--many');
-    if (args.length !== 3) throw new Error('Usage: node review.mjs --many <compositionId> <artboard-ids.json> <output-directory>');
+    if (args.length !== 3) throw new Error('Usage: node review.mjs --many <compositionId> <artboard-ids.json> <output-directory> [--accept findings.json]');
     const [compositionId, manifest, directory] = args;
     const ids = JSON.parse(readFileSync(manifest, 'utf8'));
     if (!Array.isArray(ids) || !ids.length) throw new Error('The manifest must be a non-empty artboard ID/name array.');
-    const response = rpc('canvas-act', { compositionId, action: 'canvas.review-many', args: { ids, preview: 'files' } });
+    const response = rpc('canvas-act', { compositionId, action: 'canvas.review-many', args: { ids, preview: 'files', ...accept } });
     const reports = response.results?.[0]?.value?.reviews;
     if (!Array.isArray(reports) || reports.length !== ids.length) throw new Error('Incomplete review-many result; do not claim all artboards passed.');
     const saved = [];
@@ -140,7 +161,7 @@ export async function main(argv = process.argv.slice(2)) {
   }
   const legacy = argv.includes('--perceive');
   const args = argv.filter((a) => a !== '--perceive');
-  if (args.length !== 3) throw new Error('Usage: node review.mjs <compositionId> <frame-id-or-name> <output-prefix> [--perceive]\n--perceive: older workers, preview only; pass a frame ID.');
+  if (args.length !== 3) throw new Error('Usage: node review.mjs <compositionId> <frame-id-or-name> <output-prefix> [--accept findings.json] [--perceive]\n--perceive: older workers, preview only; pass a frame ID.');
   const [compositionId, id, prefix] = args;
   let report;
   if (legacy) {
@@ -150,7 +171,7 @@ export async function main(argv = process.argv.slice(2)) {
     report = { preview: response.room?.pixels, visualReviewRequired: true,
       limitations: ['Preview-only compatibility mode. Text metrics and scoped audit were not run.'] };
   } else {
-    const response = rpc('canvas-act', { compositionId, action: 'canvas.review', args: { ids: [id], pixelScale: 1 } });
+    const response = rpc('canvas-act', { compositionId, action: 'canvas.review', args: { ids: [id], pixelScale: 1, ...accept } });
     report = response.results?.[0]?.value;
     if (!report?.scope) throw new Error('canvas.review unavailable. Check canvas-catalog; use --perceive for an explicitly preview-only check on an older worker.');
   }

package/skills/index.json

@@ -17,7 +17,7 @@
       "project-plans.md",
       "review.mjs"
     ],
-    "sha": "e23e25bd46b02d9c"
+    "sha": "4b478740d8ef22c2"
   },
   {
     "name": "agent-home",
@@ -118,5 +118,12 @@
       "SKILL.md"
     ],
     "sha": "b9622f21173bab0d"
+  },
+  {
+    "name": "clearly-artifacts",
+    "files": [
+      "SKILL.md"
+    ],
+    "sha": "14434d4904da91a3"
   }
 ]