feat: harden CV pipeline with ATS lint, page-fit, and self-check

- lint_cv.py: hard-gate deterministic ATS pre-flight checks (contact
  fields, experience/education completeness) before rendering
- generate_pdf(): enforce the 1-page constraint by checking WeasyPrint's
  real page count, retrying once with a compact CSS override, and
  warning on stderr if still overflowing instead of shipping silently
- fit_to_one_page(): given optional content (certifications/projects/
  hobbies) ranked least-to-most relevant, automatically drop and
  restore it to fit 1 page without manual trial and error
- screenshot_cv() + --screenshot: render a PNG self-check next to the
  PDF via Playwright, so the tailoring agent can visually QA layout
- cv-fr/cv-en templates: hide Experience/Skills/Education sections
  when empty, consistent with the other optional sections
- modes/generate-cv.md: document the real Python-based tailoring
  workflow (CLI alone never exposed summary/bullet/droppable overrides)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: St4r4x

CHANGELOG.md

@@ -9,8 +9,15 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 - `frontend/components/candidatures/candidatures-client.tsx` — "Masquer les offres abandonnées" checkbox above the offer list, checked by default; hides `Abandonnée` offers when no explicit status filter is set (selecting "Abandonnée" in the status dropdown still shows them)
+- `scripts/lint_cv.py` — deterministic ATS pre-flight lint (`lint_cv_context()`): flags missing contact fields (name/email/phone) and experience/education entries missing title/company/period or degree/school/period. Called as a hard gate in `generate_pdf()` before rendering — raises `ValueError` listing every issue instead of silently shipping a broken CV
+- `scripts/generate_pdf.py` — `screenshot_cv()` + `--screenshot` CLI flag: renders the CV HTML (CSS inlined, no file/base-url needed) to a full-page A4 PNG via Playwright, saved next to the PDF, so `modes/generate-cv.md`'s LLM agent can visually self-check layout before finalizing (long names wrapping, stack-tags overflowing, etc.)
+- `scripts/generate_pdf.py` — `fit_to_one_page()` + `generate_pdf(..., droppable=...)`: given optional content (certifications/projects/hobbies) ranked least-to-most relevant to the target offer, automatically drops everything droppable, then restores it back most-relevant-first as far as 1 page allows. Industrializes the manual trim-then-refill process used to fit a real CV (8 certs, 3 projects, hobbies) onto 1 page for the TREKEA offer test — verified to reproduce the same hand-tuned result automatically
 
 ### Changed
+- `scripts/generate_pdf.py` — `generate_pdf()` now renders via WeasyPrint's `HTML(...).render()` first and checks the resulting page count; a CV that overflows to 2+ pages is automatically re-rendered once with a compact CSS override (tighter margins/line-height/spacing) before falling back to a stderr warning if still over 1 page. Previously nothing enforced the "must stay 1 page" constraint — WeasyPrint would silently write a multi-page PDF
+- `scripts/generate_pdf.py`'s `build_cv_context()` now drops skill categories with an empty skill list, so post-tailoring content never leaves an empty category behind
+- `templates/cv-fr/cv.html.j2`, `templates/cv-en/cv.html.j2` — Experience, Skills, and Education sections are now wrapped in `{% if %}` guards, consistent with Summary/Certifications/Projects/Hobbies, instead of always rendering a section header even when empty
+- `modes/generate-cv.md` — step 4 now passes `--screenshot` and step 5 has the agent read the generated PNG before confirming; documents the new lint/page-count failure modes
 - `frontend/components/theme-toggle.tsx` — theme toggle button now shows a `Moon`/`Sun` icon (lucide-react) instead of "Mode sombre"/"Mode clair" text, with an `aria-label` carrying the same text for accessibility
 - `frontend/package.json` — bumped `next`/`eslint-config-next` `16.2.10` → `16.3.0`, clearing 9 GHSA advisories against `16.2.10` (middleware/proxy bypass, Server Actions DoS/SSRF, cache confusion, image-optimization DoS, internal endpoint disclosure); `npm audit` no longer lists `next` at all
 - `requirements.txt` — bumped `cryptography` `42.0.8` → `50.0.0`, `PyJWT` `2.9.0` → `2.13.0`, `mistune` `3.0.2` → `3.3.4`, `jinja2` `3.1.4` → `3.1.6`, `python-multipart` `0.0.29` → `0.0.32`, `python-dotenv` `1.0.1` → `1.2.2`, `weasyprint` `62.3.0` → `69.0` (dropped the `pydyf==0.11.0` compatibility pin now that weasyprint 69 pulls a compatible `pydyf` on its own — resolved to `0.12.1`); `pip-audit -r requirements.txt` no longer lists any of these. All three PDF generators (`generate_pdf.py`/`generate_cover_letter.py`/`generate_prep_sheet.py`) smoke-tested end-to-end (real WeasyPrint render, not mocked) to confirm the weasyprint/pydyf/jinja2 bump didn't break PDF output. `fastapi` `0.115.12` → `0.141.1` and an explicit `starlette==1.6.0` pin (previously an unpinned transitive of `fastapi`) close the remaining advisories; `pip-audit -r requirements.txt` now reports zero findings. `pytest`/`ruff` re-verified clean after the bump (one new dev-only warning: `starlette.testclient` deprecates `httpx` in favor of `httpx2`, not acted on here)

