@nodefony/devkit 10.0.0-beta.2 → 10.0.0-beta.4

package/docs/index.md

@@ -106,13 +106,13 @@ la rend éprouvable sans serveur, et ce qui l'empêche d'inventer quoi que ce so
 npx nodefony ai:mcp        # écrit .mcp.json ; --dry-run pour voir sans écrire
 ```
 
-Sept outils. Quatre sont les commandes que vous connaissez déjà :
+Neuf outils. Quatre sont les commandes que vous connaissez déjà :
 `nodefony_inspect` (ce qui est monté), `nodefony_check` (ce qui manque),
 `nodefony_symbols` (ce qu'une API signifie), `nodefony_card` (par où commencer).
 `nodefony_docs` sert la documentation des modules. `nodefony_admin_list` et
 `nodefony_admin_call` ouvrent les lectures du data plane d'administration — le
 catalogue, puis l'appel — et exigent un jeton porteur du scope `admin:read` :
-sans lui, ils n'apparaissent pas dans la liste.
+sans lui, ils n'apparaissent pas dans la liste. `nodefony_observe` mesure ce que l'application fait réellement de ses requêtes, pendant qu'elle tourne ; `nodefony_profile_route` mesure une route en lui envoyant lui-même ses requêtes (sections suivantes).
 
 **Il n'y a pas de process à lancer.** Depuis la révision `2026-07-28` du
 transport, un serveur MCP est un endpoint `POST` sans session : c'est donc une
@@ -143,13 +143,145 @@ Trois choses à savoir avant de s'étonner d'un refus :
 
 Les outils intégrés sont en lecture seule, et `mcp.tools` est une allowlist.
 
-### Obtenir le porteur — `security:token`
+### Mesurer l'application qui tourne — `nodefony_observe`
+
+Un agent de code qui vient de modifier un contrôleur ne voit pas l'effet de son
+changement : la barre de debug et la console d'administration affichent les
+mesures du profileur, mais il ne les lit pas. `nodefony_observe` les lui rend.
+Pendant une fenêtre de 1 à 50 secondes (10 par défaut), l'outil relève le
+profileur de développement toutes les deux secondes et rend un rapport :
+
+1. un **verdict** — `ok`, `anomalies (N)`, et `INCOMPLÈTE` quand les chiffres ne
+   portent pas sur tout (profils perdus, aucun trafic, appel interrompu), avec
+   la raison ;
+2. les **anomalies**, nommées par route et par contrôleur : une requête SQL
+   répétée dans une boucle (« N+1 »), les erreurs `5xx` avec leur `requestId` et
+   leurs lignes de journal, les routes dont le p95 dépasse 500 ms avec ce qui
+   coûte par requête, un blocage de la boucle d'événements de 100 ms ou plus ;
+3. un tableau par route, les requêtes SQL les plus coûteuses, et un bloc JSON
+   pour comparer deux appels — avant et après une correction.
+
+```jsonc
+{ "name": "nodefony_observe", "arguments": { "durationSec": 10 } }
+// "route": "<nom de route>" pour n'en observer qu'une ; "includeTooling": true
+// pour compter aussi les routes /nodefony/… de l'outillage
+```
+
+**L'outil ne génère aucun trafic.** On ouvre la page, on joue les tests ou on
+envoie des requêtes pendant que la fenêtre court ; sans trafic, il n'a rien à
+juger, et il le dit.
+
+Ce que les chiffres veulent dire :
+
+- **durées et temps « par requête »** portent sur les requêtes **servies**
+  (statut inférieur à 400, sans exception). Un refus `401`/`403` rendu en
+  quelques millisecondes ne mesure pas la route : il est compté à part ;
+- **`action.self`** est le temps de l'action et des services qu'elle appelle,
+  une fois retirés les phases imbriquées (initialisation, rendu, envoi) et le
+  SQL — les intervalles sont fusionnés, une requête lancée pendant le rendu
+  n'est pas comptée deux fois. **« SQL (cumul) »** additionne les durées des
+  requêtes, même lancées en parallèle ;
+- **la boucle d'événements** est rapportée en retard moyen et en **pire
+  blocage** : un gel unique de 200 ms ne déplace la moyenne d'un intervalle de
+  deux secondes que de quelques millisecondes ;
+- **la forme d'une requête SQL** remplace chaque valeur par `?` : le rapport ne
+  contient jamais une donnée. Le journal d'une erreur n'en garde que les lignes
+  WARNING et plus graves ;
+- la **variation du tas** est mesurée sans GC forcé : elle est indicative,
+  jamais une anomalie.
+
+Ce qui encadre l'outil :
+
+- c'est un **outil long** : chaque relevé part en progression, et un client qui l'annule l'arrête au relevé suivant, qu'il ferme le flux de la réponse (révision courante de MCP) ou envoie une notification d'annulation (révision précédente, celle du SDK officiel) ;
+- un **rechargement du serveur** pendant la fenêtre (un fichier modifié) ne fait
+  pas perdre l'observation : l'outil rend un rapport partiel qui le dit, avant
+  que le serveur ne ferme ses connexions ;
+- le **journal des erreurs** est lu au relevé qui voit la requête — le syslog de
+  développement ne garde que ses dernières lignes — et seulement pour un appel
+  **authentifié** (scope `admin:read`), par la même voie que
+  `nodefony_admin_call` ;
+- le profileur garde les 500 dernières requêtes : au-delà de ce débit entre deux
+  relevés, les profils perdus sont comptés, et le verdict le dit.
+
+La lecture de chaque anomalie et le geste qui la corrige sont dans le skill
+d'agent `nodefony-troubleshoot`, section « Mesurer l'application qui tourne ».
+
+### Mesurer une route — `nodefony_profile_route`
+
+Là où `nodefony_observe` attend le trafic, `nodefony_profile_route` le **produit** :
+il envoie lui-même N requêtes `GET` (ou `HEAD`) sur un chemin de l'application,
+retrouve leurs profils par l'identifiant qu'il pose (`x-request-id`) et rend le
+même rapport. C'est la boucle « je modifie → je mesure » en un appel.
+
+```jsonc
+// tools/call
+{
+  "name": "nodefony_profile_route",
+  "arguments": { "path": "/orders?page=2", "count": 50 },
+}
+// optionnel : "concurrency" (défaut 4, max 8), "warmup" (défaut 3, hors mesures),
+//             "method": "HEAD", "as": "<identifiant>", "anonymous": true
+```
+
+`path` est un **chemin**, jamais une URL : hôte, schéma et `//` sont refusés,
+l'outil ne vise que l'application elle-même. Au plus 200 requêtes par appel —
+sous les 500 profils que garde le profileur — et 45 secondes de tir.
+
+**Au nom de qui.** Une page protégée vue sans compte ne rend que des refus.
+Quand le jeton MCP porte le scope `admin:write`, l'outil joue son
+**propriétaire** : il ouvre une vraie session à son nom par le flux de connexion
+de l'application (un ticket à usage unique, présenté en boucle locale à
+`POST /nodefony/devkit/profile-session`), tire avec, puis la détruit — l'audit
+l'écrit sous la raison `devkit`. `as` joue un autre compte, à condition que ses
+rôles soient inclus dans ceux du propriétaire, hiérarchie comprise : jouer un
+compte ne monte jamais en droits. Sans ce scope, l'outil joue l'anonyme et le
+rapport donne la commande :
+
+```bash
+npx nodefony security:mcp:token --scope "admin:read admin:write" --write
+```
+
+Extrait de deux appels réels, avant puis après la correction d'un N+1 (la même
+lecture, une requête par compte, puis une seule requête `$in`) :
+
+```text
+Verdict : anomalies (1) — observation complète
+Tir : 30/30 requête(s) GET /nodefony/test/db/n-plus-one · concurrence 4 · 106 ms · chauffe de 3 requête(s) hors mesures (p50 1.5 ms, max 2.5 ms)
+Joué en tant que : `admin` (ROLE_ADMIN, ROLE_NODEFONY_ADMIN, ROLE_DEV, ROLE_SUPERVISOR)
+Reçu par le client : 2xx 30 · 3xx 0 · 401 0 · 403 0 · autres 4xx 0 · 5xx 0 · sans réponse 0
+
+Anomalies (les plus coûteuses d'abord) :
+1. N+1 — route `DbController::nPlusOne` (DbController.nPlusOne) : `select … from "User" where "User"."id" = ? …` répétée ×16 dans une requête (30 requête(s) touchée(s), 14 ms cumulés). […] Remède habituel : charger la relation en une requête (`relations`, `$in`).
+
+route | type | n | p50 | p95 | max | 2xx/3xx/4xx/5xx | SQL par requête moy/max | temps par requête
+`DbController::nPlusOne` (DbController.nPlusOne) | http | 30 | 1.2 ms | 1.7 ms | 1.7 ms | 30/0/0/0 | 18.0/18 | SQL (cumul) 0.7 ms · action.self 0.2 ms · send 0.1 ms
+
+— après correction —
+Verdict : ok — observation complète
+`DbController::nPlusOneFixed` (DbController.nPlusOneFixed) | http | 30 | 0.7 ms | 0.9 ms | 2.1 ms | 30/0/0/0 | 3.0/3 | SQL (cumul) 0.4 ms · send 0.1 ms · action.self 0.1 ms
+```
+
+Ce que le rapport dit **en tête**, avant tout chiffre : les requêtes refusées
+(`401`/`403` — verdict « rien à juger »), redirigées (vers la page de
+connexion), restées sans réponse, et les profils non retrouvés. Une mesure qui ne
+porte pas sur ce qui était demandé le dit d'abord.
+
+À savoir :
+
+- ce sont de **vraies requêtes** : une page qui écrit en `GET` écrit N fois — un
+  compteur, ou une session créée pour chaque visiteur anonyme ;
+- les zones à jeton (`jwt`, `external-jwt`) ne sont pas jouées : leurs requêtes
+  rendent `401`, et le rapport le dit ;
+- un tir plus court que cinq périodes de la sonde laisse la boucle d'événements
+  « non mesurée » plutôt que d'afficher un zéro trompeur.
+
+### Obtenir le porteur — `security:mcp:token`
 
 Dès que la porte demande un jeton, il faut en produire un. L'application **le signe elle-même**, en
 ligne de commande, sans qu'aucun serveur n'écoute :
 
 ```bash
-npx nodefony security:token --write   # pose NF_MCP_TOKEN chez les agents présents
+npx nodefony security:mcp:token --write   # pose NF_MCP_TOKEN chez les agents présents
 npx nodefony ai:mcp --auth            # l'en-tête porte ${NF_MCP_TOKEN}, jamais le jeton
 ```
 
