@clearlysh/beehaven 0.8.22 → 0.8.23

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 = '49efa8cde4ed-dirty';
+export const BUILD_SHA = '8585349e92e9-dirty';
 /** ISO-8601 minute precision, UTC. Rewritten in `dist/` by `scripts/stamp-build-channel.mjs`. */
-export const BUILD_TIME = '2026-09-30T19:01Z';
+export const BUILD_TIME = '2026-10-02T00:47Z';
 /**
  * The build identity as one short string, for `--version`.
  *

package/dist/cli.js

@@ -309,7 +309,8 @@ ${DEV_ONLY_HELP ? `  PROJECT — build your own Durable Object backend  (HIVE_DE
     app setup <name>                       Re-run a hive's setup script
     install <pkg>                          Shorthand for "app install <pkg>"
     skills install                         Teach every agent about Clearly —
-                                           writes the shipped SKILL.md files
+                                           writes the shipped SKILL.md files + the
+                                           AGENTS.md / GEMINI.md / CLAUDE.md block
     skills <list|sync|remove>              Manage skills paired with installed hives
 
     Deep dive:  beehaven help hives        Mental model + install/connect/call loop
@@ -437,7 +438,9 @@ ${DEV_ONLY_HELP ? `
   ACCOUNT
   ─────────────────────────────────────────────────────────────────────
 
-    login                                  Sign in (browser) — primary flow
+    login                                  Sign in (browser) — primary flow; also teaches
+                                           your agents (skills + AGENTS.md block;
+                                           --no-agent-setup to skip)
     login --email <e> --password <p>       Self-hosted email/password (set BEEHAVEN_API_URL)
     logout                                 Clear local credentials + keychain
     signup                                 Open sign-up page in browser
@@ -1492,6 +1495,7 @@ async function run() {
             // Paired Claude Code skill install policy (see commands/skills.ts)
             'with-skills': { type: 'boolean', default: false },
             'no-skills': { type: 'boolean', default: false },
+            'no-agent-setup': { type: 'boolean', default: false },
             // ── mobile-install metadata for `beehaven teleport <build>.ipa --composition <id>`
             //    (see commands/workspace.ts — wantMobileInstall branch).
             //    Future: parse Info.plist / AndroidManifest.xml automatically
@@ -3303,6 +3307,31 @@ async function run() {
              */
             console.log(`  ${color.green('✓')} Connected — your new sign-in is live`);
             console.log(`    Background service ${wasRunning ? 'restarted' : 'started'} (PID ${pid})`);
+            /**
+             * ⚠⚠ TEACH THE AGENTS AS PART OF SIGNING IN (PPO-190). "Install the CLI, log in, and your
+             * agents handle the rest" needs the agents to KNOW about the CLI — the skills plus the
+             * instruction block in ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md and a pointer in
+             * ~/.claude/CLAUDE.md. That used to be a separate `beehaven skills install` the installer's
+             * closing text asked for, and a step people skip is a step that did not happen.
+             *
+             * ⚠ Idempotent and non-fatal: unchanged files are not rewritten, symlinked files are left
+             * alone, and a failure here never fails the sign-in. Opt out with `--no-agent-setup` or
+             * BEEHAVEN_NO_AGENT_SETUP=1; undo with `beehaven skills uninstall`.
+             */
+            if (!values['no-agent-setup'] && process.env.BEEHAVEN_NO_AGENT_SETUP !== '1') {
+                try {
+                    const { installAgentSkills } = await import('./commands/agent-skills.js');
+                    const { installAgentInstructions } = await import('./commands/agent-instructions.js');
+                    const sk = installAgentSkills();
+                    const ins = installAgentInstructions();
+                    const changed = [...sk.steps, ...ins.steps].filter((x) => /=(written|updated)$/.test(x)).length;
+                    console.log(`  ${color.green('✓')} Your agents know about Clearly${changed ? '' : color.dim(' (already set up)')}`);
+                    console.log(color.dim('    Skills + instructions for Claude Code, Codex, Gemini and pi · undo: beehaven skills uninstall'));
+                }
+                catch (err) {
+                    console.log(color.dim(`    Agent setup skipped: ${err?.message ?? err} — run: beehaven skills install`));
+                }
+            }
             console.log('');
             break;
         }
