beehaven 0.8.16

package/skills/clearly-canvas/authoring.md

@@ -0,0 +1,160 @@
+# Authoring contracts
+
+Use `beehaven call canvas-catalog '{"query":"<action>"}'` for current arguments and
+`headlessActions`. The CLI calls the deployed worker; changing local source does
+not add a capability to that worker.
+
+## Generate payloads, then submit
+
+Use a local builder and pass JSON through `@file` or stdin. Do not interpolate copy,
+SVG or code into shell strings. Here is a minimal native-node pattern; replace its
+visual decisions with the brief's system:
+
+For a complete editable three-artboard example, inspect [example.mjs](example.mjs).
+It demonstrates tokens, reusable helpers and varied compositions; it writes a payload
+without making remote calls. Run `node <skill-directory>/example.mjs <composition-id>`.
+Use its construction approach, not its fictional brand or aesthetic, for other briefs.
+
+```js
+import { writeFileSync } from 'node:fs';
+const compositionId = process.argv[2];
+const grid = { w: 1440, h: 900, margin: 88, gap: 24 };
+const color = { paper: '#F3F0E8', ink: '#172824', accent: '#CB482F' };
+const type = {
+  display: { family: 'Inter', size: 88, fontWeight: 700, lineHeight: 1.05, letterSpacing: -2 },
+  body: { family: 'Inter', size: 24, fontWeight: 400, lineHeight: 1.4 },
+};
+const batch = [];
+const add = (action, args) => batch.push({ action, args });
+add('frame.create', { name: '01-opening', x: 0, y: 0, w: grid.w, h: grid.h, fill: color.paper });
+const text = (name, copy, x, y, w, role) => add('canvas.create-node', {
+  name, type: 'text', parentId: '01-opening', x, y, w,
+  text: copy, fill: color.ink, ...type[role],
+});
+text('opening-title', 'Ideas take\nshape here.', grid.margin, 120, 740, 'display');
+text('opening-deck', 'An editable visual system for the next chapter.', grid.margin, 360, 580, 'body');
+// Continue with the brief's central visual, supporting evidence and footer.
+writeFileSync('/tmp/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
+```
+
+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
+different rollback behavior. Use deterministic layer names and returned IDs to avoid
+duplicate content during retries.
+
+## Node shape and coordinates
+
+Fields are flat: `{name,type,x,y,w,h,text,size,family,fontWeight,fill,...}`.
+Use `text` for copy, `size` for type size, numeric `fontWeight`, and `w`/`h` for bounds.
+Create normalizes hex colours; raw stored scenes use RGBA arrays in 0..1.
+
+- `frame.create` and `canvas.create-node` with `parentId` take coordinates **relative
+  to that parent**. Create the frame first. Names can resolve earlier nodes in a batch.
+- Persisted nodes and perception bounds use **world coordinates**. Raw scene replacement
+  through `composition-patch`/MCP must use world coordinates, even with `parentId`.
+- `canvas.update-nodes` geometry is world geometry. For group 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.
+- 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.
+
+## Typography
+
+For prose, set `w` and omit `h` to enable auto-height. Omit both axes only for short
+single-line labels whose width should hug content. A fixed box sets that axis explicitly;
+it does not guarantee text will clip safely. Headless auto-height is an estimate from
+stored text and font metrics, not browser layout. Reserve enough room for measured lines,
+then inspect the rendered result in the editor.
+
+```json
+{"compositionId":"<id>","action":"canvas.measure-text","args":{
+  "text":"Ideas take shape here.","family":"Inter","size":88,"fontWeight":700,
+  "letterSpacing":-2,"lineHeight":1.05,"maxWidth":740}}
+```
+
+Use measured `height`/`lineCount` to place the next block. Measure the exact copy, font,
+weight, tracking and width you will render. Inspect final line breaks visually. Changing
+the headline width or copy is often better than shrinking every role to fit.
+
+`font` reports the requested family/weight and resolved file. `exact:false` means a
+fallback or an estimate; it is not a proof of browser fit. Bundled faces include Inter
+400/700, JetBrains Mono 400, Geist Mono 400, Montserrat 500 and Google Sans Flex's default
+face. Other weights/families need live verification. Custom font appearance can differ
+from the headless preview. The renderer's supported fonts are not a design-style mandate.
+
+## Layout, reuse and graphics
+
+Discover `canvas.arrange`, frame auto-layout, constraints, `canvas.scale`, components
+and tokens when relevant. Constraints reflow children on frame resize; they do not turn
+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.
+
+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.
+
+Use `canvas.place {kind,id,x,y,w,h,name,parentId?}` to put a workspace object (document,
+deck, sheet, board, ticket, project, site or file) on the canvas as a live card. With
+`parentId`, `x/y` are relative to that frame, like `canvas.create-node`. See
+[project-plans.md](project-plans.md).
+Use `canvas.list-sources`/`canvas.place-source` for library assets. A native image
+node accepts `src`. Upload local media using `canvas-upload-image` (discover its current
+schema), then place its returned URL. Inspect the actual asset before using it. Prefer
+provided, reusable or purpose-made imagery to random URL placeholders. Label temporary
+assets in the handoff and replace them when final assets are part of the request.
+
+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.
+Do not treat a stored `src` as proof that the intended crop rendered.
+
+For an interactive HTML prototype, use `canvas-add-artifact` with self-contained HTML.
+Choose it when interactions are the deliverable; use native nodes for editable visual
+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
+```
+
+Use the bundled `review.mjs` to decode the PNG and keep base64 out of the conversation.
+It does not edit the composition. Read `previewError`, audit findings, font fallbacks and
+`typography.omitted`; missing checks are not passes. Review each artboard individually.
+For a long page, also request `canvas-perceive` with a `region:{x,y,w,h}` detail crop.
+The preview has a pixel-size cap; increasing `pixelScale` cannot bypass it.
+
+`fitNodeIds`/`region` plus pixels uses an agent-owned persisted view (`live:false` is
+expected). Bare perception can return the user's live view. Use `format:"json"` for a
+full inventory: text format limits the list, and text previews are truncated. Perception
+is not a lossless scene serializer. Use `composition-detail {id,includeScene:true}` when
+you need the full scene and its revision.
+
+## Whole-scene writes and MCP
+
+CLI and MCP can both create or replace a whole scene. For a scripted large build,
+`composition-patch {id,expectedCanvasNodesRev,patch:{canvasNodes:[...]}}` is available.
+Read the authoritative scene first, preserve unrelated nodes and fields, and pass its
+revision. On a conflict, re-read and merge your intended changes. Never rebuild a scene
+from the abbreviated perceive report or remove a revision check just to force a write.
+
+MCP's artifact tools are split by operation:
+
+- `clearly_catalog {type:"composition"}` exposes the current schemas.
+- `clearly_read` returns nodes and `canvasNodesRev`.
+- `clearly_write` creates a composition or replaces its full node array; use
+  `expectedRev` from the read for replacement.
+- `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.

