beehaven 0.8.27 → 0.8.33

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-canvas/review.mjs

@@ -1,20 +1,69 @@
 #!/usr/bin/env node
 /** Save review pixels outside the model context. No shell interpolation, no workspace mutations. */
 import { execFileSync } from 'node:child_process';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-export function rpc(action, payload) {
+export function assertReceipt(result, { requireChange = false } = {}) {
+  if (result?.ok === false || result?.error || result?.results?.some(r => r.ok === false)) {
+    throw new Error(result.error || result.results?.find(r => !r.ok)?.error || 'Canvas request failed');
+  }
+  for (const row of result?.results ?? [result]) {
+    const value = row.value ?? row;
+    if (value.ignoredFields?.length || value.rejectedFields?.length) {
+      throw new Error(`Fields were not applied: ${[...(value.ignoredFields ?? []), ...(value.rejectedFields ?? [])].join(', ')}. Some work may have landed; inspect the saved scene before retrying.`);
+    }
+    if (requireChange) {
+      const delta = value.canvasChanges;
+      const changed = ['changed', 'partial'].includes(value.outcome) || (Array.isArray(delta) ? delta.length > 0 : delta && typeof delta === 'object'
+        ? Number(delta.added || 0) + Number(delta.changed || 0) + Number(delta.removed || 0) > 0
+        : value.placed === true || /\.create(-node)?$/.test(String(row.action || '')) && !!value.id && !value.duplicate);
+      if (!changed) throw new Error('No nodes changed, or the receipt does not prove a change. Inspect the saved scene; do not treat a match as an update.');
+    }
+  }
+  return result;
+}
+
+export function rpc(action, payload, options) {
   const stdout = execFileSync('beehaven', ['call', action, '-'], {
     input: JSON.stringify(payload), encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
     stdio: ['pipe', 'pipe', 'pipe'], timeout: 120_000,
   });
   const result = JSON.parse(stdout);
-  if (result.ok === false || result.error || result.results?.some((r) => r.ok === false)) {
-    throw new Error(result.error || result.results.find((r) => !r.ok)?.error || 'Canvas request failed');
+  return assertReceipt(result, options);
+}
+
+export function sceneNodes(result) {
+  if (!Array.isArray(result?.nodes)) throw new Error('Expected composition-detail includeScene:true to return top-level nodes. Refusing to interpret a missing field as an empty canvas.');
+  return result.nodes;
+}
+
+/** Resume creates only. Existing layers are preserved, including the person's later edits. */
+export function resumeCanvasPlan(plan, snapshot, idManifest = {}) {
+  const nodes = sceneNodes(snapshot), byId = new Map(nodes.map(n => [n.id, n]));
+  const names = new Map();
+  for (const n of nodes) { const list = names.get(n.name) ?? []; list.push(n); names.set(n.name, list); }
+  const roots = new Map(), batch = [], skipped = [];
+  for (const step of plan.batch ?? []) {
+    const args = { ...(step.args ?? {}) };
+    if (!['frame.create', 'canvas.create-node'].includes(step.action)) { skipped.push({ action: step.action, reason: 'Resume preserves existing mutations; revise explicitly.' }); continue; }
+    const type = step.action === 'frame.create' ? 'frame' : args.type;
+    const pinned = args.id || idManifest[args.name];
+    const matches = names.get(args.name) ?? [];
+    if (!pinned && matches.length > 1) throw new Error(`Ambiguous layer name ${args.name}; use its recorded ID.`);
+    const existing = pinned ? byId.get(pinned) : matches[0];
+    if (existing) {
+      if (existing.type !== type) throw new Error(`Layer ${args.name} has type ${existing.type}, expected ${type}. No automatic replacement.`);
+      roots.set(args.name, existing.id); skipped.push({ id: existing.id, name: args.name, reason: 'Already exists; preserved.' }); continue;
+    }
+    args.id = pinned || `plan-${createHash('sha256').update(`${plan.compositionId}:${args.name}`).digest('hex').slice(0, 24)}`;
+    if (args.parentId && roots.has(args.parentId)) args.parentId = roots.get(args.parentId);
+    roots.set(args.name, args.id);
+    batch.push({ ...step, args });
   }
-  return result;
+  return { compositionId: plan.compositionId, expectedCanvasNodesRev: snapshot.canvasNodesRev, batch, skipped };
 }
 
 export function saveReview(report, prefix) {
@@ -24,7 +73,21 @@ export function saveReview(report, prefix) {
   }
   const bytes = Buffer.from(preview.dataUrl.slice('data:image/png;base64,'.length), 'base64');
   if (!bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) throw new Error('Invalid PNG response');
-  const base = resolve(prefix);
+  if (bytes.length < 45 || bytes.readUInt32BE(8) !== 13 || bytes.subarray(12,16).toString() !== 'IHDR'
+    || !bytes.readUInt32BE(16) || !bytes.readUInt32BE(20)) throw new Error('Invalid PNG response: missing image header/body');
+  let offset = 8, imageData = false, end = false;
+  while (offset + 12 <= bytes.length) {
+    const length = bytes.readUInt32BE(offset), tag = bytes.subarray(offset+4,offset+8).toString();
+    if (offset + length + 12 > bytes.length) throw new Error('Invalid PNG response: truncated image chunk');
+    if (tag === 'IDAT' && length > 0) imageData = true;
+    offset += length + 12;
+    if (tag === 'IEND') { end = length === 0; break; }
+  }
+  if (!imageData || !end) throw new Error('Invalid PNG response: missing image data/end');
+  let base = resolve(prefix);
+  const original = base;
+  let version = 0;
+  while (existsSync(`${base}.png`) || existsSync(`${base}.json`)) base = `${original}-r${report.canvasNodesRev ?? 'unknown'}-${++version}`;
   mkdirSync(dirname(base), { recursive: true });
   const { dataUrl, url, ...metadata } = preview;
   const saved = { ...report, preview: { ...metadata, path: `${base}.png` } };
@@ -34,16 +97,47 @@ export function saveReview(report, prefix) {
   return { png: `${base}.png`, report: `${base}.json`,
     // `fix` = a probable defect remains: fix it, or pass its check/id in `ignore` with a reason.
     // `look` = only things worth a second look. `clean` = nothing mechanical found — NOT "good".
-    verdict: report.verdict ?? 'unknown', blocking: report.blocking,
+    verdict: report.verdict ?? 'unknown', acceptanceStatus: report.acceptanceStatus,
+    acceptedFindings: report.acceptedFindings ?? [], blocking: report.blocking,
     craft: craft.map((f) => `${f.severity} ${f.check}: ${f.detail}`),
+    audit: (report.audit?.violations ?? []).map(v => ({check:v.kind,layer:v.name || v.id,detail:v.detail || v.message || v.reason || `${v.kind} on ${v.name || v.id}`})),
+    scopeWarnings: report.scopeWarnings ?? [],
+    assets: (report.assets ?? []).filter(a => a.status !== 'ready'),
+    typography: (report.typography?.text ?? []).filter(t => t.issue || t.horizontalOverflow > 1 || !t.autoHeight && t.verticalOverflow > 1 || t.exact === false)
+      .map(t => ({layer:t.name || t.id,issue:t.issue,horizontalOverflow:t.horizontalOverflow,verticalOverflow:t.verticalOverflow,
+        requestedFont:t.font?.requestedFamily,requestedWeight:t.font?.requestedWeight,resolvedFile:t.font?.file,exact:t.exact})),
     nodes: report.scope?.nodeCount, findings: report.audit?.total, textChecked: report.typography?.checked,
     textOmitted: report.typography?.omitted, visualReviewRequired: true,
     note: report.verdict === 'fix'
-      ? 'Fix every warn (or justify it with ignore), then review again. Then open the PNG and critique it.'
+      ? 'Fix every warn (or accept an exact finding with a reason), then review changed artboards. Then open the PNG and critique it.'
       : 'Open the PNG with your image-viewing tool, critique it against the studio bar, revise and render again.' };
 }
 
-export function main(argv = process.argv.slice(2)) {
+export async function saveReviewPixels(report, prefix, fetchImage = fetch) {
+  if (report.preview?.dataUrl) return saveReview(report, prefix);
+  const url = report.preview?.url;
+  if (!url || !/^https?:\/\//.test(url)) throw new Error(report.previewError || 'No downloadable preview. Visual verification is incomplete.');
+  const response = await fetchImage(url);
+  if (!response.ok) throw new Error(`Preview download failed (HTTP ${response.status}); request a fresh review.`);
+  const bytes = Buffer.from(await response.arrayBuffer());
+  return saveReview({ ...report, preview: { ...report.preview, dataUrl: `data:image/png;base64,${bytes.toString('base64')}` } }, prefix);
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  if (argv.includes('--many')) {
+    const args = argv.filter(a => a !== '--many');
+    if (args.length !== 3) throw new Error('Usage: node review.mjs --many <compositionId> <artboard-ids.json> <output-directory>');
+    const [compositionId, manifest, directory] = args;
+    const ids = JSON.parse(readFileSync(manifest, 'utf8'));
+    if (!Array.isArray(ids) || !ids.length) throw new Error('The manifest must be a non-empty artboard ID/name array.');
+    const response = rpc('canvas-act', { compositionId, action: 'canvas.review-many', args: { ids, preview: 'files' } });
+    const reports = response.results?.[0]?.value?.reviews;
+    if (!Array.isArray(reports) || reports.length !== ids.length) throw new Error('Incomplete review-many result; do not claim all artboards passed.');
+    const saved = [];
+    for (let i = 0; i < reports.length; i++) saved.push(await saveReviewPixels(reports[i], resolve(directory, `${String(i + 1).padStart(2, '0')}-${String(ids[i]).replace(/[^a-z0-9_-]/gi, '-')}`)));
+    process.stdout.write(JSON.stringify(saved, null, 2) + '\n');
+    return;
+  }
   const legacy = argv.includes('--perceive');
   const args = argv.filter((a) => a !== '--perceive');
   if (args.length !== 3) throw new Error('Usage: node review.mjs <compositionId> <frame-id-or-name> <output-prefix> [--perceive]\n--perceive: older workers, preview only; pass a frame ID.');
@@ -60,9 +154,9 @@ export function main(argv = process.argv.slice(2)) {
     report = response.results?.[0]?.value;
     if (!report?.scope) throw new Error('canvas.review unavailable. Check canvas-catalog; use --perceive for an explicitly preview-only check on an older worker.');
   }
-  process.stdout.write(JSON.stringify(saveReview(report, prefix), null, 2) + '\n');
+  process.stdout.write(JSON.stringify(await saveReviewPixels(report, prefix), null, 2) + '\n');
 }
 
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  try { main(); } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }
+if (process.argv[1] && existsSync(process.argv[1]) && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  main().catch(error => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });
 }

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.