@clearlysh/beehaven 0.8.27 → 0.8.30

package/dist/ipc-path.js

@@ -0,0 +1,92 @@
+/**
+ * ipc-path — where the daemon's local sockets live, on every platform (CAN2-56).
+ *
+ * ⚠⚠ THE ONE PLACE A SOCKET ADDRESS IS DECIDED. `/tmp/beehaven-ipc.sock` was typed out in five CLI
+ * files (server, three clients, the claude bridge) and `/tmp/beehaven.sock` in two more, each
+ * gating its connect on `existsSync`, unlinking stale files and chmod-ing to 0600. On Windows none
+ * of that works: Node's `net` listens on a NAMED PIPE (`\\.\pipe\…`), there is no `/tmp`, a pipe is
+ * not a file you can stat, unlink or chmod — so the daemon could not bind and no client could
+ * reach it. Every caller now asks this module, and the Unix addresses are byte-for-byte unchanged
+ * (the Mac app, the mwah CLI and the Electron daemon client still dial `/tmp/beehaven-ipc.sock`).
+ *
+ * ⚠ A PIPE NAME IS MACHINE-GLOBAL, so it carries the user name: two people signed in to one
+ * Windows machine get two daemons, as two Unix users do. Same-user is still the boundary that
+ * matters, and the IPC auth token (`ipc-auth.ts`) is what gates verbs on both platforms — the
+ * Unix 0600 mode is defense in depth that a pipe does not have a file-mode equivalent for.
+ *
+ * ⚠ `$BEEHAVEN_IPC_SOCKET` / `$BEEHAVEN_WATCHER_SOCKET` override the address for BOTH ends (server
+ * and clients), so a test can stand a real daemon and a real client on a private path. Read at call
+ * time, not import time, for the same reason.
+ */
+import { existsSync, unlinkSync, chmodSync, statSync } from 'fs';
+import { tmpdir, userInfo } from 'os';
+import { join } from 'path';
+export const UNIX_IPC_SOCKET = '/tmp/beehaven-ipc.sock';
+export const UNIX_WATCHER_SOCKET = '/tmp/beehaven.sock';
+export const UNIX_EVENTS_FILE = '/tmp/beehaven-events.jsonl';
+/** `\\.\pipe\…` or `\\?\pipe\…` — the forms Node accepts for a Windows named pipe. */
+export function isNamedPipe(p) {
+    return /^\\\\[.?]\\pipe\\/i.test(p);
+}
+/** The signed-in user's name, made safe for a pipe name. */
+function pipeUser(env) {
+    let name = '';
+    try {
+        name = userInfo().username;
+    }
+    catch { /* no passwd entry / sandbox */ }
+    if (!name)
+        name = env.USERNAME || env.USER || 'user';
+    return name.toLowerCase().replace(/[^a-z0-9._-]+/g, '_').slice(0, 64) || 'user';
+}
+const pipe = (name, env) => `\\\\.\\pipe\\${name}-${pipeUser(env)}`;
+/** The daemon's IPC address: the Unix socket, or this user's named pipe on Windows. */
+export function ipcSocketPath(platform = process.platform, env = process.env) {
+    if (env.BEEHAVEN_IPC_SOCKET)
+        return env.BEEHAVEN_IPC_SOCKET;
+    return platform === 'win32' ? pipe('beehaven-ipc', env) : UNIX_IPC_SOCKET;
+}
+/** The Claude Code event watcher's HTTP-over-socket address. */
+export function watcherSocketPath(platform = process.platform, env = process.env) {
+    if (env.BEEHAVEN_WATCHER_SOCKET)
+        return env.BEEHAVEN_WATCHER_SOCKET;
+    return platform === 'win32' ? pipe('beehaven-watcher', env) : UNIX_WATCHER_SOCKET;
+}
+/** The watcher's JSONL fallback file. Windows has no `/tmp`; its temp dir is per-user already. */
+export function eventsFilePath(platform = process.platform) {
+    return platform === 'win32' ? join(tmpdir(), 'beehaven-events.jsonl') : UNIX_EVENTS_FILE;
+}
+/**
+ * Could a listener be at `p`? A socket FILE can be checked without touching it. A named pipe
+ * cannot: it exists only while a server holds it, and probing it with a filesystem call opens an
+ * instance of it. So a pipe answers `true` and the connect attempt decides (`ENOENT` = nothing).
+ */
+export function socketMayExist(p) {
+    return isNamedPipe(p) || existsSync(p);
+}
+/** Remove a stale socket file before binding. A named pipe leaves nothing behind to remove. */
+export function clearStaleSocket(p) {
+    if (isNamedPipe(p))
+        return;
+    try {
+        if (existsSync(p))
+            unlinkSync(p);
+    }
+    catch { /* already gone */ }
+}
+/**
+ * Restrict a freshly bound socket file to its owner (0600) and report the mode it really has.
+ * `applicable: false` for a named pipe, which has no file mode — its boundary is the per-user name
+ * plus the IPC token.
+ */
+export function restrictSocketToOwner(p) {
+    if (isNamedPipe(p))
+        return { applicable: false, mode: null };
+    try {
+        chmodSync(p, 0o600);
+        return { applicable: true, mode: statSync(p).mode & 0o777 };
+    }
+    catch (err) {
+        return { applicable: true, mode: null, error: String(err?.code ?? err?.message ?? err) };
+    }
+}

