@kaelio/ktx 0.1.0-rc.6 → 0.1.1

package/dist/setup-agents.js

@@ -2,12 +2,83 @@ import { existsSync } from 'node:fs';
 import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { styleText } from 'node:util';
+import { log, outro } from '@clack/prompts';
 import { loadKtxProject, markKtxSetupStateStepComplete, serializeKtxProjectConfig, } from '@ktx/context/project';
 import { strToU8, zipSync } from 'fflate';
-import { bold, dim, green } from './io/symbols.js';
-import { withMultiselectNavigation } from './prompt-navigation.js';
 import { createKtxSetupPromptAdapter, createKtxSetupUiAdapter, } from './setup-prompts.js';
 import { readKtxMcpDaemonStatus } from './managed-mcp-daemon.js';
+const MCP_DAEMON_REQUIRED_NOTICE = 'mcp-daemon-required';
+function isWritableTtyOutput(output) {
+    return (output.isTTY === true &&
+        typeof output.on === 'function' &&
+        typeof output.columns !== 'undefined');
+}
+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 });
+        return;
+    }
+    io.stdout.write(`\n${message}\n`);
+}
+function writeSetupOutro(io, message) {
+    if (isWritableTtyOutput(io.stdout)) {
+        outro(message, { output: io.stdout });
+        return;
+    }
+    io.stdout.write(`\n${message}\n`);
+}
+const STEP_HEADING_RE = /^(\d+)\. (.+)$/;
+const ACTION_MARKER_RE = /^(RUN|PASTE|USE|OPEN):$/;
+export function createAgentNextActionsLineFormatter(stdout) {
+    const maybeHasColors = stdout.hasColors;
+    const supportsColor = typeof maybeHasColors === 'function' && Boolean(maybeHasColors.call(stdout));
+    if (!supportsColor)
+        return (line) => line;
+    const homeDir = process.env.HOME ? resolve(process.env.HOME) : '';
+    const styleOptions = { validateStream: false };
+    const dim = (s) => styleText('dim', s, styleOptions);
+    const bold = (s) => styleText('bold', s, styleOptions);
+    const cyanBold = (s) => styleText(['cyan', 'bold'], s, styleOptions);
+    const dimCyan = (s) => styleText(['dim', 'cyan'], s, styleOptions);
+    const shortenPath = (path) => {
+        if (!homeDir)
+            return path;
+        if (path === homeDir)
+            return '~';
+        if (path.startsWith(`${homeDir}/`))
+            return `~/${path.slice(homeDir.length + 1)}`;
+        return path;
+    };
+    return (rawLine) => {
+        if (rawLine.length === 0 || rawLine.includes('['))
+            return rawLine;
+        const heading = rawLine.match(STEP_HEADING_RE);
+        if (heading) {
+            return `${cyanBold(heading[1])}  ${bold(heading[2])}`;
+        }
+        if (!rawLine.startsWith('  '))
+            return rawLine;
+        const body = rawLine.slice(2);
+        if (ACTION_MARKER_RE.test(body)) {
+            return `   ${dim(body)}`;
+        }
+        if (body.endsWith('.zip') && (body.startsWith('/') || body.startsWith('~'))) {
+            return `     ${dimCyan('•')}  ${shortenPath(body)}`;
+        }
+        if (body.includes(' > ')) {
+            return `   ${body.replaceAll(' > ', `  ${dim('›')}  `)}`;
+        }
+        return `   ${dim(body)}`;
+    };
+}
 async function readJsonObject(path) {
     if (!existsSync(path))
         return {};
@@ -158,7 +229,7 @@ async function installMcpClientConfig(input) {
     }
     const endpoint = await resolveMcpEndpoint(input.projectDir);
     if (!endpoint.running) {
-        notices.push('Run `ktx mcp start` to enable the configured KTX MCP server.');
+        notices.push(MCP_DAEMON_REQUIRED_NOTICE);
     }
     if (input.target === 'claude-code') {
         const config = claudeConfigPath(input.projectDir, input.scope);
@@ -171,16 +242,16 @@ async function installMcpClientConfig(input) {
         entries.push({ kind: 'json-key', path: config.path, jsonPath: config.jsonPath });
     }
     else if (input.target === 'codex') {
-        snippets.push(`Codex MCP snippet for ~/.codex/config.toml:\n${codexSnippet(endpoint)}`);
+        snippets.push(`Add this Codex MCP snippet to ~/.codex/config.toml:\n${codexSnippet(endpoint)}`);
     }
     else if (input.target === 'opencode') {
         const path = input.scope === 'global'
             ? '~/.config/opencode/opencode.json'
             : relative(input.projectDir, join(input.projectDir, 'opencode.json'));
-        snippets.push(`opencode MCP snippet for ${path}:\n${opencodeSnippet(endpoint)}`);
+        snippets.push(`Add this OpenCode MCP snippet to ${path}:\n${opencodeSnippet(endpoint)}`);
     }
     else if (input.target === 'universal') {
-        snippets.push(universalMcpSnippet(endpoint));
+        snippets.push(`Use this universal MCP endpoint with unsupported MCP clients:\n${universalMcpSnippet(endpoint)}`);
     }
     return { entries, snippets, notices };
 }
@@ -202,8 +273,11 @@ function plannedMcpJsonEntries(input) {
 export function agentInstallManifestPath(projectDir) {
     return join(resolve(projectDir), '.ktx/agents/install-manifest.json');
 }
-function claudeDesktopPluginPath(projectDir) {
-    return join(resolve(projectDir), '.ktx/agents/claude/ktx-plugin.zip');
+function claudeDesktopAnalyticsSkillBundlePath(projectDir) {
+    return join(resolve(projectDir), '.ktx/agents/claude/ktx-analytics.zip');
+}
+function claudeDesktopAdminSkillBundlePath(projectDir) {
+    return join(resolve(projectDir), '.ktx/agents/claude/ktx.zip');
 }
 function claudeDesktopLauncherPath(projectDir) {
     return join(resolve(projectDir), '.ktx/agents/claude/ktx-plugin-runner.sh');
@@ -241,7 +315,20 @@ export function plannedKtxAgentFiles(input) {
         if (input.target === 'claude-desktop') {
             return [
                 { kind: 'file', path: claudeDesktopLauncherPath(input.projectDir), role: 'launcher' },
-                { kind: 'file', path: claudeDesktopPluginPath(input.projectDir), role: 'claude-plugin' },
+                {
+                    kind: 'file',
+                    path: claudeDesktopAnalyticsSkillBundlePath(input.projectDir),
+                    role: 'claude-desktop-skill-bundle',
+                },
+                ...(withAdminCli
+                    ? [
+                        {
+                            kind: 'file',
+                            path: claudeDesktopAdminSkillBundlePath(input.projectDir),
+                            role: 'claude-desktop-skill-bundle',
+                        },
+                    ]
+                    : []),
             ];
         }
         throw new Error(`Global ${input.target} installation is not supported; omit --global.`);
@@ -361,36 +448,7 @@ function cliInstructionContent(input) {
         '',
     ].join('\n');
 }
-function claudePluginJsonContent() {
-    return `${JSON.stringify({
-        name: 'ktx',
-        version: '0.0.0-local',
-        description: 'KTX analytics workflow guidance and local MCP tools.',
-    }, null, 2)}\n`;
-}
-function claudePluginVersionContent() {
-    return `${JSON.stringify({ version: '0.0.0-local' }, null, 2)}\n`;
-}
-function claudePluginSetupContent(input) {
-    return [
-        '# KTX Claude Plugin',
-        '',
-        'Install this plugin ZIP from Claude Desktop to load the KTX analytics skill.',
-        '',
-        `KTX project: \`${input.projectDir}\``,
-        '',
-        'Included:',
-        '',
-        '- `ktx-analytics` skill for the MCP analytics workflow',
-        ...(input.withAdminCli ? ['- `ktx` admin CLI skill for KTX maintenance commands'] : []),
-        '',
-        'The KTX MCP server is registered separately in `claude_desktop_config.json` by `ktx setup` and runs as a local stdio child of Claude Desktop — no daemon to start.',
-        '',
-        'If this checkout or project directory moves, rerun `ktx setup --agents` and reinstall the regenerated plugin.',
-        '',
-    ].join('\n');
-}
-function claudePluginLauncherContent(input) {
+function claudeDesktopLauncherContent(input) {
     const binPath = input.launcher.args[0];
     if (!binPath) {
         throw new Error('Expected KTX CLI launcher to include a bin path.');
@@ -437,28 +495,33 @@ function claudePluginLauncherContent(input) {
         '  run_with_node "$(command -v node)" "$@"',
         'fi',
         '',
-        'echo "KTX plugin could not find Node.js. Set KTX_NODE to a Node executable and reinstall the plugin." >&2',
+        'echo "KTX Claude Desktop launcher could not find Node.js. Set KTX_NODE to a Node executable and rerun ktx setup --agents." >&2',
         'exit 127',
         '',
     ].join('\n');
 }
-async function writeClaudeDesktopPlugin(input) {
-    const withAdminCli = input.mode === 'mcp-cli';
+async function writeClaudeDesktopSkillBundle(input) {
+    const content = input.skillName === 'ktx-analytics'
+        ? await readAnalyticsSkillContent()
+        : cliInstructionContent({ projectDir: input.projectDir, launcher: input.launcher });
     const files = {
-        '.claude-plugin/plugin.json': strToU8(claudePluginJsonContent()),
-        'version.json': strToU8(claudePluginVersionContent()),
-        'skills/ktx-analytics/SKILL.md': strToU8(await readAnalyticsSkillContent()),
-        'SETUP.md': strToU8(claudePluginSetupContent({ projectDir: input.projectDir, withAdminCli })),
+        [`${input.skillName}/SKILL.md`]: strToU8(content),
     };
-    if (withAdminCli) {
-        files['skills/ktx/SKILL.md'] = strToU8(cliInstructionContent({ projectDir: input.projectDir, launcher: input.launcher }));
-    }
     await mkdir(dirname(input.path), { recursive: true });
     await writeFile(input.path, Buffer.from(zipSync(files)));
 }
+function claudeDesktopSkillNameForBundle(path) {
+    if (path.endsWith('/ktx-analytics.zip')) {
+        return 'ktx-analytics';
+    }
+    if (path.endsWith('/ktx.zip')) {
+        return 'ktx';
+    }
+    throw new Error(`Unsupported Claude Desktop skill bundle path: ${path}`);
+}
 async function writeClaudeDesktopLauncher(input) {
     await mkdir(dirname(input.path), { recursive: true });
-    await writeFile(input.path, claudePluginLauncherContent({ launcher: input.launcher }), 'utf-8');
+    await writeFile(input.path, claudeDesktopLauncherContent({ launcher: input.launcher }), 'utf-8');
     await chmod(input.path, 0o755);
 }
 function ruleInstructionContent(input) {
@@ -550,16 +613,8 @@ const targetDisplayNames = {
     opencode: 'OpenCode',
     universal: 'Universal .agents',
 };
-const fileEntryLabels = {
-    'claude-code': 'Skill installed',
-    'claude-desktop': 'Skill installed',
-    codex: 'Skill installed',
-    cursor: 'Rule installed',
-    opencode: 'Command installed',
-    universal: 'Skill installed',
-};
-function mcpEntryLabel(entry) {
-    return `MCP config installed — connects client agents to KTX MCP tools (${entry.jsonPath.join('.')})`;
+export function targetDisplayName(target) {
+    return Object.hasOwn(targetDisplayNames, target) ? targetDisplayNames[target] : target;
 }
 function targetSupportsGlobalScope(target) {
     return target === 'claude-code' || target === 'codex';
@@ -567,7 +622,61 @@ function targetSupportsGlobalScope(target) {
 function effectiveInstallScope(target, requestedScope) {
     return target === 'claude-desktop' ? 'global' : requestedScope;
 }
-export function formatInstallSummary(installs, entries, projectDir) {
+function scopeDisplayName(scope) {
+    if (scope === 'project')
+        return 'Project scope';
+    if (scope === 'global')
+        return 'Global scope';
+    return 'Local scope';
+}
+function targetUsesHttpMcpDaemon(target) {
+    return target !== 'claude-desktop';
+}
+function manualMcpConfigInstruction(target, scope) {
+    if (target === 'codex') {
+        return 'Add the snippet shown below to ~/.codex/config.toml.';
+    }
+    if (target === 'opencode') {
+        return scope === 'global'
+            ? 'Add the snippet shown below to ~/.config/opencode/opencode.json.'
+            : 'Add the snippet shown below to opencode.json.';
+    }
+    if (target === 'universal') {
+        return 'Use the printed endpoint with unsupported MCP clients.';
+    }
+    return 'Add the printed snippet manually.';
+}
+function guidanceInstallLine(target) {
+    if (target === 'codex')
+        return 'Codex guidance installed';
+    if (target === 'cursor')
+        return 'Cursor rules installed';
+    if (target === 'opencode')
+        return 'OpenCode commands installed';
+    if (target === 'universal')
+        return '.agents guidance installed';
+    return 'Agent guidance installed';
+}
+function hasEntryRole(entries, role) {
+    return entries.some((entry) => entry.kind === 'file' && entry.role === role);
+}
+function hasAdminCliEntries(entries) {
+    return entries.some((entry) => entry.kind === 'file' &&
+        (entry.role === 'skill' || entry.role === 'rule' || entry.role === undefined));
+}
+function formatInlinePath(path) {
+    const home = process.env.HOME;
+    if (!home)
+        return path;
+    const resolvedHome = resolve(home);
+    if (path === resolvedHome)
+        return '~';
+    if (path.startsWith(`${resolvedHome}/`)) {
+        return `~/${relative(resolvedHome, path)}`;
+    }
+    return path;
+}
+export function formatInstallSummaryLines(installs, entries, projectDir) {
     const entriesByTarget = new Map();
     for (const install of installs) {
         const plannedFilePaths = new Set(plannedKtxAgentFiles({ projectDir, ...install })
@@ -580,45 +689,196 @@ export function formatInstallSummary(installs, entries, projectDir) {
         const plannedMcpKeys = new Set(plannedMcpJsonEntries({ projectDir, ...install }).map(entryKey));
         mcpEntriesByTarget.set(install.target, entries.filter((entry) => entry.kind === 'json-key' && plannedMcpKeys.has(entryKey(entry))));
     }
-    const fileHints = {
-        skill: 'teaches admin agents which KTX CLI commands to run',
-        rule: 'tells admin agents when to use KTX CLI',
-        'analytics-skill': 'teaches your agent the KTX MCP analytics workflow',
-        'claude-plugin': 'bundles KTX skills for Claude Desktop (MCP server is registered in claude_desktop_config.json)',
-        launcher: 'runs the local KTX CLI with an available Node.js for Claude Desktop',
-    };
-    const lines = [];
-    for (const install of installs) {
+    return installs.map((install) => {
         const targetEntries = entriesByTarget.get(install.target) ?? [];
-        lines.push(`  ${targetDisplayNames[install.target]}`);
-        for (const entry of targetEntries) {
-            if (entry.kind === 'file') {
-                const isRule = entry.role === 'rule' || (!entry.role && fileEntryLabels[install.target] === 'Rule installed');
-                const label = entry.role === 'analytics-skill'
-                    ? 'Analytics skill installed'
-                    : entry.role === 'claude-plugin'
-                        ? 'Claude plugin generated'
-                        : entry.role === 'launcher'
-                            ? 'Launcher installed'
-                            : isRule
-                                ? 'Rule installed'
-                                : fileEntryLabels[install.target];
-                const hint = fileHints[isRule ? 'rule' : (entry.role ?? 'skill')] ?? '';
-                lines.push(`    + ${label} — ${hint}`);
-                if (entry.role !== 'claude-plugin') {
-                    const displayPath = install.scope === 'global' ? entry.path : relative(projectDir, entry.path);
-                    lines.push(`      ${displayPath}`);
+        const mcpEntry = mcpEntriesByTarget
+            .get(install.target)
+            ?.find((entry) => entry.kind === 'json-key');
+        const lines = [];
+        if (mcpEntry) {
+            lines.push(formatInlinePath(mcpEntry.path));
+        }
+        else if (install.target !== 'claude-desktop') {
+            lines.push(manualMcpConfigInstruction(install.target, install.scope));
+        }
+        if (targetUsesHttpMcpDaemon(install.target)) {
+            lines.push('Requires MCP to be started.');
+        }
+        const hasAnalytics = hasEntryRole(targetEntries, 'analytics-skill');
+        const hasAdmin = hasAdminCliEntries(targetEntries);
+        const claudeDesktopSkillBundles = targetEntries.filter((entry) => entry.kind === 'file' && entry.role === 'claude-desktop-skill-bundle');
+        if (install.target === 'claude-code') {
+            if (hasAnalytics) {
+                lines.push('Analytics skill installed.');
+            }
+            if (hasAdmin) {
+                lines.push('Admin CLI skill installed.');
+            }
+        }
+        else if (install.target === 'claude-desktop') {
+            if (claudeDesktopSkillBundles.length > 0) {
+                lines.push('Skill bundles:');
+                for (const bundle of claudeDesktopSkillBundles) {
+                    lines.push(`  ${bundle.path}`);
                 }
             }
         }
-        for (const entry of mcpEntriesByTarget
-            .get(install.target)
-            ?.filter((entry) => entry.kind === 'json-key') ?? []) {
-            const displayPath = install.scope === 'global' ? entry.path : relative(projectDir, entry.path);
-            lines.push(`    + ${mcpEntryLabel(entry)}`);
-            lines.push(`      ${displayPath}`);
+        else if (hasAnalytics || hasAdmin) {
+            lines.push(`${guidanceInstallLine(install.target)}.`);
+        }
+        if (hasEntryRole(targetEntries, 'launcher')) {
+            lines.push('Starts KTX over stdio from Claude Desktop.');
+        }
+        return {
+            title: `${targetDisplayName(install.target)} · ${scopeDisplayName(install.scope)}`,
+            lines,
+        };
+    });
+}
+function claudeDesktopSkillBundlePathsForInstalls(projectDir, installs) {
+    return installs
+        .filter((install) => install.target === 'claude-desktop')
+        .flatMap((install) => plannedKtxAgentFiles({ projectDir, ...install }))
+        .filter((entry) => entry.kind === 'file' && entry.role === 'claude-desktop-skill-bundle')
+        .map((entry) => entry.path);
+}
+function humanList(values) {
+    if (values.length <= 2) {
+        return values.join(' and ');
+    }
+    return `${values.slice(0, -1).join(', ')}, and ${values[values.length - 1]}`;
+}
+function pushBlankLine(lines) {
+    if (lines.length > 0 && lines[lines.length - 1] !== '') {
+        lines.push('');
+    }
+}
+function trimTrailingBlankLines(lines) {
+    while (lines[lines.length - 1] === '') {
+        lines.pop();
+    }
+}
+function manualActionFromSnippet(snippet) {
+    const [label = '', ...body] = snippet.split('\n');
+    const codexPrefix = 'Add this Codex MCP snippet to ~/.codex/config.toml:';
+    if (label === codexPrefix) {
+        return {
+            title: 'Configure Codex',
+            instruction: 'Open ~/.codex/config.toml, then paste this block:',
+            marker: 'PASTE',
+            body,
+        };
+    }
+    const opencodeMatch = label.match(/^Add this OpenCode MCP snippet to (.+):$/);
+    if (opencodeMatch) {
+        return {
+            title: 'Configure OpenCode',
+            instruction: `Open ${opencodeMatch[1]}, then paste this block:`,
+            marker: 'PASTE',
+            body,
+        };
+    }
+    if (label === 'Use this universal MCP endpoint with unsupported MCP clients:') {
+        return {
+            title: 'Configure unsupported MCP clients',
+            instruction: 'Use this endpoint when setting up unsupported MCP clients:',
+            marker: 'USE',
+            body,
+        };
+    }
+    return {
+        title: 'Configure MCP client',
+        instruction: label,
+        marker: 'PASTE',
+        body,
+    };
+}
+function formatAgentNextActions(input) {
+    const projectDir = resolve(input.projectDir);
+    const lines = [];
+    let step = 1;
+    for (const snippet of input.snippets) {
+        const action = manualActionFromSnippet(snippet);
+        lines.push(`${step}. ${action.title}`);
+        lines.push(`  ${action.instruction}`);
+        if (action.body.length > 0) {
+            lines.push('', `  ${action.marker}:`);
+        }
+        for (const line of action.body) {
+            lines.push(`  ${line}`);
         }
+        pushBlankLine(lines);
+        step += 1;
     }
+    const httpTargets = input.installs
+        .filter((install) => targetUsesHttpMcpDaemon(install.target))
+        .map((install) => targetDisplayName(install.target));
+    if (input.notices.length > 0 && httpTargets.length > 0) {
+        lines.push(`${step}. Start MCP`);
+        lines.push(`  Run this command before using ${humanList(httpTargets)}:`);
+        lines.push('');
+        lines.push('  RUN:');
+        lines.push(`  ktx mcp start --project-dir ${projectDir}`);
+        lines.push('');
+        lines.push('  If you need to stop MCP later:');
+        lines.push(`  ktx mcp stop --project-dir ${projectDir}`);
+        pushBlankLine(lines);
+        step += 1;
+    }
+    const claudeCodeInstall = input.installs.find((install) => install.target === 'claude-code');
+    if (claudeCodeInstall) {
+        lines.push(`${step}. Open Claude Code`);
+        if (claudeCodeInstall.scope === 'project') {
+            lines.push('  Open Claude Code from the KTX project directory:');
+            lines.push('');
+            lines.push('  RUN:');
+            lines.push(`  cd ${shellScriptQuote(projectDir)}`);
+            lines.push('  claude');
+        }
+        else {
+            lines.push('  RUN:');
+            lines.push('  claude');
+        }
+        pushBlankLine(lines);
+        step += 1;
+    }
+    const cursorInstall = input.installs.find((install) => install.target === 'cursor');
+    if (cursorInstall) {
+        lines.push(`${step}. Open Cursor`);
+        if (cursorInstall.scope === 'project') {
+            lines.push('  Open Cursor from the KTX project directory:');
+            lines.push('');
+            lines.push('  OPEN:');
+            lines.push(`  ${projectDir}`);
+        }
+        else {
+            lines.push('  Open Cursor.');
+        }
+        pushBlankLine(lines);
+        step += 1;
+    }
+    if (input.installs.some((install) => install.target === 'claude-desktop')) {
+        lines.push(`${step}. Restart Claude Desktop`);
+        lines.push('  Claude Desktop loads KTX MCP after restart.');
+        pushBlankLine(lines);
+        step += 1;
+        const skillBundlePaths = claudeDesktopSkillBundlePathsForInstalls(projectDir, input.installs);
+        if (skillBundlePaths.length > 0) {
+            lines.push(`${step}. Upload Claude Desktop skills`);
+            lines.push('  Open Claude Desktop: Customize > Skills > + > Create skill > Upload a skill.');
+            lines.push(skillBundlePaths.length === 1 ? '  Upload this file:' : '  Upload each file separately:');
+            for (const path of skillBundlePaths) {
+                lines.push(`  ${path}`);
+            }
+            lines.push('  Toggle the uploaded KTX skills on.');
+            pushBlankLine(lines);
+            step += 1;
+        }
+    }
+    if (lines.length === 0) {
+        lines.push('Open your configured agent and ask a data question.');
+    }
+    trimTrailingBlankLines(lines);
     return lines.join('\n');
 }
 async function installTarget(input) {
@@ -631,11 +891,11 @@ async function installTarget(input) {
             await writeClaudeDesktopLauncher({ path: entry.path, launcher });
             continue;
         }
-        if (entry.role === 'claude-plugin') {
-            await writeClaudeDesktopPlugin({
+        if (entry.role === 'claude-desktop-skill-bundle') {
+            await writeClaudeDesktopSkillBundle({
                 projectDir: input.projectDir,
                 path: entry.path,
-                mode: input.mode,
+                skillName: claudeDesktopSkillNameForBundle(entry.path),
                 launcher,
             });
             continue;
@@ -664,13 +924,24 @@ 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: 'How should client agents connect to this KTX project?',
+            message: 'What should agents be allowed to do with this KTX project?',
             options: [
-                { value: 'mcp', label: 'MCP tools + analytics skill' },
-                { value: 'mcp-cli', label: 'MCP tools + analytics skill + admin CLI skill' },
+                {
+                    value: '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',
+                    hint: 'Adds an admin CLI skill so agents can run ktx status, sl, wiki, and setup commands.',
+                },
             ],
         }));
     if (mode === 'back')
@@ -680,7 +951,7 @@ export async function runKtxSetupAgentsStep(args, io, deps = {}) {
         : args.inputMode === 'disabled'
             ? []
             : (await prompts.multiselect({
-                message: withMultiselectNavigation('Which agent targets should KTX install?'),
+                message: 'Which agent targets should KTX install?',
                 options: [
                     { value: 'claude-code', label: 'Claude Code' },
                     { value: 'claude-desktop', label: 'Claude Desktop' },
@@ -694,7 +965,9 @@ export async function runKtxSetupAgentsStep(args, io, deps = {}) {
     if (targets.includes('back'))
         return { status: 'back', projectDir: args.projectDir };
     if (targets.length === 0) {
-        io.stderr.write('Missing agent target: pass --target or use interactive setup.\n');
+        io.stderr.write(args.inputMode === 'disabled'
+            ? 'Run in a TTY, or pass --target <target>.\n'
+            : 'Missing agent target: pass --target or use interactive setup.\n');
         return { status: 'missing-input', projectDir: args.projectDir };
     }
     const scopeTargets = targets.filter((target) => target !== 'claude-desktop');
@@ -703,10 +976,18 @@ export async function runKtxSetupAgentsStep(args, io, deps = {}) {
         scopeTargets.length > 0 &&
         scopeTargets.every(targetSupportsGlobalScope)
         ? (await prompts.select({
-            message: 'Where should KTX install supported agent config?',
+            message: `Where should KTX install supported agent config?\n\nKTX project: ${resolve(args.projectDir)}`,
             options: [
-                { value: 'project', label: 'Project' },
-                { value: 'global', label: 'Global' },
+                {
+                    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;
@@ -716,7 +997,6 @@ export async function runKtxSetupAgentsStep(args, io, deps = {}) {
     const entries = [];
     const snippets = [];
     const notices = new Set();
-    let claudeDesktopTutorial;
     try {
         for (const install of installs) {
             const targetEntries = await installTarget({ projectDir: args.projectDir, ...install });
@@ -731,41 +1011,26 @@ export async function runKtxSetupAgentsStep(args, io, deps = {}) {
                 snippets.push(snippet);
             for (const notice of mcpResult.notices)
                 notices.add(notice);
-            if (install.target === 'claude-desktop') {
-                const pluginEntry = targetEntries.find((entry) => entry.kind === 'file' && entry.role === 'claude-plugin');
-                const pluginPath = pluginEntry?.path ?? '';
-                const configPath = claudeDesktopConfigPath().path;
-                claudeDesktopTutorial = [
-                    `${green('✓')} ${bold('KTX MCP server registered')}`,
-                    `  ${dim(configPath)}`,
-                    '',
-                    bold('1. Restart Claude Desktop'),
-                    '   Quit and reopen so it picks up the new MCP server.',
-                    '',
-                    bold('2. Install the KTX plugin'),
-                    '   Open Claude Desktop → Settings → Plugins and install from file:',
-                    `   📦 ${dim(pluginPath)}`,
-                ].join('\n');
-            }
         }
         await writeManifest(args.projectDir, mergeManifest(args.projectDir, await readKtxAgentInstallManifest(args.projectDir), installs, entries));
         await markAgentsComplete(args.projectDir);
         const setupUi = createKtxSetupUiAdapter();
-        setupUi.note(formatInstallSummary(installs, entries, args.projectDir), 'Agent integration complete', io);
-        if (claudeDesktopTutorial) {
-            setupUi.note(claudeDesktopTutorial, 'Finish Claude Desktop setup', io, {
-                format: (line) => line,
-            });
+        for (const summary of formatInstallSummaryLines(installs, entries, args.projectDir)) {
+            writeSetupStep(io, summary.lines.length > 0 ? `${summary.title}\n${summary.lines.join('\n')}` : summary.title);
         }
-        const nextStepBlocks = [];
-        for (const notice of notices)
-            nextStepBlocks.push(notice);
-        for (const snippet of snippets)
-            nextStepBlocks.push(snippet);
-        if (nextStepBlocks.length > 0) {
-            setupUi.note(nextStepBlocks.join('\n\n'), 'Next steps', io, { format: bold });
+        const nextActions = formatAgentNextActions({
+            projectDir: args.projectDir,
+            installs,
+            notices: [...notices],
+            snippets,
+        });
+        if (args.showNextActions !== false) {
+            setupUi.note(nextActions, 'Required before using agents', io, {
+                format: createAgentNextActionsLineFormatter(io.stdout),
+            });
+            writeSetupOutro(io, 'All set.');
         }
-        return { status: 'ready', projectDir: args.projectDir, installs };
+        return { status: 'ready', projectDir: args.projectDir, installs, nextActions };
     }
     catch (error) {
         io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);