@clearlysh/beehaven 0.8.30 → 0.8.31

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 = '2c7d78e7c945';
+export const BUILD_SHA = '3767a788c0ee';
 /** ISO-8601 minute precision, UTC. Rewritten in `dist/` by `scripts/stamp-build-channel.mjs`. */
-export const BUILD_TIME = '2026-10-13T06:00Z';
+export const BUILD_TIME = '2026-10-13T06:40Z';
 /**
  * The build identity as one short string, for `--version`.
  *

package/dist/commands/self-update.js

@@ -43,9 +43,10 @@ import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
-import { join, sep } from 'node:path';
+import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { usableUpdateDigest } from '../version-utils.js';
+import { compareVersions, usableUpdateDigest } from '../version-utils.js';
+import { npmUpdatePlan, latestNpmVersion, installedNpmVersion, installNpmVersionSync } from '../npm-update.js';
 /**
  * Which install this process is.
  *
@@ -83,8 +84,9 @@ export function updateHint(kind = installKind()) {
         return 'Run \x1b[1mbeehaven update\x1b[0m';
     if (kind === 'npx')
         return 'Run `npx @clearlysh/beehaven@latest` for the current npm release.';
+    // npm installs update themselves since CAN2-57 (the daemon hourly, `beehaven update` on demand).
     if (kind === 'npm')
-        return 'Run `npm install -g @clearlysh/beehaven@latest` to update this npm install.';
+        return 'Run \x1b[1mbeehaven update\x1b[0m (or `npm install -g @clearlysh/beehaven@latest`).';
     return 'This is a linked dev build — `npm run build` in beehaven_sdk/packages/cli.';
 }
 /**
@@ -113,9 +115,11 @@ export function runSelfUpdate(kind = installKind()) {
     if (kind === 'linked') {
         return { ok: false, message: 'This is a linked development build — refusing to overwrite it.\n  cd beehaven_sdk/packages/cli && npm run build' };
     }
-    if (kind === 'npm' || kind === 'npx') {
+    if (kind === 'npx') {
         return { ok: false, message: updateHint(kind) };
     }
+    if (kind === 'npm')
+        return runNpmSelfUpdate();
     const feed = (process.env.BEEHAVEN_CLI_FEED || 'https://downloads.clearly.sh/cli/').replace(/\/+$/, '');
     const installerUrl = process.env.BEEHAVEN_INSTALL_URL || 'https://www.clearly.sh/install.sh';
     const temp = mkdtempSync(join(tmpdir(), 'beehaven-self-update-'));
@@ -154,9 +158,32 @@ export function runSelfUpdate(kind = installKind()) {
         rmSync(temp, { recursive: true, force: true });
     }
 }
+/**
+ * ⚠ npm installs (the only Windows install) update with npm itself — see `npm-update.ts` for why
+ * it refuses rather than guessing when this copy is not npm's global install or the prefix is not
+ * writable. The daemon restarts itself after ITS hourly update; after this manual one the running
+ * daemon keeps the old code until restarted, so the message says so.
+ */
+function runNpmSelfUpdate() {
+    const manual = 'Update it by hand: npm install -g @clearlysh/beehaven@latest';
+    const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+    const plan = npmUpdatePlan(pkgRoot);
+    if (!plan.ok)
+        return { ok: false, message: `Can't update this npm install here: ${plan.reason}.\n  ${manual}` };
+    const latest = latestNpmVersion(plan.npm);
+    if (!latest)
+        return { ok: false, message: `Update failed: could not read the latest version from npm.\n  ${manual}` };
+    const current = installedNpmVersion(plan.globalRoot) ?? '0.0.0';
+    if (compareVersions(latest, current) <= 0)
+        return { ok: true, message: `Already up to date (${current}).` };
+    const r = installNpmVersionSync(plan, latest);
+    return r.ok
+        ? { ok: true, message: `${r.message} A daemon that is already running keeps the old version until: beehaven restart` }
+        : { ok: false, message: `${r.message}\n  ${manual}` };
+}
 /** True when this install can update itself at all — what the notifier uses to pick its wording. */
 export function canSelfUpdate(kind = installKind()) {
-    return kind === 'user';
+    return kind === 'user' || kind === 'npm';
 }
 /**
  * Is a bundled CLI present that the shell can NEVER reach, whatever its version?

package/dist/daemon.js

@@ -46,6 +46,7 @@ import { homedir, tmpdir } from 'os';
 import { join, dirname, relative } from 'path';
 import { fileURLToPath } from 'url';
 import { compareVersions, usableUpdateDigest } from './version-utils.js';
+import { npmUpdatePlan, installNpmVersion } from './npm-update.js';
 import { installKind } from './commands/self-update.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CONFIG_DIR = join(homedir(), '.beehaven');
@@ -963,9 +964,85 @@ function updatesAreManagedExternally() {
  *
  * ⚠ NOTHING ELSE CALLS IT. The daemon's timer is still the only production caller.
  */
