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

package/skills/nodefony-dev/SKILL.md

@@ -14,7 +14,7 @@ description: >
   est-il fini", "je ne trouve rien sur ce sujet", "ce n'est pas documenté", "je touche au
   frontend", "mon composant charge des données", "mon écran n'affiche rien".
 metadata:
-  version: 1.2.0
+  version: 1.3.0
 ---
 
 # nodefony-dev — développer dans cette application sans rien inventer
@@ -45,15 +45,19 @@ de son geste, et ceux-là ne se devinent pas — ils se paient.
 | -------------------------------------------------------------------- | ------------------------------- |
 | Une ressource : table, validation, service, REST et WebSocket        | `nodefony-add-crud`             |
 | Une logique métier réutilisable, hors de tout controller             | `nodefony-add-service`          |
-| Un flux temps réel, un canal, un abonnement client                   | `nodefony-add-realtime-channel` |
-| Réserver une route, un rôle, une zone, ouvrir à un partenaire        | `nodefony-protect-route`        |
+| Un flux temps réel (WebSocket ou SSE), un canal, un abonnement       | `nodefony-add-realtime-channel` |
+| Se connecter : /login, second facteur, retour après connexion, jeton | `nodefony-authentication`       |
+| Réserver une route ou une page à des rôles, ouvrir à un partenaire   | `nodefony-protect-route`        |
 | Changer une entité déjà en base, ou déployer un schéma changé        | `nodefony-migrate-schema`       |
 | Conclure quoi que ce soit d'un ÉCRAN — affichage, contraste, console | `nodefony-browser`              |
+| Quelque chose qui marchait ne marche plus : démarrage, 404, journal  | `nodefony-troubleshoot`         |
+| Relire la sécurité de ton diff AVANT de commiter                     | `nodefony-security-review`      |
+| Monter Nodefony de version, ou une montée qui a laissé des rouges    | `nodefony-upgrade`              |
 
 Aucune ligne ne correspond ? Alors seulement, continue ici. Et si ta tâche est EXACTEMENT celle
 d'un spécialiste, va droit à lui : il n'y a pas à passer par cette page d'abord.
 
-`ls .agents/skills/` liste ceux que TON projet a reçus ; `npx nodefony ai:sync` les remet à jour
+`ls .agents/skills/` liste ceux que TON projet a reçus ; `npx nodefony upgrade` les remet à jour
 après une montée de version. Ce sont des **pointeurs** : le contenu vit dans `node_modules` et
 suit la version installée — les éditer ne servirait à rien.
 
@@ -152,7 +156,8 @@ npx nodefony symbols --module @nodefony/http  # toute la surface exportée d'un
 ```
 
 Le graphe symbolique de tout le framework est livré avec le paquet `nodefony` : la réponse ne
-dépend ni d'un serveur, ni d'un build, ni de ta connexion. Va y chercher un symbole AVANT d'ouvrir
+dépend ni d'un serveur, ni d'un build, ni de ta connexion. Celui de TON code (`.ai/symbols.json`),
+`npm run dev` le tient à jour — ou `npx nodefony symbols --generate` ; les deux sont lus ensemble. Va y chercher un symbole AVANT d'ouvrir
 un `.d.ts` — et avant, surtout, d'inventer une signature.
 
 **Si la commande te résiste, répare l'APPEL — ne te rabats pas sur les sources.** C'est le réflexe
@@ -171,25 +176,19 @@ ENSUITE. Tout le reste (déclarer un outil métier, le réserver à des scopes,
 ### L'environnement : ne devine JAMAIS, demande
 
 ```bash
-npx nodefony env          # cascade des .env, valeur EFFECTIVE de chaque variable, sa PROVENANCE
+npx nodefony env          # valeur EFFECTIVE de chaque variable, sa PROVENANCE
 ```
 
 **Encadre toute modification de configuration par cette commande** : une fois AVANT, pour savoir ce
 qui s'applique et d'où ça vient ; une fois APRÈS, pour prouver que ta valeur est celle qui gagne.
-Lire les `.env` toi-même donne des contenus ; la précédence est un mécanisme — tu ne peux que la
-supposer, et une supposition fausse ne se voit qu'en production. La commande ne boote rien, donc
+Lire `.env` toi-même donne un contenu ; ce que l'application voit dépend aussi du shell et de
+`env.ts` — tu ne peux que le supposer, et une supposition fausse ne se voit qu'en production. La commande ne boote rien, donc
 elle répond aussi quand l'application ne démarre plus.
 
-**Précédence, du plus FORT au plus faible** — le premier qui pose une valeur gagne, les suivants
-sont ignorés en silence :
-
-```
-process.env  >  .env.<déploiement>.local  >  .env.<mode>.local  >  .env.local
-             >  .env.<déploiement>        >  .env.<mode>        >  .env
-```
-
-`<mode>` = `NODE_ENV` · `<déploiement>` = `APP_ENV` (plus spécifique, donc plus fort). Les `*.local`
-ne sont jamais committés : les secrets y vont, et nulle part ailleurs.
+**Deux fichiers** : `.env` = valeurs du POSTE (secrets de dev compris), **jamais commité** ;
+`.env.example` = notice commitée, **jamais chargée**. `process.env` > `.env`, rien d'autre. La
+production n'a **aucun** fichier (orchestrateur ; réglages non secrets dans `nodefony.config.ts`).
+Un module n'a pas de `.env`. N'écris JAMAIS `.env.local` ni `.env.<mode>` : refusés au démarrage (78).
 
 | Forme                                 | Ce que c'est                                         | Où c'est déclaré                                       |
 | ------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------ |
@@ -240,6 +239,15 @@ npx nodefony stop <nom|chemin>           # arrêter un AUTRE projet, sans change
 npx nodefony production --detach --wait   # boot réel en arrière-plan ; rend la main ports OUVERTS
 ```
 
