beehaven 0.8.29 → 0.8.34

package/dist/windows-hide.js

@@ -0,0 +1,77 @@
+/**
+ * windows-hide — no console windows flashing open on Windows (CAN2-56).
+ *
+ * ⚠⚠ WHY WINDOWS FLASHED. A Windows process with no console of its own — the detached daemon,
+ * or `beehaven` run by an agent or an app rather than in a terminal — that starts a CONSOLE
+ * program (cmd.exe for every `exec`/`execSync`, powershell, git, node, …) makes Windows create a
+ * brand-new console window for that child. It pops up and closes as the child exits: one flash per
+ * call, and the daemon makes calls on timers. Node prevents it per call with `windowsHide: true`;
+ * the CLI had ~140 child-process calls and one of them set it.
+ *
+ * ⚠ ONE CHOKEPOINT, NOT 140 CALL SITES. Imported FIRST by every entry point (`cli.ts`,
+ * `clearly.ts`, `daemon-entry.ts`), this wraps the `child_process` functions so `windowsHide`
+ * defaults to true for every caller in the process — this package, `@beehaven/core`, and any
+ * dependency — and `syncBuiltinESMExports()` makes ESM named imports (`import { spawn } …`) see
+ * the wrappers too. An explicit `windowsHide: false` is respected. Off Windows it does nothing.
+ *
+ * ⚠ `exec` / `execFile` carry `util.promisify.custom` (so `promisify(exec)` resolves
+ * `{ stdout, stderr }`). The wrappers forward it; without that, every `promisify(exec)` caller
+ * would silently start receiving a bare string.
+ */
+import { createRequire, syncBuiltinESMExports } from 'node:module';
+import { promisify } from 'node:util';
+const require = createRequire(import.meta.url);
+const MARK = Symbol.for('beehaven.windowsHide');
+/**
+ * A child_process call's arguments with `windowsHide: true` set, unless the caller chose a value.
+ * `takesArgv` = the second parameter may be an argv array (spawn, spawnSync, execFile,
+ * execFileSync, fork). Pure — exported for tests.
+ */
+export function withWindowsHide(args, takesArgv) {
+    const a = [...args];
+    for (let i = 1; i < a.length; i++) {
+        const v = a[i];
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            if (v.windowsHide === undefined)
+                a[i] = { ...v, windowsHide: true };
+            return a;
+        }
+    }
+    // No options object: it goes after the command (and its argv array), before any callback. An
+    // explicit `undefined`/`null` options slot is filled rather than shifted.
+    const at = takesArgv && Array.isArray(a[1]) ? 2 : 1;
+    if (at < a.length && (a[at] === undefined || a[at] === null))
+        a[at] = { windowsHide: true };
+    else
+        a.splice(at, 0, { windowsHide: true });
+    return a;
+}
+const WRAPPED = [
+    ['spawn', true], ['spawnSync', true], ['execFile', true], ['execFileSync', true], ['fork', true],
+    ['exec', false], ['execSync', false],
+];
+/** Wrap `child_process` once per process. Returns whether it is installed. `force` is for tests. */
+export function installWindowsHide(opts = {}) {
+    if (process.platform !== 'win32' && !opts.force)
+        return false;
+    const cp = require('node:child_process');
+    if (cp[MARK])
+        return true;
+    for (const [name, takesArgv] of WRAPPED) {
+        const orig = cp[name];
+        if (typeof orig !== 'function')
+            continue;
+        const wrapper = function (...args) {
+            return orig.apply(this, withWindowsHide(args, takesArgv));
+        };
+        const custom = orig[promisify.custom];
+        if (typeof custom === 'function') {
+            wrapper[promisify.custom] = (...args) => custom.apply(orig, withWindowsHide(args, takesArgv));
+        }
+        cp[name] = wrapper;
+    }
+    cp[MARK] = true;
+    syncBuiltinESMExports();
+    return true;
+}
+installWindowsHide();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beehaven",
-  "version": "0.8.29",
+  "version": "0.8.34",
   "description": "Beehaven CLI — command your Clearly workspace, agents, and canvas from the terminal",
   "private": false,
   "type": "module",
