beehaven 0.8.29 → 0.8.34

package/skills/index.json

@@ -17,21 +17,21 @@
       "project-plans.md",
       "review.mjs"
     ],
-    "sha": "7d79406b37f611a8"
+    "sha": "e23e25bd46b02d9c"
   },
   {
     "name": "agent-home",
     "files": [
       "SKILL.md"
     ],
-    "sha": "0bbcdbd33cfb11a3"
+    "sha": "e1d18e7518ff4b65"
   },
   {
     "name": "agent-doodle-space",
     "files": [
       "SKILL.md"
     ],
-    "sha": "053fc1cd5a1494d4"
+    "sha": "1e1911e6d8784476"
   },
   {
     "name": "design-craft",
@@ -39,35 +39,35 @@
       "SKILL.md",
       "references.md"
     ],
-    "sha": "bf2f4fac6f57ea46"
+    "sha": "d11f0c45c93c9dea"
   },
   {
     "name": "layout-systems",
     "files": [
       "SKILL.md"
     ],
-    "sha": "8de89b7b7c86f81f"
+    "sha": "27151a50e3bdb27a"
   },
   {
     "name": "brand-identity",
     "files": [
       "SKILL.md"
     ],
-    "sha": "cd891499599ccb7b"
+    "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": "11505106cb1dd287"
+  },
+  {
+    "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/layout-systems/SKILL.md

@@ -47,7 +47,7 @@ that lost one. If you have four items, ask whether one is really a different thi
 ```
 margin 8–10% of the short edge      (1080 → 88–108; A3 → 280–350)
 display 12–20% of the HEIGHT        (1350 → 160–270px), weight 700–900, tracking −3 to −6,
-                                     lineHeight 0.92–1.0
+                                     lineHeight "92%"–"100%"
 supporting 2–3% of height           credits, date, venue — deliberately small
 ```
 
@@ -105,7 +105,7 @@ content column ≤ 1200 even though the slide is 1920
 ## Landing page / hero — 1440 wide (design), content max 1200
 
 ```
-margin 96 · headline 64–88 (tracking −2, lineHeight 1.05) · sub 20–24 muted, w ≤ 640
+margin 96 · headline 64–88 (tracking −2, lineHeight "105%") · sub 20–24 muted, w ≤ 640
 CTA 48–56 tall, 24–32 horizontal padding · section spacing 96–160 vertical
 ```
 
@@ -124,7 +124,7 @@ CTA 48–56 tall, 24–32 horizontal padding · section spacing 96–160 vertica
 
 ```
 margin: outer 10%, inner (gutter side) 12–14% — asymmetric, because the binding eats it
-columns 2–3 for A4 body · measure 45–75ch · body 10–11pt (≈42–46px at 300dpi), lineHeight 1.45
+columns 2–3 for A4 body · measure 45–75ch · body 10–11pt (≈42–46px at 300dpi), lineHeight "145%"
 ```
 
 - **Asymmetric margins are the mark of real editorial.** Equal margins all round read as a
@@ -141,9 +141,9 @@ columns 2–3 for A4 body · measure 45–75ch · body 10–11pt (≈42–46px a
 ## Cards, tables and dense UI
 
 - **Card padding 24–32, radius 10–16, gap between cards ≥ 2× padding.**
-- ⚠⚠ **BACKGROUND FIRST, LABEL SECOND.** Later nodes draw over earlier ones — create the
-  card rect, THEN its text. Reversed, the opaque fill hides the label and you get the classic
-  "grid of cards with no text".
+- **Cards are filled frames.** Parent labels, icons and controls to the card; use auto
+  layout for its content. Build rows and grids from these cards, with deliberate
+  Hug/Fill/Fixed sizing. Reserve rectangles for decorative shapes, swatches and rules.
 - **In tables, align numbers RIGHT and use tabular figures.** Left-aligned numbers of
   different lengths cannot be compared, which is the only reason the table exists.
 - **Zebra striping OR rules, never both.** Ideally neither — space is enough at ≥12px row padding.
@@ -153,10 +153,13 @@ columns 2–3 for A4 body · measure 45–75ch · body 10–11pt (≈42–46px a
 ## Building it on the canvas
 
 ```jsonc
-// ONE batch. Frames first, then children with parentId (x/y RELATIVE to the frame).
-{"action":"frame.create","args":{"name":"poster","x":200,"y":300,"w":1080,"h":1350,"fill":"#111111"}}
-{"action":"canvas.create-node","args":{"name":"headline","type":"text","parentId":"poster",
-  "x":88,"y":900,"w":904,"text":"…","size":180,"fontWeight":800,"letterSpacing":-5,"lineHeight":0.95}}
+// ONE batch. A content stack owns its fill and children; the layout computes positions.
+{"action":"frame.create","args":{"id":"card","name":"Feature card","w":360,"h":200,"fill":"#FFFFFF"}}
+{"action":"canvas.create-node","args":{"name":"Feature title","type":"text","parentId":"card",
+  "w":312,"text":"Make room for the idea","size":28,"fontWeight":600,"lineHeight":"auto"}}
+{"action":"canvas.create-node","args":{"name":"Feature detail","type":"text","parentId":"card",
+  "w":312,"text":"Keep every layer ready for the next edit.","size":16,"lineHeight":"145%"}}
+{"action":"canvas.auto-layout","args":{"id":"card","direction":"v","gap":16,"padding":24,"sizingH":"fixed","sizingV":"hug"}}
 ```
 
 - ⚠ **Omit `h` on text** — it hugs its wrapped content. Pin `h` only when a later element's
@@ -180,5 +183,5 @@ columns 2–3 for A4 body · measure 45–75ch · body 10–11pt (≈42–46px a
 | Deck | too many words; title states the topic instead of the argument; full-width text |
 | Landing | subhead runs full width; two competing CTAs; sections evenly spaced |
 | Editorial | symmetric margins; no baseline grid; unbroken columns |
-| Cards | text created before its background; gaps equal to padding so groups do not read |
+| Cards | background and contents lack a shared frame; layout breaks when copy grows |
 | **All** | **an exact 50/50 split, and four type sizes where three would do** |

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.

package/skills/visualize/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: visualize
+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 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.