package/skills/clearly-canvas/communications.md

@@ -0,0 +1,32 @@
+# Canvas updates and handoff
+
+Use communication blocks when the canvas is the user's working surface. Keep them
+outside the final artboards and reuse a status block instead of adding one per tool call.
+
+```sh
+beehaven call canvas-add-claude-comm '{"compositionId":"<id>","kind":"status","title":"Designing the campaign","active":true,"statusLines":["Establishing the visual direction"]}'
+```
+
+Capture `blockId`, then pass it on subsequent updates. Close with `active:false`.
+Use `kind:"build-result"` for a code build (with the actual URL or install command),
+`kind:"result"` for design work, and `kind:"narration"` for a concise explanation.
+Discover optional fields through `canvas:actions`.
+
+`canvas.add-diff {diff,title,frame:true}` makes a spatial code review from a real diff.
+Pass it through a JSON file. Keep code review separate from delivered artwork.
+
+`canvas-add-brand-snapshot` displays a brand reference. It does not change that brand.
+Use real brand assets; do not redraw a company's logo from memory. A request to design
+an artifact does not inherently authorize changing shared brand settings.
+
+Use normal chat for a question or approval when one is actually required. Do not invent
+`canvas-add-claude-template` or `brand-propose-update` actions.
+
+```sh
+beehaven call agent-nav-open '{"kind":"composition","id":"<id>"}'
+```
+
+This records your location and can navigate connected clients. `delivered:0` means no
+client received navigation; it does not invalidate the stored composition. Give the
+user the title and composition link on the intended environment. Do not claim a browser
+opened merely because a message was delivered.

package/skills/clearly-canvas/composition-patterns.md

