@bongos/core 1.19.772 → 1.19.774

package/docs/file-map.md

@@ -189,6 +189,7 @@
 │       ├── smoke-write.sh       ← write-path smoke (create→claim→ship round-trip)
 │       ├── backup-dropin-sweep.sh ← (task 1003930) control-plane sweep: retires the temporary task-1003925 backup drop-in from each project whose pinned core carries the fix (1.19.750+), proving one backup succeeds without it first; survey by default, `--apply` to act; re-run after each pin moves
 │       ├── stray-unit-sweep.sh  ← (task 1003939) control-plane sweep: the ledger's torn-down slugs that still have a service/backup unit loaded or on disk (a torn-down project holding memory outside the ADR 0285 count); survey by default, `--apply` disables, removes, reloads, reset-failed's; DB/dumps/checkout/Caddy left alone
+│       ├── address-park-sweep.sh ← (task 1003947) control-plane sweep: the ledger's torn-down rows that still have a `<slug>.caddy` block or a hostname not yet parked (rows torn down before task 1002897 taught teardown to do both); survey by default, `--apply` removes the snippets, reloads Caddy and parks each non-reserved hostname at 192.0.2.1 via the DNS hook; the reserved rule, zone and apex come from the installed core
 │       ├── smoke-gds.js         ← public-surface + 401-check smoke test (asserts /api/pms/* now 404s — removed in V3.R01-followup #308)
 │       ├── box.js               ← (#598/ADR 0031) per-builder dev box lifecycle CLI: provision·park·wake·deprovision·sweep-idle·sweep-dormant·status (dry-run default, --apply to act; rank-gated)
 │       ├── smoke-box.sh         ← (#598) hermetic box-lifecycle smoke (no DB/DO/network): runs tests/boxes.mjs + tests/cf_tunnel.mjs (#771 named tunnel) + route-rank + module-load

package/docs/module-api-changelog.md

@@ -2018,5 +2018,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.770 with no explicit bump. run 35116254725. (task 1002620)
   1.19.772 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.771 with no explicit bump. run 35117652607. (task 1002620)
+  1.19.773 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.772 with no explicit bump. run 35118731311. (task 1002620)
+  1.19.774 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.773 with no explicit bump. run 35132992149. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/modules-contract.md

@@ -249,7 +249,7 @@ A module puts its SQL files under `modules/<key>/migrations/NNN_description.sql`
 
 Rules (enforced by the `BV1.R45` fitness check):
 - **Own your namespace** — every table must be prefixed `<key>_*`.
-- **Additive only** — `DROP TABLE`, `DROP COLUMN`, and destructive `ALTER` are rejected by the fitness check.
+- **Additive only** — `DROP TABLE`, `DROP COLUMN`, and destructive `ALTER` are rejected by the fitness check. **One acknowledged exception** (task 1003092): the *contract phase* of an expand-then-contract rename ([ADR 0177](adr/0177-goal-membership-kind.md)) may carry exactly `ALTER TABLE <own_table> DROP COLUMN <legacy>` when the file bears the same `-- forward-unsafe: <reason>` pragma core migrations use — one statement, one column, your own table; `DROP TABLE`, `TRUNCATE` and a bare `DROP CONSTRAINT` stay rejected even under the pragma (`scripts/gds/fitness-migration-contraction.js`).
 - **Disable preserves data** — there is no down-migration; a disabled module's tables simply are never created (or are left untouched).
 
 ---

package/modules/builder-settings/render-prefs.js

@@ -1,63 +1,280 @@
-// src/bongos/render-prefs.js — the per-builder "render widgets" knob (task 1279).
+// modules/builder-settings/render-prefs.js — the per-builder CARD RICHNESS knob
+// (task 1279 as a boolean; levels + profile derivation by task 1002518).
 //
-// Governs whether the deterministic session cards (start.js's /builder-start
+// Governs how much the deterministic session cards (start.js's /builder-start
 // card + the ship-card lifecycle card: claimed → review → confirmed → shipped)
-// render as a rich in-feed HTML widget (via the app's show_widget tool) or as
-// the plain markdown / monospace fallback.
+// spend on the reader: a rich in-feed HTML widget (via the app's show_widget
+// tool), the plain monospace fallback, or nothing but the guaranteed one-line
+// confirmation.
 //
 // Why it's a knob: the widget is nicer, but the agent must relay its full markup
 // VERBATIM into show_widget — reading it once and re-emitting it once — so every
 // byte of HTML is shuttled through the model twice, at every session-start,
 // claim, and ship stage. Measured: the /builder-start widget is ~4.7K tokens vs
 // ~0.5K for the markdown form (9×); the lifecycle card ~0.9K vs ~0.12K monospace
-// (7×). This knob lets a builder turn that token cost off. When off, the CLIs
-// emit ONLY the text form (no HTML is ever written or relayed) — so it's a real
-// saving, not just a visual change.
+// (7×). This knob lets a builder spend or save that.
 //
 // Unlike the wandering knob ([[wandering-prefs]]) this is pure cost/taste, NOT a
-// trust gate — so there is NO rank cap: any builder may pick either value, and
-// the default is ON (the experience tasks 1273/1275 deliberately shipped).
+// trust gate — so there is NO rank cap: any builder may pick any level.
+//
+// ---------------------------------------------------------------------------
+// WHY LEVELS AND NOT A BOOLEAN (task 1002518, clause 6 of criterion
+// `accessibility-fluency-profile`).
+//
+// The boolean conflated two independent questions — "how much explanation do I
+// want?" and "how many tokens will I spend?" — and answered both with one
+// switch. That left no way to ask for LESS noise without dropping to the plain
+// text card, and no way to ask for MORE explanation than the widget's default
+// (whose summary ships collapsed, so the part that actually explains the work is
+// behind a click the reader has to know to make).
+//
+// The deeper problem is that it was the ONE surface knob that ignored the
+// interaction profile. The builder who most needs an explanatory card — the
+// non-technical one, who by definition has not opened Settings — got exactly the
+// same card as an engineer who wants a one-liner and nothing else. That is the
+// same failure interaction-prefs.js names in its own preamble: a profile that
+// worked for everyone who had already opted out of it. Richness is not cost/taste
+// alone; it is a fluency question, and fluency already has a profile. So the
+// level DERIVES from that profile, and the knob becomes the override rather than
+// the only input.
+// ---------------------------------------------------------------------------
+//
+// THE LADDER, least to most. The ordering is the contract: index is richness,
+// and every consumer asks a predicate (showsCard / showsWidget / widgetExpanded)
+// rather than comparing level strings, so inserting a rung later is additive.
+//
+//   minimal   the guaranteed [otb-confirm] line only — no card at all.
+//   text      the monospace / markdown card. No HTML is written or relayed.
+//   standard  the HTML widget, summary collapsed.  (the historical `true`)
+//   rich      the HTML widget, summary open on arrival — the explanation is
+//             the point for this reader, so it is not hidden behind a click.
+//
+// `text` is the historical `false` and `standard` the historical `true`, so a
+// builder who already flipped the toggle keeps precisely the card they chose.
 //
 // Storage: one reserved key ('widgets') inside the `behavior_prefs` jsonb column
-// on `builders` (migration 119 — the same blob the wandering knob uses). Value
-// is a scalar boolean; a missing key falls back to DEFAULT_ENABLED, so the
-// column stays sparse. applyPatch leaves sibling keys (e.g. 'wandering') alone.
+// on `builders` (migration 119 — the same blob the wandering and interaction
+// knobs use). The value is a level STRING; the legacy booleans are still read
+// and still mean what they meant. A missing key falls back to the DERIVED level,
+// so the column stays sparse and a builder who never touches this gets a card
+// pitched at the profile they did set.
 //
 // This module is the single source of truth: GET/PATCH /api/gds/me/render + the
 // /me payload surface it, the /settings UI reads it, and the start/claim/ship
-// CLIs read the resolved boolean to decide whether to emit HTML at all.
+// CLIs read the resolved level to decide what to emit.
+
+const interactionPrefs = require('./interaction-prefs');
 
 const RESERVED_KEY = 'widgets';
+
+// Ordered least → most rich. Index IS the richness rank; see the ladder note.
+const LEVELS = ['minimal', 'text', 'standard', 'rich'];
+
+// The historical boolean default (ON). Kept exported because the legacy boolean
+// surface is still live: describeForApi still ships `widgets_enabled`, and CLIs
+// pinned to an older core still read only that. It is also the honest answer for
+// the unset default builder, whose derived level is `rich` — i.e. enabled.
 const DEFAULT_ENABLED = true;
 
-// ---- pure helpers ----
+// The level each legacy boolean means. Chosen so an existing override is a
+// no-op: whoever set the toggle keeps the exact card they picked.
+const LEGACY_LEVEL = { true: 'standard', false: 'text' };
 
-// The raw override a builder has stored (the 'widgets' key off behavior_prefs),
-// or null when unset/invalid. Kept separate from the effective value so the UI
-// can show "you chose X" vs "the default (Y)".
-function overrideEnabled(behaviorPrefs) {
+// ---- the ladder ------------------------------------------------------------
+
+function isLevel(value) {
+  return typeof value === 'string' && LEVELS.includes(value);
+}
+
+function levelRank(level) {
+  const i = LEVELS.indexOf(level);
+  return i === -1 ? LEVELS.indexOf('standard') : i;
+}
+
+function clampRank(rank) {
+  return Math.max(0, Math.min(LEVELS.length - 1, rank));
+}
+
+// ---- predicates: what a level actually means to a card emitter -------------
+// Consumers ask these, never `level === 'rich'`, so the ladder can grow.
+
+// Does anything beyond the one-line [otb-confirm] get printed?
+function showsCard(level) {
+  return levelRank(level) >= levelRank('text');
+}
+
+// Is HTML written and relayed into show_widget at all? This is the predicate the
+// historical boolean was, and widgetsEnabled() is its alias.
+function showsWidget(level) {
+  return levelRank(level) >= levelRank('standard');
+}
+
+// Does the widget arrive with its summary already open?
+function widgetExpanded(level) {
+  return levelRank(level) >= levelRank('rich');
+}
+
+// The three predicates as one object, which is how a card emitter consumes them.
+//
+// WHY THIS SHAPE EXISTS: modules/lifecycle/ship-card.js draws the cards but may
+// not require this file — a module imports only src/module-api.js, never a
+// sibling module (ADR 0083, enforced by fitness.js). So the ladder cannot travel
+// as a level string that lifecycle would have to interpret; it travels as
+// answers. The CLI scripts (outside modules/, free to require both) call this
+// and hand the result to emitCard. One ladder, one owner, no duplicated rungs.
+function cardFlags(level) {
+  return {
+    level,
+    showCard: showsCard(level),
+    showWidget: showsWidget(level),
+    expanded: widgetExpanded(level),
+  };
+}
+
+// ---- derivation from the interaction profile -------------------------------
+//
+// The interaction profile lives in the SAME behavior_prefs blob (reserved key
+// 'interaction'), so nothing here needs a second argument or a second read.
+//
+// The rule, stated so it can be argued with:
+//   base   technical_level is the primary axis — it is the field that says how
+//          much explanation the reader wants. non_technical → rich, mixed →
+//          standard, engineer → text.
+//   -1     machinery: quiet. That knob's whole content is "report outcomes, not
+//          mechanism", and a lifecycle card IS mechanism — stage ribbons, claim
+//          bookkeeping, grade rows. A reader who asked for less of that should
+//          not be handed the richest possible rendering of it.
+//   +1     verbosity: detailed. Asks for fuller explanation; the card is where
+//          this knob can actually deliver some.
+//
+// verbosity: concise is deliberately NOT -1. It is the DEFAULT, so subtracting
+// for it would push the default builder from `rich` down to `standard` — the
+// accessible-by-default reader would get the less explanatory card, which is the
+// exact inversion this task exists to fix. technical_level already sets the base
+// low for readers who want terseness; concise must not tax them twice.
+const BASE_BY_TECHNICAL_LEVEL = {
+  non_technical: 'rich',
+  mixed: 'standard',
+  engineer: 'text',
+};
+
+// The level a builder gets with no override — derived from their interaction
+// profile. Pure; takes the same behavior_prefs blob as everything else here.
+function derivedLevel(behaviorPrefs) {
+  const profile = interactionPrefs.effectiveProfile(behaviorPrefs);
+  const base = BASE_BY_TECHNICAL_LEVEL[profile.technical_level] || 'standard';
+  let rank = levelRank(base);
+  if (profile.machinery === 'quiet') rank -= 1;
+  if (profile.verbosity === 'detailed') rank += 1;
+  return LEVELS[clampRank(rank)];
+}
+
+// A short, human sentence saying WHY the derived level is what it is — the
+// /settings panel shows it so "default" is never a black box.
+function derivedReason(behaviorPrefs) {
+  const profile = interactionPrefs.effectiveProfile(behaviorPrefs);
+  const bits = [`technical level: ${profile.technical_level.replace(/_/g, '-')}`];
+  if (profile.machinery === 'quiet') bits.push('machinery: quiet');
+  if (profile.verbosity === 'detailed') bits.push('reply length: detailed');
+  return `From your interaction profile (${bits.join(', ')}).`;
+}
+
+// ---- overrides -------------------------------------------------------------
+
+// The raw override a builder has stored, as a LEVEL, or null when unset/invalid.
+// Legacy booleans are read through LEGACY_LEVEL so an old stored value keeps its
+// meaning. Kept separate from the effective value so the UI can show
+// "you chose X" vs "the default (Y)".
+function overrideLevel(behaviorPrefs) {
   const raw = behaviorPrefs && behaviorPrefs[RESERVED_KEY];
-  return typeof raw === 'boolean' ? raw : null;
+  if (isLevel(raw)) return raw;
+  if (typeof raw === 'boolean') return LEGACY_LEVEL[String(raw)];
+  return null;
+}
+
+// The resolved level — the value the CLIs act on. Override if set, else derived.
+function resolveLevel(behaviorPrefs) {
+  return overrideLevel(behaviorPrefs) || derivedLevel(behaviorPrefs);
 }
 
-// The resolved boolean — the value the CLIs act on. Override if set, else the
-// default. This is the one function the start/claim/ship scripts care about.
+// ---- the legacy boolean surface --------------------------------------------
+// Unchanged in meaning and still the shape every pinned CLI reads: true exactly
+// when the resolved level writes and relays HTML.
 function widgetsEnabled(behaviorPrefs) {
-  const o = overrideEnabled(behaviorPrefs);
-  return o === null ? DEFAULT_ENABLED : o;
+  return showsWidget(resolveLevel(behaviorPrefs));
+}
+
+// The legacy override accessor: the boolean a caller would have seen before
+// levels existed. `minimal`/`text` → false, `standard`/`rich` → true, unset →
+// null. Preserved so nothing reading `override` has to learn the ladder.
+function overrideEnabled(behaviorPrefs) {
+  const lvl = overrideLevel(behaviorPrefs);
+  return lvl === null ? null : showsWidget(lvl);
 }
 
-// Everything the /me payload + the /settings UI need in one object.
+// ---- the API payload -------------------------------------------------------
+
+const LEVEL_META = {
+  minimal: {
+    label: 'Minimal',
+    blurb: 'One confirmation line and nothing else. The cheapest possible surface.',
+  },
+  text: {
+    label: 'Plain text',
+    blurb: 'The monospace card. Same information as the widget, no HTML relayed — cheaper.',
+  },
+  standard: {
+    label: 'Rich card',
+    blurb: 'The in-feed widget, with the detail folded behind a summary toggle.',
+  },
+  rich: {
+    label: 'Rich card, expanded',
+    blurb: 'The in-feed widget with the summary already open — most explanatory, most tokens.',
+  },
+};
+
+function levelCatalog() {
+  return LEVELS.map((value) => ({
+    value,
+    label: LEVEL_META[value].label,
+    blurb: LEVEL_META[value].blurb,
+  }));
+}
+
+// Everything the /me payload + the /settings UI need in one object. The four
+// legacy keys stay first and stay exactly what they were: a CLI pinned to an
+// older core reads `widgets_enabled` and is correct.
 function describeForApi(behaviorPrefs) {
+  // Resolve each fact ONCE. resolveLevel/overrideEnabled/derivedReason each
+  // re-walk the same prefs blob, so calling them field-by-field re-derived the
+  // override and the interaction profile two or three times per request.
+  const override = overrideLevel(behaviorPrefs);
+  const derived = derivedLevel(behaviorPrefs);
+  const level = override || derived;
   return {
-    widgets_enabled: widgetsEnabled(behaviorPrefs),
+    widgets_enabled: showsWidget(level),
     default_enabled: DEFAULT_ENABLED,
-    override: overrideEnabled(behaviorPrefs),
+    override: override === null ? null : showsWidget(override),
+    // --- levels (task 1002518) ---
+    level,
+    // The three booleans a card emitter needs, RESOLVED SERVER-SIDE. This is not
+    // a convenience: scripts/gds/start.js runs on a task-scoped dev box that
+    // carries scripts/ and src/bongos/ but not every modules/ directory (task
+    // 1003098), so a CLI cannot require this file to learn what a rung draws —
+    // tree-preflight fails the entry point that tries. Shipping the answers
+    // keeps the ladder in one place AND keeps the CLI dependency-free.
+    flags: cardFlags(level),
+    levels: levelCatalog(),
+    derived_level: derived,
+    derived_reason: derivedReason(behaviorPrefs),
+    override_level: override,
   };
 }
 
-// Validate a PATCH body: { widgets: <bool> | null }. `null` clears the override
-// (fall back to the default). Unknown keys → 422. Non-boolean values → 422.
+// Validate a PATCH body: { widgets: <level> | <bool> | null }. `null` clears the
+// override (fall back to the derived level). Booleans are still accepted and
+// still mean what they meant — an older hall build PATCHing `{widgets:false}`
+// must keep working against a newer core. Unknown keys → 422.
 // Returns { ok, patch } or { ok:false, errors }. An empty body is a valid no-op.
 function validatePatch(body) {
   if (body == null || typeof body !== 'object' || Array.isArray(body)) {
@@ -70,19 +287,34 @@ function validatePatch(body) {
       errors.push({ key, error: 'unknown_key', allowed: [RESERVED_KEY] });
       continue;
     }
-    if (value === null || typeof value === 'boolean') {
-      patch[RESERVED_KEY] = value; // null = clear → default
+    if (value === null) {
+      patch[RESERVED_KEY] = null; // null = clear → derived
+      continue;
+    }
+    if (isLevel(value)) {
+      patch[RESERVED_KEY] = value;
+      continue;
+    }
+    // Normalise the legacy boolean on the way IN, so storage only ever holds a
+    // level and the compatibility shim stays at this one boundary.
+    if (typeof value === 'boolean') {
+      patch[RESERVED_KEY] = LEGACY_LEVEL[String(value)];
       continue;
     }
-    errors.push({ key, error: 'invalid_value', value, allowed: 'boolean or null' });
+    errors.push({
+      key,
+      error: 'invalid_value',
+      value,
+      allowed: `one of ${LEVELS.join(', ')} (or a boolean, or null to clear)`,
+    });
   }
   if (errors.length > 0) return { ok: false, errors };
   return { ok: true, patch };
 }
 
 // Apply a validated patch to a builder's existing behavior_prefs. Pure. null
-// deletes the key (fall back to default); a boolean overwrites. Other keys in
-// the blob (e.g. the wandering knob) are left untouched.
+// deletes the key (fall back to derived); a level overwrites. Other keys in the
+// blob (e.g. the wandering and interaction knobs) are left untouched.
 function applyPatch(existing, patch) {
   const next = { ...(existing || {}) };
   for (const [key, value] of Object.entries(patch)) {
@@ -95,8 +327,24 @@ function applyPatch(existing, patch) {
 module.exports = {
   RESERVED_KEY,
   DEFAULT_ENABLED,
+  LEVELS,
+  // the ladder
+  isLevel,
+  levelRank,
+  showsCard,
+  showsWidget,
+  widgetExpanded,
+  cardFlags,
+  levelCatalog,
+  // resolution
+  derivedLevel,
+  derivedReason,
+  overrideLevel,
+  resolveLevel,
+  // the legacy boolean surface
   overrideEnabled,
   widgetsEnabled,
+  // api
   describeForApi,
   validatePatch,
   applyPatch,

package/modules/builder-settings/routes/settings.js

@@ -337,14 +337,19 @@ module.exports = function buildBuilderSettingsRouter() {
     }
   });
 
-  // Per-builder "render widgets" knob (task 1279, shares the behavior_prefs
-  // jsonb / migration 119). Whether the deterministic session cards render as a
-  // rich in-feed HTML widget or the plain text fallback. The widget is nicer but
-  // the agent must relay its full markup verbatim into show_widget (read +
-  // re-emit) every session-start / claim / ship stage — a real token cost. This
-  // toggle turns that off; when off the CLIs emit only text (no HTML relayed).
-  // No rank cap (pure cost/taste, not a trust gate); default ON. render-prefs.js
-  // is the single source of truth.
+  // Per-builder CARD RICHNESS knob (task 1279, a four-rung ladder since task
+  // 1002518; shares the behavior_prefs jsonb / migration 119). How much the
+  // deterministic session cards spend on the reader: nothing but the guaranteed
+  // confirmation line, the plain text card, the in-feed HTML widget, or that
+  // widget with its summary already open. The widget is nicer but the agent must
+  // relay its full markup verbatim into show_widget (read + re-emit) every
+  // session-start / claim / ship stage — a real token cost.
+  //
+  // No rank cap (pure cost/taste, not a trust gate). The DEFAULT is derived from
+  // the builder's interaction profile rather than being a constant, so a builder
+  // who never opens this panel still gets a card pitched at the profile they did
+  // set. render-prefs.js is the single source of truth for both the ladder and
+  // the derivation.
   //
   // rank: any-builder — own profile config; mirrors the skill/sound/wandering routes.
   router.get('/me/render', api.requireBuilder, async (req, res) => {
@@ -357,10 +362,13 @@ module.exports = function buildBuilderSettingsRouter() {
     }
   });
 
-  // PATCH the render knob. Body: { widgets: <bool> | null } where null clears the
-  // override (fall back to the default ON). Any other key, or a non-boolean
-  // value → 422. Empty body is a no-op (returns current). Sibling behavior keys
-  // (e.g. wandering) are preserved by applyPatch.
+  // PATCH the render knob. Body: { widgets: <level> | <bool> | null } where null
+  // clears the override (fall back to the DERIVED level). The legacy boolean is
+  // still accepted and normalised to the rung it always meant, so an older hall
+  // build keeps working against this core. Any other key, or a value that is
+  // neither a known level nor a boolean nor null → 422. Empty body is a no-op
+  // (returns current). Sibling behavior keys (wandering, interaction) are
+  // preserved by applyPatch.
   //
   // rank: any-builder — self-service profile edit; same posture as /me/wandering.
   router.patch('/me/render', api.requireBuilder, async (req, res) => {

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -704,6 +704,8 @@ function createClient(opts = {}) {
       getProvisioningInstancesId: (args) => request("GET", "/provisioning/instances/{id}", { hasBody: false }, args),
       // PATCH /provisioning/instances/{id}/detail — rank: any-builder — PATCH /provisioning/instances/:id/detail
       patchProvisioningInstancesIdDetail: (args) => request("PATCH", "/provisioning/instances/{id}/detail", { hasBody: true }, args),
+      // POST /provisioning/instances/{id}/disconnect — rank: any-builder — POST /provisioning/instances/:id/disconnect
+      postProvisioningInstancesIdDisconnect: (args) => request("POST", "/provisioning/instances/{id}/disconnect", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/domain — rank: any-builder — POST /provisioning/instances/:id/domain
       postProvisioningInstancesIdDomain: (args) => request("POST", "/provisioning/instances/{id}/domain", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/force-teardown — rank: metic+archon — POST /provisioning/instances/:id/force-teardown

package/modules/dev-box/module.json

@@ -10,6 +10,10 @@
     "pollers": ["box-lifecycle"],
     "uiSections": ["boxes"]
   },
+  "declarativeSeams": {
+    "pollers": ["box-lifecycle"],
+    "uiSections": ["boxes"]
+  },
   "provides": ["box.hasEverConnected"],
   "consumes": []
 }

package/modules/hall-ui/public/settings-render.js

@@ -0,0 +1,138 @@
+// modules/hall-ui/public/settings-render.js — the "Rendering" panel on
+// /builders/settings: how rich the deterministic session cards should be
+// (task 1279's on/off toggle, a four-rung ladder since task 1002518).
+//
+// WHY ITS OWN FILE. It began as one row with one switch inside settings.js. As a
+// ladder it needs a labelled option per rung plus a line explaining what the
+// default resolved to and why — and settings.js sits against the 1500-line size
+// ratchet, so the panel moved out on the settings-sessions.js / settings-
+// interaction.js precedent. Extracting it took settings.js from 1493 to 1425.
+//
+// THE SHAPE WORTH KNOWING: unlike every other picker on this page, "default"
+// here is not a constant — it is DERIVED from the builder's interaction profile
+// (render-prefs.js maps technical level, machinery and reply length onto a
+// rung). So the default option cannot just say "default"; it has to say which
+// rung it landed on and which profile fields put it there, or the reader sees a
+// choice the system made for reasons it never stated. The server ships both
+// facts (`derived_level`, `derived_reason`) precisely so this panel can.
+//
+// PATCH body is { widgets: <level> | null } — null clears the override and
+// returns the builder to the derived rung. The route still accepts the legacy
+// boolean, which is what lets an older hall build keep working against a newer
+// core; this panel only ever sends levels or null.
+
+(() => {
+  'use strict';
+
+  const API = '/api/bongos';
+  const { escapeHtml, $ } = window.OTB;
+  const toast = (msg) => window.OTB.toast(msg);
+  const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
+
+  const toAuth = () => window.location.assign(`${API}/auth/web/start`);
+
+  // The "let the profile decide" option carries the sentinel value '' rather
+  // than a level, so the change handler can tell "clear my override" from
+  // "pin me to the rung that happens to be the derived one today". They differ:
+  // a pinned rung survives a later change to the interaction profile.
+  const USE_DEFAULT = '';
+
+  function labelForLevel(data, level) {
+    const found = (Array.isArray(data && data.levels) ? data.levels : []).find((l) => l.value === level);
+    return (found && found.label) || level;
+  }
+
+  function render(data) {
+    const wrap = $('#render-rows');
+    if (!wrap) return;
+    const levels = Array.isArray(data && data.levels) ? data.levels : [];
+    if (levels.length === 0) {
+      wrap.innerHTML = window.OTBKit.emptyStateHtml('No rendering options registered.');
+      return;
+    }
+    const override = data.override_level || null;
+    const derived = data.derived_level;
+
+    // The default row first, so the reader meets "you already have a sensible
+    // answer, here is what it is" before the list of ways to overrule it.
+    const defaultRow =
+      `<label class="prow prow--pick" for="render-default">` +
+      `<input class="pradio" type="radio" name="render-level" id="render-default"` +
+      ` value="${USE_DEFAULT}"${override === null ? ' checked' : ''}>` +
+      '<span class="prow__main">' +
+      `<span class="prow__label">Match my interaction profile` +
+      `<span class="prow__tag">default (${escapeHtml(labelForLevel(data, derived))})</span></span>` +
+      `<span class="prow__desc">${escapeHtml(data.derived_reason || '')} Change that profile and this follows it.</span>` +
+      '</span></label>';
+
+    const rows = levels.map((l) => {
+      const id = `render-level-${l.value}`;
+      return (
+        `<label class="prow prow--pick" for="${id}">` +
+        `<input class="pradio" type="radio" name="render-level" id="${id}"` +
+        ` value="${escapeHtml(l.value)}"${override === l.value ? ' checked' : ''}>` +
+        '<span class="prow__main">' +
+        `<span class="prow__label">${escapeHtml(l.label)}</span>` +
+        `<span class="prow__desc">${escapeHtml(l.blurb)}</span>` +
+        '</span></label>'
+      );
+    }).join('');
+
+    wrap.innerHTML =
+      '<fieldset class="pgroup" id="render-level-group">' +
+      '<legend class="prow__label">Session card richness</legend>' +
+      '<p class="prow__desc">How much the claim and ship cards show. Richer cards explain more and cost more tokens; the confirmation line is always there whichever you pick.</p>' +
+      defaultRow + rows +
+      '</fieldset>';
+  }
+
+  async function save(value, input) {
+    const status = $('#render-status');
+    if (status) status.textContent = 'Saving…';
+    if (input) input.disabled = true;
+    try {
+      // The sentinel becomes an explicit null — the route's clear-the-override
+      // signal. Anything else is a level and is stored as the override.
+      const body = { widgets: value === USE_DEFAULT ? null : value };
+      const res = await api.request('PATCH', `${API}/me/render`, { body });
+      if (res.status === 401) { toAuth(); return; }
+      if (!res.ok) throw new Error(`render PATCH → ${res.status}`);
+      render(res.data);
+      const msg = value === USE_DEFAULT
+        ? `Saved — following your interaction profile (${labelForLevel(res.data, res.data.derived_level)}).`
+        : `Saved — ${labelForLevel(res.data, value)}.`;
+      if (status) status.textContent = msg;
+      toast(msg);
+    } catch (err) {
+      console.error('[settings] save render failed', err);
+      if (status) status.textContent = 'Could not save. Try again.';
+      toast('Could not save your rendering preference. Try again.');
+      if (input) input.disabled = false;
+    }
+  }
+
+  async function setup() {
+    try {
+      const res = await api.request('GET', `${API}/me/render`);
+      if (res.status === 401) { toAuth(); return; }
+      if (!res.ok) throw new Error(`render GET → ${res.status}`);
+      render(res.data);
+      $('#render-scroll').hidden = false;
+      // Delegate the change so post-render radios stay wired.
+      $('#render-rows').addEventListener('change', (e) => {
+        const r = e.target.closest('.pradio');
+        if (!r || r.disabled || !r.checked) return;
+        save(r.value, r);
+      });
+    } catch (err) {
+      // Its own try/catch, like every other section: a failing endpoint shows
+      // this panel's own error rather than taking the settings page down.
+      console.error('[settings] failed to load render', err);
+      $('#render-scroll').hidden = false;
+      $('#render-rows').innerHTML =
+        '<p class="voices-empty">Your rendering preference could not be loaded. Reload the page to try again.</p>';
+    }
+  }
+
+  setup();
+})();