cursor-guard 4.7.4 → 4.7.6

package/README.md

@@ -296,16 +296,32 @@ Features:
 - **Security** — binds to `127.0.0.1` only (not exposed to LAN), API uses project IDs instead of raw file paths, static file serving restricted to `public/` directory
 - **Zero extra dependencies** — uses Node.js built-in `http` module + existing cursor-guard core modules
 
-### IDE Extension (VSCode / Cursor)
+### IDE Extension (VSCode / Cursor / Windsurf)
 
 Embed the full dashboard directly inside your IDE — no browser needed.
 
-The extension is located at `references/vscode-extension/`. To install:
+#### Method A: VSIX standalone (recommended, no npm needed)
+
+```bash
+# Build the self-contained VSIX package
+cd references/vscode-extension
+node build-vsix.js
+cd dist
+npx vsce package
+
+# Install the generated .vsix file
+code --install-extension cursor-guard-ide-4.7.5.vsix
+```
+
+On first activation, the extension automatically:
+- Installs `SKILL.md` to your IDE's skills directory
+- Registers the MCP Server in your IDE's `mcp.json`
+- Creates a default `.cursor-guard.json` if missing
+
+#### Method B: From source (development)
 
 ```bash
-# From the cursor-guard skill directory
 cd references/vscode-extension
-# Install as a development extension in your IDE
 code --install-extension .
 ```
 
@@ -314,10 +330,11 @@ Features:
 - **WebView Dashboard** — full dashboard embedded as an editor tab, identical to the browser version
 - **Status Bar Indicator** — shows `Guard: OK` (green) or `Guard: 22 files!` (yellow) in real-time
 - **Sidebar TreeView** — activity bar icon with project list, watcher status, backup stats, alerts, health
+- **Visual Sidebar** — graphical dashboard with progress bars, status badges, backup timeline in sidebar
 - **Command Palette** — `Cursor Guard: Open Dashboard`, `Snapshot Now`, `Start Watcher`, `Refresh`
-- **Auto-activation** — detects `.cursor-guard.json` in workspace, starts dashboard server automatically
+- **Auto-setup (V4.7.5)** — auto-detects IDE type, installs Skill, registers MCP, creates config on first run
 - **Multi-project** — hot-loads all workspace folders with `.cursor-guard.json`
-- **Compatible** — works with VSCode ^1.74.0, Cursor, Windsurf, and all VSCode-based IDEs
+- **Compatible** — works with VSCode ^1.74.0, Cursor, Windsurf, Trae, and all VSCode-based IDEs
 
 ---
 
@@ -410,10 +427,20 @@ The skill activates on these signals:
 
 ## Changelog
 
-### v4.7.0 — IDE Extension
+### v4.7.5 — VSIX Self-Contained Build + Auto-Setup
+
+- **Feature**: `build-vsix.js` packages all runtime dependencies into a self-contained VSIX — no npm installation needed
+- **Feature**: `auto-setup.js` auto-detects IDE type (Cursor/Windsurf/Trae/VSCode), installs SKILL.md, registers MCP Server, creates default config on first activation
+- **Fix**: `dashboard/server.js` PKG_PATH now dynamically resolved (supports skill dir, VSIX flat, `guard-version.json` fallback)
+- **Enhancement**: Added `onStartupFinished` activation event so auto-setup runs even without `.cursor-guard.json`
+
+### v4.7.0–v4.7.4 — IDE Extension + Bug Fixes
 
 - **Feature**: VSCode/Cursor/Windsurf extension — full dashboard as WebView tab, status bar alert indicator, sidebar TreeView with project status, Command Palette integration
 - **Feature**: Auto-activation on `.cursor-guard.json` detection, dashboard server runs in extension host process (zero subprocess overhead)
+- **Feature**: Visual sidebar dashboard with charts, progress bars, status badges (v4.7.3)
+- **Fix**: Smart path resolver (`paths.js`) for VSIX/skill/npm installation contexts (v4.7.4)
+- **Fix**: WebView CSP, watcher infinite restart, snapshot status handling (v4.7.1–v4.7.4)
 - **Adapt**: `fetchJson()` supports `__GUARD_BASE_URL__` for WebView; `copyText()` bridges to `vscode.env.clipboard` when in IDE
 
 ### v4.6.x — Alert UX Overhaul