@@ -0,0 +1,84 @@
+# Composition choices by deliverable
+
+Numbers below are useful starting ranges in canvas pixels, not fixed standards. Scale
+them for the actual viewing distance, content and brand. Never impose a universal
+“premium” style on every brief.
+
+## Choose structure by the content
+
+| Content asks for | A structure worth trying | What makes it specific |
+|---|---|---|
+| One strong claim | Large statement and one piece of evidence | Size contrast and the evidence's visual form |
+| A product or object | Deliberately cropped focal image with quiet annotations | Crop, lighting, material and scale |
+| Before/after or alternatives | Matched comparison fields, possibly 50/50 | Shared scale, baseline and meaningful differences |
+| A story over time | Sequence, timeline or repeated visual motif | Change across panels, controlled rhythm |
+| Many related facts | Editorial grid or carefully structured table | Grouping, direct labels, alignment and legibility |
+| A process/system | Spatial diagram with meaningful relationships | Direction, proximity, grouping and labeled connectors |
+
+Sketch visual mass before detail. Locate the primary read, supporting read and quiet
+space. Use asymmetry for tension when it helps, and symmetry for comparison or calm.
+Empty space should reinforce grouping and emphasis; excessive empty space can weaken
+information just as crowding can.
+
+## Poster, cover or campaign
+
+For 1080×1350, try 64–96 margins, 96–180 display, 24–36 supporting type, 18–22 detail.
+View a 150–250px-wide thumbnail to judge the primary read, then inspect the full image.
+The idea might be typographic, photographic, illustrative or mixed. Make the central
+visual recognisable and relevant. A repeated abstract ornament is not automatically
+a brand asset.
+
+A campaign shares a typographic voice, colour logic, grid and image treatment. Vary
+the focal scale or arrangement to suit each message. Design other aspect ratios as
+adaptations, moving hierarchy and crop; do not stretch or blindly crop the first board.
+Check the target platform's current overlays/safe zones when final publication matters.
+
+## Presentation
+
+For 1920×1080, try 96–120 margins, 64–96 headlines, 28–36 main text and 20–24 labels.
+Write the argument as the title. Choose evidence the audience can grasp at presentation
+distance. Move supporting detail into notes or a document when it obscures the argument.
+
+Plan the whole sequence: opening promise, evidence, explanation and conclusion. Vary
+the visual function: opening image, decisive statistic, diagram, comparison, detail,
+closing. Keep title baselines, folios and text roles consistent. Do not force an equal
+number of cards onto every slide. Review a contact sheet for rhythm and each slide for fit.
+
+## Page or app mockup
+
+For 1440 desktop, try 80–112 outer margins, 64–88 hero headline and 18–24 supporting
+text. For 390 mobile, try 20–24 margins, 36–48 headline and 16–18 body, then measure.
+These values are starting points, not a substitute for testing actual copy.
+
+Design a complete reading path: navigation, proposition, evidence, next action and
+relevant follow-up content. Use an actual product visual where the page claims product
+value. Distinguish interface controls from decorative editorial elements. Include useful
+empty/error/loading states when they belong to the requested UI.
+
+Mobile needs its own content order, wrapping, crop and touch affordances. A static
+desktop artboard scaled down is not a mobile design. If delivering implementation,
+verify keyboard access and responsive behavior in the real browser as well.
+
+## Editorial and information design
+
+Begin with reading order and density. Align related labels and values, give numbers
+a consistent unit/precision, and use direct chart annotations. Let the amount of content
+determine the number of columns. Body measure often works around 45–75 characters;
+captions and labels can be shorter. Check actual line breaks rather than calculating
+character count alone.
+
+Use rules and backgrounds where they clarify grouping. Remove boxes that merely frame
+every paragraph. A chart, map or diagram should carry information, with honest scales
+and visible sources when supplied. Never invent evidence to make a layout look complete.
+
+## A useful critique names the fix
+
+Weak: “Make it more polished.”
+
+Useful: “At thumbnail size the orange badge wins before the title. Reduce its area and
+move it beside the caption. The product image needs a larger crop to explain the claim.
+The second paragraph wraps into the footer; shorten its measure only after reserving
+more vertical space, or edit the copy.”
+
+Judge the artifact against its audience and brief. A quiet museum catalogue, dense
+operations dashboard and vivid music poster should not converge on the same aesthetic.

