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

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-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")
@@ -103,7 +103,7 @@ Détail : `node_modules/nodefony/docs/request-context.md`.
 
 | 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

package/skills/nodefony-authentication/SKILL.md

@@ -207,11 +207,11 @@ l'audience absente : `--write`, puis réimport. Détail :
 Un script, une tâche planifiée, un agent n'ont ni navigateur ni cookie : ils présentent une
 preuve à chaque appel, `Authorization: Bearer …`.
 
-| Preuve                          | L'obtenir                                                       |
-| ------------------------------- | --------------------------------------------------------------- |
-| clé d'API opaque (`nf_…`)       | `POST /nodefony/security/api/keys` (session d'administration)   |
-| jeton signé par l'application   | `npx nodefony security:token [compte] --scope … --ttl … --json` |
-| jeton Keycloak (client machine) | `requestClientCredentialsToken` de `@nodefony/security`         |
+| Preuve                          | L'obtenir                                                           |
+| ------------------------------- | ------------------------------------------------------------------- |
+| clé d'API opaque (`nf_…`)       | `POST /nodefony/security/api/keys` (session d'administration)       |
+| jeton signé par l'application   | `npx nodefony security:mcp:token [compte] --scope … --ttl … --json` |
+| jeton Keycloak (client machine) | `requestClientCredentialsToken` de `@nodefony/security`             |
 
 ❌ Un `POST` vers la route de login depuis un script, ou un cookie de session recopié dans sa
 configuration : le premier fait stocker un mot de passe au programme, le second expire et casse

package/skills/nodefony-browser/SKILL.md

@@ -381,6 +381,26 @@ en bout : le message part-il, revient-il, et l'écran le reçoit-il ?
 > lui, vaut pour toute attente que tu écriras : tant qu'elle n'a pas échoué une fois, elle ne
 > discrimine rien.
 
+### Éprouver la REPRISE après une coupure réseau — `NF_BROWSER_CUT`
+
+```bash
+docker exec -e NF_BROWSER_CUT=5000:4000 mon-app-browser node /app/see-screen/watch.mjs /tableau-de-bord 25000
+```
+
+`<début>:<durée>` en millisecondes : le réseau tombe 5 s après l'ouverture de la page, revient 4 s
+plus tard. Chaque socket coupé sort avec `closedAt` et `closeCode` (1006, ce que voit un client
+qui perd le réseau), le bloc `cut` compte les réouvertures refusées pendant la coupure, et le
+socket rouvert montre ses frames : l'accueil, les abonnements rejoués, leur acquittement, puis le
+flux. C'est la seule preuve qu'une page qui perd le réseau **retrouve** ses données.
+
+- **Le serveur est prévenu** (fermeture 1000) : la connexion coupée ne reste pas à demi ouverte
+  chez lui. Une vraie perte de réseau, elle, ne le prévient pas. La sonde éprouve la reprise du
+  client, pas la détection d'un pair mort.
+- **Le relais Vite (`/_vite/`) n'est pas coupé** : son client de rechargement à chaud recharge la
+  page quand il retrouve le serveur. Vous observeriez une page neuve, pas sa reprise.
+- **Les `ERR_INTERNET_DISCONNECTED` de la console pendant la coupure sont attendus.**
+- Une valeur malformée est refusée (code 64), jamais ignorée.
+
 ## Piloter le socket de bout en bout — `socket.mjs`
 
 `watch.mjs` regarde le trafic d'une page ; celui-ci **conduit** : il ouvre un socket temps réel

package/skills/nodefony-browser/references/socket.md

@@ -36,10 +36,19 @@ Deux frames servent de repères :
 
 ### `welcome`
 
