beehaven 0.8.24 → 0.8.29

package/dist/relay-presets.js

@@ -67,9 +67,8 @@ export function resolveRelaySelection(cfg) {
  *   `https://localhost:3000` (canvas.ts's `--dev` branch). They are not interchangeable: the apex
  *   301s to www, so the apex spelling handed people a link with a redirect in it.
  *
- * ⚠ STAGING RETURNS THE PRODUCTION SITE, AND THAT IS CORRECT. The frontend is prod-only — the
- * `staging.clearly-sh.pages.dev` alias is retired (CLAUDE.md) — so the staging worker's app really
- * is `www.clearly.sh`. Inventing a `staging.clearly.sh` here would be the dead-link bug again.
+ * Staging uses the local HTTPS frontend (Clearly AGENTS.md, 2026-10-08). Its workspace IDs
+ * belong to staging and must never be linked into the production frontend.
  *
  * ⚠ `custom` RETURNS undefined, DELIBERATELY. A custom relay says nothing about where its frontend
  * is, and guessing production for it is how you hand someone a link into the wrong deployment.
@@ -78,10 +77,10 @@ export function resolveRelaySelection(cfg) {
 export function appOriginForEnv(envName) {
     switch (envName) {
         case 'prod':
-        case 'staging':
             return 'https://www.clearly.sh';
         // `npm run dev` is `next dev --experimental-https`, so the local app is HTTPS, not HTTP.
         case 'dev':
+        case 'staging':
             return 'https://localhost:3000';
         default:
             return undefined;

package/dist/setup-relay.js

@@ -1,148 +1,28 @@
 #!/usr/bin/env node
 // ============================================================================
 // Beehaven Office - Relay Setup (Login)
-// Browser-based OAuth login flow for Clearly account
+// The daemon's interactive sign-in fallback, and logout.
 // ============================================================================
-import http from 'http';
-import crypto from 'crypto';
-import { createInterface } from 'readline';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, chmodSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import { spawnSync } from 'child_process';
 import { Relay, CLEARLY_RELAY_URL } from './relay.js';
-import { resolveRelaySelection } from './relay-presets.js';
 import { SESSION_KEYCHAIN_ACCOUNTS, KEYCHAIN_SERVICE } from './keychain.js';
-import { withUtm } from './utm.js';
 const CONFIG_DIR = join(homedir(), '.beehaven');
 const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
-const AUTH_BASE_URL = 'https://clearly.sh/auth/beehaven';
-const LOGIN_TIMEOUT_MS = 120_000; // 2 minutes
 /**
- * The raw config, for questions that must be answered BEFORE a token exists.
- * `Relay.loadConfig()` returns null without one, which is the state a first login is in.
+ * The daemon calls this when it starts interactively with no token, or when its session has
+ * expired (daemon.ts). It then re-reads the config, so all it needs is credentials on disk.
+ *
+ * ⚠⚠ AWO-224 — THIS USED TO BE A SECOND, DIFFERENT SIGN-IN. It opened
+ * `https://www.clearly.sh/auth/beehaven?callback=…`, waited for a single `token` and wrote its own
+ * config. The web app no longer serves that route (404 on prod and, via the apex redirect, the
+ * same 404), so the fallback opened a dead page and timed out after two minutes. It now runs the
+ * exact flow `beehaven login` runs (`browser-login.ts`: `/cli/auth`, the keychain idToken slot
+ * the daemon reads, both dial-target keys) and nothing else — it must NOT restart the daemon,
+ * because it runs inside it.
  */
-function readConfigFile() {
-    if (!existsSync(CONFIG_FILE))
-        return {};
-    try {
-        return JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
-    }
-    catch {
-        return {};
-    }
-}
-function saveRelayConfig(token, endpoint) {
-    mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
-    let existing = {};
-    if (existsSync(CONFIG_FILE)) {
-        try {
-            existing = JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
-        }
-        catch (err) {
-            console.warn(`[config] Failed to parse ${CONFIG_FILE}:`, err.message);
-        }
-    }
-    existing.token = token;
-    // ⚠ BOTH KEYS, as `beehaven env` writes them — `endpoint` is dialled, `relayUrl` is the alias
-    // other surfaces read. Updating one leaves the other naming a different environment.
-    existing.endpoint = endpoint;
-    existing.relayUrl = endpoint;
-    existing.tier = 'connected';
-    writeFileSync(CONFIG_FILE, JSON.stringify(existing, null, 2));
-    chmodSync(CONFIG_FILE, 0o600);
-}
-function prompt(question) {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise((resolve) => {
-        rl.question(question, (answer) => {
-            rl.close();
-            resolve(answer.trim());
-        });
-    });
-}
-/**
- * Start a local HTTP server on a random port to receive the OAuth callback.
- * Returns a promise for the token, plus helpers to get the port and close.
- */
-function startCallbackServer() {
-    let resolveToken;
-    let rejectToken;
-    let serverRef;
-    let settled = false;
-    const oauthState = crypto.randomBytes(32).toString('hex');
-    const promise = new Promise((resolve, reject) => {
-        resolveToken = resolve;
-        rejectToken = reject;
-        serverRef = http.createServer((req, res) => {
-            if (settled)
-                return;
-            const url = new URL(req.url, `http://localhost`);
-            if (url.pathname === '/callback') {
-                // Validate OAuth state parameter to prevent CSRF (skip if server doesn't echo it back yet)
-                const returnedState = url.searchParams.get('state');
-                if (returnedState && returnedState !== oauthState) {
-                    res.writeHead(403, { 'Content-Type': 'text/html' });
-                    res.end('<!DOCTYPE html><html><body><h1>Invalid state parameter</h1></body></html>');
-                    return;
-                }
-                const token = url.searchParams.get('token');
-                if (token) {
-                    settled = true;
-                    res.writeHead(200, { 'Content-Type': 'text/html' });
-                    res.end([
-                        '<!DOCTYPE html><html><head>',
-                        '<meta charset="utf-8">',
-                        '<title>Beehaven - Logged In</title>',
-                        '<style>',
-                        'body{font-family:system-ui,-apple-system,sans-serif;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0;background:#fef9ef}',
-                        '.card{text-align:center;padding:48px;border-radius:16px;background:white;box-shadow:0 2px 12px rgba(0,0,0,0.08)}',
-                        'h1{margin:0 0 8px;font-size:24px}',
-                        'p{margin:0;color:#666;font-size:15px}',
-                        '.bee{font-size:48px;margin-bottom:16px}',
-                        '</style>',
-                        '</head><body>',
-                        '<div class="card">',
-                        '<div class="bee">&#x1F41D;</div>',
-                        '<h1>Logged in!</h1>',
-                        '<p>You can close this tab and return to your terminal.</p>',
-                        '</div>',
-                        '</body></html>',
-                    ].join(''));
-                    serverRef.close();
-                    resolve(token);
-                }
-                else {
-                    res.writeHead(400, { 'Content-Type': 'text/html' });
-                    res.end('<!DOCTYPE html><html><body><h1>Missing token</h1></body></html>');
-                }
-            }
-            else {
-                res.writeHead(404);
-                res.end();
-            }
-        });
-        serverRef.listen(0, '127.0.0.1');
-        // Timeout after 2 minutes
-        const timer = setTimeout(() => {
-            if (!settled) {
-                settled = true;
-                serverRef.close();
-                reject(new Error('Login timed out after 2 minutes.'));
-            }
-        }, LOGIN_TIMEOUT_MS);
-        serverRef.on('close', () => clearTimeout(timer));
-    });
-    return {
-        promise,
-        getPort: () => serverRef.address()?.port || 0,
-        close: () => {
-            settled = true;
-            serverRef?.close();
-        },
-        state: oauthState,
-    };
-}
 export async function login() {
     console.log('');
     console.log('  Clearly account required to use Beehaven.');
@@ -165,114 +45,19 @@ export async function login() {
         console.log('  Session expired. Please log in again.');
         console.log('');
     }
-    // Start local callback server
-    const callbackServer = startCallbackServer();
-    // Small delay to let server bind
-    await new Promise((r) => setTimeout(r, 100));
-    const port = callbackServer.getPort();
-    if (!port) {
-        console.log('  Failed to start auth server.');
-        callbackServer.close();
-        return false;
-    }
-    const callbackUrl = `http://localhost:${port}/callback`;
-    const authUrl = withUtm(`${AUTH_BASE_URL}?callback=${encodeURIComponent(callbackUrl)}&state=${callbackServer.state}`);
-    // Try to open browser
-    let browserOpened = false;
-    try {
-        const openModule = await import('open');
-        await openModule.default(authUrl);
-        browserOpened = true;
-    }
-    catch {
-        browserOpened = false;
-    }
-    if (browserOpened) {
-        console.log('  Opening browser to sign in with Google...');
-        console.log('');
-        console.log('  Waiting for login... (press Ctrl+C to cancel)');
-    }
-    else {
-        // Fallback: show URL and offer manual token paste
-        console.log('  Could not open browser. Sign in manually:');
-        console.log('');
-        console.log(`  1. Open: ${authUrl}`);
-        console.log('  2. Sign in with Google');
-        console.log('');
-        console.log('  Waiting for login callback...');
-        console.log('  Or paste your relay token below:');
-        console.log('');
-        // Race: callback server vs manual token paste
-        const manualToken = prompt('  Relay token: ').then((token) => {
-            if (token) {
-                callbackServer.close();
-                return token;
-            }
-            return null;
-        });
-        try {
-            const token = await Promise.race([
-                callbackServer.promise,
-                manualToken.then((t) => {
-                    if (t)
-                        return t;
-                    return new Promise(() => { });
-                }),
-            ]);
-            if (token) {
-                return await verifyAndSave(token);
-            }
-        }
-        catch (err) {
-            console.log(`  ${err.message}`);
-            return false;
-        }
-    }
-    // Wait for callback
     try {
-        const token = await callbackServer.promise;
-        return await verifyAndSave(token);
-    }
-    catch (err) {
-        console.log(`  ${err.message}`);
-        return false;
-    }
-}
-async function verifyAndSave(token) {
-    // Validate token format before sending to server
-    if (!token || !/^[a-zA-Z0-9_\-.]{20,}$/.test(token)) {
-        console.log('  Invalid token format.');
-        return false;
-    }
-    console.log('');
-    console.log('  Verifying...');
-    const relay = new Relay();
-    /**
-     * ⚠⚠ THE ACTIVE RELAY, NOT A HARDCODED PROD CONSTANT. Both of these were `CLEARLY_RELAY_URL`, so
-     * a staging or dev user who signed in here was VERIFIED against prod and then had `endpoint`
-     * OVERWRITTEN to prod — silently moving them to another environment as a side effect of logging
-     * in. `beehaven env staging` writes the target; a login must honour it, never redefine it.
-     *
-     * ⚠ Read from the file rather than `Relay.loadConfig()`: that returns null without a token, which
-     * is exactly the state a first login is in. `resolveRelaySelection` defaults to prod when the
-     * config names nothing, so the no-config case is unchanged.
-     */
-    const dialUrl = resolveRelaySelection(readConfigFile()).url;
-    const profile = await relay.verifyToken(token, dialUrl);
-    if (profile) {
-        saveRelayConfig(token, dialUrl);
-        if (profile.displayName) {
-            console.log(`  Logged in as ${profile.displayName} (${profile.subscriptionPlan})`);
-        }
-        else {
-            console.log('  Logged in.');
-        }
+        // ⚠ Imported lazily: the Mac app loads this file for `logout` alone and should not pull in
+        // the sign-in flow's dependencies to do it.
+        const { browserLogin } = await import('./browser-login.js');
+        const who = await browserLogin();
+        console.log(`  Logged in as ${who.email ?? who.userId}.`);
         console.log('  Config saved to ~/.beehaven/config.json');
         console.log('');
         return true;
     }
-    else {
-        console.log('  Token verification failed. Please try again.');
+    catch (err) {
+        console.log(`  ${err?.message ?? err}`);
+        console.log('  Run `beehaven login`, then start again.');
         console.log('');
         return false;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beehaven",
-  "version": "0.8.24",
+  "version": "0.8.29",
   "description": "Beehaven CLI — command your Clearly workspace, agents, and canvas from the terminal",
   "private": false,
   "type": "module",

package/skills/beehaven-cli/SKILL.md

@@ -25,6 +25,18 @@ beehaven cd home                   # back to the default workspace
 beehaven disconnect                # end the session
 ```
 
+Start discovery narrowly: `beehaven explain <action>` gives one schema; `beehaven actions
+--search <term>` or `--category <name>` bounds the inventory. The default inventory is compact;
+`--verbose` or `--format full --json` requests full detail. Save large JSON once and print a
+small summary rather than repeating a call after output truncation.
+
+For ticket text search use `ticket-list {text:"…",projectId?,fields?,limit?}` (`query` and `q`
+are aliases). For a design setup, `design-start {title,projectId?,boardId?,idempotencyKey}` creates or
+resumes the linked artifacts using the normal permissions. Preserve idempotencyKey across retries;
+requestId is reserved by the transport.
+For supported canvas mutations inspect actual `updated` IDs, `outcome`, ignored/rejected fields
+and warnings. A navigation request reaching a socket is not a verified editor display.
+
 Once `cd`'d, **every** verb auto-routes to that target: `actions`, `call`, `sql`, `ls`, `cat`, `tree`, `grep`, `watch`, `logs`, `workspace`, `ask`. Switch by `cd`-ing again.
 
 ```bash

package/skills/brand-identity/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: brand-identity
 description: >-
-  Build a complete brand identity on a Clearly canvas the way a studio does —
+  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 +13,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.
@@ -93,7 +97,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 +231,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

@@ -75,6 +75,17 @@ the admitted agent in the workspace, and soul reads/updates report whether the d
 wearing the drawing or a preset. If the capability line is absent, it is disabled for that
 deployment; the existing companion and presets remain available.
 
+## End with a handoff
+
+```bash
+beehaven agent handoff "what you did · what is next · anything blocked"
+```
+
+The handoff is the note your next login, or the next agent you hand the work to, reads first,
+under **Last time you were here**. Write it for a colleague who has none of your context: what changed,
+where it is (ticket keys, document titles), what is next and what is blocked. It ends the work session
+and keeps your identity bound. Without one, the next brief can show only the session's label and counts.
+
 ⚠ **Do not call `agent-login` immediately after `beehaven agent login`.** The RPC is an alias of
 `agent-session-start`; doing both creates two sessions. Call it directly only when deliberately starting
 or resuming an additional workspace session.
@@ -118,8 +129,8 @@ item queued. Every comment/description write returns `mentions`, `agentsQueued`
 `beehaven comment <ref>` takes any id, key or exact title and the surface's anchor:
 `--quote` (document passage) · `--slide 3` (deck, required) · `--cell B4` / `--cell "Tab!B4"` (sheet) ·
 `--column "In review"` (board) · `--pin <id>` or `--x/--y` (canvas) · `--reply <id>`. An anchor a
-surface cannot carry is **refused**, never dropped. Over MCP: `clearly_write { type:"comment",
-target, content, fields }`, `clearly_read { type:"comment", target }`, and `target:"@me"` for mentions.
+surface cannot carry is **refused**, never dropped. Over MCP: `clearly_comment { target, content,
+fields }`, `clearly_read { type:"comment", target }`, and `target:"@me"` for mentions.
 
 ## Inbox — people and agents message you, and you message them
 
@@ -140,7 +151,7 @@ beehaven inbox who                               # every handle you can put in <
 
 Over MCP, `type: "message"` on the same tools: `clearly_read { type: "message", target: "@inbox" }`
 lists your threads (`box`, `query`), `target: "@people"` lists who you can message, and a thread id
-opens it (marks read). `clearly_write { type: "message", fields: { to: ["ada"] }, content }` starts a
+opens it (marks read). `clearly_comment { type: "message", fields: { to: ["ada"] }, content }` starts a
 thread; with `target: <threadId>` it replies. `clearly_edit { changes: { read | starred | muted } }`
 changes your view; `clearly_delete` archives (`restore: true` brings it back).
 
@@ -179,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

package/skills/clearly-canvas/SKILL.md

@@ -22,6 +22,10 @@ stored. A rendered image you have inspected is the evidence for visual quality.
 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,
@@ -33,8 +37,9 @@ A composition is done when every requested artboard meets all four 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
@@ -54,8 +59,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 +74,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,
@@ -107,6 +114,33 @@ beehaven call canvas-perceive '{"compositionId":"<id>","format":"json"}'
 beehaven call canvas-catalog '{"query":"create-node"}'
 ```
 
+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 and SVG 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.
@@ -188,6 +222,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
@@ -195,6 +233,15 @@ runs. The same steps sent as hundreds of separate calls each re-read the whole s
 call fails with a dropped connection, read the scene (`composition-detail
 {id, includeScene:true}`) before retrying: the work may have landed.
 
+⚠ **One batch per canvas at a time.** A reply that times out ("outcome unknown") or drops does
+not stop the batch — it is still running on the workspace. Resending at once used to start a
+second, slow, unprotected batch and could half-apply both (CA-43). The workspace now queues a
+second writer behind the first and answers `code: "canvas-busy"` (with the running batch's
+progress) if it waits too long — nothing from that call was applied. Either way: read the scene,
+then send only what is missing. A ~1,100-step build takes about 40 s; the CLI waits 180 s by
+default and `--timeout <ms>` (or `BEEHAVEN_RPC_TIMEOUT_MS`) raises it. Never place component
+instances after a build whose reply you did not see.
+
 Keep review notes and status outside the delivered artwork. Use
 [communications.md](communications.md) only when posting those blocks is useful.
 
@@ -216,6 +263,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
@@ -223,9 +276,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 |