@@ -203,7 +335,8 @@ métier — et c'est précisément ce qu'un agent invente le plus mal. N'importe
 module de votre application peut donc en publier :
 
 ```ts
-import { Module, mcpText, type IMcpTool } from "nodefony";
+import { Module, type IMcpTool } from "nodefony";
+import { mcpText } from "@nodefony/ai";
 
 class Shop extends Module {
   getMcpTools(): IMcpTool[] {
@@ -221,6 +354,10 @@ class Shop extends Module {
           properties: { sku: { type: "string", description: "Référence" } },
           required: ["sku"],
         },
+        // Il LIT la base et ne sort pas de l'application : il le dit, sinon la
+        // spec le tient pour destructif et l'agent demande confirmation à
+        // chaque lecture.
+        annotations: { readOnlyHint: true, openWorldHint: false },
         handler: async (args) => mcpText(await this.stock(String(args.sku))),
       },
     ];
@@ -228,8 +365,14 @@ class Shop extends Module {
 }
 ```
 
-Trois choses à savoir :
+Quatre choses à savoir :
 
+- **un outil dit ce qu'il fait** (`annotations`, indices `ToolAnnotations` de la
+  spec MCP) : sans annotation, la spec le tient pour un outil qui écrit, détruit
+  et sort de l'application. Un outil qui lit se déclare `readOnlyHint: true` ;
+  un outil qui modifie, `readOnlyHint: false`. Un indice n'est jamais une
+  autorisation — le détail des cinq indices et de leurs défauts :
+  [écrire un outil](../../ai/docs/mcp.md#dire-ce-que-fait-loutil--les-annotations) ;
 - **rien ne s'enregistre au démarrage** : la liste est relue à chaque requête,
   donc un module ajouté apparaît sans redémarrer quoi que ce soit ;
 - **`mcp.tools` ne filtre que les outils intégrés** — le vôtre est publié dès
@@ -277,6 +420,56 @@ est absent de `tools/list` **et** inappelable en le nommant, et le refus dit
 > `policy: "dev"`. Avant d'exposer une donnée par un outil, se demander si elle
 > supporterait d'être lue **sans identification**, par qui a accès à la machine.
 
+### Un outil LONG — progression et annulation
+
+Le troisième paramètre du handler sert l'outil qui dure : `run.signal` est
+abattu quand le client annule — qu'il ferme le flux de la réponse (révision courante
+de MCP) ou envoie `notifications/cancelled` (révision précédente) —,
+`run.progress()` lui donne signe de vie.
+Un outil court l'ignore ; un appel direct (un test) ne le fournit pas, d'où le
+`run?.` :
+
+```ts
+{
+  name: "shop_reindex",
+  description: "Réindexe le catalogue, lot par lot. Long : signale chaque lot.",
+  inputSchema: { type: "object", properties: {} },
+  handler: async (_args, _caller, run) => {
+    const lots = await this.lots();
+    for (const [i, lot] of lots.entries()) {
+      if (run?.signal.aborted) return mcpText("interrompu", true);
+      await this.reindex(lot, run?.signal);
+      run?.progress(i + 1, lots.length, `lot ${i + 1}/${lots.length}`);
+    }
+    return mcpText(`${lots.length} lots réindexés`);
+  },
+}
+```
+
+Ce que la porte fait du reste :
+
+- **le flux s'ouvre à la première progression, ou au bout de cinq secondes.**
+  Un agent qui envoie un `progressToken` et accepte `text/event-stream` reçoit
+  des `notifications/progress`, puis la réponse, qui clôt le flux. Un outil
+  encore en cours après le délai de grâce (`MCP_STREAM_GRACE_MS`, 5 s) ouvre le
+  flux même sans jeton : la norme oblige le client à accepter une réponse en
+  flux, et c'est ce qui désarme le délai d'inactivité de la requête (30 s par
+  défaut) — sans cela, un outil long répondant en JSON recevrait un `408`. Un
+  outil qui répond avant reste en JSON ;
+- **la norme est tenue pour vous** : une valeur qui ne croît pas est ignorée, la
+  cadence est bornée (une notification par 100 ms au plus), et plus rien ne
+  part une fois l'outil terminé ;
+- **fermer le flux, c'est annuler** (transport HTTP, révision 2026-07-28) :
+  `run.signal` est abattu, à l'outil de s'arrêter.
+
+Le journal `notifications/message` n'est **pas** proposé : la révision
+2026-07-28 le déprécie (« New implementations SHOULD NOT adopt it »). Ce qu'un
+outil veut dire en route passe par le `message` de la progression ; ce qui doit
+atteindre le modèle va dans la réponse finale. `subscriptions/listen` est refusé
+par une erreur explicite (`-32601`) : le catalogue ne change qu'au rechargement
+de l'application, qui redémarre son process, si bien qu'un flux d'abonnement
+casserait au lieu de notifier. Le `tools/list` suivant rend l'état à jour.
+
 ## Les skills d'agent — répondre à « comment fait-on ça, ici ? »
 
 La carte dit **où aller**. Elle ne dit pas **comment faire**. Or c'est là qu'un
