@clearlysh/beehaven 0.8.29 → 0.8.31

package/dist/watcher.js

@@ -1,18 +1,19 @@
 // ============================================================================
 // Beehaven Office - Claude Code Event Watcher
-// Primary: Unix domain socket HTTP server at /tmp/beehaven.sock
+// Primary: HTTP server on a local socket — /tmp/beehaven.sock, or a named pipe on Windows (ipc-path.ts)
 // Fallback: Watches the JSONL events file written by the hook script
 // ============================================================================
 // chokidar is imported lazily so a missing bundle (e.g. when the daemon ships
 // inside an Electron app whose node_modules layout doesn't include chokidar)
 // degrades the file-watcher to a no-op rather than crashing the whole daemon.
 // The primary Unix-socket path does not depend on chokidar.
-import { createReadStream, existsSync, writeFileSync, statSync, renameSync, unlinkSync, chmodSync, watch as fsWatch, } from 'fs';
+import { createReadStream, existsSync, writeFileSync, statSync, renameSync, chmodSync, watch as fsWatch, } from 'fs';
 import { createInterface } from 'readline';
 import { createServer } from 'http';
 import { EventEmitter } from 'events';
-const EVENTS_FILE = '/tmp/beehaven-events.jsonl';
-const SOCKET_PATH = '/tmp/beehaven.sock';
+import { watcherSocketPath, eventsFilePath, clearStaleSocket, restrictSocketToOwner } from './ipc-path.js';
+const EVENTS_FILE = eventsFilePath();
+const SOCKET_PATH = watcherSocketPath();
 const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10 MB
 export { SOCKET_PATH };
 export class ClaudeWatcher extends EventEmitter {
@@ -32,14 +33,8 @@ export class ClaudeWatcher extends EventEmitter {
     // ── Unix Domain Socket ───────────────────────────────────────────────
     /** Start HTTP server on Unix domain socket for direct event delivery */
     startSocket() {
-        // Remove stale socket file
-        try {
-            if (existsSync(SOCKET_PATH))
-                unlinkSync(SOCKET_PATH);
-        }
-        catch {
-            /* may not exist */
-        }
+        // Remove a stale socket file (a Windows named pipe leaves none)
+        clearStaleSocket(SOCKET_PATH);
         this.socketServer = createServer((req, res) => {
             if (req.method !== 'POST' || req.url !== '/event') {
                 res.writeHead(404);
@@ -71,10 +66,7 @@ export class ClaudeWatcher extends EventEmitter {
         // during startup). A post-bind chmod achieves the same security
         // without the race.
         this.socketServer.listen(SOCKET_PATH, () => {
-            try {
-                chmodSync(SOCKET_PATH, 0o600);
-            }
-            catch { }
+            restrictSocketToOwner(SOCKET_PATH); // no-op for a named pipe
             console.log(`[watcher] Socket listening on ${SOCKET_PATH}`);
         });
     }
@@ -84,13 +76,7 @@ export class ClaudeWatcher extends EventEmitter {
             this.socketServer.close();
             this.socketServer = null;
         }
-        try {
-            if (existsSync(SOCKET_PATH))
-                unlinkSync(SOCKET_PATH);
-        }
-        catch {
-            /* may already be gone */
-        }
+        clearStaleSocket(SOCKET_PATH);
     }
     // ── File Watcher (fallback) ──────────────────────────────────────────
     /** Start file watcher as fallback for when socket isn't available */

package/dist/windows-hide.js

@@ -0,0 +1,77 @@
+/**
+ * windows-hide — no console windows flashing open on Windows (CAN2-56).
+ *
+ * ⚠⚠ WHY WINDOWS FLASHED. A Windows process with no console of its own — the detached daemon,
+ * or `beehaven` run by an agent or an app rather than in a terminal — that starts a CONSOLE
+ * program (cmd.exe for every `exec`/`execSync`, powershell, git, node, …) makes Windows create a
+ * brand-new console window for that child. It pops up and closes as the child exits: one flash per
+ * call, and the daemon makes calls on timers. Node prevents it per call with `windowsHide: true`;
+ * the CLI had ~140 child-process calls and one of them set it.
+ *
+ * ⚠ ONE CHOKEPOINT, NOT 140 CALL SITES. Imported FIRST by every entry point (`cli.ts`,
+ * `clearly.ts`, `daemon-entry.ts`), this wraps the `child_process` functions so `windowsHide`
+ * defaults to true for every caller in the process — this package, `@beehaven/core`, and any
+ * dependency — and `syncBuiltinESMExports()` makes ESM named imports (`import { spawn } …`) see
+ * the wrappers too. An explicit `windowsHide: false` is respected. Off Windows it does nothing.
+ *
+ * ⚠ `exec` / `execFile` carry `util.promisify.custom` (so `promisify(exec)` resolves
+ * `{ stdout, stderr }`). The wrappers forward it; without that, every `promisify(exec)` caller
+ * would silently start receiving a bare string.
+ */
+import { createRequire, syncBuiltinESMExports } from 'node:module';
+import { promisify } from 'node:util';
+const require = createRequire(import.meta.url);
+const MARK = Symbol.for('beehaven.windowsHide');
+/**
+ * A child_process call's arguments with `windowsHide: true` set, unless the caller chose a value.
+ * `takesArgv` = the second parameter may be an argv array (spawn, spawnSync, execFile,
+ * execFileSync, fork). Pure — exported for tests.
+ */
+export function withWindowsHide(args, takesArgv) {
+    const a = [...args];
+    for (let i = 1; i < a.length; i++) {
+        const v = a[i];
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            if (v.windowsHide === undefined)
+                a[i] = { ...v, windowsHide: true };
+            return a;
+        }
+    }
+    // No options object: it goes after the command (and its argv array), before any callback. An
+    // explicit `undefined`/`null` options slot is filled rather than shifted.
+    const at = takesArgv && Array.isArray(a[1]) ? 2 : 1;
+    if (at < a.length && (a[at] === undefined || a[at] === null))
+        a[at] = { windowsHide: true };
+    else
+        a.splice(at, 0, { windowsHide: true });
+    return a;
+}
+const WRAPPED = [
+    ['spawn', true], ['spawnSync', true], ['execFile', true], ['execFileSync', true], ['fork', true],
+    ['exec', false], ['execSync', false],
+];
+/** Wrap `child_process` once per process. Returns whether it is installed. `force` is for tests. */
+export function installWindowsHide(opts = {}) {
+    if (process.platform !== 'win32' && !opts.force)
+        return false;
+    const cp = require('node:child_process');
+    if (cp[MARK])
+        return true;
+    for (const [name, takesArgv] of WRAPPED) {
+        const orig = cp[name];
+        if (typeof orig !== 'function')
+            continue;
+        const wrapper = function (...args) {
+            return orig.apply(this, withWindowsHide(args, takesArgv));
+        };
+        const custom = orig[promisify.custom];
+        if (typeof custom === 'function') {
+            wrapper[promisify.custom] = (...args) => custom.apply(orig, withWindowsHide(args, takesArgv));
+        }
+        cp[name] = wrapper;
+    }
+    cp[MARK] = true;
+    syncBuiltinESMExports();
+    return true;
+}
+installWindowsHide();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clearlysh/beehaven",
-  "version": "0.8.29",
+  "version": "0.8.31",
   "description": "Beehaven CLI — command your Clearly workspace, agents, and canvas from the terminal",
   "private": false,
   "type": "module",

package/scripts/sync-skills.mjs

@@ -40,6 +40,12 @@ const SOURCES = {
   'codebase-map':   'apps/mcp-server/plugin/skills/codebase-map/SKILL.md',
   'clearly-workspace': 'apps/mcp-server/plugin/skills/clearly-workspace/SKILL.md',
   'clearly-agent':     'apps/mcp-server/plugin/skills/clearly-agent/SKILL.md',
+  // CAN2-57 — the rest of the plugin's skills: one set across plugin, CLI and Mac app.
+  'visualize':         'apps/mcp-server/plugin/skills/visualize/SKILL.md',
+  'sticker-pack':      'apps/mcp-server/plugin/skills/sticker-pack/SKILL.md',
+  'clearly-docs':      'apps/mcp-server/plugin/skills/clearly-docs/SKILL.md',
+  'clearly-init':      'apps/mcp-server/plugin/skills/clearly-init/SKILL.md',
+  'clearly-workflows': 'apps/mcp-server/plugin/skills/clearly-workflows/SKILL.md',
 };
 
 let missing = 0;

package/skills/brand-identity/SKILL.md

@@ -64,15 +64,31 @@ handover. A mark of hand-placed béziers does not, and it shows.
 | **Counter-form** | the shape is the NEGATIVE space between forms | clever marks that survive one colour |
 | **Modular** | one unit repeated/rotated on a grid | systems, networks, collectives |
 
-**Build it as an `svg` node with a stated viewBox and derived numbers:**
+**Build it from native layers, every number derived from the construction** — the way an
+identity designer works in Figma, so each part of the mark stays a named, editable layer in the
+brand colour (never one generated or hand-written SVG):
 
 ```jsonc
-{"action":"canvas.create-node","args":{"name":"mark","type":"svg","x":120,"y":120,"w":240,"h":240,
- "svg":"<svg viewBox='0 0 240 240' xmlns='http://www.w3.org/2000/svg'>…</svg>"}}
+{"batch":[
+ {"action":"frame.create","args":{"name":"Mark","x":120,"y":120,"w":240,"h":240}},
+ {"action":"canvas.create-node","args":{"type":"ellipse","name":"mark/ring","parentId":"Mark",
+   "x":20,"y":20,"w":200,"h":200,"fill":"#1B4DFF"}},
+ {"action":"canvas.create-node","args":{"type":"ellipse","name":"mark/counter","parentId":"Mark",
+   "x":70,"y":70,"w":100,"h":100,"fill":"#FFFFFF"}},
+ {"action":"vector.create","args":{"name":"mark/blade","parentId":"Mark","closed":true,"fill":"#1B4DFF",
+   "points":[{"x":120,"y":20},{"x":220,"y":120},{"x":120,"y":120}]}},
+ {"action":"canvas.group","args":{"ids":["mark/ring","mark/counter","mark/blade"],"name":"mark"}}
+]}
 ```
 
-⚠ **`<text>` inside an `svg` node does NOT render headlessly** — no system fonts are loaded.
-Wordmarks are real text nodes, or outlined paths. Never live `<text>` in the mark.
+Here R = 100: the counter is R/2, the blade's corners sit on the circle. Curves are
+`vector.create` points with `hIn`/`hOut` control points (absolute coordinates) placed where the
+construction says; a quarter-circle's handle sits 0.552·R from its anchor. A counter-form is a
+ground-colour shape layered on top; `vector.boolean` makes a true cut-out when an editor is open.
+Raw SVG (`type:"svg"`) is only for importing a mark the client already has.
+
+⚠ **Wordmarks are real text nodes, or outlined paths** — and `<text>` inside an imported `svg`
+node does NOT render headlessly (no system fonts are loaded).
 
 **Test the mark against these before going further. A mark that fails any of them is not done:**
 

package/skills/clearly-canvas/SKILL.md

@@ -110,10 +110,19 @@ can read and edit artifact records, while canvas-specific actions use the CLI.
 beehaven env
 beehaven connect home
 beehaven agent login <name> --label "Design <artifact>" --client cli
-beehaven call canvas-perceive '{"compositionId":"<id>","format":"json"}'
+beehaven call canvas-perceive '{"compositionId":"<id>","outline":true}'
 beehaven call canvas-catalog '{"query":"create-node"}'
 ```
 
+Read a canvas the way you read a repository: `canvas-perceive {outline:true}` is `tree` (artboards,
+sections, layer counts, first copy, EMPTY sections — a few hundred bytes); `{frame:"<id or name>"}`
+opens one frame like a file (its layers indented, positions relative to their parent);
+`{find:"Start free"}` is `grep` (copy, layer names or `#hex`, with each match's frame path). Use
+`format:"json"` only when you need every field of every node. Every `canvas-act` write returns
+`diagnostics` — a lint of the artboards it touched (text overflow, collisions, covered text,
+contrast) — treat them like compiler errors and fix them in the next batch. `canvas.review` is still
+the pixel check and the ticket gate.
+
 A canvas is planned like a git repository: its own plan board, a WORK TICKET for the request, and
 COMMITS — one ticket per coherent layer or section of a larger change.
 `design-start {title, brandId?}` makes a PRIVATE DRAFT canvas, bound to the brand, with its private
@@ -133,7 +142,7 @@ builds on the last and can be reviewed alone. Build ONE commit per canvas-act ba
 `canvas.review` of the artboard and carries
 `"ticket":{"id":"<key>","status":"done","resolution":"<what changed>"}` — it lands only if that
 review is clean or look; `result.ticket` says whether it did, and the ticket logs the canvas
-revision and the layers the commit changed. Auto-layout, gradients, shadows and SVG placeholders:
+revision and the layers the commit changed. Auto-layout, gradients, shadows, drawing and placeholders:
 see "Technique" in [authoring.md](authoring.md).
 
 `composition-board-get {compositionId}` reads the plan back. `design-start` with a project, ticket or
@@ -195,8 +204,11 @@ hand-author hundreds of coordinates in a chat message.
   Check contrast on the actual ground. Use the user's real brand assets.
 - Choose relevant imagery, a meaningful diagram, a product view or a deliberate
   typographic treatment. Decorative blobs and random stock photos do not prove a
-  product claim. Native SVG/paths suit diagrams and vector art; raster generation
-  suits imagery when an image tool is available.
+  product claim. Draw marks, icons, illustrations and diagrams yourself from native
+  layers (shapes, vector.create pen paths, text, groups), the way a designer works in
+  Figma, so every part stays named and editable. Raster generation suits photographic
+  imagery when an image tool is available. Raw SVG (an svg node, or a generated SVG)
+  is for importing an existing file or a requested SVG, never the default.
 - Define repeated components once. Vary composition where the content changes.
   A deck of identical cards has little rhythm even when every card aligns.
 - Keep important copy and layers editable. Do not flatten the whole composition

package/skills/clearly-canvas/authoring.md

@@ -123,14 +123,15 @@ deliverable requires them, with content order and hierarchy reconsidered for the
 
 The same rules the in-app assistant works to (canvas-catalog returns them as `technique`).
 
-- AUTO-LAYOUT: rows and stacks (nav links, button groups, card rows, form fields) are a frame whose children you create in reading order, then canvas.auto-layout { id, direction, gap, padding, align, justify, hug }. hug:false keeps the frame size, which a full-width bar needs with justify:"space-between"; set a child to layoutSizingH/V "fill" | "hug" | "fixed" with canvas.update-nodes.
+- AUTO-LAYOUT: rows and stacks (nav links, button groups, card rows, form fields) are a frame whose children you create in reading order, then canvas.auto-layout { id, direction, gap, padding, align, justify, hug }. hug:false keeps the frame size, which a full-width bar needs with justify:"space-between"; set a child to layoutSizingH/V "fill" | "hug" | "fixed" with canvas.update-nodes. The frame stays live: create more children into it (parentId) and they flow in; layoutPositioning:"absolute" takes one out of the flow.
 - GRADIENTS: gradient { kind, angle, stops: [{ offset, color }] } replaces the solid fill. angle is the direction the colour travels: 0 = left to right, 90 = top to bottom, 45 = top-left to bottom-right (not CSS degrees). Use two or three stops from the brand palette, and keep text off a busy gradient or check its contrast in canvas.review.
 - SHADOWS AND BLUR: effects on any node. A soft card shadow is { type: "drop-shadow", x: 0, y: 4, blur: 16, spread: 0, color: "#0000001F" }; frosted glass is { type: "background-blur", blur: 16 }. Never fake a shadow with an extra rectangle.
-- SVG PLACEHOLDERS: until real imagery exists, draw it as an svg node at its final size in a muted tone from the brand palette, never a flat accent block, e.g. for a 400×240 slot svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 240"><rect width="400" height="240" rx="12" fill="#EDE6DF"/><circle cx="170" cy="96" r="14" fill="#CDBFB2"/><path d="M150 168l40-48 30 34 22-20 40 34z" fill="#CDBFB2"/></svg>' — <svg viewBox="0 0 W H"> always matches the node w and h. Put a label in its own text node and name the svg "<section> image placeholder". Hand-write only simple marks like this (placeholders, dividers, UI icons); logos, illustrations and finished artwork come from svg-make.
+- DRAWING: build every mark, icon, illustration and diagram shape from native layers, as a designer does in Figma, never as one generated SVG file. Primitives are canvas.create-node rect and ellipse; curves are pen paths, vector.create { name, parentId, points: [{ x, y, hIn?: { x, y }, hOut?: { x, y } }], closed, fill or stroke, strokeWidth }, where hIn/hOut are absolute control points: use few anchors with smooth handles, and refine with vector.read, vector.vertex.move and vector.handle.set. Round caps and joins: canvas.update-nodes patch { strokeCap: "round", strokeJoin: "round" }. Work back to front: ground, big silhouettes in flat brand colours, then features, then details and highlights; check the silhouette in canvas.review before detailing. Name layers by part ("fox/ear-left"), group each figure with canvas.group { ids, name } and set overlap with canvas.order { ids, op }. Make a cut-out by layering a ground-colour shape on top; vector.boolean { op } on selected paths needs an open editor. Keep one stroke weight per drawing. Photographic or painterly imagery is a placed raster. Raw SVG stays supported but is never the default: when an SVG is asked for, write the markup yourself as an svg node, canvas.create-node { type: "svg", name, w, h, svg } with <svg viewBox="0 0 W H"> matching w and h, or import existing markup the same way; never an SVG generation pipeline.
+- PLACEHOLDERS: until real imagery exists, draw a native placeholder at the final size in a muted brand tone, never a flat accent block: a rect with the slot radius plus a simple motif (an ellipse sun, a vector.create mountain), grouped with canvas.group and named "<section> image placeholder", with any label in its own text node.
 - SECTIONS: one frame per page section, named exactly as its ticket says, inside the page artboard. Build a section in one canvas-act batch that ends with canvas.review of the artboard and carries ticket: { id: "<its key>", status: "done", resolution: "<what changed>" }. The ticket moves only when that review is clean or look; result.ticket says whether it did. Then start the next section.
 
 Use `arrow.create {from,to,routing,label}` for connected diagrams, so arrows remain bound
-when nodes move. Use native shapes and SVG for custom vector details. Keep labels as
+when nodes move. Draw custom vector details natively (shapes, vector.create pen paths); raw SVG only imports an existing file. Keep labels as
 native text so they remain editable and measurable.
 
 Use `canvas.place {kind,id,x,y,w,h,name,parentId?}` to put a workspace object (document,

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.