@clearlysh/beehaven 0.8.30 → 0.8.32

package/dist/dashboard.js

@@ -17,6 +17,59 @@ import { readFileSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { WebSocketServer } from 'ws';
+// ── Who may talk to this server (CAN2-64) ───────────────────────────────────
+/**
+ * ⚠⚠ A LOOPBACK PORT IS NOT A PRIVATE CHANNEL. Every web page the person opens can dial
+ * `ws://127.0.0.1:9800` — WebSockets ignore CORS — and so can every program on the machine,
+ * another Windows or macOS user's included. `/apps/ws` used to hand EVERY connection a
+ * developer-scope IPC client with no check at all (a comment in ipc-server.ts claimed a session
+ * cookie and an origin check that did not exist), so any website could ask the daemon for the
+ * signed-in Firebase token, run `sql`/`shell`, or install a package. Proven against a live
+ * daemon on 2026-10-13 with `Origin: https://evil.example`. The rules now:
+ *
+ *   1. The Host header must name this loopback server — a DNS-rebound hostname is refused.
+ *   2. `/apps/ws`: a PAGE must come from this server (an installed hive's frontend) or be a
+ *      `file://` page (the Mac app loads the avatar UI with `loadFile`; a web page cannot claim
+ *      `file://`), and it gets CONSUMER scope. A PROGRAM (no Origin) starts unauthenticated and
+ *      must present the daemon's IPC token with `{type:'auth'}` — the pipe's own boundary. Any
+ *      other origin, `null` included (sandboxed iframes send it), is refused at the upgrade.
+ *   3. JSON routes answer CORS only to loopback origins (a dev server on localhost). Browser
+ *      building modules stay `*`: clearly.sh imports that public code cross-origin.
+ */
+export function isLoopbackHostHeader(host, port) {
+    const h = (host ?? '').toLowerCase();
+    return h === `127.0.0.1:${port}` || h === `localhost:${port}` || h === `[::1]:${port}`;
+}
+/** `http://localhost:N`, `http://127.0.0.1:N` or `http://[::1]:N` — a page served on this machine. */
+export function isLoopbackOrigin(origin) {
+    if (!origin)
+        return false;
+    try {
+        const u = new URL(origin);
+        return u.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(u.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/** A page served by THIS server. */
+export function isSelfOrigin(origin, port) {
+    return (origin === `http://127.0.0.1:${port}` ||
+        origin === `http://localhost:${port}` ||
+        origin === `http://[::1]:${port}`);
+}
+/** How a `/apps/ws` connection starts: `consumer` scope, unauthenticated (`token`), or refused (null). */
+export function appBridgeTrust(origin, port) {
+    if (!origin)
+        return 'token';
+    if (origin === 'file://' || isSelfOrigin(origin, port))
+        return 'consumer';
+    return null;
+}
+/** `/ws` streams events and accepts console logs: loopback or file pages, or programs. */
+export function metricsSocketAllowed(origin) {
+    return !origin || origin === 'file://' || isLoopbackOrigin(origin);
+}
 // ── Fallback HTML ───────────────────────────────────────────────────────────
 const FALLBACK_HTML = `<!DOCTYPE html>
 <html lang="en">
@@ -150,11 +203,28 @@ export class Dashboard {
         // first WSS's listener — both listeners fire on every upgrade event.
         // Instead we accept all upgrades and route by req.url in the
         // connection handler.
-        this._wss = new WebSocketServer({ server: this._server });
+        //
+        // Every upgrade is judged BEFORE it is accepted (see "Who may talk to this server").
+        this._wss = new WebSocketServer({
+            server: this._server,
+            verifyClient: (info, done) => {
+                const req = info.req;
+                const url = req.url ?? '';
+                const origin = req.headers.origin;
+                if (!isLoopbackHostHeader(req.headers.host, this.port))
+                    return done(false, 403, 'Forbidden');
+                if (url.startsWith('/apps/ws')) {
+                    return appBridgeTrust(origin, this.port) ? done(true) : done(false, 403, 'Forbidden');
+                }
+                if (url.startsWith('/ws'))
+                    return metricsSocketAllowed(origin) ? done(true) : done(false, 403, 'Forbidden');
+                return done(false, 404, 'Not Found');
+            },
+        });
         this._wss.on('connection', (ws, req) => {
             const url = req.url ?? '';
             if (url.startsWith('/apps/ws')) {
-                this._handleAppWsConnection(ws);
+                this._handleAppWsConnection(ws, appBridgeTrust(req.headers.origin, this.port));
             }
             else if (url.startsWith('/ws')) {
                 this._handleWSConnection(ws, req);
@@ -255,8 +325,10 @@ export class Dashboard {
     get url() {
         return `http://${this._config.host}:${this._config.port}`;
     }
+    /** The port actually bound (config 0 picks one), which the Host and Origin checks compare to. */
     get port() {
-        return this._config.port;
+        const addr = this._server?.address();
+        return addr && typeof addr === 'object' ? addr.port : this._config.port;
     }
     get running() {
         return this._server !== null;
@@ -268,6 +340,30 @@ export class Dashboard {
     _handleHTTP(req, res) {
         const url = req.url ?? '/';
         const method = req.method ?? 'GET';
+        const origin = req.headers.origin;
+        // A DNS-rebound name pointing at 127.0.0.1 carries its own Host — refuse it on every route.
+        if (!isLoopbackHostHeader(req.headers.host, this.port)) {
+            res.writeHead(403, { 'Content-Type': 'text/plain' });
+            res.end('Forbidden');
+            return;
+        }
+        /**
+         * ⚠ ONE CHOKEPOINT FOR CORS. The handlers below were written to answer `*`; every response now
+         * passes through here, which keeps `*` only for browser building modules (public code that
+         * clearly.sh imports cross-origin) and otherwise reflects a loopback origin or sends none.
+         */
+        const publicModule = /^\/apps\/[^/]+\/buildings\/[^/]+\.js$/.test(url);
+        const allowOrigin = publicModule ? '*' : isLoopbackOrigin(origin) ? origin : null;
+        const writeHead = res.writeHead.bind(res);
+        res.writeHead = (status, ...rest) => {
+            const headers = rest.find((r) => r && typeof r === 'object');
+            if (headers && 'Access-Control-Allow-Origin' in headers) {
+                delete headers['Access-Control-Allow-Origin'];
+                if (allowOrigin)
+                    Object.assign(headers, { 'Access-Control-Allow-Origin': allowOrigin, Vary: 'Origin' });
+            }
+            return writeHead(status, ...rest);
+        };
         // Handle CORS preflight
         if (method === 'OPTIONS') {
             res.writeHead(204, {
@@ -280,8 +376,14 @@ export class Dashboard {
             return;
         }
         try {
-            // Explorer API proxy — forward /api/explorer/* to the Worker
+            // Explorer API proxy — forward /api/explorer/* to the Worker. It adds the admin secret, so
+            // only this server's own explorer page (or a program, which sends no Origin) may use it.
             if (url.startsWith('/api/explorer')) {
+                if (origin && !isSelfOrigin(origin, this.port)) {
+                    res.writeHead(403, { 'Content-Type': 'text/plain' });
+                    res.end('Forbidden');
+                    return;
+                }
                 this._proxyExplorer(req, res, url);
                 return;
             }
@@ -350,6 +452,11 @@ export class Dashboard {
                 }
             }
             if (method === 'POST' && url === '/api/console') {
+                if (!metricsSocketAllowed(origin)) {
+                    res.writeHead(403, { 'Content-Type': 'text/plain' });
+                    res.end('Forbidden');
+                    return;
+                }
                 this._handleConsolePost(req, res);
                 return;
             }
@@ -702,7 +809,11 @@ export class Dashboard {
             : { installed: [], available: [] };
         this._serveJSON(res, payload);
     }
-    _handleAppWsConnection(ws) {
+    _handleAppWsConnection(ws, trust) {
+        if (!trust) {
+            ws.close(1008, 'forbidden');
+            return;
+        }
         if (!this._appBridge) {
             ws.close(1011, 'app bridge not configured');
             return;
@@ -720,7 +831,8 @@ export class Dashboard {
         // Subscribe broadly by default — browser UIs usually want to see
         // everything (pipeline:*, broadcast:*, etc.). Clients can tighten this
         // by sending their own { type: 'subscribe', patterns: [...] } message.
-        const virtId = bridge.createVirtualClient(send, ['*']);
+        // Consumer scope at most: a page never gets developer verbs (get-token, shell, sql, installs).
+        const virtId = bridge.createVirtualClient(send, ['*'], trust === 'consumer' ? 'consumer' : null);
         ws.on('message', (raw) => {
             let msg;
             try {

package/dist/ipc-server.js

@@ -602,20 +602,23 @@ export class IpcServer extends EventEmitter {
     // IPC bus so the same pipeline/app-rpc handlers serve both Claude and
     // the human UI.
     /** Register a virtual client and return its id. */
-    createVirtualClient(virtualSend, initialSubscriptions = ['*']) {
+    createVirtualClient(virtualSend, initialSubscriptions = ['*'], scope = null) {
         const id = `virt_${++this.virtualClientCounter}`;
+        /**
+         * ⚠⚠ A VIRTUAL CLIENT IS ONLY AS TRUSTED AS WHOEVER IS ON THE OTHER END OF IT (CAN2-64).
+         * This used to be `authenticated: true, scope: 'developer'` for everyone, justified by "the
+         * dashboard bridge enforces its own auth (session cookie, origin check)". It enforced none,
+         * so any web page that opened ws://127.0.0.1:9800/apps/ws could call get-token. The bridge
+         * now judges the connection (dashboard.ts `appBridgeTrust`) and passes 'consumer' or null;
+         * a null client must authenticate with the IPC token, exactly like a socket client.
+         */
         const client = {
             id,
             virtualSend,
             subscriptions: initialSubscriptions,
             buffer: '',
-            // Virtual clients are in-process — they're already inside the trust
-            // boundary. The dashboard /apps/ws bridge enforces its own auth
-            // (session cookie, origin check) before creating the virtual client,
-            // so we hand them developer scope to mirror what a logged-in tray
-            // user can already do.
-            authenticated: true,
-            scope: 'developer',
+            authenticated: scope !== null,
+            scope,
         };
         this.clients.set(id, client);
         // Mimic the on-connect status frame real clients receive so the bridge

package/dist/npm-update.js

@@ -0,0 +1,138 @@
+/**
+ * npm-update — updating a CLI that was installed with `npm install -g` (CAN2-57).
+ *
+ * ⚠⚠ npm IS THE ONLY WINDOWS INSTALL, AND IT NEVER UPDATED. The daemon's hourly updater re-runs the
+ * bash `install.sh`, so it served only `~/.beehaven/cli` installs; `beehaven update` refused npm
+ * installs and printed the npm command instead. A Windows user stayed on whatever version they
+ * first installed until they noticed the notice. Both paths now call this module.
+ *
+ * ⚠ IT UPDATES THE COPY THAT IS RUNNING, OR NOTHING. The npm that sits beside the running Node is
+ * asked for its global root; if this package is not the one installed there (an npx run, a second
+ * Node, a copied folder), installing would create a SECOND copy that shadows or is shadowed by
+ * this one — the failure `self-update.ts` documents for curl installs. So it refuses and says why.
+ *
+ * ⚠ A GLOBAL PREFIX THE USER CANNOT WRITE IS NOT "TRY sudo". Windows (`%AppData%\npm`) and
+ * Homebrew/nvm prefixes are user-writable; a system `/usr/local` usually is not, and an unattended
+ * daemon must never escalate. Not writable → the one-line manual command, nothing else.
+ *
+ * ⚠ THE EXACT VERSION, NOT `@latest`. The caller passes the version from the release manifest
+ * (`latest.json`, stable only), so the channel is decided by our publish script, never by a dist
+ * tag someone moved by hand.
+ */
+import { execFile, execFileSync } from 'child_process';
+import { accessSync, constants, existsSync, readFileSync, realpathSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join, resolve } from 'path';
+export const PACKAGE = '@clearlysh/beehaven';
+const VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+/** The npm that belongs to the Node running this process, else whatever `npm` is on PATH. */
+export function npmCommand(platform = process.platform, execPath = process.execPath) {
+    const local = join(dirname(execPath), platform === 'win32' ? 'npm.cmd' : 'npm');
+    return existsSync(local) ? local : platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+/** Windows `.cmd` shims cannot be spawned without a shell (Node refuses with EINVAL since 18.20/20.12). */
+const needsShell = (cmd) => /\.cmd$/i.test(cmd);
+const quoteForShell = (s) => (/[\s"&|<>^]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s);
+/** Run npm synchronously; returns stdout. Never inside the package directory (Windows rename locks). */
+function npmSync(npm, args, timeoutMs) {
+    const shell = needsShell(npm);
+    return execFileSync(shell ? quoteForShell(npm) : npm, args, {
+        encoding: 'utf8',
+        cwd: homedir(),
+        timeout: timeoutMs,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        shell,
+        windowsHide: true,
+    });
+}
+/**
+ * Can this install update itself with npm? `pkgRoot` is the running package's root (the folder
+ * holding its package.json).
+ */
+export function npmUpdatePlan(pkgRoot, platform = process.platform) {
+    const npm = npmCommand(platform);
+    let globalRoot;
+    try {
+        globalRoot = npmSync(npm, ['root', '-g'], 30_000).trim();
+    }
+    catch (e) {
+        return { ok: false, npm, reason: `npm is not available (${String(e?.code ?? e?.message ?? e).slice(0, 80)})` };
+    }
+    const real = (p) => { try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    } };
+    const installed = join(globalRoot, ...PACKAGE.split('/'));
+    if (real(installed).toLowerCase() !== real(pkgRoot).toLowerCase()) {
+        return { ok: false, npm, globalRoot, reason: `this copy (${pkgRoot}) is not npm's global install (${installed})` };
+    }
+    try {
+        accessSync(globalRoot, constants.W_OK);
+        accessSync(installed, constants.W_OK);
+    }
+    catch {
+        return { ok: false, npm, globalRoot, reason: `npm's global folder is not writable by you (${globalRoot})` };
+    }
+    return { ok: true, npm, globalRoot };
+}
+/** The version npm's global install of this package reports, read from disk. */
+export function installedNpmVersion(globalRoot) {
+    try {
+        return JSON.parse(readFileSync(join(globalRoot, ...PACKAGE.split('/'), 'package.json'), 'utf8')).version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The newest published version, from npm (for `beehaven update`; the daemon uses the release manifest). */
+export function latestNpmVersion(npm) {
+    try {
+        const v = npmSync(npm, ['view', PACKAGE, 'version', '--registry=https://registry.npmjs.org'], 30_000).trim();
+        return VERSION_RE.test(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The arguments that install exactly `version` globally — exported so the shape is pinned. */
+export function npmInstallArgs(version) {
+    if (!VERSION_RE.test(version))
+        throw new Error(`not a release version: ${version}`);
+    return ['install', '-g', `${PACKAGE}@${version}`, '--no-audit', '--no-fund', '--registry=https://registry.npmjs.org'];
+}
+/** Install `version` (blocking — the CLI's `update`). Verifies what landed on disk. */
+export function installNpmVersionSync(plan, version) {
+    if (!plan.ok || !plan.globalRoot)
+        return { ok: false, message: plan.reason ?? 'npm update not possible here' };
+    try {
+        npmSync(plan.npm, npmInstallArgs(version), 5 * 60_000);
+    }
+    catch (e) {
+        const detail = String(e?.stderr || e?.message || e).trim().split('\n').slice(-3).join(' ').slice(0, 240);
+        return { ok: false, message: `npm install failed: ${detail}` };
+    }
+    const got = installedNpmVersion(plan.globalRoot);
+    return got === version
+        ? { ok: true, message: `Updated to ${version}.` }
+        : { ok: false, message: `npm reported success but ${got ?? 'nothing'} is installed, not ${version}.` };
+}
+/** Install `version` without blocking the event loop (the daemon's hourly updater). */
+export function installNpmVersion(plan, version) {
+    return new Promise((resolveP) => {
+        if (!plan.ok || !plan.globalRoot)
+            return resolveP({ ok: false, message: plan.reason ?? 'npm update not possible here' });
+        const shell = needsShell(plan.npm);
+        execFile(shell ? quoteForShell(plan.npm) : plan.npm, npmInstallArgs(version), {
+            cwd: homedir(), timeout: 5 * 60_000, shell, windowsHide: true,
+        }, (err, _out, stderr) => {
+            if (err)
+                return resolveP({ ok: false, message: `npm install failed: ${String(stderr || err.message).trim().split('\n').slice(-3).join(' ').slice(0, 240)}` });
+            const got = installedNpmVersion(plan.globalRoot);
+            resolveP(got === version
+                ? { ok: true, message: `Updated to ${version}.` }
+                : { ok: false, message: `npm reported success but ${got ?? 'nothing'} is installed, not ${version}.` });
+        });
+    });
+}

package/dist/verb-surface.js

@@ -60,6 +60,7 @@ export const VERB_SURFACE = {
     logout: { cls: 'STRUCTURAL', why: 'clears local credentials' },
     signup: { cls: 'STRUCTURAL', why: 'opens a browser' },
     handoff: { cls: 'STRUCTURAL', why: 'posts a local file to the anonymous door; no account, no workspace' },
+    'agents-md': { cls: 'STRUCTURAL', why: "writes the Clearly block into this repo's AGENTS.md; no workspace" },
     whoami: { cls: 'STRUCTURAL', why: 'reads local credentials' },
     start: { cls: 'STRUCTURAL', why: 'spawns the daemon `call` needs' },
     stop: { cls: 'STRUCTURAL', why: 'daemon lifecycle' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clearlysh/beehaven",
-  "version": "0.8.30",
+  "version": "0.8.32",
   "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/agent-doodle-space/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-doodle-space
-description: Use an agent identity's Avatar Soul and durable Doodle Space. Trigger when someone says "draw my avatar", "change my expression", "make a doodle", or wants to inspect an agent's visual identity. Read the minted appearance before drawing; save durable art to a session composition. Requires AGENT_SOUL_SPACE and is separate from avatar-shop.
+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. Use an agent identity's Avatar Soul and durable Doodle Space. Trigger when someone says "draw my avatar", "change my expression", "make a doodle", or wants to inspect an agent's visual identity. Read the minted appearance before drawing; save durable art to a session composition. Requires AGENT_SOUL_SPACE and is separate from avatar-shop.
 ---
 
 # Agent Soul + Doodle Space

package/skills/agent-home/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-home
-description: Design and inhabit an agent-owned memory apartment on Clearly's canvas. Use when someone says "build my agent home", "make a room", "save a home memory", or "move the avatar". Arrange rooms, doors, windows, furniture, avatar position, memories, journals, and Home ads on a fixed 24px grid. Requires AGENT_SOUL_SPACE.
+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. Design and inhabit an agent-owned memory apartment on Clearly's canvas. Use when someone says "build my agent home", "make a room", "save a home memory", or "move the avatar". Arrange rooms, doors, windows, furniture, avatar position, memories, journals, and Home ads on a fixed 24px grid. Requires AGENT_SOUL_SPACE.
 ---
 
 # Agent Home memory apartment

package/skills/brand-identity/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: brand-identity
 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.
   Design the requested logo or brand identity on a Clearly canvas —
   brief, mark, wordmark, lockups and clear space, palette, type system,
   applications, and a spec board someone else can build from. Use when asked

package/skills/clearly-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clearly-agent
-description: Work in a Clearly workspace AS an agent — sign in with an identity, resume a session, read your brief (what changed since you were last here, your recents, your unfiled drafts), and understand whose work you are creating. TRIGGER on the first `beehaven` call of any session, on "Not an agent" / "agent login" refusals, and when the user asks "who am I acting as", "what was I doing", "what have I made", "why can't the agent see this", "why is my work invisible", or "run this as a different agent". Read this BEFORE clearly-canvas or clearly-workspace — both need an identity and neither will work without one.
+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. Work in a Clearly workspace AS an agent — sign in with an identity, resume a session, read your brief (what changed since you were last here, your recents, your unfiled drafts), and understand whose work you are creating. TRIGGER on the first `beehaven` call of any session, on "Not an agent" / "agent login" refusals, and when the user asks "who am I acting as", "what was I doing", "what have I made", "why can't the agent see this", "why is my work invisible", or "run this as a different agent". Read this BEFORE clearly-canvas or clearly-workspace — both need an identity and neither will work without one.
 ---
 
 # clearly-agent — who you are, and what that makes your work

package/skills/clearly-canvas/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: 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.
   Design and revise editable compositions on a Clearly canvas using the beehaven
   CLI: posters, campaigns, decks, page mockups, diagrams, spatial reviews, and
   project plans built from LIVE workspace objects (boards, tickets, documents,

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.