@clearlysh/beehaven 0.8.17 → 0.8.19

package/README.md

@@ -23,7 +23,7 @@ npx --yes beehaven@latest guide
 
 `guide` works before sign-in. It explains when Clearly is useful, gives the
 human a signup link, and shows the authenticated first artifact. `npx` uses an
-ephemeral npm install; it does not create a Clearly account or publish a file.
+ephemeral npm install; it does not create a Clearly account or upload anything.
 Public builds send one anonymous, content-free `cli:guide` usage event unless
 `BEEHAVEN_NO_TELEMETRY` or the local `telemetry-off` file disables telemetry.
 The package also provides the `beehaven` binary for a global npm install:
@@ -36,6 +36,23 @@ beehaven guide
 The identical release is also listed under the Clearly npm organization as
 `@clearlysh/beehaven`.
 
+### Hand work to someone without an account
+
+When an agent's work is ready before the person has signed up, `handoff` needs
+no login and prints one private link:
+
+```bash
+npx --yes beehaven@latest handoff plan.md
+npx --yes beehaven@latest handoff plan.md --tasks todo.md --csv budget.csv --wait
+```
+
+The person previews it, signs in or creates a free account, and saves it. A
+document alone becomes a private draft; with `--tasks` (a Markdown checklist or a
+JSON array) or `--csv` files it becomes a private project with a ticket per task
+and a sheet per CSV. The link is a credential — the first person to save it owns
+the work — so send it only to the person you are working with. Unsaved handoffs
+expire after 7 days. `--wait` returns when they save it.
+
 The self-contained installer remains the recommended persistent install. It does
 not require npm to resolve dependencies on the user's machine:
 

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 = 'd66d1de0cca7';
+export const BUILD_SHA = '42cf394385d8';
 /** ISO-8601 minute precision, UTC. Rewritten in `dist/` by `scripts/stamp-build-channel.mjs`. */
-export const BUILD_TIME = '2026-09-27T06:15Z';
+export const BUILD_TIME = '2026-09-27T18:08Z';
 /**
  * The build identity as one short string, for `--version`.
  *

package/dist/cli.js

@@ -944,6 +944,12 @@ const AGENT_LOGIN_EXEMPT = new Set([
      * as `skills`: setup must not require the thing setup provides.
      */
     'update',
