cursor-guard 1.3.2 → 2.0.2

package/README.md

@@ -19,7 +19,7 @@ When Cursor's AI agent edits your files, there's a risk of accidental overwrites
 - **Deterministic recovery** — Clear priority-ordered recovery paths (Git → shadow copies → conversation context → editor history)
 - **Configurable scope** — Protect only what matters via `.cursor-guard.json`
 - **Secrets filtering** — Sensitive files (`.env`, keys, certificates) are auto-excluded from backups
-- **Auto-backup script** — A PowerShell watcher that periodically snapshots to a dedicated Git branch without disturbing your working tree
+- **Auto-backup script** — A cross-platform watcher (Node.js) that periodically snapshots to a dedicated Git branch without disturbing your working tree
 
 ---
 
@@ -84,14 +84,26 @@ After installation, your directory structure should look like this:
 
 ```
 .cursor/skills/cursor-guard/
-├── SKILL.md                          # AI agent instructions
+├── SKILL.md                            # AI agent instructions
 ├── README.md
+├── README.zh-CN.md
 ├── LICENSE
+├── package.json
 └── references/
-    ├── auto-backup.ps1               # Auto-backup script
-    ├── recovery.md                   # Recovery commands
-    ├── cursor-guard.example.json     # Example config
-    └── cursor-guard.schema.json      # Config schema
+    ├── lib/
+    │   ├── auto-backup.js              # Backup core (Node.js)
+    │   ├── guard-doctor.js             # Health check core
+    │   └── utils.js                    # Shared utilities
+    ├── bin/
+    │   ├── cursor-guard-backup.js      # CLI entry: npx cursor-guard-backup
+    │   └── cursor-guard-doctor.js      # CLI entry: npx cursor-guard-doctor
+    ├── auto-backup.ps1 / .sh           # Thin wrappers
+    ├── guard-doctor.ps1 / .sh
+    ├── recovery.md                     # Recovery commands
+    ├── cursor-guard.example.json       # Example config
+    ├── cursor-guard.schema.json        # Config schema
+    ├── config-reference.md             # Config docs (EN)
+    └── config-reference.zh-CN.md       # Config docs (CN)
 ```
 
 The skill activates automatically when the AI agent detects risky operations or when you mention recovery-related terms. No extra setup needed.
@@ -118,8 +130,8 @@ cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guar
 
 5. **(Optional) Run auto-backup** in a separate terminal:
 
-```powershell
-.\auto-backup.ps1 -Path "D:\MyProject"
+```bash
+npx cursor-guard-backup --path /my/project
 ```
 
 ### Project Configuration
@@ -153,18 +165,32 @@ Regardless of config, you can always override per-request:
 
 ## Auto-Backup Script
 
-Run in a separate terminal while working in Cursor:
+Run in a separate terminal while working in Cursor. Cross-platform — requires Node.js >= 18.
 
-```powershell
-.\auto-backup.ps1 -Path "D:\MyProject"
+```bash
+# Via npx (after npm install)
+npx cursor-guard-backup --path /my/project
+npx cursor-guard-backup --path /my/project --interval 30
+
+# Windows PowerShell
+.\references\auto-backup.ps1 -Path "D:\MyProject"
 
-# Custom interval (default 60s):
-.\auto-backup.ps1 -Path "D:\MyProject" -IntervalSeconds 30
+# macOS / Linux
+./references/auto-backup.sh /my/project
 ```
 
-The script uses Git plumbing commands to snapshot to `cursor-guard/auto-backup` branch — it never switches branches or touches your working index.
+The script uses Git plumbing commands to snapshot to `cursor-guard/auto-backup` branch — it never switches branches or touches your working index. Supports `shadow` mode for non-Git directories.
+
+### Health Check
+
+```bash
+npx cursor-guard-doctor --path /my/project
+
+# Windows: .\references\guard-doctor.ps1 -Path "D:\MyProject"
+# macOS/Linux: ./references/guard-doctor.sh /my/project
+```
 
