@kaelio/ktx 0.12.0 → 0.13.1

package/dist/context/scan/local-enrichment-artifacts.js

@@ -1,6 +1,7 @@
 import YAML from 'yaml';
 import { buildLiveDatabaseManifestShards } from '../../context/ingest/adapters/live-database/manifest.js';
 import { isSlYamlPath } from '../../context/sl/source-files.js';
+import { deriveFederatedConnection } from '../connections/federation.js';
 import { buildKtxRelationshipArtifacts, buildKtxRelationshipDiagnostics, emptyKtxRelationshipProfileArtifact, } from './relationship-diagnostics.js';
 const LIVE_DATABASE_ADAPTER = 'live-database';
 const LOCAL_AUTHOR = 'ktx';
@@ -113,7 +114,32 @@ function joinReferencesExistingColumns(join, columnsByTable) {
     }
     return true;
 }
-async function loadExistingManifestState(project, connectionId, snapshot) {
+async function federatedSiblingTargets(project, connectionId) {
+    const descriptor = deriveFederatedConnection(project.config.connections, project.projectDir);
+    if (!descriptor) {
+        return new Set();
+    }
+    const siblings = descriptor.members.filter((member) => member.connectionId !== connectionId);
+    const perSibling = await Promise.all(siblings.map((sibling) => siblingJoinTargets(project, sibling.connectionId)));
+    return new Set(perSibling.flat());
+}
+async function siblingJoinTargets(project, connectionId) {
+    const listed = await project.fileStore.listFiles(schemaDir(connectionId)).catch(() => ({ files: [] }));
+    const files = listed.files.filter(isSlYamlPath);
+    const perFile = await Promise.all(files.map(async (file) => {
+        const shard = await project.fileStore
+            .readFile(file)
+            .then(({ content }) => YAML.parse(content))
+            .catch(() => null);
+        // entry.table is buildTableRef's member-local ref (1-3 parts:
+        // table / schema.table / catalog.schema.table), never connectionId-
+        // prefixed — so prefixing with the member id yields the fully-qualified
+        // `to:` form authored in cross-DB joins.
+        return Object.values(shard?.tables ?? {}).map((entry) => `${connectionId}.${entry.table}`);
+    }));
+    return perFile.flat();
+}
+async function loadExistingManifestState(project, connectionId, snapshot, siblingTargets) {
     const descriptions = new Map();
     const preservedJoins = new Map();
     const usage = new Map();
@@ -146,7 +172,7 @@ async function loadExistingManifestState(project, connectionId, snapshot) {
                 }
                 const joins = (entry.joins ?? []).filter((join) => {
                     return ((join.source === 'manual' || join.source === 'inferred') &&
-                        validTableNames.has(join.to) &&
+                        (validTableNames.has(join.to) || siblingTargets.has(join.to)) &&
                         joinReferencesExistingColumns(join, columnsByTable));
                 });
                 if (joins.length > 0) {
@@ -170,7 +196,8 @@ export async function writeLocalScanManifestShards(input) {
             manifestShardsWritten: 0,
         };
     }
-    const existing = await loadExistingManifestState(input.project, input.connectionId, input.snapshot);
+    const siblingTargets = await federatedSiblingTargets(input.project, input.connectionId);
+    const existing = await loadExistingManifestState(input.project, input.connectionId, input.snapshot, siblingTargets);
     const { shards } = buildLiveDatabaseManifestShards({
         connectionType: input.driver.toUpperCase(),
         tables: snapshotTablesToManifestData(input.snapshot, input.descriptionUpdates),
@@ -178,6 +205,7 @@ export async function writeLocalScanManifestShards(input) {
         existingDescriptions: existing.descriptions,
         existingPreservedJoins: existing.preservedJoins,
         existingUsage: existing.usage,
+        federatedSiblingTargets: siblingTargets,
         mapColumnType: (dimensionType) => dimensionType,
     });
     const manifestShards = [];

package/dist/context/sl/local-query.js

@@ -1,22 +1,35 @@
+import { FEDERATED_CONNECTION_ID } from '../connections/federation.js';
+import { resolveRequiredConnectionId } from '../connections/resolve-connection.js';
 import { sqlAnalysisDialectForDriver } from '../sql-analysis/dialect.js';
 import { loadLocalSlSourceRecords } from './local-sl.js';
 import { toResolvedWire } from './semantic-layer.service.js';
 import { assertSafeConnectionId } from './source-files.js';
 const COMPILE_ONLY_REASON = 'Local semantic-layer query compiled SQL but no data-source execution adapter is configured.';
+const FEDERATED_SL_QUERY_UNSUPPORTED = `Semantic-layer queries are per-connection and cannot target the federated connection '${FEDERATED_CONNECTION_ID}'. ` +
+    `Run a cross-database query as read-only SQL instead — ktx sql -c ${FEDERATED_CONNECTION_ID} "SELECT ..." or the sql_execution tool — ` +
+    'using catalog-qualified table names (connectionId.schema.table, or connectionId.table for sqlite; ' +
+    'double-quote ids that are not bare identifiers, e.g. "books-db".public.books).';
 function resolveLocalConnectionId(project, requested) {
-    if (requested) {
-        return assertSafeConnectionId(requested);
-    }
-    const ids = Object.keys(project.config.connections).sort();
-    if (ids.length === 1) {
-        return assertSafeConnectionId(ids[0]);
+    return assertSafeConnectionId(resolveRequiredConnectionId(project.config, requested));
+}
+// The planner rejects a source set carrying a join whose `to` names a source
+// outside that set, which would break every query for this connection. Keep only
+// joins resolvable within the connection's own sources; a cross-database join
+// (its `to` qualified by a sibling connection id) is just one such unresolvable
+// target and runs as raw SQL instead. Membership is the test, not a connection-id
+// prefix match, so a same-connection target whose name collides with a sibling
+// connection id is preserved.
+function withResolvableJoinsOnly(source, knownSourceNames) {
+    if (source.joins.length === 0) {
+        return source;
     }
-    throw new Error('connectionId is required when the local project has zero or multiple connections.');
+    const joins = source.joins.filter((join) => knownSourceNames.has(join.to));
+    return joins.length === source.joins.length ? source : { ...source, joins };
 }
 async function loadComputableSources(project, connectionId) {
-    return (await loadLocalSlSourceRecords(project, { connectionId: assertSafeConnectionId(connectionId) }))
-        .filter((record) => record.source.table || record.source.sql)
-        .map((record) => toResolvedWire(record.source));
+    const records = (await loadLocalSlSourceRecords(project, { connectionId })).filter((record) => record.source.table || record.source.sql);
+    const knownSourceNames = new Set(records.map((record) => record.source.name));
+    return records.map((record) => toResolvedWire(withResolvableJoinsOnly(record.source, knownSourceNames)));
 }
 function headersFromColumns(columns) {
     return columns
@@ -24,9 +37,13 @@ function headersFromColumns(columns) {
         .filter((name) => typeof name === 'string' && name.length > 0);
 }
 export async function compileLocalSlQuery(project, options) {
+    if (options.connectionId === FEDERATED_CONNECTION_ID) {
+        throw new Error(FEDERATED_SL_QUERY_UNSUPPORTED);
+    }
     await options.onProgress?.({ progress: 0, message: 'Compiling query' });
     const connectionId = resolveLocalConnectionId(project, options.connectionId);
-    const dialect = sqlAnalysisDialectForDriver(project.config.connections[connectionId]?.driver);
+    const driver = project.config.connections[connectionId]?.driver;
+    const dialect = sqlAnalysisDialectForDriver(driver);
     const sources = await loadComputableSources(project, connectionId);
     await options.onProgress?.({ progress: 0.3, message: 'Generating SQL' });
     const response = await options.compute.query({
@@ -76,7 +93,7 @@ export async function compileLocalSlQuery(project, options) {
             ...response.plan,
             execution: {
                 mode: 'executed',
-                driver: project.config.connections[connectionId]?.driver ?? 'unknown',
+                driver: driver ?? 'unknown',
                 maxRows,
                 rowCount: execution.rowCount,
             },

package/dist/context/sl/local-sl.js

@@ -1,6 +1,7 @@
 import { join } from 'node:path';
 import YAML from 'yaml';
 import { z } from 'zod';
+import { deriveFederatedConnection, FEDERATED_CONNECTION_ID } from '../connections/federation.js';
 import { HybridSearchCore } from '../../context/search/hybrid-search-core.js';
 import { DEFAULT_PRIORITY, resolveDescription } from './descriptions.js';
 import { normalizeSemanticLayerDescriptions } from './description-normalization.js';
@@ -86,7 +87,32 @@ function parsedStandaloneSource(parsed, name) {
     });
 }
 export async function loadLocalSlSourceRecords(project, input) {
-    const connectionId = assertSafeConnectionId(input.connectionId);
+    if (input.connectionId === FEDERATED_CONNECTION_ID) {
+        const descriptor = deriveFederatedConnection(project.config.connections, project.projectDir);
+        if (!descriptor) {
+            return [];
+        }
+        const perMember = await Promise.all(descriptor.members.map(async (member) => {
+            const records = await loadSingleConnectionSourceRecords(project, member.connectionId);
+            return records.map((record) => {
+                // The federated view is one virtual connection: rows carry its id and a
+                // member-prefixed name, so a listing/search row round-trips to
+                // `ktx sl -c _ktx_federated read <name>`. Member origin lives in the name.
+                const name = `${member.connectionId}.${record.name}`;
+                return {
+                    ...record,
+                    connectionId: FEDERATED_CONNECTION_ID,
+                    name,
+                    source: { ...record.source, name },
+                };
+            });
+        }));
+        return perMember.flat();
+    }
+    return loadSingleConnectionSourceRecords(project, input.connectionId);
+}
+async function loadSingleConnectionSourceRecords(project, rawConnectionId) {
+    const connectionId = assertSafeConnectionId(rawConnectionId);
     const dir = `semantic-layer/${connectionId}`;
     const schemaDir = `${dir}/_schema`;
     const listed = await project.fileStore.listFiles(dir);

package/dist/context/sl/source-files.d.ts

@@ -1,4 +1,6 @@
 import type { KtxFileStorePort } from '../../context/core/file-store.js';
+/** @internal */
+export declare function isReservedConnectionId(connectionId: string): boolean;
 export declare function assertSafeConnectionId(connectionId: string): string;
 export declare function isSafeConnectionId(connectionId: string | undefined): connectionId is string;
 export declare function sourceNameFromPath(path: string): string;

package/dist/context/sl/source-files.js

@@ -17,7 +17,14 @@ function assertSafePathToken(kind, value) {
     }
     return value;
 }
+/** @internal */
+export function isReservedConnectionId(connectionId) {
+    return connectionId.startsWith('_ktx_');
+}
 export function assertSafeConnectionId(connectionId) {
+    if (isReservedConnectionId(connectionId)) {
+        throw new Error(`Connection id "${connectionId}" uses the reserved "_ktx_" prefix.`);
+    }
     if (!isSafeConnectionId(connectionId)) {
         throw new Error(`Unsafe connection id: ${connectionId}`);
     }

package/dist/ingest-query-executor.d.ts

@@ -1,9 +1,11 @@
+import { executeFederatedQuery } from './connectors/duckdb/federated-executor.js';
 import type { KtxSqlQueryExecutorPort } from './context/connections/query-executor.js';
 import type { KtxLocalProject } from './context/project/project.js';
 import { createKtxCliScanConnector } from './local-scan-connectors.js';
 type CreateConnector = typeof createKtxCliScanConnector;
 export interface KtxCliIngestQueryExecutorDeps {
     createConnector?: CreateConnector;
+    executeFederated?: typeof executeFederatedQuery;
 }
 export declare function createKtxCliIngestQueryExecutor(project: KtxLocalProject, deps?: KtxCliIngestQueryExecutorDeps): KtxSqlQueryExecutorPort;
 export {};

package/dist/ingest-query-executor.js

@@ -1,30 +1,16 @@
+import { executeProjectReadOnlySql } from './context/connections/project-sql-executor.js';
 import { createKtxCliScanConnector } from './local-scan-connectors.js';
-async function cleanupConnector(connector) {
-    await connector?.cleanup?.();
-}
 export function createKtxCliIngestQueryExecutor(project, deps = {}) {
     const createConnector = deps.createConnector ?? createKtxCliScanConnector;
     return {
         async execute(input) {
-            let connector = null;
-            try {
-                connector = await createConnector(project, input.connectionId);
-                if (!connector.capabilities.readOnlySql || !connector.executeReadOnly) {
-                    throw new Error(`Connection "${input.connectionId}" driver "${connector.driver}" does not support read-only SQL execution.`);
-                }
-                const ctx = { runId: 'ingest-sql-execution' };
-                const result = await connector.executeReadOnly({ connectionId: input.connectionId, sql: input.sql, maxRows: input.maxRows }, ctx);
-                return {
-                    headers: result.headers,
-                    rows: result.rows,
-                    totalRows: result.totalRows,
-                    command: 'SELECT',
-                    rowCount: result.rowCount,
-                };
-            }
-            finally {
-                await cleanupConnector(connector);
-            }
+            return executeProjectReadOnlySql({
+                project,
+                input,
+                createConnector: (connectionId) => createConnector(project, connectionId),
+                executeFederated: deps.executeFederated,
+                runId: 'ingest-sql-execution',
+            });
         },
     };
 }

package/dist/setup-agents.d.ts

@@ -14,15 +14,24 @@ export interface KtxSetupAgentsArgs {
     mode: KtxAgentInstallMode;
     skipAgents: boolean;
     showNextActions?: boolean;
+    installRoot?: string;
+    cwd?: string;
 }
+/** The directory project-scoped agent files land in; equals projectDir unless an install root is chosen. */
+interface KtxAgentInstall {
+    target: KtxAgentTarget;
+    scope: KtxAgentScope;
+    mode: KtxAgentInstallMode;
+    installRoot: string;
+}
+/** Install shape for formatting helpers; installRoot falls back to projectDir when absent. */
+type KtxAgentInstallLike = Omit<KtxAgentInstall, 'installRoot'> & {
+    installRoot?: string;
+};
 export type KtxSetupAgentsResult = {
     status: 'ready';
     projectDir: string;
-    installs: Array<{
-        target: KtxAgentTarget;
-        scope: KtxAgentScope;
-        mode: KtxAgentInstallMode;
-    }>;
+    installs: KtxAgentInstall[];
     nextActions?: string;
 } | {
     status: 'skipped';
@@ -41,11 +50,7 @@ export interface KtxAgentInstallManifest {
     version: 1;
     projectDir: string;
     installedAt: string;
-    installs: Array<{
-        target: KtxAgentTarget;
-        scope: KtxAgentScope;
-        mode: KtxAgentInstallMode;
-    }>;
+    installs: KtxAgentInstall[];
     entries: Array<{
         kind: 'file';
         path: string;
@@ -65,6 +70,7 @@ export declare function plannedKtxAgentFiles(input: {
     target: KtxAgentTarget;
     scope: KtxAgentScope;
     mode: KtxAgentInstallMode;
+    installRoot?: string;
 }): InstallEntry[];
 export declare function readKtxAgentInstallManifest(projectDir: string): Promise<KtxAgentInstallManifest | null>;
 /** @internal */
@@ -79,6 +85,10 @@ interface KtxSetupAgentsPromptAdapter {
         options: KtxSetupPromptOption[];
         required?: boolean;
     }): Promise<string[]>;
+    text(options: {
+        message: string;
+        placeholder?: string;
+    }): Promise<string | undefined>;
     cancel(message: string): void;
 }
 export interface KtxSetupAgentsDeps {
@@ -91,10 +101,6 @@ export interface InstallSummaryEntry {
     lines: string[];
 }
 /** @internal */
-export declare function formatInstallSummaryLines(installs: Array<{
-    target: KtxAgentTarget;
-    scope: KtxAgentScope;
-    mode: KtxAgentInstallMode;
-}>, entries: InstallEntry[], projectDir: string): InstallSummaryEntry[];
+export declare function formatInstallSummaryLines(installs: KtxAgentInstallLike[], entries: InstallEntry[], projectDir: string): InstallSummaryEntry[];
 export declare function runKtxSetupAgentsStep(args: KtxSetupAgentsArgs, io: KtxCliIo, deps?: KtxSetupAgentsDeps): Promise<KtxSetupAgentsResult>;
 export {};

package/dist/setup-agents.js

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs';
-import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { styleText } from 'node:util';
@@ -166,7 +166,7 @@ function universalMcpSnippet(endpoint) {
         ...(endpoint.tokenAuth ? ['Header: Authorization: Bearer ${KTX_MCP_TOKEN}'] : []),
     ].join('\n');
 }
-function claudeConfigPath(projectDir, scope) {
+function claudeConfigPath(projectDir, installRoot, scope) {
     const home = process.env.HOME ?? '';
     if (scope === 'global') {
         return { path: join(home, '.claude.json'), jsonPath: ['mcpServers', 'ktx'] };
@@ -174,12 +174,12 @@ function claudeConfigPath(projectDir, scope) {
     if (scope === 'local') {
         return { path: join(home, '.claude.json'), jsonPath: ['projects', resolve(projectDir), 'mcpServers', 'ktx'] };
     }
-    return { path: join(resolve(projectDir), '.mcp.json'), jsonPath: ['mcpServers', 'ktx'] };
+    return { path: join(resolve(installRoot), '.mcp.json'), jsonPath: ['mcpServers', 'ktx'] };
 }
-function cursorConfigPath(projectDir, scope) {
+function cursorConfigPath(installRoot, scope) {
     const home = process.env.HOME ?? '';
     return {
-        path: scope === 'global' ? join(home, '.cursor/mcp.json') : join(resolve(projectDir), '.cursor/mcp.json'),
+        path: scope === 'global' ? join(home, '.cursor/mcp.json') : join(resolve(installRoot), '.cursor/mcp.json'),
         jsonPath: ['mcpServers', 'ktx'],
     };
 }
@@ -226,12 +226,12 @@ async function installMcpClientConfig(input) {
         notices.push(MCP_DAEMON_REQUIRED_NOTICE);
     }
     if (input.target === 'claude-code') {
-        const config = claudeConfigPath(input.projectDir, input.scope);
+        const config = claudeConfigPath(input.projectDir, input.installRoot, input.scope);
         await writeJsonKey(config.path, config.jsonPath, claudeMcpEntry(endpoint));
         entries.push({ kind: 'json-key', path: config.path, jsonPath: config.jsonPath });
     }
     else if (input.target === 'cursor') {
-        const config = cursorConfigPath(input.projectDir, input.scope);
+        const config = cursorConfigPath(input.installRoot, input.scope);
         await writeJsonKey(config.path, config.jsonPath, cursorMcpEntry(endpoint));
         entries.push({ kind: 'json-key', path: config.path, jsonPath: config.jsonPath });
     }
@@ -241,7 +241,7 @@ async function installMcpClientConfig(input) {
     else if (input.target === 'opencode') {
         const path = input.scope === 'global'
             ? '~/.config/opencode/opencode.json'
-            : relative(input.projectDir, join(input.projectDir, 'opencode.json'));
+            : relative(input.installRoot, join(input.installRoot, 'opencode.json'));
         snippets.push(`Add this OpenCode MCP snippet to ${path}:\n${opencodeSnippet(endpoint)}`);
     }
     else if (input.target === 'universal') {
@@ -251,7 +251,7 @@ async function installMcpClientConfig(input) {
 }
 function plannedMcpJsonEntries(input) {
     if (input.target === 'claude-code') {
-        const config = claudeConfigPath(input.projectDir, input.scope);
+        const config = claudeConfigPath(input.projectDir, input.installRoot, input.scope);
         return [{ kind: 'json-key', path: config.path, jsonPath: config.jsonPath }];
     }
     if (input.target === 'claude-desktop') {
@@ -259,7 +259,7 @@ function plannedMcpJsonEntries(input) {
         return [{ kind: 'json-key', path: config.path, jsonPath: config.jsonPath }];
     }
     if (input.target === 'cursor') {
-        const config = cursorConfigPath(input.projectDir, input.scope);
+        const config = cursorConfigPath(input.installRoot, input.scope);
         return [{ kind: 'json-key', path: config.path, jsonPath: config.jsonPath }];
     }
     return [];
@@ -324,7 +324,7 @@ export function plannedKtxAgentFiles(input) {
         }
         throw new Error(`Global ${input.target} installation is not supported; omit --global.`);
     }
-    const root = resolve(input.projectDir);
+    const root = resolve(input.installRoot ?? input.projectDir);
     const analyticsEntries = {
         'claude-code': [
             { kind: 'file', path: join(root, '.claude/skills/ktx-analytics/SKILL.md'), role: 'analytics-skill' },
@@ -502,7 +502,8 @@ function entryKey(entry) {
 function mergeManifest(projectDir, existing, installs, entries) {
     const installMap = new Map();
     for (const install of [...(existing?.installs ?? []), ...installs]) {
-        installMap.set(`${install.target}:${install.scope}:${install.mode}`, install);
+        const installRoot = install.installRoot ?? resolve(projectDir);
+        installMap.set(`${install.target}:${install.scope}:${install.mode}:${installRoot}`, { ...install, installRoot });
     }
     const entryMap = new Map();
     for (const entry of [...(existing?.entries ?? []), ...entries]) {
@@ -611,18 +612,31 @@ function formatInlinePath(path) {
     }
     return path;
 }
+function installSummaryTitle(install, projectDir) {
+    const name = targetDisplayName(install.target);
+    if (install.scope !== 'project') {
+        return `${name} · ${scopeDisplayName(install.scope)}`;
+    }
+    const installRoot = resolve(install.installRoot ?? projectDir);
+    if (installRoot === resolve(projectDir)) {
+        return `${name} · ${scopeDisplayName('project')}`;
+    }
+    return `${name} · ${formatInlinePath(installRoot)}`;
+}
 /** @internal */
 export function formatInstallSummaryLines(installs, entries, projectDir) {
     const entriesByTarget = new Map();
     for (const install of installs) {
-        const plannedFilePaths = new Set(plannedKtxAgentFiles({ projectDir, ...install })
+        const installRoot = install.installRoot ?? projectDir;
+        const plannedFilePaths = new Set(plannedKtxAgentFiles({ projectDir, ...install, installRoot })
             .filter((entry) => entry.kind === 'file')
             .map((entry) => entry.path));
         entriesByTarget.set(install.target, entries.filter((entry) => entry.kind === 'file' && plannedFilePaths.has(entry.path)));
     }
     const mcpEntriesByTarget = new Map();
     for (const install of installs) {
-        const plannedMcpKeys = new Set(plannedMcpJsonEntries({ projectDir, ...install }).map(entryKey));
+        const installRoot = install.installRoot ?? projectDir;
+        const plannedMcpKeys = new Set(plannedMcpJsonEntries({ projectDir, installRoot, target: install.target, scope: install.scope }).map(entryKey));
         mcpEntriesByTarget.set(install.target, entries.filter((entry) => entry.kind === 'json-key' && plannedMcpKeys.has(entryKey(entry))));
     }
     return installs.map((install) => {
@@ -663,7 +677,7 @@ export function formatInstallSummaryLines(installs, entries, projectDir) {
             lines.push(`${guidanceInstallLine(install.target)}.`);
         }
         return {
-            title: `${targetDisplayName(install.target)} · ${scopeDisplayName(install.scope)}`,
+            title: installSummaryTitle(install, projectDir),
             lines,
         };
     });
@@ -726,6 +740,9 @@ function manualActionFromSnippet(snippet) {
         body,
     };
 }
+function openFromDirectoryLabel(installRoot, projectDir) {
+    return resolve(installRoot) === resolve(projectDir) ? 'the ktx project directory' : 'the install directory';
+}
 function formatAgentNextActions(input) {
     const projectDir = resolve(input.projectDir);
     const lines = [];
@@ -762,10 +779,11 @@ function formatAgentNextActions(input) {
     if (claudeCodeInstall) {
         lines.push(`${step}. Open Claude Code`);
         if (claudeCodeInstall.scope === 'project') {
-            lines.push('  Open Claude Code from the ktx project directory:');
+            const installRoot = resolve(claudeCodeInstall.installRoot ?? projectDir);
+            lines.push(`  Open Claude Code from ${openFromDirectoryLabel(installRoot, projectDir)}:`);
             lines.push('');
             lines.push('  RUN:');
-            lines.push(`  cd ${shellScriptQuote(projectDir)}`);
+            lines.push(`  cd ${shellScriptQuote(installRoot)}`);
             lines.push('  claude');
         }
         else {
@@ -779,10 +797,11 @@ function formatAgentNextActions(input) {
     if (cursorInstall) {
         lines.push(`${step}. Open Cursor`);
         if (cursorInstall.scope === 'project') {
-            lines.push('  Open Cursor from the ktx project directory:');
+            const installRoot = resolve(cursorInstall.installRoot ?? projectDir);
+            lines.push(`  Open Cursor from ${openFromDirectoryLabel(installRoot, projectDir)}:`);
             lines.push('');
             lines.push('  OPEN:');
-            lines.push(`  ${projectDir}`);
+            lines.push(`  ${installRoot}`);
         }
         else {
             lines.push('  Open Cursor.');
@@ -844,6 +863,70 @@ async function markAgentsComplete(projectDir) {
     await writeFile(project.configPath, serializeKtxProjectConfig(project.config), 'utf-8');
     await markKtxSetupStateStepComplete(projectDir, 'agents');
 }
+// A typed path never passes through a shell, so expand a leading ~ here; HOME
+// matches formatInlinePath so the ~/… hints shown in the menu round-trip.
+function resolveTypedInstallDir(cwd, raw) {
+    const home = process.env.HOME;
+    if (home && (raw === '~' || raw.startsWith('~/'))) {
+        return resolve(home, raw.slice(2));
+    }
+    return resolve(cwd, raw);
+}
+async function ensureInstallDir(resolvedPath) {
+    if (existsSync(resolvedPath)) {
+        if (!(await stat(resolvedPath)).isDirectory()) {
+            throw new Error(`Install directory path is a file, not a directory: ${resolvedPath}`);
+        }
+        return resolvedPath;
+    }
+    await mkdir(resolvedPath, { recursive: true });
+    return resolvedPath;
+}
+async function promptInstallDirectory(input) {
+    const { prompts, io, cwd, projectRoot, scopeTargets } = input;
+    const options = [
+        { value: 'project', label: 'ktx project directory', hint: formatInlinePath(projectRoot) },
+        ...(cwd !== projectRoot
+            ? [{ value: 'current', label: 'Current directory', hint: formatInlinePath(cwd) }]
+            : []),
+        { value: 'custom', label: 'Custom directory…', hint: 'Enter a path' },
+        ...(scopeTargets.every(targetSupportsGlobalScope)
+            ? [
+                {
+                    value: 'global',
+                    label: 'Global scope (user config)',
+                    hint: 'Agents can load this ktx project from any working directory.',
+                },
+            ]
+            : []),
+    ];
+    const choice = await prompts.select({
+        message: `Where should ktx install agent config?\n\nktx project: ${projectRoot}`,
+        options,
+    });
+    if (choice === 'back')
+        return 'back';
+    if (choice === 'global')
+        return { scope: 'global', installRoot: projectRoot };
+    if (choice === 'current')
+        return { scope: 'project', installRoot: cwd };
+    if (choice === 'project')
+        return { scope: 'project', installRoot: projectRoot };
+    while (true) {
+        const typed = await prompts.text({ message: 'Enter the directory to install agent config into' });
+        if (typed === undefined)
+            return 'back';
+        const trimmed = typed.trim();
+        if (trimmed === '')
+            continue;
+        try {
+            return { scope: 'project', installRoot: await ensureInstallDir(resolveTypedInstallDir(cwd, trimmed)) };
+        }
+        catch (error) {
+            io.stderr.write(`${errorMessage(error)}\n`);
+        }
+    }
+}
 export async function runKtxSetupAgentsStep(args, io, deps = {}) {
     if (args.skipAgents) {
         io.stdout.write('│  Agent integration skipped.\n');
@@ -905,30 +988,32 @@ export async function runKtxSetupAgentsStep(args, io, deps = {}) {
             : 'Missing agent target: pass --target or use interactive setup.\n');
         return { status: 'missing-input', projectDir: args.projectDir };
     }
+    const cwd = resolve(args.cwd ?? process.cwd());
+    const projectRoot = resolve(args.projectDir);
     const scopeTargets = targets.filter((target) => target !== 'claude-desktop');
-    const selectedScope = args.inputMode !== 'disabled' &&
-        args.scope === 'project' &&
-        scopeTargets.length > 0 &&
-        scopeTargets.every(targetSupportsGlobalScope)
-        ? (await prompts.select({
-            message: `Where should ktx install supported agent config?\n\nktx project: ${resolve(args.projectDir)}`,
-            options: [
-                {
-                    value: 'project',
-                    label: 'Project scope (ktx project directory)',
-                    hint: 'Only agents opened from this ktx project path load the project-scoped config.',
-                },
-                {
-                    value: 'global',
-                    label: 'Global scope (user config)',
-                    hint: 'Agents can load this ktx project from any working directory.',
-                },
-            ],
-        }))
-        : args.scope;
-    if (selectedScope === 'back')
-        return { status: 'back', projectDir: args.projectDir };
-    const installs = targets.map((target) => ({ target, scope: effectiveInstallScope(target, selectedScope), mode }));
+    let selectedScope = args.scope;
+    let installRoot = projectRoot;
+    if (args.installRoot !== undefined) {
+        try {
+            installRoot = await ensureInstallDir(resolveTypedInstallDir(cwd, args.installRoot));
+        }
+        catch (error) {
+            writePrefixedLines((chunk) => io.stderr.write(chunk), errorMessage(error));
+            return { status: 'failed', projectDir: args.projectDir };
+        }
+        selectedScope = 'project';
+    }
+    else if (args.inputMode !== 'disabled' && args.scope === 'project' && scopeTargets.length > 0) {
+        const decision = await promptInstallDirectory({ prompts, io, cwd, projectRoot, scopeTargets });
+        if (decision === 'back')
+            return { status: 'back', projectDir: args.projectDir };
+        selectedScope = decision.scope;
+        installRoot = decision.installRoot;
+    }
+    const installs = targets.map((target) => {
+        const scope = effectiveInstallScope(target, selectedScope);
+        return { target, scope, mode, installRoot: scope === 'project' ? installRoot : projectRoot };
+    });
     const entries = [];
     const snippets = [];
     const notices = new Set();
@@ -938,6 +1023,7 @@ export async function runKtxSetupAgentsStep(args, io, deps = {}) {
             entries.push(...targetEntries);
             const mcpResult = await installMcpClientConfig({
                 projectDir: args.projectDir,
+                installRoot: install.installRoot,
                 target: install.target,
                 scope: install.scope,
             });

package/dist/setup-databases.d.ts

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