@clearlysh/beehaven 0.8.31 → 0.8.33

package/skills/clearly-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clearly-agent
-description: Work in a Clearly workspace AS an agent — sign in with an identity, resume a session, read your brief (what changed since you were last here, your recents, your unfiled drafts), and understand whose work you are creating. TRIGGER on the first `beehaven` call of any session, on "Not an agent" / "agent login" refusals, and when the user asks "who am I acting as", "what was I doing", "what have I made", "why can't the agent see this", "why is my work invisible", or "run this as a different agent". Read this BEFORE clearly-canvas or clearly-workspace — both need an identity and neither will work without one.
+description: Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini CLI); in a chat with only the Clearly connector, say so and use the clearly_* tools instead. Work in a Clearly workspace AS an agent — sign in with an identity, resume a session, read your brief (what changed since you were last here, your recents, your unfiled drafts), and understand whose work you are creating. TRIGGER on the first `beehaven` call of any session, on "Not an agent" / "agent login" refusals, and when the user asks "who am I acting as", "what was I doing", "what have I made", "why can't the agent see this", "why is my work invisible", or "run this as a different agent". Read this BEFORE clearly-canvas or clearly-workspace — both need an identity and neither will work without one.
 ---
 
 # clearly-agent — who you are, and what that makes your work
@@ -216,6 +216,11 @@ governance. Each resource's delete cell is `none`, `own`, or `all`; `own` means
 `created_by: agent:<your-id>`. Missing or legacy author data is not yours. Permanent deletion is
 human-only; agent deletes use a recoverable archive, tombstone, or checkpoint.
 
+Removing canvas layers is an **update**, including `canvas.delete`, block removal, and placed
+design layers. You may remove layers from any visible canvas within your edit scope, regardless
+of its author. The server requires an undo checkpoint first. Deleting or archiving the whole
+canvas still follows delete-own/delete-all (CAN2-128).
+
 Only agents whose owner is currently a workspace owner or admin can use admin or delete-all. The
 server checks this on every call: if your owner is demoted, your scope drops to write/delete-own.
 After an owner is promoted again, a human must explicitly re-grant the higher scope.