-> **Note**: Run this script in a separate PowerShell window, NOT inside Cursor's integrated terminal. Cursor's terminal may interfere with Git plumbing commands.
+> **Note**: Run backup/doctor scripts in a separate terminal, NOT inside Cursor's integrated terminal.
 
 ---
 
@@ -229,10 +255,18 @@ The skill activates on these signals:
 | File | Purpose |
 |------|---------|
 | `SKILL.md` | Main skill instructions for the AI agent |
-| `references/auto-backup.ps1` | PowerShell auto-backup watcher script |
+| `references/lib/auto-backup.js` | Auto-backup core logic (Node.js) |
+| `references/lib/guard-doctor.js` | Health check core logic (Node.js) |
+| `references/lib/utils.js` | Shared utilities (config, glob, git, manifest) |
+| `references/bin/cursor-guard-backup.js` | CLI entry: `npx cursor-guard-backup` |
+| `references/bin/cursor-guard-doctor.js` | CLI entry: `npx cursor-guard-doctor` |
+| `references/auto-backup.ps1` / `.sh` | Thin wrappers (Windows / macOS+Linux) |
+| `references/guard-doctor.ps1` / `.sh` | Thin wrappers (Windows / macOS+Linux) |
 | `references/recovery.md` | Recovery command templates |
 | `references/cursor-guard.example.json` | Example project configuration |
 | `references/cursor-guard.schema.json` | JSON Schema for config validation |
+| `references/config-reference.md` | Config field docs (English) |
+| `references/config-reference.zh-CN.md` | Config field docs (Chinese) |
 
 ---
 
@@ -241,15 +275,15 @@ The skill activates on these signals:
 - **Binary files**: Git diffs and snapshots work on text files. Binary files (images, compiled assets) are stored but cannot be meaningfully diffed or partially restored.
 - **Untracked files**: Files never committed to Git cannot be recovered from Git history. Shadow copy (`backup_strategy: "shadow"` or `"both"`) is the only safety net for untracked files.
 - **Concurrent agents**: If multiple AI agent threads write to the same file simultaneously, snapshots cannot prevent race conditions. Avoid parallel edits to the same file.
-- **External tools modifying the index**: Tools that alter Git's index (e.g. other Git GUIs, IDE Git integrations) while `auto-backup.ps1` is running may conflict. The script uses a temporary index to minimize this, but edge cases exist.
+- **External tools modifying the index**: Tools that alter Git's index (e.g. other Git GUIs, IDE Git integrations) while auto-backup is running may conflict. The script uses a temporary index to minimize this, but edge cases exist.
 - **Git worktree**: The auto-backup script supports worktree layouts (`git rev-parse --git-dir`), but has not been tested with all exotic setups (e.g. `--separate-git-dir`).
-- **Cursor terminal interference**: Cursor's integrated terminal injects `--trailer` flags into `git commit` commands, which breaks plumbing commands like `commit-tree`. Always run `auto-backup.ps1` in a **separate PowerShell window**.
+- **Cursor terminal interference**: Cursor's integrated terminal injects `--trailer` flags into `git commit` commands, which breaks plumbing commands like `commit-tree`. Always run auto-backup in a **separate terminal window**.
 - **Large repos**: For very large repositories, `git add -A` in the backup loop may be slow. Use `protect` patterns in `.cursor-guard.json` to narrow scope.
 
 ## Requirements
 
-- **Git** — for primary backup strategy
-- **PowerShell 5.1+** — for auto-backup script (Windows built-in)
+- **Node.js >= 18** — core runtime for backup and health check scripts
+- **Git** — for primary backup strategy (not needed for shadow-only mode)
 - **Cursor IDE** — with Agent mode enabled
 
 ---

package/README.zh-CN.md