README.md

@@ -266,7 +266,8 @@ scripts/
   dedup.py                  Accent-insensitive deduplication
   description_parser.py     Parse raw job description text into structured fields per portal
   daily_report.py           Markdown digest generation
-  generate_pdf.py           CV PDF generation (WeasyPrint + Jinja2, FR/EN)
+  generate_pdf.py           CV PDF generation (WeasyPrint + Jinja2, FR/EN); --screenshot renders a PNG self-check alongside the PDF
+  lint_cv.py                 Deterministic ATS pre-flight lint, called by generate_pdf.py before rendering
   generate_cover_letter.py  Cover letter PDF generation
   generate_prep_sheet.py    Interview prep sheet PDF generation
   models.py                 Shared data models

modes/generate-cv.md

@@ -18,21 +18,40 @@ Generate a tailored CV PDF for a specific job offer. Called from Claude Code CLI
    - `highlighted_skills`: list of skills from profile.md that match the offer keywords exactly
    - `summary`: rewrite the 2-sentence summary to mirror the offer's language (role title, key domain)
    - `experience.bullets`: for the NeuralVision AI/ML Engineer role, reorder bullets to lead with the most relevant ones for this offer. Do NOT invent new bullets.
-4. Run the PDF generation script:
+4. Summary rewrite and bullet reordering aren't exposed as CLI flags — call the Python functions directly instead of the bare CLI:
 