@@ -228,15 +233,17 @@ owner/admin-owned agent can be granted it. Check yours before a destructive step
 beehaven call agent-capabilities-get '{}'     # { scope, matrix, summary }
 ```
 
-⚠ `permission_scope: 'write'` lets you delete only your own work. A refusal on another author's
-item is the contract working, not a bug. ⚠ You cannot change permissions — yours or another agent's;
+⚠ `permission_scope: 'write'` lets you archive/remove only your own workspace items; editing layers
+inside an editable canvas follows the update rule above. A permission refusal is the contract
+working, not a bug. ⚠ You cannot change permissions — yours or another agent's;
 ask the owner.
 
 ## Traps that cost real time
 
 - ⚠ **`beehaven env` first.** `prod` and `staging` are different databases and `--env` does not
   exist on `call` — the daemon *is* the env. Every number is meaningless if you are on the wrong one.
-- ⚠ **A deploy does not reach a resident DO.** `beehaven stop && sleep 15 && beehaven start --headless`.
+- ⚠ **Verify a deploy by the response's runtime version.** Allow propagation and retry read-only
+  checks; do not restart the user's daemon to force a resident DO onto a new version.
 - ⚠⚠ **Check the `as <agent>` on your first call.** An identity archived in this workspace still
   mints (identities are account-level), but the workspace refuses its session. Current CLIs say so
   (`⚠ Signed in, but this workspace refused …`, exit 1) and then refuse every call as that

package/skills/clearly-canvas/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: clearly-canvas
 description: >-
+  Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini CLI); in a chat with only the Clearly connector, say so and use the clearly_* tools instead.
   Design and revise editable compositions on a Clearly canvas using the beehaven
   CLI: posters, campaigns, decks, page mockups, diagrams, spatial reviews, and
   project plans built from LIVE workspace objects (boards, tickets, documents,
@@ -19,6 +20,13 @@ The deliverable is a composition that communicates a specific idea at its intend
 viewing size, with editable, well-named layers. Successful RPCs prove that nodes were
 stored. A rendered image you have inspected is the evidence for visual quality.
 
+Use the same working method as a designer in Figma: artboards, named editable layers,
+text styles, reusable components, auto-layout and constraints; explicit responsive states;
+then inspect the pixels and refine. Read `authoring.md` and discover the current catalog
+before assuming an operation is missing. Typography defaults to Auto; use `140%` or `24px`
+for explicit line heights. Keep unsupported capabilities and unverified rendering visible
+in the handoff; a familiar workflow does not prove every Figma feature is implemented.
+
 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.
 
@@ -32,7 +40,7 @@ Load **`design-craft`** before any new visual work: grid, type scale, colour rol
 spacing, optical correction, the studio pass. It ships beside this skill; `layout-systems`
 covers multi-artboard grids. This skill covers the canvas mechanics.
 
-A composition is done when every requested artboard meets all four conditions:
+A composition is done when every requested artboard meets all five 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),
@@ -47,6 +55,12 @@ A composition is done when every requested artboard meets all four conditions:
    one accent, orphans, consistency.
 4. **The first read works at delivery size.** At thumbnail size, the thing that should
    win does win.
+5. **The document behaves as a design.** Inspect its frame tree: sections and UI containers
+   own their contents and background fills; rows, stacks and grids use live auto layout
+   with deliberate Hug/Fill/Fixed sizing. Resize a representative container and lengthen
+   its copy on a duplicate, then verify reflow and containment. Keep intentional artwork
+   positioned inside named artwork frames. Record these checks separately from visual QA;
+   `canvas.review` does not prove hierarchy or reflow.
 
 A new composition almost always needs at least one revision after its first render. If
 the pass finds nothing, look again at the thumbnail. If there is still nothing, say what

package/skills/clearly-canvas/authoring.md

@@ -10,8 +10,8 @@ Use a local builder and pass JSON through `@file` or stdin. Do not interpolate c
 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
+For desktop, mobile and dark examples, inspect [example.mjs](example.mjs).
+It demonstrates nested flow containers, Hug/Fill sizing and framed artwork; 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.
 
@@ -21,18 +21,22 @@ 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 },
+  display: { family: 'Inter', size: 88, fontWeight: 700, lineHeight: '105%', letterSpacing: -2 },
+  body: { family: 'Inter', size: 24, fontWeight: 400, lineHeight: '140%' },
 };
 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,
+add('frame.create', { name: 'hero-copy', parentId: '01-opening', w: 740, h: 400, fill: 'transparent' });
+const text = (name, copy, role) => add('canvas.create-node', {
+  name, type: 'text', parentId: 'hero-copy', w: 740,
   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');
+text('opening-title', 'Ideas take shape here.', 'display');
+text('opening-deck', 'An editable visual system for the next chapter.', 'body');
+add('canvas.update-nodes', { ids: ['opening-title', 'opening-deck'], patch: { layoutSizingH: 'fill' } });
+add('canvas.auto-layout', { id: 'hero-copy', direction: 'v', gap: 24, sizingH: 'fixed', sizingV: 'hug' });
+add('canvas.auto-layout', { id: '01-opening', direction: 'v', gap: 64, padding: grid.margin, sizingH: 'fixed', sizingV: 'hug' });
 // Continue with the brief's central visual, supporting evidence and footer.
 writeFileSync('/tmp/canvas-build.json', JSON.stringify({ compositionId, batch }));
 ```
@@ -57,6 +61,13 @@ Keep executed payloads and returned-ID manifests separate from regenerated plans
 
 ## Node shape and coordinates
 
+Choose ownership before coordinates: page → section → row/stack/grid → content. Put
+the container's background, border and radius on its frame. Auto layout owns positions
+in content flow; use Hug for content height and Fill for flexible width. Keep deliberate
+overlays and illustrations inside artwork frames. A native editable layer alone does
+not establish a usable document structure. Frames also make scoped perception cheaper:
+read the outline and the section you are editing instead of a full scene dump.
+
 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.
@@ -90,6 +101,14 @@ not a missing node. Replacing `svg` clears and rebuilds its reference automatica
 
 ## Typography
 
