@north-light/crouter 0.3.192 → 0.3.193

package/dist/commands/human/prompts.js

@@ -6,17 +6,20 @@
 import { defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { cliClient } from '../api-client.js';
-import { dirname, isAbsolute, join } from 'node:path';
+import { extname, join } from 'node:path';
 import { randomBytes } from 'node:crypto';
+import { rmSync } from 'node:fs';
+import { readConfig } from '../../core/config.js';
 import { tmuxServerReachable } from '../../core/spawn.js';
 import { markStopSignal } from '../../core/runtime/stop-signals.js';
-import { validateDeck, resolveDeckBodyPaths } from '../../core/human/deck-schema.js';
-import { notifyDeck } from '../../core/human/deck-factories.js';
 import { atomicWriteJson } from '../../core/human/convention.js';
 import { ticketDir } from '../../core/human/root.js';
-import { submitDeck } from '../../core/human/tickets.js';
+import { preparePage, publishPage } from '../../core/human/tickets.js';
+import { synthesizedPageDocument, writeSynthesizedPage } from '../../core/human/page-synth.js';
+import { PageAuthoringError } from '../../core/human/page.js';
 import { display } from '../../core/termrender/display.js';
-import { BODY_PATH_CONTRACT, DECK_SCHEMA_HINT, resolveMaxPanes } from './shared.js';
+import { pageHelpText, resolveMaxPanes } from './shared.js';
+const PAGE_HELP = pageHelpText();
 /** The asking node's id, or null when run from a bare shell (no parent to route to). */
 function askingNode() {
     return process.env['CRTR_NODE_ID'] ?? null;
@@ -25,7 +28,7 @@ function askingNode() {
  * directory, never ticket data; `nodeId` carries the originating node so a
  * consumer can relate a ticket back to whatever that node belongs to, and
  * `sessionName` is a presentation label only. Review tickets already stamp
- * `nodeId` the same way (`core/review/realize.ts`), so decks match them.
+ * `nodeId` the same way (`core/review/realize.ts`), so pages match them.
  * `nodeId` is stamped even when the daemon is unreachable — losing the label is
  * survivable, losing machine attribution is not. */
 export async function sourceStamp() {
@@ -60,49 +63,55 @@ function requireSubtitle(subtitle, field = 'subtitle') {
         next: 'Write one plain-English sentence stating the decision, recommendation or status, and stakes.',
     });
 }
-function validateTitledDeck(input, deckDirectory) {
-    const title = typeof input === 'object' && input !== null
-        ? input.title
-        : undefined;
-    if (typeof title !== 'string' || title.trim() === '') {
-        throw new Error('deck title is required');
-    }
-    const deck = validateDeck(input);
-    if (deckDirectory === undefined)
-        return deck;
-    for (const interaction of deck.interactions) {
-        if (interaction.bodyPath !== undefined && isAbsolute(interaction.bodyPath)) {
-            throw new Error('bodyPath must be relative to the deck JSON; absolute paths are unsupported');
-        }
+function pageDialect(sourceFile) {
+    const extension = extname(sourceFile).toLowerCase();
+    if (extension === '.md')
+        return 'md';
+    if (extension === '.html' || extension === '.htm')
+        return 'html';
+    throw new InputError({
+        error: 'invalid_page_dialect',
+        message: `--page must point to a .md, .html, or .htm file; received "${sourceFile}"`,
+        field: 'page',
+        next: 'Use a Markdown page (.md) or an HTML page (.html or .htm).',
+    });
+}
+function pageProductKinds(dialect) {
+    const config = readConfig('user');
+    if (dialect === 'html' && !config.html_pages) {
+        throw new InputError({
+            error: 'page_dialect_disabled',
+            message: 'html pages are not enabled in this home; md is the dialect to use',
+            field: 'page',
+            next: 'Use a .md page, or enable html_pages in the user scope config before submitting HTML.',
+        });
     }
-    return resolveDeckBodyPaths(deck, deckDirectory);
+    return config.page_components;
 }
-function buildHumanAskDeck(title, subtitle, question) {
-    return validateTitledDeck({
-        title,
-        interactions: [
-            {
-                id: 'question',
-                title,
-                subtitle,
-                body: question,
-                options: [],
-                allowFreetext: true,
-                freetextLabel: 'Your answer',
-            },
-        ],
+function requireNotifyTitle(title) {
+    if (title !== undefined && title.trim() !== '')
+        return title.trim();
+    throw new InputError({
+        error: 'missing_parameter',
+        message: 'notify shorthand requires a non-empty title',
+        field: 'title',
+        next: 'Retry with a positional title, --subtitle, and optional --body, or submit a page with --page PATH.',
     });
 }
-/** Crouter authors decision decks by default. Persist the explicit kind so
- * consumers can rely on the ticket store's strict interaction-kind contract. */
-function canonicalizeAskKinds(deck) {
-    return {
-        ...deck,
-        interactions: deck.interactions.map((interaction) => ({
-            ...interaction,
-            kind: interaction.kind ?? 'decision',
-        })),
-    };
+function submitAuthoredPage(submit) {
+    try {
+        return submit();
+    }
+    catch (error) {
+        if (!(error instanceof PageAuthoringError))
+            throw error;
+        throw new InputError({
+            error: 'invalid_page',
+            message: error.message,
+            field: 'page',
+            next: 'Fix the authored page, then pre-check it with `crtr human doc check <path>` before submitting again.',
+        });
+    }
 }
 /** The non-blocking status peek returned by ask/review. How the human reaches
  *  their inbox is theirs, not the agent's — naming a shortcut here only teaches
@@ -121,83 +130,85 @@ export const humanAsk = defineLeaf({
     help: {
         name: 'human ask',
         summary: "submit a decision ticket to crouter's inbox; returns a job handle immediately.",
-        guide: 'Write every interaction as a self-contained decision brief for a supervisor who has not followed this agent or task: use the title to identify the inbox topic; write a one-sentence subtitle stating the decision, your recommendation, and what it changes; then give the minimum plain-language context and tradeoffs needed to decide in the body. Never coin a term, code name, or shorthand for a system, mechanism, or state, and expand any project-internal name you do use: name the thing plainly and say what it does. Invented vocabulary is not compression — the reader has to decode it before they can decide. Put supporting evidence, chronology, and technical detail under `## Details` so the person can answer without logs, screenshots, or prior conversation. For a simple open-text question, supply the short topic with --title, the required sentence with --subtitle, and pipe the markdown body on stdin. Use --context-file for a fully structured deck; its deck title and every interaction title and subtitle are required. The deck body is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `crtr human doc check` before authoring one. Ask only what materially changes your next step, and offer genuine alternatives as `options`.',
+        guide: [
+            'Write a self-contained decision brief for a supervisor who has not followed the task: title names the topic; subtitle states the decision, your recommendation, and stakes; the body gives only the context and tradeoffs needed to decide. Put supporting evidence under `## Details`. Ask only what changes your next step, and offer genuine alternatives as `options`.',
+            PAGE_HELP.authoring,
+        ].join('\n\n'),
         params: [
-            { kind: 'flag', name: 'title', type: 'string', required: false, constraint: 'Required with stdin: a short ≤~4-word inbox topic. Mutually exclusive with --context-file, whose JSON carries its own required title.' },
-            { kind: 'flag', name: 'subtitle', type: 'string', required: false, constraint: 'Required with stdin: one plain-English sentence stating the decision, recommendation, and stakes. Mutually exclusive with --context-file, whose JSON requires every interaction subtitle.' },
-            { kind: 'stdin', name: 'question', required: false, constraint: "Simple open-text ask body. Pipe markdown from a single-quoted heredoc (`<<'EOF'`) to preserve literal bytes. Requires --title and --subtitle; mutually exclusive with --context-file." },
-            { kind: 'context-file', name: 'deck', required: false, constraint: `Strict structured deck JSON with a required deck title and non-empty subtitle on every interaction. ${BODY_PATH_CONTRACT}. Use this for multiple interactions, options, or other deck structure. Mutually exclusive with --title, --subtitle, and the question shorthand.`, shape: DECK_SCHEMA_HINT },
+            { kind: 'flag', name: 'title', type: 'string', required: false, constraint: 'Required with stdin shorthand: a short ≤~4-word inbox topic. Mutually exclusive with --page.' },
+            { kind: 'flag', name: 'subtitle', type: 'string', required: false, constraint: 'Required with stdin shorthand: one plain-English sentence stating the decision, recommendation, and stakes. Mutually exclusive with --page.' },
+            { kind: 'stdin', name: 'question', required: false, constraint: "Simple open-text ask body. Pipe markdown from a single-quoted heredoc (`<<'EOF'`) to preserve literal bytes. Requires --title and --subtitle; mutually exclusive with --page." },
+            { kind: 'flag', name: 'page', type: 'path', required: false, constraint: `${PAGE_HELP.pageHint} Mutually exclusive with shorthand.` },
         ],
         output: [
             { name: 'job_id', type: 'string', required: true, constraint: 'Node id of this human interaction. Its answer is pushed to your inbox when the human responds.' },
-            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding deck.json/run.json/response.json.' },
+            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding page.md or page.html, page.json, run.json, and response.json.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'A non-blocking status peek; the answer arrives via your inbox.' },
         ],
         outputKind: 'object',
         effects: [
-            'Creates a kind:"human" node under you and enqueues a decision deck in the human inbox.',
+            'Creates a kind:"human" node under you and enqueues a page in the human inbox.',
             'Returns immediately; nothing opens on screen. The human answers from their inbox on their own time.',
         ],
     },
-    run: async (input, context) => {
-        // Optional stdin reaches the leaf as an empty string when omitted, including
-        // when --context-file is supplied. Keep the raw non-empty bytes untouched.
+    run: async (input) => {
+        // Optional stdin reaches the leaf as an empty string when omitted. Keep the
+        // raw non-empty bytes untouched so shorthand callers retain their body.
         const titleRaw = input['title'];
         const title = typeof titleRaw === 'string' && titleRaw.trim() !== '' ? titleRaw.trim() : undefined;
         const questionRaw = input['question'];
         const question = typeof questionRaw === 'string' && questionRaw !== '' ? questionRaw : undefined;
         const subtitleRaw = input['subtitle'];
         const subtitle = typeof subtitleRaw === 'string' && subtitleRaw.trim() !== '' ? subtitleRaw.trim() : undefined;
-        const deckInput = input['deck'];
-        const deckPath = context?.contextFilePaths.get('deck');
-        if (deckInput !== undefined && (question !== undefined || titleRaw !== undefined || subtitleRaw !== undefined)) {
+        const pageInput = input['page'];
+        if (pageInput !== undefined && (question !== undefined || titleRaw !== undefined || subtitleRaw !== undefined)) {
             throw new InputError({
                 error: 'bad_invocation',
-                message: 'use --title and --subtitle with stdin question text, or --context-file, not both',
-                next: 'Retry with --title, --subtitle, and a piped question body, or with --context-file alone.',
+                message: 'use --title and --subtitle with stdin question text, or --page, not both',
+                next: 'Retry with --title, --subtitle, and a piped question body, or with --page PATH alone.',
             });
         }
-        if (question === undefined && deckInput === undefined) {
+        if (question === undefined && pageInput === undefined) {
             throw new InputError({
                 error: 'missing_parameter',
-                message: 'human ask needs stdin question text or --context-file deck.json',
-                next: 'Pipe a question body with --title and --subtitle, or pass --context-file for a structured deck.',
+                message: 'human ask needs stdin question text or --page PATH',
+                next: 'Pipe a question body with --title and --subtitle, or pass --page PATH for an authored page.',
             });
         }
-        const simpleAsk = question === undefined
-            ? undefined
-            : { title: requireAskTitle(title), subtitle: requireSubtitle(subtitle), question };
-        let deck;
+        const dialect = pageDialect(typeof pageInput === 'string' ? pageInput : 'page.md');
+        const productKinds = pageProductKinds(dialect);
+        let tempDir;
+        let sourceFile;
+        if (pageInput !== undefined) {
+            sourceFile = pageInput;
+        }
+        else {
+            const simpleAsk = { title: requireAskTitle(title), subtitle: requireSubtitle(subtitle), question: question };
+            const synthesized = writeSynthesizedPage(synthesizedPageDocument(simpleAsk.title, simpleAsk.subtitle, simpleAsk.question, true));
+            tempDir = synthesized.dir;
+            sourceFile = synthesized.path;
+        }
         try {
-            if (simpleAsk !== undefined) {
-                deck = buildHumanAskDeck(simpleAsk.title, simpleAsk.subtitle, simpleAsk.question);
-            }
-            else {
-                deck = validateTitledDeck(deckInput, deckPath === undefined ? undefined : dirname(deckPath));
-            }
-            deck = canonicalizeAskKinds(deck);
+            const source = await sourceStamp();
+            // The page is validated before the bridge node exists: a rejected page
+            // must create nothing, because a bridge node born for a ticket that never
+            // got published is a live terminal node no answer can ever finish.
+            const prepared = submitAuthoredPage(() => preparePage({ sourceFile, dialect, source, productKinds }));
+            const cwd = process.cwd();
+            const jobId = (await cliClient().createHumanBridge({ kind: 'human', parent: askingNode(), cwd, name: 'human-ask' })).node_id;
+            const idir = ticketDir(jobId);
+            const rc = { mode: 'ask', job_id: jobId };
+            atomicWriteJson(join(idir, 'run.json'), rc);
+            const { dir } = publishPage(ticketDir(jobId), prepared);
+            const originNodeId = askingNode();
+            if (originNodeId !== null && originNodeId !== '')
+                markStopSignal(originNodeId, 'askedHuman');
+            return { job_id: jobId, dir, follow_up: queuedFollowUp() };
         }
-        catch (e) {
-            throw new InputError({
-                error: 'deck_invalid',
-                message: String(e),
-                field: 'deck',
-                next: DECK_SCHEMA_HINT,
-            });
+        finally {
+            if (tempDir !== undefined)
+                rmSync(tempDir, { recursive: true, force: true });
         }
-        // Crouter owns this provenance. Never synthesize labels from deck content:
-        // an unavailable daemon leaves only machine attribution for routing.
-        deck = { ...deck, source: await sourceStamp() };
-        const cwd = process.cwd();
-        const jobId = (await cliClient().createHumanBridge({ kind: 'human', parent: askingNode(), cwd, name: 'human-ask' })).node_id;
-        const idir = ticketDir(jobId);
-        const rc = { mode: 'ask', job_id: jobId };
-        atomicWriteJson(join(idir, 'run.json'), rc);
-        const { dir } = submitDeck({ dir: ticketDir(jobId), deck });
-        const originNodeId = askingNode();
-        if (originNodeId !== null && originNodeId !== '')
-            markStopSignal(originNodeId, 'askedHuman');
-        return { job_id: jobId, dir, follow_up: queuedFollowUp() };
     },
 });
 // ---------------------------------------------------------------------------
@@ -210,33 +221,68 @@ export const humanNotify = defineLeaf({
     help: {
         name: 'human notify',
         summary: 'enqueue a fire-and-forget acknowledgement in the human inbox; creates no job',
-        guide: 'State what happened in plain words — no coined terms or internal shorthand for a system or concept; name it and say what it does. The body is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `crtr human doc check` before authoring one.',
+        guide: [
+            'State what happened in plain words. Shorthand bodies are directive-flavored Markdown; validate authored pages with `crtr human doc check`.',
+            PAGE_HELP.authoring,
+        ].join('\n\n'),
         params: [
-            { kind: 'positional', name: 'title', type: 'string', required: true, constraint: 'The notification headline.' },
-            { kind: 'flag', name: 'subtitle', type: 'string', required: true, constraint: 'One plain-English sentence stating the notification status and stakes.' },
-            { kind: 'flag', name: 'body', type: 'string', required: false, constraint: 'Optional markdown body.' },
+            { kind: 'positional', name: 'title', type: 'string', required: false, constraint: 'Notification headline for shorthand; required with --subtitle when --page is omitted.' },
+            { kind: 'flag', name: 'subtitle', type: 'string', required: false, constraint: 'One plain-English sentence stating the notification status and stakes; required when --page is omitted.' },
+            { kind: 'flag', name: 'body', type: 'string', required: false, constraint: 'Optional markdown body for shorthand; mutually exclusive with --page.' },
+            { kind: 'flag', name: 'page', type: 'path', required: false, constraint: `${PAGE_HELP.pageHint} Mutually exclusive with --body.` },
         ],
         output: [
-            { name: 'queued', type: 'boolean', required: true, constraint: 'Always true — the notify deck is durable inbox state the human acknowledges from the inbox.' },
-            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding deck.json.' },
+            { name: 'queued', type: 'boolean', required: true, constraint: 'Always true — the notify page is durable inbox state the human acknowledges from the inbox.' },
+            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding page.md or page.html, page.json, and run.json.' },
         ],
         outputKind: 'object',
         effects: [
-            'Enqueues a durable notify deck in the human inbox. Creates no node; nothing opens on screen.',
+            'Enqueues a durable display page in the human inbox. Creates no node; nothing opens on screen.',
         ],
     },
     run: async (input) => {
-        const title = input['title'];
-        const subtitle = requireSubtitle(input['subtitle']);
+        const titleRaw = input['title'];
+        const title = typeof titleRaw === 'string' && titleRaw.trim() !== '' ? titleRaw.trim() : undefined;
+        const subtitleRaw = input['subtitle'];
+        const subtitle = typeof subtitleRaw === 'string' && subtitleRaw.trim() !== '' ? subtitleRaw.trim() : undefined;
         const body = input['body'];
-        let deck = notifyDeck(title, { subtitle, ...(body !== undefined ? { body } : {}) });
-        deck = { ...deck, source: await sourceStamp() };
-        const id = `nfy-${randomBytes(4).toString('hex')}`;
-        const idir = ticketDir(id);
-        const rc = { mode: 'notify' };
-        atomicWriteJson(join(idir, 'run.json'), rc);
-        const { dir } = submitDeck({ dir: ticketDir(id), deck });
-        return { queued: true, dir };
+        const pageInput = input['page'];
+        if (pageInput !== undefined && body !== undefined) {
+            throw new InputError({
+                error: 'bad_invocation',
+                message: 'use --page or --body, not both',
+                next: 'Retry with --page PATH alone for an authored page, or use the title, --subtitle, and --body shorthand.',
+            });
+        }
+        const dialect = pageDialect(typeof pageInput === 'string' ? pageInput : 'page.md');
+        const productKinds = pageProductKinds(dialect);
+        let tempDir;
+        let sourceFile;
+        if (pageInput !== undefined) {
+            sourceFile = pageInput;
+        }
+        else {
+            const shorthandTitle = requireNotifyTitle(title);
+            const shorthandSubtitle = requireSubtitle(subtitle);
+            const synthesized = writeSynthesizedPage(synthesizedPageDocument(shorthandTitle, shorthandSubtitle, body ?? '', false));
+            tempDir = synthesized.dir;
+            sourceFile = synthesized.path;
+        }
+        try {
+            const source = await sourceStamp();
+            // Validate before the ticket directory exists, so a rejected page leaves
+            // no half-built ticket behind.
+            const prepared = submitAuthoredPage(() => preparePage({ sourceFile, dialect, source, productKinds }));
+            const id = `nfy-${randomBytes(4).toString('hex')}`;
+            const rc = { mode: 'notify' };
+            atomicWriteJson(join(ticketDir(id), 'run.json'), rc);
+            const { dir } = publishPage(ticketDir(id), prepared);
+            return { queued: true, dir };
+        }
+        finally {
+            if (tempDir !== undefined)
+                rmSync(tempDir, { recursive: true, force: true });
+        }
     },
 });
 // ---------------------------------------------------------------------------
@@ -251,7 +297,7 @@ export const humanShow = defineLeaf({
     help: {
         name: 'human show',
         summary: "put a file live on screen in a tmux pane with crouter's renderer",
-        guide: 'The pane always watches the file and live-updates on every save — a displayed doc is a live view by definition, so point it at a file something keeps rewriting (a status board, a running summary) and it stays current. The file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `crtr human doc render` before authoring one.',
+        guide: 'The pane always watches the file and live-updates on every save — a displayed doc is a live view by definition, so point it at a file something keeps rewriting (a status board, a running summary) and it stays current. The file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `crtr human doc render` before authoring one. To put a rich document in front of the human as a durable inbox page, use `crtr human notify --page PATH`.',
         params: [
             { kind: 'positional', name: 'path', type: 'path', required: true, constraint: 'Path to the file to render.' },
             { kind: 'flag', name: 'window', type: 'enum', choices: ['auto', 'split', 'new'], required: false, default: 'auto', constraint: 'Placement. Default auto.' },

package/dist/commands/human/queue.d.ts

@@ -1,4 +1,3 @@
 export declare const humanList: import("../../core/command.js").LeafDef;
-export declare const humanDeck: import("../../core/command.js").LeafDef;
 export declare const humanResolve: import("../../core/command.js").LeafDef;
 export declare const humanCancel: import("../../core/command.js").LeafDef;

package/dist/commands/human/queue.js

@@ -1,16 +1,15 @@
 import { existsSync } from 'node:fs';
-import { basename } from 'node:path';
+import { basename, join } from 'node:path';
 import { ApiError } from '../../api/index.js';
 import { defineLeaf } from '../../core/command.js';
 import { ticketDir } from '../../core/human/root.js';
 import { scanInbox } from '../../core/human/scan.js';
-import { parseDeck } from '../../core/human/deck-schema.js';
-import { deckPath, isResolved, reviewPath } from '../../core/human/convention.js';
-import { readJsonOrNull } from '../../core/fs-utils.js';
+import { pageManifestPath, isResolved, reviewPath } from '../../core/human/convention.js';
 import { InputError } from '../../core/io.js';
 import { paginate } from '../../core/pagination.js';
 import { cliClient, rethrowAsCliError } from '../api-client.js';
 import { filterVisibleReviewTickets } from '../../clients/inbox/review-visibility.js';
+import { readJsonOrNull } from '../../core/fs-utils.js';
 function toRef(n) {
     return { node_id: n.node_id, name: n.name, cwd: n.cwd, parent: n.parent, status: n.status };
 }
@@ -60,29 +59,36 @@ function askingNodeFor(jobId, byId) {
         return byId.get(bridge.parent) ?? bridge;
     return bridge;
 }
+/** `notify` enqueues a durable page with no bridge node at all — its run.json
+ *  is the manifest-based truth that distinguishes that intentional, workerless
+ *  ticket from an `ask`/`review` ticket whose bridge node was reaped. */
+function isWorkerlessTicket(dir) {
+    return readJsonOrNull(join(dir, 'run.json'))?.mode === 'notify';
+}
 function summarizeTicket(summary, nodes, byId) {
     const jobId = basename(summary.dir);
-    // Every crouter ticket lives directly in its bridge node directory. A stale
-    // ticket whose node was reaped is intentionally absent from the canvas view.
-    if (!byId.has(jobId))
+    const workerless = isWorkerlessTicket(summary.dir);
+    // A ticket that expects a bridge node but has none is a stale ticket whose
+    // node was reaped, intentionally absent from the canvas view. A workerless
+    // notify ticket never had one, so it renders with its node-derived fields
+    // omitted rather than being dropped as an orphan.
+    if (!workerless && !byId.has(jobId))
         return null;
-    const asking = askingNodeFor(jobId, byId);
+    const asking = workerless ? undefined : askingNodeFor(jobId, byId);
     const conversation = resolveConversation(asking, nodes);
-    const interactionCount = summary.kind === 'deck' ? readJsonOrNull(deckPath(summary.dir))?.interactions.length : undefined;
     const sourceLabel = readableSourceLabel(summary.source);
     return {
         id: summary.id,
-        job_id: jobId,
+        ...(workerless ? {} : { job_id: jobId }),
         dir: summary.dir,
         title: summary.title,
         subtitle: summary.subtitle,
-        kind: summary.kind === 'deck' ? summary.interactionKind ?? null : 'review',
+        kind: summary.kind,
         blocked_since: summary.blockedSince,
         ...(summary.claim !== undefined ? { claim_owner: summary.claim.owner } : {}),
         ...(sourceLabel !== undefined ? { source_label: sourceLabel } : {}),
         ...(asking !== undefined ? { asking_node_id: asking.node_id, asking_node_name: asking.name, cwd: asking.cwd } : {}),
         ...(conversation !== undefined ? { conversation_id: conversation.node_id, conversation_title: conversation.name } : {}),
-        ...(interactionCount !== undefined ? { interaction_count: interactionCount } : {}),
     };
 }
 function interactionDirForJob(jobId, byId) {
@@ -112,7 +118,7 @@ export const humanList = defineLeaf({
             { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: "Opaque token from a previous response's next_cursor. Omit on first call." },
         ],
         output: [
-            { name: 'items', type: 'object[]', required: true, constraint: 'Each: {id, dir, title, subtitle, kind, blocked_since}; subtitle is the required authored one-sentence summary. Enriched when derivable with claim_owner, source_label, asking_node_id/name, conversation_id/title, interaction_count. Oldest first.' },
+            { name: 'items', type: 'object[]', required: true, constraint: 'Each: {id, dir, title, subtitle, kind, blocked_since}; subtitle is the required authored one-sentence summary. Enriched when derivable with claim_owner, source_label, asking_node_id/name, conversation_id/title. Oldest first.' },
             { name: 'next_cursor', type: 'string | null', required: true, constraint: 'Pass on the next call to continue. null means no more items.' },
             { name: 'total', type: 'integer | null', required: true, constraint: 'Total pending interactions.' },
         ],
@@ -147,103 +153,37 @@ export const humanList = defineLeaf({
     },
 });
 // ---------------------------------------------------------------------------
-// deck detail (read-only)
+// resolve — non-interactive human answer
 // ---------------------------------------------------------------------------
-export const humanDeck = defineLeaf({
-    name: 'deck',
-    description: 'read one pending human deck',
-    whenToUse: 'you need the full questions/options for a pending human interaction',
-    help: {
-        name: 'human deck',
-        summary: 'read full pending deck detail for one human interaction job',
-        params: [{ kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'job_id from human ask/review/list.' }],
-        output: [
-            { name: 'id', type: 'string', required: true, constraint: 'Interaction job id.' },
-            { name: 'interactions', type: 'object[]', required: true, constraint: 'Deck interactions with required authored subtitles, bodies, options, and freetext policy.' },
-        ],
-        outputKind: 'object',
-        effects: ['Read-only: reads deck.json from the interaction dir resolved through the canvas node cwd.'],
-    },
-    run: async (input) => {
-        const jobId = input['job_id'];
-        const nodes = await fetchNodeRefs();
-        const byId = new Map(nodes.map((n) => [n.node_id, n]));
-        const { dir } = interactionDirForJob(jobId, byId);
-        if (isResolved(dir)) {
-            throw new InputError({ error: 'already_resolved', message: `interaction already resolved: ${jobId}`, field: 'job_id', next: 'Use `crtr human list` for pending interactions.' });
-        }
-        let deck;
-        try {
-            deck = parseDeck(deckPath(dir));
-        }
-        catch {
-            throw new InputError({ error: 'not_found', message: `no deck for interaction: ${jobId}`, field: 'job_id', next: 'Pass a pending job_id from `crtr human list`.' });
-        }
-        const asking = askingNodeFor(jobId, byId);
-        const conversation = resolveConversation(asking, nodes);
-        const sourceLabel = readableSourceLabel(deck.source);
-        const first = deck.interactions[0];
-        return {
-            id: jobId,
-            title: deck.title,
-            kind: first.kind ?? null,
-            subtitle: first.subtitle,
-            blocked_since: deck.source?.blockedSince ?? null,
-            ...(sourceLabel !== undefined ? { source_label: sourceLabel } : {}),
-            ...(asking !== undefined ? { asking_node_id: asking.node_id, asking_node_name: asking.name, cwd: asking.cwd } : {}),
-            ...(conversation !== undefined ? { conversation_id: conversation.node_id, conversation_title: conversation.name } : {}),
-            interaction_count: deck.interactions.length,
-            interactions: deck.interactions.map((it) => ({
-                id: it.id,
-                kind: it.kind ?? null,
-                title: it.title,
-                subtitle: it.subtitle,
-                ...(it.body !== undefined ? { body: it.body } : {}),
-                options: it.options.map((o) => ({ id: o.id, label: o.label, ...(o.description !== undefined ? { description: o.description } : {}) })),
-                allow_freetext: it.allowFreetext ?? false,
-                ...(it.preAnswered?.selectedOptionId !== undefined ? { default_option_id: it.preAnswered.selectedOptionId } : {}),
-            })),
-        };
-    },
-});
+/** Decode the stdin envelope only; the daemon validates every response against the page manifest. */
 function parseResolveBody(raw) {
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch (e) {
-        throw new InputError({ error: 'invalid_json', message: `stdin is not valid JSON: ${String(e)}`, field: 'stdin', next: 'Pass {"responses":[{"interaction_id":"..."}]} on stdin.' });
+        throw new InputError({ error: 'invalid_json', message: `stdin is not valid JSON: ${String(e)}`, field: 'stdin', next: 'Pass {"responses":{"<slot_id>":{...}}} on stdin.' });
     }
-    if (!Array.isArray(parsed.responses)) {
-        throw new InputError({ error: 'invalid_field', message: 'responses must be an array', field: 'responses', next: 'Pass {"responses":[{"interaction_id":"...","selected_option_ids":["..."]}]}.' });
+    const responses = parsed.responses;
+    if (typeof responses !== 'object' || responses === null || Array.isArray(responses)) {
+        throw new InputError({ error: 'invalid_field', message: 'responses must be an object keyed by slot id', field: 'responses', next: 'Pass {"responses":{"<slot_id>":{...}}}, or {"responses":{}} to acknowledge a page with no response slots.' });
     }
-    return parsed.responses.map((r) => {
-        if (r.interaction_id === undefined || r.interaction_id === '') {
-            throw new InputError({ error: 'invalid_field', message: 'each response needs interaction_id', field: 'responses', next: 'Include interaction_id for every response.' });
-        }
-        return {
-            id: r.interaction_id,
-            ...(r.selected_option_ids !== undefined ? { selectedOptionIds: r.selected_option_ids } : {}),
-            ...(r.selected_option_id !== undefined ? { selectedOptionId: r.selected_option_id } : {}),
-            ...(r.freetext !== undefined ? { freetext: r.freetext } : {}),
-            ...(r.option_comments !== undefined ? { optionComments: r.option_comments } : {}),
-        };
-    });
+    return responses;
 }
 export const humanResolve = defineLeaf({
     name: 'resolve',
-    description: 'resolve one human deck from stdin answers',
+    description: 'resolve one human page from stdin answers',
     whenToUse: 'an API client or local tool is submitting answers for a pending human interaction.',
     tier: 'hidden',
     help: {
         name: 'human resolve',
-        summary: 'resolve a pending deck with the given answers and deliver them to the asking node',
+        summary: 'resolve a pending page with the given answers and deliver them to the asking node',
         params: [
             { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'job_id from human ask/review/list.' },
-            { kind: 'stdin', name: 'body', required: true, constraint: 'JSON {responses:[{interaction_id, selected_option_ids?, freetext?}]}.' },
+            { kind: 'stdin', name: 'body', required: true, constraint: 'JSON {responses:{<slot_id>:{...}}} — one typed response object per response-bearing slot of the page.' },
         ],
         output: [
-            { name: 'resolved', type: 'boolean', required: true, constraint: 'True when this call answered and delivered the deck to the asking node.' },
+            { name: 'resolved', type: 'boolean', required: true, constraint: 'True when this call answered and delivered the page to the asking node.' },
             { name: 'job_id', type: 'string', required: true, constraint: 'Interaction job id.' },
             { name: 'reason', type: 'string', required: false, constraint: 'already_resolved or claimed when resolved is false.' },
         ],
@@ -255,8 +195,8 @@ export const humanResolve = defineLeaf({
         const nodes = await fetchNodeRefs();
         const byId = new Map(nodes.map((n) => [n.node_id, n]));
         const { dir, node } = interactionDirForJob(jobId, byId);
-        if (!existsSync(deckPath(dir))) {
-            throw new InputError({ error: 'not_found', message: `no deck for interaction: ${jobId}`, field: 'job_id', next: 'Pass a pending job_id from `crtr human list`.' });
+        if (!existsSync(pageManifestPath(dir))) {
+            throw new InputError({ error: 'not_found', message: `no page for interaction: ${jobId}`, field: 'job_id', next: 'Pass a pending job_id from `crtr human list`.' });
         }
         const responses = parseResolveBody(input['body']);
         // A published result on a live bridge may be an interrupted delivery. The
@@ -286,7 +226,7 @@ export const humanCancel = defineLeaf({
     help: {
         name: 'human cancel',
         summary: 'retract a pending ask/review you posed — drops it from the human inbox and retires the bridge node. Reach for this the moment a question goes stale (you answered it yourself, the situation changed) so a human is not left resolving a prompt whose answer no longer matters',
-        guide: 'Pass the job_id returned by `human ask`/`review`. Best-effort and idempotent: if the human already answered, or it was already canceled, it reports canceled:false with reason "already_resolved" and changes nothing. Cancellation races the human\'s submit; whichever wins is authoritative. The agent that posed the deck is almost always the one canceling it, so the caller is never messaged — only OTHER subscribers get a quiet deferred note that no answer is coming.',
+        guide: 'Pass the job_id returned by `human ask`/`review`. Best-effort and idempotent: if the human already answered, or it was already canceled, it reports canceled:false with reason "already_resolved" and changes nothing. Cancellation races the human\'s submit; whichever wins is authoritative. The agent that posed the question is almost always the one canceling it, so the caller is never messaged — only OTHER subscribers get a quiet deferred note that no answer is coming.',
         params: [
             { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Node id of the interaction to cancel — the job_id returned by ask/review.' },
             { kind: 'flag', name: 'reason', type: 'string', required: false, constraint: 'Optional short note delivered to subscribers explaining why it was retracted.' },
@@ -316,7 +256,7 @@ export const humanCancel = defineLeaf({
         const idir = ticketDir(jobId);
         // Nothing live to cancel: the bridge is already terminal, or the ticket
         // never carried a request descriptor.
-        const hasDescriptor = existsSync(deckPath(idir)) || existsSync(reviewPath(idir));
+        const hasDescriptor = existsSync(pageManifestPath(idir)) || existsSync(reviewPath(idir));
         if (isTerminalBridge(node.status) || !hasDescriptor) {
             return { canceled: false, job_id: jobId, reason: 'already_resolved' };
         }

package/dist/commands/human/shared.d.ts

@@ -1,10 +1,16 @@
-export declare const BODY_PATH_CONTRACT: string;
-export declare const DECK_SCHEMA_HINT: string;
+export interface PageHelpText {
+    authoring: string;
+    pageHint: string;
+}
+/** Invocation-local page capability and authoring contract for `human -h`.
+ * The CLI process rebuilds command help each time, so config changes appear on
+ * the next invocation without a parallel documentation surface. */
+export declare function pageHelpText(): PageHelpText;
 /**
  * Crouter's private per-interaction record. Reduced to the delivery essentials:
  * the mode that identifies the ticket and the bridge node id it delivers back to.
- * The ticket store owns every public request/result/output path (deck.json,
- * response.json, review.json); crouter never records pane ids or output paths.
+ * The ticket store owns every public request/result/output path (page.md/page.html,
+ * page.json, response.json, review.json); crouter never records pane ids or output paths.
  *
  */
 export interface RunRecord {