beehaven 0.8.27 → 0.8.33

package/skills/brand-identity/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: brand-identity
 description: >-
-  Build a complete brand identity on a Clearly canvas the way a studio does —
+  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 the requested logo or brand identity on a Clearly canvas —
   brief, mark, wordmark, lockups and clear space, palette, type system,
   applications, and a spec board someone else can build from. Use when asked
   for a brand, a logo, an identity, a rebrand, a visual system, brand
@@ -13,10 +14,14 @@ description: >-
 
 # brand-identity — a system, not a picture of a logo
 
-⚠⚠ **THE DELIVERABLE IS A SYSTEM SOMEONE ELSE CAN BUILD WITH.** A single mark on a white
-artboard is not an identity; it is a drawing. Pentagram's identity work ships a symbol, a
-wordmark, a graphic system, a palette, a type system and the guidelines that let an in-house
-team keep it consistent. That is the shape to copy.
+Match the user's scope. For a logo concept, deliver the editable mark/wordmark, primary and
+one-color use, a small-size check, and the requested application. A logo plus landing page does
+not require merchandise, storefronts or a complete guideline deck. Add those when requested or
+when a concrete use in the brief requires them.
+
+For a complete identity request, the deliverable is a system someone else can build with:
+symbol, wordmark, palette, typography, applications and guidelines. Sections 6–8 describe that
+larger scope; they are optional for a narrow concept.
 
 Read **`design-craft`** first or alongside — grid, type scale, colour roles and the studio
 pass are assumed here.
@@ -60,15 +65,31 @@ handover. A mark of hand-placed béziers does not, and it shows.
 | **Counter-form** | the shape is the NEGATIVE space between forms | clever marks that survive one colour |
 | **Modular** | one unit repeated/rotated on a grid | systems, networks, collectives |
 
-**Build it as an `svg` node with a stated viewBox and derived numbers:**
+**Build it from native layers, every number derived from the construction** — the way an
+identity designer works in Figma, so each part of the mark stays a named, editable layer in the
+brand colour (never one generated or hand-written SVG):
 
 ```jsonc
-{"action":"canvas.create-node","args":{"name":"mark","type":"svg","x":120,"y":120,"w":240,"h":240,
- "svg":"<svg viewBox='0 0 240 240' xmlns='http://www.w3.org/2000/svg'>…</svg>"}}
+{"batch":[
+ {"action":"frame.create","args":{"name":"Mark","x":120,"y":120,"w":240,"h":240}},
+ {"action":"canvas.create-node","args":{"type":"ellipse","name":"mark/ring","parentId":"Mark",
+   "x":20,"y":20,"w":200,"h":200,"fill":"#1B4DFF"}},
+ {"action":"canvas.create-node","args":{"type":"ellipse","name":"mark/counter","parentId":"Mark",
+   "x":70,"y":70,"w":100,"h":100,"fill":"#FFFFFF"}},
+ {"action":"vector.create","args":{"name":"mark/blade","parentId":"Mark","closed":true,"fill":"#1B4DFF",
+   "points":[{"x":120,"y":20},{"x":220,"y":120},{"x":120,"y":120}]}},
+ {"action":"canvas.group","args":{"ids":["mark/ring","mark/counter","mark/blade"],"name":"mark"}}
+]}
 ```
 
-⚠ **`<text>` inside an `svg` node does NOT render headlessly** — no system fonts are loaded.
-Wordmarks are real text nodes, or outlined paths. Never live `<text>` in the mark.
+Here R = 100: the counter is R/2, the blade's corners sit on the circle. Curves are
+`vector.create` points with `hIn`/`hOut` control points (absolute coordinates) placed where the
+construction says; a quarter-circle's handle sits 0.552·R from its anchor. A counter-form is a
+ground-colour shape layered on top; `vector.boolean` makes a true cut-out when an editor is open.
+Raw SVG (`type:"svg"`) is only for importing a mark the client already has.
+
+⚠ **Wordmarks are real text nodes, or outlined paths** — and `<text>` inside an imported `svg`
+node does NOT render headlessly (no system fonts are loaded).
 
 **Test the mark against these before going further. A mark that fails any of them is not done:**
 
@@ -93,7 +114,9 @@ good. If it does not work in flat black, the shape is wrong and the gradient is
 - ⚠ **A wordmark is always tracked tighter than body text.** At display size, `letterSpacing`
   −1 to −4. Then fix the specific pairs the font gets wrong (an uppercase A next to a V, a
   T next to a lowercase o).