+Line height defaults to **Auto**, from the font itself. Use `lineHeight:"140%"` for a
+percentage of font size or `lineHeight:"24px"` for fixed leading. Numeric values in old
+scenes remain multipliers (`1.4` = `140%`); new designs should carry explicit units.
+Changing font size scales % leading and leaves px leading fixed. Paragraph spacing is
+`paragraphSpacing` in px after a hard newline, never a soft wrap. In a fixed-height
+box, `vAlign:"middle"` centers the line boxes; `"bottom"` anchors their bottom. Do not
+compensate with spaces, empty lines or hand-tuned y offsets.
+
 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
@@ -99,7 +118,7 @@ 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}}
+  "letterSpacing":-2,"lineHeight":"105%","maxWidth":740}}
 ```
 
 Use measured `height`/`lineCount` to place the next block. Measure the exact copy, font,
@@ -121,12 +140,20 @@ deliverable requires them, with content order and hierarchy reconsidered for the
 
 ## Technique
 
+- CONTAINERS: page sections, cards, sidebars and toolbars are named frames that own their content and background fill. Use live auto-layout for content rows, stacks and grids, with explicit Hug/Fill/Fixed sizing; position overlays and artwork deliberately within their owning frames. A rectangle behind sibling text is not a container. Verify the frame tree, resize a representative container and lengthen its copy on a duplicate before completion; record reflow checks separately from pixel review.
+- FIGMA WORKFLOW: approach this canvas as a designer working in Figma. Read the brand and component library; compose artboards from named editable frames, text, shapes and component instances; use auto-layout, constraints, styles and variables; create deliberate desktop/mobile and light/dark states; inspect at delivery size, iterate, then review the final edit. Discover the current canvas-catalog before assuming a familiar Figma operation is unavailable. Its headlessActions identify what runs without an open editor; live-only actions need an editor. Report an unsupported capability accurately rather than inventing an operation or claiming universal feature parity.
+
+- TYPOGRAPHY: lineHeight defaults to "auto", using the resolved font metrics. Author percentages as "140%" and absolute leading as "24px"; legacy numeric 1.4 still means 140%. Percentage leading follows font size; px leading stays fixed until the Scale tool scales the artwork. paragraphSpacing is px between hard-newline paragraphs, never soft wraps. For Auto width omit w/h; for Auto height set w and omit h; for a fixed box set w/h. Explicit layoutSizingH/V "fixed" or "fill" overrides legacy autoWidth/autoHeight. align is left|center|right|justify; vAlign is top|middle|bottom and applies to fixed-height boxes. Measure exact copy/font/weight/width using canvas.measure-text, then inspect the pixels; do not center text with spaces or arbitrary y offsets.
+
 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.
+- AUTO-LAYOUT: rows, stacks and grids are a frame whose children you create in reading order, then canvas.auto-layout { id, direction: "h" | "v" | "grid", gap, padding, align, justify, hug }. hug:false keeps the frame size; justify "space-between" | "space-around" | "space-evenly" are the Auto gaps; align:"baseline" lines up text in a row. Grids take columns, rows, columnGap, rowGap, columnSizes / rowSizes ("fill", "2fr", "hug", px). wrap:true flows into new rows; give Fill cards a minW so they wrap where you mean. Child settings go on the child via canvas.update-nodes: layoutSizingH/V "fill" | "hug" | "fixed", minW / maxW / minH / maxH, gridColumn / gridRow / gridColumnSpan, layoutPositioning:"absolute". The frame stays live: children created into it (parentId) flow in. Spacing variables: canvas.variable { op: "bind", ids, field, name }.
 - 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.
+- 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. It also takes d (SVG path data, converted to native editable points) or shape: petal|circle|polygon|star|arc|spiral with cx, cy and sizes; strokeCap/strokeJoin apply. Reshape in place with canvas.update-nodes { ids, patch: { points | d | shape } }. Draw a repeated part once: canvas.repeat { id, count, around | cx, cy } turns one petal into a flower; canvas.rotate { ids, angle, cx, cy }; canvas.boolean { ids, op: "union" | "subtract" | "intersect" | "exclude" } (exact, editable operands). 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 }. 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.
+- COMPUTED GEOMETRY: shapes from math (radial petals, spirals, grids) are computed and drawn in ONE call: canvas-act { compositionId, script } runs JavaScript with geo.petal/circle/arc/star/polygon/spiral/smooth/rotate/radial/grid/bounds (degrees, 0 = 3 o'clock, clockwise) and a read-only scene list, then applies the { action, args } steps it returns. Never copy numbers from one tool result into another call.
+- SHEETS: several concepts or variants go on canvas.sheet { name, title, subtitle, cards or count, cols, cardW, cardH }: a live wrap grid of card frames that own their captions, so rows never overlap. Draw into a card with parentId = its id.
+- MEASURE: answer spacing, overlap and alignment questions with canvas.measure { frame } or { ids } and quote its numbers, never from memory or a preview.
 - 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.
 

package/skills/clearly-canvas/example.mjs

@@ -1,78 +1,81 @@
 #!/usr/bin/env node
-/** Example of a reusable native-node builder. Writes JSON only; it never calls a workspace. */
+/** Three editable page states. 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 fillWidth = id => op('canvas.update-nodes', { ids: [id], patch: { layoutSizingH: 'fill' } });
+// Page, section, row, card and button share this container contract.
+function flow(id, parentId, box, layout, children) {
+  // Enable flow before adding children so reading order is creation order.
+  op('frame.create', { id, name: id, parentId, fill: 'transparent', ...box,
+    autoLayout: { direction: 'v', gap: 24, padding: 0, ...layout },
+    layoutSizingH: layout.sizingH ?? 'fixed', layoutSizingV: layout.sizingV ?? 'hug' });
+  children(id);
+  op('canvas.auto-layout', { id, direction: 'v', gap: 24, padding: 0,
+    sizingH: 'fixed', sizingV: 'hug', ...layout });
+  return id;
 }
-
-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);
-});
+function text(parentId, name, copy, w, size, fill, extra = {}) {
+  const id = parentId + '/' + name;
+  op('canvas.create-node', { id, name, parentId, type: 'text', w, text: copy,
+    size, family: 'Inter', fill, lineHeight: 'auto', ...extra });
+  fillWidth(id);
+  return id;
+}
+function page(id, x, mobile = false, dark = false) {
+  const w = mobile ? 390 : 1440, pad = mobile ? 24 : 80, inner = w - pad * 2;
+  const ink = dark ? '#F2F0E7' : '#172824', ground = dark ? '#172824' : '#F2F0E7';
+  flow(id, undefined, { x, y: 0, w, h: 1000, fill: ground }, { gap: 64, padding: pad }, p => {
+    flow(p + '/navigation', p, { w: inner, h: 48 }, { direction: 'h', align: 'center', justify: 'space-between' }, nav => {
+      text(nav, 'brand', 'FIELDWORK', inner - 140, 20, ink, { fontWeight: 700 });
+      text(nav, 'edition', 'STUDIO NOTES', 140, 14, ink);
+      op('canvas.update-nodes', { ids: [nav + '/edition'], patch: { layoutSizingH: 'fixed' } });
+    });
+    fillWidth(p + '/navigation');
+    flow(p + '/hero', p, { w: inner, h: 420 }, { direction: mobile ? 'v' : 'h', gap: 48 }, hero => {
+      const copyWidth = mobile ? inner : 740;
+      flow(hero + '/copy', hero, { w: copyWidth, h: 400 }, { gap: 24 }, copy => {
+        text(copy, 'eyebrow', 'A NOTE ON MAKING', copyWidth, 14, ink, { letterSpacing: 1.5 });
+        text(copy, 'title', 'Make room for the idea.', copyWidth, mobile ? 48 : 88, ink,
+          { fontWeight: 700, letterSpacing: -2, lineHeight: '105%' });
+        text(copy, 'description', 'A shared direction. An editable system. Room for the next idea.', copyWidth, 22, ink, { lineHeight: '145%' });
+        flow(copy + '/action', copy, { w: 240, h: 56, fill: ink, radius: 8 },
+          { direction: 'h', padding: 16, align: 'center' }, button => {
+            text(button, 'label', 'Explore the studio', 208, 16, ground, { align: 'center' });
+          });
+      });
+      fillWidth(hero + '/copy');
+      // Art-directed coordinates belong inside an owning artwork frame.
+      const art = hero + '/artwork', aw = mobile ? inner : 400;
+      op('frame.create', { id: art, name: 'Artwork / two fields', parentId: hero, w: aw, h: 320, fill: '#C84A2E' });
+      op('canvas.create-node', { id: art + '/disc', name: 'Disc', type: 'ellipse', parentId: art, x: 24, y: 24, w: 220, h: 220, fill: '#F2F0E7' });
+      op('canvas.create-node', { id: art + '/field', name: 'Field', type: 'rect', parentId: art, x: 116, y: 136, w: 196, h: 160, fill: '#172824' });
+    });
+    fillWidth(p + '/hero');
+    flow(p + '/features', p, { w: inner, h: 220 }, { direction: 'grid', columns: mobile ? 1 : 3,
+      rows: mobile ? 3 : 1, rowSizes: mobile ? ['hug', 'hug', 'hug'] : ['hug'], gap: 24, rowGap: 24 }, grid => {
+      for (const [name, title, body] of [
+        ['type', 'Give ideas a voice.', 'Type scales and wraps with the available space.'],
+        ['space', 'Keep room to grow.', 'Content owns its height. Related layers move together.'],
+        ['review', 'Make the next edit.', 'Resize a card and extend its copy to check the system.'],
+      ]) {
+        const card = grid + '/' + name, cw = mobile ? inner : (inner - 48) / 3;
+        flow(card, grid, { w: cw, h: 180, fill: dark ? '#294337' : '#FFFFFF', radius: 12 }, { gap: 16, padding: 24 }, c => {
+          text(c, 'title', title, cw - 48, 24, ink, { fontWeight: 600 });
+          text(c, 'body', body, cw - 48, 18, ink, { lineHeight: '145%' });
+        });
+        fillWidth(card);
+      }
+    });
+    fillWidth(p + '/features');
+    text(p, 'footer', 'FIELDWORK / A SYSTEM READY FOR CHANGE', inner, 14, ink, { letterSpacing: 1 });
+  });
+}
+page('01-desktop', 0);
+page('02-mobile', 1520, true);
+page('03-dark', 1990, false, true);
 writeFileSync(output, JSON.stringify({ compositionId, batch }, null, 2) + '\n');
-process.stdout.write(`${output}: ${batch.length} operations\n`);
+process.stdout.write(output + ': ' + batch.length + ' operations\n');

package/skills/clearly-workflows/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: clearly-workflows
 description: >-
+  Best with the beehaven CLI (semantic search and write-back); with only the Clearly connector, search with clearly_grep and record decisions with clearly_create.
   Use the Clearly workspace as a COMPANY BRAIN — search the org's accumulated
   context (decisions, facts, prompts, docs), write conclusions back so the next
   agent inherits them instead of re-deriving them, and inherit the team's

package/skills/clearly-workspace/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clearly-workspace
-description: Understand and audit a Clearly workspace from the terminal — what it holds (documents, projects, boards, tickets, thoughts, files, agents), who authored what, and which known data defects are present. Run `survey.mjs` for the whole picture in one command. TRIGGER when the user asks "what is in this workspace", "how big is this workspace", "audit / survey / check the workspace", "what have my agents made", "is anything broken in here", "who created these", or before any cleanup, migration or backfill — the survey is what tells you whether a repair is needed and whether it worked. NOT for editing documents (use `document-*`) or drawing on a canvas (use clearly-canvas).
+description: Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini CLI); in a chat with only the Clearly connector, say so and use the clearly_* tools instead. Understand and audit a Clearly workspace from the terminal — what it holds (documents, projects, boards, tickets, thoughts, files, agents), who authored what, and which known data defects are present. Run `survey.mjs` for the whole picture in one command. TRIGGER when the user asks "what is in this workspace", "how big is this workspace", "audit / survey / check the workspace", "what have my agents made", "is anything broken in here", "who created these", or before any cleanup, migration or backfill — the survey is what tells you whether a repair is needed and whether it worked. NOT for editing documents (use `document-*`) or drawing on a canvas (use clearly-canvas).
 ---
 
 # clearly-workspace — know what you are standing in

package/skills/codebase-map/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: codebase-map
-description: Walk a code repository and draw a living ARCHITECTURE MAP of it on a Clearly spatial canvas — modules as frames (sized by LOC, colored by layer), key files as nodes, imports/dependencies as arrows — so the big pieces, how they depend on each other, and where the complexity sits all read at a glance. Load this when the user says "map / diagram / visualize this codebase / repo / architecture", "how is this project structured", "draw the dependency graph", "give me an architecture overview", or when you're onboarding to an unfamiliar repo and need to see its shape fast.
+description: Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini CLI); in a chat with only the Clearly connector, say so and use the clearly_* tools instead. Walk a code repository and draw a living ARCHITECTURE MAP of it on a Clearly spatial canvas — modules as frames (sized by LOC, colored by layer), key files as nodes, imports/dependencies as arrows — so the big pieces, how they depend on each other, and where the complexity sits all read at a glance. Load this when the user says "map / diagram / visualize this codebase / repo / architecture", "how is this project structured", "draw the dependency graph", "give me an architecture overview", or when you're onboarding to an unfamiliar repo and need to see its shape fast.
 ---
 
 > **⚠ CANVAS WORK GOES THROUGH THE CLI, NOT AN MCP TOOL.** Anything written

package/skills/design-craft/SKILL.md

@@ -114,8 +114,9 @@ divided by the ratio. Sizes that share a ratio look related; sizes picked by han
   make them obviously different in class (a grotesque with a serif), never two neighbours.
 - **Measure: 45–75 characters.** At 16px in a normal grotesque that is roughly **360–600px**.
   Set the text node's `w` to hold that, not to fill the column.
-- **Line height moves INVERSELY to size.** Body 1.4–1.6. Subheads 1.25–1.35. Display
-  **0.95–1.05** — big type needs tight leading or it falls apart into stripes.
+- **Line height defaults to Auto**, using the font's metrics. When tuning it deliberately,
+  use **140–160%** for body, **125–135%** for subheads, and **95–105%** for display type.
+  Author explicit units (`lineHeight:"140%"` or `"24px"`); percentage leading follows font size.
 - ⚠⚠ **TRACK DISPLAY TYPE NEGATIVE.** Type designed at 16px is far too loose at 120px.
   Above ~40px use `letterSpacing: -1` to `-4`; above ~120px, −3 to −6. **Uppercase and small
   labels go the other way: +1 to +3.** This one adjustment does more for perceived quality
@@ -250,8 +251,8 @@ only to show that a review happened.
 
 **A 1080×1350 social post**
 ```
