beehaven 0.8.18 → 0.8.20

package/dist/build-channel.js

@@ -53,9 +53,9 @@ export const PUBLIC_BUILD = true;
  * ⚠ REWRITTEN IN `dist/` AT BUILD TIME, like `PUBLIC_BUILD`. `unstamped` is what a source checkout
  * carries and what `tsx`/`vitest` see, and it is honest: nothing has stamped them.
  */
-export const BUILD_SHA = 'cea58c529fe1';
+export const BUILD_SHA = '046981bccb35-dirty';
 /** ISO-8601 minute precision, UTC. Rewritten in `dist/` by `scripts/stamp-build-channel.mjs`. */
-export const BUILD_TIME = '2026-09-27T07:47Z';
+export const BUILD_TIME = '2026-09-29T05:23Z';
 /**
  * The build identity as one short string, for `--version`.
  *

package/dist/cli.js

@@ -185,6 +185,7 @@ function printHelp() {
     beehaven mv <src> <dest>       Move, or rename
 
   Work:
+    beehaven inbox                 Messages to you from people and agents  (read · send · reply · done · who)
     beehaven ticket create "<t>"   File a card on a board  (list · move · edit · show · comment)
     beehaven board list            The boards you can file to  (create · delete · report · backlog)
     beehaven sprint list           Plan, run and close a sprint  (create · plan · start · complete)
@@ -1575,6 +1576,9 @@ async function run() {
             kind: { type: 'string' },
             tags: { type: 'string' },
             title: { type: 'string' },
+            // `beehaven inbox send <to> "…" --subject "…" --refs CLR-42,<doc id>` (WIB-1).
+            subject: { type: 'string' },
+            refs: { type: 'string' },
             source: { type: 'string' },
             info: { type: 'boolean', default: false },
             // #109 — `beehaven conversations export` flags.
@@ -1598,6 +1602,8 @@ async function run() {
             svg: { type: 'string' },
             x: { type: 'string' },
             y: { type: 'string' },
+            width: { type: 'string' },
+            height: { type: 'string' },
             w: { type: 'string' },
             h: { type: 'string' },
             // `as` is also used by teleport (text | attachment |
@@ -6432,6 +6438,12 @@ complete -F _beehaven_completions beehaven`);
             await cmdMention(positionals[1] ?? '', positionals.slice(2), values);
             break;
         }
+        // WIB-1 — messages between the people and agents of a workspace.
+        case 'inbox': {
+            const { cmdInbox } = await import('./commands/inbox.js');
+            await cmdInbox(positionals[1] ?? '', positionals.slice(2), values);
+            break;
+        }
         case 'ticket':
         case 'board': {
             const { cmdTicket, cmdBoard } = await import('./commands/ticket.js');

package/dist/commands/agent.js

@@ -897,9 +897,17 @@ function printBrief(brief) {
      */
     const mentions = brief.workspace?.mentions ?? [];
     const voicemail = brief.workspace?.voicemail ?? [];
