Docs audit — 2026-08-07 (PRs #2693–#2697)

[SebConejo]

Audited: mnfst/manifest PRs #2693 to #2697 (4 merged PRs — #2693, #2694, #2696, #2697), against the docs at commit 0160c6e.

Clean this run: the "Autofix" spelling is consistent in the docs (the only auto-fix left is a deliberate SEO keyword on autofix.mdx); the two Gemini Code Assist models the platform just removed (gemini-3.1-pro-preview, gemini-3-flash-preview) were never listed in the docs, and the subscriptions page names Gemini generically, so nothing there is stale; and no internal-tool codename leaked into the docs beyond the one flagged below.

Most of this run comes from PR #2693, which made request recordings durable across every deployment template (S3 buckets or persistent volumes). Several deploy guides now describe the old ephemeral behaviour and send users through steps that are wrong or incomplete.

Findings

1 · [WRONG/MISSING-CASE] Le guide Heroku annonce une seule valeur à saisir, alors que le déploiement en réclame désormais quatre (les identifiants S3 des logs)

Un utilisateur qui suit la page prépare seulement BETTER_AUTH_URL, puis reste bloqué sur le formulaire Heroku qui exige désormais quatre valeurs S3 en plus (bucket, région, deux clés) — ou laisse les champs vides et perd silencieusement ses logs.

• Option 1 — corriger le "one required value", ajouter un prérequis (bucket S3 privé + clé limitée) et une étape pour renseigner bucket/région/clés. (recommandée)
• Option 2 — corriger seulement le "one required value" et renvoyer vers la section S3 de request-logs pour le bucket.

Preuves (pour l'agent)

• Doc deploy/heroku.mdx:22 (carte) : « …generated secrets, and one required BETTER_AUTH_URL value. » et :29 : « Heroku still requires one manual value: BETTER_AUTH_URL. » Les étapes 40-48 ne mentionnent aucun champ S3.
• Plateforme (PR #2693) app.json : REQUEST_RECORDING_S3_BUCKET (:39-42), _S3_REGION (:50-52), _S3_ACCESS_KEY_ID (:53-55), _S3_SECRET_ACCESS_KEY (:56-58) tous "required": true ; REQUEST_RECORDING_STORAGE = s3. Les dynos Heroku ont un FS éphémère → les logs ont besoin d'un S3 externe.
• À vérifier avant PR : confirmer dans app.json si BETTER_AUTH_URL reste marqué required (le tech-writer l'a conservé par prudence).

Wording proposé (option 1) — carte :22 : « Deploy-button guide with Heroku Postgres, generated secrets, and required values for the app URL and S3-compatible recording storage. » ; :29 : « Heroku asks for a few values before it can deploy. Set BETTER_AUTH_URL to the public URL for the app name you choose. Heroku dynos have an ephemeral filesystem, so request logs write to external S3-compatible storage rather than local disk: set the bucket, region, and access key for that storage too. » ; prérequis à ajouter : « - A private S3-compatible bucket and an access key limited to it, for request logs. » ; étape à ajouter : renseigner REQUEST_RECORDING_S3_BUCKET, _S3_REGION, _S3_ACCESS_KEY_ID, _S3_SECRET_ACCESS_KEY.

2 · [MISSING-CASE] Le guide DigitalOcean ne dit nulle part de créer un Space et d'en fournir les identifiants, alors que le template les exige

Le template code STORAGE=s3 mais laisse les identifiants du bucket vides : sans un Space privé et sa clé renseignés, l'enregistrement des logs n'a pas de backend et se désactive en silence.

• Option 1 — ajouter un prérequis (Space DigitalOcean privé + clés) et une étape pour renseigner les secrets REQUEST_RECORDING_S3_*. (recommandée)
• Option 2 — ajouter une puce dans Notes qui renvoie à la configuration S3 de request-logs si les étapes restent minimales.

Preuves (pour l'agent)

• Doc deploy/digitalocean.mdx : la liste de config s'arrête aux étapes 47-49 (« Paste the other value into MANIFEST_ENCRYPTION_KEY. … Create the app. ») ; aucune mention de S3/Spaces sur la page.
• Plateforme (PR #2693) .do/deploy.template.yaml:41-43 (REQUEST_RECORDING_STORAGE = s3), :44-58 (REQUEST_RECORDING_S3_BUCKET/_ENDPOINT/_ACCESS_KEY_ID/_SECRET_ACCESS_KEY en SECRET fournis par l'opérateur, région par défaut us-east-1). App Platform n'a pas de volumes.

Wording proposé (option 1) — prérequis : « - A private DigitalOcean Space and an access key pair for it, for request logs. » ; nouvelle étape entre 5 et 6 : renseigner REQUEST_RECORDING_S3_BUCKET, _S3_ENDPOINT, _S3_ACCESS_KEY_ID, _S3_SECRET_ACCESS_KEY (région par défaut us-east-1) ; puce Notes : « App Platform has no persistent volumes, so request logs write to your DigitalOcean Space over S3. »

3 · [MISSING-CASE] Le lien de déploiement Koyeb de la doc est périmé : il déploie sans stockage S3 et perd les logs

Un utilisateur qui clique sur le lien de la page déploie avec STORAGE non défini (donc disque éphémère, logs perdus) — exactement le résultat que la note de la page décrit sans jamais le corriger.

• Option 1 — mettre à jour la carte + le lien de déploiement vers l'URL actuelle (avec REQUEST_RECORDING_STORAGE=s3 et les placeholders S3), ajouter un prérequis bucket et une étape pour remplacer les placeholders. (recommandée)
• Option 2 — garder l'ancien lien mais ajouter prérequis + étapes explicites pour créer un bucket et poser les variables S3.

Preuves (pour l'agent)

• Doc deploy/koyeb.mdx:54 (et carte :19) : l'URL de déploiement se termine sur …&env%5BDB_POOL_MAX%5D=8&env%5BAUTH_DB_POOL_MAX%5D=4, sans aucun REQUEST_RECORDING_* ; prérequis (30-33) = compte, Postgres, deux secrets ; seule la note :76 dit « needs S3-compatible storage » sans rien configurer.
• Plateforme (PR #2693) deploy/koyeb/TUTORIAL.md:3 (« you must create PostgreSQL and a private S3-compatible recording bucket separately and replace the placeholder secrets ») ; :34 — l'URL canonique inclut désormais REQUEST_RECORDING_STORAGE=s3 + les placeholders REQUEST_RECORDING_S3_*.
• Mécanique pour la PR : le lien encodé (carte :19, étape :54) doit être régénéré à partir de l'URL canonique. Confirmer la liste exacte des paramètres S3 avant merge.

Wording proposé (option 1) — prérequis : « - A private S3-compatible bucket and an access key for it. Koyeb instances have no persistent disk, so request logs need external storage. » ; nouvelle étape après l'étape 4 : « Replace the REQUEST_RECORDING_S3_* placeholder values with your bucket, region, endpoint, and access keys. »

4 · [WRONG] La page Render dit que les logs sont perdus et qu'il faut brancher du S3, alors que le template monte désormais un disque persistant (offre payante)

La doc envoie l'utilisateur configurer du S3 pour ne pas perdre ses logs, mais le Blueprint monte déjà un disque persistant de 1 Go qui les conserve ; et le service tourne maintenant sur l'offre payante Starter (plus de mise en veille), donc la note "plan gratuit / première requête lente" induit en erreur.

• Option 1 — réécrire la note (disque persistant 1 Go sur /data/request-recordings, logs conservés entre redéploiements, mono-instance, passer au S3 avant de scaler horizontalement) et retirer la ligne "free plan / sleep". (recommandée)
• Option 2 — corriger seulement la ligne sur les logs, garder la note d'offre (laisse une petite inexactitude).

Preuves (pour l'agent)

• Doc deploy/render.mdx:66 : « If the instance is sleeping on a free plan, the first request can take longer. » ; :67 : « Message recording writes to local disk by default, which Render discards on redeploy. Point it at S3-compatible storage to keep recordings. »
• Plateforme (PR #2693) render.yaml:7 (plan: starter), :11-13 (disk: name: manifest-recordings, mountPath: /data/request-recordings, sizeGB: 1), :33-36 (REQUEST_RECORDING_STORAGE: filesystem).

Wording proposé (option 1) : « The Blueprint mounts a 1 GB persistent disk manifest-recordings at /data/request-recordings and sets REQUEST_RECORDING_STORAGE=filesystem, so request logs survive redeploys. This disk is single-instance. Point recording at S3-compatible storage before you scale to more than one instance. » (et supprimer la ligne 66).

5 · [WRONG] La page Fly demande d'attacher un volume ou de brancher du S3, alors que le script provisionne automatiquement un bucket Tigris

L'utilisateur croit ses logs éphémères et attache un Fly Volume à la main — étape inutile qui entre en conflit avec le backend S3 que le script a déjà configuré ; en réalité les logs persistent tout seuls et survivent au scaling horizontal.

• Option 1 — réécrire la note : le script crée un bucket Tigris privé et configure le S3 automatiquement, rien à attacher. (recommandée)
• Option 2 — une ligne courte : « le stockage est géré automatiquement via Tigris », en retirant l'instruction de volume.

Preuves (pour l'agent)

• Doc deploy/fly.mdx:75 : « Message recording writes to the Machine's local disk by default, which Fly replaces on each deploy. Attach a Fly Volume at /data/request-recordings, or point it at S3-compatible storage. »
• Plateforme (PR #2693) deploy/fly/fly.toml:24-27 (REQUEST_RECORDING_STORAGE = "s3", endpoint Tigris https://fly.storage.tigris.dev) ; deploy/fly/TUTORIAL.md:3,35 — deploy.sh crée un bucket Tigris privé et stage les secrets AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY.

Wording proposé (option 1) : « The deploy script creates a private Tigris bucket, stores its credentials as Fly secrets, and sets REQUEST_RECORDING_STORAGE=s3 with the Tigris endpoint. Request logs persist across deploys and across scaled Machines. Nothing to attach manually. »

6 · [WRONG] La page des logs affirme que Render, Fly, Heroku et Koyeb ont tous un FS éphémère à brancher soi-même sur du S3 — ce n'est plus vrai

L'affirmation groupée est maintenant fausse pour Render (disque persistant) et Fly (Tigris automatique), et trompeuse pour Heroku/Koyeb/DigitalOcean (le S3 se configure pendant le setup du template, pas après coup).

• Option 1 — remplacer la liste par la vérité par plateforme : Render persiste sur disque monté ; Fly/AWS/GCP provisionnent l'object storage automatiquement ; Heroku/Koyeb/DigitalOcean collectent les réglages S3 au setup du template. (recommandée)
• Option 2 — adoucir en « certains hébergeurs managés ont un disque éphémère ; les templates Manifest gèrent la durabilité — voir chaque guide de déploiement », en supprimant la liste.

Preuves (pour l'agent)

• Doc request-logs.mdx:118 : « Railway, Render, Fly, Heroku, and Koyeb all give you an ephemeral filesystem, so local recordings there are wiped on every redeploy and every container restart. Point those deploys at S3-compatible storage, or accept that recordings only survive until the next deploy. »
• Plateforme (PR #2693) render.yaml:11-13,33-36 (disque persistant, filesystem) ; deploy/fly/fly.toml:24-27 + deploy/fly/TUTORIAL.md:3 (Tigris auto) ; app.json Heroku et deploy/koyeb/TUTORIAL.md:34 (S3 collecté au setup).
• Railway est non vérifié : le README de la plateforme prétend un stockage S3-compatible, mais railway.toml n'a ni REQUEST_RECORDING_* ni volume ni S3. À ne pas sur-affirmer (question à Seb hors issue).

Wording proposé (option 1) : « The one-click templates set this up for you. Render mounts a persistent disk. Fly, AWS, and Google Cloud provision object storage during deploy. Heroku, Koyeb, and DigitalOcean collect your bucket and keys as part of template setup. On any other platform with an ephemeral filesystem, point recording at S3-compatible storage yourself, or recordings only survive until the next deploy. » (Railway retiré volontairement.)

7 · [MISSING-CASE] Le déploiement manuel Easypanel oublie le volume de logs que le template monte

Un utilisateur qui suit la voie manuelle stocke ses logs sur le FS éphémère du conteneur, sans volume persistant, et les perd au redémarrage — alors que le template officiel les conserve.

• Option 1 — ajouter REQUEST_RECORDING_STORAGE=filesystem + REQUEST_RECORDING_FILESYSTEM_PATH=/data/request-recordings au bloc env manuel et une étape pour ajouter un volume d'app recordings monté sur /data/request-recordings. (recommandée)
• Option 2 — renvoyer les utilisateurs manuels vers l'onglet S3 de request-logs s'ils ne peuvent pas ajouter de volume.

Preuves (pour l'agent)

• Doc deploy/easypanel.mdx:55-68 : le bloc env manuel liste DB_POOL_MAX=10 / AUTH_DB_POOL_MAX=5 mais aucun REQUEST_RECORDING_* ; la prose « ## Manual deploy » (49-51) ne parle jamais d'un volume de logs.
• Plateforme (PR #2693) deploy/easypanel/TUTORIAL.md:62-63 (REQUEST_RECORDING_STORAGE=filesystem, REQUEST_RECORDING_FILESYSTEM_PATH=/data/request-recordings), :76 (« Add an app volume named recordings, mount it at /data/request-recordings ») ; deploy/easypanel/template/index.ts:41-49.

Wording proposé (option 1) : ajouter au bloc env les deux lignes ci-dessus, et à la prose : « Add an app volume named recordings mounted at /data/request-recordings so request logs survive restarts and redeploys. This volume is single-instance; move to S3-compatible storage before running more than one replica. »

8 · [WRONG] La référence des variables d'environnement documente des tailles de pool par défaut périmées (30/10 au lieu de 10/5)

Un opérateur qui dimensionne le max_connections de Postgres d'après la doc sur-provisionne de 3x/2x, et toute personne qui se fie aux valeurs par défaut lit un chiffre faux.

• Option 1 — passer les deux valeurs par défaut à 10 et 5 (conforme au code, une ligne). (recommandée)
• Option 2 — idem + une demi-phrase indiquant qu'un override invalide retombe sur ces valeurs par défaut.

Preuves (pour l'agent)

• Doc reference/environment-variables.mdx:44 : « DB_POOL_MAX | 30 | Max PostgreSQL connections in the main pool » ; :45 : « AUTH_DB_POOL_MAX | 10 | … ».
• Plateforme (PR #2697) packages/backend/src/config/app.config.ts:38 (… ?? 10), packages/backend/src/auth/auth.instance.ts:33 (… ?? 5). Les overrides valides gagnent toujours.

9 · [MISSING-CASE] Le récap AWS des ressources créées oublie le bucket S3 de logs, conservé après suppression de la stack

Le template crée aussi un bucket S3 pour les logs ; comme il est conservé par conception, supprimer la stack CloudFormation laisse le bucket (contenus + coût de stockage) derrière, sans que la doc le signale.

• Option 1 — ajouter une ligne Notes/teardown indiquant qu'un bucket S3 de logs conservé est provisionné et doit être supprimé à la main. (recommandée)
• Option 2 — laisser tel quel (les logs marchent tout seuls), et accepter le petit angle mort au teardown.

Preuves (pour l'agent)

• Doc deploy/aws.mdx:61-65 : « The CloudFormation template generates: - DATABASE_URL. - BETTER_AUTH_SECRET. - MANIFEST_ENCRYPTION_KEY. » (pas de bucket de logs, pas de section teardown).
• Plateforme (PR #2693) deploy/aws/manifest.yaml:364 (IAM sur RecordingBucket), :421-425 (REQUEST_RECORDING_STORAGE/_S3_BUCKET/_S3_REGION auto-posées) ; bucket DeletionPolicy: Retain.

Wording proposé (option 1) : « The template creates an S3 bucket for request logs. It is retained by design, so deleting the CloudFormation stack leaves the bucket in place. Delete it by hand when you tear the deployment down. »

10 · [INTERNAL-LEAK] La référence des variables d'environnement nomme un outil interne et son hostname interne, sur deux lignes

Deux lignes de reference/environment-variables.mdx (une variable et l'aside d'une autre) exposent le nom de code d'un outil interne et son hostname interne, dont un utilisateur n'a jamais besoin — c'est un ban AUDIENCE #1. (Volontairement non recopiés ici : dépôt public.)

• Option 1 (intérim) — supprimer la phrase qui nomme l'outil interne et son hostname, et reformuler l'aside de l'autre ligne pour décrire seulement « des origines navigateur supplémentaires autorisées à joindre le gateway ». Ne masque PAS tout : le nom de la variable porte lui-même le nom de code.
• Option 2 (propre, recommandée) — demander à la plateforme de renommer la variable en un nom neutre (ex. EXTRA_CORS_ORIGINS), puis corriger la doc — seul moyen d'enlever complètement le nom de code, une variable opérateur requise devant être documentée par son nom.
• Option 3 — laisser tel quel : rejetée (violation d'un ban permanent).

Preuves (pour l'agent)

• Doc reference/environment-variables.mdx : ligne 36 (la variable *_CORS_ORIGINS dont le nom porte le code, et son aside qui cite l'hostname interne), et ligne 32 (aside en fin de ligne CORS_ORIGIN : « …plus <var interne> »).
• Plateforme : le nom de code correspond à un outil interne (gateway tester hébergé), confirmé côté code ; la variable existe bien dans le produit (packages/backend/src/main.ts:96, cors-csp-config.ts:16) et reste un vrai bouton opérateur, d'où la nuance rename-vs-suppression.
• Rappel harness : ne jamais écrire le nom de code dans l'issue ni dans les fichiers de ce dépôt public.

---

Répondre avec le numéro du finding et l'option choisie
(ex: "3 → option 2", ou "3: autre idée, discutons").
Les PRs se font ensuite manuellement avec l'agent, jamais par le harness.
Findings rejetés = répondre "N → reject" : ils ne seront plus re-signalés.