+/** Said once per daemon, not hourly — see the managed-updates note below. */
+let announcedNpmUpdateBlocked = false;
+/**
+ * Start the freshly installed version and leave (shared by the curl and npm update paths).
+ * A CLI-spawned headless daemon is detached, with no supervisor to interpret exit 75, so it starts
+ * the new entry in a helper that waits until this process releases the IPC socket.
+ */
+async function restartForUpdate() {
+    if (process.env.BEEHAVEN_CLI_OWNED_DAEMON === '1') {
+        const child = spawn(process.execPath, [join(__dirname, 'daemon-entry.js'), '--restart-after-update', String(process.pid)], {
+            detached: true,
+            stdio: 'ignore',
+            env: process.env,
+        });
+        child.on('error', (error) => console.error(`  [update] Restart helper failed: ${error.message}`));
+        if (!child.pid)
+            throw new Error('could not start update restart helper');
+        child.unref();
+    }
+    if (daemonRelay?.isConnected())
+        await new Promise((r) => setTimeout(r, 500));
+    process.exit(75);
+}
+/**
+ * ⚠⚠ npm INSTALLS (THE ONLY WINDOWS INSTALL) NEVER AUTO-UPDATED (CAN2-57). This routine re-ran the
+ * bash installer, so it skipped every npm install and a Windows user stayed on their first version.
+ * They now update with npm itself — to the version the release manifest names (stable only) — when
+ * this copy IS npm's global install and its folder is writable; otherwise one line says why and
+ * what to run. No rollback file: `install.sh` cannot reinstall an npm package; a bad release is
+ * undone with `npm install -g @clearlysh/beehaven@<previous>`.
+ */
+async function checkAndAutoUpdateNpm() {
+    // A headless daemon's stdout goes nowhere, so the update story also goes to daemon.log.
+    const say = (m, level = 'info') => {
+        (level === 'error' ? console.error : console.log)(`  [update] ${m}`);
+        try {
+            logger[level]('daemon', `[update] ${m}`);
+        }
+        catch { /* logging never blocks an update */ }
+    };
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+        const res = await fetch(LATEST_MANIFEST, { signal: controller.signal });
+        clearTimeout(timeout);
+        if (!res.ok)
+            return;
+        const latest = (await res.json())?.version;
+        if (typeof latest !== 'string')
+            return;
+        const current = getCurrentVersion();
+        if (compareVersions(latest, current) <= 0)
+            return;
+        const plan = npmUpdatePlan(join(__dirname, '..'));
+        if (!plan.ok) {
+            if (!announcedNpmUpdateBlocked) {
+                announcedNpmUpdateBlocked = true;
+                say(`${latest} is available, but this npm install cannot update itself: ${plan.reason}. Run: npm install -g @clearlysh/beehaven@latest`);
+            }
+            return;
+        }
+        say(`Updating ${current} → ${latest} with npm...`);
+        const r = await installNpmVersion(plan, latest);
+        if (!r.ok)
+            throw new Error(r.message);
+        if (getCurrentVersion() !== latest)
+            throw new Error(`npm did not install ${latest}`);
+        say(`Updated to v${latest} — restarting...`);
+        await restartForUpdate();
+    }
+    catch (error) {
+        say(`Update failed: ${error?.message ?? error}`, 'error');
+    }
+}
 export async function checkAndAutoUpdate() {
     const owner = updatesAreManagedExternally();
     const runningKind = installKind(join(__dirname, 'daemon-entry.js'));
+    if (!owner && runningKind === 'npm')
+        return checkAndAutoUpdateNpm();
     if (owner || runningKind !== 'user') {
         // Said once at startup, not hourly — a line every hour about a thing that is working as
         // designed is how a log stops being read.
@@ -1017,19 +1094,6 @@ export async function checkAndAutoUpdate() {
             throw new Error(`installer did not install ${latest}`);
         }
         console.log(`  [update] Updated to v${latest} — restarting...`);
-        if (process.env.BEEHAVEN_CLI_OWNED_DAEMON === '1') {
-            // A CLI-spawned headless daemon is detached, with no supervisor to interpret exit 75.
-            // Start the new entry in a helper that waits until this process releases the IPC socket.
-            const child = spawn(process.execPath, [join(__dirname, 'daemon-entry.js'), '--restart-after-update', String(process.pid)], {
-                detached: true,
-                stdio: 'ignore',
-                env: process.env,
-            });
-            child.on('error', (error) => console.error(`  [update] Restart helper failed: ${error.message}`));
-            if (!child.pid)
-                throw new Error('could not start update restart helper');
-            child.unref();
-        }
         // Drop the temp tarball BEFORE exiting. `process.exit` skips `finally`,
         // so cleaning up only there would leak the whole release into /tmp on every
         // SUCCESSFUL update — the one path that always runs.
@@ -1046,13 +1110,9 @@ export async function checkAndAutoUpdate() {
             catch { }
             installerPath = null;
         }
-        // Give relay a moment to flush
-        if (daemonRelay?.isConnected()) {
-            await new Promise((r) => setTimeout(r, 500));
-        }
-        // Exit with non-zero so launchd/systemd restarts with the new version
-        // (KeepAlive > SuccessfulExit > false means exit 0 stays down)
-        process.exit(75);
+        // Start the new version and exit non-zero, so launchd/systemd also restarts with it
+        // (KeepAlive > SuccessfulExit > false means exit 0 stays down).
+        await restartForUpdate();
     }
     catch (error) {
         console.error(`  [update] Update failed: ${error?.message ?? error}`);

package/dist/npm-update.js

@@ -0,0 +1,138 @@
+/**
+ * npm-update — updating a CLI that was installed with `npm install -g` (CAN2-57).
+ *
+ * ⚠⚠ npm IS THE ONLY WINDOWS INSTALL, AND IT NEVER UPDATED. The daemon's hourly updater re-runs the
+ * bash `install.sh`, so it served only `~/.beehaven/cli` installs; `beehaven update` refused npm
+ * installs and printed the npm command instead. A Windows user stayed on whatever version they
+ * first installed until they noticed the notice. Both paths now call this module.
+ *
+ * ⚠ IT UPDATES THE COPY THAT IS RUNNING, OR NOTHING. The npm that sits beside the running Node is
+ * asked for its global root; if this package is not the one installed there (an npx run, a second
+ * Node, a copied folder), installing would create a SECOND copy that shadows or is shadowed by
+ * this one — the failure `self-update.ts` documents for curl installs. So it refuses and says why.
+ *
+ * ⚠ A GLOBAL PREFIX THE USER CANNOT WRITE IS NOT "TRY sudo". Windows (`%AppData%\npm`) and
+ * Homebrew/nvm prefixes are user-writable; a system `/usr/local` usually is not, and an unattended
+ * daemon must never escalate. Not writable → the one-line manual command, nothing else.
+ *
+ * ⚠ THE EXACT VERSION, NOT `@latest`. The caller passes the version from the release manifest
+ * (`latest.json`, stable only), so the channel is decided by our publish script, never by a dist
+ * tag someone moved by hand.
+ */
+import { execFile, execFileSync } from 'child_process';
+import { accessSync, constants, existsSync, readFileSync, realpathSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join, resolve } from 'path';
+export const PACKAGE = '@clearlysh/beehaven';
+const VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+/** The npm that belongs to the Node running this process, else whatever `npm` is on PATH. */
+export function npmCommand(platform = process.platform, execPath = process.execPath) {
+    const local = join(dirname(execPath), platform === 'win32' ? 'npm.cmd' : 'npm');
+    return existsSync(local) ? local : platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+/** Windows `.cmd` shims cannot be spawned without a shell (Node refuses with EINVAL since 18.20/20.12). */
+const needsShell = (cmd) => /\.cmd$/i.test(cmd);
+const quoteForShell = (s) => (/[\s"&|<>^]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s);
+/** Run npm synchronously; returns stdout. Never inside the package directory (Windows rename locks). */
+function npmSync(npm, args, timeoutMs) {
+    const shell = needsShell(npm);
+    return execFileSync(shell ? quoteForShell(npm) : npm, args, {
+        encoding: 'utf8',
+        cwd: homedir(),
+        timeout: timeoutMs,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        shell,
+        windowsHide: true,
+    });
+}
+/**
+ * Can this install update itself with npm? `pkgRoot` is the running package's root (the folder
+ * holding its package.json).
+ */
+export function npmUpdatePlan(pkgRoot, platform = process.platform) {
+    const npm = npmCommand(platform);
+    let globalRoot;
+    try {
+        globalRoot = npmSync(npm, ['root', '-g'], 30_000).trim();
+    }
+    catch (e) {
+        return { ok: false, npm, reason: `npm is not available (${String(e?.code ?? e?.message ?? e).slice(0, 80)})` };
+    }
+    const real = (p) => { try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    } };
+    const installed = join(globalRoot, ...PACKAGE.split('/'));
+    if (real(installed).toLowerCase() !== real(pkgRoot).toLowerCase()) {
+        return { ok: false, npm, globalRoot, reason: `this copy (${pkgRoot}) is not npm's global install (${installed})` };
+    }
+    try {
+        accessSync(globalRoot, constants.W_OK);
+        accessSync(installed, constants.W_OK);
+    }
+    catch {
+        return { ok: false, npm, globalRoot, reason: `npm's global folder is not writable by you (${globalRoot})` };
+    }
+    return { ok: true, npm, globalRoot };
+}
+/** The version npm's global install of this package reports, read from disk. */
+export function installedNpmVersion(globalRoot) {
+    try {
+        return JSON.parse(readFileSync(join(globalRoot, ...PACKAGE.split('/'), 'package.json'), 'utf8')).version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The newest published version, from npm (for `beehaven update`; the daemon uses the release manifest). */
+export function latestNpmVersion(npm) {
+    try {
+        const v = npmSync(npm, ['view', PACKAGE, 'version', '--registry=https://registry.npmjs.org'], 30_000).trim();
+        return VERSION_RE.test(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The arguments that install exactly `version` globally — exported so the shape is pinned. */
+export function npmInstallArgs(version) {
+    if (!VERSION_RE.test(version))
+        throw new Error(`not a release version: ${version}`);
+    return ['install', '-g', `${PACKAGE}@${version}`, '--no-audit', '--no-fund', '--registry=https://registry.npmjs.org'];
+}
+/** Install `version` (blocking — the CLI's `update`). Verifies what landed on disk. */
+export function installNpmVersionSync(plan, version) {
+    if (!plan.ok || !plan.globalRoot)
+        return { ok: false, message: plan.reason ?? 'npm update not possible here' };
+    try {
+        npmSync(plan.npm, npmInstallArgs(version), 5 * 60_000);
+    }
+    catch (e) {
+        const detail = String(e?.stderr || e?.message || e).trim().split('\n').slice(-3).join(' ').slice(0, 240);
+        return { ok: false, message: `npm install failed: ${detail}` };
+    }
+    const got = installedNpmVersion(plan.globalRoot);
+    return got === version
+        ? { ok: true, message: `Updated to ${version}.` }
+        : { ok: false, message: `npm reported success but ${got ?? 'nothing'} is installed, not ${version}.` };
+}
+/** Install `version` without blocking the event loop (the daemon's hourly updater). */
+export function installNpmVersion(plan, version) {
+    return new Promise((resolveP) => {
+        if (!plan.ok || !plan.globalRoot)
+            return resolveP({ ok: false, message: plan.reason ?? 'npm update not possible here' });
+        const shell = needsShell(plan.npm);
+        execFile(shell ? quoteForShell(plan.npm) : plan.npm, npmInstallArgs(version), {
+            cwd: homedir(), timeout: 5 * 60_000, shell, windowsHide: true,
+        }, (err, _out, stderr) => {
+            if (err)
+                return resolveP({ ok: false, message: `npm install failed: ${String(stderr || err.message).trim().split('\n').slice(-3).join(' ').slice(0, 240)}` });
+            const got = installedNpmVersion(plan.globalRoot);
+            resolveP(got === version
+                ? { ok: true, message: `Updated to ${version}.` }
+                : { ok: false, message: `npm reported success but ${got ?? 'nothing'} is installed, not ${version}.` });
+        });
+    });
+}

package/package.json

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

package/scripts/sync-skills.mjs

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

package/skills/clearly-docs/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: clearly-docs
+description: >-
+  Read, search, edit and recover a company's documents in a Clearly workspace.
+  Use the seven-tool MCP filesystem for ordinary work; use the `beehaven` CLI
+  only for document history, diffs, and restore. Load this whenever the answer
+  depends on what the company has written down, or when you are about to write
+  something down for it. Triggers: "what do our docs say", "find the doc about
+  X", "update the spec", "write this up", "add it to the docs", "has this
+  changed", "what did they edit", "search the wiki", "company knowledge", "our
+  documentation", "the PRD", "the runbook".
+---
+
+> **Tool names below are written UNPREFIXED** (`clearly_read`). Your runtime may expose them
+> with a server prefix — e.g. `mcp__plugin_clearly_clearly__clearly_read`. **Match by suffix,
+> not by exact name**: a skill written against the bare name resolves to nothing otherwise, and
+> the failure looks like "the tool doesn't exist" rather than "the name is decorated".
+>
+> **If no such tool is callable at all**, the Clearly MCP server isn't authorised in this
+> session — these skills still LIST when it isn't, so you find out by firing a dead call.
+> Authorise it (`/mcp`, or `claude mcp`).
+
+## What this is
+
+The workspace is a **filesystem**, not a chat surface with a search box.
+
+```
+~/                       every document
+~/clearly.md             what is settled for the whole workspace
+~/<Folder>/              one directory per project
+~/<Folder>/clearly.md    what is settled for that folder
+~/.archive/              put away — hidden, readable, read-only, still searched
+```
+
+Folders are projects. Documents are `.md` files named `<KEY> <Title>.md` — e.g.
+`CLR-42 Pricing.md`. The key is an address: `cat ~/CLR-42.md` works from anywhere, and so does
+the full name and the bare title.
+
+## The loop
+
+**Find it, then open it.** `clearly_glob` answers "what is it called", `clearly_grep` answers
+"where is this mentioned", and `clearly_read` opens what either one returned.
+
+```
+clearly_glob  { pattern: "~/**/*.md" }
+clearly_grep  { pattern: "pricing", limit: 5 }
+clearly_read  { target: "~/Prepress/CLR-42 Pricing.md" }
+```
+
+⚠ **`clearly_grep` takes a REGEX, unparsed** — `|`, `(`, `$` and quotes mean what they mean in a
+regular expression. Nothing shells out, so nothing eats them as syntax first.
+
+⚠ **Archived documents are excluded from both.** When any matched, the result carries
+`archivedHidden` saying how many — mention that rather than reporting a clean miss. Search the
+archive by naming it: `clearly_grep { pattern: …, path: "~/.archive" }`.
+
+**Structural questions — a date range, a null body, counts — have no keyword to search for**, so
+they go to SQL over the workspace's own tables. That is a CLI job, not an MCP tool:
+
+```
+beehaven call bash '{"command":"sql SELECT title, updated_at FROM notes WHERE project_id IS NULL LIMIT 20"}'
+```
+
+Read-only, one statement, credential columns redacted.
+
+## ⚠⚠ Read before you write, and check what changed
+
+This is the part that makes documentation stay true, and it is the part agents skip.
+
+The MCP read/edit/replace tools cover the current body. Document history is a separate CLI surface:
+
+- **`beehaven call document-status '{"limit":20}'`** lists recent changes. `mine: true` is the
+  certain signal that the active agent made the latest change. `by: "unknown"` means the log has
+  no author; it may be a browser edit or an older unstamped agent write, so do not claim a person
+  made it.
+- **`beehaven call document-diff '{"id":"<documentId>"}'`** follows up with added and removed
+  lines. Pass a `versionId` from status to compare against a specific checkpoint.
+
+Run status when you resume a conversation, and whenever they say something implying the document
+has moved — *"I rewrote that"*, *"take another look"*.
+
+⚠ **Their edit wins, always.** If a document now disagrees with something you concluded
+earlier, your conclusion is the stale one. You are keeping their documents, not defending your
+own record. Never quietly restore what they took out.
+
+## Editing
+
+**`clearly_edit` (find/replace) is the default. `clearly_replace` REPLACES the whole document.**
+
+To change one line of a 12,000-character document, `replace` makes you reproduce all 12,000 — and
+anything you fail to retype is gone with no error. It is also a lost-update machine: it writes
+whatever you last read, overwriting anything the human changed in between.
+
+- `clearly_edit` requires the `find` text to match **exactly once**. Ambiguity is REFUSED with a
+  count, never guessed — an agent that edits the first of three matches has changed something
+  nobody looked at.
+- Several independent document edits can be sent in one tool call with `batch`, but each batch
+  row is still one exact `{ target, find, replace, all? }` operation. There is no `multi_edit`
+  field and the batch is not transactional; inspect the per-item results and retry only failures.
+- `clearly_replace` does not accept `expected_content` or a commit-message field. If you must replace
+  a whole existing document, re-read it immediately before writing and verify the returned body.
+  Prefer `clearly_edit` whenever a precise passage change can express the job.
+
+## Comments and @mentions — say it beside the work, not instead of it
+
+A comment is ABOUT something; an edit changes it. When you have a question or a note for a person,
+leave it where they will see it, on the thing itself:
+
+```
+clearly_comment { target: "CLR-42", content: "Is this still the Q3 number? @sam" }
+clearly_comment { target: "<sheetId>", content: "Double-counts refunds", fields: { cell: "Plan!D12" } }
+clearly_comment { target: "<deckId>",  content: "Tighten this headline", fields: { slide: 3 } }
+clearly_read  { type: "comment", target: "SS-41" }          # the thread, on any item
+clearly_read  { type: "comment", target: "@me" }            # where YOU were @mentioned
+clearly_edit  { type: "comment", target: "<mentionId>", changes: { acknowledged: true } }
+```
+
+`target` is the item — a document, sheet, deck, ticket, board, thought or canvas, by id, key or exact
+title. Anchor with `fields.quote` (document), `slide` (deck, required), `cell` (sheet), `column`
+(board) or `pinId` / `x`,`y` (canvas); an anchor the item cannot carry is refused, never dropped.
+
+`@handle` mentions a person (notified) or an agent (queued in its inbox). Get real handles with
+`clearly_read { type: "comment", target, includeMentionables: true }`. The write's result lists
+`mentions`, and `unmatchedMentions` for any handle that reached **no one** — say so, do not assume.
+Acknowledge a mention once you have acted on it, or it comes back in every session.
+
+## `clearly.md` — what is settled
+
+Not a document like the others. It holds what this place IS (the work, the constraints, the
+vocabulary, the decisions that stopped moving) and **how this person wants to be worked with** —
+length, tone, format, and what irritates them, which is said once in passing and worth more than
+anything they praise.
+
+Fold a conclusion into it once it has stopped moving. Reach for `edit`, never `replace`.
+
+## Report what MOVED
+
+*"You added a paragraph about the 12-hour window to Pricing and removed the line about three
+credits"* is a report. *"I've updated the note"* is not — it costs a turn and says nothing they
+could not have assumed.
+
+## What not to do
+
+- **Do not tidy unasked.** A document that looks redundant or superseded is still theirs. If two
+  say the same thing, say so and let them choose.
+- **`delete` archives, it does not erase** — the document moves to `~/.archive/`, stays readable
+  and comes back. Report it as **archived**; "deleted" makes someone believe something is gone
+  that is not.
+- **Do not invent a media line.** `![caption](url)` renders a photo, audio or video by file
+  extension. You cannot upload, so never write one pointing at a URL you guessed — it renders
+  broken, which reads as their photo being lost. Move existing lines; never fabricate one.

package/skills/clearly-init/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: clearly-init
+description: >-
+  Connect a Clearly workspace to Claude Code or Codex and prove both the MCP and
+  CLI paths work. Prefer browser OAuth for remote HTTP clients; when an agent-bound
+  bearer credential is required, mint and install it with the active `beehaven`
+  identity. Use FIRST whenever a Clearly tool is refused for auth, returns nothing
+  on a workspace that should have content, or the user has never connected.
+  Triggers: "connect Clearly", "set up Clearly", "sign in to Clearly",
+  "authenticate", "install the MCP", "add the MCP token", "it says unauthorized",
+  "the tools are not showing up", "/mcp shows nothing", "which workspace am I in".
+---
+
+> **Tool names below are written UNPREFIXED** (`clearly_read`). Your runtime may
+> expose them with a server prefix — e.g.
+> `mcp__plugin_clearly_clearly-staging__clearly_read`. **Match by suffix, not by
+> exact name**: a skill written against the bare name resolves to nothing otherwise, and
+> the failure looks like "the tool doesn't exist" rather than "the name is decorated".
+>
+> **If no such tool is callable at all**, the Clearly MCP server isn't authorised in this
+> session — note that these skills still LIST when it isn't, so you find out by firing a
+> dead call. Authorise it (`/mcp`, or `claude mcp`), or if you have a shell, use the
+> `beehaven` CLI and its own `clearly-canvas` skill instead.
+
+# `/clearly:init` — connect a Clearly workspace to Claude Code or Codex
+
+Run this once per machine. The plugin's `.mcp.json` points at
+`https://relay.clearly.sh/mcp`; complete authentication and verify the connection before doing
+workspace work.
+
+## Steps
+
+### 1. Authenticate (OAuth — browser sign-in)
+
+The plugin already wires the MCP server. Prefer browser OAuth:
+
+- **In Claude Code (recommended)**: run `/mcp`, select `clearly`, and choose **Authenticate**. A browser window opens for sign-in; approve and it closes itself. No token.
+- **From the shell**: `claude mcp login clearly` — same browser sign-in flow.
+- **In Codex**: `codex mcp login clearly`. If the server was added outside the plugin first, run
+  `codex mcp add clearly --url https://relay.clearly.sh/mcp`, then log in.
+
+The sign-in grants scoped access (`rpc:read` for search and read; add `rpc:write` to let the
+agent write documents and create boards or tickets). Sign out or revoke with the client's MCP
+logout command, or from Settings → **Developers** in the app.
+
+### Agent-bound token path (CLI and automation)
+
+Use this when the client cannot complete OAuth or when the credential must act as a specific agent
+identity. Sign in and select the identity first:
+
+```bash
+beehaven agent login <agent-name>
+beehaven connect home
+beehaven agent whoami
+beehaven mcp install --client codex
+```
+
+The installer writes through the client's own config command and never prints the token. Restart
+the client afterward. A static token normally carries `rpc:read` and `rpc:write`; `agent:ask` is
+OAuth-only and `rpc:admin` is reserved for configured platform admins. Never paste a bearer token
+into a document, ticket, canvas, log, or chat response.
+
+> **Working in more than one workspace?** A client stores one credential per server entry, so two
+> workspaces behind a single entry collide. Use `https://relay.clearly.sh/mcp/w/<workspaceId>` as a
+> second entry — see [the MCP docs](https://clearly.sh/docs/mcp).
+
+### 2. Verify
+
+Run `/mcp` in Claude Code, or `codex mcp list` in Codex. You should see `clearly` authenticated
+with **7 tools**:
+
+**Seven MCP tools, split by what they DO rather than by what they act on.** The four CRUD tools
+cover every artifact type — document, canvas, sheet, deck, board, ticket, project — so the tool fixes
+whether it reads or writes and `type` says what it touches.
+
+- **`clearly_catalog`** — optional, lazy machine-readable schemas. Use `{ type, operation }` before a type-specific write/edit; omit both for the compact capability overview.
+- **`clearly_read` / `clearly_create` / `clearly_edit` / `clearly_replace` / `clearly_delete`** — open one, make a new one, change part of one, overwrite one's whole body, archive one. Each takes a uniform same-operation `batch`.
+- **`clearly_comment`** — comment on any item (with @mentions), or send and reply to messages.
+- **`clearly_grep` / `clearly_glob`** — find by content, find by name. Both span notes and code.
+
+Addressed by `target`: a path (`~/Q1/Plan.md`), a key (`CLR-42`) or an id. Folders are projects,
+documents are `.md`, canvases are `.scene.json` — the extension names the type, and you pass `type`
+when it does not.
+
+**Everything else is the `beehaven` CLI**, by action name — the canvas, the Company Brain, skills,
+scheduling, stickers, billing. `beehaven actions` lists them; `beehaven call <action> '<json>'` runs
+one:
+
+```bash
+beehaven call context-search '{"query":"per-seat billing","scope":"org"}'
+beehaven call canvas-act '{"compositionId":"c_…","batch":[…]}'
+```
+
+⚠ **That split is deliberate, not a gap.** A single tool that runs whatever action the caller names
+spans safe and unsafe operations at once — a connector-directory rejection criterion, and one the
+criteria explicitly refuse to let a description paper over. So the generic door is the shell, where
+Claude Code already lives and where every call is attributed to your agent.
+
+> ⚠ **Everything requires authentication.** There is no anonymous surface: as of 2026-09-11 both
+> `tools/list` and `tools/call` resolve a credential first, and every credential is bound to an
+> agent. A 401 carries an OAuth challenge, so a capable client can recover from it by itself —
+> but a caller with no token sees no catalog, by design.
+
+## Install the CLI — the other half of the surface
+
+The seven MCP tools cover reading, writing and searching artifacts. **Everything else — the canvas,
+the Company Brain, skills, stickers — is reached with `beehaven`**, and the skills in this plugin
+assume it is on PATH. Claude Code has a shell, so this is one command:
+
+```bash
+curl -fsSL https://clearly.sh/install.sh | sh
+beehaven login          # once, opens a browser
+beehaven status         # daemon + relay, both should read UP
+```
+
+⚠ **`beehaven: command not found` is the failure to expect**, and it does not look like a missing
+install — it looks like the skill being wrong. If a `beehaven call …` line fails that way, install
+it rather than reaching for an MCP tool that does not exist.
+
+⚠ **Do not restart the user's daemon to fix something.** It is theirs; `beehaven status` tells you
+what is wrong and the message says which command fixes it.
+
+Then load the usage skill: it teaches the Company Brain + self-prompting loops — see `clearly-workflows`.
+
+A quick functional test:
+> "Map my Clearly workspace's brain using the clearly MCP."
+
+If Claude calls `clearly_catalog` and gets back the artifact types with their capabilities, the connection is live. It is a connection check and schema lookup, not a required preflight for ordinary reads/deletes.
+
+## Troubleshooting
+
+- **`Missing scope "rpc:write"`** — the sign-in didn't grant write access. Run `claude mcp logout clearly`, then re-authenticate (`/mcp` → **Authenticate**) and approve the write scope.
+- **`Not authenticated` / calls rejected** — the session expired or was revoked. Re-authenticate with `claude mcp login clearly` (or `/mcp` → **Authenticate**).
+- **`clearly` shows in `/mcp` but as unauthenticated** — the endpoint is preconfigured by the plugin; you still need to complete the browser sign-in. Select `clearly` → **Authenticate**.
+- **`Network error reaching ...`** — relay.clearly.sh might be down (rare); check https://clearly.sh status page.

package/skills/clearly-workflows/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: clearly-workflows
+description: >-
+  Use the Clearly workspace as a COMPANY BRAIN — search the org's accumulated
+  context (decisions, facts, prompts, docs), write conclusions back so the next
+  agent inherits them instead of re-deriving them, and inherit the team's
+  skills. Use when a question is about what this company already decided or
+  knows, and after you work something out that the next person would otherwise
+  rediscover. Triggers: "what did we decide", "why did we do it this way", "has
+  anyone looked at this", "remember this", "write that down", "what do we know
+  about X", "company context", "our decisions", "prior art", "institutional
+  knowledge", "so nobody has to work this out again".
+---
+
+> **Tool names below are written UNPREFIXED** (`clearly_read`). Your runtime may
+> expose them with a server prefix — e.g.
+> `mcp__plugin_clearly_clearly-staging__clearly_read`. **Match by suffix, not by
+> exact name**: a skill written against the bare name resolves to nothing otherwise, and
+> the failure looks like "the tool doesn't exist" rather than "the name is decorated".
+>
+> **If no such tool is callable at all**, the Clearly MCP server isn't authorised in this
+> session — note that these skills still LIST when it isn't, so you find out by firing a
+> dead call. Authorise it (`/mcp`, or `claude mcp`), or if you have a shell, use the
+> `beehaven` CLI and its own `clearly-canvas` skill instead.
+
+# Working a Clearly workspace (Company Brain)
+
+Clearly is a **company brain over MCP**: every prompt + agent response is auto-cataloged into a searchable, ranked archive, with documents, decisions, and durable facts alongside. Treat it the way you'd treat a repo — read before you write, and write so the next agent inherits your work.
+
+If the `clearly` server isn't connected yet, run the `clearly-init` skill first.
+
+## 1. Orient before you act
+
+Run `beehaven call context-map` once at the start. It returns the brain's size (prompts / responses / facts), the recurring topics, and the org/teams it can federate across. Use it to decide whether the answer already exists.
+
+## 2. Retrieve context (don't re-derive it)
+
+`beehaven call context-search '{ "query": …, "scope"?, "kinds"?, "limit"? }'` is ONE ranked search across prompts, agent responses, documents/PRDs, and facts — use it instead of guessing or asking the user what they already decided.
+
+- `scope: "workspace"` (default) searches this workspace.
+- `scope: "org"` **federates across every workspace in the org**, merges + re-ranks by relevance, and excludes private artifacts + personal facts. Use it for "what has anyone on the team decided/built about X".
+- `kinds`: narrow to `["document"]`, `["prompt"]`, etc.
+
+Each hit carries `kind`, `ref` (the id to fetch in full), `title`, `snippet`, `score`, and `meta` (intent, tags, `sourceWorkspace`).
+
+**Always search before writing** — it prevents duplicate PRDs/decisions and surfaces prior context you'd otherwise miss.
+
+## 3. Write context BACK so it compounds
+
+When you produce something durable — a PRD, a decision, a spec, a research summary — file it with `context-write`:
+
+```jsonc
+beehaven call context-write '{
+  "title": "Per-seat billing decision",
+  "body":  "We charge per seat; usage is per-seat with shared top-up overflow. Rationale: …",
+  "kind":  "decision",          // doc | note | decision | prd
+  "tags":  ["billing","pricing"],
+  "fact":  "Billing is per-seat with shared top-up",   // optional one-line takeaway
+  "private": false               // true → workspace-local, never federated across the org
+}'
+```
+
+It creates the document AND files a searchable catalog entry, so the very next `context-search` finds it. Mark anything sensitive `private: true`.
+
+⚠ **Why these are CLI calls and not MCP tools.** The MCP surface is seven tools split by what they do to an artifact (`clearly_catalog · _read · _write · _edit · _delete · _grep · _glob`); the Company Brain's verbs are workspace ACTIONS, reached by name through the shell. Once a document exists, `clearly_grep` and `clearly_read` open it like any other.
+
+## 4. Inherit the team's skills
+
+The workspace has its own skills (procedures the team grew). Before improvising a multi-step task, check whether one exists:
+
+- `beehaven call skill-list '{"includeWorkspace":true}'` → the skill cards (name + when-to-use).
+- `beehaven call skill-get '{"id":"…"}'` → the full step-by-step instructions for the one whose trigger matches.
+
+Follow the loaded procedure rather than inventing your own — that's how you work *the way this workspace works*.
+
+## Anything else
+
+`beehaven actions` lists every workspace action with its description; `beehaven call <action> '<json>'` runs one. Reach for these when the seven MCP tools don't cover what you need — which is most things beyond reading, writing and searching artifacts.
+
+## Rules of thumb
+
+- **Read → act → write back.** Search first; file durable outcomes so they persist.
+- **`scope:"org"`** for cross-team questions; **`private:true`** for sensitive writes.
+
+<!-- A "Schedule your future self" section documenting `clearly_schedule_wake` was removed on
+     2026-08-02: the tool is in ZERO entries of mcp-server.ts's tool list and `schedule-wake` is
+     not a registered RPC, so every example here failed. Restore only when it is in tools/list. -->
+
+- **Check `beehaven call skill-list`** before hand-rolling a known procedure.

package/skills/index.json

@@ -83,5 +83,40 @@
       "SKILL.md"
     ],
     "sha": "b3f47988cb9235b9"
+  },
+  {
+    "name": "visualize",
+    "files": [
+      "SKILL.md"
+    ],
+    "sha": "ce9410c1ba7b3457"
+  },
+  {
+    "name": "sticker-pack",
+    "files": [
+      "SKILL.md"
+    ],
+    "sha": "f029503ebae59c64"
+  },
+  {
+    "name": "clearly-docs",
+    "files": [
+      "SKILL.md"
+    ],
+    "sha": "388be4de86f59eb4"
+  },
+  {
+    "name": "clearly-init",
+    "files": [
+      "SKILL.md"
+    ],
+    "sha": "d4dfdd76c7c0a108"
+  },
+  {
+    "name": "clearly-workflows",
+    "files": [
+      "SKILL.md"
+    ],
+    "sha": "f26dbbc90929ebe7"
   }
 ]

package/skills/sticker-pack/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: sticker-pack
+description: Turn an idea into a printable, die-cut STICKER SHEET on a Clearly canvas — Clearly's own sticker-vending-machine pipeline surfaced as an agent skill. Generates a cohesive SET of transparent stickers, lays them out as a sheet (frame + gridded stickers + a vector kiss-cut cutline layer), and hands back a print-ready bundle. Load this when the user says "make me stickers / a sticker pack / a sticker sheet about X", "turn this into stickers", "design stickers for my brand / startup / cat", or "I want die-cut stickers". The fun, inherently-shareable corner of the canvas skill set.
+---
+
+> **⚠ CANVAS AND STICKER WORK GO THROUGH THE CLI, NOT AN MCP TOOL.** Anything written
+> `beehaven call <action>` below is a literal command. The MCP surface is seven tools split
+> by operation; the ~1,000 workspace actions are reached by name through the shell.
+
+# Sticker pack — idea → printable die-cut sheet
+
+Stickers are the most organically viral thing Clearly makes: a generated die-cut pack someone actually prints and slaps on a laptop *is* the share. This skill drives Clearly's real sticker-vending pipeline — the same one behind the studio — straight onto a canvas.
+
+Install the `beehaven` CLI, sign in as an agent, and connect the intended workspace first
+(`clearly-init` handles setup). Then read `clearly-canvas` for the primitives and the
+perceive→act→revise loop. This skill adds the **generation** step on top of it.
+
+## The one core tool (and a heads-up)
+
+The sticker pipeline runs through **`sticker-sheet-gen`**, a real workspace action. It is NOT (yet) a dedicated MCP tool, so you call it through the generic dispatcher:
+
+```jsonc
+beehaven call sticker-sheet-gen '{ … }'
+```
+
+> ⚠ **This is a CLI action, not an MCP tool, and that is settled rather than pending.**
+> `clearly_sticker_generate` **does not exist** and is not planned — an earlier version of this
+> note called it a missing piece. The MCP surface is seven tools split by operation, and a
+> per-feature tool for every workspace action is the 139-tool surface that was withdrawn. The
+> action is production code — the same pipeline the paid studio uses — and the CLI reaches it with
+> full attribution.
+
+**It is slow (30–90s), async, and costs the user a sheet credit.** Pass a `compositionId` and the pipeline does the canvas work for you: when the art lands, it places a **transparent parent frame ("Sticker sheet")**, every cut-out sticker nested as its own `image` node (drag one out!), and the **die-cut contour as a nested vector `svg` layer ("Cutline (kiss-cut)")**. The cutline is true vector — exported as the spot cut layer, never rasterized.
+
+The call awaits the pipeline (racing a 90s timeout) so you usually get the **full result back** — `{ ok, sheetId, stickerCount, sheetUrl, placed }`. If it ran long you get `{ sessionId, timedOut: true }`; then perceive until the frame appears (see step 2).
+
+## 1. Brief — turn the idea into a cohesive set
+
+Don't just forward the user's sentence. Shape it into a **set with a through-line**: one subject family, one style, one palette, consistent line weight. Then list the concepts back before spending the credit.
+
+> *"Stickers for your plant shop — I'm thinking a cohesive 9-sticker set, flat-color cottagecore, sage + terracotta palette, chunky outlines: 1) monstera leaf, 2) watering can, 3) 'plant mom' badge, 4) terracotta pot, 5) snail, 6) sun, 7) 'grow' lettering, 8) seed packet, 9) trowel. Generate this sheet?"*
+
+A sticker sheet is ONE generation, not N — the model draws the whole cohesive grid. So the brief = the `prompt` (subject + vibe + palette), plus `style` and `stickerCount`.
+
+## 2. Generate — one call, drop on the canvas
+
+Make a canvas first (or reuse one), then fire the gen with `compositionId` so it lands:
+
+```jsonc
+beehaven call composition-create '{ "title": "Plant shop stickers" }'
+// → { "id": "c_…" }
+
+beehaven call sticker-sheet-gen '{
+  "compositionId": "c_…",
+  "prompt": "cottagecore plant-shop stickers: monstera leaf, watering can, terracotta pot, snail, sun, seed packet — flat color, chunky outlines, sage green + terracotta palette",
+  "style": "cottagecore",
+  "stickerCount": 9,
+  "bleedStyle": "halo",
+  "aspectRatio": "2:3"
+}'
+// → { ok:true, sheetId:"sht_…", stickerCount:9, sheetUrl:"https://…", placed:{ stickers:9, cutline:true } }
+```
+
+Input shape (all optional except `prompt`):
+
+| Field | Meaning |
+|---|---|
+| `prompt`* | what the stickers depict — subject, vibe, palette |
+| `compositionId` | **pass it** — the canvas to drop the sheet onto (placeholder + frame + cutline) |
+| `style` | preset: `kawaii`, `planner`, `cottagecore`, `doodle`, … (omit → inferred) |
+| `stickerCount` | stickers on the sheet (e.g. 9, 16, 30). Default 30 |
+| `bleedStyle` | `halo` (default — white sticker outline) or `full-bleed` |
+| `aspectRatio` | sheet ratio: `1:1` `2:3` `3:2` `3:4` `4:3` `9:16` `16:9` |
+| `quality` | `standard` (default, 4K) or `premium` |
+| `seed` | reproducibility |
+
+**Handle the async/loading case.** If the response is `{ sessionId, timedOut: true }` (no `placed`), the gen is still running — the ⏳ placeholder is already on the canvas. Poll until the real frame lands:
+
+```jsonc
+canvas-perceive { "compositionId": "c_…", "format": "text" }
+// look in `contents` for a frame named "Sticker sheet" with image children
+// + an svg layer "Cutline (kiss-cut)". When it's there, the sheet is done.
+```
+
+On a hard failure the response carries an `error` (`no_exports_remaining` → user needs to buy a sheet; `rate_limit_exceeded` → back off `retryAfter`s) and the credit is auto-refunded — relay that plainly, don't retry blindly.
+
+## 3. The sheet is already laid out — make it presentable
+
+The pipeline placed the frame, the cut-out stickers (gridded, native pixel size), and the cutline layer in ONE write. Your job is polish, via `canvas-act` (see `clearly-canvas`):
+
+- **Perceive first**, read the `backgroundColor`, then drop a `text` title over the frame: "Plant shop · 9 stickers · kiss-cut".
+- A tiny caption noting the **"Cutline (kiss-cut)"** layer is the spot cut path (vector) — toggle it to preview the die-cut.
+- If the grid is cramped, `canvas.update-nodes` to nudge the frame into the user's `gaze`.
+
+Don't rebuild the grid by hand — the pipeline already nested everything correctly. Only add labels + framing context.
+
+## 4. Export — the printable bundle
+
+When they're happy, pull the print kit:
+
+```jsonc
+beehaven call sticker-sheet-export '{ "sheetId": "sht_…" }'
+// → { zipUrl, pdfUrl, sheetUrl, stickerUrls:[…], stickerCount, hasCutFile:true }
+```
+
+- `zipUrl` — the FULL kit: print-ready **PDF** + **cut-file SVG** (the spot cut layer) + every individual sticker PNG + the composited sheet.
+- `pdfUrl` — drop straight into a Cricut / Roland / Stickermule flow.
+- Omit `sheetId` to export their most recent sheet.
+
+Hand the user the `pdfUrl` / `zipUrl` and tell them the SVG cut file is what a plotter reads for the die-cut contour.
+
+## 5. Keep the human in the loop
+
+The whole point of the canvas is steering by gesture. After the sheet lands: *"It's on your canvas — tell me 'more like #2', 'swap to a blue palette', or 'add a cat'."* Then re-run `sticker-sheet-gen` with the revised `prompt`/`style`/`seed` (reuse `seed` to keep a look, change it to re-roll), and re-perceive. Iterate until they love it, *then* export.
+
+## The viral bit
+
+A real die-cut pack — transparent stickers, a visible kiss-cut contour, a print-ready PDF the user actually sends to a sticker printer — is the single most shareable output Clearly has. People post the laptop, not the prompt. So make every sheet land clean: cohesive set, honest cutline, one screenshot that reads as "I generated these and printed them." The sticker IS the share.
+
+## Single-sticker fallback
+
+For ONE vector sticker (not a sheet), draw it natively with `canvas-act` like a designer: shapes and `vector.create` pen paths in a frame, named and grouped, with the white border as its own closed path behind the art. Use `studio-image-generate` for a painterly raster sticker, and `format:'svg'` only when a generated SVG file is asked for. If `sticker-sheet-gen` is ever unavailable, the manual sheet = `studio-image-generate` per concept (transparent), then `canvas-act` → `frame.create` + one `canvas.create-node {type:'image'}` per sticker on a grid + a closed `vector.create` cutline outline. But that's the cold path — the pipeline above is the real, supported one.
+
+## Rules of thumb
+
+- **One gen = one whole sheet.** Don't loop the call per sticker; the model draws the cohesive grid in a single pass.
+- **Always pass `compositionId`** — that's what lands the placeholder, frame, stickers, and cutline. No `compositionId` = no canvas output.
+- **It's slow + costs a credit.** Confirm the brief BEFORE generating; relay `no_exports_remaining` / `rate_limit_exceeded` plainly (credit auto-refunds on failure).
+- **`timedOut:true` ≠ failed** — the gen is still running; `canvas-perceive` until the "Sticker sheet" frame appears.
+- **The cutline is vector** ("Cutline (kiss-cut)" svg layer) — it's the spot cut path; the export SVG/PDF is what a plotter cuts.
+- **Iterate by re-genning**, reuse `seed` to hold a look, then **export last**.
+- **Reach `sticker-sheet-gen` / `sticker-sheet-export` with `beehaven call`** — they are workspace actions, not MCP tools, and will not become tools.

package/skills/visualize/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: visualize
+description: Turn any concept, answer, or described system into a clean DIAGRAM on a Clearly spatial canvas instead of a wall of text. Load this when the user asks to "diagram this", "draw it", "sketch it", "map it out", "visualize this",
+  "explain visually", "show me how X works", "flowchart this", "make a diagram" — AND proactively whenever YOUR OWN answer would be clearer as a picture than a paragraph (a flow with branches, who-calls-whom, a schema, an architecture, options on axes). Picks the right diagram type for the content and builds it with the canvas primitives.
+---
+
+> **⚠ CANVAS WORK GOES THROUGH THE CLI, NOT AN MCP TOOL.** Anything written
+> `canvas-act { … }` / `canvas-perceive { … }` below is an ACTION, run as
+> `beehaven call canvas-act '<the JSON>'`. The payloads are exactly as shown. The MCP
+> surface is seven tools split by operation, and a single tool that dispatches 230
+> caller-named canvas actions spans reads, writes and deletes at once — which is why the
+> generic door is the shell instead. `clearly_read { target, type: "composition" }` still
+> reads a canvas as an artifact.
+
+# Visualize — draw it, don't write it
+
+Some answers are paragraphs. Many are **pictures pretending to be paragraphs**: a flow with branches, a request hopping between services, a schema, a tradeoff matrix. The moment relationships matter, prose makes the reader rebuild the shape in their head. A diagram hands them the shape — spatial layout *is* the explanation, it's glanceable, and it's screenshot-shareable in a way a wall of text never is.
+
+So: when you catch yourself about to write three paragraphs explaining how something connects, **draw it on the canvas instead** (and you can still say the one-line version in chat).
+
+Prereq: the `beehaven` CLI is installed, signed in as an agent, and connected to the intended
+workspace (run `clearly-init` if not). **Read `clearly-canvas` for the tool contract** —
+`canvas-perceive` / `canvas-act` / `canvas-catalog`, `frame.create`, `canvas.create-node`
+(text/rect/ellipse/svg/line), first-class `arrow.create`, and nesting via `parentId` with
+frame-relative coordinates. This skill is the *diagram cookbook* on top of those primitives.
+
+## Pick the type (1-line heuristic each)
+
+| If the content is… | Draw a… |
+|---|---|
+| an answer you'd write as multiple paragraphs | **Explain-an-answer** (boxes + arrows) |
+| steps, especially with branches | **Flowchart** (boxes + decision diamonds) |
+| who-talks-to-whom over time | **Sequence diagram** (lifelines + message arrows) |
+| services / data stores and their calls | **Architecture** (frames + cylinders + arrows) |
+| things and the relationships between them | **ER / schema** (entity boxes + cardinality lines) |
+| one idea exploding outward into subtopics | **Mind-map** (central node + radial branches) |
+| options scored on a few criteria | **Comparison matrix** (grid of cells) |
+
+When unsure, ask: *is the story "then" (flowchart), "who" (sequence), "what's-related" (ER), or "which-is-better" (matrix)?*
+
+## The build loop (every diagram)
+
+1. **Get a canvas + perceive.** `canvas-perceive { compositionId, format:"text" }` → read `backgroundColor` (design WITH it — light ink on dark, dark ink on light) and `gaze.visibleWorldRect` (place work where the user is looking).
+2. **Batch the skeleton.** One `canvas-act` with a `batch` of frames + boxes on a grid. Capture every returned `{ id }`.
+3. **Wire the arrows** with `arrow.create {from, to}` — a first-class arrow that BINDS to the boxes (by returned id OR layer name) and FOLLOWS them when they move; `routing:"elbow"` for orthogonal flowcharts, `label` for the edge text (no separate label node needed). See clearly-canvas → Arrows / connectors.
+4. **Label** edges/branches with small `text` nodes at arrow midpoints.
+5. **Re-perceive** so the user can ink notes; read them back; revise with `canvas.update-nodes`.
+
+Grid discipline matters more than anything: equal gutters (24–40px), aligned edges, generous whitespace. A diagram that breathes reads as designed.
+
+---
+
+## Recipe: Explain-an-answer
+
+Your default upgrade from prose. **Layout:** 3–6 labelled boxes left→right (or top→down) in the order you'd say them, one arrow per "and then / because / leads to", a title text on top.
+
+```jsonc
+canvas-act { "compositionId": "c_…", "batch": [
+  { "action": "canvas.create-node", "args": { "type":"text", "name":"title", "text":"How a request gets billed", "x":0, "y":-40, "size":24, "fontWeight":700, "fill":"#fff" } },
+  { "action": "canvas.create-node", "args": { "type":"rect", "name":"b1", "x":0,   "y":0, "w":180, "h":72, "fill":"#1b2230", "stroke":"#3a465c", "radius":10 } },
+  { "action": "canvas.create-node", "args": { "type":"text", "name":"b1t", "text":"Member acts", "x":16, "y":26, "size":15, "fontWeight":600, "fill":"#e8edf5" } },
+  { "action": "canvas.create-node", "args": { "type":"rect", "name":"b2", "x":260, "y":0, "w":180, "h":72, "fill":"#1b2230", "stroke":"#3a465c", "radius":10 } },
+  { "action": "canvas.create-node", "args": { "type":"text", "name":"b2t", "text":"Debit seat budget", "x":276, "y":26, "size":15, "fontWeight":600, "fill":"#e8edf5" } },
+  { "action": "arrow.create", "args": { "from":"b1", "to":"b2", "routing":"elbow" } }
+]}
+```
+
+Chain more boxes at `x += 260` per step. Branch (e.g. "budget exhausted → top-up") with a second arrow going down to an offset box.
+
+## Recipe: Flowchart / process
+
+**Layout:** boxes top→down (or left→right), **rounded rect = action**, **diamond = decision**. Draw a diamond natively as a closed `vector.create` rhombus (4 points: top, right, bottom, left); give it two outgoing arrows labelled **Yes / No**.
+
+```jsonc
+canvas-act { "compositionId":"c_…", "batch":[
+  { "action":"canvas.create-node", "args":{ "type":"rect", "name":"start", "x":120, "y":0, "w":160, "h":56, "fill":"#173a2a", "stroke":"#2f6b4d", "radius":28 } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"startt", "text":"Invite sent", "x":156, "y":18, "size":14, "fontWeight":600, "fill":"#d6f5e4" } },
+  { "action": "arrow.create", "args": { "from":"start", "to":"decide", "label":"yes", "routing":"elbow" } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"yesl", "text":"yes", "x":216, "y":74, "size":12, "fontWeight":600, "fill":"#7c8497" } }
+]}
+```
+
+Rules: one entry, decisions are the only nodes with >1 exit, **every arrow labelled at branches**, keep the happy path straight and push error/No branches to the side.
+
+## Recipe: Sequence diagram
+
+**Layout:** each actor is a column — a header box at top + a vertical lifeline (`type:"line"`) running down. Messages are **horizontal arrows** between lifelines; **time flows down**, so each later message sits at a larger `y`.
+
+```jsonc
+canvas-act { "compositionId":"c_…", "batch":[
+  { "action":"canvas.create-node", "args":{ "type":"rect", "name":"a1", "x":0,   "y":0, "w":120, "h":40, "fill":"#1b2230", "stroke":"#3a465c", "radius":8 } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"a1t", "text":"Web", "x":48, "y":12, "size":14, "fontWeight":600, "fill":"#e8edf5" } },
+  { "action":"canvas.create-node", "args":{ "type":"line", "name":"a1life", "x":60, "y":40, "w":0, "h":300, "stroke":"#3a465c" } },
+  { "action":"canvas.create-node", "args":{ "type":"rect", "name":"a2", "x":280, "y":0, "w":120, "h":40, "fill":"#1b2230", "stroke":"#3a465c", "radius":8 } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"a2t", "text":"Home DO", "x":312, "y":12, "size":14, "fontWeight":600, "fill":"#e8edf5" } },
+  { "action":"canvas.create-node", "args":{ "type":"line", "name":"a2life", "x":340, "y":40, "w":0, "h":300, "stroke":"#3a465c" } },
+  { "action": "arrow.create", "args": { "from":"a1life", "to":"a2life", "label":"check-quota(userId)" } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"m1t", "text":"check-quota(userId)", "x":120, "y":52, "size":12, "fontWeight":500, "fill":"#aab3c2" } }
+]}
+```
+
+Place the message text just above its arrow. A return/response arrow points back left (flip `x1`/`x2`). Keep columns evenly spaced (~280px) so long labels fit.
+
+## Recipe: Architecture / system diagram
+
+**Layout:** each service is a `frame` (so it can hold a label + sub-parts); **data stores are cylinders** drawn natively (a `rect` body with an `ellipse` cap on top and one behind at the bottom, grouped with `canvas.group`); arrows are calls. Cluster by tier — a row of frames per tier (client / edge / data), with a faint heading text per row.
+
+```jsonc
+canvas-act { "compositionId":"c_…", "batch":[
+  { "action":"frame.create", "args":{ "name":"Worker", "x":0, "y":80, "w":200, "h":110, "fill":"#141a24" } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"wl", "text":"CF Worker", "x":14, "y":12, "size":14, "fontWeight":700, "fill":"#e8edf5", "parentId":"<WorkerFrameId>" } },
+  { "action": "arrow.create", "args": { "from":"Worker", "to":"HomeDO", "routing":"elbow", "label":"rpc" } }
+]}
+```
+
+Rules: one box per service (not per file), label every arrow with the call/protocol if non-obvious, keep tiers as aligned rows so dataflow reads in one direction.
+
+## Recipe: ER / schema
+
+**Layout:** each entity is a `frame` with a bold title row + a `text` node per field (stack fields at `y += 20`). Relationships are lines between frames with a **cardinality label** (`1`, `N`, `1..*`) near each end.
+
+```jsonc
+canvas-act { "compositionId":"c_…", "batch":[
+  { "action":"frame.create", "args":{ "name":"User", "x":0, "y":0, "w":180, "h":120, "fill":"#141a24" } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"u-h", "text":"User", "x":12, "y":10, "size":15, "fontWeight":700, "fill":"#fff", "parentId":"<UserFrameId>" } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"u-f1", "text":"id  PK", "x":12, "y":40, "size":13, "fontWeight":400, "fill":"#aab3c2", "parentId":"<UserFrameId>" } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"u-f2", "text":"email", "x":12, "y":60, "size":13, "fontWeight":400, "fill":"#aab3c2", "parentId":"<UserFrameId>" } },
+  { "action":"frame.create", "args":{ "name":"Seat", "x":300, "y":0, "w":180, "h":120, "fill":"#141a24" } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"s-h", "text":"Seat", "x":12, "y":10, "size":15, "fontWeight":700, "fill":"#fff", "parentId":"<SeatFrameId>" } },
+  { "action":"canvas.create-node", "args":{ "type":"line", "name":"u—s", "x":180, "y":40, "w":120, "h":0, "stroke":"#7c8497" } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"card1", "text":"1", "x":188, "y":24, "size":12, "fontWeight":700, "fill":"#7c8497" } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"cardN", "text":"N", "x":284, "y":24, "size":12, "fontWeight":700, "fill":"#7c8497" } }
+]}
+```
+
+Rules: PK/FK noted in the field text, one relationship line per FK, cardinality at BOTH ends so the reader knows which side is the "many".
+
+## Recipe: Mind-map
+
+**Layout:** one central node (an `ellipse` or pill `rect`), child topics radiating out, each connected by a **curved** branch (an open `vector.create` pen path with `hIn`/`hOut` control points, not a straight line). Place children evenly around the center; second-level topics hang off their parent.
+
+```jsonc
+canvas-act { "compositionId":"c_…", "batch":[
+  { "action":"canvas.create-node", "args":{ "type":"ellipse", "name":"core", "x":220, "y":160, "w":160, "h":80, "fill":"#2a1f3a", "stroke":"#7b5cc4" } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"coret", "text":"Company Brain", "x":250, "y":190, "size":15, "fontWeight":700, "fill":"#e9defb" } },
+  { "action":"canvas.create-node", "args":{ "type":"rect", "name":"c1", "x":480, "y":60, "w":150, "h":48, "fill":"#1b2230", "stroke":"#3a465c", "radius":24 } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"c1t", "text":"Org context", "x":500, "y":76, "size":13, "fontWeight":600, "fill":"#e8edf5" } },
+  { "action":"vector.create", "args":{ "name":"core→c1", "closed":false, "stroke":"#7b5cc4", "strokeWidth":2,
+    "points":[ { "x":382, "y":192, "hOut":{ "x":430, "y":192 } }, { "x":478, "y":92, "hIn":{ "x":430, "y":92 } } ] } }
+]}
+```
+
+Rules: keep the center visually heaviest, ~4–7 first-level branches (more → it's really a tree, use a frame layout), curve the branches so it reads organic not boxy.
+
+## Recipe: Comparison matrix
+
+Perfect for **"X vs Y vs Z"**. **Layout:** a grid of `rect` cells — top row = options, left column = criteria, body cells = the values. Tint the header row/column so the axes pop; fill body cells (green/amber/red) to make the winner obvious at a glance.
+
+```jsonc
+canvas-act { "compositionId":"c_…", "batch":[
+  { "action":"canvas.create-node", "args":{ "type":"rect", "name":"h-free", "x":160, "y":0, "w":120, "h":40, "fill":"#222b3a", "stroke":"#3a465c" } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"h-freet", "text":"Free", "x":196, "y":12, "size":14, "fontWeight":700, "fill":"#fff" } },
+  { "action":"canvas.create-node", "args":{ "type":"rect", "name":"h-pro", "x":280, "y":0, "w":120, "h":40, "fill":"#222b3a", "stroke":"#3a465c" } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"h-prot", "text":"Pro", "x":322, "y":12, "size":14, "fontWeight":700, "fill":"#fff" } },
+  { "action":"canvas.create-node", "args":{ "type":"rect", "name":"r-agents", "x":0, "y":40, "w":160, "h":40, "fill":"#222b3a", "stroke":"#3a465c" } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"r-agentst", "text":"Agents", "x":14, "y":52, "size":13, "fontWeight":600, "fill":"#cfd6e2" } },
+  { "action":"canvas.create-node", "args":{ "type":"rect", "name":"cell-free-agents", "x":160, "y":40, "w":120, "h":40, "fill":"#3a2417", "stroke":"#3a465c" } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"cell-free-agentst", "text":"1", "x":214, "y":52, "size":13, "fontWeight":600, "fill":"#f0c9a8" } },
+  { "action":"canvas.create-node", "args":{ "type":"rect", "name":"cell-pro-agents", "x":280, "y":40, "w":120, "h":40, "fill":"#173a2a", "stroke":"#3a465c" } },
+  { "action":"canvas.create-node", "args":{ "type":"text", "name":"cell-pro-agentst", "text":"10", "x":332, "y":52, "size":13, "fontWeight":600, "fill":"#a8f0c9" } }
+]}
+```
+
+Keep cells a uniform `w`/`h` and snap every cell to the grid (column `x`, row `y`); the alignment is what makes it read as a table, not scattered boxes.
+
+## The viral bit
+
+A clean diagram is **instantly screenshot-shareable** in a way a paragraph never is. Every text answer you convert into a tidy flowchart or architecture map is a tiny ad for the canvas — someone drops it in Slack and the reply is "wait, the AI just *drew* that?". So make each one frame-worthy: aligned grid, honest arrows, one clear read direction, a title. The diagram sells the next person on the surface.
+
+## Rules of thumb
+
+- **Prose smell test:** about to write 3+ paragraphs about how things connect? Draw it instead.
+- **Pick by the question:** "then" → flowchart, "who/when" → sequence, "what's related" → ER, "which is better" → matrix, "one idea outward" → mind-map.
+- **Skeleton in one `batch`**, then arrows, then labels — capture every returned `id`.
+- **Arrows = `arrow.create {from,to}`** — a first-class arrow that BINDS to the boxes and follows them (`routing:"elbow"` for flowcharts, `label` for edge text). Never hand-draw one as `type:"svg"` with a `marker-end`: that is a static path that does not move with its nodes; always pass `compositionId`; `name` on every create.
+- **Grid or it's a dump:** equal gutters, aligned edges, one read direction, generous whitespace.
+- **Perceive first** (design with `backgroundColor`, place in `gaze`); **re-perceive after** to read the human's ink and revise.
+- **Need an action not in clearly-canvas?** `canvas-catalog { surface:"all" }` — don't invent action names.