jekyll-theme-zer0 1.26.0 → 1.27.0

data/scripts/lib/preview_generator.py

@@ -1,1435 +1,2355 @@
 #!/usr/bin/env python3
-"""
-Preview Image Generator - AI-powered preview image generation for Jekyll content.
+# Feature: ZER0-004
+"""Preview Image Generator — the consolidated AI preview-image engine.
+
+This single file is the ONE engine behind every preview-image entry point
+(`scripts/generate-preview-images.sh` → `scripts/features/generate-preview-images`
+→ this file; `rake preview:*`; the VS Code tasks). It replaces the former
+1,400-line Bash implementation and this file's previous OpenAI-only draft.
+
+Architecture — Claude ORCHESTRATES, an image model RENDERS:
+
+    stage      role                                     engine / credential
+    --------   --------------------------------------   ----------------------------------
+    analyze    Claude reads the article and writes a    CLAUDE_CODE_OAUTH_TOKEN →
+               vivid art-direction brief for the        ANTHROPIC_AUTH_TOKEN →
+               renderer (prompt_engine: claude)         ANTHROPIC_API_KEY → `claude` CLI
+    produce    a raster image model renders the brief   the selected provider (below)
+    review     Claude looks at the produced image       same Claude credential chain
+               (vision) and, if it misrepresents the
+               article, requests ONE refined
+               regeneration (review_engine: claude)
 
-This module provides a Python-based interface for generating preview images
-using various AI providers (OpenAI DALL-E, Stability AI, etc.).
+    provider   renderer                                 credential
+    --------   --------------------------------------   ----------------------------------
+    openai     gpt-image-2 / dall-e-3 (+ --enhance      OPENAI_API_KEY
+    (default)  via /v1/images/edits)
+    xai        grok-2-image                             XAI_API_KEY
+    stability  Stable Diffusion XL (v1 API)             STABILITY_API_KEY
+    gemini     gemini-2.5-flash-image                   GEMINI_API_KEY
+    local      deterministic template SVG → PNG         none (CI-safe; skips
+                                                        analyze/review)
+
+Claude never renders pixels itself (the Anthropic API has no image-generation
+endpoint); with no Claude credential the analyze/review stages degrade
+gracefully to the built-in template prompt with a warning — the renderer still
+runs. The SVG toolkit (sanitizer + rsvg/inkscape/magick/Playwright rasterizer
+chain) serves the zero-credential `local` provider.
+
+Configuration priority (per file):
+    author preview overrides (_data/authors.yml) > CLI args > environment
+    variables > _config.yml `preview_images:` > built-in defaults
 
 Usage:
-    python3 preview_generator.py --file path/to/post.md
-    python3 preview_generator.py --collection posts --dry-run
-    python3 preview_generator.py --list-missing
+    python3 scripts/lib/preview_generator.py --list-missing
+    python3 scripts/lib/preview_generator.py --dry-run --verbose
+    python3 scripts/lib/preview_generator.py --collection posts
+    python3 scripts/lib/preview_generator.py -f pages/_posts/my-post.md --force
+    python3 scripts/lib/preview_generator.py --provider local -f <file>
+    python3 scripts/lib/preview_generator.py --prompt-engine template --review none ...
 
-Dependencies:
-    pip install openai pyyaml requests pillow
+Dependencies: Python 3.9+ stdlib + PyYAML (`pip3 install pyyaml`). No other
+packages — HTTP goes through urllib, multipart bodies are hand-rolled.
 
