beehaven 0.8.27 → 0.8.33

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/design-craft/SKILL.md

@@ -114,8 +114,9 @@ divided by the ratio. Sizes that share a ratio look related; sizes picked by han
   make them obviously different in class (a grotesque with a serif), never two neighbours.
 - **Measure: 45–75 characters.** At 16px in a normal grotesque that is roughly **360–600px**.
   Set the text node's `w` to hold that, not to fill the column.
-- **Line height moves INVERSELY to size.** Body 1.4–1.6. Subheads 1.25–1.35. Display
-  **0.95–1.05** — big type needs tight leading or it falls apart into stripes.
+- **Line height defaults to Auto**, using the font's metrics. When tuning it deliberately,
+  use **140–160%** for body, **125–135%** for subheads, and **95–105%** for display type.
+  Author explicit units (`lineHeight:"140%"` or `"24px"`); percentage leading follows font size.
 - ⚠⚠ **TRACK DISPLAY TYPE NEGATIVE.** Type designed at 16px is far too loose at 120px.
   Above ~40px use `letterSpacing: -1` to `-4`; above ~120px, −3 to −6. **Uppercase and small
   labels go the other way: +1 to +3.** This one adjustment does more for perceived quality
@@ -250,8 +251,8 @@ only to show that a review happened.
 
 **A 1080×1350 social post**
 ```
-margin 72 · display 96–140 (weight 800, tracking −3, lineHeight 1.0)
-body 20–24 (weight 500, lineHeight 1.5, w ≤ 560)
+margin 72 · display 96–140 (weight 800, tracking −3, lineHeight "100%")
+body 20–24 (weight 500, lineHeight "150%", w ≤ 560)
 caption 16 (weight 600, tracking +1.5, uppercase)
 rule 2–3px accent · footer block bottom-aligned at 1350 − 72 − blockHeight
 ```
@@ -265,7 +266,7 @@ Content column ≤ 1200 wide even though the slide is 1920 — full width is unr
 
 **A 1440 web hero**
 ```
-margin 96 · content max 1200 · headline 64–88 (tracking −2, lineHeight 1.05)
+margin 96 · content max 1200 · headline 64–88 (tracking −2, lineHeight "105%")
 sub 20–24 (muted ink, w ≤ 640) · CTA 48–56 tall, 24–32 horizontal padding, radius 8 or full
 ```
 
@@ -273,7 +274,9 @@ sub 20–24 (muted ink, w ≤ 640) · CTA 48–56 tall, 24–32 horizontal paddi
 ```
 padding 24–32 · radius 10–16 · gap between cards ≥ 2× padding
 title 20–24/600 · body 15–16/400 muted · one accent element maximum
-Background first, THEN the label — later nodes draw over earlier ones.
+Use a filled frame that owns the card's contents. Apply auto layout with this padding
+and a deliberate content gap; let text hug its height. Rectangles serve artwork,
+swatches and rules. A background rectangle with sibling text does not form a card.
 ```
 
 ---
@@ -298,6 +301,11 @@ fewer elements, tighter type, one accent*. Every ornament added is a step away f
 
 ## Sources
 
+The full shelf — about fifty books across grid, type, print production, colour, graphic form,
+brand identity, information and interface design, each reduced to one rule — is in
+[references.md](references.md). In Research pick two or three whose lens fits the brief, and name
+the one behind each direction in its rationale.
+
 Josef Müller-Brockmann, *Grid Systems in Graphic Design* (1981) · Massimo Vignelli, *The
 Vignelli Canon* (semantics / syntactics / pragmatics; "Design is one") · Michael Bierut,
 *How to* (Pentagram; brief → rationale → trade-offs) · Paula Scher / Pentagram, The Public

package/skills/design-craft/references.md

