@clearlysh/beehaven 0.8.23 → 0.8.25

package/skills/brand-identity/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: brand-identity
+description: >-
+  Build a complete brand identity on a Clearly canvas the way a studio does —
+  brief, mark, wordmark, lockups and clear space, palette, type system,
+  applications, and a spec board someone else can build from. Use when asked
+  for a brand, a logo, an identity, a rebrand, a visual system, brand
+  guidelines, or "design a company/product/app called X". Load design-craft
+  alongside it for the underlying grid, type and colour craft. Triggers:
+  "design a brand", "make me a logo", "brand identity", "visual identity",
+  "rebrand", "brand guidelines", "logo and colours", "identity system".
+---
+
+# brand-identity — a system, not a picture of a logo
+
+⚠⚠ **THE DELIVERABLE IS A SYSTEM SOMEONE ELSE CAN BUILD WITH.** A single mark on a white
+artboard is not an identity; it is a drawing. Pentagram's identity work ships a symbol, a
+wordmark, a graphic system, a palette, a type system and the guidelines that let an in-house
+team keep it consistent. That is the shape to copy.
+
+Read **`design-craft`** first or alongside — grid, type scale, colour roles and the studio
+pass are assumed here.
+
+---
+
+## 1. The brief — five lines, before anything is drawn
+
+You may ask the user, or state your reading and proceed. You may not skip it.
+
+```
+WHO      the organisation, in one clause
+FOR      the audience, specifically — not "everyone"
+UNLIKE   the nearest competitor, and what must NOT be borrowed from them
+FEELS    three adjectives, and one the brand is deliberately NOT
+LIVES    where it actually appears: app icon? shopfront? 30 pages of PDF? a t-shirt?
+```
+
+⚠⚠ **`LIVES` DECIDES THE MARK MORE THAN `FEELS` DOES.** A brand that lives at 24px in a
+browser tab cannot have a mark with four internal details. A brand that lives on a building
+can. Ask where it is smallest and design for that first.
+
+⚠ **`UNLIKE` is what stops generic output.** Without it, every fintech gets a blue geometric
+sans and every studio gets a black wordmark in Helvetica. Name the cliché and refuse it out loud.
+
+---
+
+## 2. The mark — construct it, never freehand it
+
+⚠⚠ **EVERY CURVE AND ANGLE SHOULD BE DERIVABLE.** A mark built from a stated construction —
+a circle of radius R, a 30° angle, a stroke of R/6 — survives scaling, redrawing and
+handover. A mark of hand-placed béziers does not, and it shows.
+
+**The construction methods that actually work on a canvas:**
+
+| method | how | good for |
+|---|---|---|
+| **Geometric** | circles/squares/triangles on a shared radius; every measure a fraction of R | tech, finance, infrastructure |
+| **Derived letterform** | take the initial, cut or extend one stroke | anything with a strong name |
+| **Monoline** | one stroke weight everywhere, round caps and joins | modern, friendly, screen-first |
+| **Counter-form** | the shape is the NEGATIVE space between forms | clever marks that survive one colour |
+| **Modular** | one unit repeated/rotated on a grid | systems, networks, collectives |
+
+**Build it as an `svg` node with a stated viewBox and derived numbers:**
+
+```jsonc
+{"action":"canvas.create-node","args":{"name":"mark","type":"svg","x":120,"y":120,"w":240,"h":240,
+ "svg":"<svg viewBox='0 0 240 240' xmlns='http://www.w3.org/2000/svg'>…</svg>"}}
+```
+
+⚠ **`<text>` inside an `svg` node does NOT render headlessly** — no system fonts are loaded.
+Wordmarks are real text nodes, or outlined paths. Never live `<text>` in the mark.
+
+**Test the mark against these before going further. A mark that fails any of them is not done:**
+
+```
+□ 24px      Still readable as a distinct shape? (Render it at 24 and LOOK.)
+□ 1 colour  Works in solid black? Solid white on dark?
+□ Knockout  Works as a hole in a shape — no fill, no gradient carrying it?
+□ Square    Sits comfortably in an app-icon square with its own padding?
+□ Rotated   Is it accidentally something else at 90°/180°?
+□ Unlike    Put it next to the competitor named in the brief. Distinct?
+```
+
+⚠⚠ **DESIGN IT IN ONE COLOUR FIRST.** A gradient can make a weak shape look temporarily
+good. If it does not work in flat black, the shape is wrong and the gradient is hiding it.
+
+---
+
+## 3. Wordmark and lockups
+
+- **Set the wordmark in real type, then adjust** — do not draw letters from scratch unless
+  the brief asks for a custom face.
+- ⚠ **A wordmark is always tracked tighter than body text.** At display size, `letterSpacing`
+  −1 to −4. Then fix the specific pairs the font gets wrong (an uppercase A next to a V, a
+  T next to a lowercase o).
+- **Lockups are a fixed set, not an invitation.** Ship exactly these and say so:
+
+```
+primary      mark + wordmark, horizontal    ← the default
+stacked      mark above wordmark            ← square-ish slots
+mark-only    the symbol alone               ← ≥ 24px, when context supplies the name
+reversed     the primary on dark
+mono         one colour, no exceptions      ← print, engraving, embroidery
+```
+
+- **Clear space** = a fraction of the mark, never an absolute px. **¼ of the mark's height**
+  on all four sides is a defensible default. Express it in terms of the mark so it scales.
+- **Minimum size** — state one, per lockup, and test it: mark-only 24px digital / 10mm print;
+  the full lockup needs roughly 2–3× that before the wordmark closes up.
+
+---
+
+## 4. Palette
+
+Follow `design-craft`'s role list — ground, ink, ink-muted, accent, 2–3 support. For an
+identity, add:
+
+- ⚠⚠ **ONE colour is the brand.** People remember a single colour. A five-colour identity is
+  remembered as no colour. Pick the one, then support it.
+- **State a dark-ground variant of every colour.** The same accent needs ~10% more lightness
+  on near-black to read the same. An identity without this ships broken dark mode.
+- **Give each colour a role sentence**, not just a hex: *"Accent. The one thing that shouts.
+  CTAs, the mark, one word in a headline. Never a background."* A palette without roles gets
+  used at random.
+- **Print values matter if `LIVES` includes print** — state CMYK or Pantone intent, and know
+  that a bright screen accent may be unreachable in CMYK. Say so rather than shipping a
+  surprise.
+
+---
+
+## 5. Type system
+
+```
+DISPLAY   headlines, the mark's neighbour     one face, one or two weights
+TEXT      body, UI, long form                 must have real weights + italics
+MONO      code, data, captions                only if the brand needs it
+```
+
+- **One face in two weights beats two faces.** If you use two, make them different in CLASS.
+- ⚠ **Check the face has what the brand needs**: does it have a decent 500? Real italics or
+  faked obliques? The numerals you want (lining vs oldstyle, tabular for data)? A missing
+  weight is discovered three months in, on a deadline.
+- **Publish the scale**, not just the names — the ratio, the base, and the resulting sizes
+  (see `design-craft` §2). A type "system" without sizes is a font recommendation.
+
+---
+
+## 6. Applications — this is what makes it believable
+
+For an imagery moodboard, create a small series of purpose-made images with a shared
+material, lighting and colour logic, then place each as its own editable image node.
+Keep the official Clearly rabbit wordmark as a separate canonical asset; do not ask an
+image model to redraw it. The CLI path for local raster files is
+`beehaven canvas add-image <file> --composition <id>`; see
+[`clearly-canvas/authoring.md`](../clearly-canvas/authoring.md#local-images-from-the-cli)
+for the upload, nesting and MCP contracts. Inspect a rendered artboard after placing
+the images: a stored `src` alone does not prove the intended image is visible.
+
+⚠⚠ **A mark on a white square convinces nobody. The SAME mark on six real surfaces does.**
+This is the single highest-value part of the deliverable and the part agents most often skip.
+
+Pick 4–6 that match the brief's `LIVES`:
+
+```
+app icon 512×512      business card 1050×600     social avatar + header
+website hero          poster / out-of-home       packaging face
+email signature       t-shirt / tote             signage / door vinyl
+presentation title    invoice / letterhead       UI screen with the system applied
+```
+
+Build each as a real frame at real proportions on the canvas, in a row, with a caption under
+each. **Do not fake them as flat rectangles labelled "app icon"** — draw the rounded square,
+put the mark in it at the right optical size, show it at 512 and again at 48.
+
+---
+
+## 7. The spec board — hand-off, on the canvas
+
+A titled section, below the applications, that another designer could build from:
+
+```
+01 MARK          construction diagram — the circles/angles/ratios, drawn, with the numbers
+02 CLEAR SPACE   the ¼-height rule, drawn as a dashed frame with the measure labelled
+03 LOCKUPS       all five, at the same optical size, labelled
+04 MISUSE        4–6 tiles: stretched, recoloured, rotated, on a busy photo, effects,
+                 too small — each with a ✗. This section prevents more damage than any other.
+05 PALETTE       swatches + hex + ROLE SENTENCE + dark-ground variant
+06 TYPE          the faces, the scale with real numbers, a specimen paragraph
+07 GRID          margins, columns, gutter, baseline — the numbers from design-craft §1
+08 VOICE         3 lines: how it speaks, one thing it never says
+```
+
+⚠ **Section 04 (misuse) is not filler.** Guidelines are read once and then broken; the misuse
+tiles are what people actually remember.
+
+---
+
+## 8. Canvas layout for the whole delivery
+
+Lay it out left to right as a narrative, one row per stage, generous gutters (200px+ between
+artboards) so each reads as its own object:
+
+```
+Row 1   COVER            1080×1350   the mark, big, on the brand ground
+Row 2   THE MARK         construction · lockups · clear space
+Row 3   PALETTE + TYPE   full-width panels
+Row 4   APPLICATIONS     4–6 real-proportion artboards in a row
+Row 5   SPEC BOARD       the eight sections above, as titled panels
+```
+
+- **Put a caption above every artboard** (`19px/700`, accent, `letterSpacing: 2`) so the
+  board reads as a deck rather than a pile.
+- **Set the composition background** to a dark neutral (`composition-patch {backgroundColor}`)
+  so the artboards read as objects on a desk. ⚠ That patch reaches an open tab now, but if
+  the ground is load-bearing, lay a real rect and `canvas.order {op:"back"}` it.
+- ⚠ **Build in ONE batch** and check `count` against the number of ops you sent — a batch
+  stops at the first failure and lands everything before it.
+
+---
+
+## 9. Verify like a studio
+
+Run `design-craft`'s studio pass, plus these identity-specific ones:
+
+```
+□ Rendered the mark at 24px and LOOKED at it
+□ Mark works in flat black, flat white, and knocked out
+□ Every lockup has stated clear space and minimum size
+□ Palette has a dark-ground variant and role sentences
+□ Type scale has NUMBERS, not just face names
+□ At least 4 real applications, at real proportions
+□ Misuse section exists
+□ Put the mark beside the competitor named in UNLIKE — still distinct?
+□ Can someone build a new asset from this board without asking a question?
+```
+
+⚠⚠ **THE LAST ONE IS THE REAL TEST.** If any answer would be "ask the designer", the system
+is incomplete — and the whole point of an identity is that it works when the designer has left.
+
+---
+
+## Sources
+
+Pentagram brand-identity practice (symbol, wordmark, graphic system, palette, type system,
+guidelines for in-house teams) · Michael Bierut, *How to* (brief → rationale → trade-offs) ·
+Paula Scher's Public Theater identity — a system built almost entirely from typography, which
+survived because the plays changed constantly and the identity was designed to absorb it ·
+Massimo Vignelli, *The Vignelli Canon*.

package/skills/clearly-agent/SKILL.md

@@ -170,6 +170,15 @@ teammate or another agent needs your work, move it into a project you both belon
 ⚠ Creating something does **not** put it in your owner's Recents — that is deliberate. They find it
 in Drafts. Opening it is what makes it recent *for them*.
 
+## Designing UI? Use the workspace's brand and components — and design before you build
+
+A workspace stores its brand (`brand-tokens`) and its component library (`component-list`) as data.
+Anything visual you make — a canvas, a deck, a mockup of a screen you are about to implement —
+starts from those, placed with `component-instantiate {compositionId, instances:[…]}`. When the
+task changes a product's UI, the composition comes FIRST: build the screen and its states there,
+`canvas.review` it, link it to the ticket (`work-link {ticketId, kind:"design", refKind:"composition",
+refId}`), then implement. `clearly-canvas` §0 has the details.
+
 ## When a write is refused
 
 `agent-denied-create` / `-update` / `-delete` mean your **capability matrix** said no. It covers the

package/skills/clearly-canvas/SKILL.md

@@ -47,6 +47,36 @@ A new composition almost always needs at least one revision after its first rend
 the pass finds nothing, look again at the thumbnail. If there is still nothing, say what
 you checked. Never make a change only to show that a review happened.
 
+## 0. Start from the workspace's brand and component library
+
+A workspace keeps its brand and its components as data. Read them before you draw, and
+build from them — redrawing a button the library already has is how designs drift from the
+product they describe.
+
+```sh
+beehaven call brand-tokens '{}'                                   # colours (light + dark), type roles, radius, logos, voice
+beehaven call component-list '{"query":"<brand or kind>"}'        # parts, with props, variants and the code they mirror
+beehaven call component-instantiate '{"compositionId":"<id>","instances":[
+  {"id":"<component>","x":96,"y":200,"variant":"Light"},
+  {"id":"<component>","x":96,"y":280,"variant":"Light","props":{"label":"Save changes"}}]}'
+```
+
+- `instances` places many parts with ONE scene read and ONE write; never loop single
+  placements. `mode:"dark"` resolves brand colours against the brand's dark palette.
+- Placed instances are ordinary editable nodes whose root remembers its master
+  (`libraryComponentId`). Edit freely; a genuinely new part goes back into the library with
+  `component-create` (or `{ fromCompositionId, nodeId }` to save one you drew).
+- Component node coordinates are relative to the component ROOT, even under an inner
+  frame — the opposite of `canvas.create-node`, where x/y follow `parentId`.
+- If the workspace has a brand kit, it IS the system for the brief: use its roles, faces
+  and voice rather than inventing a palette. Change the brand itself only when asked.
+
+**UX design before implementation.** When the work is a change to a product's UI, the
+composition is the design the code will answer to: show the real states (empty, loading,
+error, long content, narrow width, dark theme), review it, and link it to the ticket with
+`work-link {"ticketId":"…","kind":"design","refKind":"composition","refId":"<id>"}`
+before implementation starts.
+
 ## 1. Establish the brief and inspect the material
 
 Read the supplied canvas, copy, brand and references before drawing. Resolve:
@@ -117,8 +147,9 @@ multiple colours and dense pages can all be appropriate. Choose deliberately.
 
 ## 3. Define a small design system and code the composition
 
-Write a local JS/Python builder when the artifact has repeated elements or several
-artboards. Use named tokens, helpers, arrays and layout arithmetic as you would in
+When §0 found a brand kit and components, they are the system: map the brief onto their
+roles, then add only what the brief genuinely needs. Write a local JS/Python builder when
+the artifact has repeated elements or several artboards. Use named tokens, helpers, arrays and layout arithmetic as you would in
 HTML/CSS. The CLI can submit the complete generated payload. You do not need to
 hand-author hundreds of coordinates in a chat message.
 
@@ -158,6 +189,21 @@ Use a batch for each coherent build or revision, with descriptive unique layer n
 Parent content to its artboard. Inspect every operation result and rollback status.
 Save your builder and returned IDs so revisions are targeted and reproducible.
 
+⚠ **Batch, never loop.** One `canvas-act` batch of hundreds of steps is one scene read,
+persisted every 50 steps, and the workspace stays responsive for everyone in it while it
+runs. The same steps sent as hundreds of separate calls each re-read the whole scene. If a
+call fails with a dropped connection, read the scene (`composition-detail
+{id, includeScene:true}`) before retrying: the work may have landed.
+
+⚠ **One batch per canvas at a time.** A reply that times out ("outcome unknown") or drops does
+not stop the batch — it is still running on the workspace. Resending at once used to start a
+second, slow, unprotected batch and could half-apply both (CA-43). The workspace now queues a
+second writer behind the first and answers `code: "canvas-busy"` (with the running batch's
+progress) if it waits too long — nothing from that call was applied. Either way: read the scene,
+then send only what is missing. A ~1,100-step build takes about 40 s; the CLI waits 180 s by
+default and `--timeout <ms>` (or `BEEHAVEN_RPC_TIMEOUT_MS`) raises it. Never place component
+instances after a build whose reply you did not see.
+
 Keep review notes and status outside the delivered artwork. Use
 [communications.md](communications.md) only when posting those blocks is useful.
 

package/skills/clearly-canvas/authoring.md

@@ -57,10 +57,19 @@ Create normalizes hex colours; raw stored scenes use RGBA arrays in 0..1.
 
 - `frame.create` and `canvas.create-node` with `parentId` take coordinates **relative
   to that parent**. Create the frame first. Names can resolve earlier nodes in a batch.
+  A frame nested in a frame (a dark band inside an artboard) needs a worker from
+  2026-10-02 or later; on an older one, create it at world coordinates and attach it with
+  `canvas.update-nodes {ids:[id], patch:{parentId}}` (membership only, position kept).
+  To move a node INTO a frame and place it in one patch, pass `parentId` with frame-relative x/y.
+- Component templates (`component-create`) are different: every node's x/y is relative
+  to the component ROOT, even under an inner frame.
 - Persisted nodes and perception bounds use **world coordinates**. Raw scene replacement
   through `composition-patch`/MCP must use world coordinates, even with `parentId`.
-- `canvas.update-nodes` geometry is world geometry. For group moves/resizes use the
-  catalog's frame/arrangement/scale actions; do not assume a patch reflows children.
+- `canvas.update-nodes` geometry is world geometry — EXCEPT when the same patch also sets
+  `parentId`: then x/y are relative to that frame, exactly like `canvas.create-node`. A
+  membership-only patch (`parentId` without x/y) keeps the node's world position. For group
+  moves/resizes use the catalog's frame/arrangement/scale actions; do not assume a patch
+  reflows children.
 - Build backgrounds before foregrounds. Use `canvas.order` to change stacking.
 - Name nodes uniquely; use returned IDs where names collide. Parent content to its
   frame so movement, selection, clipping and reviews can treat it as one artifact.
@@ -124,9 +133,11 @@ beehaven canvas add-image ./photo.png --composition <id> \
   --x 120 --y 160 --width 600 --height 400 --json
 ```
 
-The command reports `nodeId` and `imageFileId`. Coordinates are world coordinates;
-omit both `--x`/`--y` to use canvas auto-placement, and omit both size flags to use
-the image's native dimensions. Check `beehaven canvas` help on the installed CLI:
+The command reports `nodeId`, `imageFileId` and `src` (the stored URL — reuse it, e.g. as a
+brand logo). Coordinates are world coordinates; omit both `--x`/`--y` to use canvas
+auto-placement, and omit both size flags to use the image's native dimensions (read from
+the file header for PNG, JPEG, GIF and WebP). A negative coordinate works as `--x -3000`
+on CLI 0.8.24+; older CLIs need `--x=-3000`. Check `beehaven canvas` help on the installed CLI:
 older versions do not have this command. On one of those, use the documented
 `get-upload-url` → binary PUT → `file-uploaded` sequence, then
 `canvas-act {action:"canvas.create-node",args:{type:"image",src:<absolute URL>,x,y,w,h}}`.

package/skills/design-craft/SKILL.md

@@ -132,6 +132,10 @@ headline estimated at 867px measured **990**.
 
 ## 3. Colour — a system, not a mood board
 
+⚠ **A workspace brand kit already IS this role list.** `beehaven call brand-tokens '{}'`
+returns ground, ink, muted, accent and support roles (light and dark) with their contrast
+already measured. Use those values; the list below is for when there is no kit.
+
 **Build the palette from a role list, not from colours you like:**
 
 ```

package/skills/index.json

@@ -17,7 +17,7 @@
       "project-plans.md",
       "review.mjs"
     ],
-    "sha": "21faa5f8d14beefe"
+    "sha": "df3ef3200c38abdf"
   },
   {
     "name": "agent-home",
@@ -38,7 +38,7 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "7761aa240847d20c"
+    "sha": "260c3a6967b08a8b"
   },
   {
     "name": "layout-systems",
@@ -47,6 +47,13 @@
     ],
     "sha": "8de89b7b7c86f81f"
   },
+  {
+    "name": "brand-identity",
+    "files": [
+      "SKILL.md"
+    ],
+    "sha": "50587f531bfab1c6"
+  },
   {
     "name": "pair-on-canvas",
     "files": [
@@ -74,6 +81,6 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "ad938cb0070fcab0"
+    "sha": "9e94e53b90ded575"
   }
 ]