@pellux/goodvibes-tui 1.16.0 → 1.17.0

package/src/renderer/selection-modal-overlay.ts

@@ -1,6 +1,6 @@
 import { type Line } from '../types/grid.ts';
 import { fitDisplay, getDisplayWidth, truncateDisplay } from '../utils/terminal-width.ts';
-import type { SelectionModal } from '../input/selection-modal.ts';
+import type { SelectionItem, SelectionModal } from '../input/selection-modal.ts';
 import {
   createOverlayBoxLayout,
   createOverlayContentLine,
@@ -30,6 +30,45 @@ function putText(line: Line, startX: number, maxWidth: number, text: string, sty
   putOverlayText(line, startX, maxWidth, text, style);
 }
 
+/**
+ * How an item's `detail` text fits on screen. Descriptive text is never
+ * clipped: if it doesn't fit beside the label at a readable width, the full
+ * text wraps onto its own line(s) below the label instead of being
+ * truncated. `wrappedDetail` is null when the detail fits inline (no data
+ * lost either way); otherwise it holds every wrapped line the FULL detail
+ * needs (no line-count cap).
+ */
+interface DetailLayout {
+  readonly labelWidth: number;
+  readonly detailWidth: number;
+  readonly wrappedDetail: readonly string[] | null;
+}
+
+function computeDetailLayout(item: SelectionItem, remaining: number): DetailLayout {
+  if (!item.detail) {
+    return { labelWidth: remaining, detailWidth: 0, wrappedDetail: null };
+  }
+  const cols = fitLabelDetailColumns(item.label, item.detail, remaining);
+  const fitsInline = cols.detailWidth >= 12 && getDisplayWidth(item.detail) <= cols.detailWidth;
+  if (fitsInline) {
+    return { labelWidth: cols.labelWidth, detailWidth: cols.detailWidth, wrappedDetail: null };
+  }
+  // Nothing shares this row with the label once the detail moves below it,
+  // so the label itself gets the full row width too.
+  return {
+    labelWidth: remaining,
+    detailWidth: cols.detailWidth,
+    wrappedDetail: wrapWithHangingIndent(item.detail, Math.max(8, remaining), ''),
+  };
+}
+
+/** Physical rows an item occupies: 1 for the label/inline-detail row, plus
+ * one more per wrapped detail line when the detail didn't fit inline. */
+function rowCostFor(item: SelectionItem, remaining: number): number {
+  if (!item.detail) return 1;
+  return 1 + (computeDetailLayout(item, remaining).wrappedDetail?.length ?? 0);
+}
+
 /**
  * Render the selection modal as Line[] for overlay in the viewport.
  */
@@ -39,12 +78,17 @@ export function renderSelectionModalOverlay(
   viewportHeight = 24,
 ): Line[] {
   const lines: Line[] = [];
+  const chromeRows = modal.allowSearch ? 5 : 4;
   const metrics = getOverlaySurfaceMetrics(width, viewportHeight, {
     margin: 4,
     maxWidth: 72,
-    chromeRows: modal.allowSearch ? 5 : 4,
+    chromeRows,
     minContentRows: 6,
-    maxContentRows: 10,
+    // Modals size to content: items whose detail wraps onto extra lines can
+    // need more physical rows than a plain one-row-per-item modal, so this
+    // ceiling grows with the viewport rather than staying pinned at a small
+    // constant (still bounded — never larger than the terminal can show).
+    maxContentRows: Math.max(10, viewportHeight - chromeRows - 4),
   });
   const layout = createOverlayBoxLayout(width, metrics.margin, metrics.boxWidth);
 
@@ -99,15 +143,51 @@ export function renderSelectionModalOverlay(
     putText(line, layout.margin + 2, layout.innerWidth, fitDisplay(message, layout.innerWidth), { fg: MUTED_FG, dim: true });
     lines.push(line);
   } else {
-    const maxVisible = metrics.contentRows;
-    let startIdx = 0;
-    if (items.length > maxVisible) {
-      startIdx = Math.max(0, Math.min(
-        modal.selectedIndex - Math.floor(maxVisible / 2),
-        items.length - maxVisible,
-      ));
+    const indicatorWidth = 2;
+    const remaining = layout.innerWidth - indicatorWidth;
+    const rowBudget = Math.max(1, metrics.contentRows);
+
+    // Row-budget-aware windowing: rather than assuming one physical row per
+    // item, account for items whose detail wraps onto extra lines, so the
+    // visible window never silently shows fewer full items than the budget
+    // allows just because a fixed item-count cap ran out. Always shows the
+    // selected item (even alone, if its wrapped detail is taller than the
+    // whole budget — descriptive text is never clipped to make it fit),
+    // then grows outward, roughly centered, until the budget is spent.
+    const selected = Math.max(0, Math.min(modal.selectedIndex, items.length - 1));
+    let startIdx = selected;
+    let endIdx = selected + 1;
+    let usedRows = rowCostFor(items[selected], remaining);
+    let growBefore = true;
+    while (startIdx > 0 || endIdx < items.length) {
+      const canGrowBefore = growBefore && startIdx > 0;
+      const canGrowAfter = !growBefore && endIdx < items.length;
+      if (canGrowBefore) {
+        const cost = rowCostFor(items[startIdx - 1], remaining);
+        if (usedRows + cost > rowBudget) break;
+        startIdx -= 1;
+        usedRows += cost;
+      } else if (canGrowAfter) {
+        const cost = rowCostFor(items[endIdx], remaining);
+        if (usedRows + cost > rowBudget) break;
+        endIdx += 1;
+        usedRows += cost;
+      } else if (startIdx > 0) {
+        const cost = rowCostFor(items[startIdx - 1], remaining);
+        if (usedRows + cost > rowBudget) break;
+        startIdx -= 1;
+        usedRows += cost;
+      } else if (endIdx < items.length) {
+        const cost = rowCostFor(items[endIdx], remaining);
+        if (usedRows + cost > rowBudget) break;
+        endIdx += 1;
+        usedRows += cost;
+      } else {
+        break;
+      }
+      growBefore = !growBefore;
     }
-    const endIdx = Math.min(startIdx + maxVisible, items.length);
+
     let lastCategory: string | undefined;
 
     for (let i = startIdx; i < endIdx; i++) {
@@ -125,13 +205,10 @@ export function renderSelectionModalOverlay(
       }
 
       const indicator = isSelected ? `${OVERLAY_GLYPHS.selected} ` : '  ';
-      const indicatorWidth = 2;
-      const remaining = layout.innerWidth - indicatorWidth;
       const labelColor = isSelected ? TITLE_FG : (item.fg ?? BODY_FG);
       const detailColor = isSelected ? BODY_FG : MUTED_FG;
-      const labelWidth = item.detail
-        ? fitLabelDetailColumns(item.label, item.detail, remaining).labelWidth
-        : remaining;
+      const detailLayout = computeDetailLayout(item, remaining);
+      const labelWidth = detailLayout.labelWidth;
       const labelLine = createOverlayContentLine(width, layout, BORDER_FG, isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg);
         putText(labelLine, layout.margin + 2, indicatorWidth, indicator, {
           fg: isSelected ? TITLE_FG : MUTED_FG,
@@ -144,23 +221,24 @@ export function renderSelectionModalOverlay(
         bold: isSelected,
       });
       if (item.detail) {
-          const detailWidth = fitLabelDetailColumns(item.label, item.detail, remaining).detailWidth;
-        if (detailWidth >= 12) {
+        if (detailLayout.wrappedDetail === null) {
+          // Fits beside the label at a readable width — no truncation needed.
           putText(labelLine, layout.margin + 2 + indicatorWidth + labelWidth, 2, '  ', {
             fg: BODY_FG,
             bg: isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg,
           });
-          putText(labelLine, layout.margin + 2 + indicatorWidth + labelWidth + 2, detailWidth, fitDisplay(truncateDisplay(item.detail, detailWidth), detailWidth), {
+          putText(labelLine, layout.margin + 2 + indicatorWidth + labelWidth + 2, detailLayout.detailWidth, fitDisplay(item.detail, detailLayout.detailWidth), {
             fg: detailColor,
             bg: isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg,
           });
           lines.push(labelLine);
         } else {
+          // Doesn't fit beside the label — wrap the FULL detail text onto as
+          // many lines as it needs below the label, rather than clipping it.
           lines.push(labelLine);
-          const wrappedDetails = wrapWithHangingIndent(item.detail, Math.max(8, remaining), '', 2);
-          for (const detailLineText of wrappedDetails) {
+          for (const detailLineText of detailLayout.wrappedDetail) {
             const detailLine = createOverlayContentLine(width, layout, BORDER_FG, isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg);
-            putText(detailLine, layout.margin + 2 + indicatorWidth, remaining, fitDisplay(truncateDisplay(detailLineText, remaining), remaining), {
+            putText(detailLine, layout.margin + 2 + indicatorWidth, remaining, fitDisplay(detailLineText, remaining), {
               fg: detailColor,
               bg: isSelected ? SELECTED_BG : DEFAULT_OVERLAY_PALETTE.bodyBg,
               dim: !isSelected,
@@ -173,7 +251,7 @@ export function renderSelectionModalOverlay(
       }
     }
 
-    if (items.length > maxVisible) {
+    if (startIdx > 0 || endIdx < items.length) {
       const above = startIdx;
       const below = items.length - endIdx;
       const scrollHint = above > 0 && below > 0
@@ -189,7 +267,7 @@ export function renderSelectionModalOverlay(
 
   const footerLine = createOverlayContentLine(width, layout, BORDER_FG, DEFAULT_OVERLAY_PALETTE.sectionBg);
   const selectedItem = modal.getSelected();
-  // UX-C vocab unification: a caller-supplied primaryVerbLabel (e.g. /help's
+  // vocab unification: a caller-supplied primaryVerbLabel (e.g. /help's
   // "Run", matching the slash-command palette) wins over the generic
   // per-primaryAction default.
   const primaryVerb = modal.primaryVerbLabel

package/src/renderer/session-picker-modal.ts

@@ -42,7 +42,7 @@ function isClosedStatus(status: string): boolean {
 }
 
 /**
- * D-TUI/#A2: closed sessions carry an optional, honest reason for WHY they
+ * Closed sessions carry an optional, honest reason for WHY they
  * closed under `metadata.closeReason` (SDK's `SharedSessionCloseReason`,
  * 'closeReason' key — see `@pellux/goodvibes-sdk` platform/control-plane
  * session-broker-sessions.ts's `readSessionCloseReason`). `metadata` is an
@@ -58,7 +58,7 @@ function readCloseReason(record: SharedSessionRecord): string | undefined {
 /**
  * A GC sweep closing an idle session ('idle-reaped') auto-reopens on the next
  * heartbeat — it is NOT the same event as a deliberate user/surface close, so
- * it must never render under the same "closed" badge (W4/#A2). Tolerant of
+ * it must never render under the same "closed" badge. Tolerant of
  * records without the field (pre-feature builds, or a deliberate close).
  */
 function isReapedRecord(record: SharedSessionRecord): boolean {

package/src/renderer/settings-modal-helpers.ts

@@ -11,7 +11,7 @@ import { UI_TONES } from './ui-primitives.ts';
 
 /**
  * "Modified / active" accent for settings rows — cyan-green, no UI_TONES
- * role matches it (WO-207b: preserved byte-exact as a named constant).
+ * role matches it (preserved byte-exact as a named constant).
  */
 const SETTINGS_ACCENT = '#00ffcc';
 
@@ -31,6 +31,14 @@ export function formatValue(entry: SettingEntry): string {
   // Array-backed settings (e.g. worktree.setup.commands) display as a
   // comma-separated list, matching how they're edited (see worktree-setup-config.ts).
   if (Array.isArray(val)) return val.length > 0 ? val.join(', ') : '(empty)';
+  // Object-backed settings (e.g. pricing.modelPrices) display their JSON when
+  // short, or an honest entry count — never the useless "[object Object]".
+  if (typeof val === 'object') {
+    const keys = Object.keys(val as Record<string, unknown>);
+    if (keys.length === 0) return '(none set)';
+    const json = JSON.stringify(val);
+    return json.length <= 64 ? json : `${keys.length} entr${keys.length === 1 ? 'y' : 'ies'} (Enter to edit as JSON)`;
+  }
   return String(val);
 }
 
@@ -57,6 +65,8 @@ export const CATEGORY_LABELS: Record<(typeof SETTINGS_CATEGORIES)[number], strin
   display: 'Display',
   ui: 'UI',
   provider: 'Provider',
+  pricing: 'Pricing',
+  update: 'Updates',
   subscriptions: 'Subscriptions',
   behavior: 'Behavior',
   storage: 'Storage',
@@ -87,7 +97,6 @@ export const CATEGORY_LABELS: Record<(typeof SETTINGS_CATEGORIES)[number], strin
   release: 'Release',
   danger: 'Danger',
   tools: 'Tools',
-  flags: 'Advanced Features',
   network: 'Network',
   relay: 'Relay',
   learning: 'Learning',
@@ -171,9 +180,9 @@ const SETTING_LABELS: Partial<Record<string, string>> = {
 };
 
 export function getSettingLabel(entry: SettingEntry): string {
-  // Feature-unit toggle headers carry the flag's human name, not the raw
-  // `featureFlags.<id>` key tail.
-  if (entry.flag) return entry.flag.flag.name;
+  // Feature-unit headers carry the feature's human name, not the raw
+  // enablement-key tail.
+  if (entry.flag) return entry.flag.feature.name;
   return SETTING_LABELS[entry.setting.key] ?? entry.setting.key.replace(/^[^.]+\./, '');
 }
 

package/src/renderer/settings-modal.ts

@@ -6,8 +6,9 @@
  */
 
 import type { Line } from '../types/grid.ts';
-import type { SettingsModal, SettingEntry, FlagEntry, McpEntry, SubscriptionEntry, SettingsCategory } from '../input/settings-modal.ts';
+import type { SettingsModal, SettingEntry, McpEntry, SubscriptionEntry, SettingsCategory } from '../input/settings-modal.ts';
 import { SETTINGS_CATEGORIES, SETTINGS_CATEGORY_GROUPS } from '../input/settings-modal.ts';
+import { FEATURE_SETTINGS_BY_ID, isFeatureValueEnabled } from '../runtime/feature-settings.ts';
 import { getDisplayWidth, wrapText } from '../utils/terminal-width.ts';
 import { CATEGORY_LABELS, describeUiRouting, formatValue, getSettingLabel, inferSubscriptionRouteReason, valueColor } from './settings-modal-helpers.ts';
 import { isSecretConfigKey } from '../config/secret-config.ts';
@@ -27,6 +28,8 @@ const CATEGORY_INFO: Record<SettingsCategory, string> = {
   display: 'Presentation settings for the terminal transcript: streaming, line numbers, thinking visibility, reasoning summaries, token speed, and tool previews.',
   ui: 'Controls where operational messages render and whether voice surfaces are enabled. These settings change visibility, not provider behavior.',
   provider: 'Default model routing for normal chat turns, embeddings, reasoning effort, and persistent system prompt file.',
+  pricing: 'Manual model prices (USD per 1M tokens, keyed provider:model). Your price wins over provider-served and catalog prices in every cost display, immediately.',
+  update: 'Self-update posture: whether the daemon checks hourly and updates at an idle moment, the release source it checks, and the check cadence. Clients update at launch; every swap keeps the previous binary for one-command rollback.',
   subscriptions: 'Provider subscription login state and routing posture. Active sessions can be reviewed or signed out here; API keys remain managed through secrets.',
   behavior: 'Day-to-day shell behavior: approval posture, compaction, history, guidance, notifications, stale-context warnings, return context, and Human-in-the-Loop mode.',
   storage: 'Local storage posture, including secret storage policy and maximum artifact size for knowledge/home graph/document ingestion.',
@@ -57,7 +60,6 @@ const CATEGORY_INFO: Record<SettingsCategory, string> = {
   release: 'Release-channel preference.',
   danger: 'High-impact switches for daemon and HTTP listener behavior. These are operational overrides, not normal preferences.',
   tools: 'Tool LLM and helper model routing. Empty provider/model values inherit the active chat route unless a specific helper/tool route is set.',
-  flags: 'Advanced feature toggles with no tuning knobs — internal and startup-gated runtime gates. Features that DO have config sit as units (toggle + settings) in their topical category, not here.',
   network: 'Combined network view for daemon control-plane, HTTP listener, browser web surface, and general outbound network settings.',
   fetch: 'Fetch response sanitization and host trust tiers for the fetch tool: sanitize mode plus default trusted/blocked host lists. Gated by the Fetch Response Sanitization feature.',
   agents: 'Sub-agent context-window awareness and per-turn passive knowledge/code injection: token budget, relevance floor, code-chunk limit, and the compaction threshold. Gated by the agent context/injection features.',
@@ -65,7 +67,7 @@ const CATEGORY_INFO: Record<SettingsCategory, string> = {
   integrations: 'Integration delivery reliability (Slack/Discord/webhook): retry counts, backoff bounds, dead-letter queue size, and SLO enforcement. Gated by the Integration Delivery SLO feature.',
   policy: 'Policy-as-code bundle loading: where the startup policy bundle is loaded from and its file path. Gated by the Policy-as-Code feature.',
   notifications: 'Notification router burst-suppression tuning: burst window, threshold, and cooldown. Gated by the Adaptive Notification Suppression feature.',
-  relay: 'Outbound zero-knowledge relay reachability, for reaching this daemon from outside the LAN without opening an inbound port. Off by default; also gated by the relay-connect feature flag. The relay operator sees only ciphertext and connection metadata — self-host your own relay for full control.',
+  relay: 'Outbound zero-knowledge relay reachability, for reaching this daemon from outside the LAN without opening an inbound port. Off by default — relay.enabled is the switch. The relay operator sees only ciphertext and connection metadata — self-host your own relay for full control.',
   learning: 'Idle-time memory consolidation: merging duplicate standing memory records and decaying/archiving stale ones. Off by default — nothing runs until enabled.',
 };
 
@@ -181,6 +183,13 @@ function buildSettingContext(modal: SettingsModal, entry: SettingEntry): string[
   if (entry.locked) lines.push(`Locked: ${entry.lockReason ?? 'This setting is locked by a higher-priority layer.'}`);
   if (entry.conflict) lines.push(`Conflict: resolve with /settings-sync resolve ${entry.setting.key} local|synced.`);
 
+  // A settings sub-row owned by a feature unit names its feature so "what
+  // does this do" is answerable without scrolling back to the header row.
+  if (entry.ownerFlagId) {
+    const owner = FEATURE_SETTINGS_BY_ID.get(entry.ownerFlagId);
+    if (owner) lines.push(`Part of feature: ${owner.name} (the header row above).`);
+  }
+
   lines.push('', entry.setting.description);
 
   if (
@@ -225,26 +234,86 @@ function buildSettingContext(modal: SettingsModal, entry: SettingEntry): string[
   return lines;
 }
 
-function buildFlagContext(entry: FlagEntry | null): string[] {
-  if (!entry) return ['Feature flags', 'No feature flag is selected.'];
-  return [
-    entry.flag.name,
-    `ID: ${entry.flag.id}`,
-    `State: ${entry.state}`,
-    `Default: ${entry.flag.defaultState}`,
-    `Tier: ${entry.flag.tier}`,
-    `Runtime toggleable: ${entry.flag.runtimeToggleable ? 'yes' : 'no'}`,
-    ...(entry.pendingRestart
-      ? [`Pending restart: saved as ${entry.persistedState}; effective state stays ${entry.state} until the next launch.`]
+/**
+ * The option shape of a feature header, rendered from the same schema the
+ * write path uses: enum headers list every mode choice (marking the current
+ * value and which values keep the feature active), boolean headers state the
+ * two positions.
+ */
+function buildFeatureOptionLines(entry: SettingEntry): string[] {
+  const feature = entry.flag!.feature;
+  const setting = entry.setting;
+  const lines: string[] = [];
+  if (setting.type === 'enum' && setting.enumValues) {
+    lines.push('', `Mode choices for ${setting.key}:`);
+    const activeValues = feature.enablement.enabledValues ?? [];
+    const descriptions = ENUM_VALUE_DESCRIPTIONS[setting.key] ?? {};
+    for (const value of setting.enumValues) {
+      const marks: string[] = [];
+      if (value === String(entry.currentValue)) marks.push('current');
+      if (feature.enablement.kind === 'enum') {
+        marks.push(activeValues.includes(value) ? 'feature on' : 'feature off');
+      }
+      const suffix = marks.length > 0 ? ` (${marks.join(', ')})` : '';
+      lines.push(`${value}${suffix}: ${descriptions[value] ?? `Use ${value} for this setting.`}`);
+    }
+  } else if (setting.type === 'boolean') {
+    lines.push('');
+    lines.push('Possible values:');
+    lines.push('true: the feature is enabled.');
+    lines.push('false: the feature is disabled.');
+  }
+  return lines;
+}
+
+/**
+ * Under-cursor documentation for a feature-unit header, rendered entirely
+ * from the SDK's per-feature settings metadata: full behavior description,
+ * the real option shape, every settings key that tunes the feature, and the
+ * honest live/restart state from the gate manager.
+ */
+function buildFlagContext(entry: SettingEntry | null): string[] {
+  const flagEntry = entry?.flag ?? null;
+  if (!entry || !flagEntry) return ['Features', 'No feature is selected.'];
+  const { feature, flag, state, persistedState, pendingRestart } = flagEntry;
+  const configOn = isFeatureValueEnabled(feature, entry.currentValue);
+  const displayState = state === 'killed' ? 'killed' : configOn ? 'enabled' : 'disabled';
+  const lines: string[] = [
+    feature.name,
+    `Feature: ${feature.id} (${feature.domain} domain)`,
+    `Setting: ${feature.enablement.key} = ${formatValue(entry)}`,
+    `State: ${displayState}`,
+    `Default: ${feature.defaultEnabled ? 'enabled' : 'disabled'}`,
+    `Applies: ${feature.restartRequired ? 'on next launch (startup-gated)' : 'immediately'}`,
+    ...(pendingRestart
+      ? [`Pending restart: saved as ${persistedState}; effective state stays ${state} until the next launch.`]
       : []),
     '',
-    entry.flag.description,
-    ...(entry.state === 'killed' && entry.flag.killReason ? ['', `Kill reason: ${entry.flag.killReason}`] : []),
-    '',
-    entry.flag.runtimeToggleable
-      ? 'Impact: changes apply immediately and are also persisted as an override when they differ from the default.'
-      : 'Impact: this flag is persisted as an override and requires restart before startup-only code sees the new state.',
+    feature.description,
   ];
+
+  lines.push(...buildFeatureOptionLines(entry));
+
+  lines.push('');
+  if (feature.enablement.kind === 'enum') {
+    lines.push(`How it turns on: active while ${feature.enablement.key} is ${(feature.enablement.enabledValues ?? []).join(' or ')}.`);
+  } else if (feature.enablement.kind === 'constant' && entry.setting.type !== 'boolean') {
+    lines.push('How it turns on: always active; the settings listed below tune its behavior directly.');
+  } else {
+    lines.push(`How it turns on: ${feature.enablement.key} set to true.`);
+  }
+
+  if (feature.settings.length > 1) {
+    lines.push('', 'Settings in this feature:');
+    for (const key of feature.settings) {
+      lines.push(key === feature.enablement.key ? `${key} (this row)` : key);
+    }
+  }
+
+  if (state === 'killed' && flag.killReason) {
+    lines.push('', `Kill reason: ${flag.killReason}`);
+  }
+  return lines;
 }
 
 function buildMcpContext(modal: SettingsModal, entry: McpEntry | null): string[] {
@@ -332,9 +401,10 @@ function buildContextLines(modal: SettingsModal, width: number): string[] {
     lines.push(...buildSubscriptionContext(modal, modal.getSelectedSubscription()));
   } else {
     const selected = modal.getSelected();
-    // A feature-unit toggle header shows flag context (tier, default, impact);
-    // its config sub-options and plain settings show the setting context.
-    if (selected?.flag) lines.push(...buildFlagContext(selected.flag));
+    // A feature-unit header shows the feature's documentation (full
+    // description, option shape, settings list, live/restart state); its
+    // settings sub-rows and plain settings show the setting context.
+    if (selected?.flag) lines.push(...buildFlagContext(selected));
     else if (selected) lines.push(...buildSettingContext(modal, selected));
     else lines.push('No setting is selected in this category.');
   }
@@ -355,7 +425,6 @@ function buildContextLines(modal: SettingsModal, width: number): string[] {
 function categoryItemCount(modal: SettingsModal, category: SettingsCategory): number {
   if (category === 'mcp') return modal.mcpEntries.length;
   if (category === 'subscriptions') return modal.subscriptionEntries.length;
-  // 'flags' (Advanced Features) now flows through the normal group path.
   return modal.groups.get(category)?.length ?? 0;
 }
 
@@ -454,15 +523,18 @@ function renderSettingTableRow(
   defaultWidth: number,
 ): string {
   if (entry.flag) {
-    const { flag, state, pendingRestart, persistedState } = entry.flag;
-    const stateMark = state === 'enabled' ? '●' : state === 'killed' ? '✕' : '○';
-    const label = `${stateMark} ${flag.name}`;
-    const source = `tier ${flag.tier} ${flag.runtimeToggleable ? 'live' : 'restart'}`;
-    // A startup-gated flag toggled this session keeps its effective state and
-    // shows the pending value it will take on restart, so the row never implies
-    // the change already took effect.
-    const value = pendingRestart ? `${state} → ${persistedState} on restart` : state;
-    return `${marker} ${padDisplay(label, keyWidth)}  ${padDisplay(value, valueWidth)}  ${padDisplay('feature', typeWidth)}  ${padDisplay(source, sourceWidth)}  ${padDisplay(flag.defaultState, defaultWidth)}`;
+    const { feature, state, pendingRestart } = entry.flag;
+    const configOn = isFeatureValueEnabled(feature, entry.currentValue);
+    const stateMark = state === 'killed' ? '✕' : configOn ? '●' : '○';
+    const label = `${stateMark} ${feature.name}`;
+    const source = feature.restartRequired ? 'restart' : 'live';
+    // A startup-gated feature changed this session shows its saved value with
+    // a compact restart-pending marker (⟳), so the row never implies the
+    // change already took effect; the documentation pane spells out the full
+    // "Pending restart: ..." sentence.
+    const rawValue = currentSettingValue(modal, entry, selected);
+    const value = pendingRestart ? `${rawValue} ⟳` : rawValue;
+    return `${marker} ${padDisplay(label, keyWidth)}  ${padDisplay(value, valueWidth)}  ${padDisplay('feature', typeWidth)}  ${padDisplay(source, sourceWidth)}  ${padDisplay(feature.defaultEnabled ? 'enabled' : 'disabled', defaultWidth)}`;
   }
   const value = currentSettingValue(modal, entry, selected);
   const source = `${entry.effectiveSource ?? 'default'}${entry.locked ? ' locked' : ''}${entry.conflict ? ' conflict' : ''}`;
@@ -626,9 +698,9 @@ function footerText(modal: SettingsModal, width: number): string {
       { key: 'Enter', verb: 'Edit trust' },
       { key: 'Esc', verb: 'Close' },
     ]));
-  // 'flags' (Advanced Features) and every topical category that now hosts feature
-  // units flow through the default settings footer below — Enter/Space toggles a
-  // feature-unit header exactly as it edits/toggles any setting row.
+  // Every topical category that hosts feature units flows through the default
+  // settings footer below — Enter/Space toggles a feature-unit header exactly
+  // as it edits/toggles any setting row.
   // Default settings pane: tier the reset affordances by available width.
   // W<80:  minimal — only the most critical action survives.
   // W<160: compact but still shows both reset affordances.
@@ -639,6 +711,7 @@ function footerText(modal: SettingsModal, width: number): string {
     return formatHints([
       { key: 'Up/Down', verb: 'Move' },
       { key: 'Enter/Space', verb: 'Edit' },
+      { key: 'PgUp/PgDn', verb: 'docs' },
       { key: '⇧R', verb: 'reset cat' },
       { key: '^⇧R', verb: 'reset all' },
       { key: 'Esc', verb: 'Close' },
@@ -647,6 +720,7 @@ function footerText(modal: SettingsModal, width: number): string {
     { key: 'Up/Down', verb: 'Setting' },
     { key: 'Left', verb: 'Categories' },
     { key: 'Enter/Space', verb: 'Edit/toggle' },
+    { key: 'PgUp/PgDn', verb: 'Scroll docs' },
     { key: '⇧R', verb: 'reset cat' },
     { key: '^⇧R', verb: 'reset all' },
     { key: 'Esc', verb: 'Close' },
@@ -664,12 +738,26 @@ export function renderSettingsModal(
   ];
   const metrics = getFullscreenWorkspaceMetrics({ width, height: viewportHeight });
   const categoryRows = renderCategories(modal, metrics.leftWidth - 2, metrics.bodyRows);
-  const contextRows = buildContextLines(modal, metrics.contextWidth).map((text, row): WorkspaceRow => {
+  // Documentation pane: long content SCROLLS (PgUp/PgDn) with honest
+  // more-above/below markers — it is never silently clipped.
+  const allContextLines = buildContextLines(modal, metrics.contextWidth);
+  const visibleContext = metrics.contextRows;
+  const maxContextScroll = Math.max(0, allContextLines.length - visibleContext);
+  const contextOffset = Math.min(Math.max(0, modal.contextScroll ?? 0), maxContextScroll);
+  const windowedContext = allContextLines.slice(contextOffset, contextOffset + visibleContext);
+  if (contextOffset > 0) {
+    windowedContext[0] = `${GLYPHS.navigation.moreAbove} ${contextOffset} more line(s) above — PgUp`;
+  }
+  if (contextOffset + visibleContext < allContextLines.length) {
+    const below = allContextLines.length - contextOffset - visibleContext;
+    windowedContext[windowedContext.length - 1] = `${GLYPHS.navigation.moreBelow} ${below} more line(s) below — PgDn`;
+  }
+  const contextRows = windowedContext.map((text, row): WorkspaceRow => {
     const selectedSetting = modal.getSelected();
-    const isTitle = row === 0 || (selectedSetting !== null && text === getSettingLabel(selectedSetting));
+    const isTitle = (row === 0 && contextOffset === 0) || (selectedSetting !== null && text === getSettingLabel(selectedSetting));
     return {
       text,
-      fg: row === 0 ? PALETTE.title : text.endsWith(':') ? PALETTE.subtitle : PALETTE.text,
+      fg: row === 0 && contextOffset === 0 ? PALETTE.title : text.endsWith(':') ? PALETTE.subtitle : PALETTE.text,
       bold: isTitle,
       dim: text.length === 0,
     };

package/src/renderer/shell-surface.ts

@@ -65,6 +65,8 @@ export interface ShellFooterBuildOptions {
    * embedded/local mode so no segment renders.
    */
   readonly sessionSpineStatus?: 'online' | 'offline';
+  /** The web surface's reachable URL, when that surface is enabled; a persistent footer segment. */
+  readonly webSurfaceUrl?: string;
 }
 
 export interface ShellFooterBuildResult {
@@ -144,6 +146,7 @@ export function buildShellFooter(
     options.compact ?? false,
     options.sessionSpineStatus,
     options.permissionMode,
+    options.webSurfaceUrl,
   );
   // Compact posture drops the process indicator and context hint entirely so
   // the footer fits within ~5 rows on short terminals.

package/src/renderer/terminal-bg-probe.ts

@@ -1,7 +1,7 @@
 /**
  * terminal-bg-probe — OSC 11 terminal-background detection for `auto` theme mode.
  *
- * DEBT-2. On startup, when appearance is `auto` and stdout is a TTY, we ask
+ *. On startup, when appearance is `auto` and stdout is a TTY, we ask
  * the terminal for its background colour with an OSC 11 query and classify the
  * reply as light or dark. Everything about this is best-effort and conservative:
  * any timeout, any unparseable reply, any ambiguity resolves to DARK, which is

package/src/renderer/theme.ts

@@ -21,7 +21,7 @@
  * DEFAULT_PANEL_PALETTE, DEFAULT_STYLE, FULLSCREEN_PALETTE and
  * DEFAULT_OVERLAY_PALETTE all read through ONE mode-resolved path instead of
  * importing the static UI_TONES constant directly. Mode stays 'dark'
- * everywhere until the terminal-bg-probe lands (see WO-001) — the light
+ * everywhere until the terminal-bg-probe lands (see) — the light
  * entry is type-complete, not a shipped light theme.
  */
 
@@ -173,7 +173,7 @@ export const DARK_THEME: Readonly<ThemeTokens> = DARK;
 //
 // UI_TONES (ui-primitives.ts) is the dark entry. The light entry mirrors
 // dark for every role that has no light-appropriate equivalent yet — the
-// WO-001 deliverable is the mode dimension and single read path, not a
+// deliverable is the mode dimension and single read path, not a
 // shipped light chrome theme (see module doc comment above).
 // ---------------------------------------------------------------------------
 
@@ -242,7 +242,7 @@ export function resolveUiTones(mode: ThemeMode): Readonly<UiToneTokens> {
 }
 
 // ===========================================================================
-// Active-mode runtime (DEBT-2 terminal-bg-probe landing).
+// Active-mode runtime (terminal-bg-probe landing).
 //
 // The mode is decided ONCE at startup — from appearance config (display.themeMode
 // forced dark/light) or the terminal-background probe (auto) — and is then stable

package/src/renderer/tool-call.ts

@@ -173,7 +173,7 @@ export function renderToolCallBlock(
 
   // Status icon. 'pending' means the tool is still awaiting a decision
   // (e.g. an approval prompt) and has NOT run yet — it uses the hollow idle
-  // glyph so a not-yet-run tool never shows the completed green ✓ (UX-B 2c).
+  // glyph so a not-yet-run tool never shows the completed green ✓ (2c).
   const icon = status === 'done' ? TOOL_STATUS.SUCCESS_ICON
     : status === 'error' ? TOOL_STATUS.FAIL_ICON
     : status === 'pending' ? GLYPHS.status.idle

package/src/renderer/tool-result-summary.ts

@@ -4,7 +4,7 @@
  * in conversation-rendering.ts) shows "wrote haiku.txt (532 B)" instead of a
  * raw `{"files_written":1,"bytes_written":532,...}` JSON blob. The full payload
  * stays reachable behind the existing collapse/expand toggle — this only
- * changes the collapsed preview line, never destroys data. (UX-B item 3.)
+ * changes the collapsed preview line, never destroys data. (item 3.)
  *
  * Returning `null` means "no honest summary for this shape" — the caller then
  * falls back to the previous raw-first-line preview, so an unrecognised tool or

package/src/renderer/turn-injection.ts

@@ -1,8 +1,8 @@
 /**
  * Per-turn knowledge injection record rendering.
  *
- * The SDK's passive per-turn retrieval engine (wo801, W5.1 —
- * packages/sdk/src/platform/agents/turn-knowledge-injection.ts) stores one
+ * The SDK's passive per-turn retrieval engine
+ * (packages/sdk/src/platform/agents/turn-knowledge-injection.ts) stores one
  * `TurnInjectionRecord` per turn on `AgentRecord.turnInjections` (a bounded
  * ring, default 20 entries) and appends the same record to the agent's
  * session transcript as `{type:'knowledge_injection', turn, ...record}`.
@@ -34,10 +34,11 @@ function fmtN(n: number): string {
 }
 
 /**
- * Annotate each injected id with its source (Stage B). Code-index hits get a
+ * Annotate each injected id with its source. Code-index hits get a
  * ` [code]` tag; memory records are left bare so a memory-only line renders
- * byte-identically to the pre-Stage-B output. `injectedSources` is parallel to
- * `injectedIds`; a missing/short entry defaults to memory (no tag).
+ * byte-identically to the output from before code-index hits existed.
+ * `injectedSources` is parallel to `injectedIds`; a missing/short entry
+ * defaults to memory (no tag).
  */
 function labelInjectedIds(entry: TurnInjectionEntry): string {
   const sources = entry.injectedSources ?? [];
@@ -107,7 +108,7 @@ export function buildTurnInjectionsText(agentId: string, entries: readonly TurnI
 
 /**
  * Render the MAIN interactive session's per-turn injection ring
- * (`Orchestrator.getTurnInjections()`, wo805), most-recent-turn first, with the
+ * (`Orchestrator.getTurnInjections()`), most-recent-turn first, with the
  * same honest empty state as the per-agent path. The main-session counterpart
  * to {@link buildTurnInjectionsText}: no agent id, main-session-appropriate
  * wording, but the identical per-entry rendering (`formatTurnInjectionEntry`).