claude-rpc 0.15.0 → 0.15.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-rpc",
-  "version": "0.15.0",
+  "version": "0.15.2",
   "description": "Discord Rich Presence for Claude Code — live model, project, tokens, and lifetime stats driven by Claude Code's hook system.",
   "type": "module",
   "license": "MIT",

package/src/cli.js

@@ -15,7 +15,7 @@ import { readState } from './state.js';
 import { buildVars, fillTemplate, humanProject, humanTool, applyIdle, framePasses, fmtNum } from './format.js';
 import { scan, readAggregate, findLiveSessions, dayKey, weekKey } from './scanner.js';
 import { runHookCli } from './hook.js';
-import { install as runInstall, uninstall as runUninstall, isInstalled, migrateConfig, installHooks, ensureCanonicalExe, installMcp, uninstallMcp, mcpServerCommand } from './install.js';
+import { install as runInstall, uninstall as runUninstall, isInstalled, migrateConfig, installHooks, ensureCanonicalExe, installMcp, uninstallMcp, mcpServerCommand, setupOutro } from './install.js';
 import { startTui } from './tui.js';
 import { generateInsights } from './insights.js';
 import { maybeNudge } from './nudge.js';
@@ -68,7 +68,7 @@ function daemonPid() {
 function startDaemon({ quiet = false } = {}) {
   const pid = daemonPid();
   if (pid) {
-    if (!quiet) console.log(`${c.yellow}!${c.reset} Daemon already running (pid ${pid}). Run 'stop' first to restart.`);
+    if (!quiet) console.log(`  ${c.yellow}!${c.reset}  ${'daemon running'.padEnd(16)}${c.dim}already up (pid ${pid}) · bounce it with ${c.reset}${c.cyan}claude-rpc restart${c.reset}`);
     return false;
   }
   // In packaged mode the "daemon script" is the exe itself with a subcommand;
@@ -79,19 +79,19 @@ function startDaemon({ quiet = false } = {}) {
   const args = IS_PACKAGED ? ['daemon'] : [DAEMON_SCRIPT];
   const child = spawn(exe, args, { detached: true, stdio: 'ignore', windowsHide: true });
   child.unref();
-  if (!quiet) console.log(`${c.green}✓${c.reset} Daemon launched (pid ${c.cyan}${child.pid}${c.reset})  ${c.dim}logs: ${LOG_PATH}${c.reset}`);
+  if (!quiet) console.log(`  ${c.green}✓${c.reset}  ${'daemon launched'.padEnd(16)}${c.dim}pid ${c.reset}${c.cyan}${child.pid}${c.reset}${c.dim} · log ${shortPath(LOG_PATH)}${c.reset}`);
   return true;
 }
 
 function stopDaemon({ quiet = false } = {}) {
   const pid = daemonPid();
-  if (!pid) { if (!quiet) console.log('Daemon not running.'); return false; }
+  if (!pid) { if (!quiet) console.log(`  ${c.cyan}·${c.reset}  daemon not running`); return false; }
   try {
     process.kill(pid, 'SIGTERM');
-    if (!quiet) console.log(`${c.green}✓${c.reset} Sent SIGTERM to pid ${c.cyan}${pid}${c.reset}`);
+    if (!quiet) console.log(`  ${c.green}✓${c.reset}  ${'daemon stopping'.padEnd(16)}${c.dim}sent SIGTERM to pid ${pid}${c.reset}`);
     return true;
   } catch (e) {
-    if (!quiet) console.log(`${c.red}✗${c.reset} Failed to stop: ${e.message}`);
+    if (!quiet) console.log(`  ${c.red}✗${c.reset}  ${'stop failed'.padEnd(16)}${c.dim}${e.message}${c.reset}`);
     return false;
   }
 }
@@ -581,24 +581,24 @@ function dumpVars() {
 }
 
 function doScan(force = false) {
-  console.log(`${c.dim}Scanning ~/.claude/projects${c.reset}`, force ? '(force re-parse)' : '(incremental)…');
+  console.log(`  ${c.dim}scanning ~/.claude/projects ${force ? '(force re-parse)' : '(incremental)'}…${c.reset}`);
   const t0 = Date.now();
   let lastReport = 0;
   const result = scan({
     force,
     onProgress: ({ scanned, total }) => {
       if (Date.now() - lastReport > 500) {
-        process.stdout.write(`\r  parsed ${scanned}/${total}…`);
+        process.stdout.write(`\r  ${c.dim}parsed ${scanned}/${total}…${c.reset}`);
         lastReport = Date.now();
       }
     },
   });
   process.stdout.write('\n');
-  console.log(`${c.green}✓${c.reset} Done in ${Date.now() - t0}ms — ${c.cyan}${result.scanned}${c.reset} parsed · ${result.skipped} cached · ${result.removed} removed (${result.total} total)`);
+  console.log(`  ${c.green}✓${c.reset}  scan complete  ${c.dim}${Date.now() - t0}ms — ${c.reset}${c.cyan}${result.scanned}${c.reset}${c.dim} parsed · ${result.skipped} cached · ${result.removed} removed (${result.total} total)${c.reset}`);
   if (result.dirs && result.dirs.length > 1) {
-    console.log(`${c.dim}Scanned roots:${c.reset} ${result.dirs.join(', ')}`);
+    console.log(`     ${c.dim}roots: ${result.dirs.join(', ')}${c.reset}`);
   }
-  console.log(`${c.dim}Aggregate written to ${AGGREGATE_PATH}${c.reset}`);
+  console.log(`     ${c.dim}aggregate → ${AGGREGATE_PATH}${c.reset}`);
 }
 
 // Backfill from any folder that has .jsonl transcripts. Useful for:
@@ -617,9 +617,9 @@ function doBackfill(argv) {
   }
   if (!existsSync(path)) {
     fail(`path doesn't exist: ${path}`,
-      { hint: 'check the spelling, or run `claude-rpc doctor` to see where transcripts live' });
+      { hint: 'check the spelling — relative paths resolve from the current directory' });
   }
-  console.log(`${c.dim}Backfilling from${c.reset} ${c.cyan}${path}${c.reset}…`);
+  console.log(`  ${c.dim}backfilling from ${c.reset}${c.cyan}${path}${c.reset}${c.dim}…${c.reset}`);
   const t0 = Date.now();
   let lastReport = 0;
   // Pass `extraDirs` rather than `projectsDirs` — this way the default
@@ -630,16 +630,16 @@ function doBackfill(argv) {
     extraDirs: [path],
     onProgress: ({ scanned, total }) => {
       if (Date.now() - lastReport > 500) {
-        process.stdout.write(`\r  parsed ${scanned}/${total}…`);
+        process.stdout.write(`\r  ${c.dim}parsed ${scanned}/${total}…${c.reset}`);
         lastReport = Date.now();
       }
     },
   });
   process.stdout.write('\n');
-  console.log(`${c.green}✓${c.reset} Done in ${Date.now() - t0}ms — ${c.cyan}${result.scanned}${c.reset} new/changed · ${result.skipped} cached`);
-  console.log(`${c.dim}Scanned roots:${c.reset} ${result.dirs.join(', ')}`);
+  console.log(`  ${c.green}✓${c.reset}  backfill complete  ${c.dim}${Date.now() - t0}ms — ${c.reset}${c.cyan}${result.scanned}${c.reset}${c.dim} new/changed · ${result.skipped} cached${c.reset}`);
+  console.log(`     ${c.dim}roots: ${result.dirs.join(', ')}${c.reset}`);
   const hours = ((result.aggregate.activeMs || 0) / 3_600_000).toFixed(1);