@@ -53,7 +53,7 @@
     }
   },
   "optionalDependencies": {
-    "better-sqlite3": "11.0.0",
+    "better-sqlite3": "13.0.3",
     "node-pty": "1.0.0",
     "open": "10.1.0"
   },

package/scripts/sync-skills.mjs

@@ -40,6 +40,12 @@ const SOURCES = {
   'codebase-map':   'apps/mcp-server/plugin/skills/codebase-map/SKILL.md',
   'clearly-workspace': 'apps/mcp-server/plugin/skills/clearly-workspace/SKILL.md',
   'clearly-agent':     'apps/mcp-server/plugin/skills/clearly-agent/SKILL.md',
+  // CAN2-57 — the rest of the plugin's skills: one set across plugin, CLI and Mac app.
+  'visualize':         'apps/mcp-server/plugin/skills/visualize/SKILL.md',
+  'sticker-pack':      'apps/mcp-server/plugin/skills/sticker-pack/SKILL.md',
+  'clearly-docs':      'apps/mcp-server/plugin/skills/clearly-docs/SKILL.md',
+  'clearly-init':      'apps/mcp-server/plugin/skills/clearly-init/SKILL.md',
+  'clearly-workflows': 'apps/mcp-server/plugin/skills/clearly-workflows/SKILL.md',
 };
 
 let missing = 0;

package/skills/agent-doodle-space/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-doodle-space
-description: Use an agent identity's Avatar Soul and durable Doodle Space. Trigger when someone says "draw my avatar", "change my expression", "make a doodle", or wants to inspect an agent's visual identity. Read the minted appearance before drawing; save durable art to a session composition. Requires AGENT_SOUL_SPACE and is separate from avatar-shop.
+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 an agent identity's Avatar Soul and durable Doodle Space. Trigger when someone says "draw my avatar", "change my expression", "make a doodle", or wants to inspect an agent's visual identity. Read the minted appearance before drawing; save durable art to a session composition. Requires AGENT_SOUL_SPACE and is separate from avatar-shop.
 ---
 
 # Agent Soul + Doodle Space

package/skills/agent-home/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-home
-description: Design and inhabit an agent-owned memory apartment on Clearly's canvas. Use when someone says "build my agent home", "make a room", "save a home memory", or "move the avatar". Arrange rooms, doors, windows, furniture, avatar position, memories, journals, and Home ads on a fixed 24px grid. Requires AGENT_SOUL_SPACE.
+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 inhabit an agent-owned memory apartment on Clearly's canvas. Use when someone says "build my agent home", "make a room", "save a home memory", or "move the avatar". Arrange rooms, doors, windows, furniture, avatar position, memories, journals, and Home ads on a fixed 24px grid. Requires AGENT_SOUL_SPACE.
 ---
 
 # Agent Home memory apartment

package/skills/brand-identity/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: brand-identity
 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 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
@@ -64,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:**
 

package/skills/clearly-agent/SKILL.md

@@ -1,18 +1,34 @@
 ---
 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
 
-## Select the workspace, then sign in once
+## Sign in once — this session is then you, in one workspace
 
 ```bash
-beehaven env
-beehaven connect home
-beehaven agent login <name> --label "what I am here to do" --client cli
+beehaven env                                   # staging or prod: the session remembers it
+beehaven agent login <name> --label "what I am here to do" --client cli [--workspace <ws>]
 ```
 
