@snapback/cli 1.0.10 → 1.1.12

package/README.md

@@ -1,288 +1,155 @@
 # @snapback/cli
 
-**Command-line interface for SnapBack** - AI-safe code snapshots, risk analysis, and intelligent validation.
+> **Git is for commits. SnapBack is for "oh no, what did I just do?"**
 
-## Installation
+[![npm version](https://img.shields.io/npm/v/@snapback/cli.svg)](https://www.npmjs.com/package/@snapback/cli)
+[![npm downloads](https://img.shields.io/npm/dm/@snapback/cli.svg)](https://www.npmjs.com/package/@snapback/cli)
+[![License](https://img.shields.io/npm/l/@snapback/cli.svg)](https://github.com/snapback-dev/snapback/blob/main/LICENSE)
 
-```bash
-# Global installation
-npm install -g @snapback/cli
-
-# Or use via npx
-npx @snapback/cli <command>
-
-# Or with pnpm
-pnpm add -g @snapback/cli
-```
-
-## Quick Start
-
-```bash
-# First-time setup with interactive wizard
-snap wizard
-
-# Initialize SnapBack in your project
-snap init
-
-# Analyze a file for risk
-snap analyze src/auth.ts
-
-# Create a snapshot before risky changes
-snap snapshot -m "Before major refactor"
-
-# Check staged files before commit
-snap check --all
+AI coding assistants like **Cursor**, **GitHub Copilot**, and **Claude** are incredible—until they're not. One wrong autocomplete can cascade into hours of debugging. Git doesn't help because you haven't committed yet.
 
-# Run diagnostics if something seems wrong
-snap doctor
-```
+**SnapBack is your safety net for AI-native development.**
 
-## Commands
+## Why SnapBack?
 
-### Core Commands
+| The Problem | The Solution |
+|-------------|--------------|
+| AI makes a bad change | Automatic snapshots before risky edits |
+| You don't notice until later | Risk analysis flags dangerous patterns |
+| Git history is clean (no commits yet) | One-click recovery with `snap undo` |
+| Same mistake happens again | Learning loop auto-promotes patterns |
+| Works in Cursor but not VS Code | Editor-agnostic protection |
 
-| Command | Description |
-|---------|-------------|
-| `snap init` | Initialize `.snapback/` directory in workspace |
-| `snap analyze <file>` | Risk analysis for a single file |
-| `snap snapshot` | Create a snapshot of current state |
-| `snap list` | List all snapshots |
-| `snap check` | Pre-commit hook to check for risky changes |
+### Key Metrics
 
-### Intelligence Commands
+- ⚡ **<100ms** snapshot creation
+- 🎯 **89%** AI change detection accuracy
+- 🔒 **Privacy-first** — code never leaves your machine
+- 🧠 **Self-improving** — learns from your mistakes automatically
 
-These commands integrate `@snapback/intelligence` for learning loop and validation:
+---
 
-| Command | Description | Example |
-|---------|-------------|---------|
-| `snap context [task]` | Get relevant context before work | `snap context "add auth" -k auth session` |
-| `snap validate <file>` | Run 7-layer validation pipeline | `snap validate src/auth.ts` |
-| `snap validate --all` | Validate all staged files | `snap validate --all --quiet` |
-| `snap stats` | Show learning statistics | `snap stats --json` |
+## Getting Started
 
-### Learning Commands
+SnapBack has two primary interfaces:
 
-| Command | Description |
-|---------|-------------|
-| `snap learn record` | Record a new learning |
-| `snap learn list` | List recorded learnings |
-| `snap patterns report` | Report a violation (auto-promotes at 3x) |
-| `snap patterns summary` | Show violation patterns and status |
+### 🎨 VS Code Extension (Recommended)
 
-### Protection Commands
-
-| Command | Description |
-|---------|-------------|
-| `snap protect add <file>` | Add file to protection list |
-| `snap protect remove <file>` | Remove file from protection |
-| `snap protect list` | List protected files |
-| `snap session start` | Start a coding session |
-| `snap session end` | End current session |
-
-### Utility Commands
-
-| Command | Description |
-|---------|-------------|
-| `snap status` | Show workspace status |
-| `snap fix` | Fix common issues |
-| `snap watch` | Continuous file watching daemon |
-| `snap interactive` | Guided TUI workflow |
-
-### Polish Commands
-
-| Command | Description |
-|---------|-------------|
-| `snap wizard` | Interactive first-run setup wizard |
-| `snap doctor` | Comprehensive diagnostics and health check |
-| `snap doctor --fix` | Auto-fix detected issues |
-| `snap upgrade` | Check for and install CLI updates |
-| `snap upgrade --check` | Only check for updates, don't install |
-| `snap config list` | List all configuration values |
-| `snap config get <key>` | Get a specific config value |
-| `snap config set <key> <value>` | Set a configuration value |
-| `snap config path` | Show config file locations |
-| `snap undo` | Undo the last destructive operation |
-| `snap undo --list` | Show recent undoable operations |
-| `snap alias list` | List command shortcuts |
-| `snap alias set <name> <cmd>` | Create a command alias |
-| `snap alias suggest` | Show recommended aliases |
-
-### MCP Server Command
-
-| Command | Description |
-|---------|-------------|
-| `snap mcp --stdio` | Start MCP server for Cursor/Claude integration |
-
-## World-Class UX Features
-
-SnapBack CLI implements best practices from GitHub CLI, Vercel CLI, and Stripe CLI.
-
-### Smart Error Messages
-
-When something goes wrong, SnapBack suggests fixes:
+The extension provides the best experience with automatic snapshots, visual recovery UI, and real-time risk indicators.
 
 ```
-╭───────────────────────────────────────────────────╮
-│ [ERR_NOT_INIT] Workspace Not Initialized          │
-│                                                   │
-│ This workspace hasn't been set up for SnapBack   │
-│                                                   │
-│ 💡 Suggestion:                                    │
-│    Initialize SnapBack in this directory         │
-│                                                   │
-│ 📋 Try running:                                   │
-│    $ snap init                                    │
-╰───────────────────────────────────────────────────╯
+ext install snapback-vscode
 ```
 
-### Unknown Command Suggestions
+Or search "SnapBack" in the VS Code Extensions marketplace.
 
-Typos are caught with helpful suggestions:
+[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/snapback.snapback-vscode.svg)](https://marketplace.visualstudio.com/items?itemName=snapback.snapback-vscode)
 
-```bash
-$ snap statis
-╭────────────────────────────────╮
-│ Unknown command: statis        │
-│                                │
-│ Did you mean:                  │
-│   $ snap status                │
-│   $ snap stats                 │
-╰────────────────────────────────╯
-```
+### 💻 CLI Tool
 
-### Interactive First-Run Wizard
+For terminal workflows, CI/CD integration, and MCP server setup:
 
 ```bash
-$ snap wizard
-```
-
-Guided 5-step onboarding:
-1. **Authentication** - Browser login or API key
-2. **Workspace Setup** - Auto-detects project type
-3. **Protection Level** - Standard or Strict mode
-4. **MCP Integration** - Configure AI tool integration
-5. **Analytics** - Optional anonymous usage data
-
-### Terminal Hyperlinks
+# Install globally
+npm install -g @snapback/cli
 
-In supported terminals (iTerm2, VS Code, Windows Terminal, Kitty, etc.), SnapBack outputs clickable links:
-- File paths open in your editor
-- Documentation links open in browser
-- Error codes link to troubleshooting guides
+# Or run without installing
+npx @snapback/cli <command>
+```
 
-### Command Aliases
+---
 
-Create shortcuts for common workflows:
+## Quick Start
 
 ```bash
-# Create aliases
-snap alias set st status
-snap alias set ss snapshot
-snap alias set ctx "context --keywords"
+# Interactive setup wizard (recommended for first-time users)
+snap wizard
 
-# Now use them
-snap st        # → snap status
-snap ss -m "before refactor"  # → snap snapshot -m "..."
+# Or quick init
+snap init
 
-# See suggested aliases
-snap alias suggest
-```
+# Analyze a file for risk
+snap analyze src/auth.ts
 
-### Undo Support
+# Create a snapshot before risky changes
+snap snapshot -m "Before auth refactor"
 
-Revert destructive operations:
+# Pre-commit validation
+snap check --all
 
-```bash
-# Undo the last operation
+# Something went wrong? Recover instantly
 snap undo
-
-# View recent operations
-snap undo --list
 ```
 
-### Dry-Run Mode
-
-Preview changes before executing:
-
-```bash
-snap init --dry-run
-```
+---
 
-Shows exactly what files will be created/modified without making changes.
+## MCP Integration (Cursor, Claude, Windsurf)
 
-### Confirmation Prompts
+SnapBack includes an MCP (Model Context Protocol) server that lets AI assistants understand your codebase and create checkpoints.
 
-Destructive operations require confirmation:
-- Standard risk: Simple Y/n prompt
-- High risk: Must type "yes, delete" to confirm
-- Use `--force` to skip (for CI/automation)
+### Quick Setup (Recommended)
 
-### Diagnostics (Doctor Command)
+The CLI can automatically configure MCP for all detected AI tools:
 
 ```bash
-$ snap doctor
-
-🏥 SnapBack Diagnostics
+# Auto-detect and configure all AI tools
+snap tools configure
 
-  ✓ Node.js version      v20.10.0
-  ✓ CLI installation     v0.5.2 (latest)
-  ✓ Global directory     ~/.snapback/ exists
-  ✓ Authentication       Logged in as @user
-  ✓ Workspace           .snapback/ initialized
-  ✓ MCP tools           3 tools configured
-  ✓ Git repository       Clean
-  ✓ Network              API reachable
-
-  All checks passed!
+# Or configure specific tools
+snap tools configure --cursor
+snap tools configure --claude
+snap tools configure --windsurf
 ```
 
-### Shell Completions
+### Manual Setup
 
-Enable tab completion for your shell:
+If you prefer manual configuration or the auto-setup doesn't work, add this to your AI tool's MCP config:
 
-**Bash:**
-```bash
-eval "$(snap completion bash)"
-# Or add to ~/.bashrc
-```
-
-**Zsh:**
-```bash
-eval "$(snap completion zsh)"
-# Or add to ~/.zshrc
-```
+#### Option 1: Using npx (Recommended)
 
-**Fish:**
-```fish
-snap completion fish | source
-# Or save to ~/.config/fish/completions/snap.fish
+```json
+{
+  "mcpServers": {
+    "snapback": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@snapback/cli",
+        "mcp",
+        "--stdio",
+        "--workspace",
+        "/absolute/path/to/your/project"
+      ],
+      "env": {
+        "SNAPBACK_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
 ```
 
-Completion scripts are also available at:
-- `apps/cli/resources/completions/snap.bash`
-- `apps/cli/resources/completions/snap.zsh`
-- `apps/cli/resources/completions/snap.fish`
-
-## MCP Server Integration
-
-SnapBack includes an MCP (Model Context Protocol) server for integration with AI coding assistants like Cursor, Claude Desktop, Windsurf, and others.
+#### Option 2: Using Global Install
 
-### Starting the MCP Server
-
-```bash
-# Start with stdio transport (default)
-snap mcp --stdio
-
-# Specify workspace explicitly
-snap mcp --stdio --workspace /path/to/your/project
-
-# Specify user tier
-snap mcp --stdio --tier pro
+```json
+{
+  "mcpServers": {
+    "snapback": {
+      "command": "snap",
+      "args": [
+        "mcp",
+        "--stdio",
+        "--workspace",
+        "/absolute/path/to/your/project"
+      ],
+      "env": {
+        "SNAPBACK_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
 ```
 
-### Configuration for AI Clients
-
-Add to your MCP client configuration (e.g., `mcp.json` for Qoder, Claude, or Cursor):
+#### Option 3: Using Node Directly
 
 ```json
 {
@@ -290,7 +157,7 @@ Add to your MCP client configuration (e.g., `mcp.json` for Qoder, Claude, or Cur
     "snapback": {
       "command": "node",
       "args": [
-        "/absolute/path/to/apps/cli/dist/index.js",
+        "/absolute/path/to/node_modules/@snapback/cli/dist/index.js",
         "mcp",
         "--stdio",
         "--workspace",
@@ -304,148 +171,300 @@ Add to your MCP client configuration (e.g., `mcp.json` for Qoder, Claude, or Cur
 }
 ```
 
-**Important:** Both the CLI path and workspace path must be **absolute paths**.
+### Config File Locations
+
+| Tool | Config Path |
+|------|-------------|
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
+| **Cursor** | `~/.cursor/mcp.json` |
+| **Windsurf** | `~/.windsurf/mcp.json` |
+| **Continue** | `~/.continue/config.json` |
 
 ### Workspace Requirements
 
-The MCP server validates that the workspace contains at least one of these markers:
+The MCP server requires at least one of these markers in your project:
 
 - `.git/` directory
 - `package.json` file
 - `.snapback/` directory
 
-If validation fails, you'll see:
-```
-[SnapBack MCP] Workspace validation failed: Workspace must contain at least one marker: .git, package.json, or .snapback
+### Verify Setup
+
+```bash
+# Check which tools are configured
+snap tools status
+
+# Validate configurations
+snap tools validate
+
+# Repair broken configs
+snap tools repair
 ```
 
-**Solution:** Ensure the `--workspace` argument points to a valid project root.
+### Available MCP Tools
 
-### Troubleshooting
+Once configured, your AI assistant can use:
 
-| Error | Cause | Solution |
-|-------|-------|----------|
-| `Cannot find module` | Relative path used | Use absolute paths for both CLI and workspace |
-| `Workspace validation failed` | Missing `--workspace` arg | Add `--workspace /path/to/project` to args |
-| `context deadline exceeded` | Server timeout | Check environment variables are set correctly |
+| Tool | Description |
+|------|-------------|
+| `snapback.get_context` | Understand your codebase |
+| `snapback.analyze_risk` | Assess change risks |
+| `snapback.create_checkpoint` | Create safety snapshots (Pro) |
+| `snapback.restore_checkpoint` | Recover from mistakes (Pro) |
 
-### Environment Variables
+---
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `SNAPBACK_API_KEY` | Optional | API key for Pro features |
-| `BETTER_AUTH_SECRET` | Optional | Auth secret (32+ chars) |
-| `DATABASE_URL` | Optional | PostgreSQL connection URL |
-| `REDIS_URL` | Optional | Redis/Upstash URL |
+## How It Compares
 
-## Intelligence Integration
+### vs. Git Stash
 
-The CLI integrates `@snapback/intelligence` to provide the same learning loop and validation capabilities as SnapBack's internal development tools.
+| Feature | Git Stash | SnapBack |
+|---------|-----------|----------|
+| Automatic snapshots | ❌ Manual | ✅ On save |
+| AI change detection | ❌ | ✅ Cursor, Copilot, Claude |
+| Risk analysis | ❌ | ✅ Per-file scoring |
+| Recovery UX | 😬 Arcane | ✅ `snap undo` |
 
-### Pre-Work Context
+### vs. Cursor's Built-in Checkpoints
 
-Get relevant patterns, learnings, and constraints before starting work:
+| Feature | Cursor | SnapBack |
+|---------|--------|----------|
+| Works in any editor | ❌ | ✅ |
+| Risk scoring | ❌ | ✅ |
+| Learning from mistakes | ❌ | ✅ |
+| CLI access | ❌ | ✅ |
+| MCP integration | ❌ | ✅ |
 
-```bash
-# Get context for a task
-snap context "add user authentication"
+### vs. Static Analysis (SonarQube, CodeClimate)
 
-# Include files you'll modify
-snap context "refactor auth" --files src/auth.ts src/session.ts
+| Feature | Static Analysis | SnapBack |
+|---------|-----------------|----------|
+| Local-first | ❌ Cloud | ✅ |
+| AI source detection | ❌ | ✅ |
+| Recovery/snapshots | ❌ | ✅ |
+| Personal learning | ❌ | ✅ |
 
-# Search with specific keywords
-snap context --keywords auth session jwt
+---
 
-# Machine-readable output
-snap context "add auth" --json
-```
+## Commands
 
-**Output:**
-```
-┌─────────────────────────────────────────┐
-│  📋 Context Loaded                       │
-│                                          │
-│  Hard Rules: 12 constraints              │
-│  Patterns: 8 patterns                    │
-│  Learnings: 3 relevant                   │
-│  Violations: 2 to avoid                  │
-└─────────────────────────────────────────┘
-
-Relevant Learnings:
-┌──────────┬──────────────┬─────────────────────────────────┐
-│ Type     │ Trigger      │ Action                          │
-├──────────┼──────────────┼─────────────────────────────────┤
-│ pattern  │ auth         │ Use @snapback/auth package...   │
-└──────────┴──────────────┴─────────────────────────────────┘
-```
+### Core Commands
 
-### Pre-Commit Validation
+| Command | Description |
+|---------|-------------|
+| `snap init` | Initialize `.snapback/` in your workspace |
+| `snap snapshot` | Create a snapshot of current state |
+| `snap analyze <file>` | Risk analysis for a file |
+| `snap check` | Pre-commit validation |
+| `snap list` | List all snapshots |
+| `snap undo` | Revert the last destructive operation |
+| `snap status` | Show workspace status |
+| `snap fix` | Fix common issues |
 
-Run the 7-layer validation pipeline before committing:
+### Authentication Commands
 
-```bash
-# Validate a single file
-snap validate src/auth.ts
+| Command | Description |
+|---------|-------------|
+| `snap login` | OAuth login flow |
+| `snap logout` | Clear credentials |
+| `snap whoami` | Show current user |
 
-# Validate all staged files
-snap validate --all
+### Intelligence Commands
 
-# Quiet mode (only output if issues)
-snap validate --all --quiet
+| Command | Description |
+|---------|-------------|
+| `snap context [task]` | Get relevant patterns before starting work |
+| `snap validate <file>` | Run 7-layer validation pipeline |
+| `snap validate --all` | Validate all staged files |
+| `snap stats` | Show learning statistics |
 
-# JSON output for CI
-snap validate --all --json
-```
+### Learning Commands
 
-**The 7 Validation Layers:**
+| Command | Description |
+|---------|-------------|
+| `snap learn record` | Record a new learning |
+| `snap learn list` | List recorded learnings |
+| `snap patterns report` | Report a violation (auto-promotes at 3×) |
+| `snap patterns summary` | Show violation patterns |
+
+### Protection Commands
+
+| Command | Description |
+|---------|-------------|
+| `snap protect add <file>` | Add file to protection list |
+| `snap protect remove <file>` | Remove from protection |
+| `snap protect list` | List protected files |
+| `snap session start` | Start a coding session |
+| `snap session end` | End current session |
+| `snap watch` | Continuous file watching |
 
-| Layer | Checks |
-|-------|--------|
+### MCP & Tools Commands
+
+| Command | Description |
+|---------|-------------|
+| `snap mcp --stdio` | Start MCP server for AI assistant integration |
+| `snap tools configure` | Auto-setup MCP for detected AI tools |
+| `snap tools configure --cursor` | Configure for Cursor only |
+| `snap tools configure --claude` | Configure for Claude Desktop only |
+| `snap tools configure --windsurf` | Configure for Windsurf only |
+| `snap tools configure --npm` | Use npx mode (recommended for npm users) |
+| `snap tools configure --dev` | Use local development mode |
+| `snap tools status` | Check MCP configuration status |
+| `snap tools validate` | Validate MCP configurations |
+| `snap tools repair` | Repair broken MCP configurations |
+
+### Daemon Commands
+
+| Command | Description |
+|---------|-------------|
+| `snap daemon start` | Start SnapBack daemon |
+| `snap daemon stop` | Stop SnapBack daemon |
+| `snap daemon status` | Check daemon status |
+| `snap daemon restart` | Restart daemon |
+
+### Utility Commands
+
+| Command | Description |
+|---------|-------------|
+| `snap wizard` | Interactive first-run setup |
+| `snap doctor` | Diagnostics and health check |
+| `snap doctor --fix` | Auto-fix detected issues |
+| `snap upgrade` | Check for CLI updates |
+| `snap config list` | List configuration values |
+| `snap config get <key>` | Get a specific config value |
+| `snap config set <key> <value>` | Set a configuration value |
+| `snap alias list` | List command shortcuts |
+| `snap alias set <name> <cmd>` | Create a command alias |
+| `snap interactive` | Guided TUI workflow |
+
+---
+
+## The 7-Layer Validation Pipeline
+
+When you run `snap validate` or `snap check`, SnapBack analyzes your code across seven layers:
+
+| Layer | What It Checks |
+|-------|----------------|
 | **Syntax** | Bracket matching, semicolons |
 | **Types** | `any` usage, `@ts-ignore`, non-null assertions |
 | **Tests** | Vague assertions, 4-path coverage |
 | **Architecture** | Layer boundaries, service bypass |
 | **Security** | Hardcoded secrets, `eval()` |
 | **Dependencies** | Deprecated packages |
-| **Performance** | console.log, sync I/O, await in loops |
+| **Performance** | `console.log`, sync I/O, `await` in loops |
+
+```bash
+# Validate a single file
+snap validate src/auth.ts
 
-### Learning Statistics
+# Validate all staged files (quiet mode for CI)
+snap validate --all --quiet
+
+# JSON output for automation
+snap validate --all --json
+```
 
-Monitor your learning system's health:
+---
+
+## Auto-Promotion: Learning from Mistakes
+
+SnapBack tracks violations and automatically promotes patterns:
+
+| Occurrence | Action |
+|------------|--------|
+| **1×** | Stored in `violations.jsonl` |
+| **3×** | Auto-promoted to `workspace-patterns.json` |
+| **5×** | Marked for automated detection |
 
 ```bash
-snap stats
+# Report a violation manually
+snap patterns report
+
+# View promotion status
+snap patterns summary
+```
+
+---
+
+## World-Class CLI UX
+
+SnapBack implements best practices from GitHub CLI, Vercel CLI, and Stripe CLI.
+
+### Smart Error Messages
+
 ```
+╭───────────────────────────────────────────────────╮
+│ [ERR_NOT_INIT] Workspace Not Initialized          │
+│                                                   │
+│ This workspace hasn't been set up for SnapBack   │
+│                                                   │
+│ 💡 Suggestion:                                    │
+│    Initialize SnapBack in this directory         │
+│                                                   │
+│ 📋 Try running:                                   │
+│    $ snap init                                    │
+╰───────────────────────────────────────────────────╯
+```
+
+### Typo Detection
+
+```
+$ snap statis
+╭────────────────────────────────────────╮
+│ Unknown command: statis                │
+│                                        │
+│ Did you mean:                          │
+│   $ snap status                        │
+│   $ snap stats                         │
+╰────────────────────────────────────────╯
+```
+
+### Command Aliases
+
+```bash
+# Create shortcuts
+snap alias set st status
+snap alias set ss snapshot
+
+# Use them
+snap st
+snap ss -m "checkpoint"
+```
+
+### Dry-Run Mode
+
+```bash
+snap init --dry-run
+# Shows what will be created without making changes
 
-**Output:**
+snap tools configure --dry-run
+# Shows what MCP config would be written
 ```
-┌─────────────────────────────────────────┐
-│  📊 Learning Statistics                  │
-│                                          │
-│  Total Interactions: 142                 │
-│  Feedback Rate: 68%                      │
-│  Accuracy Rate: 94%                      │
-│  Golden Examples: 23                     │
-└─────────────────────────────────────────┘
-
-Violation Patterns:
-┌────────────────────────┬───────┬─────────────────────────┐
-│ Type                   │ Count │ Status                  │
-├────────────────────────┼───────┼─────────────────────────┤
-│ missing-error-handling │ 5     │ 🤖 Ready for automation │
-│ vague-assertion        │ 3     │ 📈 Ready for promotion  │
-└────────────────────────┴───────┴─────────────────────────┘
+
+### Shell Completions
+
+```bash
+# Bash
+eval "$(snap completion bash)"
+
+# Zsh
+eval "$(snap completion zsh)"
+
+# Fish
+snap completion fish | source
 ```
 
-### Auto-Promotion Thresholds
+Completion scripts are also available at:
+
+- `resources/completions/snap.bash`
+- `resources/completions/snap.zsh`
+- `resources/completions/snap.fish`
 
-- **1x seen**: Stored in `violations.jsonl`
-- **3x seen**: Auto-promoted to `workspace-patterns.json`
-- **5x seen**: Marked for automated detection
+---
 
-## Pre-Commit Hook
+## Pre-Commit Hook Integration
 
-Install as a git pre-commit hook:
+### Git Hook
 
 ```bash
 #!/bin/sh
@@ -453,50 +472,46 @@ Install as a git pre-commit hook:
 npx @snapback/cli check --snapshot --quiet
 ```
 
-Or with lefthook (`.lefthook.yml`):
+### Lefthook
 
 ```yaml
+# .lefthook.yml
 pre-commit:
   commands:
-    snapback-check:
+    snapback:
       run: npx @snapback/cli check --all --quiet
 ```
 
-## CI/CD Integration
-
 ### GitHub Actions
 
 ```yaml
 - name: Validate code
-  run: npx @snapback/cli validate --all --json > validation-report.json
+  run: npx @snapback/cli validate --all --json > validation.json
 
 - name: Check for risky changes
   run: npx @snapback/cli check --quiet
 ```
 
-### Exit Codes
-
-- `0`: All checks passed
-- `1`: Issues found (validation failed, risky changes detected)
+---
 
 ## Configuration
 
 ### Workspace Structure
 
-After `snap init`, your workspace will have:
+After `snap init`:
 
 ```
 your-project/
 ├── .snapback/
-│   ├── config.json           # Workspace configuration
-│   ├── vitals.json           # Workspace vitals
-│   ├── constraints.md        # Your project constraints (optional)
+│   ├── config.json              # Workspace config
+│   ├── vitals.json              # Health metrics
+│   ├── constraints.md           # Your rules (optional)
 │   ├── patterns/
-│   │   ├── violations.jsonl  # Tracked violations
-│   │   └── workspace-patterns.json  # Promoted patterns
+│   │   ├── violations.jsonl     # Tracked violations
+│   │   └── workspace-patterns.json
 │   └── learnings/
-│       └── user-learnings.jsonl     # Recorded learnings
-└── .snapbackrc               # CLI configuration
+│       └── user-learnings.jsonl
+└── .snapbackrc                  # CLI config
 ```
 
 ### `.snapbackrc` Options
@@ -510,56 +525,75 @@ your-project/
 }
 ```
 
-## Dependencies
+---
 
-### Core Packages
-- **@snapback/intelligence**: Learning loop, validation pipeline
-- **@snapback/core**: Guardian risk analysis
-- **@snapback/engine**: V2 analysis engine
-- **@snapback/contracts**: Type definitions
+## Diagnostics
 
-### CLI Framework
-- **commander**: CLI framework
-- **chalk**: Terminal styling
-- **boxen**: Box rendering
-- **cli-table3**: Table formatting
-- **ora**: Spinners
-- **inquirer**: Interactive prompts
+```bash
+$ snap doctor
 
-### UX Enhancements
-- Smart error messages with actionable suggestions
-- Levenshtein distance for typo detection
-- OSC 8 terminal hyperlinks
-- Dry-run mode with diff preview
-- Operation history for undo support
-- Command aliases
+🏥 SnapBack Diagnostics
 
-## Development
+  ✓ Node.js version      v20.10.0
+  ✓ CLI installation     v1.0.11 (latest)
+  ✓ Global directory     ~/.snapback/ exists
+  ✓ Authentication       Logged in as @user
+  ✓ Workspace            .snapback/ initialized
+  ✓ MCP tools            3 tools configured
+  ✓ Git repository       Clean
+  ✓ Network              API reachable
 
-```bash
-# Clone the repo
-git clone https://github.com/snapback-dev/snapback.git
-cd snapback
+  All checks passed!
+```
 
-# Install dependencies
-pnpm install
+---
 
-# Build the CLI
-pnpm --filter @snapback/cli build
+## Exit Codes
 
-# Run locally
-node apps/cli/dist/index.js <command>
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Issues found (validation failed, risky changes) |
 
-# Run tests
-pnpm --filter @snapback/cli test
-```
+---
 
 ## Related Packages
 
-- [`@snapback/intelligence`](../../packages/intelligence/README.md) - Learning and validation engine
-- [`@snapback/core`](../../packages/core/README.md) - Core snapshot logic
-- [`@snapback/sdk`](../../packages/sdk/README.md) - SDK for integrations
+### Open Source (npm)
+
+| Package | Description |
+|---------|-------------|
+| [@snapback-oss/sdk](https://www.npmjs.com/package/@snapback-oss/sdk) | Production-ready SDK for code safety systems |
+| [@snapback-oss/contracts](https://www.npmjs.com/package/@snapback-oss/contracts) | Type definitions and schemas |
+| [@snapback-oss/infrastructure](https://www.npmjs.com/package/@snapback-oss/infrastructure) | Storage and logging utilities |
+| [@snapback-oss/events](https://www.npmjs.com/package/@snapback-oss/events) | Event definitions and handlers |
+
+### VS Code Extension
+
+| Package | Description |
+|---------|-------------|
+| [snapback-vscode](https://marketplace.visualstudio.com/items?itemName=snapback.snapback-vscode) | VS Code extension with visual UI |
+
+---
+
+## Get an API Key
+
+Unlock Pro features like checkpoint creation and restoration:
+
+👉 **[console.snapback.dev/settings/api-keys](https://console.snapback.dev/settings/api-keys)**
+
+---
 
 ## License
 
-Apache-2.0
+[Apache-2.0](https://github.com/snapback-dev/snapback/blob/main/LICENSE)
+
+---
+
+<p align="center">
+  <strong>Stop losing work to AI mistakes.</strong><br>
+  <a href="https://snapback.dev">Website</a> ·
+  <a href="https://docs.snapback.dev">Docs</a> ·
+  <a href="https://console.snapback.dev">Dashboard</a> ·
+  <a href="https://discord.gg/snapback">Discord</a>
+</p>