beehaven 0.8.22 → 0.8.27

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
@@ -1299,7 +1302,25 @@ async function run() {
         await shorthandCmd(rawVerb, process.argv.slice(3), {});
         return;
     }
+    /**
+     * ⚠ `--x -3000` IS A NEGATIVE COORDINATE, NOT A FLAG. node's parseArgs reads any value starting
+     * with a dash as a missing argument and dies with "Option '--x' argument is ambiguous" — which is
+     * how `beehaven canvas add-image … --x -3000` failed (CDS-25). Join a negative NUMBER onto the
+     * coordinate/size flag before it; nothing else is rewritten.
+     */
+    const NUMERIC_FLAGS = new Set(['--x', '--y', '--width', '--height', '--w', '--h', '--dx', '--dy']);
+    const argv = [];
+    for (let i = 2; i < process.argv.length; i++) {
+        const a = process.argv[i], b = process.argv[i + 1];
+        if (NUMERIC_FLAGS.has(a) && typeof b === 'string' && /^-\d+(\.\d+)?$/.test(b)) {
+            argv.push(`${a}=${b}`);
+            i++;
+            continue;
+        }
+        argv.push(a);
+    }
     const { values, positionals } = parseArgs({
+        args: argv,
         allowPositionals: true,
         options: {
             project: { type: 'string' },
@@ -1492,6 +1513,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
@@ -2918,7 +2940,7 @@ async function run() {
                 console.error(`      beehaven start --headless`);
                 console.error(``);
                 console.error(`  The Mac tray is only required for the LOCAL hive — avatar`);
-                console.error(`  building, voice and mood. Install: ${color.dim('https://clearly.sh/docs/beehaven')}`);
+                console.error(`  building, voice and mood. Install: ${color.dim('https://www.clearly.sh/docs/beehaven')}`);
                 process.exit(1);
             }
             console.log(`  Launching ${opened}…`);
@@ -2945,11 +2967,24 @@ async function run() {
             // omitted BEEHAVEN_HEADLESS=1, so the "restarted" daemon hit the
             // parent-death watchdog and exited ~3s later — restart reported a PID and
             // left you with nothing running. See spawnStandaloneDaemon's comment.
-            const { spawnStandaloneDaemon } = await import('./commands/daemon-cmd.js');
+            const { spawnStandaloneDaemon, waitForServingDaemon } = await import('./commands/daemon-cmd.js');
             const { resolveRelayUrlForDaemon } = await import('./daemon.js');
             const relayUrl = resolveRelayUrlForDaemon();
             const pid = spawnStandaloneDaemon(values);
-            console.log(`  Daemon restarted (PID ${pid}).`);
+            // ⚠ Report the daemon that is ACTUALLY serving — see waitForServingDaemon.
+            const served = await waitForServingDaemon(pid);
+            if (served.ready && served.spawnedAlive) {
+                console.log(`  Daemon restarted (PID ${pid}). Ready — socket answering.`);
+            }
+            else if (served.ready) {
+                console.log(`  Another supervisor (the Clearly app) restarted the daemon first — PID ${served.livePids.join(', ')} is serving. Ready.`);
+            }
+            else {
+                console.error(served.livePids.length
+                    ? `  Daemon process is up (PID ${served.livePids.join(', ')}) but its socket is not answering yet. 'beehaven status' shows state.`
+                    : `  The daemon did not stay up (spawned PID ${pid} exited). Run 'beehaven start --headless', or reopen the Clearly app.`);
+                process.exitCode = 1;
+            }
             console.log(`  Relay: ${color.dim(relayUrl)}`);
             break;
         }
@@ -2970,272 +3005,20 @@ async function run() {
                 await login(emailArg, password);
                 break;
             }
-            // ─── Localhost loopback OAuth (firebase-tools / wrangler /
-            //     gh / vercel / fly / supabase pattern) ─────────────────
-            //
-            // The CLI starts an ephemeral HTTP server on a free port,
-            // opens the user's browser to clearly.sh/cli/auth?state=…
-            // &redirect=http://127.0.0.1:<port>/callback. After the user
-            // signs in + clicks Approve, the web page POSTs the user's
-            // Firebase tokens directly to the loopback. The CLI captures,
-            // validates state, stores in keychain + config, and shuts
-            // down the server. Single round-trip, instant feedback.
-            //
-            // The clearly.sh web origin and the worker are NOT in the
-            // token-exchange path — tokens go from the browser's authed
-            // session straight to localhost. State (anti-CSRF) prevents
-            // a malicious site from sending tokens to a CLI that didn't
-            // request them.
-            const http = await import('http');
-            const netMod = await import('net');
-            const childProcess = await import('child_process');
-            const cryptoMod = await import('crypto');
-            const state = cryptoMod.randomBytes(16).toString('hex');
-            // Resolve the web origin from the active env so staging
-            // users sign in against staging's Pages alias (or local
-            // dev), prod users against prod.
-            const ENV_AUTH_ORIGINS = {
-                prod: 'https://clearly.sh',
-                staging: 'https://localhost:3000',
-                dev: 'https://localhost:3000',
-            };
-            let activeEnv = 'prod';
-            try {
-                const cfgPath = join(homedir(), '.beehaven', 'config.json');
-                if (existsSync(cfgPath)) {
-                    const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'));
-                    // Derive env from the canonical endpoint, not the cfg.envName
-                    // alias (a fresh login / Mac-app install may write only `endpoint`).
-                    const { envName } = resolveRelaySelection(cfg);
-                    if (ENV_AUTH_ORIGINS[envName])
-                        activeEnv = envName;
-                }
-            }
-            catch { }
-            const authOrigin = process.env.BEEHAVEN_AUTH_ORIGIN ?? ENV_AUTH_ORIGINS[activeEnv];
-            // Pre-warning: non-prod env requires a local dev server.
-            if (activeEnv !== 'prod') {
-                const probe = await new Promise((resolve) => {
-                    const t = setTimeout(() => resolve(false), 800);
-                    const sock = netMod.createConnection(3000, '127.0.0.1');
-                    sock.once('connect', () => {
-                        clearTimeout(t);
-                        sock.destroy();
-                        resolve(true);
-                    });
-                    sock.once('error', () => {
-                        clearTimeout(t);
-                        resolve(false);
-                    });
-                }).catch(() => false);
-                if (!probe) {
-                    console.log('');
-                    console.log(`  ${color.yellow('!')} localhost:3000 isn't responding.`);
-                    console.log(`    Run ${color.cyan('npm run dev')} (with --experimental-https) in the clearly monorepo first.`);
-                    console.log('');
-                }
-            }
-            // Spin up the loopback server. OS picks a free port (port 0).
-            const captured = await new Promise((resolve, reject) => {
-                // Tiny success page the browser sees AFTER it navigates to
-                // the loopback. Self-contained — no external assets,
-                // works offline. Auto-close after 1.5s on supported
-                // browsers (Chrome/Firefox allow window.close on
-                // self-opened or scripted-navigated tabs).
-                const successHtml = `<!doctype html>
-<html><head><meta charset="utf-8"><title>beehaven CLI signed in</title>
-<style>
-  body { font: 15px -apple-system, sans-serif; background: #fafaf9; color: #292524;
-         display: grid; place-items: center; min-height: 100vh; margin: 0; }
-  .card { background: white; padding: 32px 40px; border-radius: 14px;
-          box-shadow: 0 1px 3px rgba(0,0,0,.08), 0 8px 24px rgba(0,0,0,.06);
-          max-width: 420px; }
-  h1 { font-size: 20px; margin: 0 0 8px; letter-spacing: -0.01em; }
-  p { color: #57534e; margin: 8px 0; }
-  .ok { color: #16a34a; }
-  .eyebrow { font-size: 10px; letter-spacing: .22em; color: #a8a29e;
-             text-transform: uppercase; margin-bottom: 8px; }
-</style></head>
-<body><div class="card">
-  <p class="eyebrow">01 — beehaven CLI</p>
-  <h1><span class="ok">✓</span> Signed in</h1>
-  <p>The CLI now has your credentials. You can close this tab and
-     return to your terminal.</p>
-</div>
-<script>setTimeout(() => { try { window.close(); } catch (e) {} }, 1500);</script>
-</body></html>`;
-                const errorHtml = (msg) => `<!doctype html>
-<html><head><meta charset="utf-8"><title>beehaven CLI error</title>
-<style>body{font:15px -apple-system,sans-serif;padding:40px;color:#292524}
-.err{color:#dc2626}</style></head>
-<body><h1 class="err">✗ Sign-in error</h1><p>${msg}</p>
-<p><small>Run <code>beehaven login</code> again from your terminal.</small></p>
-</body></html>`;
-                const server = http.createServer((req, res) => {
-                    if (req.method !== 'GET' || !(req.url ?? '').startsWith('/callback')) {
-                        res.writeHead(404, { 'Content-Type': 'text/plain' });
-                        res.end('Not Found');
-                        return;
-                    }
-                    // Parse query params from the GET URL. Tokens arrive
-                    // as ?state=…&idToken=…&refreshToken=…&userId=…
-                    // because the web side window.location.assign'd here
-                    // — fetch() from HTTPS to HTTP loopback is mixed-
-                    // content blocked by every browser since 2020, so
-                    // top-level navigation is the standard pattern (gh,
-                    // wrangler, vercel, firebase-tools all use this).
-                    const url = new URL(req.url, `http://127.0.0.1`);
-                    const presentedState = url.searchParams.get('state') ?? '';
-                    const idToken = url.searchParams.get('idToken') ?? '';
-                    const refreshToken = url.searchParams.get('refreshToken') ?? '';
-                    const userId = url.searchParams.get('userId') ?? '';
-                    const email = url.searchParams.get('email') ?? undefined;
-                    const displayName = url.searchParams.get('displayName') ?? undefined;
-                    if (presentedState !== state) {
-                        res.writeHead(403, { 'Content-Type': 'text/html; charset=utf-8' });
-                        res.end(errorHtml("State mismatch — the CLI didn't initiate this sign-in."));
-                        return;
-                    }
-                    if (!idToken || !refreshToken || !userId) {
-                        res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
-                        res.end(errorHtml('Missing token fields. Try <code>beehaven login</code> again.'));
-                        return;
-                    }
-                    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-                    res.end(successHtml);
-                    // Tear down the server after the response flushes so
-                    // the browser has a chance to render the success
-                    // page before the connection drops.
-                    setTimeout(() => {
-                        try {
-                            server.close();
-                        }
-                        catch { }
-                    }, 500);
-                    resolve({ idToken, refreshToken, userId, email, displayName });
-                });
-                server.on('error', reject);
-                // 5-minute upper bound so a forgotten browser tab doesn't
-                // hang the terminal forever.
-                const timeout = setTimeout(() => {
-                    try {
-                        server.close();
-                    }
-                    catch { }
-                    reject(new Error('Sign-in timed out after 5 minutes.'));
-                }, 5 * 60 * 1000);
-                server.on('close', () => clearTimeout(timeout));
-                server.listen(0, '127.0.0.1', () => {
-                    const addr = server.address();
-                    const port = addr && typeof addr === 'object' ? addr.port : 0;
-                    const callbackUrl = `http://127.0.0.1:${port}/callback`;
-                    const url = withUtm(`${authOrigin}/cli/auth?state=${state}&redirect=${encodeURIComponent(callbackUrl)}`);
-                    console.log('');
-                    console.log(`  ${color.cyan('→')} Opening browser to ${authOrigin}/cli/auth …`);
-                    console.log(`  ${color.dim("If it doesn't open: ")}${color.dim(url)}`);
-                    console.log(`  ${color.dim('Listening on ' + callbackUrl + ' (5-min timeout).')}`);
-                    console.log('');
-                    try {
-                        // Best-effort browser open. macOS `open` dispatches
-                        // to the user's default browser; xdg-open on Linux;
-                        // start on Windows.
-                        const opener = process.platform === 'darwin'
-                            ? 'open'
-                            : process.platform === 'win32'
-                                ? 'start'
-                                : 'xdg-open';
-                        const proc = childProcess.spawn(opener, [url], {
-                            stdio: 'ignore',
-                            detached: true,
-                        });
-                        proc.unref();
-                        proc.on('error', (err) => {
-                            // Surface — silent failure was the bug. If
-                            // `open` isn't on PATH (e.g. unusual env),
-                            // tell the user so they can paste manually.
-                            console.log(`  ${color.yellow('!')} Couldn't auto-open browser: ${err.message}`);
-                            console.log(`    Paste this URL into your browser instead:`);
-                            console.log(`    ${color.cyan(url)}`);
-                        });
-                    }
-                    catch (err) {
-                        console.log(`  ${color.yellow('!')} Couldn't spawn opener: ${err?.message ?? err}`);
-                        console.log(`    Paste this URL into your browser instead:`);
-                        console.log(`    ${color.cyan(url)}`);
-                    }
-                });
-            });
-            // Persist the captured tokens. Mirror the Mac app's
-            // installDaemon flow exactly: keychain stores the **idToken**
-            // under service='beehaven', account='daemon-token' (because
-            // that's what relay.ts:Relay.loadConfig reads on every
-            // daemon launch — line 116). The refresh token stays in
-            // config.json where relay.ts:refreshIdToken reads it from.
-            //
-            // Earlier this code was storing the refreshToken in the
-            // keychain — wrong slot. The daemon then tried to authenticate
-            // its WebSocket with the refresh token (treating it as an ID
-            // token), got 401, kicked off a refresh that succeeded but
-            // wrote the new idToken to config.json (not keychain), so on
-            // the next daemon restart the loop repeated. Storing idToken
-            // in keychain breaks the loop.
-            const { keychain } = await import('./keychain.js');
-            try {
-                keychain.setToken(captured.idToken);
-            }
-            catch { }
+            // ─── Localhost loopback OAuth — ONE implementation (AWO-224) ───
+            // `browser-login.ts` owns the loopback server, the /cli/auth URL, the
+            // state check and where the tokens are stored. The daemon's interactive
+            // fallback (setup-relay.ts) calls the same function; it used to carry its
+            // own copy aimed at /auth/beehaven, a route the web app no longer serves.
+            // What follows the sign-in — restarting the daemon, teaching the agents —
+            // stays here, because the daemon fallback must not restart itself.
+            let captured;
             try {
-                // Reuse saveCredentials() for the email/identity record.
-                // Tokens themselves go to keychain (above). Plain-file
-                // copy lives in config.json so the daemon can identify
-                // the user without unlocking the keychain on every read.
-                const { existsSync, mkdirSync, writeFileSync } = await import('fs');
-                const cfgDir = join(homedir(), '.beehaven');
-                if (!existsSync(cfgDir))
-                    mkdirSync(cfgDir, { recursive: true, mode: 0o700 });
-                const cfgPath = join(cfgDir, 'config.json');
-                let existing = {};
-                if (existsSync(cfgPath)) {
-                    try {
-                        existing = JSON.parse(readFileSync(cfgPath, 'utf8'));
-                    }
-                    catch { }
-                }
-                /**
-                 * ⚠⚠ SIGNING IN WRITES A DIAL TARGET. It used to write only credentials and lean on
-                 * `...existing` to carry `endpoint` forward — which PRESERVES one and can never CREATE one.
-                 * So on a config that had none (a fresh install before the Mac app's `install()` ran, or
-                 * any config after `logout`, which deletes `endpoint` by name) login produced valid tokens
-                 * with nothing to connect to, and the daemon reported "Token refresh failed" while the tray
-                 * read "agent offline". A login that leaves the user unable to connect has not signed
-                 * anyone in.
-                 *
-                 * ⚠ RESOLVED FROM THE CONFIG, NEVER A HARDCODED CONSTANT — `resolveRelaySelection` keys off
-                 * whichever key is present and defaults to prod only when neither is. Pinning a literal
-                 * here is the bug `setup-relay.ts` had: it sent every staging login to the prod relay.
-                 *
-                 * ⚠ BOTH KEYS, KEPT IN SYNC, exactly as `beehaven env` writes them — `endpoint` is what the
-                 * relay client dials and `relayUrl` is the alias other surfaces read. Writing one and
-                 * leaving the other stale is how they disagree about which environment you are signed into.
-                 */
-                const { url: dialUrl } = resolveRelaySelection(existing);
-                const next = {
-                    ...existing,
-                    onboarded: true,
-                    tier: existing.tier ?? 'connected',
-                    userId: captured.userId,
-                    email: captured.email ?? null,
-                    displayName: captured.displayName ?? null,
-                    tokenStorage: 'keychain',
-                    refreshToken: captured.refreshToken,
-                    token: captured.idToken,
-                    endpoint: dialUrl,
-                    relayUrl: dialUrl,
-                };
-                writeFileSync(cfgPath, JSON.stringify(next, null, 2), { mode: 0o600 });
+                const { browserLogin } = await import('./browser-login.js');
+                captured = await browserLogin();
             }
             catch (err) {
-                console.error(`  ${color.red('✗')} Failed to write config: ${err?.message ?? err}`);
+                console.error(`  ${color.red('✗')} ${err?.message ?? err}`);
                 process.exit(1);
             }
             console.log('');
@@ -3303,6 +3086,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;
         }
@@ -3358,7 +3166,7 @@ async function run() {
             const signupUrl = withUtm(
             // Was /avatar/install, which now 301s to the homepage — a signup CTA that lands on
             // the marketing page loses the person it was meant to convert. /signup is live.
-            process.env.BEEHAVEN_SIGNUP_URL ?? 'https://clearly.sh/signup');
+            process.env.BEEHAVEN_SIGNUP_URL ?? 'https://www.clearly.sh/signup');
             console.log('');
             console.log(`  Sign up at ${color.cyan(signupUrl)}.`);
             console.log('  Then run "beehaven login" to wire the CLI to your account.');
@@ -3897,7 +3705,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;
+    }
+}