@luanpdd/kit-mcp 0.5.0 → 1.1.0

package/CHANGELOG.md

@@ -6,6 +6,99 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-05-03
+
+**Visual feedback in the terminal.** Running `kit ...` now prints colored tables, progress bars, summary panels and interactive selectors instead of the raw JSON-to-stdout default of v1.0. Programmatic consumers add `--json` to restore the previous behavior.
+
+### Added — Phase 6: UI primitives
+- `src/core/ui.js` — single module exposing `c` (color helpers), `icons`, `spinner`, `progress`, `select`, `confirm`, `summary`. Respects `NO_COLOR`, `FORCE_COLOR`, `process.stdout.isTTY`. Animations write to stderr so stdout stays clean for `--json` piping.
+- Deps: `picocolors` (~3KB, zero subdeps) and `@inquirer/prompts` (modular — only `select`+`confirm` imported).
+
+### Added — Phase 7: `--json` flag, default human
+- `--json` global flag preserves v1.0's JSON-to-stdout behavior for programmatic consumers.
+- Without `--json`: every subcommand renders a human-readable table or summary panel via `src/cli/render.js`.
+- `kit get` is unchanged (still raw, cat-like).
+
+### Added — Phase 8: Progress + spinner
+- `syncTo` and `applyReverse` accept an `opts.onProgress({ phase, current, total, label })` callback. Default no-op preserves backward compat.
+- CLI wraps long ops in `withProgress(label, total, fn)` and short ops in `withSpinner(text, fn)`. TTY animates; pipes/CI emit linear status text (`10%, 20%, ...`).
+
+### Added — Phase 9: Interactive selectors + diff confirm
+- `install write [target]` and `sync install [target]` — when target argument is omitted in TTY mode, opens a select prompt listing all 8 IDEs with labels.
+- `install write` always previews the JSON/TOML to be written and asks `Apply these changes? (y/N)` before applying. `--yes` or `--json` bypasses the prompt for CI/programmatic use.
+- In non-TTY mode without target: exits with a helpful message ("pass the value as a flag instead").
+
+### Stable API additions (1.x compatible)
+
+The 1.0 commitment is unchanged. These additions become part of the contract:
+
+- **`--json` global flag.** Behavior locked: JSON-to-stdout, no ANSI codes, no progress on stderr, prompts replaced by descriptive errors.
+- **`onProgress` callback signature** on `syncTo` and `applyReverse`: `({ phase, current, total, label }) => void`. Adding optional fields is non-breaking.
+- **Interactive selectors fall back to errors in non-TTY**, not to defaults — programs MUST pass the target as argument or use `--json`.
+
+### Migration
+
+Programs and scripts that piped `kit ... | jq` need to add `--json` explicitly:
+```bash
+# Before (v1.0):
+kit list-agents | jq '.[].name'
+
+# After (v1.1):
+kit list-agents --json | jq '.[].name'
+```
+
+Interactive shell users get the new visual output automatically — no flags needed.
+
+### Tests
+- `test/unit/ui.test.js` — 6 new tests covering `summary` rendering, `NO_COLOR` honored, icons set.
+- `test/integration/cli-roundtrip.test.js` — 4 new tests covering `--json` opt-in, default human output, selector fallback in non-TTY for `install write` / `sync install`.
+- Total: 49 unit + 9 integration = **58 tests** in ~4s. CI verde 6/6 (Ubuntu/macOS/Windows × Node 20/22).
+
+## [1.0.0] - 2026-05-03
+
+**First stable release.** kit-mcp now commits to backwards compatibility on the surfaces listed under "Stable API" below; breaking changes there require a 2.0.0 bump.
+
+### Added — Phase 1: Tooling debt
+- `.github/dependabot.yml` — weekly grouped npm + github-actions updates.
+- GitHub Release object created for v0.5.0 (was stuck on v0.2.0 "cleanup" as Latest).
+- `.github/workflows/publish.yml` now creates a GitHub Release object automatically on every `v*` tag push, with notes extracted from this CHANGELOG. Closes the gap permanently.
+
+### Fixed — Phase 2: Slash-command parser
+- `src/core/sync.js` — `renderReference` reorders the stub body so the first non-blank line is the H1 + description blockquote, not the `<!-- kit-mcp:reference -->` marker. Strict downstream parsers (notably Claude Desktop's skill listing) now surface the real description.
+- `src/core/kit.js` — `firstNonEmptyLine` skips lines starting with `<!--` as a defensive fallback when the canonical has no frontmatter description.
+- `kit/commands/*` — 8 commands (`adicionar-backlog`, `adicionar-fase`, `adicionar-tarefa`, `concluir-marco`, `definir-perfil`, `depurar`, `fio`, `inserir-fase`) had unquoted angle-bracket `argument-hint` values that strict YAML parsers misinterpreted as flow-style flags. Now consistently quoted.
+
+### Added — Phase 3: Reverse-sync for mirror-tree caps
+- `detectReverse` now walks `.claude/framework/` and `.claude/hooks/` and reports any byte-for-byte difference vs `kit/<source>/<rel>`. The `.kit-mcp-managed` marker is automatically excluded from candidates.
+- `applyReverse` adds `applyMirrorTreeOne` for `framework`/`hooks` candidates: `skip`, `overwrite`, `merge` (degenerates to overwrite — no frontmatter to preserve), `rename` (writes to `kit/<source>/<rel>.from-<tag>.<ext>` preserving the original).
+- `--only framework/<rel>` / `--only hooks/<file>` filters narrow apply to one file.
+- README "kit reverse-sync" section updated with the new examples.
+
+### Added — Phase 4: Test infrastructure
+- `node:test`-based runner — zero dependencies. `test/run.mjs` walks for `*.test.js` files (works on Node 20+ where `--test` glob support is partial).
+- 37 unit tests across `kit`, `sync`, `reverse-sync`, `gates`, `gate-runner`, `registry`.
+- 5 integration tests spawning `bin/cli.js` end-to-end (incl. MCP server boot smoke).
+- `test/fixtures/sample-kit/` minimal fixture (1 of each kind + framework template + hook + frontmatter-less command for fallback test).
+- CI runs `npm test` + `npm run test:integration` before existing smoke + MCP boot, on Ubuntu / macOS / Windows × Node 20 / 22 (6/6 combinations).
+- `package.json` scripts: `test`, `test:integration`, `test:all`.
+
+### Stable API (commitments locked at 1.0.0)
+
+The following surfaces are covered by SemVer — breaking changes require a 2.0.0 release:
+
+- **`src/core/registry.js` TARGETS table format.** Adding capabilities, IDEs, or new modes is non-breaking. Renaming or removing existing capability keys (`rules`, `agents`, `commands`, `skills`, `framework`, `hooks`, `mcpConfig`) is breaking.
+- **MCP tool action signatures.** Tool names (`kit`, `sync`, `reverse-sync`, `gates`, `forensics`, `install`) and their action-dispatch contracts are stable. New actions are non-breaking; renaming or removing existing actions is breaking.
+- **CLI subcommand surface.** Top-level commands (`kit`, `sync`, `reverse-sync`, `gates`, `forensics`, `install`) and their action sub-commands are stable. New flags are non-breaking; renaming or removing existing ones is breaking.
+- **`src/core/*.js` named exports.** Functions consumed programmatically (`listKit`, `searchKit`, `findItem`, `resolveKitRoot`, `BUNDLED_KIT_ROOT`, `syncTo`, `statusOf`, `removeFrom`, `detectReverse`, `applyReverse`, `listGates`, `getGate`, `gatesForStage`, `runGate`, `listTargets`, `getTarget`, `TARGETS`) keep their signatures. Adding new exports is non-breaking; signature changes are breaking.
+- **Stub format.** Files written by sync `--mode reference` keep the `<!-- kit-mcp:reference -->` marker somewhere in the body so `sync remove` and `reverse-sync detect` continue to identify them. Position within the body may change; presence is the contract.
+- **`.kit-mcp-managed` marker semantics.** Mirror-tree directories (`framework/`, `hooks/`) are managed only when the marker is present at the root. Without it, `sync remove` never deletes the tree.
+
+### Migration
+
+No code changes required for users on 0.5.0 — `npm install @luanpdd/kit-mcp@latest` brings in 1.0.0 with the same behavior plus the parser fixes, reverse-sync expansions, and test coverage.
+
+If you were on 0.4.0 (deprecated) or earlier, upgrade to skip the import-time crash and missing-framework regression entirely.
+
 ## [0.5.0] - 2026-05-03
 
 ### Added
@@ -174,7 +267,9 @@ npx -y @luanpdd/kit-mcp sync install claude-code --project-root .
 - CLI mirror of all MCP tools.
 - `install` command that registers kit-mcp into an IDE's MCP config (JSON for Claude/Cursor/Gemini/Windsurf, TOML for Codex).
 
-[Unreleased]: https://github.com/luanpdd/kit-mcp/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/luanpdd/kit-mcp/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/luanpdd/kit-mcp/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/luanpdd/kit-mcp/compare/v0.5.0...v1.0.0
 [0.5.0]: https://github.com/luanpdd/kit-mcp/compare/v0.4.1...v0.5.0
 [0.4.1]: https://github.com/luanpdd/kit-mcp/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/luanpdd/kit-mcp/compare/v0.3.0...v0.4.0

package/README.md

@@ -55,7 +55,7 @@ kit-mcp/
 └── README.md                   ← you are here
 ```
 
-**Lines of source code:** ~1100. **Runtime dependencies:** 3 (`@modelcontextprotocol/sdk`, `commander`, `chokidar`). **Build step:** none — plain ESM Node.js 20+.
+**Lines of source code:** ~1300. **Runtime dependencies:** 5 (`@modelcontextprotocol/sdk`, `commander`, `chokidar`, `picocolors`, `@inquirer/prompts`). **Build step:** none — plain ESM Node.js 20+.
 
 ### About the bundled workflow
 
@@ -128,7 +128,17 @@ For other IDEs, swap `claude-code` for `cursor`, `codex`, `gemini-cli`, `windsur
 
 ## CLI reference
 
-The CLI mirrors the MCP tools 1:1. Output is always JSON to stdout. The global `--kit-root` flag overrides the kit source for any subcommand.
+The CLI mirrors the MCP tools 1:1. **By default the CLI prints colored, human-readable tables and summary panels.** Add `--json` to restore raw JSON-to-stdout (machine-readable, the default in v1.0). The global `--kit-root` flag overrides the kit source for any subcommand.
+
+```bash
+kit list-agents              # human: colored table, name + description
+kit list-agents --json       # machine: JSON array
+
+kit sync install claude-code # human: progress bar + summary panel
+kit sync install claude-code --json  # machine: full result object
+```
+
+In non-TTY mode (pipes, CI), animations degrade to linear status lines automatically. `NO_COLOR=1` disables colors entirely; `FORCE_COLOR=1` forces them on even in pipes.
 
 ### `kit kit ...` — browse the kit
 
@@ -182,8 +192,12 @@ kit install dry-run claude-code --scope user --via npx        # preview the JSON
 kit install write claude-code   --scope user --via npx        # portable: uses `npx @luanpdd/kit-mcp`
 kit install write claude-code   --scope project --via local   # local clone: uses ./bin/mcp.js absolute path
 kit install write claude-code   --scope user --via global     # assumes `npm install -g @luanpdd/kit-mcp`
+kit install write                                             # no target: opens an interactive selector (TTY)
+kit install write claude-code --yes                           # CI: skip the confirm prompt
 ```
 
+Since v1.1, `install write` always **previews** the JSON/TOML it's about to write and asks you to confirm. Pass `--yes` (CI mode) or `--json` to bypass the prompt. Without a target argument in TTY mode, you get an arrow-key selector listing all 8 IDEs.
+
 `--via` decides how the IDE will invoke the server:
 
 | Mode | Command in IDE config | When to use |
@@ -194,16 +208,19 @@ kit install write claude-code   --scope user --via global     # assumes `npm ins
 
 ### `kit reverse-sync ...` — bring IDE edits back to the canonical kit
 
-If you edited an agent/command/skill **directly inside the IDE's folder** (`.claude/agents/foo.md`, `.cursor/agents/bar.md`, …) instead of in your kit, this brings those edits back so the canonical absorbs them.
+If you edited an agent/command/skill/framework/hook **directly inside the IDE's folder** (`.claude/agents/foo.md`, `.claude/framework/workflows/bar.md`, `.claude/hooks/baz.js`, …) instead of in your kit, this brings those edits back so the canonical absorbs them.
 
 ```bash
 kit reverse-sync detect claude-code --project-root .
 kit reverse-sync apply  claude-code --project-root . --strategy merge --dry-run
 kit reverse-sync apply  claude-code --project-root . --strategy merge
 kit reverse-sync apply  claude-code --project-root . --strategy overwrite --only agent/foo
+kit reverse-sync apply  claude-code --project-root . --strategy overwrite --only framework/workflows/new-milestone.md
 ```
 
-**Strategies:** `skip` (list-only), `merge` (canonical frontmatter + edited body), `overwrite`, `rename` (preserve both as `-from-{ide}.md`).
+**Strategies:** `skip` (list-only), `merge` (canonical frontmatter + edited body — for agents/commands/skills), `overwrite`, `rename` (preserve both as `-from-{ide}.md`).
+
+**Mirror-tree caps (`framework`, `hooks`):** files have no frontmatter, so `merge` degenerates to `overwrite` (with a note). The `.kit-mcp-managed` marker is automatically excluded from candidates. Filter individual files with `--only framework/<rel>` or `--only hooks/<file>`.
 
 ### `kit gates ...` — reusable workflow gates
 
@@ -469,16 +486,27 @@ PRs welcome.
 
 ---
 
-## Smoke tests
+## Tests
+
+Built on `node:test` (zero dependencies). Two suites:
+
+```bash
+npm test                # unit — kit parser, sync (all modes), reverse-sync, gates, registry
+npm run test:integration  # integration — spawns bin/cli.js end-to-end on a temp project
+npm run test:all          # both
+```
+
+Plus the original quick smokes:
 
 ```bash
 node bin/cli.js kit list-agents | head -5         # 19 bundled agents
 node bin/cli.js sync targets                      # 8 IDEs
 node bin/cli.js gates list                        # 5 gates
 node bin/cli.js install dry-run claude-code --via npx
-node bin/mcp.js < /dev/null & sleep 1; kill %1    # MCP server boots and waits on stdio
 ```
 
+CI runs unit + integration + smoke + MCP boot on Ubuntu / macOS / Windows × Node 20 / 22 on every push and PR.
+
 ---
 
 ## License

package/kit/commands/adicionar-backlog.md

@@ -1,7 +1,7 @@
 ---
 name: adicionar-backlog
 description: Adiciona uma ideia ao estacionamento de backlog (numeração 999.x)
-argument-hint: <description>
+argument-hint: "<description>"
 allowed-tools:
   - Read
   - Write

package/kit/commands/adicionar-fase.md

@@ -1,7 +1,7 @@
 ---
 name: adicionar-fase
 description: Adiciona fase ao final do milestone atual no roadmap
-argument-hint: <description>
+argument-hint: "<description>"
 allowed-tools:
   - Read
   - Write

package/kit/commands/adicionar-tarefa.md

@@ -1,7 +1,7 @@
 ---
 name: adicionar-tarefa
 description: Captura ideia ou tarefa como todo a partir do contexto da conversa atual
-argument-hint: [descrição opcional]
+argument-hint: "[descrição opcional]"
 allowed-tools:
   - Read
   - Write

package/kit/commands/concluir-marco.md

@@ -2,7 +2,7 @@
 type: prompt
 name: concluir-marco
 description: Arquiva milestone concluído e prepara para próxima versão
-argument-hint: <version>
+argument-hint: "<version>"
 allowed-tools:
   - Read
   - Write

package/kit/commands/definir-perfil.md

@@ -1,7 +1,7 @@
 ---
 name: definir-perfil
 description: Altera o perfil de modelo para os agentes framework (quality/balanced/budget/inherit)
-argument-hint: <perfil (quality|balanced|budget|inherit)>
+argument-hint: "<perfil (quality|balanced|budget|inherit)>"
 model: haiku
 allowed-tools:
   - Bash

package/kit/commands/depurar.md

@@ -1,7 +1,7 @@
 ---
 name: depurar
 description: Depuração sistemática com estado persistente entre resets de contexto
-argument-hint: [descrição do problema]
+argument-hint: "[descrição do problema]"
 allowed-tools:
   - Read
   - Bash

package/kit/commands/fio.md

@@ -1,7 +1,7 @@
 ---
 name: fio
 description: Gerencia threads de contexto persistentes para trabalho entre sessões
-argument-hint: [nome | descrição]
+argument-hint: "[nome | descrição]"
 allowed-tools:
   - Read
   - Write

package/kit/commands/inserir-fase.md

@@ -1,7 +1,7 @@
 ---
 name: inserir-fase
 description: Insere trabalho urgente como fase decimal (ex: 72.1) entre fases existentes
-argument-hint: <after> <description>
+argument-hint: "<after> <description>"
 allowed-tools:
   - Read
   - Write

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luanpdd/kit-mcp",
-  "version": "0.5.0",
+  "version": "1.1.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": {
@@ -41,11 +41,16 @@
   "scripts": {
     "start": "node bin/mcp.js",
     "cli": "node bin/cli.js",
-    "smoke": "node bin/cli.js kit list-agents | head -5"
+    "smoke": "node bin/cli.js kit list-agents | head -5",
+    "test": "node test/run.mjs test/unit",
+    "test:integration": "node test/run.mjs test/integration",
+    "test:all": "node test/run.mjs test"
   },
   "dependencies": {
+    "@inquirer/prompts": "^8.4.2",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "chokidar": "^5.0.0",
-    "commander": "^12.1.0"
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1"
   }
 }

package/src/cli/index.js

@@ -7,6 +7,10 @@
 //   kit gates list
 //   kit forensics collect --project-root /path/to/project
 //   kit install dry-run claude-code
+//
+// Default output: human-readable colored panels + summaries.
+// `--json` flag (global) restores the v1.0 JSON-to-stdout behavior for
+// programmatic consumers.
 
 import { Command } from 'commander';
 import { listKit, searchKit, findItem } from '../core/kit.js';
@@ -20,49 +24,122 @@ 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 * as render from './render.js';
+import { c, icons, spinner, progress, select, confirm } from '../core/ui.js';
 
 const program = new Command()
   .name('kit')
   .description('Personal kit (agents/commands/skills) — CLI mirror of the kit-mcp server.')
-  .version('0.2.0')
-  .option('--kit-root <path>', 'Override the kit root (default: bundled example kit, or KIT_MCP_KIT_ROOT env)');
+  .version('1.0.0')
+  .option('--kit-root <path>', 'Override the kit root (default: bundled example kit, or KIT_MCP_KIT_ROOT env)')
+  .option('--json', 'Output JSON to stdout (machine-readable, restores pre-1.1 default)');
 
-// Apply --kit-root globally by setting the env so all helpers pick it up.
 program.hook('preAction', (thisCommand, actionCommand) => {
   const opts = program.opts();
   if (opts.kitRoot) process.env.KIT_MCP_KIT_ROOT = opts.kitRoot;
 });
 
+// `out(value, humanRenderer)` — uses the human renderer unless --json is set.
+function out(value, humanRenderer) {
+  const opts = program.opts();
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(value, null, 2) + '\n');
+  } else if (typeof humanRenderer === 'function') {
+    process.stdout.write(humanRenderer(value));
+  } else {
+    process.stdout.write(render.renderFallback(value));
+  }
+}
+
+// withSpinner wraps a short opaque op with a spinner; auto-disabled in --json mode.
+async function withSpinner(text, fn) {
+  const opts = program.opts();
+  if (opts.json) return fn();
+  const sp = spinner({ text });
+  try {
+    const r = await fn();
+    sp.succeed();
+    return r;
+  } catch (e) {
+    sp.fail(e.message);
+    throw e;
+  }
+}
+
+// withProgress wraps a long op; passes onProgress callback to the core fn.
+async function withProgress(label, total, fn) {
+  const opts = program.opts();
+  if (opts.json) return fn(() => {});
+  const p = progress({ total, label });
+  let last = '';
+  const onProgress = ({ current, label }) => { last = label || last; p.tick({ label: last }); };
+  try {
+    const r = await fn(onProgress);
+    p.finish(label);
+    return r;
+  } catch (e) {
+    p.finish();
+    throw e;
+  }
+}
+
+function fail(msg) {
+  process.stderr.write(`${c.red(icons.cross)} ${msg}\n`);
+  process.exit(1);
+}
+
+function slim(x) {
+  return { kind: x.kind, name: x.name, description: x.description, absPath: x.absPath };
+}
+
 // --- kit ---
 const kit = program.command('kit').description('Browse the canonical kit.');
