@luanpdd/kit-mcp 1.26.0 → 1.28.0

package/kit/skills/supabase-postgres-roles/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: supabase-postgres-roles
-description: Use ao gerenciar Postgres roles em Supabase — system access (cron jobs, BI tools, ETL, admin scripts). Distinção canônica vs RLS+Custom Claims (application access). CREATE ROLE syntax + password best practices + GRANT/REVOKE + role hierarchy (INHERIT/NOINHERIT) + 10 predefined Supabase roles. NÃO usar para "admin vs user" (use RLS + Custom Claims v1.25). v1.26 incorpora 100% da doc oficial.
+description: Use ao gerenciar Postgres roles em Supabase — system access (cron jobs, BI tools, ETL, admin scripts). Distinção canônica vs RLS+Custom Claims (application access).
 ---
 
 # Supabase — Postgres Roles

package/kit/skills/supabase-rls-defense-in-depth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: supabase-rls-defense-in-depth
-description: Use ao desenhar defense-in-depth RLS em Supabase — event trigger rls_auto_enable (default projetos novos), BYPASSRLS role privilege, service_role caveat, security definer functions como bypass controlado, views security_invoker=true. Camada de proteção contra esquecimento humano e third-party tooling acessando DB diretamente. v1.23 incorpora a doc oficial RLS.
+description: Use ao desenhar defense-in-depth RLS em Supabase — event trigger rls_auto_enable (default projetos novos), BYPASSRLS role privilege, service_role caveat, security definer functions como bypass co…
 ---
 
 # Supabase — RLS Defense in Depth

package/kit/skills/supabase-rls-policies/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: supabase-rls-policies
-description: Use ao criar/auditar RLS — sempre (select auth.uid()), policies separadas por operação, GRANTs antes de ENABLE RLS, IS NOT NULL para anti silent-fail, índices nas colunas, NUNCA user_metadata em autorização. v1.23 incorpora 100% da doc oficial RLS Supabase + defense in depth.
+description: Use ao criar/auditar RLS — sempre (select auth.uid()), policies separadas por operação, GRANTs antes de ENABLE RLS, IS NOT NULL para anti silent-fail, índices nas colunas, NUNCA user_meta…
 ---
 
 # Supabase — RLS Policies

package/kit/skills/super-admin-platform-pattern/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: super-admin-platform-pattern
-description: Use ao implementar plataforma super-admin em B2B SaaS multi-tenant — cross-tenant view sobre todas orgs, impersonation com TTL 30min + reason obrigatório + banner visual, super_admin:bool em app_metadata via service_role apenas, audit obrigatório (BLOCKER) em toda ação super-admin.
+description: "Use ao implementar plataforma super-admin em B2B SaaS multi-tenant…"
 ---
 
 # Super-Admin Platform Pattern — B2B SaaS Multi-Tenant

package/kit/skills/tenant-quente-mitigacao/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tenant-quente-mitigacao
-description: Use ao escalar Postgres multi-tenant em Supabase quando 1 tenant consome >>> que outros (problema "Justin Bieber tenant" do DDIA Ch 6) — métricas de detecção (queries/min, storage GB, slots conexão), 5 estratégias de mitigação com tradeoffs (rate limit por tenant, pool isolado, read replica dedicada, desnormalização MVs, request shaping pgmq), particionamento range vs hash para tenant_id, índices document-partitioned vs term-partitioned, rebalanceamento sem downtime.
+description: Use ao escalar Postgres multi-tenant em Supabase quando 1 tenant consome >>> que outros (problema "Justin Bieber tenant" do DDIA Ch 6)…
 ---
 
 # Tenant Quente — Mitigação (DDIA Ch 6 aplicado a Postgres + Supabase)

