@kaelio/ktx 0.10.0 → 0.12.0

package/dist/setup-agents.js

@@ -9,21 +9,11 @@ import { markKtxSetupStateStepComplete } from './context/project/setup-config.js
 import { serializeKtxProjectConfig } from './context/project/config.js';
 import { strToU8, zipSync } from 'fflate';
 import { errorMessage, writePrefixedLines } from './clack.js';
+import { isWritableTtyOutput } from './io/tty.js';
 import { createKtxSetupPromptAdapter, createKtxSetupUiAdapter, } from './setup-prompts.js';
 import { readKtxMcpDaemonStatus } from './managed-mcp-daemon.js';
+import { withMultiselectNavigation } from './prompt-navigation.js';
 const MCP_DAEMON_REQUIRED_NOTICE = 'mcp-daemon-required';
-function isWritableTtyOutput(output) {
-    return (output.isTTY === true &&
-        typeof output.on === 'function' &&
-        typeof output.columns !== 'undefined');
-}
-function writeSetupInfo(io, message) {
-    if (isWritableTtyOutput(io.stdout)) {
-        log.info(message, { output: io.stdout });
-        return;
-    }
-    io.stdout.write(`${message}\n`);
-}
 function writeSetupStep(io, message) {
     if (isWritableTtyOutput(io.stdout)) {
         log.step(message, { output: io.stdout });
@@ -152,7 +142,7 @@ function codexSnippet(endpoint) {
     if (endpoint.tokenAuth) {
         return [
             'Codex MCP config does not currently document HTTP headers.',
-            'Run KTX on loopback without token auth for Codex, or configure headers after Codex documents support.',
+            'Run ktx on loopback without token auth for Codex, or configure headers after Codex documents support.',
         ].join('\n');
     }
     return [`[mcp_servers.ktx]`, `url = "${endpoint.url}"`].join('\n');
@@ -410,16 +400,16 @@ function cliInstructionContent(input) {
     return [
         '---',
         'name: ktx',
-        'description: Use local KTX semantic context and wiki knowledge for this project.',
+        'description: Use local ktx semantic context and wiki knowledge for this project.',
         '---',
         '',
-        '# KTX Local Context',
+        '# ktx Local Context',
         '',
-        'This is an admin/developer CLI helper. End-user data agents should use the KTX MCP tools when available.',
+        'This is an admin/developer CLI helper. End-user data agents should use the ktx MCP tools when available.',
         '',
         `Use this project with \`--project-dir ${input.projectDir}\`.`,
-        'Commands are pinned to the local KTX CLI path that created this file, so agents do not need `ktx` in PATH.',
-        'If the CLI path no longer exists after moving this checkout or reinstalling KTX, rerun `ktx setup --agents`.',
+        'Commands are pinned to the local ktx CLI path that created this file, so agents do not need `ktx` in PATH.',
+        'If the CLI path no longer exists after moving this checkout or reinstalling ktx, rerun `ktx setup --agents`.',
         '',
         'Agents must not print secrets, credential references, environment variable values, or file contents from ' +
             '`.ktx/secrets`.',
@@ -530,7 +520,7 @@ function mergeManifest(projectDir, existing, installs, entries) {
 export async function removeKtxAgentInstall(projectDir, io) {
     const manifest = await readKtxAgentInstallManifest(projectDir);
     if (!manifest) {
-        io.stdout.write('No KTX agent installation manifest found.\n');
+        io.stdout.write('No ktx agent installation manifest found.\n');
         return 0;
     }
     for (const entry of manifest.entries) {
@@ -540,7 +530,7 @@ export async function removeKtxAgentInstall(projectDir, io) {
             await removeJsonKey(entry.path, entry.jsonPath).catch(() => undefined);
     }
     await rm(agentInstallManifestPath(projectDir), { force: true });
-    io.stdout.write('Removed KTX agent integration files from manifest.\n');
+    io.stdout.write('Removed ktx agent integration files from manifest.\n');
     return 0;
 }
 function createPromptAdapter() {
@@ -772,7 +762,7 @@ function formatAgentNextActions(input) {
     if (claudeCodeInstall) {
         lines.push(`${step}. Open Claude Code`);
         if (claudeCodeInstall.scope === 'project') {
-            lines.push('  Open Claude Code from the KTX project directory:');
+            lines.push('  Open Claude Code from the ktx project directory:');
             lines.push('');
             lines.push('  RUN:');
             lines.push(`  cd ${shellScriptQuote(projectDir)}`);
@@ -789,7 +779,7 @@ function formatAgentNextActions(input) {
     if (cursorInstall) {
         lines.push(`${step}. Open Cursor`);
         if (cursorInstall.scope === 'project') {
-            lines.push('  Open Cursor from the KTX project directory:');
+            lines.push('  Open Cursor from the ktx project directory:');
             lines.push('');
             lines.push('  OPEN:');
             lines.push(`  ${projectDir}`);
@@ -802,7 +792,7 @@ function formatAgentNextActions(input) {
     }
     if (input.installs.some((install) => install.target === 'claude-desktop')) {
         lines.push(`${step}. Restart Claude Desktop`);
-        lines.push('  Claude Desktop loads KTX MCP after restart.');
+        lines.push('  Claude Desktop loads ktx MCP after restart.');
         pushBlankLine(lines);
         step += 1;
         const skillBundlePaths = claudeDesktopSkillBundlePathsForInstalls(projectDir, input.installs);
@@ -813,7 +803,7 @@ function formatAgentNextActions(input) {
             for (const path of skillBundlePaths) {
                 lines.push(`  ${path}`);
             }
-            lines.push('  Toggle the uploaded KTX skills on.');
+            lines.push('  Toggle the uploaded ktx skills on.');
             pushBlankLine(lines);
             step += 1;
         }
@@ -863,22 +853,19 @@ export async function runKtxSetupAgentsStep(args, io, deps = {}) {
         return { status: 'skipped', projectDir: args.projectDir };
     }
     const prompts = deps.prompts ?? createPromptAdapter();
-    if (args.inputMode === 'auto' && args.target === undefined) {
-        writeSetupInfo(io, 'Space to select, Enter to confirm, Esc to go back.');
-    }
     const mode = args.inputMode === 'disabled'
         ? args.mode
         : (await prompts.select({
-            message: 'What should agents be allowed to do with this KTX project?',
+            message: 'What should agents be allowed to do with this ktx project?',
             options: [
                 {
                     value: 'mcp',
-                    label: 'Ask data questions with KTX MCP',
+                    label: 'Ask data questions with ktx MCP',
                     hint: 'Installs the MCP connection and analytics workflow skill. Best for normal use.',
                 },
                 {
                     value: 'mcp-cli',
-                    label: 'Ask data questions + manage KTX with CLI commands',
+                    label: 'Ask data questions + manage ktx with CLI commands',
                     hint: 'Adds an admin CLI skill so agents can run ktx status, sl, wiki, and setup commands.',
                 },
                 {
@@ -899,7 +886,7 @@ export async function runKtxSetupAgentsStep(args, io, deps = {}) {
         : args.inputMode === 'disabled'
             ? []
             : (await prompts.multiselect({
-                message: 'Which agent targets should KTX install?',
+                message: withMultiselectNavigation('Which agent targets should ktx install?'),
                 options: [
                     { value: 'claude-code', label: 'Claude Code' },
                     { value: 'claude-desktop', label: 'Claude Desktop' },
@@ -924,17 +911,17 @@ export async function runKtxSetupAgentsStep(args, io, deps = {}) {
         scopeTargets.length > 0 &&
         scopeTargets.every(targetSupportsGlobalScope)
         ? (await prompts.select({
-            message: `Where should KTX install supported agent config?\n\nKTX project: ${resolve(args.projectDir)}`,
+            message: `Where should ktx install supported agent config?\n\nktx project: ${resolve(args.projectDir)}`,
             options: [
                 {
                     value: 'project',
-                    label: 'Project scope (KTX project directory)',
-                    hint: 'Only agents opened from this KTX project path load the project-scoped config.',
+                    label: 'Project scope (ktx project directory)',
+                    hint: 'Only agents opened from this ktx project path load the project-scoped config.',
                 },
                 {
                     value: 'global',
                     label: 'Global scope (user config)',
-                    hint: 'Agents can load this KTX project from any working directory.',
+                    hint: 'Agents can load this ktx project from any working directory.',
                 },
             ],
         }))

package/dist/setup-banner.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The `ktx setup` intro banner: a lowercase ktx wordmark drawn with
+ * half-block glyphs over the brand-orange gradient, followed by the product
+ * tagline. Rendering is a pure function of the options so output stays
+ * deterministic in tests.
+ */
+export interface KtxSetupBannerOptions {
+    /** Terminal width in columns. */
+    columns: number;
+    /** Color depth in bits, as reported by `tty.WriteStream#getColorDepth`; 1 disables color. */
+    colorDepth: number;
+    /** Whether the terminal renders Unicode block glyphs. */
+    unicode: boolean;
+}
+/**
+ * Returns the banner block ending right above the clack intro line, or an
+ * empty string when the terminal cannot display it (no Unicode support or
+ * too narrow).
+ */
+export declare function renderKtxSetupBanner(options: KtxSetupBannerOptions): string;

package/dist/setup-banner.js

@@ -0,0 +1,39 @@
+/**
+ * The `ktx setup` intro banner: a lowercase ktx wordmark drawn with
+ * half-block glyphs over the brand-orange gradient, followed by the product
+ * tagline. Rendering is a pure function of the options so output stays
+ * deterministic in tests.
+ */
+const WORDMARK = [
+    { art: '███         ███', rgb: [253, 186, 116], ansi256: 215 },
+    { art: '███  ▄██▀ ███████ ▀██▄  ▄██▀', rgb: [251, 146, 60], ansi256: 214 },
+    { art: '███▄██▀     ███     ▀████▀', rgb: [249, 115, 22], ansi256: 208 },
+    { art: '███▀██▄     ███     ▄████▄', rgb: [234, 88, 12], ansi256: 202 },
+    { art: '███  ▀██▄   ███   ▄██▀  ▀██▄', rgb: [194, 65, 12], ansi256: 166 },
+];
+const TAGLINE = 'context layer for data agents';
+const INDENT = '  ';
+const BANNER_WIDTH = Math.max(...WORDMARK.map((row) => row.art.length), TAGLINE.length) + INDENT.length;
+/**
+ * Returns the banner block ending right above the clack intro line, or an
+ * empty string when the terminal cannot display it (no Unicode support or
+ * too narrow).
+ */
+export function renderKtxSetupBanner(options) {
+    if (!options.unicode || options.columns < BANNER_WIDTH) {
+        return '';
+    }
+    const art = WORDMARK.map((row) => INDENT + colorizeBannerRow(row, options.colorDepth));
+    const tagline = INDENT + (options.colorDepth > 1 ? `\u001b[2m${TAGLINE}\u001b[22m` : TAGLINE);
+    return `\n${art.join('\n')}\n\n${tagline}\n\n`;
+}
+function colorizeBannerRow(row, colorDepth) {
+    if (colorDepth >= 24) {
+        const [r, g, b] = row.rgb;
+        return `\u001b[38;2;${r};${g};${b}m${row.art}\u001b[39m`;
+    }
+    if (colorDepth >= 8) {
+        return `\u001b[38;5;${row.ansi256}m${row.art}\u001b[39m`;
+    }
+    return row.art;
+}

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.js

@@ -119,7 +119,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 +163,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 +173,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: [] };
@@ -871,7 +852,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 +985,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 +1136,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 +1466,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 +1694,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 +1808,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 {