-- **Lockups are a fixed set, not an invitation.** Ship exactly these and say so:
+- **For a full identity, define this fixed set.** For a concept, deliver the requested lockup
+  plus the mark-only and one-color forms needed for its smallest use. Additional lockups are
+  optional unless the brief asks for them:
 
 ```
 primary      mark + wordmark, horizontal    ← the default
@@ -225,11 +248,11 @@ Run `design-craft`'s studio pass, plus these identity-specific ones:
 ```
 □ Rendered the mark at 24px and LOOKED at it
 □ Mark works in flat black, flat white, and knocked out
-□ Every lockup has stated clear space and minimum size
+□ Every delivered lockup has stated clear space and minimum size
 □ Palette has a dark-ground variant and role sentences
 □ Type scale has NUMBERS, not just face names
-□ At least 4 real applications, at real proportions
-□ Misuse section exists
+□ Requested applications at real proportions (4–6 for a full identity; the requested surface for a concept)
+□ Misuse section exists for a full identity; a concise use note is enough for a logo concept
 □ Put the mark beside the competitor named in UNLIKE — still distinct?
 □ Can someone build a new asset from this board without asking a question?
 ```

package/skills/clearly-agent/SKILL.md

@@ -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
@@ -190,6 +190,19 @@ task changes a product's UI, the composition comes FIRST: build the screen and i
 `canvas.review` it, link it to the ticket (`work-link {ticketId, kind:"design", refKind:"composition",
 refId}`), then implement. `clearly-canvas` §0 has the details.
 
+No brand yet (`brand-tokens` answers `brand-not-found`) for a real company? Ask the person for their
+website rather than inventing a palette, then:
+
+1. `beehaven call brand-import '{"url":"theirsite.com","dryRun":true}'` — colours by role, faces, logos,
+   voice and shape, each with its reason in `provenance`. Tell the person what you read.
+2. Ask what to call the brand (`suggestedName` is what the site calls itself — a suggestion, not a default).
+3. `beehaven call brand-import '{"url":"theirsite.com","name":"<their answer>"}'` saves it (the read is
+   reused; the first brand becomes the workspace default). Without `name` nothing is saved:
+   `brand-name-required`.
+
+`brandId` + `apply:["colors","type"]` refreshes an existing brand as a new version instead. Licensed faces
+come back set in the closest free one — `faces` says which.
+
 ## When a write is refused
 
 `agent-denied-create` / `-update` / `-delete` mean your **capability matrix** said no. It covers the
@@ -203,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.
@@ -215,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,22 +20,34 @@ 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.
 
+Keep the requested scope. A landing concept with a logo needs its page layouts and a usable
+logo; add application boards or a full guideline system only when the brief calls for them.
+Read only relevant references. Save large tool responses once and print compact summaries.
+
 ## The studio bar — what "done" means, every time
 
 Load **`design-craft`** before any new visual work: grid, type scale, colour roles,
 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),
    type below the artboard's legible floor, missing media, text overflowing its box,
-   placeholder copy. Fix it. When it is deliberate, pass the check name or layer in
-   `ignore` and say why in the handoff.
+   placeholder copy. Fix it. For an intentional finding, use
+   `accept:[{check,ids:[node IDs],reason}]`. Accepted findings stay visible and return `look`.
+   Legacy `ignore` can suppress multiple checks and is not an unconditional pass.
 2. **Every `look` finding was looked at**: type-size and palette sprawl, near-miss
    alignment, copy against the trim, text over imagery. Act on it or say why not.
 3. **You inspected the rendered PNG** against design-craft's studio pass, covering what no
@@ -42,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
@@ -54,8 +73,9 @@ build from them — redrawing a button the library already has is how designs dr
 product they describe.
 
 ```sh
-beehaven call brand-tokens '{}'                                   # colours (light + dark), type roles, radius, logos, voice
-beehaven call component-list '{"query":"<brand or kind>"}'        # parts, with props, variants and the code they mirror
+beehaven call brand-tokens '{"compact":true}'                     # roles without repeated CSS/prose
+beehaven call brand-import '{"url":"theirsite.com","dryRun":true}' # no brand yet? read it off their website
+beehaven call component-list '{"query":"<kind>","compact":true}' # IDs, dimensions and prop names
 beehaven call component-instantiate '{"compositionId":"<id>","instances":[
   {"id":"<component>","x":96,"y":200,"variant":"Light"},
   {"id":"<component>","x":96,"y":280,"variant":"Light","props":{"label":"Save changes"}}]}'
