@hasna/terminal 2.2.0 → 2.3.0

package/temp/rtk/docs/FEATURES.md

@@ -0,0 +1,1410 @@
+# RTK - Documentation fonctionnelle complete
+
+> **rtk (Rust Token Killer)** -- Proxy CLI haute performance qui reduit la consommation de tokens LLM de 60 a 90%.
+
+Binaire Rust unique, zero dependances externes, overhead < 10ms par commande.
+
+---
+
+## Table des matieres
+
+1. [Vue d'ensemble](#vue-densemble)
+2. [Drapeaux globaux](#drapeaux-globaux)
+3. [Commandes Fichiers](#commandes-fichiers)
+4. [Commandes Git](#commandes-git)
+5. [Commandes GitHub CLI](#commandes-github-cli)
+6. [Commandes Test](#commandes-test)
+7. [Commandes Build et Lint](#commandes-build-et-lint)
+8. [Commandes Formatage](#commandes-formatage)
+9. [Gestionnaires de paquets](#gestionnaires-de-paquets)
+10. [Conteneurs et orchestration](#conteneurs-et-orchestration)
+11. [Donnees et reseau](#donnees-et-reseau)
+12. [Cloud et bases de donnees](#cloud-et-bases-de-donnees)
+13. [Stacked PRs (Graphite)](#stacked-prs-graphite)
+14. [Analytique et suivi](#analytique-et-suivi)
+15. [Systeme de hooks](#systeme-de-hooks)
+16. [Configuration](#configuration)
+17. [Systeme Tee (recuperation de sortie)](#systeme-tee)
+18. [Telemetrie](#telemetrie)
+
+---
+
+## Vue d'ensemble
+
+rtk agit comme un proxy entre un LLM (Claude Code, Gemini CLI, etc.) et les commandes systeme. Quatre strategies de filtrage sont appliquees selon le type de commande :
+
+| Strategie | Description | Exemple |
+|-----------|-------------|---------|
+| **Filtrage intelligent** | Supprime le bruit (commentaires, espaces, boilerplate) | `ls -la` -> arbre compact |
+| **Regroupement** | Agregation par repertoire, par type d'erreur, par regle | Tests groupes par fichier |
+| **Troncature** | Conserve le contexte pertinent, supprime la redondance | Diff condense |
+| **Deduplication** | Fusionne les lignes de log repetees avec compteurs | `error x42` |
+
+### Mecanisme de fallback
+
+Si rtk ne reconnait pas une sous-commande, il execute la commande brute (passthrough) et enregistre l'evenement dans la base de suivi. Cela garantit que rtk est **toujours sur** a utiliser -- aucune commande ne sera bloquee.
+
+---
+
+## Drapeaux globaux
+
+Ces drapeaux s'appliquent a **toutes** les sous-commandes :
+
+| Drapeau | Court | Description |
+|---------|-------|-------------|
+| `--verbose` | `-v` | Augmenter la verbosite (-v, -vv, -vvv). Montre les details de filtrage. |
+| `--ultra-compact` | `-u` | Mode ultra-compact : icones ASCII, format inline. Economies supplementaires. |
+| `--skip-env` | -- | Definit `SKIP_ENV_VALIDATION=1` pour les processus enfants (Next.js, tsc, lint, prisma). |
+
+**Exemples :**
+
+```bash
+rtk -v git status          # Status compact + details de filtrage sur stderr
+rtk -vvv cargo test        # Verbosite maximale (debug)
+rtk -u git log             # Log ultra-compact, icones ASCII
+rtk --skip-env next build  # Desactive la validation d'env de Next.js
+```
+
+---
+
+## Commandes Fichiers
+
+### `rtk ls` -- Listage de repertoire
+
+**Objectif :** Remplace `ls` et `tree` avec une sortie optimisee en tokens.
+
+**Syntaxe :**
+```bash
+rtk ls [args...]
+```
+
+Tous les drapeaux natifs de `ls` sont supportes (`-l`, `-a`, `-h`, `-R`, etc.).
+
+**Economies :** ~80% de reduction de tokens
+
+**Avant / Apres :**
+```
+# ls -la (45 lignes, ~800 tokens)          # rtk ls (12 lignes, ~150 tokens)
+drwxr-xr-x  15 user staff 480 ...          my-project/
+-rw-r--r--   1 user staff 1234 ...          +-- src/ (8 files)
+-rw-r--r--   1 user staff 567 ...           |   +-- main.rs
+...40 lignes de plus...                     +-- Cargo.toml
+                                            +-- README.md
+```
+
+---
+
+### `rtk tree` -- Arbre de repertoire
+
+**Objectif :** Proxy vers `tree` natif avec sortie filtree.
+
+**Syntaxe :**
+```bash
+rtk tree [args...]
+```
+
+Supporte tous les drapeaux natifs de `tree` (`-L`, `-d`, `-a`, etc.).
+
+**Economies :** ~80%
+
+---
+
+### `rtk read` -- Lecture de fichier
+
+**Objectif :** Remplace `cat`, `head`, `tail` avec un filtrage intelligent du contenu.
+
+**Syntaxe :**
+```bash
+rtk read <fichier> [options]
+rtk read - [options]          # Lecture depuis stdin
+```
+
+**Options :**
+
+| Option | Court | Defaut | Description |
+|--------|-------|--------|-------------|
+| `--level` | `-l` | `minimal` | Niveau de filtrage : `none`, `minimal`, `aggressive` |
+| `--max-lines` | `-m` | illimite | Nombre maximum de lignes |
+| `--line-numbers` | `-n` | non | Afficher les numeros de ligne |
+
+**Niveaux de filtrage :**
+
+| Niveau | Description | Economies |
+|--------|-------------|-----------|
+| `none` | Aucun filtrage, sortie brute | 0% |
+| `minimal` | Supprime commentaires et lignes vides excessives | ~30% |
+| `aggressive` | Signatures uniquement (supprime les corps de fonctions) | ~74% |
+
+**Avant / Apres (mode aggressive) :**
+```
+# cat main.rs (~200 lignes)                # rtk read main.rs -l aggressive (~50 lignes)
+fn main() -> Result<()> {                   fn main() -> Result<()> { ... }
+    let config = Config::load()?;           fn process_data(input: &str) -> Vec<u8> { ... }
+    let data = process_data(&input);        struct Config { ... }
+    for item in data {                      impl Config { fn load() -> Result<Self> { ... } }
+        println!("{}", item);
+    }
+    Ok(())
+}
+...
+```
+
+**Langages supportes pour le filtrage :** Rust, Python, JavaScript, TypeScript, Go, C, C++, Java, Ruby, Shell.
+
+---
+
+### `rtk smart` -- Resume heuristique
+
+**Objectif :** Genere un resume technique de 2 lignes pour un fichier source.
+
+**Syntaxe :**
+```bash
+rtk smart <fichier> [--model heuristic] [--force-download]
+```
+
+**Economies :** ~95%
+
+**Exemple :**
+```
+$ rtk smart src/tracking.rs
+SQLite-based token tracking system for command executions.
+Records input/output tokens, savings %, execution times with 90-day retention.
+```
+
+---
+
+### `rtk find` -- Recherche de fichiers
+
+**Objectif :** Remplace `find` et `fd` avec une sortie compacte groupee par repertoire.
+
+**Syntaxe :**
+```bash
+rtk find [args...]
+```
+
+Supporte a la fois la syntaxe RTK et la syntaxe native `find` (`-name`, `-type`, etc.).
+
+**Economies :** ~80%
+
+**Avant / Apres :**
+```
+# find . -name "*.rs" (30 lignes)           # rtk find "*.rs" . (8 lignes)
+./src/main.rs                                src/ (12 .rs)
+./src/git.rs                                   main.rs, git.rs, config.rs
+./src/config.rs                                tracking.rs, filter.rs, utils.rs
+./src/tracking.rs                              ...6 more
+./src/filter.rs                              tests/ (3 .rs)
+./src/utils.rs                                 test_git.rs, test_ls.rs, test_filter.rs
+...24 lignes de plus...
+```
+
+---
+
+### `rtk grep` -- Recherche dans le contenu
+
+**Objectif :** Remplace `grep` et `rg` avec une sortie groupee par fichier, tronquee.
+
+**Syntaxe :**
+```bash
+rtk grep <pattern> [chemin] [options]
+```
+
+**Options :**
+
+| Option | Court | Defaut | Description |
+|--------|-------|--------|-------------|
+| `--max-len` | `-l` | 80 | Longueur maximale de ligne |
+| `--max` | `-m` | 50 | Nombre maximum de resultats |
+| `--context-only` | `-c` | non | Afficher uniquement le contexte du match |
+| `--file-type` | `-t` | tous | Filtrer par type (ts, py, rust, etc.) |
+| `--line-numbers` | `-n` | oui | Numeros de ligne (toujours actif) |
+
+Les arguments supplementaires sont transmis a `rg` (ripgrep).
+
+**Economies :** ~80%
+
+**Avant / Apres :**
+```
+# rg "fn run" (20 lignes)                   # rtk grep "fn run" (10 lignes)
+src/git.rs:45:pub fn run(...)                src/git.rs
+src/git.rs:120:fn run_status(...)              45: pub fn run(...)
+src/ls.rs:12:pub fn run(...)                   120: fn run_status(...)
+src/ls.rs:25:fn run_tree(...)                src/ls.rs
+...                                            12: pub fn run(...)
+                                               25: fn run_tree(...)
+```
+
+---
+
+### `rtk diff` -- Diff condense
+
+**Objectif :** Diff ultra-condense entre deux fichiers (uniquement les lignes modifiees).
+
+**Syntaxe :**
+```bash
+rtk diff <fichier1> <fichier2>
+rtk diff <fichier1>              # Stdin comme second fichier
+```
+
+**Economies :** ~60%
+
+---
+
+### `rtk wc` -- Comptage compact
+
+**Objectif :** Remplace `wc` avec une sortie compacte (supprime les chemins et le padding).
+
+**Syntaxe :**
+```bash
+rtk wc [args...]
+```
+
+Supporte tous les drapeaux natifs de `wc` (`-l`, `-w`, `-c`, etc.).
+
+---
+
+## Commandes Git
+
+### Vue d'ensemble
+
+Toutes les sous-commandes git sont supportees. Les commandes non reconnues sont transmises directement a git (passthrough).
+
+**Options globales git :**
+
+| Option | Description |
+|--------|-------------|
+| `-C <path>` | Changer de repertoire avant execution |
+| `-c <key=value>` | Surcharger une config git |
+| `--git-dir <path>` | Chemin vers le repertoire .git |
+| `--work-tree <path>` | Chemin vers le working tree |
+| `--no-pager` | Desactiver le pager |
+| `--no-optional-locks` | Ignorer les locks optionnels |
+| `--bare` | Traiter comme repo bare |
+| `--literal-pathspecs` | Pathspecs literals |
+
+---
+
+### `rtk git status` -- Status compact
+
+**Economies :** ~80%
+
+```bash
+rtk git status [args...]    # Supporte tous les drapeaux git status
+```
+
+**Avant / Apres :**
+```
+# git status (~20 lignes, ~400 tokens)      # rtk git status (~5 lignes, ~80 tokens)
+On branch main                               main | 3M 1? 1A
+Your branch is up to date with               M src/main.rs
+  'origin/main'.                              M src/git.rs
+                                              M tests/test_git.rs
+Changes not staged for commit:                ? new_file.txt
+  (use "git add <file>..." to update)        A staged_file.rs
+  modified:   src/main.rs
+  modified:   src/git.rs
+  ...
+```
+
+---
+
+### `rtk git log` -- Historique compact
+
+**Economies :** ~80%
+
+```bash
+rtk git log [args...]    # Supporte --oneline, --graph, --all, -n, etc.
+```
+
+**Avant / Apres :**
+```
+# git log (50+ lignes)                      # rtk git log -n 5 (5 lignes)
+commit abc123def... (HEAD -> main)           abc123 Fix token counting bug
+Author: User <user@email.com>               def456 Add vitest support
+Date:   Mon Jan 15 10:30:00 2024            789abc Refactor filter engine
+                                             012def Update README
+    Fix token counting bug                   345ghi Initial commit
+...
+```
+
+---
+
+### `rtk git diff` -- Diff compact
+
+**Economies :** ~75%
+
+```bash
+rtk git diff [args...]    # Supporte --stat, --cached, --staged, etc.
+```
+
+**Avant / Apres :**
+```
+# git diff (~100 lignes)                    # rtk git diff (~25 lignes)
+diff --git a/src/main.rs b/src/main.rs      src/main.rs (+5/-2)
+index abc123..def456 100644                    +  let config = Config::load()?;
+--- a/src/main.rs                              +  config.validate()?;
++++ b/src/main.rs                              -  // old code
+@@ -10,6 +10,8 @@                              -  let x = 42;
+   fn main() {                               src/git.rs (+1/-1)
++    let config = Config::load()?;              ~  format!("ok {}", branch)
+...30 lignes de headers et contexte...
+```
+
+---
+
+### `rtk git show` -- Show compact
+
+**Economies :** ~80%
+
+```bash
+rtk git show [args...]
+```
+
+Affiche le resume du commit + stat + diff compact.
+
+---
+
+### `rtk git add` -- Add ultra-compact
+
+**Economies :** ~92%
+
+```bash
+rtk git add [args...]    # Supporte -A, -p, --all, etc.
+```
+
+**Sortie :** `ok` (un seul mot)
+
+---
+
+### `rtk git commit` -- Commit ultra-compact
+
+**Economies :** ~92%
+
+```bash
+rtk git commit -m "message" [args...]    # Supporte -a, --amend, --allow-empty, etc.
+```
+
+**Sortie :** `ok abc1234` (confirmation + hash court)
+
+---
+
+### `rtk git push` -- Push ultra-compact
+
+**Economies :** ~92%
+
+```bash
+rtk git push [args...]    # Supporte -u, remote, branch, etc.
+```
+
+**Avant / Apres :**
+```
+# git push (15 lignes, ~200 tokens)         # rtk git push (1 ligne, ~10 tokens)
+Enumerating objects: 5, done.                ok main
+Counting objects: 100% (5/5), done.
+Delta compression using up to 8 threads
+...
+```
+
+---
+
+### `rtk git pull` -- Pull ultra-compact
+
+**Economies :** ~92%
+
+```bash
+rtk git pull [args...]
+```
+
+**Sortie :** `ok 3 files +10 -2`
+
+---
+
+### `rtk git branch` -- Branches compact
+
+```bash
+rtk git branch [args...]    # Supporte -d, -D, -m, etc.
+```
+
+Affiche branche courante, branches locales, branches distantes de facon compacte.
+
+---
+
+### `rtk git fetch` -- Fetch compact
+
+```bash
+rtk git fetch [args...]
+```
+
+**Sortie :** `ok fetched (N new refs)`
+
+---
+
+### `rtk git stash` -- Stash compact
+
+```bash
+rtk git stash [list|show|pop|apply|drop|push] [args...]
+```
+
+---
+
+### `rtk git worktree` -- Worktree compact
+
+```bash
+rtk git worktree [add|remove|prune|list] [args...]
+```
+
+---
+
+### Passthrough git
+
+Toute sous-commande git non listee ci-dessus est executee directement :
+
+```bash
+rtk git rebase main        # Execute git rebase main
+rtk git cherry-pick abc    # Execute git cherry-pick abc
+rtk git tag v1.0.0         # Execute git tag v1.0.0
+```
+
+---
+
+## Commandes GitHub CLI
+
+### `rtk gh` -- GitHub CLI compact
+
+**Objectif :** Remplace `gh` avec une sortie optimisee.
+
+**Syntaxe :**
+```bash
+rtk gh <sous-commande> [args...]
+```
+
+**Sous-commandes supportees :**
+
+| Commande | Description | Economies |
+|----------|-------------|-----------|
+| `rtk gh pr list` | Liste des PRs compacte | ~80% |
+| `rtk gh pr view <num>` | Details d'une PR + checks | ~87% |
+| `rtk gh pr checks` | Status des checks CI | ~79% |
+| `rtk gh issue list` | Liste des issues compacte | ~80% |
+| `rtk gh run list` | Status des workflow runs | ~82% |
+| `rtk gh api <endpoint>` | Reponse API compacte | ~26% |
+
+**Avant / Apres :**
+```
+# gh pr list (~30 lignes)                   # rtk gh pr list (~10 lignes)
+Showing 10 of 15 pull requests in org/repo   #42 feat: add vitest (open, 2d)
+                                              #41 fix: git diff crash (open, 3d)
+#42  feat: add vitest support                 #40 chore: update deps (merged, 5d)
+  user opened about 2 days ago                #39 docs: add guide (merged, 1w)
+  ... labels: enhancement
+...
+```
+
+---
+
+## Commandes Test
+
+### `rtk test` -- Wrapper de tests generique
+
+**Objectif :** Execute n'importe quelle commande de test et affiche uniquement les echecs.
+
+**Syntaxe :**
+```bash
+rtk test <commande...>
+```
+
+**Economies :** ~90%
+
+**Exemple :**
+```bash
+rtk test cargo test
+rtk test npm test
+rtk test bun test
+rtk test pytest
+```
+
+**Avant / Apres :**
+```
+# cargo test (200+ lignes en cas d'echec)   # rtk test cargo test (~20 lignes)
+running 15 tests                             FAILED: 2/15 tests
+test utils::test_parse ... ok                  test_edge_case: assertion failed
+test utils::test_format ... ok                 test_overflow: panic at utils.rs:18
+test utils::test_edge_case ... FAILED
+...150 lignes de backtrace...
+```
+
+---
+
+### `rtk err` -- Erreurs/avertissements uniquement
+
+**Objectif :** Execute une commande et ne montre que les erreurs et avertissements.
+
+**Syntaxe :**
+```bash
+rtk err <commande...>
+```
+
+**Economies :** ~80%
+
+**Exemple :**
+```bash
+rtk err npm run build
+rtk err cargo build
+```
+
+---
+
+### `rtk cargo test` -- Tests Rust
+
+**Economies :** ~90%
+
+```bash
+rtk cargo test [args...]
+```
+
+N'affiche que les echecs. Supporte tous les arguments de `cargo test`.
+
+---
+
+### `rtk cargo nextest` -- Tests Rust (nextest)
+
+```bash
+rtk cargo nextest [run|list|--lib] [args...]
+```
+
+Filtre la sortie de `cargo nextest` pour n'afficher que les echecs.
+
+---
+
+### `rtk vitest run` -- Tests Vitest
+
+**Economies :** ~99.5%
+
+```bash
+rtk vitest run [args...]
+```
+
+---
+
+### `rtk playwright test` -- Tests E2E Playwright
+
+**Economies :** ~94%
+
+```bash
+rtk playwright [args...]
+```
+
+---
+
+### `rtk pytest` -- Tests Python
+
+**Economies :** ~90%
+
+```bash
+rtk pytest [args...]
+```
+
+---
+
+### `rtk go test` -- Tests Go
+
+**Economies :** ~90%
+
+```bash
+rtk go test [args...]
+```
+
+Utilise le streaming JSON NDJSON de Go pour un filtrage precis.
+
+---
+
+## Commandes Build et Lint
+
+### `rtk cargo build` -- Build Rust
+
+**Economies :** ~80%
+
+```bash
+rtk cargo build [args...]
+```
+
+Supprime les lignes "Compiling...", ne conserve que les erreurs et le resultat final.
+
+---
+
+### `rtk cargo check` -- Check Rust
+
+**Economies :** ~80%
+
+```bash
+rtk cargo check [args...]
+```
+
+Supprime les lignes "Checking...", ne conserve que les erreurs.
+
+---
+
+### `rtk cargo clippy` -- Clippy Rust
+
+**Economies :** ~80%
+
+```bash
+rtk cargo clippy [args...]
+```
+
+Regroupe les avertissements par regle de lint.
+
+---
+
+### `rtk cargo install` -- Install Rust
+
+```bash
+rtk cargo install [args...]
+```
+
+Supprime la compilation des dependances, ne conserve que le resultat d'installation et les erreurs.
+
+---
+
+### `rtk tsc` -- TypeScript Compiler
+
+**Economies :** ~83%
+
+```bash
+rtk tsc [args...]
+```
+
+Regroupe les erreurs TypeScript par fichier et par code d'erreur.
+
+**Avant / Apres :**
+```
+# tsc --noEmit (50 lignes)                  # rtk tsc (15 lignes)
+src/api.ts(12,5): error TS2345: ...          src/api.ts (3 errors)
+src/api.ts(15,10): error TS2345: ...           TS2345: Argument type mismatch (x2)
+src/api.ts(20,3): error TS7006: ...            TS7006: Parameter implicitly has 'any'
+src/utils.ts(5,1): error TS2304: ...         src/utils.ts (1 error)
+...                                            TS2304: Cannot find name 'foo'
+```
+
+---
+
+### `rtk lint` -- ESLint / Biome
+
+**Economies :** ~84%
+
+```bash
+rtk lint [args...]
+rtk lint biome [args...]
+```
+
+Regroupe les violations par regle et par fichier. Auto-detecte le linter.
+
+---
+
+### `rtk prettier` -- Verification du formatage
+
+**Economies :** ~70%
+
+```bash
+rtk prettier [args...]    # ex: rtk prettier --check .
+```
+
+Affiche uniquement les fichiers necessitant un formatage.
+
+---
+
+### `rtk format` -- Formateur universel
+
+```bash
+rtk format [args...]
+```
+
+Auto-detecte le formateur du projet (prettier, black, ruff format) et applique un filtre compact.
+
+---
+
+### `rtk next build` -- Build Next.js
+
+**Economies :** ~87%
+
+```bash
+rtk next [args...]
+```
+
+Sortie compacte avec metriques de routes.
+
+---
+
+### `rtk ruff` -- Linter/formateur Python
+
+**Economies :** ~80%
+
+```bash
+rtk ruff check [args...]
+rtk ruff format --check [args...]
+```
+
+Sortie JSON compressee.
+
+---
+
+### `rtk mypy` -- Type checker Python
+
+```bash
+rtk mypy [args...]
+```
+
+Regroupe les erreurs de type par fichier.
+
+---
+
+### `rtk golangci-lint` -- Linter Go
+
+**Economies :** ~85%
+
+```bash
+rtk golangci-lint run [args...]
+```
+
+Sortie JSON compressee.
+
+---
+
+## Commandes Formatage
+
+### `rtk prettier` -- Prettier
+
+```bash
+rtk prettier --check .
+rtk prettier --write src/
+```
+
+---
+
+### `rtk format` -- Detecteur universel
+
+```bash
+rtk format [args...]
+```
+
+Detecte automatiquement : prettier, black, ruff format, rustfmt. Applique un filtre compact unifie.
+
+---
+
+## Gestionnaires de paquets
+
+### `rtk pnpm` -- pnpm
+
+| Commande | Description | Economies |
+|----------|-------------|-----------|
+| `rtk pnpm list [-d N]` | Arbre de dependances compact | ~70% |
+| `rtk pnpm outdated` | Paquets obsoletes : `pkg: old -> new` | ~80% |
+| `rtk pnpm install [pkgs...]` | Filtre les barres de progression | ~60% |
+| `rtk pnpm build` | Delegue au filtre Next.js | ~87% |
+| `rtk pnpm typecheck` | Delegue au filtre tsc | ~83% |
+
+Les sous-commandes non reconnues sont transmises directement a pnpm (passthrough).
+
+---
+
+### `rtk npm` -- npm
+
+```bash
+rtk npm [args...]    # ex: rtk npm run build
+```
+
+Filtre le boilerplate npm (barres de progression, en-tetes, etc.).
+
+---
+
+### `rtk npx` -- npx avec routage intelligent
+
+```bash
+rtk npx [args...]
+```
+
+Route intelligemment vers les filtres specialises :
+- `rtk npx tsc` -> filtre tsc
+- `rtk npx eslint` -> filtre lint
+- `rtk npx prisma` -> filtre prisma
+- Autres -> passthrough filtre
+
+---
+
+### `rtk pip` -- pip / uv
+
+```bash
+rtk pip list              # Liste des paquets (auto-detecte uv)
+rtk pip outdated          # Paquets obsoletes
+rtk pip install <pkg>     # Installation
+```
+
+Auto-detecte `uv` si disponible et l'utilise a la place de `pip`.
+
+---
+
+### `rtk deps` -- Resume des dependances
+
+**Objectif :** Resume compact des dependances du projet.
+
+```bash
+rtk deps [chemin]    # Defaut: repertoire courant
+```
+
+Auto-detecte : `Cargo.toml`, `package.json`, `pyproject.toml`, `go.mod`, `Gemfile`, etc.
+
+**Economies :** ~70%
+
+---
+
+### `rtk prisma` -- ORM Prisma
+
+| Commande | Description |
+|----------|-------------|
+| `rtk prisma generate` | Generation du client (supprime l'ASCII art) |
+| `rtk prisma migrate dev [--name N]` | Creer et appliquer une migration |
+| `rtk prisma migrate status` | Status des migrations |
+| `rtk prisma migrate deploy` | Deployer en production |
+| `rtk prisma db-push` | Push du schema |
+
+---
+
+## Conteneurs et orchestration
+
+### `rtk docker` -- Docker
+
+| Commande | Description | Economies |
+|----------|-------------|-----------|
+| `rtk docker ps` | Liste compacte des conteneurs | ~80% |
+| `rtk docker images` | Liste compacte des images | ~80% |
+| `rtk docker logs <conteneur>` | Logs dedupliques | ~70% |
+| `rtk docker compose ps` | Services Compose compacts | ~80% |
+| `rtk docker compose logs [service]` | Logs Compose dedupliques | ~70% |
+| `rtk docker compose build [service]` | Resume du build | ~60% |
+
+Les sous-commandes non reconnues sont transmises directement (passthrough).
+
+**Avant / Apres :**
+```
+# docker ps (lignes longues, ~30 tokens/ligne)    # rtk docker ps (~10 tokens/ligne)
+CONTAINER ID   IMAGE          COMMAND     ...      web  nginx:1.25 Up 2d (healthy)
+abc123def456   nginx:1.25     "/dock..."  ...      db   postgres:16 Up 2d (healthy)
+789012345678   postgres:16    "docker..."           redis redis:7 Up 1d
+```
+
+---
+
+### `rtk kubectl` -- Kubernetes
+
+| Commande | Description | Options |
+|----------|-------------|---------|
+| `rtk kubectl pods [-n ns] [-A]` | Liste compacte des pods | Namespace ou tous |
+| `rtk kubectl services [-n ns] [-A]` | Liste compacte des services | Namespace ou tous |
+| `rtk kubectl logs <pod> [-c container]` | Logs dedupliques | Container specifique |
+
+Les sous-commandes non reconnues sont transmises directement (passthrough).
+
+---
+
+## Donnees et reseau
+
+### `rtk json` -- Structure JSON
+
+**Objectif :** Affiche la structure d'un fichier JSON sans les valeurs.
+
+```bash
+rtk json <fichier> [--depth N]    # Defaut: profondeur 5
+rtk json -                         # Depuis stdin
+```
+
+**Economies :** ~60%
+
+**Avant / Apres :**
+```
+# cat package.json (50 lignes)              # rtk json package.json (10 lignes)
+{                                            {
+  "name": "my-app",                            name: string
+  "version": "1.0.0",                         version: string
+  "dependencies": {                            dependencies: { 15 keys }
+    "react": "^18.2.0",                        devDependencies: { 8 keys }
+    "next": "^14.0.0",                         scripts: { 6 keys }
+    ...15 dependances...                     }
+  },
+  ...
+}
+```
+
+---
+
+### `rtk env` -- Variables d'environnement
+
+```bash
+rtk env                    # Toutes les variables (sensibles masquees)
+rtk env -f AWS             # Filtrer par nom
+rtk env --show-all         # Inclure les valeurs sensibles
+```
+
+Les variables sensibles (tokens, secrets, mots de passe) sont masquees par defaut : `AWS_SECRET_ACCESS_KEY=***`.
+
+---
+
+### `rtk log` -- Logs dedupliques
+
+**Objectif :** Filtre et deduplique la sortie de logs.
+
+```bash
+rtk log <fichier>     # Depuis un fichier
+rtk log               # Depuis stdin (pipe)
+```
+
+Les lignes repetees sont fusionnees : `[ERROR] Connection refused (x42)`.
+
+**Economies :** ~60-80% (selon la repetitivite)
+
+---
+
+### `rtk curl` -- HTTP avec detection JSON
+
+```bash
+rtk curl [args...]
+```
+
+Auto-detecte les reponses JSON et affiche le schema au lieu du contenu complet.
+
+---
+
+### `rtk wget` -- Telechargement compact
+
+```bash
+rtk wget <url> [args...]
+rtk wget -O - <url>           # Sortie vers stdout
+```
+
+Supprime les barres de progression et le bruit.
+
+---
+
+### `rtk summary` -- Resume heuristique
+
+**Objectif :** Execute une commande et genere un resume heuristique de la sortie.
+
+```bash
+rtk summary <commande...>
+```
+
+Utile pour les commandes longues dont la sortie n'a pas de filtre dedie.
+
+---
+
+### `rtk proxy` -- Passthrough avec suivi
+
+**Objectif :** Execute une commande **sans filtrage** mais enregistre l'utilisation pour le suivi.
+
+```bash
+rtk proxy <commande...>
+```
+
+Utile pour le debug : comparer la sortie brute avec la sortie filtree.
+
+---
+
+## Cloud et bases de donnees
+
+### `rtk aws` -- AWS CLI
+
+```bash
+rtk aws <service> [args...]
+```
+
+Force la sortie JSON et compresse le resultat. Supporte tous les services AWS (sts, s3, ec2, ecs, rds, cloudformation, etc.).
+
+---
+
+### `rtk psql` -- PostgreSQL
+
+```bash
+rtk psql [args...]
+```
+
+Supprime les bordures de tableaux et compresse la sortie.
+
+---
+
+## Stacked PRs (Graphite)
+
+### `rtk gt` -- Graphite
+
+| Commande | Description |
+|----------|-------------|
+| `rtk gt log` | Stack log compact |
+| `rtk gt submit` | Submit compact |
+| `rtk gt sync` | Sync compact |
+| `rtk gt restack` | Restack compact |
+| `rtk gt create` | Create compact |
+| `rtk gt branch` | Branch info compact |
+
+Les sous-commandes non reconnues sont transmises directement ou detectees comme passthrough git.
+
+---
+
+## Analytique et suivi
+
+### Systeme de tracking
+
+RTK enregistre chaque execution de commande dans une base SQLite :
+
+- **Emplacement :** `~/.local/share/rtk/tracking.db` (Linux), `~/Library/Application Support/rtk/tracking.db` (macOS)
+- **Retention :** 90 jours automatique
+- **Metriques :** tokens entree/sortie, pourcentage d'economies, temps d'execution, projet
+
+---
+
+### `rtk gain` -- Statistiques d'economies
+
+```bash
+rtk gain                        # Resume global
+rtk gain -p                     # Filtre par projet courant
+rtk gain --graph                # Graphe ASCII (30 derniers jours)
+rtk gain --history              # Historique recent des commandes
+rtk gain --daily                # Ventilation jour par jour
+rtk gain --weekly               # Ventilation par semaine
+rtk gain --monthly              # Ventilation par mois
+rtk gain --all                  # Toutes les ventilations
+rtk gain --quota -t pro         # Estimation d'economies sur le quota mensuel
+rtk gain --failures             # Log des echecs de parsing (commandes en fallback)
+rtk gain --format json          # Export JSON (pour dashboards)
+rtk gain --format csv           # Export CSV
+```
+
+**Options :**
+
+| Option | Court | Description |
+|--------|-------|-------------|
+| `--project` | `-p` | Filtrer par repertoire courant |
+| `--graph` | `-g` | Graphe ASCII des 30 derniers jours |
+| `--history` | `-H` | Historique recent des commandes |
+| `--quota` | `-q` | Estimation d'economies sur le quota mensuel |
+| `--tier` | `-t` | Tier d'abonnement : `pro`, `5x`, `20x` (defaut: `20x`) |
+| `--daily` | `-d` | Ventilation quotidienne |
+| `--weekly` | `-w` | Ventilation hebdomadaire |
+| `--monthly` | `-m` | Ventilation mensuelle |
+| `--all` | `-a` | Toutes les ventilations |
+| `--format` | `-f` | Format de sortie : `text`, `json`, `csv` |
+| `--failures` | `-F` | Affiche les commandes en fallback |
+
+**Exemple de sortie :**
+```
+$ rtk gain
+RTK Token Savings Summary
+  Total commands:     1,247
+  Total input:        2,341,000 tokens
+  Total output:       468,200 tokens
+  Total saved:        1,872,800 tokens (80%)
+  Avg per command:    1,501 tokens saved
+
+Top commands:
+  git status    312x  -82%
+  cargo test    156x  -91%
+  git diff       98x  -76%
+```
+
+---
+
+### `rtk discover` -- Opportunites manquees
+
+**Objectif :** Analyse l'historique Claude Code pour trouver les commandes qui auraient pu etre optimisees par rtk.
+
+```bash
+rtk discover                          # Projet courant, 30 derniers jours
+rtk discover --all --since 7          # Tous les projets, 7 derniers jours
+rtk discover -p /chemin/projet        # Filtrer par projet
+rtk discover --limit 20              # Max commandes par section
+rtk discover --format json            # Export JSON
+```
+
+**Options :**
+
+| Option | Court | Description |
+|--------|-------|-------------|
+| `--project` | `-p` | Filtrer par chemin de projet |
+| `--limit` | `-l` | Max commandes par section (defaut: 15) |
+| `--all` | `-a` | Scanner tous les projets |
+| `--since` | `-s` | Derniers N jours (defaut: 30) |
+| `--format` | `-f` | Format : `text`, `json` |
+
+---
+
+### `rtk learn` -- Apprendre des erreurs
+
+**Objectif :** Analyse l'historique d'erreurs CLI de Claude Code pour detecter les corrections recurrentes.
+
+```bash
+rtk learn                             # Projet courant
+rtk learn --all --since 7             # Tous les projets
+rtk learn --write-rules               # Generer .claude/rules/cli-corrections.md
+rtk learn --min-confidence 0.8        # Seuil de confiance (defaut: 0.6)
+rtk learn --min-occurrences 3         # Occurrences minimales (defaut: 1)
+rtk learn --format json               # Export JSON
+```
+
+---
+
+### `rtk cc-economics` -- Analyse economique Claude Code
+
+**Objectif :** Compare les depenses Claude Code (via ccusage) avec les economies RTK.
+
+```bash
+rtk cc-economics                      # Resume
+rtk cc-economics --daily              # Ventilation quotidienne
+rtk cc-economics --weekly             # Ventilation hebdomadaire
+rtk cc-economics --monthly            # Ventilation mensuelle
+rtk cc-economics --all                # Toutes les ventilations
+rtk cc-economics --format json        # Export JSON
+```
+
+---
+
+### `rtk hook-audit` -- Metriques du hook
+
+**Prerequis :** Necessite `RTK_HOOK_AUDIT=1` dans l'environnement.
+
+```bash
+rtk hook-audit                        # 7 derniers jours (defaut)
+rtk hook-audit --since 30             # 30 derniers jours
+rtk hook-audit --since 0              # Tout l'historique
+```
+
+---
+
+## Systeme de hooks
+
+### Fonctionnement
+
+Le hook RTK intercepte les commandes Bash dans Claude Code **avant leur execution** et les reecrit automatiquement en equivalent RTK.
+
+**Flux :**
+```
+Claude Code "git status"
+    |
+    v
+settings.json -> PreToolUse hook
+    |
+    v
+rtk-rewrite.sh (bash)
+    |
+    v
+rtk rewrite "git status"  ->  "rtk git status"
+    |
+    v
+Claude Code execute "rtk git status"
+    |
+    v
+Sortie filtree retournee a Claude (~10 tokens vs ~200)
+```
+
+**Points cles :**
+- Claude ne voit jamais la recriture -- il recoit simplement une sortie optimisee
+- Le hook est un delegateur leger (~50 lignes bash) qui appelle `rtk rewrite`
+- Toute la logique de recriture est dans le registre Rust (`src/discover/registry.rs`)
+- Les commandes deja prefixees par `rtk` passent sans modification
+- Les heredocs (`<<`) ne sont pas modifies
+- Les commandes non reconnues passent sans modification
+
+### Installation
+
+```bash
+rtk init -g                     # Installation recommandee (hook + RTK.md)
+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
+```
+
+### Fichiers installes
+
+| 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 |
+
+### `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.
+
+```bash
+rtk rewrite "git status"           # -> "rtk git status" (exit 0)
+rtk rewrite "terraform plan"       # -> (exit 1, pas de recriture)
+rtk rewrite "rtk git status"       # -> "rtk git status" (exit 0, inchange)
+```
+
+### `rtk verify` -- Verification d'integrite
+
+Verifie l'integrite du hook installe via un controle SHA-256.
+
+```bash
+rtk verify
+```
+
+### Commandes reecrites automatiquement
+
+| Commande brute | Reecrite en |
+|----------------|-------------|
+| `git status/diff/log/add/commit/push/pull` | `rtk git ...` |
+| `gh pr/issue/run` | `rtk gh ...` |
+| `cargo test/build/clippy/check` | `rtk cargo ...` |
+| `cat/head/tail <fichier>` | `rtk read <fichier>` |
+| `rg/grep <pattern>` | `rtk grep <pattern>` |
+| `ls` | `rtk ls` |
+| `tree` | `rtk tree` |
+| `wc` | `rtk wc` |
+| `vitest/jest` | `rtk vitest run` |
+| `tsc` | `rtk tsc` |
+| `eslint/biome` | `rtk lint` |
+| `prettier` | `rtk prettier` |
+| `playwright` | `rtk playwright` |
+| `prisma` | `rtk prisma` |
+| `ruff check/format` | `rtk ruff ...` |
+| `pytest` | `rtk pytest` |
+| `mypy` | `rtk mypy` |
+| `pip list/install` | `rtk pip ...` |
+| `go test/build/vet` | `rtk go ...` |
+| `golangci-lint` | `rtk golangci-lint` |
+| `docker ps/images/logs` | `rtk docker ...` |
+| `kubectl get/logs` | `rtk kubectl ...` |
+| `curl` | `rtk curl` |
+| `pnpm list/outdated` | `rtk pnpm ...` |
+
+### Exclusion de commandes
+
+Pour empecher certaines commandes d'etre reecrites, ajoutez-les dans `config.toml` :
+
+```toml
+[hooks]
+exclude_commands = ["curl", "playwright"]
+```
+
+---
+
+## Configuration
+
+### Fichier de configuration
+
+**Emplacement :** `~/.config/rtk/config.toml` (Linux) ou `~/Library/Application Support/rtk/config.toml` (macOS)
+
+**Commandes :**
+```bash
+rtk config                # Afficher la configuration actuelle
+rtk config --create       # Creer le fichier avec les valeurs par defaut
+```
+
+### Structure complete
+
+```toml
+[tracking]
+enabled = true              # Activer/desactiver le suivi
+history_days = 90           # Jours de retention (nettoyage automatique)
+database_path = "/custom/path/tracking.db"  # Chemin personnalise (optionnel)
+
+[display]
+colors = true               # Sortie coloree
+emoji = true                # Utiliser les emojis
+max_width = 120             # Largeur maximale de sortie
+
+[filters]
+ignore_dirs = [".git", "node_modules", "target", "__pycache__", ".venv", "vendor"]
+ignore_files = ["*.lock", "*.min.js", "*.min.css"]
+
+[tee]
+enabled = true              # Activer la sauvegarde de sortie brute
+mode = "failures"           # "failures" (defaut), "always", ou "never"
+max_files = 20              # Rotation : garder les N derniers fichiers
+# directory = "/custom/tee/path"  # Chemin personnalise (optionnel)
+
+[telemetry]
+enabled = true              # Telemetrie anonyme (1 ping/jour, opt-out possible)
+
+[hooks]
+exclude_commands = []       # Commandes a exclure de la recriture automatique
+```
+
+### Variables d'environnement
+
+| Variable | Description |
+|----------|-------------|
+| `RTK_TEE_DIR` | Surcharge le repertoire tee |
+| `RTK_TELEMETRY_DISABLED=1` | Desactiver la telemetrie |
+| `RTK_HOOK_AUDIT=1` | Activer l'audit du hook |
+| `SKIP_ENV_VALIDATION=1` | Desactiver la validation d'env (Next.js, etc.) |
+
+---
+
+## Systeme Tee
+
+### Recuperation de sortie brute
+
+Quand une commande echoue, RTK sauvegarde automatiquement la sortie brute complete dans un fichier log. Cela permet au LLM de lire la sortie sans re-executer la commande.
+
+**Fonctionnement :**
+1. La commande echoue (exit code != 0)
+2. RTK sauvegarde la sortie brute dans `~/.local/share/rtk/tee/`
+3. Le chemin du fichier est affiche dans la sortie filtree
+4. Le LLM peut lire le fichier si besoin de plus de details
+
+**Sortie :**
+```
+FAILED: 2/15 tests
+[full output: ~/.local/share/rtk/tee/1707753600_cargo_test.log]
+```
+
+**Configuration :**
+
+| Parametre | Defaut | Description |
+|-----------|--------|-------------|
+| `tee.enabled` | `true` | Activer/desactiver |
+| `tee.mode` | `"failures"` | `"failures"`, `"always"`, `"never"` |
+| `tee.max_files` | `20` | Rotation : garder les N derniers |
+| Taille min | 500 octets | Les sorties trop courtes ne sont pas sauvegardees |
+| Taille max fichier | 1 Mo | Troncature au-dela |
+
+---
+
+## Telemetrie
+
+RTK envoie un ping anonyme une fois par jour (23h d'intervalle) pour des statistiques d'utilisation.
+
+**Donnees envoyees :** hash de device, version, OS, architecture, nombre de commandes/24h, top commandes, pourcentage d'economies.
+
+**Desactiver :**
+```bash
+# Via variable d'environnement
+export RTK_TELEMETRY_DISABLED=1
+
+# Via config.toml
+[telemetry]
+enabled = false
+```
+
+Aucune donnee personnelle, aucun contenu de commande, aucun chemin de fichier n'est transmis.
+
+---
+
+## Resume des economies par categorie
+
+| Categorie | Commandes | Economies typiques |
+|-----------|-----------|-------------------|
+| **Fichiers** | ls, tree, read, find, grep, diff | 60-80% |
+| **Git** | status, log, diff, show, add, commit, push, pull | 75-92% |
+| **GitHub** | pr, issue, run, api | 26-87% |
+| **Tests** | cargo test, vitest, playwright, pytest, go test | 90-99% |
+| **Build/Lint** | cargo build, tsc, eslint, prettier, next, ruff, clippy | 70-87% |
+| **Paquets** | pnpm, npm, pip, deps, prisma | 60-80% |
+| **Conteneurs** | docker, kubectl | 70-80% |
+| **Donnees** | json, env, log, curl, wget | 60-80% |
+| **Analytique** | gain, discover, learn, cc-economics | N/A (meta) |
+
+---
+
+## Nombre total de commandes
+
+RTK supporte **45+ commandes** reparties en 9 categories, avec passthrough automatique pour les sous-commandes non reconnues. Cela en fait un proxy universel : il est toujours sur a utiliser en prefixe.