@clearlysh/beehaven 0.8.36 → 0.8.37

package/dist/build-channel.js

@@ -53,9 +53,9 @@ export const PUBLIC_BUILD = true;
  * ⚠ REWRITTEN IN `dist/` AT BUILD TIME, like `PUBLIC_BUILD`. `unstamped` is what a source checkout
  * carries and what `tsx`/`vitest` see, and it is honest: nothing has stamped them.
  */
-export const BUILD_SHA = '31746b91dfbf';
+export const BUILD_SHA = '7674ddaca41b';
 /** ISO-8601 minute precision, UTC. Rewritten in `dist/` by `scripts/stamp-build-channel.mjs`. */
-export const BUILD_TIME = '2026-10-29T05:50Z';
+export const BUILD_TIME = '2026-10-29T21:35Z';
 /**
  * The build identity as one short string, for `--version`.
  *

package/dist/call-brief.js

@@ -0,0 +1,157 @@
+/**
+ * `beehaven call <action> … --brief` — a receipt a person (or an agent's context window) can read.
+ *
+ * ⚠⚠ WHY THIS EXISTS. A `canvas-act` batch answers with every step's full value plus the lint of
+ * every touched artboard — routinely tens of kilobytes. Agents learned to pipe it into a summariser
+ * they wrote on the spot (`… 2>&1 | node summ.mjs`), and in the first recorded canvas take (MCP2-20)
+ * that improvisation cost four failed tool calls: shell pipes and `/tmp` redirects need approval in
+ * a headless agent, and the summariser crashed on the stderr breadcrumb it was fed. The receipt the
+ * agent wanted is printed here instead, from the same result, with the exit code unchanged.
+ *
+ * ⚠ IT DROPS NOTHING THAT DECIDES THE NEXT STEP: failed steps (with their error), rollbacks and
+ * skips, lint findings that need fixing, a review's verdict and blocking count. What it leaves out
+ * is bulk — per-step echoes, previews, font metadata. `--json` still prints the whole payload.
+ */
+const clip = (s, n) => {
+    const t = String(s ?? '').replace(/\s+/g, ' ').trim();
+    return t.length > n ? `${t.slice(0, n - 1)}…` : t;
+};
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+/** `canvas.create-node` → `create-node`; `frame.create` stays as written. */
+const verb = (a) => (a.startsWith('canvas.') ? a.slice(7) : a);
+export function briefReceipt(action, result) {
+    const r = (result && typeof result === 'object' ? result : { value: result });
+    const error = typeof r.error === 'string' && r.error ? r.error : null;
+    /**
+     * MCP2-28 (codex review) — A FAILED BATCH IS STILL A BATCH. This returned the one-line refusal for
+     * any `ok:false`, before looking at `results`, so a rolled-back canvas-act (step 2 of 2 refused)
+     * printed a truncated error with no step number and no "rolled back". The batch receipt is read
+     * first; the top-level failure is kept on it, so the exit code still says it failed.
+     */
+    if (Array.isArray(r.results) && r.results.length) {
+        const b = batchReceipt(action, r);
+        if (error || r.ok === false) {
+            b.ok = false;
+            b.lines[0] = b.lines[0].replace(/^✓/, '✗');
+            const why = clip(error ?? r.message ?? r.code ?? '', 200);
+            // Not repeated when a failed step already says it (the step line clips at 140, this at 200).
+            if (why && !b.lines.some((l) => l.includes(why.slice(0, 60))))
+                b.lines.splice(1, 0, `  ${why}`);
+        }
+        return b;
+    }
+    if (error || r.ok === false) {
+        return { ok: false, lines: [`✗ ${action} · ${clip(error ?? r.message ?? r.code ?? 'refused', 160)}`] };
+    }
+    if (Array.isArray(r.results))
+        return batchReceipt(action, r);
+    return { ok: true, lines: [`✓ ${action}${describeValue(r)}`] };
+}
+function batchReceipt(action, r) {
+    const steps = r.results;
+    const failed = steps.map((s, i) => ({ s, i })).filter(({ s }) => s?.ok === false);
+    const lines = [];
+    // What ran: a review or a set of measurements reads better as its result than as a step count.
+    const reviews = steps.filter((s) => /canvas\.review/.test(s?.action) && s?.ok !== false);
+    const measures = steps.filter((s) => s?.action === 'canvas.measure-text' && s?.ok !== false);
+    const counts = new Map();
+    for (const s of steps)
+        counts.set(verb(s?.action ?? '?'), (counts.get(verb(s?.action ?? '?')) ?? 0) + 1);
+    const mix = [...counts].sort((a, b) => b[1] - a[1]).slice(0, 3).map(([a, n]) => (n > 1 ? `${a} ×${n}` : a)).join(', ');
+    let added = 0, changed = 0, removed = 0, sawDelta = false;
+    for (const s of steps) {
+        const d = s?.value?.canvasChanges;
+        if (d && typeof d === 'object' && !Array.isArray(d)) {
+            sawDelta = true;
+            added += Number(d.added || 0);
+            changed += Number(d.changed || 0);
+            removed += Number(d.removed || 0);
+        }
+    }
+    const rev = r.canvasNodesRev ?? [...steps].reverse().find((s) => s?.value?.canvasNodesRev != null)?.value?.canvasNodesRev;
+    const head = [`${failed.length ? '✗' : '✓'} ${action}`, `${plural(steps.length, 'step')}${mix ? ` (${mix})` : ''}`];
+    if (sawDelta && added + changed + removed)
+        head.push(`+${added} ~${changed} −${removed} layers`);
+    if (rev != null)
+        head.push(`rev ${rev}`);
+    if (r.rolledBack)
+        head.push('rolled back');
+    if (r.partial)
+        head.push('partly applied');
+    if (Array.isArray(r.skipped) ? r.skipped.length : r.skipped)
+        head.push(`${Array.isArray(r.skipped) ? r.skipped.length : r.skipped} skipped`);
+    lines.push(head.join(' · '));
+    for (const { s, i } of failed.slice(0, 3)) {
+        lines.push(`  ✗ step ${i + 1} ${verb(s.action ?? '?')}: ${clip(s.error ?? s.value?.error ?? 'failed', 140)}`);
+    }
+    if (failed.length > 3)
+        lines.push(`  … ${failed.length - 3} more failed steps`);
+    for (const m of measures.slice(0, 6)) {
+        const v = m.value ?? {};
+        lines.push(`  ${Math.round(v.width ?? 0)}×${Math.round(v.height ?? 0)} · ${plural(v.lineCount ?? 1, 'line')}${v.exact === false ? ' · estimated' : ''} — ${v.family ?? ''} ${v.size ?? ''}/${v.fontWeight ?? ''}`.trimEnd());
+    }
+    for (const rv of reviews) {
+        const v = rv.value ?? {};
+        const reports = Array.isArray(v.reviews) ? v.reviews : [v];
+        for (const rep of reports) {
+            const blocking = rep.blocking?.craft ?? 0;
+            const where = rep.scope?.name ?? rep.scope?.ids?.[0] ?? '';
+            lines.push(`  review${where ? ` ${clip(where, 40)}` : ''}: ${rep.verdict ?? 'unknown'}${blocking ? ` · ${plural(blocking, 'blocking finding')}` : ''}`);
+            for (const f of (rep.craft?.findings ?? []).filter((x) => x.severity === 'warn').slice(0, 3)) {
+                lines.push(`    ${f.check}: ${clip(f.detail, 120)}`);
+            }
+        }
+    }
+    // Lint of the touched artboards: what must be fixed next, never the whole report.
+    for (const d of (Array.isArray(r.diagnostics) ? r.diagnostics : [])) {
+        const errors = d.errors ?? [];
+        if (!errors.length && d.verdict !== 'fix')
+            continue;
+        lines.push(`  lint ${clip(d.artboard ?? d.id, 40)}: ${d.verdict ?? 'fix'}`);
+        for (const e of errors.slice(0, 3))
+            lines.push(`    ${clip(e, 140)}`);
+        if (errors.length > 3 || d.moreErrors)
+            lines.push(`    … ${(errors.length - 3 > 0 ? errors.length - 3 : 0) + (d.moreErrors ?? 0)} more`);
+    }
+    const clean = (Array.isArray(r.diagnostics) ? r.diagnostics : []).filter((d) => d.verdict && d.verdict !== 'fix');
+    if (clean.length)
+        lines.push(`  lint ${[...new Set(clean.map((d) => d.verdict))].join('/')} on ${plural(clean.length, 'artboard')}`);
+    /**
+     * MCP2-25 — THE CARRIED TICKET'S OUTCOME DECIDES THE NEXT STEP TOO. A batch carrying `ticket` moves
+     * it only when its review passes; the receipt said nothing either way, so an agent could not tell a
+     * done commit from one the review held back.
+     */
+    const t = r.ticket;
+    if (t && typeof t === 'object') {
+        if (t.applied)
+            lines.push(`  ticket ${t.key ?? t.id} → ${t.status ?? 'updated'}${t.frame?.url ? ` · frame ${t.frame.url}` : ''}`);
+        else
+            lines.push(`  ✗ ticket ${t.id ?? ''} not moved: ${clip(t.reason ?? t.error ?? 'refused', 200)}`);
+    }
+    return { ok: failed.length === 0, lines };
+}
+/** A one-line description of an ordinary result: its identity and what it holds. */
+function describeValue(r) {
+    const bits = [];
+    const id = r.key ?? r.id ?? r.compositionId ?? r.documentId;
+    if (id)
+        bits.push(String(id).length > 24 ? String(id).slice(0, 8) : String(id));
+    const title = r.title ?? r.name;
+    if (typeof title === 'string' && title)
+        bits.push(`"${clip(title, 60)}"`);
+    if (typeof r.status === 'string')
+        bits.push(r.status);
+    if (r.verdict)
+        bits.push(`verdict ${r.verdict}`);
+    for (const [k, v] of Object.entries(r)) {
+        if (Array.isArray(v) && v.length && bits.length < 4 && !['results', 'diagnostics'].includes(k))
+            bits.push(`${v.length} ${k}`);
+    }
+    if (typeof r.count === 'number' && !bits.some((b) => b.endsWith(' items')))
+        bits.push(`count ${r.count}`);
+    if (typeof r.url === 'string')
+        bits.push(r.url);
+    if (r.value !== undefined && typeof r.value !== 'object')
+        bits.push(clip(r.value, 120));
+    return bits.length ? ` · ${bits.join(' · ')}` : '';
+}

