@nodefony/devkit 10.0.0-beta.5 → 10.0.0-beta.7

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

@@ -1,21 +1,21 @@
 ---
 name: nodefony-migrate-schema
 description: >
-  Fait évoluer le schéma d'une base Nodefony et le porte en production, par les commandes
-  `orm:generate` et `orm:migrate` du framework — jamais par un `ALTER` écrit à la main ni par la
-  suppression d'une base. Porte la lecture de l'état (que l'application tourne ou non), le plan
-  avant le geste, les codes de refus et le geste que chacun appelle, les trois interdits qui
-  cassent un historique, et le patron de déploiement où les migrations passent AVANT les
-  exemplaires. À charger AVANT de modifier une entité déjà en base, ou avant de déployer un schéma
-  changé.
+  Fait évoluer le schéma d'une base Nodefony et le porte en production, par `orm:generate` et
+  `orm:migrate` — jamais par un `ALTER` à la main ni en supprimant la base. Porte la lecture de
+  l'état, le plan avant le geste, chaque code de refus et son geste, le renommage déclaré, les trois
+  interdits qui cassent un historique, et le déploiement où les migrations passent AVANT les
+  exemplaires. À charger AVANT de modifier une entité déjà en base, ou de déployer un schéma changé.
   Déclencheurs : "j'ai ajouté un champ à une entité", "la colonne n'existe pas en base",
-  "modifier une table existante", "migrer le schéma", "orm:migrate", "orm:generate",
-  "appliquer les migrations", "déployer un changement de schéma", "no such column",
+  "migrer le schéma", "orm:migrate", "orm:generate", "déployer un changement de schéma",
+  "no such column",
   "column does not exist", "ma base ne correspond plus au code", "adopter une base existante",
   "réparer une migration en échec", "éprouver une migration sans casser ma base",
-  "rejouer les migrations depuis zéro".
+  "rejouer les migrations depuis zéro", "renommer une colonne ou une table",
+  "changer le type ou la longueur d'une colonne", "changer de base", "passer à PostgreSQL ou
+  MySQL".
 metadata:
-  version: 2
+  version: 4
 ---
 
 # Faire évoluer un schéma, et le porter en production
@@ -29,18 +29,27 @@ metadata:
 > la ligne exacte :
 > `node node_modules/@nodefony/devkit/skills/nodefony-dev/scripts/docs.mjs <termes>`.
 
-## 1. La seule chose à savoir avant tout le reste
+## 1. La seule chose à savoir avant tout le reste — QUI fabrique le schéma ici ?
 
-**En développement, il n'y a rien à faire.** La base suit le code : la table naît au démarrage, et
-un champ ajouté **qui accepte le vide** est posé au démarrage suivant.
+La clé `ddl` d'un connecteur répond à une seule question : qui fabrique les tables. Le mode n'est
+presque jamais écrit, il se DÉDUIT — et c'est lui qui décide du geste.
 
-**Deux cas seulement sortent de là**, et ce sont eux qui amènent ici :
+| Situation                                                | Mode      | Qui fabrique les tables                                     |
+| -------------------------------------------------------- | --------- | ----------------------------------------------------------- |
+| `ddl` écrit dans la configuration                        | lui       | ce que dit la configuration — il gagne toujours             |
+| développement, l'application versionne **≥ 1** migration | `migrate` | les migrations, appliquées au démarrage                     |
+| développement, **aucune** migration ; ou `NODE_ENV=test` | `auto`    | le démarrage, d'après les entités (création + ajouts vides) |
+| **tout le reste**, production comprise                   | `none`    | personne au démarrage : un job lance `orm:migrate` AVANT    |
 
-- un champ **obligatoire** ajouté à une table qui existe déjà — il n'est jamais rattrapé ;
-- **la production**, où le démarrage ne fabrique JAMAIS le schéma.
+🔴 **Une application créée par `nodefony create app` avec un ORM SQL est en `migrate` dès
+l'installation** : le générateur écrit ET applique sa migration initiale. Le cas courant, en
+développement, est donc : **une entité change → une migration s'écrit** (§ 3). Ne crois pas
+qu'« en développement la base suit le code » sans avoir vérifié qu'aucune migration n'existe
+(`npx nodefony orm:migrate:status --json`).
 
-Si l'application est en développement et que le champ ajouté accepte le vide, il suffit de
-redémarrer. Ne produis pas une migration pour ça.
+En `auto` seulement, un champ ajouté **qui accepte le vide** est posé au démarrage suivant — rien à
+taper. Tout le reste (renommage, type, longueur, suppression, champ obligatoire) n'y est JAMAIS
+rattrapé : l'ancienne colonne reste en base, la nouvelle naît vide.
 
 ## 2. Lire l'état — deux voies, selon que l'application tourne
 
@@ -115,6 +124,62 @@ relue et versionnée en amont, et c'est `orm:migrate` seul qui l'applique.
 > second échoue sur un objet qui n'a jamais existé. Un `ddl` écrit dans la configuration gagne
 > toujours ; sous `NODE_ENV=test`, rien ne change.
 
+### 🔴 Un RENOMMAGE — le DÉCLARER, jamais le laisser deviner
+
+Une colonne qui disparaît pendant qu'une autre apparaît, c'est un renommage (les données suivent)
+OU une suppression puis un ajout (les données sont perdues). Aucun diff ne voit une intention. Ne
+lance donc JAMAIS `orm:generate` nu après avoir renommé un champ : il s'arrête
+(`NF_GENERATE_NEEDS_ANSWER`), et **il n'y a pas de question à laquelle répondre** — l'outil tourne
+sans terminal, humain devant l'écran compris. La réponse se DÉCLARE :
+
+```bash
+# une colonne : la table sous le nom que porte son entité
+npx nodefony orm:generate --name titre_en_anglais --rename article.titre=title
+# une table, puis une colonne DANS la table renommée (son NOUVEAU nom)
+npx nodefony orm:generate --name lignes --rename invoice_line=invoice_det --rename invoice_det.fk_parent_line=fk_parent
+```
+
+- La migration porte un `RENAME`, **changement de type compris** (`varchar(8)` → `varchar(16)`
+  renommé ET élargi s'écrit en entier).
+- Le rapport `--json` le confirme : `renamed: ["article.titre → title"]`. Relis le fichier quand même.
+- Un nom mal écrit, une ancienne colonne absente du dernier instantané, un nouveau nom qu'aucune
+  entité ne déclare : refus `NF_GENERATE_RENAME`, **rien n'est écrit**.
+- Une VRAIE suppression ET un ajout sans rapport dans la même table : **deux générations** — d'abord
+  l'entité sans la colonne retirée (la perte est nommée par le garde destructif), puis avec
+  l'ajout. Ne déclare pas `--rename` pour faire taire l'outil : ce serait mentir sur les données.
+
+Allonger une colonne (`varchar(16)` → `varchar(32)`) ou monter un entier de rang (`integer` →
+`bigint`) n'est PAS destructif : le générateur le constate sur l'état de départ et n'exige rien. Le
+raccourcir, ou rendre la colonne obligatoire, reste refusé sans `--allow-destructive`.
+
+### Les pièges d'un schéma qui ÉVOLUE — constatés en faisant migrer un vrai progiciel
+
+Chacun a été rencontré en portant un schéma réel d'une version à la suivante, sur SQLite,
+PostgreSQL, MariaDB et MySQL. Le geste est le seul qui ait tenu sur les quatre.
+
+1. **Renommer la PROPRIÉTÉ sans renommer la colonne ne demande AUCUNE migration.** Le modificateur
+   `column` garde le nom en base : `title: { kind: "string", length: 180, column: "titre" }`. Le
+   code lit `title`, la base garde `titre`, `orm:generate` répond « rien à écrire ». Choisis-le
+   quand seul le nom vu par le code doit changer — c'est le renommage qui ne coûte rien.
+2. **Une table renommée fait apparaître des `DROP CONSTRAINT` / `DROP INDEX` puis leurs `ADD`** :
+   les noms de contraintes que le kit dérive du nom de table changent, la base garde les anciens.
+   En SQLite, la table est même RECRÉÉE (`__new_<table>`, recopie, `DROP TABLE`, `RENAME`). C'est
+   la mécanique, pas une perte, et le garde ne la signale pas. Ce qui se vérifie : la ligne
+   `renamed` du rapport, et **aucun `DROP COLUMN`** dans le fichier.
+3. **Une référence posée sur des lignes DÉJÀ remplies échoue si une ligne pointe vers rien** —
+   sur les quatre moteurs : PostgreSQL et MySQL refusent l'`ADD CONSTRAINT`, SQLite refuse la
+   validation (« référence(s) orpheline(s) », table et ligne nommées). La migration est annulée et
+   un marqueur d'échec posé. Geste : corriger d'ABORD les lignes dans une migration libre
+   (`--custom` : `UPDATE … SET fk = NULL WHERE …`), PUIS déclarer la référence ; après un échec,
+   `orm:migrate:repair` lève le marqueur une fois la cause traitée.
+4. **Retirer un champ de l'entité, c'est `DROP COLUMN`** : refusé sans `--allow-destructive`.
+   Un progiciel qui abandonne une colonne la laisse souvent en base sur les installations
+   existantes (le script de passage réel ne la supprime pas). Si ses données comptent encore,
+   garde le champ, facultatif, plutôt que de le retirer.
+5. **Une évolution se prouve sur une base PEUPLÉE, jamais vide** (§ 4 b). Une table vide ne
+   déclenche ni la recréation SQLite d'une table référencée, ni une référence orpheline : un défaut
+   de l'applicateur SQLite n'apparaissait QUE sur des lignes réelles. Une ligne par table suffit.
+
 ### 🔴 Un champ OBLIGATOIRE sur une table PEUPLÉE — ton moteur ne fait pas ce que tu crois
 
 Ajouter une colonne `NOT NULL` **sans valeur par défaut** à une table qui porte déjà des lignes n'a
@@ -218,6 +283,29 @@ Deux choses qu'il rapporte et qu'il faut lire :
 > Cela ne concerne QUE cette commande de reprise : la création des tables, leur migration et le
 > fonctionnement de l'application sont inchangés sur MariaDB.
 
+### Changer de BASE — de SQLite à PostgreSQL, MySQL ou MariaDB
+
+Une entité écrite par `create entity` est une description PORTABLE (`defineTable`) : elle suit la
+base du connecteur, **sans être réécrite**. Changer de moteur tient en quatre gestes :
+
+```bash
+npm install pg                     # ou mysql2 — le pilote de la NOUVELLE base (absent : le démarrage le nomme)
+# .env : NF_DATABASE_URL=postgres://user:secret@hote:5432/app   (le dialecte se déduit de l'URL)
+npx nodefony orm:generate --name initiale   # migration INITIALE de ce dialecte
+npx nodefony orm:migrate
+```
+
+- **Les migrations se rangent par dialecte** (`migrations/<dialecte>/`) : celles de SQLite ne
+  s'appliquent jamais ailleurs, d'où la migration initiale du nouveau moteur.
+- 🔴 **Les DONNÉES ne suivent pas.** Le schéma change de base, les lignes restent dans l'ancienne :
+  aucune commande ne les transfère — export puis import, à ta charge.
+- **Une table NATIVE ne suit pas** (`sqliteTable`, ou `create entity --dialect <moteur>`) : pointée
+  vers un autre moteur, l'application refuse de démarrer en nommant l'entité
+  (`EntityNotPortedError`). Régénère-la sans `--dialect` (`create entity <Nom> … --force`).
+- **Certains écarts appartiennent au moteur**, pas au framework : l'ordre de tri des chaînes et
+  l'égalité sans casse suivent la collation de la base, la place des `NULL` dans un tri diffère, le
+  type `vector` n'existe qu'en PostgreSQL. Le SQL natif que tu écris reste propre à ton dialecte.
+
 ## 4. Éprouver une migration — sur une base d'ESSAI, jamais sur la tienne
 
 Quand il faut **prouver** qu'une migration fait ce qu'elle annonce, la réponse n'est jamais de
@@ -320,9 +408,11 @@ Le `code` est stable — **lis-le, il désigne le geste**.
 | `NF_MIGRATE_HASH_MISMATCH`         | un fichier déjà appliqué a été modifié                                                                 | RÉTABLIR le fichier (1er geste) ; `--update-hashes` seulement si la modification était sans effet                    |
 | `NF_MIGRATE_OUT_OF_ORDER`          | une migration en attente se range avant la dernière posée                                              | renommer la nouvelle après la dernière appliquée                                                                     |
 | `NF_MIGRATE_MISSING_FILE`          | une migration appliquée n'a plus de fichier                                                            | rétablir le fichier — il fait partie de l'historique                                                                 |
-| `NF_GENERATE_DATABASE_BEHIND`      | rien à écrire, et pourtant la base ne porte pas le schéma                                              | l'historique affirme une migration jamais exécutée : `orm:migrate:repair --forget <source>/<tag>` puis `orm:migrate` |
+| `NF_GENERATE_DATABASE_BEHIND`      | rien à écrire, RIEN n'attend, et pourtant la base ne porte pas le schéma                               | l'historique affirme une migration jamais exécutée : `orm:migrate:repair --forget <source>/<tag>` puis `orm:migrate` |
 | `NF_MIGRATE_LOCK_TIMEOUT`          | un autre travail de migration tient le verrou                                                          | ATTENDRE puis rejouer — ce n'est pas une panne, et le verbe est idempotent                                           |
 | `NF_MIGRATE_DESTRUCTIVE`           | les migrations en attente SUPPRIMENT des données                                                       | lire le SQL (`--dry-run`), puis assumer avec `--allow-destructive`                                                   |
+| `NF_GENERATE_NEEDS_ANSWER`         | une colonne disparaît et une autre apparaît : renommage ou perte ?                                     | renommage → `--rename table.ancienne=nouvelle` ; vraie suppression + ajout → deux générations                        |
+| `NF_GENERATE_RENAME`               | un `--rename` mal écrit, ou que le dernier instantané ne permet pas                                    | corriger la déclaration — la table sous le nom de son entité ; rien n'a été écrit                                    |
 
 Les codes exhaustifs, avec un exemple de charge utile pour chacun :
 [`references/verdicts.md`](references/verdicts.md).

package/skills/nodefony-migrate-schema/references/verdicts.md

@@ -113,26 +113,29 @@ n'a jamais les deux — c'est le discriminant à tester.
 
 ### Refus d'usage — la demande elle-même
 
-| Code                             | Ce qui s'est passé                                                                                     | Le geste                                                                                                        |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
-| `NF_MIGRATE_UNKNOWN_CONNECTOR`   | aucun connecteur de ce nom                                                                             | le message liste ceux que l'application déclare                                                                 |
-| `NF_MIGRATE_UNKNOWN_TAG`         | `--up-to` désigne une migration inconnue                                                               | relire `sources[].pendingTags`                                                                                  |
-| `NF_MIGRATE_UNKNOWN_SOURCE`      | `--source` n'est pas déclarée par cette application                                                    | relire `sources[].name`                                                                                         |
-| `NF_MIGRATE_URL_MISMATCH`        | la variable de migration désigne une base d'un AUTRE dialecte                                          | corriger la variable, ou choisir le bon connecteur                                                              |
-| `NF_MIGRATE_NOT_CONFIGURED`      | connecteur SQL non déclaré dans la configuration                                                       | le déclarer pour pouvoir le suivre                                                                              |
-| `NF_MIGRATE_SECONDARY_CONNECTOR` | un connecteur secondaire porte le nom d'un dossier de dialecte (`sqlite`, `postgres`, `mysql`, `meta`) | renommer le connecteur dans `connectors` — un secondaire range ses migrations sous `migrations/<connecteur>/`   |
-| `NF_MIGRATE_NO_MIGRATIONS`       | ce connecteur est porté par une base qui ne se migre pas ainsi                                         | rien à migrer ici — ce n'est pas une panne                                                                      |
-| `NF_MIGRATE_NOT_DEVELOPMENT`     | geste réservé au développement, demandé ailleurs                                                       | passer par le travail de déploiement                                                                            |
-| `NF_MIGRATE_DESTRUCTIVE`         | des migrations en attente SUPPRIMENT des données                                                       | relire le fichier produit, puis assumer explicitement                                                           |
-| `NF_MIGRATE_UNAVAILABLE`         | la commande s'est arrêtée sans pouvoir nommer la cause                                                 | constater l'état (`orm:migrate:status`) avant de reprendre                                                      |
-| `NF_MIGRATE_CONFIRM_REQUIRED`    | `orm:reset` demandé hors terminal, ou en sortie machine                                                | relancer avec `--yes` si l'effacement est voulu                                                                 |
-| `NF_GENERATE_NAME`               | le nom de migration demandé n'est pas utilisable                                                       | reprendre la suggestion que le message donne                                                                    |
-| `NF_GENERATE_MISSING_ENTITY`     | une entité est enregistrée sans fichier qui la fournisse                                               | `nodefony inspect entities --json` pour la situer                                                               |
-| `NF_GENERATE_UNREADABLE_ENTITY`  | rien d'écrit, et un fichier d'entités ne s'importe pas : sa table n'est vue par personne               | corriger la cause nommée (souvent un paquet absent des dépendances), ou sortir le fichier de `nodefony/entity/` |
-| `NF_GENERATE_FRAMEWORK_TABLE`    | une entité de l'application usurpe une table du framework                                              | la renommer, ou écrire une migration libre (`--custom`)                                                         |
-| `NF_GENERATE_DESTRUCTIVE`        | la migration ÉCRITE supprime des données                                                               | relire le fichier, puis annuler (`git checkout`) ou appliquer — la mise en service a sa propre garde            |
-| `NF_GENERATE_DATABASE_BEHIND`    | rien à écrire, et pourtant la base ne porte pas le schéma                                              | `repair --forget <source>/<tag>` : l'historique affirme une migration jamais exécutée                           |
-| `NF_GENERATE_TOOL_MISSING`       | l'outil de génération n'est pas installé                                                               | l'installer en dépendance de développement                                                                      |
+| Code                             | Ce qui s'est passé                                                                                      | Le geste                                                                                                        |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `NF_MIGRATE_UNKNOWN_CONNECTOR`   | aucun connecteur de ce nom                                                                              | le message liste ceux que l'application déclare                                                                 |
+| `NF_MIGRATE_UNKNOWN_TAG`         | `--up-to` désigne une migration inconnue                                                                | relire `sources[].pendingTags`                                                                                  |
+| `NF_MIGRATE_UNKNOWN_SOURCE`      | `--source` n'est pas déclarée par cette application                                                     | relire `sources[].name`                                                                                         |
+| `NF_MIGRATE_URL_MISMATCH`        | la variable de migration désigne une base d'un AUTRE dialecte                                           | corriger la variable, ou choisir le bon connecteur                                                              |
+| `NF_MIGRATE_NOT_CONFIGURED`      | connecteur SQL non déclaré dans la configuration                                                        | le déclarer pour pouvoir le suivre                                                                              |
+| `NF_MIGRATE_SECONDARY_CONNECTOR` | un connecteur secondaire porte le nom d'un dossier de dialecte (`sqlite`, `postgres`, `mysql`, `meta`)  | renommer le connecteur dans `connectors` — un secondaire range ses migrations sous `migrations/<connecteur>/`   |
+| `NF_MIGRATE_NO_MIGRATIONS`       | ce connecteur est porté par une base qui ne se migre pas ainsi                                          | rien à migrer ici — ce n'est pas une panne                                                                      |
+| `NF_MIGRATE_NOT_DEVELOPMENT`     | geste réservé au développement, demandé ailleurs                                                        | passer par le travail de déploiement                                                                            |
+| `NF_MIGRATE_DESTRUCTIVE`         | des migrations en attente SUPPRIMENT des données                                                        | relire le fichier produit, puis assumer explicitement                                                           |
+| `NF_MIGRATE_UNAVAILABLE`         | la commande s'est arrêtée sans pouvoir nommer la cause                                                  | constater l'état (`orm:migrate:status`) avant de reprendre                                                      |
+| `NF_MIGRATE_CONFIRM_REQUIRED`    | `orm:reset` demandé hors terminal, ou en sortie machine                                                 | relancer avec `--yes` si l'effacement est voulu                                                                 |
+| `NF_GENERATE_NAME`               | le nom de migration demandé n'est pas utilisable                                                        | reprendre la suggestion que le message donne                                                                    |
+| `NF_GENERATE_MISSING_ENTITY`     | une entité est enregistrée sans fichier qui la fournisse                                                | `nodefony inspect entities --json` pour la situer                                                               |
+| `NF_GENERATE_UNREADABLE_ENTITY`  | rien d'écrit, et un fichier d'entités ne s'importe pas : sa table n'est vue par personne                | corriger la cause nommée (souvent un paquet absent des dépendances), ou sortir le fichier de `nodefony/entity/` |
+| `NF_GENERATE_FRAMEWORK_TABLE`    | une entité de l'application usurpe une table du framework                                               | la renommer, ou écrire une migration libre (`--custom`)                                                         |
+| `NF_GENERATE_DEV_MODULE_TABLE`   | un module `policy: "dev"` lie ses tables au connecteur généré : elles iraient en base de production     | lui donner un connecteur à lui, sans migration ; ou retirer sa politique `dev`                                  |
+| `NF_GENERATE_DESTRUCTIVE`        | la migration ÉCRITE supprime des données                                                                | relire le fichier, puis annuler (`git checkout`) ou appliquer — la mise en service a sa propre garde            |
+| `NF_GENERATE_DATABASE_BEHIND`    | rien à écrire, RIEN n'attend, et pourtant la base ne porte pas le schéma                                | `repair --forget <source>/<tag>` : l'historique affirme une migration jamais exécutée                           |
+| `NF_GENERATE_TOOL_MISSING`       | l'outil de génération n'est pas installé                                                                | l'installer en dépendance de développement                                                                      |
+| `NF_GENERATE_NEEDS_ANSWER`       | une colonne disparaît et une autre apparaît — l'outil demande « renommage ? », sans terminal possible   | renommage → `--rename table.ancienne=nouvelle` ; vraie suppression + ajout → deux générations                   |
+| `NF_GENERATE_RENAME`             | `--rename` mal écrit, ancien nom absent du dernier instantané, ou nouveau nom qu'aucune entité ne porte | corriger la déclaration (la table sous le nom de son entité) — rien n'a été écrit                               |
 
 ## Un contrat qui ne bougera pas
 

package/skills/nodefony-protect-route/SKILL.md

@@ -245,10 +245,10 @@ Un service partenaire, un script, un agent ne stockent aucun cookie. Le
 `nodefony/config/security.ts` généré (preset `complete`) pose **deux zones, une par sorte de
 preuve** — choisis selon ce que l'appelant détient, n'en ajoute pas une troisième :
 
-| L'appelant présente                            | Zone      | Préfixe        | Obtenir la preuve                       |
-| ---------------------------------------------- | --------- | -------------- | --------------------------------------- |
-| une **clé d'API** opaque (`nf_…`)              | `machine` | `/api/machine` | `POST /nodefony/security/api/keys`      |
-| un **jeton d'accès** (de l'app ou de Keycloak) | `partner` | `/api/partner` | `npx nodefony app:partner:call` le fait |
+| L'appelant présente                  | Zone      | Préfixe        | Obtenir la preuve                  |
+| ------------------------------------ | --------- | -------------- | ---------------------------------- |
+| une **clé d'API** opaque (`nf_…`)    | `machine` | `/api/machine` | `POST /nodefony/security/api/keys` |
+| un **jeton d'accès** signé par l'app | `service` | `/api/service` | émis par l'app (voir la démo)      |
 
 ### Clé d'API : la zone `machine`
 
@@ -275,27 +275,30 @@ qui ne stocke pas de cookie ne doit rien recevoir qu'il faille stocker.**
 
 Les clés s'émettent par `POST /nodefony/security/api/keys`.
 
-### Jeton d'accès : la zone `partner`, et la commande qui l'éprouve
+### Jeton d'accès : la zone `service`
 
-La zone accepte un jeton signé par l'application (`jwt`) **et** un jeton de Keycloak
-(`external-jwt`) ; les deux s'aiguillent sur l'émetteur, leur ordre ne décide de rien. Une route
-qui tombe sous `/api/partner` est protégée sans rien ajouter. L'exemple qui marche est déjà dans
-l'application — **lis-le avant d'écrire un appelant** :
-
-```bash
-npx nodefony app:partner:call                     # jeton signé par l'app pour `admin` (--as <compte>)
-npx nodefony app:partner:call --issuer keycloak   # client <app>-machine, flux client_credentials
+```ts
+service: {
+  pattern: "^/api/service",
+  authenticators: ["jwt"], // jeton signé par CETTE application
+  stateless: true,
+}
 ```
 
-Source : `nodefony/command/PartnerCallCommand.ts` (la commande) et
-`nodefony/controllers/PartnerController.ts` (`GET /api/partner/whoami`, qui rend l'identité ET
-l'émetteur). Un jeton Keycloak s'obtient par `requestClientCredentialsToken` de
-`@nodefony/security` — découverte du point de jeton comprise —, jamais par un `fetch` recopié.
+Une route qui tombe sous `/api/service` est protégée sans rien ajouter. L'application générée
+n'y met AUCUN controller : l'exemple complet — émission du jeton, appel, et la variante Keycloak
+(`client_credentials`) — vit dans la démo, qu'on copie dans l'application pour la lire.
+
+**Accepter aussi les jetons d'un fournisseur** (Keycloak) : ajouter `"external-jwt"` à la zone ;
+`jwt` et `external-jwt` s'aiguillent sur l'émetteur du jeton, leur ordre ne décide de rien. Un jeton
+Keycloak s'obtient par `requestClientCredentialsToken` de `@nodefony/security` — découverte du point
+de jeton comprise —, jamais par un `fetch` recopié.
 
 🔴 **L'audience vit en UN endroit.** Un jeton n'ouvre que la zone dont il porte la ressource
-(RFC 8707). `partnerResource(ctx.env)` est lue par la zone (`resource`), par `jwt.audiences` et par
-la commande. Une ressource recopiée à la main finit par différer, et le seul symptôme est un refus
-sans explication. Ouvrir une AUTRE ressource à des jetons, c'est trois gestes, pas un :
+(RFC 8707). Écris-la UNE fois (une fonction de `nodefony/config/security.ts`, sur le modèle de
+`publicBaseUrl`), lue par la zone (`resource`) et par `jwt.audiences`. Une ressource recopiée à la
+main finit par différer, et le seul symptôme est un refus sans explication. Ouvrir une ressource
+à des jetons, c'est trois gestes, pas un :
 
 | Oublié                                    | Symptôme                                                      |
 | ----------------------------------------- | ------------------------------------------------------------- |
@@ -303,19 +306,11 @@ sans explication. Ouvrir une AUTRE ressource à des jetons, c'est trois gestes,
 | `security:keycloak:realm --write` relancé | **401** du jeton Keycloak : le realm n'inscrit pas l'audience |
 | la `resource` sur la zone                 | l'application **refuse de démarrer** en nommant la zone       |
 
-🔴 **`subjectPolicy: "ephemeral"` s'écrit SUR LA ZONE, jamais dans `resourceServer`.** Le client
+🔴 **`subjectPolicy: "ephemeral"` s'écrit SUR LA ZONE, jamais dans `resourceServer`.** Un client
 machine de Keycloak n'a pas de compte ici : `ephemeral` l'accepte le temps de la requête, avec les
-seuls `ephemeralRoles` de la zone (`ROLE_PARTNER`). Posé dans `resourceServer.subjectPolicy`
-(global), il ferait accepter un appelant sans compte par **toutes** les zones `external-jwt`. Et
-un rôle fort dans `ephemeralRoles` est accordé à **quiconque** détient un jeton valide du realm.
-
-`whoami` n'exige pas `ROLE_PARTNER` — un compte de l'app ne l'a pas. Pour réserver une action aux
-partenaires : `@IsGranted("ROLE_PARTNER")`.
-
-**Prouver** : `--issuer nodefony` rend 200 sans Keycloak ; `--issuer keycloak` rend 200 avec le
-profil `keycloak` du compose allumé ; et le MÊME jeton machine est refusé (401) sur une zone qui
-garde `subjectPolicy` par défaut (`require`). Chaque échec de la commande sort en code 1 avec le
-geste qui répare — lis-le avant de chercher ailleurs.
+seuls `ephemeralRoles` de la zone. Posé dans `resourceServer.subjectPolicy` (global), il ferait
+accepter un appelant sans compte par **toutes** les zones `external-jwt`. Et un rôle fort dans
+`ephemeralRoles` est accordé à **quiconque** détient un jeton valide du realm.
 
 ## Les gestes qui affaiblissent en silence