@clearlysh/beehaven 0.8.27 → 0.8.29

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 = 'db2b3eaeb90b';
+export const BUILD_SHA = 'd733c0004e58-dirty';
 /** ISO-8601 minute precision, UTC. Rewritten in `dist/` by `scripts/stamp-build-channel.mjs`. */
-export const BUILD_TIME = '2026-10-07T02:00Z';
+export const BUILD_TIME = '2026-10-10T21:21Z';
 /**
  * The build identity as one short string, for `--version`.
  *

package/dist/clearly.js

@@ -47,11 +47,12 @@ const c = {
     red: (s) => `\x1b[31m${s}\x1b[0m`,
 };
 /**
- * ⚠ THE AGENT TURN IS THE SLOW PART AND THE CLI RELAY CAPS AT 180s. `RESPOND_TIMEOUT_MS` on the
- * server is the same 180s, so a turn that outlives this was going to be killed anyway — matching
- * them means a timeout here always means the same thing it means there.
+ * ⚠ THE AGENT TURN IS THE SLOW PART. The server's `RESPOND_TIMEOUT_MS` is 300s (clearly CDS-90, was
+ * 180s); this waits that plus the report's tail, so a turn that finishes on time is never abandoned
+ * by its caller and a timeout here still means the turn itself ran out. The relay-forward window
+ * follows the `_timeout` sent with the call.
  */
