feat(init): add --project and --local scope flags

ARCHITECTURE.md

@@ -1050,11 +1050,12 @@ Modules with Exit Code Preservation:
 2. LLM Integration (CLAUDE.md)
    ────────────────────────────
    Locations:
-   • Global: ~/.config/rtk/CLAUDE.md
-   • Local:  ./CLAUDE.md (project-specific)
+   • Global:  ~/.claude/                      (user-wide)
+   • Project: ./.claude/settings.json         (team-shared, committable)
+   • Local:   ./.claude/settings.local.json   (personal, gitignored)
 
    Purpose: Instruct LLM (Claude Code) to use rtk prefix
-   Created by: rtk init [--global]
+   Created by: rtk init [--global | --project | --local]
 
    Template (init.rs:40-60):
    # CLAUDE.md
@@ -1073,11 +1074,13 @@ Modules with Exit Code Preservation:
 │                      rtk init Workflow                                 │
 └────────────────────────────────────────────────────────────────────────┘
 
-$ rtk init [--global]
+$ rtk init [--global | --project | --local]
       ↓
-Check existing CLAUDE.md:
-  • --global? → ~/.config/rtk/CLAUDE.md
-  • else      → ./CLAUDE.md
+Check target location:
+  • --global?  → ~/.claude/
+  • --project? → ./.claude/settings.json       (team-shared, committable)
+  • --local?   → ./.claude/settings.local.json  (personal, gitignored)
+  • (default)  → ./CLAUDE.md
       ↓
       ├─ Exists? → Warn user, ask to overwrite
       └─ Not exists? → Continue

INSTALL.md

@@ -77,12 +77,23 @@ rtk gain  # MUST show token savings, not "command not found"
   ├─ YES → rtk init -g              (recommended)
   │         Hook + RTK.md (~10 tokens in context)
   │         Commands auto-rewritten transparently
+  │         Scope: ~/.claude/ (user-wide)
   │
   ├─ YES, minimal → rtk init -g --hook-only
   │         Hook only, nothing added to CLAUDE.md
   │         Zero tokens in context
   │
-  └─ NO, single project → rtk init
+  ├─ NO, team project → rtk init --project
+  │         Hook + RTK.md in ./.claude/
+  │         Patches ./.claude/settings.json (committed to repo)
+  │         Shared with all team members
+  │
+  ├─ NO, personal per-project → rtk init --local
+  │         Hook + RTK.md in ./.claude/
+  │         Patches ./.claude/settings.local.json (gitignored)
+  │         Only affects you, not committed to repo
+  │
+  └─ NO, legacy → rtk init
             Local CLAUDE.md only (137 lines)
             No hook, no global effect
 ```
@@ -137,9 +148,45 @@ RTK backs up existing settings.json before changes. Restore if needed:
 cp ~/.claude/settings.json.bak ~/.claude/settings.json
 ```
 
-### Alternative: Local Project Setup
+### Alternative: Project-Scope Setup (Team-Shared)
+
+**Best for: Teams that want RTK active for a specific repo**
+
+```bash
+cd /path/to/your/project
+rtk init --project
+# → Installs hook to ./.claude/hooks/rtk-rewrite.sh
+# → Creates ./.claude/RTK.md
+# → Patches ./.claude/settings.json (committed to repo, shared with team)
+
+rtk init --project --auto-patch    # Patch without prompting
+rtk init --project --no-patch      # Print manual instructions instead
+rtk init --project --hook-only     # Hook only, no RTK.md
+```
+
+**Token savings**: Same as global (~99.5%), scoped to this project only
+
+### Alternative: Local-Scope Setup (Personal, Gitignored)
 
-**Best for: Single project without hook**
+**Best for: Personal RTK usage in a project without affecting teammates**
+
+```bash
+cd /path/to/your/project
+rtk init --local
+# → Installs hook to ./.claude/hooks/rtk-rewrite.sh
+# → Creates ./.claude/RTK.md
+# → Patches ./.claude/settings.local.json (gitignored, personal only)
+
+rtk init --local --auto-patch      # Patch without prompting
+rtk init --local --no-patch        # Print manual instructions instead
+rtk init --local --hook-only       # Hook only, no RTK.md
+```
+
+**Token savings**: Same as global (~99.5%), personal to you only
+
+### Alternative: Legacy Local Setup
+
+**Best for: Single project without hook (pre-0.22 style)**
 
 ```bash
 cd /path/to/your/project
@@ -148,6 +195,15 @@ rtk init  # Creates ./CLAUDE.md with full RTK instructions (137 lines)
 
 **Token savings**: Instructions loaded only for this project
 
+### Scope Comparison
+
+| Scope | Flag | Settings file | Shared? | Location |
+|-------|------|---------------|---------|----------|
+| Global | `-g` / `--global` | `~/.claude/settings.json` | User-wide (all projects) | `~/.claude/` |
+| Project | `--project` | `./.claude/settings.json` | Team (committed to repo) | `./.claude/` |
+| Local | `--local` | `./.claude/settings.local.json` | Personal (gitignored) | `./.claude/` |
+| Legacy | _(none)_ | N/A | Project only | `./CLAUDE.md` |
+
 ### Upgrading from Previous Version
 
 #### From old 137-line CLAUDE.md injection (pre-0.22)
@@ -240,22 +296,47 @@ rtk vitest run
 
 ## Uninstalling
 
-### Complete Removal (Global Installations Only)
+### Global Uninstall
 
 ```bash