package/skills/clearly-canvas/example.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/** Example of a reusable native-node builder. Writes JSON only; it never calls a workspace. */
+import { writeFileSync } from 'node:fs';
+
+const [compositionId, output = '/tmp/fieldwork-build.json'] = process.argv.slice(2);
+if (!compositionId) throw new Error('Usage: node example.mjs <composition-id> [output.json]');
+const grid = { w: 1440, h: 900, margin: 88, gutter: 80 };
+const ink = '#172824', paper = '#F2F0E7', orange = '#C84A2E', muted = '#58685E';
+const batch = [];
+const op = (action, args) => batch.push({ action, args });
+const frame = (name, index, fill) => op('frame.create', {
+  id: name, name, x: index * (grid.w + grid.gutter), y: 0, w: grid.w, h: grid.h, fill,
+});
+const node = (parentId, name, type, x, y, w, h, props) => op('canvas.create-node', {
+  id: `${parentId}-${name}`, name: `${parentId}-${name}`, parentId, type, x, y, w, h, ...props,
+});
+const text = (p, name, copy, x, y, w, size = 24, fill = ink, weight = 400, extra = {}) =>
+  node(p, name, 'text', x, y, w, undefined, { text: copy, size, family: 'Inter', fontWeight: weight,
+    lineHeight: 1.12, fill, ...extra });
+const rect = (p, name, x, y, w, h, fill, extra = {}) => node(p, name, 'rect', x, y, w, h, { fill, ...extra });
+const circle = (p, name, x, y, d, fill, extra = {}) => node(p, name, 'ellipse', x, y, d, d, { fill, ...extra });
+const rule = (p, y, color) => rect(p, `rule-${y}`, grid.margin, y, grid.w - grid.margin * 2, 1, color);
+const masthead = (p, index, color) => {
+  text(p, 'brand', 'FIELDWORK', grid.margin, 52, 400, 20, color, 700, { letterSpacing: 2 });
+  text(p, 'series', 'DESIGN NOTES     /     VOL. 01', 912, 54, 440, 14, color, 400, { letterSpacing: 1 });
+  text(p, 'folio', 'STUDIO PRACTICE', grid.margin, 828, 900, 14, color, 400, { letterSpacing: 1 });
+  text(p, 'page', String(index).padStart(2, '0'), 1304, 828, 48, 14, color, 400, { align: 'right' });
+};
+
+// Brief: show how one simple visual idea becomes a coherent editorial system.
+// Hierarchy: statement → geometric proof → compact practical explanation.
+// Motif: two fields meet to make a third; repeated with a different function on each slide.
+const cover = 'fieldwork-01';
+frame(cover, 0, paper); masthead(cover, 1, ink); rule(cover, 104, ink);
+text(cover, 'eyebrow', 'A NOTE ON MAKING', 88, 168, 560, 16, orange, 700, { letterSpacing: 2 });
+text(cover, 'title', 'Make room\nfor the idea.', 80, 228, 810, 108, ink, 700, { letterSpacing: -4, lineHeight: 1.02 });
+text(cover, 'intro', 'Good design begins with a point of view.\nThe system gives it room to grow.', 88, 538, 740, 25, muted);
+circle(cover, 'disc', 977, 233, 350, orange);
+rect(cover, 'field', 916, 385, 270, 270, ink);
+rect(cover, 'intersection', 977, 385, 209, 198, paper, { radius: 0 });
+text(cover, 'motif-caption', '01 / TWO FIELDS, ONE IDEA', 920, 696, 420, 14, muted, 400, { letterSpacing: 1 });
+rule(cover, 782, ink);
+
+const method = 'fieldwork-02';
+frame(method, 1, ink); masthead(method, 2, paper); rule(method, 104, '#607369');
+text(method, 'title', 'One idea.\nMany expressions.', 80, 164, 1120, 92, paper, 700, { letterSpacing: -3, lineHeight: 1.04 });
+text(method, 'intro', 'Keep the visual logic.\nChange what the content needs.', 952, 380, 400, 24, '#C7CFC4');
+const concepts = [
+  { x: 88, title: '01 / EMPHASIS', body: 'Let one thing lead.', kind: 0 },
+  { x: 520, title: '02 / RELATIONSHIP', body: 'Make the connection visible.', kind: 1 },
+  { x: 952, title: '03 / RHYTHM', body: 'Repeat with a reason.', kind: 2 },
+];
+for (const c of concepts) {
+  const y = 518;
+  if (c.kind === 0) { circle(method, 'emphasis', c.x, y, 152, orange); circle(method, 'quiet', c.x + 192, y + 92, 60, paper); }
+  if (c.kind === 1) { rect(method, 'relation-field', c.x, y + 20, 148, 120, paper); circle(method, 'relation-disc', c.x + 80, y, 152, orange); }
+  if (c.kind === 2) for (let i = 0; i < 4; i++) rect(method, `rhythm-${i}`, c.x + i * 78, y + i * 20, 48, 152 - i * 20, i === 3 ? orange : paper);
+  text(method, `label-${c.kind}`, c.title, c.x, 714, 380, 16, paper, 700, { letterSpacing: 1 });
+  text(method, `body-${c.kind}`, c.body, c.x, 748, 380, 20, '#C7CFC4');
+}
+
+const detail = 'fieldwork-03';
+frame(detail, 2, orange); masthead(detail, 3, paper); rule(detail, 104, paper);
+text(detail, 'title', 'The work is\nin the details.', 80, 168, 1100, 106, paper, 700, { letterSpacing: -4, lineHeight: 1.03 });
+text(detail, 'intro', 'A composition is finished when the details\nserve the idea — at every scale.', 88, 436, 850, 28, paper);
+rule(detail, 566, paper);
+const details = [
+  ['TYPE', 'Measure the words.\nGive them a voice.'],
+  ['SPACE', 'Group what belongs.\nLet the rest breathe.'],
+  ['REVIEW', 'Look at the result.\nMake the next decision.'],
+];
+details.forEach(([label, body], i) => {
+  const x = grid.margin + i * 432;
+  text(detail, `label-${i}`, label, x, 610, 380, 16, paper, 700, { letterSpacing: 2 });
+  text(detail, `body-${i}`, body, x, 662, 390, 28, paper);
+});
+writeFileSync(output, JSON.stringify({ compositionId, batch }, null, 2) + '\n');
+process.stdout.write(`${output}: ${batch.length} operations\n`);

