@research-copilot/plugin 1.1.17 → 1.1.19

package/dist/skills/paper-illustration-image2/SKILL.md

@@ -0,0 +1,383 @@
+---
+name: paper-illustration-image2
+description: "Generate publication-quality academic illustrations through a local Codex app-server bridge that uses Codex native image generation. This is a separate experimental alternative to `paper-illustration`, intended for Claude Code users who want a GPT-image-style renderer without modifying the original skill."
+argument-hint: [description-or-method-file]
+allowed-tools: Bash(*), Read, Write, Edit, Grep, Glob, WebSearch, mcp__codex-image2__generate, mcp__codex-image2__generate_start, mcp__codex-image2__generate_status, spawn_agent, send_input
+---
+
+# Paper Illustration Image2
+
+Generate publication-quality paper figures using **Claude as the planner/reviewer**
+and a **local Codex app-server MCP bridge** as the raster renderer.
+
+## Core Design Philosophy
+
+```text
+┌──────────────────────────────────────────────────────────────────────────┐
+│                    MULTI-STAGE ITERATIVE WORKFLOW                        │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│   User Request                                                           │
+│       │                                                                  │
+│       ▼                                                                  │
+│   ┌─────────────┐                                                        │
+│   │   Claude    │ ◄─── Step 1: Parse request, create initial prompt     │
+│   │  (Planner)  │      - Extract components, labels, and data flow       │
+│   │             │      - Write a paper-ready figure brief                │
+│   └──────┬──────┘                                                        │
+│          │                                                               │
+│          ▼                                                               │
+│   ┌─────────────┐                                                        │
+│   │Claude/Codex │ ◄─── Step 2: Optimize layout description               │
+│   │   Layout    │      - Refine component positioning                    │
+│   │   Review    │      - Optimize spacing and grouping                   │
+│   └──────┬──────┘                                                        │
+│          │                                                               │
+│          ▼                                                               │
+│   ┌─────────────┐                                                        │
+│   │Claude/Codex │ ◄─── Step 3: CVPR/NeurIPS style verification           │
+│   │   Style     │      - Check palette, arrows, and label standards      │
+│   │   Check     │      - Tighten the prompt before rendering             │
+│   └──────┬──────┘                                                        │
+│          │                                                               │
+│          ▼                                                               │
+│   ┌─────────────┐                                                        │
+│   │ codex-image2│ ◄─── Step 4: Native image generation via bridge        │
+│   │ MCP bridge  │      - Call generate_start / generate_status           │
+│   │ + app-server│      - Accept only native imageGeneration output       │
+│   └──────┬──────┘                                                        │
+│          │                                                               │
+│          ▼                                                               │
+│   ┌─────────────┐                                                        │
+│   │   Claude    │ ◄─── Step 5: STRICT visual review + SCORE (1-10)      │
+│   │  (Reviewer) │      - Verify logic, labels, arrows, and aesthetics    │
+│   │   STRICT!   │      - Reject unclear or non-paper-ready figures       │
+│   └──────┬──────┘                                                        │
+│          │                                                               │
+│          ▼                                                               │
+│   Score ≥ 9? ──YES──► Accept & Output                                    │
+│          │                                                               │
+│          NO                                                              │
+│          │                                                               │
+│          ▼                                                               │
+│   Generate SPECIFIC improvement feedback ──► Loop back to Step 2        │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+## Constants
+
+- **RENDERER = `codex-image2`** — Native image generation bridge exposed through local Codex app-server
+- **OPTIONAL_TEXT_CRITIC = `spawn_agent`** — Optional text-only second opinion for layout/style checks
+- **MAX_ITERATIONS = 5** — Maximum refinement rounds
+- **TARGET_SCORE = 9** — Minimum acceptable score (1-10)
+- **OUTPUT_DIR = `figures/ai_generated/`** — Output directory
+- **TEXT_LANGUAGE = `English`** — Default figure text language unless the user requests otherwise
+- **NATIVE_IMAGE_REQUIREMENT = `strict`** — Accept only native `imageGeneration` output; reject shell/Python fallbacks
+- **IMAGE2_HELPER** — canonical name `paper_illustration_image2.py`, resolved
+  per [`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2
+  (Policy A — skill-local gate). Phase 3.2 (Arch C) moved the canonical
+  implementation into `skills/paper-illustration-image2/scripts/`;
+  `tools/paper_illustration_image2.py` remains as an `os.execv` shim so
+  legacy resolver layers keep working without a re-install. Resolve via the
+  Codex-side chain:
+
+  ```bash
+  IMAGE2_HELPER=""
+  cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
+  if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills-codex.txt ]; then
+      ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills-codex.txt 2>/dev/null) || true
+  fi
+  [ -f ".agents/skills/paper-illustration-image2/scripts/paper_illustration_image2.py" ] && IMAGE2_HELPER=".agents/skills/paper-illustration-image2/scripts/paper_illustration_image2.py"
+  [ -z "$IMAGE2_HELPER" ] && [ -n "${ARIS_REPO:-}" ] && [ -f "$ARIS_REPO/skills/paper-illustration-image2/scripts/paper_illustration_image2.py" ] && IMAGE2_HELPER="$ARIS_REPO/skills/paper-illustration-image2/scripts/paper_illustration_image2.py"
+  [ -z "$IMAGE2_HELPER" ] && [ -n "${ARIS_REPO:-}" ] && [ -f "$ARIS_REPO/tools/paper_illustration_image2.py" ] && IMAGE2_HELPER="$ARIS_REPO/tools/paper_illustration_image2.py"
+  [ -z "$IMAGE2_HELPER" ] && [ -f tools/paper_illustration_image2.py ] && IMAGE2_HELPER="tools/paper_illustration_image2.py"
+  [ -z "$IMAGE2_HELPER" ] && [ -f ~/.codex/skills/paper-illustration-image2/scripts/paper_illustration_image2.py ] && IMAGE2_HELPER="$HOME/.codex/skills/paper-illustration-image2/scripts/paper_illustration_image2.py"
+  [ -z "$IMAGE2_HELPER" ] && {
+    echo "ERROR: paper_illustration_image2.py not resolved at .agents/skills/, \$ARIS_REPO/skills/, \$ARIS_REPO/tools/, tools/, or ~/.codex/skills/." >&2
+    echo "       /paper-illustration-image2 cannot proceed. Fix: rerun install_aris_codex.sh, export ARIS_REPO, or copy the canonical skill into ~/.codex/skills/." >&2
+    exit 1
+  }
+  ```
+
+  All invocations below use `python3 "$IMAGE2_HELPER" <subcommand>`.
+
+## CVPR/ICLR/NeurIPS Top-Tier Conference Style Guide
+
+**What "CVPR Style" Actually Means:**
+
+### Visual Standards
+- **Clean white background** — No decorative patterns or gradients unless extremely subtle
+- **Sans-serif fonts** — Arial, Helvetica, or similarly clean paper-friendly typography
+- **Subtle color palette** — Use 3-5 coordinated colors, not rainbow colors
+- **Print-friendly** — Must remain understandable in grayscale
+- **Professional borders** — Thin to medium, clean, and consistent
+
+### Layout Standards
+- **Horizontal flow** — Left-to-right is the default for pipelines
+- **Clear grouping** — Use spacing or subtle grouping boxes for related modules
+- **Consistent sizing** — Similar components should have similar sizes
+- **Balanced whitespace** — Avoid both cramped and overly sparse layouts
+
+### Arrow Standards (MOST CRITICAL)
+- **Thick strokes** — Arrows must remain visible after paper scaling
+- **Clear arrowheads** — Large, unmistakable arrowheads
+- **Dark colors** — Prefer black or dark gray arrows
+- **Labeled** — Important arrows should show what flows through them
+- **No crossings** — Reorganize the figure to avoid crossings where possible
+- **CORRECT DIRECTION** — Arrows must point to the right target
+
+### Visual Appeal (Academic Professional Style)
+
+**目标：既不保守也不花哨，找到平衡点**
+
+#### ✅ Should have
+- **Subtle gradients** — Gentle same-family gradients are acceptable
+- **Rounded corners** — Modern but restrained rounded blocks
+- **Clear hierarchy** — Main modules larger, secondary modules smaller
+- **Consistent color coding** — Stable mapping between module types and colors
+- **Professional typography** — Clean labels with readable size hierarchy
+
+#### ❌ Avoid
+- ❌ Rainbow gradients
+- ❌ Heavy drop shadows
+- ❌ 3D perspective effects
+- ❌ Glowing effects
+- ❌ Decorative clip-art icons
+- ❌ Slide-deck styling that feels flashy rather than paper-ready
+
+#### ✓ Ideal effect
+- Looks intentional, professional, and immediately readable
+- Has moderate visual appeal without becoming decorative
+- Feels appropriate for a top-tier conference paper figure
+- Survives PDF scaling and grayscale printing
+
+### What to AVOID (CRITICAL)
+- ❌ Thin, hairline arrows
+- ❌ Unlabeled or ambiguous connections
+- ❌ Tiny unreadable text
+- ❌ Flat, boring box soup with no hierarchy
+- ❌ Over-decorated figures with shadows/glows/icons
+- ❌ Wrong arrow directions
+
+## Scope
+
+| Figure Type | Quality | Examples |
+|-------------|---------|----------|
+| **Architecture diagrams** | Excellent | Model architecture, pipeline, encoder-decoder |
+| **Method illustrations** | Excellent | Conceptual diagrams, algorithm flowcharts |
+| **Conceptual figures** | Good | Comparison diagrams, taxonomy trees |
+
+**Not for:** Statistical plots (use `/paper-figure`), deterministic vector topology figures (prefer `/figure-spec`), photo-realistic scenes
+
+## Workflow: MUST EXECUTE ALL STEPS
+
+### Step 0: Pre-flight Check
+
+Render this checklist explicitly before starting:
+
+```text
+📋 paper-illustration-image2 integration checklist:
+   [ ] 1. python3 "$IMAGE2_HELPER" preflight --workspace <cwd> --json-out figures/ai_generated/preflight.json
+   [ ] 2. Confirm preflight JSON says ok=true before rendering
+   [ ] 3. Render via mcp__codex-image2__generate_start + generate_status
+   [ ] 4. Finalize via python3 "$IMAGE2_HELPER" finalize --workspace <cwd> --best-image <best_png>
+   [ ] 5. Verify artifacts via python3 "$IMAGE2_HELPER" verify --workspace <cwd> --json-out figures/ai_generated/verify.json
+```
+
+1. Create `figures/ai_generated/` if it does not exist.
+2. Confirm the request is suitable for a raster illustration:
+   - architecture diagram
+   - conceptual method figure
+   - workflow illustration
+3. Prefer **English figure text** unless the user asked otherwise.
+4. Run:
+
+```bash
+python3 "$IMAGE2_HELPER" preflight \
+  --workspace <cwd> \
+  --json-out figures/ai_generated/preflight.json
+```
+
+5. If preflight is not `ok=true`, stop and say so clearly.
+
+## Step 1: Claude Plans the Figure
+
+Turn the user request into a **fully specified image prompt**. Include:
+
+- figure type
+- exact modules / stages
+- flow direction
+- labels to show
+- data-flow arrows
+- style constraints
+- what to avoid
+
+When the input is a method note or a paper section, summarize it first into a
+clean figure brief before writing the final image prompt.
+
+## Step 2: Layout Optimization
+
+This step is required. Before rendering, refine the prompt into a concrete
+layout plan:
+
+- exact module order
+- spacing and grouping
+- relative module prominence
+- arrow routing and likely collision points
+
+If `spawn_agent` is available, you may ask it for a short second-opinion
+layout critique here, but Claude should still complete this step even without
+Codex.
+
+Use Codex layout critique for:
+
+- missing components
+- confusing layout
+- weak flow hierarchy
+- likely arrow-direction ambiguity or clutter
+
+## Step 3: Style Verification
+
+This step is also required. Check the prompt against the intended paper style
+before rendering:
+
+- palette is restrained and academic
+- arrows are thick, dark, and readable
+- labels are concise and in English unless requested otherwise
+- the figure will read clearly in grayscale / print
+- no glow, rainbow gradient, or slide-deck decoration slips in
+
+If `spawn_agent` is available, you may ask it for a short text-only
+style audit, but do not block on it.
+
+## Step 4: Generate Through the Bridge
+
+Call `mcp__codex-image2__generate_start` with:
+
+- `prompt`: the final image prompt
+- `cwd`: current project root or paper workspace
+- `outputPath`: `figures/ai_generated/figure_v1.png`
+- `system`: a short instruction like `Academic paper figure. Prefer crisp English labels.`
+- `timeoutSeconds`: a bounded render timeout such as `180`
+
+Then call `mcp__codex-image2__generate_status` with bounded waits until:
+
+- `done=true` and `status=completed`, or
+- `done=true` and `status=failed`
+
+If generation fails, report the bridge error directly instead of hiding it.
+
+## Step 5: Review the Output
+
+Review the generated image with a strict checklist:
+
+- are all major components present?
+- is the logical flow obvious?
+- are labels readable?
+- do arrows point the right way?
+- does the figure look paper-ready rather than like a slide?
+
+Score it from 1-10.
+
+## Step 6: Refine if Needed
+
+If score < 9, write a targeted refinement prompt:
+
+- say exactly what was wrong
+- say what to preserve
+- regenerate to `figure_v2.png`, `figure_v3.png`, etc.
+
+Keep refinement feedback concrete:
+
+- `Increase spacing between genome scan and scoring modules`
+- `Make the off-target branch thinner and secondary`
+- `Use cleaner English labels: "Candidate sgRNA library", not "sgRNA library 23 bp"`
+
+## Step 7: Finalize And Verify
+
+When accepted:
+
+- run the canonical helper to promote the best image to `figure_final.png`
+- let the helper write `latex_include.tex`
+- let the helper write `review_log.json`
+- run helper verification before claiming success
+
+```bash
+python3 "$IMAGE2_HELPER" finalize \
+  --workspace <cwd> \
+  --best-image figures/ai_generated/figure_vN.png \
+  --score 9 \
+  --review-summary "Accepted after strict review; labels and arrows are paper-ready."
+
+python3 "$IMAGE2_HELPER" verify \
+  --workspace <cwd> \
+  --json-out figures/ai_generated/verify.json
+```
+
+Suggested LaTeX:
+
+```latex
+\begin{figure*}[t]
+    \centering
+    \includegraphics[width=0.95\textwidth]{figures/ai_generated/figure_final.png}
+    \caption{[Replace with a paper-ready caption].}
+    \label{fig:[replace-me]}
+\end{figure*}
+```
+
+## Key Rules
+
+1. Never skip Step 2 or Step 3; layout and style checks are required.
+2. Never skip the final visual review.
+3. Never accept a figure that is logically wrong just because it looks attractive.
+4. Use the `codex-image2` bridge only for **native image generation**.
+5. If the bridge says native image generation is unavailable, surface that honestly.
+6. Reject any shell/Python/manual bitmap fallback masquerading as image generation.
+7. Keep figure text in English unless the user requested another language.
+8. Prefer 1-3 strong refinement rounds over many shallow ones.
+9. Use specific, actionable refinement feedback instead of vague comments.
+10. Review arrow direction, label clarity, and visual hierarchy every round.
+11. Accept only figures that look paper-ready, not slide-ready.
+12. Always use `tools/paper_illustration_image2.py finalize` to emit the final artifacts.
+13. Always use `tools/paper_illustration_image2.py verify` before claiming success.
+
+## Repair Path
+
+If rendering succeeded but final artifacts were skipped, repair the integration explicitly:
+
+```bash
+python3 "$IMAGE2_HELPER" finalize \
+  --workspace <cwd> \
+  --best-image figures/ai_generated/figure_vN.png
+
+python3 "$IMAGE2_HELPER" verify \
+  --workspace <cwd> \
+  --json-out figures/ai_generated/verify.json
+```
+
+## Output Structure
+
+```text
+figures/ai_generated/
+├── preflight.json         # Helper preflight receipt
+├── figure_v1.png          # Iteration 1
+├── figure_v2.png          # Iteration 2
+├── figure_v3.png          # Iteration 3
+├── figure_final.png       # Accepted version (copy of best, score ≥ 9)
+├── latex_include.tex      # LaTeX snippet
+├── review_log.json        # Review notes and refinement history
+└── verify.json            # Helper verification diagnostic
+```
+
+## Model Summary
+
+| Stage | Agent / Tool | Purpose |
+|-------|--------------|---------|
+| Step 0 | `python3 "$IMAGE2_HELPER" preflight` | Observable activation predicate and preflight receipt |
+| Step 1 | Claude | Parse request and create the initial figure prompt |
+| Step 2 | Claude (+ optional Codex critique) | Refine layout, grouping, spacing, and arrow routing |
+| Step 3 | Claude (+ optional Codex critique) | Verify academic visual style before rendering |
+| Step 4 | `mcp__codex-image2__generate_start` + `generate_status` | Native raster image generation through Codex app-server |
+| Step 5 | Claude | Strict visual review and scoring |
+| Step 7 | `python3 "$IMAGE2_HELPER" finalize` + `verify` | Emit canonical artifacts and external verification receipt |

