@clearlysh/beehaven 0.8.38 → 0.8.39

package/dist/agent-limit-refusal.js

@@ -0,0 +1,43 @@
+/**
+ * MCP2-65 — what `beehaven agent login <new name>` says when the workspace already has all the
+ * agents its plan includes (Free includes one).
+ *
+ * The identity mints at the account; joining the workspace is where the cap refuses
+ * (`agent-session-start` → automatic admission → `agent-create`, code `agent-limit-reached`). The
+ * reason alone left the person at a wall. The three choices, in this order:
+ *   1. log in as an agent they already have — one agent works from several apps;
+ *   2. upgrade for more agents (a pricing link: this is the terminal, not an MCP tool result);
+ *   3. archive one in Agents settings, then log in again.
+ *
+ * Pure: returns plain lines, the command colours them.
+ */
+export const AGENT_LIMIT_CODE = 'agent-limit-reached';
+export function isAgentLimitRefusal(code) {
+    return String(code ?? '') === AGENT_LIMIT_CODE;
+}
+/** An absolute pricing link from the refusal's relative `upgradeUrl` and the web origin for this env. */
+export function upgradeLink(origin, upgradeUrl) {
+    const base = String(origin || 'https://www.clearly.sh').replace(/\/+$/, '');
+    const raw = typeof upgradeUrl === 'string' ? upgradeUrl.trim() : '';
+    // Only a site-relative path is joined; anything else falls back to the pricing page.
+    const path = /^\/(?!\/)[A-Za-z0-9/_?=&.-]*$/.test(raw) ? raw : '/pricing';
+    return `${base}${path}`;
+}
+export function agentLimitLoginLines(opts) {
+    const agents = (Array.isArray(opts.details?.activeAgents) ? opts.details.activeAgents : [])
+        .map((a) => ({ id: String(a?.id ?? '').trim(), name: String(a?.name ?? '').trim() }))
+        .filter((a) => a.id && a.id !== opts.name);
+    const first = agents[0];
+    const listed = agents.map((a) => (a.name && a.name !== a.id ? `${a.id} ("${a.name}")` : a.id)).join(', ');
+    const reason = String(opts.reason || '').trim();
+    return {
+        headline: `Signed in, but ${opts.workspace || 'this workspace'} is at its agent limit${reason ? `: ${reason}` : '.'}`,
+        choices: [
+            first
+                ? `Use the agent you already have (one agent works from several apps): beehaven agent login ${first.id}${agents.length > 1 ? `   · also yours here: ${listed}` : ''}`
+                : 'Use an agent you already have (one agent works from several apps): beehaven agent login <its name>',
+            `Upgrade for more agents: ${upgradeLink(opts.origin, opts.details?.upgradeUrl)}`,
+            `Or archive one in Agents settings, then run: beehaven agent login ${opts.name}`,
+        ],
+    };
+}

package/dist/agent-state.js