-    if (mentions.length || voicemail.length) {
+    /** WIB-1 — people and agents writing TO this agent. Oldest first; reading one clears it. */
+    const inbox = brief.workspace?.inboxThreads ?? [];
+    if (mentions.length || voicemail.length || inbox.length) {
         console.log('');
-        console.log(`  ${bold('Addressed to you')} ${dim(`(${mentions.length + voicemail.length})`)}`);
+        console.log(`  ${bold('Addressed to you')} ${dim(`(${mentions.length + voicemail.length + inbox.length})`)}`);
+        for (const t of inbox.slice(0, 5)) {
+            console.log(`    ${dim('·')} ${cyan('message')} from ${t.from}: “${t.subject}” ${dim(`${t.unread} unread · ${t.threadId}`)}`);
+            console.log(`      ${String(t.preview ?? '').replace(/\s+/g, ' ').slice(0, 120)}`);
+        }
+        if (inbox.length)
+            console.log(dim(`      Read with \`beehaven inbox read <id>\`, answer with \`beehaven inbox reply <id> "…"\`, then \`beehaven inbox done <id>\`.`));
         for (const v of voicemail.slice(0, 3)) {
             console.log(`    ${dim('·')} ${cyan('voicemail')} from ${v.from}: ${String(v.text ?? '').replace(/\s+/g, ' ').slice(0, 100)}`);
         }
@@ -912,7 +920,7 @@ function printBrief(brief) {
             console.log(dim(`      Act, reply with \`beehaven comment <ref> "…"\`, then \`beehaven mention ack <id>\`.`));
     }
     if (!sessions.length && !assigned.length && !pending.length && !memories.length && !focus.length) {
-        if (!mentions.length && !voicemail.length)
+        if (!mentions.length && !voicemail.length && !inbox.length)
             console.log(dim('     First visit — nothing to catch up on.'));
         return;
     }

package/dist/commands/canvas-image.js

@@ -0,0 +1,101 @@
+/** Upload a local raster and place it on a composition without sending base64 over the relay. */
+import { readFileSync, statSync, existsSync } from 'node:fs';
+import { basename, extname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { rpcOnce } from '../ipc-client.js';
+const IMAGE_MIME = {
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp', '.gif': 'image/gif', '.avif': 'image/avif',
+};
+const MAX_BYTES = 100 * 1024 * 1024;
+function positiveFlag(raw, label) {
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0)
+        throw new Error(`${label} must be a positive number`);
+    return value;
+}
+function coordinateFlag(raw, label) {
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isFinite(value))
+        throw new Error(`${label} must be a number`);
+    return value;
+}
+function absoluteRelayUrl(url) {
+    if (!url.startsWith('/'))
+        return url;
+    const configPath = join(homedir(), '.beehaven', 'config.json');
+    let endpoint = 'wss://relay.clearly.sh';
+    if (existsSync(configPath)) {
+        const config = JSON.parse(readFileSync(configPath, 'utf8'));
+        if (config.endpoint)
+            endpoint = String(config.endpoint);
+    }
+    return endpoint.replace(/^wss:/, 'https:').replace(/^ws:/, 'http:').replace(/\/$/, '') + url;
+}
+export async function cmdCanvasAddImage(positionals, values) {
+    const input = positionals[0];
+    const compositionId = String(values.composition ?? values.comp ?? values.c ?? '').trim();
+    if (!input || !compositionId) {
+        throw new Error('Usage: beehaven canvas add-image <local.png|jpg|webp|gif|avif> --composition <id> [--x N --y N --width N --height N]');
+    }
+    const path = resolve(input);
+    const mimeType = IMAGE_MIME[extname(path).toLowerCase()];
+    if (!mimeType)
+        throw new Error('Supported image formats: PNG, JPEG, WebP, GIF, AVIF');
+    const stat = statSync(path);
+    if (!stat.isFile())
+        throw new Error(`Not a file: ${path}`);
+    if (!stat.size || stat.size > MAX_BYTES)
+        throw new Error(`Image must be 1 byte to 100 MB (${stat.size} bytes given)`);
+    const x = coordinateFlag(values.x, '--x');
+    const y = coordinateFlag(values.y, '--y');
+    const width = positiveFlag(values.width, '--width');
+    const height = positiveFlag(values.height, '--height');
+    if ((x === undefined) !== (y === undefined))
+        throw new Error('Pass --x and --y together');
+    if ((width === undefined) !== (height === undefined))
+        throw new Error('Pass --width and --height together');
+    // Refuse an unknown target before putting bytes in storage for a canvas that cannot use them.
+    const target = await rpcOnce('composition-detail', { id: compositionId }, 30_000);
+    if (target?.error || target?.composition?.id !== compositionId) {
+        throw new Error(`Canvas not found or not accessible: ${compositionId}`);
+    }
+    const name = basename(path);
+    const safeName = name.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 64);
+    const key = `compositions/${compositionId}/images/${randomUUID()}-${safeName}`;
+    const intent = await rpcOnce('get-upload-url', {
+        key, contentType: mimeType, maxSize: stat.size, size: stat.size,
+    }, 30_000);
+    if (intent?.error || !intent?.uploadUrl || !intent?.publicUrl) {
+        throw new Error(`Could not prepare image upload: ${intent?.error ?? 'missing upload or image URL'}`);
+    }
+    const uploaded = await fetch(absoluteRelayUrl(String(intent.uploadUrl)), {
+        method: 'PUT', headers: { 'Content-Type': mimeType }, body: readFileSync(path),
+    });
+    if (!uploaded.ok)
+        throw new Error(`Image upload failed: HTTP ${uploaded.status}`);
+    const recorded = await rpcOnce('file-uploaded', {
+        key, name, mimeType, size: stat.size, composition: true,
+    }, 30_000);
+    if (recorded?.ok === false || recorded?.error) {
+        throw new Error(`Image uploaded but could not be registered: ${recorded?.error ?? 'unknown error'}`);
+    }
+    const placed = await rpcOnce('canvas-add-image', {
+        compositionId, imageUrl: absoluteRelayUrl(String(intent.publicUrl)),
+        ...(x !== undefined ? { x, y } : {}),
+        ...(width !== undefined ? { width, height } : {}),
+    }, 30_000);
+    if (placed?.ok !== true || !placed?.nodeId && !placed?.blockId) {
+        throw new Error(`Image uploaded but could not be placed: ${placed?.error ?? 'unknown error'}. Asset key: ${key}`);
+    }
+    const result = { ok: true, compositionId, nodeId: placed.nodeId ?? placed.blockId, imageFileId: recorded?.id, name };
+    if (values.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(`  Added ${name} to canvas ${compositionId} (node ${result.nodeId})`);
+}

package/dist/commands/canvas.js

@@ -155,6 +155,10 @@ export async function cmdCanvas(sub, positionals, values) {
         case 'paste-text':
         case 'text':
             return cmdCanvasPasteText(positionals, values);
+        case 'add-image': {
+            const { cmdCanvasAddImage } = await import('./canvas-image.js');
+            return cmdCanvasAddImage(positionals, values);
+        }
         // ── publish-landing — built site dir → site comp → embed block ─
         // `beehaven canvas publish-landing ./dist --composition <id>`
         // composes compose-create + compose-push + canvas-invoke into one
@@ -301,6 +305,7 @@ function printHelp() {
   beehaven canvas delete <id>                   # soft-delete a pasteboard
   beehaven canvas export <id> [--format pdf|svg|png|json]
   beehaven canvas paste-text "..." --composition <id>   # text → text block (or pipe stdin)
+  beehaven canvas add-image ./photo.png --composition <id> [--x N --y N --width N --height N]
   beehaven canvas help [domain]                 # workspace RPC catalog (cloud), grouped
   beehaven canvas help --search <q>             # keyword search the catalog
   beehaven canvas record start [sessionId]

package/dist/commands/help.js

@@ -113,7 +113,34 @@ const PAGES = {
             { cmd: 'beehaven mention who jin' },
             { cmd: 'beehaven mention resolve "cc @omni and @bob"' },
         ],
-        related: ['comment'],
+        related: ['comment', 'inbox'],
+    },
+    inbox: {
+        synopsis: 'beehaven inbox [box|read <id>|send <to> "…"|reply <id> "…"|done <id>|add|leave|who|count]',
+        description: 'Messages between the people and agents of this workspace — everyone can message everyone. You act as '
+            + 'whoever this terminal is signed in as: an agent (`beehaven agent login <name>`) has its OWN inbox, '
+            + 'separate from its owner\'s, and its unread threads are printed in its brief under "Addressed to you".\n\n'
+            + 'Reading a thread marks it read — that is the acknowledgement. Reply in the thread, then `done` it '
+            + '(archive); a new reply brings it back. Sending runs no AI: an agent you message reads it next session.\n\n'
+            + 'Boxes: inbox (default — threads someone else has written in), unread, starred, sent, archived, all. '
+            + '`<to>` takes the handles `beehaven inbox who` lists, comma-separated.',
+        flags: [
+            { name: '--search "<q>"', desc: 'On a box: only threads whose subject or messages contain it.' },
+            { name: '--subject "<s>"', desc: 'On send: the thread subject (defaults to the first line).' },
+            { name: '--refs <a,b>', desc: 'On send/reply: workspace items to link — ids, keys (CLR-42) or exact titles.' },
+            { name: '--as agent:<id>', desc: 'On a box/read: a person reading an agent they own. Read-only; marks nothing read.' },
+            { name: '--limit <n>', desc: 'On a box: how many threads (default 50).' },
+            { name: '--json', desc: 'Raw result.' },
+        ],
+        examples: [
+            { cmd: 'beehaven inbox' },
+            { cmd: 'beehaven inbox read it_m1x2_ab12cd34' },
+            { cmd: 'beehaven inbox send ada,pixel "Draft is in CLR-42 — can you review?" --refs CLR-42' },
+            { cmd: 'beehaven inbox reply it_m1x2_ab12cd34 "Done — see the second option."' },
+            { cmd: 'beehaven inbox done it_m1x2_ab12cd34' },
+            { cmd: 'beehaven inbox who' },
+        ],
+        related: ['mention', 'comment'],
     },
     ticket: {
         synopsis: 'beehaven ticket <create|list|move|edit|show|comment|comments|delete> [args]',
@@ -535,13 +562,15 @@ const PAGES = {
         related: ['cd', 'status', 'actions', 'workspaces'],
     },
     canvas: {
-        synopsis: 'beehaven canvas <open|invoke|query|actions|help|record> [args]',
+        synopsis: 'beehaven canvas <open|add-image|invoke|query|actions|help|record> [args]',
         description: `Interact with the FAB canvas (notes editor) from the CLI.
 
     Subcommands:
       open <noteId>          Open a note in the canvas editor
       invoke <action> [json] Call an editor-client action (local UI ops)
       query <action>         Read editor-client state
+      add-image <file>       Upload a local image and place it on a composition
+                             (--composition <id>, optional x/y/width/height)
       actions / list          List editor-client UI actions (LOCAL — what the
                              canvas UI can do)
       help [domain]          Show the workspace RPC catalog (CLOUD — what
@@ -563,6 +592,7 @@ const PAGES = {
             { cmd: 'beehaven canvas actions', note: 'editor UI actions (local)' },
             { cmd: 'beehaven canvas help', note: 'workspace RPC catalog (cloud)' },
             { cmd: 'beehaven canvas help --search "image"', note: 'find image-related RPCs' },
+            { cmd: 'beehaven canvas add-image ./photo.png --composition <id>', note: 'upload a local image and place it on the canvas' },
             { cmd: 'beehaven canvas invoke insert-block \'{"type":"text","text":"hi"}\'' },
         ],
         related: ['conversations', 'call', 'actions'],

package/dist/commands/inbox.js

@@ -0,0 +1,208 @@
+/**
+ * `beehaven inbox` — messages between the people and agents of a workspace (WIB-1).
+ *
+ *   beehaven inbox [box]                      your threads — box: inbox (default) | unread |
+ *                                             starred | sent | archived | all   --search "…"
+ *   beehaven inbox read <threadId>            open a thread (marks it read)
+ *   beehaven inbox send <to> "message"        start a thread — <to> is one or more handles,
+ *                                             comma-separated: "ada,pixel"
+ *       --subject "…"   --refs CLR-42,<doc id>   (workspace items to link)
+ *   beehaven inbox reply <threadId> "message" answer in a thread
+ *   beehaven inbox done <threadId>            archive it — handled (a reply brings it back)
+ *   beehaven inbox archive|unarchive|star|unstar|mute|unmute|unread <threadId>
+ *   beehaven inbox add <threadId> <to>        bring more people or agents in
+ *   beehaven inbox leave <threadId>           stop receiving a thread
+ *   beehaven inbox who [query]                everyone you can message (people and agents)
+ *   beehaven inbox count                      unread messages and threads
+ *
+ * ⚠ YOU ACT AS WHOEVER THIS TERMINAL IS SIGNED IN AS. An agent (`beehaven agent login <name>`)
+ * has its own inbox — messages to it are not its owner's, and it cannot read anyone else's.
+ * ⚠ READING IS THE ACKNOWLEDGEMENT. There is no separate ack: `read` clears the unread count,
+ * and `done` takes it out of the inbox once you have acted.
+ */
+import { agentRpc as rpcOnce, getTimeout } from './workspace.js';
+const c = {
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+    violet: (s) => `\x1b[35m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+/** ⚠ `rpcOnce` returns `{ error }` as a VALUE and never throws. */
+function failure(res) {
+    if (!res || typeof res !== 'object')
+        return 'no answer from the workspace';
+    if (typeof res.error === 'string' && res.error)
+        return res.error;
+    if (res.ok === false)
+        return String(res.message ?? res.code ?? 'the workspace refused the call');
+    return null;
+}
+function die(msg, hint) {
+    console.error(`  Error: ${msg}`);
+    if (hint)
+        console.error(c.dim(`  ${hint}`));
+    process.exit(1);
+}
+const ago = (ts) => {
+    const d = Date.now() - Number(ts || 0);
+    if (d < 60_000)
+        return 'just now';
+    if (d < 3_600_000)
+        return `${Math.round(d / 60_000)}m ago`;
+    if (d < 86_400_000)
+        return `${Math.round(d / 3_600_000)}h ago`;
+    return `${Math.round(d / 86_400_000)}d ago`;
+};
+const who = (p) => (p?.kind === 'agent' ? c.violet(String(p.name)) : String(p?.name ?? 'someone'));
+const list = (s) => s.split(',').map((x) => x.trim()).filter(Boolean);
+const BOXES = new Set(['inbox', 'unread', 'starred', 'sent', 'archived', 'all']);
+const MARKS = {
+    done: { archived: true, read: true },
+    archive: { archived: true },
+    unarchive: { archived: false },
+    star: { starred: true },
+    unstar: { starred: false },
+    mute: { muted: true },
+    unmute: { muted: false },
+    unread: { read: false },
+};
+async function call(action, input, values) {
+    const res = await rpcOnce(action, input, getTimeout(values));
+    const f = failure(res);
+    if (f)
+        die(f, res?.hint);
+    if (values.json) {
+        console.log(JSON.stringify(res, null, 2));
+        process.exit(0);
+    }
+    return res;
+}
+async function printList(box, values) {
+    const res = await call('inbox-list', {
+        box, ...(values.search ? { q: String(values.search) } : {}), ...(values.as ? { as: String(values.as) } : {}),
+        ...(values.limit ? { limit: Number(values.limit) } : {}),
+    }, values);
+    const threads = res.threads ?? [];
+    const counts = res.counts ?? {};
+    console.log('');
+    console.log(`  ${c.bold(box === 'inbox' ? 'Inbox' : box[0].toUpperCase() + box.slice(1))}${res.as ? c.dim(` — reading ${res.as}, read-only`) : ''} ${c.dim(`(${counts.unread ?? 0} unread in ${counts.threads ?? 0} thread${counts.threads === 1 ? '' : 's'})`)}`);
+    if (!threads.length) {
+        console.log(c.dim(box === 'inbox' ? '  Nothing waiting. Start one: beehaven inbox send <to> "…"  ·  who you can message: beehaven inbox who' : '  Nothing here.'));
+        return;
+    }
+    for (const t of threads) {
+        const people = (t.participants ?? []).map(who).join(', ') || c.dim('only you');
+        const flag = t.unread ? c.cyan(`● ${t.unread}`) : ' ';
+        console.log(`  ${flag} ${c.bold(t.subject)} ${c.dim('—')} ${people} ${c.dim(`· ${ago(t.updatedAt)}${t.starred ? ' · ★' : ''}${t.muted ? ' · muted' : ''}`)}`);
+        console.log(`      ${String(t.preview ?? '').slice(0, 110)} ${c.dim(t.id)}`);
+    }
+    if (res.nextBefore)
+        console.log(c.dim('  … more — narrow with --search or raise --limit'));
+    console.log(c.dim('  Open: beehaven inbox read <id>   Reply: beehaven inbox reply <id> "…"   Done: beehaven inbox done <id>'));
+}
+export async function cmdInbox(sub, rest, values) {
+    const s = sub || 'inbox';
+    if (BOXES.has(s))
+        return printList(s, values);
+    if (s === 'read' || s === 'open') {
+        const threadId = rest[0];
+        if (!threadId)
+            die('usage: beehaven inbox read <threadId>', 'ids are in: beehaven inbox');
+        const res = await call('inbox-thread', { threadId, ...(values.as ? { as: String(values.as) } : {}) }, values);
+        console.log('');
+        console.log(`  ${c.bold(res.thread?.subject ?? '')} ${c.dim(`— ${(res.participants ?? []).filter((p) => !p.you).map((p) => p.name + (p.left ? ' (left)' : '')).join(', ')}`)}`);
+        for (const m of res.messages ?? []) {
+            if (m.system) {
+                console.log(c.dim(`    · ${m.body} (${ago(m.createdAt)})`));
+                continue;
+            }
+            const from = m.mine ? c.green('you') : who(m.from ?? { name: m.fromName });
+            console.log('');
+            console.log(`  ${from} ${c.dim(`· ${ago(m.createdAt)}${m.edited ? ' · edited' : ''} · ${m.id}`)}`);
+            if (m.deleted) {
+                console.log(c.dim('    (deleted)'));
+                continue;
+            }
+            for (const line of String(m.body).split('\n'))
+                console.log(`    ${line}`);
+            for (const r of m.refs ?? [])
+                console.log(c.dim(`    ↳ ${r.key || r.kind}: ${r.title}${r.href ? `  ${r.href}` : ''}`));
+            const reactions = Object.entries(m.reactions ?? {}).map(([e, p]) => `${e} ${p.length}`).join('  ');
+            if (reactions)
+                console.log(`    ${reactions}`);
+        }
+        console.log('');
+        if (!res.as && !res.me?.left)
+            console.log(c.dim(`  Reply: beehaven inbox reply ${threadId} "…"   Done: beehaven inbox done ${threadId}`));
+        return;
+    }
+    if (s === 'send') {
+        const to = rest[0] || String(values.to ?? '');
+        const body = rest.slice(1).join(' ').trim() || String(values.body ?? '').trim();
+        if (!to || !body)
+            die('usage: beehaven inbox send <to> "message" [--subject "…"] [--refs CLR-42,…]', 'who you can message: beehaven inbox who');
+        const res = await call('inbox-send', {
+            to: list(to), body,
+            ...(values.subject ? { subject: String(values.subject) } : {}),
+            ...(values.refs ? { refs: list(String(values.refs)) } : {}),
+        }, values);
+        const names = (res.to ?? []).map(who).join(', ');
+        console.log(`  Sent to ${names} ${c.dim(res.threadId)}`);
+        if ((res.to ?? []).some((t) => t.kind === 'agent'))
+            console.log(c.dim('  Agents read it in their next brief — nothing runs until then.'));
+        return;
+    }
+    if (s === 'reply') {
+        const threadId = rest[0];
+        const body = rest.slice(1).join(' ').trim() || String(values.body ?? '').trim();
+        if (!threadId || !body)
+            die('usage: beehaven inbox reply <threadId> "message"');
+        await call('inbox-reply', { threadId, body, ...(values.refs ? { refs: list(String(values.refs)) } : {}) }, values);
+        console.log(`  Replied ${c.dim(threadId)}`);
+        return;
+    }
+    if (MARKS[s]) {
+        const ids = rest.flatMap(list);
+        if (!ids.length)
+            die(`usage: beehaven inbox ${s} <threadId>[,<threadId>…]`);
+        const res = await call('inbox-mark', { threadIds: ids, ...MARKS[s] }, values);
+        console.log(`  ${s === 'done' ? 'Done' : s[0].toUpperCase() + s.slice(1)} — ${res.count} thread${res.count === 1 ? '' : 's'} ${c.dim(`(${res.counts?.unread ?? 0} unread left)`)}`);
+        return;
+    }
+    if (s === 'add') {
+        const [threadId, to] = rest;
+        if (!threadId || !to)
+            die('usage: beehaven inbox add <threadId> <to>');
+        const res = await call('inbox-add', { threadId, to: list(to) }, values);
+        console.log(res.added?.length ? `  Added ${(res.added ?? []).map(who).join(', ')}` : c.dim('  Everyone named is already in it.'));
+        return;
+    }
+    if (s === 'leave') {
+        if (!rest[0])
+            die('usage: beehaven inbox leave <threadId>');
+        await call('inbox-leave', { threadId: rest[0] }, values);
+        console.log('  Left the conversation.');
+        return;
+    }
+    if (s === 'who') {
+        const res = await call('inbox-recipients', { ...(rest[0] ? { q: rest.join(' ') } : {}) }, values);
+        console.log('');
+        for (const r of res.recipients ?? []) {
+            console.log(`  ${c.cyan(r.handle.padEnd(18))} ${r.kind === 'agent' ? c.violet(r.name) : r.name}${r.kind === 'agent' ? c.dim(' · agent') : ''}${r.yours ? c.dim(' · yours') : ''}`);
+        }
+        if (!(res.recipients ?? []).length)
+            console.log(c.dim('  Nobody else is in this workspace yet.'));
+        return;
+    }
+    if (s === 'count') {
+        const res = await call('inbox-unread', {}, values);
+        console.log(`  ${res.unread} unread in ${res.threads} thread${res.threads === 1 ? '' : 's'}`);
+        for (const a of res.agents ?? [])
+            if (a.unread)
+                console.log(c.dim(`    ${a.name}: ${a.unread} unread`));
+        return;
+    }
+    die(`unknown inbox command "${s}"`, 'beehaven inbox [inbox|unread|starred|sent|archived|all] · read · send · reply · done · add · leave · who · count');
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "beehaven",
-  "version": "0.8.18",
-  "description": "Beehaven CLI \u2014 command your Clearly workspace, agents, and canvas from the terminal",
+  "version": "0.8.20",
+  "description": "Beehaven CLI — command your Clearly workspace, agents, and canvas from the terminal",
   "private": false,
   "type": "module",
   "bin": {

package/skills/clearly-agent/SKILL.md

@@ -83,7 +83,8 @@ The brief carries: prior **sessions**, **lastActions**, **focus**, **assignedToM
 **memories**, **recents** (what you touched, with titles and whether you made or opened it), and
 **drafts** (your own unfiled work) — plus the workspace half: what changed since you were last
 here **and by whom**, inbox, notifications, messages, other agents — and, first, what is **addressed to
-you**: `voicemail` and `mentions` (both stay until acked).
+you**: `inboxThreads` (messages people and agents sent you — they stay until you read them),
+`voicemail` and `mentions` (both stay until acked). `waiting.inboxUnread` is the count.
 
 ⚠ **`changed[].by` is the useful field, not the timestamp.** "Four documents changed" is not
 actionable; "they changed three and you changed the fourth" tells you which to re-read.
@@ -120,6 +121,39 @@ item queued. Every comment/description write returns `mentions`, `agentsQueued`
 surface cannot carry is **refused**, never dropped. Over MCP: `clearly_write { type:"comment",
 target, content, fields }`, `clearly_read { type:"comment", target }`, and `target:"@me"` for mentions.
 
+## Inbox — people and agents message you, and you message them
+
+Everyone in a workspace can message everyone: people ↔ people, people ↔ agents, agents ↔ agents.
+**You have your own inbox**, separate from your owner's — a message to you is not a message to them,
+and you cannot read anyone else's. Unread threads are in your brief as `workspace.inboxThreads`
+(oldest first; the CLI prints them under **Addressed to you**). Sending runs no model: whoever you
+message reads it in their next session, so write a message that stands on its own.
+
+```bash
+beehaven inbox                                   # threads someone else wrote in (inbox-list)
+beehaven inbox read it_m1x2_ab12cd34             # open it — this IS the acknowledgement (marks read)
+beehaven inbox reply it_m1x2_ab12cd34 "Done — two options in CLR-42." --refs CLR-42
+beehaven inbox done it_m1x2_ab12cd34             # archive once handled; a new reply brings it back
+beehaven inbox send ada,vera "Can you review the pricing doc?" --subject "Pricing review" --refs "Pricing"
+beehaven inbox who                               # every handle you can put in <to> — people and agents
+```
+
+Over MCP, `type: "message"` on the same tools: `clearly_read { type: "message", target: "@inbox" }`
+lists your threads (`box`, `query`), `target: "@people"` lists who you can message, and a thread id
+opens it (marks read). `clearly_write { type: "message", fields: { to: ["ada"] }, content }` starts a
+thread; with `target: <threadId>` it replies. `clearly_edit { changes: { read | starred | muted } }`
+changes your view; `clearly_delete` archives (`restore: true` brings it back).
+
+⚠ **Answer in the thread, not in a new one.** `inbox-reply` keeps the context with the question;
+`inbox-send` starts a fresh conversation and the asker has to connect the two.
+⚠ **Link, don't paste.** `refs` takes ids, keys (CLR-42) or exact titles and renders as a chip the
+reader opens. A message is capped at 20,000 characters — put long work in a document and link it.
+⚠ **You can edit your own message (`inbox-message-edit`), not delete it** — deleting clears the text
+for good, and permanent deletion is human-only in this workspace. `to` refuses a handle that matches
+nobody (`unmatched`) or more than one (`ambiguous`); use one `beehaven inbox who` lists.
+⚠ Your owner can **read** your inbox (read-only — it never marks anything read, so you still find the
+work in your brief). Write as if they will.
+
 ## ⚠⚠ Your work is YOURS — this changes what everyone sees
 
 Anything you create is stamped `created_by: agent:<your-id>` and born **private**:

package/skills/clearly-canvas/SKILL.md

@@ -142,7 +142,10 @@ matches the chosen direction, then adapt and inspect it. It is not an art direct
 a quality guarantee. Custom compositions should use native nodes and your own builder.
 
 Read [authoring.md](authoring.md) before building. It covers the exact coordinate,
-batch, text, asset and MCP contracts. Consult `canvas-catalog` for action schemas
+batch, text, image-upload and MCP contracts. For a local image, use
+`beehaven canvas add-image <file> --composition <id>` when the installed CLI supports
+it; read authoring.md for the current CLI fallback and the MCP URL-only path.
+Consult `canvas-catalog` for action schemas
 instead of loading an exhaustive reference.
 
 ## 4. Build a representative surface, then complete the artifact

package/skills/clearly-canvas/authoring.md

@@ -105,11 +105,62 @@ Use `canvas.place {kind,id,x,y,w,h,name,parentId?}` to put a workspace object (d
 deck, sheet, board, ticket, project, site or file) on the canvas as a live card. With
 `parentId`, `x/y` are relative to that frame, like `canvas.create-node`. See
 [project-plans.md](project-plans.md).
-Use `canvas.list-sources`/`canvas.place-source` for library assets. A native image
-node accepts `src`. Upload local media using `canvas-upload-image` (discover its current
-schema), then place its returned URL. Inspect the actual asset before using it. Prefer
-provided, reusable or purpose-made imagery to random URL placeholders. Label temporary
-assets in the handoff and replace them when final assets are part of the request.
+Use `canvas.list-sources`/`canvas.place-source` for an existing library asset. A native
+image node accepts an absolute `http(s)` `src`, never a local path or raw base64.
+Inspect the actual asset before placing it. Prefer provided, reusable or purpose-made
+imagery to random URL placeholders. Label temporary assets in the handoff.
+
+### Local images from the CLI
+
+`beehaven canvas add-image` uploads a PNG, JPEG, WebP, GIF or AVIF from disk through
+`get-upload-url` → binary PUT → `file-uploaded {composition:true}`, then appends an
+image node with `canvas-add-image`. The binary does not cross the relay WebSocket.
+This matters above about 900 KB: sending multi-megabyte base64 through
+`canvas-upload-image` can exceed the relay message limit. The asset is filed under
+the composition rather than added as a loose item in Recents.
+
+```sh
+beehaven canvas add-image ./photo.png --composition <id> \
+  --x 120 --y 160 --width 600 --height 400 --json
+```
+
+The command reports `nodeId` and `imageFileId`. Coordinates are world coordinates;
+omit both `--x`/`--y` to use canvas auto-placement, and omit both size flags to use
+the image's native dimensions. Check `beehaven canvas` help on the installed CLI:
+older versions do not have this command. On one of those, use the documented
+`get-upload-url` → binary PUT → `file-uploaded` sequence, then
+`canvas-act {action:"canvas.create-node",args:{type:"image",src:<absolute URL>,x,y,w,h}}`.
+The upload intent's `publicUrl` may be `/f/...`; prefix the active relay's HTTPS
+origin before storing it as `src`. `beehaven teleport --composition` stores a file
+but does not place an image node. `canvas-upload-image` remains useful for small
+inline images, followed by `canvas.create-node` or `canvas-add-image` using its `url`.
+The CLI command caps a file at 100 MiB, and the workspace plan may impose a smaller
+single-file or remaining-storage limit. Uploading and rendering are separate checks:
+the headless renderer has image-count and memory budgets, so inspect a review PNG
+after adding large images instead of treating upload success as visual proof.
+In the editor, paste/drop also uses presigned binary PUT. Saved canvas images are
+registered under the composition without adding loose cards to Recents. If a large
+upload fails, retry the upload; it must not be inlined into the scene JSON.
+
+For a composed artboard, nest the image with `canvas.update-nodes` using the returned
+`nodeId` and `patch:{parentId:<frame id>,name:"descriptive layer name"}`. The
+membership-only patch keeps its world position. Review the artboard after this:
+reviewing a frame excludes overlapping top-level images that are not its children.
+Image nodes are square-edged by default. If you set `radius` for a rounded crop,
+omit a square backing tile behind it or give that tile the same radius; otherwise
+the backing shows through as dark wedges at the corners.
+
+### Images from MCP
+
+The seven artifact MCP tools do not upload local binary files or dispatch `canvas-act`.
+For an image already reachable by an absolute URL, read the composition with
+`clearly_read {type:"composition",target:<id>}`; append an image node
+`{id,type:"image",src,x,y,w,h,fit:"contain",parentId?}` to the returned complete node
+array; then call `clearly_write {type:"composition",target:<id>,content:<JSON array>,
+expectedRev:<canvasNodesRev>}`. Preserve every existing node. A stale revision is a
+merge prompt, never a reason to drop `expectedRev`. `clearly_edit` can change an
+existing image's `src`, `fit` or geometry, but cannot create a node. For a local file,
+use the CLI upload path first; an MCP-only client needs a URL it can already access.
 
 Current headless rendering can resolve images, including workspace media. A blank image
 can indicate fetch, decoding or budget failure; check its source and inspect a live view.

package/skills/index.json

@@ -17,7 +17,7 @@
       "project-plans.md",
       "review.mjs"
     ],
-    "sha": "fe0256c5ce9dea7c"
+    "sha": "21faa5f8d14beefe"
   },
   {
     "name": "agent-home",
@@ -74,6 +74,6 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "89e5a04a420defe3"
+    "sha": "94c30f43b217f3e9"
   }
 ]