docs: update for hook-first installation mode

## README.md Updates

**Quick Start section:**
- Clear 3-step process: verify → install hook → test
- Prominently recommend `rtk init -g` (hook-first mode)
- Explain 99.5% token savings (2000 → 10 tokens)
- Show alternative modes (--claude-md, local init)

**Configuration section:**
- New comparison table: 4 modes with token costs
- Migration instructions for existing users
- Clarify hook vs CLAUDE.md injection differences

**Auto-Rewrite Hook section:**
- Promote automated install (`rtk init -g`) as primary method
- Keep manual install as fallback
- Add verification step (`rtk init --show`)

## INSTALL.md Updates

**Project Initialization:**
- Recommend global hook-first setup (with rationale)
- Show token savings: 99.5% reduction
- Document local setup as alternative
- Add upgrade/migration guide for existing users

## TROUBLESHOOTING.md Updates

**RTK not working section:**
- Option A: Automated (`rtk init -g`) - recommended
- Option B: Manual install - fallback
- Clarify absolute path requirement in settings.json
- Add verification step

## Fixes Documentation Gaps

Before:
- ❌ No mode comparison
- ❌ No migration guide
- ❌ Manual install only
- ❌ Unclear token impact

After:
- ✅ Clear mode comparison with use cases
- ✅ Automatic migration documented
- ✅ Automated install prioritized
- ✅ Quantified token savings (99.5%)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: FlorianBruniaux

INSTALL.md

@@ -69,17 +69,46 @@ rtk gain  # MUST show token savings, not "command not found"
 
 ## Project Initialization
 
-**For each project where you want to use RTK:**
+### Recommended: Global Hook-First Setup
+
+**Best for: All projects, automatic RTK usage**
+
+```bash
+rtk init -g
+# → Installs hook to ~/.claude/hooks/rtk-rewrite.sh
+# → Creates ~/.claude/RTK.md (10 lines, meta commands only)
+# → Adds @RTK.md reference to ~/.claude/CLAUDE.md
+# → Prints settings.json instructions
+
+# Follow printed instructions to add hook to ~/.claude/settings.json
+# Then restart Claude Code
+
+# Verify installation
+rtk init --show  # Check hook is installed and executable
+```
+
+**Token savings**: ~99.5% reduction (2000 tokens → 10 tokens in context)
+
+### Alternative: Local Project Setup
+
+**Best for: Single project without hook**
 
 ```bash
-# Navigate to project directory
 cd /path/to/your/project
+rtk init  # Creates ./CLAUDE.md with full RTK instructions (137 lines)
+```
 
-# Initialize RTK for this project (creates ./CLAUDE.md)
-rtk init
+**Token savings**: Instructions loaded only for this project
 
-# OR initialize globally (creates ~/CLAUDE.md for all projects)
-rtk init --global
+### Upgrading from Previous Version
+
+If you previously used `rtk init -g` with the old system (137-line injection):
+
+```bash
+rtk init -g  # Automatically migrates to hook-first mode
+# → Removes old 137-line block
+# → Installs hook + RTK.md
+# → Adds @RTK.md reference
 ```
 
 ## Installation Verification

README.md