@@ -19,7 +19,7 @@
 - **确定性恢复** — 按优先级的恢复路径（Git → 影子拷贝 → 对话上下文 → 编辑器历史）
 - **可配置保护范围** — 通过 `.cursor-guard.json` 配置文件只保护你关心的文件
 - **敏感文件过滤** — `.env`、密钥、证书等敏感文件自动排除备份
-- **自动备份脚本** — 定期快照到独立 Git 分支，不干扰工作区
+- **自动备份脚本** — 跨平台 (Node.js) 定期快照到独立 Git 分支，不干扰工作区
 
 ---
 
@@ -84,14 +84,26 @@ git clone https://github.com/zhangqiang8vipp/cursor-guard.git .cursor/skills/cur
 
 ```
 .cursor/skills/cursor-guard/
-├── SKILL.md                          # AI 代理指令
+├── SKILL.md                            # AI 代理指令
 ├── README.md
+├── README.zh-CN.md
 ├── LICENSE
+├── package.json
 └── references/
-    ├── auto-backup.ps1               # 自动备份脚本
-    ├── recovery.md                   # 恢复命令模板
-    ├── cursor-guard.example.json     # 示例配置
-    └── cursor-guard.schema.json      # 配置 Schema
+    ├── lib/
+    │   ├── auto-backup.js              # 备份核心 (Node.js)
+    │   ├── guard-doctor.js             # 健康检查核心
+    │   └── utils.js                    # 共享工具库
+    ├── bin/
+    │   ├── cursor-guard-backup.js      # CLI 入口：npx cursor-guard-backup
+    │   └── cursor-guard-doctor.js      # CLI 入口：npx cursor-guard-doctor
+    ├── auto-backup.ps1 / .sh           # 薄封装
+    ├── guard-doctor.ps1 / .sh
+    ├── recovery.md                     # 恢复命令模板
+    ├── cursor-guard.example.json       # 示例配置
+    ├── cursor-guard.schema.json        # 配置 Schema
+    ├── config-reference.md             # 配置说明（英文）
+    └── config-reference.zh-CN.md       # 配置说明（中文）
 ```
 
 技能会在 AI 代理检测到高风险操作（文件编辑、删除、重命名）或你提到恢复相关词汇时自动激活。无需其他设置，安装即生效。
@@ -118,8 +130,8 @@ cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guar
 
 5. **（可选）运行自动备份** — 在独立终端运行：
 
-```powershell
-.\auto-backup.ps1 -Path "D:\MyProject"
+```bash
+npx cursor-guard-backup --path /my/project
 ```
 
 ### 项目配置
@@ -153,18 +165,32 @@ cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guar
 
 ## 自动备份脚本
 
-在使用 Cursor 时，在**单独的终端窗口**中运行：
+在使用 Cursor 时，在**单独的终端窗口**中运行。跨平台——需要 Node.js >= 18。
 
-```powershell
-.\auto-backup.ps1 -Path "D:\MyProject"
+```bash
+# 通过 npx（npm 安装后）
+npx cursor-guard-backup --path /my/project
+npx cursor-guard-backup --path /my/project --interval 30
+
+# Windows PowerShell
+.\references\auto-backup.ps1 -Path "D:\MyProject"
 
-# 自定义间隔（默认 60 秒）：
-.\auto-backup.ps1 -Path "D:\MyProject" -IntervalSeconds 30
+# macOS / Linux
+./references/auto-backup.sh /my/project
 ```
 
-脚本使用 Git 底层命令快照到 `cursor-guard/auto-backup` 分支——不会切换分支，也不会影响你的工作索引。
+脚本使用 Git 底层命令快照到 `cursor-guard/auto-backup` 分支——不会切换分支，也不会影响你的工作索引。支持 `shadow` 模式用于非 Git 目录。
+
+### 健康检查
+
+```bash
+npx cursor-guard-doctor --path /my/project
+
+# Windows: .\references\guard-doctor.ps1 -Path "D:\MyProject"
+# macOS/Linux: ./references/guard-doctor.sh /my/project
+```
 
