@kaelio/ktx 0.11.0 → 0.13.0

package/dist/runtime.js

@@ -5,7 +5,7 @@ function writeJson(io, value) {
 }
 function writeInstallResult(io, result) {
     const verb = result.status === 'ready' ? 'Using existing' : 'Installed';
-    io.stdout.write(`${verb} KTX Python runtime\n`);
+    io.stdout.write(`${verb} ktx Python runtime\n`);
     io.stdout.write(`version: ${result.manifest.cliVersion}\n`);
     io.stdout.write(`features: ${result.manifest.features.join(', ')}\n`);
     io.stdout.write(`python: ${result.manifest.python.executable}\n`);
@@ -15,7 +15,7 @@ function writeInstallResult(io, result) {
 }
 function writeDaemonStart(io, result) {
     const verb = result.status === 'reused' ? 'Using existing' : 'Started';
-    io.stdout.write(`${verb} KTX daemon\n`);
+    io.stdout.write(`${verb} ktx daemon\n`);
     io.stdout.write(`url: ${result.baseUrl}\n`);
     io.stdout.write(`pid: ${result.state.pid}\n`);
     io.stdout.write(`version: ${result.state.version}\n`);
@@ -26,10 +26,10 @@ function writeDaemonStart(io, result) {
 }
 function writeDaemonStop(io, result) {
     if (result.status === 'already-stopped') {
-        io.stdout.write('KTX daemon already stopped\n');
+        io.stdout.write('ktx daemon already stopped\n');
         return;
     }
-    io.stdout.write('Stopped KTX daemon\n');
+    io.stdout.write('Stopped ktx daemon\n');
     io.stdout.write(`pid: ${result.state?.pid ?? 'unknown'}\n`);
     io.stdout.write(`state: ${result.layout.daemonStatePath}\n`);
 }
@@ -42,11 +42,11 @@ function writeDaemonStopAll(io, result) {
         result.stale.length === 0 &&
         result.failed.length === 0 &&
         result.scanErrors.length === 0) {
-        io.stdout.write('No KTX daemons found\n');
+        io.stdout.write('No ktx daemons found\n');
         return 0;
     }
     if (failed === 0) {
-        io.stdout.write(`Stopped ${result.stopped.length} KTX daemons\n`);
+        io.stdout.write(`Stopped ${result.stopped.length} ktx daemons\n`);
         if (result.stale.length > 0) {
             io.stdout.write(`Cleaned ${result.stale.length} stale daemon states\n`);
         }
@@ -58,7 +58,7 @@ function writeDaemonStopAll(io, result) {
         }
         return 0;
     }
-    io.stderr.write(`Stopped ${result.stopped.length} KTX daemons; failed ${result.failed.length}${result.stale.length > 0 ? `; cleaned stale ${result.stale.length}` : ''}\n`);
+    io.stderr.write(`Stopped ${result.stopped.length} ktx daemons; failed ${result.failed.length}${result.stale.length > 0 ? `; cleaned stale ${result.stale.length}` : ''}\n`);
     for (const entry of result.failed) {
         io.stderr.write(`pid: ${entry.pid} source: ${entry.source}${entry.url ? ` url: ${entry.url}` : ''}${entry.health ? ` health: ${entry.health}` : ''} detail: ${entry.detail}\n`);
     }
@@ -68,7 +68,7 @@ function writeDaemonStopAll(io, result) {
     return 1;
 }
 function writeStatus(io, status) {
-    io.stdout.write('KTX Python runtime\n');
+    io.stdout.write('ktx Python runtime\n');
     io.stdout.write(`status: ${status.kind}\n`);
     io.stdout.write(`detail: ${status.detail}\n`);
     io.stdout.write(`runtime root: ${status.layout.runtimeRoot}\n`);
@@ -80,7 +80,7 @@ function writeStatus(io, status) {
     }
 }
 function writeRuntimeChecks(io, checks) {
-    io.stdout.write('KTX Python runtime checks\n');
+    io.stdout.write('ktx Python runtime checks\n');
     for (const check of checks) {
         io.stdout.write(`${check.status.toUpperCase()} ${check.label}: ${check.detail}\n`);
         if (check.fix) {

package/dist/scan.js

@@ -206,7 +206,7 @@ function writeHumanReportBody(report, io) {
 }
 function writeRunSummary(report, projectDir, io) {
     const styled = shouldUseStyledOutput(io);
-    io.stdout.write(`${styled ? green('✓') : ''}${styled ? ' ' : ''}KTX scan completed\n`);
+    io.stdout.write(`${styled ? green('✓') : ''}${styled ? ' ' : ''}ktx scan completed\n`);
     io.stdout.write('Status: done\n');
     writeHumanReportBody(report, io);
     const projectDirArg = quoteCliArg(projectDir);

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';
@@ -12,14 +12,8 @@ import { errorMessage, writePrefixedLines } from './clack.js';
 import { isWritableTtyOutput } from './io/tty.js';
 import { createKtxSetupPromptAdapter, createKtxSetupUiAdapter, } from './setup-prompts.js';
 import { readKtxMcpDaemonStatus } from './managed-mcp-daemon.js';
+import { withMultiselectNavigation } from './prompt-navigation.js';
 const MCP_DAEMON_REQUIRED_NOTICE = 'mcp-daemon-required';
-function writeSetupInfo(io, message) {
-    if (isWritableTtyOutput(io.stdout)) {
-        log.info(message, { output: io.stdout });
-        return;
-    }
-    io.stdout.write(`${message}\n`);
-}
 function writeSetupStep(io, message) {
     if (isWritableTtyOutput(io.stdout)) {
         log.step(message, { output: io.stdout });
@@ -148,7 +142,7 @@ function codexSnippet(endpoint) {
     if (endpoint.tokenAuth) {
         return [
             'Codex MCP config does not currently document HTTP headers.',
-            'Run KTX on loopback without token auth for Codex, or configure headers after Codex documents support.',
+            'Run ktx on loopback without token auth for Codex, or configure headers after Codex documents support.',
         ].join('\n');
     }
     return [`[mcp_servers.ktx]`, `url = "${endpoint.url}"`].join('\n');
@@ -172,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'] };
@@ -180,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'],
     };
 }
@@ -232,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 });
     }
@@ -247,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') {
@@ -257,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') {
@@ -265,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 [];
@@ -330,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' },
@@ -406,16 +400,16 @@ function cliInstructionContent(input) {
     return [
         '---',
         'name: ktx',
-        'description: Use local KTX semantic context and wiki knowledge for this project.',
+        'description: Use local ktx semantic context and wiki knowledge for this project.',
         '---',
         '',
-        '# KTX Local Context',
+        '# ktx Local Context',
         '',
-        'This is an admin/developer CLI helper. End-user data agents should use the KTX MCP tools when available.',
+        'This is an admin/developer CLI helper. End-user data agents should use the ktx MCP tools when available.',
         '',
         `Use this project with \`--project-dir ${input.projectDir}\`.`,
-        'Commands are pinned to the local KTX CLI path that created this file, so agents do not need `ktx` in PATH.',
-        'If the CLI path no longer exists after moving this checkout or reinstalling KTX, rerun `ktx setup --agents`.',
+        'Commands are pinned to the local ktx CLI path that created this file, so agents do not need `ktx` in PATH.',
+        'If the CLI path no longer exists after moving this checkout or reinstalling ktx, rerun `ktx setup --agents`.',
         '',
         'Agents must not print secrets, credential references, environment variable values, or file contents from ' +
             '`.ktx/secrets`.',
@@ -508,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]) {
@@ -526,7 +521,7 @@ function mergeManifest(projectDir, existing, installs, entries) {
 export async function removeKtxAgentInstall(projectDir, io) {
     const manifest = await readKtxAgentInstallManifest(projectDir);
     if (!manifest) {
-        io.stdout.write('No KTX agent installation manifest found.\n');
+        io.stdout.write('No ktx agent installation manifest found.\n');
         return 0;
     }
     for (const entry of manifest.entries) {
@@ -536,7 +531,7 @@ export async function removeKtxAgentInstall(projectDir, io) {
             await removeJsonKey(entry.path, entry.jsonPath).catch(() => undefined);
     }
     await rm(agentInstallManifestPath(projectDir), { force: true });
-    io.stdout.write('Removed KTX agent integration files from manifest.\n');
+    io.stdout.write('Removed ktx agent integration files from manifest.\n');
     return 0;
 }
 function createPromptAdapter() {
@@ -617,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) => {
@@ -669,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,
         };
     });
@@ -732,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 = [];
@@ -768,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 {
@@ -785,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.');
@@ -798,7 +811,7 @@ function formatAgentNextActions(input) {
     }
     if (input.installs.some((install) => install.target === 'claude-desktop')) {
         lines.push(`${step}. Restart Claude Desktop`);
-        lines.push('  Claude Desktop loads KTX MCP after restart.');
+        lines.push('  Claude Desktop loads ktx MCP after restart.');
         pushBlankLine(lines);
         step += 1;
         const skillBundlePaths = claudeDesktopSkillBundlePathsForInstalls(projectDir, input.installs);
@@ -809,7 +822,7 @@ function formatAgentNextActions(input) {
             for (const path of skillBundlePaths) {
                 lines.push(`  ${path}`);
             }
-            lines.push('  Toggle the uploaded KTX skills on.');
+            lines.push('  Toggle the uploaded ktx skills on.');
             pushBlankLine(lines);
             step += 1;
         }
@@ -850,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');
@@ -859,22 +936,19 @@ export async function runKtxSetupAgentsStep(args, io, deps = {}) {
         return { status: 'skipped', projectDir: args.projectDir };
     }
     const prompts = deps.prompts ?? createPromptAdapter();
-    if (args.inputMode === 'auto' && args.target === undefined) {
-        writeSetupInfo(io, 'Space to select, Enter to confirm, Esc to go back.');
-    }
     const mode = args.inputMode === 'disabled'
         ? args.mode
         : (await prompts.select({
-            message: 'What should agents be allowed to do with this KTX project?',
+            message: 'What should agents be allowed to do with this ktx project?',
             options: [
                 {
                     value: 'mcp',
-                    label: 'Ask data questions with KTX MCP',
+                    label: 'Ask data questions with ktx MCP',
                     hint: 'Installs the MCP connection and analytics workflow skill. Best for normal use.',
                 },
                 {
                     value: 'mcp-cli',
-                    label: 'Ask data questions + manage KTX with CLI commands',
+                    label: 'Ask data questions + manage ktx with CLI commands',
                     hint: 'Adds an admin CLI skill so agents can run ktx status, sl, wiki, and setup commands.',
                 },
                 {
@@ -895,7 +969,7 @@ export async function runKtxSetupAgentsStep(args, io, deps = {}) {
         : args.inputMode === 'disabled'
             ? []
             : (await prompts.multiselect({
-                message: 'Which agent targets should KTX install?',
+                message: withMultiselectNavigation('Which agent targets should ktx install?'),
                 options: [
                     { value: 'claude-code', label: 'Claude Code' },
                     { value: 'claude-desktop', label: 'Claude Desktop' },
@@ -914,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();
@@ -947,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-banner.d.ts

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

package/dist/setup-banner.js

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