nodefony 7.0.2 → 10.0.0-alpha.2

package/docs/debugbar.md

@@ -0,0 +1,218 @@
+---
+title: "Barre de débogage — nodefony/debugbar"
+lang: fr
+module: "@nodefony/core"
+topic: debugbar
+source: "src/nodefony/docs/debugbar.md"
+updated: 2026-09-01
+navTitle: Barre de débogage
+coverageModule: nodefony-core
+coveragePackage: "nodefony (cœur)"
+coverageFiles: "client/debugbar/DebugBar.ts,client/debugbar/model.ts,client/debugbar/index.ts"
+section: "Cœur runtime"
+audience: [developer]
+tags:
+  [
+    debugbar,
+    developpement,
+    observabilite,
+    journaux,
+    temps-reel,
+    requestId,
+    accessibilite,
+    stockage-local,
+  ]
+version: "doc"
+status: stable
+updated: 2026-08-31
+---
+
+# Barre de débogage
+
+Une bande fine en bas de page, en développement, qui montre ce que le serveur est
+en train de faire : le débit temps réel, la charge, la mémoire, les requêtes
+réseau et les journaux — sans quitter l'écran qu'on est en train de construire.
+
+Elle est livrée avec le cœur et ne dépend d'aucun cadre front : elle s'installe
+dans une page rendue par un serveur comme dans une application React, Vue,
+Angular ou Svelte.
+
+📍 [Documentation](../../../docs/index.md) › [`nodefony` — le cœur](index.md) › **Barre de débogage**
+
+## Démarrage rapide
+
+```ts
+import { mountDebugBar } from "nodefony/debugbar";
+
+// En développement uniquement — la barre n'a rien à faire en production.
+if (import.meta.env.DEV) mountDebugBar();
+```
+
+Sur une page rendue par le serveur, sans étape de construction :
+
+```html
+<script
+  type="module"
+  src="/node_modules/nodefony/dist/client/debugbar.standalone.js"
+></script>
+```
+
+La barre s'abonne au canal temps réel de l'application. Elle n'ouvre **aucune**
+seconde connexion : elle partage la socket déjà présente si la page en a une.
+
+## Ce qu'on voit, et ce qu'on peut faire
+
+Le **bandeau** porte l'essentiel en une ligne : l'état de la connexion,
+l'environnement, la branche git, puis le débit temps réel, la charge processeur
+et la mémoire, enfin les compteurs réseau, journaux et erreurs.
+
+Chaque élément du bandeau porte une aide qui s'ouvre au survol **et au focus
+clavier**, et chaque indicateur est un raccourci : cliquer « cpu » ouvre l'onglet
+qui le détaille. Le bandeau lui-même ne se replie pas au clic — seul le chevron
+de droite le fait, et lui seul.
+
+| Contrôle          | Ce qu'il fait                                                                         |
+| ----------------- | ------------------------------------------------------------------------------------- |
+| `flux OFF` / `ON` | Abonne aux mesures et aux journaux en direct. **Coupé par défaut** (voir ci-dessous). |
+| `⇄`               | Change la barre de côté.                                                              |
+| `—`               | Réduit la barre en pastille flottante.                                                |
+| `▴`               | Déplie ou replie le panneau.                                                          |
+
+> **Pourquoi le flux est coupé par défaut** : l'abonnement fait tourner des
+> compteurs et un émetteur de journaux côté serveur. En développement on ouvre
+> beaucoup d'onglets ; les laisser tous branchés en permanence ferait payer à
+> l'application un travail que personne ne regarde. C'est un choix d'adhésion,
+> pas une option cachée.
+
+## Les cinq onglets
+
+**Realtime** — débit, transport, protocole, état de la socket, frames reçues,
+pic. C'est la vue de la socket elle-même.
+
+**Network** — les requêtes de la page (`fetch` et `XHR`), leur durée décomposée
+et leur statut. Désactivable (`network: false`) : c'est le seul onglet qui
+instrumente des fonctions globales du navigateur.
+
+**Perf** — processeur, mémoire, boucle d'événements du serveur.
+
+**Logs** — les journaux du serveur, en direct. Voir la section suivante.
+
+**Runtime** — l'identité du processus servi (version, environnement, `pid`,
+disponibilité, cœurs, mémoire), et **ce que la barre garde sur ce navigateur**.
+
+## L'onglet Logs
+
+Chaque entrée affiche son heure, sa sévérité, son module, son message et — quand
+elle est connue — sa **requête** (`requestId`). C'est ce dernier champ qui fait la
+différence : la même valeur relie ce journal à sa route, à ses requêtes de base de
+données et à sa réponse. Une entrée s'ouvre au clic (ou à `Entrée` au clavier)
+et montre son horodatage complet, sa catégorie, son worker et sa requête —
+de quoi coller une trace dans un ticket.
+
+La barre d'outils permet de :
+
+- **filtrer par sévérité** — les puces `err` et `warn` sont des bascules ;
+  recliquer celle qui est active la retire ;
+- **chercher** dans le texte, le module, la catégorie ou la requête ;
+- **suspendre** l'affichage. Les entrées continuent d'arriver : à la reprise, la
+  liste se recompose complète — une pause ne fait rien perdre ;
+- **copier** ce qui est affiché, **vider** la liste (sans rien effacer côté
+  serveur).
+
+La liste est mise à jour **en insérant** les nouvelles entrées, jamais en la
+reconstruisant : une sélection de texte survit à l'arrivée d'une ligne, et la
+position de défilement ne saute pas.
+
+## Ce que la barre garde sur votre navigateur
+
+Six valeurs, uniquement d'apparence, dans le stockage local — visibles dans
+l'onglet Runtime, avec un bouton pour les effacer :
+
+| Clé                   | Ce qu'elle retient           |
+| --------------------- | ---------------------------- |
+| `nf.debugbar.v`       | version du format ci-dessous |
+| `nf.debugbar.visible` | barre affichée ou masquée    |
+| `nf.debugbar.min`     | réduite en pastille          |
+| `nf.debugbar.side`    | côté du dock                 |
+| `nf.debugbar.tab`     | dernier onglet ouvert        |
+| `nf.debugbar.h`       | hauteur du panneau           |
+| `nf.debugbar.live`    | flux en direct activé        |
+
+Rien d'autre n'est stocké : aucun journal, aucune donnée d'application, aucune
+identité. L'état est **versionné** — si le format change, l'ancien est effacé au
+chargement plutôt que réinterprété, ce qui éviterait un état incohérent qu'on ne
+saurait pas défaire.
+
+## Options
+
+```ts
+mountDebugBar({
+  url: "/nodefony/studio/api/realtime", // adresse du canal temps réel
+  client: maSocket, // socket déjà ouverte à partager
+  position: "bottom", // ou "top"
+  open: false, // panneau déplié au montage
+  network: true, // onglet Network (instrumente fetch/XHR)
+});
+```
+
+`mountDebugBar()` est idempotent : une seule barre par page.
+
+## Accessibilité
+
+Tous les contrôles sont des boutons : ils s'atteignent au clavier, portent un nom
+et annoncent leur état (le replieur expose `aria-expanded`, le flux
+`aria-pressed`). L'aide de chaque indicateur s'ouvre aussi bien au focus qu'au
+survol. La barre se déclare comme un contenu d'appoint (`complementary`), ce qui
+évite que tout ce qu'elle affiche soit compté hors de tout point de repère par un
+audit de la page hôte.
+
+## Coût
+
+La barre est une entrée séparée du paquet (`nodefony/debugbar`) : elle ne pèse
+**rien** sur une application qui ne l'importe pas. Son budget est vérifié à chaque
+publication (`npm run size:check`).
+
+## 📖 Lexique
+
+| Terme                  | Ce que c'est                                                                                                                                                                                                   |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Entrée séparée**     | Un sous-chemin du paquet (`nodefony/debugbar`) importé à part. Ce qui n'est pas importé n'entre pas dans votre bundle.                                                                                         |
+| **`mountDebugBar`**    | La seule fonction à appeler (`index.ts:46`). Elle installe la barre et rend une poignée pour la piloter ou la retirer.                                                                                         |
+| **Poignée** (_handle_) | Ce que le montage rend en retour (`DebugBarHandle`, `DebugBar.ts:511`) : de quoi fermer, rouvrir ou démonter proprement.                                                                                       |
+| **Options**            | Ce qu'on passe au montage (`DebugBarOptions`, `DebugBar.ts:108`) — l'adresse du socket, la position (`bottom` ou `top`), le panneau ouvert d'emblée, et l'interception réseau, qu'on peut refuser entièrement. |
+| **Charge utile**       | Ce que le serveur pousse : statistiques (`StatsPayload`, `model.ts:25`) et journaux (`LogEntry`, `model.ts:49`).                                                                                               |
+| **`requestId`**        | L'identifiant qu'une requête porte de bout en bout. C'est lui qui relie une ligne de journal à l'appel réseau qui l'a produite.                                                                                |
+
+## ⚠️ Pièges
+
+- **Elle n'a rien à faire en production.** C'est un outil de développement : ce qu'elle affiche
+  décrit votre application à qui regarde l'écran. Ne l'importez que dans le bundle de
+  développement.
+- **Ce qu'elle garde vit dans le navigateur de chacun**, pas sur le serveur : un onglet ouvert,
+  un filtre, une position. Une fenêtre privée ou un autre navigateur repart donc de zéro — ce
+  n'est pas une panne.
+- **Une barre montée deux fois n'affiche pas deux barres**, mais laisse un montage orphelin :
+  gardez la poignée rendue par `mountDebugBar()` et démontez avant de remonter.
+- **Elle ne remplace pas les journaux du serveur.** Ce qu'elle montre est ce que le serveur a bien
+  voulu pousser vers le navigateur ; un incident au boot, avant qu'elle existe, ne s'y verra
+  jamais.
+
+## 🧪 Tests & couverture
+
+Les chiffres exacts vivent dans la carte de l'aperçu, régénérée en comptant — jamais figés ici.
+
+<!-- prettier-ignore -->
+| Type | Où | Ce qui est prouvé |
+| --- | --- | --- |
+| Unitaires | `nodefony` `DebugBar.test.ts` | le montage, les options, ce que la poignée rend, le rendu des cinq onglets |
+| Unitaires (interaction) | `nodefony` `debugbarInteraction.test.ts` | l'ouverture et la fermeture, le filtrage des journaux, ce qui est gardé d'une visite à l'autre |
+
+## 🔗 Pour aller plus loin
+
+- ⬆️ **Retour au hub** : [`nodefony` — le cœur](index.md) ·
+  [Toute la documentation](../../../docs/index.md)
+- 📜 **Ce qu'elle affiche vient de là** : [journalisation](syslog.md)
+- 🔗 **L'identifiant qui relie une ligne à sa requête** :
+  [contexte de requête](request-context.md)
+- 🛠️ **La même observation, mais côté serveur** :
+  [`@nodefony/studio`](../../packages/@nodefony/studio/docs/index.md)

