@kaelio/ktx 0.7.0 → 0.9.0

package/dist/setup-models.d.ts

@@ -39,7 +39,7 @@ export interface AnthropicModelChoice {
     label: string;
     recommended: boolean;
 }
-export type KtxSetupLlmBackend = 'anthropic' | 'vertex' | 'claude-code';
+export type KtxSetupLlmBackend = 'anthropic' | 'vertex' | 'claude-code' | 'codex';
 /** @internal */
 export interface KtxSetupModelPromptAdapter {
     select(options: {
@@ -76,6 +76,15 @@ export interface KtxSetupModelDeps {
         ok: false;
         message: string;
     }>;
+    codexAuthProbe?: (input: {
+        projectDir: string;
+        model: string;
+    }) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    }>;
     readGcloudProject?: () => Promise<string | undefined>;
     listGcloudProjects?: () => Promise<GcloudProjectChoice[]>;
     spinner?: () => KtxCliSpinner;

package/dist/setup-models.js

@@ -3,6 +3,9 @@ import { writeFile } from 'node:fs/promises';
 import { promisify } from 'node:util';
 import { resolveLocalKtxLlmConfig } from './context/llm/local-config.js';
 import { runClaudeCodeAuthProbe } from './context/llm/claude-code-runtime.js';
+import { formatCodexIsolationWarning } from './context/llm/codex-isolation.js';
+import { runCodexAuthProbe } from './context/llm/codex-runtime.js';
+import { DEFAULT_CODEX_MODEL } from './context/llm/codex-models.js';
 import { resolveKtxConfigReference } from './context/core/config-reference.js';
 import { serializeKtxProjectConfig } from './context/project/config.js';
 import { loadKtxProject } from './context/project/project.js';
@@ -37,6 +40,19 @@ const CLAUDE_CODE_MODELS = [
     { id: 'opus', label: 'Claude Opus', recommended: false },
     { id: 'haiku', label: 'Claude Haiku', recommended: false },
 ];
+// Curated Codex models from OpenAI's current lineup that work under both
+// ChatGPT-account (subscription) and API-key auth. Intentionally omitted:
+// the `*-codex` ids (e.g. gpt-5.3-codex, gpt-5.2-codex) are API-key-only and
+// fail on ChatGPT-account auth, and gpt-5.3-codex-spark is a ChatGPT-Pro-only
+// research preview. Codex resolves real availability per account at runtime
+// (its binary remote-fetches the model list), so this is a convenience
+// shortlist only — the manual-entry option accepts any id your account's
+// `codex` picker exposes, and the auth probe reports an unsupported choice.
+const CODEX_MODELS = [
+    { id: 'gpt-5.5', label: 'GPT-5.5', recommended: true },
+    { id: 'gpt-5.4', label: 'GPT-5.4', recommended: false },
+    { id: 'gpt-5.4-mini', label: 'GPT-5.4 mini', recommended: false },
+];
 const HIDDEN_ANTHROPIC_MODEL_PATTERNS = [
     /^claude-sonnet-4$/i,
     /^claude-opus-4$/i,
@@ -149,7 +165,10 @@ export function isKtxSetupLlmConfigReady(config) {
     if (resolved.backend === 'vertex') {
         return typeof resolved.vertex?.location === 'string' && resolved.vertex.location.trim().length > 0;
     }
-    return resolved.backend === 'anthropic' || resolved.backend === 'gateway' || resolved.backend === 'claude-code';
+    return (resolved.backend === 'anthropic' ||
+        resolved.backend === 'gateway' ||
+        resolved.backend === 'claude-code' ||
+        resolved.backend === 'codex');
 }
 function hasUsableConfiguredLlm(config) {
     return isKtxSetupLlmConfigReady(config.llm);
@@ -162,6 +181,13 @@ function buildProjectLlmConfig(existing, provider, model) {
             promptCaching: existing.promptCaching,
         };
     }
+    if (provider.backend === 'codex') {
+        return {
+            provider: { backend: 'codex' },
+            models: { ...existing.models, default: model },
+            promptCaching: existing.promptCaching,
+        };
+    }
     if (provider.backend === 'vertex') {
         return {
             provider: {
@@ -340,6 +366,7 @@ async function chooseBackend(args, io, deps) {
         message: 'Which LLM provider should KTX use?',
         options: [
             { value: 'claude-code', label: 'Claude subscription (Pro/Max)' },
+            { value: 'codex', label: 'Codex subscription' },
             { value: 'anthropic', label: 'Anthropic API key' },
             { value: 'vertex', label: 'Google Vertex AI for Anthropic Claude' },
             { value: 'back', label: 'Back' },
@@ -350,7 +377,7 @@ async function chooseBackend(args, io, deps) {
     }
     return {
         status: 'ready',
-        backend: choice === 'vertex' || choice === 'claude-code' ? choice : 'anthropic',
+        backend: choice === 'vertex' || choice === 'claude-code' || choice === 'codex' ? choice : 'anthropic',
         prompted: true,
     };
 }
@@ -671,6 +698,42 @@ async function chooseClaudeCodeModel(args, deps) {
     }
     return { status: 'ready', model: choice };
 }
+async function chooseCodexModel(args, deps) {
+    const providedModel = requestedModel(args);
+    if (providedModel) {
+        return { status: 'ready', model: providedModel };
+    }
+    if (args.inputMode === 'disabled') {
+        return { status: 'ready', model: DEFAULT_CODEX_MODEL };
+    }
+    const prompts = deps.prompts ?? createPromptAdapter();
+    const choice = await prompts.select({
+        message: `Which Codex model should KTX use?\n\n${ANTHROPIC_MODEL_PROMPT_CONTEXT}`,
+        options: [
+            ...CODEX_MODELS.map((model) => ({
+                value: model.id,
+                label: model.label,
+                ...(model.recommended ? { hint: 'recommended' } : {}),
+            })),
+            { value: 'manual', label: 'Enter a Codex model ID manually' },
+            { value: 'back', label: 'Back' },
+        ],
+    });
+    if (choice === 'back') {
+        return { status: 'back' };
+    }
+    if (choice === 'manual') {
+        const manual = await prompts.text({
+            message: withTextInputNavigation('Codex model ID'),
+            placeholder: CODEX_MODELS.find((model) => model.recommended)?.id ?? CODEX_MODELS[0]?.id,
+        });
+        if (manual === undefined) {
+            return { status: 'back' };
+        }
+        return manual.trim() ? { status: 'ready', model: manual.trim() } : { status: 'missing-input' };
+    }
+    return { status: 'ready', model: choice };
+}
 async function persistLlmConfig(projectDir, provider, model) {
     const project = await loadKtxProject({ projectDir });
     const config = {
@@ -783,6 +846,31 @@ export async function runKtxSetupAnthropicModelStep(args, io, deps = {}) {
             io.stdout.write(`│  LLM ready: yes (${model.model})\n`);
             return { status: 'ready', projectDir: args.projectDir };
         }
+        if (backendChoice.backend === 'codex') {
+            const model = await chooseCodexModel(backendArgs, deps);
+            if (model.status === 'back' && backendChoice.prompted) {
+                attemptArgs = buildInteractiveRetryArgs(args);
+                continue;
+            }
+            if (model.status === 'invalid-credential') {
+                return { status: 'failed', projectDir: args.projectDir };
+            }
+            if (model.status !== 'ready') {
+                return { status: model.status, projectDir: args.projectDir };
+            }
+            const probe = deps.codexAuthProbe ?? runCodexAuthProbe;
+            const health = await probe({ projectDir: args.projectDir, model: model.model });
+            if (!health.ok) {
+                io.stderr.write(`${health.message}\n`);
+                return { status: 'failed', projectDir: args.projectDir };
+            }
+            // Prefix the clack gutter so the warning sits inside the setup frame
+            // instead of breaking out of it; kept on stderr for scripted runs.
+            io.stderr.write(`│  ${formatCodexIsolationWarning()}\n`);
+            await persistLlmConfig(args.projectDir, { backend: 'codex' }, model.model);
+            io.stdout.write(`│  LLM ready: yes (codex, ${model.model})\n`);
+            return { status: 'ready', projectDir: args.projectDir };
+        }
         const credential = await chooseCredentialRef(backendArgs, io, deps);
         if (credential.status === 'back' && backendChoice.prompted) {
             attemptArgs = buildInteractiveRetryArgs(args);

package/dist/setup-ready-menu.d.ts

@@ -1,6 +1,11 @@
 import { type KtxSetupPromptOption } from './setup-prompts.js';
 import type { KtxSetupStatus } from './setup.js';
 export type KtxSetupReadyAction = 'models' | 'embeddings' | 'databases' | 'sources' | 'runtime' | 'context' | 'agents' | 'exit';
+/**
+ * Where a project stands once its `ktx.yaml` exists. Single source of truth for the
+ * end-of-setup interception: each state maps to exactly one obvious next action.
+ */
+export type KtxSetupCompletion = 'incomplete' | 'needs-context' | 'needs-agents' | 'ready';
 interface KtxSetupReadyMenuPromptAdapter {
     select(options: {
         message: string;
@@ -11,8 +16,17 @@ interface KtxSetupReadyMenuPromptAdapter {
 export interface KtxSetupReadyMenuDeps {
     prompts?: KtxSetupReadyMenuPromptAdapter;
 }
-export declare function isKtxPreAgentSetupReady(status: KtxSetupStatus): boolean;
-export declare function isKtxSetupReady(status: KtxSetupStatus): boolean;
+export declare function setupHasContextTargets(status: KtxSetupStatus): boolean;
+export declare function classifyKtxSetupCompletion(status: KtxSetupStatus): KtxSetupCompletion;
+/**
+ * Shown when a returning user re-runs `ktx setup` on a fully-ready project. Leads with
+ * "you're done" (the readiness note is printed by the caller first) and keeps the
+ * section editor one explicit step away rather than defaulting into it.
+ */
+export declare function runKtxSetupReadyMenu(status: KtxSetupStatus, deps?: KtxSetupReadyMenuDeps): Promise<{
+    action: KtxSetupReadyAction;
+}>;
+/** @internal Reached only through {@link runKtxSetupReadyMenu}; exported for unit tests. */
 export declare function runKtxSetupReadyChangeMenu(status: KtxSetupStatus, deps?: KtxSetupReadyMenuDeps): Promise<{
     action: KtxSetupReadyAction;
 }>;

package/dist/setup-ready-menu.js

@@ -1,23 +1,55 @@
 import { createKtxSetupPromptAdapter, } from './setup-prompts.js';
-export function isKtxPreAgentSetupReady(status) {
+export function setupHasContextTargets(status) {
+    return status.databases.length > 0 || status.sources.length > 0;
+}
+function setupConfigReady(status) {
     return (status.project.ready &&
         status.llm.ready &&
         status.embeddings.ready &&
         status.databases.every((database) => database.ready) &&
         status.sources.every((source) => source.ready) &&
         status.runtime.ready &&
-        status.context.ready);
+        setupHasContextTargets(status));
 }
-export function isKtxSetupReady(status) {
-    return isKtxPreAgentSetupReady(status) && status.agents.some((agent) => agent.ready);
+export function classifyKtxSetupCompletion(status) {
+    if (!setupConfigReady(status)) {
+        return 'incomplete';
+    }
+    if (!status.context.ready) {
+        return 'needs-context';
+    }
+    if (!status.agents.some((agent) => agent.ready)) {
+        return 'needs-agents';
+    }
+    return 'ready';
 }
 function createPromptAdapter() {
     return createKtxSetupPromptAdapter({ selectCancelValue: 'exit' });
 }
+/**
+ * Shown when a returning user re-runs `ktx setup` on a fully-ready project. Leads with
+ * "you're done" (the readiness note is printed by the caller first) and keeps the
+ * section editor one explicit step away rather than defaulting into it.
+ */
+export async function runKtxSetupReadyMenu(status, deps = {}) {
+    const prompts = deps.prompts ?? createPromptAdapter();
+    const choice = await prompts.select({
+        message: 'Anything else?',
+        options: [
+            { value: 'done', label: "Done — I'll start using ktx" },
+            { value: 'change', label: 'Change a setting' },
+        ],
+    });
+    if (choice !== 'change') {
+        return { action: 'exit' };
+    }
+    return runKtxSetupReadyChangeMenu(status, { prompts });
+}
+/** @internal Reached only through {@link runKtxSetupReadyMenu}; exported for unit tests. */
 export async function runKtxSetupReadyChangeMenu(status, deps = {}) {
     const prompts = deps.prompts ?? createPromptAdapter();
     const action = (await prompts.select({
-        message: `KTX is already set up for ${status.project.name ?? status.project.path}. What would you like to change?`,
+        message: 'What would you like to change?',
         options: [
             { value: 'models', label: 'Models' },
             { value: 'embeddings', label: 'Embeddings' },

package/dist/setup-sources.js

@@ -19,6 +19,7 @@ import { markKtxSetupStateStepComplete } from './context/project/setup-config.js
 import { errorMessage, writePrefixedLines } from './clack.js';
 import { pickNotionRootPages } from './notion-page-picker.js';
 import { runKtxSourceMapping } from './source-mapping.js';
+import { runConnectionSetupWithRecovery, } from './connection-recovery.js';
 import { withMultiselectNavigation, withTextInputNavigation } from './prompt-navigation.js';
 import { runKtxPublicIngest } from './public-ingest.js';
 import { writeProjectLocalSecretReference } from './setup-secrets.js';
@@ -114,6 +115,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 +411,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 +1090,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 +1122,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 +1286,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)) {
@@ -1409,56 +1435,125 @@ async function validateSource(source, args, deps) {
     }
     return await (deps.validateNotion ?? defaultValidateNotion)(args.connection);
 }
-async function saveValidateAndMaybeBuildSource(input) {
-    const connectionId = input.sourceChoice.kind === 'existing'
+async function createSourceSetupRollback(projectDir) {
+    const project = await loadKtxProject({ projectDir });
+    const previousConfig = project.config;
+    const configPath = project.configPath;
+    return async () => {
+        await writeFile(configPath, serializeKtxProjectConfig(previousConfig), 'utf-8');
+    };
+}
+function sourceConnectionId(input) {
+    return input.sourceChoice.kind === 'existing' || input.sourceChoice.kind === 'edited'
         ? input.sourceChoice.connectionId
-        : input.sourceChoice.kind === 'edited'
-            ? input.sourceChoice.connectionId
-            : (input.sourceChoice.args.sourceConnectionId ?? `${input.source}-main`);
-    const connection = input.sourceChoice.kind === 'existing'
-        ? input.sourceChoice.connection
-        : buildConnection(input.source, input.sourceChoice.args);
-    const rollback = input.sourceChoice.kind === 'existing'
-        ? undefined
-        : await writeSourceConnection(input.args.projectDir, connectionId, connection, sourceAdapter(input.source), input.io);
-    if (input.sourceChoice.kind === 'existing') {
-        await ensureSourceAdapterEnabled(input.args.projectDir, input.source);
-    }
-    const validation = await validateSource(input.source, { projectDir: input.args.projectDir, connectionId, connection }, input.deps);
+        : (input.sourceChoice.args.sourceConnectionId ?? `${input.source}-main`);
+}
+async function validateSourceConnectionAndMapping(input) {
+    const validation = await validateSource(input.source, { projectDir: input.args.projectDir, connectionId: input.connectionId, connection: input.connection }, input.deps);
     if (!validation.ok) {
-        await rollback?.();
         input.io.stderr.write(`${validation.message}\n`);
         return { status: 'failed' };
     }
     if (input.source === 'metabase' || input.source === 'looker') {
-        input.prompts.log?.(`Validating ${sourceLabel(input.source)} mapping…`);
-        const mappingCode = await (input.deps.runMapping ?? defaultRunMapping)(input.args.projectDir, connectionId, createSetupPrefixedIo(input.io));
+        input.prompts.log?.(`Validating ${sourceLabel(input.source)} mapping...`);
+        const mappingCode = await (input.deps.runMapping ?? defaultRunMapping)(input.args.projectDir, input.connectionId, createSetupPrefixedIo(input.io));
         if (mappingCode !== 0) {
-            await rollback?.();
             return { status: 'failed' };
         }
     }
+    return { status: 'ok' };
+}
+async function saveValidateAndMaybeBuildSource(input) {
+    let latestChoice = input.sourceChoice;
+    let latestConnectionId = sourceConnectionId({ source: input.source, sourceChoice: latestChoice });
+    let latestConnection = latestChoice.kind === 'existing'
+        ? latestChoice.connection
+        : buildConnection(input.source, latestChoice.args);
+    let configureCount = 0;
+    let rollbackAfterConfigure;
+    const outcome = await runConnectionSetupWithRecovery({
+        label: latestConnectionId,
+        interactive: input.args.inputMode !== 'disabled',
+        allowSkip: true,
+        io: input.io,
+        prompts: input.prompts,
+        snapshot: async () => {
+            rollbackAfterConfigure = await createSourceSetupRollback(input.args.projectDir);
+            return rollbackAfterConfigure;
+        },
+        configure: async () => {
+            configureCount += 1;
+            if (latestChoice.kind === 'existing' && configureCount === 1) {
+                await ensureSourceAdapterEnabled(input.args.projectDir, input.source);
+                return 'configured';
+            }
+            const project = await loadKtxProject({ projectDir: input.args.projectDir });
+            const currentConnection = project.config.connections[latestConnectionId] ?? latestConnection;
+            const useAlreadyPromptedArgs = configureCount === 1 && latestChoice.kind !== 'existing';
+            const sourceArgs = useAlreadyPromptedArgs && latestChoice.kind !== 'existing'
+                ? latestChoice.args
+                : input.args.inputMode === 'disabled'
+                    ? sourceArgsFromExistingConnection({
+                        args: input.args,
+                        source: input.source,
+                        connectionId: latestConnectionId,
+                        connection: currentConnection,
+                    })
+                    : await promptForInteractiveSource(sourceArgsFromExistingConnection({
+                        args: input.args,
+                        source: input.source,
+                        connectionId: latestConnectionId,
+                        connection: currentConnection,
+                    }), input.source, input.prompts, input.io, {
+                        pickNotionRootPages: input.deps.pickNotionRootPages,
+                        discoverMetabaseDatabases: input.deps.discoverMetabaseDatabases,
+                    }, latestConnectionId, input.deps.testGitRepo, input.deps.discoverMetabaseDatabases);
+            if (sourceArgs === 'back') {
+                return 'back';
+            }
+            latestConnectionId = sourceArgs.sourceConnectionId ?? latestConnectionId;
+            latestConnection = buildConnection(input.source, sourceArgs);
+            latestChoice =
+                latestChoice.kind === 'new'
+                    ? { kind: 'new', args: sourceArgs }
+                    : { kind: 'edited', connectionId: latestConnectionId, args: sourceArgs };
+            await writeSourceConnection(input.args.projectDir, latestConnectionId, latestConnection, sourceAdapter(input.source), input.io);
+            return 'configured';
+        },
+        validate: () => validateSourceConnectionAndMapping({
+            args: input.args,
+            source: input.source,
+            connectionId: latestConnectionId,
+            connection: latestConnection,
+            prompts: input.prompts,
+            io: input.io,
+            deps: input.deps,
+        }),
+    });
+    if (outcome !== 'ready') {
+        return { status: outcome };
+    }
     if (input.args.runInitialSourceIngest) {
         const ingestResult = await runInitialSourceIngestWithRecovery({
             args: input.args,
-            connectionId,
+            connectionId: latestConnectionId,
             io: input.io,
             prompts: input.prompts,
             deps: input.deps,
         });
         if (ingestResult === 'failed') {
-            await rollback?.();
+            await rollbackAfterConfigure?.();
             return { status: 'failed' };
         }
         if (ingestResult === 'back') {
-            await rollback?.();
+            await rollbackAfterConfigure?.();
             return { status: 'back' };
         }
     }
     else {
-        input.io.stdout.write(`│  Context source ${connectionId} saved. It will be built during the context build step.\n`);
+        input.io.stdout.write(`│  Context source ${latestConnectionId} saved. It will be built during the context build step.\n`);
     }
-    return { status: 'ready', connectionId };
+    return { status: 'ready', connectionId: latestConnectionId };
 }
 export async function runKtxSetupSourcesStep(args, io, deps = {}) {
     try {
@@ -1467,6 +1562,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)) {
@@ -1551,8 +1649,13 @@ export async function runKtxSetupSourcesStep(args, io, deps = {}) {
                     returnToSourceSelection = true;
                     break;
                 }
-                if (!readyConnectionIds.includes(choiceResult.connectionId)) {
-                    readyConnectionIds.push(choiceResult.connectionId);
+                if (choiceResult.status === 'skip') {
+                    continue;
+                }
+                if (choiceResult.status === 'ready') {
+                    if (!readyConnectionIds.includes(choiceResult.connectionId)) {
+                        readyConnectionIds.push(choiceResult.connectionId);
+                    }
                 }
             }
             if (returnToSourceSelection) {
@@ -1612,8 +1715,13 @@ export async function runKtxSetupSourcesStep(args, io, deps = {}) {
                         if (choiceResult.status === 'back') {
                             continue;
                         }
-                        if (!readyConnectionIds.includes(choiceResult.connectionId)) {
-                            readyConnectionIds.push(choiceResult.connectionId);
+                        if (choiceResult.status === 'skip') {
+                            continue;
+                        }
+                        if (choiceResult.status === 'ready') {
+                            if (!readyConnectionIds.includes(choiceResult.connectionId)) {
+                                readyConnectionIds.push(choiceResult.connectionId);
+                            }
                         }
                         continue;
                     }

package/dist/setup.js

@@ -1,12 +1,12 @@
 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';
 import { getKtxCliPackageInfo } from './cli-runtime.js';
-import { formatSetupNextStepLines } from './next-steps.js';
+import { formatNextStepLines, formatSetupNextStepLines } from './next-steps.js';
 import { runtimeInstallPolicyFromFlags } from './managed-python-command.js';
 import { readManagedPythonRuntimeStatus } from './managed-python-runtime.js';
 import { resolveProjectRuntimeRequirements } from './runtime-requirements.js';
@@ -16,7 +16,7 @@ import { runKtxSetupDatabasesStep, } from './setup-databases.js';
 import { runKtxSetupEmbeddingsStep } from './setup-embeddings.js';
 import { isKtxSetupLlmConfigReady, runKtxSetupAnthropicModelStep, } from './setup-models.js';
 import { runKtxSetupProjectStep } from './setup-project.js';
-import { isKtxPreAgentSetupReady, isKtxSetupReady, runKtxSetupReadyChangeMenu, } from './setup-ready-menu.js';
+import { classifyKtxSetupCompletion, runKtxSetupReadyMenu, setupHasContextTargets, } from './setup-ready-menu.js';
 import { runKtxSetupSourcesStep } from './setup-sources.js';
 import { runKtxSetupRuntimeStep, } from './setup-runtime.js';
 import { createKtxSetupPromptAdapter, createKtxSetupUiAdapter, } from './setup-prompts.js';
@@ -47,6 +47,7 @@ async function recordSetupStep(input) {
             step: input.step,
             outcome: setupTelemetryOutcome(input.status),
             durationMs: Math.max(0, performance.now() - input.startedAt),
+            ...(input.errorDetail ? { errorDetail: input.errorDetail } : {}),
         },
     });
 }
@@ -105,7 +106,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);
@@ -286,9 +287,6 @@ function setupStatusReady(status) {
         status.sources.every((source) => source.ready) &&
         status.runtime.ready);
 }
-function setupHasContextTargets(status) {
-    return status.databases.length > 0 || status.sources.length > 0;
-}
 function setupContextReady(status) {
     return status.context.ready;
 }
@@ -371,14 +369,22 @@ async function runKtxSetupInner(args, io, deps = {}) {
         const currentStatus = await readKtxSetupStatus(projectResult.projectDir, { cliVersion: args.cliVersion });
         let readyAction;
         if (args.inputMode !== 'disabled' && !agentsRequested) {
-            if (isKtxSetupReady(currentStatus)) {
-                readyAction = (await runKtxSetupReadyChangeMenu(currentStatus, deps.readyMenuDeps)).action;
-                if (readyAction === 'exit')
+            const completion = classifyKtxSetupCompletion(currentStatus);
+            if (completion === 'ready') {
+                setupUi.note(formatNextStepLines().join('\n'), 'ktx is ready', io);
+                const choice = (await runKtxSetupReadyMenu(currentStatus, deps.readyMenuDeps)).action;
+                if (choice === 'exit')
                     return 0;
+                readyAction = choice;
+            }
+            else if (completion === 'needs-context') {
+                // Config is done; skip the re-walk and land straight on the build prompt.
+                readyAction = 'context';
             }
-            else if (isKtxPreAgentSetupReady(currentStatus)) {
+            else if (completion === 'needs-agents') {
                 readyAction = 'agents';
             }
+            // 'incomplete' → readyAction stays undefined → run the full setup walk.
         }
         const runOnly = readyAction;
         const agentOnlySetup = agentsRequested || runOnly === 'agents';
@@ -467,6 +473,9 @@ async function runKtxSetupInner(args, io, deps = {}) {
                 const databaseResult = await databasesRunner({
                     projectDir: projectResult.projectDir,
                     inputMode: args.inputMode,
+                    yes: args.yes,
+                    cliVersion: args.cliVersion,
+                    runtimeInstallPolicy: setupRuntimeInstallPolicy(args),
                     ...(args.databaseDrivers ? { databaseDrivers: args.databaseDrivers } : {}),
                     ...(args.databaseConnectionIds ? { databaseConnectionIds: args.databaseConnectionIds } : {}),
                     ...(args.databaseConnectionId ? { databaseConnectionId: args.databaseConnectionId } : {}),
@@ -565,6 +574,7 @@ async function runKtxSetupInner(args, io, deps = {}) {
                 startedAt: stepStartedAt,
                 io,
                 cliVersion: args.cliVersion,
+                ...(stepResult.errorDetail ? { errorDetail: stepResult.errorDetail } : {}),
             });
             if (stepResult.status === 'failed') {
                 return 1;
@@ -589,7 +599,9 @@ async function runKtxSetupInner(args, io, deps = {}) {
             }
             if (step === 'context' && stepResult.status !== 'ready') {
                 if (shouldRunAgents && args.skipAgents !== true) {
-                    return 0;
+                    // Context isn't built, so skip agent install — but still reach the
+                    // completion screen, which states readiness and points at `ktx ingest`.
+                    break setupLoop;
                 }
             }
             forcePromptSteps.delete(step);

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>