beehaven 0.8.16

package/dist/daemon-mcp-sandbox.js

@@ -0,0 +1,127 @@
+/**
+ * Ephemeral sandboxed MCP (#81) — per-session, time-boxed MCP server
+ * instances that auto-terminate when the agent turn ends OR the
+ * timeout fires.
+ *
+ * Why: many MCP servers are "useful for one task" — a Gmail server
+ * for a triage session, a Stripe sandbox key for a billing prototype.
+ * Keeping them long-lived (the #80 + #82 pattern) is wrong for these
+ * cases. This module spawns them on-demand with:
+ *   - per-session env injection (auth tokens, sandbox keys)
+ *   - 10-minute idle timeout (configurable)
+ *   - SIGTERM on session end OR daemon shutdown
+ *   - process-table tracking so `daemon-mcp-sandbox-list` reports
+ *     which sandboxes are alive
+ *
+ * Usage from the daemon's IPC layer:
+ *
+ *     beehaven mcp-sandbox start \
+ *       --command "uvx mcp-server-stripe-sandbox" \
+ *       --env STRIPE_KEY=sk_test_... \
+ *       --session-id <fab-session>
+ *
+ *     → returns { sandboxId, mcpEndpoint: 'stdio:...' }
+ *
+ *     Agent uses the sandboxId in its tool definitions; daemon
+ *     terminates on session end.
+ */
+import { spawn } from 'child_process';
+const _sandboxes = new Map();
+const SWEEP_INTERVAL_MS = 60_000;
+let _sweepTimer = null;
+/**
+ * Spawn an ephemeral MCP server bound to a session.
+ *
+ * Returns the sandbox descriptor. Caller pipes its stdin/stdout for
+ * MCP protocol traffic (or the daemon's MCP-bridge does this on
+ * their behalf).
+ */
+export function startMcpSandbox(args) {
+    const id = `mcps-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+    const proc = spawn(args.command, args.commandArgs ?? [], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env, ...(args.env ?? {}) },
+    });
+    const sandbox = {
+        id,
+        sessionId: args.sessionId,
+        command: args.command,
+        args: args.commandArgs ?? [],
+        env: args.env ?? {},
+        proc: proc,
+        startedAt: Date.now(),
+        lastActive: Date.now(),
+        idleTimeoutMs: args.idleTimeoutMs ?? 10 * 60 * 1000,
+    };
+    _sandboxes.set(id, sandbox);
+    proc.on('exit', () => {
+        _sandboxes.delete(id);
+    });
+    // Lazy-start the sweep timer the first time any sandbox spawns.
+    if (!_sweepTimer) {
+        _sweepTimer = setInterval(sweepIdleSandboxes, SWEEP_INTERVAL_MS);
+        // Don't keep the daemon alive solely for the sweep timer.
+        if (typeof _sweepTimer?.unref === 'function') {
+            _sweepTimer.unref();
+        }
+    }
+    return sandbox;
+}
+/** Mark a sandbox as recently-used (called on every MCP protocol
+ *  message routed through it). */
+export function touchMcpSandbox(id) {
+    const sandbox = _sandboxes.get(id);
+    if (sandbox)
+        sandbox.lastActive = Date.now();
+}
+/** Terminate a specific sandbox. */
+export function stopMcpSandbox(id) {
+    const sandbox = _sandboxes.get(id);
+    if (!sandbox)
+        return false;
+    try {
+        sandbox.proc.kill('SIGTERM');
+    }
+    catch { }
+    _sandboxes.delete(id);
+    return true;
+}
+/** Terminate every sandbox bound to a session — called when the
+ *  agent turn ends OR on daemon shutdown. */
+export function stopMcpSandboxesForSession(sessionId) {
+    let stopped = 0;
+    for (const [id, sandbox] of _sandboxes) {
+        if (sandbox.sessionId === sessionId) {
+            try {
+                sandbox.proc.kill('SIGTERM');
+            }
+            catch { }
+            _sandboxes.delete(id);
+            stopped++;
+        }
+    }
+    return stopped;
+}
+/** List active sandboxes for daemon-status JSON. */
+export function listMcpSandboxes() {
+    const now = Date.now();
+    return [..._sandboxes.values()].map((s) => ({
+        id: s.id,
+        sessionId: s.sessionId,
+        command: s.command,
+        ageMs: now - s.startedAt,
+        idleMs: now - s.lastActive,
+    }));
+}
+function sweepIdleSandboxes() {
+    const now = Date.now();
+    for (const [id, sandbox] of _sandboxes) {
+        if (now - sandbox.lastActive > sandbox.idleTimeoutMs) {
+            try {
+                sandbox.proc.kill('SIGTERM');
+            }
+            catch { }
+            _sandboxes.delete(id);
+        }
+    }
+}

package/dist/daemon-omni-company.js

@@ -0,0 +1,338 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+/**
+ * daemon-omni-company — run the workspace like a company, not like a chat.
+ *
+ * ## What this is
+ *
+ * A prompt ADDON, selected by a flag, that puts Omni into a mode where the deliverable is the
+ * WORKSPACE rather than the reply: a request produces a PRD, a design doc, tickets, designs and a
+ * QA pass, each as a real artifact somebody else could pick up — the way a large engineering
+ * organisation produces work.
+ *
+ * ⚠⚠ IT IS AN ADDON, NOT A REPLACEMENT. `OMNI_IDENTITY` still leads. Every safety property lives
+ * there — what may be run, what may never be done unasked, the git rules, when to stop and ask —
+ * and a mode that replaced it would drop all of them to gain a role-play. This says HOW the work is
+ * recorded; the identity says who is doing it and what they may not do.
+ *
+ * ⚠ IT SITS BEFORE THE CACHE BOUNDARY. The text is static per build, so it belongs in the cacheable
+ * prefix beside the identity. Appending it per turn as `appendSystemPrompt` would push ~6 KB across
+ * the boundary on every single turn — the prefix-cache mistake `resolveSystemPrompt` was split to
+ * avoid.
+ *
+ * ## ⚠⚠ What this mode DELIBERATELY DOES NOT DO
+ *
+ * **It does not role-play a cast of named people.** `THOUGHT_AGENT` notes record why: role-played
+ * org charts — "you are the CEO, now switch to the VP" — were refused there as "a fabrication
+ * engine", and that judgement holds. A team here is a **discipline with a deliverable and a gate**,
+ * not a character with a name and a personality. The value is the artifact trail, and a model
+ * inventing a design director's opinion produces neither better artifacts nor honest ones.
+ *
+ * **It does not invent approvals.** No stage may mark itself reviewed by somebody who does not
+ * exist. A gate is passed by producing the artifact, never by narrating that a teammate signed off.
+ */
+/**
+ * The workspace this mode is meant to run in.
+ *
+ * ⚠ NAMED, NOT ASSUMED. A mode that fills a workspace with PRDs and tickets must not do it to
+ * whichever workspace the daemon happened to be pointed at — `beehaven connect` is machine-global
+ * and another session can move it. The prompt says the name out loud so the agent checks before it
+ * writes, and `beehaven pwd` is the check.
+ */
+export const COMPANY_WORKSPACE = 'hive2';
+/**
+ * The same workspace by id, because the DAEMON only knows the id.
+ *
+ * ⚠⚠ WITHOUT THIS THE DIAGNOSTIC LIES. `connectedBuilding` carries a `buildingId`, and comparing
+ * an id against the string `'hive2'` would report "connected to the wrong workspace" on a daemon
+ * that is connected to exactly the right one — the false alarm this diagnostic's own `null` case
+ * was written to avoid, arriving through the comparison instead.
+ *
+ * ⚠ OVERRIDABLE, because an id is deployment-specific in a way a name is not. Empty means "ids
+ * cannot be matched here", which resolves to `null` — unknown — rather than to a false mismatch.
+ */
+export const COMPANY_WORKSPACE_ID = String(process.env.CLEARLY_COMPANY_WORKSPACE_ID ?? '').trim();
+/** `CLEARLY_COMPANY_MODE=1` turns it on. Off by default — this is a dev-only surface today. */
+export function isCompanyMode(env = process.env) {
+    const v = String(env.CLEARLY_COMPANY_MODE ?? '').trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'on';
+}
+/**
+ * Where the persisted switch lives.
+ *
+ * ⚠⚠ AN ENV VAR IS THE WRONG ONLY-SWITCH FOR A DAEMON, AND THIS IS THE FAILURE IT CAUSED. The
+ * daemon is spawned by the Mac app (or by `beehaven start --headless`), so `CLEARLY_COMPANY_MODE=1`
+ * typed in a terminal reaches the SHELL THAT TALKS TO the daemon and never the daemon itself.
+ * Measured on this machine: the feature was written, wired, tested — and `ps eww` on the running
+ * daemon showed the variable absent, so company mode had been OFF the whole time. `companyDiagnostics`
+ * exists to catch exactly that and warns about it in those words; nobody could run it (see below).
+ *
+ * ⚠ ITS OWN FILE, NOT `config.json`. That one holds relay credentials and tokens — a mode switch has
+ * no business in a secrets file, and this repo's own notes record the permission classifier blocking
+ * hand-edits to it. Same shape as the `target-*.json` files beside it.
+ */
+export const COMPANY_MODE_FILE = join(homedir(), '.beehaven', 'company-mode.json');
+/** The persisted switch. Unreadable / absent / malformed ⇒ OFF, never a throw. */
+export function readCompanyMode(file = COMPANY_MODE_FILE) {
+    try {
+        const raw = JSON.parse(readFileSync(file, 'utf8'));
+        return {
+            enabled: raw?.enabled === true,
+            ...(raw?.workspaceId ? { workspaceId: String(raw.workspaceId) } : {}),
+            ...(raw?.updatedAt ? { updatedAt: Number(raw.updatedAt) } : {}),
+        };
+    }
+    catch {
+        return { enabled: false };
+    }
+}
+/** Persist the switch. Returns what was written so a caller can report it back verbatim. */
+export function writeCompanyMode(patch, file = COMPANY_MODE_FILE) {
+    const next = { ...readCompanyMode(file), ...patch, updatedAt: Date.now() };
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(next, null, 2));
+    return next;
+}
+/**
+ * IS THE MODE ON? — the question the daemon actually asks.
+ *
+ * ⚠⚠ TWO NAMES BECAUSE THERE ARE TWO QUESTIONS, and collapsing them would lose the one the
+ * diagnostic needs. `isCompanyMode` answers *"did the operator set the env var"*; this answers
+ * *"is the mode on"*. The gap between those two is precisely the failure above — the var set on the
+ * wrong process — so a diagnostic that cannot tell them apart cannot report it.
+ *
+ * ⚠ THE ENV VAR WINS WHEN IT IS SET TO ANYTHING AT ALL, including `0`. An explicit
+ * `CLEARLY_COMPANY_MODE=0` must be able to turn the mode OFF on a machine whose file says on —
+ * otherwise the env var is not an override, it is a one-way latch.
+ */
+export function companyModeEnabled(env = process.env, file = COMPANY_MODE_FILE) {
+    if (String(env.CLEARLY_COMPANY_MODE ?? '').trim())
+        return isCompanyMode(env);
+    return readCompanyMode(file).enabled;
+}
+/** Where the answer came from — reported, because "set on the wrong process" has no other symptom. */
+export function companyModeSource(env = process.env, file = COMPANY_MODE_FILE) {
+    if (String(env.CLEARLY_COMPANY_MODE ?? '').trim())
+        return isCompanyMode(env) ? 'env' : 'off';
+    return readCompanyMode(file).enabled ? 'persisted' : 'off';
+}
+/**
+ * Everything an operator needs to answer "is company mode actually working", in one object.
+ *
+ * ⚠⚠ IT REPORTS STATE, NOT EVENTS. A log says what happened during turns somebody ran; it cannot
+ * say that the mode has been silently OFF all week because the env var never reached the daemon, or
+ * that the daemon drifted onto the wrong workspace after somebody ran `beehaven connect` in a
+ * terminal. Those are the two failures that produce no error and no output — the same reasoning
+ * `thought-stats` exists for.
+ *
+ * ⚠ PURE, AND IT TAKES ITS INPUTS. It cannot read the daemon's connection or the identity registry
+ * itself without importing half the daemon, and a diagnostic that drags in what it inspects is a
+ * diagnostic that stops working exactly when the thing it inspects is broken.
+ */
+export function companyDiagnostics(input = {}) {
+    const env = input.env ?? process.env;
+    const modeFile = input.modeFile ?? COMPANY_MODE_FILE;
+    const on = companyModeEnabled(env, modeFile);
+    const source = companyModeSource(env, modeFile);
+    const identity = String(input.identity ?? '');
+    const connected = input.connectedWorkspace ?? null;
+    /**
+     * ⚠ THE MATCH IS BY NAME AND IS `null` WHEN UNKNOWN, never `false`. `beehaven workspaces` prints
+     * ids; a caller that could not resolve the name must not be reported as "connected to the wrong
+     * workspace" — that reads as a fault and sends someone looking for one.
+     */
+    /**
+     * ⚠ THE ID MAY BE PERSISTED TOO. `beehaven omni company on --workspace <id>` records it, so an
+     * operator can make the match checkable without setting a build-time env var — which is the same
+     * reason the switch itself is persisted.
+     */
+    const expectedId = COMPANY_WORKSPACE_ID || String(readCompanyMode(modeFile).workspaceId ?? '');
+    const matches = connected == null
+        ? null
+        : (connected === COMPANY_WORKSPACE || (!!expectedId && connected === expectedId)
+            ? true
+            // ⚠ An id we cannot check is UNKNOWN, not wrong. Without `COMPANY_WORKSPACE_ID` configured
+            //   every id-shaped label would read as a mismatch and send someone hunting a fault.
+            : (!expectedId && /^[0-9a-f]{32,}$/i.test(connected) ? null : false));
+    const identityBytes = identity.length;
+    const addonBytes = on ? COMPANY_ADDON.length : 0;
+    const totalBytes = identityBytes + addonBytes;
+    const warnings = [];
+    if (!on)
+        warnings.push('company mode is OFF — turn it on with `beehaven omni company on` (persisted, survives a daemon restart). CLEARLY_COMPANY_MODE=1 also works, but it must be set on the DAEMON\u2019s environment, not on the shell that talks to it — which is how this was off for the whole time it appeared to be built.');
+    if (on && !identity)
+        warnings.push('no Omni identity registered — the addon is running on the bare claude_code preset, without the safety rules the identity carries');
+    if (on && matches === false)
+        warnings.push(`daemon is connected to "${connected}", not "${COMPANY_WORKSPACE}" — this mode writes artifacts and must not fill the wrong workspace`);
+    if (on && matches === null)
+        warnings.push('could not resolve the connected workspace — run `beehaven pwd` before trusting any write');
+    if (on && input.claudeBinary === null)
+        warnings.push('no claude binary resolved — turns will refuse until Claude Code is installed');
+    return {
+        mode: on ? 'on' : 'off',
+        source,
+        workspace: { expected: COMPANY_WORKSPACE, connected, matches },
+        identityRegistered: !!identity,
+        // ⚠ 4 bytes/token is a rough divisor, and it is here so the number is COMPARABLE across builds
+        //   rather than precise. The point is noticing the prompt doubling, not billing for it.
+        prompt: { identityBytes, addonBytes, totalBytes, approxTokens: Math.round(totalBytes / 4) },
+        requiredVerbs: COMPANY_REQUIRED_VERBS,
+        claudeBinary: input.claudeBinary ?? null,
+        warnings,
+    };
+}
+/**
+ * The verbs the addon actually names.
+ *
+ * ⚠⚠ KEEP THIS IN STEP WITH THE PROMPT. It exists so a missing GRANT is visible as a diagnostic
+ * rather than as an agent quietly failing mid-sprint — `dev-report` was ungranted when this mode
+ * was written, which would have made the "file the tooling gap" instruction refuse every time
+ * while reading perfectly in the prompt. A guard asserts every name here appears in the addon.
+ */
+export const COMPANY_REQUIRED_VERBS = [
+    'document-create', 'document-edit', 'document-append', 'document-link-resolve',
+    'board-create', 'ticket-create', 'ticket-update',
+    'composition-create', 'canvas-act',
+    'sheet-create', 'sheet-set', 'sheet-append',
+    'project-create', 'project-list',
+    // ⚠ THE DELIVERY VERBS. Project management is a discipline here, not a synonym for the board,
+    //   and these are what it actually uses — a sprint nobody can plan or measure is a label.
+    'sprint-create', 'sprint-plan', 'sprint-start', 'sprint-complete', 'sprint-list',
+    'ticket-link-create', 'ticket-links', 'burndown',
+    // ⚠ THE LIFECYCLE EDGE. `work-status` is how a stage is READ; `work-unlink` is the only way to
+    //   clear a dead artifact link, and without it `brokenLinks` is a number that only goes up.
+    'work-status', 'work-links', 'work-link', 'work-unlink',
+    'dev-report',
+    '_rpc:catalog', 'describe-action',
+];
+/**
+ * The verbs each stage actually reaches for. Injected per turn, so the model is told about the
+ * FIVE it needs rather than the forty it might.
+ *
+ * ⚠ NOT A TOOL GRANT. Everything remains reachable; this is a pointer, not a palette. Narrowing
+ * what is *available* per stage would break the ordinary case where a turn spans two of them.
+ */
+const STAGE_VERBS = {
+    prd: 'document-create { ticketId, artifactKind:"prd" } · document-edit · ticket-update',
+    design: 'composition-create · canvas-act (canvas.compose) · work-link { kind:"design", refKind:"composition" }',
+    'eng-design': 'document-create { ticketId, artifactKind:"eng-design" } · bash · read · edit',
+    qa: 'bash · document-create { ticketId, artifactKind:"qa" } · ticket-update',
+    done: 'ticket-update · work-link { kind:"pr", refKind:"url" }',
+};
+/** What a stage is FOR, in one clause — the judgement the verbs cannot carry. */
+const STAGE_INTENT = {
+    prd: 'state the problem, who has it, what done looks like, what is out of scope, and how you would know it worked',
+    design: 'show the screens and the states that actually fail — empty, loading, error — not only the happy path',
+    'eng-design': 'state the approach, what was rejected and why, the data model, and what breaks at scale',
+    qa: 'write what was tested, what passed, what did not, and what is knowingly untested',
+    done: 'every gate is met — close it, and link the PR if there is one',
+};
+/**
+ * The pre-turn block: where this work stands, and what this stage is for.
+ *
+ * ⚠⚠ EVERY WORD OF IT IS DERIVED FROM THE BOARD. That is the whole design. A block that ASSERTED a
+ * stage could contradict the card the moment somebody moved it in the UI — and a model handed two
+ * contradictory inventories does not average them, it follows whichever it read last. Derived, it
+ * cannot disagree with the thing it describes.
+ *
+ * ⚠ IT REPLACES FOUR FIFTHS OF THE STANDING ADDON. That text describes five disciplines, four of
+ * which are irrelevant on any given turn, and it is paid on every one. This is ~120 tokens and it
+ * is about the turn actually happening.
+ *
+ * ⚠ NO ACTIVE CARD ⇒ NO BLOCK. Silence is correct: a turn with no work in front of it is a
+ * conversation, and inventing a stage for it is how every question starts minting PRDs.
+ */
+export function workContextBlock(work) {
+    if (!work)
+        return '';
+    const met = Object.entries(work.gates).filter(([, v]) => v).map(([k]) => k);
+    const stage = work.stage || 'prd';
+    const lines = [
+        `## This turn's work`,
+        `**${work.key ?? '(unkeyed)'} — ${work.title}** · ${work.status}`,
+        met.length ? `Done: ${met.join(', ')}` : 'Nothing recorded against it yet.',
+        work.nextGate
+            ? `**Next gate: ${work.nextGate}** — ${STAGE_INTENT[stage] ?? ''}`
+            : `All gates met — ${STAGE_INTENT.done}`,
+        `Reach for: ${STAGE_VERBS[stage] ?? STAGE_VERBS.prd}`,
+    ];
+    /**
+     * ⚠ A BROKEN LINK IS SURFACED, not silently excluded. `work-status` already refuses to count it
+     * toward a gate; if nobody is ever TOLD, the card quietly needs a fix nobody makes.
+     */
+    if (work.brokenLinks > 0) {
+        lines.push(`⚠ ${work.brokenLinks} link(s) on this card point at something deleted — \`work-links\` shows which.`);
+    }
+    if (work.pr.length)
+        lines.push(`PR: ${work.pr.join(' · ')}`);
+    /**
+     * ⚠⚠ THE CARVE-OUT SURVIVES THE INJECTION. Without this line the block reads as an instruction to
+     * advance the gate whatever was asked, and every "what do you think?" turns into a PRD — the
+     * failure the no-unasked-cards restraint exists for. The stage says where the work stands; it
+     * does not decide that this turn is work.
+     */
+    lines.push('⚠ This says where the work stands. If they asked a question, answer it — a question is not a stage.');
+    return lines.join('\n');
+}
+export const COMPANY_ADDON = [
+    `# Operating mode: the workspace is the company`,
+    `You are running as an engineering organisation rather than as an assistant in a chat. The person you are talking to is a stakeholder, not a ticket queue: they describe what they want in ordinary language, and **you produce the artifacts a company would produce.** They should never have to ask you to write a PRD, open a ticket, make a design or file a doc. If the work needs one, it exists by the time you reply.`,
+    `**The workspace \`${COMPANY_WORKSPACE}\` is the source of truth.** Not this conversation. A decision that exists only in a message you sent has not been made — it is lost the moment the thread scrolls. Before you write anything, confirm where you are with \`beehaven pwd\`; if it is not \`${COMPANY_WORKSPACE}\`, connect to it and say so in one clause. Never fill a workspace you were not asked to fill.`,
+    `## The disciplines`,
+    /**
+     * ⚠⚠ NAMED, NOT DESCRIBED — the per-turn block carries the ACTIVE one in full.
+     *
+     * This used to be five paragraphs explaining what a PRD is, what a design owes, what QA's
+     * deliverable is. Four fifths of that is irrelevant on any given turn and it was paid on every
+     * one. `workContextBlock` injects the stage the work is actually at, its intent, and the verbs
+     * it uses — ~120 tokens, derived from the board, about the turn that is happening.
+     */
+    `Five disciplines, each with a deliverable: **product** owns the PRD · **design** owns the screens and their failure states · **engineering** owns the design document and the code · **QA** owns a written verification · **project management** owns the plan — the sprint, the sequence, the dependencies and the honest forecast. They are DISCIPLINES, not people: do not name colleagues, do not invent their opinions, and never record that someone reviewed something. A gate is passed by producing the artifact.`,
+    /**
+     * ⚠⚠ PROJECT MANAGEMENT IS NOT A GATE, AND MUST NOT BECOME ONE. The four gates are per-CARD and
+     * ask *is this piece of work justified*. Delivery asks a question one level up — *is the set of
+     * work going to land* — so adding a `pm` gate would demand a planning artifact on every single
+     * card, which is how a tracker becomes paperwork. `GATE_ORDER` stays four.
+     */
+    `⚠ **Project management works on the SPRINT, not on the card.** Its questions are what we committed to, what blocks what, and whether the forecast is real — so its deliverables are the sprint, the dependency links and the plan, never a per-card artifact. \`ticket-link-create { fromId, toId, linkType:"blocks" }\` records a dependency (both ends take a key); \`ticket-links\` reads them back and says whether a card is blocked; \`burndown { kind:"velocity" }\` is what a forecast is allowed to be based on. **Size cards with \`points\` — a TOP-LEVEL field, not a member of \`data\`, which counts as zero and makes every figure under-report.**`,
+    `## The gates`,
+    /**
+     * ⚠⚠ THE GATES ARE NOT LISTED HERE ANY MORE — THEY ARE READ. `work-status` answers which are met
+     * for the active card, and the pre-turn block names the next unmet one. A gate written as prose
+     * is one the model can talk itself out of; a gate read from `ticket_artifacts` is a fact, and one
+     * pointing at a DELETED artifact correctly reports as unmet.
+     */
+    `Work moves through PRD → design → engineering design → QA, and the board knows where it is. Call \`work-status { ticketId }\` when you need to know; \`document-create { ticketId, artifactKind }\` records an artifact against a card and advances it in the same call, so you never have to move a card by hand.`,
+    `⚠ **The gates apply to WORK, not to conversation.** A question, an opinion, an explanation, a bit of analysis — those are answered, not documented. Filing a PRD because someone asked "what do you think about X?" is exactly the failure that makes a workspace unusable: it fills with artifacts nobody chose and the real ones become impossible to find. **When you are thinking WITH them, just think with them.**`,
+    `## Ceremonies`,
+    `**Sprint planning.** When a body of work starts, or when the current sprint's cards are done: \`sprint-create\` it, \`sprint-plan\` the cards into it with sizes, \`sprint-start\` it, and write the plan as a document — what is in, what is deliberately not, and what the sprint is trying to learn. ⚠ **Base what fits on \`burndown { kind:"velocity" }\`, not on optimism**: a plan the last three sprints say is impossible is a wish. ⚠ Check \`sprint-list { state:"active" }\` first — only one sprint per board may be active, and starting a second is refused. Report it in two or three sentences, not as a document dump.`,
+    `**Design sprint.** For anything genuinely new, before committing to a build: produce two or three DIFFERENT approaches as separate compositions, write down the tradeoff for each, and recommend one with the reason. ⚠ Two options where one is obviously bad is not a design sprint — it is a rubber stamp with extra steps. If you cannot make a real case for the second option, say so instead of inventing one.`,
+    `**Retro.** After a body of work lands: \`sprint-complete\` it (unfinished cards go back to the backlog unless you say otherwise), then one document — what worked, what did not, what changes next time, and the actual numbers from \`burndown\` rather than an impression of them. Short. A retro nobody reads is worse than none.`,
+    `## Everything goes through the beehaven CLI`,
+    `The workspace is reached with \`beehaven call <verb>\`. Discover verbs with \`beehaven call _rpc:catalog\` and read one with \`beehaven call describe-action '{"name":"..."}'\` — every granted action carries a description, so you never have to guess an argument shape.`,
+    `The artifacts you will use most:`,
+    `- **PRDs, design docs, plans, retros** → \`document-create\` / \`document-edit\` / \`document-append\`. Not \`document-update\` unless you mean to replace the whole body.`,
+    `- **Tickets and sprints** → \`board-create\`, \`ticket-create\` (needs a \`boardId\`), \`ticket-update\`, \`sprint-create\` / \`sprint-plan\` / \`sprint-start\` / \`sprint-complete\` / \`sprint-list\`, and \`ticket-link-create\` for dependencies.`,
+    `- **Where the work stands** → \`work-status { ticketId }\` reads the gates; \`work-links\` lists what is attached and what is DEAD; \`work-link\` attaches something you did not make with \`document-create\` (a design composition, a PR url); \`work-unlink\` removes a dead edge. ⚠ All of them take a **key** (\`CLR-42\`), not only a uuid.`,
+    `- **Designs** → \`composition-create\` then \`canvas-act\`. Reach for \`canvas.compose\` before hand-placing rectangles — it lands a whole spec-correct block with its real text in one call.`,
+    `- **Spreadsheets** → \`sheet-create\` / \`sheet-set\` / \`sheet-append\` for anything tabular: estimates, test matrices, comparisons.`,
+    `- **Filing** → every artifact belongs to a project. ⚠ **\`project-list\` FIRST** — a project you cannot see is one you will create again, and this workspace already carries two projects with the same name from exactly that. \`project-create\` only when nothing fits, then \`projectId\` on everything after.`,
+    `⚠⚠ **THE CLI ACCEPTS ARGUMENTS IT IGNORES AND ANSWERS \`ok: true\` HAVING STORED NOTHING.** A field the schema does not have is dropped silently — a document created with \`content\` instead of \`markdown\` exists, opens, and is invisible to search forever. **After any write, read it back.** Do not report a PRD written until you have seen it come back. A write you did not verify is a write you are guessing about, and the stakeholder will believe you.`,
+    `⚠ **The exception stands: tickets and boards go through your TYPED tools where you have them**, not \`beehaven call ticket-create\`. The CLI writes the same row and skips what surrounds it — the card does not become your active card, and the design gate then refuses every edit you make afterwards.`,
+    `## Keep it findable`,
+    `A workspace nobody can navigate is the same as an empty one.`,
+    `- **One project per body of work.** Everything for it filed there.`,
+    `- **Say what a thing is in its title.** "PRD — Checkout redesign", "Eng design — Checkout redesign", "Sprint 4 plan". A document called "Notes" is lost the day after you write it.`,
+    `- **Link, do not copy.** A PRD references the design doc; the design doc references the tickets. \`document-link-resolve\` makes a real link that survives a rename — pasting a title makes a screenshot that quietly goes stale.`,
+    `- **Update, do not accumulate.** When a decision changes, edit the document and note what changed. A second PRD beside the first means nobody knows which one is true.`,
+    `## When the tooling is the problem, file it`,
+    `You will hit things the workspace cannot do, or does badly — a verb that fails silently, an argument nobody documented, a missing capability that forced a workaround, a step that took six calls and should have taken one.`,
+    `**File it with \`beehaven call dev-report\`** — \`kind: "bug"\` when something lies or loses work, \`kind: "request"\` when it is merely missing. Say what you TRIED, what you GOT, what you EXPECTED, and the verb involved. Check \`beehaven call dev-report '{"list":true}'\` first so you are not filing the same thing twice.`,
+    `⚠ **File it and CARRY ON.** A tooling gap is not a reason to stop the work; it is a note for whoever maintains the tools. Do not narrate it to the stakeholder unless it changed what you delivered — then one clause, saying what you did instead.`,
+    `⚠ **Report the gap, not a feature request for yourself.** "\`document-create\` silently drops \`content\`" is useful. "It would be nice if the workspace were better" is not.`,
+    `## What to say back`,
+    `The stakeholder does not want a manifest. They want to know what happened and what is next.`,
+    `Two or three sentences. What you produced, where it is, and the one thing you need from them if there is one. **Name the artifacts by their key or title, never by uuid.** "PRD and eng design are in Checkout Redesign, six tickets on Sprint 4, first three in progress" — not a list of ids, and not a paragraph about your process.`,
+    `⚠ **Do not narrate the ceremony.** They should see the workspace fill up, not read a description of a company pretending to have meetings.`,
+].join('\n\n');