Point the deck-audit docs at the unified review entry point

Update the overflow / contrast subagent docs to reference the package
modules and review_deck, and add pptx_review and the review subcommand to
README, the MCP and CLI references, and the en / zh-tw / zh-cn Sphinx docs.

Author: JE-Chen

.claude/agents/rules/deck-design.md

@@ -134,8 +134,11 @@ Both layers ship together; tests pin both. The regression test
 ``test_pptx_dark_mode_has_no_invisible_runs`` (in ``tests/test_exporters.py``)
 walks every run on every slide of a default-dark-mode deck and fails
 if any non-empty run has ``rgb is None`` or ``rgb == (0,0,0)``. A
-companion debug script lives at ``scripts/_audit_dark_text.py`` for
-manual inspection of a single rendered deck.
+companion auditor lives at ``thesisagents.exporters.audit.audit_deck`` (the
+``scripts/_audit_dark_text.py`` CLI is a thin wrapper) for manual inspection
+of a single rendered deck — or use the one-stop ``review_deck`` /
+``python -m thesisagents review`` / MCP ``pptx_review``, which bundles this
+contrast audit with the overflow and section-completeness checks.
 
 #### "No red text" contract (HARD)
 
@@ -223,9 +226,10 @@ stayed light. White-on-white. Fixed by adding the mapping
    text colour, and fails when both > 0.7 × 255 (= 178). Adding a new
    light-fill shape without a corresponding dark mapping will fail
    this test.
-3. **The audit script** ``scripts/_audit_dark_text.py`` now also
-   reports failure-mode B — run it on a rendered deck during manual
-   inspection.
+3. **The auditor** ``thesisagents.exporters.audit.audit_deck`` (CLI
+   ``scripts/_audit_dark_text.py``, or bundled into ``review_deck`` /
+   ``pptx_review``) now also reports failure-mode B — run it on a rendered
+   deck during manual inspection.
 
 Exposure surfaces (light is default; the toggles opt IN to DARK):
 - CLI: `--dark-mode` opt-in flag (when absent → light)

.claude/agents/tasks/slide-overflow-check.md

@@ -28,19 +28,29 @@ You'll be told (or you can infer from context) which deck(s) to check. Typical i
 - A specific path: `exports/<run>/<key>.pptx`
 - Or a regen script the parent just ran: re-derive the path from the script's `out_dir` + `filename_stem`.
 
-**Use the canonical inspector — `scripts/check_overflow.py`.** It already encodes
-the project's wrap estimate and calibration, so run it rather than reinventing one:
+**Use the canonical inspector.** Its logic now lives in the package at
+`thesisagents.exporters.overflow` (the `scripts/check_overflow.py` CLI is a thin
+wrapper re-exporting it), so run it rather than reinventing one:
 
 ```
 .venv/Scripts/python.exe scripts/check_overflow.py exports/<deck>.pptx [more.pptx ...]
 ```
 
 It prints the report block below per deck and exits with the count of failed decks
 (0 = all clean), so you can assert on the exit code. It is also importable —
-`from check_overflow import check_pptx, check_pptx_from_prs` — returning a list of
+`from thesisagents.exporters.overflow import check_pptx, check_pptx_from_prs` (the
+script path `from check_overflow import …` still works too) — returning a list of
 `Violation(slide, shape, kind, rendered_in, limit_in)`; `check_pptx_from_prs(prs)`
 takes an already-open `Presentation` so a test can build a deck in memory.
 
+**For a full deck audit (overflow + colour contracts + section completeness) in
+one pass, prefer `thesisagents.exporters.review.review_deck(path)`** — exposed as
+the CLI `python -m thesisagents review <deck.pptx>` and the MCP `pptx_review`
+tool. It bundles this overflow check with the dark-mode / no-red / contrast audit
+and the `paper_rule` seven-section completeness check, returning a single
+`DeckReview` (`.ok`, `.overflow`, `.contrast`, `.missing_sections`). Use the
+standalone overflow inspector above when you only need the geometry check.
+
 What it does (so you can trust / explain its output):
 
 - Reads each run's actual `font.size` (the exporter sets it per run), classifies