package/kit/skills/whatsapp-conversation-state-machine/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: whatsapp-conversation-state-machine
-description: Use ao modelar conversação WhatsApp como state machine xstate v5 + persistência em PG — estados conversation_started → opted_in → engaged → action_taken → closed, persiste estado em conversations table, integra com lead pipeline.
+description: Use ao modelar conversação WhatsApp como state machine xstate v5 + persistência em PG…
 ---
 
 # WhatsApp Conversation State Machine — xstate v5 + Postgres

package/package.json

@@ -1,63 +1,63 @@
-{
-  "name": "@luanpdd/kit-mcp",
-  "version": "1.26.0",
-  "description": "Generic infrastructure to ship YOUR personal kit of agents/commands/skills as an MCP server, with cross-IDE sync (Claude Code, Cursor, Codex, Gemini, Windsurf, Antigravity, Copilot, Trae).",
-  "type": "module",
-  "bin": {
-    "kit-mcp": "bin/mcp.js",
-    "kit": "bin/cli.js"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "kit/",
-    "gates/",
-    "README.md",
-    "LICENSE"
-  ],
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "claude",
-    "cursor",
-    "codex",
-    "gemini",
-    "agents",
-    "skills"
-  ],
-  "author": "luanpdd",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/luanpdd/kit-mcp.git"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "start": "node bin/mcp.js",
-    "cli": "node bin/cli.js",
-    "smoke": "node bin/cli.js kit list-agents | head -5",
-    "test": "node test/run.mjs test/unit",
-    "test:all": "node test/run.mjs test",
-    "test:integration": "node test/run.mjs test/integration",
-    "test:mutation": "stryker run",
-    "prepublishOnly": "node scripts/regen-manifest.js && node scripts/update-readme-counts.js && node test/run.mjs test/unit && node test/run.mjs test/integration"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "commander": "^14.0.3",
-    "picocolors": "^1.1.1"
-  },
-  "optionalDependencies": {
-    "@inquirer/prompts": "^8.4.2",
-    "chokidar": "^5.0.0",
-    "open": "^11.0.0"
-  },
-  "devDependencies": {
-    "@stryker-mutator/core": "9.6.1"
-  }
-}
+{
+  "name": "@luanpdd/kit-mcp",
+  "version": "1.28.0",
+  "description": "Generic infrastructure to ship YOUR personal kit of agents/commands/skills as an MCP server, with cross-IDE sync (Claude Code, Cursor, Codex, Gemini, Windsurf, Antigravity, Copilot, Trae).",
+  "type": "module",
+  "bin": {
+    "kit-mcp": "bin/mcp.js",
+    "kit": "bin/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "kit/",
+    "gates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "codex",
+    "gemini",
+    "agents",
+    "skills"
+  ],
+  "author": "luanpdd",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/luanpdd/kit-mcp.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node bin/mcp.js",
+    "cli": "node bin/cli.js",
+    "smoke": "node bin/cli.js kit list-agents | head -5",
+    "test": "node test/run.mjs test/unit",
+    "test:all": "node test/run.mjs test",
+    "test:integration": "node test/run.mjs test/integration",
+    "test:mutation": "stryker run",
+    "prepublishOnly": "node scripts/regen-manifest.js && node scripts/update-readme-counts.js && node test/run.mjs test/unit && node test/run.mjs test/integration"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "commander": "^14.0.3",
+    "picocolors": "^1.1.1"
+  },
+  "optionalDependencies": {
+    "@inquirer/prompts": "^8.4.2",
+    "chokidar": "^5.0.0",
+    "open": "^11.0.0"
+  },
+  "devDependencies": {
+    "@stryker-mutator/core": "9.6.1"
+  }
+}

package/src/cli/index.js

@@ -27,6 +27,7 @@ import { collectFailures, summarizeByAgent, writeLearnings } from '../core/failu
 import { reflect } from '../core/reflect.js';
 import { listReplays, loadReplay } from '../core/replays.js';
 import { installMcp, listInstallTargets } from '../mcp-server/install.js';