-  console.log(`${c.dim}Aggregate now:${c.reset} ${result.aggregate.sessions} sessions · ${hours}h · ${result.aggregate.userMessages} prompts`);
+  console.log(`     ${c.dim}aggregate now: ${result.aggregate.sessions} sessions · ${hours}h · ${result.aggregate.userMessages} prompts${c.reset}`);
 }
 
 function showInsights() {
@@ -678,7 +678,7 @@ async function doBadge(argv) {
   }
   if (opts.out) {
     writeFileSync(opts.out, svg);
-    console.log(`${c.green}✓${c.reset} Wrote ${c.cyan}${opts.out}${c.reset} (${svg.length} bytes)`);
+    console.log(`  ${c.green}✓${c.reset}  wrote ${c.cyan}${opts.out}${c.reset}  ${c.dim}(${svg.length} bytes)${c.reset}`);
   } else {
     process.stdout.write(svg);
   }
@@ -715,11 +715,11 @@ async function publishBadgeToGist(svg, opts) {
     writeFileSync(CONFIG_PATH, JSON.stringify(userCfg, null, 2));
     const wasUpdate = !!stored.id;
     console.log('');
-    console.log(`  ${c.green}✓${c.reset} ${wasUpdate ? 'Updated' : 'Created'} gist ${c.cyan}${result.id}${c.reset}`);
-    console.log(`  ${c.dim}raw:${c.reset}      ${c.cyan}${result.rawUrl}${c.reset}`);
-    if (result.htmlUrl) console.log(`  ${c.dim}gist:${c.reset}     ${c.dim}${result.htmlUrl}${c.reset}`);
+    console.log(`  ${c.green}✓${c.reset}  ${wasUpdate ? 'updated' : 'created'} gist ${c.cyan}${result.id}${c.reset}`);
+    console.log(`     ${c.dim}raw: ${c.reset}${c.cyan}${result.rawUrl}${c.reset}`);
+    if (result.htmlUrl) console.log(`     ${c.dim}gist: ${result.htmlUrl}${c.reset}`);
     console.log('');
-    console.log(`  ${c.dim}Paste into your README:${c.reset}`);
+    console.log(`  ${c.dim}paste into your README:${c.reset}`);
     console.log(`    ${gistMarkdown({ owner: result.owner, id: result.id, filename, label: 'Claude' })}`);
     console.log('');
   } catch (e) {
@@ -753,8 +753,8 @@ async function doCard(argv) {
   const svg = renderCard(aggregate, { range: opts.range });
   if (opts.out) {
     writeFileSync(opts.out, svg);
-    console.log(`${c.green}✓${c.reset} Wrote ${c.cyan}${opts.out}${c.reset} (${svg.length} bytes)`);
-    console.log(`${c.dim}Tip: open in a browser, right-click → Save as PNG. Or drop straight into a Discord message — it'll render inline.${c.reset}`);
+    console.log(`  ${c.green}✓${c.reset}  wrote ${c.cyan}${opts.out}${c.reset}  ${c.dim}(${svg.length} bytes)${c.reset}`);
+    console.log(`     ${c.dim}tip: open in a browser and save as PNG — or drop it straight into a Discord message; it renders inline${c.reset}`);
   } else {
     process.stdout.write(svg);
   }
@@ -788,8 +788,8 @@ async function doGithubStat(argv) {
   }
   if (opts.out) {
     writeFileSync(opts.out, svg);
-    console.log(`${c.green}✓${c.reset} Wrote ${c.cyan}${opts.out}${c.reset} (${svg.length} bytes)`);
-    console.log(`${c.dim}Embed in your README:  <img src="${opts.out}" alt="Claude Code stats" width="500" />${c.reset}`);
+    console.log(`  ${c.green}✓${c.reset}  wrote ${c.cyan}${opts.out}${c.reset}  ${c.dim}(${svg.length} bytes)${c.reset}`);
+    console.log(`     ${c.dim}embed in your README:  <img src="${opts.out}" alt="Claude Code stats" width="500" />${c.reset}`);
   } else {
     process.stdout.write(svg);
   }
@@ -825,13 +825,13 @@ async function doCalendar(argv) {
     else if (argv[i] === '--gist') opts.gist = true;
   }
   const aggregate = readAggregate();
-  if (!aggregate) fail('no aggregate yet — run `claude-rpc scan` first', { code: EX_BAD_STATE });
+  if (!aggregate) fail('no aggregate yet — nothing to render', { hint: 'run `claude-rpc scan` first', code: EX_BAD_STATE });
   const { renderCalendar } = await import('./calendar.js');
   const svg = renderCalendar(aggregate, {});
   if (opts.gist) return publishBadgeToGist(svg, { metric: 'calendar', range: 'year' });
   if (opts.out) {
     writeFileSync(opts.out, svg);
-    console.log(`${c.green}✓${c.reset} Wrote ${c.cyan}${opts.out}${c.reset} (${svg.length} bytes)`);
+    console.log(`  ${c.green}✓${c.reset}  wrote ${c.cyan}${opts.out}${c.reset}  ${c.dim}(${svg.length} bytes)${c.reset}`);
   } else process.stdout.write(svg);
 }
 
@@ -846,7 +846,7 @@ async function doSessionCard(argv) {
   const svg = renderSessionCard(vars, {});
   if (opts.out) {
     writeFileSync(opts.out, svg);
-    console.log(`${c.green}✓${c.reset} Wrote ${c.cyan}${opts.out}${c.reset} (${svg.length} bytes)`);
+    console.log(`  ${c.green}✓${c.reset}  wrote ${c.cyan}${opts.out}${c.reset}  ${c.dim}(${svg.length} bytes)${c.reset}`);
   } else process.stdout.write(svg);
 }
 
@@ -864,8 +864,8 @@ function doMcpInstall(argv) {
   const manual = (r) => `claude mcp add claude-rpc --scope ${scope} -- ${r.command} ${r.args.join(' ')}`;
   if (res.ok) {
     console.log('');
-    console.log(`  ${c.green}✓${c.reset} Registered the ${c.cyan}claude-rpc${c.reset} MCP server with Claude Code (scope: ${scope}).`);
-    console.log(`  ${c.dim}Restart Claude Code (or run /mcp), then ask: "how long have I coded today?"${c.reset}`);
+    console.log(`  ${c.green}✓${c.reset}  registered the ${c.cyan}claude-rpc${c.reset} MCP server with Claude Code ${c.dim}(scope: ${scope})${c.reset}`);
+    console.log(`     ${c.dim}restart Claude Code (or run /mcp), then ask: "how long have I coded today?"${c.reset}`);
     console.log('');
   } else if (res.reason === 'no-claude') {
     fail('the `claude` CLI was not found on your PATH', {
@@ -880,7 +880,7 @@ function doMcpInstall(argv) {
 function doMcpUninstall(argv) {
   const scope = argv.includes('--project') ? 'project' : argv.includes('--local') ? 'local' : 'user';
   const res = uninstallMcp({ scope });
-  if (res.ok) console.log(`${c.green}✓${c.reset} Removed the claude-rpc MCP server (scope: ${scope}).`);
+  if (res.ok) console.log(`  ${c.green}✓${c.reset}  removed the claude-rpc MCP server ${c.dim}(scope: ${scope})${c.reset}`);
   else if (res.reason === 'no-claude') fail('the `claude` CLI was not found on your PATH', { code: EX_USER_ERROR });
   else fail('could not remove the MCP server', { hint: 'claude mcp remove claude-rpc', code: EX_USER_ERROR });
 }
@@ -897,8 +897,8 @@ function doMcpUninstall(argv) {
 function doPrivate() {
   const cwd = process.cwd();
   const list = addPrivateCwd(cwd);
-  console.log(`${c.green}✓${c.reset} ${c.cyan}${cwd}${c.reset} marked private`);
-  console.log(`${c.dim}  ${list.length} ${list.length === 1 ? 'path' : 'paths'} in the private list. Daemon picks it up within ~5 min (cache TTL) or restart.${c.reset}`);
+  console.log(`  ${c.green}✓${c.reset}  ${c.cyan}${cwd}${c.reset} marked private`);
+  console.log(`     ${c.dim}${list.length} ${list.length === 1 ? 'path' : 'paths'} in the private list — the daemon picks it up within ~5 min, or ${c.reset}${c.cyan}claude-rpc restart${c.reset}`);
 }
 
 function doPublic() {
@@ -906,9 +906,9 @@ function doPublic() {
   const before = listPrivateCwds().length;
   const list = removePrivateCwd(cwd);
   if (list.length === before) {
-    console.log(`${c.yellow}!${c.reset} ${c.cyan}${cwd}${c.reset} wasn't in the private list`);
+    console.log(`  ${c.yellow}!${c.reset}  ${c.cyan}${cwd}${c.reset} wasn't in the private list`);
   } else {
-    console.log(`${c.green}✓${c.reset} ${c.cyan}${cwd}${c.reset} removed from the private list`);
+    console.log(`  ${c.green}✓${c.reset}  ${c.cyan}${cwd}${c.reset} removed from the private list`);
   }
 }
 
@@ -950,8 +950,8 @@ function doPause(argv) {
   if (arg === 'off' || arg === 'resume') return doResume();
   if (arg === 'status') {
     const until = pauseUntil();
-    if (until) console.log(`${c.yellow}●${c.reset} paused until ${c.cyan}${fmtClock(until)}${c.reset}`);
-    else console.log(`${c.green}○${c.reset} not paused`);
+    if (until) console.log(`  ${c.yellow}●${c.reset}  paused until ${c.cyan}${fmtClock(until)}${c.reset}`);
+    else console.log(`  ${c.green}○${c.reset}  not paused`);
     return;
   }
   const ms = parseDuration(argv[0]);
@@ -960,17 +960,17 @@ function doPause(argv) {
       { hint: 'use 30m, 2h, 1h30m, or a bare number of minutes (default: 1h)', code: EX_USER_ERROR });
   }
   const until = setPause(ms);
-  console.log(`${c.green}✓${c.reset} presence paused until ${c.cyan}${fmtClock(until)}${c.reset}`);
-  console.log(`${c.dim}  the daemon clears the card within a few seconds. Resume early with ${c.reset}${c.cyan}claude-rpc resume${c.reset}`);
+  console.log(`  ${c.green}✓${c.reset}  presence paused until ${c.cyan}${fmtClock(until)}${c.reset}`);
+  console.log(`     ${c.dim}the daemon clears the card within seconds — resume early with ${c.reset}${c.cyan}claude-rpc resume${c.reset}`);
 }
 
 function doResume() {
   const was = pauseUntil();
   clearPause();
   if (was) {
-    console.log(`${c.green}✓${c.reset} presence resumed ${c.dim}(was paused until ${fmtClock(was)})${c.reset}`);
+    console.log(`  ${c.green}✓${c.reset}  presence resumed ${c.dim}(was paused until ${fmtClock(was)})${c.reset}`);
   } else {
-    console.log(`${c.dim}presence wasn't paused.${c.reset}`);
+    console.log(`  ${c.cyan}·${c.reset}  presence wasn't paused`);
   }
 }
 
@@ -999,7 +999,7 @@ async function doExport(argv) {
   }
   if (out) {
     writeFileSync(out, payload);
-    console.log(`${c.green}✓${c.reset} Wrote ${c.cyan}${out}${c.reset} (${payload.length} bytes, ${csv ? 'CSV' : 'JSON'})`);
+    console.log(`  ${c.green}✓${c.reset}  wrote ${c.cyan}${out}${c.reset}  ${c.dim}(${payload.length} bytes, ${csv ? 'CSV' : 'JSON'})${c.reset}`);
   } else {
     process.stdout.write(payload);
   }
@@ -1018,7 +1018,12 @@ function squadAuth() {
   const cfg = loadConfig();
   const endpoint = (cfg.community?.endpoint || '').replace(/\/+$/, '');
   const instanceId = cfg.community?.instanceId;
-  if (!endpoint) fail('no community endpoint configured', { code: EX_BAD_STATE });
+  if (!endpoint) {
+    fail('no community endpoint configured', {
+      hint: 'config.json is missing community.endpoint — re-run `claude-rpc setup` to restore the default',
+      code: EX_BAD_STATE,
+    });
+  }
   if (!instanceId) {
     fail('squads need an identity', {
       hint: 'run `claude-rpc profile set --handle <name> && claude-rpc profile on` first',
@@ -1044,9 +1049,9 @@ function squadPageUrl(id) { return `https://claude-rpc.vercel.app/squad/${id}`;
 
 function printSquadInvite(squad) {
   console.log('');
-  console.log(`  ${c.green}✓${c.reset} squad ${c.bold}${squad.name}${c.reset}`);
-  console.log(`    ${c.dim}invite code:${c.reset} ${c.cyan}${squad.code}${c.reset}`);
-  console.log(`    ${c.dim}standings:  ${c.reset} ${c.cyan}${squadPageUrl(squad.id)}${c.reset}`);
+  console.log(`  ${c.green}✓${c.reset}  squad ${c.bold}${squad.name}${c.reset}`);
+  console.log(`     ${c.dim}invite code:${c.reset} ${c.cyan}${squad.code}${c.reset}`);
+  console.log(`     ${c.dim}standings:  ${c.reset} ${c.cyan}${squadPageUrl(squad.id)}${c.reset}`);
   console.log('');
   console.log(`  ${c.dim}send your crew this:${c.reset}`);
   console.log(`    join my Claude Code squad "${squad.name}" — npx claude-rpc@latest setup, then:`);
@@ -1083,19 +1088,28 @@ async function doSquadCmd(argv) {
   if (sub === 'status' || sub === '') return squadStatus(ctx);
   if (sub === 'create') {
     const name = argv.slice(1).join(' ').trim();
-    if (!name) return fail('usage: claude-rpc squad create <name>', { code: EX_USER_ERROR });
+    if (!name) {
+      return fail('usage: claude-rpc squad create <name>',
+        { hint: 'example: claude-rpc squad create "the night shift"', code: EX_USER_ERROR });
+    }
     const r = await ctx.post('/squad/create', { name });
     if (r.status !== 200) return fail(`create failed: ${r.json?.error || r.status}`, { code: EX_SYS_ERROR });
     return printSquadInvite(r.json.squad);
   }
   if (sub === 'join') {
     const code = (argv[1] || '').trim();
-    if (!code) return fail('usage: claude-rpc squad join SQ-XXXXXX', { code: EX_USER_ERROR });
+    if (!code) {
+      return fail('usage: claude-rpc squad join SQ-XXXXXX',
+        { hint: 'the invite code comes from whoever created the squad (`claude-rpc squad create`)', code: EX_USER_ERROR });
+    }
     const r = await ctx.post('/squad/join', { code });
-    if (r.status !== 200) return fail(`join failed: ${r.json?.error || r.status}`, { code: EX_SYS_ERROR });
+    if (r.status !== 200) {
+      return fail(`join failed: ${r.json?.error || r.status}`,
+        { hint: 'double-check the invite code with whoever created the squad', code: EX_SYS_ERROR });
+    }
     const s = r.json.squad;
-    console.log(`${c.green}✓${c.reset} ${s.alreadyMember ? 'already in' : 'joined'} ${c.bold}${s.name}${c.reset} (${s.members} member${s.members === 1 ? '' : 's'})`);
-    console.log(`  ${c.dim}standings: ${squadPageUrl(s.id)}  ·  claude-rpc squad${c.reset}`);
+    console.log(`  ${c.green}✓${c.reset}  ${s.alreadyMember ? 'already in' : 'joined'} ${c.bold}${s.name}${c.reset} ${c.dim}(${s.members} member${s.members === 1 ? '' : 's'})${c.reset}`);
+    console.log(`     ${c.dim}standings: ${squadPageUrl(s.id)} — or run ${c.reset}${c.cyan}claude-rpc squad${c.reset}`);
     return;
   }
   if (sub === 'leave') {
@@ -1114,7 +1128,7 @@ async function doSquadCmd(argv) {
     }
     const r = await ctx.post('/squad/leave', { squadId: target.id });
     if (r.status !== 200) return fail(`leave failed: ${r.json?.error || r.status}`, { code: EX_SYS_ERROR });
-    console.log(`${c.green}✓${c.reset} left ${c.bold}${target.name}${c.reset}${r.json.dissolved ? ` ${c.dim}(last member — squad dissolved)${c.reset}` : ''}`);
+    console.log(`  ${c.green}✓${c.reset}  left ${c.bold}${target.name}${c.reset}${r.json.dissolved ? ` ${c.dim}(last member — squad dissolved)${c.reset}` : ''}`);
     return;
   }
   fail(`unknown squad subcommand: ${sub}`, {
@@ -1147,14 +1161,15 @@ async function doLink(argv) {
   }
   const r = await ctx.post('/pair/claim', { code });
   if (r.status !== 200) {
-    return fail(`link failed: ${r.json?.error || r.status}`, { code: EX_SYS_ERROR });
+    return fail(`link failed: ${r.json?.error || r.status}`,
+      { hint: 'grab a fresh code from https://claude-rpc.vercel.app/squads and try again', code: EX_SYS_ERROR });
   }
   // Mirror the verified identity locally so `profile status` agrees.
   const userCfg = readJson(CONFIG_PATH, {});
   userCfg.profile = { ...(userCfg.profile || {}), githubUser: r.json.githubUser, verified: true };
   writeFileSync(CONFIG_PATH, JSON.stringify(userCfg, null, 2));
-  console.log(`${c.green}✓${c.reset} linked as ${c.cyan}@${r.json.githubUser}${c.reset} — profile verified, squads unlocked in the browser.`);
-  console.log(`  ${c.dim}head back to https://claude-rpc.vercel.app/squads — it picks the link up automatically.${c.reset}`);
+  console.log(`  ${c.green}✓${c.reset}  linked as ${c.cyan}@${r.json.githubUser}${c.reset} — profile verified, squads unlocked in the browser`);
+  console.log(`     ${c.dim}head back to https://claude-rpc.vercel.app/squads — it picks the link up automatically${c.reset}`);
 }
 
 // ── Community totals ─────────────────────────────────────────────────────
@@ -1201,7 +1216,7 @@ async function communityOn() {
   const cfg = loadConfig();
   const community = cfg.community || {};
   if (community.enabled) {
-    console.log(`${c.green}✓${c.reset} community totals are already enabled`);
+    console.log(`  ${c.green}✓${c.reset}  community totals are already enabled`);
     return;
   }
   console.log('');
@@ -1246,12 +1261,12 @@ async function communityOn() {
 function communityOff() {
   const userCfg = readJson(CONFIG_PATH, {});
   if (!userCfg.community?.enabled) {
-    console.log(`${c.dim}community totals are already off.${c.reset}`);
+    console.log(`  ${c.cyan}·${c.reset}  community totals are already off`);
     return;
   }
   userCfg.community = { ...userCfg.community, enabled: false };
   writeFileSync(CONFIG_PATH, JSON.stringify(userCfg, null, 2));
-  console.log(`${c.green}✓${c.reset} community totals disabled. instanceId retained for re-enable continuity.`);
+  console.log(`  ${c.green}✓${c.reset}  community totals disabled ${c.dim}(instanceId retained for re-enable continuity)${c.reset}`);
 }
 
 async function communityReport() {
@@ -1263,11 +1278,11 @@ async function communityReport() {
   const result = await flushCommunity(cfg);
   console.log('');
   if (result.ok && result.delta) {
-    console.log(`  ${c.green}✓${c.reset} reported  ${c.cyan}+${result.delta.sessions} sessions${c.reset}  ${c.cyan}+${result.delta.tokens} tokens${c.reset}`);
+    console.log(`  ${c.green}✓${c.reset}  reported  ${c.cyan}+${result.delta.sessions} sessions${c.reset}  ${c.cyan}+${result.delta.tokens} tokens${c.reset}`);
   } else if (result.ok) {
-    console.log(`  ${c.dim}${result.reason}${c.reset}`);
+    console.log(`  ${c.cyan}·${c.reset}  ${c.dim}${result.reason}${c.reset}`);
   } else {
-    console.log(`  ${c.yellow}↳${c.reset} flush did not complete  ${c.dim}(${result.reason}${result.error ? ': ' + result.error : ''})${c.reset}`);
+    console.log(`  ${c.yellow}!${c.reset}  flush did not complete  ${c.dim}(${result.reason}${result.error ? ': ' + result.error : ''})${c.reset}`);
   }
   console.log('');
 }
@@ -1283,6 +1298,32 @@ function readFlag(argv, name) {
   return eq ? eq.slice(name.length + 3) : undefined;
 }
 
+// Single source of truth for the profile checklist. `profile`/`profile status`
+// renders all of it; mutations point at just the first unfinished step.
+// Verification is `done` whichever way it happened — web pairing (doLink sets
+// profile.verified) or the gist fallback (profileVerify).
+function profileSteps(p) {
+  return [
+    { key: 'handle',  done: lb.isValidHandle(p.handle), label: 'set a handle',      cmd: 'claude-rpc profile set --handle <name>', note: p.handle },
+    { key: 'publish', done: !!p.enabled,                label: 'enable publishing', cmd: 'claude-rpc profile on',                  note: 'daemon republishes automatically' },
+    { key: 'verify',  done: !!p.verified,               label: 'verify via GitHub', cmd: 'claude-rpc link <code>',                 note: p.githubUser ? `@${p.githubUser}` : '' },
+  ];
+}
+
+// One dim pointer at the next unfinished step — what mutations print instead
+// of re-rendering the whole dashboard.
+function profileNextStep() {
+  const p = loadConfig().profile || {};
+  const next = profileSteps(p).find((s) => !s.done);
+  if (!next) {
+    console.log(`     ${c.dim}→  all set — you're live at${c.reset} ${c.cyan}https://claude-rpc.vercel.app/u/${encodeURIComponent(p.handle)}${c.reset}`);
+  } else if (next.key === 'verify') {
+    console.log(`     ${c.dim}→  next: log in at${c.reset} ${c.cyan}https://claude-rpc.vercel.app/squads${c.reset}${c.dim}, then${c.reset} ${c.cyan}claude-rpc link <code>${c.reset}`);
+  } else {
+    console.log(`     ${c.dim}→  next:${c.reset} ${c.cyan}${next.cmd}${c.reset}  ${c.dim}(${next.label})${c.reset}`);
+  }
+}
+
 function profileStatus() {
   const p = (loadConfig().profile) || {};
   const handleOk = lb.isValidHandle(p.handle);
@@ -1307,23 +1348,27 @@ function profileStatus() {
   // Setup checklist — same shape every time, so the user always sees where
   // they are and the exact next command. This is the screen the daemon's
   // breadcrumbs point back to.
-  const steps = [
-    { done: handleOk,    label: 'set a handle',      cmd: 'claude-rpc profile set --handle <name>', note: p.handle },
-    { done: !!p.enabled, label: 'enable publishing', cmd: 'claude-rpc profile on',                  note: 'daemon republishes automatically' },
-    { done: !!p.verified, label: 'verify on GitHub', cmd: 'claude-rpc profile verify',              note: p.githubUser ? `@${p.githubUser}` : '' },
-  ];
+  const steps = profileSteps(p);
   if (steps.every((s) => s.done)) {
-    console.log(`  ${c.green}✓${c.reset} all set — you're live at ${c.cyan}${boardUrl}${c.reset}`);
+    console.log(`  ${c.green}✓${c.reset}  all set — you're live at ${c.cyan}${boardUrl}${c.reset}`);
   } else {
     const nextIdx = steps.findIndex((s) => !s.done);
-    box('next steps', steps.map((s, i) => {
+    const lines = steps.map((s, i) => {
       const mark = s.done ? `${c.green}✓${c.reset}` : (i === nextIdx ? `${c.yellow}○${c.reset}` : `${c.dim}○${c.reset}`);
       const label = s.done ? `${c.dim}${s.label}${c.reset}` : `${c.bold}${s.label}${c.reset}`;
       const tail = s.done
         ? `${c.dim}${s.note || 'done'}${c.reset}`
         : `${c.cyan}${s.cmd}${c.reset}${i === nextIdx ? `  ${c.dim}← next${c.reset}` : ''}`;
       return `${mark} ${i + 1}. ${label}${' '.repeat(Math.max(1, 20 - s.label.length))}${tail}`;
-    }));
+    });
+    // Web pairing is the primary verify path; the gist dance stays available
+    // for terminals with no browser nearby.
+    if (!steps[2].done) {
+      lines.push('');
+      lines.push(`${c.dim}the code comes from${c.reset} ${c.cyan}https://claude-rpc.vercel.app/squads${c.reset} ${c.dim}(log in with GitHub)${c.reset}`);
+      lines.push(`${c.dim}no browser? fall back to${c.reset} ${c.cyan}claude-rpc profile verify${c.reset}`);
+    }
+    box('next steps', lines);
   }
   console.log('');
 }
@@ -1356,8 +1401,14 @@ function profileSet(argv) {
 
   userCfg.profile = next;
   writeFileSync(CONFIG_PATH, JSON.stringify(userCfg, null, 2));
-  console.log(`${c.green}✓${c.reset} profile saved`);
-  profileStatus();
+  // One-line confirmation + a pointer at the next step. The full dashboard
+  // stays behind `claude-rpc profile` — mutations shouldn't re-render it.
+  const saved = [];
+  if (rawHandle !== undefined) saved.push(`handle ${next.handle}`);
+  if (rawName !== undefined)   saved.push(`name ${next.displayName || '—'}`);
+  if (rawGh !== undefined)     saved.push(`github ${next.githubUser || '—'}`);
+  console.log(`  ${c.green}✓${c.reset}  profile saved${saved.length ? `  ${c.dim}${saved.join(' · ')}${c.reset}` : ''}`);
+  profileNextStep();
 }
 
 function profileEnable(on) {
@@ -1382,10 +1433,11 @@ function profileEnable(on) {
   }
   userCfg.profile = next;
   writeFileSync(CONFIG_PATH, JSON.stringify(userCfg, null, 2));
-  console.log(`${c.green}✓${c.reset} leaderboard publishing ${on ? 'enabled' : 'disabled'}`);
   if (on) {
-    console.log(`  ${c.dim}publish now with ${c.reset}${c.cyan}claude-rpc profile publish${c.reset}${c.dim} (or wait for the next daemon flush).${c.reset}`);
-    profileStatus();
+    console.log(`  ${c.green}✓${c.reset}  publishing enabled  ${c.dim}— board syncs on the next flush, or now: ${c.reset}${c.cyan}claude-rpc profile publish${c.reset}`);
+    profileNextStep();
+  } else {
+    console.log(`  ${c.green}✓${c.reset}  leaderboard publishing disabled`);
   }
 }
 
@@ -1399,12 +1451,12 @@ async function profilePublish() {
     });
   }
   const { flushProfile } = await import('./community.js');
-  console.log(`${c.dim}publishing @${cfg.profile.handle} to the board…${c.reset}`);
+  console.log(`  ${c.dim}publishing @${cfg.profile.handle} to the board…${c.reset}`);
   const r = await flushProfile(cfg);
   if (r.ok) {
-    console.log(`${c.green}✓${c.reset} published — see it at ${c.cyan}https://claude-rpc.vercel.app/u/${encodeURIComponent(cfg.profile.handle)}${c.reset}`);
+    console.log(`  ${c.green}✓${c.reset}  published — see it at ${c.cyan}https://claude-rpc.vercel.app/u/${encodeURIComponent(cfg.profile.handle)}${c.reset}`);
   } else if (r.reason === 'rate-limited') {
-    console.log(`${c.yellow}!${c.reset} rate-limited — already published in the last minute; the board has you.`);
+    console.log(`  ${c.yellow}!${c.reset}  rate-limited — already published in the last minute; the board has you`);
   } else {
     return fail(`publish failed: ${r.reason}${r.error ? ' (' + r.error + ')' : ''}`, { code: EX_SYS_ERROR });
   }
@@ -1421,13 +1473,18 @@ async function profileVerify() {
   // and publishing that gist already requires gh auth, so the account is
   // known by the time it matters.
   if (!profile.githubUser) {
-    console.log(`${c.dim}no --github set — your verified identity will be the account that owns the proof gist.${c.reset}`);
+    console.log(`  ${c.dim}no --github set — your verified identity will be the account that owns the proof gist${c.reset}`);
   }
   if (!community.instanceId) {
     return fail('enable the profile first', { hint: 'claude-rpc profile on', code: EX_BAD_STATE });
   }
   const endpoint = (community.endpoint || '').replace(/\/+$/, '');
-  if (!endpoint) return fail('no community endpoint configured', { code: EX_BAD_STATE });
+  if (!endpoint) {
+    return fail('no community endpoint configured', {
+      hint: 'config.json is missing community.endpoint — re-run `claude-rpc setup` to restore the default',
+      code: EX_BAD_STATE,
+    });
+  }
 
   const post = async (path, body) => {
     const res = await fetch(endpoint + path, {
@@ -1445,13 +1502,13 @@ async function profileVerify() {
       const { flushProfile } = await import('./community.js');
       await flushProfile(cfg);
     }
-    console.log(`${c.dim}requesting a verification token…${c.reset}`);
+    console.log(`  ${c.dim}requesting a verification token…${c.reset}`);
     const start = await post('/verify/start', { instanceId: community.instanceId, githubUser: profile.githubUser || null });
     if (!start.json?.token) return fail(`verify/start failed: ${start.json?.error || start.status}`, { code: EX_SYS_ERROR });
     const token = start.json.token;
 
     const { publishGistFile } = await import('./gist.js');
-    console.log(`${c.dim}publishing a public proof gist…${c.reset}`);
+    console.log(`  ${c.dim}publishing a public proof gist…${c.reset}`);
     const gist = await publishGistFile({
       svg: `claude-rpc leaderboard verification\n${token}\n`,
       filename: 'claude-rpc-verify.txt',
@@ -1462,7 +1519,7 @@ async function profileVerify() {
     // Hand the worker the gist ID so it fetches that gist directly (no
     // gist-list lag) and reads the real owner — instant, and the owner becomes
     // the verified identity regardless of what --github was set to.
-    console.log(`${c.dim}confirming with the server…${c.reset}`);
+    console.log(`  ${c.dim}confirming with the server…${c.reset}`);
     const check = await post('/verify/check', { instanceId: community.instanceId, gistId: gist.id });
     if (check.json?.verified) {
       const who = check.json.githubUser || gist.owner || profile.githubUser;
@@ -1471,13 +1528,13 @@ async function profileVerify() {
       const userCfg = readJson(CONFIG_PATH, {});
       userCfg.profile = { ...(userCfg.profile || {}), ...(who ? { githubUser: who } : {}), verified: true };
       writeFileSync(CONFIG_PATH, JSON.stringify(userCfg, null, 2));
-      console.log(`${c.green}✓${c.reset} verified as @${who} — you'll show the ✓ on the board.`);
+      console.log(`  ${c.green}✓${c.reset}  verified as ${c.cyan}@${who}${c.reset} — you'll show the ✓ on the board`);
       if (who && profile.githubUser && who.toLowerCase() !== profile.githubUser.toLowerCase()) {
-        console.log(`  ${c.dim}(your gist is owned by @${who}, so the profile now uses that account.)${c.reset}`);
+        console.log(`     ${c.dim}(your gist is owned by @${who}, so the profile now uses that account)${c.reset}`);
       }
     } else {
-      console.log(`${c.yellow}!${c.reset} not confirmed: ${check.json?.error || check.status}`);
-      console.log(`  ${c.dim}make sure the gist is public, then re-run ${c.reset}${c.cyan}claude-rpc profile verify${c.reset}${c.dim}.${c.reset}`);
+      console.log(`  ${c.yellow}!${c.reset}  not confirmed: ${check.json?.error || check.status}`);
+      console.log(`     ${c.dim}↳ make sure the gist is public, then re-run ${c.reset}${c.cyan}claude-rpc profile verify${c.reset}`);
     }
   } catch (e) {
     return fail(`verification failed: ${e.message}`, {
@@ -1514,7 +1571,8 @@ async function doCommunity(argv) {
 
 function tailLog() {
   if (!existsSync(LOG_PATH)) {
-    console.log(`${c.yellow}No log yet at ${LOG_PATH}${c.reset}`);
+    console.log(`  ${c.yellow}!${c.reset}  no log yet  ${c.dim}${LOG_PATH}${c.reset}`);
+    console.log(`     ${c.gray}↳ the daemon creates it on first start: ${c.reset}${c.cyan}claude-rpc start${c.reset}`);
     return;
   }
   // Print the last ~30 lines, then follow.
@@ -1646,18 +1704,19 @@ function help() {
     ['tail',      'Tail the daemon log file'],
     ['daemon',    'Run daemon in foreground (debug)'],
   ];
+  const colW = cmds.reduce((m, [name]) => Math.max(m, name.length), 0);
   console.log('');
   console.log(`  ${c.bold}${c.magenta}◆ claude-rpc${c.reset}  ${c.dim}— Discord Rich Presence for Claude Code${c.reset}`);
   console.log('');
   console.log(`  ${c.dim}Commands:${c.reset}`);
   for (const [name, desc] of cmds) {
-    console.log(`    ${c.cyan}${name.padEnd(10)}${c.reset}  ${desc}`);
+    console.log(`    ${c.cyan}${name.padEnd(colW)}${c.reset}  ${desc}`);
   }
   console.log('');
   console.log(`  ${c.dim}First-time setup:${c.reset}`);
-  console.log(`    1. Set ${c.cyan}clientId${c.reset} in ${c.cyan}config.json${c.reset} to your Discord app id.`);
-  console.log(`    2. (Optional) Upload art under Rich Presence → Art Assets: ${c.cyan}claude${c.reset}, ${c.cyan}working${c.reset}, ${c.cyan}idle${c.reset}, ${c.cyan}thinking${c.reset}.`);
-  console.log(`    3. ${c.cyan}npm install${c.reset}  &&  ${c.cyan}claude-rpc setup${c.reset}  &&  ${c.cyan}claude-rpc start${c.reset}.`);
+  console.log(`    1. ${c.cyan}claude-rpc setup${c.reset} — wires hooks, seeds config, starts the daemon.`);
+  console.log(`    2. Open Claude Code and send a prompt — the card appears in Discord.`);
+  console.log(`    3. ${c.dim}(optional)${c.reset} Use your own Discord app: set ${c.cyan}clientId${c.reset} in ${c.cyan}config.json${c.reset} and upload art under Rich Presence → Art Assets: ${c.cyan}claude${c.reset}, ${c.cyan}working${c.reset}, ${c.cyan}idle${c.reset}, ${c.cyan}thinking${c.reset}.`);
   console.log('');
   console.log(`  ${c.dim}Tip: ${c.reset}edit ${c.cyan}config.json${c.reset} to customize rotation frames. Run ${c.cyan}claude-rpc preview${c.reset} to see the result without Discord.`);
   console.log('');
@@ -1686,8 +1745,11 @@ const packagedDefault = IS_PACKAGED && !cmd;
     // startup, install = with) but in practice users expect one command
     // to do everything. Non-Windows: addStartupEntry is a no-op + warning.
     case 'setup':
-    case 'install':
-      await runInstall({ exePath: EXE_PATH || process.execPath });
+    case 'install': {
+      // runInstall prints the phased checklist (or a one-line "already set
+      // up" on clean re-runs); the daemon row lands after it, then setupOutro
+      // closes the screen — only when something actually changed.
+      const { target, changed } = await runInstall({ exePath: EXE_PATH || process.execPath });
       // Slimmer first run: bring the daemon up now so the card appears
       // immediately, instead of making the user run a separate `start`.
       // Best-effort — a start hiccup must never make `setup` look failed.
@@ -1696,22 +1758,29 @@ const packagedDefault = IS_PACKAGED && !cmd;
           // Our own tree is npm's throwaway _npx cache; launch from the global
           // install setup just promoted to, via the PATH-resolved bin.
           if (!daemonPid()) {
-            spawn('claude-rpc', ['daemon'], {
+            const child = spawn('claude-rpc', ['daemon'], {
               detached: true, stdio: 'ignore', windowsHide: true,
               shell: process.platform === 'win32',
-            }).unref();
-            console.log(`${c.green}✓${c.reset} Daemon launched  ${c.dim}logs: ${LOG_PATH}${c.reset}`);
+            });
+            child.unref();
+            console.log(`  ${c.green}✓${c.reset}  ${'daemon launched'.padEnd(16)}${c.dim}log ${shortPath(LOG_PATH)}${c.reset}`);
+          } else {
+            console.log(`  ${c.cyan}·${c.reset}  ${'daemon running'.padEnd(16)}${c.dim}pid ${daemonPid()}${c.reset}`);
           }
         } else {
           startDaemon();
         }
       } catch (e) {
-        console.log(`${c.yellow}!${c.reset} Couldn't auto-start the daemon: ${e.message}`);
-        console.log(`  ${c.dim}↳ run \`claude-rpc start\` when you're ready${c.reset}`);
+        console.log(`  ${c.yellow}!${c.reset}  ${'daemon start'.padEnd(16)}${c.dim}couldn't auto-start: ${e.message}${c.reset}`);
+        console.log(`     ${c.gray}↳ run \`claude-rpc start\` when you're ready${c.reset}`);
       }
+      setupOutro(target, changed);
       break;
+    }
     case 'uninstall': await runUninstall(); break;
-    case 'upgrade-config': migrateConfig(); break;
+    case 'upgrade-config':
+      if (!migrateConfig()) console.log(`  ${c.green}✓${c.reset}  config already current — nothing to migrate`);
+      break;
     case 'start':     startDaemon(); break;
     case 'stop':      stopDaemon(); break;
     case 'restart':   restartDaemon(); break;
@@ -1776,19 +1845,19 @@ const packagedDefault = IS_PACKAGED && !cmd;
         try {
           if (kind === 'setup') {
             await runInstall({ exePath: EXE_PATH || process.execPath });
-            console.log(`  ${c.green}✓${c.reset} config + hooks repaired`);
+            console.log(`  ${c.green}✓${c.reset}  config + hooks repaired`);
           } else if (kind === 'rescan') {
             doScan(true);
-            console.log(`  ${c.green}✓${c.reset} aggregate rebuilt from transcripts`);
+            console.log(`  ${c.green}✓${c.reset}  aggregate rebuilt from transcripts`);
           } else if (kind === 'daemon') {
             restartDaemon();
             restarted = true;
-            console.log(`  ${c.green}✓${c.reset} daemon (re)starting`);
+            console.log(`  ${c.green}✓${c.reset}  daemon (re)starting`);
           } else if (kind === 'discord') {
-            console.log(`  ${c.yellow}!${c.reset} discord IPC is down — open the Discord ${c.bold}desktop${c.reset} app (RPC isn't exposed by the browser client). Not auto-fixable.`);
+            console.log(`  ${c.yellow}!${c.reset}  discord IPC is down — open the Discord ${c.bold}desktop${c.reset} app (RPC isn't exposed by the browser client). Not auto-fixable.`);
           }
         } catch (e) {
-          console.log(`  ${c.red}✗${c.reset} ${kind} step failed: ${e.message}`);
+          console.log(`  ${c.red}✗${c.reset}  ${kind} step failed: ${e.message}`);
         }
       }
       // A 'setup' rewire only takes effect once the daemon reloads, so ensure a
@@ -1805,8 +1874,9 @@ const packagedDefault = IS_PACKAGED && !cmd;
     default: {
       if (packagedDefault) {
         if (!isInstalled()) {
-          await runInstall({ exePath: EXE_PATH || process.execPath });
+          const { target } = await runInstall({ exePath: EXE_PATH || process.execPath });
           startDaemon();
+          setupOutro(target);
         } else {
           // Self-heal an existing install. Two real failure modes this fixes:
           //
@@ -1824,13 +1894,14 @@ const packagedDefault = IS_PACKAGED && !cmd;
           // Refresh hooks against the canonical exe, migrate config blocks,
           // wipe state, restart daemon. Anything the user has customized in
           // config.json is preserved (migrateConfig is non-destructive).
-          console.log('Claude RPC is installed. Refreshing…');
+          console.log('');
+          console.log(`  ${c.bold}${c.magenta}◆ claude-rpc${c.reset}  ${c.dim}— already installed; refreshing hooks + config${c.reset}`);
           try {
             const target = ensureCanonicalExe(process.execPath);
             migrateConfig();
             installHooks(target);
           } catch (e) {
-            console.warn(`refresh skipped: ${e.message}`);
+            console.warn(`  ${c.yellow}!${c.reset}  ${'refresh skipped'.padEnd(16)}${c.dim}${e.message}${c.reset}`);
           }
           const wasRunning = stopDaemon({ quiet: true });
           try { if (existsSync(STATE_PATH)) unlinkSync(STATE_PATH); } catch { /* state.json locked or already gone — next hook will recreate it */ }
@@ -1847,11 +1918,16 @@ const packagedDefault = IS_PACKAGED && !cmd;
         // click with no args" install-and-start flow.
         overview();
       } else {
-        // Version in the error line is deliberate: the #1 cause of "unknown
+        // Version in the hint is deliberate: the #1 cause of "unknown
         // command" in the wild is a stale global install resolving instead of
         // the version the user read the docs for. Make the skew visible.
-        fail(`unknown command: ${cmd}  (claude-rpc v${VERSION})`,
-          { hint: 'run `claude-rpc --help` for the full list — if this command should exist, update first: npm install -g claude-rpc@latest', code: EX_USER_ERROR });
+        fail(`unknown command: ${cmd}`, {
+          hint: [
+            'run `claude-rpc --help` for the full command list',
+            `this install is v${VERSION} — if the docs mention \`${cmd}\`, update first: npm install -g claude-rpc@latest`,
+          ],
+          code: EX_USER_ERROR,
+        });
       }
     }
   }

package/src/doctor.js

@@ -50,7 +50,7 @@ export function fixPlan() {
 }
 
 function section(title) {
-  console.log(`\n${c.bold}${title}${c.reset}`);
+  console.log(`\n  ${c.bold}${title}${c.reset}`);
 }
 
 // ── individual checks ────────────────────────────────────────────────────
@@ -363,7 +363,8 @@ function checkDataDir() {
 export function runDoctor() {
   counters.pass = 0; counters.fail = 0; counters.warn = 0;
   findings = [];
-  console.log(`${c.bold}${c.cyan}claude-rpc doctor${c.reset}  ${c.dim}— diagnostic checklist${c.reset}`);
+  console.log('');
+  console.log(`  ${c.bold}${c.magenta}◆ doctor${c.reset}  ${c.dim}— diagnostic checklist${c.reset}`);
 
   section('Runtime');
   checkNodeVersion();

package/src/install.js

@@ -17,10 +17,41 @@ import {
 } from './paths.js';
 import { DEFAULT_CONFIG } from './default-config.js';
 import { VERSION } from './version.js';
+import { c, SYM_OK, SYM_WARN, SYM_FAIL, SYM_INFO, hintLine } from './ui.js';
 
 const STARTUP_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run';
 const STARTUP_VALUE = 'ClaudeRPC';
 
+// Setup output is a phased checklist: every row is `sym  label  detail`, with
+// the label column fixed-width so the detail column lines up across phases.
+// The same rows print standalone (doctor --fix, packaged refresh) and still
+// read fine outside the phased layout.
+//
+// Loud when something changes, near-silent when nothing does: a re-run where
+// everything is already in place collapses to ONE summary line instead of
+// re-printing the checklist. State-changing steps print rows (flushing their
+// pending phase header) and mark the run dirty; confirmations record a
+// `noop()` fact for the summary. Failures always print.
+const LABEL_W = 16;
+let pendingPhase = null;
+let runDirty = false;
+let noopFacts = [];
+
+function resetRun() { pendingPhase = null; runDirty = false; noopFacts = []; }
+function phase(title) { pendingPhase = title; }
+function step(sym, label, detail = '', log = console.log) {
+  if (pendingPhase) {
+    console.log(`\n  ${c.bold}${pendingPhase}${c.reset}`);
+    pendingPhase = null;
+  }
+  log(`  ${sym}  ${label.padEnd(LABEL_W)}${detail ? `${c.dim}${detail}${c.reset}` : ''}`);
+}
+function dirtyStep(sym, label, detail = '', log = console.log) {
+  runDirty = true;
+  step(sym, label, detail, log);
+}
+function noop(fact) { noopFacts.push(fact); }
+
 const EVENTS = [
   'SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse',
   'Stop', 'SubagentStop', 'Notification', 'SessionEnd',
@@ -43,6 +74,7 @@ function isOurHookCommand(cmd) {
 
 export function installHooks(exePath) {
   const settings = readJson(CLAUDE_SETTINGS, {});
+  const before = JSON.stringify(settings.hooks || {});
   settings.hooks = settings.hooks || {};
   // Three modes, three shapes:
   //   packaged → `"<exe>" hook <event>`         (canonical exe, no node)
@@ -69,8 +101,13 @@ export function installHooks(exePath) {
       bucket.push({ matcher: '', hooks: [{ type: 'command', command: wanted }] });
     }
   }
+  if (JSON.stringify(settings.hooks) === before) {
+    noop(`hooks wired (${EVENTS.length} events)`);
+    return false;
+  }
   writeJson(CLAUDE_SETTINGS, settings);
-  console.log(`  hooks → ${CLAUDE_SETTINGS}`);
+  dirtyStep(SYM_OK, 'hooks wired', `${EVENTS.length} events → ${CLAUDE_SETTINGS}`);
+  return true;
 }
 
 export function uninstallHooks() {
@@ -85,7 +122,7 @@ export function uninstallHooks() {
     if (settings.hooks[event].length === 0) delete settings.hooks[event];
   }
   writeJson(CLAUDE_SETTINGS, settings);
-  console.log(`  hooks removed from ${CLAUDE_SETTINGS}`);
+  step(SYM_OK, 'hooks removed', CLAUDE_SETTINGS);
 }
 
 function regCommand(args) {
@@ -106,13 +143,14 @@ export async function addStartupEntry(exePath) {
     '/d', `"${exePath}" daemon`,
     '/f',
   ]);
-  console.log(`  startup → HKCU\\...\\Run\\${STARTUP_VALUE}`);
+  if (runDirty) step(SYM_OK, 'startup entry', `HKCU\\…\\Run\\${STARTUP_VALUE} — daemon starts at login`);
+  else noop('startup entry present');
 }
 
 export async function removeStartupEntry() {
   try {
     await regCommand(['delete', STARTUP_KEY, '/v', STARTUP_VALUE, '/f']);
-    console.log(`  startup entry removed`);
+    step(SYM_OK, 'startup entry', 'removed');
   } catch {
     // Already absent — fine.
   }
@@ -159,7 +197,7 @@ export function ensureCanonicalExe(currentExe) {
       const src = statSync(currentExe);
       const dst = statSync(CANONICAL_EXE);
       if (src.size === dst.size && Math.abs(src.mtimeMs - dst.mtimeMs) < 2000) {
-        console.log(`  exe already installed → ${CANONICAL_EXE}`);
+        noop('exe current');
         return CANONICAL_EXE;
       }
     } catch { /* stat failed — fall through to copy attempt */ }
@@ -176,14 +214,13 @@ export function ensureCanonicalExe(currentExe) {
     }
     copyFileSync(currentExe, CANONICAL_EXE);
     if (process.platform !== 'win32') chmodSync(CANONICAL_EXE, 0o755);
-    console.log(`  exe installed → ${CANONICAL_EXE}`);
-    console.log(`  (the copy at ${currentExe} can be safely deleted)`);
+    dirtyStep(SYM_OK, 'exe installed', CANONICAL_EXE);
+    step(SYM_INFO, 'original copy', `${currentExe} — safe to delete`);
     sweepStaleCanonicalBackups();
     return CANONICAL_EXE;
   } catch (e) {
-    console.warn(`  ! failed to copy exe to ${CANONICAL_EXE}: ${e.message}`);
-    console.warn(`    falling back to ${currentExe} — manual updates that change`);
-    console.warn(`    the exe path may require running 'setup' again.`);
+    step(SYM_WARN, 'exe copy failed', `${CANONICAL_EXE}: ${e.message}`, console.warn);
+    hintLine(`falling back to ${currentExe} — if that file moves, run \`claude-rpc setup\` again`, process.stderr);
     return currentExe;
   }
 }
@@ -199,17 +236,17 @@ export function seedConfig() {
       if (!existsSync(CONFIG_PATH) && existsSync(legacyPath)) {
         mkdirSync(USER_CONFIG_DIR, { recursive: true });
         copyFileSync(legacyPath, CONFIG_PATH);
-        console.log(`  config migrated → ${CONFIG_PATH}`);
-        console.log(`    (was: ${legacyPath} — safe to delete on next 'npm update')`);
+        dirtyStep(SYM_OK, 'config migrated', CONFIG_PATH);
+        step(SYM_INFO, 'legacy copy', `${legacyPath} — safe to delete on the next npm update`);
         return false;
       }
     } catch (e) {
-      console.warn(`  ! legacy-config migration skipped: ${e.message}`);
+      step(SYM_WARN, 'config legacy', `migration skipped: ${e.message}`, console.warn);
     }
   }
 
   if (existsSync(CONFIG_PATH)) {
-    console.log(`  config exists → ${CONFIG_PATH}`);
+    noop('config current');
     return false;
   }
   mkdirSync(USER_CONFIG_DIR, { recursive: true });
@@ -221,9 +258,9 @@ export function seedConfig() {
     seeded.community.instanceId = randomUUID();
   }
   writeFileSync(CONFIG_PATH, JSON.stringify(seeded, null, 2));
-  console.log(`  config seeded → ${CONFIG_PATH}`);
+  dirtyStep(SYM_OK, 'config seeded', CONFIG_PATH);
   if (seeded.community?.enabled && seeded.community.instanceId) {
-    console.log(`  community totals on by default → opt out with \`claude-rpc community off\``);
+    step(SYM_INFO, 'community', `anonymous totals on by default · opt out: ${c.reset}${c.cyan}claude-rpc community off`);
   }
   return true;
 }
@@ -270,7 +307,7 @@ export function migrateConfig({ silent = false } = {}) {
   let cfg;
   try { cfg = JSON.parse(readFileSync(CONFIG_PATH, 'utf8')); }
   catch (e) {
-    if (!silent) console.warn(`  ! could not read config for migration: ${e.message}`);
+    if (!silent) step(SYM_WARN, 'config migration', `could not read config: ${e.message}`, console.warn);
     return false;
   }
   if (!cfg || typeof cfg !== 'object') return false;
@@ -358,15 +395,9 @@ export function migrateConfig({ silent = false } = {}) {
     if (changed) added.push('presence.buttons[] → CTA');
   }
 
-  if (added.length === 0) {
-    if (!silent) console.log(`  config up to date → ${CONFIG_PATH}`);
-    return false;
-  }
+  if (added.length === 0) return false;
   writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2));
-  if (!silent) {
-    console.log(`  config migrated  → ${CONFIG_PATH}`);
-    console.log(`    added: ${added.join(', ')}`);
-  }
+  if (!silent) dirtyStep(SYM_OK, 'config migrated', `added: ${added.join(', ')}`);
   return true;
 }
 
@@ -417,12 +448,29 @@ function verifyHookPipe(exePath) {
 // Best-effort + loud: a failed -g (perms, offline) returns false so the caller
 // can stop with the manual command rather than wire a dead hook.
 function promoteNpxToGlobal() {
-  console.log('  npx is one-off — installing claude-rpc globally so hooks survive…');
+  // Already promoted on a previous run? The PATH-resolved bin answers fast.
+  try {
+    const v = spawnSync('claude-rpc', ['--version'], {
+      encoding: 'utf8', timeout: 4000, windowsHide: true,
+      shell: process.platform === 'win32',
+    });
+    if ((v.stdout || '').trim() === `claude-rpc ${VERSION}`) {
+      noop('global install current');
+      return true;
+    }
+  } catch { /* not installed yet — promote below */ }
   const r = spawnSync('npm', ['install', '-g', `claude-rpc@${VERSION}`], {
-    stdio: 'inherit',
+    encoding: 'utf8',
     shell: process.platform === 'win32',   // npm is npm.cmd on Windows
   });
-  return !r.error && r.status === 0;
+  if (r.error || r.status !== 0) {
+    // The piped npm chatter only matters when it failed.
+    if (r.stdout) process.stderr.write(r.stdout);
+    if (r.stderr) process.stderr.write(r.stderr);
+    return false;
+  }
+  dirtyStep(SYM_OK, 'installed globally', `claude-rpc@${VERSION} — hooks survive npx's throwaway cache`);
+  return true;
 }
 
 // Best-effort registry check. npx serves stale cached copies without
@@ -442,72 +490,98 @@ function warnIfStale() {
     const [l, v] = [num(latest), num(VERSION)];
     const newer = l[0] !== v[0] ? l[0] > v[0] : l[1] !== v[1] ? l[1] > v[1] : l[2] > v[2];
     if (newer) {
-      console.warn(`  ! you're running v${VERSION} but v${latest} is published — npx may have served a stale cache.`);
-      console.warn(`    for the newest version, stop here and re-run:  npx claude-rpc@latest setup`);
+      step(SYM_WARN, 'newer version', `v${latest} is published but this is v${VERSION} — npx may have served a stale cache`, console.warn);
+      hintLine('for the newest version, stop here and re-run: npx claude-rpc@latest setup', process.stderr);
     }
   } catch { /* offline or npm missing — a version check must never block setup */ }
 }
 
 export async function install({ exePath, withStartup = true } = {}) {
+  resetRun();
+  console.log('');
+  console.log(`  ${c.bold}${c.magenta}◆ claude-rpc setup${c.reset}  ${c.dim}v${VERSION}${c.reset}`);
   warnIfStale();
   if (IS_NPX) {
     if (!promoteNpxToGlobal()) {
-      console.error('\n  ✗ Global install failed. Run this once, then you\'re set:');
-      console.error('      npm install -g claude-rpc && claude-rpc setup');
+      console.error('');
+      step(SYM_FAIL, 'global install', 'failed', console.error);
+      hintLine('run this once, then you\'re set: npm install -g claude-rpc && claude-rpc setup', process.stderr);
       const err = new Error('npx self-install failed');
       err.code = 3;   // system error (see exit-code contract)
       throw err;
     }
-    console.log('  ✓ claude-rpc installed globally\n');
-  }
-  if (process.platform !== 'win32' && withStartup) {
-    console.warn('Note: startup registration only works on Windows; other steps still run.');
+    step(SYM_OK, 'global install', `claude-rpc@${VERSION}`);
   }
   const incoming = exePath || process.execPath;
   // Canonicalize first so hook + startup entries point at a stable location,
   // not at the temp/Downloads path the user happened to launch from.
+  if (IS_PACKAGED) phase('binary');
   const target = ensureCanonicalExe(incoming);
-  console.log('Installing Claude RPC…');
+
+  phase('config');
   // Order matters: seed creates the file if missing, then migrate fills in
   // any blocks new exe versions added (e.g. presence.byStatus from v0.3.6).
   seedConfig();
   migrateConfig();
-  installHooks(target);
-  if (withStartup && process.platform === 'win32') {
-    try { await addStartupEntry(target); }
-    catch (e) { console.warn(`  startup entry failed: ${e.message}`); }
-  }
 
+  phase('claude code');
+  installHooks(target);
   // Proof the hook pipe actually fires. A setup that returns success
   // without verification is a lie — we caught broken-hook-path bugs
   // twice during v0.3.x because no one ran a real event after install.
   const probe = verifyHookPipe(target);
-  if (probe.ok) {
-    console.log(`  hook pipe   ✓ ${probe.detail}`);
+  if (!probe.ok) {
+    step(SYM_FAIL, 'hook verify', probe.detail, console.warn);
+    hintLine('run `claude-rpc doctor` for a full diagnostic', process.stderr);
+  } else if (runDirty) {
+    step(SYM_OK, 'hook verified', probe.detail);
   } else {
-    console.warn(`  hook pipe   ✗ ${probe.detail}`);
-    console.warn(`              ↳ run \`claude-rpc doctor\` for a full diagnostic`);
+    noop('hook pipe verified');
   }
 
-  console.log('\nDone.');
-  console.log(`Config: ${CONFIG_PATH}`);
-  console.log(`  (a working Discord app is bundled — edit clientId only to use your own)`);
-  // setup auto-starts the daemon (see cli.js), so we point at management +
-  // verification rather than a start command. The packaged exe manages the
-  // daemon via its own subcommands; the npm/dev bin uses `claude-rpc …`.
-  if (IS_PACKAGED) {
-    console.log(`\nManage the daemon:  "${target}" daemon  (start) · check with claude-rpc doctor`);
-  } else {
-    console.log(`\nManage the daemon:  claude-rpc start | stop | status`);
-    console.log(`Verify wiring:      claude-rpc doctor`);
+  // The CLI's setup case launches the daemon right after this returns, so its
+  // row lands under this heading; setupOutro() then closes the screen.
+  phase('daemon');
+  if (withStartup) {
+    if (process.platform === 'win32') {
+      try { await addStartupEntry(target); }
+      catch (e) { step(SYM_WARN, 'startup entry', `failed: ${e.message}`, console.warn); }
+    } else if (runDirty) {
+      step(SYM_INFO, 'startup entry', 'skipped — login autostart is Windows-only');
+    }
   }
+  // Nothing changed: the checklist above stayed silent, so say so in one line.
+  if (!runDirty && probe.ok) {
+    console.log(`  ${SYM_OK}  ${c.bold}already set up${c.reset}  ${c.dim}${noopFacts.join(' · ')}${c.reset}`);
+  }
+  return { target, changed: runDirty };
+}
+
+// The single closing block of `claude-rpc setup` — what to do now, where the
+// levers are. Printed by the CLI after the daemon launch so it always lands
+// last; doctor --fix re-runs install() without it.
+export function setupOutro(target, changed = true) {
+  if (!changed) return;
+  const point = (label, value, note = '') =>
+    console.log(`     ${c.dim}→${c.reset}  ${c.dim}${label.padEnd(14)}${c.reset} ${c.cyan}${value}${c.reset}${note ? `  ${c.dim}${note}${c.reset}` : ''}`);
+  console.log('');
+  console.log(`  ${SYM_OK}  ${c.bold}setup complete${c.reset} — open Claude Code and send a prompt; your card goes live in Discord.`);
+  point('verify wiring', 'claude-rpc doctor');
+  if (IS_PACKAGED) point('start daemon', `"${target}" daemon`, 'also runs automatically at login');
+  else point('manage daemon', 'claude-rpc start · stop · status');
+  point('config', CONFIG_PATH, 'a working Discord app is bundled — set clientId only to use your own');
+  console.log('');
 }
 
 export async function uninstall() {
-  console.log('Uninstalling Claude RPC…');
+  console.log('');
+  console.log(`  ${c.bold}${c.magenta}◆ claude-rpc uninstall${c.reset}`);
+  console.log('');
   uninstallHooks();
   if (process.platform === 'win32') await removeStartupEntry();
-  console.log('\nDone. (Config at %APPDATA%\\claude-rpc\\ left intact — delete manually if you want.)');
+  console.log('');
+  console.log(`  ${SYM_OK}  ${c.bold}uninstalled${c.reset} — config at ${c.cyan}${USER_CONFIG_DIR}${c.reset} ${c.dim}left intact; delete it manually if you want.${c.reset}`);
+  console.log('');
 }
 
 export function isInstalled() {

package/src/ui.js

@@ -43,12 +43,21 @@ export const EX_USER_ERROR = 1;
 export const EX_SYS_ERROR  = 2;
 export const EX_BAD_STATE  = 3;
 
-// Print a one-line message plus an indented dim hint on the next line.
-// Hint is the tired-user safety net: every failure surface tells you
-// what to type next. Empty hint omits the second line.
+// Hint lines sit directly under the message they belong to, aligned with the
+// label (the symbol column differs between TTY glyphs and [fail]-style tags).
+const HINT_INDENT = ' '.repeat(TTY ? 5 : 10);
+
+export function hintLine(text, stream = process.stdout) {
+  stream.write(`${HINT_INDENT}${c.gray}↳ ${text}${c.reset}\n`);
+}
+
+// Print a one-line message plus aligned dim hint line(s) below it. A hint is
+// the tired-user safety net: it tells you what to type next. Accepts a single
+// string or an array (one ↳ line each); empty omits them.
 function withHint(sym, label, hint, stream = process.stdout) {
   stream.write(`  ${sym}  ${label}\n`);
-  if (hint) stream.write(`        ${c.gray}↳ ${hint}${c.reset}\n`);
+  const hints = Array.isArray(hint) ? hint : (hint ? [hint] : []);
+  for (const h of hints) hintLine(h, stream);
 }
 
 export function ok(label, detail = '') {
@@ -63,11 +72,11 @@ export function warn(label, hint = '') {
   withHint(SYM_WARN, label, hint);
 }
 
-// Print a failure with a hint and exit with the given code. The hint is
-// the difference between a frustrated user and a fixed user — always
-// supply one when you can, and default it to `claude-rpc doctor` when
-// you have no better idea.
-export function fail(label, { hint = 'run `claude-rpc doctor` for a full diagnostic', code = EX_USER_ERROR } = {}) {
+// Print a failure with an optional hint and exit with the given code. Hints
+// must be contextual: point at `claude-rpc doctor` only for local wiring or
+// state problems it actually diagnoses — for usage errors, remote rejections,
+// and network failures, give a directly useful hint or none at all.
+export function fail(label, { hint = '', code = EX_USER_ERROR } = {}) {
   withHint(SYM_FAIL, label, hint, process.stderr);
   process.exit(code);
 }
@@ -93,7 +102,5 @@ export function check(label, status, detail = '', hint = '') {
   else                        sym = SYM_INFO;
   const tail = detail ? `  ${c.dim}${detail}${c.reset}` : '';
   process.stdout.write(`  ${sym}  ${label}${tail}\n`);
-  if (hint && status !== 'pass') {
-    process.stdout.write(`        ${c.gray}↳ ${hint}${c.reset}\n`);
-  }
+  if (hint && status !== 'pass') hintLine(hint);
 }

package/src/version.js

@@ -11,7 +11,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ROOT } from './paths.js';
 
-const BAKED = '0.15.0';
+const BAKED = '0.15.2';
 
 function readPkgVersion() {
   try {