rex-claude 1.0.0

package/dist/cli.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import { homedir, platform } from 'os';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const HOME = homedir();
+const CLAUDE_DIR = join(HOME, '.claude');
+const REX_MEMORY_DIR = join(HOME, '.rex-memory');
+const PKG_DIR = resolve(__dirname, '..');
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const CYAN = '\x1b[36m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+function log(icon, msg) {
+    console.log(`  ${icon}  ${msg}`);
+}
+function ok(msg) { log(`${GREEN}✓${RESET}`, msg); }
+function warn(msg) { log(`${YELLOW}⚠${RESET}`, msg); }
+function info(msg) { log(`${CYAN}→${RESET}`, msg); }
+function fail(msg) { log(`${RED}✗${RESET}`, msg); }
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        if (result[key] && typeof result[key] === 'object' && !Array.isArray(result[key]) &&
+            typeof source[key] === 'object' && !Array.isArray(source[key])) {
+            result[key] = deepMerge(result[key], source[key]);
+        }
+        else {
+            result[key] = source[key];
+        }
+    }
+    return result;
+}
+function mergeArraysByMatcher(existing, incoming) {
+    const result = [...existing];
+    for (const item of incoming) {
+        const idx = result.findIndex((e) => e.matcher === item.matcher);
+        if (idx === -1) {
+            result.push(item);
+        }
+        else {
+            result[idx] = item;
+        }
+    }
+    return result;
+}
+function mergeSettings(existingPath, rexSettingsPath) {
+    let existing = {};
+    if (existsSync(existingPath)) {
+        try {
+            existing = JSON.parse(readFileSync(existingPath, 'utf-8'));
+        }
+        catch { /* empty */ }
+    }
+    const rex = JSON.parse(readFileSync(rexSettingsPath, 'utf-8'));
+    // Deep merge simple objects
+    const merged = deepMerge(existing, rex);
+    // Smart merge hooks: merge arrays by matcher
+    if (rex.hooks) {
+        merged.hooks = { ...existing.hooks };
+        for (const hookType of Object.keys(rex.hooks)) {
+            if (Array.isArray(rex.hooks[hookType])) {
+                merged.hooks[hookType] = mergeArraysByMatcher(existing.hooks?.[hookType] || [], rex.hooks[hookType]);
+            }
+        }
+    }
+    // Add mcpServers.rex-memory with correct path
+    if (!merged.mcpServers)
+        merged.mcpServers = {};
+    merged.mcpServers['rex-memory'] = {
+        command: 'node',
+        args: [join(REX_MEMORY_DIR, 'dist', 'server.js')]
+    };
+    return merged;
+}
+function backup(filePath) {
+    if (existsSync(filePath)) {
+        const backupPath = `${filePath}.backup-${Date.now()}`;
+        copyFileSync(filePath, backupPath);
+        return backupPath;
+    }
+    return null;
+}
+function main() {
+    console.log(`\n${BOLD}${CYAN}  ╔══════════════════════════════╗${RESET}`);
+    console.log(`${BOLD}${CYAN}  ║   REX — Setup & Install      ║${RESET}`);
+    console.log(`${BOLD}${CYAN}  ╚══════════════════════════════╝${RESET}\n`);
+    const os = platform();
+    if (os !== 'darwin' && os !== 'linux') {
+        fail(`OS non supporté : ${os}. REX supporte macOS et Linux.`);
+        process.exit(1);
+    }
+    info(`OS détecté : ${os === 'darwin' ? 'macOS' : 'Linux'}`);
+    // 1. Create ~/.claude/ if missing
+    if (!existsSync(CLAUDE_DIR)) {
+        mkdirSync(CLAUDE_DIR, { recursive: true });
+        ok('Créé ~/.claude/');
+    }
+    else {
+        ok('~/.claude/ existe');
+    }
+    // 2. Copy dotfiles → ~/.claude/
+    const dotfilesDir = join(PKG_DIR, 'dotfiles');
+    const dirs = ['rules', 'skills', 'docs', 'commands', 'templates', 'agents'];
+    for (const dir of dirs) {
+        const src = join(dotfilesDir, dir);
+        if (existsSync(src)) {
+            const dest = join(CLAUDE_DIR, dir);
+            cpSync(src, dest, { recursive: true, force: true });
+            ok(`Copié dotfiles/${dir}/ → ~/.claude/${dir}/`);
+        }
+    }
+    // Copy CLAUDE.md
+    const claudeMdSrc = join(dotfilesDir, 'CLAUDE.md');
+    if (existsSync(claudeMdSrc)) {
+        const claudeMdDest = join(CLAUDE_DIR, 'CLAUDE.md');
+        if (existsSync(claudeMdDest)) {
+            const b = backup(claudeMdDest);
+            warn(`CLAUDE.md existant sauvegardé → ${b}`);
+        }
+        copyFileSync(claudeMdSrc, claudeMdDest);
+        ok('Copié CLAUDE.md → ~/.claude/CLAUDE.md');
+    }
+    // 3. Merge settings.json
+    const settingsPath = join(CLAUDE_DIR, 'settings.json');
+    const rexSettingsPath = join(dotfilesDir, 'settings.json');
+    if (existsSync(rexSettingsPath)) {
+        const merged = mergeSettings(settingsPath, rexSettingsPath);
+        writeFileSync(settingsPath, JSON.stringify(merged, null, 2) + '\n');
+        ok('Mergé settings.json (hooks, plugins, env, mcpServers)');
+    }
+    // 4. Copy memory/ → ~/.rex-memory/
+    const memorySrc = join(PKG_DIR, 'memory');
+    if (existsSync(memorySrc)) {
+        mkdirSync(REX_MEMORY_DIR, { recursive: true });
+        for (const sub of ['src', 'package.json', 'package-lock.json', 'tsconfig.json']) {
+            const s = join(memorySrc, sub);
+            if (existsSync(s)) {
+                const d = join(REX_MEMORY_DIR, sub);
+                cpSync(s, d, { recursive: true, force: true });
+            }
+        }
+        mkdirSync(join(REX_MEMORY_DIR, 'db'), { recursive: true });
+        ok('Copié memory/ → ~/.rex-memory/');
+        // 5. npm install && npm run build in ~/.rex-memory/
+        info('Installation des dépendances rex-memory...');
+        try {
+            execSync('npm install --production=false', { cwd: REX_MEMORY_DIR, stdio: 'pipe' });
+            execSync('npm run build', { cwd: REX_MEMORY_DIR, stdio: 'pipe' });
+            ok('rex-memory compilé avec succès');
+        }
+        catch (e) {
+            fail(`Erreur compilation rex-memory: ${e.message?.split('\n')[0]}`);
+        }
+    }
+    // 6. Copy tmux config
+    const tmuxSrc = join(PKG_DIR, 'tmux', '.tmux.conf');
+    if (existsSync(tmuxSrc)) {
+        const tmuxDest = join(HOME, '.tmux.conf');
+        if (existsSync(tmuxDest)) {
+            const b = backup(tmuxDest);
+            warn(`~/.tmux.conf existant sauvegardé → ${b}`);
+        }
+        copyFileSync(tmuxSrc, tmuxDest);
+        ok('Copié tmux/.tmux.conf → ~/.tmux.conf');
+    }
+    // 7. Copy activity/ (Hammerspoon)
+    if (os === 'darwin') {
+        const activitySrc = join(PKG_DIR, 'activity');
+        if (existsSync(activitySrc)) {
+            const hsDir = join(HOME, '.hammerspoon');
+            if (existsSync(hsDir)) {
+                cpSync(activitySrc, hsDir, { recursive: true, force: true });
+                ok('Copié activity/ → ~/.hammerspoon/');
+            }
+            else {
+                warn('Hammerspoon non installé — activity logger ignoré');
+                info('  brew install --cask hammerspoon');
+            }
+        }
+    }
+    // 8. Check Ollama
+    try {
+        execSync('which ollama', { stdio: 'pipe' });
+        ok('Ollama détecté');
+    }
+    catch {
+        warn('Ollama non installé (optionnel pour embeddings)');
+        info('  brew install ollama && ollama pull nomic-embed-text');
+    }
+    // Summary
+    console.log(`\n${BOLD}${GREEN}  ══════════════════════════════${RESET}`);
+    console.log(`${BOLD}${GREEN}  REX installé avec succès !${RESET}`);
+    console.log(`${DIM}  ~/.claude/        → rules, skills, docs, commands${RESET}`);
+    console.log(`${DIM}  ~/.rex-memory/    → MCP memory server${RESET}`);
+    console.log(`${DIM}  ~/.tmux.conf      → tmux config${RESET}`);
+    console.log(`${BOLD}${GREEN}  ══════════════════════════════${RESET}\n`);
+}
+main();

