# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Nature du dépôt

Monorepo d'**outils internes** hétérogènes (langages et runtimes différents selon l'outil). Ce n'est pas une application : il n'y a pas de build global, pas de test suite globale, pas de dépendance partagée implicite entre outils. Chaque outil est autonome et doit pouvoir être exécuté sans que les autres soient installés.

## Règle d'organisation — non négociable

- **Un outil = un dossier** sous `tools/<nom-outil>/`. Jamais de script orphelin à la racine.
- **`TMP/`** = tout ce qui n'est pas définitif : prototypes, expérimentations, scratch, sorties de test. Rien de `TMP/` n'est considéré comme stable ou référençable. Un outil promu depuis `TMP/` est déplacé dans `tools/`, pas copié.
- Chaque `tools/<nom-outil>/` est self-contained : son `README.md`, ses dépendances déclarées, son point d'entrée, ses fichiers de config. Pas de fichier d'un outil qui vit ailleurs.
- La racine ne contient que : le CLI interactif de sélection d'outils, la config partagée du dépôt, et `tools/` / `TMP/`.

## Runtimes & outillage

- **`mise`** est le gestionnaire de runtimes par défaut. Chaque outil qui a besoin d'une version épinglée porte son propre `mise.toml`.
- **Python → `uv`** exclusivement (`uv run`, `uv sync`, `uv add`). Jamais `pip` / `venv` / `poetry` à la main.
- Les binaires système utilisés par les outils (`brew`, `fish`, `pg_dump`, …) sont supposés présents sur la machine cible mais doivent être **vérifiés au démarrage** de l'outil, avec un message d'erreur explicite s'ils manquent — ces outils tournent sur des machines en cours de réinstallation, où rien n'est garanti.

## Environnement machine de référence (vérifié)

Contexte utile aux outils qui touchent au système local :

- macOS arm64, Homebrew dans `/opt/homebrew`
- Shell : `fish` (`/opt/homebrew/bin/fish`)
- `mise` dans `~/.local/bin/mise`, `uv` installé via mise
- PostgreSQL **18** (Homebrew), service `postgresql@18` géré par `brew services`, actuellement `started`

## Git

Le flow (main = prod, dev = intégration, branches éphémères `feature/` / `fix/`, Conventional Commits) vient des règles globales de l'utilisateur et s'applique ici. **Le dépôt n'a pour l'instant que `main`** : créer `dev` avant tout travail d'implémentation.