@clearlysh/beehaven 0.8.16

package/dist/clearly.js

@@ -0,0 +1,616 @@
+#!/usr/bin/env node
+/**
+ * `clearly` — THE PRODUCT CLI. Two verbs that do the work, and six that get out of their way.
+ *
+ * ⚠⚠ THIS IS NOT `beehaven`, AND THE SPLIT IS THE POINT. `beehaven` is the internal tool: ~50
+ * verbs, `admin`, `sql`, `d1`, a dev-mode escape hatch and a hidden "build your own backend"
+ * surface. Handing that to an engineering team to write documentation would ship them a console
+ * for a platform they are not buying. The precedent is already in this repo — `mwah` is the
+ * consumer CLI beside `beehaven` the developer one.
+ *
+ * ⚠ IT IS A FRONT-END, NOT A FORK. Every call goes through the SAME daemon over the SAME IPC
+ * socket, so login, the relay, DO routing and env selection are inherited rather than
+ * reimplemented. A second auth stack is how the two drift and how one of them ends up wrong.
+ *
+ *   THE WORK        note · ask
+ *   THE ARCHIVE     pull
+ *   THE ACCOUNT     login · logout · settings · status · uninstall
+ *
+ * ⚠ KEEP THIS LIST AND `help()` IN STEP. It said "three verbs, and deliberately only three" while
+ * the file had eight — two contradictory inventories in one document, which is the exact failure
+ * `thought-prompt.ts` shipped and had to be guarded against ("you have exactly ONE tool" while
+ * granting nineteen). A reader believes whichever they saw last.
+ *
+ * ⚠ GIT IS THE ONLY SOURCE TODAY, and that is a deliberate first step rather than a limitation to
+ * paper over. It is local, it needs no OAuth, and "reads your commits" is most of what the
+ * product promises. GitHub / Linear / Slack ingestion is a separate project; nothing here
+ * pretends otherwise, and `status` says so out loud.
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { rpcOnce } from './ipc-client.js';
+import { readCliConfig, patchCliConfig } from './feature-flags.js';
+const argv = process.argv.slice(2);
+const cmd = argv[0] ?? 'help';
+const flag = (n) => {
+    const i = argv.indexOf(n);
+    return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : null;
+};
+const has = (n) => argv.includes(n);
+const c = {
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+    honey: (s) => `\x1b[33m${s}\x1b[0m`,
+    mint: (s) => `\x1b[32m${s}\x1b[0m`,
+    red: (s) => `\x1b[31m${s}\x1b[0m`,
+};
+/**
+ * ⚠ THE AGENT TURN IS THE SLOW PART AND THE CLI RELAY CAPS AT 180s. `RESPOND_TIMEOUT_MS` on the
+ * server is the same 180s, so a turn that outlives this was going to be killed anyway — matching
+ * them means a timeout here always means the same thing it means there.
+ */
+const TURN_MS = 180_000;
+/**
+ * ⚠ STDERR IS CAPTURED, NOT INHERITED. A failing probe is normal here — `HEAD~30` does not exist in
+ * a repo with two commits — and with inherited stderr git printed
+ * `fatal: ambiguous argument 'HEAD~30..HEAD'` straight into the user's terminal above a run that
+ * then succeeded. A tool that prints `fatal:` and works anyway teaches people to ignore the word.
+ */
+function git(args, cwd) {
+    try {
+        return execFileSync('git', args, {
+            cwd, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return '';
+    }
+}
+function repoRoot() {
+    const root = git(['rev-parse', '--show-toplevel'], process.cwd());
+    return root || null;
+}
+const statePath = (root) => join(root, '.clearly', 'state.json');
+function readState(root) {
+    try {
+        return JSON.parse(readFileSync(statePath(root), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeState(root, s) {
+    try {
+        mkdirSync(dirname(statePath(root)), { recursive: true });
+        writeFileSync(statePath(root), `${JSON.stringify(s, null, 2)}\n`);
+    }
+    catch { /* a lost bookmark costs a duplicate note, never the note itself */ }
+}
+/** True when the sha is a real commit in THIS repo — see the rebase note above. */
+const commitExists = (root, sha) => !!sha && git(['cat-file', '-e', `${sha}^{commit}`], root) === '' && git(['rev-parse', '--verify', `${sha}^{commit}`], root) !== '';
+/**
+ * What happened, as text the agent can reason about.
+ *
+ * ⚠⚠ THE DIFF IS SUMMARISED, NOT PASTED. A day of work is routinely tens of thousands of lines;
+ * sending it whole would blow the turn's context, cost real money per note, and bury the one
+ * thing being asked for. Subjects, bodies and a per-file stat are what a person reads to
+ * reconstruct a decision — the reasoning lives in commit messages and review comments, not in the
+ * hunks.
+ *
+ * ⚠ AND IT IS CAPPED, VISIBLY. Truncation that does not announce itself reads as "this is
+ * everything that happened", which is exactly the false confidence a decision record must not
+ * have.
+ */
+function collectWork(root, since) {
+    const fmt = '%h%x09%an%x09%ad%x09%s%n%b';
+    const log = since
+        ? git(['log', `${since}..HEAD`, '--date=short', `--pretty=format:${fmt}`], root)
+        : git(['log', '-30', '--date=short', `--pretty=format:${fmt}`], root);
+    /**
+     * ⚠ THE DIFF BASE IS THE OLDEST COMMIT WE ACTUALLY READ, NOT `HEAD~30`. A repo with fewer than
+     * thirty commits has no `HEAD~30`, and asking for one made git print
+     * `fatal: ambiguous argument` while the run went on to succeed — the stat was simply empty and
+     * nobody could tell. Deriving the base from the log means the window always exists.
+     */
+    const oldest = since || (() => {
+        const shas = git(['log', '-30', '--pretty=format:%H'], root).split('\n').filter(Boolean);
+        return shas.length ? `${shas[shas.length - 1]}^` : '';
+    })();
+    const stat = oldest
+        ? git(['diff', '--stat', `${oldest}..HEAD`], root)
+        // No parent for the very first commit — show what that commit itself introduced.
+        : git(['show', '--stat', '--oneline', 'HEAD'], root);
+    const range = since ? `${since}..HEAD` : 'last 30 commits';
+    const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], root);
+    const commits = log ? log.split('\n').filter((l) => /^[0-9a-f]{7,}\t/.test(l)).length : 0;
+    const CAP = 12_000;
+    let text = [
+        `Repository: ${root.split('/').pop()}`,
+        `Branch: ${branch}`,
+        `Range: ${range}`,
+        '',
+        '## Commits',
+        log || '(none)',
+        '',
+        '## Files changed',
+        stat || '(none)',
+    ].join('\n');
+    const truncated = text.length > CAP;
+    if (truncated)
+        text = `${text.slice(0, CAP)}\n\n[…truncated at ${CAP} characters]`;
+    return { text, commits, truncated };
+}
+async function turn(message) {
+    const res = await rpcOnce('agent-prompt', { message, wait: true, _timeout: TURN_MS }, TURN_MS);
+    const rows = Array.isArray(res?.toolCalls) ? res.toolCalls : [];
+    return {
+        reply: String(res?.reply ?? ''),
+        tools: rows.filter((r) => r?.role === 'tool_call').map((r) => String(r?.tool ?? '')),
+    };
+}
+function die(msg, hint) {
+    console.error(`\n  ${c.red('✗')} ${msg}`);
+    if (hint)
+        console.error(`  ${c.dim(hint)}`);
+    console.error('');
+    process.exit(1);
+}
+// ── note ────────────────────────────────────────────────────────────────────────────────────
+async function cmdNote() {
+    const root = repoRoot();
+    if (!root)
+        die('Not a git repository.', 'clearly note reads your commits — run it inside a repo.');
+    /**
+     * ⚠ AN EXPLICIT `--since` ALWAYS WINS over the bookmark — re-noting a range on purpose is a
+     * thing people do (the first note was thin, the range was wrong), and a tool that silently
+     * refuses because it "already did that" is one you stop reaching for.
+     */
+    const state = readState(root);
+    const bookmark = state.lastCommit && commitExists(root, state.lastCommit) ? state.lastCommit : null;
+    const since = flag('--since') ?? bookmark;
+    const head = git(['rev-parse', 'HEAD'], root);
+    if (!flag('--since') && bookmark && bookmark === head) {
+        console.log(`\n  ${c.dim('Nothing new since the last note.')}`);
+        if (state.note)
+            console.log(`  ${c.dim(state.note)}`);
+        console.log(`  ${c.dim('Re-note a range anyway with:')} clearly note --since HEAD~5\n`);
+        return;
+    }
+    const { text, commits, truncated } = collectWork(root, since);
+    if (!commits) {
+        die('No commits found in that range.', since ? `Nothing between ${since} and HEAD.` : 'This repo has no history yet.');
+    }
+    if (bookmark && !flag('--since')) {
+        console.log(`\n  ${c.dim(`since the last note (${bookmark.slice(0, 7)})`)}`);
+    }
+    if (has('--dry-run')) {
+        console.log(`\n${c.dim('— what would be sent —')}\n`);
+        console.log(text);
+        console.log(`\n${c.dim(`${commits} commits${truncated ? ' · truncated' : ''}`)}\n`);
+        return;
+    }
+    console.log(`\n  ${c.honey('nib')} ${c.dim(`reading ${commits} commits…`)}`);
+    /**
+     * ⚠⚠ THE BRIEF ASKS FOR WHAT WAS REJECTED, BECAUSE THAT IS THE PART THAT IS ALWAYS LOST.
+     * A summary of what changed is recoverable from the log forever; the option someone argued
+     * against and why is not, and it is what stops a team re-litigating the same thing next quarter.
+     *
+     * ⚠ AND IT FORBIDS INVENTION EXPLICITLY. The product's own FAQ promises a note leaves a section
+     * empty rather than filling it in, so the brief has to say so — a model asked for a tidy
+     * document will produce a tidy document whether or not the evidence is there.
+     */
+    const brief = [
+        'Write ONE decision note from the work below, into the notes archive.',
+        '',
+        'Rules:',
+        '- The first line is the note title. Make it name the DECISION, not the task ("Retry backoff, exponential with jitter" — not "Update retry logic").',
+        '- Say WHY, from the evidence. Cite the commit hash or PR number that shows it.',
+        '- Record what was REJECTED and who argued against it, if the evidence shows it. This is the most valuable part.',
+        '- If the evidence does not support a section, LEAVE IT OUT. Do not invent a rationale.',
+        '- Look for an existing note on this subject first and update it rather than creating a near-duplicate.',
+        '- Reply with one line: the path you wrote and what changed. No preamble.',
+        '',
+        '--- the work ---',
+        text,
+    ].join('\n');
+    const t0 = Date.now();
+    let out;
+    try {
+        out = await turn(brief);
+    }
+    catch (err) {
+        const m = String(err?.message ?? err);
+        if (/timeout/i.test(m))
+            die('The note took too long to write.', 'Try a narrower range: clearly note --since HEAD~5');
+        die(m, 'clearly status  — check the connection');
+    }
+    /**
+     * ⚠⚠ THE TOOL CALLS ARE THE EVIDENCE; THE REPLY IS ONLY A CLAIM.
+     *
+     * Observed on a real run: the turn grepped, globbed twice for nothing, hit a `bash` error, wrote
+     * NOTHING — and replied *"`~/Retry backoff…md` — recorded the exponential-backoff decision"*. The
+     * file did exist, from a different run seconds earlier, so the sentence read as true and the
+     * warning under it read as noise.
+     *
+     * A person reads the confident sentence. So when no `write` or `edit` ran, the CLI says so FIRST
+     * and does not print the claim as though it were the outcome — the same rule the eval suite
+     * already enforces for phantom board cards, applied to the verb this product is actually sold on.
+     * Reporting a note that does not exist is worse than reporting a failure: nobody goes looking for
+     * the second one.
+     */
+    const wrote = out.tools.filter((t) => t === 'write' || t === 'edit').length;
+    const secs = ((Date.now() - t0) / 1000).toFixed(1);
+    if (!wrote) {
+        console.log(`  ${c.dim(`${out.tools.length} steps · ${secs}s`)}\n`);
+        console.log(`  ${c.red('✗')} ${c.bold('Nothing was written.')}`);
+        console.log(`  ${c.dim('The agent looked but did not record anything. It said:')}\n`);
+        console.log(`  ${c.dim(out.reply.trim().split('\n').join('\n  ') || '(nothing)')}\n`);
+        console.log(`  ${c.dim('If that reads like it worked, it did not — no write or edit ran.')}`);
+        console.log(`  ${c.dim('Try a narrower range:')} clearly note --since HEAD~5\n`);
+        return; // ⚠ and the bookmark does NOT move — see below.
+    }
+    console.log(`  ${c.mint('tuck')} ${c.dim(`filed · ${out.tools.length} steps · ${secs}s`)}\n`);
+    console.log(out.reply.trim() || c.dim('(the agent wrote nothing back)'));
+    /**
+     * ⚠ THE BOOKMARK MOVES ONLY WHEN SOMETHING WAS ACTUALLY WRITTEN. Advancing it on a turn that
+     * wrote nothing — a timeout, a refusal, an agent that decided the work was already covered —
+     * would skip that range forever, and the commits it describes would never be noted by anything.
+     * Losing a bookmark costs a duplicate; moving one wrongly costs the record.
+     */
+    if (wrote && head) {
+        writeState(root, { lastCommit: head, at: new Date().toISOString(), note: out.reply.trim().slice(0, 200) });
+    }
+    console.log('');
+}
+// ── ask ─────────────────────────────────────────────────────────────────────────────────────
+async function cmdAsk() {
+    const q = argv.slice(1).filter((a) => !a.startsWith('--')).join(' ').trim();
+    if (!q)
+        die('Ask what?', 'clearly ask "why did we drop fixed backoff?"');
+    console.log(`\n  ${c.mint('tuck')} ${c.dim('searching the archive…')}`);
+    /**
+     * ⚠⚠ THE SEARCH IS DONE HERE, DETERMINISTICALLY, AND THE MODEL ONLY SYNTHESISES.
+     *
+     * The first version told the agent to search, and when it missed it answered "nothing in the
+     * archive covers that" about a note written ninety seconds earlier. The obvious fix — instruct
+     * it to try more phrasings — made it strictly worse: it re-issued the SAME search until the
+     * SDK's loop detector ended the turn and the person's answer was `Error: loop detected`.
+     *
+     * That is the same escalation this codebase already paid for once with the thought map's `type`
+     * filter, and it ended the same way: **a guard that depends on the model choosing correctly is
+     * not a guard.** Rewriting the instruction did not work there either; deleting the choice did.
+     *
+     * So retrieval moves out of the model. Grep is cheap, exact, and cannot loop; the model gets the
+     * hits and does the one thing it is actually better at — reading them and answering. It is also
+     * far faster, and a miss is now provably a miss rather than an agent that gave up.
+     */
+    const stop = new Set(['what', 'why', 'when', 'where', 'which', 'does', 'did', 'the', 'and', 'for',
+        'that', 'this', 'with', 'have', 'has', 'was', 'are', 'our', 'you', 'how', 'not', 'but', 'from',
+        'about', 'into', 'they', 'them', 'their', 'were', 'been', 'would', 'could', 'should', 'we']);
+    const terms = q.toLowerCase().replace(/[^\w\s-]/g, ' ').split(/\s+/)
+        .filter((w) => w.length >= 4 && !stop.has(w));
+    const seen = new Set();
+    const hits = [];
+    const searches = [];
+    /** The whole question first, then each distinctive word — narrowest signal to broadest. */
+    const probes = [q.replace(/[^\w\s-]/g, ' ').trim(), ...terms].slice(0, 8);
+    for (const p of probes) {
+        if (!p || hits.length >= 40)
+            continue;
+        searches.push(p);
+        try {
+            const r = await rpcOnce('notes-grep', { pattern: p, limit: 12 }, 60_000);
+            for (const m of (Array.isArray(r?.matches) ? r.matches : []).map(String)) {
+                if (seen.has(m))
+                    continue;
+                seen.add(m);
+                hits.push(m);
+            }
+        }
+        catch { /* one failed probe is not a failed search */ }
+    }
+    let out;
+    try {
+        /**
+         * ⚠⚠ ONE MISS IS NOT AN ANSWER, AND THIS BRIEF EXISTS BECAUSE OF A REAL ONE.
+         *
+         * Asked "why do the notes-shell tools have both prefixed and bare names?", the agent searched
+         * once, found nothing, and replied "Nothing in the notes archive covers that" — while a note
+         * written ninety seconds earlier said, on line 14, *"Bare names as the only registry names
+         * were rejected after six consecutive `Unknown action: bash` failures"*. `grep "bare names"`
+         * finds it instantly.
+         *
+         * **A false "we have no record of that" is worse than having no archive**: it sends someone off
+         * to re-litigate a decision that IS written down, and it teaches them the archive cannot be
+         * trusted — which is the whole asset.
+         *
+         * ⚠ THE ESCALATION IS SPELLED OUT because "search before you answer" plainly is not enough —
+         * it was already in the previous brief. A question and the note answering it are written by
+         * different people at different times, so the words rarely match: the asker says "why do the
+         * tools have two names", the note says "registry-prefixed … aliases". Searching the QUESTION's
+         * vocabulary and stopping is the single most likely way to miss.
+         */
+        out = await turn([
+            'Answer this question from the workspace notes.',
+            '',
+            hits.length
+                ? [
+                    'These lines were already found for you by searching the archive. Read the notes they',
+                    'point at if you need more context, then answer and CITE the note path.',
+                    'If they genuinely do not answer it, say so — do not stretch them into an answer.',
+                    '',
+                    '--- search hits ---',
+                    hits.slice(0, 40).join('\n'),
+                ].join('\n')
+                : [
+                    `The archive was searched for: ${searches.slice(0, 6).join(', ')} — nothing matched.`,
+                    'Say plainly that it is not written down, and name what was searched for so they can',
+                    'tell "not recorded" from "not found". Do not answer from general knowledge.',
+                ].join('\n'),
+            '',
+            `--- question ---`,
+            q,
+        ].join('\n'));
+    }
+    catch (err) {
+        die(String(err?.message ?? err), 'clearly status  — check the connection');
+    }
+    console.log('');
+    console.log(out.reply.trim() || c.dim('(no answer)'));
+    console.log('');
+}
+// ── pull ────────────────────────────────────────────────────────────────────────────────────
+/**
+ * ⚠⚠ THIS IS THE CLAIM "your notes are files in your repo" MADE TRUE. Until the archive is on
+ * disk, "uninstall and the archive is untouched" is marketing rather than a property — the notes
+ * live in a Durable Object and leaving takes them with it.
+ *
+ * ⚠ ONE DIRECTION, DELIBERATELY. Writing local edits back is a merge problem with a live agent on
+ * the other side, and a half-built two-way sync loses work in a way nobody notices for weeks. Pull
+ * is safe, useful on its own (commit the archive, review it in a PR), and does not pretend.
+ */
+async function cmdPull() {
+    const root = repoRoot() ?? process.cwd();
+    const dir = resolve(flag('--dir') ?? join(root, '.clearly', 'notes'));
+    console.log(`\n  ${c.dim('reading the archive…')}`);
+    const listed = await rpcOnce('notes-glob', { pattern: '~/**/*.md', limit: 500 }, 120_000);
+    const paths = Array.isArray(listed?.files) ? listed.files.map(String) : [];
+    if (!paths.length)
+        die('The archive is empty.', 'Write one first:  clearly note');
+    let written = 0;
+    for (const p of paths) {
+        const rel = p.replace(/^~\/?/, '');
+        let body = '';
+        try {
+            const r = await rpcOnce('notes-read', { file_path: p }, 60_000);
+            // `read` returns `cat -n` numbered lines — strip the gutter before writing a real file.
+            body = String(r?.content ?? '').replace(/^\s*\d+\t/gm, '');
+        }
+        catch {
+            continue;
+        }
+        if (!body.trim())
+            continue;
+        const target = join(dir, rel);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, body.endsWith('\n') ? body : `${body}\n`);
+        written++;
+    }
+    console.log(`  ${c.mint('✓')} ${written} notes → ${c.bold(dir.replace(root + '/', ''))}`);
+    console.log(`  ${c.dim('They are plain markdown. Commit them like any other file.')}\n`);
+}
+// ── status ──────────────────────────────────────────────────────────────────────────────────
+async function cmdStatus() {
+    const root = repoRoot();
+    console.log('');
+    console.log(`  ${c.bold('clearly')}`);
+    console.log(`  ${c.dim('─'.repeat(46))}`);
+    console.log(`  Repo        ${root ? root.split('/').pop() : c.dim('not a git repository')}`);
+    let notes = 0, reachable = false;
+    try {
+        const r = await rpcOnce('notes-glob', { pattern: '~/**/*.md', limit: 500 }, 60_000);
+        notes = Number(r?.count ?? 0);
+        reachable = true;
+    }
+    catch { /* reported below */ }
+    console.log(`  Archive     ${reachable ? `${notes} notes` : c.red('unreachable')}`);
+    console.log(`  Sources     git ${c.dim('(local commits)')}`);
+    /**
+     * ⚠ THE UNBUILT SOURCES ARE NAMED HERE ON PURPOSE. The landing page sells GitHub, Linear and
+     * Slack; a CLI that stays quiet about not having them lets someone believe a note covered a
+     * discussion it never saw. Being the one surface that says what it cannot see is cheap honesty.
+     */
+    console.log(`              ${c.dim('github, linear, slack — not connected in this build')}`);
+    if (!reachable) {
+        console.log(`\n  ${c.dim('Not connected. Sign in with:')}  beehaven login`);
+    }
+    console.log('');
+}
+// ── login / logout ──────────────────────────────────────────────────────────────────────────
+/**
+ * ⚠⚠ AUTH IS DELEGATED, NOT REIMPLEMENTED. `beehaven login` is ~300 lines of loopback OAuth —
+ * ephemeral local server, anti-CSRF state, browser round-trip, keychain write — and it is inline
+ * in `cli.ts` rather than exported. Copying it here would be a SECOND auth stack against the same
+ * accounts, which is how the two drift and how one of them ends up subtly wrong on the day it
+ * matters. Both binaries ship from this package, so the sibling is always the right version.
+ *
+ * The user never sees the delegation: stdio is inherited, so the browser opens and the prompts
+ * appear exactly as they would either way.
+ */
+function delegate(verb, args = []) {
+    const cli = join(dirname(fileURLToPath(import.meta.url)), 'cli.js');
+    const r = spawnSync(process.execPath, [cli, verb, ...args], { stdio: 'inherit' });
+    process.exit(r.status ?? 0);
+}
+// ── settings ────────────────────────────────────────────────────────────────────────────────
+async function cmdSettings() {
+    const key = argv[1];
+    const value = argv[2];
+    /**
+     * ⚠ ONLY SETTINGS THIS CLI ACTUALLY HONOURS ARE LISTED. A settings screen that shows a key
+     * nothing reads is worse than no screen — it invites someone to change a value and conclude the
+     * product ignored them.
+     */
+    const OWNED = {
+        notesDir: 'Where `clearly pull` writes markdown (default: .clearly/notes)',
+    };
+    if (key && !OWNED[key]) {
+        die(`Not a clearly setting: ${key}`, `Settings: ${Object.keys(OWNED).join(', ')}. Account and environment are beehaven's — use \`beehaven env\`.`);
+    }
+    if (key && value !== undefined) {
+        patchCliConfig({ [`clearly.${key}`]: value });
+        console.log(`\n  ${c.mint('✓')} ${key} = ${value}\n`);
+        return;
+    }
+    const cfg = readCliConfig();
+    console.log('');
+    console.log(`  ${c.bold('settings')}`);
+    console.log(`  ${c.dim('─'.repeat(52))}`);
+    for (const [k, desc] of Object.entries(OWNED)) {
+        const v = cfg[`clearly.${k}`] ?? c.dim('(default)');
+        console.log(`  ${k.padEnd(12)} ${String(v)}`);
+        console.log(`  ${c.dim(' '.repeat(12) + ' ' + desc)}`);
+    }
+    console.log('');
+    // ⚠ Account and env belong to the daemon and are shown READ-ONLY here, with the verb that owns
+    // them — two places that can both write one value is how they disagree.
+    console.log(`  ${c.dim('Account')}      ${String(cfg.email ?? c.dim('not signed in'))}`);
+    console.log(`  ${c.dim('Environment')}  ${String(cfg.envName ?? cfg.env ?? 'prod')}  ${c.dim('· change with `beehaven env`')}`);
+    console.log('');
+    console.log(`  ${c.dim('clearly settings <key> <value>')}`);
+    console.log('');
+}
+// ── uninstall ───────────────────────────────────────────────────────────────────────────────
+/**
+ * ⚠⚠ THIS REMOVES LOCAL STATE. IT DOES NOT TOUCH THE ARCHIVE, AND IT SAYS SO.
+ *
+ * The notes are the asset — the entire pitch is that cancelling takes nothing away. An uninstall
+ * that quietly deleted them, or that left someone UNSURE whether it had, would undo that promise
+ * more effectively than any outage. So it names what it deleted and what it did not, every time.
+ *
+ * ⚠ IT ALSO DOES NOT SIGN YOU OUT unless asked. Auth is shared with `beehaven`, and revoking it
+ * here would break a tool the person did not ask about.
+ *
+ * ⚠⚠ AND IT REMOVES ONLY THE FILES THIS CLI WROTE — NOT `.clearly/`. The first version deleted the
+ * whole directory recursively, and running it on this very repo found `README.md` and `REVENUE.md`
+ * already living there: `.clearly/` is a SHARED layout (the daemon's sync puts `CLAUDE.md`,
+ * `tasks.yaml` and `memories.yaml` in it too). A recursive delete of a directory you shipped one
+ * file into is how an uninstall takes someone's documentation with it, silently, and the tell
+ * would have been a git diff nobody read until later.
+ */
+const OWNED_PATHS = ['state.json', 'notes'];
+function cmdUninstall() {
+    const root = repoRoot() ?? process.cwd();
+    const dir = join(root, '.clearly');
+    const rel = dir.replace(root + '/', '');
+    const mine = OWNED_PATHS.filter((p) => existsSync(join(dir, p)));
+    const theirs = (() => {
+        try {
+            return readdirSync(dir).filter((f) => !OWNED_PATHS.includes(f));
+        }
+        catch {
+            return [];
+        }
+    })();
+    if (!mine.length) {
+        console.log(`\n  ${c.dim('Nothing to remove — this repo has no clearly state.')}\n`);
+        return;
+    }
+    if (!has('--yes')) {
+        console.log(`\n  This will remove from ${c.bold(rel)}:`);
+        for (const p of mine) {
+            console.log(`    · ${p} ${c.dim(p === 'notes' ? '(your pulled copy — the archive itself is untouched)' : '(where the last note stopped)')}`);
+        }
+        if (theirs.length)
+            console.log(`\n  ${c.dim(`Leaving alone: ${theirs.join(', ')}`)}`);
+        console.log(`\n  ${c.dim('It does NOT delete your notes archive, and does NOT sign you out.')}`);
+        console.log(`  ${c.dim('Run again with --yes to confirm.')}\n`);
+        return;
+    }
+    const gone = [];
+    for (const p of mine) {
+        try {
+            rmSync(join(dir, p), { recursive: true, force: true });
+            gone.push(p);
+        }
+        catch { /* reported */ }
+    }
+    console.log(`\n  ${c.mint('✓')} removed ${gone.join(', ')} from ${rel}`);
+    if (theirs.length)
+        console.log(`  ${c.dim(`Left alone: ${theirs.join(', ')}`)}`);
+    console.log(`  ${c.dim('Your archive is untouched — `clearly ask` still answers, `clearly pull` restores the files.')}`);
+    console.log(`  ${c.dim('Still signed in. Sign out with:')} beehaven logout\n`);
+}
+// ── main ────────────────────────────────────────────────────────────────────────────────────
+/**
+ * ⚠ THE TWO VERBS THAT DO THE WORK COME FIRST, and the housekeeping is grouped below them. A flat
+ * alphabetical list of eight makes `note` and `settings` look equally important, and the first
+ * thing a new reader needs is which one to type tonight.
+ */
+function help() {
+    console.log(`
+  ${c.bold('clearly')} ${c.dim('— write the decision down while the context is still warm')}
+
+    ${c.bold('note')} ${c.dim('[--since <ref>] [--dry-run]')}
+        Read the work in this repo and write the decision into the archive.
+        ${c.dim('Defaults to everything since your last note.')}
+        ${c.dim('--since HEAD~5   that range instead     --dry-run   show what would be sent')}
+
+    ${c.bold('ask')} ${c.dim('"<question>"')}
+        Answer from the archive, citing the note it came from.
+
+  ${c.dim('─── the archive ' + '─'.repeat(38))}
+
+    ${c.bold('pull')} ${c.dim('[--dir <path>]')}      Write it into this repo as markdown ${c.dim('(.clearly/notes)')}
+    ${c.bold('status')}                  What is connected, and what it can see
+
+  ${c.dim('─── your account ' + '─'.repeat(37))}
+
+    ${c.bold('login')} ${c.dim('·')} ${c.bold('logout')}          Sign in or out ${c.dim('(shared with beehaven)')}
+    ${c.bold('settings')} ${c.dim('[<k> <v>]')}       Show or change settings
+    ${c.bold('uninstall')} ${c.dim('[--yes]')}         Remove local state ${c.dim('— never your archive')}
+`);
+}
+(async () => {
+    switch (cmd) {
+        case 'note':
+            await cmdNote();
+            break;
+        case 'ask':
+            await cmdAsk();
+            break;
+        case 'pull':
+            await cmdPull();
+            break;
+        case 'status':
+            await cmdStatus();
+            break;
+        case 'login':
+            delegate('login', argv.slice(1));
+            break;
+        case 'logout':
+            delegate('logout', argv.slice(1));
+            break;
+        case 'settings':
+            await cmdSettings();
+            break;
+        case 'uninstall':
+            cmdUninstall();
+            break;
+        case 'help':
+        case '--help':
+        case '-h':
+            help();
+            break;
+        default:
+            console.error(`\n  ${c.red('✗')} unknown command: ${cmd}`);
+            help();
+            process.exit(1);
+    }
+})().catch((err) => {
+    console.error(`\n  ${c.red('✗')} ${err?.message ?? err}\n`);
+    process.exit(1);
+});