@bongos/core 1.17.0

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

@@ -0,0 +1,1219 @@
+// public-builders/settings.js — the personal Settings page (/builders/settings).
+//
+// Open to ANY authenticated builder (no rank gate — a builder owns their own
+// preferences; the server enforces the same posture on /me/skill-prefs and
+// /me/disciplines). Two sections:
+//
+//   1. VOICES  — per-skill model picker (GET/PATCH /api/bongos/me/skill-prefs).
+//   2. CRAFT   — preferred disciplines (GET /api/bongos/me, PATCH /api/bongos/me/disciplines).
+//   3. DEV BOX — full box management via the shared OTBBoxPanel (#807, ADR 0040):
+//                request/open the online terminal, SSH details, and close.
+//   5. SOUNDS  — per-sound on/off toggles (GET/PATCH /api/bongos/me/sound-prefs, #786).
+//
+// On a 401 it redirects into the web sign-in flow, like the other hall pages.
+// Each section loads behind its own try/catch so one failing endpoint doesn't
+// take the whole page down.
+
+(() => {
+  'use strict';
+
+  const API = '/api/bongos';
+  // Generated typed client (task 1996 / R09), served as window.BongosClient by
+  // /lib/bongos-client.js. baseUrl:'' passes the full same-origin paths this file
+  // builds through unchanged; result-mode ({ status, ok, data }) preserves control flow 1:1.
+  const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
+
+  // escapeHtml / $ / toast now come from the shared window.OTB toolkit
+  // (dom-utils.js, loaded first). The toast wrapper keeps this page's variant
+  // (the 3200ms non-clearing toast).
+  const { escapeHtml, $ } = window.OTB;
+  const toast = (msg) => window.OTB.toast(msg);
+  const brandWorld = () => (window.__BRANDING__ && window.__BRANDING__.identity && window.__BRANDING__.identity.worldName) || 'the project';
+
+  function toAuth() {
+    window.location.assign(`${API}/auth/web/start`);
+  }
+
+  // ---- model labels (match the hall's wording in builders.js) --------------
+
+  const MODEL_LABELS = {
+    opus: 'Opus',
+    sonnet: 'Sonnet',
+    haiku: 'Haiku',
+    script: 'no LLM',
+  };
+  const modelLabel = (m) => MODEL_LABELS[m] || m || '—';
+
+  // ---- section 1: VOICES (per-skill model picker) --------------------------
+
+  // Render one row per skill in `effective`. Each row: skill name, the system
+  // default (muted), and a <select> whose value is the builder's override (or
+  // "" for "fall back to default"). The allowed model set is echoed back by the
+  // endpoint so we don't mirror it from a second source.
+  function renderVoices(data) {
+    const body = $('#voices-body');
+    if (!body) return;
+    const rows = Array.isArray(data?.effective) ? data.effective : [];
+    const allowed = Array.isArray(data?.allowed_models)
+      ? data.allowed_models
+      : ['opus', 'sonnet', 'haiku', 'script'];
+    if (rows.length === 0) {
+      body.innerHTML = '<tr><td colspan="3" class="voices-empty">No skills registered.</td></tr>';
+      return;
+    }
+    body.innerHTML = rows.map((row) => {
+      const opts = [`<option value="">Default (${escapeHtml(modelLabel(row.default_model))})</option>`]
+        .concat(allowed.map((m) => {
+          const sel = row.override_model === m ? ' selected' : '';
+          return `<option value="${escapeHtml(m)}"${sel}>${escapeHtml(modelLabel(m))}</option>`;
+        }))
+        .join('');
+      return (
+        `<tr data-skill="${escapeHtml(row.skill)}">` +
+        `<td class="voices__skill"><code>${escapeHtml(row.skill)}</code></td>` +
+        `<td><span class="voices__default" title="System default for this skill">${escapeHtml(modelLabel(row.default_model))}</span></td>` +
+        '<td>' +
+        `<select class="voices__select" data-skill="${escapeHtml(row.skill)}" aria-label="Voice for ${escapeHtml(row.skill)}">${opts}</select>` +
+        '</td>' +
+        '</tr>'
+      );
+    }).join('');
+  }
+
+  // PATCH a single skill's override. Body shape (see me.js + skill-prefs.js):
+  //   { "<skill-name>": "<model>" | null }
+  // where null clears the override (fall back to the system default).
+  async function saveVoice(skill, modelOrNull) {
+    const status = $('#voices-status');
+    if (status) status.textContent = 'Saving…';
+    try {
+      const body = { [skill]: modelOrNull };
+      const res = await api.request('PATCH', `${API}/me/skill-prefs`, { body });
+      if (res.status === 401) { toAuth(); return; }
+      if (!res.ok) throw new Error(`skill-prefs PATCH → ${res.status}`);
+      const data = res.data;
+      renderVoices(data);
+      const msg = modelOrNull
+        ? `${skill} → ${modelLabel(modelOrNull)}.`
+        : `Cleared ${skill} — falls back to default.`;
+      if (status) status.textContent = msg;
+      toast(msg);
+    } catch (err) {
+      console.error('[settings] save voice failed', err);
+      if (status) status.textContent = 'Could not save. Try again.';
+      toast('Could not save your choice. Try again.');
+    }
+  }
+
+  async function loadVoices() {
+    try {
+      const res = await api.request('GET', `${API}/me/skill-prefs`);
+      if (res.status === 401) { toAuth(); return; }
+      if (!res.ok) throw new Error(`skill-prefs GET → ${res.status}`);
+      const data = res.data;
+      renderVoices(data);
+      $('#voices-scroll').hidden = false;
+      // Delegate change events so post-render selects stay wired.
+      const table = $('#voices-table');
+      table.addEventListener('change', (e) => {
+        const sel = e.target.closest('.voices__select');
+        if (!sel) return;
+        const skill = sel.dataset.skill;
+        const next = sel.value === '' ? null : sel.value;
+        saveVoice(skill, next);
+      });
+    } catch (err) {
+      console.error('[settings] failed to load voices', err);
+      $('#voices-scroll').hidden = false;
+      $('#voices-body').innerHTML =
+        '<tr><td colspan="3" class="voices-empty">The skill list could not be loaded. Reload the page to try again.</td></tr>';
+    }
+  }
+
+  // ---- section 5: SOUNDS (per-sound on/off toggles, #786) ------------------
+
+  // Render one row per sound from `effective`. Each row: label + description and
+  // an On/Off toggle button whose data-on reflects the effective enabled-state.
+  function renderSounds(data) {
+    const wrap = $('#sound-rows');
+    if (!wrap) return;
+    const rows = Array.isArray(data?.effective) ? data.effective : [];
+    if (rows.length === 0) {
+      wrap.innerHTML = '<p class="voices-empty">No sounds registered.</p>';
+      return;
+    }
+    wrap.innerHTML = rows.map((row) => {
+      const on = row.enabled !== false;
+      return (
+        `<div class="sound-row" data-sound="${escapeHtml(row.sound)}">` +
+        '<div class="sound-row__text">' +
+        `<div class="sound-row__label">${escapeHtml(row.label || row.sound)}</div>` +
+        `<div class="sound-row__desc">${escapeHtml(row.desc || '')}</div>` +
+        '</div>' +
+        `<button type="button" class="sound-toggle" data-sound="${escapeHtml(row.sound)}" ` +
+        `data-on="${on ? '1' : '0'}" aria-pressed="${on ? 'true' : 'false'}">` +
+        `${on ? 'On' : 'Off'}</button>` +
+        '</div>'
+      );
+    }).join('');
+  }
+
+  // Live chime preview while dragging the volume slider (#792). Uses the HTML5
+  // Audio element's native .volume (linear gain, matching the local player's
+  // WAV scaling). PLAY-WHEN-IDLE so a continuous drag repeats the chime without
+  // overlapping copies (which would pile into noise); the in-flight chime's
+  // volume is updated live so the level you hear tracks the slider immediately.
+  // Silent at 0. Best-effort: any audio error is swallowed.
+  let chimeAudio = null;
+  let chimePlaying = false;
+  function previewChime(volPct) {
+    try {
+      if (!chimeAudio) {
+        chimeAudio = new Audio('/builders/chime.wav');
+        chimeAudio.addEventListener('ended', () => { chimePlaying = false; });
+        chimeAudio.addEventListener('error', () => { chimePlaying = false; });
+      }
+      const gain = Math.max(0, Math.min(1, volPct / 100));
+      chimeAudio.volume = gain;       // live — affects an in-flight chime too
+      if (gain <= 0) return;          // muted — don't start a new one
+      if (chimePlaying) return;       // let the current one finish (no overlap)
+      chimePlaying = true;
+      chimeAudio.currentTime = 0;
+      const p = chimeAudio.play();
+      if (p && typeof p.catch === 'function') p.catch(() => { chimePlaying = false; });
+    } catch (_) { /* best-effort preview */ }
+  }
+
+  // Reflect the master volume (#788) into the slider + percentage label.
+  function renderVolume(data) {
+    const wrap = $('#sound-volume');
+    const range = $('#sound-volume-range');
+    const pct = $('#sound-volume-pct');
+    if (!wrap || !range || !pct) return;
+    const v = (typeof data?.volume === 'number') ? data.volume : 100;
+    range.value = String(v);
+    pct.textContent = `${v}%`;
+    wrap.hidden = false;
+  }
+
+  // PATCH the master volume. Body shape: { volume: <0-100> } (see me.js +
+  // sound-prefs.js). Saved on the slider's `change` event (release), not on every
+  // `input` tick — the pct label updates live on input, the PATCH fires once.
+  // Feedback for volume goes to the toast popup ONLY — no in-card status line
+  // (it duplicated the percentage at the bottom of the card; #794).
+  async function saveVolume(value) {
+    try {
+      const res = await api.request('PATCH', `${API}/me/sound-prefs`, { body: { volume: value } });
+      if (res.status === 401) { toAuth(); return; }
+      if (!res.ok) throw new Error(`sound-prefs PATCH → ${res.status}`);
+      const data = res.data;
+      renderVolume(data);
+      toast(`Volume ${value}%.`);
+    } catch (err) {
+      console.error('[settings] save volume failed', err);
+      toast('Could not save the volume. Try again.');
+    }
+  }
+
+  // PATCH a single sound's enabled-state. Body shape (see me.js + sound-prefs.js):
+  //   { "<sound>": <bool> }  — we always send an explicit boolean (not the null
+  //   clear sentinel), so the toggle is a plain on/off.
+  // Feedback goes to the toast popup ONLY — no in-card status line (it duplicated
+  // the toast at the bottom of the card; #798, matching the volume cleanup #794).
+  async function saveSound(sound, enabled, btn) {
+    if (btn) btn.disabled = true;
+    try {
+      const res = await api.request('PATCH', `${API}/me/sound-prefs`, { body: { [sound]: enabled } });
+      if (res.status === 401) { toAuth(); return; }
+      if (!res.ok) throw new Error(`sound-prefs PATCH → ${res.status}`);
+      const data = res.data;
+      renderSounds(data);
+      toast(enabled ? `${sound} — on.` : `${sound} — off.`);
+    } catch (err) {
+      console.error('[settings] save sound failed', err);
+      toast('Could not save your sound preference. Try again.');
+      if (btn) btn.disabled = false;
+    }
+  }
+
+  async function loadSounds() {
+    try {
+      const res = await api.request('GET', `${API}/me/sound-prefs`);
+      if (res.status === 401) { toAuth(); return; }
+      if (!res.ok) throw new Error(`sound-prefs GET → ${res.status}`);
+      const data = res.data;
+      renderSounds(data);
+      renderVolume(data);
+      $('#sounds-scroll').hidden = false;
+      // Delegate clicks so post-render toggles stay wired.
+      const wrap = $('#sound-rows');
+      wrap.addEventListener('click', (e) => {
+        const btn = e.target.closest('.sound-toggle');
+        if (!btn) return;
+        const sound = btn.dataset.sound;
+        const next = btn.dataset.on !== '1'; // flip current state
+        saveSound(sound, next, btn);
+      });
+      // Volume slider: live % label on input (drag), persist once on change (release).
+      const range = $('#sound-volume-range');
+      const pct = $('#sound-volume-pct');
+      if (range) {
+        range.addEventListener('input', () => {
+          if (pct) pct.textContent = `${range.value}%`;
+          previewChime(Number(range.value)); // hear the level as you drag (#792)
+        });
+        range.addEventListener('change', () => { saveVolume(Number(range.value)); });
+      }
+    } catch (err) {
+      console.error('[settings] failed to load sounds', err);
+      $('#sounds-scroll').hidden = false;
+      $('#sound-rows').innerHTML =
+        '<p class="voices-empty">The sounds could not be loaded. Reload the page to try again.</p>';
+    }
+  }
+
+  // ---- section 5b: EVENT SOUNDS (per-event variant picker, task 582) ---------
+  //
+  // GET/PATCH /api/bongos/me/event-sound-prefs. The payload carries each of the 5
+  // build events with their available world-themed variants and the builder's
+  // current selection. A <select> dropdown per event + a preview button that
+  // plays the current variant inline via Web Audio.
+
+  function renderEventSounds(data) {
+    const wrap = $('#event-sound-rows');
+    if (!wrap) return;
+    const rows = Array.isArray(data?.effective) ? data.effective : [];
+    if (rows.length === 0) {
+      wrap.innerHTML = '<p class="voices-empty">No event sounds registered.</p>';
+      return;
+    }
+    wrap.innerHTML = rows.map((row) => {
+      const opts = row.variants.map((v) =>
+        `<option value="${escapeHtml(v.id)}" data-wav="${escapeHtml(v.wav)}"` +
+        `${row.selected === v.id ? ' selected' : ''}>` +
+        `${escapeHtml(v.label)}${v.is_default ? ' (default)' : ''}</option>`
+      ).join('');
+      return (
+        `<div class="event-sound-row" data-event="${escapeHtml(row.event)}">` +
+        '<div class="event-sound-row__text">' +
+        `<div class="event-sound-row__label">${escapeHtml(row.label || row.event)}</div>` +
+        `<div class="event-sound-row__desc">${escapeHtml(row.desc || '')}</div>` +
+        '</div>' +
+        '<div class="event-sound-row__controls">' +
+        `<select class="event-sound-select" data-event="${escapeHtml(row.event)}" ` +
+        `data-wav="${escapeHtml(row.wav)}" aria-label="Sound for ${escapeHtml(row.label)}">${opts}</select>` +
+        `<button type="button" class="event-sound-preview" data-wav="${escapeHtml(row.wav)}" ` +
+        `aria-label="Preview ${escapeHtml(row.label)} sound">Play</button>` +
+        '</div>' +
+        '</div>'
+      );
+    }).join('');
+  }
+
+  async function saveEventSound(eventId, variantId, sel) {
+    if (sel) sel.disabled = true;
+    try {
+      const res = await api.request('PATCH', `${API}/me/event-sound-prefs`, { body: { [eventId]: variantId } });
+      if (res.status === 401) { toAuth(); return; }
+      if (!res.ok) throw new Error(`event-sound-prefs PATCH → ${res.status}`);
+      const data = res.data;
+      renderEventSounds(data);
+      toast('Sound preference saved.');
+    } catch (err) {
+      console.error('[settings] save event sound failed', err);
+      toast('Could not save your sound preference. Try again.');
+      if (sel) sel.disabled = false;
+    }
+  }
+
+  function previewEventSound(wavName) {
+    try {
+      const audio = new Audio(`/builders/${wavName}.wav`);
+      audio.volume = (() => {
+        try {
+          const range = $('#sound-volume-range');
+          return range ? Math.max(0, Math.min(1, Number(range.value) / 100)) : 1;
+        } catch (_) { return 1; }
+      })();
+      const p = audio.play();
+      if (p && typeof p.catch === 'function') p.catch(() => {});
+    } catch (_) { /* best-effort preview */ }
+  }
+
+  async function loadEventSounds() {
+    try {
+      const res = await api.request('GET', `${API}/me/event-sound-prefs`);
+      if (res.status === 401) { toAuth(); return; }
+      if (!res.ok) throw new Error(`event-sound-prefs GET → ${res.status}`);
+      const data = res.data;
+      renderEventSounds(data);
+      $('#event-sounds-scroll').hidden = false;
+
+      const wrap = $('#event-sound-rows');
+      // Delegate select changes → save new variant.
+      wrap.addEventListener('change', (e) => {
+        const sel = e.target.closest('.event-sound-select');
+        if (!sel) return;
+        const eventId = sel.dataset.event;
+        saveEventSound(eventId, sel.value, sel);
+      });
+      // Update preview button's data-wav live when the select changes so the
+      // Play button always previews the currently selected option.
+      wrap.addEventListener('input', (e) => {
+        const sel = e.target.closest('.event-sound-select');
+        if (!sel) return;
+        const row = sel.closest('.event-sound-row');
+        if (!row) return;
+        const opt = sel.options[sel.selectedIndex];
+        const wav = opt && opt.dataset.wav;
+        if (!wav) return;
+        const previewBtn = row.querySelector('.event-sound-preview');
+        if (previewBtn) previewBtn.dataset.wav = wav;
+      });
+      // Delegate preview button clicks.
+      wrap.addEventListener('click', (e) => {
+        const btn = e.target.closest('.event-sound-preview');
+        if (!btn) return;
+        // btn.dataset.wav is the wav name from the last render (or updated on input).
+        // After a change event saves and re-renders, it's the server-confirmed wav.
+        // Before a save, it's the variant id (which is also a valid wav fallback).
+        previewEventSound(btn.dataset.wav);
+      });
+    } catch (err) {
+      console.error('[settings] failed to load event sounds', err);
+      $('#event-sounds-scroll').hidden = false;
+      $('#event-sound-rows').innerHTML =
+        '<p class="voices-empty">The event sounds could not be loaded. Reload the page to try again.</p>';
+    }
+  }
+
+  // ---- section 2b: WANDERING (off-task thread suppression, task 1268) -------
+  //
+  // GET/PATCH /api/bongos/me/wandering. The payload (wandering-prefs.describeForApi)
+  // carries the level catalog with per-rank `allowed`, the effective level, the
+  // rank default, and the ceiling. Single-select: clicking an allowed level
+  // PATCHes { wandering: n }. Levels above the rank cap render disabled — the
+  // server enforces the same clamp, this is just the friendly UI half. Reuses
+  // the .sound-row / .sound-toggle styling.
+  function renderWandering(data) {
+    const wrap = $('#wander-rows');
+    if (!wrap) return;
+    const levels = Array.isArray(data?.levels) ? data.levels : [];
+    const eff = typeof data?.effective_level === 'number' ? data.effective_level : null;
+    const def = typeof data?.default_level === 'number' ? data.default_level : null;
+    if (levels.length === 0) {
+      wrap.innerHTML = '<p class="voices-empty">No levels registered.</p>';
+      return;
+    }
+    wrap.innerHTML = levels.map((lv) => {
+      const chosen = lv.n === eff;
+      const tag = lv.n === def ? ' <span class="voices__default">· default for your rank</span>' : '';
+      let btn;
+      if (!lv.allowed) {
+        btn = `<button type="button" class="sound-toggle" disabled data-level="${lv.n}" data-on="0">Rank-locked</button>`;
+      } else if (chosen) {
+        btn = `<button type="button" class="sound-toggle" data-level="${lv.n}" data-on="1" aria-pressed="true">Chosen</button>`;
+      } else {
+        btn = `<button type="button" class="sound-toggle" data-level="${lv.n}" data-on="0" aria-pressed="false">Choose</button>`;
+      }
+      return (
+        `<div class="sound-row" data-level="${lv.n}">` +
+        '<div class="sound-row__text">' +
+        `<div class="sound-row__label">${escapeHtml(lv.label)}${tag}</div>` +
+        `<div class="sound-row__desc">${escapeHtml(lv.blurb || '')}</div>` +
+        '</div>' +
+        btn +
+        '</div>'
+      );
+    }).join('');
+    const note = $('#wandering-note');
+    if (note) {
+      note.textContent = (data && data.effective_label && data.max_key)
+        ? `Now: ${data.effective_label}. Your rank allows up to ${data.max_key}.`
+        : '';
+    }
+  }
+
+  // PATCH the wandering level. Body: { wandering: <0..3> } (see me.js +
+  // wandering-prefs.js). A level above the rank ceiling is rejected server-side
+  // (422) — but those buttons render disabled, so it shouldn't be reachable.
+  async function saveWandering(level, btn) {
+    const status = $('#wandering-status');
+    if (status) status.textContent = 'Saving…';
+    if (btn) btn.disabled = true;
+    try {
+      const res = await api.request('PATCH', `${API}/me/wandering`, { body: { wandering: level } });
+      if (res.status === 401) { toAuth(); return; }
+      if (!res.ok) throw new Error(`wandering PATCH → ${res.status}`);
+      const data = res.data;
+      renderWandering(data);
+      const msg = `Wandering → ${data.effective_label || level}.`;
+      if (status) status.textContent = msg;
+      toast(msg);
+    } catch (err) {
+      console.error('[settings] save wandering failed', err);
+      if (status) status.textContent = 'Could not save. Try again.';
+      toast('Could not save your wandering level. Try again.');
+      if (btn) btn.disabled = false;
+    }
+  }
+
+  async function loadWandering() {
+    try {
+      const res = await api.request('GET', `${API}/me/wandering`);
+      if (res.status === 401) { toAuth(); return; }
+      if (!res.ok) throw new Error(`wandering GET → ${res.status}`);
+      const data = res.data;
+      renderWandering(data);
+      $('#wandering-scroll').hidden = false;
+      // Delegate clicks so post-render buttons stay wired (single-select).
+      const wrap = $('#wander-rows');
+      wrap.addEventListener('click', (e) => {
+        const b = e.target.closest('.sound-toggle');
+        if (!b || b.disabled || b.dataset.on === '1') return; // ignore locked + already-chosen
+        const level = Number(b.dataset.level);
+        if (Number.isInteger(level)) saveWandering(level, b);
+      });
+    } catch (err) {
+      console.error('[settings] failed to load wandering', err);
+      $('#wandering-scroll').hidden = false;
+      $('#wander-rows').innerHTML =
+        '<p class="voices-empty">Your wandering level could not be loaded. Reload the page to try again.</p>';
+    }
+  }
+
+  // ---- section 2c: RENDERING (rich in-feed cards on/off, task 1279) ---------
+  //
+  // GET/PATCH /api/bongos/me/render. A single boolean (widgets_enabled). The session
+  // cards render as an HTML widget Claude must relay verbatim every time, which
+  // costs tokens; off uses the cheap text form. No rank gate (cost/taste). Reuses
+  // the .sound-row / .sound-toggle styling — one row, one on/off toggle.
+  function renderRender(data) {
+    const wrap = $('#render-rows');
+    if (!wrap) return;
+    const on = data ? data.widgets_enabled !== false : true;
+    const isDefault = !data || data.override == null;
+    wrap.innerHTML =
+      '<div class="sound-row" data-render="widgets">' +
+      '<div class="sound-row__text">' +
+      '<div class="sound-row__label">Rich in-feed cards' +
+      (isDefault ? ' <span class="voices__default">· default (on)</span>' : '') +
+      '</div>' +
+      '<div class="sound-row__desc">Render session cards as widgets (prettier, costs tokens) instead of plain text (cheaper, identical info).</div>' +
+      '</div>' +
+      `<button type="button" class="sound-toggle" data-on="${on ? '1' : '0'}" aria-pressed="${on ? 'true' : 'false'}">${on ? 'On' : 'Off'}</button>` +
+      '</div>';
+  }
+
+  // PATCH the render knob. Body: { widgets: <bool> } (see me.js + render-prefs.js).
+  async function saveRender(enabled, btn) {
+    const status = $('#render-status');
+    if (status) status.textContent = 'Saving…';
+    if (btn) btn.disabled = true;
+    try {
+      const res = await api.request('PATCH', `${API}/me/render`, { body: { widgets: enabled } });
+      if (res.status === 401) { toAuth(); return; }
+      if (!res.ok) throw new Error(`render PATCH → ${res.status}`);
+      const data = res.data;
+      renderRender(data);
+      const msg = enabled ? 'Rich in-feed cards — on.' : 'Rich in-feed cards — off (plain text).';
+      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 (btn) btn.disabled = false;
+    }
+  }
+
+  async function loadRender() {
+    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}`);
+      const data = res.data;
+      renderRender(data);
+      $('#render-scroll').hidden = false;
+      // Delegate clicks so the post-render button stays wired (single toggle).
+      const wrap = $('#render-rows');
+      wrap.addEventListener('click', (e) => {
+        const b = e.target.closest('.sound-toggle');
+        if (!b || b.disabled) return;
+        saveRender(b.dataset.on !== '1', b); // flip current state
+      });
+    } catch (err) {
+      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>';
+    }
+  }
+
+  // ---- section 2: CRAFT (discipline preferences) ---------------------------
+
+  // Valid disciplines are limited (see me.js + db.updateBuilderDisciplines):
+  // engineer | ideator (core) + artist when the art-pipeline module is on
+  // (R59 / task 1198). moduleOn defaults true if the flag is missing, so OTB
+  // (art on) keeps all three; a vanilla instance offers only the two it accepts.
+  const DISCIPLINES = ['engineer', 'artist', 'ideator']
+    .filter((d) => (d === 'artist' ? window.OTB.moduleOn('art-pipeline') : true));
+
+  // Current selection mutated in place as the builder toggles chips; saved on
+  // the "Save" button (the hall's profile card behaviour) via PATCH.
+  const craft = { selected: new Set() };
+
+  function renderCraft() {
+    const wrap = $('#craft-chips');
+    if (!wrap) return;
+    wrap.innerHTML = DISCIPLINES.map((d) => {
+      const on = craft.selected.has(d);
+      return (
+        `<label class="craft-chip" data-disc="${escapeHtml(d)}" data-on="${on ? '1' : '0'}">` +
+        `<input type="checkbox" class="craft-pref" value="${escapeHtml(d)}"${on ? ' checked' : ''}>` +
+        `${escapeHtml(d)}</label>`
+      );
+    }).join('');
+  }
+
+  async function saveCraft() {
+    const selected = DISCIPLINES.filter((d) => craft.selected.has(d));
+    const btn = $('#craft-save');
+    const status = $('#craft-status');
+    if (btn) { btn.disabled = true; btn.textContent = 'Saving…'; }
+    if (status) status.textContent = '';
+    try {
+      const res = await api.request('PATCH', `${API}/me/disciplines`, { body: { preferred_disciplines: selected } });
+      if (res.status === 401) { toAuth(); return; }
+      if (!res.ok) throw new Error(`disciplines PATCH → ${res.status}`);
+      const data = res.data;
+      // Re-seed local state from the server's echo so it stays authoritative.
+      const prefs = Array.isArray(data?.builder?.preferred_disciplines)
+        ? data.builder.preferred_disciplines
+        : selected;
+      craft.selected = new Set(prefs.filter((d) => DISCIPLINES.includes(d)));
+      renderCraft();
+      const msg = selected.length ? `Preferred work: ${selected.join(', ')}.` : 'Preference cleared.';
+      if (status) status.textContent = msg;
+      toast(msg);
+    } catch (err) {
+      console.error('[settings] save craft failed', err);
+      if (status) status.textContent = 'Could not save. Try again.';
+      toast('Could not save your preference. Try again.');
+    } finally {
+      if (btn) { btn.disabled = false; btn.textContent = 'Save'; }
+    }
+  }
+
+  function wireCraft() {
+    const wrap = $('#craft-chips');
+    if (wrap) {
+      wrap.addEventListener('change', (e) => {
+        const box = e.target.closest('.craft-pref');
+        if (!box) return;
+        if (box.checked) craft.selected.add(box.value);
+        else craft.selected.delete(box.value);
+        const chip = box.closest('.craft-chip');
+        if (chip) chip.dataset.on = box.checked ? '1' : '0';
+      });
+    }
+    const btn = $('#craft-save');
+    if (btn) btn.addEventListener('click', saveCraft);
+  }
+
+  // ---- section 2a: DISPLAY NAME (the label beside your work, task 1669) -----
+  //
+  // GET/PATCH /api/bongos/me/display-name. A single editable field, pre-filled from
+  // the /me payload (so the page already has it without a second fetch). Save
+  // PATCHes { display_name }; the server trims + validates (empty, control chars,
+  // length) and echoes the saved value back, which we re-seed into the field.
+  // Identity stays github_login/id — this only renames the rendered label.
+
+  // The longest name we let a builder type — mirrors display-name.js MAX_LENGTH
+  // (the input's maxlength attr already caps it; the server is the real gate).
+  const DISPLAY_NAME_MAX = 60;
+
+  function renderDisplayName(value) {
+    const input = $('#display-name-input');
+    if (input) input.value = value || '';
+  }
+
+  async function saveDisplayName() {
+    const input = $('#display-name-input');
+    const btn = $('#display-name-save');
+    const status = $('#display-name-status');
+    if (!input) return;
+    const next = input.value.trim();
+    if (status) status.textContent = '';
+    // Friendly client-side pre-check; the server is the authority.
+    if (!next) {
+      if (status) status.textContent = 'Name cannot be blank.';
+      toast('Your name cannot be blank.');
+      return;
+    }
+    if (Array.from(next).length > DISPLAY_NAME_MAX) {
+      if (status) status.textContent = `Name must be ${DISPLAY_NAME_MAX} characters or fewer.`;
+      toast(`Your name must be ${DISPLAY_NAME_MAX} characters or fewer.`);
+      return;
+    }
+    if (btn) { btn.disabled = true; btn.textContent = 'Saving…'; }
+    try {
+      const res = await api.request('PATCH', `${API}/me/display-name`, { body: { display_name: next } });
+      if (res.status === 401) { toAuth(); return; }
+      const data = (res.data || {});
+      if (res.status === 422) {
+        const first = Array.isArray(data.errors) && data.errors[0];
+        const msg = (first && first.message) || 'That name is not allowed.';
+        if (status) status.textContent = msg;
+        toast(msg);
+        return;
+      }
+      if (!res.ok) throw new Error(`display-name PATCH → ${res.status}`);
+      renderDisplayName(data.display_name);
+      // Reflect the new name in the page sub-header too, for instant feedback.
+      const sub = $('#settings-sub');
+      if (sub && data.display_name) sub.textContent = `Your preferences, ${data.display_name}.`;
+      const msg = `Saved — you're now “${data.display_name}”.`;
+      if (status) status.textContent = msg;
+      toast(msg);
+    } catch (err) {
+      console.error('[settings] save display name failed', err);
+      if (status) status.textContent = 'Could not save. Try again.';
+      toast('Could not save your name. Try again.');
+    } finally {
+      if (btn) { btn.disabled = false; btn.textContent = 'Save'; }
+    }
+  }
+
+  // Seed the field from the /me payload (the page already has the builder row),
+  // wire Save + Enter, then reveal the section. No separate GET needed for the
+  // initial value; the dedicated GET /me/display-name endpoint stays available
+  // for callers that want a fresh read.
+  function setupDisplayName(builder) {
+    renderDisplayName(builder && builder.display_name);
+    const btn = $('#display-name-save');
+    if (btn) btn.addEventListener('click', saveDisplayName);
+    const input = $('#display-name-input');
+    if (input) input.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter') { e.preventDefault(); saveDisplayName(); }
+    });
+    $('#display-name-scroll').hidden = false;
+  }
+
+  // ---- section 1b: DEV BOX (full management, #807 ADR 0040) ----------------
+  //
+  // Mounts the shared OTBBoxPanel (box-panel.js) with showSsh:true so a builder
+  // sees BOTH the online terminal and the SSH IP + command, and can request,
+  // open, or close their box. The module owns its own polling + state painting;
+  // we just hand it the mount element. Hidden if the module failed to load.
+  function setupBox() {
+    // R60 (task 1199): dev boxes are a feature module. On a vanilla instance the
+    // module is off — there is no box to manage, so the whole section stays
+    // hidden (its #box-scroll defaults to hidden in the markup).
+    if (!window.OTB.moduleOn('dev-box')) return;
+    const mount = $('#box-mount');
+    if (!mount || !window.OTBBoxPanel) return;
+    const panel = window.OTBBoxPanel.create({ api: API, showSsh: true, toast });
+    $('#box-scroll').hidden = false;
+    panel.mount(mount);
+  }
+
+  // ---- section 3: CONNECTIONS (Discord link/unlink, F7 ADR 0033) -----------
+  //
+  // The /me payload carries `discord: { configured, linked }`. The section is
+  // hidden entirely when the server has no Discord OAuth creds (configured=false)
+  // — there's nothing to connect to. Linking is a plain <a> into the server's
+  // OAuth start; the callback now returns to /settings (see routes/auth.js), and
+  // handleDiscordReturn() below surfaces the one-shot confirmation.
+
+  let discordState = null;
+
+  function renderDiscord() {
+    const card = $('#discord-card');
+    if (!card) return;
+    const d = discordState;
+    if (!d || !d.configured) { $('#connections-scroll').hidden = true; return; }
+    $('#connections-scroll').hidden = false;
+    if (d.linked) {
+      card.innerHTML =
+        '<span class="settings-card__ok">Discord connected ✓</span>' +
+        `<span class="settings-card__hint">You're in the ${brandWorld()} server with your rank role.</span>` +
+        '<button type="button" class="settings-btn" id="discord-unlink-btn">Unlink</button>';
+      const btn = $('#discord-unlink-btn');
+      if (btn) btn.addEventListener('click', unlinkDiscord);
+    } else {
+      card.innerHTML =
+        `<a class="settings-btn settings-btn--discord" href="${API}/auth/discord/start">Connect Discord &amp; join the server</a>` +
+        '<span class="settings-card__hint">Link first — your rank role is set the moment you join.</span>';
+    }
+  }
+
+  async function unlinkDiscord() {
+    const btn = $('#discord-unlink-btn');
+    if (btn) { btn.disabled = true; btn.textContent = 'Unlinking…'; }
+    try {
+      const res = await api.request('POST', `${API}/auth/discord/unlink`);
+      if (res.status === 401) { toAuth(); return; }
+      if (!res.ok) throw new Error(`discord unlink → ${res.status}`);
+      toast('Discord unlinked.');
+      if (discordState) discordState.linked = false;
+      renderDiscord();
+    } catch (err) {
+      console.error('[settings] discord unlink failed', err);
+      toast(`Unlink failed: ${err.message}`);
+      if (btn) { btn.disabled = false; btn.textContent = 'Unlink'; }
+    }
+  }
+
+  function setupConnections(discord) {
+    discordState = discord || null;
+    renderDiscord();
+  }
+
+  // One-shot toast when the Discord OAuth callback returns here with
+  // ?discord=joined|linked, then strip the param so a refresh doesn't re-toast.
+  function handleDiscordReturn() {
+    try {
+      const dq = new URLSearchParams(location.search).get('discord');
+      if (dq === 'joined' || dq === 'linked') {
+        toast(dq === 'joined'
+          ? "Discord connected — you're in the server with your rank role."
+          : "Discord connected. (You'll get your role when the server bot is live.)");
+        const url = new URL(location.href);
+        url.searchParams.delete('discord');
+        history.replaceState(null, '', url.pathname + url.search + url.hash);
+      }
+    } catch (_) { /* non-fatal */ }
+  }
+
+  // ---- section 4: CLI ACCESS (re-issue a CLI bearer, V3.R91 #401) ----------
+
+  async function issueCliToken() {
+    const btn = $('#cli-reissue-btn');
+    const result = $('#cli-reissue-result');
+    if (!btn) return;
+    btn.disabled = true;
+    const original = btn.textContent;
+    btn.textContent = 'Minting…';
+    try {
+      const res = await api.request('POST', `${API}/auth/cli-token/issue`);
+      if (res.status === 401) { toAuth(); return; }
+      const body = (res.data || {});
+      if (!res.ok) throw new Error(body.message || `HTTP ${res.status}`);
+      const expires = body.expires_at ? new Date(body.expires_at).toLocaleString() : 'unknown';
+      result.innerHTML =
+        '<p>Fresh CLI token issued. Paste it in your terminal:</p>' +
+        `<pre>${escapeHtml(body.paste_command || '')}</pre>` +
+        '<p><button type="button" class="settings-btn" id="cli-reissue-copy">Copy</button>' +
+        `<span class="settings-card__hint" style="margin-left:0.6rem;">Expires ${escapeHtml(expires)} · refreshes on use.</span></p>`;
+      result.hidden = false;
+      const copyBtn = $('#cli-reissue-copy');
+      if (copyBtn) copyBtn.addEventListener('click', async () => {
+        try { await navigator.clipboard.writeText(body.paste_command); toast('Paste command copied.'); }
+        catch (err) { toast(`Could not copy automatically — select and copy manually. (${err.message})`); }
+      });
+    } catch (err) {
+      console.error('[settings] cli token reissue failed', err);
+      toast(`Re-issue failed: ${err.message}`);
+    } finally {
+      btn.disabled = false;
+      btn.textContent = original;
+    }
+  }
+
+  function setupCliAccess() {
+    $('#cli-scroll').hidden = false;
+    const btn = $('#cli-reissue-btn');
+    if (btn) btn.addEventListener('click', issueCliToken);
+  }
+
+  // ---- section 2d: IMAGE KEY (per-builder Gemini key, task 1013 / ADR 0073) --
+  //
+  // GET/PUT/DELETE /api/bongos/me/art-key/own. Write-only: set / replace / remove,
+  // masked (last-4) read. The banner + tone come from the /me `needs` art_key
+  // item — covered for newcomers, action-needed once coverage ends, satisfied
+  // once a key is on file. The full key is never shown again after saving.
+  const AISTUDIO = 'https://aistudio.google.com/app/apikey';
+  const getOneLink = `<a href="${AISTUDIO}" target="_blank" rel="noopener">Get a free key ↗</a>`;
+
+  // Viewer's live rank (set in loadArtKey). Decides whether the "storage not yet
+  // configured" state shows an Archon "set it up" button (task 1398) or the
+  // wait-for-an-Archon message. The button POST is server-gated regardless — this
+  // only controls what we render. Divine tiers sit above archon and also pass.
+  let viewerRank = null;
+  const ARCHON_OR_ABOVE = new Set(['archon', 'olympian', 'hermes', 'oracle', 'demigod']);
+  function isArchonRank(r) { return ARCHON_OR_ABOVE.has(r); }
+
+  function artKeyNeedItem(me) {
+    const items = me && me.needs && Array.isArray(me.needs.items) ? me.needs.items : [];
+    return items.find((n) => n && n.id === 'art_key') || null;
+  }
+
+  // The "we cover it" / "action needed" banner above the card. Satisfied (or no
+  // need data) → hidden; the card itself shows the on-file state.
+  function renderArtKeyBanner(need) {
+    const el = $('#artkey-banner');
+    if (!el) return;
+    if (!need || need.state === 'satisfied') { el.hidden = true; return; }
+    el.hidden = false;
+    el.className = `artkey-banner artkey-banner--${need.state === 'action_needed' ? 'action' : 'covered'}`;
+    el.innerHTML = `<strong>${escapeHtml(need.title)}</strong> — ${escapeHtml(need.message)}`;
+  }
+
+  function artKeyEntryHtml() {
+    return (
+      '<div class="artkey-entry-row">' +
+      '<input type="password" class="artkey-input" id="artkey-input" autocomplete="off" ' +
+      'spellcheck="false" placeholder="Paste your Google AI Studio key">' +
+      '<button type="button" class="settings-btn" id="artkey-save">Save key</button>' +
+      '</div>' +
+      `<p class="settings-card__hint">${getOneLink} · Stored encrypted; never shown again after saving.</p>`
+    );
+  }
+
+  function renderArtKeyCard(meta) {
+    const card = $('#artkey-card');
+    if (!card) return;
+    if (meta && meta.storage_configured === false) {
+      // Storage isn't provisioned yet. An Archon can turn it on right here — the
+      // server generates + stores the master key, no terminal (task 1398). Everyone
+      // else waits for an Archon to do it.
+      if (isArchonRank(viewerRank)) {
+        card.innerHTML =
+          '<p class="settings-card__hint">Key storage isn\'t set up yet. As an Archon you can turn it on now — the server generates and safely stores the master key (no terminal needed).</p>' +
+          '<div class="artkey-actions"><button type="button" class="settings-btn" id="artkey-setup-storage">Set up key storage</button></div>' +
+          '<p class="settings-card__hint" id="artkey-status"></p>';
+      } else {
+        card.innerHTML = `<p class="settings-card__hint">Key storage is being set up by an Archon — check back shortly. ${getOneLink}</p>`;
+      }
+      return;
+    }
+    if (meta && meta.set) {
+      const added = meta.set_at ? new Date(meta.set_at).toLocaleDateString() : '';
+      card.innerHTML =
+        `<p class="settings-card__ok">Key on file ending …${escapeHtml(meta.last4 || '????')}${added ? ` · added ${escapeHtml(added)}` : ''}.</p>` +
+        '<div class="artkey-actions">' +
+        '<button type="button" class="settings-btn" id="artkey-replace">Replace</button>' +
+        '<button type="button" class="settings-btn settings-btn--quiet" id="artkey-remove">Remove</button>' +
+        '</div>' +
+        '<div id="artkey-entry" hidden></div>';
+      return;
+    }
+    card.innerHTML = artKeyEntryHtml();
+  }
+
+  // (Re)wire the card's controls after every render — re-rendering replaces the
+  // nodes, so handlers are attached fresh each time.
+  function wireArtKeyCard() {
+    const setup = $('#artkey-setup-storage');
+    if (setup) setup.onclick = () => setupKeyStorage(setup);
+    const save = $('#artkey-save');
+    if (save) save.onclick = () => { const i = $('#artkey-input'); saveArtKey(i ? i.value : '', save); };
+    const input = $('#artkey-input');
+    if (input) input.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter') { e.preventDefault(); saveArtKey(input.value, $('#artkey-save')); }
+    });
+    const replace = $('#artkey-replace');
+    if (replace) replace.onclick = () => {
+      const entry = $('#artkey-entry');
+      if (!entry) return;
+      entry.innerHTML = artKeyEntryHtml();
+      entry.hidden = false;
+      wireArtKeyCard();
+      const i = $('#artkey-input'); if (i) i.focus();
+    };
+    const remove = $('#artkey-remove');
+    if (remove) remove.onclick = removeArtKey;
+  }
+
+  async function saveArtKey(value, btn) {
+    const status = $('#artkey-status');
+    const key = (value || '').trim();
+    if (!key) { toast('Paste your key first.'); return; }
+    if (status) status.textContent = 'Checking your key…';
+    if (btn) btn.disabled = true;
+    try {
+      const res = await api.request('PUT', `${API}/me/art-key/own`, { body: { key } });
+      if (res.status === 401) { toAuth(); return; }
+      const body = (res.data || {});
+      if (!res.ok) {
+        const msg = body.message || `Could not save (HTTP ${res.status}).`;
+        if (status) status.textContent = msg;
+        toast(msg);
+        if (btn) btn.disabled = false;
+        return;
+      }
+      renderArtKeyCard({ set: true, last4: body.last4, set_at: body.set_at, storage_configured: true });
+      wireArtKeyCard();
+      renderArtKeyBanner({ state: 'satisfied' }); // the need is now satisfied
+      const msg = body.validated === false
+        ? 'Key saved — but we couldn\'t reach Google to verify it just now.'
+        : 'Key saved and verified.';
+      if (status) status.textContent = msg;
+      toast(msg);
+    } catch (err) {
+      console.error('[settings] save art key failed', err);
+      if (status) status.textContent = 'Could not save. Try again.';
+      toast('Could not save your key. Try again.');
+      if (btn) btn.disabled = false;
+    }
+  }
+
+  // Archon-only: turn on key storage (provision the server master key) without a
+  // terminal — task 1398. On success the card re-renders to the key-entry state so
+  // the Archon can add their own key immediately. The server enforces the rank.
+  async function setupKeyStorage(btn) {
+    const status = $('#artkey-status');
+    if (btn) btn.disabled = true;
+    if (status) status.textContent = 'Setting up key storage…';
+    try {
+      const res = await api.request('POST', `${API}/me/art-key/storage-init`);
+      if (res.status === 401) { toAuth(); return; }
+      const body = (res.data || {});
+      if (!res.ok) {
+        const msg = body.message || `Could not set up storage (HTTP ${res.status}).`;
+        if (status) status.textContent = msg;
+        toast(msg);
+        if (btn) btn.disabled = false;
+        return;
+      }
+      // Storage is on now — drop straight into the key-entry state.
+      renderArtKeyCard({ set: false, storage_configured: true });
+      wireArtKeyCard();
+      const msg = body.created
+        ? 'Key storage is set up — paste your key below.'
+        : 'Key storage was already set up — paste your key below.';
+      const s2 = $('#artkey-status');
+      if (s2) s2.textContent = msg;
+      toast(msg);
+      const i = $('#artkey-input'); if (i) i.focus();
+    } catch (err) {
+      console.error('[settings] set up key storage failed', err);
+      if (status) status.textContent = 'Could not set up storage. Try again.';
+      toast('Could not set up key storage. Try again.');
+      if (btn) btn.disabled = false;
+    }
+  }
+
+  async function removeArtKey() {
+    const status = $('#artkey-status');
+    if (!window.confirm('Remove your image-generation key? Art generation will stop until you add one again.')) return;
+    if (status) status.textContent = 'Removing…';
+    try {
+      const res = await api.request('DELETE', `${API}/me/art-key/own`);
+      if (res.status === 401) { toAuth(); return; }
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      renderArtKeyCard({ set: false, storage_configured: true });
+      wireArtKeyCard();
+      if (status) status.textContent = 'Key removed.';
+      toast('Image key removed.');
+    } catch (err) {
+      console.error('[settings] remove art key failed', err);
+      if (status) status.textContent = 'Could not remove. Try again.';
+      toast('Could not remove your key. Try again.');
+    }
+  }
+
+  async function loadArtKey(me) {
+    try {
+      // Remember the viewer's rank so the not-yet-configured state can offer the
+      // Archon "set it up" button (task 1398).
+      viewerRank = (me && me.builder && me.builder.rank) || (me && me.rank) || null;
+      renderArtKeyBanner(artKeyNeedItem(me));
+      const res = await api.request('GET', `${API}/me/art-key/own`);
+      if (res.status === 401) { toAuth(); return; }
+      if (!res.ok) throw new Error(`art-key GET → ${res.status}`);
+      renderArtKeyCard(res.data);
+      wireArtKeyCard();
+      $('#art-key').hidden = false;
+      // Landed here from the hall's "Add your key" action / the CLI nudge link.
+      if (location.hash === '#art-key') $('#art-key').scrollIntoView({ behavior: 'smooth' });
+    } catch (err) {
+      console.error('[settings] failed to load art key', err);
+      $('#art-key').hidden = false;
+      $('#artkey-card').innerHTML =
+        '<p class="voices-empty">Your image-generation key settings could not be loaded. Reload the page to try again.</p>';
+    }
+  }
+
+  // ---- module-contributed panels (BV1.R42, ADR 0083) -----------------------
+  //
+  // Render every Settings panel a module registered via
+  // window.OTB.contributeSettingsPanel (its browser-side client script runs
+  // before this one). Each panel gets its own <section class="scroll"> with a
+  // heading + a mount div, matching the hardcoded sections' shape. Empty until a
+  // module registers (none today) → no behavior change. One failing panel is
+  // isolated so it never takes the page down.
+  function mountContributedPanels() {
+    const host = $('#contributed-panels');
+    if (!host || typeof window.OTB.settingsPanels !== 'function') return;
+    for (const panel of window.OTB.settingsPanels()) {
+      try {
+        const section = document.createElement('section');
+        section.className = 'scroll';
+        section.id = `panel-${panel.id}`;
+        if (panel.title) {
+          const h = document.createElement('h2');
+          h.className = 'scroll__h';
+          h.textContent = panel.title;
+          section.appendChild(h);
+        }
+        const mount = document.createElement('div');
+        section.appendChild(mount);
+        host.appendChild(section);
+        panel.mount(mount);
+      } catch (err) {
+        console.error(`[settings] contributed panel "${panel && panel.id}" failed`, err);
+      }
+    }
+  }
+
+  // ---- section rail (grouped sub-nav, task 1723) -----------------------------
+  //
+  // The sections sit in six groups behind a left rail (#settings-rail). CSS on
+  // the page shows only the active group (.settings-groups[data-active]); a
+  // section's own [hidden] attribute still wins, so the per-section reveal
+  // logic above is unchanged. Deep links like #art-key activate their group
+  // first, so the existing scrollIntoView lands on a visible section.
+
+  const RAIL_GROUPS = ['account', 'devbox', 'access', 'preferences', 'sound', 'extensions'];
+
+  function activateGroup(group, opts) {
+    if (!RAIL_GROUPS.includes(group)) return;
+    const groups = document.getElementById('settings-groups');
+    if (!groups) return;
+    groups.dataset.active = group;
+    document.querySelectorAll('#settings-rail .rail-link').forEach((a) => {
+      a.classList.toggle('rail-link--active', a.dataset.group === group);
+    });
+    if (!opts || opts.scroll !== false) window.scrollTo({ top: 0 });
+  }
+
+  // Map a #hash to its group: either a group name itself (#access), or the id
+  // of an element inside a grouped section (#art-key → access).
+  function groupForHash(hash) {
+    const id = String(hash || '').replace(/^#/, '');
+    if (!id) return null;
+    if (RAIL_GROUPS.includes(id)) return id;
+    const el = document.getElementById(id);
+    const grouped = el && el.closest ? el.closest('[data-group]') : null;
+    return grouped ? grouped.getAttribute('data-group') : null;
+  }
+
+  function wireRail() {
+    const rail = document.getElementById('settings-rail');
+    if (!rail) return;
+    rail.addEventListener('click', (e) => {
+      const a = e.target.closest ? e.target.closest('.rail-link') : null;
+      if (!a || !a.dataset.group) return;
+      e.preventDefault();
+      activateGroup(a.dataset.group);
+    });
+    const fromHash = groupForHash(window.location.hash);
+    if (fromHash) activateGroup(fromHash, { scroll: false });
+  }
+
+  // Hide the rail + groups entirely while the not-signed-in gate is showing —
+  // an empty content column next to a floating rail reads as broken.
+  function hideLayout(hide) {
+    const layout = document.getElementById('settings-layout');
+    if (layout) layout.hidden = !!hide;
+  }
+
+  // ---- bootstrap -----------------------------------------------------------
+
+  async function load() {
+    // The OAuth callback (Discord) lands here with ?discord=…; surface it once.
+    handleDiscordReturn();
+    // Who is viewing? /me first — on 401 redirect into the web sign-in flow.
+    let builder, me;
+    try {
+      const res = await api.request('GET', `${API}/me`);
+      if (res.status === 401) { toAuth(); return; }
+      if (!res.ok) throw new Error(`me → ${res.status}`);
+      me = res.data;
+      builder = (me && me.builder) ? me.builder : me;
+    } catch (err) {
+      console.error('[settings] failed to read viewer', err);
+      $('#settings-sub').textContent = 'Could not load your account. Reload the page to try again.';
+      $('#gate-scroll').hidden = false;
+      hideLayout(true);
+      toast('Could not load your settings.');
+      return;
+    }
+
+    if (!builder) {
+      $('#settings-sub').textContent = 'No builder account found for this sign-in.';
+      $('#gate-scroll').hidden = false;
+      hideLayout(true);
+      return;
+    }
+
+    $('#gate-scroll').hidden = true;
+    hideLayout(false);
+    const who = builder.display_name || builder.github_login || 'builder';
+    $('#settings-sub').textContent = `Your preferences, ${who}.`;
+
+    // Seed craft state from the /me payload, then render + reveal that section.
+    const prefs = Array.isArray(builder.preferred_disciplines) ? builder.preferred_disciplines : [];
+    craft.selected = new Set(prefs.filter((d) => DISCIPLINES.includes(d)));
+    renderCraft();
+    wireCraft();
+    $('#craft-scroll').hidden = false;
+
+    // DISPLAY NAME — the label beside your work (task 1669); seeded from /me.
+    setupDisplayName(builder);
+
+    // DEV BOX — full box management (online terminal + SSH + close), #807.
+    setupBox();
+    // DEV BOX APP — static download links (#904); revealed once we know the
+    // viewer is a real builder (matches the page's hidden-until-loaded pattern).
+    $('#boxapp-scroll').hidden = false;
+    loadDevboxLatestVersion(); // #924: best-effort "latest version: X" courtesy line
+    // CONNECTIONS — Discord (hidden unless the server has Discord configured).
+    setupConnections(me && me.discord ? me.discord : null);
+    // CLI ACCESS — re-issue a CLI bearer from this browser session.
+    setupCliAccess();
+    // MODULE PANELS — render any Settings panels modules contributed via the
+    // seam (BV1.R42). None today; ready for dev-box/discord/art once they leave core.
+    mountContributedPanels();
+    // Reveal the Extensions rail entry only when a module actually contributed.
+    const contributed = $('#contributed-panels');
+    const railExt = document.getElementById('rail-extensions');
+    if (railExt) railExt.hidden = !(contributed && contributed.children.length > 0);
+
+    // Voices loads independently — its own endpoint + its own try/catch.
+    await loadVoices();
+    // Sounds loads independently too (per-sound on/off, #786).
+    await loadSounds();
+    // Event sounds loads independently (per-event variant picker, task 582).
+    await loadEventSounds();
+    // Wandering loads independently too (off-task thread suppression, task 1268).
+    await loadWandering();
+    // Rendering loads independently too (rich in-feed cards on/off, task 1279).
+    await loadRender();
+    // Image key (per-builder Gemini key, task 1013) — own try/catch; `me` carries
+    // the `needs` art_key item that drives the covered/action-needed banner.
+    await loadArtKey(me);
+  }
+
+  // #924: show the current published Dev Box app version next to the download
+  // buttons, read from the same public endpoint the app polls (/downloads/devbox/
+  // version → config/devbox-app.json). Best-effort: a fetch failure just leaves the
+  // courtesy line hidden — it must never break the settings page.
+  async function loadDevboxLatestVersion() {
+    try {
+      const r = await fetch('/downloads/devbox/version', { headers: { Accept: 'application/json' } });
+      if (!r.ok) return;
+      const v = await r.json();
+      if (v && v.version) {
+        const el = $('#boxapp-latest');
+        el.textContent = `Latest version: v${v.version}.`;
+        el.hidden = false;
+      }
+    } catch (_) { /* best-effort courtesy line — never break the page */ }
+  }
+
+  wireRail();
+  load();
+})();