-> **注意**：请在独立的 PowerShell 窗口中运行此脚本，不要在 Cursor 的集成终端中运行，因为 Cursor 终端可能干扰 Git 底层命令。
+> **注意**：请在独立终端窗口中运行备份/检查脚本，不要在 Cursor 集成终端中运行。
 
 ---
 
@@ -229,10 +255,18 @@ cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guar
 | 文件 | 用途 |
 |------|------|
 | `SKILL.md` | AI 代理的主要技能指令 |
-| `references/auto-backup.ps1` | PowerShell 自动备份监控脚本 |
+| `references/lib/auto-backup.js` | 自动备份核心逻辑 (Node.js) |
+| `references/lib/guard-doctor.js` | 健康检查核心逻辑 (Node.js) |
+| `references/lib/utils.js` | 共享工具库（配置、glob、git、manifest） |
+| `references/bin/cursor-guard-backup.js` | CLI 入口：`npx cursor-guard-backup` |
+| `references/bin/cursor-guard-doctor.js` | CLI 入口：`npx cursor-guard-doctor` |
+| `references/auto-backup.ps1` / `.sh` | 薄封装（Windows / macOS+Linux） |
+| `references/guard-doctor.ps1` / `.sh` | 薄封装（Windows / macOS+Linux） |
 | `references/recovery.md` | 恢复命令模板 |
 | `references/cursor-guard.example.json` | 示例项目配置 |
 | `references/cursor-guard.schema.json` | 配置文件的 JSON Schema |
+| `references/config-reference.md` | 配置字段说明（英文） |
+| `references/config-reference.zh-CN.md` | 配置字段说明（中文） |
 
 ---
 
@@ -241,15 +275,15 @@ cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guar
 - **二进制文件**：Git 快照可以存储二进制文件（图片、编译产物），但无法进行有意义的 diff 或部分恢复。
 - **未跟踪文件**：从未提交到 Git 的文件无法从 Git 历史恢复。影子拷贝（`backup_strategy: "shadow"` 或 `"both"`）是未跟踪文件的唯一安全网。
 - **并发 Agent**：如果多个 AI 代理线程同时写入同一文件，快照无法防止竞态条件。请避免并行编辑同一文件。
-- **外部工具修改索引**：在 `auto-backup.ps1` 运行期间，其他修改 Git 索引的工具（如 Git GUI、IDE Git 集成）可能冲突。脚本使用临时索引来最小化风险，但边缘情况仍存在。
+- **外部工具修改索引**：在自动备份运行期间，其他修改 Git 索引的工具（如 Git GUI、IDE Git 集成）可能冲突。脚本使用临时索引来最小化风险，但边缘情况仍存在。
 - **Git worktree**：自动备份脚本支持 worktree 布局（`git rev-parse --git-dir`），但未在所有特殊配置下测试（如 `--separate-git-dir`）。
-- **Cursor 终端干扰**：Cursor 集成终端会向 `git commit` 命令注入 `--trailer` 标志，导致 `commit-tree` 等底层命令异常。请始终在**独立的 PowerShell 窗口**中运行 `auto-backup.ps1`。
+- **Cursor 终端干扰**：Cursor 集成终端会向 `git commit` 命令注入 `--trailer` 标志，导致 `commit-tree` 等底层命令异常。请始终在**独立的终端窗口**中运行自动备份脚本。
 - **大型仓库**：对于非常大的仓库，备份循环中的 `git add -A` 可能较慢。使用 `.cursor-guard.json` 中的 `protect` 模式缩小范围。
 
 ## 环境要求
 
-- **Git** — 主要备份策略
-- **PowerShell 5.1+** — 自动备份脚本（Windows 自带）
+- **Node.js >= 18** — 备份与健康检查脚本的核心运行时
+- **Git** — 主要备份策略（仅影子拷贝模式不需要）
 - **Cursor IDE** — 需启用 Agent 模式
 
 ---

package/SKILL.md