-kit.command('list-agents').action(async () => print((await listKit()).agents.map(slim)));
-kit.command('list-commands').action(async () => print((await listKit()).commands.map(slim)));
+kit.command('list-agents').action(async () => {
+  const k = await withSpinner('Loading kit...', () => listKit());
+  out(k.agents.map(slim), v => render.renderKitList(v, 'agent'));
+});
+kit.command('list-commands').action(async () => {
+  const k = await withSpinner('Loading kit...', () => listKit());
+  out(k.commands.map(slim), v => render.renderKitList(v, 'command'));
+});
 kit.command('list-skills').action(async () => {
-  const k = await listKit();
-  print([...k.skills, ...k.skillsExtras].map(slim));
+  const k = await withSpinner('Loading kit...', () => listKit());
+  out([...k.skills, ...k.skillsExtras].map(slim), v => render.renderKitList(v, 'skill'));
 });
 kit.command('get <kind> <name>').action(async (kind, name) => {
   const k = await listKit();
   const item = findItem(k, kind, name);
   if (!item) return fail(`Not found: ${kind}/${name}`);
+  // Always raw for `kit get` — it's intended to be cat-like
   process.stdout.write(item.content ?? item.skillContent);
 });
-kit.command('search <query>').action(async (q) => print(searchKit(await listKit(), q)));
+kit.command('search <query>').action(async (q) => out(searchKit(await listKit(), q), render.renderKitSearch));
 
 // --- sync ---
 const sync = program.command('sync').description('Project the kit into an IDE.');