package/dist/claude-bridge.js

@@ -22,6 +22,7 @@ import { homedir } from 'os';
 import { EventEmitter } from 'events';
 import { activeAgentWrap } from './agent-attribution.js';
 import { ipcSocketPath, watcherSocketPath, socketMayExist } from './ipc-path.js';
+import { utf8Stream } from './utf8-stream.js';
 const CONFIG_DIR = join(homedir(), '.beehaven');
 export class ClaudeBridge extends EventEmitter {
     socket = null;
@@ -56,8 +57,10 @@ export class ClaudeBridge extends EventEmitter {
                 this.send({ type: 'session:announce', label: 'claude-code', app: 'bridge' });
                 resolve(true);
             });
+            // CA-63 — decode the stream, not each chunk: a character split across two reads stays whole.
+            const decode = utf8Stream();
             socket.on('data', (data) => {
-                this.buffer += data.toString();
+                this.buffer += decode(data);
                 const lines = this.buffer.split('\n');
                 this.buffer = lines.pop() || '';
                 for (const line of lines) {

package/dist/cli.js

@@ -408,7 +408,7 @@ ${DEV_ONLY_HELP ? `
     beehaven actions --all         …including ones this caller cannot invoke
     beehaven actions --search <q>  Find one by substring
     beehaven explain <action>      Its exact arguments, from the live schema
-    beehaven call <action> [json]  Invoke it; returns the raw JSON result
+    beehaven call <action> [json]  Invoke it; returns the raw JSON result (--brief: a short receipt; --out <file>: the JSON to a file)
 
     # discover, then run
     beehaven actions --search ticket
@@ -1443,6 +1443,8 @@ async function run() {
             address: { type: 'string' },
             protocol: { type: 'string' },
             json: { type: 'boolean', default: false },
+            // `beehaven call … --brief`: a short receipt instead of the full JSON (call-brief.ts).
+            brief: { type: 'boolean', default: false },
             // `--conversation <id>` threads `beehaven agent "<msg>"` onto an existing
             // Omni thread instead of minting a new one per invocation.
             conversation: { type: 'string' },
@@ -2090,6 +2092,8 @@ async function run() {
         'slides', 'deck',
         // `brand tokens -o tokens.css` · `component render -o button.svg`
         'brand', 'brands', 'component', 'components',
+        // MCP2-25 — `call <action> … --out result.json`: the whole result to a file, the receipt to the console.
+        'call',
     ]);
     /**
      * ⚠ ONE REFUSAL, because there is now one flag. Both spellings are named in the message so a

package/dist/commands/help.js

@@ -715,7 +715,7 @@ const PAGES = {
         related: ['call', 'pwd', 'workspace'],
     },
     call: {
-        synopsis: 'beehaven call <action> [json-input] [--building <type>:<id>] [--json]',
+        synopsis: 'beehaven call <action> [json-input | @file | -] [--building <type>:<id>] [--json | --brief]',
         description: `Invoke an RPC on the current target. Input is a JSON string.
     Schema comes from the action's manifest — use \`beehaven actions\` first
     to see what's available, or \`beehaven explain <action>\` for the exact
@@ -725,10 +725,12 @@ const PAGES = {
         flags: [
             { name: '--building <type>:<id>', desc: 'Explicit target (e.g. shopifyStore:clearly-demo)' },
             { name: '--json', desc: 'Suppress breadcrumb + hint blocks; raw stdout only' },
+            { name: '--brief', desc: 'A short receipt instead of the JSON: steps, layer changes, failures, lint to fix, review verdicts. Same exit code.' },
             { name: '--timeout <ms>', desc: 'Override the 30s default' },
         ],
         examples: [
             { cmd: 'beehaven call note-create \'{"title":"Hello"}\'' },
+            { cmd: 'beehaven call canvas-act @build.json --brief', note: 'a canvas batch, read as a one-line receipt' },
             { cmd: "beehaven call project-list '{}' --building home" },
             {
                 cmd: 'beehaven call admin-agent-chat \'{"conversationId":"c1","message":"top sellers?","scope":"read"}\'',

package/dist/commands/workspace.js

@@ -1132,7 +1132,36 @@ export async function cmdCall(action, rawInput, values) {
             printCallErrorHints(raw.message, action, values);
             process.exit(1);
         }
-        if (result && typeof result === 'object') {
+        /**
+         * MCP2-25 — `call … --out <file>` writes the whole JSON result to a file. The canvas skill tells
+         * agents to save a large response once and read a summary, and the only way was `> file`, which a
+         * headless agent needs permission for: a recorded Claude Code take lost a call to "`--out` is not
+         * supported by `beehaven call`". The receipt (or a one-line note) still prints; the exit code is
+         * the result's, exactly as without the flag.
+         */
+        const outPath = values.out ?? values.output;
+        if (typeof outPath === 'string' && outPath) {
+            const { mkdirSync, writeFileSync } = await import('node:fs');
+            const { dirname, resolve } = await import('node:path');
+            const file = resolve(outPath);
+            mkdirSync(dirname(file), { recursive: true });
+            const text = result && typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
+            writeFileSync(file, text + '\n');
+            if (!values.brief)
+                console.log(`wrote ${text.length.toLocaleString()} bytes to ${outPath}`);
+        }
+        let briefFailed = false;
+        if (values.brief && !values.json) {
+            // ⚠ THE SAME RESULT, READ FOR A PERSON — see call-brief.ts for what is kept and why.
+            const { briefReceipt } = await import('../call-brief.js');
+            const receipt = briefReceipt(action, result);
+            console.log(receipt.lines.join('\n'));
+            briefFailed = !receipt.ok;
+        }
+        else if (typeof outPath === 'string' && outPath) {
+            // Written above; the console keeps only the note, so a large result stays out of the context.
+        }
+        else if (result && typeof result === 'object') {
             console.log(JSON.stringify(result, null, 2));
         }
         else {
@@ -1234,7 +1263,7 @@ export async function cmdCall(action, rawInput, values) {
             }
             printKnownActionAdvice(action, input, result);
         }
-        if (isFailureResult(result))
+        if (briefFailed || isFailureResult(result))
             process.exit(1);
     }
     catch (err) {

package/dist/daemon-client.js

@@ -18,6 +18,7 @@ import net from 'net';
 import { resolveClientAuthToken } from './ipc-auth.js';
 import { activeAgentWrap } from './agent-attribution.js';
 import { ipcSocketPath, socketMayExist } from './ipc-path.js';
+import { utf8Stream } from './utf8-stream.js';
 const TIMEOUT_MS = 60_000;
 const AUTH_TIMEOUT_MS = 3_000;
 /** One attempt. Resolves, never rejects. */
@@ -112,8 +113,10 @@ function handshake(socket) {
             socket.removeListener('data', onData);
             reject(new Error('IPC auth handshake timeout'));
         }, AUTH_TIMEOUT_MS);
+        // CA-63 — decode the stream, not each chunk: a character split across two reads stays whole.
+        const decode = utf8Stream();
         const onData = (chunk) => {
-            buffer += chunk.toString();
+            buffer += decode(chunk);
             const lines = buffer.split('\n');
             buffer = lines.pop() || '';
             for (const line of lines) {
@@ -218,8 +221,10 @@ function sendIpc(socket, msg) {
             socket.removeListener('data', onData);
             reject(new Error(`Daemon RPC timeout after ${TIMEOUT_MS}ms`));
         }, TIMEOUT_MS);
+        // CA-63 — decode the stream, not each chunk: a character split across two reads stays whole.
+        const decode = utf8Stream();
         const onData = (chunk) => {
-            buffer += chunk.toString();
+            buffer += decode(chunk);
             const lines = buffer.split('\n');
             buffer = lines.pop() || '';
             for (const line of lines) {

package/dist/ipc-client.js

@@ -11,6 +11,7 @@ import { EventEmitter } from 'events';
 import { resolveClientAuthToken } from './ipc-auth.js';
 import { ipcSocketPath, socketMayExist } from './ipc-path.js';
 import { activeAgentWrap } from './agent-attribution.js';
+import { utf8Stream } from './utf8-stream.js';
 /** The default address (Unix socket, or this user's named pipe on Windows) — see `ipc-path.ts`. */
 const IPC_SOCKET_PATH = ipcSocketPath();
 /** Default timeout for RPC calls (ms) */
@@ -77,8 +78,10 @@ export class IpcClient extends EventEmitter {
             socket.on('connect', () => {
                 this._connected = true;
             });
+            // CA-63 — decode the stream, not each chunk: a character split across two reads stays whole.
+            const decode = utf8Stream();
             socket.on('data', (data) => {
-                this.buffer += data.toString();
+                this.buffer += decode(data);
                 const lines = this.buffer.split('\n');
                 this.buffer = lines.pop() || '';
                 for (const line of lines) {

package/dist/ipc-server.js

@@ -27,6 +27,7 @@ import { createConnection, createServer } from 'net';
 import { EventEmitter } from 'events';
 import { resolveAuthScope } from './ipc-auth.js';
 import { ipcSocketPath, socketMayExist, clearStaleSocket, restrictSocketToOwner } from './ipc-path.js';
+import { utf8Stream } from './utf8-stream.js';
 /** The default address (Unix socket, or this user's named pipe on Windows) — see `ipc-path.ts`. */
 const IPC_SOCKET_PATH = ipcSocketPath();
 /**
@@ -194,8 +195,10 @@ export class IpcServer extends EventEmitter {
                 daemonPid: process.pid,
                 requireAuth: true,
             });
+            // CA-63 — decode the stream, not each chunk: a character split across two reads stays whole.
+            const decode = utf8Stream();
             socket.on('data', (data) => {
-                client.buffer += data.toString();
+                client.buffer += decode(data);
                 const lines = client.buffer.split('\n');
                 client.buffer = lines.pop() || '';
                 for (const line of lines) {

package/dist/relay.js

@@ -777,10 +777,14 @@ 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);
@@ -1098,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);

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": "@clearlysh/beehaven",
-  "version": "0.8.36",
+  "version": "0.8.37",
   "description": "Beehaven CLI — command your Clearly workspace, agents, and canvas from the terminal",
   "private": false,
   "type": "module",

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",