@clearlysh/beehaven 0.8.30 → 0.8.32

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,90 @@
+---
+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.
+  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/clearly-workspace/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clearly-workspace
-description: Understand and audit a Clearly workspace from the terminal — what it holds (documents, projects, boards, tickets, thoughts, files, agents), who authored what, and which known data defects are present. Run `survey.mjs` for the whole picture in one command. TRIGGER when the user asks "what is in this workspace", "how big is this workspace", "audit / survey / check the workspace", "what have my agents made", "is anything broken in here", "who created these", or before any cleanup, migration or backfill — the survey is what tells you whether a repair is needed and whether it worked. NOT for editing documents (use `document-*`) or drawing on a canvas (use clearly-canvas).
+description: Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini CLI); in a chat with only the Clearly connector, say so and use the clearly_* tools instead. Understand and audit a Clearly workspace from the terminal — what it holds (documents, projects, boards, tickets, thoughts, files, agents), who authored what, and which known data defects are present. Run `survey.mjs` for the whole picture in one command. TRIGGER when the user asks "what is in this workspace", "how big is this workspace", "audit / survey / check the workspace", "what have my agents made", "is anything broken in here", "who created these", or before any cleanup, migration or backfill — the survey is what tells you whether a repair is needed and whether it worked. NOT for editing documents (use `document-*`) or drawing on a canvas (use clearly-canvas).
 ---
 
 # clearly-workspace — know what you are standing in

package/skills/codebase-map/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: codebase-map
-description: Walk a code repository and draw a living ARCHITECTURE MAP of it on a Clearly spatial canvas — modules as frames (sized by LOC, colored by layer), key files as nodes, imports/dependencies as arrows — so the big pieces, how they depend on each other, and where the complexity sits all read at a glance. Load this when the user says "map / diagram / visualize this codebase / repo / architecture", "how is this project structured", "draw the dependency graph", "give me an architecture overview", or when you're onboarding to an unfamiliar repo and need to see its shape fast.
+description: Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini CLI); in a chat with only the Clearly connector, say so and use the clearly_* tools instead. Walk a code repository and draw a living ARCHITECTURE MAP of it on a Clearly spatial canvas — modules as frames (sized by LOC, colored by layer), key files as nodes, imports/dependencies as arrows — so the big pieces, how they depend on each other, and where the complexity sits all read at a glance. Load this when the user says "map / diagram / visualize this codebase / repo / architecture", "how is this project structured", "draw the dependency graph", "give me an architecture overview", or when you're onboarding to an unfamiliar repo and need to see its shape fast.
 ---
 
 > **⚠ CANVAS WORK GOES THROUGH THE CLI, NOT AN MCP TOOL.** Anything written

package/skills/index.json

@@ -17,21 +17,21 @@
       "project-plans.md",
       "review.mjs"
     ],
-    "sha": "b942eebe6f0397fb"
+    "sha": "41327744a8cc0fe1"
   },
   {
     "name": "agent-home",
     "files": [
       "SKILL.md"
     ],
-    "sha": "0bbcdbd33cfb11a3"
+    "sha": "e1d18e7518ff4b65"
   },
   {
     "name": "agent-doodle-space",
     "files": [
       "SKILL.md"
     ],
-    "sha": "053fc1cd5a1494d4"
+    "sha": "1e1911e6d8784476"
   },
   {
     "name": "design-craft",
@@ -53,21 +53,21 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "755db2d1ab8c759f"
+    "sha": "366139b11ff11b58"
   },
   {
     "name": "pair-on-canvas",
     "files": [
       "SKILL.md"
     ],
-    "sha": "65f87e74bf3566a6"
+    "sha": "1d79147baa8c232d"
   },
   {
     "name": "codebase-map",
     "files": [
       "SKILL.md"
     ],
-    "sha": "2e80ffd32f77327f"
+    "sha": "4a4af2229b68827d"
   },
   {
     "name": "clearly-workspace",
@@ -75,13 +75,48 @@
       "SKILL.md",
       "survey.mjs"
     ],
-    "sha": "f5585be212a67c32"
+    "sha": "3a3e6fa6e3cf8717"
   },
   {
     "name": "clearly-agent",
     "files": [
       "SKILL.md"
     ],
-    "sha": "b3f47988cb9235b9"
+    "sha": "1c6425a2143e7901"
+  },
+  {
+    "name": "visualize",
+    "files": [
+      "SKILL.md"
+    ],
+    "sha": "88bb6e94fb37c337"
+  },
+  {
+    "name": "sticker-pack",
+    "files": [
+      "SKILL.md"
+    ],
+    "sha": "74af254817a134d6"
+  },
+  {
+    "name": "clearly-docs",
+    "files": [
+      "SKILL.md"
+    ],
+    "sha": "388be4de86f59eb4"
+  },
+  {
+    "name": "clearly-init",
+    "files": [
+      "SKILL.md"
+    ],
+    "sha": "d4dfdd76c7c0a108"
+  },
+  {
+    "name": "clearly-workflows",
+    "files": [
+      "SKILL.md"
+    ],
+    "sha": "b9622f21173bab0d"
   }
 ]

package/skills/pair-on-canvas/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pair-on-canvas
-description: Use a Clearly canvas as mission control for a coding task — read the spec the human placed on the board, do the work in the repo, and report progress, diffs, and next steps back as cards they steer by inking. Load this when the user says "work the task on my canvas", "take this from the board", "what's on my Clearly canvas", "pick up the spec", "let's pair on the canvas", or whenever a human is directing your coding work spatially instead of in a chat thread.
+description: Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini CLI); in a chat with only the Clearly connector, say so and use the clearly_* tools instead. Use a Clearly canvas as mission control for a coding task — read the spec the human placed on the board, do the work in the repo, and report progress, diffs, and next steps back as cards they steer by inking. Load this when the user says "work the task on my canvas", "take this from the board", "what's on my Clearly canvas", "pick up the spec", "let's pair on the canvas", or whenever a human is directing your coding work spatially instead of in a chat thread.
 ---
 
 > **⚠ CANVAS WORK GOES THROUGH THE CLI, NOT AN MCP TOOL.** Anything written

package/skills/sticker-pack/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: sticker-pack
+description: Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini CLI); in a chat with only the Clearly connector, say so and use the clearly_* tools instead. 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.