-margin 72 · display 96–140 (weight 800, tracking −3, lineHeight 1.0)
-body 20–24 (weight 500, lineHeight 1.5, w ≤ 560)
+margin 72 · display 96–140 (weight 800, tracking −3, lineHeight "100%")
+body 20–24 (weight 500, lineHeight "150%", w ≤ 560)
 caption 16 (weight 600, tracking +1.5, uppercase)
 rule 2–3px accent · footer block bottom-aligned at 1350 − 72 − blockHeight
 ```
@@ -265,7 +266,7 @@ Content column ≤ 1200 wide even though the slide is 1920 — full width is unr
 
 **A 1440 web hero**
 ```
-margin 96 · content max 1200 · headline 64–88 (tracking −2, lineHeight 1.05)
+margin 96 · content max 1200 · headline 64–88 (tracking −2, lineHeight "105%")
 sub 20–24 (muted ink, w ≤ 640) · CTA 48–56 tall, 24–32 horizontal padding, radius 8 or full
 ```
 
@@ -273,7 +274,9 @@ sub 20–24 (muted ink, w ≤ 640) · CTA 48–56 tall, 24–32 horizontal paddi
 ```
 padding 24–32 · radius 10–16 · gap between cards ≥ 2× padding
 title 20–24/600 · body 15–16/400 muted · one accent element maximum