package/README.zh-CN.md

@@ -296,16 +296,32 @@ node references\dashboard\server.js --path "D:\MyProject"
 - **安全性** — 仅绑定 `127.0.0.1`（不暴露到局域网）、API 使用项目 ID 而非原始路径、静态文件服务严格限制在 `public/` 目录
 - **零额外依赖** — 使用 Node.js 内置 `http` 模块 + cursor-guard 已有核心模块
 
-### IDE 扩展（VSCode / Cursor）
+### IDE 扩展（VSCode / Cursor / Windsurf）
 
 将完整仪表盘直接嵌入 IDE 内部，无需打开浏览器。
 
-扩展位于 `references/vscode-extension/`。安装方式：
+#### 方式 A：VSIX 独立安装（推荐，无需 npm）
+
+```bash
+# 构建独立 VSIX 包
+cd references/vscode-extension
+node build-vsix.js
+cd dist
+npx vsce package
+
+# 安装生成的 .vsix 文件
+code --install-extension cursor-guard-ide-4.7.5.vsix
+```
+
+首次激活时，扩展自动：
+- 将 `SKILL.md` 安装到 IDE 的 skills 目录
+- 将 MCP Server 注册到 IDE 的 `mcp.json`
+- 创建默认 `.cursor-guard.json` 配置（如不存在）
+
+#### 方式 B：从源码安装（开发模式）
 
 ```bash
-# 从 cursor-guard skill 目录
 cd references/vscode-extension
-# 作为开发扩展安装到 IDE
 code --install-extension .
 ```
 
@@ -314,10 +330,11 @@ code --install-extension .
 - **WebView 仪表盘** — 完整仪表盘作为编辑器标签页嵌入，与浏览器版本完全一致
 - **状态栏指示器** — 实时显示 `Guard: OK`（绿色）或 `Guard: 22 files!`（黄色告警）
 - **侧边栏 TreeView** — Activity Bar 图标，树形展示项目列表、Watcher 状态、备份统计、告警、健康评估
+- **可视化图表侧边栏** — 进度条、状态徽章、备份时间线等图形化展示
 - **命令面板** — `Cursor Guard: Open Dashboard`、`Snapshot Now`、`Start Watcher`、`Refresh`
-- **自动激活** — 检测到工作区有 `.cursor-guard.json` 时自动启动 Dashboard 服务
+- **自动配置（V4.7.5）** — 首次运行自动检测 IDE 类型、安装 Skill、注册 MCP、创建配置
 - **多项目** — 热加载所有包含 `.cursor-guard.json` 的工作区文件夹
-- **兼容性** — 支持 VSCode ^1.74.0、Cursor、Windsurf 及所有基于 VSCode 的 IDE
+- **兼容性** — 支持 VSCode ^1.74.0、Cursor、Windsurf、Trae 及所有基于 VSCode 的 IDE
 
 ---
 
@@ -410,10 +427,19 @@ code --install-extension .
 
 ## 更新日志
 
-### v4.7.0 — IDE 扩展
+### v4.7.5 — VSIX 独立打包 + 自动配置
+
+- **功能**：`build-vsix.js` 将所有运行时依赖打包为独立 VSIX —— 无需 npm 安装
+- **功能**：`auto-setup.js` 首次激活自动检测 IDE 类型（Cursor/Windsurf/Trae/VSCode），安装 SKILL.md，注册 MCP Server，创建默认配置
+- **修复**：`dashboard/server.js` PKG_PATH 改为动态查找（支持 skill 目录、VSIX 扁平、guard-version.json 回退）
+- **增强**：新增 `onStartupFinished` 激活事件，确保无 `.cursor-guard.json` 的项目也能触发自动配置
+
+### v4.7.0–v4.7.4 — IDE 扩展 + Bug 修复
 
 - **功能**：VSCode/Cursor/Windsurf 扩展 — 完整仪表盘作为 WebView 标签页嵌入，状态栏告警指示器，侧边栏 TreeView 项目状态，命令面板集成
