@pellux/goodvibes-tui 0.19.24 → 0.19.26

package/src/cli/types.ts

@@ -0,0 +1,69 @@
+export type GoodVibesCliCommand =
+  | 'tui'
+  | 'run'
+  | 'serve'
+  | 'web'
+  | 'service'
+  | 'status'
+  | 'doctor'
+  | 'onboarding'
+  | 'models'
+  | 'providers'
+  | 'auth'
+  | 'subscription'
+  | 'secrets'
+  | 'sessions'
+  | 'tasks'
+  | 'pair'
+  | 'surfaces'
+  | 'listener'
+  | 'control-plane'
+  | 'bundle'
+  | 'remote'
+  | 'bridge'
+  | 'completion'
+  | 'help'
+  | 'version'
+  | 'unknown';
+
+export type GoodVibesCliOutputFormat = 'text' | 'json' | 'stream-json';
+
+export interface CliCommandOutput {
+  readonly output: string;
+  readonly exitCode: number;
+}
+
+export interface GoodVibesCliFlags {
+  readonly provider: string | undefined;
+  readonly model: string | undefined;
+  readonly daemonHome: string | undefined;
+  readonly workingDir: string | undefined;
+  readonly help: boolean;
+  readonly version: boolean;
+  readonly prompt: string | undefined;
+  readonly print: boolean;
+  readonly outputFormat: GoodVibesCliOutputFormat;
+  readonly configOverrides: readonly string[];
+  readonly enableFeatures: readonly string[];
+  readonly disableFeatures: readonly string[];
+  readonly noAltScreen: boolean;
+  readonly port: number | undefined;
+  readonly hostname: string | undefined;
+  readonly open: boolean;
+  readonly continueLast: boolean;
+  readonly resume: string | undefined;
+  readonly session: string | undefined;
+  readonly fork: boolean;
+  readonly rawOutput: boolean;
+  readonly acceptRawOutputRisk: boolean;
+}
+
+export interface GoodVibesCliParseResult {
+  readonly binary: string;
+  readonly command: GoodVibesCliCommand;
+  readonly rawCommand: string | undefined;
+  readonly commandArgs: readonly string[];
+  readonly positionals: readonly string[];
+  readonly flags: GoodVibesCliFlags;
+  readonly errors: readonly string[];
+}

package/src/cli-flags.ts

@@ -1,58 +1,21 @@
-// ---------------------------------------------------------------------------
-// Shared CLI flag parsing for TUI shell and daemon entrypoints.
-// ---------------------------------------------------------------------------
+// Compatibility wrapper for older imports. New CLI code lives in src/cli.
+export type { GoodVibesCliFlags as CliFlags } from './cli/types.ts';
+export {
+  applyRuntimeConfigOverrides,
+  applyRuntimeConfigValue,
+  applyRuntimeCommandEndpointFlagOverrides,
+  applyRuntimeEndpointFlagOverrides,
+  applyRuntimeFeatureFlagOverrides,
+  handleGoodVibesCliCommand,
+  parseGoodVibesCli,
+  renderGoodVibesCommandHelp,
+  renderGoodVibesHelp,
+  renderGoodVibesVersion,
+} from './cli/index.ts';
 
-export type CliFlags = {
-  readonly provider: string | undefined;
-  readonly model: string | undefined;
-  readonly daemonHome: string | undefined;
-  readonly workingDir: string | undefined;
-};
+import { parseGoodVibesCli } from './cli/parser.ts';
+import type { GoodVibesCliFlags } from './cli/types.ts';
 
