@clearlysh/beehaven 0.8.16

package/skills/clearly-workspace/SKILL.md

@@ -0,0 +1,79 @@
+---
+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).
+---
+
+# clearly-workspace — know what you are standing in
+
+## ⚠ FIRST: sign in as an agent
+
+Every `beehaven` verb except a short bootstrap list is refused without an agent identity.
+
+```bash
+beehaven agent login <name>      # mints it if it does not exist
+beehaven status                  # daemon + relay + which env
+```
+
+⚠ **Check `beehaven env` before reading anything.** `prod` and `staging` are different
+databases, and every number below is meaningless if you are on the one you did not mean.
+
+## The whole workspace in one command
+
+```bash
+node ~/.claude/skills/clearly-workspace/survey.mjs          # human-readable
+node ~/.claude/skills/clearly-workspace/survey.mjs --json   # for further processing
+```
+
+It prints the workspace name, its key prefix, counts of every content kind, a
+**needs-attention** block, and documents-by-author.
+
+⚠⚠ **PREFER THIS OVER HAND-WRITTEN SQL.** The same survey by hand is ~15 `workspace-sql`
+round trips, and three of the coercions are traps that fail *silently*:
+
+- **SQLite folder booleans are TEXT.** `is_archived != 1` misses every row storing the
+  string `'true'`, so "live projects" quietly includes archived ones.
+- **Archived rows still satisfy most defect queries.** Counting body-less documents without
+  a live filter reports problems that were already resolved by archiving.
+- **An unreadable table and an empty table both return 0** unless you check for the error.
+  The script prints `?` plus the reason instead.
+
+Every one of those produced a wrong number on this workspace before the script existed.
+
+## What the needs-attention flags mean
+
+| flag | what it is | fix |
+|---|---|---|
+| documents with no body | no `note-content` row → **invisible to `document-search` forever** | archive them, or seed a body; the create path is fixed forward |
+| boards with no project | reachable from nothing in the UI — a board is found through its project | file them, or archive if empty |
+| many 'active' agent sessions | sessions are reaped after 6h idle, so a high count means the sweep is not running | call `agent-session-list` once (it sweeps on read) |
+
+## Reading it deeper
+
+```bash
+# who authored what — `agent:<id>` is an AGENT principal, not a person
+beehaven call workspace-sql '{"query":"SELECT COALESCE(created_by,'\''(unstamped)'\'') AS who, COUNT(*) AS n FROM notes GROUP BY who ORDER BY n DESC"}'
+
+# what a specific agent has been doing
+beehaven call recent-list '{"limit":20}'          # self-scoped: YOUR recents
+beehaven call agent-brief '{}'                    # your session brief, incl. recents + unfiled drafts
+```
+
+⚠ **`(unstamped)` is the ordinary case, not a defect.** `created_by` was added long after most
+rows, and an unstamped row is treated as legacy-visible by design.
+
+⚠ **`agent:<id>` in `created_by` is an AGENT.** Its work is visible to its owner and invisible
+to a SIBLING agent unless filed into a shared project — filing IS the sharing mechanism.
+
+## Repairs — all operator verbs, all `dryRun` by default
+
+```bash
+beehaven call keys-repair-prefix '{}'        # workspace renamed but keys still say the old prefix
+beehaven call boards-repair-authors '{}'     # boards authored by a workspace id instead of a person
+beehaven call notes-backfill-keys '{}'       # documents with no CLR-42 style key
+beehaven call thought-vacuum '{}'            # thought vectors whose map is gone
+```
+
+⚠⚠ **EVERY ONE IS BOUNDED AND REPORTS `remaining` — LOOP UNTIL IT READS 0.** A single call is
+not a finished job. `keys-repair-prefix` once flipped a counter after re-keying only 500 of
+1,219 artifacts and then reported "nothing to do" while 719 rows were stranded. Re-run the
+survey afterwards; that is what tells you the repair actually landed.

