Restore first-run welcome before provider setup

Unconfigured launches jumped straight into model setup and skipped the
orange mountain plus product line. Gate setup on settings.onboarded,
show the welcome surface first, and stamp onboarded only after it
completes so returning users still open setup directly.

Author: TheGreatAxios

CHANGELOG.md

@@ -13,6 +13,11 @@ parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
 
 ## [Unreleased]
 
+### Fixed
+
+- First-run onboarding shows the welcome mountain and product line before
+  provider setup again; already-onboarded users still open setup directly.
+
 ## [0.3.8] - 2026-08-28
 
 ### TUI

docs/IMPLEMENTATION.md

@@ -125,7 +125,7 @@ src/
     lsp-hint-plugin.ts         TS/JS LSP setup hint on unavailable server
   tui/
     runner.ts             Chat-mode agent setup; mounts the OpenTUI host
-    onboarding.ts         First-run provider setup entry
+    onboarding.ts         First-run welcome gate, then provider setup
     pick-session.ts       Resume picker (via runListModal)
     turns-to-blocks.ts    Stored turns → typed content blocks (resume hydration)
     tool-formatter.ts     Human-readable tool args/results

src/tui/onboarding.test.ts

@@ -5,21 +5,35 @@ import { join } from "node:path";
 
 import type { Config, UnconfiguredConfig } from "../config/index.js";
 import type { ProviderSetupConfig } from "./provider-setup.js";
+import type { WelcomeConfig } from "./welcome.js";
 import { withMockedModule } from "../../tests/helpers/mock-module.js";
 
 let testHome = "";
 let setup: (config: ProviderSetupConfig) => Promise<void> = async () => {};
+let welcome: (config: WelcomeConfig) => Promise<boolean> = async () => true;
 let tuiConfig: Config | undefined;
+const callOrder: string[] = [];
 
 await withMockedModule(import.meta.resolve("node:os"), (real: typeof import("node:os")) => ({
   ...real,
   homedir: () => testHome,
 }));