+import { listLogs, tailLogs, logDir, currentLogPath } from '../core/logger.js';
 import * as render from './render.js';
 import { c, icons, spinner, progress, select, confirm } from '../core/ui.js';
 import { readLock, lockPathFor } from '../ui/lockfile.js';
@@ -217,14 +218,28 @@ sync.command('install [target]')
   .option('--project-root <path>')
   .option('--mode <mode>', 'reference | copy', 'reference')
   .option('--dry-run')
+  .option('--quiet', 'Suppress per-file progress; keep final summary')
   .action(async (target, opts) => {
     if (!target) target = await pickTarget(listTargets(), 'Which IDE do you want to sync the kit into?');
-    const result = await withProgress(
-      `Syncing kit → ${target}`,
-      300,
-      (onProgress) => syncTo(target, { projectRoot: opts.projectRoot, mode: opts.mode, dryRun: opts.dryRun, onProgress }),
-      { tool: 'sync.install', projectRoot: opts.projectRoot },
-    );
+    // Phase 160 (v1.28): count written vs skipped so the post-sync summary
+    // can render "X new/updated, Y unchanged".
+    const tally = { written: 0, skipped: 0 };
+    const wrapOnProgress = (orig) => (ev) => {
+      if (ev?.skipped) tally.skipped += 1;
+      else tally.written += 1;
+      if (orig) orig(ev);
+    };
+    const runSync = (onProgress) => syncTo(target, {
+      projectRoot: opts.projectRoot,
+      mode: opts.mode,
+      dryRun: opts.dryRun,
+      onProgress: wrapOnProgress(opts.quiet ? null : onProgress),
+    });
+    const result = opts.quiet
+      ? await runSync()
+      : await withProgress(`Syncing kit → ${target}`, 300, runSync,
+          { tool: 'sync.install', projectRoot: opts.projectRoot });
+    result._tally = tally; // surfaced by renderSyncInstall (v1.28)
     out(result, render.renderSyncInstall);
   });
 sync.command('remove <target>')
@@ -669,6 +684,30 @@ async function runDoctorChecks(projectRoot) {
     }
   } catch { /* tmpdir scan is best-effort */ }
 
+  // 8. (v1.28) log dir writable — required for kit logs
+  try {
+    const dir = logDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const probe = path.join(dir, `.doctor-probe-${process.pid}`);
+    fs.writeFileSync(probe, '', 'utf8');
+    fs.unlinkSync(probe);
+    const files = listLogs();
+    checks.push({ label: 'log dir', status: 'pass',
+      detail: `${dir} writable (${files.length} log file${files.length === 1 ? '' : 's'})` });
+  } catch (err) {
+    checks.push({ label: 'log dir', status: 'fail',
+      detail: `${logDir()} not writable: ${err.message}`,
+      fix: 'check permissions or set KIT_MCP_LOG_DIR to a writable path' });
+  }
+
+  // 9. (v1.28) sidecar auto-spawn config — informational
+  const noUi = process.env.KIT_MCP_NO_UI === '1' || process.env.KIT_MCP_NO_UI === 'true';
+  checks.push({ label: 'sidecar auto-spawn', status: noUi ? 'warn' : 'pass',
+    detail: noUi
+      ? 'KIT_MCP_NO_UI=1 — sidecar will NOT auto-start on MCP boot'
+      : 'enabled (default) — sidecar starts when MCP server boots',
+    fix: noUi ? 'unset KIT_MCP_NO_UI if you want live tool-call visibility' : undefined });
+
   return checks;
 }
 
@@ -739,4 +778,304 @@ function renderUiStatusFallback(v) {
   ].join('\n');
 }
 
