@north-light/crouter 0.3.215 → 0.3.217

package/dist/clients/inbox/__tests__/serial/mount-panel.test.js

@@ -14,8 +14,8 @@ optionsPanel.handleKey('', enter);
 optionsPanel.handleKey('y', key());
 assert.deepEqual(optionResponses, { choice: { selectedOptionIds: ['yes'], comments: [{ id: 'option:yes', anchor: { kind: 'option', optionId: 'yes' }, text: 'ship it' }] } });
 optionsPanel.unmount();
-// Multi-select empty Enter remains inert; selection confirmation lands on Summary before submit.
-const multi = manifest([{ id: 'toppings', kind: 'options', step: 0, config: { mode: 'multi', options: [{ id: 'mush', label: 'Mushroom' }, { id: 'onion', label: 'Onion' }] } }]);
+// A required multi-select refuses an empty Enter; selection confirmation lands on Summary before submit.
+const multi = manifest([{ id: 'toppings', kind: 'options', step: 0, config: { mode: 'multi', required: true, options: [{ id: 'mush', label: 'Mushroom' }, { id: 'onion', label: 'Onion' }] } }]);
 let multiResponses;
 const multiPanel = mountPanel({ manifest: multi, cols: 80, rows: 24, onComplete: (r) => { multiResponses = r; } });
 multiPanel.handleKey('', enter);

package/dist/clients/inbox/tui/input.js

@@ -1,6 +1,6 @@
 import { isResponseBearingSlot } from '../../../core/human/page-schema.js';
 import { panItemReview, verticalCursor, wordLeftIndex, wordRightIndex } from './render.js';
