refactor: code quality cleanup — remove any types, add logger, rename Kine to Tabata

- Phase 0: Rename all Kine references to Tabata (types, files, imports, i18n, analytics events) - Phase 1: Add test coverage for tabataProgramStore, workoutProgramStore, and color utils (47 tests) - Phase 2: Remove all `any` types from production code with proper typed replacements - Phase 3: Replace ~60 raw console.* calls with __DEV__-gated logger utility - Phase 4: Verify .DS_Store housekeeping (already clean) 0 TypeScript errors, 583/583 tests passing.
2026-04-17 18:56:24 +02:00
parent e0e02c4550
commit 791f432334
176 changed files with 16508 additions and 2305 deletions
--- a/.claude/skills/design_system/SKILL.md
+++ b/.claude/skills/design_system/SKILL.md
@@ -0,0 +1,576 @@
+---
+name: tabata-kine-design-system
+description: >
+  Design system complet pour l'application Tabata Kiné. Utilise ce skill pour
+  toute tâche liée au design, aux composants UI, aux écrans, aux couleurs, à la
+  typographie ou aux décisions d'interface de l'app Tabata Kiné. Déclenche ce
+  skill dès que l'utilisateur mentionne : un écran de l'app (onboarding, séance,
+  dashboard, paywall, programmes), un composant (bouton, carte, timer, badge,
+  input), une couleur, une typographie, une animation, un espacement, ou demande
+  à coder un élément UI. Ce skill contient les règles non négociables du design
+  "Dark Medical" — le style qui différencie l'app de tous les concurrents fitness.
+---
+
+# Design System — Tabata Kiné
+
+## Principe directeur : Dark Medical
+
+L'app Tabata Kiné n'est **pas** une app fitness classique. C'est une app médicale
+qui utilise le format tabata. Le style "Dark Medical" traduit visuellement ce
+positionnement : fond sombre professionnel, vert santé comme seule couleur d'action,
+expertise kiné visible à chaque écran.
+
+**Règles absolues :**
+- Pas de mode clair. Dark only, sans exception.
+- Le vert (#00C896) ne sert qu'aux actions et à la validation.
+- L'orange (#FF8A5C) ne sert qu'aux conseils kiné et alertes positives.
+- Le rouge (#FF4444) est réservé au timer en phase d'urgence (<10s).
+- Touch target minimum : 44×44px pour tous les éléments interactifs.
+
+---
+
+## 1. Tokens de couleur
+
+### Fonds — Navy
+
+| Token | Valeur | Usage |
+|-------|--------|-------|
+| `navy-900` | `#0D1B2A` | Fond principal de l'app |
+| `navy-800` | `#112240` | Surface 1 — cartes par défaut |
+| `navy-700` | `#1A3050` | Surface 2 — cartes surélevées |
+| `navy-600` | `#243C5E` | Bordures actives |
+
+### Vert Kiné — action & santé
+
+| Token | Valeur | Usage |
+|-------|--------|-------|
+| `green-500` | `#00C896` | CTA principal, timer effort, progress |
+| `green-600` | `#00A67C` | État hover / pressed |
+| `green-700` | `#00875F` | État active deep |
+| `green-dim` | `rgba(0,200,150,0.12)` | Fond badge, chip, card accent |
+| `green-border` | `rgba(0,200,150,0.35)` | Bordure card accent |
+
+### Texte & bordures
+
+| Token | Valeur | Usage |
+|-------|--------|-------|
+| `white-100` | `#E6F1FF` | Texte primaire |
+| `slate-300` | `#A8B2D8` | Texte secondaire |
+| `slate-400` | `#8892B0` | Texte tertiaire, placeholders |
+| `border-dim` | `rgba(168,178,216,0.15)` | Bordure par défaut |
+| `border-hover` | `rgba(168,178,216,0.25)` | Bordure hover |
+
+### Orange — conseils kiné uniquement
+
+| Token | Valeur | Usage |
+|-------|--------|-------|
+| `orange-500` | `#FF8A5C` | Tip card border, badge Kiné+ |
+| `orange-600` | `#E06A3C` | Hover orange |
+| `orange-dim` | `rgba(255,138,92,0.12)` | Fond tip card |
+
+### Sémantique
+
+| Token | Valeur | Usage |
+|-------|--------|-------|
+| `red-500` | `#FF4444` | Timer urgence <10s UNIQUEMENT |
+
+---
+
+## 2. Typographie
+
+### Familles
+
+| Rôle | Famille | Notes |
+|------|---------|-------|
+| Titres émotionnels | Serif italique (ex: DM Serif Display, Georgia) | Célébration, fin de séance, accroches |
+| Interface & corps | Sans-serif géométrique (ex: Outfit, DM Sans) | Navigation, descriptions, labels |
+| Données & timer | Monospace (ex: DM Mono, JetBrains Mono) | Timer, stats, codes, metadata |
+
+### Échelle
+
+| Style | Famille | Taille | Poids | Usage |
+|-------|---------|--------|-------|-------|
+| `display` | Serif italic | 28–32px | 400 | Fin de séance, titres forts |
+| `heading-1` | Serif | 22–24px | 500 | Titres de section |
+| `heading-2` | Sans | 18px | 500 | Titre exercice, carte programme |
+| `body` | Sans | 15–16px | 400 | Corps, conseil kiné |
+| `label` | Mono | 11–13px | 500 | Tags, metadata, uppercase tracking |
+| `timer` | Mono | **80–100px** | 500 | Timer séance — lisible à 2 mètres |
+| `caption` | Sans | 12px | 400 | Sous-labels, hints |
+
+**Règle typographie :** La taille du timer est la décision de design la plus
+importante de l'écran séance. Tout se dimensionne autour de lui.
+
+---
+
+## 3. Espacement
+
+Base : **4px**
+
+| Token | Valeur | Usage |
+|-------|--------|-------|
+| `space-1` | 4px | Gap minimal entre éléments liés |
+| `space-2` | 8px | Gap interne composant |
+| `space-3` | 12px | Gap entre composants proches |
+| `space-4` | 16px | Padding carte, gap standard |
+| `space-6` | 24px | Espacement sections |
+| `space-8` | 32px | Padding écran horizontal |
+| `space-12` | 48px | Espacement majeur |
+| `space-16` | 64px | Espacement entre blocs screens |
+
+---
+
+## 4. Border Radius
+
+| Token | Valeur | Usage |
+|-------|--------|-------|
+| `radius-sm` | 4px | Badge, chip, tag |
+| `radius-md` | 8px | Bouton, input, tip card |
+| `radius-lg` | 12px | Carte programme standard |
+| `radius-xl` | 16px | Carte large, modal |
+| `radius-pill` | 9999px | Pill, toggle, progress bar |
+| `radius-circle` | 50% | Icon button, avatar, streak dot |
+
+---
+
+## 5. Système d'élévation (surfaces)
+
+```
+Fond (navy-900)
+  └── Surface 1 (navy-800) — cartes par défaut
+        └── Surface 2 (navy-700) — cartes surélevées / hover
+              └── Surface active (navy-800 + border green-500 1.5px)
+```
+
+Différencier les surfaces **uniquement par la couleur de fond**, jamais par des
+ombres portées (box-shadow : non). La bordure active verte est le seul signal
+d'état sélectionné.
+
+---
+
+## 6. Composants
+
+### Boutons
+
+```
+PrimaryButton
+  background: green-500
+  color: navy-900
+  padding: 14px 24px
+  height: 52–56px
+  border-radius: radius-md
+  font: sans 15px 500
+  width: 100% (full-width dans les screens)
+  hover: background green-600
+  active: background green-700 + scale(0.98)
+
+SecondaryButton
+  background: transparent
+  color: green-500
+  border: 1.5px solid green-500
+  padding: 13px 24px
+  hover: background green-dim
+
+GhostButton
+  background: transparent
+  color: slate-300
+  no border
+  usage: actions secondaires (Passer, Annuler)
+
+DangerButton
+  background: rgba(255,68,68,0.12)
+  color: #FF6B6B
+  border: 1px solid rgba(255,68,68,0.3)
+  usage: Quitter la séance UNIQUEMENT
+
+IconButton
+  width: 44px
+  height: 44px
+  border-radius: 50%
+  background: rgba(168,178,216,0.10)
+  color: slate-300
+  JAMAIS en dessous de 44×44px (accessibilité)
+```
+
+### Inputs
+
+```
+TextField
+  background: navy-800
+  border: 1px solid border-dim
+  border-radius: radius-md
+  padding: 12px 16px
+  color: white-100
+  font: sans 15px 400
+  focus: border green-500
+  error: border red-500
+  height: 48px
+```
+
+### Badges & Pills
+
+```
+Badge (tier)
+  font: mono 11px 500
+  padding: 3px 10px
+  border-radius: radius-sm
+  UPPERCASE + letter-spacing: 0.08em
+
+  .free:   background green-dim,  color green-500
+  .premium: background orange-dim, color orange-500
+  .kine:   background rgba(168,178,216,0.12), color slate-300
+
+Pill (metadata)
+  font: sans 12px 400
+  padding: 4px 12px
+  border-radius: radius-pill
+  border: 1px solid (couleur correspondante à 0.3 opacity)
+```
+
+### Cartes
+
+```
+CardDefault
+  background: navy-800
+  border: 1px solid border-dim
+  border-radius: radius-lg
+  padding: 16px
+
+CardAccent (CTA, prochaine séance)
+  background: rgba(0,200,150,0.05)
+  border: 1.5px solid green-border
+  border-radius: radius-lg
+
+CardTip (conseil kiné)
+  background: orange-dim
+  border-left: 3px solid orange-500
+  border-radius: 0 radius-lg radius-lg 0
+  NE PAS arrondir le côté gauche (border-left unique)
+  Structure: icône 💡 + texte + signature "— Prénom, kiné"
+
+CardProgram
+  border-radius: radius-xl
+  overflow: hidden
+  Thumbnail: 120px height, gradient navy-700→navy-600
+  Body: padding 14px
+  Toujours afficher: progression bar + "X/12 séances"
+```
+
+### Timer
+
+```
+Timer (composant le plus critique de l'app)
+  font: mono 80–100px 500
+  text-align: center
+
+  État effort normal (>10s):
+    color: green-500
+
+  État urgence (<10s):
+    color: red-500
+    animation: pulse subtil (scale 1→1.02→1, 1s infinite)
+
+  Label sous le chiffre:
+    font: mono 14px 400
+    color: slate-400
+    letter-spacing: 0.1em
+    text: "SECONDES"
+
+  Contexte repos:
+    color: slate-300 (pas de vert, signal visuel de repos)
+```
+
+### Progress Bar
+
+```
+ProgressBar
+  track: background rgba(168,178,216,0.12), height 4px, border-radius pill
+  fill: background green-500, border-radius pill
+  
+  Variante séance (épaisseur réduite):
+    height: 3px
+
+  Variante programme:
+    height: 4px
+    Afficher le % à droite en mono 11px green-500
+
+  Animation: transition width 300ms ease
+```
+
+### Feedback ressenti
+
+```
+FeedbackButton
+  width: flex (3 boutons égaux)
+  height: 72px
+  border-radius: radius-lg
+  background: navy-800
+  border: 1px solid border-dim
+  flex-direction: column
+  gap: 4px
+
+  Emoji: 28px
+  Label: sans 12px slate-400
+
+  État sélectionné:
+    border: 1.5px solid green-500
+    background: green-dim
+```
+
+### Streak hebdomadaire
+
+```
+StreakDot
+  width: 32px
+  height: 32px
+  border-radius: 50%
+
+  .done:  background rgba(0,200,150,0.15)  → afficher ✓
+  .today: background green-500             → afficher ✓
+  .empty: background rgba(168,178,216,0.06), border 1px border-dim
+
+Label jour: mono 10px slate-400, centré sous chaque dot
+```
+
+---
+
+## 7. Écran séance — règles spéciales
+
+L'écran séance est le plus critique de l'app. Il doit être utilisable **les mains
+sur les genoux, en sueur, à 2 mètres de l'écran**. Chaque décision de design doit
+passer ce test.
+
+### Architecture visuelle
+
+```
+[Vidéo plein écran en boucle — fond de tout l'écran]
+  ↓ Gradient top navy→transparent (40% opacité, 100px height)
+    → Contrôles pause/audio en overlay
+    → Indicateur exercice X/8 centré
+  ↓ Zone centrale nette (pas de gradient — l'utilisateur voit le mouvement)
+  ↓ Gradient bottom transparent→navy (70% opacité, 220px height)
+    → Timer géant centré
+    → Progress bar
+    → Tip card conseil kiné
+```
+
+### Transitions séance
+
+```
+Effort → Repos:
+  Fond passe de vidéo plein écran → navy-800 uni
+  Transition: fade 300ms
+  Vibration haptique légère (si disponible)
+  Le repos a une identité visuelle différente (pas de vidéo, couleur unie)
+
+Repos → Effort:
+  Countdown audio "3... 2... 1..."
+  Vibration haptique + transition fade
+
+Exercice suivant pendant le repos:
+  Afficher un thumbnail 56×56px du prochain exercice
+  Nom en sans 14px 500
+  Label "PROCHAIN EXERCICE" en mono 11px slate-400
+```
+
+### Phase repos
+
+L'écran repos doit être **visuellement différent** de l'écran effort.
+
+- Fond : `navy-800` uni (plus de vidéo plein écran)
+- Timer couleur : `slate-300` (pas de vert — c'est le repos)
+- Mot "REPOS" en mono 13px slate-400, letter-spacing 0.15em
+- Aperçu prochain exercice centré
+
+---
+
+## 8. Navigation
+
+```
+Tab Bar (5 onglets, fixé en bas)
+  height: 56px + safe area inset
+  background: navy-800
+  border-top: 1px solid border-dim
+
+  Onglets:
+    - Accueil (home icon)
+    - Programmes (grid icon)
+    - Minuteur (timer icon)
+    - Progression (chart icon)
+    - Profil (person icon)
+
+  Onglet actif: icône green-500 + label green-500
+  Onglet inactif: icône slate-400 + label slate-400
+
+  Font label: sans 11px 400
+  Icon size: 22×22px
+  Touch target: 44×44px minimum
+```
+
+---
+
+## 9. Animations & micro-interactions
+
+```
+FadeIn:
+  opacity: 0 → 1
+  duration: 300ms
+  easing: ease
+
+SlideUp (bottom sheet, modal):
+  translateY(100%) → 0
+  duration: 400ms
+  easing: cubic-bezier(0.4, 0, 0.2, 1)
+
+Pulse (CTA bouton, timer urgence):
+  scale: 1 → 1.02 → 1
+  duration: 2s
+  infinite, ease-in-out
+
+Bounce (célébration fin de séance):
+  scale: 0.5 → 1.05 → 0.98 → 1
+  duration: 600ms
+  easing: spring
+
+StaggerList (items qui apparaissent en séquence):
+  Délai: 100ms entre chaque item
+  Chaque item: FadeIn + translateY(12px→0)
+
+ScalePress (tous les boutons):
+  active: scale(0.97)
+  duration: 100ms
+```
+
+**Règle d'or animations :** Une animation bien exécutée au chargement d'écran
+vaut mieux que des micro-interactions dispersées partout.
+
+---
+
+## 10. Paywall — règles de design conversion
+
+```
+Structure obligatoire du paywall:
+  1. Célébration des accomplissements (TOUJOURS en premier)
+     → Font serif italic, emoji, stats concrètes
+  2. Valeur du contenu débloqué (liste concrète)
+  3. Pricing transparent (pas de dark patterns)
+     → "Essai gratuit 7 jours · puis 24,99€/an · soit 2,08€/mois"
+  4. CTA principal (PrimaryButton full-width)
+  5. Réassurance ("Annulation facile à tout moment")
+  6. Alternative gratuite visible (GhostButton ou lien)
+
+  Couleur encadré pricing: CardAccent (vert)
+  Bouton fermeture: TOUJOURS visible en haut à gauche
+  Pas de compte à rebours fictif, pas de stock limité : anti dark patterns
+```
+
+---
+
+## 11. Accessibilité
+
+```
+Contraste texte:
+  Texte primaire (#E6F1FF) sur navy-900 → ratio 15:1 ✓
+  Texte secondaire (#A8B2D8) sur navy-900 → ratio 7:1 ✓
+  Vert (#00C896) sur navy-900 → ratio 8:1 ✓
+  Tous conformes WCAG AA (4.5:1 minimum requis)
+
+Touch targets:
+  Minimum 44×44px pour TOUS les éléments interactifs
+  Espacement minimum 8px entre deux éléments interactifs adjacents
+
+Timer:
+  La couleur n'est pas le seul signal d'urgence
+  Ajouter aussi: pulse animation + vibration haptique + signal audio
+
+Audio:
+  Toujours proposer une alternative visuelle à chaque signal audio
+  Le toggle audio est accessible en 1 tap depuis l'écran séance
+```
+
+---
+
+## 12. Tokens React Native / Expo
+
+```typescript
+// design-tokens.ts
+export const colors = {
+  // Navy
+  navy900: '#0D1B2A',
+  navy800: '#112240',
+  navy700: '#1A3050',
+  navy600: '#243C5E',
+
+  // Green
+  green500: '#00C896',
+  green600: '#00A67C',
+  green700: '#00875F',
+  greenDim: 'rgba(0,200,150,0.12)',
+  greenBorder: 'rgba(0,200,150,0.35)',
+
+  // Text
+  white100: '#E6F1FF',
+  slate300: '#A8B2D8',
+  slate400: '#8892B0',
+
+  // Borders
+  borderDim: 'rgba(168,178,216,0.15)',
+  borderHover: 'rgba(168,178,216,0.25)',
+
+  // Orange (tip/kine only)
+  orange500: '#FF8A5C',
+  orange600: '#E06A3C',
+  orangeDim: 'rgba(255,138,92,0.12)',
+
+  // Semantic
+  red500: '#FF4444', // timer urgence ONLY
+} as const
+
+export const spacing = {
+  1: 4,
+  2: 8,
+  3: 12,
+  4: 16,
+  6: 24,
+  8: 32,
+  12: 48,
+  16: 64,
+} as const
+
+export const radius = {
+  sm: 4,
+  md: 8,
+  lg: 12,
+  xl: 16,
+  pill: 9999,
+} as const
+
+export const fontSizes = {
+  caption: 12,
+  label: 13,
+  body: 15,
+  heading2: 18,
+  heading1: 22,
+  display: 28,
+  timer: 88, // taille par défaut du timer
+} as const
+
+export const timerThreshold = 10 // secondes — passage vert → rouge
+```
+
+---
+
+## Checklist avant livraison d'un écran
+
+- [ ] Fond `navy-900` utilisé comme base
+- [ ] Aucun shadow/élévation — différenciation par couleur uniquement
+- [ ] Tous les touch targets ≥ 44×44px
+- [ ] Le vert n'est utilisé que pour des actions ou validations
+- [ ] L'orange n'est utilisé que pour des conseils kiné ou alertes positives
+- [ ] Le rouge n'apparaît que sur le timer en urgence
+- [ ] Timer ≥ 80px de haut sur l'écran séance
+- [ ] Vidéo plein écran sur l'écran séance (pas un bloc vidéo)
+- [ ] Gradients top + bottom sur l'écran séance pour la lisibilité
+- [ ] Phase repos visuellement différente de la phase effort
+- [ ] Paywall : célébration en premier, alternative gratuite visible
+- [ ] Typographie : serif pour les moments émotionnels, mono pour les données
--- a/.claude/skills/gitnexus/gitnexus-cli/SKILL.md
+++ b/.claude/skills/gitnexus/gitnexus-cli/SKILL.md
@@ -0,0 +1,82 @@
+---
+name: gitnexus-cli
+description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\""
+---
+
+# GitNexus CLI Commands
+
+All commands work via `npx` — no global install required.
+
+## Commands
+
+### analyze — Build or refresh the index
+
+```bash
+npx gitnexus analyze
+```
+
+Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.
+
+| Flag           | Effect                                                           |
+| -------------- | ---------------------------------------------------------------- |
+| `--force`      | Force full re-index even if up to date                           |
+| `--embeddings` | Enable embedding generation for semantic search (off by default) |
+
+**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
+
+### status — Check index freshness
+
+```bash
+npx gitnexus status
+```
+
+Shows whether the current repo has a GitNexus index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed.
+
+### clean — Delete the index
+
+```bash
+npx gitnexus clean
+```
+
+Deletes the `.gitnexus/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing GitNexus from a project.
+
+| Flag      | Effect                                            |
+| --------- | ------------------------------------------------- |
+| `--force` | Skip confirmation prompt                          |
+| `--all`   | Clean all indexed repos, not just the current one |
+
+### wiki — Generate documentation from the graph
+
+```bash
+npx gitnexus wiki
+```
+
+Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
+
+| Flag                | Effect                                    |
+| ------------------- | ----------------------------------------- |
+| `--force`           | Force full regeneration                   |
+| `--model <model>`   | LLM model (default: minimax/minimax-m2.5) |
+| `--base-url <url>`  | LLM API base URL                          |
+| `--api-key <key>`   | LLM API key                               |
+| `--concurrency <n>` | Parallel LLM calls (default: 3)           |
+| `--gist`            | Publish wiki as a public GitHub Gist      |
+
+### list — Show all indexed repos
+
+```bash
+npx gitnexus list
+```
+
+Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
+
+## After Indexing
+
+1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded
+2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task
+
+## Troubleshooting
+
+- **"Not inside a git repository"**: Run from a directory inside a git repo
+- **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
+- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding
--- a/.claude/skills/gitnexus/gitnexus-debugging/SKILL.md
+++ b/.claude/skills/gitnexus/gitnexus-debugging/SKILL.md
@@ -0,0 +1,89 @@
+---
+name: gitnexus-debugging
+description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
+---
+
+# Debugging with GitNexus
+
+## When to Use
+
+- "Why is this function failing?"
+- "Trace where this error comes from"
+- "Who calls this method?"
+- "This endpoint returns 500"
+- Investigating bugs, errors, or unexpected behavior
+
+## Workflow
+
+```
+1. gitnexus_query({query: "<error or symptom>"})            → Find related execution flows
+2. gitnexus_context({name: "<suspect>"})                    → See callers/callees/processes
+3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
+4. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] Understand the symptom (error message, unexpected behavior)
+- [ ] gitnexus_query for error text or related code
+- [ ] Identify the suspect function from returned processes
+- [ ] gitnexus_context to see callers and callees
+- [ ] Trace execution flow via process resource if applicable
+- [ ] gitnexus_cypher for custom call chain traces if needed
+- [ ] Read source files to confirm root cause
+```
+
+## Debugging Patterns
+
+| Symptom              | GitNexus Approach                                          |
+| -------------------- | ---------------------------------------------------------- |
+| Error message        | `gitnexus_query` for error text → `context` on throw sites |
+| Wrong return value   | `context` on the function → trace callees for data flow    |
+| Intermittent failure | `context` → look for external calls, async deps            |
+| Performance issue    | `context` → find symbols with many callers (hot paths)     |
+| Recent regression    | `detect_changes` to see what your changes affect           |
+
+## Tools
+
+**gitnexus_query** — find code related to error:
+
+```
+gitnexus_query({query: "payment validation error"})
+→ Processes: CheckoutFlow, ErrorHandling
+→ Symbols: validatePayment, handlePaymentError, PaymentException
+```
+
+**gitnexus_context** — full context for a suspect:
+
+```
+gitnexus_context({name: "validatePayment"})
+→ Incoming calls: processCheckout, webhookHandler
+→ Outgoing calls: verifyCard, fetchRates (external API!)
+→ Processes: CheckoutFlow (step 3/7)
+```
+
+**gitnexus_cypher** — custom call chain traces:
+
+```cypher
+MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
+RETURN [n IN nodes(path) | n.name] AS chain
+```
+
+## Example: "Payment endpoint returns 500 intermittently"
+
+```
+1. gitnexus_query({query: "payment error handling"})
+   → Processes: CheckoutFlow, ErrorHandling
+   → Symbols: validatePayment, handlePaymentError
+
+2. gitnexus_context({name: "validatePayment"})
+   → Outgoing calls: verifyCard, fetchRates (external API!)
+
+3. READ gitnexus://repo/my-app/process/CheckoutFlow
+   → Step 3: validatePayment → calls fetchRates (external)
+
+4. Root cause: fetchRates calls external API without proper timeout
+```
--- a/.claude/skills/gitnexus/gitnexus-exploring/SKILL.md
+++ b/.claude/skills/gitnexus/gitnexus-exploring/SKILL.md
@@ -0,0 +1,78 @@
+---
+name: gitnexus-exploring
+description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
+---
+
+# Exploring Codebases with GitNexus
+
+## When to Use
+
+- "How does authentication work?"
+- "What's the project structure?"
+- "Show me the main components"
+- "Where is the database logic?"
+- Understanding code you haven't seen before
+
+## Workflow
+
+```
+1. READ gitnexus://repos                          → Discover indexed repos
+2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
+3. gitnexus_query({query: "<what you want to understand>"})  → Find related execution flows
+4. gitnexus_context({name: "<symbol>"})            → Deep dive on specific symbol
+5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
+```
+
+> If step 2 says "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] READ gitnexus://repo/{name}/context
+- [ ] gitnexus_query for the concept you want to understand
+- [ ] Review returned processes (execution flows)
+- [ ] gitnexus_context on key symbols for callers/callees
+- [ ] READ process resource for full execution traces
+- [ ] Read source files for implementation details
+```
+
+## Resources
+
+| Resource                                | What you get                                            |
+| --------------------------------------- | ------------------------------------------------------- |
+| `gitnexus://repo/{name}/context`        | Stats, staleness warning (~150 tokens)                  |
+| `gitnexus://repo/{name}/clusters`       | All functional areas with cohesion scores (~300 tokens) |
+| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens)              |
+| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens)              |
+
+## Tools
+
+**gitnexus_query** — find execution flows related to a concept:
+
+```
+gitnexus_query({query: "payment processing"})
+→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
+→ Symbols grouped by flow with file locations
+```
+
+**gitnexus_context** — 360-degree view of a symbol:
+
+```
+gitnexus_context({name: "validateUser"})
+→ Incoming calls: loginHandler, apiMiddleware
+→ Outgoing calls: checkToken, getUserById
+→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
+```
+
+## Example: "How does payment processing work?"
+
+```
+1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
+2. gitnexus_query({query: "payment processing"})
+   → CheckoutFlow: processPayment → validateCard → chargeStripe
+   → RefundFlow: initiateRefund → calculateRefund → processRefund
+3. gitnexus_context({name: "processPayment"})
+   → Incoming: checkoutHandler, webhookHandler
+   → Outgoing: validateCard, chargeStripe, saveTransaction
+4. Read src/payments/processor.ts for implementation details
+```
--- a/.claude/skills/gitnexus/gitnexus-guide/SKILL.md
+++ b/.claude/skills/gitnexus/gitnexus-guide/SKILL.md
@@ -0,0 +1,64 @@
+---
+name: gitnexus-guide
+description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\""
+---
+
+# GitNexus Guide
+
+Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema.
+
+## Always Start Here
+
+For any task involving code understanding, debugging, impact analysis, or refactoring:
+
+1. **Read `gitnexus://repo/{name}/context`** — codebase overview + check index freshness
+2. **Match your task to a skill below** and **read that skill file**
+3. **Follow the skill's workflow and checklist**
+
+> If step 1 warns the index is stale, run `npx gitnexus analyze` in the terminal first.
+
+## Skills
+
+| Task                                         | Skill to read       |
+| -------------------------------------------- | ------------------- |
+| Understand architecture / "How does X work?" | `gitnexus-exploring`         |
+| Blast radius / "What breaks if I change X?"  | `gitnexus-impact-analysis`   |
+| Trace bugs / "Why is X failing?"             | `gitnexus-debugging`         |
+| Rename / extract / split / refactor          | `gitnexus-refactoring`       |
+| Tools, resources, schema reference           | `gitnexus-guide` (this file) |
+| Index, status, clean, wiki CLI commands      | `gitnexus-cli`               |
+
+## Tools Reference
+
+| Tool             | What it gives you                                                        |
+| ---------------- | ------------------------------------------------------------------------ |
+| `query`          | Process-grouped code intelligence — execution flows related to a concept |
+| `context`        | 360-degree symbol view — categorized refs, processes it participates in  |
+| `impact`         | Symbol blast radius — what breaks at depth 1/2/3 with confidence         |
+| `detect_changes` | Git-diff impact — what do your current changes affect                    |
+| `rename`         | Multi-file coordinated rename with confidence-tagged edits               |
+| `cypher`         | Raw graph queries (read `gitnexus://repo/{name}/schema` first)           |
+| `list_repos`     | Discover indexed repos                                                   |
+
+## Resources Reference
+
+Lightweight reads (~100-500 tokens) for navigation:
+
+| Resource                                       | Content                                   |
+| ---------------------------------------------- | ----------------------------------------- |
+| `gitnexus://repo/{name}/context`               | Stats, staleness check                    |
+| `gitnexus://repo/{name}/clusters`              | All functional areas with cohesion scores |
+| `gitnexus://repo/{name}/cluster/{clusterName}` | Area members                              |
+| `gitnexus://repo/{name}/processes`             | All execution flows                       |
+| `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace                        |
+| `gitnexus://repo/{name}/schema`                | Graph schema for Cypher                   |
+
+## Graph Schema
+
+**Nodes:** File, Function, Class, Interface, Method, Community, Process
+**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
+RETURN caller.name, caller.filePath
+```
--- a/.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md
+++ b/.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md
@@ -0,0 +1,97 @@
+---
+name: gitnexus-impact-analysis
+description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\""
+---
+
+# Impact Analysis with GitNexus
+
+## When to Use
+
+- "Is it safe to change this function?"
+- "What will break if I modify X?"
+- "Show me the blast radius"
+- "Who uses this code?"
+- Before making non-trivial code changes
+- Before committing — to understand what your changes affect
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → What depends on this
+2. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
+3. gitnexus_detect_changes()                               → Map current git changes to affected flows
+4. Assess risk and report to user
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] gitnexus_impact({target, direction: "upstream"}) to find dependents
+- [ ] Review d=1 items first (these WILL BREAK)
+- [ ] Check high-confidence (>0.8) dependencies
+- [ ] READ processes to check affected execution flows
+- [ ] gitnexus_detect_changes() for pre-commit check
+- [ ] Assess risk level and report to user
+```
+
+## Understanding Output
+
+| Depth | Risk Level       | Meaning                  |
+| ----- | ---------------- | ------------------------ |
+| d=1   | **WILL BREAK**   | Direct callers/importers |
+| d=2   | LIKELY AFFECTED  | Indirect dependencies    |
+| d=3   | MAY NEED TESTING | Transitive effects       |
+
+## Risk Assessment
+
+| Affected                       | Risk     |
+| ------------------------------ | -------- |
+| <5 symbols, few processes      | LOW      |
+| 5-15 symbols, 2-5 processes    | MEDIUM   |
+| >15 symbols or many processes  | HIGH     |
+| Critical path (auth, payments) | CRITICAL |
+
+## Tools
+
+**gitnexus_impact** — the primary tool for symbol blast radius:
+
+```
+gitnexus_impact({
+  target: "validateUser",
+  direction: "upstream",
+  minConfidence: 0.8,
+  maxDepth: 3
+})
+
+→ d=1 (WILL BREAK):
+  - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
+  - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
+```
+
+**gitnexus_detect_changes** — git-diff based impact analysis:
+
+```
+gitnexus_detect_changes({scope: "staged"})
+
+→ Changed: 5 symbols in 3 files
+→ Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline
+→ Risk: MEDIUM
+```
+
+## Example: "What breaks if I change validateUser?"
+
+```
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+   → d=1: loginHandler, apiMiddleware (WILL BREAK)
+   → d=2: authRouter, sessionManager (LIKELY AFFECTED)
+
+2. READ gitnexus://repo/my-app/processes
+   → LoginFlow and TokenRefresh touch validateUser
+
+3. Risk: 2 direct callers, 2 processes = MEDIUM
+```
--- a/.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md
+++ b/.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md
@@ -0,0 +1,121 @@
+---
+name: gitnexus-refactoring
+description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\""
+---
+
+# Refactoring with GitNexus
+
+## When to Use
+
+- "Rename this function safely"
+- "Extract this into a module"
+- "Split this service"
+- "Move this to a new file"
+- Any task involving renaming, extracting, splitting, or restructuring code
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → Map all dependents
+2. gitnexus_query({query: "X"})                            → Find execution flows involving X
+3. gitnexus_context({name: "X"})                           → See all incoming/outgoing refs
+4. Plan update order: interfaces → implementations → callers → tests
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklists
+
+### Rename Symbol
+
+```
+- [ ] gitnexus_rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
+- [ ] Review graph edits (high confidence) and ast_search edits (review carefully)
+- [ ] If satisfied: gitnexus_rename({..., dry_run: false}) — apply edits
+- [ ] gitnexus_detect_changes() — verify only expected files changed
+- [ ] Run tests for affected processes
+```
+
+### Extract Module
+
+```
+- [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs
+- [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers
+- [ ] Define new module interface
+- [ ] Extract code, update imports
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+### Split Function/Service
+
+```
+- [ ] gitnexus_context({name: target}) — understand all callees
+- [ ] Group callees by responsibility
+- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update
+- [ ] Create new functions/services
+- [ ] Update callers
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+## Tools
+
+**gitnexus_rename** — automated multi-file rename:
+
+```
+gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+→ 12 edits across 8 files
+→ 10 graph edits (high confidence), 2 ast_search edits (review)
+→ Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
+```
+
+**gitnexus_impact** — map all dependents first:
+
+```
+gitnexus_impact({target: "validateUser", direction: "upstream"})
+→ d=1: loginHandler, apiMiddleware, testUtils
+→ Affected Processes: LoginFlow, TokenRefresh
+```
+
+**gitnexus_detect_changes** — verify your changes after refactoring:
+
+```
+gitnexus_detect_changes({scope: "all"})
+→ Changed: 8 files, 12 symbols
+→ Affected processes: LoginFlow, TokenRefresh
+→ Risk: MEDIUM
+```
+
+**gitnexus_cypher** — custom reference queries:
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
+RETURN caller.name, caller.filePath ORDER BY caller.filePath
+```
+
+## Risk Rules
+
+| Risk Factor         | Mitigation                                |
+| ------------------- | ----------------------------------------- |
+| Many callers (>5)   | Use gitnexus_rename for automated updates |
+| Cross-area refs     | Use detect_changes after to verify scope  |
+| String/dynamic refs | gitnexus_query to find them               |
+| External/public API | Version and deprecate properly            |
+
+## Example: Rename `validateUser` to `authenticateUser`
+
+```
+1. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+   → 12 edits: 10 graph (safe), 2 ast_search (review)
+   → Files: validator.ts, login.ts, middleware.ts, config.json...
+
+2. Review ast_search edits (config.json: dynamic reference!)
+
+3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
+   → Applied 12 edits across 8 files
+
+4. gitnexus_detect_changes({scope: "all"})
+   → Affected: LoginFlow, TokenRefresh
+   → Risk: MEDIUM — run tests for these flows
+```