@kaelio/ktx 0.11.0 → 0.13.0

package/dist/setup-context.js

@@ -4,7 +4,7 @@ import { join, resolve } from 'node:path';
 import { loadKtxProject } from './context/project/project.js';
 import { markKtxSetupStateStepComplete, readKtxSetupState } from './context/project/setup-config.js';
 import { serializeKtxProjectConfig } from './context/project/config.js';
-import { errorMessage, writePrefixedLines } from './clack.js';
+import { createCliSpinner, errorMessage, writePrefixedLines } from './clack.js';
 import { formatErrorDetail } from './telemetry/scrubber.js';
 import { buildPublicIngestPlan } from './public-ingest.js';
 import { runKtxConnection } from './connection.js';
@@ -189,13 +189,22 @@ async function defaultGateTestConnection(projectDir, connectionId, io) {
  * test's output is captured in a buffer and discarded so raw error text never
  * reaches the user — callers surface only the connection id and connector type.
  */
-async function testRequiredConnections(projectDir, project, targets, testConnection) {
+async function testRequiredConnections(projectDir, project, targets, testConnection, io) {
     const failures = [];
-    for (const connectionId of requiredConnectionIds(targets)) {
+    const connectionIds = requiredConnectionIds(targets);
+    for (const [index, connectionId] of connectionIds.entries()) {
+        const driver = connectorTypeLabel(project, connectionId);
+        const counter = connectionIds.length > 1 ? ` (${index + 1}/${connectionIds.length})` : '';
+        const spinner = createCliSpinner(io);
+        spinner.start(`Testing connection ${connectionId}${counter}…`);
         const buffered = createBufferedCommandIo();
         const exitCode = await testConnection(projectDir, connectionId, buffered);
-        if (exitCode !== 0) {
-            failures.push({ connectionId, driver: connectorTypeLabel(project, connectionId) });
+        if (exitCode === 0) {
+            spinner.stop(`Connection ${connectionId} (${driver}) is reachable`);
+        }
+        else {
+            spinner.error(`Connection ${connectionId} (${driver}) is not reachable`);
+            failures.push({ connectionId, driver });
         }
     }
     return failures.length === 0 ? { ok: true } : { ok: false, failures };
@@ -213,7 +222,7 @@ async function prepareBuildTargets(args, io) {
         if (args.allowEmpty === true) {
             return { kind: 'result', result: { status: 'skipped', projectDir: args.projectDir } };
         }
-        io.stderr.write('No databases or context sources are configured for a KTX context build.\n');
+        io.stderr.write('No databases or context sources are configured for a ktx context build.\n');
         return { kind: 'result', result: { status: 'failed', projectDir: args.projectDir } };
     }
     const preflightPlan = buildPublicIngestPlan(project, { projectDir: project.projectDir, all: true });
@@ -228,12 +237,12 @@ async function prepareBuildTargets(args, io) {
     return { kind: 'ready', project, targets };
 }
 function writeConnectionGateFailureLines(io, projectDir, failures) {
-    io.stderr.write('KTX cannot build context: a required connection failed its live test.\n\n');
+    io.stderr.write('ktx cannot build context: a required connection failed its live test.\n\n');
     io.stderr.write('Failed connections:\n');
     for (const failure of failures) {
         io.stderr.write(`  ${failure.connectionId} (${failure.driver})\n`);
     }
-    io.stderr.write('\nEach connection must be reachable before KTX builds context.\n');
+    io.stderr.write('\nEach connection must be reachable before ktx builds context.\n');
     io.stderr.write(`Run \`ktx connection test <id> --project-dir ${resolve(projectDir)}\` to see the error, fix the connection, then retry.\n`);
 }
 function connectionGateFailureReason(failures) {
@@ -391,7 +400,7 @@ async function markContextComplete(projectDir) {
     await markKtxSetupStateStepComplete(projectDir, 'context');
 }
 function writeMissingCapabilities(missing, io) {
-    io.stderr.write('KTX cannot build agent-ready context yet.\n\n');
+    io.stderr.write('ktx cannot build agent-ready context yet.\n\n');
     io.stderr.write('Missing:\n');
     for (const item of missing) {
         io.stderr.write(`  ${item}\n`);
@@ -404,7 +413,7 @@ function writeSkippedContext(io) {
     io.stdout.write('\nLeaving context unbuilt for now.\n');
 }
 function writeSuccess(readiness, targets, io) {
-    io.stdout.write('\nKTX context is ready for agents.\n\n');
+    io.stdout.write('\nktx context is ready for agents.\n\n');
     io.stdout.write('Databases:\n');
     if (targets.primarySourceConnectionIds.length === 0) {
         io.stdout.write('  none\n');
@@ -428,7 +437,7 @@ function writeSuccess(readiness, targets, io) {
     io.stdout.write(`  Semantic search: ${readiness.semanticSearchReady ? 'ready' : 'not ready'}\n`);
 }
 function writeExistingContextSuccess(readiness, io) {
-    io.stdout.write('\nKTX context is ready for agents.\n\n');
+    io.stdout.write('\nktx context is ready for agents.\n\n');
     io.stdout.write('Existing context artifacts were found from setup ingest.\n\n');
     io.stdout.write('Verification:\n');
     io.stdout.write(`  Agent context: ${readiness.agentContextReady ? 'ready' : 'not ready'}\n`);
@@ -436,8 +445,8 @@ function writeExistingContextSuccess(readiness, io) {
 }
 async function promptForBuild(prompts) {
     return (await prompts.select({
-        message: 'Build KTX context for agents?\n\n' +
-            'KTX is fully configured and ready to build context. This may take a few minutes to a few hours.',
+        message: 'Build ktx context for agents?\n\n' +
+            'ktx is fully configured and ready to build context. This may take a few minutes to a few hours.',
         options: [
             { value: 'build', label: 'Build context now (recommended)' },
             { value: 'skip', label: 'Leave context unbuilt and exit setup' },
@@ -517,7 +526,7 @@ async function runBuild(args, io, deps, project, targets) {
             failureReason: readiness.details.join(' '),
             ...(lastSourceProgress ? { sourceProgress: lastSourceProgress } : {}),
         });
-        io.stderr.write('KTX context build did not pass agent-readiness verification.\n');
+        io.stderr.write('ktx context build did not pass agent-readiness verification.\n');
         for (const detail of readiness.details) {
             io.stderr.write(`  ${detail}\n`);
         }
@@ -607,7 +616,7 @@ export async function runKtxSetupContextStep(args, io, deps = {}) {
         // error text.
         const testConnection = deps.testConnection ?? defaultGateTestConnection;
         while (true) {
-            const gate = await testRequiredConnections(args.projectDir, project, targets, testConnection);
+            const gate = await testRequiredConnections(args.projectDir, project, targets, testConnection, io);
             if (gate.ok) {
                 return await runBuild(args, io, deps, project, targets);
             }

package/dist/setup-databases.d.ts

@@ -1,6 +1,7 @@
 import type { KtxLlmRuntimePort } from './context/llm/runtime-port.js';
 import { type ProposeQueryHistoryServiceAccountFiltersInput, type QueryHistoryFilterProposal } from './context/ingest/adapters/historic-sql/query-history-filter-picker.js';
 import { type HistoricSqlReadinessProbe } from './context/ingest/historic-sql-probes.js';
+import { type KtxProjectConnectionConfig } from './context/project/config.js';
 import { loadKtxProject } from './context/project/project.js';
 import type { KtxTableListEntry } from './context/scan/types.js';
 import { type KtxCliIo } from './cli-runtime.js';
@@ -90,6 +91,8 @@ export interface KtxSetupDatabasesDeps {
     createQueryHistoryLlmRuntime?: (projectDir: string, project: Awaited<ReturnType<typeof loadKtxProject>>) => KtxLlmRuntimePort | null;
 }
 /** @internal */
+export declare function federationNoticeFor(connections: Record<string, KtxProjectConnectionConfig>, projectDir: string): string | null;
+/** @internal */
 export declare function managedDaemonOptionsForSetupQueryHistoryPicker(input: {
     projectDir: string;
     args: Pick<KtxSetupDatabasesArgs, 'cliVersion' | 'runtimeInstallPolicy' | 'inputMode'>;

package/dist/setup-databases.js

@@ -3,6 +3,7 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { delimiter, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
+import { deriveFederatedConnection, FEDERATED_CONNECTION_ID } from './context/connections/federation.js';
 import { getDriverRegistration } from './context/connections/drivers.js';
 import { createLocalKtxLlmRuntimeFromConfig } from './context/llm/local-config.js';
 import { queryHistoryDialectForConnection } from './context/ingest/adapters/historic-sql/connection-dialect.js';
@@ -119,7 +120,7 @@ function driverLabel(driver) {
     return DRIVER_LABELS[driver];
 }
 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 missingConnectionDetailsPrompt(label, canReturnToDriverSelection) {
     const backDestination = canReturnToDriverSelection ? 'database selection' : 'the previous setup step';
@@ -163,12 +164,6 @@ function numberConfigField(connection, field) {
     const value = connection?.[field];
     return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 }
-function historicSqlConfigRecord(connection) {
-    const historicSql = connection?.historicSql;
-    return historicSql && typeof historicSql === 'object' && !Array.isArray(historicSql)
-        ? historicSql
-        : null;
-}
 function contextRecord(connection) {
     const context = connection?.context;
     return context && typeof context === 'object' && !Array.isArray(context) ? context : {};
@@ -179,28 +174,15 @@ function queryHistoryConfigRecord(connection) {
         ? queryHistory
         : null;
 }
-function stripLegacyHistoricSql(connection) {
-    const { historicSql: _historicSql, ...rest } = connection;
-    return rest;
-}
 function withQueryHistoryConfig(connection, queryHistory) {
     return {
-        ...stripLegacyHistoricSql(connection),
+        ...connection,
         context: {
             ...contextRecord(connection),
             queryHistory,
         },
     };
 }
-function migrateLegacyHistoricSqlConnection(connection) {
-    const existingQueryHistory = queryHistoryConfigRecord(connection);
-    const legacy = historicSqlConfigRecord(connection);
-    if (existingQueryHistory || !legacy) {
-        return existingQueryHistory ? stripLegacyHistoricSql(connection) : connection;
-    }
-    const { dialect: _dialect, ...queryHistory } = legacy;
-    return withQueryHistoryConfig(connection, queryHistory);
-}
 function setupHistoricSqlProbeResult(outcome) {
     if (!outcome) {
         return { ok: true, lines: [] };
@@ -864,6 +846,21 @@ async function writeConnectionConfig(input) {
     if (queryHistory?.enabled === true) {
         await ensureHistoricSqlIngestDefaults(input.projectDir);
     }
+    if (input.io) {
+        const federationNotice = federationNoticeFor(config.connections, input.projectDir);
+        if (federationNotice) {
+            writeSetupSection(input.io, 'Federated connection available', [federationNotice]);
+        }
+    }
+}
+/** @internal */
+export function federationNoticeFor(connections, projectDir) {
+    const descriptor = deriveFederatedConnection(connections, projectDir);
+    if (!descriptor) {
+        return null;
+    }
+    const names = descriptor.members.map((m) => m.connectionId).join(', ');
+    return `Detected ${descriptor.members.length} attach-compatible databases (${names}). Run a cross-database join as read-only SQL against \`${FEDERATED_CONNECTION_ID}\` (ktx sql -c ${FEDERATED_CONNECTION_ID} "SELECT ..."), using catalog-qualified table names.`;
 }
 async function disableConnectionQueryHistory(projectDir, connectionId) {
     const project = await loadKtxProject({ projectDir });
@@ -871,7 +868,7 @@ async function disableConnectionQueryHistory(projectDir, connectionId) {
     if (!connection) {
         return;
     }
-    const existing = queryHistoryConfigRecord(connection) ?? historicSqlConfigRecord(connection) ?? {};
+    const existing = queryHistoryConfigRecord(connection) ?? {};
     await writeConnectionConfig({
         projectDir,
         connectionId,
@@ -1004,32 +1001,29 @@ async function maybeConfigureDatabaseScope(input) {
     }
     const cliSchemas = input.args.databaseSchemas;
     if (input.args.inputMode === 'disabled') {
-        if (spec) {
-            let scopeToWrite = cliSchemas;
-            if (scopeToWrite.length === 0) {
-                try {
-                    scopeToWrite = unique(await (input.deps.listSchemas ?? defaultListSchemas)(input.projectDir, input.connectionId));
-                }
-                catch (error) {
-                    const detail = error instanceof Error ? error.message : String(error);
-                    input.io.stderr.write(`Could not discover ${spec.promptLabel.toLowerCase()} for ${input.connectionId}; ${detail}\n`);
-                    return okValidateResult();
-                }
-            }
-            if (scopeToWrite.length > 0) {
-                await writeScopeConfig({
-                    projectDir: input.projectDir,
-                    connectionId: input.connectionId,
-                    values: scopeToWrite,
-                    spec,
-                });
-                const capitalNounPlural = spec.nounPlural[0].toUpperCase() + spec.nounPlural.slice(1);
-                writeSetupSection(input.io, `${capitalNounPlural} saved for ${input.connectionId}`, [
-                    `✓ ${scopeToWrite.join(', ')}`,
-                ]);
-            }
+        if (!spec) {
+            return okValidateResult();
         }
-        return okValidateResult();
+        if (cliSchemas.length > 0) {
+            await writeScopeConfig({
+                projectDir: input.projectDir,
+                connectionId: input.connectionId,
+                values: cliSchemas,
+                spec,
+            });
+            const capitalNounPlural = spec.nounPlural[0].toUpperCase() + spec.nounPlural.slice(1);
+            writeSetupSection(input.io, `${capitalNounPlural} saved for ${input.connectionId}`, [
+                `✓ ${cliSchemas.join(', ')}`,
+            ]);
+            return okValidateResult();
+        }
+        if (existingScope.length > 0) {
+            return okValidateResult();
+        }
+        writePrefixedLines((chunk) => input.io.stderr.write(chunk), `No ${spec.nounPlural} configured for ${input.connectionId}. ` +
+            `Pass --database-schema <${spec.noun}> (repeatable) or set ` +
+            `connections.${input.connectionId}.${spec.configArrayField} in ktx.yaml.`);
+        return failedValidateResult();
     }
     if (spec && cliSchemas.length > 0) {
         await writeScopeConfig({
@@ -1158,20 +1152,14 @@ async function ensureHistoricSqlIngestDefaults(projectDir) {
 }
 async function markDatabasesComplete(projectDir, connectionIds) {
     const project = await loadKtxProject({ projectDir });
-    const config = setKtxSetupDatabaseConnectionIds({
-        ...project.config,
-        connections: Object.fromEntries(Object.entries(project.config.connections).map(([connectionId, connection]) => [
-            connectionId,
-            migrateLegacyHistoricSqlConnection(connection),
-        ])),
-    }, unique(connectionIds));
+    const config = setKtxSetupDatabaseConnectionIds(project.config, unique(connectionIds));
     await writeFile(project.configPath, serializeKtxProjectConfig(config), 'utf-8');
     await markKtxSetupStateStepComplete(projectDir, 'databases');
 }
 async function maybeRunHistoricSqlSetupProbe(input) {
     const project = await loadKtxProject({ projectDir: input.projectDir });
     const connection = project.config.connections[input.connectionId];
-    const queryHistory = queryHistoryConfigRecord(connection) ?? historicSqlConfigRecord(connection);
+    const queryHistory = queryHistoryConfigRecord(connection);
     if (queryHistory?.enabled !== true) {
         return true;
     }
@@ -1494,13 +1482,13 @@ async function chooseDrivers(args, io, prompts, options) {
         return [];
     }
     if (args.inputMode === 'disabled') {
-        io.stderr.write('KTX cannot work without a database. Pass --database or --database-connection-id, or pass --skip-databases to leave setup incomplete.\n');
+        io.stderr.write('ktx cannot work without a database. Pass --database or --database-connection-id, or pass --skip-databases to leave setup incomplete.\n');
         return 'missing-input';
     }
     const initialValues = unique(options?.initialDrivers ?? []);
     createKtxSetupUiAdapter().note(`Get demo credentials: ${KTX_DEMO_START_URL}`, '🎁 Need a warehouse to play with?', io);
     const choices = await prompts.multiselect({
-        message: withMultiselectNavigation('Which databases should KTX connect to?'),
+        message: withMultiselectNavigation('Which databases should ktx connect to?'),
         options: [...DRIVER_OPTIONS],
         ...(initialValues.length > 0 ? { initialValues } : {}),
         required: true,
@@ -1722,7 +1710,7 @@ async function runPrimarySourceFullEdit(input) {
 }
 export async function runKtxSetupDatabasesStep(args, io, deps = {}) {
     if (args.skipDatabases) {
-        io.stdout.write('│  Database setup skipped. KTX cannot work until you add a database.\n');
+        io.stdout.write('│  Database setup skipped. ktx cannot work until you add a database.\n');
         return { status: 'skipped', projectDir: args.projectDir };
     }
     const prompts = deps.prompts ?? createPromptAdapter();
@@ -1836,7 +1824,7 @@ export async function runKtxSetupDatabasesStep(args, io, deps = {}) {
             return { status: 'missing-input', projectDir: args.projectDir };
         if (drivers.length === 0) {
             await markDatabasesComplete(args.projectDir, []);
-            io.stdout.write('│  KTX cannot work without a database.\n');
+            io.stdout.write('│  ktx cannot work without a database.\n');
             return { status: 'skipped', projectDir: args.projectDir };
         }
         let returnToDriverSelection = false;

package/dist/setup-demo-tour.js

@@ -1,3 +1,4 @@
+import { createStaticCliSpinner, runWithCliSpinner } from './clack.js';
 import { createRepainter, renderContextBuildView } from './context-build-view.js';
 import { defaultDemoProjectDir, ensureSeededDemoProject } from './demo-assets.js';
 import { runKtxSetupAgentsStep } from './setup-agents.js';
@@ -48,7 +49,7 @@ function createTargetState(target) {
 export function renderDemoBanner(projectDir) {
     const lines = [
         '',
-        `┌  ${cyan('Demo mode')} — data has been pre-processed and KTX context is already built.`,
+        `┌  ${cyan('Demo mode')} — data has been pre-processed and ktx context is already built.`,
         '│  This walkthrough illustrates the setup steps. Selections are pre-filled and read-only.',
     ];
     if (projectDir) {
@@ -73,7 +74,7 @@ export function renderDemoAgentTransition() {
     const lines = [
         '┌  Demo project is ready — let\'s connect your agent',
         '│',
-        '│  Your KTX context has been built with demo data.',
+        '│  Your ktx context has been built with demo data.',
         '│  Select an agent to start using it.',
         '└',
     ];
@@ -83,17 +84,17 @@ export function renderDemoAgentTransition() {
 export function renderDemoCompletionSummary(projectDir, agentInstalled) {
     const lines = [
         '',
-        `${cyan('★')} KTX demo is ready`,
+        `${cyan('★')} ktx demo is ready`,
         '',
     ];
     if (agentInstalled) {
-        lines.push('  Your agent is connected to a demo KTX project.');
+        lines.push('  Your agent is connected to a demo ktx project.');
     }
     else {
         lines.push('  Demo project created. Connect an agent to start using it:');
         lines.push(`  $ ${cyan(`ktx setup --agents --project-dir ${projectDir}`)}`);
     }
-    lines.push('', `  ${dim('⚠')} This project is in a temporary directory and will be`, '    cleaned up by your system. To set up KTX with your own', '    data, run: ktx setup', '', `  Project: ${projectDir}`);
+    lines.push('', `  ${dim('⚠')} This project is in a temporary directory and will be`, '    cleaned up by your system. To set up ktx with your own', '    data, run: ktx setup', '', `  Project: ${projectDir}`);
     return lines.join('\n');
 }
 // ---------------------------------------------------------------------------
@@ -171,9 +172,9 @@ export function buildDemoReplayTimeline() {
 function renderDemoContextCompletionSummary() {
     const lines = [
         '',
-        `${cyan('★')} KTX finished building context`,
+        `${cyan('★')} ktx finished building context`,
         '',
-        '  KTX created:',
+        '  ktx created:',
         `    ${cyan('📊')} 46 semantic layer definitions`,
         `    ${cyan('📝')} 28 wiki pages`,
         '',
@@ -249,7 +250,10 @@ export async function runDemoTour(args, io, deps = {}) {
     const waitNav = deps.waitForNavigation ?? waitForDemoNavigation;
     const ensureProject = deps.ensureProject ?? ensureSeededDemoProject;
     const projectDir = defaultDemoProjectDir();
-    await ensureProject({ projectDir, force: false, io, cliVersion: args.cliVersion });
+    // Static (stderr-only) spinner: the demo navigation below reads stdin in raw mode,
+    // and an animated clack spinner would leave stdin dirty so the first keypress wait
+    // sees a stray key and skips the intro.
+    await runWithCliSpinner(createStaticCliSpinner(io), { start: 'Preparing demo project…', success: 'Demo project ready', failure: 'Could not prepare demo project' }, () => ensureProject({ projectDir, force: false, io, cliVersion: args.cliVersion }));
     io.stdout.write(renderDemoBanner(projectDir) + '\n');
     io.stdout.write(`\n│  ${dim('Press Enter to continue, Escape to go back')}\n└\n`);
     const introDirection = await waitNav();

package/dist/setup-embeddings.js

@@ -4,7 +4,7 @@ import { serializeKtxProjectConfig } from './context/project/config.js';
 import { loadKtxProject } from './context/project/project.js';
 import { markKtxSetupStateStepComplete, readKtxSetupState } from './context/project/setup-config.js';
 import { runKtxEmbeddingHealthCheck } from './llm/embedding-health.js';
-import { createStaticCliSpinner, errorMessage, writePrefixedLines } from './clack.js';
+import { createCliSpinner, errorMessage, writePrefixedLines } from './clack.js';
 import { ensureManagedLocalEmbeddingsDaemon, managedLocalEmbeddingHealthConfig, } from './managed-local-embeddings.js';
 import { ManagedPythonDaemonStartError } from './managed-python-daemon.js';
 import { withTextInputNavigation } from './prompt-navigation.js';
@@ -20,7 +20,7 @@ const DEFAULTS = {
     },
 };
 const LOCAL_EMBEDDING_BACKEND = 'sentence-transformers';
-const EMBEDDING_OPTION_PROMPT_CONTEXT = 'KTX uses embeddings for semantic search over semantic-layer sources, wiki context, schema metadata, ' +
+const EMBEDDING_OPTION_PROMPT_CONTEXT = 'ktx uses embeddings for semantic search over semantic-layer sources, wiki context, schema metadata, ' +
     'and relationship evidence.';
 const LOCAL_EMBEDDING_HEALTH_TIMEOUT_MS = 120_000;
 const LOCAL_EMBEDDING_STDERR_TAIL_LINES = 40;
@@ -136,7 +136,7 @@ async function chooseCredentialRef(backend, args, io, deps) {
     const defaultEnv = DEFAULTS[backend].envName ?? 'EMBEDDING_API_KEY';
     const prompts = deps.prompts ?? createPromptAdapter();
     const choice = await prompts.select({
-        message: `How should KTX find your ${embeddingBackendDisplayName(backend)} embedding API key?`,
+        message: `How should ktx find your ${embeddingBackendDisplayName(backend)} embedding API key?`,
         options: [
             { value: 'paste', label: 'Paste a key and save it as a local secret file' },
             { value: 'env', label: `Use ${defaultEnv} from the environment` },
@@ -148,7 +148,7 @@ async function chooseCredentialRef(backend, args, io, deps) {
     }
     if (choice === 'paste') {
         io.stdout.write(`│  ${[
-            `KTX will save the key in .ktx/secrets/${backend}-api-key with local file permissions,`,
+            `ktx will save the key in .ktx/secrets/${backend}-api-key with local file permissions,`,
             'then write a file: reference in ktx.yaml.',
         ].join(' ')}\n`);
         const value = await prompts.password({ message: withTextInputNavigation(`${backend} embedding API key`) });
@@ -181,7 +181,7 @@ async function chooseEmbeddingBackend(args, deps) {
         return LOCAL_EMBEDDING_BACKEND;
     }
     const choice = await (deps.prompts ?? createPromptAdapter()).select({
-        message: `Which embedding option should KTX use?\n\n${EMBEDDING_OPTION_PROMPT_CONTEXT}`,
+        message: `Which embedding option should ktx use?\n\n${EMBEDDING_OPTION_PROMPT_CONTEXT}`,
         options: [
             { value: 'sentence-transformers', label: 'Local sentence-transformers embeddings' },
             { value: 'openai', label: 'OpenAI embeddings', hint: 'recommended' },
@@ -211,19 +211,19 @@ async function readLocalEmbeddingDaemonStderrTail(stderrLog) {
 function localEmbeddingSetupMessage(message, stderrTail = []) {
     const lines = [
         `Local embedding health check failed: ${message}`,
-        'Local embeddings use the KTX-managed Python runtime.',
+        'Local embeddings use the ktx-managed Python runtime.',
         'Prepare the runtime with: ktx admin runtime start --feature local-embeddings',
         'Use --yes with setup to install and start the runtime without prompting.',
         'The first run may download Python packages and the all-MiniLM-L6-v2 model.',
     ];
     if (stderrTail.length > 0) {
-        lines.push('Recent KTX daemon stderr:', ...stderrTail);
+        lines.push('Recent ktx daemon stderr:', ...stderrTail);
     }
     return lines.join('\n');
 }
 async function promptAfterLocalEmbeddingFailure(deps) {
     const choice = await (deps.prompts ?? createPromptAdapter()).select({
-        message: 'Local embeddings are not reachable. Start the local KTX daemon, then retry.',
+        message: 'Local embeddings are not reachable. Start the local ktx daemon, then retry.',
         options: [
             { value: 'retry', label: 'Retry' },
             { value: 'openai', label: 'Use OpenAI embeddings' },
@@ -329,7 +329,7 @@ export async function runKtxSetupEmbeddingsStep(args, io, deps = {}) {
                 dimensions,
                 credentialValue,
             });
-        const healthSpinner = (deps.spinner ?? (() => createStaticCliSpinner(io)))();
+        const healthSpinner = (deps.spinner ?? (() => createCliSpinner(io)))();
         const progress = startHealthCheckProgress(healthSpinner, healthCheckStartText(selectedBackend, model, dimensions));
         let health;
         try {

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: {