@@ -93,21 +93,25 @@ Download from [rtk-ai/releases](https://github.com/rtk-ai/rtk/releases):
 ## Quick Start
 
 ```bash
-# Run installation check script (recommended first step)
-bash scripts/check-installation.sh
+# 1. Verify installation
+rtk gain  # Must show token stats, not "command not found"
 
-# OR manually verify correct installation
-rtk gain  # Must show token stats, not error
+# 2. Initialize for Claude Code (RECOMMENDED: hook-first mode)
+rtk init --global
+# → Installs hook + creates slim RTK.md (10 lines, 99.5% token savings)
+# → Follow printed instructions to add hook to ~/.claude/settings.json
 
-# Initialize rtk for Claude Code
-rtk init --global    # Add to ~/.claude/CLAUDE.md (all projects)
-rtk init             # Add to ./CLAUDE.md (this project)
+# 3. Test it works
+rtk git status  # Should show ultra-compact output
+rtk init --show # Verify hook is installed and executable
 
-# Test basic commands
-rtk ls .
-rtk git status
+# Alternative modes:
+# rtk init --global --claude-md  # Legacy: full injection (137 lines)
+# rtk init                       # Local project only (./CLAUDE.md)
 ```
 
+**New in v0.9.5**: Hook-first installation eliminates ~2000 tokens from Claude's context while maintaining full RTK functionality through transparent command rewriting.
+
 ## Global Flags
 
 ```bash
@@ -298,14 +302,24 @@ FAILED: 2/15 tests
 
 ## Configuration
 
-rtk reads from `CLAUDE.md` files to instruct Claude Code to use rtk automatically:
+### Installation Modes
+
+| Command | Scope | Hook | RTK.md | CLAUDE.md | Tokens in Context | Use Case |
+|---------|-------|------|--------|-----------|-------------------|----------|
+| `rtk init -g` | Global | ✅ | ✅ (10 lines) | @RTK.md | ~10 | **Recommended**: All projects, automatic |
+| `rtk init -g --claude-md` | Global | ❌ | ❌ | Full (137 lines) | ~2000 | Legacy compatibility |
+| `rtk init -g --hook-only` | Global | ✅ | ❌ | Nothing | 0 | Minimal setup, hook-only |
+| `rtk init` | Local | ❌ | ❌ | Full (137 lines) | ~2000 | Single project, no hook |
 
 ```bash
-rtk init --show    # Show current configuration
-rtk init           # Create local CLAUDE.md
-rtk init --global  # Create ~/CLAUDE.md
+rtk init --show         # Show current configuration
+rtk init -g             # Install hook + RTK.md (recommended)
+rtk init -g --claude-md # Legacy: full injection into CLAUDE.md
+rtk init                # Local project: full injection into ./CLAUDE.md
 ```
 
+**Migration**: If you previously used `rtk init -g` with the old system (137-line injection), simply re-run `rtk init -g` to automatically migrate to the new hook-first approach.
+
 example of 3 days session:
 ```bash
 📊 RTK Token Savings
@@ -336,13 +350,27 @@ Daily Savings (last 30 days):
 
 The most effective way to use rtk is with the **auto-rewrite hook** for Claude Code. Instead of relying on CLAUDE.md instructions (which subagents may ignore), this hook transparently intercepts Bash commands and rewrites them to their rtk equivalents before execution.
 
-**Result**: 100% rtk adoption across all conversations and subagents, zero token overhead.
+**Result**: 100% rtk adoption across all conversations and subagents, zero token overhead in Claude's context.
 
 ### How It Works
 
 The hook runs as a Claude Code [PreToolUse hook](https://docs.anthropic.com/en/docs/claude-code/hooks). When Claude Code is about to execute a Bash command like `git status`, the hook rewrites it to `rtk git status` before the command reaches the shell. Claude Code never sees the rewrite — it's transparent.
 
-### Global Install (all projects)
+### Quick Install (Automated)
+
+```bash
+rtk init -g
+# → Installs hook to ~/.claude/hooks/rtk-rewrite.sh (with executable permissions)
+# → Creates ~/.claude/RTK.md (10 lines, minimal context footprint)
+# → Adds @RTK.md reference to ~/.claude/CLAUDE.md
+# → Prints settings.json instructions (manual step required)
+
+# Follow the printed instructions to add hook to ~/.claude/settings.json
+```
+
+### Manual Install (Fallback)
+
+If `rtk init -g` doesn't work for your setup:
 
 ```bash
 # 1. Copy the hook script

docs/TROUBLESHOOTING.md

@@ -123,15 +123,28 @@ cat ~/.claude/CLAUDE.md | grep rtk
 cat ./CLAUDE.md | grep rtk
 ```
 
-**4. Optional: Install auto-rewrite hook (recommended):**
+**4. Install auto-rewrite hook (recommended for automatic RTK usage):**
+
+**Option A: Automatic (recommended)**
+```bash
+rtk init -g
+# → Installs hook + RTK.md automatically
+# → Follow printed instructions to add hook to ~/.claude/settings.json
+# → Restart Claude Code
+
+# Verify installation
+rtk init --show  # Should show "✅ Hook: executable, with guards"
+```
+
+**Option B: Manual (fallback)**
 ```bash
 # Copy hook to Claude Code hooks directory
 mkdir -p ~/.claude/hooks
 cp .claude/hooks/rtk-rewrite.sh ~/.claude/hooks/
 chmod +x ~/.claude/hooks/rtk-rewrite.sh
 ```
 
-Then add to `~/.claude/settings.json`:
+Then add to `~/.claude/settings.json` (replace `~` with full path):
 ```json
 {
   "hooks": {
@@ -141,7 +154,7 @@ Then add to `~/.claude/settings.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "~/.claude/hooks/rtk-rewrite.sh"
+            "command": "/Users/yourname/.claude/hooks/rtk-rewrite.sh"
           }
         ]
       }
@@ -150,6 +163,8 @@ Then add to `~/.claude/settings.json`:
 }
 ```
 
+**Note**: Use absolute path in `settings.json`, not `~/.claude/...`
+
 ---
 
 ## Problem: "command not found: rtk" after installation