-sync.command('targets').action(async () => print(listTargets()));
+sync.command('targets').action(async () => {
+  const targets = await withSpinner('Loading capability matrix...', async () => listTargets());
+  out(targets, render.renderSyncTargets);
+});
 sync.command('status <target>')
   .option('--project-root <path>')
-  .action(async (target, opts) => print(await statusOf(target, { projectRoot: opts.projectRoot })));
-sync.command('install <target>')
+  .action(async (target, opts) => out(await statusOf(target, { projectRoot: opts.projectRoot }), render.renderSyncStatus));
+sync.command('install [target]')
   .option('--project-root <path>')
   .option('--mode <mode>', 'reference | copy', 'reference')
   .option('--dry-run')
-  .action(async (target, opts) => print(await syncTo(target, { projectRoot: opts.projectRoot, mode: opts.mode, dryRun: opts.dryRun })));
+  .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 }),
+    );
+    out(result, render.renderSyncInstall);
+  });
 sync.command('remove <target>')
   .option('--project-root <path>')
-  .action(async (target, opts) => print(await removeFrom(target, { projectRoot: opts.projectRoot })));
+  .action(async (target, opts) => out(await removeFrom(target, { projectRoot: opts.projectRoot }), render.renderSyncRemove));
 sync.command('watch [targets...]')
   .description('Watch kit/ and re-sync to one or more IDEs on every change. Use --all to pick up every IDE that already has files in the project.')
   .option('--project-root <path>')