@@ -365,11 +365,18 @@ export function loginSessionOutcome(started, thrown) {
         return { kind: 'started', sessionId: id, brief: payload?.brief };
     const err = payload?.error ?? started?.error;
     if (err) {
+        const code = String(payload?.code ?? started?.code ?? '');
         return {
             kind: 'refused',
             reason: typeof err === 'string' ? err : String(err?.message ?? JSON.stringify(err)),
-            code: String(payload?.code ?? started?.code ?? ''),
+            code,
             scope: String(payload?.scope ?? started?.scope ?? ''),
+            // MCP2-65: the agent-cap refusal names the caller's live agents and a pricing path, so the
+            // login can print the three choices instead of a bare reason.
+            ...(code === 'agent-limit-reached' ? { details: {
+                    activeAgents: Array.isArray(payload?.activeAgents) ? payload.activeAgents : [],
+                    ...(typeof payload?.upgradeUrl === 'string' ? { upgradeUrl: payload.upgradeUrl } : {}),
+                } } : {}),
         };
     }
     return { kind: 'refused', reason: 'the workspace returned no session', code: '', scope: '' };

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 = '6f5ce18b17c5';
+export const BUILD_SHA = '3026e5a147f9';
 /** ISO-8601 minute precision, UTC. Rewritten in `dist/` by `scripts/stamp-build-channel.mjs`. */
-export const BUILD_TIME = '2026-10-30T07:25Z';
+export const BUILD_TIME = '2026-11-12T22:52Z';
 /**
  * The build identity as one short string, for `--version`.
  *

package/dist/call-brief.js

@@ -58,14 +58,29 @@ function batchReceipt(action, r) {
     for (const s of steps)
         counts.set(verb(s?.action ?? '?'), (counts.get(verb(s?.action ?? '?')) ?? 0) + 1);
     const mix = [...counts].sort((a, b) => b[1] - a[1]).slice(0, 3).map(([a, n]) => (n > 1 ? `${a} ×${n}` : a)).join(', ');
+    /**
+     * CDS-163 — THE BATCH'S OWN DELTA WINS. Only update steps carry a per-step `canvasChanges`, so
+     * summing steps printed "+0 ~69 −0 layers" for a 343-step build that created 211 layers. The worker
+     * returns one batch-level `canvasChanges`, diffed over every node the batch addressed (creates
+     * included); the per-step sum is kept for an older worker that does not send it.
+     */
     let added = 0, changed = 0, removed = 0, sawDelta = false;
-    for (const s of steps) {
-        const d = s?.value?.canvasChanges;
-        if (d && typeof d === 'object' && !Array.isArray(d)) {
-            sawDelta = true;
-            added += Number(d.added || 0);
-            changed += Number(d.changed || 0);
-            removed += Number(d.removed || 0);
+    const isDelta = (d) => !!d && typeof d === 'object' && !Array.isArray(d);
+    if (isDelta(r.canvasChanges)) {
+        sawDelta = true;
+        added = Number(r.canvasChanges.added || 0);
+        changed = Number(r.canvasChanges.changed || 0);
+        removed = Number(r.canvasChanges.removed || 0);
+    }
+    else {
+        for (const s of steps) {
+            const d = s?.value?.canvasChanges;
+            if (isDelta(d)) {
+                sawDelta = true;
+                added += Number(d.added || 0);
+                changed += Number(d.changed || 0);
+                removed += Number(d.removed || 0);
+            }
         }
     }
     const rev = r.canvasNodesRev ?? [...steps].reverse().find((s) => s?.value?.canvasNodesRev != null)?.value?.canvasNodesRev;

package/dist/cli.js

@@ -1881,6 +1881,7 @@ async function run() {
      * would be refused while `conversations --json` worked.
      */
     const JSON_CAPABLE = new Set([
+        'doc', 'search',
         'admin', 'apps', 'd1', 'describe', 'explain', 'marketplace', 'secrets',
         'shop', 'user', 'webhook', 'webhooks', 'workspaces', 'ws',
         // Honour what the modules already implement.

package/dist/commands/agent.js

@@ -26,6 +26,7 @@ import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { rpcOnce } from '../ipc-client.js';
 import { accountMintRequest, accountMintResponse } from '../agent-mint-response.js';
+import { agentLimitLoginLines, isAgentLimitRefusal } from '../agent-limit-refusal.js';
 import { saveAgent, loadAgent, listAgents, deleteAgent, findAgentByAvatar, isValidAgentName, resolveActiveAgent, activeAgentName, saveAgentSession, clearAgentSession, clearAgentSessionId, decodeAgentTokenClaims, } from '../agent-state.js';
 const VALID_KINDS = ['claude-code', 'daemon-agent', 'clearly-ai'];
 export const FREE_SKINS = [
@@ -699,6 +700,12 @@ async function agentLogin(args, values) {
     }
     catch (err) {
         console.error(`  Could not mint identity: ${err?.message ?? err}`);
+        if (String(err?.code) === 'identity-limit-reached') {
+            // MCP2-71: the account's safety ceiling — no plan lifts it; signing in as one you have always works.
+            console.error('  Sign in as an agent you already have: beehaven agent list, then beehaven agent login <name>');
+            console.error('  Or delete one you no longer use in Agents, then run this again.');
+            process.exit(1);
+        }
         if (!err?.code || /^(ECONN|ENOENT|ETIMEDOUT)/.test(String(err.code)))
             console.error('  Is the daemon connected? Check with: beehaven status');
         process.exit(1);
@@ -964,6 +971,21 @@ async function agentLogin(args, values) {
         console.log(`  ${green('◷')} Workspace work session ${cyan(outcome.sessionId.slice(0, 8))} started.`);
         printBrief(outcome.brief);
     }
+    else if (outcome.kind === 'refused' && isAgentLimitRefusal(outcome.code)) {
+        // MCP2-65: at the plan's agent limit, say what to do — not just that it was refused.
+        const { resolveAuthOrigin } = await import('../browser-login.js');
+        const lines = agentLimitLoginLines({
+            name, workspace: (await workspaceLabel(chosenWorkspace)).split(/ {2}\(| — /)[0], reason: outcome.reason,
+            details: outcome.details, origin: resolveAuthOrigin().authOrigin,
+        });
+        console.log('');
+        console.error(`  ${yellow('⚠')} ${lines.headline}`);
+        console.error('    Your choices:');
+        for (const line of lines.choices)
+            console.error(`    · ${line}`);
+        console.error(dim(`    Calls from this session run as ${name} and will be refused — they will NOT fall back to another agent.`));
+        process.exitCode = 1;
+    }
     else if (outcome.kind === 'refused') {
         console.log('');
         console.error(`  ${yellow('⚠')} Signed in, but this workspace refused ${cyan(name)}: ${outcome.reason}`);

package/dist/commands/workspace.js

@@ -26,6 +26,8 @@ import { resolveActiveAgent } from '../agent-state.js';
 import { isAgentRuntime } from '../agent-scope.js';
 import { getTarget } from '../cli-state.js';
 import { attachShellCwd, absorbShellCwd, shellTargetKey } from '../shell-session.js';
+import { planLimitAdvice } from '../limit-advice.js';
+import { resolveAuthOrigin } from '../browser-login.js';
 /** Workspace-agent jobs wait for the server's ceiling (900s) plus the report's tail. */
 export const AGENT_TURN_TIMEOUT_MS = 930_000;
 const AGENT_TURN_ACTIONS = new Set(['agent-prompt', 'agent-turn']);
@@ -1287,6 +1289,16 @@ function printKnownActionAdvice(action, input, result) {
     if (action === 'ticket-get' && result?.code === 'not-found') {
         console.error('  If this key belongs to a document, read it with document-get; ticket-get reads board cards only.');
     }
+    // MCP2-70 / MCP2-71: a plan or account limit says what is true and what to do, in words.
+    if (/-limit-reached$/.test(String(result?.code ?? ''))) {
+        let origin = 'https://www.clearly.sh';
+        try {
+            origin = resolveAuthOrigin().authOrigin;
+        }
+        catch { /* the default web origin */ }
+        for (const line of planLimitAdvice(result, origin))
+            console.error(line);
+    }
 }
 /**
  * Emit navigation hints for common call failures. Agents parse these to
@@ -2463,8 +2475,8 @@ export async function cmdTask(title, values) {
 }
 // ── beehaven doc add <file> — local file → searchable project document ───
 //
-// One-shot: reads a local file, mints a note (note-create) + seeds its body
-// (note-content-seed). Content lands in the workspace SQLite note-content
+// One-shot: reads a local file and creates it through document-create.
+// Content lands in the workspace SQLite note-content
 // table + FTS5 index, so `search-notes` and the cloud agent can retrieve it.
 // This is the DOCUMENT path; `teleport` is the raw-blob (R2) path. Markdown is
 // stored verbatim; code is wrapped in a fenced block (with the language) so it
@@ -2525,16 +2537,14 @@ export async function cmdDocAdd(filePath, values) {
     const title = values.title ||
         (isMarkdown ? raw.match(/^#\s+(.+)$/m)?.[1]?.trim() || fileName : fileName);
     try {
-        const created = await rpcOnce('note-create', {
-            noteData: { projectId: values.project || undefined, title },
-            fileType: 'document',
+        const created = await rpcOnce('document-create', {
+            projectId: values.project || undefined, title, markdown: data,
         }, getTimeout(values));
-        const noteId = created?.noteId || created?.id;
+        assertNoRpcError(created, 'document-create');
+        const noteId = created?.id;
         if (!noteId) {
-            console.error(`  note-create failed: ${JSON.stringify(created)}`);
-            process.exit(1);
+            throw new Error(`document-create failed: ${JSON.stringify(created)}`);
         }
-        await rpcOnce('note-content-seed', { noteId, data, title }, getTimeout(values));
         if (values.json) {
             console.log(JSON.stringify({
                 noteId,

package/dist/limit-advice.js

@@ -0,0 +1,32 @@
+/**
+ * Plain-language advice printed under a plan or account limit refusal from `beehaven call`
+ * (MCP2-70 workspaces, MCP2-71 identities, MCP2-65 per-workspace agents). The refusal JSON is
+ * printed first; these lines say what is true and the one thing to do next. Pure: returns lines.
+ */
+import { upgradeLink } from './agent-limit-refusal.js';
+export function planLimitAdvice(result, origin) {
+    const code = String(result?.code ?? '');
+    if (code === 'workspace-limit-reached') {
+        const owned = Number(result?.current) || 1;
+        return [
+            owned > 1
+                ? `  You own ${owned} workspaces and Free includes 1. Nothing has been removed.`
+                : '  Free includes 1 workspace you own, and you have it. Workspaces you were invited to don\'t count.',
+            `  Upgrade your workspace to create more: ${upgradeLink(origin, result?.upgradeUrl)}`,
+        ];
+    }
+    if (code === 'identity-limit-reached') {
+        return [
+            `  Your account has ${Number(result?.current) || 'the most'} agents, the most one account can have (the same on every plan).`,
+            '  Delete one you no longer use in Agents, or sign in as one you have: beehaven agent list',
+        ];
+    }
+    if (code === 'agent-limit-reached') {
+        return [
+            '  This workspace has all the agents its plan includes. One agent can work from several apps.',
+            '  Use one you have (beehaven agent login <name>), archive one in Agents settings,',
+            `  or upgrade for more agents: ${upgradeLink(origin, result?.upgradeUrl)}`,
+        ];
+    }
+    return [];
+}

package/package.json

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

package/scripts/sync-skills.mjs

@@ -47,12 +47,24 @@ const SOURCES = {
   'clearly-init':      'apps/mcp-server/plugin/skills/clearly-init/SKILL.md',
   'clearly-workflows': 'apps/mcp-server/plugin/skills/clearly-workflows/SKILL.md',
   'clearly-artifacts': 'apps/mcp-server/plugin/skills/clearly-artifacts/SKILL.md',
+  // CC2-245 — print and social design, so the CLI teaches the same set as the app.
+  'print-production':  'apps/mcp-server/plugin/skills/print-production/SKILL.md',
+  'social-posts':      'apps/mcp-server/plugin/skills/social-posts/SKILL.md',
 };
 
 let missing = 0;
 const out = join(PKG, 'skills');
 mkdirSync(out, { recursive: true });
 for (const [name, rel] of Object.entries(SOURCES)) {
+  // Standalone package CI has no Clearly monorepo. Its explicitly merged bundle is the input;
+  // still validate every shipped skill and regenerate the same content-hashed manifest below.
+  if (process.env.BEEHAVEN_SKILLS_SNAPSHOT === '1') {
+    if (!existsSync(join(out, name, 'SKILL.md'))) {
+      console.error(`  ✗ ${name}: packaged snapshot missing`);
+      missing++;
+    }
+    continue;
+  }
   const src = join(REPO, rel);
   if (!existsSync(src)) {
     /**

package/skills/clearly-agent/SKILL.md

@@ -190,11 +190,23 @@ Anything you create is stamped `created_by: agent:<your-id>` and born **private*
 - **a SIBLING agent does not**, unless it is shared;
 - **you can see and manage your own**, and you can see your owner's work.
 
-⚠⚠ **FILING INTO A SHARED PROJECT IS THE ONLY SHARING MECHANISM.** There is no per-item ACL. If a
+⚠⚠ **FILING INTO A SHARED PROJECT IS HOW YOU SHARE.** There is no per-item ACL. If a
 teammate or another agent needs your work, move it into a project you both belong to
 (`project-member-add` takes an `agentId`). A project is **open** (all workspace members) or
 **invite-only**; the workspace default is set once in Settings → Workspace → Project access.
 
+Change it on something you made (document, sheet, deck or canvas) with one call, CLI or MCP:
+
+```bash
+beehaven call sharing-set '{"kind":"document","id":"PLA-5420","project":"Agent Work OS — Seed Roadmap"}'
+beehaven call sharing-set '{"kind":"document","id":"PLA-5420","visibility":"workspace"}'   # unfiled, everyone
+beehaven call sharing-set '{"kind":"composition","id":"<canvas id>","project":null}'       # back to Drafts, private
+```
+
+Over MCP: `clearly_edit { target, changes: { sharing: { project?, visibility? } } }`. The reply says
+who can see it now. ⚠ Only on your own work: another agent's (or your owner's) is refused `not-yours`.
+Don't copy a document to share it; the copy splits its history and comments.
+
 ⚠ Creating something does **not** put it in your owner's Recents — that is deliberate. They find it
 in Drafts. Opening it is what makes it recent *for them*.
 

package/skills/clearly-artifacts/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   Put a self-contained interactive HTML page into a Clearly workspace, the way a
   Claude artifact works: an explainer, an animation, a small tool, a calculator, a
   chart that runs. Covers which of the three HTML homes runs scripts (a SITE does,
-  a canvas ARTIFACT card does but cannot be clicked, a NOTE never does), the exact
+  a canvas ARTIFACT card does and is clicked only in Interact mode, a NOTE never does), the exact
   CLI calls, the sandbox limits, updating, filing in a project, how a person opens
   it, and QA. Use when asked to publish, host or add an HTML page, demo or animation
   to the workspace. Triggers: "make an artifact", "publish this HTML", "add this page /
@@ -23,13 +23,14 @@ production hold different workspaces.
 | Home | Make it with | Scripts and CSS animation | Clickable | Search, history | Opens at |
 |---|---|---|---|---|---|
 | **Site** | `compose-upload-init` → `file-teleport-inline` → `compose-upload-finalize` | run | yes | not in `document-search`; no version history; a re-upload overwrites | Recents or project card → `/compositions/detail?id=<id>` |
-| **Canvas artifact** | `canvas-act` `canvas.add-artifact` | run | **no**: the card never takes pointer events, so it pans like a picture | no; it is part of the canvas and is deleted with it | the canvas, `/c/<compositionId>` |
+| **Canvas artifact** | `canvas-act` `canvas.add-artifact` | run | **only in Interact mode**: by default the card takes no pointer events and pans like a picture; the person selects it and presses **Interact** (Done or Esc hands input back to the canvas) | no; it is part of the canvas and is deleted with it | the canvas, `/c/<compositionId>` |
 | **Note** | `document-create {html}`; `page-write` (in-app chat only) | **never**: it opens in the document editor, which drops `<script>`, `<style>` and inline `<svg>` | n/a | yes, both | `/documents/<id>` |
 
 - An interactive page someone opens, clicks through or comes back to is a **site**. This is the
   Claude-artifact equivalent and the default.
 - A page that only needs to be **seen** beside other cards (a looping animation, a live chart in a
-  review board) is a **canvas artifact**. Buttons inside it cannot be pressed.
+  review board) is a **canvas artifact**. Its buttons respond only after the person selects the
+  card and presses Interact, so never make a control the only way to see the content.
 - Prose the team will read, search and edit is a **note**. Never put a script in a note: it
   is stored, and then nothing ever runs it. Editing the note in the app rewrites its body.
 
@@ -99,8 +100,8 @@ artifact card. It copies the entry HTML at that moment: later re-uploads do not
 and the site's other files do not load.
 
 **Connector only (MCP):** no tool makes a site or an artifact. `clearly_file_upload` cannot choose
-a site path, and `clearly_create` stores a document body as markdown. `clearly_canvas_place
-{target, kind:"site", id}` can place a site that already exists. Otherwise, tell the person the
+a site path, and `clearly_create` stores a document body as markdown. `clearly_canvas_add
+{target, ops:[{op:"place", kind:"site", id}]}` can place a site that already exists. Otherwise, tell the person the
 running page needs the CLI.
 
 ## 4. Update, file, link

package/skills/clearly-docs/SKILL.md

@@ -2,8 +2,9 @@
 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
+  Use the MCP filesystem tools (clearly_glob, clearly_grep, clearly_read,
+  clearly_edit…) 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
@@ -101,6 +102,42 @@ whatever you last read, overwriting anything the human changed in between.
   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.
 
+## Formatting a document (PRDs, specs, memos)
+
+A document renders like a Google Doc: Arial 11pt, 1.15 line spacing, Google's heading sizes, and no space
+between blocks except what you write. Write the body in `markdown`; switch to `html` only for what markdown
+cannot say.
+
+**Markdown**
+- `<!-- clearly-style:title -->` on the line above `# Name` makes the Title; `<!-- clearly-style:subtitle -->`
+  above `## Line` the Subtitle. `#` to `######` are Headings 1-6. Numbered headings ("1. Summary") are spaced
+  exactly like plain ones.
+- A blank line between two paragraphs, lists, tables, quotes or code blocks is an empty line on the page —
+  put one wherever you would press Enter twice in Google Docs. None is needed next to a heading.
+- `1.` lists keep their numbers: a list that resumes at `3.` after a paragraph continues at 3. Indent 2-4
+  spaces to nest (1. a. i. and bullets ● ○ ■). `- [ ]` / `- [x]` is a checklist.
+- GFM tables: the first row is the header; `:---:` centres a column, `---:` right-aligns it.
+- `**bold**`, `*italic*`, `~~strike~~`, `==highlight==`, `` `code` ``, `[text](https://…)`, and inline
+  `<u>`, `<sub>`, `<sup>`, `<br>`, `<span style="color: #dc2626">…</span>`,
+  `<span style="background-color: #fef08a">…</span>`. Any other HTML in markdown shows as text.
+- `> text` is a quote; `> [!NOTE]` (TIP, IMPORTANT, WARNING, CAUTION) opens a callout with that bold label.
+- Fenced code (```` ```ts ````), `---` for a horizontal line, `[TOC]` for a table of contents (filled from
+  Headings 1-3 when the document opens), `<!-- pagebreak -->` for a page break, and
+  `<!-- clearly-align:center -->` (left, right, justify) on the line above a paragraph or heading to align it.
+
+**HTML** (send `html` instead of `markdown`) reaches every option the editor has:
+`<span style="font-size: 14pt">`, `<span style="font-family: Georgia">`, `<p style="padding-top: 10pt;
+padding-bottom: 10pt">` (space before/after), `<p data-line-spacing="1.5">`, `<p style="margin-left: 36pt">`
+(indent), `<p style="text-align: justify">`, `<mark data-color="#bfdbfe" style="background-color: #bfdbfe">`,
+`<th colwidth="120">` (column width), `<ul data-type="taskList"><li data-type="taskItem" data-checked="true"><p>…</p></li></ul>`,
+`<div data-toc></div>`, `<div data-type="page-break"></div>`, `<h1 class="doc-title">`, `<h2 class="doc-subtitle">`.
+An empty line is `<p></p>`.
+
+**A PRD, the way big-tech teams write one:** Title, then a Subtitle with team · status · version; a
+two-column table of Owner, Status, Reviewers and Target launch; `[TOC]`; then Summary, Problem, Goals and
+Non-goals (a checklist), Requirements (a table of ID, requirement, priority, notes), User experience, Metrics
+(a table of baseline and target), Launch plan (a numbered list), Risks and open questions (callouts), Appendix.
+
 ## 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,

package/skills/clearly-init/SKILL.md

@@ -67,24 +67,33 @@ into a document, ticket, canvas, log, or chat response.
 ### 2. Verify
 
 Run `/mcp` in Claude Code, or `codex mcp list` in Codex. You should see `clearly` authenticated
-with **7 tools**:
+with its tools listed: `clearly_read`, `clearly_create` and `clearly_canvas_add` among them. A
+client that connected before 2026-10-30 may show its older list until it reconnects; the old names
+keep working.
 
-**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.
+**Every tool has one safety class: its name says whether it reads, adds, edits or deletes.** The
+CRUD tools cover every artifact type — document, canvas, sheet, deck, board, ticket, project — and
+`type` says what they touch.
 
 - **`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.
+- **Canvas tools** — `clearly_canvas_read` (layers, or a `view`: inspect, measure, text, fonts,
+  vectors, prototype, variables, live, table), `_add` (nodes and additive ops), `_update` (edits and
+  ops: auto layout, variables, prototype links, vector edits…), `_delete`, `_review` (a saved PNG)
+  and `_export`. One call is one batch and one revision.
+- **Workspace tools** — components, design start/plan, context and semantic search, skills,
+  version history and files.
 
 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:
+**Everything else is the `beehaven` CLI**, by action name — Company Brain writes, scheduling,
+stickers and other AI media, billing. In a shell the CLI is also the faster canvas door, because one
+`canvas-act` batch can mix reads and writes. `beehaven actions` lists them; `beehaven call <action>
+'<json>'` runs one:
 
 ```bash
 beehaven call context-search '{"query":"per-seat billing","scope":"org"}'
@@ -103,9 +112,9 @@ Claude Code already lives and where every call is attributed to your agent.
 
 ## 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:
+The MCP tools cover artifacts, the canvas, components, search, skills and files. **The rest — the
+Company Brain's writes, stickers and other AI media, scheduling — 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

package/skills/clearly-workflows/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: clearly-workflows
 description: >-
-  Best with the beehaven CLI (semantic search and write-back); with only the Clearly connector, search with clearly_grep and record decisions with clearly_create.
+  Best with the beehaven CLI (semantic search and write-back); with only the Clearly connector, search with clearly_search_semantic or clearly_grep and record decisions with clearly_create.
   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
@@ -63,7 +63,7 @@ beehaven call context-write '{
 
 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.
+⚠ **Why these are CLI calls.** The MCP connector covers artifacts (`clearly_catalog · _read · _create · _edit · _replace · _comment · _delete · _grep · _glob`), the canvas and context search (`clearly_search_context`), but not the Company Brain's write verbs: those 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
 
@@ -76,7 +76,7 @@ Follow the loaded procedure rather than inventing your own — that's how you wo
 
 ## 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.
+`beehaven actions` lists every workspace action with its description; `beehaven call <action> '<json>'` runs one. Reach for these when the MCP tools don't cover what you need — which is most things beyond reading, writing and searching artifacts.
 
 ## Rules of thumb
 

package/skills/index.json

@@ -82,14 +82,14 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "11505106cb1dd287"
+    "sha": "73755afe97270a0a"
   },
   {
     "name": "visualize",
     "files": [
       "SKILL.md"
     ],
-    "sha": "88bb6e94fb37c337"
+    "sha": "634baf88dd3d0b2a"
   },
   {
     "name": "sticker-pack",
@@ -103,27 +103,42 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "388be4de86f59eb4"
+    "sha": "044d6b33c1b07f10"
   },
   {
     "name": "clearly-init",
     "files": [
       "SKILL.md"
     ],
-    "sha": "d4dfdd76c7c0a108"
+    "sha": "c3ebdc077b05bc7d"
   },
   {
     "name": "clearly-workflows",
     "files": [
       "SKILL.md"
     ],
-    "sha": "b9622f21173bab0d"
+    "sha": "13aed38f4d4dfe67"
   },
   {
     "name": "clearly-artifacts",
     "files": [
       "SKILL.md"
     ],
-    "sha": "14434d4904da91a3"
+    "sha": "13b9ab880f975914"
+  },
+  {
+    "name": "print-production",
+    "files": [
+      "SKILL.md",
+      "formats.md"
+    ],
+    "sha": "d436b3a56ff65b5d"
+  },
+  {
+    "name": "social-posts",
+    "files": [
+      "SKILL.md"
+    ],
+    "sha": "f8b095de39645000"
   }
 ]

package/skills/print-production/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: print-production
+description: >-
+  Print-ready flyers, posters, leaflets and tri-folds, booklets, menus, postcards, business cards, books,
+  stickers and signs on a Clearly canvas: physical print pages at 96 units per inch, layout grids in mm and pt,
+  bleed, trim and safe areas, type for the reading distance, image resolution, CMYK risks, preflight with the
+  layers to fix, and press PDF export with crop marks. Load it BEFORE building anything that will be printed.
+  Triggers: "print-ready", "flyer", "poster", "brochure", "tri-fold", "business card", "menu", "booklet",
+  "zine", "send to the printer", "with bleed", "crop marks", "A4", "letter size". Needs a terminal with the
+  beehaven CLI; in a chat with only the Clearly connector, use the clearly_* tools (add op "artboard", update
+  ops "grid" and "print", read view "preflight", clearly_canvas_export).
+---
+
+> **Canvas work goes through the CLI.** Every verb below is a `canvas-act` action:
+> `beehaven call canvas-act '{"compositionId":"<id>","action":"canvas.add-artboard","args":{"preset":"a4","grid":{"margin":15,"columns":6,"gutter":5,"baseline":13}}}'`,
+> or several at once with `{"compositionId":"<id>","batch":[{"action":…,"args":{…}}, …]}`. With only the Clearly
+> connector: `clearly_canvas_add { ops:[{ op:"artboard", preset:"a4", grid:{…} }] }`, `clearly_canvas_update { ops:[{ op:"grid", id, … }, { op:"print", bleedMm:3, cropMarks:true }] }`,
+> `clearly_canvas_read { view:"preflight", id }` and `clearly_canvas_export { ids:[page], format:"pdf" }`.
+> Clearly runs no AI model for a connected agent (MCP2-57): no image generation, editing or upscaling here — place
+> photos the person supplies. The in-app agent's `print-production` house skill (apps/cloudflare/src/agent/media-skills.ts)
+> shares this text except for its AI image steps. Every format id, its trim, units and defaults: [formats.md](formats.md).
+
+# print-production
+
+Print production on the Clearly canvas: flyers, posters, leaflets and brochures, menus, postcards, business cards, books, stickers and signs that print at the right size and survive the press.
+
+ONE SCALE
+Print pages are physical: 96 canvas units per inch. 1 mm = 3.78 units and 1 pt = 1.333 units, so 10 pt type is fontSize 13.33 and a 0.5 pt rule is strokeWidth 0.67. DPI is output only: an A4 page is 793.7×1122.5 units whether it exports at 150 or 300 dpi. Never build a print page at "300 dpi pixels" or 2×.
+
+1 SET UP THE PAGE (one call)
+canvas.add-artboard { preset, orientation?, pages?, spread?, fold?, grid? } makes print pages; frame.create with a print preset makes the same page. Presets: "a4" 210×297 mm, "a5", "a3", "a2", "a1", "letter" 8.5×11 in (also "flyer"), "tabloid" 11×17 in, "poster-18x24" 18×24 in, "poster-24x36", "poster-50x70", "postcard" 6×4 in, "postcard-5x7", "business-card" 3.5×2 in, "business-card-eu" 85×55 mm, "dl" 99×210 mm, "trifold-letter", "trifold-a4", "bifold-a4", "greeting-card", "book-6x9", "book-5x8", "sticker3", "roll-up"; any size with wMm/hMm. It saves the format's bleed and safe area as the print settings when the canvas has none, and returns the page ids, fold panels, grid numbers and output pixels.
+- Booklets: pages in multiples of 4; spread:true lays page 1 as a recto, then verso|recto pairs, and the inside margins mirror.
+- Folded leaflets ("half", "roll", "z", "gate" folds) come as two pages, Outside and Inside, with a column band per panel and fold guides. Roll folds are unequal: the inside flap is 2 mm narrower. Letter roll fold: Outside [inside flap | back | cover], Inside [2 | 3 | 4].
+
+2 GRID BEFORE CONTENT
+canvas.layout-grid { id, margin, columns, gutter, baseline, side? } in mm, baseline in pt. It returns frame-relative columns [{x,w}], spans (the width of n columns) and baseline { first, step }; place on those numbers, never estimates. Starting points:
+- A4/Letter flyer or menu: margins 12–15 mm, 6 or 12 columns, 4–5 mm gutter, baseline = body leading (13 pt for 10/13).
+- Report or book page: inside 18–22 mm, outside 14–16, top 15, foot 20–24 (the foot is largest); 1–2 columns of 45–75 characters.
+- Poster: margins 4–6% of the short side, 4–6 columns, and one element breaks the grid on purpose.
+- Business card: 4–5 mm all round. Tri-fold: 6 mm inside each panel.
+
+3 TYPE FOR THE DISTANCE
+Body 9–11 pt (fontSize 12–14.7) at 125–145% leading; captions 7–8 pt; legal small print 6 pt minimum; nothing under 4 pt. A headline needs about 32 pt per metre of reading distance (an A3 poster read at 2 m: 64–120 pt; a roll-up's key line read at 5 m: 160 pt+). Reversed type (light on dark): 8 pt minimum and a heavier weight. Small black text in pure #000000 so it prints from black ink alone. Measure with canvas.measure-text before placing; put text tops where the baselines land on the baseline grid.
+
+4 BLEED, TRIM, SAFE
+The trim is the page edge. Anything that touches it (backgrounds, photos, colour bands) runs past it by the bleed: 3 mm = 11.34 units, 2 mm on stickers. Print pages are unclipped so bleed art shows. Keep text and logos inside the safe area (usually 5 mm, 3 mm on cards) or the grid margins. No thin borders near the trim: cutting drifts by about 1 mm.
+
+5 IMAGES AND COLOUR
+A photo prints sharp with at least 300 source pixels per printed inch (150 for posters seen from 2 m or more); preflight reads stored source sizes. When a photo is small or soft, ask the person for a larger source image before export. Canvas colour is RGB and the printer converts to CMYK: very vivid blues, greens, violets and oranges print duller, so choose a slightly deeper colour or warn. Large black areas: ask for the printer's rich black (often C60 M40 Y40 K100); small text stays pure black. Ask for the printer's spec, spot colours and paper; they override these defaults.
+
+6 CHECK AND DELIVER
+- canvas.review the page and open its image; fix overflow, collisions and contrast.
+- canvas.preflight { id }: fix every warning on the ids it names (bleed-short, safe-area, hairline, reversed-small-text, tiny-text, low-res, vivid-rgb), then run it again until the verdict is "pass" or each remaining warning is a choice you state.
+- canvas.set-print { dpi, bleedMm, safeMm, cropMarks:true } when the printer asks for marks.
+- canvas.export { format:"pdf", ids:[page] }: a press PDF with trim and bleed boxes, crop marks and art at the DPI (the receipt states the DPI achieved). format:"svg" is vector with outlined text; "png" is trim plus bleed at the DPI.
+- In your reply state the trim size, bleed, safe area, marks, DPI, paper if known and any colour risk.
+
+## Folds and panels
+
+| fold | panels (flat → folded) | panel widths | outside order | inside order |
+|---|---|---|---|---|
+| half (bi-fold) | 2 | equal | back · front | 2 · 3 |
+| roll (tri-fold) | 3 | outer two equal, the inside flap 2 mm narrower | inside flap · back · cover | 2 · 3 · 4 |
+| z (concertina) | 3 | equal | 1 · 2 · 3 | 4 · 5 · 6 |
+| gate | 3 | flaps 1 mm narrower than a quarter each, centre half | flap · back · flap | flap · centre spread · flap |
+
+- `canvas.add-artboard { preset:"trifold-letter" }` (or `fold:"roll"` on any size) returns `fold.panelsMm`, `fold.foldsMm` and
+  a grid with one column band per panel. Never put type across a fold; keep 6 mm clear either side of it.
+- Design the cover panel first, then the inside spread as one composition across panels 2–4.
+- Heavier stock (over about 170 gsm) needs scoring before folding: say so in the handoff.
+
+## Booklets and imposition
+
+- Saddle-stitched booklets are a multiple of 4 pages: 8, 12, 16, 20, 24. Design reader spreads with
+  `pages:N, spread:true`; the printer imposes printer spreads. Do not impose yourself unless asked.
+- Inside margins grow with page count on saddle stitch (creep): add 1–2 mm to the inside margin at 24+ pages.
+- Perfect-bound books lose 3–6 mm into the spine on the inside: inside margin 18–22 mm minimum.
+- Page 1 is a right-hand page (recto). Odd pages are rectos; running heads and folios go on the outside edges.
+
+## Paper and finishing (say what you assume)
+
+- Uncoated paper absorbs ink: colours print softer and darker, fine type spreads. Coated (gloss, silk, matt) keeps
+  detail. Ask, or state the assumption.
+- Weights: flyers 130–170 gsm, posters 150–200 gsm, postcards and covers 300–350 gsm, business cards 350–450 gsm.
+- Spot UV, foil, emboss and die-cuts need a separate vector layer per effect in pure 100% K or a named spot
+  swatch: build it as its own named group and say the printer needs it as a separate plate.
+- White ink, varnish and spot colours cannot be represented in an RGB export; describe them in the handoff.
+
+## Printer handoff checklist
+
+1. Trim size, orientation, page count and fold.
+2. Bleed (3 mm unless the printer says otherwise) and whether crop marks are on.
+3. Output DPI the export achieved (the receipt states it) and that colour is RGB for the printer's conversion.
+4. Paper, finish and any spot colours or special effects.
+5. The preflight verdict, and any warning you kept on purpose with its reason.
+6. The PDF and the composition link.

package/skills/print-production/formats.md

@@ -0,0 +1,90 @@
+# Print formats
+
+Generated from `lib/canvas/printFormats.ts` — do not edit by hand. Every id works as `canvas.add-artboard { preset }` and as a `frame.create` print preset. Units are canvas units at 96 per inch; bleed and safe are the defaults saved when a canvas has no print settings. A printer's own specification always governs.
+
+## Paper
+
+| id | name | trim | units (w×h) | bleed / safe mm | fold | note |
+|---|---|---|---|---|---|---|
+| `a6` | A6 | 105×148 mm | 396.9×559.4 | 3 / 4 | — | Pocket flyer or postcard; body 8–9 pt. |
+| `a5` | A5 | 148×210 mm | 559.4×793.7 | 3 / 5 | — | Flyer, booklet or notebook page; body 9–10 pt. Also: `a5-flyer`. |
+| `a4` | A4 | 210×297 mm | 793.7×1122.5 | 3 / 5 | — | Letterhead, report, menu or flyer; body 9–11 pt, read at 40 cm. Also: `a4-flyer`, `menu`, `report`, `letterhead`. |
+| `letter` | Letter | 8.5×11 in | 816×1056 | 3 / 5 | — | US flyer, letterhead or report; body 9–11 pt. Also: `flyer`, `us-letter`, `poster-letter`. |
+| `legal` | Legal | 8.5×14 in | 816×1344 | 3 / 5 | — | Menus and long forms. |
+| `half-letter` | Half Letter | 5.5×8.5 in | 528×816 | 3 / 5 | — | Booklet, zine or program page; body 9–10 pt. Also: `statement`, `book-5.5x8.5`, `zine`. |
+
+## Leaflet
+
+| id | name | trim | units (w×h) | bleed / safe mm | fold | note |
+|---|---|---|---|---|---|---|
+| `dl` | DL leaflet | 99×210 mm | 374.2×793.7 | 3 / 5 | — | Rack card or compliment slip; one column of copy. Also: `rack-card`, `dl-flyer`. |
+| `trifold-letter` | Tri-fold Letter | 11×8.5 in | 1056×816 | 3 / 5 | roll | Roll fold to 3.7×8.5 in: inside flap 2 mm narrower; panel 1 is the cover. Also: `brochure`, `trifold`. |
+| `trifold-a4` | Tri-fold A4 | 297×210 mm | 1122.5×793.7 | 3 / 5 | roll | Roll fold to DL (~99×210 mm): inside flap 2 mm narrower. |
+| `zfold-a4` | Z-fold A4 | 297×210 mm | 1122.5×793.7 | 3 / 5 | z | Concertina fold into three equal DL panels. |
+| `bifold-a4` | Bi-fold A4 | 297×210 mm | 1122.5×793.7 | 3 / 5 | half | Folds once to A5: back cover left, front cover right. Also: `folded-a5`. |
+| `bifold-letter` | Bi-fold Letter | 11×8.5 in | 1056×816 | 3 / 5 | half | Folds once to 5.5×8.5 in. |
+| `gatefold-letter` | Gate-fold Letter | 11×8.5 in | 1056×816 | 3 / 5 | gate | Two flaps meet at the centre; the flaps are 1 mm narrower than a quarter. |
+
+## Poster
+
+| id | name | trim | units (w×h) | bleed / safe mm | fold | note |
+|---|---|---|---|---|---|---|
+| `a3` | A3 | 297×420 mm | 1122.5×1587.4 | 3 / 5 | — | Small poster or spread; headline read at 1–2 m. Also: `a3-poster`. |
+| `a2` | A2 | 420×594 mm | 1587.4×2245 | 3 / 10 | — | Poster read at 2–3 m; headline 72 pt or more. |
+| `a1` | A1 | 594×841 mm | 2245×3178.6 | 3 / 10 | — | Poster or A-board read at 3–5 m. Also: `a-board`, `a-frame`. |
+| `a0` | A0 | 841×1189 mm | 3178.6×4493.9 | 3 / 15 | — | Large poster or conference board; read at 5 m or more. Also: `conference-poster`. |
+| `b4` | B4 | 250×353 mm | 944.9×1334.2 | 3 / 5 | — | Poster or large booklet. |
+| `tabloid` | Tabloid 11×17 | 11×17 in | 1056×1632 | 3 / 5 | — | Small poster or newsletter spread. Also: `ledger`, `poster-11x17`, `11x17`. |
+| `poster-18x24` | Poster 18×24 in | 18×24 in | 1728×2304 | 3 / 10 | — | Event poster read at 2–4 m. |
+| `poster-24x36` | Poster 24×36 in | 24×36 in | 2304×3456 | 3 / 12 | — | Large poster read at 3–6 m. |
+| `poster-27x40` | One-sheet 27×40 in | 27×40 in | 2592×3840 | 3 / 12 | — | Film one-sheet; billing block at the foot. Also: `one-sheet`, `movie-poster`. |
+| `poster-50x70` | Poster 50×70 cm | 500×700 mm | 1889.8×2645.7 | 3 / 10 | — | European poster read at 3–5 m. |
+| `poster-70x100` | Poster 70×100 cm | 700×1000 mm | 2645.7×3779.5 | 3 / 12 | — | Large European poster. |
+
+## Card
+
+| id | name | trim | units (w×h) | bleed / safe mm | fold | note |
+|---|---|---|---|---|---|---|
+| `business-card` | Business card 3.5×2 in | 3.5×2 in | 336×192 | 3 / 3 | — | US card; name 9–11 pt, details 7–8 pt, 3 mm safe. Also: `business-cards`, `card`, `business-card-us`. |
+| `business-card-eu` | Business card 85×55 mm | 85×55 mm | 321.3×207.9 | 3 / 3 | — | European card; details 7–8 pt. |
+| `business-card-jp` | Business card 91×55 mm | 91×55 mm | 343.9×207.9 | 3 / 3 | — | Japanese meishi. |
+| `postcard` | Postcard 6×4 in | 6×4 in | 576×384 | 3 / 4 | — | Landscape postcard; leave the back address half clear. Also: `postcard-6x4`, `4x6`. |
+| `postcard-5x7` | Postcard 7×5 in | 7×5 in | 672×480 | 3 / 4 | — | Invitation or large postcard. Also: `invitation`, `5x7`. |
+| `postcard-a6` | Postcard A6 | 148×105 mm | 559.4×396.9 | 3 / 4 | — | European landscape postcard. |
+| `greeting-card` | Greeting card 5×7 folded | 10×7 in | 960×672 | 3 / 4 | half | Flat sheet folding to 5×7 in portrait: back panel left, front right. |
+| `bookmark` | Bookmark 2×6 in | 2×6 in | 192×576 | 3 / 3 | — | One column; 6–8 pt details. |
+| `ticket` | Ticket 5.5×2 in | 5.5×2 in | 528×192 | 3 / 3 | — | Event ticket; stub on the right. |
+
+## Book
+
+| id | name | trim | units (w×h) | bleed / safe mm | fold | note |
+|---|---|---|---|---|---|---|
+| `b5` | B5 | 176×250 mm | 665.2×944.9 | 3 / 5 | — | Journal, workbook or magazine. |
+| `book-5x8` | Book 5×8 in | 5×8 in | 480×768 | 3 / 5 | — | Trade paperback; inner margin largest for the binding. |
+| `book-6x9` | Book 6×9 in | 6×9 in | 576×864 | 3 / 5 | — | Trade paperback or report; body 10–11.5 pt. |
+| `book-b-format` | B-format 129×198 mm | 129×198 mm | 487.6×748.3 | 3 / 5 | — | UK paperback. |
+| `book-royal` | Royal 156×234 mm | 156×234 mm | 589.6×884.4 | 3 / 5 | — | Hardback or monograph. |
+
+## Sticker
+
+| id | name | trim | units (w×h) | bleed / safe mm | fold | note |
+|---|---|---|---|---|---|---|
+| `sticker2` | Sticker 2 in | 2×2 in | 192×192 | 2 / 3 | — | Die-cut sticker; 2 mm bleed past the cut. |
+| `sticker3` | Sticker 3 in | 3×3 in | 288×288 | 2 / 3 | — | Die-cut sticker; 2 mm bleed past the cut. |
+| `sticker4` | Sticker 4 in | 4×4 in | 384×384 | 2 / 3 | — | Die-cut sticker or label. |
+| `square1080` | Square 1080 at 300 dpi | 3.6×3.6 in | 345.6×345.6 | 0 / 3 | — | A 1080-px square exported at 300 dpi. |
+
+## Signage
+
+| id | name | trim | units (w×h) | bleed / safe mm | fold | note |
+|---|---|---|---|---|---|---|
+| `roll-up` | Roll-up banner 85×200 cm | 850×2000 mm | 3212.6×7559.1 | 5 / 25 | — | Bottom 150 mm hides in the stand; keep copy above 1 m. Also: `banner`, `pull-up`. |
+| `yard-sign` | Yard sign 24×18 in | 24×18 in | 2304×1728 | 3 / 15 | — | Read from a moving car: five words, huge type. |
+
+## Envelope
+
+| id | name | trim | units (w×h) | bleed / safe mm | fold | note |
+|---|---|---|---|---|---|---|
+| `envelope-dl` | Envelope DL | 220×110 mm | 831.5×415.7 | 0 / 10 | — | Address window conventions vary: ask the printer. |
+| `envelope-c5` | Envelope C5 | 229×162 mm | 865.5×612.3 | 0 / 10 | — | Holds A5 or folded A4. |
+| `envelope-10` | Envelope #10 | 9.5×4.126 in | 912×396.1 | 0 / 10 | — | US business envelope. |

package/skills/social-posts/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: social-posts
+description: >-
+  Instagram feed posts and carousels, stories, reel covers, thumbnails and banners on a Clearly canvas: platform sizes (frame presets), safe zones, phone-readable type, carousel structure, one design rebuilt for every format, and PNG export. Load it before building any social post, carousel, story, thumbnail, banner or ad, or to adapt a design to other platform sizes. Triggers: "instagram post", "carousel", "story", "reel cover", "youtube thumbnail", "linkedin banner", "resize this for every platform". Needs a terminal with the beehaven CLI; in a chat with only the Clearly connector, use the clearly_* tools.
+---
+
+> **Canvas work goes through the CLI.** Every verb below is a `canvas-act` action:
+> `beehaven call canvas-act '{"compositionId":"<id>","action":"frame.create","args":{"name":"Launch · IG 4:5","preset":"social-portrait"}}'`,
+> or several at once with `{"compositionId":"<id>","batch":[{"action":…,"args":{…}}, …]}`. `brand-tokens`
+> and `canvas-perceive` are `beehaven call <name> '{…}'` too. Clearly runs no AI model for a connected
+> agent (MCP2-57): no image generation, editing or upscaling here — place photos the person supplies.
+> The in-app agent's `social-posts` house skill (apps/cloudflare/src/agent/media-skills.ts) shares this text
+> except for its AI image steps.
+
+# social-posts
+
+Social posts on the Clearly canvas: Instagram feed posts and carousels, stories and reels covers, thumbnails and banners, and one design adapted to every format.
+
+SIZES (frame.create { name, preset })
+- Feed: "social-portrait" 1080×1350 (4:5, the most screen space; the default for a feed post), "social-post" 1080×1080, "social-grid" 1080×1440 (3:4).
+- Story / reel / TikTok cover: "social-story" 1080×1920.
+- "youtube-thumbnail" 1280×720, "pinterest-pin" 1000×1500, "linkedin-post" 1200×627, "x-post" 1600×900, "linkedin-banner", "youtube-banner", "facebook-cover".
+Name artboards "<campaign> · IG 4:5", "<campaign> · Story".
+
+SAFE ZONES (keep text, logos and faces inside)
+- Story/reel 1080×1920: nothing important in the top 250 px or the bottom 340 px (the app's own UI covers them).
+- The Instagram profile grid shows a 3:4 centre crop: on a 1:1 post keep key content inside the centre 810 px; on 4:5, inside the centre ~1012 px.
+- YouTube thumbnail: the duration badge covers the bottom-right corner.
+- Margins: at least 64 px from every edge on 1080-wide formats.
+
+TYPE THAT READS ON A PHONE
+A 1080 px post is seen at about a third of its size. Headline 72–120 px, at most about 7 words; supporting line 36–48 px; small print 28 px minimum. One typeface family, two weights. Measure with canvas.measure-text before placing.
+
+LAYOUT
+One focal point per slide: a photo or illustration, one headline, one small brand mark. Brand colours from brand-tokens. Text over a photo needs a calm area, a scrim or a plate. Leave the logo small, in a corner, never centred.
+
+CAROUSELS
+2–10 slides of the same size, built as artboards side by side. Slide 1 is the hook (the claim or the question), the middle slides each carry one idea, the last is the call to action. Repeat the same grid, margins and type sizes on every slide. For continuity, carry one shape or line across a seam: draw its two halves at the matching edge of each slide.
+
+ONE DESIGN, EVERY FORMAT
+Design the master first (usually 4:5). For each other format, create its artboard from the preset and REBUILD the layout: same hierarchy and content, re-flowed for the new shape. Do not just scale. Move a photo's focus with cropX/cropY so the subject stays in frame, re-wrap the headline to the new width, and keep sizes relative to the short side. canvas.duplicate { ids, dx, name, toW } only for the same aspect at another size (for example 1080 → 2160).
+
+CHECK AND DELIVER
+- canvas.review each artboard until clean or look; open its image and check the safe zones and legibility.
+- Export: canvas.export { format:"png", ids:[artboard] } gives a 1080-px file link per artboard (scale:2 for a sharper upload).
+- Offer a caption (the first line is the hook), alt text describing the image, and hashtags only if asked.

package/skills/visualize/SKILL.md

@@ -4,13 +4,12 @@ description: Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini
   "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
+> **⚠ IN A SHELL, CANVAS WORK GOES THROUGH THE CLI.** 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.
+> `beehaven call canvas-act '<the JSON>'`. The payloads are exactly as shown. One CLI batch can
+> mix reads and writes, so a build is fewer calls. Without a shell, the MCP connector's six canvas
+> tools do the same work, one safety class each: `clearly_canvas_add` takes the same node
+> objects, `clearly_canvas_update` the same patches and ops, `clearly_canvas_review` the review.
 
 # Visualize — draw it, don't write it