From 626284c78df11a1e5ac91299df2d9e2007c71d75 Mon Sep 17 00:00:00 2001
From: Luca Martial <lucamrtl@gmail.com>
Date: Mon, 11 May 2026 22:05:59 -0700
Subject: [PATCH] Clarify agent setup summary

---
 packages/cli/src/setup-agents.test.ts | 16 ++++++++--------
 packages/cli/src/setup-agents.ts      | 14 +++++++++++---
 2 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/packages/cli/src/setup-agents.test.ts b/packages/cli/src/setup-agents.test.ts
index d5ced403..a0971eef 100644
--- a/packages/cli/src/setup-agents.test.ts
+++ b/packages/cli/src/setup-agents.test.ts
@@ -239,11 +239,11 @@ describe('setup agents', () => {
     const output = io.stdout();
     expect(output).toContain('Agent integration complete');
     expect(output).toContain('Claude Code');
-    expect(output).toContain('+ Skill installed');
+    expect(output).toContain('+ Skill installed — teaches your agent which KTX commands to run');
     expect(output).toContain('.claude/skills/ktx/SKILL.md');
-    expect(output).toContain('+ Rule installed');
+    expect(output).toContain('+ Rule installed — tells your agent when to use KTX');
     expect(output).toContain('.claude/rules/ktx.md');
-    expect(output).toContain('+ MCP config added');
+    expect(output).toContain('+ MCP config added — lets your agent talk to KTX over MCP');
     expect(output).toContain('.mcp.json');
   });
 
@@ -258,9 +258,9 @@ describe('setup agents', () => {
     );
 
     expect(summary).toContain('Cursor');
-    expect(summary).toContain('+ Rule installed');
+    expect(summary).toContain('+ Rule installed — tells your agent when to use KTX');
     expect(summary).toContain('.cursor/rules/ktx.mdc');
-    expect(summary).toContain('+ MCP config added');
+    expect(summary).toContain('+ MCP config added — lets your agent talk to KTX over MCP');
     expect(summary).toContain('.cursor/mcp.json');
     expect(summary).not.toContain(tempDir);
   });
@@ -280,9 +280,9 @@ describe('setup agents', () => {
     );
 
     expect(summary).toContain('Claude Code');
-    expect(summary).toContain('+ Skill installed');
-    expect(summary).toContain('+ Rule installed');
+    expect(summary).toContain('+ Skill installed — teaches your agent which KTX commands to run');
+    expect(summary).toContain('+ Rule installed — tells your agent when to use KTX');
     expect(summary).toContain('Codex');
-    expect(summary).toContain('+ MCP config added');
+    expect(summary).toContain('+ MCP config added — lets your agent talk to KTX over MCP');
   });
 });
diff --git a/packages/cli/src/setup-agents.ts b/packages/cli/src/setup-agents.ts
index 67394861..dad15e7e 100644
--- a/packages/cli/src/setup-agents.ts
+++ b/packages/cli/src/setup-agents.ts
@@ -348,6 +348,12 @@ export function formatInstallSummary(
     idx += planned.length;
   }
 
+  const fileHints: Record<string, string> = {
+    skill: 'teaches your agent which KTX commands to run',
+    rule: 'tells your agent when to use KTX',
+    mcp: 'lets your agent talk to KTX over MCP',
+  };
+
   const lines: string[] = [];
   for (const install of installs) {
     const targetEntries = entriesByTarget.get(install.target) ?? [];
@@ -356,11 +362,13 @@ export function formatInstallSummary(
       const displayPath =
         install.scope === 'global' ? entry.path : relative(projectDir, entry.path);
       if (entry.kind === 'file') {
-        const label = entry.role === 'rule' ? 'Rule installed' : fileEntryLabels[install.target];
-        lines.push(`    + ${label}`);
+        const isRule = entry.role === 'rule' || fileEntryLabels[install.target] === 'Rule installed';
+        const label = isRule ? 'Rule installed' : fileEntryLabels[install.target];
+        const hint = fileHints[isRule ? 'rule' : (entry.role ?? 'skill')] ?? '';
+        lines.push(`    + ${label} — ${hint}`);
         lines.push(`      ${displayPath}`);
       } else {
-        lines.push(`    + MCP config added`);
+        lines.push(`    + MCP config added — ${fileHints.mcp}`);
         lines.push(`      ${displayPath}`);
       }
     }