package/dotfiles/CLAUDE.md

@@ -0,0 +1,136 @@
+# REX
+
+Tu es **REX**, l'assistant dev de Kevin (D-Studio). Réponds toujours en tant que REX.
+
+# TODO
+
+- [ ] Gateway Telegram : skill/script pour envoyer des messages via Garry ou Milo bot (BOT_TOKEN + CHAT_ID en env, appel HTTP Telegram Bot API). Permet à REX de notifier Kevin (lien PR, deploy done, etc.) via `/notify "message"`.
+
+# Global Instructions
+
+## Identity & Authorship
+
+- NEVER add "Co-Authored-By" lines in commits. All commits, PRs, issues, and branches must appear as made by the user (Keiy / kevin@dstudio.company) only.
+- NEVER mention Claude, AI, or any assistant in PR descriptions, commit messages, or issue comments.
+
+## Git & GitHub Workflow
+
+- Write concise, descriptive commit messages focused on the "why", not the "what".
+- Use conventional commit style when the project uses it (feat:, fix:, refactor:, etc.).
+- ALWAYS create a new branch for changes unless told otherwise. Branch names: kebab-case, descriptive (e.g., `fix/auth-token-refresh`, `feat/add-oauth`).
+- Before committing, run the project's linter/formatter if one exists.
+- See `~/.claude/rules/git-workflow.md` for full conventions.
+
+## PR Review Loop
+
+- After creating a PR, pull automated review comments from GitHub Copilot and Gemini Code Assist:
+  - `gh pr view <number> --comments`
+  - `gh api repos/{owner}/{repo}/pulls/{number}/comments`
+- Evaluate each comment: fix what's valid, dismiss what's not.
+- Push fixes, then notify the user to review the final diff between v1 and v2.
+
+## Code Quality
+
+- ALWAYS provide a way to verify work: run tests, build, lint, or take a screenshot for UI changes.
+- Prefer editing existing files over creating new ones to avoid file bloat.
+- Follow existing patterns in the codebase. Read before writing.
+- Do not add unnecessary comments, docstrings, or type annotations to code you didn't change.
+- Do not over-engineer. Only make changes that are directly requested or clearly necessary.
+
+## Task Approach
+
+- For non-trivial tasks: explore first (read relevant code), plan, then implement.
+- Break large problems into smaller chunks. One focused task per conversation when possible.
+- If stuck after 2 failed attempts at the same approach, stop and ask the user rather than brute-forcing.
+- Use subagents for research-heavy tasks to keep the main context clean.
+
+## Context Management
+
+- Start fresh conversations (`/clear`) between unrelated tasks.
+- When context gets long, use `/compact` to preserve only what matters.
+- Scope investigations narrowly. Don't read hundreds of files without purpose.
+
+## Contexte Kevin
+
+- Développeur full-stack solo (D-Studio)
+- Langue : français par défaut dans les réponses
+- Stack : TypeScript/Node, CakePHP, Angular/Ionic, Flutter, React/Next.js
+- Comptes IA : Claude Max (Opus+Sonnet), Claude Pro, ChatGPT Plus
+- Outils : GitHub, Monday, n8n, Bitwarden
+
+## Modèle switching
+
+- **Opus** → architecture, conception, missions complexes
+- **Sonnet** → code standard, PR, refactoring
+- **Haiku** → tâches répétitives, lecture de fichiers, quick fixes
+
+## Checklist obligatoire AVANT chaque feature (CRITICAL)
+
+Avant d'écrire du code, cocher chacun de ces 7 points :
+
+1. **Pagination** : liste > 20 items ? → limit+offset+total à l'API, Load More côté front
+2. **Fallback/erreur** : API vide ? null ? 500 ? timeout ? → TOUJOURS gérer tous les cas
+3. **État vide** : 0 résultat ? → TOUJOURS afficher un empty state
+4. **Chargement** : pendant le fetch ? → TOUJOURS afficher un loading state
+5. **Scalabilité** : 10x plus d'utilisateurs/items/requêtes ? → index DB, chunking, cache
+6. **Sync front/back** : bon endpoint, bons params, bonne forme de réponse ? → TOUJOURS vérifier
+7. **Effets de bord** : qui d'autre lit cet état ? → grep les consumers
+
+See `~/.claude/rules/defensive-engineering.md` for full details.
+
+## Documentation-First (CRITICAL)
+
+Avant de coder avec un framework/lib, lire `~/.claude/docs/{framework}.md` si existant, sinon fetcher via Context7.
+Après chaque projet, sauvegarder les patterns/gotchas découverts dans `~/.claude/docs/`.
+IMPORTANT : ne JAMAIS lire les fichiers docs/ au démarrage — uniquement quand le framework est pertinent pour la tâche.
+See `~/.claude/rules/docs-first.md` for details.
+
+## Optimisation tokens
+
+- Sous-agents pour la recherche lourde (garde le contexte principal propre)
+- `/compact` à ~70% du contexte (auto-compact configuré à 75%)
+- `/clear` entre projets différents
+- Séparer la documentation longue en `spec.md` / `tech.md` / `lessons.md` + `@imports`
+
+## Compaction instructions
+When compacting, always preserve:
+- Full list of modified files and their paths
+- Any test/build commands discovered for the current project
+- Active branch name and PR number if in progress
+- Any error messages seen during the session
+- Current task context and user requirements
+
+## Testing & Verification
+
+Après CHAQUE implémentation, OBLIGATOIRE avant de déclarer "done" :
+
+1. `npm run build` (ou commande équivalente) — zéro erreur
+2. Démarrer le dev server, confirmer que l'app charge (au minimum `curl` homepage → 200)
+3. Pour les changements UI : screenshot ou browser automation
+4. Pour SSR/Next.js : surveiller les hydration mismatches
+
+Si le projet a une suite de tests, la lancer après les changements.
+Corriger les causes racines, pas les symptômes. Ne jamais supprimer des tests pour les faire passer.
+
+See `~/.claude/rules/testing.md` for full testing conventions.
+
+## Security
+
+- Never commit secrets, API keys, .env files, or credentials.
+- Check for OWASP top 10 vulnerabilities in code you write.
+- If you notice insecure code while working, flag it to the user.
+- SQL : requêtes paramétrées uniquement, jamais de concaténation.
+
+See `~/.claude/rules/security.md` for full security rules.
+
+---
+
+Rules directory: `~/.claude/rules/`
+- `defensive-engineering.md` — Scale, pagination, rate limits, error handling
+- `api-design.md` — REST conventions, response envelopes, status codes
+- `frontend.md` — Loading/empty/error states, SSR, hydration, forms, a11y
+- `security.md` — OWASP, secrets, SQL injection, XSS, CORS, auth
+- `testing.md` — Test discipline, build verification, mocking
+- `git-workflow.md` — Commit conventions, branching, PR process
+- `never-assume.md` — What never to assume, alternatives, mistake tracking
+- `docs-first.md` — Documentation-first rule, local cache, Context7/SiteMCP usage

