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

package/README.md

@@ -228,13 +228,17 @@ npx nodefony ai:sync            # --dry-run pour voir sans écrire, --json pour
   = nodefony-add-crud              @nodefony/devkit
   = nodefony-add-realtime-channel  @nodefony/devkit
   = nodefony-add-service           @nodefony/devkit
+  = nodefony-authentication        @nodefony/devkit
   = nodefony-browser               @nodefony/devkit
   = nodefony-dev                   @nodefony/devkit
   = nodefony-devops                @nodefony/devkit
   = nodefony-migrate-schema        @nodefony/devkit
   = nodefony-protect-route         @nodefony/devkit
+  = nodefony-security-review       @nodefony/devkit
+  = nodefony-troubleshoot          @nodefony/devkit
+  = nodefony-upgrade               @nodefony/devkit
 
-  0 posé(s) · 0 mis à jour · 8 inchangé(s)
+  0 posé(s) · 0 mis à jour · 12 inchangé(s)
 ```
 
 **Le préfixe `nodefony-` vous laisse la place.** Ces pointeurs arrivent dans

package/dist/_virtual/{_@oxc-project_runtime@0.152.0 → _@oxc-project_runtime@0.153.0}/helpers/esm/decorate.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.152.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);

package/dist/_virtual/{_@oxc-project_runtime@0.152.0 → _@oxc-project_runtime@0.153.0}/helpers/esm/decorateMetadata.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.152.0/helpers/esm/decorateMetadata.js
+//#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorateMetadata.js
 function __decorateMetadata(k, v) {
 	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }

package/dist/_virtual/{_@oxc-project_runtime@0.152.0 → _@oxc-project_runtime@0.153.0}/helpers/esm/decorateParam.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.152.0/helpers/esm/decorateParam.js
+//#region \0@oxc-project+runtime@0.153.0/helpers/esm/decorateParam.js
 function __decorateParam(paramIndex, decorator) {
 	return function(target, key) {
 		decorator(target, key, paramIndex);

package/dist/index.js

@@ -1,8 +1,8 @@
 import defaults, { devkitConfigSchema } from "./nodefony/config/config.js";
 import { defineDevkitConfig } from "./nodefony/config/defineModuleConfig.js";
 import { buildCard } from "./nodefony/src/card.js";
-import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import __decorate from "./_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import __decorate from "./_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
 import DevkitService_default from "./nodefony/service/DevkitService.js";
 import DevkitController_default from "./nodefony/controllers/DevkitController.js";
 import McpController_default from "./nodefony/controllers/McpController.js";

package/dist/nodefony/controllers/DevkitController.js

@@ -1,5 +1,5 @@
-import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
 import { Controller, controller, route } from "@nodefony/framework";
 //#region nodefony/controllers/DevkitController.ts
 /**

package/dist/nodefony/controllers/McpController.js

@@ -1,10 +1,15 @@
-import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
-import __decorateParam from "../../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateParam.js";
-import { ACCESS_TOKEN_VERIFIER, JsonRpcError, Nodefony, authorizeProtectedResource, checkMcpAccess, collectMcpTools, handleMcpMessage, jsonRpcFailure, mcpCallerRoles, protectedResourceMetadataUrl, readBearerHeader } from "nodefony";
+import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
+import __decorateParam from "../../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateParam.js";
+import { ACCESS_TOKEN_VERIFIER, JsonRpcError, Nodefony, authorizeProtectedResource, checkMcpAccess, collectMcpTools, createMcpResponseStream, handleMcpMessage, jsonRpcFailure, mcpCallerRoles, protectedResourceMetadataUrl, readBearerHeader } from "nodefony";
 import { Body, Controller, Headers, controller, route } from "@nodefony/framework";
 //#region nodefony/controllers/McpController.ts
 /**
+* Plafond d'un événement sur le flux de réponse MCP, octets UTF-8 — celui de la
+* réponse finale, qui porte le résultat entier de l'outil (16 Mio).
+*/
+const MCP_STREAM_MAX_EVENT_BYTES = 16777216;
+/**
 * Serveur **Model Context Protocol** de l'application — la porte par laquelle
 * un agent externe l'interroge.
 *
@@ -99,6 +104,29 @@ let McpController = class McpController extends Controller {
 		return read.kind === "token" && read.token.startsWith("${") && read.token.endsWith("}");
 	}
 	/**
+	* Le corps reçu est-il un texte qui ne se PARSE pas en JSON ?
+	*
+	* Le parseur HTTP ignore un JSON malformé et laisse `@Body()` à `{}` : seul
+	* le brut (`request.data`) permet alors de distinguer un `{}` envoyé d'un
+	* texte illisible. Relu uniquement quand le corps n'a aucune clé.
+	*
+	* @param body - corps tel que `@Body()` le rend
+	* @returns `true` si le texte reçu n'est pas du JSON
+	*/
+	#unparsableBody(body) {
+		if (body === null || typeof body !== "object" || Array.isArray(body) || Object.keys(body).length > 0) return false;
+		const request = this.request;
+		if (!request || !("data" in request)) return false;
+		const text = request.data.toString(request.charset).trim();
+		if (text === "") return false;
+		try {
+			JSON.parse(text);
+			return false;
+		} catch {
+			return true;
+		}
+	}
+	/**
 	* `POST /nodefony/mcp` — un message JSON-RPC entre, une réponse sort.
 	*
 	* Les trois statuts que rend cette route sont ceux que la spec impose, et pas
@@ -121,7 +149,8 @@ let McpController = class McpController extends Controller {
 			this.log(`MCP refusé — ${verdict.why}`, "WARNING");
 			return this.renderJson(jsonRpcFailure(null, JsonRpcError.INVALID_REQUEST, "origine refusée"), 403);
 		}
-		if (body === null || typeof body !== "object") return this.renderJson(jsonRpcFailure(null, JsonRpcError.PARSE_ERROR, "corps attendu : un message JSON-RPC"), 400);
+		if (this.#unparsableBody(body)) return this.renderJson(jsonRpcFailure(null, JsonRpcError.PARSE_ERROR, "corps illisible : JSON invalide"), 400);
+		if (body === null || typeof body !== "object") return this.renderJson(jsonRpcFailure(null, JsonRpcError.INVALID_REQUEST, "corps attendu : un message JSON-RPC (objet)"), 400);
 		const authz = settings.authorization;
 		const gateProtected = settings.authorization.authorizationServers.length > 0;
 		let caller = {
@@ -186,23 +215,50 @@ let McpController = class McpController extends Controller {
 			},
 			deps: this.#service().mcpToolDeps()
 		});
+		const context = this.context;
+		const stream = createMcpResponseStream({
+			signal: context?.signal,
+			open: this.acceptsSse() ? () => this.renderSse({ maxEventBytes: MCP_STREAM_MAX_EVENT_BYTES }) : void 0,
+			onError: (error, final) => this.log(`MCP — ${final ? "réponse finale" : "notification"} perdue sur le flux : ${error instanceof Error ? error.message : String(error)}`, final ? "WARNING" : "DEBUG")
+		});
 		const reply = await handleMcpMessage(body, {
 			tools,
 			caller,
 			withheldCount,
+			transport: stream.transport,
 			serverInfo: {
 				name: kernel?.projectName ?? "nodefony",
 				version: Nodefony.version
 			}
 		}, { protocolVersion });
+		if (reply.failure) {
+			const { tool, error } = reply.failure;
+			this.log(`MCP — l'outil « ${tool} » a levé : ${error instanceof Error ? error.stack ?? error.message : String(error)}`, "ERROR");
+		}
+		const sse = await stream.finish(reply.body);
+		if (sse !== null) return sse.close();
 		if (reply.body === null) return this.renderResponse("", void 0, reply.status);
 		return this.renderJson(reply.body, reply.status);
 	}