@@ -20,6 +20,7 @@ Use this skill when any of the following appear:
 - **Parallel context**: Multiple repos or branches; unclear which folder is the workspace root.
 - **Recovery asks**: e.g. "改不回来", "丢版本", "回滚", "reflog", "误删", or English equivalents.
 - **Time/version recovery**: e.g. "恢复到5分钟前", "恢复到前3个版本", "回到上一个版本", "restore to 10 minutes ago", "go back 2 versions", "恢复到下午3点的状态".
+- **Health check**: e.g. "guard doctor", "检查备份配置", "自检", "诊断guard", "check guard setup". Run `guard-doctor.ps1` and report results.
 
 If none of the above, do not expand scope; answer normally.
 
@@ -51,7 +52,11 @@ On first trigger in a session, check if the workspace root contains `.cursor-gua
   "pre_restore_backup": "always",
 
   // Retention for shadow copies. mode: "days" | "count" | "size"
-  "retention": { "mode": "days", "days": 30, "max_count": 100, "max_size_mb": 500 }
+  "retention": { "mode": "days", "days": 30, "max_count": 100, "max_size_mb": 500 },
+
+  // Retention for Git auto-backup branch. Disabled by default.
+  // "count": keep N newest commits. "days": keep commits from last N days.
+  "git_retention": { "enabled": false, "mode": "count", "max_count": 200 }
 }
 ```
 
@@ -100,19 +105,22 @@ When the target file of an edit **falls outside the protected scope**, the agent
 Use a **temporary index and dedicated ref** so the user's staged/unstaged state is never touched:
 
 ```bash
+GIT_DIR=$(git rev-parse --git-dir)
+GUARD_IDX="$GIT_DIR/guard-snapshot-index"
+
 # 1. Create temp index from HEAD
-GIT_INDEX_FILE=.git/guard-snapshot-index git read-tree HEAD
+GIT_INDEX_FILE="$GUARD_IDX" git read-tree HEAD
 
 # 2. Stage working-tree files into temp index
-GIT_INDEX_FILE=.git/guard-snapshot-index git add -A
+GIT_INDEX_FILE="$GUARD_IDX" git add -A
 
 # 3. Write tree and create commit on a guard ref (not on the user's branch)
-TREE=$(GIT_INDEX_FILE=.git/guard-snapshot-index git write-tree)
-COMMIT=$(git commit-tree $TREE -p HEAD -m "guard: snapshot before ai edit")
-git update-ref refs/guard/snapshot $COMMIT
+TREE=$(GIT_INDEX_FILE="$GUARD_IDX" git write-tree)
+COMMIT=$(git commit-tree "$TREE" -p HEAD -m "guard: snapshot before ai edit")
+git update-ref refs/guard/snapshot "$COMMIT"
 
 # 4. Cleanup
-rm .git/guard-snapshot-index
+rm -f "$GUARD_IDX"
 ```
 
 **PowerShell equivalent** (for agent Shell calls):
@@ -197,21 +205,24 @@ There are two distinct backup mechanisms. Do not confuse them:
 | | **Git branch snapshot** | **Shadow copy** |
 |---|---|---|
 | **What** | Commits to `cursor-guard/auto-backup` branch via plumbing | File copies to `.cursor-guard-backup/<timestamp>/` |
-| **Who creates** | `auto-backup.ps1` (when `backup_strategy` = `git` or `both`) | `auto-backup.ps1` (when `backup_strategy` = `shadow` or `both`); or the agent manually (§2b) |
-| **Who cleans up** | Manual: `git branch -D cursor-guard/auto-backup` | `auto-backup.ps1` per `retention` config; or manual |
-| **Restore** | `git restore --source=cursor-guard/auto-backup -- <file>` | `Copy-Item ".cursor-guard-backup/<ts>/<file>" "<path>"` |
+| **Who creates** | Auto-backup script (when `backup_strategy` = `git` or `both`) | Auto-backup script (when `backup_strategy` = `shadow` or `both`); or the agent manually (§2b) |
+| **Who cleans up** | `git_retention` config (auto, opt-in); or manual `git branch -D` | `retention` config (auto); or manual |
+| **Restore** | `git restore --source=cursor-guard/auto-backup -- <file>` | Copy file from `.cursor-guard-backup/<ts>/<file>` to original path |
 | **Requires Git** | Yes | No (fallback for non-git repos) |
 
 **Priority order for the agent:**
 
 1. **Guard ref snapshot** (`refs/guard/snapshot`) — agent creates before each high-risk edit using temp index (§2a). Does not pollute user's branch or staging area.