-Environment Variables:
-    OPENAI_API_KEY - Required for OpenAI provider
-    STABILITY_API_KEY - Required for Stability AI provider
+Exit codes: 0 = success; 1 = validation failure or any per-file errors.
 """
 
 import argparse
+import base64
+import functools
+import io
 import json
 import os
 import re
-import sys
+import shutil
 import signal
-import time
+import subprocess
+import sys
 import threading
+import time
+import uuid
+import urllib.error
+import urllib.request
+import zlib
+import xml.etree.ElementTree as ET
 from concurrent.futures import ThreadPoolExecutor, as_completed
-from dataclasses import dataclass, field
-from datetime import datetime, timedelta
+from dataclasses import dataclass, field, replace
 from pathlib import Path
-from typing import Optional, List, Dict, Any, TextIO, Tuple
-import yaml
+from typing import Any, Dict, List, Optional, Tuple
 
-# Optional imports with fallback
 try:
-    import requests
-    HAS_REQUESTS = True
-except ImportError:
-    HAS_REQUESTS = False
+    import yaml
+except ImportError:  # checked in ensure_yaml() after --help handling
+    yaml = None
 
-try:
-    from openai import OpenAI
-    HAS_OPENAI = True
-except ImportError:
-    HAS_OPENAI = False
-
-
-def _load_dotenv():
-    """Load environment variables from .env file if present."""
-    # Search for .env in cwd and parent directories
-    search_dir = Path.cwd()
-    for _ in range(5):  # limit search depth
-        env_file = search_dir / '.env'
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+# Built-in fallbacks — used only when a key is absent from _config.yml, env,
+# and CLI. Mirrors the former Bash defaults; Claude orchestration (analysis +
+# review, ZER0-004) is on by default and degrades gracefully without a
+# Claude credential.
+DEFAULTS: Dict[str, Any] = {
+    "enabled": True,
+    "provider": "openai",
+    "model": "",  # empty → the active provider's default_model()
+    "size": "1536x1024",
+    "quality": "auto",
+    "style": (
+        "retro pixel art, 8-bit video game aesthetic, vibrant colors, "
+        "nostalgic, clean pixel graphics"
+    ),
+    "style_modifiers": (
+        "pixelated, retro gaming style, CRT screen glow effect, "
+        "limited color palette"
+    ),
+    "output_dir": "assets/images/previews",
+    "assets_prefix": "/assets",
+    "auto_prefix": True,
+    "collections": ["posts", "quickstart", "docs"],
+    "prompt_engine": "claude",   # claude analyzes the article; falls back to template
+    "review_engine": "claude",   # claude vision-reviews the render; `none` disables
+    "claude_model": "",          # empty → DEFAULT_CLAUDE_MODEL
+}
+
+# Enhance mode (OpenAI /v1/images/edits — see OpenAIProvider.edit)
+ENHANCE_DEFAULTS: Dict[str, str] = {
+    "model": "gpt-image-2",
+    "quality": "auto",
+    "fidelity": "high",
+    "format": "png",
+}
+DEFAULT_ENHANCE_PROMPT = (
+    "Improve this preview banner image: fix any misspelled, garbled, or "
+    "incorrect text so it reads clearly and accurately. Sharpen visual details "
+    "and improve composition while preserving the original art style, color "
+    "palette, and theme. Ensure the image is clean and professional."
+)
+
+# Anthropic wire constants — keep in sync with templates/deploy/chat-proxy/worker.js.
+ANTHROPIC_API_URL = "https://api.anthropic.com/v1/messages"
+ANTHROPIC_VERSION = "2023-06-01"
+OAUTH_BETA = "oauth-2025-04-20"
+# Claude Code OAuth tokens require the FIRST system block to identify as Claude
+# Code, otherwise the API rejects the call with a misleading `rate_limit_error`.
+CLAUDE_CODE_SYSTEM_PROMPT = "You are Claude Code, Anthropic's official CLI for Claude."
+DEFAULT_CLAUDE_MODEL = "claude-opus-4-8"
+CLAUDE_MAX_TOKENS = 16000  # non-streaming ceiling; SVG banners fit comfortably
+
+# Model-name prefix → provider family. Used to ignore a configured/author model
+# that belongs to a different vendor than the active provider (never send a
+# request that is guaranteed to 400).
+MODEL_FAMILIES: Dict[str, str] = {
+    "claude-": "claude",
+    "gpt-image-": "openai",
+    "dall-e-": "openai",
+    "grok-": "xai",
+    "stable-": "stability",
+    "sd3": "stability",
+    "gemini-": "gemini",
+    "imagen-": "gemini",
+}
+
+# Banner geometry for SVG-producing providers (claude, local).
+SVG_WIDTH, SVG_HEIGHT = 1536, 1024
+
+# Curated retro palettes: (sky/background, far, mid, near, accent, glow).
+# Selected deterministically per slug so re-runs stay visually stable.
+RETRO_PALETTES: List[List[str]] = [
+    ["#1a1a2e", "#16213e", "#0f3460", "#533483", "#e94560", "#f9ed69"],
+    ["#0d1b2a", "#1b263b", "#415a77", "#778da9", "#e0e1dd", "#ffb703"],
+    ["#2d132c", "#801336", "#c72c41", "#ee4540", "#f9d276", "#f4f4f4"],
+    ["#10002b", "#3c096c", "#7b2cbf", "#c77dff", "#e0aaff", "#72efdd"],
+    ["#001219", "#005f73", "#0a9396", "#94d2bd", "#e9d8a6", "#ee9b00"],
+    ["#03071e", "#370617", "#9d0208", "#dc2f02", "#f48c06", "#ffba08"],
+    ["#0b132b", "#1c2541", "#3a506b", "#5bc0be", "#6fffe9", "#ff6b6b"],
+    ["#232931", "#393e46", "#4ecca3", "#a5ecd7", "#eeeeee", "#f95959"],
+    ["#1f0a24", "#571089", "#ab51e3", "#f7aef8", "#b388eb", "#8093f1"],
+    ["#141e30", "#243b55", "#3c6382", "#82ccdd", "#f8c291", "#e55039"],
+]
+
+COMPOSITION_VARIANTS: List[str] = [
+    "a low horizon with a huge rising sun disk banded by scanlines",
+    "layered diagonal mountain silhouettes receding into haze",
+    "a vaporwave perspective grid floor vanishing toward the horizon",
+    "floating terraced islands with cascading pixel waterfalls",
+    "a night starfield with a large ringed planet arcing across the frame",
+    "a stepped city skyline of blocky towers with lit windows",
+    "rolling desert dunes with a lone monolith and long shadows",
+    "an ocean of chunky pixel waves under drifting square clouds",
+]
+
+# System prompt for Claude's ART-DIRECTOR role (prompt_engine: claude): read
+# the article, then write the brief a raster image model will render. NOTE:
+# "no text" matches the long-standing prompt rule of this feature — image
+# models garble lettering.
+ART_DIRECTOR_SYSTEM = """You are an art director for a technical blog. You will be given an article
+(title, description, tags, an excerpt) plus mandatory style directions. Your
+job is to design ONE preview banner image and describe it to an AI image
+model.
+
+Respond with ONLY the image-generation prompt — no preamble, no quotes, no
+markdown. One vivid paragraph of at most 130 words that:
+- captures the article's actual SUBJECT as a concrete visual metaphor or
+  scene (specific objects, actions and spatial arrangement — never a generic
+  'technology background');
+- specifies composition for a wide banner (what sits left/center/right,
+  foreground/background, focal point);
+- weaves in the given art style and palette directions verbatim in spirit;
+- states that the image must contain NO text, letters, words, numbers, logos
+  or UI copy of any kind."""
+
+# System prompt for Claude's REVIEWER role (review_engine: claude): look at
+# the rendered image and decide whether it represents the article.
+REVIEWER_SYSTEM = """You are reviewing an AI-generated blog preview banner against the article it
+illustrates. Judge three things: (1) does the image clearly evoke the
+article's actual subject, (2) does it follow the requested art style, and
+(3) is it free of text/lettering artifacts and visual glitches.
+
+Respond with ONLY a JSON object, no markdown fences:
+{"verdict": "approve" | "revise",
+ "critique": "<one or two sentences on what is wrong or right>",
+ "revised_prompt": "<empty when approving; otherwise a complete replacement
+image-generation prompt (max 130 words) that fixes the problems while keeping
+the required style and the no-text rule>"}
+
+Approve unless the image genuinely misrepresents the subject, breaks the
+style, or contains text/glitches — minor taste differences are not grounds
+for revision."""
+
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+
+# Pause after each successful non-dry generation (Bash parity: polite pacing
+# between paid API calls). Tests set this to 0.
+POST_GENERATION_SLEEP = 2.0
+
+
+# =============================================================================
+# Terminal output
+# =============================================================================
+
+class Colors:
+    RED = "\033[0;31m"
+    GREEN = "\033[0;32m"
+    YELLOW = "\033[1;33m"
+    BLUE = "\033[0;34m"
+    CYAN = "\033[0;36m"
+    PURPLE = "\033[0;35m"
+    BOLD = "\033[1m"
+    NC = "\033[0m"
+
+
+VERBOSE = False
+_log_file = None  # type: Optional[Any]
+
+_LEVEL_COLORS = {
+    "info": Colors.BLUE,
+    "step": Colors.CYAN,
+    "success": Colors.GREEN,
+    "warning": Colors.YELLOW,
+    "error": Colors.RED,
+    "debug": Colors.PURPLE,
+}
+
+
+def log(msg: str, level: str = "info") -> None:
+    color = _LEVEL_COLORS.get(level, Colors.NC)
+    stream = sys.stderr if level in ("warning", "error", "debug") else sys.stdout
+    print(f"{color}[{level.upper()}]{Colors.NC} {msg}", file=stream)
+    if _log_file:
+        stamp = time.strftime("%Y-%m-%d %H:%M:%S")
+        _log_file.write(f"{stamp} [{level.upper()}] {msg}\n")
+        _log_file.flush()
+
+
+def info(msg: str) -> None:
+    log(msg, "info")
+
+
+def step(msg: str) -> None:
+    log(msg, "step")
+
+
+def success(msg: str) -> None:
+    log(msg, "success")
+
+
+def warn(msg: str) -> None:
+    log(msg, "warning")
+
+
+def debug(msg: str) -> None:
+    if VERBOSE:
+        log(msg, "debug")
+
+
+def error_exit(msg: str) -> "NoReturn":  # noqa: F821 - typing.NoReturn (3.9 compat)
+    log(msg, "error")
+    sys.exit(1)
+
+
+def print_header(title: str) -> None:
+    line = "=" * 64
+    print(f"\n{Colors.CYAN}{line}{Colors.NC}")
+    print(f"  {Colors.GREEN}{title}{Colors.NC}")
+    print(f"{Colors.CYAN}{line}{Colors.NC}\n")
+
+
+# =============================================================================
+# Environment / interrupts
+# =============================================================================
+
+_interrupted = False
+
+
+def _signal_handler(signum, frame):  # noqa: ARG001
+    global _interrupted
+    _interrupted = True
+    print(f"\n{Colors.YELLOW}⚠️  Interrupt received. Finishing current tasks...{Colors.NC}")
+
+
+def _load_dotenv(start: Optional[Path] = None) -> None:
+    """Load .env from cwd (or `start`) up to 4 parents.
+
+    Non-empty exported env vars win over .env; an EMPTY env var is treated as
+    unset (docker/VS Code tasks forward `-e KEY=${env:KEY}` which materializes
+    empty strings that must not shadow a real value in .env).
+    """
+    search_dir = start or Path.cwd()
+    for _ in range(5):
+        env_file = search_dir / ".env"
         if env_file.is_file():
-            with open(env_file) as f:
-                for line in f:
+            try:
+                for line in env_file.read_text(encoding="utf-8").splitlines():
                     line = line.strip()
-                    if not line or line.startswith('#'):
+                    if not line or line.startswith("#") or "=" not in line:
                         continue
-                    if '=' in line:
-                        key, _, value = line.partition('=')
-                        key = key.strip()
-                        value = value.strip().strip('"').strip("'")
-                        if key and key not in os.environ:
-                            os.environ[key] = value
+                    key, _, value = line.partition("=")
+                    key = key.strip()
+                    value = value.strip()
+                    if value[:1] in ("'", '"') and value[-1:] == value[:1]:
+                        value = value[1:-1]  # matched surrounding quotes
+                    else:
+                        value = value.split(" #", 1)[0].rstrip()  # inline comment
+                    if key and not os.environ.get(key):
+                        os.environ[key] = value
+            except OSError:
+                pass
             return
-        parent = search_dir.parent
-        if parent == search_dir:
+        if search_dir.parent == search_dir:
             break
-        search_dir = parent
+        search_dir = search_dir.parent
 
-_load_dotenv()
 
+def ensure_yaml() -> None:
+    if yaml is None:
+        error_exit(
+            "PyYAML is required (front matter, _config.yml and _data/authors.yml "
+            "parsing). Install it with ONE of:\n"
+            "    pip3 install pyyaml\n"
+            "    python3 -m pip install --user pyyaml\n"
+            "    docker-compose exec jekyll pip3 install --break-system-packages pyyaml"
+        )
 
-# Global state for interrupt handling
-_interrupted = False
-_log_file: Optional[TextIO] = None
 
+# =============================================================================
+# HTTP layer (urllib only — no third-party HTTP deps)
+# =============================================================================
 
-def _signal_handler(signum, frame):
-    """Handle interrupt signals gracefully."""
-    global _interrupted
-    _interrupted = True
-    print(f"\n{Colors.YELLOW}⚠️  Interrupt received. Finishing current tasks...{Colors.NC}")
+class HttpStatusError(Exception):
+    """Non-2xx HTTP response, with parsed body + headers when possible."""
 
+    def __init__(self, status: int, body: bytes, url: str,
+                 headers: Optional[Dict[str, str]] = None):
+        self.status = status
+        self.body = body
+        self.url = url
+        self.headers = {k.lower(): v for k, v in (headers or {}).items()}
+        super().__init__(f"HTTP {status} from {url}: {self.message()[:300]}")
 
-class RateLimiter:
-    """Token bucket rate limiter for API calls."""
-    
-    def __init__(self, requests_per_minute: int = 5):
-        self.requests_per_minute = requests_per_minute
-        self.min_interval = 60.0 / requests_per_minute
-        self.lock = threading.Lock()
-        self.last_request_time = 0.0
-        self.request_count = 0
-        self.window_start = time.time()
-    
-    def acquire(self) -> float:
-        """Acquire permission to make a request. Returns time waited."""
-        with self.lock:
-            now = time.time()
-            if now - self.window_start >= 60.0:
-                self.window_start = now
-                self.request_count = 0
-            if self.request_count >= self.requests_per_minute:
-                wait_time = 60.0 - (now - self.window_start)
-                if wait_time > 0:
-                    time.sleep(wait_time)
-                    self.window_start = time.time()
-                    self.request_count = 0
-                    return wait_time
-            elapsed = now - self.last_request_time
-            if elapsed < self.min_interval:
-                wait_time = self.min_interval - elapsed
-                time.sleep(wait_time)
-            else:
-                wait_time = 0
-            self.last_request_time = time.time()
-            self.request_count += 1
-            return wait_time
+    def retry_after(self) -> float:
+        """Server-requested backoff: the Retry-After header (what Anthropic/
+        OpenAI/xAI actually send on 429), falling back to a JSON body field."""
+        try:
+            header = self.headers.get("retry-after")
+            if header:
+                return float(header)
+        except (TypeError, ValueError):
+            pass
+        data = self.json()
+        if isinstance(data, dict):
+            try:
+                return float(data.get("retry_after", 0) or 0)
+            except (TypeError, ValueError):
+                pass
+        return 0.0
+
+    def json(self) -> Optional[dict]:
+        try:
+            return json.loads(self.body.decode("utf-8", "replace"))
+        except (ValueError, UnicodeDecodeError):
+            return None
+
+    def message(self) -> str:
+        data = self.json()
+        if isinstance(data, dict):
+            err = data.get("error")
+            if isinstance(err, dict) and err.get("message"):
+                return str(err["message"])
+            if isinstance(err, str):
+                return err
+            if data.get("detail"):
+                return str(data["detail"])
+        return self.body.decode("utf-8", "replace")[:500]
+
+
+def http_request(
+    url: str,
+    method: str = "GET",
+    headers: Optional[Dict[str, str]] = None,
+    data: Optional[bytes] = None,
+    timeout: int = 120,
+) -> Tuple[int, Dict[str, str], bytes]:
+    req = urllib.request.Request(url, data=data, method=method)
+    for key, value in (headers or {}).items():
+        req.add_header(key, value)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return resp.status, dict(resp.headers.items()), resp.read()
+    except urllib.error.HTTPError as exc:
+        body = exc.read() if exc.fp else b""
+        raise HttpStatusError(exc.code, body, url,
+                              dict(exc.headers.items()) if exc.headers else None) from None
+
+
+def http_json(
+    url: str, payload: dict, headers: Dict[str, str], timeout: int = 900
+) -> dict:
+    body = json.dumps(payload).encode("utf-8")
+    hdrs = {"Content-Type": "application/json", **headers}
+    _, _, raw = http_request(url, "POST", hdrs, body, timeout)
+    return json.loads(raw.decode("utf-8"))
+
+
+def build_multipart(
+    fields: Dict[str, str], files: List[Tuple[str, str, bytes, str]]
+) -> Tuple[bytes, str]:
+    """Encode multipart/form-data. files: (field, filename, content, mime)."""
+    boundary = f"----zer0-{uuid.uuid4().hex}"
+    buf = io.BytesIO()
+    for name, value in fields.items():
+        buf.write(f"--{boundary}\r\n".encode())
+        buf.write(f'Content-Disposition: form-data; name="{name}"\r\n\r\n'.encode())
+        buf.write(str(value).encode("utf-8"))
+        buf.write(b"\r\n")
+    for name, filename, content, mime in files:
+        buf.write(f"--{boundary}\r\n".encode())
+        buf.write(
+            f'Content-Disposition: form-data; name="{name}"; filename="{filename}"\r\n'.encode()
+        )
+        buf.write(f"Content-Type: {mime}\r\n\r\n".encode())
+        buf.write(content)
+        buf.write(b"\r\n")
+    buf.write(f"--{boundary}--\r\n".encode())
+    return buf.getvalue(), f"multipart/form-data; boundary={boundary}"
+
+
+def http_multipart(
+    url: str,
+    fields: Dict[str, str],
+    files: List[Tuple[str, str, bytes, str]],
+    headers: Dict[str, str],
+    timeout: int = 900,
+) -> dict:
+    body, content_type = build_multipart(fields, files)
+    hdrs = {"Content-Type": content_type, **headers}
+    _, _, raw = http_request(url, "POST", hdrs, body, timeout)
+    return json.loads(raw.decode("utf-8"))
+
+
+def download_to(url: str, dest: Path, timeout: int = 120) -> None:
+    _, _, raw = http_request(url, "GET", {}, None, timeout)
+    dest.write_bytes(raw)
+
+
+RETRYABLE_STATUSES = {429, 500, 502, 503, 529}
+
+
+def with_retries(fn, what: str, attempts: int = 4):
+    """Run fn(); retry transport errors and retryable HTTP statuses.
+
+    Backoff 2s/4s/8s (or the server's Retry-After when larger, capped 60s).
+    """
+    delay = 2.0
+    for attempt in range(1, attempts + 1):
+        try:
+            return fn()
+        except HttpStatusError as exc:
+            if exc.status not in RETRYABLE_STATUSES or attempt == attempts:
+                raise
+            wait = min(max(delay, exc.retry_after()), 60.0)
+            warn(f"{what}: HTTP {exc.status}, retrying in {wait:.0f}s "
+                 f"(attempt {attempt}/{attempts})")
+        except (urllib.error.URLError, TimeoutError, ConnectionError, OSError) as exc:
+            if attempt == attempts:
+                raise
+            wait = delay
+            warn(f"{what}: {exc.__class__.__name__}: {exc}; retrying in {wait:.0f}s "
+                 f"(attempt {attempt}/{attempts})")
+        time.sleep(wait)
+        delay *= 2
+
+
+# =============================================================================
+# Config layer
+# =============================================================================
+
+def find_project_root() -> Path:
+    """Repo root: scripts/lib/<this file> → two parents up; else walk from cwd."""
+    script_root = Path(__file__).resolve().parent.parent.parent
+    if (script_root / "_config.yml").is_file():
+        return script_root
+    probe = Path.cwd()
+    for _ in range(6):
+        if (probe / "_config.yml").is_file():
+            return probe
+        if probe.parent == probe:
+            break
+        probe = probe.parent
+    return script_root
+
+
+def load_yaml_file(path: Path) -> Dict[str, Any]:
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else {}
+    except FileNotFoundError:
+        return {}
+    except Exception as exc:  # malformed YAML must not kill the whole run
+        warn(f"Could not parse {path.name}: {exc}")
+        return {}
+
+
+def read_site_config(project_root: Path) -> Dict[str, Any]:
+    cfg = load_yaml_file(project_root / "_config.yml").get("preview_images")
+    return cfg if isinstance(cfg, dict) else {}
+
+
+def read_authors(project_root: Path) -> Dict[str, Any]:
+    return load_yaml_file(project_root / "_data" / "authors.yml")
+
+
+def author_preview_overrides(authors: Dict[str, Any], author_key: Any) -> Dict[str, str]:
+    """`preview:` override block for an author key (style/style_modifiers/size/
+    quality/model). `author:` may be a list or mapping in some posts — only a
+    plain string key can index authors.yml; anything else has no override."""
+    if not isinstance(author_key, str) or not author_key:
+        return {}
+    author = authors.get(author_key)
+    if not isinstance(author, dict):
+        return {}
+    preview = author.get("preview")
+    if not isinstance(preview, dict):
+        return {}
+    return {
+        key: str(value).strip()
+        for key, value in preview.items()
+        if key in ("style", "style_modifiers", "size", "quality", "model")
+        and value is not None and str(value).strip()
+    }
+
+
+def _env_flag(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() == "true"
 
 
+@dataclass
+class Settings:
+    """Fully-resolved run settings (before per-file author overrides)."""
+
+    provider: str = DEFAULTS["provider"]
+    model: str = DEFAULTS["model"]
+    size: str = DEFAULTS["size"]
+    quality: str = DEFAULTS["quality"]
+    style: str = DEFAULTS["style"]
+    style_modifiers: str = DEFAULTS["style_modifiers"]
+    output_dir: str = DEFAULTS["output_dir"]
+    assets_prefix: str = DEFAULTS["assets_prefix"]
+    auto_prefix: bool = DEFAULTS["auto_prefix"]
+    enabled: bool = True
+    collections: List[str] = field(default_factory=lambda: list(DEFAULTS["collections"]))
+    prompt_engine: str = DEFAULTS["prompt_engine"]
+    review_engine: str = DEFAULTS["review_engine"]
+    claude_model: str = DEFAULTS["claude_model"]
+
+    dry_run: bool = False
+    verbose: bool = False
+    force: bool = False
+    list_only: bool = False
+    parallel: int = 4
+    batch: int = 0
+
+    file: str = ""
+    collection: str = ""
+
+    enhance: bool = False
+    enhance_prompt: str = ""
+    enhance_model: str = ENHANCE_DEFAULTS["model"]
+    enhance_quality: str = ENHANCE_DEFAULTS["quality"]
+    enhance_fidelity: str = ENHANCE_DEFAULTS["fidelity"]
+    enhance_format: str = ENHANCE_DEFAULTS["format"]
+
+    rasterizer: str = "auto"
+    provider_explicit: bool = False
+
+
+def resolve_settings(args: argparse.Namespace, site: Dict[str, Any]) -> Settings:
+    """Merge CLI > env > _config.yml > DEFAULTS into a Settings object."""
+
+    def cfg(key: str, default: Any) -> Any:
+        value = site.get(key)
+        return default if value is None else value
+
+    def pick(cli_value: Optional[str], env_name: str, cfg_key: str) -> str:
+        if cli_value is not None:
+            return cli_value
+        env_value = os.environ.get(env_name)
+        if env_value:
+            return env_value
+        return str(cfg(cfg_key, DEFAULTS[cfg_key]))
+
+    collections = cfg("collections", DEFAULTS["collections"])
+    if not isinstance(collections, list) or not collections:
+        collections = list(DEFAULTS["collections"])
+
+    parallel_env = os.environ.get("MAX_PARALLEL", "")
+    parallel = args.parallel if args.parallel is not None else (
+        int(parallel_env) if parallel_env.isdigit() else 4
+    )
+
+    settings = Settings(
+        provider=pick(args.provider, "AI_PROVIDER", "provider"),
+        model=pick(args.model, "IMAGE_MODEL", "model"),
+        size=pick(None, "IMAGE_SIZE", "size"),
+        quality=pick(None, "IMAGE_QUALITY", "quality"),
+        style=pick(args.style, "IMAGE_STYLE", "style"),
+        style_modifiers=pick(None, "IMAGE_STYLE_MODIFIERS", "style_modifiers"),
+        output_dir=pick(args.output_dir, "OUTPUT_DIR", "output_dir"),
+        assets_prefix=(
+            args.assets_prefix if args.assets_prefix is not None
+            else str(cfg("assets_prefix", DEFAULTS["assets_prefix"]))
+        ),
+        auto_prefix=(
+            False if args.no_auto_prefix
+            else bool(cfg("auto_prefix", DEFAULTS["auto_prefix"]))
+        ),
+        enabled=bool(cfg("enabled", True)),
+        collections=[str(c) for c in collections],
+        prompt_engine=pick(args.prompt_engine, "PROMPT_ENGINE", "prompt_engine"),
+        review_engine=pick(args.review, "REVIEW_ENGINE", "review_engine"),
+        claude_model=str(cfg("claude_model", "") or ""),
+        dry_run=args.dry_run or _env_flag("DRY_RUN"),
+        verbose=args.verbose or _env_flag("VERBOSE"),
+        force=args.force or _env_flag("FORCE"),
+        list_only=args.list_missing or _env_flag("LIST_ONLY"),
+        parallel=parallel,
+        batch=args.batch or 0,
+        file=args.file or "",
+        collection=args.collection or "",
+        enhance=args.enhance or _env_flag("ENHANCE"),
+        enhance_prompt=args.enhance_prompt or "",
+        enhance_model=(
+            args.enhance_model or os.environ.get("ENHANCE_MODEL")
+            or ENHANCE_DEFAULTS["model"]
+        ),
+        enhance_quality=(
+            args.enhance_quality or os.environ.get("ENHANCE_QUALITY")
+            or ENHANCE_DEFAULTS["quality"]
+        ),
+        enhance_fidelity=(
+            args.enhance_fidelity or os.environ.get("ENHANCE_FIDELITY")
+            or ENHANCE_DEFAULTS["fidelity"]
+        ),
+        enhance_format=(
+            args.enhance_format or os.environ.get("ENHANCE_FORMAT")
+            or ENHANCE_DEFAULTS["format"]
+        ),
+        rasterizer=args.rasterizer or "auto",
+        provider_explicit=args.provider is not None or bool(os.environ.get("AI_PROVIDER")),
+    )
+    return settings
+
+
+def apply_author_overrides(settings: Settings, overrides: Dict[str, str]) -> Settings:
+    """Per-file settings copy with the author's preview block applied on top."""
+    if not overrides:
+        return settings
+    return replace(
+        settings,
+        style=overrides.get("style", settings.style),
+        style_modifiers=overrides.get("style_modifiers", settings.style_modifiers),
+        size=overrides.get("size", settings.size),
+        quality=overrides.get("quality", settings.quality),
+        model=overrides.get("model", settings.model),
+    )
+
+
+def model_family(model: str) -> Optional[str]:
+    m = (model or "").strip().lower()
+    for prefix, family in MODEL_FAMILIES.items():
+        if m.startswith(prefix):
+            return family
+    return None
+
+
+def effective_model(settings: Settings, provider: "Provider") -> str:
+    """Configured model when it belongs to the provider's family, else the
+    provider default (with a warning) — never emit a guaranteed-400 request."""
+    model = (settings.model or "").strip()
+    if not model:
+        return provider.default_model()
+    family = model_family(model)
+    if family is not None and family != provider.name:
+        warn(
+            f"Model '{model}' belongs to the '{family}' family; using "
+            f"{provider.name} default '{provider.default_model()}' instead"
+        )
+        return provider.default_model()
+    return model
+
+
+# =============================================================================
+# Front-matter layer
+# =============================================================================
+
 @dataclass
 class ContentFile:
-    """Represents a Jekyll content file with its metadata."""
     path: Path
     title: str
     description: str
-    categories: List[str]
-    tags: List[str]
+    categories: str
     preview: Optional[str]
+    author: Any
     content: str
     front_matter: Dict[str, Any]
 
 
-@dataclass
-class GenerationResult:
-    """Result of an image generation attempt."""
-    success: bool
-    image_path: Optional[str]
-    preview_url: Optional[str]
-    error: Optional[str]
-    prompt_used: Optional[str]
-    duration: float = 0.0
-    file_path: Optional[Path] = None
-
-
-class ThreadSafeStats:
-    """Thread-safe progress statistics."""
-    
-    def __init__(self):
-        self.lock = threading.Lock()
-        self._total_files: int = 0
-        self._current_index: int = 0
-        self._processed: int = 0
-        self._generated: int = 0
-        self._skipped: int = 0
-        self._errors: int = 0
-        self._start_time: float = time.time()
-        self._generation_times: List[float] = []
-        self._active_workers: int = 0
-        self._pending_files: List[str] = []
-    
-    @property
-    def total_files(self) -> int:
-        with self.lock:
-            return self._total_files
-    
-    @total_files.setter
-    def total_files(self, value: int):
-        with self.lock:
-            self._total_files = value
-    
-    @property
-    def current_index(self) -> int:
-        with self.lock:
-            return self._current_index
-    
-    @current_index.setter
-    def current_index(self, value: int):
-        with self.lock:
-            self._current_index = value
-    
-    @property
-    def processed(self) -> int:
-        with self.lock:
-            return self._processed
-    
-    @property
-    def generated(self) -> int:
-        with self.lock:
-            return self._generated
-    
-    @property
-    def skipped(self) -> int:
-        with self.lock:
-            return self._skipped
-    
-    @property
-    def errors(self) -> int:
-        with self.lock:
-            return self._errors
-    
-    @property
-    def active_workers(self) -> int:
-        with self.lock:
-            return self._active_workers
-    
-    def increment_processed(self):
-        with self.lock:
-            self._processed += 1
-            self._current_index += 1
-    
-    def increment_generated(self):
-        with self.lock:
-            self._generated += 1
-    
-    def increment_skipped(self):
-        with self.lock:
-            self._skipped += 1
-    
-    def increment_errors(self):
-        with self.lock:
-            self._errors += 1
-    
-    def add_generation_time(self, duration: float):
-        with self.lock:
-            self._generation_times.append(duration)
-    
-    def set_active_workers(self, count: int):
-        with self.lock:
-            self._active_workers = count
-    
-    def add_pending_file(self, filename: str):
-        with self.lock:
-            self._pending_files.append(filename)
-    
-    def remove_pending_file(self, filename: str):
-        with self.lock:
-            if filename in self._pending_files:
-                self._pending_files.remove(filename)
-    
-    def get_pending_files(self) -> List[str]:
-        with self.lock:
-            return self._pending_files.copy()
-    
-    @property
-    def elapsed(self) -> float:
-        return time.time() - self._start_time
-    
-    @property
-    def elapsed_str(self) -> str:
-        return str(timedelta(seconds=int(self.elapsed)))
-    
-    @property
-    def avg_generation_time(self) -> float:
-        with self.lock:
-            if not self._generation_times:
-                return 25.0
-            return sum(self._generation_times) / len(self._generation_times)
-    
-    @property
-    def generation_times(self) -> List[float]:
-        with self.lock:
-            return self._generation_times.copy()
-    
-    @property
-    def estimated_remaining(self) -> float:
-        with self.lock:
-            remaining = self._total_files - self._current_index
-            return remaining * self.avg_generation_time
-    
-    @property
-    def eta_str(self) -> str:
-        with self.lock:
-            if self._total_files == 0:
-                return "unknown"
-            return str(timedelta(seconds=int(self.estimated_remaining)))
-    
-    @property
-    def percentage(self) -> float:
-        with self.lock:
-            if self._total_files == 0:
-                return 0.0
-            return (self._current_index / self._total_files) * 100
+_FM_OPEN = re.compile(r"\A---[ \t]*\r?\n")
 
 
-@dataclass
-class ProgressStats:
-    """Track progress statistics (legacy, non-thread-safe)."""
-    total_files: int = 0
-    current_index: int = 0
-    processed: int = 0
-    generated: int = 0
-    skipped: int = 0
-    errors: int = 0
-    start_time: float = field(default_factory=time.time)
-    generation_times: List[float] = field(default_factory=list)
-    
-    @property
-    def elapsed(self) -> float:
-        return time.time() - self.start_time
-    
-    @property
-    def elapsed_str(self) -> str:
-        return str(timedelta(seconds=int(self.elapsed)))
-    
-    @property
-    def avg_generation_time(self) -> float:
-        if not self.generation_times:
-            return 25.0
-        return sum(self.generation_times) / len(self.generation_times)
-    
-    @property
-    def estimated_remaining(self) -> float:
-        remaining = self.total_files - self.current_index
-        return remaining * self.avg_generation_time
-    
-    @property
-    def eta_str(self) -> str:
-        if self.total_files == 0:
-            return "unknown"
-        return str(timedelta(seconds=int(self.estimated_remaining)))
-    
-    @property
-    def percentage(self) -> float:
-        if self.total_files == 0:
-            return 0.0
-        return (self.current_index / self.total_files) * 100
+def split_front_matter(text: str) -> Optional[Tuple[int, int, str]]:
+    """Return (fm_start, fm_end, fm_text) — offsets of the raw front-matter
+    body between the opening and closing `---` fences — or None."""
+    open_match = _FM_OPEN.match(text)
+    if not open_match:
+        return None
+    fm_start = open_match.end()
+    close = re.compile(r"^---[ \t]*\r?$", re.M).search(text, fm_start)
+    if not close:
+        return None
+    return fm_start, close.start(), text[fm_start:close.start()]
 
 
-class Colors:
-    """Terminal colors for output."""
-    RED = '\033[0;31m'
-    GREEN = '\033[0;32m'
-    YELLOW = '\033[1;33m'
-    BLUE = '\033[0;34m'
-    CYAN = '\033[0;36m'
-    PURPLE = '\033[0;35m'
-    BOLD = '\033[1m'
-    DIM = '\033[2m'
-    NC = '\033[0m'  # No Color
-
-
-class Spinner:
-    """Simple spinner for showing activity during long operations."""
-    
-    FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
-    
-    def __init__(self, message: str = ""):
-        self.message = message
-        self.running = False
-        self.thread: Optional[threading.Thread] = None
-        self.frame_idx = 0
-        self.start_time = 0.0
-    
-    def _spin(self):
-        while self.running:
-            elapsed = int(time.time() - self.start_time)
-            frame = self.FRAMES[self.frame_idx % len(self.FRAMES)]
-            sys.stdout.write(f"\r{Colors.CYAN}{frame}{Colors.NC} {self.message} ({elapsed}s)...")
-            sys.stdout.flush()
-            self.frame_idx += 1
-            time.sleep(0.1)
-    
-    def start(self, message: str = None):
-        if message:
-            self.message = message
-        self.running = True
-        self.start_time = time.time()
-        self.thread = threading.Thread(target=self._spin, daemon=True)
-        self.thread.start()
-    
-    def stop(self, success: bool = True):
-        self.running = False
-        if self.thread:
-            self.thread.join(timeout=0.2)
-        elapsed = time.time() - self.start_time
-        sys.stdout.write('\r' + ' ' * 80 + '\r')
-        sys.stdout.flush()
-        return elapsed
-
-
-def log(msg: str, level: str = "info", to_file: bool = True):
-    """Print formatted log message."""
-    global _log_file
-    
-    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-    
-    colors = {
-        "info": Colors.BLUE,
-        "success": Colors.GREEN,
-        "warning": Colors.YELLOW,
-        "error": Colors.RED,
-        "debug": Colors.PURPLE,
-        "step": Colors.CYAN,
-        "progress": Colors.BOLD,
-    }
-    color = colors.get(level, Colors.NC)
-    prefix = f"[{level.upper()}]"
-    print(f"{color}{prefix}{Colors.NC} {msg}")
-    
-    if to_file and _log_file:
-        _log_file.write(f"{timestamp} {prefix} {msg}\n")
-        _log_file.flush()
+def parse_front_matter(path: Path) -> Optional[ContentFile]:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        warn(f"Failed to read {path}: {exc}")
+        return None
 
+    parts = split_front_matter(text)
+    if not parts:
+        debug(f"No front matter found in: {path}")
+        return None
+    fm_start, fm_end = parts[0], parts[1]
 
-def log_progress(current: int, total: int, title: str, stats):
-    """Print progress bar and statistics."""
-    bar_width = 30
-    filled = int(bar_width * current / total) if total > 0 else 0
-    bar = '█' * filled + '░' * (bar_width - filled)
-    
-    max_title_len = 40
-    display_title = title[:max_title_len-3] + "..." if len(title) > max_title_len else title
-    
-    print(f"\n{Colors.CYAN}{'─' * 70}{Colors.NC}")
-    print(f"{Colors.BOLD}📊 Progress: [{bar}] {current}/{total} ({stats.percentage:.1f}%){Colors.NC}")
-    print(f"   {Colors.DIM}Elapsed: {stats.elapsed_str} | ETA: {stats.eta_str} | Avg: {stats.avg_generation_time:.1f}s/image{Colors.NC}")
-    print(f"   ✅ Generated: {stats.generated} | ⏭️  Skipped: {stats.skipped} | ❌ Errors: {stats.errors}")
-    print(f"{Colors.CYAN}{'─' * 70}{Colors.NC}")
-    print(f"📁 Processing: {display_title}")
-
-
-class PreviewGenerator:
-    """AI-powered preview image generator for Jekyll content."""
-    
-    def __init__(
-        self,
-        project_root: Path,
-        provider: str = "openai",
-        output_dir: str = "assets/images/previews",
-        image_style: str = "digital art, professional blog illustration",
-        image_size: str = "1024x1024",
-        assets_prefix: str = "/assets",
-        auto_prefix: bool = True,
-        dry_run: bool = False,
-        verbose: bool = False,
-        force: bool = False,
-        batch_limit: int = 0,
-        workers: int = 1,
-        rate_limit: int = 5,
-    ):
-        self.project_root = project_root
-        self.provider = provider
-        self.output_dir = project_root / output_dir
-        self.image_style = image_style
-        self.image_size = image_size
-        self.assets_prefix = assets_prefix
-        self.auto_prefix = auto_prefix
-        self.dry_run = dry_run
-        self.verbose = verbose
-        self.force = force
-        self.batch_limit = batch_limit
-        self.workers = workers
-        self.rate_limit = rate_limit
-        
-        # Progress tracking - use thread-safe stats for parallel processing
-        if workers > 1:
-            self.stats = ThreadSafeStats()
-        else:
-            self.stats = ProgressStats()
-        self.spinner = Spinner()
-        
-        # Rate limiter for API calls
-        self.rate_limiter = RateLimiter(requests_per_minute=rate_limit)
-
-        # Author data (for per-author art-style overrides). Loaded once and read
-        # (never mutated) per file, so it is safe to share across worker threads.
-        self.authors = self._load_authors()
-
-        # Ensure output directory exists
-        if not dry_run:
-            self.output_dir.mkdir(parents=True, exist_ok=True)
-
-    def _load_authors(self) -> Dict[str, Any]:
-        """Load _data/authors.yml so posts can override the art style per author."""
-        authors_file = self.project_root / '_data' / 'authors.yml'
-        try:
-            data = yaml.safe_load(authors_file.read_text(encoding='utf-8'))
-            return data if isinstance(data, dict) else {}
-        except Exception:
-            return {}
+    try:
+        data = yaml.safe_load(parts[2])
+    except yaml.YAMLError as exc:
+        warn(f"Failed to parse YAML in {path}: {exc}")
+        return None
+    if not isinstance(data, dict):
+        return None
 
-    def author_preview_overrides(self, author_key: Optional[str]) -> Dict[str, Any]:
-        """Return the `preview:` override block for an author key (or {}).
+    categories = data.get("categories", [])
+    if isinstance(categories, str):
+        categories = [categories]
+    if not isinstance(categories, list):
+        categories = []
 
-        A post whose `author:` references an entry in _data/authors.yml that
-        carries a `preview:` block gets that block's settings — they win over the
-        site-wide style for that post's banner (e.g. AI personas cassandra/vega).
-        """
-        # Jekyll allows `author:` as a string, a list (multi-author), or a mapping
-        # (jekyll-seo-tag E-E-A-T). Only a hashable string can index authors.yml;
-        # anything else simply has no per-author override (and must not crash the
-        # run — keeping this path as resilient as the rest of the file).
-        if not isinstance(author_key, str) or not author_key:
-            return {}
-        author = self.authors.get(author_key)
-        if not isinstance(author, dict):
-            return {}
-        preview = author.get('preview')
-        return preview if isinstance(preview, dict) else {}
-    
-    def debug(self, msg: str):
-        """Print debug message if verbose mode is enabled."""
-        if self.verbose:
-            log(msg, "debug")
-    
-    def normalize_preview_path(self, preview_path: Optional[str]) -> Optional[str]:
-        """Normalize a preview path by adding assets_prefix if needed.
-        
-        This allows users to omit the /assets/ prefix in frontmatter:
-        - /images/previews/my-image.png -> /assets/images/previews/my-image.png
-        - /assets/images/previews/my-image.png -> unchanged
-        - https://example.com/image.png -> unchanged (external URL)
-        """
-        if not preview_path:
-            return preview_path
-        
-        # External URLs pass through unchanged
-        if preview_path.startswith('http://') or preview_path.startswith('https://'):
-            return preview_path
-        
-        # If auto_prefix is enabled and path doesn't contain assets_prefix
-        if self.auto_prefix and self.assets_prefix not in preview_path:
-            return f"{self.assets_prefix}{preview_path}"
-        
-        return preview_path
-    
-    def parse_front_matter(self, file_path: Path) -> Optional[ContentFile]:
-        """Parse front matter and content from a markdown file."""
-        try:
-            content = file_path.read_text(encoding='utf-8')
-        except Exception as e:
-            log(f"Failed to read {file_path}: {e}", "error")
-            return None
-        
-        # Extract front matter
-        fm_match = re.match(r'^---\s*\n(.*?)\n---\s*\n(.*)$', content, re.DOTALL)
-        if not fm_match:
-            self.debug(f"No front matter found in: {file_path}")
-            return None
-        
-        try:
-            front_matter = yaml.safe_load(fm_match.group(1))
-            post_content = fm_match.group(2)
-        except yaml.YAMLError as e:
-            log(f"Failed to parse YAML in {file_path}: {e}", "error")
-            return None
-        
-        if not front_matter:
-            return None
-        
-        # Extract fields with defaults
-        categories = front_matter.get('categories', [])
-        if isinstance(categories, str):
-            categories = [categories]
-        
-        tags = front_matter.get('tags', [])
-        if isinstance(tags, str):
-            tags = [tags]
-        
-        return ContentFile(
-            path=file_path,
-            title=front_matter.get('title', ''),
-            description=front_matter.get('description', ''),
-            categories=categories,
-            tags=tags,
-            preview=front_matter.get('preview'),
-            content=post_content,
-            front_matter=front_matter,
+    body_start = text.find("\n", fm_end)
+    body = text[body_start + 1:] if body_start != -1 else ""
+
+    return ContentFile(
+        path=path,
+        title=str(data.get("title") or ""),
+        description=str(data.get("description") or ""),
+        categories=", ".join(str(c) for c in categories),
+        preview=data.get("preview") if isinstance(data.get("preview"), str) else None,
+        author=data.get("author"),
+        content=body,
+        front_matter=data,
+    )
+
+
+def update_front_matter(path: Path, preview_path: str, dry_run: bool = False) -> bool:
+    """Set `preview:` inside the front-matter block ONLY (first match).
+
+    Replaces an existing `preview:` line, else inserts after the first
+    `description:` line, else after the first `title:` line. Everything outside
+    the front-matter block is preserved byte-for-byte (the former sed/regex
+    implementations operated file-wide and could corrupt body lines that start
+    with `preview:`). Writes a transient `.bak`, replaces atomically, removes
+    the `.bak` on success.
+    """
+    if dry_run:
+        info(f"[DRY RUN] Would update preview in {path} to: {preview_path}")
+        return True
+
+    try:
+        # Bytes round-trip: Path.read_text() would translate CRLF → LF.
+        text = path.read_bytes().decode("utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        warn(f"Failed to read {path}: {exc}")
+        return False
+
+    parts = split_front_matter(text)
+    if not parts:
+        warn(f"No front matter block in {path}; not updating")
+        return False
+    fm_start, fm_end, fm_text = parts
+
+    eol = "\r\n" if "\r\n" in fm_text else "\n"
+    lines = fm_text.splitlines(keepends=True)
+
+    def find_key(prefix: str) -> int:
+        for idx, line in enumerate(lines):
+            if line.startswith(prefix):
+                return idx
+        return -1
+
+    def end_of_block(idx: int) -> int:
+        """Index just past a key line and any indented continuation lines
+        (folded/literal scalars, nested maps)."""
+        j = idx + 1
+        while j < len(lines) and (lines[j].startswith((" ", "\t"))
+                                  or lines[j].strip() == ""):
+            # A blank line only continues the block if an indented line follows.
+            if lines[j].strip() == "" and not (
+                j + 1 < len(lines) and lines[j + 1].startswith((" ", "\t"))
+            ):
+                break
+            j += 1
+        return j
+
+    preview_idx = find_key("preview:")
+    if preview_idx != -1:
+        line_eol = "\r\n" if lines[preview_idx].endswith("\r\n") else (
+            "\n" if lines[preview_idx].endswith("\n") else ""
         )
-    
-    def check_preview_exists(self, preview_path: Optional[str]) -> bool:
-        """Check if the preview image file exists."""
-        if not preview_path:
-            return False
-        
-        # Normalize the path first (adds assets_prefix if needed)
-        normalized_path = self.normalize_preview_path(preview_path)
-        if not normalized_path:
+        lines[preview_idx] = f"preview: {preview_path}{line_eol}"
+    else:
+        anchor = find_key("description:")
+        if anchor == -1:
+            anchor = find_key("title:")
+        if anchor == -1:
+            warn(f"No preview:/description:/title: anchor in {path} front matter")
             return False
-        
-        # Handle absolute and relative paths
-        clean_path = normalized_path.lstrip('/')
-        
-        # Check direct path
-        full_path = self.project_root / clean_path
-        if full_path.exists():
-            return True
-        
+        insert_at = end_of_block(anchor)
+        if not lines[anchor].endswith("\n") and insert_at == anchor + 1:
+            lines[anchor] += eol  # anchor was the final unterminated line
+        lines.insert(insert_at, f"preview: {preview_path}{eol}")
+
+    new_text = text[:fm_start] + "".join(lines) + text[fm_end:]
+
+    backup = path.with_name(path.name + ".bak")
+    tmp = path.with_name(path.name + ".tmp~")
+    try:
+        shutil.copy2(path, backup)
+        tmp.write_bytes(new_text.encode("utf-8"))
+        os.replace(tmp, path)
+        backup.unlink(missing_ok=True)
+    except OSError as exc:
+        warn(f"Failed to update front matter in {path}: {exc}")
+        tmp.unlink(missing_ok=True)
         return False
-    
-    def generate_prompt(self, content: ContentFile) -> str:
-        """Generate an AI prompt from content metadata."""
-        prompt_parts = [
-            f"Create a professional blog preview image for an article titled '{content.title}'."
-        ]
-        
-        if content.description:
-            prompt_parts.append(f"The article is about: {content.description}.")
-        
-        if content.categories:
-            prompt_parts.append(f"Categories: {', '.join(content.categories)}.")
-        
-        if content.tags:
-            prompt_parts.append(f"Tags: {', '.join(content.tags[:5])}.")  # Limit tags
-        
-        # Add content excerpt (first 500 chars)
-        content_excerpt = content.content[:500].strip()
-        if content_excerpt:
-            # Remove markdown formatting
-            clean_content = re.sub(r'[#*`\[\]()]', '', content_excerpt)
-            clean_content = re.sub(r'\n+', ' ', clean_content)
-            prompt_parts.append(f"Key themes: {clean_content}")
-        
-        # Per-author art-style override (e.g. AI personas) wins over the
-        # configured style for this post's banner. Computed per-call from the
-        # document's own front matter, so it is thread-safe under parallel workers.
-        effective_style = self.image_style
-        style_modifiers = ""
-        overrides = self.author_preview_overrides(content.front_matter.get('author'))
-        if overrides.get('style'):
-            effective_style = str(overrides['style']).strip()
-            self.debug(f"Author '{content.front_matter.get('author')}' style override applied")
-        if overrides.get('style_modifiers'):
-            style_modifiers = f" Additional style: {str(overrides['style_modifiers']).strip()}."
-
-        # Add style instructions
-        prompt_parts.extend([
-            f"Style: {effective_style}.{style_modifiers}",
-            "The image should be suitable as a blog header/preview image.",
-            "Clean composition, professional look, visually appealing.",
-            "No text or letters in the image.",
-        ])
-
-        return ' '.join(prompt_parts)
-    
-    def generate_filename(self, title: str) -> str:
-        """Generate a safe filename from title."""
-        # Convert to lowercase and replace special chars
-        safe_name = re.sub(r'[^a-z0-9]+', '-', title.lower())
-        safe_name = re.sub(r'-+', '-', safe_name).strip('-')
-        return safe_name[:50]  # Limit length
-    
-    def generate_image_openai(self, prompt: str, output_path: Path) -> GenerationResult:
-        """Generate image using OpenAI DALL-E via HTTP API (no SDK required)."""
-        if not HAS_REQUESTS:
-            return GenerationResult(
-                success=False,
-                image_path=None,
-                preview_url=None,
-                error="requests package not installed. Run: pip install requests",
-                prompt_used=prompt,
-            )
-        
-        api_key = os.environ.get('OPENAI_API_KEY')
-        if not api_key:
-            return GenerationResult(
-                success=False,
-                image_path=None,
-                preview_url=None,
-                error="OPENAI_API_KEY environment variable not set",
-                prompt_used=prompt,
-            )
-        
-        try:
-            self.debug(f"Generating with prompt: {prompt[:200]}...")
-            
-            # Parse size
-            size_map = {
-                "1024x1024": "1024x1024",
-                "1792x1024": "1792x1024",
-                "1024x1792": "1024x1792",
-            }
-            size = size_map.get(self.image_size, "1024x1024")
-            
-            # Use HTTP API directly instead of SDK
-            response = requests.post(
-                "https://api.openai.com/v1/images/generations",
-                headers={
-                    "Authorization": f"Bearer {api_key}",
-                    "Content-Type": "application/json",
-                },
-                json={
-                    "model": "dall-e-3",
-                    "prompt": prompt,
-                    "size": size,
-                    "quality": "standard",
-                    "n": 1,
-                },
-                timeout=120,  # 2 minute timeout for image generation
-            )
-            response.raise_for_status()
-            
-            data = response.json()
-            image_url = data['data'][0]['url']
-            
-            # Download image
-            img_response = requests.get(image_url, timeout=60)
-            img_response.raise_for_status()
-            
-            output_path.write_bytes(img_response.content)
-            
-            return GenerationResult(
-                success=True,
-                image_path=str(output_path),
-                preview_url=str(output_path.relative_to(self.project_root)),
-                error=None,
-                prompt_used=prompt,
-            )
-            
-        except requests.exceptions.HTTPError as e:
-            error_msg = str(e)
+
+    success(f"Updated front matter with preview: {preview_path}")
+    return True
+
+
+def generate_filename(title: str) -> str:
+    """Slug identical to the historical Bash chain (trim before the 50-cut)."""
+    slug = re.sub(r"[^a-z0-9]", "-", title.lower())
+    slug = re.sub(r"-+", "-", slug).strip("-")
+    return slug[:50]
+
+
+def normalize_preview_path(preview: Optional[str], settings: Settings) -> Optional[str]:
+    """Front-matter path → site-absolute path (/assets/... form) for existence
+    checks. External URLs pass through unchanged."""
+    if not preview:
+        return preview
+    if preview.startswith(("http://", "https://")):
+        return preview
+    # Substring (not prefix) check is deliberate: it mirrors the Liquid
+    # `contains` logic in components/preview-image.html and content/seo.html —
+    # the engine's idea of "already prefixed" must match what the site renders.
+    if settings.auto_prefix and settings.assets_prefix not in preview:
+        return f"{settings.assets_prefix}{preview}"
+    return preview
+
+
+def check_preview_exists(preview: Optional[str], settings: Settings, root: Path) -> bool:
+    if not preview:
+        return False
+    # External URLs count as present (matches the Liquid component + SEO tags;
+    # the old Bash engine would silently regenerate over them).
+    if preview.startswith(("http://", "https://")):
+        return True
+    normalized = normalize_preview_path(preview, settings) or ""
+    clean = normalized.lstrip("/")
+    candidates = [root / clean, root / "assets" / clean]
+    return any(p.is_file() for p in candidates)
+
+
+def preview_front_matter_path(settings: Settings, filename: str) -> str:
+    """The value written to front matter — WITHOUT the assets prefix (Liquid
+    adds it): assets/images/previews → /images/previews/<filename>."""
+    out = settings.output_dir.strip("/")
+    prefix = settings.assets_prefix.strip("/")
+    if prefix and (out == prefix or out.startswith(prefix + "/")):
+        out = out[len(prefix):].strip("/")
+    return f"/{out}/{filename}" if out else f"/{filename}"
+
+
+def find_preview_image(preview: Optional[str], settings: Settings, root: Path) -> Optional[Path]:
+    """Locate an existing preview image on disk (for --enhance)."""
+    if not preview or preview.startswith(("http://", "https://")):
+        return None
+    clean = preview.lstrip("/")
+    candidates = [
+        root / clean,
+        root / "assets" / clean,
+        root / settings.output_dir / Path(clean).name,
+    ]
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+# =============================================================================
+# Prompt layer
+# =============================================================================
+
+def build_prompt(cf: ContentFile, settings: Settings) -> str:
+    """Template prompt — wording carried over from the original engine."""
+    parts = [f"Create a blog preview banner image for an article titled '{cf.title}'."]
+    if cf.description:
+        parts.append(f"The article is about: {cf.description}.")
+    if cf.categories:
+        parts.append(f"Categories: {cf.categories}.")
+    excerpt = re.sub(r"\s+", " ", cf.content[:500]).strip()
+    if excerpt:
+        parts.append(f"Key themes from content: {excerpt}")
+    parts.append(f"Art style: {settings.style}.")
+    if settings.style_modifiers:
+        parts.append(f"Additional style: {settings.style_modifiers}.")
+    parts.append(
+        "The image should be suitable as a wide blog header/banner image with "
+        "clean composition. No text or words in the image."
+    )
+    return " ".join(parts)
+
+
+def build_enhance_prompt(cf: ContentFile, settings: Settings) -> str:
+    prompt = settings.enhance_prompt or DEFAULT_ENHANCE_PROMPT
+    if cf.title:
+        prompt += f" Context: This is a preview banner for an article titled '{cf.title}'."
+    if cf.description:
+        prompt += f" Article topic: {cf.description}."
+    prompt += f" Maintain the {settings.style} artistic style."
+    return prompt
+
+
+def claude_model_for(settings: Settings) -> str:
+    return settings.claude_model or DEFAULT_CLAUDE_MODEL
+
+
+def claude_article_brief(client: "AnthropicClient", cf: ContentFile,
+                         settings: Settings, base_prompt: str) -> str:
+    """Analyze stage (prompt_engine: claude): Claude reads the article and
+    writes the art-direction brief the renderer will receive. Falls back to
+    the template prompt on any failure — analysis is an enhancement layer,
+    never a hard dependency."""
+    excerpt = re.sub(r"\s+", " ", cf.content[:1500]).strip()
+    article = (
+        f"ARTICLE\nTitle: {cf.title}\n"
+        f"Description: {cf.description or '(none)'}\n"
+        f"Categories/tags: {cf.categories or '(none)'}\n"
+        f"Excerpt: {excerpt or '(none)'}\n\n"
+        f"MANDATORY STYLE DIRECTIONS\nArt style: {settings.style}\n"
+        f"Style modifiers: {settings.style_modifiers or '(none)'}\n\n"
+        "Write the image-generation prompt now."
+    )
+    try:
+        text = client.complete(
+            ART_DIRECTOR_SYSTEM, article,
+            model=claude_model_for(settings), max_tokens=2048,
+        ).strip()
+        if text:
+            debug(f"Claude art-direction brief: {text[:300]}...")
+            return text
+        warn("Claude analysis returned empty text; using template prompt")
+    except Exception as exc:
+        warn(f"Claude analysis failed ({exc}); using template prompt")
+    return base_prompt
+
+
+def _extract_json_object(text: str) -> Optional[dict]:
+    start, end = text.find("{"), text.rfind("}")
+    if start == -1 or end <= start:
+        return None
+    try:
+        data = json.loads(text[start:end + 1])
+        return data if isinstance(data, dict) else None
+    except ValueError:
+        return None
+
+
+def claude_review_image(client: "AnthropicClient", image_path: Path,
+                        cf: ContentFile, prompt: str,
+                        settings: Settings) -> Tuple[bool, str, str]:
+    """Review stage (review_engine: claude): Claude inspects the rendered
+    banner. Returns (approved, critique, revised_prompt). Any failure counts
+    as approval — review must never block generation."""
+    context = (
+        f"ARTICLE\nTitle: {cf.title}\nDescription: {cf.description or '(none)'}\n"
+        f"Categories/tags: {cf.categories or '(none)'}\n\n"
+        f"REQUIRED STYLE\n{settings.style}"
+        + (f"; {settings.style_modifiers}" if settings.style_modifiers else "")
+        + f"\n\nPROMPT THE IMAGE WAS GENERATED FROM\n{prompt}\n\n"
+        "Review the image above against the article and style. JSON only."
+    )
+    try:
+        text = client.complete_vision(
+            REVIEWER_SYSTEM, context, image_path,
+            model=claude_model_for(settings),
+        )
+        data = _extract_json_object(text)
+        if not data:
+            warn("Claude review returned no parseable verdict; keeping image")
+            return True, "", ""
+        verdict = str(data.get("verdict", "approve")).lower()
+        critique = str(data.get("critique", "")).strip()
+        revised = str(data.get("revised_prompt", "")).strip()
+        if verdict == "revise" and revised:
+            return False, critique, revised
+        return True, critique, ""
+    except Exception as exc:
+        warn(f"Claude review failed ({exc}); keeping image")
+        return True, "", ""
+
+
+# =============================================================================
+# SVG toolkit
+# =============================================================================
+
+SVG_NS = "http://www.w3.org/2000/svg"
+XLINK_NS = "http://www.w3.org/1999/xlink"
+
+_BANNED_SVG_ELEMENTS = {"script", "foreignObject", "iframe", "audio", "video", "image"}
+
+
+class SvgError(Exception):
+    pass
+
+
+def seed_for(slug: str) -> int:
+    return zlib.crc32(slug.encode("utf-8"))
+
+
+def palette_for(seed: int) -> List[str]:
+    return RETRO_PALETTES[seed % len(RETRO_PALETTES)]
+
+
+def composition_for(seed: int) -> str:
+    return COMPOSITION_VARIANTS[(seed >> 8) % len(COMPOSITION_VARIANTS)]
+
+
+def _localname(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1] if "}" in tag else tag
+
+
+_URL_REF = re.compile(r"url\(\s*(?!#|'#|\"#)[^)]*\)", re.I)
+
+
+def _scrub_style_text(value: str) -> str:
+    value = re.sub(r"@import[^;]*;?", "", value, flags=re.I)
+    return _URL_REF.sub("none", value)
+
+
+def sanitize_svg(svg_text: str) -> Tuple[str, List[str]]:
+    """Parse + sanitize model-produced SVG. Raises SvgError when unusable.
+
+    Strips scripts/foreignObject/external references/event handlers; forces the
+    banner viewBox/width/height. Returns (clean_svg, warnings).
+    """
+    warnings: List[str] = []
+    # Reject DTDs outright: entity declarations enable expansion attacks
+    # (billion-laughs) and external references; legit banner SVG needs neither.
+    if re.search(r"<!\s*(DOCTYPE|ENTITY)", svg_text, re.I):
+        raise SvgError("SVG contains a DOCTYPE/ENTITY declaration (rejected)")
+    try:
+        root = ET.fromstring(svg_text)
+    except ET.ParseError as exc:
+        raise SvgError(f"SVG does not parse: {exc}") from None
+    if _localname(root.tag) != "svg":
+        raise SvgError(f"Root element is <{_localname(root.tag)}>, not <svg>")
+
+    def scrub(element: ET.Element) -> None:
+        for child in list(element):
+            name = _localname(child.tag)
+            if name in _BANNED_SVG_ELEMENTS:
+                element.remove(child)
+                warnings.append(f"removed <{name}>")
+                continue
+            scrub(child)
+
+        for attr in list(element.attrib):
+            local = _localname(attr)
+            value = element.attrib[attr]
+            if local.lower().startswith("on"):
+                del element.attrib[attr]
+                warnings.append(f"removed {local} handler")
+            elif local == "href" and not value.startswith("#"):
+                del element.attrib[attr]
+                warnings.append("removed external href")
+            elif "url(" in value.lower() or "@import" in value.lower():
+                # Covers style= AND presentation attributes (fill, stroke,
+                # filter, mask, clip-path, …) — url() must stay #-local.
+                cleaned = _scrub_style_text(value)
+                if cleaned != value:
+                    element.attrib[attr] = cleaned
+                    warnings.append(f"scrubbed url() in {local}")
+
+        if _localname(element.tag) == "style" and element.text:
+            cleaned = _scrub_style_text(element.text)
+            if cleaned != element.text:
+                element.text = cleaned
+                warnings.append("scrubbed <style> url()/@import")
+
+    scrub(root)
+
+    root.set("viewBox", f"0 0 {SVG_WIDTH} {SVG_HEIGHT}")
+    root.set("width", str(SVG_WIDTH))
+    root.set("height", str(SVG_HEIGHT))
+
+    ET.register_namespace("", SVG_NS)
+    ET.register_namespace("xlink", XLINK_NS)
+    return ET.tostring(root, encoding="unicode"), warnings
+
+
+def render_local_svg(title: str, seed: int) -> str:
+    """Deterministic retro-landscape SVG for the `local` provider (no network).
+
+    Shares the claude provider's seed → palette/composition scheme so the two
+    stay visually kin per slug."""
+    pal = palette_for(seed)
+    variant = (seed >> 8) % len(COMPOSITION_VARIANTS)
+    rng = seed or 1
+
+    def nxt(bound: int) -> int:
+        nonlocal rng
+        rng = (rng * 1103515245 + 12345) & 0x7FFFFFFF
+        return rng % max(bound, 1)
+
+    w, h = SVG_WIDTH, SVG_HEIGHT
+    parts = [
+        f'<svg xmlns="{SVG_NS}" viewBox="0 0 {w} {h}" width="{w}" height="{h}">',
+        f'<rect width="{w}" height="{h}" fill="{pal[0]}"/>',
+    ]
+    # Sky bands
+    band_h = h // 8
+    for i in range(3):
+        parts.append(
+            f'<rect y="{i * band_h}" width="{w}" height="{band_h}" '
+            f'fill="{pal[1]}" opacity="0.{25 + i * 12}"/>'
+        )
+    # Celestial body with stepped "pixel" rings
+    cx, cy, radius = w - 320 - nxt(400), 240 + nxt(160), 130 + nxt(80)
+    for i, ring_color in enumerate([pal[5], pal[4]]):
+        parts.append(
+            f'<circle cx="{cx}" cy="{cy}" r="{radius - i * 26}" fill="{ring_color}"/>'
+        )
+    # Scanline stripes across the disk (clipped to the circle's chord width)
+    for i in range(3):
+        y = cy + 12 + i * 26
+        dy = abs(y + 5 - cy)
+        if dy >= radius:
+            continue
+        half = int((radius * radius - dy * dy) ** 0.5)
+        parts.append(f'<rect x="{cx - half}" y="{y}" width="{half * 2}" height="10" fill="{pal[0]}"/>')
+    # Layered terrain: three silhouette ranges of blocky steps
+    for layer, color in enumerate([pal[2], pal[3], pal[1]]):
+        base = h - 120 - layer * 170
+        x = -40
+        points = [f"-40,{h}"]
+        while x < w + 80:
+            peak = base - nxt(300) - (2 - layer) * 70
+            width_step = 90 + nxt(150)
+            points.append(f"{x},{peak}")
+            points.append(f"{x + width_step},{peak}")
+            x += width_step
+        points.append(f"{w + 80},{h}")
+        parts.append(f'<polygon points="{" ".join(points)}" fill="{color}"/>')
+    # Variant flourish: grid floor for even variants, stars for odd
+    if variant % 2 == 0:
+        for i in range(1, 7):
+            y = h - i * (i * 8)
+            parts.append(f'<rect y="{y}" width="{w}" height="3" fill="{pal[4]}" opacity="0.35"/>')
+    else:
+        for _ in range(40):
+            sx, sy = nxt(w), nxt(h // 2)
+            size = 3 + nxt(5)
+            parts.append(f'<rect x="{sx}" y="{sy}" width="{size}" height="{size}" fill="{pal[4]}"/>')
+    # CRT scanline veil + vignette bars
+    for y in range(0, h, 8):
+        parts.append(f'<rect y="{y}" width="{w}" height="1" fill="#000" opacity="0.10"/>')
+    parts.append(f'<rect width="{w}" height="26" fill="#000" opacity="0.35"/>')
+    parts.append(f'<rect y="{h - 26}" width="{w}" height="26" fill="#000" opacity="0.35"/>')
+    parts.append("</svg>")
+    return "".join(parts)
+
+
+# =============================================================================
+# Rasterizer chain
+# =============================================================================
+
+# Tool discovery is per-run stable; memoize the PATH walks so a batch of N
+# files doesn't pay N x 4 which() scans.
+@functools.lru_cache(maxsize=None)
+def _which(tool: str) -> Optional[str]:
+    return shutil.which(tool)
+
+
+def _run_quiet(cmd: List[str], cwd: Optional[Path] = None, timeout: int = 120) -> bool:
+    try:
+        proc = subprocess.run(
+            cmd, cwd=str(cwd) if cwd else None, capture_output=True, timeout=timeout
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        debug(f"rasterizer {cmd[0]} failed: {exc}")
+        return False
+    if proc.returncode != 0:
+        debug(f"rasterizer {cmd[0]} exit {proc.returncode}: "
+              f"{proc.stderr.decode('utf-8', 'replace')[:200]}")
+        return False
+    return True
+
+
+def _playwright_helper(project_root: Path) -> Optional[Path]:
+    candidates = [
+        Path(__file__).resolve().parent.parent / "dev" / "rasterize-svg.js",
+        project_root / "scripts" / "dev" / "rasterize-svg.js",
+    ]
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def rasterize_svg(
+    svg_path: Path, png_path: Path, project_root: Path, preference: str = "auto"
+) -> Optional[str]:
+    """SVG → PNG through the first available tool. Returns the tool name used,
+    or None when nothing worked (caller keeps the .svg)."""
+    w, h = SVG_WIDTH, SVG_HEIGHT
+    helper = _playwright_helper(project_root)
+    chain: List[Tuple[str, Any]] = [
+        ("rsvg", lambda: _which("rsvg-convert") and _run_quiet(
+            ["rsvg-convert", "-w", str(w), "-h", str(h), "-o", str(png_path), str(svg_path)])),
+        ("inkscape", lambda: _which("inkscape") and _run_quiet(
+            ["inkscape", str(svg_path), "--export-type=png",
+             f"--export-filename={png_path}", "-w", str(w), "-h", str(h)])),
+        ("magick", lambda: (
+            (_which("magick") and _run_quiet(
+                ["magick", str(svg_path), "-resize", f"{w}x{h}", str(png_path)]))
+            or (_which("convert") and _run_quiet(
+                ["convert", str(svg_path), "-resize", f"{w}x{h}", str(png_path)]))
+        )),
+        ("playwright", lambda: helper is not None and _which("node") and _run_quiet(
+            ["node", str(helper), str(svg_path), str(png_path), str(w), str(h)],
+            cwd=project_root, timeout=180)),
+    ]
+    if preference == "none":
+        return None
+    if preference != "auto":
+        chain = [entry for entry in chain if entry[0] == preference]
+        if not chain:
+            warn(f"Unknown rasterizer '{preference}'")
+            return None
+    for name, attempt in chain:
+        if attempt():
             try:
-                error_data = e.response.json()
-                if 'error' in error_data:
-                    error_msg = error_data['error'].get('message', str(e))
-            except:
+                if png_path.is_file() and png_path.read_bytes()[:8] == PNG_SIGNATURE:
+                    debug(f"Rasterized with {name}: {png_path.name}")
+                    return name
+            except OSError:
                 pass
-            return GenerationResult(
-                success=False,
-                image_path=None,
-                preview_url=None,
-                error=error_msg,
-                prompt_used=prompt,
-            )
-        except Exception as e:
-            return GenerationResult(
-                success=False,
-                image_path=None,
-                preview_url=None,
-                error=str(e),
-                prompt_used=prompt,
-            )
-    
-    def generate_image_stability(self, prompt: str, output_path: Path) -> GenerationResult:
-        """Generate image using Stability AI."""
-        if not HAS_REQUESTS:
-            return GenerationResult(
-                success=False,
-                image_path=None,
-                preview_url=None,
-                error="requests package not installed",
-                prompt_used=prompt,
-            )
-        
-        api_key = os.environ.get('STABILITY_API_KEY')
-        if not api_key:
-            return GenerationResult(
-                success=False,
-                image_path=None,
-                preview_url=None,
-                error="STABILITY_API_KEY environment variable not set",
-                prompt_used=prompt,
+            png_path.unlink(missing_ok=True)
+    return None
+
+
+# =============================================================================
+# Anthropic client (Claude Code OAuth → API key → claude CLI)
+# =============================================================================
+
+class ClaudeRefusal(Exception):
+    def __init__(self, category: Optional[str]):
+        self.category = category
+        super().__init__(f"request declined (category: {category or 'unspecified'})")
+
+
+class ClaudeTruncated(Exception):
+    pass
+
+
+class AnthropicClient:
+    """Minimal Messages-API client honoring the repo's credential conventions.
+
+    Modes (first match wins — mirrors templates/deploy/chat-proxy/worker.js):
+      oauth    CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_AUTH_TOKEN → Bearer +
+               `anthropic-beta: oauth-2025-04-20` + Claude Code first system block
+      api_key  ANTHROPIC_API_KEY → x-api-key header
+      cli      `claude -p` headless (rides the local Claude Code login)
+    """
+
+    def __init__(self, env: Optional[Dict[str, str]] = None):
+        self.env = dict(env if env is not None else os.environ)
+        self.mode: Optional[str] = None
+        self.token: Optional[str] = None
+        if self.env.get("CLAUDE_CODE_OAUTH_TOKEN"):
+            self.mode, self.token = "oauth", self.env["CLAUDE_CODE_OAUTH_TOKEN"]
+        elif self.env.get("ANTHROPIC_AUTH_TOKEN"):
+            self.mode, self.token = "oauth", self.env["ANTHROPIC_AUTH_TOKEN"]
+        elif self.env.get("ANTHROPIC_API_KEY"):
+            self.mode, self.token = "api_key", self.env["ANTHROPIC_API_KEY"]
+        elif shutil.which("claude"):
+            self.mode = "cli"
+
+    def available(self) -> bool:
+        return self.mode is not None
+
+    def describe(self) -> str:
+        return {
+            "oauth": "Claude Code OAuth token (Bearer)",
+            "api_key": "Anthropic API key",
+            "cli": "claude CLI (local Claude Code login)",
+            None: "none",
+        }[self.mode]
+
+    def headers(self) -> Dict[str, str]:
+        if self.mode == "oauth":
+            return {
+                "Authorization": f"Bearer {self.token}",
+                "anthropic-version": ANTHROPIC_VERSION,
+                "anthropic-beta": OAUTH_BETA,
+            }
+        if self.mode == "api_key":
+            return {
+                "x-api-key": self.token or "",
+                "anthropic-version": ANTHROPIC_VERSION,
+            }
+        raise RuntimeError(f"no API headers for mode {self.mode}")
+
+    def complete(
+        self,
+        system_text: str,
+        user_text: str,
+        model: str = DEFAULT_CLAUDE_MODEL,
+        max_tokens: int = CLAUDE_MAX_TOKENS,
+    ) -> str:
+        """One Messages-API turn (or CLI run); returns concatenated text blocks.
+
+        Raises ClaudeRefusal / ClaudeTruncated / HttpStatusError / RuntimeError.
+        """
+        if self.mode == "cli":
+            return self._complete_cli(system_text, user_text, model)
+        if self.mode is None:
+            raise RuntimeError("no Anthropic credential configured")
+
+        # The Claude Code identity block is REQUIRED as the first system block
+        # for OAuth tokens (worker.js recipe) and intentionally omitted for
+        # plain API keys, matching the chat proxy's per-mode behavior.
+        system_blocks = [{"type": "text", "text": system_text}]
+        if self.mode == "oauth":
+            system_blocks.insert(0, {"type": "text", "text": CLAUDE_CODE_SYSTEM_PROMPT})
+
+        payload: Dict[str, Any] = {
+            "model": model,
+            "max_tokens": max_tokens,
+            "thinking": {"type": "adaptive"},
+            "system": system_blocks,
+            "messages": [{"role": "user", "content": user_text}],
+        }
+
+        def call(body: Dict[str, Any]) -> dict:
+            return with_retries(
+                lambda: http_json(ANTHROPIC_API_URL, body, self.headers(), timeout=900),
+                "Anthropic API",
             )
-        
+
         try:
-            response = requests.post(
-                "https://api.stability.ai/v1/generation/stable-diffusion-xl-1024-v1-0/text-to-image",
-                headers={
-                    "Authorization": f"Bearer {api_key}",
-                    "Content-Type": "application/json",
-                },
-                json={
-                    "text_prompts": [{"text": prompt}],
-                    "cfg_scale": 7,
-                    "height": 1024,
-                    "width": 1024,
-                    "samples": 1,
-                    "steps": 30,
-                },
-            )
-            response.raise_for_status()
-            
-            data = response.json()
-            
-            if 'artifacts' not in data or not data['artifacts']:
-                return GenerationResult(
-                    success=False,
-                    image_path=None,
-                    preview_url=None,
-                    error="No image data in response",
-                    prompt_used=prompt,
-                )
-            
-            import base64
-            image_data = base64.b64decode(data['artifacts'][0]['base64'])
-            output_path.write_bytes(image_data)
-            
-            return GenerationResult(
-                success=True,
-                image_path=str(output_path),
-                preview_url=str(output_path.relative_to(self.project_root)),
-                error=None,
-                prompt_used=prompt,
-            )
-            
-        except Exception as e:
-            return GenerationResult(
-                success=False,
-                image_path=None,
-                preview_url=None,
-                error=str(e),
-                prompt_used=prompt,
+            data = call(payload)
+        except HttpStatusError as exc:
+            if exc.status == 400 and "thinking" in exc.message().lower():
+                debug("Retrying without thinking parameter")
+                payload.pop("thinking", None)
+                data = call(payload)
+            elif exc.status == 401 and self.mode == "oauth":
+                raise RuntimeError(
+                    "Anthropic rejected the OAuth token (401). It may be expired "
+                    "— mint a fresh one with `claude setup-token`, or use "
+                    "ANTHROPIC_API_KEY instead."
+                ) from None
+            else:
+                raise
+
+        stop_reason = data.get("stop_reason")
+        if stop_reason == "refusal":
+            details = data.get("stop_details") or {}
+            raise ClaudeRefusal(details.get("category") if isinstance(details, dict) else None)
+
+        text = "".join(
+            block.get("text", "")
+            for block in data.get("content", [])
+            if isinstance(block, dict) and block.get("type") == "text"
+        )
+        if stop_reason == "max_tokens":
+            raise ClaudeTruncated(text)
+        return text
+
+    def complete_vision(
+        self,
+        system_text: str,
+        user_text: str,
+        image_path: Path,
+        model: str = DEFAULT_CLAUDE_MODEL,
+        max_tokens: int = 2048,
+    ) -> str:
+        """One vision turn over a local PNG (review stage). CLI mode passes the
+        file path and lets `claude -p` read it; API modes embed base64."""
+        if self.mode == "cli":
+            prompt = (
+                f"{system_text}\n\n---\n\nFirst use the Read tool to view the "
+                f"image file at {image_path.resolve()} — then respond.\n\n{user_text}"
             )
-    
-    def generate_image_xai(self, prompt: str, output_path: Path) -> GenerationResult:
-        """Generate image using xAI Grok API."""
-        if not HAS_REQUESTS:
-            return GenerationResult(
-                success=False,
-                image_path=None,
-                preview_url=None,
-                error="requests package not installed. Run: pip install requests",
-                prompt_used=prompt,
+            return self._run_cli(prompt, model, allowed_tools="Read")
+        if self.mode is None:
+            raise RuntimeError("no Anthropic credential configured")
+
+        system_blocks = [{"type": "text", "text": system_text}]
+        if self.mode == "oauth":
+            system_blocks.insert(0, {"type": "text", "text": CLAUDE_CODE_SYSTEM_PROMPT})
+        payload: Dict[str, Any] = {
+            "model": model,
+            "max_tokens": max_tokens,
+            "thinking": {"type": "adaptive"},
+            "system": system_blocks,
+            "messages": [{
+                "role": "user",
+                "content": [
+                    {"type": "image", "source": {
+                        "type": "base64", "media_type": "image/png",
+                        "data": base64.b64encode(image_path.read_bytes()).decode("ascii"),
+                    }},
+                    {"type": "text", "text": user_text},
+                ],
+            }],
+        }
+        data = with_retries(
+            lambda: http_json(ANTHROPIC_API_URL, payload, self.headers(), timeout=900),
+            "Anthropic API (review)",
+        )
+        if data.get("stop_reason") == "refusal":
+            details = data.get("stop_details") or {}
+            raise ClaudeRefusal(details.get("category") if isinstance(details, dict) else None)
+        return "".join(
+            block.get("text", "")
+            for block in data.get("content", [])
+            if isinstance(block, dict) and block.get("type") == "text"
+        )
+
+    def _complete_cli(self, system_text: str, user_text: str, model: str) -> str:
+        return self._run_cli(f"{system_text}\n\n---\n\n{user_text}", model)
+
+    def _run_cli(self, prompt: str, model: str,
+                 allowed_tools: Optional[str] = None) -> str:
+        cmd = ["claude", "-p", "--model", model, "--output-format", "text"]
+        if allowed_tools:
+            cmd += ["--allowedTools", allowed_tools]
+        try:
+            proc = subprocess.run(
+                cmd,
+                input=prompt,
+                capture_output=True,
+                text=True,
+                timeout=300,
             )
-        
-        api_key = os.environ.get('XAI_API_KEY')
-        if not api_key:
-            return GenerationResult(
-                success=False,
-                image_path=None,
-                preview_url=None,
-                error="XAI_API_KEY environment variable not set",
-                prompt_used=prompt,
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            raise RuntimeError(f"claude CLI failed: {exc}") from None
+        if proc.returncode != 0 or not proc.stdout.strip():
+            tail = (proc.stderr or "").strip()[-300:]
+            raise RuntimeError(
+                f"claude CLI exited {proc.returncode}: {tail or 'no output'}"
             )
-        
+        return proc.stdout
+
+
+CLAUDE_CREDENTIAL_HINT = (
+    "Claude orchestration (article analysis + image review) needs any ONE of:\n"
+    "  1. CLAUDE_CODE_OAUTH_TOKEN   — run `claude setup-token` (Claude Pro/Max)\n"
+    "  2. ANTHROPIC_AUTH_TOKEN      — short-lived Bearer (e.g. `ant auth print-credentials`)\n"
+    "  3. ANTHROPIC_API_KEY         — key from console.anthropic.com\n"
+    "  4. the `claude` CLI installed and logged in (used automatically)\n"
+    "Falling back to the template prompt and skipping review (or pass "
+    "--prompt-engine template --review none to silence this)."
+)
+
+
+# =============================================================================
+# Providers
+# =============================================================================
+
+@dataclass
+class ImageResult:
+    ok: bool
+    kind: str = "png"                 # png | svg
+    path: Optional[Path] = None
+    error: Optional[str] = None
+
+
+class EditUnsupported(Exception):
+    def __init__(self, provider: str):
+        super().__init__(f"provider '{provider}' has no image-edit capability")
+        self.provider = provider
+
+
+class Provider:
+    name = "base"
+
+    def is_configured(self, env: Dict[str, str]) -> bool:
+        raise NotImplementedError
+
+    def missing_hint(self, env: Dict[str, str]) -> str:
+        raise NotImplementedError
+
+    def default_model(self) -> str:
+        raise NotImplementedError
+
+    def generate(self, prompt: str, settings: Settings, out_base: Path,
+                 ctx: "RunContext") -> ImageResult:
+        raise NotImplementedError
+
+    def edit(self, image_path: Path, prompt: str, settings: Settings,
+             ctx: "RunContext", out_path: Optional[Path] = None) -> ImageResult:
+        """Enhance an existing image. Providers without an edit capability
+        raise EditUnsupported; the runner then falls back to OpenAI (the
+        historical behavior of --enhance)."""
+        raise EditUnsupported(self.name)
+
+
+@dataclass
+class RunContext:
+    """Run-scoped services handed to providers."""
+    project_root: Path
+    env: Dict[str, str]
+    anthropic: Optional[AnthropicClient] = None
+    slug: str = ""
+
+    def claude(self) -> AnthropicClient:
+        if self.anthropic is None:
+            self.anthropic = AnthropicClient(self.env)
+        return self.anthropic
+
+
+def adapt_openai_size_quality(model: str, size: str, quality: str) -> Tuple[str, str]:
+    """Historical engine behavior: adapt shared settings per model family."""
+    if model.startswith("gpt-image-") and size == "1792x1024":
+        size = "1536x1024"
+    elif model.startswith("dall-e-") and quality == "auto":
+        quality = "standard"
+    return size, quality
+
+
+def _write_image_payload(entry: Dict[str, Any], out_path: Path) -> bool:
+    """Persist one OpenAI-style data[0] entry (b64_json preferred, else url)."""
+    b64 = entry.get("b64_json")
+    if b64:
+        out_path.write_bytes(base64.b64decode(b64))
+        return True
+    url = entry.get("url")
+    if url:
+        download_to(url, out_path)
+        return True
+    return False
+
+
+class OpenAIProvider(Provider):
+    name = "openai"
+
+    def is_configured(self, env: Dict[str, str]) -> bool:
+        return bool(env.get("OPENAI_API_KEY"))
+
+    def missing_hint(self, env: Dict[str, str]) -> str:
+        return "OPENAI_API_KEY environment variable is required for the OpenAI provider"
+
+    def default_model(self) -> str:
+        return "gpt-image-2"
+
+    def _headers(self, env: Dict[str, str]) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {env['OPENAI_API_KEY']}"}
+
+    def generate(self, prompt, settings, out_base, ctx) -> ImageResult:
+        model = effective_model(settings, self)
+        size, quality = adapt_openai_size_quality(model, settings.size, settings.quality)
+        out_path = out_base.with_suffix(".png")
+        payload = {"model": model, "prompt": prompt, "n": 1, "size": size, "quality": quality}
+        debug(f"OpenAI generate: model={model} size={size} quality={quality}")
         try:
-            # xAI has a max prompt length of 1024 characters
-            truncated_prompt = prompt[:1000] if len(prompt) > 1000 else prompt
-            self.debug(f"Generating with xAI Grok, prompt: {truncated_prompt[:200]}...")
-            
-            # xAI uses OpenAI-compatible API format
-            response = requests.post(
-                "https://api.x.ai/v1/images/generations",
-                headers={
-                    "Authorization": f"Bearer {api_key}",
-                    "Content-Type": "application/json",
-                },
-                json={
-                    "model": "grok-2-image",
-                    "prompt": truncated_prompt,
-                    "n": 1,
-                },
-                timeout=120,  # 2 minute timeout for image generation
+            data = with_retries(
+                lambda: http_json(
+                    "https://api.openai.com/v1/images/generations",
+                    payload, self._headers(ctx.env), timeout=900,
+                ),
+                "OpenAI API",
             )
-            response.raise_for_status()
-            
-            data = response.json()
-            
-            # xAI returns base64-encoded images
-            if 'data' not in data or not data['data']:
-                return GenerationResult(
-                    success=False,
-                    image_path=None,
-                    preview_url=None,
-                    error="No image data in response",
-                    prompt_used=prompt,
-                )
-            
-            image_data = data['data'][0]
-            
-            # Check if it's a URL or base64
-            if 'url' in image_data:
-                # Download from URL
-                img_response = requests.get(image_data['url'], timeout=60)
-                img_response.raise_for_status()
-                output_path.write_bytes(img_response.content)
-            elif 'b64_json' in image_data:
-                # Decode base64
-                import base64
-                image_bytes = base64.b64decode(image_data['b64_json'])
-                output_path.write_bytes(image_bytes)
-            else:
-                return GenerationResult(
-                    success=False,
-                    image_path=None,
-                    preview_url=None,
-                    error="Unexpected response format from xAI",
-                    prompt_used=prompt,
-                )
-            
-            return GenerationResult(
-                success=True,
-                image_path=str(output_path),
-                preview_url=str(output_path.relative_to(self.project_root)),
-                error=None,
-                prompt_used=prompt,
+            entries = data.get("data") or []
+            if not entries or not _write_image_payload(entries[0], out_path):
+                return ImageResult(False, error="No image data in OpenAI response")
+            return ImageResult(True, "png", out_path)
+        except HttpStatusError as exc:
+            return ImageResult(False, error=f"OpenAI API error: {exc.message()}")
+        except Exception as exc:
+            return ImageResult(False, error=str(exc))
+
+    def edit(self, image_path, prompt, settings, ctx, out_path=None) -> ImageResult:
+        model = settings.enhance_model
+        fields = {
+            "prompt": prompt,
+            "model": model,
+            "n": "1",
+            "size": "auto",
+            "quality": settings.enhance_quality,
+            "output_format": settings.enhance_format,
+        }
+        # gpt-image-2 does not accept input_fidelity (historical behavior).
+        if model != "gpt-image-2":
+            fields["input_fidelity"] = settings.enhance_fidelity
+        files = [("image[]", image_path.name, image_path.read_bytes(), "image/png")]
+        out_path = out_path or image_path
+        debug(f"OpenAI edit: model={model} fidelity="
+              f"{fields.get('input_fidelity', '(omitted)')} format={settings.enhance_format}")
+        try:
+            data = with_retries(
+                lambda: http_multipart(
+                    "https://api.openai.com/v1/images/edits",
+                    fields, files, self._headers(ctx.env), timeout=900,
+                ),
+                "OpenAI edits API",
             )
-            
-        except requests.exceptions.HTTPError as e:
-            error_msg = str(e)
-            try:
-                error_data = e.response.json()
-                self.debug(f"xAI error response: {error_data}")
-                if 'error' in error_data:
-                    error_msg = error_data['error'].get('message', str(error_data['error']))
-                elif 'detail' in error_data:
-                    error_msg = str(error_data['detail'])
-                else:
-                    error_msg = str(error_data)
-            except:
-                # Try to get raw text
-                try:
-                    error_msg = e.response.text[:500]
-                except:
-                    pass
-            return GenerationResult(
-                success=False,
-                image_path=None,
-                preview_url=None,
-                error=f"xAI API error: {error_msg}",
-                prompt_used=prompt,
+            usage = data.get("usage") or {}
+            if usage.get("total_tokens"):
+                debug(f"Token usage: {usage.get('total_tokens')} total")
+            entries = data.get("data") or []
+            if not entries or not _write_image_payload(entries[0], out_path):
+                return ImageResult(False, error="No image data in enhance response")
+            revised = entries[0].get("revised_prompt")
+            if revised:
+                debug(f"Revised prompt: {revised[:200]}...")
+            return ImageResult(True, "png", out_path)
+        except HttpStatusError as exc:
+            return ImageResult(False, error=f"OpenAI enhance API error: {exc.message()}")
+        except Exception as exc:
+            return ImageResult(False, error=str(exc))
+
+
+class XAIProvider(Provider):
+    name = "xai"
+
+    def is_configured(self, env: Dict[str, str]) -> bool:
+        return bool(env.get("XAI_API_KEY"))
+
+    def missing_hint(self, env: Dict[str, str]) -> str:
+        return "XAI_API_KEY environment variable is required for the xAI provider"
+
+    def default_model(self) -> str:
+        return "grok-2-image"
+
+    def generate(self, prompt, settings, out_base, ctx) -> ImageResult:
+        model = effective_model(settings, self)
+        out_path = out_base.with_suffix(".png")
+        payload = {"model": model, "prompt": prompt[:1000], "n": 1}  # 1024-char cap
+        try:
+            data = with_retries(
+                lambda: http_json(
+                    "https://api.x.ai/v1/images/generations",
+                    payload,
+                    {"Authorization": f"Bearer {ctx.env['XAI_API_KEY']}"},
+                    timeout=900,
+                ),
+                "xAI API",
             )
-        except Exception as e:
-            return GenerationResult(
-                success=False,
-                image_path=None,
-                preview_url=None,
-                error=str(e),
-                prompt_used=prompt,
+            entries = data.get("data") or []
+            if not entries or not _write_image_payload(entries[0], out_path):
+                return ImageResult(False, error="No image data in xAI response")
+            return ImageResult(True, "png", out_path)
+        except HttpStatusError as exc:
+            return ImageResult(False, error=f"xAI API error: {exc.message()}")
+        except Exception as exc:
+            return ImageResult(False, error=str(exc))
+
+
+class StabilityProvider(Provider):
+    name = "stability"
+
+    def is_configured(self, env: Dict[str, str]) -> bool:
+        return bool(env.get("STABILITY_API_KEY"))
+
+    def missing_hint(self, env: Dict[str, str]) -> str:
+        return "STABILITY_API_KEY environment variable is required for the Stability AI provider"
+
+    def default_model(self) -> str:
+        return "stable-diffusion-xl-1024-v1-0"
+
+    def generate(self, prompt, settings, out_base, ctx) -> ImageResult:
+        out_path = out_base.with_suffix(".png")
+        payload = {
+            "text_prompts": [{"text": prompt}],
+            "cfg_scale": 7,
+            # SDXL v1 endpoint accepts fixed dimension sets; 1024x1024 preserved
+            # from the original engine.
+            "height": 1024,
+            "width": 1024,
+            "samples": 1,
+            "steps": 30,
+        }
+        try:
+            data = with_retries(
+                lambda: http_json(
+                    "https://api.stability.ai/v1/generation/"
+                    "stable-diffusion-xl-1024-v1-0/text-to-image",
+                    payload,
+                    {"Authorization": f"Bearer {ctx.env['STABILITY_API_KEY']}"},
+                    timeout=900,
+                ),
+                "Stability API",
             )
-    
-    def generate_image(self, prompt: str, output_path: Path) -> GenerationResult:
-        """Generate image using configured provider."""
-        if self.provider == "openai":
-            return self.generate_image_openai(prompt, output_path)
-        elif self.provider == "stability":
-            return self.generate_image_stability(prompt, output_path)
-        elif self.provider == "xai":
-            return self.generate_image_xai(prompt, output_path)
-        else:
-            return GenerationResult(
-                success=False,
-                image_path=None,
-                preview_url=None,
-                error=f"Unknown provider: {self.provider}",
-                prompt_used=prompt,
+            artifacts = data.get("artifacts") or []
+            if not artifacts or not artifacts[0].get("base64"):
+                return ImageResult(False, error="No image data in Stability response")
+            out_path.write_bytes(base64.b64decode(artifacts[0]["base64"]))
+            return ImageResult(True, "png", out_path)
+        except HttpStatusError as exc:
+            return ImageResult(False, error=f"Stability API error: {exc.message()}")
+        except Exception as exc:
+            return ImageResult(False, error=str(exc))
+
+
+class GeminiProvider(Provider):
+    name = "gemini"
+
+    def is_configured(self, env: Dict[str, str]) -> bool:
+        return bool(env.get("GEMINI_API_KEY"))
+
+    def missing_hint(self, env: Dict[str, str]) -> str:
+        return "GEMINI_API_KEY environment variable is required for the Gemini provider"
+
+    def default_model(self) -> str:
+        return "gemini-2.5-flash-image"
+
+    def generate(self, prompt, settings, out_base, ctx) -> ImageResult:
+        model = effective_model(settings, self)
+        out_path = out_base.with_suffix(".png")
+        url = (
+            "https://generativelanguage.googleapis.com/v1beta/models/"
+            f"{model}:generateContent"
+        )
+        payload = {"contents": [{"parts": [{"text": prompt}]}]}
+        try:
+            data = with_retries(
+                lambda: http_json(
+                    url, payload,
+                    {"x-goog-api-key": ctx.env["GEMINI_API_KEY"]},
+                    timeout=900,
+                ),
+                "Gemini API",
             )
-    
-    def update_front_matter(self, file_path: Path, preview_path: str) -> bool:
-        """Update the front matter with new preview path."""
+            for candidate in data.get("candidates") or []:
+                for part in ((candidate.get("content") or {}).get("parts")) or []:
+                    inline = part.get("inlineData") or part.get("inline_data")
+                    if inline and inline.get("data"):
+                        out_path.write_bytes(base64.b64decode(inline["data"]))
+                        return ImageResult(True, "png", out_path)
+            return ImageResult(False, error="No inline image data in Gemini response")
+        except HttpStatusError as exc:
+            return ImageResult(False, error=f"Gemini API error: {exc.message()}")
+        except Exception as exc:
+            return ImageResult(False, error=str(exc))
+
+
+class SvgProviderMixin:
+    """Shared sanitize → write → rasterize tail for SVG-producing providers."""
+
+    def finish_svg(self, svg_text: str, out_base: Path, settings: Settings,
+                   ctx: RunContext) -> ImageResult:
         try:
-            content = file_path.read_text(encoding='utf-8')
-            
-            # Check if preview field exists
-            if re.search(r'^preview:', content, re.MULTILINE):
-                # Update existing preview
-                new_content = re.sub(
-                    r'^preview:.*$',
-                    f'preview: {preview_path}',
-                    content,
-                    flags=re.MULTILINE,
-                )
-            else:
-                # Add preview after description or title
-                if 'description:' in content:
-                    new_content = re.sub(
-                        r'(^description:.*$)',
-                        f'\\1\npreview: {preview_path}',
-                        content,
-                        flags=re.MULTILINE,
-                    )
-                else:
-                    new_content = re.sub(
-                        r'(^title:.*$)',
-                        f'\\1\npreview: {preview_path}',
-                        content,
-                        flags=re.MULTILINE,
-                    )
-            
-            file_path.write_text(new_content, encoding='utf-8')
-            return True
-            
-        except Exception as e:
-            log(f"Failed to update front matter: {e}", "error")
-            return False
-    
-    def _increment_stat(self, stat_name: str):
-        """Increment a stat on either ThreadSafeStats or ProgressStats."""
-        if isinstance(self.stats, ThreadSafeStats):
-            method = getattr(self.stats, f"increment_{stat_name}", None)
-            if method:
-                method()
-        else:
-            setattr(self.stats, stat_name, getattr(self.stats, stat_name) + 1)
+            clean, notes = sanitize_svg(svg_text)
+        except SvgError as exc:
+            return ImageResult(False, error=str(exc))
+        for note in notes:
+            warn(f"SVG sanitizer: {note}")
+        svg_path = out_base.with_suffix(".svg")
+        png_path = out_base.with_suffix(".png")
+        svg_path.write_text(clean, encoding="utf-8")
+        tool = rasterize_svg(svg_path, png_path, ctx.project_root, settings.rasterizer)
+        if tool:
+            svg_path.unlink(missing_ok=True)
+            return ImageResult(True, "png", png_path)
+        warn(
+            "No SVG rasterizer available — keeping the .svg preview. Social "
+            "og:image works best as PNG: install librsvg (`brew install librsvg`) "
+            "or Playwright (`npx playwright install chromium`)."
+        )
+        return ImageResult(True, "svg", svg_path)
+
+
+class LocalProvider(Provider, SvgProviderMixin):
+    name = "local"
+
+    def is_configured(self, env: Dict[str, str]) -> bool:
+        return True
+
+    def missing_hint(self, env: Dict[str, str]) -> str:
+        return ""
+
+    def default_model(self) -> str:
+        return "template-svg"
 
-    def process_file(self, file_path: Path, list_only: bool = False) -> bool:
-        """Process a single content file."""
-        global _interrupted
+    def generate(self, prompt, settings, out_base, ctx) -> ImageResult:
+        seed = seed_for(ctx.slug or out_base.stem)
+        svg_text = render_local_svg(ctx.slug, seed)
+        return self.finish_svg(svg_text, out_base, settings, ctx)
+
+    def edit(self, image_path, prompt, settings, ctx, out_path=None) -> ImageResult:
+        # Historical behavior: the local provider "enhances" by doing nothing
+        # (no API), so dry testing of --enhance needs no credentials.
+        warn("Local provider: No actual enhancement. Logging prompt...")
+        debug(f"Enhancement prompt: {prompt[:400]}...")
+        info(f"Placeholder: would enhance {image_path}")
+        return ImageResult(True, "png", image_path)
+
+
+# Renderers only — Claude is the orchestration layer (claude_article_brief /
+# claude_review_image) that sits in front of ANY of these, not a provider.
+PROVIDERS: Dict[str, Provider] = {
+    provider.name: provider
+    for provider in (
+        OpenAIProvider(),
+        XAIProvider(),
+        StabilityProvider(),
+        GeminiProvider(),
+        LocalProvider(),
+    )
+}
+
+
+# =============================================================================
+# Orchestrator
+# =============================================================================
+
+@dataclass
+class Stats:
+    processed: int = 0
+    generated: int = 0
+    enhanced: int = 0
+    skipped: int = 0
+    errors: int = 0
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+
+    def inc(self, name: str) -> None:
+        with self._lock:
+            setattr(self, name, getattr(self, name) + 1)
+
+
+class Runner:
+    def __init__(self, settings: Settings, project_root: Path,
+                 ctx: Optional[RunContext] = None):
+        self.settings = settings
+        self.root = project_root
+        self.stats = Stats()
+        self.authors = read_authors(project_root)
+        self.ctx = ctx or RunContext(project_root=project_root, env=dict(os.environ))
+
+    # -- discovery ------------------------------------------------------------
+
+    def collection_path(self, name: str) -> Path:
+        return self.root / "pages" / f"_{name}"
+
+    def discover(self, collection_path: Path) -> List[Path]:
+        if not collection_path.is_dir():
+            warn(f"Collection directory not found: {collection_path}")
+            return []
+        return sorted(collection_path.rglob("*.md"))
+
+    # -- per-file processing --------------------------------------------------
+
+    def process_file(self, path: Path) -> None:
         if _interrupted:
-            return False
-        
-        self._increment_stat("processed")
-        
-        content = self.parse_front_matter(file_path)
-        if not content:
-            self._increment_stat("skipped")
-            return False
-        
-        self.debug(f"Processing: {content.title}")
-        
-        # Check if preview exists
-        if content.preview and self.check_preview_exists(content.preview):
-            if not self.force:
-                self.debug(f"Preview exists: {content.preview}")
-                self._increment_stat("skipped")
-                return True
-            else:
-                log(f"Force mode: regenerating preview for {content.title}", "info")
-        
-        # List only mode
-        if list_only:
-            print(f"{Colors.YELLOW}Missing preview:{Colors.NC} {file_path}")
-            print(f"  Title: {content.title}")
-            if content.preview:
-                print(f"  Current preview (not found): {content.preview}")
+            return
+        settings = self.settings
+        self.stats.inc("processed")
+        debug(f"Processing file: {path}")
+
+        cf = parse_front_matter(path)
+        if cf is None:
+            self.stats.inc("skipped")
+            return
+
+        if settings.enhance:
+            self._enhance_file(cf)
+            return
+
+        # Generate mode -------------------------------------------------------
+        if cf.preview and check_preview_exists(cf.preview, settings, self.root):
+            if not settings.force:
+                debug(f"Preview already exists and is valid: {cf.preview}")
+                self.stats.inc("skipped")
+                return
+            info(f"Force mode: regenerating preview for {cf.title}")
+
+        if settings.list_only:
+            print(f"{Colors.YELLOW}Missing preview:{Colors.NC} {path}")
+            print(f"  Title: {cf.title}")
+            if cf.preview:
+                print(f"  Current preview (not found): {cf.preview}")
             print()
-            return True
-        
-        log(f"Generating preview for: {content.title}", "info")
-        
-        # Generate filename and paths
-        safe_filename = self.generate_filename(content.title)
-        output_file = self.output_dir / f"{safe_filename}.png"
-        preview_url = f"/{self.output_dir.relative_to(self.project_root)}/{safe_filename}.png"
-        
-        # Generate prompt
-        prompt = self.generate_prompt(content)
-        self.debug(f"Prompt: {prompt[:300]}...")
-        
-        # Dry run mode
-        if self.dry_run:
-            log(f"[DRY RUN] Would generate image:", "info")
-            print(f"  Output: {output_file}")
-            print(f"  Preview URL: {preview_url}")
-            print(f"  Prompt: {prompt[:200]}...")
+            return
+
+        info(f"Generating preview for: {cf.title}")
+
+        slug = generate_filename(cf.title)
+        if not slug:
+            warn(f"Cannot derive filename from title in {path}")
+            self.stats.inc("errors")
+            return
+        out_base = self.root / settings.output_dir / slug
+
+        # Author overrides apply only once an image/prompt is actually built.
+        file_settings = apply_author_overrides(
+            settings, author_preview_overrides(self.authors, cf.author)
+        )
+        if file_settings is not settings:
+            info(f"  ↳ Author '{cf.author}' preview overrides applied (_data/authors.yml)")
+
+        # ---- Analyze: Claude reads the article and writes the art brief ----
+        base_prompt = build_prompt(cf, file_settings)
+        prompt = base_prompt
+        orchestrated = settings.provider != "local"  # local is deterministic
+        if (orchestrated and file_settings.prompt_engine == "claude"
+                and not settings.dry_run):
+            prompt = claude_article_brief(
+                self.ctx.claude(), cf, file_settings, base_prompt)
+        debug(f"Generated prompt: {prompt[:500]}...")
+
+        if settings.dry_run:
+            info("[DRY RUN] Would generate image:")
+            print(f"  Provider: {settings.provider}")
+            if orchestrated and file_settings.prompt_engine == "claude":
+                print("  Prompt engine: claude (article analysis runs at generation time)")
+            if orchestrated and file_settings.review_engine == "claude":
+                print("  Review: claude (image review runs at generation time)")
+            print(f"  Output: {out_base.with_suffix('.png')}")
+            print(f"  Preview path: {preview_front_matter_path(file_settings, slug + '.png')}")
+            print(f"  Prompt: {prompt[:400]}...")
             print()
-            self._increment_stat("generated")
-            return True
-        
-        # Rate limiting
-        self.rate_limiter.acquire()
-        
-        start_time = time.time()
-        
-        # Generate image
-        self.spinner.start(f"Generating: {content.title[:50]}...")
-        result = self.generate_image(prompt, output_file)
-        self.spinner.stop()
-        
-        duration = time.time() - start_time
-        result.duration = duration
-        result.file_path = file_path
-        
-        if result.success:
-            # Update front matter
-            self.spinner.start("Updating front matter...")
-            updated = self.update_front_matter(file_path, preview_url)
-            self.spinner.stop()
-            
-            if updated:
-                log(f"Updated front matter with: {preview_url} ({duration:.1f}s)", "success")
-                self._increment_stat("generated")
-                if isinstance(self.stats, ThreadSafeStats):
-                    self.stats.add_generation_time(duration)
-                return True
+            self.stats.inc("generated")
+            return
+
+        provider = PROVIDERS[settings.provider]
+        # Per-file context copy: workers must not share a mutable slug (the
+        # local provider derives its deterministic seed from it). The copy
+        # carries the shared AnthropicClient reference, which is stateless
+        # after init and therefore thread-safe.
+        file_ctx = replace(self.ctx, slug=slug)
+        # ---- Produce: the selected raster model renders the brief ----
+        result = provider.generate(prompt, file_settings, out_base, file_ctx)
+
+        # ---- Review: Claude inspects the render; at most ONE regeneration ----
+        if (orchestrated and file_settings.review_engine == "claude"
+                and result.ok and result.path and result.kind == "png"):
+            approved, critique, revised = claude_review_image(
+                self.ctx.claude(), result.path, cf, prompt, file_settings)
+            if approved:
+                if critique:
+                    debug(f"Claude review: {critique}")
             else:
-                self._increment_stat("errors")
-                return False
-        else:
-            log(f"Failed to generate image: {result.error}", "warning")
-            self._increment_stat("errors")
-            return False
-    
-    def process_file_parallel(self, file_path: Path) -> Tuple[Path, GenerationResult]:
-        """Thread-safe version of process_file for parallel processing."""
-        global _interrupted
-        if _interrupted:
-            return file_path, GenerationResult(success=False, error="Interrupted")
-        
-        content = self.parse_front_matter(file_path)
-        if not content:
-            self.stats.increment_skipped()
-            return file_path, GenerationResult(success=False, error="No front matter")
-        
-        # Check if preview exists
-        if content.preview and self.check_preview_exists(content.preview):
-            if not self.force:
-                self.stats.increment_skipped()
-                return file_path, GenerationResult(success=True, file_path=file_path)
-        
-        # Generate filename and paths
-        safe_filename = self.generate_filename(content.title)
-        output_file = self.output_dir / f"{safe_filename}.png"
-        preview_url = f"/{self.output_dir.relative_to(self.project_root)}/{safe_filename}.png"
-        
-        # Generate prompt
-        prompt = self.generate_prompt(content)
-        
-        # Rate limiting
-        self.rate_limiter.acquire()
-        
-        start_time = time.time()
-        result = self.generate_image(prompt, output_file)
-        duration = time.time() - start_time
-        result.duration = duration
-        result.file_path = file_path
-        
-        if result.success:
-            if self.update_front_matter(file_path, preview_url):
-                self.stats.increment_generated()
-                self.stats.add_generation_time(duration)
-                return file_path, result
+                info(f"  ↳ Claude review requested a revision: {critique}")
+                debug(f"Revised prompt: {revised[:300]}...")
+                retry = provider.generate(revised, file_settings, out_base, file_ctx)
+                if retry.ok and retry.path:
+                    result = retry
+                    success("  ↳ Regenerated with Claude's revised brief")
+                else:
+                    warn(f"  ↳ Revision render failed "
+                         f"({retry.error or 'unknown'}); keeping the first image")
+
+        if result.ok and result.path:
+            fm_value = preview_front_matter_path(file_settings, result.path.name)
+            if update_front_matter(path, fm_value, dry_run=False):
+                self.stats.inc("generated")
+                # Serial-mode pacing between paid API calls (historical
+                # behavior). In parallel mode a per-worker sleep throttles
+                # nothing — it only burns worker capacity — so skip it.
+                if POST_GENERATION_SLEEP and settings.parallel <= 1:
+                    time.sleep(POST_GENERATION_SLEEP)
             else:
-                self.stats.increment_errors()
-                result.success = False
-                result.error = "Failed to update front matter"
-                return file_path, result
+                self.stats.inc("errors")
         else:
-            self.stats.increment_errors()
-            return file_path, result
-    
-    def process_collection(self, collection_path: Path, list_only: bool = False):
-        """Process all markdown files in a collection."""
-        if not collection_path.exists():
-            log(f"Collection not found: {collection_path}", "warning")
+            warn(f"Failed to generate image for: {cf.title}")
+            if result.error:
+                warn(f"  {result.error}")
+            self.stats.inc("errors")
+
+    def _enhance_file(self, cf: ContentFile) -> None:
+        settings = self.settings
+        existing = find_preview_image(cf.preview, settings, self.root)
+        if existing is None:
+            warn(f"No existing preview image found for: {cf.title}")
+            warn(f"  Expected at: {cf.preview}")
+            warn("  Use without --enhance to generate a new image first.")
+            self.stats.inc("skipped")
             return
-        
-        files = sorted(collection_path.rglob("*.md"))
-        
-        # Apply batch limit
-        if self.batch_limit > 0:
-            files = files[:self.batch_limit]
-            log(f"Batch limit: processing {len(files)} files", "info")
-        
-        if not files:
-            log(f"No markdown files found in {collection_path}", "info")
+
+        info(f"Enhancing preview for: {cf.title}")
+        file_settings = apply_author_overrides(
+            settings, author_preview_overrides(self.authors, cf.author)
+        )
+        prompt = build_enhance_prompt(cf, file_settings)
+        debug(f"Enhancement prompt: {prompt[:400]}...")
+
+        if settings.dry_run:
+            info("[DRY RUN] Would enhance image:")
+            print(f"  Source: {existing}")
+            print(f"  Model: {settings.enhance_model}")
+            print(f"  Prompt: {prompt[:400]}...")
+            print()
+            self.stats.inc("enhanced")
             return
-        
-        if self.workers > 1 and not list_only and not self.dry_run:
-            self._process_collection_parallel(files)
+
+        # --enhance-format other than the current extension writes a NEW file
+        # (content and extension must agree) and repoints the front matter;
+        # the default png-onto-png flow enhances in place with a backup.
+        out_path = existing.with_suffix("." + settings.enhance_format)
+        in_place = out_path == existing
+
+        if in_place:
+            backup = existing.with_name(existing.stem + "_pre-enhance" + existing.suffix)
+            if not backup.exists():
+                shutil.copy2(existing, backup)
+                info(f"Original backed up to: {backup.name}")
+            else:
+                debug(f"Backup already exists: {backup}")
         else:
-            self._process_collection_sequential(files, list_only)
-
-    def _process_collection_sequential(self, files: List[Path], list_only: bool = False):
-        """Process files sequentially with progress tracking."""
-        global _interrupted
-        total = len(files)
-        
-        for i, md_file in enumerate(files):
-            if _interrupted:
-                log("Interrupted! Stopping...", "warning")
-                break
-            
-            if isinstance(self.stats, ProgressStats):
-                log_progress(i + 1, total, "Processing", self.stats)
-            
-            self.process_file(md_file, list_only)
-            self.stats.processed = i + 1
-
-    def _process_collection_parallel(self, files: List[Path]):
-        """Process files in parallel using ThreadPoolExecutor."""
-        global _interrupted
-        total = len(files)
-        
-        log(f"Processing {total} files with {self.workers} workers", "info")
-        
-        if isinstance(self.stats, ThreadSafeStats):
-            self.stats.set_active_workers(self.workers)
-            for f in files:
-                self.stats.add_pending_file(str(f))
-        
-        completed = 0
-        
-        with ThreadPoolExecutor(max_workers=self.workers) as executor:
-            futures = {
-                executor.submit(self.process_file_parallel, f): f
-                for f in files
-            }
-            
+            backup = existing  # original file is untouched and acts as the fallback
+
+        # Capability-driven routing: the active provider's edit() runs when it
+        # has one; EditUnsupported falls back to OpenAI (historical behavior).
+        provider = PROVIDERS[settings.provider]
+        try:
+            result = provider.edit(existing, prompt, file_settings, self.ctx, out_path)
+        except EditUnsupported:
+            warn(f"Enhancement not supported for provider: {settings.provider} "
+                 "(falling back to OpenAI)")
+            openai_provider = PROVIDERS["openai"]
+            if not openai_provider.is_configured(self.ctx.env):
+                warn("Enhance requires OPENAI_API_KEY (the images/edits API is OpenAI-only).")
+                self.stats.inc("errors")
+                return
+            result = openai_provider.edit(existing, prompt, file_settings, self.ctx, out_path)
+
+        if result.ok:
+            if not in_place and result.path and result.path != existing:
+                old_value = cf.preview or ""
+                new_value = (
+                    old_value.rsplit("/", 1)[0] + "/" + result.path.name
+                    if "/" in old_value else result.path.name
+                )
+                update_front_matter(cf.path, new_value, dry_run=False)
+                info(f"Preview extension changed: {existing.name} → {result.path.name}")
+            success(f"Enhanced image saved to: {result.path or existing}")
+            self.stats.inc("enhanced")
+        else:
+            warn(f"Failed to enhance image for: {cf.title}")
+            if result.error:
+                warn(f"  {result.error}")
+            info(f"Original preserved at: {backup}")
+            self.stats.inc("errors")
+
+    # -- collection / run loop ------------------------------------------------
+
+    def process_collection(self, collection_path: Path) -> None:
+        files = self.discover(collection_path)
+        if self.settings.batch > 0:
+            files = files[: self.settings.batch]
+        if not files:
+            return
+        serial = (
+            self.settings.list_only
+            or self.settings.dry_run
+            or self.settings.parallel <= 1
+        )
+        if serial:
+            for file_path in files:
+                if _interrupted:
+                    warn("Interrupted! Stopping...")
+                    break
+                self.process_file(file_path)
+            return
+        with ThreadPoolExecutor(max_workers=self.settings.parallel) as pool:
+            futures = {pool.submit(self.process_file, f): f for f in files}
             for future in as_completed(futures):
                 if _interrupted:
-                    log("Interrupted! Cancelling remaining tasks...", "warning")
-                    for f in futures:
-                        f.cancel()
+                    for pending in futures:
+                        pending.cancel()
+                    warn("Interrupted! Cancelling remaining tasks...")
                     break
-                
-                file_path, result = future.result()
-                completed += 1
-                
-                if isinstance(self.stats, ThreadSafeStats):
-                    self.stats.increment_processed()
-                    self.stats.remove_pending_file(str(file_path))
-                
-                self._show_parallel_progress(completed, total, file_path, result)
-
-    def _show_parallel_progress(self, completed: int, total: int, file_path: Path, result: GenerationResult):
-        """Show progress for parallel processing."""
-        pct = (completed / total) * 100
-        bar_len = 30
-        filled = int(bar_len * completed / total)
-        bar = "█" * filled + "░" * (bar_len - filled)
-        
-        status = f"{Colors.GREEN}✓{Colors.NC}" if result.success else f"{Colors.RED}✗{Colors.NC}"
-        name = file_path.name[:30]
-        duration = f" ({result.duration:.1f}s)" if result.duration > 0 else ""
-        
-        workers_info = ""
-        if isinstance(self.stats, ThreadSafeStats):
-            workers_info = f" [{self.stats.active_workers}w]"
-        
-        print(f"\r  {bar} {pct:5.1f}% ({completed}/{total}){workers_info} {status} {name}{duration}    ", end="", flush=True)
-        
-        if completed == total:
-            print()
-    
-    def print_summary(self):
-        """Print processing summary."""
-        stats = self.stats
-        
-        print()
-        print(f"{Colors.CYAN}{'=' * 50}{Colors.NC}")
-        print(f"{Colors.CYAN}📊 Generation Summary{Colors.NC}")
-        print(f"{Colors.CYAN}{'=' * 50}{Colors.NC}")
-        
-        if isinstance(stats, ThreadSafeStats):
-            print(f"  📁 Files processed:  {stats.processed}")
-            print(f"  🎨 Images generated: {stats.generated}")
-            print(f"  ⏭️  Files skipped:    {stats.skipped}")
-            print(f"  ❌ Errors:           {stats.errors}")
-            
-            if stats.elapsed > 0:
-                print(f"\n  ⏱️  Total time:      {stats.elapsed_str}")
-            if stats.avg_generation_time > 0:
-                print(f"  📈 Avg time/image:   {stats.avg_generation_time:.1f}s")
-            if self.workers > 1:
-                print(f"  👷 Workers used:     {self.workers}")
+                exc = future.exception()
+                if exc:
+                    warn(f"Worker failed on {futures[future]}: {exc}")
+                    self.stats.inc("errors")
+
+    def run(self) -> int:
+        settings = self.settings
+        if settings.file:
+            target = Path(settings.file)
+            if not target.is_absolute():
+                target = self.root / settings.file
+            if not target.is_file():
+                error_exit(f"File not found: {settings.file}")
+            self.process_file(target)
+        elif settings.collection and settings.collection != "all":
+            path = self.collection_path(settings.collection)
+            if not path.is_dir():
+                available = ", ".join(settings.collections)
+                error_exit(
+                    f"Unknown collection: {settings.collection}. "
+                    f"Available: {available}, all"
+                )
+            step(f"Processing {settings.collection} collection...")
+            self.process_collection(path)
         else:
-            print(f"  📁 Files processed:  {stats.processed}")
-            print(f"  🎨 Images generated: {stats.generated}")
-            print(f"  ⏭️  Files skipped:    {stats.skipped}")
-            print(f"  ❌ Errors:           {stats.errors}")
-        
+            step("Processing all configured collections...")
+            for name in settings.collections:
+                path = self.collection_path(name)
+                if path.is_dir():
+                    step(f"Processing {name} collection...")
+                    self.process_collection(path)
+                else:
+                    warn(f"Collection directory not found: {path}")
+
         print()
-        
-        if _interrupted:
-            log("Processing was interrupted by user.", "warning")
-        
-        if self.dry_run:
-            log("This was a dry run. No actual changes were made.", "info")
-        
-        errors = stats.errors if isinstance(stats, ThreadSafeStats) else stats.errors
-        if errors > 0:
-            log("Some files had errors. Check the output above.", "warning")
-
-
-def main():
-    """Main entry point."""
-    global _log_file
-    
-    # Set up signal handlers for graceful shutdown
-    signal.signal(signal.SIGINT, _signal_handler)
-    signal.signal(signal.SIGTERM, _signal_handler)
-    
+        print_header("📊 Summary")
+        print(f"  Files processed: {self.stats.processed}")
+        print(f"  Images generated: {self.stats.generated}")
+        print(f"  Images enhanced: {self.stats.enhanced}")
+        print(f"  Files skipped: {self.stats.skipped}")
+        print(f"  Errors: {self.stats.errors}")
+        print()
+
+        if settings.dry_run:
+            info("This was a dry run. No actual changes were made.")
+        if self.stats.errors > 0:
+            warn("Some files had errors. Check the output above.")
+            return 1
+        success("Preview image generation complete!")
+        return 0
+
+
+# =============================================================================
+# CLI
+# =============================================================================
+
+def build_arg_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
-        description="AI-powered preview image generator for Jekyll content"
-    )
-    parser.add_argument(
-        '-f', '--file',
-        help="Process a specific file only"
-    )
-    parser.add_argument(
-        '-c', '--collection',
-        choices=['posts', 'quickstart', 'docs', 'all'],
-        help="Process specific collection"
-    )
-    parser.add_argument(
-        '-p', '--provider',
-        choices=['openai', 'stability', 'xai'],
-        default='openai',
-        help="AI provider for image generation (openai, stability, xai)"
-    )
-    parser.add_argument(
-        '-d', '--dry-run',
-        action='store_true',
-        help="Preview without making changes"
-    )
-    parser.add_argument(
-        '-v', '--verbose',
-        action='store_true',
-        help="Enable verbose output"
-    )
-    parser.add_argument(
-        '--force',
-        action='store_true',
-        help="Regenerate images even if preview exists"
-    )
-    parser.add_argument(
-        '--list-missing',
-        action='store_true',
-        help="Only list files with missing previews"
-    )
-    parser.add_argument(
-        '--output-dir',
-        default='assets/images/previews',
-        help="Output directory for generated images"
-    )
-    parser.add_argument(
-        '--style',
-        default='digital art, professional blog illustration, clean design',
-        help="Image style prompt"
-    )
-    parser.add_argument(
-        '--assets-prefix',
-        default='/assets',
-        help="Prefix to prepend to relative preview paths (default: /assets)"
+        prog="generate-preview-images",
+        description="AI-powered preview image generator for Jekyll content "
+                    "(providers: claude [default], openai, xai, stability, gemini, local)",
     )
-    parser.add_argument(
-        '--no-auto-prefix',
-        action='store_true',
-        help="Disable automatic assets prefix prepending"
-    )
-    parser.add_argument(
-        '--batch',
-        type=int,
-        default=0,
-        help="Limit number of files to process (0 = no limit)"
-    )
-    parser.add_argument(
-        '--log-file',
-        help="Write log output to file"
-    )
-    parser.add_argument(
-        '-w', '--workers',
-        type=int,
-        default=1,
-        help="Number of parallel workers (default: 1 = sequential)"
-    )
-    parser.add_argument(
-        '--rate-limit',
-        type=int,
-        default=5,
-        help="Max API requests per minute (default: 5)"
-    )
-    
-    args = parser.parse_args()
-    
-    # Set up log file
+    parser.add_argument("-d", "--dry-run", action="store_true",
+                        help="Preview what would be generated (no changes)")
+    parser.add_argument("-v", "--verbose", action="store_true",
+                        help="Enable verbose output")
+    parser.add_argument("-f", "--file", help="Process a specific file only")
+    parser.add_argument("-c", "--collection",
+                        help="Process specific collection (posts, quickstart, docs, all)")
+    parser.add_argument("-p", "--provider",
+                        choices=sorted(PROVIDERS.keys()),
+                        help="AI provider (default: claude, via _config.yml)")
+    parser.add_argument("--model", help="Override the image/SVG model for the provider")
+    parser.add_argument("--output-dir",
+                        help="Output directory for images (default: assets/images/previews)")
+    parser.add_argument("--force", action="store_true",
+                        help="Regenerate images even if preview exists")
+    parser.add_argument("--list-missing", action="store_true",
+                        help="Only list files with missing previews")
+    parser.add_argument("-j", "--parallel", "-w", "--workers", type=int, default=None,
+                        dest="parallel", metavar="N",
+                        help="Concurrent workers (default 4; serial for dry-run/list)")
+    parser.add_argument("-e", "--enhance", action="store_true",
+                        help="Enhance existing preview images (OpenAI images/edits)")
+    parser.add_argument("--enhance-prompt", help="Custom enhancement prompt (implies --enhance)")
+    parser.add_argument("--enhance-model", help="Model for enhancement (default: gpt-image-2)")
+    parser.add_argument("--enhance-quality", choices=["low", "medium", "high", "auto"],
+                        help="Enhancement quality (default: auto)")
+    parser.add_argument("--enhance-fidelity", choices=["high", "low"],
+                        help="Input fidelity (implies --enhance)")
+    parser.add_argument("--enhance-format", choices=["png", "jpeg", "webp"],
+                        help="Enhanced output format (implies --enhance)")
+    parser.add_argument("--prompt-engine", choices=["template", "claude"],
+                        help="Art-direction brief: claude analyzes the article "
+                             "(default) or template uses the built-in prompt")
+    parser.add_argument("--review", choices=["claude", "none"],
+                        help="Post-render review: claude inspects the image and "
+                             "may request one refined regeneration (default: claude)")
+    parser.add_argument("--rasterizer",
+                        choices=["auto", "rsvg", "inkscape", "magick", "playwright", "none"],
+                        help="SVG→PNG tool for claude/local providers (default: auto)")
+    parser.add_argument("--style", help="Override image style prompt")
+    parser.add_argument("--assets-prefix", help="Assets prefix for path normalization")
+    parser.add_argument("--no-auto-prefix", action="store_true",
+                        help="Disable automatic assets prefix prepending")
+    parser.add_argument("--batch", type=int, default=0,
+                        help="Limit number of files processed (0 = no limit)")
+    parser.add_argument("--log-file", help="Also write log output to a file")
+    # Accepted for backward compatibility with the previous engine's CLI;
+    # pacing is now handled by with_retries (Retry-After aware) + -j workers.
+    parser.add_argument("--rate-limit", type=int, dest="rate_limit",
+                        help=argparse.SUPPRESS)
+    return parser
+
+
+def parse_args(argv: Optional[List[str]] = None) -> argparse.Namespace:
+    args = build_arg_parser().parse_args(argv)
+    # Historical flag semantics: these imply --enhance (--enhance-model does not).
+    if args.enhance_prompt or args.enhance_fidelity or args.enhance_format:
+        args.enhance = True
+    return args
+
+
+def validate_credentials(settings: Settings, ctx: RunContext) -> None:
+    """Credential checks are skipped for --list-missing/--dry-run (historical
+    behavior), but an unknown provider name (from AI_PROVIDER / _config.yml —
+    argparse already constrains -p) errors in every mode."""
+    provider = PROVIDERS.get(settings.provider)
+    if provider is None:
+        error_exit(f"Unknown AI provider: {settings.provider}. "
+                   f"Available: {', '.join(sorted(PROVIDERS))}")
+    if settings.list_only or settings.dry_run:
+        return
+    if provider.name == "local":
+        info("Using local provider - no API key required")
+        return
+    if not provider.is_configured(ctx.env):
+        error_exit(provider.missing_hint(ctx.env))
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    global VERBOSE, _log_file
+
+    signal.signal(signal.SIGINT, _signal_handler)
+    signal.signal(signal.SIGTERM, _signal_handler)
+
+    args = parse_args(argv)
+    ensure_yaml()
+    _load_dotenv()
+
+    project_root = find_project_root()
+    site_config = read_site_config(project_root)
+    settings = resolve_settings(args, site_config)
+    VERBOSE = settings.verbose
+
     if args.log_file:
         try:
-            _log_file = open(args.log_file, 'w')
-            log(f"Logging to: {args.log_file}", "info")
-        except IOError as e:
-            log(f"Cannot open log file: {e}", "warning")
-    
-    # Determine project root
-    script_dir = Path(__file__).parent
-    project_root = script_dir.parent.parent
-    
-    # Initialize generator
-    generator = PreviewGenerator(
-        project_root=project_root,
-        provider=args.provider,
-        output_dir=args.output_dir,
-        image_style=args.style,
-        assets_prefix=args.assets_prefix,
-        auto_prefix=not args.no_auto_prefix,
-        dry_run=args.dry_run,
-        verbose=args.verbose,
-        force=args.force,
-        batch_limit=args.batch,
-        workers=args.workers,
-        rate_limit=args.rate_limit,
+            _log_file = open(args.log_file, "w", encoding="utf-8")
+            info(f"Logging to: {args.log_file}")
+        except OSError as exc:
+            warn(f"Cannot open log file: {exc}")
+
+    explicitly_targeted = (
+        settings.file or settings.collection or settings.enhance
+        or settings.provider_explicit
     )
-    
-    print(f"{Colors.BLUE}{'=' * 50}{Colors.NC}")
-    print(f"{Colors.BLUE}🎨 Preview Image Generator{Colors.NC}")
-    print(f"{Colors.BLUE}{'=' * 50}{Colors.NC}")
-    print()
-    
-    log(f"Provider:    {args.provider}", "info")
-    log(f"Output Dir:  {args.output_dir}", "info")
-    log(f"Workers:     {args.workers}", "info")
-    log(f"Rate Limit:  {args.rate_limit} req/min", "info")
-    log(f"Dry Run:     {args.dry_run}", "info")
-    if args.batch > 0:
-        log(f"Batch Limit: {args.batch}", "info")
-    print()
-    
-    # Process files
-    if args.file:
-        file_path = Path(args.file)
-        if not file_path.is_absolute():
-            file_path = project_root / file_path
-        generator.process_file(file_path, args.list_missing)
-    elif args.collection:
-        collections = {
-            'posts': project_root / 'pages' / '_posts',
-            'quickstart': project_root / 'pages' / '_quickstart',
-            'docs': project_root / 'pages' / '_docs',
-        }
-        
-        if args.collection == 'all':
-            for name, path in collections.items():
-                log(f"Processing {name}...", "step")
-                generator.process_collection(path, args.list_missing)
+    if not settings.enabled and not explicitly_targeted:
+        info("preview_images.enabled is false in _config.yml — nothing to do "
+             "(pass --provider, --file or --collection to override).")
+        return 0
+
+    print_header("🎨 Preview Image Generator")
+    ctx = RunContext(project_root=project_root, env=dict(os.environ))
+    validate_credentials(settings, ctx)
+
+    # Claude orchestration (analyze/review) degrades gracefully: without a
+    # Claude credential the run continues on template prompts, unreviewed.
+    wants_claude = (
+        settings.provider != "local"
+        and "claude" in (settings.prompt_engine, settings.review_engine)
+        and not (settings.dry_run or settings.list_only)
+    )
+    if wants_claude:
+        if ctx.claude().available():
+            info(f"Claude orchestration: {ctx.claude().describe()}")
         else:
-            log(f"Processing {args.collection}...", "step")
-            generator.process_collection(collections[args.collection], args.list_missing)
-    else:
-        # Default: process all
-        collections = [
-            project_root / 'pages' / '_posts',
-            project_root / 'pages' / '_quickstart',
-            project_root / 'pages' / '_docs',
-        ]
-        for collection in collections:
-            log(f"Processing {collection.name}...", "step")
-            generator.process_collection(collection, args.list_missing)
-    
-    generator.print_summary()
-    
-    # Close log file
+            warn(CLAUDE_CREDENTIAL_HINT)
+            settings = replace(settings, prompt_engine="template", review_engine="none")
+
+    output_dir = project_root / settings.output_dir
+    if not settings.dry_run and not settings.list_only:
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+    info("Configuration:")
+    print(f"  AI Provider: {settings.provider}")
+    print(f"  Image Model: {settings.model or PROVIDERS[settings.provider].default_model()}")
+    print(f"  Output Dir: {settings.output_dir}")
+    print(f"  Image Size: {settings.size}")
+    print(f"  Parallel Workers: {settings.parallel}")
+    print(f"  Dry Run: {str(settings.dry_run).lower()}")
+    print(f"  Force: {str(settings.force).lower()}")
+    print(f"  List Only: {str(settings.list_only).lower()}")
+    print(f"  Prompt Engine: {settings.prompt_engine}")
+    print(f"  Review: {settings.review_engine}")
+    if settings.enhance:
+        print("  Mode: ENHANCE (improve existing images)")
+        print(f"  Enhance Model: {settings.enhance_model}")
+        print(f"  Enhance Quality: {settings.enhance_quality}")
+        print(f"  Input Fidelity: {settings.enhance_fidelity}")
+        print(f"  Output Format: {settings.enhance_format}")
+        if settings.enhance_prompt:
+            print(f"  Custom Prompt: {settings.enhance_prompt[:80]}...")
+        else:
+            print("  Prompt: (default improvement prompt)")
+    print()
+
+    runner = Runner(settings, project_root, ctx=ctx)
+    exit_code = runner.run()
+
     if _log_file:
         _log_file.close()
-    
-    errors = generator.stats.errors if isinstance(generator.stats, ThreadSafeStats) else generator.stats.errors
-    return 0 if errors == 0 else 1
+    return exit_code
 
 
 if __name__ == "__main__":