@north-light/crouter 0.3.231 → 0.3.233

package/dist/core/__tests__/seam/dormancy-release.test.js

@@ -133,7 +133,7 @@ test('an already idle resident with no live obligation reconciles into completed
     subscribe(root, nodeId, true);
     await h.tick();
     assert.equal(h.node(nodeId)?.status, 'done', 'an older idle row becomes pruning-eligible without needing a broker revive');
-    assert.equal(h.node(nodeId)?.intent, 'done', 'the reconciled row records clean completion');
+    assert.equal(h.node(nodeId)?.intent, 'parked', 'the reconciled row carries the durable park marker (isParked)');
     const wake = readInboxSince(root).find((entry) => entry.from === nodeId && entry.data?.['reason'] === 'child-auto-done');
     assert.ok(wake, 'the subscribing root learns that the parked resident completed without a final report');
 });
@@ -141,8 +141,19 @@ test('an unattended resident with no live obligation completes on the daemon clo
     // The park clock is read per supervision pass (unattendedParkMsForDaemon), so
     // it is armed for THIS test only — a file-global 1500ms park clock would also
     // apply to the idle-release manager above and race its own release path.
+    //
+    // The clock no longer terminalizes directly: it arms a pending park and asks
+    // the live engine for one summary turn, and broker SETTLEMENT enacts the park
+    // on the good path. That settlement runs in the harness's separate api-server
+    // process, where the (deliberately process-local) pending park does not
+    // exist — so this seam pins the DEGRADED path: the summary grace expires on
+    // the supervision clock and the daemon parks without a report, fanning the
+    // doctrine wake. The settlement good path is covered by the in-process
+    // broker-settle tests.
     const priorParkMs = process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
+    const priorGraceMs = process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS'];
     process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = '1500';
+    process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS'] = '1000';
     try {
         const nodeId = h.fabricateBrokerNode({
             id: 'settled-no-work',
@@ -167,15 +178,20 @@ test('an unattended resident with no live obligation completes on the daemon clo
         await h.tick(seenAt);
         await h.tick(seenAt + 1499);
         assert.equal(h.fleet.has(nodeId), true, 'the daemon keeps the broker through the full grace');
+        // Clock expiry: arms the pending park and requests the summary turn.
         await h.tick(seenAt + 1500);
+        // Summary grace expiry: the degraded enactment parks without a report.
+        // (If the summary turn's settlement already released the broker in the
+        // api-server process, the dormant-inbox reconciler applies the same park.)
+        await h.tick(seenAt + 1500 + 1000);
         await h.waitFor(() => {
             const node = h.node(nodeId);
-            return node?.status === 'done' && node.intent === 'done' && !isPidAlive(boot.pid);
-        }, { timeoutMs: 10_000, intervalMs: 20, label: 'unattended completion and broker exit' });
+            return node?.status === 'done' && node.intent === 'parked' && !isPidAlive(boot.pid);
+        }, { timeoutMs: 10_000, intervalMs: 20, label: 'unattended park and broker exit' });
         // The pid vanishing is not the fleet learning about it: wait for the child
         // 'exit' delivery + its policy job, which is what actually frees the slot.
         await h.awaitFleetExit(nodeId);
-        assert.equal(h.fleet.has(nodeId), false, 'exit policy forgets the completed broker');
+        assert.equal(h.fleet.has(nodeId), false, 'exit policy forgets the parked broker');
         assert.equal(h.node(nodeId)?.status, 'done', 'the row is terminal and eligible for history pruning');
         const wake = readInboxSince(root).find((entry) => entry.from === nodeId && entry.data?.['reason'] === 'child-auto-done');
         assert.ok(wake, 'the subscribing root is woken when the unattended clock completes the resident');
@@ -188,11 +204,17 @@ test('an unattended resident with no live obligation completes on the daemon clo
             delete process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
         else
             process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = priorParkMs;
+        if (priorGraceMs === undefined)
+            delete process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS'];
+        else
+            process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS'] = priorGraceMs;
     }
 });
 test('a non-attending observer does not prevent unattended resident parking', { timeout: 30_000 }, async () => {
     const priorParkMs = process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
+    const priorGraceMs = process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS'];
     process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = '1500';
+    process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS'] = '1000';
     const nodeId = h.fabricateBrokerNode({
         id: 'settled-with-system-observer',
         parent: root,
@@ -209,10 +231,11 @@ test('a non-attending observer does not prevent unattended resident parking', {
         const seenAt = 12_000;
         await h.tick(seenAt);
         await h.tick(seenAt + 1500);
+        await h.tick(seenAt + 1500 + 1000);
         await h.waitFor(() => h.node(nodeId)?.status === 'done' && !isPidAlive(boot.pid), {
             timeoutMs: 10_000,
             intervalMs: 20,
-            label: 'system-observed unattended completion and broker exit',
+            label: 'system-observed unattended park and broker exit',
         });
         await h.awaitFleetExit(nodeId);
     }
@@ -221,6 +244,10 @@ test('a non-attending observer does not prevent unattended resident parking', {
             delete process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
         else
             process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = priorParkMs;
+        if (priorGraceMs === undefined)
+            delete process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS'];
+        else
+            process.env['CRTR_TEST_PARK_SUMMARY_GRACE_MS'] = priorGraceMs;
     }
 });
 test('a connected broker viewer keeps an obligation-free resident live', { timeout: 30_000 }, async () => {

package/dist/core/canvas/attention.d.ts

@@ -3,6 +3,8 @@ export interface TicketEntry {
     name: string;
     cwd: string;
     count: number;
+    /** Open ticket titles for this node, newest first (scan order). */
+    subjects: string[];
 }
 /** Drop the cached walk. Callers that swap the canvas home out from under a live
  *  process (tests, and any in-process home switch) must call this: the cache is

package/dist/core/canvas/attention.js

@@ -33,57 +33,64 @@ let ticketCountCache = null;
 export function invalidateTicketCounts() {
     ticketCountCache = null;
 }
-function ticketCounts() {
+function ticketSubjects() {
     const now = Date.now();
     if (ticketCountCache !== null && now - ticketCountCache.at < TICKET_COUNT_TTL_MS) {
-        return ticketCountCache.counts;
+        return ticketCountCache.subjects;
     }
-    const counts = new Map();
+    const subjects = new Map();
     try {
         for (const ticket of filterTerminalReviewTickets(scanInbox())) {
             const nodeId = askingNodeId(ticket.dir);
-            if (nodeId !== null)
-                counts.set(nodeId, (counts.get(nodeId) ?? 0) + 1);
+            if (nodeId === null)
+                continue;
+            const list = subjects.get(nodeId);
+            if (list === undefined)
+                subjects.set(nodeId, [ticket.title]);
+            else
+                list.push(ticket.title);
         }
     }
     catch {
         // An unavailable ticket store or absent root has no display consequence.
     }
-    ticketCountCache = { at: Date.now(), counts };
-    return counts;
+    ticketCountCache = { at: Date.now(), subjects };
+    return subjects;
 }
 /** Count pending tickets asked by one node. */
 export function countTickets(nodeId) {
-    return ticketCounts().get(nodeId) ?? 0;
+    return ticketSubjects().get(nodeId)?.length ?? 0;
 }
 /** Pending tickets for every reachable asking node, including the root. */
 export function pendingTicketsForView(rootId) {
-    const counts = ticketCounts();
+    const found = ticketSubjects();
     const entries = [];
     for (const id of [rootId, ...view(rootId)]) {
         const node = getNode(id);
-        const count = counts.get(id) ?? 0;
-        if (node !== null && count > 0)
-            entries.push({ node_id: id, name: node.name, cwd: node.cwd, count });
+        const subjects = found.get(id) ?? [];
+        if (node !== null && subjects.length > 0) {
+            entries.push({ node_id: id, name: node.name, cwd: node.cwd, count: subjects.length, subjects });
+        }
     }
     return entries;
 }
 /** Per-node pending ticket counts for an explicit node set. */
 export function ticketCountsForNodes(ids) {
-    const found = ticketCounts();
+    const found = ticketSubjects();
     const counts = {};
     for (const id of ids)
-        counts[id] = found.get(id) ?? 0;
+        counts[id] = found.get(id)?.length ?? 0;
     return counts;
 }
 /** Pending tickets across the entire canvas, attributed to asking nodes. */
 export function ticketsAcrossCanvas() {
-    const counts = ticketCounts();
+    const found = ticketSubjects();
     const entries = [];
     for (const node of listNodes()) {
-        const count = counts.get(node.node_id) ?? 0;
-        if (count > 0)
-            entries.push({ node_id: node.node_id, name: node.name, cwd: node.cwd, count });
+        const subjects = found.get(node.node_id) ?? [];
+        if (subjects.length > 0) {
+            entries.push({ node_id: node.node_id, name: node.name, cwd: node.cwd, count: subjects.length, subjects });
+        }
     }
     return entries;
 }

package/dist/core/canvas/extensions.d.ts

@@ -1,4 +1,4 @@
-export declare const CANVAS_EXTENSION_NAMES: readonly ["canvas-inbox-watcher", "canvas-review-boundary", "canvas-stophook", "canvas-recap", "canvas-goal-capture", "canvas-passive-context", "canvas-context-intro", "canvas-tool-guide", "canvas-doc-substrate", "canvas-structured-output", "canvas-bash-valve", "canvas-preview-result"];
+export declare const CANVAS_EXTENSION_NAMES: readonly ["canvas-inbox-watcher", "canvas-review-boundary", "canvas-stophook", "canvas-recap", "canvas-goal-capture", "canvas-passive-context", "canvas-context-intro", "canvas-tool-guide", "canvas-doc-substrate", "canvas-structured-output", "canvas-bash-valve", "canvas-preview-result", "canvas-prompt-scrub"];
 /** Structural shipped-hook identity: a canvas-hook stem directly under a
  * `pi-extensions` directory. A user's own extension elsewhere may share the
  * stem and is not shipped. */

package/dist/core/canvas/extensions.js

@@ -7,9 +7,15 @@ export const CANVAS_EXTENSION_NAMES = [
     'canvas-inbox-watcher', 'canvas-review-boundary', 'canvas-stophook', 'canvas-recap',
     'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',
     'canvas-tool-guide', 'canvas-doc-substrate', 'canvas-structured-output',
-    'canvas-bash-valve', 'canvas-preview-result',
+    'canvas-bash-valve', 'canvas-preview-result', 'canvas-prompt-scrub',
 ];
 const HISTORICAL_CANVAS_EXTENSION_PREFIXES = [
+    [
+        'canvas-inbox-watcher', 'canvas-review-boundary', 'canvas-stophook', 'canvas-recap',
+        'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',
+        'canvas-tool-guide', 'canvas-doc-substrate', 'canvas-structured-output',
+        'canvas-bash-valve', 'canvas-preview-result',
+    ],
     [
         'canvas-inbox-watcher', 'canvas-review-boundary', 'canvas-stophook', 'canvas-recap',
         'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',

package/dist/core/canvas/history.js

@@ -451,16 +451,34 @@ export function nodeArtifacts(nodeId, types) {
     const want = new Set(types !== undefined && types.length > 0 ? types : ['report', 'doc', 'roadmap']);
     const desc = node.description ?? '';
     const out = [];
+    // One malformed file must not break the whole listing — the frontmatter
+    // parser throws by design, so this collection layer isolates per file, same
+    // as buildCorpus. A context dir often holds foreign markdown (a checked-out
+    // repo, node_modules) whose `---` header is not crouter frontmatter.
     if (want.has('report')) {
         for (const f of listReportFiles(nodeId)) {
-            const a = reportArtifact(row, desc, f);
+            let a;
+            try {
+                a = reportArtifact(row, desc, f);
+            }
+            catch (e) {
+                warnInvalidFrontmatter(join(reportsDir(nodeId), f), e);
+                continue;
+            }
             if (a !== null)
                 out.push(a);
         }
     }
     if (want.has('doc') || want.has('roadmap')) {
         for (const abs of listDocFiles(nodeId)) {
-            const a = docArtifact(row, desc, abs);
+            let a;
+            try {
+                a = docArtifact(row, desc, abs);
+            }
+            catch (e) {
+                warnInvalidFrontmatter(abs, e);
+                continue;
+            }
             if (a.source === 'roadmap' && !want.has('roadmap'))
                 continue;
             if (a.source === 'doc' && !want.has('doc'))

package/dist/core/canvas/types.d.ts

@@ -17,7 +17,7 @@ export type Lifecycle = 'terminal' | 'resident';
 /** base = hands-on worker; orchestrator = delegating manager. Bespoke per kind. */
 export type Mode = 'base' | 'orchestrator';
 /** Why a node last stopped — drives the daemon's reap-vs-revive decision. */
-export type ExitIntent = 'done' | 'refresh' | 'idle-release' | null;
+export type ExitIntent = 'done' | 'refresh' | 'idle-release' | 'parked' | null;
 /** The two structural edges. `subscribes_to` is the load-bearing spine (flow,
  *  org chart, views, completion routing). `spawned_by` is audit only. */
 export type EdgeType = 'subscribes_to' | 'spawned_by';

package/dist/core/command.js

@@ -189,11 +189,16 @@ function renderNode(node) {
     return renderLeafArgv(node.help);
 }
 /** Render effective Effects for a hook-eligible core leaf, then append any
- *  commands.json helpAddenda beneath the contract. Both lookups read stored
- *  manifest bytes only. Addenda validation receives the install gate's exact
- *  reserved core names and full core path set, so a manifest rejected at
- *  ingress contributes nothing here either. */
-async function renderNodeWithAddenda(node, path) {
+ *  commands.json helpAddenda beneath the ordinary contract. Focused parameter
+ *  help returns only the leaf-owned parameter view, because the caller already
+ *  read the ordinary contract and addenda before following its road sign. Both
+ *  plugin lookups read stored manifest bytes only. Addenda validation receives
+ *  the install gate's exact reserved core names and full core path set, so a
+ *  manifest rejected at ingress contributes nothing here either. */
+async function renderNodeWithAddenda(node, path, focusedFlag) {
+    if (focusedFlag !== undefined && node.kind === 'leaf') {
+        return renderLeafArgv(node.help, focusedFlag);
+    }
     const body = node.kind === 'leaf' && node.effectiveHelp !== undefined
         ? renderLeafArgv(await node.effectiveHelp())
         : renderNode(node);
@@ -215,6 +220,21 @@ async function renderNodeWithAddenda(node, path) {
 function helpRequested(remaining) {
     return remaining.some((t) => t === '-h' || t === '--help');
 }
+/** Resolve the canonical focused-help form `crtr <leaf> --<flag> -h`.
+ *  Only flags that explicitly own a focusedHelp contract select that view;
+ *  every other historical help invocation renders ordinary leaf help. */
+function focusedHelpFlag(node, remaining) {
+    if (node.kind !== 'leaf' || remaining.length !== 2)
+        return undefined;
+    const [flagToken, helpToken] = remaining;
+    if ((helpToken !== '-h' && helpToken !== '--help')
+        || !flagToken.startsWith('--')
+        || flagToken.includes('='))
+        return undefined;
+    const name = flagToken.slice(2);
+    const flag = (node.help.params ?? []).find((param) => param.kind === 'flag' && param.name === name);
+    return flag?.focusedHelp !== undefined ? name : undefined;
+}
 /** Recover the RAW argv slice after a matched passthrough branch's path,
  *  unaffected by the `--json`-stripping done to build `tokens`. `path` is a
  *  prefix of non-`--json` tokens in order, so walking `rawTokens` while
@@ -387,7 +407,10 @@ export async function parseArgv(params, tokens, options) {
             }
             const rawVal = inlineValue !== undefined ? inlineValue : tokens[++i];
             if (rawVal === undefined || rawVal.startsWith('--')) {
-                throw parseArgvError('missing_parameter', `--${flagName} requires a value`, `--${flagName}`, flagName);
+                const focusedNext = flagDef.focusedHelp !== undefined && (options?.leafPath?.length ?? 0) > 0
+                    ? `Run \`crtr ${options.leafPath.join(' ')} --${flagName} -h\` and read the focused value contract before retrying.`
+                    : undefined;
+                throw parseArgvError('missing_parameter', `--${flagName} requires a value`, `--${flagName}`, flagName, focusedNext);
             }
             let parsedValue;
             if (flagDef.type === 'int') {
@@ -620,9 +643,11 @@ export async function runCli(root, argv) {
             && remaining[0] !== '-h' && remaining[0] !== '--help') {
             throw unknownPathError(node, path, remaining[0]);
         }
-        // Help anywhere in remaining tokens → print node help and exit
+        // Help anywhere in remaining tokens → print node help and exit. The exact
+        // leaf form `--<flag> -h` selects that flag's focused continuation when one
+        // is declared; no invocation state or acknowledgement token is persisted.
         if (helpRequested(remaining)) {
-            process.stdout.write(await renderNodeWithAddenda(node, path) + '\n');
+            process.stdout.write(await renderNodeWithAddenda(node, path, focusedHelpFlag(node, remaining)) + '\n');
             process.exitCode = ExitCode.SUCCESS;
             return;
         }

package/dist/core/help.d.ts

@@ -28,6 +28,20 @@ export interface PositionalParam {
 }
 /** How a local file named by a `path` param is encoded into the request. */
 export type FileEncoding = 'text' | 'base64';
+/** Additional guidance for an uncommon flag whose safe selection, value
+ *  grammar, dynamic choices, or effects do not fit in its compact leaf-schema
+ *  row. The compact row routes the agent to `crtr <leaf> --<flag> -h`; that
+ *  focused continuation renders only this parameter contract. */
+export interface FocusedFlagHelp {
+    /** Concrete cases that justify overriding the default, plus when to omit. */
+    whenToUse: string;
+    /** Complete accepted-value grammar and default/inheritance behavior. */
+    value: string;
+    /** Flag-specific persistent or lifecycle effects and coupled interactions. */
+    effects?: string[];
+    /** Bounded dynamic choices owned by this flag, rendered only in focused help. */
+    dynamicState?: () => string | null;
+}
 /** Long-form flag (`--name`). */
 export interface FlagParam {
     kind: 'flag';
@@ -37,7 +51,13 @@ export interface FlagParam {
     /** Required only when type is 'enum'. */
     choices?: string[];
     required: boolean;
+    /** Compact discovery contract. When focusedHelp is present, state what the
+     *  flag changes and the condition that could justify it; the renderer adds
+     *  the exact focused-help road sign automatically. */
     constraint: string;
+    /** Opt into focused `--flag -h` guidance. Use only when omission is normal
+     *  and the complete safe contract cannot fit in one compact row. */
+    focusedHelp?: FocusedFlagHelp;
     default?: string | number | boolean;
     /** When true, the flag may appear multiple times; values accumulate into an
      *  array (parseArgv collects them; body-placed REST params ship as a JSON array). */
@@ -196,7 +216,9 @@ export interface LeafHelp {
     name: string;
     summary: string;
     /** Optional long-form workflow prose rendered immediately after the summary
-     *  line. Only plan new / spec new carry this; it precedes the schema. */
+     *  line, before the schema. Carried only by leaves whose correct use needs
+     *  prose beyond the schema (e.g. node new's prompt-writing guidance,
+     *  node yield's pre-yield checklist). */
     guide?: string;
     params?: InputParam[];
     /** Note appended when there is no input (replaces the Input block). */
@@ -231,4 +253,8 @@ export type EffectiveLeafHelp = Readonly<Omit<LeafHelp, 'effects'> & {
 export declare function stateBlock(tag: string, attrs: Record<string, string | number>, body: string): string;
 export declare function renderRoot(h: RootHelp): string;
 export declare function renderBranch(h: BranchHelp): string;
-export declare function renderLeafArgv(h: LeafHelp | EffectiveLeafHelp): string;
+/** Render one leaf's ordinary contract, or the focused continuation for one
+ *  uncommon flag selected through `--flag -h`. The caller reaches focused help
+ *  from the ordinary row, so that view contains only leaf identity and the new
+ *  parameter detail instead of repeating information already in context. */
+export declare function renderLeafArgv(h: LeafHelp | EffectiveLeafHelp, focusedFlag?: string): string;

package/dist/core/help.js

@@ -47,7 +47,7 @@ function pad(s, width) {
 // ---------------------------------------------------------------------------
 const IO_CONTRACT = 'I/O contract: flags and positional args on input; stdout is agent-ready markdown/XML you\n' +
     'act on directly — read it as a continuation of your prompt, don\'t parse it as data.\n' +
-    'Exit 0 on success, non-zero on failure. Schemas appear at leaf -h.';
+    'Exit 0 on success, non-zero on failure. Schemas appear at leaf -h; a leaf may route an uncommon flag to focused --flag -h guidance.';
 // Behavioral instruction (not a schema) — engrained in the appended system
 // prompt so the model treats unfamiliar capabilities as a cue to discover the
 // contract, never to guess, AND reads a command's contract before invoking it.
@@ -57,6 +57,7 @@ const CAPABILITY_DISCOVERY = 'Before running a crtr command that changes state
     "deletes anything — whose exact contract (args, flags, effects) you haven't " +
     'verified this session, run `-h` on it and read the schema first — a reliable ' +
     'read beats a guess that wastes a turn or triggers an unintended effect. ' +
+    'When a leaf routes a flag to focused help, read that focused help before using the flag; the compact row is discovery, not its invocation contract. ' +
     "Same when the user names a capability you don't fully recognize: " +
     '`-h` it before acting.';
 /** Lines for a command's subcommand affordance at root: any promoted
@@ -204,7 +205,12 @@ function envDefaultNote(envVar) {
         ? ''
         : ` Defaults to $${envVar} when that is set and non-empty in the environment, and counts as supplied.`;
 }
-function paramDesc(p) {
+function focusedFlagHelpNote(flag, leafName) {
+    if (flag.focusedHelp === undefined)
+        return '';
+    return ` Before using this flag, run \`crtr ${leafName} --${flag.name} -h\` and read its focused guidance.`;
+}
+function paramDesc(p, leafName) {
     const req = p.required ? 'required' : 'optional';
     if (p.kind === 'positional') {
         const repeatable = p.repeatable === true
@@ -222,8 +228,9 @@ function paramDesc(p) {
     }
     // flag
     const f = p;
+    const focusedNote = focusedFlagHelpNote(f, leafName);
     if (f.type === 'bool')
-        return `${req} boolean. Presence means true. ${f.constraint}`.trim();
+        return `${req} boolean. Presence means true. ${f.constraint}${focusedNote}`.trim();
     const dflt = f.default !== undefined ? ` Default: ${String(f.default)}.` : '';
     const choices = f.type === 'enum' && f.choices !== undefined
         ? ` One of: ${f.choices.join(', ')}.`
@@ -231,24 +238,53 @@ function paramDesc(p) {
     const repeatable = f.repeatable === true
         ? ' Repeatable — pass multiple times to accumulate.'
         : '';
-    return `${f.type}, ${req}.${choices}${dflt}${fileEncodingNote(f.encoding)}${envDefaultNote(f.defaultFromEnv)} ${f.constraint}${repeatable}`.trim();
+    return `${f.type}, ${req}.${choices}${dflt}${fileEncodingNote(f.encoding)}${envDefaultNote(f.defaultFromEnv)} ${f.constraint}${repeatable}${focusedNote}`.trim();
 }
-export function renderLeafArgv(h) {
-    const lines = [];
-    lines.push(`${h.name}: ${h.summary}.`);
+/** Render one leaf's ordinary contract, or the focused continuation for one
+ *  uncommon flag selected through `--flag -h`. The caller reaches focused help
+ *  from the ordinary row, so that view contains only leaf identity and the new
+ *  parameter detail instead of repeating information already in context. */
+export function renderLeafArgv(h, focusedFlag) {
+    const lines = [`${h.name}: ${h.summary}.`];
+    // Hidden flags are parsed but never advertised in -h (see FlagParam.hidden).
+    const params = (h.params ?? []).filter((p) => !(p.kind === 'flag' && p.hidden === true));
+    const focused = focusedFlag === undefined
+        ? undefined
+        : params.find((p) => p.kind === 'flag' && p.name === focusedFlag && p.focusedHelp !== undefined);
+    if (focused?.focusedHelp !== undefined) {
+        const detail = focused.focusedHelp;
+        lines.push('');
+        lines.push(`<parameter name="${focused.name}">`);
+        lines.push('When to use');
+        lines.push(`  ${detail.whenToUse}`);
+        lines.push('');
+        lines.push('Value');
+        lines.push(`  ${detail.value}`);
+        if ((detail.effects ?? []).length > 0) {
+            lines.push('');
+            lines.push('Effects');
+            for (const effect of detail.effects ?? [])
+                lines.push(`  ${effect}`);
+        }
+        const focusedState = evalDynamic(detail.dynamicState);
+        if (focusedState !== null) {
+            lines.push('');
+            lines.push(focusedState);
+        }
+        lines.push('</parameter>');
+        return lines.join('\n');
+    }
     if (h.guide !== undefined) {
         lines.push('');
         lines.push(h.guide);
     }
     lines.push('');
-    // Hidden flags are parsed but never advertised in -h (see FlagParam.hidden).
-    const params = (h.params ?? []).filter((p) => !(p.kind === 'flag' && p.hidden === true));
     if (params.length > 0) {
         lines.push('Input');
         const labels = params.map(paramLabel);
         const colW = maxLen(labels);
         for (let i = 0; i < params.length; i++) {
-            lines.push(`  ${pad(labels[i], colW)}  ${paramDesc(params[i])}`);
+            lines.push(`  ${pad(labels[i], colW)}  ${paramDesc(params[i], h.name)}`);
         }
     }
     else {

package/dist/core/human/__tests__/page-html-markdown.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/human/__tests__/page-html-markdown.test.js

@@ -0,0 +1,48 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { projectHtmlDocumentMarkdown } from '../page-html-markdown.js';
+test('an authored HTML page projects to readable markdown', () => {
+    const markdown = projectHtmlDocumentMarkdown(`<!doctype html>
+<html><head><title>Deploy sign-off</title><style>body{color:red}</style></head>
+<body>
+<h1>Deploy sign-off</h1>
+<p>Staging has been green for <strong>6 hours</strong>; the risk is the <em>migration</em>.</p>
+<ul><li>Smoke suite passed</li><li>Rollback rehearsed &mdash; 90s</li><li>See <a href="https://ci.example.com/42">run 42</a></li></ul>
+<table><tr><th>Step</th><th>Duration</th></tr><tr><td>Migrate</td><td>4m 10s</td></tr></table>
+<pre><code>kubectl rollout status deploy/orders</code></pre>
+<blockquote>Waiting on your call.</blockquote>
+<script>console.log('nope')</script>
+</body></html>`);
+    assert.equal(markdown, [
+        '# Deploy sign-off',
+        '',
+        'Staging has been green for **6 hours**; the risk is the *migration*.',
+        '',
+        '- Smoke suite passed',
+        '- Rollback rehearsed — 90s',
+        '- See [run 42](https://ci.example.com/42)',
+        '',
+        '| Step | Duration |',
+        '| --- | --- |',
+        '| Migrate | 4m 10s |',
+        '',
+        '```',
+        'kubectl rollout status deploy/orders',
+        '```',
+        '',
+        '> Waiting on your call.',
+    ].join('\n'));
+});
+test('the projection survives malformed markup rather than losing the document', () => {
+    // A stray </style> must not reopen the head, and a stray <script> must not
+    // swallow the rest of the page: both are common in hand-written HTML.
+    assert.match(projectHtmlDocumentMarkdown('</style><p>Body text</p>'), /Body text/);
+    assert.equal(projectHtmlDocumentMarkdown('<p>Before</p><script>x=1;</script><p>After</p>'), 'Before\n\nAfter');
+    assert.equal(projectHtmlDocumentMarkdown('<p>Alone<'), 'Alone\\<');
+    assert.equal(projectHtmlDocumentMarkdown(''), '');
+    // Ordered lists number themselves, and a link with no label leaves no husk.
+    assert.equal(projectHtmlDocumentMarkdown('<ol><li>First</li><li>Second</li></ol>'), '1. First\n2. Second');
+    assert.equal(projectHtmlDocumentMarkdown('<p>Read <a href="https://x.test"></a>this</p>'), 'Read this');
+    // Markdown structure in authored prose is escaped, not obeyed.
+    assert.equal(projectHtmlDocumentMarkdown('<p># not a heading</p>'), '\\# not a heading');
+});

package/dist/core/human/component-docs.js

@@ -10,7 +10,7 @@ const SLOT_RULES = `Component contract
 - When a page has two or more response-bearing components, every one needs a nonempty \`label\`.
 - Config objects and every documented nested object reject unknown fields.
 - The page is rendered once at submit to build the ticket manifest, so every prop reaches it whatever its shape — mapped data, a helper component, a value from \`useState\`. Event handlers are dropped, because a manifest is JSON. The user's answer lands in \`response.json\` keyed by this \`id\`.`;
-const COMMENT_SHAPE = `Comments are \`{id:string (nonempty), text:string, anchor:Anchor}\` and qualify the answer itself. \`Anchor\` is \`{kind:"option",optionId:string}\` or \`{kind:"row",rowId:string}\`; each component accepts only the anchors named next. Feedback on rendered page content — including the question text — is given by highlighting it on the page, never authored into a response.`;
+const COMMENT_SHAPE = `Comments are \`{id:string (nonempty), text:string, anchor:Anchor}\` and qualify the answer itself. \`Anchor\` is \`{kind:"option",optionId:string}\` or \`{kind:"row",rowId:string}\`; each component accepts only the anchors named next. The reader writes one against a specific option or row in whatever host they read in — in the terminal inbox, \`c\` on the selected one — so every option and row needs a label that reads on its own. Feedback on the page's own prose is a separate channel, offered only by hosts that render the page, and never part of a response.`;
 const DISPLAY_RULES = `Display-only: it is not recorded in the page manifest and contributes nothing to the response. Every display component also takes \`className\` for Tailwind utilities, and standard shadcn props otherwise.`;
 export const BUILTIN_COMPONENT_DOCS = [
     {
@@ -103,12 +103,12 @@ Example
     {
         names: ['UserText'],
         group: 'slot',
-        selectionLine: '`UserText` — writing surface (wire kind `text`). Use when you need prose back from the user — a value they write, or a draft they hand back revised; use `singleLine` for a subject, name, or URL. Prose the user only reads is a plain element, never this.',
+        selectionLine: '`UserText` — writing surface (wire kind `text`). Use whenever the answer is written rather than chosen: a value, a paragraph, or a draft you seeded for them to revise; `singleLine` for a subject, name, or URL. This is the page\'s surface for freeform input — a picker\'s `allowFreetext` is an escape hatch beside its options, not a way to collect prose. Prose the user only reads is a plain element.',
         contract: `\`<UserText>\` — wire kind \`text\`
 
 Response-bearing. The response is \`{text:string, edited:boolean}\`: the text the user hands back, and whether they changed what you drafted.
 
-It collects prose, it does not present it. Text the user only reads is a plain element with Tailwind classes — \`<p className="whitespace-pre-wrap">\` — which renders the same and asks nothing of them. Reach for it only when the answer you need is the string left in the field. Feedback on the rendered text is given by highlighting it on the page, not authored into the response.
+Reach for it whenever what you need back is written rather than picked — a value, a paragraph, or a draft you seeded with \`initialText\` for them to revise. It is the page's one writing surface: \`allowFreetext\` on a picker adds a single "something else" row beside the options, so prose you actually want belongs here instead. It collects text, it does not present it — text the user only reads is a plain element with Tailwind classes, \`<p className="whitespace-pre-wrap">\`, which renders the same and asks nothing of them.
 
 ${SLOT_RULES}
 
@@ -164,7 +164,7 @@ Example
         selectionLine: '`UserCards` — visual item picker (wire kind `cards`). Use when the user chooses among rich, card-shaped alternatives.',
         contract: `\`<UserCards>\` — wire kind \`cards\`
 
-Response-bearing. The response is \`{selectedCardIds:string[]}\`. Feedback on a card's content is given by highlighting it on the page, not authored into the response.
+Response-bearing. The response is \`{selectedCardIds:string[]}\` — the selection alone; cards carry no comments.
 
 ${SLOT_RULES}
 

package/dist/core/human/page-html-markdown.d.ts

@@ -0,0 +1,8 @@
+/** An HTML page's document projected to markdown, so a terminal reader sees the
+ *  page's actual content instead of a placeholder line. HTML pages are authored
+ *  for a browser surface and carry no slots, so this is a reading projection
+ *  only — layout, styling, and scripting are dropped, and what survives is the
+ *  prose, headings, lists, links, code, and table cells the author wrote. */
+/** Project one authored HTML document to markdown. Never throws: a document
+ *  this cannot make sense of yields whatever text it did find, down to ''. */
+export declare function projectHtmlDocumentMarkdown(document: string): string;