package/docs/environnement.md

@@ -0,0 +1,308 @@
+---
+title: "Environnement — variables, cascade des .env, et qui gagne"
+navTitle: Environnement
+lang: fr
+module: "@nodefony/core"
+topic: environnement
+coverageModule: nodefony-core
+coveragePackage: "nodefony (cœur)"
+coverageFiles: "runtime/loadEnv.ts,config/defineEnv.ts,config/envOverride.ts,cli/envReport.ts"
+section: "Cœur runtime"
+audience: [developer, devops]
+tags:
+  [
+    environnement,
+    env,
+    dotenv,
+    variables,
+    precedence,
+    cascade,
+    secrets,
+    configuration,
+    NF,
+  ]
+version: "doc"
+status: stable
+updated: 2026-07-25
+source: "src/nodefony/docs/environnement.md"
+---
+
+# Environnement — variables, cascade des `.env`, et qui gagne
+
+📍 [Documentation](../../../docs/index.md) › [Cœur — @nodefony/core](index.md) › **Environnement**
+
+> Une variable d'environnement qui « ne prend pas » est le bug le plus long à comprendre du
+> métier : rien n'échoue, rien ne s'affiche, la valeur est simplement ignorée et un défaut
+> s'applique en silence. Cette page dit **où poser une valeur**, **qui l'emporte**, et surtout
+> comment le **vérifier** au lieu de le supposer.
+
+## 🧭 Démarrage rapide
+
+```bash
+nodefony env          # la cascade, chaque variable, sa valeur EFFECTIVE et sa PROVENANCE
+nodefony env --json   # le même rapport, pour un script ou un agent
+```
+
+La commande ne démarre rien ([`cli/env.ts:208`](../src/cli/env.ts)) — elle répond même sur une
+application qui ne boote plus, ce qui est précisément le moment où on la lance. Elle sort en
+**78** (`EX_CONFIG`) si une variable requise manque, pour qu'un script s'arrête là plutôt que de
+tenter un démarrage voué à l'échec.
+
+Ce qu'elle montre, et qu'aucune lecture de fichier ne donne :
+
+- la **cascade réelle** — quels fichiers sont lus, dans quel ordre, lesquels existent ;
+- chaque variable **déclarée** par l'application, sa valeur effective et **le fichier qui l'a
+  fournie** ;
+- ce qui est **masqué** : une valeur écrite dans un fichier de rang inférieur, donc sans effet ;
+- les variables `NF_` **inconnues** — presque toujours une faute de frappe, avec la correction
+  probable ;
+- les variables **posées par le framework** lui-même, à part, avec ce que chacune signale.
+
+> **Pourquoi ces deux dernières listes sont séparées.** Le framework écrit des `NF_*` dans
+> l'environnement sans que vous les ayez demandées : le lanceur du CLI marque sa délégation au
+> `nodefony` du projet (`NF_CLI_DELEGATED`), les commandes de démarrage inscrivent le mode
+> (`NF_MODE_START`), le maître de grappe signale la grappe (`NF_CLUSTER`), la déclaration MCP
+> porte son jeton (`NF_MCP_TOKEN`). Rangées parmi les inconnues, elles vous accusaient d'une
+> faute de frappe que vous n'aviez pas commise — et proposaient de « corriger »
+> `NF_CLI_DELEGATED` en `NF_ADMIN_PASSWORD`. Elles ne sont pas tues pour autant : une variable
+> présente que le rapport passe sous silence vous ferait chercher pourquoi votre environnement
+> ne ressemble pas à ce qu'il montre.
+
+## Le modèle : deux axes, une cascade, un seul lecteur
+
+Trois décisions gouvernent tout ce qui suit, et rien d'autre n'est à retenir.
+
+**Deux axes plutôt qu'un** : _comment_ le code s'exécute (le mode) et _où_ il s'exécute (le
+déploiement) sont deux questions distinctes — un `staging` tourne en mode `production`.
+
+**Une cascade, jamais un écrasement** : chaque source pose ce que les plus fortes n'ont pas déjà
+posé. La précédence n'est donc pas une règle appliquée quelque part, c'est une **conséquence** de
+l'ordre de lecture — il n'y a rien à synchroniser, et rien qui puisse diverger.
+
+**Un seul lecteur de `process.env`** : `env.ts`. Tout le reste de l'application lit un objet
+typé, validé au démarrage. Une variable non déclarée là n'existe pas, quoi qu'en dise un fichier
+`.env` — c'est ce qui rend une faute de frappe muette, et c'est pourquoi `nodefony env` existe.
+
+## Les deux axes : mode et déploiement
+
+Nodefony sépare ce que la plupart des frameworks confondent :
+
+| Axe             | Variable             | Valeurs                             | Ce qu'il décide                                     |
+| --------------- | -------------------- | ----------------------------------- | --------------------------------------------------- |
+| **Mode**        | `NODE_ENV`           | `development` / `production`        | comment le code s'exécute (optimisations, journaux) |
+| **Déploiement** | `APP_ENV` / `NF_ENV` | chaîne libre : `staging`, `canary`… | **où** il s'exécute (quelle base, quels secrets)    |
+
+Un `staging` tourne en mode `production` : ce sont deux questions différentes, et les mélanger
+oblige à choisir entre « optimisé » et « pointe la bonne base ». Le déploiement est **plus
+spécifique** que le mode, donc plus fort dans la cascade.
+
+## Et si `NODE_ENV` n'est pas posé ?
+
+C'est le cas de tous les jours sur une machine de développement — et la réponse n'est pas
+« au hasard ». **Poser `NODE_ENV` est un acte de déploiement ; ne rien poser est l'état d'un
+poste de développement.**
+
+| `NODE_ENV`                                        | Mode retenu       | Pourquoi                                          |
+| ------------------------------------------------- | ----------------- | ------------------------------------------------- |
+| `development` / `dev`                             | **`development`** | déclaré                                           |
+| `production` / `prod`                             | **`production`**  | déclaré                                           |
+| **absent**                                        | **`development`** | personne n'a rien dit → poste de développement    |
+| posé mais autre (`staging`, `canary`, `prod-eu`…) | **`production`**  | un DÉPLOIEMENT est nommé — il tourne comme prod   |
+| chaîne vide                                       | **`production`**  | choix conservateur : « vidée » ≠ « jamais posée » |
+
+Une chaîne vide compte comme posée : on ne distingue pas « vidée par erreur » de « vidée
+exprès », et se tromper vers la production ne coûte qu'une commande utilitaire, là où l'inverse
+exposerait la console d'administration d'un serveur.
+
+**Le défaut ne gouverne jamais un serveur.** `nodefony development`, `nodefony production`
+(alias `start`, `prod`) et `nodefony cluster` posent leur mode eux-mêmes, et il n'existe pas
+d'autre façon d'en démarrer un. Le défaut ne concerne donc que les commandes utilitaires —
+`inspect`, `check`, `env`, `security:*`.
+
+> ⚠️ **Le piège à connaître : une commande utilitaire ne tourne PAS dans le mode du serveur que
+> vous avez lancé.** Chacune démarre son propre noyau. Si votre serveur tourne par
+> `nodefony development` mais que `NODE_ENV` n'est pas dans votre shell, une commande lancée à
+> côté partira bien en `development` — mais le jour où vous exportez `NODE_ENV=production` pour
+> un essai, elle changera de base de données sans rien dire d'autre. **Demandez le mode plutôt
+> que de le supposer :**
+>
+> ```bash
+> npx nodefony env                 # le mode, et d'où vient chaque variable
+> npx nodefony inspect routes      # la dernière ligne indique l'environnement
+> ```
+>
+> Pour forcer explicitement, préfixez la commande : `NODE_ENV=production npx nodefony …`.
+
+## La cascade — qui gagne
+
+Du **plus fort** au **plus faible**. Le premier niveau qui pose une valeur gagne ; les suivants
+sont ignorés, sans message.
+
+| Rang | Source                     | Committé ? | Rôle                                           |
+| ---- | -------------------------- | ---------- | ---------------------------------------------- |
+| 1    | `process.env`              | —          | shell, orchestrateur, k8s — **gagne toujours** |
+| 2    | `.env.<déploiement>.local` | ❌ non     | secrets de CE déploiement, sur CETTE machine   |
+| 3    | `.env.<mode>.local`        | ❌ non     | secrets du mode                                |
+| 4    | `.env.local`               | ❌ non     | secrets communs, machine du développeur        |
+| 5    | `.env.<déploiement>`       | ✅ oui     | réglages partagés du déploiement               |
+| 6    | `.env.<mode>`              | ✅ oui     | réglages partagés du mode                      |
+| 7    | `.env`                     | ✅ oui     | défauts communs — le plus faible               |
+
+Deux règles suffisent à retrouver cet ordre de mémoire : **les `*.local` priment sur les
+committés**, et **à rang égal, le plus spécifique gagne**.
+
+L'ordre est produit par une fonction unique, [`envFileOrder`](../src/runtime/loadEnv.ts)
+([`loadEnv.ts:72`](../src/runtime/loadEnv.ts)) — celle-là même que `nodefony env` affiche : un
+ordre montré qui différerait de l'ordre appliqué serait pire que pas d'affichage du tout.
+L'injection ([`loadEnv.ts:88`](../src/runtime/loadEnv.ts)) n'écrase **jamais** une clé déjà
+posée, ce dont toute la précédence découle.
+
+Le chargement a lieu **une fois**, au démarrage du binaire, **avant** la construction du noyau :
+les configurations de modules lisent `process.env` pendant le boot, il doit donc être peuplé
+avant elles.
+
+## Déclarer une variable — `env.ts`
+
+`env.ts` est le **seul** endroit du projet qui lit `process.env`
+([`defineEnv.ts:270`](../src/config/defineEnv.ts)). Une variable non déclarée là n'existe pas
+pour l'application, quoi qu'un fichier `.env` en dise.
+
+```typescript
+import { defineEnv, envNumber, envEnum, envString } from "nodefony";
+
+export const env = defineEnv({
+  NF_PORT: envNumber({ default: 5151, description: "Port HTTP." }),
+  NF_LOG_DRIVER: envEnum(["stdout", "file", "null"], {
+    default: "stdout",
+    description: "Destination des journaux.",
+  }),
+  NF_DATABASE_URL: envString({
+    optional: true,
+    description: "URL de la base.",
+  }),
+});
+```
+
+Ce que la déclaration apporte, et qu'une lecture directe de `process.env` ne donne pas : la
+valeur est **typée** (`number`, `boolean`, énumération), **validée au démarrage** (une valeur
+hors énumération échoue tout de suite, avec le nom de la variable), **documentée**
+(`description` alimente `.env.example` et `nodefony env`), et **atteignable typée** dans la
+configuration via `ctx.env`.
+
+Une variable **requise** est celle qui n'a ni défaut ni `optional: true`. `nodefony env` les
+nomme, et sort en erreur si l'une manque.
+
+### Requise LÀ-BAS seulement — `requiredIn`
+
+Certaines variables ne sont indispensables qu'en production. Les déclarer `optional` est vrai
+sur le poste du développeur et faux là où ça compte ; les déclarer requises empêcherait de
+démarrer en local. `requiredIn` nomme les environnements où l'absence devient une faute :
+
+```typescript
+NF_CSRF_SECRET: envString({
+  optional: true,
+  requiredIn: ["production"],
+  description: "Secret des jetons anti-CSRF — partagé entre process en cluster.",
+}),
+```
+
+Le cas qui fonde cette règle n'est pas un secret laissé en dur, c'est l'inverse : **un secret
+absent est engendré à la volée**. Rien ne va mal au premier démarrage — c'est au deuxième
+exemplaire que les jetons émis par l'un se font refuser par l'autre, sans une ligne dans les
+journaux.
+
+Les noms sont libres : ils se comparent aux **étiquettes** de l'environnement courant, à savoir
+le mode d'exécution (`NODE_ENV`) et l'environnement de déploiement (`NF_ENV`, ou l'alias de
+plateforme `APP_ENV`) quand il en diffère. Une préproduction qui tourne en `production` porte
+donc les deux, et `requiredIn: ["preprod"]` y mord.
+
+Trois lecteurs appliquent la MÊME règle
+([`isEnvVarRequired`](../src/config/defineEnv.ts)) : le démarrage refuse de partir, `nodefony
+env` marque la variable, et `nodefony doctor` la nomme avant qu'on déploie.
+
+### Demander ce qui manquera ailleurs — `--env`
+
+`nodefony doctor --env production` et `nodefony env --env production` évaluent les exigences
+pour l'environnement **visé**, avec les valeurs présentes **ici** : on ne simule pas un
+déploiement, on demande ce qui manquera là-bas. Le rapport l'annonce en tête, et sort en erreur
+si une variable requise à destination n'a aucune valeur.
+
+`doctor` signale aussi un fichier `.env*.local` **suivi par git** — l'historique garde les
+secrets même après suppression. Sans dépôt git, il ne conclut pas : il énonce le contrôle comme
+non fait.
+
+## Secrets : `<VARIABLE>_FILE`
+
+Un secret monté par Docker ou Kubernetes est un **fichier**, pas une valeur. Toute variable
+accepte donc la forme `<VARIABLE>_FILE`, qui pointe le fichier à lire :
+
+```bash
+NF_TOTP_KEY_FILE=/run/secrets/totp_key    # au lieu de NF_TOTP_KEY=…
+```
+
+Poser les deux échoue au démarrage : entre deux sources contradictoires, deviner serait le pire
+service. Les valeurs des variables dont le nom évoque un secret ne sont jamais rendues en clair
+par `nodefony env` — seulement leur présence, leur longueur et leur provenance.
+
+## Surcharger une clé de module — `NF__`
+
+Deux mécanismes coexistent, et les confondre est l'erreur la plus fréquente :
+
+| Forme                                 | Ce que c'est                                    | Où c'est déclaré                           |
+| ------------------------------------- | ----------------------------------------------- | ------------------------------------------ |
+| `NF_PORT=5151`                        | variable de l'**application**, typée et validée | `env.ts` — non déclarée = **sans effet**   |
+| `NF__HTTP__SERVERS__HTTPS__PORT=8443` | surcharge **directe** d'une clé de module       | rien à déclarer — `__` sépare les segments |
+
+Le second ([`envOverride.ts:80`](../src/config/envOverride.ts)) vise une clé de configuration
+par son chemin, sans passer par `env.ts` : `NF__<MODULE>__<CHEMIN…>`. Une liste s'écrit en
+valeurs séparées par des virgules. Un segment mal orthographié est signalé au démarrage avec la
+clé la plus proche — le « vouliez-vous dire » de git.
+
+Réserve ce mécanisme à ce qu'il fait bien : régler une brique en exploitation sans toucher au
+code. Ce que l'application possède en propre se déclare dans `env.ts`.
+
+## 🧪 Tests
+
+Le calcul du rapport est un module **pur** ([`envReport.ts:177`](../src/cli/envReport.ts)) : il
+reçoit la cascade déjà lue et l'environnement effectif, et conclut. Cette séparation est ce qui
+rend éprouvables les trois affirmations sur lesquelles on va se fier pour corriger une
+configuration — d'où vient une valeur, ce qui est masqué, ce qui n'a aucun effet. Se tromper sur
+l'une d'elles est pire que de ne rien afficher : on croit le rapport, et on cherche ailleurs.
+
+## ⚠️ Pièges
+
+- **La valeur est dans le fichier, et n'a aucun effet.** Elle est posée à un rang inférieur à
+  celui qui la définit déjà — typiquement `.env` alors que `.env.local` la porte. `nodefony env`
+  l'affiche comme _ignorée dans …_, avec le fichier gagnant.
+- **Le shell gagne toujours.** Une variable exportée dans le terminal (ou par l'orchestrateur)
+  ne peut être contredite par aucun fichier. C'est voulu : en production, l'orchestrateur fait
+  autorité.
+- **Une faute de frappe est silencieuse.** `NF_PROT` au lieu de `NF_PORT` n'échoue pas : la
+  variable est inconnue, donc ignorée, et le défaut s'applique. Aucun démarrage ne le dira —
+  `nodefony env` est le seul endroit qui la montre.
+- **Un `.env.local` n'est jamais committé.** C'est la règle qui rend les secrets tenables ; le
+  `.gitignore` généré l'applique dès la création de l'application. Un secret dans `.env` part
+  dans le dépôt.
+- **Le catalogue exige un build.** `nodefony env` lit les variables déclarées dans le `dist/` de
+  l'application. Sans build, la cascade reste exacte et le rapport **dit** que la liste manque —
+  il ne se tait pas.
+
+## 📖 Lexique
+
+- **Cascade** — la suite ordonnée des sources d'environnement, du shell au `.env` commun.
+- **Mode** (`NODE_ENV`) — comment le code s'exécute : `development` ou `production`.
+- **Déploiement** (`APP_ENV`) — où il s'exécute : `staging`, `canary`, `prod-eu`… chaîne libre.
+- **Masquée** — variable définie dans un fichier, mais fournie par une source plus forte : elle
+  est ignorée.
+- **Effective** — la valeur que l'application verra réellement, après application de la cascade.
+- **Catalogue** — l'ensemble des variables qu'une application déclare dans `env.ts`, avec leur
+  type, leur défaut et leur description.
+
+## 🔗 Pour aller plus loin
+
+- ⬆️ **Retour au hub** : [Cœur — @nodefony/core](index.md)
+- ⚙️ **Configurer les modules** (le `use()` du manifeste, les schémas Zod) :
+  [guide de configuration](../../../docs/guides/configuration.md)
+- 🧩 **Quel module installer** : [catalogue des modules](catalogue.md)
+- 🖥️ **Les autres commandes** : [CLI](cli.md) · le cycle de vie qui consomme cet
+  environnement : [kernel](kernel.md)