@khanhcan148/mk 0.1.9 → 0.1.11

package/README.md

@@ -6,15 +6,8 @@
 
 Modular packages that extend Claude Code with specialized knowledge, workflows, and tool integrations.
 
-**Quick Navigation:** [Quick Reference](docs/QUICK-REFERENCE.md) | [Common Workflows](docs/COMMON-WORKFLOWS.md) | [Skill Index](docs/SKILL-INDEX.md)
+**Quick Navigation:** [Quick Reference](docs/quick-reference.md) | [Common Workflows](docs/common-workflows.md) | [Skill Index](docs/skill-index.md)
 
-## 🔒 Access Notice
-
-**This package has limited access.** To get access to the npm package and repository:
-
-📧 **Email:** khanhcan148@gmail.com
-
-Include your use case and I'll send you an invitation.
 
 ## Quick Start
 
@@ -73,27 +66,31 @@ cp -r .claude ~/.claude/
 
 ```bash
 # Use a workflow command
-/mk-init          # Bootstrap new project
-/mk-brainstorm    # Explore options, debate trade-offs
-/mk-plan          # Create implementation plan
-/mk-implement     # End-to-end feature delivery
-/mk-test          # Run tests and validate
-/mk-review        # Code quality review
-/mk-debug         # Debug issues
-/mk-security      # Security scan and audit
-/mk-db            # Database operations
-/mk-docs          # Generate documentation
-/mk-git           # Git operations
+/mk-init           # Bootstrap new project
+/mk-brainstorm     # Explore options, debate trade-offs; pass Jira/AzDO URL to fetch ticket context first
+/mk-plan           # Create implementation plan
+/mk-implement      # End-to-end feature delivery
+/mk-test           # Run tests and validate
+/mk-review         # Code quality review
+/mk-debug          # Debug issues
+/mk-security       # Security scan and audit
+/mk-db             # Database operations
+/mk-docs           # Generate documentation
+/mk-overview       # Multi-tier stakeholder overview (Executive, Product, Technical)
+/mk-git            # Git operations
+/mk-audit          # Code archaeology chain: orientation, testing, heatmap, breaking-change analysis, technical debt, domain extraction
+/mk-selftest       # Self-validation checks on kit agents, skills, docs, workflows
+/mk-log-analysis   # Datadog + Azure App Insights log analysis with severity triage and Mermaid visual reports
 ```
 
 ## Structure
 
 ```
 ├── .claude/
-│   ├── agents/      # 29 agents (5 primary + 24 utility: implementers, quality, docs, specialized, concerns)
-│   ├── skills/      # 53 skill packages (SKILL.md + scripts/references/assets)
-│   │   ├── mk-*/    # 14 workflow commands (/mk-brainstorm, /mk-selftest, etc.)
-│   │   └── ...      # Domain skills (frontend, backend, testing, etc.)
+│   ├── agents/      # 31 agents (5 primary + 26 utility: implementers, quality, docs, specialized, concerns)
+│   ├── skills/      # 65 skill packages (SKILL.md + scripts/references/assets)
+│   │   ├── mk-*/    # 19 workflow commands (/mk-audit, /mk-brainstorm, /mk-log-analysis, /mk-overview, /mk-selftest, etc.)
+│   │   └── ...      # Domain skills (frontend, backend, testing, browser automation, etc.)
 │   └── workflows/   # Development protocols
 ├── bin/             # CLI entry point (mk command)
 ├── src/             # CLI source code
@@ -106,7 +103,7 @@ cp -r .claude ~/.claude/
 
 ## Primary Workflow
 
-Orchestration is handled by `/mk-*` skills which spawn utility agents as needed. See [Common Workflows](docs/COMMON-WORKFLOWS.md) for practical examples.
+Orchestration is handled by `/mk-*` skills which spawn utility agents as needed. See [Common Workflows](docs/common-workflows.md) for practical examples.
 
 **Architecture:**
 
@@ -123,19 +120,24 @@ User → /mk-* command (skill) → spawns utility agents → agents use knowledg
 
 | Command | Purpose |
 |---------|---------|
-| `/mk-init` | Full project bootstrap from conception to deployment; includes brownfield detection (Phase 0 gate) and adoption workflow (B1-B4.5 stages) |
-| `/mk-brainstorm` | Ideation, requirements exploration, structured debate (analyzer opus agent); use `--domain` flag to extract and document domain knowledge |
-| `/mk-research` | Deep multi-source research on technical topics |
+| `/mk-init` | Full project bootstrap from conception to deployment; includes brownfield detection (Phase 0 gate) and adoption workflow (B1-B4.5 stages); generates AGENTS.md template (or migrates existing tool configs); suggests /mk-audit as next step for brownfield projects |
+| `/mk-brainstorm` | Ideation, requirements exploration, structured debate (analyzer opus agent); pass a Jira or AzDO URL to fetch ticket hierarchy first (Phase 0.5) |
+| `/mk-audit` | Code archaeology chain: orientation report, characterization testing, topology heatmap, breaking-change analysis, technical debt dashboard, domain extraction; enriches CLAUDE.md and AGENTS.md with auto-generated architecture and debt sections |
 | `/mk-plan` | Create implementation plans with phases and tasks (opus) |
 | `/mk-design` | UI/UX wireframes, design systems, mockups |
 | `/mk-implement` | End-to-end feature delivery (sonnet) |
 | `/mk-test` | Run tests, analyze coverage, validate builds |
 | `/mk-review` | Code review for quality, security, performance |
-| `/mk-debug` | Debugging workflow: investigate, diagnose, fix, verify |
+| `/mk-debug` | Debugging workflow: investigate, diagnose, fix, verify; always offers incident journal documentation with severity hints |
 | `/mk-security` | Security-first workflow: dependency scan, secrets detection |
 | `/mk-db` | Database operations: diagnose, optimize, design, migrate |
-| `/mk-docs` | Generate and update project documentation |
+| `/mk-docs` | Generate and update project documentation; maintains AGENTS.md; Impact Areas analysis produces human-readable "What changed / Who is affected / What could go wrong" narrative |
 | `/mk-git` | Git operations: branch, commit, push, PR, merge |
+| `/mk-research` | Deep multi-source research on technical topics |
+| `/mk-spike` | Investigate external service integrations: fetch API docs, evaluate options, produce spike.md with Go/No-Go |
+| `/mk-overview` | Synthesize project artifacts into multi-tier stakeholder overview: Executive Brief, Product Report, Technical Report |
+| `/mk-workflow` | Trace REST endpoint call chains with upstream caller detection, variant branching, side effects/feature flags, Mermaid diagrams |
+| `/mk-log-analysis` | Analyze production logs from Datadog or Azure Application Insights via MCP; progressive severity triage, pattern detection, mandatory stack trace investigation, mk-debug integration |
 | `/mk-selftest` | Run self-validation checks on kit agents, skills, docs, and workflows |
 
 ## Primary Agents
@@ -148,17 +150,18 @@ Invoked directly via `/mk-*` skills:
 | **planner** | Implementation planning with phases, tasks, dependencies | opus |
 | **implementer** | End-to-end feature implementation | sonnet |
 | **database-admin** | Database operations: diagnose, optimize, design, migrate | sonnet |
-| **git-manager** | Git operations: commit, push, PR, merge | haiku |
+| **git-manager** | Git operations: commit, push, PR, merge | sonnet |
 
 ## Utility Agents
 
 Spawned by primary agents for domain-specific work:
 
-**Implementation & Quality (8)**
+**Implementation & Quality (9)**
 | Agent | Purpose |
 |-------|---------|
 | **backend-implementer** | API and domain logic implementation |
 | **frontend-implementer** | UI components, consuming API contract |
+| **mobile-implementer** | Mobile app implementation (Flutter, React Native, Swift, Kotlin) with TFD |
 | **tester** | Test execution and validation |
 | **debugger** | Issue investigation and diagnosis |
 | **refactorer** | Refactoring with TFD-first safety workflow |
@@ -184,7 +187,7 @@ Spawned by primary agents for domain-specific work:
 | **scout-external** | Codebase search via external tools |
 | **mcp-manager** | MCP server integrations |
 
-**Parallel Concern Review Agents (10)**
+**Parallel Concern Review Agents (11)**
 | Agent | Purpose |
 |-------|---------|
 | **quality-reviewer** | Code quality, readability, maintainability (mk-review concern) |
@@ -197,32 +200,30 @@ Spawned by primary agents for domain-specific work:
 | **infra-reviewer** | Infrastructure security review (mk-security concern) |
 | **log-analyzer** | Log analysis and diagnostics (mk-debug concern) |
 | **hypothesis-generator** | Root cause hypothesis generation (mk-debug concern) |
+| **log-collector** | External observability platform queries — Datadog and Azure App Insights MCP (mk-log-analysis concern) |
 
 [Full agent details →](.claude/agents/README.md)
 
 ## Skills
 
-See [Skill Index](docs/SKILL-INDEX.md) for a complete categorized list of all skills.
+See [Skill Index](docs/skill-index.md) for a complete categorized list of all skills.
 
 Each skill contains:
-- `SKILL.md` (required) - Instructions (<100 lines)
+- `SKILL.md` (required) - Instructions (≤250 lines)
 - `scripts/` (optional) - Executable code with tests
 - `references/` (optional) - Documentation chunks
 - `assets/` (optional) - Templates, images
 
 ```bash
