@luanpdd/kit-mcp 0.4.1 → 1.0.0

package/CHANGELOG.md

@@ -6,6 +6,67 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [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
+- **Mirror-tree sync for `framework` and `hooks`.** `kit/framework/` (124 files: workflows, templates, references, libs) and `kit/hooks/` (5 files) are now projected into `.claude/framework/` and `.claude/hooks/` on every `sync install claude-code`. Without this, the bundled slash-commands like `/novo-marco` were broken-by-design — they referenced `@./.claude/framework/workflows/new-milestone.md` and similar paths that never existed in the destination project. Now they resolve correctly end-to-end.
+- New `mode: 'mirror-tree'` capability spec in `src/core/registry.js`. Each mirror-tree entry has a `source` (relative path inside `kit/`) and a `path` (destination path in the target project).
+- A `.kit-mcp-managed` marker file is written at the root of each managed tree so `kit sync remove` can recursively clean up the directory **only** when the marker is present. Trees you authored yourself (without the marker) are never touched.
+- CI smoke test asserts `.claude/framework/workflows/new-milestone.md`, `.claude/framework/templates/project.md`, and `.claude/hooks/workflow-guard.js` are projected, and that `sync remove` cleans them up.
+- New CI safety test: `sync remove` against a `.claude/framework/` directory with no marker preserves user content.
+
+### Changed
+- `statusOf` now reports `framework` and `hooks` capability paths.
+- README capability matrix gained two columns (`framework`, `hooks`) and a paragraph explaining the mirror-tree semantics.
+
+### Migration
+No action needed — `npx -y @luanpdd/kit-mcp@latest sync install claude-code --project-root .` projects the new directories automatically. If you had a manually-created `.claude/framework/` or `.claude/hooks/`, kit-mcp will overwrite individual files but won't delete user files; `sync remove` continues to leave them alone.
+
 ## [0.4.1] - 2026-05-03
 
 ### Fixed
@@ -158,7 +219,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.4.1...HEAD
+[Unreleased]: https://github.com/luanpdd/kit-mcp/compare/v1.0.0...HEAD
+[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
 [0.3.0]: https://github.com/luanpdd/kit-mcp/compare/v0.2.1...v0.3.0

package/README.md

@@ -159,19 +159,21 @@ kit sync watch --all                          # watch + auto-detect every IDE al
 
 **Per-IDE projection** — what each target receives:
 
-| IDE | rules → | agents → | commands → | skills → |
-|---|---|---|---|---|
-| Claude Code | `CLAUDE.md` | `.claude/agents/*.md` | `.claude/commands/*.md` | `.claude/skills/*/` |
-| Cursor | `.cursor/rules/*.mdc` | `.cursor/agents/*.md` | — | — |
-| Codex | `AGENTS.md` | — | — | `.codex/skills/*/` |
-| Gemini CLI | `GEMINI.md` | — | — | `.gemini/skills/*/` |
-| Copilot | `.github/copilot-instructions.md` | `.github/agents/*.agent` | — | `.github/skills/*/` |
-| Windsurf | `.windsurf/rules/*.md` | `.windsurf/agents/*.md` | — | `.windsurf/skills/*/` |
-| Antigravity | `.agents/rules/*.md` | `.agents/agents/*.md` | — | `.agents/workflows/*/` |
-| Trae | `.trae/rules/*.md` | `.trae/agents/*.md` | — | — |
+| IDE | rules → | agents → | commands → | skills → | framework → | hooks → |
+|---|---|---|---|---|---|---|
+| Claude Code | `CLAUDE.md` | `.claude/agents/*.md` | `.claude/commands/*.md` | `.claude/skills/*/` | `.claude/framework/**` | `.claude/hooks/**` |
+| Cursor | `.cursor/rules/*.mdc` | `.cursor/agents/*.md` | — | — | — | — |
+| Codex | `AGENTS.md` | — | — | `.codex/skills/*/` | — | — |
+| Gemini CLI | `GEMINI.md` | — | — | `.gemini/skills/*/` | — | — |
+| Copilot | `.github/copilot-instructions.md` | `.github/agents/*.agent` | — | `.github/skills/*/` | — | — |
+| Windsurf | `.windsurf/rules/*.md` | `.windsurf/agents/*.md` | — | `.windsurf/skills/*/` | — | — |
+| Antigravity | `.agents/rules/*.md` | `.agents/agents/*.md` | — | `.agents/workflows/*/` | — | — |
+| Trae | `.trae/rules/*.md` | `.trae/agents/*.md` | — | — | — | — |
 
 A capability marked `—` is not supported by that IDE. Adding a new IDE = one entry in [`src/core/registry.js`](src/core/registry.js).
 
+**About `framework` and `hooks`:** these are *mirror-tree* capabilities — the entire `kit/framework/` and `kit/hooks/` subtrees are copied verbatim into `.claude/framework/` and `.claude/hooks/`. They're needed by the bundled workflow because slash-commands like `/novo-marco` reference framework files via paths like `@./.claude/framework/workflows/new-milestone.md`. A `.kit-mcp-managed` marker is written at the root of each managed tree so `kit sync remove` can clean up safely without touching directories you authored yourself.
+
 ### `kit install ...` — register kit-mcp into an IDE's MCP config
 
 ```bash
@@ -192,16 +194,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
 
@@ -467,16 +472,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.4.1",
+  "version": "1.0.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,7 +41,10 @@
   "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": {
     "@modelcontextprotocol/sdk": "^1.0.0",

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/registry.js

@@ -20,6 +20,8 @@ export const TARGETS = {
     agents:   { path: '.claude/agents/',                   mode: 'multi',     extension: '.md' },
     commands: { path: '.claude/commands/',                 mode: 'multi',     extension: '.md' },
     skills:   { path: '.claude/skills/',                   mode: 'multi-dir' },
+    framework:{ path: '.claude/framework/',                mode: 'mirror-tree', source: 'framework' },
+    hooks:    { path: '.claude/hooks/',                    mode: 'mirror-tree', source: 'hooks' },
     mcpConfig:{ path: '.mcp.json',                         strategy: 'merge-mcpServers-json',
                 userPath: '~/.claude.json',                userKey: 'mcpServers' },
   },
@@ -92,11 +94,13 @@ export function listTargets() {
     id,
     label: t.label,
     capabilities: {
-      rules:    !!t.rules,
-      agents:   !!t.agents,
-      commands: !!t.commands,
-      skills:   !!t.skills,
-      mcpConfig:!!t.mcpConfig,
+      rules:     !!t.rules,
+      agents:    !!t.agents,
+      commands:  !!t.commands,
+      skills:    !!t.skills,
+      framework: !!t.framework,
+      hooks:     !!t.hooks,
+      mcpConfig: !!t.mcpConfig,
     },
   }));
 }

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,6 +122,51 @@ 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 = {}) {
@@ -139,6 +189,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 +204,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 +212,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 +227,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 +242,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

@@ -15,6 +15,8 @@ import { getTarget } from './registry.js';
 import { listKit, resolveKitRoot } from './kit.js';
 
 const STUB_MARKER = '<!-- kit-mcp:reference -->';
+const MANAGED_MARKER_FILE = '.kit-mcp-managed';
+const MANAGED_MARKER_BODY = '# Managed by @luanpdd/kit-mcp — this directory is overwritten on every `kit sync install`.\n# Do not edit files here directly; edit the canonical source under kit/ and re-run sync.\n# Removing this file disables `kit sync remove` cleanup of this tree.\n';
 
 export async function syncTo(targetId, opts = {}) {
   const target      = getTarget(targetId);
@@ -62,21 +64,62 @@ export async function syncTo(targetId, opts = {}) {
     }
   }
 
+  // Mirror-tree capabilities (framework, hooks) — copy a whole subtree of kit/<source>
+  // into target.<cap>.path, preserving relative structure. Dropped a marker file at the
+  // root so `kit sync remove` can clean up the tree safely.
+  for (const cap of ['framework', 'hooks']) {
+    const spec = target[cap];
+    if (!spec || spec.mode !== 'mirror-tree') continue;
+    const srcRoot = path.join(kitRoot, spec.source);
+    const dstRoot = path.join(projectRoot, spec.path);
+    const files = await walkTree(srcRoot);
+    if (files.length === 0) continue;
+    ops.push({ path: path.join(dstRoot, MANAGED_MARKER_FILE), content: MANAGED_MARKER_BODY, kind: cap });
+    for (const f of files) {
+      const dst = path.join(dstRoot, f.rel);
+      ops.push({ path: dst, srcAbs: f.abs, kind: cap, treeCopy: true });
+    }
+  }
+
   if (!dryRun) {
     for (const op of ops) {
       await fs.mkdir(path.dirname(op.path), { recursive: true });
-      await fs.writeFile(op.path, op.content, 'utf8');
+      if (op.treeCopy) {
+        await fs.copyFile(op.srcAbs, op.path);
+      } else {
+        await fs.writeFile(op.path, op.content, 'utf8');
+      }
     }
   }
 
   return { target: targetId, mode, projectRoot, kitRoot, written: ops.map(o => o.path), dryRun };
 }
 
+async function walkTree(dir) {
+  const out = [];
+  async function visit(current, relPrefix) {
+    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 = relPrefix ? `${relPrefix}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        await visit(abs, rel);
+      } else if (e.isFile()) {
+        out.push({ abs, rel });
+      }
+    }
+  }
+  await visit(dir, '');
+  return out;
+}
+
 export async function statusOf(targetId, opts = {}) {
   const target      = getTarget(targetId);
   const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
   const checks = [];
-  for (const cap of ['rules', 'agents', 'commands', 'skills']) {
+  for (const cap of ['rules', 'agents', 'commands', 'skills', 'framework', 'hooks']) {
     if (!target[cap]) continue;
     const probe = path.join(projectRoot, target[cap].path);
     let exists = false;
@@ -105,6 +148,18 @@ export async function removeFrom(targetId, opts = {}) {
       }
     } catch {}
   }
+  // Mirror-tree capabilities: only remove if our marker is present (we manage the whole subtree).
+  for (const cap of ['framework', 'hooks']) {
+    const spec = target[cap];
+    if (!spec || spec.mode !== 'mirror-tree') continue;
+    const dir = path.join(projectRoot, spec.path);
+    const marker = path.join(dir, MANAGED_MARKER_FILE);
+    try {
+      await fs.access(marker);
+      await fs.rm(dir, { recursive: true, force: true });
+      removed.push(dir);
+    } catch {}
+  }
   return { target: targetId, projectRoot, removed };
 }
 
@@ -141,15 +196,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}
 `;
 }