-`receivedAfterMs`, canaux, méthodes, identité. **S'il ne vient jamais** (code de retour 65), les trois
-suspects, dans l'ordre : le chemin du endpoint est faux ; la page n'est pas authentifiée (donner
-`NF_BROWSER_USER` + `NF_BROWSER_LOGIN`) ; l'`Origin` de la page est refusé par le serveur. Le
-réseau qui « passe » n'innocente aucun des trois.
+`verdict`, `receivedAfterMs`, canaux, méthodes, identité. **S'il ne vient jamais** (code de retour
+65), la sortie dit lequel des deux cas :
+
+- **`REFUSÉ AU HANDSHAKE`** — le serveur a répondu autre chose que `101` : la socket ne s'est jamais
+  ouverte, et la sonde le rend tout de suite avec `status`, `afterMs` et la `browserReason` du
+  navigateur (la page ne voit qu'une fermeture `1006` ; le statut, seul le navigateur le connaît).
+  `401` : la page n'est pas authentifiée (donner `NF_BROWSER_USER` + `NF_BROWSER_LOGIN`) ; `403` :
+  le compte n'a pas le rôle, ou l'`Origin` de la page est refusé ; `404` : le chemin du endpoint
+  est faux. Chromium ne nomme pas le code d'un `401` porteur de `WWW-Authenticate` (« HTTP
+  Authentication failed ») : la sonde le traduit.
+- **Rien sur la sortie standard, message « en 8000 ms »** — la socket s'est ouverte mais l'accueil
+  n'est jamais venu : l'endpoint n'est pas un endpoint temps réel Nodefony, ou le serveur ferme
+  après l'ouverture. Le réseau qui « passe » n'innocente rien.
 
 ### `subscription`
 

package/skills/nodefony-browser/scripts/inspect.mjs

