toolroll 0.9.82 → 0.9.84

package/dist/settings-kit-script.js

@@ -0,0 +1,67 @@
+/**
+ * The settings kit's one script (docs/plans/settings-revamp.md §4), shipped as a page's functional script beside kit
+ * forms (settings-kit.ts). Without it every kit form works as today: the proof field shows inline and Save posts.
+ *
+ * With it, a kit form that asks for a proof:
+ * - moves its server-written proof field into the `<dialog>` inside the same form (the field never leaves the form);
+ * - opens the dialog on submit instead of posting, remembering the pressed button;
+ * - Confirm (its button, or Enter in the field) posts the form with that button (`requestSubmit(submitter)`, after the
+ *   submit event that asked has finished), so its name=value and every hidden term go along unchanged; Cancel (or
+ *   Escape) closes it and posts nothing, and focus returns to the button;
+ * - once a kit form posts, it is pending: further submits are dropped and its Save and Confirm are disabled (after the
+ *   post has taken their values), until the page is shown again or the post was cancelled — never on a timer;
+ * - asks for nothing when the proof was left out (Passwordless) — there is no dialog then — and shows the
+ *   identity-provider link when the sign-in swapped the field.
+ * Each section's Save bar names what changed. The script never reads or sets a field's value except to check that a
+ * required proof isn't empty; the server still proves everything.
+ */
+export const SETTINGS_KIT_SCRIPT = `(function(){
+if(window.__soKit)return;window.__soKit=1;
+var d=document;d.documentElement.classList.add("kit-js");
+function label(el){var l=el.labels&&el.labels[0];if(!l&&el.closest)l=el.closest("fieldset")&&el.closest("fieldset").querySelector("legend");return l?(l.textContent||"").replace(/\\s+/g," ").trim():(el.name||"");}
+function prep(f){if(f.__kit)return;f.__kit=1;
+var bar=f.querySelector("[data-kit-state]");if(bar&&bar.textContent==="")bar.textContent=bar.getAttribute("data-idle")||"";
+if(!f.hasAttribute("data-kit-step-up"))return;
+var dl=f.querySelector("[data-kit-dialog]"),p=f.querySelector(":scope>[data-kit-proof]");
+if(!dl||!p||typeof dl.showModal!=="function"){f.removeAttribute("data-kit-step-up");return;}
+dl.querySelector("[data-kit-slot]").appendChild(p);
+p.querySelectorAll("[required]").forEach(function(i){i.removeAttribute("required");i.setAttribute("data-kit-required","");});
+dl.addEventListener("close",function(){if(f.__kitSent)return;var back=f.__kitBy||f.querySelector(".kit-save");if(back&&back.focus)back.focus();});}
+function scan(root){if(root.querySelectorAll)root.querySelectorAll("form.kit-form").forEach(prep);}
+scan(d);
+if(typeof MutationObserver!=="undefined")new MutationObserver(function(list){list.forEach(function(m){m.addedNodes.forEach(function(n){if(n.nodeType===1){if(n.matches&&n.matches("form.kit-form"))prep(n);scan(n);}});});}).observe(d.documentElement,{childList:true,subtree:true});
+function asks(dl){var slot=dl.querySelector("[data-kit-slot]");return !!slot.querySelector("input:not([type=hidden]),a,.sso-step-up");}
+function confirm(f){var dl=f.querySelector("[data-kit-dialog]"),miss=null;
+dl.querySelectorAll("[data-kit-required]").forEach(function(i){if(!miss&&i.value==="")miss=i;});
+if(miss){miss.setCustomValidity("Enter your password.");miss.reportValidity();miss.focus();return;}
+var by=f.__kitBy&&f.__kitBy.form===f?f.__kitBy:null;f.__kitSent=1;dl.close();
+setTimeout(function(){f.__kitGo=1;try{by?f.requestSubmit(by):f.requestSubmit();}finally{f.__kitGo=0;}},0);}
+function buttons(f){return f.querySelectorAll(".kit-save,[data-kit-confirm]");}
+function release(f){f.__kitPending=0;f.__kitSent=0;buttons(f).forEach(function(b){b.disabled=false;});}
+function latch(f,e){f.__kitPending=1;setTimeout(function(){if(e.defaultPrevented){release(f);return;}
+buttons(f).forEach(function(b){b.disabled=true;});},0);}
+addEventListener("pageshow",function(){d.querySelectorAll("form.kit-form").forEach(release);});
+d.addEventListener("submit",function(e){var f=e.target;if(!f||!f.classList||!f.classList.contains("kit-form"))return;prep(f);
+if(f.__kitPending){e.preventDefault();e.stopImmediatePropagation();return;}
+var dl=f.hasAttribute("data-kit-step-up")?f.querySelector("[data-kit-dialog]"):null;
+if(f.__kitGo||!dl||!asks(dl)){latch(f,e);return;}
+e.preventDefault();e.stopImmediatePropagation();
+if(dl.open){confirm(f);return;}
+f.__kitBy=e.submitter||null;f.__kitSent=0;dl.showModal();
+var first=dl.querySelector("[data-kit-slot] input:not([type=hidden]),[data-kit-slot] a")||dl.querySelector("[data-kit-confirm]");if(first)first.focus();},true);
+d.addEventListener("click",function(e){var b=e.target&&e.target.closest?e.target.closest("[data-kit-confirm],[data-kit-cancel]"):null;if(!b)return;
+var dl=b.closest("[data-kit-dialog]"),f=dl&&dl.closest("form");if(!f)return;e.preventDefault();
+if(b.hasAttribute("data-kit-cancel")){dl.close();return;}confirm(f);});
+d.addEventListener("input",function(e){var t=e.target;if(t&&t.setCustomValidity&&t.hasAttribute&&t.hasAttribute("data-kit-required"))t.setCustomValidity("");},true);
+function changed(e){var t=e.target,f=t&&t.form;if(!f||!f.classList.contains("kit-form")||t.closest("[data-kit-dialog]")||t.type==="hidden")return;prep(f);
+var bar=f.querySelector("[data-kit-save-bar]"),state=f.querySelector("[data-kit-state]");if(!bar||!state)return;
+f.__kitChanged=f.__kitChanged||[];var name=label(t);if(name&&f.__kitChanged.indexOf(name)<0)f.__kitChanged.push(name);
+bar.setAttribute("data-changed","");state.textContent="Changed: "+f.__kitChanged.join(", ");}
+d.addEventListener("input",changed);d.addEventListener("change",changed);
+})();`;
+/** The pages that wear the settings frame: one column, no Crew sheet, a breadcrumb under Settings. Here (not in
+ * settings-kit.ts) so the browser bundle reads it without the server's form contracts. */
+export function isSettingsFrame(pathname) {
+    return pathname === "/settings" || pathname.startsWith("/settings/") || pathname === "/setup" || pathname.startsWith("/setup/")
+        || pathname === "/people" || pathname === "/mode" || pathname === "/control" || pathname === "/spend";
+}