-Background first, THEN the label — later nodes draw over earlier ones.
+Use a filled frame that owns the card's contents. Apply auto layout with this padding
+and a deliberate content gap; let text hug its height. Rectangles serve artwork,
+swatches and rules. A background rectangle with sibling text does not form a card.
 ```
 
 ---

package/skills/index.json

@@ -17,21 +17,21 @@
       "project-plans.md",
       "review.mjs"
     ],
-    "sha": "b942eebe6f0397fb"
+    "sha": "5daf296f2bdf65e6"
   },
   {
     "name": "agent-home",
     "files": [
       "SKILL.md"
     ],
-    "sha": "0bbcdbd33cfb11a3"
+    "sha": "e1d18e7518ff4b65"
   },
   {
     "name": "agent-doodle-space",
     "files": [
       "SKILL.md"
     ],
-    "sha": "053fc1cd5a1494d4"
+    "sha": "1e1911e6d8784476"
   },
   {
     "name": "design-craft",
@@ -39,35 +39,35 @@
       "SKILL.md",
       "references.md"
     ],
-    "sha": "bf2f4fac6f57ea46"
+    "sha": "d11f0c45c93c9dea"
   },
   {
     "name": "layout-systems",
     "files": [
       "SKILL.md"
     ],
-    "sha": "8de89b7b7c86f81f"
+    "sha": "27151a50e3bdb27a"
   },
   {
     "name": "brand-identity",
     "files": [
       "SKILL.md"
     ],
-    "sha": "755db2d1ab8c759f"
+    "sha": "366139b11ff11b58"
   },
   {
     "name": "pair-on-canvas",
     "files": [
       "SKILL.md"
     ],
-    "sha": "65f87e74bf3566a6"
+    "sha": "1d79147baa8c232d"
   },
   {
     "name": "codebase-map",
     "files": [
       "SKILL.md"
     ],
-    "sha": "2e80ffd32f77327f"
+    "sha": "4a4af2229b68827d"
   },
   {
     "name": "clearly-workspace",
@@ -75,28 +75,28 @@
       "SKILL.md",
       "survey.mjs"
     ],
-    "sha": "f5585be212a67c32"
+    "sha": "3a3e6fa6e3cf8717"
   },
   {
     "name": "clearly-agent",
     "files": [
       "SKILL.md"
     ],
-    "sha": "b3f47988cb9235b9"
+    "sha": "c20b255224221342"
   },
   {
     "name": "visualize",
     "files": [
       "SKILL.md"
     ],
-    "sha": "ce9410c1ba7b3457"
+    "sha": "88bb6e94fb37c337"
   },
   {
     "name": "sticker-pack",
     "files": [
       "SKILL.md"
     ],
-    "sha": "f029503ebae59c64"
+    "sha": "74af254817a134d6"
   },
   {
     "name": "clearly-docs",
@@ -117,6 +117,6 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "f26dbbc90929ebe7"
+    "sha": "b9622f21173bab0d"
   }
 ]

package/skills/layout-systems/SKILL.md

@@ -47,7 +47,7 @@ that lost one. If you have four items, ask whether one is really a different thi
 ```
 margin 8–10% of the short edge      (1080 → 88–108; A3 → 280–350)
 display 12–20% of the HEIGHT        (1350 → 160–270px), weight 700–900, tracking −3 to −6,