-- **功能**：检测到 `.cursor-guard.json` 自动激活，Dashboard 服务在扩展宿主进程内运行（零额外进程开销）
+- **功能**：可视化图表侧边栏 — 进度条、状态徽章、备份时间线（v4.7.3）
+- **修复**：智能路径解析器 `paths.js` 支持 VSIX/skill/npm 多种安装环境（v4.7.4）
+- **修复**：WebView CSP、Watcher 无限重启、快照状态处理（v4.7.1–v4.7.4）
 - **适配**：`fetchJson()` 支持 `__GUARD_BASE_URL__` 用于 WebView；`copyText()` 在 IDE 中通过 `postMessage` 桥接到 `vscode.env.clipboard`
 
 ### v4.6.x — 告警 UX 大优化

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.7.4`  
-> **文档状态**：`V2` ~ `V4.7.4` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
+> **当前版本**：`V4.7.6`  
+> **文档状态**：`V2` ~ `V4.7.6` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -734,6 +734,32 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 }
 ```
 
+### V4.7.6：侧边栏 UX 重构 + Health 修复 + Open Dashboard 修复 ✅
+
+| 修复/增强 | 说明 |
+|----------|------|
+| **Health 阈值逻辑修复** | 移除"Last backup too old"健康警告。Watcher 在跑但无文件变更时不备份是正常行为，不应报警。Health 判定改为：watcher 在跑 + 无磁盘问题 = healthy；watcher 停 = warning；磁盘不足/非 Git = critical |
+| **侧边栏 Dashboard 重构** | 从"报表"改为"仪表盘"：顶部单个大状态指示器（🟢 Protected / 🔴 Alert / 🟡 Watcher Stopped）替代四个小卡片。移除 Recent Backups 列表、Protection Scope 标签、Health Issues 重复区。只保留 Quick Stats（last backup / git backups / disk free）。浮点数取整（49.4 GB 而非 49.356...） |
+| **操作按钮重构** | 2×2 网格布局：📸 Snapshot + ⏪ Restore（一存一取配对），🟢 Watcher Toggle + 🔍 Doctor，📊 Open Dashboard 居中。新增 Quick Restore 命令（QuickPick 选最近 8 条备份）和 Doctor 命令（显示诊断摘要） |
+| **Open Dashboard 修复** | `PUBLIC_DIR` 从模块加载时求值改为懒加载（避免路径解析失败导致整个模块崩溃）；找不到前端文件时 fallback 到浏览器打开；CSP `connect-src` 空值修复 |
+| **新命令** | `cursorGuard.quickRestore`（Quick Restore）、`cursorGuard.doctor`（Run Diagnostics） |
+
+### V4.7.5：VSIX 独立打包 + 自动配置 Skill/MCP ✅
+
+| 组件 | 说明 |
+|------|------|
+| **`build-vsix.js` 打包脚本** | 将所有运行时依赖（dashboard、lib/core、bin、mcp、skill 文件）复制到 `dist/` 扁平结构，自动同步版本号，生成可独立安装的 `.vsix` 包。无需 npm 安装 |
+| **`auto-setup.js` 自动配置** | 插件激活时自动检测 IDE 类型（Cursor/Windsurf/VSCode），将 SKILL.md 安装到对应 skills 目录，将 MCP Server 注册到 mcp.json，创建默认 `.cursor-guard.json` 配置。所有操作不覆盖已有配置 |
+| **IDE 类型检测** | 通过 `vscode.env.appName` 和目录存在性检测 IDE 类型：Cursor → `.cursor/`、Windsurf → `.windsurf/`、Trae → `.trae/`、VSCode → `.vscode/`（预留） |
+| **dashboard/server.js PKG_PATH 修复** | `PKG_PATH` 从硬编码 `../../package.json` 改为动态查找（支持 skill 目录、VSIX 扁平、`guard-version.json` 回退），版本读取失败时安全降级为 `0.0.0` |
+| **激活事件扩展** | 新增 `onStartupFinished` 激活事件，确保在没有 `.cursor-guard.json` 的项目中也能触发自动配置 |
+| **VSIX 独立分发** | 用户只需安装 `.vsix` 文件（或从 Marketplace 安装），无需 npm。打开项目后 Dashboard/Watcher/Skill/MCP 全部自动就绪 |
+
+用户体验流程：
+```
+安装 .vsix → 打开项目 → activate() → 检测 IDE → 安装 SKILL.md → 注册 MCP → 创建配置 → Dashboard 启动 → 就绪
+```
+
 ### V4.7.4：路径解析器 + 4 Bug 修复 ✅
 
 | 修复 | 说明 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "4.7.4",