package/skills/clearly-workspace/survey.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * survey.mjs — what is IN this workspace, in one command.
+ *
+ * `node survey.mjs [--json]`
+ *
+ * ── WHY A SCRIPT AND NOT PROSE ───────────────────────────────────────────────
+ * Answering "what is in here" by hand is ~15 `workspace-sql` round trips, each
+ * one a chance to mistype a table name or forget that a SQLite boolean comes
+ * back as the STRING 'true'. Every one of those mistakes is silent: you get a
+ * number, it is just the wrong number. A script makes the sequence one call and
+ * the coercions one decision.
+ *
+ * ⚠ IT REPORTS WHAT IT CANNOT SEE. A query that fails prints as `?` with its
+ * error rather than as 0 — an unreadable table and an empty table are opposite
+ * facts, and a survey that renders them alike is worse than no survey.
+ *
+ * ⚠ READ-ONLY BY CONSTRUCTION. Everything goes through `workspace-sql`, which
+ * refuses anything that is not a single SELECT/WITH. This cannot mutate.
+ */
+import { execFileSync } from 'node:child_process';
+
+const JSON_OUT = process.argv.includes('--json');
+
+/** One guarded SELECT through the CLI. Returns rows, or `{ error }`. */
+function sql(query) {
+  try {
+    const out = execFileSync('beehaven', ['call', 'workspace-sql', JSON.stringify({ query })], {
+      encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const m = out.match(/\{[\s\S]*\}/);
+    if (!m) return { error: 'no JSON in response — is the daemon running? `beehaven status`' };
+    const body = JSON.parse(m[0]);
+    if (body.error) return { error: body.error };
+    return { rows: body.rows ?? [] };
+  } catch (e) {
+    const msg = String(e.stderr || e.message || e);
+    // ⚠ The two failures a caller can actually act on, named rather than dumped.
+    if (/agent login|Not an agent/i.test(msg)) return { error: 'no agent identity — run `beehaven agent login <name>`' };
+    if (/daemon|IPC/i.test(msg)) return { error: 'daemon not reachable — `beehaven status`' };
+    return { error: msg.split('\n')[0].slice(0, 160) };
+  }
+}
+
+const one = (query, col = 'n') => {
+  const r = sql(query);
+  if (r.error) return { v: null, error: r.error };
+  return { v: Number(r.rows?.[0]?.[col] ?? 0) };
+};
+
+/** ⚠ SQLite folder booleans store as TEXT. `is_archived != 1` misses every 'true'. */
+const LIVE = "(is_archived IS NULL OR is_archived NOT IN (1,'true','1'))";
+
+const counts = {
+  documents:    one(`SELECT COUNT(*) AS n FROM notes WHERE ${LIVE}`),
+  // ⚠ LIVE ONLY. Counting archived rows too made this flag lie: 16 body-less documents were
+  //   resolved by ARCHIVING them, and the health line still reported all 16 as a problem.
+  //   A health check that cannot see its own fix is one nobody trusts twice.
+  bodyless:     one(`SELECT COUNT(*) AS n FROM notes WHERE ${LIVE} AND id NOT IN (SELECT id FROM "note-content")`),
+  projects:     one(`SELECT COUNT(*) AS n FROM projects WHERE ${LIVE}`),
+  compositions: one(`SELECT COUNT(*) AS n FROM compositions WHERE ${LIVE} AND (is_system IS NULL OR is_system != 'true')`),
+  boards:       one(`SELECT COUNT(*) AS n FROM boards WHERE ${LIVE}`),
+  orphanBoards: one(`SELECT COUNT(*) AS n FROM boards WHERE project_id IS NULL OR project_id = ''`),
+  tickets:      one(`SELECT COUNT(*) AS n FROM tickets`),
+  openTickets:  one(`SELECT COUNT(*) AS n FROM tickets WHERE status NOT IN ('done','closed','resolved')`),
+  thoughts:     one(`SELECT COUNT(*) AS n FROM thoughts`),
+  files:        one(`SELECT COUNT(*) AS n FROM files WHERE deleted_at IS NULL OR deleted_at = 0`),
+  agents:       one(`SELECT COUNT(*) AS n FROM agents WHERE archived IS NULL OR archived NOT IN ('true','1')`),
+  liveSessions: one(`SELECT COUNT(*) AS n FROM agent_sessions WHERE state = 'active'`),
+};
+
+const name = sql(`SELECT value FROM "team-settings" WHERE key = 'name'`);
+const prefix = sql(`SELECT prefix, last_number FROM project_counters WHERE id = 'unfiled'`);
+const authors = sql(`SELECT COALESCE(created_by,'(unstamped)') AS who, COUNT(*) AS n FROM notes WHERE ${LIVE} GROUP BY who ORDER BY n DESC LIMIT 6`);
+
+if (JSON_OUT) {
+  console.log(JSON.stringify({ name: name.rows?.[0]?.value ?? null, counts, prefix: prefix.rows?.[0] ?? null, authors: authors.rows ?? [] }, null, 2));
+  process.exit(0);
+}
+
+const n = (c) => (c.error ? `? (${c.error})` : String(c.v));
+console.log(`\n  ${name.rows?.[0]?.value ?? '(unnamed workspace)'}`);
+if (prefix.rows?.[0]) console.log(`  keys: ${prefix.rows[0].prefix}-*  (${prefix.rows[0].last_number} issued)`);
+console.log('  ' + '─'.repeat(46));
+for (const [k, v] of Object.entries(counts)) console.log(`  ${k.padEnd(16)} ${n(v)}`);
+
+/**
+ * ⚠ THE HEALTH LINES ARE THE POINT. A raw count tells you the size; these tell
+ * you what is WRONG, and each one is a defect this workspace has actually had.
+ */
+const flags = [];
+if (counts.bodyless.v > 0) flags.push(`${counts.bodyless.v} document(s) have no body — invisible to document-search forever`);
+if (counts.orphanBoards.v > 0) flags.push(`${counts.orphanBoards.v} board(s) have no project — reachable from nothing in the UI`);
+if (counts.liveSessions.v > 20) flags.push(`${counts.liveSessions.v} 'active' agent sessions — sessions are reaped after 6h idle, so this is high`);
+if (flags.length) { console.log('\n  needs attention'); for (const f of flags) console.log(`  ⚠ ${f}`); }
+
+if (authors.rows?.length) {
+  console.log('\n  documents by author');
+  for (const a of authors.rows) console.log(`  ${String(a.who).padEnd(34)} ${a.n}`);
+}
+console.log('');

package/skills/codebase-map/SKILL.md

@@ -0,0 +1,142 @@
+---
+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.
+---
+
+> **⚠ 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.
+
+# Codebase map — repo → spatial architecture diagram
+
+A `tree` dump is 400 files of noise. The thing a dev actually wants is the **shape**: ~8 boxes,
+sized by weight, wired by who-imports-whom, with the hot, gnarly module obvious. Use the host shell
+to inspect the repo and the `beehaven` CLI to draw it. Sign in as an agent and connect the intended
+workspace first; `clearly-init` handles setup. Read `clearly-canvas` for the primitives and the
+locked tool contract — this skill builds on it (perceive → act → revise; `frame.create`;
+`canvas.create-node`; frame-relative nesting; bound `arrow.create`; always `compositionId`).
+
+## 1. Discover the structure (host shell)
+
+Survey before you draw. Run these from the repo root:
+
+```bash
+# top-level shape + package boundaries
+ls -d */ ; git ls-files | sed 's|/.*||' | sort | uniq -c | sort -rn | head -20
+find . -name package.json -o -name go.mod -o -name Cargo.toml -o -name pyproject.toml | grep -v node_modules
+
+# size per module (the LOC that sizes each frame) — cloc if present, else wc
+cloc --quiet --json src 2>/dev/null \
+  || git ls-files | grep -vE 'node_modules|dist|build|\.lock' | xargs wc -l 2>/dev/null | sort -rn | head
+
+# hotspots: most-churned files (complexity lives where the diffs pile up)
+git log --format= --name-only | grep -vE '^$|node_modules' | sort | uniq -c | sort -rn | head -20
+```
+
+**Dependencies** (the arrows). Either read declared deps from manifests, or grep the cross-module edges directly:
+
+```bash
+# JS/TS — who imports whom across top-level dirs
+grep -rhoE "from ['\"](\.\./)+[a-zA-Z0-9_-]+" src | sort | uniq -c | sort -rn | head -30
+grep -rhoE "import .* from ['\"]@/[a-zA-Z0-9_-]+" src | sort | uniq -c | sort -rn
+# Python: ^import|^from   ·   Go: read go.mod requires   ·   Rust: [dependencies] in Cargo.toml
+```
+
+You want, per module: an LOC count, a file count, and its 1–3 heaviest outbound dependencies. That's enough to draw the map.
+
+## 2. Cluster into domains
+
+Collapse dirs into a handful of **logical layers** — the same lens regardless of stack:
+
+| Layer | typical dirs | color |
+|---|---|---|
+| **ui** | components, pages, app, views | `#3b82f6` blue |
+| **api / logic** | routes, handlers, services, lib | `#8b5cf6` violet |
+| **data** | db, models, store, repositories | `#10b981` green |
+| **infra** | workers, deploy, config, scripts | `#f59e0b` amber |
+| **shared** | utils, types, common | `#6b7280` slate |
+| **hotspot** | the biggest / most-churned module | `#ef4444` red |
+
+Pick the **~6–12 modules that matter** — never every file. A 40-file `components/` dir is ONE frame, not 40 nodes. Optionally surface 2–4 marquee files *inside* a frame (the entrypoint, the fattest file, the one everything imports).
+
+## 3. Draw it
+
+Get a canvas, then **perceive the background first** so you paint with it (dark board → light ink), and place the map in the user's `gaze`:
+
+```jsonc
+beehaven call composition-create '{"title":"Architecture map · clearly"}'   // → { id: "c_…" }
+canvas-perceive  { "compositionId": "c_…", "format": "text" }   // read backgroundColor + visibleWorldRect
+```
+
+Then batch the whole map in one `canvas-act`. Capture the frame ids the creates return so you can nest + connect. **Size each frame ~proportional to LOC** (e.g. `w ≈ 160 + LOC/40`, clamp 200–420), **fill by layer color**, lay out on a grid with 40px gutters:
+
+```jsonc
+canvas-act {
+  "compositionId": "c_…",
+  "batch": [
+    { "action": "canvas.create-node", "args": { "type": "text", "name": "map-title",
+      "text": "clearly · architecture (12k LOC, 9 modules) — arrows = imports, red = hotspot",
+      "x": 0, "y": -56, "size": 22, "fontWeight": 700, "fill": "#e8edf5" } },
+
+    { "action": "frame.create", "args": { "name": "ui/components", "x": 0,   "y": 0,   "w": 360, "h": 220, "fill": "#16223a" } },
+    { "action": "frame.create", "args": { "name": "lib/services",  "x": 440, "y": 0,   "w": 300, "h": 200, "fill": "#241a3a" } },
+    { "action": "frame.create", "args": { "name": "data/store",    "x": 440, "y": 280, "w": 240, "h": 150, "fill": "#10291f" } },
+    { "action": "frame.create", "args": { "name": "infra/worker",  "x": 0,   "y": 300, "w": 280, "h": 160, "fill": "#2a2110" } }
+  ]
+}
+```
+
+Then a second `canvas-act` once you hold the frame ids — **titles + stats inside each frame** (coords are frame-relative via `parentId`), **key files as nodes**, and **dependency arrows** spanning the gap between frames (use bounds from perceive):
+
+```jsonc
+canvas-act {
+  "compositionId": "c_…",
+  "batch": [
+    { "action": "canvas.create-node", "args": { "type": "text", "name": "ui-title",
+      "text": "ui/components", "x": 16, "y": 12, "size": 16, "fontWeight": 700, "fill": "#cfe0ff", "parentId": "<uiFrameId>" } },
+    { "action": "canvas.create-node", "args": { "type": "text", "name": "ui-stat",
+      "text": "84 files · 4.1k LOC", "x": 16, "y": 36, "size": 12, "fontWeight": 400, "fill": "#8aa0c0", "parentId": "<uiFrameId>" } },
+    { "action": "canvas.create-node", "args": { "type": "rect", "name": "ui-key-canvas",
+      "text": "DocumentCanvas.tsx", "x": 16, "y": 64, "w": 180, "h": 30, "fill": "#1e2d4d", "stroke": "#3b82f6", "radius": 6, "parentId": "<uiFrameId>" } },
+
+    { "action": "arrow.create", "args": { "from":"ui", "to":"lib", "routing":"elbow" } }
+  ]
+}
+```
+
+**Arrow weight = coupling**: `stroke-width:3` for a heavy edge (dozens of imports), `1.5` for a thin one. Curve overlapping arrows with a `<path d=…>` instead of `<line>`. Drop a tiny `text` at an edge's midpoint only when the relationship needs a name.
+
+Finish with a **legend frame** (one colored `rect` + label per layer) tucked in a corner, and confirm the **one-line summary** text sits at the top.
+
+## 4. Reveal, don't dump
+
+The map earns its keep by making structure *jump out*:
+
+- **Hotspot in red.** The biggest or most-churned module gets `fill:"#ef4444"`-family — "here be dragons" at a glance.
+- **Size encodes weight.** A 6k-LOC frame should dwarf a 400-LOC one. Don't draw equal boxes.
+- **Thicker arrows = heavier coupling.** A glance shows what's load-bearing.
+- **Whitespace.** 40px gutters, aligned edges, the legend out of the way. A breathing board reads as designed; a crowded one reads as a dump.
+
+Good map answers three questions instantly: *what are the big pieces, how do they depend on each other, and where's the complexity?*
+
+## 5. Keep it live
+
+This isn't a one-shot render — it's a living diagram. After the repo changes, re-run §1 and `canvas.update-nodes` the frames whose LOC/coupling shifted (resize, recolor, re-arrow) instead of redrawing — the map stays current as the codebase moves. A `canvas.add-diff` block can land the current change next to the architecture map, and **`beehaven watch git`** can re-tune the map as commits land (⚠ CLI-only; on MCP, re-run §1 when you know the repo moved).
+
+## The viral bit
+
+A beautiful, auto-generated architecture map — modules sized by weight, layers color-coded, dependency arrows, the hotspot glowing red — is *exactly* the thing devs screenshot and post: "Claude mapped my entire codebase in 30 seconds." Make every map look like that. Clean frames, honest arrows, an obvious "this is the scary part." The screenshot sells the next install.
+
+## Rules of thumb
+
+- **Always pass `compositionId`** — that's what persists the map with no tab open.
+- **Perceive the background first**; paint with it (dark board → light ink), drop the map in the user's `gaze`.
+- **Draw ~6–12 modules, not every file** — collapse a dir into one frame; surface only marquee files inside.
+- **Size by LOC, color by layer**, one module red as the hotspot.
+- **Arrows only for REAL dependencies** (A imports B → A→B); thicker = heavier coupling. Don't decorate, inform.
+- **`name` is required on every create**; capture returned frame ids to nest + connect.
+- **Need an action not listed?** `canvas-catalog { surface: "all" }` describes every one.

package/skills/design-craft/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: design-craft
+description: >-
+  The craft layer for visual work on a Clearly canvas — how to make something
+  that looks like a design studio made it, not like a first draft. Grid
+  construction, type scale, colour systems, spacing, hierarchy, optical
+  correction, and the pass to run before calling anything finished. Use whenever visual
+  quality is the point rather than an afterthought, and load it BEFORE building any poster, deck, identity, landing page, social post, cover,
+  report or diagram; clearly-canvas tells you HOW to place a node, this tells
+  you WHERE it goes and WHY. Triggers: "design", "make it look good", "make it
+  beautiful", "lay this out", "poster", "deck", "landing page", "brand", "this
+  looks off", "make it more premium", "art direct this", "clean this up".
+---
+
+# design-craft — the difference between placed and designed
+
+`clearly-canvas` teaches the mechanics: node shape, coordinates, verbs. This teaches the
+part that makes the result worth looking at.
+
+⚠ **Everything here is expressed as NUMBERS you can put on a node.** A rule you cannot act
+on is a rule you will not follow. Where a value is a judgement call, this says so.
+
+---
+
+## 0. The method: decide before you draw
+
+Pentagram — the largest independent design consultancy, partner-led with no house style —
+is **idea-led, not style-led**: each partner runs their own team, and the through-line is
+that the work answers a brief rather than expressing a signature. Michael Bierut's *How to*
+presents 35 case studies as **brief → rationale → trade-offs**, which is the useful shape:
+the reasoning is the deliverable, not the artefact.
+
+Massimo Vignelli's *Canon* gives the three questions, in order. Answer them in one line each
+before you place a single node:
+
+| | question | if you skip it |
+|---|---|---|
+| **Semantics** | What does this MEAN, to whom? | a beautiful thing about nothing |
+| **Syntactics** | What visual grammar suits it? | borrowed style, arbitrary choices |
+| **Pragmatics** | Will they understand it? | clever, unread |
+
+⚠⚠ **THE SINGLE MOST COMMON AGENT FAILURE IS SKIPPING SEMANTICS.** Asked for "a poster for a
+jazz night", a weak agent reaches for a typeface and a gradient. A studio asks what the night
+IS — basement or concert hall, 40 people or 400, regulars or first-timers — and the answer
+picks the type, the palette and the crop. **You can ask the user one sentence, or state your
+reading and proceed; you cannot skip it.**
+
+⚠ **Vignelli: "Design is one."** The discipline is above style. A deck, a poster and an app
+screen are the same problem — order, hierarchy, restraint — wearing different aspect ratios.
+
+---
+
+## 1. The grid — build it, don't eyeball it
+
+Josef Müller-Brockmann systematised this over two decades of Tonhalle Zürich posters and
+codified it in *Grid Systems in Graphic Design* (1981). The grid is not a technical
+convenience; it is what makes a composition read as ordered rather than arranged.
+
+**Construct it in this order, every time:**
+
+1. **Canvas** — pick the real output size. 1080×1350 (social 4:5) · 1080×1920 (story 9:16) ·
+   1920×1080 (deck/desktop) · 1440×1024 (web) · 2480×3508 (A4 at 300dpi).
+2. **Margin** — the single biggest lever on whether it looks professional. Start at
+   **6–8% of the short edge**. On 1080 wide that is **72px**. Go bigger for editorial (10%),
+   never smaller than 4% except for a deliberate full-bleed.
+3. **Columns** — 12 divides by 2, 3, 4 and 6, which is why it is the default. Use 6 for
+   simple work, 12 for anything with mixed content, 3–4 for a poster.
+4. **Gutter** — 2–3% of the content width. On a 936px content area, **24px**.
+5. **Baseline** — an 8pt vertical rhythm. Every y is a multiple of 8; every height is a
+   multiple of 4.
+
+**The arithmetic, done for you (1080 canvas):**
+
+```
+margin 72 · content 936 · 12 columns · gutter 24
+column = (936 − 11×24) / 12 = 56px
+column + gutter = 80px          ← every x lands on 72 + n×80
+```
+
+⚠ **A column count is a decision about CONTENT, not a default.** Three columns of body copy
+at 1080 wide gives a 96-character measure, which is unreadable. Pick the grid the content
+needs, then hold it.
+
+⚠⚠ **THE GRID IS A SKELETON, NOT A CAGE.** Müller-Brockmann's own posters break it — one
+element crossing the grid is what creates tension. **Break it once, deliberately, and hold
+everything else.** Two breaks and there was no grid.
+
+---
+
+## 2. Type — the whole game
+
+**Use a modular scale.** Pick a base and a ratio; every size is the base multiplied or
+divided by the ratio. Sizes that share a ratio look related; sizes picked by hand do not.
+
+| ratio | name | use for |
+|---|---|---|
+| 1.125 | Major second | dense UI, documentation, dashboards |
+| 1.250 | Major third | product UI, reports, general purpose |
+| 1.333 | Perfect fourth | editorial, marketing pages — the safe default |
+| 1.500 | Perfect fifth | posters, covers, decks |
+| 1.618 | Golden | display work with very few sizes |
+
+**A perfect-fourth scale from a 16px base** (round to whole pixels, then round to the 4-grid):
+
+```
+16 · 21 · 28 · 38 · 50 · 67 · 89 · 119 · 158 · 211
+```
+
+**Rules that survive contact with real work:**
+
+- ⚠⚠ **THREE SIZES PER SURFACE.** Display, body, caption. A fourth is almost always a
+  hierarchy failure you are papering over. Count them before you finish.
+- **ONE typeface, two weights, is a stronger position than two typefaces.** If you use two,
+  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.
+- ⚠⚠ **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
+  than any other single change.
+- **Never centre more than three lines.** Centred text has two ragged edges; the eye needs
+  one hard edge to return to.
+
+⚠ **MEASURE, DO NOT GUESS.** `canvas.measure-text {text, size, fontWeight, letterSpacing,
+maxWidth}` returns `{width, height, lineCount, fits, overflowBy}` from real font metrics.
+Guessing a per-character ratio is how a headline ships bleeding past its margin — a 182px
+headline estimated at 867px measured **990**.
+
+---
+
+## 3. Colour — a system, not a mood board
+
+**Build the palette from a role list, not from colours you like:**
+
+```
+ground     the surface everything sits on         1 colour
+ink        primary text on that ground            1
+ink-muted  secondary text                         1
+accent     the brand / the one thing that shouts  1
+support    2–3 tones for charts, states, depth
+```
+
+- ⚠⚠ **ONE ACCENT.** Two accents means neither is one. If the work needs a second bright
+  colour, it is a *support* tone and must be visibly quieter.
+- **60 / 30 / 10** — ground, secondary surface, accent. If the accent is over ~10% of the
+  area it has stopped being emphasis.
+- **Contrast is a measurement, not an opinion.** Body text ≥ **4.5:1**, large/display ≥ **3:1**.
+  Check it; do not eyeball dark grey on mid grey.
+- ⚠ **Avoid pure `#000` on pure `#FFF` for large areas** — the contrast is harsh and reads
+  cheap in print and on OLED. `#111` on `#FAFAF8` is the same legibility, better texture.
+- ⚠ **A dark UI needs a LIGHTER accent than a light one.** The same green that sings on white
+  goes muddy on near-black; lift lightness ~10% for dark grounds.
+- **Colour last, or colour first — never in the middle.** Compose in greyscale to prove the
+  hierarchy works on VALUE alone, then add colour. If it only works in colour, it does not work.
+
+---
+
+## 4. Space — the cheapest quality signal there is
+
+- **Spacing is a scale**, same as type: `4 · 8 · 12 · 16 · 24 · 32 · 48 · 64 · 96 · 128`.
+  Never an arbitrary 27.
+- ⚠⚠ **PROXIMITY BEATS EVERY OTHER GROUPING DEVICE.** A label 8px from its value and 48px
+  from the next pair needs no line, no box and no colour to be understood. **Reach for space
+  before you reach for a border.**
+- **Space between groups must be visibly larger than space within them** — aim for ≥2×. If
+  a card's internal padding is 24, the gap between cards is 48+, not 32.
+- ⚠ **Padding is not symmetrical when type is involved.** Text sits optically high in its
+  box because of descender space, so a visually centred label usually needs 2–4px more
+  padding on top than bottom at body sizes, more at display.
+- **Whitespace is not "empty".** The most common studio-vs-draft difference is that the draft
+  fills the canvas. **Cutting content is a design move.**
+
+---
+
+## 5. Hierarchy — decide what wins
+
+Rank every element **before** you style it: primary / secondary / tertiary. Then:
+
+- ⚠⚠ **CHANGE ONE VARIABLE AT A TIME.** Size, weight, colour and space each signal
+  importance. Using all four at once on the same element is the signature of amateur work —
+  a heading that is bigger AND bolder AND coloured AND boxed. **Pick one, maybe two.**
+- **One focal point per surface.** Where does the eye land first? If you cannot answer in
+  one second, neither can the reader.
+- **Scale contrast should be decisive.** A 28px heading over 24px body reads as a mistake;
+  38 or 50 over 16 reads as a decision. If two things are nearly the same size, make them
+  the same size.
+- **Alignment creates order for free.** Every element should align to something else. A
+  single unaligned element is read as an error, not as freedom.
+
+---
+
+## 6. Optical correction — where the numbers stop being right
+
+The renderer is mathematically correct and the eye is not. These are the adjustments that
+separate work that is *measured* from work that *looks* right.
+
+- **Optical centring**: a thing centred in a frame looks low. Raise it ~2% of the frame
+  height. Always true for a mark inside a container.
+- **Circles and pointed shapes overshoot**: a circle the same height as a square looks
+  smaller. Make round and pointed forms ~2–3% larger to match a flat-sided neighbour.
+- **Align on the INK, not the box.** A text node's box includes ascender/descender space.
+  To align a heading's cap-height with a rule or an icon, expect to nudge 2–6px.
+- **Punctuation hangs.** A quote mark or bullet starting a line should sit slightly OUTSIDE
+  the margin, or the text edge reads as ragged.
+- ⚠ **Stroke weight does not scale with the box.** Scaling a 2px-stroked icon to 3× gives a
+  6px stroke that no longer matches its neighbours. `canvas.scale` scales strokes and fonts
+  as a unit — that is right for a whole card, wrong for an icon that must match a set.
+
+---
+
+## 7. THE STUDIO PASS — run this before you say it is done
+
+⚠⚠ **A check reads the DATA. It cannot see that the work is ugly.** Run
+`canvas.review {ids:[<artboard>]}` (or clearly-canvas's `review.mjs`). Its `verdict` and
+`craft` findings measure the boxes marked **✓** below. Then open the PNG it returns and
+judge the rest by eye. On a real build, looking caught four defects that every automated
+check called clean.
+
+```
+✓ MARGINS      Is anything closer to an edge than the margin, unintentionally?   (edge-crowding)
+□ MEASURE      Any line of body copy over ~75 characters?
+✓ SIZES        Count distinct type sizes. More than 3–4? Collapse them.          (type-sprawl flags >6 and near-duplicates; aim lower)
+□ TRACKING     Is display type still at default spacing? Tighten it.
+✓ ALIGNMENT    Pick any element — what is it aligned to? If nothing, fix it.     (near-miss-alignment catches 1–3px misses only)
+□ SPACE        Is between-group space ≥ 2× within-group space?
+□ FOCAL        Where does the eye land first? Is that the most important thing?
+□ GREYSCALE    Does the hierarchy survive with colour removed?
+✓ CONTRAST     Body ≥ 4.5:1, display ≥ 3:1 — measured, not guessed.           (contrast; text-over-image means look)
+□ ACCENT       Exactly one? Under ~10% of the area?                            (palette-sprawl flags a scatter)
+□ ORPHANS      Any single word alone on the last line of a heading?
+□ CONSISTENCY  Same corner radius, same stroke weight, same gap, everywhere?
+✓ EDGE         Zoom to 100%. Does anything touch, overlap or clip?             (text-collision, text-covered, overflow)
+```
+
+A **✓** check that comes back clean only means the numbers passed. Still look at the pixels.
+
+A first draft almost always has something this pass should change, so if you changed nothing,
+run it again on the thumbnail. If it is still clean, say what you checked. Never make a change
+only to show that a review happened.
+
+---
+
+## 8. Canvas recipes — the numbers, ready to use
+
+**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)
+caption 16 (weight 600, tracking +1.5, uppercase)
+rule 2–3px accent · footer block bottom-aligned at 1350 − 72 − blockHeight
+```
+
+**A 1920×1080 deck slide**
+```
+margin 120 · title 72–96 · body 28–32 · caption 20
+Never more than ~40 words. A slide is a headline with evidence, not a document.
+Content column ≤ 1200 wide even though the slide is 1920 — full width is unreadable.
+```
+
+**A 1440 web hero**
+```
+margin 96 · content max 1200 · headline 64–88 (tracking −2, lineHeight 1.05)
+sub 20–24 (muted ink, w ≤ 640) · CTA 48–56 tall, 24–32 horizontal padding, radius 8 or full
+```
+
+**A card**
+```
+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.
+```
+
+---
+
+## 9. What to do when asked to "make it better"
+
+In order, because the earlier ones are cheaper and do more:
+
+1. **Increase the margins.** Nine times in ten, it is too tight.
+2. **Remove a type size.** Collapse the two closest into one.
+3. **Track the display type negative.**
+4. **Double the space between groups.**
+5. **Remove the second accent colour.**
+6. **Align one stray element** to the nearest grid line.
+7. **Cut 20% of the words.**
+8. Only now consider a new typeface, a texture or an effect.
+
+⚠ **Do not answer "make it more premium" with more ornament.** Premium reads as *more space,
+fewer elements, tighter type, one accent*. Every ornament added is a step away from it.
+
+---
+
+## Sources
+
+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
+Theater identity (typography as the whole system) · Pentagram's partner-led, idea-led model.