package/dist/skills/paper-illustration-image2/scripts/paper_illustration_image2.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""Integration helper for the paper-illustration-image2 workflow."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def resolve_workspace(raw_workspace: str | None) -> Path:
+    workspace = Path(raw_workspace).expanduser() if raw_workspace else Path.cwd()
+    return workspace.resolve()
+
+
+def output_dir(workspace: Path) -> Path:
+    return (workspace / "figures" / "ai_generated").resolve()
+
+
+def ensure_png_file(path: Path) -> None:
+    if not path.is_file():
+        raise FileNotFoundError(f"missing PNG file: {path}")
+    if not path.read_bytes().startswith(PNG_SIGNATURE):
+        raise ValueError(f"expected a PNG file: {path}")
+
+
+def write_json(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+def emit_json(payload: dict, *, json_out: Path | None = None) -> int:
+    if json_out is not None:
+        write_json(json_out, payload)
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0 if payload.get("ok", False) else 1
+
+
+def run_preflight(workspace: Path, *, json_out: Path | None = None) -> int:
+    figures_dir = output_dir(workspace)
+    figures_dir.mkdir(parents=True, exist_ok=True)
+    codex_bin = shutil.which("codex")
+    payload = {
+        "ok": False,
+        "workspace": str(workspace),
+        "outputDir": str(figures_dir),
+        "codexBin": codex_bin,
+        "checkedAt": utc_now(),
+    }
+    if codex_bin is None:
+        payload["error"] = "codex CLI not found on PATH"
+        return emit_json(payload, json_out=json_out)
+
+    try:
+        result = subprocess.run(
+            [codex_bin, "debug", "app-server", "send-message-v2", "ping"],
+            cwd=str(workspace),
+            stdin=subprocess.DEVNULL,
+            capture_output=True,
+            text=True,
+            timeout=20,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        payload["error"] = "codex app-server ping timed out"
+        return emit_json(payload, json_out=json_out)
+
+    payload["returncode"] = result.returncode
+    payload["ok"] = result.returncode == 0
+    if result.returncode != 0:
+        payload["error"] = (result.stderr or result.stdout or "codex app-server ping failed").strip()
+    return emit_json(payload, json_out=json_out)
+
+
+def build_latex_include(caption: str, label: str) -> str:
+    return "\n".join(
+        [
+            r"\begin{figure*}[t]",
+            r"    \centering",
+            r"    \includegraphics[width=0.95\textwidth]{figures/ai_generated/figure_final.png}",
+            f"    \\caption{{{caption}}}",
+            f"    \\label{{{label}}}",
+            r"\end{figure*}",
+            "",
+        ]
+    )
+
+
+def run_finalize(
+    workspace: Path,
+    *,
+    best_image: Path,
+    caption: str,
+    label: str,
+    score: float | None,
+    review_summary: str | None,
+    json_out: Path | None = None,
+) -> int:
+    figures_dir = output_dir(workspace)
+    figures_dir.mkdir(parents=True, exist_ok=True)
+    best_image = best_image.expanduser().resolve()
+    ensure_png_file(best_image)
+
+    final_image = figures_dir / "figure_final.png"
+    latex_include = figures_dir / "latex_include.tex"
+    review_log = figures_dir / "review_log.json"
+
+    shutil.copy2(best_image, final_image)
+    latex_include.write_text(build_latex_include(caption, label), encoding="utf-8")
+
+    review_payload = {
+        "ok": True,
+        "finalizedAt": utc_now(),
+        "workspace": str(workspace),
+        "bestImage": str(best_image),
+        "finalImage": str(final_image),
+        "score": score,
+        "reviewSummary": review_summary,
+        "caption": caption,
+        "label": label,
+    }
+    write_json(review_log, review_payload)
+
+    payload = {
+        "ok": True,
+        "workspace": str(workspace),
+        "artifacts": {
+            "figureFinal": str(final_image),
+            "latexInclude": str(latex_include),
+            "reviewLog": str(review_log),
+        },
+        "score": score,
+        "reviewSummary": review_summary,
+        "finalizedAt": review_payload["finalizedAt"],
+    }
+    return emit_json(payload, json_out=json_out)
+
+
+def run_verify(workspace: Path, *, json_out: Path | None = None) -> int:
+    figures_dir = output_dir(workspace)
+    final_image = figures_dir / "figure_final.png"
+    latex_include = figures_dir / "latex_include.tex"
+    review_log = figures_dir / "review_log.json"
+
+    errors: list[str] = []
+    artifacts = {
+        "figureFinal": {"path": str(final_image), "exists": final_image.is_file()},
+        "latexInclude": {"path": str(latex_include), "exists": latex_include.is_file()},
+        "reviewLog": {"path": str(review_log), "exists": review_log.is_file()},
+    }
+
+    if final_image.is_file():
+        try:
+            ensure_png_file(final_image)
+        except (FileNotFoundError, ValueError) as exc:
+            errors.append(str(exc))
+    else:
+        errors.append(f"missing artifact: {final_image}")
+
+    if latex_include.is_file():
+        latex_text = latex_include.read_text(encoding="utf-8")
+        if "figure_final.png" not in latex_text:
+            errors.append("latex_include.tex does not reference figures/ai_generated/figure_final.png")
+    else:
+        errors.append(f"missing artifact: {latex_include}")
+
+    if review_log.is_file():
+        try:
+            review_payload = json.loads(review_log.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            errors.append(f"review_log.json is not valid JSON: {exc}")
+        else:
+            if str(review_payload.get("finalImage")) != str(final_image):
+                errors.append("review_log.json does not point at figure_final.png")
+    else:
+        errors.append(f"missing artifact: {review_log}")
+
+    payload = {
+        "ok": not errors,
+        "workspace": str(workspace),
+        "checkedAt": utc_now(),
+        "artifacts": artifacts,
+        "errors": errors,
+    }
+    return emit_json(payload, json_out=json_out)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    preflight = subparsers.add_parser("preflight", help="Check that Codex image generation is available")
+    preflight.add_argument("--workspace", help="Paper or project workspace root")
+    preflight.add_argument("--json-out", help="Optional path to save the JSON result")
+
+    finalize = subparsers.add_parser("finalize", help="Finalize the accepted figure artifacts")
+    finalize.add_argument("--workspace", help="Paper or project workspace root")
+    finalize.add_argument("--best-image", required=True, help="Accepted PNG to promote to figure_final.png")
+    finalize.add_argument(
+        "--caption",
+        default="[Replace with a paper-ready caption].",
+        help="Caption text to place in latex_include.tex",
+    )
+    finalize.add_argument("--label", default="fig:replace-me", help="LaTeX figure label")
+    finalize.add_argument("--score", type=float, help="Final review score")
+    finalize.add_argument("--review-summary", help="Short review summary for review_log.json")
+    finalize.add_argument("--json-out", help="Optional path to save the JSON result")
+
+    verify = subparsers.add_parser("verify", help="Verify that final artifacts were emitted correctly")
+    verify.add_argument("--workspace", help="Paper or project workspace root")
+    verify.add_argument("--json-out", help="Optional path to save the JSON result")
+
+    return parser
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+    workspace = resolve_workspace(getattr(args, "workspace", None))
+    json_out = Path(args.json_out).expanduser().resolve() if getattr(args, "json_out", None) else None
+
+    if args.command == "preflight":
+        return run_preflight(workspace, json_out=json_out)
+
+    if args.command == "finalize":
+        return run_finalize(
+            workspace,
+            best_image=Path(args.best_image),
+            caption=args.caption,
+            label=args.label,
+            score=args.score,
+            review_summary=args.review_summary,
+            json_out=json_out,
+        )
+
+    if args.command == "verify":
+        return run_verify(workspace, json_out=json_out)
+
+    parser.error(f"unknown command: {args.command}")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())