+After login **every** `beehaven` command in this session runs as `<name>`, in its workspace — no
+`--agent`, no export, nothing per call. The login prints the session, the agent, the workspace (by
+name) and the env. `--workspace` takes `home`, `workspace/<id>`, `team/<id>` or a bare 64-character
+id (`beehaven workspaces` lists them); without it a session starts where this identity last worked.
+
+**One session = one identity + one workspace + one env (AWO-394).** A session is a Claude/Codex/
+Gemini conversation, or a terminal tab. Each has its own:
+- workspace — `beehaven connect <ws>` moves THIS session only (and moves its work session there);
+  another agent, or another conversation signed in as the same name, stays where it is;
+- work session — a second login under the same name no longer ends the first one's;
+- env — if someone switches the daemon (`beehaven env prod`), calls from a staging session are
+  refused with the fix instead of landing in the other environment.
+
+Typed verbs (`ticket`, `sheet`, `slides`, `design`, `mention`, `trash`) follow the session's
+workspace exactly like `call` (AWO-393). A Shopify store is an operator target:
+`beehaven admin do shopifyStore/<id> <action> '<json>'` (platform admins).
+
 ## Personal workspace means a private layer, not another DO
 
 Every human and every agent in the selected workspace has a **personal workspace layer**: its own
@@ -38,13 +54,14 @@ steps. CI gets a real identity for one command: `beehaven agent login ci`.
 | 2 | `BEEHAVEN_AGENT=<name>` | a script, or another terminal |
 | 3 | the **scope binding** from `agent login` | this session, no flag needed |
 
-⚠ **The binding needs no cooperation.** `agent login` records the calling process's scope —
-`claude-<sessionId>`, `codex-…`, `gemini-…`, or `pid-<ppid>` for a non-TTY — on the identity. So
-two harness sessions are two agents concurrently with no env var, and **two agents on one scope is
-refused rather than guessed** (that can only happen if you logged in twice from one session).
+⚠ **The binding needs no cooperation.** `agent login` writes `~/.beehaven/sessions/<scope>.json` for
+the calling process's scope — `claude-<sessionId>`, `codex-…`, `gemini-…`, `term-<tab>` for a
+terminal tab that says which tab it is (macOS Terminal, iTerm2, Windows Terminal, tmux, kitty,
+WezTerm), or `pid-<ppid>` for a non-TTY. Two harness sessions or two tabs are two agents
+concurrently with no env var; logging in twice from one session means the second login.
 
-⚠ The workspace **cursor** is scoped the same way, so two identities can be `connect`ed to
-different workspaces at once. What is NOT concurrent: one daemon, one relay, one `beehaven env`.
+⚠ What is still machine-wide: one daemon, one relay, one `beehaven env` (sessions refuse a mismatch
+rather than follow it). `agent logout` ends this session only.
 
 ## Identity ≠ session
 
@@ -216,6 +233,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 +250,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,26 @@ 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: build every row, stack, card and grid AS an auto-layout frame from the start: frame.create (or canvas.create-node type "frame") { name, parentId, autoLayout: { direction: "h" | "v" | "grid", gap, padding, align, justify, hug } }, then create its children with parentId and NO x/y; they flow in creation order and the frame stays live. canvas.auto-layout { id, … } changes the settings; with only { id } it converts a hand-positioned frame, reading direction, gap and padding off the children so nothing moves, and review reports any stack left positioned by hand. 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".
+- VARIABLES: use the brand by name, not by value: in canvas.create-node and frame.create write fill: "brand/accent", stroke: "brand/line", radius: "brand/radius", autoLayout: { gap: "brand/spacing", padding: "brand/spacing" }, and on text textStyle: "brand/heading" (or "brand/body"), which sets family, weight, size, line height and letter spacing together from the brand's type role. Each binds, so the layer follows the canvas brand and a switch of brand; "var/<name>" reaches a workspace variable (text: "var/product/name", visible: "var/flags/promo"). A dark version of a frame is variableModes: { brand: "dark" } on it, not new colours. canvas.variable binds existing layers (op "bind", "apply-style", "set-mode"); op "list" shows every variable and style. A typed value detaches.
 - 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, d, fill or stroke, strokeWidth }: write d as SVG path data (M, C, Z), native editable points in far fewer tokens than points: [{ x, y, hIn?, hOut? }] (hIn/hOut are absolute control points); few anchors, smooth curves. It also takes 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. A new top-level artboard goes beside or below what scene already holds (or leave out both x and y), never at 0,0 over an existing one.
+- 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,