+**Déboguer** : en développement, les piles d'appels pointent vers les `.ts` de l'application (le
+build de dev émet ses sourcemaps et le serveur les lit ; `npm run build`, lui, n'en émet pas — une
+pile de production pointe vers `dist/`). Pour un point d'arrêt : `npm run debug` (= `nodefony debug` :
+le mode développement, débogueur ouvert sur `127.0.0.1:9229`), puis `chrome://inspect` ou « Attach »
+dans l'éditeur. `--inspect=<port>` change le port, `--inspect-brk` arrête avant le chargement de
+l'application ; `nodefony development --inspect` fait la même chose. C'est le SERVEUR qui ouvre
+l'inspecteur, et il le rouvre à chaque rechargement ; marche aussi avec `--no-watch`. ⚠️ Jamais `NODE_OPTIONS=--inspect` :
+le premier process node de la chaîne (`npx`, `npm`) prend le port, et le serveur ne s'arrête jamais.
+
 **Arrête ce que tu démarres.** Un serveur laissé derrière garde les ports : le run suivant échoue
 sur une erreur qui ne parle jamais de lui (`EADDRINUSE`) — ou pire, un test interroge l'ANCIENNE
 version du code. Et **jamais `… &`** : le processus reçoit SIGHUP et meurt ; tuer le PID du port ne
@@ -252,6 +260,13 @@ une table à part — et ce nom est ce que `stop` accepte. Donc « aucune instan
 REFUSÉE, avec un code de sortie non nul et rien d'arrêté — **lis ce code**, un refus ressemble
 sinon à un succès.
 
