@pellux/goodvibes-tui 0.19.26 → 0.19.28

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

@@ -26,7 +26,6 @@ type RenderedFieldRow =
       readonly kind: 'field';
       readonly field: OnboardingWizardFieldDefinition;
       readonly absoluteIndex: number;
-      readonly line: 0 | 1;
     };
 
 function clamp(value: number, min: number, max: number): number {
@@ -95,7 +94,11 @@ function fieldBadgeTone(
     return wizard.getFieldValue(field) ? UI_TONES.state.good : UI_TONES.fg.muted;
   }
   if (field.kind === 'radio') return UI_TONES.state.active;
-  if (field.kind === 'masked') return UI_TONES.state.warn;
+  if (field.kind === 'text' || field.kind === 'masked') {
+    const missingRequired = wizard.getFieldValueLabel(field) === 'Missing';
+    if (missingRequired) return UI_TONES.state.warn;
+    if (field.kind === 'masked') return UI_TONES.state.warn;
+  }
   return UI_TONES.fg.secondary;
 }
 
@@ -116,8 +119,7 @@ function buildFieldRows(
 
   fieldWindow.fields.forEach((field, index) => {
     const absoluteIndex = fieldWindow.start + index;
-    rows.push({ kind: 'field', field, absoluteIndex, line: 0 });
-    rows.push({ kind: 'field', field, absoluteIndex, line: 1 });
+    rows.push({ kind: 'field', field, absoluteIndex });
   });
 
   if (fieldWindow.end < fieldWindow.total) {
@@ -155,6 +157,48 @@ function fieldHint(
   return field.hint;
 }
 
+function fieldRowPrefix(
+  wizard: OnboardingWizardController,
+  field: OnboardingWizardFieldDefinition,
+  selected: boolean,
+): string {
+  if (selected) return `${OVERLAY_GLYPHS.selected} `;
+  if (wizard.isFieldDirty(field.id)) return '◇ ';
+  if (field.kind === 'checklist') return (wizard.getFieldValue(field) as boolean) ? '✓ ' : '□ ';
+  if (field.kind === 'acknowledgement') return (wizard.getFieldValue(field) as boolean) ? '✓ ' : '□ ';
+  if (field.kind === 'action') return '▶ ';
+  if (field.kind === 'radio') return '◉ ';
+  return '  ';
+}
+
+function selectedFieldText(wizard: OnboardingWizardController): {
+  readonly title: string;
+  readonly hint: string;
+} {
+  if (wizard.isEditingTextField() && wizard.editingFieldId !== null) {
+    const editingField = wizard.getFieldById(wizard.editingFieldId);
+    if (editingField) {
+      return {
+        title: `Editing: ${editingField.label}`,
+        hint: fieldHint(wizard, editingField, true),
+      };
+    }
+  }
+
+  const field = wizard.getSelectedField();
+  if (!field) {
+    return {
+      title: 'Selected: none',
+      hint: 'No selectable row is active on this screen.',
+    };
+  }
+
+  return {
+    title: `Selected: ${field.label} [${wizard.getFieldValueLabel(field)}]`,
+    hint: fieldHint(wizard, field, true),
+  };
+}
+
 function renderFieldRow(
   line: Line,
   wizard: OnboardingWizardController,
@@ -178,38 +222,36 @@ function renderFieldRow(
   const fieldBg = selected ? DEFAULT_OVERLAY_PALETTE.selectedBg : UI_TONES.bg.base;
   fillRange(line, startX, width, fieldBg);
 
-  if (fieldRow.line === 0) {
-    const badge = truncateDisplay(`[${wizard.getFieldValueLabel(field)}]`, Math.max(8, Math.floor(width * 0.38)));
-    const badgeWidth = getDisplayWidth(badge);
-    const prefix = selected ? `${OVERLAY_GLYPHS.selected} ` : wizard.isFieldDirty(field.id) ? '◇ ' : '  ';
-    const labelWidth = Math.max(0, width - badgeWidth - 4);
-
-    putOverlayText(line, startX + 1, labelWidth, truncateDisplay(`${prefix}${field.label}`, labelWidth), {
-      fg: UI_TONES.fg.primary,
-      bg: fieldBg,
-      bold: selected,
-    });
-    putOverlayText(line, startX + width - badgeWidth - 1, badgeWidth, badge, {
-      fg: fieldBadgeTone(wizard, field),
-      bg: fieldBg,
-      bold: selected,
-    });
-    return;
-  }
+  const badge = truncateDisplay(`[${wizard.getFieldValueLabel(field)}]`, Math.max(8, Math.floor(width * 0.34)));
+  const badgeWidth = getDisplayWidth(badge);
+  const labelWidth = Math.max(0, width - badgeWidth - 4);
+  const prefix = fieldRowPrefix(wizard, field, selected);
 
-  putOverlayText(line, startX + 3, Math.max(0, width - 4), truncateDisplay(fieldHint(wizard, field, selected), Math.max(0, width - 4)), {
-    fg: selected ? UI_TONES.fg.secondary : UI_TONES.fg.muted,
+  putOverlayText(line, startX + 1, labelWidth, truncateDisplay(`${prefix}${field.label}`, labelWidth), {
+    fg: UI_TONES.fg.primary,
     bg: fieldBg,
-    dim: !selected,
+    bold: selected,
+  });
+  putOverlayText(line, startX + width - badgeWidth - 1, badgeWidth, badge, {
+    fg: fieldBadgeTone(wizard, field),
+    bg: fieldBg,
+    bold: selected,
   });
 }
 
 function footerText(wizard: OnboardingWizardController): string {
   if (wizard.isEditingTextField()) {
-    return '[Enter] Save  [Esc] Cancel  [Backspace] Delete  [Type] Edit value';
+    return '[Enter] Save value  [Esc] Cancel edit  [Backspace] Delete  [Type] Edit value';
   }
 
-  return '[Tab/Shift+Tab] Step  [↑↓/j/k] Move  [Enter/Space] Toggle/Open  [1-9] Jump  [Esc] Close';
+  return '[Enter] Toggle/open selected  [Tab] Next screen  [Shift+Tab] Previous  [↑↓] Move  [Esc] Close';
+}
+
+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 or Space changes the selected row; Tab/Shift+Tab changes screens; arrows move; typing edits selected inputs.';
 }
 
 function renderWideLayout(
@@ -252,12 +294,13 @@ function renderWideLayout(
   const descriptionLines = wrapText(currentStep.description, Math.max(18, centerWidth - 2)).slice(0, 2);
   const summaryLines = [
     currentStep.summaryTitle,
-    ...currentStep.summaryLines,
+    ...currentStep.summaryLines.slice(0, 2),
     `Fields ${wizard.getCompletedFieldCount(wizard.stepIndex)}/${wizard.getStepFieldCount(wizard.stepIndex)} complete`,
     `Dirty steps ${wizard.dirtyStepCount}`,
-    `Pending picker ${wizard.pendingModelPickerTarget ?? 'none'}`,
   ];
-  const fieldRows = buildFieldRows(wizard, visibleFields, Math.max(0, bodyRows - 3));
+  const fieldStartRow = 5;
+  const selectedText = selectedFieldText(wizard);
+  const fieldRows = buildFieldRows(wizard, visibleFields, Math.max(0, bodyRows - fieldStartRow));
 
   const topLine = createOverlayFilledBorderLine(
     width,
@@ -296,7 +339,7 @@ function renderWideLayout(
     bg: headerBg,
     bold: true,
   });
-  putOverlayText(headerLine, rightStart + 1, rightWidth - 2, 'Summary Rail', {
+  putOverlayText(headerLine, rightStart + 1, rightWidth - 2, 'Summary', {
     fg: UI_TONES.fg.secondary,
     bg: summaryBg,
     bold: true,
@@ -333,28 +376,40 @@ function renderWideLayout(
         bg: bodyBg,
       });
     } else if (row === 2) {
-      const status = fitDisplay(
-        `Fields ${wizard.getCompletedFieldCount(wizard.stepIndex)}/${wizard.getStepFieldCount(wizard.stepIndex)} complete • ${modeLabel(wizard.mode)}`,
-        centerWidth - 2,
-      );
-      putOverlayText(line, centerStart + 1, centerWidth - 2, descriptionLines[1] ?? status, {
+      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) {
+      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) {
+      fillRange(line, centerStart, centerWidth, DEFAULT_OVERLAY_PALETTE.selectedBg);
+      putOverlayText(line, centerStart + 1, centerWidth - 2, truncateDisplay(selectedText.hint, centerWidth - 2), {
         fg: UI_TONES.fg.secondary,
-        bg: bodyBg,
+        bg: DEFAULT_OVERLAY_PALETTE.selectedBg,
       });
     } else {
-      renderFieldRow(line, wizard, fieldRows[row - 3] ?? { kind: 'empty' }, centerStart, centerWidth);
+      renderFieldRow(line, wizard, fieldRows[row - fieldStartRow] ?? { kind: 'empty' }, centerStart, centerWidth);
     }
 
     const step = wizard.steps[row] ?? null;
     if (step) {
       const stepState = stepGlyph(wizard, step, row);
       const completion = `${wizard.getCompletedFieldCount(row)}/${wizard.getStepFieldCount(row)}`;
-      putOverlayText(line, leftStart + 1, leftWidth - 2, truncateDisplay(`${stepState.glyph} ${row + 1}. ${step.shortLabel}`, leftWidth - 2), {
+      const completionWidth = getDisplayWidth(completion);
+      const stepLabelWidth = Math.max(0, leftWidth - completionWidth - 4);
+      putOverlayText(line, leftStart + 1, stepLabelWidth, truncateDisplay(`${stepState.glyph} ${row + 1}. ${step.shortLabel}`, stepLabelWidth), {
         fg: stepState.fg,
         bg: railBg,
         bold: row === wizard.stepIndex,
       });
-      putOverlayText(line, Math.max(leftStart + 1, leftStart + leftWidth - getDisplayWidth(completion) - 2), leftWidth - 2, completion, {
+      putOverlayText(line, Math.max(leftStart + 1, leftStart + leftWidth - completionWidth - 2), completionWidth, completion, {
         fg: wizard.isStepDirty(row) ? UI_TONES.state.warn : UI_TONES.fg.muted,
         bg: railBg,
       });
@@ -418,7 +473,9 @@ 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 fieldRows = buildFieldRows(wizard, visibleFields, Math.max(0, bodyRows - 3));
+  const fieldStartRow = 5;
+  const selectedText = selectedFieldText(wizard);
+  const fieldRows = buildFieldRows(wizard, visibleFields, Math.max(0, bodyRows - fieldStartRow));
 
   const topLine = createOverlayFilledBorderLine(
     width,
@@ -476,16 +533,26 @@ function renderCollapsedLayout(
         bg: bodyBg,
       });
     } else if (row === 2) {
-      const compactMeta = fitDisplay(
-        `${currentStep.summaryTitle} • ${wizard.getCompletedFieldCount(wizard.stepIndex)}/${wizard.getStepFieldCount(wizard.stepIndex)} complete`,
-        innerWidth - 2,
-      );
-      putOverlayText(line, innerStart + 1, innerWidth - 2, descriptionLines[1] ?? compactMeta, {
+      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) {
+      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) {
+      fillRange(line, innerStart, innerWidth, DEFAULT_OVERLAY_PALETTE.selectedBg);
+      putOverlayText(line, innerStart + 1, innerWidth - 2, truncateDisplay(selectedText.hint, innerWidth - 2), {
         fg: UI_TONES.fg.secondary,
-        bg: bodyBg,
+        bg: DEFAULT_OVERLAY_PALETTE.selectedBg,
       });
     } else {
-      renderFieldRow(line, wizard, fieldRows[row - 3] ?? { kind: 'empty' }, innerStart, innerWidth);
+      renderFieldRow(line, wizard, fieldRows[row - fieldStartRow] ?? { kind: 'empty' }, innerStart, innerWidth);
     }
 
     lines.push(line);

package/src/runtime/onboarding/apply.ts

@@ -2,12 +2,6 @@ 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 {
-  clearOnboardingCompletionMarker,
-  getOnboardingCompletionMarkerPath,
-  readOnboardingCompletionMarker,
-  writeOnboardingCompletionMarker,
-} from './markers.ts';
 import {
   getOnboardingRuntimeStatePath,
   readOnboardingRuntimeState,
@@ -27,11 +21,6 @@ function getNow(deps: Pick<OnboardingApplyDependencies, 'clock'>): number {
   return deps.clock?.() ?? Date.now();
 }
 
-function normalizeCompletionSource(source: string): 'wizard' | 'command' | 'import' | 'unknown' {
-  if (source === 'wizard' || source === 'command' || source === 'import') return source;
-  return 'unknown';
-}
-
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -234,17 +223,6 @@ function validateAcknowledgementOperation(
   }
 }
 
-function validateCompletionMarkerOperation(
-  deps: OnboardingApplyDependencies,
-  operation: Extract<OnboardingApplyOperation, { kind: 'set-completion-marker' }>,
-): void {
-  const marker = readOnboardingCompletionMarker(deps.shellPaths, operation.scope);
-  if (marker.parseError && !operation.completed) return;
-  if (marker.parseError) {
-    throw new Error(`Existing ${operation.scope} onboarding marker could not be parsed: ${marker.parseError}`);
-  }
-}
-
 function applyConfigOperation(
   deps: OnboardingApplyDependencies,
   operation: Extract<OnboardingApplyOperation, { kind: 'set-config' }>,
@@ -433,9 +411,8 @@ async function buildRollbackAction(
     );
   }
 
-  return snapshotFileRollback(
-    getOnboardingCompletionMarkerPath(deps.shellPaths, operation.scope),
-  );
+  const neverOperation: never = operation;
+  throw new Error(`Unsupported onboarding operation: ${JSON.stringify(neverOperation)}`);
 }
 
 function applyAcknowledgementOperation(
@@ -458,35 +435,6 @@ function applyAcknowledgementOperation(
   };
 }
 
-function applyCompletionMarkerOperation(
-  deps: OnboardingApplyDependencies,
-  request: OnboardingApplyRequest,
-  operation: Extract<OnboardingApplyOperation, { kind: 'set-completion-marker' }>,
-): OnboardingAppliedOperation {
-  if (!operation.completed) {
-    clearOnboardingCompletionMarker(deps.shellPaths, operation.scope);
-    return {
-      kind: operation.kind,
-      summary: `Cleared ${operation.scope} onboarding completion marker.`,
-    };
-  }
-
-  const updatedAt = getNow(deps);
-  writeOnboardingCompletionMarker(deps.shellPaths, {
-    scope: operation.scope,
-    completedAt: operation.payload?.completedAt,
-    updatedAt: operation.payload?.updatedAt ?? updatedAt,
-    source: operation.payload?.source ?? normalizeCompletionSource(request.source),
-    mode: operation.payload?.mode ?? request.mode,
-    workspaceRoot: operation.payload?.workspaceRoot,
-  });
-
-  return {
-    kind: operation.kind,
-    summary: `Wrote ${operation.scope} onboarding completion marker.`,
-  };
-}
-
 function orderApplyOperations(
   operations: readonly OnboardingApplyOperation[],
 ): readonly OnboardingApplyOperation[] {
@@ -499,7 +447,7 @@ function orderApplyOperations(
     operation.kind === 'set-config' && operation.key !== 'storage.secretPolicy'
   ));
   const finalOperations = operations.filter((operation) => (
-    operation.kind === 'acknowledge' || operation.kind === 'set-completion-marker'
+    operation.kind === 'acknowledge'
   ));
 
   return [
@@ -543,7 +491,8 @@ function prevalidateApplyRequest(
         continue;
       }
 
-      validateCompletionMarkerOperation(deps, operation);
+      const neverOperation: never = operation;
+      throw new Error(`Unsupported onboarding operation: ${JSON.stringify(neverOperation)}`);
     } catch (error) {
       errors.push({
         kind: operation.kind,
@@ -560,22 +509,9 @@ function getVerificationFailureKind(itemId: string): OnboardingApplyOperation['k
   if (itemId.startsWith('secret:')) return 'set-secret';
   if (itemId.startsWith('auth:')) return 'ensure-auth-user';
   if (itemId.startsWith('acknowledge:')) return 'acknowledge';
-  if (itemId.startsWith('marker:')) return 'set-completion-marker';
   return 'set-config';
 }
 
-function splitCompletionMarkerOperations(
-  operations: readonly OnboardingApplyOperation[],
-): {
-  readonly preMarkerOperations: readonly OnboardingApplyOperation[];
-  readonly markerOperations: readonly OnboardingApplyOperation[];
-} {
-  return {
-    preMarkerOperations: operations.filter((operation) => operation.kind !== 'set-completion-marker'),
-    markerOperations: operations.filter((operation) => operation.kind === 'set-completion-marker'),
-  };
-}
-
 export async function applyOnboardingRequest(
   deps: OnboardingApplyDependencies,
   request: OnboardingApplyRequest,
@@ -593,7 +529,6 @@ export async function applyOnboardingRequest(
   }
 
   const orderedOperations = orderApplyOperations(request.operations);
-  const { preMarkerOperations, markerOperations } = splitCompletionMarkerOperations(orderedOperations);
   const rollbacks: RollbackAction[] = [];
 
   const applyOperations = async (operations: readonly OnboardingApplyOperation[]): Promise<boolean> => {
@@ -625,8 +560,8 @@ export async function applyOnboardingRequest(
           continue;
         }
 
-        applied.push(applyCompletionMarkerOperation(deps, request, operation));
-        rollbacks.push(rollback);
+        const neverOperation: never = operation;
+        throw new Error(`Unsupported onboarding operation: ${JSON.stringify(neverOperation)}`);
       } catch (error) {
         const rollbackErrors = await runRollbacks([...rollbacks, rollback]);
         applied.length = 0;
@@ -660,19 +595,11 @@ export async function applyOnboardingRequest(
     return false;
   };
 
-  if (!await applyOperations(preMarkerOperations)) {
-    return { ok: false, applied, skipped, errors };
-  }
-
-  if (!await verifyOrRollback(preMarkerOperations)) {
-    return { ok: false, applied, skipped, errors };
-  }
-
-  if (!await applyOperations(markerOperations)) {
+  if (!await applyOperations(orderedOperations)) {
     return { ok: false, applied, skipped, errors };
   }
 
-  if (!await verifyOrRollback(request.operations)) {
+  if (!await verifyOrRollback(orderedOperations)) {
     return { ok: false, applied, skipped, errors };
   }
 

package/src/runtime/onboarding/markers.ts

@@ -1,15 +1,15 @@
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import type { ShellPathService } from '@pellux/goodvibes-sdk/platform/runtime/shell-paths';
 import type {
-  OnboardingCompletionMarkerPayload,
-  OnboardingCompletionMarkerScope,
-  OnboardingCompletionMarkerState,
-  OnboardingCompletionMarkersState,
-  WriteOnboardingCompletionMarkerOptions,
+  OnboardingCheckMarkerPayload,
+  OnboardingCheckMarkerState,
+  OnboardingCheckMarkersState,
+  OnboardingStateScope,
+  WriteOnboardingCheckMarkerOptions,
 } from './types.ts';
 
-const ONBOARDING_COMPLETION_MARKER_FILE = 'onboarding-complete.json';
+const ONBOARDING_CHECK_MARKER_FILE = 'onboarding-checked.json';
 
 type OnboardingShellPaths = Pick<
   ShellPathService,
@@ -18,26 +18,26 @@ type OnboardingShellPaths = Pick<
 
 function resolveMarkerPath(
   shellPaths: OnboardingShellPaths,
-  scope: OnboardingCompletionMarkerScope,
+  scope: OnboardingStateScope,
 ): string {
   return scope === 'project'
-    ? shellPaths.resolveProjectPath('tui', ONBOARDING_COMPLETION_MARKER_FILE)
-    : shellPaths.resolveUserPath('tui', ONBOARDING_COMPLETION_MARKER_FILE);
+    ? shellPaths.resolveProjectPath('tui', ONBOARDING_CHECK_MARKER_FILE)
+    : shellPaths.resolveUserPath('tui', ONBOARDING_CHECK_MARKER_FILE);
 }
 
 function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }
 
-function isOnboardingMode(value: unknown): value is OnboardingCompletionMarkerPayload['mode'] {
+function isOnboardingMode(value: unknown): value is OnboardingCheckMarkerPayload['mode'] {
   return value === 'new' || value === 'edit' || value === 'reopen';
 }
 
-function isCompletionMarkerPayload(value: unknown): value is OnboardingCompletionMarkerPayload {
+function isCheckMarkerPayload(value: unknown): value is OnboardingCheckMarkerPayload {
   return isObject(value)
     && value.version === 1
-    && typeof value.completedAt === 'number'
-    && Number.isFinite(value.completedAt)
+    && typeof value.checkedAt === 'number'
+    && Number.isFinite(value.checkedAt)
     && typeof value.updatedAt === 'number'
     && Number.isFinite(value.updatedAt)
     && typeof value.source === 'string'
@@ -46,9 +46,9 @@ function isCompletionMarkerPayload(value: unknown): value is OnboardingCompletio
 }
 
 function buildMissingMarkerState(
-  scope: OnboardingCompletionMarkerScope,
+  scope: OnboardingStateScope,
   path: string,
-): OnboardingCompletionMarkerState {
+): OnboardingCheckMarkerState {
   return {
     scope,
     path,
@@ -58,10 +58,10 @@ function buildMissingMarkerState(
 }
 
 function buildParseErrorState(
-  scope: OnboardingCompletionMarkerScope,
+  scope: OnboardingStateScope,
   path: string,
   parseError: string,
-): OnboardingCompletionMarkerState {
+): OnboardingCheckMarkerState {
   return {
     scope,
     path,
@@ -72,34 +72,31 @@ function buildParseErrorState(
 }
 
 function pickEffectiveMarker(
-  project: OnboardingCompletionMarkerState,
-  user: OnboardingCompletionMarkerState,
-): OnboardingCompletionMarkerState | null {
-  if (project.payload) return project;
+  user: OnboardingCheckMarkerState,
+): OnboardingCheckMarkerState | null {
   if (user.payload) return user;
-  if (project.exists) return project;
   if (user.exists) return user;
   return null;
 }
 
-export function getOnboardingCompletionMarkerPath(
+export function getOnboardingCheckMarkerPath(
   shellPaths: OnboardingShellPaths,
-  scope: OnboardingCompletionMarkerScope = 'user',
+  scope: OnboardingStateScope = 'user',
 ): string {
   return resolveMarkerPath(shellPaths, scope);
 }
 
-export function readOnboardingCompletionMarker(
+export function readOnboardingCheckMarker(
   shellPaths: OnboardingShellPaths,
-  scope: OnboardingCompletionMarkerScope = 'user',
-): OnboardingCompletionMarkerState {
+  scope: OnboardingStateScope = 'user',
+): OnboardingCheckMarkerState {
   const path = resolveMarkerPath(shellPaths, scope);
   if (!existsSync(path)) return buildMissingMarkerState(scope, path);
 
   try {
     const parsed = JSON.parse(readFileSync(path, 'utf-8')) as unknown;
-    if (!isCompletionMarkerPayload(parsed)) {
-      return buildParseErrorState(scope, path, 'Invalid onboarding completion marker payload.');
+    if (!isCheckMarkerPayload(parsed)) {
+      return buildParseErrorState(scope, path, 'Invalid onboarding check marker payload.');
     }
 
     return {
@@ -114,48 +111,37 @@ export function readOnboardingCompletionMarker(
   }
 }
 
-export function readOnboardingCompletionMarkers(
+export function readOnboardingCheckMarkers(
   shellPaths: OnboardingShellPaths,
-): OnboardingCompletionMarkersState {
-  const user = readOnboardingCompletionMarker(shellPaths, 'user');
-  const project = readOnboardingCompletionMarker(shellPaths, 'project');
+): OnboardingCheckMarkersState {
+  const user = readOnboardingCheckMarker(shellPaths, 'user');
+  const project = readOnboardingCheckMarker(shellPaths, 'project');
 
   return {
     user,
     project,
-    effective: pickEffectiveMarker(project, user),
+    effective: pickEffectiveMarker(user),
   };
 }
 
-export function writeOnboardingCompletionMarker(
+export function writeOnboardingCheckMarker(
   shellPaths: OnboardingShellPaths,
-  options: WriteOnboardingCompletionMarkerOptions = {},
-): OnboardingCompletionMarkerState {
+  options: WriteOnboardingCheckMarkerOptions = {},
+): OnboardingCheckMarkerState {
   const scope = options.scope ?? 'user';
   const path = resolveMarkerPath(shellPaths, scope);
-  const completedAt = options.completedAt ?? Date.now();
-  const payload: OnboardingCompletionMarkerPayload = {
+  const checkedAt = options.checkedAt ?? Date.now();
+  const payload: OnboardingCheckMarkerPayload = {
     version: 1,
-    completedAt,
-    updatedAt: options.updatedAt ?? completedAt,
+    checkedAt,
+    updatedAt: options.updatedAt ?? checkedAt,
     source: options.source ?? 'wizard',
     ...(options.mode ? { mode: options.mode } : {}),
-    ...(options.workspaceRoot ?? shellPaths.workingDirectory
-      ? { workspaceRoot: options.workspaceRoot ?? shellPaths.workingDirectory }
-      : {}),
+    ...(options.workspaceRoot ? { workspaceRoot: options.workspaceRoot } : {}),
   };
 
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
 
-  return readOnboardingCompletionMarker(shellPaths, scope);
-}
-
-export function clearOnboardingCompletionMarker(
-  shellPaths: OnboardingShellPaths,
-  scope: OnboardingCompletionMarkerScope = 'user',
-): OnboardingCompletionMarkerState {
-  const path = resolveMarkerPath(shellPaths, scope);
-  if (existsSync(path)) unlinkSync(path);
-  return buildMissingMarkerState(scope, path);
+  return readOnboardingCheckMarker(shellPaths, scope);
 }

package/src/runtime/onboarding/state.ts

@@ -3,15 +3,15 @@ import { dirname } from 'node:path';
 import type {
   OnboardingAcknowledgementRuntimeState,
   OnboardingAcknowledgementTarget,
-  OnboardingCompletionMarkerScope,
   OnboardingMode,
   OnboardingShellPaths,
+  OnboardingStateScope,
 } from './types.ts';
 
 const ONBOARDING_RUNTIME_STATE_FILE = 'onboarding-state.json';
 
 export interface OnboardingRuntimeStateRecord {
-  readonly scope: OnboardingCompletionMarkerScope;
+  readonly scope: OnboardingStateScope;
   readonly path: string;
   readonly exists: boolean;
   readonly payload: OnboardingAcknowledgementRuntimeState | null;
@@ -19,7 +19,7 @@ export interface OnboardingRuntimeStateRecord {
 }
 
 interface WriteOnboardingAcknowledgementStateOptions {
-  readonly scope?: OnboardingCompletionMarkerScope;
+  readonly scope?: OnboardingStateScope;
   readonly target: OnboardingAcknowledgementTarget;
   readonly acknowledged: boolean;
   readonly updatedAt?: number;
@@ -30,7 +30,7 @@ interface WriteOnboardingAcknowledgementStateOptions {
 
 function resolveStatePath(
   shellPaths: OnboardingShellPaths,
-  scope: OnboardingCompletionMarkerScope,
+  scope: OnboardingStateScope,
 ): string {
   return scope === 'project'
     ? shellPaths.resolveProjectPath('tui', ONBOARDING_RUNTIME_STATE_FILE)
@@ -63,14 +63,14 @@ function isRuntimeStatePayload(value: unknown): value is OnboardingAcknowledgeme
 
 export function getOnboardingRuntimeStatePath(
   shellPaths: OnboardingShellPaths,
-  scope: OnboardingCompletionMarkerScope = 'project',
+  scope: OnboardingStateScope = 'project',
 ): string {
   return resolveStatePath(shellPaths, scope);
 }
 
 export function readOnboardingRuntimeState(
   shellPaths: OnboardingShellPaths,
-  scope: OnboardingCompletionMarkerScope = 'project',
+  scope: OnboardingStateScope = 'project',
 ): OnboardingRuntimeStateRecord {
   const path = resolveStatePath(shellPaths, scope);
   if (!existsSync(path)) {