+  "version": "4.7.6",
   "description": "Protects code from accidental AI overwrite or deletion in Cursor IDE — mandatory pre-write snapshots, review-before-apply, local Git safety net, and deterministic recovery. | 保护代码免受 Cursor AI 代理意外覆写或删除——强制写前快照、预览再执行、本地 Git 安全网、确定性恢复。",
   "keywords": [
     "cursor",

package/references/dashboard/server.js

@@ -24,8 +24,25 @@ function clearGuardCache() {
 }
 
 const PUBLIC_DIR = path.join(__dirname, 'public');
-const PKG_PATH = path.resolve(__dirname, '..', '..', 'package.json');
-let SERVER_VERSION = require('../../package.json').version;
+const PKG_PATH = _findPackageJson(__dirname);
+let SERVER_VERSION = _readVersion(PKG_PATH);
+
+function _findPackageJson(from) {
+  const candidates = [
+    path.resolve(from, '..', '..', 'package.json'),
+    path.resolve(from, '..', 'package.json'),
+    path.resolve(from, '..', 'guard-version.json'),
+  ];
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+  return candidates[0];
+}
+
+function _readVersion(pkgPath) {
+  try { return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version || '0.0.0'; }
+  catch { return '0.0.0'; }
+}
 const DEFAULT_PORT = 3120;
 const MAX_PORT_RETRIES = 10;
 const ALLOWED_HOSTS = /^(127\.0\.0\.1|localhost)(:\d+)?$/;

package/references/lib/core/dashboard.js

@@ -168,14 +168,8 @@ function getDashboard(projectDir) {
     issues.push(`Disk space low (${status.disk.freeGB} GB free)`);
   }
 
-  if (status.lastBackup.git && status.watcher.running) {
-    const lastTs = new Date(status.lastBackup.git.timestamp).getTime();
-    const staleSec = (Date.now() - lastTs) / 1000;
-    const staleThreshold = Math.max(cfg.auto_backup_interval_seconds * 10, 300);
-    if (staleSec > staleThreshold) {
-      issues.push(`Last git backup: ${relativeTime(status.lastBackup.git.timestamp)}`);
-    }
-  }
+  // Last backup time is purely informational — no changes = no backup is normal behavior.
+  // Health warnings should only reflect actionable problems (watcher down, disk full, no repo).
 
   let healthStatus = 'healthy';
   if (issues.length > 0) healthStatus = 'warning';

package/references/vscode-extension/.vscodeignore

@@ -1,4 +1,9 @@
 .vscode/**
-node_modules/**
-*.md
 .gitignore
+build-vsix.js
+dist/**
+*.test.js
+**/*.test.js
+CHANGELOG.md
+!node_modules/@modelcontextprotocol/**
+!node_modules/zod/**

package/references/vscode-extension/build-vsix.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const REFS = path.resolve(__dirname, '..');
+const ROOT = path.resolve(REFS, '..');
+const DIST = path.join(__dirname, 'dist');
+
+const rootPkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf-8'));
+const extPkg = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf-8'));
+
+console.log(`\n  build-vsix: cursor-guard v${rootPkg.version}\n`);
+
+if (fs.existsSync(DIST)) fs.rmSync(DIST, { recursive: true, force: true });
+fs.mkdirSync(DIST, { recursive: true });
+
+const copyMap = [
+  // Extension core
+  { src: 'extension.js' },
+  { src: 'lib', type: 'dir' },
+  { src: 'media', type: 'dir' },
+
+  // Cursor-guard runtime deps (from references/)
+  { src: path.join(REFS, 'dashboard'), dst: 'dashboard', type: 'dir' },
+  { src: path.join(REFS, 'lib', 'core'), dst: path.join('lib', 'core'), type: 'dir' },
+  { src: path.join(REFS, 'lib', 'utils.js'), dst: path.join('lib', 'utils.js') },
+  { src: path.join(REFS, 'lib', 'auto-backup.js'), dst: path.join('lib', 'auto-backup.js') },
+  { src: path.join(REFS, 'lib', 'guard-doctor.js'), dst: path.join('lib', 'guard-doctor.js') },
+  { src: path.join(REFS, 'bin'), dst: 'bin', type: 'dir' },
+  { src: path.join(REFS, 'mcp'), dst: 'mcp', type: 'dir' },
+
+  // Skill files
+  { src: path.join(ROOT, 'SKILL.md'), dst: path.join('skill', 'SKILL.md') },
+  { src: path.join(ROOT, 'ROADMAP.md'), dst: path.join('skill', 'ROADMAP.md') },
+  { src: path.join(REFS, 'cursor-guard.example.json'), dst: path.join('skill', 'cursor-guard.example.json') },
+  { src: path.join(REFS, 'cursor-guard.schema.json'), dst: path.join('skill', 'cursor-guard.schema.json') },
+  { src: path.join(REFS, 'config-reference.md'), dst: path.join('skill', 'config-reference.md') },
+  { src: path.join(REFS, 'config-reference.zh-CN.md'), dst: path.join('skill', 'config-reference.zh-CN.md') },
+  { src: path.join(REFS, 'recovery.md'), dst: path.join('skill', 'recovery.md') },
+];
+
+for (const entry of copyMap) {
+  const src = path.isAbsolute(entry.src) ? entry.src : path.join(__dirname, entry.src);
+  const dst = path.join(DIST, entry.dst || entry.src);
+  if (!fs.existsSync(src)) { console.log(`  SKIP (not found): ${entry.src}`); continue; }
+  fs.mkdirSync(path.dirname(dst), { recursive: true });
+  if (entry.type === 'dir') {
+    copyDir(src, dst);
+  } else {
+    fs.copyFileSync(src, dst);
+  }
+  console.log(`  COPY: ${path.relative(DIST, dst)}`);
+}
+
+// Copy MCP SDK dependencies to vendor/ (not node_modules/ — vsce excludes that)
+const sdkSrc = path.join(ROOT, 'node_modules', '@modelcontextprotocol');
+if (fs.existsSync(sdkSrc)) {
+  const sdkDst = path.join(DIST, 'vendor', '@modelcontextprotocol');
+  copyDir(sdkSrc, sdkDst);
+  console.log('  COPY: vendor/@modelcontextprotocol/');
+}
+const zodSrc = path.join(ROOT, 'node_modules', 'zod');
+if (fs.existsSync(zodSrc)) {
+  copyDir(zodSrc, path.join(DIST, 'vendor', 'zod'));
+  console.log('  COPY: vendor/zod/');
+}
+
+// Generate merged package.json
+extPkg.version = rootPkg.version;
+fs.writeFileSync(path.join(DIST, 'package.json'), JSON.stringify(extPkg, null, 2));
+console.log(`  WRITE: package.json (v${rootPkg.version})`);
+
+// Copy .vscodeignore
+const ignoreFile = path.join(__dirname, '.vscodeignore');
+if (fs.existsSync(ignoreFile)) {
+  fs.copyFileSync(ignoreFile, path.join(DIST, '.vscodeignore'));
+}
+
+// Write a guard-version.json so the extension knows its version
+fs.writeFileSync(path.join(DIST, 'guard-version.json'), JSON.stringify({ version: rootPkg.version }));
+
+console.log(`\n  dist/ ready at: ${DIST}`);
+console.log(`  To build VSIX: cd dist && npx vsce package\n`);
+
+function copyDir(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.name === 'node_modules' || entry.name === '.git') continue;
+    if (entry.name.endsWith('.test.js')) continue;
+    if (entry.isDirectory()) copyDir(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}

package/references/vscode-extension/dist/.vscodeignore

@@ -0,0 +1,9 @@
+.vscode/**
+.gitignore
+build-vsix.js
+dist/**
+*.test.js
+**/*.test.js
+CHANGELOG.md
+!node_modules/@modelcontextprotocol/**
+!node_modules/zod/**

package/references/vscode-extension/dist/bin/cursor-guard-backup.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const { parseArgs } = require('../lib/utils');
+
+const args = parseArgs(process.argv);
+
+if (args.help || args.h) {
+  console.log(`Usage: cursor-guard-backup [options]
+
+Options:
+  --path <dir>       Project directory to watch (default: current dir)
+  --interval <sec>   Override backup interval in seconds
+  --dashboard [port] Start dashboard server alongside watcher (default port: 3120)
+  --help, -h         Show this help message
+  --version, -v      Show version number`);
+  process.exit(0);
+}
+
+if (args.version || args.v) {
+  const pkg = require('../../package.json');
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const targetPath = args.path || '.';
+const interval = parseInt(args.interval, 10) || 0;
+const resolved = path.resolve(targetPath);
+
+const opts = {};
+if (args.dashboard !== undefined) {
+  opts.dashboardPort = (typeof args.dashboard === 'string' && /^\d+$/.test(args.dashboard))
+    ? parseInt(args.dashboard, 10)
+    : 3120;
+}
+
+const { runBackup } = require('../lib/auto-backup');
+runBackup(resolved, interval, opts);

package/references/vscode-extension/dist/bin/cursor-guard-doctor.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const { parseArgs } = require('../lib/utils');
+
+const args = parseArgs(process.argv);
+
+if (args.help || args.h) {
+  console.log(`Usage: cursor-guard-doctor [options]
+
+Options:
+  --path <dir>       Project directory to check (default: current dir)
+  --help, -h         Show this help message
+  --version, -v      Show version number`);
+  process.exit(0);
+}
+
+if (args.version || args.v) {
+  const pkg = require('../../package.json');
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const targetPath = args.path || '.';
+const resolved = path.resolve(targetPath);
+
+const { runDoctor } = require('../lib/guard-doctor');
+const exitCode = runDoctor(resolved);
+process.exit(exitCode);

package/references/vscode-extension/dist/bin/cursor-guard-init.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync } = require('child_process');
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`Usage: cursor-guard-init [options]
+
+Installs cursor-guard skill into your Cursor skills directory, including
+MCP dependencies and .gitignore entries.
+
+Options:
+  --global             Install to ~/.cursor/skills/ (default: project-local)
+  --path <dir>         Project directory (default: current dir)
+  --help, -h           Show this help message
+  --version, -v        Show version number`);
+  process.exit(0);
+}
+
+if (args.includes('--version') || args.includes('-v')) {
+  const pkg = require('../../package.json');
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const isGlobal = args.includes('--global');
+const pathIdx = args.indexOf('--path');
+const projectDir = path.resolve(pathIdx >= 0 && args[pathIdx + 1] ? args[pathIdx + 1] : '.');
+
+const skillSource = path.resolve(__dirname, '../..');
+const skillTarget = isGlobal
+  ? path.join(process.env.USERPROFILE || process.env.HOME || os.homedir(), '.cursor', 'skills', 'cursor-guard')
+  : path.join(projectDir, '.cursor', 'skills', 'cursor-guard');
+
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    if (path.basename(src) === 'node_modules') return;
+    if (path.basename(src) === '.git') return;
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+  } else {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+  }
+}
+
+console.log(`\n  cursor-guard init\n`);
+console.log(`  Source:  ${skillSource}`);
+console.log(`  Target:  ${skillTarget}`);
+console.log(`  Mode:    ${isGlobal ? 'global (~/.cursor/skills/)' : 'project-local (.cursor/skills/)'}\n`);
+
+// Pre-check: warn if .cursor-guard.json already exists (upgrade scenario)
+const configPath = path.join(projectDir, '.cursor-guard.json');
+if (fs.existsSync(configPath)) {
+  console.log('  NOTE: .cursor-guard.json already exists — your config will be preserved.');
+  console.log('        Only skill files will be updated (upgrade mode).\n');
+}
+
+// Step 1: Copy skill files (excluding node_modules and .git)
+console.log('  [1/5] Copying skill files...');
+if (fs.existsSync(skillTarget)) {
+  fs.rmSync(skillTarget, { recursive: true, force: true });
+}
+copyRecursive(skillSource, skillTarget);
+console.log('        Done.');
+
+// Step 2: Install MCP dependencies in skill directory
+console.log('  [2/5] Installing MCP dependencies...');
+try {
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  execFileSync(npmCmd, ['install', '--omit=dev', '--ignore-scripts'], {
+    cwd: skillTarget,
+    stdio: 'pipe',
+  });
+  console.log('        Done.');
+} catch (e) {
+  console.log(`        Warning: npm install failed (${e.message}). MCP tools may not work.`);
+  console.log('        You can fix this later: cd "' + skillTarget + '" ; npm install');
+}
+
+// Step 3: Add .gitignore entries for skill node_modules
+console.log('  [3/5] Updating .gitignore...');
+const gitignorePath = path.join(projectDir, '.gitignore');
+const entries = ['node_modules/', '.cursor/skills/**/node_modules/'];
+let gitignoreUpdated = false;
+if (!isGlobal) {
+  let existing = '';
+  try { existing = fs.readFileSync(gitignorePath, 'utf-8'); } catch { /* doesn't exist */ }
+  const missing = entries.filter(e => !existing.includes(e));
+  if (missing.length > 0) {
+    const newline = existing.endsWith('\n') || !existing ? '' : '\n';
+    fs.appendFileSync(gitignorePath, `${newline}# cursor-guard skill dependencies\n${missing.join('\n')}\n`);
+    gitignoreUpdated = true;
+    console.log('        Added: ' + missing.join(', '));
+  } else {
+    console.log('        Already configured.');
+  }
+} else {
+  console.log('        Skipped (global install, not inside a project).');
+}
+
+// Step 4: Create default config if missing
+console.log('  [4/5] Checking .cursor-guard.json...');
+if (!fs.existsSync(configPath)) {
+  const examplePath = path.join(skillTarget, 'references', 'cursor-guard.example.json');
+  if (fs.existsSync(examplePath)) {
+    fs.copyFileSync(examplePath, configPath);
+    console.log('        Created .cursor-guard.json with default settings.');
+  } else {
+    console.log('        Warning: example config not found, skipping.');
+  }
+} else {
+  console.log('        Already exists — preserved.');
+}
+
+// Step 5: Summary
+console.log('  [5/5] Verifying...');
+const serverExists = fs.existsSync(path.join(skillTarget, 'references', 'mcp', 'server.js'));
+const sdkExists = fs.existsSync(path.join(skillTarget, 'node_modules', '@modelcontextprotocol', 'sdk'));
+const skillMdExists = fs.existsSync(path.join(skillTarget, 'SKILL.md'));
+
+console.log(`        SKILL.md:   ${skillMdExists ? 'OK' : 'MISSING'}`);
+console.log(`        MCP server: ${serverExists ? 'OK' : 'MISSING'}`);
+console.log(`        MCP SDK:    ${sdkExists ? 'OK' : 'MISSING — run npm install in skill dir'}`);
+
+console.log(`\n  Installation complete!\n`);
+
+// Detect git repo and recommend committing
+let isGitRepoDir = false;
+try { isGitRepoDir = fs.existsSync(path.join(projectDir, '.git')); } catch { /* ignore */ }
+if (!isGlobal && isGitRepoDir) {
+  console.log('  ** Important: commit now to prevent restore from reverting the skill **');
+  console.log(`     git add .cursor/ .cursor-guard.json && git commit -m "chore: install cursor-guard"\n`);
+}
+
+console.log('  If MCP was already configured, restart Cursor (or Ctrl+Shift+P ->');
+console.log('     "Developer: Reload Window") to load the updated MCP server.\n');
+console.log('  Next steps:');
+console.log('  1. The skill activates automatically in Cursor Agent conversations.');
+console.log('  2. (Optional) Edit .cursor-guard.json to customize protect/ignore patterns.');
+console.log('  3. (Optional) Enable MCP — add to .cursor/mcp.json:');
+console.log(`     { "mcpServers": { "cursor-guard": { "command": "node", "args": ["${path.join(skillTarget, 'references', 'mcp', 'server.js').replace(/\\/g, '/')}"] } } }`);
+console.log('  4. (Optional) Start auto-backup:');
+console.log(`     npx cursor-guard-backup --path "${projectDir}"\n`);