@@ -284,20 +477,24 @@ agent invente : faute d'une marche à suivre, il écrit un CRUD à la main, un
 service à méthodes `static` que le conteneur ne voit pas, un contrôle de droits
 dans le corps de l'action.
 
-Le paquet livre donc huit **skills** au format [Agent Skills](https://agentskills.io) :
-un qui porte la conduite commune de toute tâche, et un par geste où l'invention
-coûte cher :
-
-| Skill                           | Le besoin qu'il couvre                                          |
-| ------------------------------- | --------------------------------------------------------------- |
-| `nodefony-dev`                  | conduire une tâche de bout en bout, avant toute modification    |
-| `nodefony-add-crud`             | exposer une ressource REST complète, entité comprise            |
-| `nodefony-add-service`          | ajouter de la logique métier réutilisable, vue du conteneur     |
-| `nodefony-protect-route`        | réserver une route à qui est habilité                           |
-| `nodefony-add-realtime-channel` | ouvrir un canal temps réel où le serveur pousse                 |
-| `nodefony-browser`              | voir **et mesurer** un écran, sans navigateur sur le poste      |
-| `nodefony-migrate-schema`       | faire évoluer le schéma d'une base et le porter en production   |
-| `nodefony-devops`               | exploiter l'application en conteneur, sans réécrire son contrat |
+Le paquet livre donc onze **skills** au format [Agent Skills](https://agentskills.io) :
+un qui porte la conduite commune de toute tâche, un qui part du symptôme d'une panne,
+et un par geste où l'invention coûte cher :
+
+| Skill                           | Le besoin qu'il couvre                                           |
+| ------------------------------- | ---------------------------------------------------------------- |
+| `nodefony-dev`                  | conduire une tâche de bout en bout, avant toute modification     |
+| `nodefony-add-crud`             | exposer une ressource REST complète, entité comprise             |
+| `nodefony-add-service`          | ajouter de la logique métier réutilisable, vue du conteneur      |
+| `nodefony-authentication`       | connecter un utilisateur ou un programme, sans rien réécrire     |
+| `nodefony-protect-route`        | réserver une route à qui est habilité                            |
+| `nodefony-add-realtime-channel` | ouvrir un canal temps réel où le serveur pousse                  |
+| `nodefony-browser`              | voir **et mesurer** un écran, sans navigateur sur le poste       |
+| `nodefony-migrate-schema`       | faire évoluer le schéma d'une base et le porter en production    |
+| `nodefony-devops`               | exploiter l'application en conteneur, sans réécrire son contrat  |
+| `nodefony-troubleshoot`         | partir d'un symptôme de panne pour trouver le geste qui la règle |
+| `nodefony-security-review`      | relire la sécurité d'un diff avant de le commiter                |
+| `nodefony-upgrade`              | monter le framework de version sans rien laisser derrière        |
 
 Tous portent le préfixe `nodefony-` : leurs pointeurs arrivent dans le dossier où
 vous écrivez aussi les vôtres, et sans namespace un skill maison du même nom

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/devkit",
-  "version": "10.0.0-beta.2",
+  "version": "10.0.0-beta.4",
   "type": "module",
   "description": "Outillage de développement d'une application Nodefony : carte de visite du projet et portes de découverte pour un agent de développement",
   "author": "Christophe CAMENSULI <ccamensuli@gmail.com>",
@@ -20,25 +20,30 @@
   ],
   "scripts": {
     "build": "rolldown -c rolldown.config.ts && tsgo -p tsconfig.declarations.json",
+    "clean": "node --eval \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "typecheck": "tsgo --noEmit -p tsconfig.json && tsgo --noEmit -p tsconfig.tests.json",
     "test": "vitest run",
-    "coverage": "vitest run --coverage"
+    "coverage": "vitest run --coverage",
+    "test:integration": "vitest run --config vitest.integration.config.ts"
   },
   "peerDependencies": {
-    "@nodefony/framework": "^10.0.0-beta.2",
-    "@nodefony/http": "^10.0.0-beta.2",
-    "nodefony": "^10.0.0-beta.2",
-    "zod": "^4.6.5",
+    "@nodefony/ai": "^10.0.0-beta.4",
+    "@nodefony/framework": "^10.0.0-beta.4",
+    "@nodefony/http": "^10.0.0-beta.4",
+    "lighthouse": "^13.0.0",
+    "nodefony": "^10.0.0-beta.4",
     "playwright": "^1.50.0",
-    "lighthouse": "^13.0.0"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@nodefony/framework": "^10.0.0-beta.2",
-    "@nodefony/http": "^10.0.0-beta.2",
-    "nodefony": "^10.0.0-beta.2"
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@nodefony/ai": "^10.0.0-beta.4",
+    "@nodefony/framework": "^10.0.0-beta.4",
+    "@nodefony/http": "^10.0.0-beta.4",
+    "nodefony": "^10.0.0-beta.4"
   },
   "dependencies": {
-    "axe-core": "4.13.0",
+    "axe-core": "4.14.0",
     "tslib": "2.8.1"
   },
   "peerDependenciesMeta": {
@@ -72,6 +77,6 @@
     "esm"
   ],
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=24.14.0"
   }
 }