@@ -68,8 +88,9 @@ beehaven call component-instantiate '{"compositionId":"<id>","instances":[
   `component-create` (or `{ fromCompositionId, nodeId }` to save one you drew).
 - Component node coordinates are relative to the component ROOT, even under an inner
   frame — the opposite of `canvas.create-node`, where x/y follow `parentId`.
-- If the workspace has a brand kit, it IS the system for the brief: use its roles, faces
-  and voice rather than inventing a palette. Change the brand itself only when asked.
+- For Clearly product UI, use its brand kit. For a separate client, use that client's kit
+  and supplied assets. A requested new client identity is scoped to that composition;
+  it does not change the workspace's default brand.
 
 **UX design before implementation.** When the work is a change to a product's UI, the
 composition is the design the code will answer to: show the real states (empty, loading,
@@ -103,10 +124,46 @@ can read and edit artifact records, while canvas-specific actions use the CLI.
 beehaven env
 beehaven connect home
 beehaven agent login <name> --label "Design <artifact>" --client cli
-beehaven call canvas-perceive '{"compositionId":"<id>","format":"json"}'
+beehaven call canvas-perceive '{"compositionId":"<id>","outline":true}'
 beehaven call canvas-catalog '{"query":"create-node"}'
 ```
 
+Read a canvas the way you read a repository: `canvas-perceive {outline:true}` is `tree` (artboards,
+sections, layer counts, first copy, EMPTY sections — a few hundred bytes); `{frame:"<id or name>"}`
+opens one frame like a file (its layers indented, positions relative to their parent);
+`{find:"Start free"}` is `grep` (copy, layer names or `#hex`, with each match's frame path). Use
+`format:"json"` only when you need every field of every node. Every `canvas-act` write returns
+`diagnostics` — a lint of the artboards it touched (text overflow, collisions, covered text,
+contrast) — treat them like compiler errors and fix them in the next batch. `canvas.review` is still
+the pixel check and the ticket gate.
+
+A canvas is planned like a git repository: its own plan board, a WORK TICKET for the request, and
+COMMITS — one ticket per coherent layer or section of a larger change.
+`design-start {title, brandId?}` makes a PRIVATE DRAFT canvas, bound to the brand, with its private
+plan board and the work ticket, and returns `{ compositionId, ticketId, ticketKey, boardId, brand }`.
+Same title again returns the same draft. Nothing is shared until it is filed:
+`design-file {compositionId, projectId | projectTitle}` moves the canvas — plan board and every
+ticket with it — into the project the person chose and sends the work ticket to in-review. Ask which
+project unless they named one; a close-but-different title answers `similar-projects` with
+candidates. Repeat-safe.
+Plan a larger change before drawing, the way you would split a big code change into commits:
+`design-plan {compositionId, commits: ["Grid, type and colour styles", "Nav", "Hero", …]}` (drafts
+and filed canvases alike) adds ordered commit tickets under the work ticket. `sections: true` uses
+the landing-page set (set up frames and styles, nav bar, hero, highlights, offer, story, call to
+action, footer, mobile, states); `phases: true` and a `brief` add the studio method (brief, research,
+structure, direction, design, review) — load the `design-process` skill. Order commits so each
+builds on the last and can be reviewed alone. Build ONE commit per canvas-act batch that ends with
+`canvas.review` of the artboard and carries
+`"ticket":{"id":"<key>","status":"done","resolution":"<what changed>"}` — it lands only if that
+review is clean or look; `result.ticket` says whether it did, and the ticket logs the canvas
+revision and the layers the commit changed. Auto-layout, gradients, shadows, drawing and placeholders:
+see "Technique" in [authoring.md](authoring.md).
+
+`composition-board-get {compositionId}` reads the plan back. `design-start` with a project, ticket or
+`phases` still sets up planned work directly (kept for one release).
+For an existing task, reuse its ticket/project. Check one unknown action with
+`beehaven explain <action>` or a filtered catalog; do not download the entire registry.
+
 Use the composition supplied by the user. If none is named, inspect recent titles and
 context; create a clearly titled composition for new work instead of modifying an
 arbitrary recent canvas. File shared work into its project.
@@ -161,8 +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
@@ -188,6 +248,10 @@ For a single page, establish the complete hierarchy before polishing small detai
 Use a batch for each coherent build or revision, with descriptive unique layer names.
 Parent content to its artboard. Inspect every operation result and rollback status.
 Save your builder and returned IDs so revisions are targeted and reproducible.
+Check `ignoredFields`, `rejectedFields`, `warnings`, `outcome` and `canvasChanges` as well as
+`ok/count`. `matched` is not `updated`. An unchanged or partly ignored request does not prove
+the intended edit happened. Read `composition-detail {includeScene:true}` from its top-level
+`nodes`; never treat a missing response field as an empty scene. Keep executed payloads immutable.
 
 ⚠ **Batch, never loop.** One `canvas-act` batch of hundreds of steps is one scene read,
 persisted every 50 steps, and the workspace stays responsive for everyone in it while it
@@ -225,6 +289,12 @@ It invokes `canvas.review` on one persisted snapshot and returns:
   type and palette sprawl, near-miss edges, trim crowding, text over imagery;
 - the placeholder/overflow audit, measured text fit, and a preview PNG.
 
+For several artboards, write their IDs/names as a JSON array and use:
+`node <skill-directory>/review.mjs --many <composition-id> <ids.json> <output-directory>`.
+This uses `canvas.review-many`: one scene read, separate findings per artboard and compact
+preview handles. Review only artboards changed since their verified snapshot. The helper versions
+existing output paths so before/after evidence is retained.
+
 The helper prints the verdict and every finding. Work until the verdict is `clean` or
 `look`, as described in the studio bar above. If the installed worker lacks `canvas.review`,
 use a real frame ID with `--perceive` for a preview-only check and run the text measurement
@@ -232,9 +302,16 @@ and audit separately. A failed or missing render means visual verification is in
 
 ```sh
 # A deliberate finding — say why in the handoff:
-beehaven call canvas-act '{"compositionId":"<id>","action":"canvas.review","args":{"ids":["<frame>"],"ignore":["text-over-image"]}}'
+beehaven call canvas-act '{"compositionId":"<id>","action":"canvas.review","args":{"ids":["<frame>"],"accept":[{"check":"text-over-image","ids":["<text-id>","<image-id>"],"reason":"Intentional type over this photograph; rendered contrast was inspected."}]}}'
 ```
 
+Asset storage is a reference-aware pipeline: an SVG may have `svgRef` instead of inline markup.
+Do not shrink or recreate it just because the inline field is absent. Replace it with
+`canvas.update-nodes {ids, patch:{svg:<complete markup>}}`; references are managed by the action.
+Use `canvas.fonts` before choosing an unfamiliar family/weight. Fallback metrics are not exact.
+Use `canvas.editor-state {requireLive:true,includePixels:true}` to verify the responding editor.
+An agent camera and a navigation delivery count do not prove the person's view was framed.
+
 Inspect the actual image and identify concrete defects, not generic praise:
 
 | Lens | What to judge |

package/skills/clearly-canvas/authoring.md

@@ -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 }));
 ```
@@ -49,8 +53,21 @@ do not blindly resend only skipped operations. Mixed live/headless actions may h
 different rollback behavior. Use deterministic layer names and returned IDs to avoid
 duplicate content during retries.
 
+Also check ignored/rejected fields, warnings, mutation outcome and actual changed IDs. A matched
+node or `ok:true` receipt alone is not proof of an update. The bundled `assertReceipt` helper can
+reject partial drops; `requireChange:true` rejects an unexpected no-op. A deliberate replay may
+be unchanged and should reuse its previous evidence instead of recreating nodes.
+Keep executed payloads and returned-ID manifests separate from regenerated plans.
+
 ## Node shape and coordinates
 
+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.
@@ -71,12 +88,27 @@ Create normalizes hex colours; raw stored scenes use RGBA arrays in 0..1.
   moves/resizes use the catalog's frame/arrangement/scale actions; do not assume a patch
   reflows children.
 - Build backgrounds before foregrounds. Use `canvas.order` to change stacking.
+
+For create/update geometry, `coordinateSpace:"world"` or `"parent"` makes the intent explicit.
+Default behavior remains compatible with the rules above. Receipts include normalized world
+bounds and parent offsets where available. Template coordinates remain relative to their root.
+An SVG's bytes may be stored in `svgRef` once it exceeds the inline limit; this is valid artwork,
+not a missing node. Replacing `svg` clears and rebuilds its reference automatically. Never patch
+`svgRef` manually or guess its storage URL. Image `fit` is explicitly `contain` or `cover`.
 - Name nodes uniquely; use returned IDs where names collide. Parent content to its
   frame so movement, selection, clipping and reviews can treat it as one artifact.
 - Give an intended stroke both `stroke` and `strokeWidth`. Zero explicitly removes it.
 
 ## 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
@@ -86,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,
@@ -106,8 +138,27 @@ and tokens when relevant. Constraints reflow children on frame resize; they do n
 a static canvas into a responsive website. Design explicit mobile artboards when the
 deliverable requires them, with content order and hierarchy reconsidered for the width.
 
+## Technique
+
+- 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, 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. 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,