-/**
- * Parse `--provider` / `--model` / `--daemon-home` / `--working-dir` / `--help` flags from an argv slice.
- *
- * @param argv   - argv array (pass `process.argv.slice(2)`)
- * @param binary - binary name shown in the --help usage line (e.g. "goodvibes" or "goodvibes-daemon")
- */
-export function parseCliFlags(argv: readonly string[], binary = 'goodvibes'): CliFlags {
-  let provider: string | undefined;
-  let model: string | undefined;
-  let daemonHome: string | undefined;
-  let workingDir: string | undefined;
-
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === '--help' || arg === '-h') {
-      // eslint-disable-next-line no-console
-      console.log([
-        `Usage: ${binary} [options]`,
-        '',
-        'Options:',
-        '  --provider <id>          Override the provider from settings.json at startup',
-        '  --model <registryKey>    Override the model from settings.json at startup',
-        '                           Format: provider:modelId (e.g. inception:mercury-2)',
-        '                           If provider:modelId format is used, --provider is inferred',
-        '  --daemon-home=<path>     Override daemon home (precedence: flag > GOODVIBES_DAEMON_HOME env > ~/.goodvibes/daemon)',
-        '  --working-dir=<path>     Override working directory (precedence: flag > GOODVIBES_WORKING_DIR env > <cwd>)',
-        '  --help, -h               Show this help message',
-      ].join('\n'));
-      process.exit(0);
-    }
-    if (arg === '--provider' && argv[i + 1] !== undefined) {
-      provider = argv[++i];
-    } else if (arg === '--model' && argv[i + 1] !== undefined) {
-      model = argv[++i];
-      // Infer provider from registryKey format (provider:modelId) if --provider not given
-      if (typeof model === 'string' && model.includes(':') && provider === undefined) {
-        provider = model.split(':')[0];
-      }
-    } else if (arg.startsWith('--daemon-home=')) {
-      daemonHome = arg.slice('--daemon-home='.length);
-    } else if (arg.startsWith('--working-dir=')) {
-      workingDir = arg.slice('--working-dir='.length);
-    }
-  }
-
-  return { provider, model, daemonHome, workingDir };
+export function parseCliFlags(argv: readonly string[], binary = 'goodvibes'): GoodVibesCliFlags {
+  return parseGoodVibesCli(argv, binary).flags;
 }

package/src/config/index.ts

@@ -8,7 +8,7 @@
 
 export { ConfigManager } from '@pellux/goodvibes-sdk/platform/config/manager';
 export type { DeepReadonly } from '@pellux/goodvibes-sdk/platform/config/manager';
-export type { GoodVibesConfig, ConfigKey, ConfigValue, ConfigSetting, PermissionMode, PermissionAction, PermissionsToolConfig, NotificationsConfig } from '@pellux/goodvibes-sdk/platform/config/schema';
+export type { GoodVibesConfig, ConfigKey, ConfigValue, ConfigSetting, PermissionMode, PermissionAction, PermissionsToolConfig, NotificationsConfig, PersistedFlagState } from '@pellux/goodvibes-sdk/platform/config/schema';
 export { DEFAULT_CONFIG, CONFIG_SCHEMA } from '@pellux/goodvibes-sdk/platform/config/schema';
 export { ConfigError } from '@pellux/goodvibes-sdk/platform/types/errors';
 

package/src/config/secrets.ts

@@ -13,9 +13,38 @@ import {
   SecretsManager as SdkSecretsManager,
   type SecretsManagerOptions as SdkSecretsManagerOptions,
 } from '@pellux/goodvibes-sdk/platform/config/secrets';
+import { isSecretRefInput } from '@pellux/goodvibes-sdk/platform/config/secret-refs';
 
 export type SecretsManagerOptions = Omit<SdkSecretsManagerOptions, 'surfaceRoot'>;
 