@@ -0,0 +1,95 @@
+# The design shelf
+
+<!-- Generated from apps/cloudflare/src/agent/design-references.ts (the design-references and brand-references house skills).
+     Edit the list there, then run: WRITE_DESIGN_REFERENCES=1 npx vitest run src/__tests__/verify-design-references.test.ts -->
+
+Books a studio designer works from, each reduced to one rule you can act on. The in-app
+assistant gets the same list as the `design-references` and `brand-references` workspace skills.
+
+## How to use it
+
+- In Research, pick two or three references whose lens fits the brief: a print piece or poster → grid, type, print; an identity → brand; a chart or report → information; a screen or flow → interface. Write what each one changes in this design.
+- In Direction, name the reference behind each direction's idea in one line ("a Müller-Brockmann modular grid, type as the image after Scher").
+- In Review, critique against the same rules you chose.
+- These are paraphrased principles, not quotations. Never invent a quote or page number; cite author and title only.
+
+## Method — deciding before drawing
+
+- Massimo Vignelli, *The Vignelli Canon* (2010): Answer semantics (what it means, to whom), syntactics (its visual grammar) and pragmatics (will they get it) before placing a node; few typefaces, a grid, discipline.
+- Michael Bierut, *How to* (2015): Present brief → idea → trade-offs; the idea comes out of the problem, and the rationale is part of the deliverable.
+- Paul Rand, *Thoughts on Design* (1947): Form and content are one: simplify until the idea is legible, and allow wit — play is a way of making it memorable.
+- Bruno Munari, *Design as Art* (1966): Solve the problem with the simplest means; decoration that solves nothing is noise.
+- Karl Gerstner, *Designing Programmes* (1964): Design the rules, not one layout: define the variables (size, position, colour) and generate the set from them.
+- Dieter Rams, *Less but Better* (1995): As little design as possible: every element must earn its place by use; remove what does not.
+- Alan Fletcher, *The Art of Looking Sideways* (2001): Look for the idea sideways — a visual pun or found connection beats a literal illustration of the brief.
+
+## Grid and layout
+
+- Josef Müller-Brockmann, *Grid Systems in Graphic Design* (1981): Construct margins, columns, gutter and baseline first; every element lands on the grid; break it once, on purpose.
+- Timothy Samara, *Making and Breaking the Grid* (2002): Pick the grid for the content (manuscript, column, modular, hierarchical); a deliberate break needs a grid to break.
+- Kimberly Elam, *Geometry of Design* (2001): Place the focal point on a proportional line (golden section, root rectangles, thirds), not at dead centre.
+- Beth Tondreau, *Layout Essentials* (2009): Grids by job: a single column for reading, multi-column for mixed content, modular for catalogues and dashboards.
+
+## Typography
+
+- Robert Bringhurst, *The Elements of Typographic Style* (1992): Measure 45–75 characters, leading to suit the measure, honour the content: type exists to be read.
+- Ellen Lupton, *Thinking with Type* (2004): Build hierarchy by changing one variable at a time — size, weight, colour or space — and track capitals open.
+- Jan Tschichold, *The New Typography* (1928): Asymmetric, functional layout: hierarchy by size, weight and position, never ornament.
+- Emil Ruder, *Typographie* (1967): White space is active form: the counter, the gap and the margin are composed like the type itself.
+- Jost Hochuli, *Detail in Typography* (1987): Letter, word and line spacing decide readability: tighten display type, keep word spaces even, open the leading for long lines.
+- Erik Spiekermann and E. M. Ginger, *Stop Stealing Sheep & Find Out How Type Works* (1993): A typeface is a voice: choose it for the message and audience, then set it with care before anything else.
+- Ellen Lupton, *Type on Screen* (2014): On screen, type is motion and interaction too: sizes, scales and states are a system, not one setting.
+
+## Print and editorial production
+
+- Jan Tschichold, *The Form of the Book*: Classical page proportions: inner margin smallest, foot margin largest; the text block sits high and toward the spine.
+- Richard Hendel, *On Book Design* (1998): A book design serves the reading; decide trim, margins, type and running heads together, and stay invisible.
+- Andrew Haslam, *Book Design* (2006): Plan the whole object — format, grid, pagination, binding — before designing a spread.
+- Jan V. White, *Editing by Design* (1974): Editorial layout starts from what the story says; headline, picture and caption are one unit.
+- International Paper, *Pocket Pal*: Production rules: CMYK for press, 300 dpi images at final size, 3 mm (0.125 in) bleed, a safe area inside the trim.
+- Alan Pipes, *Production for Graphic Designers*: Specify for the press: paper stock, ink coverage, rich black for large areas only, overprint and trap small type.
+
+## Colour
+
+- Josef Albers, *Interaction of Color* (1963): Colour is relative: judge it beside its neighbours on the real ground, never as a swatch alone.
+- Johannes Itten, *The Art of Color* (1961): Choose the one contrast that leads (light–dark, warm–cool, complementary, saturation, extent) and let the rest support it.
+
+## Graphic form and visual perception
+
+- Armin Hofmann, *Graphic Design Manual* (1965): Build with elementary contrasts — point, line, plane, black and white, large and small — before colour.
+- Ellen Lupton and Jennifer Cole Phillips, *Graphic Design: The New Basics* (2008): Point, line, plane, rhythm, scale, texture, figure/ground and framing are variables; change one deliberately.
+- Wucius Wong, *Principles of Two-Dimensional Design* (1972): Repetition, gradation and radiation give a field structure; an anomaly in that structure is the focal point.
+- Rudolf Arnheim, *Art and Visual Perception* (1954): Visual weight balances on the frame's hidden axes; size, value, isolation and position all add weight.
+- Robin Williams, *The Non-Designer's Design Book* (1994): Contrast, repetition, alignment, proximity: if two things differ, make them clearly different.
+- Alex W. White, *The Elements of Graphic Design* (2002): Treat space as an element: emptiness gives the content its shape and its importance.
+- Kenya Hara, *Designing Design* (2007): Emptiness invites the viewer in: leave room for the reader's imagination instead of filling the frame.
+- Paula Scher, *Make It Bigger* (2002): Type can be the image: scale and crop a word until it carries the identity on its own.
+- Philip B. Meggs, *A History of Graphic Design* (1983): Know the lineage of a style so a reference is chosen, not a pastiche of the first thing found.
+- Adrian Frutiger, *Signs and Symbols*: A sign reads by its simplest form; test a mark small, at a distance and in one colour.
+
+## Brand and identity
+
+- Alina Wheeler, *Designing Brand Identity* (2003): Identity is a process — research, strategy, design, touchpoints, asset management; design the touchpoints, not just the logo.
+- Marty Neumeier, *The Brand Gap* (2003): A brand is the customer's gut feeling; close the gap between strategy and the look by testing what people actually perceive.
+- Marty Neumeier, *Zag* (2006): When everyone zigs, zag: state what makes this the only one, then design to that difference.
+- Wally Olins, *On Brand* (2003): A brand shows in product, environment, communication and behaviour; keep all four saying the same thing.
+- Byron Sharp, *How Brands Grow* (2010): Growth comes from being easy to notice and buy: protect distinctive assets and stay consistent.
+- Jenni Romaniuk, *Building Distinctive Brand Assets* (2018): An asset (colour, shape, character) works once it is famous and unique to the brand; use it everywhere, change it rarely.
+- Tom Geismar, Ivan Chermayeff and Sagi Haviv, *Identify* (2011): A mark must be appropriate, distinctive and simple; it earns meaning through use over time.
+- David Airey, *Logo Design Love* (2009): Test a logo at 16 px, in one colour and in reverse; if it needs detail or colour to survive, simplify it.
+- Danne & Blackburn, *NASA Graphics Standards Manual* (1975): A standards manual fixes the mark, clear space, colours, type, grid and applications so anyone can apply the system.
+- Unimark International (Vignelli, Noorda), *New York City Transit Authority Graphics Standards Manual* (1970): A system scales by rules: one typeface, fixed modules, colour coding and consistent placement.
+
+## Information design
+
+- Edward R. Tufte, *The Visual Display of Quantitative Information* (1983): Maximise data-ink: remove chart junk, label directly, show the comparison; use small multiples for change.
+- Edward R. Tufte, *Envisioning Information* (1990): Layer and separate: quiet the grid and background so the data reads first.
+- Otto Neurath, *International Picture Language* (1936): Isotype: count with repeated identical pictograms, never by enlarging one.
+
+## Interface and product design
+
+- Don Norman, *The Design of Everyday Things* (1988): Make the action visible: signifiers, feedback, mapping and constraints; a control must say how it is used.
+- Steve Krug, *Don't Make Me Think* (2000): People scan, they do not read: obvious hierarchy, conventions, one clear next action per page.
+- Adam Wathan and Steve Schoger, *Refactoring UI* (2018): Hierarchy by weight and colour before size, de-emphasise secondary text, use a spacing and shadow scale.
+- Jenifer Tidwell, *Designing Interfaces* (2005): Use the known pattern for the job (navigation, forms, lists, dashboards) before inventing one.
+- William Lidwell, Kritina Holden and Jill Butler, *Universal Principles of Design* (2003): Check the design against named principles (Fitts, Hick, proximity, progressive disclosure) and say which one a choice serves.