CLAUDE.md

@@ -47,8 +47,10 @@ Concretely, the assistant:
 4. **Generates** `.pptx` (three rendering tiers — lightweight / enriched-flat /
    thesis-style), `.xlsx`, `.bib`, `.md`, `.json` outputs.
 5. **Exposes** every step as an MCP tool (`search`, `fetch_paper`, `fetch_pdf_text`,
-   `export`, `pptx_inspect`, `pptx_update_slide`, `pptx_delete_slide`,
-   `pptx_reorder_slides`, `pptx_add_slide`).
+   `export`, `pptx_inspect`, `pptx_review`, `pptx_update_slide`, `pptx_delete_slide`,
+   `pptx_reorder_slides`, `pptx_add_slide`). `pptx_review` audits an existing deck
+   (overflow + colour contracts + `paper_rule` section completeness) in one call —
+   the same audit the CLI exposes as `python -m thesisagents review <deck.pptx>`.
 
 Single-process, Python 3.12+. Heavy I/O off the event loop; shared
 `httpx.AsyncClient` registry pools connections per source.

README.md

@@ -64,9 +64,9 @@ it.
 6. export(papers=[{...paper, "summary": {...}}], language="zh-tw", ...)
 ```
 
-All twelve MCP tools (including `list_sources`, `list_exports`,
-`download_pdfs`, `pptx_inspect` / `pptx_update_slide` / `pptx_add_slide`
-/ etc.) are
+All thirteen MCP tools (including `list_sources`, `list_exports`,
+`download_pdfs`, `pptx_inspect` / `pptx_review` / `pptx_update_slide` /
+`pptx_add_slide` / etc.) are
 documented in [`docs/mcp.md`](docs/mcp.md).
 
 ### Mandatory: URL / DOI verification before shipping
@@ -411,6 +411,7 @@ Tools:
 | `download_pdfs` | Batch-download a papers list's PDFs into `{out_dir}/pdfs/`. Returns per-paper results keyed by BibTeX key. |
 | `export` | Papers list + formats → writes `.pptx/.xlsx/.md/.bib/.json/.ris/.csv/.csl.json`. Accepts a `summary` field per paper for the rich thesis-style schema, `max_slides_per_paper` (default 25), and `dark_mode` (default `true` — the project's dark-deck post-pass; pass `false` for the printable light variant). |
 | `pptx_inspect` | Read slide / shape structure of an existing deck. |
+| `pptx_review` | Audit a deck in one call — overflow + colour contracts + `paper_rule` section completeness. Auto-detects the deck language; also the CLI `python -m thesisagents review <deck.pptx>`. |
 | `pptx_update_slide` | Replace `title` / `body` / `meta` (by shape name) or arbitrary shapes by index. |
 | `pptx_delete_slide` | Remove a slide and its part relationship. |
 | `pptx_reorder_slides` | Permute slides via `sldIdLst`. |

docs/cli.md

@@ -131,6 +131,24 @@ research question, KPI metrics, technique table, literature
 positioning, per-RQ result tables, …), and the PPT exporter renders the
 thesis-style layout.
 
+### Review an existing deck
+
+```bash
+thesisagents review ./exports/attention.pptx
+thesisagents review ./exports/*.pptx --lang zh-tw
+```
+
+The `review` subcommand audits a finished `.pptx` against all three
+deck-quality contracts in one pass — slide **overflow**, the dark-mode /
+no-red / contrast **colour** contracts, and `paper_rule` **section
+completeness** (Introduction, Literature Review, Methodology, Experiment,
+Conclusion). `--lang` is optional; the deck's language is auto-detected
+from its slide titles otherwise. It prints a per-deck report and exits
+with the number of decks that failed (`0` = all clean), so it drops into
+CI. Section completeness only fails a *thesis-style* deck — a lightweight
+abstract-only deck is never failed for legitimately lacking sections.
+The same audit is the MCP `pptx_review` tool.
+
 ## Exit codes
 
 | Code | Meaning |

docs/en/index.rst

@@ -448,6 +448,10 @@ Tools at a glance:
        for the printable light variant).
    * - ``pptx_inspect``
      - Read slide / shape structure of an existing deck.
+   * - ``pptx_review``
+     - Audit a deck in one call — overflow + colour contracts +
+       ``paper_rule`` section completeness. Auto-detects the deck
+       language; also the CLI ``python -m thesisagents review``.
    * - ``pptx_update_slide``
      - Replace ``title`` / ``body`` / ``meta`` (by shape name) or
        arbitrary shapes by index.

docs/mcp.md

@@ -385,6 +385,40 @@ Shape names are set by `PptxExporter`: each slide carries `title`,
 elsewhere may not have these names — fall back to `shape_updates`
 addressed by integer index.
 
+### `pptx_review`
+
+Audit an existing deck against all three deck-quality contracts in one
+call: slide **overflow**, the dark-mode / no-red / contrast **colour**
+contracts, and `paper_rule` **section completeness**.
+
+```json
+{"path": "./exports/attention.pptx"}
+```
+
+`language` is optional — it is auto-detected from the slide titles when
+omitted (pass e.g. `"zh-tw"` to force it). Returns:
+
+```text
+{
+  "path": "./exports/attention.pptx",
+  "language": "zh-tw",
+  "thesis_style": true,
+  "ok": true,
+  "overflow": [],                 // {slide, shape, kind, rendered_in, limit_in}
+  "contrast": [],                 // {slide, shape, kind, detail, hard}
+  "missing_sections": [],         // canonical body sections with no covering slide
+  "completeness_gated": true      // missing_sections only fail a thesis-style deck
+}
+```
+
+`ok` is `false` when there is any overflow, any *hard* contrast issue
+(invisible / red / light-on-light text), or — for a thesis-style deck —
+any missing body section (Introduction, Literature Review, Methodology,
+Experiment, Conclusion). A lightweight abstract-only deck is never failed
+for lacking sections (`thesis_style` / `completeness_gated` say which).
+The same audit is available on the command line as
+`python -m thesisagents review <deck.pptx> [more.pptx ...] [--lang xx]`.
+
 ### `pptx_update_slide`
 
 Replace text on one slide.

docs/zh-cn/index.rst

@@ -353,6 +353,10 @@ Claude Desktop、Cursor …)都能驱动整套流程。
        代表不限)。
    * - ``pptx_inspect``
      - 读已有幻灯片文件的 slide / shape 结构。
+   * - ``pptx_review``
+     - 一次审核整份幻灯片 — 溢出 + 颜色契约 + ``paper_rule``\
+       章节完整度。自动检测语言,也是 CLI
+       ``python -m thesisagents review``。
    * - ``pptx_update_slide``
      - 替换 ``title``/ ``body``/ ``meta``\ (通过 shape name)或
        任意 shape(通过 index)。

docs/zh-tw/index.rst

@@ -354,6 +354,10 @@ Claude Desktop、Cursor …)都能驅動整套流程。
        代表不限)。
    * - ``pptx_inspect``
      - 讀既有投影片檔的 slide / shape 結構。
+   * - ``pptx_review``
+     - 一次稽核整份投影片 — 溢位 + 色彩契約 + ``paper_rule``\
+       章節完整度。自動偵測語言,亦為 CLI
+       ``python -m thesisagents review``。
    * - ``pptx_update_slide``
      - 取代 ``title``/ ``body``/ ``meta``\ (透過 shape name)或
        任意 shape(透過 index)。