diff --git a/CHANGELOG.md b/CHANGELOG.md
index 32e8a20..92f69dc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,338 @@ Format follows [Keep a Changelog](https://keepachangelog.com/).
 
 ## [Unreleased]
 
+## [3.2.1] — 2026-04-07
+
+### Fixed
+- `agents/plugin-advisor.md`: 4 signals had entries in the signal table but no conditional rule — added rules for `skill-creation`, `browser-qa`, `design-system`, and `complex-arch`
+
+### Changed
+- `version.txt`: 3.2.0 → 3.2.1
+
+## [3.2.0] — 2026-04-07
+
+### Fixed
+- `doctor.sh`: EXPECTED_SKILLS pass message uses `${#EXPECTED_SKILLS[@]}` (dynamic count) instead of hardcoded 9
+- `agents/plugin-advisor.md`: `setup.py` and `pyproject.toml` added as counterindicators for embedded signal — prevents Python C-extensions from false-triggering embedded
+- `agents/status-reporter.md`: PHP phpunit added to manifest fallback (`composer.json` → `./vendor/bin/phpunit`)
+- `skills/health/SKILL.md`: post-result guidance added — CRITICAL/WARNING/errors/warnings/all-pass handling
+
+### Added
+- `USAGE.md`: "Erreurs fréquentes" — embedded signal not detected entry
+
+### Changed
+- `version.txt`: 3.1.0 → 3.2.0
+
+## [3.1.0] — 2026-04-07
+
+### Fixed
+- `agents/plugin-advisor.md`: `Makefile` restored as embedded indicator — `Makefile` + `src/*.c` + no Node/Rust/Go manifest = embedded; `.c` files alone still not sufficient (Rust FFI counterindicated)
+- `agents/onboarder.md`: PHASE 6 — check `command -v gsd` before generating ROADMAP.md; if absent, ROADMAP.md still generated with install instructions; same pattern as init-project STEP 13
+
+### Added
+- `doctor.sh`: expected skills check — verifies all 9 skills (analyze, health, init-project, onboard, plugin-check, readme, refactor, ship-feature, status) present in `~/.claude/skills/`
+- `skills/analyze/SKILL.md`: description updated to mention DEBUG mode (read-only analysis OR error/stack trace → DEBUG mode)
+- `USAGE.md`: token cost estimates on workflow patterns (Pattern A ~3000-5000t, B ~1500-2500t/session, D ~500-800t, E ~600-900t); budget note at top of Patterns section
+
+### Changed
+- `version.txt`: 3.0.0 → 3.1.0
+
+## [3.0.0] — 2026-04-07
+
+### Fixed
+- `agents/plugin-advisor.md`: embedded false positive removed — `src/*.c` alone no longer triggers embedded signal (Rust FFI projects have .c files); only `platformio.ini` or `*.ld`/`*.lds` linker scripts are reliable triggers
+- `agents/status-reporter.md`: flat awk scoped to `## Milestone` headings — no longer matches `## Prerequisites`, `## Notes`, or other non-milestone `##` headings in ROADMAP.md
+
+### Added
+- `agents/status-reporter.md`: Go test runner in manifest fallback (`go.mod` → "go test ./...")
+- `USAGE.md`: GSD v2 active/interrupted node in decision tree — /gsd auto, /gsd steer, /gsd forensics
+- `skills/analyze/SKILL.md`: argument-hint updated to mention DEBUG mode (pass error/stack trace)
+
+### Breaking
+- `agents/plugin-advisor.md`: embedded detection no longer triggers on C/C++ files alone — projects relying on .c file detection must add `platformio.ini` or a `*.ld` linker script
+
+### Changed
+- `version.txt`: 2.9.0 → 3.0.0
+
+## [2.9.0] — 2026-04-07
+
+### Fixed
+- `agents/plugin-advisor.md`: PHASE 1 — filesystem embedded detection added (platformio.ini, *.ld linker scripts, src/*.c without package.json/Dockerfile); signal description updated
+- `agents/status-reporter.md`: PHASE 3 — flat ROADMAP fallback awk command for milestones with tasks directly under ## (no ### slices); marked with "(flat)" in output
+- `agents/status-reporter.md`: pytest cache parsing — JSON `{}` = "all passing" instead of "0 failing"; uses python3 for proper JSON parse instead of `cat | head`
+
+### Added
+- `USAGE.md`: analyze → refactor → analyze cycle documented in decision tree (refactoring profond)
+- `README.md`: link to USAGE.md in intro section
+
+### Changed
+- `version.txt`: 2.8.0 → 2.9.0
+
+## [2.8.0] — 2026-04-07
+
+### Fixed
+- `agents/status-reporter.md`: awk milestone detection uses `index()` instead of regex negation — portable across macOS nawk and GNU awk
+- `agents/status-reporter.md`: Tests field fallback improved — shows "run '<cmd>' to check" when no result found but test manifest exists; shows "N/A" only when no test infrastructure at all
+
+### Added
+- `agents/plugin-advisor.md`: `embedded` signal added — firmware/bare-metal/microcontroller detection; DECISION TABLE row; conditional rule disabling all toggles, superpowers optional
+- `doctor.sh`: agents pass message now lists all 8 agent names inline for quick visual confirmation
+- `USAGE.md`: section "Quel skill utiliser ?" — decision tree for all 9 skills with quick-reference table
+- `README.md`: `/status` added to Maintenance Diagnostic section alongside `/health`
+
+### Changed
+- `version.txt`: 2.7.0 → 2.8.0
+
+## [2.7.0] — 2026-04-07
+
+### Fixed
+- `agents/status-reporter.md`: milestone detection algorithm — uses `awk` to find first `##` heading with pending `###` slices (top-to-bottom scan), not `tail -5` of all `##` headings
+- `skills/ship-feature/SKILL.md`: `git log` now uses `--format="%h %<(50,trunc)%s"` to truncate long commit messages at 50 chars
+
+### Added
+- `agents/status-reporter.md`: PHASE 2 — best-effort build/test status check (pytest cache, Jest coverage, log files); `Tests` field in output
+- `doctor.sh`: `check_symlink "lib"` added; `_EXPECTED_LINKS` updated 6 → 7
+- `agents/plugin-advisor.md`: `skill-creation` signal added to PHASE 2; WARN rule if skill-creator active without skill-creation signal
+- `USAGE.md`: Exemple 9 — firmware C/C++ STM32, workflow minimaliste sans superpowers ni GSD
+
+### Changed
+- `version.txt`: 2.6.0 → 2.7.0
+
+## [2.6.0] — 2026-04-07
+
+### Fixed
+- `agents/status-reporter.md`: PHASE 3 now counts slices (### headings) not tasks (- [ ]) — correct progress metric matching GSD v2 dashboard
+- `hooks/session-start.sh`: continuation line uses 13-space prefix (verified 60 bytes) for consistent box alignment
+- `agents/onboarder.md`: PHASE 5b clarifies .gitignore target path per mode (A=workspace root, B=PACKAGE_ROOT, C=per-package)
+
+### Added
+- `skills/ship-feature/SKILL.md`: STEP 0b now prints PROJECT CONTEXT header when CLAUDE.md found — project name, stack, current branch, last 3 commits, GSD milestone
+- `USAGE.md`: Exemple 8 — full session resume workflow with /status + GSD v2 step mode + /gsd discuss
+
+### Changed
+- `version.txt`: 2.5.0 → 2.6.0
+
+## [2.5.0] — 2026-04-07
+
+### Fixed
+- `skills/init-project/SKILL.md`: STEP 1 — checks both `CLAUDE.md` and `.claude/CLAUDE.md`; pre-fills interview from either location
+- `agents/status-reporter.md`: PHASE 3 GSD — replaced fragile `STATUS.md` read with robust ROADMAP.md checkbox parsing; handles missing ROADMAP.md; never reads binary `state.db`
+- `agents/onboarder.md`: PHASE 5b added — .gitignore safety check; appends `.claude/settings.local.json` to existing .gitignore or creates minimal one; applies to all monorepo options
+
+### Added
+- `doctor.sh`: expected agents check in Consistency section — warns if any of 8 expected `.md` agent files are missing from `~/.claude/agents/`
+- `README.md` + `USAGE.md`: `/status` added to Pattern B (multi-session) and Pattern C (onboarding) workflows
+- `hooks/session-start.sh`: 2-line display for >4 active/inactive plugins — all plugin names shown, split at 4 per line
+
+### Changed
+- `version.txt`: 2.4.0 → 2.5.0
+
+## [2.4.0] — 2026-04-07
+
+### Fixed
+- `skills/init-project/SKILL.md`: STEP 1 — reads existing CLAUDE.md if present; pre-fills interview answers already documented; asks only genuinely missing fields
+- `agents/onboarder.md`: Option B fully implemented — explicit PACKAGE_ROOT scoping; all PHASE 3-5 paths relative to selected package; no root CLAUDE.md generated
+- `agents/plugin-advisor.md`: upstream monorepo detection in PHASE 1 — checks `../turbo.json`, `../pnpm-workspace.yaml`, `../../turbo.json` for sub-package context; signal table updated to describe upstream detection
+
+### Added
+- `agents/status-reporter.md` + `skills/status/SKILL.md`: new `/status` skill — consolidated read-only snapshot (plugins + token cost + git state + recent commits + GSD v2 milestone)
+- `USAGE.md`: section "Erreurs fréquentes" — quick-reference table of 14 common errors with causes and solutions
+- `doctor.sh`: symlink counter — reports `N/6 OK` after symlink checks
+- `hooks/session-start.sh`: `+N more` display — shows first 2 active/inactive plugins + count of remaining instead of truncated string
+- `README.md`: /status added to skill table and file tree
+
+### Changed
+- `version.txt`: 2.3.0 → 2.4.0
+
+## [2.3.0] — 2026-04-07
+
+### Fixed
+- `skills/ship-feature/SKILL.md`: STEP 0b added — checks for CLAUDE.md before starting; blocks with `/onboard` instruction if missing
+- `skills/ship-feature/SKILL.md`: STEP 4b option B enhanced — scans remaining tasks for dependents before skipping a failed task; prompts to skip dependent tasks too
+- `agents/onboarder.md`: Option C (sequential monorepo onboarding) fully implemented — iterates all packages, generates per-package CLAUDE.md + settings + .claudeignore, summary table, optional root ROADMAP.md
+- `agents/plugin-advisor.md`: `monorepo` signal added to PHASE 1 detection (turbo.json, pnpm-workspace, nx.json), PHASE 2 signal table, DECISION TABLE, and conditional rules — recommends plugins per-package, not for the whole repo
+- `doctor.sh`: `check_symlink "templates"` added — detects missing templates/ symlink (pre-v2.0.0 installations)
+- `hooks/session-start.sh`: ACTIVE_STR and INACTIVE_STR truncated to 37 chars + `…` indicator when overflow detected
+
+### Added
+- `USAGE.md`: Exemple 7 — refactoring module Python legacy; full `/analyze` → `/refactor` → `/analyze` cycle; shows report-before-modify behavior and test-first recommendation
+
+### Changed
+- `version.txt`: 2.2.0 → 2.3.0
+
+## [2.2.0] — 2026-04-07
+
+### Fixed (bugs identified via case study simulation)
+- `skills/init-project/SKILL.md`: STEP 13 — guard `command -v gsd` before running `gsd init`; prints install instructions if GSD v2 not in PATH instead of failing silently
+- `skills/ship-feature/SKILL.md`: STEP 4b added — structured error recovery when a subagent fails (build error, failing test, type error); DEBUG mode analysis + user gate before any fix; max 2 retry attempts; never auto-patches
+- `agents/onboarder.md`: monorepo detection added (PHASE 1) — detects `apps/`, `packages/`, `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`; interactive gate (onboard whole workspace / single package / each separately)
+- `agents/plugin-advisor.md`: `mobile` signal added to PHASE 2 signal table + DECISION TABLE + conditional rules — React Native / Expo / Flutter explicitly handled; gstack disabled for mobile, Docker N/A
+- `doctor.sh`: GStack `skills/` subdirectory check added after symlink verification — warns if GStack is symlinked but has no skills (needs `./setup`)
+- `hooks/session-start.sh`: TOKEN_WARN truncated to 44 chars to prevent box overflow with emoji width
+
+### Added
+- `USAGE.md`: Exemple 6 — CLI Rust from scratch; illustrates minimal workflow (superpowers only, no frontend plugins, cargo check as verify, no GSD v2)
+
+### Changed
+- `version.txt`: 2.1.0 → 2.2.0
+
+## [2.1.0] — 2026-04-07
+
+### Added
+- `agents/scaffolder.md`: React Native/Expo + Flutter support — PHASE 0 (Docker exclusion), PHASE 3 (stack templates), PHASE 4 (install commands), PHASE 5 (verify commands per stack)
+- `agents/analyzer.md`: DEBUG MODE section — structured error diagnosis with root cause hypotheses, trace, and affected files
+- `agents/onboarder.md`: new agent — onboard existing projects (discovery → interview → CLAUDE.md + settings + .claudeignore + optional GSD v2 ROADMAP)
+- `skills/onboard/SKILL.md`: new skill `/onboard` invoking the onboarder agent
+- `skills/init-project/SKILL.md`: STEP 13 (optional) — propose GSD v2 init at end of init-project when multi-session signal detected
+- `Makefile`: `make onboard` target
+- `README.md`: Workflow patterns section (5 patterns: new short, new long, onboarding, hotfix, refactor); /onboard in skill table and tree; make onboard in maintenance
+
+### Fixed
+- `agents/plugin-advisor.md`: "Next.js + context7 not configured" moved from BLOCK → WARN with force option — Context7 requires manual API key, should not hard-block project start
+- `lib/detect-plugins.sh`: `detect_ruflo()` now uses 3-level fallback (npm binary → MCP config grep + ruvnet/claude-flow variants → `claude mcp list`)
+- `hooks/session-start.sh`: passive token cost estimate added to session display — warns at >25%, alerts at >50% of Pro session budget
+
+### Changed
+- `version.txt`: 2.0.0 → 2.1.0
+
+## [2.0.0] — 2026-04-06
+
+### Breaking
+- GSD v1 (`glittercowboy/get-shit-done-cc`) removed entirely
+- GSD v1 commands (`/gsd:discuss-phase`, `/gsd:plan-phase`, `/gsd:execute-phase`, `/gsd:ship`, `/gsd:next`) no longer available — these were Claude Code slash commands; they do not exist in v2
+- GSD v2 (`gsd-pi`) is a standalone CLI (Pi SDK), not a Claude Code plugin — usage model is entirely different
+
+### Added
+- **GSD v2 integration** (`gsd-build/gsd-2`, npm: `gsd-pi` 2.64.0) — standalone CLI with autonomous mode (`/gsd auto`), state machine per-task execution, crash recovery, cost tracking, parallel workers, worktree isolation
+- **Ruflo plugin** (`ruvnet/ruflo`, npm: `ruflo` 3.5.58) — enterprise multi-agent MCP server (formerly claude-flow), 310+ tools, 100+ agent types, WASM kernel; 🔄 TOGGLE, ~500-1500t passive
+- **Full plugin compatibility matrix** in `agents/plugin-advisor.md` — all 12 plugins analyzed pairwise, conditional rules, recommended sets by project type
+- **Ruflo auto-detection** in `lib/detect-plugins.sh`, `doctor.sh`, `hooks/session-start.sh`
+- **GSD v2 CLI status** in `session-start.sh` — dedicated `🖥️  CLI` line (separate from CC plugin toggles)
+- **8 new deny rules** in `settings.json`: `source /dev/stdin`, `mkfifo *`, `python3 -c *`, `node -e *`, `xargs * .env*`, `tar * .env*`, `zip * .env*`, `base64 .env*` — covers runtime secret access and exfiltration vectors
+- **`disableAutoMode: "disable"`** added to global `settings.json` # TODO: VERIFY syntax in CC v2.1.89
+- **`templates/` symlink** in `link.sh` — `~/.claude/templates/` now resolves correctly for scaffolder and init-project
+- **Token budget breakdown** in `doctor.sh` — CLAUDE.md + skill descriptions + plugin passive cost, thresholds vs Pro session budget (~11k tokens/5h)
+- **GStack pinning warning** in `doctor.sh` and `update-all.sh` (confirmation prompt before `--remote` update)
+- **GStack false-positive fix** in `doctor.sh` — submodule check now requires `.git` presence, not just directory existence
+- Ruflo install instructions in `install-plugins.sh` (Step 5, manual — enterprise tool)
+- Ruflo update step in `update-all.sh`
+- GSD v2 update step in `update-all.sh`
+
+### Changed
+- `plugins.lock.json`: GSD v1 (`npm:get-shit-done-cc`) → GSD v2 (`npm:gsd-pi` 2.64.0); ruflo (`npm:ruflo` 3.5.58) added
+- `install-plugins.sh`: STEP 4 GSD v2 (`npm install -g gsd-pi`), STEP 5 ruflo (manual instructions), steps renumbered 6-7
+- `lib/detect-plugins.sh`: `detect_gsd()` now checks `command -v gsd` (not `~/.claude/skills/` grep); `detect_ruflo()` added
+- `doctor.sh`: GSD v2 check, ruflo check, GStack false-positive fix, GStack pinning warning, EXPECTED_DENY 92→100, token budget Pro-aware with breakdown, `readlink -f` portability fix
+- `hooks/session-start.sh`: GSD v2 removed from toggle loop → dedicated `🖥️  CLI` line; ruflo added to toggle loop
+- `update-all.sh`: GStack confirmation prompt, GSD v2 update step, ruflo update step, steps renumbered 1-7
+- `agents/plugin-advisor.md`: complete rewrite — PHASE 1 detection (GSD v2, ruflo), PHASE 2 signal table, full compatibility matrix, conditional rules, recommended sets by project type, WARN/BLOCK updated
+- `link.sh`: `templates/` added to symlink loop
+- `settings.json`: 92→100 deny rules, `disableAutoMode` added
+- `README.md`: comprehensive update — GSD v2 full usage guide, ruflo install/usage, plugin compatibility matrix section, updated plugin table (GSD v2 as CLI, ruflo as TOGGLE), version pinning examples, troubleshooting entries for GSD v2 and ruflo, Known Limitations updated
+- `version.txt`: 1.0.4 → 2.0.0
+
+### Fixed
+- `link.sh`: `templates/` not symlinked — scaffolder and init-project now find `~/.claude/templates/project-CLAUDE.md`
+- `doctor.sh`: GStack submodule check was a false positive when directory existed but submodule was uninitialised
+- `doctor.sh`: `readlink -f` fallback made explicit for BSD macOS compatibility
+- `doctor.sh`: token budget used incorrect "~8000 tokens" reference — now uses Pro session budget (~11k)
+- `doctor.sh`: EXPECTED_DENY hardcoded at 92 — updated to 100 after new deny rules
+- `update-all.sh`: GStack update had no confirmation prompt — added; GStack step structure had mismatched `if/fi`
+- `agents/plugin-advisor.md`: GSD detection used `ls ~/.claude/skills/ | grep gsd` — broken for v2 (CLI not a skill)
+- `hooks/session-start.sh`: GSD v2 (standalone CLI) was in the CC plugin toggle loop — incorrect, moved to dedicated CLI line
+
+## [1.0.4] — 2026-04-05
+
+### Fixed
+- `skills/*/SKILL.md`: agent paths changed from `.claude/agents/` to `$HOME/.claude/agents/` — unambiguous user-scope resolution regardless of working directory
+- `hooks/session-start.sh`: `CONFIG_VERSION` now displayed in session-start box (was computed but never shown)
+- `settings.json` + templates: removed non-standard `_readme` key (silently ignored by Claude Code but triggers schema warnings)
+- `agents/plugin-advisor.md`: RTK detection re-added in PHASE 1 (was removed in v1.0.3 compression)
+- `skills/health/SKILL.md`: fallback command simplified — removed 3-level quote nesting
+- `install-plugins.sh`: removed duplicate "→ Restart Claude Code" line
+
+### Changed
+- README: Superpowers command table now shows actual skill names (`superpowers:brainstorming`, `superpowers:writing-plans`, `superpowers:subagent-driven-development`, etc.)
+- README: install step 6 — replaced `/reload-plugins` (nonexistent command) with "Restart Claude Code — plugins load automatically"
+- README: Context7 API key URL corrected from `context7.com` to `upstash.com`
+- README: Known Limitations — clarified agent frontmatter fields ARE enforced in v2.1.x; added `disableAutoMode` note
+- README: Makefile command list in Maintenance section now includes `make new-skill`
+- `lib/detect-plugins.sh`: `detect_context7()` no longer spawns `claude` CLI — reads `~/.claude.json` and `~/.mcp.json` directly (no subprocess overhead at session start)
+
+## [1.0.3] — 2026-04-05
+
+### Token savings (~57% reduction across agents/skills)
+- `CLAUDE.md`: 1414t → 418t (-70%) — rewritten as dense rule list, no prose padding
+- `agents/plugin-advisor.md`: 1251t → 536t (-57%) — DECISION MATRIX removed (duplicated THRESHOLDS), output template compressed
+- `agents/interviewer.md`: 1088t → 438t (-60%) — PROJECT BRIEF ASCII art → compact YAML-style, question groups flattened
+- `agents/readme-updater.md`: 2224t → 792t (-64%) — Docker detection unified to one block, template skeleton condensed, phases as tight checklists
+- `agents/scaffolder.md`: 2402t → 1041t (-57%) — Dockerfile/compose templates replaced by 3-line descriptions, Phase 0 compressed
+- `skills/init-project/SKILL.md`: 2452t → 915t (-63%) — AGENTS LOADED section removed, each STEP condensed to 2-4 lines
+- `skills/ship-feature/SKILL.md`: 1236t → 537t (-57%) — same treatment as init-project
+
+### Changed behavior
+- `agents/interviewer.md`: if prompt already contains name + purpose + stack + features + architecture → generate BRIEF directly, no questions asked
+- `agents/readme-updater.md`: Docker detection defined once at top, referenced in all modes (no duplication)
+- `hooks/session-start.sh`: always-on plugins (security-guidance, rtk, superpowers) now explicitly shown in session start display
+- `skills/health/SKILL.md`: fallback path when `~/.claude/doctor.sh` not found (follows CLAUDE.md symlink to locate repo)
+- `skills/plugin-check/SKILL.md`: argument-hint now shows concrete example
+
+### Added
+- `Makefile`: `make new-skill name=<n>` — scaffolds agent + skill files from template in one command
+- `templates/project-CLAUDE.md`: inline examples per section (FastAPI-based) — usable without /init-project
+- README: bundled skills section (`/batch`, `/debug`, `/simplify`)
+- README: accurate progressive loading explanation (description only at startup, body on-demand)
+- `link.sh`: idempotent — reports "already up to date" or count of updated symlinks
+
+## [1.0.2] — 2026-04-04
+
+### Security
+- `Bash(git add .env*)` and `Bash(git add **/.env*)` added to deny — prevents staging secrets
+- `Bash(cp **/id_rsa*)`, `Bash(cp **/id_ed25519*)`, `Bash(cp **/.ssh/*)` added to deny — closes SSH key copy bypass
+- `deny` total: 87 → 92 rules
+- `npx *` moved from allow to ask in project template settings — arbitrary npm package execution now requires confirmation
+- `docker stop *` and `docker rm *` moved from allow to ask in project template settings
+
+### Changed
+- `skill-creator` and `pr-review-toolkit` reclassified from ALWAYS ON to TOGGLE — saves ~400 tokens/session by default
+- `agents/scaffolder.md`: removed Go, PHP/WordPress, Flutter/Dart stack templates (unused)
+- `CLAUDE.md`: STRICT MODE section removed — rules inlined into `skills/init-project/SKILL.md` and `skills/ship-feature/SKILL.md` where they apply, reducing global context weight
+- `CLAUDE.md`: FAIL FAST MODE cleaned up (removed contradictory "override all" claim)
+- `agents/readme-updater.md`: mode detection changed from substring match to exact first-word match — `/readme update X` no longer silently triggers SYNC mode
+- `templates/settings/SETTINGS.md`: stripped sections duplicating README (precedence table, what-goes-where) — 132 → 58 lines
+- `plugins.lock.json`: removed unused `install_cmd` and `node` fields
+- README: GStack 14-command table collapsed to a single reference line
+- README: plugin table updated to reflect new toggle status
+
+### Fixed
+- `install-plugins.sh`: GStack `./setup` now runs in subshell with existence+executable guard (same fix as update-all.sh)
+- `install-plugins.sh`: log setup guarded against read-only filesystem — no longer crashes before output
+- `install-plugins.sh`: `rtk init -g` now skipped if RTK hook already present in settings.json
+- `doctor.sh`: CRLF detection ported from `grep -qP` (Linux-only) to `grep -c $'\r'` (portable macOS/Linux)
+- `doctor.sh`: token budget breakdown now lists top consumers per file when estimate exceeds 2000 tokens
+- `lib/detect-plugins.sh`: removed three never-called functions (`detect_security_guidance`, `detect_skill_creator`, `detect_pr_review_toolkit`)
+- `hooks/session-start.sh`: removed unreachable inline fallback — replaced with clean exit message
+
+## [1.0.1] — 2026-04-03
+
+### Security
+- `env` and `printenv *` moved from allow to deny — blocks secret exposure via process environment
+- `export *` added to deny — prevents environment variable injection
+- `cp .env*`, `cp **/.env*`, `mv .env*`, `mv **/.env*` added to deny — closes copy-then-read bypass on secret files
+- `cp **/secrets/*`, `mv **/secrets/*` added to deny — extends secret move protection to secrets/ directory
+- `sed *` moved from allow to ask — all sed (including in-place `-i`) now requires confirmation
+- `sed -i *` and `sed -i'' *` removed from ask (consolidated into `sed *`)
+
+### Changed
+- `git stash*` (broad allow) split into safe variants in allow (`git stash`, `push*`, `list*`, `show*`) and destructive variants in ask (`pop*`, `drop*`, `clear`)
+- `doctor.sh` token budget estimate now uses full skill/agent file sizes instead of description-only char count — produces accurate token estimates (~4 chars/token)
+- `doctor.sh` deny rule count now checks against expected value (87) and warns on mismatch
+- `doctor.sh` python3 one-liner wrapped in `|| echo "?"` — diagnosis no longer crashes on missing python3
+
+### Fixed
+- `update-all.sh` GStack `./setup` now runs in a subshell — upstream setup failure no longer crashes the update script mid-execution under `set -euo pipefail`
+- `update-all.sh` guards `./setup` existence and executable bit before invoking it
+
 ## [1.0.0] — 2025-04-03
 
 ### Added
diff --git a/CLAUDE.md b/CLAUDE.md
index 640616a..92c2725 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,159 +1,58 @@
 # Global coding preferences
 
-Apply these preferences across all projects unless repository-specific
-instructions override them.
+Apply unless repo-specific instructions override.
 
-## General philosophy
+## Code style
 
-I prefer clean, readable, maintainable code with strong structural discipline,
-inspired by 42-style constraints but adapted pragmatically to each language,
-framework, and project.
+- Simple, readable, maintainable > clever or compact.
+- One responsibility per function/method.
+- Preserve existing behavior unless asked otherwise.
+- Scope changes to the task. No unrelated edits.
 
-These rules are important, but they are not absolute dogma:
-- apply them by default
-- report clearly when code does not follow them
-- if a deviation is justified, keep it and explain why
-- if a deviation is not clearly justified, ask whether it should be kept or fixed
+## Limits (adapt to language)
 
-## Design principles
+- Max 25 lines of logic per function (excl. comments, error handling).
+- Max 80 chars/line.
+- Max 5 params per function → group into a struct/object if more needed.
+- Max 5 local vars per function → split or extract.
+- No global state. Prefer explicit data flow.
 
-- Prefer simple, readable, maintainable code over clever or overly compact code.
-- Each function, method, or equivalent unit should have one clear responsibility.
-- Preserve existing behavior unless explicitly asked to change it.
-- Avoid unrelated changes during a fix or refactor.
-- Keep modifications scoped and intentional.
+## Comments
 
-## Function and method size
-
-- Prefer keeping the core logic of a function or method within 25 useful lines.
-- Empty lines do not count toward this limit.
-- Multi-line wrapped statements count as one logical instruction for this rule.
-- Error handling may extend the total size when necessary, but the main logic
-  should remain compact and easy to understand.
-- If a unit becomes too large, split it into small helpers.
-- Use private/internal/file-local helpers when the language supports them.
-
-## Line length
-
-- Prefer a maximum of 80 characters per line when reasonably possible.
-- If a line is too long, split it cleanly for readability.
-- Long calls, conditions, and expressions should be formatted clearly.
-
-## Parameters
-
-- Prefer no more than 5 parameters per function or method.
-- If more inputs are needed, group them into a meaningful structure adapted
-  to the language, such as an object, record, struct, dataclass, DTO,
-  config object, or equivalent.
-
-## Local variables
-
-- Prefer no more than 5 local variables per function or method.
-- If more local state is needed, consider:
-  - splitting the logic
-  - extracting a helper
-  - introducing a dedicated small structure adapted to the language
-
-## Shared and global state
-
-- Global state is discouraged.
-- Prefer explicit data flow through parameters, return values, objects,
-  context structures, dependency injection, or another justified mechanism.
-- If shared or global state is used, mention it explicitly and justify it.
-
-## Comments and documentation
-
-- Functions and methods should be documented when their purpose, parameters,
-  return value, or intent are not immediately obvious.
-- The comment should help explain intent and usage, not restate the code line by line.
-- Apply the documentation style that fits the language and project conventions
-  (docstring, block comment, JSDoc, Doxygen, XML docs, etc.).
-- Internal/private helpers are not exempt if their role is unclear.
+- Document purpose/intent when not obvious. Not line-by-line restating.
+- Use the project's doc style (docstring, JSDoc, Doxygen, etc.).
 
 ## Readability
 
-- Use explicit, consistent, and meaningful names.
-- Prefer straightforward control flow.
-- Simplify or extract complex conditions.
-- Avoid hidden side effects unless clearly necessary.
-- Prefer code that is easy to review, test, and modify.
+- Explicit, consistent, meaningful names.
+- Straight control flow. Extract complex conditions.
+- No hidden side effects.
 
-## Refactoring and modifications
+## Refactoring
 
-- During refactoring, prioritize:
-  1. safety
-  2. readability
-  3. consistency with the project
-- Keep behavior unchanged unless explicitly asked otherwise.
-- After modifying a function, feature, or behavior, verify that no residue from
-  the previous implementation remains.
-- Remove obsolete code, dead branches, unused helpers, stale flags, outdated
-  comments, legacy conditions, and old-version leftovers when they are no longer needed.
-- If something from the previous implementation is intentionally retained,
-  explain why.
+- Priority: safety → readability → consistency.
+- Remove dead code, obsolete comments, stale flags after changes.
+- After modifying behavior: verify no old residue remains.
 
-## Handling deviations from the standard
+## Deviations
 
-- Treat these rules as strong preferences, not rigid mechanical laws.
-- If existing code is outside the standard, report it clearly.
-- If the deviation is minor and acceptable, mention it briefly.
-- If the deviation is significant and not obviously justified, ask whether to:
-  - keep the deviation
-  - or refactor toward compliance
-- If a deviation is clearly justified by language constraints, framework style,
-  performance needs, safety requirements, or project architecture, keep it and explain it.
+- Report deviations from the above clearly.
+- Minor/justified → keep and explain.
+- Significant/unjustified → ask: keep or fix?
 
-## Language adaptation
+## After code changes
 
-- Adapt these rules to the language and ecosystem instead of applying C/C++
-  terminology blindly.
-- Interpret "function" broadly as the relevant unit of logic:
-  function, method, procedure, hook, handler, endpoint, callback, class method, etc.
-- Interpret "structure" broadly as any suitable grouping construct:
-  struct, object, class, record, dataclass, DTO, tuple wrapper, options object,
-  config object, context object, or equivalent.
+1. Run tests, lint, build, type-check if available.
+2. Report what was verified / what wasn't.
+3. List remaining risks and any surviving deviations.
 
-## Expected workflow after code changes
+## When working on code
 
-After making changes, when applicable:
-1. run relevant tests
-2. run lint, format, build, and type-check steps if available
-3. report what was verified
-4. report what could not be verified
-5. summarize remaining risks or uncertainties
-6. mention any remaining deviation from these preferences
-7. confirm whether old implementation residue remains or has been removed
+- Analyze before changing. Brief plan first.
+- Minimal changes unless broader refactor requested.
+- State trade-offs clearly.
 
-## Interaction preferences
+## FAIL FAST
 
-When working on code:
-- first analyze before changing
-- explain the plan briefly
-- keep changes minimal unless a broader refactor is requested
-- mention trade-offs clearly
-- after changes, summarize what was done and what remains uncertain
-
-## STRICT MODE
-
-These rules are always active in orchestrator skills (/init-project,
-/ship-feature) and during code review. They apply automatically.
-
-These rules override all other instructions.
-
-- Never skip workflow steps
-- Never merge agent responsibilities
-- Always enforce user validation before implementation
-- Always run review loop until no CRITICAL issues remain
-- Stop execution if requirements are unclear
-
-## FAIL FAST MODE
-
-These rules are always active in every interaction. They apply automatically.
-
-These rules override all other instructions.
-
-- Stop immediately if requirements are unclear
-- Ask clarifying questions instead of guessing
-- Do not invent missing context
-- Do not proceed with partial understanding
-- Explicitly list unknowns before continuing
\ No newline at end of file
+- Stop if requirements are unclear. Ask, don't guess.
+- No invented context. List unknowns before continuing.
diff --git a/Makefile b/Makefile
index 9076064..fe27f4a 100644
--- a/Makefile
+++ b/Makefile
@@ -1,12 +1,12 @@
-.PHONY: help install link doctor update
+.PHONY: help install link doctor update new-skill
 
 help: ## Show available commands
-	@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf "  make %-12s %s\n", $$1, $$2}'
+	@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf "  make %-14s %s\n", $$1, $$2}'
 
 install: link ## Full install: symlinks + prerequisites + plugins
 	bash install-plugins.sh
 
-link: ## Create symlinks into ~/.claude/
+link: ## Create/update symlinks into ~/.claude/
 	bash link.sh
 
 doctor: ## Run setup diagnostic
@@ -14,3 +14,20 @@ doctor: ## Run setup diagnostic
 
 update: ## Update config, submodules, plugins, and verify
 	bash update-all.sh
+
+onboard: link ## Onboard an existing project (run from the project directory)
+	@echo "Open Claude Code in your project directory and run: /onboard"
+	@echo "Or with hints: /onboard Python FastAPI monorepo"
+
+new-skill: ## Create a new skill scaffold (usage: make new-skill name=myskill)
+	@test -n "$(name)" || (echo "Usage: make new-skill name=myskill" && exit 1)
+	@mkdir -p agents skills/$(name)
+	@if [ ! -f agents/$(name).md ]; then \
+		printf -- '---\nname: $(name)\ndescription: <what this agent does — keep under 200 chars>\ntools: Read, Grep, Glob, Bash\nmodel: sonnet\n---\n\n# $(name)\n\n## ROLE\n<role>\n\n## TASKS\n- <task>\n\n## RULES\n- <rule>\n\n## OUTPUT\n```\n<format>\n```\n' > agents/$(name).md; \
+		echo "✅ Created agents/$(name).md"; \
+	else echo "⚠️  agents/$(name).md already exists"; fi
+	@if [ ! -f skills/$(name)/SKILL.md ]; then \
+		printf -- '---\nname: $(name)\ndescription: <what this skill does — front-load key use case, max 250 chars>\nargument-hint: <what to pass>\ndisable-model-invocation: true\nallowed-tools: Read, Grep, Glob, Bash\n---\n\nLoad and follow strictly:\n- .claude/agents/$(name).md\n\nExecute on:\n\n$$ARGUMENTS\n' > skills/$(name)/SKILL.md; \
+		echo "✅ Created skills/$(name)/SKILL.md"; \
+	else echo "⚠️  skills/$(name)/SKILL.md already exists"; fi
+	@echo "   Edit both files, then run: bash link.sh"
diff --git a/README.md b/README.md
index e5288d6..73cdd23 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,8 @@
 
 Global Claude Code configuration — agents, skills, plugins, and project templates.
 
+> **Guide d'utilisation complet :** voir [`USAGE.md`](./USAGE.md) — workflows typiques, exemples par type de projet (mobile, web, CLI, firmware, monorepo), arbre de décision "quel skill utiliser ?", cas de figure validés, et table des erreurs fréquentes.
+
 ---
 
 ## Overview
@@ -11,13 +13,13 @@ This repo is your personal Claude Code setup, versioned and reproducible across
 ```
 claude-config/
 ├── CLAUDE.md              # Global coding preferences (style, rules, workflow)
-├── settings.json          # Global permissions (77 deny / 16 ask / 57 allow rules)
+├── settings.json          # Global permissions (100 deny / 18 ask / 57 allow rules)
 ├── install-plugins.sh     # One-shot installer: prerequisites + all plugins (reads plugins.lock.json)
 ├── link.sh                # Symlinks this repo into ~/.claude/
 ├── doctor.sh              # Setup diagnostic — checks symlinks, plugins, permissions, token budget
 ├── update-all.sh          # One-command update for all components
 ├── Makefile               # Unified entry point: make install / doctor / update
-├── plugins.lock.json      # Version pinning for non-marketplace dependencies (RTK, GSD)
+├── plugins.lock.json      # Version pinning for non-marketplace dependencies (RTK, GSD v2, ruflo)
 ├── version.txt            # Semver version of this config
 ├── CHANGELOG.md           # Release history
 ├── lib/
@@ -30,7 +32,9 @@ claude-config/
 ├── agents/
 │   ├── analyzer.md        # Factual codebase analysis (read-only)
 │   ├── interviewer.md     # Project questionnaire → PROJECT BRIEF
-│   ├── plugin-advisor.md  # Plugin check: detect mismatches, block if Superpowers missing
+│   ├── onboarder.md       # Onboard existing project — CLAUDE.md, settings, optional GSD ROADMAP
+│   ├── status-reporter.md  # Consolidated project status — read-only snapshot
+│   ├── plugin-advisor.md  # Plugin check: detect signals, apply compatibility matrix, block if needed
 │   ├── readme-updater.md  # Update README from git history + codebase
 │   ├── refactorer.md      # Surgical refactoring with norm enforcement
 │   └── scaffolder.md      # Full project generation (CLAUDE.md, README, code)
@@ -38,6 +42,8 @@ claude-config/
 │   ├── analyze/           # /analyze — deep factual analysis
 │   ├── health/            # /health — run setup diagnostic
 │   ├── init-project/      # /init-project — full project initialization
+│   ├── onboard/           # /onboard — onboard existing project into claude-config
+│   ├── status/            # /status — consolidated project snapshot
 │   ├── plugin-check/      # /plugin-check — check plugin config vs project needs
 │   ├── readme/            # /readme — update README from current state
 │   ├── refactor/          # /refactor — improve code without changing behavior
@@ -48,15 +54,16 @@ claude-config/
         ├── settings.json         # Template for project .claude/settings.json
         ├── settings.local.json   # Template for personal .claude/settings.local.json
         ├── .claudeignore         # Template for project .claudeignore
-        └── SETTINGS.md           # Full settings reference
+        └── SETTINGS.md           # Rule syntax reference (rule types, patterns, defaultMode values)
 ```
 
 **Architecture principle:**
 - `skills/` = entry points you invoke via `/skill-name`
 - `agents/` = execution units called by skills (never invoked directly by user)
 - `lib/` = shared shell functions sourced by scripts (plugin detection)
+- `templates/` = symlinked to `~/.claude/templates/` — copy into projects via per-project setup
 - Custom skills use **Superpowers** agents for implementation phases (required — auto-detected)
-- **Plugins** (Superpowers, GStack, GSD, etc.) install separately and complement custom skills
+- **Plugins** (Superpowers, GStack, GSD v2, ruflo, etc.) install separately and complement custom skills
 
 ---
 
@@ -73,23 +80,23 @@ bash link.sh
 # 3. Install prerequisites + all plugins (detects OS, reads pinned versions from plugins.lock.json)
 bash install-plugins.sh
 
-# 4. Add Context7 API key (free at context7.com) — manual step
+# 4. Add Context7 API key (free at upstash.com) — manual step
 claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key YOUR_KEY
 
 # 5. Verify setup
 bash doctor.sh
 
-# 6. Restart Claude Code then run /reload-plugins
+# 6. Restart Claude Code — plugins load automatically
 ```
 
 All scripts use their own location to find the repo — run them from anywhere or from the repo directory.
 Symlinks point to the repo's actual path, so renaming or moving the repo requires re-running `bash link.sh`.
 
-The install script handles: git, Node.js 22, Rust/Cargo, Python 3, RTK, GStack (submodule), GSD,
+The install script handles: git, Node.js 22, Rust/Cargo, Python 3, RTK, GStack (submodule), GSD v2,
 and all marketplace plugins on Linux (apt/dnf/pacman) and macOS (brew).
 
-RTK and GSD versions are pinned in `plugins.lock.json`. The install script reads those
-versions automatically. Marketplace plugins install to `~/.claude/plugins/` (user scope).
+RTK and GSD v2 versions are pinned in `plugins.lock.json`. The install script reads those versions
+automatically. Marketplace plugins install to `~/.claude/plugins/` (user scope).
 
 Install output is logged to `install-YYYYMMDD-HHMMSS.log` in the repo directory for post-mortem debugging.
 
@@ -108,6 +115,7 @@ Install output is logged to `install-YYYYMMDD-HHMMSS.log` in the repo directory
 | `/init-project` | Initialize a complete project from scratch (full orchestrator) |
 | `/ship-feature` | Ship a feature end-to-end with validation gates (full orchestrator) |
 | `/health` | Run setup diagnostic — check symlinks, plugins, permissions, token budget |
+| `/onboard` | Onboard an existing project — generate CLAUDE.md, settings, optional GSD v2 ROADMAP |
 
 ### Superpowers skills (auto-invoked or explicit)
 
@@ -116,47 +124,100 @@ Install output is logged to `install-YYYYMMDD-HHMMSS.log` in the repo directory
 
 | Command | When it auto-activates |
 |---|---|
-| `/superpowers:brainstorm` | When you describe something to build |
-| `/superpowers:write-plan` | After design is approved |
-| `/superpowers:execute-plan` | With an approved plan |
-| `systematic-debugging` | Auto — when debugging |
-| `test-driven-development` | Auto — when implementing |
-| `requesting-code-review` | Auto — after a feature step |
+| `superpowers:brainstorming` | When you describe something to build |
+| `superpowers:writing-plans` | After design is approved |
+| `superpowers:subagent-driven-development` | With an approved plan |
+| `superpowers:requesting-code-review` | Auto — after a feature step |
+| `superpowers:finishing-a-development-branch` | After review is approved |
 
 ### GStack skills (Garry Tan — full-product projects only)
 
 > Installed as a git submodule at `skills-external/gstack/`, symlinked to `~/.claude/skills/gstack/`.
 > **Use when:** project has UI + design + deploy + browser QA. Skip for backend/lib/CLI projects.
+> Full command reference: `~/.claude/skills/gstack/README.md` or run `/office-hours` to start.
+
+### GSD v2 — standalone CLI (multi-session large features)
+
+> **Architecture change from v1:** GSD v2 (`gsd-pi`) is a standalone TypeScript CLI built on the Pi SDK.
+> It is **not** a Claude Code plugin — it runs as an external process with its own session management.
+> The `/gsd ...` commands are GSD-internal and are typed inside a `gsd` terminal session, not in Claude Code.
+>
+> **Install:** `npm install -g gsd-pi` (pinned version in `plugins.lock.json`)
+>
+> **Use when:** a feature spans multiple days/sessions, you need crash recovery, cost tracking per unit,
+> parallel workers across milestones, or automatic context-fresh execution per task.
+
+```bash
+# Start a GSD session in your terminal (from your project directory)
+gsd
+
+# Or jump straight to autonomous mode — walk away and come back to built software
+gsd          # then inside the session:
+/gsd auto    # autonomous mode: research → plan → execute → commit → repeat
+/gsd         # step mode: pause between each unit for review
+/gsd status  # progress dashboard
+/gsd discuss # talk through architecture decisions
+/gsd quick   # atomic quick task without full planning overhead
+```
+
+**Key commands inside a GSD session:**
 
 | Command | Description |
 |---|---|
-| `/office-hours` | Discovery consultant — scope and challenge before code |
-| `/plan-ceo-review` | CEO challenges product scope and feature value |
-| `/plan-eng-review` | Staff engineer locks architecture decisions |
-| `/design-consultation` | Build a design system from scratch |
-| `/design-shotgun` | Generate multiple visual variants for comparison |
-| `/design-html` | Turn approved mockup into production HTML |
-| `/review` | Code review (GStack version) |
-| `/ship` | One-command: test → build → deploy |
-| `/qa` | QA with real Chrome browser automation |
-| `/browse` | Headless Chrome web navigation |
-| `/careful` | Activate safety guardrails |
-| `/freeze` | Lock edits to current directory |
-| `/retro` | Engineering retrospective |
-| `/gstack-upgrade` | Self-update GStack |
+| `/gsd auto` | Autonomous mode — research, plan, execute, commit, repeat until milestone done |
+| `/gsd` or `/gsd next` | Step mode — execute one unit at a time, pause between each |
+| `/gsd quick` | Quick atomic task with GSD guarantees (no full planning overhead) |
+| `/gsd stop` | Stop auto mode gracefully |
+| `/gsd status` | Progress dashboard (token usage, cost, milestone progress) |
+| `/gsd discuss` | Discuss architecture decisions (works alongside auto mode) |
+| `/gsd steer` | Hard-steer plan documents during execution |
+| `/gsd prefs` | Model selection, timeouts, budget ceiling |
+| `/gsd doctor` | Runtime health checks |
+| `/gsd migrate` | Migrate a v1 `.planning` directory to `.gsd` format |
+| `/gsd export --html` | Generate self-contained HTML report for a milestone |
+| `/worktree` | Git worktree lifecycle — create, switch, merge, remove |
 
-### GSD skills (glittercowboy — multi-session large features)
+**GSD v2 vs v1:**
 
-> Install: `npx get-shit-done-cc --claude --global`
-> **Use when:** feature spans multiple days/sessions. Each session starts fresh with full context from previous phases.
+| | v1 (deprecated) | v2 (current) |
+|---|---|---|
+| Runtime | Claude Code slash commands | Standalone CLI (Pi SDK) |
+| Context management | None — fills up | Fresh session per task |
+| Auto mode | LLM self-loop | State machine with `.gsd/` files |
+| Crash recovery | None | Lock files + session forensics |
+| Cost tracking | None | Per-unit token/cost ledger |
+| Git strategy | LLM writes git commands | Worktree isolation, squash merge |
+
+### Ruflo MCP (enterprise multi-agent orchestration)
+
+> Ruflo (formerly claude-flow) is a heavy enterprise MCP server — 310+ tools, 100+ agent types,
+> WASM kernel, self-learning architecture. ~500-1500 tokens passive cost when active.
+>
+> **Use when:** project explicitly requires coordinating 5+ specialized agents simultaneously,
+> parallel swarm execution, or enterprise-grade multi-agent orchestration.
+> **For standard multi-session work, GSD v2 is sufficient and much lighter.**
+>
+> **Install:**
+> ```bash
+> # Full install (~340MB)
+> npm install -g ruflo@latest
+> # Or minimal (faster, no ML/embeddings)
+> npm install -g ruflo@latest --omit=optional
+>
+> # Register as MCP server in Claude Code
+> claude mcp add --scope user ruflo -- npx ruflo mcp start
+>
+> # Verify
+> claude mcp list | grep ruflo
+> ```
+
+### Bundled skills (Claude Code built-in, always available)
 
 | Command | Description |
 |---|---|
-| `/gsd:discuss-phase` | Refine spec for a phase through conversation |
-| `/gsd:plan-phase` | Generate hierarchical phase plan |
-| `/gsd:execute-phase` | Execute phase in an isolated context window |
-| `/gsd:ship` | Create PR from verified work |
-| `/gsd:next` | Auto-advance to the next phase |
+| `/batch <instruction>` | Large-scale parallel refactoring — decomposes into 5–30 units, spawns one background agent per unit in isolated git worktrees |
+| `/debug [description]` | Enable debug logging for the session, analyze the session debug log |
+| `/simplify [focus]` | Review recent changes for code reuse, quality, efficiency issues |
 
 ### Other plugin commands
 
@@ -167,6 +228,68 @@ Install output is logged to `install-YYYYMMDD-HHMMSS.log` in the repo directory
 
 ---
 
+## Workflow patterns
+
+### Pattern A — Nouveau projet (court, 1 session)
+```
+/plugin-check "description"   → configure plugins
+/init-project "description"   → interview → scaffold → implement v1
+/ship-feature "feature"       → ship feature by feature
+```
+
+### Pattern B — Nouveau projet (long, multi-session)
+```
+/plugin-check "description"
+/init-project "description"   → à la fin, STEP 13 propose d'init GSD v2
+                                 → répondre "yes"
+# Ensuite dans un terminal :
+gsd                            → démarrer une session GSD
+/gsd auto                      → mode autonome — walk away
+/gsd status                    → vérifier la progression
+/gsd discuss                   → décisions d'architecture en cours de route
+```
+**À chaque reprise de session :**
+```
+/status                        → snapshot : plugins, token, git state, milestone GSD en cours
+```
+
+### Pattern C — Projet existant (onboarding)
+```
+cd mon-projet-existant/
+# Dans Claude Code :
+/onboard                       → génère CLAUDE.md + settings + .claudeignore
+                                 → optionnel : ROADMAP.md pour GSD v2
+/status                        → confirmer que l'onboarding est complet + état du projet
+/plugin-check "type de projet"
+/ship-feature "prochaine feature"
+```
+
+### Pattern D — Hotfix / modification ponctuelle
+```
+# Pas de /init-project, pas de GSD
+/analyze src/module-cible.py   → rapport factuel sans solution
+/ship-feature "corriger X"     → brainstorm + plan + gate + impl + review
+```
+
+### Pattern E — Refactoring ciblé
+```
+/analyze src/legacy.py         → liste les violations
+/refactor src/legacy.py        → corrections sans changement de comportement
+```
+
+### Choisir entre /ship-feature et gsd auto
+
+| Critère | /ship-feature | gsd auto |
+|---|---|---|
+| Durée estimée | < 1 journée | > 1 journée |
+| Nombre de tâches | < 10 | > 10 |
+| Crash recovery nécessaire | non | oui |
+| Suivi de coût par tâche | non | oui |
+| Workers parallèles | non | oui (parallel mode) |
+| Contexte fresh par tâche | non (même session) | oui (Pi SDK) |
+
+---
+
 ## Orchestrators in detail
 
 ### `/init-project`
@@ -224,41 +347,77 @@ against what you're about to do. Also embedded as STEP 0 in both orchestrators.
 
 Blocks if Superpowers is not active (required by orchestrators).
 Blocks if critical project-specific plugins are missing (frontend tools, Context7, GStack).
+Warns if ruflo is active with no multi-agent signal, or if GSD v2 CLI is not installed for multi-session work.
 
 ```
 /plugin-check "I want to build a React + FastAPI SaaS"
 
 → Detects active plugins
-→ Analyzes signals: frontend? design? QA? multi-session? fast-evolving libs?
-→ Produces recommendation table
-→ Blocks with OPTIONS if critical plugins are missing (including Superpowers)
+→ Scans filesystem for project signals (frontend? design? deploy? multi-agent?)
+→ Applies compatibility matrix
+→ Produces recommendation table with passive cost estimate
+→ Warns about plugin conflicts (gstack + ruflo, etc.)
+→ Blocks with OPTIONS if critical plugins are missing
 → Or confirms "proceed" if config is optimal
 ```
 
 ---
 
+## Plugin compatibility matrix
+
+### Quick reference
+
+| Pair | Relation | Notes |
+|---|---|---|
+| frontend-design ↔ ui-ux-pro-max | ⚠️ Overlap | Keep both for design-heavy. Drop ui-ux-pro-max for simple UI. |
+| gstack ↔ gsd v2 | ✅ Complementary | Different scopes — CC workflow vs CLI orchestration |
+| gstack ↔ ruflo | ⚠️ Overlap | Both orchestrate multi-step work. Use one or the other. ~3250-4250t combined. |
+| gsd v2 ↔ ruflo | ⚠️ Overlap | Sequential (GSD) vs parallel swarm (ruflo). Pick based on need. |
+| superpowers ↔ gsd v2 | ✅ Complementary | Single-session engine + multi-session CLI = no conflict |
+| superpowers ↔ gstack | ✅ Complementary | Used together by orchestrators |
+| context7 ↔ any | ✅ Independent | Doc lookup MCP — always safe to combine |
+
+### Recommended sets by project type
+
+| Project type | Plugins ON | OFF | Passive cost |
+|---|---|---|---|
+| Backend API / microservice | superpowers, context7* | frontend-design, ui-ux-pro-max, gstack, ruflo | ~800t |
+| Frontend SPA / SSR | superpowers, frontend-design, ui-ux-pro-max, context7 | gstack, ruflo | ~1600t |
+| Full-stack SaaS | superpowers, gstack, frontend-design, ui-ux-pro-max, context7 | ruflo | ~4400t |
+| CLI tool / library | superpowers | all toggles | ~800t |
+| Multi-session large feature | superpowers + gsd v2 CLI (external) | ruflo | ~800t CC |
+| Quick fix / hotfix | superpowers | all toggles | ~800t |
+| Design system / component lib | superpowers, frontend-design, ui-ux-pro-max | gstack, ruflo, gsd | ~1600t |
+| Enterprise multi-agent | superpowers, ruflo + gsd v2 CLI (external) | others | ~2300t CC |
+
+> *context7 only if using fast-evolving libs (Next.js, React 18+, Prisma, Supabase)
+> security-guidance and rtk are ALWAYS ON (0 tokens) — omitted from estimates
+
+---
+
 ## Plugins reference
 
 All plugins below are installed by `install-plugins.sh`.
 
-### Quick reference
+### How loading works
 
-The mechanism: Claude Code loads every active skill's **description** into a shared context budget
-at session start (default 8000 chars). Even if you never invoke the skill, its description
-is already consuming tokens. **Disabling a plugin prevents its descriptions from loading entirely.**
+Only each skill's `description` field is pre-loaded into the system prompt at session start —
+the full skill body is loaded on demand when the skill is invoked. `CLAUDE.md` is the only file
+loaded in full at every session. Disabling a plugin prevents even its description from loading.
 
-A `hooks/session-start.sh` hook shows the current toggle status at the start of every session.
-Run `/plugin-check` anytime to get a full recommendation for the current project type.
+A `hooks/session-start.sh` hook shows plugin toggle status at every session start.
+Run `/plugin-check` anytime to get a recommendation for the current project type.
 
-| Plugin | Status | Passive cost | When to toggle ON | Installed by |
+| Plugin | Status | Passive cost | When to use | Installed by |
 |---|---|---|---|---|
 | **security-guidance** | ✅ ALWAYS ON | 0 tokens (hook only) | — | marketplace |
 | **RTK** | ✅ ALWAYS ON | 0 tokens (hook only) | — | cargo (pinned in plugins.lock.json) |
-| **Superpowers** | ✅ REQUIRED | ~600–1000 tokens | — required by orchestrators, auto-detected | marketplace |
-| **skill-creator** | ✅ ALWAYS ON | ~100 tokens | — | marketplace |
-| **pr-review-toolkit** | ✅ ALWAYS ON | ~300 tokens | — use `/pr-review-toolkit:review-pr` | marketplace |
+| **Superpowers** | ✅ REQUIRED | ~600–1000 tokens | — required by orchestrators | marketplace |
 | **GStack** | 🔄 TOGGLE | ~2500–3000 tokens | Full-product: UI + design + deploy + browser QA | git submodule |
-| **GSD** | 🔄 TOGGLE | ~500–800 tokens | Feature spanning multiple days/sessions | npx (pinned in plugins.lock.json) |
+| **GSD v2** | 🖥️ CLI | 0 tokens (external CLI) | Multi-day features, crash recovery, cost tracking, parallel workers | npm (pinned in plugins.lock.json) |
+| **ruflo** | 🔄 TOGGLE | ~500–1500 tokens | Enterprise multi-agent swarm (5+ concurrent agents) | npm + MCP manual |
+| **skill-creator** | 🔄 TOGGLE | ~100 tokens | Creating or editing custom skills | marketplace |
+| **pr-review-toolkit** | 🔄 TOGGLE | ~300 tokens | PR review sessions | marketplace |
 | **frontend-design** | 🔄 TOGGLE | ~200 tokens | Any project with a UI | marketplace |
 | **ui-ux-pro-max** | 🔄 TOGGLE | ~400 tokens | Design system, color/typography choices | marketplace |
 | **Context7 MCP** | 🔄 TOGGLE | ~200 tokens | Fast-evolving libs (Next.js, React, Prisma…) | MCP manual |
@@ -269,12 +428,13 @@ and **blocks if Superpowers is not active**.
 
 ### Version pinning
 
-RTK and GSD versions are pinned in `plugins.lock.json`:
+RTK, GSD v2, and ruflo versions are pinned in `plugins.lock.json`:
 
 ```json
 {
-  "rtk": { "version": "v0.34.3" },
-  "gsd": { "version": "1.30.0" }
+  "rtk":   { "source": "https://github.com/rtk-ai/rtk", "version": "v0.34.3" },
+  "gsd":   { "source": "npm:gsd-pi",  "version": "2.64.0" },
+  "ruflo": { "source": "npm:ruflo",   "version": "3.5.58" }
 }
 ```
 
@@ -294,26 +454,7 @@ Or in the project's `.claude/settings.json`:
 ```json
 {
   "enabledPlugins": {
-    "gstack@gstack": false,
-    "gsd@gsd": false
-  }
-}
-```
-
-### Enabling a plugin for a specific project (so teammates can install it)
-
-```json
-{
-  "enabledPlugins": {
-    "ui-ux-pro-max@ui-ux-pro-max-skill": true
-  },
-  "extraKnownMarketplaces": {
-    "ui-ux-pro-max-skill": {
-      "source": {
-        "source": "github",
-        "repo": "nextlevelbuilder/ui-ux-pro-max-skill"
-      }
-    }
+    "gstack@gstack": false
   }
 }
 ```
@@ -339,20 +480,27 @@ DENY always wins over ALLOW at any level.
 
 ### Global settings (this repo's `settings.json`)
 
-77 deny rules, 16 ask rules, 57 allow rules.
+100 deny rules, 18 ask rules, 57 allow rules.
 
 | Section | Purpose |
 |---|---|
 | `deny` — secrets (Read) | Blocks `Read` on `.env`, `.pem`, `.key`, SSH keys, cloud credentials |
 | `deny` — secrets (Bash) | Blocks `cat`, `head`, `tail`, `grep`, `less`, `more` on `.env` and secret files |
+| `deny` — env leak | Blocks `env`, `printenv`, `export *` — prevents secret exposure via process environment |
+| `deny` — secret move | Blocks `cp`/`mv` on `.env*` and `secrets/` — closes copy-then-read bypass |
 | `deny` — destructive | Blocks `rm -rf`, `git push --force`, `chmod 777` |
 | `deny` — system | Blocks `sudo`, `ssh`, `scp`, `crontab`, `systemctl` |
 | `deny` — injection | Blocks `curl \| bash`, `wget \| sh` |
 | `deny` — escalation | Blocks `bash -c`, `eval`, `exec`, `find -delete`, `perl -e`, `ruby -e` |
+| `deny` — runtime exec | Blocks `python3 -c *`, `node -e *`, `source /dev/stdin`, `mkfifo *` |
+| `deny` — exfiltration | Blocks `xargs * .env*`, `tar * .env*`, `zip * .env*`, `base64 .env*` |
 | `ask` — risky | Prompts before `git push`, `docker run`, package managers |
-| `ask` — write tools | Prompts before `xargs`, `sed -i` (in-place file editing) |
-| `allow` — safe reads | Auto-approves git read-only, `ls`, `cat`, `grep`, `find`, `sed` (stdout only) |
+| `ask` — write tools | Prompts before `xargs`, all `sed` (including in-place) |
+| `ask` — stash destructive | Prompts before `git stash pop`, `drop`, `clear` |
+| `allow` — safe reads | Auto-approves git read-only, `ls`, `cat`, `grep`, `find` |
+| `allow` — stash safe | Auto-approves `git stash` (push), `list`, `show` |
 | `disableBypassPermissionsMode` | Prevents YOLO mode globally |
+| `disableAutoMode` | Prevents auto mode globally |
 
 ### Per-project setup
 
@@ -374,7 +522,7 @@ echo ".claude/settings.local.json" >> .gitignore
 cp "$CONF/templates/settings/.claudeignore" .claudeignore
 
 # Project CLAUDE.md (commit to project git)
-cp "$CONF/templates/project-CLAUDE.md" .claude/CLAUDE.md
+cp "$CONF/templates/project-CLAUDE.md" CLAUDE.md
 ```
 
 ---
@@ -386,14 +534,14 @@ cp "$CONF/templates/project-CLAUDE.md" .claude/CLAUDE.md
 ```bash
 # From the repo directory
 bash update-all.sh
-# Pulls config, updates GStack submodule, updates RTK (pinned version), refreshes symlinks, runs doctor
+# Pulls config, prompts before updating GStack (tracks main), updates RTK + GSD v2 (pinned),
+# updates ruflo if installed, refreshes symlinks, runs doctor
 ```
 
 ### Manual updates
 
 #### This repo
 ```bash
-# cd into the repo (wherever you cloned it)
 git pull
 # Symlinks → changes active immediately
 ```
@@ -404,23 +552,40 @@ git pull
 /gstack-upgrade
 
 # Option B — via submodule (from the repo directory)
+# Note: GStack tracks branch = main, review upstream commits before updating
 git submodule update --remote skills-external/gstack
 cd skills-external/gstack && ./setup
 git add skills-external/gstack
 git commit -m "chore: update gstack to latest"
 ```
 
-GStack is a git submodule. Its version is pinned in your config repo — reproducible on every machine.
-
 #### RTK
 ```bash
-# Uses the version pinned in plugins.lock.json (from the repo directory)
+# Uses the version pinned in plugins.lock.json
 bash update-all.sh
 
-# Or manually (check latest at https://github.com/rtk-ai/rtk/releases)
+# Or manually
 cargo install --git https://github.com/rtk-ai/rtk --tag v0.34.3 --force
 ```
 
+#### GSD v2
+```bash
+# Uses the version pinned in plugins.lock.json
+bash update-all.sh
+
+# Or manually
+npm install -g gsd-pi@2.64.0
+```
+
+#### Ruflo MCP
+```bash
+# Uses the version pinned in plugins.lock.json
+bash update-all.sh
+
+# Or manually
+npm install -g ruflo@3.5.58
+```
+
 #### Marketplace plugins
 ```bash
 /plugin marketplace update    # inside Claude Code
@@ -430,22 +595,30 @@ cargo install --git https://github.com/rtk-ai/rtk --tag v0.34.3 --force
 
 ## Adding a new custom skill
 
+**Fastest way:**
+```bash
+make new-skill name=myskill
+# Creates agents/myskill.md + skills/myskill/SKILL.md with templates filled
+# Edit both files, then: bash link.sh
+```
+
+**Manually:**
 1. Create `agents/myagent.md` — role, tasks, rules, output format
 2. Create `skills/myskill/SKILL.md`:
 
 ```markdown
 ---
 name: myskill
-description: What this skill does — front-load the key use case (max 250 chars)
+description: What this skill does — front-load key use case (max 250 chars)
 argument-hint: <what to pass>
 disable-model-invocation: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob
 ---
 
 Load and follow strictly:
-- .claude/agents/myagent.md
+- $HOME/.claude/agents/myagent.md
 
-Execute MYAGENT on:
+Execute on:
 
 $ARGUMENTS
 ```
@@ -475,20 +648,24 @@ cp "$CONF/agents/refactorer.md" .claude/agents/refactorer.md
 bash doctor.sh
 
 # Or from within Claude Code
-/health
+/health       # full diagnostic (symlinks, plugins, permissions, token budget)
+/status       # project snapshot at session start (plugins, git, GSD milestone)
 
 # Unified commands via Makefile (from the repo directory)
 make doctor     # diagnostic
 make update     # pull + submodules + symlinks + doctor
 make install    # link.sh + install-plugins.sh
+make onboard    # reminder to run /onboard in Claude Code
+make new-skill name=myskill  # scaffold agent + skill files
 ```
 
-`doctor.sh` checks 7 axes: symlinks, GStack submodule, prerequisites (git, Node, Cargo, Python, Claude Code),
-plugins (RTK, Superpowers, Context7), permissions, token budget estimate, and config consistency
-(frontmatter coherence, CRLF detection).
+`doctor.sh` checks 7 axes: symlinks, GStack submodule (with pinning warning), prerequisites
+(git, Node, Cargo, Python, Claude Code), plugins (RTK, Superpowers, Context7, GSD v2, ruflo),
+permissions (deny count, bypass mode), token budget (breakdown vs Pro session budget), and
+config consistency (frontmatter, CRLF detection).
 
 `session-start.sh` runs a quick health check at every session start (filesystem only, no subprocesses)
-and displays toggle plugin status with `/plugin-check` and `/health` hints.
+and displays toggle plugin status, GSD v2 CLI status, with `/plugin-check` and `/health` hints.
 
 Both scripts source `lib/detect-plugins.sh` for consistent plugin detection logic.
 
@@ -500,7 +677,8 @@ bash update-all.sh
 
 # Or step by step
 git pull                                                # this repo
-git submodule update --remote skills-external/gstack    # GStack
+# GStack: prompts for confirmation (tracks main branch)
+git submodule update --remote skills-external/gstack
 bash link.sh                                            # refresh symlinks
 bash doctor.sh                                          # verify
 ```
@@ -513,7 +691,6 @@ bash doctor.sh                                          # verify
 Restart your shell or run `source ~/.bashrc` / `source ~/.zshrc`.
 
 ### Orchestrator blocks at STEP 0 — Superpowers missing
-The plugin-advisor blocks `/init-project` and `/ship-feature` if Superpowers is not active.
 Install: `claude plugin marketplace add obra/superpowers-marketplace && claude plugin install --scope user superpowers@superpowers-marketplace`
 Then re-run the orchestrator.
 
@@ -525,32 +702,56 @@ Run `bash link.sh` and verify: `ls -la ~/.claude/skills/gstack`.
 If missing: `cd` into your config repo and run `git submodule update --init`.
 
 ### link.sh warns "is a real directory"
-If `~/.claude/agents/`, `~/.claude/skills/`, or `~/.claude/lib/` exist as real directories (not symlinks
-from a previous `link.sh` run), the script skips them to avoid data loss. Rename or remove the directory, then re-run `link.sh`.
+If `~/.claude/agents/`, `~/.claude/skills/`, `~/.claude/lib/`, or `~/.claude/templates/` exist as real
+directories, the script skips them to avoid data loss. Rename or remove the directory, then re-run `link.sh`.
 
-### Token budget exceeded / skills truncated at session start
+### GSD v2 — "command not found: gsd"
+npm's global bin directory is not in `$PATH`. Run `npm prefix -g` to find it, then add `$(npm prefix -g)/bin`
+to your PATH. See the [GSD troubleshooting guide](https://github.com/gsd-build/gsd-2/blob/main/docs/troubleshooting.md).
+
+### GSD v2 — migrating from v1 projects
+If you have old projects with `.planning` directories from GSD v1, migrate them:
+```bash
+cd your-project
+gsd          # start a session
+/gsd migrate # migrate .planning → .gsd format
+```
+
+### Ruflo MCP not detected by doctor.sh
+Ruflo must be registered as an MCP server. Run:
+```bash
+claude mcp add --scope user ruflo -- npx ruflo mcp start
+claude mcp list | grep ruflo
+```
+
+### Token budget exceeded — skills truncated at session start
 Too many plugins active. Run `/plugin-check` to optimize.
-Run `bash doctor.sh` for a token budget estimate.
+Run `bash doctor.sh` for a token budget breakdown (vs Pro ~11k session budget).
 
 ### settings.json not applying
 Check precedence: deny always wins over allow at any level. `.claudeignore` overrides all permission rules.
 Verify deny count: `cat ~/.claude/settings.json | python3 -c "import json,sys; print(len(json.load(sys.stdin)['permissions']['deny']))"`
-Expected: 77 deny rules.
+Expected: 100 deny rules.
 
 ### Claude reads .env despite deny rules
 The `Read(**/.env)` deny rule blocks the Read tool. `Bash(cat .env)` and similar commands have separate
-deny rules (included in this config). For hard exclusion regardless of tool, use `.claudeignore` in the project root.
+deny rules (included in this config). For hard exclusion regardless of tool, use `.claudeignore`.
 
 ### install-plugins.sh failed — where are the logs?
-Check `install-YYYYMMDD-HHMMSS.log` in your config repo directory — the script logs all output to a timestamped file.
+Check `install-YYYYMMDD-HHMMSS.log` in your config repo directory.
 
 ---
 
 ## Known limitations
 
-- **Deny rules are pattern-based, not sandboxed.** Common bypass vectors (`bash -c`, `eval`, `xargs`, `cat .env`) are blocked, but novel indirect patterns are still possible. `.claudeignore` is the only hard file exclusion mechanism.
-- **Superpowers is a hard dependency** for `/init-project` and `/ship-feature`. The plugin-advisor (STEP 0) auto-detects and blocks if Superpowers is missing, with install instructions. There is no manual fallback mode.
-- **Marketplace plugin versions are not pinned.** They install latest. Non-marketplace tools (RTK, GSD) are pinned in `plugins.lock.json` and read by `install-plugins.sh`.
-- **Token budget is finite and not directly observable.** With all toggle plugins active, the description budget can exceed 60%. Run `/health` or `bash doctor.sh` for an estimate.
-- **Agent frontmatter fields** like `model` and `memory` are declared but their enforcement by Claude Code is not guaranteed. They serve as documentation more than strict runtime controls.
-- **`Bash(cat *)` in allow vs `Bash(cat .env)` in deny** depends on Claude Code resolving deny-wins. This is the expected behavior but cannot be tested outside the runtime.
+- **Deny rules are pattern-based, not sandboxed.** Core bypass vectors (`bash -c`, `eval`, `python3 -c *`, `node -e *`, `source /dev/stdin`, `mkfifo *`, `xargs * .env*`, `base64 .env*`) are blocked. Process substitution (`<(cmd)`, `>(cmd)`), here strings (`<<<`), and `/dev/fd/*` access remain possible without explicit patterns — `.claudeignore` is the only hard file exclusion mechanism.
+- **`disableAutoMode` syntax not verified** against CC v2.1.89 — added as `"disableAutoMode": "disable"` by analogy with `disableBypassPermissionsMode`. # TODO: VERIFY
+- **Superpowers is a hard dependency** for `/init-project` and `/ship-feature`. The plugin-advisor (STEP 0) auto-detects and blocks if missing, with install instructions. No manual fallback mode.
+- **Marketplace plugin versions are not pinned.** They install latest. Non-marketplace tools (RTK, GSD v2, ruflo) are pinned in `plugins.lock.json`.
+- **Token budget:** `CLAUDE.md` loads in full every session (~420t). Skill bodies load on-demand. Plugin descriptions load passively. With all toggles active, passive plugin cost can reach ~50% of the Pro session budget (~11k tokens/5h). Run `/health` or `bash doctor.sh` for a breakdown.
+- **GSD v2 is a standalone CLI**, not a Claude Code plugin. `/gsd ...` commands are GSD-internal and do not work in the Claude Code slash command bar.
+- **Ruflo is heavy** (~340MB default, ~500-1500t passive tokens). Only enable for genuine enterprise multi-agent needs. For multi-session work, GSD v2 is lighter and sufficient.
+- **Agent frontmatter fields** `model`, `memory`, `effort` are enforced by Claude Code v2.1.x.
+- **`bypassPermissions` mode is disabled** via `disableBypassPermissionsMode`.
+- **GStack submodule is pinned to `branch = main`**, not a commit hash. `update-all.sh` now prompts for confirmation before updating. Review upstream commits before accepting.
+- **`disable-model-invocation: true` on orchestrator skills** (`/init-project`, `/ship-feature`): behavior when a skill with this flag invokes sub-agents via loaded agent files has not been fully verified in CC v2.1.89. # TODO: VERIFY
diff --git a/USAGE.md b/USAGE.md
new file mode 100644
index 0000000..f8f4232
--- /dev/null
+++ b/USAGE.md
@@ -0,0 +1,2021 @@
+# claude-config — Guide d'utilisation et cas d'usage
+
+Ce fichier complète le README. Il documente les bonnes pratiques, les workflows typiques, et des exemples concrets pour plusieurs types de projets.
+
+---
+
+## Principes fondamentaux
+
+**Tu décris, le pipeline exécute.** Le système prend en charge : l'architecture, le scaffolding, la décomposition en tâches, l'implémentation TDD, le code review, et la synchronisation du README. Tu n'interviens qu'aux deux gates de validation.
+
+**Prompt détaillé = moins de friction.** L'interviewer (STEP 1) skip les questions si ton prompt contient déjà : nom, purpose, stack, features v1, conventions. Un prompt de 10 lignes structuré évite toute interruption.
+
+**Plugin-check avant tout.** Soit via `/plugin-check "description"` (explicite), soit via STEP 0 de `/init-project` ou `/ship-feature` (automatique). Les plugins mal configurés dégradent silencieusement la qualité du résultat.
+
+---
+
+## Quel skill utiliser ?
+
+Arbre de décision rapide face à une situation donnée :
+
+```
+Tu veux...
+│
+├─ Créer un nouveau projet from scratch ?
+│    → /init-project "description"
+│
+├─ Intégrer un projet existant dans claude-config ?
+│    → /onboard
+│
+├─ Ajouter une feature à un projet existant ?
+│    → /ship-feature "description"
+│
+├─ Reprendre après une pause / orienter la session ?
+│    → /status
+│
+├─ Comprendre du code avant de le modifier ?
+│    → /analyze src/fichier.py
+│    → (mode DEBUG si tu passes une erreur/stack trace)
+│
+├─ Améliorer la qualité sans changer le comportement ?
+│    → /refactor src/module.py
+│    ⚠️  Pour un refactoring profond (module entier) :
+│       /analyze src/module/   ← rapport de violations d'abord
+│       /refactor src/module/  ← corrections sur rapport
+│       /analyze src/module/   ← vérification après (cycle complet)
+│
+├─ Vérifier/mettre à jour le README ?
+│    → /readme
+│
+├─ Vérifier si les plugins sont bien configurés ?
+│    → /plugin-check "description du projet"
+│    → (aussi fait automatiquement en STEP 0 de /init-project et /ship-feature)
+│
+├─ Session GSD v2 active/interrompue ?
+│    → dans le terminal: gsd → /gsd auto  (reprend depuis .gsd/)
+│    → modifier le plan en cours: /gsd steer ou /gsd discuss
+│    → voir la progression: /gsd status
+│    → un step a échoué: /gsd forensics  (debug autonome)
+│
+└─ Quelque chose ne marche pas ?
+     → /health    ← diagnostic complet (symlinks, plugins, permissions, token budget)
+```
+
+### Règle de décision simplifiée
+
+| Situation | Skill recommandé |
+|---|---|
+| Tout nouveau | `/init-project` |
+| Code existant sans config | `/onboard` |
+| Feature à ajouter | `/ship-feature` |
+| Reprise de session | `/status` |
+| Debug / comprendre | `/analyze` |
+| Nettoyage code | `/refactor` |
+| Doc périmée | `/readme` |
+| Plugins OK ? | `/plugin-check` |
+| Rien ne marche | `/health` |
+
+---
+
+## Les commandes et quand les utiliser
+
+| Commande | Quand | Notes |
+|---|---|---|
+| `/init-project` | Nouveau projet from scratch | 12-13 steps, deux gates obligatoires |
+| `/ship-feature` | Feature sur projet existant | 8 steps, une gate |
+| `/onboard` | Projet existant non géré par ce config | Génère CLAUDE.md + settings |
+| `/plugin-check` | Avant de démarrer tout travail | Aussi embarqué en STEP 0 des orchestrateurs |
+| `/analyze` | Comprendre du code avant de le modifier | Read-only, aucune solution proposée |
+| `/analyze` + erreur | Diagnostiquer un test/build qui échoue | Mode DEBUG : hypothèses ordonnées |
+| `/refactor` | Améliorer un fichier sans changer le comportement | Rapport de violations d'abord, modif ensuite |
+| `/readme` | Après une série de features | AUDIT : compare README vs code réel |
+| `/health` | Quand quelque chose ne fonctionne pas | Lance doctor.sh |
+
+---
+
+## Les plugins — décision rapide
+
+```
+Toujours actifs (0 token) : security-guidance, rtk
+
+Projet avec interface     → frontend-design ON
+Design élaboré/system     → ui-ux-pro-max ON
+Deploy + QA browser       → gstack ON
+Next.js/React/Prisma      → context7 ON (WARN si absent, pas BLOCK)
+Multi-session (>1 jour)   → gsd v2 CLI (gsd dans terminal)
+Swarm 5+ agents parallèles → ruflo ON
+
+Backend/CLI seulement     → tout OFF sauf superpowers
+Hotfix/quick fix          → tout OFF sauf superpowers
+```
+
+**GSD v2** n'est pas un plugin Claude Code — c'est un CLI externe. Il ne consomme pas de tokens passifs. Tu le lances dans un terminal séparé avec `gsd`, puis `/gsd auto` pour le mode autonome.
+
+---
+
+## Patterns de workflow
+
+> **Budget Pro (~11k tokens/5h) :** un `/init-project` complet consomme 3000-5000t — laissant 6000-8000t pour les steps suivants. Adapter le choix de plugins actifs en conséquence. Les tokens sont indiqués à titre indicatif — varient selon la taille du projet et les plugins actifs.
+
+### Pattern A — Nouveau projet court (≤1 session) · ~3000-5000t
+
+```
+# 1. Configurer les plugins
+/plugin-check "description de ton projet"
+# → Activer les plugins recommandés, puis :
+
+# 2. Créer le projet
+/init-project "description complète"
+# → STEP 0  : vérifie les plugins automatiquement
+# → STEP 1  : interview (skip si prompt complet)
+# → STEP 4  : ★ GATE — valider l'architecture
+# → STEP 7  : ★ GATE — valider le plan d'implémentation
+# → STEP 8-11: implémentation TDD + review + finish
+# → STEP 12 : sync README
+# → STEP 13 : propose GSD v2 si multi-session détecté
+
+# 3. Features suivantes
+/ship-feature "description de la feature"
+```
+
+### Pattern B — Projet long (multi-session, plusieurs jours) · ~1500-2500t/session CC
+
+```
+# Même départ que Pattern A, mais au STEP 13 :
+# → Répondre "yes" à "Initialize GSD v2?"
+# → ROADMAP.md est créé avec les milestones
+
+# À chaque reprise de session (dans Claude Code) :
+/status              # snapshot : plugins + git + milestone GSD en cours
+
+# Ensuite dans un terminal (depuis le dossier projet) :
+gsd                  # démarrer une session
+/gsd init            # si pas encore fait
+/gsd auto            # mode autonome, walk away
+
+# Pour suivre :
+/gsd status          # dashboard progression + coût
+
+# Pour orienter en cours de route :
+/gsd discuss         # décisions d'architecture
+/gsd steer           # modifier le plan en cours d'exécution
+
+# Crash/interruption → reprendre :
+gsd                  # relancer
+/gsd auto            # reprend depuis l'état sauvegardé dans .gsd/
+```
+
+### Pattern C — Projet existant (onboarding) · ~500-1000t (onboard) + normal ensuite
+
+```
+cd mon-projet-existant/
+
+# Dans Claude Code :
+/onboard
+# → Scanne le projet (stack, structure, commandes, deps)
+# → Pose seulement les questions manquantes
+# → Génère CLAUDE.md, .claude/settings.json, .claudeignore
+# → Option : ROADMAP.md pour GSD v2
+
+/status              # confirmer que l'onboarding est complet + vue d'ensemble
+
+# Configurer les plugins pour ce projet
+/plugin-check "type du projet"
+
+# Reprendre le développement normalement
+/ship-feature "prochaine feature"
+```
+
+### Pattern D — Hotfix / modification chirurgicale · ~500-800t
+
+```
+# Pas de /init-project, pas de GSD, pas de plugin lourd
+/analyze src/module-bugue.py   # comprendre sans modifier
+/ship-feature "corriger X"     # pipeline complet mais ciblé
+```
+
+### Pattern E — Debug d'erreur de build/test · ~600-900t
+
+```
+# Copier le message d'erreur complet, puis :
+/analyze "FAILED tests/test_api.py::test_create — AssertionError: 422 != 201"
+# → Mode DEBUG automatique
+# → Hypothèses ordonnées par probabilité
+# → Fichiers à vérifier
+# → Ce qu'il ne faut pas toucher
+
+# Puis si fix nécessaire :
+/ship-feature "corriger le test_create_order — cause: champ quantity manquant"
+```
+
+---
+
+## Exemples complets
+
+---
+
+### Exemple 1 — Application mobile liste de courses (Expo/React Native)
+
+**Contexte :** app mobile, offline-first, SQLite local, notifications push, iOS + Android.
+
+**Setup plugins :**
+```
+/plugin-check "App mobile React Native Expo liste de courses, offline-first, SQLite, notifications push"
+
+→ SIGNALS: frontend (mobile), fast-libs (Expo SDK)
+→ ENABLE: frontend-design (composants RN)
+→ WARN: context7 si Expo SDK 51+ utilisé (fast-libs)
+→ OFF: gstack (mobile, pas de browser QA), ui-ux-pro-max (optionnel)
+→ BLOCKING: none
+```
+
+**Prompt init (prompt complet → pas de questions) :**
+```
+/init-project "Application mobile 'KartApp' — liste de courses offline-first.
+
+Stack: React Native 0.74 + Expo SDK 51 + TypeScript. SQLite via expo-sqlite. Notifications push via expo-notifications. Expo Router pour la navigation. Zustand pour le state. iOS + Android.
+
+Features v1:
+1. Création/édition/suppression de listes
+2. Ajout d'articles (nom, quantité, unité, catégorie)
+3. Cocher/décocher des articles
+4. Partage de liste par lien (Expo Sharing)
+5. Historique des 10 dernières courses
+
+Out of scope: sync backend, collaboration, paiement.
+
+Tests: Jest + @testing-library/react-native. Coverage >70%.
+Convention: composants PascalCase, hooks use*, stores en Zustand slices."
+```
+
+**Ce que le scaffolder génère (STEP 5) :**
+```
+app/
+  (tabs)/
+    index.tsx          — liste des listes (vide)
+    history.tsx        — historique (vide)
+  list/[id].tsx        — détail liste (vide)
+  _layout.tsx          — root layout Expo Router
+components/
+  ListCard.tsx         — vide
+  ItemRow.tsx          — vide
+  CategoryBadge.tsx    — vide
+stores/
+  listsStore.ts        — Zustand slice (vide)
+  itemsStore.ts        — Zustand slice (vide)
+db/
+  schema.ts            — types SQLite (vide)
+  migrations/
+    001_initial.ts     — vide
+hooks/
+  useLists.ts          — vide
+  useItems.ts          — vide
+constants/
+  Colors.ts            — tokens couleurs
+app.json               — Expo config
+package.json           — scripts: start/android/ios/test/lint
+tsconfig.json
+.env.example
+
+Install : npx expo install ✅
+Verify  : npx expo export --platform web --output-dir /tmp/expo-check --clear ✅
+```
+
+**Si le projet devient long (plusieurs features sur semaines) :**
+```
+# STEP 13 propose GSD v2 : répondre "yes"
+# Puis dans terminal :
+gsd
+/gsd auto
+# → GSD gère deck-building, sharing backend, etc. milestone par milestone
+```
+
+---
+
+### Exemple 2 — Site vitrine graphisme élégant (Next.js)
+
+**Contexte :** studio photographique, design premium, galerie masonry, dark mode, SEO, Vercel.
+
+**Setup plugins :**
+```
+/plugin-check "Site vitrine Next.js 14 studio photo, design élaboré, animations Framer Motion, galerie, dark mode, SEO"
+
+→ SIGNALS: frontend, design-system, fast-libs(Next.js)
+→ ENABLE: frontend-design (~200t)
+→ ENABLE: ui-ux-pro-max (~400t) — "design élaboré" signal fort
+→ WARN: context7 non configuré → taper "force" pour continuer (ou configurer avant)
+→ OFF: gstack (vitrine statique, pas de deploy complexe)
+→ COST: ~1600t passif (comfortable)
+```
+
+**Prompt init :**
+```
+/init-project "Site vitrine 'Lumière Studio' pour photographe professionnel.
+
+Stack: Next.js 14 App Router + TypeScript + Tailwind CSS + Framer Motion. Hébergement: Vercel. Pas de base de données.
+
+Features v1:
+1. Page d'accueil — hero animé, teaser galerie
+2. Galerie masonry (>50 photos, lightbox, lazy loading)
+3. Page À propos (biographie, parcours)
+4. Page Contact (formulaire → Resend pour email)
+5. Dark mode (system preference + toggle)
+6. SEO (OpenGraph, sitemap, metadata par page)
+
+Out of scope: blog, e-commerce, espace client, CMS.
+
+Tests: Playwright (home, contact form, dark mode toggle). Jest/RTL pour composants.
+Convention: composants dans components/, pages dans app/, assets dans public/images/."
+```
+
+**Ce que ui-ux-pro-max apporte en STEP 3 (brainstorm) :**
+Avec ui-ux-pro-max actif, le brainstorming propose un système de design complet :
+```
+Palette    : zinc-950 (fond dark) / zinc-50 (texte) / amber-400 (accent)
+Typo       : Cormorant Garant (titres serif) + Inter (corps)
+Espacement : multiples de 8px, max-width 1440px
+Animations : entrées scroll (Framer Motion viewport), 200ms ease-out
+Masonry    : CSS columns responsive (1→2→3 colonnes), gap 16px
+```
+Sans ui-ux-pro-max : "Tailwind avec palette neutre, Inter". La différence est visible pour un projet où le design est le produit.
+
+**Ajouter une feature après init :**
+```
+/ship-feature "Page Tarifs — 3 formules (Reportage, Portrait, Mariage) avec comparateur visuel et CTA de contact par formule"
+```
+
+---
+
+### Exemple 3 — Jeu de puzzle avec API, auth et cartes collectibles
+
+**Contexte :** le projet le plus complexe — React + FastAPI + PostgreSQL + Docker, auth JWT, gameplay, collection.
+
+**Setup plugins :**
+```
+/plugin-check "Jeu de puzzle web React + FastAPI + PostgreSQL. Auth JWT, collection de cartes, boutique in-app, leaderboard. Multi-session, dev sur plusieurs semaines."
+
+→ SIGNALS: frontend, fast-libs(React), deploy, multi-session
+→ ENABLE: frontend-design, context7
+→ ENABLE: ui-ux-pro-max (cartes visuelles, cohérence design)
+→ CLI: gsd v2 RECOMMANDÉ (multi-session détecté)
+→ OPTIONAL: gstack si deploy CI + browser QA prévus
+→ COST: ~1800t passif (avec context7)
+```
+
+**Prompt init :**
+```
+/init-project "Jeu de puzzle web 'CardForge'.
+
+Stack: React 18 + TypeScript + Vite (frontend), FastAPI + Python 3.12 (backend), PostgreSQL 16, Redis 7, Docker Compose.
+
+Features v1:
+1. Inscription/connexion (JWT + refresh tokens)
+2. Gameplay puzzle grille 4x4 (pièces = cartes)
+3. Collection personnelle (50 cartes de base)
+4. 3 niveaux de difficulté
+5. Sauvegarde de partie en cours
+6. Profil + statistiques (parties, win rate)
+
+Out of scope: boutique, PvP, cartes premium, leaderboard.
+
+Tests: pytest backend (>80% coverage), Vitest + Testing Library frontend.
+Docker: dev + prod (nginx pour frontend, uvicorn pour backend).
+Convention: snake_case Python, camelCase TypeScript."
+```
+
+**Workflow long avec GSD v2 :**
+```
+# Après /init-project (STEP 13 → "yes")
+# Le ROADMAP.md généré contient :
+#   Milestone 1: Boutique in-app + Stripe
+#   Milestone 2: PvP + matchmaking
+#   Milestone 3: Leaderboard + saisons
+
+# Dans un terminal :
+cd cardforge/
+gsd                  # démarre session GSD
+/gsd auto            # GSD travaille sur Milestone 1 de façon autonome
+# → research Stripe API + docs
+# → plan décomposé en tâches
+# → exécute chaque tâche dans fresh context window
+# → commits propres avec messages clairs
+# → revient quand Milestone 1 est complet ou si décision requise
+```
+
+**Quand le projet est lancé, ajouter des features ponctuelles :**
+```
+# Petite feature rapide (1h) → rester dans CC
+/ship-feature "Ajouter un compteur de combo sur la grille de jeu"
+
+# Feature longue (2 jours) → GSD v2
+gsd
+/gsd quick "Implémenter la boutique in-app avec Stripe"
+# ou
+/gsd auto  # si ROADMAP.md est déjà à jour
+```
+
+---
+
+### Exemple 4 — Onboarding d'un projet existant (CLI Rust)
+
+**Contexte :** outil CLI Rust existant sur GitHub, sans CLAUDE.md ni settings.
+
+**Workflow :**
+```bash
+git clone git@github.com:user/my-rust-cli.git
+cd my-rust-cli/
+```
+
+Dans Claude Code :
+```
+/onboard "Rust CLI"
+
+→ PHASE 1 — Discovery:
+   Cargo.toml trouvé : name="mycli", edition=2021, version=0.3.1
+   Structure: src/main.rs, src/commands/, src/utils/, tests/
+   Makefile: targets build, test, release, lint (clippy)
+   Pas de Dockerfile (CLI pur)
+
+→ PHASE 2 — Interview (manquant):
+   Purpose ? → répondre: "CLI de gestion de projets locaux"
+
+→ PHASE 3-5 — Génère:
+   CLAUDE.md avec stack Rust 1.77, commandes exactes du Makefile
+   .claude/settings.json — blocs cargo uniquement
+   .claudeignore — target/, *.rlib
+
+→ PHASE 6 — GSD v2 ? → skip (projet stable, pas de multi-session)
+
+ONBOARD COMPLETE: mycli
+→ Prêt pour /ship-feature
+```
+
+```
+/plugin-check "Rust CLI, pas de frontend, pas de deploy"
+
+→ SIGNALS: none (CLI pur)
+→ DISABLE: frontend-design, ui-ux-pro-max, gstack, context7
+→ KEEP: superpowers
+→ COST: ~800t (minimal)
+→ ACTION REQUIRED? NO
+```
+
+```
+/ship-feature "Ajouter une commande 'mycli export --format json/csv' pour exporter les projets"
+```
+
+---
+
+### Exemple 5 — Debug d'une régression (mode /analyze DEBUG)
+
+**Contexte :** CI qui échoue après un merge, erreur de type TypeScript.
+
+**Workflow :**
+```
+/analyze "src/store/cartStore.ts:47:5 - error TS2345: Argument of type 'string | undefined' is not assignable to parameter of type 'string'.
+
+  const product = products.find(p => p.id === productId)
+  addToCart(product.id)  // <-- erreur ligne 47"
+```
+
+**Output attendu (DEBUG MODE) :**
+```
+DEBUG ANALYSIS: TS2345 — 'string | undefined' non assignable à 'string' en ligne 47
+
+ERROR:
+  src/store/cartStore.ts:47 — product.id passé à addToCart(id: string)
+  product peut être undefined car Array.find() retourne T | undefined
+
+TRACE:
+  addToCart(productId) → products.find(p => p.id === productId) → product.id → TS2345
+
+ROOT CAUSE HYPOTHESES:
+  1. [HIGH] Guard manquant après find() — product non vérifié avant utilisation
+             evidence: find() retourne toujours T | undefined, jamais T seul
+  2. [MED]  Type de addToCart() trop strict (devrait accepter string | undefined)
+             evidence: si product peut légitimement être absent, le type est correct
+  3. [LOW]  Changement récent dans le type Product (id devenu optional)
+             evidence: vérifier git log sur Product type
+
+WHAT TO VERIFY NEXT:
+  - Ajouter guard: if (!product) return; avant ligne 47
+  - Ou utiliser optional chaining: addToCart(product?.id ?? '')
+  - Vérifier si product absent est un cas métier valide ou une erreur
+
+DO NOT TOUCH:
+  src/store/cartStore.ts dans son ensemble — corriger seulement la ligne 47
+```
+
+
+---
+
+### Exemple 6 — CLI Rust from scratch (workflow minimaliste)
+
+**Contexte :** outil en ligne de commande, pas de frontend, pas de serveur, pas de Docker. Le cas le plus simple — illustre que le système fonctionne aussi bien sur les projets petits que complexes.
+
+**Setup plugins — zéro token inutile :**
+```
+/plugin-check "CLI Rust, convertisseur de fichiers JSON/CSV/TOML, pas de réseau, pas de frontend"
+
+→ SIGNALS: none (CLI pur, pas de deploy, pas de frontend)
+→ KEEP: superpowers
+→ DISABLE: frontend-design, ui-ux-pro-max, gstack, context7, ruflo
+→ COST: ~800t (base seulement)
+→ ACTION REQUIRED? NO
+```
+
+L'intérêt ici est de voir que `/plugin-check` est aussi utile pour confirmer qu'on n'a **rien** à activer, évitant de polluer le contexte avec 3000t de plugins inutiles.
+
+**Prompt init (complet, pas de questions) :**
+```
+/init-project "CLI Rust 'jsonconv' — convertisseur de formats de données.
+
+Stack: Rust 1.77 + Cargo. Libs: serde + serde_json + csv + toml + clap (CLI args).
+
+Features v1:
+1. Conversion JSON → CSV
+2. Conversion CSV → JSON
+3. Conversion JSON → TOML
+4. Conversion TOML → JSON
+5. Lecture stdin ou fichier, écriture stdout ou fichier
+
+Usage: jsonconv --from json --to csv input.json -o output.csv
+
+Out of scope: XML, YAML, validation de schéma, streaming.
+
+Tests: cargo test, unitaires par format, doctests pour les fonctions publiques.
+Convention: snake_case partout, erreurs via thiserror, pas de unwrap() en dehors des tests."
+```
+
+**Ce que le scaffolder génère (STEP 5) :**
+```
+Cargo.toml          (serde, serde_json, csv, toml, clap pinned)
+src/
+  main.rs           (empty — clap parse + dispatch)
+  lib.rs            (empty — re-exports)
+  converter/
+    mod.rs          (empty)
+    json_csv.rs     (empty)
+    csv_json.rs     (empty)
+    json_toml.rs    (empty)
+    toml_json.rs    (empty)
+  error.rs          (empty — thiserror types)
+tests/
+  integration_test.rs (empty)
+.gitignore          (target/, *.log)
+.claudeignore       (target/)
+
+Install : cargo fetch ✅
+Verify  : cargo check ✅ (validates Cargo.toml + Rust syntax sans compiler)
+Docker  : N/A (CLI pur)
+```
+
+**Gate #1 — architecture :**
+Simple à valider. L'architecture proposée est plate, pas de surprise.
+
+**Gate #2 — plan d'implémentation (20-25 tâches) :**
+```
+  1. [error.rs] Définir ConversionError avec thiserror
+  2. [converter/json_csv.rs] fn json_to_csv() — tests first
+  3. [converter/json_csv.rs] fn csv_to_json() — tests first
+  ...
+  20. [main.rs] Intégrer clap, dispatcher vers les converters
+  21. [tests/integration_test.rs] Tests end-to-end avec fichiers fixtures
+```
+
+**Après init — features complémentaires :**
+```
+/ship-feature "Ajouter conversion YAML ↔ JSON via serde_yaml"
+/ship-feature "Ajouter flag --pretty pour indentation JSON output"
+/refactor src/converter/   # après plusieurs features, si violations de normes
+/analyze src/converter/json_csv.rs  # avant une grosse modification
+```
+
+**Points clés de cet exemple :**
+- `/plugin-check` confirme "rien à activer" — actif et utile même pour dire non
+- Scaffolder génère un Cargo.toml avec deps pinned — pas de `cargo add` manuel
+- `cargo check` comme verify évite un full compile sur un skeleton vide
+- Pas de GSD v2 : CLI simple, toutes les features tiennent en 1-2 sessions CC
+
+---
+
+## Bonnes pratiques — résumé
+
+**Plugins :** toujours vérifier avant de commencer. Les gates de validation de `/init-project` et `/ship-feature` sont des points de contrôle — ne jamais "force" une gate d'architecture sans l'avoir lue.
+
+**Prompts :** plus le prompt initial est précis (stack, features, conventions), moins il y a de questions. Un prompt de 15 lignes structuré élimine l'interview entière.
+
+**GSD v2 :** dès qu'une feature ou un projet dépasse une journée de développement. Le signal est : "je vais devoir ouvrir plusieurs sessions pour finir ça". GSD v2 résout la perte de contexte entre sessions.
+
+**`/onboard` :** pour tout projet existant. Même si le projet est fonctionnel, CLAUDE.md et `.claude/settings.json` améliorent significativement la qualité des interactions suivantes.
+
+**`/analyze` avant `/refactor` :** toujours. Le refactorer attend le rapport d'analyse avant de toucher au code. Le passer en bypass donne de moins bons résultats.
+
+**`/readme` régulièrement :** après chaque milestone. Le mode AUDIT compare le README à l'état réel du code et liste les divergences — évite la documentation périmée.
+
+---
+
+---
+
+---
+
+### Exemple 7 — Refactoring d'un module Python legacy
+
+**Contexte :** module `services/payment_service.py` dans un projet FastAPI existant. Écrit il y a 2 ans, jamais refactorisé. Violations connues : fonctions de 80 lignes, global state, pas de tests unitaires, logique métier mélangée avec appels HTTP.
+
+**Setup :** projet déjà onboardé (CLAUDE.md présent), superpowers actif, plugins inutiles désactivés.
+
+#### Étape 1 — Analyse avant toute modification
+
+```
+/analyze src/services/payment_service.py
+```
+
+**Ce que l'analyzer produit :**
+```
+ANALYSIS: src/services/payment_service.py
+
+CONTEXT:
+- Module de 340 lignes gérant les paiements Stripe
+- Pas de tests, 3 variables globales, 2 fonctions > 80 lignes
+
+KEY COMPONENTS:
+- process_payment(): 95 lignes — logique métier + appel Stripe + logging entremêlés
+- _build_stripe_payload(): 72 lignes — construction du payload + validation + mapping
+- STRIPE_CLIENT: variable globale initialisée au module load (non mockable)
+- retry_payment(): appelle process_payment() directement (couplage fort)
+
+CONSTRAINTS:
+- Aucun test existant — refactoring sans filet
+- retry_payment() appelé par 3 endpoints différents — interface publique à préserver
+
+RISKS:
+- Modification de process_payment() peut casser les 3 appelants — probability: high
+- STRIPE_CLIENT global rend les tests unitaires impossibles sans monkeypatch — probability: high
+- _build_stripe_payload() mélange validation et mapping — extraction risquée — probability: medium
+
+OPEN QUESTIONS:
+- process_payment() retourne-t-il toujours un dict ou parfois None ?
+- Les appelants de retry_payment() vérifient-ils le code de retour ?
+```
+
+#### Étape 2 — Refactoring guidé
+
+```
+/refactor src/services/payment_service.py
+```
+
+**Ce que le refactorer produit d'abord (rapport avant modification) :**
+```
+VIOLATIONS DETECTED: src/services/payment_service.py
+
+- [NORM] process_payment(): 95 lignes → split plan: _validate_payment(), _call_stripe(), _handle_response()
+- [NORM] _build_stripe_payload(): 72 lignes → split plan: _validate_payload(), _map_to_stripe()
+- [NORM] STRIPE_CLIENT: global state → inject via paramètre ou dependency injection
+- [QUALITY] logique métier dans process_payment() mélangée avec appel HTTP Stripe
+- [QUALITY] retry_payment() appelle process_payment() directement (tight coupling)
+
+PLAN:
+1. Extraire _validate_payment() depuis process_payment() (lignes 12-28)
+2. Extraire _call_stripe() depuis process_payment() (lignes 45-67)
+3. Extraire _handle_response() depuis process_payment() (lignes 68-95)
+4. Réécrire process_payment() comme coordinateur des 3 sous-fonctions
+5. Extraire _validate_payload() et _map_to_stripe() depuis _build_stripe_payload()
+6. Injecter stripe_client via paramètre (défaut = STRIPE_CLIENT global pour rétro-compat)
+
+TESTS PRESENT: non
+→ ⚠️ Aucun test existant. Le refactoring est risqué sans filet.
+   Recommandation: créer des tests d'intégration minaux AVANT de toucher au code.
+   Procéder malgré tout ? (yes / create tests first)
+```
+
+**User répond : "create tests first"**
+
+Le refactorer génère d'abord `tests/test_payment_service.py` avec des tests d'intégration basiques qui capturent le comportement actuel (avant refactoring). Puis procède au refactoring fonction par fonction.
+
+#### Étape 3 — Vérification finale
+
+```
+/analyze src/services/payment_service.py
+```
+
+Post-refactoring, l'analyzer confirme :
+```
+VIOLATIONS FIXED:
+- process_payment(): 95 lignes → 18 lignes (coordinateur) ✅
+- STRIPE_CLIENT: injectable, toujours rétro-compatible ✅
+- Interface publique de retry_payment() inchangée ✅
+
+REMAINING:
+- _build_stripe_payload() : 48 lignes (sous le seuil de 25 mais proche)
+  → justified: validation + mapping ne peuvent pas être séparés sans risque
+
+TESTS: ✅ 8 tests passent (créés avant refactoring)
+```
+
+#### Points clés de cet exemple
+
+- **`/analyze` d'abord, toujours.** L'analyzer identifie les risques (3 appelants, pas de tests) AVANT que le refactorer ne touche au code. Sans ça, le refactorer aurait pu casser l'interface publique.
+- **Le refactorer s'arrête si pas de tests.** Ce comportement est intentionnel — refactorer sans tests = régression silencieuse garantie. Proposer de créer des tests d'abord est la bonne réponse.
+- **Rapport de violations avant modifications.** Le refactorer produit toujours un rapport + plan, attend confirmation, puis exécute. Jamais aveugle.
+- **`/analyze` après pour confirmer.** Le cycle analyse → refactor → analyse est la boucle de qualité correcte.
+
+---
+
+## Cas de figure — corrections v2.2.0 validées
+
+Ces exemples valident les bugs corrigés dans la version 2.2.0.
+
+---
+
+### Cas A — Onboarding d'un monorepo Next.js + FastAPI
+
+**Contexte :** repo avec `apps/web/` (Next.js 14) et `apps/api/` (FastAPI). Pas de `CLAUDE.md`. La racine n'a qu'un `package.json` de workspace vide.
+
+**Avant v2.2.0 :** `/onboard` lisait le `package.json` racine (workspaces uniquement), ne trouvait pas de stack claire, produisait un `CLAUDE.md` incomplet ou demandait trop de questions.
+
+**Avec v2.2.0 :**
+```
+/onboard
+
+→ PHASE 1: apps/, pnpm-workspace.yaml détectés
+
+MONOREPO DETECTED
+Sub-packages: apps/web/, apps/api/
+Options:
+  A) Workspace entier — un CLAUDE.md à la racine
+  B) apps/web seulement
+  C) Chaque package séparément
+
+[User: A]
+
+→ Lit apps/web/package.json → Next.js 14, TypeScript, Tailwind
+→ Lit apps/api/pyproject.toml → FastAPI, SQLAlchemy, alembic
+→ Lit Makefile racine → make dev-web, make dev-api, make test
+
+→ CLAUDE.md généré:
+   Stack: Next.js 14 (apps/web/) + FastAPI (apps/api/) + PostgreSQL
+   Build: make dev-web | make dev-api | docker compose up --build
+   Structure: monorepo, 2 apps indépendantes, DB partagée
+```
+
+---
+
+### Cas B — ship-feature : subagent en échec
+
+**Contexte :** feature notifications email, STEP 4, tâche 3 (worker retry) échoue.
+
+**Avant v2.2.0 :** arrêt abrupt. L'utilisateur devait diagnostiquer lui-même, relancer manuellement.
+
+**Avec v2.2.0 :**
+```
+STEP 4 — Tâche 3 échoue:
+  pytest FAILED test_retry_on_failure — AssertionError: worker ne retente pas
+
+→ STEP 4b déclenché automatiquement
+
+DEBUG ANALYSIS: Worker ne retente pas après timeout SMTP
+ROOT CAUSE:
+  1. [HIGH] Mock déclenche ConnectionRefusedError ≠ SMTPException — le retry handler ne s'active pas
+  2. [MED]  max_retries non configuré dans le worker (valeur par défaut = 0)
+
+SHIP FEATURE — ERROR IN STEP 4
+OPTIONS:
+  A) Corriger le mock (hypothesis 1)
+  B) Passer cette tâche
+  C) Abort
+
+[User: A] → fix ciblé → re-run tâche 3 → passe ✅ → suite de la feature
+```
+
+---
+
+### Cas C — Projet mobile React Native : signal correct
+
+**Contexte :** `/init-project "App mobile KartApp React Native Expo iOS Android"`.
+
+**Avant v2.2.0 :** signal `frontend` uniquement → `gstack` potentiellement recommandé (aberrant sur mobile).
+
+**Avec v2.2.0 :**
+```
+SIGNALS: mobile (React Native + Expo détectés)
+
+RECOMMENDATIONS:
+  ⚡ ENABLE  : frontend-design — composants React Native (~200t)
+  ⚠️  DISABLE : gstack — mobile, pas de browser QA ni deploy web
+  ℹ️  OPTIONAL: ui-ux-pro-max — uniquement si design system complexe
+  ℹ️  NOTE    : Docker N/A pour les apps mobiles
+
+BLOCKING: none
+```
+
+---
+
+### Cas D — STEP 13 avec GSD v2 non installé
+
+**Contexte :** `/init-project` multi-session atteint STEP 13. `gsd` absent du PATH.
+
+**Avant v2.2.0 :** `gsd init` → "command not found" → erreur opaque.
+
+**Avec v2.2.0 :**
+```
+STEP 13 — GSD v2 INIT
+→ Vérification: command -v gsd → NOT FOUND
+
+⚠️ GSD v2 not installed.
+   Run: npm install -g gsd-pi
+   Then: /onboard add gsd (pour générer ROADMAP.md)
+
+→ STEP 13 skippé proprement
+→ Projet initialisé correctement ✅
+→ GSD v2 peut être ajouté plus tard
+```
+
+---
+
+### Cas E — CLI Rust : workflow minimaliste (0 plugin inutile)
+
+**Contexte :** `/init-project "CLI Rust jsonconv, pas de réseau, pas de frontend"`.
+
+```
+/plugin-check "CLI Rust convertisseur JSON/CSV/TOML"
+
+SIGNALS: simple, CLI pur
+COST: ~800t
+
+RECOMMENDATIONS:
+  ✅ KEEP   : superpowers
+  ⚠️ DISABLE: frontend-design, ui-ux-pro-max, gstack, context7, ruflo
+BLOCKING: none → "proceed"
+
+→ Scaffolder: cargo check comme verify (pas cargo build)
+→ Docker: N/A (CLI pur)
+→ Pipeline complet en ~800t passif, zéro bruit
+```
+
+Point clé : **`/plugin-check` est utile même pour confirmer qu'on n'a rien à activer.** Évite de polluer le contexte avec 3000t de plugins inutiles sur un projet simple.
+
+---
+
+## Cas de figure — corrections v2.3.0 validées
+
+---
+
+### Cas F — `/ship-feature` sans CLAUDE.md (nouveau repo cloné)
+
+**Contexte :** développeur clone un repo existant, lance directement `/ship-feature` sans avoir run `/onboard`.
+
+**Avant v2.3.0 :** le brainstorm (STEP 1) démarrait sans contexte projet → questions génériques, architecture inadaptée au projet réel.
+
+**Avec v2.3.0 :**
+```
+/ship-feature "Ajouter authentification OAuth Google"
+
+→ STEP 0  : plugin check OK
+→ STEP 0b : ls CLAUDE.md .claude/CLAUDE.md → rien trouvé
+
+⚠️ No CLAUDE.md found in this directory.
+   This project has not been onboarded into claude-config.
+   Run `/onboard` first, then re-run `/ship-feature`.
+   STOP.
+```
+
+L'utilisateur fait `/onboard`, obtient son CLAUDE.md, relance `/ship-feature` avec le bon contexte.
+
+---
+
+### Cas G — Onboarding monorepo turborepo (Option C séquentielle)
+
+**Contexte :** repo avec `apps/web/`, `apps/api/`, `packages/ui/`, `turbo.json`, `pnpm-workspace.yaml`.
+
+**Avant v2.3.0 :** Option C non implémentée — comportement indéfini.
+
+**Avec v2.3.0 :**
+```
+/onboard
+
+MONOREPO DETECTED (turbo.json + pnpm-workspace.yaml)
+Sub-packages: apps/web/, apps/api/, packages/ui/
+[User: C]
+
+── Package 1/3: apps/web ──
+  Stack: Next.js 14 / TypeScript
+  Genere: apps/web/CLAUDE.md + settings + .claudeignore
+  OK
+
+── Package 2/3: apps/api ──
+  Stack: Express / Prisma / PostgreSQL
+  Genere: apps/api/CLAUDE.md + settings + .claudeignore
+  OK
+
+── Package 3/3: packages/ui ──
+  Stack: React + Storybook + Tailwind
+  Genere: packages/ui/CLAUDE.md + settings + .claudeignore
+  OK
+
+Resume: 3 packages onboardes
+  apps/web    | Next.js 14    | OK
+  apps/api    | Express/Prisma| OK
+  packages/ui | React/Storybook| OK
+
+"Generate root-level ROADMAP.md? (yes/skip)"
+```
+
+Chaque package a son propre CLAUDE.md. Pas de CLAUDE.md racine (Option C).
+
+---
+
+### Cas H — plugin-advisor : signal `monorepo` evite gstack inutile
+
+**Contexte :** monorepo Next.js (apps/web/) + FastAPI (apps/api/). Avant : signal `frontend` + `deploy` → gstack recommandé pour tout le repo.
+
+**Avec v2.3.0 :**
+```
+SIGNALS: monorepo, frontend(apps/web/), fast-libs(Next.js), deploy(apps/api/)
+
+RECOMMENDATIONS:
+  OK KEEP   : superpowers
+  ENABLE    : frontend-design — apps/web/ uniquement (~200t)
+  WARN      : context7 — Next.js detecte dans apps/web/
+  DISABLE   : gstack — apps/api/ n'a pas de browser-qa
+              (NOTE: gstack aurait ete recommande si browser-qa present)
+  DISABLE   : ui-ux-pro-max — pas de design-system signal
+
+Cout total: ~1200t (au lieu de ~4400t avec gstack)
+```
+
+---
+
+### Cas I — doctor.sh detecte templates/ manquant (installation pre-v2.0.0)
+
+**Contexte :** installation ancienne (avant v2.0.0), `link.sh` n'avait pas de templates dans la boucle.
+
+**Avant v2.3.0 :** `/init-project` echouait silencieusement en STEP 5 (scaffolder ne trouvait pas `~/.claude/templates/project-CLAUDE.md`).
+
+**Avec v2.3.0 :**
+```
+bash doctor.sh
+
+── Symlinks ──
+  OK  ~/.claude/CLAUDE.md
+  OK  ~/.claude/settings.json
+  OK  ~/.claude/agents
+  OK  ~/.claude/skills
+  MISSING: ~/.claude/templates    ← nouveau check
+  OK  ~/.claude/hooks/session-start.sh
+
+Fix: cd /path/to/claude-config && bash link.sh
+```
+
+L'utilisateur voit exactement ce qui manque et la commande pour corriger.
+
+---
+
+### Cas J — session-start : box ne deborde pas avec 5 plugins actifs
+
+**Avant v2.3.0 :** avec `gstack frontend-design ui-ux-pro-max context7 ruflo` tous actifs, la ligne `ON` depassait la largeur de la box.
+
+**Avec v2.3.0 :**
+```
+┌─ Claude Code config ──────────────────────────────────┐
+│  ✅ ON  : security-guidance rtk superpowers            │
+│  🟢 ON  : gstack frontend-design ui-ux-pro-ma...      │  <- tronque a 37+...
+│  ⚫ OFF : none                                         │
+│  💰 ~5350t passif (48% budget)                        │
+│  📦 v2.3.0                                            │
+└───────────────────────────────────────────────────────┘
+```
+
+La box reste alignee. L'utilisateur voit qu'il y a plus de plugins (les `...` indiquent la troncature) et peut faire `/health` pour la liste complete.
+
+---
+
+## Cas de figure — corrections v2.4.0 validées
+
+---
+
+### Cas K — `/init-project` sur un projet avec CLAUDE.md existant
+
+**Contexte :** projet FastAPI avec un `CLAUDE.md` minimal (stack documenté, features absentes). L'utilisateur veut ajouter un module de facturation.
+
+**Avant v2.4.0 :** STEP 1 posait toutes les questions (stack, purpose, features, conventions) même si le stack était déjà documenté.
+
+**Avec v2.4.0 :**
+```
+/init-project "Ajouter un module de facturation au projet"
+
+STEP 1 — ls CLAUDE.md → FOUND
+📄 Existing CLAUDE.md found — using as context.
+
+Questions posées (manquantes seulement):
+  → Features v1 du module facturation ?
+  → Stratégie de tests ?
+  → Conventions spécifiques ?
+
+Questions SKIP (déjà dans CLAUDE.md):
+  → Stack (Python 3.12 / FastAPI / PostgreSQL) ✓
+  → Architecture ✓
+```
+3 questions au lieu de 6. Gain de temps significatif sur les projets déjà documentés.
+
+---
+
+### Cas L — `/status` en début de session (projet multi-semaines)
+
+**Contexte :** projet CardForge repris après 3 jours. GSD v2 initialisé, milestone 2 en cours.
+
+```
+/status
+
+PROJECT STATUS
+==============
+
+CONFIG
+  Version   : v2.4.0
+  Plugins ON: superpowers, frontend-design, context7 (~1200t)
+  GSD v2    : installed (2.64.0)
+
+PROJECT
+  CLAUDE.md : found
+  Stack     : React 18 + FastAPI + PostgreSQL + Docker
+  Branch    : feature/stripe-integration
+  Uncommitted: 3 files
+
+RECENT COMMITS (last 5):
+  a1b2c3d feat: add card collection schema
+  e4f5g6h fix: jwt refresh token expiry
+  ...
+
+GSD v2
+  Status    : initialized
+  Milestone : Milestone 2 — Boutique in-app
+  Progress  : 2/5 slices done
+
+QUICK ACTIONS
+  /ship-feature "..."  — next feature
+  /health              — full diagnostic
+```
+
+Vue complète en une commande. Utile après un break pour se réorienter avant de taper `/gsd auto`.
+
+---
+
+### Cas M — plugin-advisor depuis un sous-package de monorepo
+
+**Contexte :** l'utilisateur est dans `apps/web/` et lance `/plugin-check`. Le monorepo a `turbo.json` et `pnpm-workspace.yaml` à la racine (`../`).
+
+**Avant v2.4.0 :** pas de détection monorepo → plugins recommandés comme pour un projet standalone Next.js.
+
+**Avec v2.4.0 :**
+```
+/plugin-check "Next.js frontend"  (depuis apps/web/)
+
+PHASE 1 — upstream detection:
+  ls ../turbo.json → FOUND
+  ls ../pnpm-workspace.yaml → FOUND
+
+SIGNALS: monorepo (upstream), frontend, fast-libs(Next.js)
+NOTE: dans apps/web/ d'un monorepo (détecté via parent dir)
+
+RECOMMENDATIONS:
+  ENABLE: frontend-design — apps/web/ uniquement
+  WARN: context7 — Next.js détecté
+  DISABLE: gstack — pas de browser-qa dans ce package
+```
+
+La recommandation est correcte même sans être à la racine du monorepo.
+
+---
+
+### Cas N — doctor.sh avec compteur de symlinks
+
+**Contexte :** installation avant v2.0.0 — `templates/` n'est pas symlinké.
+
+```
+bash doctor.sh
+
+── Symlinks ──
+  ✓ ~/.claude/CLAUDE.md
+  ✓ ~/.claude/settings.json
+  ✓ ~/.claude/agents
+  ✓ ~/.claude/skills
+  ✗ ~/.claude/templates — MISSING
+  ✓ ~/.claude/hooks/session-start.sh
+  → Symlinks: 5/6 OK
+
+Fix: cd /path/to/claude-config && bash link.sh
+```
+
+Le compteur `5/6 OK` indique exactement le problème sans lire toutes les lignes.
+
+---
+
+### Cas O — session-start avec 5 toggles actifs
+
+**Avant v2.4.0 :** avec gstack + frontend-design + ui-ux-pro-max + context7 + ruflo actifs, la ligne débordait la box.
+
+**Avec v2.4.0 :**
+```
+┌─ Claude Code config ──────────────────────────────────┐
+│  ✅ ON  : security-guidance rtk superpowers            │
+│  🟢 ON  : gstack frontend-design +3 more              │
+│  ⚫ OFF : none                                         │
+│  💰 ~5350t passif (48% budget)                        │
+│  📦 v2.4.0                                            │
+│  💡 /plugin-check  before starting a new project   │
+│  🩺 /health  to run full diagnostic               │
+└───────────────────────────────────────────────────────┘
+```
+
+`+3 more` indique qu'il y a 3 plugins actifs supplémentaires. `/health` donne la liste complète.
+
+---
+
+---
+
+### Exemple 8 — Reprise d'une session interrompue avec GSD v2
+
+**Contexte :** projet CardForge (React + FastAPI), milestone 2 "Boutique Stripe" en cours. Travail interrompu 4 jours plus tôt. GSD v2 initialisé, 3/7 slices terminées.
+
+#### Étape 1 — Orientation rapide
+
+```
+/status
+
+PROJECT STATUS
+==============
+
+CONFIG
+  Version   : v2.5.0
+  Plugins ON: superpowers, frontend-design, context7 (~1200t)
+  GSD v2    : installed (2.64.0)
+
+PROJECT
+  CLAUDE.md : found
+  Stack     : React 18 + FastAPI + PostgreSQL + Docker
+  Branch    : feature/stripe-integration
+  Uncommitted: 1 file (src/components/checkout/CartSummary.tsx)
+
+RECENT COMMITS:
+  b3c4d5e feat: add cart persistence to localStorage
+  f6g7h8i feat: implement card collection display
+  j9k0l1m chore: setup Stripe SDK
+
+GSD v2
+  Status    : initialized
+  Milestone : Milestone 2 — Boutique in-app
+  Progress  : 3/7 slices done (43%)
+```
+
+En 5 secondes : je sais où j'en suis, ce qui était en cours, et qu'il reste 4 slices à faire.
+
+#### Étape 2 — Reprendre GSD v2 (terminal)
+
+```bash
+cd cardforge/
+gsd                   # relance une session GSD
+```
+
+GSD v2 lit `.gsd/` et reconstruit le contexte :
+```
+GSD v2 — Resume session
+Current milestone: Milestone 2 — Boutique in-app
+Last completed   : Slice 3 — Cart UI
+Next up          : Slice 4 — Stripe checkout integration
+
+Previous session crash detected? No — clean shutdown.
+State loaded from .gsd/state.db ✓
+
+/gsd auto    → reprendre en mode autonome
+/gsd         → reprendre en step mode (recommandé après longue pause)
+```
+
+#### Étape 3 — Reprendre en step mode (recommandé après pause longue)
+
+```
+/gsd
+
+── Slice 4 — Stripe checkout integration ──
+Tasks:
+  [ ] 4.1 — Implement PaymentIntent creation (backend)
+  [ ] 4.2 — Add Stripe Elements to CartSummary.tsx
+  [ ] 4.3 — Handle payment confirmation + webhook
+  [ ] 4.4 — Integration test: checkout flow
+
+Research: Stripe docs fetched (context7 active)
+Plan: ready
+
+Execute slice 4? (yes / review plan / modify)
+```
+
+Le step mode permet de relire le plan avant d'exécuter — critique après une pause où les décisions peuvent avoir changé.
+
+#### Étape 4 — Si une décision d'architecture a changé pendant la pause
+
+```
+/gsd discuss
+
+"Je veux utiliser Stripe Payment Element au lieu de CardElement —
+ c'est l'API recommandée depuis 2023"
+
+GSD v2 integrates your input into the current plan.
+Updated: Slice 4 plan — Payment Element instead of CardElement
+Continue? (yes)
+```
+
+GSD v2 met à jour le plan dans `.gsd/ROADMAP.md` sans perdre le travail déjà fait.
+
+#### Ce que ce workflow démontre
+
+- **`/status`** est le point d'entrée naturel après une pause — snapshot complet en 1 commande.
+- **GSD v2 `step mode`** est préférable à `auto` après une longue pause — permet de vérifier que les décisions sont toujours valides.
+- **`.gsd/ROADMAP.md`** est la source de vérité du progress — parsé par `/status` et par GSD lui-même.
+- **`/gsd discuss`** permet de modifier l'architecture en cours de route sans recommencer depuis zéro.
+
+---
+
+## Cas de figure — corrections v2.5.0 validées
+
+---
+
+### Cas P — `/init-project` détecte `.claude/CLAUDE.md`
+
+**Contexte :** projet Node.js/Express avec CLAUDE.md dans `.claude/` (pas à la racine).
+
+**Avant v2.5.0 :** `ls CLAUDE.md` ne trouvait rien → 6 questions pour redécouvrir le stack.
+
+**Avec v2.5.0 :**
+```
+/init-project "Ajouter notifications push"
+
+STEP 1: ls CLAUDE.md .claude/CLAUDE.md → .claude/CLAUDE.md FOUND
+📄 Existing CLAUDE.md found — using as context.
+
+Questions posées (manquantes seulement):
+  → Service push ? (Firebase/OneSignal/APNs ?)
+  → Types ? (in-app/email/mobile ?)
+
+Questions SKIP (déjà dans .claude/CLAUDE.md):
+  → Stack (Node.js 20 / Express / MongoDB) ✓
+  → Purpose ✓
+```
+2 questions au lieu de 6.
+
+---
+
+### Cas Q — `/status` avec GSD v2 et ROADMAP.md présent
+
+**Contexte :** projet CardForge avec `.gsd/ROADMAP.md` contenant des checkboxes GSD.
+
+**Avant v2.5.0 :** `cat .gsd/STATUS.md` → fichier inexistant → `"no STATUS.md"`.
+
+**Avec v2.5.0 :**
+```
+/status
+
+PHASE 3 — parse ROADMAP.md:
+  - [x] Slice 1 — Schema DB      ✓
+  - [x] Slice 2 — Auth JWT        ✓
+  - [x] Slice 3 — Collection cards ✓
+  - [ ] Slice 4 — Boutique Stripe  (en cours)
+  - [ ] Slice 5 — PvP
+  ...
+
+GSD v2
+  Status    : initialized
+  Milestone : Milestone 2 — Boutique in-app
+  Progress  : 3/7 slices done (43%)
+```
+
+---
+
+### Cas R — `/status` avec `.gsd/` vide (pas de ROADMAP.md)
+
+**Contexte :** `gsd init` fait mais `/gsd discuss` pas encore lancé.
+
+```
+/status
+
+GSD v2
+  Status    : initialized
+  Milestone : N/A
+  Progress  : N/A
+
+  GSD v2 initialized — no ROADMAP.md yet.
+  Run /gsd init or /gsd discuss to create one.
+```
+
+Message actionnable au lieu d'une erreur silencieuse.
+
+---
+
+### Cas S — `doctor.sh` détecte `status-reporter.md` manquant
+
+**Contexte :** installation v2.3.0 ou antérieure — `status-reporter.md` n'existait pas.
+
+```
+bash doctor.sh
+
+── Consistency ──
+  ✓ All skills have disable-model-invocation
+  ⚠ Missing agents: status-reporter.md — run: bash link.sh
+  ✓ No CRLF line endings detected
+```
+
+Sans ce check : `/status` chargerait un agent inexistant → erreur cryptique.
+
+---
+
+### Cas T — session-start avec 6 plugins actifs (tous affichés)
+
+**Avant v2.5.0 :** `gstack frontend-design +4 more` — 4 plugins masqués.
+
+**Avec v2.5.0 :**
+```
+┌─ Claude Code config ──────────────────────────────────┐
+│  ✅ ON  : security-guidance rtk superpowers            │
+│  🟢 ON  : gstack frontend-design ui-ux-pro-max context7│
+│         + ruflo skill-creator                          │
+│  ⚫ OFF : none                                         │
+│  💰 ~5750t passif (52% budget)                        │
+│  📦 v2.5.0                                            │
+└───────────────────────────────────────────────────────┘
+```
+
+Tous les noms visibles, box alignée.
+
+---
+
+### Cas U — onboarder crée `.gitignore` pour protéger `settings.local.json`
+
+**Contexte :** monorepo, Option B (apps/api/), aucun `.gitignore` dans le package.
+
+```
+/onboard B apps/api
+
+PHASE 5b — .gitignore check:
+  ls .gitignore → absent
+
+  Créé: apps/api/.gitignore
+    # claude-config — personal settings (never commit)
+    .claude/settings.local.json
+
+📝 Created .gitignore with .claude/settings.local.json entry
+```
+
+Sans ce check : `settings.local.json` risquait d'être commité avec les clés API et credentials.
+
+---
+
+---
+
+### Exemple 9 — Firmware C/C++ embarqué (workflow sans superpowers)
+
+**Contexte :** firmware pour microcontrôleur STM32 (C, bare-metal). Pas de réseau, pas de frontend, pas de Docker. L'outillage standard de superpowers (brainstorming Socratique, subagent pipeline) est surdimensionné pour ce contexte.
+
+**Setup plugins :**
+```
+/plugin-check "Firmware C STM32, bare-metal, pas de réseau, pas de frontend, pas de Docker"
+
+SIGNALS: simple, CLI/embedded
+COST: ~800t (superpowers seul)
+
+RECOMMENDATIONS:
+  OK KEEP   : superpowers (peut être utile pour brainstorm initial)
+  DISABLE   : frontend-design, ui-ux-pro-max, gstack, context7, ruflo
+  NOTE      : Pour un firmware vraiment simple (hotfix, modification ciblée),
+              même superpowers peut être désactivé → ~0t passif
+```
+
+**Workflow minimaliste — modification d'un driver existant :**
+
+```
+# Pas de /init-project, pas de GSD, pas de superpowers
+
+# 1. Comprendre avant de modifier
+/analyze src/drivers/uart.c
+
+OUTPUT:
+  ANALYSIS: src/drivers/uart.c
+  CONTEXT: Driver UART pour STM32F4, DMA en mode circulaire
+  KEY COMPONENTS:
+    uart_init(): 45 lignes — config registres + DMA
+    uart_send(): 12 lignes — écriture dans ring buffer
+    UART_IRQHandler(): 28 lignes — ISR, gère overrun
+  RISKS:
+    - uart_init() dépasse 25 lignes → split candidat
+    - Accès non-atomique à ring_buffer_head dans ISR — probability: high
+  OPEN QUESTIONS:
+    - Quid si DMA transfer pas terminé avant appel uart_send() ?
+```
+
+**Modification chirurgicale :**
+```
+/ship-feature "Corriger l'accès non-atomique au ring_buffer_head dans l'ISR"
+
+STEP 0b — CLAUDE.md found
+STEP 0  — plugin check: superpowers OK (ou désactivé si YOLO mode)
+
+STEP 1 — BRAINSTORM (rapide, contexte déjà clair depuis /analyze):
+  Design: protéger ring_buffer_head avec __disable_irq()/__enable_irq()
+  ou utiliser un flag volatile + memory barrier
+
+STEP 3 — VALIDATION GATE:
+  TASKS: 2
+    1. [src/drivers/uart.c] Ajouter protection atomique dans UART_IRQHandler
+    2. [tests/test_uart.c] Ajouter test simulant ISR concurrent
+
+STEP 4 — IMPLEMENT (subagents légers, modifications chirurgicales)
+```
+
+**Alternative : workflow encore plus minimaliste (sans /ship-feature) :**
+```
+# Pour un hotfix ultra-ciblé, ignorer l'orchestrateur
+/analyze src/drivers/uart.c    # comprendre
+# → modifier directement avec Edit tool
+# → vérifier avec make + flash sur hardware
+```
+
+**Points clés :**
+- `/plugin-check` confirme "superpowers seulement" → aucun plugin inutile actif.
+- `/analyze` est particulièrement utile sur du code C bas-niveau : l'analyzer identifie les accès non-atomiques, les race conditions, les violations de normes, **sans proposer de fix**.
+- Pour un firmware, le workflow `analyze → ship-feature` peut se réduire à `analyze → edit direct` si la modification est triviale.
+- GSD v2 n'est jamais pertinent pour du firmware : les sessions sont courtes et les tâches atomiques.
+
+---
+
+## Cas de figure — corrections v2.6.0 validées
+
+---
+
+### Cas V — `/status` compte les slices, pas les tasks
+
+**Contexte :** `.gsd/ROADMAP.md` avec 3 milestones, chacun subdivisé en slices (`###`) contenant des tasks (`- [ ]`).
+
+**Avant v2.6.0 :** comptait `- [x]` = nombre de tasks terminées → résultat faux (ex: `6/8 "slices"` alors que c'était des tasks).
+
+**Avec v2.6.0 :**
+```
+ROADMAP.md:
+  ## Milestone 1 — Auth [x]
+  ### Slice 1 — JWT setup [x]      ← slice terminée
+  ### Slice 2 — Login UI [x]       ← slice terminée
+  ## Milestone 2 — Boutique
+  ### Slice 3 — Cart UI [x]        ← slice terminée
+  ### Slice 4 — Stripe checkout    ← en cours
+  ### Slice 5 — Webhook handler    ← en attente
+
+/status → GSD v2 : Progress = 3/5 slices done (60%)
+          Milestone actuel : Milestone 2 — Boutique
+```
+
+3/5 correspond exactement au dashboard GSD v2.
+
+---
+
+### Cas W — `/ship-feature` affiche le contexte projet dès STEP 0b
+
+**Avant v2.6.0 :** STEP 0b trouvait CLAUDE.md → continuait silencieusement. Pas de rappel de contexte.
+
+**Avec v2.6.0 :**
+```
+/ship-feature "Ajouter webhook Stripe"
+
+STEP 0b — CLAUDE.md found
+📋 PROJECT CONTEXT
+  Project : CardForge
+  Stack   : React 18 + FastAPI + PostgreSQL + Docker
+  Branch  : feature/stripe-integration
+  Recent  : feat: add cart persistence
+             feat: implement collection display
+             chore: setup Stripe SDK
+  GSD     : Milestone 2 — Boutique (3/5 slices)
+
+→ STEP 1 — BRAINSTORM
+```
+
+Developer se réoriente instantanément — pas de risque d'implémenter sur la mauvaise branche.
+
+---
+
+### Cas X — session-start : 6 plugins actifs, tous affichés
+
+```
+┌─ Claude Code config ──────────────────────────────────┐
+│  ✅ ON  : security-guidance rtk superpowers            │
+│  🟢 ON  : gstack frontend-design ui-ux-pro-max context7│
+│             ruflo skill-creator                        │
+│  ⚫ OFF : none                                         │
+│  💰 ~5750t passif (52% budget)                        │
+│  📦 v2.6.0                                            │
+└───────────────────────────────────────────────────────┘
+```
+
+Tous les 6 plugins actifs visibles. Ligne de continuation alignée avec la ligne principale.
+
+---
+
+### Cas Y — Exemple 8 en action : reprise de session CardForge
+
+```
+# Dans Claude Code
+/status
+→ 3/5 slices, branche feature/stripe-integration, 1 fichier uncommitted
+
+# Dans un terminal
+gsd
+/gsd         (step mode — relire le plan avant d'exécuter)
+
+# Architecture change détectée pendant la pause
+/gsd discuss "Je veux PaymentElement pas CardElement"
+→ Plan mis à jour
+
+# Reprendre l'exécution autonome
+/gsd auto
+→ GSD exécute Slice 4 avec le plan mis à jour, commits propres
+```
+
+Cycle complet : orientation → vérification plan → décision → exécution. Zero perte de contexte.
+
+---
+
+## Cas de figure — corrections v2.7.0 validées
+
+---
+
+### Cas Z1 — `/status` détecte le bon milestone courant
+
+**Avant v2.7.0 :** `grep -E '^## ' | tail -5` → retournait les 5 derniers headings `##`, pouvait inclure des milestones **terminés** comme courant.
+
+**Avec v2.7.0 :**
+```
+ROADMAP.md:
+  ## Milestone 1 — Auth [x]
+  ### Slice 1 — JWT [x]
+  ## Milestone 2 — Boutique
+  ### Slice 3 — Cart UI [x]
+  ### Slice 4 — Stripe checkout    ← première slice en attente
+
+awk scan top-to-bottom:
+  → Slice 4 n'a pas [x] → milestone courant = "Milestone 2 — Boutique" ✓
+```
+
+---
+
+### Cas Z2 — `/status` affiche l'état des tests
+
+**Contexte :** projet Python, dernier pytest avec 1 test échoué.
+
+```
+/status
+
+PROJECT
+  CLAUDE.md   : found
+  Stack       : FastAPI / PostgreSQL
+  Branch      : feature/notifications
+  Uncommitted : 2 files
+  Tests       : 1 failing (test_email_worker.py::test_retry)
+```
+
+Developer voit immédiatement le test cassé avant de relancer GSD.
+
+---
+
+### Cas Z3 — `/ship-feature` : commits tronqués à 50 chars
+
+```
+📋 PROJECT CONTEXT
+  Recent  : a1b2c3d feat: add Stripe PaymentIntent creation wi...
+             e4f5g6h fix: jwt token refresh not working on mobi...
+             i7j8k9l chore: update all dependencies to latest v...
+```
+
+Messages complets disponibles via `git log` — le contexte PROJECT affiche uniquement les 50 premiers caractères.
+
+---
+
+### Cas Z4 — `doctor.sh` détecte `lib/` non symlinké
+
+```
+bash doctor.sh
+
+── Symlinks ──
+  ✓ ~/.claude/CLAUDE.md
+  ...
+  ⚠ ~/.claude/lib exists but is NOT a symlink
+  ✓ ~/.claude/hooks/session-start.sh
+  → Symlinks: 6/7 OK
+
+Fix: mv ~/.claude/lib ~/.claude/lib.bak && bash link.sh
+```
+
+Si `lib/` n'est pas un symlink vers le repo, `detect-plugins.sh` sourcé est la version installée localement — potentiellement périmée.
+
+---
+
+### Cas Z5 — plugin-advisor warn sur skill-creator inactif
+
+**Contexte :** projet React SaaS, `skill-creator` resté actif par oubli.
+
+```
+/plugin-check "React SaaS avec FastAPI"
+
+SIGNALS: frontend, deploy, fast-libs(React)
+
+WARN: skill-creator ON — aucun signal skill-creation détecté
+      → ~100t économisés si désactivé
+      → Activer uniquement quand vous créez des skills custom
+```
+
+---
+
+### Cas Z6 — Firmware C STM32 : aucun plugin inutile
+
+```
+/plugin-check "Firmware C STM32, bare-metal, I2C driver"
+
+SIGNALS: simple, embedded
+COST: ~800t (superpowers seul)
+
+DISABLE: frontend-design, ui-ux-pro-max, gstack, context7, ruflo, skill-creator
+NOTE: Pour hotfix ultra-ciblé, superpowers aussi optionnel
+```
+
+Pipeline complet disponible : `/analyze` → `/ship-feature` avec 0 overhead de plugins inutiles. Voir Exemple 9 pour le détail.
+
+---
+
+## Cas de figure — corrections v2.8.0 validées
+
+---
+
+### Cas AA — awk portable : milestone courant sur macOS et Linux
+
+```
+ROADMAP:
+  ## Milestone 1 — Auth [x]
+  ### Slice 1 — JWT [x]
+  ## Milestone 2 — Boutique
+  ### Slice 3 — Cart UI [x]
+  ### Slice 4 — Stripe checkout   ← pas de [x]
+
+awk scan (index() au lieu de regex):
+  ## Milestone 2 → ms = "## Milestone 2 — Boutique"
+  ### Slice 3 [x] → index = 14 ≠ 0 → skip
+  ### Slice 4 → index = 0 → PRINT "## Milestone 2" → EXIT ✓
+```
+
+Fonctionne identiquement sur GNU awk (Linux) et nawk (macOS).
+
+---
+
+### Cas AB — Tests field : fallback sur la commande de test
+
+```
+Projet Node.js, pas de run récent, mais package.json présent:
+
+/status → Tests: run 'jest --coverage' to check
+
+Projet Rust (pas de CI log):
+/status → Tests: run 'cargo test' to check
+
+Firmware C (pas de test infra du tout):
+/status → Tests: N/A
+```
+
+Plus jamais "unknown" quand il y a un test script défini.
+
+---
+
+### Cas AC — signal `embedded` sur firmware ESP32
+
+```
+/plugin-check "Firmware ESP32 WiFi driver, FreeRTOS, C"
+
+SIGNALS: embedded (ESP32, Firmware, FreeRTOS détectés)
+NOTE: embedded project detected — minimal plugin footprint
+
+RECOMMENDATIONS:
+  superpowers OPTIONAL
+  DISABLE: tout le reste (frontend-design, gstack, context7, ruflo, skill-creator)
+  gsd v2: NOT recommended
+
+Workflow: /analyze src/wifi_driver.c → /ship-feature si multi-fichiers
+COST: ~800t (ou 0 si superpowers désactivé)
+```
+
+---
+
+### Cas AD — doctor.sh liste les 8 agents
+
+```
+── Consistency ──
+  ✓ All 8 agents present (analyzer, interviewer, plugin-advisor, readme-updater,
+                           refactorer, scaffolder, onboarder, status-reporter)
+```
+
+Confirme visuellement la présence de `onboarder` et `status-reporter` (ajoutés en v2.4.0).
+
+---
+
+### Cas AE — Arbre de décision "Quel skill utiliser ?"
+
+| Situation | Skill |
+|---|---|
+| Bug dans API FastAPI existante | `/ship-feature` |
+| Comprendre un module avant modifier | `/analyze` |
+| Reprise après 4 jours | `/status` |
+| Install Claude Code cassée | `/health` |
+| App Flutter from scratch | `/init-project` |
+| Quels plugins pour React ? | `/plugin-check` |
+
+L'arbre de décision est maintenant disponible en début de USAGE.md (section "Quel skill utiliser ?").
+
+---
+
+## Cas de figure — corrections v2.9.0 validées
+
+---
+
+### Cas AF — signal `embedded` détecté depuis le filesystem
+
+**Contexte :** dossier firmware ESP32, `platformio.ini` présent, `src/*.c`, pas de `package.json`. L'utilisateur tape `/plugin-check` sans argument.
+
+**Avant v2.9.0 :** aucun signal détecté → recommandations génériques.
+
+**Avec v2.9.0 :**
+```
+/plugin-check   (sans argument, depuis le dossier firmware)
+
+PHASE 1 filesystem scan:
+  platformio.ini → FOUND → signal embedded
+
+SIGNALS: embedded (platformio.ini)
+NOTE: embedded project detected — minimal plugin footprint
+
+KEEP   : superpowers (optional)
+DISABLE: frontend-design, ui-ux-pro-max, gstack, context7, ruflo, skill-creator
+gsd v2 : NOT recommended (sessions courtes, tâches atomiques)
+```
+
+---
+
+### Cas AG — ROADMAP.md flat (pas de `###` slices)
+
+**Contexte :** GSD v2 initialisé avec un ROADMAP minimal : tasks directement sous `##`, sans `### Slice`.
+
+**Avant v2.9.0 :** awk ne trouvait aucun `###` → retournait `"all milestones complete"` → faux.
+
+**Avec v2.9.0 :**
+```
+ROADMAP:
+  ## Milestone 2 — Core
+  - [x] Create models
+  - [ ] Implement CRUD   ← task en attente
+
+awk fallback flat:
+  → "## Milestone 2 — Core (flat)"
+
+/status → GSD v2: Milestone 2 — Core (flat)
+```
+
+---
+
+### Cas AH — pytest cache `{}` = all passing
+
+**Avant v2.9.0 :** `cat .pytest_cache/.../lastfailed` affichait `{}` littéralement.
+
+**Avec v2.9.0 :**
+```python
+d = json.load(open('.pytest_cache/v/cache/lastfailed'))
+# d = {} → n = 0
+# Output: "pytest: all passing"
+```
+
+---
+
+### Cas AI — Refactoring profond : cycle `/analyze` → `/refactor` → `/analyze`
+
+```
+# Étape 1 : comprendre avant de toucher
+/analyze src/payment/
+→ RISKS: process_payment 95 lignes, global non-mockable, 0 tests
+
+# Étape 2 : corriger sur la base du rapport
+/refactor src/payment/
+→ split, injection, tests ajoutés
+
+# Étape 3 : confirmer que les violations sont résolues
+/analyze src/payment/
+→ VIOLATIONS FIXED: 95→18 lignes, injectable ✓
+→ TESTS: 8 passing
+```
+
+Ce cycle est maintenant documenté dans l'arbre de décision ("Quel skill utiliser ?").
+
+---
+
+### Cas AJ — README renvoie vers USAGE.md
+
+```
+# claude-config
+
+Global Claude Code configuration...
+
+> Guide d'utilisation complet : voir USAGE.md — workflows typiques, exemples
+> par type de projet, arbre de décision, cas validés...
+```
+
+Un nouvel utilisateur trouve immédiatement le guide pratique.
+
+---
+
+## Cas de figure — corrections v3.0.0 validées
+
+---
+
+### Cas AK — Rust FFI : plus de faux positif embedded
+
+**Contexte :** bibliothèque Rust avec bindings C (FFI). `tests/c_binding_test.c` présent mais c'est du Rust, pas du firmware.
+
+**Avant v3.0.0 :** présence de `.c` → signal embedded → recommandations firmware inutiles.
+
+**Avec v3.0.0 :**
+```
+PHASE 1: ls platformio.ini → absent, ls *.ld → absent
+Signal embedded: NOT detected ✓
+
+SIGNALS: none (Rust library)
+→ workflow normal Rust, superpowers + context7
+```
+
+Seuls `platformio.ini` ou un linker script `*.ld` déclenchent le signal embedded.
+
+---
+
+### Cas AL — ROADMAP avec `## Prerequisites` (faux positif évité)
+
+**Contexte :** ROADMAP.md avec sections `## Overview`, `## Prerequisites`, puis `## Milestone 1`.
+
+**Avant v3.0.0 :** awk flat matchait `## Prerequisites → - [ ] Node 22` → fausse progression.
+
+**Avec v3.0.0 :**
+```
+awk scoped:
+  ## Overview → ms="" (non-Milestone)
+  - [ ] review → ms="" → SKIP ✓
+  ## Prerequisites → ms="" (non-Milestone)
+  - [ ] Node 22 → ms="" → SKIP ✓
+  ## Milestone 1 — Auth → ms="## Milestone 1"
+  - [ ] Login UI → PRINT "## Milestone 1 (flat)" ✓
+```
+
+---
+
+### Cas AM — Projet Go : commande de test affichée
+
+```
+/status (projet Go avec go.mod)
+
+Tests: run 'go test ./...' to check
+```
+
+Couverture: Python (`pytest`), Node.js (`jest`), Rust (`cargo test`), Go (`go test ./...`).
+
+---
+
+### Cas AN — `/analyze` : mode DEBUG découvrable via argument-hint
+
+```
+Dans Claude Code, argument-hint visible:
+  /analyze <file/area — OR paste error/stack trace for DEBUG mode>
+  
+→ /analyze "TypeError at CartSummary.tsx:47 — Cannot read 'map' of undefined"
+→ DEBUG MODE activé automatiquement ✓
+```
+
+---
+
+### Cas AO — GSD v2 interrompu : reprise depuis l'arbre de décision
+
+```
+Arbre: "Session GSD v2 interrompue ?"
+→ gsd → /gsd auto    (reprend depuis .gsd/)
+→ /gsd steer         (modifier le plan)
+→ /gsd forensics     (analyser un échec)
+```
+
+GSD v2 reprend automatiquement depuis `.gsd/` — l'utilisateur n'a pas besoin de recommencer.
+
+---
+
+## Cas de figure — corrections v3.1.0 validées
+
+---
+
+### Cas AP — STM32 avec Makefile+C : signal embedded retrouvé
+
+**Contexte :** firmware STM32, `Makefile` + `src/main.c`, pas de `platformio.ini`, pas de `*.ld` séparé (linker inline dans Makefile).
+
+**Avant v3.1.0 :** `Makefile` retiré en v3.0.0 → signal absent → recommandations génériques.
+
+**Avec v3.1.0 :**
+```
+PHASE 1: ls Makefile → FOUND, ls src/*.c → 3 fichiers C
+         ls package.json Cargo.toml go.mod → absent
+
+Signal embedded: DETECTED (Makefile + .c + no ecosystem)
+→ DISABLE all toggles, superpowers optional ✓
+```
+
+---
+
+### Cas AQ — Rust FFI : toujours pas de faux positif
+
+```
+Cargo.toml présent + src/ffi.c
+→ Signal embedded: NOT detected (Cargo.toml = contre-indicateur) ✓
+```
+
+---
+
+### Cas AR — Onboarder PHASE 6 : ROADMAP.md généré même sans GSD installé
+
+**Avant v3.1.0 :** `gsd init` échouait silencieusement si GSD absent.
+
+**Avec v3.1.0 :**
+```
+PHASE 6 — command -v gsd → NOT FOUND
+
+⚠️ GSD v2 not installed — run: npm install -g gsd-pi
+ROADMAP.md generated (ready to use once GSD is installed).
+After installing: gsd → /gsd auto
+```
+
+ROADMAP.md est utile même sans GSD installé — l'utilisateur peut l'installer plus tard.
+
+---
+
+### Cas AS — `doctor.sh` détecte skill `/status` manquant
+
+```
+bash doctor.sh
+
+── Consistency ──
+  ⚠ Missing skills: status/ — run: bash link.sh
+  ✓ All 8 agents present (...)
+```
+
+---
+
+### Cas AT — Token cost visible sur les patterns
+
+```
+### Pattern A — Nouveau projet court (≤1 session) · ~3000-5000t
+
+Budget Pro note:
+  /init-project ≈ 3000-5000t ≈ 30-45% d'une session Pro (~11k tokens)
+  Planifier les grosses features sur des sessions séparées.
+```
+
+---
+
+## Erreurs fréquentes — diagnostic rapide
+
+| Erreur / Symptôme | Cause probable | Solution |
+|---|---|---|
+| `⚠️ No CLAUDE.md found` | `/ship-feature` dans un projet non onboardé | `/onboard` d'abord, puis relancer |
+| `command not found: gsd` | GSD v2 non installé ou pas dans PATH | `npm install -g gsd-pi` puis `source ~/.bashrc` |
+| `MISSING: ~/.claude/templates` dans doctor.sh | Installation pre-v2.0.0, `link.sh` pas rejoué | `cd /path/to/claude-config && bash link.sh` |
+| Scaffolder échoue sur projet Flutter | `flutter` non installé ou pas dans PATH | Installer Flutter SDK, puis `flutter doctor` |
+| Scaffolder échoue sur projet Expo | `npx` non disponible ou Node < 18 | `node --version` → mettre à jour Node si < 18 |
+| Plugin-check recommande gstack sur mobile | Signal `mobile` non détecté (manque RN/Expo/Flutter dans description) | Ajouter "React Native" ou "Flutter" explicitement dans le prompt |
+| Plugin-check recommande gstack sur monorepo sans browser QA | Signal `monorepo` non détecté | Vérifier que `apps/` ou `turbo.json` est détecté ; relancer depuis la racine du monorepo |
+| Session-start box mal alignée | Version < v2.3.0 | Mettre à jour depuis l'archive v2.3.0+ |
+| `/init-project` pose des questions déjà dans le prompt | Prompt incomplet (stack ou features manquants) | Ajouter stack, features v1, et conventions dans le prompt initial |
+| STEP 13 `gsd init` : "command not found" | GSD v2 non installé au moment de init-project | `npm install -g gsd-pi`, puis `/onboard add gsd` |
+| Plugin-check recommande plugins web sur firmware | signal `embedded` non détecté | Vérifier: `platformio.ini` ou `*.ld` présent, ou `Makefile` + `.c` + pas de `package.json`/`Cargo.toml`/`setup.py` |
+| `detect_ruflo` retourne faux positif | `claude-flow` ou `ruvnet` dans un autre fichier config | Inspecter `~/.claude.json` et `~/.mcp.json` manuellement |
+| `doctor.sh` : deny rules count mismatch | `settings.json` modifié manuellement | Vérifier avec `python3 -c "import json; print(len(json.load(open('~/.claude/settings.json'))['permissions']['deny']))"` — attendu : 100 |
+| Subagent échoue en STEP 4, pas de guidance | Version < v2.2.0 | Mettre à jour, le STEP 4b est ajouté en v2.2.0 |
+| `/analyze` ne passe pas en mode DEBUG | L'erreur n'est pas passée en argument | Copier l'erreur exacte dans l'argument : `/analyze "FAILED test_foo — TypeError: ..."`|
+| GStack skills/ manquant | Submodule initialisé mais `./setup` pas exécuté | `cd skills-external/gstack && ./setup` |
+
+---
+
+## Référence rapide — signaux → plugins
+
+```
+Description contient...    →  Plugin
+─────────────────────────────────────────────────────
+React / Vue / Svelte       →  frontend-design ON
+Next.js 13+ / App Router   →  context7 WARN
+Prisma / Supabase          →  context7 ON
+"design élaboré" / tokens  →  ui-ux-pro-max ON
+Docker + QA browser        →  gstack ON
+"plusieurs semaines"       →  gsd v2 CLI
+"5+ agents parallèles"     →  ruflo ON
+Rust / Python / Go / C     →  tout OFF sauf superpowers
+Mobile / Flutter / RN      →  frontend-design ON, gstack OFF
+Hotfix / script rapide     →  tout OFF sauf superpowers
+```
diff --git a/agents/analyzer.md b/agents/analyzer.md
index 22fb568..69090f1 100644
--- a/agents/analyzer.md
+++ b/agents/analyzer.md
@@ -67,3 +67,52 @@ OPEN QUESTIONS:
 ```
 
 Update project memory with discovered patterns and conventions.
+
+---
+
+## DEBUG MODE
+
+Activated when called with a failing test, error output, or broken build as target.
+
+### INPUTS EXPECTED
+- Exact error message or stack trace
+- File(s) involved
+- Last action that triggered the failure
+
+### PROCESS
+1. Read all files mentioned in the error (no guessing)
+2. Trace execution path from entry point to failure site
+3. Identify the exact line/expression that produces the error
+4. List all state at the point of failure (vars, imports, types)
+
+### OUTPUT FORMAT (DEBUG MODE)
+
+```
+DEBUG ANALYSIS: <error summary in one line>
+
+ERROR:
+  <exact message, file, line>
+
+TRACE:
+  <entry point> → <call chain> → <failure site>
+
+ROOT CAUSE HYPOTHESES (ordered by probability):
+  1. [HIGH] <specific hypothesis> — evidence: <what in the code supports this>
+  2. [MED]  <specific hypothesis> — evidence: <what in the code supports this>
+  3. [LOW]  <specific hypothesis> — evidence: <what in the code supports this>
+
+AFFECTED FILES:
+  - <file>: <what role it plays in the failure>
+
+WHAT TO VERIFY NEXT:
+  - <concrete check #1> — expected result if hypothesis 1 is correct
+  - <concrete check #2>
+
+DO NOT TOUCH:
+  - <file or logic that is NOT the cause, to avoid regression>
+```
+
+Rules in DEBUG MODE:
+- Never propose a fix. Only diagnose.
+- Never touch files.
+- Stop after the report. The orchestrator or user decides next steps.
diff --git a/agents/interviewer.md b/agents/interviewer.md
index af1acf9..f0eb232 100644
--- a/agents/interviewer.md
+++ b/agents/interviewer.md
@@ -1,6 +1,6 @@
 ---
 name: interviewer
-description: Gather all information needed to initialize a project. Asks targeted questions, synthesizes answers into a complete PROJECT BRIEF. Use as the first step of any project initialization.
+description: Gather project info. Ask targeted questions, produce PROJECT BRIEF. First step of project init.
 tools: Read
 model: sonnet
 ---
@@ -8,126 +8,56 @@ model: sonnet
 # INTERVIEWER
 
 ## ROLE
-Gather all necessary context before any design or implementation begins.
-
-## GOAL
-Produce a complete, unambiguous PROJECT BRIEF that all subsequent agents
-can use as their single source of truth.
-
----
+Gather context. Produce complete PROJECT BRIEF as single source of truth.
 
 ## BEHAVIOR
 
-- Ask ALL questions upfront in a single structured block.
-- Never make assumptions about missing information.
-- If the user's initial prompt already answers some questions clearly,
-  skip those and only ask what remains genuinely unclear.
-- Group questions logically so the user can answer efficiently.
-- After receiving answers, synthesize everything into a PROJECT BRIEF.
-- If any answer is ambiguous or contradictory, ask one follow-up before
-  producing the brief.
+- If the initial prompt already provides name + purpose + stack + features + architecture → skip questions and generate the BRIEF directly.
+- Otherwise ask only what's genuinely missing, in a single structured block.
+- After answers: produce BRIEF. One follow-up allowed if answer is ambiguous.
 
----
+## QUESTIONS (skip answered ones)
 
-## QUESTION GROUPS
-
-Present questions in this order, skipping any already answered
-by the initial prompt:
-
-### 1. PROJECT IDENTITY
-- What is the project name?
-- What is the project's purpose in one sentence?
-- Who are the target users?
-
-### 2. CORE FEATURES
-- List the top 5–10 features the first version must include.
-- Which features are strictly out of scope for now?
-
-### 3. TECH STACK
-- Preferred language(s)?
-- Framework(s) if applicable?
-- Database / storage needs?
-- External APIs or services to integrate?
-- Any hard constraint on dependencies (license, size, etc.)?
-
-### 4. ARCHITECTURE & DEPLOYMENT
-- Where will this run? (local, cloud, Docker, embedded, etc.)
-- Expected scale / performance constraints?
-- Monolith, microservices, library, CLI, or other?
-- Any existing codebase or code to integrate?
-
-### 5. QUALITY & WORKFLOW
-- Minimum test coverage expected?
-- Specific linting / formatting tools required?
-- CI/CD pipeline needed?
-- Any exceptions to the global CLAUDE.md coding rules for this project?
-
-### 6. CONVENTIONS
-- Naming style preferences (snake_case, camelCase, PascalCase, etc.)?
-- Any domain-specific terminology to use consistently?
-- Language for code comments and docs (English strongly recommended)?
-
----
+1. PROJECT: name, purpose (1 sentence), target users
+2. FEATURES: top 5–10 v1 features, what's out of scope
+3. STACK: language, framework, DB, external APIs, dependency constraints
+4. ARCH: runtime (local/cloud/Docker/embedded), scale, shape (monolith/micro/lib/CLI), existing code?
+5. QUALITY: test coverage, lint/format tools, CI/CD, exceptions to global CLAUDE.md rules
+6. CONVENTIONS: naming style, domain terms, comment language (English recommended)
 
 ## OUTPUT — PROJECT BRIEF
 
-After gathering answers, produce this document exactly:
-
 ```
-================================================================
-PROJECT BRIEF
-================================================================
+PROJECT: <name>
+PURPOSE: <one sentence>
+USERS: <who>
+LANG: <English/other>
 
-PROJECT NAME      : <name>
-PURPOSE           : <one sentence>
-TARGET USERS      : <who>
-LANGUAGE          : <English / other>
-
-----------------------------------------------------------------
 STACK
-----------------------------------------------------------------
-Language          : <lang + version if specified>
-Framework         : <framework or "none">
-Database          : <db or "none">
-External services : <list or "none">
-Runtime target    : <local / Docker / cloud / embedded / etc.>
-Architecture      : <monolith / microservices / lib / CLI / etc.>
+  Language : <lang+version>
+  Framework: <framework or none>
+  DB       : <db or none>
+  Services : <list or none>
+  Runtime  : <local/Docker/cloud/embedded>
+  Shape    : <monolith/micro/lib/CLI>
 
-----------------------------------------------------------------
-CORE FEATURES (v1)
-----------------------------------------------------------------
-1. <feature>
-2. <feature>
-...
+V1 FEATURES
+  1. <feature>
+  ...
+  OUT OF SCOPE: <list>
 
-OUT OF SCOPE
-- <feature>
-
-----------------------------------------------------------------
 QUALITY
-----------------------------------------------------------------
-Tests             : <strategy + minimum coverage>
-Lint / Format     : <tools>
-CI/CD             : <yes/no + details>
+  Tests  : <strategy + coverage>
+  Lint   : <tools>
+  CI/CD  : <yes/no + detail>
 
-----------------------------------------------------------------
 CONVENTIONS
-----------------------------------------------------------------
-Naming            : <style>
-Comments          : <style + language>
-Doc format        : <JSDoc / Doxygen / docstring / etc.>
+  Naming  : <style>
+  Comments: <style + lang>
+  Docs    : <JSDoc/Doxygen/docstring/etc>
 
-----------------------------------------------------------------
-EXCEPTIONS TO GLOBAL RULES
-----------------------------------------------------------------
-<list exceptions to ~/.claude/CLAUDE.md, or "none">
-
-----------------------------------------------------------------
-OPEN DECISIONS (if any remain)
-----------------------------------------------------------------
-<list anything still undecided that the designer must resolve>
-================================================================
+EXCEPTIONS TO GLOBAL RULES: <list or none>
+OPEN DECISIONS: <list or none>
 ```
 
-Do not proceed further. The PROJECT BRIEF is the only output
-of this agent. The orchestrator will pass it to the next step.
+Stop after BRIEF. Orchestrator handles next step.
diff --git a/agents/onboarder.md b/agents/onboarder.md
new file mode 100644
index 0000000..5d58849
--- /dev/null
+++ b/agents/onboarder.md
@@ -0,0 +1,227 @@
+---
+name: onboarder
+description: Onboard an existing project into claude-config. Generates CLAUDE.md, .claude/settings.json, .claudeignore, and optionally a GSD v2 ROADMAP.md. Use on repos not created via /init-project.
+tools: Read, Write, Edit, Bash, Glob, Grep
+model: sonnet
+---
+
+# ONBOARDER
+
+## ROLE
+Analyze an existing codebase and produce the full claude-config integration: CLAUDE.md, settings, .claudeignore. No feature changes. No refactoring.
+
+## INPUTS REQUIRED
+1. Project root directory (current working directory)
+2. Optionally: `$ARGUMENTS` with hints ("Python FastAPI", "add GSD", etc.)
+
+If called with no arguments → infer everything from the filesystem.
+
+---
+
+## PHASE 1 — DISCOVERY
+
+Read and catalog (non-destructive, no writes yet):
+
+```bash
+# Monorepo detection (run first — changes how everything else is read)
+ls apps/ packages/ workspaces/ services/ 2>/dev/null | head -10
+cat pnpm-workspace.yaml 2>/dev/null | head -10 || true
+cat turbo.json 2>/dev/null | head -10 || true
+cat nx.json 2>/dev/null | head -5 || true
+cat lerna.json 2>/dev/null | head -5 || true
+
+# Stack detection (root level)
+ls package.json pyproject.toml Cargo.toml go.mod pubspec.yaml 2>/dev/null
+cat package.json 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); print('name:', d.get('name'), '| workspaces:', d.get('workspaces'), '| scripts:', list(d.get('scripts',{}).keys())[:6])" 2>/dev/null || true
+cat pyproject.toml 2>/dev/null | head -20 || true
+cat Cargo.toml 2>/dev/null | head -10 || true
+
+# Structure
+find . -maxdepth 3 -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/__pycache__/*' -not -path '*/target/*' -not -path '*/.next/*' -not -path '*/dist/*' -not -path '*/build/*' | sort | head -80
+
+# Existing config
+ls .claude/ .claudeignore CLAUDE.md README.md .env.example 2>/dev/null
+cat CLAUDE.md 2>/dev/null | head -40 || true
+cat README.md 2>/dev/null | head -60 || true
+
+# Test/lint commands
+cat package.json 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); [print(k,':',v) for k,v in d.get('scripts',{}).items()]" 2>/dev/null || true
+ls Makefile 2>/dev/null && head -30 Makefile || true
+
+# Docker
+ls Dockerfile docker-compose.yml docker-compose.yaml 2>/dev/null
+
+# Git history summary
+git log --oneline -10 2>/dev/null || true
+```
+
+**Monorepo detection logic:**
+After running the commands above, determine if this is a monorepo:
+- Monorepo indicators: `apps/` or `packages/` with multiple sub-dirs, `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, or `workspaces` key in root `package.json`.
+
+**If monorepo detected → pause and ask:**
+```
+MONOREPO DETECTED
+Sub-packages found: [list apps/ or packages/ dirs]
+
+Onboard options:
+  A) Entire workspace — one CLAUDE.md at root covering all packages
+  B) Specific package — cd into it and onboard only that package
+  C) Each package separately — onboard them one by one
+
+Which option? (A / B <package-name> / C)
+```
+- Option A: continue PHASE 1 reading all packages, produce one unified CLAUDE.md at root
+- Option B (single package): onboard only the specified package
+  1. Print: "Onboarding <package-name> only (from <root>/<package-name>/)"
+  2. Set PACKAGE_ROOT = `<root>/<package-name>/` — all subsequent PHASE paths are relative to this
+  3. Run PHASE 1 discovery using PACKAGE_ROOT as the working directory
+  4. Run PHASE 2 interview scoped to this package only
+  5. Generate files at:
+     - `<PACKAGE_ROOT>/CLAUDE.md`
+     - `<PACKAGE_ROOT>/.claude/settings.json`
+     - `<PACKAGE_ROOT>/.claudeignore`
+  6. Do NOT touch the workspace root or other packages
+  7. PHASE 6 GSD v2 ROADMAP: generate at `<PACKAGE_ROOT>/ROADMAP.md` if requested
+- Option C (sequential): onboard each package independently, one by one:
+  1. Build the package list from `apps/` or `packages/` subdirs
+  2. Print: "Onboarding N packages sequentially: [list]"
+  3. For each package (index i / total):
+     a. Print "── Package i/N: <package-name> ──"
+     b. Run PHASE 1 discovery from `<package>/` as root
+     c. Run PHASE 2 interview for this package only (skip already answered)
+     d. Generate `<package>/CLAUDE.md`, `<package>/.claude/settings.json`, `<package>/.claudeignore`
+     e. Print: "✅ <package> onboarded"
+  4. After all packages: print summary table of all onboarded packages
+  5. Ask once at the end: "Generate root-level ROADMAP.md linking all packages? (yes/skip)"
+  Note: Do NOT generate a root-level CLAUDE.md in Option C — each package has its own.
+
+**If NOT monorepo:** continue normally.
+
+---
+
+## PHASE 2 — INTERVIEW (only missing info)
+
+From the discovery, determine what is still unknown:
+- Project name and purpose (if not in README or package.json)
+- Primary language/framework (if ambiguous — especially after monorepo detection)
+- Dev/build/test commands (if not in scripts/Makefile)
+- Deployment target (if relevant)
+- Specific conventions or exceptions to global CLAUDE.md rules
+
+For monorepos (option A): also ask about the relationship between packages (shared lib? separate deploys? common DB?).
+
+Ask only genuinely missing info in a single block. Skip what was found.
+
+---
+
+## PHASE 3 — GENERATE CLAUDE.md
+
+Read `~/.claude/templates/project-CLAUDE.md` and `~/.claude/CLAUDE.md`.
+
+Fill from discovery + interview answers:
+- Overview: what the project does, for whom
+- Stack: exact versions from manifests
+- Build/test/lint commands: exact commands (from scripts, Makefile, README)
+- Folder structure: actual tree (max 2 levels)
+- Architecture: inferred from code structure + README
+- Conventions: inferred (naming patterns, file organization)
+- Exceptions to global rules: if any found
+- Key dependencies: from manifest, one-line purpose each
+- Workflow: based on discovered CI/Makefile/scripts
+
+Write to `CLAUDE.md` at project root.
+
+---
+
+## PHASE 4 — GENERATE .claude/settings.json
+
+Read `~/.claude/templates/settings/settings.json`.
+
+Keep only stack-relevant allow blocks:
+- Node.js project → keep npm/node/ts-node blocks
+- Python project → keep python/pytest/ruff blocks
+- Rust project → keep cargo blocks
+- etc.
+
+Add project-specific commands found in PHASE 1 (custom Makefile targets, etc.).
+Write to `.claude/settings.json`.
+
+---
+
+## PHASE 5 — GENERATE .claudeignore
+
+Read `~/.claude/templates/settings/.claudeignore`.
+Extend with project-specific ignores (e.g., large data dirs, vendor dirs, build outputs specific to this stack).
+Write to `.claudeignore` at project root.
+
+---
+
+## PHASE 5b — .gitignore SAFETY CHECK
+
+```bash
+ls .gitignore 2>/dev/null
+grep 'settings.local.json' .gitignore 2>/dev/null || echo "not found"
+```
+
+- **`.gitignore` exists AND contains `settings.local.json`** → nothing to do. ✅
+- **`.gitignore` exists but does NOT contain `settings.local.json`** →
+  Append to existing `.gitignore`:
+  ```
+  # claude-config — personal settings (never commit)
+  .claude/settings.local.json
+  ```
+  Print: "📝 Added .claude/settings.local.json to existing .gitignore"
+- **`.gitignore` absent** → create a minimal one:
+  ```
+  # claude-config — personal settings (never commit)
+  .claude/settings.local.json
+  ```
+  Print: "📝 Created .gitignore with .claude/settings.local.json entry"
+
+Target path for `.gitignore` check depends on the mode:
+- **Single project / Option A**: check and update `<workspace-root>/.gitignore`
+- **Option B**: check and update `<PACKAGE_ROOT>/.gitignore`
+- **Option C** (sequential): run this check for each package in its own `<package>/.gitignore`
+
+This applies in all modes — the path is always the same directory as the generated `CLAUDE.md`.
+
+---
+
+## PHASE 6 — GSD v2 ROADMAP (optional)
+
+Ask: "Generate a GSD v2 ROADMAP.md for multi-session feature management? (yes / skip)"
+
+If yes:
+- **First check: `command -v gsd`**
+  - If NOT found: print "⚠️ GSD v2 not installed — run: `npm install -g gsd-pi`
+    ROADMAP.md will be generated but `gsd init` cannot run now.
+    After installing: run `gsd` in your terminal → `/gsd auto`."
+    Generate ROADMAP.md anyway (it will be ready when GSD is installed).
+  - If found: generate ROADMAP.md then print "✅ Run `gsd` in terminal → `/gsd auto` to start."
+- Read CLAUDE.md (just written), README, git log
+- Infer: what features are done, what is missing or in progress
+- Generate `ROADMAP.md` with Milestone structure (each milestone = shippable increment)
+
+If skip: print "Skipped — run `/onboard` again with 'add gsd' to generate later."
+
+---
+
+## OUTPUT
+
+```
+ONBOARD COMPLETE: <project name>
+STACK      : <detected stack>
+FILES WRITTEN:
+  ✅ CLAUDE.md
+  ✅ .claude/settings.json
+  ✅ .claudeignore
+  [✅ ROADMAP.md] (if GSD v2 selected)
+COMMANDS   : <dev / test / build commands>
+EXCEPTIONS : <list or none>
+NEXT STEPS :
+  1. Review CLAUDE.md — correct any wrong inferences
+  2. bash ~/.claude/link.sh — verify symlinks OK
+  3. /plugin-check "<project type>" — configure plugins
+  4. /ship-feature "<next feature>" — start working
+```
diff --git a/agents/plugin-advisor.md b/agents/plugin-advisor.md
index cbc0291..9353a31 100644
--- a/agents/plugin-advisor.md
+++ b/agents/plugin-advisor.md
@@ -1,6 +1,6 @@
 ---
 name: plugin-advisor
-description: Analyze the current project context and running plugins to recommend which plugins to enable or disable before starting work. Use as a gate before init-project and ship-feature.
+description: Check active plugins vs project needs. Recommend enable/disable before starting work. Gate before init-project and ship-feature.
 tools: Read, Bash, Glob, Grep
 model: haiku
 ---
@@ -8,134 +8,243 @@ model: haiku
 # PLUGIN ADVISOR
 
 ## ROLE
-Analyze project scope and active plugins.
-Recommend enabling or disabling plugins based on what the work actually needs.
-
-## GOAL
-Prevent two failure modes:
-1. Starting a complex project without the right plugins active (missing capabilities)
-2. Running a simple task with heavy plugins active (wasted tokens)
+Detect active plugins and project signals. Recommend enable/disable. Apply compatibility matrix. Block or warn as needed.
 
 ---
 
-## PHASE 1 — DETECT ACTIVE PLUGINS
-
-Run these commands to get the current state:
+## PHASE 1 — DETECT
 
 ```bash
-# List all installed and enabled plugins
+# Claude Code plugins
 claude plugin list 2>/dev/null || echo "plugin-list-unavailable"
 
-# Check if GStack is installed
-ls ~/.claude/skills/gstack/skills/ 2>/dev/null | wc -l || echo "0"
+# GStack skills count (toggle CC plugin)
+ls $HOME/.claude/skills/gstack/skills/ 2>/dev/null | wc -l || echo "0"
 
-# Check if RTK hook is active
-grep -l "rtk" ~/.claude/settings.json 2>/dev/null | head -1 || echo "rtk-not-configured"
+# MCP servers
+claude mcp list 2>/dev/null | grep -E "context7|ruflo" || echo "no-mcp"
 
-# Check if Context7 MCP is configured
-claude mcp list 2>/dev/null | grep context7 || echo "context7-not-configured"
+# Standalone CLIs
+command -v gsd &>/dev/null && gsd --version 2>/dev/null | head -1 || echo "gsd-not-installed"
+command -v rtk &>/dev/null && rtk --version 2>/dev/null | head -1 || echo "rtk-not-installed"
+command -v ruflo &>/dev/null && ruflo --version 2>/dev/null | head -1 || echo "ruflo-cli-not-in-path"
 
-# Check if GSD is installed
-ls ~/.claude/skills/ 2>/dev/null | grep gsd || echo "gsd-not-installed"
+# Project signals (run from project root)
+ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null | head -5
+grep -rl "next\|react\|vue\|prisma\|supabase" package.json 2>/dev/null | head -3 || true
+find . -name "*.tsx" -o -name "*.jsx" 2>/dev/null | head -3 | wc -l
+find . -name "docker-compose*" -o -name "Dockerfile" 2>/dev/null | head -3 | wc -l
+# Monorepo detection (current dir + parent dirs for sub-package context)
+ls apps/ packages/ services/ workspaces/ 2>/dev/null | head -5
+ls pnpm-workspace.yaml turbo.json nx.json lerna.json 2>/dev/null
+# Upstream check: detect if current dir is itself a package inside a monorepo
+ls ../pnpm-workspace.yaml ../turbo.json ../nx.json ../../turbo.json ../../pnpm-workspace.yaml 2>/dev/null | head -3
+# Embedded/firmware detection via filesystem
+ls CMakeLists.txt platformio.ini 2>/dev/null
+ls *.ld *.lds linker*.ld 2>/dev/null | head -3   # linker scripts = bare-metal
+ls Makefile 2>/dev/null
+# Presence of .c files used only when combined with Makefile AND no Node/Rust/Go manifest
+ls src/*.c 2>/dev/null | head -3
+ls package.json Cargo.toml go.mod pubspec.yaml setup.py pyproject.toml 2>/dev/null | head -1   # counterindicators (ecosystem present = not bare embedded)
 ```
 
 ---
 
-## PHASE 2 — ANALYZE THE REQUEST
+## PHASE 2 — ANALYZE $ARGUMENTS
 
-From the user's description ($ARGUMENTS), extract:
+Detect signals from the project description and filesystem scan:
 
-**Project signals:**
-- Has frontend UI? (React, Vue, HTML, mobile app, dashboard, landing page, design…)
-- Has complex design needs? (design system, multiple variants, color/typography choices…)
-- Has browser/QA needs? (test in browser, automated QA, screenshot…)
-- Has deployment needs? (deploy, CI/CD, canary, production…)
-- Has multi-session scope? (large feature, multi-day, cross-session continuity…)
-- Uses fast-evolving libs? (Next.js, React, Prisma, Supabase, Tailwind, FastAPI…)
-- Estimated complexity: small / medium / large / very-large
+| Signal | How to detect |
+|---|---|
+| `frontend` | .tsx/.jsx files, React/Vue/Next/Svelte in deps |
+| `mobile` | React Native / Expo in deps, `pubspec.yaml` present (Flutter), or "mobile"/"iOS"/"Android" in description |
+| `monorepo` | `apps/` or `packages/` with >1 sub-dir, `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, or `workspaces` key in root `package.json`; **or** parent dir has `turbo.json`/`pnpm-workspace.yaml` (current dir is a sub-package) |
+| `design-system` | tokens, theme files, storybook, design references |
+| `deploy` | docker-compose, Dockerfile, CI config, cloud references |
+| `browser-qa` | playwright, cypress, puppeteer in deps |
+| `multi-session` | description says "multi-day", "large feature", "multiple sessions" |
+| `fast-libs` | Next.js, React 18+, Prisma, Supabase, Drizzle, Expo SDK in deps |
+| `multi-agent` | "orchestrate agents", "parallel workers", "swarm", >5 concurrent agents needed |
+| `complex-arch` | multiple services, event bus, distributed system in description |
+| `skill-creation` | "create a skill", "new skill", "custom skill", `/skill-creator` in description |
+| `embedded` | "firmware", "bare-metal", "microcontroller", "STM32", "ESP32", "RTOS", "driver", "kernel", "bootloader" in description; **or** `platformio.ini` present; **or** linker script (`*.ld`, `*.lds`) present; **or** `Makefile` + `src/*.c` + no `package.json`/`Cargo.toml`/`go.mod`/`setup.py`/`pyproject.toml` (C project without standard ecosystems). Note: `.c` files with a Rust/Node/Go manifest = FFI binding, NOT embedded. |
+| `simple` | single file, hotfix, quick script, no frontend, no deploy |
 
 ---
 
-## PHASE 3 — PRODUCE RECOMMENDATION
-
-Output this block exactly. Do not summarize — show the full table.
+## PHASE 3 — OUTPUT
 
 ```
-================================================================
 PLUGIN CHECK
-================================================================
+ACTIVE: [plugin — status, one line each]
+SIGNALS: [detected signals]
+COST ESTIMATE: ~Xt passive tokens (all active plugins combined)
 
-DETECTED ACTIVE PLUGINS
-------------------------
-✅ superpowers          — core workflow (always keep active)
-✅ security-guidance    — security hook (always keep active)
-✅ rtk                  — token compression (always keep active)
-[one line per detected plugin]
-❌ [plugin]             — not installed / not active
+RECOMMENDATIONS:
+  ✅ KEEP    : [plugin] — [reason]
+  ⚡ ENABLE  : [plugin] — [reason] — [install/enable cmd]
+  ⚠️  DISABLE : [plugin] — [token cost saved, not needed here]
+  ℹ️  OPTIONAL: [plugin] — [marginal benefit, low priority]
+  🖥️  CLI     : [gsd v2] — [run 'gsd' in terminal if multi-session]
 
-PROJECT SIGNALS DETECTED
--------------------------
-Frontend UI      : yes / no
-Complex design   : yes / no
-Browser QA       : yes / no
-Deployment       : yes / no
-Multi-session    : yes / no
-Fast-evolving libs: yes / no ([lib names])
-Complexity       : small / medium / large / very-large
-
-RECOMMENDATIONS
----------------
-[For each relevant plugin, one of:]
-
-✅ KEEP ACTIVE   : [plugin] — [one-line reason]
-⚡ ENABLE NOW    : [plugin] — [why it's needed] — [install command if not installed]
-⚠️  DISABLE      : [plugin] — [costs X tokens/session, not needed for this task]
-ℹ️  OPTIONAL     : [plugin] — [marginal benefit, your call]
-
-BLOCKING ISSUES (must resolve before continuing)
--------------------------------------------------
-[List only if a strongly-recommended plugin is missing/disabled]
-[or write "none"]
-
-================================================================
-ACTION REQUIRED? [YES — resolve blocking issues first] / [NO — proceed]
-================================================================
+CONFLICTS: [plugin A ↔ plugin B — overlap on X] or none
+BLOCKING: [issues] or none
+ACTION REQUIRED? YES / NO
 ```
 
 ---
 
-## DECISION MATRIX
+## DECISION TABLE
 
-| Signal | Plugin to enable | Plugin to disable |
+| Signal | Enable / Use | Disable / Skip | Notes |
+|---|---|---|---|
+| `frontend` | frontend-design, ui-ux-pro-max | — | Both complement each other |
+| `mobile` (React Native/Expo/Flutter) | frontend-design | gstack (no browser QA), Docker N/A | ui-ux-pro-max optional |
+| `monorepo` | per-package plugin recommendations | avoid recommending gstack for whole repo if only one package has browser QA | Specify which plugin applies to which package |
+| `design-system` | frontend-design, ui-ux-pro-max | — | High overlap but both useful |
+| `deploy` + `browser-qa` | gstack | — | Full-product workflow |
+| `multi-session` | gsd v2 CLI | — | Run `gsd` in terminal, not CC plugin |
+| `fast-libs` | context7 | — | Doc freshness critical |
+| `multi-agent` + `complex-arch` | ruflo (MCP) | — | Only if genuine swarm needed |
+| `simple` / single-session | — | gsd, gstack, ruflo, ui-ux-pro-max | Saves ~3000-5000t |
+| `embedded` / firmware | — | all toggles; superpowers optional | workflow: /analyze → edit or /ship-feature |
+| backend/lib/CLI only | — | frontend-design, ui-ux-pro-max, gstack | ~3100t saved |
+| small project / hotfix | — | gstack, ruflo, gsd | Overhead exceeds value |
+
+**GSD v2 note:** `gsd-pi` is a standalone CLI (Pi SDK), not a Claude Code plugin. Zero passive token cost in CC sessions. Recommend when: feature > 1 day, multiple isolated context windows needed, crash recovery, cost tracking, or parallel workers. Usage: `gsd` in terminal → `/gsd auto`.
+
+**Ruflo note:** `ruflo` is a heavy MCP server (310+ tools, ~500-1500t passive). Only recommend when the project explicitly requires coordinating 5+ specialized agents simultaneously or swarm/parallel-orchestration architecture. For standard multi-session work, GSD v2 is sufficient and lighter.
+
+---
+
+## COMPATIBILITY MATRIX
+
+### Conflicts and overlaps
+
+| Pair | Relation | Verdict |
 |---|---|---|
-| Frontend UI | frontend-design, ui-ux-pro-max | — |
-| Complex design (system, variants) | gstack (/design-*) | — |
-| Browser QA | gstack (/qa, /browse) | — |
-| Deployment in scope | gstack (/ship, /canary) | — |
-| Multi-session feature (days) | gsd | — |
-| Fast-evolving libs | context7 | — |
-| Backend/lib/CLI only, no frontend | — | frontend-design, ui-ux-pro-max, gstack |
-| Single session | — | gsd |
-| Simple fix or small task | — | gstack, gsd |
+| frontend-design ↔ ui-ux-pro-max | ⚠️ Overlap | Both do UI styling. Keep both for design-heavy projects; drop ui-ux-pro-max for simple UIs. ~600t combined. |
+| gstack ↔ gsd v2 | ✅ Complementary | GStack = full-product CC workflow. GSD v2 = multi-session CLI. Different scopes, no conflict. |
+| gstack ↔ ruflo | ⚠️ Overlap | Both orchestrate multi-step workflows. GStack is CC-native; ruflo is MCP swarm. High combined overhead (~3250-4250t). Use one or the other. |
+| gsd v2 ↔ ruflo | ⚠️ Overlap | GSD v2 = sequential session pipeline. Ruflo = parallel agent swarm. Pick one per project; ruflo only if genuinely parallel work needed. |
+| superpowers ↔ gsd v2 | ✅ Complementary | Superpowers = single-session execution. GSD v2 = multi-session CLI orchestration. No conflict. |
+| superpowers ↔ gstack | ✅ Complementary | Used together in /init-project and /ship-feature. Superpowers = engine, GStack = full-product skills. |
+| superpowers ↔ ruflo | ⚠️ Overlap | Both can orchestrate agent sub-tasks. Together only for advanced hybrid setups. |
+| context7 ↔ any | ✅ Independent | Doc lookup MCP, no workflow overlap. Always safe to combine. |
+| skill-creator ↔ superpowers | ⚠️ Minor overlap | Superpowers can create skills too. Keep skill-creator only when actively building new skills. |
+| frontend-design ↔ gstack | ✅ Complementary | GStack = deploy/QA layer; frontend-design = UI quality layer. Different concerns. |
+| pr-review-toolkit ↔ superpowers | ✅ Complementary | superpowers:requesting-code-review and /pr-review-toolkit:review-pr cover different review styles. |
+| rtk ↔ any | ✅ Independent | Hook-only token compression. Zero interaction with any plugin. |
+| security-guidance ↔ any | ✅ Independent | Hook-only security rules. Zero interaction. |
+
+### Recommended sets by project type
+
+| Project type | Plugins ON | OFF | Passive cost |
+|---|---|---|---|
+| Backend API / microservice | superpowers, context7 (if fast libs) | frontend-design, ui-ux-pro-max, gstack, ruflo | ~800t |
+| Frontend SPA / SSR | superpowers, frontend-design, ui-ux-pro-max, context7 | gstack, ruflo | ~1600t |
+| Full-stack SaaS | superpowers, gstack, frontend-design, ui-ux-pro-max, context7 | ruflo | ~4400t |
+| CLI tool / library | superpowers | all toggles | ~800t |
+| Multi-session large feature | superpowers + gsd v2 CLI (external) | ruflo (unless parallel) | ~800t CC |
+| Quick fix / hotfix | superpowers | all toggles | ~800t |
+| Design system / component lib | superpowers, frontend-design, ui-ux-pro-max | gstack, ruflo, gsd | ~1600t |
+| Fast-evolving libs (Next.js etc.) | superpowers, context7, frontend-design | ruflo | ~1200t |
+| Enterprise multi-agent orchestration | superpowers, ruflo + gsd v2 (external) | skill-creator, pr-review-toolkit | ~2300t CC |
+
+> security-guidance and rtk are ALWAYS ON (0 tokens) — omitted from cost estimates for clarity.
+
+### Conditional rules
+
+```
+RULE: IF "mobile" signal (React Native/Expo/Flutter detected):
+  → frontend-design ON (~200t) — mobile UI components
+  → gstack OFF — no browser QA on mobile
+  → Docker NOT relevant — no server-side containerization for mobile
+  → ui-ux-pro-max OPTIONAL (~400t) — only if design system complexity is high
+
+RULE: IF "monorepo" signal detected:
+  → scan each top-level package individually for frontend/deploy/fast-libs signals
+  → recommend plugins per-package, NOT for the whole repo
+  → if only apps/web/ has frontend: enable frontend-design for web package only
+  → if only apps/api/ has deploy: gstack only if apps/api/ has browser QA too
+  → NOTE in output: "Plugin X recommended for apps/web/ — disable for apps/api/"
+  → passive cost estimate = highest-cost package profile (other packages add nothing)
+
+RULE: IF "frontend" signal OR .tsx/.jsx count > 0:
+  → frontend-design ON (~200t)
+  → ui-ux-pro-max ON if "design-system" signal (~400t additional)
+
+RULE: IF "deploy" AND "browser-qa" signals:
+  → gstack ON (~2750t) — full-product workflow
+
+RULE: IF "multi-session" OR multi-day feature:
+  → Recommend gsd v2 CLI: npm install -g gsd-pi → gsd → /gsd auto
+  → Zero passive CC token cost
+
+RULE: IF "fast-libs" (Next.js/React 18+/Prisma/Supabase/Drizzle):
+  → context7 ON (~200t)
+
+RULE: IF "multi-agent" AND "complex-arch":
+  → ruflo MCP ON (~500-1500t)
+  → IF gstack also ON: WARN overlap (~3250-4250t combined)
+
+RULE: IF "simple" OR "hotfix":
+  → Disable all toggles. ~800t base only.
+
+RULE: IF "embedded" signal (firmware, bare-metal, microcontroller, or Makefile+C without Node/Rust/Go):
+  → Disable ALL toggles including gstack, context7, ruflo, skill-creator
+  → superpowers OPTIONAL: useful for initial design brainstorm on complex drivers,
+    but unnecessary for single-function patches — user decides
+  → GSD v2 CLI: not recommended (sessions are short, tasks are atomic)
+  → Recommend workflow: /analyze <file> → Edit direct (hotfix) or /ship-feature (multi-file)
+  → NOTE: print "embedded project detected — minimal plugin footprint recommended"
+
+RULE: IF gstack ON AND ruflo ON:
+  → WARN: functional overlap on multi-step orchestration
+  → Suggest: gstack for CC-native workflow, ruflo only if parallel swarm needed
+
+RULE: IF skill-creator ON AND no `skill-creation` signal detected:
+  → WARN: skill-creator active but no skill-creation signal (~100t saved if disabled)
+  → Disable unless you're actively building or editing custom skills
+
+RULE: IF `skill-creation` signal:
+  → skill-creator ON (~100t)
+  → superpowers ON — required for skill scaffolding
+
+RULE: IF `browser-qa` signal (e2e tests, Playwright/Cypress/Puppeteer in deps):
+  → gstack ON — browser automation and QA
+  → context7 OPTIONAL (depends on framework version)
+
+RULE: IF `design-system` signal (tokens, theme files, Storybook present):
+  → frontend-design ON (~200t)
+  → ui-ux-pro-max ON (~400t)
+  → WARN if both are OFF with this signal: significant design gap
+
+RULE: IF `complex-arch` signal (multiple services, event bus, distributed system):
+  → ruflo MCP ON (~500-1500t)
+  → gsd v2 CLI recommended for multi-session coordination
+  → IF gstack also ON: WARN combined cost ~3250-4250t — consider disabling one
+```
 
 ---
 
-## THRESHOLDS
+## BLOCK if
 
-**Block and require action if:**
-- Superpowers is not active (required by /init-project and /ship-feature orchestrators — install command: `claude plugin marketplace add obra/superpowers-marketplace && claude plugin install --scope user superpowers@superpowers-marketplace`)
-- Project has significant frontend AND frontend-design + ui-ux-pro-max are both disabled
-- Project uses Next.js/React/Prisma/Supabase AND context7 is not configured
-- Project is full-product (UI + deploy + QA) AND gstack is not installed
+- Superpowers not active → install: `claude plugin marketplace add obra/superpowers-marketplace && claude plugin install --scope user superpowers@superpowers-marketplace`
+- Significant frontend signal + frontend-design AND ui-ux-pro-max both off
+- Full-product (UI+deploy+QA) + gstack not installed
 
-**Warn but don't block if:**
-- Heavy plugins active but not needed (just cost notice)
-- GSD active for a simple single-session task
+## WARN (no block)
 
----
+- Active toggle plugins not needed for this task (dead passive cost)
+- gstack ON + ruflo ON simultaneously (overlap, ~3250-4250t)
+- ruflo ON with no multi-agent signal detected
+- Multi-session feature + `gsd` CLI not installed → `npm install -g gsd-pi`
+- Total passive cost > 5500t (~50% of Pro session budget)
+- **Next.js/React 18+/Prisma/Supabase detected + context7 not configured**
+  → Risk: Claude may generate code using outdated APIs (App Router changes frequently)
+  → Fix: `claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key KEY`
+  → Free key: https://upstash.com
+  → Type "force" to proceed without context7 (not recommended for fast-evolving libs)
 
-## IMPORTANT
-
-This agent only reads and checks. It never modifies files.
-If action is required, stop — wait for the user to enable/disable plugins.
-If no action required, state clearly "proceed" so the orchestrator continues.
+Never modify files. If action required → stop and wait. If not → say "proceed".
diff --git a/agents/readme-updater.md b/agents/readme-updater.md
index d7e79cd..d9364ce 100644
--- a/agents/readme-updater.md
+++ b/agents/readme-updater.md
@@ -1,320 +1,81 @@
 ---
 name: readme-updater
-description: Manage the project README in all lifecycle phases. Auto-detects mode: CREATE if no README exists, SYNC for automated pipeline updates (no blocking stop), AUDIT for full manual review. Called by /readme, init-project, and ship-feature.
+description: Manage project README. Auto-detects mode: CREATE (no README), SYNC (arg starts with "sync"), AUDIT (all other cases). Called by /readme, init-project, ship-feature.
 tools: Read, Write, Edit, Bash, Glob, Grep
 model: sonnet
 ---
 
 # README UPDATER
 
-## ROLE
-Single agent responsible for the README across the entire project lifecycle.
+## MODES
 
-## GOAL
-Always produce a README that is immediately actionable on any platform,
-accurate, and reflects the current state of the project.
+First word of `$ARGUMENTS` determines mode. CREATE takes precedence if README.md missing.
 
----
+- **CREATE** — README.md doesn't exist → build from scratch
+- **SYNC** — first word is exactly `sync` → silent updates, no stop
+- **AUDIT** — anything else (empty, description, "audit") → full diff + mandatory stop
 
-## MODE DETECTION
+## DOCKER DETECTION (run in all modes before writing)
 
-Determine the operating mode from $ARGUMENTS and context:
-
-**CREATE mode** — when `README.md` does not exist in the project root.
-Build the README from scratch using available sources.
-
-**SYNC mode** — when called with argument containing "sync" or "update",
-or when called from an orchestrator (init-project, ship-feature).
-Apply updates without blocking. No mandatory stop.
-
-**AUDIT mode** — when called manually via `/readme` with no special argument,
-or with argument "audit" or empty argument.
-Full diff analysis with mandatory stop before applying changes.
-
----
-
-## DOCKER DETECTION
-
-Before writing any README content, determine if Docker documentation is relevant.
-
-Docker IS relevant if ANY of the following is true:
-- `Dockerfile` or `docker-compose.yml` exists in the project
-- `CLAUDE.md` mentions: deploy, deployment, service, API, server, container, Docker
-- The project type is: web app, API, backend service, microservice, SaaS
-- The project has external dependencies: database, cache (Redis), message broker (Kafka/RabbitMQ)
-
-Docker is NOT relevant if the project type is:
-- Library / package (npm package, Python lib, Rust crate, Go module)
-- CLI tool with no server component
-- WordPress theme or plugin (deployed differently)
-- Device driver or system plugin
-- Mobile app (Flutter, React Native) — Docker is a stretch
-
-Store this as: `DOCKER_RELEVANT = true/false`
+Docker relevant if: Dockerfile or docker-compose.yml present, or CLAUDE.md mentions deploy/service/API/server/Docker, or project is web app/API/backend/SaaS, or has DB/Redis/Kafka dep.
+Docker NOT relevant if: library, CLI (no server), mobile app, driver/plugin.
+Store as `DOCKER_RELEVANT = true/false`.
 
 ---
 
 ## CREATE MODE
 
-*Triggered when: `README.md` does not exist.*
+Sources (in order): CLAUDE.md, folder structure (`find . -not -path '*/.git/*' -not -path '*/node_modules/*' ... | head -80`), package manifest, .env.example, Dockerfile/compose if present.
 
-### Sources to read (in order):
-1. `CLAUDE.md` (required)
-2. `~/.claude/CLAUDE.md` (global rules, for context only)
-3. Folder structure: `find . -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/__pycache__/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/target/*' | sort | head -80`
-4. Package manifest: `package.json`, `Cargo.toml`, `pyproject.toml`, `pubspec.yaml`, `go.mod`, `composer.json`
-5. `.env.example` if present
-6. `Dockerfile` and `docker-compose.yml` if present
+Generate sections: About (summary+objective+status), Prerequisites (per OS, exact cmds), Installation, Running (dev/prod/test/lint), Docker (only if DOCKER_RELEVANT), Project structure (2 levels), Configuration (all .env.example vars), Contributing (branch → test → commit → PR).
 
-### README structure to generate:
+Rules: exact runnable commands only, derive from CLAUDE.md, no placeholders.
 
-Every command must be exact and runnable.
-Never use placeholder examples — derive real commands from CLAUDE.md.
-
-```markdown
-# <Project Name>
-
-> <one-line tagline>
-
-## About
-
-**Summary**: <2–3 sentences: what it does, what problem it solves>
-**Objective**: <what success looks like for users>
-**Status**: `in development`
-
-## Prerequisites
-
-List every tool with minimum version and purpose.
-Organize by OS — only include steps that differ per OS.
-If a tool installs identically on all platforms, use a single block.
-
-### Windows
-<winget commands or installer URLs — exact>
-
-### Linux (Debian/Ubuntu)
-<apt/curl commands — exact>
-<if dnf/pacman differ meaningfully, add a note>
-
-### macOS
-<brew commands — exact>
-
-## Installation
-
-```bash
-# Clone
-git clone <repo-url>
-cd <project-name>
-
-# Install dependencies
-<exact command — derived from CLAUDE.md build commands>
-
-# Configure environment
-cp .env.example .env
-# Edit .env — required variables listed in Configuration section below
-
-# Database setup (if applicable)
-<exact migration/seed commands>
-
-# Build (if applicable)
-<exact build command>
-```
-
-## Running
-
-```bash
-# Development
-<exact dev command>
-
-# Production
-<exact prod command>
-
-# Tests
-<exact test command>
-
-# Lint / format (if configured)
-<exact lint command>
-```
-
-## [Docker] — INCLUDE ONLY IF DOCKER_RELEVANT = true
-
-```bash
-# Build and start all services
-docker compose up --build
-
-# Start in background
-docker compose up -d
-
-# Stop services
-docker compose down
-
-# View logs
-docker compose logs -f <service-name>
-
-# Run tests in container
-docker compose run --rm <app-service> <test-command>
-
-# Production build only
-docker build -t <project-name>:<tag> .
-```
-
-**Environment variables for Docker:**
-Copy `.env.example` to `.env` before running.
-The `docker-compose.yml` reads from `.env` automatically.
-
-If the project has a database service in docker-compose.yml:
-```bash
-# Run migrations inside container
-docker compose run --rm <app-service> <migration-command>
-```
-
-**Port mapping:**
-<list ports exposed by docker-compose.yml with their purpose>
-
-## Project structure
-
-<folder tree — 2 levels deep — with one-line description per entry>
-
-## Configuration
-
-| Variable | Required | Default | Description |
-|---|---|---|---|
-| <VAR_NAME> | yes/no | <value or "—"> | <what it does> |
-
-<derive from .env.example — every variable documented>
-
-## Contributing
-
-```bash
-# Create a branch
-git checkout -b feature/<name>
-
-# Run tests before committing
-<test command>
-
-# Commit and push
-git add .
-git commit -m "feat: <description>"
-git push origin feature/<name>
-```
-
-Open a pull request against `main`.
-```
-
-Write to `README.md`. No mandatory stop — print confirmation and continue.
+Output: `📄 README created — <N sections> [Docker: included/N/A]`. No stop.
 
 ---
 
 ## SYNC MODE
 
-*Triggered when: called with "sync", or from init-project/ship-feature.*
+Read: README.md, CLAUDE.md, git log (last 20), folder structure, manifests.
 
-### What SYNC does:
-1. Run DOCKER DETECTION
-2. Read `README.md`, `CLAUDE.md`, git log (last 20 commits), folder structure, manifests
-3. Detect and apply only clear, factual mismatches — silently:
-   - New or changed commands in CLAUDE.md not in README
-   - New env vars in `.env.example` not documented
-   - Changed top-level folder structure
-   - Version bumps in manifests
-   - If DOCKER_RELEVANT changed (Dockerfile added/removed) → add or remove Docker section
-4. Add `## Recent changes` entry if 5+ commits since last README update and no changelog exists
+Apply only clear factual mismatches (no prose rewrites, no speculation, no stops):
+- Changed commands in CLAUDE.md not in README
+- New .env.example vars undocumented
+- Changed folder structure
+- Version bumps in manifests
+- Docker section added/removed if DOCKER_RELEVANT changed
+- Add `## Recent changes` if 5+ commits since last README update and no changelog
 
-### What SYNC does NOT do:
-- Rewrite existing prose
-- Add speculative content
-- Stop and ask the user anything
-- Modify sections that are still accurate
-
-Print after completing:
-`📄 README synced — <N changes applied / "no changes needed">`
+Output: `📄 README synced — <N changes / "no changes needed"> [Docker: <status>]`
 
 ---
 
 ## AUDIT MODE
 
-*Triggered when: called via `/readme` with empty or "audit" argument.*
+### Phase 1 — Read
+README.md, CLAUDE.md, `git log --oneline -50`, `git diff HEAD~20..HEAD --stat`, folder structure, manifest, .env.example, Dockerfile/compose if present.
 
-### PHASE 1 — GATHER CONTEXT
+### Phase 2 — Status per section
+✅ current | 📝 update | ➕ missing | ❌ remove
 
-Read:
-1. `README.md` — current state (if missing, switch to CREATE mode automatically)
-2. `CLAUDE.md`
-3. Git history: `git log --oneline -50`
-4. Git diff vs last tag or `git diff HEAD~20..HEAD --stat`
-5. Folder structure
-6. Package manifest
-7. `.env.example`
-8. `Dockerfile`, `docker-compose.yml` if present
-9. Run DOCKER DETECTION
+Check: About still accurate, prereqs versions, install/run cmds, Docker section vs DOCKER_RELEVANT, structure vs reality, all .env vars documented.
 
-### PHASE 2 — AUDIT
-
-For each section, determine status:
-
-| Status | Meaning |
-|---|---|
-| ✅ current | Accurate |
-| 📝 update | Outdated |
-| ➕ missing | Should be added |
-| ❌ remove | No longer relevant |
-
-Check specifically:
-- About/Summary still matches project
-- Prerequisites versions still accurate
-- Missing tools
-- Installation commands still work
-- Running commands still accurate
-- Docker section: present if DOCKER_RELEVANT=true, absent if DOCKER_RELEVANT=false
-- Project structure matches reality
-- Configuration: all .env.example vars documented, no obsolete vars
-- Recent changes since last README update
-
-### PHASE 3 — AUDIT REPORT + MANDATORY STOP
+### Phase 3 — Report + MANDATORY STOP
 
 ```
-================================================================
 README AUDIT
-================================================================
-
-LAST MEANINGFUL COMMIT : <hash — message>
-DOCKER                 : relevant (✅ / ❌) — section <present / missing / N/A>
-
-STATUS SUMMARY
---------------
-✅ current  : <N sections>
-📝 update   : <N sections>
-➕ missing  : <N sections>
-❌ remove   : <N sections>
-
-DETAIL
-------
-<per-section findings — specific, actionable>
-
-================================================================
-Proceed with update? (yes / select sections / cancel)
-================================================================
+LAST COMMIT : <hash — msg>
+DOCKER      : relevant ✅/❌ — section present/missing/N/A
+SUMMARY     : ✅<n> 📝<n> ➕<n> ❌<n>
+DETAIL      : <per-section findings>
+Proceed? (yes / select sections / cancel)
 ```
 
-**MANDATORY STOP — wait for user confirmation.**
+### Phase 4 — Apply (after confirmation)
+Surgical edits only. Preserve structure and tone. 📝 replace, ➕ insert, ❌ remove or mark deprecated.
 
-### PHASE 4 — UPDATE (after confirmation)
+### Phase 5 — Verify
+Re-read. No broken markdown. Commands consistent with CLAUDE.md.
 
-Apply all approved changes surgically:
-- Preserve existing structure and tone
-- For 📝: replace only outdated content
-- For ➕: insert in logical order
-- For ❌: remove or mark `> ⚠️ Deprecated: <reason>`
-- Never rewrite the entire README
-
-### PHASE 5 — VERIFY
-
-Re-read the updated README.
-Confirm no broken markdown, all commands consistent with CLAUDE.md.
-
----
-
-## OUTPUT (all modes)
-
-**CREATE:** `📄 README created — <N sections> [Docker: included / not applicable]`
-**SYNC:** `📄 README synced — <N changes / "no changes needed"> [Docker: <status>]`
-**AUDIT:** Full report → `📄 README updated — <summary>`
+Output: `📄 README updated — <summary>`
diff --git a/agents/scaffolder.md b/agents/scaffolder.md
index 13a8af2..4326df6 100644
--- a/agents/scaffolder.md
+++ b/agents/scaffolder.md
@@ -1,6 +1,6 @@
 ---
 name: scaffolder
-description: Create the empty skeleton of a project. Generates CLAUDE.md, settings, folder structure, config files, empty entry points, installs dependencies, and optionally adds Docker config if the project type warrants it. Does NOT implement any business logic or features.
+description: Create empty project skeleton. Generates CLAUDE.md, settings, structure, config, empty entry points, installs deps, optional Docker. NO business logic.
 tools: Read, Write, Edit, Bash, Glob, Grep
 model: sonnet
 effort: high
@@ -8,355 +8,116 @@ effort: high
 
 # SCAFFOLDER
 
-## ROLE
-Create the empty skeleton of a project and make it buildable.
-
 ## GOAL
-Deliver a project where:
-- Folder structure and config files are in place
-- CLAUDE.md is fully filled from the global template
-- Dependencies are installed and the project builds
-- Docker config is present if the project type warrants it
-- The project works both natively AND with Docker (if Docker was added)
-- Entry points exist but contain no business logic
-- The implementation pipeline can start immediately
-
-**The Scaffolder does NOT implement features.**
-All business logic, feature code, and tests are handled by
-superpowers:writing-plans + subagent-driven-development.
-
----
-
-## INPUT REQUIRED
+Deliver a buildable skeleton: structure + config + empty entry points. No features, no business logic.
 
+## INPUTS REQUIRED
 1. PROJECT BRIEF (from interviewer)
 2. Approved DESIGN (from brainstorming)
 3. `~/.claude/templates/project-CLAUDE.md`
 4. `~/.claude/CLAUDE.md`
 
-If any input is missing → STOP and report.
+If any missing → STOP.
 
 ---
 
 ## PHASE 0 — DOCKER DECISION
 
-Before creating any files, decide if Docker is relevant.
-
-**Docker IS relevant** if ANY of these apply:
-- Project type is: web app, API, backend service, microservice, SaaS
-- Project has external runtime dependencies: database, Redis, Kafka, RabbitMQ, S3
-- PROJECT BRIEF or DESIGN mentions: deploy, deployment, container, Docker, cloud
-- The project is meant to be run as a persistent server/service
-
-**Docker is NOT relevant** if the project is:
-- A library / package (npm, pip, crate, Go module)
-- A CLI tool with no server component
-- A WordPress theme or plugin
-- A device driver or system plugin
-- A mobile app (Flutter, React Native)
-- A C/C++ project without networked services
-
-Store this decision as `DOCKER_RELEVANT = true/false`.
-
-**If DOCKER_RELEVANT = true**, Docker config is added as a parallel option.
-The project MUST still work natively without Docker.
-Docker is an additional way to run it, not a replacement.
+Docker relevant: web app/API/SaaS, external deps (DB/Redis/Kafka), BRIEF mentions deploy/Docker/cloud, persistent server/service.
+Docker NOT relevant: library, CLI (no server), **mobile app (React Native, Expo, Flutter)**, driver.
+Store: `DOCKER_RELEVANT = true/false`. If true → Docker is additional, project must still run natively.
 
 ---
 
-## PHASE 1 — GENERATE PROJECT CLAUDE.md
+## PHASE 1 — GENERATE CLAUDE.md
 
-Read `~/.claude/templates/project-CLAUDE.md` in full.
-Read `~/.claude/CLAUDE.md` to understand global rules.
-
-Fill in every section from the PROJECT BRIEF and approved DESIGN.
-No placeholders. No template examples left in.
-Mark irrelevant sections as `N/A — <reason>`.
-
-Required content:
-- Project overview (2–4 sentences)
-- Stack (language + version, framework, runtime, database)
-- Build commands (exact, native)
-- Test commands (exact)
-- Lint/format commands (exact or N/A)
-- Docker commands (if DOCKER_RELEVANT) — exact
-- Folder structure (actual tree)
-- Architecture (module responsibilities, data flow)
-- Project conventions
-- Exceptions to global rules (or "none")
-- Key dependencies (name — purpose)
-- Workflow expectations
-
-Write to `CLAUDE.md` at the project root.
+Read `~/.claude/templates/project-CLAUDE.md` and `~/.claude/CLAUDE.md`.
+Fill every section from BRIEF + DESIGN. No placeholders. Irrelevant sections → `N/A — <reason>`.
+Required: overview, stack+version, build/test/lint/docker commands (exact), folder tree, architecture, conventions, exceptions, deps, workflow.
+Write to `CLAUDE.md` at project root.
 
 ---
 
-## PHASE 2 — GENERATE SETTINGS
+## PHASE 2 — SETTINGS
 
-### a. `.claude/settings.json`
-Read `~/.claude/templates/settings/settings.json`.
-Adapt `allow` rules to this stack:
-- Keep only blocks relevant to this stack
-- Add stack-specific commands
-- If DOCKER_RELEVANT: add `Bash(docker compose *)`, `Bash(docker build *)`
-- Add project-specific `ask` rules
-
-### b. `.claudeignore`
-Read `~/.claude/templates/settings/.claudeignore`.
-Extend with stack-specific exclusions.
-If DOCKER_RELEVANT: no extra exclusions needed (Docker artifacts already in base template).
-
-### c. Print:
-```
-⚙️  SETTINGS SETUP
-.claude/settings.json  created
-.claudeignore          created
-
-Manual: copy ~/.claude/templates/settings/settings.local.json
-→ .claude/settings.local.json (gitignore it, never commit)
-```
+**a. `.claude/settings.json`** — read `~/.claude/templates/settings/settings.json`, keep only relevant stack blocks, add stack-specific cmds, add docker cmds if DOCKER_RELEVANT.
+**b. `.claudeignore`** — read `~/.claude/templates/settings/.claudeignore`, extend for stack.
+**c. Print** confirmation of both files + manual note for settings.local.json.
 
 ---
 
-## PHASE 3 — SCAFFOLD STRUCTURE
+## PHASE 3 — SCAFFOLD FILES
 
-Create every folder and file from the approved DESIGN.
+### Universal
+`CLAUDE.md`, `.gitignore` (stack-appropriate), `.env.example` (all vars described, no secrets), `.claude/settings.json`, `.claudeignore`.
 
-### Universal required files:
-| File | Content |
+### Entry points
+Empty structure only: imports + empty main/init. No logic.
+
+### Stack files
+
+**Node.js/TS**: `package.json` (scripts: dev/build/test/lint), `tsconfig.json` if TS, `.eslintrc`, `src/index.ts` (empty).
+**React**: `package.json`, `vite.config.ts`, `src/main.tsx`, `src/App.tsx` (empty), `src/components/`, `index.html`.
+**Python**: `pyproject.toml` or `requirements.txt`, `src/<pkg>/__init__.py`, `src/<pkg>/main.py` (empty).
+**FastAPI/Flask/Django**: `requirements.txt` (pinned), `src/<pkg>/main.py` (app init only), `routes/` + `models/` (empty), `.env.example`, `alembic.ini` if SQLAlchemy.
+**Rust**: `Cargo.toml`, `src/main.rs` or `src/lib.rs` (empty).
+**C/C++**: `Makefile` (all/clean/fclean/re, -Wall -Wextra -Werror), `src/`, `include/`, `main.c/.cpp` (empty).
+
+**React Native / Expo**: `package.json` (scripts: start/android/ios/test/lint), `tsconfig.json`, `app.json` (Expo config with name/slug/version/sdkVersion), `app/(tabs)/index.tsx` (empty tab), `app/_layout.tsx` (root layout, empty), `components/` (empty), `hooks/` (empty), `constants/Colors.ts` (empty), `.env.example`. No Docker. Install: `npx expo install`. Build check: `npx expo export --platform web --output-dir /tmp/expo-check --clear` (web build validates config without device).
+
+**Flutter**: `pubspec.yaml` (sdk: '>=3.0.0 <4.0.0', deps: flutter sdk, flutter_lints), `analysis_options.yaml`, `lib/main.dart` (empty MaterialApp), `lib/src/` (features/, shared/, core/), `test/widget_test.dart` (empty). No Docker. Install: `flutter pub get`. Build check: `flutter analyze` (validates pubspec + dart syntax without device).
+
+### Docker (only if DOCKER_RELEVANT)
+`Dockerfile`: multi-stage build (builder → production), non-root user, EXPOSE, CMD. Adapt to stack.
+`docker-compose.yml`: app service (build, ports, env_file), db/redis only if actually needed, named volumes.
+`.dockerignore`: node_modules, .git, .env, dist/build/target, __pycache__.
+Add `COMPOSE_PROJECT_NAME=<slug>` to `.env.example`.
+
+---
+
+## PHASE 4 — INSTALL DEPS
+
+| Stack | Command |
 |---|---|
-| `CLAUDE.md` | Generated in Phase 1 |
-| `.gitignore` | Stack-appropriate, comprehensive |
-| `.env.example` | All env vars with description, no real secrets |
-| `.claude/settings.json` | Generated in Phase 2 |
-| `.claudeignore` | Generated in Phase 2 |
-
-### Entry points and modules:
-- Entry point files exist with minimal structure (imports + empty main/app init)
-- Module/package files exist but are empty or have minimal declarations
-- No business logic anywhere
-
-### Stack-specific required files:
-
-**Node.js / TypeScript**
-```
-package.json           — name, scripts (dev/build/test/lint), dependencies
-tsconfig.json          — if TypeScript
-.eslintrc              — lint config
-src/index.ts           — empty entry point with comment
-```
-
-**React (frontend)**
-```
-package.json           — scripts: dev, build, preview, test, lint
-vite.config.ts         — bundler config
-src/main.tsx           — minimal entry point
-src/App.tsx            — empty root component
-src/components/        — empty folder
-index.html             — entry HTML
-```
-
-**Python**
-```
-pyproject.toml or requirements.txt
-src/<package>/__init__.py
-src/<package>/main.py  — empty entry point
-```
-
-**FastAPI / Flask / Django**
-```
-requirements.txt       — pinned dependencies
-src/<pkg>/main.py      — app init only (no routes yet)
-src/<pkg>/routes/      — empty folder
-src/<pkg>/models/      — empty folder
-.env.example           — DATABASE_URL, SECRET_KEY, etc.
-alembic.ini            — if using SQLAlchemy
-```
-
-**Rust**
-```
-Cargo.toml
-src/main.rs or src/lib.rs  — empty main / empty lib
-```
-
-**Go**
-```
-go.mod
-cmd/<app>/main.go      — empty main
-internal/              — empty folder
-```
-
-**C / C++**
-```
-Makefile               — targets: all, clean, fclean, re (-Wall -Wextra -Werror)
-src/                   — empty
-include/               — empty
-main.c or main.cpp     — empty main
-```
-
-**PHP / WordPress Theme**
-```
-style.css              — theme header (Name, Description, Version, etc.)
-functions.php          — empty theme setup
-index.php              — minimal template
-```
-
-**Flutter / Dart**
-```
-pubspec.yaml
-lib/main.dart          — minimal MaterialApp / CupertinoApp
-lib/app/               — empty folders
-```
-
-### Docker config (ONLY if DOCKER_RELEVANT = true):
-
-Create these files IN ADDITION to the native stack files above.
-The project must still run without Docker.
-
-**`Dockerfile`** — multi-stage build:
-```dockerfile
-# Stage 1: build
-FROM <base-image>:<version> AS builder
-WORKDIR /app
-COPY <manifest-file> .
-RUN <install-deps-command>
-COPY . .
-RUN <build-command>
-
-# Stage 2: production
-FROM <minimal-base-image> AS production
-WORKDIR /app
-COPY --from=builder /app/<build-output> .
-EXPOSE <port>
-CMD [<start-command>]
-```
-Adapt image, ports, and commands to the actual stack.
-Use non-root user for security.
-
-**`docker-compose.yml`** — all services:
-```yaml
-services:
-  app:
-    build: .
-    ports:
-      - "<host-port>:<container-port>"
-    env_file: .env
-    depends_on: [<db-service>]  # only if DB present
-
-  # Add only services actually needed:
-  db:       # if project uses a relational DB
-    image: postgres:16-alpine  # or mysql:8 / mariadb:11 as appropriate
-    environment:
-      POSTGRES_DB: ${DB_NAME}
-      POSTGRES_USER: ${DB_USER}
-      POSTGRES_PASSWORD: ${DB_PASSWORD}
-    volumes:
-      - db_data:/var/lib/postgresql/data
-
-  redis:    # only if project uses Redis
-    image: redis:7-alpine
-
-volumes:
-  db_data:
-```
-
-**`.dockerignore`**:
-```
-node_modules/
-.git/
-.env
-dist/
-build/
-target/
-__pycache__/
-*.pyc
-.pytest_cache/
-coverage/
-```
-
-After creating Docker files, add to `.env.example`:
-```
-# Docker (optional — only needed when using docker compose)
-COMPOSE_PROJECT_NAME=<project-slug>
-```
-
----
-
-## PHASE 4 — INSTALL DEPENDENCIES
-
-Install project dependencies so the build works.
-This is mandatory — the build verification in Phase 5 requires installed deps.
-
-Run the appropriate install command for the stack:
-
-| Stack | Install command |
-|---|---|
-| Node.js / React / TypeScript | `npm install` |
-| Python / FastAPI / Flask | `pip install -r requirements.txt` or `uv pip install -r requirements.txt` |
-| Rust | `cargo fetch` |
-| Go | `go mod download` |
+| Node.js/React/TS | `npm install` |
+| React Native / Expo | `npx expo install` |
 | Flutter | `flutter pub get` |
-| PHP / Composer | `composer install` |
-| C / C++ | No package manager — verify compiler is available: `gcc --version` or `clang --version` |
+| Python | `pip install -r requirements.txt` or `uv pip install -r requirements.txt` |
+| Rust | `cargo fetch` |
+| C/C++ | verify: `gcc --version` or `clang --version` |
 
-If the install command fails:
-1. Read the error output
-2. Fix the config file causing the failure (package.json, requirements.txt, etc.)
-3. Retry
-4. If it still fails after one fix attempt → report the error and stop
-
-If DOCKER_RELEVANT = true, also verify Docker is available:
-```bash
-docker --version && docker compose version
-```
-If Docker is not installed, print a warning but do not fail — native install continues.
+On failure: read error → fix config → retry once → if still failing: report and stop.
+If DOCKER_RELEVANT: `docker --version && docker compose version` — failure is warning, not blocker.
 
 ---
 
-## PHASE 5 — VERIFY SKELETON
+## PHASE 5 — VERIFY BUILD
 
-Run the build command on the empty project.
-The project must compile/start even with no features.
+Run build/check command from CLAUDE.md on empty project. Must succeed with no features.
 
-```bash
-# Native build
-<build-command from CLAUDE.md>
-```
+| Stack | Verify command | Notes |
+|---|---|---|
+| Node.js/TS/React | `npm run build` | Must produce dist/ without error |
+| React Native / Expo | `npx expo export --platform web --output-dir /tmp/expo-check --clear` | No device needed; validates config |
+| Flutter | `flutter analyze` | No device needed; validates pubspec + Dart syntax |
+| Python / FastAPI | start dev server, check port responds | |
+| Rust | `cargo check` | Faster than full build for skeleton |
+| C/C++ | `make` | Must produce binary |
 
-If build fails:
-1. Read the full error
-2. Fix the issue (missing import, wrong path, syntax error in empty file, etc.)
-3. Retry — maximum 2 attempts
-4. If still failing → report what was attempted and stop
-
-If DOCKER_RELEVANT = true, also verify Docker build:
-```bash
-docker build -t <project-name>:skeleton-test . --quiet
-```
-Docker build failure is a warning, not a blocker — native must pass.
+On failure: read error → fix → retry max 2 times → if still failing: report and stop.
+If DOCKER_RELEVANT: `docker build -t <n>:skeleton-test . --quiet` — failure is warning.
 
 ---
 
 ## OUTPUT
 
 ```
-SKELETON COMPLETE: <project name>
-
-FILES CREATED    : <count>
-DOCKER           : included / not applicable — <one-line reason>
-INSTALL          : ✅ dependencies installed / ❌ <e>
-BUILD (native)   : ✅ passes / ❌ <e>
-BUILD (docker)   : ✅ passes / ⚠️ not verified / N/A
-
-STRUCTURE:
-<actual tree of what was created>
-
-READY FOR IMPLEMENTATION PIPELINE:
-- V1 features to implement : <N> features from PROJECT BRIEF
-- Entry points ready       : ✅
-- Config files ready       : ✅
-- Dependencies installed   : ✅ / ❌
-- CLAUDE.md                : ✅ complete
-- README.md                : handled by readme-updater (next step)
-- Settings                 : ✅ .claude/settings.json + .claudeignore
+SKELETON COMPLETE: <name>
+FILES    : <count>
+DOCKER   : included / N/A — <reason>
+INSTALL  : ✅ / ❌ <error>
+BUILD    : ✅ / ❌ <error>
+DOCKER BUILD: ✅ / ⚠️ not verified / N/A
+STRUCTURE: <tree>
+READY: <N> v1 features | entry points ✅ | config ✅ | CLAUDE.md ✅ | README → readme-updater | settings ✅
 ```
diff --git a/agents/status-reporter.md b/agents/status-reporter.md
new file mode 100644
index 0000000..de113aa
--- /dev/null
+++ b/agents/status-reporter.md
@@ -0,0 +1,176 @@
+---
+name: status-reporter
+description: Consolidated project status — plugins, token budget, git state, build, tests, GSD milestone. Read-only snapshot. Use to orient quickly at session start or after a break.
+tools: Read, Bash, Glob, Grep
+model: haiku
+---
+
+# STATUS REPORTER
+
+## ROLE
+Produce a read-only consolidated status of the current project and Claude Code setup.
+No modifications. No design. No proposals. Facts only.
+
+---
+
+## PHASE 1 — SETUP STATUS
+
+```bash
+# Config version
+cat ~/.claude/version.txt 2>/dev/null || echo "unknown"
+
+# Active plugins (from session-start detection)
+command -v rtk &>/dev/null && echo "rtk: installed" || echo "rtk: missing"
+command -v gsd &>/dev/null && gsd --version 2>/dev/null | head -1 || echo "gsd: not installed"
+
+# Token estimate (passive)
+# (approximate from known plugin costs)
+```
+
+Check `~/.claude/plugins/cache` for active marketplace plugins.
+Check `~/.claude.json` for active MCP servers.
+
+---
+
+## PHASE 2 — PROJECT STATUS
+
+```bash
+# CLAUDE.md
+ls CLAUDE.md .claude/CLAUDE.md 2>/dev/null | head -1
+head -10 CLAUDE.md 2>/dev/null || head -10 .claude/CLAUDE.md 2>/dev/null || echo "no CLAUDE.md"
+
+# Git state
+git log --oneline -5 2>/dev/null || echo "not a git repo"
+git status --short 2>/dev/null | head -10
+git branch --show-current 2>/dev/null
+
+# Last build/test status (best-effort — several possible sources)
+# Try common CI output files
+cat .last-build.log 2>/dev/null | tail -3
+cat .last-test.log  2>/dev/null | tail -3
+# Try pytest cache (Python projects) — parse JSON: {} = all passing, {nodeids:[...]} = failures
+python3 -c "
+import json, os
+f = '.pytest_cache/v/cache/lastfailed'
+if os.path.exists(f):
+    try:
+        d = json.load(open(f))
+        n = len(d.get('nodeids', []))
+        print('pytest: all passing' if n == 0 else f'pytest: {n} failing')
+    except: pass
+" 2>/dev/null || true
+# Try Jest/Vitest last run
+cat coverage/coverage-summary.json 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); print('Jest coverage:', d.get('total',{}).get('statements',{}).get('pct','?'), '%')" 2>/dev/null || true
+# Fallback: if no result found, extract test command from manifest
+# so output can show "run '<cmd>' to check" instead of "unknown"
+if [ -f package.json ]; then
+  python3 -c "import json,sys; d=json.load(open('package.json')); print('test:', d.get('scripts',{}).get('test',''))" 2>/dev/null || true
+fi
+if [ -f pytest.ini ] || [ -f pyproject.toml ] || [ -f setup.cfg ]; then
+  echo "pytest: pytest (Python project detected)"
+fi
+if [ -f Cargo.toml ]; then
+  echo "rust: cargo test"
+fi
+if [ -f go.mod ]; then
+  echo "go: go test ./..."
+fi
+if [ -f composer.json ]; then
+  echo "php: ./vendor/bin/phpunit (or composer test)"
+fi
+```
+
+**Building the Tests field:**
+If any test result was found (pytest lastfailed, Jest coverage, log file):
+  → `Tests: all passing` (pytest {} or Jest 100%) or `Tests: X failing (<file::test>)` or `Tests: coverage X%`
+  Note: pytest `.pytest_cache/v/cache/lastfailed` with empty `{}` means all tests passed last run.
+If no result found but test command exists:
+  → `Tests: run '<test-command>' to check`
+If no test infrastructure found:
+  → `Tests: N/A`
+
+---
+
+## PHASE 3 — GSD v2 STATUS (if .gsd/ exists)
+
+```bash
+# Check .gsd/ presence and contents
+ls .gsd/ 2>/dev/null | head -10
+
+# ROADMAP.md — milestone checklist (most reliable source)
+cat .gsd/ROADMAP.md 2>/dev/null | head -60 || echo "no ROADMAP.md"
+
+# Slice-level progress — GSD v2 uses ### headings for slices (not tasks)
+# Slices done = ### headings with [x] marker
+grep -c '^### .*\[x\]' .gsd/ROADMAP.md 2>/dev/null || echo "0"
+# Slices total = all ### headings
+grep -c '^### ' .gsd/ROADMAP.md 2>/dev/null || echo "0"
+
+# Task-level count (informational only — not the primary progress metric)
+# Done tasks: - [x], Total tasks: - [
+grep -c '^\s*- \[x\]' .gsd/ROADMAP.md 2>/dev/null || echo "0"
+grep -c '^\s*- \[' .gsd/ROADMAP.md 2>/dev/null || echo "0"
+
+# Current milestone — tries slice-level first, falls back to task-level
+# Primary: first ## heading with a ### slice without [x]
+awk '/^## /{ms=$0} /^### /{if(index($0,"[x]")==0){print ms; exit}}' .gsd/ROADMAP.md 2>/dev/null
+# Fallback (flat structure — tasks directly under ##, no ### slices):
+# Scoped to ## Milestone headings only — avoids matching documentation lists
+# Resets on any non-Milestone ## heading (e.g. ## Prerequisites, ## Notes)
+awk '/^## [Mm]ilestone/{ms=$0} /^## / && !/[Mm]ilestone/{ms=""} /^- \[/{if(ms && index($0,"- [x]")==0){print ms" (flat)"; exit}}' .gsd/ROADMAP.md 2>/dev/null
+# All ## headings for context
+grep -E '^## ' .gsd/ROADMAP.md 2>/dev/null
+
+# Any additional GSD state files
+find .gsd/ -name "*.md" -not -name "ROADMAP.md" 2>/dev/null | head -5
+```
+
+**Reading the output:**
+- If `ROADMAP.md` exists: derive progress at **slice level** (### headings), not task level.
+  Slices done = `### headings with [x]`. Slices total = all `### headings`.
+  Report as: "X/Y slices done" — this matches GSD v2's own progress dashboard.
+  The current milestone = first `## heading` with an unchecked `### slice`. If no `###` slices exist (flat structure with tasks directly under `##`), fall back to the first `## heading` with an unchecked `- [ ]` task (second awk command, marked with "(flat)"). If both return empty, all milestones are complete.
+- If only `.gsd/` exists but no `ROADMAP.md`: GSD initialized but no roadmap yet.
+  Print: "GSD v2 initialized — no ROADMAP.md yet. Run `/gsd init` or `/gsd discuss` to create one."
+- If `.gsd/` is absent: print "GSD v2 not initialized for this project."
+- Never attempt to read `state.db` or binary files — print "N/A" if state unclear.
+
+---
+
+## OUTPUT FORMAT
+
+```
+PROJECT STATUS
+══════════════════════════════════════
+
+CONFIG
+  Version   : v<N>
+  Plugins ON: <list> (~<X>t passive)
+  GSD v2    : installed / not installed
+
+PROJECT
+  CLAUDE.md : found / missing
+  Stack     : <from CLAUDE.md overview or "unknown">
+  Branch    : <current git branch>
+  Uncommitted: <count> files / clean
+  Tests     : <last known result — "passing" / "X failing" / "unknown">
+
+RECENT COMMITS (last 5):
+  <hash> <message>
+  ...
+
+GSD v2
+  Status    : initialized / not initialized
+  Milestone : <current milestone or "none">
+  Progress  : <X/Y slices done or "N/A">
+
+QUICK ACTIONS
+  /plugin-check "<stack>" — audit plugins
+  /ship-feature "<desc>"  — ship next feature
+  /health                  — full diagnostic
+```
+
+Rules:
+- Never propose changes or solutions.
+- If any data is unavailable, print "N/A" — do not guess.
+- Keep output under 40 lines.
diff --git a/doctor.sh b/doctor.sh
index 447a3b7..3d98f9b 100644
--- a/doctor.sh
+++ b/doctor.sh
@@ -29,6 +29,9 @@ echo ""
 # 1. Core symlinks
 # ────────────────────────────────────────────────────────────
 echo "── Symlinks ──"
+# Expected: CLAUDE.md, settings.json, agents, skills, templates, hooks/session-start.sh
+_EXPECTED_LINKS=7
+_LINK_PASS=0
 
 check_symlink() {
   local name="$1"
@@ -40,12 +43,13 @@ check_symlink() {
   fi
 
   if [ -L "$target" ]; then
+    # readlink -f is not available on macOS BSD — use -f with fallback
     local real
-    real=$(readlink -f "$target" 2>/dev/null || readlink "$target")
+    real=$(readlink -f "$target" 2>/dev/null) || real=$(readlink "$target")
     if [ ! -e "$real" ]; then
       fail "~/.claude/$name → $real — BROKEN SYMLINK"
     else
-      pass "~/.claude/$name"
+      pass "~/.claude/$name"; _LINK_PASS=$((_LINK_PASS + 1))
     fi
   else
     warn "~/.claude/$name exists but is NOT a symlink (expected symlink to repo)"
@@ -56,7 +60,11 @@ check_symlink "CLAUDE.md"
 check_symlink "settings.json"
 check_symlink "agents"
 check_symlink "skills"
+check_symlink "templates"
+check_symlink "lib"
 check_symlink "hooks/session-start.sh"
+info "Symlinks: ${_LINK_PASS}/${_EXPECTED_LINKS} OK"
+unset _EXPECTED_LINKS _LINK_PASS
 
 echo ""
 
@@ -65,16 +73,27 @@ echo ""
 # ────────────────────────────────────────────────────────────
 echo "── GStack submodule ──"
 
-if [ -d "$REPO/skills-external/gstack" ] || [ -f "$REPO/skills-external/gstack/.git" ]; then
-  pass "Submodule present at skills-external/gstack"
+GSTACK_DIR="$REPO/skills-external/gstack"
+if [ -f "$GSTACK_DIR/.git" ] || [ -d "$GSTACK_DIR/.git" ]; then
+  pass "Submodule initialized at skills-external/gstack"
+  warn "GStack tracks branch = main (no commit hash pin). Review upstream before updating."
+elif [ -d "$GSTACK_DIR" ]; then
+  warn "skills-external/gstack exists but submodule not initialized — run: git submodule update --init"
 else
-  warn "Submodule not initialized — run: git submodule update --init"
+  warn "GStack submodule missing — run: git submodule update --init"
 fi
 
 if [ -L "$HOME/.claude/skills/gstack" ]; then
   real=$(readlink -f "$HOME/.claude/skills/gstack" 2>/dev/null || readlink "$HOME/.claude/skills/gstack")
   if [ -d "$real" ]; then
     pass "Symlink OK → $real"
+    # Check for skills/ subdirectory (referenced by plugin-advisor PHASE 1)
+    gstack_skills_count=$(ls "$HOME/.claude/skills/gstack/skills/" 2>/dev/null | wc -l | tr -d ' ')
+    if [ "${gstack_skills_count:-0}" -gt 0 ]; then
+      pass "GStack: ${gstack_skills_count} skills available"
+    else
+      warn "GStack symlink OK but no skills/ subdirectory found — may need: cd skills-external/gstack && ./setup"
+    fi
   else
     fail "Symlink broken → $real"
   fi
@@ -149,6 +168,18 @@ else
   info "Context7 MCP not configured (optional — needed for fast-evolving libs)"
 fi
 
+if detect_gsd; then
+  pass "GSD v2 installed ($(gsd --version 2>/dev/null | head -1 || echo 'gsd'))"
+else
+  info "GSD v2 not installed (optional — run: npm install -g gsd-pi)"
+fi
+
+if detect_ruflo; then
+  pass "Ruflo MCP configured"
+else
+  info "Ruflo MCP not configured (optional — enterprise multi-agent orchestration)"
+fi
+
 echo ""
 
 # ────────────────────────────────────────────────────────────
@@ -170,7 +201,17 @@ with open('$SETTINGS') as f:
     d = json.load(f)
 print(len(d.get('permissions',{}).get('deny',[])))
 " 2>/dev/null || echo "?")
-  pass "Deny rules: $DENY_COUNT"
+
+  if [ "$DENY_COUNT" = "?" ]; then
+    warn "Could not parse deny count (python3 unavailable or JSON parse error)"
+  else
+    EXPECTED_DENY=100
+    if [ "$DENY_COUNT" -eq "$EXPECTED_DENY" ] 2>/dev/null; then
+      pass "Deny rules: $DENY_COUNT"
+    else
+      warn "Deny rules: $DENY_COUNT (expected $EXPECTED_DENY) — settings may have been manually modified"
+    fi
+  fi
 else
   fail "~/.claude/settings.json not found"
 fi
@@ -181,29 +222,66 @@ echo ""
 # 6. Token budget estimate
 # ────────────────────────────────────────────────────────────
 echo "── Token budget estimate ──"
+# Reference: Claude Code Pro plan ~11k tokens/5h session (session budget, not context window).
+# Seuils: WARNING >15%, CRITICAL >30% of session budget.
 
-TOTAL_CHARS=0
+CLAUDE_MD_CHARS=$(wc -c < "$REPO/CLAUDE.md" 2>/dev/null || echo 0)
+CLAUDE_MD_TOKENS=$((CLAUDE_MD_CHARS / 4))
 
-# Skill descriptions
+# Skill descriptions only (frontmatter description field — loaded passively at startup)
+SKILL_DESC_CHARS=0
 for f in "$HOME/.claude/skills/"*/SKILL.md; do
   [ -f "$f" ] || continue
-  desc=$(sed -n 's/^description: //p' "$f" 2>/dev/null || true)
-  TOTAL_CHARS=$((TOTAL_CHARS + ${#desc}))
+  desc=$(grep "^description:" "$f" 2>/dev/null | head -1 | sed 's/^description: *//' )
+  SKILL_DESC_CHARS=$((SKILL_DESC_CHARS + ${#desc}))
 done
+SKILL_DESC_TOKENS=$((SKILL_DESC_CHARS / 4))
+SKILL_COUNT=$(find "$HOME/.claude/skills/" -maxdepth 2 -name "SKILL.md" 2>/dev/null | wc -l | tr -d ' ')
 
-# Agent descriptions
-for f in "$HOME/.claude/agents/"*.md; do
-  [ -f "$f" ] || continue
-  desc=$(sed -n '/^---$/,/^---$/{ s/^description: //p }' "$f" 2>/dev/null || true)
-  TOTAL_CHARS=$((TOTAL_CHARS + ${#desc}))
-done
+# Plugin passive cost estimates (tokens)
+PLUGIN_TOKENS=0
+if detect_superpowers 2>/dev/null; then PLUGIN_TOKENS=$((PLUGIN_TOKENS + 800)); fi
+if detect_gstack      2>/dev/null; then PLUGIN_TOKENS=$((PLUGIN_TOKENS + 2750)); fi
+if detect_frontend_design 2>/dev/null; then PLUGIN_TOKENS=$((PLUGIN_TOKENS + 200)); fi
+if detect_uiux_pro_max    2>/dev/null; then PLUGIN_TOKENS=$((PLUGIN_TOKENS + 400)); fi
+if detect_context7    2>/dev/null; then PLUGIN_TOKENS=$((PLUGIN_TOKENS + 200)); fi
+if detect_ruflo       2>/dev/null; then PLUGIN_TOKENS=$((PLUGIN_TOKENS + 1000)); fi
 
-if [ "$TOTAL_CHARS" -gt 6000 ]; then
-  warn "Custom descriptions: ~${TOTAL_CHARS} chars (budget ~8000) — risk of truncation"
-elif [ "$TOTAL_CHARS" -gt 4000 ]; then
-  info "Custom descriptions: ~${TOTAL_CHARS} chars (within budget, moderate margin)"
+TOTAL_TOKENS=$((CLAUDE_MD_TOKENS + SKILL_DESC_TOKENS + PLUGIN_TOKENS))
+SESSION_BUDGET=11000
+PCT=$((TOTAL_TOKENS * 100 / SESSION_BUDGET))
+
+echo ""
+echo "  CLAUDE.md:           ~${CLAUDE_MD_TOKENS}t"
+echo "  Skill descriptions:  ~${SKILL_DESC_TOKENS}t  (${SKILL_COUNT} skills)"
+echo "  Plugin passive cost: ~${PLUGIN_TOKENS}t  (active plugins)"
+echo "  ─────────────────────────────────────────"
+info "  Total:               ~${TOTAL_TOKENS}t"
+info "  Session budget (Pro): ${SESSION_BUDGET}t"
+info "  Usage:               ~${PCT}%"
+echo ""
+
+if [ "$PCT" -gt 30 ]; then
+  warn "CRITICAL: ${PCT}% of session budget — /plugin-check to disable unused plugins"
+elif [ "$PCT" -gt 15 ]; then
+  warn "WARNING: ${PCT}% of session budget — consider disabling unused toggle plugins"
 else
-  pass "Custom descriptions: ~${TOTAL_CHARS} chars (comfortable)"
+  pass "Budget: ${PCT}% (comfortable)"
+fi
+
+# Per-file breakdown (skill bodies — loaded on demand, shown for awareness)
+if [ "$TOTAL_TOKENS" -gt 2000 ]; then
+  info "Skill/agent bodies (loaded on demand, >200t each):"
+  for f in "$HOME/.claude/skills/"*/SKILL.md "$HOME/.claude/agents/"*.md; do
+    [ -f "$f" ] || continue
+    size=$(wc -c < "$f" 2>/dev/null || echo 0)
+    tokens=$((size / 4))
+    if [ "$tokens" -gt 200 ]; then
+      label=$(basename "$(dirname "$f")" 2>/dev/null)
+      [ "$label" = "." ] && label=$(basename "$f")
+      info "  ~${tokens}t  ${label}"
+    fi
+  done
 fi
 
 echo ""
@@ -228,11 +306,45 @@ else
   warn "Skills missing disable-model-invocation: ${MISSING_DMI[*]}"
 fi
 
-# Check CRLF
+# Check expected skills are present
+EXPECTED_SKILLS=(
+  "analyze" "health" "init-project" "onboard" "plugin-check"
+  "readme" "refactor" "ship-feature" "status"
+)
+MISSING_SKILLS=()
+for skill in "${EXPECTED_SKILLS[@]}"; do
+  if [ ! -f "$HOME/.claude/skills/${skill}/SKILL.md" ]; then
+    MISSING_SKILLS+=("${skill}/")
+  fi
+done
+if [ ${#MISSING_SKILLS[@]} -eq 0 ]; then
+  pass "All ${#EXPECTED_SKILLS[@]} expected skills present (analyze, health, init-project, onboard, plugin-check, readme, refactor, ship-feature, status)"
+else
+  warn "Missing skills: ${MISSING_SKILLS[*]} — run: bash link.sh"
+fi
+
+# Check expected agents are present
+EXPECTED_AGENTS=(
+  "analyzer" "interviewer" "plugin-advisor" "readme-updater"
+  "refactorer" "scaffolder" "onboarder" "status-reporter"
+)
+MISSING_AGENTS=()
+for agent in "${EXPECTED_AGENTS[@]}"; do
+  if [ ! -f "$HOME/.claude/agents/${agent}.md" ]; then
+    MISSING_AGENTS+=("${agent}.md")
+  fi
+done
+if [ ${#MISSING_AGENTS[@]} -eq 0 ]; then
+  pass "All 8 agents present (analyzer, interviewer, plugin-advisor, readme-updater, refactorer, scaffolder, onboarder, status-reporter)"
+else
+  warn "Missing agents: ${MISSING_AGENTS[*]} — run: bash link.sh"
+fi
+
+# Check CRLF — portable: grep -P not available on macOS BSD grep
 CRLF_FILES=()
 for f in "$REPO"/*.md "$REPO"/agents/*.md "$REPO"/skills/*/SKILL.md; do
   [ -f "$f" ] || continue
-  if grep -qP '\r' "$f" 2>/dev/null; then
+  if grep -c $'\r' "$f" 2>/dev/null | grep -q "^[^0]"; then
     CRLF_FILES+=("$(basename "$f")")
   fi
 done
diff --git a/hooks/session-start.sh b/hooks/session-start.sh
index 4162f7c..d498ae9 100644
--- a/hooks/session-start.sh
+++ b/hooks/session-start.sh
@@ -38,12 +38,8 @@ if [ -f "$_lib" ]; then
   # shellcheck source=../lib/detect-plugins.sh
   source "$_lib"
 else
-  # Fallback: inline detection if lib is missing
-  detect_gstack()          { [ -d "$HOME/.claude/skills/gstack" ]; }
-  detect_gsd()             { ls "$HOME/.claude/skills/" 2>/dev/null | grep -qi "gsd"; }
-  detect_uiux_pro_max()    { ls "$HOME/.claude/plugins/cache/" 2>/dev/null | grep -qi "ui-ux-pro-max"; }
-  detect_frontend_design() { ls "$HOME/.claude/plugins/cache/" 2>/dev/null | grep -qi "frontend-design"; }
-  detect_context7()        { claude mcp list 2>/dev/null | grep -q "context7"; }
+  echo "⚠️  lib/detect-plugins.sh not found — config broken, run: bash link.sh"
+  exit 0
 fi
 unset _lib
 
@@ -52,7 +48,7 @@ unset _lib
 TOGGLE_ACTIVE=()
 TOGGLE_INACTIVE=()
 
-for plugin in gstack gsd uiux_pro_max frontend_design context7; do
+for plugin in gstack uiux_pro_max frontend_design context7 ruflo; do
   # Map function name to display name
   case "$plugin" in
     uiux_pro_max)    display="ui-ux-pro-max" ;;
@@ -71,6 +67,13 @@ done
 ACTIVE_STR="${TOGGLE_ACTIVE[*]:-none}"
 INACTIVE_STR="${TOGGLE_INACTIVE[*]:-none}"
 
+# GSD v2 — standalone CLI (not a Claude Code plugin — shown separately)
+if detect_gsd 2>/dev/null; then
+  GSD_STATUS="gsd v2 ✓"
+else
+  GSD_STATUS="gsd v2 ✗ (npm install -g gsd-pi)"
+fi
+
 # Version detection: follow CLAUDE.md symlink back to repo, then read version.txt
 _claude_real="$(readlink "$HOME/.claude/CLAUDE.md" 2>/dev/null || true)"
 if [ -n "$_claude_real" ]; then
@@ -81,11 +84,63 @@ else
 fi
 unset _claude_real _repo_dir
 
+# Quick passive token cost estimate (Pro session budget = ~11k tokens)
+_passive_t=0
+detect_superpowers 2>/dev/null && _passive_t=$((_passive_t + 800))
+detect_gstack      2>/dev/null && _passive_t=$((_passive_t + 2750))
+detect_frontend_design 2>/dev/null && _passive_t=$((_passive_t + 200))
+detect_uiux_pro_max    2>/dev/null && _passive_t=$((_passive_t + 400))
+detect_context7    2>/dev/null && _passive_t=$((_passive_t + 200))
+detect_ruflo       2>/dev/null && _passive_t=$((_passive_t + 1000))
+_budget_pct=$((_passive_t * 100 / 11000))
+if [ "$_budget_pct" -gt 50 ]; then
+  TOKEN_WARN="⚠️  ~${_passive_t}t passif (${_budget_pct}% budget)"
+elif [ "$_budget_pct" -gt 25 ]; then
+  TOKEN_WARN="~${_passive_t}t passif (${_budget_pct}% budget)"
+else
+  TOKEN_WARN=""
+fi
+unset _passive_t _budget_pct
+
 echo ""
-echo "┌─ Toggle plugins ──────────────────────────────────┐"
-printf "│  🟢 ON  : %-40s│\n" "$ACTIVE_STR"
-printf "│  ⚫ OFF : %-40s│\n" "$INACTIVE_STR"
+echo "┌─ Claude Code config ──────────────────────────────────┐"
+printf "│  ✅ ON  : %-40s│\n" "security-guidance rtk superpowers"
+# Plugin display — all plugins shown, split across 2 lines if >4
+_active_count=${#TOGGLE_ACTIVE[@]}
+_inactive_count=${#TOGGLE_INACTIVE[@]}
+
+if [ "$_active_count" -eq 0 ]; then
+  printf "│  🟢 ON  : %-40s│\n" "none"
+elif [ "$_active_count" -le 4 ]; then
+  printf "│  🟢 ON  : %-40s│\n" "$ACTIVE_STR"
+else
+  # Split: first 4 on line 1, rest on continuation line
+  _line1="${TOGGLE_ACTIVE[0]} ${TOGGLE_ACTIVE[1]} ${TOGGLE_ACTIVE[2]} ${TOGGLE_ACTIVE[3]}"
+  _rest=("${TOGGLE_ACTIVE[@]:4}")
+  _line2="${_rest[*]}"
+  printf "│  🟢 ON  : %-40s│\n" "$_line1"
+  printf "│             %-40s│\n" "$_line2"
+  unset _line1 _line2 _rest
+fi
+
+if [ "$_inactive_count" -eq 0 ]; then
+  printf "│  ⚫ OFF : %-40s│\n" "none"
+elif [ "$_inactive_count" -le 4 ]; then
+  printf "│  ⚫ OFF : %-40s│\n" "$INACTIVE_STR"
+else
+  _line1="${TOGGLE_INACTIVE[0]} ${TOGGLE_INACTIVE[1]} ${TOGGLE_INACTIVE[2]} ${TOGGLE_INACTIVE[3]}"
+  _rest=("${TOGGLE_INACTIVE[@]:4}")
+  _line2="${_rest[*]}"
+  printf "│  ⚫ OFF : %-40s│\n" "$_line1"
+  printf "│             %-40s│\n" "$_line2"
+  unset _line1 _line2 _rest
+fi
+unset _active_count _inactive_count
+printf "│  🖥️  CLI : %-40s│\n" "$GSD_STATUS"
+[ -n "$TOKEN_WARN" ] && printf "│  💰 %-44s│\n" "${TOKEN_WARN:0:44}"
+printf "│  📦 v%-45s│\n" "$CONFIG_VERSION"
 echo "│  💡 /plugin-check  before starting a new project  │"
 echo "│  🩺 /health  to run full diagnostic               │"
 echo "└───────────────────────────────────────────────────┘"
 echo ""
+unset TOKEN_WARN
diff --git a/install-plugins.sh b/install-plugins.sh
index abec3b9..41352c0 100644
--- a/install-plugins.sh
+++ b/install-plugins.sh
@@ -18,7 +18,12 @@ REPO="$(cd "$(dirname "$0")" && pwd)"
 
 # Log to file for post-mortem debugging (terminal output unchanged)
 LOG_FILE="$REPO/install-$(date +%Y%m%d-%H%M%S).log"
-exec > >(tee -a "$LOG_FILE") 2>&1
+if touch "$LOG_FILE" 2>/dev/null; then
+  exec > >(tee -a "$LOG_FILE") 2>&1
+  info "Logging to $LOG_FILE"
+else
+  warn "Cannot write log to $REPO — continuing without log file"
+fi
 
 # Load shared detection library
 # shellcheck source=lib/detect-plugins.sh
@@ -179,7 +184,15 @@ fi
 
 if [ -d "$GSTACK_DIR" ]; then
   info "Running GStack setup..."
-  cd "$GSTACK_DIR" && ./setup && cd - > /dev/null
+  if [ -x "$GSTACK_DIR/setup" ]; then
+    if (cd "$GSTACK_DIR" && ./setup) 2>/dev/null; then
+      : # setup succeeded
+    else
+      warn "GStack ./setup failed — submodule present but setup incomplete"
+    fi
+  else
+    warn "GStack ./setup not found or not executable — skipping"
+  fi
   # Symlinks are handled by link.sh — verify it was run
   if [ -L "$HOME/.claude/skills/gstack" ]; then
     ok "GStack ready (submodule initialized, symlink OK)"
@@ -209,34 +222,77 @@ else
     cargo install --git https://github.com/rtk-ai/rtk
   fi
 fi
-info "Configuring RTK PreToolUse hook (global)..."
-rtk init -g --auto-patch
-ok "RTK configured"
-echo ""
-
-# ============================================================
-# STEP 4 — GSD
-# ============================================================
-echo "── Step 4: GSD — get-shit-done ─────────────────────────────"
-echo ""
-info "Installing GSD globally..."
-GSD_VER=$(pinned_version "gsd")
-if [ "$GSD_VER" != "latest" ]; then
-  info "Version $GSD_VER (pinned in plugins.lock.json)"
-  npx "get-shit-done-cc@$GSD_VER" --claude --global --auto
+# Only init if not already configured (avoids overwriting custom RTK config)
+if ! grep -q "rtk" "$HOME/.claude/settings.json" 2>/dev/null; then
+  info "Configuring RTK PreToolUse hook (global)..."
+  rtk init -g --auto-patch
+  ok "RTK configured"
 else
-  info "Version: latest (consider pinning in plugins.lock.json)"
-  npx get-shit-done-cc --claude --global --auto
+  ok "RTK hook already present in settings.json — skipping init"
 fi
-ok "GSD installed"
 echo ""
 
 # ============================================================
-# STEP 5 — MARKETPLACE PLUGINS (user scope, explicit)
+# STEP 4 — GSD v2
+# ============================================================
+# GSD v2 (gsd-pi) is a standalone CLI built on the Pi SDK.
+# It is NOT a Claude Code plugin — it runs as an external process ('gsd' command).
+# Usage: run 'gsd' in your terminal from a project directory.
+# Slash commands (/gsd auto, /gsd status, etc.) are internal to a GSD session.
+echo "── Step 4: GSD v2 — gsd-pi ─────────────────────────────────"
+echo ""
+if command -v gsd &>/dev/null; then
+  ok "gsd already installed ($(gsd --version 2>/dev/null | head -1 || echo 'installed'))"
+else
+  GSD_VER=$(pinned_version "gsd")
+  if [ "$GSD_VER" != "latest" ]; then
+    info "Installing gsd-pi@${GSD_VER} (pinned in plugins.lock.json)..."
+    npm install -g "gsd-pi@${GSD_VER}"
+  else
+    info "Installing gsd-pi@latest (consider pinning in plugins.lock.json)..."
+    npm install -g gsd-pi
+  fi
+  command -v gsd &>/dev/null && ok "GSD v2 installed ($(gsd --version 2>/dev/null | head -1))" \
+    || err "GSD v2 install failed — check npm output above"
+fi
+echo ""
+
+# ============================================================
+# STEP 5 — RUFLO MCP (manual — requires npm install + MCP config)
+# ============================================================
+# Ruflo is an enterprise multi-agent orchestration MCP server (formerly claude-flow).
+# 310+ MCP tools, 100+ agent types, WASM kernel, self-learning architecture.
+# Use only for projects requiring complex multi-agent coordination.
+# Default install ~340MB. Minimal: npm install -g ruflo@latest --omit=optional (~15s)
+echo "── Step 5: Ruflo MCP ────────────────────────────────────────"
+echo ""
+if detect_ruflo; then
+  ok "Ruflo MCP already configured"
+else
+  warn "Ruflo requires manual setup — cannot auto-install (enterprise tool)"
+  echo ""
+  echo "  Steps:"
+  echo "  1. Install the package:"
+  echo "     npm install -g ruflo@latest             # full (~340MB)"
+  echo "     npm install -g ruflo@latest --omit=optional  # minimal"
+  echo ""
+  echo "  2. Register as MCP server in Claude Code:"
+  echo "     claude mcp add --scope user ruflo -- npx ruflo mcp start"
+  echo ""
+  echo "  3. Verify:"
+  echo "     claude mcp list | grep ruflo"
+  echo ""
+  echo "  Or use the automated installer:"
+  echo "     curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash -s -- --full"
+  echo ""
+fi
+
+# ============================================================
+# STEP 6 — MARKETPLACE PLUGINS (user scope, explicit)
 # ============================================================
 # All claude plugin install commands use --scope user to ensure
 # they install to ~/.claude/plugins/ regardless of working directory.
-echo "── Step 5: Marketplace plugins (scope: user) ────────────────"
+echo "── Step 6: Marketplace plugins (scope: user) ────────────────"
 echo ""
 
 install_plugin() {
@@ -273,7 +329,7 @@ echo ""
 # ============================================================
 # STEP 6 — CONTEXT7 MCP (manual — requires API key)
 # ============================================================
-echo "── Step 6: Context7 MCP ─────────────────────────────────────"
+echo "── Step 7: Context7 MCP ─────────────────────────────────────"
 echo ""
 if claude mcp list 2>/dev/null | grep -q "context7"; then
   ok "Context7 MCP already configured"
@@ -281,7 +337,7 @@ else
   warn "Context7 requires a free API key — cannot auto-install"
   echo ""
   echo "  Steps:"
-  echo "  1. Get a free key at https://context7.com"
+  echo "  1. Get a free key at https://upstash.com"
   echo "  2. Run:"
   echo "     claude mcp add --scope user context7 -- \\"
   echo "       npx -y @upstash/context7-mcp --api-key YOUR_KEY"
@@ -296,23 +352,23 @@ echo "╔═══════════════════════
 echo "║                     Install Summary                     ║"
 echo "╚══════════════════════════════════════════════════════════╝"
 echo ""
-echo "  ALWAYS ON (installed at user scope, ~10 tokens/session each):"
+echo "  ALWAYS ON (installed at user scope):"
 echo "    ✅ security-guidance   — PreToolUse security hook (0 tokens)"
 echo "    ✅ rtk                 — token compression hook (0 tokens)"
 echo "    ✅ superpowers         — brainstorm/plan/implement/debug workflow"
-echo "    ✅ skill-creator       — create skills from conversation"
-echo "    ✅ pr-review-toolkit   — /pr-review-toolkit:review-pr"
 echo ""
 echo "  TOGGLE (installed but start OFF — /plugin-check recommends when needed):"
 echo "    🔄 gstack              — ~/.claude/skills/gstack/ (→ submodule)"
-echo "    🔄 gsd                 — ~/.claude/skills/ (npx)"
-echo "    🔄 frontend-design     — user scope"
-echo "    🔄 ui-ux-pro-max       — user scope"
-echo "    🔄 context7 MCP        — see Step 6 above"
+echo "    🔄 gsd v2              — standalone CLI 'gsd' (gsd-pi, not a Claude Code plugin)"
+echo "    🔄 skill-creator       — create skills from conversation (~100 tokens)"
+echo "    🔄 pr-review-toolkit   — /pr-review-toolkit:review-pr (~300 tokens)"
+echo "    🔄 frontend-design     — user scope (~200 tokens)"
+echo "    🔄 ui-ux-pro-max       — user scope (~400 tokens)"
+echo "    🔄 context7 MCP        — see Step 7 above (~200 tokens)"
+echo "    🔄 ruflo MCP           — see Step 5 above (~500-1500 tokens, enterprise only)"
 echo ""
 echo "  All plugins installed at: user scope (~/.claude/plugins/)"
 echo "  GStack at: ~/.claude/skills/gstack/ (symlink → submodule)"
 echo ""
-echo "  → Restart Claude Code"
-echo "  → Run /reload-plugins"
+echo "  → Restart Claude Code — plugins load automatically"
 echo ""
diff --git a/lib/detect-plugins.sh b/lib/detect-plugins.sh
index 5abf35b..120fbb7 100644
--- a/lib/detect-plugins.sh
+++ b/lib/detect-plugins.sh
@@ -24,20 +24,6 @@ detect_superpowers() {
   return 1
 }
 
-detect_security_guidance() {
-  local cache_dir="$HOME/.claude/plugins/cache"
-  [ -d "$cache_dir" ] && ls "$cache_dir" 2>/dev/null | grep -qi "security-guidance"
-}
-
-detect_skill_creator() {
-  local cache_dir="$HOME/.claude/plugins/cache"
-  [ -d "$cache_dir" ] && ls "$cache_dir" 2>/dev/null | grep -qi "skill-creator"
-}
-
-detect_pr_review_toolkit() {
-  local cache_dir="$HOME/.claude/plugins/cache"
-  [ -d "$cache_dir" ] && ls "$cache_dir" 2>/dev/null | grep -qi "pr-review-toolkit"
-}
 
 # --- Toggle plugins ---
 
@@ -46,7 +32,9 @@ detect_gstack() {
 }
 
 detect_gsd() {
-  ls "$HOME/.claude/skills/" 2>/dev/null | grep -qi "gsd"
+  # GSD v2 (gsd-pi) is a standalone CLI, not a Claude Code plugin.
+  # Detection: check for 'gsd' binary in PATH.
+  command -v gsd &>/dev/null
 }
 
 detect_frontend_design() {
@@ -60,5 +48,27 @@ detect_uiux_pro_max() {
 }
 
 detect_context7() {
-  claude mcp list 2>/dev/null | grep -q "context7"
+  # Fast check: read ~/.claude.json (MCP config) without spawning the claude CLI
+  local cfg="$HOME/.claude.json"
+  if [ -f "$cfg" ]; then
+    grep -q "context7" "$cfg" 2>/dev/null && return 0
+  fi
+  # Fallback: ~/.mcp.json (project-scoped MCP config at user level)
+  local mcp="$HOME/.mcp.json"
+  if [ -f "$mcp" ]; then
+    grep -q "context7" "$mcp" 2>/dev/null && return 0
+  fi
+  return 1
+}
+
+detect_ruflo() {
+  # 1. Fast: check npm global binary
+  command -v ruflo &>/dev/null && return 0
+  # 2. Fast: check MCP config files (ruflo or ruvnet/claude-flow variants)
+  for _cfg in "$HOME/.claude.json" "$HOME/.mcp.json"; do
+    [ -f "$_cfg" ] && grep -qi "ruflo\|ruvnet\|claude-flow" "$_cfg" 2>/dev/null && return 0
+  done
+  # 3. Slow fallback: claude mcp list (only if fast checks fail, spawns subprocess)
+  command -v claude &>/dev/null && claude mcp list 2>/dev/null | grep -qi "ruflo" && return 0
+  return 1
 }
diff --git a/link.sh b/link.sh
index 1b9b38e..34c9396 100644
--- a/link.sh
+++ b/link.sh
@@ -1,47 +1,57 @@
 #!/usr/bin/env bash
 # Symlink this repo into ~/.claude/
-# Run once after cloning on a new machine.
-
 set -euo pipefail
 
 REPO="$(cd "$(dirname "$0")" && pwd)"
 CLAUDE="$HOME/.claude"
+CHANGED=0
 
 mkdir -p "$CLAUDE"
 
-# Core config files (plain files — ln -sf handles these correctly)
-ln -sf "$REPO/CLAUDE.md"      "$CLAUDE/CLAUDE.md"
-ln -sf "$REPO/settings.json"  "$CLAUDE/settings.json"
+link_file() {
+  local src="$1" dst="$2"
+  if [ -L "$dst" ] && [ "$(readlink "$dst")" = "$src" ]; then
+    return  # already correct
+  fi
+  ln -sf "$src" "$dst"
+  CHANGED=$((CHANGED + 1))
+}
 
-# Agents and skills — must handle the case where target exists
-# as a real directory (ln -sf would create a link INSIDE the dir
-# instead of replacing it)
-for item in agents skills lib; do
+link_file "$REPO/CLAUDE.md"     "$CLAUDE/CLAUDE.md"
+link_file "$REPO/settings.json" "$CLAUDE/settings.json"
+
+for item in agents skills lib templates; do
   target="$CLAUDE/$item"
   if [ -L "$target" ]; then
-    # Stale symlink from a previous run — remove before recreating
+    if [ "$(readlink "$target")" = "$REPO/$item" ]; then
+      continue  # already correct
+    fi
     rm -f "$target"
   elif [ -d "$target" ]; then
-    echo "⚠️  ~/.claude/$item is a real directory (not a symlink)."
-    echo "   Rename or remove it, then re-run link.sh."
-    echo "   Skipping $item to avoid data loss."
+    echo "⚠️  ~/.claude/$item is a real directory. Rename or remove it, then re-run link.sh."
     continue
   fi
   ln -sf "$REPO/$item" "$target"
+  CHANGED=$((CHANGED + 1))
 done
 
-# Hooks
 mkdir -p "$CLAUDE/hooks"
-ln -sf "$REPO/hooks/session-start.sh" "$CLAUDE/hooks/session-start.sh"
+link_file "$REPO/hooks/session-start.sh" "$CLAUDE/hooks/session-start.sh"
 
-# GStack (submodule) — symlink into ~/.claude/skills/ (which points to repo/skills/)
-# The submodule must be initialized first (done by install-plugins.sh)
 if [ -d "$REPO/skills-external/gstack" ]; then
-  ln -sf "$REPO/skills-external/gstack" "$CLAUDE/skills/gstack"
-  echo "✅ GStack symlinked from submodule"
+  if [ -L "$CLAUDE/skills/gstack" ] && [ "$(readlink "$CLAUDE/skills/gstack")" = "$REPO/skills-external/gstack" ]; then
+    : # already correct
+  else
+    ln -sf "$REPO/skills-external/gstack" "$CLAUDE/skills/gstack"
+    CHANGED=$((CHANGED + 1))
+  fi
 else
   echo "⚠️  GStack submodule not found — run: git submodule update --init"
 fi
 
-echo "✅ Symlinks created in ~/.claude/"
+if [ "$CHANGED" -eq 0 ]; then
+  echo "✅ All symlinks already up to date."
+else
+  echo "✅ $CHANGED symlink(s) updated in ~/.claude/"
+fi
 echo "   Next: bash install-plugins.sh"
diff --git a/plugins.lock.json b/plugins.lock.json
index 2444a29..4f7f24c 100644
--- a/plugins.lock.json
+++ b/plugins.lock.json
@@ -2,23 +2,22 @@
   "_readme": "Pinned versions for reproducible installs. Update versions deliberately, then run install-plugins.sh.",
   "rtk": {
     "source": "https://github.com/rtk-ai/rtk",
-    "install_cmd": "cargo install --git https://github.com/rtk-ai/rtk --tag {version}",
     "version": "v0.34.3",
     "note": "Check latest at https://github.com/rtk-ai/rtk/releases before updating"
   },
   "gsd": {
-    "source": "npm:get-shit-done-cc",
-    "install_cmd": "npx get-shit-done-cc@{version} --claude --global --auto",
-    "version": "1.30.0",
-    "note": "Check latest at https://www.npmjs.com/package/get-shit-done-cc before updating"
+    "source": "npm:gsd-pi",
+    "version": "2.64.0",
+    "note": "Check latest at https://www.npmjs.com/package/gsd-pi before updating. GSD v2 is a standalone CLI (Pi SDK), not a Claude Code plugin. Run 'gsd' in terminal, not '/gsd' in Claude Code."
   },
   "gstack": {
     "source": "https://github.com/garrytan/gstack.git",
     "managed_by": "git submodule",
     "note": "Version controlled by submodule pointer in .gitmodules. Update: git submodule update --remote"
   },
-  "node": {
-    "minimum": "18",
-    "recommended": "22"
+  "ruflo": {
+    "source": "npm:ruflo",
+    "version": "3.5.58",
+    "note": "Enterprise multi-agent MCP server (formerly claude-flow). Requires manual MCP config after install. Check latest at https://www.npmjs.com/package/ruflo before updating."
   }
 }
diff --git a/settings.json b/settings.json
index aad49b8..c7b03e9 100644
--- a/settings.json
+++ b/settings.json
@@ -1,9 +1,9 @@
 {
-  "_readme": "Global user settings — place at ~/.claude/settings.json. Applies to ALL projects. Never commit this file.",
   "cleanupPeriodDays": 30,
   "permissions": {
     "defaultMode": "default",
     "disableBypassPermissionsMode": "disable",
+    "disableAutoMode": "disable",
     "deny": [
       "Bash(rm -rf *)",
       "Bash(rm -rf /*)",
@@ -81,7 +81,30 @@
       "Bash(more .env)",
       "Bash(more .env.*)",
       "Bash(grep * .env)",
-      "Bash(grep * .env.*)"
+      "Bash(grep * .env.*)",
+      "Bash(env)",
+      "Bash(printenv)",
+      "Bash(printenv *)",
+      "Bash(export *)",
+      "Bash(cp .env*)",
+      "Bash(cp **/.env*)",
+      "Bash(cp **/secrets/*)",
+      "Bash(mv .env*)",
+      "Bash(mv **/.env*)",
+      "Bash(mv **/secrets/*)",
+      "Bash(git add .env*)",
+      "Bash(git add **/.env*)",
+      "Bash(cp **/id_rsa*)",
+      "Bash(cp **/id_ed25519*)",
+      "Bash(cp **/.ssh/*)",
+      "Bash(source /dev/stdin)",
+      "Bash(mkfifo *)",
+      "Bash(python3 -c *)",
+      "Bash(node -e *)",
+      "Bash(xargs * .env*)",
+      "Bash(tar * .env*)",
+      "Bash(zip * .env*)",
+      "Bash(base64 .env*)"
     ],
     "ask": [
       "Bash(git push *)",
@@ -98,8 +121,10 @@
       "WebSearch",
       "WebFetch",
       "Bash(xargs *)",
-      "Bash(sed -i *)",
-      "Bash(sed -i'' *)"
+      "Bash(sed *)",
+      "Bash(git stash pop*)",
+      "Bash(git stash drop*)",
+      "Bash(git stash clear)"
     ],
     "allow": [
       "Bash(git status)",
@@ -112,7 +137,10 @@
       "Bash(git commit*)",
       "Bash(git checkout *)",
       "Bash(git switch *)",
-      "Bash(git stash*)",
+      "Bash(git stash)",
+      "Bash(git stash push*)",
+      "Bash(git stash list*)",
+      "Bash(git stash show*)",
       "Bash(git tag*)",
       "Bash(git show*)",
       "Bash(ls *)",
@@ -129,8 +157,6 @@
       "Bash(pwd)",
       "Bash(which *)",
       "Bash(type *)",
-      "Bash(env)",
-      "Bash(printenv *)",
       "Bash(whoami)",
       "Bash(uname *)",
       "Bash(mkdir -p *)",
@@ -139,7 +165,6 @@
       "Bash(mv *)",
       "Bash(jq *)",
       "Bash(yq *)",
-      "Bash(sed *)",
       "Bash(awk *)",
       "Bash(sort *)",
       "Bash(uniq *)",
diff --git a/skills/analyze/SKILL.md b/skills/analyze/SKILL.md
index e1181d5..4b89734 100644
--- a/skills/analyze/SKILL.md
+++ b/skills/analyze/SKILL.md
@@ -1,13 +1,13 @@
 ---
 name: analyze
-description: Deep factual code analysis — read-only, no solutions proposed
-argument-hint: <code, file, or area to analyze>
+description: Deep factual code analysis (read-only) or DEBUG mode (pass error/stack trace) — no solutions proposed, no file modifications
+argument-hint: <file/area to analyze — OR paste error/stack trace for DEBUG mode>
 disable-model-invocation: true
 allowed-tools: Read, Grep, Glob, Bash
 ---
 
 Load and follow strictly:
-- .claude/agents/analyzer.md
+- $HOME/.claude/agents/analyzer.md
 
 Execute the ANALYZER agent on the following target:
 
diff --git a/skills/health/SKILL.md b/skills/health/SKILL.md
index 141224d..2fcd141 100644
--- a/skills/health/SKILL.md
+++ b/skills/health/SKILL.md
@@ -6,13 +6,18 @@ disable-model-invocation: true
 allowed-tools: Bash
 ---
 
-Run the health check script and report findings to the user:
+Run the health check script:
 
 ```bash
-bash ~/.claude/doctor.sh
+bash $HOME/.claude/doctor.sh 2>/dev/null || {
+  REPO=$(dirname "$(readlink "$HOME/.claude/CLAUDE.md" 2>/dev/null)" 2>/dev/null)
+  bash "$REPO/doctor.sh"
+}
 ```
 
-After displaying the output:
-- If errors are found, suggest the specific fix commands shown in the output.
-- If only warnings, note them but confirm the setup is functional.
-- If all checks pass, confirm the setup is healthy.
+After displaying the doctor.sh output:
+- **CRITICAL token (>30%)** → suggest `/plugin-check` to disable unused plugins; list the heaviest ones.
+- **WARNING token (>15%)** → note which toggle plugins are active and not needed.
+- **Errors (symlinks, agents)** → show the exact fix command (`bash link.sh`).
+- **Warnings only** → confirm setup is functional, note any action recommended.
+- **All pass** → confirm healthy and operational.
diff --git a/skills/init-project/SKILL.md b/skills/init-project/SKILL.md
index d12b80a..67f3b4e 100644
--- a/skills/init-project/SKILL.md
+++ b/skills/init-project/SKILL.md
@@ -8,343 +8,120 @@ allowed-tools: Read, Write, Edit, Bash, Grep, Glob
 
 # ORCHESTRATOR: INIT PROJECT
 
-## AGENTS AND SKILLS LOADED
-
-Custom agents (this config):
-- .claude/agents/plugin-advisor.md   ← plugin configuration check
-- .claude/agents/interviewer.md      ← project questionnaire
-- .claude/agents/analyzer.md         ← risk/constraint analysis
-- .claude/agents/scaffolder.md       ← project skeleton (NO features, skeleton only)
-
-Superpowers skills (design + implementation):
-- superpowers:brainstorming                 ← architecture design
-- superpowers:writing-plans                 ← v1 feature decomposition
-- superpowers:subagent-driven-development   ← isolated TDD implementation
-- superpowers:requesting-code-review        ← final review
-- superpowers:finishing-a-development-branch ← cleanup + verification
-
----
-
-## INITIAL REQUEST
-
+## REQUEST
 $ARGUMENTS
 
 ---
 
-## WORKFLOW
+## STEP 0 — PLUGIN CHECK
+Load `$HOME/.claude/agents/plugin-advisor.md`. Feed request.
+- ACTION REQUIRED → show RECOMMENDATIONS block, offer: A) fix plugins B) type "force". STOP.
+- OK → `✅ Plugin check passed — [active plugins]`, continue.
 
----
-
-### STEP 0 — PLUGIN CHECK
-
-Load and follow: `.claude/agents/plugin-advisor.md`
-
-Feed it the initial request above.
-
-**If `ACTION REQUIRED: YES`:**
+## STEP 1 — INTERVIEW
+Before loading the interviewer, check for an existing CLAUDE.md:
+```bash
+ls CLAUDE.md .claude/CLAUDE.md 2>/dev/null | head -1
 ```
-================================================================
-⚠️  PLUGIN CHECK — ACTION REQUIRED
-================================================================
-[paste full RECOMMENDATIONS block]
-----------------------------------------------------------------
-A) Enable recommended plugins then re-run /init-project
-B) Type "force" to proceed without them
-================================================================
+- **Found** (either `CLAUDE.md` or `.claude/CLAUDE.md`) → read it silently.
+  Pre-fill all interview answers already documented (stack, purpose, features, conventions).
+  Load `$HOME/.claude/agents/interviewer.md` and ask ONLY what is genuinely missing.
+  Print: "📄 Existing CLAUDE.md found — using as context."
+- **Not found** → standard mode: load `$HOME/.claude/agents/interviewer.md`,
+  ask all unanswered questions.
+
+In both cases: MANDATORY STOP until user answers remaining questions. Produce PROJECT BRIEF.
+
+## STEP 2 — ANALYZE
+Load `$HOME/.claude/agents/analyzer.md`. Analyze BRIEF: existing code, stack constraints, infra risks, open decisions. Produce ANALYSIS REPORT.
+
+## STEP 3 — DESIGN
+Invoke `superpowers:brainstorming` with BRIEF + ANALYSIS REPORT.
+Produce DESIGN: stack+versions, full folder tree, module responsibilities, data flow, interfaces (signatures only), config+tooling, test strategy, resolved decisions, prereqs list.
+
+## STEP 4 — VALIDATION GATE #1 ★ MANDATORY STOP
+Present:
 ```
-**STOP. Wait for user response.**
-- Re-run → restart from STEP 0
-- "force" → note missing plugins, continue to STEP 1
-
-**If `ACTION REQUIRED: NO`:**
-Print one line and continue:
-`✅ Plugin check passed — [active plugins]`
-
----
-
-### STEP 1 — INTERVIEWER
-
-Load and follow: `.claude/agents/interviewer.md`
-
-Identify what is already provided in the initial request.
-Ask only what is genuinely missing. Single structured block of questions.
-
-**MANDATORY STOP — do not continue until user has answered.**
-
-Produce the PROJECT BRIEF. This is the single source of truth
-for all subsequent steps.
-
----
-
-### STEP 2 — ANALYZER
-
-Load and follow: `.claude/agents/analyzer.md`
-
-Analyze the PROJECT BRIEF:
-- Existing repo or code to integrate
-- Stack constraints and compatibility issues
-- Infrastructure constraints
-- Risks that could affect the design
-- Open decisions from the PROJECT BRIEF
-
-Produce an ANALYSIS REPORT.
-
----
-
-### STEP 3 — ARCHITECTURE DESIGN
-
-Invoke skill: `superpowers:brainstorming`
-
-Feed it the PROJECT BRIEF + ANALYSIS REPORT.
-
-Produce a complete DESIGN covering:
-- Finalized tech stack with exact versions
-- Complete folder structure (full tree)
-- Module responsibilities and data flow
-- Key interfaces and data models (signatures only — no implementation)
-- Config and tooling setup
-- Test strategy
-- Any open decisions resolved with justification
-- Prerequisites list (what must be installed on dev machine)
-
----
-
-### STEP 4 — VALIDATION GATE #1 — ARCHITECTURE
-
-**MANDATORY STOP — present to the user and wait for approval.**
-
-```
-================================================================
 INIT PROJECT — ARCHITECTURE VALIDATION
-================================================================
-
-PROJECT SUMMARY
----------------
-<3–5 line recap of what will be built>
-
-STACK
------
-<finalized stack with versions>
-
-PREREQUISITES TO INSTALL
--------------------------
-<list of tools / runtimes / services with versions>
-
-FOLDER STRUCTURE
-----------------
-<full tree from the DESIGN>
-
-V1 FEATURES TO IMPLEMENT
--------------------------
-<numbered list from PROJECT BRIEF — these will be implemented
- in the pipeline AFTER the skeleton is scaffolded>
-
-CONVENTIONS
------------
-<naming, doc style, test strategy>
-
-EXCEPTIONS TO GLOBAL RULES
----------------------------
-<list or "none">
-
-================================================================
-Approve this architecture? (yes / request changes)
-================================================================
+PROJECT : <3-5 line recap>
+STACK   : <versions>
+PREREQS : <install list>
+TREE    : <folder tree>
+V1 FEATURES: <numbered list>
+CONVENTIONS: <naming, doc, test>
+EXCEPTIONS : <list or none>
+Approve? (yes / request changes)
 ```
+Changes → back to STEP 3. Approved → continue.
 
-IF changes → return to STEP 3.
-IF approved → proceed.
+## STEP 5 — SCAFFOLD
+Load `$HOME/.claude/agents/scaffolder.md`. Pass: BRIEF + DESIGN + `~/.claude/templates/project-CLAUDE.md` + `~/.claude/CLAUDE.md`.
+Creates: CLAUDE.md, settings, structure, config, empty entry points, .gitignore, .env.example. NO README, NO features.
+Verify: `git init` + build passes.
 
----
+## STEP 5b — CREATE README
+Load `$HOME/.claude/agents/readme-updater.md`. README.md missing → CREATE mode auto. No stop.
 
-### STEP 5 — SCAFFOLD SKELETON
-
-Load and follow: `.claude/agents/scaffolder.md`
-
-Pass to the scaffolder:
-- Full PROJECT BRIEF
-- Approved DESIGN
-- `~/.claude/templates/project-CLAUDE.md`
-- `~/.claude/CLAUDE.md`
-
-The scaffolder creates:
-1. `CLAUDE.md` — filled from global template, no placeholders
-2. `.claude/settings.json` — adapted to this stack
-3. `.claudeignore` — extended for this project
-4. Complete folder structure
-5. Config files (package.json, Cargo.toml, etc.)
-6. Empty entry points and module files (structure only, no business logic)
-7. `.gitignore`, `.env.example`
-
-**The scaffolder does NOT create the README and does NOT implement any features.**
-README is handled by readme-updater (STEP 5b).
-Features are handled by the implementation pipeline (STEPs 6–9).
-
-The scaffolder must verify: `git init` + build passes on empty project.
-
----
-
-### STEP 5b — CREATE README
-
-Load and follow: `.claude/agents/readme-updater.md`
-
-Context: `README.md` does not exist yet → CREATE mode activates automatically.
-
-The readme-updater reads `CLAUDE.md`, the folder structure, and manifests
-to generate the full README (About, Prerequisites with OS-specific install
-commands, Installation, Running, Project structure, Configuration, Contributing).
-
-No stop required — prints confirmation and continues immediately.
-
----
-
-### STEP 6 — PLAN V1 FEATURES
-
-Invoke skill: `superpowers:writing-plans`
-
-Using the PROJECT BRIEF v1 features list and the scaffolded skeleton as context:
-- Break each v1 feature into granular tasks (2–5 min each)
-- Each task must reference exact file paths from the scaffolded structure
-- Each task must include: what to implement, expected behavior, verification steps
-- Apply TDD: tests are written before implementation code
-
----
-
-### STEP 7 — VALIDATION GATE #2 — IMPLEMENTATION PLAN
-
-**MANDATORY STOP — present the plan to the user.**
+## STEP 6 — PLAN
+Invoke `superpowers:writing-plans` with BRIEF + skeleton.
+Granular tasks (2-5 min each), exact file paths, TDD: tests before code.
 
+## STEP 7 — VALIDATION GATE #2 ★ MANDATORY STOP
 ```
-================================================================
-INIT PROJECT — IMPLEMENTATION PLAN VALIDATION
-================================================================
-
-SKELETON STATUS : ✅ build passes
-V1 FEATURES     : <N> features → <M> tasks
-
-<numbered task list with file paths>
-
-================================================================
-Approve this plan and start implementation? (yes / request changes)
-================================================================
+INIT PROJECT — IMPLEMENTATION PLAN
+SKELETON: ✅ build passes
+FEATURES: <N> → <M> tasks
+<numbered task list with paths>
+Approve and start? (yes / request changes)
 ```
+Changes → back to STEP 6. Approved → continue.
 
-IF changes → return to STEP 6.
-IF approved → proceed.
+## STEP 8 — IMPLEMENT
+Invoke `superpowers:subagent-driven-development`. Isolated subagents, TDD, 2-stage review per task.
 
----
+## STEP 9 — ANALYZE
+Load `$HOME/.claude/agents/analyzer.md`. Check: no regressions, no deviations, no stale scaffold, conventions respected.
 
-### STEP 8 — IMPLEMENT V1 FEATURES
+## STEP 10 — CODE REVIEW
+Invoke `superpowers:requesting-code-review`. Fix all CRITICAL before proceeding.
 
-Invoke skill: `superpowers:subagent-driven-development`
+## STEP 11 — FINISH
+Invoke `superpowers:finishing-a-development-branch`. Tests pass, build clean, no placeholders, initial commit ready.
 
-Execute each task with isolated subagents.
-Mandatory TDD: `superpowers:test-driven-development` applies.
-Two-stage review per task: spec compliance → code quality.
+## STEP 12 — SYNC README
+Load `$HOME/.claude/agents/readme-updater.md` with arg `sync`. Detect drift, update cmds/vars/structure, add recent changes entry.
 
-Each subagent works on a clean context with:
-- The task description
-- Relevant file paths
-- PROJECT BRIEF context
-- CLAUDE.md conventions
-
----
-
-### STEP 9 — ANALYZE
-
-Load and follow: `.claude/agents/analyzer.md`
-
-Run the ANALYZER on the completed implementation:
-- Verify no regressions
-- Verify no plan deviations
-- Verify no stale scaffold code left (empty files not yet populated)
-- Verify conventions are respected
-
----
-
-### STEP 10 — CODE REVIEW
-
-Invoke skill: `superpowers:requesting-code-review`
-
-Full review scope:
-- Code quality vs CLAUDE.md conventions and global rules
-- Security issues
-- Missing or incomplete v1 features
-- README accuracy
-- Generated CLAUDE.md completeness (no placeholder remaining)
-- Test coverage
-
-Fix all CRITICAL issues before proceeding.
-
----
-
-### STEP 11 — FINISH
-
-Invoke skill: `superpowers:finishing-a-development-branch`
-
-Verify:
-- All tests pass
-- Build is clean
-- No leftover scaffold placeholders
-- Initial commit prepared
-
----
-
-### STEP 12 — SYNC README
-
-Load and follow: `.claude/agents/readme-updater.md`
-
-Context: call with argument "sync".
-
-SYNC mode — no stop required. The readme-updater:
-- Detects any drift between README and the implemented code
-- Updates commands, env vars, folder structure if changed during implementation
-- Adds a `## Recent changes` entry summarizing v1 features
-- Prints one-line confirmation
+## STEP 13 — GSD v2 INIT (optional)
+If `multi-session` signal was detected in STEP 0 OR the project has >3 planned milestones:
+Ask: "Initialize GSD v2 for multi-session management? (yes / skip)"
+- `yes` →
+  1. First check: `command -v gsd` — if not found:
+     Print: "⚠️ GSD v2 not installed. Run `npm install -g gsd-pi` then re-run `/onboard add gsd` or `/ship-feature` to initialize later."
+     Do NOT attempt `gsd init`. Skip to RULES.
+  2. If `gsd` is in PATH: run `gsd init` in the project directory to create `.gsd/` and `ROADMAP.md`.
+     Populate ROADMAP.md with milestones from BRIEF (v1 features + any beyond-v1 items).
+     Print: "✅ GSD v2 initialized — run `gsd` in terminal then `/gsd auto` to work autonomously."
+- `skip` → print: "GSD v2 skipped — use `/ship-feature` for individual features."
 
 ---
 
 ## RULES
-
-- Never skip STEP 0 — plugin check is mandatory.
-- Never skip STEP 1 — no assumptions about missing info.
-- Never implement without explicit user approval at STEP 4.
-- Never implement without explicit user approval at STEP 7.
-- The scaffolder only creates the skeleton — zero business logic.
-- All feature implementation goes through the subagent pipeline (STEP 8).
-- Apply CLAUDE.md norms throughout.
-- A broken skeleton or a broken build is not acceptable output.
+- No skipping steps. No merged agent responsibilities.
+- No implement without user approval at STEP 4 and STEP 7.
+- Scaffolder = skeleton only, zero logic.
+- Features → subagent pipeline only.
+- Broken build = unacceptable output.
+- Fix all CRITICAL review issues before proceeding.
+- Stop if requirements unclear at any step.
 
 ---
 
 ## FINAL OUTPUT
-
 ```
-================================================================
-PROJECT INITIALIZED: <project name>
-================================================================
-
-LOCATION    : <project root>
-STACK       : <finalized stack>
-BUILD       : ✅ / ❌ <e>
-TESTS       : ✅ <N> passing / ❌ <detail>
-
-V1 FEATURES
------------
-✅ <feature>
-✅ <feature>
-⚠️ <feature> — partial: <reason>
-
-REMAINING ISSUES
-----------------
-<IMPORTANT and MINOR issues, or "none">
-
-QUICK START
------------
-<exact commands to run the project right now>
-
-CLAUDE.md  : ✅ complete
-README.md  : ✅ created (STEP 5b) + synced (STEP 12)
-SETTINGS   : ✅ .claude/settings.json + .claudeignore generated
-================================================================
+PROJECT INITIALIZED: <n>
+LOCATION: <path> | STACK: <stack> | BUILD: ✅/❌ | TESTS: ✅<N>/❌
+V1 FEATURES: ✅<f> / ⚠️<f> partial: <reason>
+REMAINING ISSUES: <list or none>
+QUICK START: <exact cmds>
+CLAUDE.md ✅ | README ✅ | SETTINGS ✅
 ```
diff --git a/skills/onboard/SKILL.md b/skills/onboard/SKILL.md
new file mode 100644
index 0000000..581532a
--- /dev/null
+++ b/skills/onboard/SKILL.md
@@ -0,0 +1,15 @@
+---
+name: onboard
+description: Onboard an existing project into claude-config — generates CLAUDE.md, settings, .claudeignore, optional GSD v2 ROADMAP. Use on repos not created via /init-project.
+argument-hint: [optional hints: "Python FastAPI" | "add gsd" | "Next.js monorepo"]
+disable-model-invocation: true
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+Load and follow strictly:
+- $HOME/.claude/agents/onboarder.md
+
+Run the ONBOARDER agent on the current working directory.
+
+Additional hints from user (if any):
+$ARGUMENTS
diff --git a/skills/plugin-check/SKILL.md b/skills/plugin-check/SKILL.md
index 3604814..e898b8e 100644
--- a/skills/plugin-check/SKILL.md
+++ b/skills/plugin-check/SKILL.md
@@ -1,13 +1,13 @@
 ---
 name: plugin-check
 description: Audit active plugins vs project needs. Recommends enable/disable actions.
-argument-hint: [project description or feature to build]
+argument-hint: [ex: "React + FastAPI" or "Rust CLI, no frontend"]
 disable-model-invocation: true
 allowed-tools: Read, Bash, Glob, Grep
 ---
 
 Load and follow strictly:
-- .claude/agents/plugin-advisor.md
+- $HOME/.claude/agents/plugin-advisor.md
 
 Analyze active plugins and the following context,
 then produce the full PLUGIN ADVISOR REPORT:
diff --git a/skills/readme/SKILL.md b/skills/readme/SKILL.md
index dd7332e..d69897e 100644
--- a/skills/readme/SKILL.md
+++ b/skills/readme/SKILL.md
@@ -7,7 +7,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 
 Load and follow strictly:
-- .claude/agents/readme-updater.md
+- $HOME/.claude/agents/readme-updater.md
 
 Execute the README UPDATER on this project.
 
diff --git a/skills/refactor/SKILL.md b/skills/refactor/SKILL.md
index f11fe73..7d0fc3a 100644
--- a/skills/refactor/SKILL.md
+++ b/skills/refactor/SKILL.md
@@ -7,7 +7,7 @@ allowed-tools: Read, Write, Edit, Grep, Glob, Bash
 ---
 
 Load and follow strictly:
-- .claude/agents/refactorer.md
+- $HOME/.claude/agents/refactorer.md
 
 Execute the REFACTORER agent on the following target:
 
diff --git a/skills/ship-feature/SKILL.md b/skills/ship-feature/SKILL.md
index 4a4c931..3228630 100644
--- a/skills/ship-feature/SKILL.md
+++ b/skills/ship-feature/SKILL.md
@@ -8,176 +8,112 @@ allowed-tools: Read, Write, Edit, Bash, Grep, Glob
 
 # ORCHESTRATOR: SHIP FEATURE
 
-## AGENTS AND SKILLS LOADED
-
-Custom agents (this config):
-- .claude/agents/plugin-advisor.md   ← plugin configuration check
-- .claude/agents/analyzer.md         ← post-implementation verification
-
-Superpowers skills:
-- superpowers:brainstorming
-- superpowers:writing-plans
-- superpowers:subagent-driven-development
-- superpowers:requesting-code-review
-- superpowers:finishing-a-development-branch
-
----
-
-## FEATURE REQUEST
-
+## REQUEST
 $ARGUMENTS
 
 ---
 
-## WORKFLOW
-
----
-
-### STEP 0 — PLUGIN CHECK (mandatory gate)
-
-Load and follow: `.claude/agents/plugin-advisor.md`
-
-Feed it the feature request above as context for signal detection.
-
-The advisor will:
-1. Detect which plugins are currently active
-2. Analyze the feature description for signals
-3. Produce a recommendation table
-
-**If the advisor output says `ACTION REQUIRED: YES`:**
-
-Print this block and STOP COMPLETELY:
+## STEP 0 — PLUGIN CHECK
+Load `$HOME/.claude/agents/plugin-advisor.md`. Feed request.
+- ACTION REQUIRED → show RECOMMENDATIONS, offer: A) fix plugins B) type "force". STOP.
+- OK → `✅ Plugin check passed — [active plugins]`, continue.
 
+## STEP 0b — PROJECT CONTEXT CHECK
+Verify the project has a `CLAUDE.md` and print a brief orientation summary:
+```bash
+ls CLAUDE.md .claude/CLAUDE.md 2>/dev/null | head -1
+git branch --show-current 2>/dev/null || echo "not a git repo"
+git log --oneline -3 --format="%h %<(50,trunc)%s" 2>/dev/null || true
+ls .gsd/ROADMAP.md 2>/dev/null | head -1
 ```
-================================================================
-⚠️  PLUGIN CHECK — ACTION REQUIRED
-================================================================
+- **CLAUDE.md found** → read it silently, then print orientation header (informational, not a gate):
+  ```
+  📋 PROJECT CONTEXT
+  Project : <name from CLAUDE.md>
+  Stack   : <stack from CLAUDE.md>
+  Branch  : <current git branch>
+  Recent  : <last 3 commit messages>
+  GSD     : <current milestone if .gsd/ROADMAP.md exists, else "not initialized">
+  ```
+  Continue to STEP 1.
+- **Not found** →
+  Print: "⚠️ No CLAUDE.md found in this directory.
+  This project has not been onboarded into claude-config.
+  Run `/onboard` first to generate CLAUDE.md and project settings,
+  then re-run `/ship-feature`."
+  STOP.
 
-[paste the full RECOMMENDATIONS block from the advisor]
+## STEP 1 — BRAINSTORM
+Invoke `superpowers:brainstorming`. Refine request into validated design via Socratic questioning. Don't proceed until design approved.
 
-----------------------------------------------------------------
-Options:
-  A) Enable the recommended plugins, then re-run /ship-feature
-  B) Type "force" to proceed without the recommended plugins
-     (you will miss capabilities — see warnings above)
-================================================================
+## STEP 2 — PLAN
+Invoke `superpowers:writing-plans`. Break design into tasks (2-5 min each). Each task: exact file paths, full code, verification steps.
+
+## STEP 3 — VALIDATION GATE ★ MANDATORY STOP
 ```
-
-Wait for user response.
-- If user re-runs `/ship-feature` → start from STEP 0 again
-- If user types "force" → note missing plugins and continue to STEP 1
-
-**If the advisor output says `ACTION REQUIRED: NO`:**
-Print one line and continue immediately:
-```
-✅ Plugin check passed — [active plugins in one line]
-```
-
----
-
-### STEP 1 — BRAINSTORM
-Invoke skill: `superpowers:brainstorming`
-
-Refine the feature request into a validated design through
-Socratic questioning. Do not proceed until the design is approved.
-
----
-
-### STEP 2 — PLAN
-Invoke skill: `superpowers:writing-plans`
-
-Break the approved design into granular tasks (2–5 min each).
-Each task must have: exact file paths, complete code, verification steps.
-
----
-
-### STEP 3 — VALIDATION GATE
-
-**MANDATORY STOP — present the plan to the user.**
-
-```
-================================================================
 SHIP FEATURE — VALIDATION GATE
-================================================================
-FEATURE  : <name>
-TASKS    : <count>
+FEATURE: <n> | TASKS: <count>
 <numbered task list>
-================================================================
 Approve and execute? (yes / request changes)
-================================================================
 ```
+Changes → back to STEP 2. Approved → continue.
 
-IF changes → return to STEP 2.
-IF approved → proceed.
+## STEP 4 — IMPLEMENT
+Invoke `superpowers:subagent-driven-development`. Isolated subagents. 2-stage review per task: spec compliance → code quality.
 
----
+## STEP 4b — ERROR RECOVERY (if STEP 4 fails)
+If a subagent returns a build error, failing test, or type error:
+1. Load `$HOME/.claude/agents/analyzer.md` in DEBUG MODE on the exact error output.
+   Produce: root cause hypotheses (ordered), affected files, what NOT to touch.
+2. Present gate:
+```
+SHIP FEATURE — ERROR IN STEP 4
+TASK    : <task name that failed>
+ERROR   : <one-line summary>
+HYPOTHESES:
+  1. [HIGH] <cause> — evidence: <…>
+  2. [MED]  <cause> — evidence: <…>
+OPTIONS :
+  A) Apply fix for hypothesis 1 and re-run this task
+  B) Skip this task and continue with remaining tasks
+  C) Abort feature — preserve work done so far
+```
+3. Wait for user choice. Do NOT auto-fix. Do NOT proceed without explicit approval.
+4. If A → apply minimal fix, re-run STEP 4 for the failed task only. Max 2 retry attempts.
+   If still failing after 2 → fall back to options B or C.
+   If B → before skipping: scan remaining task list for tasks that depend on the failed task
+     (look for references to the same file or function in subsequent tasks).
+     If dependents found → present: "Tasks [N, M] depend on the skipped task.
+       Skip them too? (yes / keep and accept partial implementation)"
+     If no dependents → skip cleanly and continue.
 
-### STEP 4 — IMPLEMENT
-Invoke skill: `superpowers:subagent-driven-development`
+## STEP 5 — ANALYZE
+Load `$HOME/.claude/agents/analyzer.md`. Check: no regressions, no stale code, no plan deviations.
 
-Execute each task with isolated subagents.
-Two-stage review per task: spec compliance → code quality.
+## STEP 6 — CODE REVIEW
+Invoke `superpowers:requesting-code-review`. Fix all CRITICAL before proceeding.
 
----
+## STEP 7 — FINISH
+Invoke `superpowers:finishing-a-development-branch`. Tests pass, build clean, ready to merge.
 
-### STEP 5 — ANALYZE (custom)
-Load and follow: `.claude/agents/analyzer.md`
-
-Run the ANALYZER on the produced implementation.
-Verify no regressions, no stale code, no plan deviations.
-
----
-
-### STEP 6 — CODE REVIEW
-Invoke skill: `superpowers:requesting-code-review`
-
-Dispatch the code-reviewer agent on the full implementation.
-Fix any CRITICAL issues before proceeding.
-
----
-
-### STEP 7 — FINISH BRANCH
-Invoke skill: `superpowers:finishing-a-development-branch`
-
-Verify all tests pass, cleanup, prepare for merge.
-
----
-
-### STEP 8 — SYNC README
-
-Load and follow: `.claude/agents/readme-updater.md`
-
-Context: call with argument "sync".
-
-SYNC mode — no stop required. The readme-updater:
-- Detects any drift between README and the new feature
-- Updates commands, env vars, folder structure if changed
-- Adds a `## Recent changes` entry with the shipped feature
-- Prints one-line confirmation
+## STEP 8 — SYNC README
+Load `$HOME/.claude/agents/readme-updater.md` with arg `sync`. Update cmds/vars/structure, add recent changes entry.
 
 ---
 
 ## RULES
-
-- Never skip STEP 0 — plugin check is mandatory.
-- Never skip brainstorming.
-- Never implement without explicit user approval of the plan.
-- Keep subagents isolated — no shared context between tasks.
-- Apply CLAUDE.md norms throughout.
+- No skipping steps. No merged agent responsibilities.
+- No implement without user approval at STEP 3.
+- Subagents isolated — no shared context between tasks.
+- Fix all CRITICAL review issues before proceeding.
+- Stop if requirements unclear at any step.
+- STEP 4 errors → STEP 4b gate required before any fix. Never auto-patch a failing subagent.
 
 ---
 
 ## FINAL OUTPUT
-
 ```
-================================================================
-FEATURE SHIPPED: <name>
-================================================================
-TASKS COMPLETED : <N>/<N>
-TESTS           : ✅ passing / ❌ <detail>
-REVIEW          : APPROVED / CHANGES REQUIRED
-
-REMAINING ISSUES (IMPORTANT/MINOR):
-- <issue or "none">
-================================================================
+FEATURE SHIPPED: <n>
+TASKS: <N>/<N> | TESTS: ✅/❌ | REVIEW: APPROVED/CHANGES REQUIRED
+REMAINING ISSUES: <list or none>
 ```
diff --git a/skills/status/SKILL.md b/skills/status/SKILL.md
new file mode 100644
index 0000000..b9d47f3
--- /dev/null
+++ b/skills/status/SKILL.md
@@ -0,0 +1,14 @@
+---
+name: status
+description: Consolidated project snapshot — plugins active, token cost, git state, recent commits, GSD v2 milestone progress. Read-only. Run at session start or after a break.
+argument-hint: (no arguments needed)
+disable-model-invocation: true
+allowed-tools: Read, Bash, Glob, Grep
+---
+
+Load and follow strictly:
+- $HOME/.claude/agents/status-reporter.md
+
+Produce the full PROJECT STATUS report for the current working directory.
+
+$ARGUMENTS
diff --git a/templates/project-CLAUDE.md b/templates/project-CLAUDE.md
index bd7e1ab..6da6cb8 100644
--- a/templates/project-CLAUDE.md
+++ b/templates/project-CLAUDE.md
@@ -1,74 +1,105 @@
 # <PROJECT NAME> — CLAUDE.md
 
-# This file was generated by /init-project.
-# It is the single source of truth for Claude in this repository.
-# Global rules live in ~/.claude/CLAUDE.md — this file extends or
-# overrides them for this specific project.
+# Generated by /init-project. Single source of truth for Claude in this repo.
+# Global rules: ~/.claude/CLAUDE.md — this file extends or overrides them.
 
 ---
 
 ## Project overview
 
-<!-- FILL: 2–4 sentences. What does this project do and for whom. -->
+<!-- What it does and for whom. 2-4 sentences. -->
+<!-- Ex: REST API for managing food delivery orders. Exposes CRUD endpoints consumed by a React frontend. Single-tenant, deployed on a VPS via Docker Compose. -->
 
 ---
 
 ## Stack
 
-<!-- FILL: language + version, framework, runtime, database, key services -->
+<!-- language+version, framework, runtime, database, key services -->
+<!-- Ex: Python 3.12 / FastAPI / PostgreSQL 16 / Redis 7 / Docker Compose -->
 
 ---
 
 ## Build commands
 
-<!-- FILL: exact commands to build the project -->
+<!-- Exact commands — native and Docker if applicable -->
+<!-- Ex:
+  Native : uvicorn src.main:app --reload
+  Docker : docker compose up --build
+  Build  : docker build -t myapp .
+-->
 
 ---
 
 ## Test commands
 
-<!-- FILL: exact commands to run tests -->
+<!-- Ex: pytest src/tests/ -v --cov=src -->
 
 ---
 
 ## Lint / format commands
 
-<!-- FILL: exact commands, or N/A -->
+<!-- Ex: ruff check . && black --check . && mypy src/ -->
+<!-- Or: N/A -->
 
 ---
 
 ## Folder structure
 
-<!-- FILL: actual tree of the project -->
+<!-- Actual tree — fill after scaffolding -->
+<!-- Ex:
+src/
+  main.py        — app init, lifespan hooks
+  routes/        — one file per resource
+  models/        — SQLAlchemy models
+  schemas/       — Pydantic schemas
+  services/      — business logic
+tests/
+  conftest.py
+  test_orders.py
+-->
 
 ---
 
 ## Architecture
 
-<!-- FILL: module responsibilities, data flow, key design decisions -->
+<!-- Module responsibilities, data flow, key design decisions -->
+<!-- Ex: Request → router → service (business logic) → repository (DB) → response.
+     Auth: JWT validated in a FastAPI dependency injected at router level. -->
 
 ---
 
 ## Project conventions
 
-<!-- FILL: naming style, file organization, patterns specific to this project -->
+<!-- Naming, file organization, patterns specific to this project -->
+<!-- Ex: snake_case everywhere. Route files named after the resource (orders.py, users.py).
+     All DB access goes through repository classes, never direct in routes. -->
 
 ---
 
 ## Exceptions to global rules
 
-<!-- FILL: explicit overrides of ~/.claude/CLAUDE.md, or write "none — global rules apply" -->
+<!-- Explicit overrides of ~/.claude/CLAUDE.md, or: -->
+<!-- none — global rules apply -->
 
 ---
 
 ## Key dependencies
 
-<!-- FILL: library name — purpose, one line each -->
+<!-- library — purpose, one line each -->
+<!-- Ex:
+  fastapi      — web framework
+  sqlalchemy   — ORM
+  alembic      — DB migrations
+  pydantic     — validation/serialization
+  pytest       — test framework
+  ruff         — linter
+-->
 
 ---
 
 ## Workflow expectations
 
-<!-- FILL: how Claude should behave in this repo:
-     e.g. always run tests after modification, never modify unrelated files,
-     ask before large refactors, etc. -->
+<!-- How Claude should behave in this repo -->
+<!-- Ex: Always run pytest after any model/service change.
+     Never modify migration files — generate new ones with alembic revision.
+     Ask before touching the auth dependency or JWT logic. -->
diff --git a/templates/settings/SETTINGS.md b/templates/settings/SETTINGS.md
index 8d5103f..ef5a5f5 100644
--- a/templates/settings/SETTINGS.md
+++ b/templates/settings/SETTINGS.md
@@ -1,69 +1,4 @@
-# Claude Code — Settings Reference
-
-## Where each file goes
-
-```
-~/.claude/
-├── settings.json          ← home-settings.json (renamed) — global, NEVER commit
-│
-mon-projet/
-└── .claude/
-    ├── settings.json      ← settings.json — project rules, commit to git
-    └── settings.local.json← settings.local.json — personal, gitignored
-```
-
-Add to your project `.gitignore`:
-```
-.claude/settings.local.json
-```
-
----
-
-## Precedence (highest → lowest)
-
-```
-managed-settings.json     system-wide, cannot be overridden
-  └── CLI flags            --allowedTools, --disallowedTools (session only)
-        └── settings.local.json   personal local
-              └── settings.json   project (team)
-                    └── ~/.claude/settings.json   global user
-```
-
-**DENY always wins over ALLOW, regardless of level.**
-
----
-
-## What goes where
-
-| Rule type | File |
-|---|---|
-| Deny secrets, SSH, rm -rf, sudo | `~/.claude/settings.json` |
-| Deny git push --force, curl\|bash | `~/.claude/settings.json` |
-| Ask git push, docker run, deploy | `~/.claude/settings.json` |
-| Ask package managers (brew, apt) | `~/.claude/settings.json` |
-| Allow git read-only, ls, cat, grep | `~/.claude/settings.json` |
-| Allow npm/cargo/make/pytest... | `.claude/settings.json` (project) |
-| Ask psql, mysql, redis-cli | `.claude/settings.json` (project) |
-| Allow specific WebFetch domains | `.claude/settings.local.json` |
-| Personal additionalDirectories | `.claude/settings.local.json` |
-
----
-
-## defaultMode values
-
-| Value | Behavior | When to use |
-|---|---|---|
-| `default` | Prompts on first use of each tool | Normal development |
-| `acceptEdits` | Auto-accepts file edits, prompts for Bash | Trusting sessions |
-| `plan` | Read-only — Claude plans, cannot execute | Code review, audit |
-| `bypassPermissions` | Skips all prompts — **dangerous** | CI/CD only, sandboxed env |
-
-Disable bypass permanently (set in `~/.claude/settings.json`):
-```json
-{ "permissions": { "disableBypassPermissionsMode": "disable" } }
-```
-
----
+# Claude Code — Settings Rule Syntax
 
 ## Rule syntax
 
@@ -83,14 +18,10 @@ Disable bypass permanently (set in `~/.claude/settings.json`):
 "Write(**/*.key)"          // deny writing any .key file
 ```
 
-### WebFetch
+### WebFetch / WebSearch
 ```json
 "WebFetch(domain:docs.rs)" // specific domain only
-"WebFetch"                  // all web fetches (no sub-pattern)
-```
-
-### WebSearch
-```json
+"WebFetch"                  // all web fetches
 "WebSearch"                 // no sub-patterns supported
 ```
 
@@ -99,32 +30,27 @@ Disable bypass permanently (set in `~/.claude/settings.json`):
 "Agent(explorer)"
 "Skill(deploy *)"
 "mcp__github__*"           // all tools from github MCP server
-"mcp__playwright__navigate"
 ```
 
----
+## defaultMode values
+
+| Value | Behavior | When to use |
+|---|---|---|
+| `default` | Prompts on first use of each tool | Normal development |
+| `acceptEdits` | Auto-accepts file edits, prompts for Bash | Trusting sessions |
+| `plan` | Read-only — Claude plans, cannot execute | Code review, audit |
+| `bypassPermissions` | Skips all prompts — **dangerous** | CI/CD only, sandboxed env |
 
 ## Security notes
 
-- `Read(**/.env)` only blocks the Read tool.
-  `Bash(cat .env)` bypasses it unless you also deny that Bash command.
-  → Use `.claudeignore` for hard file exclusion.
-
-- `disableBypassPermissionsMode: "disable"` prevents switching to
-  bypass mode mid-session — set it in `~/.claude/settings.json`.
-
-- Prefer `ask` over `allow` for anything touching external systems
-  (git push, deploy, database commands, package install).
-
-- `deny` rules in `~/.claude/settings.json` cannot be overridden
-  by project-level `allow` rules — deny always wins globally.
-
----
+- `Read(**/.env)` only blocks the Read tool. `Bash(cat .env)` bypasses it unless separately denied.
+  → Use `.claudeignore` for hard file exclusion regardless of tool.
+- `disableBypassPermissionsMode: "disable"` prevents switching to bypass mode mid-session.
+- Prefer `ask` over `allow` for anything touching external systems.
+- `deny` in `~/.claude/settings.json` cannot be overridden by project-level `allow` — deny always wins.
 
 ## managed-settings.json (enterprise)
 
-Cannot be overridden by any user or project setting.
-
 | OS | Path |
 |---|---|
 | Windows | `C:\ProgramData\ClaudeCode\managed-settings.json` |
diff --git a/templates/settings/settings.json b/templates/settings/settings.json
index ea95801..8a46b57 100644
--- a/templates/settings/settings.json
+++ b/templates/settings/settings.json
@@ -1,5 +1,4 @@
 {
-  "_readme": "Project-level settings — commit this file. Extends ~/.claude/settings.json. Only put project-specific rules here.",
 
   "permissions": {
 
@@ -53,19 +52,21 @@
       "Bash(docker ps*)",
       "Bash(docker images*)",
       "Bash(docker logs *)",
-      "Bash(docker stop *)",
-      "Bash(docker rm *)",
 
       "Bash(node *)",
       "Bash(ts-node *)",
       "Bash(tsx *)",
-      "Bash(npx *)",
 
       "Bash(norminette*)"
     ],
 
     "ask": [
 
+      "Bash(npx *)",
+
+      "Bash(docker stop *)",
+      "Bash(docker rm *)",
+
       "Bash(make deploy*)",
       "Bash(npm run deploy*)",
       "Bash(cargo publish*)",
diff --git a/templates/settings/settings.local.json b/templates/settings/settings.local.json
index e522343..4fec95e 100644
--- a/templates/settings/settings.local.json
+++ b/templates/settings/settings.local.json
@@ -1,5 +1,4 @@
 {
-  "_readme": "Personal local overrides — DO NOT commit. Add .claude/settings.local.json to .gitignore. Highest priority after CLI flags.",
 
   "permissions": {
 
diff --git a/update-all.sh b/update-all.sh
index cf07690..ef80ec6 100644
--- a/update-all.sh
+++ b/update-all.sh
@@ -30,13 +30,29 @@ fi
 # ── 2. Update GStack submodule ──
 echo ""
 echo "── Updating GStack submodule..."
-if git submodule update --remote skills-external/gstack 2>/dev/null; then
-  if [ -d "skills-external/gstack" ]; then
-    cd skills-external/gstack && ./setup 2>/dev/null && cd "$REPO"
-    ok "GStack updated"
+warn "GStack tracks branch = main (no commit hash). Review upstream commits before updating."
+echo ""
+printf "  Proceed with GStack update? [y/N] "
+read -r _gstack_confirm
+if [[ "$_gstack_confirm" =~ ^[Yy]$ ]]; then
+  if git submodule update --remote skills-external/gstack 2>/dev/null; then
+    if [ -d "skills-external/gstack" ]; then
+      if [ -x "skills-external/gstack/setup" ]; then
+        if (cd skills-external/gstack && ./setup) 2>/dev/null; then
+          ok "GStack updated"
+        else
+          warn "GStack ./setup failed — submodule updated but setup did not complete"
+        fi
+      else
+        warn "GStack ./setup not found or not executable — skipping"
+        ok "GStack submodule pointer updated"
+      fi
+    fi
+  else
+    warn "GStack submodule update failed — run: git submodule update --init"
   fi
 else
-  warn "GStack submodule update failed — run: git submodule update --init"
+  info "GStack update skipped"
 fi
 
 # ── 3. Update RTK (if pinned version available) ──
@@ -68,11 +84,68 @@ else
   warn "Cargo not available — skipping RTK"
 fi
 
-# ── 4. Refresh symlinks ──
+# ── 4. Update GSD v2 ──
+echo ""
+echo "── Updating GSD v2 (gsd-pi)..."
+if command -v gsd &>/dev/null; then
+  GSD_VER=""
+  if [ -f "$REPO/plugins.lock.json" ] && command -v python3 &>/dev/null; then
+    GSD_VER=$(python3 -c "
+import json
+with open('$REPO/plugins.lock.json') as f:
+    d = json.load(f)
+print(d.get('gsd',{}).get('version',''))
+" 2>/dev/null || true)
+  fi
+
+  if [ -n "$GSD_VER" ] && [ "$GSD_VER" != "latest" ]; then
+    info "Pinned version: $GSD_VER"
+    npm install -g "gsd-pi@${GSD_VER}" 2>/dev/null \
+      && ok "GSD v2 updated to $GSD_VER" \
+      || warn "GSD v2 update failed"
+  else
+    info "No pinned version — installing latest"
+    npm install -g gsd-pi 2>/dev/null \
+      && ok "GSD v2 updated (latest)" \
+      || warn "GSD v2 update failed"
+  fi
+else
+  warn "GSD v2 not installed — skipping (run: npm install -g gsd-pi)"
+fi
+
+# ── 5. Update Ruflo MCP (if installed) ──
+echo ""
+echo "── Updating Ruflo MCP..."
+if command -v ruflo &>/dev/null || detect_ruflo; then
+  RUFLO_VER=""
+  if [ -f "$REPO/plugins.lock.json" ] && command -v python3 &>/dev/null; then
+    RUFLO_VER=$(python3 -c "
+import json
+with open('$REPO/plugins.lock.json') as f:
+    d = json.load(f)
+print(d.get('ruflo',{}).get('version',''))
+" 2>/dev/null || true)
+  fi
+
+  if [ -n "$RUFLO_VER" ] && [ "$RUFLO_VER" != "latest" ]; then
+    info "Pinned version: $RUFLO_VER"
+    npm install -g "ruflo@${RUFLO_VER}" 2>/dev/null \
+      && ok "Ruflo updated to $RUFLO_VER" \
+      || warn "Ruflo update failed"
+  else
+    npm install -g ruflo@latest 2>/dev/null \
+      && ok "Ruflo updated (latest)" \
+      || warn "Ruflo update failed"
+  fi
+else
+  info "Ruflo not installed — skipping"
+fi
+
+# ── 6. Refresh symlinks ──
 echo ""
 echo "── Refreshing symlinks..."
 bash "$REPO/link.sh"
 
-# ── 5. Run doctor ──
+# ── 7. Run doctor ──
 echo ""
 bash "$REPO/doctor.sh"
diff --git a/version.txt b/version.txt
index 3eefcb9..e4604e3 100644
--- a/version.txt
+++ b/version.txt
@@ -1 +1 @@
-1.0.0
+3.2.1