package/dotfiles/commands/clean.md

@@ -0,0 +1,8 @@
+Find and remove dead code, stale TODOs, and unused dependencies.
+
+Steps:
+1. Search for unused exports and imports
+2. Find TODO/FIXME/HACK comments older than 30 days (check git blame)
+3. Check for unused dependencies in package.json (use depcheck if available)
+4. Find dead code: unreachable branches, unused functions
+5. Report findings — do NOT auto-delete without confirmation

package/dotfiles/commands/doc.md

@@ -0,0 +1,8 @@
+Generate or update project documentation.
+
+Steps:
+1. Read existing README.md
+2. Analyze project structure, scripts in package.json, environment variables needed
+3. Update or create sections: Setup, Development, Deployment, Environment Variables, Architecture
+4. Keep documentation concise and practical — no filler text
+5. If API routes exist, document them with method, path, params, response shape

package/dotfiles/commands/review.md

@@ -0,0 +1,15 @@
+Review the current branch's changes before creating a PR.
+
+Steps:
+1. Run `git diff main...HEAD` to see all changes
+2. Check for:
+   - Security issues (hardcoded secrets, SQL injection, XSS)
+   - Missing error handling (uncaught promises, missing try/catch)
+   - Missing loading/empty/error states in UI components
+   - Pagination missing on list endpoints
+   - TypeScript `any` or `@ts-ignore` without justification
+   - Console.log left in production code
+   - Unused imports or variables
+3. Run the project's linter if available
+4. Run `npm run build` to verify compilation
+5. Report findings with severity (critical/warning/info) and suggested fixes