+const RAW_SECRET_LITERAL_PREFIX = '__GOODVIBES_LITERAL_V1__';
+
+function isGoodVibesSecretRefInput(value: string): boolean {
+  const normalized = value.trim();
+  return normalized.startsWith('goodvibes://secrets/') && isSecretRefInput(normalized);
+}
+
+function shouldStoreAsLiteral(value: string): boolean {
+  return value.startsWith(RAW_SECRET_LITERAL_PREFIX)
+    || (isSecretRefInput(value) && !isGoodVibesSecretRefInput(value));
+}
+
+function encodeLiteralSecret(value: string): string {
+  return `${RAW_SECRET_LITERAL_PREFIX}${Buffer.from(JSON.stringify({ value }), 'utf-8').toString('base64url')}`;
+}
+
+function decodeLiteralSecret(value: string): string | null {
+  if (!value.startsWith(RAW_SECRET_LITERAL_PREFIX)) return null;
+  try {
+    const decoded = Buffer.from(value.slice(RAW_SECRET_LITERAL_PREFIX.length), 'base64url').toString('utf-8');
+    const parsed = JSON.parse(decoded) as unknown;
+    if (!parsed || typeof parsed !== 'object' || typeof (parsed as { value?: unknown }).value !== 'string') return null;
+    return (parsed as { value: string }).value;
+  } catch {
+    return null;
+  }
+}
+
 export class SecretsManager extends SdkSecretsManager {
   constructor(options: SecretsManagerOptions) {
     super({
@@ -23,4 +52,19 @@ export class SecretsManager extends SdkSecretsManager {
       surfaceRoot: 'tui',
     });
   }
+
+  override async get(key: string): Promise<string | null> {
+    const envValue = process.env[key];
+    if (envValue !== undefined && shouldStoreAsLiteral(envValue)) {
+      return decodeLiteralSecret(envValue) ?? envValue;
+    }
+
+    const value = await super.get(key);
+    if (value === null) return null;
+    return decodeLiteralSecret(value) ?? value;
+  }
+
+  override async set(key: string, value: string, options?: Parameters<SdkSecretsManager['set']>[2]): Promise<void> {
+    await super.set(key, shouldStoreAsLiteral(value) ? encodeLiteralSecret(value) : value, options);
+  }
 }

package/src/daemon/cli.ts

@@ -25,7 +25,15 @@ import {
   persistProviders,
 } from '@pellux/goodvibes-sdk/platform/discovery/index';
 
-import { parseCliFlags } from '../cli-flags.ts';
+import {
+  parseGoodVibesCli,
+  renderGoodVibesDaemonHelp,
+  renderGoodVibesVersion,
+  applyRuntimeConfigOverrides,
+  applyRuntimeConfigValue,
+  applyRuntimeFeatureFlagOverrides,
+  applyRuntimeEndpointFlagOverrides,
+} from '../cli/index.ts';
 type DaemonCliOwnership = {
   readonly workingDirectory: string;
   readonly homeDirectory: string;
@@ -39,13 +47,17 @@ type DaemonCliTokens = {
 };
 
 function getLocalNetworkIp(): string {
-  const nets = networkInterfaces();
-  for (const name of Object.keys(nets)) {
-    for (const net of nets[name] ?? []) {
-      if (net.family === 'IPv4' && !net.internal) {
-        return net.address;
+  try {
+    const nets = networkInterfaces();
+    for (const name of Object.keys(nets)) {
+      for (const net of nets[name] ?? []) {
+        if (net.family === 'IPv4' && !net.internal) {
+          return net.address;
+        }
       }
     }
+  } catch {
+    return 'localhost';
   }
   return 'localhost';
 }
@@ -82,7 +94,22 @@ function readDaemonCliTokens(env: NodeJS.ProcessEnv): DaemonCliTokens {
 async function main(): Promise<void> {
   // Parse CLI flags first so --daemon-home and --working-dir env vars are set
   // before resolveDaemonCliOwnership() reads them.
-  const cliFlags = parseCliFlags(process.argv.slice(2), 'goodvibes-daemon');
+  const cli = parseGoodVibesCli(process.argv.slice(2), 'goodvibes-daemon');
+  if (cli.errors.length > 0) {
+    console.error(cli.errors.join('\n'));
+    console.error('');
+    console.error(renderGoodVibesDaemonHelp('goodvibes-daemon'));
+    process.exit(2);
+  }
+  if (cli.flags.help || cli.command === 'help') {
+    console.log(renderGoodVibesDaemonHelp('goodvibes-daemon'));
+    process.exit(0);
+  }
+  if (cli.flags.version || cli.command === 'version') {
+    console.log(renderGoodVibesVersion('goodvibes-daemon'));
+    process.exit(0);
+  }
+  const cliFlags = cli.flags;
   if (cliFlags.daemonHome !== undefined) {
     process.env['GOODVIBES_DAEMON_HOME'] = cliFlags.daemonHome;
     logger.info('daemon: --daemon-home flag applied', { daemonHome: cliFlags.daemonHome });
@@ -96,15 +123,36 @@ async function main(): Promise<void> {
   const config = new ConfigManager({ workingDir, homeDir: homeDirectory, surfaceRoot: 'tui' });
   new GlobalNetworkTransportInstaller().install(config);
 
-  // Apply remaining CLI flags — override settings.json before the provider registry is constructed
+  const overrideErrors = applyRuntimeConfigOverrides(config, cliFlags.configOverrides);
+  if (overrideErrors.length > 0) {
+    console.error(overrideErrors.join('\n'));
+    process.exit(2);
+  }
+  applyRuntimeFeatureFlagOverrides(config, {
+    enableFeatures: cliFlags.enableFeatures,
+    disableFeatures: cliFlags.disableFeatures,
+  });
+
+  // Apply remaining CLI flags before the provider registry is constructed.
+  // These are runtime-only overrides; they must not rewrite settings.json.
   if (cliFlags.provider !== undefined) {
-    config.set('provider.provider', cliFlags.provider);
+    applyRuntimeConfigValue(config, 'provider.provider', cliFlags.provider);
     logger.info('daemon: --provider flag applied', { provider: cliFlags.provider });
   }
   if (cliFlags.model !== undefined) {
-    config.set('provider.model', cliFlags.model);
+    applyRuntimeConfigValue(config, 'provider.model', cliFlags.model);
     logger.info('daemon: --model flag applied', { model: cliFlags.model });
   }
+  const endpointOverrideErrors = applyRuntimeEndpointFlagOverrides(config, 'controlPlane', cliFlags);
+  if (endpointOverrideErrors.length > 0) {
+    console.error(endpointOverrideErrors.join('\n'));
+    process.exit(2);
+  }
+  if (cliFlags.port !== undefined) logger.info('daemon: --port flag applied', { port: cliFlags.port });
+  if (cliFlags.hostname !== undefined) {
+    process.env['GOODVIBES_DAEMON_HOST'] = cliFlags.hostname;
+    logger.info('daemon: --hostname flag applied', { hostname: cliFlags.hostname });
+  }
   const runtimeBus = new RuntimeEventBus();
   const runtimeStore = createRuntimeStore();
   const runtimeServices = createRuntimeServices({
@@ -209,7 +257,10 @@ async function main(): Promise<void> {
   // Print companion connection info + QR code to stdout.
   // Use the config-driven control plane port, not a hardcoded default.
   const daemonPort = config.get('controlPlane.port');
-  const daemonHost = String(process.env.GOODVIBES_DAEMON_HOST ?? getLocalNetworkIp());
+  const configuredDaemonHost = String(process.env.GOODVIBES_DAEMON_HOST ?? getLocalNetworkIp());
+  const daemonHost = configuredDaemonHost === '0.0.0.0' || configuredDaemonHost === '::'
+    ? getLocalNetworkIp()
+    : configuredDaemonHost;
   const daemonUrl = `http://${daemonHost}:${daemonPort}`;
   const bootstrapPassword = readBootstrapPassword(userAuth.getBootstrapCredentialPath());
   const connectionInfo = buildCompanionConnectionInfo({

package/src/input/command-registry.ts

@@ -9,6 +9,8 @@ import type { SelectionItem, SelectionResult, SelectionAction } from './selectio
 import type { FileUndoManager } from '@pellux/goodvibes-sdk/platform/state/file-undo';
 import type { PanelManager } from '../panels/panel-manager.ts';
 import type { KeybindingsManager } from './keybindings.ts';
+import type { OnboardingWizardMode } from './onboarding/onboarding-wizard.ts';
+import type { OpenOnboardingWizardOptions } from './handler-ui-state.ts';
 import type { KnowledgeApi } from '@pellux/goodvibes-sdk/platform/knowledge/knowledge-api';
 import type { HookApi } from '@pellux/goodvibes-sdk/platform/hooks/hook-api';
 import type { McpApi } from '@pellux/goodvibes-sdk/platform/mcp/mcp-api';
@@ -72,6 +74,7 @@ export interface CommandUiActions {
 
 export interface CommandShellUiOpeners {
   reloadSystemPrompt?: () => string;
+  openOnboardingWizard?: (modeOrOptions?: OnboardingWizardMode | OpenOnboardingWizardOptions) => void;
   openModelPicker?: () => void;
   openProviderPicker?: () => void;
   openContextInspector?: () => void;

package/src/input/commands/guidance-runtime.ts

@@ -2,24 +2,29 @@ import { estimateConversationTokens } from '@pellux/goodvibes-sdk/platform/core/
 import { evaluateSessionMaintenance, formatSessionMaintenanceLines, getGuidanceMode } from '@pellux/goodvibes-sdk/platform/runtime/session-maintenance';
 import { dismissGuidance, evaluateContextualGuidance, formatGuidanceItems, resetGuidance } from '@pellux/goodvibes-sdk/platform/runtime/guidance';
 import type { CommandRegistry } from '../command-registry.ts';
-import { openCommandPanel, requireProviderApi, requireReadModels, requireSessionMemoryStore, requireShellPaths } from './runtime-services.ts';
+import { requireProviderApi, requireReadModels, requireSessionMemoryStore, requireShellPaths } from './runtime-services.ts';
 
 export function registerGuidanceRuntimeCommands(registry: CommandRegistry): void {
   registry.register({
     name: 'welcome',
     aliases: ['guide'],
-    description: 'Open the guided start surface for setup, security, marketplace, remote, and operator workflows',
+    description: 'Open the product entry surface for the onboarding wizard, security, marketplace, remote, and operator workflows',
     usage: '[open|print]',
     handler(args, ctx) {
       const sub = args[0] ?? 'open';
       if (sub === 'open' || sub === 'panel') {
-        openCommandPanel(ctx, 'welcome');
+        if (ctx.openOnboardingWizard) {
+          ctx.openOnboardingWizard({ mode: 'edit' });
+          return;
+        }
+        ctx.print('Use /onboarding to open the setup wizard.');
         return;
       }
       if (sub === 'print') {
         ctx.print([
           'Welcome To GoodVibes',
-          '  /setup onboarding   - first-run checklist and health flows',
+          '  /onboarding         - open the onboarding wizard with current settings preloaded',
+          '  /setup onboarding   - open the same onboarding wizard from setup workflows',
           '  /health review      - unified startup, service, and sandbox posture',
           '  /sandbox review     - inspect VM isolation posture',
           '  /marketplace open   - browse curated plugins, skills, hook packs, and policy packs',

package/src/input/commands/local-runtime.ts

@@ -11,6 +11,16 @@ import { BUILTIN_SECRET_PROVIDER_SOURCES, describeSecretRef, isSecretRefInput, r
 import { openCommandPanel, requireBookmarkManager, requireProviderApi, requireSecretsManager } from './runtime-services.ts';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
 
+function isGoodVibesSecretRefInput(value: string): boolean {
+  const normalized = value.trim();
+  return normalized.startsWith('goodvibes://secrets/') && isSecretRefInput(normalized);
+}
+
+function isMalformedGoodVibesSecretRefInput(value: string): boolean {
+  const normalized = value.trim();
+  return normalized.startsWith('goodvibes://') && !isGoodVibesSecretRefInput(normalized);
+}
+
 function toggleBlocks(typeFilter: string, collapsed: boolean, ctx: CommandContext): void {
   const VALID_TYPES = ['all', 'thinking', 'tool', 'code'] as const;
   if (!VALID_TYPES.includes(typeFilter as typeof VALID_TYPES[number])) {
@@ -157,11 +167,11 @@ export function registerLocalRuntimeCommands(registry: CommandRegistry): void {
           ...BUILTIN_SECRET_PROVIDER_SOURCES.map((source) => `  ${source}`),
           '',
           'Examples:',
-          '  /secrets link OPENAI_API_KEY secret://env/OPENAI_API_KEY',
-          '  /secrets link SLACK_BOT_TOKEN bw://GoodVibes%20Slack/password?sessionEnv=BW_SESSION',
-          '  /secrets link SLACK_BOT_TOKEN vaultwarden://GoodVibes%20Slack/password?server=https%3A%2F%2Fvault.example.test',
-          '  /secrets link STRIPE_TOKEN bws://00000000-0000-0000-0000-000000000000/value?accessTokenEnv=BWS_ACCESS_TOKEN',
-          '  /secrets link OPENAI_API_KEY op://Private/GoodVibes%20OpenAI/API%20Key',
+          '  /secrets link OPENAI_API_KEY goodvibes://secrets/env/OPENAI_API_KEY',
+          '  /secrets link SLACK_BOT_TOKEN goodvibes://secrets/bitwarden?item=GoodVibes%20Slack&field=password&sessionEnv=BW_SESSION',
+          '  /secrets link SLACK_BOT_TOKEN goodvibes://secrets/vaultwarden?item=GoodVibes%20Slack&field=password&server=https%3A%2F%2Fvault.example.test',
+          '  /secrets link STRIPE_TOKEN goodvibes://secrets/bws/00000000-0000-0000-0000-000000000000?field=value&accessTokenEnv=BWS_ACCESS_TOKEN',
+          '  /secrets link OPENAI_API_KEY goodvibes://secrets/1password?vault=Private&item=GoodVibes%20OpenAI&field=API%20Key',
         ].join('\n'));
         return;
       }
@@ -171,7 +181,7 @@ export function registerLocalRuntimeCommands(registry: CommandRegistry): void {
           ctx.print('[secrets] Usage: /secrets test <secret-ref>');
           return;
         }
-        if (!isSecretRefInput(refText)) {
+        if (!isGoodVibesSecretRefInput(refText)) {
           ctx.print('[secrets] Invalid secret reference. Use /secrets providers for examples.');
           return;
         }
@@ -192,7 +202,11 @@ export function registerLocalRuntimeCommands(registry: CommandRegistry): void {
           return;
         }
         const value = rawValueParts.join(' ');
-        if (sub === 'link' && !isSecretRefInput(value)) {
+        if (sub === 'link' && !isGoodVibesSecretRefInput(value)) {
+          ctx.print('[secrets] Invalid secret reference. Use /secrets providers for examples.');
+          return;
+        }
+        if (sub === 'set' && isMalformedGoodVibesSecretRefInput(value)) {
           ctx.print('[secrets] Invalid secret reference. Use /secrets providers for examples.');
           return;
         }

package/src/input/commands/local-setup.ts

@@ -1,10 +1,9 @@
-import { dirname, join, resolve } from 'path';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import type { CommandRegistry, CommandContext } from '../command-registry.ts';
+import { dirname, join } from 'path';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import type { CommandRegistry } from '../command-registry.ts';
 import type { ConfigKey } from '../../config/index.ts';
 import { CONFIG_SCHEMA } from '../../config/index.ts';
 import { listHookPointContracts } from '@pellux/goodvibes-sdk/platform/hooks/index';
-import { isRunningInWsl } from '@pellux/goodvibes-sdk/platform/runtime/sandbox/manager';
 import { renderQemuWrapperTemplate } from '@pellux/goodvibes-sdk/platform/runtime/sandbox/qemu-wrapper-template';
 import type { SetupTransferBundle } from './local-setup-transfer.ts';
 import {
@@ -15,20 +14,29 @@ import {
   parseSetupLink,
 } from './local-setup-transfer.ts';
 import { buildSetupReviewSnapshot, exportSetupSupportBundle, renderSetupSandboxReview } from './local-setup-review.ts';
-import { requirePanelManager, requireShellPaths } from './runtime-services.ts';
+import { openOnboardingWizard, requirePanelManager, requireShellPaths } from './runtime-services.ts';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
 
+type SetupSnapshot = Awaited<ReturnType<typeof buildSetupReviewSnapshot>>;
+
 export function registerLocalSetupCommands(registry: CommandRegistry): void {
   registry.register({
     name: 'setup',
     aliases: ['startup'],
-    description: 'Review startup readiness, ecosystem posture, sandbox bring-up, and service configuration',
+    description: 'Launch the onboarding wizard and review startup readiness, service posture, and sandbox bring-up',
     usage: '[review|doctor|services|hooks|remote|sandbox|onboarding|support-bundle <dir>|export <path>|transfer <export|inspect|import> <path>|link <surface> [target]|open-link <uri>]',
     async handler(args, ctx) {
-      const shellPaths = requireShellPaths(ctx);
       const sub = args[0] ?? 'review';
-      const snapshot = await buildSetupReviewSnapshot(ctx);
+      let shellPaths: ReturnType<typeof requireShellPaths> | null = null;
+      let snapshotPromise: Promise<SetupSnapshot> | null = null;
+      const getShellPaths = () => (shellPaths ??= requireShellPaths(ctx));
+      const getSnapshot = async (): Promise<SetupSnapshot> => {
+        snapshotPromise ??= buildSetupReviewSnapshot(ctx);
+        return snapshotPromise;
+      };
+
       if (sub === 'review') {
+        const snapshot = await getSnapshot();
         ctx.print([
           'Startup Readiness Review',
           `  session: ${snapshot.sessionId}`,
@@ -58,6 +66,7 @@ export function registerLocalSetupCommands(registry: CommandRegistry): void {
       }
 
       if (sub === 'doctor') {
+        const snapshot = await getSnapshot();
         ctx.print([
           'Startup Doctor',
           ...snapshot.issues.map((issue) => `  [${issue.severity.toUpperCase()}] ${issue.area}: ${issue.message}`),
@@ -75,6 +84,7 @@ export function registerLocalSetupCommands(registry: CommandRegistry): void {
       }
 
       if (sub === 'services') {
+        const snapshot = await getSnapshot();
         ctx.print([
           'Startup Services',
           `  configured: ${snapshot.serviceCount}`,
@@ -91,6 +101,7 @@ export function registerLocalSetupCommands(registry: CommandRegistry): void {
       }
 
       if (sub === 'hooks') {
+        const snapshot = await getSnapshot();
         const contracts = listHookPointContracts();
         ctx.print([
           'Startup Hooks',
@@ -102,6 +113,7 @@ export function registerLocalSetupCommands(registry: CommandRegistry): void {
       }
 
       if (sub === 'remote') {
+        const snapshot = await getSnapshot();
         const runners = ctx.ops.remoteRuntime?.listContracts() ?? [];
         ctx.print([
           'Startup Remote',
@@ -112,40 +124,19 @@ export function registerLocalSetupCommands(registry: CommandRegistry): void {
       }
 
       if (sub === 'sandbox') {
+        const snapshot = await getSnapshot();
         ctx.print(renderSetupSandboxReview(ctx, snapshot));
         return;
       }
 
       if (sub === 'onboarding') {
-        ctx.print([
-          'Onboarding Checklist',
-          `  providers: ${snapshot.providerCount > 0 ? '[ready]' : '[needs setup]'}`,
-          `  services: ${(snapshot.serviceCount > 0 || snapshot.oauthProviderCount > 0 || snapshot.builtinSubscriptionProviderCount > 0) ? '[ready]' : '[optional]'}`,
-          `  subscriptions: ${snapshot.activeSubscriptionCount > 0 ? '[ready]' : (snapshot.oauthProviderCount + snapshot.builtinSubscriptionProviderCount) > 0 ? '[available]' : '[optional]'}`,
-          `  hooks: ${(snapshot.managedHookCount + snapshot.managedHookChainCount) > 0 ? '[ready]' : '[optional]'}`,
-          `  remote: ${snapshot.remoteRunnerCount > 0 ? '[ready]' : '[optional]'}`,
-          `  sandbox: ${`${ctx.platform.configManager.get('sandbox.vmBackend')}` === 'local' ? '[local default]' : (snapshot.sandboxSecureModeReady ? '[qemu ready]' : '[host blocked]')}`,
-          `  plugins: ${snapshot.pluginCount > 0 ? '[ready]' : '[optional]'}`,
-          `  skills: ${snapshot.skillCount > 0 ? '[ready]' : '[optional]'}`,
-          '',
-          'Recommended next commands:',
-          '  /health review',
-          '  /provider',
-          '  /services doctor',
-          '  /subscription review',
-          '  /hooks scaffold <name> <match> <type>',
-          '  /setup sandbox',
-          '  /sandbox recommend',
-          '  /sandbox qemu bootstrap .goodvibes/tui/sandbox 20',
-          ...(process.platform === 'win32' && !isRunningInWsl() ? ['  Run GoodVibes inside WSL before enabling QEMU sandboxing'] : []),
-          '  /remote setup',
-          '  /plugin browse',
-          '  /skills browse',
-        ].join('\n'));
+        openOnboardingWizard(ctx, { mode: 'edit', reset: true });
+        ctx.print('Opening onboarding wizard.');
         return;
       }
 
       if (sub === 'support-bundle') {
+        const snapshot = await getSnapshot();
         const dirArg = args[1];
         if (!dirArg) {
           ctx.print('Usage: /setup support-bundle <dir>');
@@ -167,12 +158,13 @@ export function registerLocalSetupCommands(registry: CommandRegistry): void {
       }
 
       if (sub === 'export') {
+        const snapshot = await getSnapshot();
         const pathArg = args[1];
         if (!pathArg) {
           ctx.print('Usage: /setup export <path>');
           return;
         }
-        const targetPath = shellPaths.resolveWorkspacePath(pathArg);
+        const targetPath = getShellPaths().resolveWorkspacePath(pathArg);
         mkdirSync(dirname(targetPath), { recursive: true });
         writeFileSync(targetPath, JSON.stringify(snapshot, null, 2) + '\n', 'utf-8');
         ctx.print(`Exported startup review to ${targetPath}`);
@@ -186,8 +178,9 @@ export function registerLocalSetupCommands(registry: CommandRegistry): void {
           ctx.print('Usage: /setup transfer <export|inspect|import> <path>');
           return;
         }
-        const targetPath = shellPaths.resolveWorkspacePath(pathArg);
+        const targetPath = getShellPaths().resolveWorkspacePath(pathArg);
         if (mode === 'export') {
+          const snapshot = await getSnapshot();
           const bundle = buildSetupTransferBundle(ctx, snapshot);
           ctx.print(`Exported setup transfer bundle to ${exportSetupTransferBundle(ctx, pathArg, bundle)}`);
           return;
@@ -210,17 +203,17 @@ export function registerLocalSetupCommands(registry: CommandRegistry): void {
               }
             }
             if (bundle.services) {
-              const servicesPath = shellPaths.resolveProjectPath('tui', 'services.json');
+              const servicesPath = getShellPaths().resolveProjectPath('tui', 'services.json');
               mkdirSync(dirname(servicesPath), { recursive: true });
               writeFileSync(servicesPath, JSON.stringify(bundle.services, null, 2) + '\n', 'utf-8');
             }
             if (bundle.ecosystem?.plugins) {
-              const pluginsPath = shellPaths.resolveProjectPath('tui', 'ecosystem', 'plugins.json');
+              const pluginsPath = getShellPaths().resolveProjectPath('tui', 'ecosystem', 'plugins.json');
               mkdirSync(dirname(pluginsPath), { recursive: true });
               writeFileSync(pluginsPath, JSON.stringify(bundle.ecosystem.plugins, null, 2) + '\n', 'utf-8');
             }
             if (bundle.ecosystem?.skills) {
-              const skillsPath = shellPaths.resolveProjectPath('tui', 'ecosystem', 'skills.json');
+              const skillsPath = getShellPaths().resolveProjectPath('tui', 'ecosystem', 'skills.json');
               mkdirSync(dirname(skillsPath), { recursive: true });
               writeFileSync(skillsPath, JSON.stringify(bundle.ecosystem.skills, null, 2) + '\n', 'utf-8');
             }

package/src/input/commands/onboarding-runtime.ts

@@ -0,0 +1,14 @@
+import type { CommandRegistry } from '../command-registry.ts';
+import { openOnboardingWizard } from './runtime-services.ts';
+
+export function registerOnboardingRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'onboarding',
+    description: 'Open the onboarding wizard with current settings preloaded for review and editing',
+    usage: '',
+    handler(_args, ctx) {
+      openOnboardingWizard(ctx, { mode: 'edit', reset: true });
+      ctx.print('Opening onboarding wizard.');
+    },
+  });
+}

package/src/input/commands/runtime-services.ts

@@ -99,6 +99,15 @@ export function openCommandPanel(
   showPanel(panelId, pane);
 }
 
+export function openOnboardingWizard(
+  context: Pick<CommandContext, 'openOnboardingWizard'>,
+  modeOrOptions?: import('../onboarding/onboarding-wizard.ts').OnboardingWizardMode
+    | import('../handler-ui-state.ts').OpenOnboardingWizardOptions,
+): void {
+  const openWizard = requireContextValue(context.openOnboardingWizard, 'openOnboardingWizard');
+  openWizard(modeOrOptions);
+}
+
 export function requireKeybindingsManager(context: CommandContext) {
   return requireContextValue(context.workspace.keybindingsManager, 'workspace.keybindingsManager');
 }