+// --- status (Phase 162, v1.28: live metrics snapshot + log file path) ---
+program.command('status')
+  .description('Show MCP server metrics (p50/p95/p99/error rate) + log file path.')
+  .option('--project-root <path>', 'Default: cwd')
+  .action(async (opts) => {
+    const { snapshot, loadSnapshots } = await import('../core/metrics.js');
+    const projectRoot = opts.projectRoot || process.cwd();
+    const live = snapshot(); // current-process metrics (only useful when called from inside the MCP process)
+    const persisted = await loadSnapshots(projectRoot, 60 * 60 * 1000).catch(() => []); // last hour
+
+    if (program.opts().json) {
+      out({ live, persistedCount: persisted.length, latest: persisted[persisted.length - 1] || null, logPath: currentLogPath() }, () => '');
+      return;
+    }
+
+    process.stdout.write(`\n${c.bold('kit-mcp status')}\n\n`);
+
+    // Sidecar
+    const lock = readLock(projectRoot);
+    process.stdout.write(`${c.bold('sidecar:')}  ${lock ? c.green(`running on port ${lock.port}`) : c.dim('not running')}\n`);
+
+    // Log file
+    const files = listLogs();
+    process.stdout.write(`${c.bold('log:')}      ${currentLogPath()}\n`);
+    process.stdout.write(`           ${c.dim(`${files.length} file(s) in ${logDir()}`)}\n`);
+
+    // Latency from latest persisted snapshot (last hour window)
+    const latest = persisted[persisted.length - 1];
+    const lat = latest?.latency || live.latency || {};
+    const tools = Object.keys(lat);
+    process.stdout.write(`\n${c.bold('latency (last hour, or current process):')}\n`);
+    if (tools.length === 0) {
+      process.stdout.write(`  ${c.dim('no samples yet')}\n`);
+    } else {
+      const w = Math.max(...tools.map((t) => t.length));
+      for (const t of tools) {
+        const s = lat[t];
+        process.stdout.write(`  ${t.padEnd(w)}  p50 ${c.cyan(s.p50 + 'ms').padEnd(20)} p95 ${c.cyan(s.p95 + 'ms').padEnd(20)} p99 ${c.cyan(s.p99 + 'ms').padEnd(20)} n=${s.count}\n`);
+      }
+    }
+
+    // Error rate from counters
+    const counters = latest?.counters || live.counters || {};
+    let okTotal = 0, errTotal = 0;
+    for (const [k, v] of Object.entries(counters)) {
+      if (k.endsWith(':ok')) okTotal += v;
+      if (k.endsWith(':error')) errTotal += v;
+    }
+    const total = okTotal + errTotal;
+    const rate = total === 0 ? 0 : (errTotal / total) * 100;
+    process.stdout.write(`\n${c.bold('errors:')}   ${errTotal}/${total} (${rate.toFixed(2)}%)\n\n`);
+  });
+
+// --- init (Phase 161, v1.28: guided onboarding — install + sync + doctor) ---
+program.command('init')
+  .description('Onboard: register kit-mcp into an IDE, sync the kit, run doctor.')
+  .option('--ide <id>', 'Skip the IDE picker (e.g. claude-code, cursor, codex)')
+  .option('--project-root <path>', 'Default: cwd')
+  .option('--non-interactive', 'Fail fast if --ide is missing instead of prompting')
+  .option('--mode <mode>', 'sync mode: reference | copy', 'reference')
+  .action(async (opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    const targets = listInstallTargets();
+    const targetIds = targets.map(t => t.id);
+
+    let ide = opts.ide;
+    if (!ide) {
+      if (opts.nonInteractive) {
+        process.stderr.write(`${c.red(icons.cross)} --non-interactive requires --ide=<${targetIds.join('|')}>\n`);
+        process.exit(2);
+      }
+      ide = await pickTarget(targets, 'Which IDE should kit-mcp register with?');
+    }
+    if (!targetIds.includes(ide)) {
+      process.stderr.write(`${c.red(icons.cross)} unknown IDE "${ide}" — valid: ${targetIds.join(', ')}\n`);
+      process.exit(2);
+    }
+
+    process.stdout.write(`\n${c.bold('kit init')} → ${ide}\n\n`);
+
+    // 1. Register MCP server in IDE config
+    process.stdout.write(`${c.cyan('1/3')} registering MCP server...\n`);
+    try {
+      const r = await installMcp(ide, { projectRoot });
+      process.stdout.write(`     ${c.green(icons.check)} ${r.path || 'config updated'}\n`);
+    } catch (e) {
+      process.stdout.write(`     ${c.red(icons.cross)} ${e.message}\n`);
+      process.exit(1);
+    }
+
+    // 2. Sync kit content
+    process.stdout.write(`\n${c.cyan('2/3')} syncing kit content...\n`);
+    const tally = { written: 0, skipped: 0 };
+    try {
+      const r = await syncTo(ide, {
+        projectRoot,
+        mode: opts.mode,
+        onProgress: (ev) => { if (ev?.skipped) tally.skipped += 1; else tally.written += 1; },
+      });
+      const total = (r.written || []).length;
+      process.stdout.write(`     ${c.green(icons.check)} ${total} files (${tally.written} new/updated, ${tally.skipped} unchanged)\n`);
+    } catch (e) {
+      process.stdout.write(`     ${c.red(icons.cross)} ${e.message}\n`);
+      process.exit(1);
+    }
+
+    // 3. Doctor
+    process.stdout.write(`\n${c.cyan('3/3')} running diagnostic...\n`);
+    const checks = await runDoctorChecks(projectRoot);
+    const failed = checks.filter(c => c.status === 'fail').length;
+    const warned = checks.filter(c => c.status === 'warn').length;
+    const passed = checks.length - failed - warned;
+    process.stdout.write(`     ${failed === 0 ? c.green(icons.check) : c.red(icons.cross)} `
+      + `${passed} pass · ${warned} warn · ${failed} fail\n`);
+
+    // 4. Final confirmation
+    try {
+      const kit = await listKit();
+      process.stdout.write(`\n${c.green(icons.check)} ${c.bold(ide)} now sees `
+        + `${c.cyan(kit.skills.length)} skills, `
+        + `${c.cyan(kit.agents.length)} agents, `
+        + `${c.cyan(kit.commands.length)} commands\n\n`);
+    } catch { /* non-fatal */ }
+
+    if (failed > 0) {
+      process.stdout.write(`${c.yellow(icons.warn)} doctor reported failures — run ${c.cyan('kit doctor')} for details\n`);
+      process.exit(1);
+    }
+  });
+
+// --- replay (Phase 165, v1.28: inspect recorded agent Task() payloads) ---
+const replay = program.command('replay').description('List or inspect recorded agent replays.');
+
+replay.command('list')
+  .description('List replays in <project-root>/.planning/replays/')
+  .option('--project-root <path>', 'Default: cwd')
+  .action(async (opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    const items = await listReplays({ projectRoot });
+    if (program.opts().json) {
+      out(items, () => '');
+      return;
+    }
+    if (items.length === 0) {
+      process.stderr.write(`${c.yellow(icons.warn)} no replays at ${path.join(projectRoot, '.planning', 'replays')}\n`);
+      return;
+    }
+    process.stdout.write(`\n${c.bold(items.length + ' replay(s)')}\n\n`);
+    for (const r of items) {
+      process.stdout.write(`  ${c.cyan(r.id)}\n`);
+      process.stdout.write(`    agent: ${c.bold(r.agent || '?')}  phase: ${r.phase || '?'}  plan: ${r.plan || '?'}\n`);
+      process.stdout.write(`    ${c.dim(r.recorded_at || '?')}\n\n`);
+    }
+  });
+
+replay.command('show <id>')
+  .description('Show the full recorded payload for a replay id.')
+  .option('--project-root <path>', 'Default: cwd')
+  .action(async (id, opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    try {
+      const r = await loadReplay(id, { projectRoot });
+      if (program.opts().json) {
+        out(r, () => '');
+        return;
+      }
+      process.stdout.write(`\n${c.bold(r.id)}\n`);
+      process.stdout.write(`${c.dim('recorded:')} ${r.recorded_at}\n`);
+      process.stdout.write(`${c.dim('agent:')}    ${c.bold(r.agent || '?')}\n`);
+      process.stdout.write(`${c.dim('phase:')}    ${r.phase || '?'}\n`);
+      process.stdout.write(`${c.dim('plan:')}     ${r.plan || '?'}\n`);
+      if (r.outcome) {
+        process.stdout.write(`${c.dim('outcome:')}  ${JSON.stringify(r.outcome)}\n`);
+      }
+      process.stdout.write(`\n${c.bold('payload:')}\n`);
+      const { id: _id, recorded_at: _rec, agent: _a, phase: _p, plan: _pl, outcome: _o, ...rest } = r;
+      process.stdout.write(JSON.stringify(rest, null, 2) + '\n');
+    } catch (e) {
+      process.stderr.write(`${c.red(icons.cross)} replay "${id}" not found: ${e.message}\n`);
+      process.exit(1);
+    }
+  });
+
+replay.command('diff <id>')
+  .description('Compare a replay payload against its most recent re-record (if any).')
+  .option('--project-root <path>', 'Default: cwd')
+  .action(async (id, opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    try {
+      const target = await loadReplay(id, { projectRoot });
+      const all = await listReplays({ projectRoot });
+      // Find newest replay with same agent that isn't the target itself.
+      const candidate = all.find((r) => r.id !== id && r.agent === target.agent);
+      if (!candidate) {
+        process.stdout.write(`${c.yellow(icons.warn)} no peer replay for agent "${target.agent}" — nothing to diff\n`);
+        return;
+      }
+      const newer = await loadReplay(candidate.id, { projectRoot });
+      const a = JSON.stringify(target, null, 2).split('\n');
+      const b = JSON.stringify(newer, null, 2).split('\n');
+      process.stdout.write(`\n${c.bold(`diff ${id}  ↔  ${candidate.id}`)}\n\n`);
+      const max = Math.max(a.length, b.length);
+      for (let i = 0; i < max; i++) {
+        if (a[i] !== b[i]) {
+          if (a[i] !== undefined) process.stdout.write(c.red('-') + ' ' + a[i] + '\n');
+          if (b[i] !== undefined) process.stdout.write(c.green('+') + ' ' + b[i] + '\n');
+        }
+      }
+    } catch (e) {
+      process.stderr.write(`${c.red(icons.cross)} ${e.message}\n`);
+      process.exit(1);
+    }
+  });
+
+// --- inspect (Phase 163, v1.28: live TUI mirror of MCP request/response) ---
+program.command('inspect')
+  .description('Live request/response mirror — pretty-print MCP tool calls as they happen.')
+  .option('--tail <n>', 'show last N events (default 20)', '20')
+  .action(async (opts) => {
+    const lines = parseInt(opts.tail, 10) || 20;
+    if (process.env.KIT_MCP_INSPECT !== '1' && process.env.KIT_MCP_INSPECT !== 'true') {
+      process.stderr.write(`${c.yellow(icons.warn)} verbose payload capture is OFF\n`);
+      process.stderr.write(`${c.dim('set KIT_MCP_INSPECT=1 in the env where kit-mcp runs to capture args/result')}\n`);
+      process.stderr.write(`${c.dim('(events are still tailed; just without payloads)')}\n\n`);
+    }
+
+    const render = (raw) => {
+      try {
+        const ev = JSON.parse(raw);
+        const t = ev.ts ? ev.ts.replace('T', ' ').replace('Z', '') : '?';
+        const status = ev.status === 'ok' ? c.green('●') : c.red('●');
+        const tool = c.bold(ev.tool || '?');
+        const action = ev.action ? c.cyan(ev.action) : '';
+        const dur = ev.duration_ms !== undefined ? c.dim(`(${ev.duration_ms}ms)`) : '';
+        process.stdout.write(`\n${status} ${c.dim(t)}  ${tool} ${action} ${dur}\n`);
+        if (ev.args !== undefined) {
+          process.stdout.write(`  ${c.dim('req:')}  ${JSON.stringify(ev.args)}\n`);
+        }
+        if (ev.result !== undefined && ev.result !== null) {
+          const pretty = JSON.stringify(ev.result);
+          process.stdout.write(`  ${c.dim('res:')}  ${pretty.length > 200 ? pretty.slice(0, 200) + '…' : pretty}\n`);
+        }
+        if (ev.error_type) {
+          process.stdout.write(`  ${c.red('err:')}  ${ev.error_type}\n`);
+        }
+      } catch {
+        process.stdout.write(raw + '\n');
+      }
+    };
+
+    const t = tailLogs({ lines, follow: true, onLine: render });
+    process.stdout.write(`${c.dim(`-- inspecting ${currentLogPath()} (Ctrl-C to stop) --`)}\n`);
+    process.on('SIGINT', () => { t.stop(); process.exit(0); });
+    await new Promise(() => {});
+  });
+
+// --- logs (Phase 158, v1.28: tail kit-mcp tool-call log) ---
+program.command('logs')
+  .description('Tail JSONL logs of MCP tool invocations (~/.kit-mcp/logs/).')
+  .option('--tail <n>', 'show last N lines (default 50)', '50')
+  .option('--follow', 'keep streaming new events as they arrive')
+  .option('--path', 'print the current log file path and exit')
+  .action(async (opts) => {
+    if (opts.path) {
+      process.stdout.write(`${currentLogPath()}\n`);
+      return;
+    }
+    const lines = parseInt(opts.tail, 10) || 50;
+    const files = listLogs();
+    if (files.length === 0) {
+      process.stderr.write(`${c.yellow(icons.warn)} no logs yet at ${logDir()}\n`);
+      process.stderr.write(`${c.dim('logs are appended when the MCP server handles a tool call')}\n`);
+      process.exit(0);
+    }
+    const isJson = program.opts().json;
+    const render = (raw) => {
+      if (isJson) { process.stdout.write(raw + '\n'); return; }
+      try {
+        const ev = JSON.parse(raw);
+        const t = ev.ts ? ev.ts.replace('T', ' ').replace('Z', '') : '?';
+        const status = ev.status === 'ok' ? c.green(icons.check) : c.red(icons.cross);
+        const tool = c.bold(ev.tool || '?');
+        const action = ev.action ? c.dim(`[${ev.action}]`) : '';
+        const dur = ev.duration_ms !== undefined ? c.cyan(`${ev.duration_ms}ms`) : '';
+        const err = ev.error_type ? c.red(` (${ev.error_type})`) : '';
+        process.stdout.write(`${c.dim(t)}  ${status} ${tool} ${action} ${dur}${err}\n`);
+      } catch {
+        process.stdout.write(raw + '\n');
+      }
+    };
+
+    const t = tailLogs({ lines, follow: !!opts.follow, onLine: render });
+    if (opts.follow) {
+      process.stdout.write(`${c.dim(`-- following ${currentLogPath()} (Ctrl-C to stop) --`)}\n`);
+      process.on('SIGINT', () => { t.stop(); process.exit(0); });
+      // keep process alive
+      await new Promise(() => {});
+    }
+  });
+
 program.parseAsync(process.argv);

package/src/cli/render.js

@@ -85,6 +85,13 @@ export function renderSyncInstall(result) {
     if (counts[cap] !== undefined) rows.push([cap, counts[cap]]);
   }
   const visibleTotal = Object.values(counts).reduce((a, b) => a + b, 0);
+  // Phase 160 (v1.28): append diff tally row if cli attached one.
+  if (result._tally) {
+    const w = result._tally.written;
+    const s = result._tally.skipped;
+    rows.push(['new / updated', w]);
+    rows.push(['unchanged', s]);
+  }
   return summary({
     title: `Synced kit → ${result.target}${result.dryRun ? ' (dry-run)' : ''}`,
     rows,