-2. **Git branch auto-backup** (`cursor-guard/auto-backup`) — periodic snapshots by `auto-backup.ps1`.
+2. **Git branch auto-backup** (`cursor-guard/auto-backup`) — periodic snapshots by auto-backup script.
 3. **Shadow copy** (`.cursor-guard-backup/`) — fallback for non-git repos, or as extra insurance when `backup_strategy = "both"`.
 4. **Editor habits** — Ctrl+S frequently; optional extensions are user-configured, mention only if asked.
 
 **Hard default:** Do NOT `git push` unless the user explicitly asks. Scope = **local only**.
 
-**Retention:** The `retention` config in `.cursor-guard.json` controls cleanup of **shadow copy directories** only. Git branch snapshots are not subject to retention; clean them manually (see [references/recovery.md](references/recovery.md)).
+**Retention:**
+- **Shadow copies**: controlled by `retention` in `.cursor-guard.json` (mode: days/count/size).
+- **Git branch**: controlled by `git_retention` in `.cursor-guard.json` (disabled by default; enable with `"enabled": true`, mode: count/days). Safely rebuilds the backup branch as an orphan chain containing only kept snapshots — never touches user history. Run `git gc` to reclaim disk space.
+- See [references/config-reference.md](references/config-reference.md) for full field docs.
 
 ---
 
@@ -359,9 +370,12 @@ Then jump to Step 5.
 
 Use the same temp-index plumbing as §2a to avoid polluting the user's staging area:
 
-**Git repo (preferred):**
+**Git repo (preferred) — timestamped ref stack:**
+
+Each pre-restore snapshot writes to a unique ref `refs/guard/pre-restore/<yyyyMMdd_HHmmss>` so consecutive restores never overwrite each other:
 
 ```powershell
+$ts = Get-Date -Format 'yyyyMMdd_HHmmss'
 $guardIdx = Join-Path (git rev-parse --git-dir) "guard-pre-restore-index"
 $env:GIT_INDEX_FILE = $guardIdx
 
@@ -378,10 +392,16 @@ $env:GIT_INDEX_FILE = $null
 Remove-Item $guardIdx -Force -ErrorAction SilentlyContinue
 
 $commit = git commit-tree $tree -p HEAD -m "guard: preserve current before restore to <target>"
+git update-ref "refs/guard/pre-restore/$ts" $commit
+```
+
+Record the short hash and the ref path. Also update `refs/guard/pre-restore` as an alias pointing to the latest:
+
+```powershell
 git update-ref refs/guard/pre-restore $commit
 ```
 
-Record the short hash and the ref `refs/guard/pre-restore`.
+To list all pre-restore snapshots: `git for-each-ref refs/guard/pre-restore/ --sort=-creatordate --format="%(refname:short) %(creatordate:short) %(objectname:short)"`
 
 **Non-Git fallback (shadow copy):**
 
