@pellux/goodvibes-tui 0.19.28 → 0.19.30

package/src/main.ts

@@ -177,6 +177,7 @@ async function main() {
   };
 
   const getViewportHeight = (): number => {
+    if (input.onboardingWizard.active) return stdout.rows || 24;
     const promptLines: number = input.getVisiblePromptLineCount(getPromptContentWidth());
     const currentModel = providerRegistry.getCurrentModel();
     return (stdout.rows || 24) - 2 - estimateShellFooterHeight(promptLines, currentModel.contextWindow);
@@ -551,19 +552,23 @@ async function main() {
       composerPendingRisk: composerState.pendingRisk,
     }).lines;
 
+    const onboardingOwnsScreen = input.onboardingWizard.active;
+    const shellHeaderLines = onboardingOwnsScreen ? [] : headerLines;
+    const shellFooterLines = onboardingOwnsScreen ? [] : footerLines;
+    const panelWidth = !onboardingOwnsScreen && panelManager.isVisible() && panelManager.getAllOpen().length > 0
+      ? panelManager.getRightWidth(width)
+      : 0;
     const shellLayout = createShellLayout({
       width,
       height,
-      headerHeight: headerLines.length,
-      footerHeight: footerLines.length,
-      panelWidth: panelManager.isVisible() && panelManager.getAllOpen().length > 0
-        ? panelManager.getRightWidth(width)
-        : 0,
+      headerHeight: shellHeaderLines.length,
+      footerHeight: shellFooterLines.length,
+      panelWidth,
     });
     const vHeight = shellLayout.body.height;
     const conversationWidth = shellLayout.conversation.width;
     activeConversationWidth = conversationWidth;
-    const hasPanelWorkspace = panelManager.isVisible() && panelManager.getAllOpen().length > 0;
+    const hasPanelWorkspace = !onboardingOwnsScreen && panelManager.isVisible() && panelManager.getAllOpen().length > 0;
     conversation.setSplashSuppressed(hasPanelWorkspace);
 
     // Flush pending renders after updating the width provider and splash posture
@@ -627,27 +632,29 @@ async function main() {
     });
 
     // Panel composite data
