@north-light/crouter 0.3.197 → 0.3.198

package/dist/commands/human/doc.js

@@ -5,7 +5,6 @@ import { defineBranch, defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { readConfig } from '../../core/config.js';
 import { derivePageManifest } from '../../core/human/page.js';
-import { checkMarkdown, renderMarkdown } from '../../core/termrender/termrender.js';
 function documentSource(input, context) {
     const path = input['path'];
     const body = input['body'];
@@ -13,8 +12,8 @@ function documentSource(input, context) {
     if (path === undefined && !stdinProvided) {
         throw new InputError({
             error: 'missing_parameter',
-            message: 'provide exactly one document source: PATH or stdin',
-            next: 'Run `crtr human doc check -h` or `crtr human doc render -h` and provide a path or pipe a document on stdin.',
+            message: 'provide exactly one HTML page source: PATH or stdin',
+            next: 'Run `crtr human doc check -h` and provide a complete HTML page path or pipe one on stdin.',
         });
     }
     if (path !== undefined && path !== '-' && stdinProvided && body.trim() !== '') {
@@ -22,7 +21,7 @@ function documentSource(input, context) {
             error: 'bad_invocation',
             message: 'both a positional path and piped stdin were provided',
             field: 'path, body',
-            next: 'Pass exactly one document source: either PATH or piped stdin, not both.',
+            next: 'Pass exactly one page source: either PATH or piped stdin, not both.',
         });
     }
     if (path === undefined || path === '-')
@@ -33,38 +32,22 @@ function documentSource(input, context) {
             error: 'file_not_found',
             message: `file not found: ${abs}`,
             field: 'path',
-            next: 'Provide a path to an existing markdown or HTML file, or pipe a document on stdin.',
+            next: 'Provide a path to an existing complete HTML page or pipe one on stdin.',
         });
     }
     return { body: readFileSync(abs, 'utf8'), path: abs };
 }