-import { commentAnchors, commentIdFor, pageComplete, slotActions, slotAnswered, terminalAnswerable } from './slots.js';
+import { commentAnchors, commentIdFor, pageComplete, responseAnswers, slotActions, slotAnswered, terminalAnswerable } from './slots.js';
 /** Only a single-mode options/cards pick jumps ahead; a table pick leaves the user on the table. */
 const autoAdvances = (slot, mode) => mode === 'single' && (slot.kind === 'options' || slot.kind === 'cards');
 export function handleKeypress(input, key, state, render, exit) {
@@ -143,18 +143,22 @@ function handleItemReview(input, key, state, render, exit) {
             render();
             return;
         }
-        if (slot.kind === 'table' && terminalAnswerable(slot)) {
-            const r = responseFor(slot, state.responses.get(slot.id));
-            setResponse(state, slot, r);
-            advanceToNextIncomplete(state);
-            render();
-            return;
-        }
         if (slotAnswered(state, slot)) {
             advanceToNextIncomplete(state);
             render();
             return;
         }
+        // Enter settles a question whose current value already answers it: an optional picker
+        // left empty is a real answer, not a skipped one.
+        if (terminalAnswerable(slot)) {
+            const settled = responseFor(slot, state.responses.get(slot.id));
+            if (responseAnswers(state, slot, settled)) {
+                setResponse(state, slot, settled);
+                advanceToNextIncomplete(state);
+                render();
+                return;
+            }
+        }
         if (isResponseBearingSlot(slot)) {
             state.hint = terminalAnswerable(slot) ? 'Select at least one option (space to toggle), or q to go back' : 'This must be answered in Northlight';
             render();

package/dist/clients/inbox/tui/slots.d.ts

@@ -1,4 +1,4 @@
-import type { CommentAnchor, PageManifest, PageSlot, TableConfig } from '../../../core/human/page-schema.js';
+import type { CommentAnchor, PageManifest, PageSlot, SlotResponse, TableConfig } from '../../../core/human/page-schema.js';
 import type { TuiState } from './types.js';
 export type SelectGroup = 'option' | 'card' | 'row' | 'column';
 export type ActionRow = {
@@ -24,6 +24,8 @@ export declare function describeSlot(slot: PageSlot): string;
 export declare function terminalAnswerable(slot: PageSlot): boolean;
 export declare function slotActions(slot: PageSlot): ActionRow[];
 export declare function tableMarkdown(config: TableConfig): string;
+/** Whether this value would be accepted as the slot's answer — the same reading crtrd applies on submit. */
+export declare function responseAnswers(state: Pick<TuiState, 'manifest'>, slot: PageSlot, response: SlotResponse): boolean;
 export declare function slotAnswered(state: TuiState, slot: PageSlot): boolean;
 export declare function pageComplete(state: Pick<TuiState, 'manifest' | 'responses'>): boolean;
 export declare function commentIdFor(anchor: CommentAnchor): string;

package/dist/clients/inbox/tui/slots.js

@@ -88,17 +88,23 @@ export function tableMarkdown(config) {
     const divider = `| ${config.columns.map((column) => column.align === 'right' ? '---:' : '---').join(' | ')} |`;
     return [header, divider, ...(config.rows ?? []).map((row) => `| ${config.columns.map((column) => escapeCell(row.cells[column.id], column.mono === true)).join(' | ')} |`)].join('\n');
 }
-export function slotAnswered(state, slot) {
-    if (!terminalAnswerable(slot) || slot.id === undefined || !state.responses.has(slot.id))
+/** Whether this value would be accepted as the slot's answer — the same reading crtrd applies on submit. */
+export function responseAnswers(state, slot, response) {
+    if (slot.id === undefined)
         return false;
     try {
-        validatePartialPageResponses(state.manifest, { [slot.id]: state.responses.get(slot.id) });
+        validatePartialPageResponses(state.manifest, { [slot.id]: response });
         return true;
     }
     catch {
         return false;
     }
 }
+export function slotAnswered(state, slot) {
+    if (!terminalAnswerable(slot) || slot.id === undefined || !state.responses.has(slot.id))
+        return false;
+    return responseAnswers(state, slot, state.responses.get(slot.id));
+}
 export function pageComplete(state) {
     if (state.manifest.slots.some((slot) => isResponseBearingSlot(slot) && !terminalAnswerable(slot)))
         return false;

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

@@ -77,6 +77,6 @@ export declare function overlayParam(name: string, overrides?: Partial<FlagParam
  *  happening. Same field, same prose, two flag names that cannot be confused. */
 export declare const DOC_RATIONALE_CONSTRAINT = "Frontmatter rationale \u2014 the observed agent failure that made this doc necessary. Maintainer-facing only: never ships in any delivered surface (boot render, on-read injection, `memory read` content), visible only via `memory read --frontmatter`. Omitting the flag preserves an existing rationale unchanged.";
 export declare const GUIDE_SURFACES = "Every doc appears in its directory\u2019s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing \u2014 entries declaring WHEN the doc delivers and how much. Events: `boot` delivers in the boot catalog every agent sees; `workspace-open` delivers in first-message context when cwd/profile mounts the doc\u2019s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file\u2019s absolute path and basename, `./`-anchored globs vs its path relative to the store\u2019s owning repo dir, `match-frontmatter` predicates over the read file\u2019s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc\u2019s canonical name, `./` anchored to this doc\u2019s own name directory); `command` fires when a matching shell command runs (globs vs the whole command string, `*` crossing `/`). `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Each entry is paid by every future agent it fires on, so default down: no surfaces at all is correct for reference depth reached through listings and [[links]], and when a doc fits in a single sentence, deliver `content` directly \u2014 a `preview` routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.";
-export declare const GUIDE_ROUTING_LINE = "The routing line (--when-and-why-to-read) is the only text an agent reads before deciding to load the doc. The test for its because-clause: if it can be derived by paraphrasing the doc\u2019s advice, it is a restatement, not a payoff \u2014 a real payoff names a consequence in the reader\u2019s world that the document itself never asserts. Bad: \"because only genuine first principles belong in taste memory.\" Bad: \"because keeping the test loop fast and free of speculative tests protects the development pace\" \u2014 the doc\u2019s rule as an outcome, derivable straight from its advice. Good: \"because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation.\" Someone mid-task who has not read the doc must be able to decide from this line alone whether the read is worth it. If you cannot name the concrete situation that triggers it, you do not yet understand the memory \u2014 ask the user one sharp question instead of improvising.";
+export declare const GUIDE_ROUTING_LINE = "The routing line (--when-and-why-to-read) is the only text an agent reads before deciding to load the doc. The test for its when-clause: it names an observable circumstance in the reader\u2019s current work, not the doc\u2019s topic reworded as an activity. If the WHEN can be inferred from the title alone, it is not a real trigger. Bad on a todo list: \"When planning or prioritizing work across this profile.\" Good: \"When the user mentions something from their todos, or asks what is still outstanding across this profile.\" The test for its because-clause: if it can be derived by paraphrasing the doc\u2019s advice, it is a restatement, not a payoff \u2014 a real payoff names a consequence in the reader\u2019s world that the document itself never asserts. Bad: \"because only genuine first principles belong in taste memory.\" Bad: \"because keeping the test loop fast and free of speculative tests protects the development pace\" \u2014 the doc\u2019s rule as an outcome, derivable straight from its advice. Good: \"because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation.\" Someone mid-task who has not read the doc must be able to decide from this line alone whether the read is worth it. If you cannot name the concrete situation that triggers it, you do not yet understand the memory \u2014 ask the user one sharp question instead of improvising.";
 export declare const GUIDE_PREDICATE_VOCABULARY = "Gate and match-frontmatter share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.";
 export declare const GUIDE_DOC_LINKS = "Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name \u2014 the same identifier `crtr memory read` takes. A bare directory name is a valid link too: following it returns that directory\u2019s listing, a browse entrance rather than a doc. Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document or directory, and `crtr memory read` lists a doc\u2019s resolvable links alongside its body. There is no alias or label form.";

package/dist/commands/memory/shared.js

@@ -343,6 +343,6 @@ export function overlayParam(name, overrides = {}, extraConstraint) {
  *  happening. Same field, same prose, two flag names that cannot be confused. */
 export const DOC_RATIONALE_CONSTRAINT = 'Frontmatter rationale \u2014 the observed agent failure that made this doc necessary. Maintainer-facing only: never ships in any delivered surface (boot render, on-read injection, `memory read` content), visible only via `memory read --frontmatter`. Omitting the flag preserves an existing rationale unchanged.';
 export const GUIDE_SURFACES = 'Every doc appears in its directory’s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing — entries declaring WHEN the doc delivers and how much. Events: `boot` delivers in the boot catalog every agent sees; `workspace-open` delivers in first-message context when cwd/profile mounts the doc’s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file’s absolute path and basename, `./`-anchored globs vs its path relative to the store’s owning repo dir, `match-frontmatter` predicates over the read file’s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc’s canonical name, `./` anchored to this doc’s own name directory); `command` fires when a matching shell command runs (globs vs the whole command string, `*` crossing `/`). `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Each entry is paid by every future agent it fires on, so default down: no surfaces at all is correct for reference depth reached through listings and [[links]], and when a doc fits in a single sentence, deliver `content` directly — a `preview` routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.';
-export const GUIDE_ROUTING_LINE = 'The routing line (--when-and-why-to-read) is the only text an agent reads before deciding to load the doc. The test for its because-clause: if it can be derived by paraphrasing the doc\u2019s advice, it is a restatement, not a payoff \u2014 a real payoff names a consequence in the reader\u2019s world that the document itself never asserts. Bad: "because only genuine first principles belong in taste memory." Bad: "because keeping the test loop fast and free of speculative tests protects the development pace" \u2014 the doc\u2019s rule as an outcome, derivable straight from its advice. Good: "because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation." Someone mid-task who has not read the doc must be able to decide from this line alone whether the read is worth it. If you cannot name the concrete situation that triggers it, you do not yet understand the memory \u2014 ask the user one sharp question instead of improvising.';
+export const GUIDE_ROUTING_LINE = 'The routing line (--when-and-why-to-read) is the only text an agent reads before deciding to load the doc. The test for its when-clause: it names an observable circumstance in the reader\u2019s current work, not the doc\u2019s topic reworded as an activity. If the WHEN can be inferred from the title alone, it is not a real trigger. Bad on a todo list: "When planning or prioritizing work across this profile." Good: "When the user mentions something from their todos, or asks what is still outstanding across this profile." The test for its because-clause: if it can be derived by paraphrasing the doc\u2019s advice, it is a restatement, not a payoff \u2014 a real payoff names a consequence in the reader\u2019s world that the document itself never asserts. Bad: "because only genuine first principles belong in taste memory." Bad: "because keeping the test loop fast and free of speculative tests protects the development pace" \u2014 the doc\u2019s rule as an outcome, derivable straight from its advice. Good: "because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation." Someone mid-task who has not read the doc must be able to decide from this line alone whether the read is worth it. If you cannot name the concrete situation that triggers it, you do not yet understand the memory \u2014 ask the user one sharp question instead of improvising.';
 export const GUIDE_PREDICATE_VOCABULARY = 'Gate and match-frontmatter share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.';
 export const GUIDE_DOC_LINKS = 'Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name \u2014 the same identifier `crtr memory read` takes. A bare directory name is a valid link too: following it returns that directory\u2019s listing, a browse entrance rather than a doc. Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document or directory, and `crtr memory read` lists a doc\u2019s resolvable links alongside its body. There is no alias or label form.';

package/dist/commands/profile/kind.d.ts

@@ -1,2 +1 @@
-export declare function assertProfileDefaultKind(kind: string): void;
 export declare const kindLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/profile/kind.js

@@ -1,19 +1,7 @@
 import { defineLeaf } from '../../core/command.js';
-import { InputError } from '../../core/io.js';
-import { readMergedLaunchConfig } from '../../core/config.js';
+import { assertInstalledKind, readMergedLaunchConfig } from '../../core/config.js';
 import { loadProfileManifest, setProfileDefaultKind } from '../../core/profiles/manifest.js';
 import { stateBlock } from '../../core/help.js';
-export function assertProfileDefaultKind(kind) {
-    const kinds = Object.keys(readMergedLaunchConfig().kinds).sort();
-    if (!kinds.includes(kind)) {
-        throw new InputError({
-            error: 'unknown_kind',
-            message: `unknown kind: ${kind}`,
-            field: 'kind',
-            next: `Valid kinds: ${kinds.join(', ')}.`,
-        });
-    }
-}
 function kindsStateBlock() {
     return stateBlock('kinds', { count: Object.keys(readMergedLaunchConfig().kinds).length }, Object.keys(readMergedLaunchConfig().kinds).sort().join('\n'));
 }
@@ -39,7 +27,7 @@ export const kindLeaf = defineLeaf({
     },
     run: async (input) => {
         const kind = input['kind'];
-        assertProfileDefaultKind(kind);
+        assertInstalledKind(kind);
         const { profileId } = loadProfileManifest(input['profile']);
         const { manifest } = setProfileDefaultKind(profileId, kind);
         return {

package/dist/commands/profile/meta.js

@@ -5,7 +5,9 @@ import { loadProfileManifest, updateProfileMetadata } from '../../core/profiles/
  *  with the manifest store (`assertProfileMetadata`); this only splits. */
 export function resolveMetaPairs(raw, field) {
     const pairs = Array.isArray(raw) ? raw.map(String) : typeof raw === 'string' && raw !== '' ? [raw] : [];
-    const out = {};
+    // Null prototype: on a plain object a `__proto__` key would silently
+    // vanish here instead of reaching the store's key-shape rejection.
+    const out = Object.create(null);
     for (const pair of pairs) {
         const eq = pair.indexOf('=');
         if (eq <= 0) {

package/dist/commands/profile/new.js

@@ -1,7 +1,7 @@
 import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
+import { assertInstalledKind } from '../../core/config.js';
 import { createProfile, ensureRootProfile, profileRoot } from '../../core/profiles/manifest.js';
-import { assertProfileDefaultKind } from './kind.js';
 import { resolveMetaPairs } from './meta.js';
 export const newLeaf = defineLeaf({
     name: 'new',
@@ -23,7 +23,7 @@ export const newLeaf = defineLeaf({
                 name: 'root',
                 type: 'bool',
                 required: false,
-                constraint: 'Provision the canonical stable root profile (fixed id `root-00000000`, name `root`) — the fallback default identity for a home — instead of a fresh named one. Idempotent: re-running returns the existing root. Node-free (no `node new --root` needed). Mutually exclusive with `--name`/`--project`.',
+                constraint: 'Provision the canonical stable root profile (fixed id `root-00000000`, name `root`) — the fallback default identity for a home — instead of a fresh named one. Idempotent: re-running returns the existing root. Node-free (no `node new --root` needed). Mutually exclusive with `--name`/`--project`/`--default-kind`/`--meta`.',
             },
             {
                 kind: 'flag',
@@ -88,7 +88,7 @@ export const newLeaf = defineLeaf({
         if (name === undefined)
             throw usage('provide `--name <name>` to create a profile, or `--root` to provision the stable root profile.');
         if (defaultKind !== undefined)
-            assertProfileDefaultKind(defaultKind);
+            assertInstalledKind(defaultKind);
         const { profileId, manifest } = createProfile(name, project !== undefined ? [project] : [], {
             defaultKind,
             ...(Object.keys(metadata).length > 0 ? { metadata } : {}),

package/dist/commands/profile/show.js

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
-import { loadProfileManifest, profileRoot } from '../../core/profiles/manifest.js';
+import { loadProfileManifest, profileRoot, sanitizeProfileMetadata } from '../../core/profiles/manifest.js';
 import { CONFIG_FILE } from '../../types.js';
 export const showLeaf = defineLeaf({
     name: 'show',
@@ -46,7 +46,7 @@ export const showLeaf = defineLeaf({
             home: manifest.home,
             paused_at: manifest.paused_at,
             default_kind: manifest.default_kind ?? null,
-            metadata: manifest.metadata ?? {},
+            metadata: sanitizeProfileMetadata(manifest.metadata),
             created_at: manifest.created_at,
             last_used_at: manifest.last_used_at,
             path: profileRoot(profileId),

package/dist/core/__tests__/human-cancel-guard.test.js

@@ -13,7 +13,7 @@ import { createNode } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
 import { nodeDir } from '../canvas/paths.js';
 import { atomicWriteJson, bindTicketReplyRoute, pageManifestPath } from '../human/convention.js';
-import { cancelTicket } from '../human/tickets.js';
+import { cancelTicket, readTicketResult } from '../human/tickets.js';
 import { humanCancel } from '../../commands/human/queue.js';
 import { createApiServer } from '../../daemon/api/server.js';
 import { apiSocketPath } from '../canvas/paths.js';
@@ -46,7 +46,7 @@ function node(id) {
 }
 /** Publish a reply-bearing page ticket in the bridge node's directory, exactly as
  *  `human send` does: reply route first, then the page manifest. */
-function publishTicket(id) {
+function publishTicket(id, slots = []) {
     const dir = nodeDir(id);
     mkdirSync(dir, { recursive: true });
     bindTicketReplyRoute(dir, id);
@@ -58,7 +58,7 @@ function publishTicket(id) {
         delivery: { placement: 'inline', inbox: true, reply: true },
         document: 'page.tsx',
         steps: 1,
-        slots: [],
+        slots,
     });
 }
 before(() => {
@@ -80,13 +80,31 @@ after(() => {
     rmSync(home, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
 });
-test('cancel on an already-canceled ticket is a no-op, never throws on the finalize', async () => {
-    const id = 'canceledJob';
-    createNode(node(id));
-    publishTicket(id);
-    cancelTicket(nodeDir(id), { actor: 'human' }); // settled by the first cancel
-    const res = (await humanCancel.run({ ticket_id: id }));
-    assert.equal(res['canceled'], false);
-    assert.equal(res['reason'], 'already_resolved');
-    assert.equal(res['ticket_id'], id);
+test('cancel accepts newer page config and treats an already-canceled ticket as a no-op', async () => {
+    const newerId = 'newerPage';
+    createNode(node(newerId));
+    publishTicket(newerId, [{
+            id: 'decision',
+            kind: 'options',
+            step: 0,
+            config: {
+                label: 'Decision',
+                body: 'Choose one.',
+                options: [{ id: 'yes', label: 'Yes' }],
+                mode: 'single',
+                futureField: true,
+            },
+        }]);
+    const canceled = (await humanCancel.run({ ticket_id: newerId }));
+    assert.equal(canceled['canceled'], true);
+    assert.equal(canceled['ticket_id'], newerId);
+    assert.equal(readTicketResult(nodeDir(newerId))?.kind, 'canceled');
+    const settledId = 'canceledJob';
+    createNode(node(settledId));
+    publishTicket(settledId);
+    cancelTicket(nodeDir(settledId), { actor: 'human' });
+    const settled = (await humanCancel.run({ ticket_id: settledId }));
+    assert.equal(settled['canceled'], false);
+    assert.equal(settled['reason'], 'already_resolved');
+    assert.equal(settled['ticket_id'], settledId);
 });

package/dist/core/config.d.ts

@@ -141,6 +141,11 @@ export declare function readMergedLaunchConfig(targetCwd?: string, targetProfile
  *  existence/launch-menu enumeration is a caller concern); this only
  *  resolves the config for a kind the caller already knows about. */
 export declare function resolveKindConfig(kind: string): KindConfig | undefined;
+/** Reject a kind no scope registers. The one validation gate for every
+ *  surface that PERSISTS a kind (`profile new/kind`, the profile-ensure API
+ *  route) — a stored unknown kind would poison future omitted-kind creates
+ *  through `default_kind` resolution. */
+export declare function assertInstalledKind(kind: string): void;
 /** The sub-kinds available to spawn FROM a given top-level kind — every
  *  registered sub-kind (full path contains `/`) whose `availableTo` (default:
  *  its own top-level ancestor, e.g. `plan/reviewers/security` defaults to

package/dist/core/config.js

@@ -2,6 +2,7 @@ import { dirname, join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { CONFIG_FILE, STATE_FILE, CONDENSED_HISTORY_MODES, MOUSE_MODE_DEFAULTS, WHIP_MESSAGE_MODES, DEFAULT_WHIP_MESSAGES, defaultScopeConfig, defaultScopeState, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
 import { BINDING_CATALOG, BINDING_IDS, isAttachPaneBinding } from './keybindings/catalog.js';
+import { usage } from './errors.js';
 import { emitEvent } from './events/emit.js';
 import { atomicWriteJson, readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
 import { scopeRoot, requireScopeRoot, findProjectScopeRoots } from './scope.js';
@@ -753,6 +754,20 @@ export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileI
 export function resolveKindConfig(kind) {
     return readMergedLaunchConfig().kinds[kind];
 }
+/** Reject a kind no scope registers. The one validation gate for every
+ *  surface that PERSISTS a kind (`profile new/kind`, the profile-ensure API
+ *  route) — a stored unknown kind would poison future omitted-kind creates
+ *  through `default_kind` resolution. */
+export function assertInstalledKind(kind) {
+    const kinds = Object.keys(readMergedLaunchConfig().kinds).sort();
+    if (!kinds.includes(kind)) {
+        throw usage(`unknown kind: ${kind}`, {
+            received: kind,
+            field: 'kind',
+            next: `Valid kinds: ${kinds.join(', ')}.`,
+        });
+    }
+}
 /** The sub-kinds available to spawn FROM a given top-level kind — every
  *  registered sub-kind (full path contains `/`) whose `availableTo` (default:
  *  its own top-level ancestor, e.g. `plan/reviewers/security` defaults to

package/dist/core/human/__tests__/page.test.js

@@ -78,3 +78,15 @@ test('final and partial response validation share slot-addressed rules', () => {
     assert.throws(() => validatePartialPageResponses(manifest, { choice: { selectedOptionIds: ['maybe'], comments: [] } }), /unknown option id "maybe"/);
     assert.throws(() => validatePartialPageResponses(manifest, { extra: {} }), /unknown or non-response-bearing slot id "extra"/);
 });
+// Which questions have a minimum is the author's call, and both defaults matter to a
+// renderer mirroring this rule: pick-many is answered by ticking nothing, pick-one is not.
+test('an empty answer is refused only where the question is required', () => {
+    const manifest = derivePageManifestFromDocument(page(`<UserQuestion id="risks" label="Tick everything that applies" body="Skip it if none do." mode="multi" options={[{ id: "data", label: "Data" }]} />
+      <UserQuestion id="lane" label="Which lane?" body="Ships tonight." mode="single" required={false} options={[{ id: "now", label: "Now" }]} />
+      <UserText id="window" label="Maintenance window" initialText="" required />`));
+    const empty = { risks: { selectedOptionIds: [], comments: [] }, lane: { selectedOptionIds: [], comments: [] }, window: { text: 'Sunday 02:00', edited: true } };
+    assert.deepEqual(validatePageResponses(manifest, empty), empty);
+    assert.throws(() => validatePageResponses(manifest, { ...empty, window: { text: '  ', edited: true } }), /slot "window" is required and was left empty/);
+    const required = derivePageManifestFromDocument(page('<UserQuestion id="risks" label="Tick everything that applies" body="At least one." mode="multi" required options={[{ id: "data", label: "Data" }]} />'));
+    assert.throws(() => validatePageResponses(required, { risks: { selectedOptionIds: [], comments: [] } }), /multi-select slot "risks" requires a selection/);
+});

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

@@ -79,12 +79,13 @@ Props
 - \`options\` — required nonempty array of \`{id:string (nonempty, unique), label:string (nonempty), description?:string, recommended?:boolean}\`.
 - \`recommended\` on one option marks it the suggested answer. At most one option per question may set it. The inbox shows it on the row, and when this question is the page's only response-bearing component the user can accept it from the list with one keystroke, without opening the page. Recommend when you have a view worth acting on; leave it off when the choice is genuinely theirs.
 - \`mode\` — required: \`single\` or \`multi\`.
+- \`required?:boolean\` — whether an empty answer is refused. Defaults to the mode: a \`single\` question must be answered, a \`multi\` one need not be, because leaving every box unticked says "none of these apply". Set \`required\` when the mode's default is wrong — \`required={false}\` on a \`single\` question the user may skip, \`required\` on a \`multi\` one where at least one tick is the point.
 - \`label\` — required nonempty string: the question itself, drawn as the bold first line.
 - \`body\` — required nonempty string: markdown rendered above the choices — the context under the question a label cannot carry. Display-only; contributes nothing to the response.
 - \`allowFreetext?:boolean\`, \`freetextLabel?:string\`, \`freetextPlaceholder?:string\` — adds a final "something else" choice, drawn as one more row with its own control and a field to write in rather than as a note on the question. It is exclusive on a \`single\` question (choosing it clears the selection, and choosing an option clears what was written) and just another box on a \`multi\` one. \`freetextLabel\` names that row, default "Something else".
 
 Response rules
-- \`selectedOptionIds\` contains unique known option ids. A \`single\` response has at most one selected id and requires exactly one selection or nonempty allowed \`freetext\`; a \`multi\` response requires a selection, comment, or nonempty allowed \`freetext\`.
+- \`selectedOptionIds\` contains unique known option ids; a \`single\` response has at most one. When the question is required, a \`single\` response needs exactly one selection or nonempty allowed \`freetext\`, and a \`multi\` response needs a selection, comment, or nonempty allowed \`freetext\`.
 - \`freetext\` is accepted only when \`allowFreetext:true\`.
 - ${COMMENT_SHAPE} UserQuestion accepts only \`option\` anchors; \`optionId\` must name a configured option.
 
@@ -116,6 +117,7 @@ Props
 - \`label?:string\` — the component's label; required by the multi-response page rule.
 - \`placeholder?:string\` — the hint shown while the field is empty.
 - \`singleLine?:boolean\` — swaps the writing surface for one compact form field.
+- \`required?:boolean\` — defaults false. When set, a field left empty (whitespace only) is refused, and the inbox marks it unanswered rather than sending it.
 
 The field is always writable; there is no read-only mode, and the config rejects an \`editable\` prop.
 
@@ -140,6 +142,7 @@ Props
 - \`rows?:\` array of \`{id:string (nonempty, unique), cells:Record<string,string|number|boolean|null>}\`. Rows are inline — map your data into this array in the module.
 - \`rowSelect?:"none"|"single"|"multi"\` — defaults to \`none\`.
 - \`columnSelect?:"none"|"single"|"multi"\` — defaults to \`none\`.
+- \`required?:boolean\` — defaults false. When set on a selectable table, a response selecting no row and no column is refused.
 - \`label?:string\` — the component's label; required by the multi-response page rule when the table is selectable.
 - \`body?:string\` — optional markdown rendered above the table. Display-only; it contributes nothing to the response.
 
@@ -169,6 +172,7 @@ Props
 - \`cards?:\` array of \`{id:string (nonempty, unique), title:string (nonempty), subtitle?:string, body?:string, tag?:string}\`. Cards are inline — map your data into this array in the module.
 - \`mode\` — required: \`single\` or \`multi\`.
 - \`columns?:2|3\` — optional layout column count.
+- \`required?:boolean\` — defaults false. When set, a response selecting no card is refused.
 - \`label?:string\` — the component's label; required by the multi-response page rule.
 - \`body?:string\` — optional markdown rendered above the cards. Display-only; it contributes nothing to the response.
 

package/dist/core/human/page-schema.d.ts

@@ -41,6 +41,7 @@ export declare const optionsConfigSchema: z.ZodObject<{
         single: "single";
         multi: "multi";
     }>;
+    required: z.ZodOptional<z.ZodBoolean>;
     allowFreetext: z.ZodOptional<z.ZodBoolean>;
     freetextLabel: z.ZodOptional<z.ZodString>;
     freetextPlaceholder: z.ZodOptional<z.ZodString>;
@@ -67,6 +68,7 @@ export declare const textConfigSchema: z.ZodObject<{
     initialText: z.ZodString;
     placeholder: z.ZodOptional<z.ZodString>;
     singleLine: z.ZodOptional<z.ZodBoolean>;
+    required: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type TextConfig = z.infer<typeof textConfigSchema>;
 export declare const textResponseSchema: z.ZodObject<{
@@ -119,6 +121,7 @@ export declare const tableConfigSchema: z.ZodObject<{
         single: "single";
         multi: "multi";
     }>>;
+    required: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type TableConfig = z.infer<typeof tableConfigSchema>;
 export declare const tableResponseSchema: z.ZodObject<{
@@ -167,6 +170,7 @@ export declare const cardsConfigSchema: z.ZodObject<{
         multi: "multi";
     }>;
     columns: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>]>>;
+    required: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type CardsConfig = z.infer<typeof cardsConfigSchema>;
 export declare const cardsResponseSchema: z.ZodObject<{
@@ -228,6 +232,14 @@ export interface PageManifest {
     slots: PageSlot[];
     source?: PageSource;
 }
+export declare const pageDeliverySchema: z.ZodObject<{
+    placement: z.ZodEnum<{
+        inline: "inline";
+        panel: "panel";
+    }>;
+    inbox: z.ZodBoolean;
+    reply: z.ZodBoolean;
+}, z.core.$strict>;
 export declare const BUILTIN_PAGE_CONFIG_SCHEMAS: Record<(typeof BUILTIN_PAGE_KINDS)[number], z.ZodType>;
 export declare const BUILTIN_PAGE_RESPONSE_SCHEMAS: Partial<Record<(typeof BUILTIN_PAGE_KINDS)[number], z.ZodType>>;
 export declare function issueText(error: z.ZodError): string;
@@ -266,6 +278,8 @@ export declare function validateAuthoredPageManifest(parsed: unknown, productCom
 export declare function createPageManifestSchema(): z.ZodType<PageManifest>;
 export declare const pageManifestSchema: z.ZodType<PageManifest, unknown, z.core.$ZodTypeInternals<PageManifest, unknown>>;
 export type PageResponses = Record<string, SlotResponse>;
+/** A picker's minimum: authored `required` wins, else the mode's own reading of an empty answer. */
+export declare function optionsRequired(config: OptionsConfig): boolean;
 /** Validate a complete final response map. */
 export declare function validatePageResponses(manifest: PageManifest, responses: unknown): PageResponses;
 /** Validate an autosaved response map, permitting omitted response-bearing components. */

package/dist/core/human/page-schema.js

@@ -28,6 +28,9 @@ export const optionsConfigSchema = z.object({
     body: z.string().optional(),
     options: z.array(optionSchema).min(1).superRefine((items, ctx) => uniqueIds(items, ctx, 'option')),
     mode: z.enum(['single', 'multi']),
+    // Defaults with the mode: a radio group means "pick one", while an empty checkbox
+    // list is itself an answer ("none of these apply").
+    required: z.boolean().optional(),
     allowFreetext: z.boolean().optional(),
     freetextLabel: z.string().optional(),
     freetextPlaceholder: z.string().optional(),
@@ -40,7 +43,7 @@ export const optionsResponseSchema = z.object({ selectedOptionIds: z.array(itemI
 // Text is a writing surface, always: its whole point is the string the user hands back, so
 // there is no read-only mode. `singleLine` only swaps the multi-line surface for one compact
 // form field — a subject line, a name, a URL.
-export const textConfigSchema = z.object({ label: z.string().optional(), initialText: z.string(), placeholder: z.string().optional(), singleLine: z.boolean().optional() }).strict();
+export const textConfigSchema = z.object({ label: z.string().optional(), initialText: z.string(), placeholder: z.string().optional(), singleLine: z.boolean().optional(), required: z.boolean().optional() }).strict();
 export const textResponseSchema = z.object({ text: z.string(), edited: z.boolean() }).strict();
 export const tableColumnSchema = z.object({ id: itemIdSchema, label: z.string().min(1), align: z.enum(['left', 'right']).optional(), mono: z.boolean().optional() }).strict();
 export const tableCellSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
@@ -53,6 +56,7 @@ const tableConfigFields = {
     rows: tableRowsSchema.optional(),
     rowSelect: selectModeSchema.default('none'),
     columnSelect: selectModeSchema.default('none'),
+    required: z.boolean().optional(),
 };
 /** Table config: its data is always embedded. */
 export const tableConfigSchema = z.object(tableConfigFields).strict();
@@ -65,6 +69,7 @@ const cardsConfigFields = {
     cards: cardsSchema.optional(),
     mode: z.enum(['single', 'multi']),
     columns: z.union([z.literal(2), z.literal(3)]).optional(),
+    required: z.boolean().optional(),
 };
 /** Cards config: its data is always embedded. */
 export const cardsConfigSchema = z.object(cardsConfigFields).strict();
@@ -81,14 +86,14 @@ const chartConfigFields = {
 /** Chart config: its data is always embedded. */
 export const chartConfigSchema = z.object(chartConfigFields).strict();
 const sourceSchema = z.object({ sessionName: z.string().optional(), askedBy: z.string().optional(), emittedAt: z.string().datetime({ offset: true }).optional(), profileName: z.string().optional(), nodeId: z.string().optional() }).strict();
-const deliverySchema = z.object({ placement: z.enum(['inline', 'panel']), inbox: z.boolean(), reply: z.boolean() }).strict();
+export const pageDeliverySchema = z.object({ placement: z.enum(['inline', 'panel']), inbox: z.boolean(), reply: z.boolean() }).strict();
 const rawSlotSchema = z.object({ id: idSchema.optional(), kind: z.string().min(1), step: z.number().int().nonnegative(), config: jsonObjectSchema, unvalidated: z.literal(true).optional(), display: z.literal(true).optional() }).strict();
 const rawPageManifestSchema = z.object({
     schema: z.literal('crtr.page/v2'),
     dialect: z.enum(['jsx', 'html']),
     title: z.string().trim().min(1),
     subtitle: z.string().optional(),
-    delivery: deliverySchema,
+    delivery: pageDeliverySchema,
     document: z.enum(['page.tsx', 'page.html']),
     steps: z.number().int().positive(),
     slots: z.array(rawSlotSchema),
@@ -254,6 +259,10 @@ function validateComments(slot, comments) {
         throw new Error(`slot "${slot.id}" does not allow comment anchor kind "${anchor.kind}"`);
     }
 }
+/** A picker's minimum: authored `required` wins, else the mode's own reading of an empty answer. */
+export function optionsRequired(config) {
+    return config.required ?? config.mode === 'single';
+}
 function parseResponse(slot, raw) {
     if (slot.unvalidated === true) {
         const result = jsonObjectSchema.safeParse(raw);
@@ -276,10 +285,12 @@ function parseResponse(slot, raw) {
         if (config.mode === 'single' && response.selectedOptionIds.length > 1)
             throw new Error(`slot "${slot.id}" is single-select but received ${response.selectedOptionIds.length} option ids`);
         const hasFreetext = config.allowFreetext === true && (response.freetext?.trim() ?? '') !== '';
-        if (config.mode === 'single' && response.selectedOptionIds.length !== 1 && !hasFreetext)
-            throw new Error(`single-select slot "${slot.id}" requires exactly one selection or nonempty allowed freetext`);
-        if (config.mode === 'multi' && response.selectedOptionIds.length === 0 && response.comments.length === 0 && !hasFreetext)
-            throw new Error(`multi-select slot "${slot.id}" requires a selection, comment, or nonempty allowed freetext`);
+        if (optionsRequired(config)) {
+            if (config.mode === 'single' && response.selectedOptionIds.length !== 1 && !hasFreetext)
+                throw new Error(`single-select slot "${slot.id}" requires exactly one selection or nonempty allowed freetext`);
+            if (config.mode === 'multi' && response.selectedOptionIds.length === 0 && response.comments.length === 0 && !hasFreetext)
+                throw new Error(`multi-select slot "${slot.id}" requires a selection, comment, or nonempty allowed freetext`);
+        }
         validateComments(slot, response.comments);
         return response;
     }
@@ -287,6 +298,8 @@ function parseResponse(slot, raw) {
         const result = textResponseSchema.safeParse(raw);
         if (!result.success)
             throw new Error(`invalid response for slot "${slot.id}": ${issueText(result.error)}`);
+        if (slot.config.required === true && result.data.text.trim() === '')
+            throw new Error(`slot "${slot.id}" is required and was left empty`);
         return result.data;
     }
     if (slot.kind === 'table') {
@@ -305,6 +318,8 @@ function parseResponse(slot, raw) {
         for (const id of response.selectedColumnIds)
             if (!columnIds.has(id))
                 throw new Error(`slot "${slot.id}" selects unknown column id "${id}"`);
+        if (config.required === true && response.selectedRowIds.length === 0 && response.selectedColumnIds.length === 0)
+            throw new Error(`slot "${slot.id}" is required and nothing is selected`);
         if ((config.rowSelect === 'none' && response.selectedRowIds.length > 0) || (config.rowSelect === 'single' && response.selectedRowIds.length > 1))
             throw new Error(`slot "${slot.id}" response violates row select mode "${config.rowSelect}"`);
         if ((config.columnSelect === 'none' && response.selectedColumnIds.length > 0) || (config.columnSelect === 'single' && response.selectedColumnIds.length > 1))
@@ -324,6 +339,8 @@ function parseResponse(slot, raw) {
                 throw new Error(`slot "${slot.id}" selects unknown card id "${id}"`);
         if (config.mode === 'single' && response.selectedCardIds.length > 1)
             throw new Error(`slot "${slot.id}" is single-select but received ${response.selectedCardIds.length} card ids`);
+        if (config.required === true && response.selectedCardIds.length === 0)
+            throw new Error(`slot "${slot.id}" is required and nothing is selected`);
         return response;
     }
     throw new Error(`slot "${slot.id}" kind "${slot.kind}" does not accept a response`);

package/dist/core/human/page.d.ts

@@ -12,3 +12,5 @@ export declare function deriveHtmlPageManifest(document: string, source?: PageSo
 export declare function derivePageManifest(sourceFile: string, productComponents?: ProductPageComponents, source?: PageSource, delivery?: PageDelivery): PageManifest;
 /** Read and validate page.json from a ticket directory. */
 export declare function parsePage(dir: string): PageManifest;
+/** Read only the stable delivery envelope without interpreting component config. */
+export declare function parsePageDelivery(dir: string): PageDelivery;

package/dist/core/human/page.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { transformSync } from 'esbuild';
 import ts from 'typescript';
 import { BUILTIN_KIND_BY_TAG, BUILTIN_PAGE_COMPONENT_TAGS, DISPLAY_PAGE_COMPONENT_TAGS, pageComponentTag } from './page-catalog.js';
-import { isResponseBearingSlot, validateAuthoredPageManifest, validatePageManifest } from './page-schema.js';
+import { isResponseBearingSlot, pageDeliverySchema, validateAuthoredPageManifest, validatePageManifest } from './page-schema.js';
 import { evaluatePageTree, jsonProps } from './page-eval.js';
 import { PageAuthoringError } from './page-errors.js';
 export { PageAuthoringError };
@@ -174,14 +174,25 @@ export function deriveHtmlPageManifest(document, source, delivery = { placement:
 export function derivePageManifest(sourceFile, productComponents = [], source, delivery) {
     return derivePageManifestFromDocument(readFileSync(sourceFile, 'utf8'), productComponents, source, delivery);
 }
-/** Read and validate page.json from a ticket directory. */
-export function parsePage(dir) {
-    let raw;
+function readPageJson(dir) {
     try {
-        raw = JSON.parse(readFileSync(join(dir, 'page.json'), 'utf8'));
+        return JSON.parse(readFileSync(join(dir, 'page.json'), 'utf8'));
     }
     catch {
         throw new PageAuthoringError('page.json is not valid JSON');
     }
-    return validatePageManifest(raw);
+}
+/** Read and validate page.json from a ticket directory. */
+export function parsePage(dir) {
+    return validatePageManifest(readPageJson(dir));
+}
+/** Read only the stable delivery envelope without interpreting component config. */
+export function parsePageDelivery(dir) {
+    const raw = readPageJson(dir);
+    const parsed = pageDeliverySchema.safeParse(typeof raw === 'object' && raw !== null && !Array.isArray(raw)
+        ? raw['delivery']
+        : undefined);
+    if (!parsed.success)
+        throw new PageAuthoringError('page.json has an invalid delivery envelope');
+    return parsed.data;
 }