@kaelio/ktx 0.7.0 → 0.8.0

package/dist/setup-context.js

@@ -6,8 +6,6 @@ import { markKtxSetupStateStepComplete, readKtxSetupState } from './context/proj
 import { serializeKtxProjectConfig } from './context/project/config.js';
 import { errorMessage, writePrefixedLines } from './clack.js';
 import { buildPublicIngestPlan } from './public-ingest.js';
-import { databaseContextDepth, } from './ingest-depth.js';
-import { ensureSetupDatabaseContextDepths } from './setup-database-context-depth.js';
 import { runContextBuild, } from './context-build-view.js';
 import { createKtxSetupPromptAdapter, } from './setup-prompts.js';
 const SETUP_CONTEXT_STATE_PATH = ['.ktx', 'setup', 'context-build.json'];
@@ -232,15 +230,6 @@ async function readLatestScanReport(projectDir, connectionId) {
     reports.sort((left, right) => left.sortKey.localeCompare(right.sortKey));
     return reports.at(-1)?.report ?? null;
 }
-function scanReportHasSchemaManifest(report, connectionId) {
-    if (!isRecord(report)) {
-        return false;
-    }
-    if (report.connectionId !== connectionId || report.dryRun === true) {
-        return false;
-    }
-    return stringArrayValue(isRecord(report.artifactPaths) ? report.artifactPaths.manifestShards : undefined).length > 0;
-}
 function scanReportHasCompletedDeepEnrichment(report, connectionId, relationshipsRequired) {
     if (!isRecord(report)) {
         return false;
@@ -260,23 +249,13 @@ function scanReportHasCompletedDeepEnrichment(report, connectionId, relationship
         (!relationshipsRequired || completedStages.includes('relationships')) &&
         stringArrayValue(report.artifactPaths.manifestShards).length > 0);
 }
-function scanReportSatisfiesDepth(input) {
-    if (input.depth === 'fast') {
-        return scanReportHasSchemaManifest(input.report, input.connectionId);
-    }
-    return scanReportHasCompletedDeepEnrichment(input.report, input.connectionId, input.relationshipsRequired);
-}
 async function verifyPrimarySourceScans(project, connectionIds) {
     const details = [];
     const relationshipsRequired = project.config.scan.relationships.enabled;
     for (const connectionId of connectionIds) {
-        const connection = project.config.connections[connectionId];
-        const depth = connection ? (databaseContextDepth(connection) ?? 'fast') : 'fast';
         const report = await readLatestScanReport(project.projectDir, connectionId);
-        if (!scanReportSatisfiesDepth({ report, connectionId, depth, relationshipsRequired })) {
-            details.push(depth === 'fast'
-                ? `${connectionId}: schema context has not completed.`
-                : `${connectionId}: deep database context has not completed.`);
+        if (!scanReportHasCompletedDeepEnrichment(report, connectionId, relationshipsRequired)) {
+            details.push(`${connectionId}: database context has not completed.`);
         }
     }
     return { ready: details.length === 0, details };
@@ -331,7 +310,7 @@ function writeSkippedContext(projectDir, io) {
     io.stdout.write(`Build context:\n  ktx setup --project-dir ${resolve(projectDir)}\n\n`);
     io.stdout.write(`Check status:\n  ktx status --project-dir ${resolve(projectDir)}\n`);
 }
-function writeSuccess(project, readiness, targets, io) {
+function writeSuccess(readiness, targets, io) {
     io.stdout.write('\nKTX context is ready for agents.\n\n');
     io.stdout.write('Databases:\n');
     if (targets.primarySourceConnectionIds.length === 0) {
@@ -339,9 +318,7 @@ function writeSuccess(project, readiness, targets, io) {
     }
     else {
         for (const connectionId of targets.primarySourceConnectionIds) {
-            const connection = project.config.connections[connectionId];
-            const depth = connection ? (databaseContextDepth(connection) ?? 'fast') : 'fast';
-            io.stdout.write(`  ${connectionId}: ${depth === 'deep' ? 'deep context complete' : 'schema context complete'}\n`);
+            io.stdout.write(`  ${connectionId}: database context complete\n`);
         }
     }
     io.stdout.write('\nContext sources:\n');
@@ -466,7 +443,7 @@ async function runBuild(args, io, deps, project, targets) {
         failureReason: undefined,
         ...(lastSourceProgress ? { sourceProgress: lastSourceProgress } : {}),
     });
-    writeSuccess(project, readiness, targets, io);
+    writeSuccess(readiness, targets, io);
     return { status: 'ready', projectDir: args.projectDir, runId };
 }
 async function completeExistingContext(args, io, deps, targets) {
@@ -496,17 +473,8 @@ async function completeExistingContext(args, io, deps, targets) {
 }
 export async function runKtxSetupContextStep(args, io, deps = {}) {
     try {
-        let project = await loadKtxProject({ projectDir: args.projectDir });
+        const project = await loadKtxProject({ projectDir: args.projectDir });
         const prompts = deps.prompts ?? createPromptAdapter();
-        const depthProject = await ensureSetupDatabaseContextDepths({
-            project,
-            args,
-            prompts,
-        });
-        if (depthProject === 'back') {
-            return { status: 'back', projectDir: args.projectDir };
-        }
-        project = depthProject;
         const existingState = await readKtxSetupContextState(args.projectDir);
         const completedSteps = (await readKtxSetupState(args.projectDir)).completed_steps;
         if (completedSteps.includes('context') && existingState.status === 'completed') {

package/dist/setup-databases.js

@@ -14,13 +14,12 @@ import { runKtxConnection } from './connection.js';
 import { pickDatabaseScope as defaultPickDatabaseScope, } from './database-tree-picker.js';
 import { withMultiselectNavigation, withTextInputNavigation } from './prompt-navigation.js';
 import { runKtxScan } from './scan.js';
-import { applySetupDatabaseContextDepth } from './setup-database-context-depth.js';
 import { writeProjectLocalSecretReference } from './setup-secrets.js';
 import { isDemoConnection } from './telemetry/demo-detect.js';
 import { emitTelemetryEvent } from './telemetry/index.js';
 import { createKtxSetupPromptAdapter, createKtxSetupUiAdapter, } from './setup-prompts.js';
 const HISTORIC_SQL_WORK_UNIT_MAX_CONCURRENCY = 6;
-const KTX_QUICKSTART_URL = 'https://docs.kaelio.com/ktx/docs/getting-started/quickstart';
+const KTX_DEMO_START_URL = 'https://www.kaelio.com/start';
 const execFileAsync = promisify(execFileCallback);
 const DRIVER_OPTIONS = [
     { value: 'postgres', label: 'PostgreSQL' },
@@ -1209,39 +1208,10 @@ async function applyHistoricSqlConfigToExistingConnection(input) {
     });
     if (withHistoricSql === 'back')
         return 'back';
-    const withContextDepth = await maybeApplyContextDepthConfig({
-        projectDir: input.projectDir,
-        connectionId: input.connectionId,
-        connection: withHistoricSql,
-        args: input.args,
-        prompts: input.prompts,
-    });
-    if (withContextDepth === 'back')
-        return 'back';
     await writeConnectionConfig({
         projectDir: input.projectDir,
         connectionId: input.connectionId,
-        connection: withContextDepth,
-    });
-}
-async function maybeApplyContextDepthConfig(input) {
-    const project = await loadKtxProject({ projectDir: input.projectDir });
-    return await applySetupDatabaseContextDepth({
-        project: {
-            ...project,
-            config: {
-                ...project.config,
-                connections: {
-                    ...project.config.connections,
-                    [input.connectionId]: input.connection,
-                },
-            },
-        },
-        connection: input.connection,
-        args: {
-            inputMode: input.args.inputMode === 'disabled' || input.args.databaseUrl ? 'disabled' : input.args.inputMode,
-        },
-        prompts: input.prompts,
+        connection: withHistoricSql,
     });
 }
 async function validateAndScanConnection(input) {
@@ -1273,7 +1243,7 @@ async function validateAndScanConnection(input) {
         deps: input.deps,
     });
     writeSetupSection(input.io, `Building schema context for ${input.connectionId}`, [
-        'Running fast database ingest…',
+        'Running database scan…',
     ]);
     let scanIo = createBufferedCommandIo();
     let scanCode = await scanConnection(input.projectDir, input.connectionId, scanIo);
@@ -1281,7 +1251,7 @@ async function validateAndScanConnection(input) {
         const nativeSqliteDetail = nativeSqliteAbiMismatchDetail(`${scanIo.stderrText()}\n${scanIo.stdoutText()}`);
         if (nativeSqliteDetail) {
             writePrefixedLines((chunk) => input.io.stderr.write(chunk), [
-                `Fast database ingest failed for ${input.connectionId}.`,
+                `Database scan failed for ${input.connectionId}.`,
                 'Native SQLite is built for a different Node.js ABI.',
                 `Detail: ${nativeSqliteDetail}`,
                 'Rebuilding Native SQLite with pnpm run native:rebuild…',
@@ -1289,7 +1259,7 @@ async function validateAndScanConnection(input) {
             const rebuildNativeSqlite = input.deps.rebuildNativeSqlite ?? defaultRebuildNativeSqlite;
             const rebuildCode = await rebuildNativeSqlite(input.io);
             if (rebuildCode === 0) {
-                writePrefixedLines((chunk) => input.io.stderr.write(chunk), 'Native SQLite rebuild complete. Retrying fast database ingest…');
+                writePrefixedLines((chunk) => input.io.stderr.write(chunk), 'Native SQLite rebuild complete. Retrying database scan…');
                 const retryScanIo = createBufferedCommandIo();
                 scanCode = await scanConnection(input.projectDir, input.connectionId, retryScanIo);
                 scanIo = retryScanIo;
@@ -1297,18 +1267,18 @@ async function validateAndScanConnection(input) {
             if (scanCode !== 0) {
                 writePrefixedLines((chunk) => input.io.stderr.write(chunk), [
                     rebuildCode === 0
-                        ? `Fast database ingest still failed for ${input.connectionId} after rebuilding Native SQLite.`
+                        ? `Database scan still failed for ${input.connectionId} after rebuilding Native SQLite.`
                         : `Native SQLite rebuild failed for ${input.connectionId}.`,
                     'Fix: pnpm run native:rebuild',
-                    `Retry: ktx ingest ${input.connectionId} --project-dir ${input.projectDir} --fast`,
+                    `Retry: ktx ingest ${input.connectionId} --project-dir ${input.projectDir}`,
                 ].join('\n'));
             }
         }
         else {
             flushPrefixedBufferedCommandOutput(input.io, scanIo);
             writePrefixedLines((chunk) => input.io.stderr.write(chunk), [
-                `Fast database ingest failed for ${input.connectionId}.`,
-                `Debug command: ktx ingest ${input.connectionId} --project-dir ${input.projectDir} --fast --debug`,
+                `Database scan failed for ${input.connectionId}.`,
+                `Debug command: ktx ingest ${input.connectionId} --project-dir ${input.projectDir} --debug`,
             ].join('\n'));
         }
         if (scanCode !== 0) {
@@ -1334,7 +1304,7 @@ async function chooseDrivers(args, io, prompts, options) {
         return 'missing-input';
     }
     const initialValues = unique(options?.initialDrivers ?? []);
-    createKtxSetupUiAdapter().note(`Get demo credentials from the Quickstart: ${KTX_QUICKSTART_URL}`, '🎁 Need a warehouse to play with?', io);
+    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?'),
         options: [...DRIVER_OPTIONS],
@@ -1690,23 +1660,10 @@ export async function runKtxSetupDatabasesStep(args, io, deps = {}) {
                     returnToDriverSelection = true;
                     break;
                 }
-                const withContextDepth = await maybeApplyContextDepthConfig({
-                    projectDir: args.projectDir,
-                    connectionId: connectionChoice.connectionId,
-                    connection: withHistoricSql,
-                    args,
-                    prompts,
-                });
-                if (withContextDepth === 'back') {
-                    if (!canReturnToDriverSelection)
-                        return { status: 'back', projectDir: args.projectDir };
-                    returnToDriverSelection = true;
-                    break;
-                }
                 await writeConnectionConfig({
                     projectDir: args.projectDir,
                     connectionId: connectionChoice.connectionId,
-                    connection: withContextDepth,
+                    connection: withHistoricSql,
                     io,
                 });
             }
@@ -1719,23 +1676,10 @@ export async function runKtxSetupDatabasesStep(args, io, deps = {}) {
                     returnToDriverSelection = true;
                     break;
                 }
-                const withContextDepth = await maybeApplyContextDepthConfig({
-                    projectDir: args.projectDir,
-                    connectionId: connectionChoice.connectionId,
-                    connection: withHistoricSql,
-                    args,
-                    prompts,
-                });
-                if (withContextDepth === 'back') {
-                    if (!canReturnToDriverSelection)
-                        return { status: 'back', projectDir: args.projectDir };
-                    returnToDriverSelection = true;
-                    break;
-                }
                 await writeConnectionConfig({
                     projectDir: args.projectDir,
                     connectionId: connectionChoice.connectionId,
-                    connection: withContextDepth,
+                    connection: withHistoricSql,
                     io,
                 });
             }
@@ -1825,23 +1769,10 @@ export async function runKtxSetupDatabasesStep(args, io, deps = {}) {
                         returnToDriverSelection = true;
                         break;
                     }
-                    const withContextDepth = await maybeApplyContextDepthConfig({
-                        projectDir: args.projectDir,
-                        connectionId: connectionChoice.connectionId,
-                        connection: withHistoricSql,
-                        args,
-                        prompts,
-                    });
-                    if (withContextDepth === 'back') {
-                        if (!canReturnToDriverSelection)
-                            return { status: 'back', projectDir: args.projectDir };
-                        returnToDriverSelection = true;
-                        break;
-                    }
                     await writeConnectionConfig({
                         projectDir: args.projectDir,
                         connectionId: connectionChoice.connectionId,
-                        connection: withContextDepth,
+                        connection: withHistoricSql,
                         io,
                     });
                     setupStatus = await validateAndScanConnection({

package/dist/setup-sources.js

@@ -114,6 +114,31 @@ function credentialRef(value, label) {
     }
     return ref;
 }
+// Each connector reads exactly one credential ref; the flag name mirrors the
+// ktx.yaml field it writes (auth_token_ref / api_key_ref / client_secret_ref).
+const SOURCE_CREDENTIAL_FLAG = {
+    dbt: { field: 'sourceAuthTokenRef', flag: '--source-auth-token-ref' },
+    metricflow: { field: 'sourceAuthTokenRef', flag: '--source-auth-token-ref' },
+    lookml: { field: 'sourceAuthTokenRef', flag: '--source-auth-token-ref' },
+    notion: { field: 'sourceAuthTokenRef', flag: '--source-auth-token-ref' },
+    metabase: { field: 'sourceApiKeyRef', flag: '--source-api-key-ref' },
+    looker: { field: 'sourceClientSecretRef', flag: '--source-client-secret-ref' },
+};
+const ALL_SOURCE_CREDENTIAL_FLAGS = [
+    { field: 'sourceAuthTokenRef', flag: '--source-auth-token-ref' },
+    { field: 'sourceApiKeyRef', flag: '--source-api-key-ref' },
+    { field: 'sourceClientSecretRef', flag: '--source-client-secret-ref' },
+];
+// Reject a credential ref flag the chosen source does not read, so a wrong flag
+// fails loudly instead of being silently dropped (KLO-724).
+function assertSourceCredentialFlags(source, args) {
+    const allowed = SOURCE_CREDENTIAL_FLAG[source];
+    for (const { field, flag } of ALL_SOURCE_CREDENTIAL_FLAGS) {
+        if (args[field] && field !== allowed.field) {
+            throw new Error(`${flag} does not apply to --source ${source}; use ${allowed.flag}.`);
+        }
+    }
+}
 async function chooseSourceCredentialRef(input) {
     while (true) {
         const choice = await input.prompts.select({
@@ -385,7 +410,7 @@ function buildNotionConnection(args) {
     }
     return {
         driver: 'notion',
-        auth_token_ref: credentialRef(args.sourceApiKeyRef, 'Notion token ref'),
+        auth_token_ref: credentialRef(args.sourceAuthTokenRef, 'Notion token ref'),
         crawl_mode: crawlMode,
         ...(rootPageIds.length > 0 ? { root_page_ids: rootPageIds } : {}),
         root_database_ids: [],
@@ -1064,11 +1089,11 @@ async function promptForInteractiveSource(args, source, prompts, io, deps, defau
                 label: 'Notion integration token',
                 envName: 'NOTION_TOKEN',
                 secretFileName: `${currentState.sourceConnectionId ?? 'notion-main'}-token`,
-                existingRef: currentState.sourceApiKeyRef,
+                existingRef: currentState.sourceAuthTokenRef,
             });
             if (ref === 'back')
                 return 'back';
-            currentState.sourceApiKeyRef = ref;
+            currentState.sourceAuthTokenRef = ref;
             return 'next';
         },
         async (currentState) => {
@@ -1096,7 +1121,7 @@ async function promptForInteractiveSource(args, source, prompts, io, deps, defau
                         connectionId,
                         connection: {
                             driver: 'notion',
-                            auth_token_ref: credentialRef(currentState.sourceApiKeyRef, 'Notion token ref'),
+                            auth_token_ref: credentialRef(currentState.sourceAuthTokenRef, 'Notion token ref'),
                             crawl_mode: 'selected_roots',
                             root_page_ids: currentState.notionRootPageIds ?? [],
                             root_database_ids: [],
@@ -1260,7 +1285,7 @@ function sourceArgsFromExistingConnection(input) {
         }
         return sourceArgs;
     }
-    sourceArgs.sourceApiKeyRef = stringField(input.connection.auth_token_ref);
+    sourceArgs.sourceAuthTokenRef = stringField(input.connection.auth_token_ref);
     sourceArgs.notionCrawlMode =
         input.connection.crawl_mode === 'all_accessible' ? 'all_accessible' : 'selected_roots';
     if (Array.isArray(input.connection.root_page_ids)) {
@@ -1467,6 +1492,9 @@ export async function runKtxSetupSourcesStep(args, io, deps = {}) {
             io.stdout.write('│  Context source setup skipped.\n');
             return { status: 'skipped', projectDir: args.projectDir };
         }
+        if (args.source) {
+            assertSourceCredentialFlags(args.source, args);
+        }
         const prompts = deps.prompts ?? createPromptAdapter();
         const project = await loadKtxProject({ projectDir: args.projectDir });
         if (!hasPrimarySource(project.config)) {

package/dist/setup.js

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
 import { getLatestLocalIngestStatus } from './context/ingest/local-ingest.js';
-import { savedMemoryCountsForReport } from './context/ingest/reports.js';
+import { ingestReportOutcome, savedMemoryCountsForReport } from './context/ingest/reports.js';
 import { ktxLocalStateDbPath } from './context/project/local-state-db.js';
 import { loadKtxProject } from './context/project/project.js';
 import { readKtxSetupState } from './context/project/setup-config.js';
@@ -105,7 +105,7 @@ function sourceConnections(config) {
         .sort((left, right) => left.connectionId.localeCompare(right.connectionId));
 }
 function reportHasSavedContext(report) {
-    if (report.body.failedWorkUnits.length > 0) {
+    if (ingestReportOutcome(report) === 'error') {
         return false;
     }
     const counts = savedMemoryCountsForReport(report);

package/dist/skills/analytics/SKILL.md

@@ -28,7 +28,12 @@ You have access to KTX MCP tools for data discovery, semantic-layer analysis, ra
 - Read entity details before writing SQL against an unfamiliar table. Do not assume column names.
 - Treat `sql_execution` as read-only. Writes are rejected by the server.
 - Validate value mentions with `dictionary_search` instead of guessing case or spelling. Treat a `dictionary_search` miss as non-authoritative. The index is built from profile-sampled values, so a missing value may simply have been outside the sample. Follow up with `sql_execution` against the most plausible columns before concluding the value is absent.
-- When `connection_list` shows multiple connections, pass an explicit `connectionId` to every tool that takes one and where user intent pins a specific warehouse. Required: `entity_details`, `sl_read_source`, and `sql_execution`. Required when user intent is warehouse-specific, including wording like "in our warehouse" or "this warehouse": `memory_ingest`; without `connectionId`, the memory agent cannot update the semantic layer and the knowledge lands as wiki-only. Pass `connectionId` when intent pins a warehouse, otherwise omit for unscoped discovery: `sl_query`, `discover_data`, and `dictionary_search`. Never pass `connectionId` to `connection_list`, `wiki_search`, `wiki_read`, or `memory_ingest_status`. If intent is ambiguous for a required-or-scoped tool, ask the user which warehouse before calling.
+- `connectionId` scoping when `connection_list` shows multiple connections:
+  - Always pass it: `entity_details`, `sl_read_source`, `sql_execution`.
+  - Pass it when intent pins a warehouse, otherwise omit for unscoped discovery: `sl_query`, `discover_data`, `dictionary_search`.
+  - `memory_ingest`: pass it for warehouse-specific knowledge (e.g. "in our warehouse"); without it the memory lands as wiki-only and cannot update the semantic layer.
+  - Never pass it: `connection_list`, `wiki_search`, `wiki_read`, `memory_ingest_status`.
+  - If scoping is required but intent is ambiguous, ask which warehouse before calling.
 - Show compact result tables for small outputs. For broad results, summarize the top findings and mention the applied limit.
 - Ask a concise clarification only when the metric, date range, entity, or grain is genuinely ambiguous and cannot be inferred from context.
 </rules>

package/dist/sl.d.ts

@@ -23,10 +23,15 @@ export type KtxSlArgs = {
     output?: string;
     json?: boolean;
     cliVersion: string;
+} | {
+    command: 'read';
+    projectDir: string;
+    connectionId?: string;
+    sourceName: string;
 } | {
     command: 'validate';
     projectDir: string;
-    connectionId: string;
+    connectionId?: string;
     sourceName: string;
 } | {
     command: 'query';

package/dist/sl.js

@@ -3,7 +3,7 @@ import { createDefaultLocalQueryExecutor } from './context/connections/local-que
 import { KtxIngestEmbeddingPortAdapter } from './context/llm/embedding-port.js';
 import { loadKtxProject } from './context/project/project.js';
 import { compileLocalSlQuery } from './context/sl/local-query.js';
-import { listLocalSlSources, readLocalSlSource, searchLocalSlSources as defaultSearchLocalSlSources, validateLocalSlSource } from './context/sl/local-sl.js';
+import { listLocalSlSources, resolveLocalSlSource, searchLocalSlSources as defaultSearchLocalSlSources, validateLocalSlSource, } from './context/sl/local-sl.js';
 import { resolveProjectEmbeddingProvider, } from './embedding-resolution.js';
 import { createManagedPythonSemanticLayerComputePort, } from './managed-python-command.js';
 import { profileMark } from './startup-profile.js';
@@ -85,6 +85,9 @@ async function readSlQueryFile(path) {
     }
     return parsed;
 }
+function ambiguousSourceMessage(sourceName, connectionIds) {
+    return `Source '${sourceName}' exists in multiple connections: ${connectionIds.join(', ')}. Re-run with --connection-id <id>.`;
+}
 export async function runKtxSl(args, io = process, deps = {}) {
     const startedAt = performance.now();
     let queryForTelemetry;
@@ -132,17 +135,38 @@ export async function runKtxSl(args, io = process, deps = {}) {
             });
             return 0;
         }
+        if (args.command === 'read') {
+            const resolved = await resolveLocalSlSource(project, {
+                connectionId: args.connectionId,
+                sourceName: args.sourceName,
+            });
+            if (resolved.kind === 'not-found') {
+                throw new Error(args.connectionId !== undefined
+                    ? `No semantic-layer source '${args.sourceName}' for connection '${args.connectionId}'`
+                    : `No semantic-layer source '${args.sourceName}'`);
+            }
+            if (resolved.kind === 'ambiguous') {
+                throw new Error(ambiguousSourceMessage(args.sourceName, resolved.connectionIds));
+            }
+            io.stdout.write(resolved.source.yaml);
+            return 0;
+        }
         if (args.command === 'validate') {
-            const source = await readLocalSlSource(project, {
+            const resolved = await resolveLocalSlSource(project, {
                 connectionId: args.connectionId,
                 sourceName: args.sourceName,
             });
-            if (!source) {
-                throw new Error(`Semantic-layer source "${args.connectionId}/${args.sourceName}" was not found`);
+            if (resolved.kind === 'not-found') {
+                throw new Error(args.connectionId !== undefined
+                    ? `Semantic-layer source "${args.connectionId}/${args.sourceName}" was not found`
+                    : `Semantic-layer source "${args.sourceName}" was not found`);
             }
-            const result = await validateLocalSlSource(source.yaml, {
+            if (resolved.kind === 'ambiguous') {
+                throw new Error(ambiguousSourceMessage(args.sourceName, resolved.connectionIds));
+            }
+            const result = await validateLocalSlSource(resolved.source.yaml, {
                 project,
-                connectionId: args.connectionId,
+                connectionId: resolved.source.connectionId,
                 sourceName: args.sourceName,
             });
             await emitTelemetryEvent({
@@ -150,7 +174,7 @@ export async function runKtxSl(args, io = process, deps = {}) {
                 projectDir: args.projectDir,
                 io,
                 fields: {
-                    sourceCount: source ? 1 : 0,
+                    sourceCount: 1,
                     modelCount: 0,
                     validationErrorCount: result.valid ? 0 : result.errors.length,
                     outcome: result.valid ? 'ok' : 'error',
@@ -163,7 +187,7 @@ export async function runKtxSl(args, io = process, deps = {}) {
                 }
                 return 1;
             }
-            io.stdout.write(`Valid semantic-layer source: ${args.connectionId}/${args.sourceName}\n`);
+            io.stdout.write(`Valid semantic-layer source: ${resolved.source.connectionId}/${args.sourceName}\n`);
             return 0;
         }
         if (args.command === 'query') {

package/dist/telemetry/emitter.js

@@ -17,7 +17,7 @@ async function getPostHogClient(projectApiKey, host) {
         return null;
     }
     clientPromise ??= import('posthog-node')
-        .then(({ PostHog }) => new PostHog(projectApiKey, { host, flushAt: 1, flushInterval: 0 }))
+        .then(({ PostHog }) => new PostHog(projectApiKey, { host, flushAt: 1, flushInterval: 0, disableGeoip: false }))
         .catch(() => null);
     return await clientPromise;
 }

package/dist/telemetry/events.d.ts

@@ -69,7 +69,6 @@ export declare const telemetryEventSchemas: {
             runtime: "runtime";
             agents: "agents";
             secrets: "secrets";
-            "database-context-depth": "database-context-depth";
             "demo-tour": "demo-tour";
         }>;
         outcome: z.ZodEnum<{
@@ -299,7 +298,9 @@ export declare const telemetryEventSchemas: {
         }>;
         durationMs: z.ZodNumber;
         errorClass: z.ZodOptional<z.ZodString>;
-        sampleRate: z.ZodLiteral<0.1>;
+        sampleRate: z.ZodLiteral<1>;
+        mcpClientName: z.ZodOptional<z.ZodString>;
+        mcpClientVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
     readonly daemon_started: z.ZodObject<{
         cliVersion: z.ZodString;
@@ -433,7 +434,7 @@ export declare const telemetryEventCatalog: readonly [{
 }, {
     readonly name: "mcp_request_completed";
     readonly description: "Emitted for sampled MCP tool requests.";
-    readonly fields: readonly ["toolName", "outcome", "durationMs", "errorClass", "sampleRate"];
+    readonly fields: readonly ["toolName", "outcome", "durationMs", "errorClass", "sampleRate", "mcpClientName", "mcpClientVersion"];
 }, {
     readonly name: "daemon_started";
     readonly description: "Emitted when the long-lived ktx-daemon HTTP server starts.";

package/dist/telemetry/events.js

@@ -33,7 +33,6 @@ const setupStepSchema = telemetryCommonEnvelopeSchema
         'embeddings',
         'secrets',
         'databases',
-        'database-context-depth',
         'sources',
         'context',
         'agents',
@@ -141,7 +140,12 @@ const mcpRequestCompletedSchema = telemetryCommonEnvelopeSchema
     outcome: outcomeSchema,
     durationMs: z.number().nonnegative(),
     errorClass: z.string().optional(),
-    sampleRate: z.literal(0.1),
+    sampleRate: z.literal(1),
+    // Raw, client-tool-controlled identity from the MCP initialize handshake
+    // (clientInfo.name/version). Optional: clients may omit clientInfo. Stored
+    // verbatim — normalize the free-form names at query time, not at write time.
+    mcpClientName: z.string().optional(),
+    mcpClientVersion: z.string().optional(),
 })
     .strict();
 const daemonStartedSchema = telemetryCommonEnvelopeSchema
@@ -304,7 +308,7 @@ export const telemetryEventCatalog = [
     {
         name: 'mcp_request_completed',
         description: 'Emitted for sampled MCP tool requests.',
-        fields: ['toolName', 'outcome', 'durationMs', 'errorClass', 'sampleRate'],
+        fields: ['toolName', 'outcome', 'durationMs', 'errorClass', 'sampleRate', 'mcpClientName', 'mcpClientVersion'],
     },
     {
         name: 'daemon_started',

package/dist/telemetry/identity.d.ts

@@ -1,5 +1,5 @@
 /** @internal */
-export declare const TELEMETRY_NOTICE = "ktx collects anonymous usage data to improve the product. Opt out: set KTX_TELEMETRY_DISABLED=1.";
+export declare const TELEMETRY_NOTICE = "ktx collects usage data to improve the product. Opt out: set KTX_TELEMETRY_DISABLED=1.";
 /** @internal */
 export interface TelemetryIdentityEnv {
     KTX_TELEMETRY_DISABLED?: string;

package/dist/telemetry/identity.js

@@ -4,7 +4,7 @@ import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { z } from 'zod';
 /** @internal */
-export const TELEMETRY_NOTICE = 'ktx collects anonymous usage data to improve the product. Opt out: set KTX_TELEMETRY_DISABLED=1.';
+export const TELEMETRY_NOTICE = 'ktx collects usage data to improve the product. Opt out: set KTX_TELEMETRY_DISABLED=1.';
 const NOTICE_VERSION = 1;
 const telemetryFileSchema = z
     .object({
@@ -41,16 +41,13 @@ async function writeTelemetryFile(path, value) {
 export async function loadTelemetryIdentity(options) {
     const env = options.env ?? process.env;
     const path = telemetryPath(options.homeDir ?? homedir());
-    if (envDisablesTelemetry(env) || options.stdoutIsTTY !== true) {
-        const existing = await readTelemetryFile(path);
-        return {
-            installId: existing?.installId,
-            enabled: false,
-            createdFile: false,
-            noticeShown: false,
-            path,
-        };
+    if (envDisablesTelemetry(env)) {
+        return { enabled: false, createdFile: false, noticeShown: false, path };
     }
+    // Honor an already-consented identity regardless of the current surface.
+    // Telemetry enablement follows the persisted decision and opt-out env vars,
+    // not whether this invocation happens to own a TTY — MCP servers always run
+    // headless (stdio stubs stdout; the HTTP server runs detached).
     const existing = await readTelemetryFile(path);
     if (existing) {
         return {
@@ -61,6 +58,12 @@ export async function loadTelemetryIdentity(options) {
             path,
         };
     }
+    // No identity yet. Minting one means showing the one-time opt-out notice, so
+    // first-run creation requires an interactive surface; a headless first run
+    // stays disabled and defers enablement until the next interactive run.
+    if (options.stdoutIsTTY !== true) {
+        return { enabled: false, createdFile: false, noticeShown: false, path };
+    }
     const timestamp = (options.now ?? (() => new Date()))().toISOString();
     const next = {
         installId: randomUUID(),

package/dist/telemetry/index.d.ts

@@ -7,7 +7,7 @@ export type { CommandOutcome, CompletedCommandSpan };
 export declare function showTelemetryNoticeIfNeeded(io: KtxCliIo, packageInfo: KtxCliPackageInfo): Promise<void>;
 type TelemetryEventFields<Name extends TelemetryEventName> = Omit<TelemetryEventProperties<Name>, keyof TelemetryCommonEnvelope>;
 export declare function shouldEmitMcpTelemetry(): boolean;
-export declare function mcpTelemetrySampleRate(): 0.1;
+export declare function mcpTelemetrySampleRate(): 1;
 export declare function emitTelemetryEvent<Name extends TelemetryEventName>(input: {
     name: Name;
     fields: TelemetryEventFields<Name>;

package/dist/telemetry/index.js

@@ -26,7 +26,11 @@ export async function showTelemetryNoticeIfNeeded(io, packageInfo) {
     });
 }
 const emittedProjectSnapshots = new Set();
-const MCP_SAMPLE_RATE = 0.1;
+// MCP tool calls are captured at full rate while ktx is early-stage: at current
+// install counts any sampling below 1.0 yields too few events to be useful, and
+// the recorded sampleRate lets us dial this down (and reweight history) once
+// per-session call volume justifies it.
+const MCP_SAMPLE_RATE = 1;
 let mcpSampled;
 function telemetryDebugEnabled() {
     return process.env.KTX_TELEMETRY_DEBUG === '1';