@@ -93,50 +170,57 @@ sync.command('watch [targets...]')
 const reverse = program.command('reverse-sync').description('Detect and apply edits made directly in an IDE back to the canonical kit/.');
 reverse.command('detect <target>')
   .option('--project-root <path>')
-  .action(async (target, opts) => print(await detectReverse(target, { projectRoot: opts.projectRoot })));
+  .action(async (target, opts) => out(await detectReverse(target, { projectRoot: opts.projectRoot }), render.renderReverseDetect));
 reverse.command('apply <target>')
   .option('--project-root <path>')
   .option('--strategy <s>', 'skip | overwrite | merge | rename', 'skip')
-  .option('--only <items...>', 'Limit to these kind/name pairs (e.g. agent/planner skill/paperclip)')
+  .option('--only <items...>', 'Limit to these kind/name pairs (e.g. agent/planner skill/paperclip framework/workflows/foo.md)')
   .option('--dry-run')
-  .action(async (target, opts) => print(await applyReverse(target, { projectRoot: opts.projectRoot, strategy: opts.strategy, only: opts.only, dryRun: opts.dryRun })));
+  .action(async (target, opts) => {
+    const result = await withProgress(
+      `Applying reverse-sync (${opts.strategy})`,
+      50,
+      (onProgress) => applyReverse(target, { projectRoot: opts.projectRoot, strategy: opts.strategy, only: opts.only, dryRun: opts.dryRun, onProgress }),
+    );
+    out(result, render.renderReverseApply);
+  });
 
 // --- gates ---
 const gates = program.command('gates').description('Reusable workflow gates.');
-gates.command('list').action(async () => print(await listGates()));
+gates.command('list').action(async () => out(await listGates(), render.renderGatesList));
 gates.command('get <id>').action(async (id) => process.stdout.write((await getGate(id)).content));
-gates.command('for-stage <stage>').action(async (stage) => print(await gatesForStage(stage)));
+gates.command('for-stage <stage>').action(async (stage) => out(await gatesForStage(stage), render.renderGatesList));
 gates.command('run <id>')
   .description('Execute a gate (with confirmation in interactive mode). Returns a structured verdict.')
   .option('--project-root <path>')
   .option('--yes', 'Skip confirmation (CI/non-interactive)')
   .option('--no-interactive', 'Never prompt; manual gates return verdict=manual')
-  .action(async (id, opts) => print(await runGate(id, {
+  .action(async (id, opts) => out(await runGate(id, {
     projectRoot: opts.projectRoot,
     yes: opts.yes,
     interactive: opts.interactive !== false,
-  })));
+  }), render.renderGateRun));
 
 // --- forensics ---
 const forensics = program.command('forensics').description('Failure dataset & replays.');
 forensics.command('collect')
   .option('--project-root <path>')
-  .action(async (opts) => print(await collectFailures({ projectRoot: opts.projectRoot })));
+  .action(async (opts) => out(await collectFailures({ projectRoot: opts.projectRoot }), render.renderForensicsCollect));
 forensics.command('summarize')
   .option('--project-root <path>')
   .action(async (opts) => {
     const f = await collectFailures({ projectRoot: opts.projectRoot });
-    print(await summarizeByAgent(f));
+    out(await summarizeByAgent(f), render.renderForensicsSummarize);
   });
 forensics.command('write-learnings')
   .option('--project-root <path>')
   .action(async (opts) => {
     const f = await collectFailures({ projectRoot: opts.projectRoot });
-    print(await writeLearnings(f, { projectRoot: opts.projectRoot }));
+    out(await writeLearnings(f, { projectRoot: opts.projectRoot }), render.renderFallback);
   });
 forensics.command('list-replays')
   .option('--project-root <path>')
-  .action(async (opts) => print(await listReplays({ projectRoot: opts.projectRoot })));
+  .action(async (opts) => out(await listReplays({ projectRoot: opts.projectRoot }), render.renderListReplays));
 forensics.command('reflect')
   .description('LLM-pass: read learnings + current agent, propose minimal prompt edits, optionally apply.')
   .requiredOption('--agent <name>', 'Agent name (matches kit/agents/<name>.md)')
@@ -144,39 +228,90 @@ forensics.command('reflect')
   .option('--dry-run', 'Save the assembled prompt without calling the LLM')
   .option('--apply', 'Skip confirmation; apply the proposal directly')
   .option('--no-interactive', 'Save proposal but never prompt to apply')
-  .action(async (opts) => print(await reflect({
+  .action(async (opts) => out(await reflect({
     agent: opts.agent,
     projectRoot: opts.projectRoot,
     dryRun: opts.dryRun,
     apply: opts.apply,
     interactive: opts.interactive !== false,
-  })));
+  }), render.renderFallback));
 forensics.command('load-replay <id>')
   .option('--project-root <path>')