@@ -3897,7 +3926,13 @@ complete -F _beehaven_completions beehaven`);
              */
             if (sub === 'install' || sub === 'uninstall') {
                 const { installAgentSkills, removeAgentSkills, AGENT_SKILL_DIRS } = await import('./commands/agent-skills.js');
+                const { installAgentInstructions, removeAgentInstructions } = await import('./commands/agent-instructions.js');
                 const r = sub === 'install' ? installAgentSkills() : removeAgentSkills();
+                // ⚠ The instruction block travels with the skills (PPO-190) — a skill is only OFFERED;
+                // the block is what makes an agent reach for `beehaven` at all.
+                const ins = sub === 'install' ? installAgentInstructions() : removeAgentInstructions();
+                r.steps.push(...ins.steps);
+                r.warnings.push(...ins.warnings);
                 const wrote = r.steps.filter((x) => /=(written|updated)$/.test(x)).length;
                 const current = r.steps.filter((x) => x.endsWith('=current')).length;
                 const removed = r.steps.filter((x) => x.endsWith('=removed')).length;

package/dist/commands/agent-instructions.js

@@ -0,0 +1,182 @@
+/**
+ * agent-instructions — the "use the beehaven CLI" block in each agent's GLOBAL instruction file.
+ *
+ * ⚠⚠ THE MISSING HALF OF "install the CLI, log in, and your agents handle the rest" (PPO-190).
+ * `skills install` put SKILL.md files on disk, but a skill is only OFFERED to a model when its
+ * description matches. The instruction block is what makes an agent reach for `beehaven` at all
+ * when the user says "put this on my board". The Mac app has written it on every launch
+ * (`apps/electron/electron/agent-skills-installer.ts`); the CLI never did, so a CLI-only user's
+ * Codex and Gemini had skills they never used.
+ *
+ * ⚠⚠ BYTE-IDENTICAL TO THE MAC APP'S BLOCK, MARKER LINE INCLUDED. Both writers splice between the
+ * same BLOCK_START / BLOCK_END. If their text differed by one character, a machine with both would
+ * rewrite the file on every app launch and every CLI install, each undoing the other. One text
+ * means both converge and either uninstaller removes it. `agentInstructionParity.test.mjs` in the
+ * root repo pins the two copies together.
+ *
+ * ⚠ CLAUDE GETS THE SHORT POINTER — `~/.claude/CLAUDE.md` is prepended to every Claude Code
+ * session in every repository, so it carries a pointer to the skills, not a manual. Same rule as
+ * the Mac app; see its note on `AGENT_INSTRUCTION_FILES`.
+ *
+ * ⚠ ONLY OUR BLOCK IS EVER TOUCHED. Text around it is preserved byte for byte; a file with no
+ * block gets one appended; removal deletes the block and nothing else.
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+const MANAGED_MARKER = 'managed-by: clearly-mac-app';
+export const BLOCK_START = '<!-- clearly:beehaven-cli:start -->';
+export const BLOCK_END = '<!-- clearly:beehaven-cli:end -->';
+/** Resolved at call time so tests can point HOME at a temp dir. */
+export function agentInstructionFiles(home = os.homedir()) {
+    return [
+        { agent: 'codex', file: path.join(home, '.codex', 'AGENTS.md') },
+        { agent: 'gemini', file: path.join(home, '.gemini', 'GEMINI.md') },
+        { agent: 'claude', file: path.join(home, '.claude', 'CLAUDE.md') },
+    ];
+}
+/** The managed block appended to AGENTS.md / GEMINI.md. Keep identical to the Mac app's. */
+export function instructionBlock() {
+    return [
+        BLOCK_START,
+        `<!-- ${MANAGED_MARKER}. Edits inside this block are overwritten on app launch; edit outside it. -->`,
+        '',
+        '## Clearly — drive it with the `beehaven` CLI',
+        '',
+        'Clearly (clearly.sh) is a workspace — documents, projects, boards, tickets and a design',
+        'canvas. Reach it from the shell with the `beehaven` CLI, NOT an HTTP API you construct.',
+        '',
+        '⚠ SIGN IN FIRST. Every call is attributed to an agent identity, and without one the CLI',
+        'refuses. `login` MINTS the name if it does not exist yet, and binds this terminal:',
+        '',
+        '```sh',
+        'beehaven agent login <your-name>   # required — mints + binds, once per session',
+        'beehaven connect home              # target the personal workspace',
+        'beehaven actions                   # list every action available there',
+        'beehaven call <action> \'{...}\'',
+        '```',
+        '',
+        'Read the full skills before driving it — they carry the exact verbs and node shapes:',
+        '',
+        '- `~/.<agent>/skills/clearly-agent/SKILL.md` — **read this first**: identity, sessions, your brief',
+        '- `~/.<agent>/skills/beehaven-cli/SKILL.md` — connect / call / sql / logs, the daemon',
+        '- `~/.<agent>/skills/clearly-workspace/SKILL.md` — audit what a workspace holds and who made it',
+        '- `~/.<agent>/skills/clearly-canvas/SKILL.md` — build + perceive a canvas, comm blocks, code diffs',
+        '- `~/.<agent>/skills/design-craft/SKILL.md` — **load before any visual work**: grid, type, colour, the studio pass',
+        '- `~/.<agent>/skills/layout-systems/SKILL.md` — grids and systems across many artboards',
+        '- `~/.<agent>/skills/pair-on-canvas/SKILL.md` — drive a coding task from a spec on the canvas',
+        '- `~/.<agent>/skills/codebase-map/SKILL.md` — draw a repo’s architecture on the canvas',
+        '',
+        'If a command reports the daemon is unreachable, `beehaven login` re-auths and',
+        '`beehaven start --headless` starts a daemon when the Mac app is not running.',
+        BLOCK_END,
+    ].join('\n');
+}
+/** The short form, for `~/.claude/CLAUDE.md`. Keep identical to the Mac app's `claudeBlock()`. */
+export function claudeBlock() {
+    return [
+        BLOCK_START,
+        `<!-- ${MANAGED_MARKER}. Edits inside this block are overwritten on app launch; edit outside it. -->`,
+        '',
+        '**Clearly workspace** — drive it from the shell with the `beehaven` CLI (documents, projects,',
+        'boards, tickets, canvas). Sign in once per session first: `beehaven agent login <name>` —',
+        'it mints the identity if new. Full detail is in the skills, `clearly-agent` first.',
+        BLOCK_END,
+    ].join('\n');
+}
+/** Insert or replace our block, leaving everything around it untouched. Pure. */
+export function upsertBlock(existing, block) {
+    const start = existing.indexOf(BLOCK_START);
+    const end = existing.indexOf(BLOCK_END);
+    if (start !== -1 && end !== -1 && end > start) {
+        return existing.slice(0, start) + block + existing.slice(end + BLOCK_END.length);
+    }
+    return existing.trim() ? `${existing.trimEnd()}\n\n${block}\n` : `${block}\n`;
+}
+/** Remove our block (and the blank line it was appended after). Pure. */
+export function stripBlock(existing) {
+    const start = existing.indexOf(BLOCK_START);
+    const end = existing.indexOf(BLOCK_END);
+    if (start === -1 || end === -1 || end < start)
+        return existing;
+    const before = existing.slice(0, start).replace(/\n{1,2}$/, '\n');
+    const after = existing.slice(end + BLOCK_END.length).replace(/^\n/, '');
+    const out = (before + after);
+    return out.trim() ? out : '';
+}
+/**
+ * Write the block into every agent's global instruction file. Idempotent: an unchanged file is
+ * reported `=current` and not rewritten.
+ *
+ * ⚠ A SYMLINKED INSTRUCTION FILE IS LEFT ALONE. People keep dotfiles in a repo and link them in;
+ * writing through the link would silently edit their checkout. Same rule as the skills installer.
+ */
+export function installAgentInstructions(home = os.homedir()) {
+    const steps = [];
+    const warnings = [];
+    for (const { agent, file } of agentInstructionFiles(home)) {
+        try {
+            /**
+             * ⚠ ONLY FOR AGENTS THAT ARE INSTALLED. Creating `~/.gemini/GEMINI.md` for someone without
+             * Gemini invents an agent: the skills installer keys on that same directory existing, so
+             * the NEXT run would install skills for it too. Same rule as `installAgentSkills`.
+             */
+            if (!fs.existsSync(path.dirname(file))) {
+                steps.push(`${agent}/instructions=agent-absent`);
+                continue;
+            }
+            if (isSymlink(file)) {
+                steps.push(`${agent}/instructions=symlink-skipped`);
+                continue;
+            }
+            let existing = '';
+            try {
+                existing = fs.readFileSync(file, 'utf8');
+            }
+            catch { /* first run */ }
+            const next = upsertBlock(existing, agent === 'claude' ? claudeBlock() : instructionBlock());
+            if (next === existing) {
+                steps.push(`${agent}/instructions=current`);
+                continue;
+            }
+            fs.writeFileSync(file, next, { mode: 0o644 });
+            steps.push(`${agent}/instructions=${existing ? 'updated' : 'written'}`);
+        }
+        catch (e) {
+            warnings.push(`${agent}/instructions: ${e?.message ?? String(e)}`);
+        }
+    }
+    return { steps, warnings };
+}
+/** Remove only our block. A file that becomes empty is deleted only if we created all of it. */
+export function removeAgentInstructions(home = os.homedir()) {
+    const steps = [];
+    const warnings = [];
+    for (const { agent, file } of agentInstructionFiles(home)) {
+        try {
+            if (!fs.existsSync(file) || isSymlink(file))
+                continue;
+            const existing = fs.readFileSync(file, 'utf8');
+            const next = stripBlock(existing);
+            if (next === existing)
+                continue;
+            if (next)
+                fs.writeFileSync(file, next);
+            else
+                fs.unlinkSync(file);
+            steps.push(`${agent}/instructions=removed`);
+        }
+        catch (e) {
+            warnings.push(`${agent}/instructions: ${e?.message ?? String(e)}`);
+        }
+    }
+    return { steps, warnings };
+}
+function isSymlink(file) {
+    try {
+        return fs.lstatSync(file).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/commands/agent.js

@@ -845,7 +845,11 @@ async function agentLogin(args, values) {
         console.error(`  ${yellow('⚠')} Signed in, but this workspace refused ${cyan(name)}: ${outcome.reason}`);
         if (/revoked|not active|unknown agent|not admitted/i.test(`${outcome.scope} ${outcome.reason}`)) {
             console.error(dim(`    The agent is archived or not admitted here. Restore it in Settings → Agent access,`));
-            console.error(dim(`    or log in as an active agent (beehaven call agent-list '{}' shows the roster).`));
+            // ⚠ The workspace names the live identity in its refusal (PPO-190). The old advice —
+            // `beehaven call agent-list` — ran AS this refused identity and was refused in turn.
+            if (!/Log in as one:/.test(outcome.reason)) {
+                console.error(dim(`    or log in as an active agent: beehaven agent login <name> (the Settings → Agent access page lists them).`));
+            }
         }
         console.error(dim(`    Calls from this session run as ${name} and will be refused — they will NOT fall back to another agent.`));
         process.exitCode = 1;

package/dist/commands/workspace.js

@@ -860,6 +860,22 @@ export async function cmdCall(action, rawInput, values) {
             input = { ...input, action: canonical, name: canonical };
         }
     }
+    // ⚠ `type` IS THE WIRE'S ACTION NAME (PPO-190): a top-level `type` would be overwritten by the
+    // daemon's `{ ...input, type: action }` and lost with `ok: true`. Move it to the verb's own field
+    // or refuse with the right spelling — never drop it in silence. See reserved-type.ts.
+    {
+        const { reconcileReservedType } = await import('../reserved-type.js');
+        const r = reconcileReservedType(action, input);
+        if (r.kind === 'refused') {
+            console.error(`  ${r.error}`);
+            process.exit(1);
+        }
+        if (r.kind === 'moved') {
+            input = r.input;
+            if (!values.json)
+                console.error(`  · ${r.note}`);
+        }
+    }
     // Confirm spend BEFORE resolving a building or touching the daemon — a cancelled call must
     // cost nothing and behave identically whether the input came from argv, a file, or stdin.
     // It runs after the parse because the gate is input-aware: `engine:'handroll'` and any call

package/dist/reserved-type.js

@@ -0,0 +1,60 @@
+/**
+ * reserved-type — `type` is the WIRE'S action name, so a top-level `type` in a call's input is lost.
+ *
+ * ⚠⚠ SILENT DATA LOSS (PPO-190). The daemon sends `{ ...input, type: action }`. An agent that calls
+ * `ticket-create '{"title":"…","type":"bug"}'` gets `ok: true` and a ticket that is NOT a bug: its
+ * `type` was overwritten by `"ticket-create"` before the workspace ever saw it. AGENTS.md has
+ * carried "use `issueType`, not `type`" as a warning, which is a rule every new agent has to be
+ * told and every one of them breaks once.
+ *
+ * The verbs already accept a non-colliding spelling (`issueType`, `linkType`, `proposalType`,
+ * `kind`). This moves `type` onto that spelling when the verb has one, and refuses with the right
+ * spelling when it does not — either way, nothing is dropped in silence.
+ */
+/** Verb → the field the workspace reads instead of `type`. */
+export const TYPE_ALIASES = {
+    // Each entry is a verb whose handler reads this field (verified against apps/cloudflare/src).
+    'ticket-create': 'issueType',
+    'ticket-update': 'issueType',
+    'ticket-link-create': 'linkType',
+    'proposal-create': 'proposalType',
+    'composition-create': 'kind',
+    'record-thought': 'kind',
+    'thought-record': 'kind',
+};
+/**
+ * Reconcile a top-level `type` with the wire's use of the name. Pure.
+ *
+ * ⚠ A `type` EQUAL TO THE ACTION is left alone — that is a caller spelling the action twice, which
+ * the wire already agrees with. Nested `type`s (canvas nodes, `updates.type`) never collide and are
+ * never inspected.
+ */
+export function reconcileReservedType(action, input) {
+    if (!input || typeof input !== 'object' || !Object.prototype.hasOwnProperty.call(input, 'type'))
+        return { kind: 'none' };
+    const value = input.type;
+    if (value === undefined || value === action)
+        return { kind: 'none' };
+    const field = TYPE_ALIASES[action];
+    if (field) {
+        const { type: _dropped, ...rest } = input;
+        if (rest[field] !== undefined && rest[field] !== value) {
+            return {
+                kind: 'refused',
+                error: `both "type" (${JSON.stringify(value)}) and "${field}" (${JSON.stringify(rest[field])}) were given — `
+                    + `"type" is the action name on the wire and would be dropped; pass only "${field}".`,
+            };
+        }
+        return {
+            kind: 'moved',
+            field,
+            input: { ...rest, [field]: value },
+            note: `"type" is reserved for the action name on the wire — sent as "${field}": ${JSON.stringify(value)}`,
+        };
+    }
+    return {
+        kind: 'refused',
+        error: `"type" is reserved for the action name on the wire, so ${action} would never see ${JSON.stringify(value)}. `
+            + `Use the verb's own field (see: beehaven describe ${action}).`,
+    };
+}

package/package.json

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

package/skills/clearly-agent/SKILL.md

@@ -211,7 +211,8 @@ ask the owner.
   `beehaven call agent-list '{}'` shows the live roster; log in as one of those.
 - ⚠ **`workspace-sql` takes `query`**, not `sql`. The wrong key is silently dropped and you get the
   SCHEMA back — `ok: true`, a confident list of tables, not your answer.
-- ⚠ **`document-create` takes `markdown` or `html`**, not `content`. An unknown key is stripped, the
-  document is created empty, and it is **invisible to `document-search` forever**.
-- ⚠ **`ticket-create` takes `issueType`, not `type`** (the wire uses `type` as the action
-  discriminator) and **`body`, not `description`**. Both fail silently.
+- **`document-create` takes `markdown` or `html`.** `content`, `body` and `text` are accepted as
+  markdown aliases, but prefer `markdown`.
+- **`ticket-create` / `ticket-update` take `issueType` and `body`.** The wire uses `type` as the action
+  name, so the CLI moves a top-level `type` to `issueType` for you and refuses it on verbs with no
+  such field. `description` is accepted as `body`.

package/skills/index.json

@@ -74,6 +74,6 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "94c30f43b217f3e9"
+    "sha": "ad938cb0070fcab0"
   }
 ]