beehaven 0.8.29 → 0.8.34

package/skills/clearly-canvas/example.mjs

@@ -1,78 +1,81 @@
 #!/usr/bin/env node
-/** Example of a reusable native-node builder. Writes JSON only; it never calls a workspace. */
+/** Three editable page states. Writes JSON only; it never calls a workspace. */
 import { writeFileSync } from 'node:fs';
 
 const [compositionId, output = '/tmp/fieldwork-build.json'] = process.argv.slice(2);
 if (!compositionId) throw new Error('Usage: node example.mjs <composition-id> [output.json]');
-const grid = { w: 1440, h: 900, margin: 88, gutter: 80 };
-const ink = '#172824', paper = '#F2F0E7', orange = '#C84A2E', muted = '#58685E';
 const batch = [];
 const op = (action, args) => batch.push({ action, args });
-const frame = (name, index, fill) => op('frame.create', {
-  id: name, name, x: index * (grid.w + grid.gutter), y: 0, w: grid.w, h: grid.h, fill,
-});
-const node = (parentId, name, type, x, y, w, h, props) => op('canvas.create-node', {
-  id: `${parentId}-${name}`, name: `${parentId}-${name}`, parentId, type, x, y, w, h, ...props,
-});
-const text = (p, name, copy, x, y, w, size = 24, fill = ink, weight = 400, extra = {}) =>
-  node(p, name, 'text', x, y, w, undefined, { text: copy, size, family: 'Inter', fontWeight: weight,
-    lineHeight: 1.12, fill, ...extra });
-const rect = (p, name, x, y, w, h, fill, extra = {}) => node(p, name, 'rect', x, y, w, h, { fill, ...extra });
-const circle = (p, name, x, y, d, fill, extra = {}) => node(p, name, 'ellipse', x, y, d, d, { fill, ...extra });
-const rule = (p, y, color) => rect(p, `rule-${y}`, grid.margin, y, grid.w - grid.margin * 2, 1, color);
-const masthead = (p, index, color) => {
-  text(p, 'brand', 'FIELDWORK', grid.margin, 52, 400, 20, color, 700, { letterSpacing: 2 });
-  text(p, 'series', 'DESIGN NOTES     /     VOL. 01', 912, 54, 440, 14, color, 400, { letterSpacing: 1 });
-  text(p, 'folio', 'STUDIO PRACTICE', grid.margin, 828, 900, 14, color, 400, { letterSpacing: 1 });
-  text(p, 'page', String(index).padStart(2, '0'), 1304, 828, 48, 14, color, 400, { align: 'right' });
-};
-
-// Brief: show how one simple visual idea becomes a coherent editorial system.
-// Hierarchy: statement → geometric proof → compact practical explanation.
-// Motif: two fields meet to make a third; repeated with a different function on each slide.
-const cover = 'fieldwork-01';
-frame(cover, 0, paper); masthead(cover, 1, ink); rule(cover, 104, ink);
-text(cover, 'eyebrow', 'A NOTE ON MAKING', 88, 168, 560, 16, orange, 700, { letterSpacing: 2 });
-text(cover, 'title', 'Make room\nfor the idea.', 80, 228, 810, 108, ink, 700, { letterSpacing: -4, lineHeight: 1.02 });
-text(cover, 'intro', 'Good design begins with a point of view.\nThe system gives it room to grow.', 88, 538, 740, 25, muted);
-circle(cover, 'disc', 977, 233, 350, orange);
-rect(cover, 'field', 916, 385, 270, 270, ink);
-rect(cover, 'intersection', 977, 385, 209, 198, paper, { radius: 0 });
-text(cover, 'motif-caption', '01 / TWO FIELDS, ONE IDEA', 920, 696, 420, 14, muted, 400, { letterSpacing: 1 });
-rule(cover, 782, ink);
-
-const method = 'fieldwork-02';
-frame(method, 1, ink); masthead(method, 2, paper); rule(method, 104, '#607369');
-text(method, 'title', 'One idea.\nMany expressions.', 80, 164, 1120, 92, paper, 700, { letterSpacing: -3, lineHeight: 1.04 });
-text(method, 'intro', 'Keep the visual logic.\nChange what the content needs.', 952, 380, 400, 24, '#C7CFC4');
-const concepts = [
-  { x: 88, title: '01 / EMPHASIS', body: 'Let one thing lead.', kind: 0 },
-  { x: 520, title: '02 / RELATIONSHIP', body: 'Make the connection visible.', kind: 1 },
-  { x: 952, title: '03 / RHYTHM', body: 'Repeat with a reason.', kind: 2 },
-];
-for (const c of concepts) {
-  const y = 518;
-  if (c.kind === 0) { circle(method, 'emphasis', c.x, y, 152, orange); circle(method, 'quiet', c.x + 192, y + 92, 60, paper); }
-  if (c.kind === 1) { rect(method, 'relation-field', c.x, y + 20, 148, 120, paper); circle(method, 'relation-disc', c.x + 80, y, 152, orange); }
-  if (c.kind === 2) for (let i = 0; i < 4; i++) rect(method, `rhythm-${i}`, c.x + i * 78, y + i * 20, 48, 152 - i * 20, i === 3 ? orange : paper);
-  text(method, `label-${c.kind}`, c.title, c.x, 714, 380, 16, paper, 700, { letterSpacing: 1 });
-  text(method, `body-${c.kind}`, c.body, c.x, 748, 380, 20, '#C7CFC4');
+const fillWidth = id => op('canvas.update-nodes', { ids: [id], patch: { layoutSizingH: 'fill' } });
+// Page, section, row, card and button share this container contract.
+function flow(id, parentId, box, layout, children) {
+  // Enable flow before adding children so reading order is creation order.
+  op('frame.create', { id, name: id, parentId, fill: 'transparent', ...box,
+    autoLayout: { direction: 'v', gap: 24, padding: 0, ...layout },
+    layoutSizingH: layout.sizingH ?? 'fixed', layoutSizingV: layout.sizingV ?? 'hug' });
+  children(id);
+  op('canvas.auto-layout', { id, direction: 'v', gap: 24, padding: 0,
+    sizingH: 'fixed', sizingV: 'hug', ...layout });
+  return id;
 }
-
-const detail = 'fieldwork-03';
-frame(detail, 2, orange); masthead(detail, 3, paper); rule(detail, 104, paper);
-text(detail, 'title', 'The work is\nin the details.', 80, 168, 1100, 106, paper, 700, { letterSpacing: -4, lineHeight: 1.03 });
-text(detail, 'intro', 'A composition is finished when the details\nserve the idea — at every scale.', 88, 436, 850, 28, paper);
-rule(detail, 566, paper);
-const details = [
-  ['TYPE', 'Measure the words.\nGive them a voice.'],
-  ['SPACE', 'Group what belongs.\nLet the rest breathe.'],
-  ['REVIEW', 'Look at the result.\nMake the next decision.'],
-];
-details.forEach(([label, body], i) => {
-  const x = grid.margin + i * 432;
-  text(detail, `label-${i}`, label, x, 610, 380, 16, paper, 700, { letterSpacing: 2 });
-  text(detail, `body-${i}`, body, x, 662, 390, 28, paper);
-});
+function text(parentId, name, copy, w, size, fill, extra = {}) {
+  const id = parentId + '/' + name;
+  op('canvas.create-node', { id, name, parentId, type: 'text', w, text: copy,
+    size, family: 'Inter', fill, lineHeight: 'auto', ...extra });
+  fillWidth(id);
+  return id;
+}
+function page(id, x, mobile = false, dark = false) {
+  const w = mobile ? 390 : 1440, pad = mobile ? 24 : 80, inner = w - pad * 2;
+  const ink = dark ? '#F2F0E7' : '#172824', ground = dark ? '#172824' : '#F2F0E7';
+  flow(id, undefined, { x, y: 0, w, h: 1000, fill: ground }, { gap: 64, padding: pad }, p => {
+    flow(p + '/navigation', p, { w: inner, h: 48 }, { direction: 'h', align: 'center', justify: 'space-between' }, nav => {
+      text(nav, 'brand', 'FIELDWORK', inner - 140, 20, ink, { fontWeight: 700 });
+      text(nav, 'edition', 'STUDIO NOTES', 140, 14, ink);
+      op('canvas.update-nodes', { ids: [nav + '/edition'], patch: { layoutSizingH: 'fixed' } });
+    });
+    fillWidth(p + '/navigation');
+    flow(p + '/hero', p, { w: inner, h: 420 }, { direction: mobile ? 'v' : 'h', gap: 48 }, hero => {
+      const copyWidth = mobile ? inner : 740;
+      flow(hero + '/copy', hero, { w: copyWidth, h: 400 }, { gap: 24 }, copy => {
+        text(copy, 'eyebrow', 'A NOTE ON MAKING', copyWidth, 14, ink, { letterSpacing: 1.5 });
+        text(copy, 'title', 'Make room for the idea.', copyWidth, mobile ? 48 : 88, ink,
+          { fontWeight: 700, letterSpacing: -2, lineHeight: '105%' });
+        text(copy, 'description', 'A shared direction. An editable system. Room for the next idea.', copyWidth, 22, ink, { lineHeight: '145%' });
+        flow(copy + '/action', copy, { w: 240, h: 56, fill: ink, radius: 8 },
+          { direction: 'h', padding: 16, align: 'center' }, button => {
+            text(button, 'label', 'Explore the studio', 208, 16, ground, { align: 'center' });
+          });
+      });
+      fillWidth(hero + '/copy');
+      // Art-directed coordinates belong inside an owning artwork frame.
+      const art = hero + '/artwork', aw = mobile ? inner : 400;
+      op('frame.create', { id: art, name: 'Artwork / two fields', parentId: hero, w: aw, h: 320, fill: '#C84A2E' });
+      op('canvas.create-node', { id: art + '/disc', name: 'Disc', type: 'ellipse', parentId: art, x: 24, y: 24, w: 220, h: 220, fill: '#F2F0E7' });
+      op('canvas.create-node', { id: art + '/field', name: 'Field', type: 'rect', parentId: art, x: 116, y: 136, w: 196, h: 160, fill: '#172824' });
+    });
+    fillWidth(p + '/hero');
+    flow(p + '/features', p, { w: inner, h: 220 }, { direction: 'grid', columns: mobile ? 1 : 3,
+      rows: mobile ? 3 : 1, rowSizes: mobile ? ['hug', 'hug', 'hug'] : ['hug'], gap: 24, rowGap: 24 }, grid => {
+      for (const [name, title, body] of [
+        ['type', 'Give ideas a voice.', 'Type scales and wraps with the available space.'],
+        ['space', 'Keep room to grow.', 'Content owns its height. Related layers move together.'],
+        ['review', 'Make the next edit.', 'Resize a card and extend its copy to check the system.'],
+      ]) {
+        const card = grid + '/' + name, cw = mobile ? inner : (inner - 48) / 3;
+        flow(card, grid, { w: cw, h: 180, fill: dark ? '#294337' : '#FFFFFF', radius: 12 }, { gap: 16, padding: 24 }, c => {
+          text(c, 'title', title, cw - 48, 24, ink, { fontWeight: 600 });
+          text(c, 'body', body, cw - 48, 18, ink, { lineHeight: '145%' });
+        });
+        fillWidth(card);
+      }
+    });
+    fillWidth(p + '/features');
+    text(p, 'footer', 'FIELDWORK / A SYSTEM READY FOR CHANGE', inner, 14, ink, { letterSpacing: 1 });
+  });
+}
+page('01-desktop', 0);
+page('02-mobile', 1520, true);
+page('03-dark', 1990, false, true);
 writeFileSync(output, JSON.stringify({ compositionId, batch }, null, 2) + '\n');
-process.stdout.write(`${output}: ${batch.length} operations\n`);
+process.stdout.write(output + ': ' + batch.length + ' operations\n');

package/skills/clearly-docs/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: clearly-docs
+description: >-
+  Read, search, edit and recover a company's documents in a Clearly workspace.
+  Use the seven-tool MCP filesystem for ordinary work; use the `beehaven` CLI
+  only for document history, diffs, and restore. Load this whenever the answer
+  depends on what the company has written down, or when you are about to write
+  something down for it. Triggers: "what do our docs say", "find the doc about
+  X", "update the spec", "write this up", "add it to the docs", "has this
+  changed", "what did they edit", "search the wiki", "company knowledge", "our
+  documentation", "the PRD", "the runbook".
+---
+
+> **Tool names below are written UNPREFIXED** (`clearly_read`). Your runtime may expose them
+> with a server prefix — e.g. `mcp__plugin_clearly_clearly__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 — these skills still LIST when it isn't, so you find out by firing a dead call.
+> Authorise it (`/mcp`, or `claude mcp`).
+
+## What this is
+
+The workspace is a **filesystem**, not a chat surface with a search box.
+
+```
+~/                       every document
+~/clearly.md             what is settled for the whole workspace
+~/<Folder>/              one directory per project
+~/<Folder>/clearly.md    what is settled for that folder
+~/.archive/              put away — hidden, readable, read-only, still searched
+```
+
+Folders are projects. Documents are `.md` files named `<KEY> <Title>.md` — e.g.
+`CLR-42 Pricing.md`. The key is an address: `cat ~/CLR-42.md` works from anywhere, and so does
+the full name and the bare title.
+
+## The loop
+
+**Find it, then open it.** `clearly_glob` answers "what is it called", `clearly_grep` answers
+"where is this mentioned", and `clearly_read` opens what either one returned.
+
+```
+clearly_glob  { pattern: "~/**/*.md" }
+clearly_grep  { pattern: "pricing", limit: 5 }
+clearly_read  { target: "~/Prepress/CLR-42 Pricing.md" }
+```
+
+⚠ **`clearly_grep` takes a REGEX, unparsed** — `|`, `(`, `$` and quotes mean what they mean in a
+regular expression. Nothing shells out, so nothing eats them as syntax first.
+
+⚠ **Archived documents are excluded from both.** When any matched, the result carries
+`archivedHidden` saying how many — mention that rather than reporting a clean miss. Search the
+archive by naming it: `clearly_grep { pattern: …, path: "~/.archive" }`.
+
+**Structural questions — a date range, a null body, counts — have no keyword to search for**, so
+they go to SQL over the workspace's own tables. That is a CLI job, not an MCP tool:
+
+```
+beehaven call bash '{"command":"sql SELECT title, updated_at FROM notes WHERE project_id IS NULL LIMIT 20"}'
+```
+
+Read-only, one statement, credential columns redacted.
+
+## ⚠⚠ Read before you write, and check what changed
+
+This is the part that makes documentation stay true, and it is the part agents skip.
+
+The MCP read/edit/replace tools cover the current body. Document history is a separate CLI surface:
+
+- **`beehaven call document-status '{"limit":20}'`** lists recent changes. `mine: true` is the
+  certain signal that the active agent made the latest change. `by: "unknown"` means the log has
+  no author; it may be a browser edit or an older unstamped agent write, so do not claim a person
+  made it.
+- **`beehaven call document-diff '{"id":"<documentId>"}'`** follows up with added and removed
+  lines. Pass a `versionId` from status to compare against a specific checkpoint.
+
+Run status when you resume a conversation, and whenever they say something implying the document
+has moved — *"I rewrote that"*, *"take another look"*.
+
+⚠ **Their edit wins, always.** If a document now disagrees with something you concluded
+earlier, your conclusion is the stale one. You are keeping their documents, not defending your
+own record. Never quietly restore what they took out.
+
+## Editing
+
+**`clearly_edit` (find/replace) is the default. `clearly_replace` REPLACES the whole document.**
+
+To change one line of a 12,000-character document, `replace` makes you reproduce all 12,000 — and
+anything you fail to retype is gone with no error. It is also a lost-update machine: it writes
+whatever you last read, overwriting anything the human changed in between.
+
+- `clearly_edit` requires the `find` text to match **exactly once**. Ambiguity is REFUSED with a
+  count, never guessed — an agent that edits the first of three matches has changed something
+  nobody looked at.
+- Several independent document edits can be sent in one tool call with `batch`, but each batch
+  row is still one exact `{ target, find, replace, all? }` operation. There is no `multi_edit`
+  field and the batch is not transactional; inspect the per-item results and retry only failures.
+- `clearly_replace` does not accept `expected_content` or a commit-message field. If you must replace
+  a whole existing document, re-read it immediately before writing and verify the returned body.
+  Prefer `clearly_edit` whenever a precise passage change can express the job.
+
+## Comments and @mentions — say it beside the work, not instead of it
+
+A comment is ABOUT something; an edit changes it. When you have a question or a note for a person,
+leave it where they will see it, on the thing itself:
+
+```
+clearly_comment { target: "CLR-42", content: "Is this still the Q3 number? @sam" }
+clearly_comment { target: "<sheetId>", content: "Double-counts refunds", fields: { cell: "Plan!D12" } }
+clearly_comment { target: "<deckId>",  content: "Tighten this headline", fields: { slide: 3 } }
+clearly_read  { type: "comment", target: "SS-41" }          # the thread, on any item
+clearly_read  { type: "comment", target: "@me" }            # where YOU were @mentioned
+clearly_edit  { type: "comment", target: "<mentionId>", changes: { acknowledged: true } }
+```
+
+`target` is the item — a document, sheet, deck, ticket, board, thought or canvas, by id, key or exact
+title. Anchor with `fields.quote` (document), `slide` (deck, required), `cell` (sheet), `column`
+(board) or `pinId` / `x`,`y` (canvas); an anchor the item cannot carry is refused, never dropped.
+
+`@handle` mentions a person (notified) or an agent (queued in its inbox). Get real handles with
+`clearly_read { type: "comment", target, includeMentionables: true }`. The write's result lists
+`mentions`, and `unmatchedMentions` for any handle that reached **no one** — say so, do not assume.
+Acknowledge a mention once you have acted on it, or it comes back in every session.
+
+## `clearly.md` — what is settled
+
+Not a document like the others. It holds what this place IS (the work, the constraints, the
+vocabulary, the decisions that stopped moving) and **how this person wants to be worked with** —
+length, tone, format, and what irritates them, which is said once in passing and worth more than
+anything they praise.
+
+Fold a conclusion into it once it has stopped moving. Reach for `edit`, never `replace`.
+
+## Report what MOVED
+
+*"You added a paragraph about the 12-hour window to Pricing and removed the line about three
+credits"* is a report. *"I've updated the note"* is not — it costs a turn and says nothing they
+could not have assumed.
+
+## What not to do
+
+- **Do not tidy unasked.** A document that looks redundant or superseded is still theirs. If two
+  say the same thing, say so and let them choose.
+- **`delete` archives, it does not erase** — the document moves to `~/.archive/`, stays readable
+  and comes back. Report it as **archived**; "deleted" makes someone believe something is gone
+  that is not.
+- **Do not invent a media line.** `![caption](url)` renders a photo, audio or video by file
+  extension. You cannot upload, so never write one pointing at a URL you guessed — it renders
+  broken, which reads as their photo being lost. Move existing lines; never fabricate one.

package/skills/clearly-init/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: clearly-init
+description: >-
+  Connect a Clearly workspace to Claude Code or Codex and prove both the MCP and
+  CLI paths work. Prefer browser OAuth for remote HTTP clients; when an agent-bound
+  bearer credential is required, mint and install it with the active `beehaven`
+  identity. Use FIRST whenever a Clearly tool is refused for auth, returns nothing
+  on a workspace that should have content, or the user has never connected.
+  Triggers: "connect Clearly", "set up Clearly", "sign in to Clearly",
+  "authenticate", "install the MCP", "add the MCP token", "it says unauthorized",
+  "the tools are not showing up", "/mcp shows nothing", "which workspace am I in".
+---
+
+> **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.
+
+# `/clearly:init` — connect a Clearly workspace to Claude Code or Codex
+
+Run this once per machine. The plugin's `.mcp.json` points at
+`https://relay.clearly.sh/mcp`; complete authentication and verify the connection before doing
+workspace work.
+
+## Steps
+
+### 1. Authenticate (OAuth — browser sign-in)
+
+The plugin already wires the MCP server. Prefer browser OAuth:
+
+- **In Claude Code (recommended)**: run `/mcp`, select `clearly`, and choose **Authenticate**. A browser window opens for sign-in; approve and it closes itself. No token.
+- **From the shell**: `claude mcp login clearly` — same browser sign-in flow.
+- **In Codex**: `codex mcp login clearly`. If the server was added outside the plugin first, run
+  `codex mcp add clearly --url https://relay.clearly.sh/mcp`, then log in.
+
+The sign-in grants scoped access (`rpc:read` for search and read; add `rpc:write` to let the
+agent write documents and create boards or tickets). Sign out or revoke with the client's MCP
+logout command, or from Settings → **Developers** in the app.
+
+### Agent-bound token path (CLI and automation)
+
+Use this when the client cannot complete OAuth or when the credential must act as a specific agent
+identity. Sign in and select the identity first:
+
+```bash
+beehaven agent login <agent-name>
+beehaven connect home
+beehaven agent whoami
+beehaven mcp install --client codex
+```
+
+The installer writes through the client's own config command and never prints the token. Restart
+the client afterward. A static token normally carries `rpc:read` and `rpc:write`; `agent:ask` is
+OAuth-only and `rpc:admin` is reserved for configured platform admins. Never paste a bearer token
+into a document, ticket, canvas, log, or chat response.
+
+> **Working in more than one workspace?** A client stores one credential per server entry, so two
+> workspaces behind a single entry collide. Use `https://relay.clearly.sh/mcp/w/<workspaceId>` as a
+> second entry — see [the MCP docs](https://clearly.sh/docs/mcp).
+
+### 2. Verify
+
+Run `/mcp` in Claude Code, or `codex mcp list` in Codex. You should see `clearly` authenticated
+with **7 tools**:
+
+**Seven MCP tools, split by what they DO rather than by what they act on.** The four CRUD tools
+cover every artifact type — document, canvas, sheet, deck, board, ticket, project — so the tool fixes
+whether it reads or writes and `type` says what it touches.
+
+- **`clearly_catalog`** — optional, lazy machine-readable schemas. Use `{ type, operation }` before a type-specific write/edit; omit both for the compact capability overview.
+- **`clearly_read` / `clearly_create` / `clearly_edit` / `clearly_replace` / `clearly_delete`** — open one, make a new one, change part of one, overwrite one's whole body, archive one. Each takes a uniform same-operation `batch`.
+- **`clearly_comment`** — comment on any item (with @mentions), or send and reply to messages.
+- **`clearly_grep` / `clearly_glob`** — find by content, find by name. Both span notes and code.
+
+Addressed by `target`: a path (`~/Q1/Plan.md`), a key (`CLR-42`) or an id. Folders are projects,
+documents are `.md`, canvases are `.scene.json` — the extension names the type, and you pass `type`
+when it does not.
+
+**Everything else is the `beehaven` CLI**, by action name — the canvas, the Company Brain, skills,
+scheduling, stickers, billing. `beehaven actions` lists them; `beehaven call <action> '<json>'` runs
+one:
+
+```bash
+beehaven call context-search '{"query":"per-seat billing","scope":"org"}'
+beehaven call canvas-act '{"compositionId":"c_…","batch":[…]}'
+```
+
+⚠ **That split is deliberate, not a gap.** A single tool that runs whatever action the caller names
+spans safe and unsafe operations at once — a connector-directory rejection criterion, and one the
+criteria explicitly refuse to let a description paper over. So the generic door is the shell, where
+Claude Code already lives and where every call is attributed to your agent.
+
+> ⚠ **Everything requires authentication.** There is no anonymous surface: as of 2026-09-11 both
+> `tools/list` and `tools/call` resolve a credential first, and every credential is bound to an
+> agent. A 401 carries an OAuth challenge, so a capable client can recover from it by itself —
+> but a caller with no token sees no catalog, by design.
+
+## Install the CLI — the other half of the surface
+
+The seven MCP tools cover reading, writing and searching artifacts. **Everything else — the canvas,
+the Company Brain, skills, stickers — is reached with `beehaven`**, and the skills in this plugin
+assume it is on PATH. Claude Code has a shell, so this is one command:
+
+```bash
+curl -fsSL https://clearly.sh/install.sh | sh
+beehaven login          # once, opens a browser
+beehaven status         # daemon + relay, both should read UP
+```
+
+⚠ **`beehaven: command not found` is the failure to expect**, and it does not look like a missing
+install — it looks like the skill being wrong. If a `beehaven call …` line fails that way, install
+it rather than reaching for an MCP tool that does not exist.
+
+⚠ **Do not restart the user's daemon to fix something.** It is theirs; `beehaven status` tells you
+what is wrong and the message says which command fixes it.
+
+Then load the usage skill: it teaches the Company Brain + self-prompting loops — see `clearly-workflows`.
+
+A quick functional test:
+> "Map my Clearly workspace's brain using the clearly MCP."
+
+If Claude calls `clearly_catalog` and gets back the artifact types with their capabilities, the connection is live. It is a connection check and schema lookup, not a required preflight for ordinary reads/deletes.
+
+## Troubleshooting
+
+- **`Missing scope "rpc:write"`** — the sign-in didn't grant write access. Run `claude mcp logout clearly`, then re-authenticate (`/mcp` → **Authenticate**) and approve the write scope.
+- **`Not authenticated` / calls rejected** — the session expired or was revoked. Re-authenticate with `claude mcp login clearly` (or `/mcp` → **Authenticate**).
+- **`clearly` shows in `/mcp` but as unauthenticated** — the endpoint is preconfigured by the plugin; you still need to complete the browser sign-in. Select `clearly` → **Authenticate**.
+- **`Network error reaching ...`** — relay.clearly.sh might be down (rare); check https://clearly.sh status page.

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.
 ```
 
 ---