From 72ea7db7385d149d63faf1bc71a9c9926fa4f2cc Mon Sep 17 00:00:00 2001
From: Sawyer <sawyer@dirtroad.dev>
Date: Tue, 4 Aug 2026 19:46:14 -0700
Subject: [PATCH 1/3] Guide first-run onboarding with numbered step copy

Show step N of M, field-specific guidance, and a post-setup hint so new
installs are less guesswork during provider setup.

Closes CL-5347
---
 src/tui/onboarding.tsx | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/src/tui/onboarding.tsx b/src/tui/onboarding.tsx
index 9e5280e15..e84a60542 100644
--- a/src/tui/onboarding.tsx
+++ b/src/tui/onboarding.tsx
@@ -181,9 +181,24 @@ export function ProviderSetupPanel({ onSubmit, showTelemetryNotice }: ProviderSe
 
       {/* Main content */}
       <Box flexGrow={1} flexDirection="column" paddingX={4} paddingY={2}>
-        <Box marginBottom={2}>
-          <Text color={color("text")}>
-            No inference provider is configured. Add one to get started.
+        <Box marginBottom={1} flexDirection="column">
+          <Text color={color("text")} bold>
+            Welcome — let's connect an inference provider
+          </Text>
+          <Text color={color("muted")}>
+            Step {fieldIndex + 1} of {FIELDS.length}: {FIELD_LABELS[currentField]}
+          </Text>
+        </Box>
+
+        <Box marginBottom={2} flexDirection="column">
+          <Text color={color("dim")}>
+            {currentField === "name" && "1. Name the provider (openai, anthropic, fireworks, ollama, …)"}
+            {currentField === "baseURL" && "2. Paste the API base URL (must include /v1 if required)"}
+            {currentField === "apiKey" && "3. Enter an API key — leave blank for local/keyless providers"}
+            {currentField === "model" && "4. Pick a default model, then Enter to test & save"}
+          </Text>
+          <Text color={color("dim")}>
+            After setup you can switch providers with Ctrl+A or /models.
           </Text>
         </Box>
 

From 8891069d5623d03765db638dc32bb10785529ff2 Mon Sep 17 00:00:00 2001
From: Sawyer <sawyer@dirtroad.dev>
Date: Tue, 4 Aug 2026 20:44:20 -0700
Subject: [PATCH 2/3] Tighten onboarding guidance and fix post-setup shortcuts

Collapse step copy so errors still fit on small terminals, and point
users at /model instead of the incorrect Ctrl+A and /models bindings.
---
 src/tui/onboarding.tsx | 18 +++++++-----------
 1 file changed, 7 insertions(+), 11 deletions(-)

diff --git a/src/tui/onboarding.tsx b/src/tui/onboarding.tsx
index e84a60542..00fbe6a24 100644
--- a/src/tui/onboarding.tsx
+++ b/src/tui/onboarding.tsx
@@ -183,22 +183,18 @@ export function ProviderSetupPanel({ onSubmit, showTelemetryNotice }: ProviderSe
       <Box flexGrow={1} flexDirection="column" paddingX={4} paddingY={2}>
         <Box marginBottom={1} flexDirection="column">
           <Text color={color("text")} bold>
-            Welcome — let's connect an inference provider
+            Welcome — connect an inference provider
           </Text>
           <Text color={color("muted")}>
             Step {fieldIndex + 1} of {FIELDS.length}: {FIELD_LABELS[currentField]}
-          </Text>
-        </Box>
-
-        <Box marginBottom={2} flexDirection="column">
-          <Text color={color("dim")}>
-            {currentField === "name" && "1. Name the provider (openai, anthropic, fireworks, ollama, …)"}
-            {currentField === "baseURL" && "2. Paste the API base URL (must include /v1 if required)"}
-            {currentField === "apiKey" && "3. Enter an API key — leave blank for local/keyless providers"}
-            {currentField === "model" && "4. Pick a default model, then Enter to test & save"}
+            {" — "}
+            {currentField === "name" && "name it (openai, anthropic, ollama, …)"}
+            {currentField === "baseURL" && "paste the API base URL (include /v1 if required)"}
+            {currentField === "apiKey" && "API key (blank for local/keyless)"}
+            {currentField === "model" && "default model, then Enter to test & save"}
           </Text>
           <Text color={color("dim")}>
-            After setup you can switch providers with Ctrl+A or /models.
+            After setup, switch providers with /model
           </Text>
         </Box>
 

From a9ba3e4d2320bad3f2a24d2514f2fd35da24d275 Mon Sep 17 00:00:00 2001
From: Sawyer <sawyer@dirtroad.dev>
Date: Tue, 4 Aug 2026 22:33:55 -0700
Subject: [PATCH 3/3] Align onboarding name examples and cover step copy

Match FIELD_HINTS to the step guidance catalog (openai, anthropic, ollama)
and add a unit test that the provider-setup step banner renders on mount.
---
 src/tui/onboarding.tsx             | 2 +-
 tests/unit/tui/onboarding.test.tsx | 9 +++++++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/src/tui/onboarding.tsx b/src/tui/onboarding.tsx
index 00fbe6a24..32745a4d8 100644
--- a/src/tui/onboarding.tsx
+++ b/src/tui/onboarding.tsx
@@ -30,7 +30,7 @@ const FIELD_LABELS: Record<Field, string> = {
 };
 
 const FIELD_HINTS: Record<Field, string> = {
-  name: "openai, anthropic, fireworks, ...",
+  name: "openai, anthropic, ollama, ...",
   baseURL: "https://api.openai.com/v1",
   apiKey: "sk-... (blank for keyless/local)",
   model: "gpt-4o",
diff --git a/tests/unit/tui/onboarding.test.tsx b/tests/unit/tui/onboarding.test.tsx
index 3ddf340ff..843491591 100644
--- a/tests/unit/tui/onboarding.test.tsx
+++ b/tests/unit/tui/onboarding.test.tsx
@@ -49,6 +49,15 @@ test("shows Provider name label on mount", () => {
   expect(lastFrame()).toContain("Provider name");
 });
 
+test("shows welcome and step copy on mount", () => {
+  const { lastFrame } = renderPanel();
+  const frame = lastFrame() ?? "";
+  // Fixed-height panel (rows fallback 24) can flex-shrink the bold welcome
+  // line under ink-testing-library; assert the step banner that always shows.
+  expect(frame).toContain("Provider setup");
+  expect(frame).toContain("Step 1 of 4");
+});
+
 test("shows all field labels", () => {
   const { lastFrame } = renderPanel();
   expect(lastFrame()).toContain("Provider name");