@clearlysh/beehaven 0.8.29 → 0.8.31

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

@@ -17,7 +17,7 @@
       "project-plans.md",
       "review.mjs"
     ],
-    "sha": "7d79406b37f611a8"
+    "sha": "b942eebe6f0397fb"
   },
   {
     "name": "agent-home",
@@ -53,7 +53,7 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "cd891499599ccb7b"
+    "sha": "755db2d1ab8c759f"
   },
   {
     "name": "pair-on-canvas",
@@ -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.