@@ -789,7 +789,7 @@ if (active.has("reseau")) {
   const slowThreshold = Number(process.env.NF_BROWSER_SEUIL_LENT ?? 1000);
   const items = await Promise.all(
     finishedRequests.map(async (rq) => {
-      let bytes = null;
+      let bytes;
       try {
         // `sizes()` rend la taille RÉELLEMENT transférée ; l'en-tête
         // content-length manque sur les réponses en flux.

package/skills/nodefony-browser/scripts/lib/probes.mjs

@@ -240,6 +240,44 @@ export function parseColorScheme(raw) {
   return { schema: null, invalid: v };
 }
 
+/**
+ * Analyse une coupure réseau demandée (`NF_BROWSER_CUT`), au format
+ * `<début>:<durée>` en millisecondes — `4000:3000` coupe le réseau 4 s après
+ * l'ouverture de la page et le rétablit 3 s plus tard.
+ *
+ * La coupure existe pour éprouver une REPRISE : un flux temps réel qui revient
+ * après une perte de réseau ne se constate sur aucune capture. Une valeur
+ * malformée est REFUSÉE : ignorée, elle ferait observer une page jamais coupée
+ * en croyant avoir éprouvé sa reprise.
+ *
+ * @param {string|undefined} raw - valeur brute (`"4000:3000"`, vide).
+ * @returns {{ cut: { at: number, duration: number }|null, invalid: string|null }}
+ *   `cut` à null quand rien n'est demandé.
+ */
+export function parseCut(raw) {
+  const v = (raw ?? "").trim();
+  if (!v) return { cut: null, invalid: null };
+  const m = /^(\d+):(\d+)$/.exec(v);
+  if (!m || Number(m[2]) === 0) return { cut: null, invalid: v };
+  return { cut: { at: Number(m[1]), duration: Number(m[2]) }, invalid: null };
+}
+
+/**
+ * Ramène un code de fermeture WebSocket à un code qu'un NAVIGATEUR peut
+ * émettre : 1000, ou 3000 à 4999 — tout autre lève `InvalidAccessError`.
+ *
+ * 🔴 Le côté serveur d'une route Playwright est un vrai WebSocket de page.
+ * Fermé avec 1001 ou 1006, il refuse, Playwright avale l'erreur et rend « ok » :
+ * la connexion réelle reste ouverte et le serveur continue de pousser vers un
+ * socket que la sonde dit fermé. Mesuré : 47 s sans fermeture côté serveur.
+ *
+ * @param {number} code - le code voulu.
+ * @returns {number} ce code s'il est émissible, 1000 sinon.
+ */
+export function sendableCloseCode(code) {
+  return code === 1000 || (code >= 3000 && code <= 4999) ? code : 1000;
+}
+
 /**
  * Arguments de lancement qui imposent le schéma de couleurs AU MOTEUR.
  *
@@ -483,6 +521,21 @@ export function median(values) {
   const m = Math.floor(sorted.length / 2);
   return sorted.length % 2 === 1 ? sorted[m] : (sorted[m - 1] + sorted[m]) / 2;
 }
+
+/**
+ * Arrondit une durée au centième de milliseconde — la précision d'un RTT local.
+ *
+ * Un arrondi à la milliseconde entière rend 0 pour tout aller-retour sous
+ * 0,5 ms : sur une même machine, la sonde annonçait une latence nulle. Le
+ * centième reste sous la résolution de `performance.now()` côté navigateur
+ * (~0,1 ms hors isolation), donc ne fabrique aucune précision qui n'existe pas.
+ *
+ * @param {number} ms - durée brute en millisecondes.
+ * @returns {number} la durée arrondie à 0,01 ms.
+ */
+export function roundMs(ms) {
+  return Math.round(ms * 100) / 100;
+}
 /**
  * Résume un rapport axe-core en un bloc lisible — le tri éditorial, pas la mesure.
  *

package/skills/nodefony-browser/scripts/socket.mjs

@@ -24,10 +24,10 @@
  * `@env` NF_BROWSER_PINGS nombre de mesures de latence (défaut 5)
  * `@requires` conteneur du profil `browser` démarré · serveur joignable · un endpoint temps réel exposé
  * `@output` un objet JSON sur stdout : accueil, abonnement, latence, api, reconnexion — un verdict par étape
- * `@exit` 0 scénario joué (les verdicts sont des DONNÉES) · 64 usage (endpoint manquant, params illisibles) · 65 accueil jamais reçu
+ * `@exit` 0 scénario joué (les verdicts sont des DONNÉES) · 64 usage (endpoint manquant, params illisibles) · 65 accueil jamais reçu (refus au handshake : JSON sur stdout, statut nommé)
  */
 import { open, goTo } from "./lib/browser.mjs";
-import { median } from "./lib/probes.mjs";
+import { median, roundMs } from "./lib/probes.mjs";
 
 const ENDPOINT = process.argv[2] ?? process.env.NF_BROWSER_SOCKET ?? "";
 if (!ENDPOINT.startsWith("/")) {
@@ -95,6 +95,13 @@ async function scenarioSocket(conf) {
   const openSocket = () =>
     new Promise((resolve, reject) => {
       const ws = new WebSocket(url);
+      // Une fermeture AVANT l'ouverture est un refus du HANDSHAKE (réponse
+      // non-101 : 401, 403, 404…) — rien à attendre, et surtout pas les huit
+      // secondes du garde, qui feraient lire un refus net comme un silence.
+      let opened = false;
+      ws.addEventListener("open", () => {
+        opened = true;
+      });
       const guard = setTimeout(() => {
         try {
           ws.close();
@@ -105,6 +112,14 @@ async function scenarioSocket(conf) {
       }, conf.timeoutMs);
       ws.addEventListener("close", (ev) => {
         closes.push({ a: a(), code: ev.code, reason: ev.reason });
+        if (!opened) {
+          clearTimeout(guard);
+          const refusal = new Error(
+            `accueil jamais reçu : connexion refusée au handshake sur ${url}`,
+          );
+          refusal.handshake = { afterMs: a(), closeCode: ev.code };
+          reject(refusal);
+        }
       });
       ws.addEventListener("message", (ev) => {
         let frame;
@@ -166,7 +181,8 @@ async function scenarioSocket(conf) {
       const settle = (value) => {
         if (settled) return;
         settled = true;
-        resolve({ ...value, ms: Math.round(performance.now() - start) });
+        // Durée BRUTE : l'arrondi se fait côté Node (`roundMs`), où il s'éprouve.
+        resolve({ ...value, ms: performance.now() - start });
       };
       const guard = setTimeout(() => {
         pending.delete(id);
@@ -181,8 +197,21 @@ async function scenarioSocket(conf) {
       ws.send(JSON.stringify(frame));
     });
 
-  const { ws, welcome } = await openSocket();
+  let first;
+  try {
+    first = await openSocket();
+  } catch (e) {
+    // Le refus au handshake est une RÉPONSE du serveur, pas une panne de la
+    // sonde : il se rend en données (le pilote y joint le statut HTTP que seul
+    // le navigateur connaît — la page ne voit qu'un code de fermeture 1006).
+    if (!e?.handshake) throw e;
+    result.welcome = { verdict: "REFUSÉ AU HANDSHAKE", ...e.handshake };
+    result.closes = closes;
+    return result;
+  }
+  const { ws, welcome } = first;
   result.welcome = {
+    verdict: "OK",
     receivedAfterMs: a(),
     protocol: welcome.protocol ?? null,
     channels: welcome.channels ?? [],
@@ -330,6 +359,19 @@ async function scenarioSocket(conf) {
 const { browser, ctx, page, reuse } = await open();
 await goTo(page, ctx, process.env.NF_BROWSER_PAGE ?? "/", reuse);
 
+// Le statut HTTP d'un handshake refusé n'existe que pour le NAVIGATEUR : la
+// page n'en reçoit qu'un code de fermeture 1006. Le pilote l'écoute là où le
+// navigateur le dit — l'erreur du socket et la console.
+const handshakeErrors = [];
+page.on("websocket", (socket) => {
+  socket.on("socketerror", (error) => handshakeErrors.push(String(error)));
+});
+page.on("console", (message) => {
+  if (message.type() === "error" && message.text().includes("WebSocket")) {
+    handshakeErrors.push(message.text());
+  }
+});
+
 let result;
 try {
   result = await page.evaluate(scenarioSocket, cfg);
@@ -344,11 +386,35 @@ try {
   process.exit(65); // EX_DATAERR
 }
 
+if (result.welcome?.verdict === "REFUSÉ AU HANDSHAKE") {
+  // Les messages du navigateur arrivent par le protocole de débogage, parfois
+  // juste APRÈS la fermeture vue par la page : une courte attente bornée.
+  if (handshakeErrors.length === 0) await page.waitForTimeout(500);
+  const reason = handshakeErrors[0]?.slice(0, 300) ?? null;
+  // Chromium nomme le code (« Unexpected response code: 404 ») SAUF pour un
+  // 401 porteur de `WWW-Authenticate` : il le traite en défi d'authentification
+  // qu'il ne sait pas satisfaire, et ne dit que cela.
+  const status = /HTTP Authentication failed/i.test(reason ?? "")
+    ? "401"
+    : /\b([1-5]\d\d)\b/.exec(reason ?? "")?.[1];
+  result.welcome.status = status ? Number(status) : null;
+  result.welcome.browserReason = reason;
+  console.log(JSON.stringify(result, null, 2));
+  console.error(
+    `Accueil jamais reçu : le serveur a REFUSÉ le handshake (statut ${result.welcome.status ?? "non communiqué par le navigateur"}).\n` +
+      `→ 401/403 : la page ${process.env.NF_BROWSER_PAGE ?? "/"} n'est pas authentifiée, ou le compte n'a pas le droit (NF_BROWSER_USER + NF_BROWSER_LOGIN) ; 404 : chemin du endpoint faux ; 403 sur une page authentifiée : Origin refusé.`,
+  );
+  await browser.close();
+  process.exit(65); // EX_DATAERR — l'accueil n'est pas venu, la cause est nommée
+}
+
 // La médiane se calcule ici, avec la fonction que les tests éprouvent — la
 // moyenne serait déplacée par un seul aller-retour aberrant.
 if (Array.isArray(result.latency?.measuresMs)) {
+  result.latency.measuresMs = result.latency.measuresMs.map(roundMs);
   result.latency.medianMs = median(result.latency.measuresMs);
 }
+if (typeof result.api?.ms === "number") result.api.ms = roundMs(result.api.ms);
 
 console.log(JSON.stringify(result, null, 2));
 await browser.close();

package/skills/nodefony-browser/scripts/watch.mjs

@@ -13,16 +13,27 @@
  * `@env` NF_BROWSER_USER identifiant ; sans lui, aucune authentification n'est tentée
  * `@env` NF_BROWSER_PASSWORD mot de passe associé
  * `@env` NF_BROWSER_UNTIL expression JS évaluée DANS la page ; l'observation s'arrête dès qu'elle est vraie (point d'arrêt applicatif)
+ * `@env` NF_BROWSER_CUT coupure réseau `<début>:<durée>` en ms (`4000:3000`), comptée depuis l'ouverture de la page — éprouve la REPRISE d'un flux ; chaque socket dit alors quand il s'est fermé et rouvert
  * `@env` NF_BROWSER_MAXFRAMES nombre de frames WebSocket conservées par sens (défaut 12)
  * `@requires` conteneur du profil `browser` démarré · serveur Nodefony joignable
  * `@output` JSON : sockets et leurs frames (horodatées), requêtes non-2xx, erreurs console, verdict de la condition
  */
 import { open, goTo } from "./lib/browser.mjs";
+import { parseCut, sendableCloseCode } from "./lib/probes.mjs";
 
 const PAGE = process.argv[2] ?? process.env.NF_BROWSER_PAGE ?? "/";
 const DURATION = Number(process.argv[3] ?? 8000);
 const UNTIL = process.env.NF_BROWSER_UNTIL ?? "";
 const MAX = Number(process.env.NF_BROWSER_MAXFRAMES ?? 12);
+const { cut: CUT, invalid: invalidCut } = parseCut(process.env.NF_BROWSER_CUT);
+if (invalidCut) {
+  console.error(
+    `NF_BROWSER_CUT attend « <début>:<durée> » en ms (ex. 4000:3000), reçu « ${invalidCut} »`,
+  );
+  process.exit(64);
+}
+// Sockets que la coupure FERME (cf « La coupure réseau » plus bas).
+const isRouted = (url) => !new URL(url).pathname.startsWith("/_vite/");
 
 const { browser, ctx, page, reuse } = await open();
 
@@ -39,6 +50,9 @@ const uncaughtErrors = [];
 // qu'on ne lit, et une sortie de plusieurs mégaoctets serait illisible — donc
 // inexploitable pour décider. On garde les premières de chaque sens.
 page.on("websocket", (ws) => {
+  // Un socket routé pour la coupure est enregistré par la route : l'écouter
+  // ici aussi le compterait deux fois.
+  if (CUT && isRouted(ws.url())) return;
   const rec = { url: ws.url(), openedAt: at(), sent: [], received: [] };
   sockets.push(rec);
   ws.on("framesent", (f) => {
@@ -72,8 +86,88 @@ page.on("pageerror", (e) => {
     uncaughtErrors.push({ a: at(), text: String(e).slice(0, 200) });
 });
 
+// ── La coupure réseau : éprouver une REPRISE ────────────────────────────────
+// `setOffline` seul ne suffit PAS : Chromium y coupe le HTTP mais laisse les
+// WebSockets déjà ouverts vivre — mesuré, aucun `close` n'est émis, et l'on
+// « éprouverait » une reprise sans qu'aucune connexion ait été perdue. Les
+// sockets passent donc par `routeWebSocket` : à la coupure, la sonde ferme
+// chaque connexion des deux côtés — 1006 vers la page, ce que voit un client
+// qui perd le réseau ; 1000 vers le serveur, qui libère la connexion au lieu de
+// la garder à demi ouverte — et refuse toute réouverture jusqu'au
+// rétablissement.
+// Le relais Vite (`/_vite/`) est épargné : son client de rechargement à chaud
+// RECHARGE la page quand il retrouve le serveur, et la reprise observée serait
+// celle d'une page neuve, pas celle de l'application.
+let cut = null;
+let cutActive = false;
+const cutTimers = [];
+const routed = new Set();
+// Le côté SERVEUR d'une route est un vrai WebSocket de navigateur : son code
+// de fermeture passe par `sendableCloseCode` (cf son TSDoc).
+if (CUT) {
+  cut = { requested: CUT, refused: 0 };
+  await ctx.routeWebSocket(isRouted, (route) => {
+    if (cutActive) {
+      cut.refused += 1;
+      route.close({ code: 1006, reason: "coupure réseau (sonde)" });
+      return;
+    }
+    const server = route.connectToServer();
+    const rec = { url: route.url(), openedAt: at(), sent: [], received: [] };
+    sockets.push(rec);
+    const pair = { route, server, rec };
+    routed.add(pair);
+    // Poser `onMessage` coupe le relais automatique : on relaie à la main.
+    route.onMessage((m) => {
+      if (rec.sent.length < MAX)
+        rec.sent.push({ a: at(), payload: String(m).slice(0, 160) });
+      server.send(m);
+    });
+    server.onMessage((m) => {
+      if (rec.received.length < MAX)
+        rec.received.push({ a: at(), payload: String(m).slice(0, 160) });
+      route.send(m);
+    });
+    const closed = (code) => {
+      rec.closedAt ??= at();
+      rec.closeCode ??= code;
+      routed.delete(pair);
+    };
+    route.onClose((code, reason) => {
+      closed(code);
+      server.close({ code: sendableCloseCode(code), reason });
+    });
+    server.onClose((code, reason) => {
+      closed(code);
+      route.close({ code, reason });
+    });
+  });
+}
+
 await goTo(page, ctx, PAGE, reuse);
 
+if (CUT) {
+  cutTimers.push(
+    setTimeout(() => {
+      cut.offlineAt = at();
+      cutActive = true;
+      ctx.setOffline(true).catch((e) => (cut.error = String(e)));
+      for (const { route, server, rec } of routed) {
+        rec.closedAt ??= at();
+        rec.closeCode ??= 1006;
+        server.close({ code: 1000, reason: "coupure réseau (sonde)" });
+        route.close({ code: 1006, reason: "coupure réseau (sonde)" });
+      }
+      routed.clear();
+    }, CUT.at),
+    setTimeout(() => {
+      cut.onlineAt = at();
+      cutActive = false;
+      ctx.setOffline(false).catch((e) => (cut.error = String(e)));
+    }, CUT.at + CUT.duration),
+  );
+}
+
 // ── Le « point d'arrêt » : une CONDITION, pas une ligne de code ──────────────
 // `waitForFunction` réévalue l'expression dans la page à chaque animation frame.
 // C'est ce qui remplace utilement un breakpoint dans un pilotage automatisé :
@@ -100,12 +194,19 @@ if (UNTIL) {
   await page.waitForTimeout(DURATION);
 }
 
+for (const t of cutTimers) clearTimeout(t);
+if (cut && cut.onlineAt === undefined) {
+  cutActive = false;
+  await ctx.setOffline(false);
+}
+
 console.log(
   JSON.stringify(
     {
       url: page.url(),
       observeForMs: at(),
       verdict,
+      cut,
       // Les totaux sont posés sur l'objet accumulé plutôt que recomposés par
       // étalement dans un `map` (règle `no-map-spread` : allocation inutile).
       sockets: sockets.map((s) =>

package/skills/nodefony-dev/SKILL.md

@@ -128,6 +128,11 @@ Elle répond **toujours** — application pas encore construite, terminal sans a
 d'environnement : elle ne lit que des fichiers. Elle le DIT alors (« modules installés », pas
 « chargés ») et renvoie à `inspect modules` pour ce qui est vraiment monté.
 
+**`rg` ou outil MCP ?** Question étroite, format connu (un motif, un fichier) → `rg`, bien moins
+cher. Question ouverte sur l'application qui TOURNE (démarrage sain ? quelle route casse ?) →
+`nodefony_check` (= `nodefony doctor`), `nodefony_observe` : un appel au lieu de plusieurs `rg`,
+et des faits qu'aucun fichier ne porte.
+
 ```bash
 npx nodefony inspect routes --json     # routes réelles (chemin MONTÉ, méthodes, controller)
 npx nodefony inspect services --json   # services enregistrés, et le module qui les porte
@@ -170,9 +175,26 @@ tube, puis remets ton filtre.
 (`npx nodefony ai:mcp` écrit `.mcp.json`) — mêmes réponses, et tes propres modules peuvent publier
 les leurs. La porte est une ROUTE : elle n'existe que serveur démarré, et un client qui la trouve
 éteinte la marque en échec pour toute sa session — démarre l'application D'ABORD, ta session
-ENSUITE. Tout le reste (déclarer un outil métier, le réserver à des scopes, l'autorisation OAuth) :
+ENSUITE. Aucun serveur ne peut tourner (CI, agent dans un runner) ? Ton client lance lui-même
+`npx nodefony ai:stdio` et lui parle sur l'entrée et la sortie standard : mêmes outils, mais le
+code du démarrage, sans rechargement à chaud ni trafic réel à mesurer. Tout le reste (déclarer un outil métier, le réserver à des scopes, l'autorisation OAuth) :
 `node_modules/@nodefony/devkit/docs/index.md`.
 
+**Ta tâche est d'OFFRIR les outils de l'application à un agent** (« expose ceci par MCP ») ? Ce
+n'est pas la porte ci-dessus, qui sert l'outillage en développement : c'est une porte de
+l'APPLICATION, et elle se génère — n'écris pas le protocole à la main :
+
+```bash
+npx nodefony create controller mcp --kind mcp                  # porte locale : la machine seulement
+npx nodefony create controller mcp --kind mcp --expose oauth   # production : jeton exigé (401 sans)
+npx nodefony create controller mcp --kind mcp --expose mixte   # outils publics sans jeton, les autres réservés à un scope
+```
+
+Elle naît avec deux outils d'exemple (`nodefony/mcp/mcp-tools.ts`), sa définition
+(`defineMcpGate`, `nodefony/mcp/mcp-gate.ts`) et son test. Ajoute tes outils à la LISTE de la
+porte : elle publie ce qu'elle choisit, rien d'autre. Mode d'emploi :
+`node_modules/@nodefony/ai/docs/mcp.md` § « Monter une porte ».
+
 ### L'environnement : ne devine JAMAIS, demande
 
 ```bash
@@ -344,6 +366,14 @@ ont leur skill, qui part du symptôme : **`nodefony-troubleshoot`**.
   huit, `redis` quatre (`session`, `tokens`, `passkeys`, `idempotency`) : un cache ne garde ni
   comptes ni journal d'audit. Ne promets jamais une parité qui n'existe pas — lis ce champ, et
   `npx nodefony inspect stores` dit où atterrit chaque donnée.
+- **L'entrée d'une route se DÉCLARE — ne la valide pas à la main.** L'option `schema` d'un
+  décorateur de route (`@Post("/posts", { schema: { params, query, body, headers } })`, un schéma Zod
+  par partie) fait valider l'entrée AVANT l'action — **422** qui nomme chaque champ et sa partie, sur
+  HTTP comme par la socket (`api.request`) — et l'action la reçoit typée en UN argument,
+  `input: RouteInput<…>`. Une action à schéma ne prend **aucun** décorateur de paramètre (`@Body`,
+  `@Query`…) : le mélange est refusé au démarrage, qui nomme la route. L'identité se lit par
+  `this.user`. Un corps binaire arrive en octets (`Uint8Array`), un `text/*` en chaîne : un même
+  `z.instanceof(Uint8Array)` vaut pour les deux portes. Doc : `node_modules/@nodefony/framework/docs/decorateurs.md`.
 - **Les violations de contrainte sont DÉJÀ traduites en HTTP — ne les rattrape pas.** Un doublon
   sur une colonne unique ressort en **409**, une donnée qui viole le schéma Zod en **422**, chacun
   avec son corps JSON : le rendu d'erreur lit le code du pilote (`23505`, `ER_DUP_ENTRY`,

package/skills/nodefony-dev/scripts/docs.mjs

@@ -136,7 +136,7 @@ export function docDirectories(root) {
   };
   push(path.join(modules, "nodefony"));
   const scope = path.join(modules, "@nodefony");
-  let entries = [];
+  let entries;
   try {
     entries = readdirSync(scope);
   } catch {
@@ -155,7 +155,7 @@ export function docDirectories(root) {
 function markdownFiles(dir) {
   const out = [];
   const walk = (current) => {
-    let entries = [];
+    let entries;
     try {
       entries = readdirSync(current, { withFileTypes: true });
     } catch {
@@ -300,7 +300,7 @@ export function index(root) {
   const pages = [];
   for (const dir of docDirectories(root)) {
     for (const file of markdownFiles(dir)) {
-      let source = "";
+      let source;
       try {
         source = readFileSync(file, "utf8");
       } catch {