package/skills/clearly-canvas/project-plans.md

@@ -0,0 +1,156 @@
+# Project plans on a canvas — the real work, laid out
+
+Use this when asked to plan, kick off, roadmap or organise work on a canvas: "make a
+project plan", "lay out the launch", "put the roadmap on a board". The deliverable is
+a composition where every card is a **live workspace object** — the project, its board
+and tickets, the PRD, the checklist sheet, the review deck, the site — arranged so a
+person understands the plan at a glance and can open any piece of it.
+
+Do not draw a board out of rectangles or paste a document's text into a text node.
+`canvas.place` stores `{refKind, refId}`, so the card *is* the row: edit the ticket
+anywhere and the card updates; open the card and you are in the real editor.
+
+## 1. Anchor the plan in a project
+
+```sh
+beehaven call project-list '{"limit":50}'                 # reuse the project that owns the work
+beehaven call project-create '{"title":"Launch — Q4","description":"…"}'
+beehaven call board-list '{"projectId":"<project>"}'      # a project usually has a default board
+```
+
+File everything you create into that project (`projectId`). Unfiled agent work is
+private to you; filing is how the team sees it.
+
+## 2. Create the objects — each with its own verb
+
+| Primitive | Create | Exact-shape traps |
+|---|---|---|
+| Document (PRD, brief) | `document-create {title, markdown, projectId}` | `markdown` or `html`, **never** `content` (dropped silently → an empty, unsearchable doc). `ticketId` + `artifactKind:"prd"` files it on a ticket. |
+| Sheet (checklist, budget) | `sheet-create {title, columns:[…], rows:[[…]], projectId}` | `rows` are arrays of cells; `columns` is the header row. |
+| Slides (review deck) | `deck-create {title, projectId, slides:[{title, bullets:[…]}]}` | Build the whole deck in one call; `layout:"title"` for an opener. |
+| Board | `board-create {projectId, title, columns?}` | Needs `projectId` (or `personal:true`). Cards on a board **are tickets**. |
+| Ticket | `ticket-create {projectId, boardId, title, body, issueType, status}` | `issueType`, not `type`; `body`, not `description` — both fail silently. |
+| Site (one page) | `compose-upload-init` → `file-teleport-inline` (`composition:true`, key `compositions/<id>/build/index.html`) → `compose-upload-finalize` | All three steps, or the site is empty. For a page that only lives on this canvas, `canvas.add-artifact {html}` is simpler. |
+
+Keep every returned `id`. Tickets are placed by **row id**, not by key.
+
+## 3. Lay it out with a builder, then place everything in one batch
+
+```sh
+beehaven call composition-create '{"title":"Launch — Q4 plan","projectId":"<project>"}'
+```
+
+Think in reading order. A header states the goal. Then two lanes: *why and what* (the
+project, PRD, tickets, board) and *how and ship* (the checklist sheet, review deck, site).
+Connect only cards that depend on each other. A plan is a composition like any other, so
+it meets the studio bar in SKILL.md: one grid, a few type roles, one left edge, and a
+`canvas.review` verdict before you hand it over.
+
+Build it **inside one frame** named `plan`. That frame is what `canvas.review` inspects,
+what a person moves as one piece, and what gives the page its margin.
+
+```js
+// plan.mjs — node plan.mjs <compositionId> > /tmp/plan.json
+const [compositionId] = process.argv.slice(2);
+const ids = { project: '…', prd: '…', board: '…', tickets: ['…', '…'], sheet: '…', deck: '…', site: '…' };
+// The system: margin, gutter (room for an arrow label), three type roles, two inks, one ground.
+const M = 96, G = 80;
+const type = { title: { size: 72, fontWeight: 700, letterSpacing: -1.5 }, lead: { size: 24 }, label: { size: 16, fontWeight: 600 } };   // a plan is read zoomed out: labels ≥ 1% of the board
+const ink = { strong: '#16150f', muted: '#6b6760' };            // both ≥ 4.5:1 on the ground below
+const size = { card: [340, 440], wide: [720, 440], ticket: [340, 210], deck: [560, 315], site: [420, 440] };
+const row1 = [size.card, size.card, size.card, size.wide].reduce((w, [cw]) => w + cw + G, -G);
+const W = M * 2 + row1, LANE1 = 300, CARDS1 = LANE1 + 36, LANE2 = CARDS1 + 440 + G, CARDS2 = LANE2 + 36;
+const H = CARDS2 + 440 + M;
+
+const batch = [];
+const add = (action, args) => batch.push({ action, args });
+// Coordinates below are RELATIVE to the plan frame (parentId), for text and cards alike.
+const text = (name, copy, x, y, w, role, fill = ink.strong) => add('canvas.create-node', { name, type: 'text', parentId: 'plan', x, y, w, text: copy, fill, ...type[role] });
+const place = (kind, id, name, x, y, [w, h]) => add('canvas.place', { kind, id, name, parentId: 'plan', x, y, w, h });
+
+add('frame.create', { name: 'plan', x: 0, y: 0, w: W, h: H, fill: '#f6f5f1' });
+text('plan-title', 'Launch — Q4', M, M, 1400, 'title');
+text('plan-goal', 'Ship the new onboarding to every workspace by Nov 30', M, M + 104, 1400, 'lead', ink.muted);
+
+text('lane-1', 'Why and what', M, LANE1, 400, 'label', ink.muted);
+let x = M;
+place('project', ids.project, 'project', x, CARDS1, size.card); x += 340 + G;
+place('document', ids.prd, 'prd', x, CARDS1, size.card); x += 340 + G;
+place('ticket', ids.tickets[0], 'ticket-1', x, CARDS1, size.ticket);
+place('ticket', ids.tickets[1], 'ticket-2', x, CARDS1 + 230, size.ticket); x += 340 + G;
+place('board', ids.board, 'board', x, CARDS1, size.wide);
+
+text('lane-2', 'How and ship', M, LANE2, 400, 'label', ink.muted);
+x = M;
+place('sheet', ids.sheet, 'checklist', x, CARDS2, size.wide); x += 720 + G;
+place('deck', ids.deck, 'review-deck', x, CARDS2, size.deck); x += 560 + G;
+place('site', ids.site, 'status-site', x, CARDS2, size.site);
+
+// Connect NEIGHBOURS. An arrow is drawn straight through anything between its ends.
+add('arrow.create', { from: 'prd', to: 'ticket-1', label: 'scopes' });
+add('arrow.create', { from: 'review-deck', to: 'status-site', label: 'ships' });
+console.log(JSON.stringify({ compositionId, batch }));
+```
+
+```sh
+node plan.mjs <composition-id> > /tmp/plan.json
+beehaven call canvas-act @/tmp/plan.json > /tmp/plan-result.json   # check ok, results[].ok, skipped
+```
+
+- With `parentId` (a frame id **or** name), `canvas.place` takes `x/y` relative to that
+  frame, exactly like `canvas.create-node`, and refuses a parent it cannot find. Results come
+  back in world coordinates.
+- Give explicit sizes. Unsized cards are born at their kind's size: board and sheet 720×440,
+  deck 560×315, document/project 340×440, ticket 340×210, site 420×440. A board shows up to
+  five lanes; a sheet its first rows.
+- A multi-page document places as a frame of pages; its result `id` is that frame.
+- `arrow.create {from,to}` resolves ids **or** layer names, and refuses one that matches
+  nothing. Read the error rather than retrying; the name you placed with is the handle.
+- Leave ~80px between connected cards so the label fits.
+
+## 4. Review it like any composition
+
+```sh
+node <skill-directory>/review.mjs <composition-id> plan /tmp/plan-review/plan
+```
+
+Work until the verdict is `clean` or `look` (see the studio bar in SKILL.md), then open the
+PNG. Check that each card shows its content:
+
+| Card | Should show | If not |
+|---|---|---|
+| Board | Lanes named after its columns, ticket cards in each | Empty lanes → no tickets on that board (check `boardId`) |
+| Sheet | A table: header row, then rows | One run-on line → an older worker; re-check after deploy |
+| Deck | Numbered slide titles | "Untitled slide" → slides were created without titles |
+| Any | Its content | "no longer exists" → wrong id or kind; "Loading…" in a headless render → unresolved kind |
+
+Then judge it as a page: does the goal win at thumbnail size, do the lanes read as two
+groups, does every card share the left edge and gutter? Fix the layout (cramped lanes,
+unreadable arrows, a stray card off the grid) before you finish.
+
+## 5. You are visible while you build
+
+When someone has the composition open, you appear in its collaborator stack with your
+name, your face and a live activity line ("Placing board · Q4 roadmap"). Your pointer
+travels to each thing a step creates or edits, a click plays where it lands, and the
+new node is briefly outlined in your colour. While someone is watching, each step is
+paced by a fraction of a second (capped per call) so the build streams in under the
+pointer. Nobody watching means no pacing.
+
+- **Order the batch in reading order** — header, then each lane left to right — so the
+  build reads as the plan unfolding rather than cards popping up at random.
+- **Name every layer** (`name`). The activity line uses titles and names.
+- Prefer **one batch per coherent section** over one call per node or one enormous
+  call: each call's pacing is capped, and a section is what a watcher follows.
+- Presence only ever reflects real steps. Do not issue no-op edits to "show activity".
+- Presence is not a status report. For a long task, keep one `canvas-add-claude-comm`
+  status block updated as well (see [communications.md](communications.md)).
+
+## 6. Hand it over
+
+```sh
+beehaven call agent-nav-open '{"kind":"composition","id":"<composition-id>"}'
+```
+
+Report the composition title and link, what each card is, and anything left to do
+(unfilled tickets, placeholder copy). Everything should be filed in the project.

