@clearlysh/beehaven 0.8.27 → 0.8.30

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,
@@ -103,10 +110,46 @@ can read and edit artifact records, while canvas-specific actions use the CLI.
 beehaven env
 beehaven connect home
 beehaven agent login <name> --label "Design <artifact>" --client cli
-beehaven call canvas-perceive '{"compositionId":"<id>","format":"json"}'
+beehaven call canvas-perceive '{"compositionId":"<id>","outline":true}'
 beehaven call canvas-catalog '{"query":"create-node"}'
 ```
 
+Read a canvas the way you read a repository: `canvas-perceive {outline:true}` is `tree` (artboards,
+sections, layer counts, first copy, EMPTY sections — a few hundred bytes); `{frame:"<id or name>"}`
+opens one frame like a file (its layers indented, positions relative to their parent);
+`{find:"Start free"}` is `grep` (copy, layer names or `#hex`, with each match's frame path). Use
+`format:"json"` only when you need every field of every node. Every `canvas-act` write returns
+`diagnostics` — a lint of the artboards it touched (text overflow, collisions, covered text,
+contrast) — treat them like compiler errors and fix them in the next batch. `canvas.review` is still
+the pixel check and the ticket gate.
+
+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, 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
+`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.
@@ -161,8 +204,11 @@ hand-author hundreds of coordinates in a chat message.
   Check contrast on the actual ground. Use the user's real brand assets.
 - Choose relevant imagery, a meaningful diagram, a product view or a deliberate
   typographic treatment. Decorative blobs and random stock photos do not prove a
-  product claim. Native SVG/paths suit diagrams and vector art; raster generation
-  suits imagery when an image tool is available.
+  product claim. Draw marks, icons, illustrations and diagrams yourself from native
+  layers (shapes, vector.create pen paths, text, groups), the way a designer works in
+  Figma, so every part stays named and editable. Raster generation suits photographic
+  imagery when an image tool is available. Raw SVG (an svg node, or a generated SVG)
+  is for importing an existing file or a requested SVG, never the default.
 - Define repeated components once. Vary composition where the content changes.
   A deck of identical cards has little rhythm even when every card aligns.
 - Keep important copy and layers editable. Do not flatten the whole composition
@@ -188,6 +234,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 +275,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 +288,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,8 +119,19 @@ 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. The frame stays live: create more children into it (parentId) and they flow in; layoutPositioning:"absolute" takes one out of the flow.
+- 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.
+- DRAWING: build every mark, icon, illustration and diagram shape from native layers, as a designer does in Figma, never as one generated SVG file. Primitives are canvas.create-node rect and ellipse; curves are pen paths, vector.create { name, parentId, points: [{ x, y, hIn?: { x, y }, hOut?: { x, y } }], closed, fill or stroke, strokeWidth }, where hIn/hOut are absolute control points: use few anchors with smooth handles, and refine with vector.read, vector.vertex.move and vector.handle.set. Round caps and joins: canvas.update-nodes patch { strokeCap: "round", strokeJoin: "round" }. Work back to front: ground, big silhouettes in flat brand colours, then features, then details and highlights; check the silhouette in canvas.review before detailing. Name layers by part ("fox/ear-left"), group each figure with canvas.group { ids, name } and set overlap with canvas.order { ids, op }. Make a cut-out by layering a ground-colour shape on top; vector.boolean { op } on selected paths needs an open editor. Keep one stroke weight per drawing. Photographic or painterly imagery is a placed raster. Raw SVG stays supported but is never the default: when an SVG is asked for, write the markup yourself as an svg node, canvas.create-node { type: "svg", name, w, h, svg } with <svg viewBox="0 0 W H"> matching w and h, or import existing markup the same way; never an SVG generation pipeline.
+- 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.
+
 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
+when nodes move. Draw custom vector details natively (shapes, vector.create pen paths); raw SVG only imports an existing file. Keep labels as
 native text so they remain editable and measurable.
 
 Use `canvas.place {kind,id,x,y,w,h,name,parentId?}` to put a workspace object (document,

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": "b942eebe6f0397fb"
   },
   {
     "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": "755db2d1ab8c759f"
   },
   {
     "name": "pair-on-canvas",
@@ -81,6 +82,6 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "c16e1b5d08dbd669"
+    "sha": "b3f47988cb9235b9"
   }
 ]