-const TURN_MS = 180_000;
+export const TURN_MS = 330_000;
 /**
  * ⚠ STDERR IS CAPTURED, NOT INHERITED. A failing probe is normal here — `HEAD~30` does not exist in
  * a repo with two commits — and with inherited stderr git printed

package/dist/cli.js

@@ -3917,7 +3917,7 @@ complete -F _beehaven_completions beehaven`);
             console.log(`  ${r.url}`);
             // "reached" not "navigated": the frame goes to every connected surface but only the
             // VISIBLE one acts on it, so a count of sockets is not a count of things that moved.
-            console.log(color.dim(`  ${r.delivered > 0 ? `on screen (reached ${r.delivered} connected surface(s))` : 'no tab connected'}`));
+            console.log(color.dim(`  ${r.delivered > 0 ? `navigation requested (${r.delivered} connected surface(s)); editor display is not yet verified` : 'no navigation recipient connected'}`));
             // Only reach for the local browser when asked, or when nothing was
             // delivered — opening a window under someone who already has the tab
             // focused is worse than doing nothing.

package/dist/commands/workspace.js

@@ -26,7 +26,10 @@ import { resolveActiveAgent } from '../agent-state.js';
 import { isAgentRuntime } from '../agent-scope.js';
 import { getTarget } from '../cli-state.js';
 import { attachShellCwd, absorbShellCwd, shellTargetKey } from '../shell-session.js';
-export function getTimeout(values) {
+/** Workspace-agent turns wait for the server's turn ceiling (300s) plus the report's tail. */
+export const AGENT_TURN_TIMEOUT_MS = 330_000;
+const AGENT_TURN_ACTIONS = new Set(['agent-prompt', 'agent-turn']);
+export function getTimeout(values, action) {
     // Precedence: explicit --timeout flag → BEEHAVEN_RPC_TIMEOUT_MS env → default.
     // The default is generous because real jobs (sticker-sheet gen, renders,
     // long agent turns) routinely run well past the old 30s and shouldn't need a
@@ -37,7 +40,8 @@ export function getTimeout(values) {
     const env = process.env.BEEHAVEN_RPC_TIMEOUT_MS;
     if (env && Number.isFinite(Number(env)) && Number(env) > 0)
         return parseInt(env, 10);
-    return 180_000;
+    // An agent turn may run to the server's 300s ceiling (clearly CDS-90); waiting less abandons it.
+    return action && AGENT_TURN_ACTIONS.has(action) ? AGENT_TURN_TIMEOUT_MS : 180_000;
 }
 /**
  * True when `msg` says `action` isn't available on the target DO.
@@ -618,11 +622,24 @@ export async function cmdActions(values, positional) {
                 grouped.set(cat, []);
             grouped.get(cat).push(action);
         }
+        if (!values.verbose && !values.category && !values.search) {
+            for (const [category, entries] of grouped) {
+                console.log(`  ${category.padEnd(18)} ${String(entries.length).padStart(3)} actions · ${entries.slice(0, 3).map(a => a.name).join(', ')}${entries.length > 3 ? ', …' : ''}`);
+            }
+            console.log('');
+            console.log('  Find an action: beehaven actions --search <term>');
+            console.log('  List a category: beehaven actions --category <name>');
+            console.log('  Exact schema: beehaven explain <action>');
+            console.log('  Complete inventory: beehaven actions --verbose or --format full --json');
+            return;
+        }
         for (const [category, catActions] of grouped) {
             const catLabel = category.charAt(0).toUpperCase() + category.slice(1);
             console.log(`  \x1b[36m${catLabel}\x1b[0m (${catActions.length})`);
             for (const a of catActions) {
-                const desc = a.description ? `  \x1b[90m${a.description}\x1b[0m` : '';
+                const description = String(a.description || '');
+                const display = values.verbose || description.length <= 160 ? description : `${description.slice(0, 157)}…`;
+                const desc = display ? `  \x1b[90m${display}\x1b[0m` : '';
                 const aliasLabel = Array.isArray(a.aliases) && a.aliases.length > 0
                     ? `  \x1b[2m(also: ${a.aliases.join(', ')})\x1b[0m`
                     : '';
@@ -1088,7 +1105,7 @@ export async function cmdCall(action, rawInput, values) {
         console.error(`\x1b[2m→ ${target}  ${action}${who}\x1b[0m`);
     }
     try {
-        const raw = await rpcOnce(resolved.action, resolved.input, getTimeout(values));
+        const raw = await rpcOnce(resolved.action, resolved.input, getTimeout(values, action));
         // Unwrap proxy envelope: admin:*-rpc wraps results in { type: 'ack', result: ... }
         const result = raw?.type === 'ack' && raw?.result !== undefined
             ? raw.result
@@ -3090,7 +3107,7 @@ export async function cmdAgent(prompt, values) {
                 : {}),
         }, 
         // Omni runs tools; the CLI default is far too short for a real turn.
-        getTimeout(values) || 180_000);
+        getTimeout(values, 'agent-turn'));
         /**
          * Print the REPLY, not the envelope. The whole response is still available
          * with `--json` — but a verb whose entire purpose is "ask a question and read

package/dist/relay-presets.js

@@ -67,9 +67,8 @@ export function resolveRelaySelection(cfg) {
  *   `https://localhost:3000` (canvas.ts's `--dev` branch). They are not interchangeable: the apex
  *   301s to www, so the apex spelling handed people a link with a redirect in it.
  *
- * ⚠ STAGING RETURNS THE PRODUCTION SITE, AND THAT IS CORRECT. The frontend is prod-only — the
- * `staging.clearly-sh.pages.dev` alias is retired (CLAUDE.md) — so the staging worker's app really
- * is `www.clearly.sh`. Inventing a `staging.clearly.sh` here would be the dead-link bug again.
+ * Staging uses the local HTTPS frontend (Clearly AGENTS.md, 2026-10-08). Its workspace IDs
+ * belong to staging and must never be linked into the production frontend.
  *
  * ⚠ `custom` RETURNS undefined, DELIBERATELY. A custom relay says nothing about where its frontend
  * is, and guessing production for it is how you hand someone a link into the wrong deployment.
@@ -78,10 +77,10 @@ export function resolveRelaySelection(cfg) {
 export function appOriginForEnv(envName) {
     switch (envName) {
         case 'prod':
-        case 'staging':
             return 'https://www.clearly.sh';
         // `npm run dev` is `next dev --experimental-https`, so the local app is HTTPS, not HTTP.
         case 'dev':
+        case 'staging':
             return 'https://localhost:3000';
         default:
             return undefined;

package/package.json

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

package/skills/beehaven-cli/SKILL.md

@@ -25,6 +25,18 @@ beehaven cd home                   # back to the default workspace
 beehaven disconnect                # end the session
 ```
 
+Start discovery narrowly: `beehaven explain <action>` gives one schema; `beehaven actions
+--search <term>` or `--category <name>` bounds the inventory. The default inventory is compact;
+`--verbose` or `--format full --json` requests full detail. Save large JSON once and print a
+small summary rather than repeating a call after output truncation.
+
+For ticket text search use `ticket-list {text:"…",projectId?,fields?,limit?}` (`query` and `q`
+are aliases). For a design setup, `design-start {title,projectId?,boardId?,idempotencyKey}` creates or
+resumes the linked artifacts using the normal permissions. Preserve idempotencyKey across retries;
+requestId is reserved by the transport.
+For supported canvas mutations inspect actual `updated` IDs, `outcome`, ignored/rejected fields
+and warnings. A navigation request reaching a socket is not a verified editor display.
+
 Once `cd`'d, **every** verb auto-routes to that target: `actions`, `call`, `sql`, `ls`, `cat`, `tree`, `grep`, `watch`, `logs`, `workspace`, `ask`. Switch by `cd`-ing again.
 
 ```bash

package/skills/brand-identity/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: brand-identity
 description: >-
-  Build a complete brand identity on a Clearly canvas the way a studio does —
+  Design the requested logo or brand identity on a Clearly canvas —
   brief, mark, wordmark, lockups and clear space, palette, type system,
   applications, and a spec board someone else can build from. Use when asked
   for a brand, a logo, an identity, a rebrand, a visual system, brand
@@ -13,10 +13,14 @@ description: >-
 
 # brand-identity — a system, not a picture of a logo
 
-⚠⚠ **THE DELIVERABLE IS A SYSTEM SOMEONE ELSE CAN BUILD WITH.** A single mark on a white
-artboard is not an identity; it is a drawing. Pentagram's identity work ships a symbol, a
-wordmark, a graphic system, a palette, a type system and the guidelines that let an in-house
-team keep it consistent. That is the shape to copy.
+Match the user's scope. For a logo concept, deliver the editable mark/wordmark, primary and
+one-color use, a small-size check, and the requested application. A logo plus landing page does
+not require merchandise, storefronts or a complete guideline deck. Add those when requested or
+when a concrete use in the brief requires them.
+
+For a complete identity request, the deliverable is a system someone else can build with:
+symbol, wordmark, palette, typography, applications and guidelines. Sections 6–8 describe that
+larger scope; they are optional for a narrow concept.
 
 Read **`design-craft`** first or alongside — grid, type scale, colour roles and the studio
 pass are assumed here.
@@ -93,7 +97,9 @@ good. If it does not work in flat black, the shape is wrong and the gradient is
 - ⚠ **A wordmark is always tracked tighter than body text.** At display size, `letterSpacing`
   −1 to −4. Then fix the specific pairs the font gets wrong (an uppercase A next to a V, a
   T next to a lowercase o).
-- **Lockups are a fixed set, not an invitation.** Ship exactly these and say so:
+- **For a full identity, define this fixed set.** For a concept, deliver the requested lockup
+  plus the mark-only and one-color forms needed for its smallest use. Additional lockups are
+  optional unless the brief asks for them:
 
 ```
 primary      mark + wordmark, horizontal    ← the default
@@ -225,11 +231,11 @@ Run `design-craft`'s studio pass, plus these identity-specific ones:
 ```
 □ Rendered the mark at 24px and LOOKED at it
 □ Mark works in flat black, flat white, and knocked out
-□ Every lockup has stated clear space and minimum size
+□ Every delivered lockup has stated clear space and minimum size
 □ Palette has a dark-ground variant and role sentences
 □ Type scale has NUMBERS, not just face names
-□ At least 4 real applications, at real proportions
-□ Misuse section exists
+□ Requested applications at real proportions (4–6 for a full identity; the requested surface for a concept)
+□ Misuse section exists for a full identity; a concise use note is enough for a logo concept
 □ Put the mark beside the competitor named in UNLIKE — still distinct?
 □ Can someone build a new asset from this board without asking a question?
 ```

package/skills/clearly-agent/SKILL.md

@@ -190,6 +190,19 @@ task changes a product's UI, the composition comes FIRST: build the screen and i
 `canvas.review` it, link it to the ticket (`work-link {ticketId, kind:"design", refKind:"composition",
 refId}`), then implement. `clearly-canvas` §0 has the details.
 
+No brand yet (`brand-tokens` answers `brand-not-found`) for a real company? Ask the person for their
+website rather than inventing a palette, then:
+
+1. `beehaven call brand-import '{"url":"theirsite.com","dryRun":true}'` — colours by role, faces, logos,
+   voice and shape, each with its reason in `provenance`. Tell the person what you read.
+2. Ask what to call the brand (`suggestedName` is what the site calls itself — a suggestion, not a default).
+3. `beehaven call brand-import '{"url":"theirsite.com","name":"<their answer>"}'` saves it (the read is
+   reused; the first brand becomes the workspace default). Without `name` nothing is saved:
+   `brand-name-required`.
+
+`brandId` + `apply:["colors","type"]` refreshes an existing brand as a new version instead. Licensed faces
+come back set in the closest free one — `faces` says which.
+
 ## When a write is refused
 
 `agent-denied-create` / `-update` / `-delete` mean your **capability matrix** said no. It covers the

package/skills/clearly-canvas/SKILL.md

@@ -22,6 +22,10 @@ stored. A rendered image you have inspected is the evidence for visual quality.
 For a small correction, keep the existing direction and make the smallest useful edit.
 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.
+
 ## The studio bar — what "done" means, every time
 
 Load **`design-craft`** before any new visual work: grid, type scale, colour roles,
@@ -33,8 +37,9 @@ A composition is done when every requested artboard meets all four conditions:
 1. **`canvas.review` verdict is `clean` or `look`.** `fix` means a probable defect
    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. When it is deliberate, pass the check name or layer in
-   `ignore` and say why in the handoff.
+   placeholder copy. Fix it. For an intentional finding, use
+   `accept:[{check,ids:[node IDs],reason}]`. 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.
 3. **You inspected the rendered PNG** against design-craft's studio pass, covering what no
@@ -54,8 +59,9 @@ build from them — redrawing a button the library already has is how designs dr
 product they describe.
 
 ```sh
-beehaven call brand-tokens '{}'                                   # colours (light + dark), type roles, radius, logos, voice
-beehaven call component-list '{"query":"<brand or kind>"}'        # parts, with props, variants and the code they mirror
+beehaven call brand-tokens '{"compact":true}'                     # roles without repeated CSS/prose
+beehaven call brand-import '{"url":"theirsite.com","dryRun":true}' # no brand yet? read it off their website
+beehaven call component-list '{"query":"<kind>","compact":true}' # IDs, dimensions and prop names
 beehaven call component-instantiate '{"compositionId":"<id>","instances":[
   {"id":"<component>","x":96,"y":200,"variant":"Light"},
   {"id":"<component>","x":96,"y":280,"variant":"Light","props":{"label":"Save changes"}}]}'
@@ -68,8 +74,9 @@ beehaven call component-instantiate '{"compositionId":"<id>","instances":[
   `component-create` (or `{ fromCompositionId, nodeId }` to save one you drew).
 - Component node coordinates are relative to the component ROOT, even under an inner
   frame — the opposite of `canvas.create-node`, where x/y follow `parentId`.
-- If the workspace has a brand kit, it IS the system for the brief: use its roles, faces
-  and voice rather than inventing a palette. Change the brand itself only when asked.
+- For Clearly product UI, use its brand kit. For a separate client, use that client's kit
+  and supplied assets. A requested new client identity is scoped to that composition;
+  it does not change the workspace's default brand.
 
 **UX design before implementation.** When the work is a change to a product's UI, the
 composition is the design the code will answer to: show the real states (empty, loading,
@@ -107,6 +114,33 @@ beehaven call canvas-perceive '{"compositionId":"<id>","format":"json"}'
 beehaven call canvas-catalog '{"query":"create-node"}'
 ```
 
+A canvas is planned like a git repository: its own plan board, a WORK TICKET for the request, and
+COMMITS — one ticket per coherent layer or section of a larger change.
+`design-start {title, brandId?}` makes a PRIVATE DRAFT canvas, bound to the brand, with its private
+plan board and the work ticket, and returns `{ compositionId, ticketId, ticketKey, boardId, brand }`.
+Same title again returns the same draft. Nothing is shared until it is filed:
+`design-file {compositionId, projectId | projectTitle}` moves the canvas — plan board and every
+ticket with it — into the project the person chose and sends the work ticket to in-review. Ask which
+project unless they named one; a close-but-different title answers `similar-projects` with
+candidates. Repeat-safe.
+Plan a larger change before drawing, the way you would split a big code change into commits:
+`design-plan {compositionId, commits: ["Grid, type and colour styles", "Nav", "Hero", …]}` (drafts
+and filed canvases alike) adds ordered commit tickets under the work ticket. `sections: true` uses
+the landing-page set (set up frames and styles, nav bar, hero, highlights, offer, story, call to
+action, footer, mobile, states); `phases: true` and a `brief` add the studio method (brief, research,
+structure, direction, design, review) — load the `design-process` skill. Order commits so each
+builds on the last and can be reviewed alone. Build ONE commit per canvas-act batch that ends with
+`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 and SVG placeholders:
+see "Technique" in [authoring.md](authoring.md).
+
+`composition-board-get {compositionId}` reads the plan back. `design-start` with a project, ticket or
+`phases` still sets up planned work directly (kept for one release).
+For an existing task, reuse its ticket/project. Check one unknown action with
+`beehaven explain <action>` or a filtered catalog; do not download the entire registry.
+
 Use the composition supplied by the user. If none is named, inspect recent titles and
 context; create a clearly titled composition for new work instead of modifying an
 arbitrary recent canvas. File shared work into its project.
@@ -188,6 +222,10 @@ For a single page, establish the complete hierarchy before polishing small detai
 Use a batch for each coherent build or revision, with descriptive unique layer names.
 Parent content to its artboard. Inspect every operation result and rollback status.
 Save your builder and returned IDs so revisions are targeted and reproducible.
+Check `ignoredFields`, `rejectedFields`, `warnings`, `outcome` and `canvasChanges` as well as
+`ok/count`. `matched` is not `updated`. An unchanged or partly ignored request does not prove
+the intended edit happened. Read `composition-detail {includeScene:true}` from its top-level
+`nodes`; never treat a missing response field as an empty scene. Keep executed payloads immutable.
 
 ⚠ **Batch, never loop.** One `canvas-act` batch of hundreds of steps is one scene read,
 persisted every 50 steps, and the workspace stays responsive for everyone in it while it
@@ -225,6 +263,12 @@ It invokes `canvas.review` on one persisted snapshot and returns:
   type and palette sprawl, near-miss edges, trim crowding, text over imagery;
 - the placeholder/overflow audit, measured text fit, and a preview PNG.
 
+For several artboards, write their IDs/names as a JSON array and use:
+`node <skill-directory>/review.mjs --many <composition-id> <ids.json> <output-directory>`.
+This uses `canvas.review-many`: one scene read, separate findings per artboard and compact
+preview handles. Review only artboards changed since their verified snapshot. The helper versions
+existing output paths so before/after evidence is retained.
+
 The helper prints the verdict and every finding. Work until the verdict is `clean` or
 `look`, as described in the studio bar above. If the installed worker lacks `canvas.review`,
 use a real frame ID with `--perceive` for a preview-only check and run the text measurement
@@ -232,9 +276,16 @@ and audit separately. A failed or missing render means visual verification is in
 
 ```sh
 # A deliberate finding — say why in the handoff:
-beehaven call canvas-act '{"compositionId":"<id>","action":"canvas.review","args":{"ids":["<frame>"],"ignore":["text-over-image"]}}'
+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."}]}}'
 ```
 
+Asset storage is a reference-aware pipeline: an SVG may have `svgRef` instead of inline markup.
+Do not shrink or recreate it just because the inline field is absent. Replace it with
+`canvas.update-nodes {ids, patch:{svg:<complete markup>}}`; references are managed by the action.
+Use `canvas.fonts` before choosing an unfamiliar family/weight. Fallback metrics are not exact.
+Use `canvas.editor-state {requireLive:true,includePixels:true}` to verify the responding editor.
+An agent camera and a navigation delivery count do not prove the person's view was framed.
+
 Inspect the actual image and identify concrete defects, not generic praise:
 
 | Lens | What to judge |

package/skills/clearly-canvas/authoring.md

@@ -49,6 +49,12 @@ do not blindly resend only skipped operations. Mixed live/headless actions may h
 different rollback behavior. Use deterministic layer names and returned IDs to avoid
 duplicate content during retries.
 
+Also check ignored/rejected fields, warnings, mutation outcome and actual changed IDs. A matched
+node or `ok:true` receipt alone is not proof of an update. The bundled `assertReceipt` helper can
+reject partial drops; `requireChange:true` rejects an unexpected no-op. A deliberate replay may
+be unchanged and should reuse its previous evidence instead of recreating nodes.
+Keep executed payloads and returned-ID manifests separate from regenerated plans.
+
 ## Node shape and coordinates
 
 Fields are flat: `{name,type,x,y,w,h,text,size,family,fontWeight,fill,...}`.
@@ -71,6 +77,13 @@ Create normalizes hex colours; raw stored scenes use RGBA arrays in 0..1.
   moves/resizes use the catalog's frame/arrangement/scale actions; do not assume a patch
   reflows children.
 - Build backgrounds before foregrounds. Use `canvas.order` to change stacking.
+
+For create/update geometry, `coordinateSpace:"world"` or `"parent"` makes the intent explicit.
+Default behavior remains compatible with the rules above. Receipts include normalized world
+bounds and parent offsets where available. Template coordinates remain relative to their root.
+An SVG's bytes may be stored in `svgRef` once it exceeds the inline limit; this is valid artwork,
+not a missing node. Replacing `svg` clears and rebuilds its reference automatically. Never patch
+`svgRef` manually or guess its storage URL. Image `fit` is explicitly `contain` or `cover`.
 - Name nodes uniquely; use returned IDs where names collide. Parent content to its
   frame so movement, selection, clipping and reviews can treat it as one artifact.
 - Give an intended stroke both `stroke` and `strokeWidth`. Zero explicitly removes it.
@@ -106,6 +119,16 @@ and tokens when relevant. Constraints reflow children on frame resize; they do n
 a static canvas into a responsive website. Design explicit mobile artboards when the
 deliverable requires them, with content order and hierarchy reconsidered for the width.
 
+## Technique
+
+The same rules the in-app assistant works to (canvas-catalog returns them as `technique`).
+
+- AUTO-LAYOUT: rows and stacks (nav links, button groups, card rows, form fields) are a frame whose children you create in reading order, then canvas.auto-layout { id, direction, gap, padding, align, justify, hug }. hug:false keeps the frame size, which a full-width bar needs with justify:"space-between"; set a child to layoutSizingH/V "fill" | "hug" | "fixed" with canvas.update-nodes.
+- GRADIENTS: gradient { kind, angle, stops: [{ offset, color }] } replaces the solid fill. angle is the direction the colour travels: 0 = left to right, 90 = top to bottom, 45 = top-left to bottom-right (not CSS degrees). Use two or three stops from the brand palette, and keep text off a busy gradient or check its contrast in canvas.review.
+- SHADOWS AND BLUR: effects on any node. A soft card shadow is { type: "drop-shadow", x: 0, y: 4, blur: 16, spread: 0, color: "#0000001F" }; frosted glass is { type: "background-blur", blur: 16 }. Never fake a shadow with an extra rectangle.
+- SVG PLACEHOLDERS: until real imagery exists, draw it as an svg node at its final size in a muted tone from the brand palette, never a flat accent block, e.g. for a 400×240 slot svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 240"><rect width="400" height="240" rx="12" fill="#EDE6DF"/><circle cx="170" cy="96" r="14" fill="#CDBFB2"/><path d="M150 168l40-48 30 34 22-20 40 34z" fill="#CDBFB2"/></svg>' — <svg viewBox="0 0 W H"> always matches the node w and h. Put a label in its own text node and name the svg "<section> image placeholder". Hand-write only simple marks like this (placeholders, dividers, UI icons); logos, illustrations and finished artwork come from svg-make.
+- 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.
+
 Use `arrow.create {from,to,routing,label}` for connected diagrams, so arrows remain bound
 when nodes move. Use native shapes and SVG for custom vector details. Keep labels as
 native text so they remain editable and measurable.

package/skills/clearly-canvas/review.mjs

@@ -1,20 +1,69 @@
 #!/usr/bin/env node
 /** Save review pixels outside the model context. No shell interpolation, no workspace mutations. */
 import { execFileSync } from 'node:child_process';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-export function rpc(action, payload) {
+export function assertReceipt(result, { requireChange = false } = {}) {
+  if (result?.ok === false || result?.error || result?.results?.some(r => r.ok === false)) {
+    throw new Error(result.error || result.results?.find(r => !r.ok)?.error || 'Canvas request failed');
+  }
+  for (const row of result?.results ?? [result]) {
+    const value = row.value ?? row;
+    if (value.ignoredFields?.length || value.rejectedFields?.length) {
+      throw new Error(`Fields were not applied: ${[...(value.ignoredFields ?? []), ...(value.rejectedFields ?? [])].join(', ')}. Some work may have landed; inspect the saved scene before retrying.`);
+    }
+    if (requireChange) {
+      const delta = value.canvasChanges;
+      const changed = ['changed', 'partial'].includes(value.outcome) || (Array.isArray(delta) ? delta.length > 0 : delta && typeof delta === 'object'
+        ? Number(delta.added || 0) + Number(delta.changed || 0) + Number(delta.removed || 0) > 0
+        : value.placed === true || /\.create(-node)?$/.test(String(row.action || '')) && !!value.id && !value.duplicate);
+      if (!changed) throw new Error('No nodes changed, or the receipt does not prove a change. Inspect the saved scene; do not treat a match as an update.');
+    }
+  }
+  return result;
+}
+
+export function rpc(action, payload, options) {
   const stdout = execFileSync('beehaven', ['call', action, '-'], {
     input: JSON.stringify(payload), encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
     stdio: ['pipe', 'pipe', 'pipe'], timeout: 120_000,
   });
   const result = JSON.parse(stdout);
-  if (result.ok === false || result.error || result.results?.some((r) => r.ok === false)) {
-    throw new Error(result.error || result.results.find((r) => !r.ok)?.error || 'Canvas request failed');
+  return assertReceipt(result, options);
+}
+
+export function sceneNodes(result) {
+  if (!Array.isArray(result?.nodes)) throw new Error('Expected composition-detail includeScene:true to return top-level nodes. Refusing to interpret a missing field as an empty canvas.');
+  return result.nodes;
+}
+
+/** Resume creates only. Existing layers are preserved, including the person's later edits. */
+export function resumeCanvasPlan(plan, snapshot, idManifest = {}) {
+  const nodes = sceneNodes(snapshot), byId = new Map(nodes.map(n => [n.id, n]));
+  const names = new Map();
+  for (const n of nodes) { const list = names.get(n.name) ?? []; list.push(n); names.set(n.name, list); }
+  const roots = new Map(), batch = [], skipped = [];
+  for (const step of plan.batch ?? []) {
+    const args = { ...(step.args ?? {}) };
+    if (!['frame.create', 'canvas.create-node'].includes(step.action)) { skipped.push({ action: step.action, reason: 'Resume preserves existing mutations; revise explicitly.' }); continue; }
+    const type = step.action === 'frame.create' ? 'frame' : args.type;
+    const pinned = args.id || idManifest[args.name];
+    const matches = names.get(args.name) ?? [];
+    if (!pinned && matches.length > 1) throw new Error(`Ambiguous layer name ${args.name}; use its recorded ID.`);
+    const existing = pinned ? byId.get(pinned) : matches[0];
+    if (existing) {
+      if (existing.type !== type) throw new Error(`Layer ${args.name} has type ${existing.type}, expected ${type}. No automatic replacement.`);
+      roots.set(args.name, existing.id); skipped.push({ id: existing.id, name: args.name, reason: 'Already exists; preserved.' }); continue;
+    }
+    args.id = pinned || `plan-${createHash('sha256').update(`${plan.compositionId}:${args.name}`).digest('hex').slice(0, 24)}`;
+    if (args.parentId && roots.has(args.parentId)) args.parentId = roots.get(args.parentId);
+    roots.set(args.name, args.id);
+    batch.push({ ...step, args });
   }
-  return result;
+  return { compositionId: plan.compositionId, expectedCanvasNodesRev: snapshot.canvasNodesRev, batch, skipped };
 }
 
 export function saveReview(report, prefix) {
@@ -24,7 +73,21 @@ export function saveReview(report, prefix) {
   }
   const bytes = Buffer.from(preview.dataUrl.slice('data:image/png;base64,'.length), 'base64');
   if (!bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) throw new Error('Invalid PNG response');
-  const base = resolve(prefix);
+  if (bytes.length < 45 || bytes.readUInt32BE(8) !== 13 || bytes.subarray(12,16).toString() !== 'IHDR'
+    || !bytes.readUInt32BE(16) || !bytes.readUInt32BE(20)) throw new Error('Invalid PNG response: missing image header/body');
+  let offset = 8, imageData = false, end = false;
+  while (offset + 12 <= bytes.length) {
+    const length = bytes.readUInt32BE(offset), tag = bytes.subarray(offset+4,offset+8).toString();
+    if (offset + length + 12 > bytes.length) throw new Error('Invalid PNG response: truncated image chunk');
+    if (tag === 'IDAT' && length > 0) imageData = true;
+    offset += length + 12;
+    if (tag === 'IEND') { end = length === 0; break; }
+  }
+  if (!imageData || !end) throw new Error('Invalid PNG response: missing image data/end');
+  let base = resolve(prefix);
+  const original = base;
+  let version = 0;
+  while (existsSync(`${base}.png`) || existsSync(`${base}.json`)) base = `${original}-r${report.canvasNodesRev ?? 'unknown'}-${++version}`;
   mkdirSync(dirname(base), { recursive: true });
   const { dataUrl, url, ...metadata } = preview;
   const saved = { ...report, preview: { ...metadata, path: `${base}.png` } };
@@ -34,16 +97,47 @@ export function saveReview(report, prefix) {
   return { png: `${base}.png`, report: `${base}.json`,
     // `fix` = a probable defect remains: fix it, or pass its check/id in `ignore` with a reason.
     // `look` = only things worth a second look. `clean` = nothing mechanical found — NOT "good".
-    verdict: report.verdict ?? 'unknown', blocking: report.blocking,
+    verdict: report.verdict ?? 'unknown', acceptanceStatus: report.acceptanceStatus,
+    acceptedFindings: report.acceptedFindings ?? [], blocking: report.blocking,
     craft: craft.map((f) => `${f.severity} ${f.check}: ${f.detail}`),
+    audit: (report.audit?.violations ?? []).map(v => ({check:v.kind,layer:v.name || v.id,detail:v.detail || v.message || v.reason || `${v.kind} on ${v.name || v.id}`})),
+    scopeWarnings: report.scopeWarnings ?? [],
+    assets: (report.assets ?? []).filter(a => a.status !== 'ready'),
+    typography: (report.typography?.text ?? []).filter(t => t.issue || t.horizontalOverflow > 1 || !t.autoHeight && t.verticalOverflow > 1 || t.exact === false)
+      .map(t => ({layer:t.name || t.id,issue:t.issue,horizontalOverflow:t.horizontalOverflow,verticalOverflow:t.verticalOverflow,
+        requestedFont:t.font?.requestedFamily,requestedWeight:t.font?.requestedWeight,resolvedFile:t.font?.file,exact:t.exact})),
     nodes: report.scope?.nodeCount, findings: report.audit?.total, textChecked: report.typography?.checked,
     textOmitted: report.typography?.omitted, visualReviewRequired: true,
     note: report.verdict === 'fix'
-      ? 'Fix every warn (or justify it with ignore), then review again. Then open the PNG and critique it.'
+      ? 'Fix every warn (or accept an exact finding with a reason), then review changed artboards. Then open the PNG and critique it.'
       : 'Open the PNG with your image-viewing tool, critique it against the studio bar, revise and render again.' };
 }
 
-export function main(argv = process.argv.slice(2)) {
+export async function saveReviewPixels(report, prefix, fetchImage = fetch) {
+  if (report.preview?.dataUrl) return saveReview(report, prefix);
+  const url = report.preview?.url;
+  if (!url || !/^https?:\/\//.test(url)) throw new Error(report.previewError || 'No downloadable preview. Visual verification is incomplete.');
+  const response = await fetchImage(url);
+  if (!response.ok) throw new Error(`Preview download failed (HTTP ${response.status}); request a fresh review.`);
+  const bytes = Buffer.from(await response.arrayBuffer());
+  return saveReview({ ...report, preview: { ...report.preview, dataUrl: `data:image/png;base64,${bytes.toString('base64')}` } }, prefix);
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  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>');
+    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 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 = [];
+    for (let i = 0; i < reports.length; i++) saved.push(await saveReviewPixels(reports[i], resolve(directory, `${String(i + 1).padStart(2, '0')}-${String(ids[i]).replace(/[^a-z0-9_-]/gi, '-')}`)));
+    process.stdout.write(JSON.stringify(saved, null, 2) + '\n');
+    return;
+  }
   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.');
@@ -60,9 +154,9 @@ export function main(argv = process.argv.slice(2)) {
     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.');
   }
-  process.stdout.write(JSON.stringify(saveReview(report, prefix), null, 2) + '\n');
+  process.stdout.write(JSON.stringify(await saveReviewPixels(report, prefix), null, 2) + '\n');
 }
 
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  try { main(); } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }
+if (process.argv[1] && existsSync(process.argv[1]) && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  main().catch(error => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });
 }

package/skills/design-craft/SKILL.md

@@ -298,6 +298,11 @@ fewer elements, tighter type, one accent*. Every ornament added is a step away f
 
 ## Sources
 
+The full shelf — about fifty books across grid, type, print production, colour, graphic form,
+brand identity, information and interface design, each reduced to one rule — is in
+[references.md](references.md). In Research pick two or three whose lens fits the brief, and name
+the one behind each direction in its rationale.
+
 Josef Müller-Brockmann, *Grid Systems in Graphic Design* (1981) · Massimo Vignelli, *The
 Vignelli Canon* (semantics / syntactics / pragmatics; "Design is one") · Michael Bierut,
 *How to* (Pentagram; brief → rationale → trade-offs) · Paula Scher / Pentagram, The Public

package/skills/design-craft/references.md

@@ -0,0 +1,95 @@
+# The design shelf
+
+<!-- Generated from apps/cloudflare/src/agent/design-references.ts (the design-references and brand-references house skills).
+     Edit the list there, then run: WRITE_DESIGN_REFERENCES=1 npx vitest run src/__tests__/verify-design-references.test.ts -->
+
+Books a studio designer works from, each reduced to one rule you can act on. The in-app
+assistant gets the same list as the `design-references` and `brand-references` workspace skills.
+
+## How to use it
+
+- In Research, pick two or three references whose lens fits the brief: a print piece or poster → grid, type, print; an identity → brand; a chart or report → information; a screen or flow → interface. Write what each one changes in this design.
+- In Direction, name the reference behind each direction's idea in one line ("a Müller-Brockmann modular grid, type as the image after Scher").
+- In Review, critique against the same rules you chose.
+- These are paraphrased principles, not quotations. Never invent a quote or page number; cite author and title only.
+
+## Method — deciding before drawing
+
+- Massimo Vignelli, *The Vignelli Canon* (2010): Answer semantics (what it means, to whom), syntactics (its visual grammar) and pragmatics (will they get it) before placing a node; few typefaces, a grid, discipline.
+- Michael Bierut, *How to* (2015): Present brief → idea → trade-offs; the idea comes out of the problem, and the rationale is part of the deliverable.
+- Paul Rand, *Thoughts on Design* (1947): Form and content are one: simplify until the idea is legible, and allow wit — play is a way of making it memorable.
+- Bruno Munari, *Design as Art* (1966): Solve the problem with the simplest means; decoration that solves nothing is noise.
+- Karl Gerstner, *Designing Programmes* (1964): Design the rules, not one layout: define the variables (size, position, colour) and generate the set from them.
+- Dieter Rams, *Less but Better* (1995): As little design as possible: every element must earn its place by use; remove what does not.
+- Alan Fletcher, *The Art of Looking Sideways* (2001): Look for the idea sideways — a visual pun or found connection beats a literal illustration of the brief.
+
+## Grid and layout
+
+- Josef Müller-Brockmann, *Grid Systems in Graphic Design* (1981): Construct margins, columns, gutter and baseline first; every element lands on the grid; break it once, on purpose.
+- Timothy Samara, *Making and Breaking the Grid* (2002): Pick the grid for the content (manuscript, column, modular, hierarchical); a deliberate break needs a grid to break.
+- Kimberly Elam, *Geometry of Design* (2001): Place the focal point on a proportional line (golden section, root rectangles, thirds), not at dead centre.
+- Beth Tondreau, *Layout Essentials* (2009): Grids by job: a single column for reading, multi-column for mixed content, modular for catalogues and dashboards.
+
+## Typography
+
+- Robert Bringhurst, *The Elements of Typographic Style* (1992): Measure 45–75 characters, leading to suit the measure, honour the content: type exists to be read.
+- Ellen Lupton, *Thinking with Type* (2004): Build hierarchy by changing one variable at a time — size, weight, colour or space — and track capitals open.
+- Jan Tschichold, *The New Typography* (1928): Asymmetric, functional layout: hierarchy by size, weight and position, never ornament.
+- Emil Ruder, *Typographie* (1967): White space is active form: the counter, the gap and the margin are composed like the type itself.
+- Jost Hochuli, *Detail in Typography* (1987): Letter, word and line spacing decide readability: tighten display type, keep word spaces even, open the leading for long lines.
+- Erik Spiekermann and E. M. Ginger, *Stop Stealing Sheep & Find Out How Type Works* (1993): A typeface is a voice: choose it for the message and audience, then set it with care before anything else.
+- Ellen Lupton, *Type on Screen* (2014): On screen, type is motion and interaction too: sizes, scales and states are a system, not one setting.
+
+## Print and editorial production
+
+- Jan Tschichold, *The Form of the Book*: Classical page proportions: inner margin smallest, foot margin largest; the text block sits high and toward the spine.
+- Richard Hendel, *On Book Design* (1998): A book design serves the reading; decide trim, margins, type and running heads together, and stay invisible.
+- Andrew Haslam, *Book Design* (2006): Plan the whole object — format, grid, pagination, binding — before designing a spread.
+- Jan V. White, *Editing by Design* (1974): Editorial layout starts from what the story says; headline, picture and caption are one unit.
+- International Paper, *Pocket Pal*: Production rules: CMYK for press, 300 dpi images at final size, 3 mm (0.125 in) bleed, a safe area inside the trim.
+- Alan Pipes, *Production for Graphic Designers*: Specify for the press: paper stock, ink coverage, rich black for large areas only, overprint and trap small type.
+
+## Colour
+
+- Josef Albers, *Interaction of Color* (1963): Colour is relative: judge it beside its neighbours on the real ground, never as a swatch alone.
+- Johannes Itten, *The Art of Color* (1961): Choose the one contrast that leads (light–dark, warm–cool, complementary, saturation, extent) and let the rest support it.
+
+## Graphic form and visual perception
+
+- Armin Hofmann, *Graphic Design Manual* (1965): Build with elementary contrasts — point, line, plane, black and white, large and small — before colour.
+- Ellen Lupton and Jennifer Cole Phillips, *Graphic Design: The New Basics* (2008): Point, line, plane, rhythm, scale, texture, figure/ground and framing are variables; change one deliberately.
+- Wucius Wong, *Principles of Two-Dimensional Design* (1972): Repetition, gradation and radiation give a field structure; an anomaly in that structure is the focal point.
+- Rudolf Arnheim, *Art and Visual Perception* (1954): Visual weight balances on the frame's hidden axes; size, value, isolation and position all add weight.
+- Robin Williams, *The Non-Designer's Design Book* (1994): Contrast, repetition, alignment, proximity: if two things differ, make them clearly different.
+- Alex W. White, *The Elements of Graphic Design* (2002): Treat space as an element: emptiness gives the content its shape and its importance.
+- Kenya Hara, *Designing Design* (2007): Emptiness invites the viewer in: leave room for the reader's imagination instead of filling the frame.
+- Paula Scher, *Make It Bigger* (2002): Type can be the image: scale and crop a word until it carries the identity on its own.
+- Philip B. Meggs, *A History of Graphic Design* (1983): Know the lineage of a style so a reference is chosen, not a pastiche of the first thing found.
+- Adrian Frutiger, *Signs and Symbols*: A sign reads by its simplest form; test a mark small, at a distance and in one colour.
+
+## Brand and identity
+
+- Alina Wheeler, *Designing Brand Identity* (2003): Identity is a process — research, strategy, design, touchpoints, asset management; design the touchpoints, not just the logo.
+- Marty Neumeier, *The Brand Gap* (2003): A brand is the customer's gut feeling; close the gap between strategy and the look by testing what people actually perceive.
+- Marty Neumeier, *Zag* (2006): When everyone zigs, zag: state what makes this the only one, then design to that difference.
+- Wally Olins, *On Brand* (2003): A brand shows in product, environment, communication and behaviour; keep all four saying the same thing.
+- Byron Sharp, *How Brands Grow* (2010): Growth comes from being easy to notice and buy: protect distinctive assets and stay consistent.
+- Jenni Romaniuk, *Building Distinctive Brand Assets* (2018): An asset (colour, shape, character) works once it is famous and unique to the brand; use it everywhere, change it rarely.
+- Tom Geismar, Ivan Chermayeff and Sagi Haviv, *Identify* (2011): A mark must be appropriate, distinctive and simple; it earns meaning through use over time.
+- David Airey, *Logo Design Love* (2009): Test a logo at 16 px, in one colour and in reverse; if it needs detail or colour to survive, simplify it.
+- Danne & Blackburn, *NASA Graphics Standards Manual* (1975): A standards manual fixes the mark, clear space, colours, type, grid and applications so anyone can apply the system.
+- Unimark International (Vignelli, Noorda), *New York City Transit Authority Graphics Standards Manual* (1970): A system scales by rules: one typeface, fixed modules, colour coding and consistent placement.
+
+## Information design
+
+- Edward R. Tufte, *The Visual Display of Quantitative Information* (1983): Maximise data-ink: remove chart junk, label directly, show the comparison; use small multiples for change.
+- Edward R. Tufte, *Envisioning Information* (1990): Layer and separate: quiet the grid and background so the data reads first.
+- Otto Neurath, *International Picture Language* (1936): Isotype: count with repeated identical pictograms, never by enlarging one.
+
+## Interface and product design
+
+- Don Norman, *The Design of Everyday Things* (1988): Make the action visible: signifiers, feedback, mapping and constraints; a control must say how it is used.
+- Steve Krug, *Don't Make Me Think* (2000): People scan, they do not read: obvious hierarchy, conventions, one clear next action per page.
+- Adam Wathan and Steve Schoger, *Refactoring UI* (2018): Hierarchy by weight and colour before size, de-emphasise secondary text, use a spacing and shadow scale.
+- Jenifer Tidwell, *Designing Interfaces* (2005): Use the known pattern for the job (navigation, forms, lists, dashboards) before inventing one.
+- William Lidwell, Kritina Holden and Jill Butler, *Universal Principles of Design* (2003): Check the design against named principles (Fitts, Hick, proximity, progressive disclosure) and say which one a choice serves.

package/skills/index.json

@@ -4,7 +4,7 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "2d33d2ecfb166fa6"
+    "sha": "6233057bd1a44b51"
   },
   {
     "name": "clearly-canvas",
@@ -17,7 +17,7 @@
       "project-plans.md",
       "review.mjs"
     ],
-    "sha": "8b1890ca7588af6c"
+    "sha": "7d79406b37f611a8"
   },
   {
     "name": "agent-home",
@@ -36,9 +36,10 @@
   {
     "name": "design-craft",
     "files": [
-      "SKILL.md"
+      "SKILL.md",
+      "references.md"
     ],
-    "sha": "260c3a6967b08a8b"
+    "sha": "bf2f4fac6f57ea46"
   },
   {
     "name": "layout-systems",
@@ -52,7 +53,7 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "50587f531bfab1c6"
+    "sha": "cd891499599ccb7b"
   },
   {
     "name": "pair-on-canvas",
@@ -81,6 +82,6 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "c16e1b5d08dbd669"
+    "sha": "b3f47988cb9235b9"
   }
 ]