package/skills/clearly-canvas/review.mjs

@@ -0,0 +1,68 @@
+#!/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 { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function rpc(action, payload) {
+  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 result;
+}
+
+export function saveReview(report, prefix) {
+  const preview = report.preview;
+  if (!preview?.dataUrl?.startsWith('data:image/png;base64,')) {
+    throw new Error(report.previewError || 'No PNG returned. Visual verification is incomplete.');
+  }
+  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);
+  mkdirSync(dirname(base), { recursive: true });
+  const { dataUrl, url, ...metadata } = preview;
+  const saved = { ...report, preview: { ...metadata, path: `${base}.png` } };
+  writeFileSync(`${base}.png`, bytes);
+  writeFileSync(`${base}.json`, JSON.stringify(saved, null, 2) + '\n');
+  const craft = report.craft?.findings ?? [];
+  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,
+    craft: craft.map((f) => `${f.severity} ${f.check}: ${f.detail}`),
+    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.'
+      : '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)) {
+  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.');
+  const [compositionId, id, prefix] = args;
+  let report;
+  if (legacy) {
+    const response = rpc('canvas-perceive', { compositionId, includePixels: true, fitNodeIds: [id], pixelScale: 1 });
+    const objects = response.room?.contents?.objects || [];
+    if (!objects.some((n) => n.id === id)) throw new Error('Frame ID absent from perception; refusing an unverified crop.');
+    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 } });
+    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');
+}
+
+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; }
+}