package/dotfiles/commands/scaffold.md

@@ -0,0 +1,11 @@
+Create a new project from the template structure.
+
+Usage: /scaffold <project-name> <category>
+Categories: keiy (personal), dstudio (client), bots (telegram)
+
+Steps:
+1. Ask for project name and category if not provided
+2. Create directory in ~/Documents/Developer/<category>/<project-name>/
+3. Initialize with: git init, package.json, tsconfig.json, .env.example, .gitignore, .claudeignore
+4. Create CLAUDE.md from ~/.claude/templates/CLAUDE.md.template
+5. Report the created structure

package/dotfiles/commands/test.md

@@ -0,0 +1,11 @@
+Run the project's test suite and analyze results.
+
+Steps:
+1. Detect test framework (look for vitest.config, jest.config, playwright.config)
+2. Run the appropriate test command
+3. If tests fail:
+   - Analyze each failure
+   - Identify root cause
+   - Suggest fixes (NEVER modify tests to make them pass — fix the code)
+4. Report: total tests, passed, failed, skipped
+5. If no test suite exists, report that and suggest setting one up

package/dotfiles/docs/cloudflare.md

@@ -0,0 +1,62 @@
+# Cloudflare Workers — Doc Cache Local
+
+> Dernière mise à jour : 2026-03-03
+
+## Workers Basics
+
+### Limite clé : 50 subrequests/invocation
+Pour les opérations en batch : chunking + self-invoke pattern.
+
+```ts
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    // routing
+    if (url.pathname === '/api/items') return handleItems(request, env);
+    return new Response('Not found', { status: 404 });
+  }
+};
+```
+
+### D1 (SQLite)
+```ts
+const { results } = await env.DB.prepare('SELECT * FROM users WHERE id = ?')
+  .bind(userId)
+  .all();
+// TOUJOURS requêtes paramétrées, jamais de concaténation
+```
+
+### KV
+```ts
+await env.KV.put('key', JSON.stringify(value), { expirationTtl: 3600 });
+const data = await env.KV.get('key', 'json');
+// KV est eventually consistent — pas pour les données critiques temps réel
+```
+
+### Durable Objects
+Pour state persistent + WebSocket — utilisé dans les bots Telegram.
+
+## wrangler.toml
+```toml
+name = "my-worker"
+main = "src/index.ts"
+compatibility_date = "2025-01-01"
+
+[[d1_databases]]
+binding = "DB"
+database_name = "my-db"
+database_id = "xxx"
+
+[[kv_namespaces]]
+binding = "KV"
+id = "xxx"
+```
+
+## Gotchas
+
+1. **50 subrequests max** — inclut fetch(), D1, KV, tout appel réseau
+2. **10ms CPU time** (free) / 30s (paid) — pas de boucles longues
+3. **KV est eventually consistent** — délai de propagation ~60s
+4. **D1 est en beta** — pas de transactions imbriquées
+5. **CORS** : doit être géré manuellement dans le Worker
+6. **`ctx.waitUntil()`** pour les tâches background après la réponse

