Epic: Release readiness — end-to-end clone-and-run for external users

[jsboige]

Vision

Quand un utilisateur tiers (contributeur, imprimeur, partenaire) clone le repo et lance dotnet run -c Release, le pipeline doit fonctionner sans configuration locale :

• CSV tirés depuis raw.githubusercontent.com/.../master/Cards/...
• CardPen depuis GitHub Pages
• Templates JSON depuis GitHub raw
• Output qualité imprimeur (PNG lossless + CMYK + 300 DPI)

Le développeur (dotnet run Debug) garde son expérience actuelle : fichiers locaux, cache .harvest.json, output preview-friendly (JPEG Q=85, no CMYK pour Print&Play) pour faciliter la review dans Edge PDFium.

Pattern de référence

Le mécanisme est déjà en place dans AssetConverterConfig.cs:363-376 :

```csharp
public bool UseDebugParams => (isInDebugMode || ForceDebugParams) && !ForceReleaseParams;
public bool UseReleaseParams => (!isInDebugMode && !ForceDebugParams) || ForceReleaseParams;

#if DEBUG
bool isInDebugMode = true;
#else
bool isInDebugMode = false;
#endif
```

Avec ForceDebugParams / ForceReleaseParams overridables via JSON pour les cas spéciaux (CI, livraison depuis Debug build).

Précédents corrects (10+ endroits utilisant déjà ce pattern) :

• CardSetInfo.GetJsonFilePath() — JsonFilePathDebug vs JsonFilePathRelease
• HarvestManager — CSV dataSet.GetContent(AssetConverterConfig.UseDebugParams) (filesystem vs GitHub raw)
• MindMapDocumentConfig.GenerateHtmlSvgWrappers() — TemplatePathDebug vs TemplatePathRelease
• DatasetUpdaterConfig — mêmes patterns

Anti-patterns à corriger (découverts session 16 mai) :

• PR fix(printandplay): reduce PDF size — JPEG Q=85 + skip CMYK #277 a hardcodé ConvertToCmyk = false sur 4 Print&Play + JPEG Q=85 dans PdfManager au lieu d'utiliser UseReleaseParams
• WebBasedGeneratorConfig.ReleaseCardpenUrl pointe vers une 404 (workflow Pages a changé sans que l'URL soit mise à jour)

Roadmap (par ordre de priorité)

• Task 1 — Fix bug latent : ReleaseCardpenUrl 404 → fix(config): ReleaseCardpenUrl points to 404 — Pages workflow URL mismatch #279 (P0, 1h)
  URL hardcodée pointe vers /Argumentum/Generation/CardPen/index.html mais workflow upload path: 'Generation/CardPen' qui devient /Argumentum/. Fix soit URL côté C#, soit restructurer workflow Pages.

• Task 2 — Refactor PR fix(printandplay): reduce PDF size — JPEG Q=85 + skip CMYK #277 → UseDebugParams pattern → refactor(pdf): respect UseDebugParams pattern in PR #277 (CMYK + JPEG quality) #280 (P1, 2-3h)
  Convention (a) per CardSet : ConvertToCmykDebug / ConvertToCmykRelease + helper. Convention (b) au call site pour JPEG quality. Default Debug = preview (état actuel post-PR fix(printandplay): reduce PDF size — JPEG Q=85 + skip CMYK #277), Default Release = qualité imprimeur.

• Task 3 — Audit hardcoded paths/URLs/quality → audit(config): hardcoded paths, URLs, and quality constants — Release readiness review #283 (closed by PR fix(config): remove hardcoded Debug paths — thumbnails + Freeplane/FreeMind (#283) #284) (P2, 3-4h)
  Grep exhaustif des constantes qui devraient varier entre Debug/Release et n'utilisent pas le pattern. Examples potentiels : DPI, OWL output paths, mindmap SVG output paths, harvest cache location, asset paths dans CardPen templates. Liste + propositions de refactor ou justification "pas pertinent".

• Task 4 — CI healthcheck Pages URLs live (P2, 1h)
  Petit workflow pages-url-healthcheck.yml : curl -I sur les URLs Release configurées dans WebBasedGeneratorConfig + autres Release* paths. Fail si 404. Aurait attrapé le bug ReleaseCardpenUrl.

• Task 5 — CI matrix Debug + Release (P2, 1-2h)
  Actuellement CI build/test seulement Debug (à confirmer). Ajouter dotnet build -c Release + dotnet test -c Release au workflow CI. Test runtime du pipeline Release entier hors scope (trop coûteux).

• Task 6 — Doc CLAUDE.md : Debug vs Release semantics (P3, 30min)
  Section dédiée documentant UseDebugParams / UseReleaseParams / ForceDebugParams / ForceReleaseParams. Quand utiliser quoi. Liste à jour des dimensions Debug/Release (post-audit Task 3).

• Task 7 — README Quickstart end user (P3, 1-2h)
  Section "How to generate the print-ready PDFs from source". Commande : dotnet run -c Release. Ce que ça produit, où c'est, comment l'envoyer à l'imprimeur.

Dépendances

• Bloque release: Publish new GitHub release with updated game materials #134 (GitHub Release) — packaging dépend d'un build Release fonctionnel
• Bloque feat(ontology): Publish OWL ontology to public endpoint #133 (OWL publication) — même mécanisme à respecter
• Bloque ops(deploy): Production deployment — database migration and go-live #132 (Production deployment) — même mécanisme à respecter

Convention sprint

• 1 task = 1 PR (sauf 2+3 qui peuvent être combinés)
• Preuve before/after dans body PR
• Tests verts requis
• Convention `1 PR = 1 issue` respectée

🤖 Generated with Claude Code