-                                     lineHeight 0.92–1.0
+                                     lineHeight "92%"–"100%"
 supporting 2–3% of height           credits, date, venue — deliberately small
 ```
 
@@ -105,7 +105,7 @@ content column ≤ 1200 even though the slide is 1920
 ## Landing page / hero — 1440 wide (design), content max 1200
 
 ```
-margin 96 · headline 64–88 (tracking −2, lineHeight 1.05) · sub 20–24 muted, w ≤ 640
+margin 96 · headline 64–88 (tracking −2, lineHeight "105%") · sub 20–24 muted, w ≤ 640
 CTA 48–56 tall, 24–32 horizontal padding · section spacing 96–160 vertical
 ```
 
@@ -124,7 +124,7 @@ CTA 48–56 tall, 24–32 horizontal padding · section spacing 96–160 vertica
 
 ```
 margin: outer 10%, inner (gutter side) 12–14% — asymmetric, because the binding eats it
-columns 2–3 for A4 body · measure 45–75ch · body 10–11pt (≈42–46px at 300dpi), lineHeight 1.45
+columns 2–3 for A4 body · measure 45–75ch · body 10–11pt (≈42–46px at 300dpi), lineHeight "145%"
 ```
 
 - **Asymmetric margins are the mark of real editorial.** Equal margins all round read as a
@@ -141,9 +141,9 @@ columns 2–3 for A4 body · measure 45–75ch · body 10–11pt (≈42–46px a
 ## Cards, tables and dense UI
 
 - **Card padding 24–32, radius 10–16, gap between cards ≥ 2× padding.**
-- ⚠⚠ **BACKGROUND FIRST, LABEL SECOND.** Later nodes draw over earlier ones — create the
-  card rect, THEN its text. Reversed, the opaque fill hides the label and you get the classic
-  "grid of cards with no text".
+- **Cards are filled frames.** Parent labels, icons and controls to the card; use auto
+  layout for its content. Build rows and grids from these cards, with deliberate
+  Hug/Fill/Fixed sizing. Reserve rectangles for decorative shapes, swatches and rules.
 - **In tables, align numbers RIGHT and use tabular figures.** Left-aligned numbers of
   different lengths cannot be compared, which is the only reason the table exists.
 - **Zebra striping OR rules, never both.** Ideally neither — space is enough at ≥12px row padding.
@@ -153,10 +153,13 @@ columns 2–3 for A4 body · measure 45–75ch · body 10–11pt (≈42–46px a
 ## Building it on the canvas
 
 ```jsonc
