first

docs/signaling_v_2.md

@@ -0,0 +1,161 @@
+# 📄 signaling.md — Mesh Signaling & Connectivity (v2)
+
+## 1. Objectif
+
+Documenter :
+
+- la **signalisation WebRTC** (média) via Mesh Server,
+- la stratégie **ICE/STUN/TURN**,
+- la stratégie **data-plane QUIC** (agents Rust) et ses contraintes réseau,
+- les optimisations et diagnostics.
+
+---
+
+## 2. Architecture
+
+- **Control plane** : Mesh Server (WS)
+- **Media plane** : WebRTC (clients web)
+- **Data plane** : QUIC P2P (agents Rust)
+
+Le serveur ne transporte aucun flux média ou transfert lourd.
+
+---
+
+## 3. WebRTC (média) — ICE
+
+### STUN (obligatoire)
+
+Découverte IP publique.
+
+### TURN (fallback)
+
+Relais si P2P direct échoue.
+
+Politique candidats :
+
+1. host
+2. srflx
+3. relay
+
+Recommandations :
+
+- Ne pas forcer TURN
+- Logguer quand relay est utilisé
+- Credentials temporaires TURN (V1+)
+
+---
+
+## 4. WebRTC — séquence
+
+1. Action (call/screen) demandée au serveur
+2. Serveur valide ACL + émet `cap_token`
+3. Échange SDP/ICE via WS (`rtc.offer/answer/ice`)
+4. Flux média direct A↔B
+
+---
+
+## 5. QUIC P2P (data plane) — stratégie
+
+- QUIC = TLS 1.3 natif + multiplexing streams
+- Sessions orchestrées via `p2p.session.request/created`
+- Connexion directe agent↔agent sur UDP
+
+### Contraintes réseau
+
+- UDP sortant requis.
+- Certains NAT/CGNAT peuvent compliquer la traversée.
+
+Stratégie :
+
+- privilégier LAN
+- documenter l’ouverture/autorisation UDP côté WAN
+- fallback exceptionnel : HTTP temporaire via serveur
+
+---
+
+## 6. Optimisations transferts
+
+- chunks 64–256 KB
+- backpressure
+- reprise par offset
+- hashing blake3 (chunk + final)
+
+---
+
+## 7. Sécurité
+
+- Actions gated by capability token TTL court.
+- QUIC : TLS 1.3.
+- Terminal : preview-only par défaut, contrôle arbitré par serveur.
+
+---
+
+## 8. Diagnostics
+
+Exposer :
+
+- WebRTC : host/srflx/relay
+- QUIC : latence, débit, pertes, retries
+- erreurs : sessions refusées, tokens expirés
+
+---
+
+## 9. Changelog
+
+```
+0.1.0 – WebRTC signaling + ICE
+0.2.0 – QUIC data-plane sessions (agent Rust)
+```
+
+
+
+---
+
+## Consignes de gestion du contexte et des fichiers CLAUDE.md (obligatoire)
+
+### Utilisation de plusieurs fichiers `CLAUDE.md`
+
+- Utilisez **plus d’un fichier **`` dans le projet.
+- Conservez un ``** général à la racine** du dépôt Mesh (vision globale, règles communes).
+- Ajoutez des ``** spécifiques dans les sous-dossiers** (`server/`, `agent/`, `client/`, `infra/`, etc.) afin de fournir à Claude un **contexte ciblé et local**.
+- Chaque fichier `CLAUDE.md` de sous-dossier doit compléter le fichier racine, sans le contredire.
+
+### Gestion de la fenêtre de contexte
+
+Au fil d’une session longue, la fenêtre de contexte de Claude peut se saturer, entraînant une perte de précision ou l’oubli d’instructions importantes.
+
+Pour éviter cela, appliquer systématiquement les pratiques suivantes :
+
+#### 1. Réinitialisation stratégique du contexte
+
+- Utiliser régulièrement la commande :
+  ```
+  /clear
+  ```
+- En particulier :
+  - entre deux tâches distinctes,
+  - entre conception et implémentation,
+  - entre implémentation et revue.
+
+Cette commande efface l’historique courant et permet de repartir sur une **ardoise vierge**, en s’appuyant uniquement sur les fichiers `CLAUDE.md` pertinents.
+
+#### 2. Utilisation de sous-agents
+
+Pour les flux de travail complexes ou multi-étapes, déléguer explicitement à des **sous-agents**.
+
+Exemple :
+
+> « Tu viens d’écrire le code du partage de fichiers. Maintenant, utilise un sous-agent pour effectuer une revue de sécurité de ce code. »
+
+Avantages :
+
+- séparation claire des responsabilités,
+- contexte dédié pour chaque analyse,
+- réduction du bruit dans la conversation principale.
+
+### Principe fondamental
+
+Le **contexte de référence du projet Mesh doit toujours être porté par les fichiers **``, et non par l’historique de la conversation. L’historique n’est qu’un support temporaire.
+
+Ces consignes sont **obligatoires** pour toute utilisation de Claude dans le cadre du projet Mesh.
+