-  .action(async (id, opts) => print(await loadReplay(id, { projectRoot: opts.projectRoot })));
+  .action(async (id, opts) => out(await loadReplay(id, { projectRoot: opts.projectRoot }), render.renderFallback));
 
 // --- install (the MCP server itself into an IDE) ---
 const install = program.command('install').description('Register kit-mcp into an IDE\'s MCP config.');
-install.command('targets').action(async () => print(listInstallTargets()));
+install.command('targets').action(async () => out(listInstallTargets(), render.renderInstallTargets));
 install.command('dry-run <target>')
   .option('--scope <scope>', 'user | project', 'user')
   .option('--name <name>', 'Server name in IDE config', 'kit')
   .option('--via <via>', 'local | npx | global  (how the IDE will invoke the server)', 'local')
   .option('--pkg <name>', 'npm package name (only with --via npx)', '@luanpdd/kit-mcp')
   .option('--project-root <path>')
-  .action(async (target, opts) => print(await installMcp(target, { ...opts, dryRun: true })));
-install.command('write <target>')
+  .action(async (target, opts) => out(await installMcp(target, { ...opts, dryRun: true }), render.renderInstallResult));
+install.command('write [target]')
   .option('--scope <scope>', 'user | project', 'user')
   .option('--name <name>', 'Server name in IDE config', 'kit')
   .option('--via <via>', 'local | npx | global', 'local')
   .option('--pkg <name>', 'npm package name (only with --via npx)', '@luanpdd/kit-mcp')
   .option('--force')
   .option('--project-root <path>')
-  .action(async (target, opts) => print(await installMcp(target, opts)));
+  .option('--yes', 'Skip confirmation prompt (CI mode)')
+  .action(async (target, opts) => {
+    const globalOpts = program.opts();
+    if (!target) target = await pickTarget(listInstallTargets(), 'Where do you want to register kit-mcp?');
+
+    // Preview first (dry-run)
+    const preview = await installMcp(target, { ...opts, dryRun: true });
+    if (!preview.ok) {
+      out(preview, render.renderInstallResult);
+      process.exit(1);
+    }
+
+    // Show the preview unless --json
+    if (!globalOpts.json) {
+      process.stdout.write(`\n${c.bold('Preview:')} ${c.dim(preview.configPath)}\n\n`);
+      if (preview.preview) {
+        process.stdout.write(c.dim(JSON.stringify(preview.preview, null, 2)) + '\n');
+      } else if (preview.snippet) {
+        process.stdout.write(c.dim(preview.snippet) + '\n');
+      }
+    }
+
+    // Confirm unless --yes or --json (programmatic consumers must pass --yes)
+    if (!opts.yes && !globalOpts.json) {
+      let proceed;
+      try {
+        proceed = await confirm({ message: 'Apply these changes?', default: false });
+      } catch (e) {
+        return fail(`${e.message} (use --yes to skip)`);
+      }
+      if (!proceed) {
+        process.stdout.write(`${c.yellow(icons.warn)} Aborted by user.\n`);
+        process.exit(0);
+      }
+    }
 
-// --- helpers ---
-function print(x) { process.stdout.write(JSON.stringify(x, null, 2) + '\n'); }
-function fail(msg) { process.stderr.write(msg + '\n'); process.exit(1); }
-function slim(x) { return { kind: x.kind, name: x.name, description: x.description, absPath: x.absPath }; }
+    out(await installMcp(target, opts), render.renderInstallResult);
+  });
+
+// pickTarget — interactive selector for IDE targets, falls back to error in non-TTY/--json
+async function pickTarget(targets, message) {
+  const globalOpts = program.opts();
+  if (globalOpts.json) {
+    return fail('--target is required when using --json mode');
+  }
+  try {
+    return await select({
+      message,
+      choices: targets.map(t => ({
+        name: `${t.label.padEnd(22)} ${c.dim(`(${t.id})`)}`,
+        value: t.id,
+      })),
+    });
+  } catch (e) {
+    return fail(`${e.message} (or pass <target> as argument)`);
+  }
+}
 
 program.parseAsync(process.argv);

package/src/cli/render.js