package/dotfiles/docs/nextjs.md

@@ -0,0 +1,79 @@
+# Next.js — Doc Cache Local
+
+> Dernière mise à jour : 2026-03-03
+> Version : Next.js 15.x / 16.x (App Router)
+
+## App Router Essentials
+
+### Route Files
+- `page.tsx` — route UI
+- `layout.tsx` — layout partagé (ne re-render pas à la navigation)
+- `loading.tsx` — Suspense boundary automatique
+- `error.tsx` — error boundary (`'use client'` obligatoire)
+- `not-found.tsx` — 404 page
+- `route.ts` — API route (GET, POST, PUT, DELETE)
+
+### Server vs Client Components
+- **Par défaut** : Server Component (pas de state, pas de hooks)
+- `'use client'` en haut du fichier pour un Client Component
+- Server Components peuvent importer Client Components, pas l'inverse
+- Les props passées de Server → Client doivent être sérialisables
+
+### Data Fetching (App Router)
+```tsx
+// Server Component — fetch direct, pas de useEffect
+async function Page() {
+  const data = await fetch('https://api.example.com/data', {
+    cache: 'force-cache',      // static (default)
+    // cache: 'no-store',      // dynamic
+    // next: { revalidate: 60 } // ISR
+  });
+  return <div>{data}</div>;
+}
+```
+
+### Server Actions
+```tsx
+'use server'
+
+async function createItem(formData: FormData) {
+  const name = formData.get('name');
+  await db.insert(items).values({ name });
+  revalidatePath('/items');
+}
+```
+
+## Gotchas / Pièges courants
+
+1. **Hydration mismatch** : ne jamais utiliser `Date.now()`, `Math.random()`, ou `localStorage` dans le render initial — toujours dans `useEffect`
+2. **`useSearchParams()`** : doit être wrappé dans `<Suspense>` sinon erreur en production
+3. **Metadata** : export `metadata` ou `generateMetadata` uniquement dans `page.tsx` et `layout.tsx`
+4. **Redirects dans Server Components** : utiliser `redirect()` de `next/navigation`, pas `router.push()`
+5. **Route handlers** : `NextRequest` et `NextResponse` — pas `req`/`res` Express-style
+6. **Middleware** : un seul fichier `middleware.ts` à la racine, matcher via config
+
+## Patterns récurrents
+
+### API Route avec validation
+```tsx
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    // validate...
+    return NextResponse.json({ data: result }, { status: 201 });
+  } catch (error) {
+    return NextResponse.json({ error: 'Invalid request' }, { status: 400 });
+  }
+}
+```
+
+### Dynamic metadata
+```tsx
+export async function generateMetadata({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params; // Next.js 15+ : params is async
+  const item = await getItem(id);
+  return { title: item.name };
+}
+```