package/skills/nodefony-add-crud/SKILL.md

@@ -42,6 +42,11 @@ gabarit porte des détails qui ne se devinent pas : le repository résolu au pre
 se connecte qu'au démarrage), la pagination bornée **et son tri déclaré**, les codes
 201/204/404/409/422, et l'en-tête `Location`.
 
+Le controller généré **déclare** ses entrées : chaque route porte un `schema` (`idParams`, le schéma
+de création ou de retouche de l'entité), et l'action reçoit `input` — validé à la porte (422) avant
+tout appel au service, qui revalide pour ses autres portes (CLI, socket). Pour ajouter une action,
+**garde cette forme** : un `@Body` ou un `@Param` sur une action à schéma est refusé au démarrage.
+
 ## La grammaire de champs
 
 `nom:type[?][=défaut][:index|:unique]` — **non-null par défaut**, `?` rend facultatif, `=valeur`

package/skills/nodefony-add-realtime-channel/SKILL.md

@@ -6,9 +6,11 @@ description: >
   Porte la façon de fermer un canal à certains rôles, le piège du canal public par défaut, celui
   du canal dont le nom est calculé, et la façade cliente à employer côté navigateur. À charger
   AVANT d'écrire du code WebSocket, un canal, ou un abonnement client.
+  Dit aussi quand un flux SSE suffit, et sa façade.
   Déclencheurs : "flux temps réel", "websocket", "canal", "push", "notifications en direct",
   "abonnement", "RealtimeController", "@RealtimeChannel", "socket client", "temps réel privé",
-  "réserver un canal à un rôle", "mon canal est public", "diffuser à plusieurs onglets".
+  "réserver un canal à un rôle", "mon canal est public", "diffuser à plusieurs onglets",
+  "SSE", "server-sent events", "EventSource", "barre de progression", "réponse en streaming".
 ---
 
 # add-realtime-channel — le temps réel par sa couche
@@ -37,6 +39,33 @@ câblage. **N'écris pas de `new WebSocket(...)` ni de `ws.on(...)` côté serve
 existe, il est employé par le framework, et le reprendre à la main te prive du routage par canal,
 de l'authentification partagée avec HTTP, et de la contre-pression.
 
+## WebSocket, ou un simple flux SSE ?
+
+| Besoin                                                         | Choisir                                     |
+| -------------------------------------------------------------- | ------------------------------------------- |
+| Le serveur pousse, le client écoute (progression, journal)     | **SSE** — une réponse HTTP qui ne finit pas |
+| La réponse d'UNE requête arrive par morceaux (modèle, export)  | **SSE** sur cette requête                   |
+| Échange dans les deux sens, canaux, état partagé entre onglets | **WebSocket** — le reste de cette page      |
+
+SSE n'est pas une route d'un genre particulier : l'action d'une route ordinaire choisit de
+répondre en flux.
+
+```ts
+@route("progress-run", { path: "/run" })
+async run() {
+  const sse = await this.renderSse();          // en-têtes, battement, contre-pression
+  await sse.send({ step: "calcul" }, { event: "step" });
+  return sse.close();
+}
+```
+
+`this.acceptsSse()` dit si le client a demandé `text/event-stream` (une même route peut répondre
+en JSON ou en flux). Côté navigateur, `new NodefonySse(url)` (`nodefony/client`), qui se lit comme
+`EventSource` ; les liaisons de front existent comme pour la socket. **N'écris jamais
+`Content-Type: text/event-stream` à la main** : tu perdrais le battement qui empêche un proxy de
+couper la connexion, et la contre-pression (`await sse.send()` freine si le client lit lentement).
+Détail : `node_modules/@nodefony/http/docs/sse.md`.
+
 ## Fermer un canal
 
 ```ts
@@ -53,27 +82,55 @@ aucun rôle particulier n'est requis.
 
 ## 🔴 Le piège du canal dont le nom est calculé
 
-Une politique est indexée par le nom **EXACT** du canal. Un canal dont le nom se construit à
-l'exécution (`` `room:${id}` ``) **n'est couvert par aucune politique déclarée** — il naît public,
-et rien ne le signale.
+La politique d'un `@RealtimeChannel` est indexée par le nom **EXACT** du canal. Un canal dont le
+nom se construit à l'exécution (`` `room:${id}` ``) **n'est couvert par aucun décorateur** — il
+naît public, et rien ne le signale.
 
 ```ts
 @RealtimeChannel("room:lobby", { authenticated: true })   // ✅ couvert
-// `room:42` construit à la volée                          // 🔴 PAS couvert
+// `room:42` construit à la volée                          // 🔴 PAS couvert par le décorateur
 ```
 
-Tant qu'un canal à membres n'existe pas dans le framework, le geste montrable est le canal
-**gardé** par rôle ou authentification, pas le canal dynamique.
+La parade est une règle **par préfixe** dans la configuration de sécurité, qui garde à la fois
+les canaux ET les actions dont le nom commence ainsi :
+
+```ts
+use("@nodefony/security", {
+  realtimeChannels: [
+    { pattern: "room:", authenticated: true, roles: ["ROLE_USER"] },
+  ],
+});
+```
+
+Elle exprime une classe d'identité (connecté, rôles), jamais une liste de membres : « seuls les
+participants de la salle 42 » ne s'écrit pas encore dans le framework. Ne le simule pas avec un
+nom de canal difficile à deviner.
+
+## Savoir QUI appelle une action
+
+Les paramètres décorés d'une route valent aussi dans une `@RealtimeAction` : `@Body("clé")` lit la
+charge de l'appel, `@CurrentUser()` l'utilisateur de la connexion (`undefined` pour un anonyme).
+L'auteur d'un message se prend là, côté SERVEUR — jamais dans la charge, où le client peut mentir.
+
+```ts
+@RealtimeAction("chat:send")
+send(@Body("text") text: string, @CurrentUser() user: IUser) {
+  return { author: user.identifier, text };
+}
+```
 
 ## Côté client — la façade, pas le socket
 
 ```ts
-import { RealtimeClient } from "nodefony/client";
+import { NodefonySocket } from "nodefony/client";
 
-const client = RealtimeClient.shared();
+const client = NodefonySocket.shared({ url: "/api/live/realtime" });
 client.subscribe("ops:alerts", (payload) => { … });
 ```
 
+L'adresse est **obligatoire** : `shared()` sans `url` lève une erreur, parce que la route dépend de
+l'application. Une application générée monte `/api/live/realtime`.
+
 En React, les hooks du paquet client font la même chose avec le cycle de vie du composant.
 **Importe depuis `nodefony/client`**, jamais depuis la racine `nodefony` : côté navigateur, elle
 n'expose pas ces symboles et le compilateur refuse.

package/skills/nodefony-add-service/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Crée un service injectable dans une application Nodefony par `nodefony create service`, et le
   fait entrer dans le conteneur — la moitié qu'on oublie. Porte la distinction entre le nom de la
   CLASSE et le nom de l'INSTANCE, les deux façons d'obtenir un service depuis un autre
-  (`@inject` au constructeur ou `container.get` à l'usage), le choix de sa durée de vie
+  (`@Inject` au constructeur ou `container.get` à l'usage), le choix de sa durée de vie
   (un exemplaire pour l'application, ou un par requête), et le défaut mesuré qu'un service
   écrit à la main produit : une classe qui compile, dont les tests passent, et que le conteneur
   ignore. À charger AVANT d'écrire une classe de service ou d'appeler un service depuis un autre.
@@ -63,7 +63,7 @@ et à l'introspection, et n'est construit qu'à la première requête qui le ré
 C'est le piège n°1, et il ne produit aucune erreur — juste un `null` :
 
 ```ts
-@injectable()                            // ← nomme la CLASSE : @inject("BillingService")
+@injectable()                            // ← nomme la CLASSE : @Inject("BillingService")
 export class BillingService extends Service {
   constructor() {
     super("billing", ...);               // ← nomme l'INSTANCE : container.get("billing")
@@ -88,11 +88,22 @@ dépend est refusé au démarrage. Pour **lire** une donnée de la requête depu
 besoin de portée : `RequestContext.getScope()` ou `RequestContext.get()` au moment de l'appel.
 Détail : `node_modules/nodefony/docs/service.md`.
 
+**Qui est connecté, depuis un service** : `RequestContext.getAuthenticatedUser()` (l'utilisateur
+connecté, ou `null`) et `RequestContext.getUserId()` (`string | null`). Jamais
+`RequestContext.getUser()` pour décider : il rend l'utilisateur BRUT, anonyme compris.
+
+**Le payload de la requête est une forme FERMÉE** (`RequestContextPayload`) :
+`RequestContext.set("maCle", …)` sur une clé qu'il ne déclare pas ne compile pas. Ta clé s'ajoute
+par augmentation — `declare module "nodefony" { interface RequestContextPayload { tenant?: string } }`
+— mais `RequestContext.release()`, qui vide le payload à la fin de l'unité de travail, ne la
+vide PAS d'office.
+Détail : `node_modules/nodefony/docs/request-context.md`.
+
 ## Obtenir un service depuis un autre — deux voies, un choix
 
 | Voie                           | Quand                                                                         |
 | ------------------------------ | ----------------------------------------------------------------------------- |
-| `@inject("X")` au constructeur | **par défaut** — la dépendance est déclarée, l'ordre de démarrage la respecte |
+| `@Inject("X")` au constructeur | **par défaut** — la dépendance est déclarée, l'ordre de démarrage la respecte |
 | `container.get("x")` à l'usage | quand la dépendance est facultative, tardive, ou choisie à l'exécution        |
 
 `create service --inject` pose la première. Le second est visible partout dans les exemples, et