feat(cli): setup progress spinners, Tab-to-select, and banner polish (#296)

* fix(cli): double the height of the setup banner t crossbar

* fix(cli): unify setup multi-select hints and make Tab the select key

The six interactive multi-select surfaces in `ktx setup` documented three
different hint voices, one had no hint at all, and they named two different
select keys (Space vs Tab). Tab is the only key that can toggle selection
without colliding with type-to-search input, so make it the single documented
select key everywhere and compose every hint from one shared fragment
vocabulary in prompt-navigation.ts.

- Register `updateSettings({ aliases: { tab: 'space' } })` so Tab toggles flat
  multiselects; the alias applies only to non-text prompts, leaving typed
  search input (schema/Notion) untouched.
- Add the missing hint to the agent-targets prompt and drop the stray
  "Space to select … Esc …" info line plus the now-dead writeSetupInfo helper.
- Replace the schema-scope ad-hoc hint with the searchable-multiselect voice
  and standardize "filter" -> "search" vocabulary.
- Delete DEFAULT_TREE_PICKER_HELP_TEXT and the unused TreePickerChrome.helpText
  seam; render the shared tree hint instead.

* refactor(cli): show LLM check progress for every setup backend

Rename runLlmHealthCheckWithProgress to validateModelWithProgress and
wrap the Claude subscription and Codex auth probes in the same spinner
progress as the Anthropic API and Vertex backends, so each backend shows
consistent "Checking <provider> LLM" output during setup.

* feat(cli): add ktx-orange progress spinners to setup steps

Add a shared runWithCliSpinner helper and a TTY-aware createCliSpinner:
an animated clack spinner in a terminal, and a static stderr-only spinner
before raw-mode pickers (the table tree picker and demo tour), where the
animated spinner's stdin grab would otherwise corrupt the next prompt.

Wrap the slow setup waits in progress spinners: managed runtime install,
embedding daemon start + first-run model download, embeddings health
check, the connection-test gate, and source validation / dbt clone /
Metabase discovery. Recolor every spinner frame from clack's magenta to
the ktx mascot orange (#FF8A4C) via the static helper and clack's
styleFrame option.

packages/cli/test/clack.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { type KtxCliSpinner, runWithCliSpinner } from '../src/clack.js';
+
+function makeSpinner() {
+  const events: string[] = [];
+  const spinner: KtxCliSpinner = {
+    start: (msg) => events.push(`start:${msg}`),
+    message: (msg) => events.push(`message:${msg}`),
+    stop: (msg) => events.push(`stop:${msg}`),
+    error: (msg) => events.push(`error:${msg}`),
+  };
+  return { events, spinner };
+}
+
+describe('runWithCliSpinner', () => {
+  it('starts then stops with the success text and returns the value', async () => {
+    const { events, spinner } = makeSpinner();
+
+    const value = await runWithCliSpinner(spinner, { start: 'Working…', success: 'Done', failure: 'Failed' }, async () => 42);
+
+    expect(value).toBe(42);
+    expect(events).toEqual(['start:Working…', 'stop:Done']);
+  });
+
+  it('errors with the failure text and rethrows when the work throws', async () => {
+    const { events, spinner } = makeSpinner();
+    const boom = new Error('boom');
+
+    await expect(
+      runWithCliSpinner(spinner, { start: 'Working…', success: 'Done', failure: 'Failed' }, async () => {
+        throw boom;
+      }),
+    ).rejects.toBe(boom);
+    expect(events).toEqual(['start:Working…', 'error:Failed']);
+  });
+});

packages/cli/test/prompt-navigation.test.ts

@@ -1,5 +1,14 @@
 import { describe, expect, it } from 'vitest';
-import { withMenuOptionSpacing, withMultiselectNavigation, withTextInputNavigation } from '../src/prompt-navigation.js';
+import {
+  FLAT_MULTISELECT_NAVIGATION_HINT,
+  MULTISELECT_NAVIGATION_FRAGMENTS,
+  SEARCHABLE_MULTISELECT_NAVIGATION_HINT,
+  TREE_PICKER_NAVIGATION_HINT,
+  withMenuOptionSpacing,
+  withMultiselectNavigation,
+  withSearchableMultiselectNavigation,
+  withTextInputNavigation,
+} from '../src/prompt-navigation.js';
 
 describe('prompt navigation helpers', () => {
   it('leaves compact single-line menu prompts unchanged', () => {
@@ -18,10 +27,56 @@ describe('prompt navigation helpers', () => {
 
   it('keeps multiselect navigation copy multiline so menu renderers can separate it from options', () => {
     expect(withMultiselectNavigation('Which sources?')).toBe(
-      'Which sources?\nUse Up/Down to move, Space to select or unselect, Enter to confirm, Escape to go back, or Ctrl+C to exit.',
+      'Which sources?\nUp/Down to move, Tab to select or unselect, Enter to confirm, Escape to go back, Ctrl+C to exit.',
     );
   });
 
+  it('appends the searchable hint for autocomplete multiselect prompts', () => {
+    expect(withSearchableMultiselectNavigation('Choose schemas')).toBe(
+      'Choose schemas\nUp/Down to move, Tab to select or unselect, Type to search, Enter to confirm, Escape to go back, Ctrl+C to exit.',
+    );
+  });
+
+  it('does not duplicate the searchable hint when applied twice', () => {
+    const once = withSearchableMultiselectNavigation('Choose schemas');
+    expect(withSearchableMultiselectNavigation(once)).toBe(once);
+  });
+
+  it('matches the approved hint wording for each multi-select surface', () => {
+    expect(FLAT_MULTISELECT_NAVIGATION_HINT).toBe(
+      'Up/Down to move, Tab to select or unselect, Enter to confirm, Escape to go back, Ctrl+C to exit.',
+    );
+    expect(SEARCHABLE_MULTISELECT_NAVIGATION_HINT).toBe(
+      'Up/Down to move, Tab to select or unselect, Type to search, Enter to confirm, Escape to go back, Ctrl+C to exit.',
+    );
+    expect(TREE_PICKER_NAVIGATION_HINT).toBe(
+      'Up/Down to move, Right/Left to expand or collapse, Tab to select or unselect, Type to search, Enter to confirm, Escape to clear search or go back, Ctrl+C to exit.',
+    );
+  });
+
+  it('composes every hint from the shared fragment vocabulary so wording cannot drift', () => {
+    const hints = [
+      FLAT_MULTISELECT_NAVIGATION_HINT,
+      SEARCHABLE_MULTISELECT_NAVIGATION_HINT,
+      TREE_PICKER_NAVIGATION_HINT,
+    ];
+    const sharedFragments = [
+      MULTISELECT_NAVIGATION_FRAGMENTS.move,
+      MULTISELECT_NAVIGATION_FRAGMENTS.select,
+      MULTISELECT_NAVIGATION_FRAGMENTS.confirm,
+      MULTISELECT_NAVIGATION_FRAGMENTS.exit,
+    ];
+    for (const fragment of sharedFragments) {
+      for (const hint of hints) {
+        expect(hint).toContain(fragment);
+      }
+    }
+    expect(MULTISELECT_NAVIGATION_FRAGMENTS.select).toBe('Tab to select or unselect');
+    for (const hint of hints) {
+      expect(hint).not.toContain('Space');
+    }
+  });
+
   it('adds a blank separator between text input helper copy and the editable value', () => {
     expect(
       withTextInputNavigation(

packages/cli/test/setup-agents.test.ts

@@ -998,7 +998,7 @@ describe('setup agents', () => {
     ).resolves.toEqual({ status: 'skipped', projectDir: tempDir });
   });
 
-  it('prints one navigation hint before interactive agent target prompts', async () => {
+  it('wraps the agent target prompt with the navigation hint and prints no separate hint line', async () => {
     const io = makeIo();
     const prompts = {
       select: vi.fn(async () => 'mcp-cli'),
@@ -1022,13 +1022,14 @@ describe('setup agents', () => {
       ),
     ).resolves.toEqual({ status: 'back', projectDir: tempDir });
 
-    expect(io.stdout()).toContain('Space to select, Enter to confirm, Esc to go back.');
-    expect(io.stdout().match(/Space to select/g)).toHaveLength(1);
     expect(prompts.multiselect).toHaveBeenCalledWith(
       expect.objectContaining({
-        message: 'Which agent targets should ktx install?',
+        message:
+          'Which agent targets should ktx install?\n' +
+          'Up/Down to move, Tab to select or unselect, Enter to confirm, Escape to go back, Ctrl+C to exit.',
       }),
     );
+    expect(io.stdout()).not.toContain('Space to select');
   });
 
   it('prints per-agent install summary after successful installation', async () => {

packages/cli/test/setup-databases.test.ts

@@ -235,7 +235,7 @@ describe('setup databases step', () => {
     expect(prompts.multiselect).toHaveBeenCalledWith({
       message:
         'Which databases should ktx connect to?\n' +
-        'Use Up/Down to move, Space to select or unselect, Enter to confirm, Escape to go back, or Ctrl+C to exit.',
+        'Up/Down to move, Tab to select or unselect, Enter to confirm, Escape to go back, Ctrl+C to exit.',
       options: [
         { value: 'postgres', label: 'PostgreSQL' },
         { value: 'bigquery', label: 'BigQuery' },
@@ -273,7 +273,7 @@ describe('setup databases step', () => {
     expect(prompts.multiselect).toHaveBeenCalledTimes(2);
     expect(vi.mocked(prompts.multiselect).mock.calls[1]?.[0].message).toBe(
       'Which databases should ktx connect to?\n' +
-        'Use Up/Down to move, Space to select or unselect, Enter to confirm, Escape to go back, or Ctrl+C to exit.',
+        'Up/Down to move, Tab to select or unselect, Enter to confirm, Escape to go back, Ctrl+C to exit.',
     );
   });
 

packages/cli/test/setup-embeddings.test.ts

@@ -21,7 +21,7 @@ function makeIo() {
   return {
     io: {
       stdout: {
-        isTTY: true,
+        isTTY: false,
         write: (chunk: string) => {
           stdout += chunk;
         },
@@ -185,7 +185,7 @@ describe('setup embeddings step', () => {
     expect(io.stdout()).toContain('Embeddings ready: yes');
   });
 
-  it('uses a short non-animated local embeddings health-check status by default', async () => {
+  it('uses a short non-animated local embeddings health-check status when stdout is not a TTY', async () => {
     const io = makeIo();
     const healthCheck = vi.fn(async () => ({ ok: true as const }));
     const prompts = makePromptAdapter({ selectValues: ['sentence-transformers'] });

packages/cli/test/setup-models.test.ts

@@ -161,6 +161,7 @@ describe('setup Anthropic model step', () => {
   it('configures Claude Code backend and validates local auth', async () => {
     const io = makeIo();
     const authProbe = vi.fn(async () => ({ ok: true as const }));
+    const { events: spinnerEvents, spinner } = makeSpinnerEvents();
 
     const result = await runKtxSetupAnthropicModelStep(
       {
@@ -170,7 +171,7 @@ describe('setup Anthropic model step', () => {
         skipLlm: false,
       },
       io.io,
-      { claudeCodeAuthProbe: authProbe },
+      { claudeCodeAuthProbe: authProbe, spinner },
     );
 
     expect(result.status).toBe('ready');
@@ -183,17 +184,26 @@ describe('setup Anthropic model step', () => {
     expect(authProbe).toHaveBeenNthCalledWith(1, expect.objectContaining({ projectDir: tempDir, model: 'sonnet' }));
     expect(authProbe).toHaveBeenNthCalledWith(2, expect.objectContaining({ projectDir: tempDir, model: 'haiku' }));
     expect(authProbe).toHaveBeenNthCalledWith(3, expect.objectContaining({ projectDir: tempDir, model: 'opus' }));
+    expect(spinnerEvents).toEqual([
+      'start:Checking Claude subscription LLM (sonnet).',
+      'stop:LLM test passed (Claude subscription, sonnet)',
+      'start:Checking Claude subscription LLM (haiku).',
+      'stop:LLM test passed (Claude subscription, haiku)',
+      'start:Checking Claude subscription LLM (opus).',
+      'stop:LLM test passed (Claude subscription, opus)',
+    ]);
   });
 
   it('does not prompt for a Claude Code model during interactive setup', async () => {
     const io = makeIo();
     const prompts = makePromptAdapter({ selectValues: ['claude-code'] });
     const authProbe = vi.fn(async () => ({ ok: true as const }));
+    const { spinner } = makeSpinnerEvents();
 
     const result = await runKtxSetupAnthropicModelStep(
       { projectDir: tempDir, inputMode: 'auto', skipLlm: false },
       io.io,
-      { prompts, claudeCodeAuthProbe: authProbe },
+      { prompts, claudeCodeAuthProbe: authProbe, spinner },
     );
 
     expect(result.status).toBe('ready');
@@ -214,6 +224,7 @@ describe('setup Anthropic model step', () => {
   it('configures Codex backend and validates local auth', async () => {
     const io = makeIo();
     const codexAuthProbe = vi.fn(async () => ({ ok: true as const }));
+    const { events: spinnerEvents, spinner } = makeSpinnerEvents();
 
     const result = await runKtxSetupAnthropicModelStep(
       {
@@ -223,7 +234,7 @@ describe('setup Anthropic model step', () => {
         skipLlm: false,
       },
       io.io,
-      { codexAuthProbe },
+      { codexAuthProbe, spinner },
     );
 
     expect(result.status).toBe('ready');
@@ -234,6 +245,10 @@ describe('setup Anthropic model step', () => {
     });
     expect(codexAuthProbe).toHaveBeenCalledTimes(1);
     expect(codexAuthProbe).toHaveBeenCalledWith(expect.objectContaining({ projectDir: tempDir, model: 'gpt-5.5' }));
+    expect(spinnerEvents).toEqual([
+      'start:Checking Codex LLM (gpt-5.5).',
+      'stop:LLM test passed (Codex, gpt-5.5)',
+    ]);
     // The warning carries the clack gutter so it renders inside the setup frame.
     expect(io.stderr()).toContain('│  Codex backend isolation is limited');
     expect(io.stderr()).toContain('may still load user Codex config');
@@ -242,6 +257,7 @@ describe('setup Anthropic model step', () => {
   it('defaults the Codex model to gpt-5.5 when none is provided non-interactively', async () => {
     const io = makeIo();
     const codexAuthProbe = vi.fn(async () => ({ ok: true as const }));
+    const { spinner } = makeSpinnerEvents();
 
     const result = await runKtxSetupAnthropicModelStep(
       {
@@ -251,7 +267,7 @@ describe('setup Anthropic model step', () => {
         skipLlm: false,
       },
       io.io,
-      { codexAuthProbe },
+      { codexAuthProbe, spinner },
     );
 
     expect(result.status).toBe('ready');
@@ -283,6 +299,7 @@ describe('setup Anthropic model step', () => {
       'utf-8',
     );
     const io = makeIo();
+    const { spinner } = makeSpinnerEvents();
 
     const result = await runKtxSetupAnthropicModelStep(
       {
@@ -294,6 +311,7 @@ describe('setup Anthropic model step', () => {
       io.io,
       {
         claudeCodeAuthProbe: async () => ({ ok: true as const }),
+        spinner,
       },
     );
 

packages/cli/test/setup-prompts-tab-toggle.test.ts

@@ -0,0 +1,44 @@
+import { PassThrough } from 'node:stream';
+import { multiselect } from '@clack/prompts';
+import { describe, expect, it } from 'vitest';
+// Importing the adapter module registers the tab→space alias on clack settings.
+import '../src/setup-prompts.js';
+
+type FakeInput = PassThrough & { isTTY: boolean; setRawMode: (value: boolean) => void };
+type FakeOutput = PassThrough & { isTTY: boolean; columns: number; rows: number };
+
+function fakeTty(): { input: FakeInput; output: FakeOutput } {
+  const input = new PassThrough() as FakeInput;
+  input.isTTY = true;
+  input.setRawMode = () => {};
+  const output = new PassThrough() as FakeOutput;
+  output.isTTY = true;
+  output.columns = 80;
+  output.rows = 24;
+  output.resume();
+  return { input, output };
+}
+
+const tick = (): Promise<void> => new Promise((resolve) => setImmediate(resolve));
+
+describe('Tab selection in a flat multiselect', () => {
+  it('toggles the focused option, proving the adapter alias drives a real clack multiselect', async () => {
+    const { input, output } = fakeTty();
+    const result = multiselect({
+      message: 'Pick',
+      options: [
+        { value: 'a', label: 'A' },
+        { value: 'b', label: 'B' },
+      ],
+      input,
+      output,
+    });
+
+    await tick();
+    input.emit('keypress', '\t', { name: 'tab' });
+    await tick();
+    input.emit('keypress', '', { name: 'return' });
+
+    expect(await result).toEqual(['a']);
+  });
+});

packages/cli/test/setup-prompts.test.ts

@@ -1,3 +1,4 @@
+import { settings } from '@clack/core';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import {
   createKtxSetupPromptAdapter,
@@ -63,6 +64,13 @@ describe('setup prompt adapter', () => {
     mocks.withSetupInterruptConfirmation.mockClear();
   });
 
+  it('registers Tab as a Space alias so flat multiselects toggle on Tab', () => {
+    // Importing the adapter module runs updateSettings({ aliases: { tab: 'space' } }).
+    // clack remaps Tab→Space on non-text prompts, which is what toggles a flat
+    // multiselect option; text inputs set _track, so their typed Tab is untouched.
+    expect(settings.aliases.get('tab')).toBe('space');
+  });
+
   it('passes select hint and disabled options through Clack and delegates cancellation handling', async () => {
     mocks.select.mockResolvedValueOnce('openai');
     const adapter = createKtxSetupPromptAdapter({ selectCancelValue: 'back' });

packages/cli/test/setup-sources.test.ts

@@ -761,7 +761,7 @@ describe('setup sources step', () => {
     expect(testPrompts.multiselect).toHaveBeenCalledWith(
       expect.objectContaining({
         message:
-          'Which context sources should ktx ingest?\nUse Up/Down to move, Space to select or unselect, Enter to confirm, Escape to go back, or Ctrl+C to exit.',
+          'Which context sources should ktx ingest?\nUp/Down to move, Tab to select or unselect, Enter to confirm, Escape to go back, Ctrl+C to exit.',
       }),
     );
     const options = vi.mocked(testPrompts.multiselect).mock.calls[0]?.[0].options ?? [];

packages/cli/test/tree-picker-tui.test.tsx

@@ -193,24 +193,11 @@ describe('TreePickerApp', () => {
     expect(frame).toContain('◻ Engineering Docs ▸ (1)');
     expect(frame).toContain('◻ Marketing');
     expect(normalizeFrameWrap(frame)).toContain(
-      'Up/Down to move, Right/Left to expand or collapse, Tab to select, Type to search, Enter to confirm, Escape to clear search or go back, Ctrl+C to exit.',
+      'Up/Down to move, Right/Left to expand or collapse, Tab to select or unselect, Type to search, Enter to confirm, Escape to clear search or go back, Ctrl+C to exit.',
     );
     expect(frame).toContain('Search:');
   });
 
-  it('renders custom help text when supplied', () => {
-    const { lastFrame } = renderInkTest(
-      <TreePickerApp
-        initialState={state()}
-        chrome={chrome({ helpText: 'Bespoke instructions here.' })}
-        terminalRows={24}
-        terminalWidth={100}
-        onExit={vi.fn()}
-      />,
-    );
-    expect(lastFrame() ?? '').toContain('Bespoke instructions here.');
-  });
-
   it('renders checked parents and locked descendants with locked glyphs', () => {
     const initialState = {
       ...state(),