fix(refacto-codebase): technical docs & sub folders

.claude/agents/code-reviewer.md

@@ -14,13 +14,15 @@ Prevent bugs, performance regressions, and token savings failures before they re
 ## RTK Architecture Context
 
 ```
-main.rs (Commands enum + routing)
-  → *_cmd.rs modules (filter logic)
-  → tracking.rs (SQLite, token metrics)
-  → utils.rs (shared helpers)
-  → tee.rs (failure recovery)
-  → config.rs (user config)
-  → filter.rs (language-aware filtering)
+src/main.rs (Commands enum + routing)
+  → src/cmds/**/*_cmd.rs (filter logic, organized by ecosystem)
+  → src/core/tracking.rs (SQLite, token metrics)
+  → src/core/utils.rs (shared helpers)
+  → src/core/tee.rs (failure recovery)
+  → src/core/config.rs (user config)
+  → src/core/filter.rs (language-aware filtering)
+  → src/hooks/ (init, rewrite, verify, trust)
+  → src/analytics/ (gain, cc_economics, ccusage)
 ```
 
 **Non-negotiable constraints:**

.claude/agents/rtk-testing-specialist.md

@@ -337,7 +337,7 @@ docker run --rm -v $(pwd):/rtk -w /rtk rust:latest cargo test
 newcmd --some-args > tests/fixtures/newcmd_raw.txt
 ```
 
-2. **Add snapshot test** to `src/newcmd_cmd.rs`:
+2. **Add snapshot test** to `src/cmds/<ecosystem>/newcmd_cmd.rs`:
 ```rust
 #[cfg(test)]
 mod tests {
@@ -439,18 +439,27 @@ cargo test --ignored
 ```
 rtk/
 ├── src/
-│   ├── git.rs                  # Filter implementation
-│   │   └── #[cfg(test)] mod tests { ... }  # Unit tests
-│   ├── snapshots/              # Insta snapshots (gitignored pattern)
-│   │   └── git.rs.snap         # Snapshot for git tests
+│   ├── cmds/
+│   │   ├── git/
+│   │   │   ├── git.rs                    # Filter implementation
+│   │   │   │   └── #[cfg(test)] mod tests { ... }  # Unit tests
+│   │   │   └── snapshots/                # Insta snapshots for git module
+│   │   ├── js/
+│   │   ├── python/
+│   │   └── ...                           # Other ecosystems
+│   ├── core/
+│   │   ├── filter.rs                     # Core filtering with tests
+│   │   └── snapshots/
+│   └── hooks/
 ├── tests/
 │   ├── common/
-│   │   └── mod.rs              # Shared test utilities (count_tokens, etc.)
-│   ├── fixtures/               # Real command output fixtures
-│   │   ├── git_log_raw.txt     # Real git log output
-│   │   ├── cargo_test_raw.txt  # Real cargo test output
-│   │   └── gh_pr_view_raw.txt  # Real gh pr view output
-│   └── integration_test.rs     # Integration tests (#[ignore])
+│   │   └── mod.rs                        # Shared test utilities (count_tokens, etc.)
+│   ├── fixtures/                         # Real command output fixtures
+│   │   ├── git_log_raw.txt
+│   │   ├── cargo_test_raw.txt
+│   │   ├── gh_pr_view_raw.txt
+│   │   └── dotnet/                       # Dotnet-specific fixtures
+│   └── integration_test.rs              # Integration tests (#[ignore])
 ```
 
 **Best practices**:

.claude/agents/rust-rtk.md

@@ -306,20 +306,27 @@ fn test_real_git_log() {
 
 ## Key Files Reference
 
-**Core modules**:
+**Core infrastructure** (`src/core/`):
 - `src/main.rs` - CLI entry point, Clap command parsing, routing to modules
-- `src/git.rs` - Git operations filter (log, status, diff, etc.)
-- `src/grep_cmd.rs` - Code search filter (grep, ripgrep)
-- `src/runner.rs` - Command execution filter (test, err)
-- `src/utils.rs` - Shared utilities (truncate, strip_ansi, execute_command)
-- `src/tracking.rs` - SQLite token savings tracking (`rtk gain`)
-
-**Filter modules** (see CLAUDE.md Module Responsibilities table):
-- `src/lint_cmd.rs`, `src/tsc_cmd.rs`, `src/next_cmd.rs` - JavaScript/TypeScript tooling
-- `src/prettier_cmd.rs`, `src/playwright_cmd.rs`, `src/prisma_cmd.rs` - Modern JS stack
-- `src/pnpm_cmd.rs`, `src/vitest_cmd.rs` - Package manager, test runner
-- `src/ruff_cmd.rs`, `src/pytest_cmd.rs`, `src/pip_cmd.rs` - Python ecosystem
-- `src/go_cmd.rs`, `src/golangci_cmd.rs` - Go ecosystem
+- `src/core/utils.rs` - Shared utilities (truncate, strip_ansi, execute_command)
+- `src/core/tracking.rs` - SQLite token savings tracking (`rtk gain`)
+- `src/core/filter.rs` - Language-aware code filtering engine
+- `src/core/tee.rs` - Raw output recovery on failure
+- `src/core/config.rs` - User configuration (~/.config/rtk/config.toml)
+
+**Command modules** (`src/cmds/<ecosystem>/`):
+- `src/cmds/git/` - git.rs, gh_cmd.rs, gt_cmd.rs, diff_cmd.rs
+- `src/cmds/rust/` - cargo_cmd.rs, runner.rs
+- `src/cmds/js/` - lint_cmd.rs, tsc_cmd.rs, next_cmd.rs, prettier_cmd.rs, playwright_cmd.rs, prisma_cmd.rs, vitest_cmd.rs, pnpm_cmd.rs, npm_cmd.rs
+- `src/cmds/python/` - ruff_cmd.rs, pytest_cmd.rs, mypy_cmd.rs, pip_cmd.rs
+- `src/cmds/go/` - go_cmd.rs, golangci_cmd.rs
+- `src/cmds/ruby/` - rake_cmd.rs, rspec_cmd.rs, rubocop_cmd.rs
+- `src/cmds/cloud/` - aws_cmd.rs, container.rs, curl_cmd.rs, wget_cmd.rs, psql_cmd.rs
+- `src/cmds/system/` - ls.rs, tree.rs, read.rs, grep_cmd.rs, find_cmd.rs, etc.
+
+**Hook & analytics** (`src/hooks/`, `src/analytics/`):
+- `src/hooks/init.rs` - rtk init command
+- `src/analytics/gain.rs` - rtk gain command
 
 **Tests**:
 - `tests/fixtures/` - Real command output fixtures for testing
@@ -401,11 +408,11 @@ When adding a new filter (e.g., `rtk newcmd`):
 ### 1. Create Module
 
 ```bash
-touch src/newcmd_cmd.rs
+touch src/cmds/<ecosystem>/newcmd_cmd.rs
 ```
 
 ```rust
-// src/newcmd_cmd.rs
+// src/cmds/<ecosystem>/newcmd_cmd.rs
 use anyhow::{Context, Result};
 use lazy_static::lazy_static;
 use regex::Regex;
@@ -436,18 +443,23 @@ mod tests {
 }
 ```
 
-### 2. Add to main.rs Commands Enum
+### 2. Register Module
 
+Add to ecosystem `mod.rs` (e.g., `src/cmds/system/mod.rs`):
 ```rust
-// src/main.rs
-#[derive(Subcommand)]
-enum Commands {
-    // ... existing commands
-    Newcmd {
-        #[arg(trailing_var_arg = true, allow_hyphen_values = true)]
-        args: Vec<String>,
-    },
-}
+pub mod newcmd_cmd;
+```
+
+Add to `src/main.rs` Commands enum and routing:
+```rust
+// Add use import
+use cmds::system::newcmd_cmd;
+
+// In Commands enum
+Newcmd {
+    #[arg(trailing_var_arg = true, allow_hyphen_values = true)]
+    args: Vec<String>,
+},
 
 // In match statement
 Commands::Newcmd { args } => {

.claude/agents/system-architect.md

@@ -30,21 +30,24 @@ Think in terms of filter families, not individual commands. Every new `*_cmd.rs`
 ## RTK Architecture Map
 
 ```
-main.rs
+src/main.rs
 ├── Commands enum (clap derive)
-│   ├── Git(GitArgs)      → git.rs
-│   ├── Cargo(CargoArgs)  → runner.rs
-│   ├── Gh(GhArgs)        → gh_cmd.rs
-│   ├── Grep(GrepArgs)    → grep_cmd.rs
-│   ├── ...               → *_cmd.rs
-│   ├── Gain              → tracking.rs
+│   ├── Git(GitArgs)      → cmds/git/git.rs
+│   ├── Cargo(CargoArgs)  → cmds/rust/runner.rs
+│   ├── Gh(GhArgs)        → cmds/git/gh_cmd.rs
+│   ├── Grep(GrepArgs)    → cmds/system/grep_cmd.rs
+│   ├── ...               → cmds/<ecosystem>/*_cmd.rs
+│   ├── Gain              → analytics/gain.rs
 │   └── Proxy(ProxyArgs)  → passthrough
 │
-├── tracking.rs           ← SQLite, token metrics, 90-day retention
-├── config.rs             ← ~/.config/rtk/config.toml
-├── tee.rs                ← Raw output recovery on failure
-├── filter.rs             ← Language-aware code filtering
-└── utils.rs              ← strip_ansi, truncate, execute_command
+├── core/
+│   ├── tracking.rs       ← SQLite, token metrics, 90-day retention
+│   ├── config.rs         ← ~/.config/rtk/config.toml
+│   ├── tee.rs            ← Raw output recovery on failure
+│   ├── filter.rs         ← Language-aware code filtering
+│   └── utils.rs          ← strip_ansi, truncate, execute_command
+├── hooks/                ← init, rewrite, verify, trust, integrity
+└── analytics/            ← gain, cc_economics, ccusage, session_cmd
 ```
 
 **TOML Filter DSL** (v0.25.0+):

.claude/agents/technical-writer.md

@@ -227,11 +227,11 @@ echo $LAST_COMMAND  # Should show "rtk git status"
 ### 1. Create Filter Module
 
 ```bash
-touch src/newcmd_cmd.rs
+touch src/cmds/<ecosystem>/newcmd_cmd.rs
 ```
 
 ```rust
-// src/newcmd_cmd.rs
+// src/cmds/<ecosystem>/newcmd_cmd.rs
 use anyhow::{Context, Result};
 use lazy_static::lazy_static;
 use regex::Regex;

.claude/commands/tech/codereview.md

@@ -57,11 +57,12 @@ git diff "$BASE_BRANCH"...HEAD --stat
 
 | Si le diff contient...         | Vérifier                                   |
 | ------------------------------ | ------------------------------------------ |
-| `src/*.rs`                     | CLAUDE.md sections Error Handling + Tests  |
-| `src/filter.rs` ou `*_cmd.rs`  | Filter Development Checklist (CLAUDE.md)   |
+| `src/**/*.rs`                  | CLAUDE.md sections Error Handling + Tests  |
+| `src/core/filter.rs` ou `src/cmds/**/*_cmd.rs` | Filter Development Checklist (CLAUDE.md) |
 | `src/main.rs`                  | Command routing + Commands enum            |
-| `src/tracking.rs`              | SQLite patterns + DB path config           |
-| `src/config.rs`                | Configuration system + init patterns       |
+| `src/core/tracking.rs`         | SQLite patterns + DB path config           |
+| `src/core/config.rs`           | Configuration system                       |
+| `src/hooks/init.rs`            | Init patterns + hook installation          |
 | `.github/workflows/`           | CI/CD multi-platform build targets         |
 | `tests/` ou `fixtures/`        | Testing Strategy (CLAUDE.md)               |
 | `Cargo.toml`                   | Dependencies + build optimizations         |

.claude/rules/cli-testing.md

@@ -43,7 +43,7 @@ fn test_git_log_output() {
 git log -20 > tests/fixtures/git_log_raw.txt
 
 # 2. Write test with assert_snapshot!
-cat > src/git.rs <<'EOF'
+cat > src/cmds/git/git.rs <<'EOF'
 #[cfg(test)]
 mod tests {
     use insta::assert_snapshot;
@@ -64,7 +64,7 @@ cargo test test_git_log_format
 cargo insta review
 # Press 'a' to accept, 'r' to reject
 
-# 5. Snapshot saved in src/snapshots/git.rs.snap
+# 5. Snapshot saved in src/cmds/git/snapshots/git__tests__*.snap
 ```
 
 ## Token Accuracy Testing (🔴 Critical)
@@ -299,24 +299,32 @@ diff /tmp/before.txt /tmp/after.txt
 ```
 rtk/
 ├── src/
-│   ├── git.rs                  # Filter implementation
-│   │   └── #[cfg(test)] mod tests { ... }  # Unit tests
-│   ├── snapshots/              # Insta snapshots
-│   │   └── git.rs.snap         # Snapshot for git tests
+│   ├── cmds/
+│   │   ├── git/
+│   │   │   ├── git.rs              # Filter implementation
+│   │   │   │   └── #[cfg(test)] mod tests { ... }
+│   │   │   └── snapshots/          # Insta snapshots for git module
+│   │   ├── js/                     # JS/TS ecosystem filters
+│   │   ├── python/                 # Python ecosystem filters
+│   │   └── ...
+│   ├── core/                       # Shared infrastructure
+│   ├── hooks/                      # Hook system
+│   └── analytics/                  # Token savings analytics
 ├── tests/
 │   ├── common/
-│   │   └── mod.rs              # Shared test utilities (count_tokens)
-│   ├── fixtures/               # Real command output
+│   │   └── mod.rs                  # Shared test utilities (count_tokens)
+│   ├── fixtures/                   # Real command output
 │   │   ├── git_log_raw.txt
 │   │   ├── cargo_test_raw.txt
-│   │   └── gh_pr_view_raw.txt
-│   └── integration_test.rs     # Integration tests (#[ignore])
+│   │   ├── gh_pr_view_raw.txt
+│   │   └── dotnet/                 # Dotnet-specific fixtures
+│   └── integration_test.rs         # Integration tests (#[ignore])
 ```
 
 **Best practices**:
 - **Unit tests**: Embedded in module (`#[cfg(test)] mod tests`)
 - **Fixtures**: Real command output in `tests/fixtures/`
-- **Snapshots**: Auto-generated in `src/snapshots/` (by insta)
+- **Snapshots**: Auto-generated in `src/cmds/<ecosystem>/snapshots/` (by insta)
 - **Shared utils**: `tests/common/mod.rs` (count_tokens, helpers)
 - **Integration**: `tests/` with `#[ignore]` attribute