beehaven 0.8.29 → 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
@@ -110,10 +124,19 @@ 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
@@ -133,7 +156,7 @@ builds on the last and can be reviewed alone. Build ONE commit per canvas-act ba
 `canvas.review` of the artboard and carries
 `"ticket":{"id":"<key>","status":"done","resolution":"<what changed>"}` — it lands only if that
 review is clean or look; `result.ticket` says whether it did, and the ticket logs the canvas
-revision and the layers the commit changed. Auto-layout, gradients, shadows and SVG placeholders:
+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
@@ -195,8 +218,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

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,16 +140,25 @@ 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.
+- 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.
-- SVG PLACEHOLDERS: until real imagery exists, draw it as an svg node at its final size in a muted tone from the brand palette, never a flat accent block, e.g. for a 400×240 slot svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 240"><rect width="400" height="240" rx="12" fill="#EDE6DF"/><circle cx="170" cy="96" r="14" fill="#CDBFB2"/><path d="M150 168l40-48 30 34 22-20 40 34z" fill="#CDBFB2"/></svg>' — <svg viewBox="0 0 W H"> always matches the node w and h. Put a label in its own text node and name the svg "<section> image placeholder". Hand-write only simple marks like this (placeholders, dividers, UI icons); logos, illustrations and finished artwork come from svg-make.
+- 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.
 
 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/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-docs/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: clearly-docs