@@ -404,12 +424,14 @@ If the snapshot fails (e.g. disk full, permission error):
 Before executing restore, tell the user:
 ```
 在恢复前，我已保留当前版本：
-- 备份引用: refs/guard/pre-restore (abc1234)
-- 恢复方式: git restore --source=refs/guard/pre-restore -- <file>
+- 备份引用: refs/guard/pre-restore/20260321_163005 (abc1234)
+- 恢复方式: git restore --source=refs/guard/pre-restore/20260321_163005 -- <file>
+- 历史栈: git for-each-ref refs/guard/pre-restore/ --sort=-creatordate
 
 Current version preserved before restore:
-- Backup ref: refs/guard/pre-restore (abc1234)
-- To undo: git restore --source=refs/guard/pre-restore -- <file>
+- Backup ref: refs/guard/pre-restore/20260321_163005 (abc1234)
+- To undo: git restore --source=refs/guard/pre-restore/20260321_163005 -- <file>
+- History: git for-each-ref refs/guard/pre-restore/ --sort=-creatordate
 ```
 
 ### Step 5: Execute Recovery
@@ -451,11 +473,12 @@ After restoring, always:
 
 ```markdown
 **Cursor Guard — restore status**
-- **Pre-restore backup**: `refs/guard/pre-restore` (`<short-hash>`) or `shadow copy at .cursor-guard-backup/pre-restore-<ts>/` or `skipped (user opted out)` or `skipped (no changes)`
+- **Pre-restore backup**: `refs/guard/pre-restore/<ts>` (`<short-hash>`) or `shadow copy at .cursor-guard-backup/pre-restore-<ts>/` or `skipped (user opted out)` or `skipped (no changes)`
 - **Restored to**: `<target-hash>` / `<target description>`
 - **Scope**: single file `<path>` / N files / entire project
 - **Result**: success / failed
-- **To undo restore**: `git restore --source=refs/guard/pre-restore -- <file>`
+- **To undo restore**: `git restore --source=refs/guard/pre-restore/<ts> -- <file>`
+- **All pre-restore snapshots**: `git for-each-ref refs/guard/pre-restore/ --sort=-creatordate`
 ```
 
 ---
@@ -506,8 +529,29 @@ Skip the block for unrelated turns.
 ## Further Reading
 
 - Recovery commands: [references/recovery.md](references/recovery.md)
-- Auto-backup script: [references/auto-backup.ps1](references/auto-backup.ps1)
+- Auto-backup (Node.js core): [references/lib/auto-backup.js](references/lib/auto-backup.js)
+- Guard doctor (Node.js core): [references/lib/guard-doctor.js](references/lib/guard-doctor.js)
+- Shared utilities: [references/lib/utils.js](references/lib/utils.js)
 - Config JSON Schema: [references/cursor-guard.schema.json](references/cursor-guard.schema.json)
 - Example config: [references/cursor-guard.example.json](references/cursor-guard.example.json)
 - Config field reference (EN): [references/config-reference.md](references/config-reference.md)
 - 配置参数说明（中文）: [references/config-reference.zh-CN.md](references/config-reference.zh-CN.md)
+
+### Running scripts
+
+Cross-platform (requires Node.js >= 18):
+
+```bash
+# Via npx (if installed from npm)
+npx cursor-guard-backup --path /my/project --interval 60
+npx cursor-guard-doctor --path /my/project
+
+# Via thin wrapper (from skill directory)
+# Windows PowerShell:
+.\references\auto-backup.ps1 -Path "D:\MyProject"
+.\references\guard-doctor.ps1 -Path "D:\MyProject"
+
+# macOS / Linux:
+./references/auto-backup.sh /my/project
+./references/guard-doctor.sh /my/project
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "1.3.2",
+  "version": "2.0.2",
   "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",
@@ -10,7 +10,8 @@
     "git-backup",
     "snapshot",
     "recovery",
-    "agent-skill"
+    "agent-skill",
+    "cross-platform"
   ],
   "author": "zhangqiang8vipp",
   "license": "MIT",
@@ -19,6 +20,13 @@
     "url": "https://github.com/zhangqiang8vipp/cursor-guard.git"
   },
   "homepage": "https://github.com/zhangqiang8vipp/cursor-guard",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "cursor-guard-backup": "references/bin/cursor-guard-backup.js",
+    "cursor-guard-doctor": "references/bin/cursor-guard-doctor.js"
+  },
   "files": [
     "SKILL.md",
     "README.md",