+**Le plein écran n'est pas pour toi — et il est le DÉFAUT sous macOS et Linux.** Il fige la barre
+d'état en bas, capte le clavier et la souris (molette, PgUp/PgDn, Ctrl+C devient une touche) :
+c'est un écran pour un humain. Il s'active dès que le terminal répond à une sonde, et un
+pseudo-terminal (tmux, un outil qui t'en fournit un) y répond. Nodefony ne devine jamais qu'un
+agent est aux commandes : si tu lances `development` toi-même, ajoute **toujours** `--no-ui`
+(ou pose `NF_DEV_UI=0`), ou `--output plain` pour une sortie sans séquences d'écran.
+
 **Pour faire tourner une suite contre un serveur, prends `--no-watch`.** Le mode développement
 relance le serveur dès qu'un fichier bouge : pendant un run, le redémarrage coupe les connexions
 sous les tests, et le rouge qui en sort accuse le code alors que le fautif est le décor.
@@ -274,8 +289,9 @@ routes auth` ne rend que les routes dont le chemin, le nom, le contrôleur, l'ac
 4. **Édite le moins possible**, et regroupe : toutes les modifications serveur d'une même
    fonctionnalité, PUIS un seul cycle de reconstruction. Le frontend passe en HMR, zéro
    redémarrage.
-5. **Prouve.** `npm run verify` — une seule commande : types, style, tests, câblage, dans cet
-   ordre. Elle s'arrête au premier rouge, et **ce rouge est ta tâche suivante**.
+5. **Prouve.** `npm run verify` — une seule commande : types, style, mise en forme,
+   `.env.example`, tests, build, câblage, dans cet ordre. Elle s'arrête au premier rouge, et
+   **ce rouge est ta tâche suivante**.
 
 **Le point d'arrêt qu'on rate** : `npm test` seul ne prouve pas que ça compile — vitest
 n'inspecte aucun type. Une application peut être verte et ne pas compiler.
@@ -295,50 +311,19 @@ ici — ils changent tous les trimestres ; raisonne en poids.
 
 ## 7. Les pièges du serveur
 
-Chacun a déjà coûté au moins une heure à quelqu'un. Les quatre premiers sont les plus fréquents.
-
-- **Ta route répond 404 alors qu'elle existe dans les sources.** Le runtime charge `dist/`, pas
-  le source : `npm run build`. C'est la cause n°1.
-- **Une classe que rien ne déclare compile, passe ses tests, et casse au démarrage suivant** —
-  entité hors `@entities([…])`, controller hors `@controllers([…])`. Table jamais créée, route
-  en 404. C'est le mode d'échec de la COPIE : on recopie le voisin au lieu d'appeler le
-  générateur, qui, lui, déclare. `npx nodefony doctor` la NOMME.
-- **Une clé de configuration mal orthographiée est retirée en silence.** `satisfies` sur le
-  fragment n'est pas décoratif : sans lui, la faute compile, puis la validation écarte la clé et
-  le module démarre sur son défaut. Personne ne le voit.
+Ceux qu'on pose en ÉCRIVANT. Ceux qu'on rencontre quand quelque chose qui marchait ne marche plus
+— démarrage qui échoue, route en 404, refus inattendu, journal en erreur, tests rouges d'un coup —
+ont leur skill, qui part du symptôme : **`nodefony-troubleshoot`**.
+
+- **Une clé de configuration mal orthographiée ARRÊTE le démarrage** (code 78), en la nommant.
+  `satisfies` sur un fragment extrait n'est pas décoratif pour autant : il te la signale à la
+  compilation, au lieu du prochain démarrage.
 - **La config d'un module est FIGÉE après le démarrage** : l'écrire lève `TypeError`. Une variante
   par requête = `overlayConfig()` (clés de la liste blanche du module), lue par `useConfig()`.
 - **Tu lis une liste sans la BORNER.** Un `find` sans limite matérialise la table entière —
   indolore sur les quelques lignes du poste de développement, fatal sur les dizaines de milliers
   de la production. Le service d'une entité hérite `findPage({ limit: 25 })`.
 
-- **Des dizaines de tests d'intégration rouges d'un coup** (`ECONNREFUSED`) : ils FRAPPENT un
-  serveur, ils ne le lancent pas — il est éteint. `npx nodefony status` d'abord ; en e2e, laisse
-  la commande gérer le cycle.
-- **Ta route NEUVE répond 404 et le `dist/` est à jour** : elle n'est pas montée où tu crois. Le
-  chemin réel est le PRÉFIXE de son controller suivi du `path` de la route — une action
-  `path: "/widget"` dans un controller `@controller("/api")` répond sur `/api/widget`.
-  `npx nodefony inspect routes --json` donne le chemin MONTÉ.
-- **TOUT répond 404, même les routes du gabarit** : un AUTRE serveur tient les ports — ou LE TIEN
-  a glissé, le port voulu étant pris. `npx nodefony status` montre les ports RÉELS, pas ceux que
-  tu as configurés, et NOMME le projet voisin.
-- 🔴 **`nodefony <commande>` échoue là où `npm run dev` réussit, sur la MÊME application** : DEUX
-  paquets `nodefony` tournent dans le processus — un binaire lié ailleurs (installation globale,
-  `npm link`) exécute un noyau pendant que l'application importe le sien. Chaque copie a ses
-  propres classes, son contexte de requête et ses registres d'injection : un module construit à la
-  frontière perd son container SANS la moindre erreur — il figure dans la liste des modules et ne
-  fait rien. ⚠️ Les deux copies peuvent être la MÊME version ; deux fichiers distincts suffisent,
-  il n'y a aucune incohérence à repérer. `npm ls nodefony` liste les copies (« deduped » partout =
-  une seule) ; `NF_CLI_DEBUG=1 nodefony --version` dit quel CLI s'exécute.
-- **`localhost` et `127.0.0.1` te jouent des tours** : ce sont deux ORIGINES distinctes — cookies,
-  cache et passkeys ne les partagent pas. Une seule origine en développement, partout, URL ouverte
-  comme callbacks.
-
-- **Les routes authentifiées plafonnent quand le reste tient la charge** : le stockage de session
-  par défaut est SYNCHRONE — chaque reprise bloque la boucle d'événements. Compare une route
-  anonyme et une route authentifiée AVANT d'accuser TLS ou le pare-feu ; passe le stockage sur
-  redis pour la charge.
-
 ### Ce qui tue le processus, pas la requête
 
 - 🔴 **Une promesse lancée sans `await` porte TOUJOURS un `.catch()`.** Audit, courriel,
@@ -352,24 +337,6 @@ Chacun a déjà coûté au moins une heure à quelqu'un. Les quatre premiers son
 - **Un `PATCH` au corps vide se refuse en `400`.** Le laisser passer produit un `updateOne({})`,
   qui finit en `500 « No values to set »` — une erreur serveur pour une faute de client.
 
-### Quand ça ne va pas, et que le message ne suffit pas
-
-- **Un test vert seul et rouge en suite accuse une RESSOURCE PARTAGÉE**, pas ton code : base ou
-  index réutilisé, port, store jamais purgé, assertion `count === N` qui suppose une table
-  vierge. Lance deux fichiers ENSEMBLE pour isoler la paire, puis cloisonne. **Ne sérialise
-  jamais la suite** pour faire passer le rouge : tu masques la cause et tu paies la lenteur à
-  chaque exécution.
-- **Une suite lancée contre un serveur en `production` reçoit `404` partout** : les modules
-  `policy:"dev"` n'y sont pas. `NF_WITH_DEV_MODULES=1` déroge pour 30 minutes
-  (`NF_WITH_DEV_MODULES_TTL_MIN`, 4 h au plus), et le `CRITIC « arrêt automatique … dérogation »`
-  du journal est cette garde qui se referme — pas une panne.
-- **Ton application a démarré AMPUTÉE et tout a l'air sain** — base injoignable, module écarté
-  par sa politique. Seul `npx nodefony doctor` le dit, en relisant `var/last-boot.json`.
-  ⚠️ Ce bilan a un ÂGE : il décrit le **dernier démarrage**, et une commande console (`inspect`,
-  une commande de module) ne l'écrase pas. C'est voulu — lis la date avant d'en conclure.
-- **L'application ne démarre plus et le superviseur avale la sortie** :
-  `NF_DEV_CHILD=1 npx nodefony development` lance l'enfant seul et montre le crash brut.
-
 ## 8. Données et fichiers — les façades qu'on ne recompose pas
 
 - **Un cache ne remplace pas une base : ils se COMPLÈTENT.** Chaque adaptateur déclare les
@@ -445,11 +412,16 @@ Ne concerne qu'une application qui a un frontend. Sauf mention, **vaut pour les
   **couleur seule**, `rel="noopener noreferrer"` sur les liens externes.
 
 - **Une route d'API répond du HTML** : un repli SPA générique avale les routes voisines — le
-  premier motif qui correspond gagne. Repli en préfixe LITTÉRAL ; `npx nodefony inspect routes
---json` montre l'ordre réel.
+  premier motif qui correspond gagne. Déclare la route de la page monopage avec
+  `fallback: true` : elle ne sert alors que ce qu'aucune autre route ne sert, quel que soit
+  l'ordre. `npx nodefony inspect routes --json` montre l'ordre réel.
 - **Des utilisateurs « déconnectés au hasard »** : le traitement global « 401 = session expirée »
-  frappe aussi les sondes d'authentification, où 401 est NORMAL — et détruit une session valide.
-  Exempte les sondes du traitement global.
+  frappe aussi la connexion refusée (un mauvais mot de passe rend 401) — et détruit une session
+  valide. Exempte les routes d'authentification du traitement global. `me` ne renvoie jamais
+  401 : il répond toujours 200, `{ user: null }` sans session.
+- **La connexion ne s'écrit pas en `fetch`** : `/login` est servie ; la liaison du front
+  (`useNodefonyLogin`…) porte `me()` et `logout()` — suis l'adresse que rend `logout()`, sinon
+  la session Keycloak reste ouverte. Détail : skill `nodefony-authentication`.
 - **Ta page répond 200 et son script ne s'exécute pas** : la politique de contenu exige un `nonce`
   sur les scripts, et le navigateur refuse un `<script>` en ligne qui n'en porte pas (« Refused to
   execute inline script »). Un `curl` ne le voit JAMAIS, il ne lit que le corps. Signe le script
@@ -468,10 +440,13 @@ Ne concerne qu'une application qui a un frontend. Sauf mention, **vaut pour les
 ## 10. Avant de dire « fait »
 
 ```bash
-npm run verify        # types + style + tests + câblage
+npm run verify        # types, style, mise en forme, .env.example, tests, build, câblage
 npm run test:e2e      # boot réel + HTTP/WS — le gate LENT, hors `verify`
 ```
 
+Ton diff ajoute une route, une requête ou touche la sécurité ? Relis-le AVANT de commiter :
+skill `nodefony-security-review` — un script y nomme, ligne par ligne, ce qu'un œil laisse passer.
+
 Puis, en une phrase : **nomme ce que tu n'as PAS lancé.** Un vert ne couvre que le diff qui l'a
 produit, et un banc sauté faute de son décor compte comme vert. Dire « e2e non lancé » coûte
 cinq mots ; le taire coûte la confiance dans tout le reste.

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

@@ -21,10 +21,23 @@
  * `@output` les pages classées, avec chemin, ligne et extrait — ou un refus qui DIT pourquoi
  */
 
-import { readFileSync, readdirSync, statSync } from "node:fs";
+import { readFileSync, readdirSync, statSync, realpathSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
+import { findProjectRoot } from "nodefony/project-root";
+
+/**
+ * Racine de l'APPLICATION vue depuis `cwd` — le dossier qui porte
+ * `nodefony.config.ts` —, ou `cwd` lui-même hors application. Un script lancé
+ * depuis `frontend/` ou `modules/blog/` travaille ainsi sur l'app entière.
+ * `nodefony/project-root` est le sous-chemin LÉGER du cœur (`node:` seul) :
+ * importer `nodefony` entier coûtait jusqu'à plusieurs secondes à froid.
+ *
+ * @param {string} cwd - le dossier de lancement.
+ * @returns {string} la racine retenue.
+ */
+const appRoot = (cwd) => findProjectRoot(cwd) ?? cwd;
 
 /** Nombre de pages rendues par défaut — au-delà, personne ne lit. */
 const DEFAULT_LIMIT = 6;
@@ -55,14 +68,14 @@ const FLAGS = new Set([
  * @returns les options lues.
  * @throws Error quand un drapeau est inconnu ou qu'une valeur manque.
  */
-export function parseArgs(argv) {
+export function parseArgs(argv, cwd = process.cwd()) {
   const opts = {
     terms: [],
     list: false,
     open: /** @type {string | null} */ (null),
     json: false,
     limit: DEFAULT_LIMIT,
-    root: process.cwd(),
+    root: appRoot(cwd),
     help: false,
   };
   for (let i = 0; i < argv.length; i += 1) {
@@ -538,7 +551,10 @@ export function main() {
 // confondrait deux scripts homonymes de deux skills.
 if (
   process.argv[1] !== undefined &&
-  pathToFileURL(process.argv[1]).href === import.meta.url
+  // Chemins RÉELS des deux côtés : Node résout `import.meta.url` en suivant
+  // les liens, pas `argv[1]` — lancé par `/var/…` (macOS) ou un dossier lié,
+  // la comparaison brute échouait et le script ne faisait RIEN.
+  realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)
 ) {
   process.exitCode = main();
 }

package/skills/nodefony-devops/SKILL.md

@@ -75,7 +75,8 @@ Ce que l'application ne peut pas deviner. Chacun de ces oublis produit une dégr
 
 - **`NF__HTTP__TRUSTPROXY`** dès qu'un frontal termine le TLS. Sans lui, l'application constate un
   schéma `http` et **un cookie `__Host-` n'est pas émis** : les sessions ne tiennent plus, sans le
-  moindre message. Détail et preuve → [`references/frontal.md`](references/frontal.md).
+  moindre message — et toute connexion par mot de passe répond `403`, le secret étant reçu
+  « en clair ». Détail et preuve → [`references/frontal.md`](references/frontal.md).
 - **Deux volumes inscriptibles**, sur `/app/tmp` et `/app/var`, si tu scelles la racine.
 - **Une fenêtre d'arrêt ≥ 30 s**, strictement supérieure au drain de 15 s.
 - **Pas de limite processeur.** Une limite mémoire tue proprement et l'exemplaire redémarre ; une
@@ -106,18 +107,20 @@ Chaque ligne a la commande qui la **prouve**. Une case cochée sans commande est
 
 Le tableau qu'on lit en urgence.
 
-| Symptôme                                                     | Cause                                                                                             | Correction                                                                   |
-| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| L'exemplaire redémarre en boucle, journaux muets             | La sonde de vivacité tombe avant la fin du démarrage                                              | Sonde de démarrage sur `/readyz`, dimensionnée sur le **pire** cas           |
-| Le conteneur sort en **137** à l'arrêt                       | Il a été tué : la fenêtre d'arrêt est ≤ au drain                                                  | Fenêtre ≥ 30 s (Podman : `--stop-timeout 20`, son défaut est **10 s**)       |
-| Des `5xx` **pendant** chaque déploiement                     | Le répartiteur envoie encore du trafic quand le drain a commencé                                  | Un délai avant drain, et un court arrêt avant terminaison                    |
-| Les sessions ne tiennent pas derrière le frontal             | Schéma constaté `http` → le cookie `__Host-` n'est pas émis                                       | `NF__HTTP__TRUSTPROXY`                                                       |
-| Les journaux d'audit montrent tous la **même adresse**       | L'adresse du client n'est pas propagée, ou le frontal n'est pas de confiance                      | `trustProxy` ; en Podman sans privilèges, **c'est irréparable** (§7)         |
-| `EACCES` au premier démarrage sur un volume                  | Le volume est né `root:root` : monté **par-dessus** un dossier dont l'image avait fixé le porteur | Volume nommé (il hérite du porteur) ou groupe de système de fichiers         |
-| La base refuse des connexions dès qu'on monte en exemplaires | Une base administrée les compte ; le pool n'est pas borné                                         | Réduire les exemplaires — le plafond n'est pas encore réglable (§6)          |
-| La sonde répond `429`                                        | Ce n'est **pas** la sonde : c'est la limitation de débit — donc l'appel n'a pas pris le raccourci | Interroger `/livez` et `/readyz` nus, sans en-tête ni préfixe ajouté         |
-| Un secret retiré du `Dockerfile` reste dans l'image          | Une couche antérieure le contient encore ; l'effacer plus loin ne l'enlève pas                    | `npx nodefony image:check`, et reconstruire sans jamais l'avoir copié        |
-| La variable posée « ne fait rien »                           | Le nom est faux d'un caractère — une variable inconnue est **ignorée**, pas refusée               | `npx nodefony doctor` → [`references/variables.md`](references/variables.md) |
+| Symptôme                                                        | Cause                                                                                                                                             | Correction                                                                                                                                                                |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| L'exemplaire redémarre en boucle, journaux muets                | La sonde de vivacité tombe avant la fin du démarrage                                                                                              | Sonde de démarrage sur `/readyz`, dimensionnée sur le **pire** cas                                                                                                        |
+| Le conteneur sort en **137** à l'arrêt                          | Il a été tué : la fenêtre d'arrêt est ≤ au drain                                                                                                  | Fenêtre ≥ 30 s (Podman : `--stop-timeout 20`, son défaut est **10 s**)                                                                                                    |
+| Des `5xx` **pendant** chaque déploiement                        | Le répartiteur envoie encore du trafic quand le drain a commencé                                                                                  | Un délai avant drain, et un court arrêt avant terminaison                                                                                                                 |
+| Les sessions ne tiennent pas derrière le frontal                | Schéma constaté `http` → le cookie `__Host-` n'est pas émis                                                                                       | `NF__HTTP__TRUSTPROXY`                                                                                                                                                    |
+| Toutes les connexions répondent `403` « doit passer par HTTPS » | Même cause : le mot de passe arrive sur une requête que l'application croit en clair                                                              | `NF__HTTP__TRUSTPROXY` — jamais `allowInsecureCredentials`                                                                                                                |
+| Sortie **78** au démarrage, une clé ou une variable nommée      | Faute de configuration : clé inconnue (ou retirée par une mise à jour), valeur invalide, secret requis absent (`NF_CSRF_SECRET`, `NF_JWT_KEYSET`) | Lire la ligne qui la nomme ; `npx nodefony doctor --env production` annonce AVANT les variables requises (pas `NF_JWT_KEYSET`, exigée seulement si l'app émet des jetons) |
+| Les journaux d'audit montrent tous la **même adresse**          | L'adresse du client n'est pas propagée, ou le frontal n'est pas de confiance                                                                      | `trustProxy` ; en Podman sans privilèges, **c'est irréparable** (§7)                                                                                                      |
+| `EACCES` au premier démarrage sur un volume                     | Le volume est né `root:root` : monté **par-dessus** un dossier dont l'image avait fixé le porteur                                                 | Volume nommé (il hérite du porteur) ou groupe de système de fichiers                                                                                                      |
+| La base refuse des connexions dès qu'on monte en exemplaires    | Une base administrée les compte ; le pool n'est pas borné                                                                                         | Réduire les exemplaires — le plafond n'est pas encore réglable (§6)                                                                                                       |
+| La sonde répond `429`                                           | Ce n'est **pas** la sonde : c'est la limitation de débit — donc l'appel n'a pas pris le raccourci                                                 | Interroger `/livez` et `/readyz` nus, sans en-tête ni préfixe ajouté                                                                                                      |
+| Un secret retiré du `Dockerfile` reste dans l'image             | Une couche antérieure le contient encore ; l'effacer plus loin ne l'enlève pas                                                                    | `npx nodefony image:check`, et reconstruire sans jamais l'avoir copié                                                                                                     |
+| La variable posée « ne fait rien »                              | Le nom est faux d'un caractère — une variable inconnue est **ignorée**, pas refusée                                                               | `npx nodefony doctor` → [`references/variables.md`](references/variables.md)                                                                                              |
 
 ## 6. Kubernetes — ce qui est rendu, et ce qui te reste
 

package/skills/nodefony-devops/references/compose.md

@@ -16,6 +16,7 @@ docker compose --profile edge up -d         # la TOPOLOGIE DE PRODUCTION : front
 docker compose --profile tools up -d        # les explorateurs de données
 docker compose --profile loki up -d         # journalisation centralisée + tableaux de bord
 docker compose --profile browser up -d      # un navigateur piloté
+docker compose --profile keycloak up -d keycloak   # un fournisseur d'identité OpenID Connect, de DÉVELOPPEMENT
 ```
 
 > Le profil `app` et le profil `edge` sont **exclusifs par nature** : le premier publie un port sur
@@ -35,6 +36,13 @@ docker compose --profile browser up -d      # un navigateur piloté
 | `redisinsight`             | `tools`       | explorateur du cache                                 | `5540`                                     |
 | `loki` / `grafana`         | `loki`        | journaux et tableaux de bord                         | `3100`, `3000`                             |
 | `browser`                  | `browser`     | navigateur piloté (image **épinglée par empreinte**) | `3001`                                     |
+| `keycloak`                 | `keycloak`    | `quay.io/keycloak/keycloak` (préréglage `complete`)  | `8444` (8443 est au frontal)               |
+
+Le profil `keycloak` est un décor de **développement** (base embarquée, secrets publics) : realm
+et thème viennent de `docker/keycloak/`, posés par le paquet `@nodefony/security` et tenus à jour
+par `npx nodefony scaffold:sync --update`. Il exige `npx nodefony http:certificates` une fois
+(Keycloak sert en https), et sous Linux natif `export KEYCLOAK_UID=$(id -u)` avant le `up`. Le
+mode d'emploi est en commentaire au-dessus du service, dans `compose.yaml`.
 
 **Les ports sont publiés sur la boucle locale**, pas sur `0.0.0.0`. Une base de développement
 accessible depuis le réseau est une base de développement qui finit indexée.

package/skills/nodefony-devops/references/frontal.md

@@ -34,7 +34,11 @@ Conséquence si tu ne le poses pas : le schéma constaté est `http`, donc :
   sécurisée. Les sessions ne tiennent pas, **sans aucun message** ;
 - l'adresse cliente enregistrée est celle du frontal, donc l'audit et toute limitation par adresse
   portent sur une seule IP ;
-- les redirections peuvent pointer sur `http://`.
+- les redirections peuvent pointer sur `http://` ;
+- **toute connexion par mot de passe répond `403`** (« doit passer par HTTPS ») : en production,
+  un secret reçu sur une requête que l'application croit en clair est refusé avant toute
+  vérification. `security.allowInsecureCredentials` n'est PAS la correction — elle accepterait
+  vraiment le clair ; la correction est cette variable.
 
 ```yaml
 NF__HTTP__TRUSTPROXY: uniquelocal # le frontal est sur un réseau privé

package/skills/nodefony-devops/references/image.md

@@ -11,7 +11,7 @@ du frontal ne sort que si tu le demandes explicitement.
 | ----------- | ------------------- | --------------------------------------------------------------------- | ----------------------------- |
 | `build`     | `node:24-alpine`    | Installe, compile, élague les dépendances de développement            | seulement son `/app`          |
 | `proxyconf` | hérite de `build`   | **Dérive** la configuration nginx et rassemble les fichiers statiques | non — étage intermédiaire     |
-| `edge`      | `nginx:1.27-alpine` | Le frontal, avec la configuration dérivée ci-dessus                   | non — cible séparée           |
+| `edge`      | `nginx:1.30-alpine` | Le frontal, avec la configuration dérivée ci-dessus                   | non — cible séparée           |
 | _(final)_   | `node:24-alpine`    | L'application en production                                           | **oui**                       |
 
 ```bash

package/skills/nodefony-devops/references/secrets.md

@@ -24,7 +24,7 @@ Il est rendu avec l'application, et il exclut quatre familles. Ne les retire pas
 | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
 | `**/node_modules`, `**/dist`            | Reconstruits **dans** l'image. Entrés depuis ta machine, ils masqueraient la construction et l'image partirait avec le code de la veille. |
 | `var`, `logs`, `**/*.log`, `**/*.jsonl` | Écritures propres à une machine, sans valeur dans une image                                                                               |
-| `*.local`, `**/*.local`                 | La convention des fichiers de secrets locaux — jamais commités, et pas davantage dans une image                                           |
+| `.env`, `.env.*` (sauf `.env.example`)  | Les valeurs du poste, secrets de dev compris — jamais commitées, et pas davantage dans une image                                          |
 | **La matière cryptographique**          | Clés privées, certificats                                                                                                                 |
 
 > ⚠️ **Un motif de `.dockerignore` n'obéit pas aux règles du `.gitignore`.** Sans `**/`, il est
@@ -47,15 +47,29 @@ qu'aucun certificat auto-signé de ta machine ne descende en production.
 | `NF_CSRF_SECRET`    | Les jetons anti-CSRF                                           | **oui** — sinon un jeton émis par un exemplaire est refusé par l'autre |
 | `NF_TOTP_KEY`       | Le chiffrement au repos des secrets de double authentification | **oui** — sinon les seconds facteurs deviennent illisibles             |
 | `NF_WEBHOOK_KEY`    | Le chiffrement des signatures de webhooks                      | **oui**                                                                |
+| `NF_JWT_KEYSET`     | La clé qui signe les jetons (privée)                           | **oui** — sinon chaque exemplaire refuse les jetons des autres         |
 | `NF_ADMIN_PASSWORD` | Le compte d'administration                                     | —                                                                      |
 
 > 🔴 **Le partage entre exemplaires n'est pas un détail de confort.** Un secret différent par
 > exemplaire produit des échecs **intermittents** — une requête sur deux, selon le répartiteur.
 > C'est le symptôme le plus coûteux à diagnostiquer, parce qu'il ressemble à un problème réseau.
 
-`NF_ADMIN_PASSWORD` a un défaut en développement. **En production il est obligatoire** : sans lui,
-aucun compte d'administration n'est créé et le démarrage échoue — volontairement, plutôt que de
-créer un compte avec un mot de passe connu de tout le monde.
+**Lesquels arrêtent le démarrage en production** : `NF_CSRF_SECRET` toujours, `NF_JWT_KEYSET`
+dès que l'application émet des jetons. Sans `NF_TOTP_KEY` ou `NF_WEBHOOK_KEY`, l'application
+démarre mais la brique se désactive (double authentification, webhooks), avec un journal CRITIC.
+
+```bash
+npx nodefony security:secrets --env          # les secrets, en lignes CLÉ=valeur (--env-file, gestionnaire)
+npx nodefony security:secrets --jwt-keyset   # la valeur de NF_JWT_KEYSET — une ligne JSON, clé PRIVÉE
+```
+
+Une valeur par ENVIRONNEMENT (staging ≠ production), générée une fois, rangée dans le
+gestionnaire de secrets ; ne laisse traîner aucun fichier qui la contient.
+
+`NF_ADMIN_PASSWORD` a un défaut en développement, aucun en production : sans lui, le premier
+démarrage ne crée **aucun** compte d'administration — plutôt qu'un compte au mot de passe connu de
+tout le monde. Il ne sert qu'à ce premier démarrage ; `npx nodefony security:user:add <id> --admin`
+fait le même geste à la main.
 
 ## 5. Les monter, pas les poser en clair
 

package/skills/nodefony-devops/references/variables.md

@@ -5,7 +5,7 @@
 ## 1. La commande qui répond, et à laquelle rien ne ment
 
 ```bash
-npx nodefony env            # la cascade des .env, la valeur EFFECTIVE de chaque variable, et sa PROVENANCE
+npx nodefony env            # la valeur EFFECTIVE de chaque variable, et sa PROVENANCE (.env ou process)
 npx nodefony env --json     # le même rapport, pour un script
 ```
 
@@ -19,8 +19,11 @@ npx nodefony inspect schema <module>        # les clés qui EXISTENT, leur type,
 npx nodefony doctor --env production        # ce qui manquerait là-bas, depuis ici
 ```
 
-> 🔴 **`inspect schema` avant d'écrire une clé.** Une clé inconnue n'est pas refusée : elle est
-> **retirée en silence** à la validation. Tu poses le réglage, rien ne change, rien ne le dit.
+> 🔴 **`inspect schema` avant d'écrire une clé.** Une clé inconnue **arrête le démarrage**
+> (code 78) en la nommant — y compris une clé qu'une version du framework a retirée, que tu
+> découvres alors au premier déploiement après un `npm update`. Ce qui reste muet, c'est une
+> **variable** mal orthographiée (`NF_PROT` au lieu de `NF_PORT`) : inconnue, donc ignorée, et
+> seul `npx nodefony env` la montre.
 
 ## 2. Deux grammaires, et elles ne font pas la même chose
 
@@ -54,6 +57,27 @@ booléen, un nombre devient un nombre, `[…]` et `{…}` sont lus en JSON, une
 devient un tableau, le reste reste une chaîne. C'est ce qui évite le piège classique où la chaîne
 `"false"` est convertie en booléen **vrai**.
 
+### `NF_<MODULE>_<RÉGLAGE>` — les noms courts des modules
+
+Un module déclare sur un champ de son schéma le nom court qui le règle (`NF_REDIS_HOST`,
+`NF_REALTIME_DRIVER`…). `npx nodefony env --example` les écrit dans `.env.example`, une section
+par module. Trois règles, toutes au démarrage :
+
+- La valeur est **validée par le schéma** : `NF_REDIS_PORT=abc` arrête le démarrage (78) en
+  nommant la VARIABLE, pas le seul champ.
+- **Nom court ET `NF__…` sur le même champ** : refus du démarrage en production (78) ; en
+  développement, `NF__…` l'emporte avec un avertissement qui nomme les deux.
+- Chaque nom court accepte `<NOM>_FILE` ; une variable vide vaut absente.
+
+### Lire la notice `.env.example`
+
+Chaque variable y porte ses métadonnées : `@required` / `@optional`, `@required=forEnv(production)`,
+`@requiredWhen="…"` (exigée sous condition — `NF_JWT_KEYSET` : « en production, si l'application
+émet des jetons »), `@sensitive`, `@default`, et **`@placement`**, qui dit où la poser en
+production : `platform` (variables du déploiement), `secrets` (gestionnaire de secrets, ou
+`<NOM>_FILE`), `workstation` (le poste seulement — ne la pose pas en production).
+`npm run env:check` échoue (78) quand la notice a dérivé d'`env.ts`.
+
 ## 3. Le suffixe `_FILE` — les secrets montés
 
 **Toute** variable du catalogue accepte un `_FILE`. Le contenu du fichier est lu, retour à la ligne
@@ -102,23 +126,32 @@ Les seules qui te concernent au déploiement. Le catalogue complet, c'est `npx n
 
 ### Données
 
-| Variable          | Rôle                   | Absente ⇒                                            |
-| ----------------- | ---------------------- | ---------------------------------------------------- |
-| `NF_DATABASE_URL` | L'URL de la base       | **Repli sur SQLite local**, dans `var/` — silencieux |
-| `NF_REDIS_URL`    | L'URL du cache partagé | Le cache n'est pas chargé                            |
+| Variable          | Rôle                   | Absente ⇒                                         |
+| ----------------- | ---------------------- | ------------------------------------------------- |
+| `NF_DATABASE_URL` | L'URL de la base       | **Repli sur SQLite local**, dans `var/` — annoncé |
+| `NF_REDIS_URL`    | L'URL du cache partagé | Le cache n'est pas chargé                         |
 
 > Le repli SQLite est le piège d'exploitation classique : l'application **démarre**, sert des
-> requêtes, écrit dans un fichier — et chaque exemplaire a sa propre base. Rien n'est en erreur.
-> `npx nodefony env` le montre en une ligne.
-
-### Secrets — obligatoires en production
-
-| Variable            | Ce qu'il protège                                 |
-| ------------------- | ------------------------------------------------ |
-| `NF_CSRF_SECRET`    | Les jetons anti-CSRF, partagés entre exemplaires |
-| `NF_TOTP_KEY`       | Les secrets de double authentification au repos  |
-| `NF_WEBHOOK_KEY`    | Les signatures de webhooks                       |
-| `NF_ADMIN_PASSWORD` | Le compte d'administration                       |
+> requêtes, écrit dans un fichier — et chaque exemplaire a sa propre base. Il est ANNONCÉ
+> (avertissement au démarrage, point `DB_SQLITE_FALLBACK` dans `npx nodefony status --json`),
+> mais rien n'échoue : lis le bilan du démarrage. Seule exception : si une entité est écrite pour
+> un autre moteur (PostgreSQL, MySQL), le repli est **refusé** et le démarrage s'arrête.
+
+### Secrets — ce qui se passe en production sans eux
+
+| Variable            | Ce qu'il protège                                 | Absente en production ⇒                             |
+| ------------------- | ------------------------------------------------ | --------------------------------------------------- |
+| `NF_CSRF_SECRET`    | Les jetons anti-CSRF, partagés entre exemplaires | **Refus de démarrer** (78)                          |
+| `NF_JWT_KEYSET`     | La clé de signature des jetons, commune à tous   | **Refus de démarrer** si l'app émet des jetons      |
+| `NF_TOTP_KEY`       | Les secrets de double authentification au repos  | Double authentification désactivée (journal CRITIC) |
+| `NF_WEBHOOK_KEY`    | Les signatures de webhooks                       | Webhooks désactivés (journal CRITIC)                |
+| `NF_ADMIN_PASSWORD` | Le compte d'administration, au PREMIER démarrage | Aucun compte créé ; inutile une fois le compte créé |
+
+`NF_JWT_KEYSET` manque presque toujours au premier déploiement : sans elle, un exemplaire qui
+émet des jetons **refuse de démarrer** en production (78) — et deux exemplaires à clés
+différentes refuseraient chacun les jetons de l'autre. `npx nodefony security:secrets --jwt-keyset`
+la produit (une ligne JSON) ; `--env` rend les autres secrets en lignes `CLÉ=valeur`, prêtes pour
+`docker run --env-file` ou un gestionnaire de secrets.
 
 Tous en `_FILE` en production. Détail et rotation → [`secrets.md`](secrets.md).
 
@@ -129,7 +162,7 @@ Tous en `_FILE` en production. Détail et rotation → [`secrets.md`](secrets.md
 | `NF_POD_NAME`                     | Identité de l'exemplaire — **dérive l'identité d'origine du bus temps réel** |
 | `NF_INSTANCE_ID`                  | Identifiant d'exemplaire                                                     |
 | `NF_REALTIME_DRIVER`              | Le transport du bus entre exemplaires                                        |
-| `NF_REALTIME_BACKPLANE_SECRET`    | Scelle les enveloppes échangées sur le bus                                   |
+| `NF_REALTIME_BACKPLANE_SECRET`    | Scelle les enveloppes du bus — moins de 32 caractères arrête le démarrage    |
 | `NF_REALTIME_BACKPLANE_NAMESPACE` | Cloisonne deux applications qui partagent le même bus                        |
 
 > 🔴 **Deux applications sur un même cache, sans espace de noms distinct, se parlent.** Le symptôme

package/skills/nodefony-migrate-schema/SKILL.md

@@ -259,10 +259,13 @@ neuve ne prouve RIEN de tout ça — elle est vide.
 ```bash
 # sqlite : une copie du fichier. Le chemin par défaut du connecteur `default` est
 # `var/databases/nodefony-drizzle.db` — `orm:migrate:status --json` le confirme.
-cp var/databases/nodefony-drizzle.db /tmp/essai.sqlite
+# La copie va sous `tmp/scratch/` de l'application, pas dans le /tmp du système :
+# c'est un résultat qu'on relit, et il doit disparaître avec le reste de `tmp/`.
+mkdir -p tmp/scratch
+cp var/databases/nodefony-drizzle.db tmp/scratch/essai.sqlite
 # PostgreSQL : CREATE DATABASE app_essai TEMPLATE app;  (ou une restauration de sauvegarde)
 
-export NF_MIGRATE_DATABASE_URL="sqlite:/tmp/essai.sqlite"
+export NF_MIGRATE_DATABASE_URL="sqlite:tmp/scratch/essai.sqlite"
 npx nodefony orm:migrate --json
 ```