+description: >-
+  Read, search, edit and recover a company's documents in a Clearly workspace.
+  Use the seven-tool MCP filesystem for ordinary work; use the `beehaven` CLI
+  only for document history, diffs, and restore. Load this whenever the answer
+  depends on what the company has written down, or when you are about to write
+  something down for it. Triggers: "what do our docs say", "find the doc about
+  X", "update the spec", "write this up", "add it to the docs", "has this
+  changed", "what did they edit", "search the wiki", "company knowledge", "our
+  documentation", "the PRD", "the runbook".
+---
+
+> **Tool names below are written UNPREFIXED** (`clearly_read`). Your runtime may expose them
+> with a server prefix — e.g. `mcp__plugin_clearly_clearly__clearly_read`. **Match by suffix,
+> not by exact name**: a skill written against the bare name resolves to nothing otherwise, and
+> the failure looks like "the tool doesn't exist" rather than "the name is decorated".
+>
+> **If no such tool is callable at all**, the Clearly MCP server isn't authorised in this
+> session — these skills still LIST when it isn't, so you find out by firing a dead call.
+> Authorise it (`/mcp`, or `claude mcp`).
+
+## What this is
+
+The workspace is a **filesystem**, not a chat surface with a search box.
+
+```
+~/                       every document
+~/clearly.md             what is settled for the whole workspace
+~/<Folder>/              one directory per project
+~/<Folder>/clearly.md    what is settled for that folder
+~/.archive/              put away — hidden, readable, read-only, still searched
+```
+
+Folders are projects. Documents are `.md` files named `<KEY> <Title>.md` — e.g.
+`CLR-42 Pricing.md`. The key is an address: `cat ~/CLR-42.md` works from anywhere, and so does
+the full name and the bare title.
+
+## The loop
+
+**Find it, then open it.** `clearly_glob` answers "what is it called", `clearly_grep` answers
+"where is this mentioned", and `clearly_read` opens what either one returned.
+
+```
+clearly_glob  { pattern: "~/**/*.md" }
+clearly_grep  { pattern: "pricing", limit: 5 }
+clearly_read  { target: "~/Prepress/CLR-42 Pricing.md" }
+```
+
+⚠ **`clearly_grep` takes a REGEX, unparsed** — `|`, `(`, `$` and quotes mean what they mean in a
+regular expression. Nothing shells out, so nothing eats them as syntax first.
+
+⚠ **Archived documents are excluded from both.** When any matched, the result carries
+`archivedHidden` saying how many — mention that rather than reporting a clean miss. Search the
+archive by naming it: `clearly_grep { pattern: …, path: "~/.archive" }`.
+
+**Structural questions — a date range, a null body, counts — have no keyword to search for**, so
+they go to SQL over the workspace's own tables. That is a CLI job, not an MCP tool:
+
+```
+beehaven call bash '{"command":"sql SELECT title, updated_at FROM notes WHERE project_id IS NULL LIMIT 20"}'
+```
+
+Read-only, one statement, credential columns redacted.
+
+## ⚠⚠ Read before you write, and check what changed
+
+This is the part that makes documentation stay true, and it is the part agents skip.
+
+The MCP read/edit/replace tools cover the current body. Document history is a separate CLI surface:
+
+- **`beehaven call document-status '{"limit":20}'`** lists recent changes. `mine: true` is the
+  certain signal that the active agent made the latest change. `by: "unknown"` means the log has
+  no author; it may be a browser edit or an older unstamped agent write, so do not claim a person
+  made it.
+- **`beehaven call document-diff '{"id":"<documentId>"}'`** follows up with added and removed
+  lines. Pass a `versionId` from status to compare against a specific checkpoint.
+
+Run status when you resume a conversation, and whenever they say something implying the document
+has moved — *"I rewrote that"*, *"take another look"*.
+
+⚠ **Their edit wins, always.** If a document now disagrees with something you concluded
+earlier, your conclusion is the stale one. You are keeping their documents, not defending your
+own record. Never quietly restore what they took out.
+
+## Editing
+
+**`clearly_edit` (find/replace) is the default. `clearly_replace` REPLACES the whole document.**
+
+To change one line of a 12,000-character document, `replace` makes you reproduce all 12,000 — and
+anything you fail to retype is gone with no error. It is also a lost-update machine: it writes
+whatever you last read, overwriting anything the human changed in between.
+
+- `clearly_edit` requires the `find` text to match **exactly once**. Ambiguity is REFUSED with a
+  count, never guessed — an agent that edits the first of three matches has changed something
+  nobody looked at.
+- Several independent document edits can be sent in one tool call with `batch`, but each batch
+  row is still one exact `{ target, find, replace, all? }` operation. There is no `multi_edit`
+  field and the batch is not transactional; inspect the per-item results and retry only failures.
+- `clearly_replace` does not accept `expected_content` or a commit-message field. If you must replace
+  a whole existing document, re-read it immediately before writing and verify the returned body.
+  Prefer `clearly_edit` whenever a precise passage change can express the job.
+
+## Comments and @mentions — say it beside the work, not instead of it
+
+A comment is ABOUT something; an edit changes it. When you have a question or a note for a person,
+leave it where they will see it, on the thing itself:
+
+```
+clearly_comment { target: "CLR-42", content: "Is this still the Q3 number? @sam" }
+clearly_comment { target: "<sheetId>", content: "Double-counts refunds", fields: { cell: "Plan!D12" } }
+clearly_comment { target: "<deckId>",  content: "Tighten this headline", fields: { slide: 3 } }
+clearly_read  { type: "comment", target: "SS-41" }          # the thread, on any item
+clearly_read  { type: "comment", target: "@me" }            # where YOU were @mentioned
+clearly_edit  { type: "comment", target: "<mentionId>", changes: { acknowledged: true } }
+```
+
+`target` is the item — a document, sheet, deck, ticket, board, thought or canvas, by id, key or exact
+title. Anchor with `fields.quote` (document), `slide` (deck, required), `cell` (sheet), `column`
+(board) or `pinId` / `x`,`y` (canvas); an anchor the item cannot carry is refused, never dropped.
+
+`@handle` mentions a person (notified) or an agent (queued in its inbox). Get real handles with
+`clearly_read { type: "comment", target, includeMentionables: true }`. The write's result lists
+`mentions`, and `unmatchedMentions` for any handle that reached **no one** — say so, do not assume.
+Acknowledge a mention once you have acted on it, or it comes back in every session.
+
+## `clearly.md` — what is settled
+
+Not a document like the others. It holds what this place IS (the work, the constraints, the
+vocabulary, the decisions that stopped moving) and **how this person wants to be worked with** —
+length, tone, format, and what irritates them, which is said once in passing and worth more than
+anything they praise.
+
+Fold a conclusion into it once it has stopped moving. Reach for `edit`, never `replace`.
+
+## Report what MOVED
+
+*"You added a paragraph about the 12-hour window to Pricing and removed the line about three
+credits"* is a report. *"I've updated the note"* is not — it costs a turn and says nothing they
+could not have assumed.
+
+## What not to do
+
+- **Do not tidy unasked.** A document that looks redundant or superseded is still theirs. If two
+  say the same thing, say so and let them choose.
+- **`delete` archives, it does not erase** — the document moves to `~/.archive/`, stays readable
+  and comes back. Report it as **archived**; "deleted" makes someone believe something is gone
+  that is not.
+- **Do not invent a media line.** `![caption](url)` renders a photo, audio or video by file
+  extension. You cannot upload, so never write one pointing at a URL you guessed — it renders
+  broken, which reads as their photo being lost. Move existing lines; never fabricate one.