+    /**
+     * ⚠ `handoff` EXISTS FOR CALLERS WITH NO ACCOUNT. It posts one Markdown file to the relay's
+     * anonymous door and prints a claim link; it never opens a workspace. Gating it on an agent login
+     * would refuse the one person it is for — the agent whose user has not signed up yet (SGS-73).
+     */
+    'handoff',
 ]);
 /**
  * ⚠ ALIAS → CANONICAL VERB, for the activity log's `source` column only.
@@ -1359,6 +1365,10 @@ async function run() {
             quote: { type: 'string' }, // document passage
             cell: { type: 'string' }, // sheet cell, A1 or "Tab!B4"
             sheet: { type: 'string' }, // sheet tab, when --cell names none
+            // `handoff`: a task list file, CSV files (repeatable), and waiting for the person to save it.
+            tasks: { type: 'string' },
+            csv: { type: 'string', multiple: true },
+            wait: { type: 'boolean', default: false },
             column: { type: 'string' }, // board column key or label
             pin: { type: 'string' }, // canvas pin to reply to
             // (--x / --y for a new pin and --kind are declared below, shared with other verbs)
@@ -1588,6 +1598,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 |
@@ -1736,11 +1748,17 @@ async function run() {
   A useful first artifact:
     beehaven doc add ./flow.md            # after sign-in and agent login
 
+  Work ready before they have an account? Hand it over with one private link:
+    beehaven handoff ./plan.md --tasks ./todo.md --wait
+  They preview it and save it to a free workspace. First to save owns it; give
+  the link only to the person you are working with.
+
   If the agent has no shell, connect Clearly MCP through browser OAuth:
     https://relay.clearly.sh/mcp
 
   Do not claim a file was published or a workspace was created until the CLI
-  returns a successful result. Anonymous publish-and-claim is not available.
+  returns a successful result. A handoff link is not in their workspace until
+  they save it.
 
   Docs: https://www.clearly.sh/docs/quickstart
 `);
@@ -1864,6 +1882,7 @@ async function run() {
         'composition', 'comp',
         'devices',
         'sheet', 'sheets',
+        'handoff',
         'slides', 'deck',
         'brand', 'brands',
         'component', 'components',
@@ -3311,6 +3330,18 @@ async function run() {
             console.log('  (or quit and relaunch the Hive Mac app if it owns the daemon).');
             break;
         }
+        case 'handoff': {
+            const { cmdHandoff } = await import('./commands/handoff.js');
+            process.exitCode = await cmdHandoff(positionals[1], {
+                title: values.title,
+                json: !!values.json,
+                tasks: values.tasks,
+                csv: values.csv ?? [],
+                wait: !!values.wait,
+                version: getVersion(),
+            });
+            break;
+        }
         case 'signup': {
             const email = values.email ?? positionals[1];
             const password = values.password;

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/handoff.js

@@ -0,0 +1,227 @@
+/**
+ * `beehaven handoff [file.md] [--tasks tasks.md|json] [--csv data.csv]… [--wait]` — give a person
+ * an agent's work when they have no Clearly account yet (SGS-73).
+ *
+ * Uploads a Markdown document and, optionally, the work around it — a task list and CSV sheets —
+ * to the relay's anonymous door, and prints ONE private claim link. The person previews it, signs
+ * in or signs up, and saves it: a document alone becomes a private draft; with tasks or sheets it
+ * becomes a private project holding the document, a ticket per task, and the sheets. No agent
+ * login, no workspace, no daemon: this is the step BEFORE any of those exist.
+ *
+ * ⚠ NOT `beehaven publish`. That verb ships app-marketplace packages and is unrelated.
+ *
+ * ⚠ THE LINK IS A CREDENTIAL. Whoever opens it first and saves it owns the work. The output says
+ * so, and says where it may go (to the person you are working with) and where it may not.
+ *
+ * ⚠ THE SERVER DECIDES AVAILABILITY. A relay without the feature answers 404, and this command
+ * says "not available here" with the signed-in alternative rather than guessing.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { basename, extname, join } from 'path';
+import { homedir } from 'os';
+import { resolveRelaySelection } from '../relay-presets.js';
+/** The relay's HTTPS origin for the env this CLI is configured for (prod when unconfigured). */
+export function relayHttpOrigin() {
+    const override = process.env.BEEHAVEN_RELAY_HTTP_URL;
+    if (override)
+        return override.replace(/\/+$/, '');
+    let cfg = {};
+    try {
+        const p = join(process.env.BEEHAVEN_PREFIX || join(homedir(), '.beehaven'), 'config.json');
+        if (existsSync(p))
+            cfg = JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch { /* unconfigured ⇒ prod */ }
+    return resolveRelaySelection(cfg).url
+        .replace(/^wss:\/\//, 'https://').replace(/^ws:\/\//, 'http://').replace(/\/+$/, '');
+}
+const PRIORITY = { low: 0, medium: 1, med: 1, high: 2, urgent: 3 };
+/**
+ * A task list is JSON (`[{ title, body?, priority? }]`) or Markdown the way an agent already writes
+ * one: each list item (`- [ ] …`, `- …`, `1. …`) is a task, and indented lines under it are its
+ * body. A trailing `(high)` / `[urgent]` sets the priority. Headings and prose between items are
+ * ignored, so a plan's own checklist section can be handed over as-is.
+ */
+export function parseTasks(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith('[')) {
+        const arr = JSON.parse(trimmed);
+        if (!Array.isArray(arr))
+            throw new Error('JSON task list must be an array');
+        return arr.map((t) => (typeof t === 'string' ? { title: t } : t));
+    }
+    const tasks = [];
+    let current = null;
+    const body = [];
+    const flush = () => {
+        if (current) {
+            const b = body.join('\n').trim();
+            if (b)
+                current.body = b;
+            tasks.push(current);
+        }
+        current = null;
+        body.length = 0;
+    };
+    for (const line of text.split(/\r?\n/)) {
+        const item = line.match(/^\s{0,3}(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?(.+?)\s*$/);
+        if (item) {
+            flush();
+            let title = item[1];
+            let priority;
+            const pm = title.match(/\s*[([](low|medium|med|high|urgent)[)\]]\s*$/i);
+            if (pm) {
+                priority = PRIORITY[pm[1].toLowerCase()];
+                title = title.slice(0, pm.index).trim();
+            }
+            current = { title, ...(priority !== undefined ? { priority } : {}) };
+        }
+        else if (current && /^\s{2,}\S/.test(line)) {
+            body.push(line.trim());
+        }
+        else if (current && line.trim() && !/^\s/.test(line)) {
+            flush();
+        }
+    }
+    flush();
+    return tasks;
+}
+async function readInput(file) {
+    if (file === '-') {
+        const chunks = [];
+        for await (const c of process.stdin)
+            chunks.push(c);
+        return Buffer.concat(chunks).toString('utf8');
+    }
+    return readFileSync(file, 'utf8');
+}
+function usage() {
+    console.error('  Usage: beehaven handoff [file.md|-] [--tasks tasks.md|tasks.json] [--csv data.csv]… [--title "…"] [--wait] [--json]');
+    return 2;
+}
+async function post(url, body, version) {
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'User-Agent': `beehaven/${version}` },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(20_000),
+        });
+        return { status: res.status, body: await res.json().catch(() => null) };
+    }
+    catch (e) {
+        return { status: 0, body: { ok: false, code: 'network', error: `Could not reach ${url}: ${e?.message ?? e}` } };
+    }
+}
+/**
+ * ⚠ WAITING READS THE SAME DOOR THE PAGE DOES, WITH NO IDENTITY. The agent holds the token, so it
+ * may ask; a saved draft answers 409 to anyone but its owner, which is exactly "someone saved it" —
+ * and says nothing about who.
+ */
+async function waitForClaim(relay, token, opts) {
+    const deadline = Date.now() + (opts.waitMs ?? 15 * 60_000);
+    const every = opts.pollMs ?? 5_000;
+    while (Date.now() < deadline) {
+        const r = await post(`${relay}/publish/anon/inspect`, { token }, opts.version);
+        if (r.body?.code === 'already_claimed')
+            return 'saved';
+        if (r.status === 410 || r.status === 404)
+            return 'expired';
+        await new Promise((res) => setTimeout(res, every));
+    }
+    return 'timeout';
+}
+export async function cmdHandoff(file, opts) {
+    const csvFiles = opts.csv ?? [];
+    if (!file && !opts.tasks && !csvFiles.length)
+        return usage();
+    for (const f of [file, opts.tasks, ...csvFiles]) {
+        if (f && f !== '-' && !existsSync(f)) {
+            console.error(`  No such file: ${f}`);
+            return 2;
+        }
+    }
+    let markdown = '';
+    let tasks = [];
+    const sheets = [];
+    try {
+        if (file)
+            markdown = await readInput(file);
+        if (opts.tasks)
+            tasks = parseTasks(readFileSync(opts.tasks, 'utf8'));
+        for (const f of csvFiles)
+            sheets.push({ title: basename(f, extname(f)), csv: readFileSync(f, 'utf8') });
+    }
+    catch (e) {
+        console.error(`  Could not read the handoff: ${e?.message ?? e}`);
+        return 2;
+    }
+    if (opts.tasks && !tasks.length) {
+        console.error(`  No tasks found in ${opts.tasks}. Use list items (- [ ] Title) or a JSON array.`);
+        return 2;
+    }
+    const relay = relayHttpOrigin();
+    const { status, body } = await post(`${relay}/publish/anon`, {
+        ...(markdown ? { markdown } : {}),
+        ...(opts.title ? { title: opts.title } : {}),
+        ...(tasks.length ? { tasks } : {}),
+        ...(sheets.length ? { sheets } : {}),
+        source: 'cli',
+    }, opts.version);
+    if (opts.json && !opts.wait) {
+        console.log(JSON.stringify(body ?? { ok: false, status }, null, 2));
+        return body?.ok ? 0 : 1;
+    }
+    if (!body?.ok) {
+        if (status === 404) {
+            console.error('\n  Anonymous handoff is not available on this server yet.');
+            console.error('  Ask the person to create a free workspace, then run:');
+            console.error('    beehaven login && beehaven agent login <name> && beehaven doc add ' + (file && file !== '-' ? file : '<file>') + '\n');
+            return 1;
+        }
+        console.error(`\n  Handoff failed: ${body?.error ?? `relay answered ${status}`}\n`);
+        return 1;
+    }
+    const days = Math.max(1, Math.round((Number(body.expiresAt) - Date.now()) / 86_400_000));
+    const parts = [
+        markdown.trim() ? 'a document' : '',
+        body.tasks ? `${body.tasks} task${body.tasks === 1 ? '' : 's'}` : '',
+        body.sheets ? `${body.sheets} sheet${body.sheets === 1 ? '' : 's'}` : '',
+    ].filter(Boolean).join(', ');
+    if (!opts.json) {
+        console.log(`
+  Ready to hand off: ${body.title} (${parts})
+
+    ${body.claimUrl}
+
+  Give this link to the person you are working with. They can preview it and
+  save it to their own Clearly workspace, creating a free account if needed.
+  The first person to save it owns it. It expires unsaved in ${days} days.
+  Do not post it publicly — in an issue, a commit, or a shared channel.
+`);
+    }
+    if (!opts.wait)
+        return 0;
+    const token = String(body.claimUrl).split('#')[1] ?? '';
+    if (!opts.json)
+        console.log('  Waiting for them to save it (up to 15 minutes)…');
+    const outcome = await waitForClaim(relay, token, opts);
+    if (opts.json) {
+        console.log(JSON.stringify({ ...body, outcome }, null, 2));
+        return outcome === 'saved' ? 0 : 1;
+    }
+    if (outcome === 'saved') {
+        console.log(`
+  Saved. It is in their workspace now, private to them.
+  To keep working on it with them, ask them to connect you:
+    npx --yes beehaven@latest login
+    beehaven start --headless && beehaven connect home
+    beehaven agent login <your-name> --label "Continue: ${body.title}" --client cli
+`);
+        return 0;
+    }
+    console.log(outcome === 'expired'
+        ? '\n  The link expired before it was saved. Run handoff again for a new one.\n'
+        : '\n  Not saved yet. The link still works; they can save it any time before it expires.\n');
+    return outcome === 'expired' ? 1 : 0;
+}

