nodefony 7.0.2 → 10.0.0-alpha.2

package/docs/angular-services.md

@@ -0,0 +1,318 @@
+---
+title: "Fonctions d'injection Angular — nodefony/angular"
+navTitle: Fonctions d'injection Angular
+lang: fr
+module: "@nodefony/core"
+topic: angular-services
+coverageModule: nodefony-core
+coveragePackage: "nodefony (cœur)"
+coverageFiles: "client/angular/index.ts,client/realtime/observe.ts"
+section: "Cœur runtime"
+audience: [developer]
+tags:
+  [
+    angular,
+    injection,
+    signals,
+    provider,
+    temps-reel,
+    websocket,
+    abonnement,
+    zone,
+    identite,
+    isomorphe,
+  ]
+version: "doc"
+status: stable
+updated: 2026-08-28
+source: "src/nodefony/docs/angular-services.md"
+---
+
+# Fonctions d'injection Angular — `nodefony/angular`
+
+> Le subpath `nodefony/angular` branche un composant Angular sur la socket Nodefony **sans une ligne
+> de glue** : un fournisseur posé dans les `providers` de l'application, puis des fonctions
+> d'injection qui s'abonnent à la construction et rendent l'abonnement à la destruction. Elles ne
+> gèrent **que** l'abonnement — ouvrir et maintenir la connexion reste le travail du client, décrit
+> dans [Client isomorphe](client.md). Le pendant exact de [Hooks React](react-hooks.md) et de
+> [Composables Vue](vue-composables.md) : même surface, mêmes noms, mêmes garanties. Ancré sur
+> `src/nodefony/src/client/angular/index.ts`.
+
+📍 [Documentation](../../../docs/index.md) › [Cœur — @nodefony/core](index.md) › **Fonctions d'injection Angular**
+
+## 🧠 Le modèle mental — une prise, N composants branchés dessus
+
+Un composant vit et meurt au gré de la navigation. Une socket, elle, doit rester ouverte. La liaison
+tient les deux bouts : **le fil est unique et long**, **les branchements sont nombreux et courts**.
+
+```mermaid
+flowchart LR
+  APP["main.ts<br/>provideNodefony({ url }) — UNE fois"] --> CL
+  subgraph CL["RealtimeClient (hors Angular)"]
+    direction TB
+    S["état · identité · notices"]
+    C["canaux ref-comptés"]
+  end
+  CL --> A["injectNodefonyState()<br/>Signal&lt;RealtimeState&gt;"]
+  CL --> B["injectNodefonyChannelData()<br/>Signal&lt;T | null&gt;"]
+  CL --> D["injectNodefonySnapshot()<br/>Signal&lt;SocketSnapshot&gt;"]
+  A --> V["le gabarit se réévalue"]
+  B --> V
+  D --> V
+```
+
+## 📖 Lexique
+
+| Terme                    | Ce que c'est ici                                                                                                      |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| **fournisseur**          | Un enregistrement d'injection de dépendances. C'est là que vit une politique, en Angular.                             |
+| **fonction d'injection** | Une fonction appelée dans un contexte d'injection, qui installe des effets et rend de l'état. L'idiome d'Angular 20+. |
+| **contexte d'injection** | Un initialiseur de champ, un constructeur, ou `runInInjectionContext` — le seul endroit où `inject()` a un sens.      |
+| **`Signal<T>`**          | Une valeur lue par appel (`etat()`), dont toute lecture dans un gabarit déclenche sa réévaluation.                    |
+| **`DestroyRef`**         | La durée de vie du composant. Ce qu'on y enregistre est rendu à sa destruction.                                       |
+| **zone**                 | `zone.js`, l'ancien moteur de détection de changements d'Angular. Absent en `provideZonelessChangeDetection()`.       |
+
+## Pourquoi un fournisseur, et pas un composant enveloppant
+
+React publie un `<NodefonyProvider>` parce qu'en React tout est composant. Vue installe un plugin.
+En Angular, une politique qui vaut pour l'application entière s'écrit dans ses `providers` :
+
+```ts
+bootstrapApplication(AppComponent, {
+  providers: [provideNodefony({ url: "/api/live/realtime" })],
+});
+```
+
+Traduire littéralement le fournisseur React aurait donné un composant de plus dans l'arbre, que
+personne n'aurait pensé à chercher. **Une liaison idiomatique n'est pas une traduction mot à mot :
+c'est la même garantie, dite dans la langue du framework.**
+
+## 🔴 Pourquoi ce subpath ne publie AUCUN décorateur Angular
+
+Il n'y a ni `@Injectable`, ni `NgModule`, ni classe décorée dans `nodefony/angular` — et ce n'est
+pas un raccourci.
+
+Un décorateur Angular n'est pas du JavaScript : c'est une instruction pour le compilateur d'Angular,
+qui doit la **transformer**. Une bibliothèque qui en publie doit donc être bâtie par `ng-packagr`, au
+format de paquet Angular (_partial compilation_, puis _linker_ côté application) — une seconde chaîne
+de build pour un subpath sur quatre, et un couplage du paquet publié aux majeures d'Angular. Non
+compilé, un décorateur marche parfois en développement, quand `@angular/compiler` se trouve chargé
+dans la page, et **casse en production**, où il ne l'est pas : exactement le défaut qui ne se voit
+jamais chez celui qui l'écrit.
+
+La forme retenue — `InjectionToken`, `makeEnvironmentProviders`, fonctions `inject*()` — est celle
+qu'Angular emploie **pour lui-même** : `provideHttpClient()`, `provideRouter()`,
+`takeUntilDestroyed()`. C'est du TypeScript ordinaire, que le bundler du framework produit comme le
+reste, avec une injection de dépendances et un `DestroyRef` intacts.
+
+> ⚠️ **Cela ne restreint en rien ton application.** `@Component`, `@Injectable`, `@Directive`,
+> `@Pipe` y sont compilés par le plugin Angular du builder Nodefony
+> (`@analogjs/vite-plugin-angular`, qui embarque `@angular/compiler-cli`). Les fonctions ci-dessous
+> s'appellent depuis tes propres classes décorées.
+
+## La règle qu'Angular impose, et qui est chiffrée : hors zone
+
+Avec `zone.js`, Angular remplace `WebSocket` pour savoir quand relancer la détection de changements.
+Une socket ouverte **dans** la zone déclenche donc une détection **globale à chaque trame** : un
+canal à 10 Hz coûte dix détections par seconde à toute l'application — et rien ne le dirait, la page
+s'affiche parfaitement.
+
+`provideNodefony` ouvre donc la connexion dans `NgZone.runOutsideAngular`
+(`src/nodefony/src/client/angular/index.ts:202`). Les valeurs, elles, arrivent par des **signals**,
+qui notifient leurs lecteurs sans zone : justes dans les deux mondes, `zone.js` ou
+`provideZonelessChangeDetection()`.
+
+## 🚀 Démarrage rapide
+
+### 1. Le fournisseur, sur l'application
+
+```ts
+// frontend/src/main.ts
+import { bootstrapApplication } from "@angular/platform-browser";
+import { provideZonelessChangeDetection } from "@angular/core";
+import { provideNodefony } from "nodefony/angular";
+import { AppComponent } from "./app/app.component";
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideZonelessChangeDetection(),
+    provideNodefony({ url: "/api/live/realtime" }),
+  ],
+}).catch((err) => console.error(err));
+```
+
+L'adresse est écrite **ici, et nulle part ailleurs**. Le framework n'en devine aucune : une adresse
+devinée marche en développement et se trompe en production. Sans `url` ni `client`, le fournisseur
+refuse — et il refuse **à la composition des providers**
+(`src/nodefony/src/client/angular/index.ts:186`), pas au premier rendu d'un composant, où l'erreur
+se lirait loin de sa cause.
+
+### 2. La page
+
+```ts
+// frontend/src/app/app.component.ts
+import { Component } from "@angular/core";
+import {
+  injectNodefony,
+  injectNodefonyChannelData,
+  injectNodefonyState,
+} from "nodefony/angular";
+
+interface LiveEvent {
+  text: string;
+  ts: number;
+}
+
+@Component({
+  selector: "app-root",
+  template: `
+    <p>connexion : {{ state() }}</p>
+    @if (last(); as e) {
+      <p>{{ e.text }}</p>
+    }
+    <button (click)="say('bonjour')">envoyer</button>
+  `,
+})
+export class AppComponent {
+  private readonly live = injectNodefony();
+  readonly state = injectNodefonyState();
+  readonly last = injectNodefonyChannelData<LiveEvent>("live:events");
+
+  say(text: string): void {
+    this.live.emit("live:say", { text });
+  }
+}
+```
+
+Il n'y a **rien à libérer** : `DestroyRef` rend les abonnements à la destruction du composant. C'est
+la différence visible avec un câblage à la main, où il fallait tenir une liste de fonctions de
+libération et n'en oublier aucune.
+
+### 3. Quand l'application possède son cycle de connexion
+
+```ts
+import { RealtimeClient } from "nodefony/client";
+import { provideNodefony } from "nodefony/angular";
+
+declare const maSocket: RealtimeClient;
+
+// La socket fournie l'emporte sur `url`, et son cycle n'est pas touché :
+// ni `connect`, ni `disconnect`.
+provideNodefony({ client: maSocket });
+```
+
+### 4. Un canal qui change
+
+```ts
+import { Component, signal } from "@angular/core";
+import { injectNodefonyChannelData } from "nodefony/angular";
+
+interface Message {
+  text: string;
+}
+
+@Component({ selector: "app-salon", template: `` })
+export class SalonComponent {
+  readonly salle = signal("salon:general");
+  // L'abonnement SUIT le signal : l'ancien canal est rendu avant que le
+  // nouveau soit pris. Aucun tableau de dépendances à tenir.
+  readonly messages = injectNodefonyChannelData<Message>(this.salle);
+}
+```
+
+Un argument constant ne coûte **aucun** effet : le branchement est direct, et seule une source
+_fonction_ installe un `effect` (`src/nodefony/src/client/angular/index.ts:263`).
+
+## 🧰 Les fonctions
+
+Toutes rendent un `Signal` en lecture — on l'appelle (`etat()`), y compris dans un gabarit. La
+socket, elle, n'est pas un signal : c'est un objet, pas un état.
+
+| Fonction                                  | Rend                               | À quoi ça sert                                               |
+| ----------------------------------------- | ---------------------------------- | ------------------------------------------------------------ |
+| `provideNodefony(opts)`                   | `EnvironmentProviders`             | le fournisseur : enregistre la socket, connecte hors zone    |
+| `injectNodefony()`                        | `RealtimeClient`                   | l'échappatoire : `emit`, `request`, `mutate`, `ping`         |
+| `injectNodefonyState()`                   | `Signal<RealtimeState>`            | afficher l'état, griser un bouton pendant une reconnexion    |
+| `injectNodefonyIdentity()`                | `Signal<RealtimeIdentity \| null>` | savoir qui est connecté — sans appeler `/auth/me`            |
+| `injectNodefonyChannel(canal, onMessage)` | —                                  | réagir à chaque message (journal, son, animation)            |
+| `injectNodefonyChannelData<T>(canal)`     | `Signal<T \| null>`                | la dernière valeur — le cas le plus courant                  |
+| `injectNodefonyAdaptiveChannel(…)`        | `Signal<number>`                   | même chose, en cadence auto-ajustée ; rend la cadence        |
+| `injectNodefonyAdaptiveChannelData<T>(…)` | `{ data, intervalMs }`             | la dernière valeur **et** la cadence                         |
+| `injectNodefonyChannelStats(canal)`       | `Signal<MessageStats \| null>`     | débit et série d'un canal, pour un VU-mètre                  |
+| `injectNodefonySnapshot()`                | `Signal<SocketSnapshot \| null>`   | ce que la socket sait d'elle-même : canaux, trames, dernière |
+| `injectNodefonySyslog(opts?)`             | `Signal<unknown[]>`                | le flux de journal, anneau borné et filtre de sévérité       |
+| `injectNodefonyNotifications(onNotice)`   | —                                  | les notices normalisées — à monter **une seule fois**        |
+| `injectNodefonyNoticeLog(opts?)`          | `Signal<NodefonyNotice[]>`         | l'historique borné des incidents                             |
+
+La déclaration de chacune se lit dans `src/nodefony/src/client/angular/index.ts:284` et suivantes.
+
+Sont aussi réexportés depuis ce subpath : `NODEFONY_CLIENT` (le jeton, pour fournir une AUTRE socket
+à un sous-arbre), `rateChannel`, `parseRate`, `isRateChannel` (fabriquer un nom de canal cadencé), et
+les types `RealtimeIdentity`, `RealtimeState`, `NodefonyNotice`, `SocketSnapshot` — pour qu'un
+composant puisse **nommer** ce qu'il reçoit.
+
+Les arguments « canal » et « cadence » acceptent une valeur, un signal ou une fonction : l'abonnement
+suit, sans liste de dépendances.
+
+## 🏗️ Cycle de vie d'un abonnement
+
+```
+construction       → subscribe (si premier consommateur du canal)
+message reçu       → le signal change → le gabarit se réévalue
+canal qui change   → unsubscribe de l'ancien, subscribe du nouveau
+reconnexion        → le client rejoue TOUS les abonnements, sans rien à faire
+destruction        → unsubscribe (si dernier consommateur)
+```
+
+Ce qui est **partagé** et ne dépend pas d'Angular — le comptage de références, le rejeu après
+reconnexion, l'appariement `on`↔`subscribe` — vit dans le socle agnostique et est prouvé une fois
+pour les quatre fronts. Ce qui est **propre à Angular** — le contexte d'injection, les signals,
+l'ouverture hors zone, la libération — est prouvé dans
+`src/nodefony/src/tests/clientAngular.test.ts:1`.
+
+La socket, elle, **n'est jamais coupée par un composant**. Elle appartient à la page : la fermer à la
+destruction trancherait les requêtes en vol des autres consommateurs.
+
+## ⚠️ Pièges (symptôme → cause → correction)
+
+| Symptôme                                                            | Cause                                                                         | Correction                                                                    |
+| ------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `injectNodefony() : provideNodefony() n'est pas dans les providers` | La fonction est appelée dans une application où le fournisseur n'est pas posé | Ajouter `provideNodefony({ url })` aux `providers` de `bootstrapApplication`  |
+| `NG0203: inject() must be called from an injection context`         | Appel dans un gestionnaire d'événement, un `setTimeout`, au niveau du module  | Appeler dans un initialiseur de champ ou le constructeur                      |
+| Le fournisseur lève à la composition                                | Ni `url` ni `client` fourni — le framework ne devine aucune adresse           | Passer l'URL du serveur temps réel                                            |
+| L'application rame dès qu'un canal débite                           | La socket a été ouverte DANS la zone (câblage manuel, `zone.js` actif)        | Passer par `provideNodefony`, qui ouvre hors zone                             |
+| Rien n'arrive et l'état reste `disconnected`                        | Le serveur n'écoute pas cette adresse, ou la socket a été coupée              | Vérifier l'adresse du fournisseur, et qu'aucun code n'appelle `disconnect()`  |
+| `Module 'nodefony' has no exported member 'RealtimeClient'`         | Condition d'export `browser` inactive dans le `tsconfig.json` de l'app        | Importer depuis `nodefony/client`, ou ajouter `customConditions: ["browser"]` |
+| Le canal se ré-abonne sans raison                                   | Le nom du canal est recalculé par une fonction qui lit trop de signals        | Ne faire dépendre la source que de ce qui doit vraiment ré-abonner            |
+| `needs to be compiled using the JIT compiler` dans un test          | Un contexte Angular est monté sans compilateur                                | `import "@angular/compiler";` en tête du banc — jamais dans le code livré     |
+| Notices en double                                                   | `injectNodefonyNotifications` appelé dans plusieurs composants                | Un seul appel, au shell de l'application                                      |
+| Une exception dans un rappel disparaît sans trace                   | Le dispatch du client isole les erreurs de handler                            | Envelopper le corps du rappel dans son propre `try`/`catch`                   |
+
+## 🧪 Tests & couverture
+
+- **Les règles du temps réel** (comptage de références, rejeu après reconnexion, dernier reçu gagne,
+  anneaux, filtres) sont prouvées **une fois pour les quatre fronts** dans
+  `src/nodefony/src/tests/clientObserve.test.ts`. Les rejouer à travers Angular mesurerait le socle.
+- **La traduction Angular** est prouvée dans `src/nodefony/src/tests/clientAngular.test.ts` :
+  contexte d'injection exigé, canal signal qui déplace l'abonnement, **ouverture hors zone** — jugée
+  sur le moment où le transport est fabriqué, puisque c'est lui que `zone.js` remplace — et surtout
+  **la destruction qui rend l'abonnement au serveur**, comptée sur les trames émises, seul juge
+  d'une fuite.
+- **La surface publiée** est tenue par `clientSubpathSurface.types.test.ts` : ce que les fonctions
+  rendent doit pouvoir être **nommé** par un consommateur, et les quatre subpaths parlent des mêmes
+  types, pas de jumeaux.
+- **Le banc monte une vraie application** (`createApplication`, ce que `bootstrapApplication`
+  appelle) : un injecteur fabriqué à la main n'exercerait pas le chemin réel — `effect()` y lève
+  `NG0201`, faute du planificateur de détection de changements.
+
+Couverture : `npm run coverage` dans `src/nodefony`.
+
+## 🔗 Pour aller plus loin
+
+- ⬆️ **Retour au hub** : [@nodefony/core — vue d'ensemble](index.md) · [Toute la documentation](../../../docs/index.md)
+- 🧭 **Pages sœurs** : [Client isomorphe](client.md) — la socket, le transport, la reconnexion, les
+  rôles · [Hooks React](react-hooks.md) · [Composables Vue](vue-composables.md) — la même surface,
+  dans les autres langues · [Journalisation](syslog.md)
+- Le vocabulaire commun aux deux bords du fil → [Vocabulaire de la socket](../../packages/@nodefony/realtime/docs/vocabulaire.md)
+- Le module serveur qui pousse les canaux → [@nodefony/realtime](../../packages/@nodefony/realtime/docs/index.md)
+- Qui sert et reconstruit ton interface → [@nodefony/frontend](../../packages/@nodefony/frontend/docs/index.md)

package/docs/catalogue.md

@@ -0,0 +1,184 @@
+---
+title: "Catalogue des modules — quel module pour quel besoin"
+navTitle: Catalogue des modules
+lang: fr
+module: "@nodefony/core"
+topic: catalogue
+section: "Cœur runtime"
+audience: [developer]
+tags:
+  [
+    catalogue,
+    modules,
+    dependances,
+    choix,
+    orm,
+    realtime,
+    security,
+    redis,
+    manifeste,
+  ]
+version: "doc"
+status: stable
+updated: 2026-07-25
+source: "src/nodefony/docs/catalogue.md"
+# Page d'ORIENTATION, pas de référence : elle envoie vers des modules et n'explique
+# aucune brique. Lui réclamer des ancres `fichier:ligne` fabriquerait du faux.
+hub: true
+---
+
+# Catalogue des modules — quel module pour quel besoin
+
+📍 [Documentation](../../../docs/index.md) › [Cœur — @nodefony/core](index.md) › **Catalogue des modules**
+
+> Nodefony ne fournit pas UNE façon de tout faire : il fournit un socle, et des modules qu'une
+> application **déclare**. Cette page répond à la seule question qu'on se pose avant d'écrire du
+> code : _quel paquet installer pour ce besoin, et lequel ne PAS installer_. Elle est publiée
+> avec le cœur — une application l'a donc sous la main dans
+> `node_modules/nodefony/docs/catalogue.md`, sans réseau ni dépôt.
+
+## 🧭 Par où commencer
+
+1. Trouve ton besoin dans les familles ci-dessous — chaque entrée dit aussi **quand ne PAS**
+   prendre le module, ce qu'aucune page de vente ne fait.
+2. Déclare-le (trois pas, section suivante).
+3. Vérifie sur pièce : `nodefony inspect modules --json` liste ce qui est **réellement** chargé.
+
+## Déclarer un module — le geste, une fois pour toutes
+
+Trois pas, toujours les mêmes :
+
+```bash
+npm install @nodefony/<module>
+```
+
+```typescript
+// nodefony.config.ts — manifeste `modules`
+use("@nodefony/<module>", {/* options */});
+```
+
+```bash
+nodefony inspect modules --json   # ce qui est RÉELLEMENT chargé, sans ouvrir de port
+```
+
+**Les clés de configuration ne sont pas dans cette page** — et c'est voulu : elles vivent dans le
+schéma du module, `node_modules/@nodefony/<module>/dist/nodefony/config/config.js`, où chaque clé
+porte son défaut et sa description. Une page qui les recopierait mentirait à la première évolution.
+`nodefony inspect config <module>` en donne la valeur **effective** et sa provenance.
+
+## Le socle — présent dans toute application
+
+Ces trois-là ne se choisissent pas : `nodefony create app` les pose.
+
+| Paquet                | Ce qu'il apporte                                                                               |
+| --------------------- | ---------------------------------------------------------------------------------------------- |
+| `nodefony`            | Le cœur : `Service`, conteneur d'injection, `Kernel`, `Module`, journal, CLI, client isomorphe |
+| `@nodefony/http`      | Serveurs HTTP/HTTP2/WebSocket, contextes de requête, sessions, TLS                             |
+| `@nodefony/framework` | Routeur, contrôleurs, décorateurs de route, idempotence                                        |
+
+## Sécurité & identité
+
+<!-- prettier-ignore -->
+| Paquet | Prends-le quand… | Ne le prends pas si… |
+| --- | --- | --- |
+| `@nodefony/security` | une partie de l'application doit être fermée : zones de pare-feu, six méthodes d'authentification, autorisation par voters, CSRF/CORS, 2FA, passkeys, journal d'audit | l'application est entièrement publique — mais la fermer plus tard coûte alors une reprise des routes |
+| `@nodefony/user` | tu veux des comptes utilisateurs (contrat `IUser`, encodeurs de mot de passe) sans dépendre du pare-feu | l'identité vient d'ailleurs (jeton d'un fournisseur externe, service amont) |
+
+`@nodefony/security` embarque déjà `@nodefony/user` : le déclarer seul n'a de sens que pour gérer
+des comptes **sans** fermer de routes.
+
+## Données
+
+Un contrat commun, plusieurs implémentations : écris contre le contrat, choisis le moteur ensuite.
+
+<!-- prettier-ignore -->
+| Paquet | Prends-le quand… | Ne le prends pas si… |
+| --- | --- | --- |
+| `@nodefony/orm-core` | jamais directement — c'est le contrat, tiré par l'adaptateur que tu choisis | — |
+| `@nodefony/drizzle` | **le défaut** : SQL (PostgreSQL, MySQL/MariaDB, SQLite), `nodefony create entity` cible lui | tes données sont des documents sans schéma stable |
+| `@nodefony/mongoose` | MongoDB, données orientées document | tu as besoin d'un des **stores qu'il ne fournit pas** : il en couvre 5 (session, user, tokens, passkeys, webhooks) là où `drizzle` en couvre 8 — `totp`, `audit` et `idempotency` lui manquent |
+| `@nodefony/redis` | cache, sessions partagées entre pods, backplane du temps réel en cluster | un seul processus : les sessions en mémoire et le backplane local suffisent |
+
+**L'arbitrage qui revient le plus souvent** : `drizzle` ou `mongoose` ? Le générateur d'entités
+(`nodefony create entity`) produit du Drizzle natif du dialecte ; partir sur Mongoose, c'est écrire
+ses modèles à la main. Prends `mongoose` parce que tes données SONT des documents, pas pour éviter
+de choisir un dialecte SQL.
+
+**La couverture d'un adaptateur est ADAPTÉE, pas identique.** Chaque adaptateur déclare les
+_stores_ qu'il sait tenir (`nodefony.stores` de son `package.json`) : `drizzle` les huit,
+`mongoose` cinq, `redis` quatre. Ce n'est pas un retard de développement mais un choix — stocker
+un journal d'audit ou un verrou d'idempotence dans un moteur documentaire n'a pas de sens partout.
+Conséquence pratique : un adaptateur ne remplace pas l'autre, ils se **complètent**, et
+`nodefony inspect stores` dit où chaque donnée atterrit RÉELLEMENT dans ton application.
+
+**Et `redis` ?** Il ne sert à rien tant que l'application tourne dans un seul processus. Il devient
+nécessaire à l'instant où il y en a deux : sans lui, deux pods ont deux annuaires de sessions et
+deux hubs temps réel qui ne se parlent pas.
+
+## Temps réel & interface
+
+| Paquet                    | Prends-le quand…                                                                                                                      | Ne le prends pas si…                                                        |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `@nodefony/realtime`      | le serveur doit **pousser** : une connexion qui multiplexe N canaux bidirectionnels, actions RPC, backplane cluster                   | un simple echo WebSocket suffit — `@nodefony/http` le fait déjà             |
+| `@nodefony/frontend`      | l'application sert une interface Vite (React, Vue, Angular), en rechargement à chaud en développement et pré-construite en production | l'application n'est qu'une API                                              |
+| `@nodefony/studio`        | tu veux voir l'intérieur en marche : routes, services, configuration, sessions, journaux, en **développement**                        | production — c'est un outil de développement, pas un tableau de bord public |
+| `@nodefony/documentation` | tu publies des pages de documentation servies par l'application elle-même                                                             | tu écris de la documentation lue seulement dans le dépôt                    |
+| `@nodefony/devkit`        | tu développes l'application **avec un agent** : carte de visite de l'application, portes de découverte de l'outillage                 | production — ce qu'il expose n'y est plus une aide, mais une divulgation    |
+
+`@nodefony/studio` tire `@nodefony/frontend` : le déclarer suffit à avoir les deux.
+
+`@nodefony/devkit` se déclare `policy: "dev"` : hors développement, il n'est même pas importé.
+
+## 🗂️ La documentation de chaque module
+
+Une fois le module choisi, sa documentation est **installée avec lui** — lis ciblé, jamais tout le
+dossier.
+
+```nodefony-cards
+[
+  { "icon": "🔌", "title": "@nodefony/http", "href": "../../packages/@nodefony/http/docs/index.md",
+    "desc": "Serveurs, contextes, sessions, TLS.", "meta": "le transport" },
+  { "icon": "🧭", "title": "@nodefony/framework", "href": "../../packages/@nodefony/framework/docs/index.md",
+    "desc": "Routeur, contrôleurs, décorateurs.", "meta": "tu écris des routes" },
+  { "icon": "🛡️", "title": "@nodefony/security", "href": "../../packages/@nodefony/security/docs/index.md",
+    "desc": "Pare-feu par zones, authentification, autorisation, audit.", "meta": "fermer l'application" },
+  { "icon": "👤", "title": "@nodefony/user", "href": "../../packages/@nodefony/user/docs/index.md",
+    "desc": "Contrat `IUser`, stockage des comptes, mots de passe.", "meta": "les comptes" },
+  { "icon": "📐", "title": "@nodefony/orm-core", "href": "../../packages/@nodefony/orm-core/docs/index.md",
+    "desc": "Le contrat commun à tous les moteurs.", "meta": "le contrat" },
+  { "icon": "🐘", "title": "@nodefony/drizzle", "href": "../../packages/@nodefony/drizzle/docs/index.md",
+    "desc": "SQL — PostgreSQL, MySQL/MariaDB, SQLite.", "meta": "le défaut" },
+  { "icon": "🍃", "title": "@nodefony/mongoose", "href": "../../packages/@nodefony/mongoose/docs/index.md",
+    "desc": "MongoDB, données orientées document.", "meta": "document" },
+  { "icon": "⚡", "title": "@nodefony/redis", "href": "../../packages/@nodefony/redis/docs/index.md",
+    "desc": "Cache, sessions partagées, backplane du temps réel.", "meta": "dès le 2ᵉ processus" },
+  { "icon": "🛰️", "title": "@nodefony/realtime", "href": "../../packages/@nodefony/realtime/docs/index.md",
+    "desc": "Une connexion, N canaux bidirectionnels, backplane cluster.", "meta": "le serveur pousse" },
+  { "icon": "🎨", "title": "@nodefony/frontend", "href": "../../packages/@nodefony/frontend/docs/index.md",
+    "desc": "Build Vite, rechargement à chaud, React/Vue/Angular.", "meta": "servir une interface" },
+  { "icon": "🛠️", "title": "@nodefony/studio", "href": "../../packages/@nodefony/studio/docs/index.md",
+    "desc": "L'administration web : voir l'intérieur en marche.", "meta": "développement" },
+  { "icon": "📘", "title": "@nodefony/documentation", "href": "../../packages/@nodefony/documentation/docs/index.md",
+    "desc": "Le portail qui rend ces pages, et son data plane.", "meta": "méta" },
+  { "icon": "🧰", "title": "@nodefony/devkit", "href": "../../packages/@nodefony/devkit/docs/index.md",
+    "desc": "Carte de visite de l'application, portes de découverte pour un agent.", "meta": "développement" }
+]
+```
+
+## Ce que ce catalogue ne dit pas
+
+- **Les clés de configuration** — elles vivent dans le schéma du module (voir plus haut). Les
+  recopier ici les périmerait.
+- **Les versions** — une publication les fixe toutes ensemble ; `npm install @nodefony/<module>`
+  prend celle qui correspond à ton cœur.
+- **Ce que ton application charge vraiment** — `nodefony inspect modules --json` le dit, et lui ne
+  peut pas se tromper.
+
+## 🔗 Pour aller plus loin
+
+- ⬆️ **Retour au hub** : [Cœur — @nodefony/core](index.md)
+- 🧭 **Le cycle de vie** qui charge ces modules : [kernel.md](kernel.md) · les commandes qui les
+  interrogent : [cli.md](cli.md)
+- ⚙️ **Régler un module sans toucher au code** — variables, cascade des `.env`, précédence :
+  [environnement.md](environnement.md)
+- 📖 [Lexique général](../../../docs/lexique.md) du framework.