@node9/proxy 1.0.3 → 1.0.5

package/README.md

@@ -45,12 +45,38 @@ Node9 doesn't just "cut the wire." When a command is blocked, it injects a **Str
 
 ### ⏪ Shadow Git Snapshots (Auto-Undo)
 
-Node9 takes silent, lightweight Git snapshots right before an AI agent is allowed to edit or delete files. If the AI hallucinates and ruins your code, don't waste time manualy fixing it. Just run:
+Node9 takes a silent, lightweight Git snapshot before every AI file edit. If the AI hallucinates and breaks your code, run `node9 undo` to instantly revert — with a full diff preview before anything changes.
 
 ```bash
+# Undo the last AI action (shows diff + asks confirmation)
 node9 undo
+
+# Go back N actions at once
+node9 undo --steps 3
+```
+
+Example output:
+
+```
+⏪  Node9 Undo
+    Tool:  str_replace_based_edit_tool → src/app.ts
+    When:  2m ago
+    Dir:   /home/user/my-project
+
+--- src/app.ts (snapshot)
++++ src/app.ts (current)
+@@ -1,4 +1,6 @@
+-const x = 1;
++const x = 99;
++const y = "hello";
+
+Revert to this snapshot? [y/N]
 ```
 
+Node9 keeps the last 10 snapshots. Snapshots are only taken for file-writing tools (`write_file`, `edit_file`, `str_replace_based_edit_tool`, `create_file`) — not for read-only or shell commands.
+
+Node9 keeps the last 10 snapshots. Snapshots are only taken for file-writing tools (`write_file`, `edit_file`, `str_replace_based_edit_tool`, `create_file`) — not for read-only or shell commands.
+
 ### 🌊 The Resolution Waterfall
 
 Security posture is resolved using a strict 5-tier waterfall:
@@ -69,13 +95,17 @@ Security posture is resolved using a strict 5-tier waterfall:
 npm install -g @node9/proxy
 
 # 1. Setup protection for your favorite agent
-node9 addto claude
+node9 setup           # interactive menu — picks the right agent for you
+node9 addto claude    # or wire directly
 node9 addto gemini
 
 # 2. Initialize your local safety net
 node9 init
 
-# 3. Check your status
+# 3. Verify everything is wired correctly
+node9 doctor
+
+# 4. Check your status
 node9 status
 ```
 
@@ -121,9 +151,64 @@ Rules are **merged additive**—you cannot "un-danger" a word locally if it was
 
 ---
 
-## ⏪ Phase 2: The "Undo" Engine (Coming Soon)
+---
+
+## 🖥️ CLI Reference
+
+| Command                       | Description                                                                           |
+| :---------------------------- | :------------------------------------------------------------------------------------ |
+| `node9 setup`                 | Interactive menu — detects installed agents and wires hooks for you                   |
+| `node9 addto <agent>`         | Wire hooks for a specific agent (`claude`, `gemini`, `cursor`)                        |
+| `node9 init`                  | Create default `~/.node9/config.json`                                                 |
+| `node9 status`                | Show current protection status and active rules                                       |
+| `node9 doctor`                | Health check — verifies binaries, config, credentials, and all agent hooks            |
+| `node9 explain <tool> [args]` | Trace the policy waterfall for a given tool call (dry-run, no approval prompt)        |
+| `node9 undo [--steps N]`      | Revert the last N AI file edits using shadow Git snapshots                            |
+| `node9 check`                 | Called by agent hooks; evaluates a pending tool call and exits 0 (allow) or 1 (block) |
+
+### `node9 doctor`
 
-Node9 is currently building **Shadow Git Snapshots**. When enabled, Node9 takes a silent, lightweight Git snapshot right before an AI agent is allowed to edit or delete files. If the AI hallucinates, you can revert the entire session with one click: `node9 undo`.
+Runs a full self-test and exits 1 if any required check fails:
+
+```
+Node9 Doctor  v1.2.0
+────────────────────────────────────────
+Binaries
+  ✅  Node.js v20.11.0
+  ✅  git version 2.43.0
+
+Configuration
+  ✅  ~/.node9/config.json found and valid
+  ✅  ~/.node9/credentials.json — cloud credentials found
+
+Agent Hooks
+  ✅  Claude Code — PreToolUse hook active
+  ⚠️  Gemini CLI — not configured (optional)
+  ⚠️  Cursor — not configured (optional)
+
+────────────────────────────────────────
+All checks passed ✅
+```
+
+### `node9 explain`
+
+Dry-runs the policy engine and prints exactly which rule (or waterfall tier) would block or allow a given tool call — useful for debugging your config:
+
+```bash
+node9 explain bash '{"command":"rm -rf /tmp/build"}'
+```
+
+```
+Policy Waterfall for: bash
+──────────────────────────────────────────────
+Tier 1 · Cloud Org Policy       SKIP  (no org policy loaded)
+Tier 2 · Dangerous Words        BLOCK ← matched "rm -rf"
+Tier 3 · Path Block             –
+Tier 4 · Inline Exec            –
+Tier 5 · Rule Match             –
+──────────────────────────────────────────────
+Verdict: BLOCK  (dangerous word: rm -rf)
+```
 
 ---