+	/**
+	* `GET` et `DELETE /nodefony/mcp` — refusés en `405`, avec `Allow: POST`.
+	*
+	* Un client d'une révision antérieure du transport ouvre un flux SSE en `GET`
+	* et clôt sa session en `DELETE` ; la révision `2026-07-28` a retiré les deux
+	* et demande ce `405` (transports, « Earlier Streamable HTTP Revisions »).
+	* Sans cette route, la requête tombait dans le repli SPA du Studio
+	* (`/nodefony/{page}`) : `200` + HTML, que le client prenait pour un flux
+	* rompu et rouvrait à chaque seconde, indéfiniment.
+	*/
+	unsupported() {
+		if (!this.#service().mcpSettings().enabled) return this.renderJson({ error: "MCP désactivé" }, 404);
+		return this.renderResponse("", void 0, 405, { allow: "POST" });
+	}
 };
 __decorate([
 	route("devkit-mcp", {
 		path: "/mcp",
-		method: "POST"
+		requirements: { methods: ["POST"] }
 	}),
 	__decorateParam(0, Body()),
 	__decorateParam(1, Headers("origin")),
@@ -217,6 +273,15 @@ __decorate([
 	]),
 	__decorateMetadata("design:returntype", Promise)
 ], McpController.prototype, "mcp", null);