@@ -0,0 +1,187 @@
+// Human-readable renderers for each CLI subcommand. The CLI default switched
+// from JSON-to-stdout to these in v1.1; --json restores the old behavior
+// (still useful for piping to jq, MCP-like consumers, etc.).
+//
+// Conventions:
+//   - Render functions write to process.stdout (no trailing newline beyond
+//     what the formatted output naturally has).
+//   - They never throw on missing fields — the result objects come from
+//     core/ which already shape them.
+//   - Cores happen via src/core/ui.js (which already disables in NO_COLOR
+//     or when --no-tty etc.).
+
+import path from 'node:path';
+import { c, icons, summary } from '../core/ui.js';
+
+// --- generic helpers ---
+
+function table(rows, headers) {
+  if (rows.length === 0) {
+    return `${c.dim('(empty)')}\n`;
+  }
+  const cols = headers.length;
+  const widths = new Array(cols).fill(0);
+  for (let i = 0; i < cols; i++) widths[i] = Math.max(headers[i].length, ...rows.map(r => String(r[i] ?? '').length));
+  const out = [];
+  out.push(headers.map((h, i) => c.bold(h.padEnd(widths[i]))).join('  '));
+  out.push(headers.map((_, i) => c.dim('─'.repeat(widths[i]))).join('  '));
+  for (const r of rows) {
+    out.push(r.map((v, i) => String(v ?? '').padEnd(widths[i])).join('  '));
+  }
+  return out.join('\n') + '\n';
+}
+
+// --- kit ---
+
+export function renderKitList(items, kind) {
+  if (items.length === 0) {
+    return `${c.dim(`No ${kind}s in kit.`)}\n`;
+  }
+  const rows = items.map(x => [x.name, (x.description ?? '').slice(0, 80)]);
+  return table(rows, ['name', 'description']);
+}
+
+export function renderKitSearch(results) {
+  if (results.length === 0) {
+    return `${c.dim('No matches.')}\n`;
+  }
+  const rows = results.map(x => [x.kind, x.name, (x.description ?? '').slice(0, 70)]);
+  return table(rows, ['kind', 'name', 'description']);
+}
+
+// --- sync ---
+
+export function renderSyncTargets(targets) {
+  const rows = targets.map(t => [
+    t.id,
+    t.label,
+    Object.entries(t.capabilities).filter(([, v]) => v).map(([k]) => k).join(', '),
+  ]);
+  return table(rows, ['id', 'label', 'capabilities']);
+}
+
+export function renderSyncStatus(result) {
+  const rows = result.checks.map(c => [c.capability, c.path, c.exists ? '✓' : '—']);
+  return `${c.bold(`Status: ${result.target}`)}  ${c.dim(result.projectRoot)}\n` + table(rows, ['cap', 'path', 'present']);
+}
+
+export function renderSyncInstall(result) {
+  // Tally written paths by capability prefix
+  const counts = {};
+  for (const p of result.written) {
+    const rel = path.relative(result.projectRoot, p).replace(/\\/g, '/');
+    // Hide internal markers from the user-facing tally (they're a kit-mcp impl detail)
+    if (rel.endsWith('/.kit-mcp-managed')) continue;
+    let cap = 'rules';
+    if (rel.includes('.claude/agents/'))    cap = 'agents';
+    else if (rel.includes('.claude/commands/'))  cap = 'commands';
+    else if (rel.includes('.claude/skills/'))    cap = 'skills';
+    else if (rel.includes('.claude/framework/')) cap = 'framework';
+    else if (rel.includes('.claude/hooks/'))     cap = 'hooks';
+    counts[cap] = (counts[cap] ?? 0) + 1;
+  }
+  const rows = [];
+  for (const cap of ['rules', 'agents', 'commands', 'skills', 'framework', 'hooks']) {
+    if (counts[cap] !== undefined) rows.push([cap, counts[cap]]);
+  }
+  const visibleTotal = Object.values(counts).reduce((a, b) => a + b, 0);
+  return summary({
+    title: `Synced kit → ${result.target}${result.dryRun ? ' (dry-run)' : ''}`,
+    rows,
+    total: visibleTotal,
+    hint: c.dim(result.projectRoot),
+  }) + '\n';
+}
+
+export function renderSyncRemove(result) {
+  return summary({
+    title: `Removed kit-mcp stubs from ${result.target}`,
+    rows: [['Files removed', result.removed.length]],
+    total: result.removed.length,
+    hint: c.dim(result.projectRoot),
+  }) + '\n';
+}
+
+// --- reverse-sync ---
+
+export function renderReverseDetect(result) {
+  if (result.candidates.length === 0) {
+    return `${c.green(icons.check)} No edits to bring back. Canonical kit and ${result.target} are in sync.\n`;
+  }
+  const rows = result.candidates.map(x => [x.kind, x.name, x.reason, x.diffSummary ?? '']);
+  return `${c.bold(`Candidates: ${result.candidates.length}`)}  ${c.dim(`(${result.target})`)}\n` +
+    table(rows, ['kind', 'name', 'reason', 'diff']);
+}
+
+export function renderReverseApply(result) {
+  const rows = result.results.map(x => [
+    x.kind,
+    x.name,
+    x.action.startsWith('overwrit') || x.action.startsWith('merge') || x.action.startsWith('renamed')
+      ? c.green(x.action)
+      : x.action.startsWith('skipped') ? c.dim(x.action) : c.yellow(x.action),
+  ]);
+  return `${c.bold(`Applied (strategy=${result.strategy})`)}\n` + table(rows, ['kind', 'name', 'action']);
+}
+
+// --- gates ---
+
+export function renderGatesList(items) {
+  const rows = items.map(g => [g.id, g.stage, g.blocking ? c.red('blocking') : c.dim('warn-only'), g.description]);
+  return table(rows, ['id', 'stage', 'mode', 'description']);
+}
+
+export function renderGateRun(result) {
+  const verdictColor = result.verdict === 'passed' ? c.green
+                     : result.verdict === 'block'  ? c.red
+                     : result.verdict === 'warn'   ? c.yellow
+                     : c.dim;
+  return `${c.bold(`Gate ${result.id}`)}: ${verdictColor(result.verdict)} ${result.exitCode !== undefined ? c.dim(`(exit ${result.exitCode})`) : ''}\n`;
+}
+
+// --- forensics ---
+
+export function renderForensicsCollect(items) {
+  if (items.length === 0) return `${c.dim('No failures collected.')}\n`;
+  const rows = items.map(x => [x.agent ?? '?', x.kind ?? '?', x.absPath ?? x.path ?? '']);
+  return table(rows, ['agent', 'kind', 'path']);
+}
+
+export function renderForensicsSummarize(byAgent) {
+  const entries = Object.entries(byAgent ?? {});
+  if (entries.length === 0) return `${c.dim('No failures.')}\n`;
+  const rows = entries.map(([agent, items]) => [agent, Array.isArray(items) ? items.length : '?']);
+  return table(rows, ['agent', 'failures']);
+}
+
+export function renderListReplays(items) {
+  if (!Array.isArray(items) || items.length === 0) return `${c.dim('No replays recorded.')}\n`;
+  const rows = items.map(r => [r.id ?? '?', r.agent ?? '?', r.timestamp ?? '?']);
+  return table(rows, ['id', 'agent', 'recorded']);
+}
+
+// --- install ---
+
+export function renderInstallTargets(targets) {
+  const rows = targets.map(t => [t.id, t.label, t.scopes?.join(', ') ?? '?']);
+  return table(rows, ['id', 'label', 'scopes']);
+}
+
+export function renderInstallResult(result) {
+  return summary({
+    title: result.dryRun ? `Install preview (${result.target}, scope=${result.scope})` : `Registered kit-mcp → ${result.target} (scope=${result.scope})`,
+    rows: [
+      ['Path',  result.path ?? '?'],
+      ['Name',  result.name ?? 'kit'],
+      ['Via',   result.via ?? '?'],
+    ].map(([k, v]) => [k, v ?? '—']),
+    hint: result.dryRun ? c.dim('No file written (dry-run)') : undefined,
+  }) + '\n';
+}
+
+// --- generic fallback ---
+
+export function renderFallback(value) {
+  // Used when we don't have a custom renderer yet.
+  return JSON.stringify(value, null, 2) + '\n';
+}

package/src/core/kit.js

@@ -135,7 +135,10 @@ function parseLooseYaml(text) {
 function firstNonEmptyLine(body) {
   for (const line of body.split(/\r?\n/)) {
     const t = line.trim();
-    if (t && !t.startsWith('#')) return t.slice(0, 200);
+    if (!t) continue;                      // blank
+    if (t.startsWith('#')) continue;       // markdown heading
+    if (t.startsWith('<!--')) continue;    // HTML comment (e.g. STUB_MARKER)
+    return t.slice(0, 200);
   }
   return '';
 }

package/src/core/reverse-sync.js

@@ -35,6 +35,11 @@ export async function detectReverse(targetId, opts = {}) {
   if (target.agents)   await scanCapability(candidates, 'agent',   target.agents,   projectRoot, kit.agents,   kitRoot);
   if (target.commands) await scanCapability(candidates, 'command', target.commands, projectRoot, kit.commands, kitRoot);
   if (target.skills)   await scanSkills    (candidates,            target.skills,   projectRoot, [...kit.skills, ...kit.skillsExtras], kitRoot);
+  for (const cap of ['framework', 'hooks']) {
+    const spec = target[cap];
+    if (!spec || spec.mode !== 'mirror-tree') continue;
+    await scanMirrorTree(candidates, cap, spec, projectRoot, kitRoot);
+  }
 
   return { target: targetId, projectRoot, kitRoot, candidates };
 }
@@ -117,21 +122,70 @@ async function scanSkills(candidates, capCfg, projectRoot, kitSkills, kitRoot) {
   }
 }
 