-```bash
-python scripts/generate_pdf.py \
-  --offer "<company-slug>" \
-  --date "<YYYY-MM-DD>" \
-  --highlighted <skill1> <skill2> ...
+```python
+import sys
+sys.path.insert(0, ".")
+from scripts.generate_pdf import default_context, generate_pdf
+
+ctx = default_context(lang="fr")  # or "en"
+ctx["summary"] = "..."  # tailored summary
+ctx["experience"][0]["bullets"] = [...]  # reordered, never invented
+ctx["highlighted_skills"] = ["<skill1>", "<skill2>", ...]
+
+path = generate_pdf(ctx, offer="<company-slug>", output_date="<YYYY-MM-DD>", lang="fr", screenshot=True)
+```
+
+5. If stderr warns the CV still exceeds 1 page after the automatic compact-layout retry, rank the optional content (certifications, projects, hobbies) least-to-most relevant to this offer and pass it as `droppable` to `generate_pdf()` — it trims from the least relevant end and restores as much as still fits 1 page, before falling back to the compact-CSS retry:
+
+```python
+droppable = [
+    ("certification", "<least relevant cert name>"),
+    ("certification", "<next least relevant cert name>"),
+    ("project", "<least relevant project name>"),
+    ("hobbies", None),  # dropped as a whole unit, tried last (most relevant to keep)
+]
+path = generate_pdf(ctx, offer="<slug>", output_date="<date>", lang="fr", screenshot=True, droppable=droppable)
 ```
 
-5. Confirm the PDF was created at `output/cv-<company-slug>-<date>.pdf`
+6. Read the generated `output/<slug>-<date>/cv-<slug>-<date>.png` screenshot (View/Read tool) and check for: text overflowing 1 page, long company/skill names wrapping badly, stack-tags spilling onto a new line. Re-tailor content and re-run if something looks broken.
+7. Confirm the PDF was created at `output/<slug>-<date>/cv-<slug>-<date>.pdf`
 
 ## Output
 
-Print: `CV generated: output/cv-<slug>-<date>.pdf`
-Remind the user to open and visually verify the PDF before sending.
+Print: `CV generated: output/<slug>-<date>/cv-<slug>-<date>.pdf`
+The script raises on ATS pre-flight lint failures (missing contact fields, missing experience/education fields) and warns on stderr if the CV still exceeds 1 page after the automatic compact-layout retry — do not report success if that warning appears without fixing the content first.
 
 ## Constraints
 

scripts/generate_pdf.py

@@ -3,13 +3,15 @@
 
 import argparse
 import re as _re
+import sys
 from datetime import date
 from pathlib import Path
 
 import yaml
 from jinja2 import Environment, FileSystemLoader
-from weasyprint import HTML
+from weasyprint import CSS, HTML
 
+from scripts.lint_cv import lint_cv_context
 
 _ATS_REPLACEMENTS: list[tuple[str, str]] = [
     ("—", "--"),  # em-dash
@@ -18,7 +20,7 @@
     ("’", "'"),  # right single quote
     ("“", '"'),  # left double quote
     ("”", '"'),  # right double quote
-    (" ", " "),  # non-breaking space
+    (" ", " "),  # non-breaking space
     ("​", ""),  # zero-width space
     ("‌", ""),  # zero-width non-joiner
     ("", ""),  # BOM
@@ -29,6 +31,18 @@
     _re.DOTALL | _re.IGNORECASE,
 )
 
+# ponytail: single compact retry, not an iterative shrink loop — escalate to
+# multiple compact levels only if one retry proves insufficient in practice.
+_COMPACT_CSS = CSS(
+    string="""
+    @page { margin: 5mm 10mm; }
+    body { font-size: 8.7pt; line-height: 1.15; }
+    .section { margin-bottom: 7px; }
+    li { margin-bottom: 0; }
+    .job { margin-bottom: 2px; }
+    """
+)
+
 
 def _normalize_for_ats(html: str) -> str:
     """Replace typographic characters that break ATS parsers, preserving style/script blocks."""
@@ -96,7 +110,7 @@ def build_cv_context(
         "github": github,
         "summary": summary,
         "experience": experience,
-        "skill_categories": skill_categories,
+        "skill_categories": {k: v for k, v in skill_categories.items() if v},
         "highlighted_skills": highlighted_skills,
         "education": education,
         "languages": languages,
@@ -113,9 +127,103 @@ def render_html(context: dict, lang: str = "fr") -> str:
     return template.render(**context)
 
 
-def generate_pdf(context: dict, offer: str, output_date: str, lang: str = "fr") -> Path:
+def screenshot_cv(html_content: str, css_path: Path, output_path: Path) -> Path:
+    """Render CV HTML (CSS inlined) to a full-page A4 PNG for visual self-check."""
+    from playwright.sync_api import sync_playwright
+
+    inlined = html_content.replace(
+        '<link rel="stylesheet" href="cv.css">',
+        f"<style>{css_path.read_text(encoding='utf-8')}</style>",
+    )
+    with sync_playwright() as pw:
+        browser = pw.chromium.launch()
+        page = browser.new_page(viewport={"width": 794, "height": 1123})
+        page.set_content(inlined)
+        page.screenshot(path=str(output_path), full_page=True)
+        browser.close()
+    return output_path
+
+
+_DROPPABLE_KINDS = {"certification", "project", "hobbies"}
+
+
+def _page_count(context: dict, lang: str) -> int:
+    template_dir = TEMPLATE_DIR_EN if lang == "en" else TEMPLATE_DIR_FR
+    html = _normalize_for_ats(render_html(context, lang=lang))
+    return len(
+        HTML(string=html, base_url=str(template_dir)).render(
+            stylesheets=[str(template_dir / "cv.css")]
+        ).pages
+    )
+
+
+def _apply_cuts(context: dict, cuts: list[tuple[str, str | None]]) -> dict:
+    """Return a copy of context with each (kind, name) cut removed."""
+    ctx = dict(context)
+    drop_certs = {name for kind, name in cuts if kind == "certification"}
+    drop_projects = {name for kind, name in cuts if kind == "project"}
+    if drop_certs:
+        ctx["certifications"] = [
+            c for c in (ctx.get("certifications") or []) if c["name"] not in drop_certs
+        ]
+    if drop_projects:
+        ctx["projects"] = [p for p in (ctx.get("projects") or []) if p["name"] not in drop_projects]
+    if any(kind == "hobbies" for kind, _ in cuts):
+        ctx["hobbies"] = []
+    return ctx
+
+
+def fit_to_one_page(
+    context: dict, lang: str, droppable: list[tuple[str, str | None]]
+) -> tuple[dict, list[str]]:
+    """Trim optional content to fit the CV on 1 page, keeping as much as possible.
+
+    `droppable` ranks removable content least-to-most relevant to the target offer, as
+    (kind, name) pairs where kind is "certification" | "project" | "hobbies" (name is
+    ignored for "hobbies", which drops the whole section as one unit).
+
+    ponytail: only handles whole-unit cuts (certs/projects/hobbies) -- experience bullets
+    and skills are ranked by hand when building `context` (modes/generate-cv.md already
+    does this). Extend with a 4th kind if bullet-level trimming proves necessary in practice.
+
+    Returns the resulting context (input is never mutated) and the labels still cut.
+    """
+    for kind, _ in droppable:
+        if kind not in _DROPPABLE_KINDS:
+            raise ValueError(f"unknown droppable kind: {kind!r}")
+
+    if _page_count(context, lang) <= 1:
+        return context, []
+
+    kept_cuts = list(droppable)  # start by cutting everything droppable
+    for cut in reversed(droppable):  # try restoring most-relevant-first
+        candidate_cuts = [c for c in kept_cuts if c != cut]
+        if _page_count(_apply_cuts(context, candidate_cuts), lang) <= 1:
+            kept_cuts = candidate_cuts
+
+    final = _apply_cuts(context, kept_cuts)
+    return final, [f"{kind}:{name}" for kind, name in kept_cuts]
+
+
+def generate_pdf(
+    context: dict,
+    offer: str,
+    output_date: str,
+    lang: str = "fr",
+    screenshot: bool = False,
+    droppable: list[tuple[str, str | None]] | None = None,
+) -> Path:
     from scripts.models import safe_slug
 
+    issues = lint_cv_context(context)
+    if issues:
+        raise ValueError(
+            "CV failed ATS pre-flight lint:\n" + "\n".join(f"- {issue}" for issue in issues)
+        )
+
+    if droppable:
+        context, _ = fit_to_one_page(context, lang, droppable)
+
     template_dir = TEMPLATE_DIR_EN if lang == "en" else TEMPLATE_DIR_FR
     slug = safe_slug(offer)
     out_dir = (OUTPUT_DIR / f"{slug}-{output_date}").resolve()
@@ -126,10 +234,24 @@ def generate_pdf(context: dict, offer: str, output_date: str, lang: str = "fr")
     output_path = out_dir / f"cv-{slug}-{output_date}{suffix}.pdf"
     html_content = _normalize_for_ats(render_html(context, lang=lang))
     css_path = template_dir / "cv.css"
-    HTML(string=html_content, base_url=str(template_dir)).write_pdf(
-        str(output_path),
-        stylesheets=[str(css_path)],
+
+    document = HTML(string=html_content, base_url=str(template_dir)).render(
+        stylesheets=[str(css_path)]
     )
+    if len(document.pages) > 1:
+        document = HTML(string=html_content, base_url=str(template_dir)).render(
+            stylesheets=[str(css_path), _COMPACT_CSS]
+        )
+        if len(document.pages) > 1:
+            print(
+                f"WARNING: CV is {len(document.pages)} pages after compact retry — trim content.",
+                file=sys.stderr,
+            )
+    document.write_pdf(str(output_path))
+
+    if screenshot:
+        screenshot_cv(html_content, css_path, output_path.with_suffix(".png"))
+
     return output_path
 
 
@@ -187,9 +309,16 @@ def default_context_en() -> dict:
         default="fr",
         help="CV language: fr (default) or en",
     )
+    parser.add_argument(
+        "--screenshot",
+        action="store_true",
+        help="Also render a PNG screenshot next to the PDF for visual self-check",
+    )
     args = parser.parse_args()
 
     ctx = default_context(lang=args.lang)
     ctx["highlighted_skills"] = args.highlighted
-    path = generate_pdf(ctx, offer=args.offer, output_date=args.date, lang=args.lang)
+    path = generate_pdf(
+        ctx, offer=args.offer, output_date=args.date, lang=args.lang, screenshot=args.screenshot
+    )
     print(f"PDF generated: {path}")

scripts/lint_cv.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""Deterministic pre-flight checks on CV content, run before PDF generation."""
+
+
+def lint_cv_context(context: dict) -> list[str]:
+    """Return ATS-parseability issues found in a CV context dict (empty list = clean)."""
+    issues: list[str] = []
+
+    for field in ("name", "email", "phone"):
+        if not context.get(field):
+            issues.append(f"missing required contact field: {field}")
+
+    for i, job in enumerate(context.get("experience", [])):
+        for field in ("title", "company", "period"):
+            if not job.get(field):
+                issues.append(f"experience[{i}] missing '{field}'")
+
+    for i, edu in enumerate(context.get("education", [])):
+        for field in ("degree", "school", "period"):
+            if not edu.get(field):
+                issues.append(f"education[{i}] missing '{field}'")
+
+    return issues

templates/cv-en/cv.html.j2

@@ -23,6 +23,7 @@
 </div>
 {% endif %}
 
+{% if experience %}
 <div class="section">
   <div class="section-title">Experience</div>
   {% for job in experience %}
@@ -47,7 +48,9 @@
   </div>
   {% endfor %}
 </div>
+{% endif %}
 
+{% if skill_categories %}
 <div class="section">
   <div class="section-title">Skills</div>
   {% for category, items in skill_categories.items() %}
@@ -59,6 +62,7 @@
   </div>
   {% endfor %}
 </div>
+{% endif %}
 
 {% if certifications %}
 <div class="section">
@@ -84,6 +88,7 @@
 </div>
 {% endif %}
 
+{% if education %}
 <div class="section">
   <div class="section-title">Education</div>
   {% for edu in education %}
@@ -96,6 +101,7 @@
   </div>
   {% endfor %}
 </div>
+{% endif %}
 
 {% if languages %}
 <div class="section">

templates/cv-fr/cv.html.j2

@@ -23,6 +23,7 @@
 </div>
 {% endif %}
 
+{% if experience %}
 <div class="section">
   <div class="section-title">Expérience</div>
   {% for job in experience %}
@@ -47,7 +48,9 @@
   </div>
   {% endfor %}
 </div>
+{% endif %}
 
+{% if skill_categories %}
 <div class="section">
   <div class="section-title">Compétences</div>
   {% for category, items in skill_categories.items() %}
@@ -59,6 +62,7 @@
   </div>
   {% endfor %}
 </div>
+{% endif %}
 
 {% if certifications %}
 <div class="section">
@@ -84,6 +88,7 @@
 </div>
 {% endif %}
 
+{% if education %}
 <div class="section">
   <div class="section-title">Formation</div>
   {% for edu in education %}
@@ -96,6 +101,7 @@
   </div>
   {% endfor %}
 </div>
+{% endif %}
 
 {% if languages %}
 <div class="section">