mixdog 0.9.1 → 0.9.2

package/src/tui/App.jsx

@@ -22,17 +22,22 @@ import React, { useState, useCallback, useEffect, useLayoutEffect, useMemo, useR
 import { Box, Text, useApp, useInput, useStdin, useStdout } from 'ink';
 import stringWidth from 'string-width';
 import stripAnsi from 'strip-ansi';
-import { theme, TURN_MARKER, RESULT_GUTTER } from './theme.mjs';
+import { theme, surfaceBackground, TURN_MARKER, RESULT_GUTTER } from './theme.mjs';
 import { useEngine } from './hooks/useEngine.mjs';
-import { renderTokenAnsiSegments } from './markdown/render-ansi.mjs';
-import { assistantBodyWidth, measureMarkdownTableRows } from './markdown/table-layout.mjs';
+import {
+  measureMarkdownRenderedRows,
+  measureStreamingMarkdownRenderedRows,
+} from './markdown/measure-rendered-rows.mjs';
+import { streamingLayoutText } from './markdown/streaming-markdown.mjs';
+import { displayWidth } from './display-width.mjs';
 import { classifyToolCategory, formatToolSurface, normalizeToolName, parseToolArgs, summarizeAgentSurfaceBrief } from '../runtime/shared/tool-surface.mjs';
 import { isBackgroundErrorOnlyBody } from '../runtime/shared/err-text.mjs';
-import { AssistantMessage, UserMessage, ThinkingMessage, NoticeMessage } from './components/Message.jsx';
+import { AssistantMessage, UserMessage, NoticeMessage } from './components/Message.jsx';
 import { ToolExecution } from './components/ToolExecution.jsx';
 import { formatExpandedResult, wrapExpandedResultLines } from './components/tool-output-format.mjs';
 import { Spinner } from './components/Spinner.jsx';
 import { StatusDone, TurnDone } from './components/TurnDone.jsx';
+import { ItemRightHintOverprint } from './components/ItemRightHintOverprint.jsx';
 import { StatusLine } from './components/StatusLine.jsx';
 import { PromptInput } from './components/PromptInput.jsx';
 import { QueuedCommands } from './components/QueuedCommands.jsx';
@@ -67,13 +72,30 @@ import {
   shouldSuppressFullyFailedToolItem,
   toolItemResultText,
 } from './transcript-tool-failures.mjs';
+import {
+  toggleVoice,
+  isVoiceEnabled,
+  getRecorderState,
+  startRecording,
+  stopRecording,
+  cancelRecording,
+  disposeRecorder,
+} from './lib/voice-recorder.mjs';
 
 import { displayModelName } from '../ui/model-display.mjs';
+import { supportsExtendedKeys, ENABLE_KITTY_KEYBOARD, ENABLE_MODIFY_OTHER_KEYS } from './keyboard-protocol.mjs';
 
 const MOUSE_TRACKING_ON = '\x1b[?1000h\x1b[?1002h\x1b[?1006h';
 const MOUSE_TRACKING_OFF = '\x1b[?1006l\x1b[?1002l\x1b[?1000l';
 const MOUSE_MODIFIER_MASK = 4 | 8 | 16;
 const MOUSE_CTRL_MASK = 16;
+// SEARCH_DEFAULT marker — mirrors backend SEARCH_DEFAULT_PROVIDER/MODEL
+// (mixdog-session-runtime.mjs 1167-1168). A search route of {provider:'default',
+// model:'default'} means "follow the Main Model" at runtime (nativeSearchRoutes).
+const SEARCH_DEFAULT_ROUTE = Object.freeze({ provider: 'default', model: 'default' });
+const isSearchDefaultRoute = (route) =>
+  String(route?.provider || '').toLowerCase() === 'default'
+  && String(route?.model || '').toLowerCase() === 'default';
 
 const SLASH_COMMANDS = [
   { name: 'clear', usage: '/clear', aliases: ['new'], aliasUsage: ['new'], description: 'Start a fresh chat' },
@@ -97,10 +119,13 @@ const SLASH_COMMANDS = [
   { name: 'hooks', usage: '/hooks', description: 'Manage before-tool hook rules and events' },
   { name: 'providers', usage: '/providers', description: 'Manage auth, API keys, OAuth, and local endpoints' },
   { name: 'channels', usage: '/channels', description: 'Manage Discord, channels, schedules, webhooks' },
+  { name: 'remote', usage: '/remote', description: 'Toggle Discord remote mode for this session' },
   { name: 'schedules', usage: '/schedules', description: 'Manage schedules' },
   { name: 'webhooks', usage: '/webhooks', description: 'Manage inbound webhooks' },
   { name: 'settings', usage: '/setting', aliases: ['setting', 'config'], aliasUsage: ['settings', 'config'], showAliasUsage: false, description: 'Open runtime settings' },
   { name: 'profile', usage: '/profile', description: 'Set your title and response language' },
+  { name: 'update', usage: '/update', description: 'Check version and update mixdog' },
+  { name: 'voice', usage: '/voice', description: 'Toggle voice input (Ctrl+Space to record)' },
   { name: 'quit', usage: '/quit', aliases: ['exit', 'q'], aliasUsage: ['exit', 'q'], description: 'Quit the TUI' },
 ];
 
@@ -174,6 +199,42 @@ function terminalSize(stdout) {
   };
 }
 
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+
+function wrappedTextRows(value, width) {
+  const w = Math.max(1, Math.floor(Number(width) || 1));
+  let row = 0;
+  let col = 0;
+  for (const { segment } of graphemeSegmenter.segment(String(value ?? ''))) {
+    if (segment === '\n') {
+      row += 1;
+      col = 0;
+      continue;
+    }
+    const segmentWidth = stringWidth(segment);
+    if (segmentWidth === 0) continue;
+    if (col > 0 && col + segmentWidth > w) {
+      row += 1;
+      col = 0;
+    }
+    col += segmentWidth;
+    if (col >= w) {
+      row += Math.floor(col / w);
+      col %= w;
+    }
+  }
+  return row + 1;
+}
+
+function promptContentRows(value, contentColumns) {
+  // PromptInput appends a blank trailing cell when the caret is at end-of-input
+  // so the native cursor always has a rendered cell. App does not own the cursor
+  // offset, so reserve for the worst common case: caret at the end. This can
+  // over-reserve by one row at exact wrap boundaries, but never under-reserves
+  // and therefore prevents transcript rows from bleeding into the prompt box.
+  return wrappedTextRows(`${String(value ?? '')} `, contentColumns);
+}
+
 function clean(value) {
   return String(value ?? '').trim();
 }
@@ -195,14 +256,6 @@ function modelSwitchNotice() {
   return 'Model updated · new sessions';
 }
 
-function systemShellDescription(shell = {}) {
-  const command = clean(shell.command);
-  if (command) return `${command} · config`;
-  const effective = clean(shell.effective);
-  if (effective) return `${effective} · ${shell.source || 'env'}`;
-  return 'auto';
-}
-
 function compactJson(value, max = 180) {
   let text = '';
   try {
@@ -251,14 +304,6 @@ function providerKindLabel(provider = {}) {
   return 'API key';
 }
 
-function summarizeTags(tags, limit = 3) {
-  const values = [...new Set((Array.isArray(tags) ? tags : [])
-    .map((tag) => clean(tag))
-    .filter(Boolean))];
-  if (values.length <= limit) return values.join(', ');
-  return `${values.slice(0, limit).join(', ')}, +${values.length - limit}`;
-}
-
 function formatSessionUpdatedAt(value) {
   const n = Number(value);
   if (!Number.isFinite(n) || n <= 0) return '--:--';
@@ -278,50 +323,6 @@ function formatSessionMessageCount(count) {
   return `${Number.isFinite(n) ? Math.max(0, Math.round(n)) : 0} msg${n === 1 ? '' : 's'}`;
 }
 
-function parseAgentControl(text) {
-  const parts = String(text || '').trim().split(/\s+/).filter(Boolean);
-  const action = (parts[0] || '').toLowerCase();
-  if (!['spawn', 'send', 'list', 'status', 'read', 'cleanup', 'cancel', 'close'].includes(action)) return null;
-  const value = parts[1] || '';
-  if (action === 'list' || action === 'cleanup') return { type: action };
-  if (action === 'spawn') {
-    const agent = value;
-    if (!agent) return { error: 'usage: /agent spawn <agent> <prompt>' };
-    const parsed = parseAgentFreeform(parts.slice(2));
-    if (!parsed.message) return { error: 'usage: /agent spawn <agent> <prompt>' };
-    return { type: 'spawn', agent, ...parsed };
-  }
-  if (action === 'send') {
-    if (!value) return { error: 'usage: /agent send <target> <message>' };
-    const parsed = parseAgentFreeform(parts.slice(2));
-    if (!parsed.message) return { error: 'usage: /agent send <target> <message>' };
-    return value.startsWith('sess_')
-      ? { type: 'send', sessionId: value, ...parsed }
-      : { type: 'send', tag: value, ...parsed };
-  }
-  if (!value) return { error: `usage: /agent ${action} <target>` };
-  if (action === 'status' || action === 'read') return { type: action, task_id: value };
-  if (value.startsWith('task_')) return { type: action, task_id: value };
-  if (value.startsWith('sess_')) return { type: action, sessionId: value };
-  return { type: action, tag: value };
-}
-
-function parseAgentFreeform(parts) {
-  const out = {};
-  let i = 0;
-  for (; i < parts.length; i += 1) {
-    const token = parts[i];
-    const kv = /^([a-zA-Z][\w-]*)=(.+)$/.exec(token);
-    if (kv && ['tag', 'preset', 'provider', 'model', 'effort', 'cwd'].includes(kv[1])) {
-      out[kv[1]] = kv[2];
-      continue;
-    }
-    break;
-  }
-  out.message = parts.slice(i).join(' ').trim();
-  return out;
-}
-
 function parseHookRuleInput(text) {
   const parts = String(text || '').split('|').map((part) => part.trim());
   const [tool, actionRaw, match, reason, patchText] = parts;
@@ -352,7 +353,7 @@ function parseMcpServerInput(text) {
   const parts = String(text || '').split('|').map((part) => part.trim());
   const [name, commandOrUrl, argsText = '', cwd = ''] = parts;
   if (!name || !commandOrUrl) return { error: 'usage: name | command-or-url | args(optional) | cwd(optional)' };
-  if (/^https?:\/\//i.test(commandOrUrl)) return { server: { name, url: commandOrUrl } };
+  if (/^(?:https?|wss?):\/\//i.test(commandOrUrl)) return { server: { name, url: commandOrUrl } };
   return {
     server: {
       name,
@@ -448,6 +449,68 @@ function centerLine(value, columns, reserve = 0) {
   return `${' '.repeat(pad)}${text}`;
 }
 
+const WELCOME_PROMPT_HINTS = [
+  'Tip: /setting · Tune the runtime before the run.',
+  'Tip: /model · Pick the right brain for the job.',
+  'Tip: /workflow · Change how work gets routed.',
+  'Tip: Ctrl+O · Expand tool output when you need details.',
+  'Tip: PageUp/PageDown · Scroll the transcript.',
+  'Tip: Esc · Close panels or interrupt work.',
+  'Tip: /usage · Check quota before a long run.',
+  'Tip: /agents · See who can help.',
+  'Tip: /theme · Change the terminal mood.',
+  'Tip: /search · Set web search routing.',
+  'Paste an error. I’ll trace it.',
+  'Tell me the goal. I’ll handle the steps.',
+  'Start with a task, a bug, or a wild idea.',
+  'Good fixes start with a repro.',
+  'Ask for a plan, then let the agents work.',
+  'Small prompt, sharp result.',
+  'Drop in a file path and ask what changed.',
+  'Describe the outcome, not just the command.',
+  'Ready when you are.',
+  'One clear goal beats ten vague tasks.',
+];
+
+const CONDITIONAL_WELCOME_PROMPT_HINTS = {
+  noProvider: 'Tip: /providers · Connect a provider before your first turn.',
+  noModel: 'Tip: /model · Choose a model before your first turn.',
+  soloWorkflow: 'Tip: /workflow · Switch from Solo when you want agents.',
+  searchDefaultUnsupported: 'Tip: /search · Choose a native search model for this main model.',
+  error: 'Tip: /doctor · Check setup health. (coming soon)',
+};
+
+function randomWelcomePromptHint() {
+  const index = Math.floor(Math.random() * WELCOME_PROMPT_HINTS.length);
+  return WELCOME_PROMPT_HINTS[index] || WELCOME_PROMPT_HINTS[0] || '';
+}
+
+function providerSetupHasUsableProvider(setup = {}) {
+  const rows = [
+    ...(Array.isArray(setup.api) ? setup.api : []),
+    ...(Array.isArray(setup.oauth) ? setup.oauth : []),
+    ...(Array.isArray(setup.local) ? setup.local : []),
+  ];
+  return rows.some((row) => (
+    row?.authenticated === true
+    || row?.enabled === true
+    || row?.stored === true
+    || row?.env === true
+    || row?.detected === true
+  ));
+}
+
+function activeWorkflowSummaryForStore(store, workflow = {}) {
+  try {
+    const workflows = store.listWorkflows?.() || [];
+    return workflows.find((item) => item.active)
+      || workflows.find((item) => item.id === workflow?.id)
+      || null;
+  } catch {
+    return null;
+  }
+}
+
 function promptStatusColor(tone) {
   if (tone === 'error') return theme.error;
   if (tone === 'warn' || tone === 'cancel') return theme.warning;
@@ -542,25 +605,34 @@ function isAgentResponseResultText(text) {
 function ToolHookDenialCard({ item, columns = 80 }) {
   const { label, summary } = formatToolSurface(item.name, item.args);
   const detail = formatHookDenialDetail(toolItemResultText(item));
-  const summaryText = summary ? ` (${summary})` : '';
+  const safeLabel = stripAnsi(String(label || '')).replace(/[\u0000-\u001F\u007F]/g, ' ').replace(/\s+/g, ' ').trim();
+  const safeSummary = stripAnsi(String(summary || '')).replace(/[\u0000-\u001F\u007F]/g, ' ').replace(/\s+/g, ' ').trim();
+  const safeDetail = stripAnsi(String(detail || '')).replace(/[\u0000-\u001F\u007F]/g, ' ').replace(/\s+/g, ' ').trim();
+  const summaryText = safeSummary ? ` (${safeSummary})` : '';
+  const rowWidth = Math.max(1, Number(columns || 80));
+  const detailWidth = Math.max(1, rowWidth - stringWidth(RESULT_GUTTER));
   return (
-    <Box flexDirection="column" marginTop={1}>
-      <Box flexDirection="row">
+    <Box flexDirection="column" marginTop={1} width={rowWidth} overflow="hidden">
+      <Box flexDirection="row" width={rowWidth} overflow="hidden">
         <Box flexShrink={0} minWidth={2}>
           <Text color={theme.error}>{TURN_MARKER}</Text>
         </Box>
-        <Text wrap="truncate">
-          <Text bold color={theme.text}>{label}</Text>
-          {summaryText ? <Text color={theme.text}>{summaryText}</Text> : null}
-          <Text color={theme.error}> · Denied</Text>
-        </Text>
+        <Box flexGrow={1} flexShrink={1} overflow="hidden" minWidth={0}>
+          <Text wrap="truncate">
+            <Text bold color={theme.text}>{safeLabel}</Text>
+            {summaryText ? <Text color={theme.text}>{summaryText}</Text> : null}
+            <Text color={theme.error}> · Denied</Text>
+          </Text>
+        </Box>
       </Box>
-      {detail ? (
-        <Box flexDirection="row">
-          <Box flexShrink={0}>
+      {safeDetail ? (
+        <Box flexDirection="row" width={rowWidth} overflow="hidden">
+          <Box flexShrink={0} width={stringWidth(RESULT_GUTTER)}>
             <Text color={theme.subtle}>{RESULT_GUTTER}</Text>
           </Box>
-          <Text color={theme.error} wrap="truncate">{detail}</Text>
+          <Box flexShrink={0} width={detailWidth} overflow="hidden">
+            <Text color={theme.error} wrap="truncate">{safeDetail}</Text>
+          </Box>
         </Box>
       ) : null}
     </Box>
@@ -573,21 +645,46 @@ function ToolHookDenialCard({ item, columns = 80 }) {
 // epoch through Item → AssistantMessage/UserMessage/ToolExecution breaks
 // React.memo's shallow equality on a theme change without a broad refactor.
 const Item = React.memo(function Item({ item, prevKind, columns, toolOutputExpanded, rightMessage = '', rightTone = 'info', rightMessageWidth = 24, themeEpoch = 0 }) {
+  const hintOnTurnDoneRow = item.kind === 'turndone' || item.kind === 'statusdone';
+  let node = null;
   switch (item.kind) {
-    case 'user': return <UserMessage text={item.text} attached={prevKind === 'user'} columns={columns} themeEpoch={themeEpoch} />;
-    case 'assistant': return <AssistantMessage text={item.text} streaming={item.streaming} columns={columns} themeEpoch={themeEpoch} />;
+    case 'user':
+      node = <UserMessage text={item.text} attached={prevKind === 'user'} columns={columns} themeEpoch={themeEpoch} />;
+      break;
+    case 'assistant':
+      node = <AssistantMessage text={item.text} streaming={item.streaming} columns={columns} themeEpoch={themeEpoch} assistantId={item.id} />;
+      break;
     case 'tool': {
       if (shouldSuppressFullyFailedToolItem(item)) return null;
       if (isHookApprovalDenialToolItem(item)) {
-        return <ToolHookDenialCard item={item} columns={columns} />;
+        node = <ToolHookDenialCard item={item} columns={columns} />;
+        break;
       }
-      return <ToolExecution name={item.name} args={item.args} result={item.result} rawResult={item.rawResult} isError={item.isError} errorCount={item.errorCount} expanded={toolOutputExpanded || item.expanded} globalExpanded={toolOutputExpanded} columns={columns} attached={false} count={item.count} completedCount={item.completedCount} startedAt={item.startedAt} completedAt={item.completedAt} aggregate={item.aggregate} categories={item.categories} headerFinalized={item.headerFinalized} deferredDisplayReady={item.deferredDisplayReady} themeEpoch={themeEpoch} />;
+      node = <ToolExecution name={item.name} args={item.args} result={item.result} rawResult={item.rawResult} isError={item.isError} errorCount={item.errorCount} expanded={toolOutputExpanded || item.expanded} columns={columns} attached={false} count={item.count} completedCount={item.completedCount} startedAt={item.startedAt} completedAt={item.completedAt} aggregate={item.aggregate} categories={item.categories} headerFinalized={item.headerFinalized} deferredDisplayReady={item.deferredDisplayReady} themeEpoch={themeEpoch} />;
+      break;
     }
-    case 'notice': return <NoticeMessage text={item.text} tone={item.tone} columns={columns} />;
-    case 'turndone': return <TurnDone elapsedMs={item.elapsedMs} status={item.status} outputTokens={item.outputTokens} thinkingElapsedMs={item.thinkingElapsedMs} verb={item.verb} rightMessage={rightMessage} rightTone={rightTone} rightMessageWidth={rightMessageWidth} />;
-    case 'statusdone': return <StatusDone label={item.label} detail={item.detail} rightMessage={rightMessage} rightTone={rightTone} rightMessageWidth={rightMessageWidth} />;
-    default: return null;
+    case 'notice':
+      node = <NoticeMessage text={item.text} tone={item.tone} columns={columns} />;
+      break;
+    case 'turndone':
+      node = <TurnDone elapsedMs={item.elapsedMs} status={item.status} outputTokens={item.outputTokens} thinkingElapsedMs={item.thinkingElapsedMs} verb={item.verb} rightMessage={rightMessage} rightTone={rightTone} rightMessageWidth={rightMessageWidth} />;
+      break;
+    case 'statusdone':
+      node = <StatusDone label={item.label} detail={item.detail} rightMessage={rightMessage} rightTone={rightTone} rightMessageWidth={rightMessageWidth} />;
+      break;
+    default:
+      return null;
   }
+  if (!node || hintOnTurnDoneRow || !rightMessage) return node;
+  return (
+    <ItemRightHintOverprint
+      rightMessage={rightMessage}
+      rightTone={rightTone}
+      rightMessageWidth={rightMessageWidth}
+    >
+      {node}
+    </ItemRightHintOverprint>
+  );
 });
 
 function positiveIntEnv(name, fallback) {
@@ -665,6 +762,15 @@ function shiftSelectionRectY(rect, deltaY) {
   return { ...rect, y1: rect.y1 + dy, y2: rect.y2 + dy };
 }
 
+// Reading-order compare (row then col): -1 if a<b, 1 if a>b, 0 equal. Shared by
+// buildSpanRect (word/line drag-extension). Module scope so both the mouse
+// handler and the auto-scroll path can reach it.
+function comparePoints(a, b) {
+  if (a.y !== b.y) return a.y < b.y ? -1 : 1;
+  if (a.x !== b.x) return a.x < b.x ? -1 : 1;
+  return 0;
+}
+
 // Count how many terminal rows ONE logical line (no '\n') occupies once ink
 // word-wraps it. ink/Yoga break on whitespace (wrap-ansi wordWrap), NOT on a
 // hard column count: a word that does not fit the remaining space is pushed
@@ -676,14 +782,14 @@ function shiftSelectionRectY(rect, deltaY) {
 // word-wrap so the row estimate is never lower than what ink actually renders.
 function wrappedLineRows(line, width) {
   const text = String(line);
-  const full = stringWidth(text);
+  const full = displayWidth(text);
   if (full === 0) return 1;
   if (full <= width) return 1;
   let rows = 1;
   let col = 0;
   for (const token of text.split(/(\s+)/)) {
     if (!token) continue;
-    const tw = stringWidth(token);
+    const tw = displayWidth(token);
     if (tw === 0) continue;
     if (tw > width) {
       // Over-long unbreakable token: ink hard-splits it across rows.
@@ -724,38 +830,6 @@ function estimateWrappedRows(text, columns, reserve = 4) {
 // equals MarkdownTable's real line count (horizontal box OR vertical fallback)
 // with zero drift, including on win32 where stdout.columns ≠ frameColumns.
 //
-// StreamingMarkdown splits the body into stable+unstable <Markdown> children
-// under one gap={1} parent; the boundary gap exactly replaces the natural
-// segment-boundary gap, so measuring the whole text in one pass yields the same
-// total row count (no streaming-specific correction needed).
-function measureMarkdownRenderedRows(text, columns) {
-  const value = String(text ?? '');
-  if (!value) return 1;
-  const bodyWidth = assistantBodyWidth(columns);
-  let segments;
-  try {
-    segments = renderTokenAnsiSegments(value, { width: bodyWidth });
-  } catch {
-    // Never throw into the scroll math — fall back to the raw wrapped count.
-    return Math.max(1, estimateWrappedRows(value, columns, 3));
-  }
-  if (!segments.length) return 1;
-  let rows = 0;
-  for (const seg of segments) {
-    if (seg.type === 'table') {
-      rows += Math.max(1, measureMarkdownTableRows(seg.token, bodyWidth));
-      continue;
-    }
-    const plain = stripAnsi(String(seg.ansi ?? ''));
-    for (const line of plain.split('\n')) {
-      rows += wrappedLineRows(line, bodyWidth);
-    }
-  }
-  // Markdown.jsx wraps the segments in <Box gap={1}>: one blank row per boundary.
-  rows += segments.length - 1;
-  return Math.max(1, rows);
-}
-
 const BACKGROUND_TASK_TOOL_NAMES = new Set(['explore', 'search', 'shell', 'bash', 'bash_session', 'shell_command', 'task']);
 
 function isBackgroundTaskToolName(normalizedName) {
@@ -817,6 +891,14 @@ function toolItemPendingForRows(item) {
 }
 
 // Mirror ToolExecution displayedResultText for row estimates (agent brief, etc.).
+const LEADING_STATUS_MARKER_LINE_RE = /^\[status:\s*[^\]]*\]\s*$/i;
+
+function stripLeadingStatusMarkerFromTextForRows(text) {
+  const lines = String(text || '').split('\n');
+  if (lines.length > 0 && LEADING_STATUS_MARKER_LINE_RE.test(String(lines[0] ?? '').trim())) lines.shift();
+  return lines.join('\n');
+}
+
 function toolDisplayedResultTextForRows(item) {
   const rt = item?.result == null ? '' : String(item.result).replace(/\s+$/, '');
   const bgArgs = backgroundArgsForRows(item?.args);
@@ -825,9 +907,11 @@ function toolDisplayedResultTextForRows(item) {
   const normalizedName = String(normalizeToolName(item?.name) || '').toLowerCase();
   if (!toolItemPendingForRows(item) && isBackgroundTaskToolName(normalizedName)) {
     const meta = parseBackgroundTaskResultForRows(rt);
-    if (meta?.hasResponse && String(meta.body || '').trim()) return String(meta.body);
+    if (meta?.hasResponse && String(meta.body || '').trim()) {
+      return stripLeadingStatusMarkerFromTextForRows(String(meta.body));
+    }
   }
-  return errorOnlyResult ? '' : (rt || '');
+  return stripLeadingStatusMarkerFromTextForRows(errorOnlyResult ? '' : (rt || ''));
 }
 
 function toolHasDisplayResultForRows(item) {
@@ -849,7 +933,7 @@ function toolExpandedRawTextForRows(item, rawRt) {
   if (item?.aggregate) return rawRt;
   const hasDisplayResult = toolHasDisplayResultForRows(item);
   if (hasDisplayResult) return toolDisplayedResultTextForRows(item);
-  return rawRt;
+  return stripLeadingStatusMarkerFromTextForRows(rawRt || '');
 }
 
 function toolHeaderFailureOnlyForRows(item, normalizedName, hasDisplayResult) {
@@ -919,11 +1003,12 @@ function estimateTranscriptItemRows(item, columns, toolOutputExpanded) {
     case 'user':
       return 1 + estimateWrappedRows(item.text, columns, 4);
     case 'assistant':
-      // marginTop={1} (AssistantMessage <Box>) + the exact rendered body height.
-      // measureMarkdownRenderedRows mirrors the <Markdown> segment/gap/table
-      // layout at the real body width (columns-3), so the reserved height equals
-      // what ink draws — no phantom blank band (over) and no top-clip (under).
-      return 1 + measureMarkdownRenderedRows(item.text, columns);
+      // marginTop={1} (AssistantMessage <Box>) + rendered body height.
+      // Streaming uses measureStreamingMarkdownRenderedRows (shared layout with
+      // StreamingMarkdown); settled assistant uses measureMarkdownRenderedRows.
+      return 1 + (item.streaming
+        ? measureStreamingMarkdownRenderedRows(item.text, columns, item.id)
+        : measureMarkdownRenderedRows(item.text, columns));
     case 'tool': {
       const TOOL_MARGIN_TOP = 1;
       if (shouldSuppressFullyFailedToolItem(item)) return 0;
@@ -1270,7 +1355,7 @@ function measuredTranscriptRows(item, columns, toolOutputExpanded) {
 const STREAMING_ROW_QUANTUM = 1;
 
 function assistantTextForStreamingRowEstimate(text) {
-  return String(text ?? '').replace(/^\n+|\n+$/g, '');
+  return streamingLayoutText(text);
 }
 
 function streamingEstimateRows(item, columns, toolOutputExpanded) {
@@ -1465,9 +1550,13 @@ function transcriptRenderWindow(items, { scrollOffset = 0, viewportHeight = 24,
   };
 }
 
-export function App({ store, initialStatusLine = '' }) {
+export function App({ store, initialStatusLine = '', forceOnboarding = false }) {
   const state = useEngine(store);
   const [toolOutputExpanded, setToolOutputExpanded] = useState(false);
+  // True for the entire first-run onboarding wizard (every step + nested depth)
+  // so the welcome banner stays reserved and the layout doesn't jump when the
+  // step pickers mount. Cleared on finish/cancel.
+  const [onboardingActive, setOnboardingActive] = useState(false);
   const { exit } = useApp();
   // internal_eventEmitter is ink's parsed-input bus. ink 7 consumes stdin via
   // the 'readable' event + stdin.read() (see ink's App.js), draining the buffer
@@ -1484,6 +1573,13 @@ export function App({ store, initialStatusLine = '' }) {
   const [tuiReady, setTuiReady] = useState(false);
   const exitRequestedRef = useRef(false);
   const [resizeState, setResizeState] = useState(() => ({ ...terminalSize(stdout), epoch: 0 }));
+  // Windows Terminal/conhost scrolls the alt-screen (auto-wrap/DECAWM) when the
+  // bottom-right cell is written. WT_SESSION is also set when the UI runs under
+  // a Unix-ish shell hosted by Windows Terminal, where process.platform is not
+  // necessarily win32 but the terminal behavior is still Windows-like.
+  const windowsLikeTerminal = process.platform === 'win32' || Boolean(process.env.WT_SESSION);
+  const rightSafetyColumns = windowsLikeTerminal ? 1 : 0;
+  const frameColumns = Math.max(1, resizeState.columns - rightSafetyColumns);
   // scrollOffset = how many transcript ROWS we've scrolled UP from the bottom
   // (0 = pinned to the latest, showing the newest content). Mouse wheel adjusts
   // it; accepted prompts only arm bottom-follow; the snap happens when the
@@ -1492,6 +1588,7 @@ export function App({ store, initialStatusLine = '' }) {
   const scrollPositionRef = useRef(0);
   const scrollTargetRef = useRef(0);
   const maxScrollRowsRef = useRef(0);
+  const transcriptBottomSlackRowsRef = useRef(0);
   const scrollAnimationRef = useRef(null);
   const transcriptTotalRowsRef = useRef(0);
   const preservedScrollDeltaRef = useRef(0);
@@ -1667,6 +1764,8 @@ export function App({ store, initialStatusLine = '' }) {
   const toolApproval = state.toolApproval || null;
   const [promptDraft, setPromptDraft] = useState('');
   const [promptDraftOverride, setPromptDraftOverride] = useState(null);
+  const promptLayoutValueRef = useRef('');
+  const [, setPromptLayoutRows] = useState(1);
   const [, setPastedImages] = useState({});
   const pastedImagesRef = useRef({});
   const nextPastedImageIdRef = useRef(1);
@@ -1683,20 +1782,40 @@ export function App({ store, initialStatusLine = '' }) {
   const promptHistoryDraftChangeRef = useRef(false);
   const [promptHint, setPromptHint] = useState('');
   const [promptHintTone, setPromptHintTone] = useState('info');
+  const [welcomePromptHintDismissed, setWelcomePromptHintDismissed] = useState(false);
+  const [conditionalWelcomePromptHint, setConditionalWelcomePromptHint] = useState('');
+  const welcomePromptHintRef = useRef(null);
+  if (welcomePromptHintRef.current === null) {
+    welcomePromptHintRef.current = randomWelcomePromptHint();
+  }
+  const dismissWelcomePromptHint = useCallback(() => {
+    setWelcomePromptHintDismissed((dismissed) => dismissed || true);
+  }, []);
+  const toastErrorSignature = useMemo(() => (
+    (state.toasts || [])
+      .filter((toast) => toast?.tone === 'error')
+      .map((toast) => `${toast.id || ''}:${toast.text || ''}`)
+      .join('|')
+  ), [state.toasts]);
   const [slashIndex, setSlashIndex] = useState(0);
   const [slashDismissedFor, setSlashDismissedFor] = useState('');
   const [disabledSkills, setDisabledSkills] = useState(() => new Set());
   const slashPaletteRef = useRef({ open: false, count: 0 });
   const scrollFocusRef = useRef({});
   const onboardingStartedRef = useRef(false);
-  const onboardingRef = useRef({ defaultRoute: null, workflowRoutes: {}, providerModels: [] });
+  const onboardingRef = useRef({ defaultRoute: null, searchRoute: null, agentRoutes: {}, agents: [], providerModels: [] });
   const providerModelsCacheRef = useRef({ models: null, at: 0 });
   const searchModelsCacheRef = useRef({ models: null, at: 0 });
   const modelPickerRequestRef = useRef(0);
+  // Generation guard for the Step 1 background prefetch: bumped on every
+  // provider-scope cache clear (e.g. after auth) so a stale in-flight
+  // listProviderModels() cannot repopulate the ref after invalidation.
+  const onboardingPrefetchSeqRef = useRef(0);
   const clearModelCaches = useCallback((scope = 'all') => {
     if (scope === 'all' || scope === 'provider') {
       providerModelsCacheRef.current = { models: null, at: 0 };
       onboardingRef.current.providerModels = [];
+      onboardingPrefetchSeqRef.current += 1;
     }
     if (scope === 'all' || scope === 'search') {
       searchModelsCacheRef.current = { models: null, at: 0 };
@@ -1710,7 +1829,11 @@ export function App({ store, initialStatusLine = '' }) {
   // region: which surface the in-progress (or last) selection belongs to —
   // 'transcript' | 'status' (both ink-grid) | 'prompt' (PromptInput's own engine)
   // | null. Press decides it; motion/release stay in that region.
-  const dragRef = useRef({ anchor: null, anchorScroll: 0, last: null, active: false, rect: null, region: null });
+  // anchorSpan: for word/line multi-click selections, the initial word/line
+  // bounds ({ lo:{x,y}, hi:{x,y}, kind:'word'|'line' }) so a subsequent drag
+  // extends the selection whole-word/whole-line from that span (see selection.ts
+  // extendSelection). Null ⇔ ordinary char-drag selection.
+  const dragRef = useRef({ anchor: null, anchorScroll: 0, last: null, active: false, rect: null, region: null, anchorSpan: null });
   const selectionPaintRef = useRef({ t: 0, rect: null, pending: null, timer: null });
   const transcriptViewportRef = useRef({ top: 0, bottom: 0 });
   // [mixdog] Latest terminal row count + the statusline band (bottom rows),
@@ -1719,12 +1842,85 @@ export function App({ store, initialStatusLine = '' }) {
   // region. STATUSLINE_ROWS mirrors the layout reserve below.
   const frameRowsRef = useRef(24);
   const STATUSLINE_BAND_ROWS = 3;
+  const promptContentColumns = Math.max(1, frameColumns - 4);
+  const syncPromptLayoutRows = useCallback((value) => {
+    const text = String(value ?? '');
+    promptLayoutValueRef.current = text;
+    const nextRows = promptContentRows(text, promptContentColumns);
+    setPromptLayoutRows((prev) => (prev === nextRows ? prev : nextRows));
+  }, [promptContentColumns]);
+  useEffect(() => {
+    syncPromptLayoutRows(promptLayoutValueRef.current);
+  }, [syncPromptLayoutRows]);
+  useEffect(() => {
+    let alive = true;
+    const refreshConditionalWelcomeHint = async () => {
+      let next = '';
+      try {
+        const setup = await store.getProviderSetup?.();
+        if (setup && !providerSetupHasUsableProvider(setup)) {
+          next = CONDITIONAL_WELCOME_PROMPT_HINTS.noProvider;
+        }
+      } catch {
+        // If provider setup probing fails, let the generic/error tip path decide.
+      }
+      if (!next) {
+        const activeProvider = String(state.provider || '').trim();
+        const activeModel = String(state.model || '').trim();
+        if (!activeProvider || !activeModel) {
+          next = CONDITIONAL_WELCOME_PROMPT_HINTS.noModel;
+        } else {
+          try {
+            const models = await Promise.resolve(store.listProviderModels?.({ quick: true }) || []);
+            if (Array.isArray(models) && models.length === 0) {
+              next = CONDITIONAL_WELCOME_PROMPT_HINTS.noModel;
+            }
+          } catch {
+            // Model probing is advisory only; avoid replacing the random hint on failure.
+          }
+        }
+      }
+      const activeWorkflow = activeWorkflowSummaryForStore(store, state.workflow || {});
+      if (!next && String(activeWorkflow?.id || state.workflow?.id || '').toLowerCase() === 'solo') {
+        next = CONDITIONAL_WELCOME_PROMPT_HINTS.soloWorkflow;
+      }
+      if (!next) {
+        const searchRoute = store.getSearchRoute?.() || null;
+        const searchProvider = String(searchRoute?.provider || '').trim();
+        const searchModel = String(searchRoute?.model || '').trim();
+        const defaultSearchRoute = searchProvider.toLowerCase() === 'default' && searchModel.toLowerCase() === 'default';
+        if (defaultSearchRoute) {
+          try {
+            const models = await Promise.resolve(store.listProviderModels?.({ quick: true }) || []);
+            const current = Array.isArray(models)
+              ? models.find((model) => model?.provider === state.provider && model?.id === state.model)
+              : null;
+            if (current && current.supportsWebSearch !== true) {
+              next = CONDITIONAL_WELCOME_PROMPT_HINTS.searchDefaultUnsupported;
+            }
+          } catch {
+            // Search default probing is advisory only.
+          }
+        }
+      }
+      if (!next && toastErrorSignature) {
+        next = CONDITIONAL_WELCOME_PROMPT_HINTS.error;
+      }
+      if (alive) setConditionalWelcomePromptHint((prev) => (prev === next ? prev : next));
+    };
+    void refreshConditionalWelcomeHint();
+    return () => { alive = false; };
+  }, [store, state.provider, state.model, state.workflow?.id, toastErrorSignature]);
   const selectionLayoutRef = useRef(null);
   const selectionTextRef = useRef('');
   const selectionTextTimerRef = useRef(null);
   // lastClickRef tracks the previous left-press cell + time so the mouse handler
-  // can detect a double-click (same cell within 400ms) for word selection.
-  const lastClickRef = useRef({ x: -1, y: -1, t: 0 });
+  // can detect a double-click (same cell within 500ms) for word selection.
+  // count = consecutive qualifying presses on the same cell (1=single,
+  // 2=double/word, 3=triple/line). A 4th qualifying press restarts the
+  // sequence at 1 (claude-code cycles; simplest reset). Any non-qualifying
+  // press resets to a fresh single.
+  const lastClickRef = useRef({ x: -1, y: -1, t: 0, count: 0 });
 
   const showSelectionCopyHint = useCallback((text, tone = 'plain') => {
     if (promptHintTimerRef.current) clearTimeout(promptHintTimerRef.current);
@@ -1821,6 +2017,90 @@ export function App({ store, initialStatusLine = '' }) {
     }, 2200);
   }, []);
 
+  // Voice recorder status hint — reuses the SAME promptHint state as
+  // showPromptHint/clearPromptHint, but bypasses their 2200ms auto-clear
+  // timer: '● REC' / '… transcribing' must stay visible for the ENTIRE
+  // recording/transcribing duration (which can run well past 2.2s), not
+  // vanish on a fixed timer. Also cancels any pending showPromptHint timer
+  // so a stale auto-clear can never stomp the live recording status.
+  const setVoiceStatusHint = useCallback((text, tone = 'info') => {
+    if (promptHintTimerRef.current) {
+      clearTimeout(promptHintTimerRef.current);
+      promptHintTimerRef.current = null;
+    }
+    promptHintActiveRef.current = !!text;
+    setPromptHint(String(text || ''));
+    setPromptHintTone(tone);
+  }, []);
+
+  // Ctrl+Space handler wired to PromptInput's onVoiceToggle. Dispatches on the
+  // recorder's CURRENT state (idle/recording/transcribing) — see
+  // src/tui/lib/voice-recorder.mjs for the state machine itself.
+  const handleVoiceToggle = useCallback(async () => {
+    if (!isVoiceEnabled()) {
+      store.pushNotice('Voice is off — run /voice to turn it on', 'warn');
+      return;
+    }
+    const recState = getRecorderState();
+    if (recState === 'transcribing') {
+      store.pushNotice('Voice: already transcribing…', 'info');
+      return;
+    }
+    if (recState === 'recording') {
+      setVoiceStatusHint('… transcribing', 'info');
+      let result;
+      try {
+        result = await stopRecording();
+      } catch (e) {
+        result = { ok: false, reason: e?.message || String(e) };
+      }
+      setVoiceStatusHint('', 'info');
+      if (!result) return; // race: recorder was no longer RECORDING
+      if (!result.ok) {
+        store.pushNotice(`Voice: ${result.reason || 'transcription failed'}`, 'error');
+        return;
+      }
+      const text = String(result.text || '').trim();
+      if (!text) {
+        store.pushNotice('Voice: no speech detected', 'warn');
+        return;
+      }
+      // End-of-draft insertion via promptDraftOverride (approved design —
+      // no cursor-position insert; see gamerscroll skill's out-of-scope note
+      // on PromptInput's imperative surface).
+      // Med-4: promptValueRef.current is read HERE — after `await
+      // stopRecording()` has already resolved — not captured earlier before
+      // the await. PromptInput keeps valueRef.current live on every
+      // keystroke (commitDraft), so this always reflects whatever the user
+      // typed during the recording+transcribe window; nothing typed in that
+      // gap is overwritten.
+      const current = promptValueRef.current || '';
+      const next = current ? `${current}${/\s$/.test(current) ? '' : ' '}${text}` : text;
+      syncPromptLayoutRows(next);
+      setPromptDraftOverride({ id: Date.now(), value: next });
+      return;
+    }
+    // idle -> recording
+    let result;
+    try {
+      result = await startRecording();
+    } catch (e) {
+      result = { ok: false, reason: e?.message || String(e) };
+    }
+    if (!result?.ok) {
+      store.pushNotice(`Voice: ${result?.reason || 'failed to start recording'}`, 'error');
+      return;
+    }
+    setVoiceStatusHint('● REC', 'error');
+  }, [store, setVoiceStatusHint, syncPromptLayoutRows]);
+
+  // Best-effort recorder teardown on unmount (component-level cleanup;
+  // index.jsx's runTui() also disposes via store.dispose on exit/signal, but
+  // that path doesn't know about the TUI-local recorder singleton).
+  useEffect(() => () => {
+    disposeRecorder();
+  }, []);
+
   const installPastedImages = useCallback((images, { merge = true } = {}) => {
     if (!images || typeof images !== 'object' || Object.keys(images).length === 0) return;
     const next = merge ? { ...pastedImagesRef.current, ...images } : { ...images };
@@ -1944,6 +2224,8 @@ export function App({ store, initialStatusLine = '' }) {
     // long transcript jump to the bottom, then jump again when the new row is
     // appended. Keep the current viewport stable and let the row-delta effect
     // perform the single bottom-follow when the transcript actually grows.
+    transcriptAnchorRef.current = null;
+    transcriptAnchorDirtyRef.current = false;
     followingRef.current = true;
     stopSmoothScroll();
   }, [stopSmoothScroll]);
@@ -1980,6 +2262,8 @@ export function App({ store, initialStatusLine = '' }) {
       ...rect,
       clipY1: clip.y1,
       clipY2: Math.max(clip.y1, clip.y2),
+      selectionForeground: theme.selectionHighlightText || theme.selectionText,
+      selectionBackground: theme.selectionHighlightBackground || theme.selectionBackground,
     };
     if (options.captureText === false) clipped.captureText = false;
     return clipped;
@@ -2055,6 +2339,124 @@ export function App({ store, initialStatusLine = '' }) {
     };
   }, []);
 
+  // Port of selection.ts extendSelection onto the linear-rect model, hoisted to
+  // component scope so BOTH the mouse handler (motion/release) AND the
+  // auto-scroll path (scrollTranscriptRows) can rebuild a span-aware rect. Grows
+  // a word/line multi-click selection from its anchor span to the word/line under
+  // the cursor: target ends before the span → extend backward (span.hi→targetLo);
+  // target starts after → extend forward (span.lo→targetHi); overlapping → the
+  // span. The moving end snaps to the word (getWordRectAt) or line (getLineRectAt)
+  // at the cursor; a miss (blank/gutter) falls back to the raw cell. spanScroll
+  // re-anchors the span to the current transcript scroll (status never scrolls) so
+  // the original word/line tracks the content while dragging/auto-scrolling.
+  const buildSpanRect = useCallback((span, x, y, region, spanScroll = 0) => {
+    const conv = (pt) => (region === 'status' ? pt : selectionPointAtCurrentScroll(pt, spanScroll));
+    const spanLo = conv(span.lo);
+    const spanHi = conv(span.hi);
+    let mLo;
+    let mHi;
+    if (span.kind === 'word') {
+      const wr = store.getWordRectAt?.(x, y);
+      if (wr) { mLo = { x: wr.x1, y: wr.y1 }; mHi = { x: wr.x2, y: wr.y2 }; }
+      else { mLo = { x, y }; mHi = { x, y }; }
+    } else {
+      const lr = store.getLineRectAt?.(y);
+      if (lr) { mLo = { x: lr.x1, y: lr.y1 }; mHi = { x: lr.x2, y: lr.y2 }; }
+      else { mLo = { x: 0, y }; mHi = { x, y }; }
+    }
+    const rect = (a, b) => ({ mode: 'linear', x1: a.x, y1: a.y, x2: b.x, y2: b.y });
+    if (comparePoints(mHi, spanLo) < 0) return rect(spanHi, mLo);
+    if (comparePoints(mLo, spanHi) > 0) return rect(spanLo, mHi);
+    return rect(spanLo, spanHi);
+  }, [store, selectionPointAtCurrentScroll]);
+
+  const transcriptViewportRows = useCallback(() => {
+    const top = Math.max(0, Number(transcriptViewportRef.current?.top) || 0);
+    const bottom = Math.max(top, Number(transcriptViewportRef.current?.bottom) || top);
+    return { top, bottom };
+  }, []);
+
+  const statusBandRows = useCallback(() => {
+    const rows = Math.max(1, Number(frameRowsRef.current) || 24);
+    const top = Math.max(0, rows - STATUSLINE_BAND_ROWS);
+    return { top, bottom: Math.max(top, rows - 1) };
+  }, []);
+
+  const selectionMaxColAtRow = useCallback((row) => {
+    const lr = store.getLineRectAt?.(row);
+    if (lr != null && Number.isFinite(lr.x2)) return Math.max(0, lr.x2);
+    return Math.max(0, frameColumns - 1);
+  }, [store, frameColumns]);
+
+  const moveSelectionFocus = useCallback((move) => {
+    const drag = dragRef.current;
+    if (drag.active) return false;
+    const region = drag.region;
+    if (region !== 'transcript' && region !== 'status') return false;
+    const rect = drag.rect;
+    if (!rect) return false;
+    if (rect.x1 === rect.x2 && rect.y1 === rect.y2) return false;
+
+    const anchor = { x: rect.x1, y: rect.y1 };
+    let col = rect.x2;
+    let row = rect.y2;
+    const beforeCol = col;
+    const beforeRow = row;
+
+    const { top, bottom } = region === 'status' ? statusBandRows() : transcriptViewportRows();
+
+    switch (move) {
+      case 'left':
+        if (col > 0) col -= 1;
+        else if (row > top) {
+          row -= 1;
+          col = selectionMaxColAtRow(row);
+        }
+        break;
+      case 'right': {
+        const maxCol = selectionMaxColAtRow(row);
+        if (col < maxCol) col += 1;
+        else if (row < bottom) {
+          row += 1;
+          col = 0;
+        }
+        break;
+      }
+      case 'up':
+        if (row > top) row -= 1;
+        break;
+      case 'down':
+        if (row < bottom) row += 1;
+        break;
+      case 'lineStart':
+        col = 0;
+        break;
+      case 'lineEnd':
+        col = selectionMaxColAtRow(row);
+        break;
+      default:
+        return false;
+    }
+
+    row = Math.max(top, Math.min(bottom, row));
+    col = Math.max(0, Math.min(selectionMaxColAtRow(row), col));
+
+    if (col === beforeCol && row === beforeRow) return false;
+
+    if (drag.anchorSpan) drag.anchorSpan = null;
+
+    const focus = { x: col, y: row };
+    applySelectionRect({
+      mode: 'linear',
+      x1: anchor.x,
+      y1: anchor.y,
+      x2: focus.x,
+      y2: focus.y,
+    });
+    drag.last = { x: focus.x, y: focus.y };
+    return true;
+  }, [applySelectionRect, statusBandRows, transcriptViewportRows, selectionMaxColAtRow]);
+
   useEffect(() => () => {
     const paintState = selectionPaintRef.current;
     if (paintState.timer) clearTimeout(paintState.timer);
@@ -2078,7 +2480,7 @@ export function App({ store, initialStatusLine = '' }) {
     // streaming growth could lurch the view. At/over the bottom, drop the anchor
     // so the bottom-follow path owns the viewport again.
     if (appliedDelta !== 0) {
-      if (target <= 0) {
+      if (target <= Math.max(0, Number(transcriptBottomSlackRowsRef.current) || 0)) {
         transcriptAnchorRef.current = null;
         transcriptAnchorDirtyRef.current = false;
       } else {
@@ -2110,9 +2512,16 @@ export function App({ store, initialStatusLine = '' }) {
     if (appliedDelta !== 0 && dragRef.current.rect) {
       let rect;
       if (dragRef.current.active) {
-        const { anchor, anchorScroll, last } = dragRef.current;
-        const currentAnchor = selectionPointAtCurrentScroll(anchor, anchorScroll);
-        rect = currentAnchor && last ? { mode: 'linear', x1: currentAnchor.x, y1: currentAnchor.y, x2: last.x, y2: last.y } : null;
+        const { anchor, anchorScroll, last, anchorSpan, region } = dragRef.current;
+        if (anchorSpan && last) {
+          // Word/line multi-click drag that reached the edge: keep extending by
+          // whole words/lines from the span to the word/line at the current cell,
+          // NOT collapsing to a char {anchor->last} rect. Mirrors the motion path.
+          rect = buildSpanRect(anchorSpan, last.x, last.y, region, anchorScroll);
+        } else {
+          const currentAnchor = selectionPointAtCurrentScroll(anchor, anchorScroll);
+          rect = currentAnchor && last ? { mode: 'linear', x1: currentAnchor.x, y1: currentAnchor.y, x2: last.x, y2: last.y } : null;
+        }
       } else {
         rect = shiftSelectionRectY(dragRef.current.rect, appliedDelta);
       }
@@ -2127,7 +2536,7 @@ export function App({ store, initialStatusLine = '' }) {
     stopSmoothScroll();
     scrollPositionRef.current = target;
     setScrollOffset(Math.round(target));
-  }, [startSmoothScroll, stopSmoothScroll, paintSelectionRect, selectionPointAtCurrentScroll, withSelectionClip, cancelTranscriptFollow]);
+  }, [startSmoothScroll, stopSmoothScroll, paintSelectionRect, selectionPointAtCurrentScroll, withSelectionClip, cancelTranscriptFollow, buildSpanRect]);
 
   const passthroughCtrlWheelZoom = useCallback(() => {
     if (!stdout?.write) return;
@@ -2184,6 +2593,8 @@ export function App({ store, initialStatusLine = '' }) {
         y2: b.y,
       };
     };
+    // Word/line multi-click drag-extension uses the hoisted buildSpanRect (same
+    // logic reachable from the auto-scroll path in scrollTranscriptRows).
     const transcriptViewport = () => {
       const top = Math.max(0, Number(transcriptViewportRef.current?.top) || 0);
       const bottom = Math.max(top, Number(transcriptViewportRef.current?.bottom) || top);
@@ -2244,6 +2655,7 @@ export function App({ store, initialStatusLine = '' }) {
       // arrives whole. Guard so non-mouse keystrokes fall through untouched.
       const s = typeof data === 'string' ? data : String(data ?? '');
       if (s.indexOf('\x1b[<') === -1) return;
+      dismissWelcomePromptHint();
       let up = 0;
       let down = 0;
       let m;
@@ -2277,7 +2689,7 @@ export function App({ store, initialStatusLine = '' }) {
             applySelectionRect(null);
             const offset = promptOffsetAt(x, y);
             stopSmoothScroll();
-            dragRef.current = { anchor: { x, y }, anchorScroll: 0, last: { x, y }, active: true, rect: null, region: 'prompt' };
+            dragRef.current = { anchor: { x, y }, anchorScroll: 0, last: { x, y }, active: true, rect: null, region: 'prompt', anchorSpan: null };
             if (offset != null) promptMouseSelectionRef.current?.anchorAt?.(offset);
             continue;
           }
@@ -2287,45 +2699,65 @@ export function App({ store, initialStatusLine = '' }) {
             lastClickRef.current = { x: -1, y: -1, t: 0 };
             dragRef.current.active = false;
             dragRef.current.region = null;
+            dragRef.current.anchorSpan = null;
             clearAllSelections();
             continue;
           }
           const region = inTranscript ? 'transcript' : 'status';
           // A press always clears the prompt-box selection (single active region).
           promptMouseSelectionRef.current?.clear?.();
-          // Double-click on a word: select just that word and copy it, reusing
-          // the existing selection/copy pipeline, then advance to the next event.
-          // Works for transcript AND status rows since getWordRectAt is grid-based.
+          // Multi-click sequence: 2nd consecutive press = word (double-click),
+          // 3rd = whole line (triple-click). Each press must land near the prior
+          // one within 500ms — up to 2 columns and 1 row of drift (terminals
+          // often report a shifted cell on repeat clicks); tighter matching made
+          // word selection unreliable. A 4th qualifying press restarts the
+          // sequence at 1 (claude-code cycles; simplest: reset). Works for
+          // transcript AND status rows since getWordRectAt/getLineRectAt are
+          // grid-based. Copy still happens on Ctrl+C, never here.
           const now = Date.now();
           const lc = lastClickRef.current;
-          // Treat a second press as a double-click when it lands near the first
-          // press within 500ms: up to 2 columns and 1 row of drift (terminals
-          // often report a shifted cell on the second click). Tighter matching
-          // made double-click word selection unreliable.
-          const isDouble = (now - lc.t) < 500
+          const qualifies = (now - lc.t) < 500
             && Math.abs(lc.y - y) <= 1
             && Math.abs(lc.x - x) <= 2;
-          if (isDouble) {
-            // Consume this click so a following press is not mistaken for another
-            // double-click (avoids a stray single-cell selection flicker).
-            lastClickRef.current = { x: -1, y: -1, t: 0 };
-            const wr = store.getWordRectAt?.(x, y);
+          let clickCount = qualifies ? (lc.count || 1) + 1 : 1;
+          if (clickCount > 3) clickCount = 1;
+          if (clickCount === 2 || clickCount === 3) {
+            // Word (2) or line (3) select. Snap to the word/line under the cell
+            // and record the span on dragRef so a following drag extends by whole
+            // words/lines from this span (see buildSpanRect). Leave the drag
+            // ARMED (active:true): a release without motion keeps this highlight
+            // (buildSpanRect returns the span for an in-span target), while
+            // any motion extends it. Mirrors selectWordAt/selectLineAt setting
+            // isDragging=true + anchorSpan; the mouse-up finalizes.
+            const kind = clickCount === 2 ? 'word' : 'line';
+            const wr = kind === 'word' ? store.getWordRectAt?.(x, y) : store.getLineRectAt?.(y);
             if (wr) {
-              const rect = linearSelection({ x: wr.x1, y: wr.y1 }, { x: wr.x2, y: wr.y2 });
+              const lo = { x: wr.x1, y: wr.y1 };
+              const hi = { x: wr.x2, y: wr.y2 };
+              const rect = linearSelection(lo, hi);
               stopSmoothScroll();
-              dragRef.current = { anchor: null, anchorScroll: 0, last: null, active: false, rect: null, region };
+              dragRef.current = {
+                anchor: { x, y },
+                anchorScroll: region === 'transcript' ? scrollTargetRef.current : 0,
+                last: { x, y },
+                active: true,
+                rect: null,
+                region,
+                anchorSpan: { lo, hi, kind },
+              };
               applySelectionRect(rect);
-              // Selection only — copy happens on Ctrl+C (see useInput), not here.
+              lastClickRef.current = { x, y, t: now, count: clickCount };
               continue;
             }
           }
-          lastClickRef.current = { x, y, t: now };
+          lastClickRef.current = { x, y, t: now, count: 1 };
           // Left-button press: begin a new selection anchored here.
           // Anchor the drag but do NOT paint a zero-width selection yet; a plain
           // single click should not flash a one-cell highlight. The selection is
           // only rendered once a drag actually extends past the anchor.
           // Status-band selections do NOT scroll, so anchorScroll is irrelevant
           // there; keep the transcript scroll anchor only for the transcript.
+          // Plain single press clears any word/line anchorSpan (char-drag mode).
           stopSmoothScroll();
           dragRef.current = {
             anchor: { x, y },
@@ -2334,6 +2766,7 @@ export function App({ store, initialStatusLine = '' }) {
             active: true,
             rect: null,
             region,
+            anchorSpan: null,
           };
         } else if (baseButton === 0 && isMotion && dragRef.current.active) {
           const region = dragRef.current.region;
@@ -2350,11 +2783,19 @@ export function App({ store, initialStatusLine = '' }) {
           // current cell, clamped to the owning region's band.
           const selectionY = region === 'status' ? clampToStatusBand(y) : clampToTranscriptViewport(y);
           dragRef.current.last = { x, y: selectionY };
-          const anchor = region === 'status'
-            ? dragRef.current.anchor
-            : selectionPointAtCurrentScroll(dragRef.current.anchor, dragRef.current.anchorScroll);
-          const rect = linearSelection(anchor, { x, y: selectionY });
-          applySelectionRectThrottled(rect);
+          const span = dragRef.current.anchorSpan;
+          if (span) {
+            // Word/line multi-click drag: extend by whole words/lines from the
+            // anchor span to the word/line under the cursor (see buildSpanRect).
+            const rect = buildSpanRect(span, x, selectionY, region, dragRef.current.anchorScroll);
+            applySelectionRectThrottled(rect);
+          } else {
+            const anchor = region === 'status'
+              ? dragRef.current.anchor
+              : selectionPointAtCurrentScroll(dragRef.current.anchor, dragRef.current.anchorScroll);
+            const rect = linearSelection(anchor, { x, y: selectionY });
+            applySelectionRectThrottled(rect);
+          }
           // Auto-scroll-while-dragging is transcript-only (the status band does
           // not scroll).
           if (region === 'transcript') {
@@ -2378,18 +2819,28 @@ export function App({ store, initialStatusLine = '' }) {
           // (the SGR release event carries col/row) and keep the selection
           // visible. Copy is NOT automatic — the user presses Ctrl+C to copy.
           // The highlight stays until ESC or a plain click.
-          const anchor = region === 'status'
-            ? dragRef.current.anchor
-            : selectionPointAtCurrentScroll(dragRef.current.anchor, dragRef.current.anchorScroll);
-          dragRef.current.active = false;
+          const span = dragRef.current.anchorSpan;
           const releaseY = region === 'status' ? clampToStatusBand(y) : clampToTranscriptViewport(y);
-          const rect = linearSelection(anchor, { x, y: releaseY });
-          const empty = rect.x1 === rect.x2 && rect.y1 === rect.y2;
-          if (empty) {
-            applySelectionRect(null); // a plain click clears any prior highlight
-          } else {
-            // Push the final rect so ink re-renders the visible selection.
+          dragRef.current.active = false;
+          if (span) {
+            // Word/line multi-click release: finalize from the span to the
+            // word/line at the release cell. A release-without-motion resolves
+            // to the span itself (in-span target), so the original word/line
+            // highlight stays — never cleared as "empty" like a bare click.
+            const rect = buildSpanRect(span, x, releaseY, region, dragRef.current.anchorScroll);
             applySelectionRect(rect);
+          } else {
+            const anchor = region === 'status'
+              ? dragRef.current.anchor
+              : selectionPointAtCurrentScroll(dragRef.current.anchor, dragRef.current.anchorScroll);
+            const rect = linearSelection(anchor, { x, y: releaseY });
+            const empty = rect.x1 === rect.x2 && rect.y1 === rect.y2;
+            if (empty) {
+              applySelectionRect(null); // a plain click clears any prior highlight
+            } else {
+              // Push the final rect so ink re-renders the visible selection.
+              applySelectionRect(rect);
+            }
           }
           // Drag is over: the measured-height harvest was skipped for every
           // motion commit (see the harvest effect's dragRef guard), so force one
@@ -2415,7 +2866,28 @@ export function App({ store, initialStatusLine = '' }) {
     };
     inkInput.on('input', onData);
     return () => { inkInput.off('input', onData); };
-  }, [inkInput, isRawModeSupported, store, passthroughCtrlWheelZoom, resizeState.rows, scrollTranscriptRows, applySelectionRect, applySelectionRectThrottled, selectionPointAtCurrentScroll]);
+  }, [inkInput, isRawModeSupported, store, passthroughCtrlWheelZoom, resizeState.rows, scrollTranscriptRows, applySelectionRect, applySelectionRectThrottled, selectionPointAtCurrentScroll, buildSpanRect, dismissWelcomePromptHint]);
+
+  // Enable extended keyboard reporting (kitty + xterm modifyOtherKeys) the same
+  // way Claude Code does: SYNCHRONOUSLY, ONCE, with NO query/round-trip. ink
+  // turns raw mode on during the first useInput mount (synchronously, inside
+  // render); this mount effect runs in the same commit phase, right after — i.e.
+  // before the user can realistically press a key. We write BOTH enables
+  // unconditionally (the terminal honors whichever it implements; Windows
+  // Terminal 1.24 has no kitty but DOES honor modifyOtherKeys), gated only by the
+  // supportsExtendedKeys() allowlist. Because the enable lands before the first
+  // keypress is read, the FIRST Ctrl+Enter already arrives as a distinguishable
+  // \x1b[27;5;13~ (or kitty \x1b[13;5u) instead of a bare \r — fixing the old
+  // "first Ctrl+Enter submits, second works" race. Teardown lives in index.jsx's
+  // restoreTerminal(). The empty dep array makes this run exactly once on mount.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useEffect(() => {
+    if (!isRawModeSupported || !stdout?.write) return;
+    if (!supportsExtendedKeys()) return;
+    try {
+      stdout.write(ENABLE_KITTY_KEYBOARD + ENABLE_MODIFY_OTHER_KEYS);
+    } catch { /* terminal may be closing */ }
+  }, []);
 
   // Item-count changes are the only time we can arm follow before row totals are
   // recomputed. Pure streaming height growth is handled in the row-delta effect.
@@ -2428,7 +2900,7 @@ export function App({ store, initialStatusLine = '' }) {
       return;
     }
     if (count === previousCount || dragRef.current.active) return;
-    if (scrollTargetRef.current <= 0 || followingRef.current) followingRef.current = true;
+    if (scrollTargetRef.current <= transcriptBottomSlackRows || followingRef.current) followingRef.current = true;
   }, [state.items.length, resetTranscriptScroll]);
 
   // `exiting` removes the inline caret (PromptInput draws none when disabled) and
@@ -2468,6 +2940,7 @@ export function App({ store, initialStatusLine = '' }) {
     }
     if (restoreDraft) {
       if (restored.pastedImages) installPastedImages(restored.pastedImages, { merge: true });
+      syncPromptLayoutRows(restored.text);
       setPromptDraftOverride({ id: Date.now(), value: restored.text });
     }
     if (showHint) {
@@ -2476,7 +2949,7 @@ export function App({ store, initialStatusLine = '' }) {
       clearPromptHint();
     }
     return true;
-  }, [store, promptDraft, showPromptHint, clearPromptHint, installPastedImages]);
+  }, [store, promptDraft, showPromptHint, clearPromptHint, installPastedImages, syncPromptLayoutRows]);
 
   const recentPromptHistory = useMemo(() => {
     const items = Array.isArray(state.items) ? state.items : [];
@@ -2562,6 +3035,18 @@ export function App({ store, initialStatusLine = '' }) {
   //   the active turn on the same Esc press.
   // - empty prompt + active turn interrupts the active turn.
   const handlePromptEscape = useCallback((text = '', meta = {}) => {
+    // Recording takes priority over every other Esc branch (usage/context
+    // panels, slash-clear, queue-restore, turn-interrupt): a live mic capture
+    // must never silently keep running because Esc was consumed by something
+    // else first. Only consumes Esc while actually RECORDING — transcribing
+    // (already stopped, awaiting the HTTP round-trip) and idle fall through
+    // to the existing branches unchanged.
+    if (getRecorderState() === 'recording') {
+      cancelRecording();
+      setVoiceStatusHint('', 'info');
+      store.pushNotice('Voice: recording cancelled', 'plain');
+      return true;
+    }
     if (usagePanel) { closeUsagePanel(); return true; }
     if (contextPanel) { setContextPanel(null); return true; }
 
@@ -2576,19 +3061,20 @@ export function App({ store, initialStatusLine = '' }) {
     // Idle + empty + nothing to restore: nothing (double-press from empty
     // opens message selector, but we don't have that feature yet).
     return false;
-  }, [contextPanel, usagePanel, closeUsagePanel, restoreQueuedToPrompt, clearPromptHint, clearPastedImagesSnapshot]);
+  }, [contextPanel, usagePanel, closeUsagePanel, restoreQueuedToPrompt, clearPromptHint, clearPastedImagesSnapshot, setVoiceStatusHint, store]);
 
   const handlePromptInterrupt = useCallback((currentText = '') => {
     const result = store.abort?.();
     if (result?.aborted === false) return undefined;
     if (result?.pastedImages) installPastedImages(result.pastedImages, { merge: true });
+    if (result?.discardPastedImages) clearPastedImagesSnapshot(result.discardPastedImages);
     const restoreText = String(result?.restoreText || '').trim();
     if (!restoreText) return undefined;
     const existingText = String(currentText || '').trim();
     const nextText = [restoreText, existingText].filter(Boolean).join('\n');
     clearPromptHint();
     return nextText;
-  }, [store, clearPromptHint, installPastedImages]);
+  }, [store, clearPromptHint, installPastedImages, clearPastedImagesSnapshot]);
 
   // Ctrl+O toggles the global tool-output expansion, matching common terminal-chat
   // expectation that this is a view mode rather than a per-card hidden state.
@@ -2597,6 +3083,7 @@ export function App({ store, initialStatusLine = '' }) {
   }, []);
 
   useInput((input, key) => {
+    if (!welcomePromptHintDismissed) dismissWelcomePromptHint();
     if (toolApproval) {
       const value = String(input || '').trim().toLowerCase();
       if (key.escape || value === 'd' || value === 'n') {
@@ -2638,6 +3125,20 @@ export function App({ store, initialStatusLine = '' }) {
       toggleExpand();
       return;
     }
+    if (
+      !picker
+      && key.shift
+      && (key.leftArrow || key.rightArrow || key.upArrow || key.downArrow || key.home || key.end)
+    ) {
+      let move = null;
+      if (key.leftArrow) move = 'left';
+      else if (key.rightArrow) move = 'right';
+      else if (key.upArrow) move = 'up';
+      else if (key.downArrow) move = 'down';
+      else if (key.home) move = 'lineStart';
+      else if (key.end) move = 'lineEnd';
+      if (move && moveSelectionFocus(move)) return;
+    }
     if (key.escape && usagePanel && !picker) {
       closeUsagePanel();
       return;
@@ -2665,6 +3166,7 @@ export function App({ store, initialStatusLine = '' }) {
     if (key.escape && !picker) {
       dragRef.current.active = false;
       dragRef.current.region = null;
+      dragRef.current.anchorSpan = null;
       // Clear whichever region's selection is active. PromptInput's own ESC also
       // clears its selection when focused/enabled; this covers the disabled case
       // and a status/transcript ink-grid selection in one press.
@@ -3474,6 +3976,10 @@ export function App({ store, initialStatusLine = '' }) {
 
   const openOutputStylePicker = (options = {}) => {
     const returnTo = typeof options.returnTo === 'function' ? options.returnTo : null;
+    // Onboarding mode: Enter (row select) and ConfirmBar Next must both persist
+    // the chosen style, then advance. `onboarding.onAdvance/onBack` drive the
+    // wizard; the confirm bar is built here so both paths share `saveStyle`.
+    const onboarding = options.onboarding || null;
     let status = null;
     try {
       status = store.listOutputStyles?.() || null;
@@ -3487,6 +3993,7 @@ export function App({ store, initialStatusLine = '' }) {
       return;
     }
     const currentId = status?.current?.id || 'default';
+    let highlightedStyleId = currentId;
     const items = styles.map((style) => ({
       value: style.id,
       label: style.label || style.id,
@@ -3501,30 +4008,55 @@ export function App({ store, initialStatusLine = '' }) {
     setSettingsPrompt(null);
     setContextPanel(null);
     closeUsagePanel();
+    const saveStyle = (styleId, { advance = false } = {}) => {
+      if (!styleId) return;
+      setPicker(null);
+      void store.setOutputStyle?.(styleId)
+        .then((result) => {
+          if (!result) {
+            store.pushNotice('Output style switch is already running.', 'warn');
+          } else {
+            store.pushNotice(outputStyleNotice(result), 'info');
+          }
+          if (advance && onboarding) onboarding.onAdvance?.();
+          else if (returnTo) returnTo();
+        })
+        .catch((e) => store.pushNotice(`Couldn’t switch output style: ${e?.message || e}`, 'error'));
+    };
     setPicker({
       title: 'Output Style',
       description: 'Select response style.',
-      help: returnTo ? '↑/↓ Select · Enter Choose · Esc Settings' : '↑/↓ Select · Enter Choose · Esc Back',
+      // Onboarding uses a ConfirmBar (←/→ = Back/Next); let the Picker supply
+      // its ConfirmBar help instead of a stale ←/→ hint.
+      help: onboarding ? undefined : (returnTo ? '↑/↓ Select · Enter Choose · Esc Settings' : '↑/↓ Select · Enter Choose · Esc Back'),
       labelWidth: 18,
       items,
+      confirmBar: onboarding ? {
+        buttons: [
+          { value: 'back', label: '◀ Back' },
+          { value: 'next', label: 'Next ▶' },
+        ],
+        onConfirm: (button) => {
+          if (button.value === 'back') {
+            setPicker(null);
+            onboarding.onBack?.();
+            return;
+          }
+          saveStyle(highlightedStyleId, { advance: true });
+        },
+      } : (options.confirmBar || null),
+      onHighlight: onboarding ? (_value, item) => {
+        if (item?._style?.id) highlightedStyleId = item._style.id;
+      } : undefined,
       onSelect: (_value, item) => {
         const style = item?._style;
         if (!style) return;
-        setPicker(null);
-        void store.setOutputStyle?.(style.id)
-          .then((result) => {
-            if (!result) {
-              store.pushNotice('Output style switch is already running.', 'warn');
-              return;
-            }
-            store.pushNotice(outputStyleNotice(result), 'info');
-            if (returnTo) returnTo();
-          })
-          .catch((e) => store.pushNotice(`Couldn’t switch output style: ${e?.message || e}`, 'error'));
+        saveStyle(style.id, { advance: Boolean(onboarding) });
       },
       onCancel: () => {
         setPicker(null);
-        if (returnTo) returnTo();
+        if (onboarding) onboarding.onCancel?.();
+        else if (returnTo) returnTo();
       },
     });
   };
@@ -3533,6 +4065,7 @@ export function App({ store, initialStatusLine = '' }) {
 
   const openThemePicker = (options = {}) => {
     const returnTo = typeof options.returnTo === 'function' ? options.returnTo : null;
+    const onboarding = options.onboarding || null;
     let themes = [];
     try {
       themes = store.listThemes?.() || [];
@@ -3545,6 +4078,7 @@ export function App({ store, initialStatusLine = '' }) {
       return;
     }
     const currentId = store.getTheme?.() || themes.find((t) => t.current)?.id || themes[0]?.id;
+    let highlightedThemeId = currentId;
     const items = themes.map((entry) => ({
       value: entry.id,
       label: entry.label || entry.id,
@@ -3566,31 +4100,57 @@ export function App({ store, initialStatusLine = '' }) {
         return null;
       }
     };
+    // Onboarding: Enter (row) and ConfirmBar Next both persist the highlighted
+    // theme, then advance; Back restores the original palette then steps back.
+    const saveTheme = (id, { advance = false } = {}) => {
+      setPicker(null);
+      const applied = applyTheme(id, { persist: true });
+      store.pushNotice(themeNotice(applied || { id }), 'info');
+      if (advance && onboarding) onboarding.onAdvance?.();
+      else if (returnTo) returnTo();
+    };
     setPicker({
       title: 'Theme',
       description: 'Choose the color theme that looks best with your terminal.',
-      help: returnTo ? '↑/↓ Preview · Enter Choose · Esc Settings' : '↑/↓ Preview · Enter Choose · Esc Back',
+      help: onboarding ? undefined : (returnTo ? '↑/↓ Preview · Enter Choose · Esc Settings' : '↑/↓ Preview · Enter Choose · Esc Back'),
       labelWidth: 22,
       initialIndex: Math.max(0, items.findIndex((item) => item.value === currentId)),
       items,
+      confirmBar: onboarding ? {
+        buttons: [
+          { value: 'back', label: '◀ Back' },
+          { value: 'next', label: 'Next ▶' },
+        ],
+        onConfirm: (button) => {
+          if (button.value === 'back') {
+            setPicker(null);
+            // Restore the palette active before the picker opened, then step back.
+            if (currentId) applyTheme(currentId, { persist: false });
+            onboarding.onBack?.();
+            return;
+          }
+          saveTheme(highlightedThemeId, { advance: true });
+        },
+      } : (options.confirmBar || null),
       // Live preview while moving: apply (no persist) so the surface re-tones
       // as the selection moves. Enter persists; Esc restores the original.
       onHighlight: (_value, item) => {
-        if (item?._theme?.id) applyTheme(item._theme.id, { persist: false });
+        if (item?._theme?.id) {
+          highlightedThemeId = item._theme.id;
+          applyTheme(item._theme.id, { persist: false });
+        }
       },
       onSelect: (_value, item) => {
         const entry = item?._theme;
         if (!entry) return;
-        setPicker(null);
-        const applied = applyTheme(entry.id, { persist: true });
-        store.pushNotice(themeNotice(applied || entry), 'info');
-        if (returnTo) returnTo();
+        saveTheme(entry.id, { advance: Boolean(onboarding) });
       },
       onCancel: () => {
         setPicker(null);
         // Restore the theme that was active before the picker opened.
         if (currentId) applyTheme(currentId, { persist: false });
-        if (returnTo) returnTo();
+        if (onboarding) onboarding.onCancel?.();
+        else if (returnTo) returnTo();
       },
     });
   };
@@ -3838,7 +4398,7 @@ export function App({ store, initialStatusLine = '' }) {
     const pct = (value, total = windowTokens) => {
       const n = Number(value || 0);
       const d = Number(total || 0);
-      if (!d) return 'n/a';
+      if (!d) return 'N/A';
       return `${((n / d) * 100).toFixed(n > 0 && n < d / 100 ? 1 : 0)}%`;
     };
     const fmt = (value) => {
@@ -3850,11 +4410,17 @@ export function App({ store, initialStatusLine = '' }) {
       return `${Math.round(n)}`;
     };
     const cachedRead = Number(usage.lastCachedReadTokens || 0);
-    const freshInput = Number(usage.lastInputTokens || 0);
-    const cacheDenom = cachedRead + freshInput;
+    const cacheWrite = Number(usage.lastCacheWriteTokens || 0);
+    const freshInput = Number(
+      usage.lastUncachedInputTokens != null
+        ? usage.lastUncachedInputTokens
+        : Math.max(Number(usage.lastInputTokens || 0) - cachedRead - cacheWrite, 0)
+    );
+    const cacheDenom = Number(usage.lastContextTokens || 0) || (cachedRead + freshInput + cacheWrite);
     const cacheHitRate = cacheDenom > 0
       ? `${((cachedRead / cacheDenom) * 100).toFixed(0)}%`
-      : 'n/a';
+      : 'N/A';
+    const cacheWriteLabel = cacheWrite > 0 ? ` · ${fmt(cacheWrite)} write` : '';
     const contextSource = context.usedSource === 'last_api_request' ? 'last API request' : 'estimated';
     const lastApiLabel = context.lastApiRequestStale ? 'last API request (pre-compact)' : 'last API request';
     const compactElapsed = (value) => {
@@ -3922,13 +4488,13 @@ export function App({ store, initialStatusLine = '' }) {
       {
         value: 'last-api',
         label: 'Last API usage',
-        description: `${fmt(usage.lastContextTokens)} context · ${fmt(usage.lastInputTokens)} input · ${fmt(usage.lastOutputTokens)} output · ${lastApiLabel}`,
+        description: `${fmt(usage.lastContextTokens)} context · ${fmt(freshInput)} uncached input · ${fmt(usage.lastOutputTokens)} output · ${lastApiLabel}`,
         _action: 'last-api',
       },
       {
         value: 'cache',
         label: 'Prompt cache',
-        description: `${cacheHitRate} hit · ${fmt(usage.lastCachedReadTokens)} read · ${fmt(usage.lastInputTokens)} new (last request)`,
+        description: `${cacheHitRate} hit · ${fmt(usage.lastCachedReadTokens)} read${cacheWriteLabel} · ${fmt(freshInput)} new (last request)`,
         _action: 'cache',
       },
       {
@@ -3993,12 +4559,14 @@ export function App({ store, initialStatusLine = '' }) {
         },
         lastApi: {
           contextTokens: usage.lastContextTokens,
-          inputTokens: usage.lastInputTokens,
+          inputTokens: freshInput,
+          rawInputTokens: usage.lastInputTokens,
           outputTokens: usage.lastOutputTokens,
         },
         cache: {
           hitRate: cacheHitRate,
           readTokens: usage.lastCachedReadTokens,
+          writeTokens: cacheWrite,
         },
         extensions: {
           skills: skills.count,
@@ -4048,6 +4616,17 @@ export function App({ store, initialStatusLine = '' }) {
     const plugins = store.pluginsStatus?.() || { count: 0 };
     const skills = store.skillsStatus?.() || { count: 0 };
     const channelWorker = store.getChannelWorkerStatus?.();
+    let channelBackend = 'discord';
+    try {
+      channelBackend = store.getChannelSetup?.()?.backend || 'discord';
+    } catch {
+      channelBackend = 'discord';
+    }
+    const channelBackendLabel = channelBackend === 'telegram' ? 'Telegram' : 'Discord';
+    const remoteEnabled = store.isRemoteEnabled?.() === true;
+    const remoteRuntimeDescription = channelWorker?.running
+      ? `runtime running · pid ${channelWorker.pid}`
+      : 'runtime stopped';
     const compactType = compaction.compactType || compaction.type || 'semantic';
     const compactTypeLabel = compactType === 'recall-fasttrack' ? 'Fast-track' : 'Default';
     const outputStyleLabel = outputStyle?.current?.label || outputStyle?.current?.id || outputStyle?.configured || 'Default';
@@ -4174,6 +4753,31 @@ export function App({ store, initialStatusLine = '' }) {
       }
       openSettingsPicker();
     };
+    const applyRemoteRuntime = () => {
+      const enabled = store.toggleRemote?.() === true;
+      store.pushNotice(enabled ? 'Remote mode ON' : 'Remote mode OFF', 'info');
+      openSettingsPicker();
+    };
+    const cycleChannelBackend = (direction = 1) => {
+      const backends = ['discord', 'telegram'];
+      const currentIndex = Math.max(0, backends.indexOf(channelBackend));
+      const chosen = backends[(currentIndex + direction + backends.length) % backends.length];
+      if (chosen === channelBackend) {
+        openSettingsPicker();
+        return;
+      }
+      try {
+        store.setBackend(chosen);
+        const label = chosen === 'telegram' ? 'Telegram' : 'Discord';
+        const restartHint = (store.isRemoteEnabled?.() === true || channelWorker?.running)
+          ? `Channel set to ${label}. Restart remote to apply.`
+          : `Channel set to ${label}.`;
+        store.pushNotice(restartHint, 'info');
+      } catch (e) {
+        store.pushNotice(`channel backend failed: ${e?.message || e}`, 'error');
+      }
+      openSettingsPicker();
+    };
     const items = [
       {
         value: 'profile',
@@ -4234,10 +4838,24 @@ export function App({ store, initialStatusLine = '' }) {
         _action: 'channels',
       },
       {
-        value: 'channels-setup',
-        label: 'Channels setup',
-        description: channelWorker?.running ? `runtime running · pid ${channelWorker.pid}` : 'runtime stopped',
-        _action: 'channels-setup',
+        value: 'remote-runtime',
+        label: 'Remote Runtime',
+        meta: boolLabel(remoteEnabled),
+        description: remoteRuntimeDescription,
+        _action: 'remote-runtime',
+      },
+      {
+        value: 'channel-backend',
+        label: 'Channel',
+        meta: channelBackendLabel,
+        description: 'Left/Right or Enter changes channel type (Discord or Telegram).',
+        _action: 'channel-backend',
+      },
+      {
+        value: 'channel-setting',
+        label: 'Setting',
+        description: 'Configure credentials and main channel/chat for the active type.',
+        _action: 'channel-setting',
       },
       {
         value: 'output-style',
@@ -4310,6 +4928,21 @@ export function App({ store, initialStatusLine = '' }) {
         description: `${skills.count || 0} available`,
         _action: 'skills',
       },
+      {
+        value: 'update',
+        label: 'Update',
+        meta: (() => {
+          try {
+            const upd = store.getUpdateSettings?.() || {};
+            const current = upd.currentVersion || 'unknown';
+            if (upd.updateAvailable && upd.latestVersion) return `${current} → ${upd.latestVersion}`;
+            if (!upd.currentVersion) return 'unknown';
+            return `${current} (latest)`;
+          } catch { return 'unknown'; }
+        })(),
+        description: 'Check version and update mixdog.',
+        _action: 'update',
+      },
     ];
     setProviderPrompt(null);
     setChannelPrompt(null);
@@ -4333,6 +4966,8 @@ export function App({ store, initialStatusLine = '' }) {
         }
         else if (item?._action === 'memory') applyMemory(!(memory.enabled !== false));
         else if (item?._action === 'channels') applyChannels(!(channels.enabled !== false));
+        else if (item?._action === 'remote-runtime') applyRemoteRuntime();
+        else if (item?._action === 'channel-backend') cycleChannelBackend(-1);
         else if (item?._action === 'output-style') cycleOutputStyle(-1);
         else if (item?._action === 'theme') cycleTheme(-1);
         else if (item?._action === 'workflow') cycleWorkflow(-1);
@@ -4346,6 +4981,8 @@ export function App({ store, initialStatusLine = '' }) {
         }
         else if (item?._action === 'memory') applyMemory(!(memory.enabled !== false));
         else if (item?._action === 'channels') applyChannels(!(channels.enabled !== false));
+        else if (item?._action === 'remote-runtime') applyRemoteRuntime();
+        else if (item?._action === 'channel-backend') cycleChannelBackend(1);
         else if (item?._action === 'output-style') cycleOutputStyle(1);
         else if (item?._action === 'theme') cycleTheme(1);
         else if (item?._action === 'workflow') cycleWorkflow(1);
@@ -4362,7 +4999,9 @@ export function App({ store, initialStatusLine = '' }) {
         else if (item._action === 'memory') applyMemory(!(memory.enabled !== false));
         else if (item._action === 'memory-dashboard') openMemoryPicker();
         else if (item._action === 'channels') applyChannels(!(channels.enabled !== false));
-        else if (item._action === 'channels-setup') void openChannelSetupPicker('all');
+        else if (item._action === 'remote-runtime') applyRemoteRuntime();
+        else if (item._action === 'channel-backend') cycleChannelBackend(1);
+        else if (item._action === 'channel-setting') openChannelSettingTypePicker({ returnTo: openSettingsPicker });
         else if (item._action === 'output-style') openOutputStylePicker({ returnTo: openSettingsPicker });
         else if (item._action === 'theme') openThemePicker({ returnTo: openSettingsPicker });
         else if (item._action === 'workflow') openWorkflowPicker({ returnTo: openSettingsPicker });
@@ -4387,6 +5026,7 @@ export function App({ store, initialStatusLine = '' }) {
         else if (item._action === 'plugins') openPluginsPicker();
         else if (item._action === 'hooks') openHooksPicker();
         else if (item._action === 'skills') openSkillsPicker();
+        else if (item._action === 'update') openUpdatePicker({ returnTo: openSettingsPicker });
       },
       onCancel: () => {
         setPicker(null);
@@ -4402,37 +5042,44 @@ export function App({ store, initialStatusLine = '' }) {
     setChannelPrompt(null);
     setHookPrompt(null);
     setSettingsPrompt(null);
-    setPicker({
-      title: options.title || 'Providers',
-      description: options.description || 'Choose a provider to configure.',
-      labelWidth: 18,
-      metaWidth: 10,
-      pickerKey: 'providers-loading',
-      initialIndex: 0,
-      items: [{
-        value: 'checking',
-        label: 'Checking Providers',
-        meta: '',
-        description: 'please wait',
-        _type: 'loading',
-      }],
-      onSelect: () => {},
-      onCancel: () => {
-        setPicker(null);
-        if (onCancel) onCancel();
-      },
-    });
-    let setup;
-    try {
-      await new Promise((resolve) => setTimeout(resolve, 0));
-      setup = await store.getProviderSetup();
-    } catch (e) {
-      store.pushNotice(`providers failed: ${e?.message || e}`, 'error');
-      return;
+    // Onboarding (and any caller) can pass a preloaded provider setup so we skip
+    // the "Checking Providers" placeholder frame that otherwise flashes before
+    // the real list — that swap is what looked like a jump on Step 1 entry.
+    let setup = options.preloadedSetup && typeof options.preloadedSetup === 'object'
+      ? options.preloadedSetup
+      : null;
+    if (!setup) {
+      setPicker({
+        title: options.title || 'Providers',
+        description: options.description || 'Choose a provider to configure.',
+        labelWidth: 18,
+        metaWidth: 10,
+        pickerKey: 'providers-loading',
+        initialIndex: 0,
+        items: [{
+          value: 'checking',
+          label: 'Checking Providers',
+          meta: '',
+          description: 'please wait',
+          _type: 'loading',
+        }],
+        onSelect: () => {},
+        onCancel: () => {
+          setPicker(null);
+          if (onCancel) onCancel();
+        },
+      });
+      try {
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        setup = await store.getProviderSetup();
+      } catch (e) {
+        store.pushNotice(`providers failed: ${e?.message || e}`, 'error');
+        return;
+      }
     }
 
     const items = [];
-    if (returnTo || onContinue) {
+    if ((returnTo || onContinue) && !options.confirmBar) {
       items.push({
         value: 'continue-setup',
         label: options.continueLabel || 'Continue setup',
@@ -4828,14 +5475,15 @@ export function App({ store, initialStatusLine = '' }) {
       title: options.title || 'Providers',
       description: options.description || 'Choose a provider. Enter opens provider actions.',
       footer: providerFooter,
-      footerGapRows: 0,
-      help: '↑/↓ Select · Enter Open · Esc Back',
+      footerGapRows: 1,
+      help: options.confirmBar ? undefined : '↑/↓ Select · Enter Open · Esc Back',
       indexMode: 'always',
       labelWidth: 18,
       metaWidth: 12,
       pickerKey: `providers-main:${options.highlightProviderValue || 'root'}`,
       initialIndex: providerMainInitialIndex(),
       items,
+      confirmBar: options.confirmBar || null,
       onHighlight: (_value, item) => {
         if (item?._providerId) rememberProviderSelection(item);
       },
@@ -4865,70 +5513,274 @@ export function App({ store, initialStatusLine = '' }) {
     });
   };
 
-  const openOnboardingAuthStep = () => {
-    void openProviderSetupPicker({
-      title: 'First Run · Step 1/2 · Provider Auth',
-      continueLabel: 'Continue to model setup',
-      continueDescription: 'choose the default and workflow models',
-      returnTo: () => openOnboardingAuthStep(),
-      onContinue: () => void openOnboardingWorkflowStep(),
-      onCancel: () => store.pushNotice('first-run setup will open again next launch', 'warn'),
-    });
+  // First-run onboarding is a 5-step wizard. Each step's ROOT screen carries a
+  // ConfirmBar (Back/Next, Finish on the last step); the Picker owns the bar
+  // focus and only fires onConfirm from the bar. Nested depths (API-key entry,
+  // model route picker, channel setting/webhook) render without a ConfirmBar so
+  // their own key semantics are untouched and step-switching is disabled there.
+  // Esc/cancel during onboarding = confirm skip. Mark onboarding complete
+  // (routes/agents/provider untouched) so it does not reopen next launch;
+  // `mixdog --onboarding` (forceOnboarding) still reopens regardless.
+  const onboardingWarnReopen = () => {
+    setOnboardingActive(false);
+    try {
+      store.skipOnboarding?.();
+      store.pushNotice('Setup skipped. Run `mixdog --onboarding` to set up later.', 'info');
+    } catch (e) {
+      store.pushNotice(`Couldn’t save skip: ${e?.message || e}`, 'error');
+    }
   };
 
-  const openOnboardingRoleModelPicker = (slot) => {
-    const models = normalizeModelOptions(onboardingRef.current.providerModels || []);
-    const fallbackRoute = onboardingRef.current.defaultRoute || null;
-    if (models.length === 0) {
-      store.pushNotice('no provider models available; open /providers to sign in', 'warn');
-      openOnboardingAuthStep();
-      return;
+  // Warm the Step 2 data (provider models + agent roster) in the background as
+  // soon as Step 1 opens, so advancing to Step 2 renders instantly instead of
+  // flashing an empty panel while the async load runs.
+  const prefetchOnboardingStep2 = () => {
+    if (!Array.isArray(onboardingRef.current.providerModels) || onboardingRef.current.providerModels.length === 0) {
+      const seq = onboardingPrefetchSeqRef.current;
+      void Promise.resolve(store.listProviderModels?.())
+        .then((models) => {
+          // Drop a stale result: if the provider cache was invalidated (auth
+          // change) while this load was in flight, its generation moved on.
+          if (seq !== onboardingPrefetchSeqRef.current) return;
+          if (Array.isArray(models) && models.length) {
+            onboardingRef.current.providerModels = models;
+            providerModelsCacheRef.current = { models, at: Date.now() };
+          }
+        })
+        .catch(() => { /* Step 2 falls back to its own load on entry. */ });
     }
-    const recommendedRoute = chooseRecommendedModel(models, slot, fallbackRoute);
-    const items = [
-      {
-        value: 'recommended',
-        label: 'Use recommended',
-        description: routeLabel(recommendedRoute),
-        _action: 'recommended',
+    if (!Array.isArray(onboardingRef.current.agents) || onboardingRef.current.agents.length === 0) {
+      try {
+        const roster = (store.listAgents?.() || []).map((a) => ({ id: a.id, label: a.label || a.id, description: a.description || '' }));
+        if (roster.length) onboardingRef.current.agents = roster;
+      } catch { /* Step 2 retries on entry. */ }
+    }
+  };
+
+  const openOnboardingAuthStep = async () => {
+    prefetchOnboardingStep2();
+    // Load the provider setup BEFORE opening the picker so Step 1 renders the
+    // real list in one frame instead of flashing the "Checking Providers"
+    // placeholder (that swap is what looked like a jump on entry). On failure,
+    // fall back to the picker's own in-panel loading path.
+    let preloadedSetup = null;
+    try {
+      preloadedSetup = await store.getProviderSetup?.();
+    } catch { /* openProviderSetupPicker will show its loading frame + error. */ }
+    void openProviderSetupPicker({
+      title: 'First Run · Step 1/5 · Provider Auth',
+      returnTo: () => openOnboardingAuthStep(),
+      preloadedSetup,
+      confirmBar: {
+        buttons: [{ value: 'next', label: 'Next ▶' }],
+        onConfirm: () => { setPicker(null); void openOnboardingWorkflowStep(); },
       },
-      ...models.map((m) => ({
-        value: `${m.provider}:${m.id}`,
-        label: m.display || m.id,
-        description: modelDescription(m),
-        _action: 'select-model',
-        _model: m,
-      })),
-      ...(fallbackRoute ? [{
-        value: 'fallback',
-        label: 'Use lead model',
-        description: routeLabel(fallbackRoute),
-        _action: 'fallback',
-      }] : []),
-    ];
+      onCancel: onboardingWarnReopen,
+    });
+  };
+
+  const openOnboardingThemeStep = () => {
+    openThemePicker({
+      onboarding: {
+        onAdvance: () => openOnboardingOutputStyleStep(),
+        onBack: () => void openOnboardingWorkflowStep(),
+        onCancel: onboardingWarnReopen,
+      },
+    });
+  };
+
+  const openOnboardingOutputStyleStep = () => {
+    openOutputStylePicker({
+      onboarding: {
+        onAdvance: () => void openOnboardingRemoteStep(),
+        onBack: () => openOnboardingThemeStep(),
+        onCancel: onboardingWarnReopen,
+      },
+    });
+  };
+
+  const openOnboardingRemoteStep = () => {
+    void openChannelSetupPicker('all', {
+      onboarding: true,
+      confirmBar: {
+        buttons: [
+          { value: 'back', label: '◀ Back' },
+          { value: 'finish', label: 'Finish ✓' },
+        ],
+        onConfirm: (button) => {
+          if (button.value === 'back') {
+            setPicker(null);
+            openOnboardingOutputStyleStep();
+            return;
+          }
+          finishOnboarding();
+        },
+      },
+    });
+  };
+
+  const finishOnboarding = () => {
+    const defaultRoute = onboardingRef.current.defaultRoute;
+    const searchRoute = onboardingRef.current.searchRoute || null;
+    const overrides = onboardingRef.current.agentRoutes || {};
+    const hasOverrides = Object.keys(overrides).length > 0;
+    setPicker(null);
+    setOnboardingActive(false);
+    const done = () => store.pushNotice('First-run setup complete.', 'info');
+    const failed = (e) => store.pushNotice(`Couldn’t save setup: ${e?.message || e}`, 'error');
+    // Branch 1 — Main Model set: full persist. Agents without an explicit
+    // override are sent; untouched agents are left out so the backend never
+    // overwrites them (they follow the Main Model dynamically at runtime).
+    if (defaultRoute) {
+      void store.completeOnboarding?.({
+        defaultRoute,
+        defaultProvider: defaultRoute.provider,
+        ...(hasOverrides ? { agentRoutes: { ...overrides } } : {}),
+        ...(searchRoute ? { searchRoute } : {}),
+      }).then(done).catch(failed);
+      return;
+    }
+    // Branch 2 — Main unset but some Search/agent picks exist: partial persist.
+    // Only the explicit overrides are sent (no defaultRoute/defaultProvider); the
+    // backend skips agents lacking a route and marks onboarding complete.
+    if (hasOverrides || searchRoute) {
+      void store.completeOnboarding?.({
+        ...(hasOverrides ? { agentRoutes: { ...overrides } } : {}),
+        ...(searchRoute ? { searchRoute } : {}),
+      }).then(done).catch(failed);
+      return;
+    }
+    // Branch 3 — nothing configured: mark done only, leave config untouched.
+    try {
+      store.skipOnboarding?.();
+    } catch (e) {
+      failed(e);
+      return;
+    }
+    done();
+  };
+
+  // Onboarding Step 2 per-target model picker. `target` is either the pseudo
+  // slot 'lead' (Main Model) or a real agent id from listAgents(). No
+  // recommendation logic: the current effective route is pre-highlighted, and
+  // the plain model list is shown. Selecting Main Model updates defaultRoute;
+  // agents that have no explicit override keep inheriting it.
+  const openOnboardingRoleModelPicker = async (target) => {
+    const isLead = target === 'lead';
+    const isSearch = target === 'search';
+    // Search uses the search-capable model list; lead/agent use provider models.
+    let models;
+    if (isSearch) {
+      let searchModels = [];
+      try {
+        searchModels = await Promise.resolve(store.listSearchModels?.() || []);
+      } catch (e) {
+        store.pushNotice(`could not list search models: ${e?.message || e}`, 'warn');
+      }
+      models = normalizeModelOptions(searchModels || []);
+      if (models.length === 0) {
+        store.pushNotice('no native search models available; connect OpenAI, Grok, Gemini, or Anthropic', 'warn');
+        void openOnboardingWorkflowStep();
+        return;
+      }
+    } else {
+      models = normalizeModelOptions(onboardingRef.current.providerModels || []);
+      if (models.length === 0) {
+        store.pushNotice('no provider models available; open /providers to sign in', 'warn');
+        openOnboardingAuthStep();
+        return;
+      }
+    }
+    const overrides = onboardingRef.current.agentRoutes || {};
+    // Current effective route for pre-marking: Main/Search show their own stored
+    // route (or none); agents show their explicit override only (unset = none,
+    // so we don't falsely mark the Main Model row on an untouched agent).
+    const currentRoute = isLead
+      ? (onboardingRef.current.defaultRoute || null)
+      : isSearch
+        ? (onboardingRef.current.searchRoute || null)
+        : (overrides[target] || null);
+    const routeMatchesModel = (route, m) => route?.provider === m.provider && route?.model === m.id;
+    // Non-lead targets get a leading "Default" row that makes the target follow
+    // the Main Model at runtime. For agents this clears the override (null);
+    // for search this stores the SEARCH_DEFAULT marker route. "Default" is the
+    // pre-marked row when the target is unset (agent) or on the marker (search).
+    const isDefaultSelected = isSearch
+      ? (!currentRoute || isSearchDefaultRoute(currentRoute))
+      : !currentRoute;
+    const isUnset = isDefaultSelected;
+    const modelItems = models.map((m) => ({
+      value: `${m.provider}:${m.id}`,
+      label: m.display || m.id,
+      marker: routeMatchesModel(currentRoute, m) ? '✓' : '',
+      markerColor: theme.success,
+      description: modelDescription(m),
+      _model: m,
+    }));
+    const items = isLead
+      ? modelItems
+      : [
+          {
+            value: '__default__',
+            label: 'Default',
+            marker: isUnset ? '✓' : '',
+            markerColor: theme.success,
+            description: 'follows Main Model',
+            _default: true,
+          },
+          ...modelItems,
+        ];
+    const matchIdx = models.findIndex((m) => routeMatchesModel(currentRoute, m));
+    const initialIndex = isLead
+      ? Math.max(0, matchIdx)
+      : (isUnset || matchIdx < 0 ? 0 : matchIdx + 1);
+    const label = isLead
+      ? 'Main'
+      : isSearch
+        ? 'Search'
+        : (onboardingRef.current.agents || []).find((a) => a.id === target)?.label || target;
     setPicker({
-      title: `First Run · ${slot} model`,
-      description: 'Pick the model route for this workflow role.',
+      title: `First Run · ${label}`,
+      description: isLead
+        ? 'Pick the main model. Agents inherit this unless individually changed.'
+        : isSearch
+          ? 'Pick the native web-search model, or Default to follow the Main Model.'
+          : `Pick the model for ${label}, or Default to follow the Main Model.`,
+      initialIndex,
       items,
       onSelect: (_value, item) => {
-        const next = item._action === 'select-model'
-          ? routeFromModel(item._model)
-          : item._action === 'recommended'
-            ? recommendedRoute
-            : fallbackRoute;
+        // "Default" → clear the override so this target follows the Main Model.
+        if (item?._default) {
+          if (isSearch) {
+            // Store the SEARCH_DEFAULT marker so finish persists it and the
+            // runtime follows the Main Model (not a null that drops the field).
+            onboardingRef.current.searchRoute = { ...SEARCH_DEFAULT_ROUTE };
+          } else {
+            const nextOverrides = { ...(onboardingRef.current.agentRoutes || {}) };
+            delete nextOverrides[target];
+            onboardingRef.current.agentRoutes = nextOverrides;
+          }
+          setPicker(null);
+          void openOnboardingWorkflowStep();
+          return;
+        }
+        const next = item?._model ? routeFromModel(item._model) : null;
         if (!next) {
           store.pushNotice('select a provider model first', 'warn');
           setPicker(null);
-          openOnboardingAuthStep();
+          void openOnboardingWorkflowStep();
           return;
         }
-        if (slot === 'lead') {
+        if (isLead) {
           onboardingRef.current.defaultRoute = next;
+        } else if (isSearch) {
+          onboardingRef.current.searchRoute = next;
+        } else {
+          onboardingRef.current.agentRoutes = {
+            ...(onboardingRef.current.agentRoutes || {}),
+            [target]: next,
+          };
         }
-        onboardingRef.current.workflowRoutes = {
-          ...(onboardingRef.current.workflowRoutes || {}),
-          [slot]: next,
-        };
         setPicker(null);
         void openOnboardingWorkflowStep();
       },
@@ -4952,90 +5804,86 @@ export function App({ store, initialStatusLine = '' }) {
     const models = onboardingRef.current.providerModels || [];
     if (models.length === 0) {
       onboardingRef.current.defaultRoute = null;
-      onboardingRef.current.workflowRoutes = {};
+      onboardingRef.current.agentRoutes = {};
       store.pushNotice('no provider models available; open /providers to sign in', 'warn');
       openOnboardingAuthStep();
       return;
     }
-    if (!onboardingRef.current.defaultRoute) {
-      onboardingRef.current.defaultRoute = chooseRecommendedModel(models, 'lead', null);
-    }
-    if (!onboardingRef.current.workflowRoutes || Object.keys(onboardingRef.current.workflowRoutes).length === 0) {
-      onboardingRef.current.workflowRoutes = buildWorkflowDefaults(models, onboardingRef.current.defaultRoute);
+    // Main Model stays unset until the user picks one; no auto-recommendation.
+    // Load the real agent roster once (explore/maintainer/worker/heavy-worker/
+    // reviewer/debugger). Each agent defaults to the Main Model unless the user
+    // set an explicit override in agentRoutes.
+    if (!Array.isArray(onboardingRef.current.agents) || onboardingRef.current.agents.length === 0) {
+      try {
+        onboardingRef.current.agents = (store.listAgents?.() || []).map((a) => ({ id: a.id, label: a.label || a.id, description: a.description || '' }));
+      } catch (e) {
+        onboardingRef.current.agents = [];
+        store.pushNotice(`could not list agents: ${e?.message || e}`, 'warn');
+      }
     }
-    onboardingRef.current.workflowRoutes = {
-      ...(onboardingRef.current.workflowRoutes || {}),
-      lead: onboardingRef.current.defaultRoute,
-    };
-    const routes = onboardingRef.current.workflowRoutes || {};
-    const slots = [
-      ['agent', 'Agent', 'agent dispatch route'],
-      ['explorer', 'Explorer', 'code graph, file reading, repo exploration'],
-      ['memory', 'Memory', 'memory cycles and curation'],
-    ];
+    const defaultRoute = onboardingRef.current.defaultRoute;
+    const searchRoute = onboardingRef.current.searchRoute || null;
+    const overrides = onboardingRef.current.agentRoutes || {};
+    const agents = onboardingRef.current.agents || [];
     setProviderPrompt(null);
     setChannelPrompt(null);
     setHookPrompt(null);
     setSettingsPrompt(null);
     setPicker({
-      title: 'First Run · Step 2/2 · Workflow Routes',
-      description: 'Assign lead and workflow routes, then finish setup.',
+      title: 'First Run · Step 2/5 · Models',
+      description: 'Set the Main Model; each agent inherits it unless changed.',
+      indexMode: 'always',
+      labelWidth: 18,
+      metaWidth: 33,
       items: [
         {
-          value: 'finish',
-          label: 'Finish setup',
-          description: 'save model and workflow route mapping',
-          _action: 'finish',
+          value: 'main-model',
+          label: 'Main',
+          metaParts: agentModelParts(defaultRoute),
+          description: 'main chat, planning, and agent default',
+          _action: 'slot',
+          _target: 'lead',
         },
         {
-          value: 'lead',
-          label: 'Default model',
-          description: `${routeLabel(onboardingRef.current.defaultRoute)} · main chat and planning route`,
+          value: 'search-model',
+          label: 'Search',
+          // Marker route = follow Main Model → show a hint, not 'default/default'.
+          metaParts: isSearchDefaultRoute(searchRoute)
+            ? [{ text: '(follows main)', width: 17 }, { text: '', width: 6 }, { text: '', width: 4 }]
+            : agentModelParts(searchRoute),
+          description: 'native search model',
           _action: 'slot',
-          _slot: 'lead',
+          _target: 'search',
         },
-        ...slots.map(([slot, label, description]) => ({
-          value: slot,
-          label,
-          description: `${routeLabel(routes[slot])} · ${description}`,
+        ...agents.map((agent) => ({
+          value: `agent:${agent.id}`,
+          label: agent.label,
+          metaParts: agentModelParts(overrides[agent.id] || null),
+          description: agent.description || '',
           _action: 'slot',
-          _slot: slot,
+          _target: agent.id,
         })),
-        {
-          value: 'back',
-          label: 'Back to provider auth',
-          description: 'change API keys, OAuth, or local endpoints',
-          _action: 'back',
-        },
       ],
+      confirmBar: {
+        buttons: [
+          { value: 'back', label: '◀ Back' },
+          { value: 'next', label: 'Next ▶' },
+        ],
+        onConfirm: (button) => {
+          setPicker(null);
+          if (button.value === 'back') openOnboardingAuthStep();
+          else openOnboardingThemeStep();
+        },
+      },
       onSelect: (_value, item) => {
         setPicker(null);
-        if (item._action === 'finish') {
-          const defaultRoute = onboardingRef.current.defaultRoute;
-          if (!defaultRoute) {
-            store.pushNotice('select a provider model before finishing setup', 'warn');
-            openOnboardingAuthStep();
-            return;
-          }
-          void store.completeOnboarding?.({
-            defaultRoute,
-            workflowRoutes: onboardingRef.current.workflowRoutes || {},
-          })
-            .then(() => store.pushNotice('First-run setup complete.', 'info'))
-            .catch((e) => store.pushNotice(`Couldn’t save setup: ${e?.message || e}`, 'error'));
-          return;
-        }
-        if (item._action === 'back') {
-          openOnboardingAuthStep();
-          return;
-        }
         if (item._action === 'slot') {
-          openOnboardingRoleModelPicker(item._slot);
+          openOnboardingRoleModelPicker(item._target);
         }
       },
       onCancel: () => {
         setPicker(null);
-        store.pushNotice('first-run setup will open again next launch', 'warn');
+        onboardingWarnReopen();
       },
     });
   };
@@ -5045,8 +5893,9 @@ export function App({ store, initialStatusLine = '' }) {
     let canceled = false;
     try {
       const status = store.getOnboardingStatus?.();
-      if (status?.completed === true) return undefined;
+      if (status?.completed === true && !forceOnboarding) return undefined;
       onboardingStartedRef.current = true;
+      setOnboardingActive(true);
       setTimeout(() => {
         if (!canceled) openOnboardingAuthStep();
       }, 0);
@@ -5056,9 +5905,176 @@ export function App({ store, initialStatusLine = '' }) {
     return () => {
       canceled = true;
     };
-  }, [store]);
+  }, [store, forceOnboarding]);
+
+  const openChannelTypeActionsPicker = (backend, options = {}) => {
+    const parentReturn = typeof options.returnTo === 'function'
+      ? options.returnTo
+      : () => openChannelSettingTypePicker();
+    setProviderPrompt(null);
+    setHookPrompt(null);
+    setSettingsPrompt(null);
+    setContextPanel(null);
+    let setup;
+    try {
+      setup = store.getChannelSetup();
+    } catch (e) {
+      store.pushNotice(`channels failed: ${e?.message || e}`, 'error');
+      return;
+    }
+    const isTelegram = backend === 'telegram';
+    const activeBackend = setup.backend || 'discord';
+    const tokenDescription = isTelegram
+      ? `${setup.telegram?.status ?? 'Off'}${setup.telegram?.problem ? ' · Invalid' : ''}`
+      : `${setup.discord.status}${setup.discord.problem ? ' · Invalid' : ''}`;
+    const mainEntry = (setup.channels || []).find((ch) => ch.main)
+      || (setup.channels || []).find((ch) => ch.name === 'main');
+    const mainTarget = isTelegram
+      ? (mainEntry?.telegramChatId || (activeBackend === 'telegram' ? mainEntry?.channelId : ''))
+      : (mainEntry?.discordChannelId || (activeBackend === 'discord' ? mainEntry?.channelId : ''));
+    const mainDescription = isTelegram
+      ? (mainTarget ? `Chat ID ${mainTarget}` : 'Not set · Enter Telegram chat ID')
+      : (mainTarget ? `Channel ID ${mainTarget}` : 'Not set · Enter Discord channel ID');
+
+    const openChannelPrompt = (prompt) => {
+      setPicker(null);
+      setContextPanel(null);
+      setChannelPrompt({
+        ...prompt,
+        afterSave: () => openChannelTypeActionsPicker(backend, options),
+      });
+    };
+
+    setPicker({
+      title: isTelegram ? 'Telegram' : 'Discord',
+      description: activeBackend === backend
+        ? 'Active channel type · token and main target'
+        : 'Token and main target settings',
+      help: '↑/↓ Select · Enter Edit · Esc Back',
+      indexMode: 'always',
+      labelWidth: 18,
+      items: [
+        {
+          value: 'token',
+          label: 'Bot token',
+          description: tokenDescription,
+          _action: isTelegram ? 'telegram-token' : 'discord-token',
+        },
+        {
+          value: 'main',
+          label: isTelegram ? 'Main chat' : 'Main channel',
+          description: mainDescription,
+          _action: 'main-target',
+        },
+      ],
+      onSelect: (_value, item) => {
+        try {
+          if (item._action === 'discord-token') {
+            openChannelPrompt({
+              kind: 'discord-token',
+              label: 'Discord bot token',
+              hint: 'Paste the Discord bot token. It is stored in the OS keychain.',
+            });
+            return;
+          }
+          if (item._action === 'telegram-token') {
+            openChannelPrompt({
+              kind: 'telegram-token',
+              label: 'Telegram bot token',
+              hint: 'Paste the Telegram bot token from @BotFather. Stored in the OS keychain.',
+            });
+            return;
+          }
+          if (item._action === 'main-target') {
+            openChannelPrompt({
+              kind: 'channel-add',
+              backend,
+              label: isTelegram ? 'Main chat' : 'Main channel',
+              hint: isTelegram
+                ? 'Format: main | Telegram chat ID | mode(interactive/broadcast) | main'
+                : 'Format: main | Discord channel ID | mode(interactive/broadcast) | main',
+            });
+          }
+        } catch (e) {
+          store.pushNotice(`channels update failed: ${e?.message || e}`, 'error');
+        }
+      },
+      onCancel: () => {
+        parentReturn();
+      },
+    });
+  };
+
+  const openChannelSettingTypePicker = (options = {}) => {
+    const returnTo = typeof options.returnTo === 'function' ? options.returnTo : () => {};
+    setProviderPrompt(null);
+    setChannelPrompt(null);
+    setHookPrompt(null);
+    setSettingsPrompt(null);
+    setContextPanel(null);
+    let setup;
+    try {
+      setup = store.getChannelSetup();
+    } catch (e) {
+      store.pushNotice(`channels failed: ${e?.message || e}`, 'error');
+      return;
+    }
+    const activeBackend = setup.backend || 'discord';
+    const mainEntry = (setup.channels || []).find((ch) => ch.main)
+      || (setup.channels || []).find((ch) => ch.name === 'main');
+    const typeDescription = (backend) => {
+      const selected = activeBackend === backend;
+      const hasToken = backend === 'telegram'
+        ? setup.telegram?.authenticated === true
+        : setup.discord?.authenticated === true;
+      const hasTarget = backend === 'telegram'
+        ? Boolean(mainEntry?.telegramChatId || (activeBackend === 'telegram' && mainEntry?.channelId))
+        : Boolean(mainEntry?.discordChannelId || (activeBackend === 'discord' && mainEntry?.channelId));
+      const needs = [
+        ...(hasToken ? [] : ['token']),
+        ...(hasTarget ? [] : [backend === 'telegram' ? 'chat ID' : 'channel ID']),
+      ];
+      return [
+        ...(selected ? ['Selected'] : []),
+        needs.length ? `Needs ${needs.join(' + ')}` : 'Ready',
+      ].join(' · ');
+    };
+    setPicker({
+      title: 'Channel Type Settings',
+      description: 'Choose a type. Selected is the active backend; Ready means token and main target are set.',
+      help: '↑/↓ Select · Enter Open · Esc Back',
+      indexMode: 'always',
+      labelWidth: 18,
+      items: [
+        {
+          value: 'discord',
+          label: 'Discord',
+          description: typeDescription('discord'),
+          _backend: 'discord',
+        },
+        {
+          value: 'telegram',
+          label: 'Telegram',
+          description: typeDescription('telegram'),
+          _backend: 'telegram',
+        },
+      ],
+      onSelect: (value, item) => {
+        const backend = item?._backend || (value === 'telegram' ? 'telegram' : value === 'discord' ? 'discord' : null);
+        if (!backend) return;
+        setPicker(null);
+        openChannelTypeActionsPicker(backend, {
+          returnTo: () => openChannelSettingTypePicker(options),
+        });
+      },
+      onCancel: () => {
+        setPicker(null);
+        returnTo();
+      },
+    });
+  };
 
-  const openChannelSetupPicker = async (focus = 'all') => {
+  const openChannelSetupPicker = async (focus = 'all', options = {}) => {
     setProviderPrompt(null);
     setChannelPrompt(null);
     setHookPrompt(null);
@@ -5078,23 +6094,19 @@ export function App({ store, initialStatusLine = '' }) {
       setChannelPrompt(prompt);
     };
 
+    const channelRemoteEnabled = store.isRemoteEnabled?.() === true;
+
     if (focus === 'schedules') {
       const schedules = setup.schedules || [];
       const items = [
-        {
-          value: 'schedule-add',
-          label: 'Add schedule',
-          description: 'name | cron | instructions | optional channel | optional model',
-          _action: 'schedule-add',
-        },
         ...(schedules.length ? schedules.map((schedule) => {
         const enabled = schedule.enabled !== false;
         return {
           value: `schedule:${schedule.name}`,
           label: schedule.name,
           marker: enabled ? '●' : '○',
-          markerColor: enabled ? theme.success : theme.inactive,
-          description: `${schedule.time || '(no cron)'} · ${schedule.route}${schedule.model ? ` · ${schedule.model}` : ''}`,
+          markerColor: channelRemoteEnabled ? (enabled ? theme.success : theme.inactive) : theme.inactive,
+          description: `${schedule.time || '(no cron)'} · ${schedule.route}${schedule.model ? ` · ${schedule.model}` : ''}${channelRemoteEnabled ? '' : ' · channel off'}`,
           _action: 'schedule-toggle',
           _name: schedule.name,
           _enabled: enabled,
@@ -5105,40 +6117,87 @@ export function App({ store, initialStatusLine = '' }) {
           description: 'no schedules configured',
           _action: 'noop',
         }]),
+      ];
+      const toggleSchedule = (item) => {
+        if (item._action !== 'schedule-toggle') return;
+        if (!channelRemoteEnabled) {
+          store.pushNotice('enable channel first', 'warn');
+          return;
+        }
+        try {
+          store.setScheduleEnabled?.(item._name, !item._enabled);
+          void openChannelSetupPicker('schedules', { highlightValue: `schedule:${item._name}` });
+        } catch (e) {
+          store.pushNotice(`schedule toggle failed: ${e?.message || e}`, 'error');
+        }
+      };
+      setPicker({
+        title: 'Schedules',
+        description: channelRemoteEnabled ? 'Enable or disable cron schedules.' : 'Enable channel to toggle schedules.',
+        initialIndex: Math.max(0, items.findIndex((entry) => entry.value === options.highlightValue)),
+        items,
+        onSelect: (_value, item) => toggleSchedule(item),
+        onLeft: (item) => toggleSchedule(item),
+        onRight: (item) => toggleSchedule(item),
+        onCancel: () => {
+          setPicker(null);
+        },
+      });
+      return;
+    }
+
+    if (focus === 'webhook-endpoint') {
+      const returnTo = typeof options.returnTo === 'function'
+        ? options.returnTo
+        : () => setPicker(null);
+      const domain = setup.webhook?.ngrokDomain || setup.webhook?.domain || '';
+      const items = [
+        {
+          value: 'endpoint-domain',
+          label: 'ngrok domain',
+          description: domain ? domain : 'Not set · Enter ngrok domain',
+          _action: 'endpoint-domain',
+        },
         {
-          value: 'back',
-          label: 'Back',
-          description: 'return to channel setup',
-          _action: 'back',
+          value: 'endpoint-authtoken',
+          label: 'authtoken',
+          description: setup.webhook?.authenticated === true ? 'Set' : 'Not set · Enter authtoken',
+          _action: 'endpoint-authtoken',
         },
       ];
       setPicker({
-        title: 'Schedules',
-        description: 'Add, enable, or disable cron schedules.',
+        title: 'Webhook endpoint',
+        description: 'ngrok domain and authtoken. Toggle individual webhooks in /webhooks.',
+        help: '↑/↓ Select · Enter Edit · Esc Back',
+        indexMode: 'always',
+        labelWidth: 18,
         items,
         onSelect: (_value, item) => {
           try {
-            if (item._action === 'schedule-add') {
+            if (item._action === 'endpoint-domain') {
               openChannelPrompt({
-                kind: 'schedule-add',
-                label: 'Add schedule',
-                hint: 'Format: name | cron (5 or 6 fields) | instructions | channel(optional) | model(required with channel)',
+                kind: 'webhook-domain',
+                label: 'ngrok domain',
+                hint: 'Paste the reserved ngrok domain (e.g. my-app.ngrok-free.app).',
+                afterSave: () => void openChannelSetupPicker('webhook-endpoint', options),
               });
               return;
             }
-            if (item._action === 'back') {
-              void openChannelSetupPicker('all');
-              return;
+            if (item._action === 'endpoint-authtoken') {
+              openChannelPrompt({
+                kind: 'webhook-token',
+                label: 'Webhook/ngrok authtoken',
+                hint: 'Paste the webhook/ngrok authtoken. It is stored in the OS keychain.',
+                afterSave: () => void openChannelSetupPicker('webhook-endpoint', options),
+              });
             }
-            if (item._action !== 'schedule-toggle') return;
-            store.setScheduleEnabled?.(item._name, !item._enabled);
-            void openChannelSetupPicker('schedules');
           } catch (e) {
-            store.pushNotice(`schedule toggle failed: ${e?.message || e}`, 'error');
+            store.pushNotice(`webhook endpoint failed: ${e?.message || e}`, 'error');
           }
         },
         onCancel: () => {
           setPicker(null);
+          returnTo();
         },
       });
       return;
@@ -5146,31 +6205,15 @@ export function App({ store, initialStatusLine = '' }) {
 
     if (focus === 'webhooks') {
       const hooks = setup.webhooks || [];
-      const serverEnabled = setup.webhook.enabled !== false;
       const items = [
-        {
-          value: 'webhook-add',
-          label: 'Add webhook',
-          description: 'name | instructions | optional channel | optional model | parser',
-          _action: 'webhook-add',
-        },
-        {
-          value: 'webhook-server',
-          label: 'Webhook server',
-          marker: serverEnabled ? '●' : '○',
-          markerColor: serverEnabled ? theme.success : theme.inactive,
-          description: `port ${setup.webhook.port || 3333} · auth ${setup.webhook.status}`,
-          _action: 'server-toggle',
-          _enabled: serverEnabled,
-        },
         ...(hooks.length ? hooks.map((hook) => {
           const enabled = hook.enabled !== false;
           return {
             value: `webhook:${hook.name}`,
             label: hook.name,
             marker: enabled ? '●' : '○',
-            markerColor: enabled ? theme.success : theme.inactive,
-            description: `${hook.parser || 'github'} · ${hook.route} · secret:${hook.secretSet ? 'set' : 'missing'}`,
+            markerColor: channelRemoteEnabled ? (enabled ? theme.success : theme.inactive) : theme.inactive,
+            description: `${hook.parser || 'github'} · ${hook.route} · secret:${hook.secretSet ? 'set' : 'missing'}${channelRemoteEnabled ? '' : ' · channel off'}`,
             _action: 'webhook-toggle',
             _name: hook.name,
             _enabled: enabled,
@@ -5181,44 +6224,28 @@ export function App({ store, initialStatusLine = '' }) {
           description: 'no webhook endpoints configured',
           _action: 'noop',
         }]),
-        {
-          value: 'back',
-          label: 'Back',
-          description: 'return to channel setup',
-          _action: 'back',
-        },
       ];
+      const toggleWebhook = (item) => {
+        if (item._action !== 'webhook-toggle') return;
+        if (!channelRemoteEnabled) {
+          store.pushNotice('enable channel first', 'warn');
+          return;
+        }
+        try {
+          store.setWebhookEnabled?.(item._name, !item._enabled);
+          void openChannelSetupPicker('webhooks', { highlightValue: `webhook:${item._name}` });
+        } catch (e) {
+          store.pushNotice(`webhook toggle failed: ${e?.message || e}`, 'error');
+        }
+      };
       setPicker({
         title: 'Webhooks',
-        description: 'Manage inbound webhook endpoints and server settings.',
+        description: channelRemoteEnabled ? 'Enable or disable inbound webhook endpoints.' : 'Enable channel to toggle webhooks.',
+        initialIndex: Math.max(0, items.findIndex((entry) => entry.value === options.highlightValue)),
         items,
-        onSelect: (_value, item) => {
-          try {
-            if (item._action === 'webhook-add') {
-              openChannelPrompt({
-                kind: 'webhook-add',
-                label: 'Add webhook',
-                hint: 'Format: name | instructions | channel(optional) | model(required with channel) | parser(github/generic/stripe/sentry)',
-              });
-              return;
-            }
-            if (item._action === 'back') {
-              void openChannelSetupPicker('all');
-              return;
-            }
-            if (item._action === 'server-toggle') {
-              store.setWebhookConfig?.({ enabled: !item._enabled });
-              void openChannelSetupPicker('webhooks');
-              return;
-            }
-            if (item._action === 'webhook-toggle') {
-              store.setWebhookEnabled?.(item._name, !item._enabled);
-              void openChannelSetupPicker('webhooks');
-            }
-          } catch (e) {
-            store.pushNotice(`webhook toggle failed: ${e?.message || e}`, 'error');
-          }
-        },
+        onSelect: (_value, item) => toggleWebhook(item),
+        onLeft: (item) => toggleWebhook(item),
+        onRight: (item) => toggleWebhook(item),
         onCancel: () => {
           setPicker(null);
         },
@@ -5227,144 +6254,128 @@ export function App({ store, initialStatusLine = '' }) {
     }
 
     const worker = store.getChannelWorkerStatus?.();
-    const serverEnabled = setup.webhook.enabled !== false;
+    const activeBackend = setup.backend === 'telegram' ? 'telegram' : 'discord';
+    const backendLabel = activeBackend === 'telegram' ? 'Telegram' : 'Discord';
+    const remoteEnabled = store.isRemoteEnabled?.() === true;
+    const boolLabel = (enabled) => enabled ? 'On' : 'Off';
+    // Onboarding Step 5 reuses this root picker with a ConfirmBar. Reopens after
+    // a toggle must carry the onboarding context (confirmBar + flag) forward so
+    // Back/Finish stay wired and the general /channels path keeps its own opts.
+    const reopenRoot = (extra = {}) => {
+      const preserved = options.onboarding
+        ? { onboarding: true, confirmBar: options.confirmBar || null }
+        : {};
+      void openChannelSetupPicker('all', { ...preserved, ...extra });
+    };
+    const applyRemoteRuntime = (highlightValue = 'remote-runtime') => {
+      const enabled = store.toggleRemote?.() === true;
+      store.pushNotice(enabled ? 'Remote mode ON' : 'Remote mode OFF', 'info');
+      reopenRoot({ highlightValue });
+    };
+    const cycleChannelBackend = (direction = 1, highlightValue = 'channel-backend') => {
+      const backends = ['discord', 'telegram'];
+      const currentIndex = Math.max(0, backends.indexOf(activeBackend));
+      const chosen = backends[(currentIndex + direction + backends.length) % backends.length];
+      if (chosen === activeBackend) {
+        reopenRoot({ highlightValue, backendOverride: activeBackend });
+        return;
+      }
+      try {
+        store.setBackend(chosen);
+        const label = chosen === 'telegram' ? 'Telegram' : 'Discord';
+        const restartHint = (store.isRemoteEnabled?.() === true || worker?.running)
+          ? `Channel set to ${label}. Restart remote to apply.`
+          : `Channel set to ${label}.`;
+        store.pushNotice(restartHint, 'info');
+      } catch (e) {
+        store.pushNotice(`channel backend failed: ${e?.message || e}`, 'error');
+      }
+      reopenRoot({ highlightValue, backendOverride: chosen });
+    };
     const items = [
       {
-        value: 'worker-status',
-        label: 'Channel runtime',
-        description: worker?.running ? `running · pid ${worker.pid}` : 'stopped',
-        _action: 'worker-status',
-      },
-      {
-        value: 'discord-token',
-        label: 'Discord token',
-        description: `Bot token · ${setup.discord.status}${setup.discord.problem ? ' · invalid' : ''}`,
-        _action: 'discord-token',
-      },
-      {
-        value: 'channel-add',
-        label: 'Add channel',
-        description: 'name | channelId | mode(interactive/broadcast)',
-        _action: 'channel-add',
+        value: 'remote-runtime',
+        label: 'Remote Runtime',
+        meta: boolLabel(remoteEnabled),
+        description: worker?.running ? `Running · pid ${worker.pid}` : 'Stopped',
+        _action: 'remote-runtime',
       },
       {
-        value: 'schedules',
-        label: 'Schedules',
-        description: `${(setup.schedules || []).length} configured`,
-        _action: 'schedules',
+        value: 'channel-backend',
+        label: 'Channel',
+        meta: backendLabel,
+        description: 'Select Discord or Telegram',
+        _action: 'channel-backend',
       },
       {
-        value: 'schedule-add',
-        label: 'Add schedule',
-        description: 'name | cron | instructions | optional channel | optional model',
-        _action: 'schedule-add',
+        value: 'channel-setting',
+        label: 'Setting',
+        description: 'Token and main target',
+        _action: 'channel-setting',
       },
       {
-        value: 'webhook-token',
-        label: 'Webhook auth',
-        description: `ngrok/webhook authtoken · ${setup.webhook.status}`,
-        _action: 'webhook-token',
-      },
-      {
-        value: 'webhook-toggle',
-        label: 'Webhook server',
-        marker: serverEnabled ? '●' : '○',
-        markerColor: serverEnabled ? theme.success : theme.inactive,
-        description: `${serverEnabled ? 'enabled' : 'disabled'} · port ${setup.webhook.port || 3333}`,
-        _action: 'webhook-toggle',
-        _enabled: serverEnabled,
-      },
-      {
-        value: 'webhooks',
-        label: 'Webhooks',
-        description: `${(setup.webhooks || []).length} configured`,
-        _action: 'webhooks',
-      },
-      {
-        value: 'webhook-add',
-        label: 'Add webhook',
-        description: 'name | instructions | optional channel | optional model | parser',
-        _action: 'webhook-add',
+        value: 'webhook-endpoint',
+        label: 'Webhook endpoint',
+        meta: (() => {
+          const hasDomain = Boolean(setup.webhook?.ngrokDomain || setup.webhook?.domain);
+          const hasAuth = setup.webhook?.authenticated === true;
+          return (hasDomain && hasAuth) ? 'On' : 'Off';
+        })(),
+        description: (() => {
+          const hasDomain = Boolean(setup.webhook?.ngrokDomain || setup.webhook?.domain);
+          const hasAuth = setup.webhook?.authenticated === true;
+          const needs = [
+            ...(hasDomain ? [] : ['domain']),
+            ...(hasAuth ? [] : ['authtoken']),
+          ];
+          return needs.length ? `Needs ${needs.join(' + ')}` : 'ngrok domain and authtoken set';
+        })(),
+        _action: 'webhook-endpoint',
       },
-      ...((setup.channels || []).map((ch) => ({
-          value: `channel:${ch.name}`,
-          label: `# ${ch.name}`,
-          description: `${ch.channelId || '(unset)'} · ${ch.mode}${ch.main ? ' · main' : ''} · edit`,
-          _action: 'channel-edit',
-          _channel: ch,
-        }))),
     ];
 
     setPicker({
       title: 'Channels',
-      description: 'Discord token, channels, schedules, and webhooks.',
+      description: 'Remote access and channel setup.',
+      // Onboarding overlays a ConfirmBar (←/→ drive Back/Finish, not toggles),
+      // so drop the ←/→ Change hint there and use the Picker's ConfirmBar help.
+      help: options.confirmBar ? undefined : '↑/↓ Select · ←/→ Change · Enter Choose/Toggle · Esc Back',
+      indexMode: 'always',
+      labelWidth: 18,
+      metaWidth: 12,
+      pickerKey: `channels:${activeBackend}:${remoteEnabled ? 'on' : 'off'}:${options.highlightValue || 'root'}`,
+      initialIndex: Math.max(0, items.findIndex((entry) => entry.value === options.highlightValue)),
       items,
+      confirmBar: options.confirmBar || null,
+      onLeft: options.confirmBar ? undefined : (item) => {
+        if (item?._action === 'remote-runtime') applyRemoteRuntime(item.value);
+        else if (item?._action === 'channel-backend') cycleChannelBackend(-1, item.value);
+      },
+      onRight: options.confirmBar ? undefined : (item) => {
+        if (item?._action === 'remote-runtime') applyRemoteRuntime(item.value);
+        else if (item?._action === 'channel-backend') cycleChannelBackend(1, item.value);
+      },
       onSelect: (_value, item) => {
         try {
-          if (item._action === 'worker-status') {
-            store.pushNotice(worker?.running ? `channel runtime running: pid ${worker.pid}` : 'channel runtime stopped', 'info');
-            return;
-          }
-          if (item._action === 'discord-token') {
-            openChannelPrompt({
-              kind: 'discord-token',
-              label: 'Discord bot token',
-              hint: 'Paste the Discord bot token. It is stored in the OS keychain.',
-            });
-            return;
-          }
-          if (item._action === 'webhook-token') {
-            openChannelPrompt({
-              kind: 'webhook-token',
-              label: 'Webhook/ngrok authtoken',
-              hint: 'Paste the webhook/ngrok authtoken. It is stored in the OS keychain.',
-            });
-            return;
-          }
-          if (item._action === 'channel-add') {
-            openChannelPrompt({
-              kind: 'channel-add',
-              label: 'Add channel',
-              hint: 'Format: name | Discord channel ID | mode(interactive/broadcast) | main(optional)',
-            });
+          if (item._action === 'remote-runtime') {
+            applyRemoteRuntime(item.value);
             return;
           }
-          if (item._action === 'channel-edit') {
-            const ch = item._channel || {};
-            openChannelPrompt({
-              kind: 'channel-add',
-              label: `Edit channel · ${ch.name}`,
-              hint: `Format: ${ch.name} | ${ch.channelId || '<channel-id>'} | ${ch.mode || 'interactive'} | ${ch.main ? 'main' : 'main(optional)'}`,
-            });
+          if (item._action === 'channel-backend') {
+            cycleChannelBackend(1, item.value);
             return;
           }
-          if (item._action === 'schedule-add') {
-            openChannelPrompt({
-              kind: 'schedule-add',
-              label: 'Add schedule',
-              hint: 'Format: name | cron (5 or 6 fields) | instructions | channel(optional) | model(required with channel)',
+          if (item._action === 'channel-setting') {
+            openChannelSettingTypePicker({
+              returnTo: () => reopenRoot({ highlightValue: 'channel-setting' }),
             });
             return;
           }
-          if (item._action === 'webhook-add') {
-            openChannelPrompt({
-              kind: 'webhook-add',
-              label: 'Add webhook',
-              hint: 'Format: name | instructions | channel(optional) | model(required with channel) | parser(github/generic/stripe/sentry)',
+          if (item._action === 'webhook-endpoint') {
+            void openChannelSetupPicker('webhook-endpoint', {
+              ...(options.onboarding ? { onboarding: true, confirmBar: options.confirmBar || null } : {}),
+              returnTo: () => reopenRoot({ highlightValue: 'webhook-endpoint' }),
             });
-            return;
-          }
-          if (item._action === 'webhook-toggle') {
-            store.setWebhookConfig?.({ enabled: !item._enabled });
-            void openChannelSetupPicker('all');
-            return;
-          }
-          if (item._action === 'schedules') {
-            void openChannelSetupPicker('schedules');
-            return;
-          }
-          if (item._action === 'webhooks') {
-            void openChannelSetupPicker('webhooks');
           }
         } catch (e) {
           store.pushNotice(`channels update failed: ${e?.message || e}`, 'error');
@@ -5372,6 +6383,8 @@ export function App({ store, initialStatusLine = '' }) {
       },
       onCancel: () => {
         setPicker(null);
+        // Onboarding Step 5 Esc mirrors the other steps' reopen-next-launch warning.
+        if (options.onboarding) onboardingWarnReopen();
       },
     });
   };
@@ -5387,46 +6400,7 @@ export function App({ store, initialStatusLine = '' }) {
     return { ...status, servers: status.servers || [] };
   };
 
-  const openMcpServerPicker = (server) => {
-    if (server?.error) store.pushNotice(`${server.name}: ${server.error}`, 'warn');
-    const enabled = server?.enabled !== false;
-    const items = [
-      {
-        value: enabled ? 'disable' : 'enable',
-        label: enabled ? 'Disable server' : 'Enable server',
-        description: server?.configured ? `${server?.status || 'unknown'} · ${server?.transport || 'unknown'}` : 'server is not configured',
-        _action: server?.configured ? (enabled ? 'disable' : 'enable') : 'noop',
-      },
-      {
-        value: 'reconnect',
-        label: 'Reconnect server',
-        description: 'refresh configured MCP servers',
-        _action: 'reconnect',
-      },
-    ];
-    setPicker({
-      title: `MCP · ${server?.name || 'server'}`,
-      description: 'Enable, disable, or reconnect this MCP server.',
-      items,
-      onSelect: (_toolValue, toolItem) => {
-        setPicker(null);
-        if (toolItem._action === 'enable' || toolItem._action === 'disable') {
-          void store.setMcpServerEnabled?.(server.name, toolItem._action === 'enable')
-            .then(() => openMcpServersPicker())
-            .catch((e) => store.pushNotice(`mcp toggle failed: ${e?.message || e}`, 'error'));
-          return;
-        }
-        if (toolItem._action === 'reconnect') {
-          void store.reconnectMcp?.()
-            .then(() => openMcpServersPicker())
-            .catch((e) => store.pushNotice(`mcp reconnect failed: ${e?.message || e}`, 'error'));
-        }
-      },
-      onCancel: () => openMcpServersPicker(),
-    });
-  };
-
-  const openMcpServersPicker = () => {
+  const openMcpServersPicker = (options = {}) => {
     const status = mcpStatus();
     if (!status) return;
     const servers = status.servers || [];
@@ -5440,27 +6414,36 @@ export function App({ store, initialStatusLine = '' }) {
       });
     }
     for (const server of servers) {
+      const enabled = server.enabled !== false;
       items.push({
         value: `server:${server.name}`,
-        label: server.enabled === false ? `${server.name} (off)` : server.name,
+        label: server.name,
+        marker: enabled ? '●' : '○',
+        markerColor: enabled ? theme.success : theme.inactive,
         description: `${server.status || 'unknown'} · ${server.transport || 'unknown'} · ${server.toolCount || 0} tools${server.error ? ` · ${server.error}` : ''}`,
         _action: 'server',
         _server: server,
+        _enabled: enabled,
       });
     }
     setProviderPrompt(null);
     setChannelPrompt(null);
     setHookPrompt(null);
     setSettingsPrompt(null);
+    const toggleServer = (item) => {
+      if (item._action !== 'server' || !item._server?.name) return;
+      void store.setMcpServerEnabled?.(item._server.name, !item._enabled)
+        .then(() => openMcpServersPicker({ highlightValue: `server:${item._server.name}` }))
+        .catch((e) => store.pushNotice(`mcp toggle failed: ${e?.message || e}`, 'error'));
+    };
     setPicker({
       title: 'MCP servers',
-      description: 'Configured MCP servers and connection status.',
+      description: 'Enable or disable configured MCP servers.',
+      initialIndex: Math.max(0, items.findIndex((entry) => entry.value === options?.highlightValue)),
       items,
-      onSelect: (_value, item) => {
-        setPicker(null);
-        if (item._action !== 'server') return;
-        openMcpServerPicker(item._server);
-      },
+      onSelect: (_value, item) => toggleServer(item),
+      onLeft: (item) => toggleServer(item),
+      onRight: (item) => toggleServer(item),
       onCancel: () => {
         setPicker(null);
       },
@@ -5524,10 +6507,11 @@ export function App({ store, initialStatusLine = '' }) {
     });
   };
 
-  const openSkillsPicker = () => {
+  const openSkillsPicker = (options = {}) => {
     const status = skillsStatus();
     if (!status) return;
     const skills = status.skills || [];
+    const disabledSet = options.disabledOverride instanceof Set ? options.disabledOverride : disabledSkills;
     const items = [];
     if (skills.length === 0) {
       items.push({
@@ -5538,28 +6522,39 @@ export function App({ store, initialStatusLine = '' }) {
       });
     }
     for (const skill of skills) {
-      const disabled = disabledSkills.has(skill.name);
+      const enabled = !disabledSet.has(skill.name);
       items.push({
         value: skill.name,
-        label: disabled ? `${skill.name} (disabled)` : skill.name,
-        description: `${disabled ? 'disabled · ' : ''}${skill.source || 'skill'} · ${skill.description || skill.filePath || ''}`,
+        label: skill.name,
+        marker: enabled ? '●' : '○',
+        markerColor: enabled ? theme.success : theme.inactive,
+        description: `${skill.source || 'skill'} · ${skill.description || skill.filePath || ''}`,
         _action: 'skill',
         _skill: skill,
+        _enabled: enabled,
       });
     }
     setProviderPrompt(null);
     setChannelPrompt(null);
     setHookPrompt(null);
     setSettingsPrompt(null);
+    const toggleSkill = (item) => {
+      if (item._action !== 'skill' || !item._skill?.name) return;
+      const name = item._skill.name;
+      const next = new Set(disabledSet);
+      if (item._enabled) next.add(name); else next.delete(name);
+      setDisabledSkills(next);
+      store.pushNotice(`skill ${item._enabled ? 'disabled' : 'enabled'}: ${name}`, 'info');
+      openSkillsPicker({ highlightValue: name, disabledOverride: next });
+    };
     setPicker({
       title: 'Skills',
-      description: 'Project skills available to the assistant.',
+      description: 'Enable or disable project skills.',
+      initialIndex: Math.max(0, items.findIndex((entry) => entry.value === options.highlightValue)),
       items,
-      onSelect: (_value, item) => {
-        setPicker(null);
-        if (item._action !== 'skill' || !item._skill?.name) return;
-        openSkillDetailPicker(item._skill);
-      },
+      onSelect: (_value, item) => toggleSkill(item),
+      onLeft: (item) => toggleSkill(item),
+      onRight: (item) => toggleSkill(item),
       onCancel: () => {
         setPicker(null);
       },
@@ -5841,21 +6836,22 @@ export function App({ store, initialStatusLine = '' }) {
     setChannelPrompt(null);
     setHookPrompt(null);
     setSettingsPrompt(null);
+    const toggleRule = (item) => {
+      if (item._action !== 'rule') return;
+      try {
+        store.setHookRuleEnabled?.(item._rule.index, !item._rule.enabled);
+        void openHooksPicker();
+      } catch (e) {
+        store.pushNotice(`hook toggle failed: ${e?.message || e}`, 'error');
+      }
+    };
     setPicker({
       title: 'Hooks',
       description: 'Before-tool hook rules; Enter toggles a rule.',
       items,
-      onSelect: (_value, item) => {
-        setPicker(null);
-        if (item._action === 'rule') {
-          try {
-            store.setHookRuleEnabled?.(item._rule.index, !item._rule.enabled);
-            void openHooksPicker();
-          } catch (e) {
-            store.pushNotice(`hook toggle failed: ${e?.message || e}`, 'error');
-          }
-        }
-      },
+      onSelect: (_value, item) => toggleRule(item),
+      onLeft: (item) => toggleRule(item),
+      onRight: (item) => toggleRule(item),
       onCancel: () => {
         setPicker(null);
       },
@@ -5925,6 +6921,126 @@ export function App({ store, initialStatusLine = '' }) {
       .catch((e) => store.pushNotice(`memory failed: ${e?.message || e}`, 'error'));
   };
 
+  const openUpdatePicker = (options = {}) => {
+    const returnTo = typeof options.returnTo === 'function' ? options.returnTo : null;
+    const readSettings = () => {
+      try { return store.getUpdateSettings?.() || {}; } catch { return {}; }
+    };
+    const readStatus = () => {
+      try { return store.getUpdateStatus?.() || { phase: 'idle' }; } catch { return { phase: 'idle' }; }
+    };
+    const render = ({ checking = false } = {}) => {
+      const upd = readSettings();
+      const status = readStatus();
+      const current = upd.currentVersion || 'unknown';
+      const latestMeta = checking || status.phase === 'checking'
+        ? 'checking…'
+        : (upd.latestVersion || 'unknown');
+      const items = [
+        {
+          value: 'current',
+          label: 'Current version',
+          meta: current,
+          description: 'Installed mixdog version.',
+          _action: 'current',
+        },
+        {
+          value: 'latest',
+          label: 'Latest version',
+          meta: latestMeta,
+          description: 'Enter to re-check now.',
+          _action: 'latest',
+        },
+        {
+          value: 'auto-update',
+          label: 'Auto-update',
+          meta: upd.autoUpdate ? 'On' : 'Off',
+          description: '←/→ or Enter to toggle automatic updates.',
+          _action: 'auto-update',
+        },
+        {
+          value: 'update-now',
+          label: 'Update now',
+          description: upd.updateAvailable
+            ? `Install ${upd.latestVersion || 'latest'}.`
+            : 'Check and install the latest version.',
+          _action: 'update-now',
+        },
+      ];
+      setProviderPrompt(null);
+      setChannelPrompt(null);
+      setHookPrompt(null);
+      setSettingsPrompt(null);
+      setPicker({
+        title: 'Update',
+        description: 'Check version and update mixdog.',
+        help: '↑/↓ Select · ←/→ Change · Enter Open/Toggle · Esc Close',
+        indexMode: 'always',
+        labelWidth: 16,
+        metaWidth: 16,
+        fillAvailable: true,
+        items,
+        onLeft: (item) => {
+          if (item?._action === 'auto-update') toggleAutoUpdate(!upd.autoUpdate);
+        },
+        onRight: (item) => {
+          if (item?._action === 'auto-update') toggleAutoUpdate(!upd.autoUpdate);
+        },
+        onSelect: (_value, item) => {
+          if (item?._action === 'latest') {
+            recheck();
+          } else if (item?._action === 'auto-update') {
+            toggleAutoUpdate(!upd.autoUpdate);
+          } else if (item?._action === 'update-now') {
+            runUpdate();
+          }
+        },
+        onCancel: () => {
+          setPicker(null);
+          if (returnTo) returnTo();
+        },
+      });
+    };
+    const toggleAutoUpdate = (enabled) => {
+      try {
+        void Promise.resolve(store.setAutoUpdate?.(enabled)).finally(() => render());
+        store.pushNotice(`Auto-update ${enabled ? 'on' : 'off'}`, 'info');
+      } catch (e) {
+        store.pushNotice(`auto-update failed: ${e?.message || e}`, 'error');
+      }
+      render();
+    };
+    const recheck = () => {
+      render({ checking: true });
+      void Promise.resolve(store.checkForUpdate?.({ force: true }))
+        .then(() => render())
+        .catch((e) => {
+          store.pushNotice(`update check failed: ${e?.message || e}`, 'error');
+          render();
+        });
+    };
+    const runUpdate = () => {
+      store.pushNotice('Updating…', 'info');
+      void Promise.resolve(store.runUpdateNow?.())
+        .then((result) => {
+          if (result?.ok) {
+            store.pushNotice(`v${result.version} installed — restart to apply`, 'info');
+          } else {
+            store.pushNotice(`Update failed: ${result?.error || 'unknown error'}`, 'error');
+          }
+          render();
+        })
+        .catch((e) => {
+          store.pushNotice(`Update failed: ${e?.message || e}`, 'error');
+          render();
+        });
+    };
+    render({ checking: true });
+    void Promise.resolve(store.checkForUpdate?.({}))
+      .then(() => render())
+      .catch(() => render());
+  };
+
   const openMemoryPicker = () => {
     setProviderPrompt(null);
     setChannelPrompt(null);
@@ -6325,6 +7441,19 @@ export function App({ store, initialStatusLine = '' }) {
           .then(ok => store.pushNotice(ok ? modelSwitchNotice() : 'Model switch is already running.', ok ? 'info' : 'warn'))
           .catch((e) => store.pushNotice(`Couldn’t switch model: ${e?.message || e}`, 'error'));
         return true;
+      case 'remote': {
+        const enabled = store.toggleRemote?.() === true;
+        store.pushNotice(enabled ? 'Remote mode ON' : 'Remote mode OFF', 'info');
+        return true;
+      }
+      case 'voice': {
+        // Step1 only: toggleVoice() owns config persistence (voice.enabled) +
+        // the missing-component install sequence + its own notices (OFF/ON/
+        // progress/failure). We don't push a redundant notice here; a null
+        // return means "already running" or "failed", both already noticed.
+        void toggleVoice({ pushNotice: store.pushNotice });
+        return true;
+      }
       case 'search':
         if (state.busy) {
           store.pushNotice('wait for the current turn to finish before /search', 'warn');
@@ -6623,6 +7752,9 @@ export function App({ store, initialStatusLine = '' }) {
       case 'profile':
         openProfilePicker();
         return true;
+      case 'update':
+        openUpdatePicker();
+        return true;
       case 'quit':
         requestExit();
         return true;
@@ -6750,26 +7882,42 @@ export function App({ store, initialStatusLine = '' }) {
         return false;
       }
       try {
+        const resumeAfterChannelPrompt = (prompt) => {
+          const afterSave = prompt?.afterSave;
+          setChannelPrompt(null);
+          if (typeof afterSave === 'function') afterSave();
+          else void openChannelSetupPicker('all');
+        };
         if (channelPrompt.kind === 'discord-token') {
           if (!commandText) return false;
           store.saveDiscordToken(commandText);
-          setChannelPrompt(null);
-          void openChannelSetupPicker('all');
+          resumeAfterChannelPrompt(channelPrompt);
+          return true;
+        }
+        if (channelPrompt.kind === 'telegram-token') {
+          if (!commandText) return false;
+          store.saveTelegramToken(commandText);
+          resumeAfterChannelPrompt(channelPrompt);
           return true;
         }
         if (channelPrompt.kind === 'webhook-token') {
           if (!commandText) return false;
           store.saveWebhookAuthtoken(commandText);
-          setChannelPrompt(null);
-          void openChannelSetupPicker('all');
+          resumeAfterChannelPrompt(channelPrompt);
+          return true;
+        }
+        if (channelPrompt.kind === 'webhook-domain') {
+          if (!commandText) return false;
+          store.setWebhookConfig?.({ ngrokDomain: commandText });
+          resumeAfterChannelPrompt(channelPrompt);
           return true;
         }
         const parts = commandText.split('|').map((part) => part.trim());
         if (channelPrompt.kind === 'channel-add') {
-          const [name, channelId, mode] = parts;
-          store.saveChannel({ name, channelId, mode });
-          setChannelPrompt(null);
-          void openChannelSetupPicker('all');
+          const [name, channelId, mode, mainFlag] = parts;
+          const main = String(mainFlag || '').toLowerCase() === 'main' || String(name || '').toLowerCase() === 'main';
+          store.saveChannel({ name, channelId, mode, main, backend: channelPrompt.backend });
+          resumeAfterChannelPrompt(channelPrompt);
           return true;
         }
         if (channelPrompt.kind === 'schedule-add') {
@@ -7015,6 +8163,8 @@ export function App({ store, initialStatusLine = '' }) {
   }, [slashCommands.length, activeSlashQuery]);
 
   const onPromptDraftChange = useCallback((value) => {
+    if (String(value ?? '').length > 0) dismissWelcomePromptHint();
+    syncPromptLayoutRows(value);
     const suppressPromptHint = promptHistoryDraftChangeRef.current;
     promptHistoryDraftChangeRef.current = false;
     const historyNav = promptHistoryNavRef.current;
@@ -7053,7 +8203,7 @@ export function App({ store, initialStatusLine = '' }) {
     if (slashDismissedFor) {
       setSlashDismissedFor((dismissed) => (dismissed && dismissed !== value ? '' : dismissed));
     }
-  }, [clearPromptHint, resetPromptHistoryNav, showPromptHint, slashDismissedFor]);
+  }, [clearPromptHint, dismissWelcomePromptHint, resetPromptHistoryNav, showPromptHint, slashDismissedFor, syncPromptLayoutRows]);
 
   const cancelProviderPrompt = useCallback(() => {
     try { providerPrompt?.login?.cancel?.(); } catch {}
@@ -7066,8 +8216,12 @@ export function App({ store, initialStatusLine = '' }) {
   }, [providerPrompt, showPromptHint]);
 
   const cancelChannelPrompt = useCallback(() => {
+    const onCancel = channelPrompt?.onCancel;
+    const afterSave = channelPrompt?.afterSave;
     setChannelPrompt(null);
-  }, [showPromptHint]);
+    if (typeof onCancel === 'function') onCancel();
+    else if (typeof afterSave === 'function') afterSave();
+  }, [channelPrompt, showPromptHint]);
 
   const cancelHookPrompt = useCallback(() => {
     setHookPrompt(null);
@@ -7245,7 +8399,8 @@ export function App({ store, initialStatusLine = '' }) {
   //                  − welcome header  (empty transcript only)
   //                  − live status     (thinking / spinner / TurnDone)
   //                  − queued prompts  (marginTop 1 + N rows, only when queued)
-  //                  − input box       (marginTop 1 + 2 border + 1 content)
+  //                  − prompt meta     (spinner / transient message / queued)
+  //                  − input box       (2 border + wrapped content)
   //                  − statusline      (reserved L1 + L2 + outer gap; total 3 rows)
   //
   // Every sibling outside the viewport must be accounted for here; otherwise
@@ -7263,24 +8418,39 @@ export function App({ store, initialStatusLine = '' }) {
   // Slash search floats above the normal prompt. Actual option panels own the
   // prompt/status area, so they hide those rows and expand into that space.
   const inputBoxHidden = expandedOptionPanel;
-  const showWelcomeBanner = (state.items.length === 0 && !hasFloatingPanel) || projectSelectionActive;
+  const showWelcomeBanner = (state.items.length === 0 && !hasFloatingPanel) || projectSelectionActive || onboardingActive;
   const WELCOME_ROWS = showWelcomeBanner ? 11 : 0;
   const liveSpinner = state.spinner?.active ? state.spinner : (state.commandStatus?.active ? state.commandStatus : null);
   const latestToast = state.toasts?.length ? state.toasts[state.toasts.length - 1] : null;
   const toastHint = latestToast ? latestToast.text : '';
   const inputHint = promptHint || toastHint;
   const inputHintTone = promptHint ? promptHintTone : (latestToast?.tone || 'info');
-  // While the slash palette is open it owns the area above the prompt, so the
-  // live spinner/meta row is suppressed entirely — no reservation and no render.
-  const promptMetaRows = !inputBoxHidden && liveSpinner && !slashPaletteOpen ? 2 : 0;
+  const latestTranscriptItem = state.items[state.items.length - 1] || null;
+  const latestDoneAtTail = latestTranscriptItem?.kind === 'turndone' || latestTranscriptItem?.kind === 'statusdone';
+  // Bottom meta band ownership is LIVE-SPINNER ONLY. A finished turn's done row
+  // (turndone/statusdone) is a normal transcript item and flows into scrollback
+  // like anything else, so the area directly above the prompt is CLEAR when the
+  // user is idle. Earlier this row was pinned in the meta band until the next
+  // transcript item was appended (to dodge an autowrap overprint/bleed), which
+  // left the completed status row stuck above the prompt while the user typed or
+  // sat idle. That bleed is now fixed at the source by the tool-output width
+  // clamp, so the pin is no longer needed. Kept as a named null const so the
+  // downstream meta-band/hint logic collapses cleanly to the spinner-only path.
+  const latestDoneItem = null;
   const SCROLL_HINT_ROWS = 0;
   const LIVE_STATUS_ROWS = 0;
-  // The standalone prompt box is 3 rows (round border + one input line). Normal
-  // mode keeps a one-row top gap, but slash mode pins the command palette flush
-  // to the prompt, so reserve only the actual prompt height there. Otherwise an
-  // extra reserved row remains below the statusline and the prompt appears one
-  // row too high.
-  const INPUT_BOX_ROWS = inputBoxHidden ? 0 : (slashPaletteOpen ? 3 : 4) + promptMetaRows;
+  // The standalone prompt box is 2 border rows + the wrapped PromptInput body.
+  // The one-row scroll baseline gap ABOVE the prompt is owned by
+  // transcriptGuardRows, not the prompt box itself. That keeps the scroll
+  // reference at "textbox + 1" while the prompt/statusline bottom stays fixed.
+  //
+  // This must track the prompt draft's REAL wrapped height. Reserving a constant
+  // one-line prompt lets long/multiline input grow the bottom cluster after the
+  // transcript viewport has already claimed those rows, which makes transcript
+  // body text overprint the textbox or slash command window.
+  const currentPromptLayoutRows = promptContentRows(promptLayoutValueRef.current, promptContentColumns);
+  const promptInputRows = inputBoxHidden ? 0 : currentPromptLayoutRows;
+  const promptBoxRows = inputBoxHidden ? 0 : 2 + promptInputRows;
   const STATUSLINE_ROWS = 3;
   // Shared panel chrome math. Every floating panel follows the same vertical
   // rhythm INSIDE its round border: title row, blank, description/hint row,
@@ -7297,11 +8467,26 @@ export function App({ store, initialStatusLine = '' }) {
   const TEXT_ENTRY_ROWS = PANEL_CHROME_ROWS + 1;
   const OPTION_PANEL_EXTRA_ROWS = expandedOptionPanel ? 3 : 0;
   const queuedVisible = !hasFloatingPanel && !inputBoxHidden && state.queued?.length > 0;
-  // QueuedCommands has its own top margin, and the prompt box drops its normal
-  // top margin while a queue is visible. Net extra height is therefore only the
-  // queued rows themselves; counting the queue margin as an extra row over-
-  // reserves by one and makes the bottom input cluster float upward.
+  // While the slash palette is open it owns the area above the prompt, so the
+  // live spinner/meta row is suppressed entirely — no reservation and no render.
+  // Normalize the spinner → TurnDone handoff by making them occupy the SAME
+  // two-row slot. Engine appends turndone/statusdone before clearing spinner, so
+  // a transient frame can otherwise contain BOTH: transcript grows by two rows
+  // while the bottom spinner still reserves two rows, making the viewport visibly
+  // jump. As soon as the done row is the transcript tail, drop the spinner slot;
+  // the new done row replaces that height in the same frame, with no ms timer.
+  const promptMetaVisible = !inputBoxHidden && !slashPaletteOpen && !!liveSpinner && !latestDoneAtTail;
+  const promptMetaRows = promptMetaVisible ? 2 : 0;
+  // Toast/error text without a live spinner uses the existing transcript guard
+  // row directly above the prompt. Do NOT reserve another row here: that made a
+  // transient hint add a visible newline/prompt jump whenever no spinner was
+  // active.
+  const overlayHintRequested = !inputBoxHidden && !hasFloatingPanel && !liveSpinner && !!inputHint && !queuedVisible;
+  const overlayHintRows = 0;
+  // QueuedCommands renders one row per queued command, pinned above the prompt
+  // box (no extra top-margin row).
   const queuedRows = queuedVisible ? state.queued.length : 0;
+  const INPUT_BOX_ROWS = promptBoxRows + promptMetaRows + overlayHintRows;
   const baseReserve = WELCOME_ROWS + SCROLL_HINT_ROWS + LIVE_STATUS_ROWS + INPUT_BOX_ROWS + STATUSLINE_ROWS + queuedRows;
   const maxFloatingPanelRows = Math.max(0, resizeState.rows - baseReserve - 1);
   const desiredFloatingPanelRows = toolApproval
@@ -7315,19 +8500,51 @@ export function App({ store, initialStatusLine = '' }) {
         : slashPaletteOpen
           ? PANEL_MAX_VISIBLE + PANEL_CHROME_ROWS
           : hasTextEntryPrompt
-            ? TEXT_ENTRY_ROWS + OPTION_PANEL_EXTRA_ROWS
+            ? TEXT_ENTRY_ROWS
             : 0;
   const floatingPanelRows = desiredFloatingPanelRows > 0
     ? Math.min(desiredFloatingPanelRows, maxFloatingPanelRows)
     : 0;
+  // Give the list every content row the panel exposes. The panel already grew
+  // by OPTION_PANEL_EXTRA_ROWS; previously that growth was subtracted back out
+  // here, so the rows leaked into an empty flexGrow gap instead of the list.
+  // Reserving only PICKER_CHROME_ROWS lets the list occupy the full interior
+  // (the footer's own reservation is handled inside Picker).
   const pickerVisibleRows = picker
-    ? Math.max(1, floatingPanelRows - PICKER_CHROME_ROWS - (picker.fillAvailable ? 0 : OPTION_PANEL_EXTRA_ROWS))
+    ? Math.max(1, floatingPanelRows - PICKER_CHROME_ROWS)
     : PANEL_MAX_VISIBLE;
   const bottomReserve = baseReserve + floatingPanelRows;
   const viewportHeight = Math.max(1, resizeState.rows - bottomReserve);
+  // Keep one physical row between the transcript clip and the bottom cluster
+  // even when pinned to the live tail. Windows Terminal/conhost can still
+  // surface one clipped/off-by-one transcript row below the statusline during
+  // rapid tool-card updates; a permanent guard row makes that row blank instead
+  // of a tool header/detail.
+  const baseGuardRows = viewportHeight > 1 ? 1 : 0;
+  // ── Scroll-time overprint guard ───────────────────────────────────────────
+  // Wheel/manual scroll pushes the transcript column DOWN via a negative
+  // marginBottom (see the viewport render). Under conhost/Windows Terminal the
+  // incremental redraw can leave the row that slid past the clip edge painted
+  // OVER the bottom cluster (input box / statusline) for a frame — the reported
+  // "scrolled text shows on the statusline row" bug. One guard row is enough
+  // while pinned to the live tail, but during an active scroll the slid row can
+  // still bleed one line further, so widen the guard to TWO rows whenever the
+  // viewport is genuinely scrolled up. The extra blank row absorbs the stray
+  // paint instead of the statusline. Requires a viewport tall enough to spare
+  // the row, and never shrinks below the base guard.
+  const transcriptGuardRows = baseGuardRows;
+  const transcriptContentHeight = Math.max(1, viewportHeight - transcriptGuardRows);
+  // Bottom-follow / pin semantics must NOT widen with the scroll-time guard, or
+  // the "pinned to tail" threshold would drift and streaming could freeze a row
+  // above bottom. Keep the slack anchored to the BASE (single) guard: if a stale
+  // pre-guard offset of 1 survives while no reading anchor is active, still treat
+  // the viewport as pinned to the live tail so streaming/tool output continues
+  // to auto-follow instead of freezing one row above bottom.
+  const transcriptBottomSlackRows = Math.max(0, baseGuardRows);
+  transcriptBottomSlackRowsRef.current = transcriptBottomSlackRows;
   transcriptViewportRef.current = {
     top: WELCOME_ROWS,
-    bottom: Math.max(WELCOME_ROWS, WELCOME_ROWS + viewportHeight - 1),
+    bottom: Math.max(WELCOME_ROWS, WELCOME_ROWS + transcriptContentHeight - 1),
   };
   // [mixdog] Keep the live terminal row count current for the mouse handler's
   // region routing + status-band selection clip (see onData).
@@ -7336,24 +8553,6 @@ export function App({ store, initialStatusLine = '' }) {
   // bottom area), drop its stale measured rect so the mouse handler does not
   // route presses to a prompt box that is not on screen.
   if (inputBoxHidden) promptBoxRectRef.current = null;
-  // Windows Terminal/conhost scrolls the alt-screen (auto-wrap/DECAWM) when the
-  // bottom-right cell is written, so reserve one cell on win32. Other platforms
-  // render at full width.
-  const rightSafetyColumns = process.platform === 'win32' ? 1 : 0;
-  const frameColumns = Math.max(1, resizeState.columns - rightSafetyColumns);
-  const promptMetaVisible = !inputBoxHidden && !!liveSpinner && !slashPaletteOpen;
-  // Same-row done hint: when the newest transcript row is a TurnDone/StatusDone
-  // and there is a transient hint to show (and no live spinner owns the status
-  // band), attach the hint to that done row's right side instead of reserving a
-  // separate overlay row. overlayHintVisible excludes this case so the hint is
-  // not double-painted.
-  const lastTranscriptItem = (state.items || []).at(-1) ?? null;
-  const lastItemIsDoneRow = lastTranscriptItem?.kind === 'turndone'
-    || lastTranscriptItem?.kind === 'statusdone';
-  const attachInputHintToTurnDone = !inputBoxHidden
-    && !liveSpinner
-    && !!inputHint
-    && lastItemIsDoneRow;
   // Toast/error text has two mutually exclusive placements:
   // - while a live status row exists (thinking/compacting/responding), attach it
   //   to that row so the bottom cluster reserves exactly one status band;
@@ -7361,13 +8560,32 @@ export function App({ store, initialStatusLine = '' }) {
   //   the blank spacer instead of reserving an extra row. This keeps late errors
   //   from pushing the prompt/statusline upward, and when thinking starts the
   //   hint moves into the live row on the same render instead of double-painting.
-  const overlayHintVisible = !inputBoxHidden && !liveSpinner && !!inputHint && !queuedVisible && floatingPanelRows <= 0 && !attachInputHintToTurnDone;
-  const transientStatusWidth = inputHint
+  // Transient hint placement while no spinner owns the band is resolved after
+  // transcript windowing (see overlayHintOnLastItem / overlayHintFallbackRow).
+  const spinnerHintWidth = inputHint
+    ? Math.max(1, Math.min(Math.max(1, frameColumns - 4), Math.max(12, Math.floor(frameColumns * 0.42))))
+    : 0;
+  // When no live spinner owns a status band, the transient hint/error is drawn
+  // into the existing transcript guard row directly above the prompt. Mirror the
+  // spinner-row placement: a fixed-width right slot, not a full-width left box.
+  const guardHintWidth = inputHint
     ? Math.max(1, Math.min(Math.max(1, frameColumns - 4), Math.max(12, Math.floor(frameColumns * 0.42))))
     : 0;
+  const transientStatusWidth = liveSpinner ? spinnerHintWidth : guardHintWidth;
   const promptSpinnerColumns = liveSpinner && inputHint
-    ? Math.max(1, frameColumns - transientStatusWidth - 1)
+    ? Math.max(1, frameColumns - spinnerHintWidth - 1)
     : frameColumns;
+  const welcomePromptHintText = conditionalWelcomePromptHint || welcomePromptHintRef.current || '';
+  const welcomePromptHintVisible = Boolean(
+    welcomePromptHintText
+    && !welcomePromptHintDismissed
+    && state.items.length === 0
+    && !hasFloatingPanel
+    && !inputBoxHidden
+    && !queuedVisible
+    && !liveSpinner
+    && !inputHint
+  );
   // Key the heavy O(n) row-index + windowing memos on a STRUCTURE signature
   // instead of the `state.items` array identity. The engine swaps `state.items`
   // for a new array on every streaming flush (~8ms) while only the final
@@ -7401,40 +8619,111 @@ export function App({ store, initialStatusLine = '' }) {
   // SAME render, so the completed line fills its space with no one-frame gap.
   // Falls back to the live scrollOffset state when there is no active anchor
   // (bottom-follow / pinned) or it cannot be aligned (anchor item gone).
-  const anchorLockActive = !!transcriptAnchorRef.current
+  const hasReadingAnchor = !!transcriptAnchorRef.current && !transcriptAnchorDirtyRef.current;
+  const scrolledUpRows = Math.max(0, Number(scrollTargetRef.current) || 0);
+  // "Genuinely scrolled up" = the viewport is above the bottom slack band. The
+  // bottom-follow / pinned path owns everything at-or-below the slack; anything
+  // above it is the user reading older transcript.
+  const scrolledUp = scrolledUpRows > transcriptBottomSlackRows;
+  // A genuine reading anchor wins even if followingRef is stale-true while the
+  // user is scrolled up. The follow-arm SHOULD have been cleared when the anchor
+  // was captured, but if it lingers true we must not fall through to the stale-
+  // offset render path (that is one half of the newline-jump bug). Keep the
+  // plain !following gate for the anchor-less follow case.
+  const anchorLockActive = hasReadingAnchor && !followingRef.current && scrolledUp;
+  const targetNearBottom = followingRef.current || !scrolledUp;
+  const nearBottomWithoutAnchor = !transcriptAnchorRef.current
     && !transcriptAnchorDirtyRef.current
-    && !followingRef.current;
-  let renderScrollOffset = scrollOffset;
+    && targetNearBottom;
+  let renderScrollOffset = targetNearBottom ? 0 : scrollOffset;
+  const lockViewRows = Math.max(1, Number(transcriptContentHeight) || 1);
+  const lockTotalRows = Math.max(0, Number(transcriptRowIndex?.totalRows) || 0);
+  const lockMaxRows = Math.max(0, lockTotalRows - lockViewRows);
+  const curPrefixForLock = transcriptRowIndex?.prefixRows || null;
   if (anchorLockActive) {
-    const lockViewRows = Math.max(1, Number(viewportHeight) || 1);
-    const lockTotalRows = Math.max(0, Number(transcriptRowIndex?.totalRows) || 0);
-    const lockMaxRows = Math.max(0, lockTotalRows - lockViewRows);
     const locked = resolveAnchorScrollOffset({
       anchor: transcriptAnchorRef.current,
       items: state.items,
-      curPrefix: transcriptRowIndex?.prefixRows || null,
+      curPrefix: curPrefixForLock,
       totalRows: lockTotalRows,
       viewRows: lockViewRows,
       maxRows: lockMaxRows,
     });
     if (locked != null) renderScrollOffset = locked;
+  } else if (!followingRef.current && !nearBottomWithoutAnchor && scrolledUp) {
+    // ── Same-frame anchor CAPTURE for the missing/dirty-anchor case ─────────
+    // The viewport is genuinely scrolled up but there is NO usable same-frame
+    // anchor: it is missing, or dirtied by a manual scroll whose synchronous
+    // capture failed, or a stale-true follow-arm already dropped it. Without an
+    // anchor this frame would render with the STALE bottom-relative
+    // scrollOffset, so any row growth THIS frame (a streaming newline
+    // completing a line, a transcript row expanding) shifts the visible top by
+    // the delta BEFORE the post-commit rowDelta effect can capture/correct — and
+    // that effect would then capture from the ALREADY-shifted totalRows. That is
+    // the confirmed one-frame jump/jitter.
+    //
+    // Fix it at render time: capture an anchor from the PREVIOUS published
+    // geometry (transcriptGeomRef still holds the prior frame here — THIS
+    // frame's geom is published a few lines below), identifying the item id +
+    // row offset that sat at the previous visible-TOP edge, then resolve the
+    // offset against the CURRENT prefix table with the same pure helper so that
+    // exact top row stays put THIS frame. Persist the captured anchor so the
+    // post-commit effect keeps the identical anchor stable instead of
+    // re-deriving one from the already-shifted totalRows.
+    const geom = transcriptGeomRef.current || {};
+    const prevPrefix = geom.prefixRows;
+    if (Array.isArray(prevPrefix) && prevPrefix.length > 1) {
+      const prevTotal = Math.max(0, Number(geom.totalRows) || 0);
+      const prevView = Math.max(1, Number(geom.viewRows) || 1);
+      const prevOffset = Math.max(0, Number(geom.renderOffset) || 0);
+      const prevItems = geom.items || [];
+      // Bottom-relative window math (same as transcriptRenderWindow): the top
+      // edge sits `offset + viewRows` rows up from the previous total.
+      const prevTopRow = Math.max(0, Math.min(prevTotal, prevTotal - prevOffset - prevView));
+      let idx = upperBound(prevPrefix, prevTopRow) - 1;
+      if (idx < 0) idx = 0;
+      if (idx > prevPrefix.length - 2) idx = prevPrefix.length - 2;
+      const anchorItem = prevItems[idx];
+      if (anchorItem && anchorItem.id != null) {
+        const captured = { id: anchorItem.id, offset: Math.max(0, prevTopRow - (prevPrefix[idx] || 0)) };
+        const locked = resolveAnchorScrollOffset({
+          anchor: captured,
+          items: state.items,
+          curPrefix: curPrefixForLock,
+          totalRows: lockTotalRows,
+          viewRows: lockViewRows,
+          maxRows: lockMaxRows,
+        });
+        if (locked != null) {
+          renderScrollOffset = locked;
+          transcriptAnchorRef.current = captured;
+          transcriptAnchorDirtyRef.current = false;
+        }
+      }
+    }
   }
   const transcriptWindow = useMemo(() => transcriptRenderWindow(state.items, {
     scrollOffset: renderScrollOffset,
-    viewportHeight,
+    viewportHeight: transcriptContentHeight,
     columns: frameColumns,
     toolOutputExpanded,
     rowIndex: transcriptRowIndex,
   // eslint-disable-next-line react-hooks/exhaustive-deps -- intentional: sig+scroll/viewport capture the relevant changes
-  }), [transcriptStructureSig, renderScrollOffset, viewportHeight, transcriptRowIndex]);
+  }), [transcriptStructureSig, renderScrollOffset, transcriptContentHeight, transcriptRowIndex]);
   maxScrollRowsRef.current = transcriptWindow.maxScrollRows;
   // Publish this frame's geometry so a manual scroll can capture the reading
   // anchor synchronously (see captureTranscriptAnchorAt).
   transcriptGeomRef.current = {
     prefixRows: transcriptRowIndex?.prefixRows || null,
     totalRows: Math.max(0, Number(transcriptWindow.totalRows) || 0),
-    viewRows: Math.max(1, Number(viewportHeight) || 1),
+    viewRows: Math.max(1, Number(transcriptContentHeight) || 1),
     items: state.items || null,
+    // The offset THIS frame actually rendered with. The same-frame anchor
+    // CAPTURE for a missing/dirty anchor (above) reads this from the PREVIOUS
+    // frame to reconstruct the exact top-edge row that was on screen, so the
+    // capture matches what the user saw rather than the stale scrollOffset
+    // state. Bottom-relative, matching transcriptRenderWindow's window math.
+    renderOffset: Math.max(0, Number(renderScrollOffset) || 0),
   };
   // The window memo is keyed on a structure signature that intentionally
   // ignores per-character growth of the streaming assistant text, so its
@@ -7446,8 +8735,27 @@ export function App({ store, initialStatusLine = '' }) {
     transcriptWindow.startIndex,
     transcriptWindow.endIndex,
   );
-  // (attachInputHintToTurnDone / lastTranscriptItem computed earlier, before
-  // overlayHintVisible, so the overlay can exclude the same-row attach case.)
+  // The bottom meta band is spinner-only, so nothing is pulled out of the
+  // transcript for it. A finished turn's done row (turndone/statusdone) renders
+  // inline in scrollback like any other item — no filtering, no double-paint.
+  const renderedTranscriptItems = transcriptVisibleItems;
+  let overlayHintAttachItemIndex = -1;
+  for (let i = renderedTranscriptItems.length - 1; i >= 0; i--) {
+    const item = renderedTranscriptItems[i];
+    if (item?.kind === 'tool' && shouldSuppressFullyFailedToolItem(item)) continue;
+    overlayHintAttachItemIndex = i;
+    break;
+  }
+  const transcriptTailPinned = Math.max(0, Number(transcriptWindow.effectiveScrollOffset) || 0) <= transcriptBottomSlackRows;
+  const overlayHintOnLastItem = overlayHintRequested
+    && floatingPanelRows <= 0
+    && transcriptWindow.bottomSpacerRows === 0
+    && transcriptTailPinned
+    && overlayHintAttachItemIndex >= 0;
+  const overlayHintFallbackRow = overlayHintRequested
+    && floatingPanelRows <= 0
+    && transcriptGuardRows > 0
+    && !overlayHintOnLastItem;
   // ── App-level measured height harvest (ScrollBox/useVirtualScroll-inspired) ─
   // Runs after EVERY commit (no deps): Yoga has just laid out the mounted rows,
   // so each tracked item Box's getComputedHeight() is its REAL terminal height.
@@ -7537,8 +8845,18 @@ export function App({ store, initialStatusLine = '' }) {
     const currentPosition = Math.max(0, Number(scrollPositionRef.current) || 0);
     const currentOffset = Math.max(0, Number(scrollOffset) || 0);
     const maxRows = Math.max(0, Number(transcriptWindow.maxScrollRows) || 0);
-    const pinnedToBottom = currentTarget <= 0 && currentPosition <= 0 && currentOffset <= 0;
-    const followOnGrowth = followingRef.current && rowDelta > 0;
+    const nearBottom = followingRef.current || currentTarget <= transcriptBottomSlackRows;
+    const pinnedToBottom = nearBottom;
+    // A genuine reading anchor must win over ordinary stream growth, but an
+    // explicit follow arm (prompt submit / pinned bottom) must win over stale
+    // anchor state. Manual scroll cancels followingRef before anchor capture, so
+    // deliberate reading still stays anchored while automatic bottom-follow
+    // stays armed across spinner/tool/stream height corrections.
+    const activeReadingAnchor = !!transcriptAnchorRef.current
+      && !transcriptAnchorDirtyRef.current
+      && !followingRef.current
+      && !nearBottom;
+    const followOnGrowth = followingRef.current && rowDelta > 0 && !activeReadingAnchor;
     const shouldFollowBottom = rowDelta > 0 && (followOnGrowth || pinnedToBottom);
     if (shouldFollowBottom) {
       // Bottom follow: while pinned to the newest output,
@@ -7547,7 +8865,18 @@ export function App({ store, initialStatusLine = '' }) {
       // during streaming makes the transcript jump down/up and can clip the
       // currently generated assistant text. Keep all scroll refs at zero so
       // character generation stays visually stable.
-      followingRef.current = false;
+      stopSmoothScroll();
+      scrollTargetRef.current = 0;
+      scrollPositionRef.current = 0;
+      transcriptAnchorRef.current = null;
+      transcriptAnchorDirtyRef.current = false;
+      if (currentOffset !== 0) setScrollOffset(0);
+      return;
+    }
+
+    // Viewport-only changes, such as swapping TextEntryPanel for a picker, must
+    // not turn a bottom-pinned transcript into a reading-anchor lock.
+    if (rowDelta <= 0 && nearBottom) {
       stopSmoothScroll();
       scrollTargetRef.current = 0;
       scrollPositionRef.current = 0;
@@ -7569,12 +8898,12 @@ export function App({ store, initialStatusLine = '' }) {
     // only moves the bottom — the top is rock-stable. Changes ABOVE the anchor
     // move the item's prefix start and are absorbed the same way. No deltas, no
     // fallback, no drift.
-    const viewRows = Math.max(1, Number(viewportHeight) || 1);
+    const viewRows = Math.max(1, Number(transcriptContentHeight) || 1);
     const items = state.items || [];
     let anchor = transcriptAnchorRef.current;
     // (Re)capture the anchor from the current viewport-top edge when missing or
     // invalidated by a manual scroll. anchorRow = absolute row at the top edge.
-    if (!anchor || transcriptAnchorDirtyRef.current) {
+    if (!followingRef.current && (!anchor || transcriptAnchorDirtyRef.current)) {
       if (curPrefix && curPrefix.length > 1) {
         const anchorRow = Math.max(0, Math.min(totalRows, totalRows - currentTarget - viewRows));
         let idx = upperBound(curPrefix, anchorRow) - 1;
@@ -7614,12 +8943,25 @@ export function App({ store, initialStatusLine = '' }) {
     scrollPositionRef.current = Math.max(0, Math.min(maxRows, currentPosition + appliedDelta));
     preservedScrollDeltaRef.current += appliedDelta;
     setScrollOffset(Math.max(0, Math.round(desired)));
-  }, [transcriptWindow.totalRows, transcriptWindow.maxScrollRows, transcriptRowIndex, viewportHeight, scrollOffset, stopSmoothScroll]);
+  }, [transcriptWindow.totalRows, transcriptWindow.maxScrollRows, transcriptRowIndex, transcriptContentHeight, transcriptBottomSlackRows, scrollOffset, stopSmoothScroll]);
+  useLayoutEffect(() => {
+    if (transcriptBottomSlackRows <= 0) return;
+    if (transcriptAnchorRef.current || transcriptAnchorDirtyRef.current || followingRef.current) return;
+    const currentTarget = Math.max(0, Number(scrollTargetRef.current) || 0);
+    const currentPosition = Math.max(0, Number(scrollPositionRef.current) || 0);
+    const currentOffset = Math.max(0, Number(scrollOffset) || 0);
+    if (Math.max(currentTarget, currentPosition, currentOffset) === 0) return;
+    if (Math.max(currentTarget, currentPosition, currentOffset) > transcriptBottomSlackRows) return;
+    stopSmoothScroll();
+    scrollTargetRef.current = 0;
+    scrollPositionRef.current = 0;
+    setScrollOffset(0);
+  }, [transcriptBottomSlackRows, scrollOffset, stopSmoothScroll]);
   useLayoutEffect(() => {
     const top = Math.max(0, Number(transcriptViewportRef.current?.top) || 0);
     const next = {
       top,
-      height: Math.max(1, Number(viewportHeight) || 1),
+      height: Math.max(1, Number(transcriptContentHeight) || 1),
       totalRows: Math.max(0, Number(transcriptWindow.totalRows) || 0),
       scrollOffset: Math.max(0, Number(transcriptWindow.effectiveScrollOffset) || 0),
     };
@@ -7639,7 +8981,13 @@ export function App({ store, initialStatusLine = '' }) {
     const clippedRect = withSelectionClip(shiftSelectionRectY(dragRef.current.rect, deltaY));
     dragRef.current = { ...dragRef.current, rect: clippedRect };
     paintSelectionRect(clippedRect, { rememberText: true, immediate: true });
-  }, [viewportHeight, transcriptWindow.totalRows, transcriptWindow.effectiveScrollOffset, withSelectionClip, paintSelectionRect]);
+  }, [transcriptContentHeight, transcriptWindow.totalRows, transcriptWindow.effectiveScrollOffset, withSelectionClip, paintSelectionRect]);
+  useEffect(() => {
+    if (!dragRef.current.rect) return;
+    const clippedRect = withSelectionClip(dragRef.current.rect);
+    dragRef.current = { ...dragRef.current, rect: clippedRect };
+    paintSelectionRect(clippedRect, { rememberText: true, immediate: true });
+  }, [state.themeEpoch, withSelectionClip, paintSelectionRect]);
   useEffect(() => {
     const maxRows = Math.max(0, Number(transcriptWindow.maxScrollRows) || 0);
     if (scrollTargetRef.current <= maxRows && scrollPositionRef.current <= maxRows && scrollOffset <= maxRows) return;
@@ -7704,6 +9052,7 @@ export function App({ store, initialStatusLine = '' }) {
       onTab={cycleWorkflowFromPrompt}
       onPasteText={handlePromptPaste}
       onHistoryNavigate={handlePromptHistoryNavigate}
+      onVoiceToggle={handleVoiceToggle}
       commandPaletteActive={slashPaletteOpen}
       onCommandPaletteNavigate={(direction) => {
         setSlashIndex((index) => {
@@ -7734,16 +9083,16 @@ export function App({ store, initialStatusLine = '' }) {
     // stack up from just over the input. A top flexGrow spacer sinks the whole
     // stack to the bottom; the transcript itself is a fixed-height clipping
     // viewport (see viewportHeight above).
-    <Box flexDirection="column" width={frameColumns} height={resizeState.rows} backgroundColor={theme.background}>
+    <Box flexDirection="column" width={frameColumns} height={resizeState.rows} backgroundColor={surfaceBackground()}>
       {/* Empty-transcript header stays outside the bottom-anchored viewport and
           has its own reserved rows, so it cannot steal space from the input. */}
       {showWelcomeBanner ? (
-        <Box flexDirection="column" height={7} flexShrink={0} marginTop={3} marginBottom={1} backgroundColor={theme.background}>
+        <Box flexDirection="column" height={7} flexShrink={0} marginTop={3} marginBottom={1} backgroundColor={surfaceBackground()}>
           <Text color={theme.text} bold>{centerLine('███╗   ███╗██╗██╗  ██╗██████╗  ██████╗  ██████╗ ', frameColumns)}</Text>
           <Text color={theme.text} bold>{centerLine('████╗ ████║██║╚██╗██╔╝██╔══██╗██╔═══██╗██╔════╝ ', frameColumns)}</Text>
-          <Text color={theme.claude} bold>{centerLine('██╔████╔██║██║ ╚███╔╝ ██║  ██║██║   ██║██║  ███╗', frameColumns)}</Text>
-          <Text color={theme.claude} bold>{centerLine('██║╚██╔╝██║██║ ██╔██╗ ██║  ██║██║   ██║██║   ██║', frameColumns)}</Text>
-          <Text color={theme.claude} bold>{centerLine('██║ ╚═╝ ██║██║██╔╝ ██╗██████╔╝╚██████╔╝╚██████╔╝', frameColumns)}</Text>
+          <Text color={theme.logo ?? theme.claude} bold>{centerLine('██╔████╔██║██║ ╚███╔╝ ██║  ██║██║   ██║██║  ███╗', frameColumns)}</Text>
+          <Text color={theme.logo ?? theme.claude} bold>{centerLine('██║╚██╔╝██║██║ ██╔██╗ ██║  ██║██║   ██║██║   ██║', frameColumns)}</Text>
+          <Text color={theme.logo ?? theme.claude} bold>{centerLine('██║ ╚═╝ ██║██║██╔╝ ██╗██████╔╝╚██████╔╝╚██████╔╝', frameColumns)}</Text>
           <Box height={1} flexShrink={0} />
           <Text color={theme.inactive}>{centerLine(`mixdog coding agent · ${state.cwd}`, frameColumns, 4)}</Text>
         </Box>
@@ -7765,6 +9114,14 @@ export function App({ store, initialStatusLine = '' }) {
         overflow="hidden"
         justifyContent="flex-end"
       >
+        <Box
+          flexDirection="column"
+          width="100%"
+          height={transcriptContentHeight}
+          flexShrink={0}
+          overflow="hidden"
+          justifyContent="flex-end"
+        >
         {/* Wheel scroll: with the viewport bottom-anchored (flex-end), a NEGATIVE
             marginBottom pushes the transcript column DOWN past the bottom edge,
             bringing older content above the window into view (overflow hidden
@@ -7783,20 +9140,18 @@ export function App({ store, initialStatusLine = '' }) {
              * OVERSCAN: TRANSCRIPT_WINDOW_OVERSCAN_ROWS extra rows above the viewport so
              * fast wheel scrolls don't show a blank gap before re-render.
              */}
-           {transcriptVisibleItems.map((item, i, arr) => {
-             const showRightMessage = attachInputHintToTurnDone
-               && item.id === lastTranscriptItem?.id
-               && (item.kind === 'turndone' || item.kind === 'statusdone');
+           {renderedTranscriptItems.map((item, i, arr) => {
              const measureRef = transcriptMeasureRef(item);
+             const attachOverlayHint = overlayHintOnLastItem && i === overlayHintAttachItemIndex;
              const itemNode = (
                <Item
                  item={item}
                  prevKind={i > 0 ? arr[i - 1].kind : state.items[transcriptWindow.startIndex - 1]?.kind ?? null}
                  columns={frameColumns}
                  toolOutputExpanded={toolOutputExpanded}
-                 rightMessage={showRightMessage ? inputHint : ''}
-                 rightTone={inputHintTone}
-                 rightMessageWidth={transientStatusWidth || 24}
+                 rightMessage={attachOverlayHint ? inputHint : ''}
+                 rightTone={attachOverlayHint ? inputHintTone : 'info'}
+                 rightMessageWidth={attachOverlayHint ? (guardHintWidth || transientStatusWidth || 24) : 24}
                  themeEpoch={state.themeEpoch || 0}
                />
              );
@@ -7817,6 +9172,22 @@ export function App({ store, initialStatusLine = '' }) {
              <Box height={transcriptWindow.bottomSpacerRows} flexShrink={0} />
            ) : null}
         </Box>
+        {welcomePromptHintVisible ? (
+          <Box height={1} flexShrink={0} width="100%" overflow="hidden">
+            <Text color={theme.inactive} wrap="truncate">{centerLine(welcomePromptHintText, frameColumns, 2)}</Text>
+          </Box>
+        ) : null}
+        </Box>
+        {transcriptGuardRows > 0 ? (
+          <Box height={transcriptGuardRows} flexShrink={0} backgroundColor={surfaceBackground()} flexDirection="row" width="100%" overflow="hidden">
+            <Box flexGrow={1} flexShrink={1} overflow="hidden" />
+            {overlayHintFallbackRow ? (
+              <Box flexShrink={0} width={guardHintWidth || 1} marginLeft={1} marginRight={1} justifyContent="flex-end" overflow="hidden">
+                <Text color={promptStatusColor(inputHintTone)} wrap="truncate">{inputHint}</Text>
+              </Box>
+            ) : null}
+          </Box>
+        ) : null}
       </Box>
 
       {/* Live reasoning and transient status live just above the prompt: reasoning
@@ -7826,9 +9197,9 @@ export function App({ store, initialStatusLine = '' }) {
           panels use their actual rendered height and shrink before the prompt
           can move; overflow is clipped from the top while the panel remains
           bottom-aligned against the prompt. */}
-      <Box flexDirection="column" flexShrink={0} width="100%" backgroundColor={theme.background}>
+      <Box flexDirection="column" flexShrink={0} width="100%" backgroundColor={surfaceBackground()}>
         {floatingPanelRows > 0 ? (
-          <Box flexDirection="column" flexShrink={0} height={floatingPanelRows} overflow="hidden" justifyContent="flex-end" backgroundColor={theme.background}>
+          <Box flexDirection="column" flexShrink={0} height={floatingPanelRows} overflow="hidden" justifyContent="flex-end" backgroundColor={surfaceBackground()}>
             {toolApproval ? (
               <Picker
                 items={[
@@ -7906,6 +9277,7 @@ export function App({ store, initialStatusLine = '' }) {
                 visibleCount={pickerVisibleRows}
                 fillHeight={expandedOptionPanel}
                 themeEpoch={state.themeEpoch || 0}
+                confirmBar={picker.confirmBar}
               />
             ) : contextPanel ? (
               <ContextPanel
@@ -7973,7 +9345,7 @@ export function App({ store, initialStatusLine = '' }) {
               <TextEntryPanel
                 title={channelPrompt.label}
                 hint={channelPrompt.hint || 'Save channel setting.'}
-                mask={channelPrompt.kind === 'discord-token' || channelPrompt.kind === 'webhook-token'}
+                mask={channelPrompt.kind === 'discord-token' || channelPrompt.kind === 'telegram-token' || channelPrompt.kind === 'webhook-token'}
                 columns={frameColumns}
                 promptLabel="Value > "
                 onSubmit={onSubmit}
@@ -8021,56 +9393,47 @@ export function App({ store, initialStatusLine = '' }) {
         {!inputBoxHidden ? (
           <>
           {promptMetaVisible ? (
-            <Box
-              marginTop={floatingPanelRows > 0 ? 0 : 1}
-              height={1}
-              width="100%"
-              flexDirection="row"
-              backgroundColor={theme.background}
-            >
-              <Box flexGrow={1} flexShrink={1} overflow="hidden">
-                {liveSpinner ? (
-                  <Spinner
-                    verb={liveSpinner.verb}
-                    startedAt={liveSpinner.startedAt}
-                    outputTokens={liveSpinner?.outputTokens ?? liveSpinner?.tokens ?? 0}
-                    thinking={!!(state.thinking || liveSpinner?.thinking)}
-                    thinkingActiveSince={liveSpinner?.thinkingSegmentStartedAt ?? 0}
-                    mode={liveSpinner?.mode || 'responding'}
-                    columns={promptSpinnerColumns}
-                    marginTop={0}
-                  />
-                ) : null}
-              </Box>
-              {inputHint ? (
-                <Box flexShrink={0} width={transientStatusWidth || 1} marginLeft={1} marginRight={1} justifyContent="flex-end" overflow="hidden">
-                  <Text color={promptStatusColor(inputHintTone)} wrap="truncate">{inputHint}</Text>
+            <>
+              <Box
+                marginTop={0}
+                marginBottom={0}
+                height={1}
+                width="100%"
+                flexDirection="row"
+                backgroundColor={surfaceBackground()}
+              >
+                <Box flexGrow={1} flexShrink={1} overflow="hidden">
+                  {liveSpinner ? (
+                    <Spinner
+                      verb={liveSpinner.verb}
+                      startedAt={liveSpinner.startedAt}
+                      outputTokens={liveSpinner?.outputTokens ?? liveSpinner?.tokens ?? 0}
+                      thinking={!!(state.thinking || liveSpinner?.thinking)}
+                      thinkingActiveSince={liveSpinner?.thinkingSegmentStartedAt ?? 0}
+                      mode={liveSpinner?.mode || 'responding'}
+                      columns={promptSpinnerColumns}
+                      marginTop={0}
+                    />
+                  ) : null}
                 </Box>
-              ) : null}
-            </Box>
-          ) : null}
-          {overlayHintVisible ? (
-            <Box
-              height={1}
-              width="100%"
-              flexDirection="row"
-              backgroundColor={theme.background}
-            >
-              <Box flexGrow={1} flexShrink={1} overflow="hidden" />
-              <Box flexShrink={0} width={transientStatusWidth || 1} marginLeft={1} marginRight={1} justifyContent="flex-end" overflow="hidden">
-                <Text color={promptStatusColor(inputHintTone)} wrap="truncate">{inputHint}</Text>
+                {inputHint ? (
+                  <Box flexShrink={0} width={transientStatusWidth || 1} marginLeft={1} marginRight={1} justifyContent="flex-end" overflow="hidden">
+                    <Text color={promptStatusColor(inputHintTone)} wrap="truncate">{inputHint}</Text>
+                  </Box>
+                ) : null}
               </Box>
-            </Box>
+              <Box height={1} width="100%" backgroundColor={surfaceBackground()} />
+            </>
           ) : null}
           {queuedVisible ? (
             <QueuedCommands queued={state.queued} columns={frameColumns} />
           ) : null}
           <Box
-            marginTop={queuedVisible || overlayHintVisible ? 0 : (floatingPanelRows > 0 ? 0 : 1)}
+            marginTop={0}
             width="100%"
             borderStyle="round"
             borderColor={theme.promptBorder}
-            backgroundColor={theme.background}
+            backgroundColor={surfaceBackground()}
             paddingX={1}
           >
             {promptInputControl}
@@ -8098,6 +9461,7 @@ export function App({ store, initialStatusLine = '' }) {
           activeTools={activeTools}
           initialLine={initialStatusLine}
           workflow={state.workflow}
+          remoteEnabled={state.remoteEnabled === true}
           themeEpoch={state.themeEpoch || 0}
         />
       </Box>