package/dist/settings-kit.d.ts

@@ -0,0 +1,137 @@
+/**
+ * The settings kit (docs/plans/settings-revamp.md §4): the frame's breadcrumb, and the pieces every settings page is
+ * rebuilt from — a section, its own sticky Save, the step-up dialog drawn from the action's own proof contract
+ * (settings-proofs.ts), field errors, secret inputs and choice groups. Server-rendered HTML that works without
+ * JavaScript; settings-kit-script.ts only turns the inline proof field into a dialog.
+ *
+ * Rules the helpers keep (and settings-kit.test.ts pins):
+ * - the proof field is written into the form's own server HTML, named as its handler reads it, labelled, and
+ *   `current-password`; so sensitivity (serve.ts sendScreen) and the identity-provider swap (ssoStepUps) still see it;
+ * - a step-up field renders through `reauth`, so Passwordless leaves it out exactly as today; a credential or typed
+ *   password field always renders;
+ * - a CSRF-only action renders no proof field and no dialog;
+ * - nothing here ever sets `value` on a proof or secret field;
+ * - handlers never read any of this: it only draws.
+ */
+import { type Html, type HtmlValue } from "./html.js";
+import { isSettingsFrame } from "./settings-kit-script.js";
+import { type ProofRow } from "./settings-proofs.js";
+export { isSettingsFrame };
+/** One breadcrumb: a link, or (the last) the page itself. */
+export type Crumb = {
+    label: string;
+    href: string | null;
+};
+/** The text of a page's first h1 (tags dropped, the common entities read), or null. */
+export declare function headingText(page: string): string | null;
+/** The breadcrumb for a settings-frame page: "Settings / <this page>", or nothing on the hub and outside the frame. */
+export declare function settingsCrumbs(pathname: string, title: string, page: string): Crumb[] | undefined;
+/** The project the sidebar's picker names: the session's saved selection while this person may still see it, else
+ * the page's own effective project, else none — checked against the visible project list, so a selection that
+ * outlived the ceiling is never sent to the page. */
+export declare function openProjectFor(saved: string | null, effective: string | null | undefined, visible: readonly {
+    path: string;
+}[]): string | null;
+/** The breadcrumb as server HTML (the page before scripts, and without them). */
+export declare function crumbsHtml(crumbs: readonly Crumb[]): Html;
+/** The password-manager opt-outs every secret input carries (a service's key is not the person's sign-in). */
+export declare const SECRET_OPT_OUTS: {
+    readonly "data-1p-ignore": true;
+    readonly "data-lpignore": "true";
+    readonly "data-bwignore": true;
+    readonly "data-form-type": "other";
+};
+/** A field's message under it: tied to the field with aria-describedby, announced, and the field focused. */
+export declare function fieldError(id: string, message: string): Html;
+export type TextField = {
+    id: string;
+    name: string;
+    label: string;
+    type?: "text" | "number" | "url" | "email";
+    /** What the person typed (kept after a validation error). Never a secret: secrets use secretInput. */
+    value?: string | null;
+    hint?: string;
+    error?: string | null;
+    attrs?: Readonly<Record<string, string | number | boolean | null | undefined>>;
+};
+/** A labelled text field; with an error it is aria-invalid, names its message and takes focus. */
+export declare function textField(field: TextField): Html;
+/** A secret that is not the person's own password (an API key, a bot token, a client secret): masked, never given a
+ * value, kept out of password managers. The field name is the handler's own wire name. */
+export declare function secretInput(field: {
+    id: string;
+    name: string;
+    label: string;
+    hint?: string;
+    required?: boolean;
+    error?: string | null;
+}): Html;
+/** A choice group: a fieldset with its legend, each option's detail tied to it. Nothing saves until Save. */
+export declare function choiceGroup(group: {
+    id: string;
+    name: string;
+    legend: string;
+    checked: string | null;
+    options: readonly {
+        value: string;
+        label: string;
+        detail?: string;
+    }[];
+    error?: string | null;
+}): Html;
+/** Proofs that only a password typed now satisfies: no Passwordless session and no identity-provider re-check. */
+export declare const typedOnly: (row: ProofRow) => boolean;
+/** The proof field a row's handler reads, as today's forms write it; empty for a CSRF-only row. A step-up field goes
+ * through `reauth` (Passwordless leaves it out); a credential or typed field always shows. A typed-only field carries
+ * `data-so-typed`, so the identity-provider swap leaves it a real password field (keepTypedFields). Never a value. */
+export declare function proofField(row: ProofRow, options?: {
+    label?: string;
+}): Html;
+/**
+ * The identity-provider swap (render-people.ts ssoStepUps) with typed-only proof fields kept: those handlers take only
+ * a password typed now, so the field must stay a real password input. The field is held out of the swap by its
+ * marker and put back as it was. Every other step-up field is swapped exactly as before.
+ */
+export declare function keepTypedFields<A extends unknown[]>(page: Html, swap: (page: Html, ...rest: A) => Html, ...rest: A): Html;
+/** How the dialog explains a proof that Passwordless doesn't cover, in words; null where nothing needs saying. */
+export declare function proofNote(row: ProofRow): string | null;
+export type StepUpForm = {
+    /** The proof inventory row this form posts under. */
+    proof: string;
+    /** The exact route (one of the row's). */
+    action: string;
+    /** Unique on the page: the form, its dialog and its section hang from it. */
+    id: string;
+    /** The section's own fields. */
+    body: HtmlValue;
+    /** Hidden terms posted back unchanged (nonce, digest, fingerprint, the shown project…). */
+    hidden?: Readonly<Record<string, string | number | null | undefined>>;
+    /** The Save bar's words before anything changes, and its button. */
+    save?: {
+        label?: string;
+        idle?: string;
+        name?: string;
+        value?: string;
+    };
+    /** What the dialog says the person is agreeing to (the action's own words by default). */
+    confirm?: string;
+};
+/**
+ * A section's form, posted to its existing route with its existing fields, and its sticky Save. When the row needs a
+ * proof, the proof field sits in the form's own HTML — inline (as today, which is how it works without JavaScript) and
+ * moved into a `<dialog>` inside the same form by settings-kit-script.ts, which opens it on submit, keeps the pressed
+ * button, and posts nothing on Cancel. The server still proves everything.
+ */
+export declare function stepUpForm(form: StepUpForm): Html;
+/** A section: a heading, a one-line state, a problem the handler sent back (role=alert), then its form. */
+export declare function kitSection(section: {
+    id: string;
+    title: string;
+    state?: HtmlValue;
+    problem?: string | null;
+    said?: string | null;
+    body: HtmlValue;
+}): Html;
+/** The kit's look: one 760px column, sections with no nested wells, the sticky Save, the dialog. The needs-you colour
+ * falls back to the warning token until S5 lands `--so-needs-you`. */
+export declare const SETTINGS_KIT_CSS: string;