package/dist/ipc-server.js

@@ -2,7 +2,7 @@
  * IPC Server — bidirectional Unix socket for local clients (Electron, CLI tools).
  *
  * Provides request-response RPCs and broadcast subscriptions over a line-based
- * JSON protocol on /tmp/beehaven-ipc.sock.
+ * JSON protocol on /tmp/beehaven-ipc.sock (a per-user named pipe on Windows — see ipc-path.ts).
  *
  * Local clients send messages to the daemon, which forwards them to the DO
  * via the relay WebSocket. DO responses and broadcasts are forwarded back
@@ -24,10 +24,11 @@
  *   { "type": "status", "connected": true, "daemonPid": 1234 }
  */
 import { createConnection, createServer } from 'net';
-import { existsSync, unlinkSync, chmodSync, statSync } from 'fs';
 import { EventEmitter } from 'events';
 import { resolveAuthScope } from './ipc-auth.js';
-const IPC_SOCKET_PATH = '/tmp/beehaven-ipc.sock';
+import { ipcSocketPath, socketMayExist, clearStaleSocket, restrictSocketToOwner } from './ipc-path.js';
+/** The default address (Unix socket, or this user's named pipe on Windows) — see `ipc-path.ts`. */
+const IPC_SOCKET_PATH = ipcSocketPath();
 /**
  * Message types the daemon will process without authentication.
  *
@@ -114,9 +115,10 @@ export function actionChain(action, input, depth = 0) {
  */
 function probeIpcSocket(timeoutMs = 400) {
     return new Promise((resolve) => {
-        if (!existsSync(IPC_SOCKET_PATH))
+        const path = ipcSocketPath();
+        if (!socketMayExist(path))
             return resolve(false);
-        const client = createConnection(IPC_SOCKET_PATH);
+        const client = createConnection(path);
         const done = (alive) => {
             try {
                 client.destroy();
@@ -138,6 +140,8 @@ function probeIpcSocket(timeoutMs = 400) {
 export { probeIpcSocket };
 export class IpcServer extends EventEmitter {
     server = null;
+    /** The address this server bound (resolved at `start`, so an env override set before start applies). */
+    path = null;
     clients = new Map();
     clientCounter = 0;
     virtualClientCounter = 0;
@@ -157,12 +161,10 @@ export class IpcServer extends EventEmitter {
      * at this point; a live server would have been caught upstream.
      */
     start() {
-        // Clean up stale socket
-        try {
-            if (existsSync(IPC_SOCKET_PATH))
-                unlinkSync(IPC_SOCKET_PATH);
-        }
-        catch { }
+        // Clean up a stale socket file (a named pipe leaves none).
+        const path = ipcSocketPath();
+        this.path = path;
+        clearStaleSocket(path);
         this.server = createServer((socket) => {
             const clientId = `ipc_${++this.clientCounter}`;
             // Connections start unauthenticated and scope=null. The client must
@@ -235,7 +237,7 @@ export class IpcServer extends EventEmitter {
         // process-wide umask — umask changes are global and race with any
         // other mkdirSync / writeFileSync happening in parallel (e.g.
         // LocalHive pre-creating building data dirs during startup).
-        this.server.listen(IPC_SOCKET_PATH, () => {
+        this.server.listen(path, () => {
             /**
              * ⚠⚠ CHMOD, THEN **VERIFY**. This was `chmodSync(…, 0o600)` inside an empty `catch {}`, and
              * the mode it claims has been wrong on every start measured: the live socket comes up
@@ -266,19 +268,18 @@ export class IpcServer extends EventEmitter {
              * was learned once and not applied here. Import at the top; never reach for `require` in this
              * package.
              */
-            let mode = null;
-            try {
-                chmodSync(IPC_SOCKET_PATH, 0o600);
-                mode = statSync(IPC_SOCKET_PATH).mode & 0o777;
-            }
-            catch (err) {
-                console.warn(`[ipc] SECURITY: could not set 0600 on ${IPC_SOCKET_PATH} — ${err?.code ?? err?.message ?? err}`);
+            // A Windows named pipe has no file mode (`applicable: false`): its boundary is the per-user
+            // pipe name plus the IPC token — see `ipc-path.ts`.
+            const restricted = restrictSocketToOwner(path);
+            const mode = restricted.mode;
+            if (restricted.error) {
+                console.warn(`[ipc] SECURITY: could not set 0600 on ${path} — ${restricted.error}`);
             }
             if (mode !== null && mode !== 0o600) {
                 console.warn(`[ipc] SECURITY: socket mode is 0${mode.toString(8)}, expected 0600. Other-user connect is still `
                     + `blocked (no write bit), but the documented guarantee does not hold — do not weaken it further.`);
             }
-            console.log(`[ipc] Listening on ${IPC_SOCKET_PATH}${mode !== null ? ` (mode 0${mode.toString(8)})` : ''}`);
+            console.log(`[ipc] Listening on ${path}${mode !== null ? ` (mode 0${mode.toString(8)})` : ''}`);
         });
         this.server.on('error', (err) => {
             console.warn(`[ipc] Server error: ${err.message}`);
@@ -295,11 +296,7 @@ export class IpcServer extends EventEmitter {
             this.server.close();
             this.server = null;
         }
-        try {
-            if (existsSync(IPC_SOCKET_PATH))
-                unlinkSync(IPC_SOCKET_PATH);
-        }
-        catch { }
+        clearStaleSocket(this.path ?? ipcSocketPath());
     }
     /** Broadcast a message from the DO to all subscribed local clients */
     /**

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-service.js

@@ -391,8 +391,12 @@ export async function cleanupAll() {
     }
     // 3. Socket + event log
     const { existsSync, unlinkSync, readdirSync, rmSync, readFileSync, writeFileSync } = await import('node:fs');
-    const { join } = await import('node:path');
-    for (const p of ['/tmp/beehaven.sock', '/tmp/beehaven-ipc.sock', '/tmp/beehaven-events.jsonl']) {
+    const { join, dirname } = await import('node:path');
+    const { watcherSocketPath, ipcSocketPath, eventsFilePath, isNamedPipe } = await import('./ipc-path.js');
+    const eventsFile = eventsFilePath();
+    for (const p of [watcherSocketPath(), ipcSocketPath(), eventsFile]) {
+        if (isNamedPipe(p))
+            continue; // a Windows pipe disappears with the daemon that held it
         try {
             if (existsSync(p)) {
                 unlinkSync(p);
@@ -402,10 +406,11 @@ export async function cleanupAll() {
         catch { }
     }
     try {
-        for (const f of readdirSync('/tmp')) {
+        const eventsDir = dirname(eventsFile);
+        for (const f of readdirSync(eventsDir)) {
             if (f.startsWith('beehaven-events.jsonl.') && f.endsWith('.old')) {
                 try {
-                    unlinkSync(join('/tmp', f));
+                    unlinkSync(join(eventsDir, f));
                 }
                 catch { }
             }

package/dist/watcher.js

@@ -1,18 +1,19 @@
 // ============================================================================
 // Beehaven Office - Claude Code Event Watcher
-// Primary: Unix domain socket HTTP server at /tmp/beehaven.sock
+// Primary: HTTP server on a local socket — /tmp/beehaven.sock, or a named pipe on Windows (ipc-path.ts)
 // Fallback: Watches the JSONL events file written by the hook script
 // ============================================================================
 // chokidar is imported lazily so a missing bundle (e.g. when the daemon ships
 // inside an Electron app whose node_modules layout doesn't include chokidar)
 // degrades the file-watcher to a no-op rather than crashing the whole daemon.
 // The primary Unix-socket path does not depend on chokidar.
-import { createReadStream, existsSync, writeFileSync, statSync, renameSync, unlinkSync, chmodSync, watch as fsWatch, } from 'fs';
+import { createReadStream, existsSync, writeFileSync, statSync, renameSync, chmodSync, watch as fsWatch, } from 'fs';
 import { createInterface } from 'readline';
 import { createServer } from 'http';
 import { EventEmitter } from 'events';
-const EVENTS_FILE = '/tmp/beehaven-events.jsonl';
-const SOCKET_PATH = '/tmp/beehaven.sock';
+import { watcherSocketPath, eventsFilePath, clearStaleSocket, restrictSocketToOwner } from './ipc-path.js';
+const EVENTS_FILE = eventsFilePath();
+const SOCKET_PATH = watcherSocketPath();
 const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10 MB
 export { SOCKET_PATH };
 export class ClaudeWatcher extends EventEmitter {
@@ -32,14 +33,8 @@ export class ClaudeWatcher extends EventEmitter {
     // ── Unix Domain Socket ───────────────────────────────────────────────
     /** Start HTTP server on Unix domain socket for direct event delivery */
     startSocket() {
-        // Remove stale socket file
-        try {
-            if (existsSync(SOCKET_PATH))
-                unlinkSync(SOCKET_PATH);
-        }
-        catch {
-            /* may not exist */
-        }
+        // Remove a stale socket file (a Windows named pipe leaves none)
+        clearStaleSocket(SOCKET_PATH);
         this.socketServer = createServer((req, res) => {
             if (req.method !== 'POST' || req.url !== '/event') {
                 res.writeHead(404);
@@ -71,10 +66,7 @@ export class ClaudeWatcher extends EventEmitter {
         // during startup). A post-bind chmod achieves the same security
         // without the race.
         this.socketServer.listen(SOCKET_PATH, () => {
-            try {
-                chmodSync(SOCKET_PATH, 0o600);
-            }
-            catch { }
+            restrictSocketToOwner(SOCKET_PATH); // no-op for a named pipe
             console.log(`[watcher] Socket listening on ${SOCKET_PATH}`);
         });
     }
@@ -84,13 +76,7 @@ export class ClaudeWatcher extends EventEmitter {
             this.socketServer.close();
             this.socketServer = null;
         }
-        try {
-            if (existsSync(SOCKET_PATH))
-                unlinkSync(SOCKET_PATH);
-        }
-        catch {
-            /* may already be gone */
-        }
+        clearStaleSocket(SOCKET_PATH);
     }
     // ── File Watcher (fallback) ──────────────────────────────────────────
     /** Start file watcher as fallback for when socket isn't available */

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": "@clearlysh/beehaven",
-  "version": "0.8.27",
+  "version": "0.8.30",
   "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.
@@ -60,15 +64,31 @@ handover. A mark of hand-placed béziers does not, and it shows.
 | **Counter-form** | the shape is the NEGATIVE space between forms | clever marks that survive one colour |
 | **Modular** | one unit repeated/rotated on a grid | systems, networks, collectives |
 
-**Build it as an `svg` node with a stated viewBox and derived numbers:**
+**Build it from native layers, every number derived from the construction** — the way an
+identity designer works in Figma, so each part of the mark stays a named, editable layer in the
+brand colour (never one generated or hand-written SVG):
 
 ```jsonc
-{"action":"canvas.create-node","args":{"name":"mark","type":"svg","x":120,"y":120,"w":240,"h":240,
- "svg":"<svg viewBox='0 0 240 240' xmlns='http://www.w3.org/2000/svg'>…</svg>"}}
+{"batch":[
+ {"action":"frame.create","args":{"name":"Mark","x":120,"y":120,"w":240,"h":240}},
+ {"action":"canvas.create-node","args":{"type":"ellipse","name":"mark/ring","parentId":"Mark",
+   "x":20,"y":20,"w":200,"h":200,"fill":"#1B4DFF"}},
+ {"action":"canvas.create-node","args":{"type":"ellipse","name":"mark/counter","parentId":"Mark",
+   "x":70,"y":70,"w":100,"h":100,"fill":"#FFFFFF"}},
+ {"action":"vector.create","args":{"name":"mark/blade","parentId":"Mark","closed":true,"fill":"#1B4DFF",
+   "points":[{"x":120,"y":20},{"x":220,"y":120},{"x":120,"y":120}]}},
+ {"action":"canvas.group","args":{"ids":["mark/ring","mark/counter","mark/blade"],"name":"mark"}}
+]}
 ```
 
-⚠ **`<text>` inside an `svg` node does NOT render headlessly** — no system fonts are loaded.
-Wordmarks are real text nodes, or outlined paths. Never live `<text>` in the mark.
+Here R = 100: the counter is R/2, the blade's corners sit on the circle. Curves are
+`vector.create` points with `hIn`/`hOut` control points (absolute coordinates) placed where the
+construction says; a quarter-circle's handle sits 0.552·R from its anchor. A counter-form is a
+ground-colour shape layered on top; `vector.boolean` makes a true cut-out when an editor is open.
+Raw SVG (`type:"svg"`) is only for importing a mark the client already has.
+
+⚠ **Wordmarks are real text nodes, or outlined paths** — and `<text>` inside an imported `svg`
+node does NOT render headlessly (no system fonts are loaded).
 
 **Test the mark against these before going further. A mark that fails any of them is not done:**
 
@@ -93,7 +113,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 +247,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

@@ -190,6 +190,19 @@ task changes a product's UI, the composition comes FIRST: build the screen and i
 `canvas.review` it, link it to the ticket (`work-link {ticketId, kind:"design", refKind:"composition",
 refId}`), then implement. `clearly-canvas` §0 has the details.
 
+No brand yet (`brand-tokens` answers `brand-not-found`) for a real company? Ask the person for their
+website rather than inventing a palette, then:
+
+1. `beehaven call brand-import '{"url":"theirsite.com","dryRun":true}'` — colours by role, faces, logos,
+   voice and shape, each with its reason in `provenance`. Tell the person what you read.
+2. Ask what to call the brand (`suggestedName` is what the site calls itself — a suggestion, not a default).
+3. `beehaven call brand-import '{"url":"theirsite.com","name":"<their answer>"}'` saves it (the read is
+   reused; the first brand becomes the workspace default). Without `name` nothing is saved:
+   `brand-name-required`.
+
+`brandId` + `apply:["colors","type"]` refreshes an existing brand as a new version instead. Licensed faces
+come back set in the closest free one — `faces` says which.
+
 ## When a write is refused
 
 `agent-denied-create` / `-update` / `-delete` mean your **capability matrix** said no. It covers the