+async function scanMirrorTree(candidates, cap, spec, projectRoot, kitRoot) {
+  const dstRoot = path.join(projectRoot, spec.path);
+  const srcRoot = path.join(kitRoot, spec.source);
+  const files = await walkRel(dstRoot);
+  for (const rel of files) {
+    if (rel === '.kit-mcp-managed' || path.basename(rel) === '.kit-mcp-managed') continue;
+    const dstPath = path.join(dstRoot, rel);
+    const srcPath = path.join(srcRoot, rel);
+    let dstBuf, srcBuf;
+    try { dstBuf = await fs.readFile(dstPath); } catch { continue; }
+    try { srcBuf = await fs.readFile(srcPath); } catch { srcBuf = null; }
+    if (!srcBuf) {
+      candidates.push({
+        kind: cap, name: rel, target: spec.path, destPath: dstPath, kitPath: srcPath,
+        reason: 'new-in-ide',
+        diffSummary: `+${dstBuf.length} bytes (no kit source)`,
+      });
+      continue;
+    }
+    if (dstBuf.equals(srcBuf)) continue;
+    candidates.push({
+      kind: cap, name: rel, target: spec.path, destPath: dstPath, kitPath: srcPath,
+      reason: 'modified-in-ide',
+      diffSummary: `${dstBuf.length} bytes vs ${srcBuf.length} canonical (${dstBuf.length - srcBuf.length >= 0 ? '+' : ''}${dstBuf.length - srcBuf.length})`,
+    });
+  }
+}
+
+async function walkRel(root) {
+  const out = [];
+  async function visit(current, prefix) {
+    let entries;
+    try { entries = await fs.readdir(current, { withFileTypes: true }); }
+    catch { return; }
+    for (const e of entries) {
+      const abs = path.join(current, e.name);
+      const rel = prefix ? `${prefix}/${e.name}` : e.name;
+      if (e.isDirectory()) await visit(abs, rel);
+      else if (e.isFile()) out.push(rel);
+    }
+  }
+  await visit(root, '');
+  return out;
+}
+
 // --- apply ---
 
 export async function applyReverse(targetId, opts = {}) {
   const strategy = opts.strategy ?? 'skip';
+  const onProgress = opts.onProgress ?? (() => {});
   const { candidates } = await detectReverse(targetId, opts);
   const results = [];
 
-  for (const c of candidates) {
+  for (let i = 0; i < candidates.length; i++) {
+    const c = candidates[i];
     if (opts.only && !opts.only.includes(`${c.kind}/${c.name}`)) {
       results.push({ ...c, action: 'skipped (filter)' });
+      onProgress({ phase: c.kind, current: i + 1, total: candidates.length, label: c.name });
       continue;
     }
 
     const action = await applyOne(c, strategy, opts);
     results.push({ ...c, action });
+    onProgress({ phase: c.kind, current: i + 1, total: candidates.length, label: c.name });
   }
 
   return { target: targetId, strategy, results };
@@ -139,6 +193,13 @@ export async function applyReverse(targetId, opts = {}) {
 
 async function applyOne(c, strategy, opts) {
   const dryRun = !!opts.dryRun;
+  const isMirrorTree = c.kind === 'framework' || c.kind === 'hooks';
+
+  // Mirror-tree files don't have stub boilerplate — copy bytes verbatim.
+  if (isMirrorTree) {
+    return applyMirrorTreeOne(c, strategy, dryRun);
+  }
+
   const destContent = await fs.readFile(c.destPath, 'utf8');
   const stripped = stripStubBoilerplate(destContent);
 
@@ -147,7 +208,6 @@ async function applyOne(c, strategy, opts) {
       return 'skipped';
 
     case 'overwrite': {
-      // Replace canonical with the destination content (stripped of stub boilerplate)
       if (!dryRun) {
         await fs.mkdir(path.dirname(c.kitPath), { recursive: true });
         await fs.writeFile(c.kitPath, stripped, 'utf8');
@@ -156,8 +216,6 @@ async function applyOne(c, strategy, opts) {
     }
 
     case 'merge': {
-      // Frontmatter from canonical (if present), body from destination.
-      // If canonical doesn't exist (new-in-ide), this degenerates to overwrite.
       let merged = stripped;
       if (c.reason === 'modified-in-ide') {
         try {
@@ -173,7 +231,6 @@ async function applyOne(c, strategy, opts) {
     }
 
     case 'rename': {
-      // Write next to canonical with a -from-<targetfolder>.md suffix
       const base = c.kitPath.replace(/\.md$/, '');
       const tag = path.basename(path.dirname(path.dirname(c.destPath))).replace(/^\./, '');
       const out = `${base}-from-${tag || 'ide'}.md`;
@@ -189,6 +246,42 @@ async function applyOne(c, strategy, opts) {
   }
 }
 
+async function applyMirrorTreeOne(c, strategy, dryRun) {
+  switch (strategy) {
+    case 'skip':
+      return 'skipped';
+
+    case 'overwrite':
+    case 'merge': {
+      // For framework/hooks files there's no frontmatter to preserve,
+      // so 'merge' degenerates to overwrite. Returning a verb that
+      // signals the degradation.
+      const verb = strategy === 'merge' ? 'merged (overwrite, no frontmatter)' : 'overwritten';
+      if (!dryRun) {
+        await fs.mkdir(path.dirname(c.kitPath), { recursive: true });
+        await fs.copyFile(c.destPath, c.kitPath);
+      }
+      return dryRun ? `${strategy} (dry-run)` : verb;
+    }
+
+    case 'rename': {
+      // Write to kit/<source>/<rel>.from-<tag> preserving extension after the tag.
+      const ext = path.extname(c.kitPath);
+      const stem = c.kitPath.slice(0, c.kitPath.length - ext.length);
+      const tag = path.basename(path.dirname(path.dirname(c.destPath))).replace(/^\./, '') || 'ide';
+      const out = `${stem}.from-${tag}${ext}`;
+      if (!dryRun) {
+        await fs.mkdir(path.dirname(out), { recursive: true });
+        await fs.copyFile(c.destPath, out);
+      }
+      return dryRun ? `rename → ${out} (dry-run)` : `renamed → ${out}`;
+    }
+
+    default:
+      return `unknown strategy: ${strategy}`;
+  }
+}
+
 // --- helpers ---
 
 function isCleanStub(content) {

package/src/core/sync.js

@@ -24,6 +24,7 @@ export async function syncTo(targetId, opts = {}) {
   const kitRoot     = resolveKitRoot(opts.kitRoot);
   const mode        = opts.mode ?? 'reference';
   const dryRun      = !!opts.dryRun;
+  const onProgress  = opts.onProgress ?? (() => {});
 
   const kit  = await listKit(kitRoot);
   const ops  = [];
@@ -82,6 +83,7 @@ export async function syncTo(targetId, opts = {}) {
   }
 
   if (!dryRun) {
+    let i = 0;
     for (const op of ops) {
       await fs.mkdir(path.dirname(op.path), { recursive: true });
       if (op.treeCopy) {
@@ -89,6 +91,8 @@ export async function syncTo(targetId, opts = {}) {
       } else {
         await fs.writeFile(op.path, op.content, 'utf8');
       }
+      i++;
+      onProgress({ phase: op.kind, current: i, total: ops.length, label: path.basename(op.path) });
     }
   }
 
@@ -196,15 +200,19 @@ function renderReference(item, kitRoot, outPath, isSkill) {
     ? item.frontmatterRaw
     : synthFrontmatter(item);
 
-  const desc = item.description ? `\n> ${item.description}\n` : '';
-  // Blank line between frontmatter and the stub marker so YAML parsers don't choke.
-  return `${fm}\n${STUB_MARKER}
+  // Body must NOT start with the STUB_MARKER comment — IDE listings (e.g. Claude Desktop)
+  // that take the first non-blank body line as the visible description would surface
+  // "<!-- kit-mcp:reference -->" instead of the real description. So we open with the
+  // H1 + description blockquote, and tuck the marker at the end as a trailing comment.
+  const descLine = item.description ? `\n> ${item.description}\n` : '';
+  return `${fm}
 # ${item.name}
-
+${descLine}
 > Canonical source: [\`${rel}\`](${rel})
-${desc}
-> Generated by kit-mcp at ${new Date().toISOString()}.
 > Edit the source file in the kit, not this stub.
+> Generated by kit-mcp at ${new Date().toISOString()}.
+
+${STUB_MARKER}
 `;
 }
 

package/src/core/ui.js

@@ -0,0 +1,167 @@
+// UI primitives for the CLI: colors, icons, spinner, progress bar,
+// interactive select/confirm prompts, and a summary panel.
+//
+// Design rules:
+//   - Respect process.stdout.isTTY: animations only when interactive.
+//     In pipes/CI, fall back to linear status text.
+//   - Respect NO_COLOR (https://no-color.org) and FORCE_COLOR=1.
+//   - Animations write to stderr to keep stdout clean for `--json` mode
+//     (the user can still pipe machine-readable output even with spinners).
+//   - Zero hidden globals — every primitive is a plain function/class.
+
+import pc from 'picocolors';
+import { select as inqSelect, confirm as inqConfirm } from '@inquirer/prompts';
+
+// --- color helpers ---
+
+const NO_COLOR = process.env.NO_COLOR && process.env.NO_COLOR !== '0';
+const FORCE    = process.env.FORCE_COLOR === '1';
+const COLOR_ON = FORCE || (!NO_COLOR && process.stdout.isTTY);
+
+function id(s) { return String(s); }
+export const c = COLOR_ON
+  ? {
+      green: pc.green, red: pc.red, yellow: pc.yellow, cyan: pc.cyan,
+      magenta: pc.magenta, blue: pc.blue, dim: pc.dim, bold: pc.bold,
+      gray: pc.gray, underline: pc.underline,
+    }
+  : {
+      green: id, red: id, yellow: id, cyan: id, magenta: id, blue: id,
+      dim: id, bold: id, gray: id, underline: id,
+    };
+
+export const icons = {
+  check:   '✓',
+  cross:   '✗',
+  warn:    '⚠',
+  dot:     '•',
+  arrow:   '→',
+  spinner: ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'],
+};
+
+// --- spinner ---
+
+export function spinner({ text = '' } = {}) {
+  const tty = process.stderr.isTTY;
+  let i = 0;
+  let current = text;
+  let timer = null;
+
+  function render() {
+    process.stderr.write(`\r${c.cyan(icons.spinner[i])} ${current}\x1b[K`);
+    i = (i + 1) % icons.spinner.length;
+  }
+
+  if (tty) {
+    timer = setInterval(render, 80);
+    render();
+  } else {
+    process.stderr.write(`${icons.dot} ${current}\n`);
+  }
+
+  function clearLine() {
+    if (tty) process.stderr.write('\r\x1b[K');
+  }
+
+  return {
+    update(t) { current = t; if (!tty) process.stderr.write(`${icons.dot} ${t}\n`); },
+    succeed(t) {
+      if (timer) clearInterval(timer);
+      clearLine();
+      process.stderr.write(`${c.green(icons.check)} ${t ?? current}\n`);
+    },
+    fail(t) {
+      if (timer) clearInterval(timer);
+      clearLine();
+      process.stderr.write(`${c.red(icons.cross)} ${t ?? current}\n`);
+    },
+    stop() {
+      if (timer) clearInterval(timer);
+      clearLine();
+    },
+  };
+}
+
+// --- progress bar ---
+
+export function progress({ total, label = '' } = {}) {
+  const tty = process.stderr.isTTY;
+  const width = 24;
+  let current = 0;
+  let lastLabel = label;
+
+  function render() {
+    const pct = total === 0 ? 100 : Math.min(100, Math.round((current / total) * 100));
+    const filled = Math.round((width * pct) / 100);
+    const bar = '━'.repeat(filled) + c.dim('━'.repeat(width - filled));
+    const line = `${c.cyan(bar)} ${pct.toString().padStart(3)}% ${c.dim(`(${current}/${total})`)} ${lastLabel}`;
+    process.stderr.write(`\r${line}\x1b[K`);
+  }
+
+  function tick({ label } = {}) {
+    current++;
+    if (label !== undefined) lastLabel = label;
+    if (tty) {
+      render();
+    } else if (current === total || current % Math.max(1, Math.floor(total / 10)) === 0) {
+      // Every ~10% in non-TTY mode
+      const pct = total === 0 ? 100 : Math.round((current / total) * 100);
+      process.stderr.write(`  ${pct}% ${lastLabel}\n`);
+    }
+  }
+
+  function finish(text) {
+    if (tty) {
+      process.stderr.write('\r\x1b[K');
+    }
+    if (text) process.stderr.write(`${c.green(icons.check)} ${text}\n`);
+  }
+
+  if (tty) render();
+  return { tick, finish };
+}
+
+// --- interactive prompts ---
+
+export async function select(opts) {
+  if (!process.stdin.isTTY) {
+    throw new Error('Interactive prompt unavailable: stdin is not a TTY. Pass the value as a flag instead.');
+  }
+  return inqSelect(opts);
+}
+
+export async function confirm(opts) {
+  if (!process.stdin.isTTY) {
+    throw new Error('Interactive prompt unavailable: stdin is not a TTY. Pass --yes to skip confirmation.');
+  }
+  return inqConfirm(opts);
+}
+
+// --- summary panel ---
+
+export function summary({ title, rows = [], total, hint }) {
+  const lines = [];
+  lines.push(`${c.green(icons.check)} ${c.bold(title)}`);
+  lines.push('');
+
+  // Compute label column width
+  const w = Math.max(...rows.map(r => String(r[0]).length), 0);
+  for (const [label, count, status] of rows) {
+    const cnt = count > 0 ? c.green(String(count).padStart(4)) : c.dim(String(count).padStart(4));
+    const tail = status === 'fail' ? c.red(icons.cross) : c.green(icons.check);
+    lines.push(`  ${label.padEnd(w)}  ${cnt}  ${tail}`);
+  }
+
+  if (total !== undefined || hint) {
+    lines.push('');
+    const totalStr = total !== undefined ? `Total: ${c.bold(total)}` : '';
+    const hintStr = hint ? c.dim(`· ${hint}`) : '';
+    lines.push(`  ${totalStr}${totalStr && hintStr ? ' ' : ''}${hintStr}`);
+  }
+
+  return lines.join('\n');
+}
+
+// --- helpers exposed for tests ---
+
+export const _internal = { COLOR_ON };