-function markdownSource(input, context) {
-    return documentSource(input, context).body;
-}
-function pageDialect(source) {
-    const extension = source.path?.toLowerCase();
-    if (extension?.endsWith('.html') || extension?.endsWith('.htm'))
-        return 'html';
-    if (/^\s*<!doctype\b/i.test(source.body) || /^\s*<html(?:\s|>)/i.test(source.body))
-        return 'html';
-    if (source.body.startsWith('---'))
-        return 'md';
-    return undefined;
-}
-function checkPage(source, dialect) {
+function checkPage(source) {
     const config = readConfig('user');
-    if (dialect === 'html' && !config.html_pages) {
-        return { ok: false, error: 'HTML page validation requires the user-scope html_pages capability flag to be enabled (html_pages is false).' };
-    }
     let tempDir;
     try {
         const sourcePath = source.path ?? (() => {
             tempDir = mkdtempSync(join(tmpdir(), 'crtr-human-doc-'));
-            const path = join(tempDir, dialect === 'html' ? 'page.html' : 'page.md');
+            const path = join(tempDir, 'page.html');
             writeFileSync(path, source.body, 'utf8');
             return path;
         })();
-        derivePageManifest(sourcePath, dialect, config.page_components);
+        derivePageManifest(sourcePath, 'html', config.page_components);
         return { ok: true };
     }
     catch (error) {
@@ -77,68 +60,32 @@ function checkPage(source, dialect) {
 }
 const humanDocCheck = defineLeaf({
     name: 'check',
-    description: 'validate a directive-flavored markdown body or page source',
-    whenToUse: 'validating a page source or review body before submitting it.',
+    description: 'validate a complete HTML page source',
+    whenToUse: 'validating an authored page before submitting it.',
     help: {
         name: 'human doc check',
-        summary: 'validate directive-flavored markdown or a page through the managed renderer and page schemas',
-        guide: 'Plain markdown is checked by the pinned renderer. A file with page front matter or an HTML document is parsed as a page; HTML page validation requires the user-scope html_pages capability flag.',
+        summary: 'validate a complete HTML page through page schemas',
         params: [
-            { kind: 'positional', name: 'path', type: 'path', required: false, constraint: 'Markdown or HTML file to validate. Files ending in .html/.htm, HTML documents beginning with a doctype or <html, and markdown beginning with --- front matter are checked as pages. Provide exactly one of PATH or stdin; use - to read stdin.' },
-            { kind: 'stdin', name: 'body', required: false, constraint: 'Markdown or HTML to validate. Provide exactly one of piped stdin or PATH.' },
+            { kind: 'positional', name: 'path', type: 'path', required: false, constraint: 'Complete HTML page to validate. Provide exactly one of PATH or stdin; use - to read stdin.' },
+            { kind: 'stdin', name: 'body', required: false, constraint: 'Complete HTML page to validate. Provide exactly one of piped stdin or PATH.' },
         ],
         output: [
-            { name: 'ok', type: 'boolean', required: true, constraint: 'True when the markdown is valid.' },
-            { name: 'error', type: 'string', required: false, constraint: 'The renderer or page-parser validation error when ok is false.' },
+            { name: 'ok', type: 'boolean', required: true, constraint: 'True when the complete HTML page is valid.' },
+            { name: 'error', type: 'string', required: false, constraint: 'The page-parser validation error when ok is false.' },
         ],
         outputKind: 'object',
-        effects: ['Read-only: invokes the private managed renderer or page parser to validate the supplied document.'],
-    },
-    run: async (input, context) => {
-        const source = documentSource(input, context);
-        const dialect = pageDialect(source);
-        if (dialect !== undefined)
-            return checkPage(source, dialect);
-        return checkMarkdown(source.body);
-    },
-});
-const humanDocRender = defineLeaf({
-    name: 'render',
-    description: 'render a directive-flavored markdown body',
-    whenToUse: 'previewing how a page or review body renders before submitting it.',
-    help: {
-        name: 'human doc render',
-        summary: 'render directive-flavored markdown through the pinned managed renderer',
-        guide: 'The pinned renderer runs from a private managed venv and is not on PATH, so this is the only way to render a page or review body before submitting it.',
-        params: [
-            { kind: 'positional', name: 'path', type: 'path', required: false, constraint: 'Markdown file to render. Provide exactly one of PATH or stdin; use - to read stdin.' },
-            { kind: 'stdin', name: 'body', required: false, constraint: 'Markdown to render. Provide exactly one of piped stdin or PATH.' },
-            { kind: 'flag', name: 'width', type: 'int', required: false, default: process.stdout.columns || 100, constraint: 'Render width in columns. Default: current stdout width, or 100.' },
-            { kind: 'flag', name: 'color', type: 'bool', required: false, default: true, constraint: 'Emit ANSI color. Default true; false strips ANSI escape sequences.' },
-        ],
-        output: [
-            { name: 'lines', type: 'string[]', required: true, constraint: 'Rendered terminal lines in display order.' },
-            { name: 'width', type: 'integer', required: true, constraint: 'The render width in columns.' },
-        ],
-        outputKind: 'object',
-        effects: ['Read-only: invokes the private managed renderer to render the supplied body.'],
-    },
-    run: async (input, context) => {
-        const width = input['width'];
-        const color = input['color'];
-        const lines = renderMarkdown(markdownSource(input, context), width);
-        return { lines: color ? lines : lines.map((line) => line.replace(/\x1b\[[0-9;]*[A-Za-z]/g, '')), width };
+        effects: ['Read-only: invokes the page parser to validate the supplied complete HTML page.'],
     },
-    render: (result) => result['lines'].join('\n'),
+    run: async (input, context) => checkPage(documentSource(input, context)),
 });
 export const humanDoc = defineBranch({
     name: 'doc',
-    description: 'validate or render directive-flavored markdown bodies',
-    whenToUse: 'validating or previewing a directive-flavored markdown body before submitting it.',
+    description: 'validate authored HTML pages',
+    whenToUse: 'validating an authored HTML page before submitting it.',
     help: {
         name: 'human doc',
-        summary: 'validate and render directive-flavored markdown bodies',
-        model: 'Both leaves read exactly one body from a path or stdin through the private managed renderer.',
+        summary: 'validate authored HTML pages',
+        model: 'The check leaf reads exactly one complete HTML page from a path or stdin.',
     },
-    children: [humanDocCheck, humanDocRender],
+    children: [humanDocCheck],
 });

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

@@ -0,0 +1,2 @@
+import { type BranchDef } from '../../core/command.js';
+export declare const humanHtml: BranchDef;

package/dist/commands/human/html.js

@@ -0,0 +1,81 @@
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { stateBlock } from '../../core/help.js';
+import { InputError } from '../../core/io.js';
+import { readConfig } from '../../core/config.js';
+import { componentKinds, renderComponentCatalog, renderComponentContract } from '../../core/human/component-docs.js';
+import { pageComponentKinds } from '../../core/human/page-catalog.js';
+function productComponents() {
+    return readConfig('user').page_components;
+}
+function productKinds() {
+    return pageComponentKinds(productComponents());
+}
+function componentKindState() {
+    const kinds = componentKinds(productKinds());
+    return stateBlock('kinds', { count: kinds.length }, kinds.join('\n'));
+}
+const humanHtmlList = defineLeaf({
+    name: 'list',
+    description: 'list page components for selection',
+    whenToUse: 'choosing which page component to put in an authored HTML page.',
+    help: {
+        name: 'human html list',
+        summary: 'list page components for selection',
+        inputNote: 'No input parameters.',
+        output: [
+            { name: 'catalog', type: 'markdown', required: true, constraint: 'One concise selection entry per built-in and product-registered component; no component field schemas.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Points to `crtr human html show <kind>` for one selected component contract.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async () => ({
+        catalog: renderComponentCatalog(productComponents()),
+        follow_up: 'Use `crtr human html show <kind>` for one component contract.',
+    }),
+    render: (result) => `${String(result['catalog'])}\n\n${String(result['follow_up'])}`,
+});
+const humanHtmlShow = defineLeaf({
+    name: 'show',
+    description: 'show one page component contract',
+    whenToUse: 'authoring or validating one selected page component and needing its exact config or response contract.',
+    help: {
+        name: 'human html show',
+        summary: 'show one page component contract',
+        params: [
+            { kind: 'positional', name: 'kind', type: 'string', required: true, constraint: 'Component kind from the live <kinds> catalog below.' },
+        ],
+        output: [
+            { name: 'kind', type: 'string', required: true, constraint: 'The selected component kind.' },
+            { name: 'contract', type: 'markdown', required: true, constraint: 'Hand-written config, response, and display/response-bearing contract for that component.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+        dynamicState: componentKindState,
+    },
+    run: async (input) => {
+        const kind = input['kind'];
+        const contract = renderComponentContract(kind, productComponents());
+        if (contract === undefined) {
+            throw new InputError({
+                error: 'unknown_component',
+                message: `unknown page component kind "${kind}"`,
+                field: 'kind',
+                next: 'Run `crtr human html show -h` and choose a kind from its live catalog.',
+            });
+        }
+        return { kind, contract };
+    },
+    render: (result) => String(result['contract']),
+});
+export const humanHtml = defineBranch({
+    name: 'html',
+    description: 'discover HTML page components and contracts',
+    whenToUse: 'authoring an HTML page and choosing a component or needing one component’s exact contract.',
+    help: {
+        name: 'human html',
+        summary: 'discover HTML page components and contracts',
+        model: 'List is the selection catalog; show owns the full config and response contract for one selected component.',
+    },
+    children: [humanHtmlList, humanHtmlShow],
+});

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

@@ -2,10 +2,11 @@ import type { PageSource } from '../../core/human/page-schema.js';
 /** Provenance for crouter tickets. Ticket *identity* comes from the bridge node
  * 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 pages match them.
- * `nodeId` is stamped even when the daemon is unreachable — losing the label is
- * survivable, losing machine attribution is not. */
+ * `sessionName` is a presentation label only, while `profileName` lets product
+ * consumers resolve the applet or worker identity behind the ticket. Review
+ * tickets stamp the same provenance (`core/review/realize.ts`), so pages match
+ * them. `nodeId` is stamped even when the daemon is unreachable — losing the
+ * labels is survivable, losing machine attribution is not. */
 export declare function sourceStamp(): Promise<PageSource>;
 export declare const humanAsk: import("../../core/command.js").LeafDef;
 export declare const humanNotify: import("../../core/command.js").LeafDef;

package/dist/commands/human/prompts.js

@@ -1,20 +1,15 @@
-/**
- * Prompt-design gap: a person opens asks from background agents without the
- * task or conversation context. Human-ask help therefore teaches agents to
- * make every interruption self-contained and answerable before its evidence.
- */
 import { defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { cliClient } from '../api-client.js';
 import { extname, join } from 'node:path';
 import { randomBytes } from 'node:crypto';
-import { rmSync } from 'node:fs';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { readConfig } from '../../core/config.js';
 import { markStopSignal } from '../../core/runtime/stop-signals.js';
 import { atomicWriteJson } from '../../core/human/convention.js';
 import { ticketDir } from '../../core/human/root.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 { pageHelpText, resolveMaxPanes } from './shared.js';
@@ -26,76 +21,45 @@ function askingNode() {
 /** Provenance for crouter tickets. Ticket *identity* comes from the bridge node
  * 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 pages match them.
- * `nodeId` is stamped even when the daemon is unreachable — losing the label is
- * survivable, losing machine attribution is not. */
+ * `sessionName` is a presentation label only, while `profileName` lets product
+ * consumers resolve the applet or worker identity behind the ticket. Review
+ * tickets stamp the same provenance (`core/review/realize.ts`), so pages match
+ * them. `nodeId` is stamped even when the daemon is unreachable — losing the
+ * labels is survivable, losing machine attribution is not. */
 export async function sourceStamp() {
     const nodeId = askingNode();
     if (nodeId === null || nodeId === '')
         return {};
     try {
-        const sessionName = (await cliClient().getNode(nodeId)).name.trim();
-        return sessionName === '' ? { nodeId } : { nodeId, sessionName };
+        const client = cliClient();
+        const node = await client.getNode(nodeId);
+        const sessionName = node.name.trim();
+        const profileName = node.profile_id === null
+            ? undefined
+            : (await client.getProfile(node.profile_id)).name;
+        return {
+            nodeId,
+            ...(sessionName === '' ? {} : { sessionName }),
+            ...(profileName === undefined ? {} : { profileName }),
+        };
     }
     catch {
         return { nodeId };
     }
 }
-function requireAskTitle(title) {
-    if (title !== undefined)
-        return title;
-    throw new InputError({
-        error: 'missing_parameter',
-        message: 'stdin questions require a non-empty --title',
-        field: 'title',
-        next: 'Retry with a short --title naming the topic being decided.',
-    });
-}
-function requireSubtitle(subtitle, field = 'subtitle') {
-    if (subtitle !== undefined && subtitle.trim() !== '')
-        return subtitle.trim();
-    throw new InputError({
-        error: 'missing_parameter',
-        message: 'a non-empty subtitle is required',
-        field,
-        next: 'Write one plain-English sentence stating the decision, recommendation or status, and stakes.',
-    });
-}
 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}"`,
+        message: `--page must name an HTML page; received "${sourceFile}"`,
         field: 'page',
-        next: 'Use a Markdown page (.md) or an HTML page (.html or .htm).',
+        next: 'Write the page at `$CRTR_CONTEXT_DIR/pages/<name>.html`, then retry with --page PATH.',
     });
 }
-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 config.page_components;
-}
-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.',
-    });
+function pageProductKinds() {
+    return readConfig('user').page_components;
 }
 function submitAuthoredPage(submit) {
     try {
@@ -112,10 +76,50 @@ function submitAuthoredPage(submit) {
         });
     }
 }
+function writePipedPage(document) {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-human-page-'));
+    const path = join(dir, 'page.html');
+    writeFileSync(path, document, { encoding: 'utf8', mode: 0o600 });
+    return { dir, path };
+}
+/** Resolve exactly one authored page input. Piped bytes are materialized so
+ * both input forms follow the same page preparation and validation path. */
+function pageInput(input) {
+    const file = input['page'];
+    const documentRaw = input['document'];
+    // Optional stdin arrives as an empty string when a caller redirects an empty
+    // stream. It is not a page source and must not conflict with --page.
+    const document = typeof documentRaw === 'string' && documentRaw.trim() !== '' ? documentRaw : undefined;
+    if (file !== undefined && document !== undefined) {
+        throw new InputError({
+            error: 'bad_invocation',
+            message: 'received both --page and a piped page document',
+            field: 'page, document',
+            next: 'Pass exactly one page source: --page PATH or the document on stdin.',
+        });
+    }
+    if (file === undefined && document === undefined) {
+        throw new InputError({
+            error: 'missing_parameter',
+            message: 'a page source is required',
+            field: 'page, document',
+            next: 'Pass exactly one page source: --page PATH or the document on stdin.',
+        });
+    }
+    if (file !== undefined) {
+        if (typeof file !== 'string')
+            throw new InputError({ error: 'invalid_type', message: '--page must be a path', field: 'page', next: 'Retry with --page PATH.' });
+        return { sourceFile: file };
+    }
+    if (typeof document !== 'string')
+        throw new InputError({ error: 'invalid_type', message: 'stdin must contain a page document', field: 'document', next: 'Pipe the page document on stdin.' });
+    const temp = writePipedPage(document);
+    return { sourceFile: temp.path, tempDir: temp.dir };
+}
 /** 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
- *  agents to repeat a screen-specific gesture back to a reader who may be on a
- *  different surface entirely. */
+ * their inbox is theirs, not the agent's — naming a shortcut here only teaches
+ * agents to repeat a screen-specific gesture back to a reader who may be on a
+ * different surface entirely. */
 function queuedFollowUp() {
     return 'Queued for the human. Their answer is pushed to your inbox and wakes you when they respond — never poll, verify it opened, or block.';
 }
@@ -128,20 +132,15 @@ export const humanAsk = defineLeaf({
     whenToUse: 'you would otherwise lay a decision, a set of options, or a question out for the user as prose — reach for this instead, for anything from a quick yes/no to a judgment-heavy call: gating a handoff, merge, deploy, destructive/irreversible operation, or real budget on an explicit human sign-off (offer Yes/No options), reviewing all the requirements before building, choosing among implementation patterns, walking a list of risks and deciding what to do about each, settling a naming or scope question, picking which of several findings to act on. Works for open-ended asks too (set `allowFreetext`, offer a few `options` as starting points).',
     help: {
         name: 'human ask',
-        summary: "submit a decision ticket to crouter's inbox; returns a job handle immediately.",
-        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'),
+        summary: "submit a decision ticket to crouter's inbox; returns a job handle immediately",
+        guide: 'Page authoring: `crtr human -h`.',
         params: [
-            { 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.` },
+            { kind: 'stdin', name: 'document', required: false, allowPositional: false, constraint: 'Page bytes from stdin. Provide exactly one of stdin or --page PATH.' },
+            { kind: 'flag', name: 'page', type: 'path', required: false, constraint: `${PAGE_HELP.pageHint} Provide exactly one of --page or stdin.` },
         ],
         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 page.md or page.html, page.json, run.json, and response.json.' },
+            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding 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',
@@ -151,48 +150,10 @@ export const humanAsk = defineLeaf({
         ],
     },
     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 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 --page, not both',
-                next: 'Retry with --title, --subtitle, and a piped question body, or with --page PATH alone.',
-            });
-        }
-        if (question === undefined && pageInput === undefined) {
-            throw new InputError({
-                error: 'missing_parameter',
-                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 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;
-        }
+        const { sourceFile, tempDir } = pageInput(input);
         try {
             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 prepared = submitAuthoredPage(() => preparePage({ sourceFile, dialect: pageDialect(sourceFile), source, productKinds: pageProductKinds() }));
             const cwd = process.cwd();
             const jobId = (await cliClient().createHumanBridge({ kind: 'human', parent: askingNode(), cwd, name: 'human-ask' })).node_id;
             const idir = ticketDir(jobId);
@@ -220,19 +181,14 @@ 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. Shorthand bodies are directive-flavored Markdown; validate authored pages with `crtr human doc check`.',
-            PAGE_HELP.authoring,
-        ].join('\n\n'),
+        guide: 'Page authoring: `crtr human -h`.',
         params: [
-            { 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.` },
+            { kind: 'stdin', name: 'document', required: false, allowPositional: false, constraint: 'Page bytes from stdin. Provide exactly one of stdin or --page PATH.' },
+            { kind: 'flag', name: 'page', type: 'path', required: false, constraint: `${PAGE_HELP.pageHint} Provide exactly one of --page or stdin.` },
         ],
         output: [
             { 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.' },
+            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding page.html, page.json, and run.json.' },
         ],
         outputKind: 'object',
         effects: [
@@ -240,38 +196,10 @@ export const humanNotify = defineLeaf({
         ],
     },
     run: async (input) => {
-        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'];
-        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;
-        }
+        const { sourceFile, tempDir } = pageInput(input);
         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 prepared = submitAuthoredPage(() => preparePage({ sourceFile, dialect: pageDialect(sourceFile), source, productKinds: pageProductKinds() }));
             const id = `nfy-${randomBytes(4).toString('hex')}`;
             const rc = { mode: 'notify' };
             atomicWriteJson(join(ticketDir(id), 'run.json'), rc);
@@ -286,8 +214,8 @@ export const humanNotify = defineLeaf({
 });
 // ---------------------------------------------------------------------------
 // show (no job, non-blocking passthrough) — passive live document display, NOT
-// a ticket surface. Retained per the tmux-inbox cutover: `display()` puts a
-// file live in a watch pane and never enqueues anything.
+// a ticket surface. `display()` puts a file live in a watch pane and never
+// enqueues anything.
 // ---------------------------------------------------------------------------
 export const humanShow = defineLeaf({
     name: 'show',
@@ -296,7 +224,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. To put a rich document in front of the human as a durable inbox page, use `crtr human notify --page PATH`.',
+        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). 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/shared.d.ts

@@ -1,17 +1,16 @@
 export interface PageHelpText {
     authoring: string;
+    componentSelection: readonly string[];
     pageHint: string;
+    rootUseWhen: 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;
+/** The one HTML authoring model for `human -h`. */
+export declare function pageHelpText(htmlSurface?: boolean): 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 (page.md/page.html,
+ * The ticket store owns every public request/result/output path (page.html,
  * page.json, response.json, review.json); crouter never records pane ids or output paths.
- *
  */
 export interface RunRecord {
     mode: 'ask' | 'notify' | 'review';