-    const panelComposite = buildPanelCompositeData(
-      panelManager,
-      input,
-      shellLayout.panel?.width ?? 0,
-      shellLayout.panel?.height ?? vHeight,
-    );
+    const panelComposite = onboardingOwnsScreen
+      ? { panelData: undefined, panelWidth: 0 }
+      : buildPanelCompositeData(
+        panelManager,
+        input,
+        shellLayout.panel?.width ?? 0,
+        shellLayout.panel?.height ?? vHeight,
+      );
 
     compositor.composite({
       width, height,
-      header: headerLines,
+      header: shellHeaderLines,
       viewport,
-      footer: footerLines,
-      selection: {
+      footer: shellFooterLines,
+      selection: onboardingOwnsScreen ? undefined : {
         isCellSelected: (col, row) => selection.isCellSelected(col, row),
         scrollTop,
         lineCount: conversation.history.getLineCount(),
       },
-      search: input.searchManager.active ? {
+      search: !onboardingOwnsScreen && input.searchManager.active ? {
         manager: input.searchManager,
         scrollTop,
-        viewportStartY: 2,
+        viewportStartY: shellHeaderLines.length,
       } : undefined,
       panel: panelComposite.panelData,
       panelWidth: panelComposite.panelWidth,
@@ -675,15 +682,6 @@ async function main() {
     render,
   });
 
-  applyInitialTuiCliState({
-    cli,
-    input,
-    commandRegistry,
-    commandContext,
-    shellPaths: ctx.services.shellPaths,
-    render,
-  });
-
   // --- Streaming speed + tool preview wiring ---
   const refreshGit = () => gitStatusProvider.refresh().then((info) => { lastGitInfoRef.value = info; render(); }).catch(() => { /* non-fatal */ });
   // Refresh git status after each turn completes or after tool results arrive
@@ -729,6 +727,15 @@ async function main() {
   stdin.setEncoding('utf8');
   stdout.write((cli.flags.noAltScreen ? '' : ALT_SCREEN_ENTER) + CLEAR_SCREEN + CURSOR_HIDE + MOUSE_ENABLE + KEYBOARD_EXT_ENABLE + PASTE_ENABLE);
 
+  applyInitialTuiCliState({
+    cli,
+    input,
+    commandRegistry,
+    commandContext,
+    shellPaths: ctx.services.shellPaths,
+    render,
+  });
+
   stdin.on('data', (data: string) => {
     const blocking = handleBlockingShellInput({
       data,

package/src/renderer/compositor.ts

@@ -86,11 +86,11 @@ export class Compositor {
     const leftWidth = hasPanel ? Math.max(1, width - panelWidth - 1) : width;
     const sepX = hasPanel ? leftWidth : -1;
 
-    // 1. Draw Header (Rows 0-1) — always full width
+    // 1. Draw Header — always full width
     header.forEach((line, i) => newBuffer.blitLine(i, line));
 
-    // 2. Draw Viewport (Starting at Row 2)
-    const viewportStartY = 2;
+    // 2. Draw Viewport directly after the supplied header.
+    const viewportStartY = header.length;
     const vHeight = Math.max(0, height - header.length - footer.length);
 
     // Calculate the offset for bottom-anchored short history

package/src/renderer/onboarding/onboarding-wizard.ts

@@ -60,6 +60,12 @@ function modeLabel(mode: OnboardingWizardController['mode']): string {
   return 'New setup';
 }
 
+function changedScreensLabel(wizard: OnboardingWizardController): string {
+  if (wizard.dirtyStepCount === 0) return 'no changes';
+  if (wizard.dirtyStepCount === 1) return '1 changed screen';
+  return `${wizard.dirtyStepCount} changed screens`;
+}
+
 function stepGlyph(
   wizard: OnboardingWizardController,
   step: OnboardingWizardStepDefinition,
@@ -241,17 +247,17 @@ function renderFieldRow(
 
 function footerText(wizard: OnboardingWizardController): string {
   if (wizard.isEditingTextField()) {
-    return '[Enter] Save value  [Esc] Cancel edit  [Backspace] Delete  [Type] Edit value';
+    return '[Enter] Save value  [Esc] Cancel edit  [Backspace] Delete char  [Del/Ctrl+U] Clear value';
   }
 
-  return '[Enter] Toggle/open selected  [Tab] Next screen  [Shift+Tab] Previous  [↑↓] Move  [Esc] Close';
+  return '[Enter] Toggle/open  [Esc] Close  [Tab/Shift+Tab] Screen  [↑↓] Move  [Del/Ctrl+U] Clear input';
 }
 
 function controlsText(wizard: OnboardingWizardController): string {
   if (wizard.isEditingTextField()) {
-    return 'Controls: Enter saves this value, Esc cancels editing, Backspace deletes, typing edits the value.';
+    return 'Controls: Enter saves this value, Esc cancels editing, Backspace deletes one character, Delete or Ctrl+U clears the field.';
   }
-  return 'Controls: Enter or Space changes the selected row; Tab/Shift+Tab changes screens; arrows move; typing edits selected inputs.';
+  return 'Controls: Enter or Space changes the selected row; Delete or Ctrl+U clears selected text inputs; Tab/Shift+Tab changes screens; arrows move.';
 }
 
 function renderWideLayout(
@@ -271,18 +277,18 @@ function renderWideLayout(
   const summaryBg = UI_TONES.bg.summary;
   const innerLeft = layout.margin + 1;
   const availableInner = layout.innerWidth - 2;
-  const leftWidthBase = layout.innerWidth >= 108 ? 22 : 18;
-  const rightWidthBase = layout.innerWidth >= 108 ? 30 : 24;
-  const minCenterWidth = 34;
-  let leftWidth = Math.min(leftWidthBase, Math.max(16, availableInner - minCenterWidth - 12));
-  let rightWidth = Math.min(rightWidthBase, Math.max(20, availableInner - minCenterWidth - leftWidth));
+  const leftWidthBase = layout.innerWidth >= 150 ? 32 : layout.innerWidth >= 108 ? 28 : 24;
+  const rightWidthBase = layout.innerWidth >= 150 ? 34 : layout.innerWidth >= 108 ? 32 : 24;
+  const minCenterWidth = layout.innerWidth >= 120 ? 48 : 40;
+  let leftWidth = Math.min(leftWidthBase, Math.max(20, availableInner - minCenterWidth - 12));
+  let rightWidth = Math.min(rightWidthBase, Math.max(22, availableInner - minCenterWidth - leftWidth));
   let centerWidth = layout.innerWidth - leftWidth - rightWidth - 2;
 
   if (centerWidth < minCenterWidth) {
     const deficit = minCenterWidth - centerWidth;
-    const leftCut = Math.min(Math.max(0, leftWidth - 16), Math.ceil(deficit / 2));
+    const leftCut = Math.min(Math.max(0, leftWidth - 20), Math.ceil(deficit / 2));
     leftWidth -= leftCut;
-    rightWidth -= Math.min(Math.max(0, rightWidth - 20), deficit - leftCut);
+    rightWidth -= Math.min(Math.max(0, rightWidth - 22), deficit - leftCut);
     centerWidth = layout.innerWidth - leftWidth - rightWidth - 2;
   }
 
@@ -296,9 +302,9 @@ function renderWideLayout(
     currentStep.summaryTitle,
     ...currentStep.summaryLines.slice(0, 2),
     `Fields ${wizard.getCompletedFieldCount(wizard.stepIndex)}/${wizard.getStepFieldCount(wizard.stepIndex)} complete`,
-    `Dirty steps ${wizard.dirtyStepCount}`,
+    changedScreensLabel(wizard),
   ];
-  const fieldStartRow = 5;
+  const fieldStartRow = 6;
   const selectedText = selectedFieldText(wizard);
   const fieldRows = buildFieldRows(wizard, visibleFields, Math.max(0, bodyRows - fieldStartRow));
 
@@ -316,7 +322,7 @@ function renderWideLayout(
     bg: headerBg,
     bold: true,
   });
-  const meta = `${modeLabel(wizard.mode)}  ${wizard.stepIndex + 1}/${wizard.steps.length}  dirty ${wizard.dirtyStepCount}`;
+  const meta = `${modeLabel(wizard.mode)}  ${wizard.stepIndex + 1}/${wizard.steps.length}  ${changedScreensLabel(wizard)}`;
   putOverlayText(topLine, Math.max(layout.margin + 2, layout.margin + layout.width - getDisplayWidth(meta) - 3), layout.width - 4, meta, {
     fg: UI_TONES.fg.secondary,
     bg: headerBg,
@@ -376,19 +382,24 @@ function renderWideLayout(
         bg: bodyBg,
       });
     } else if (row === 2) {
+      putOverlayText(line, centerStart + 1, centerWidth - 2, descriptionLines[1] ?? '', {
+        fg: UI_TONES.fg.secondary,
+        bg: bodyBg,
+      });
+    } else if (row === 3) {
       fillRange(line, centerStart, centerWidth, railBg);
       putOverlayText(line, centerStart + 1, centerWidth - 2, truncateDisplay(controlsText(wizard), centerWidth - 2), {
         fg: UI_TONES.state.info,
         bg: railBg,
       });
-    } else if (row === 3) {
+    } else if (row === 4) {
       fillRange(line, centerStart, centerWidth, DEFAULT_OVERLAY_PALETTE.selectedBg);
       putOverlayText(line, centerStart + 1, centerWidth - 2, truncateDisplay(`Focus: ${selectedText.title.replace(/^Selected: /, '')}`, centerWidth - 2), {
         fg: UI_TONES.fg.primary,
         bg: DEFAULT_OVERLAY_PALETTE.selectedBg,
         bold: true,
       });
-    } else if (row === 4) {
+    } else if (row === 5) {
       fillRange(line, centerStart, centerWidth, DEFAULT_OVERLAY_PALETTE.selectedBg);
       putOverlayText(line, centerStart + 1, centerWidth - 2, truncateDisplay(selectedText.hint, centerWidth - 2), {
         fg: UI_TONES.fg.secondary,
@@ -473,7 +484,7 @@ function renderCollapsedLayout(
   const innerStart = layout.margin + 1;
   const innerWidth = layout.innerWidth;
   const descriptionLines = wrapText(currentStep.description, Math.max(14, innerWidth - 2)).slice(0, 2);
-  const fieldStartRow = 5;
+  const fieldStartRow = 6;
   const selectedText = selectedFieldText(wizard);
   const fieldRows = buildFieldRows(wizard, visibleFields, Math.max(0, bodyRows - fieldStartRow));
 
@@ -491,7 +502,7 @@ function renderCollapsedLayout(
     bg: headerBg,
     bold: true,
   });
-  const meta = `${wizard.stepIndex + 1}/${wizard.steps.length} • dirty ${wizard.dirtyStepCount}`;
+  const meta = `${wizard.stepIndex + 1}/${wizard.steps.length} • ${changedScreensLabel(wizard)}`;
   putOverlayText(topLine, Math.max(layout.margin + 2, layout.margin + layout.width - getDisplayWidth(meta) - 3), layout.width - 4, meta, {
     fg: UI_TONES.fg.secondary,
     bg: headerBg,
@@ -533,19 +544,24 @@ function renderCollapsedLayout(
         bg: bodyBg,
       });
     } else if (row === 2) {
+      putOverlayText(line, innerStart + 1, innerWidth - 2, descriptionLines[1] ?? '', {
+        fg: UI_TONES.fg.secondary,
+        bg: bodyBg,
+      });
+    } else if (row === 3) {
       fillRange(line, innerStart, innerWidth, UI_TONES.bg.section);
       putOverlayText(line, innerStart + 1, innerWidth - 2, truncateDisplay(controlsText(wizard), innerWidth - 2), {
         fg: UI_TONES.state.info,
         bg: UI_TONES.bg.section,
       });
-    } else if (row === 3) {
+    } else if (row === 4) {
       fillRange(line, innerStart, innerWidth, DEFAULT_OVERLAY_PALETTE.selectedBg);
       putOverlayText(line, innerStart + 1, innerWidth - 2, truncateDisplay(`Focus: ${selectedText.title.replace(/^Selected: /, '')}`, innerWidth - 2), {
         fg: UI_TONES.fg.primary,
         bg: DEFAULT_OVERLAY_PALETTE.selectedBg,
         bold: true,
       });
-    } else if (row === 4) {
+    } else if (row === 5) {
       fillRange(line, innerStart, innerWidth, DEFAULT_OVERLAY_PALETTE.selectedBg);
       putOverlayText(line, innerStart + 1, innerWidth - 2, truncateDisplay(selectedText.hint, innerWidth - 2), {
         fg: UI_TONES.fg.secondary,
@@ -592,7 +608,8 @@ export function renderOnboardingWizard(
   width: number,
   viewportHeight: number,
 ): Line[] {
-  const layout = createOverlayBoxLayout(width, 0, width);
+  const margin = width >= 64 ? 1 : 0;
+  const layout = createOverlayBoxLayout(width, margin, Math.max(20, width - margin * 2));
   const collapsed = layout.innerWidth < 86;
   return collapsed
     ? renderCollapsedLayout(wizard, width, viewportHeight, layout)

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

@@ -75,6 +75,7 @@ export const CATEGORY_LABELS: Record<(typeof SETTINGS_CATEGORIES)[number], strin
   permissions: 'Permissions',
   mcp: 'MCP',
   sandbox: 'Sandbox',
+  surfaces: 'Surfaces',
   danger: 'Danger',
   tools: 'Tools',
   flags: 'Flags',
@@ -129,6 +130,14 @@ export const SETTING_LABELS: Partial<Record<string, string>> = {
   'web.port': 'Web Port',
   'web.publicBaseUrl': 'Web Public Base URL',
   'web.staticAssetsDir': 'Web Static Assets Dir',
+  'surfaces.ntfy.enabled': 'ntfy Enabled',
+  'surfaces.ntfy.baseUrl': 'ntfy Base URL',
+  'surfaces.ntfy.topic': 'ntfy Default Delivery Topic',
+  'surfaces.ntfy.chatTopic': 'ntfy Chat Topic',
+  'surfaces.ntfy.agentTopic': 'ntfy Agent Topic',
+  'surfaces.ntfy.remoteTopic': 'ntfy Daemon-Only Remote Topic',
+  'surfaces.ntfy.token': 'ntfy Token',
+  'surfaces.ntfy.defaultPriority': 'ntfy Default Priority',
 };
 
 export function getSettingLabel(entry: SettingEntry): string {

package/src/renderer/settings-modal.ts

@@ -64,6 +64,7 @@ export function renderSettingsModal(
   const isUiTab = SETTINGS_CATEGORIES[modal.categoryIndex] === 'ui';
   const isToolsTab = SETTINGS_CATEGORIES[modal.categoryIndex] === 'tools';
   const isNetworkTab = SETTINGS_CATEGORIES[modal.categoryIndex] === 'network';
+  const isSurfacesTab = SETTINGS_CATEGORIES[modal.categoryIndex] === 'surfaces';
   let persistentHelpers: import('./modal-factory.ts').ModalHelperRow[] | undefined;
   sections.push({
     type: 'text',
@@ -79,6 +80,8 @@ export function renderSettingsModal(
             ? 'Feature flags control staged or experimental behavior. Some changes may require restart.'
             : isToolsTab
               ? 'Configure tool LLM routing and helper model. Provider and model fields are optional — empty means use the active provider.'
+              : isSurfacesTab
+                ? 'Configure external app surfaces. Toggle each Enabled setting to auto-start that surface when the service starts.'
               : isNetworkTab
                 ? 'Configure control-plane and HTTP-listener binding. hostMode local/network use preset hosts; custom enables the host field. Changes trigger auto-restart.'
                 : 'Browse and adjust operator-facing runtime settings by category.',

package/src/runtime/bootstrap-core.ts

@@ -11,6 +11,7 @@ import { Compositor } from '../renderer/compositor.ts';
 import type { PermissionRequestHandler } from '@pellux/goodvibes-sdk/platform/permissions/prompt';
 import type { SystemMessageRouter } from '../core/system-message-router.ts';
 import type { ConversationFollowUpItem } from '@pellux/goodvibes-sdk/platform/core/conversation-follow-ups';
+import type { OrchestratorUserInputOptions } from '../core/orchestrator.ts';
 import type { ControlPlaneRecentEvent } from '@pellux/goodvibes-sdk/platform/control-plane/gateway';
 import type { MutableRuntimeState } from '@pellux/goodvibes-sdk/platform/runtime/mutable-runtime-state';
 import type { BootstrapOptions } from './context.ts';
@@ -55,12 +56,32 @@ export interface BootstrapCoreState {
    * When non-null, COMPANION_MESSAGE_RECEIVED fires a real LLM turn via
    * orchestrator.handleUserInput() instead of only appending the user message.
    */
-  readonly orchestratorHandleUserInputRef: { value: ((text: string) => void) | null };
+  readonly orchestratorHandleUserInputRef: { value: ((text: string, options?: OrchestratorUserInputOptions) => void) | null };
   readonly requestRender: () => void;
   readonly setRenderRequest: (fn: () => void) => void;
   readonly runtimeSessionIdRef: { value: string };
 }
 
+export type CompanionMessagePayload = Extract<SessionEvent, { type: 'COMPANION_MESSAGE_RECEIVED' }>;
+
+export function companionMessageToOrchestratorInputOptions(
+  payload: CompanionMessagePayload,
+): OrchestratorUserInputOptions {
+  const metadata = payload.metadata;
+  const surface = typeof metadata?.surface === 'string' ? metadata.surface : undefined;
+  const topic = typeof metadata?.topic === 'string' ? metadata.topic : undefined;
+
+  return {
+    origin: {
+      source: payload.source,
+      messageId: payload.messageId,
+      ...(surface ? { surface } : {}),
+      ...(topic ? { topic } : {}),
+      ...(metadata ? { metadata } : {}),
+    },
+  };
+}
+
 export async function initializeBootstrapCore(
   stdout: NodeJS.WriteStream,
   options: BootstrapOptions,
@@ -362,13 +383,17 @@ export async function initializeBootstrapCore(
   // The fallback (ref not yet set) adds the message to the conversation view only —
   // this path is unreachable in practice because the event bus is not connected to
   // any live HTTP traffic until after the orchestrator is wired in bootstrap.ts.
-  const orchestratorHandleUserInputRef: { value: ((text: string) => void) | null } = { value: null };
+  const orchestratorHandleUserInputRef: {
+    value: ((text: string, options?: OrchestratorUserInputOptions) => void) | null;
+  } = { value: null };
   runtimeUnsubs.push(runtimeBus.on<Extract<SessionEvent, { type: 'COMPANION_MESSAGE_RECEIVED' }>>(
     'COMPANION_MESSAGE_RECEIVED',
     ({ payload }) => {
       if (orchestratorHandleUserInputRef.value) {
         // Delegate to the orchestrator: adds user message + fires a real LLM turn.
-        orchestratorHandleUserInputRef.value(payload.body);
+        // Preserve surface origin metadata so the SDK can correlate replies back
+        // to the originating external channel, including ntfy chat topics.
+        orchestratorHandleUserInputRef.value(payload.body, companionMessageToOrchestratorInputOptions(payload));
       } else {
         // Fallback: render the user message immediately (orchestrator not yet ready).
         conversation.addUserMessage(payload.body);

package/src/runtime/bootstrap.ts

@@ -11,7 +11,7 @@
  */
 import { join } from 'node:path';
 import net from 'node:net';
-import { Orchestrator } from '../core/orchestrator.ts';
+import { Orchestrator, type OrchestratorUserInputOptions } from '../core/orchestrator.ts';
 import { AcpManager } from '@pellux/goodvibes-sdk/platform/acp/manager';
 import { getTierPromptSupplement, getTierForContextWindow } from '@pellux/goodvibes-sdk/platform/providers/tier-prompts';
 import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
@@ -195,8 +195,10 @@ export async function bootstrapRuntime(
       return supplement ? runtime.systemPrompt + '\n\n' + supplement : runtime.systemPrompt;
     },
     hookDispatcher,
+    flagManager: services.featureFlags,
     requestRender: () => orchestratorRefs.requestRender(),
     runtimeBus,
+    sessionId: runtime.sessionId,
     services: {
       agentManager: services.agentManager,
       wrfcController: services.wrfcController,
@@ -204,8 +206,8 @@ export async function bootstrapRuntime(
   });
   conversationFollowUpRef.value = (item) => orchestrator.enqueueConversationFollowUp(item);
   // Wire orchestratorHandleUserInputRef so COMPANION_MESSAGE_RECEIVED fires a real LLM turn.
-  orchestratorHandleUserInputRef.value = (text: string) => {
-    orchestrator.handleUserInput(text).catch((err: unknown) => {
+  orchestratorHandleUserInputRef.value = (text: string, options?: OrchestratorUserInputOptions) => {
+    orchestrator.handleUserInput(text, undefined, options).catch((err: unknown) => {
       logger.debug('companion handleUserInput safety catch', { error: String(err) });
     });
   };
@@ -370,6 +372,20 @@ export async function bootstrapRuntime(
     };
   };
 
+  const waitForConfigDrivenRestarts = async (handle: ExternalServicesHandle): Promise<void> => {
+    const waitForRestart = async (service: unknown): Promise<void> => {
+      const maybeRestarting = service as { waitForRestart?: unknown } | null;
+      if (typeof maybeRestarting?.waitForRestart === 'function') {
+        await maybeRestarting.waitForRestart();
+      }
+    };
+
+    await Promise.all([
+      waitForRestart(handle.daemonServer),
+      waitForRestart(handle.httpListener),
+    ]);
+  };
+
   let externalServices: ExternalServicesHandle = {
     daemonServer: null,
     httpListener: null,
@@ -401,6 +417,7 @@ export async function bootstrapRuntime(
           // A failed previous startup should not prevent a restart attempt.
         }
       }
+      await waitForConfigDrivenRestarts(externalServices);
       await externalServices.stop();
       const previousBindings = externalServiceBindings;
       externalServiceBindings = readExternalServiceBindings();

package/src/runtime/onboarding/apply.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from '
 import { dirname } from 'node:path';
 import { isSecretRefInput } from '@pellux/goodvibes-sdk/platform/config/secret-refs';
 import { CONFIG_SCHEMA, DEFAULT_CONFIG } from '../../config/index.ts';
+import type { FeatureFlagConfigKey } from '../surface-feature-flags.ts';
 import {
   getOnboardingRuntimeStatePath,
   readOnboardingRuntimeState,
@@ -133,11 +134,39 @@ function isMalformedGoodVibesSecretReferenceValue(value: string): boolean {
   return normalized.startsWith('goodvibes://') && !isGoodVibesSecretReferenceValue(normalized);
 }
 
+function isFeatureFlagConfigKey(key: string): key is FeatureFlagConfigKey {
+  return key === 'featureFlags' || key.startsWith('featureFlags.');
+}
+
+function validateFeatureFlagConfigValue(operation: Extract<OnboardingApplyOperation, { kind: 'set-config' }>): boolean {
+  if (!isFeatureFlagConfigKey(operation.key)) return false;
+
+  if (operation.key === 'featureFlags') {
+    if (!isPlainObject(operation.value)) throw new Error('featureFlags expects an object value.');
+    for (const [flagId, state] of Object.entries(operation.value)) {
+      if (flagId.trim().length === 0) throw new Error('featureFlags cannot contain an empty feature id.');
+      if (state !== 'enabled' && state !== 'disabled') {
+        throw new Error(`featureFlags.${flagId} expects enabled or disabled.`);
+      }
+    }
+    return true;
+  }
+
+  const flagId = operation.key.slice('featureFlags.'.length);
+  if (flagId.trim().length === 0) throw new Error('featureFlags requires a feature id.');
+  if (operation.value !== 'enabled' && operation.value !== 'disabled') {
+    throw new Error(`Config key ${operation.key} expects enabled or disabled.`);
+  }
+  return true;
+}
+
 function validateConfigValue(operation: Extract<OnboardingApplyOperation, { kind: 'set-config' }>): void {
   if (typeof operation.value === 'string' && isMalformedGoodVibesSecretReferenceValue(operation.value)) {
     throw new Error(`Config key ${operation.key} only accepts goodvibes://secrets/... secret references.`);
   }
 
+  if (validateFeatureFlagConfigValue(operation)) return;
+
   const schema = CONFIG_SCHEMA.find((entry) => entry.key === operation.key);
   if (!schema) {
     const defaultValue = operation.key.split('.').reduce<unknown>((cursor, part) => (
@@ -204,9 +233,6 @@ function validateAuthOperation(
   if (existing && !requiredRoles.every((role) => existing.roles.includes(role))) {
     throw new Error(`Existing local auth user ${username} is missing required role(s): ${requiredRoles.join(', ')}.`);
   }
-  if (existing && operation.retireBootstrapCredential) {
-    throw new Error('Replacing a bootstrap credential requires a new local admin username.');
-  }
 }
 
 function validateAcknowledgementOperation(
@@ -242,7 +268,7 @@ function applyConfigOperation(
     };
   }
 
-  deps.config.setDynamic(operation.key, operation.value);
+  deps.config.setDynamic(operation.key as never, operation.value);
   return {
     kind: operation.kind,
     summary: `Updated ${operation.key} in global onboarding settings.`,
@@ -278,7 +304,9 @@ function applyAuthOperation(
     ? parseBootstrapCredential(readFileSync(before.bootstrapCredentialPath, 'utf-8'))
     : null;
 
-  if (!existing) {
+  if (existing) {
+    auth.rotatePassword(username, operation.password);
+  } else {
     auth.addUser(username, operation.password, operation.roles ?? ['admin']);
   }
 
@@ -296,7 +324,7 @@ function applyAuthOperation(
   return {
     kind: operation.kind,
     summary: existing
-      ? `Verified local auth user ${username}.`
+      ? `Updated local auth user ${username}.`
       : `Created local auth user ${username}.`,
   };
 }
@@ -391,9 +419,9 @@ async function buildRollbackAction(
       );
     }
 
-    const previous = deps.config.get(operation.key);
+    const previous = deps.config.get(operation.key as never);
     return () => {
-      deps.config.setDynamic(operation.key, previous);
+      deps.config.setDynamic(operation.key as never, previous);
     };
   }
 

package/src/runtime/onboarding/derivation.ts

@@ -240,22 +240,22 @@ function hasExternalIntegrations(snapshot: OnboardingSnapshotState): boolean {
 
 function describeLocalTuiOnly(snapshot: OnboardingSnapshotState): string {
   if (!hasAnyServerEnabled(snapshot)) {
-    return 'Keep GoodVibes in this terminal and disable browser access, background services, network listeners, and external surfaces.';
+    return 'Use GoodVibes only in this terminal. No browser access, background service, HTTP listener, external app surface, or network setup.';
   }
 
-  return 'Switching to this disables browser access, background services, network listeners, and external surfaces.';
+  return 'Turn off browser access, background services, HTTP listeners, external app surfaces, and network setup.';
 }
 
 function describeBrowserAccess(snapshot: OnboardingSnapshotState): string {
   return snapshot.bindSettings.web.enabled
-    ? 'Keep the background service and web UI enabled, reachable according to the network step.'
-    : 'Enable the background service and web UI, reachable on the local network by default unless customized.';
+    ? 'Keep the background service and web UI enabled. Network reachability is controlled on the next screen.'
+    : 'Run the background service and web UI. GoodVibes will use the local network by default; you can restrict or customize it next.';
 }
 
 function describeRemoteDeviceAccess(snapshot: OnboardingSnapshotState): string {
   return hasRemoteDeviceAccess(snapshot)
-    ? 'Keep enabled GoodVibes services reachable from other devices on your LAN. Local auth is required.'
-    : 'Expose enabled GoodVibes services on your LAN so other devices can reach them. Local auth is required.';
+    ? 'Keep enabled GoodVibes services reachable from other devices on your LAN. Local authentication is required.'
+    : 'Make enabled GoodVibes services reachable from other devices on your LAN. Local authentication is required.';
 }
 
 function describeWebhookIngress(snapshot: OnboardingSnapshotState): string {
@@ -272,7 +272,7 @@ function describeExternalIntegrations(snapshot: OnboardingSnapshotState): string
   ]).size;
 
   if (integrationCount === 0) {
-    return 'Show Slack, Discord, Telegram, Teams, Matrix, and other app surfaces so they can be enabled and configured here.';
+    return 'Enable setup screens for Slack, Discord, Telegram, Teams, Matrix, and other app surfaces you choose.';
   }
 
   return `Review and configure ${integrationCount} detected external app, service, or surface integration signal(s).`;

package/src/runtime/onboarding/snapshot.ts

@@ -40,6 +40,7 @@ function buildConfigSnapshot(
     network: config.getCategory('network'),
     surfaces: config.getCategory('surfaces'),
     service: config.getCategory('service'),
+    featureFlags: config.getCategory('featureFlags'),
   };
 }
 

package/src/runtime/onboarding/types.ts

@@ -1,5 +1,6 @@
 import type { ConfigManager, ConfigKey, GoodVibesConfig } from '../../config/index.ts';
 import type { SecretsManager, SecretRecord, SecretStorageReview } from '../../config/secrets.ts';
+import type { FeatureFlagConfigKey } from '../surface-feature-flags.ts';
 import type { LocalAuthSnapshot, UserAuthManager } from '@pellux/goodvibes-sdk/platform/security/user-auth';
 import type { ShellPathService } from '@pellux/goodvibes-sdk/platform/runtime/shell-paths';
 import type {
@@ -45,6 +46,7 @@ export interface OnboardingConfigSnapshot {
   readonly network: GoodVibesConfig['network'];
   readonly surfaces: GoodVibesConfig['surfaces'];
   readonly service: GoodVibesConfig['service'];
+  readonly featureFlags: GoodVibesConfig['featureFlags'];
 }
 
 export interface OnboardingProviderRoutingSnapshot {
@@ -235,7 +237,7 @@ export interface OnboardingStepDerivationState {
 export type OnboardingApplyOperation =
   | {
       readonly kind: 'set-config';
-      readonly key: ConfigKey;
+      readonly key: ConfigKey | FeatureFlagConfigKey;
       readonly value: unknown;
       readonly scope?: 'global' | 'project';
     }
@@ -381,6 +383,7 @@ export interface OnboardingApplyDependencies {
     | 'getUser'
     | 'inspect'
     | 'revokeSession'
+    | 'rotatePassword'
   >;
   readonly shellPaths: OnboardingShellPaths;
   readonly acknowledgementScope?: OnboardingStateScope;

package/src/runtime/onboarding/verify.ts

@@ -43,7 +43,7 @@ function verifyConfigOperation(
   deps: OnboardingVerificationDependencies,
   operation: Extract<OnboardingApplyOperation, { kind: 'set-config' }>,
 ): OnboardingVerificationItem {
-  const actual = deps.config.get(operation.key);
+  const actual = deps.config.get(operation.key as never);
   const ok = isDeepEqual(actual, operation.value);
 
   return {