-# Initialize new skill
-.claude/skills/skill-creator/scripts/init_skill.py <skill-name> --path <output-directory>
-
-# Package for distribution
-.claude/skills/skill-creator/scripts/package_skill.py <path/to/skill-folder>
+# Create new skill
+python .claude/skills/skill-creator/scripts/package_skill.py <path/to/skill-folder>
 ```
 
 ## Documentation
 
 | Document | Description |
 |----------|-------------|
-| [Skill Index](docs/SKILL-INDEX.md) | Categorized list of all skills and workflows |
+| [Skill Index](docs/skill-index.md) | Categorized list of all skills and workflows |
 | [mk-* Workflows & Agents](docs/mk-workflow-agents.md) | How each /mk-* command works and which agents it uses |
 | [Project Overview & PDR](docs/project-overview-pdr.md) | Requirements, constraints, success metrics |
 | [Project Roadmap](docs/project-roadmap.md) | Phases, milestones, and risk register |
@@ -230,8 +231,8 @@ Each skill contains:
 | [Code Standards](docs/code-standards.md) | Conventions, naming, quality gates |
 | [System Architecture](docs/system-architecture.md) | Component diagrams, data flow |
 | [Product Domain Glossary](docs/product-domain-glossary.md) | Core domain concepts, terminology, and ecosystem definitions |
-| [Quick Reference](docs/QUICK-REFERENCE.md) | Common commands and quick lookup |
-| [Common Workflows](docs/COMMON-WORKFLOWS.md) | Practical workflow examples |
+| [Quick Reference](docs/quick-reference.md) | Common commands and quick lookup |
+| [Common Workflows](docs/common-workflows.md) | Practical workflow examples |
 
 ## Core Principles
 
@@ -242,16 +243,12 @@ Each skill contains:
 
 ## Key Constraints
 
-- SKILL.md must be under 100 lines
-- Referenced markdown files also under 100 lines
+- SKILL.md must be ≤250 lines
+- Reference files in `references/` have no line limit; loaded on-demand
 - Scripts must include tests
 - **Cross-platform compatibility (Windows + macOS/Linux) is mandatory**: Scripts use Python or Node.js only — no bash/shell scripts
 - Token efficiency - minimize context usage
 
-## Compatibility
-
-This skill kit works in both Claude Code CLI and VSCode GitHub Copilot (1.108+).
-
 ## Cross-Platform Compatibility
 
 This kit is designed to work on Windows, macOS, and Linux:
@@ -259,19 +256,4 @@ This kit is designed to work on Windows, macOS, and Linux:
 - **Scripts**: All executable scripts use Python or Node.js (no bash/shell scripts)
 - **Claude Code Bash tool**: Provides a Unix-like shell on all platforms, including Windows — git commands and other Bash tool invocations work everywhere
 - **External tool installs**: Reference files include install instructions for macOS (`brew`), Ubuntu/Debian (`apt-get`), and Windows (`winget`/`choco`) where applicable
-- **Agent fallbacks**: Agents using CLI-only tools (TodoWrite, BashOutput, MultiEdit) document VSCode Copilot fallback behavior inline
-
-| Feature | Claude Code CLI | VSCode Copilot (1.108+) |
-|---------|----------------|------------------------|
-| Skills (SKILL.md) | Full support | Full support |
-| Agents (.md) | Full support | Full support |
-| CLAUDE.md | Full support | Full support |
-| Model field | Shorthand (opus/sonnet/haiku) | Shorthand (recommended) |
-| Task tool | Native Task() syntax | Natural language delegation* |
-| color | Supported | Ignored (harmless) |
-| MCP tools | Full support | Limited |
-| AskUserQuestion | Native UI | Natural language fallback |
-
-*VSCode Copilot users: Use natural language to invoke agents (e.g., "Use the planner agent to create a plan"). The explicit Task() syntax is Claude Code CLI-specific.
-
-**CLI-only tools**: TodoWrite, BashOutput, KillShell, MultiEdit are Claude Code-specific. Agents gracefully fall back to standard tools (Write, Bash, sequential Edit) when these are unavailable.
+**Supported runtime**: Claude Code CLI. All skills, agents, and workflows are designed for the Claude Code runtime.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanhcan148/mk",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "CLI to install and manage MyClaudeKit (.claude/) in your projects",
   "type": "module",
   "bin": {
@@ -14,8 +14,8 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "test": "node --test test/lib/*.test.js test/commands/*.test.js test/integration/*.test.js",
-    "lint": "node --check src/**/*.js bin/**/*.js 2>/dev/null || true",
+    "test": "node --test test/lib/*.test.js test/commands/*.test.js test/integration/*.test.js test/characterization/*.characterization.test.js test/hooks/*.test.cjs",
+    "lint": "node --check src/**/*.js bin/**/*.js 2>/dev/null",
     "selftest": "python3 .claude/skills/mk-selftest/scripts/validate_kit.py"
   },
   "dependencies": {

package/src/commands/init.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import { existsSync, readFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { copyKitFiles } from '../lib/copy.js';
+import { copyKitFiles, mergeSettingsJson } from '../lib/copy.js';
 import { writeManifest } from '../lib/manifest.js';
 import { computeChecksum } from '../lib/checksum.js';
 import { resolveTargetDir, resolveManifestPath } from '../lib/paths.js';
@@ -45,6 +45,9 @@ export async function runInit(params = {}) {
   // Copy files (dry-run or real)
   const fileList = copyKitFiles(sourceDir, targetDir, { dryRun });
 
+  // Merge settings.json (hooks configuration) — safe merge, never overwrites user keys
+  mergeSettingsJson(sourceDir, targetDir, { dryRun });
+
   if (dryRun) {
     return { files: fileList, totalSize: fileList.reduce((s, f) => s + f.size, 0), dryRun: true };
   }

package/src/commands/remove.js

@@ -1,8 +1,9 @@
 import chalk from 'chalk';
-import { existsSync, unlinkSync, rmdirSync, readdirSync } from 'node:fs';
+import { existsSync, unlinkSync, rmdirSync } from 'node:fs';
 import { join, dirname, resolve, sep } from 'node:path';
 import { readManifest } from '../lib/manifest.js';
 import { resolveTargetDir, resolveManifestPath, deriveProjectRoot, assertSafePath } from '../lib/paths.js';
+import { isEmptyDir } from '../lib/fs-utils.js';
 
 /**
  * Run the remove command.
@@ -110,19 +111,6 @@ export async function runRemove(params = {}) {
   return { removed, skipped, dirsCleaned };
 }
 
-/**
- * Check if a directory is empty.
- * @param {string} dir
- * @returns {boolean}
- */
-function isEmptyDir(dir) {
-  try {
-    return readdirSync(dir).length === 0;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * CLI action handler for 'mk remove'.
  * @param {{ global: boolean }} options

package/src/commands/update.js

@@ -1,16 +1,17 @@
 import chalk from 'chalk';
 import { createInterface } from 'node:readline';
-import { existsSync, unlinkSync, copyFileSync, mkdirSync, readFileSync } from 'node:fs';
-import { join, dirname, resolve } from 'node:path';
+import { existsSync, unlinkSync, copyFileSync, mkdirSync, readFileSync, rmdirSync } from 'node:fs';
+import { join, dirname, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readManifest, updateManifest, diffManifest } from '../lib/manifest.js';
 import { computeChecksum } from '../lib/checksum.js';
-import { copyKitFiles } from '../lib/copy.js';
+import { copyKitFiles, collectDiskFiles, mergeSettingsJson } from '../lib/copy.js';
 import { resolveTargetDir, resolveManifestPath, deriveProjectRoot, assertSafePath } from '../lib/paths.js';
 import { resolveTokenOrLogin } from '../lib/auth.js';
 import { writeToken, readStoredToken } from '../lib/config.js';
 import { downloadAndExtractKit, cleanupTempDir } from '../lib/download.js';
 import { fetchLatestRelease, compareVersions } from '../lib/releases.js';
+import { isEmptyDir } from '../lib/fs-utils.js';
 
 // ---------------------------------------------------------------------------
 // Prompt helper
@@ -167,6 +168,61 @@ export async function runUpdate(params = {}) {
     delete newFiles[relPath];
   }
 
+  // Orphan cleanup: files on disk (in kit subdirs) that are not in the new source
+  const diskFiles = collectDiskFiles(targetDir);
+  const orphans = [];
+  const orphanParentDirs = new Set();
+  for (const relPath of diskFiles) {
+    if (relPath in sourceFiles) continue; // present in new source — keep
+    const absPath = join(projectRoot, relPath);
+    try {
+      assertSafePath(absPath, claudeRoot, `orphan "${relPath}"`);
+    } catch (err) {
+      process.stderr.write(`Warning: Skipping unsafe orphan path: ${err.message}\n`);
+      continue;
+    }
+    try {
+      unlinkSync(absPath);
+      orphans.push(relPath);
+      orphanParentDirs.add(dirname(absPath));
+    } catch {
+      // Already missing — skip
+    }
+  }
+
+  // Clean up empty directories bottom-up after orphan deletion
+  const resolvedTarget = resolve(targetDir);
+  const sortedOrphanDirs = [...orphanParentDirs].sort((a, b) => {
+    return b.split(/[/\\]/).length - a.split(/[/\\]/).length;
+  });
+  for (const dir of sortedOrphanDirs) {
+    if (isEmptyDir(dir)) {
+      try {
+        rmdirSync(dir);
+        let current = dirname(dir);
+        let prev = dir;
+        while (current !== prev && isEmptyDir(current)) {
+          const resolvedCurrent = resolve(current);
+          if (resolvedCurrent === resolvedTarget || !resolvedCurrent.startsWith(resolvedTarget + sep)) {
+            break;
+          }
+          try {
+            rmdirSync(current);
+          } catch {
+            break;
+          }
+          prev = current;
+          current = dirname(current);
+        }
+      } catch {
+        // Non-empty or permission error — skip
+      }
+    }
+  }
+
+  // Merge settings.json hooks — additive merge, never overwrites user keys
+  mergeSettingsJson(sourceDir, targetDir);
+
   // Update manifest with new file map.
   // Use explicitVersion when provided (e.g. release.version from updateAction);
   // fall back to pkg.version for direct runUpdate calls or main-branch fallback downloads.
@@ -178,6 +234,7 @@ export async function runUpdate(params = {}) {
     removed: diff.removed,
     conflicts: skippedConflicts,
     unchanged: diff.unchanged,
+    orphans,
     upToDate: false
   };
 }
@@ -305,6 +362,15 @@ export async function updateAction(options = {}, deps = {}) {
       }
       if (result.removed.length > 0) {
         process.stdout.write(chalk.yellow(`Removed: ${result.removed.length} files\n`));
+        for (const f of result.removed) {
+          process.stdout.write(`  Removed: ${f}\n`);
+        }
+      }
+      if (result.orphans && result.orphans.length > 0) {
+        process.stdout.write(chalk.yellow(`Cleaned: ${result.orphans.length} orphan files\n`));
+        for (const f of result.orphans) {
+          process.stdout.write(`  Cleaned: ${f}\n`);
+        }
       }
       if (result.conflicts.length > 0) {
         process.stdout.write(

package/src/lib/constants.js

@@ -1,7 +1,7 @@
 /**
  * Kit subdirectories to copy/manage (relative to .claude/)
  */
-export const KIT_SUBDIRS = ['agents', 'skills', 'workflows'];
+export const KIT_SUBDIRS = ['agents', 'skills', 'workflows', 'hooks'];
 
 /**
  * Manifest file name
@@ -13,12 +13,14 @@ export const MANIFEST_FILENAME = '.mk-manifest.json';
  */
 export const COPY_FILTER_PATTERNS = [
   '__pycache__',
+  '.pytest_cache',
   '.pyc',
   '.pyo',
   'node_modules',
   '.DS_Store',
   'package-lock.json',
-  '.env'
+  '.env',
+  '.logs'
 ];
 
 /**

package/src/lib/copy.js

@@ -1,5 +1,5 @@
 import { join, relative } from 'node:path';
-import { statSync, lstatSync, existsSync } from 'node:fs';
+import { statSync, lstatSync, existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import fsExtra from 'fs-extra';
 import { KIT_SUBDIRS, COPY_FILTER_PATTERNS, WINDOWS_PATH_WARN_LENGTH } from './constants.js';
 
@@ -52,6 +52,31 @@ function collectFiles(dir) {
   return results;
 }
 
+/**
+ * Collect all kit-managed files currently on disk under targetDir (.claude/).
+ * Only walks KIT_SUBDIRS (agents/, skills/, workflows/).
+ * Returns relative paths in the form `.claude/agents/foo.md`.
+ * Applies shouldFilter to exclude filtered patterns.
+ *
+ * @param {string} targetDir - Absolute path to target .claude/
+ * @returns {string[]} relative paths (relative to project root, e.g. `.claude/agents/foo.md`)
+ */
+export function collectDiskFiles(targetDir) {
+  const results = [];
+  for (const subdir of KIT_SUBDIRS) {
+    const subdirAbs = join(targetDir, subdir);
+    if (!existsSync(subdirAbs)) continue;
+    const files = collectFiles(subdirAbs);
+    for (const absPath of files) {
+      if (shouldFilter(absPath)) continue;
+      const relFromSubdir = relative(subdirAbs, absPath);
+      const relPath = join('.claude', subdir, relFromSubdir).replace(/\\/g, '/');
+      results.push(relPath);
+    }
+  }
+  return results;
+}
+
 /**
  * Copy kit files from sourceDir (.claude/) to targetDir (.claude/).
  * Only copies KIT_SUBDIRS (agents/, skills/, workflows/).
@@ -128,3 +153,96 @@ export function copyKitFiles(sourceDir, targetDir, options = {}) {
 
   return fileList;
 }
+
+/**
+ * Merge kit's settings.json into user's existing settings.json.
+ * Strategy: deep-merge "hooks" key from kit source; preserve all other user keys.
+ * If user has no settings.json, copy kit source as-is.
+ * If kit source has no settings.json, do nothing.
+ *
+ * @param {string} sourceDir - Absolute path to source .claude/
+ * @param {string} targetDir - Absolute path to target .claude/
+ * @param {{ dryRun: boolean }} options
+ * @returns {{ action: 'created'|'merged'|'skipped', merged?: string[] }}
+ */
+export function mergeSettingsJson(sourceDir, targetDir, options = {}) {
+  const { dryRun = false } = options;
+  const srcPath = join(sourceDir, 'settings.json');
+  const destPath = join(targetDir, 'settings.json');
+
+  if (!existsSync(srcPath)) return { action: 'skipped' };
+
+  let kitSettings;
+  try {
+    kitSettings = JSON.parse(readFileSync(srcPath, 'utf-8'));
+  } catch {
+    return { action: 'skipped' };
+  }
+
+  // No existing user settings — copy kit source as-is
+  if (!existsSync(destPath)) {
+    if (!dryRun) {
+      mkdirSync(targetDir, { recursive: true });
+      writeFileSync(destPath, JSON.stringify(kitSettings, null, 2) + '\n', 'utf-8');
+    }
+    return { action: 'created' };
+  }
+
+  // Existing user settings — merge hooks only, preserve everything else
+  let userSettings;
+  try {
+    userSettings = JSON.parse(readFileSync(destPath, 'utf-8'));
+  } catch {
+    // Malformed user settings — skip to avoid data loss
+    return { action: 'skipped' };
+  }
+
+  const merged = [];
+
+  // Merge hooks: kit entries are added/updated, user entries not in kit are preserved
+  if (kitSettings.hooks) {
+    if (!userSettings.hooks) userSettings.hooks = {};
+    for (const [event, kitEntries] of Object.entries(kitSettings.hooks)) {
+      if (!userSettings.hooks[event]) {
+        userSettings.hooks[event] = kitEntries;
+        merged.push(event);
+      } else {
+        // Merge by matcher: add kit entries whose matcher doesn't already exist
+        for (const kitEntry of kitEntries) {
+          const kitMatcher = kitEntry.matcher || '*';
+          const exists = userSettings.hooks[event].some(
+            e => (e.matcher || '*') === kitMatcher
+          );
+          if (!exists) {
+            userSettings.hooks[event].push(kitEntry);
+            merged.push(`${event}[${kitMatcher}]`);
+          }
+          // If matcher exists, check if kit hooks are present
+          if (exists) {
+            const userEntry = userSettings.hooks[event].find(
+              e => (e.matcher || '*') === kitMatcher
+            );
+            if (userEntry && userEntry.hooks && kitEntry.hooks) {
+              for (const kh of kitEntry.hooks) {
+                const hookExists = userEntry.hooks.some(
+                  uh => uh.command === kh.command
+                );
+                if (!hookExists) {
+                  userEntry.hooks.push(kh);
+                  merged.push(`${event}[${kitMatcher}]:${kh.command}`);
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  if (merged.length === 0) return { action: 'skipped' };
+
+  if (!dryRun) {
+    writeFileSync(destPath, JSON.stringify(userSettings, null, 2) + '\n', 'utf-8');
+  }
+  return { action: 'merged', merged };
+}

package/src/lib/fs-utils.js

@@ -0,0 +1,18 @@
+import { readdirSync } from 'node:fs';
+
+/**
+ * Check if a directory is empty.
+ *
+ * Returns false (rather than throwing) if the directory does not exist
+ * or is inaccessible — callers treat non-empty as a safe default.
+ *
+ * @param {string} dir - Absolute path to directory
+ * @returns {boolean} true if directory exists and contains no entries
+ */
+export function isEmptyDir(dir) {
+  try {
+    return readdirSync(dir).length === 0;
+  } catch {
+    return false;
+  }
+}