@kaelio/ktx 0.4.1 → 0.6.0

package/dist/public-ingest.js

@@ -1,15 +1,17 @@
-import { loadKtxProject } from '@ktx/context/project';
+import { getKtxCliPackageInfo } from './cli-runtime.js';
+import { loadKtxProject } from './context/project/project.js';
 import { databaseContextDepth, deepReadinessGaps, isDatabaseDriver, normalizeConnectionDriver, } from './ingest-depth.js';
 import { ensureManagedPythonCommandRuntime, } from './managed-python-command.js';
 import { publicIngestOutputLine } from './public-ingest-copy.js';
 import { resolvePublicIngestRuntimeRequirements } from './runtime-requirements.js';
 import { profileMark } from './startup-profile.js';
+import { isDemoConnection } from './telemetry/demo-detect.js';
+import { emitProjectStackSnapshot, emitTelemetryEvent } from './telemetry/index.js';
 profileMark('module:public-ingest');
 const sourceAdapterByDriver = new Map([
     ['metabase', 'metabase'],
     ['local_metabase', 'metabase'],
     ['looker', 'looker'],
-    ['local_looker', 'looker'],
     ['notion', 'notion'],
     ['metricflow', 'metricflow'],
     ['dbt', 'dbt'],
@@ -17,7 +19,6 @@ const sourceAdapterByDriver = new Map([
 ]);
 const queryHistoryDialectByDriver = new Map([
     ['postgres', 'postgres'],
-    ['postgresql', 'postgres'],
     ['bigquery', 'bigquery'],
     ['snowflake', 'snowflake'],
 ]);
@@ -122,9 +123,6 @@ function queryHistoryPullConfig(input) {
         ...(input.windowDays !== undefined ? { windowDays: input.windowDays } : {}),
     };
 }
-function depthFromLegacyScanMode(mode) {
-    return mode === 'enriched' || mode === 'relationships' ? 'deep' : undefined;
-}
 function sourceDirForConnection(connection) {
     const value = connection.source_dir;
     return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
@@ -137,7 +135,7 @@ function resolveDatabaseTargetOptions(input) {
     const windowOverrideRequested = input.args.queryHistoryWindowDays !== undefined;
     const requestedQh = explicitQueryHistory === 'enabled' ||
         (explicitQueryHistory !== 'disabled' && (windowOverrideRequested || storedEnabled));
-    let depth = input.args.depth ?? depthFromLegacyScanMode(input.args.scanMode) ?? databaseContextDepth(input.connection) ?? 'fast';
+    let depth = input.args.depth ?? databaseContextDepth(input.connection) ?? 'fast';
     const queryHistory = {
         enabled: false,
         ...(input.args.queryHistoryWindowDays !== undefined
@@ -335,30 +333,82 @@ function markTargetResult(target, args, status, failedOperation, failureDetail)
         }),
     };
 }
+function markTargetWithSkippedQueryHistory(target, args, detail) {
+    const baseline = markTargetResult(target, args, 'done');
+    return {
+        ...baseline,
+        steps: baseline.steps.map((step) => step.operation === 'query-history' ? { ...step, status: 'skipped', detail } : step),
+    };
+}
+function queryHistoryFailureDetail(input) {
+    const captured = capturedFailureMessage(input.capturedOutput ?? '');
+    return failureDetailWithRetry({
+        target: input.target,
+        args: input.args,
+        failedOperation: 'query-history',
+        failureDetail: captured,
+    });
+}
 function resultFailed(result) {
     return result.steps.some((step) => step.status === 'failed');
 }
+function resultSkippedQueryHistory(result) {
+    const skipped = result.steps.find((step) => step.operation === 'query-history' && step.status === 'skipped' && step.detail !== undefined);
+    return skipped?.detail ? { connectionId: result.connectionId, detail: skipped.detail } : null;
+}
+function rowsBucket() {
+    return '<10k';
+}
+async function emitIngestCompleted(input) {
+    const failed = resultFailed(input.result);
+    await emitTelemetryEvent({
+        name: 'ingest_completed',
+        projectDir: input.args.projectDir,
+        io: input.io,
+        fields: {
+            driver: input.target.driver,
+            isDemoConnection: isDemoConnection(input.target.connectionId, input.project.config.connections[input.target.connectionId]),
+            schemaCount: 0,
+            tableCount: 0,
+            columnCount: 0,
+            rowsBucket: rowsBucket(),
+            durationMs: Math.max(0, performance.now() - input.startedAt),
+            outcome: failed ? 'error' : 'ok',
+        },
+    });
+}
 function stepStatus(result, operation) {
     return result.steps.find((step) => step.operation === operation)?.status ?? 'not-run';
 }
 function renderPlainResults(results, io) {
     const failures = results.filter(resultFailed);
-    io.stdout.write(failures.length > 0 ? 'Ingest finished with partial failures\n' : 'Ingest finished\n');
+    const skippedQueryHistory = results.map(resultSkippedQueryHistory).filter((entry) => entry !== null);
+    const headerSuffix = failures.length > 0
+        ? ' with partial failures'
+        : skippedQueryHistory.length > 0
+            ? ' with skipped query history'
+            : '';
+    io.stdout.write(`Ingest finished${headerSuffix}\n`);
     io.stdout.write('\n');
     io.stdout.write('Source         Database schema  Query history  Source ingest  Memory update\n');
     for (const result of results) {
         io.stdout.write(`${result.connectionId.padEnd(14)} ${stepStatus(result, 'database-schema').padEnd(16)} ${stepStatus(result, 'query-history').padEnd(14)} ${stepStatus(result, 'source-ingest').padEnd(14)} ${stepStatus(result, 'memory-update')}\n`);
     }
-    if (failures.length === 0) {
-        return;
+    if (failures.length > 0) {
+        io.stdout.write('\nFailed sources:\n');
+        for (const result of failures) {
+            const failedStep = result.steps.find((step) => step.status === 'failed');
+            if (!failedStep) {
+                continue;
+            }
+            io.stdout.write(`  ${failedStep.detail ?? `${result.connectionId} failed.`}\n`);
+        }
     }
-    io.stdout.write('\nFailed sources:\n');
-    for (const result of failures) {
-        const failedStep = result.steps.find((step) => step.status === 'failed');
-        if (!failedStep) {
-            continue;
+    if (skippedQueryHistory.length > 0) {
+        io.stdout.write('\nSkipped query history:\n');
+        for (const { detail } of skippedQueryHistory) {
+            io.stdout.write(`  ${detail}\n`);
         }
-        io.stdout.write(`  ${failedStep.detail ?? `${result.connectionId} failed.`}\n`);
     }
 }
 function hasInteractiveInput(io) {
@@ -501,8 +551,13 @@ export async function executePublicIngestTarget(target, args, io, deps) {
                 ? await runIngest(ingestArgs, ingestIo, ingestDeps)
                 : await runIngest(ingestArgs, ingestIo);
             if (qhExitCode !== 0) {
-                deps.onPhaseEnd?.('query-history', 'failed');
-                return markTargetResult(target, args, 'failed', 'query-history', capturedIngestIo ? capturedFailureMessage(capturedIngestIo.capturedOutput()) : undefined);
+                const detail = queryHistoryFailureDetail({
+                    target,
+                    args,
+                    capturedOutput: capturedIngestIo ? capturedIngestIo.capturedOutput() : undefined,
+                });
+                deps.onPhaseEnd?.('query-history', 'failed', detail);
+                return markTargetWithSkippedQueryHistory(target, args, detail);
             }
             deps.onPhaseEnd?.('query-history', 'done');
         }
@@ -540,12 +595,15 @@ export async function runKtxPublicIngest(args, io, deps = {}) {
     const project = await loadProject({ projectDir: args.projectDir });
     if (shouldUseForegroundContextBuildView(args, io)) {
         const plan = buildPublicIngestPlan(project, args);
-        const requirements = resolvePublicIngestRuntimeRequirements(plan, { env: deps.env ?? process.env });
+        const requirements = resolvePublicIngestRuntimeRequirements(plan, {
+            config: project.config,
+            env: deps.env ?? process.env,
+        });
         const ensureRuntime = deps.ensureRuntime ?? ensureManagedPythonCommandRuntime;
         for (const feature of requirements.features) {
             try {
                 await ensureRuntime({
-                    cliVersion: args.cliVersion ?? '0.0.0-private',
+                    cliVersion: args.cliVersion ?? getKtxCliPackageInfo().version,
                     installPolicy: args.runtimeInstallPolicy ?? 'prompt',
                     io,
                     feature,
@@ -585,7 +643,10 @@ export async function runKtxPublicIngest(args, io, deps = {}) {
         }
     }
     for (const target of plan.targets) {
-        results.push(await executePublicIngestTarget(target, args, io, deps));
+        const startedAt = performance.now();
+        const result = await executePublicIngestTarget(target, args, io, deps);
+        results.push(result);
+        await emitIngestCompleted({ args, project, target, result, startedAt, io });
     }
     if (args.json) {
         io.stdout.write(`${JSON.stringify({ plan, results }, null, 2)}\n`);
@@ -593,5 +654,6 @@ export async function runKtxPublicIngest(args, io, deps = {}) {
     else {
         renderPlainResults(results, io);
     }
+    await emitProjectStackSnapshot({ projectDir: args.projectDir, io });
     return results.some(resultFailed) ? 1 : 0;
 }

package/dist/runtime-requirements.d.ts

@@ -1,4 +1,4 @@
-import type { KtxProjectConfig } from '@ktx/context/project';
+import type { KtxProjectConfig } from './context/project/config.js';
 import type { KtxRuntimeFeature } from './managed-python-runtime.js';
 import type { KtxPublicIngestPlan } from './public-ingest.js';
 type KtxRuntimeRequirementReason = 'query-history' | 'looker-source' | 'database-introspection' | 'local-embeddings';
@@ -16,6 +16,7 @@ export interface KtxProjectRuntimeRequirementOptions {
     env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
 }
 export interface KtxPublicIngestRuntimeRequirementOptions {
+    config?: KtxProjectConfig;
     env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
 }
 export declare function resolveProjectRuntimeRequirements(config: KtxProjectConfig, options?: KtxProjectRuntimeRequirementOptions): KtxRuntimeRequirements;

package/dist/runtime-requirements.js

@@ -49,7 +49,7 @@ export function resolveProjectRuntimeRequirements(config, options = {}) {
     }
     for (const [connectionId, connection] of Object.entries(config.connections)) {
         const driver = normalizeDriver(connection.driver);
-        if ((driver === 'looker' || driver === 'local_looker') && !hasDaemonOverride(env)) {
+        if (driver === 'looker' && !hasDaemonOverride(env)) {
             requirements.push({
                 feature: 'core',
                 reason: 'looker-source',
@@ -86,7 +86,7 @@ export function resolvePublicIngestRuntimeRequirements(plan, options = {}) {
                 detail: `${target.connectionId} query-history ingest uses SQL analysis.`,
             });
         }
-        if ((driver === 'looker' || driver === 'local_looker' || adapter === 'looker') && !hasDaemonOverride(env)) {
+        if ((driver === 'looker' || adapter === 'looker') && !hasDaemonOverride(env)) {
             requirements.push({
                 feature: 'core',
                 reason: 'looker-source',
@@ -94,5 +94,12 @@ export function resolvePublicIngestRuntimeRequirements(plan, options = {}) {
             });
         }
     }
+    if (options.config && requiresManagedLocalEmbeddings(options.config.ingest.embeddings)) {
+        requirements.push({
+            feature: 'local-embeddings',
+            reason: 'local-embeddings',
+            detail: 'Local sentence-transformers embeddings use the managed Python runtime.',
+        });
+    }
     return uniqueRequirements(requirements);
 }

package/dist/scan.d.ts

@@ -1,4 +1,6 @@
-import { type KtxProgressPort, type KtxScanMode, runLocalScan } from '@ktx/context/scan';
+import type { KtxProgressPort, KtxScanMode } from './context/scan/types.js';
+import { runLocalScan } from './context/scan/local-scan.js';
+import { resolveProjectEmbeddingProvider } from './embedding-resolution.js';
 import type { KtxCliIo } from './index.js';
 import { createKtxCliLocalIngestAdapters } from './local-adapters.js';
 import type { KtxManagedPythonInstallPolicy } from './managed-python-command.js';
@@ -16,6 +18,7 @@ export interface KtxScanArgs {
 export interface KtxScanDeps {
     runLocalScan?: typeof runLocalScan;
     createLocalIngestAdapters?: typeof createKtxCliLocalIngestAdapters;
+    resolveEmbeddingProvider?: typeof resolveProjectEmbeddingProvider;
     progress?: KtxProgressPort;
     runtimeIo?: KtxCliIo;
 }
@@ -30,6 +33,7 @@ interface KtxCliScanProgress extends Omit<KtxProgressPort, 'update'> {
     update(progress: number, message?: string, options?: KtxCliScanProgressUpdateOptions): Promise<void>;
     flush(): void;
 }
+/** @internal */
 export declare function createCliScanProgress(io: KtxCliIo, state?: KtxCliScanProgressState, start?: number, weight?: number): KtxCliScanProgress;
 export declare function runKtxScan(args: KtxScanArgs, io?: KtxCliIo, deps?: KtxScanDeps): Promise<number>;
 export {};

package/dist/scan.js

@@ -1,9 +1,12 @@
-import { runLocalScan, } from '@ktx/context/scan';
-import { loadKtxProject } from '@ktx/context/project';
+import { runLocalScan } from './context/scan/local-scan.js';
+import { loadKtxProject } from './context/project/project.js';
+import { getKtxCliPackageInfo } from './cli-runtime.js';
 import { resolveProjectEmbeddingProvider } from './embedding-resolution.js';
 import { createKtxCliLocalIngestAdapters } from './local-adapters.js';
 import { createKtxCliScanConnector } from './local-scan-connectors.js';
 import { profileMark } from './startup-profile.js';
+import { emitTelemetryEvent } from './telemetry/index.js';
+import { scrubErrorClass } from './telemetry/scrubber.js';
 profileMark('module:scan');
 function shouldUseStyledOutput(io) {
     return io.stdout.isTTY === true && !process.env.NO_COLOR && process.env.TERM !== 'dumb' && !process.env.CI;
@@ -29,6 +32,12 @@ function tableChangeCount(report) {
 function totalTableCount(report) {
     return tableChangeCount(report) + report.diffSummary.tablesUnchanged;
 }
+function scanColumnCount(report) {
+    return report.structuralSyncStats.columnsCreated + report.structuralSyncStats.columnsUpdated;
+}
+function inferredFkCount(report) {
+    return report.relationships.accepted + report.relationships.review + report.relationships.rejected;
+}
 function writeScanIdentity(report, io) {
     io.stdout.write(`Run: ${report.runId}\n`);
     io.stdout.write(`Connection: ${report.connectionId}\n`);
@@ -204,6 +213,7 @@ function writeRunSummary(report, projectDir, io) {
     const statusCommand = styled ? dim('ktx status') : 'ktx status';
     io.stdout.write(`  ${statusCommand} --project-dir ${projectDirArg}\n`);
 }
+/** @internal */
 export function createCliScanProgress(io, state = { progress: 0, hasPendingTransient: false }, start = 0, weight = 1) {
     const shouldWrite = io.stdout.isTTY === true && !process.env.CI;
     const progress = {
@@ -237,13 +247,15 @@ export function createCliScanProgress(io, state = { progress: 0, hasPendingTrans
     return progress;
 }
 export async function runKtxScan(args, io = process, deps = {}) {
+    const startedAt = performance.now();
     try {
         const project = await loadKtxProject({ projectDir: args.projectDir });
-        const resolution = await resolveProjectEmbeddingProvider(project, {
+        const resolveEmbeddingProvider = deps.resolveEmbeddingProvider ?? resolveProjectEmbeddingProvider;
+        const resolution = await resolveEmbeddingProvider(project, {
             mode: 'ensure',
             installPolicy: args.runtimeInstallPolicy ?? 'never',
-            cliVersion: args.cliVersion ?? '0.0.0-private',
-            io,
+            cliVersion: args.cliVersion ?? getKtxCliPackageInfo().version,
+            io: deps.runtimeIo ?? io,
         });
         const embeddingProvider = resolution.kind === 'disabled' || resolution.kind === 'managed-unavailable' ? null : resolution.provider;
         const managedDaemon = managedDaemonOptionsForScanRun(args, deps.runtimeIo ?? io);
@@ -270,14 +282,45 @@ export async function runKtxScan(args, io = process, deps = {}) {
                 ...(progress ? { progress } : {}),
             });
             cliProgress?.flush();
+            await emitTelemetryEvent({
+                name: 'scan_completed',
+                projectDir: args.projectDir,
+                io,
+                fields: {
+                    driver: result.report.driver,
+                    tableCount: totalTableCount(result.report),
+                    columnCount: scanColumnCount(result.report),
+                    inferredFkCount: inferredFkCount(result.report),
+                    declaredFkCount: 0,
+                    durationMs: Math.max(0, performance.now() - startedAt),
+                    outcome: 'ok',
+                },
+            });
             writeRunSummary(result.report, args.projectDir, io);
         }
         finally {
             cliProgress?.flush();
+            await connector?.cleanup?.();
         }
         return 0;
     }
     catch (error) {
+        const errorClass = scrubErrorClass(error);
+        await emitTelemetryEvent({
+            name: 'scan_completed',
+            projectDir: args.projectDir,
+            io,
+            fields: {
+                driver: 'unknown',
+                tableCount: 0,
+                columnCount: 0,
+                inferredFkCount: 0,
+                declaredFkCount: 0,
+                durationMs: Math.max(0, performance.now() - startedAt),
+                outcome: 'error',
+                ...(errorClass ? { errorClass } : {}),
+            },
+        });
         io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
         return 1;
     }

package/dist/setup-agents.d.ts

@@ -2,6 +2,7 @@ import type { KtxCliIo } from './cli-runtime.js';
 import { type KtxSetupPromptOption } from './setup-prompts.js';
 export type KtxAgentTarget = 'claude-code' | 'claude-desktop' | 'codex' | 'cursor' | 'opencode' | 'universal';
 export type KtxAgentScope = 'project' | 'global' | 'local';
+/** @internal */
 export type KtxAgentInstallMode = 'mcp' | 'mcp-cli';
 export interface KtxSetupAgentsArgs {
     projectDir: string;
@@ -48,7 +49,7 @@ export interface KtxAgentInstallManifest {
     entries: Array<{
         kind: 'file';
         path: string;
-        role?: 'skill' | 'rule' | 'analytics-skill' | 'claude-desktop-skill-bundle' | 'launcher';
+        role?: 'skill' | 'rule' | 'analytics-skill' | 'claude-desktop-skill-bundle';
     } | {
         kind: 'json-key';
         path: string;
@@ -56,9 +57,9 @@ export interface KtxAgentInstallManifest {
     }>;
 }
 type InstallEntry = KtxAgentInstallManifest['entries'][number];
+/** @internal */
 export declare function createAgentNextActionsLineFormatter(stdout: KtxCliIo['stdout']): (line: string) => string;
-export declare function collectClaudeDesktopForwardedEnv(source: NodeJS.ProcessEnv): Record<string, string>;
-export declare function agentInstallManifestPath(projectDir: string): string;
+/** @internal */
 export declare function plannedKtxAgentFiles(input: {
     projectDir: string;
     target: KtxAgentTarget;
@@ -66,8 +67,9 @@ export declare function plannedKtxAgentFiles(input: {
     mode: KtxAgentInstallMode;
 }): InstallEntry[];
 export declare function readKtxAgentInstallManifest(projectDir: string): Promise<KtxAgentInstallManifest | null>;
+/** @internal */
 export declare function removeKtxAgentInstall(projectDir: string, io: KtxCliIo): Promise<number>;
-export interface KtxSetupAgentsPromptAdapter {
+interface KtxSetupAgentsPromptAdapter {
     select(options: {
         message: string;
         options: KtxSetupPromptOption[];
@@ -83,10 +85,12 @@ export interface KtxSetupAgentsDeps {
     prompts?: KtxSetupAgentsPromptAdapter;
 }
 export declare function targetDisplayName(target: string): string;
+/** @internal */
 export interface InstallSummaryEntry {
     title: string;
     lines: string[];
 }
+/** @internal */
 export declare function formatInstallSummaryLines(installs: Array<{
     target: KtxAgentTarget;
     scope: KtxAgentScope;

package/dist/setup-agents.js

@@ -1,11 +1,14 @@
 import { existsSync } from 'node:fs';
-import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { styleText } from 'node:util';
 import { log, outro } from '@clack/prompts';
-import { loadKtxProject, markKtxSetupStateStepComplete, serializeKtxProjectConfig, } from '@ktx/context/project';
+import { loadKtxProject } from './context/project/project.js';
+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 { createKtxSetupPromptAdapter, createKtxSetupUiAdapter, } from './setup-prompts.js';
 import { readKtxMcpDaemonStatus } from './managed-mcp-daemon.js';
 const MCP_DAEMON_REQUIRED_NOTICE = 'mcp-daemon-required';
@@ -37,6 +40,7 @@ function writeSetupOutro(io, message) {
 }
 const STEP_HEADING_RE = /^(\d+)\. (.+)$/;
 const ACTION_MARKER_RE = /^(RUN|PASTE|USE|OPEN):$/;
+/** @internal */
 export function createAgentNextActionsLineFormatter(stdout) {
     const maybeHasColors = stdout.hasColors;
     const supportsColor = typeof maybeHasColors === 'function' && Boolean(maybeHasColors.call(stdout));
@@ -197,7 +201,7 @@ function claudeDesktopConfigPath() {
     return { path, jsonPath: ['mcpServers', 'ktx'] };
 }
 const CLAUDE_DESKTOP_FORWARDED_ENV_KEYS = ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY'];
-export function collectClaudeDesktopForwardedEnv(source) {
+function collectClaudeDesktopForwardedEnv(source) {
     const captured = {};
     for (const [key, value] of Object.entries(source)) {
         if (value === undefined || value === '')
@@ -210,9 +214,10 @@ export function collectClaudeDesktopForwardedEnv(source) {
 }
 function claudeDesktopMcpEntry(input) {
     const captured = collectClaudeDesktopForwardedEnv(input.env ?? process.env);
+    const launcher = ktxCliLauncher();
     return {
-        command: input.launcherPath,
-        args: ['--project-dir', input.projectDir, 'mcp', 'stdio'],
+        command: launcher.command,
+        args: [...launcher.args, '--project-dir', input.projectDir, 'mcp', 'stdio'],
         ...(Object.keys(captured).length > 0 ? { env: captured } : {}),
     };
 }
@@ -222,8 +227,7 @@ async function installMcpClientConfig(input) {
     const notices = [];
     if (input.target === 'claude-desktop') {
         const config = claudeDesktopConfigPath();
-        const launcherPath = claudeDesktopLauncherPath(input.projectDir);
-        await writeJsonKey(config.path, config.jsonPath, claudeDesktopMcpEntry({ launcherPath, projectDir: input.projectDir }));
+        await writeJsonKey(config.path, config.jsonPath, claudeDesktopMcpEntry({ projectDir: input.projectDir }));
         entries.push({ kind: 'json-key', path: config.path, jsonPath: config.jsonPath });
         return { entries, snippets, notices };
     }
@@ -270,7 +274,7 @@ function plannedMcpJsonEntries(input) {
     }
     return [];
 }
-export function agentInstallManifestPath(projectDir) {
+function agentInstallManifestPath(projectDir) {
     return join(resolve(projectDir), '.ktx/agents/install-manifest.json');
 }
 function claudeDesktopAnalyticsSkillBundlePath(projectDir) {
@@ -279,9 +283,7 @@ function claudeDesktopAnalyticsSkillBundlePath(projectDir) {
 function claudeDesktopAdminSkillBundlePath(projectDir) {
     return join(resolve(projectDir), '.ktx/agents/claude/ktx.zip');
 }
-function claudeDesktopLauncherPath(projectDir) {
-    return join(resolve(projectDir), '.ktx/agents/claude/ktx-plugin-runner.sh');
-}
+/** @internal */
 export function plannedKtxAgentFiles(input) {
     const withAdminCli = input.mode === 'mcp-cli';
     if (input.scope === 'global') {
@@ -314,7 +316,6 @@ export function plannedKtxAgentFiles(input) {
         }
         if (input.target === 'claude-desktop') {
             return [
-                { kind: 'file', path: claudeDesktopLauncherPath(input.projectDir), role: 'launcher' },
                 {
                     kind: 'file',
                     path: claudeDesktopAnalyticsSkillBundlePath(input.projectDir),
@@ -448,58 +449,6 @@ function cliInstructionContent(input) {
         '',
     ].join('\n');
 }
-function claudeDesktopLauncherContent(input) {
-    const binPath = input.launcher.args[0];
-    if (!binPath) {
-        throw new Error('Expected KTX CLI launcher to include a bin path.');
-    }
-    const candidates = [
-        input.launcher.command,
-        '/opt/homebrew/bin/node',
-        '/usr/local/bin/node',
-        '/usr/bin/node',
-    ];
-    return [
-        '#!/bin/sh',
-        'set -eu',
-        '',
-        `KTX_CLI_BIN=${shellScriptQuote(binPath)}`,
-        '',
-        'run_with_node() {',
-        '  node_bin=$1',
-        '  shift',
-        '  exec "$node_bin" "$KTX_CLI_BIN" "$@"',
-        '}',
-        '',
-        'if [ -n "${KTX_NODE:-}" ] && [ -x "${KTX_NODE:-}" ]; then',
-        '  run_with_node "$KTX_NODE" "$@"',
-        'fi',
-        '',
-        'if [ -x "$HOME/.volta/bin/node" ]; then',
-        '  run_with_node "$HOME/.volta/bin/node" "$@"',
-        'fi',
-        '',
-        ...candidates.map((candidate) => [
-            `if [ -x ${shellScriptQuote(candidate)} ]; then`,
-            `  run_with_node ${shellScriptQuote(candidate)} "$@"`,
-            'fi',
-        ].join('\n')),
-        '',
-        'for candidate in "$HOME"/.nvm/versions/node/*/bin/node; do',
-        '  if [ -x "$candidate" ]; then',
-        '    run_with_node "$candidate" "$@"',
-        '  fi',
-        'done',
-        '',
-        'if command -v node >/dev/null 2>&1; then',
-        '  run_with_node "$(command -v node)" "$@"',
-        'fi',
-        '',
-        'echo "KTX Claude Desktop launcher could not find Node.js. Set KTX_NODE to a Node executable and rerun ktx setup --agents." >&2',
-        'exit 127',
-        '',
-    ].join('\n');
-}
 async function writeClaudeDesktopSkillBundle(input) {
     const content = input.skillName === 'ktx-analytics'
         ? await readAnalyticsSkillContent()
@@ -519,11 +468,6 @@ function claudeDesktopSkillNameForBundle(path) {
     }
     throw new Error(`Unsupported Claude Desktop skill bundle path: ${path}`);
 }
-async function writeClaudeDesktopLauncher(input) {
-    await mkdir(dirname(input.path), { recursive: true });
-    await writeFile(input.path, claudeDesktopLauncherContent({ launcher: input.launcher }), 'utf-8');
-    await chmod(input.path, 0o755);
-}
 function ruleInstructionContent(input) {
     return [
         `Use the \`ktx\` CLI to query local semantic context and wiki knowledge for this project ` +
@@ -582,6 +526,7 @@ function mergeManifest(projectDir, existing, installs, entries) {
         entries: [...entryMap.values()],
     };
 }
+/** @internal */
 export async function removeKtxAgentInstall(projectDir, io) {
     const manifest = await readKtxAgentInstallManifest(projectDir);
     if (!manifest) {
@@ -676,6 +621,7 @@ function formatInlinePath(path) {
     }
     return path;
 }
+/** @internal */
 export function formatInstallSummaryLines(installs, entries, projectDir) {
     const entriesByTarget = new Map();
     for (const install of installs) {
@@ -726,9 +672,6 @@ export function formatInstallSummaryLines(installs, entries, projectDir) {
         else if (hasAnalytics || hasAdmin) {
             lines.push(`${guidanceInstallLine(install.target)}.`);
         }
-        if (hasEntryRole(targetEntries, 'launcher')) {
-            lines.push('Starts KTX over stdio from Claude Desktop.');
-        }
         return {
             title: `${targetDisplayName(install.target)} · ${scopeDisplayName(install.scope)}`,
             lines,
@@ -887,10 +830,6 @@ async function installTarget(input) {
     for (const entry of entries) {
         if (entry.kind !== 'file')
             continue;
-        if (entry.role === 'launcher') {
-            await writeClaudeDesktopLauncher({ path: entry.path, launcher });
-            continue;
-        }
         if (entry.role === 'claude-desktop-skill-bundle') {
             await writeClaudeDesktopSkillBundle({
                 projectDir: input.projectDir,
@@ -942,10 +881,19 @@ export async function runKtxSetupAgentsStep(args, io, deps = {}) {
                     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.',
                 },
+                {
+                    value: 'skip',
+                    label: 'Skip agent setup for now',
+                    hint: 'Leaves agent integration incomplete. You can run ktx setup --agents later.',
+                },
             ],
         }));
     if (mode === 'back')
         return { status: 'skipped', projectDir: args.projectDir };
+    if (mode === 'skip') {
+        io.stdout.write('│  Agent integration skipped.\n');
+        return { status: 'skipped', projectDir: args.projectDir };
+    }
     const targets = args.target !== undefined
         ? [args.target]
         : args.inputMode === 'disabled'
@@ -1033,7 +981,7 @@ export async function runKtxSetupAgentsStep(args, io, deps = {}) {
         return { status: 'ready', projectDir: args.projectDir, installs, nextActions };
     }
     catch (error) {
-        io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        writePrefixedLines((chunk) => io.stderr.write(chunk), errorMessage(error));
         return { status: 'failed', projectDir: args.projectDir };
     }
 }