package/dist/settings-kit.js

@@ -0,0 +1,186 @@
+/**
+ * The settings kit (docs/plans/settings-revamp.md §4): the frame's breadcrumb, and the pieces every settings page is
+ * rebuilt from — a section, its own sticky Save, the step-up dialog drawn from the action's own proof contract
+ * (settings-proofs.ts), field errors, secret inputs and choice groups. Server-rendered HTML that works without
+ * JavaScript; settings-kit-script.ts only turns the inline proof field into a dialog.
+ *
+ * Rules the helpers keep (and settings-kit.test.ts pins):
+ * - the proof field is written into the form's own server HTML, named as its handler reads it, labelled, and
+ *   `current-password`; so sensitivity (serve.ts sendScreen) and the identity-provider swap (ssoStepUps) still see it;
+ * - a step-up field renders through `reauth`, so Passwordless leaves it out exactly as today; a credential or typed
+ *   password field always renders;
+ * - a CSRF-only action renders no proof field and no dialog;
+ * - nothing here ever sets `value` on a proof or secret field;
+ * - handlers never read any of this: it only draws.
+ */
+import { attributes, html, htmlString, joinHtml, postForm, reauth, replaceMarkup } from "./html.js";
+import { isSettingsFrame } from "./settings-kit-script.js";
+import { contractReads, PROOF_INVENTORY, proofRow } from "./settings-proofs.js";
+export { isSettingsFrame };
+const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', "#39": "'", "#x27": "'", nbsp: " " };
+/** The text of a page's first h1 (tags dropped, the common entities read), or null. */
+export function headingText(page) {
+    const found = /<h1\b[^>]*>([\s\S]*?)<\/h1>/i.exec(page);
+    if (found === null)
+        return null;
+    const text = found[1].replace(/<[^>]*>/g, "").replace(/&(amp|lt|gt|quot|#39|#x27|nbsp);/g, (_whole, name) => ENTITIES[name] ?? "").replace(/\s+/g, " ").trim();
+    return text === "" ? null : text.slice(0, 80);
+}
+/** The breadcrumb for a settings-frame page: "Settings / <this page>", or nothing on the hub and outside the frame. */
+export function settingsCrumbs(pathname, title, page) {
+    if (!isSettingsFrame(pathname) || pathname === "/settings")
+        return undefined;
+    const name = headingText(page) ?? (title.charAt(0).toUpperCase() + title.slice(1));
+    return [{ label: "Settings", href: "/settings" }, { label: name, href: null }];
+}
+/** The project the sidebar's picker names: the session's saved selection while this person may still see it, else
+ * the page's own effective project, else none — checked against the visible project list, so a selection that
+ * outlived the ceiling is never sent to the page. */
+export function openProjectFor(saved, effective, visible) {
+    return [saved, effective ?? null].find((path) => path !== null && visible.some(one => one.path === path)) ?? null;
+}
+/** The breadcrumb as server HTML (the page before scripts, and without them). */
+export function crumbsHtml(crumbs) {
+    return html `<nav class="kit-crumbs" aria-label="Breadcrumb"><ol>${crumbs.map(one => one.href === null
+        ? html `<li aria-current="page">${one.label}</li>`
+        : html `<li><a href="${one.href}">${one.label}</a></li>`)}</ol></nav>`;
+}
+// ---- fields --------------------------------------------------------------------------------------------------------
+/** The password-manager opt-outs every secret input carries (a service's key is not the person's sign-in). */
+export const SECRET_OPT_OUTS = { "data-1p-ignore": true, "data-lpignore": "true", "data-bwignore": true, "data-form-type": "other" };
+const errorId = (id) => `${id}-error`;
+/** A field's message under it: tied to the field with aria-describedby, announced, and the field focused. */
+export function fieldError(id, message) {
+    return html `<p class="kit-field-error" id="${errorId(id)}" role="alert">${message}</p>`;
+}
+/** A labelled text field; with an error it is aria-invalid, names its message and takes focus. */
+export function textField(field) {
+    const hint = field.hint === undefined ? null : `${field.id}-hint`;
+    const described = [hint, field.error ? errorId(field.id) : null].filter(Boolean).join(" ");
+    return html `<div class="kit-field"><label for="${field.id}">${field.label}</label>\
+${field.hint === undefined ? "" : html `<p class="kit-hint" id="${hint}">${field.hint}</p>`}\
+<input${attributes({ id: field.id, name: field.name, type: field.type ?? "text", value: field.value ?? null, ...(field.attrs ?? {}),
+        "aria-invalid": field.error ? "true" : null, "aria-describedby": described === "" ? null : described, autofocus: field.error ? true : null })}>\
+${field.error ? fieldError(field.id, field.error) : ""}</div>`;
+}
+/** A secret that is not the person's own password (an API key, a bot token, a client secret): masked, never given a
+ * value, kept out of password managers. The field name is the handler's own wire name. */
+export function secretInput(field) {
+    const described = [field.hint === undefined ? null : `${field.id}-hint`, field.error ? errorId(field.id) : null].filter(Boolean).join(" ");
+    return html `<div class="kit-field"><label for="${field.id}">${field.label}</label>\
+${field.hint === undefined ? "" : html `<p class="kit-hint" id="${field.id}-hint">${field.hint}</p>`}\
+<input${attributes({ id: field.id, name: field.name, type: "password", autocomplete: "off", spellcheck: "false", autocapitalize: "none", "data-so-secret": true, ...SECRET_OPT_OUTS,
+        required: field.required === true, "aria-invalid": field.error ? "true" : null, "aria-describedby": described === "" ? null : described, autofocus: field.error ? true : null })}>\
+${field.error ? fieldError(field.id, field.error) : ""}</div>`;
+}
+/** A choice group: a fieldset with its legend, each option's detail tied to it. Nothing saves until Save. */
+export function choiceGroup(group) {
+    return html `<fieldset class="kit-choices"${group.error ? html ` aria-describedby="${errorId(group.id)}"` : ""}><legend>${group.legend}</legend>\
+${group.options.map((one, at) => {
+        const id = `${group.id}-${at}`;
+        return html `<label class="kit-choice" for="${id}"><input${attributes({ type: "radio", id, name: group.name, value: one.value, checked: one.value === group.checked, "aria-describedby": one.detail === undefined ? null : `${id}-detail` })}>\
+<span>${one.label}</span>${one.detail === undefined ? "" : html `<span class="kit-choice-detail" id="${id}-detail">${one.detail}</span>`}</label>`;
+    })}${group.error ? fieldError(group.id, group.error) : ""}</fieldset>`;
+}
+// ---- proof ---------------------------------------------------------------------------------------------------------
+/** Proofs that only a password typed now satisfies: no Passwordless session and no identity-provider re-check. */
+export const typedOnly = (row) => row.proof === "typed-password" || row.proof === "typed-now-operator";
+/** The proof field a row's handler reads, as today's forms write it; empty for a CSRF-only row. A step-up field goes
+ * through `reauth` (Passwordless leaves it out); a credential or typed field always shows. A typed-only field carries
+ * `data-so-typed`, so the identity-provider swap leaves it a real password field (keepTypedFields). Never a value. */
+export function proofField(row, options = {}) {
+    if (row.field === null || row.proof === "none")
+        return html ``;
+    if (!contractReads(row, row.field))
+        throw new Error(`${row.id}: its form doesn't read ${row.field}`);
+    const label = options.label ?? "Your Toolroll password";
+    if (typedOnly(row))
+        return html `<label>${label}<input type="password" name="${row.field}" data-so-typed autocomplete="current-password" required></label>`;
+    const field = html `<label>${label}<input type="password" name="${row.field}" autocomplete="current-password" required></label>`;
+    return row.proof === "step-up" ? reauth(field) : field;
+}
+const TYPED_FIELD = /<input type="password" name="([a-z-]+)" data-so-typed autocomplete="current-password" required>/g;
+const HELD_FIELD = /<input type="password" name="([a-z-]+)" data-so-typed data-so-typed-held required>/g;
+/**
+ * The identity-provider swap (render-people.ts ssoStepUps) with typed-only proof fields kept: those handlers take only
+ * a password typed now, so the field must stay a real password input. The field is held out of the swap by its
+ * marker and put back as it was. Every other step-up field is swapped exactly as before.
+ */
+export function keepTypedFields(page, swap, ...rest) {
+    const held = replaceMarkup(page, TYPED_FIELD, (_whole, name) => html `<input type="password" name="${name}" data-so-typed data-so-typed-held required>`);
+    return replaceMarkup(swap(held, ...rest), HELD_FIELD, (_whole, name) => html `<input type="password" name="${name}" data-so-typed autocomplete="current-password" required>`);
+}
+/** The rows that share this row's route: one handler's variants. */
+const variantsOf = (row) => PROOF_INVENTORY.filter(one => one !== row && one.routes.some(route => row.routes.includes(route)));
+/** How the dialog explains a proof that Passwordless doesn't cover, in words; null where nothing needs saying. */
+export function proofNote(row) {
+    if (row.proof === "credential")
+        return "This changes a way in, so it always takes your password.";
+    if (row.proof === "typed-password")
+        return "This always takes your password, typed.";
+    if (row.proof === "typed-now-operator")
+        return "Widening this takes an instance operator's password, typed now.";
+    return null;
+}
+/**
+ * A section's form, posted to its existing route with its existing fields, and its sticky Save. When the row needs a
+ * proof, the proof field sits in the form's own HTML — inline (as today, which is how it works without JavaScript) and
+ * moved into a `<dialog>` inside the same form by settings-kit-script.ts, which opens it on submit, keeps the pressed
+ * button, and posts nothing on Cancel. The server still proves everything.
+ */
+export function stepUpForm(form) {
+    const row = proofRow(form.proof);
+    if (!row.routes.includes(form.action))
+        throw new Error(`${row.id} doesn't post to ${form.action}`);
+    const hidden = form.hidden ?? {};
+    for (const name of Object.keys(hidden))
+        if (row.field === name || row.secrets.includes(name))
+            throw new Error(`${row.id}: ${name} is never a hidden value`);
+    // The exact variant: its own selector must be in the hidden terms, and no other variant's may be.
+    if (row.select !== undefined && String(hidden[row.select.field] ?? "") !== row.select.value)
+        throw new Error(`${row.id} posts ${row.select.field}=${row.select.value}`);
+    for (const other of variantsOf(row))
+        if (other.select !== undefined && String(hidden[other.select.field] ?? "") === other.select.value)
+            throw new Error(`${form.action} with ${other.select.field}=${other.select.value} is ${other.id}, not ${row.id}`);
+    const proof = proofField(row);
+    const asks = htmlString(proof) !== "";
+    const note = proofNote(row);
+    const save = form.save ?? {};
+    const submit = html `<button${attributes({ type: "submit", class: "kit-save", name: save.name ?? null, value: save.value ?? null })}>${save.label ?? "Save"}</button>`;
+    const dialog = asks ? html `<dialog class="kit-dialog" id="${form.id}-dialog" aria-labelledby="${form.id}-dialog-title" data-kit-dialog>\
+<h2 id="${form.id}-dialog-title">Confirm it's you</h2><p class="kit-dialog-terms">${form.confirm ?? row.action}${row.when === undefined ? "" : html ` <span class="kit-hint">(${row.when})</span>`}</p>\
+${note === null ? "" : html `<p class="kit-hint">${note}</p>`}<div class="kit-dialog-slot" data-kit-slot></div>\
+<div class="kit-dialog-actions"><button type="button" class="kit-cancel" data-kit-cancel>Cancel</button><button type="button" class="kit-confirm" data-kit-confirm>${save.label ?? "Save"}</button></div></dialog>` : "";
+    return postForm(form.action, joinHtml([
+        form.body,
+        asks ? html `<div class="kit-proof" data-kit-proof>${proof}</div>` : "",
+        html `<div class="kit-save-bar" data-kit-save-bar><span class="kit-save-state" aria-live="polite" data-kit-state data-idle="${save.idle ?? "No changes"}"></span>${submit}</div>`,
+        dialog,
+    ]), { hidden, attrs: { id: form.id, class: "kit-form", "data-kit-form": row.id, "data-kit-step-up": asks ? "" : null } });
+}
+/** A section: a heading, a one-line state, a problem the handler sent back (role=alert), then its form. */
+export function kitSection(section) {
+    return html `<section class="kit-section" id="${section.id}" aria-labelledby="${section.id}-title"><h2 id="${section.id}-title">${section.title}</h2>\
+${section.state === undefined ? "" : html `<p class="kit-state">${section.state}</p>`}\
+${section.problem ? html `<p class="kit-problem" role="alert">${section.problem}</p>` : ""}\
+${section.said ? html `<p class="kit-said" role="status">${section.said}</p>` : ""}${section.body}</section>`;
+}
+/** The kit's look: one 760px column, sections with no nested wells, the sticky Save, the dialog. The needs-you colour
+ * falls back to the warning token until S5 lands `--so-needs-you`. */
+export const SETTINGS_KIT_CSS = ":root{--so-settings-width:760px}" +
+    ".kit-crumbs ol{display:flex;flex-wrap:wrap;align-items:center;gap:6px;margin:0;padding:0;list-style:none;font-size:14px;color:var(--so-muted)}" +
+    ".kit-crumbs li+li::before{content:'/';margin-right:6px;color:var(--so-muted)}.kit-crumbs a{color:var(--so-muted);text-decoration:none}.kit-crumbs a:hover{color:var(--so-ink);text-decoration:underline}" +
+    ".kit-crumbs [aria-current]{color:var(--so-ink);font-weight:600}" +
+    ".kit-section{margin:0 0 32px}.kit-section>h2{margin:0 0 4px;font-size:16px}.kit-state{margin:0 0 12px;color:var(--so-muted)}" +
+    ".kit-problem{margin:0 0 12px;padding:10px 12px;border:1px solid var(--so-danger);border-radius:8px;color:var(--so-danger)}.kit-said{margin:0 0 12px;color:var(--so-muted)}" +
+    ".kit-field{margin:0 0 14px}.kit-hint{margin:2px 0 0;font-size:13px;color:var(--so-muted)}" +
+    ".kit-field-error{margin:4px 0 0;font-size:13px;color:var(--so-danger)}.kit-field [aria-invalid=true]{border-color:var(--so-danger)}" +
+    ".kit-choices{margin:0 0 14px;padding:0;border:0}.kit-choices legend{padding:0;margin:0 0 6px;font-weight:600}" +
+    ".kit-choice{display:grid;grid-template-columns:auto 1fr;column-gap:10px;align-items:start;min-height:44px;padding:8px 0;margin:0}.kit-choice input{margin:3px 0 0}.kit-choice-detail{grid-column:2;font-size:13px;color:var(--so-muted)}" +
+    ".kit-save-bar{position:sticky;bottom:0;z-index:2;display:flex;align-items:center;justify-content:space-between;gap:12px;margin:16px 0 0;padding:10px 0;border-top:1px solid var(--so-line);background:var(--so-paper)}" +
+    ".kit-save-state{color:var(--so-muted);font-size:14px}.kit-save-bar[data-changed] .kit-save-state{color:var(--so-ink)}" +
+    ".kit-js .kit-form[data-kit-step-up]>.kit-proof{display:none}" +
+    ".kit-dialog{max-width:min(440px,calc(100vw - 32px));padding:20px;border:1px solid var(--so-line);border-radius:12px;background:var(--so-paper);color:var(--so-ink)}" +
+    ".kit-dialog::backdrop{background:rgb(0 0 0 / .35)}.kit-dialog h2{margin:0 0 6px;font-size:17px}.kit-dialog-slot .kit-proof{display:block}" +
+    ".kit-dialog-actions{display:flex;justify-content:flex-end;gap:8px;margin:16px 0 0}" +
+    "@media (max-width:900px){.kit-save-bar button,.kit-dialog-actions button,.kit-crumbs a{min-height:44px}.kit-crumbs a{display:inline-flex;align-items:center}}";

package/dist/settings-proofs.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The settings proof inventory (docs/plans/settings-revamp.md §4): for every settings action, the proof its handler
+ * already asks for, as data. Only rendering code reads it (settings-kit.ts draws the step-up dialog from it); no
+ * handler does, and nothing here changes what a handler proves. `src/settings-kit.test.ts` pins every row against the
+ * form contracts (console-api.ts), the route table, and — for one row of each kind — the handler itself over HTTP.
+ *
+ * Proof kinds, as the handlers implement them (scope.ts, server/guards.ts):
+ * - `none`: the session and the form token (CSRF) only.
+ * - `step-up`: `authenticateApprover` — a password typed now; an empty field stands in under Passwordless (the
+ *   person's own live browser session) and for a one-use identity-provider re-check.
+ * - `credential`: `authenticateCredential` — a password typed now, or a one-use identity-provider re-check. Passwordless
+ *   never covers it.
+ * - `typed-password`: the handler checks the typed password itself (`authenticateAccount`, or an empty field refused
+ *   before the check). Neither Passwordless nor an identity-provider re-check stands in.
+ * - `typed-now-operator`: a password typed now by an instance operator (widening check access); not even a re-check.
+ */
+import { type ConsoleFormName } from "./contracts/console-api.js";
+export type ProofKind = "none" | "step-up" | "credential" | "typed-password" | "typed-now-operator";
+/** Who the route table admits (route-table.ts `role`); `handler` notes a narrower check the handler makes itself. */
+export type ProofRole = "any" | "approver" | "operator";
+export type ProofRow = {
+    /** Stable id the kit is called with. */
+    readonly id: string;
+    /** What the person is doing, in words. */
+    readonly action: string;
+    /** The exact POST paths. */
+    readonly routes: readonly string[];
+    /** The form contract its handler reads through. */
+    readonly form: ConsoleFormName;
+    /** The proof field's name, or null when none is read. */
+    readonly field: "password" | "token" | null;
+    readonly proof: ProofKind;
+    /** Only some submissions need the proof (the rest are `none`), in words. */
+    readonly when?: string;
+    /** Rows that share a route are variants of one handler, each with its own exact proof. A variant with `select`
+     * applies exactly when the form carries that hidden value (the kit refuses a form whose hidden terms pick another
+     * variant); a variant with `explicit` is named by the caller (a choice the server decides, like widening). */
+    readonly select?: {
+        readonly field: string;
+        readonly value: string;
+    };
+    readonly explicit?: true;
+    /** Under Passwordless, does an empty proof field pass? (`accepted` only for step-up.) */
+    readonly passwordless: "accepted" | "refused" | "n/a";
+    /** Does a one-use identity-provider re-check (empty field after "Confirm with …") pass? */
+    readonly sso: "accepted" | "refused" | "n/a";
+    readonly role: ProofRole;
+    /** A narrower standing the handler checks itself, in words. */
+    readonly handlerRole?: string;
+    /** Fields that hold a secret that is not the person's proof (never echoed, password managers kept out). */
+    readonly secrets: readonly string[];
+    /** Fields whose name reads like a credential but hold something else (an id, a bot token…). */
+    readonly notProof?: readonly string[];
+    /** Every term the handler requires besides the proof: hidden fields carried back unchanged (nonce, digest,
+     * fingerprint, the shown project, what a preview showed) and the fields that pick the target (repo, act). */
+    readonly terms: readonly string[];
+    /** Anything else the handler requires, in words. */
+    readonly note?: string;
+};
+export declare const PROOF_INVENTORY: readonly ProofRow[];
+/** One row by id; throws on an unknown id (a rendering bug, never a request's input). */
+export declare function proofRow(id: string): ProofRow;
+/** Whether the field a row names is one its form contract reads (used by the kit's own guard and the tests). */
+export declare function contractReads(row: ProofRow, field: string): boolean;

package/dist/settings-proofs.js

@@ -0,0 +1,101 @@
+/**
+ * The settings proof inventory (docs/plans/settings-revamp.md §4): for every settings action, the proof its handler
+ * already asks for, as data. Only rendering code reads it (settings-kit.ts draws the step-up dialog from it); no
+ * handler does, and nothing here changes what a handler proves. `src/settings-kit.test.ts` pins every row against the
+ * form contracts (console-api.ts), the route table, and — for one row of each kind — the handler itself over HTTP.
+ *
+ * Proof kinds, as the handlers implement them (scope.ts, server/guards.ts):
+ * - `none`: the session and the form token (CSRF) only.
+ * - `step-up`: `authenticateApprover` — a password typed now; an empty field stands in under Passwordless (the
+ *   person's own live browser session) and for a one-use identity-provider re-check.
+ * - `credential`: `authenticateCredential` — a password typed now, or a one-use identity-provider re-check. Passwordless
+ *   never covers it.
+ * - `typed-password`: the handler checks the typed password itself (`authenticateAccount`, or an empty field refused
+ *   before the check). Neither Passwordless nor an identity-provider re-check stands in.
+ * - `typed-now-operator`: a password typed now by an instance operator (widening check access); not even a re-check.
+ */
+import { CONSOLE_FORMS } from "./contracts/console-api.js";
+const ACCEPT = { passwordless: "accepted", sso: "accepted" };
+const CREDENTIAL = { passwordless: "refused", sso: "accepted" };
+const TYPED = { passwordless: "refused", sso: "refused" };
+const NONE = { passwordless: "n/a", sso: "n/a" };
+/** /mode/sign re-derives the digest from the posted terms, so every one rides back. */
+const MODE_TERMS = ["nonce", "digest", "expiry", "name", "days", "publication", "auto-approve", "plan-auto", "chat-approve"];
+const CHAT_APPS = [["slack", "Slack", "slack", ["app-token", "bot-token"]], ["teams", "Teams", "teams", ["secret"]], ["discord", "Discord", "discord", ["bot-token"]]];
+export const PROOF_INVENTORY = [
+    // CSRF only.
+    { id: "quality-default", action: "Set the default quality for new tasks", routes: ["/settings/quality-default"], form: "qualityDefault", field: null, proof: "none", ...NONE, role: "any", secrets: [], terms: [] },
+    { id: "notifications", action: "Choose what reaches you", routes: ["/settings/notifications"], form: "notifications", field: null, proof: "none", ...NONE, role: "any", secrets: [], terms: [] },
+    { id: "notifications-mute", action: "Mute a project", routes: ["/settings/notifications/mute"], form: "notificationsMute", field: null, proof: "none", ...NONE, role: "any", secrets: [], terms: [] },
+    { id: "messaging", action: "Choose the chat app that receives alerts", routes: ["/settings/messaging"], form: "messaging", field: null, proof: "none", ...NONE, role: "any", secrets: [], terms: [] },
+    { id: "telegram-digest", action: "Set the Telegram digest", routes: ["/settings/telegram-digest"], form: "telegramDigest", field: null, proof: "none", ...NONE, role: "any", secrets: [], terms: [] },
+    { id: "provider-key", action: "Save or clear an AI provider key", routes: ["/settings/provider-key", "/settings/provider-key-clear"], form: "providerKey", field: null, proof: "none", ...NONE, role: "any", secrets: ["value"], terms: [] },
+    { id: "telegram-token", action: "Save the Telegram bot token", routes: ["/settings/telegram-token"], form: "telegramToken", field: null, proof: "none", ...NONE, role: "any", secrets: ["token"], notProof: ["token"], terms: [] },
+    { id: "email", action: "Set up or test email", routes: ["/settings/email", "/settings/email-test", "/settings/email-read-test"], form: "email", field: null, proof: "none", ...NONE, role: "any", secrets: ["password"], notProof: ["password"], terms: [], note: "`password` is the mail server's password; its wire name stays" },
+    { id: "google", action: "Connect or disconnect Google", routes: ["/settings/google", "/settings/google/disconnect"], form: "google", field: null, proof: "none", ...NONE, role: "any", secrets: ["clientSecret"], terms: [] },
+    { id: "appearance", action: "Change the theme or accent", routes: ["/settings/appearance"], form: "appearance", field: null, proof: "none", ...NONE, role: "any", secrets: [], terms: [] },
+    { id: "chat-approval-confirm", action: "Review approving from chat", routes: ["/settings/chat-approval/confirm", "/settings/chat-approval/off"], form: "chatApproval", field: null, proof: "none", ...NONE, role: "approver", secrets: [], terms: [] },
+    ...CHAT_APPS.map(([app, name, form]) => ({ id: `${app}-alerts`, action: `Send alerts to ${name}`, routes: [`/settings/${app}/alerts`], form, field: null, proof: "none", ...NONE, role: "approver", secrets: [], terms: [] })),
+    // Step-up: a password typed now, the Passwordless session, or a one-use re-check.
+    { id: "permission-default", action: "Start new tasks with Full access", routes: ["/settings/permission-default"], form: "permissionDefault", field: "password", proof: "step-up", when: "only when widening to Full access", ...ACCEPT, role: "any", secrets: [], terms: [] },
+    { id: "spend-budget", action: "Set a monthly limit", routes: ["/spend/budget"], form: "spendBudget", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: [], terms: [] },
+    { id: "models-agent", action: "Change which model does each job", routes: ["/settings/models/agent"], form: "modelsChange", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: [], terms: ["scope", "digest"] },
+    { id: "models-apply", action: "Apply a model preset or switch", routes: ["/settings/models/apply"], form: "modelsChange", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: [], terms: ["scope", "digest", "change"], note: "plus the previewed preset, or switch and to" },
+    ...[
+        ["policy", "Change the policy", "policy", "operator"],
+        ["approval", "Change approval rules", "approval", "operator"],
+        ["request-limits", "Change request limits", "requestLimits", "operator"],
+        ["retention", "Change retention", "retention", "operator"],
+        ["backups", "Change backups", "backups", "operator"],
+        ["data", "Download everything", "data", "operator"],
+    ].map(([path, action, form, role]) => ({ id: path, action, routes: [`/settings/${path}`], form, field: "password", proof: "step-up", ...ACCEPT, role, secrets: [], terms: path === "approval" ? ["repo"] : [] })),
+    { id: "pull-requests", action: "Change pull-request settings, or turn them off", routes: ["/settings/pull-requests"], form: "pullRequests", field: "password", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo", "act"] },
+    { id: "pull-requests-on", action: "Turn pull requests on", routes: ["/settings/pull-requests"], select: { field: "act", value: "on" }, form: "pullRequests", field: "password", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo", "act", "github", "base"], note: "`github` and `base` are what the page showed; the handler checks again and refuses a difference" },
+    { id: "checks", action: "Change checks", routes: ["/settings/checks"], form: "checks", field: "password", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo", "act"] },
+    { id: "monitoring", action: "Change monitoring", routes: ["/settings/monitoring"], form: "monitoring", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: ["header-value"], terms: [] },
+    { id: "updates", action: "Update Toolroll", routes: ["/settings/updates", "/settings/updates/seen", "/settings/updates/cancel"], form: "updates", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: [], terms: [] },
+    { id: "storage-cleanup", action: "Choose when checkouts are removed", routes: ["/settings/storage"], form: "storage", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: [], terms: [] },
+    { id: "storage-clean", action: "Clean up checkouts", routes: ["/settings/storage/clean"], form: "storage", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: [], terms: ["preview"], note: "`preview` is the digest of what the page showed; a changed list is refused" },
+    { id: "storage-discard", action: "Discard a checkout", routes: ["/settings/storage/discard"], form: "storage", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: [], terms: ["path"] },
+    { id: "project-live-view", action: "Show a project's commands in the live view", routes: ["/settings/project/live-view"], form: "projectLiveView", field: "password", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo", "nonce"] },
+    { id: "project-delete", action: "Delete a project", routes: ["/settings/project/delete"], form: "projectDelete", field: "password", proof: "step-up", ...ACCEPT, role: "operator", secrets: [], terms: ["repo", "step"], note: "the project's name typed too" },
+    { id: "tools-connect", action: "Connect a tool", routes: ["/settings/tools/connect"], form: "toolsConnect", field: "password", proof: "step-up", ...ACCEPT, role: "approver", secrets: [], terms: ["repo", "shown"], note: "`shown` is the project the page showed (a post from another project is refused), not a digest" },
+    { id: "tools-change", action: "Change a project's tools", routes: ["/settings/tools/change"], form: "toolsChange", field: "password", proof: "step-up", when: "only to add a tool (catalog, custom, import) or set a secret", ...ACCEPT, role: "approver", secrets: ["value"], terms: ["repo", "shown", "action"] },
+    ...CHAT_APPS.map(([app, name, form]) => ({ id: `${app}-close`, action: `Unpair or disconnect ${name}`, routes: [`/settings/${app}/unpair`, `/settings/${app}/disconnect`], form, field: "password", proof: "step-up", ...ACCEPT, role: "approver", secrets: [], terms: [] })),
+    { id: "telegram-unpair", action: "Unpair your phone from Telegram", routes: ["/settings/telegram/unpair"], form: "telegramPair", field: "password", proof: "step-up", ...ACCEPT, role: "approver", secrets: [], terms: [] },
+    { id: "people-close", action: "Cancel an invite or remove a person", routes: ["/people/invite-revoke", "/people/revoke"], form: "peopleRevoke", field: "token", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver", secrets: [], terms: [] },
+    { id: "project-setup", action: "Approve project setup", routes: ["/control/setup-approve"], form: "projectSetup", field: "token", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver of the project; models for a new installation need an instance operator", secrets: [], terms: ["repo", "nonce", "fingerprint", "provider", "model", "command", "seconds"], note: "the nonce is spent before the password is checked: after a refusal, review again; the reviewed inputs are previewed again and must match the fingerprint" },
+    { id: "project-instructions", action: "Add the agent instructions", routes: ["/control/instructions-approve"], form: "projectSetup", field: "token", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo", "nonce", "fingerprint"], note: "the nonce is spent before the password is checked" },
+    { id: "mode-sign", action: "Sign an operating mode", routes: ["/mode/sign"], form: "mode", field: "token", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver of the project", secrets: [], terms: MODE_TERMS },
+    { id: "mode-sign-chat-approve", action: "Sign an operating mode that lets your chat app approve", routes: ["/mode/sign"], select: { field: "chat-approve", value: "1" }, form: "mode", field: "token", proof: "credential", ...CREDENTIAL, role: "any", handlerRole: "an approver of the project", secrets: [], terms: MODE_TERMS },
+    // Credential acts: a password typed now or a one-use re-check; never Passwordless.
+    { id: "passwordless-on", action: "Turn Passwordless on", routes: ["/settings/passwordless"], form: "passwordless", field: "password", proof: "credential", when: "only to turn it on (off needs nothing)", ...CREDENTIAL, role: "operator", secrets: [], terms: [] },
+    { id: "sign-in", action: "Change sign-in (SSO)", routes: ["/settings/sign-in"], form: "signIn", field: "password", proof: "credential", when: "every action except Test", ...CREDENTIAL, role: "operator", secrets: ["client-secret"], terms: [] },
+    { id: "release-approval", action: "Approve releases automatically", routes: ["/settings/release-approval"], form: "releaseApproval", field: "password", proof: "credential", when: "only to approve automatically (Ask me needs nothing)", ...CREDENTIAL, role: "approver", handlerRole: "an approver of the project", secrets: [], terms: ["repo"] },
+    { id: "project-network", action: "Change what builds may reach", routes: ["/settings/project/network"], form: "projectNetwork", field: "password", proof: "credential", ...CREDENTIAL, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo"] },
+    { id: "project-writes", action: "Change where builds may write", routes: ["/settings/project/writes"], form: "projectWrites", field: "password", proof: "credential", ...CREDENTIAL, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo"] },
+    { id: "project-sandbox", action: "Change a project's sandbox", routes: ["/settings/project/sandbox"], form: "projectSandbox", field: "password", proof: "credential", ...CREDENTIAL, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo"] },
+    { id: "project-check-access", action: "Narrow how far checks reach", routes: ["/settings/project/check-access"], form: "projectCheckAccess", field: "password", proof: "credential", ...CREDENTIAL, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo"], note: "for a form that can only narrow; one that offers a wider level uses project-check-access-widen" },
+    { id: "project-check-access-widen", action: "Widen how far checks reach", routes: ["/settings/project/check-access"], explicit: true, form: "projectCheckAccess", field: "password", proof: "typed-now-operator", ...TYPED, role: "any", handlerRole: "an instance operator", secrets: [], terms: ["repo"], note: "the server decides whether a choice widens; a form offering any wider level asks for this proof" },
+    ...CHAT_APPS.map(([app, name, form, secrets]) => ({ id: `${app}-open`, action: `Connect or pair ${name}`, routes: [`/settings/${app}/connect`, `/settings/${app}/pair`], form, field: "password", proof: "credential", ...CREDENTIAL, role: "approver", secrets, terms: [] })),
+    { id: "sessions-token", action: "Make an API token", routes: ["/settings/sessions"], form: "sessions", field: "password", proof: "credential", when: "only to make a token (ending sessions and revoking tokens need nothing)", ...CREDENTIAL, role: "any", secrets: [], notProof: ["token"], terms: [], note: "`token` here names an API token to revoke" },
+    { id: "people-invite", action: "Invite someone", routes: ["/people/invite"], form: "peopleInvite", field: "token", proof: "credential", ...CREDENTIAL, role: "any", handlerRole: "an approver", secrets: [], terms: [] },
+    { id: "people-projects", action: "Change a person's projects", routes: ["/people/projects"], form: "peopleProjects", field: "token", proof: "credential", ...CREDENTIAL, role: "operator", secrets: [], terms: ["name"] },
+    // A typed password, checked by the handler itself.
+    { id: "telegram-pair", action: "Pair your phone with Telegram", routes: ["/settings/telegram/pair"], form: "telegramPair", field: "password", proof: "typed-password", ...TYPED, role: "approver", secrets: [], terms: [] },
+    { id: "chat-approval-save", action: "Turn on approving from chat", routes: ["/settings/chat-approval/save"], form: "chatApproval", field: "token", proof: "typed-password", ...TYPED, role: "approver", secrets: [], terms: ["nonce", "digest", "scope", "full-access", "cap-usd"] },
+    { id: "push-subscribe", action: "Get alerts on this device", routes: ["/push/subscribe"], form: "pushSubscribe", field: "token", proof: "typed-password", ...TYPED, role: "any", handlerRole: "an approver", secrets: [], terms: ["endpoint", "p256dh", "auth"] },
+    { id: "lead-config", action: "Set up the lead's model and its own key", routes: ["/chat/config"], form: "chatConfig", field: "token", proof: "typed-password", ...TYPED, role: "any", handlerRole: "an approver", secrets: ["key"], terms: [] },
+];
+const BY_ID = new Map(PROOF_INVENTORY.map(row => [row.id, row]));
+/** One row by id; throws on an unknown id (a rendering bug, never a request's input). */
+export function proofRow(id) {
+    const row = BY_ID.get(id);
+    if (row === undefined)
+        throw new Error(`no proof inventory row ${id}`);
+    return row;
+}
+/** Whether the field a row names is one its form contract reads (used by the kit's own guard and the tests). */
+export function contractReads(row, field) {
+    return CONSOLE_FORMS[row.form].fields.includes(field);
+}

package/dist/setup-guide.js

@@ -15,8 +15,10 @@ export const ASSISTANTS = withAcp({
 export function modelChoices(provider, configured, home = homedir()) {
     // Aliases documented at https://code.claude.com/docs/en/model-config.
     let choices = provider === "claude"
-        ? [{ value: "sonnet", label: "Sonnet — everyday coding" }, { value: "opus", label: "Opus — complex tasks" },
-            { value: "haiku", label: "Haiku — smaller tasks" }]
+        // Exact ids first: Sonnet 5.5 builds routine tasks under "Sized by job" (Settings → Models); the short names float.
+        ? [{ value: "claude-sonnet-5-5", label: "Sonnet 5.5 — routine tasks" }, { value: "claude-opus-5-5", label: "Opus 5.5 — large or risky tasks" },
+            { value: "claude-haiku-5-5", label: "Haiku 5.5 — small tasks" }, { value: "sonnet", label: "Sonnet (floating) — moves to the newest version" },
+            { value: "opus", label: "Opus (floating) — moves to the newest version" }, { value: "haiku", label: "Haiku (floating) — moves to the newest version" }]
         : [];
     if (provider === "codex") {
         // Use the local CLI's own catalog, including account-specific availability.