beehaven 0.8.22 → 0.8.24

package/dist/build-channel.js

@@ -53,9 +53,9 @@ export const PUBLIC_BUILD = true;
  * ⚠ REWRITTEN IN `dist/` AT BUILD TIME, like `PUBLIC_BUILD`. `unstamped` is what a source checkout
  * carries and what `tsx`/`vitest` see, and it is honest: nothing has stamped them.
  */
-export const BUILD_SHA = '49efa8cde4ed-dirty';
+export const BUILD_SHA = '150d0d2c336a';
 /** ISO-8601 minute precision, UTC. Rewritten in `dist/` by `scripts/stamp-build-channel.mjs`. */
-export const BUILD_TIME = '2026-09-30T19:01Z';
+export const BUILD_TIME = '2026-10-02T08:34Z';
 /**
  * The build identity as one short string, for `--version`.
  *

package/dist/cli.js

@@ -309,7 +309,8 @@ ${DEV_ONLY_HELP ? `  PROJECT — build your own Durable Object backend  (HIVE_DE
     app setup <name>                       Re-run a hive's setup script
     install <pkg>                          Shorthand for "app install <pkg>"
     skills install                         Teach every agent about Clearly —
-                                           writes the shipped SKILL.md files
+                                           writes the shipped SKILL.md files + the
+                                           AGENTS.md / GEMINI.md / CLAUDE.md block
     skills <list|sync|remove>              Manage skills paired with installed hives
 
     Deep dive:  beehaven help hives        Mental model + install/connect/call loop
@@ -437,7 +438,9 @@ ${DEV_ONLY_HELP ? `
   ACCOUNT
   ─────────────────────────────────────────────────────────────────────
 
-    login                                  Sign in (browser) — primary flow
+    login                                  Sign in (browser) — primary flow; also teaches
+                                           your agents (skills + AGENTS.md block;
+                                           --no-agent-setup to skip)
     login --email <e> --password <p>       Self-hosted email/password (set BEEHAVEN_API_URL)
     logout                                 Clear local credentials + keychain
     signup                                 Open sign-up page in browser
@@ -1299,7 +1302,25 @@ async function run() {
         await shorthandCmd(rawVerb, process.argv.slice(3), {});
         return;
     }
+    /**
+     * ⚠ `--x -3000` IS A NEGATIVE COORDINATE, NOT A FLAG. node's parseArgs reads any value starting
+     * with a dash as a missing argument and dies with "Option '--x' argument is ambiguous" — which is
+     * how `beehaven canvas add-image … --x -3000` failed (CDS-25). Join a negative NUMBER onto the
+     * coordinate/size flag before it; nothing else is rewritten.
+     */
+    const NUMERIC_FLAGS = new Set(['--x', '--y', '--width', '--height', '--w', '--h', '--dx', '--dy']);
+    const argv = [];
+    for (let i = 2; i < process.argv.length; i++) {
+        const a = process.argv[i], b = process.argv[i + 1];
+        if (NUMERIC_FLAGS.has(a) && typeof b === 'string' && /^-\d+(\.\d+)?$/.test(b)) {
+            argv.push(`${a}=${b}`);
+            i++;
+            continue;
+        }
+        argv.push(a);
+    }
     const { values, positionals } = parseArgs({
+        args: argv,
         allowPositionals: true,
         options: {
             project: { type: 'string' },
@@ -1492,6 +1513,7 @@ async function run() {
             // Paired Claude Code skill install policy (see commands/skills.ts)
             'with-skills': { type: 'boolean', default: false },
             'no-skills': { type: 'boolean', default: false },
+            'no-agent-setup': { type: 'boolean', default: false },
             // ── mobile-install metadata for `beehaven teleport <build>.ipa --composition <id>`
             //    (see commands/workspace.ts — wantMobileInstall branch).
             //    Future: parse Info.plist / AndroidManifest.xml automatically
@@ -2945,11 +2967,24 @@ async function run() {
             // omitted BEEHAVEN_HEADLESS=1, so the "restarted" daemon hit the
             // parent-death watchdog and exited ~3s later — restart reported a PID and
             // left you with nothing running. See spawnStandaloneDaemon's comment.
-            const { spawnStandaloneDaemon } = await import('./commands/daemon-cmd.js');
+            const { spawnStandaloneDaemon, waitForServingDaemon } = await import('./commands/daemon-cmd.js');
             const { resolveRelayUrlForDaemon } = await import('./daemon.js');
             const relayUrl = resolveRelayUrlForDaemon();
             const pid = spawnStandaloneDaemon(values);
-            console.log(`  Daemon restarted (PID ${pid}).`);
+            // ⚠ Report the daemon that is ACTUALLY serving — see waitForServingDaemon.
+            const served = await waitForServingDaemon(pid);
+            if (served.ready && served.spawnedAlive) {
+                console.log(`  Daemon restarted (PID ${pid}). Ready — socket answering.`);
+            }
+            else if (served.ready) {
+                console.log(`  Another supervisor (the Clearly app) restarted the daemon first — PID ${served.livePids.join(', ')} is serving. Ready.`);
+            }
+            else {
+                console.error(served.livePids.length
+                    ? `  Daemon process is up (PID ${served.livePids.join(', ')}) but its socket is not answering yet. 'beehaven status' shows state.`
+                    : `  The daemon did not stay up (spawned PID ${pid} exited). Run 'beehaven start --headless', or reopen the Clearly app.`);
+                process.exitCode = 1;
+            }
             console.log(`  Relay: ${color.dim(relayUrl)}`);
             break;
         }
@@ -3303,6 +3338,31 @@ async function run() {
              */
             console.log(`  ${color.green('✓')} Connected — your new sign-in is live`);
             console.log(`    Background service ${wasRunning ? 'restarted' : 'started'} (PID ${pid})`);
+            /**
+             * ⚠⚠ TEACH THE AGENTS AS PART OF SIGNING IN (PPO-190). "Install the CLI, log in, and your
+             * agents handle the rest" needs the agents to KNOW about the CLI — the skills plus the
+             * instruction block in ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md and a pointer in
+             * ~/.claude/CLAUDE.md. That used to be a separate `beehaven skills install` the installer's
+             * closing text asked for, and a step people skip is a step that did not happen.
+             *
+             * ⚠ Idempotent and non-fatal: unchanged files are not rewritten, symlinked files are left
+             * alone, and a failure here never fails the sign-in. Opt out with `--no-agent-setup` or
+             * BEEHAVEN_NO_AGENT_SETUP=1; undo with `beehaven skills uninstall`.
+             */
+            if (!values['no-agent-setup'] && process.env.BEEHAVEN_NO_AGENT_SETUP !== '1') {
+                try {
+                    const { installAgentSkills } = await import('./commands/agent-skills.js');
+                    const { installAgentInstructions } = await import('./commands/agent-instructions.js');
+                    const sk = installAgentSkills();
+                    const ins = installAgentInstructions();
+                    const changed = [...sk.steps, ...ins.steps].filter((x) => /=(written|updated)$/.test(x)).length;
+                    console.log(`  ${color.green('✓')} Your agents know about Clearly${changed ? '' : color.dim(' (already set up)')}`);
+                    console.log(color.dim('    Skills + instructions for Claude Code, Codex, Gemini and pi · undo: beehaven skills uninstall'));
+                }
+                catch (err) {
+                    console.log(color.dim(`    Agent setup skipped: ${err?.message ?? err} — run: beehaven skills install`));
+                }
+            }
             console.log('');
             break;
         }
@@ -3897,7 +3957,13 @@ complete -F _beehaven_completions beehaven`);
              */
             if (sub === 'install' || sub === 'uninstall') {
                 const { installAgentSkills, removeAgentSkills, AGENT_SKILL_DIRS } = await import('./commands/agent-skills.js');
+                const { installAgentInstructions, removeAgentInstructions } = await import('./commands/agent-instructions.js');
                 const r = sub === 'install' ? installAgentSkills() : removeAgentSkills();
+                // ⚠ The instruction block travels with the skills (PPO-190) — a skill is only OFFERED;
+                // the block is what makes an agent reach for `beehaven` at all.
+                const ins = sub === 'install' ? installAgentInstructions() : removeAgentInstructions();
+                r.steps.push(...ins.steps);
+                r.warnings.push(...ins.warnings);
                 const wrote = r.steps.filter((x) => /=(written|updated)$/.test(x)).length;
                 const current = r.steps.filter((x) => x.endsWith('=current')).length;
                 const removed = r.steps.filter((x) => x.endsWith('=removed')).length;

package/dist/commands/agent-instructions.js

@@ -0,0 +1,182 @@
+/**
+ * agent-instructions — the "use the beehaven CLI" block in each agent's GLOBAL instruction file.
+ *
+ * ⚠⚠ THE MISSING HALF OF "install the CLI, log in, and your agents handle the rest" (PPO-190).
+ * `skills install` put SKILL.md files on disk, but a skill is only OFFERED to a model when its
+ * description matches. The instruction block is what makes an agent reach for `beehaven` at all
+ * when the user says "put this on my board". The Mac app has written it on every launch
+ * (`apps/electron/electron/agent-skills-installer.ts`); the CLI never did, so a CLI-only user's
+ * Codex and Gemini had skills they never used.
+ *
+ * ⚠⚠ BYTE-IDENTICAL TO THE MAC APP'S BLOCK, MARKER LINE INCLUDED. Both writers splice between the
+ * same BLOCK_START / BLOCK_END. If their text differed by one character, a machine with both would
+ * rewrite the file on every app launch and every CLI install, each undoing the other. One text
+ * means both converge and either uninstaller removes it. `agentInstructionParity.test.mjs` in the
+ * root repo pins the two copies together.
+ *
+ * ⚠ CLAUDE GETS THE SHORT POINTER — `~/.claude/CLAUDE.md` is prepended to every Claude Code
+ * session in every repository, so it carries a pointer to the skills, not a manual. Same rule as
+ * the Mac app; see its note on `AGENT_INSTRUCTION_FILES`.
+ *
+ * ⚠ ONLY OUR BLOCK IS EVER TOUCHED. Text around it is preserved byte for byte; a file with no
+ * block gets one appended; removal deletes the block and nothing else.
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+const MANAGED_MARKER = 'managed-by: clearly-mac-app';
+export const BLOCK_START = '<!-- clearly:beehaven-cli:start -->';
+export const BLOCK_END = '<!-- clearly:beehaven-cli:end -->';
+/** Resolved at call time so tests can point HOME at a temp dir. */
+export function agentInstructionFiles(home = os.homedir()) {
+    return [
+        { agent: 'codex', file: path.join(home, '.codex', 'AGENTS.md') },
+        { agent: 'gemini', file: path.join(home, '.gemini', 'GEMINI.md') },
+        { agent: 'claude', file: path.join(home, '.claude', 'CLAUDE.md') },
+    ];
+}
+/** The managed block appended to AGENTS.md / GEMINI.md. Keep identical to the Mac app's. */
+export function instructionBlock() {
+    return [
+        BLOCK_START,
+        `<!-- ${MANAGED_MARKER}. Edits inside this block are overwritten on app launch; edit outside it. -->`,
+        '',
+        '## Clearly — drive it with the `beehaven` CLI',
+        '',
+        'Clearly (clearly.sh) is a workspace — documents, projects, boards, tickets and a design',
+        'canvas. Reach it from the shell with the `beehaven` CLI, NOT an HTTP API you construct.',
+        '',
+        '⚠ SIGN IN FIRST. Every call is attributed to an agent identity, and without one the CLI',
+        'refuses. `login` MINTS the name if it does not exist yet, and binds this terminal:',
+        '',
+        '```sh',
+        'beehaven agent login <your-name>   # required — mints + binds, once per session',
+        'beehaven connect home              # target the personal workspace',
+        'beehaven actions                   # list every action available there',
+        'beehaven call <action> \'{...}\'',
+        '```',
+        '',
+        'Read the full skills before driving it — they carry the exact verbs and node shapes:',
+        '',
+        '- `~/.<agent>/skills/clearly-agent/SKILL.md` — **read this first**: identity, sessions, your brief',
+        '- `~/.<agent>/skills/beehaven-cli/SKILL.md` — connect / call / sql / logs, the daemon',
+        '- `~/.<agent>/skills/clearly-workspace/SKILL.md` — audit what a workspace holds and who made it',
+        '- `~/.<agent>/skills/clearly-canvas/SKILL.md` — build + perceive a canvas, comm blocks, code diffs',
+        '- `~/.<agent>/skills/design-craft/SKILL.md` — **load before any visual work**: grid, type, colour, the studio pass',
+        '- `~/.<agent>/skills/layout-systems/SKILL.md` — grids and systems across many artboards',
+        '- `~/.<agent>/skills/pair-on-canvas/SKILL.md` — drive a coding task from a spec on the canvas',
+        '- `~/.<agent>/skills/codebase-map/SKILL.md` — draw a repo’s architecture on the canvas',
+        '',
+        'If a command reports the daemon is unreachable, `beehaven login` re-auths and',
+        '`beehaven start --headless` starts a daemon when the Mac app is not running.',
+        BLOCK_END,
+    ].join('\n');
+}
+/** The short form, for `~/.claude/CLAUDE.md`. Keep identical to the Mac app's `claudeBlock()`. */
+export function claudeBlock() {
+    return [
+        BLOCK_START,
+        `<!-- ${MANAGED_MARKER}. Edits inside this block are overwritten on app launch; edit outside it. -->`,
+        '',
+        '**Clearly workspace** — drive it from the shell with the `beehaven` CLI (documents, projects,',
+        'boards, tickets, canvas). Sign in once per session first: `beehaven agent login <name>` —',
+        'it mints the identity if new. Full detail is in the skills, `clearly-agent` first.',
+        BLOCK_END,
+    ].join('\n');
+}
+/** Insert or replace our block, leaving everything around it untouched. Pure. */
+export function upsertBlock(existing, block) {
+    const start = existing.indexOf(BLOCK_START);
+    const end = existing.indexOf(BLOCK_END);
+    if (start !== -1 && end !== -1 && end > start) {
+        return existing.slice(0, start) + block + existing.slice(end + BLOCK_END.length);
+    }
+    return existing.trim() ? `${existing.trimEnd()}\n\n${block}\n` : `${block}\n`;
+}
+/** Remove our block (and the blank line it was appended after). Pure. */
+export function stripBlock(existing) {
+    const start = existing.indexOf(BLOCK_START);
+    const end = existing.indexOf(BLOCK_END);
+    if (start === -1 || end === -1 || end < start)
+        return existing;
+    const before = existing.slice(0, start).replace(/\n{1,2}$/, '\n');
+    const after = existing.slice(end + BLOCK_END.length).replace(/^\n/, '');
+    const out = (before + after);
+    return out.trim() ? out : '';
+}
+/**
+ * Write the block into every agent's global instruction file. Idempotent: an unchanged file is
+ * reported `=current` and not rewritten.
+ *
+ * ⚠ A SYMLINKED INSTRUCTION FILE IS LEFT ALONE. People keep dotfiles in a repo and link them in;
+ * writing through the link would silently edit their checkout. Same rule as the skills installer.
+ */
+export function installAgentInstructions(home = os.homedir()) {
+    const steps = [];
+    const warnings = [];
+    for (const { agent, file } of agentInstructionFiles(home)) {
+        try {
+            /**
+             * ⚠ ONLY FOR AGENTS THAT ARE INSTALLED. Creating `~/.gemini/GEMINI.md` for someone without
+             * Gemini invents an agent: the skills installer keys on that same directory existing, so
+             * the NEXT run would install skills for it too. Same rule as `installAgentSkills`.
+             */
+            if (!fs.existsSync(path.dirname(file))) {
+                steps.push(`${agent}/instructions=agent-absent`);
+                continue;
+            }
+            if (isSymlink(file)) {
+                steps.push(`${agent}/instructions=symlink-skipped`);
+                continue;
+            }
+            let existing = '';
+            try {
+                existing = fs.readFileSync(file, 'utf8');
+            }
+            catch { /* first run */ }
+            const next = upsertBlock(existing, agent === 'claude' ? claudeBlock() : instructionBlock());
+            if (next === existing) {
+                steps.push(`${agent}/instructions=current`);
+                continue;
+            }
+            fs.writeFileSync(file, next, { mode: 0o644 });
+            steps.push(`${agent}/instructions=${existing ? 'updated' : 'written'}`);
+        }
+        catch (e) {
+            warnings.push(`${agent}/instructions: ${e?.message ?? String(e)}`);
+        }
+    }
+    return { steps, warnings };
+}
+/** Remove only our block. A file that becomes empty is deleted only if we created all of it. */
+export function removeAgentInstructions(home = os.homedir()) {
+    const steps = [];
+    const warnings = [];
+    for (const { agent, file } of agentInstructionFiles(home)) {
+        try {
+            if (!fs.existsSync(file) || isSymlink(file))
+                continue;
+            const existing = fs.readFileSync(file, 'utf8');
+            const next = stripBlock(existing);
+            if (next === existing)
+                continue;
+            if (next)
+                fs.writeFileSync(file, next);
+            else
+                fs.unlinkSync(file);
+            steps.push(`${agent}/instructions=removed`);
+        }
+        catch (e) {
+            warnings.push(`${agent}/instructions: ${e?.message ?? String(e)}`);
+        }
+    }
+    return { steps, warnings };
+}
+function isSymlink(file) {
+    try {
+        return fs.lstatSync(file).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/commands/agent.js

@@ -845,7 +845,11 @@ async function agentLogin(args, values) {
         console.error(`  ${yellow('⚠')} Signed in, but this workspace refused ${cyan(name)}: ${outcome.reason}`);
         if (/revoked|not active|unknown agent|not admitted/i.test(`${outcome.scope} ${outcome.reason}`)) {
             console.error(dim(`    The agent is archived or not admitted here. Restore it in Settings → Agent access,`));
-            console.error(dim(`    or log in as an active agent (beehaven call agent-list '{}' shows the roster).`));
+            // ⚠ The workspace names the live identity in its refusal (PPO-190). The old advice —
+            // `beehaven call agent-list` — ran AS this refused identity and was refused in turn.
+            if (!/Log in as one:/.test(outcome.reason)) {
+                console.error(dim(`    or log in as an active agent: beehaven agent login <name> (the Settings → Agent access page lists them).`));
+            }
         }
         console.error(dim(`    Calls from this session run as ${name} and will be refused — they will NOT fall back to another agent.`));
         process.exitCode = 1;

package/dist/commands/canvas-image.js

@@ -25,6 +25,50 @@ function coordinateFlag(raw, label) {
         throw new Error(`${label} must be a number`);
     return value;
 }
+/**
+ * ⚠ NATIVE SIZE IS READ HERE, FROM THE FILE'S OWN HEADER. The docs promise "omit both size flags to
+ * use the image's native dimensions", but nothing measured the image, so the server's placeholder
+ * box won: a 1032×320 PNG landed as a 400×400 node with its aspect squashed (CDS-26). PNG, GIF,
+ * JPEG and WebP carry their size in the first bytes; AVIF (ISO-BMFF) falls back to the server.
+ */
+export function imageSize(buf, mime) {
+    try {
+        if (mime === 'image/png' && buf.length >= 24 && buf.toString('ascii', 12, 16) === 'IHDR') {
+            return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+        }
+        if (mime === 'image/gif' && buf.length >= 10)
+            return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) };
+        if (mime === 'image/webp' && buf.length >= 30 && buf.toString('ascii', 8, 12) === 'WEBP') {
+            const kind = buf.toString('ascii', 12, 16);
+            if (kind === 'VP8X')
+                return { width: 1 + buf.readUIntLE(24, 3), height: 1 + buf.readUIntLE(27, 3) };
+            if (kind === 'VP8L') {
+                const b = buf.readUInt32LE(21);
+                return { width: (b & 0x3fff) + 1, height: ((b >> 14) & 0x3fff) + 1 };
+            }
+            if (kind === 'VP8 ')
+                return { width: buf.readUInt16LE(26) & 0x3fff, height: buf.readUInt16LE(28) & 0x3fff };
+        }
+        if (mime === 'image/jpeg' && buf[0] === 0xff && buf[1] === 0xd8) {
+            let i = 2;
+            while (i + 9 < buf.length) {
+                if (buf[i] !== 0xff) {
+                    i++;
+                    continue;
+                }
+                const marker = buf[i + 1];
+                const len = buf.readUInt16BE(i + 2);
+                // SOF0–SOF15 except DHT(C4), JPG(C8), DAC(CC) carry the frame size.
+                if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+                    return { width: buf.readUInt16BE(i + 7), height: buf.readUInt16BE(i + 5) };
+                }
+                i += 2 + len;
+            }
+        }
+    }
+    catch { /* fall back to the server's default */ }
+    return null;
+}
 function absoluteRelayUrl(url) {
     if (!url.startsWith('/'))
         return url;
@@ -54,12 +98,19 @@ export async function cmdCanvasAddImage(positionals, values) {
         throw new Error(`Image must be 1 byte to 100 MB (${stat.size} bytes given)`);
     const x = coordinateFlag(values.x, '--x');
     const y = coordinateFlag(values.y, '--y');
-    const width = positiveFlag(values.width, '--width');
-    const height = positiveFlag(values.height, '--height');
+    let width = positiveFlag(values.width, '--width');
+    let height = positiveFlag(values.height, '--height');
     if ((x === undefined) !== (y === undefined))
         throw new Error('Pass --x and --y together');
     if ((width === undefined) !== (height === undefined))
         throw new Error('Pass --width and --height together');
+    if (width === undefined) {
+        const native = imageSize(readFileSync(path), mimeType);
+        if (native && native.width > 0 && native.height > 0) {
+            width = native.width;
+            height = native.height;
+        }
+    }
     // Refuse an unknown target before putting bytes in storage for a canvas that cannot use them.
     const target = await rpcOnce('composition-detail', { id: compositionId }, 30_000);
     if (target?.error || target?.composition?.id !== compositionId) {
@@ -93,7 +144,10 @@ export async function cmdCanvasAddImage(positionals, values) {
     if (placed?.ok !== true || !placed?.nodeId && !placed?.blockId) {
         throw new Error(`Image uploaded but could not be placed: ${placed?.error ?? 'unknown error'}. Asset key: ${key}`);
     }
-    const result = { ok: true, compositionId, nodeId: placed.nodeId ?? placed.blockId, imageFileId: recorded?.id, name };
+    // ⚠ `src` IS RETURNED — reusing an upload (a brand logo, a second placement) needed a scene read
+    //   to find the URL the node stores (CDS-27).
+    const src = String(placed?.src ?? placed?.url ?? placed?.node?.src ?? absoluteRelayUrl(String(intent.publicUrl)));
+    const result = { ok: true, compositionId, nodeId: placed.nodeId ?? placed.blockId, imageFileId: recorded?.id, name, src, ...(width !== undefined ? { width, height } : {}) };
     if (values.json)
         console.log(JSON.stringify(result, null, 2));
     else

package/dist/commands/daemon-cmd.js

@@ -138,6 +138,38 @@ export async function startHeadlessDaemon(values) {
         ? `     Ready — socket answering.`
         : `     Started, but not answering yet after ${Math.round(DAEMON_READY_TIMEOUT_MS / 1000)}s. 'beehaven status' shows state.`);
 }
+/**
+ * ⚠⚠ WHO IS ACTUALLY SERVING AFTER A RESPAWN. `restart` used to print the PID it spawned and stop
+ * there. On a Mac with the Clearly app open, the tray supervisor respawns ITS daemon the moment the
+ * old one dies — so the CLI's spawn lost the single-instance race ("Refusing to start — daemon
+ * already running"), exited, and the user was told "Daemon restarted (PID 5706)" about a process
+ * that no longer existed (observed 2026-10-01; the next call said "Cannot connect to daemon").
+ * This waits for a usable socket and reports the PID that is really live.
+ */
+export async function waitForServingDaemon(spawnedPid) {
+    const { isDaemonRunning } = await import('../daemon-client.js');
+    const alive = (pid) => { if (!pid)
+        return false; try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    } };
+    const deadline = Date.now() + DAEMON_READY_TIMEOUT_MS;
+    let ready = false;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, DAEMON_POLL_MS));
+        if (await isDaemonRunning()) {
+            ready = true;
+            break;
+        }
+        // The spawn died and nobody else took over: no point waiting out the clock.
+        if (!alive(spawnedPid) && findLiveDaemons().length === 0)
+            break;
+    }
+    return { ready, spawnedAlive: alive(spawnedPid), livePids: findLiveDaemons() };
+}
 export async function cmdDaemon(sub, values) {
     switch (sub) {
         case 'start':

package/dist/commands/workspace.js

@@ -860,6 +860,22 @@ export async function cmdCall(action, rawInput, values) {
             input = { ...input, action: canonical, name: canonical };
         }
     }
+    // ⚠ `type` IS THE WIRE'S ACTION NAME (PPO-190): a top-level `type` would be overwritten by the
+    // daemon's `{ ...input, type: action }` and lost with `ok: true`. Move it to the verb's own field
+    // or refuse with the right spelling — never drop it in silence. See reserved-type.ts.
+    {
+        const { reconcileReservedType } = await import('../reserved-type.js');
+        const r = reconcileReservedType(action, input);
+        if (r.kind === 'refused') {
+            console.error(`  ${r.error}`);
+            process.exit(1);
+        }
+        if (r.kind === 'moved') {
+            input = r.input;
+            if (!values.json)
+                console.error(`  · ${r.note}`);
+        }
+    }
     // Confirm spend BEFORE resolving a building or touching the daemon — a cancelled call must
     // cost nothing and behave identically whether the input came from argv, a file, or stdin.
     // It runs after the parse because the gate is input-aware: `engine:'handroll'` and any call

package/dist/reserved-type.js

@@ -0,0 +1,60 @@
+/**
+ * reserved-type — `type` is the WIRE'S action name, so a top-level `type` in a call's input is lost.
+ *
+ * ⚠⚠ SILENT DATA LOSS (PPO-190). The daemon sends `{ ...input, type: action }`. An agent that calls
+ * `ticket-create '{"title":"…","type":"bug"}'` gets `ok: true` and a ticket that is NOT a bug: its
+ * `type` was overwritten by `"ticket-create"` before the workspace ever saw it. AGENTS.md has
+ * carried "use `issueType`, not `type`" as a warning, which is a rule every new agent has to be
+ * told and every one of them breaks once.
+ *
+ * The verbs already accept a non-colliding spelling (`issueType`, `linkType`, `proposalType`,
+ * `kind`). This moves `type` onto that spelling when the verb has one, and refuses with the right
+ * spelling when it does not — either way, nothing is dropped in silence.
+ */
+/** Verb → the field the workspace reads instead of `type`. */
+export const TYPE_ALIASES = {
+    // Each entry is a verb whose handler reads this field (verified against apps/cloudflare/src).
+    'ticket-create': 'issueType',
+    'ticket-update': 'issueType',
+    'ticket-link-create': 'linkType',
+    'proposal-create': 'proposalType',
+    'composition-create': 'kind',
+    'record-thought': 'kind',
+    'thought-record': 'kind',
+};
+/**
+ * Reconcile a top-level `type` with the wire's use of the name. Pure.
+ *
+ * ⚠ A `type` EQUAL TO THE ACTION is left alone — that is a caller spelling the action twice, which
+ * the wire already agrees with. Nested `type`s (canvas nodes, `updates.type`) never collide and are
+ * never inspected.
+ */
+export function reconcileReservedType(action, input) {
+    if (!input || typeof input !== 'object' || !Object.prototype.hasOwnProperty.call(input, 'type'))
+        return { kind: 'none' };
+    const value = input.type;
+    if (value === undefined || value === action)
+        return { kind: 'none' };
+    const field = TYPE_ALIASES[action];
+    if (field) {
+        const { type: _dropped, ...rest } = input;
+        if (rest[field] !== undefined && rest[field] !== value) {
+            return {
+                kind: 'refused',
+                error: `both "type" (${JSON.stringify(value)}) and "${field}" (${JSON.stringify(rest[field])}) were given — `
+                    + `"type" is the action name on the wire and would be dropped; pass only "${field}".`,
+            };
+        }
+        return {
+            kind: 'moved',
+            field,
+            input: { ...rest, [field]: value },
+            note: `"type" is reserved for the action name on the wire — sent as "${field}": ${JSON.stringify(value)}`,
+        };
+    }
+    return {
+        kind: 'refused',
+        error: `"type" is reserved for the action name on the wire, so ${action} would never see ${JSON.stringify(value)}. `
+            + `Use the verb's own field (see: beehaven describe ${action}).`,
+    };
+}

package/package.json

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

package/scripts/sync-skills.mjs

@@ -35,6 +35,7 @@ const SOURCES = {
   'agent-doodle-space':'apps/mcp-server/plugin/skills/agent-doodle-space/SKILL.md',
   'design-craft':   'apps/mcp-server/plugin/skills/design-craft/SKILL.md',
   'layout-systems': 'apps/mcp-server/plugin/skills/layout-systems/SKILL.md',
+  'brand-identity': 'apps/mcp-server/plugin/skills/brand-identity/SKILL.md',
   'pair-on-canvas': 'apps/mcp-server/plugin/skills/pair-on-canvas/SKILL.md',
   'codebase-map':   'apps/mcp-server/plugin/skills/codebase-map/SKILL.md',
   'clearly-workspace': 'apps/mcp-server/plugin/skills/clearly-workspace/SKILL.md',

package/skills/README.md

@@ -1,24 +1,26 @@
-# CLI-paired Claude Code skills
+# Skills shipped with the CLI
 
-Claude Code skills that document built-in `beehaven` CLI verbs.
-Distinct from hive-paired skills (which live with each hive in
-`clearly-hives/<hive>/skills/`).
+The `beehaven` tarball carries the agent skills a CLI-only user needs — the same set the Clearly
+Mac app installs — so `curl | sh` teaches an agent Clearly without the app.
 
-A skill belongs here when it documents functionality that ships
-with the CLI itself, not with any specific hive. Currently:
+## Where each skill comes from
 
-- **`claude-shopper/`** — documents `beehaven shop find/at/search/get/checkout`
-  (the shop@0 protocol surface). Not paired with any hive — the shop
-  catalog is part of the CLI's Yellow Pages integration.
+| Skill | Source of truth (edit HERE, never the copy) |
+|---|---|
+| `beehaven-cli` | `clearly-hives/beehaven-cli/skills/SKILL.md` |
+| `clearly-agent`, `clearly-canvas`, `clearly-workspace`, `design-craft`, `layout-systems`, `brand-identity`, `pair-on-canvas`, `codebase-map`, `agent-home`, `agent-doodle-space` | `apps/mcp-server/plugin/skills/<name>/` in the monorepo |
+| `claude-shopper` | this folder — hand-written, documents `beehaven shop` (the shop@0 protocol) |
 
-These aren't installed by `beehaven install` (that's for hive-paired
-skills via the `agentDocs.claudeCode` manifest field). If a user wants
-the claude-shopper skill, they install it manually:
+`scripts/sync-skills.mjs` copies every monorepo source into `skills/<name>/` (`npm run sync:skills`,
+and automatically at `prepack`) and writes `skills/index.json`. Its `SOURCES` table mirrors the
+Mac app's `electron-builder*.yml` extraResources and `SHIPPED_SKILLS`
+(`apps/electron/electron/agent-skills-installer.ts`); `apps/electron/scripts/verify-mcp-parity.mjs`
+fails when the two sets disagree.
 
-```bash
-cp -R packages/cli/skills/claude-shopper ~/.claude/skills/beehaven-shopper
-```
+## Rules
 
-Or eventually via a `beehaven skills install-bundled <name>` verb (not
-yet built). See `beehaven_sdk/docs/LOCAL_HIVES.md` §11.5 for the
-hive-paired skill flow this complements.
+- Edit the source, then run `npm run sync:skills`. A change made to a copy here is overwritten.
+- Copies are generated, so they are listed in `.gitignore` (a second committed copy is a second copy
+  to drift). ⚠ `agent-home`, `agent-doodle-space`, `clearly-agent` and `clearly-workspace` are still
+  tracked from before that rule; treat them as generated all the same.
+- Only `README.md` and `claude-shopper/` are hand-written here.

package/skills/brand-identity/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: brand-identity
+description: >-
+  Build a complete brand identity on a Clearly canvas the way a studio does —
+  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
+  guidelines, or "design a company/product/app called X". Load design-craft
+  alongside it for the underlying grid, type and colour craft. Triggers:
+  "design a brand", "make me a logo", "brand identity", "visual identity",
+  "rebrand", "brand guidelines", "logo and colours", "identity system".
+---
+
+# 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.
+
+Read **`design-craft`** first or alongside — grid, type scale, colour roles and the studio
+pass are assumed here.
+
+---
+
+## 1. The brief — five lines, before anything is drawn
+
+You may ask the user, or state your reading and proceed. You may not skip it.
+
+```
+WHO      the organisation, in one clause
+FOR      the audience, specifically — not "everyone"
+UNLIKE   the nearest competitor, and what must NOT be borrowed from them
+FEELS    three adjectives, and one the brand is deliberately NOT
+LIVES    where it actually appears: app icon? shopfront? 30 pages of PDF? a t-shirt?
+```
+
+⚠⚠ **`LIVES` DECIDES THE MARK MORE THAN `FEELS` DOES.** A brand that lives at 24px in a
+browser tab cannot have a mark with four internal details. A brand that lives on a building
+can. Ask where it is smallest and design for that first.
+
+⚠ **`UNLIKE` is what stops generic output.** Without it, every fintech gets a blue geometric
+sans and every studio gets a black wordmark in Helvetica. Name the cliché and refuse it out loud.
+
+---
+
+## 2. The mark — construct it, never freehand it
+
+⚠⚠ **EVERY CURVE AND ANGLE SHOULD BE DERIVABLE.** A mark built from a stated construction —
+a circle of radius R, a 30° angle, a stroke of R/6 — survives scaling, redrawing and
+handover. A mark of hand-placed béziers does not, and it shows.
+
+**The construction methods that actually work on a canvas:**
+
+| method | how | good for |
+|---|---|---|
+| **Geometric** | circles/squares/triangles on a shared radius; every measure a fraction of R | tech, finance, infrastructure |
+| **Derived letterform** | take the initial, cut or extend one stroke | anything with a strong name |
+| **Monoline** | one stroke weight everywhere, round caps and joins | modern, friendly, screen-first |
+| **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:**
+
+```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>"}}
+```
+
+⚠ **`<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.
+
+**Test the mark against these before going further. A mark that fails any of them is not done:**
+
+```
+□ 24px      Still readable as a distinct shape? (Render it at 24 and LOOK.)
+□ 1 colour  Works in solid black? Solid white on dark?
+□ Knockout  Works as a hole in a shape — no fill, no gradient carrying it?
+□ Square    Sits comfortably in an app-icon square with its own padding?
+□ Rotated   Is it accidentally something else at 90°/180°?
+□ Unlike    Put it next to the competitor named in the brief. Distinct?
+```
+
+⚠⚠ **DESIGN IT IN ONE COLOUR FIRST.** A gradient can make a weak shape look temporarily
+good. If it does not work in flat black, the shape is wrong and the gradient is hiding it.
+
+---
+
+## 3. Wordmark and lockups
+
+- **Set the wordmark in real type, then adjust** — do not draw letters from scratch unless
+  the brief asks for a custom face.
+- ⚠ **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:
+
+```
+primary      mark + wordmark, horizontal    ← the default
+stacked      mark above wordmark            ← square-ish slots
+mark-only    the symbol alone               ← ≥ 24px, when context supplies the name
+reversed     the primary on dark
+mono         one colour, no exceptions      ← print, engraving, embroidery
+```
+
+- **Clear space** = a fraction of the mark, never an absolute px. **¼ of the mark's height**
+  on all four sides is a defensible default. Express it in terms of the mark so it scales.
+- **Minimum size** — state one, per lockup, and test it: mark-only 24px digital / 10mm print;
+  the full lockup needs roughly 2–3× that before the wordmark closes up.
+
+---
+
+## 4. Palette
+
+Follow `design-craft`'s role list — ground, ink, ink-muted, accent, 2–3 support. For an
+identity, add:
+
+- ⚠⚠ **ONE colour is the brand.** People remember a single colour. A five-colour identity is
+  remembered as no colour. Pick the one, then support it.
+- **State a dark-ground variant of every colour.** The same accent needs ~10% more lightness
+  on near-black to read the same. An identity without this ships broken dark mode.
+- **Give each colour a role sentence**, not just a hex: *"Accent. The one thing that shouts.
+  CTAs, the mark, one word in a headline. Never a background."* A palette without roles gets
+  used at random.
+- **Print values matter if `LIVES` includes print** — state CMYK or Pantone intent, and know
+  that a bright screen accent may be unreachable in CMYK. Say so rather than shipping a
+  surprise.
+
+---
+
+## 5. Type system
+
+```
+DISPLAY   headlines, the mark's neighbour     one face, one or two weights
+TEXT      body, UI, long form                 must have real weights + italics
+MONO      code, data, captions                only if the brand needs it
+```
+
+- **One face in two weights beats two faces.** If you use two, make them different in CLASS.
+- ⚠ **Check the face has what the brand needs**: does it have a decent 500? Real italics or
+  faked obliques? The numerals you want (lining vs oldstyle, tabular for data)? A missing
+  weight is discovered three months in, on a deadline.
+- **Publish the scale**, not just the names — the ratio, the base, and the resulting sizes
+  (see `design-craft` §2). A type "system" without sizes is a font recommendation.
+
+---
+
+## 6. Applications — this is what makes it believable
+
+For an imagery moodboard, create a small series of purpose-made images with a shared
+material, lighting and colour logic, then place each as its own editable image node.
+Keep the official Clearly rabbit wordmark as a separate canonical asset; do not ask an
+image model to redraw it. The CLI path for local raster files is
+`beehaven canvas add-image <file> --composition <id>`; see
+[`clearly-canvas/authoring.md`](../clearly-canvas/authoring.md#local-images-from-the-cli)
+for the upload, nesting and MCP contracts. Inspect a rendered artboard after placing
+the images: a stored `src` alone does not prove the intended image is visible.
+
+⚠⚠ **A mark on a white square convinces nobody. The SAME mark on six real surfaces does.**
+This is the single highest-value part of the deliverable and the part agents most often skip.
+
+Pick 4–6 that match the brief's `LIVES`:
+
+```
+app icon 512×512      business card 1050×600     social avatar + header
+website hero          poster / out-of-home       packaging face
+email signature       t-shirt / tote             signage / door vinyl
+presentation title    invoice / letterhead       UI screen with the system applied
+```
+
+Build each as a real frame at real proportions on the canvas, in a row, with a caption under
+each. **Do not fake them as flat rectangles labelled "app icon"** — draw the rounded square,
+put the mark in it at the right optical size, show it at 512 and again at 48.
+
+---
+
+## 7. The spec board — hand-off, on the canvas
+
+A titled section, below the applications, that another designer could build from:
+
+```
+01 MARK          construction diagram — the circles/angles/ratios, drawn, with the numbers
+02 CLEAR SPACE   the ¼-height rule, drawn as a dashed frame with the measure labelled
+03 LOCKUPS       all five, at the same optical size, labelled
+04 MISUSE        4–6 tiles: stretched, recoloured, rotated, on a busy photo, effects,
+                 too small — each with a ✗. This section prevents more damage than any other.
+05 PALETTE       swatches + hex + ROLE SENTENCE + dark-ground variant
+06 TYPE          the faces, the scale with real numbers, a specimen paragraph
+07 GRID          margins, columns, gutter, baseline — the numbers from design-craft §1
+08 VOICE         3 lines: how it speaks, one thing it never says
+```
+
+⚠ **Section 04 (misuse) is not filler.** Guidelines are read once and then broken; the misuse
+tiles are what people actually remember.
+
+---
+
+## 8. Canvas layout for the whole delivery
+
+Lay it out left to right as a narrative, one row per stage, generous gutters (200px+ between
+artboards) so each reads as its own object:
+
+```
+Row 1   COVER            1080×1350   the mark, big, on the brand ground
+Row 2   THE MARK         construction · lockups · clear space
+Row 3   PALETTE + TYPE   full-width panels
+Row 4   APPLICATIONS     4–6 real-proportion artboards in a row
+Row 5   SPEC BOARD       the eight sections above, as titled panels
+```
+
+- **Put a caption above every artboard** (`19px/700`, accent, `letterSpacing: 2`) so the
+  board reads as a deck rather than a pile.
+- **Set the composition background** to a dark neutral (`composition-patch {backgroundColor}`)
+  so the artboards read as objects on a desk. ⚠ That patch reaches an open tab now, but if
+  the ground is load-bearing, lay a real rect and `canvas.order {op:"back"}` it.
+- ⚠ **Build in ONE batch** and check `count` against the number of ops you sent — a batch
+  stops at the first failure and lands everything before it.
+
+---
+
+## 9. Verify like a studio
+
+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
+□ 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
+□ Put the mark beside the competitor named in UNLIKE — still distinct?
+□ Can someone build a new asset from this board without asking a question?
+```
+
+⚠⚠ **THE LAST ONE IS THE REAL TEST.** If any answer would be "ask the designer", the system
+is incomplete — and the whole point of an identity is that it works when the designer has left.
+
+---
+
+## Sources
+
+Pentagram brand-identity practice (symbol, wordmark, graphic system, palette, type system,
+guidelines for in-house teams) · Michael Bierut, *How to* (brief → rationale → trade-offs) ·
+Paula Scher's Public Theater identity — a system built almost entirely from typography, which
+survived because the plays changed constantly and the identity was designed to absorb it ·
+Massimo Vignelli, *The Vignelli Canon*.

package/skills/clearly-agent/SKILL.md

@@ -170,6 +170,15 @@ teammate or another agent needs your work, move it into a project you both belon
 ⚠ Creating something does **not** put it in your owner's Recents — that is deliberate. They find it
 in Drafts. Opening it is what makes it recent *for them*.
 
+## Designing UI? Use the workspace's brand and components — and design before you build
+
+A workspace stores its brand (`brand-tokens`) and its component library (`component-list`) as data.
+Anything visual you make — a canvas, a deck, a mockup of a screen you are about to implement —
+starts from those, placed with `component-instantiate {compositionId, instances:[…]}`. When the
+task changes a product's UI, the composition comes FIRST: build the screen and its states there,
+`canvas.review` it, link it to the ticket (`work-link {ticketId, kind:"design", refKind:"composition",
+refId}`), then implement. `clearly-canvas` §0 has the details.
+
 ## When a write is refused
 
 `agent-denied-create` / `-update` / `-delete` mean your **capability matrix** said no. It covers the
@@ -211,7 +220,8 @@ ask the owner.
   `beehaven call agent-list '{}'` shows the live roster; log in as one of those.
 - ⚠ **`workspace-sql` takes `query`**, not `sql`. The wrong key is silently dropped and you get the
   SCHEMA back — `ok: true`, a confident list of tables, not your answer.
-- ⚠ **`document-create` takes `markdown` or `html`**, not `content`. An unknown key is stripped, the
-  document is created empty, and it is **invisible to `document-search` forever**.
-- ⚠ **`ticket-create` takes `issueType`, not `type`** (the wire uses `type` as the action
-  discriminator) and **`body`, not `description`**. Both fail silently.
+- **`document-create` takes `markdown` or `html`.** `content`, `body` and `text` are accepted as
+  markdown aliases, but prefer `markdown`.
+- **`ticket-create` / `ticket-update` take `issueType` and `body`.** The wire uses `type` as the action
+  name, so the CLI moves a top-level `type` to `issueType` for you and refuses it on verbs with no
+  such field. `description` is accepted as `body`.

package/skills/clearly-canvas/SKILL.md

@@ -47,6 +47,36 @@ A new composition almost always needs at least one revision after its first rend
 the pass finds nothing, look again at the thumbnail. If there is still nothing, say what
 you checked. Never make a change only to show that a review happened.
 
+## 0. Start from the workspace's brand and component library
+
+A workspace keeps its brand and its components as data. Read them before you draw, and
+build from them — redrawing a button the library already has is how designs drift from the
+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 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"}}]}'
+```
+
+- `instances` places many parts with ONE scene read and ONE write; never loop single
+  placements. `mode:"dark"` resolves brand colours against the brand's dark palette.
+- Placed instances are ordinary editable nodes whose root remembers its master
+  (`libraryComponentId`). Edit freely; a genuinely new part goes back into the library with
+  `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.
+
+**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,
+error, long content, narrow width, dark theme), review it, and link it to the ticket with
+`work-link {"ticketId":"…","kind":"design","refKind":"composition","refId":"<id>"}`
+before implementation starts.
+
 ## 1. Establish the brief and inspect the material
 
 Read the supplied canvas, copy, brand and references before drawing. Resolve:
@@ -117,8 +147,9 @@ multiple colours and dense pages can all be appropriate. Choose deliberately.
 
 ## 3. Define a small design system and code the composition
 
-Write a local JS/Python builder when the artifact has repeated elements or several
-artboards. Use named tokens, helpers, arrays and layout arithmetic as you would in
+When §0 found a brand kit and components, they are the system: map the brief onto their
+roles, then add only what the brief genuinely needs. Write a local JS/Python builder when
+the artifact has repeated elements or several artboards. Use named tokens, helpers, arrays and layout arithmetic as you would in
 HTML/CSS. The CLI can submit the complete generated payload. You do not need to
 hand-author hundreds of coordinates in a chat message.
 
@@ -158,6 +189,12 @@ Use a batch for each coherent build or revision, with descriptive unique layer n
 Parent content to its artboard. Inspect every operation result and rollback status.
 Save your builder and returned IDs so revisions are targeted and reproducible.
 
+⚠ **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
+runs. The same steps sent as hundreds of separate calls each re-read the whole scene. If a
+call fails with a dropped connection, read the scene (`composition-detail
+{id, includeScene:true}`) before retrying: the work may have landed.
+
 Keep review notes and status outside the delivered artwork. Use
 [communications.md](communications.md) only when posting those blocks is useful.
 

package/skills/clearly-canvas/authoring.md

@@ -57,10 +57,19 @@ Create normalizes hex colours; raw stored scenes use RGBA arrays in 0..1.
 
 - `frame.create` and `canvas.create-node` with `parentId` take coordinates **relative
   to that parent**. Create the frame first. Names can resolve earlier nodes in a batch.
+  A frame nested in a frame (a dark band inside an artboard) needs a worker from
+  2026-10-02 or later; on an older one, create it at world coordinates and attach it with
+  `canvas.update-nodes {ids:[id], patch:{parentId}}` (membership only, position kept).
+  To move a node INTO a frame and place it in one patch, pass `parentId` with frame-relative x/y.
+- Component templates (`component-create`) are different: every node's x/y is relative
+  to the component ROOT, even under an inner frame.
 - Persisted nodes and perception bounds use **world coordinates**. Raw scene replacement
   through `composition-patch`/MCP must use world coordinates, even with `parentId`.
-- `canvas.update-nodes` geometry is world geometry. For group moves/resizes use the
-  catalog's frame/arrangement/scale actions; do not assume a patch reflows children.
+- `canvas.update-nodes` geometry is world geometry — EXCEPT when the same patch also sets
+  `parentId`: then x/y are relative to that frame, exactly like `canvas.create-node`. A
+  membership-only patch (`parentId` without x/y) keeps the node's world position. For group
+  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.
 - 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.
@@ -124,9 +133,11 @@ beehaven canvas add-image ./photo.png --composition <id> \
   --x 120 --y 160 --width 600 --height 400 --json
 ```
 
-The command reports `nodeId` and `imageFileId`. Coordinates are world coordinates;
-omit both `--x`/`--y` to use canvas auto-placement, and omit both size flags to use
-the image's native dimensions. Check `beehaven canvas` help on the installed CLI:
+The command reports `nodeId`, `imageFileId` and `src` (the stored URL — reuse it, e.g. as a
+brand logo). Coordinates are world coordinates; omit both `--x`/`--y` to use canvas
+auto-placement, and omit both size flags to use the image's native dimensions (read from
+the file header for PNG, JPEG, GIF and WebP). A negative coordinate works as `--x -3000`
+on CLI 0.8.24+; older CLIs need `--x=-3000`. Check `beehaven canvas` help on the installed CLI:
 older versions do not have this command. On one of those, use the documented
 `get-upload-url` → binary PUT → `file-uploaded` sequence, then
 `canvas-act {action:"canvas.create-node",args:{type:"image",src:<absolute URL>,x,y,w,h}}`.

package/skills/design-craft/SKILL.md

@@ -132,6 +132,10 @@ headline estimated at 867px measured **990**.
 
 ## 3. Colour — a system, not a mood board
 
+⚠ **A workspace brand kit already IS this role list.** `beehaven call brand-tokens '{}'`
+returns ground, ink, muted, accent and support roles (light and dark) with their contrast
+already measured. Use those values; the list below is for when there is no kit.
+
 **Build the palette from a role list, not from colours you like:**
 
 ```

package/skills/index.json

@@ -17,7 +17,7 @@
       "project-plans.md",
       "review.mjs"
     ],
-    "sha": "21faa5f8d14beefe"
+    "sha": "9b34f0b8326257d0"
   },
   {
     "name": "agent-home",
@@ -38,7 +38,7 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "7761aa240847d20c"
+    "sha": "260c3a6967b08a8b"
   },
   {
     "name": "layout-systems",
@@ -47,6 +47,13 @@
     ],
     "sha": "8de89b7b7c86f81f"
   },
+  {
+    "name": "brand-identity",
+    "files": [
+      "SKILL.md"
+    ],
+    "sha": "50587f531bfab1c6"
+  },
   {
     "name": "pair-on-canvas",
     "files": [
@@ -74,6 +81,6 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "94c30f43b217f3e9"
+    "sha": "9e94e53b90ded575"
   }
 ]