@kaelio/ktx 0.10.0 → 0.12.0

package/dist/setup-interrupt.js

@@ -2,7 +2,7 @@ import { stdin } from 'node:process';
 import { cancel, confirm, isCancel as isClackCancel } from '@clack/prompts';
 export class KtxSetupExitError extends Error {
     constructor() {
-        super('KTX setup exit requested');
+        super('ktx setup exit requested');
         this.name = 'KtxSetupExitError';
     }
 }

package/dist/setup-models.d.ts

@@ -32,7 +32,10 @@ export type KtxSetupModelResult = {
     status: 'failed';
     projectDir: string;
 };
-export type KtxSetupLlmBackend = 'anthropic' | 'vertex' | 'claude-code' | 'codex';
+declare const KTX_SETUP_LLM_BACKENDS: readonly ["claude-code", "codex", "anthropic", "vertex"];
+export type KtxSetupLlmBackend = (typeof KTX_SETUP_LLM_BACKENDS)[number];
+/** Validates a raw CLI or prompt value against the setup-selectable LLM backends. */
+export declare function isKtxSetupLlmBackend(value: string): value is KtxSetupLlmBackend;
 /** @internal */
 export interface KtxSetupModelPromptAdapter {
     select(options: {

package/dist/setup-models.js

@@ -21,10 +21,28 @@ const ESC = String.fromCharCode(0x1b);
 function yellow(text) {
     return `${ESC}[33m${text}${ESC}[39m`;
 }
-const ANTHROPIC_CREDENTIAL_PROMPT_CONTEXT = 'KTX uses the key to verify Anthropic model access now and to run ingest agents that turn schemas, SQL, ' +
+// Single source of truth for the LLM backends a user can pick during setup.
+// The CLI arg parser, the interactive prompt, and the missing-backend error all
+// derive from this list, so adding a backend is one edit. Order is the prompt's
+// preference order (subscription backends first).
+const KTX_SETUP_LLM_BACKENDS = ['claude-code', 'codex', 'anthropic', 'vertex'];
+/** Validates a raw CLI or prompt value against the setup-selectable LLM backends. */
+export function isKtxSetupLlmBackend(value) {
+    return KTX_SETUP_LLM_BACKENDS.some((backend) => backend === value);
+}
+// Display labels for the interactive provider prompt. The Record key type forces
+// every backend to carry a label, so adding one to KTX_SETUP_LLM_BACKENDS fails
+// to compile until its prompt option exists here.
+const KTX_SETUP_LLM_BACKEND_LABELS = {
+    'claude-code': 'Claude subscription (Pro/Max)',
+    codex: 'Codex subscription',
+    anthropic: 'Anthropic API key',
+    vertex: 'Google Vertex AI for Anthropic Claude',
+};
+const ANTHROPIC_CREDENTIAL_PROMPT_CONTEXT = 'ktx uses the key to verify Anthropic model access now and to run ingest agents that turn schemas, SQL, ' +
     'BI metadata, and docs into semantic-layer sources and wiki context. ktx.yaml stores an env: or file: ' +
     'reference, not the raw key.';
-const VERTEX_PROJECT_PROMPT_CONTEXT = 'KTX stores the selected Google Cloud project ID in ktx.yaml and uses Application Default Credentials for ' +
+const VERTEX_PROJECT_PROMPT_CONTEXT = 'ktx stores the selected Google Cloud project ID in ktx.yaml and uses Application Default Credentials for ' +
     'access. Project visibility depends on the signed-in Google account and organization permissions.';
 const DEFAULT_VERTEX_LOCATION = 'us-east5';
 const ANTHROPIC_PRESET = {
@@ -61,6 +79,14 @@ function presetForBackend(backend) {
     return MODEL_PRESETS[backend];
 }
 const execFileAsync = promisify(execFile);
+// Non-interactive setup cannot pick a provider safely: every backend needs
+// something the user must supply (an API key, gcloud ADC, or a logged-in local
+// CLI), so there is no credential-free default to fall back to. Name the hidden
+// --llm-backend flag and its choices here instead, mirroring how the other
+// automation errors guide users to the flag they need.
+const MISSING_LLM_BACKEND_MESSAGE = `Missing LLM backend: pass --llm-backend with one of ${KTX_SETUP_LLM_BACKENDS.join(', ')}. ` +
+    'claude-code and codex use local CLI authentication; anthropic also needs --anthropic-api-key-env or ' +
+    '--anthropic-api-key-file, and vertex also needs --vertex-project.';
 function createPromptAdapter() {
     return createKtxSetupPromptAdapter({ selectCancelValue: 'back' });
 }
@@ -171,10 +197,10 @@ function buildVertexHealthConfig(vertex, model) {
         promptCaching: { enabled: true, vertexFallbackTo5m: true },
     };
 }
-function llmHealthCheckStartText(provider, model) {
+function llmCheckStartText(provider, model) {
     return `Checking ${provider} LLM (${model}).`;
 }
-function startLlmHealthCheckProgress(spinner, message) {
+function startLlmCheckProgress(spinner, message) {
     spinner.start(message);
     return {
         succeed(msg) {
@@ -185,23 +211,23 @@ function startLlmHealthCheckProgress(spinner, message) {
         },
     };
 }
-async function runLlmHealthCheckWithProgress(config, provider, model, healthCheck, deps) {
-    const progress = startLlmHealthCheckProgress((deps.spinner ?? createClackSpinner)(), llmHealthCheckStartText(provider, model));
-    let health;
+async function validateModelWithProgress(provider, model, deps, run) {
+    const progress = startLlmCheckProgress((deps.spinner ?? createClackSpinner)(), llmCheckStartText(provider, model));
+    let result;
     try {
-        health = await healthCheck(config);
+        result = await run();
     }
     catch (error) {
         progress.fail('LLM test failed');
         throw error;
     }
-    if (health.ok) {
+    if (result.ok) {
         progress.succeed(`LLM test passed (${provider}, ${model})`);
     }
     else {
         progress.fail('LLM test failed');
     }
-    return health;
+    return result;
 }
 function formatVertexHealthFailure(message, vertex) {
     const trimmed = message.trim() || 'unknown error';
@@ -248,7 +274,7 @@ async function chooseCredentialRef(args, io, deps) {
     }
     while (true) {
         const choice = await prompts.select({
-            message: `How should KTX find your Anthropic API key?\n\n${ANTHROPIC_CREDENTIAL_PROMPT_CONTEXT}`,
+            message: `How should ktx find your Anthropic API key?\n\n${ANTHROPIC_CREDENTIAL_PROMPT_CONTEXT}`,
             options: [
                 { value: 'paste', label: 'Paste a key and save it as a local secret file' },
                 { value: 'env', label: 'Use ANTHROPIC_API_KEY from the environment' },
@@ -259,7 +285,7 @@ async function chooseCredentialRef(args, io, deps) {
             return { status: 'back' };
         }
         if (choice === 'paste') {
-            io.stdout.write('│  KTX will save the key in .ktx/secrets/anthropic-api-key with local file permissions, then write a file: reference in ktx.yaml.\n');
+            io.stdout.write('│  ktx will save the key in .ktx/secrets/anthropic-api-key with local file permissions, then write a file: reference in ktx.yaml.\n');
             const value = await prompts.password({ message: withTextInputNavigation('Anthropic API key') });
             if (value === undefined) {
                 continue;
@@ -301,30 +327,30 @@ async function chooseBackend(args, io, deps) {
         return { status: 'ready', backend: explicit, prompted: false };
     }
     if (args.inputMode === 'disabled') {
-        return { status: 'ready', backend: 'anthropic', prompted: false };
+        io.stderr.write(`${MISSING_LLM_BACKEND_MESSAGE}\n`);
+        return { status: 'missing-input' };
     }
     const prompts = deps.prompts ?? createPromptAdapter();
     if (args.showPromptInstructions !== false) {
         io.stdout.write('│  Use Up/Down to move, Enter to confirm the current selection, choose Back to return to the previous step, Ctrl+C to exit.\n');
     }
     const choice = await prompts.select({
-        message: 'Which LLM provider should KTX use?',
+        message: 'Which LLM provider should ktx use?',
         options: [
-            { value: 'claude-code', label: 'Claude subscription (Pro/Max)' },
-            { value: 'codex', label: 'Codex subscription' },
-            { value: 'anthropic', label: 'Anthropic API key' },
-            { value: 'vertex', label: 'Google Vertex AI for Anthropic Claude' },
+            ...KTX_SETUP_LLM_BACKENDS.map((backend) => ({ value: backend, label: KTX_SETUP_LLM_BACKEND_LABELS[backend] })),
             { value: 'back', label: 'Back' },
         ],
     });
     if (choice === 'back') {
         return { status: 'back' };
     }
-    return {
-        status: 'ready',
-        backend: choice === 'vertex' || choice === 'claude-code' || choice === 'codex' ? choice : 'anthropic',
-        prompted: true,
-    };
+    if (isKtxSetupLlmBackend(choice)) {
+        return { status: 'ready', backend: choice, prompted: true };
+    }
+    // Options are derived from KTX_SETUP_LLM_BACKENDS, so the only other value is
+    // 'back' (handled above). Treat any unexpected value as a cancel rather than
+    // silently assuming a provider.
+    return { status: 'back' };
 }
 function resolveProvidedVertexRef(label, ref, env, io) {
     let value;
@@ -404,7 +430,7 @@ async function chooseInteractiveVertexProject(currentProject, io, deps) {
             io.stdout.write('│  gcloud did not return any visible Google Cloud projects. Enter a project ID manually or choose Back.\n');
         }
         const choice = await prompts.autocomplete({
-            message: `Which Google Cloud project should KTX use for Vertex AI?\n\n${[
+            message: `Which Google Cloud project should ktx use for Vertex AI?\n\n${[
                 VERTEX_PROJECT_PROMPT_CONTEXT,
                 listFailureMessage,
             ]
@@ -616,7 +642,7 @@ export async function runKtxSetupAnthropicModelStep(args, io, deps = {}) {
                 return { status: vertex.status, projectDir: args.projectDir };
             }
             const preset = presetForBackend('vertex');
-            const validation = await validatePresetModels(preset, async (model) => runLlmHealthCheckWithProgress(buildVertexHealthConfig(vertex.values, model), 'Vertex AI', model, healthCheck, deps), io);
+            const validation = await validatePresetModels(preset, (model) => validateModelWithProgress('Vertex AI', model, deps, () => healthCheck(buildVertexHealthConfig(vertex.values, model))), io);
             if (validation.status !== 'ready') {
                 io.stderr.write(`Vertex AI Anthropic model health check failed: ${formatVertexHealthFailure(validation.message, vertex.values)}\n`);
                 if (args.inputMode === 'disabled') {
@@ -633,7 +659,7 @@ export async function runKtxSetupAnthropicModelStep(args, io, deps = {}) {
         if (backendChoice.backend === 'claude-code') {
             const preset = presetForBackend('claude-code');
             const probe = deps.claudeCodeAuthProbe ?? runClaudeCodeAuthProbe;
-            const validation = await validatePresetModels(preset, async (model) => probe({ projectDir: args.projectDir, model, env: deps.env ?? process.env }), io);
+            const validation = await validatePresetModels(preset, (model) => validateModelWithProgress('Claude subscription', model, deps, () => probe({ projectDir: args.projectDir, model, env: deps.env ?? process.env })), io);
             if (validation.status !== 'ready') {
                 io.stderr.write(`${validation.message}\n`);
                 return { status: 'failed', projectDir: args.projectDir };
@@ -649,7 +675,7 @@ export async function runKtxSetupAnthropicModelStep(args, io, deps = {}) {
         if (backendChoice.backend === 'codex') {
             const preset = presetForBackend('codex');
             const probe = deps.codexAuthProbe ?? runCodexAuthProbe;
-            const validation = await validatePresetModels(preset, async (model) => probe({ projectDir: args.projectDir, model }), io);
+            const validation = await validatePresetModels(preset, (model) => validateModelWithProgress('Codex', model, deps, () => probe({ projectDir: args.projectDir, model })), io);
             if (validation.status !== 'ready') {
                 io.stderr.write(`${validation.message}\n`);
                 return { status: 'failed', projectDir: args.projectDir };
@@ -670,7 +696,7 @@ export async function runKtxSetupAnthropicModelStep(args, io, deps = {}) {
             return { status: credential.status, projectDir: args.projectDir };
         }
         const preset = presetForBackend('anthropic');
-        const validation = await validatePresetModels(preset, async (model) => runLlmHealthCheckWithProgress(buildAnthropicHealthConfig(credential.value, model), 'Anthropic API', model, healthCheck, deps), io);
+        const validation = await validatePresetModels(preset, (model) => validateModelWithProgress('Anthropic API', model, deps, () => healthCheck(buildAnthropicHealthConfig(credential.value, model))), io);
         if (validation.status !== 'ready') {
             io.stderr.write(`Anthropic model health check failed: ${validation.message}\n`);
             if (args.inputMode === 'disabled') {

package/dist/setup-project.js

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
+import { classifyKtxRepoOwnership } from './context/core/git.service.js';
 import { initKtxProject, loadKtxProject } from './context/project/project.js';
 import { markKtxSetupStateStepComplete, mergeKtxSetupGitignoreEntries } from './context/project/setup-config.js';
 import { serializeKtxProjectConfig } from './context/project/config.js';
@@ -39,7 +40,24 @@ async function existingFolderState(projectDir) {
         throw error;
     }
 }
+/**
+ * ktx owns the git repository at the project dir, so it refuses to create a
+ * project inside a repository it did not create (which it would otherwise have
+ * to adopt or fail on at first commit). Guides the user toward a dedicated
+ * directory instead of letting `GitService.initialize()` throw mid-setup.
+ */
+async function ensureProjectDirIsOwnable(selectedDir, io) {
+    if ((await classifyKtxRepoOwnership(selectedDir)) === 'foreign') {
+        io.stderr.write(`${selectedDir} is already a git repository that ktx did not create.\n` +
+            'ktx keeps its context in a repository it owns. Choose a new subfolder or an empty directory instead.\n');
+        return false;
+    }
+    return true;
+}
 async function confirmProjectDir(selectedDir, io, prompts) {
+    if (!(await ensureProjectDirIsOwnable(selectedDir, io))) {
+        return { status: 'choose-another' };
+    }
     const state = await existingFolderState(selectedDir);
     if (state === 'not-directory') {
         io.stderr.write(`Project folder path exists and is not a directory: ${selectedDir}\n`);
@@ -49,7 +67,7 @@ async function confirmProjectDir(selectedDir, io, prompts) {
         const action = await prompts.select({
             message: `That folder already exists and is not empty: ${selectedDir}`,
             options: [
-                { value: 'use-existing', label: 'Yes, create KTX files there' },
+                { value: 'use-existing', label: 'Yes, create ktx files there' },
                 { value: 'choose-another', label: 'Choose another folder' },
                 { value: 'back', label: 'Back' },
             ],
@@ -62,9 +80,9 @@ async function confirmProjectDir(selectedDir, io, prompts) {
             return { status: 'cancelled' };
         return { status: 'confirmed', confirmedCreation: true };
     }
-    io.stdout.write(`│  KTX will create:\n│    ${selectedDir}\n`);
+    io.stdout.write(`│  ktx will create:\n│    ${selectedDir}\n`);
     const action = await prompts.select({
-        message: `Create KTX project at ${selectedDir}?`,
+        message: `Create ktx project at ${selectedDir}?`,
         options: [
             { value: 'create', label: 'Create project' },
             { value: 'choose-another', label: 'Choose another folder' },
@@ -108,7 +126,7 @@ async function promptForNewProjectDir(projectDir, homeDir, io, prompts) {
     const defaultProjectDir = join(projectDir, DEFAULT_NEW_PROJECT_FOLDER_NAME);
     while (true) {
         const destinationChoice = await prompts.select({
-            message: 'Where should KTX create the project?',
+            message: 'Where should ktx create the project?',
             options: [
                 { value: 'default', label: `Create the default project folder: ${defaultProjectDir}` },
                 { value: 'custom', label: 'Enter a custom path' },
@@ -196,6 +214,9 @@ export async function runKtxSetupProjectStep(args, io, deps = {}) {
             io.stderr.write('Missing setup choice: pass --yes to create a project in non-interactive setup.\n');
             return { status: 'missing-input', projectDir };
         }
+        if (!(await ensureProjectDirIsOwnable(projectDir, io))) {
+            return { status: 'missing-input', projectDir };
+        }
         const project = await createProject(projectDir, deps);
         printProjectSummary(io, projectDir);
         return {
@@ -217,7 +238,7 @@ export async function runKtxSetupProjectStep(args, io, deps = {}) {
     io.stdout.write('│  Use Up/Down to move, Enter to confirm the current selection, choose Back to return to the previous step, Ctrl+C to exit.\n');
     while (true) {
         const choice = await prompts.select({
-            message: 'Where should KTX create the project?',
+            message: 'Where should ktx create the project?',
             options: [
                 { value: 'current', label: `Current directory (${projectDir})` },
                 { value: 'new-default', label: `New subfolder (${defaultProjectDirLabel})` },
@@ -234,6 +255,9 @@ export async function runKtxSetupProjectStep(args, io, deps = {}) {
             return { status: 'cancelled', projectDir };
         }
         if (choice === 'current') {
+            if (!(await ensureProjectDirIsOwnable(projectDir, io))) {
+                continue;
+            }
             const project = await createProject(projectDir, deps);
             printProjectSummary(io, projectDir);
             return {

package/dist/setup-prompts.js

@@ -1,7 +1,15 @@
+import { updateSettings } from '@clack/core';
 import { autocomplete, autocompleteMultiselect, cancel, confirm, intro, isCancel, log, multiselect, note, select, text, } from '@clack/prompts';
+import { unicodeSupported } from './io/symbols.js';
+import { colorDepthForOutput, isWritableTtyOutput } from './io/tty.js';
 import { withMenuOptionsSpacing, withTextInputNavigation } from './prompt-navigation.js';
+import { renderKtxSetupBanner } from './setup-banner.js';
 import { revealPassword } from './reveal-password-prompt.js';
 import { withSetupInterruptConfirmation } from './setup-interrupt.js';
+// clack remaps Tab to Space only on non-text prompts (flat multiselect/select/
+// confirm); text inputs and autocomplete search set _track, so typed Tab is
+// untouched. This makes Tab the single documented select key across setup.
+updateSettings({ aliases: { tab: 'space' } });
 const DEFAULT_SETUP_CANCEL_MESSAGE = 'Setup cancelled.';
 export function createKtxSetupPromptAdapter(options) {
     const cancelMessage = options.cancelMessage ?? DEFAULT_SETUP_CANCEL_MESSAGE;
@@ -101,15 +109,18 @@ export function createKtxSetupPromptAdapter(options) {
         },
     };
 }
-function isWritableTtyOutput(output) {
-    return (output.isTTY === true &&
-        typeof output.on === 'function' &&
-        typeof output.columns !== 'undefined');
-}
 export function createKtxSetupUiAdapter() {
     return {
         intro(title, io) {
             if (isWritableTtyOutput(io.stdout)) {
+                const banner = renderKtxSetupBanner({
+                    columns: io.stdout.columns ?? 80,
+                    colorDepth: colorDepthForOutput(io.stdout),
+                    unicode: unicodeSupported,
+                });
+                if (banner !== '') {
+                    io.stdout.write(banner);
+                }
                 intro(title, { output: io.stdout });
                 return;
             }

package/dist/setup-ready-menu.js

@@ -56,7 +56,7 @@ export async function runKtxSetupReadyChangeMenu(status, deps = {}) {
             { value: 'databases', label: 'Databases' },
             { value: 'sources', label: 'Context sources' },
             ...(status.runtime.required ? [{ value: 'runtime', label: 'Runtime' }] : []),
-            { value: 'context', label: 'Rebuild KTX context' },
+            { value: 'context', label: 'Rebuild ktx context' },
             { value: 'agents', label: 'Agent integration' },
             { value: 'exit', label: 'Exit' },
         ],

package/dist/setup-sources.js

@@ -16,7 +16,7 @@ import { parseMetricflowFiles } from './context/ingest/adapters/metricflow/deep-
 import { serializeKtxProjectConfig } from './context/project/config.js';
 import { loadKtxProject } from './context/project/project.js';
 import { markKtxSetupStateStepComplete } from './context/project/setup-config.js';
-import { errorMessage, writePrefixedLines } from './clack.js';
+import { createCliSpinner, errorMessage, writePrefixedLines } from './clack.js';
 import { pickNotionRootPages } from './notion-page-picker.js';
 import { runKtxSourceMapping } from './source-mapping.js';
 import { runConnectionSetupWithRecovery, } from './connection-recovery.js';
@@ -65,7 +65,7 @@ function sourceAdapter(source) {
     return source;
 }
 function connectionNamePrompt(label) {
-    return `Name this ${label} connection\nKTX will use this short name in commands and config. You can rename it now.`;
+    return `Name this ${label} connection\nktx will use this short name in commands and config. You can rename it now.`;
 }
 function sourceSubpathPrompt(source) {
     if (source === 'dbt') {
@@ -143,7 +143,7 @@ function assertSourceCredentialFlags(source, args) {
 async function chooseSourceCredentialRef(input) {
     while (true) {
         const choice = await input.prompts.select({
-            message: `How should KTX find your ${input.label}?`,
+            message: `How should ktx find your ${input.label}?`,
             options: [
                 ...(input.existingRef ? [{ value: 'keep', label: 'Keep existing credential' }] : []),
                 { value: 'paste', label: 'Paste a key and save it as a local secret file' },
@@ -733,12 +733,15 @@ async function chooseMetabaseDatabaseId(input) {
     const sourceUrl = input.state.sourceUrl;
     const sourceApiKeyRef = input.state.sourceApiKeyRef;
     if (sourceUrl && sourceApiKeyRef) {
+        const discoverSpinner = createCliSpinner(input.io);
+        discoverSpinner.start('Discovering Metabase databases…');
         try {
             const discovered = await (input.deps.discoverMetabaseDatabases ?? defaultDiscoverMetabaseDatabases)({
                 sourceUrl,
                 sourceApiKeyRef,
                 sourceConnectionId: input.state.sourceConnectionId ?? 'metabase-main',
             });
+            discoverSpinner.stop(`Found ${discovered.length} ${discovered.length === 1 ? 'database' : 'databases'}`);
             if (discovered.length === 1) {
                 return discovered[0].id;
             }
@@ -763,6 +766,7 @@ async function chooseMetabaseDatabaseId(input) {
         catch {
             // Discovery is a convenience. Fall back to the raw id prompt when credentials
             // are unavailable locally or the Metabase API cannot be reached yet.
+            discoverSpinner.error('Could not reach Metabase — enter the database id manually');
         }
     }
     const databaseId = await promptText(input.prompts, { message: 'Metabase database id' });
@@ -891,6 +895,8 @@ async function promptForInteractiveSource(args, source, prompts, io, deps, defau
                                 scanDir = currentState.sourcePath;
                             }
                             else if (currentState.sourceLocation === 'git' && currentState.sourceGitUrl) {
+                                const cloneSpinner = createCliSpinner(io);
+                                cloneSpinner.start('Cloning repository to scan for dbt projects…');
                                 try {
                                     const cacheDir = await mkdtemp(join(tmpdir(), 'ktx-setup-dbt-scan-'));
                                     const authToken = currentState.sourceAuthTokenRef
@@ -903,8 +909,10 @@ async function promptForInteractiveSource(args, source, prompts, io, deps, defau
                                         branch: currentState.sourceBranch ?? 'main',
                                     });
                                     scanDir = cacheDir;
+                                    cloneSpinner.stop('Repository cloned');
                                 }
                                 catch {
+                                    cloneSpinner.error('Could not clone repository');
                                     // Clone failed — fall through to manual prompt
                                 }
                             }
@@ -924,7 +932,7 @@ async function promptForInteractiveSource(args, source, prompts, io, deps, defau
                                     }
                                     if (subpaths.length > 1) {
                                         const selected = await prompts.select({
-                                            message: 'Multiple dbt projects found — which one should KTX use?',
+                                            message: 'Multiple dbt projects found — which one should ktx use?',
                                             options: [
                                                 ...subpaths.map((p) => ({ value: p || '.', label: p || '(project root)' })),
                                                 { value: 'back', label: 'Back' },
@@ -1008,6 +1016,7 @@ async function promptForInteractiveSource(args, source, prompts, io, deps, defau
                     state,
                     prompts,
                     deps: { discoverMetabaseDatabases: discoverMetabaseDatabaseList },
+                    io,
                 });
                 if (databaseId === 'back')
                     return 'back';
@@ -1099,7 +1108,7 @@ async function promptForInteractiveSource(args, source, prompts, io, deps, defau
         },
         async (currentState) => {
             const crawlMode = await prompts.select({
-                message: 'Which Notion pages should KTX ingest?',
+                message: 'Which Notion pages should ktx ingest?',
                 options: [
                     { value: 'all_accessible', label: 'All pages the integration can access' },
                     { value: 'selected_roots', label: 'Specific pages and their subpages (choose them in a picker)' },
@@ -1449,11 +1458,22 @@ function sourceConnectionId(input) {
         : (input.sourceChoice.args.sourceConnectionId ?? `${input.source}-main`);
 }
 async function validateSourceConnectionAndMapping(input) {
-    const validation = await validateSource(input.source, { projectDir: input.args.projectDir, connectionId: input.connectionId, connection: input.connection }, input.deps);
+    const validateSpinner = createCliSpinner(input.io);
+    validateSpinner.start(`Validating ${sourceLabel(input.source)} source…`);
+    let validation;
+    try {
+        validation = await validateSource(input.source, { projectDir: input.args.projectDir, connectionId: input.connectionId, connection: input.connection }, input.deps);
+    }
+    catch (error) {
+        validateSpinner.error(`${sourceLabel(input.source)} source validation failed`);
+        throw error;
+    }
     if (!validation.ok) {
+        validateSpinner.error(`${sourceLabel(input.source)} source validation failed`);
         input.io.stderr.write(`${validation.message}\n`);
         return { status: 'failed' };
     }
+    validateSpinner.stop(`${sourceLabel(input.source)} source validated`);
     if (input.source === 'metabase' || input.source === 'looker') {
         input.prompts.log?.(`Validating ${sourceLabel(input.source)} mapping...`);
         const mappingCode = await (input.deps.runMapping ?? defaultRunMapping)(input.args.projectDir, input.connectionId, createSetupPrefixedIo(input.io));
@@ -1585,7 +1605,7 @@ export async function runKtxSetupSourcesStep(args, io, deps = {}) {
                 : args.inputMode === 'disabled'
                     ? []
                     : await prompts.multiselect({
-                        message: withMultiselectNavigation('Which context sources should KTX ingest?'),
+                        message: withMultiselectNavigation('Which context sources should ktx ingest?'),
                         options: contextSourceChecklist.options,
                         ...(contextSourceChecklist.initialValues.length > 0
                             ? { initialValues: contextSourceChecklist.initialValues }

package/dist/setup.d.ts

@@ -1,5 +1,6 @@
 import { type KtxCliIo } from './cli-runtime.js';
 import { readManagedPythonRuntimeStatus } from './managed-python-runtime.js';
+import type { CommandOutcome } from './telemetry/index.js';
 import { type KtxAgentScope, type KtxAgentTarget, type KtxSetupAgentsDeps, runKtxSetupAgentsStep } from './setup-agents.js';
 import { type KtxSetupDatabaseDriver, type KtxSetupDatabasesDeps, runKtxSetupDatabasesStep } from './setup-databases.js';
 import { type KtxSetupEmbeddingsDeps, runKtxSetupEmbeddingsStep } from './setup-embeddings.js';
@@ -125,6 +126,7 @@ export interface KtxSetupDeps {
     entryMenuDeps?: KtxSetupEntryMenuDeps;
     setupUi?: KtxSetupUiAdapter;
 }
+type TelemetrySetupStep = 'project' | 'runtime' | 'models' | 'embeddings' | 'databases' | 'sources' | 'context' | 'agents' | 'demo-tour';
 export interface KtxSetupEntryMenuPromptAdapter {
     select(options: {
         message: string;
@@ -135,6 +137,28 @@ export interface KtxSetupEntryMenuPromptAdapter {
 export interface KtxSetupEntryMenuDeps {
     prompts?: KtxSetupEntryMenuPromptAdapter;
 }
+interface SetupCommandAnnotation {
+    outcome: CommandOutcome;
+    errorClass?: string;
+    errorDetail?: string;
+}
+/**
+ * Single source of truth for how a non-ready setup step ends: the process exit
+ * code and the telemetry annotation are both derived from one classification,
+ * so they can never disagree. A genuine failure (`error`) exits non-zero; an
+ * abort — the user leaving an interactive wizard — exits 0, matching the entry
+ * menu's "Exit", a project cancellation, and a confirmed Ctrl+C.
+ */
+/** @internal */
+export declare function setupTerminalOutcome(input: {
+    status: 'failed' | 'missing-input' | 'cancelled';
+    step: TelemetrySetupStep;
+    interactive: boolean;
+    errorDetail?: string;
+}): {
+    exitCode: number;
+    annotation: SetupCommandAnnotation;
+};
 export interface ReadKtxSetupStatusOptions {
     cliVersion?: string;
     env?: NodeJS.ProcessEnv;
@@ -146,3 +170,4 @@ export declare function formatKtxSetupCompletionSummary(status: KtxSetupStatus,
     agentNextActions?: string;
 }): string;
 export declare function runKtxSetup(args: KtxSetupArgs, io: KtxCliIo, deps?: KtxSetupDeps): Promise<number>;
+export {};