Files

185 lines
23 KiB
Markdown
Raw Permalink Normal View History

# Support par l'API Claude : plan de construction
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**But** : une page locale `support` où Marc colle le mail d'un client ; deux clients de l'API Claude (support, analyste) produisent un PDF de diapositives qui répond à la question, et Marc les fait corriger jusqu'à un PDF qu'il peut envoyer.
**Architecture** : un serveur de la bibliothèque standard (`ThreadingHTTPServer`, 127.0.0.1) sert la page et tient une séance en mémoire. Chaque agent est un historique de messages, seulement ajouté, et une boucle d'outils écrite à la main sur `client.beta.messages.stream`. Les outils lancent des copies des détecteurs, des outils de lecture, des scripts de figures et de la fabrique Typst, toutes dans `API/tools/`. LangSmith trace chaque appel.
**Technique** : Python 3.14, `anthropic`, `langsmith`, `matplotlib` dans `API/.venv` ; Typst ≥ 0.14 (`~/.local/bin/typst`), `pdftotext`, `pdftoppm`.
**Spec** : `API/docs/2026-11-05-support-api-design.md` (validé par Marc le 2026-11-05).
## Contraintes globales
- Tout dans `API/` ; aucun fichier de `API/` ne lit `.claude/`, `agent-tools/`, `detectors/` ni `labeling/` à l'exécution. Seule dépendance extérieure : le dossier des données, réglage `AIMSIGHT_DATA` (défaut `<API>/../data`).
- Modèle `claude-opus-5-5` pour les deux agents, `thinking={"type": "adaptive"}`, `output_config={"effort": ...}` explicite : support `"medium"`, analyste `"high"`. `betas=["server-side-fallback-2026-07-01"]`, `fallbacks="default"`. Streaming, `max_tokens=64000`, `.get_final_message()`.
- Tarifs pour le coût (Opus 5.5, $ par million de tokens) : entrée 4,00 ; sortie 20,00 ; lecture du cache 0,20 ; écriture du cache 5,00.
- Historique **seulement ajouté** : jamais réécrit ni tronqué (le modèle refuse un historique édité qui contient ses blocs de réflexion). Un message assistant qui demande des outils et ses `tool_result` s'ajoutent ensemble, ou pas du tout.
- Chaque message entrant porte sa source en tête : `<source>marc</source>` ou `<source>support</source>`.
- Le serveur écoute sur `127.0.0.1:8770` seulement. Bibliothèque standard pour le serveur, HTML et JS sans framework pour la page.
- Toute heure en UTC. Page, prompts et documents de `API/` en français ; le PDF dans la langue du client.
- Lecture seule sur les données. Les outils n'écrivent que dans le dossier de la séance et dans `API/tools/typst/{documents,build}/`.
- Pas de tests automatisés dans le projet (D-008) : un seul `API/support/check.py` à `assert`, plus des vérifications par lancement.
- Pas de commit avant la validation de Marc (sa règle pour les essais de fonctionnalités). Un seul commit à la fin (Task 6).
## Points d'attention
1. **Mail sans station ni plage** : le support pose sa question à Marc et n'appelle pas l'analyste. Vérifié en Task 4, étape 5.
2. **Station absente de `data/`, ou aucune mesure sur la plage** : l'outil rend une erreur claire (`is_error`), l'analyste le dit, le support le dit à Marc ; aucune exception ne remonte au serveur. `check.py`, Task 3.
3. **Marc écrit pendant qu'un agent travaille** : le serveur répond 409 et la page affiche « occupé » ; l'historique reste valide. Le support est occupé tant que l'analyste qu'il a appelé l'est. Task 5.
4. **Erreur de l'API au milieu d'un tour** (surcharge, quota) : le tour s'arrête sur un événement d'erreur, sans `tool_use` orphelin dans l'historique ; le message suivant de Marc repart proprement. `check.py`, Task 2.
5. **Sortie d'outil énorme ou image trop grande** : texte plafonné à 40 000 caractères avec la mention `[… tronqué : N caractères]` ; image réduite à 1568 px de côté au plus. `check.py`, Task 3.
---
### Task 1 : le dossier `API/` et ses copies
**Fichiers :**
- Créer : `API/README.md`, `API/PROVENANCE.md`, `API/.gitignore`, `API/requirements.txt`
- Copier : `agent-tools/*.py` → `API/tools/agent-tools/` ; `detectors/*.py` (sans `archive/`) → `API/tools/detectors/` ; `.claude/skills/presentation/figure-y.py` et `image-de-la-cause.py` → `API/tools/figures/` ; `~/docfactory-presentation/brand/` → `API/tools/typst/brand/`
- Copier, savoir de l'analyste → `API/knowledge/analyste/` : `labeling/familles.md`, `labeling/carte-des-etiquettes.md`, `labeling/connaissances/{chaine-de-mesure,colonnes-des-deplacements,cycle-thermique,images-de-la-camera,les-trous,metriques-de-qualite}.md`, `.claude/skills/lire-les-donnees/SKILL.md` (→ `lire-les-donnees.md`), `agent-diagnostic/instructions.md` §5 seul (→ `regles-de-preuve.md`)
- Copier, savoir du support → `API/knowledge/support/` : `.claude/skills/presentation/SKILL.md` (→ `presentation.md`), `.claude/skills/presentation/modele.typ`, `.claude/skills/support/SKILL.md` §5 seul (→ `redaction.md`)
**Interfaces :**
- Produit : `API/tools/detectors/categories.py <dossier> --du AAAA-MM-JJ --au AAAA-MM-JJ` (inchangé) ; `API/tools/figures/figure-y.py` (mêmes arguments que l'original) ; `API/tools/typst/` = fabrique réduite (`brand/`, `documents/`, `build/`).
- [ ] **Étape 1 : copier.** `agent-tools/` et `detectors/` restent frères dans `API/tools/` : leurs `sys.path` relatifs (`.., agent-tools`) marchent tels quels. Dans `figures/figure-y.py`, remplacer `"..", "..", "..", "agent-tools"` par `"..", "agent-tools"`. Dans les copies du savoir, les chemins qui pointent hors de `API/` (`.claude/…`, `agent-tools/…`) deviennent ceux de `API/tools/…` ; le reste du texte est inchangé.
- [ ] **Étape 2 : `PROVENANCE.md`.** Une ligne par copie : source, destination, `git rev-parse --short HEAD` du jour (pour `brand/` : le `VERSION` de la fabrique), date 2026-11-05, et ce qui a été adapté. En tête, comment rafraîchir : recopier, puis mettre à jour la ligne.
- [ ] **Étape 3 : `.gitignore`, `requirements.txt`, venv.** Ignorer `.venv/`, `.env`, `__pycache__/`, `tools/typst/documents/`, `tools/typst/build/`. `requirements.txt` : `anthropic`, `langsmith`, `matplotlib`.
Lancer : `python3 -m venv API/.venv && API/.venv/bin/pip install -r API/requirements.txt`
- [ ] **Étape 4 : vérifier les détecteurs copiés.**
Lancer : `cd API && .venv/bin/python tools/detectors/categories.py ../data/NEBRASKA --du 2026-10-20 --au 2026-11-01`
Attendu : les mêmes lignes que `python3 detectors/categories.py data/NEBRASKA --du 2026-10-20 --au 2026-11-01` depuis la racine (`diff` vide).
- [ ] **Étape 5 : vérifier les figures et la fabrique.**
Lancer : `cd API && .venv/bin/python tools/figures/figure-y.py ../data/NEBRASKA /tmp/f.png 2026-10-20T00:00Z 2026-11-01T00:00Z --cam tilt,pan --cibles COLJ20,COLH21` → PNG écrit.
Puis copier `knowledge/support/modele.typ` dans `tools/typst/documents/essai/main.typ` avec les PNG qu'il cite (pris dans `support/2026-11-02_BREITHORN_rapport-situation/`), et `cd tools/typst && ../../.venv/bin/python brand/tools/build.py essai` → `build/essai-draft.pdf` existe. Supprimer `documents/essai/` et `build/` ensuite.
- [ ] **Étape 6 : `README.md`.** Installer (étape 3), les clés dans `API/.env` (`ANTHROPIC_API_KEY`, `LANGSMITH_API_KEY`, `LANGSMITH_TRACING=true`, `LANGSMITH_PROJECT=aimsight-support`), `AIMSIGHT_DATA`, lancer la page (`API/.venv/bin/python API/support/serveur.py`), ce que contient chaque dossier.
### Task 2 : l'agent, une boucle d'outils qui reste vivante
**Fichiers :**
- Créer : `API/support/agent.py`, `API/support/check.py`
**Interfaces :**
- Produit :
- `PRIX = {"claude-opus-5-5": {"entree": 4.0, "sortie": 20.0, "cache_lu": 0.20, "cache_ecrit": 5.0}}` ($/Mtok)
- `class Agent(nom: str, systeme: str, outils: list[dict], executer: Callable[[str, dict], str | list[dict]], client, journal: Callable[[dict], None], effort: str, modele: str = "claude-opus-5-5")`
- `Agent.messages: list[dict]`, `Agent.cout: float` ($), `Agent.occupe: bool`
- `Agent.tour(contenu: str | list[dict], source: str) -> str` : ajoute le message de l'utilisateur (source en tête), fait tourner la boucle jusqu'à `end_turn` et rend le texte final
- `Agent.sauver(chemin: Path) -> None` : écrit `messages` en JSON
- événements du journal : `{"agent": nom, "type": "entree" | "texte" | "outil" | "erreur" | "cout", "texte": str, "source": str}` ; `"entree"` : le message reçu, avec sa source (`marc` ou `support`), pour que le fil de l'analyste montre aussi les demandes du support ; pour `"cout"`, `"texte"` = le coût cumulé de l'agent, formaté `0.42` ; `"source"` seulement pour `"entree"`
- [ ] **Étape 1 : écrire les vérifications dans `check.py`** avec un faux client (un objet dont `beta.messages.stream(**kw)` est un gestionnaire de contexte qui rend des réponses scriptées, avec `content`, `stop_reason` et `usage`) :
- `check_boucle()` : réponse 1 = `tool_use` (`detecteurs`), réponse 2 = `end_turn` avec un texte → `tour` rend ce texte ; `messages` contient, dans l'ordre, user, assistant (tool_use), user (tool_result du même `tool_use_id`), assistant ; l'exécuteur a été appelé une fois avec le bon nom et la bonne entrée.
- `check_erreur()` : la réponse 2 lève une exception → `tour` ne la propage pas, émet un événement `"erreur"` ; la dernière entrée de `messages` n'est pas un assistant avec `tool_use` sans `tool_result` ; `occupe` revient à `False`.
- `check_cout()` : usage `input_tokens=1_000_000, output_tokens=100_000, cache_read_input_tokens=0, cache_creation_input_tokens=0` → `cout == 6.0`.
- `check_source()` : le premier bloc texte du message de l'utilisateur commence par `<source>marc</source>`.
- [ ] **Étape 2 : lancer, constater l'échec.** `API/.venv/bin/python API/support/check.py` → ImportError sur `agent`.
- [ ] **Étape 3 : écrire `agent.py`.** Appel : `client.beta.messages.stream(model, max_tokens=64000, system=[{"type": "text", "text": systeme, "cache_control": {"type": "ephemeral"}}], tools=outils, messages=messages, thinking={"type": "adaptive"}, output_config={"effort": effort}, betas=["server-side-fallback-2026-07-01"], fallbacks="default", cache_control={"type": "ephemeral"})`, puis `.get_final_message()`. Le contenu de la réponse est ajouté en dicts (`b.model_dump(mode="json", exclude_none=True)`). `stop_reason` : `tool_use` → exécuter **tous** les `tool_use`, puis ajouter l'assistant et un seul message user avec tous les `tool_result` ; un exécuteur qui lève → `tool_result` avec `is_error: True` et le message d'erreur ; `pause_turn` → renvoyer tel quel ; `end_turn` → fin ; `max_tokens` ou `refusal` → événement `"erreur"` et fin. Un événement `"texte"` par bloc texte de l'assistant ; un événement `"outil"` par appel (`nom` et entrée résumée sur une ligne). Coût : usage × `PRIX`, cumulé, un événement `"cout"` par réponse. Une exception autour d'un appel à l'API : événement `"erreur"`, l'assistant n'est pas ajouté, fin du tour.
- [ ] **Étape 4 : lancer `check.py`** → `ok` pour chaque vérification.
### Task 3 : les outils des deux agents
**Fichiers :**
- Créer : `API/support/outils.py`
- Modifier : `API/support/check.py` (ajouter les vérifications des outils)
**Interfaces :**
- Consomme : `Agent` (Task 2) seulement pour l'outil `demander_analyste`, par un rappel que lui donne la séance.
- Produit :
- `OUTILS_ANALYSTE: list[dict]`, `OUTILS_SUPPORT: list[dict]` (schémas de l'API, `strict: True`, `additionalProperties: false`)
- `class Boite(dossier_seance: Callable[[], Path], station: Callable[[], str | None], donnees: Path, demander_analyste: Callable[[str], str], poser: Callable[[str, str], Path])` (`poser(station, sujet)` : le rappel de la séance qui renomme son dossier et retient la station) avec `executer_analyste(nom: str, entree: dict) -> str | list[dict]` et `executer_support(nom: str, entree: dict) -> str | list[dict]`
- `LECTURE = {"inventaire", "resume", "plages", "jours", "vignettes", "qualite", "ensemble", "graphique", "metriques", "stations"}`
- `plafonner(texte: str, n: int = 40_000) -> str` ; `bloc_image(chemin: Path) -> dict` (bloc image en base64, PNG ou JPEG, plus grand côté ≤ 1568 px)
Outils de l'**analyste** (tous lancés par `subprocess.run` avec `API/.venv/bin/python`, `cwd` = le parent de `donnees`, délai 600 s, stdout et stderr rendus, plafonnés) :
- `detecteurs(station: str, du: str, au: str)` → `tools/detectors/categories.py <donnees>/<station> --du <du> --au <au>`
- `outil_de_lecture(nom: str, arguments: list[str])` → `tools/agent-tools/<nom>.py <arguments>` ; `nom` hors de `LECTURE` → erreur ; pour `graphique`, `ensemble`, `jours`, `metriques`, `vignettes`, `qualite`, ajouter `--sortie <dossier de la séance>`
- `figure_courbes(nom: str, debut: str, fin: str, cibles: list[str], options: list[str])` → `tools/figures/figure-y.py <donnees>/<station> <séance>/<nom>.png <debut> <fin> --cibles <…> <options>` (station : celle de la séance, posée par le support, cf. Task 4)
- `image_de_la_cause(nom: str, x: int, y: int, instants: list[str])` → `tools/figures/image-de-la-cause.py <donnees>/<station> <x> <y> <séance>/<nom>.png <instants>`
- `voir_image(chemin: str)` → `[bloc_image(…)]` ; chemin relatif au dossier de la séance, ou `images/…` de la station ; tout autre chemin (`..`, absolu) → erreur
Outils du **support** :
- `poser_station(station: str, sujet: str)` → vérifie que `<donnees>/<station>` existe ; renomme le dossier de la séance en `<AAAA-MM-JJ>_<STATION>_<sujet>` ; rend la liste des sous-dossiers de données de la station
- `demander_analyste(message: str)` → le rappel de la séance
- `ecrire_presentation(source_typ: str)` → écrit `<séance>/<station minuscule>.typ`
- `compiler()` → copie le `.typ` (en `main.typ`) et les PNG de la séance dans `tools/typst/documents/<slug>/`, lance `brand/tools/build.py <slug>` depuis `tools/typst/`, copie `build/<slug>-draft.pdf` vers `<séance>/v<N>.pdf` (N = 1 + nombre de `v*.pdf` présents), rend `v<N>.pdf : <k> diapositive(s) qui débordent` (`pdftotext` puis compter `Overflow`) ou la sortie d'erreur de Typst, sans créer de version
- `voir_page(n: int)` → `pdftoppm -f n -l n -png -r 80` sur la dernière version, rendu par `bloc_image`
- [ ] **Étape 1 : vérifications dans `check.py`** (sans appel à l'API ; sur `data/NEBRASKA`) :
- `check_lecture_refusee()` : `outil_de_lecture("rm", [])` rend une erreur et ne lance rien.
- `check_chemin()` : `voir_image("../../.env")` et `voir_image("/etc/passwd")` → erreur.
- `check_station_absente()` : `detecteurs("NULLEPART", "2026-10-01", "2026-10-02")` → une erreur qui nomme la station, pas d'exception.
- `check_detecteurs()` : `detecteurs("NEBRASKA", "2026-10-20", "2026-11-01")` → texte non vide.
- `check_plafond()` : `plafonner("x" * 50_000)` fait au plus 40 100 caractères et finit par `tronqué : 50000 caractères]`.
- `check_image()` : `bloc_image` d'une image de `data/NEBRASKA/images/` → `media_type` `image/jpeg`, image décodée de côté ≤ 1568.
- `check_compiler()` : séance temporaire contenant `modele.typ` (en `nebraska.typ`) et ses PNG → `compiler()` rend `v1.pdf : …` et `v1.pdf` existe ; une seconde fois → `v2.pdf`. Un `.typ` cassé (`#oups(`) → erreur, pas de `v3.pdf`.
- [ ] **Étape 2 : lancer `check.py`** → échec (pas de `outils`).
- [ ] **Étape 3 : écrire `outils.py`.**
- [ ] **Étape 4 : lancer `check.py`** → `ok` partout.
### Task 4 : les prompts, la séance et LangSmith
**Fichiers :**
- Créer : `API/prompts/support.md`, `API/prompts/analyste.md`, `API/support/seance.py`
**Interfaces :**
- Consomme : `Agent` (Task 2), `Boite`, `OUTILS_*` (Task 3).
- Produit : `class Seance(mail: str, images: list[tuple[str, bytes]], contexte: str, donnees: Path, journal: Callable[[dict], None])`, avec :
- `dossier: Path` (d'abord `API/cases/<AAAA-MM-JJ>_<HHMMSS>/`, renommé par `poser_station`), `station: str | None`
- `support: Agent`, `analyste: Agent`
- `demarrer() -> None` : écrit `demande.md` (mail, contexte, images en fichiers), puis premier tour du support avec le mail, les images (blocs image) et le contexte
- `parler(agent: str, texte: str) -> None` : `"support"` ou `"analyste"`, source `marc`
- `occupe(agent: str) -> bool` : le support est occupé aussi pendant qu'il attend l'analyste
- `cout() -> dict` : `{"support": float, "analyste": float, "total": float}`
- `derniere_version() -> Path | None`
- [ ] **Étape 1 : `prompts/analyste.md`**, en balises : `<role>`, `<premiere_passe>`, `<approfondi>`, `<rendu>`, `<regles>`, puis le savoir de `knowledge/analyste/` inclus par le code au chargement (balise `<savoir fichier="…">` par fichier : prompt stable, donc en cache). Il doit dire :
- première passe : `detecteurs` sur la plage, les événements qui répondent à la question, **une illustration par événement retenu** (courbe `corr_y` à plage grisée, ou image de la cause), regardée par `voir_image` avant d'être gardée ;
- approfondi (`outil_de_lecture`, images, critique des détecteurs) seulement si le message vient de `<source>marc</source>` et le demande ; une demande du support qui l'exigerait est renvoyée au support, pour Marc ;
- le rendu au support : un bloc par événement (quand, cibles, ce qu'on voit, diagnostic, illustration), puis `Hors question (pour Marc)` ; vocabulaire de preuve (`regles-de-preuve.md`) ; il ne modifie jamais les détecteurs.
- [ ] **Étape 2 : `prompts/support.md`**, en balises : `<role>`, `<deroule>`, `<presentation>`, `<redaction>`, `<interdits>`, puis `knowledge/support/` inclus de la même façon. Il doit dire :
- tirer station, plage UTC et question du mail et du contexte ; ce qui manque, le demander à Marc et finir son tour ; sinon `poser_station`, puis `demander_analyste` avec station, plage et question ;
- la présentation suit `presentation.md` et `modele.typ`, **restreinte à la question du mail** : seuls les événements qui y répondent ; titre, résumé, une diapositive par événement, conclusions, clôture ; rien de la section « Hors question » ;
- `compiler`, puis `voir_page` sur chaque page à image ; corriger jusqu'à zéro débordement ;
- un retour de forme : corriger seul ; un retour de fond : le transmettre à l'analyste ;
- les interdits (spec §2, anti-buts) : rien d'interne, ne pas se mettre en cause, ne rien affirmer sur l'ouvrage, aucune consigne au client.
- [ ] **Étape 3 : `seance.py`.** Un client `anthropic.Anthropic()` enveloppé par `langsmith.wrappers.wrap_anthropic`, et `demarrer`, `parler` décorés `@langsmith.traceable` (le nom de la séance en métadonnée) : une trace par séance. Clés lues dans `API/.env` par un petit lecteur `CLE=valeur` (pas de dépendance). Quand Marc parle à l'analyste, l'échange (sa question, la réponse) est mis de côté puis ajouté en tête du prochain tour du support, dans `<echange_marc_analyste>`. Les deux historiques sont sauvés (`support.json`, `analyste.json`) dans le dossier de la séance après chaque tour.
- [ ] **Étape 4 : essai sans page** (coûte quelques dollars). Un mail court, station explicite :
`cd API && .venv/bin/python -c "from support.seance import Seance; …"` avec le mail « Bonjour, pourquoi les courbes de NEBRASKA sont-elles si bruitées du 28 au 31 octobre ? », journal = `print`.
Attendu : `poser_station` ; un `demander_analyste` ; l'analyste lance `detecteurs`, produit au moins une figure et la regarde ; le support écrit, compile, regarde ses pages ; `v1.pdf` existe ; `cache_read_input_tokens > 0` à partir du deuxième appel d'un même agent ; une trace dans le projet LangSmith `aimsight-support`.
- [ ] **Étape 5 : essai du point d'attention 1.** Mail « Bonjour, les courbes sont bizarres depuis la semaine passée, tu peux regarder ? » sans contexte → le support pose une question à Marc, et aucun `demander_analyste`.
### Task 5 : la page et le serveur
**Fichiers :**
- Créer : `API/support/serveur.py`, `API/support/page.html`
**Interfaces :**
- Consomme : `Seance` (Task 4).
- Produit, routes de `127.0.0.1:8770` :
- `GET /` → `page.html`
- `POST /analyser` `{"mail": str, "contexte": str, "images": [{"nom": str, "type": str, "base64": str}]}` → crée la séance, lance `demarrer` dans un fil ; 409 si une séance tourne déjà
- `POST /message` `{"agent": "support" | "analyste", "texte": str}` → `parler` dans un fil ; 409 si `occupe(agent)`
- `GET /evenements?depuis=N` → `{"evenements": [...], "n": int, "cout": {...}, "version": "v2.pdf" | null, "occupe": {"support": bool, "analyste": bool}}`
- `GET /pdf` → la dernière version (`application/pdf`)
- [ ] **Étape 1 : `serveur.py`.** `ThreadingHTTPServer`, une seule séance à la fois, la liste des événements en mémoire derrière un `threading.Lock`. Au lancement, ouvrir la page dans le navigateur comme les autres pages du projet (`explorer.exe` sous WSL, sinon `webbrowser`), sans dépendre de `src/common/`.
- [ ] **Étape 2 : `page.html`, disposition B** (maquette : `.superpowers/brainstorm/*/content/page-support.html`) : en haut, le mail (zone de texte ; une image collée depuis le presse-papiers s'ajoute en vignette), le contexte, **Analyser**, le coût (support, analyste, total, en $) ; au milieu, deux fils côte à côte, **support** à gauche, **analyste** à droite, chacun avec sa zone de saisie, désactivée et marquée « occupé » quand l'agent travaille ; les événements `"outil"` en une ligne grise, les `"erreur"` en rouge ; en dessous, le PDF dans un `<iframe>` rechargé à chaque nouvelle version, son numéro et **Télécharger**. Interrogation de `/evenements` chaque seconde.
- [ ] **Étape 3 : vérifier par lancement et capture.** `API/.venv/bin/python API/support/serveur.py`, coller le mail de la Task 4 étape 4, **Analyser** : les deux fils se remplissent au fil de l'eau, le coût monte, le PDF v1 apparaît et se télécharge. Écrire au support « La conclusion est trop longue, deux puces au plus » → v2. Écrire au support pendant qu'il travaille → refusé, « occupé ». Capture de la page à montrer à Marc.
### Task 6 : documenter et livrer
**Fichiers :**
- Modifier : `docs/decisions.md` (D-133), `CLAUDE.md` (carte et « État »), `run.md` (la commande de la page)
- [ ] **Étape 1 : D-133**, au format du fichier : le support par l'API Claude dans le sous-projet `API/`, séparé de `.claude/` ; options écartées (Agent SDK, Managed Agents) et pourquoi ; renvoi au design.
- [ ] **Étape 2 : `CLAUDE.md`.** Une ligne dans « État et prochaine étape » (support par l'API, prototype) et une entrée `API/` dans la carte du dépôt (sous-projet autonome ; sa doc dans `API/README.md`) ; rester sous 200 lignes.
- [ ] **Étape 3 : montrer à Marc** la capture et le PDF de l'essai ; attendre sa validation.
- [ ] **Étape 4 : commit, après sa validation seulement.**
```bash
git add API docs/decisions.md CLAUDE.md run.md docs/superpowers/plans/2026-10-23-journal-du-matin.md
git commit -m "API: support page with two Claude API clients, support and analyst (D-133)"
```
Vérifier avant que `git status` ne montre ni `API/.env` ni `API/.venv/`.