package/skills/index.json

@@ -4,7 +4,7 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "2d33d2ecfb166fa6"
+    "sha": "6233057bd1a44b51"
   },
   {
     "name": "clearly-canvas",
@@ -17,56 +17,57 @@
       "project-plans.md",
       "review.mjs"
     ],
-    "sha": "8b1890ca7588af6c"
+    "sha": "5daf296f2bdf65e6"
   },
   {
     "name": "agent-home",
     "files": [
       "SKILL.md"
     ],
-    "sha": "0bbcdbd33cfb11a3"
+    "sha": "e1d18e7518ff4b65"
   },
   {
     "name": "agent-doodle-space",
     "files": [
       "SKILL.md"
     ],
-    "sha": "053fc1cd5a1494d4"
+    "sha": "1e1911e6d8784476"
   },
   {
     "name": "design-craft",
     "files": [
-      "SKILL.md"
+      "SKILL.md",
+      "references.md"
     ],
-    "sha": "260c3a6967b08a8b"
+    "sha": "d11f0c45c93c9dea"
   },
   {
     "name": "layout-systems",
     "files": [
       "SKILL.md"
     ],
-    "sha": "8de89b7b7c86f81f"
+    "sha": "27151a50e3bdb27a"
   },
   {
     "name": "brand-identity",
     "files": [
       "SKILL.md"
     ],
-    "sha": "50587f531bfab1c6"
+    "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",
@@ -74,13 +75,48 @@
       "SKILL.md",
       "survey.mjs"
     ],
-    "sha": "f5585be212a67c32"
+    "sha": "3a3e6fa6e3cf8717"
   },
   {
     "name": "clearly-agent",
     "files": [
       "SKILL.md"
     ],
-    "sha": "c16e1b5d08dbd669"
+    "sha": "c20b255224221342"
+  },
+  {
+    "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.