-// ONE batch. Frames first, then children with parentId (x/y RELATIVE to the frame).
-{"action":"frame.create","args":{"name":"poster","x":200,"y":300,"w":1080,"h":1350,"fill":"#111111"}}
-{"action":"canvas.create-node","args":{"name":"headline","type":"text","parentId":"poster",
-  "x":88,"y":900,"w":904,"text":"…","size":180,"fontWeight":800,"letterSpacing":-5,"lineHeight":0.95}}
+// ONE batch. A content stack owns its fill and children; the layout computes positions.
+{"action":"frame.create","args":{"id":"card","name":"Feature card","w":360,"h":200,"fill":"#FFFFFF"}}
+{"action":"canvas.create-node","args":{"name":"Feature title","type":"text","parentId":"card",
+  "w":312,"text":"Make room for the idea","size":28,"fontWeight":600,"lineHeight":"auto"}}
+{"action":"canvas.create-node","args":{"name":"Feature detail","type":"text","parentId":"card",
+  "w":312,"text":"Keep every layer ready for the next edit.","size":16,"lineHeight":"145%"}}
+{"action":"canvas.auto-layout","args":{"id":"card","direction":"v","gap":16,"padding":24,"sizingH":"fixed","sizingV":"hug"}}
 ```
 
 - ⚠ **Omit `h` on text** — it hugs its wrapped content. Pin `h` only when a later element's
@@ -180,5 +183,5 @@ columns 2–3 for A4 body · measure 45–75ch · body 10–11pt (≈42–46px a
 | Deck | too many words; title states the topic instead of the argument; full-width text |
 | Landing | subhead runs full width; two competing CTAs; sections evenly spaced |
 | Editorial | symmetric margins; no baseline grid; unbroken columns |
-| Cards | text created before its background; gaps equal to padding so groups do not read |
+| Cards | background and contents lack a shared frame; layout breaks when copy grows |
 | **All** | **an exact 50/50 split, and four type sizes where three would do** |

package/skills/pair-on-canvas/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pair-on-canvas
-description: Use a Clearly canvas as mission control for a coding task — read the spec the human placed on the board, do the work in the repo, and report progress, diffs, and next steps back as cards they steer by inking. Load this when the user says "work the task on my canvas", "take this from the board", "what's on my Clearly canvas", "pick up the spec", "let's pair on the canvas", or whenever a human is directing your coding work spatially instead of in a chat thread.
+description: Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini CLI); in a chat with only the Clearly connector, say so and use the clearly_* tools instead. Use a Clearly canvas as mission control for a coding task — read the spec the human placed on the board, do the work in the repo, and report progress, diffs, and next steps back as cards they steer by inking. Load this when the user says "work the task on my canvas", "take this from the board", "what's on my Clearly canvas", "pick up the spec", "let's pair on the canvas", or whenever a human is directing your coding work spatially instead of in a chat thread.
 ---
 
 > **⚠ CANVAS WORK GOES THROUGH THE CLI, NOT AN MCP TOOL.** Anything written