beehaven 0.8.16

package/dist/commands/explain.js

@@ -0,0 +1,882 @@
+/**
+ * beehaven explain <action> — schema + examples for one action.
+ *
+ * Where `beehaven actions` lists every action name, `explain` renders
+ * ONE action's input schema, description, and 2-3 example invocations.
+ * Agents call this before `beehaven call <action>` to know what payload
+ * shape to send — no more guessing at field names.
+ *
+ * Strategy:
+ *   1. Try `describe-action` (home Hive exposes this); if the target
+ *      has it, the response includes schema + description + examples.
+ *   2. If the target doesn't have describe-action (unknown-action error),
+ *      fall back to `list-actions --format=full` and filter client-side.
+ *      Every DO with list-actions + the right format flag gives us the
+ *      same data.
+ *   3. If BOTH fail, suggest `beehaven cat /.workspace.json` — the raw
+ *      manifest always carries action schemas.
+ *
+ * Routing: honors the CLI-side target (same as `call` / `actions`).
+ * Explicit --building wins, then file-based target, then legacy daemon
+ * session fallback.
+ */
+import { rpcOnce } from '../ipc-client.js';
+/** Same logic as workspace.ts:getTimeout — inlined to avoid importing the full module. */
+function resolveTimeout(values) {
+    if (values.timeout) {
+        const n = parseInt(values.timeout, 10);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return 30_000;
+}
+// ── Entry ──────────────────────────────────────────────────────────────
+export async function cmdExplain(actionName, values = {}) {
+    if (!actionName) {
+        console.error('  Usage: beehaven explain <action>');
+        console.error('  Example: beehaven explain note-create');
+        console.error('');
+        console.error('  Tip: `beehaven actions` to list every action on the current target.');
+        process.exit(1);
+    }
+    if (!values.json) {
+        const target = values.building ? values.building : 'home';
+        console.error(`\x1b[2m→ ${target}  describe-action ${actionName}\x1b[0m`);
+    }
+    const manifest = await fetchManifest(actionName, values);
+    if (!manifest) {
+        console.error(`  No manifest for action "${actionName}".`);
+        console.error('');
+        console.error('  Try:');
+        console.error('    beehaven actions                  # is this action spelled right?');
+        console.error('    beehaven actions --search ' + actionName);
+        console.error('    beehaven cat /.workspace.json     # raw manifest (always available)');
+        process.exit(1);
+    }
+    if (values.json) {
+        console.log(JSON.stringify(manifest, null, 2));
+        return;
+    }
+    render(manifest);
+}
+// ── Fetch ──────────────────────────────────────────────────────────────
+async function fetchManifest(name, values) {
+    const timeout = resolveTimeout(values);
+    // Strategy 1: describe-action if available (home does).
+    try {
+        const { resolveBuildingForExplain } = await import('./explain-router.js');
+        const resolved = resolveBuildingForExplain('describe-action', { name }, values.building);
+        const raw = await rpcOnce(resolved.action, resolved.input, timeout);
+        const inner = unwrap(raw);
+        if (inner && !inner.error && (inner.name || inner.input || inner.description)) {
+            const m = normalize(inner);
+            return await enrichAlias(m, name, values, timeout);
+        }
+    }
+    catch {
+        // fall through to strategy 2
+    }
+    // Strategy 2: list-actions --format=full + filter.
+    try {
+        const { resolveBuildingForExplain } = await import('./explain-router.js');
+        const resolved = resolveBuildingForExplain('list-actions', { format: 'full' }, values.building);
+        const raw = await rpcOnce(resolved.action, resolved.input, timeout);
+        const inner = unwrap(raw);
+        const actions = inner?.actions ?? (Array.isArray(inner) ? inner : []);
+        const match = actions.find((a) => a.name === name);
+        if (match)
+            return normalize(match);
+    }
+    catch {
+        // fall through
+    }
+    return null;
+}
+/**
+ * ⚠⚠ AN ALIAS ANSWERS WITH A DIFFERENT SCHEMA THAN ITS CANONICAL NAME, SO ASK FOR BOTH (CBH2-18).
+ *
+ * `beehaven actions` LISTS actions under their alias names — `velocity` and `burndown` appear,
+ * `board-report` does not — so the name an agent discovers is exactly the name whose schema is
+ * degraded. One extra round trip on the rare alias path is worth strictly more than a correct
+ * answer that only the undiscoverable name can produce.
+ *
+ * ⚠ ONE EXTRA FETCH, AND ONLY ON AN ALIAS. `isAlias` comes from the server, so the common path
+ * (canonical name) costs nothing and this cannot recurse: the second call asks for the canonical
+ * name, whose own reply has `isAlias: false`.
+ *
+ * ⚠ NON-FATAL BY CONSTRUCTION. Enrichment is a bonus; a daemon hiccup on the second call must
+ * degrade to the alias's own manifest, never to an error. `explain` failing because the *optional*
+ * half of its answer failed would be strictly worse than the bug being fixed.
+ */
+async function enrichAlias(m, requestedName, values, timeout) {
+    if (!m.isAlias || !m.name || m.name === requestedName)
+        return m;
+    try {
+        const { resolveBuildingForExplain } = await import('./explain-router.js');
+        const resolved = resolveBuildingForExplain('describe-action', { name: m.name }, values.building);
+        const raw = await rpcOnce(resolved.action, resolved.input, timeout);
+        const inner = unwrap(raw);
+        if (!inner || inner.error)
+            return m;
+        const canonical = normalize(inner);
+        return {
+            ...m,
+            input: mergeInputSchemas(m.input, canonical.input),
+            // The canonical registration is where a curated description lives, too.
+            description: m.description || canonical.description,
+            examples: m.examples ?? canonical.examples,
+        };
+    }
+    catch {
+        return m;
+    }
+}
+function unwrap(raw) {
+    if (!raw)
+        return null;
+    if (raw.type === 'ack' && raw.result !== undefined)
+        return raw.result;
+    if (raw.result !== undefined)
+        return raw.result;
+    return raw;
+}
+function normalize(raw) {
+    return {
+        name: raw.name ?? '',
+        description: raw.description,
+        category: raw.category,
+        aliases: Array.isArray(raw.aliases) ? raw.aliases : undefined,
+        input: raw.input ?? raw.inputSchema ?? raw.schema,
+        output: raw.output ?? raw.outputSchema,
+        examples: Array.isArray(raw.examples) ? raw.examples : undefined,
+        requested: typeof raw.requested === 'string' ? raw.requested : undefined,
+        isAlias: raw.isAlias === true ? true : undefined,
+    };
+}
+/**
+ * ⚠⚠ ONE ACTION, TWO PARTIAL SCHEMAS — MERGED PER PROPERTY, NOT PER ACTION (CBH2-18).
+ *
+ * `board-report` is reachable under four names, and the server answers each with a DIFFERENT
+ * subset of one schema. Measured live on staging:
+ *
+ *     explain board-report  →  kind: { type:'string', description:'velocity | burndown | …' }
+ *     explain velocity      →  kind: { type:'string', enum:['velocity','burndown',…] }
+ *
+ * So it is NOT simply that the alias is degraded — each NAME carries something the other lacks.
+ * The canonical name has the curated prose; the alias has the derived `enum`. A fix that merely
+ * preferred the canonical would recover the descriptions and still throw the enum away, i.e. fix
+ * the ticket and keep half the bug.
+ *
+ * ⚠ THE MERGE IS PER PROPERTY KEY, and that is the whole point. A whole-object
+ * `{...canonical, ...alias}` lets one side's `{type:'string'}` shadow the other side's
+ * `description` — the exact per-action-vs-per-field mistake `ACTION_INPUT_SCHEMAS` records making
+ * on `sheet-get`, where curation won outright and hid two working fields.
+ *
+ * ⚠ `required` IS UNIONED. Neither side is a superset: curation marks what it knows, the
+ * derivation marks what each handler's own "<field> is required" refusal proves.
+ *
+ * ⚠ NOT A GUESS WHEN EITHER SIDE IS NOT A JSON SCHEMA. A raw Zod descriptor map has no
+ * `properties`, so there is no key-wise merge to do; return the richer side untouched rather than
+ * inventing a shape neither server sent.
+ */
+function mergeInputSchemas(requested, canonical) {
+    const isObj = (v) => !!v && typeof v === 'object';
+    if (!isObj(requested))
+        return canonical;
+    if (!isObj(canonical))
+        return requested;
+    const rp = requested.properties;
+    const cp = canonical.properties;
+    // One of them is not a JSON Schema (raw Zod map / field map) — do not invent a union.
+    if (!isObj(rp) || !isObj(cp))
+        return isObj(rp) ? requested : canonical;
+    const properties = {};
+    for (const key of new Set([...Object.keys(cp), ...Object.keys(rp)])) {
+        const rv = rp[key];
+        const cv = cp[key];
+        if (!isObj(rv) || !isObj(cv)) {
+            properties[key] = rv ?? cv;
+            continue;
+        }
+        // Requested wins on shared keys (it is the derived, complete-from-the-handler side)…
+        const merged = { ...cv, ...rv };
+        // …EXCEPT the description, which is the curated half and the reason to merge at all.
+        const prose = [cv?.description, rv?.description].find((d) => typeof d === 'string' && d.trim() !== '');
+        if (prose)
+            merged.description = prose;
+        else
+            delete merged.description;
+        properties[key] = merged;
+    }
+    const required = [
+        ...new Set([
+            ...(Array.isArray(canonical.required) ? canonical.required : []),
+            ...(Array.isArray(requested.required) ? requested.required : []),
+        ]),
+    ];
+    return {
+        ...canonical,
+        ...requested,
+        properties,
+        ...(required.length ? { required } : {}),
+    };
+}
+// ── Render ─────────────────────────────────────────────────────────────
+function render(m) {
+    console.log('');
+    console.log(`  ${bold(m.name)}${m.category ? dim(`  [${m.category}]`) : ''}`);
+    if (m.description) {
+        console.log(indent(m.description));
+    }
+    console.log('');
+    // Aliases — quick scan row for agents
+    if (m.aliases && m.aliases.length > 0) {
+        console.log(`  ${bold('Also called')}  ${m.aliases.join(', ')}`);
+        console.log('');
+    }
+    // Input schema.
+    //
+    // ABSENCE IS NOT EMPTINESS. This printed "none (empty object)" whenever the manifest carried
+    // no schema — a positive claim that the action takes no arguments. 731 of 802 actions on the
+    // workspace register without a zod input (`defineApp(name, { run })` is the common form), so
+    // the CLI was telling an agent "this takes nothing" about 91% of the surface, including
+    // `ticket-create`, which requires projectId AND title.
+    //
+    // The server is not at fault: `describe-action` returns `input: null` for undeclared and a
+    // real object for declared. Only the renderer conflated them.
+    if (m.input && Object.keys(m.input).length > 0) {
+        console.log(`  ${bold('Input')}`);
+        renderSchema(m.input);
+        console.log('');
+    }
+    else {
+        console.log(`  ${bold('Input')}  ${dim('not declared — the description above carries the shape')}`);
+        console.log('');
+    }
+    // Output schema
+    if (m.output && Object.keys(m.output).length > 0) {
+        console.log(`  ${bold('Output')}`);
+        renderSchema(m.output);
+        console.log('');
+    }
+    // Examples
+    if (m.examples && m.examples.length > 0) {
+        console.log(`  ${bold('Examples')}`);
+        for (const ex of m.examples) {
+            if (typeof ex === 'string') {
+                console.log(`    beehaven call ${m.name} '${ex}'`);
+            }
+            else {
+                const input = typeof ex.input === 'string' ? ex.input : JSON.stringify(ex.input);
+                console.log(`    beehaven call ${m.name} '${input}'`);
+                if (ex.note)
+                    console.log(`      ${dim('# ' + ex.note)}`);
+            }
+        }
+        console.log('');
+    }
+    else if (m.input && Object.keys(m.input).length > 0) {
+        // Synthesize a minimal example — but ONLY from a real schema. With no schema this
+        // synthesized `{}`, printing `beehaven call ticket-create '{}'` under the heading
+        // "Example": a copy-pasteable line that is guaranteed to fail. A fabricated example is
+        // worse than none, because it reads as verified.
+        const minimal = synthMinimalInput(m.input);
+        /**
+         * ⚠ AN EMPTY SYNTHESIS MEANS "we could not tell which fields are required" — print NOTHING
+         * rather than `'{}'`. `beehaven call ticket-create '{}'` under a heading that says "Example"
+         * is a copy-pasteable line guaranteed to fail, which is the case this block's own comment
+         * above was written for. The schema is rendered directly above; that is the honest answer.
+         */
+        if (Object.keys(minimal).length > 0) {
+            for (const line of exampleBlock(m.name, minimal))
+                console.log(line);
+            console.log('');
+        }
+    }
+    console.log(`  ${dim('Call it:')}  beehaven call ${m.name} '<json>'`);
+    console.log('');
+}
+/**
+ * The pure half of `renderSchema`: schema in, rows out. `null` means "not a field map" — the two
+ * degenerate cases the caller prints as `(opaque schema)` / the raw JSON.
+ */
+function schemaRows(schema) {
+    if (!schema || typeof schema !== 'object')
+        return null;
+    // Zod-like nested: { shape: {...}, _def: {...} }
+    const fields = schema.shape ?? schema.properties ?? schema;
+    if (typeof fields !== 'object' || fields === null)
+        return null;
+    const entries = Object.entries(fields);
+    /**
+     * ⚠⚠ `required` LIVES ON THE SCHEMA, NOT ON THE FIELD — AND THIS DROPPED IT ENTIRELY (CBH2-11).
+     *
+     * `describeField` decides requiredness from `raw.optional`, which is the shape of our own
+     * `FieldSchema` (`{ type: 'string', optional: true }`). JSON Schema does not mark fields at all;
+     * it lists required NAMES in a sibling array. So for every JSON-Schema action `raw.optional` was
+     * `undefined`, `!undefined` was `true`, and the "optional" label never printed — every field
+     * rendered identically whether it was mandatory or not.
+     *
+     * ⚠ THE SERVER WAS SENDING IT THE WHOLE TIME. `describe-action { name: 'sprint-create' }`
+     * returns `required: ['boardId']`; only the renderer discarded it. And 614 fields across the
+     * derived map were promoted to `required` by reading each handler's own "<field> is required"
+     * refusal — all of that work was invisible at the one door agents are told to use.
+     *
+     * ⚠ MARKED POSITIVELY ("required"), NOT BY ABSENCE. With a JSON Schema the required set is the
+     * small, actionable one, and the old rendering made an unmarked field read as mandatory — the
+     * dangerous direction, because a caller who believes everything is required supplies junk for
+     * fields they should have omitted.
+     *
+     * ⚠ BOTH SHAPES STILL WORK: a sibling `required[]` wins where present; otherwise the per-field
+     * `optional` flag is honoured exactly as before, so nothing that rendered correctly changes.
+     */
+    const requiredNames = Array.isArray(schema?.required)
+        ? new Set(schema.required.map(String))
+        : null;
+    const alts = aliasGroups(schema);
+    return entries.map(([name, desc]) => {
+        const { type, required, hint } = describeField(desc);
+        /**
+         * ⚠⚠ THE ALIAS `required[]` CANNOT NAME (CBH2-91). 60 actions open
+         * `const compId = input.compositionId || input.id;` and refuse with the bare
+         * `'compositionId required'` — the refusal names ONE field, the code accepts EITHER. So `id`
+         * rendered as plain `optional` beside a required `compositionId`, which is not wrong about
+         * `compositionId` and says nothing at all about the alias.
+         *
+         * ⚠ THE ROW'S required/optional COLUMN IS UNTOUCHED, and that is deliberate. The deriver keeps
+         * `compositionId` in `required[]` because following it always produces a working call; a
+         * suppression that marked NEITHER was built, measured on 47 actions and removed. What was
+         * missing was only that `id` works too, and a hint is where that belongs — a third value in
+         * the required column would also overflow the 12-char pad every other row is aligned to.
+         */
+        const others = altsFor(alts, name);
+        const aliasHint = others.length
+            ? `${others.length === 1 ? 'or' : 'or one of'} \`${others.join('`, `')}\``
+            : null;
+        return {
+            name,
+            type,
+            required: requiredNames ? requiredNames.has(name) : required,
+            hint: [hint, aliasHint].filter(Boolean).join('  ') || undefined,
+        };
+    });
+}
+/**
+ * The alias disjunctions a schema declares: each group is a set of field names of which any one
+ * satisfies the same slot.
+ *
+ * ⚠ BOTH ENCODINGS. One disjunction is a top-level `anyOf`; several INDEPENDENT ones are an
+ * `allOf` of `anyOf`s, because flattening two groups into one `anyOf` would read as "any one of
+ * these five fields", a different and false claim. The deriver emits whichever fits; a reader that
+ * knew only `anyOf` would silently see nothing on `session-note-add`.
+ */
+function aliasGroups(schema) {
+    const groups = [];
+    const take = (anyOf) => {
+        if (!Array.isArray(anyOf))
+            return;
+        const names = anyOf
+            .map((b) => (Array.isArray(b?.required) && b.required.length === 1 ? String(b.required[0]) : null))
+            .filter((n) => !!n);
+        if (names.length > 1)
+            groups.push(names);
+    };
+    take(schema?.anyOf);
+    if (Array.isArray(schema?.allOf))
+        for (const part of schema.allOf)
+            take(part?.anyOf);
+    return groups;
+}
+function altsFor(groups, name) {
+    const out = new Set();
+    for (const g of groups)
+        if (g.includes(name))
+            for (const n of g)
+                if (n !== name)
+                    out.add(n);
+    return [...out];
+}
+/** The formatting half: rows in, printable lines out (padding + colour, no I/O). */
+function formatSchemaRows(rows, indent = '    ') {
+    if (rows.length === 0)
+        return [`${indent}${dim('(empty)')}`];
+    const maxNameW = Math.min(30, Math.max(...rows.map((r) => r.name.length)));
+    return rows.map((r) => {
+        const nameCol = r.name.padEnd(maxNameW + 2);
+        const typeCol = r.type.padEnd(12);
+        /**
+         * ⚠ PAD THE VISIBLE TEXT, THEN COLOUR IT. `dim()` wraps the string in ANSI escapes, which
+         * `padEnd` counts as characters — so padding the coloured string mis-aligns every dimmed cell
+         * against every undimmed one. Width first, colour second.
+         */
+        /**
+         * ⚠ MARK BOTH WAYS ALWAYS. The fallback branch printed '' for required, so an action with a
+         * `required[]` said "required" and one without said nothing — two renderings of the same fact,
+         * and the blank one is indistinguishable from "we don't know".
+         */
+        const reqText = r.required ? 'required' : 'optional';
+        const padded = ('  ' + reqText).padEnd(12);
+        const reqLabel = reqText === 'optional' ? dim(padded) : padded;
+        const hintLabel = r.hint ? `  ${dim('# ' + r.hint)}` : '';
+        return `${indent}${nameCol}${typeCol}${reqLabel}${hintLabel}`;
+    });
+}
+function renderSchema(schema, indent = '    ') {
+    const rows = schemaRows(schema);
+    if (rows === null) {
+        const isObj = !!schema && typeof schema === 'object';
+        console.log(`${indent}${dim(isObj ? JSON.stringify(schema) : '(opaque schema)')}`);
+        return;
+    }
+    for (const line of formatSchemaRows(rows, indent))
+        console.log(line);
+}
+/**
+ * ⚠⚠ THE IMPLEMENTATION'S TYPE NAMES LEAKED INTO THE PRODUCT (CBH2-31).
+ *
+ * The server answers "what does this take" in TWO shapes, and the renderer printed each one's
+ * vocabulary verbatim — so the same question got two visibly different answers:
+ *
+ *     explain document-edit    →  id     string      required   # The documentId…
+ *     explain document-create  →  title  ZodString?  optional
+ *
+ * `ZodString?` is a zod INTERNAL, produced by `_describeInputSchema`'s walk of the registration.
+ * A caller reading it learns our validator library, not their argument type — and the trailing `?`
+ * duplicates, in a second notation, the requiredness the row already states in words.
+ *
+ * ⚠ THE `_def` BRANCH WAS ALREADY CORRECT and this is why the split was easy to miss: it does
+ * `replace(/^Zod/,'').toLowerCase()`, so it has always emitted `string`. Only the STRING-descriptor
+ * branch — the one the live server actually sends — passed the name through untouched.
+ *
+ * ⚠ ANCHORED ON `Zod` + AN UPPERCASE LETTER, so a user type that merely starts with those three
+ * characters is left alone. A blanket `/^Zod/` turns a field typed `Zodiac` into `iac`.
+ *
+ * ⚠ THE FALLBACK IS STRIP-AND-LOWERCASE, NOT `unknown`. An unmapped zod type still reads better as
+ * its own lowercased name (`ZodOptional` → `optional`) than as a word that claims we know nothing.
+ */
+const ZOD_TYPE_ALIASES = {
+    bigint: 'number',
+    nativeenum: 'enum',
+    record: 'object',
+    tuple: 'array',
+};
+function normalizeTypeName(raw) {
+    const m = /^Zod([A-Z].*)$/.exec(raw);
+    if (!m)
+        return raw;
+    const bare = m[1].toLowerCase();
+    return ZOD_TYPE_ALIASES[bare] ?? bare;
+}
+/**
+ * ⚠⚠ THE ENUM WAS IN THE SCHEMA AND ON NEITHER LINE OF THE OUTPUT (CBH2-33).
+ *
+ * `canvas-align-blocks.axis` arrives as `{ type:'string', enum:['left','center-h',…] }`. The row
+ * printed `axis  string  required` and the Example printed `"axis":"example"` — so the six legal
+ * values were dropped from the description AND from the one line built to be pasted. Everything
+ * needed to be right was already in hand.
+ */
+function fieldEnum(raw) {
+    const e = raw?.enum ?? raw?.enumValues;
+    if (Array.isArray(e) && e.length > 0)
+        return e.map(String);
+    return undefined;
+}
+function describeField(raw) {
+    if (typeof raw === 'string') {
+        /**
+         * ⚠⚠ THE TRAILING `?` IS THE OPTIONALITY MARKER AND THIS DISCARDED IT (CBH2-11 / CBH2-16).
+         *
+         * The server renders a zod field as the string `"ZodString?"` — `_describeInputSchema` appends
+         * `?` for `ZodOptional`/`ZodDefault`. This branch returned `required: true` unconditionally, so
+         * every raw-Zod action printed all fields as required and `synthMinimalInput` put all of them
+         * in the example. That is why `explain composition-create` still listed eight fields after the
+         * first fix: `fieldsDeclareOptionality` saw string descriptors and believed optionality was
+         * knowable, while this function could not read it.
+         *
+         * ⚠ FOUND BY A REVIEWER EXECUTING THE CODE, not by reading it — and it is one root cause under
+         * two tickets. The `?` was in the data the whole time.
+         */
+        const optional = raw.endsWith('?');
+        return { type: normalizeTypeName(optional ? raw.slice(0, -1) : raw), required: !optional };
+    }
+    if (!raw || typeof raw !== 'object') {
+        return { type: 'unknown', required: true };
+    }
+    // Our FieldSchema shape: { type: 'string', optional: true, default?: ... }
+    if (raw.type) {
+        const enumValues = fieldEnum(raw);
+        return {
+            type: normalizeTypeName(String(raw.type)),
+            required: !raw.optional,
+            // ⚠ PROSE FIRST, ENUM AS THE FALLBACK. A curated description usually spells the options out
+            // already ("velocity | burndown | cycle-time | summary"), so printing both is one fact twice.
+            hint: raw.description || (enumValues ? enumValues.join(' | ') : undefined),
+            enumValues,
+        };
+    }
+    // Zod-ish: { _def: { typeName: 'ZodString' } }
+    if (raw._def) {
+        const tn = raw._def.typeName ?? 'unknown';
+        const type = normalizeTypeName(tn);
+        const required = tn !== 'ZodOptional' && tn !== 'ZodDefault';
+        return { type, required };
+    }
+    return { type: 'object', required: true, hint: 'nested — see --json' };
+}
+/**
+ * ⚠⚠ THE "MINIMAL" EXAMPLE WAS NEITHER MINIMAL NOR RUNNABLE (CBH2-16).
+ *
+ * Two defects, one root cause shared with the required-field bug above:
+ *
+ *  1. IT INCLUDED EVERY FIELD. Requiredness came from `describeField().required`, which reads a
+ *     per-field `optional` flag that JSON Schema does not have — so `!undefined` was `true` and
+ *     nothing was filtered. `document-create`'s example listed eight fields including `html`,
+ *     `markdown`, `content`, `body` and `text`, which are MUTUALLY EXCLUSIVE spellings of one
+ *     argument. Pasting it asks for five bodies at once.
+ *  2. UNKNOWN TYPES BECAME `null`. `sampleValue` fell through to `null`, producing
+ *     `{"title":null,"data":null,…}` — printed under a heading that says "Example", above a line
+ *     that says "Call it:". Measured in `agent_activity` during this sprint: an agent pasted one
+ *     and got `unknown kind 'example'` back.
+ *
+ * ⚠ AN UNRUNNABLE EXAMPLE IS WORSE THAN NO EXAMPLE. No example makes a caller read the schema; a
+ * broken one makes them run it, and on a WRITE verb that means a junk artifact in the workspace.
+ */
+function synthMinimalInput(schema) {
+    if (!schema || typeof schema !== 'object')
+        return {};
+    const fields = schema.shape ?? schema.properties ?? schema;
+    if (typeof fields !== 'object' || fields === null)
+        return {};
+    // ⚠ The sibling `required[]` is the real answer when present — see `renderSchema`.
+    const requiredNames = Array.isArray(schema.required)
+        ? new Set(schema.required.map(String))
+        : null;
+    /**
+     * ⚠⚠ NO `required[]` MEANS WE CANNOT TELL — SO DO NOT CLAIM A MINIMAL EXAMPLE.
+     *
+     * Without it every field looked required, so the "minimal" example listed ALL of them. On
+     * `document-create` that is `html`, `markdown`, `content`, `body` AND `text` — five MUTUALLY
+     * EXCLUSIVE spellings of one argument, printed as a single copy-pasteable line. That is not a
+     * minimal example, it is an incorrect call rendered under a heading that says "Example".
+     *
+     * ⚠ Returning `{}` here makes the caller fall through to NO example block at all, which is what
+     * this file already argues for elsewhere: "A fabricated example is worse than none, because it
+     * reads as verified." The schema is printed directly above; it is the honest answer.
+     */
+    /**
+     * ⚠⚠ THREE CASES, AND COLLAPSING THEM IS A REGRESSION EITHER WAY. A first cut returned `{}`
+     * whenever there was no `required[]` — which is right for a JSON Schema and WRONG for our own
+     * FieldSchema shape, where requiredness is genuinely knowable from a per-field `optional` flag.
+     * It silently removed the example from every FieldSchema action. Caught by the existing suite.
+     */
+    const entries = Object.entries(fields);
+    const fieldsDeclareOptionality = entries.some(([, d]) => typeof d === 'string' || (d && typeof d === 'object' && 'optional' in d));
+    // Neither source of truth: a JSON Schema with no `required[]` and no per-field flags. We cannot
+    // tell, so we do not guess — see the caller, which then prints no Example at all.
+    if (!requiredNames && !fieldsDeclareOptionality)
+        return {};
+    const out = {};
+    for (const [name, desc] of entries) {
+        const { required } = describeField(desc);
+        const isRequired = requiredNames ? requiredNames.has(name) : required;
+        /**
+         * ⚠⚠ AN AUTHOR-SUPPLIED `example` OUTRANKS REQUIREDNESS (CBH2-97).
+         *
+         * `board-update` and `ticket-update` LIFT a flat call into `updates`, so `updates` is genuinely
+         * not required — and dropping it from `required[]` (the honest schema) also dropped it from the
+         * example, leaving `'{"id":"example"}'`: a copy-pasteable call that answers `changed: false`.
+         * A confident no-op, which is the very class CBH2-57 exists for.
+         *
+         * A field carrying an explicit `example` is an author saying "put THIS here" — a stronger
+         * statement than requiredness, and the only way to show a working shape for a field the schema
+         * correctly marks optional. `sampleValue` already prefers `example` over everything else; this
+         * is what lets the field reach it.
+         *
+         * ⚠ ZERO BLAST RADIUS AT THE TIME OF WRITING, MEASURED: 0 of 414 curated properties carried
+         * `example`, `default` or `const`, so nothing that prints an Example today changes shape. Only
+         * `default`/`const` are deliberately NOT honoured here — a default is what the handler would
+         * have used anyway, so putting it in a "minimal" example adds noise rather than meaning.
+         */
+        const carriesExample = !!desc && typeof desc === 'object' && 'example' in desc;
+        if (!isRequired && !carriesExample)
+            continue;
+        /**
+         * ⚠ THE WHOLE DESCRIPTOR, NOT ITS TYPE. This passed `type` — a lowercase string — so `enum`,
+         * `default` and `const` were unreachable from here and every constrained field got the
+         * `"example"` placeholder that its own schema forbids (CBH2-33).
+         */
+        out[name] = sampleValue(desc);
+    }
+    return out;
+}
+/**
+ * ⚠⚠ THE EXAMPLE WAS WELL-FORMED, RUNNABLE, AND STILL WROTE JUNK INTO THE GALLERY (CBH2-57).
+ *
+ * CBH2-15/16/33 fixed everything that made the printed line INVALID — the `null` values, the
+ * eight-mutually-exclusive-fields "minimal" example, the `"example"` string in a required enum.
+ * Swept across all 1,115 derived schemas on 2026-09-06: **591 print an Example and every one of
+ * them now satisfies its own schema** — 0 missing-required, 0 illegal enum, 0 type mismatch, 0
+ * nulls. The generator is correct.
+ *
+ * ⚠⚠ AND THE ORIGINAL HARM SURVIVED ALL OF IT, because it was never about validity. The ticket is
+ * titled *"prints a runnable example that writes junk into the gallery"*, and a hunter created a
+ * real card, `PLA-3517`, by pasting one. `beehaven call composition-create '{"title":"example"}'`
+ * is a perfectly valid call that puts a composition named "example" in someone's workspace. Making
+ * it valid made it MORE likely to be run, not less.
+ *
+ * So the fix is at the render, not the generator: a mutating verb's example is presented as a
+ * SHAPE, and the line says what running it verbatim would create. The reader keeps the exact call
+ * form — which is the whole value of an example to an agent — and loses the invitation.
+ *
+ * ⚠ IT IS A NAME-SHAPE HEURISTIC AND IT SAYS SO. There is no `mutates: true` on a registration to
+ * read, and inventing one for ~1,100 actions is a different ticket. The failure modes are
+ * asymmetric and that is what makes a heuristic acceptable here: a false POSITIVE prints a caution
+ * on a harmless read (noise), a false NEGATIVE prints an unmarked write (the bug). So the list
+ * leans inclusive, and `explain` is a documentation surface where over-cautioning costs nothing.
+ *
+ * ⚠ MATCHED ON WORD BOUNDARIES INSIDE A HYPHENATED NAME, never as a substring. `document-restore`
+ * must match `restore`; `board-report` must NOT match on `report` containing no verb at all, and —
+ * the case that actually bites — `note-content-seed` must not be missed because the verb is last
+ * while `list-actions` must not be caught because `list` is first. Splitting on `-`/`:` and testing
+ * each segment is what makes both come out right.
+ */
+const MUTATING_SEGMENTS = new Set([
+    'create', 'new', 'add', 'insert', 'append', 'seed', 'write', 'update', 'patch', 'edit', 'set',
+    'rename', 'move', 'copy', 'duplicate', 'delete', 'remove', 'destroy', 'purge', 'empty', 'clear',
+    'archive', 'restore', 'revert', 'rollback', 'rewind', 'undo', 'redo', 'send', 'publish', 'post',
+    'upload', 'import', 'export', 'generate', 'draw', 'record', 'revoke', 'grant', 'approve',
+    'reject', 'decide', 'start', 'stop', 'complete', 'cancel', 'reset', 'repair', 'backfill',
+    'migrate', 'sync', 'install', 'uninstall', 'register', 'link', 'unlink', 'invite', 'admit',
+    'evict', 'assign', 'toggle', 'pin', 'unpin', 'star', 'snooze', 'mark', 'takeover', 'upgrade',
+    'downgrade', 'topup', 'checkout', 'claim', 'compact', 'vacuum', 'reap', 'apply', 'commit',
+    /**
+     * ⚠ ADDED FROM THE MEASURED "unknown" BUCKET (CBH2-96), each against a real action rather than
+     * from imagination: `agent-memory-forget`/`-remember`, `agent-slug-rotate`,
+     * `avatar:honey-spend`, `avatar:champion-unlock`, `avatar:accessory-equip`/`-unequip`,
+     * `admin:broadcast`, `admin:migration-run`, `_mcp-oauth-finalize`, `agent-mint-token`,
+     * `agent-session-end`, `agent-sandbox-exec`, `avatar:bootstrap`. Adding a segment is only safe
+     * when it names a verb that WRITES — every entry here moves actions out of "cannot tell" and
+     * into a positive claim, so a wrong one is the false-positive noise the list tolerates, but a
+     * word that is usually a noun (`report`, `session`) would move reads too.
+     */
+    'forget', 'remember', 'rotate', 'spend', 'unlock', 'equip', 'unequip', 'broadcast', 'finalize',
+    'mint', 'end', 'bootstrap', 'run', 'exec',
+]);
+/**
+ * ⚠⚠ THE THIRD STATE: A NAME THAT CARRIES NO VERB AT ALL (CBH2-96).
+ *
+ * The classifier was a boolean over `MUTATING_SEGMENTS`, so every name it did not recognise fell
+ * into the SAFE bucket — and CBH2-96 names that blind spot exactly: *"a verb whose name carries no
+ * verb at all is still invisible to it"*. Measured across all 1,115 derived actions: 468 named a
+ * write and **647 did not** — and of those, only 320 name a READ. The other **327, 29% of the
+ * surface, named neither and were silently filed as harmless.** The bucket is not a corner:
+ * `agent-memory-forget`, `avatar:honey-spend`, `admin:broadcast`, `admin:migration-run`, `Bash`
+ * and `MultiEdit` were all in it. After the segments added below it is 500 / 320 / 295.
+ *
+ * ⚠⚠ THE DECISION, since CBH2-96 asks for one: KEEP THE HEURISTIC, STOP OVERSTATING IT, AND STOP
+ * DEFAULTING TO SAFE. A declared `mutates: true` on the registration is the real fix and remains
+ * the right one — it would also let `_rpc:catalog` report it and let the CLI's spend gate reason
+ * about it — but it is ~1,100 registrations across files this change does not own, and half of it
+ * (some declared, the rest inferred) is worse than either: a reader cannot tell which verbs were
+ * declared, so an unmarked write still reads as a checked one.
+ *
+ * What was actually wrong was not the inference, it was the CLAIM. The line asserted
+ * `⚠ <action> WRITES` — a fact a name test cannot establish — so a false positive was not merely
+ * noise, it was a confident wrong statement about someone's data. Three states, each saying only
+ * what it knows:
+ *
+ *     write    reads as a write verb  →  say so, and say it is read from the name
+ *     read     reads as a read verb   →  no caution
+ *     unknown  neither                →  say we cannot tell
+ *
+ * ⚠ The asymmetry that makes a heuristic acceptable is unchanged and now applies to the third
+ * state too: over-cautioning on a documentation surface costs a line of text, and an unmarked
+ * write costs someone real workspace data.
+ */
+const READ_SEGMENTS = new Set([
+    'list', 'get', 'search', 'read', 'find', 'show', 'describe', 'explain', 'status', 'report',
+    'stats', 'diff', 'history', 'count', 'counts', 'info', 'catalog', 'perceive', 'look', 'preview',
+    'brief', 'log', 'logs', 'map', 'summary', 'view', 'inspect', 'query', 'check', 'ask', 'recall',
+    'resolve', 'actions', 'items', 'members', 'columns', 'comments', 'links', 'tree', 'ls', 'cat',
+    'grep', 'glob', 'peek', 'fetch', 'estimate', 'validate', 'verify', 'compare', 'suggest',
+    'recent', 'feed', 'usage', 'quota', 'whoami', 'ping', 'health', 'schema', 'sql', 'stat',
+]);
+/**
+ * ⚠ WRITE WINS A TIE. `document-list` is a read and `note-content-seed` is a write; a name holding
+ * both kinds of segment (`board-report-export`) is a write, because that is the direction whose
+ * failure costs data.
+ */
+export function classifyExample(action) {
+    const segs = String(action ?? '').toLowerCase().split(/[-:._]/);
+    if (segs.some((s) => MUTATING_SEGMENTS.has(s)))
+        return 'write';
+    if (segs.some((s) => READ_SEGMENTS.has(s)))
+        return 'read';
+    return 'unknown';
+}
+/**
+ * ⚠ KEPT AS THE BOOLEAN FACE OF `classifyExample`, never a second implementation. Existing guards
+ * assert on it in both directions (`note-content-seed` caught, `list-actions` and `board-report`
+ * not), and two independent name tests are exactly how the renderer and its guard drift apart.
+ */
+export function exampleMutates(action) {
+    return classifyExample(action) === 'write';
+}
+/**
+ * The Example block, as LINES — pure, so a guard can assert what is printed without a terminal.
+ *
+ * ⚠⚠ RETURNING LINES RATHER THAN PRINTING IS THE POINT. `render` is `void` and talks to
+ * `console.log`, and this file's own history (CBH2-25) is guards that read it as TEXT and called
+ * themselves behavioural: "a reviewer broke the fix in one line and they stayed green". A guard
+ * still has to prove `render` CALLS this — a correct helper nobody calls proves nothing — so the
+ * suite captures `console.log` around the real `render` as well as unit-testing this.
+ */
+export function exampleBlock(action, minimal) {
+    const call = `    beehaven call ${action} '${JSON.stringify(minimal)}'`;
+    const risk = classifyExample(action);
+    /**
+     * ⚠⚠ THE HEADING IS THE SAME FOR EVERY RISK CLASS — CBH2-17, AND THE READ BRANCH IS WHY.
+     *
+     * It used to return `[bold('Example'), call]` for a read: one heading, two behaviours, and the
+     * unlabelled half is the one the ticket copy-pasted. `beehaven call document-get
+     * '{"id":"example"}'` under a bare heading that says "Example" answers `document not found`.
+     *
+     * ⚠⚠ THE LABEL IS THE FIX, NOT A BETTER VALUE, AND THAT IS NOT A PREFERENCE — it is forced.
+     * An `id` names one row in one workspace, so there is no generic value that could stand in for
+     * it; ANY placeholder a synthesizer picks must fail. CBH2-15/16/33 already made these lines
+     * VALID against their own schemas (591 of 1,115 print one, all valid) and validity was never the
+     * complaint. A line that parses, type-checks and fails is exactly the shape that reads as a
+     * working invocation.
+     *
+     * ⚠ THE *CAUTION* STAYS DIFFERENTIATED, AND THE OLD GUARD'S ARGUMENT FOR THAT IS UNTOUCHED:
+     * "a caution on every row is a caution nobody reads". That argument is about the CONSEQUENCE
+     * line — a write creates real data, a read merely fails — and none of it applies to a statement
+     * about what the values ARE. Reads carry the heading and no third line.
+     */
+    const heading = `  ${bold('Example')}  ${dim('— SHAPE ONLY. The values are placeholders, not a suggestion.')}`;
+    if (risk === 'read')
+        return [heading, call];
+    const caution = risk === 'write'
+        ? `⚠ ${action} reads as a WRITE verb (inferred from its name). Run this verbatim and you create real workspace data named "example".`
+        : `⚠ ${action}'s name says neither read nor write, so this cannot tell you which it is. Check before running it verbatim — if it writes, you create real workspace data named "example".`;
+    return [heading, call, `    ${dim(caution)}`];
+}
+/**
+ * ⚠⚠ IT ONLY EVER SAW A TYPE NAME, SO IT COULD NOT HAVE BEEN RIGHT (CBH2-33).
+ *
+ * `synthMinimalInput` called `sampleValue(type)` — a single lowercase string — and threw the rest
+ * of the field descriptor away. Everything that makes a value LEGAL rather than merely
+ * well-typed lives in the part that was discarded: `enum`, `default`, `const`, `example`. So a
+ * constrained field could only ever be filled with a placeholder that the handler must reject:
+ *
+ *     explain canvas-align-blocks  →  '{"blockIds":[],"axis":"example"}'
+ *     …while the schema says        axis: enum ['left','center-h','right','top','center-v','bottom']
+ *
+ * 23 required-enum fields across the derived map were emitting a guaranteed-invalid example.
+ *
+ * ⚠ IT STILL ACCEPTS A BARE TYPE STRING. That is the FieldSchema path and three existing tests
+ * pin it; a previous pass on this file regressed exactly that surface. `string | descriptor`
+ * keeps the old contract byte-for-byte and adds the new one beside it.
+ *
+ * ⚠ ORDER: `example` → `default` → `const` → `enum[0]` → type. An author-supplied value outranks
+ * anything synthesized, and a declared default is what the handler would have used anyway.
+ * `enum[0]` is last of the real values because it is arbitrary among the legal ones — but arbitrary
+ * AND legal beats `"example"`, which is neither.
+ */
+function sampleValue(field) {
+    if (field !== null && typeof field === 'object') {
+        if (field.example !== undefined)
+            return field.example;
+        if (Array.isArray(field.examples) && field.examples.length > 0)
+            return field.examples[0];
+        if (field.default !== undefined)
+            return field.default;
+        if (field.const !== undefined)
+            return field.const;
+        const e = fieldEnum(field);
+        if (e)
+            return e[0];
+        return sampleValue(describeField(field).type);
+    }
+    /**
+     * ⚠ THE STRING PATH GOES THROUGH `describeField` TOO, or the zod spelling silently degrades.
+     * The live server sends `"ZodNumber?"`, which matches no case below and would fall through to
+     * the `'example'` default — a STRING placeholder in a numeric field, which is the first of the
+     * three defects CBH2-33 reports. One vocabulary in, one vocabulary out.
+     */
+    const type = typeof field === 'string' ? describeField(field).type : 'unknown';
+    switch (type.toLowerCase()) {
+        case 'string':
+            return 'example';
+        case 'number':
+        case 'real':
+        case 'float':
+            return 0;
+        case 'int':
+        case 'integer':
+            return 0;
+        case 'boolean':
+        case 'bool':
+            return true;
+        case 'array':
+            return [];
+        case 'object':
+        case 'json':
+            return {};
+        case 'date':
+            return new Date().toISOString();
+        default:
+            /**
+             * ⚠ NEVER `null`. An unrecognised type used to fall through to null, which renders as
+             * `{"title":null}` — a value that reads as "explicitly blank" rather than "we did not know",
+             * and which several handlers accept and store. A placeholder string is obviously a
+             * placeholder; `null` is obviously nothing, and the two are not confusable in a paste.
+             */
+            return 'example';
+    }
+}
+// ── format helpers ─────────────────────────────────────────────────────
+function bold(s) {
+    return `\x1b[1m${s}\x1b[0m`;
+}
+function dim(s) {
+    return `\x1b[2m${s}\x1b[0m`;
+}
+function indent(s) {
+    return s
+        .split('\n')
+        .map((l) => '  ' + l.trim())
+        .join('\n');
+}
+/**
+ * Exposed for tests.
+ *
+ * ⚠⚠ `schemaRows` / `formatSchemaRows` ARE HERE SO THE GUARDS CAN RUN THE CODE (CBH2-25).
+ * A previous pass on this file shipped guards that read `explain.ts` as TEXT and called themselves
+ * behavioural in their own docstrings; a reviewer broke the fix in one line and they stayed green.
+ * Anything a guard needs to assert about rendering must be reachable as a function, not as a
+ * regex over the source — so the extraction IS the fix, not tidying.
+ */
+export const __testing = {
+    normalize,
+    describeField,
+    synthMinimalInput,
+    sampleValue,
+    schemaRows,
+    formatSchemaRows,
+    mergeInputSchemas,
+    normalizeTypeName,
+    exampleMutates,
+    classifyExample,
+    aliasGroups,
+    exampleBlock,
+    /**
+     * ⚠⚠ `render` IS EXPORTED SO A GUARD CAN ASSERT THE REAL CALL SITE, NOT JUST THE HELPER (CBH2-57).
+     *
+     * `exampleBlock` being correct proves nothing about what `explain` prints — the previous version
+     * of this defect was exactly that shape, a generator that had been fixed while the line a user
+     * reads had not. The suite captures `console.log` around this function and asserts the actual
+     * output, so deleting the call and inlining the old one-liner fails.
+     */
+    render,
+};