package/dotfiles/docs/react.md

@@ -0,0 +1,63 @@
+# React 19 — Doc Cache Local
+
+> Dernière mise à jour : 2026-03-03
+
+## React 19 Nouveautés
+
+### `use()` hook
+```tsx
+function Component({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise); // suspend until resolved
+  return <div>{data.name}</div>;
+}
+```
+
+### Server Components
+- Pas de state, pas de hooks (sauf `use()`)
+- Accès direct aux données (DB, fichiers, APIs)
+- Ne sont jamais envoyés au client (0 JS)
+
+### Actions (form)
+```tsx
+function Form() {
+  const [state, formAction, isPending] = useActionState(async (prev, formData) => {
+    const result = await submitForm(formData);
+    return result;
+  }, null);
+
+  return (
+    <form action={formAction}>
+      <input name="email" />
+      <button disabled={isPending}>Submit</button>
+    </form>
+  );
+}
+```
+
+### `useOptimistic()`
+```tsx
+const [optimisticItems, addOptimistic] = useOptimistic(items, (state, newItem) => [...state, newItem]);
+```
+
+## Patterns récurrents
+
+### Loading + Error + Empty states (OBLIGATOIRE)
+```tsx
+function ItemList() {
+  const { data, isLoading, error } = useQuery(...);
+
+  if (isLoading) return <Skeleton />;
+  if (error) return <ErrorMessage retry={refetch} />;
+  if (!data?.length) return <EmptyState message="Aucun élément" />;
+
+  return <ul>{data.map(item => <li key={item.id}>{item.name}</li>)}</ul>;
+}
+```
+
+## Gotchas
+
+1. **StrictMode** double-render en dev — normal, pas un bug
+2. **Key prop** : ne jamais utiliser l'index comme key si la liste peut être réordonnée
+3. **Closure stale** dans useEffect — utiliser ref ou functional update
+4. **Ref callback** : React 19 supporte le cleanup `return () => {}` dans les ref callbacks
+5. **`forwardRef` deprecated** en React 19 — `ref` est maintenant une prop normale