package/dist/commands/help.js

@@ -374,6 +374,48 @@ const PAGES = {
         ],
         related: ['logout', 'whoami', 'status', 'doctor'],
     },
+    guide: {
+        synopsis: 'beehaven guide',
+        description: `What Clearly is and the first steps for a shell-capable agent: a read-only demo,
+    the signup link, login, the headless daemon, and agent login. Needs no account.`,
+        related: ['signup', 'login', 'agent'],
+    },
+    signup: {
+        synopsis: 'beehaven signup',
+        description: `Open the Clearly signup page in the browser. After the account exists, run
+    \`beehaven login\` to connect the CLI to it.`,
+        related: ['login', 'guide'],
+    },
+    handoff: {
+        synopsis: 'beehaven handoff [file.md|-] [--tasks tasks.md|json] [--csv data.csv]… [--title "…"] [--wait] [--json]',
+        description: `Give a person your work when they have no Clearly account yet. Needs no login.
+    Prints one private link. They preview it, sign in or create a free account, and save it.
+
+    A document alone becomes a private draft. Add \`--tasks\` (a Markdown checklist or a JSON
+    array; indented lines become a task's description, a trailing "(high)" sets priority) and/or
+    \`--csv\` files, and it becomes a private project: the document, a ticket per task on
+    its board, and a sheet per CSV. Up to 100 tasks, 5 sheets, 256 KB in total.
+
+    The link is a credential: the first person to save it owns it. Send it to the person you
+    are working with — never to an issue, a commit or a public channel. Unsaved handoffs expire
+    after 7 days. \`--wait\` blocks (up to 15 minutes) until they save it, then prints how to
+    connect you to their workspace so you can keep working.
+
+    Already signed in? Use \`beehaven doc add\` instead — it writes straight to the workspace.
+    Not \`beehaven publish\`, which ships app packages.`,
+        flags: [
+            { name: '--tasks', desc: 'Task list: Markdown list items or a JSON array of { title, body?, priority? }' },
+            { name: '--csv', desc: 'A CSV file to include as a sheet (repeatable)' },
+            { name: '--title', desc: 'Title (default: the document\'s first heading)' },
+            { name: '--wait', desc: 'Wait until the person saves it' },
+            { name: '--json', desc: 'Print the relay response as JSON' },
+        ],
+        examples: [
+            { cmd: 'beehaven handoff plan.md', note: 'one private draft' },
+            { cmd: 'beehaven handoff plan.md --tasks todo.md --csv budget.csv --wait', note: 'a project with tickets and a sheet' },
+        ],
+        related: ['login', 'doc'],
+    },
     logout: {
         synopsis: 'beehaven logout',
         description: 'Clear stored credentials (keychain + ~/.beehaven/config.json).',
@@ -493,13 +535,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
@@ -521,6 +565,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/verb-surface.js

@@ -59,6 +59,7 @@ export const VERB_SURFACE = {
     login: { cls: 'STRUCTURAL', why: 'browser OAuth + keychain' },
     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' },
     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.17",
+  "version": "0.8.19",
   "description": "Beehaven CLI — command your Clearly workspace, agents, and canvas from the terminal",
   "private": false,
   "type": "module",

package/skills/beehaven-cli/SKILL.md

@@ -50,6 +50,7 @@ Only ONE daemon runs at a time, on `/tmp/beehaven-ipc.sock`. Either the **Hive M
 
 - **Start:** open the Mac app (the tray auto-spawns `daemon-entry.js`), OR `beehaven start --headless` for a detached, CLI-owned daemon with no Mac app (`--headless` disables the tray-death watchdog so it persists — without it a headless daemon suicides ~3s after spawn). Plain `beehaven start` (no flag) just opens the tray app. **Stop/restart:** `beehaven stop` / `beehaven restart`. **Sign in/out:** `beehaven login` / `logout` / `whoami`.
 - **`beehaven status`** — Account/Target/Tier (proves a token is on disk, *not* relay liveness). The live proof is "any command works."
+- **No account yet?** `beehaven handoff plan.md [--tasks todo.md] [--csv data.csv] [--wait]` needs no login, daemon or workspace: it prints one private link the person uses to preview and save the work (a document → private draft; with tasks/CSVs → private project). The link is a credential — give it only to the person you are working with.
 - **"Cannot connect to daemon"** ⇒ nothing owns the socket → open the Mac app, or `beehaven start --headless`. **"Not connected to cloud"** ⇒ daemon up but its relay WS isn't live: if the token EXPIRED, `beehaven login` re-auths (a plain `restart` will NOT refresh it — reach for this first); if the relay just dropped (e.g. after sleep), `beehaven restart` (CLI-owned) or relaunch the Mac app.
 - **State files:** `~/.beehaven/status.json` (refreshed ~2s: `relayConnected`, `reconnectAttempts`, `relayEndpoint`, `pid`) · `~/.beehaven/logs/daemon.log` (structured) · `~/.beehaven/target.json` · `~/.beehaven/config.json`.
 

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

@@ -4,7 +4,7 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "03e91dcc483f189d"
+    "sha": "2d33d2ecfb166fa6"
   },
   {
     "name": "clearly-canvas",
@@ -17,7 +17,7 @@
       "project-plans.md",
       "review.mjs"
     ],
-    "sha": "fe0256c5ce9dea7c"
+    "sha": "21faa5f8d14beefe"
   },
   {
     "name": "agent-home",