+__decorate([
+	route("devkit-mcp-unsupported", {
+		path: "/mcp",
+		requirements: { methods: ["GET", "DELETE"] }
+	}),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", []),
+	__decorateMetadata("design:returntype", void 0)
+], McpController.prototype, "unsupported", null);
 McpController = __decorate([controller("/nodefony"), __decorateMetadata("design:paramtypes", [Object])], McpController);
 var McpController_default = McpController;
 //#endregion

package/dist/nodefony/service/DevkitService.js

@@ -1,7 +1,7 @@
 import defaults from "../config/config.js";
 import { buildCard } from "../src/card.js";
-import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import __decorate from "../../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
 import { Module, Nodefony, Service, extend, injectable, mcpDeclaredScopes } from "nodefony";
 //#region nodefony/service/DevkitService.ts
 /**

package/dist/nodefony/src/card.js

@@ -1,2 +1 @@
-import { buildCard, renderCard } from "nodefony";
-export { buildCard, renderCard };
+export { buildCard, renderCard } from "nodefony";

package/dist/types/nodefony/controllers/McpController.d.ts

@@ -65,6 +65,17 @@ declare class McpController extends Controller {
      * inconnue (afin de la distinguer d'un serveur qui n'hébergerait pas
      * d'endpoint MCP du tout).
      */
-    mcp(body: unknown, origin?: string, protocolVersion?: string, authorization?: string): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    mcp(body: unknown, origin?: string, protocolVersion?: string, authorization?: string): Promise<void | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /**
+     * `GET` et `DELETE /nodefony/mcp` — refusés en `405`, avec `Allow: POST`.
+     *
+     * Un client d'une révision antérieure du transport ouvre un flux SSE en `GET`
+     * et clôt sa session en `DELETE` ; la révision `2026-07-28` a retiré les deux
+     * et demande ce `405` (transports, « Earlier Streamable HTTP Revisions »).
+     * Sans cette route, la requête tombait dans le repli SPA du Studio
+     * (`/nodefony/{page}`) : `200` + HTML, que le client prenait pour un flux
+     * rompu et rouvrait à chaque seconde, indéfiniment.
+     */
+    unsupported(): import("nodefony").MaybePromise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
 }
 export default McpController;

package/docs/index.md

@@ -277,6 +277,50 @@ 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 l'agent abandonne l'appel, `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 ne s'ouvre qu'à la première progression.** 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. Sans jeton, ou
+  pour un outil qui ne signale rien, la réponse reste du 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 +328,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.3",
   "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>",
@@ -25,20 +25,20 @@
     "coverage": "vitest run --coverage"
   },
   "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/framework": "^10.0.0-beta.3",
+    "@nodefony/http": "^10.0.0-beta.3",
+    "nodefony": "^10.0.0-beta.3",
+    "zod": "^4.6.7",
     "playwright": "^1.50.0",
     "lighthouse": "^13.0.0"
   },
   "devDependencies": {
-    "@nodefony/framework": "^10.0.0-beta.2",
-    "@nodefony/http": "^10.0.0-beta.2",
-    "nodefony": "^10.0.0-beta.2"
+    "@nodefony/framework": "^10.0.0-beta.3",
+    "@nodefony/http": "^10.0.0-beta.3",
+    "nodefony": "^10.0.0-beta.3"
   },
   "dependencies": {
-    "axe-core": "4.13.0",
+    "axe-core": "4.14.0",
     "tslib": "2.8.1"
   },
   "peerDependenciesMeta": {

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

@@ -88,6 +88,17 @@ 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                                                                         |