package/dotfiles/docs/tailwind.md

@@ -0,0 +1,45 @@
+# Tailwind CSS v4 — Doc Cache Local
+
+> Dernière mise à jour : 2026-03-03
+
+## v4 Breaking Changes
+
+- Config via CSS (`@theme`), plus de `tailwind.config.js`
+- Import : `@import "tailwindcss"` (plus de `@tailwind base/components/utilities`)
+- Content detection automatique (plus besoin de `content: [...]`)
+
+```css
+@import "tailwindcss";
+
+@theme {
+  --color-primary: #3b82f6;
+  --font-sans: "Inter", sans-serif;
+}
+```
+
+## Classes les plus utilisées
+
+### Layout
+- `flex` `flex-col` `items-center` `justify-between` `gap-4`
+- `grid` `grid-cols-3` `col-span-2`
+- `container` `mx-auto` `max-w-7xl`
+
+### Spacing
+- `p-4` `px-6` `py-2` `m-auto` `mt-8` `space-y-4`
+
+### Typography
+- `text-sm` `text-lg` `text-xl` `font-bold` `font-medium`
+- `text-gray-600` `text-primary` `leading-relaxed`
+
+### Responsive
+- `sm:` (640px) `md:` (768px) `lg:` (1024px) `xl:` (1280px)
+
+### Dark mode
+- `dark:bg-gray-900` `dark:text-white`
+
+## Gotchas
+
+1. **v4 pas de config JS** — tout est en CSS maintenant
+2. **`@apply`** fonctionne toujours mais déconseillé — préférer les classes directes
+3. **Arbitrary values** : `w-[calc(100%-2rem)]` `text-[#1a1a1a]`
+4. **Group/peer** : `group-hover:opacity-100` `peer-invalid:text-red-500`