+await withMockedModule(
+  import.meta.resolve("./welcome.js"),
+  (real: typeof import("./welcome.js")) => ({
+    ...real,
+    runWelcome: async (config: WelcomeConfig = {}) => {
+      callOrder.push("welcome");
+      return welcome(config);
+    },
+  }),
+);
 await withMockedModule(
   import.meta.resolve("./provider-setup.js"),
   (real: typeof import("./provider-setup.js")) => ({
     ...real,
     runProviderSetup: async (config: ProviderSetupConfig) => {
+      callOrder.push("setup");
       await setup(config);
       return true;
     },
@@ -78,7 +92,102 @@ async function writeXAIAuthProfile(home: string, profile: string): Promise<void>
 
 afterEach(() => {
   setup = async () => {};
+  welcome = async () => true;
   tuiConfig = undefined;
+  callOrder.length = 0;
+});
+
+describe("runOnboarding welcome gate", () => {
+  test("fresh user sees welcome before provider setup and marks onboarded", async () => {
+    testHome = await mkdtemp(join(tmpdir(), "corbits-onboarding-welcome-home-"));
+    const cwd = await mkdtemp(join(tmpdir(), "corbits-onboarding-welcome-cwd-"));
+    const configPath = join(testHome, ".corbits", "settings.json");
+    try {
+      await mkdir(join(testHome, ".corbits"), { recursive: true });
+      await writeFile(configPath, JSON.stringify({ providers: {} }));
+      const config = await unconfiguredConfig(cwd, { programmaticConfigPath: configPath });
+
+      setup = async ({ onSubmit }) => {
+        await onSubmit(
+          {
+            name: "custom",
+            baseURL: "https://provider.example.com/v1",
+            apiKey: "test-key",
+            model: "test-model",
+            oauthProfile: "",
+          },
+          () => {},
+          { skipValidation: true },
+        );
+      };
+
+      expect(await runOnboarding(config)).toBe(0);
+      expect(callOrder).toEqual(["welcome", "setup"]);
+
+      const persisted = JSON.parse(await readFile(configPath, "utf8")) as {
+        onboarded?: boolean;
+      };
+      expect(persisted.onboarded).toBe(true);
+    } finally {
+      await rm(testHome, { recursive: true, force: true });
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+
+  test("already-onboarded skips welcome and opens setup directly", async () => {
+    testHome = await mkdtemp(join(tmpdir(), "corbits-onboarding-skip-home-"));
+    const cwd = await mkdtemp(join(tmpdir(), "corbits-onboarding-skip-cwd-"));
+    const configPath = join(testHome, ".corbits", "settings.json");
+    try {
+      await mkdir(join(testHome, ".corbits"), { recursive: true });
+      await writeFile(configPath, JSON.stringify({ providers: {}, onboarded: true }));
+      const config = await unconfiguredConfig(cwd, { programmaticConfigPath: configPath });
+
+      setup = async ({ onSubmit }) => {
+        await onSubmit(
+          {
+            name: "custom",
+            baseURL: "https://provider.example.com/v1",
+            apiKey: "test-key",
+            model: "test-model",
+            oauthProfile: "",
+          },
+          () => {},
+          { skipValidation: true },
+        );
+      };
+
+      expect(await runOnboarding(config)).toBe(0);
+      expect(callOrder).toEqual(["setup"]);
+    } finally {
+      await rm(testHome, { recursive: true, force: true });
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+
+  test("cancelled welcome does not mark onboarded or open setup", async () => {
+    testHome = await mkdtemp(join(tmpdir(), "corbits-onboarding-cancel-home-"));
+    const cwd = await mkdtemp(join(tmpdir(), "corbits-onboarding-cancel-cwd-"));
+    const configPath = join(testHome, ".corbits", "settings.json");
+    try {
+      await mkdir(join(testHome, ".corbits"), { recursive: true });
+      await writeFile(configPath, JSON.stringify({ providers: {} }));
+      const config = await unconfiguredConfig(cwd, { programmaticConfigPath: configPath });
+
+      welcome = async () => false;
+
+      expect(await runOnboarding(config)).toBe(1);
+      expect(callOrder).toEqual(["welcome"]);
+
+      const persisted = JSON.parse(await readFile(configPath, "utf8")) as {
+        onboarded?: boolean;
+      };
+      expect(persisted.onboarded).toBeUndefined();
+    } finally {
+      await rm(testHome, { recursive: true, force: true });
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
 });
 
 describe("runOnboarding settings source", () => {

src/tui/onboarding.ts

@@ -1,22 +1,43 @@
 import { runTUI } from "./runner.js";
 import { buildProviderSubmitHandler } from "./provider-setup-submit.js";
 import { loadConfig, type UnconfiguredConfig } from "../config/index.js";
-import { globalSettingsPath, loadSettings, resolveLocalSettingsPath } from "../config/settings.js";
+import {
+  globalSettingsPath,
+  loadSettings,
+  markOnboarded,
+  resolveLocalSettingsPath,
+} from "../config/settings.js";
 import { activateHeldTelemetry, telemetryFirstRunPending } from "../telemetry/first-run.js";
 import { runProviderSetup } from "./provider-setup.js";
+import { runWelcome } from "./welcome.js";
 
 export async function runOnboarding(config: UnconfiguredConfig): Promise<number> {
   const settingsPath = config.globalSettingsPath;
-  const existing = await loadSettings(settingsPath);
 
   // Disclosure before any send: startup held telemetry because the notice
   // has never been shown, so render it here and treat a completed submit as
   // the affirmative action that activates telemetry (consent by proceeding).
   // Read from the TRUE global settings file — telemetry state never lives in
   // a --config override file.
-  const trueGlobalSettings = await loadSettings(globalSettingsPath()).catch(() => null);
+  const trueGlobalPath = globalSettingsPath();
+  const trueGlobalSettings = await loadSettings(trueGlobalPath).catch(() => null);
   const showTelemetryNotice = telemetryFirstRunPending(trueGlobalSettings);
 
+  // Welcome is global first-run state (same TRUE global file as telemetry /
+  // onboarded), independent of --config provider write targets. Already-
+  // onboarded users who wiped providers jump straight to setup.
+  if (trueGlobalSettings?.onboarded !== true) {
+    const welcomed = await runWelcome();
+    if (!welcomed) {
+      return 1;
+    }
+    await markOnboarded(trueGlobalPath);
+  }
+
+  // Load the provider write-target after welcome so a same-path markOnboarded
+  // is preserved when setup merges the new provider into existing settings.
+  const existing = await loadSettings(settingsPath);
+
   const submitted = await runProviderSetup({
     showTelemetryNotice,
     existingProviderNames: Object.keys(existing?.providers ?? {}),
@@ -37,7 +58,7 @@ export async function runOnboarding(config: UnconfiguredConfig): Promise<number>
   // Completing setup with the disclosure on screen is the affirmative action
   // that unlocks telemetry and fires the held cli_start.
   if (showTelemetryNotice) {
-    await activateHeldTelemetry(globalSettingsPath());
+    await activateHeldTelemetry(trueGlobalPath);
   }
 
   const argv: string[] = ["--cwd", config.cwd];

src/tui/welcome.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from "bun:test";
+
+import { PRODUCT_NAME } from "../branding.js";
+import { MARK_LARGE, MARK_MID, MARK_SMALL } from "./mark-shape.js";
+import { createHarness } from "./harness.js";
+import { resolveWelcomeMarkGrid, runWelcome, WELCOME_LINE } from "./welcome.js";
+
+describe("WELCOME_LINE", () => {
+  test("names the product as the local software factory", () => {
+    expect(WELCOME_LINE).toBe(`${PRODUCT_NAME}, your local software factory`);
+    expect(WELCOME_LINE).toContain("Corbits Code, your local software factory");
+  });
+});
+
+describe("resolveWelcomeMarkGrid", () => {
+  test("picks the largest mark that fits the terminal", () => {
+    expect(resolveWelcomeMarkGrid(24, 80)).toBe(MARK_LARGE);
+    expect(resolveWelcomeMarkGrid(14, 80)).toBe(MARK_MID);
+    expect(resolveWelcomeMarkGrid(10, 40)).toBe(MARK_SMALL);
+    expect(resolveWelcomeMarkGrid(4, 80)).toBeNull();
+  });
+});
+
+describe("runWelcome", () => {
+  test("paints the product line and continues on keypress", async () => {
+    const harness = await createHarness({ width: 80, height: 30 });
+    const done = runWelcome({
+      createRenderer: async () => harness.renderer,
+      autoAdvanceMs: 60_000,
+      now: () => 2_000,
+    });
+    try {
+      await harness.renderOnce();
+      await harness.renderOnce();
+      expect(harness.captureCharFrame()).toContain(WELCOME_LINE);
+
+      harness.pressKey("Enter");
+      await expect(done).resolves.toBe(true);
+    } finally {
+      // If the assertion failed before Enter, cancel so timers cannot leak.
+      harness.pressKey("Ctrl+C");
+      await Promise.race([done, new Promise((r) => setTimeout(r, 50))]);
+      harness.destroy();
+    }
+  });
+
+  test("cancels on Ctrl+C without continuing", async () => {
+    const harness = await createHarness({ width: 80, height: 30 });
+    const done = runWelcome({
+      createRenderer: async () => harness.renderer,
+      autoAdvanceMs: 60_000,
+      now: () => 2_000,
+    });
+    try {
+      await harness.renderOnce();
+      harness.pressKey("Ctrl+C");
+      await expect(done).resolves.toBe(false);
+    } finally {
+      harness.destroy();
+    }
+  });
+
+  test("auto-advances when the timer fires", async () => {
+    const harness = await createHarness({ width: 80, height: 30 });
+    const done = runWelcome({
+      createRenderer: async () => harness.renderer,
+      autoAdvanceMs: 20,
+      now: () => 2_000,
+    });
+    try {
+      await expect(done).resolves.toBe(true);
+    } finally {
+      harness.destroy();
+    }
+  });
+});