@kaelio/ktx 0.11.0 → 0.13.0

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,8 +1,15 @@
+import { updateSettings } from '@clack/core';
 import { autocomplete, autocompleteMultiselect, cancel, confirm, intro, isCancel, log, multiselect, note, select, text, } from '@clack/prompts';
-import { isWritableTtyOutput } from './io/tty.js';
+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;
@@ -106,6 +113,14 @@ 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,9 +16,10 @@ 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 { assertSafeConnectionId } from './context/sl/source-files.js';
 import { runConnectionSetupWithRecovery, } from './connection-recovery.js';
 import { withMultiselectNavigation, withTextInputNavigation } from './prompt-navigation.js';
 import { runKtxPublicIngest } from './public-ingest.js';
@@ -65,7 +66,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') {
@@ -100,11 +101,6 @@ async function findDbtProjectSubpaths(rootDir) {
 async function promptText(prompts, options) {
     return await prompts.text({ ...options, message: withTextInputNavigation(options.message) });
 }
-function assertSafeConnectionId(connectionId) {
-    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(connectionId)) {
-        throw new Error(`Unsafe connection id: ${connectionId}`);
-    }
-}
 function credentialRef(value, label) {
     const ref = value?.trim();
     if (!ref) {
@@ -143,7 +139,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 +729,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 +762,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 +891,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 +905,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 +928,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 +1012,7 @@ async function promptForInteractiveSource(args, source, prompts, io, deps, defau
                     state,
                     prompts,
                     deps: { discoverMetabaseDatabases: discoverMetabaseDatabaseList },
+                    io,
                 });
                 if (databaseId === 'back')
                     return 'back';
@@ -1099,7 +1104,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 +1454,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 +1601,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

@@ -57,6 +57,7 @@ export type KtxSetupArgs = {
     agents: boolean;
     target?: KtxAgentTarget;
     agentScope?: KtxAgentScope;
+    installRoot?: string;
     skipAgents?: boolean;
     inputMode: 'auto' | 'disabled';
     debug?: boolean;

package/dist/setup.js

@@ -112,16 +112,16 @@ async function runKtxSetupEntryMenu(status, deps = {}) {
     const options = status.project.ready
         ? [
             { value: 'setup', label: 'Resume or change an existing setup' },
-            { value: 'new-project', label: 'Create a new KTX project' },
-            { value: 'agents', label: 'Connect a coding agent to KTX' },
+            { value: 'new-project', label: 'Create a new ktx project' },
+            { value: 'agents', label: 'Connect a coding agent to ktx' },
             { value: 'status', label: 'Check setup status' },
-            { value: 'demo', label: 'Explore a pre-built KTX project' },
+            { value: 'demo', label: 'Explore a pre-built ktx project' },
             { value: 'exit', label: 'Exit' },
         ]
         : [
-            { value: 'setup', label: 'Set up KTX for my data' },
+            { value: 'setup', label: 'Set up ktx for my data' },
             { value: 'status', label: 'Check setup status' },
-            { value: 'demo', label: 'Explore a pre-built KTX project' },
+            { value: 'demo', label: 'Explore a pre-built ktx project' },
             { value: 'exit', label: 'Exit' },
         ];
     const action = (await prompts.select({
@@ -282,16 +282,16 @@ function formatContextBuilt(status) {
 export function formatKtxSetupStatus(status) {
     if (!status.project.ready) {
         return [
-            `No KTX project found at ${status.project.path}.`,
+            `No ktx project found at ${status.project.path}.`,
             '',
             'Check another project: ktx --project-dir <folder> status',
             'Or from that folder: ktx status',
-            'Create a new KTX project here: ktx setup',
+            'Create a new ktx project here: ktx setup',
             '',
         ].join('\n');
     }
     const lines = [
-        `KTX project: ${status.project.path}`,
+        `ktx project: ${status.project.path}`,
         `Project ready: ${formatReady(status.project.ready)}`,
         `LLM ready: ${formatReady(status.llm.ready)}${status.llm.model ? ` (${status.llm.model})` : ''}`,
         `Embeddings ready: ${formatReady(status.embeddings.ready)}${status.embeddings.model ? ` (${status.embeddings.model})` : ''}`,
@@ -302,7 +302,7 @@ export function formatKtxSetupStatus(status) {
                 `Runtime ready: ${formatReady(status.runtime.ready)}${status.runtime.features.length > 0 ? ` (${status.runtime.features.join(', ')})` : ''}`,
             ]
             : []),
-        `KTX context built: ${formatContextBuilt(status.context)}`,
+        `ktx context built: ${formatContextBuilt(status.context)}`,
         `Agent integration ready: ${formatReady(status.agents.some((agent) => agent.ready))}${status.agents.length > 0 ? ` (${status.agents.map((agent) => `${agent.target}:${agent.scope}`).join(', ')})` : ''}`,
     ];
     if (!status.context.ready && status.context.status === 'failed' && status.context.detail) {
@@ -327,7 +327,7 @@ export function formatKtxSetupCompletionSummary(status, options = {}) {
         lines.push('', 'REQUIRED BEFORE USING AGENTS', '', ...agentNextActions.split('\n').map((line) => (line ? `  ${line}` : '')));
     }
     lines.push('', agentNextActions ? 'After that, try' : 'Try it');
-    lines.push('  Ask your agent: "Use KTX to show me the available tables."');
+    lines.push('  Ask your agent: "Use ktx to show me the available tables."');
     return lines.join('\n');
 }
 function setupStatusReady(status) {
@@ -357,7 +357,7 @@ function setupRuntimeInstallPolicy(args) {
 }
 async function commitSetupConfigChanges(projectDir) {
     const project = await loadKtxProject({ projectDir });
-    await project.git.commitFile('ktx.yaml', 'setup: update KTX project config', 'ktx setup', 'setup@ktx.local');
+    await project.git.commitFile('ktx.yaml', 'setup: update ktx project config', 'ktx setup', 'setup@ktx.local');
 }
 export async function runKtxSetup(args, io, deps = {}) {
     try {
@@ -372,7 +372,7 @@ export async function runKtxSetup(args, io, deps = {}) {
 }
 async function runKtxSetupInner(args, io, deps = {}) {
     const setupUi = deps.setupUi ?? createKtxSetupUiAdapter();
-    setupUi.intro('KTX setup', io);
+    setupUi.intro('ktx setup', io);
     setupUi.note(KTX_DOCS_URL, '📚 Docs', io);
     let entryAction;
     let projectResult;
@@ -624,6 +624,7 @@ async function runKtxSetupInner(args, io, deps = {}) {
                     agents: true,
                     ...(args.target ? { target: args.target } : {}),
                     scope: args.agentScope ?? 'project',
+                    ...(args.installRoot ? { installRoot: args.installRoot } : {}),
                     mode: 'mcp',
                     skipAgents: false,
                     showNextActions: agentsRequested,
@@ -684,7 +685,7 @@ async function runKtxSetupInner(args, io, deps = {}) {
     const focusedOnAgents = args.agents || entryAction === 'agents';
     if (!focusedOnAgents) {
         if (shouldPrintConciseReadySummary(status)) {
-            setupUi.note(formatKtxSetupCompletionSummary(status, { agentNextActions }), agentNextActions ? 'Finish KTX agent setup' : 'KTX project ready', io, {
+            setupUi.note(formatKtxSetupCompletionSummary(status, { agentNextActions }), agentNextActions ? 'Finish ktx agent setup' : 'ktx project ready', io, {
                 format: (line) => line,
             });
         }

package/dist/skills/analytics/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: ktx-analytics
-description: Use when answering a question that needs data from a KTX-connected database - investigating, analyzing, "how many", "show me", "what's the breakdown of", finding records by value, exploring tables, comparing periods, explaining metrics, or any data-analysis request. Triggers even when the user does not say "analytics"; if the answer requires querying a configured KTX connection, this skill applies.
+description: Use when answering a question that needs data from a ktx-connected database - investigating, analyzing, "how many", "show me", "what's the breakdown of", finding records by value, exploring tables, comparing periods, explaining metrics, or any data-analysis request. Triggers even when the user does not say "analytics"; if the answer requires querying a configured ktx connection, this skill applies.
 ---
 
-# KTX Analytics Workflow
+# ktx Analytics Workflow
 
-You have access to KTX MCP tools for data discovery, semantic-layer analysis, raw read-only SQL, wiki context, and memory ingest. Follow this workflow.
+You have access to ktx MCP tools for data discovery, semantic-layer analysis, raw read-only SQL, wiki context, and memory ingest. Follow this workflow.
 
 <workflow>
 1. **Discover** - call `discover_data` first to see what exists across wiki pages, semantic-layer sources, metrics, dimensions, raw tables, and columns. Returns refs only.

package/dist/skills/dbt_ingest/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: dbt_ingest
-description: Map dbt `schema.yml` / `properties.yml` models and sources into KTX semantic-layer overlays and column notes. Covers `sources:` vs `models:`, column `data_tests` (not_null, unique, accepted_values, relationships), and how bundle-time writes complement manifest backfill from git sync. Load when the WorkUnit's `skillNames` includes `dbt_ingest` or when raw files are dbt YAML under `models/` / `sources/`.
+description: Map dbt `schema.yml` / `properties.yml` models and sources into ktx semantic-layer overlays and column notes. Covers `sources:` vs `models:`, column `data_tests` (not_null, unique, accepted_values, relationships), and how bundle-time writes complement manifest backfill from git sync. Load when the WorkUnit's `skillNames` includes `dbt_ingest` or when raw files are dbt YAML under `models/` / `sources/`.
 callers: [memory_agent]
 ---
 
-# dbt → KTX (bundle ingest)
+# dbt → ktx (bundle ingest)
 
 Use this skill for **uploaded** dbt projects (`dbt_project.yml` at stage root, `models/**`, `sources/**`, `schema.yml`). There is **no** `fetch()` in v1 - scheduled `dbt parse` / `manifest.json` pulls are out of scope; host-provided dbt sync may still backfill structured test metadata into `_schema` on the next sync.
 
 ## Mapping (models / sources → SL)
 
-| dbt | KTX | Notes |
+| dbt | ktx | Notes |
 |-----|--------|--------|
 | `models:` entry with `columns:` | **Overlay** on the manifest table with the same name (after `discover_data` / `entity_details`) | One SL source per physical table; model name may differ from DB name - resolve with `read_raw_file` + warehouse context. |
 | `sources:` → `tables:` | Same as models; use `identifier` when present instead of logical `name`. | Schema + name must match how the connection sees tables. |

package/dist/skills/looker_ingest/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: looker_ingest
-description: Extract durable KTX knowledge and semantic-layer contribution proposals from staged Looker runtime dashboard, Look, and explore JSON. Load for WorkUnits whose raw files are under explores/, dashboards/, or looks/.
+description: Extract durable ktx knowledge and semantic-layer contribution proposals from staged Looker runtime dashboard, Look, and explore JSON. Load for WorkUnits whose raw files are under explores/, dashboards/, or looks/.
 callers: [memory_agent]
 ---
 
 # Looker Runtime Ingest
 
-Looker runtime ingest turns API-staged dashboards, Looks, and explores into durable KTX memory. Runtime entities are evidence. They are not themselves the final knowledge shape.
+Looker runtime ingest turns API-staged dashboards, Looks, and explores into durable ktx memory. Runtime entities are evidence. They are not themselves the final knowledge shape.
 
 ## Required Workflow
 
@@ -103,7 +103,7 @@ The staged explore file carries warehouse target fields populated before the WU
 - `rawSqlTableName`: Looker's verbatim `sql_table_name`. Keep it as provenance only.
 - `targetTable`: the parsed target-table union. Use this as the sole branch condition.
 
-When `targetTable.ok === true`, the explore has a complete KTX backing target. Before writing:
+When `targetTable.ok === true`, the explore has a complete ktx backing target. Before writing:
 
 1. Use `targetTable.catalog`, `targetTable.schema`, and `targetTable.name` for `source_tables` preflight matching through `sl_discover` or `sl_read_source`.
 2. Use Looker field `sql`, labels, descriptions, and type metadata to derive source columns, measures, segments, joins, and grain.