-# Complete removal (global installations only)
 rtk init -g --uninstall
 
 # What gets removed:
 #   - Hook: ~/.claude/hooks/rtk-rewrite.sh
 #   - Context: ~/.claude/RTK.md
 #   - Reference: @RTK.md line from ~/.claude/CLAUDE.md
-#   - Registration: RTK hook entry from settings.json
+#   - Registration: RTK hook entry from ~/.claude/settings.json
 
 # Restart Claude Code after uninstall
 ```
 
-**For Local Projects**: Manually remove RTK block from `./CLAUDE.md`
+### Project-Scope Uninstall
+
+```bash
+cd /path/to/your/project
+rtk init --project --uninstall
+
+# What gets removed:
+#   - Hook: ./.claude/hooks/rtk-rewrite.sh
+#   - Context: ./.claude/RTK.md
+#   - Registration: RTK hook entry from ./.claude/settings.json
+```
+
+### Local-Scope Uninstall
+
+```bash
+cd /path/to/your/project
+rtk init --local --uninstall
+
+# What gets removed:
+#   - Hook: ./.claude/hooks/rtk-rewrite.sh
+#   - Context: ./.claude/RTK.md
+#   - Registration: RTK hook entry from ./.claude/settings.local.json
+```
+
+### Legacy Local Projects
+
+Manually remove the RTK block from `./CLAUDE.md`.
 
 ### Binary Removal
 

README.md

@@ -100,13 +100,16 @@ rtk gain        # Should show token savings stats
 
 ```bash
 # 1. Install hook for Claude Code (recommended)
-rtk init --global
-# Follow instructions to register in ~/.claude/settings.json
+rtk init --global              # User-wide (~/.claude/settings.json)
+rtk init --project             # Team-shared (.claude/settings.json, committable)
+rtk init --local               # Personal (.claude/settings.local.json, gitignored)
 
 # 2. Restart Claude Code, then test
 git status  # Automatically rewritten to rtk git status
 ```
 
+Three scopes: **global** applies to all projects for the current user, **project** is shared with your team via version control, and **local** is personal to your machine and gitignored.
+
 The hook transparently rewrites commands (e.g., `git status` -> `rtk git status`) before execution. Claude never sees the rewrite, it just gets compressed output.
 
 ## How It Works
@@ -271,7 +274,9 @@ The most effective way to use rtk. The hook transparently intercepts Bash comman
 ### Setup
 
 ```bash
-rtk init -g                 # Install hook + RTK.md (recommended)
+rtk init -g                 # Global: hook + RTK.md in ~/.claude/ (recommended)
+rtk init --project          # Project: hook + RTK.md in ./.claude/ (team-shared)
+rtk init --local            # Local: hook + RTK.md in ./.claude/ (personal, gitignored)
 rtk init -g --auto-patch    # Non-interactive (CI/CD)
 rtk init -g --hook-only     # Hook only, no RTK.md
 rtk init --show             # Verify installation
@@ -338,9 +343,11 @@ FAILED: 2/15 tests
 ### Uninstall
 
 ```bash
-rtk init -g --uninstall     # Remove hook, RTK.md, settings.json entry
-cargo uninstall rtk          # Remove binary
-brew uninstall rtk           # If installed via Homebrew
+rtk init -g --uninstall          # Remove global hook, RTK.md, settings.json entry
+rtk init --project --uninstall   # Remove project-scope RTK artifacts
+rtk init --local --uninstall     # Remove local-scope RTK artifacts
+cargo uninstall rtk              # Remove binary
+brew uninstall rtk               # If installed via Homebrew
 ```
 
 ## Documentation

README_es.md

@@ -77,7 +77,9 @@ rtk gain        # Debe mostrar estadisticas de ahorro
 
 ```bash
 # 1. Instalar hook para Claude Code (recomendado)
-rtk init --global
+rtk init --global            # ~/.claude/ (a nivel de usuario)
+rtk init --project           # ./.claude/settings.json (compartido en equipo, committeable)
+rtk init --local             # ./.claude/settings.local.json (personal, gitignored)
 
 # 2. Reiniciar Claude Code, luego probar
 git status  # Automaticamente reescrito a rtk git status

README_fr.md

@@ -84,8 +84,9 @@ rtk gain        # Doit afficher les statistiques d'economies
 
 ```bash
 # 1. Installer le hook pour Claude Code (recommande)
