@pellux/goodvibes-tui 0.19.27 → 0.19.29

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to GoodVibes TUI.
 
 ---
 
+## [0.19.29] — 2026-04-24
+
+### Changes
+- 617b8860 feat: improve onboarding and surface setup
+- 5e39b0f8 docs: add onboarding wizard WIP notice to README top
+
+## [0.19.28] — 2026-04-24
+
+### Changes
+- 89221c1 fix: mark onboarding checked when opened
+
 ## [0.19.27] — 2026-04-24
 
 ### Changes

package/README.md

@@ -1,8 +1,10 @@
+> **ATTENTION:** Currently updating the Onboarding Wizard - Expect problems with starting the TUI until this work is complete!
+
 # goodvibes-tui
 
 [![CI](https://github.com/mgd34msu/goodvibes-tui/actions/workflows/ci.yml/badge.svg)](https://github.com/mgd34msu/goodvibes-tui/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-0.19.27-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
+[![Version](https://img.shields.io/badge/version-0.19.29-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
 
 A terminal-native AI coding, operations, automation, knowledge, and integration console with a typed runtime, omnichannel surfaces, structured memory/knowledge, and a raw ANSI renderer.
 

package/docs/foundation-artifacts/operator-contract.json

@@ -3,7 +3,7 @@
   "product": {
     "id": "goodvibes",
     "surface": "operator",
-    "version": "0.25.1"
+    "version": "0.25.4"
   },
   "auth": {
     "modes": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "0.19.27",
+  "version": "0.19.29",
   "description": "Terminal-native GoodVibes product for coding, operations, automation, knowledge, channels, and daemon-backed control-plane workflows.",
   "type": "module",
   "main": "src/main.ts",
@@ -91,7 +91,7 @@
     "@anthropic-ai/vertex-sdk": "^0.16.0",
     "@ast-grep/napi": "^0.42.0",
     "@aws/bedrock-token-generator": "^1.1.0",
-    "@pellux/goodvibes-sdk": "^0.25.1",
+    "@pellux/goodvibes-sdk": "^0.25.4",
     "bash-language-server": "^5.6.0",
     "fuse.js": "^7.1.0",
     "graphql": "^16.13.2",

package/src/cli/bundle-command.ts

@@ -5,6 +5,7 @@ import { createShellPathService } from '@pellux/goodvibes-sdk/platform/runtime/s
 import { listProviderRuntimeSnapshots } from '@pellux/goodvibes-sdk/platform/providers/runtime-snapshot';
 import { createRuntimeServices } from '../runtime/services.ts';
 import { createRuntimeStore } from '../runtime/store/index.ts';
+import { getOnboardingCheckMarkerPath } from '../runtime/onboarding/index.ts';
 import { CONFIG_SCHEMA } from '../config/index.ts';
 import { SecretsManager } from '../config/secrets.ts';
 import type { ConfigKey } from '../config/index.ts';
@@ -178,8 +179,8 @@ export async function handleBundleCommand(runtime: CliCommandRuntime): Promise<C
       },
       secrets: await secrets.inspect(),
       onboarding: {
-        projectMarker: existsSync(shellPaths.resolveProjectPath('tui', 'onboarding.json')),
-        userMarker: existsSync(shellPaths.resolveUserPath('tui', 'onboarding.json')),
+        userMarker: existsSync(getOnboardingCheckMarkerPath(shellPaths, 'user')),
+        projectMarker: existsSync(getOnboardingCheckMarkerPath(shellPaths, 'project')),
       },
     };
     const targetPath = shellPaths.resolveWorkspacePath(outputPath);

package/src/cli/entrypoint.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ConfigManager } from '../config/index.ts';
-import { readOnboardingCompletionMarkers } from '../runtime/onboarding/index.ts';
+import { readOnboardingCheckMarkers } from '../runtime/onboarding/index.ts';
 import { GlobalNetworkTransportInstaller } from '@pellux/goodvibes-sdk/platform/runtime/network/index';
 import { createShellPathService } from '@pellux/goodvibes-sdk/platform/runtime/shell-paths';
 import { configureActivityLogger } from '@pellux/goodvibes-sdk/platform/utils/logger';
@@ -125,7 +125,7 @@ export async function prepareShellCliRuntime(
     const userStorePath = shellPaths.resolveUserPath('tui', 'auth-users.json');
     const bootstrapCredentialPath = shellPaths.resolveUserPath('tui', 'auth-bootstrap.txt');
     const operatorTokenPath = join(bootstrapHomeDirectory, '.goodvibes', 'daemon', 'operator-tokens.json');
-    const onboardingMarkers = readOnboardingCompletionMarkers(shellPaths);
+    const onboardingMarkers = readOnboardingCheckMarkers(shellPaths);
     const service = await buildCliServicePosture({
       configManager,
       workingDirectory: bootstrapWorkingDir,

package/src/cli/help.ts

@@ -124,7 +124,7 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
   },
   onboarding: {
     usage: ['onboarding', 'setup', 'onboarding status'],
-    summary: 'Open the setup wizard on the next TUI startup, or inspect onboarding marker status from the CLI.',
+    summary: 'Open the setup wizard, or inspect whether onboarding has already been shown for this user.',
     examples: ['onboarding', 'onboarding status'],
   },
   status: {

package/src/cli/status.ts

@@ -1,5 +1,5 @@
 import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config/manager';
-import type { OnboardingCompletionMarkersState } from '../runtime/onboarding/index.ts';
+import type { OnboardingCheckMarkersState } from '../runtime/onboarding/index.ts';
 import { resolveRuntimeEndpointBinding } from './endpoints.ts';
 import { isNetworkFacing } from './network-posture.ts';
 import type { GoodVibesCliOutputFormat } from './types.ts';
@@ -9,7 +9,7 @@ export interface CliStatusOptions {
   readonly configManager: Pick<ConfigManager, 'get'>;
   readonly workingDirectory: string;
   readonly homeDirectory: string;
-  readonly onboardingMarkers?: OnboardingCompletionMarkersState;
+  readonly onboardingMarkers?: OnboardingCheckMarkersState;
   readonly auth?: CliAuthStatus;
   readonly service?: CliServicePosture;
   readonly doctor?: boolean;
@@ -63,7 +63,7 @@ export interface CliStatusSnapshot {
     readonly web: ReturnType<typeof resolveRuntimeEndpointBinding> & { readonly enabled: unknown };
   };
   readonly onboarding: {
-    readonly completed: boolean;
+    readonly checked: boolean;
     readonly scope: string;
     readonly updatedAt: number | null;
   };
@@ -167,13 +167,13 @@ export function buildCliDoctorFindings(options: CliStatusOptions): readonly CliD
     }
   }
 
-  if (!marker?.payload) {
+  if (!marker?.exists) {
     findings.push({
       id: 'onboarding-incomplete',
       area: 'onboarding',
       severity: 'warning',
-      summary: 'Onboarding has not been completed for this user/project.',
-      cause: 'No effective onboarding completion marker was found.',
+      summary: 'Onboarding has not been shown for this user.',
+      cause: 'No global user onboarding check marker was found.',
       impact: 'Important service, network, provider, auth, or permission choices may still be implicit defaults.',
       action: 'Run /onboarding in the TUI or goodvibes onboarding status to review setup state.',
     });
@@ -277,7 +277,7 @@ export function buildCliStatusSnapshot(options: CliStatusOptions): CliStatusSnap
       web: { enabled: config.get('web.enabled'), ...webBinding },
     },
     onboarding: {
-      completed: Boolean(marker?.payload),
+      checked: Boolean(marker?.exists),
       scope: marker?.scope ?? 'none',
       updatedAt: marker?.payload?.updatedAt ?? null,
     },
@@ -344,7 +344,7 @@ export function renderCliStatus(options: CliStatusOptions): string {
     bindLine('web', webEnabled, webBinding),
     '',
     'Onboarding:',
-    `  completed: ${marker?.payload ? 'yes' : 'no'}`,
+    `  checked: ${marker?.exists ? 'yes' : 'no'}`,
     `  scope: ${marker?.scope ?? 'none'}`,
     `  updatedAt: ${marker?.payload ? new Date(marker.payload.updatedAt).toISOString() : 'n/a'}`,
   ];
@@ -372,7 +372,7 @@ export function renderOnboardingCliStatus(options: CliStatusOptions): string {
   const marker = options.onboardingMarkers?.effective;
   return [
     'GoodVibes onboarding status',
-    `  completed: ${marker?.payload ? 'yes' : 'no'}`,
+    `  checked: ${marker?.exists ? 'yes' : 'no'}`,
     `  scope: ${marker?.scope ?? 'none'}`,
     `  source: ${marker?.payload?.source ?? 'n/a'}`,
     `  mode: ${marker?.payload?.mode ?? 'n/a'}`,

package/src/cli/surface-command.ts

@@ -1,4 +1,11 @@
 import type { ConfigKey } from '../config/index.ts';
+import {
+  GOODVIBES_NTFY_AGENT_TOPIC,
+  GOODVIBES_NTFY_CHAT_TOPIC,
+  GOODVIBES_NTFY_REMOTE_TOPIC,
+  resolveGoodVibesNtfyTopics,
+} from '@pellux/goodvibes-sdk/platform/integrations/ntfy';
+import { enableFeatureFlags, getMissingSurfaceFeatureFlags, getServerSurfaceFeatureFlags } from '../runtime/surface-feature-flags.ts';
 import { resolveRuntimeEndpointBinding } from './endpoints.ts';
 import { classifyBindPosture, isNetworkFacing } from './network-posture.ts';
 import type { CliCommandRuntime } from './management.ts';
@@ -18,7 +25,7 @@ export const SURFACE_CONFIGS = [
   ['discord', 'Discord', ['surfaces.discord.publicKey', 'surfaces.discord.botToken', 'surfaces.discord.applicationId']],
   ['telegram', 'Telegram', ['surfaces.telegram.botToken']],
   ['webhook', 'Webhook', ['surfaces.webhook.secret']],
-  ['ntfy', 'ntfy', ['surfaces.ntfy.baseUrl', 'surfaces.ntfy.topic']],
+  ['ntfy', 'ntfy', ['surfaces.ntfy.baseUrl']],
   ['googleChat', 'Google Chat', ['surfaces.googleChat.webhookUrl']],
   ['signal', 'Signal', ['surfaces.signal.bridgeUrl', 'surfaces.signal.account']],
   ['whatsapp', 'WhatsApp', ['surfaces.whatsapp.accessToken', 'surfaces.whatsapp.phoneNumberId']],
@@ -39,6 +46,7 @@ export async function handleSurfacesCommand(runtime: CliCommandRuntime): Promise
     if (target === 'web') {
       runtime.configManager.setDynamic('web.enabled', enabled);
       if (enabled) {
+        enableFeatureFlags(runtime.configManager, getServerSurfaceFeatureFlags({ serverBacked: true, web: true }));
         runtime.configManager.setDynamic('danger.daemon', true);
         runtime.configManager.setDynamic('controlPlane.enabled', true);
         const webError = applyTargetEndpointFlagsOrDefault(runtime, 'web');
@@ -71,6 +79,7 @@ export async function handleSurfacesCommand(runtime: CliCommandRuntime): Promise
     else if (SURFACE_CONFIGS.some(([id]) => id === target)) {
       runtime.configManager.setDynamic(`surfaces.${target}.enabled` as ConfigKey, enabled);
       if (enabled) {
+        enableFeatureFlags(runtime.configManager, getServerSurfaceFeatureFlags({ serverBacked: true, externalSurfaces: [target] }));
         runtime.configManager.setDynamic('danger.httpListener', true);
         enableEndpointLanDefault(runtime.configManager, 'httpListener');
       }
@@ -88,34 +97,45 @@ export async function handleSurfacesCommand(runtime: CliCommandRuntime): Promise
   const web = resolveRuntimeEndpointBinding(config, 'web');
   const httpListener = resolveRuntimeEndpointBinding(config, 'httpListener');
   const includeProbe = sub === 'check';
+  const targetExternalSurface = target && SURFACE_CONFIGS.some(([id]) => id === target);
+  const shouldProbeControlPlane = includeProbe && !target;
+  const shouldProbeWeb = includeProbe && !target;
+  const shouldProbeListener = includeProbe && (!target || targetExternalSurface);
   const [controlPlaneReachable, webReachable, listenerReachable] = includeProbe
     ? await Promise.all([
-      probeTcp(controlPlane.host, controlPlane.port),
-      probeTcp(web.host, web.port),
-      probeTcp(httpListener.host, httpListener.port),
+      shouldProbeControlPlane ? probeTcp(controlPlane.host, controlPlane.port) : Promise.resolve(undefined),
+      shouldProbeWeb ? probeTcp(web.host, web.port) : Promise.resolve(undefined),
+      shouldProbeListener ? probeTcp(httpListener.host, httpListener.port) : Promise.resolve(undefined),
     ])
     : [undefined, undefined, undefined];
   const externalSurfaces = SURFACE_CONFIGS.map(([id, label, requiredKeys]) => {
     const enabled = config.get(`surfaces.${id}.enabled` as ConfigKey);
     const missing = requiredKeys.filter((key) => !isPresentConfigValue(config.get(key as ConfigKey)));
+    const missingFeatureFlags = enabled === true ? getMissingSurfaceFeatureFlags(config, id) : [];
     return {
       id,
       label,
       enabled,
-      ready: !enabled || missing.length === 0,
+      ready: !enabled || (missing.length === 0 && missingFeatureFlags.length === 0),
       missing,
+      missingFeatureFlags,
     };
   });
   const filteredSurfaces = target ? externalSurfaces.filter((surface) => surface.id === target) : externalSurfaces;
   if (target && filteredSurfaces.length === 0) return { output: `Unknown surface: ${target}`, exitCode: 1 };
+  const ntfyTopics = resolveGoodVibesNtfyTopics({
+    chatTopic: String(config.get('surfaces.ntfy.chatTopic' as ConfigKey) || GOODVIBES_NTFY_CHAT_TOPIC),
+    agentTopic: String(config.get('surfaces.ntfy.agentTopic' as ConfigKey) || GOODVIBES_NTFY_AGENT_TOPIC),
+    remoteTopic: String(config.get('surfaces.ntfy.remoteTopic' as ConfigKey) || GOODVIBES_NTFY_REMOTE_TOPIC),
+  });
   const readinessIssues: string[] = [];
-  if (includeProbe && config.get('controlPlane.enabled') === true && !controlPlaneReachable) {
+  if (shouldProbeControlPlane && config.get('controlPlane.enabled') === true && !controlPlaneReachable) {
     readinessIssues.push(`Control plane is enabled but not reachable on ${controlPlane.host}:${controlPlane.port}.`);
   }
-  if (includeProbe && config.get('web.enabled') === true && !webReachable) {
+  if (shouldProbeWeb && config.get('web.enabled') === true && !webReachable) {
     readinessIssues.push(`Web surface is enabled but not reachable on ${web.host}:${web.port}.`);
   }
-  if (includeProbe && config.get('danger.httpListener') === true && !listenerReachable) {
+  if (shouldProbeListener && config.get('danger.httpListener') === true && !listenerReachable) {
     readinessIssues.push(`HTTP listener is enabled but not reachable on ${httpListener.host}:${httpListener.port}.`);
   }
   for (const surface of filteredSurfaces) {
@@ -126,6 +146,9 @@ export async function handleSurfacesCommand(runtime: CliCommandRuntime): Promise
     if (surface.missing.length > 0) {
       readinessIssues.push(`${surface.label} is enabled but missing ${surface.missing.join(', ')}.`);
     }
+    if (surface.missingFeatureFlags.length > 0) {
+      readinessIssues.push(`${surface.label} is enabled but feature gates are disabled: ${surface.missingFeatureFlags.join(', ')}.`);
+    }
   }
   const value = {
     controlPlane: {
@@ -162,7 +185,15 @@ export async function handleSurfacesCommand(runtime: CliCommandRuntime): Promise
     `  http-listener: ${yesNo(value.httpListener.enabled)} (${value.httpListener.hostMode} ${value.httpListener.host}:${value.httpListener.port})${includeProbe ? ` reachable=${yesNo(value.httpListener.reachable)}` : ''}`,
     '',
     'External surfaces:',
-    ...value.surfaces.map((surface) => `  ${surface.label.padEnd(16)} enabled=${yesNo(surface.enabled)} ready=${yesNo(surface.ready)}${surface.enabled && surface.missing.length > 0 ? ` missing=${surface.missing.join(',')}` : ''}`),
+    ...value.surfaces.map((surface) => `  ${surface.label.padEnd(16)} enabled=${yesNo(surface.enabled)} ready=${yesNo(surface.ready)}${surface.enabled && surface.missing.length > 0 ? ` missing=${surface.missing.join(',')}` : ''}${surface.enabled && surface.missingFeatureFlags.length > 0 ? ` featureGates=${surface.missingFeatureFlags.join(',')}` : ''}`),
+    ...(filteredSurfaces.some((surface) => surface.id === 'ntfy') ? [
+      '',
+      'ntfy inbound topics:',
+      `  chat: ${ntfyTopics.chatTopic}`,
+      `  agent: ${ntfyTopics.agentTopic}`,
+      `  daemon-only remote: ${ntfyTopics.remoteTopic}`,
+      `  default delivery topic: ${String(config.get('surfaces.ntfy.topic') || '(none)')}`,
+    ] : []),
     ...(includeProbe ? [
       readinessIssues.length === 0 ? 'Readiness: ready' : 'Readiness: needs attention',
       ...readinessIssues.map((issue) => `  - ${issue}`),
@@ -191,6 +222,7 @@ export interface ListenerTestResult {
     readonly enabled: unknown;
     readonly ready: boolean;
     readonly missing: readonly string[];
+    readonly missingFeatureFlags: readonly string[];
   }[];
   readonly issues: readonly string[];
 }
@@ -209,12 +241,14 @@ export async function buildListenerTestResult(runtime: CliCommandRuntime): Promi
   const surfaces = SURFACE_CONFIGS.map(([id, label, requiredKeys]) => {
     const surfaceEnabled = runtime.configManager.get(`surfaces.${id}.enabled` as ConfigKey);
     const missing = requiredKeys.filter((key) => !isPresentConfigValue(runtime.configManager.get(key as ConfigKey)));
+    const missingFeatureFlags = surfaceEnabled === true ? getMissingSurfaceFeatureFlags(runtime.configManager, id) : [];
     return {
       id,
       label,
       enabled: surfaceEnabled,
-      ready: surfaceEnabled !== true || missing.length === 0,
+      ready: surfaceEnabled !== true || (missing.length === 0 && missingFeatureFlags.length === 0),
       missing,
+      missingFeatureFlags,
     };
   }).filter((surface) => surface.enabled === true);
   const issues: string[] = [];
@@ -226,6 +260,7 @@ export async function buildListenerTestResult(runtime: CliCommandRuntime): Promi
   if (isNetworkFacing(enabled, binding) && auth.bootstrapCredentialPresent) issues.push('Network-facing listener still has a bootstrap credential file.');
   for (const surface of surfaces) {
     if (surface.missing.length > 0) issues.push(`${surface.label} is enabled but missing ${surface.missing.join(', ')}.`);
+    if (surface.missingFeatureFlags.length > 0) issues.push(`${surface.label} is enabled but feature gates are disabled: ${surface.missingFeatureFlags.join(', ')}.`);
   }
   return { enabled, ...binding, posture, reachable, service, auth, surfaces, issues };
 }
@@ -241,7 +276,7 @@ export function formatListenerTestResult(runtime: CliCommandRuntime, value: List
     `  local auth users: ${value.auth.userStorePresent ? 'present' : 'missing'}`,
     `  bootstrap credential: ${value.auth.bootstrapCredentialPresent ? 'present' : 'missing'}`,
     value.surfaces.length === 0 ? '  enabled webhook surfaces: none' : '  enabled webhook surfaces:',
-    ...value.surfaces.map((surface) => `    ${surface.label}: ready=${yesNo(surface.ready)}${surface.missing.length > 0 ? ` missing=${surface.missing.join(',')}` : ''}`),
+    ...value.surfaces.map((surface) => `    ${surface.label}: ready=${yesNo(surface.ready)}${surface.missing.length > 0 ? ` missing=${surface.missing.join(',')}` : ''}${surface.missingFeatureFlags.length > 0 ? ` featureGates=${surface.missingFeatureFlags.join(',')}` : ''}`),
     value.issues.length === 0 ? '  readiness: ready' : '  readiness: needs attention',
     ...value.issues.map((issue) => `    - ${issue}`),
   ].join('\n'));

package/src/cli/tui-startup.ts

@@ -1,6 +1,6 @@
 import type { CommandContext, CommandRegistry } from '../input/command-registry.ts';
 import type { InputHandler } from '../input/handler.ts';
-import { readOnboardingCompletionMarkers } from '../runtime/onboarding/index.ts';
+import { readOnboardingCheckMarker } from '../runtime/onboarding/index.ts';
 import type { GoodVibesCliParseResult } from './types.ts';
 
 export function applyInitialTuiCliState(options: {
@@ -8,11 +8,11 @@ export function applyInitialTuiCliState(options: {
   readonly input: InputHandler;
   readonly commandRegistry: CommandRegistry;
   readonly commandContext: CommandContext;
-  readonly shellPaths: Parameters<typeof readOnboardingCompletionMarkers>[0];
+  readonly shellPaths: Parameters<typeof readOnboardingCheckMarker>[0];
   readonly render: () => void;
 }): void {
   const { cli, input, commandRegistry, commandContext, shellPaths, render } = options;
-  const onboardingMarkers = readOnboardingCompletionMarkers(shellPaths);
+  const globalOnboardingMarker = readOnboardingCheckMarker(shellPaths, 'user');
   if (cli.command === 'onboarding') {
     input.openOnboardingWizard({ mode: 'edit', reset: true });
   } else if (cli.command === 'sessions' && cli.commandArgs[0] === 'resume') {
@@ -20,7 +20,7 @@ export function applyInitialTuiCliState(options: {
     if (target) {
       void commandRegistry.execute('session', ['resume', target], commandContext).then(() => render());
     }
-  } else if (!onboardingMarkers.effective?.payload) {
+  } else if (!globalOnboardingMarker.exists) {
     input.openOnboardingWizard({ mode: 'new', reset: true });
   }
 

package/src/daemon/cli.ts

@@ -3,6 +3,8 @@ import { join } from 'node:path';
 import { readFileSync } from 'node:fs';
 import { ConfigManager } from '@pellux/goodvibes-sdk/platform/config/manager';
 import { RuntimeEventBus } from '@pellux/goodvibes-sdk/platform/runtime/events/index';
+import { createFeatureFlagManager } from '@pellux/goodvibes-sdk/platform/runtime/feature-flags/index';
+import type { FlagState } from '@pellux/goodvibes-sdk/platform/runtime/feature-flags/types';
 import { createRuntimeStore } from '../runtime/store/index.ts';
 import { createRuntimeServices } from '../runtime/services.ts';
 import { DaemonServer } from '@pellux/goodvibes-sdk/platform/daemon/server';
@@ -155,8 +157,13 @@ async function main(): Promise<void> {
   }
   const runtimeBus = new RuntimeEventBus();
   const runtimeStore = createRuntimeStore();
+  const featureFlags = createFeatureFlagManager();
+  featureFlags.loadFromConfig({
+    flags: (config.getCategory('featureFlags') as Record<string, FlagState>) ?? {},
+  });
   const runtimeServices = createRuntimeServices({
     configManager: config,
+    featureFlags,
     runtimeBus,
     runtimeStore,
     getConversationTitle: () => 'goodvibes daemon',

package/src/input/handler-interactions.ts

@@ -1,6 +1,6 @@
 import { buildProviderAccountSnapshot } from '@pellux/goodvibes-sdk/platform/runtime/provider-accounts/registry';
 import type { OnboardingWizardMode } from './onboarding/onboarding-wizard.ts';
-import { collectOnboardingSnapshot } from '../runtime/onboarding/index.ts';
+import { collectOnboardingSnapshot, readOnboardingCheckMarker, writeOnboardingCheckMarker } from '../runtime/onboarding/index.ts';
 import { cleanupMarkerRegistry, expandPrompt, findMarkerAtPos, handleBlockCopy, handleBlockRerun, handleBlockSave, handleBlockToggle, handleBookmark, handleClipboardPaste, handleCopy, handleCtrlC, handleDiffApply, registerPaste } from './handler-content-actions.ts';
 import { clearModalStack, handleEscape, modalOpened } from './handler-modal-stack.ts';
 import { openOnboardingWizardState, type OpenOnboardingWizardOptions } from './handler-ui-state.ts';
@@ -11,6 +11,19 @@ export function openOnboardingWizardForHandler(
     modeOrOptions: OnboardingWizardMode | OpenOnboardingWizardOptions = 'new',
   ): void {
     const options = typeof modeOrOptions === 'string' ? { mode: modeOrOptions } : modeOrOptions;
+    const userMarker = readOnboardingCheckMarker(handler.uiServices.environment.shellPaths, 'user');
+    if (!userMarker.payload) {
+      try {
+        writeOnboardingCheckMarker(handler.uiServices.environment.shellPaths, {
+          scope: 'user',
+          source: 'wizard',
+          mode: options.mode ?? 'new',
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        handler.commandContext?.print?.(`Onboarding check marker could not be written: ${message}`);
+      }
+    }
     if (!handler.modalStack.includes('onboarding')) handler.modalOpened('onboarding');
     handler.clearOnboardingModelPickerCancelState();
     openOnboardingWizardState(handler.onboardingWizard, options);