@kaelio/ktx 0.1.0-rc.6 → 0.1.1

package/dist/setup-agents.test.js

@@ -4,7 +4,7 @@ import { join } from 'node:path';
 import { readKtxSetupState } from '@ktx/context/project';
 import { strFromU8, unzipSync } from 'fflate';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { formatInstallSummary, plannedKtxAgentFiles, readKtxAgentInstallManifest, removeKtxAgentInstall, runKtxSetupAgentsStep, } from './setup-agents.js';
+import { createAgentNextActionsLineFormatter, formatInstallSummaryLines, plannedKtxAgentFiles, readKtxAgentInstallManifest, removeKtxAgentInstall, runKtxSetupAgentsStep, } from './setup-agents.js';
 function makeIo() {
     let stdout = '';
     let stderr = '';
@@ -72,7 +72,11 @@ describe('setup agents', () => {
         ]);
         expect(plannedKtxAgentFiles({ projectDir: tempDir, target: 'claude-desktop', scope: 'global', mode: 'mcp' })).toEqual([
             { kind: 'file', path: join(tempDir, '.ktx/agents/claude/ktx-plugin-runner.sh'), role: 'launcher' },
-            { kind: 'file', path: join(tempDir, '.ktx/agents/claude/ktx-plugin.zip'), role: 'claude-plugin' },
+            {
+                kind: 'file',
+                path: join(tempDir, '.ktx/agents/claude/ktx-analytics.zip'),
+                role: 'claude-desktop-skill-bundle',
+            },
         ]);
         expect(plannedKtxAgentFiles({ projectDir: tempDir, target: 'codex', scope: 'project', mode: 'mcp' })).toEqual([
             { kind: 'file', path: join(tempDir, '.agents/skills/ktx-analytics/SKILL.md'), role: 'analytics-skill' },
@@ -112,7 +116,16 @@ describe('setup agents', () => {
         ]);
         expect(plannedKtxAgentFiles({ projectDir: tempDir, target: 'claude-desktop', scope: 'global', mode: 'mcp-cli' })).toEqual([
             { kind: 'file', path: join(tempDir, '.ktx/agents/claude/ktx-plugin-runner.sh'), role: 'launcher' },
-            { kind: 'file', path: join(tempDir, '.ktx/agents/claude/ktx-plugin.zip'), role: 'claude-plugin' },
+            {
+                kind: 'file',
+                path: join(tempDir, '.ktx/agents/claude/ktx-analytics.zip'),
+                role: 'claude-desktop-skill-bundle',
+            },
+            {
+                kind: 'file',
+                path: join(tempDir, '.ktx/agents/claude/ktx.zip'),
+                role: 'claude-desktop-skill-bundle',
+            },
         ]);
     });
     it('installs target files, writes a manifest, and marks agents complete', async () => {
@@ -126,7 +139,7 @@ describe('setup agents', () => {
             scope: 'project',
             mode: 'mcp-cli',
             skipAgents: false,
-        }, io.io)).resolves.toEqual({
+        }, io.io)).resolves.toMatchObject({
             status: 'ready',
             projectDir: tempDir,
             installs: [{ target: 'universal', scope: 'project', mode: 'mcp-cli' }],
@@ -150,6 +163,88 @@ describe('setup agents', () => {
         expect(await readKtxSetupState(tempDir)).toEqual({ completed_steps: ['agents'] });
         expect(io.stderr()).toBe('');
     });
+    it('installs a specified target in non-interactive mode without --yes', async () => {
+        const io = makeIo();
+        await expect(runKtxSetupAgentsStep({
+            projectDir: tempDir,
+            inputMode: 'disabled',
+            yes: false,
+            agents: true,
+            target: 'claude-code',
+            scope: 'project',
+            mode: 'mcp',
+            skipAgents: false,
+        }, io.io)).resolves.toMatchObject({
+            status: 'ready',
+            projectDir: tempDir,
+            installs: [{ target: 'claude-code', scope: 'project', mode: 'mcp' }],
+        });
+        await expect(stat(join(tempDir, '.claude/skills/ktx-analytics/SKILL.md'))).resolves.toBeDefined();
+        const mcpConfig = JSON.parse(await readFile(join(tempDir, '.mcp.json'), 'utf-8'));
+        expect(mcpConfig.mcpServers).toHaveProperty('ktx');
+        expect(io.stderr()).toBe('');
+    });
+    it('prints concrete target guidance when non-interactive agent setup has no target', async () => {
+        const io = makeIo();
+        await expect(runKtxSetupAgentsStep({
+            projectDir: tempDir,
+            inputMode: 'disabled',
+            yes: false,
+            agents: true,
+            scope: 'project',
+            mode: 'mcp',
+            skipAgents: false,
+        }, io.io)).resolves.toEqual({ status: 'missing-input', projectDir: tempDir });
+        expect(io.stderr()).toBe('Run in a TTY, or pass --target <target>.\n');
+    });
+    it('prints standalone agent next actions after successful installation', async () => {
+        const io = makeIo();
+        const result = await runKtxSetupAgentsStep({
+            projectDir: tempDir,
+            inputMode: 'disabled',
+            yes: true,
+            agents: true,
+            target: 'claude-code',
+            scope: 'project',
+            mode: 'mcp-cli',
+            skipAgents: false,
+        }, io.io);
+        expect(result).toMatchObject({
+            status: 'ready',
+            nextActions: expect.stringContaining('Run this command before using Claude Code:'),
+        });
+        expect(io.stdout()).toContain('Required before using agents');
+        expect(io.stdout()).toContain('Run this command before using Claude Code:');
+        expect(io.stdout()).toContain('RUN:');
+        expect(io.stdout()).toContain(`ktx mcp start --project-dir ${tempDir}`);
+        expect(io.stdout()).toContain('If you need to stop MCP later:');
+        expect(io.stdout()).toContain(`ktx mcp stop --project-dir ${tempDir}`);
+        expect(io.stdout()).toContain('All set.');
+        expect(io.stdout()).not.toContain('Finish agent setup');
+        expect(io.stdout()).not.toContain('Next actions');
+    });
+    it('can return agent next actions without printing them', async () => {
+        const io = makeIo();
+        const result = await runKtxSetupAgentsStep({
+            projectDir: tempDir,
+            inputMode: 'disabled',
+            yes: true,
+            agents: true,
+            target: 'claude-code',
+            scope: 'project',
+            mode: 'mcp-cli',
+            skipAgents: false,
+            showNextActions: false,
+        }, io.io);
+        expect(result).toMatchObject({
+            status: 'ready',
+            nextActions: expect.stringContaining(`ktx mcp start --project-dir ${tempDir}`),
+        });
+        expect(io.stdout()).toContain('Claude Code · Project scope');
+        expect(io.stdout()).not.toContain('Agent integration complete');
+        expect(io.stdout()).not.toContain('Required before using agents');
+        expect(io.stdout()).not.toContain('All set.');
+    });
     it('installs the analytics skill from the runtime asset', async () => {
         const io = makeIo();
         await expect(runKtxSetupAgentsStep({
@@ -207,7 +302,6 @@ describe('setup agents', () => {
         expect(await readKtxAgentInstallManifest(tempDir)).toMatchObject({
             entries: expect.arrayContaining([{ kind: 'json-key', path: join(tempDir, '.mcp.json'), jsonPath: ['mcpServers', 'ktx'] }]),
         });
-        expect(io.stdout()).toContain('Run `ktx mcp start` to enable the configured KTX MCP server.');
     });
     it('prompts for MCP-first client agent connection mode in interactive setup', async () => {
         const io = makeIo();
@@ -229,10 +323,18 @@ describe('setup agents', () => {
             installs: [{ target: 'claude-code', scope: 'project', mode: 'mcp' }],
         });
         expect(prompts.select).toHaveBeenCalledWith({
-            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.',
+                },
             ],
         });
         expect(prompts.multiselect).toHaveBeenCalledWith(expect.objectContaining({
@@ -263,10 +365,18 @@ describe('setup agents', () => {
                 installs: [{ target: 'claude-code', scope: 'global', mode: 'mcp' }],
             });
             expect(prompts.select).toHaveBeenCalledWith({
-                message: 'Where should KTX install supported agent config?',
+                message: `Where should KTX install supported agent config?\n\nKTX project: ${tempDir}`,
                 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.',
+                    },
                 ],
             });
         }
@@ -275,7 +385,7 @@ describe('setup agents', () => {
             await rm(home, { recursive: true, force: true });
         }
     });
-    it('registers Claude Desktop MCP via claude_desktop_config.json and ships a skills-only plugin', async () => {
+    it('registers Claude Desktop MCP and ships an uploadable analytics skill zip', async () => {
         const home = await mkdtemp(join(tmpdir(), 'ktx-setup-agents-home-'));
         const previousHome = process.env.HOME;
         const envSnapshot = captureEnvKeys(process.env, ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY']);
@@ -298,9 +408,11 @@ describe('setup agents', () => {
                 status: 'ready',
                 installs: [{ target: 'claude-desktop', scope: 'global', mode: 'mcp' }],
             });
-            const pluginPath = join(tempDir, '.ktx/agents/claude/ktx-plugin.zip');
+            const analyticsSkillPath = join(tempDir, '.ktx/agents/claude/ktx-analytics.zip');
+            const adminSkillPath = join(tempDir, '.ktx/agents/claude/ktx.zip');
             const launcherPath = join(tempDir, '.ktx/agents/claude/ktx-plugin-runner.sh');
-            await expect(stat(pluginPath)).resolves.toBeDefined();
+            await expect(stat(analyticsSkillPath)).resolves.toBeDefined();
+            await expect(stat(adminSkillPath)).rejects.toThrow();
             const launcherStat = await stat(launcherPath);
             expect(launcherStat.mode & 0o111).not.toBe(0);
             const launcher = await readFile(launcherPath, 'utf-8');
@@ -312,18 +424,21 @@ describe('setup agents', () => {
                 command: launcherPath,
                 args: ['--project-dir', tempDir, 'mcp', 'stdio'],
             });
-            expect(await readZipText(pluginPath, '.claude-plugin/plugin.json')).toContain('"name": "ktx"');
-            await expect(readZipText(pluginPath, '.mcp.json')).rejects.toThrow('Missing zip entry');
-            expect(await readZipText(pluginPath, 'skills/ktx-analytics/SKILL.md')).toContain('KTX Analytics Workflow');
-            const setupMd = await readZipText(pluginPath, 'SETUP.md');
-            expect(setupMd).not.toContain('ktx mcp start');
-            expect(setupMd).toContain('claude_desktop_config.json');
-            await expect(readZipText(pluginPath, 'skills/ktx/SKILL.md')).rejects.toThrow('Missing zip entry');
-            expect(io.stdout()).toContain('Claude plugin generated');
-            expect(io.stdout()).toContain('.ktx/agents/claude/ktx-plugin.zip');
-            expect(io.stdout()).toContain('KTX MCP server registered');
+            expect(await readZipText(analyticsSkillPath, 'ktx-analytics/SKILL.md')).toContain('KTX Analytics Workflow');
+            await expect(readZipText(analyticsSkillPath, 'ktx/SKILL.md')).rejects.toThrow('Missing zip entry');
+            await expect(readZipText(analyticsSkillPath, '.claude-plugin/plugin.json')).rejects.toThrow('Missing zip entry');
+            await expect(readZipText(analyticsSkillPath, 'skills/ktx-analytics/SKILL.md')).rejects.toThrow('Missing zip entry');
+            expect(io.stdout()).toContain('Claude Desktop');
+            expect(io.stdout()).toContain(analyticsSkillPath);
+            expect(io.stdout()).not.toContain(adminSkillPath);
             expect(io.stdout()).toContain('claude_desktop_config.json');
-            expect(io.stdout()).toContain('Restart Claude Desktop');
+            expect(io.stdout()).toContain('Required before using agents');
+            expect(io.stdout()).toContain('1. Restart Claude Desktop');
+            expect(io.stdout()).toContain('Claude Desktop loads KTX MCP after restart.');
+            expect(io.stdout()).toContain('2. Upload Claude Desktop skills');
+            expect(io.stdout()).toContain('Customize > Skills > + > Create skill > Upload a skill');
+            expect(io.stdout()).toContain('Upload this file:');
+            expect(io.stdout()).toContain('Toggle the uploaded KTX skills on.');
             expect(io.stdout()).not.toContain('Run `ktx mcp start`');
         }
         finally {
@@ -374,7 +489,7 @@ describe('setup agents', () => {
             await rm(home, { recursive: true, force: true });
         }
     });
-    it('includes the admin CLI skill in the Claude Desktop plugin zip when requested', async () => {
+    it('includes an uploadable admin CLI skill zip for Claude Desktop when requested', async () => {
         const home = await mkdtemp(join(tmpdir(), 'ktx-setup-agents-home-'));
         const previousHome = process.env.HOME;
         process.env.HOME = home;
@@ -393,12 +508,18 @@ describe('setup agents', () => {
                 status: 'ready',
                 installs: [{ target: 'claude-desktop', scope: 'global', mode: 'mcp-cli' }],
             });
-            const pluginPath = join(tempDir, '.ktx/agents/claude/ktx-plugin.zip');
-            const adminSkill = await readZipText(pluginPath, 'skills/ktx/SKILL.md');
+            const analyticsSkillPath = join(tempDir, '.ktx/agents/claude/ktx-analytics.zip');
+            const adminSkillPath = join(tempDir, '.ktx/agents/claude/ktx.zip');
+            expect(await readZipText(analyticsSkillPath, 'ktx-analytics/SKILL.md')).toContain('KTX Analytics Workflow');
+            await expect(readZipText(analyticsSkillPath, 'ktx/SKILL.md')).rejects.toThrow('Missing zip entry');
+            const adminSkill = await readZipText(adminSkillPath, 'ktx/SKILL.md');
             expect(adminSkill).toContain(`--project-dir ${tempDir}`);
             expect(adminSkill).toContain('status --json');
-            expect(await readZipText(pluginPath, 'SETUP.md')).toContain('admin CLI skill');
-            await expect(readZipText(pluginPath, '.mcp.json')).rejects.toThrow('Missing zip entry');
+            await expect(readZipText(adminSkillPath, '.mcp.json')).rejects.toThrow('Missing zip entry');
+            await expect(readZipText(adminSkillPath, 'ktx-analytics/SKILL.md')).rejects.toThrow('Missing zip entry');
+            expect(io.stdout()).toContain(analyticsSkillPath);
+            expect(io.stdout()).toContain(adminSkillPath);
+            expect(io.stdout()).toContain('Upload each file separately:');
         }
         finally {
             process.env.HOME = previousHome;
@@ -455,6 +576,9 @@ describe('setup agents', () => {
         }, codexIo.io);
         expect(codexIo.stdout()).toContain('[mcp_servers.ktx]');
         expect(codexIo.stdout()).toContain('url = "http://localhost:7878/mcp"');
+        expect(codexIo.stdout()).toContain('1. Configure Codex');
+        expect(codexIo.stdout()).toContain('Open ~/.codex/config.toml, then paste this block:');
+        expect(codexIo.stdout()).toContain('PASTE:');
         const opencodeIo = makeIo();
         await runKtxSetupAgentsStep({
             projectDir: tempDir,
@@ -468,6 +592,8 @@ describe('setup agents', () => {
         }, opencodeIo.io);
         expect(opencodeIo.stdout()).toContain('"mcp"');
         expect(opencodeIo.stdout()).toContain('"type": "remote"');
+        expect(opencodeIo.stdout()).toContain('1. Configure OpenCode');
+        expect(opencodeIo.stdout()).toContain('Open opencode.json, then paste this block:');
         await expect(readFile(join(tempDir, 'opencode.json'), 'utf-8')).rejects.toThrow();
         const universalIo = makeIo();
         await runKtxSetupAgentsStep({
@@ -482,6 +608,8 @@ describe('setup agents', () => {
         }, universalIo.io);
         expect(universalIo.stdout()).toContain('Universal MCP endpoint:');
         expect(universalIo.stdout()).toContain('http://localhost:7878/mcp');
+        expect(universalIo.stdout()).toContain('1. Configure unsupported MCP clients');
+        expect(universalIo.stdout()).toContain('Use this endpoint when setting up unsupported MCP clients:');
     });
     it('uses MCP daemon state for port and token metadata without rendering literal tokens', async () => {
         await mkdir(join(tempDir, '.ktx'), { recursive: true });
@@ -513,7 +641,9 @@ describe('setup agents', () => {
             expect(rendered).toContain('http://127.0.0.1:8787/mcp');
             expect(rendered).toContain('Bearer ${KTX_MCP_TOKEN}');
             expect(rendered).not.toContain('secret-token');
-            expect(io.stdout()).toContain('Run `ktx mcp start` to enable the configured KTX MCP server.');
+            expect(io.stdout()).toContain('Run this command before using Claude Code:');
+            expect(io.stdout()).toContain('RUN:');
+            expect(io.stdout()).toContain(`ktx mcp start --project-dir ${tempDir}`);
         }
         finally {
             if (previousToken === undefined) {
@@ -567,7 +697,7 @@ describe('setup agents', () => {
         await expect(stat(join(tempDir, '.claude/skills/ktx/keep.txt'))).resolves.toBeDefined();
         await expect(readKtxAgentInstallManifest(tempDir)).resolves.toEqual(null);
     });
-    it('removes generated Claude Desktop plugin from the manifest', async () => {
+    it('removes generated Claude Desktop skill zips from the manifest', async () => {
         const home = await mkdtemp(join(tmpdir(), 'ktx-setup-agents-home-'));
         const previousHome = process.env.HOME;
         process.env.HOME = home;
@@ -583,15 +713,18 @@ describe('setup agents', () => {
                 mode: 'mcp-cli',
                 skipAgents: false,
             }, io.io);
-            const pluginPath = join(tempDir, '.ktx/agents/claude/ktx-plugin.zip');
+            const analyticsSkillPath = join(tempDir, '.ktx/agents/claude/ktx-analytics.zip');
+            const adminSkillPath = join(tempDir, '.ktx/agents/claude/ktx.zip');
             const launcherPath = join(tempDir, '.ktx/agents/claude/ktx-plugin-runner.sh');
             const configPath = join(home, 'Library/Application Support/Claude/claude_desktop_config.json');
-            await expect(stat(pluginPath)).resolves.toBeDefined();
+            await expect(stat(analyticsSkillPath)).resolves.toBeDefined();
+            await expect(stat(adminSkillPath)).resolves.toBeDefined();
             await expect(stat(launcherPath)).resolves.toBeDefined();
             const beforeConfig = JSON.parse(await readFile(configPath, 'utf-8'));
             expect(beforeConfig.mcpServers.ktx).toBeDefined();
             await expect(removeKtxAgentInstall(tempDir, io.io)).resolves.toBe(0);
-            await expect(stat(pluginPath)).rejects.toThrow();
+            await expect(stat(analyticsSkillPath)).rejects.toThrow();
+            await expect(stat(adminSkillPath)).rejects.toThrow();
             await expect(stat(launcherPath)).rejects.toThrow();
             const afterConfig = JSON.parse(await readFile(configPath, 'utf-8'));
             expect(afterConfig.mcpServers.ktx).toBeUndefined();
@@ -619,7 +752,7 @@ describe('setup agents', () => {
             skipAgents: false,
         }, io.io, { prompts })).resolves.toEqual({ status: 'skipped', projectDir: tempDir });
     });
-    it('explains how to select multiple agent targets in interactive mode', async () => {
+    it('prints one navigation hint before interactive agent target prompts', async () => {
         const io = makeIo();
         const prompts = {
             select: vi.fn(async () => 'mcp-cli'),
@@ -635,8 +768,10 @@ describe('setup agents', () => {
             mode: 'mcp-cli',
             skipAgents: false,
         }, io.io, { prompts })).resolves.toEqual({ status: 'back', projectDir: tempDir });
+        expect(io.stdout()).toContain('Space to select, Enter to confirm, Esc to go back.');
+        expect(io.stdout().match(/Space to select/g)).toHaveLength(1);
         expect(prompts.multiselect).toHaveBeenCalledWith(expect.objectContaining({
-            message: 'Which agent targets should KTX install?\nUse Up/Down to move, Space to select or unselect, Enter to confirm, Escape to go back, or Ctrl+C to exit.',
+            message: 'Which agent targets should KTX install?',
         }));
     });
     it('prints per-agent install summary after successful installation', async () => {
@@ -652,45 +787,242 @@ describe('setup agents', () => {
             skipAgents: false,
         }, io.io);
         const output = io.stdout();
-        expect(output).toContain('Agent integration complete');
-        expect(output).toContain('Claude Code');
-        expect(output).toContain('+ Analytics skill installed — teaches your agent the KTX MCP analytics workflow');
-        expect(output).toContain('.claude/skills/ktx-analytics/SKILL.md');
-        expect(output).toContain('+ Skill installed — teaches admin agents which KTX CLI commands to run');
-        expect(output).toContain('.claude/skills/ktx/SKILL.md');
-        expect(output).toContain('+ Rule installed — tells admin agents when to use KTX CLI');
-        expect(output).toContain('.claude/rules/ktx.md');
-    });
-    it('formats summary with relative paths for project scope', () => {
-        const summary = formatInstallSummary([{ target: 'cursor', scope: 'project', mode: 'mcp-cli' }], [
+        expect(output).toContain('Claude Code · Project scope');
+        expect(output).toContain(join(tempDir, '.mcp.json'));
+        expect(output).toContain('Requires MCP to be started.');
+        expect(output).toContain('Analytics skill installed.');
+        expect(output).toContain('Admin CLI skill installed.');
+        expect(output).not.toContain('Agent integration complete');
+        expect(output).not.toContain(`KTX project\n  ${tempDir}`);
+        expect(output).not.toContain('Installed agents');
+        expect(output).not.toContain('.claude/skills/ktx-analytics/SKILL.md');
+        expect(output).not.toContain('.claude/skills/ktx/SKILL.md');
+        expect(output).not.toContain('.claude/rules/ktx.md');
+    });
+    it('formats summary with explicit project-scoped config paths', () => {
+        const summary = formatInstallSummaryLines([{ target: 'cursor', scope: 'project', mode: 'mcp-cli' }], [
             { kind: 'file', path: join(tempDir, '.cursor/rules/ktx-analytics.mdc'), role: 'analytics-skill' },
             { kind: 'file', path: join(tempDir, '.cursor/rules/ktx.mdc') },
+            { kind: 'json-key', path: join(tempDir, '.cursor/mcp.json'), jsonPath: ['mcpServers', 'ktx'] },
         ], tempDir);
-        expect(summary).toContain('Cursor');
-        expect(summary).toContain('+ Analytics skill installed — teaches your agent the KTX MCP analytics workflow');
-        expect(summary).toContain('.cursor/rules/ktx-analytics.mdc');
-        expect(summary).toContain('+ Rule installed — tells admin agents when to use KTX CLI');
-        expect(summary).toContain('.cursor/rules/ktx.mdc');
-        expect(summary).not.toContain(tempDir);
+        expect(summary).toEqual([
+            {
+                title: 'Cursor · Project scope',
+                lines: [
+                    join(tempDir, '.cursor/mcp.json'),
+                    'Requires MCP to be started.',
+                    'Cursor rules installed.',
+                ],
+            },
+        ]);
     });
     it('formats summary with multiple agent targets', () => {
-        const summary = formatInstallSummary([
+        const summary = formatInstallSummaryLines([
             { target: 'claude-code', scope: 'project', mode: 'mcp-cli' },
             { target: 'codex', scope: 'project', mode: 'mcp-cli' },
         ], [
             { kind: 'file', path: join(tempDir, '.claude/skills/ktx-analytics/SKILL.md'), role: 'analytics-skill' },
             { kind: 'file', path: join(tempDir, '.claude/skills/ktx/SKILL.md'), role: 'skill' },
             { kind: 'file', path: join(tempDir, '.claude/rules/ktx.md'), role: 'rule' },
+            { kind: 'json-key', path: join(tempDir, '.mcp.json'), jsonPath: ['mcpServers', 'ktx'] },
             { kind: 'file', path: join(tempDir, '.agents/skills/ktx-analytics/SKILL.md'), role: 'analytics-skill' },
             { kind: 'file', path: join(tempDir, '.agents/skills/ktx/SKILL.md'), role: 'skill' },
             { kind: 'file', path: join(tempDir, '.codex/instructions/ktx.md'), role: 'rule' },
         ], tempDir);
-        expect(summary).toContain('Claude Code');
-        expect(summary).toContain('+ Analytics skill installed — teaches your agent the KTX MCP analytics workflow');
-        expect(summary).toContain('+ Skill installed — teaches admin agents which KTX CLI commands to run');
-        expect(summary).toContain('+ Rule installed — tells admin agents when to use KTX CLI');
-        expect(summary).toContain('Codex');
-        expect(summary).toContain('.agents/skills/ktx-analytics/SKILL.md');
-        expect(summary).toContain('.agents/skills/ktx/SKILL.md');
+        expect(summary).toEqual([
+            {
+                title: 'Claude Code · Project scope',
+                lines: [
+                    join(tempDir, '.mcp.json'),
+                    'Requires MCP to be started.',
+                    'Analytics skill installed.',
+                    'Admin CLI skill installed.',
+                ],
+            },
+            {
+                title: 'Codex · Project scope',
+                lines: [
+                    'Add the snippet shown below to ~/.codex/config.toml.',
+                    'Requires MCP to be started.',
+                    'Codex guidance installed.',
+                ],
+            },
+        ]);
+    });
+    it('prints one target-aware next actions block for mixed agent targets', async () => {
+        const home = await mkdtemp(join(tmpdir(), 'ktx-setup-agents-home-'));
+        const previousHome = process.env.HOME;
+        process.env.HOME = home;
+        try {
+            const io = makeIo();
+            const prompts = {
+                select: vi.fn(async ({ message }) => message.startsWith('Where should') ? 'project' : 'mcp'),
+                multiselect: vi.fn(async () => ['claude-code', 'claude-desktop']),
+                cancel: vi.fn(),
+            };
+            await expect(runKtxSetupAgentsStep({
+                projectDir: tempDir,
+                inputMode: 'auto',
+                yes: false,
+                agents: true,
+                scope: 'project',
+                mode: 'mcp',
+                skipAgents: false,
+            }, io.io, { prompts })).resolves.toMatchObject({
+                status: 'ready',
+                installs: [
+                    { target: 'claude-code', scope: 'project', mode: 'mcp' },
+                    { target: 'claude-desktop', scope: 'global', mode: 'mcp' },
+                ],
+            });
+            const output = io.stdout();
+            expect(output).toContain('Required before using agents');
+            expect(output).not.toContain('Next actions');
+            expect(output).toContain('1. Start MCP');
+            expect(output).toContain('Run this command before using Claude Code:');
+            expect(output).toContain(`ktx mcp start --project-dir ${tempDir}`);
+            expect(output).toContain(`ktx mcp stop --project-dir ${tempDir}\n\n2. Open Claude Code`);
+            expect(output).toContain('Open Claude Code from the KTX project directory');
+            expect(output).toContain('RUN:');
+            expect(output).toContain(`cd '${tempDir}'`);
+            expect(output).toContain('3. Restart Claude Desktop');
+            expect(output).toContain('Claude Desktop loads KTX MCP after restart.');
+            expect(output).toContain('4. Upload Claude Desktop skills');
+            expect(output).toContain('Customize > Skills > + > Create skill > Upload a skill');
+            expect(output).toContain(join(tempDir, '.ktx/agents/claude/ktx-analytics.zip'));
+            expect(output).not.toContain(join(tempDir, '.ktx/agents/claude/ktx.zip'));
+            expect(output).toContain('Upload this file:');
+            expect(output).toContain('All set.');
+            expect(output).not.toContain('Finish Claude Desktop setup');
+            expect(output).not.toContain('Run `ktx mcp start` to enable the configured KTX MCP server.');
+        }
+        finally {
+            process.env.HOME = previousHome;
+            await rm(home, { recursive: true, force: true });
+        }
+    });
+    it('does not tell global Claude Code installs to open from the project directory', async () => {
+        const home = await mkdtemp(join(tmpdir(), 'ktx-setup-agents-home-'));
+        const previousHome = process.env.HOME;
+        process.env.HOME = home;
+        try {
+            const io = makeIo();
+            await expect(runKtxSetupAgentsStep({
+                projectDir: tempDir,
+                inputMode: 'disabled',
+                yes: true,
+                agents: true,
+                target: 'claude-code',
+                scope: 'global',
+                mode: 'mcp',
+                skipAgents: false,
+            }, io.io)).resolves.toMatchObject({
+                status: 'ready',
+                installs: [{ target: 'claude-code', scope: 'global', mode: 'mcp' }],
+            });
+            const output = io.stdout();
+            expect(output).toContain('2. Open Claude Code');
+            expect(output).toContain('RUN:');
+            expect(output).toContain('claude');
+            expect(output).not.toContain('Open Claude Code from the KTX project directory');
+            expect(output).not.toContain(`cd '${tempDir}'`);
+        }
+        finally {
+            process.env.HOME = previousHome;
+            await rm(home, { recursive: true, force: true });
+        }
+    });
+    it('explains next actions for Codex, Cursor, OpenCode, and universal MCP targets', async () => {
+        const io = makeIo();
+        const prompts = {
+            select: vi.fn(async () => 'mcp-cli'),
+            multiselect: vi.fn(async () => ['codex', 'cursor', 'opencode', 'universal']),
+            cancel: vi.fn(),
+        };
+        await expect(runKtxSetupAgentsStep({
+            projectDir: tempDir,
+            inputMode: 'auto',
+            yes: false,
+            agents: true,
+            scope: 'project',
+            mode: 'mcp-cli',
+            skipAgents: false,
+        }, io.io, { prompts })).resolves.toMatchObject({
+            status: 'ready',
+            installs: [
+                { target: 'codex', scope: 'project', mode: 'mcp-cli' },
+                { target: 'cursor', scope: 'project', mode: 'mcp-cli' },
+                { target: 'opencode', scope: 'project', mode: 'mcp-cli' },
+                { target: 'universal', scope: 'project', mode: 'mcp-cli' },
+            ],
+        });
+        const output = io.stdout();
+        expect(output).toContain('Required before using agents');
+        expect(output).toContain('1. Configure Codex');
+        expect(output).toContain('2. Configure OpenCode');
+        expect(output).toContain('3. Configure unsupported MCP clients');
+        expect(output).toContain('4. Start MCP');
+        expect(output).toContain('Run this command before using Codex, Cursor, OpenCode, and Universal .agents:');
+        expect(output).toContain('Open Cursor from the KTX project directory');
+        expect(output).toContain('Open ~/.codex/config.toml, then paste this block:\n\n  PASTE:\n  [mcp_servers.ktx]');
+        expect(output).toContain('Open opencode.json, then paste this block:');
+        expect(output).toContain('Use this endpoint when setting up unsupported MCP clients:');
+        expect(output).toContain('Codex guidance installed');
+        expect(output).toContain('Cursor rules installed');
+        expect(output).toContain('OpenCode commands installed');
+        expect(output).toContain('.agents guidance installed');
+    });
+    describe('createAgentNextActionsLineFormatter', () => {
+        function makeColorStdout() {
+            return { write: () => true, hasColors: () => true };
+        }
+        function makePlainStdout() {
+            return { write: () => true, hasColors: () => false };
+        }
+        const ESC = String.fromCharCode(27);
+        it('returns the line untouched when the stream cannot render colors', () => {
+            const format = createAgentNextActionsLineFormatter(makePlainStdout());
+            expect(format('2. Upload Claude Desktop skills')).toBe('2. Upload Claude Desktop skills');
+            expect(format('  /tmp/ktx/.ktx/agents/claude/ktx.zip')).toBe('  /tmp/ktx/.ktx/agents/claude/ktx.zip');
+        });
+        it('styles step headings and aligns sub-prose under the title', () => {
+            const format = createAgentNextActionsLineFormatter(makeColorStdout());
+            const heading = format('2. Upload Claude Desktop skills');
+            expect(heading).toContain(ESC);
+            expect(heading).toContain('2');
+            expect(heading).toContain('Upload Claude Desktop skills');
+            expect(heading).not.toMatch(/^2\. /);
+            const sub = format('  Toggle the uploaded KTX skills on.');
+            expect(sub).toMatch(/^ {3}/);
+            expect(sub).toContain('Toggle the uploaded KTX skills on.');
+        });
+        it('renders skill bundle .zip paths as bullets and shortens HOME to ~', () => {
+            const previousHome = process.env.HOME;
+            process.env.HOME = '/tmp/test-home';
+            try {
+                const format = createAgentNextActionsLineFormatter(makeColorStdout());
+                const line = format('  /tmp/test-home/.ktx/agents/claude/ktx-analytics.zip');
+                expect(line).toContain('•');
+                expect(line).toContain('~/.ktx/agents/claude/ktx-analytics.zip');
+                expect(line).not.toContain('/tmp/test-home/');
+            }
+            finally {
+                if (previousHome === undefined)
+                    delete process.env.HOME;
+                else
+                    process.env.HOME = previousHome;
+            }
+        });
+        it('replaces breadcrumb separators with a typographic chevron', () => {
+            const format = createAgentNextActionsLineFormatter(makeColorStdout());
+            const line = format('  Open Claude Desktop: Customize > Skills > + > Create skill > Upload a skill.');
+            expect(line).toContain('›');
+            expect(line).not.toContain(' > ');
+        });
+        it('leaves already-styled lines untouched to avoid double-wrapping', () => {
+            const format = createAgentNextActionsLineFormatter(makeColorStdout());
+            const preStyled = `${ESC}[1m2. Already styled${ESC}[22m`;
+            expect(format(preStyled)).toBe(preStyled);
+        });
     });
 });

package/dist/setup-embeddings.d.ts

@@ -49,6 +49,7 @@ export interface KtxSetupEmbeddingsDeps {
     healthCheck?: (config: KtxEmbeddingConfig) => Promise<KtxEmbeddingHealthCheckResult>;
     ensureLocalEmbeddings?: (options: {
         cliVersion: string;
+        projectDir: string;
         installPolicy: KtxManagedPythonInstallPolicy;
         io: KtxCliIo;
     }) => Promise<ManagedLocalEmbeddingsDaemon>;