-rtk init --global
-# Suivre les instructions pour enregistrer dans ~/.claude/settings.json
+rtk init --global            # ~/.claude/ (utilisateur entier)
+rtk init --project           # ./.claude/settings.json (partage en equipe, committable)
+rtk init --local             # ./.claude/settings.local.json (personnel, gitignore)
 
 # 2. Redemarrer Claude Code, puis tester
 git status  # Automatiquement reecrit en rtk git status

README_ja.md

@@ -77,7 +77,9 @@ rtk gain        # トークン節約統計が表示されるはず
 
 ```bash
 # 1. Claude Code 用フックをインストール（推奨）
-rtk init --global
+rtk init --global            # ~/.claude/（ユーザー全体）
+rtk init --project           # ./.claude/settings.json（チーム共有、コミット可能）
+rtk init --local             # ./.claude/settings.local.json（個人用、gitignore対象）
 
 # 2. Claude Code を再起動してテスト
 git status  # 自動的に rtk git status に書き換え

README_ko.md

@@ -77,7 +77,9 @@ rtk gain        # 토큰 절약 통계 표시되어야 함
 
 ```bash
 # 1. Claude Code용 hook 설치 (권장)
-rtk init --global
+rtk init --global            # ~/.claude/ (사용자 전체)
+rtk init --project           # ./.claude/settings.json (팀 공유, 커밋 가능)
+rtk init --local             # ./.claude/settings.local.json (개인용, gitignore 대상)
 
 # 2. Claude Code 재시작 후 테스트
 git status  # 자동으로 rtk git status로 재작성

README_zh.md

@@ -78,7 +78,9 @@ rtk gain        # 应显示 token 节省统计
 
 ```bash
 # 1. 为 Claude Code 安装 hook（推荐）
-rtk init --global
+rtk init --global            # ~/.claude/（用户级别）
+rtk init --project           # ./.claude/settings.json（团队共享，可提交）
+rtk init --local             # ./.claude/settings.local.json（个人使用，gitignore）
 
 # 2. 重启 Claude Code，然后测试
 git status  # 自动重写为 rtk git status

docs/FEATURES.md

@@ -1213,21 +1213,49 @@ Sortie filtree retournee a Claude (~10 tokens vs ~200)
 ### Installation
 
 ```bash
-rtk init -g                     # Installation recommandee (hook + RTK.md)
+# Portees d'installation
+rtk init --global               # ~/.claude/ (user-wide, recommande)
+rtk init --project              # ./.claude/settings.json (team-shared, committable)
+rtk init --local                # ./.claude/settings.local.json (personal, gitignored)
+
+# Raccourcis
+rtk init -g                     # Equivalent de --global
 rtk init -g --auto-patch        # Non-interactif (CI/CD)
 rtk init -g --hook-only         # Hook seul, sans RTK.md
-rtk init --show                 # Verifier l'installation
-rtk init -g --uninstall         # Desinstaller
+
+# Verification et desinstallation
+rtk init --show                 # Verifier l'installation (toutes les portees)
+rtk init -g --uninstall         # Desinstaller (global)
+rtk init --project --uninstall  # Desinstaller (project)
+rtk init --local --uninstall    # Desinstaller (local)
 ```
 
 ### Fichiers installes
 
+**`--global` (user-wide) :**
+
 | Fichier | Description |
 |---------|-------------|
 | `~/.claude/hooks/rtk-rewrite.sh` | Script hook (delegue a `rtk rewrite`) |
 | `~/.claude/RTK.md` | Instructions minimales pour le LLM |
 | `~/.claude/settings.json` | Enregistrement du hook PreToolUse |
 
+**`--project` (team-shared, committable) :**
+
+| Fichier | Description |
+|---------|-------------|
+| `./.claude/hooks/rtk-rewrite.sh` | Script hook (delegue a `rtk rewrite`) |
+| `./.claude/RTK.md` | Instructions minimales pour le LLM |
+| `./.claude/settings.json` | Enregistrement du hook PreToolUse |
+
+**`--local` (personal, gitignored) :**
+
+| Fichier | Description |
+|---------|-------------|
+| `./.claude/hooks/rtk-rewrite.sh` | Script hook (delegue a `rtk rewrite`) |
+| `./.claude/RTK.md` | Instructions minimales pour le LLM |
+| `./.claude/settings.local.json` | Enregistrement du hook PreToolUse (gitignored) |
+
 ### `rtk rewrite` -- Recriture de commande
 
 Commande interne utilisee par le hook. Imprime la commande reecrite sur stdout (exit 0) ou sort avec exit 1 si aucun equivalent RTK n'existe.