ci: harden cto-review.yml severity KeyError (v0.18.3)

QA (seq 43) identified a content-triggered KeyError in the CTO-Review
postprocessor: when a model returns a concerns[] item without a 'severity'
key, line 454 crashed with KeyError instead of degrading.

  sev = c[severity].upper()        # before — hard KeyError
  sev = c.get("severity", "UNKNOWN").upper()  # after — degrades gracefully

The JSON schema marks severity as required but the postprocessor does not
enforce it — a model deviating on a large diff (91K bytes for f10e177 vs
41K for 02e9aab) triggered the crash. The fix surfaces UNKNOWN-severity
concerns rather than killing the check.

No other workflow changes.

Agent-Session: prab-v0183-20260612

.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php: ['7.4', '8.1', '8.3']
+        php: ['8.1', '8.2', '8.3']
     steps:
       - uses: actions/checkout@v4
       - name: Setup PHP ${{ matrix.php }}
@@ -31,7 +31,7 @@ jobs:
           coverage: none
       - name: Syntax check all PHP files
         # Exclude .github/mu-plugins — those run on the production server (PHP 8+)
-        # and may use PHP 8+ syntax (union types etc.) that 7.4 rejects.
+        # and may use PHP 8+ syntax (union types etc.) that older versions reject.
         run: |
           set -e
           find . -name '*.php' \
@@ -44,9 +44,14 @@ jobs:
   phpcs:
     name: PHPCS (WordPress standards)
     runs-on: ubuntu-latest
-    continue-on-error: true  # non-blocking for now — see CONVENTIONS.md
+    continue-on-error: false  # strict after PHPCS cleanup in v0.8.3
+    permissions:
+      contents: write  # allows phpcbf auto-fix commits back to the PR branch
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref || github.ref_name }}
+          token: ${{ secrets.GITHUB_TOKEN }}
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
@@ -55,22 +60,34 @@ jobs:
           tools: composer:v2, phpcs
       - name: Install WordPress Coding Standards
         run: |
-          # Allow the PHPCS composer-installer plugin (auto-registers standards).
           composer global config --no-plugins allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
-          # WPCS 3.x requires PHPCSExtra (for the Universal.* and NormalizedArrays.* sniffs)
-          # AND phpcsutils. Installing the installer itself lets it auto-register the standards path.
           composer global require --no-interaction \
             "dealerdirect/phpcodesniffer-composer-installer:^1.0" \
             "wp-coding-standards/wpcs:^3.0" \
             "phpcsstandards/phpcsutils:^1.0" \
             "phpcsstandards/phpcsextra:^1.0"
-      - name: Run PHPCS
+      - name: Auto-fix with phpcbf (commit back to branch if changed)
+        # phpcbf exits 1 when it makes fixes, 0 when nothing to fix — both are success here.
+        # Commits made via GITHUB_TOKEN do not trigger a new CI run (GitHub prevents loops).
         run: |
-          phpcs --standard=WordPress-Core \
+          phpcbf --standard=phpcs.xml \
+            --extensions=php \
+            --ignore=vendor/*,tests/*,node_modules/* \
+            includes/ prautoblogger.php uninstall.php || true
+          if ! git diff --quiet; then
+            git config user.name "peptiderepo"
+            git config user.email "peptiderepo@users.noreply.github.com"
+            git add -A
+            git commit -m "style: auto-fix PHPCS violations via phpcbf"
+            git push
+          fi
+      - name: Run PHPCS (only non-auto-fixable violations can fail here)
+        run: |
+          phpcs --standard=phpcs.xml \
             --extensions=php \
             --ignore=vendor/*,tests/*,node_modules/* \
             --warning-severity=0 \
-            --report=summary \
+            --report=full \
             includes/ prautoblogger.php uninstall.php
 
   phpunit:
@@ -79,7 +96,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php: ['7.4', '8.1', '8.3']
+        php: ['8.1', '8.2', '8.3']
     steps:
       - uses: actions/checkout@v4
       - name: Setup PHP ${{ matrix.php }}

.github/workflows/cto-review.yml

@@ -123,17 +123,18 @@ jobs:
           git fetch origin ${{ github.event.pull_request.base.ref }} --depth=50
           BASE_SHA="${{ github.event.pull_request.base.sha }}"
           HEAD_SHA="${{ github.event.pull_request.head.sha }}"
-          DIFF=$(git diff --no-color "$BASE_SHA" "$HEAD_SHA" | head -c 400000)
+          # Write the diff to a file, not a step output / env var. Passing a
+          # ~400KB diff through the process env (execve argv+envp) exceeds the
+          # runner ARG_MAX and fails the next step with "Argument list too long"
+          # (issue #110). File transport also sidesteps the ~1MB step-output cap.
+          git diff --no-color "$BASE_SHA" "$HEAD_SHA" | head -c 400000 > /tmp/cto-review-diff.txt
           FILES=$(git diff --name-only "$BASE_SHA" "$HEAD_SHA")
-          SIZE=$(echo -n "$DIFF" | wc -c)
+          SIZE=$(wc -c < /tmp/cto-review-diff.txt)
           {
             echo "size=$SIZE"
             echo "files<<EOF_FILES"
             echo "$FILES"
             echo "EOF_FILES"
-            echo "diff<<EOF_DIFF"
-            echo "$DIFF"
-            echo "EOF_DIFF"
           } >> "$GITHUB_OUTPUT"
 
       - name: Load repo conventions
@@ -161,7 +162,7 @@ jobs:
           PR_AUTHOR: ${{ github.event.pull_request.user.login }}
           PR_NUMBER: ${{ github.event.pull_request.number }}
           REPO_NAME: ${{ github.event.repository.name }}
-          DIFF: ${{ steps.diff.outputs.diff }}
+          DIFF_PATH: /tmp/cto-review-diff.txt
           DIFF_SIZE: ${{ steps.diff.outputs.size }}
           CHANGED_FILES: ${{ steps.diff.outputs.files }}
           CONVENTIONS: ${{ steps.conventions.outputs.content }}
@@ -208,7 +209,8 @@ jobs:
           1. Assess whether the change is safe to merge and deploy to production (peptiderepo.com on Hostinger WordPress).
           2. Flag security issues, cost traps (paid AI API usage), performance regressions, missing input sanitization, missing output escaping, hardcoded secrets, broken migrations, or violations of the repo's CONVENTIONS.md.
           3. Check that the PR follows the project's git workflow: branch naming (claude/<scope>-<date>), Agent-Session trailer in commits, PR description covers what/why/risk/test-plan.
-          4. Be concise and direct. No pleasantries. Call out concrete line-level issues when possible.
+          4. CTO app-map freshness. If this PR modifies any of: (a) the admin settings surface (register_setting, add_submenu_page, add_options_page, settings field labels, option keys, types, defaults); (b) the file/class structure (any file added, renamed, split per the 300-line rule, or materially restructured); or (c) the data flow (new external API client, new hook/filter fired publicly, new scheduled job, or changed class responsibilities) — then the PR description MUST include a line referencing an accompanying update to `Peptide Repo CTO/app-maps/<repo-slug>.md`. The CTO workspace is a separate repo, so CI cannot verify the doc update mechanically — you must inspect the PR description for an explicit mention. If the description is silent despite a triggering change, raise this as a MAJOR concern (not blocking) so the author can add the mention or open a follow-up PR on the CTO workspace.
+          5. Be concise and direct. No pleasantries. Call out concrete line-level issues when possible.
 
           You MUST respond by calling the submit_review function. Do not write prose outside the tool call.
 
@@ -228,7 +230,9 @@ jobs:
           user_blocks.append(f"**Changed files:**\n```\n{os.environ['CHANGED_FILES']}\n```\n")
           if os.environ.get("CONVENTIONS", "").strip():
               user_blocks.append(f"# Repo CONVENTIONS.md\n{os.environ['CONVENTIONS']}\n")
-          user_blocks.append(f"# Diff\n```diff\n{os.environ['DIFF']}\n```\n")
+          with open(os.environ["DIFF_PATH"], encoding="utf-8", errors="replace") as _df:
+              _diff_text = _df.read()
+          user_blocks.append(f"# Diff\n```diff\n{_diff_text}\n```\n")
           user_message = "\n\n".join(user_blocks)
 
           tools = [{
@@ -447,7 +451,7 @@ jobs:
               if rev.get("concerns"):
                   lines.append("**Concerns:**")
                   for c in rev["concerns"]:
-                      sev = c["severity"].upper()
+                      sev = c.get("severity", "UNKNOWN").upper()
                       f = f"`{c['file']}`" if c.get("file") else ""
                       lines.append(f"- **{sev}** {f} — {c['issue']}")
                   lines.append("")

.github/workflows/deploy.yml

@@ -4,104 +4,34 @@ on:
   push:
     branches: [main]
 
+concurrency:
+  group: deploy-prautoblogger-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   validate:
-    name: Validate Code Quality
+    name: PHP Lint Gate
     runs-on: ubuntu-latest
-
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
+      - uses: actions/checkout@v4
+      - uses: shivammathur/setup-php@v2
         with:
           php-version: '8.1'
-          tools: composer, phpcs
           coverage: none
-
       - name: PHP Lint Check
         run: |
-          find . -name "*.php" -not -path "./vendor/*" -not -path "./node_modules/*" -exec php -l {} \; | (grep -v "No syntax errors" || true) | head -20
-          test ${PIPESTATUS[0]} -eq 0
-
-      - name: Install Composer dependencies
-        run: composer install --no-interaction --prefer-dist
-
-      - name: Install WordPress Coding Standards
-        run: |
-          # Composer 2.2+ blocks plugins by default. The WPCS installer needs
-          # dealerdirect/phpcodesniffer-composer-installer to wire standards
-          # into PHPCS. Allow it globally before requiring WPCS.
-          composer global config --no-plugins allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
-          composer global require "wp-coding-standards/wpcs:^3.0" "phpcsstandards/phpcsutils:^1.0" --no-interaction
-          phpcs --config-set installed_paths "$(composer global config home)/vendor/wp-coding-standards/wpcs"
-
-      - name: Run PHPCS (WordPress standards)
-        run: |
-          phpcs --standard=WordPress-Core \
-            --extensions=php \
-            --ignore=vendor/*,tests/*,node_modules/* \
-            --warning-severity=0 \
-            --report=summary \
-            includes/ prautoblogger.php uninstall.php || true
-
-      - name: Run PHPUnit
-        run: vendor/bin/phpunit --testdox
+          set -e
+          find . -name '*.php' \
+            -not -path './vendor/*' \
+            -not -path './node_modules/*' \
+            -not -path './.git/*' \
+            -not -path './.github/*' \
+            -print0 | xargs -0 -n1 -P4 php -l > /dev/null
 
   deploy:
+    name: Deploy (shared pipeline)
     needs: validate
-    name: Deploy to Production
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup SSH key
-        run: |
-          mkdir -p ~/.ssh
-          echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/deploy_key
-          chmod 600 ~/.ssh/deploy_key
-          ssh-keyscan -p ${{ secrets.SSH_PORT }} ${{ secrets.SSH_HOST }} >> ~/.ssh/known_hosts 2>/dev/null
-
-      - name: Deploy via rsync
-        run: |
-          rsync -avz --delete \
-            --exclude '.git' \
-            --exclude '.github' \
-            --exclude 'tests' \
-            --exclude 'phpunit.xml.dist' \
-            --exclude 'composer.json' \
-            --exclude 'composer.lock' \
-            --exclude 'vendor' \
-            --exclude '.distignore' \
-            --exclude 'ARCHITECTURE.md' \
-            --exclude 'CONVENTIONS.md' \
-            -e "ssh -i ~/.ssh/deploy_key -p ${{ secrets.SSH_PORT }}" \
-            ./ ${{ secrets.SSH_USERNAME }}@${{ secrets.SSH_HOST }}:~/domains/peptiderepo.com/public_html/wp-content/plugins/prautoblogger/
-
-      - name: Purge LiteSpeed Cache
-        run: |
-          ssh -i ~/.ssh/deploy_key -p ${{ secrets.SSH_PORT }} \
-            ${{ secrets.SSH_USERNAME }}@${{ secrets.SSH_HOST }} \
-            "cd ~/domains/peptiderepo.com/public_html && find wp-content/litespeed/ -type f -delete 2>/dev/null; touch .lscache_purge 2>/dev/null || true"
-
-      - name: Health check
-        run: |
-          sleep 5
-          STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://peptiderepo.com)
-          # 200 = normal healthy response.
-          # 403 = peptide-starter-theme v1.5.2 CF-peer validator rejecting this
-          #       GHA-runner direct-to-origin request as non-Cloudflare traffic.
-          #       That rejection is the validator working — itself a positive
-          #       liveness signal. Real user traffic via Cloudflare gets 200.
-          if [ "$STATUS" != "200" ] && [ "$STATUS" != "403" ]; then
-            echo "ERROR: Site returned unexpected HTTP $STATUS after deploy"
-            exit 1
-          fi
-          echo "Site is responsive (HTTP $STATUS)"
-
-      - name: Cleanup
-        if: always()
-        run: rm -f ~/.ssh/deploy_key
+    uses: peptiderepo/peptide-e2e/.github/workflows/deploy-app.yml@main
+    with:
+      target_path: wp-content/plugins/prautoblogger
+    secrets: inherit

.github/workflows/main-push-audit.yml

@@ -29,12 +29,22 @@ jobs:
         with:
           script: |
             const sha = context.sha;
-            const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              commit_sha: sha,
-            });
-            const merged = prs.find(p => p.merged_at);
+            // Squash-merge -> PR association is eventually-consistent; poll briefly
+            // before concluding this was a direct push (avoids false positives on merges).
+            async function findMergedPR() {
+              for (let attempt = 1; attempt <= 5; attempt++) {
+                const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  commit_sha: sha,
+                });
+                const m = prs.find(p => p.merged_at);
+                if (m) return m;
+                if (attempt < 5) await new Promise(r => setTimeout(r, 10000));
+              }
+              return null;
+            }
+            const merged = await findMergedPR();
             if (merged) {
               core.info(`OK: commit ${sha.substring(0,7)} came from PR #${merged.number}`);
               return;

ARCHITECTURE.md

@@ -16,9 +16,10 @@ PRAutoBlogger is a WordPress plugin that monitors social media (starting with Re
              │
              ▼
 ┌─────────────────────────┐
-│  1. Source Collector     │  Pulls raw posts/comments from social platforms
-│  (Reddit RSS primary    │  Reddit RSS/Atom feeds (primary) / .json (fallback)
-│   / .json fallback)        Stores raw data in `ab_source_data` table
+│  1. Source Collector     │  Pulls data from enabled sources:
+│  (Reddit + LLM Research)│  - Reddit RSS/Atom (primary) / .json (fallback)
+│                         │  - LLM Deep Research (reasoning model)
+│                         │  Stores raw data in `ab_source_data` table
 └────────────┬────────────┘
              │
              ▼
@@ -65,6 +66,25 @@ PRAutoBlogger is a WordPress plugin that monitors social media (starting with Re
              │
              ▼
 ┌─────────────────────────┐
+│  6b. Image Pipeline     │  Generates two A/B images in parallel:
+│  (optional, if enabled) │  - Image A: article-driven (featured)
+│                         │  - Image B: source-driven (post meta)
+│                         │  Provider derived from the saved Image Model
+│                         │  via Image_Model_Registry::provider_for().
+│                         │  NSFW-blocked slots (CF error code 3030) are
+│                         │  retried once with a rule-based fallback
+│                         │  prompt via Image_NSFW_Retry; a second block
+│                         │  logs WARNING and publishes without that image.
+│                         │  v0.17.0: results then pass through the local
+│                         │  deterministic Image_Composer (corner mark +
+│                         │  branded OG/square variants for Image A; mark
+│                         │  only for Image B) with a capability ladder
+│                         │  (imagick → GD resize-only → pass-through).
+│                         │  Sideloads to media library, logs costs.
+└────────────┬────────────┘
+             │
+             ▼
+┌─────────────────────────┐
 │  7. Metrics Collector   │  Tracks post-publish performance:
 │  (Separate cron job)    │  - WordPress native (views, comments)
 │                         │  - GA4 (pageviews, bounce rate, time on page)
@@ -88,6 +108,15 @@ prautoblogger/
 ├── CHANGELOG.md                       # Semantic versioning changelog
 │
 ├── assets/
+│   ├── brand/                         # Vendored brand PNGs rasterized from peptide-repo-brand SVGs (composer overlays)
+│   │   ├── logo-mark-small-56.png     # Corner mark, 1x
+│   │   ├── logo-mark-small-112.png    # Corner mark / OG band logo, 2x
+│   │   ├── logo-horizontal-reverse-128.png # Square footer lockup, 1x
+│   │   └── logo-horizontal-reverse-256.png # Square footer lockup, 2x
+│   ├── fonts/                         # Bundled OFL faces for deterministic text rendering
+│   │   ├── Poppins-Bold.ttf           # Square-card caption face
+│   │   ├── Poppins-SemiBold.ttf       # OG band caption face
+│   │   └── OFL.txt                    # SIL Open Font License
 │   ├── css/
 │   │   ├── admin.css                  # Admin page styles (wp-admin conventions)
 │   │   └── posts-widget.css           # Frontend posts widget styles (uses theme CSS vars)
@@ -96,18 +125,27 @@ prautoblogger/
 │       └── posts-widget.js            # React component for frontend post cards (wp.element)
 │
 ├── includes/
-│   ├── class-prautoblogger.php        # Main orchestrator — registers all hooks via loader
+│   ├── class-prautoblogger.php        # Main orchestrator — registers all hooks, delegates execution
+│   ├── class-pipeline-schema-installer.php # v0.18.0 substrate tables (prompts, run_sources, run_decisions, runs, run_stages)
+│   ├── class-migrate-prompt-seed-v0180.php # One-shot v0.18.0 prompt-registry seed migration
+│   ├── class-executor.php             # Cron handlers, generation AJAX (delegates start + status to poller), model registry
+│   ├── class-generation-status-poller.php # Generation AJAX handlers: status transient renewal, lock-age orphan detection (R2b/R3), abort_orphaned_run
+│   ├── class-ajax-handlers.php        # Non-generation AJAX: images, models, test connections
+│   ├── class-generation-lock.php      # DB-level atomic mutex for single-writer generation
 │   ├── class-activator.php            # Activation: create DB tables, set defaults, schedule cron
 │   ├── class-deactivator.php          # Deactivation: clear cron, cleanup transients
 │   ├── class-autoloader.php           # PSR-4-style autoloader for plugin classes
 │   │
 │   ├── admin/
 │   │   ├── class-admin-page.php       # Main settings page (tabbed SaaS-style UI)
-│   │   ├── class-settings-fields.php  # Declarative settings definitions (sections + fields)
+│   │   ├── class-settings-fields.php  # Declarative settings: sections + core fields (API/Models/Content/Sources)
+│   │   ├── class-settings-fields-extended.php # Operational fields: schedule, publishing, display, analytics, images
+│   │   ├── class-image-model-registry.php # Static list of image generation models for the model picker
 │   │   ├── class-admin-notices.php    # Onboarding notices, error alerts, budget warnings
 │   │   ├── class-dashboard-widget.php # WP Dashboard widget showing generation status
 │   │   ├── class-post-metabox.php     # Metabox on posts showing generation metadata
 │   │   ├── class-metrics-page.php     # Admin page for cost dashboard and content scores
+│   │   ├── class-ideas-browser.php    # Browse all analysis results (article ideas)
 │   │   ├── class-review-queue.php     # Approve/edit/reject queue for generated drafts
 │   │   └── class-log-viewer.php       # Activity log viewer with level filtering
 │   │
@@ -115,31 +153,79 @@ prautoblogger/
 │   │   ├── class-scheduler.php        # WP-Cron / Action Scheduler job management
 │   │   ├── class-source-collector.php # Orchestrates data collection from all sources
 │   │   ├── class-content-analyzer.php # LLM-powered analysis of collected social data
-│   │   ├── class-idea-scorer.php      # Ranks and deduplicates article ideas
+│   │   ├── class-analysis-prompts.php # System/user prompt builders + performance context for analyzer
+│   │   ├── class-idea-scorer.php      # Ranks and deduplicates article ideas (delegates to Semantic_Dedup)
+│   │   ├── class-semantic-dedup.php   # Embedding-based cosine similarity dedup with keyword fallback
 │   │   ├── class-content-generator.php# Writer agent — manages the generation pipeline
+│   │   ├── class-content-prompts.php  # Builds all LLM prompts for content generation (system, stage, linking rules)
+│   │   ├── class-peptide-linker.php   # Deterministic post-processor: hyperlinks peptide mentions to /peptides/ pages
 │   │   ├── class-chief-editor.php     # Editor agent — LLM-powered editorial review
 │   │   ├── class-publisher.php        # Creates WordPress posts from approved content
+│   │   ├── class-post-assembler.php   # Post-creation helpers: taxonomy, log linking, images, sanitization
+│   │   ├── class-image-pipeline.php   # Orchestrates A/B image generation (parallel via batch)
+│   │   ├── class-image-prompt-builder.php # Generates visual prompts from article/source data
+│   │   ├── class-image-template-filler.php # Fills the editorial style template's {{ topic_summary }} slot (v0.16.0)
+│   │   ├── interface-image-composer.php    # Contract: provider bytes → featured-first variant list (v0.17.0)
+│   │   ├── class-image-composer.php        # Composer orchestrator: cached capability probe + degradation ladder
+│   │   ├── class-image-composer-imagick.php # Imagick renderer: corner mark, OG band, square card (WP-free)
+│   │   ├── class-image-composer-canvas.php # Imagick primitives: smoke test, cover-crop, logo, deterministic PNG (WP-free)
+│   │   ├── class-image-composer-editor.php # Resize-only rung via wp_get_image_editor (GD path)
+│   │   ├── class-image-composer-layout.php # Geometry defaults + caption clamp (pure, WP-free)
+│   │   ├── class-image-attacher.php        # Sideload + cost log + variant meta-linking + caption prepend
+│   │   ├── class-image-media-sideloader.php # Imports images into WordPress media library
 │   │   ├── class-cost-tracker.php     # Logs all API costs, enforces budget limits
+│   │   ├── class-stage-display-map.php # Stage vocabulary: labels + default roles + prompt keys (old + new + image stages)
+│   │   ├── class-prompt-registry.php  # Versioned prompt registry, read side (render, pins, self-healing fallback)
+│   │   ├── class-prompt-registry-writer.php # Registry write side (create version, activate, seed) — versions immutable
+│   │   ├── class-prompt-defaults.php  # Canonical v1 bodies: content.* + analysis.* (seed + fallback single source)
+│   │   ├── class-prompt-defaults-editorial.php # Canonical v1 bodies: editor.* / research.system / image.* (composer seam)
+│   │   ├── class-run-context.php      # Per-process active run id (set by Cost_Tracker::set_run_id)
+│   │   ├── class-run-state.php        # runs-table ledger + lifecycle row (ceiling/reserved/settled, pins, status)
+│   │   ├── class-cost-governor.php    # Per-run reserve-before-call enforcement (atomic conditional UPDATE)
+│   │   ├── class-cost-ceiling-exception.php # Thrown on ceiling breach (run already halted)
+│   │   ├── class-run-stage-state.php  # Per-run per-stage state machine (idempotent resume, output snapshots)
+│   │   ├── class-run-reaper.php       # Stuck-run sweep + audit-payload retention (rides the #19 cron)
+│   │   ├── class-audit-writer.php     # run_sources / run_decisions insert layer
+│   │   ├── class-pipeline-status.php  # Status-transient + summary helpers (extracted from runner/worker)
 │   │   ├── class-logger.php           # Structured logging singleton (error/warning/info/debug)
-│   │   ├── class-pipeline-runner.php  # Orchestrates the full generation pipeline
+│   │   ├── class-article-worker.php   # Single-article generation (content + edit + publish)
+│   │   ├── class-pipeline-runner.php  # Orchestrates pipeline; chains per-article cron jobs
 │   │   ├── class-ga4-client.php       # Google Analytics 4 API client (OAuth + Data API)
 │   │   └── class-metrics-collector.php# Collects post performance data (WP + GA4)
 │   │
 │   ├── providers/
 │   │   ├── interface-llm-provider.php    # Contract for any LLM provider
-│   │   ├── class-open-router-provider.php # OpenRouter API implementation
+│   │   ├── class-open-router-provider.php # OpenRouter API implementation (chat completions)
+│   │   ├── class-open-router-completion-guard.php # Empty-completion guard: warn on finish_reason=length, one reasoning-off retry, audited failure (v0.18.1)
+│   │   ├── class-open-router-embedding-provider.php # Text embeddings for semantic dedup
 │   │   ├── class-open-router-pricing.php  # Model pricing lookup and cost estimation
 │   │   ├── interface-source-provider.php # Contract for any social media source
 │   │   ├── class-reddit-json-client.php  # Reddit HTTP client — RSS (primary) + .json (fallback)
+│   │   ├── class-llm-research-provider.php # LLM deep research source (reasoning models)
 │   │   ├── class-reddit-provider.php     # Reddit data collection orchestrator (RSS primary)
-│   │   ├── interface-image-provider.php  # Contract for any image generation provider
-│   │   ├── class-cloudflare-image-provider.php  # FLUX.1 via Cloudflare Workers AI
-│   │   ├── class-cloudflare-image-pricing.php   # Model alias + per-MP cost estimation
-│   │   ├── class-cloudflare-image-validator.php # Non-destructive credential + connectivity check
-│   │   ├── class-cloudflare-image-support.php   # Token, account, URL, and log helpers for the CF provider
+│   │   ├── interface-image-provider.php  # Contract for any image generation provider (incl. batch)
+│   │   ├── class-open-router-image-provider.php  # OpenRouter image gen (single + batch dispatch)
+│   │   ├── class-open-router-image-batch.php     # Parallel curl_multi execution for batch image gen
+│   │   ├── class-open-router-image-support.php   # API key, response parsing, retry/backoff helpers
+│   │   ├── class-open-router-image-pricing.php   # Model resolution + per-image cost estimation
+│   │   ├── class-open-router-config.php          # API base URL (direct vs AI Gateway)
+│   │   ├── class-open-router-request-builder.php # Request body assembly + reasoning token cap/headroom (v0.18.1) + headers + Hostinger cURL auth workaround
+│   │   ├── class-runware-image-provider.php     # Runware FLUX.1 (default v0.9.0+)
+│   │   ├── class-runware-image-pricing.php      # FLUX schnell/dev cost table + resolver
+│   │   ├── class-runware-image-support.php      # Key, response parsing, retry, dimension snap
+│   │   ├── class-runware-image-batch.php        # True parallel curl_multi batch dispatcher
+│   │   ├── class-runware-model-catalog.php      # Live model catalog sync: modelSearch pagination, cache v2, failure cooldown
+│   │   ├── class-runware-catalog-fetcher.php    # HTTP fetch + normalize_models for Runware modelSearch (extracted for 300-line rule)
 │   │   └── (new providers go here — see CONVENTIONS.md)
 │   │
+│   ├── services/
+│   │   ├── interface-model-registry.php           # Contract for provider-specific model registries
+│   │   ├── class-open-router-model-registry.php    # Fetches, caches, queries the OpenRouter model list
+│   │   ├── class-open-router-model-normalizer.php  # Maps raw OpenRouter data → standardized record shape
+│   │   └── (Phase 3: class-runware-model-registry.php)
+│   │
 │   ├── frontend/
+│   │   ├── class-article-typography.php # Inline CSS for font, size, table borders on generated posts
 │   │   └── class-posts-widget.php     # [prautoblogger_posts] shortcode + REST endpoint
 │   │
 │   └── models/
@@ -215,6 +301,61 @@ The widget CSS (`posts-widget.css`) uses the Peptide Starter theme's CSS custom
 
 ---
 
+## Background Generation Flow (v0.3.0)
+
+The "Generate Now" button runs the pipeline in a background WP-Cron process to avoid
+Hostinger's 120-second LiteSpeed connection timeout. The frontend polls for status.
+
+```
+┌──────────────────────────────┐
+│  Admin clicks "Generate Now" │  admin.js sends AJAX to on_ajax_generate_now()
+└────────────┬─────────────────┘
+             │  Handler returns immediately (< 1 second):
+             │  1. Writes "running" transient with started timestamp
+             │  2. Schedules one-shot cron: prautoblogger_manual_generation
+             │  3. Fires non-blocking loopback to wp-cron.php
+             │  4. Returns JSON success to browser
+             ▼
+┌──────────────────────────────┐
+│  admin.js starts polling     │  setInterval every 5 seconds
+│  on_ajax_generation_status() │  Shows stage text + spinner
+└────────────┬─────────────────┘
+             │
+             ▼ (separate PHP process)
+┌──────────────────────────────┐
+│  on_manual_generation()      │  WP-Cron fires this in a new request
+│  (class-executor.php)        │  1. ignore_user_abort(true) — survives HTTP kill
+│                              │  2. set_time_limit(300)
+│                              │  3. Acquires PRAutoBlogger_Generation_Lock
+│                              │  4. Runs PRAutoBlogger_Pipeline_Runner::run()
+│                              │     (pipeline broadcasts stage updates to transient)
+│                              │  5. Writes final result to transient
+│                              │  6. Releases lock
+└────────────┬─────────────────┘
+             │
+             ▼
+┌──────────────────────────────┐
+│  Poller detects completion   │  Reads transient: status = 'complete' or 'error'
+│  Shows result message        │  Resets button to idle state
+└──────────────────────────────┘
+```
+
+**Fallback detection (v0.18.3 R2b/R3):** The status transient is renewed on every stage
+transition via `update_generation_stage()` (`Pipeline_Status::broadcast()`), so its TTL
+always counts from the last activity rather than run start. When a status poll finds the
+transient absent:
+
+- **Lock within TTL (`lock_age ≤ STATUS_TTL = 600s`):** the background process is still alive
+  but has not broadcast yet (or the transient was evicted). `handle_missing_transient()` returns
+  `status: running` (R3) — button stays in-progress, no state change.
+- **Lock exceeded TTL (`lock_age > STATUS_TTL`):** background process died without releasing the
+  lock. `abort_orphaned_run()` marks the `runs` row `failed`, releases the generation lock, deletes
+  the status transient and queue option, and returns `status: error` with "infrastructure timeout"
+  (R2b). A daily `Run_Reaper::sweep_stuck_runs()` at 2× `EXPECTED_RUN_SECONDS` (~3600s) remains
+  the backstop for runs the poll path never sees.
+
+---
+
 ## Database Schema
 
 ### Custom Tables
@@ -265,7 +406,7 @@ All tables use `$wpdb->prefix` + `prautoblogger_` prefix.
 | id                | BIGINT UNSIGNED   | Auto-increment PK                             |
 | post_id           | BIGINT UNSIGNED   | WordPress post ID (nullable, set after publish)|
 | run_id            | VARCHAR(36)       | UUID linking all entries from one pipeline run |
-| stage             | VARCHAR(50)       | 'analysis', 'outline', 'draft', 'edit', 'review' |
+| stage             | VARCHAR(50)       | See "Stage vocabulary" below. Canonical edit-stage name is **'polish'** (this doc previously said 'edit'; the code always wrote 'polish') |
 | provider          | VARCHAR(50)       | 'openrouter'                                  |
 | model             | VARCHAR(100)      | Model identifier used                         |
 | prompt_tokens     | INT               | Input tokens consumed                         |
@@ -274,6 +415,8 @@ All tables use `$wpdb->prefix` + `prautoblogger_` prefix.
 | request_json      | LONGTEXT          | Full request payload (for debugging)          |
 | response_status   | VARCHAR(20)       | 'success', 'error', 'timeout'                 |
 | error_message     | TEXT              | Error details if failed (nullable)             |
+| agent_role        | VARCHAR(50)       | v0.18.0, nullable. Role that made the call ('writer', 'editor', 'analyst', 'researcher', 'illustrator', …). Historical rows stay NULL |
+| prompt_version    | VARCHAR(20)       | v0.18.0, nullable. Pinned prompt-registry version the call rendered with. Historical rows stay NULL |
 | created_at        | DATETIME          | When the API call was made                    |
 
 - INDEX: `post_id`
@@ -281,6 +424,18 @@ All tables use `$wpdb->prefix` + `prautoblogger_` prefix.
 - INDEX: `created_at`
 - INDEX: `stage`
 
+**Stage vocabulary.** `stage` is a VARCHAR, not a SQL enum; the vocabulary lives in
+`PRAutoBlogger_Stage_Display_Map` (PHP), which renders historical and new values coherently
+and maps each stage to its default agent role + primary prompt-registry key:
+
+- **Historical values (exist on prod):** `analysis`, `outline`, `draft`, `polish`, `review`,
+  `llm_research`, `image_a`, `image_b`, `image_prompt_rewrite`, `opik_eval_judge`.
+  Note: single-pass generation logs its one call as `draft` (no `outline` row — that absence
+  is how single-pass and multi-step runs are told apart in cost reporting).
+- **Pipeline v2 values (new runs may write):** `research`, `curate`, `draft`, `editorial`,
+  `seo`, `publish`.
+- Unknown values render via a humanizing fallback — the audit view never renders blank.
+
 #### `prab_event_log` — Structured application logging
 
 | Column     | Type              | Description                                     |
@@ -313,6 +468,97 @@ All tables use `$wpdb->prefix` + `prautoblogger_` prefix.
 - INDEX: `measured_at`
 - INDEX: `composite_score`
 
+#### Pipeline v2 substrate tables (v0.18.0, db 1.2.0)
+
+Real table names use the standard prefix, e.g. `wp_prautoblogger_prompts` (the plan-of-record's
+`prab_*` names are shorthand). Created by `PRAutoBlogger_Pipeline_Schema_Installer`; all are
+dropped on uninstall.
+
+##### `prautoblogger_prompts` — versioned prompt registry
+
+| Column      | Type            | Description                                              |
+|-------------|-----------------|----------------------------------------------------------|
+| id          | BIGINT UNSIGNED | Auto-increment PK                                        |
+| prompt_key  | VARCHAR(64)     | Registry key, e.g. 'content.single_pass' (`key` is reserved SQL) |
+| version     | INT UNSIGNED    | Monotonic per key; **rows are immutable** — edits create new versions |
+| body        | LONGTEXT        | Prompt template; `{{ token }}` placeholders filled at render time |
+| model       | VARCHAR(100)    | Optional model hint (informational in Phase 1)           |
+| params_json | LONGTEXT        | Optional params snapshot (temperature, max_tokens, …)     |
+| author      | VARCHAR(100)    | Who created the version ('seed:v0.18.0', wp user login, agent) |
+| created_at  | DATETIME        | Version creation time                                    |
+| active      | TINYINT(1)      | Exactly one active row per key                           |
+
+- UNIQUE: `prompt_key, version` · INDEX: `prompt_key, active`
+
+##### `prautoblogger_run_sources` — per-run source audit
+
+| Column        | Type         | Description                                  |
+|---------------|--------------|----------------------------------------------|
+| id            | BIGINT UNSIGNED | Auto-increment PK                         |
+| run_id        | VARCHAR(36)  | Pipeline run UUID                            |
+| agent_role    | VARCHAR(50)  | Role that surfaced the source               |
+| source_url    | VARCHAR(500) | Source URL (nullable)                        |
+| doi           | VARCHAR(255) | DOI when known (nullable)                    |
+| kept          | TINYINT(1)   | Keep/discard decision                        |
+| reason        | TEXT         | Why kept or discarded (nullable)             |
+| quality_score | FLOAT        | Source quality weighting (nullable)          |
+| created_at    | DATETIME     | Row creation time                            |
+
+- INDEX: `run_id` — consolidates the old `source_ids_json` + `_prautoblogger_research_sources`
+  scatter for **new** runs; historical runs are not backfilled.
+
+##### `prautoblogger_run_decisions` — per-stage decision audit
+
+| Column         | Type        | Description                                   |
+|----------------|-------------|-----------------------------------------------|
+| id             | BIGINT UNSIGNED | Auto-increment PK                         |
+| run_id         | VARCHAR(36) | Pipeline run UUID                             |
+| stage          | VARCHAR(50) | Stage that decided (see stage vocabulary)     |
+| verdict        | VARCHAR(50) | e.g. 'approved', 'revised', 'rejected', 'halted' |
+| rationale      | TEXT        | Decision rationale (nullable)                 |
+| citation_score | FLOAT       | Nullable until the Phase-2 editorial loop computes it |
+| created_at     | DATETIME    | Row creation time                             |
+
+- INDEX: `run_id`
+
+##### `prautoblogger_runs` — run ledger + lifecycle
+
+| Column              | Type          | Description                                 |
+|---------------------|---------------|---------------------------------------------|
+| run_id              | VARCHAR(36)   | PK — pipeline run UUID                      |
+| status              | VARCHAR(20)   | pending / running / done / failed / halted  |
+| ceiling_usd         | DECIMAL(10,6) | Per-run cost ceiling snapshotted at run start |
+| reserved_usd        | DECIMAL(10,6) | Outstanding reserve-before-call holds       |
+| settled_usd         | DECIMAL(10,6) | Actual settled spend                        |
+| overage_usd         | DECIMAL(10,6) | Amount the breaching reservation exceeded the ceiling by |
+| pinned_prompts_json | LONGTEXT      | Map of prompt_key → version frozen at run start |
+| started_at          | DATETIME      | Run start                                   |
+| updated_at          | DATETIME      | Last ledger/state write                     |
+| finished_at         | DATETIME      | Set on done/failed/halted (nullable)        |
+
+- INDEX: `status` — the Cost_Governor's reserve is a single conditional UPDATE against this
+  row (same atomic discipline as the #10 generation lock), so concurrent `curl_multi`
+  writers cannot slip past the ceiling between check and call.
+
+##### `prautoblogger_run_stages` — per-run per-stage state machine
+
+| Column      | Type            | Description                                        |
+|-------------|-----------------|----------------------------------------------------|
+| id          | BIGINT UNSIGNED | Auto-increment PK                                  |
+| run_id      | VARCHAR(36)     | Pipeline run UUID                                  |
+| stage       | VARCHAR(50)     | Stage name (see stage vocabulary)                  |
+| agent_role  | VARCHAR(50)     | Fan-out dimension. Populated in Phase 1 from `Stage_Display_Map::default_agent_role()` (e.g. 'writer', 'editor', 'publisher'). Phase-2 quorum passes multiple roles for the same stage. |
+| item_key    | VARCHAR(64)     | Scopes article-level stages within multi-article runs ('' for run-level) |
+| status      | VARCHAR(20)     | pending / running / done / failed / halted         |
+| attempt     | SMALLINT UNSIGNED | Re-entry counter                                 |
+| cost_usd    | DECIMAL(10,6)   | Cost attributed to the stage                       |
+| meta_json   | LONGTEXT        | Stage output snapshot — lets resume reuse a done stage instead of re-charging it (payload pruned on the retention cron) |
+| started_at  | DATETIME        | First entry                                        |
+| updated_at  | DATETIME        | Last transition                                    |
+| finished_at | DATETIME        | Set on done/failed (nullable)                      |
+
+- UNIQUE: `run_id, stage, agent_role, item_key` (the idempotency key) · INDEX: `status, updated_at`
+
 ### WordPress Options (`wp_options`)
 
 All prefixed with `prautoblogger_`:
@@ -327,11 +573,14 @@ All prefixed with `prautoblogger_`:
 | `prautoblogger_analysis_model`         | OpenRouter model for analysis (default: cheap)        |
 | `prautoblogger_writing_model`          | OpenRouter model for writing (default: quality)       |
 | `prautoblogger_editor_model`           | OpenRouter model for chief editor (default: quality)  |
+| `prautoblogger_reasoning_max_tokens`   | v0.18.1 — hard cap on thinking tokens per call when reasoning is enabled; sent as OpenRouter `reasoning.max_tokens` (replaces `effort` when active) and the request `max_tokens` is raised by the cap so reasoning can never consume the visible-content budget; 0 = legacy uncapped effort mode. Default `PRAUTOBLOGGER_DEFAULT_REASONING_MAX_TOKENS` (2048) |
 | `prautoblogger_daily_article_target`   | Number of articles per day (1-10, default: 1)         |
 | `prautoblogger_writing_pipeline`       | 'single_pass' or 'multi_step' (default: multi_step)  |
 | `prautoblogger_niche_description`      | Text description of the site's niche                  |
 | `prautoblogger_target_subreddits`      | JSON array of subreddits to monitor                   |
 | `prautoblogger_monthly_budget_usd`     | Monthly API spend limit in USD                        |
+| `prautoblogger_per_run_cost_ceiling_usd` | v0.18.0 — per-run hard cost ceiling (USD); reserve-before-call enforced; snapshotted onto the runs row at run start; 0 = disabled. Default `PRAUTOBLOGGER_DEFAULT_RUN_CEILING_USD` ($0.50) |
+| `prautoblogger_request_json_retention_days` | v0.18.0 — days before heavy audit payloads (generation_log.request_json, run_stages.meta_json) are NULLed by the daily cleanup cron; 0 = keep forever. Default `PRAUTOBLOGGER_DEFAULT_REQUEST_JSON_RETENTION_DAYS` (14) |
 | `prautoblogger_tone`                   | Content tone (informational, conversational, etc.)    |
 | `prautoblogger_min_word_count`         | Minimum article word count (default: 800)             |
 | `prautoblogger_max_word_count`         | Maximum article word count (default: 2000)            |
@@ -343,10 +592,22 @@ All prefixed with `prautoblogger_`:
 | `prautoblogger_log_level`              | Logging threshold: error/warning/info/debug           |
 | `prautoblogger_db_version`             | Schema version for migrations                         |
 | `prautoblogger_schedule_time`          | Daily generation time (HH:MM, default: '03:00')       |
-| `prautoblogger_cloudflare_ai_token`    | Encrypted Cloudflare Workers AI API token             |
-| `prautoblogger_cloudflare_account_id`  | Cloudflare account UUID (plaintext — identifier, not secret) |
-| `prautoblogger_image_model`            | Image model alias: `flux-1-schnell` (default) or `flux-1-dev` |
-| `prautoblogger_image_style_suffix`     | Text appended to every image prompt (default: CEO-locked 90s infomercial prompt) |
+| `prautoblogger_image_model`            | Image model slug from `Image_Model_Registry::get_models()`; provider is derived from this on save |
+| `prautoblogger_image_provider`         | Derived from the chosen model on save (v0.8.0+); not editable in admin UI |
+| `prautoblogger_image_prompt_instructions` | System prompt given to the image rewriter LLM (v0.8.0+); falls back to `Image_Prompt_Builder::REWRITER_SYSTEM_PROMPT` when empty. v0.16.0: the default now instructs the LLM to emit a 1-2 sentence editorial topic/mechanism summary as the SCENE (was a comic gag) |
+| `prautoblogger_image_nsfw_retry`       | Toggle: retry NSFW-blocked image slots with a rule-based fallback prompt (default: '1') |
+| `prautoblogger_migrated_image_provider_v080` | One-shot migration flag — auto-heals mismatched provider/model pairs on first admin_init after v0.8.0 upgrade |
+| `prautoblogger_article_font_family`    | Font family key: 'default', 'inter', 'georgia', 'merriweather', 'lora', 'open_sans', 'roboto', 'system' |
+| `prautoblogger_article_font_size`     | Body font size in px (0 = theme default). Recommended: 16–18. |
+| `prautoblogger_table_borders`         | Toggle: add borders/padding/striping to tables (default: '1') |
+| `prautoblogger_image_style_template`   | Full image prompt template (v0.16.0+); contains exactly one `{{ topic_summary }}` token filled per-article with the rewriter scene. Default = `PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_TEMPLATE` (editorial scientific illustration). Replaces the Style Suffix. Validated on save (single-token, brief A5) |
+| `prautoblogger_image_style_suffix`     | DEPRECATED (v0.16.0). Former comic style suffix appended to every image prompt; no longer read by the builder. Mirrored to `prautoblogger_image_style_suffix_deprecated` for one cycle and not deleted yet |
+| `prautoblogger_openrouter_model_registry` | Normalized OpenRouter model list (JSON array, daily refresh, serves as durable cache) |
+| `prautoblogger_openrouter_model_registry_fetched_at` | Unix timestamp of last successful model registry refresh |
+| `prautoblogger_image_compose_enabled`  | Toggle: run the deterministic image composer (default '1'; auto-degrades, never blocks publishing) |
+| `prautoblogger_image_compose_variants` | Comma list of composed variants for Image A (default 'og,square'; whitelisted at point of use) |
+| `prautoblogger_image_featured_mark_enabled` | Toggle: subtle corner mark on featured images (default '1') |
+| `prautoblogger_image_compose_capability` | Cached capability probe `{fingerprint, capability}`; fingerprint = PHP version + imagick/gd presence, so it auto-invalidates on host changes |
 
 ### Post Meta
 
@@ -365,6 +626,15 @@ Stored on every PRAutoBlogger-generated post:
 | `_prautoblogger_editor_notes`         | Chief editor's review notes                   |
 | `_prautoblogger_generated_at`         | ISO 8601 timestamp of generation              |
 | `_prautoblogger_research_sources`     | JSON array of source URLs used                |
+| `_prautoblogger_idea_hash`            | v0.18.0 — stable hash of the idea (title|topic); with `_prautoblogger_run_id` forms the post-creation idempotency key |
+| `_prautoblogger_og_image_id`          | Attachment ID of the composed 1200×630 OG variant (v0.17.0; the rebuilt SEO stage emits `og:image` from this — key name frozen) |
+| `_prautoblogger_square_image_id`      | Attachment ID of the composed 1080×1080 square variant (v0.17.0; stored now, no consumer yet) |
+
+Composed-variant **attachment** meta (v0.17.0): every pipeline attachment gets
+`_prautoblogger_image_role` (`featured`/`og`/`square`); OG/square variants also
+get `_prautoblogger_base_attachment_id` pointing at the featured attachment
+they derive from. All keys keep the `_prautoblogger_` prefix, so the uninstall
+prefix-sweep purges them.
 
 ---
 
@@ -377,7 +647,51 @@ Stored on every PRAutoBlogger-generated post:
 | Reddit RSS | Primary Reddit data source — Atom feeds for subreddit hot posts | None (unauthenticated) | No known rate limit; reliable from datacenter IPs | `providers/class-reddit-json-client.php` |
 | Reddit .json | Fallback for posts + only source for comments | None (unauthenticated) | ~10 req/min (datacenter IPs often blocked) | `providers/class-reddit-json-client.php` |
 | Google Analytics 4 | Post performance metrics | OAuth2 service account | Standard GA4 limits | `core/class-ga4-client.php`, `core/class-metrics-collector.php` |
-| Cloudflare Workers AI | Image generation (FLUX.1 schnell / dev) for article hero, thumbnail, and IG placements | API token (encrypted in wp_options) + account ID | Workers AI per-account quotas | `providers/class-cloudflare-image-provider.php`, `providers/class-cloudflare-image-pricing.php`, `providers/class-cloudflare-image-validator.php` |
+| Runware (FLUX.1 via runware.ai) | **Default** image backend (v0.9.0+): schnell ~$0.0006/image, dev ~$0.02/image. True parallel generation via curl_multi. **v0.15.0: live model catalog sync** from `/v1/models` endpoint (task-based API); normalized to Image_Model_Registry shape; cached with 24h TTL; on-demand refresh via AJAX. | API key (encrypted in wp_options) | Account-level quotas | `providers/class-runware-image-provider.php`, `providers/class-runware-image-pricing.php`, `providers/class-runware-image-support.php`, `providers/class-runware-image-batch.php`, `providers/class-runware-model-catalog.php` |
+
+---
+
+## Opik LLM Observability (Optional)
+
+**Status:** Wave 1 (v0.12.0) — tracing skeleton. Wave 2 (future) — eval harness with frozen-dataset regression testing.
+
+Opik is a cloud-hosted LLM observability platform (Comet) providing:
+- **Per-call tracing:** Every OpenRouter call generates a span with model, tokens, latency metadata.
+- **Trace grouping:** One trace per article generation bundles all spans (draft, QA, image prompt).
+- **Prompt versioning:** Foundation for Wave 2 — compare new prompt revisions against a frozen reference dataset using LLM-as-judge scoring on rubric axes (factual accuracy, style match, hallucination risk).
+
+**Architecture:**
+- **Feature flag:** `prautoblogger_opik_enabled` (WP option, default off). When false, zero network traffic to Opik.
+- **Credentials:** API key and workspace from PHP constants `PRAUTOBLOGGER_OPIK_API_KEY`, `PRAUTOBLOGGER_OPIK_WORKSPACE` (defined in wp-config.php). Never stored in DB.
+- **Span lifecycle:** 
+  1. `Opik_Trace_Context::init_trace()` generates UUID at article-worker start.
+  2. Each LLM call wraps with `start_span()` → LLM request → `end_span()` with tokens + response.
+  3. `finalize_trace()` + `Opik_Span_Queue::enqueue()` accumulates trace + spans for async dispatch.
+  4. `prautoblogger_opik_dispatch` cron action batches spans/traces (max 100 per POST) to `/v1/private/spans/batch`, `/v1/private/traces/batch`.
+- **Retry logic:** Exponential backoff (2s, 4s, 8s) on 5xx errors; permanent abort on 4xx; dropped after 3 attempts per item.
+- **Queue:** WP options-backed; max 1000 items; 12-hour TTL; persists across page reloads for truly async dispatch.
+
+**Call sites instrumented (Wave 1):**
+- Draft generation (single-pass or multi-step outline/draft/polish).
+- Editorial review (chief editor LLM call).
+- Image prompt generation (deferred; file at 314 LOC, over limit).
+
+**Cost & Performance:**
+- Opik free tier: 25k spans/month. Estimated current usage ~4.2k/month (20 posts/day × 7 calls × 30 days). Headroom to 5× growth.
+- Impact on article generation: async dispatch, zero blocking latency overhead.
+- Wave 2 (eval harness): adds LLM-as-judge calls (~$14/month at Haiku pricing, assuming 2 eval runs/week).
+
+**Code structure:**
+```
+includes/services/opik/
+  class-opik-client.php            — REST client (auth, retry, batch POSTs)
+  class-opik-trace-context.php     — per-request trace state singleton
+  class-opik-span-queue.php        — WP options-backed async queue
+  class-opik-dispatcher.php        — cron handler, batch dispatch
+
+includes/admin/
+  class-opik-settings.php          — admin UI (toggle, project name, status)
+```
 
 ---
 
@@ -420,19 +734,123 @@ The posts widget uses WordPress-bundled React (`wp.element`) with raw `createEle
 The widget fetches posts asynchronously from a dedicated REST endpoint rather than rendering server-side. This keeps initial page load fast and allows the endpoint to be cached independently (5-minute Cache-Control). The permission callback uses a filter (`prautoblogger_rest_posts_public`) so sites can restrict access if needed.
 
 ### #13: Run-ID based log linking
-Each pipeline execution generates a UUID (`run_id`) that tags every `prab_generation_log` entry. When a post is published, `link_generation_logs()` uses `UPDATE WHERE run_id = X` to associate entries with the `post_id`. This is more reliable than the previous timestamp-window approach, especially in batch runs where multiple posts are generated in quick succession.
+Each pipeline execution generates a UUID (`run_id`) that tags every `prab_generation_log` entry. When a post is published, `link_generation_logs()` uses `UPDATE WHERE run_id = X` to associate entries with the `post_id`. This is more reliable than the previous timestamp-window approach, especially in batch runs where multiple posts are generated in quick succession. **v0.8.1+**: `run_id` is also persisted on each post as `_prautoblogger_run_id` post_meta, giving the orphan-research reaper a direct path from run to siblings without walking the gen_log table (see #19).
+
+### #19: Daily orphan-research-row reaper (v0.8.1)
+When a pipeline dies between post creation and the final `Post_Assembler::amortize_research_costs()` call (Hostinger exec kill, OOM, LiteSpeed cut, fatal), the shared `llm_research` cost row stays in `prab_generation_log` with `post_id = NULL` and sibling articles understate their true cost in the breakdown popover. A new daily WP-Cron event `prautoblogger_reap_orphan_research_rows` (hooked to `PRAutoBlogger_Research_Reaper::on_cron`, 03:15 server time — 15 min after the primary generation cron) scans for orphan rows older than a 1-hour grace window, looks up sibling posts by `_prautoblogger_run_id` post_meta (fallback: distinct `post_id`s in gen_log for the same run_id), and delegates to the existing idempotent `amortize_research_costs()` on match. Orphans that still have no siblings after 7 days are deleted outright as sunk cost. A one-time activator migration (`prautoblogger_migrated_run_id_meta_v081`) back-populates `_prautoblogger_run_id` on existing posts from gen_log so the meta-primary path works on upgrade. Manual ops trigger: `wp prautoblogger reap-research`.
 
 ### #14: Reddit RSS replaces PullPush.io (and earlier Reddit OAuth)
 Reddit rejected our OAuth API application (April 2026). We initially switched to PullPush.io, but its index was frequently stale or unavailable. Reddit's RSS/Atom feeds (`/r/{sub}/hot.rss`) proved the most reliable option — they work from datacenter IPs where .json gets 403, require no auth, and have no apparent rate limit. The .json endpoints are kept as a fallback for posts and as the sole source for comment data. Each collected item's metadata includes a `data_source` field (`reddit_rss` or `reddit_json`) for auditability.
 
-### #16: Image generation via Cloudflare Workers AI (FLUX.1), direct (not via AI Gateway)
-The image-generation layer (started 2026-04-15, tracked in `convo/prautoblogger/threads/2026-04-image-pipeline/`) uses FLUX.1 [schnell] on Cloudflare Workers AI as its default model, chosen for its ~$0.0011/MP cost and 2–3 sec latency. FLUX.1 [dev] is a ~4× cost upgrade exposed as a dropdown for specific posts that warrant it. Calls go directly to `https://api.cloudflare.com/client/v4/accounts/{id}/ai/run/@cf/black-forest-labs/...`, *not* through the Cloudflare AI Gateway that we use for OpenRouter — the gateway route to Workers AI currently 403s (pre-existing open issue). The provider lives behind `PRAutoBlogger_Image_Provider_Interface`, so the decision is trivially reversible: switching to a different image API (DALL-E, Replicate, a future AI Gateway route) is a new class implementation plus a one-line swap in the pipeline wiring. Trade-off: we run two different Cloudflare integration paths (gateway for OpenRouter LLMs, direct for Workers AI images) until the gateway route stabilizes — minor cognitive overhead, zero functional downside.
+### #18: OpenRouter model registry — daily refresh, WP option + transient cache, zero-coupling
+
+The admin model picker (v1) needs to list OpenRouter models with pricing and capabilities. We fetch `https://openrouter.ai/api/v1/models` (free, unauthenticated) once daily and store the normalized payload in a WP option fronted by a 24h transient. On stale-and-fetch-fails, we serve last-good + surface a warning. The registry class (`class-open-router-model-registry.php`) takes all config via constructor (option name, transient name, endpoint URL) — no PRAUTOBLOGGER_* constants inside the class body. Phase 2 lifts it into a shared Composer package with zero internal edits. Phase 3 adds a parallel `Cloudflare_WorkersAI_Model_Registry` behind the same interface. Capability vocabulary: `text→text`, `text+image→text`, `text+audio→text`, `text→image`, `text→audio`, `text→video`, `text→embedding`. Cost: $0/month.
+
+### #20: Editorial illustration prompt + style-template setting (v0.16.0, May 2026)
+
+Commit 1 of the in-plugin editorial image pipeline (brief `docs/proposals/2026-05-29-image-pipeline-in-plugin-brief.md`). The image style pivots from a single-panel newspaper comic to a **text-free editorial scientific illustration**. Two changes ship here; the deterministic PHP composer is a later commit.
+
+1. **Prompt structure.** `Image_Prompt_Builder::REWRITER_SYSTEM_PROMPT` now asks the rewriter LLM for a concise 1-2 sentence topic/mechanism summary (one concrete centered focal subject, no text/people-as-gag/logos) as the SCENE, keeping the short CAPTION line for the unchanged HTML-caption-below-image path. The scene/caption parsing contract (`Image_Scene_Parser`) is unchanged.
+2. **Template substitution.** The old `trim($scene . ' ' . $style_suffix)` concat is replaced by `PRAutoBlogger_Image_Template_Filler::fill($scene)` in all three entry points (`build_article_prompt`, `build_source_prompt`, `build_fallback_prompt`). The filler resolves the active template (admin override → default), strips control chars and clamps the summary length (brief A5), then substitutes the single `{{ topic_summary }}` token. Degradation (brief A5/A6): if the template lacks exactly one token it appends the summary and logs a warning; if the summary is empty it emits the style-only prompt — a blank or token-only prompt is never sent to the provider.
+3. **Setting.** New textarea `prautoblogger_image_style_template` (default `PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_TEMPLATE`) replaces the Style Suffix field. On save it is sanitised with `sanitize_textarea_field` and validated to contain exactly one token (`Image_Template_Filler::sanitize_for_save`). The old `prautoblogger_image_style_suffix` is mirrored to `..._deprecated` for one cycle and not deleted (one-time migration `prautoblogger_migrated_style_template_v0160`).
+
+Provider/model are unchanged — only the prompt text changes, so production keeps emitting via Runware FLUX.1 schnell but now produces text-free editorial base images.
+
+### #21: Deterministic PHP image composer with capability ladder (v0.17.0, Jun 2026)
+
+Commit 2 (and final scope) of the in-plugin editorial image pipeline (#20). Small diffusion
+models cannot render clean text (2026-04-21 A/B finding), so base images are text-free —
+but the one image that travels *without* its HTML caption is the social/OG share image.
+A **deterministic local composer** (`PRAutoBlogger_Image_Composer` behind
+`PRAutoBlogger_Image_Composer_Interface`) now runs between provider bytes and sideload:
+
+1. **Variants.** Image A → corner-marked featured (1200×632) + branded OG (1200×630, teal
+   band, brand mark, baked caption in Poppins SemiBold) + square card (1080×1080: full base
+   downscaled into a 1080×569 top slice — no upscaling — cream caption panel in Poppins
+   Bold, teal footer with the horizontal reverse lockup). Image B → corner mark only. The
+   variant set is config-driven (`prautoblogger_image_compose_variants`, default `og,square`;
+   square has no consumer yet — CEO wants it rendered + stored now). Variants are
+   meta-linked via `_prautoblogger_image_role`, `_prautoblogger_base_attachment_id`,
+   `_prautoblogger_og_image_id`, `_prautoblogger_square_image_id`. The og key is **frozen**:
+   the rebuilt SEO stage (pipeline-redesign §4.8) emits `og:image` from it.
+2. **Capability ladder, never fatal.** Imagick is probed once (PNG format + TTF annotate
+   smoke test) and cached in `prautoblogger_image_compose_capability`, fingerprinted by
+   PHP version + imagick/gd presence so host flips (hPanel/cagefs — it has happened)
+   auto-invalidate the cache. Rungs: imagick → `wp_get_image_editor()` resize-only
+   (unbranded, square skipped because it would upscale) → pass-through. Every render is
+   try/caught; degradation logs one WARNING per run; the publish always proceeds with the
+   editable HTML caption intact. Test/ops override: `prautoblogger_image_compose_capability`
+   filter.
+3. **Determinism.** Bundled OFL fonts (no system-font queries), vendored brand PNGs (no
+   runtime SVG delegate variance), `stripImage()` + PNG date/time chunks excluded + fixed
+   compression → byte-stable output **per environment** (not across ImageMagick versions).
+   Composition is local CPU, $0, logged as a duration-only stage on the `image_composer`
+   channel — no cost-tracker rows.
+4. **Layout tuning.** Geometry/opacity are constants in
+   `PRAutoBlogger_Image_Composer_Layout::defaults()` behind the
+   `prautoblogger_image_compose_layout` filter — deliberately not settings; promote only if
+   the CEO asks to tune them. The caption is hard-clamped (word-boundary wrap + ellipsis,
+   multibyte-safe) even though the rewriter LLM is already constrained to <15 words.
+
+### #17: Runware as default image backend (v0.9.0, Apr 2026)
+
+After a comic-style A/B round in Apr 2026, FLUX.1 schnell via Runware was chosen as the default image backend. Cost is ~$0.0006/image vs ~$0.039/image for Gemini 2.5 Flash Image via OpenRouter (≈65× cheaper), and the looser schnell fidelity reads as editorial-cartoon style — a feature, not a bug, for our single-panel comic aesthetic. FLUX.1 dev (~$0.02/image, 28 steps) remains available as an opt-in for higher-fidelity runs. The Runware layer mirrors the OpenRouter split (interface + provider + support + pricing + batch), all under the 300-line cap. The batch class dispatches `imageInference` POSTs via `curl_multi_init/exec/select` — wall-clock time for the A/B pair drops to ≈ the slowest single image. A v0.9.0 one-time migration (`prautoblogger_migrated_default_image_v090`) flips sites still on the legacy default; explicit user selections are preserved. Cloudflare Workers AI was removed as an image provider in v0.10.0 (see ADR #16 note below).
+
+### #16: Image generation via Cloudflare Workers AI (FLUX.1) — SUPERSEDED v0.10.0
+Kept here for history. Until v0.8.2 the default image backend was FLUX.1 schnell on Cloudflare Workers AI, routed via the Cloudflare AI Gateway for caching + unified telemetry. In v0.9.0 (2026-04-21) Runware FLUX.1 schnell became the default (65× cheaper, see ADR #17). In v0.10.0 (2026-04-21) the Cloudflare Workers AI provider was removed entirely — classes, settings, tests, and registry entries are gone; any CF user is migrated to `runware:100@1` on upgrade via `PRAutoBlogger_Migrate_Remove_Cloudflare_V0100::run()`. The Cloudflare AI Gateway in front of OpenRouter (ADR #15) is unaffected — it is a distinct integration.
+
 
 ### #15: Optional Cloudflare AI Gateway in front of OpenRouter
 We already use Cloudflare for DNS/CDN on peptiderepo.com, so layering AI Gateway in front of OpenRouter is zero marginal infrastructure. It gives us response caching (meaningful for repeated classification/scoring calls), a unified cost/latency dashboard, rate limiting, and provider fallback — all of which we would otherwise have to build ourselves to satisfy the CTO cost-tracking rules. Kept as an opt-in URL setting (`prautoblogger_ai_gateway_base_url`) so the plugin still works unchanged out of the box and can be bypassed instantly if the gateway misbehaves. The gateway is a transparent OpenRouter-compatible proxy; no new provider class is needed, and the response parsing path (`usage`, `choices[0].message.content`) is unchanged.
 
 ---
 
+### #22: Pipeline v2 Phase 1 substrate (v0.18.0, db 1.2.0, June 2026)
+
+Phase 1 of the CEO-approved pipeline rebuild (plan of record:
+`convo/cpo/threads/2026-06-prautoblogger-pipeline-redesign/03-cto-revised-brief.md`), built
+**on the current pipeline with no behavior change** to the Economy (single-pass) and
+multi-step publish paths. Four subsystems:
+
+1. **Versioned prompt registry** (`prautoblogger_prompts`). All pipeline prompt copy
+   (content/analysis/editor/research + the illustration rewriter prompt and the image Style
+   Template) lives as immutable versioned rows; the hardcoded v0.16.0 texts are seeded as v1
+   and remain the in-code fallback, so a missing/empty table can never fatal — call sites
+   render through `PRAutoBlogger_Prompt_Registry` and fall back to the same constants the
+   seed used (byte-identical output). A run pins the active version of every key at start
+   (`runs.pinned_prompts_json`) and every generation_log row is stamped with the pinned
+   `prompt_version`. The image-composer PR **consumes** the `image.*` keys — it must not
+   grow its own prompt storage. No admin UI in Phase 1; the API supports list/activate/
+   create-version (never mutate) for the Phase-2 Prompts screen.
+2. **Additive audit schema.** `agent_role` + `prompt_version` columns on generation_log;
+   `run_sources` + `run_decisions` child tables; `PRAutoBlogger_Stage_Display_Map` renders
+   historical + image + v2 stage values. `request_json` (and stage output payloads in
+   `run_stages.meta_json`) are nulled after R days — R from the
+   `prautoblogger_request_json_retention_days` setting (default 14), pruned on the existing
+   daily reaper cron.
+3. **Per-run cost governor** (`PRAutoBlogger_Cost_Governor`). Reserve-before-call against the
+   per-run ledger row using a single conditional UPDATE (the #10 atomic-write discipline);
+   estimates come from the #18 pricing chain; `curl_multi` image batches reserve their summed
+   estimate before dispatch; reservations settle to actuals after each response. Breach →
+   run `halted`, overage recorded, un-dispatched work aborted, surfaced on the Review Queue.
+   Ceiling = `prautoblogger_per_run_cost_ceiling_usd` setting (default $0.50, 0 = disabled).
+   The monthly `Cost_Tracker` cap and the Cloudflare AI Gateway (#15) path are unchanged.
+4. **Run state machine + idempotency** (`PRAutoBlogger_Run_State`). Per-run per-stage state
+   (pending/running/done/failed/halted) keyed `run_id + stage + agent_role + item_key`
+   (item_key scopes article-level stages because one run_id spans all N articles of a batch);
+   done stages persist output and are reused on re-entry, never re-charged; post creation is
+   keyed by `_prautoblogger_run_id` + `_prautoblogger_idea_hash` (check-before-insert) so a
+   retried run cannot duplicate a post. `PRAutoBlogger_Run_Reaper` (same daily cron as #19)
+   marks runs stuck `running` > 2× expected stage wall-clock as `failed`; such runs render
+   as **"incomplete"** in audit queries. Quorum logic (multiple roles per stage) itself is Phase 2. In Phase 1,
+   `agent_role` is populated on every row from `Stage_Display_Map::default_agent_role()`
+   so the run timeline is self-describing and the idempotency key is fully populated.
+
+### #20: PHPUnit test infrastructure + WordPress-Core PHPCS compliance (v0.10.1)
+
+Tests use Brain\Monkey for WordPress function mocking (no database required). The BaseTestCase singleton handles setup/teardown of Monkey stubs and provides fixture helpers for common data shapes (SourceData, ArticleIdea, GenerationLog, etc.). All WordPress functions used by the plugin are stubbed in BaseTestCase::setUp() so individual test classes only override what they need. In v0.10.1, missing stubs for `post_type_exists()` were added to support PeptideLinker's PR-Core guards. All 1,362 WordPress-Core coding-standards violations (short array syntax, line length, spacing) were auto-fixed via phpcbf and the CI gate was flipped to strict mode — PHPCS failures now block CI. This prevents future regressions on the code style front.
+
+
 ## Cross-System LLM Budget Coordination
 
 PRAutoBlogger and Peptide News both call OpenRouter and may share a single API key / billing account. Their combined spend should be considered when setting per-plugin budgets.

CONVENTIONS.md

@@ -150,6 +150,38 @@ interface PRAutoBlogger_Image_Provider_Interface {
 
 ---
 
+## How To: Tune the Image Composer (v0.17.0+)
+
+The deterministic composer (ARCHITECTURE.md #21) renders branded variants between
+provider bytes and sideload. Three rules when touching it:
+
+1. **Geometry lives in code, not settings.** All sizes/colors/opacities come from
+   `PRAutoBlogger_Image_Composer_Layout::defaults()` and can be overridden via the
+   `prautoblogger_image_compose_layout` filter:
+   ```php
+   add_filter( 'prautoblogger_image_compose_layout', function ( array $layout ): array {
+       $layout['featured']['mark_opacity'] = 0.40;
+       return $layout;
+   } );
+   ```
+   Promote a value to a settings field only on explicit CEO request.
+2. **Keep renderer classes WP-free.** `Image_Composer_Imagick`, `Image_Composer_Canvas`,
+   and `Image_Composer_Layout` must not call WordPress functions — they are exercised by
+   a standalone render harness (and the determinism test) without a WP bootstrap. Only
+   the orchestrator (`Image_Composer`) and the GD rung (`Image_Composer_Editor`) may
+   touch WP APIs.
+3. **Never fatal a publish.** Any new render path needs a try/catch that degrades to
+   pass-through and logs at most one WARNING per run (`warn_once()`). Capability checks
+   go through the cached probe (`prautoblogger_image_compose_capability` option +
+   same-named override filter) — never re-probe per image.
+
+Adding a new variant role: extend `Layout::defaults()` + the renderer, whitelist the
+role in `Image_Composer::configured_variants()` and in
+`Image_Attacher::ROLE_POST_META` (new `_prautoblogger_{role}_image_id` post meta keeps
+the uninstall prefix-sweep effective), then cover it in the unit ladder tests.
+
+---
+
 ## How To: Add a New Admin Setting
 
 1. Define the option key in the settings array in `admin/class-admin-page.php` → `get_settings_fields()` method
@@ -172,13 +204,18 @@ interface PRAutoBlogger_Image_Provider_Interface {
 
 ## How To: Add a New Pipeline Stage
 
-The writing pipeline is an ordered array of stages. Each stage is a class method on `Content_Generator`.
+Writing stages are methods on `Content_Generator` that delegate to its `execute_stage()`
+helper (Opik span + LLM dispatch + cost log + run-stage state in one place).
 
-1. Add the stage method to `class-content-generator.php`: `protected function stage_{name}(PRAutoBlogger_Content_Request $request): string`
-2. Register the stage in the `get_pipeline_stages()` method for the appropriate mode (single_pass or multi_step)
-3. Each stage receives the accumulated context and returns its output
-4. Each stage logs its cost via `Cost_Tracker::log_api_call()`
-5. If a stage fails after retries, the entire pipeline fails (no partial publishes)
+1. Add the stage method to `class-content-generator.php` and call
+   `$this->execute_stage( $stage, $span_name, $user_prompt, $request, $model, $options )`
+2. Wire it into `generate_multi_step()` (or the relevant mode path)
+3. Add the stage to `PRAutoBlogger_Stage_Display_Map` (label, default agent role, prompt key)
+   and — if it has registry-managed copy — a prompt key in the defaults classes
+4. Cost logging and per-run stage state (idempotent resume, output snapshot) come free from
+   `execute_stage()`; the per-run cost governor guards the call inside the provider
+5. If a stage fails after retries, the entire pipeline fails (no partial publishes); the
+   stage row is failed by the worker's catch-all and the run is swept by Run_Reaper
 
 ---
 
@@ -234,6 +271,92 @@ Frontend components use `wp.element` (WordPress-bundled React) — no JSX, no bu
 9. **No `echo` of raw data** — always escape with `esc_html()`, `esc_attr()`, etc.
 10. **Nonce on every form/AJAX** — `wp_nonce_field()` / `check_ajax_referer()`
 
+
+## How To: Add an OpenRouter model picker field (v0.11.0+)
+
+Use the `model_select` field type to let admins choose OpenRouter models with a searchable dropdown, capability filtering, and estimated cost preview based on usage history.
+
+### 1. Declare the field in `class-settings-fields.php`
+
+```php
+[
+    'id'          => 'my_plugin_model',
+    'label'       => __( 'My Model Setting', 'my-plugin' ),
+    'type'        => 'model_select',
+    'section'     => 'my_plugin_settings',
+    'default'     => 'anthropic/claude-3.5-haiku',
+    'capability'  => 'text→text',  // see ARCHITECTURE.md §18 for all capability strings
+    'description' => __( 'Choose a model...', 'my-plugin' ),
+    'badge'       => __( 'Quality', 'my-plugin' ),
+],
+```
+
+### 2. Map the setting to pipeline stages (for cost preview)
+
+If you want cost preview to work, add your setting ID and stage list to the `get_stages_for_setting()` method in `includes/admin/fields/class-open-router-model-field.php`:
+
+```php
+private static function get_stages_for_setting( string $field_id ): array {
+    $map = [
+        'prautoblogger_analysis_model'     => [ 'analysis' ],
+        'prautoblogger_writing_model'      => [ 'outline', 'draft', 'polish' ],
+        'prautoblogger_editor_model'       => [ 'review' ],
+        'my_new_model_setting'             => [ 'my_stage' ],  // ADD HERE
+    ];
+    return $map[ $field_id ] ?? [];
+}
+```
+
+The cost preview queries `get_avg_tokens_for_stages()` on the Cost Tracker to show estimated cost per generation based on the last 30 days of usage.
+
+### 3. That's it
+
+The field renderer, AJAX refresh, model picker JS, and capability filtering are already wired. The admin will see a "Refresh Model List" button on the AI Models tab (or whichever tab contains the picker field).
+
+### Capability strings (locked in v0.11.0)
+
+- `text→text` — text input, text output (default for analysis/writing/editor)
+- `text+image→text` — vision models
+- `text+audio→text` — audio input models
+- `text→image` — image generation
+- `text→audio` — voice synthesis
+- `text→video` — video generation
+- `text→embedding` — embeddings
+
+Phase 3 will add provider selection; v0.11.0 is OpenRouter-only.
+
+## How To: Change a Pipeline Prompt (v0.18.0+)
+
+Prompt copy is **versioned data**, not code. The bodies live in
+`wp_prautoblogger_prompts` (one ACTIVE version per key); the hardcoded texts in
+`class-prompt-defaults.php` / `class-prompt-defaults-editorial.php` are the canonical v1 seed
+AND the fallback when the table is unavailable — never edit a stored version in place.
+
+1. **Never `UPDATE` a body.** Create a new version and activate it:
+   ```php
+   $v = PRAutoBlogger_Prompt_Registry_Writer::create_version(
+       'content.polish', $new_body, $model, $params, 'your-name', true
+   );
+   ```
+2. **Keys** are dot-namespaced: `content.system`, `content.single_pass`, `content.outline`,
+   `content.draft`, `content.polish`, `analysis.system`, `analysis.user`, `editor.system`,
+   `editor.review`, `research.system`, `image.rewriter_system`, `image.style_template`.
+   The two `image.*` keys are the image-composer seam — coordinate on the convo thread
+   before touching them.
+3. **Tokens** use the `{{ name }}` syntax (exactly one space each side — same convention as
+   the Style Template's `{{ topic_summary }}`). Token VALUES are computed by code
+   (`Content_Prompts`, `Analysis_Prompts`, `Chief_Editor`); a new prompt version may reorder
+   or drop tokens but must not invent new ones without adding the value at the call site.
+4. **Pinning.** A run pins the active version of every key at start
+   (`runs.pinned_prompts_json`, written by `Cost_Tracker::set_run_id()`); every
+   generation_log row is stamped with the pinned `prompt_version`. Activating a new version
+   affects the NEXT run, never a run in flight.
+5. **Call sites** render via `PRAutoBlogger_Prompt_Registry::render( $key, $tokens )` and
+   must keep working when the table is absent (the registry falls back to the defaults
+   automatically — do not add your own fallback).
+6. If you add a key: define the body in the appropriate defaults class, add it to `defs()`,
+   map its stage in `Stage_Display_Map`, and it will seed on the next migration pass.
+
 ## Git Workflow — PR-Gated, Soft-Enforced
 
 This repo is private on GitHub's free plan, which does not support branch protection or rulesets. The review gate is enforced at the agent layer, not server-side. Every agent and human contributor follows these rules; the `.github/workflows/main-push-audit.yml` tripwire opens an audit issue on any direct push to `main` that did not come from a merged PR.
@@ -278,4 +401,104 @@ curl -s -X POST -H "Authorization: token $GH_TOKEN" \
 
 ### When this changes
 
-If the peptiderepo GitHub account is ever upgraded to Pro (or the repo goes public), replace this soft-enforcement section with a note pointing to the real branch protection rules in repo settings.
+If the peptiderepo GitHub account is ever upgraded to Pro (or the repo goes public), replace this soft-enforcement section with a note pointing to the real branch protection rules in repo settings.
+## Instrumenting a New LLM Call Site for Opik (v0.12.0+)
+
+When you add a new LLM call (via `$llm->send_chat_completion()`), follow this pattern to capture it in Opik:
+
+### 1. Get the trace context
+
+At the start of your method, grab the per-request singleton:
+
+```php
+$ctx = PRAutoBlogger_Opik_Trace_Context::current();
+```
+
+### 2. Start the span
+
+Before the LLM call, declare a span with metadata:
+
+```php
+$span_id = $ctx->start_span(
+	array(
+		'name'     => 'my_llm_operation',  // kebab-case, descriptive
+		'type'     => 'llm',
+		'model'    => $model,               // e.g. 'gpt-4', from get_option()
+		'provider' => 'openrouter',         // or the actual provider name
+		'input'    => array( 'key' => 'value' ), // optional metadata (no full prompts!)
+	)
+);
+```
+
+### 3. Make the LLM call (unchanged)
+
+```php
+$response = $this->llm->send_chat_completion(
+	array(
+		array( 'role' => 'system', 'content' => $system_prompt ),
+		array( 'role' => 'user', 'content' => $user_prompt ),
+	),
+	$model,
+	array( 'temperature' => 0.7, 'max_tokens' => 4000 )
+);
+```
+
+### 4. End the span with output
+
+After the response, record the outcome:
+
+```php
+$ctx->end_span(
+	$span_id,
+	array(
+		'output' => array( 'response_length' => strlen( $response['content'] ?? '' ) ),
+		'usage'  => array(
+			'prompt_tokens'     => $response['prompt_tokens'],
+			'completion_tokens' => $response['completion_tokens'],
+			'total_tokens'      => $response['prompt_tokens'] + $response['completion_tokens'],
+		),
+	)
+);
+```
+
+### Key rules
+
+- **Never log full prompts.** Use prompt hashes or version tags in `input`. Full text blows payload size and leaks content policy.
+- **Check the feature flag at call-site level?** No. The singleton is always available; Opik_Dispatcher checks the flag before dispatch.
+- **Async dispatch?** Yes. Spans are queued; dispatch happens via `prautoblogger_opik_dispatch` cron (no blocking).
+- **Cost logging?** Unchanged. Your `cost_tracker->log_api_call()` remains separate from Opik; Opik is observability-only.
+
+### Example: minimal instrumentation
+
+```php
+public function my_operation( $input ) {
+	$model = get_option( 'my_model', 'default-model' );
+	$ctx = PRAutoBlogger_Opik_Trace_Context::current();
+
+	$span_id = $ctx->start_span(
+		array(
+			'name'     => 'my_operation',
+			'type'     => 'llm',
+			'model'    => $model,
+			'provider' => 'openrouter',
+		)
+	);
+
+	$response = $this->llm->send_chat_completion( /* ... */ );
+
+	$ctx->end_span(
+		$span_id,
+		array(
+			'usage' => array(
+				'prompt_tokens'     => $response['prompt_tokens'],
+				'completion_tokens' => $response['completion_tokens'],
+				'total_tokens'      => $response['prompt_tokens'] + $response['completion_tokens'],
+			),
+		)
+	);
+
+	return $response['content'];
+}
+```
+
+That's it. No config, no feature-flag checks, no try/catch needed.

assets/admin/peptiderepo-model-picker.css

@@ -0,0 +1,6 @@
+/**
+ * Styling for model registry picker refresh functionality.
+ *
+ * Button animations and toast notifications are defined in admin.css.
+ * This file is reserved for model-picker-specific styles (future extensibility).
+ */

assets/admin/peptiderepo-model-picker.js

@@ -0,0 +1,58 @@
+/**
+ * Model registry refresh handler for PRAutoBlogger admin settings.
+ *
+ * Handles the "Refresh Model List" button click in the AI Models admin tab.
+ * Sends AJAX request to refresh the OpenRouter model registry cache and shows
+ * success/error toast notifications.
+ *
+ * @see admin/class-admin-page.php — Renders the refresh button + nonce.
+ * @see ajax/class-model-registry-refresh.php — Server-side handler.
+ */
+(function ($) {
+	'use strict';
+
+	// Refresh model registry button.
+	$(document).on('click', '#prautoblogger-refresh-models', function (e) {
+		e.preventDefault();
+		var $btn = $(this);
+		var nonce = $btn.data('nonce');
+		var originalText = $btn.html();
+
+		$btn.prop('disabled', true).addClass('ab-btn-loading');
+
+		$.ajax({
+			url: ajaxurl,
+			method: 'POST',
+			data: {
+				action: 'prautoblogger_refresh_models',
+				nonce: nonce
+			},
+			timeout: 30000
+		})
+		.done(function (response) {
+			if (response.success && response.data && response.data.message) {
+				// Show success toast
+				var $notice = $('<div class="ab-save-notice" role="status"></div>')
+					.html('<span class="dashicons dashicons-yes"></span> ' + response.data.message)
+					.insertBefore('.ab-layout')
+					.delay(4000)
+					.fadeOut(function () {
+						$(this).remove();
+					});
+			}
+		})
+		.fail(function () {
+			var $notice = $('<div class="ab-save-notice notice-error" role="alert"></div>')
+				.html('<span class="dashicons dashicons-warning"></span> ' + 'Failed to refresh model list. Please try again.')
+				.insertBefore('.ab-layout')
+				.delay(5000)
+				.fadeOut(function () {
+					$(this).remove();
+				});
+		})
+		.always(function () {
+			$btn.prop('disabled', false).removeClass('ab-btn-loading').html(originalText);
+		});
+	});
+
+})(jQuery);

assets/css/model-picker.css

@@ -0,0 +1,264 @@
+/**
+ * Model picker popup styles for PRAutoBlogger admin.
+ *
+ * Renders a modal overlay with a searchable list of AI models.
+ * Uses the same design tokens as admin.css (--ab-* CSS variables).
+ *
+ * @see assets/js/model-picker.js — JS that builds and manages the popup DOM.
+ * @see assets/css/admin.css      — Parent design system variables.
+ */
+
+/* ── Overlay ────────────────────────────────────────────────────────── */
+.ab-mp-overlay {
+	position: fixed; inset: 0; z-index: 100100;
+	background: rgba(0, 0, 0, 0.45);
+	display: flex; align-items: center; justify-content: center;
+	animation: ab-mp-fade-in 0.15s ease;
+}
+
+@keyframes ab-mp-fade-in {
+	from { opacity: 0; }
+	to   { opacity: 1; }
+}
+
+/* ── Popup container ────────────────────────────────────────────────── */
+.ab-mp-popup {
+	background: var(--ab-card-bg, #fff);
+	border-radius: 12px;
+	box-shadow: 0 20px 60px rgba(0, 0, 0, 0.25);
+	width: 640px; max-width: 90vw;
+	max-height: 80vh;
+	display: flex; flex-direction: column;
+	animation: ab-mp-slide-up 0.2s ease;
+}
+
+@keyframes ab-mp-slide-up {
+	from { opacity: 0; transform: translateY(12px); }
+	to   { opacity: 1; transform: translateY(0); }
+}
+
+/* ── Header ─────────────────────────────────────────────────────────── */
+.ab-mp-header {
+	display: flex; align-items: center; justify-content: space-between;
+	padding: 16px 20px; border-bottom: 1px solid var(--ab-border, #e2e8f0);
+}
+
+.ab-mp-title {
+	font-size: 16px; font-weight: 700;
+	color: var(--ab-text, #1e293b);
+}
+
+.ab-mp-close {
+	background: none; border: none; cursor: pointer;
+	font-size: 22px; line-height: 1; color: var(--ab-text-muted, #64748b);
+	padding: 4px 8px; border-radius: 4px;
+}
+.ab-mp-close:hover {
+	background: var(--ab-bg, #f8fafc);
+	color: var(--ab-text, #1e293b);
+}
+
+/* ── Search ─────────────────────────────────────────────────────────── */
+.ab-mp-search-wrap {
+	padding: 12px 20px;
+	border-bottom: 1px solid var(--ab-border, #e2e8f0);
+}
+
+.ab-mp-search {
+	width: 100%; box-sizing: border-box;
+	padding: 10px 14px; font-size: 14px;
+	border: 1px solid var(--ab-border, #e2e8f0);
+	border-radius: 8px; outline: none;
+	color: var(--ab-text, #1e293b);
+	background: var(--ab-bg, #f8fafc);
+}
+.ab-mp-search:focus {
+	border-color: var(--ab-primary, #4f46e5);
+	box-shadow: 0 0 0 3px var(--ab-primary-light, #eef2ff);
+	background: var(--ab-card-bg, #fff);
+}
+
+/* ── Model list ─────────────────────────────────────────────────────── */
+.ab-mp-list {
+	flex: 1; overflow-y: auto;
+	padding: 4px 0;
+	min-height: 200px; max-height: 50vh;
+}
+
+.ab-mp-loading, .ab-mp-empty {
+	padding: 40px 20px; text-align: center;
+	color: var(--ab-text-muted, #64748b); font-size: 14px;
+}
+
+/* ── Model row ──────────────────────────────────────────────────────── */
+.ab-mp-row {
+	display: flex; align-items: center; justify-content: space-between;
+	padding: 10px 20px; cursor: pointer;
+	transition: background 0.1s ease;
+	gap: 12px;
+}
+.ab-mp-row:hover {
+	background: var(--ab-primary-light, #eef2ff);
+}
+
+.ab-mp-row-main {
+	display: flex; align-items: center; gap: 8px;
+	flex: 1; min-width: 0;
+}
+
+.ab-mp-name {
+	font-size: 13px; font-weight: 600;
+	color: var(--ab-text, #1e293b);
+	white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+
+.ab-mp-provider {
+	font-size: 11px; font-weight: 500;
+	color: var(--ab-primary, #4f46e5);
+	background: var(--ab-primary-light, #eef2ff);
+	padding: 1px 6px; border-radius: 4px;
+	white-space: nowrap; flex-shrink: 0;
+}
+
+.ab-mp-dep-badge {
+	font-size: 10px; font-weight: 600;
+	color: var(--ab-warning, #d97706);
+	background: #fffbeb;
+	padding: 1px 6px; border-radius: 4px;
+	white-space: nowrap; flex-shrink: 0;
+}
+
+.ab-mp-deprecated {
+	opacity: 0.55;
+}
+
+.ab-mp-row-meta {
+	display: flex; align-items: center; gap: 16px;
+	flex-shrink: 0;
+}
+
+.ab-mp-price {
+	font-size: 12px; font-weight: 500;
+	color: var(--ab-text-muted, #64748b);
+	font-variant-numeric: tabular-nums;
+	white-space: nowrap;
+	min-width: 90px; text-align: right; flex-shrink: 0;
+}
+
+.ab-mp-ctx {
+	font-size: 11px; font-weight: 600;
+	color: var(--ab-text-muted, #64748b);
+	background: var(--ab-bg, #f8fafc);
+	padding: 2px 6px; border-radius: 4px;
+	white-space: nowrap; min-width: 36px; text-align: center;
+	max-width: 200px; overflow: hidden; text-overflow: ellipsis;
+}
+
+/* ── Footer ─────────────────────────────────────────────────────────── */
+.ab-mp-footer {
+	display: flex; align-items: center; justify-content: space-between;
+	padding: 10px 20px;
+	border-top: 1px solid var(--ab-border, #e2e8f0);
+	font-size: 12px; color: var(--ab-text-muted, #64748b);
+}
+
+/* ── Trigger button (replaces text input) ───────────────────────────── */
+.ab-mp-trigger {
+	display: inline-flex; align-items: center; gap: 10px;
+	padding: 8px 14px;
+	background: var(--ab-card-bg, #fff);
+	border: 1px solid var(--ab-border, #e2e8f0);
+	border-radius: 6px; cursor: pointer;
+	transition: border-color 0.15s ease, box-shadow 0.15s ease;
+	max-width: 420px; width: 100%; box-sizing: border-box;
+	text-align: left;
+}
+.ab-mp-trigger:hover {
+	border-color: var(--ab-primary, #4f46e5);
+}
+.ab-mp-trigger:focus {
+	border-color: var(--ab-primary, #4f46e5);
+	box-shadow: 0 0 0 3px var(--ab-primary-light, #eef2ff);
+	outline: none;
+}
+
+.ab-mp-display-name {
+	font-size: 13px; font-weight: 600;
+	color: var(--ab-text, #1e293b);
+	flex: 1; min-width: 0;
+	overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+
+.ab-mp-display-price {
+	font-size: 11px; font-weight: 500;
+	color: var(--ab-text-muted, #64748b);
+	white-space: nowrap; flex-shrink: 0;
+}
+
+.ab-mp-display-arrow {
+	color: var(--ab-text-muted, #64748b);
+	font-size: 14px; flex-shrink: 0;
+}
+
+/* ── Responsive ─────────────────────────────────────────────────────── */
+@media screen and (max-width: 680px) {
+	.ab-mp-popup { width: 95vw; max-height: 85vh; }
+	.ab-mp-row { padding: 10px 14px; }
+	.ab-mp-row-meta { gap: 8px; }
+}
+
+/* ── Column headers (sortable) ──────────────────────────────────────── */
+.ab-mp-col-headers {
+	display: flex; align-items: center; justify-content: space-between;
+	padding: 5px 20px;
+	border-bottom: 1px solid var(--ab-border, #e2e8f0);
+	background: var(--ab-bg, #f8fafc);
+	gap: 12px; /* must match .ab-mp-row gap */
+}
+
+.ab-mp-col-headers-meta {
+	display: flex; align-items: center;
+	gap: 16px; /* must match .ab-mp-row-meta gap */
+	flex-shrink: 0;
+}
+
+.ab-mp-col-header {
+	display: inline-flex; align-items: center;
+	font-size: 10px; font-weight: 700; text-transform: uppercase;
+	letter-spacing: 0.05em;
+	color: var(--ab-text-muted, #64748b);
+	cursor: pointer; user-select: none;
+	background: none; border: none; padding: 3px 0;
+	white-space: nowrap; line-height: 1.2;
+	transition: color 0.1s ease;
+}
+.ab-mp-col-header:hover {
+	color: var(--ab-text, #1e293b);
+}
+.ab-mp-col-header.ab-mp-col-active {
+	color: var(--ab-primary, #4f46e5);
+}
+
+/* "Model" header spans the left flex-1 area */
+.ab-mp-col-model {
+	flex: 1; min-width: 0;
+}
+
+/* "Price" header width matches .ab-mp-price */
+.ab-mp-col-price {
+	font-variant-numeric: tabular-nums;
+	min-width: 90px; justify-content: flex-end;
+}
+
+/* "Context" header width matches .ab-mp-ctx (min-width 36px + padding) */
+.ab-mp-col-ctx {
+	min-width: 48px; justify-content: center; text-align: center;
+}
+
+.ab-mp-sort-arrow {
+	font-size: 9px; opacity: 0.5;
+	transition: opacity 0.1s ease;
+}
+.ab-mp-col-header.ab-mp-col-active .ab-mp-sort-arrow {
+	opacity: 1;
+}

assets/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The Poppins Project Authors (https://github.com/itfoundry/Poppins)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

assets/js/admin.js

@@ -36,6 +36,14 @@
 			url.searchParams.set('tab', tab);
 			window.history.replaceState({}, '', url);
 		}
+
+		// Update the _wp_http_referer so WordPress redirects back to this tab after save.
+		var $referer = $('#ab-settings-form input[name="_wp_http_referer"]');
+		if ($referer.length) {
+			var refUrl = new URL($referer.val(), window.location.origin);
+			refUrl.searchParams.set('tab', tab);
+			$referer.val(refUrl.pathname + refUrl.search);
+		}
 	});
 
 	/*
@@ -55,6 +63,37 @@
 				$notice.fadeOut(400, function () { $(this).remove(); });
 			}, 6000);
 		}
+
+		// On load, sync _wp_http_referer with the current tab so the first
+		// save without switching tabs still returns to the right place.
+		var currentTab = new URL(window.location).searchParams.get('tab');
+		if (currentTab) {
+			var $referer = $('#ab-settings-form input[name="_wp_http_referer"]');
+			if ($referer.length) {
+				var refUrl = new URL($referer.val(), window.location.origin);
+				refUrl.searchParams.set('tab', currentTab);
+				$referer.val(refUrl.pathname + refUrl.search);
+			}
+		}
+
+		// Resume polling if a generation is already running (e.g., user
+		// navigated away and came back, or opened a new tab mid-generation).
+		var $genBtn = $('#prautoblogger-generate-now');
+		if ($genBtn.length && config.ajaxUrl) {
+			$.ajax({
+				url: config.ajaxUrl,
+				method: 'POST',
+				data: { action: 'prautoblogger_generation_status', nonce: config.generateNonce },
+				timeout: 10000,
+				success: function (response) {
+					if (response.success && response.data && response.data.status === 'running') {
+						setButtonLoading($genBtn, config.generatingText || 'Generating…');
+						showProgress(response.data.stage || 'Generation in progress…');
+						pollGenerationStatus($genBtn);
+					}
+				}
+			});
+		}
 	});
 
 	/*
@@ -126,29 +165,76 @@
 	 * Shows pipeline stages while the request is in-flight so the user
 	 * knows it hasn't hung.
 	 */
-	var generateStages = [
-		{ text: 'Collecting sources from Reddit…',      delay: 0 },
-		{ text: 'Analyzing topics and scoring…',        delay: 8000 },
-		{ text: 'Selecting best topic…',                delay: 16000 },
-		{ text: 'Generating article draft via AI…',     delay: 24000 },
-		{ text: 'Running editorial pass…',              delay: 50000 },
-		{ text: 'Saving and publishing…',               delay: 75000 },
-		{ text: 'Almost done — finalizing…',            delay: 100000 }
-	];
-	var stageTimers = [];
+	/*
+	 * Pipeline stages are now reported by the server via the status polling
+	 * endpoint. The old client-side fake timers have been removed.
+	 */
+
+	/** Poll interval handle for generation status checks. */
+	var statusPollTimer = null;
+
+	/**
+	 * Poll the generation status endpoint until the run finishes.
+	 * Updates the progress UI and resolves the button state on completion.
+	 *
+	 * @param {jQuery} $btn The Generate Now button.
+	 */
+	function pollGenerationStatus($btn) {
+		statusPollTimer = setInterval(function () {
+			$.ajax({
+				url: config.ajaxUrl,
+				method: 'POST',
+				data: {
+					action: 'prautoblogger_generation_status',
+					nonce: config.generateNonce
+				},
+				timeout: 15000,
+				success: function (response) {
+					if (!response.success) return;
+					var d = response.data;
+
+					if (d.status === 'running') {
+						showProgress(d.stage || 'Generating…');
+						return; // Keep polling.
+					}
+
+					// Terminal state — stop polling.
+					clearInterval(statusPollTimer);
+					statusPollTimer = null;
+					hideProgress();
+					resetButton($btn, config.generateText || 'Generate Now');
+
+					if (d.status === 'complete') {
+						showStatus(
+							'Generation complete: ' + d.generated + ' generated, ' +
+							d.published + ' published, ' + d.rejected + ' rejected. ' +
+							'Cost: $' + parseFloat(d.cost).toFixed(4),
+							'success'
+						);
+					} else if (d.status === 'error') {
+						showStatus(
+							'Generation failed: ' + (d.message || 'Unknown error'),
+							'error'
+						);
+					} else {
+						// idle or unknown — generation may have finished before
+						// polling started. Reset the button cleanly.
+						hideProgress();
+					}
+				},
+				error: function () {
+					// Network blip — keep polling, don't bail on transient errors.
+				}
+			});
+		}, 5000); // Poll every 5 seconds.
+	}
 
 	$(document).on('click', '#prautoblogger-generate-now', function () {
 		var $btn = $(this);
 		if ($btn.prop('disabled')) return;
 
 		setButtonLoading($btn, config.generatingText || 'Generating…');
-
-		// Start pipeline stage messages.
-		stageTimers = [];
-		$.each(generateStages, function (i, stage) {
-			var t = setTimeout(function () { showProgress(stage.text); }, stage.delay);
-			stageTimers.push(t);
-		});
+		showProgress('Starting generation…');
 
 		$.ajax({
 			url: config.ajaxUrl,
@@ -158,21 +244,19 @@
 				nonce: config.generateNonce,
 				force: '1' // Always clear stale locks on manual runs.
 			},
-			timeout: 300000, // 5 minutes — generation can be slow.
+			timeout: 30000, // 30s is plenty — this just schedules the cron.
 			success: function (response) {
 				if (response.success) {
-					var d = response.data;
-					showStatus(
-						'Generation complete: ' + d.generated + ' generated, ' +
-						d.published + ' published, ' + d.rejected + ' rejected. ' +
-						'Cost: $' + parseFloat(d.cost).toFixed(4),
-						'success'
-					);
+					// Generation kicked off in background — start polling.
+					showProgress(response.data.message || 'Generation started…');
+					pollGenerationStatus($btn);
 				} else {
 					showStatus(
 						'Generation failed: ' + (response.data && response.data.message || 'Unknown error'),
 						'error'
 					);
+					hideProgress();
+					resetButton($btn, config.generateText || 'Generate Now');
 				}
 			},
 			error: function (xhr, status) {
@@ -180,11 +264,6 @@
 					'Request failed: ' + status + '. Check server error logs.',
 					'error'
 				);
-			},
-			complete: function () {
-				// Clear all stage timers.
-				$.each(stageTimers, function (_, t) { clearTimeout(t); });
-				stageTimers = [];
 				hideProgress();
 				resetButton($btn, config.generateText || 'Generate Now');
 			}

assets/js/ideas-browser.js

@@ -0,0 +1,157 @@
+/**
+ * PRAutoBlogger Ideas Browser — "Generate Article" button handler.
+ *
+ * Each idea row has a Generate button that triggers single-article generation
+ * via AJAX → WP-Cron background job. Polls for status and shows stage updates
+ * in the button cell, then swaps to a "View" link on completion.
+ *
+ * @see admin/class-ideas-browser.php — AJAX handlers.
+ * @see templates/admin/ideas-browser.php — Button markup.
+ */
+(function ($) {
+	'use strict';
+
+	var config = window.prautobloggerAdmin || {};
+	var pollTimers = {};
+
+	/**
+	 * Kick off generation for an idea and start polling.
+	 *
+	 * @param {jQuery} $cell  The table cell containing the button.
+	 * @param {number} ideaId Analysis result row ID.
+	 */
+	function generateFromIdea($cell, ideaId) {
+		$cell.html(
+			'<span class="dashicons dashicons-update ab-spin"></span> ' +
+			'<span class="prab-idea-stage">Starting…</span>'
+		);
+
+		$.ajax({
+			url: config.ajaxUrl,
+			method: 'POST',
+			data: {
+				action: 'prautoblogger_generate_from_idea',
+				nonce: config.ideaGenNonce,
+				idea_id: ideaId
+			},
+			timeout: 15000,
+			success: function (response) {
+				if (response.success) {
+					pollIdeaStatus($cell, ideaId);
+				} else {
+					showIdeaError($cell, ideaId, response.data && response.data.message || 'Failed to start.');
+				}
+			},
+			error: function () {
+				showIdeaError($cell, ideaId, 'Request failed.');
+			}
+		});
+	}
+
+	/**
+	 * Poll the per-idea status endpoint until generation completes.
+	 *
+	 * @param {jQuery} $cell  The table cell to update.
+	 * @param {number} ideaId Analysis result row ID.
+	 */
+	function pollIdeaStatus($cell, ideaId) {
+		pollTimers[ideaId] = setInterval(function () {
+			$.ajax({
+				url: config.ajaxUrl,
+				method: 'POST',
+				data: {
+					action: 'prautoblogger_idea_gen_status',
+					nonce: config.ideaGenNonce,
+					idea_id: ideaId
+				},
+				timeout: 10000,
+				success: function (response) {
+					if (!response.success) return;
+					var d = response.data;
+
+					if (d.status === 'running') {
+						$cell.find('.prab-idea-stage').text(d.stage || 'Generating…');
+						return;
+					}
+
+					// Terminal — stop polling.
+					clearInterval(pollTimers[ideaId]);
+					delete pollTimers[ideaId];
+
+					if (d.status === 'complete') {
+						showIdeaComplete($cell, ideaId, d);
+					} else if (d.status === 'error') {
+						showIdeaError($cell, ideaId, d.message || 'Generation failed.');
+					} else {
+						showIdeaError($cell, ideaId, 'Unknown status.');
+					}
+				}
+			});
+		}, 4000);
+	}
+
+	/**
+	 * Show the completion state with a View link.
+	 *
+	 * @param {jQuery} $cell  The table cell.
+	 * @param {number} ideaId Analysis result row ID.
+	 * @param {Object} data   Server response data.
+	 */
+	function showIdeaComplete($cell, ideaId, data) {
+		var html = '<span class="dashicons dashicons-yes-alt" style="color:#00a32a;"></span> ';
+		html += '<span style="color:#00a32a;">Done</span>';
+
+		if (data.post_id) {
+			var editUrl = config.adminUrl + 'post.php?post=' + data.post_id + '&action=edit';
+			var viewUrl = config.siteUrl + '?p=' + data.post_id;
+			html += ' &mdash; <a href="' + editUrl + '">Edit</a>';
+			html += ' | <a href="' + viewUrl + '" target="_blank">View</a>';
+		}
+
+		if (data.cost > 0) {
+			html += '<div style="font-size:11px;color:#666;margin-top:2px;">$' + parseFloat(data.cost).toFixed(4) + '</div>';
+		}
+
+		$cell.html(html);
+	}
+
+	/**
+	 * Show an error state with a retry button.
+	 *
+	 * @param {jQuery} $cell   The table cell.
+	 * @param {number} ideaId  Analysis result row ID.
+	 * @param {string} message Error message.
+	 */
+	function showIdeaError($cell, ideaId, message) {
+		$cell.html(
+			'<span class="dashicons dashicons-warning" style="color:#d63638;"></span> ' +
+			'<span style="color:#d63638; font-size:12px;">' + $('<span>').text(message).html() + '</span>' +
+			'<br><button type="button" class="button button-small prab-gen-idea-btn" data-idea-id="' + ideaId + '" style="margin-top:4px;">Retry</button>'
+		);
+	}
+
+	// Click handler for Generate / Retry buttons (event delegation).
+	$(document).on('click', '.prab-gen-idea-btn', function () {
+		var $btn = $(this);
+		if ($btn.prop('disabled')) return;
+
+		var ideaId = $btn.data('idea-id');
+		var $cell  = $btn.closest('td');
+
+		generateFromIdea($cell, ideaId);
+	});
+
+	// On page load, resume polling for any ideas that are mid-generation.
+	$(function () {
+		$('.prab-idea-gen-cell[data-status="running"]').each(function () {
+			var $cell  = $(this);
+			var ideaId = $cell.data('idea-id');
+			$cell.html(
+				'<span class="dashicons dashicons-update ab-spin"></span> ' +
+				'<span class="prab-idea-stage">Resuming…</span>'
+			);
+			pollIdeaStatus($cell, ideaId);
+		});
+	});
+
+})(jQuery);

assets/js/model-picker.js

@@ -0,0 +1,363 @@
+/**
+ * Model picker popup for PRAutoBlogger admin settings.
+ *
+ * Fetches the OpenRouter model registry via AJAX, then renders a searchable,
+ * sortable popup overlay when the user clicks a model-select trigger button.
+ * Columns: Model, Price (in / out per 1M tokens), Context window.
+ * Each column header is clickable to sort ascending/descending.
+ *
+ * @see admin/class-admin-page.php — Renders model_select fields and localizes config.
+ * @see services/class-open-router-model-registry.php — Server-side registry source.
+ */
+(function ($) {
+	'use strict';
+
+	var config          = window.prautobloggerAdmin || {};
+	var cachedModels    = null;
+	var fetchInProgress = null;
+
+	// Persists across open/close so the user's preferred sort is remembered.
+	var sortState = { col: 'name', dir: 'asc' };
+
+	/**
+	 * Fetch models from the server (cached after first call).
+	 *
+	 * @param {string} capability Filter capability (e.g. 'text→text').
+	 * @return {jQuery.Deferred} Resolves with model array.
+	 */
+	function fetchModels( capability ) {
+		// Image models are embedded in the page config — no AJAX needed.
+		if ( capability === 'image_generation' ) {
+			var imgModels = config.imageModels || [];
+			return $.Deferred().resolve( imgModels );
+		}
+
+		if ( cachedModels ) {
+			return $.Deferred().resolve( filterModels( cachedModels, capability ) );
+		}
+
+		if ( fetchInProgress ) {
+			return fetchInProgress.then( function () {
+				return filterModels( cachedModels, capability );
+			} );
+		}
+
+		fetchInProgress = $.ajax( {
+			url:    config.ajaxUrl,
+			method: 'POST',
+			data: {
+				action: 'prautoblogger_get_models',
+				nonce:  config.modelsNonce
+			},
+			timeout: 15000
+		} ).then( function ( response ) {
+			fetchInProgress = null;
+			if ( response.success && Array.isArray( response.data ) ) {
+				cachedModels = response.data;
+				return filterModels( cachedModels, capability );
+			}
+			cachedModels = [];
+			return [];
+		}, function () {
+			fetchInProgress = null;
+			cachedModels    = [];
+			return [];
+		} );
+
+		return fetchInProgress;
+	}
+
+	/**
+	 * Filter model array by capability.
+	 *
+	 * @param {Array}  models     Full model list.
+	 * @param {string} capability Capability string to match.
+	 * @return {Array} Filtered models.
+	 */
+	function filterModels( models, capability ) {
+		if ( ! capability ) return models;
+		return models.filter( function ( m ) {
+			return m.capabilities && m.capabilities.indexOf( capability ) !== -1;
+		} );
+	}
+
+	/**
+	 * Sort a model array according to the current sortState.
+	 * Deprecated models always sink to the bottom regardless of column.
+	 *
+	 * @param {Array} arr Model array to sort (not mutated — returns a new array).
+	 * @return {Array} Sorted copy.
+	 */
+	function applySort( arr ) {
+		var col = sortState.col;
+		var dir = sortState.dir;
+
+		return arr.slice().sort( function ( a, b ) {
+			// Deprecated always last.
+			if ( a.deprecated !== b.deprecated ) {
+				return a.deprecated ? 1 : -1;
+			}
+
+			var valA, valB;
+
+			if ( col === 'price' ) {
+				// Image models use cost_per_image; text models use input_price_per_m.
+				valA = ( a.cost_per_image !== undefined ) ? a.cost_per_image : ( a.input_price_per_m || 0 );
+				valB = ( b.cost_per_image !== undefined ) ? b.cost_per_image : ( b.input_price_per_m || 0 );
+			} else if ( col === 'context' ) {
+				valA = a.context_length || 0;
+				valB = b.context_length || 0;
+			} else {
+				// Default: sort by model name.
+				valA = ( a.name || '' ).toLowerCase();
+				valB = ( b.name || '' ).toLowerCase();
+			}
+
+			if ( valA < valB ) return dir === 'asc' ? -1 : 1;
+			if ( valA > valB ) return dir === 'asc' ? 1  : -1;
+			return 0;
+		} );
+	}
+
+	/**
+	 * Format a price-per-million-tokens value for display.
+	 *
+	 * @param {number} price Price per 1M tokens.
+	 * @return {string} Formatted string like "$0.25" or "Free".
+	 */
+	function formatPrice( price ) {
+		if ( ! price || price <= 0 ) return 'Free';
+		if ( price < 0.01 )         return '$' + price.toFixed( 4 );
+		if ( price < 1 )            return '$' + price.toFixed( 2 );
+		return '$' + price.toFixed( 2 );
+	}
+
+	/**
+	 * Format context length for display.
+	 *
+	 * @param {number} ctx Context length in tokens.
+	 * @return {string} Formatted string like "128K" or "1M".
+	 */
+	function formatContext( ctx ) {
+		if ( ! ctx )          return '—';
+		if ( ctx >= 1000000 ) return ( ctx / 1000000 ).toFixed( 0 ) + 'M';
+		if ( ctx >= 1000 )    return Math.round( ctx / 1000 ) + 'K';
+		return ctx.toString();
+	}
+
+	/**
+	 * Build HTML for a single model row in the picker list.
+	 *
+	 * @param {Object} model Normalized model record.
+	 * @return {string} HTML string.
+	 */
+	function renderModelRow( model ) {
+		var deprecated   = model.deprecated ? ' ab-mp-deprecated' : '';
+		var isImageModel = model.cost_per_image !== undefined && model.cost_per_image > 0;
+		var priceHtml, priceTitle, metaRight;
+
+		if ( isImageModel ) {
+			priceHtml  = '$' + model.cost_per_image.toFixed( 4 ) + '/image';
+			priceTitle = 'Cost per generated image';
+			metaRight  = model.description
+				? '<span class="ab-mp-ctx" title="Details">' + escHtml( model.description ) + '</span>'
+				: '';
+		} else {
+			priceHtml  = formatPrice( model.input_price_per_m ) + ' / ' + formatPrice( model.output_price_per_m );
+			priceTitle = 'Input / Output per 1M tokens';
+			metaRight  = '<span class="ab-mp-ctx" title="Context window">' + formatContext( model.context_length ) + '</span>';
+		}
+
+		return (
+			'<div class="ab-mp-row' + deprecated + '" data-model-id="' + escAttr( model.id ) + '">' +
+				'<div class="ab-mp-row-main">' +
+					'<span class="ab-mp-name">' + escHtml( model.name ) + '</span>' +
+					'<span class="ab-mp-provider">' + escHtml( model.provider ) + '</span>' +
+					( model.deprecated ? '<span class="ab-mp-dep-badge">deprecated</span>' : '' ) +
+				'</div>' +
+				'<div class="ab-mp-row-meta">' +
+					metaRight +
+					'<span class="ab-mp-price" title="' + priceTitle + '">' + priceHtml + '</span>' +
+				'</div>' +
+			'</div>'
+		);
+	}
+
+	/** Minimal HTML escaping for display. */
+	function escHtml( str ) {
+		if ( ! str ) return '';
+		return str.replace( /&/g, '&amp;' ).replace( /</g, '&lt;' ).replace( />/g, '&gt;' );
+	}
+
+	/** Escape a string for use in an HTML attribute. */
+	function escAttr( str ) {
+		return escHtml( str ).replace( /"/g, '&quot;' );
+	}
+
+	/**
+	 * Open the model picker popup for a given trigger button.
+	 *
+	 * @param {jQuery} $trigger The .ab-mp-trigger button that was clicked.
+	 */
+	function openPicker( $trigger ) {
+		var fieldId    = $trigger.data( 'field-id' );
+		var capability = $trigger.data( 'capability' ) || '';
+
+		var isImageCap = capability === 'image_generation';
+		var priceLabel = isImageCap ? 'Cost per generated image' : 'Prices per 1M tokens (in / out)';
+
+		// ── Build overlay + popup ───────────────────────────────────────
+		var $overlay = $( '<div class="ab-mp-overlay"></div>' );
+		var $popup   = $(
+			'<div class="ab-mp-popup">' +
+				'<div class="ab-mp-header">' +
+					'<span class="ab-mp-title">Select Model</span>' +
+					'<button type="button" class="ab-mp-close">&times;</button>' +
+				'</div>' +
+				'<div class="ab-mp-search-wrap">' +
+					'<input type="text" class="ab-mp-search" placeholder="Search models…" autocomplete="off" />' +
+				'</div>' +
+				'<div class="ab-mp-col-headers">' +
+					'<button type="button" class="ab-mp-col-header ab-mp-col-model" data-col="name">Model <span class="ab-mp-sort-arrow"></span></button>' +
+					'<div class="ab-mp-col-headers-meta">' +
+						'<button type="button" class="ab-mp-col-header ab-mp-col-ctx" data-col="context">Context <span class="ab-mp-sort-arrow"></span></button>' +
+						'<button type="button" class="ab-mp-col-header ab-mp-col-price" data-col="price">Price (in / out) <span class="ab-mp-sort-arrow"></span></button>' +
+					'</div>' +
+				'</div>' +
+				'<div class="ab-mp-list"><div class="ab-mp-loading">Loading models…</div></div>' +
+				'<div class="ab-mp-footer">' +
+					'<span class="ab-mp-count"></span>' +
+					'<span class="ab-mp-price-label">' + priceLabel + '</span>' +
+				'</div>' +
+			'</div>'
+		);
+
+		$overlay.append( $popup );
+		$( 'body' ).append( $overlay );
+
+		var $search      = $popup.find( '.ab-mp-search' );
+		var $list        = $popup.find( '.ab-mp-list' );
+		var $count       = $popup.find( '.ab-mp-count' );
+		var $colHeaders  = $popup.find( '.ab-mp-col-headers' );
+		var allModels    = [];
+		var currentQuery = '';
+
+		// Focus search after render.
+		setTimeout( function () { $search.focus(); }, 50 );
+
+		// ── Sort header indicators ──────────────────────────────────────
+		/** Update active-column highlight and sort arrow glyphs. */
+		function updateSortHeaders() {
+			$colHeaders.find( '.ab-mp-col-header' ).each( function () {
+				var col    = $( this ).data( 'col' );
+				var $arrow = $( this ).find( '.ab-mp-sort-arrow' );
+				if ( col === sortState.col ) {
+					$( this ).addClass( 'ab-mp-col-active' );
+					$arrow.text( sortState.dir === 'asc' ? ' ▲' : ' ▼' );
+				} else {
+					$( this ).removeClass( 'ab-mp-col-active' );
+					$arrow.text( ' ⇅' );
+				}
+			} );
+		}
+
+		// ── Render ──────────────────────────────────────────────────────
+		/** Render filtered + sorted model list. */
+		function renderList( models, query ) {
+			var filtered = models;
+			if ( query ) {
+				var q = query.toLowerCase();
+				filtered = models.filter( function ( m ) {
+					return ( m.name     && m.name.toLowerCase().indexOf( q )     !== -1 ) ||
+					       ( m.id       && m.id.toLowerCase().indexOf( q )       !== -1 ) ||
+					       ( m.provider && m.provider.toLowerCase().indexOf( q ) !== -1 );
+				} );
+			}
+
+			filtered = applySort( filtered );
+
+			if ( filtered.length === 0 ) {
+				$list.html( '<div class="ab-mp-empty">No models found.</div>' );
+			} else {
+				var html = '';
+				for ( var i = 0; i < filtered.length; i++ ) {
+					html += renderModelRow( filtered[ i ] );
+				}
+				$list.html( html );
+			}
+			$count.text( filtered.length + ' model' + ( filtered.length !== 1 ? 's' : '' ) );
+			updateSortHeaders();
+		}
+
+		// Initial render after data loads.
+		fetchModels( capability ).then( function ( models ) {
+			allModels = models;
+			renderList( allModels, currentQuery );
+		} );
+
+		// ── Column header sort clicks ───────────────────────────────────
+		$colHeaders.on( 'click', '.ab-mp-col-header', function () {
+			var col = $( this ).data( 'col' );
+			if ( sortState.col === col ) {
+				sortState.dir = sortState.dir === 'asc' ? 'desc' : 'asc';
+			} else {
+				sortState.col = col;
+				sortState.dir = 'asc';
+			}
+			renderList( allModels, currentQuery );
+		} );
+
+		// ── Search (debounced) ──────────────────────────────────────────
+		var searchTimer = null;
+		$search.on( 'input', function () {
+			currentQuery = $( this ).val();
+			clearTimeout( searchTimer );
+			searchTimer = setTimeout( function () {
+				renderList( allModels, currentQuery );
+			}, 150 );
+		} );
+
+		// ── Select a model ──────────────────────────────────────────────
+		$list.on( 'click', '.ab-mp-row', function () {
+			var id    = $( this ).data( 'model-id' );
+			var model = null;
+			for ( var i = 0; i < allModels.length; i++ ) {
+				if ( allModels[ i ].id === id ) { model = allModels[ i ]; break; }
+			}
+			if ( ! model ) return;
+
+			$( '#' + fieldId ).val( model.id );
+			$trigger.find( '.ab-mp-display-name' ).text( model.name || model.id );
+
+			var isImageModel = model.cost_per_image !== undefined && model.cost_per_image > 0;
+			var priceText    = isImageModel
+				? '$' + model.cost_per_image.toFixed( 4 ) + '/image'
+				: formatPrice( model.input_price_per_m ) + ' / ' + formatPrice( model.output_price_per_m );
+			$trigger.find( '.ab-mp-display-price' ).text( priceText );
+			closePicker();
+		} );
+
+		// ── Close ───────────────────────────────────────────────────────
+		function closePicker() {
+			$overlay.remove();
+		}
+
+		$popup.find( '.ab-mp-close' ).on( 'click', closePicker );
+		$overlay.on( 'click', function ( e ) {
+			if ( $( e.target ).is( '.ab-mp-overlay' ) ) closePicker();
+		} );
+		$( document ).on( 'keydown.abModelPicker', function ( e ) {
+			if ( e.key === 'Escape' ) {
+				closePicker();
+				$( document ).off( 'keydown.abModelPicker' );
+			}
+		} );
+	}
+
+	// Bind click on all model picker triggers.
+	$( document ).on( 'click', '.ab-mp-trigger', function ( e ) {
+		e.preventDefault();
+		openPicker( $( this ) );
+	} );
+
+} )( jQuery );

composer.json

@@ -8,7 +8,6 @@
 },
 "require-dev": {
 "phpunit/phpunit": "^9.5",
-"wp-phpunit/wp-phpunit": "^6.0",
 "brain/monkey": "^2.6"
 },
 "autoload": {

eval/dataset.json

@@ -0,0 +1,142 @@
+[
+  {
+    "id": "bpc157-healing",
+    "topic": "BPC-157 healing protocols for tendons and gut lining",
+    "expected_keywords": ["BPC-157", "tendon", "gut", "healing"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "tb500-muscle-recovery",
+    "topic": "TB-500 for accelerated muscle recovery and repair",
+    "expected_keywords": ["TB-500", "muscle", "recovery", "growth"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "ghk-cu-skin-collagen",
+    "topic": "GHK-Cu peptide for skin collagen synthesis and anti-aging",
+    "expected_keywords": ["GHK-Cu", "collagen", "skin", "aging"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "semaglutide-glp1-weight",
+    "topic": "GLP-1 receptor agonists like Semaglutide for metabolic health",
+    "expected_keywords": ["Semaglutide", "GLP-1", "weight", "metabolism"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "ipamorelin-growth-hormone",
+    "topic": "Ipamorelin for natural growth hormone stimulation and recovery",
+    "expected_keywords": ["Ipamorelin", "growth hormone", "HGH", "secretagogue"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "hexarelin-strength-gains",
+    "topic": "Hexarelin peptide for lean muscle and strength improvement",
+    "expected_keywords": ["Hexarelin", "muscle", "strength", "lean"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "semax-cognitive-enhancement",
+    "topic": "Semax nootropic peptide for cognitive function and focus",
+    "expected_keywords": ["Semax", "cognition", "focus", "neuroprotection"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "selank-anxiety-stress",
+    "topic": "Selank peptide for anxiety reduction and stress management",
+    "expected_keywords": ["Selank", "anxiety", "stress", "mood"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "oxytocin-social-bonding",
+    "topic": "Oxytocin peptide hormone and its role in social connection",
+    "expected_keywords": ["Oxytocin", "social", "bonding", "neuropeptide"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "kisspeptin-fertility-hormone",
+    "topic": "Kisspeptin's role in reproductive health and hormone signaling",
+    "expected_keywords": ["Kisspeptin", "fertility", "hormone", "reproduction"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "melanotan-tanning-peptide",
+    "topic": "Melanotan peptide for pigmentation and UV protection",
+    "expected_keywords": ["Melanotan", "melanin", "tanning", "skin"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "cerebrolysin-neuroprotection",
+    "topic": "Cerebrolysin for brain health and neuroprotection",
+    "expected_keywords": ["Cerebrolysin", "brain", "neuroprotection", "cognition"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "epithalon-telomerase-aging",
+    "topic": "Epithalon peptide and telomerase activation for longevity",
+    "expected_keywords": ["Epithalon", "telomerase", "aging", "longevity"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "thymosin-immune-function",
+    "topic": "Thymosin alpha-1 for immune system enhancement",
+    "expected_keywords": ["Thymosin", "immune", "T-cells", "immunity"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "igf1-muscle-growth-aging",
+    "topic": "IGF-1 peptide for muscle growth, recovery, and anti-aging",
+    "expected_keywords": ["IGF-1", "muscle", "growth", "aging"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "mechano-growth-factor",
+    "topic": "MGF (Mechano Growth Factor) for muscle hypertrophy",
+    "expected_keywords": ["MGF", "mechano", "muscle", "hypertrophy"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "ll37-antimicrobial-peptide",
+    "topic": "LL-37 antimicrobial peptide for immune and skin health",
+    "expected_keywords": ["LL-37", "antimicrobial", "immune", "peptide"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "lactoferrin-iron-immunity",
+    "topic": "Lactoferrin peptide for iron absorption and immune support",
+    "expected_keywords": ["Lactoferrin", "iron", "immune", "absorption"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "collagen-peptides-joints",
+    "topic": "Collagen peptides for joint health and connective tissue repair",
+    "expected_keywords": ["Collagen", "peptides", "joints", "connective tissue"],
+    "min_words": 700,
+    "style": "comic"
+  },
+  {
+    "id": "ckgp-cognitive-longevity",
+    "topic": "Cognitive peptides and nootropic stacks for brain longevity",
+    "expected_keywords": ["peptide", "cognitive", "nootropic", "brain"],
+    "min_words": 700,
+    "style": "comic"
+  }
+]

includes/admin/class-admin-notices.php

@@ -2,10 +2,12 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Displays admin notices for onboarding, errors, and budget warnings.
  *
  * Triggered by: PRAutoBlogger::register_admin_hooks() on `admin_notices`.
- * Dependencies: PRAutoBlogger_Cost_Tracker (for budget warnings).
+ * Dependencies: PRAutoBlogger_Cost_Reporter (for budget warnings).
  *
  * @see class-prautoblogger.php — Registers the hook.
  */
@@ -51,8 +53,8 @@ class PRAutoBlogger_Admin_Notices {
 	 * @return void
 	 */
 	private function check_budget_notice(): void {
-		$cost_tracker = new PRAutoBlogger_Cost_Tracker();
-		$utilization  = $cost_tracker->get_budget_utilization();
+		$cost_reporter = new PRAutoBlogger_Cost_Reporter();
+		$utilization   = $cost_reporter->get_budget_utilization();
 
 		if ( $utilization >= 100.0 ) {
 			printf(
@@ -62,11 +64,13 @@ class PRAutoBlogger_Admin_Notices {
 		} elseif ( $utilization >= 80.0 ) {
 			printf(
 				'<div class="notice notice-warning"><p>%s</p></div>',
-				esc_html( sprintf(
+				esc_html(
+					sprintf(
 					/* translators: %s: budget utilization percentage */
-					__( 'PRAutoBlogger: Monthly API budget is at %.0f%%. Consider increasing the budget or reducing daily article count.', 'prautoblogger' ),
-					$utilization
-				) )
+						__( 'PRAutoBlogger: Monthly API budget is at %.0f%%. Consider increasing the budget or reducing daily article count.', 'prautoblogger' ),
+						$utilization
+					)
+				)
 			);
 		}
 	}

includes/admin/class-admin-page.php

@@ -2,6 +2,8 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Registers and renders the main PRAutoBlogger settings page in wp-admin.
  *
  * Uses the WordPress Settings API for option registration, sanitization, and rendering.
@@ -26,7 +28,7 @@ class PRAutoBlogger_Admin_Page {
 			__( 'PRAutoBlogger', 'prautoblogger' ),
 			'manage_options',
 			self::PAGE_SLUG,
-			[ $this, 'render_page' ],
+			array( $this, 'render_page' ),
 			'dashicons-edit-page',
 			30
 		);
@@ -43,40 +45,65 @@ class PRAutoBlogger_Admin_Page {
 
 		foreach ( $fields as $field ) {
 			$section = $field['section'] ?? 'prautoblogger_api';
-			register_setting( self::OPTION_GROUP, $field['id'], [
-				'type'              => $field['wp_type'] ?? 'string',
-				'sanitize_callback' => [ $this, 'sanitize_field' ],
-				'default'           => $field['default'] ?? '',
-			] );
-			add_settings_field( $field['id'], $field['label'], [ $this, 'render_field' ], self::PAGE_SLUG, $section, $field );
+			register_setting(
+				self::OPTION_GROUP,
+				$field['id'],
+				array(
+					'type'              => $field['wp_type'] ?? 'string',
+					'sanitize_callback' => array( $this, 'sanitize_field' ),
+					'default'           => $field['default'] ?? '',
+				)
+			);
+			add_settings_field( $field['id'], $field['label'], array( $this, 'render_field' ), self::PAGE_SLUG, $section, $field );
 		}
 	}
 
 	/** Enqueue admin CSS and JS on all PRAutoBlogger admin pages. */
 	public function on_enqueue_assets( string $hook_suffix ): void {
-		$pages = [
+		$pages = array(
 			'toplevel_page_' . self::PAGE_SLUG,
 			'prautoblogger_page_prautoblogger-metrics',
 			'prautoblogger_page_prautoblogger-review-queue',
+			'prautoblogger_page_prautoblogger-ideas',
 			'prautoblogger_page_prautoblogger-logs',
-		];
+		);
 		if ( ! in_array( $hook_suffix, $pages, true ) ) {
 			return;
 		}
 
-		wp_enqueue_style( 'prautoblogger-admin', PRAUTOBLOGGER_PLUGIN_URL . 'assets/css/admin.css', [], PRAUTOBLOGGER_VERSION );
-		wp_enqueue_script( 'prautoblogger-admin', PRAUTOBLOGGER_PLUGIN_URL . 'assets/js/admin.js', [ 'jquery' ], PRAUTOBLOGGER_VERSION, true );
+		wp_enqueue_style( 'prautoblogger-admin', PRAUTOBLOGGER_PLUGIN_URL . 'assets/css/admin.css', array(), PRAUTOBLOGGER_VERSION );
+		wp_enqueue_style( 'prautoblogger-model-picker', PRAUTOBLOGGER_PLUGIN_URL . 'assets/css/model-picker.css', array( 'prautoblogger-admin' ), PRAUTOBLOGGER_VERSION );
+		wp_enqueue_script( 'prautoblogger-admin', PRAUTOBLOGGER_PLUGIN_URL . 'assets/js/admin.js', array( 'jquery' ), PRAUTOBLOGGER_VERSION, true );
+		wp_enqueue_script( 'prautoblogger-model-picker', PRAUTOBLOGGER_PLUGIN_URL . 'assets/js/model-picker.js', array( 'jquery', 'prautoblogger-admin' ), PRAUTOBLOGGER_VERSION, true );
+		wp_enqueue_script( 'peptiderepo-model-picker', PRAUTOBLOGGER_PLUGIN_URL . 'assets/admin/peptiderepo-model-picker.js', array( 'jquery' ), PRAUTOBLOGGER_VERSION, true );
+		wp_enqueue_style( 'peptiderepo-model-picker', PRAUTOBLOGGER_PLUGIN_URL . 'assets/admin/peptiderepo-model-picker.css', array(), PRAUTOBLOGGER_VERSION );
 
-		wp_localize_script( 'prautoblogger-admin', 'prautobloggerAdmin', [
-			'ajaxUrl'        => admin_url( 'admin-ajax.php' ),
-			'generateNonce'  => wp_create_nonce( 'prautoblogger_generate_now' ),
-			'testNonce'      => wp_create_nonce( 'prautoblogger_test_connection' ),
-			'reviewNonce'    => wp_create_nonce( 'prautoblogger_review_queue' ),
-			'generatingText' => __( 'Generating...', 'prautoblogger' ),
-			'generateText'   => __( 'Generate Now', 'prautoblogger' ),
-			'testingText'    => __( 'Testing...', 'prautoblogger' ),
-			'testText'       => __( 'Test Connections', 'prautoblogger' ),
-		] );
+		wp_localize_script(
+			'prautoblogger-admin',
+			'prautobloggerAdmin',
+			array(
+				'ajaxUrl'        => admin_url( 'admin-ajax.php' ),
+				'adminUrl'       => admin_url(),
+				'siteUrl'        => home_url( '/' ),
+				'generateNonce'  => wp_create_nonce( 'prautoblogger_generate_now' ),
+				'imageNonce'     => wp_create_nonce( 'prautoblogger_generate_image' ),
+				'testNonce'      => wp_create_nonce( 'prautoblogger_test_connection' ),
+				'modelsNonce'    => wp_create_nonce( 'prautoblogger_get_models' ),
+				'reviewNonce'    => wp_create_nonce( 'prautoblogger_review_queue' ),
+				'ideaGenNonce'   => wp_create_nonce( 'prautoblogger_idea_gen' ),
+				'generatingText' => __( 'Generating...', 'prautoblogger' ),
+				'generateText'   => __( 'Generate Now', 'prautoblogger' ),
+				'testingText'    => __( 'Testing...', 'prautoblogger' ),
+				'testText'       => __( 'Test Connections', 'prautoblogger' ),
+				// Image models for the picker — defined in the settings class to keep this file short.
+				'imageModels'    => PRAutoBlogger_Settings_Fields_Extended::get_image_models(),
+			)
+		);
+
+		// Ideas browser: generate-from-idea JS (only on the Ideas page).
+		if ( 'prautoblogger_page_prautoblogger-ideas' === $hook_suffix ) {
+			wp_enqueue_script( 'prautoblogger-ideas-browser', PRAUTOBLOGGER_PLUGIN_URL . 'assets/js/ideas-browser.js', array( 'jquery', 'prautoblogger-admin' ), PRAUTOBLOGGER_VERSION, true );
+		}
 	}
 
 	/** Render the settings page (delegates to template). */
@@ -112,15 +139,22 @@ class PRAutoBlogger_Admin_Page {
 			case 'url':
 			case 'time':
 				$attrs = '';
-				if ( isset( $args['min'] ) ) { $attrs .= ' min="' . esc_attr( (string) $args['min'] ) . '"'; }
-				if ( isset( $args['max'] ) ) { $attrs .= ' max="' . esc_attr( (string) $args['max'] ) . '"'; }
-				if ( isset( $args['step'] ) ) { $attrs .= ' step="' . esc_attr( (string) $args['step'] ) . '"'; }
+				if ( isset( $args['min'] ) ) {
+					$attrs .= ' min="' . esc_attr( (string) $args['min'] ) . '"'; }
+				if ( isset( $args['max'] ) ) {
+					$attrs .= ' max="' . esc_attr( (string) $args['max'] ) . '"'; }
+				if ( isset( $args['step'] ) ) {
+					$attrs .= ' step="' . esc_attr( (string) $args['step'] ) . '"'; }
 				printf( '<input type="%s" id="%s" name="%s" value="%s" class="ab-input" %s />', esc_attr( $type ), $id, $id, esc_attr( (string) $value ), $attrs );
 				break;
 
 			case 'password':
-				printf( '<input type="password" id="%s" name="%s" value="" class="ab-input" placeholder="%s" autocomplete="off" />',
-					$id, $id, '' !== $value ? esc_attr__( 'Saved (enter new value to change)', 'prautoblogger' ) : '' );
+				printf(
+					'<input type="password" id="%s" name="%s" value="" class="ab-input" placeholder="%s" autocomplete="off" />',
+					$id,
+					$id,
+					'' !== $value ? esc_attr__( 'Saved (enter new value to change)', 'prautoblogger' ) : ''
+				);
 				break;
 
 			case 'textarea':
@@ -129,38 +163,76 @@ class PRAutoBlogger_Admin_Page {
 
 			case 'select':
 				printf( '<select id="%s" name="%s" class="ab-select">', $id, $id );
-				foreach ( ( $args['options'] ?? [] ) as $v => $label ) {
+				foreach ( ( $args['options'] ?? array() ) as $v => $label ) {
 					printf( '<option value="%s"%s>%s</option>', esc_attr( (string) $v ), selected( $value, (string) $v, false ), esc_html( $label ) );
 				}
 				echo '</select>';
 				break;
 
 			case 'toggle':
-				$checked = in_array( $value, [ '1', 'yes', true ], true );
-				printf( '<label class="ab-toggle"><input type="hidden" name="%s" value="0" /><input type="checkbox" name="%s" value="1" %s /><span class="ab-toggle-slider"></span></label>',
-					$id, $id, checked( $checked, true, false ) );
+				$checked = in_array( $value, array( '1', 'yes', true ), true );
+				printf(
+					'<label class="ab-toggle"><input type="hidden" name="%s" value="0" /><input type="checkbox" name="%s" value="1" %s /><span class="ab-toggle-slider"></span></label>',
+					$id,
+					$id,
+					checked( $checked, true, false )
+				);
 				break;
 
 			case 'checkboxes':
-				$current = json_decode( (string) $value, true ) ?: [];
-				foreach ( ( $args['options'] ?? [] ) as $v => $label ) {
+				$current = json_decode( (string) $value, true ) ?? array();
+				// Hidden input ensures an empty value is POSTed when all boxes
+				// are unchecked — without this, the browser omits the field
+				// entirely, so WordPress never fires the sanitize callback and
+				// the old value persists in wp_options.
+				printf( '<input type="hidden" name="%s" value="" />', $id );
+				foreach ( ( $args['options'] ?? array() ) as $v => $label ) {
 					$is_checked = in_array( $v, $current, true );
 					$disabled   = strpos( $label, 'coming soon' ) !== false ? ' disabled' : '';
-					printf( '<label class="ab-checkbox-label"><input type="checkbox" name="%s[]" value="%s" %s%s /> %s</label>',
-						$id, esc_attr( $v ), checked( $is_checked, true, false ), $disabled, esc_html( $label ) );
+					printf(
+						'<label class="ab-checkbox-label"><input type="checkbox" name="%s[]" value="%s" %s%s /> %s</label>',
+						$id,
+						esc_attr( $v ),
+						checked( $is_checked, true, false ),
+						$disabled,
+						esc_html( $label )
+					);
 				}
 				break;
 
+			case 'model_select':
+				$this->render_model_select_field( $id, (string) $value, $args );
+				break;
+
 			case 'source_status':
 				$this->render_source_status_field();
 				break;
 
 			case 'author_select':
-				wp_dropdown_users( [ 'name' => $id, 'id' => $id, 'selected' => absint( $value ), 'show_option_none' => __( '— Auto (first admin) —', 'prautoblogger' ), 'option_none_value' => '0', 'class' => 'ab-select' ] );
+				wp_dropdown_users(
+					array(
+						'name'              => $id,
+						'id'                => $id,
+						'selected'          => absint( $value ),
+						'show_option_none'  => __( '— Auto (first admin) —', 'prautoblogger' ),
+						'option_none_value' => '0',
+						'class'             => 'ab-select',
+					)
+				);
 				break;
 
 			case 'category_select':
-				wp_dropdown_categories( [ 'name' => $id, 'id' => $id, 'selected' => absint( $value ), 'show_option_none' => __( '— Auto-assign by type —', 'prautoblogger' ), 'option_none_value' => '0', 'class' => 'ab-select', 'hide_empty' => false ] );
+				wp_dropdown_categories(
+					array(
+						'name'              => $id,
+						'id'                => $id,
+						'selected'          => absint( $value ),
+						'show_option_none'  => __( '— Auto-assign by type —', 'prautoblogger' ),
+						'option_none_value' => '0',
+						'class'             => 'ab-select',
+						'hide_empty'        => false,
+					)
+				);
 				break;
 		}
 
@@ -173,58 +245,25 @@ class PRAutoBlogger_Admin_Page {
 	}
 
 	/**
-	 * Render the Reddit source status indicator.
+	 * Delegate source status rendering to the dedicated field class.
 	 *
-	 * Shows Reddit RSS (primary) and .json (fallback) availability
-	 * with live status checks via transient cache and rate limit info.
-	 *
-	 * Side effects: Reads transients for cached availability status.
-	 *
-	 * @return void
+	 * @see admin/fields/class-source-status-field.php
 	 */
 	private function render_source_status_field(): void {
-		$last_collection  = get_option( 'prautoblogger_last_collection_time', '' );
-		$last_source_used = get_option( 'prautoblogger_last_source_used', '' );
+		PRAutoBlogger_Source_Status_Field::render();
+	}
 
-		echo '<div class="ab-source-status">';
-
-		// Reddit RSS — primary source.
-		printf(
-			'<div class="ab-source-row">'
-			. '<span class="ab-source-dot ab-status-ok"></span>'
-			. '<strong>%s</strong> <span class="ab-source-badge">%s</span>'
-			. '<span class="ab-source-label">%s</span>'
-			. '</div>',
-			esc_html__( 'Reddit RSS', 'prautoblogger' ),
-			esc_html__( 'Primary', 'prautoblogger' ),
-			esc_html__( 'Reliable from all IPs', 'prautoblogger' )
-		);
-
-		// Reddit .json — fallback source.
-		printf(
-			'<div class="ab-source-row">'
-			. '<span class="ab-source-dot ab-status-ok"></span>'
-			. '<strong>%s</strong> <span class="ab-source-badge ab-badge-secondary">%s</span>'
-			. '<span class="ab-source-label">%s</span>'
-			. '</div>',
-			esc_html__( 'Reddit .json', 'prautoblogger' ),
-			esc_html__( 'Fallback + Comments', 'prautoblogger' ),
-			esc_html__( 'May be IP-blocked on some hosts', 'prautoblogger' )
-		);
-
-		// Last collection info.
-		if ( '' !== $last_collection ) {
-			$time_ago = human_time_diff( (int) $last_collection, time() );
-			printf(
-				'<div class="ab-source-meta">%s <strong>%s</strong> %s</div>',
-				esc_html__( 'Last collection:', 'prautoblogger' ),
-				/* translators: %s is a human-readable time difference like "2 hours" */
-				esc_html( sprintf( __( '%s ago', 'prautoblogger' ), $time_ago ) ),
-				'' !== $last_source_used ? esc_html( sprintf( __( 'via %s', 'prautoblogger' ), $last_source_used ) ) : ''
-			);
-		}
-
-		echo '</div>';
+	/**
+	 * Delegate model picker rendering to the dedicated field class.
+	 *
+	 * @param string               $id    Field HTML id/name.
+	 * @param string               $value Current model id.
+	 * @param array<string, mixed> $args  Field definition.
+	 *
+	 * @see admin/fields/class-openrouter-model-field.php
+	 */
+	private function render_model_select_field( string $id, string $value, array $args ): void {
+		PRAutoBlogger_OpenRouter_Model_Field::render( $id, $value, $args );
 	}
 
 	/**
@@ -240,7 +279,7 @@ class PRAutoBlogger_Admin_Page {
 			$option_name = substr( $filter, strlen( 'sanitize_option_' ) );
 		}
 
-		$encrypted = [ 'prautoblogger_openrouter_api_key', 'prautoblogger_ga4_credentials_json' ];
+		$encrypted = array( 'prautoblogger_openrouter_api_key', 'prautoblogger_ga4_credentials_json', 'prautoblogger_runware_api_key' );
 		if ( in_array( $option_name, $encrypted, true ) ) {
 			// Empty value means password field wasn't touched — keep existing.
 			if ( '' === $value ) {
@@ -260,21 +299,54 @@ class PRAutoBlogger_Admin_Page {
 			return PRAutoBlogger_Encryption::encrypt( sanitize_text_field( $value ) );
 		}
 
-		$json_fields = [ 'prautoblogger_target_subreddits', 'prautoblogger_topic_exclusions', 'prautoblogger_enabled_sources' ];
+		$json_fields = array( 'prautoblogger_target_subreddits', 'prautoblogger_topic_exclusions', 'prautoblogger_enabled_sources' );
 		if ( in_array( $option_name, $json_fields, true ) ) {
-			if ( is_array( $value ) ) { return wp_json_encode( array_values( array_map( 'sanitize_text_field', $value ) ) ); }
-			if ( is_string( $value ) && '[' !== substr( trim( $value ), 0, 1 ) ) {
-				$items = array_filter( array_map( 'trim', explode( ',', $value ) ) );
-				return wp_json_encode( array_values( $items ) );
+			// PHP array from checkboxes — sanitize each item and re-encode.
+			if ( is_array( $value ) ) {
+				return wp_json_encode( array_values( array_map( 'sanitize_text_field', $value ) ) );
 			}
-			return sanitize_text_field( $value );
+
+			$trimmed = trim( (string) $value );
+
+			// Already JSON-encoded array — decode, sanitize each item, re-encode.
+			// This prevents sanitize_text_field() from mangling the JSON string,
+			// which caused json_decode() on read to return null → empty subreddits.
+			if ( '[' === substr( $trimmed, 0, 1 ) ) {
+				$decoded = json_decode( $trimmed, true );
+				if ( is_array( $decoded ) ) {
+					return wp_json_encode( array_values( array_map( 'sanitize_text_field', $decoded ) ) );
+				}
+			}
+
+			// Comma-separated plain text — split, sanitize, encode as JSON array.
+			$items = array_filter( array_map( 'trim', explode( ',', $trimmed ) ) );
+			return wp_json_encode( array_values( array_map( 'sanitize_text_field', $items ) ) );
 		}
 
-		$numeric = [ 'prautoblogger_daily_article_target', 'prautoblogger_monthly_budget_usd', 'prautoblogger_min_word_count', 'prautoblogger_max_word_count', 'prautoblogger_default_author', 'prautoblogger_default_category', 'prautoblogger_pullpush_cache_ttl', 'prautoblogger_reddit_posts_per_subreddit' ];
+		$numeric = array( 'prautoblogger_daily_article_target', 'prautoblogger_monthly_budget_usd', 'prautoblogger_min_word_count', 'prautoblogger_max_word_count', 'prautoblogger_default_author', 'prautoblogger_default_category', 'prautoblogger_pullpush_cache_ttl', 'prautoblogger_reddit_posts_per_subreddit', 'prautoblogger_reasoning_max_tokens' );
 		if ( in_array( $option_name, $numeric, true ) ) {
 			return is_numeric( $value ) ? $value : 0;
 		}
-
+		if ( 'prautoblogger_image_model' === $option_name ) {
+			return $this->sanitize_image_model( (string) $value );
+		}
+		if ( 'prautoblogger_image_style_template' === $option_name ) {
+			// Multi-line template: validation + textarea-safe sanitisation
+			// (incl. the single-token check, brief A5) lives in the filler.
+			return PRAutoBlogger_Image_Template_Filler::sanitize_for_save( (string) $value );
+		}
 		return sanitize_text_field( (string) $value );
 	}
+
+	/** Validate model id against the registry and persist the derived provider. */
+	private function sanitize_image_model( string $value ): string {
+		$candidate = sanitize_text_field( $value );
+		$provider  = PRAutoBlogger_Image_Model_Registry::provider_for( $candidate );
+		if ( '' !== $provider ) {
+			update_option( 'prautoblogger_image_provider', $provider );
+			return $candidate;
+		}
+		add_settings_error( 'prautoblogger_image_model', 'prautoblogger_image_model_unknown', sprintf( esc_html__( 'Image model "%s" is not in the registry. Keeping the previous selection.', 'prautoblogger' ), esc_html( $candidate ) ) );
+		return (string) get_option( 'prautoblogger_image_model', PRAUTOBLOGGER_DEFAULT_IMAGE_MODEL );
+	}
 }

includes/admin/class-dashboard-widget.php

@@ -2,13 +2,15 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * WordPress Dashboard widget showing PRAutoBlogger generation status at a glance.
  *
  * Displays: last generation time, articles generated today, monthly cost,
  * and budget utilization.
  *
  * Triggered by: Could be registered via wp_dashboard_setup hook.
- * Dependencies: PRAutoBlogger_Cost_Tracker.
+ * Dependencies: PRAutoBlogger_Cost_Reporter.
  *
  * @see class-prautoblogger.php — Can register this on wp_dashboard_setup.
  */
@@ -27,7 +29,7 @@ class PRAutoBlogger_Dashboard_Widget {
 		wp_add_dashboard_widget(
 			'prautoblogger_status',
 			__( 'PRAutoBlogger Status', 'prautoblogger' ),
-			[ $this, 'render_widget' ]
+			array( $this, 'render_widget' )
 		);
 	}
 
@@ -37,14 +39,15 @@ class PRAutoBlogger_Dashboard_Widget {
 	 * @return void
 	 */
 	public function render_widget(): void {
-		$cost_tracker = new PRAutoBlogger_Cost_Tracker();
-		$monthly_spend = $cost_tracker->get_monthly_spend();
+		$cost_reporter = new PRAutoBlogger_Cost_Reporter();
+		$monthly_spend = $cost_reporter->get_monthly_spend();
 		$budget        = (float) get_option( 'prautoblogger_monthly_budget_usd', 50.00 );
-		$utilization   = $cost_tracker->get_budget_utilization();
+		$utilization   = $cost_reporter->get_budget_utilization();
 
 		$next_run = wp_next_scheduled( 'prautoblogger_daily_generation' );
 
-		printf( '<p><strong>%s</strong> $%.2f / $%.2f (%.0f%%)</p>',
+		printf(
+			'<p><strong>%s</strong> $%.2f / $%.2f (%.0f%%)</p>',
 			esc_html__( 'Monthly Spend:', 'prautoblogger' ),
 			$monthly_spend,
 			$budget,
@@ -52,7 +55,8 @@ class PRAutoBlogger_Dashboard_Widget {
 		);
 
 		if ( false !== $next_run ) {
-			printf( '<p><strong>%s</strong> %s</p>',
+			printf(
+				'<p><strong>%s</strong> %s</p>',
 				esc_html__( 'Next Generation:', 'prautoblogger' ),
 				esc_html( wp_date( 'M j, Y g:i A', $next_run ) )
 			);

includes/admin/class-ideas-browser.php

@@ -0,0 +1,337 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Admin page listing analysis results (article ideas) with per-idea generation.
+ *
+ * Triggered by: PRAutoBlogger::register_admin_hooks() on `admin_menu`.
+ * Dependencies: WordPress $wpdb, Article_Worker, Cost_Tracker, Generation_Lock.
+ *
+ * @see core/class-article-worker.php         — Generates articles from ideas.
+ * @see templates/admin/ideas-browser.php     — Renders the HTML.
+ */
+class PRAutoBlogger_Ideas_Browser {
+
+	private const PER_PAGE = 30;
+
+	/** Transient prefix for per-idea generation status. */
+	private const STATUS_PREFIX = 'prab_idea_gen_';
+
+	/** How long to keep per-idea status (seconds). */
+	private const STATUS_TTL = 600;
+
+	/** Register the Ideas submenu page under PRAutoBlogger. */
+	public function on_register_menu(): void {
+		add_submenu_page(
+			'prautoblogger-settings',
+			__( 'Ideas', 'prautoblogger' ),
+			__( 'Ideas', 'prautoblogger' ),
+			'manage_options',
+			'prautoblogger-ideas',
+			array( $this, 'render_page' )
+		);
+	}
+
+	/** Render the ideas browser page. */
+	public function render_page(): void {
+		if ( ! current_user_can( 'manage_options' ) ) {
+			return;
+		}
+
+		$paged       = isset( $_GET['paged'] ) ? absint( $_GET['paged'] ) : 1;
+		$type_filter = isset( $_GET['type'] ) ? sanitize_key( $_GET['type'] ) : '';
+
+		$result      = $this->query_ideas( $paged, $type_filter );
+		$rows        = $result['rows'];
+		$total       = $result['total'];
+		$total_pages = (int) ceil( $total / self::PER_PAGE );
+		$type_counts = $this->get_type_counts();
+
+		include PRAUTOBLOGGER_PLUGIN_DIR . 'templates/admin/ideas-browser.php';
+	}
+
+	/**
+	 * AJAX: trigger article generation from a specific idea.
+	 *
+	 * Loads the analysis result, stores it as a transient, sets a per-idea
+	 * status transient, and schedules a one-shot cron event so the actual
+	 * generation runs in a separate PHP process (Hostinger 120s limit).
+	 *
+	 * Side effects: transient writes, cron scheduling.
+	 */
+	public function on_ajax_generate_from_idea(): void {
+		check_ajax_referer( 'prautoblogger_idea_gen', 'nonce' );
+		if ( ! current_user_can( 'manage_options' ) ) {
+			wp_send_json_error( array( 'message' => 'Insufficient permissions.' ), 403 );
+			return;
+		}
+
+		$idea_id = absint( $_POST['idea_id'] ?? 0 );
+		if ( $idea_id < 1 ) {
+			wp_send_json_error( array( 'message' => 'Invalid idea ID.' ) );
+			return;
+		}
+
+		// Build Article_Idea from the analysis row.
+		$idea_data = self::load_idea_data( $idea_id );
+		if ( null === $idea_data ) {
+			wp_send_json_error( array( 'message' => 'Idea not found.' ) );
+			return;
+		}
+
+		// Store idea for the cron handler and set initial "running" status.
+		set_transient( self::STATUS_PREFIX . 'data_' . $idea_id, $idea_data, self::STATUS_TTL );
+		set_transient(
+			self::STATUS_PREFIX . $idea_id,
+			array(
+				'status'  => 'running',
+				'stage'   => __( 'Starting generation…', 'prautoblogger' ),
+				'started' => time(),
+			),
+			self::STATUS_TTL
+		);
+
+		// Schedule background cron — passes idea_id as argument.
+		$hook = 'prautoblogger_generate_from_idea';
+		if ( ! wp_next_scheduled( $hook, array( $idea_id ) ) ) {
+			wp_schedule_single_event( time(), $hook, array( $idea_id ) );
+		}
+		spawn_cron();
+		wp_remote_post(
+			site_url( 'wp-cron.php?doing_wp_cron=' . sprintf( '%.22F', microtime( true ) ) ),
+			array(
+				'timeout'   => 0.01,
+				'blocking'  => false,
+				'sslverify' => false,
+			)
+		);
+
+		wp_send_json_success( array( 'message' => 'Generation started.' ) );
+	}
+
+	/**
+	 * AJAX: return per-idea generation status for frontend polling.
+	 *
+	 * Side effects: none (reads transient only).
+	 */
+	public function on_ajax_idea_gen_status(): void {
+		check_ajax_referer( 'prautoblogger_idea_gen', 'nonce' );
+		if ( ! current_user_can( 'manage_options' ) ) {
+			wp_send_json_error( array( 'message' => 'Insufficient permissions.' ), 403 );
+			return;
+		}
+
+		$idea_id = absint( $_POST['idea_id'] ?? 0 );
+		$status  = get_transient( self::STATUS_PREFIX . $idea_id );
+		if ( ! is_array( $status ) ) {
+			wp_send_json_success( array( 'status' => 'idle' ) );
+			return;
+		}
+
+		wp_send_json_success( $status );
+	}
+
+	/**
+	 * Cron handler: generate a single article from a stored idea.
+	 *
+	 * Runs in a background PHP process. Acquires the generation lock,
+	 * runs Article_Worker, and writes the result to the per-idea status transient.
+	 *
+	 * Side effects: LLM API calls, DB writes, post creation, cost logging.
+	 *
+	 * @param int $idea_id Analysis result row ID.
+	 */
+	public static function on_cron_generate_from_idea( int $idea_id ): void {
+		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
+		@ignore_user_abort( true );
+		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
+		@set_time_limit( 300 );
+
+		$key       = self::STATUS_PREFIX . $idea_id;
+		$idea_data = get_transient( self::STATUS_PREFIX . 'data_' . $idea_id );
+		if ( ! is_array( $idea_data ) ) {
+			set_transient(
+				$key,
+				array(
+					'status'  => 'error',
+					'message' => 'Idea data expired.',
+				),
+				self::STATUS_TTL
+			);
+			return;
+		}
+
+		if ( ! PRAutoBlogger_Generation_Lock::acquire() ) {
+			set_transient(
+				$key,
+				array(
+					'status'  => 'error',
+					'message' => 'Another generation is running.',
+				),
+				self::STATUS_TTL
+			);
+			return;
+		}
+
+		try {
+			$idea         = new PRAutoBlogger_Article_Idea( $idea_data );
+			$cost_tracker = new PRAutoBlogger_Cost_Tracker();
+			$cost_tracker->set_run_id( wp_generate_uuid4() );
+
+			self::update_idea_stage( $idea_id, __( 'Generating article draft…', 'prautoblogger' ) );
+			$worker = new PRAutoBlogger_Article_Worker( $cost_tracker );
+			$result = $worker->generate( $idea );
+
+			// Amortize any research costs for this single-article run.
+			PRAutoBlogger_Post_Assembler::amortize_research_costs( $cost_tracker->get_run_id() );
+
+			// Find the generated post ID for the "View" link.
+			$post_id = self::find_post_by_run_id( $cost_tracker->get_run_id() );
+
+			set_transient(
+				$key,
+				array(
+					'status'    => 'complete',
+					'generated' => $result['generated'],
+					'published' => $result['published'],
+					'cost'      => $result['cost'],
+					'post_id'   => $post_id,
+				),
+				self::STATUS_TTL
+			);
+		} catch ( \Throwable $e ) {
+			PRAutoBlogger_Logger::instance()->error(
+				sprintf( 'Idea generation %s for #%d: %s', get_class( $e ), $idea_id, $e->getMessage() ),
+				'pipeline'
+			);
+			set_transient(
+				$key,
+				array(
+					'status'  => 'error',
+					'message' => $e->getMessage(),
+				),
+				self::STATUS_TTL
+			);
+		}
+
+		PRAutoBlogger_Generation_Lock::release();
+		delete_transient( self::STATUS_PREFIX . 'data_' . $idea_id );
+	}
+
+	// ── Private helpers ─────────────────────────────────────────────────
+
+	/** Update the per-idea status transient with a stage message. */
+	private static function update_idea_stage( int $idea_id, string $stage ): void {
+		$key     = self::STATUS_PREFIX . $idea_id;
+		$current = get_transient( $key );
+		if ( is_array( $current ) ) {
+			$current['stage'] = $stage;
+			set_transient( $key, $current, self::STATUS_TTL );
+		}
+	}
+
+	/** Find the most recent post created by a specific run_id. */
+	private static function find_post_by_run_id( string $run_id ): ?int {
+		global $wpdb;
+		$table = $wpdb->prefix . 'prautoblogger_generation_log';
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$post_id = $wpdb->get_var(
+			$wpdb->prepare(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+				"SELECT DISTINCT post_id FROM {$table} WHERE run_id = %s AND post_id IS NOT NULL LIMIT 1",
+				$run_id
+			)
+		);
+		return null !== $post_id ? (int) $post_id : null;
+	}
+
+	/**
+	 * Load an analysis result row and map it to Article_Idea constructor data.
+	 *
+	 * @param int $idea_id Analysis result row ID.
+	 * @return array<string, mixed>|null Article_Idea-compatible array, or null.
+	 */
+	private static function load_idea_data( int $idea_id ): ?array {
+		global $wpdb;
+		$table = $wpdb->prefix . 'prautoblogger_analysis_results';
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$row = $wpdb->get_row(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+			$wpdb->prepare( "SELECT * FROM {$table} WHERE id = %d", $idea_id ),
+			ARRAY_A
+		);
+		if ( ! $row ) {
+			return null;
+		}
+
+		$meta = json_decode( $row['metadata_json'] ?? '{}', true ) ?? array();
+		return array(
+			'topic'           => $row['topic'],
+			'article_type'    => $row['analysis_type'],
+			'suggested_title' => $meta['suggested_title'] ?? $row['topic'],
+			'summary'         => $row['summary'] ?? '',
+			'score'           => (float) $row['relevance_score'],
+			'analysis_id'     => (int) $row['id'],
+			'source_ids'      => json_decode( $row['source_ids_json'] ?? '[]', true ) ?? array(),
+			'key_points'      => $meta['key_points'] ?? array(),
+			'target_keywords' => $meta['target_keywords'] ?? array(),
+		);
+	}
+
+	/** Query analysis results with optional filtering and pagination. */
+	private function query_ideas( int $paged, string $type ): array {
+		global $wpdb;
+		$table  = $wpdb->prefix . 'prautoblogger_analysis_results';
+		$where  = array();
+		$params = array();
+
+		if ( '' !== $type ) {
+			$where[]  = 'analysis_type = %s';
+			$params[] = $type;
+		}
+
+		$where_sql = empty( $where ) ? '' : 'WHERE ' . implode( ' AND ', $where );
+		$offset    = ( $paged - 1 ) * self::PER_PAGE;
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$total = (int) $wpdb->get_var(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+			empty( $params )  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.DB.PreparedSQL.NotPrepared
+			? "SELECT COUNT(*) FROM {$table} {$where_sql}"  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.DB.PreparedSQL.NotPrepared
+			: $wpdb->prepare( "SELECT COUNT(*) FROM {$table} {$where_sql}", ...$params )  // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared
+		);
+
+		$order_sql = 'ORDER BY analyzed_at DESC, relevance_score DESC';
+		$limit_sql = sprintf( 'LIMIT %d OFFSET %d', self::PER_PAGE, $offset );
+		$full_sql  = "SELECT * FROM {$table} {$where_sql} {$order_sql} {$limit_sql}";
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$rows = empty( $params )  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.DB.PreparedSQL.NotPrepared
+		? $wpdb->get_results( $full_sql, ARRAY_A )  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.DB.PreparedSQL.NotPrepared
+		: $wpdb->get_results( $wpdb->prepare( $full_sql, ...$params ), ARRAY_A );  // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared
+
+		return array(
+			'rows'  => $rows ?? array(),
+			'total' => $total,
+		);
+	}
+
+	/** Get counts per analysis_type for the filter badges. */
+	private function get_type_counts(): array {
+		global $wpdb;
+		$table = $wpdb->prefix . 'prautoblogger_analysis_results';
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$rows = $wpdb->get_results(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+			"SELECT analysis_type, COUNT(*) AS cnt FROM {$table} GROUP BY analysis_type ORDER BY cnt DESC",
+			ARRAY_A
+		);
+
+		$counts = array();
+		foreach ( $rows ?? array() as $row ) {
+			$counts[ $row['analysis_type'] ] = (int) $row['cnt'];
+		}
+		return $counts;
+	}
+}

includes/admin/class-image-model-registry.php

@@ -0,0 +1,264 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Static registry of available image generation models.
+ *
+ * What: Returns a merged list of Runware models (from live catalog sync) and
+ *       OpenRouter models (static list). No API discovery for OpenRouter — updated
+ *       manually when new models are available.
+ *       As of 2026-04-26, registry includes 15 Runware models (live) + 6 OpenRouter
+ *       models (static), ordered cheapest-to-most-expensive within each provider.
+ * Who calls it: PRAutoBlogger_Admin_Page (model picker UI + save-time provider
+ *               derivation) and PRAutoBlogger_Image_Pipeline (provider lookup).
+ * Dependencies: PRAutoBlogger_Runware_Model_Catalog (live Runware models),
+ *               hardcoded fallback lists for resilience.
+ *
+ * @see admin/class-settings-fields-extended.php — Image settings reference this registry.
+ * @see core/class-image-pipeline.php            — Derives provider from picked model.
+ * @see providers/class-runware-image-provider.php — Runware FLUX backend.
+ * @see providers/class-runware-model-catalog.php — Live model sync and caching.
+ */
+class PRAutoBlogger_Image_Model_Registry {
+
+	/**
+	 * Get all available image generation models (Runware live + OpenRouter static).
+	 *
+	 * Each entry contains:
+	 * - id:             Model identifier used in API calls.
+	 * - name:           Human-readable display name.
+	 * - provider:       'runware' | 'openrouter'.
+	 * - cost_per_image: Estimated USD cost per generation.
+	 * - capabilities:   Array of capability tags.
+	 * - description:    Short description for the admin UI.
+	 *
+	 * Ordered cheapest-to-most-expensive within each provider, with the
+	 * recommended default (Runware schnell) at the top.
+	 *
+	 * @return array<int, array<string, mixed>>
+	 */
+	public static function get_models(): array {
+		$catalog = new PRAutoBlogger_Runware_Model_Catalog();
+		$runware_models = $catalog->get_models();
+		$openrouter_models = self::get_openrouter_models();
+		return array_merge( $runware_models, $openrouter_models );
+	}
+
+	/**
+	 * Return the provider id for a known model, or empty string if the
+	 * model id is not in the registry.
+	 *
+	 * @param string $model_id Model slug from the admin UI.
+	 * @return string Provider id ('runware' | 'openrouter' | '').
+	 */
+	public static function provider_for( string $model_id ): string {
+		foreach ( self::get_models() as $model ) {
+			if ( ( $model['id'] ?? '' ) === $model_id ) {
+				return (string) ( $model['provider'] ?? '' );
+			}
+		}
+		return '';
+	}
+
+	/**
+	 * Hardcoded Runware model list used as fallback when the live catalog
+	 * sync fails or API is unreachable. Kept in sync with actual Runware
+	 * pricing page (runware.ai/pricing). This is the source of truth for
+	 * pricing data when the Runware API doesn't expose cost information.
+	 *
+	 * Last verified: 2026-04-26. To update: check runware.ai/pricing for new
+	 * text-to-image models and their costs.
+	 *
+	 * @return array<int, array<string, mixed>>
+	 */
+	public static function get_runware_fallback_models(): array {
+		return array(
+			array(
+				'id'             => 'runware:100@1',
+				'name'           => 'FLUX.1 schnell (Runware)',
+				'provider'       => 'runware',
+				'cost_per_image' => 0.0006,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'Default. Fast, very cheap, comic-friendly fidelity.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'runware:twinflow-z-image-turbo@0',
+				'name'           => 'TwinFlow Z-Image-Turbo (Runware)',
+				'provider'       => 'runware',
+				'cost_per_image' => 0.0006,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'Fast text-to-image, same cost as schnell.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'runware:400@2',
+				'name'           => 'FLUX.2 klein 9B (Runware)',
+				'provider'       => 'runware',
+				'cost_per_image' => 0.00078,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'FLUX.2 compact 9B. Stronger than schnell at similar cost.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'runware:400@4',
+				'name'           => 'FLUX.2 klein 4B (Runware)',
+				'provider'       => 'runware',
+				'cost_per_image' => 0.0006,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'FLUX.2 compact 4B. Newer architecture at schnell price.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'runware:5@1',
+				'name'           => 'Stable Diffusion 3 (Runware)',
+				'provider'       => 'runware',
+				'cost_per_image' => 0.0013,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'Stable Diffusion 3. Sharp text, complex scenes.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'runware:z-image@turbo',
+				'name'           => 'Z-Image Turbo (Runware)',
+				'provider'       => 'runware',
+				'cost_per_image' => 0.0013,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'Fast photorealistic generation.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'runware:101@1',
+				'name'           => 'FLUX.1 dev (Runware)',
+				'provider'       => 'runware',
+				'cost_per_image' => 0.02,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'Higher fidelity FLUX.1. ~30x schnell cost.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'runware:97@3',
+				'name'           => 'HiDream-I1 Fast (Runware)',
+				'provider'       => 'runware',
+				'cost_per_image' => 0.0038,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'HiDream-I1 Fast. Low latency, 17B quality.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'runware:97@2',
+				'name'           => 'HiDream-I1 Dev (Runware)',
+				'provider'       => 'runware',
+				'cost_per_image' => 0.0045,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'HiDream-I1 Dev. Strong prompt alignment.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'runware:z-image@0',
+				'name'           => 'Z-Image (Runware)',
+				'provider'       => 'runware',
+				'cost_per_image' => 0.0045,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'High-quality Z-Image foundation model.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'runware:400@1',
+				'name'           => 'FLUX.2 dev (Runware)',
+				'provider'       => 'runware',
+				'cost_per_image' => 0.0051,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'FLUX.2 dev. Controllable open text-to-image. From $0.0051.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'runware:108@1',
+				'name'           => 'Qwen-Image (Runware)',
+				'provider'       => 'runware',
+				'cost_per_image' => 0.0058,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'Alibaba Qwen-Image. Strong text rendering in generated images.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'runware:97@1',
+				'name'           => 'HiDream-I1 Full (Runware)',
+				'provider'       => 'runware',
+				'cost_per_image' => 0.009,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'HiDream-I1 Full. 17B high-fidelity, LoRA support.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'runware:107@1',
+				'name'           => 'FLUX.1 Krea dev (Runware)',
+				'provider'       => 'runware',
+				'cost_per_image' => 0.0098,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'FLUX.1 Krea Dev. Photorealistic open-weight generation.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'runware:glm-image@0',
+				'name'           => 'GLM-Image (Runware)',
+				'provider'       => 'runware',
+				'cost_per_image' => 0.0225,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'GLM-Image. Hybrid autoregressive+diffusion, excellent text rendering.', 'prautoblogger' ),
+			),
+		);
+	}
+
+	/**
+	 * Hardcoded OpenRouter image model list. Left static for now because
+	 * OpenRouter's catalog is large (hundreds of models) with noisy filtering.
+	 * Future iteration will add smart filtering strategy (output_modalities,
+	 * pricing, rate limits).
+	 *
+	 * Last verified: 2026-04-26. To update: check openrouter.ai/api/v1/models
+	 * filtering to output_modalities containing 'image'.
+	 *
+	 * @return array<int, array<string, mixed>>
+	 */
+	private static function get_openrouter_models(): array {
+		return array(
+			array(
+				'id'             => 'google/gemini-2.5-flash-image',
+				'name'           => 'Gemini 2.5 Flash Image (OpenRouter)',
+				'provider'       => 'openrouter',
+				'cost_per_image' => 0.005,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'Mid-tier quality, proven.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'google/gemini-3.1-flash-image-preview',
+				'name'           => 'Gemini 3.1 Flash Image (OpenRouter)',
+				'provider'       => 'openrouter',
+				'cost_per_image' => 0.008,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'Latest Google Flash image. Better quality.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'openai/gpt-5-image-mini',
+				'name'           => 'GPT-5 Image Mini (OpenRouter)',
+				'provider'       => 'openrouter',
+				'cost_per_image' => 0.02,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'OpenAI budget image model.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'openai/gpt-5.4-image-2',
+				'name'           => 'GPT-5.4 Image 2 (OpenRouter)',
+				'provider'       => 'openrouter',
+				'cost_per_image' => 0.02,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'OpenAI GPT-5.4 image generation.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'google/gemini-3-pro-image-preview',
+				'name'           => 'Gemini 3 Pro Image (OpenRouter)',
+				'provider'       => 'openrouter',
+				'cost_per_image' => 0.03,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'Highest quality Google image. Premium.', 'prautoblogger' ),
+			),
+			array(
+				'id'             => 'openai/gpt-5-image',
+				'name'           => 'GPT-5 Image (OpenRouter)',
+				'provider'       => 'openrouter',
+				'cost_per_image' => 0.08,
+				'capabilities'   => array( 'image_generation' ),
+				'description'    => __( 'OpenAI premium. Photorealistic.', 'prautoblogger' ),
+			),
+		);
+	}
+}

includes/admin/class-log-viewer.php

@@ -2,6 +2,8 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Admin page displaying structured application log entries.
  *
  * Provides level filtering (error/warning/info/debug), text search,
@@ -29,7 +31,7 @@ class PRAutoBlogger_Log_Viewer {
 			__( 'Activity Log', 'prautoblogger' ),
 			'manage_options',
 			'prautoblogger-logs',
-			[ $this, 'render_page' ]
+			array( $this, 'render_page' )
 		);
 	}
 
@@ -66,19 +68,21 @@ class PRAutoBlogger_Log_Viewer {
 		check_ajax_referer( 'prautoblogger_clear_logs', 'nonce' );
 
 		if ( ! current_user_can( 'manage_options' ) ) {
-			wp_send_json_error( [ 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ], 403 );
+			wp_send_json_error( array( 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ), 403 );
 			return;
 		}
 
 		$days    = isset( $_POST['days'] ) ? absint( $_POST['days'] ) : 30;
 		$deleted = PRAutoBlogger_Logger::prune( $days );
 
-		wp_send_json_success( [
-			'message' => sprintf(
+		wp_send_json_success(
+			array(
+				'message' => sprintf(
 				/* translators: %d: number of entries deleted */
-				__( '%d log entries cleared.', 'prautoblogger' ),
-				$deleted
-			),
-		] );
+					__( '%d log entries cleared.', 'prautoblogger' ),
+					$deleted
+				),
+			)
+		);
 	}
 }

includes/admin/class-metrics-page.php

@@ -2,6 +2,8 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Admin page displaying cost dashboard, content scores, and generation history.
  *
  * Shows: monthly spend, daily cost chart, spend by pipeline stage, budget
@@ -27,7 +29,7 @@ class PRAutoBlogger_Metrics_Page {
 			__( 'Metrics & Costs', 'prautoblogger' ),
 			'manage_options',
 			'prautoblogger-metrics',
-			[ $this, 'render_page' ]
+			array( $this, 'render_page' )
 		);
 	}
 

includes/admin/class-opik-settings.php

@@ -0,0 +1,204 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Opik settings UI and registration.
+ *
+ * Registers settings fields in the PRAutoBlogger Settings page under
+ * a new "Observability" section. Fields include:
+ * - Enable Opik tracing (checkbox, default off)
+ * - Opik project name (text, default 'prautoblogger')
+ * - Capture full prompts (checkbox, default off)
+ * - Status display (read-only: API key configured, last dispatch, queue depth)
+ *
+ * Never renders the API key value in admin HTML.
+ *
+ * @see includes/admin/class-admin-page.php — Main settings page loader.
+ */
+class PRAutoBlogger_Opik_Settings {
+
+	/**
+	 * Constructor.
+	 *
+	 * Register hooks in __construct so they fire when the plugin loads.
+	 */
+	public function __construct() {
+		add_action( 'admin_init', array( $this, 'register_settings' ) );
+	}
+
+	/**
+	 * Register Opik settings section and fields.
+	 *
+	 * Hooked to 'admin_init'.
+	 */
+	public function register_settings(): void {
+		// Register the section.
+		add_settings_section(
+			'prautoblogger_observability',
+			__( 'Observability (Opik)', 'prautoblogger' ),
+			array( $this, 'render_section_help' ),
+			'prautoblogger_settings'
+		);
+
+		// Register fields.
+		add_settings_field(
+			'prautoblogger_opik_enabled',
+			__( 'Enable Opik tracing', 'prautoblogger' ),
+			array( $this, 'render_field_enabled' ),
+			'prautoblogger_settings',
+			'prautoblogger_observability'
+		);
+
+		register_setting(
+			'prautoblogger_settings',
+			'prautoblogger_opik_enabled',
+			array( 'type' => 'boolean' )
+		);
+
+		add_settings_field(
+			'prautoblogger_opik_project_name',
+			__( 'Opik project name', 'prautoblogger' ),
+			array( $this, 'render_field_project_name' ),
+			'prautoblogger_settings',
+			'prautoblogger_observability'
+		);
+
+		register_setting(
+			'prautoblogger_settings',
+			'prautoblogger_opik_project_name',
+			array(
+				'type'              => 'string',
+				'sanitize_callback' => 'sanitize_text_field',
+			)
+		);
+
+		add_settings_field(
+			'prautoblogger_opik_capture_full_prompt',
+			__( 'Capture full prompt text', 'prautoblogger' ),
+			array( $this, 'render_field_capture_full' ),
+			'prautoblogger_settings',
+			'prautoblogger_observability'
+		);
+
+		register_setting(
+			'prautoblogger_settings',
+			'prautoblogger_opik_capture_full_prompt',
+			array( 'type' => 'boolean' )
+		);
+
+		add_settings_field(
+			'prautoblogger_opik_status',
+			__( 'Status', 'prautoblogger' ),
+			array( $this, 'render_field_status' ),
+			'prautoblogger_settings',
+			'prautoblogger_observability'
+		);
+	}
+
+	/**
+	 * Render section help text.
+	 */
+	public function render_section_help(): void {
+		echo wp_kses_post(
+			'<p>Optional LLM observability via <a href="https://www.comet.com/" target="_blank" rel="noopener">Comet Opik</a>. ' .
+			'Captures detailed traces of article generation with per-LLM-call metrics. ' .
+			'Requires API credentials in <code>wp-config.php</code>.</p>'
+		);
+	}
+
+	/**
+	 * Render the "Enable Opik" checkbox.
+	 */
+	public function render_field_enabled(): void {
+		$enabled = get_option( 'prautoblogger_opik_enabled', false );
+		$checked = $enabled ? 'checked' : '';
+		?>
+		<input type="checkbox" name="prautoblogger_opik_enabled" value="1" <?php echo esc_attr( $checked ); ?> />
+		<label for="prautoblogger_opik_enabled">
+			<?php esc_html_e( 'Send article generation traces to Opik', 'prautoblogger' ); ?>
+		</label>
+		<?php
+		if ( ! $this->has_credentials() ) {
+			echo '<p style="color: #d63638;"><strong>' .
+				esc_html__( 'Note: API credentials must be set in wp-config.php (PRAUTOBLOGGER_OPIK_API_KEY, PRAUTOBLOGGER_OPIK_WORKSPACE)', 'prautoblogger' ) .
+				'</strong></p>';
+		}
+	}
+
+	/**
+	 * Render the project name field.
+	 */
+	public function render_field_project_name(): void {
+		$value = get_option( 'prautoblogger_opik_project_name', 'prautoblogger' );
+		?>
+		<input type="text" name="prautoblogger_opik_project_name" value="<?php echo esc_attr( $value ); ?>" style="width: 300px;" />
+		<p class="description">
+			<?php esc_html_e( 'Opik auto-creates this project on first trace (lowercase, no spaces)', 'prautoblogger' ); ?>
+		</p>
+		<?php
+	}
+
+	/**
+	 * Render the "Capture full prompt" checkbox.
+	 */
+	public function render_field_capture_full(): void {
+		$enabled = get_option( 'prautoblogger_opik_capture_full_prompt', false );
+		$checked = $enabled ? 'checked' : '';
+		?>
+		<input type="checkbox" name="prautoblogger_opik_capture_full_prompt" value="1" <?php echo esc_attr( $checked ); ?> />
+		<label>
+			<?php esc_html_e( 'Include full prompt text in spans (increases payload size)', 'prautoblogger' ); ?>
+		</label>
+		<p class="description">
+			<?php esc_html_e( 'By default, only prompt hash is logged. Enable this for debugging.' ); ?>
+		</p>
+		<?php
+	}
+
+	/**
+	 * Render the status display (read-only).
+	 */
+	public function render_field_status(): void {
+		$has_api_key = $this->has_credentials();
+		$queue       = new PRAutoBlogger_Opik_Span_Queue();
+		$queue_depth = $queue->get_queue_depth();
+		$last_dispatch = get_option( 'prautoblogger_opik_last_dispatch', 0 );
+		$last_dispatch_str = $last_dispatch
+			? sprintf(
+				/* translators: %s = human-readable time */
+				__( '%s ago', 'prautoblogger' ),
+				human_time_diff( (int) $last_dispatch )
+			)
+			: __( 'Never', 'prautoblogger' );
+
+		?>
+		<div style="background: #f1f1f1; padding: 10px; border-radius: 3px; max-width: 600px;">
+			<p>
+				<strong><?php esc_html_e( 'API key configured:', 'prautoblogger' ); ?></strong>
+				<?php echo $has_api_key ? '<span style="color: green;">✓ Yes</span>' : '<span style="color: red;">✗ No</span>'; ?>
+			</p>
+			<p>
+				<strong><?php esc_html_e( 'Last dispatch:', 'prautoblogger' ); ?></strong>
+				<?php echo esc_html( $last_dispatch_str ); ?>
+			</p>
+			<p>
+				<strong><?php esc_html_e( 'Queue depth:', 'prautoblogger' ); ?></strong>
+				<?php echo esc_html( (string) $queue_depth ); ?>
+				<?php esc_html_e( 'item(s) pending', 'prautoblogger' ); ?>
+			</p>
+		</div>
+		<?php
+	}
+
+	/**
+	 * Check if Opik credentials are configured in wp-config.php.
+	 *
+	 * @return bool
+	 */
+	private function has_credentials(): bool {
+		return defined( 'PRAUTOBLOGGER_OPIK_API_KEY' ) &&
+			defined( 'PRAUTOBLOGGER_OPIK_WORKSPACE' ) &&
+			! empty( PRAUTOBLOGGER_OPIK_API_KEY ) &&
+			! empty( PRAUTOBLOGGER_OPIK_WORKSPACE );
+	}
+}

includes/admin/class-post-list-columns.php

@@ -0,0 +1,269 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Adds "Writing Model", "Image Model", and "Cost" columns to the Posts list.
+ *
+ * Shows which LLM wrote each article, which model generated its featured image,
+ * and the total API cost of generating the article. Non-generated posts show "—".
+ *
+ * Triggered by: PRAutoBlogger::register_admin_hooks().
+ * Dependencies: Post meta, attachment meta, prab_generation_log table.
+ *
+ * @see core/class-publisher.php              — Sets _prautoblogger_model_used.
+ * @see core/class-image-media-sideloader.php — Sets _prautoblogger_image_model on attachment.
+ * @see core/class-cost-tracker.php           — Writes generation_log with estimated_cost.
+ * @see class-prautoblogger.php               — Registers hooks for this class.
+ */
+class PRAutoBlogger_Post_List_Columns {
+
+	/**
+	 * Register column and render hooks.
+	 *
+	 * Side effects: adds WordPress filters/actions for post list customization.
+	 */
+	public function register(): void {
+		add_filter( 'manage_posts_columns', array( $this, 'filter_add_columns' ) );
+		add_action( 'manage_posts_custom_column', array( $this, 'on_render_column' ), 10, 2 );
+		add_filter( 'manage_edit-post_sortable_columns', array( $this, 'filter_sortable_columns' ) );
+		add_action( 'pre_get_posts', array( $this, 'on_sort_by_model' ) );
+		add_action( 'admin_head', array( $this, 'on_column_styles' ) );
+	}
+
+	/**
+	 * Insert three columns after the title column.
+	 *
+	 * @param array<string, string> $columns Existing columns.
+	 * @return array<string, string> Modified columns.
+	 */
+	public function filter_add_columns( array $columns ): array {
+		$new = array();
+		foreach ( $columns as $key => $label ) {
+			$new[ $key ] = $label;
+			if ( 'title' === $key ) {
+				$new['prab_writing_model'] = __( 'Writing Model', 'prautoblogger' );
+				$new['prab_image_model']   = __( 'Image Model', 'prautoblogger' );
+				$new['prab_cost']          = __( 'Cost', 'prautoblogger' );
+			}
+		}
+		return $new;
+	}
+
+	/**
+	 * Render cell content for our custom columns.
+	 *
+	 * @param string $column  Column identifier.
+	 * @param int    $post_id Current post ID.
+	 */
+	public function on_render_column( string $column, int $post_id ): void {
+		switch ( $column ) {
+			case 'prab_writing_model':
+				$this->render_model_cell(
+					(string) get_post_meta( $post_id, '_prautoblogger_model_used', true )
+				);
+				break;
+
+			case 'prab_image_model':
+				$this->render_image_model_cell( $post_id );
+				break;
+
+			case 'prab_cost':
+				$this->render_cost_cell( $post_id );
+				break;
+		}
+	}
+
+	/**
+	 * Make the writing model column sortable.
+	 *
+	 * @param array<string, string> $columns Sortable column map.
+	 * @return array<string, string>
+	 */
+	public function filter_sortable_columns( array $columns ): array {
+		$columns['prab_writing_model'] = 'prab_writing_model';
+		return $columns;
+	}
+
+	/**
+	 * Handle sorting by writing model meta value.
+	 *
+	 * @param \WP_Query $query The admin posts query.
+	 */
+	public function on_sort_by_model( \WP_Query $query ): void {
+		if ( ! is_admin() || ! $query->is_main_query() ) {
+			return;
+		}
+		if ( 'prab_writing_model' !== $query->get( 'orderby' ) ) {
+			return;
+		}
+		$query->set( 'meta_key', '_prautoblogger_model_used' );
+		$query->set( 'orderby', 'meta_value' );
+	}
+
+	/**
+	 * Output column width styles on the Posts list screen only.
+	 */
+	public function on_column_styles(): void {
+		$screen = get_current_screen();
+		if ( ! $screen || 'edit-post' !== $screen->id ) {
+			return;
+		}
+		echo '<style>'
+			. '.wp-list-table .column-title{width:22%}'
+			. '.column-author{width:6%}'
+			. '.column-categories{width:7%}'
+			. '.column-tags{width:9%;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}'
+			. '.column-date{width:8%}'
+			. '.column-prab_writing_model{width:85px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}'
+			. '.column-prab_image_model{width:85px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}'
+			. '.column-prab_cost{width:50px;white-space:nowrap;overflow:visible}'
+			. '.column-taxonomy-peptide_topic{width:75px}'
+			. '.prab-cost-wrap{position:relative;display:inline-block}'
+			. '.prab-cost-trigger{font-size:12px;color:#2271b1;text-decoration:underline;cursor:pointer}'
+			. '.prab-cost-popover{display:none;position:absolute;right:0;top:100%;z-index:9999;'
+			. 'background:#fff;border:1px solid #c3c4c7;border-radius:4px;box-shadow:0 2px 8px rgba(0,0,0,.15);'
+			. 'padding:8px;min-width:340px;white-space:normal}'
+			. '.prab-cost-wrap:hover .prab-cost-popover,'
+			. '.prab-cost-trigger:focus+.prab-cost-popover{display:block}'
+			. '.prab-cost-table{width:100%;border-collapse:collapse;font-size:12px}'
+			. '.prab-cost-table th{text-align:left;border-bottom:2px solid #dcdcde;padding:3px 6px;color:#50575e;font-weight:600}'
+			. '.prab-cost-table td{padding:3px 6px;border-bottom:1px solid #f0f0f1;color:#3c434a}'
+			. '.prab-cost-table tr:last-child td{border-bottom:none}'
+			. '.prab-cost-total td{border-top:2px solid #dcdcde;border-bottom:none}'
+			. '</style>';
+	}
+
+	// ── Private helpers ─────────────────────────────────────────────────
+
+	/**
+	 * Render a model name cell with shortened display and full tooltip.
+	 *
+	 * @param string $model Full model identifier (may be empty).
+	 */
+	private function render_model_cell( string $model ): void {
+		if ( '' === $model ) {
+			echo '—';
+			return;
+		}
+		printf(
+			'<span title="%s" style="font-size:12px;color:#666;">%s</span>',
+			esc_attr( $model ),
+			esc_html( $this->shorten( $model ) )
+		);
+	}
+
+	/**
+	 * Look up the featured image's model and render it.
+	 *
+	 * @param int $post_id The post ID.
+	 */
+	private function render_image_model_cell( int $post_id ): void {
+		$thumbnail_id = (int) get_post_thumbnail_id( $post_id );
+		if ( 0 === $thumbnail_id ) {
+			echo '—';
+			return;
+		}
+		$model = (string) get_post_meta( $thumbnail_id, '_prautoblogger_image_model', true );
+		$this->render_model_cell( $model );
+	}
+
+	/**
+	 * Fetch generation_log rows for a post, render total with clickable breakdown.
+	 *
+	 * @param int $post_id The post ID.
+	 */
+	private function render_cost_cell( int $post_id ): void {
+		$is_generated = get_post_meta( $post_id, '_prautoblogger_generated', true );
+		if ( '1' !== $is_generated ) {
+			echo '—';
+			return;
+		}
+
+		global $wpdb;
+		$table = $wpdb->prefix . 'prautoblogger_generation_log';
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching
+		$rows = $wpdb->get_results(
+			$wpdb->prepare(
+				// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+				"SELECT stage, model, prompt_tokens, completion_tokens, estimated_cost
+					FROM {$table} WHERE post_id = %d ORDER BY id ASC",
+				$post_id
+			),
+			ARRAY_A
+		);
+
+		if ( empty( $rows ) ) {
+			echo '<span style="font-size:12px;color:#999;">$0.00</span>';
+			return;
+		}
+
+		$total     = array_sum( array_column( $rows, 'estimated_cost' ) );
+		$formatted = $total < 0.01
+			? sprintf( '$%.4f', $total )
+			: sprintf( '$%.2f', $total );
+
+		$breakdown = $this->build_breakdown_html( $rows, $total );
+
+		printf(
+			'<span class="prab-cost-wrap">'
+			. '<a href="#" class="prab-cost-trigger" onclick="return false;">%s</a>'
+			. '<span class="prab-cost-popover">%s</span>'
+			. '</span>',
+			esc_html( $formatted ),
+			$breakdown
+		);
+	}
+
+	/**
+	 * Build the HTML breakdown table for the cost popover.
+	 *
+	 * @param array[] $rows  Generation log rows.
+	 * @param float   $total Total cost.
+	 * @return string HTML table (already escaped).
+	 */
+	private function build_breakdown_html( array $rows, float $total ): string {
+		$html  = '<table class="prab-cost-table">';
+		$html .= '<tr><th>Stage</th><th>Model</th><th>Tokens</th><th>Cost</th></tr>';
+
+		foreach ( $rows as $row ) {
+			$stage  = esc_html( ucfirst( str_replace( '_', ' ', $row['stage'] ) ) );
+			$model  = esc_html( $this->shorten( $row['model'] ) );
+			$tokens = (int) $row['prompt_tokens'] + (int) $row['completion_tokens'];
+			$cost   = (float) $row['estimated_cost'];
+			$cost_f = $cost < 0.01 ? sprintf( '$%.4f', $cost ) : sprintf( '$%.2f', $cost );
+
+			$html .= sprintf(
+				'<tr><td>%s</td><td title="%s">%s</td><td>%s</td><td>%s</td></tr>',
+				$stage,
+				esc_attr( $row['model'] ),
+				$model,
+				esc_html( number_format( $tokens ) ),
+				esc_html( $cost_f )
+			);
+		}
+
+		$total_f = $total < 0.01 ? sprintf( '$%.4f', $total ) : sprintf( '$%.2f', $total );
+		$html   .= sprintf(
+			'<tr class="prab-cost-total"><td colspan="3"><strong>Total</strong></td>'
+			. '<td><strong>%s</strong></td></tr>',
+			esc_html( $total_f )
+		);
+		$html   .= '</table>';
+
+		return $html;
+	}
+
+	/**
+	 * Strip provider prefix for compact display.
+	 *
+	 * @param string $model Full model identifier.
+	 * @return string Shortened name.
+	 */
+	private function shorten( string $model ): string {
+		$pos = strpos( $model, '/' );
+		return false !== $pos ? substr( $model, $pos + 1 ) : $model;
+	}
+}

includes/admin/class-post-metabox.php

@@ -2,6 +2,8 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Adds a metabox to posts showing PRAutoBlogger generation metadata.
  *
  * Only appears on posts that were generated by PRAutoBlogger (checked via
@@ -34,7 +36,7 @@ class PRAutoBlogger_Post_Metabox {
 		add_meta_box(
 			'prautoblogger_generation_info',
 			__( 'PRAutoBlogger Generation Info', 'prautoblogger' ),
-			[ $this, 'render_metabox' ],
+			array( $this, 'render_metabox' ),
 			'post',
 			'side',
 			'default'

includes/admin/class-review-queue.php

@@ -2,6 +2,8 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Admin page listing generated draft posts for editorial review.
  *
  * Provides approve (publish), edit (opens WP editor), and reject (trash)
@@ -28,11 +30,11 @@ class PRAutoBlogger_Review_Queue {
 			__( 'Review Queue', 'prautoblogger' ),
 			'manage_options',
 			'prautoblogger-review-queue',
-			[ $this, 'render_page' ]
+			array( $this, 'render_page' )
 		);
 
 		if ( false !== $hook ) {
-			add_action( "load-{$hook}", [ $this, 'on_handle_bulk_actions' ] );
+			add_action( "load-{$hook}", array( $this, 'on_handle_bulk_actions' ) );
 		}
 	}
 
@@ -49,9 +51,22 @@ class PRAutoBlogger_Review_Queue {
 		$paged = isset( $_GET['paged'] ) ? absint( $_GET['paged'] ) : 1;
 		$query = $this->get_pending_posts( $paged );
 
+		// v0.18.0 — runs halted by the per-run cost governor are routed
+		// here for human attention (they may have no draft post to list).
+		$halted_runs = $this->get_halted_runs();
+
 		include PRAUTOBLOGGER_PLUGIN_DIR . 'templates/admin/review-queue.php';
 	}
 
+	/**
+	 * Runs halted by the per-run cost governor, newest first.
+	 *
+	 * @return array<int, array<string, mixed>> Halted run rows (max 10).
+	 */
+	public function get_halted_runs(): array {
+		return PRAutoBlogger_Run_State::halted_runs( 10 );
+	}
+
 	/**
 	 * Query generated draft posts awaiting review.
 	 *
@@ -60,20 +75,22 @@ class PRAutoBlogger_Review_Queue {
 	 * @return \WP_Query
 	 */
 	public function get_pending_posts( int $paged = 1 ): \WP_Query {
-		return new \WP_Query( [
-			'post_type'      => 'post',
-			'post_status'    => 'draft',
-			'posts_per_page' => 20,
-			'paged'          => $paged,
-			'meta_query'     => [
-				[
-					'key'   => '_prautoblogger_generated',
-					'value' => '1',
-				],
-			],
-			'orderby'        => 'date',
-			'order'          => 'DESC',
-		] );
+		return new \WP_Query(
+			array(
+				'post_type'      => 'post',
+				'post_status'    => 'draft',
+				'posts_per_page' => 20,
+				'paged'          => $paged,
+				'meta_query'     => array(
+					array(
+						'key'   => '_prautoblogger_generated',
+						'value' => '1',
+					),
+				),
+				'orderby'        => 'date',
+				'order'          => 'DESC',
+			)
+		);
 	}
 
 	/**
@@ -100,7 +117,7 @@ class PRAutoBlogger_Review_Queue {
 		$action   = sanitize_text_field( wp_unslash( $_POST['prautoblogger_bulk_action'] ) );
 		$post_ids = isset( $_POST['prautoblogger_post_ids'] ) && is_array( $_POST['prautoblogger_post_ids'] )
 			? array_map( 'absint', $_POST['prautoblogger_post_ids'] )
-			: [];
+			: array();
 
 		if ( empty( $post_ids ) ) {
 			return;
@@ -113,25 +130,31 @@ class PRAutoBlogger_Review_Queue {
 			}
 
 			if ( 'approve' === $action ) {
-				$result = wp_update_post( [ 'ID' => $post_id, 'post_status' => 'publish' ], true );
+				$result = wp_update_post(
+					array(
+						'ID'          => $post_id,
+						'post_status' => 'publish',
+					),
+					true
+				);
 				if ( ! is_wp_error( $result ) ) {
 					update_post_meta( $post_id, '_prautoblogger_approved_at', gmdate( 'c' ) );
-					$count++;
+					++$count;
 				}
 			} elseif ( 'reject' === $action ) {
 				$result = wp_trash_post( $post_id );
 				if ( false !== $result ) {
-					$count++;
+					++$count;
 				}
 			}
 		}
 
 		$redirect = add_query_arg(
-			[
-				'page'                  => 'prautoblogger-review-queue',
+			array(
+				'page'                    => 'prautoblogger-review-queue',
 				'prautoblogger_bulk_done' => $count,
 				'prautoblogger_bulk_type' => $action,
-			],
+			),
 			admin_url( 'admin.php' )
 		);
 
@@ -150,25 +173,36 @@ class PRAutoBlogger_Review_Queue {
 		check_ajax_referer( 'prautoblogger_review_queue', 'nonce' );
 
 		if ( ! current_user_can( 'manage_options' ) ) {
-			wp_send_json_error( [ 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ], 403 );
+			wp_send_json_error( array( 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ), 403 );
 			return;
 		}
 
 		$post_id = isset( $_POST['post_id'] ) ? absint( $_POST['post_id'] ) : 0;
 		if ( $post_id <= 0 ) {
-			wp_send_json_error( [ 'message' => __( 'Invalid post ID.', 'prautoblogger' ) ] );
+			wp_send_json_error( array( 'message' => __( 'Invalid post ID.', 'prautoblogger' ) ) );
 			return;
 		}
 
-		$result = wp_update_post( [ 'ID' => $post_id, 'post_status' => 'publish' ], true );
+		$result = wp_update_post(
+			array(
+				'ID'          => $post_id,
+				'post_status' => 'publish',
+			),
+			true
+		);
 
 		if ( is_wp_error( $result ) ) {
-			wp_send_json_error( [ 'message' => $result->get_error_message() ] );
+			wp_send_json_error( array( 'message' => $result->get_error_message() ) );
 			return;
 		}
 
 		update_post_meta( $post_id, '_prautoblogger_approved_at', gmdate( 'c' ) );
-		wp_send_json_success( [ 'message' => __( 'Post published.', 'prautoblogger' ), 'post_id' => $post_id ] );
+		wp_send_json_success(
+			array(
+				'message' => __( 'Post published.', 'prautoblogger' ),
+				'post_id' => $post_id,
+			)
+		);
 	}
 
 	/**
@@ -182,22 +216,27 @@ class PRAutoBlogger_Review_Queue {
 		check_ajax_referer( 'prautoblogger_review_queue', 'nonce' );
 
 		if ( ! current_user_can( 'manage_options' ) ) {
-			wp_send_json_error( [ 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ], 403 );
+			wp_send_json_error( array( 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ), 403 );
 			return;
 		}
 
 		$post_id = isset( $_POST['post_id'] ) ? absint( $_POST['post_id'] ) : 0;
 		if ( $post_id <= 0 ) {
-			wp_send_json_error( [ 'message' => __( 'Invalid post ID.', 'prautoblogger' ) ] );
+			wp_send_json_error( array( 'message' => __( 'Invalid post ID.', 'prautoblogger' ) ) );
 			return;
 		}
 
 		$result = wp_trash_post( $post_id );
 		if ( false === $result || null === $result ) {
-			wp_send_json_error( [ 'message' => __( 'Failed to reject post.', 'prautoblogger' ) ] );
+			wp_send_json_error( array( 'message' => __( 'Failed to reject post.', 'prautoblogger' ) ) );
 			return;
 		}
 
-		wp_send_json_success( [ 'message' => __( 'Post rejected.', 'prautoblogger' ), 'post_id' => $post_id ] );
+		wp_send_json_success(
+			array(
+				'message' => __( 'Post rejected.', 'prautoblogger' ),
+				'post_id' => $post_id,
+			)
+		);
 	}
 }

includes/admin/class-settings-fields-extended.php

@@ -0,0 +1,324 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Extended settings fields: schedule, publishing, analytics, display, and images.
+ *
+ * What: Declarative field definitions for operational settings sections.
+ * Who calls it: PRAutoBlogger_Settings_Fields::get_fields() merges these in.
+ * Dependencies: PRAUTOBLOGGER_DEFAULT_IMAGE_MODEL, PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_TEMPLATE constants,
+ *               PRAutoBlogger_Article_Typography (font choices), PRAutoBlogger_Image_Model_Registry.
+ *
+ * @see admin/class-settings-fields.php       — Core fields and sections; calls get_extended_fields().
+ * @see admin/class-admin-page.php            — Renders fields registered from these definitions.
+ * @see admin/class-image-model-registry.php  — Static image model list extracted for 300-line compliance.
+ * @see frontend/class-article-typography.php — Reads Display settings on the frontend.
+ * @see CONVENTIONS.md                        — "How To: Add a New Admin Setting".
+ */
+class PRAutoBlogger_Settings_Fields_Extended {
+
+	/**
+	 * Static image model list for the admin model picker.
+	 * Delegates to Image_Model_Registry (extracted for 300-line file limit).
+	 *
+	 * @return array<int, array<string, mixed>>
+	 */
+	public static function get_image_models(): array {
+		return PRAutoBlogger_Image_Model_Registry::get_models();
+	}
+
+	/**
+	 * Get schedule, publishing, analytics, and image settings fields.
+	 *
+	 * @return array<int, array<string, mixed>>
+	 */
+	public static function get_fields(): array {
+		return array(
+			// ── Sources (extended) ──────────────────────────────────────
+			array(
+				'id'          => 'prautoblogger_research_model',
+				'label'       => __( 'Research Model', 'prautoblogger' ),
+				'type'        => 'model_select',
+				'section'     => 'prautoblogger_sources',
+				'default'     => PRAUTOBLOGGER_DEFAULT_ANALYSIS_MODEL,
+				'capability'  => 'text→text',
+				'description' => __( 'Model for LLM Deep Research. Pick a reasoning-capable model (e.g. Grok 4.1 Fast, DeepSeek-R1) for best results. Only used when LLM Deep Research is enabled above.', 'prautoblogger' ),
+				'badge'       => __( 'Reasoning', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_research_prompt',
+				'label'       => __( 'Research Prompt', 'prautoblogger' ),
+				'type'        => 'textarea',
+				'section'     => 'prautoblogger_sources',
+				'default'     => 'Conduct a deep research sweep of the {niche} space and identify the most substantive, actionable topics that practitioners and curious newcomers are searching for or actively discussing.' . "\n\n" . 'Focus on:' . "\n" . '- Practical questions real readers would search for (not theoretical debates)' . "\n" . '- Emerging trends gaining momentum in the community' . "\n" . '- Common misconceptions that deserve clarification' . "\n" . '- Comparative analysis (product vs. product, protocol vs. protocol)' . "\n" . '- Safety and efficacy topics that drive concern or curiosity' . "\n" . '- Beginner-to-advanced mix — cover entry-level and depth-focused topics' . "\n\n" . 'Aim for topics that feel timely, underserved by existing content, and likely to drive reader engagement. Return 8-12 findings with detailed analysis in each.',
+				'description' => __( 'The research brief sent to the LLM. Use {niche} as a placeholder for your niche description. The system prompt handles output format — this controls WHAT to research.', 'prautoblogger' ),
+			),
+
+			// ── AI Models (extended) ────────────────────────────────────
+			array(
+				'id'          => 'prautoblogger_reasoning_enabled',
+				'label'       => __( 'Enable Reasoning', 'prautoblogger' ),
+				'type'        => 'toggle',
+				'section'     => 'prautoblogger_models',
+				'default'     => '0',
+				'description' => __( 'Send reasoning instructions to models that support it (e.g. Grok, DeepSeek-R1). Reasoning tokens are billed as output tokens — expect higher costs per call. Models that don\'t support reasoning will ignore this.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_reasoning_effort',
+				'label'       => __( 'Reasoning Effort', 'prautoblogger' ),
+				'type'        => 'select',
+				'section'     => 'prautoblogger_models',
+				'default'     => 'medium',
+				'options'     => array(
+					'xhigh'   => __( 'Extra High — maximum depth, highest cost', 'prautoblogger' ),
+					'high'    => __( 'High — thorough reasoning', 'prautoblogger' ),
+					'medium'  => __( 'Medium — balanced (recommended)', 'prautoblogger' ),
+					'low'     => __( 'Low — light reasoning, lower cost', 'prautoblogger' ),
+					'minimal' => __( 'Minimal — barely any reasoning', 'prautoblogger' ),
+				),
+				'description' => __( 'How much effort the model spends reasoning before answering. Higher effort = more reasoning tokens = higher cost. Only applies when reasoning is enabled above. When the Reasoning Token Cap below is set (default), the cap is sent instead of the effort level — set the cap to 0 to use effort only.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_reasoning_max_tokens',
+				'label'       => __( 'Reasoning Token Cap', 'prautoblogger' ),
+				'type'        => 'number',
+				'section'     => 'prautoblogger_models',
+				'default'     => PRAUTOBLOGGER_DEFAULT_REASONING_MAX_TOKENS,
+				'min'         => 0,
+				'max'         => 32000,
+				'description' => __( 'Hard ceiling on thinking tokens per call when reasoning is enabled. The completion budget is raised by this amount so reasoning can never crowd out the article text — an uncapped high effort can spend the entire budget thinking and return an empty draft. 0 = no cap (uncapped effort mode, not recommended).', 'prautoblogger' ),
+			),
+
+			// ── Schedule & Budget ───────────────────────────────────────
+			array(
+				'id'      => 'prautoblogger_daily_article_target',
+				'label'   => __( 'Articles per Day', 'prautoblogger' ),
+				'type'    => 'number',
+				'section' => 'prautoblogger_schedule',
+				'default' => 1,
+				'min'     => 1,
+				'max'     => 10,
+			),
+			array(
+				'id'          => 'prautoblogger_schedule_time',
+				'label'       => __( 'Generation Time', 'prautoblogger' ),
+				'type'        => 'time',
+				'section'     => 'prautoblogger_schedule',
+				'default'     => '03:00',
+				'description' => sprintf(
+					/* translators: %s: site timezone string, e.g. "Asia/Singapore". */
+					esc_html__( "Daily generation runs at this time in your site's configured timezone (Settings → General → Timezone). Current site timezone: %s.", 'prautoblogger' ),
+					esc_html( function_exists( 'wp_timezone_string' ) ? wp_timezone_string() : 'UTC' )
+				),
+			),
+			array(
+				'id'          => 'prautoblogger_monthly_budget_usd',
+				'label'       => __( 'Monthly Budget (USD)', 'prautoblogger' ),
+				'type'        => 'number',
+				'section'     => 'prautoblogger_schedule',
+				'default'     => 50,
+				'min'         => 0,
+				'step'        => '0.01',
+				'description' => __( 'Hard stop when reached. 0 = unlimited.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_request_json_retention_days',
+				'label'       => __( 'Audit Payload Retention (days)', 'prautoblogger' ),
+				'type'        => 'number',
+				'section'     => 'prautoblogger_schedule',
+				'default'     => PRAUTOBLOGGER_DEFAULT_REQUEST_JSON_RETENTION_DAYS,
+				'min'         => 0,
+				'step'        => '1',
+				'description' => __( 'Heavy audit payloads (request_json on the generation log, stage output snapshots) are emptied after this many days by the daily cleanup cron. Cost/token rows are kept forever. 0 = keep payloads forever.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_per_run_cost_ceiling_usd',
+				'label'       => __( 'Per-Run Cost Ceiling (USD)', 'prautoblogger' ),
+				'type'        => 'number',
+				'section'     => 'prautoblogger_schedule',
+				'default'     => PRAUTOBLOGGER_DEFAULT_RUN_CEILING_USD,
+				'min'         => 0,
+				'step'        => '0.01',
+				'description' => __( 'Hard per-run stop: every API call reserves its worst-case cost against this ceiling before dispatch; a breach halts the run and routes it to the Review Queue. Snapshotted at run start. 0 = disabled.', 'prautoblogger' ),
+			),
+
+			// ── Publishing ──────────────────────────────────────────────
+			array(
+				'id'          => 'prautoblogger_auto_publish',
+				'label'       => __( 'Auto-Publish', 'prautoblogger' ),
+				'type'        => 'toggle',
+				'section'     => 'prautoblogger_publishing',
+				'default'     => '0',
+				'description' => __( 'Automatically publish editor-approved posts. When off, all posts go to the Review Queue as drafts.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_default_author',
+				'label'       => __( 'Default Author', 'prautoblogger' ),
+				'type'        => 'author_select',
+				'section'     => 'prautoblogger_publishing',
+				'default'     => 0,
+				'description' => __( 'WordPress user assigned as author of generated posts.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_default_category',
+				'label'       => __( 'Default Category', 'prautoblogger' ),
+				'type'        => 'category_select',
+				'section'     => 'prautoblogger_publishing',
+				'default'     => 0,
+				'description' => __( 'Fallback category for generated posts.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_log_level',
+				'label'       => __( 'Log Level', 'prautoblogger' ),
+				'type'        => 'select',
+				'section'     => 'prautoblogger_publishing',
+				'default'     => 'info',
+				'options'     => array(
+					'error'   => __( 'Error — only failures', 'prautoblogger' ),
+					'warning' => __( 'Warning — errors + warnings', 'prautoblogger' ),
+					'info'    => __( 'Info — key events (recommended)', 'prautoblogger' ),
+					'debug'   => __( 'Debug — everything (verbose)', 'prautoblogger' ),
+				),
+				'description' => __( 'Controls detail level in the Activity Log.', 'prautoblogger' ),
+			),
+
+			// ── Analytics ───────────────────────────────────────────────
+			array(
+				'id'          => 'prautoblogger_ga4_property_id',
+				'label'       => __( 'GA4 Property ID', 'prautoblogger' ),
+				'type'        => 'text',
+				'section'     => 'prautoblogger_analytics',
+				'description' => __( 'Your GA4 Property ID — digits only, e.g. 123456789 (the code adds the "properties/" prefix internally). Find it in GA4 → Admin → Property details. Leave blank to skip GA4.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_ga4_credentials_json',
+				'label'       => __( 'Service Account JSON', 'prautoblogger' ),
+				'type'        => 'password',
+				'section'     => 'prautoblogger_analytics',
+				'description' => __( 'Paste the full JSON key file for a service account with Analytics read access.', 'prautoblogger' ),
+			),
+
+			// ── Display ────────────────────────────────────────────────
+			array(
+				'id'          => 'prautoblogger_article_font_family',
+				'label'       => __( 'Article Font', 'prautoblogger' ),
+				'type'        => 'select',
+				'section'     => 'prautoblogger_display',
+				'default'     => 'default',
+				'options'     => PRAutoBlogger_Article_Typography::get_font_choices(),
+				'description' => __( 'Font family used for generated article body text. Serif fonts improve long-form readability.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_article_font_size',
+				'label'       => __( 'Article Font Size (px)', 'prautoblogger' ),
+				'type'        => 'number',
+				'section'     => 'prautoblogger_display',
+				'default'     => 0,
+				'min'         => 0,
+				'max'         => 32,
+				'description' => __( 'Base font size for article body text. 0 uses the theme default (13px). Recommended: 16–18px for comfortable reading.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_table_borders',
+				'label'       => __( 'Table Borders', 'prautoblogger' ),
+				'type'        => 'toggle',
+				'section'     => 'prautoblogger_display',
+				'default'     => '1',
+				'description' => __( 'Add visible borders, padding, and alternating row colors to tables in generated articles.', 'prautoblogger' ),
+			),
+
+			// ── Images ─────────────────────────────────────────────────
+			array(
+				'id'          => 'prautoblogger_image_enabled',
+				'label'       => __( 'Enable Image Generation', 'prautoblogger' ),
+				'type'        => 'toggle',
+				'section'     => 'prautoblogger_images',
+				'default'     => '0',
+				'description' => __( 'Generate images for each published article.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_image_b_enabled',
+				'label'       => __( 'Generate Second Image (B)', 'prautoblogger' ),
+				'type'        => 'toggle',
+				'section'     => 'prautoblogger_images',
+				'default'     => '1',
+				'description' => __( 'Generate a second image from source data for A/B testing. Disabling saves one image generation + one LLM prompt rewrite per article.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_image_model',
+				'label'       => __( 'Image Model', 'prautoblogger' ),
+				'type'        => 'model_select',
+				'section'     => 'prautoblogger_images',
+				'default'     => PRAUTOBLOGGER_DEFAULT_IMAGE_MODEL,
+				'capability'  => 'image_generation',
+				'description' => __( 'Pick an image model. The provider (Runware or OpenRouter) is derived from the model registry on save, so mismatched pairs are no longer possible.', 'prautoblogger' ),
+				'badge'       => __( 'Quality', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_runware_api_key',
+				'label'       => __( 'Runware API Key', 'prautoblogger' ),
+				'type'        => 'password',
+				'section'     => 'prautoblogger_images',
+				'description' => __( 'Required when using a Runware FLUX model. Get your key at runware.ai/signup.', 'prautoblogger' ),
+				'icon'        => '🔑',
+			),
+			array(
+				'id'          => 'prautoblogger_image_style_template',
+				'label'       => __( 'Style Template', 'prautoblogger' ),
+				'type'        => 'textarea',
+				'section'     => 'prautoblogger_images',
+				'default'     => PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_TEMPLATE,
+				'description' => __( 'The full image prompt template. Must contain exactly one {{ topic_summary }} token, which is filled with a 1-2 sentence topic/mechanism summary per article. The rest is brand-locked editorial style. Replaces the old Style Suffix (now deprecated). Changing mid-run causes visible style drift.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_image_prompt_instructions',
+				'label'       => __( 'Image Prompt Instructions', 'prautoblogger' ),
+				'type'        => 'textarea',
+				'section'     => 'prautoblogger_images',
+				'default'     => PRAutoBlogger_Image_Prompt_Builder::REWRITER_SYSTEM_PROMPT,
+				'description' => __( 'System prompt given to the rewriter LLM that turns each article into a SCENE (a 1-2 sentence editorial topic/mechanism summary, substituted into the Style Template) plus a CAPTION (HTML text shown below the image). Changing this reshapes the look of all future images. Leave blank to use the default.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_image_nsfw_retry',
+				'label'       => __( 'Retry NSFW-Blocked Images', 'prautoblogger' ),
+				'type'        => 'toggle',
+				'section'     => 'prautoblogger_images',
+				'default'     => '1',
+				'description' => __( 'When the provider rejects an image prompt as NSFW, retry once with a generic fallback scene built from the article title. Disable to fail fast if the filter gets trigger-happy.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_image_compose_enabled',
+				'label'       => __( 'Compose Branded Variants', 'prautoblogger' ),
+				'type'        => 'toggle',
+				'section'     => 'prautoblogger_images',
+				'default'     => '1',
+				'description' => __( 'Render branded social variants (teal band, logo, baked caption) from each generated image via the local deterministic composer. Auto-degrades to plain resizing or pass-through if the server lacks an image library — publishing is never blocked.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_image_compose_variants',
+				'label'       => __( 'Composed Variant Set', 'prautoblogger' ),
+				'type'        => 'text',
+				'section'     => 'prautoblogger_images',
+				'default'     => 'og,square',
+				'description' => __( 'Comma-separated variants to render for Image A. Supported: og (1200×630 social share), square (1080×1080 card). Unknown values are ignored.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_image_featured_mark_enabled',
+				'label'       => __( 'Featured Image Corner Mark', 'prautoblogger' ),
+				'type'        => 'toggle',
+				'section'     => 'prautoblogger_images',
+				'default'     => '1',
+				'description' => __( 'Overlay a small semi-transparent Peptide Repo mark in the bottom-right corner of featured images, so scraped or re-shared images carry attribution.', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_runware_model_catalog',
+				'label'       => __( 'Runware Model Catalog', 'prautoblogger' ),
+				'type'        => 'runware_catalog_sync',
+				'section'     => 'prautoblogger_images',
+				'description' => __( 'Live model catalog sync status and on-demand refresh.', 'prautoblogger' ),
+			),
+		);
+	}
+}

includes/admin/class-settings-fields.php

@@ -2,16 +2,21 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Declarative settings fields and sections for the PRAutoBlogger admin page.
  *
  * Centralizes all field and section definitions in one place, making it trivial
  * to add new settings (just add one array entry). Decoupled from page rendering logic.
+ * Core fields (API, Models, Content, Sources) live here; operational fields
+ * (Schedule, Publishing, Analytics, Images) are in Settings_Fields_Extended.
  *
  * Triggered by: PRAutoBlogger_Admin_Page::on_register_settings() calls static methods here.
- * Dependencies: None — contains only data definitions and static methods.
+ * Dependencies: PRAutoBlogger_Settings_Fields_Extended for operational field definitions.
  *
- * @see admin/class-admin-page.php — Calls get_sections() and get_fields() to register settings.
- * @see CONVENTIONS.md             — "How To: Add a New Admin Setting".
+ * @see admin/class-settings-fields-extended.php — Schedule, publishing, analytics, images fields.
+ * @see admin/class-admin-page.php               — Calls get_sections() and get_fields() to register settings.
+ * @see CONVENTIONS.md                           — "How To: Add a New Admin Setting".
  */
 class PRAutoBlogger_Settings_Fields {
 
@@ -21,75 +26,89 @@ class PRAutoBlogger_Settings_Fields {
 	 * @return array<string, array{title: string, icon: string, description: string}>
 	 */
 	public static function get_sections(): array {
-		return [
-			'prautoblogger_api' => [
+		return array(
+			'prautoblogger_api'        => array(
 				'title'       => __( 'API Keys', 'prautoblogger' ),
 				'icon'        => 'dashicons-admin-network',
 				'description' => __( 'Connect your external services. Keys are encrypted at rest.', 'prautoblogger' ),
-			],
-			'prautoblogger_models' => [
+			),
+			'prautoblogger_models'     => array(
 				'title'       => __( 'AI Models', 'prautoblogger' ),
 				'icon'        => 'dashicons-superhero-alt',
 				'description' => __( 'Choose which models power each stage of the pipeline.', 'prautoblogger' ),
-			],
-			'prautoblogger_content' => [
+			),
+			'prautoblogger_content'    => array(
 				'title'       => __( 'Content', 'prautoblogger' ),
 				'icon'        => 'dashicons-edit-large',
 				'description' => __( 'Control tone, length, pipeline mode, and topic guardrails.', 'prautoblogger' ),
-			],
-			'prautoblogger_sources' => [
+			),
+			'prautoblogger_sources'    => array(
 				'title'       => __( 'Sources', 'prautoblogger' ),
 				'icon'        => 'dashicons-rss',
 				'description' => __( 'Configure where PRAutoBlogger finds trending topics.', 'prautoblogger' ),
-			],
-			'prautoblogger_schedule' => [
+			),
+			'prautoblogger_schedule'   => array(
 				'title'       => __( 'Schedule & Budget', 'prautoblogger' ),
 				'icon'        => 'dashicons-calendar-alt',
 				'description' => __( 'Set daily generation schedule, volume, and spending limits.', 'prautoblogger' ),
-			],
-			'prautoblogger_publishing' => [
+			),
+			'prautoblogger_publishing' => array(
 				'title'       => __( 'Publishing', 'prautoblogger' ),
 				'icon'        => 'dashicons-megaphone',
 				'description' => __( 'Control how generated content is published.', 'prautoblogger' ),
-			],
-			'prautoblogger_analytics' => [
+			),
+			'prautoblogger_analytics'  => array(
 				'title'       => __( 'Analytics', 'prautoblogger' ),
 				'icon'        => 'dashicons-chart-area',
 				'description' => __( 'Connect Google Analytics 4 for post performance scoring.', 'prautoblogger' ),
-			],
-			'prautoblogger_images' => [
+			),
+			'prautoblogger_display'    => array(
+				'title'       => __( 'Display', 'prautoblogger' ),
+				'icon'        => 'dashicons-editor-textcolor',
+				'description' => __( 'Control how generated articles look on the frontend — fonts, sizes, and table styling.', 'prautoblogger' ),
+			),
+			'prautoblogger_images'     => array(
 				'title'       => __( 'Images', 'prautoblogger' ),
 				'icon'        => 'dashicons-format-image',
-				'description' => __( 'Cloudflare Workers AI credentials and image style controls.', 'prautoblogger' ),
-			],
-		];
+				'description' => __( 'Image provider, model, and style controls. OpenRouter reuses your existing API key.', 'prautoblogger' ),
+			),
+		);
 	}
 
 	/**
-	 * Get all settings fields. Adding a new setting = adding one entry to this array.
+	 * Get all settings fields. Core fields here, operational fields merged from Extended.
 	 *
 	 * @return array<int, array<string, mixed>>
 	 */
 	public static function get_fields(): array {
-		return [
+		return array_merge( self::get_core_fields(), PRAutoBlogger_Settings_Fields_Extended::get_fields() );
+	}
+
+	/**
+	 * Core fields: API Keys, AI Models, Content, and Sources.
+	 *
+	 * @return array<int, array<string, mixed>>
+	 */
+	private static function get_core_fields(): array {
+		return array(
 			// ── API Keys ────────────────────────────────────────────────
-			[
+			array(
 				'id'          => 'prautoblogger_openrouter_api_key',
 				'label'       => __( 'OpenRouter API Key', 'prautoblogger' ),
 				'type'        => 'password',
 				'section'     => 'prautoblogger_api',
 				'description' => __( 'Get your key at openrouter.ai/keys', 'prautoblogger' ),
 				'icon'        => '🔑',
-			],
-			[
+			),
+			array(
 				'id'          => 'prautoblogger_reddit_source_status',
 				'label'       => __( 'Reddit Data Source', 'prautoblogger' ),
 				'type'        => 'source_status',
 				'section'     => 'prautoblogger_api',
 				'description' => __( 'Uses Reddit RSS (primary) and .json (fallback). No API key required.', 'prautoblogger' ),
 				'icon'        => '📡',
-			],
-			[
+			),
+			array(
 				'id'          => 'prautoblogger_ai_gateway_base_url',
 				'label'       => __( 'Cloudflare AI Gateway URL', 'prautoblogger' ),
 				'type'        => 'text',
@@ -97,8 +116,8 @@ class PRAutoBlogger_Settings_Fields {
 				'default'     => '',
 				'description' => __( 'Optional. Route OpenRouter calls through a Cloudflare AI Gateway for caching, cost logging, and rate limiting. Format: https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openrouter — leave blank to call OpenRouter directly.', 'prautoblogger' ),
 				'icon'        => '☁️',
-			],
-			[
+			),
+			array(
 				'id'          => 'prautoblogger_ai_gateway_cache_ttl',
 				'label'       => __( 'AI Gateway Cache TTL (seconds)', 'prautoblogger' ),
 				'type'        => 'number',
@@ -107,114 +126,142 @@ class PRAutoBlogger_Settings_Fields {
 				'min'         => 0,
 				'max'         => 2592000,
 				'description' => __( 'How long Cloudflare may serve cached responses for identical LLM calls. 0 disables caching. Only used when a gateway URL is set above. Safe values: 0 for article generation (always fresh), 3600+ for repeated classification/scoring calls.', 'prautoblogger' ),
-			],
+			),
 
 			// ── AI Models ───────────────────────────────────────────────
-			[
+			array(
 				'id'          => 'prautoblogger_analysis_model',
 				'label'       => __( 'Analysis Model', 'prautoblogger' ),
-				'type'        => 'text',
+				'type'        => 'model_select',
 				'section'     => 'prautoblogger_models',
 				'default'     => PRAUTOBLOGGER_DEFAULT_ANALYSIS_MODEL,
+				'capability'  => 'text→text',
 				'description' => __( 'Used for source analysis. Pick a cheap, fast model.', 'prautoblogger' ),
 				'badge'       => __( 'Low cost', 'prautoblogger' ),
-			],
-			[
+			),
+			array(
 				'id'          => 'prautoblogger_writing_model',
 				'label'       => __( 'Writing Model', 'prautoblogger' ),
-				'type'        => 'text',
+				'type'        => 'model_select',
 				'section'     => 'prautoblogger_models',
 				'default'     => PRAUTOBLOGGER_DEFAULT_WRITING_MODEL,
+				'capability'  => 'text→text',
 				'description' => __( 'Used for article generation. Quality matters here.', 'prautoblogger' ),
 				'badge'       => __( 'Quality', 'prautoblogger' ),
-			],
-			[
+			),
+			array(
 				'id'          => 'prautoblogger_editor_model',
 				'label'       => __( 'Editor Model', 'prautoblogger' ),
-				'type'        => 'text',
+				'type'        => 'model_select',
 				'section'     => 'prautoblogger_models',
 				'default'     => PRAUTOBLOGGER_DEFAULT_EDITOR_MODEL,
+				'capability'  => 'text→text',
 				'description' => __( 'Used for the chief editor review pass.', 'prautoblogger' ),
 				'badge'       => __( 'Quality', 'prautoblogger' ),
-			],
+			),
 
 			// ── Content ─────────────────────────────────────────────────
-			[
+			array(
 				'id'          => 'prautoblogger_niche_description',
 				'label'       => __( 'Niche Description', 'prautoblogger' ),
 				'type'        => 'textarea',
 				'section'     => 'prautoblogger_content',
 				'description' => __( 'Describe your site\'s niche. Guides content analysis and generation.', 'prautoblogger' ),
-			],
-			[
+			),
+			array(
+				'id'          => 'prautoblogger_analysis_instructions',
+				'label'       => __( 'Analysis Instructions', 'prautoblogger' ),
+				'type'        => 'textarea',
+				'section'     => 'prautoblogger_content',
+				'default'     => '',
+				'description' => __( 'Custom instructions for the topic analysis LLM. Steers how source data is evaluated and which ideas get surfaced — e.g. "Prioritize questions over news. Ignore price-related discussions."', 'prautoblogger' ),
+			),
+			array(
 				'id'      => 'prautoblogger_tone',
 				'label'   => __( 'Content Tone', 'prautoblogger' ),
 				'type'    => 'select',
 				'section' => 'prautoblogger_content',
 				'default' => 'informational',
-				'options' => [
+				'options' => array(
 					'informational'  => __( 'Informational', 'prautoblogger' ),
 					'conversational' => __( 'Conversational', 'prautoblogger' ),
 					'professional'   => __( 'Professional', 'prautoblogger' ),
 					'casual'         => __( 'Casual', 'prautoblogger' ),
 					'authoritative'  => __( 'Authoritative', 'prautoblogger' ),
-				],
-			],
-			[
+				),
+			),
+			array(
 				'id'      => 'prautoblogger_writing_pipeline',
 				'label'   => __( 'Writing Pipeline', 'prautoblogger' ),
 				'type'    => 'select',
 				'section' => 'prautoblogger_content',
 				'default' => 'multi_step',
-				'options' => [
+				'options' => array(
 					'multi_step'  => __( 'Multi-step (outline → draft → polish)', 'prautoblogger' ),
 					'single_pass' => __( 'Single-pass (one LLM call)', 'prautoblogger' ),
-				],
-			],
-			[
+				),
+			),
+			array(
 				'id'      => 'prautoblogger_min_word_count',
 				'label'   => __( 'Min Word Count', 'prautoblogger' ),
 				'type'    => 'number',
 				'section' => 'prautoblogger_content',
 				'default' => 800,
 				'min'     => 200,
-			],
-			[
+			),
+			array(
 				'id'      => 'prautoblogger_max_word_count',
 				'label'   => __( 'Max Word Count', 'prautoblogger' ),
 				'type'    => 'number',
 				'section' => 'prautoblogger_content',
 				'default' => 2000,
 				'min'     => 500,
-			],
-			[
+			),
+			array(
+				'id'          => 'prautoblogger_writing_instructions',
+				'label'       => __( 'Writing Instructions', 'prautoblogger' ),
+				'type'        => 'textarea',
+				'section'     => 'prautoblogger_content',
+				'default'     => '',
+				'description' => __( 'Custom instructions appended to the LLM\'s system prompt when writing articles. Use this to steer style, structure, voice, and formatting — e.g. "Always open with a hook question. Use short paragraphs. Cite at least two studies."', 'prautoblogger' ),
+			),
+			array(
+				'id'          => 'prautoblogger_editor_instructions',
+				'label'       => __( 'Editor Instructions', 'prautoblogger' ),
+				'type'        => 'textarea',
+				'section'     => 'prautoblogger_content',
+				'default'     => '',
+				'description' => __( 'Custom instructions for the chief editor LLM review pass. Steers what the editor looks for and how it revises — e.g. "Be strict about medical disclaimers. Reject any article under 800 words."', 'prautoblogger' ),
+			),
+			array(
 				'id'          => 'prautoblogger_topic_exclusions',
 				'label'       => __( 'Topic Exclusions', 'prautoblogger' ),
 				'type'        => 'textarea',
 				'section'     => 'prautoblogger_content',
 				'description' => __( 'Comma-separated topics to never write about.', 'prautoblogger' ),
-			],
+			),
 
 			// ── Sources ─────────────────────────────────────────────────
-			[
+			array(
 				'id'          => 'prautoblogger_target_subreddits',
 				'label'       => __( 'Target Subreddits', 'prautoblogger' ),
 				'type'        => 'textarea',
 				'section'     => 'prautoblogger_sources',
 				'description' => __( 'Comma-separated, without r/. E.g.: peptides, Nootropics, biohackers', 'prautoblogger' ),
-			],
-			[
+			),
+			array(
 				'id'          => 'prautoblogger_enabled_sources',
 				'label'       => __( 'Enabled Sources', 'prautoblogger' ),
 				'type'        => 'checkboxes',
 				'section'     => 'prautoblogger_sources',
-				'options'     => [
-					'reddit'    => __( 'Reddit (RSS + .json)', 'prautoblogger' ),
-				],
+				'options'     => array(
+					'reddit'       => __( 'Reddit (RSS + .json)', 'prautoblogger' ),
+					'llm_research' => __( 'LLM Deep Research (reasoning model)', 'prautoblogger' ),
+				),
 				'default'     => '["reddit"]',
 				'description' => __( 'Select which platforms to monitor for topics.', 'prautoblogger' ),
-			],
-			[
+			),
+			array(
 				'id'          => 'prautoblogger_pullpush_cache_ttl',
 				'label'       => __( 'Research Cache (hours)', 'prautoblogger' ),
 				'type'        => 'number',
@@ -223,21 +270,21 @@ class PRAutoBlogger_Settings_Fields {
 				'min'         => 1,
 				'max'         => 72,
 				'description' => __( 'How long to cache Reddit research results before re-fetching. Saves bandwidth on low-traffic sites.', 'prautoblogger' ),
-			],
-			[
+			),
+			array(
 				'id'          => 'prautoblogger_reddit_time_filter',
 				'label'       => __( 'Reddit Time Window', 'prautoblogger' ),
 				'type'        => 'select',
 				'section'     => 'prautoblogger_sources',
 				'default'     => 'day',
-				'options'     => [
+				'options'     => array(
 					'day'   => __( 'Past 24 hours', 'prautoblogger' ),
 					'week'  => __( 'Past week', 'prautoblogger' ),
 					'month' => __( 'Past month', 'prautoblogger' ),
-				],
+				),
 				'description' => __( 'How far back to search for trending posts and comments.', 'prautoblogger' ),
-			],
-			[
+			),
+			array(
 				'id'          => 'prautoblogger_reddit_posts_per_subreddit',
 				'label'       => __( 'Posts per Subreddit', 'prautoblogger' ),
 				'type'        => 'number',
@@ -246,133 +293,7 @@ class PRAutoBlogger_Settings_Fields {
 				'min'         => 5,
 				'max'         => 100,
 				'description' => __( 'Maximum posts to fetch per subreddit per collection run.', 'prautoblogger' ),
-			],
-
-			// ── Schedule & Budget ───────────────────────────────────────
-			[
-				'id'      => 'prautoblogger_daily_article_target',
-				'label'   => __( 'Articles per Day', 'prautoblogger' ),
-				'type'    => 'number',
-				'section' => 'prautoblogger_schedule',
-				'default' => 1,
-				'min'     => 1,
-				'max'     => 10,
-			],
-			[
-				'id'          => 'prautoblogger_schedule_time',
-				'label'       => __( 'Generation Time', 'prautoblogger' ),
-				'type'        => 'time',
-				'section'     => 'prautoblogger_schedule',
-				'default'     => '03:00',
-				'description' => __( 'Daily generation runs at this time (server timezone).', 'prautoblogger' ),
-			],
-			[
-				'id'          => 'prautoblogger_monthly_budget_usd',
-				'label'       => __( 'Monthly Budget (USD)', 'prautoblogger' ),
-				'type'        => 'number',
-				'section'     => 'prautoblogger_schedule',
-				'default'     => 50,
-				'min'         => 0,
-				'step'        => '0.01',
-				'description' => __( 'Hard stop when reached. 0 = unlimited.', 'prautoblogger' ),
-			],
-
-			// ── Publishing ──────────────────────────────────────────────
-			[
-				'id'          => 'prautoblogger_auto_publish',
-				'label'       => __( 'Auto-Publish', 'prautoblogger' ),
-				'type'        => 'toggle',
-				'section'     => 'prautoblogger_publishing',
-				'default'     => '0',
-				'description' => __( 'Automatically publish editor-approved posts. When off, all posts go to the Review Queue as drafts.', 'prautoblogger' ),
-			],
-			[
-				'id'          => 'prautoblogger_default_author',
-				'label'       => __( 'Default Author', 'prautoblogger' ),
-				'type'        => 'author_select',
-				'section'     => 'prautoblogger_publishing',
-				'default'     => 0,
-				'description' => __( 'WordPress user assigned as author of generated posts.', 'prautoblogger' ),
-			],
-			[
-				'id'          => 'prautoblogger_default_category',
-				'label'       => __( 'Default Category', 'prautoblogger' ),
-				'type'        => 'category_select',
-				'section'     => 'prautoblogger_publishing',
-				'default'     => 0,
-				'description' => __( 'Fallback category for generated posts.', 'prautoblogger' ),
-			],
-
-			// ── Logging ─────────────────────────────────────────────────
-			[
-				'id'          => 'prautoblogger_log_level',
-				'label'       => __( 'Log Level', 'prautoblogger' ),
-				'type'        => 'select',
-				'section'     => 'prautoblogger_publishing',
-				'default'     => 'info',
-				'options'     => [
-					'error'   => __( 'Error — only failures', 'prautoblogger' ),
-					'warning' => __( 'Warning — errors + warnings', 'prautoblogger' ),
-					'info'    => __( 'Info — key events (recommended)', 'prautoblogger' ),
-					'debug'   => __( 'Debug — everything (verbose)', 'prautoblogger' ),
-				],
-				'description' => __( 'Controls detail level in the Activity Log.', 'prautoblogger' ),
-			],
-
-			// ── Analytics ───────────────────────────────────────────────
-			[
-				'id'          => 'prautoblogger_ga4_property_id',
-				'label'       => __( 'GA4 Property ID', 'prautoblogger' ),
-				'type'        => 'text',
-				'section'     => 'prautoblogger_analytics',
-				'description' => __( 'Format: properties/XXXXXXXXX. Leave blank to skip GA4.', 'prautoblogger' ),
-			],
-			[
-				'id'          => 'prautoblogger_ga4_credentials_json',
-				'label'       => __( 'Service Account JSON', 'prautoblogger' ),
-				'type'        => 'password',
-				'section'     => 'prautoblogger_analytics',
-				'description' => __( 'Paste the full JSON key file for a service account with Analytics read access.', 'prautoblogger' ),
-			],
-
-			// ── Images ─────────────────────────────────────────────────
-			[
-				'id'          => 'prautoblogger_cloudflare_ai_token',
-				'label'       => __( 'Cloudflare API Token', 'prautoblogger' ),
-				'type'        => 'password',
-				'section'     => 'prautoblogger_images',
-				'description' => __( 'Workers AI token with Read + Edit scope. Create at dash.cloudflare.com → AI → API Tokens.', 'prautoblogger' ),
-				'icon'        => '🔑',
-			],
-			[
-				'id'          => 'prautoblogger_cloudflare_account_id',
-				'label'       => __( 'Cloudflare Account ID', 'prautoblogger' ),
-				'type'        => 'text',
-				'section'     => 'prautoblogger_images',
-				'default'     => '',
-				'description' => __( 'The Account ID shown on your Cloudflare dashboard sidebar. Used to build the Workers AI URL.', 'prautoblogger' ),
-			],
-			[
-				'id'          => 'prautoblogger_image_model',
-				'label'       => __( 'Image Model', 'prautoblogger' ),
-				'type'        => 'select',
-				'section'     => 'prautoblogger_images',
-				'default'     => PRAUTOBLOGGER_DEFAULT_IMAGE_MODEL,
-				'options'     => [
-					'flux-1-schnell' => __( 'FLUX.1 [schnell] — fast + cheap (default)', 'prautoblogger' ),
-					'flux-1-dev'     => __( 'FLUX.1 [dev] — higher quality, ~4× cost', 'prautoblogger' ),
-				],
-				'description' => __( 'Schnell is the normal choice. Only switch to [dev] when a specific post needs higher quality.', 'prautoblogger' ),
-				'badge'       => __( 'Low cost', 'prautoblogger' ),
-			],
-			[
-				'id'          => 'prautoblogger_image_style_suffix',
-				'label'       => __( 'Style Suffix', 'prautoblogger' ),
-				'type'        => 'textarea',
-				'section'     => 'prautoblogger_images',
-				'default'     => PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_SUFFIX,
-				'description' => __( 'Appended to every image prompt. Controls the visual look across all placements. Changing this mid-run will cause visible style drift — prefer changing during quiet periods.', 'prautoblogger' ),
-			],
-		];
+			),
+		);
 	}
 }

includes/admin/class-wp-cli-commands.php

@@ -0,0 +1,72 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * WP-CLI commands for PRAutoBlogger.
+ *
+ * Registers custom wp-cli commands exposed to the plugin.
+ */
+class PRAutoBlogger_WP_CLI_Commands {
+
+	/**
+	 * Register WP-CLI commands.
+	 *
+	 * Called on plugins_loaded hook.
+	 */
+	public static function register(): void {
+		if ( ! defined( 'WP_CLI' ) || ! WP_CLI ) {
+			return;
+		}
+
+		// Command: wp prautoblogger opik:eval
+		\WP_CLI::add_command(
+			'prautoblogger opik:eval',
+			array( self::class, 'opik_eval_command' ),
+			array(
+				'shortdesc' => 'Run Opik evals on the frozen dataset',
+				'synopsis'  => array(
+					array(
+						'type'        => 'assoc',
+						'name'        => 'limit',
+						'description' => 'Max items to run (0 = all)',
+						'optional'    => true,
+						'default'     => '0',
+					),
+					array(
+						'type'        => 'flag',
+						'name'        => 'dry-run',
+						'description' => 'Skip Opik API push; score locally only',
+						'optional'    => true,
+					),
+				),
+			)
+		);
+	}
+
+	/**
+	 * Run eval on the frozen dataset.
+	 *
+	 * @param array $args Positional args (unused).
+	 * @param array $assoc_args Associative args: limit, dry-run.
+	 *
+	 * @return void
+	 */
+	public static function opik_eval_command( array $args, array $assoc_args ): void {
+		// Check if Opik is enabled.
+		if ( empty( PRAUTOBLOGGER_OPIK_API_KEY ) || empty( PRAUTOBLOGGER_OPIK_WORKSPACE ) ) {
+			if ( ! isset( $assoc_args['dry-run'] ) ) {
+				// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_echo -- CLI output
+				echo "Warning: Opik is not configured. Running with --dry-run only.\n";
+				$assoc_args['dry-run'] = true;
+			}
+		}
+
+		$limit   = absint( $assoc_args['limit'] ?? 0 );
+		$dry_run = isset( $assoc_args['dry-run'] );
+
+		$runner = new PRAutoBlogger_Opik_Eval_Runner();
+		$result = $runner->run( $limit, $dry_run );
+
+		exit( $result['items_run'] > 0 ? 0 : 1 );
+	}
+}

includes/admin/fields/class-open-router-model-field.php

@@ -0,0 +1,163 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Renders the interactive model-picker field for OpenRouter models.
+ *
+ * What: a button showing the current model's name + pricing. Clicking it
+ *       opens a JS-powered popup (model-picker.js) with a searchable list.
+ *       Includes an estimated cost preview below based on historical usage.
+ * Who calls it: PRAutoBlogger_Admin_Page::render_field() delegates here
+ *               for fields with type 'model_select'.
+ * Dependencies: PRAutoBlogger_Model_Registry_Interface (cached registry lookup),
+ *               PRAutoBlogger_Cost_Tracker (historical token averages).
+ *
+ * @see admin/class-admin-page.php          — Calls render() from the main field switch.
+ * @see assets/js/model-picker.js           — JS popup that fetches + displays models.
+ * @see services/interface-model-registry.php — Registry interface for find_model().
+ * @see core/class-cost-tracker.php         — get_avg_tokens_for_stages() for cost preview.
+ */
+class PRAutoBlogger_OpenRouter_Model_Field {
+
+	/**
+	 * Render the model picker trigger button and hidden input.
+	 *
+	 * @param string               $id    Field HTML id/name attribute.
+	 * @param string               $value Current model id (e.g. 'google/gemini-2.5-flash-lite').
+	 * @param array<string, mixed> $args  Field definition from settings fields.
+	 */
+	public static function render( string $id, string $value, array $args ): void {
+		$capability    = $args['capability'] ?? 'text→text';
+		$display_name  = '' !== $value ? $value : __( '— Select a model —', 'prautoblogger' );
+		$display_price = '';
+		if ( 'image_generation' === $capability ) {
+			// Resolve from the static image model list defined in settings.
+			$image_models = PRAutoBlogger_Settings_Fields_Extended::get_image_models();
+			foreach ( $image_models as $im ) {
+				if ( ( $im['id'] ?? '' ) === $value ) {
+					$display_name  = $im['name'] ?? $value;
+					$display_price = '$' . number_format( (float) ( $im['cost_per_image'] ?? 0 ), 4 ) . '/image';
+					break;
+				}
+			}
+		} else {
+			// Resolve from the OpenRouter model registry cache.
+			$registry = prautoblogger()->get_executor()->get_model_registry();
+			$model    = $registry->find_model( $value );
+			if ( null !== $model ) {
+				$display_name  = $model['name'] ?? $value;
+				$in            = (float) ( $model['input_price_per_m'] ?? 0 );
+				$out           = (float) ( $model['output_price_per_m'] ?? 0 );
+				$display_price = self::format_price( $in ) . ' / ' . self::format_price( $out );
+			}
+		}
+
+		// Hidden input carries the actual value for the form submission.
+		printf(
+			'<input type="hidden" id="%s" name="%s" value="%s" />',
+			esc_attr( $id ),
+			esc_attr( $id ),
+			esc_attr( $value )
+		);
+
+		// Trigger button — opens the model picker popup via JS.
+		printf(
+			'<button type="button" class="ab-mp-trigger" data-field-id="%s" data-capability="%s">'
+			. '<span class="ab-mp-display-name">%s</span>'
+			. '<span class="ab-mp-display-price">%s</span>'
+			. '<span class="ab-mp-display-arrow">&#9662;</span>'
+			. '</button>',
+			esc_attr( $id ),
+			esc_attr( $capability ),
+			esc_html( $display_name ),
+			esc_html( $display_price )
+		);
+
+		// Cost preview panel — only for text→text models (not image).
+		if ( 'image_generation' !== $capability && '' !== $value ) {
+			$cost_preview = self::get_cost_preview( $id, $value );
+			if ( $cost_preview ) {
+				printf(
+					'<div class="ab-mp-cost-preview">%s</div>',
+					wp_kses_post( $cost_preview )
+				);
+			}
+		}
+	}
+
+	/**
+	 * Calculate and render the estimated cost preview for a model + setting combo.
+	 *
+	 * @param string $field_id Setting ID (e.g. 'prautoblogger_writing_model').
+	 * @param string $model_id Model ID (e.g. 'anthropic/claude-3.5-haiku').
+	 *
+	 * @return string HTML snippet for the cost preview, or empty if no history.
+	 */
+	private static function get_cost_preview( string $field_id, string $model_id ): string {
+		$stages = self::get_stages_for_setting( $field_id );
+		if ( empty( $stages ) ) {
+			return '';
+		}
+
+		$registry = prautoblogger()->get_executor()->get_model_registry();
+		$model    = $registry->find_model( $model_id );
+		if ( null === $model ) {
+			return '';
+		}
+
+		$tracker = new PRAutoBlogger_Cost_Tracker();
+		$tokens  = $tracker->get_avg_tokens_for_stages( $stages, 30 );
+
+		if ( 0 === $tokens['sample_size'] ) {
+			return '<small>' . esc_html__( 'Estimated cost: — (insufficient history)', 'prautoblogger' ) . '</small>';
+		}
+
+		$in_price   = (float) ( $model['input_price_per_m'] ?? 0 );
+		$out_price  = (float) ( $model['output_price_per_m'] ?? 0 );
+		$avg_tokens_in  = $tokens['avg_prompt_tokens'];
+		$avg_tokens_out = $tokens['avg_completion_tokens'];
+
+		// Cost per generation = (avg_in_tokens × in_price + avg_out_tokens × out_price) / 1_000_000
+		$cost_per_gen = ( ( $avg_tokens_in * $in_price ) + ( $avg_tokens_out * $out_price ) ) / 1_000_000;
+
+		return sprintf(
+			'<small>%s %s</small>',
+			esc_html__( 'Estimated cost per generation:', 'prautoblogger' ),
+			esc_html( '$' . number_format( $cost_per_gen, 4 ) )
+		);
+	}
+
+	/**
+	 * Map a setting ID to its constituent pipeline stages.
+	 *
+	 * @param string $field_id Setting ID.
+	 *
+	 * @return string[] Stage names, e.g. ['outline', 'draft', 'polish'] for writing model.
+	 */
+	private static function get_stages_for_setting( string $field_id ): array {
+		$map = array(
+			'prautoblogger_analysis_model' => array( 'analysis' ),
+			'prautoblogger_writing_model'  => array( 'outline', 'draft', 'polish' ),
+			'prautoblogger_editor_model'   => array( 'review' ),
+		);
+		return $map[ $field_id ] ?? array();
+	}
+
+	/**
+	 * Format a price-per-million-tokens value for display.
+	 *
+	 * @param float $price Price per 1M tokens.
+	 * @return string Formatted price string like "$0.25" or "Free".
+	 */
+	private static function format_price( float $price ): string {
+		if ( $price <= 0 ) {
+			return __( 'Free', 'prautoblogger' );
+		}
+		if ( $price < 0.01 ) {
+			return '$' . number_format( $price, 4 );
+		}
+		return '$' . number_format( $price, 2 );
+	}
+}

includes/admin/fields/class-source-status-field.php

@@ -0,0 +1,68 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Renders the Reddit source status indicator in the admin settings.
+ *
+ * What: shows RSS (primary) and .json (fallback) availability with
+ *       last-collection timestamp.
+ * Who calls it: PRAutoBlogger_Admin_Page::render_field() delegates here
+ *               for fields with type 'source_status'.
+ * Dependencies: None — reads wp_options only.
+ *
+ * @see admin/class-admin-page.php — Calls render() from the main field switch.
+ */
+class PRAutoBlogger_Source_Status_Field {
+
+	/**
+	 * Render the Reddit source status indicator.
+	 *
+	 * Side effects: reads wp_options for last collection time.
+	 */
+	public static function render(): void {
+		$last_collection  = get_option( 'prautoblogger_last_collection_time', '' );
+		$last_source_used = get_option( 'prautoblogger_last_source_used', '' );
+
+		echo '<div class="ab-source-status">';
+
+		// Reddit RSS — primary source.
+		printf(
+			'<div class="ab-source-row">'
+			. '<span class="ab-source-dot ab-status-ok"></span>'
+			. '<strong>%s</strong> <span class="ab-source-badge">%s</span>'
+			. '<span class="ab-source-label">%s</span>'
+			. '</div>',
+			esc_html__( 'Reddit RSS', 'prautoblogger' ),
+			esc_html__( 'Primary', 'prautoblogger' ),
+			esc_html__( 'Reliable from all IPs', 'prautoblogger' )
+		);
+
+		// Reddit .json — fallback source.
+		printf(
+			'<div class="ab-source-row">'
+			. '<span class="ab-source-dot ab-status-ok"></span>'
+			. '<strong>%s</strong> <span class="ab-source-badge ab-badge-secondary">%s</span>'
+			. '<span class="ab-source-label">%s</span>'
+			. '</div>',
+			esc_html__( 'Reddit .json', 'prautoblogger' ),
+			esc_html__( 'Fallback + Comments', 'prautoblogger' ),
+			esc_html__( 'May be IP-blocked on some hosts', 'prautoblogger' )
+		);
+
+		// Last collection info.
+		if ( '' !== $last_collection ) {
+			$time_ago = human_time_diff( (int) $last_collection, time() );
+			printf(
+				'<div class="ab-source-meta">%s <strong>%s</strong> %s</div>',
+				esc_html__( 'Last collection:', 'prautoblogger' ),
+				/* translators: %s is a human-readable time difference like "2 hours" */
+				esc_html( sprintf( __( '%s ago', 'prautoblogger' ), $time_ago ) ),
+				'' !== $last_source_used ? esc_html( sprintf( __( 'via %s', 'prautoblogger' ), $last_source_used ) ) : ''
+			);
+		}
+
+		echo '</div>';
+	}
+}

includes/ajax/class-model-registry-refresh.php

@@ -0,0 +1,82 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * AJAX handler to manually refresh the OpenRouter model registry.
+ *
+ * What: Allows admins to trigger an immediate refresh of the cached model
+ *       list via a button in the admin UI, without waiting for the daily
+ *       cron. Useful for testing new models or after adding an API key.
+ * Who calls: Admin-facing JavaScript (model-picker.js) via wp_ajax.
+ * Dependencies: PRAutoBlogger_OpenRouter_Model_Registry, capability gating.
+ *
+ * Triggered by: AJAX POST to 'wp-admin/admin-ajax.php?action=prautoblogger_refresh_models'
+ * Side effects: HTTP GET to OpenRouter /api/v1/models (optional, if 12h window passed);
+ *               wp_options write; transient set.
+ *
+ * @see includes/class-ajax-handlers.php — Instantiation and wiring.
+ * @see assets/js/model-picker.js       — Client-side trigger.
+ * @see services/class-open-router-model-registry.php — Registry that performs the work.
+ */
+class PRAutoBlogger_Model_Registry_Refresh {
+
+	/** @var PRAutoBlogger_OpenRouter_Model_Registry Lazy-loaded singleton. */
+	private PRAutoBlogger_OpenRouter_Model_Registry $registry;
+
+	/**
+	 * @param PRAutoBlogger_OpenRouter_Model_Registry $registry Shared model registry.
+	 */
+	public function __construct( PRAutoBlogger_OpenRouter_Model_Registry $registry ) {
+		$this->registry = $registry;
+	}
+
+	/**
+	 * Handle the AJAX refresh request.
+	 *
+	 * Security: nonce-gated via wp-nonce, capability gated to manage_options.
+	 * Response format: JSON { success: bool, data: { count: int, fetched_at: int, message: string } }
+	 *
+	 * @side-effect Writes HTTP GET request, database options, transient cache.
+	 * @return void (echoes JSON)
+	 */
+	public function handle(): void {
+		// Nonce check.
+		if ( ! isset( $_POST['nonce'] ) || ! wp_verify_nonce( sanitize_text_field( wp_unslash( $_POST['nonce'] ) ), 'prautoblogger_refresh_models' ) ) {
+			wp_send_json_error(
+				array(
+					'message' => __( 'Security check failed. Please refresh the page and try again.', 'prautoblogger' ),
+				),
+				403
+			);
+		}
+
+		// Capability check.
+		if ( ! current_user_can( 'manage_options' ) ) {
+			wp_send_json_error(
+				array(
+					'message' => __( 'Insufficient permissions. Only administrators can refresh the model list.', 'prautoblogger' ),
+				),
+				403
+			);
+		}
+
+		// Perform the refresh (force=true bypasses the idempotency window).
+		$result = $this->registry->refresh( true );
+
+		$count       = (int) ( $result['count'] ?? 0 );
+		$fetched_at  = (int) ( $result['fetched_at'] ?? 0 );
+		$mins_ago    = $fetched_at > 0 ? intval( ( time() - $fetched_at ) / 60 ) : 0;
+
+		wp_send_json_success(
+			array(
+				'count'       => $count,
+				'fetched_at'  => $fetched_at,
+				'message'     => sprintf(
+					__( 'Model registry refreshed: %1$d models loaded, last updated %2$s', 'prautoblogger' ),
+					$count,
+					0 === $mins_ago ? __( 'just now', 'prautoblogger' ) : sprintf( __( '%d minutes ago', 'prautoblogger' ), $mins_ago )
+				),
+			)
+		);
+	}
+}

includes/class-activator.php

@@ -2,6 +2,8 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Handles plugin activation: creates database tables, sets default options,
  * and schedules the initial cron job.
  *
@@ -28,121 +30,23 @@ class PRAutoBlogger_Activator {
 		self::create_tables();
 		self::set_default_options();
 		self::schedule_cron();
+		self::backpopulate_run_id_meta_v081();
+		PRAutoBlogger_Migrate_Prompt_Seed_V0180::run();
 
 		// Store the DB version so we can run migrations on future updates.
 		update_option( 'prautoblogger_db_version', PRAUTOBLOGGER_DB_VERSION, false );
 	}
 
 	/**
-	 * Create all custom database tables using dbDelta.
+	 * Delegate to the schema installers — see those classes.
 	 *
-	 * Side effects: creates/updates four database tables.
-	 *
-	 * @return void
+	 * `Schema_Installer` owns the v1.1.0 tables; `Pipeline_Schema_Installer`
+	 * owns the v0.18.0 / db-1.2.0 Pipeline v2 substrate tables. Both are
+	 * dbDelta-idempotent and safe to re-run on any version mismatch.
 	 */
 	private static function create_tables(): void {
-		global $wpdb;
-
-		$charset_collate = $wpdb->get_charset_collate();
-		$prefix          = $wpdb->prefix . 'prautoblogger_';
-
-		require_once ABSPATH . 'wp-admin/includes/upgrade.php';
-
-		// Source data — raw posts/comments from social platforms.
-		$sql_source_data = "CREATE TABLE {$prefix}source_data (
-			id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
-			source_type VARCHAR(50) NOT NULL,
-			source_id VARCHAR(255) NOT NULL,
-			subreddit VARCHAR(255) DEFAULT NULL,
-			title TEXT DEFAULT NULL,
-			content LONGTEXT DEFAULT NULL,
-			author VARCHAR(255) DEFAULT NULL,
-			score INT DEFAULT 0,
-			comment_count INT DEFAULT 0,
-			permalink VARCHAR(500) DEFAULT NULL,
-			collected_at DATETIME NOT NULL,
-			metadata_json LONGTEXT DEFAULT NULL,
-			PRIMARY KEY (id),
-			UNIQUE KEY source_unique (source_type, source_id),
-			KEY source_collected (source_type, collected_at)
-		) {$charset_collate};";
-
-		// Analysis results — detected patterns from source data.
-		$sql_analysis = "CREATE TABLE {$prefix}analysis_results (
-			id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
-			analysis_type VARCHAR(50) NOT NULL,
-			topic VARCHAR(500) NOT NULL,
-			summary TEXT DEFAULT NULL,
-			frequency INT DEFAULT 1,
-			relevance_score FLOAT DEFAULT 0,
-			source_ids_json LONGTEXT DEFAULT NULL,
-			analyzed_at DATETIME NOT NULL,
-			metadata_json LONGTEXT DEFAULT NULL,
-			PRIMARY KEY (id),
-			KEY type_relevance (analysis_type, relevance_score),
-			KEY analyzed_at (analyzed_at)
-		) {$charset_collate};";
-
-		// Generation log — every API call with cost tracking.
-		// run_id groups all log entries from a single pipeline execution so
-		// link_generation_logs() can accurately attribute costs to a post.
-		$sql_generation_log = "CREATE TABLE {$prefix}generation_log (
-			id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
-			post_id BIGINT UNSIGNED DEFAULT NULL,
-			run_id VARCHAR(36) DEFAULT NULL,
-			stage VARCHAR(50) NOT NULL,
-			provider VARCHAR(50) NOT NULL,
-			model VARCHAR(100) NOT NULL,
-			prompt_tokens INT DEFAULT 0,
-			completion_tokens INT DEFAULT 0,
-			estimated_cost DECIMAL(10,6) DEFAULT 0,
-			request_json LONGTEXT DEFAULT NULL,
-			response_status VARCHAR(20) NOT NULL DEFAULT 'success',
-			error_message TEXT DEFAULT NULL,
-			created_at DATETIME NOT NULL,
-			PRIMARY KEY (id),
-			KEY post_id (post_id),
-			KEY run_id (run_id),
-			KEY created_at (created_at),
-			KEY stage (stage)
-		) {$charset_collate};";
-
-		// Content scores — post performance metrics for self-improvement.
-		$sql_content_scores = "CREATE TABLE {$prefix}content_scores (
-			id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
-			post_id BIGINT UNSIGNED NOT NULL,
-			pageviews INT DEFAULT 0,
-			avg_time_on_page FLOAT DEFAULT 0,
-			bounce_rate FLOAT DEFAULT 0,
-			comment_count INT DEFAULT 0,
-			composite_score FLOAT DEFAULT 0,
-			score_factors_json LONGTEXT DEFAULT NULL,
-			measured_at DATETIME NOT NULL,
-			PRIMARY KEY (id),
-			KEY post_id (post_id),
-			KEY measured_at (measured_at),
-			KEY composite_score (composite_score)
-		) {$charset_collate};";
-
-		// Event log — structured application log entries for the admin log viewer.
-		$sql_event_log = "CREATE TABLE {$prefix}event_log (
-			id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
-			level VARCHAR(10) NOT NULL DEFAULT 'info',
-			context VARCHAR(100) DEFAULT NULL,
-			message TEXT NOT NULL,
-			meta_json LONGTEXT DEFAULT NULL,
-			created_at DATETIME NOT NULL,
-			PRIMARY KEY (id),
-			KEY level (level),
-			KEY created_at (created_at),
-			KEY level_created (level, created_at)
-		) {$charset_collate};";
-
-		dbDelta( $sql_source_data );
-		dbDelta( $sql_analysis );
-		dbDelta( $sql_generation_log );
-		dbDelta( $sql_content_scores );
-		dbDelta( $sql_event_log );
+		PRAutoBlogger_Schema_Installer::install();
+		PRAutoBlogger_Pipeline_Schema_Installer::install();
 	}
 
 	/**
@@ -155,23 +59,29 @@ class PRAutoBlogger_Activator {
 	 * @return void
 	 */
 	private static function set_default_options(): void {
-		$defaults = [
+		$defaults = array(
 			'prautoblogger_analysis_model'       => PRAUTOBLOGGER_DEFAULT_ANALYSIS_MODEL,
 			'prautoblogger_writing_model'        => PRAUTOBLOGGER_DEFAULT_WRITING_MODEL,
 			'prautoblogger_editor_model'         => PRAUTOBLOGGER_DEFAULT_EDITOR_MODEL,
-			'prautoblogger_daily_article_target'  => 1,
-			'prautoblogger_writing_pipeline'      => 'multi_step',
-			'prautoblogger_niche_description'     => '',
-			'prautoblogger_target_subreddits'     => '[]',
-			'prautoblogger_monthly_budget_usd'    => 50.00,
-			'prautoblogger_tone'                  => 'informational',
-			'prautoblogger_min_word_count'        => 800,
-			'prautoblogger_max_word_count'        => 2000,
-			'prautoblogger_topic_exclusions'      => '[]',
-			'prautoblogger_enabled_sources'       => '["reddit"]',
-			'prautoblogger_schedule_time'         => '03:00',
-			'prautoblogger_log_level'             => 'info',
-		];
+			'prautoblogger_daily_article_target' => 1,
+			'prautoblogger_writing_pipeline'     => 'multi_step',
+			'prautoblogger_niche_description'    => '',
+			'prautoblogger_target_subreddits'    => '[]',
+			'prautoblogger_monthly_budget_usd'   => 50.00,
+			'prautoblogger_per_run_cost_ceiling_usd' => PRAUTOBLOGGER_DEFAULT_RUN_CEILING_USD,
+			'prautoblogger_request_json_retention_days' => PRAUTOBLOGGER_DEFAULT_REQUEST_JSON_RETENTION_DAYS,
+			'prautoblogger_tone'                 => 'informational',
+			'prautoblogger_min_word_count'       => 800,
+			'prautoblogger_max_word_count'       => 2000,
+			'prautoblogger_topic_exclusions'     => '[]',
+			'prautoblogger_enabled_sources'      => '["reddit"]',
+			'prautoblogger_article_font_family'  => 'default',
+			'prautoblogger_article_font_size'    => 0,
+			'prautoblogger_table_borders'        => '1',
+			'prautoblogger_schedule_time'        => '03:00',
+			'prautoblogger_log_level'            => 'info',
+			'prautoblogger_image_nsfw_retry'     => '1',
+		);
 
 		foreach ( $defaults as $key => $value ) {
 			add_option( $key, $value );
@@ -192,14 +102,8 @@ class PRAutoBlogger_Activator {
 	 */
 	private static function schedule_cron(): void {
 		if ( ! wp_next_scheduled( 'prautoblogger_daily_generation' ) ) {
-			// Schedule for the configured time tomorrow.
-			$time_str  = get_option( 'prautoblogger_schedule_time', '03:00' );
-			$parts     = explode( ':', $time_str );
-			$hour      = isset( $parts[0] ) ? absint( $parts[0] ) : 3;
-			$minute    = isset( $parts[1] ) ? absint( $parts[1] ) : 0;
-			$timestamp = strtotime( "tomorrow {$hour}:{$minute}" );
-
-			if ( false !== $timestamp ) {
+			$timestamp = self::next_daily_generation_timestamp();
+			if ( $timestamp > 0 ) {
 				wp_schedule_event( $timestamp, 'daily', 'prautoblogger_daily_generation' );
 			}
 		}
@@ -209,18 +113,177 @@ class PRAutoBlogger_Activator {
 		// in class-prautoblogger.php may not be hooked yet.
 		$schedules = wp_get_schedules();
 		if ( ! isset( $schedules['prautoblogger_six_hours'] ) ) {
-			add_filter( 'cron_schedules', static function ( array $scheds ): array {
-				$scheds['prautoblogger_six_hours'] = [
-					'interval' => 6 * HOUR_IN_SECONDS,
-					'display'  => __( 'Every Six Hours', 'prautoblogger' ),
-				];
-				return $scheds;
-			} );
+			add_filter(
+				'cron_schedules',
+				static function ( array $scheds ): array {
+					$scheds['prautoblogger_six_hours'] = array(
+						'interval' => 6 * HOUR_IN_SECONDS,
+						'display'  => __( 'Every Six Hours', 'prautoblogger' ),
+					);
+					return $scheds;
+				}
+			);
 		}
 
 		// Schedule a separate metrics collection job (runs every 6 hours).
 		if ( ! wp_next_scheduled( 'prautoblogger_collect_metrics' ) ) {
 			wp_schedule_event( time() + HOUR_IN_SECONDS, 'prautoblogger_six_hours', 'prautoblogger_collect_metrics' );
 		}
+
+		// v0.8.1: daily reaper for orphan `llm_research` rows. Pinned to
+		// 03:15 so it runs 15 min after the primary generation cron, giving
+		// any live pipeline time to finish and call amortize_research_costs
+		// cleanly before the reaper scans.
+		if ( ! wp_next_scheduled( 'prautoblogger_reap_orphan_research_rows' ) ) {
+			$tomorrow = strtotime( 'tomorrow 03:15' );
+			if ( false !== $tomorrow ) {
+				wp_schedule_event( $tomorrow, 'daily', 'prautoblogger_reap_orphan_research_rows' );
+			}
+		}
+
+		// v0.15.0: daily Runware model catalog sync.
+		if ( ! wp_next_scheduled( 'prautoblogger_sync_runware_models' ) ) {
+			wp_schedule_event( time() + HOUR_IN_SECONDS, 'daily', 'prautoblogger_sync_runware_models' );
+		}
+	}
+
+	/**
+	 * Compute the next daily-generation timestamp in the site's configured
+	 * timezone. Fixes the v<0.8.2 bug where `strtotime("tomorrow HH:MM")`
+	 * evaluated in UTC (WP core sets `date_default_timezone_set('UTC')`),
+	 * firing the cron N hours off from user intent where N is the site's
+	 * UTC offset.
+	 *
+	 * @return int Unix timestamp, or 0 on any failure.
+	 */
+	public static function next_daily_generation_timestamp(): int {
+		$time_str = (string) get_option( 'prautoblogger_schedule_time', '03:00' );
+		$parts    = explode( ':', $time_str );
+		$hour     = isset( $parts[0] ) ? absint( $parts[0] ) : 3;
+		$minute   = isset( $parts[1] ) ? absint( $parts[1] ) : 0;
+
+		try {
+			$site_tz = function_exists( 'wp_timezone' )
+				? wp_timezone()
+				: new \DateTimeZone( 'UTC' );
+			$local   = ( new \DateTimeImmutable( 'tomorrow', $site_tz ) )
+				->setTime( $hour, $minute, 0 );
+			return (int) $local->getTimestamp();
+		} catch ( \Exception $e ) {
+			// Defensive: never leave the site without any schedule because
+			// of a bad tz string. Fall back to the pre-fix behaviour.
+			$timestamp = strtotime( "tomorrow {$hour}:{$minute}" );
+			return false === $timestamp ? 0 : (int) $timestamp;
+		}
+	}
+
+	/**
+	 * v0.8.2 one-shot migration — reschedule `prautoblogger_daily_generation`
+	 * in the site's timezone.
+	 *
+	 * Existing installs had their daily cron scheduled with the v<0.8.2
+	 * UTC-interpretation bug. This clears the stale event and reschedules it
+	 * using the timezone-aware helper, exactly once per site (gated by
+	 * `prautoblogger_migrated_schedule_tz_v082`). Logs an INFO line with the
+	 * before/after next-run times so the outcome is auditable.
+	 *
+	 * @return void
+	 */
+	public static function reschedule_daily_in_site_timezone_v082(): void {
+		if ( get_option( 'prautoblogger_migrated_schedule_tz_v082' ) ) {
+			return;
+		}
+
+		$old_timestamp = wp_next_scheduled( 'prautoblogger_daily_generation' );
+		wp_clear_scheduled_hook( 'prautoblogger_daily_generation' );
+
+		$new_timestamp = self::next_daily_generation_timestamp();
+		if ( $new_timestamp > 0 ) {
+			wp_schedule_event( $new_timestamp, 'daily', 'prautoblogger_daily_generation' );
+		}
+
+		if ( class_exists( 'PRAutoBlogger_Logger', false ) ) {
+			PRAutoBlogger_Logger::instance()->info(
+				sprintf(
+					'Rescheduled daily generation in site timezone (was UTC). Old next_run: %s, new next_run: %s.',
+					false !== $old_timestamp ? gmdate( 'Y-m-d H:i:s \\U\\T\\C', (int) $old_timestamp ) : 'unscheduled',
+					$new_timestamp > 0 ? gmdate( 'Y-m-d H:i:s \\U\\T\\C', $new_timestamp ) : 'unscheduled'
+				),
+				'activator'
+			);
+		}
+
+		update_option( 'prautoblogger_migrated_schedule_tz_v082', '1' );
+	}
+
+	/**
+	 * One-shot v0.8.1 migration — back-populate `_prautoblogger_run_id`
+	 * post_meta for existing posts from their gen-log rows.
+	 *
+	 * Lets the orphan-research-row reaper (v0.8.1+) attribute historic
+	 * orphan rows to sibling posts via post_meta lookup, without having
+	 * to walk the generation_log table. Gated by
+	 * `prautoblogger_migrated_run_id_meta_v081` so it runs exactly once
+	 * per site.
+	 *
+	 * Side effects: adds post_meta rows for existing PRAutoBlogger posts
+	 *               that don't already have `_prautoblogger_run_id`.
+	 *
+	 * @return void
+	 */
+	private static function backpopulate_run_id_meta_v081(): void {
+		if ( get_option( 'prautoblogger_migrated_run_id_meta_v081' ) ) {
+			return;
+		}
+
+		global $wpdb;
+		$gen_log = $wpdb->prefix . 'prautoblogger_generation_log';
+
+		// For each (post_id, run_id) pair present in the gen-log, write
+		// the run_id meta if it's not already set. Uses the first run_id
+		// seen per post — in practice each post is linked to exactly one run.
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+		$pairs = $wpdb->get_results(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+			"SELECT post_id, MIN(run_id) AS run_id FROM {$gen_log}
+			WHERE post_id IS NOT NULL AND run_id IS NOT NULL AND run_id != ''
+			GROUP BY post_id"
+		);
+
+		if ( is_array( $pairs ) ) {
+			foreach ( $pairs as $row ) {
+				$post_id = (int) ( $row->post_id ?? 0 );
+				$run_id  = (string) ( $row->run_id ?? '' );
+				if ( $post_id > 0 && '' !== $run_id && ! metadata_exists( 'post', $post_id, '_prautoblogger_run_id' ) ) {
+					update_post_meta( $post_id, '_prautoblogger_run_id', $run_id );
+				}
+			}
+		}
+
+		update_option( 'prautoblogger_migrated_run_id_meta_v081', '1' );
+	}
+
+	/**
+	 * v0.9.0 migration: flip legacy default image model to Runware schnell
+	 * and re-derive provider. CEO decision 2026-04-21 — 65× cheaper than
+	 * Gemini Nano Banana. Explicit user selections are preserved.
+	 *
+	 * Side effects: may update `prautoblogger_image_model`,
+	 *               `prautoblogger_image_provider`, and sets the
+	 *               `prautoblogger_migrated_default_image_v090` flag.
+	 */
+	public static function migrate_default_image_v090(): void {
+		if ( get_option( 'prautoblogger_migrated_default_image_v090' ) ) {
+			return;
+		}
+		$curr = (string) get_option( 'prautoblogger_image_model', '' );
+		if ( in_array( $curr, array( '', 'google/gemini-2.5-flash-image' ), true ) ) {
+			update_option( 'prautoblogger_image_model', 'runware:100@1' );
+		}
+		$final = (string) get_option( 'prautoblogger_image_model', 'runware:100@1' );
+		$prov  = PRAutoBlogger_Image_Model_Registry::provider_for( $final );
+		if ( '' !== $prov ) {
+			update_option( 'prautoblogger_image_provider', $prov );
+		}
+		update_option( 'prautoblogger_migrated_default_image_v090', '1' );
 	}
 }

includes/class-ajax-handlers.php

@@ -0,0 +1,209 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * AJAX endpoint handlers for PRAutoBlogger admin actions.
+ *
+ * What: Handles image generation, model registry, and connection test AJAX requests.
+ * Who calls it: PRAutoBlogger registers wp_ajax hooks that delegate to methods here.
+ * Dependencies: PRAutoBlogger_Image_Pipeline, PRAutoBlogger_Source_Collector,
+ *               PRAutoBlogger_OpenRouter_Provider, PRAutoBlogger_Reddit_Provider,
+ *               PRAutoBlogger_OpenRouter_Model_Registry, PRAutoBlogger_Logger.
+ *
+ * @see class-prautoblogger.php — Hook registration that wires these handlers.
+ * @see class-executor.php      — Generation-related AJAX lives there (generate_now, status).
+ */
+class PRAutoBlogger_Ajax_Handlers {
+
+	/** @var PRAutoBlogger_OpenRouter_Model_Registry Model registry instance (shared with Executor). */
+	private PRAutoBlogger_OpenRouter_Model_Registry $model_registry;
+
+	/**
+	 * @param PRAutoBlogger_OpenRouter_Model_Registry $model_registry Shared model registry.
+	 */
+	public function __construct( PRAutoBlogger_OpenRouter_Model_Registry $model_registry ) {
+		$this->model_registry = $model_registry;
+	}
+
+	/**
+	 * AJAX handler: generate images for existing posts that lack them.
+	 *
+	 * Accepts a `post_id` parameter. Generates Image A (article-driven) and
+	 * sets it as the featured image. Useful for retroactively adding images
+	 * to posts published before image generation was enabled/fixed.
+	 *
+	 * Side effects: image provider API call, media library write, post meta update.
+	 */
+	public function on_ajax_generate_image(): void {
+		check_ajax_referer( 'prautoblogger_generate_image', 'nonce' );
+
+		if ( ! current_user_can( 'manage_options' ) ) {
+			wp_send_json_error( array( 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ), 403 );
+			return;
+		}
+
+		// Image generation can take 20-30s (Runware FLUX + OpenRouter image models).
+		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
+		@set_time_limit( 120 );
+
+		$post_id = isset( $_POST['post_id'] ) ? absint( $_POST['post_id'] ) : 0;
+		if ( 0 === $post_id ) {
+			wp_send_json_error( array( 'message' => __( 'Missing post_id parameter.', 'prautoblogger' ) ) );
+			return;
+		}
+
+		$post = get_post( $post_id );
+		if ( ! $post ) {
+			wp_send_json_error( array( 'message' => sprintf( __( 'Post %d not found.', 'prautoblogger' ), $post_id ) ) );
+			return;
+		}
+
+		try {
+			$pipeline     = new PRAutoBlogger_Image_Pipeline();
+			$article_data = array(
+				'post_title'   => $post->post_title,
+				'post_content' => $post->post_content,
+			);
+
+			// Retrieve original source IDs from post meta so Image B can generate
+			// a source-driven prompt even on retroactive regeneration.
+			$source_ids_json = get_post_meta( $post_id, '_prautoblogger_source_ids', true );
+			$source_ids      = is_string( $source_ids_json ) ? json_decode( $source_ids_json, true ) : array();
+			$source_data     = ( new PRAutoBlogger_Source_Collector() )->get_source_data_for_image(
+				is_array( $source_ids ) ? array_map( 'absint', $source_ids ) : array()
+			);
+
+			// The pipeline sets featured image and Image B meta internally.
+			$result = $pipeline->generate_and_attach_images( $post_id, $article_data, $source_data );
+
+			wp_send_json_success( $result );
+		} catch ( \Throwable $e ) {
+			PRAutoBlogger_Logger::instance()->error(
+				sprintf( 'Retroactive image gen %s for post %d: %s', get_class( $e ), $post_id, $e->getMessage() ),
+				'image_pipeline'
+			);
+			wp_send_json_error( array( 'message' => $e->getMessage() ) );
+		}
+	}
+
+	/**
+	 * AJAX handler: return the model registry for the admin model picker.
+	 *
+	 * Returns the full cached model list. If the registry is empty, triggers
+	 * a refresh first. Called by the model-picker.js popup.
+	 *
+	 * Side effects: may trigger an OpenRouter API call if registry is empty.
+	 */
+	public function on_ajax_get_models(): void {
+		check_ajax_referer( 'prautoblogger_get_models', 'nonce' );
+
+		if ( ! current_user_can( 'manage_options' ) ) {
+			wp_send_json_error( array( 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ), 403 );
+			return;
+		}
+
+		$models = $this->model_registry->get_models();
+
+		// Auto-refresh if the registry has never been populated.
+		if ( empty( $models ) ) {
+			$this->model_registry->refresh( true );
+			$models = $this->model_registry->get_models();
+		}
+
+		wp_send_json_success( $models );
+	}
+
+	/**
+	 * AJAX handler: test API connections (OpenRouter, Reddit).
+	 *
+	 * Accepts a `service` parameter: 'openrouter', 'reddit', or 'all'.
+	 *
+	 * Side effects: API calls to OpenRouter and/or Reddit to validate credentials.
+	 */
+	public function on_ajax_test_connection(): void {
+		check_ajax_referer( 'prautoblogger_test_connection', 'nonce' );
+		if ( ! current_user_can( 'manage_options' ) ) {
+			wp_send_json_error( array( 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ), 403 );
+			return;
+		}
+
+		$service = isset( $_POST['service'] ) ? sanitize_text_field( wp_unslash( $_POST['service'] ) ) : '';
+		$results = array();
+
+		if ( 'openrouter' === $service || 'all' === $service ) {
+			$results['openrouter'] = ( new PRAutoBlogger_OpenRouter_Provider() )->validate_credentials_detailed();
+		}
+		if ( 'reddit' === $service || 'all' === $service ) {
+			$reddit            = new PRAutoBlogger_Reddit_Provider();
+			$is_ok             = $reddit->validate_credentials();
+			$results['reddit'] = $is_ok
+				? array(
+					'status'  => 'ok',
+					'message' => __( 'Reddit source available (RSS primary, .json fallback).', 'prautoblogger' ),
+				)
+				: array(
+					'status'  => 'error',
+					'message' => __( 'Reddit sources unreachable (both RSS and .json failed).', 'prautoblogger' ),
+				);
+		}
+		wp_send_json_success( $results );
+	}
+
+	/**
+	 * AJAX handler: sync Runware model catalog on demand.
+	 *
+	 * Nonce-protected and requires manage_options capability.
+	 * Returns the updated cache timestamp and model count.
+	 *
+	 * Side effects: makes HTTP request to Runware API, writes WP options.
+	 */
+	public function on_ajax_sync_runware_models_now(): void {
+		check_ajax_referer( 'prautoblogger_sync_runware_models_now', 'nonce' );
+
+		if ( ! current_user_can( 'manage_options' ) ) {
+			wp_send_json_error( array( 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ), 403 );
+			return;
+		}
+
+		try {
+			$catalog = new PRAutoBlogger_Runware_Model_Catalog();
+			$success = $catalog->sync();
+
+			if ( ! $success ) {
+				wp_send_json_error( array( 'message' => __( 'Catalog sync failed. Check logs for details.', 'prautoblogger' ) ) );
+				return;
+			}
+
+			$models = $catalog->get_models();
+			$synced_at = $catalog->get_last_synced_at();
+			$synced_at_str = $synced_at
+				? wp_date( __( 'Y-m-d H:i:s', 'prautoblogger' ), $synced_at )
+				: __( 'Never', 'prautoblogger' );
+
+			wp_send_json_success(
+				array(
+					'message'   => __( 'Runware model catalog synced successfully.', 'prautoblogger' ),
+					'model_count' => count( $models ),
+					'synced_at' => $synced_at_str,
+				)
+			);
+		} catch ( \Throwable $e ) {
+			PRAutoBlogger_Logger::instance()->error(
+				sprintf( 'AJAX sync Runware models failed: %s (%s)', $e->getMessage(), get_class( $e ) ),
+				'runware-catalog'
+			);
+			wp_send_json_error( array( 'message' => $e->getMessage() ) );
+		}
+	}
+
+	/**
+	 * Get the shared model registry instance.
+	 *
+	 * @return PRAutoBlogger_OpenRouter_Model_Registry
+	 */
+	public function get_registry(): PRAutoBlogger_OpenRouter_Model_Registry {
+		return $this->model_registry;
+	}
+}

includes/class-autoloader.php

@@ -2,6 +2,8 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * PSR-4-inspired autoloader for PRAutoBlogger classes.
  *
  * Maps class names like `PRAutoBlogger_Content_Generator` to file paths like
@@ -19,14 +21,18 @@ class PRAutoBlogger_Autoloader {
 	 *
 	 * @var string[]
 	 */
-	private static array $directories = [
+	private static array $directories = array(
 		'',           // includes/ root
 		'admin/',
+		'admin/fields/',
 		'core/',
 		'providers/',
 		'models/',
 		'frontend/',
-	];
+		'services/',
+		'services/opik/',
+		'ajax/',
+	);
 
 	/**
 	 * Register the autoloader with SPL.
@@ -34,7 +40,7 @@ class PRAutoBlogger_Autoloader {
 	 * @return void
 	 */
 	public static function register(): void {
-		spl_autoload_register( [ __CLASS__, 'autoload' ] );
+		spl_autoload_register( array( __CLASS__, 'autoload' ) );
 	}
 
 	/**

includes/class-deactivator.php

@@ -2,6 +2,8 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Handles plugin deactivation: clears scheduled cron events and transients.
  *
  * Note: does NOT delete data or options — that happens in uninstall.php.
@@ -33,10 +35,12 @@ class PRAutoBlogger_Deactivator {
 	 * @return void
 	 */
 	private static function clear_cron(): void {
-		$hooks = [
+		$hooks = array(
 			'prautoblogger_daily_generation',
 			'prautoblogger_collect_metrics',
-		];
+			'prautoblogger_reap_orphan_research_rows',
+			'prautoblogger_sync_runware_models',
+		);
 
 		foreach ( $hooks as $hook ) {
 			$timestamp = wp_next_scheduled( $hook );
@@ -54,11 +58,11 @@ class PRAutoBlogger_Deactivator {
 	 * @return void
 	 */
 	private static function clear_transients(): void {
-		$transients = [
+		$transients = array(
 			'prautoblogger_reddit_token',
 			'prautoblogger_generation_lock',
 			'prautoblogger_openrouter_models',
-		];
+		);
 
 		foreach ( $transients as $transient ) {
 			delete_transient( $transient );

includes/class-encryption.php

@@ -2,6 +2,8 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Encrypts and decrypts sensitive option values (API keys, secrets).
  *
  * Uses OpenSSL AES-256-CBC with a key derived from wp_salt('auth').

includes/class-executor.php

@@ -0,0 +1,226 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Cron handlers for content generation and metrics collection.
+ *
+ * What: Daily generation, manual generation, queued-article processing,
+ *       and metrics collection cron handlers. AJAX generation handlers
+ *       live in PRAutoBlogger_Generation_Status_Poller (v0.18.3 split).
+ * Triggered by: PRAutoBlogger hook registration.
+ * Dependencies: Pipeline_Runner, Metrics_Collector, Generation_Lock, Logger.
+ *
+ * @see class-generation-status-poller.php — "Generate Now" AJAX + status poll.
+ * @see class-prautoblogger.php            — Hook wiring.
+ * @see core/class-pipeline-runner.php     — Actual generation pipeline.
+ * @see class-generation-lock.php          — DB mutex.
+ */
+class PRAutoBlogger_Executor {
+
+	/** @var PRAutoBlogger_OpenRouter_Model_Registry|null Lazy-loaded singleton. */
+	private ?PRAutoBlogger_OpenRouter_Model_Registry $model_registry = null;
+
+	/** @var PRAutoBlogger_Generation_Status_Poller|null Lazy-loaded poller. */
+	private ?PRAutoBlogger_Generation_Status_Poller $poller = null;
+
+	/**
+	 * Handle the daily generation cron event.
+	 *
+	 * Uses an atomic DB mutex. If the pipeline queues additional articles,
+	 * they fire as chained cron events and the lock is released by the
+	 * last article job — not here.
+	 *
+	 * Side effects: API calls, database writes, WordPress post creation.
+	 */
+	public function on_daily_generation(): void {
+		do_action( 'prautoblogger_refresh_model_registry', false );
+
+		if ( ! PRAutoBlogger_Generation_Lock::acquire() ) {
+			PRAutoBlogger_Logger::instance()->info( 'Daily generation skipped: already running (lock held).', 'scheduler' );
+			return;
+		}
+
+		try {
+			( new PRAutoBlogger_Pipeline_Runner() )->run();
+
+			// Release lock only if no articles were queued for chained processing.
+			if ( ! get_option( 'prautoblogger_article_queue' ) ) {
+				PRAutoBlogger_Generation_Lock::release();
+			}
+		} catch ( \Throwable $e ) {
+			PRAutoBlogger_Logger::instance()->error(
+				sprintf( 'Daily generation %s: %s', get_class( $e ), $e->getMessage() ),
+				'scheduler'
+			);
+			$this->mark_current_run_failed();
+			PRAutoBlogger_Generation_Lock::release();
+		}
+	}
+
+	/**
+	 * Handle the metrics collection cron event.
+	 * Side effects: API calls to GA4, database writes to ab_content_scores.
+	 */
+	public function on_collect_metrics(): void {
+		try {
+			( new PRAutoBlogger_Metrics_Collector() )->collect_all();
+		} catch ( \Throwable $e ) {
+			PRAutoBlogger_Logger::instance()->error(
+				sprintf( 'Metrics collection %s: %s', get_class( $e ), $e->getMessage() ),
+				'metrics'
+			);
+		}
+	}
+
+	/**
+	 * AJAX handler: kick off manual generation as a background cron job.
+	 * Delegates to PRAutoBlogger_Generation_Status_Poller.
+	 *
+	 * Side effects: schedules a WP-Cron event, writes a status transient.
+	 */
+	public function on_ajax_generate_now(): void {
+		$this->poller()->on_ajax_generate_now();
+	}
+
+	/**
+	 * Cron handler: runs pipeline orchestration + first article.
+	 *
+	 * If the pipeline queues additional articles (2..N), they will fire as
+	 * chained cron events — each in its own PHP process. The lock is released
+	 * by the pipeline when the last article completes, not here.
+	 */
+	public function on_manual_generation(): void {
+		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
+		@ignore_user_abort( true );
+		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
+		@set_time_limit( 300 );
+
+		if ( ! PRAutoBlogger_Generation_Lock::acquire() ) {
+			set_transient(
+				PRAutoBlogger_Generation_Status_Poller::STATUS_TRANSIENT,
+				array(
+					'status'  => 'error',
+					'message' => __( 'Could not acquire generation lock. Another run may be in progress.', 'prautoblogger' ),
+				),
+				PRAutoBlogger_Generation_Status_Poller::STATUS_TTL
+			);
+			return;
+		}
+
+		try {
+			$this->poller()->update_generation_stage( __( 'Collecting sources from Reddit...', 'prautoblogger' ) );
+
+			$runner  = ( new PRAutoBlogger_Pipeline_Runner() )->set_skip_dedup( true );
+			$results = $runner->run();
+
+			// If no articles were queued (target=1 or 0 ideas), finalize here.
+			// When articles ARE queued, the pipeline handles status + lock release.
+			if ( ! get_option( 'prautoblogger_article_queue' ) ) {
+				set_transient(
+					PRAutoBlogger_Generation_Status_Poller::STATUS_TRANSIENT,
+					array(
+						'status'    => 'complete',
+						'generated' => $results['generated'],
+						'published' => $results['published'],
+						'rejected'  => $results['rejected'],
+						'cost'      => $results['cost'],
+					),
+					PRAutoBlogger_Generation_Status_Poller::STATUS_TTL
+				);
+				PRAutoBlogger_Generation_Lock::release();
+			}
+		} catch ( \Throwable $e ) {
+			PRAutoBlogger_Logger::instance()->error(
+				sprintf( 'Manual generation %s: %s', get_class( $e ), $e->getMessage() ),
+				'pipeline'
+			);
+			set_transient(
+				PRAutoBlogger_Generation_Status_Poller::STATUS_TRANSIENT,
+				array(
+					'status'  => 'error',
+					'message' => $e->getMessage(),
+				),
+				PRAutoBlogger_Generation_Status_Poller::STATUS_TTL
+			);
+			$this->mark_current_run_failed();
+			PRAutoBlogger_Generation_Lock::release();
+		}
+	}
+
+	/** Cron handler: process next queued article. Chained by Pipeline_Runner. */
+	public function on_process_article_queue(): void {
+		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
+		@ignore_user_abort( true );
+		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
+		@set_time_limit( 300 );
+
+		try {
+			( new PRAutoBlogger_Pipeline_Runner() )->process_next_queued_article();
+		} catch ( \Throwable $e ) {
+			PRAutoBlogger_Logger::instance()->error(
+				sprintf( 'Queued article generation %s: %s', get_class( $e ), $e->getMessage() ),
+				'pipeline'
+			);
+			// Clean up on catastrophic failure.
+			delete_option( 'prautoblogger_article_queue' );
+			PRAutoBlogger_Generation_Lock::release();
+			set_transient(
+				PRAutoBlogger_Generation_Status_Poller::STATUS_TRANSIENT,
+				array(
+					'status'  => 'error',
+					'message' => $e->getMessage(),
+				),
+				PRAutoBlogger_Generation_Status_Poller::STATUS_TTL
+			);
+		}
+	}
+
+	/** AJAX: return generation status for frontend polling. Delegates to poller. */
+	public function on_ajax_generation_status(): void {
+		$this->poller()->on_ajax_generation_status();
+	}
+
+	/**
+	 * Lazy-load the generation status poller.
+	 *
+	 * @return PRAutoBlogger_Generation_Status_Poller
+	 */
+	private function poller(): PRAutoBlogger_Generation_Status_Poller {
+		if ( null === $this->poller ) {
+			$this->poller = new PRAutoBlogger_Generation_Status_Poller();
+		}
+		return $this->poller;
+	}
+
+	/**
+	 * Mark this process's run failed after a fatal pipeline error
+	 * (no-op outside a run; a governor-halted run stays halted — final
+	 * states are sticky).
+	 *
+	 * @return void
+	 */
+	private function mark_current_run_failed(): void {
+		$run_id = PRAutoBlogger_Run_Context::current_run_id();
+		if ( null !== $run_id ) {
+			PRAutoBlogger_Run_State::mark_status( $run_id, 'failed' );
+		}
+	}
+
+	/**
+	 * Lazy-load the OpenRouter model registry singleton.
+	 * Config injected here — registry class has no knowledge of PRAUTOBLOGGER_* constants.
+	 *
+	 * @return PRAutoBlogger_OpenRouter_Model_Registry
+	 */
+	public function get_model_registry(): PRAutoBlogger_OpenRouter_Model_Registry {
+		if ( null === $this->model_registry ) {
+			$this->model_registry = new PRAutoBlogger_OpenRouter_Model_Registry(
+				'prautoblogger_openrouter_model_registry',
+				'prautoblogger_openrouter_model_registry_cache'
+			);
+		}
+		return $this->model_registry;
+	}
+}

includes/class-generation-lock.php

@@ -0,0 +1,120 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Database-level atomic mutex for content generation.
+ *
+ * What: Provides acquire/release/check semantics for a single-writer generation lock.
+ * Who calls it: PRAutoBlogger_Executor (daily and manual generation), status polling fallback.
+ * Dependencies: WordPress $wpdb for direct SQL.
+ *
+ * Uses INSERT IGNORE against the wp_options UNIQUE index on option_name to
+ * guarantee only one PHP process can hold the lock at a time. Expired locks
+ * (>1 hour) are cleaned up automatically on acquire to prevent permanent deadlock.
+ *
+ * @see class-executor.php — Acquires/releases the lock around pipeline runs.
+ * @see class-ajax-handlers.php — Releases stale locks in the status fallback path.
+ */
+class PRAutoBlogger_Generation_Lock {
+
+	/** @var string Option name used as the lock key in wp_options. */
+	private const LOCK_NAME = 'prautoblogger_generation_lock';
+
+	/**
+	 * Acquire the generation mutex.
+	 *
+	 * Cleans up expired locks (>1 hour) first, then attempts an atomic INSERT
+	 * IGNORE. The UNIQUE constraint on option_name ensures only one caller wins.
+	 *
+	 * @return bool True if lock acquired, false if already held.
+	 */
+	public static function acquire(): bool {
+		global $wpdb;
+
+		// Clean up expired locks to prevent permanent deadlock.
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$wpdb->query(
+			$wpdb->prepare(
+				"DELETE FROM {$wpdb->options} WHERE option_name = %s AND CAST(option_value AS UNSIGNED) < %d",
+				self::LOCK_NAME,
+				time() - HOUR_IN_SECONDS
+			)
+		);
+
+		// Atomic insert — UNIQUE constraint guarantees only one process succeeds.
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$result = $wpdb->query(
+			$wpdb->prepare(
+				"INSERT IGNORE INTO {$wpdb->options} (option_name, option_value, autoload) VALUES (%s, %s, %s)",
+				self::LOCK_NAME,
+				(string) time(),
+				'no'
+			)
+		);
+
+		return $result > 0;
+	}
+
+	/**
+	 * Check if the generation lock is currently held.
+	 *
+	 * @return bool True if the lock exists (generation in progress or stuck).
+	 */
+	public static function is_locked(): bool {
+		global $wpdb;
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$row = $wpdb->get_var(
+			$wpdb->prepare(
+				"SELECT option_value FROM {$wpdb->options} WHERE option_name = %s LIMIT 1",
+				self::LOCK_NAME
+			)
+		);
+
+		return null !== $row;
+	}
+
+	/**
+	 * Get the Unix timestamp when the lock was acquired, or null if not held.
+	 *
+	 * Returns null when the lock is not set. The timestamp is the value written
+	 * by acquire() — used by the status poller to detect infrastructure-timeout
+	 * runs (lock held longer than STATUS_TTL → background PHP process died).
+	 *
+	 * @return int|null Unix timestamp, or null when the lock is absent.
+	 */
+	public static function get_acquired_at(): ?int {
+		global $wpdb;
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$row = $wpdb->get_var(
+			$wpdb->prepare(
+				"SELECT option_value FROM {$wpdb->options} WHERE option_name = %s LIMIT 1",
+				self::LOCK_NAME
+			)
+		);
+
+		return null !== $row ? (int) $row : null;
+	}
+
+	/**
+	 * Release the generation mutex.
+	 *
+	 * Safe to call even if the lock is not held (no-ops gracefully).
+	 *
+	 * Side effects: deletes the lock row from wp_options.
+	 */
+	public static function release(): void {
+		global $wpdb;
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$wpdb->query(
+			$wpdb->prepare(
+				"DELETE FROM {$wpdb->options} WHERE option_name = %s",
+				self::LOCK_NAME
+			)
+		);
+	}
+}

includes/class-generation-status-poller.php

@@ -0,0 +1,260 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * AJAX handlers for "Generate Now" + status polling.
+ *
+ * What: Two AJAX endpoints: kick-off (fire-and-forget cron spawn) and the
+ *       status poll that drives the admin UI spinner. Extracted from
+ *       PRAutoBlogger_Executor in v0.18.3 to keep each file under 300 lines.
+ *
+ * R2/R3 resilience (v0.18.3):
+ *   - R2(a): on_ajax_generate_now() renews the transient with the
+ *     full STATUS_TTL on every stage update via update_generation_stage().
+ *   - R2(b): on_ajax_generation_status() detects lock-held-but-transient-gone
+ *     when the lock has been held > STATUS_TTL seconds (Hostinger background-
+ *     process death); marks the stuck run failed + surfaces a human-readable
+ *     "infrastructure timeout" message for the Activity Log.
+ *   - R3: on_ajax_generation_status() returns status:running (with
+ *     started_at) when the transient is absent but the lock IS held and
+ *     within TTL — so the button reflects reality during long runs rather
+ *     than silently resetting to idle.
+ *
+ * Who calls it: PRAutoBlogger hook registration (wp_ajax_prautoblogger_*).
+ * Dependencies: PRAutoBlogger_Generation_Lock, PRAutoBlogger_Run_State,
+ *               PRAutoBlogger_Run_Context, PRAutoBlogger_Pipeline_Runner,
+ *               PRAutoBlogger_Logger.
+ *
+ * @see class-executor.php         — Cron handlers (daily, manual, queued).
+ * @see class-generation-lock.php  — DB mutex (acquire/release/timestamps).
+ * @see core/class-pipeline-status.php — Transient broadcast helpers.
+ * @see ARCHITECTURE.md #21        — Run lifecycle and reaper design.
+ */
+class PRAutoBlogger_Generation_Status_Poller {
+
+	/** Transient key for background generation status (shared with Pipeline_Status). */
+	public const STATUS_TRANSIENT = 'prautoblogger_generation_status';
+
+	/**
+	 * How long (seconds) to keep the status transient readable.
+	 * Renewed on every stage transition so a long run doesn't expire it early.
+	 */
+	public const STATUS_TTL = 600;
+
+	/**
+	 * AJAX handler: kick off manual generation as a background cron job.
+	 *
+	 * Returns immediately so the browser never hits Hostinger's connection
+	 * timeout. The frontend polls on_ajax_generation_status() every few
+	 * seconds for progress and final results.
+	 *
+	 * Side effects: schedules a WP-Cron event, writes a status transient.
+	 */
+	public function on_ajax_generate_now(): void {
+		check_ajax_referer( 'prautoblogger_generate_now', 'nonce' );
+
+		if ( ! current_user_can( 'manage_options' ) ) {
+			wp_send_json_error( array( 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ), 403 );
+			return;
+		}
+
+		$force = isset( $_POST['force'] ) && '1' === $_POST['force'];
+		if ( $force ) {
+			PRAutoBlogger_Generation_Lock::release();
+			delete_transient( self::STATUS_TRANSIENT );
+		}
+
+		// Check if a run is already in progress.
+		$current = get_transient( self::STATUS_TRANSIENT );
+		if ( is_array( $current ) && 'running' === ( $current['status'] ?? '' ) ) {
+			wp_send_json_success(
+				array(
+					'background' => true,
+					'message'    => __( 'Generation already in progress.', 'prautoblogger' ),
+				)
+			);
+			return;
+		}
+
+		// Write initial "running" status for the frontend to poll.
+		set_transient(
+			self::STATUS_TRANSIENT,
+			array(
+				'status'       => 'running',
+				'stage'        => __( 'Starting generation...', 'prautoblogger' ),
+				'started'      => time(),
+				'last_updated' => time(),
+			),
+			self::STATUS_TTL
+		);
+
+		// Schedule immediate one-shot cron event. WordPress will fire this
+		// on the next page load (or via wp-cron.php) in a separate PHP process
+		// not subject to the connection timeout.
+		if ( ! wp_next_scheduled( 'prautoblogger_manual_generation' ) ) {
+			wp_schedule_single_event( time(), 'prautoblogger_manual_generation' );
+		}
+
+		// Spawn the cron immediately via a non-blocking loopback request
+		// so we don't depend on the next visitor to trigger it.
+		spawn_cron();
+
+		// Direct non-blocking loopback to wp-cron.php — ensures the event
+		// fires even if DISABLE_WP_CRON is true or spawn_cron() no-ops.
+		wp_remote_post(
+			site_url( 'wp-cron.php?doing_wp_cron=' . sprintf( '%.22F', microtime( true ) ) ),
+			array(
+				'timeout'   => 0.01,
+				'blocking'  => false,
+				'sslverify' => false,
+			)
+		);
+
+		wp_send_json_success(
+			array(
+				'background' => true,
+				'message'    => __( 'Generation started in background. Polling for status...', 'prautoblogger' ),
+			)
+		);
+	}
+
+	/** AJAX: return generation status for frontend polling. Recovers orphaned runs. */
+	public function on_ajax_generation_status(): void {
+		check_ajax_referer( 'prautoblogger_generate_now', 'nonce' );
+		if ( ! current_user_can( 'manage_options' ) ) {
+			wp_send_json_error( array( 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ), 403 );
+			return;
+		}
+
+		$status = get_transient( self::STATUS_TRANSIENT );
+
+		// R2(b) + R3: transient is gone — check the lock before returning idle.
+		if ( ! is_array( $status ) ) {
+			$this->handle_missing_transient();
+			return;
+		}
+
+		if ( 'running' === $status['status'] ) {
+			$elapsed = time() - ( $status['started'] ?? 0 );
+
+			// Absolute timeout — give up after STATUS_TTL.
+			if ( $elapsed > self::STATUS_TTL ) {
+				$this->abort_orphaned_run( __( 'Generation timed out. Check the Activity Log.', 'prautoblogger' ) );
+				return;
+			}
+
+			// After 90s, check if a queued job died and needs re-scheduling.
+			if ( $elapsed > 90 && get_option( 'prautoblogger_article_queue' ) ) {
+				if ( ! wp_next_scheduled( PRAutoBlogger_Pipeline_Runner::CRON_ACTION ) ) {
+					wp_schedule_single_event( time(), PRAutoBlogger_Pipeline_Runner::CRON_ACTION );
+					spawn_cron();
+				}
+			}
+
+			// Stall = 5 min since last stage update (not since start).
+			$last_activity = $status['last_updated'] ?? $status['started'] ?? 0;
+			$idle_seconds  = time() - $last_activity;
+			if ( $idle_seconds > 300 ) {
+				$this->abort_orphaned_run( __( 'Generation stalled. Check Activity Log.', 'prautoblogger' ) );
+				return;
+			}
+		}
+
+		wp_send_json_success( $status );
+	}
+
+	/**
+	 * Handle the case where the status transient is absent.
+	 *
+	 * R3: if lock is HELD and within TTL → return status:running so the
+	 *     button reflects reality during long background runs.
+	 * R2(b): if lock is held but has been held > STATUS_TTL → the background
+	 *     PHP process died without releasing it; mark the run failed and
+	 *     surface "infrastructure timeout" to the UI.
+	 *
+	 * @return void Sends JSON and exits.
+	 */
+	private function handle_missing_transient(): void {
+		$acquired_at = PRAutoBlogger_Generation_Lock::get_acquired_at();
+
+		if ( null === $acquired_at ) {
+			// Lock not held — genuinely idle.
+			wp_send_json_success( array( 'status' => 'idle' ) );
+			return;
+		}
+
+		$lock_age = time() - $acquired_at;
+
+		if ( $lock_age > self::STATUS_TTL ) {
+			// Lock held longer than STATUS_TTL: background process died.
+			// R2(b): mark the stuck run failed + surface a clear error.
+			PRAutoBlogger_Logger::instance()->warning(
+				sprintf(
+					'Status transient absent and lock held for %ds (> %ds TTL) — background process died; marking run failed.',
+					$lock_age,
+					self::STATUS_TTL
+				),
+				'pipeline'
+			);
+			$this->abort_orphaned_run(
+				__( 'Generation failed — infrastructure timeout. Check Activity Log for details.', 'prautoblogger' )
+			);
+			return;
+		}
+
+		// R3: lock is fresh (within TTL) but transient is gone — long run in
+		// progress (pipeline broadcast hasn't fired yet, or transient was
+		// evicted by object-cache pressure). Return running so the button
+		// does not silently reset to idle.
+		wp_send_json_success(
+			array(
+				'status'       => 'running',
+				'stage'        => __( 'Generation in progress (background). Check Activity Log for details.', 'prautoblogger' ),
+				'started'      => $acquired_at,
+				'last_updated' => $acquired_at,
+			)
+		);
+	}
+
+	/** Clean up an orphaned generation run and report error. */
+	private function abort_orphaned_run( string $message ): void {
+		// Mark the stuck run as failed in the audit ledger.
+		$queue = get_option( 'prautoblogger_article_queue' );
+		if ( is_array( $queue ) && ! empty( $queue['run_id'] ) ) {
+			PRAutoBlogger_Run_State::mark_status( (string) $queue['run_id'], 'failed' );
+		}
+		// Also attempt to close the current active run from Run_Context.
+		$run_id = PRAutoBlogger_Run_Context::current_run_id();
+		if ( null !== $run_id ) {
+			PRAutoBlogger_Run_State::mark_status( $run_id, 'failed' );
+		}
+		delete_transient( self::STATUS_TRANSIENT );
+		delete_option( 'prautoblogger_article_queue' );
+		PRAutoBlogger_Generation_Lock::release();
+		wp_send_json_success(
+			array(
+				'status'  => 'error',
+				'message' => $message,
+			)
+		);
+	}
+
+	/**
+	 * Update the generation stage text for frontend polling.
+	 * Renews the transient TTL at every call so a long run doesn't expire it.
+	 *
+	 * @param string $stage Human-readable stage description.
+	 */
+	public function update_generation_stage( string $stage ): void {
+		$current = get_transient( self::STATUS_TRANSIENT );
+		if ( is_array( $current ) ) {
+			$current['stage']        = $stage;
+			$current['last_updated'] = time();
+			// R2(a): renew the TTL on every stage update so the transient
+			// outlives any single LLM call (STATUS_TTL from last activity).
+			set_transient( self::STATUS_TRANSIENT, $current, self::STATUS_TTL );
+		}
+	}
+}

includes/class-migrate-prompt-seed-v0180.php

@@ -0,0 +1,59 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * One-shot v0.18.0 migration — seed the versioned prompt registry.
+ *
+ * What: Writes the canonical hardcoded prompt texts (content, analysis,
+ *       editor, research, illustration rewriter, image Style Template)
+ *       into `wp_prautoblogger_prompts` as immutable version 1 and
+ *       activates them. Idempotent twice over: gated by the
+ *       `prautoblogger_migrated_prompt_seed_v0180` flag AND seed_v1()
+ *       itself skips any key that already has rows. The flag is only set
+ *       when the table was actually reachable, so a failed seed
+ *       self-heals on the next activation / version-mismatch pass.
+ *       Standalone class per the Migrate_Remove_Cloudflare_V0100
+ *       precedent (keeps Activator under the 300-line cap).
+ * Who triggers it: PRAutoBlogger_Activator::activate() — on activation and
+ *       on every db-version mismatch.
+ * Dependencies: PRAutoBlogger_Prompt_Registry(_Writer), get_option.
+ *
+ * @see class-activator.php                       — Sole caller.
+ * @see core/class-prompt-registry-writer.php     — seed_v1() implementation.
+ * @see includes/class-migrate-remove-cloudflare-v0100.php — Pattern precedent.
+ */
+class PRAutoBlogger_Migrate_Prompt_Seed_V0180 {
+
+	/** Option flag marking the seed as complete. */
+	private const FLAG = 'prautoblogger_migrated_prompt_seed_v0180';
+
+	/**
+	 * Run the seed once.
+	 *
+	 * Side effects: up to 12 INSERTs into the prompts table, one INFO log
+	 * line, one option write.
+	 *
+	 * @return void
+	 */
+	public static function run(): void {
+		if ( get_option( self::FLAG ) ) {
+			return;
+		}
+		if ( ! PRAutoBlogger_Prompt_Registry::is_available() ) {
+			return; // Table missing — retry on the next migration pass.
+		}
+
+		$seeded = PRAutoBlogger_Prompt_Registry_Writer::seed_v1( 'seed:v0.18.0' );
+
+		if ( class_exists( 'PRAutoBlogger_Logger', false ) ) {
+			PRAutoBlogger_Logger::instance()->info(
+				sprintf( 'Prompt registry seeded: %d key(s) written as v1.', $seeded ),
+				'activator'
+			);
+		}
+
+		update_option( self::FLAG, '1' );
+	}
+}

includes/class-migrate-remove-cloudflare-v0100.php

@@ -0,0 +1,101 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * One-shot v0.10.0 migration — remove Cloudflare Workers AI as image provider.
+ *
+ * Cloudflare Workers AI was removed as an image provider in v0.10.0.
+ * Runware FLUX.1 schnell is 65× cheaper at equivalent quality, so any user
+ * still on a `cloudflare` provider must be migrated off — otherwise the
+ * image pipeline throws "no provider for id cloudflare" at the first
+ * generation run after upgrade.
+ *
+ * Split out of class-activator.php so that file stays under the 300-line
+ * cap. The activator's maybe_run_db_migrations() delegates here.
+ *
+ * Triggered by: PRAutoBlogger::maybe_run_db_migrations() once per admin_init
+ *               until the `prautoblogger_migrated_remove_cloudflare_v0100`
+ *               flag is set.
+ * Dependencies: PRAutoBlogger_Image_Model_Registry::provider_for() for
+ *               current-model provider derivation.
+ *
+ * @see class-activator.php                 — Parallel v0.9.0 migration.
+ * @see class-prautoblogger.php             — Calls run() during admin_init.
+ * @see class-image-model-registry.php      — Provider derivation source.
+ * @see convo/prautoblogger/threads/2026-04-cloudflare-workers-ai-removal/
+ */
+class PRAutoBlogger_Migrate_Remove_Cloudflare_V0100 {
+
+	/**
+	 * Migration flag option key. Presence = already migrated.
+	 */
+	private const FLAG = 'prautoblogger_migrated_remove_cloudflare_v0100';
+
+	/**
+	 * Run the migration. Idempotent — second + later calls are no-ops.
+	 *
+	 * Side effects: may update `prautoblogger_image_model` +
+	 *               `prautoblogger_image_provider`; always deletes
+	 *               `prautoblogger_cloudflare_ai_token`,
+	 *               `prautoblogger_cloudflare_account_id`,
+	 *               `prautoblogger_cf_image_via_gateway`; sets the
+	 *               migration flag option.
+	 *
+	 * Explicitly does NOT touch `prautoblogger_ai_gateway_base_url` —
+	 * that option is shared with the OpenRouter AI Gateway route and
+	 * must stay intact.
+	 *
+	 * @return void
+	 */
+	public static function run(): void {
+		if ( get_option( self::FLAG ) ) {
+			return;
+		}
+
+		if ( self::is_user_on_cloudflare() ) {
+			// Closest equivalent — FLUX.1 schnell, Runware-hosted, ~$0.0006/image.
+			update_option( 'prautoblogger_image_model', 'runware:100@1' );
+			update_option( 'prautoblogger_image_provider', 'runware' );
+		}
+
+		// Clean up orphaned CF Workers AI credentials + the dead gateway toggle.
+		delete_option( 'prautoblogger_cloudflare_ai_token' );
+		delete_option( 'prautoblogger_cloudflare_account_id' );
+		delete_option( 'prautoblogger_cf_image_via_gateway' );
+
+		update_option( self::FLAG, '1' );
+	}
+
+	/**
+	 * Detect whether the site is currently configured to use Cloudflare
+	 * Workers AI for image generation.
+	 *
+	 * Because the v0.10.0 image-model registry no longer contains
+	 * Cloudflare entries, `provider_for()` returns '' for legacy
+	 * `flux-1-schnell` slugs. We therefore look at three signals and
+	 * treat any of them as "on Cloudflare":
+	 *   1. Current registry-derived provider === 'cloudflare'.
+	 *   2. The legacy `prautoblogger_image_provider` option is 'cloudflare'.
+	 *   3. The legacy CF-specific slug `flux-1-schnell` is still persisted
+	 *      as the image model (pre-registry-rename installs).
+	 *
+	 * @return bool
+	 */
+	private static function is_user_on_cloudflare(): bool {
+		$curr          = (string) get_option( 'prautoblogger_image_model', '' );
+		$curr_provider = PRAutoBlogger_Image_Model_Registry::provider_for( $curr );
+
+		if ( 'cloudflare' === $curr_provider ) {
+			return true;
+		}
+
+		$legacy_provider = (string) get_option( 'prautoblogger_image_provider', '' );
+		if ( 'cloudflare' === $legacy_provider ) {
+			return true;
+		}
+
+		return 'flux-1-schnell' === $curr;
+	}
+}

includes/class-pipeline-schema-installer.php

@@ -0,0 +1,147 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Creates / updates the Pipeline v2 substrate tables via `dbDelta` (db 1.2.0).
+ *
+ * What: Owns the five v0.18.0 substrate tables — the versioned prompt
+ *       registry (`prompts`), the audit child tables (`run_sources`,
+ *       `run_decisions`), and the run ledger / state machine tables
+ *       (`runs`, `run_stages`). Kept separate from the original
+ *       PRAutoBlogger_Schema_Installer so both classes stay under the
+ *       300-line cap and the v1.1.0 schema remains byte-stable.
+ * Who triggers it: PRAutoBlogger_Activator::activate() — on activation and
+ *       on every `prautoblogger_db_version` mismatch (self-healing
+ *       auto-migration via PRAutoBlogger::on_check_db_version()).
+ * Dependencies: WordPress $wpdb, dbDelta() from wp-admin/includes/upgrade.php.
+ *
+ * @see class-schema-installer.php      — v1.1.0 tables (source data, logs, scores).
+ * @see class-activator.php             — Sole caller.
+ * @see core/class-prompt-registry.php  — Reads/writes the prompts table.
+ * @see core/class-run-state.php        — Reads/writes runs + run_stages.
+ * @see ARCHITECTURE.md                 — Database schema section documents each table.
+ */
+class PRAutoBlogger_Pipeline_Schema_Installer {
+
+	/**
+	 * Create (or upgrade) the Pipeline v2 substrate tables.
+	 *
+	 * `dbDelta` is idempotent: it creates missing tables, adds missing
+	 * columns and indexes, and never drops anything — matching the
+	 * plugin's forward-only schema policy. Safe to re-run on every
+	 * version mismatch.
+	 *
+	 * Side effects: up to five CREATE TABLE / ALTER TABLE statements.
+	 *
+	 * @return void
+	 */
+	public static function install(): void {
+		global $wpdb;
+
+		$charset_collate = $wpdb->get_charset_collate();
+		$prefix          = $wpdb->prefix . 'prautoblogger_';
+
+		require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+
+		// Versioned prompt registry. Versions are immutable: writes create
+		// new (prompt_key, version) rows; exactly one row per key has
+		// active = 1. `prompt_key` (not `key`) because KEY is reserved SQL.
+		$sql_prompts = "CREATE TABLE {$prefix}prompts (
+			id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+			prompt_key VARCHAR(64) NOT NULL,
+			version INT UNSIGNED NOT NULL DEFAULT 1,
+			body LONGTEXT NOT NULL,
+			model VARCHAR(100) DEFAULT NULL,
+			params_json LONGTEXT DEFAULT NULL,
+			author VARCHAR(100) NOT NULL DEFAULT '',
+			created_at DATETIME NOT NULL,
+			active TINYINT(1) NOT NULL DEFAULT 0,
+			PRIMARY KEY (id),
+			UNIQUE KEY key_version (prompt_key, version),
+			KEY key_active (prompt_key, active)
+		) {$charset_collate};";
+
+		// Research-source audit rows: one row per source a run considered,
+		// with the keep/discard decision. Consolidates the old
+		// source_ids_json + _prautoblogger_research_sources scatter for
+		// new runs (no backfill of historical runs).
+		$sql_run_sources = "CREATE TABLE {$prefix}run_sources (
+			id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+			run_id VARCHAR(36) NOT NULL,
+			agent_role VARCHAR(50) NOT NULL DEFAULT '',
+			source_url VARCHAR(500) DEFAULT NULL,
+			doi VARCHAR(255) DEFAULT NULL,
+			kept TINYINT(1) NOT NULL DEFAULT 0,
+			reason TEXT DEFAULT NULL,
+			quality_score FLOAT DEFAULT NULL,
+			created_at DATETIME NOT NULL,
+			PRIMARY KEY (id),
+			KEY run_id (run_id)
+		) {$charset_collate};";
+
+		// Stage-decision audit rows: verdict + rationale per pipeline
+		// stage. citation_score is nullable until the Phase-2 editorial
+		// loop computes it.
+		$sql_run_decisions = "CREATE TABLE {$prefix}run_decisions (
+			id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+			run_id VARCHAR(36) NOT NULL,
+			stage VARCHAR(50) NOT NULL,
+			verdict VARCHAR(50) NOT NULL,
+			rationale TEXT DEFAULT NULL,
+			citation_score FLOAT DEFAULT NULL,
+			created_at DATETIME NOT NULL,
+			PRIMARY KEY (id),
+			KEY run_id (run_id)
+		) {$charset_collate};";
+
+		// Per-run ledger + lifecycle row. reserved/settled/ceiling drive the
+		// Cost_Governor's atomic reserve-before-call check; pinned_prompts_json
+		// freezes the prompt versions a run uses at start; status feeds the
+		// run state machine (pending|running|done|failed|halted).
+		$sql_runs = "CREATE TABLE {$prefix}runs (
+			run_id VARCHAR(36) NOT NULL,
+			status VARCHAR(20) NOT NULL DEFAULT 'pending',
+			ceiling_usd DECIMAL(10,6) NOT NULL DEFAULT 0,
+			reserved_usd DECIMAL(10,6) NOT NULL DEFAULT 0,
+			settled_usd DECIMAL(10,6) NOT NULL DEFAULT 0,
+			overage_usd DECIMAL(10,6) NOT NULL DEFAULT 0,
+			pinned_prompts_json LONGTEXT DEFAULT NULL,
+			started_at DATETIME NOT NULL,
+			updated_at DATETIME NOT NULL,
+			finished_at DATETIME DEFAULT NULL,
+			PRIMARY KEY (run_id),
+			KEY status (status)
+		) {$charset_collate};";
+
+		// Per-run per-stage state rows. The idempotency key is
+		// (run_id, stage, agent_role, item_key): agent_role is the Phase-2
+		// fan-out dimension (quorum members), item_key scopes article-level
+		// stages within multi-article runs ('' for run-level stages).
+		// meta_json holds the stage output for resume-without-recharge.
+		$sql_run_stages = "CREATE TABLE {$prefix}run_stages (
+			id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+			run_id VARCHAR(36) NOT NULL,
+			stage VARCHAR(50) NOT NULL,
+			agent_role VARCHAR(50) NOT NULL DEFAULT '',
+			item_key VARCHAR(64) NOT NULL DEFAULT '',
+			status VARCHAR(20) NOT NULL DEFAULT 'pending',
+			attempt SMALLINT UNSIGNED NOT NULL DEFAULT 1,
+			cost_usd DECIMAL(10,6) NOT NULL DEFAULT 0,
+			meta_json LONGTEXT DEFAULT NULL,
+			started_at DATETIME NOT NULL,
+			updated_at DATETIME NOT NULL,
+			finished_at DATETIME DEFAULT NULL,
+			PRIMARY KEY (id),
+			UNIQUE KEY run_stage_role_item (run_id, stage, agent_role, item_key),
+			KEY status_updated (status, updated_at)
+		) {$charset_collate};";
+
+		dbDelta( $sql_prompts );
+		dbDelta( $sql_run_sources );
+		dbDelta( $sql_run_decisions );
+		dbDelta( $sql_runs );
+		dbDelta( $sql_run_stages );
+	}
+}

includes/class-prautoblogger.php

@@ -2,6 +2,8 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Main orchestrator for the PRAutoBlogger plugin.
  *
  * Registers all WordPress hooks (actions and filters) and wires up dependencies.
@@ -9,139 +11,202 @@ declare(strict_types=1);
  * business logic, not hook registration.
  *
  * Triggered by: prautoblogger() singleton in prautoblogger.php, called on `plugins_loaded`.
- * Dependencies: All other plugin classes (loaded via autoloader), PRAutoBlogger_Pipeline_Runner.
+ * Dependencies: All other plugin classes (loaded via autoloader), PRAutoBlogger_Executor.
  *
- * @see prautoblogger.php                — Plugin bootstrap that instantiates this class.
- * @see core/class-pipeline-runner.php — Executes the generation pipeline.
- * @see ARCHITECTURE.md                — Data flow diagram showing how classes interact.
- * @see CONVENTIONS.md                 — Hook naming conventions.
+ * @see prautoblogger.php                     — Plugin bootstrap that instantiates this class.
+ * @see class-executor.php                    — Cron/AJAX handlers for generation, model registry.
+ * @see class-ajax-handlers.php               — Non-generation AJAX endpoints (images, models, test).
+ * @see class-generation-lock.php             — DB mutex for single-writer generation.
+ * @see core/class-pipeline-runner.php         — Executes the generation pipeline.
+ * @see ARCHITECTURE.md                        — Data flow diagram showing how classes interact.
+ * @see CONVENTIONS.md                         — Hook naming conventions.
  */
 class PRAutoBlogger {
 
-	/**
-	 * Whether the plugin has been initialized.
-	 */
 	private bool $initialized = false;
 
+	/** @var PRAutoBlogger_Executor Handles generation cron/AJAX, model registry. */
+	private PRAutoBlogger_Executor $executor;
+
+	/** @var PRAutoBlogger_Ajax_Handlers Handles non-generation AJAX (images, models, test). */
+	private PRAutoBlogger_Ajax_Handlers $ajax_handlers;
+
 	/**
 	 * Register all hooks and initialize the plugin.
-	 *
-	 * Called once on `plugins_loaded`. Idempotent — calling it twice is a no-op.
+	 * Called once on `plugins_loaded`. Idempotent.
 	 *
 	 * Side effects: registers WordPress actions and filters.
-	 *
-	 * @return void
 	 */
 	public function run(): void {
 		if ( $this->initialized ) {
 			return;
 		}
-		$this->initialized = true;
+		$this->initialized   = true;
+		$this->executor      = new PRAutoBlogger_Executor();
+		$this->ajax_handlers = new PRAutoBlogger_Ajax_Handlers( $this->executor->get_model_registry() );
 
-		// Check for database migrations on admin_init.
-		add_action( 'admin_init', [ $this, 'on_check_db_version' ] );
+		add_action( 'admin_init', array( $this, 'on_check_db_version' ) );
+		// v0.18.0: cron requests must also self-heal the schema — after a
+		// deploy, scheduled generation can run before any admin page load,
+		// and new-column inserts would silently fail on the old schema.
+		add_action( 'init', array( $this, 'on_check_db_version_for_cron' ) );
+		add_filter( 'cron_schedules', array( $this, 'filter_add_cron_schedules' ) );
 
-		// Register custom cron schedules.
-		add_filter( 'cron_schedules', [ $this, 'filter_add_cron_schedules' ] );
-
-		// Admin hooks — only load on admin pages.
 		if ( is_admin() ) {
 			$this->register_admin_hooks();
 		}
 
-		// Cron hooks — always registered so WP-Cron can fire them.
 		$this->register_cron_hooks();
-
-		// Frontend hooks — shortcode and REST API for public-facing widget.
 		$this->register_frontend_hooks();
-
-		// AJAX hooks — always registered so admin AJAX works.
 		$this->register_ajax_hooks();
+		$this->register_cli_hooks();
 
-		/**
-		 * Fires after PRAutoBlogger has finished registering all hooks.
-		 *
-		 * Useful for add-ons that need to hook into PRAutoBlogger's lifecycle.
-		 */
+		/** Fires after PRAutoBlogger has finished registering all hooks. */
 		do_action( 'prautoblogger_loaded' );
 	}
 
-	/**
-	 * Register admin-only hooks (settings page, notices, metabox, dashboard widget).
-	 *
-	 * @return void
-	 */
+	/** Register admin-only hooks (settings, notices, metabox, dashboard widget). */
 	private function register_admin_hooks(): void {
 		$admin_page = new PRAutoBlogger_Admin_Page();
-		add_action( 'admin_menu', [ $admin_page, 'on_register_menu' ] );
-		add_action( 'admin_init', [ $admin_page, 'on_register_settings' ] );
-		add_action( 'admin_enqueue_scripts', [ $admin_page, 'on_enqueue_assets' ] );
+		add_action( 'admin_menu', array( $admin_page, 'on_register_menu' ) );
+		add_action( 'admin_init', array( $admin_page, 'on_register_settings' ) );
+		add_action( 'admin_enqueue_scripts', array( $admin_page, 'on_enqueue_assets' ) );
 
-		$notices = new PRAutoBlogger_Admin_Notices();
-		add_action( 'admin_notices', [ $notices, 'on_display_notices' ] );
-
-		$metabox = new PRAutoBlogger_Post_Metabox();
-		add_action( 'add_meta_boxes', [ $metabox, 'on_register_metabox' ] );
-
-		$metrics_page = new PRAutoBlogger_Metrics_Page();
-		add_action( 'admin_menu', [ $metrics_page, 'on_register_menu' ] );
-
-		$dashboard_widget = new PRAutoBlogger_Dashboard_Widget();
-		add_action( 'wp_dashboard_setup', [ $dashboard_widget, 'on_register_widget' ] );
+		add_action( 'admin_notices', array( new PRAutoBlogger_Admin_Notices(), 'on_display_notices' ) );
+		add_action( 'add_meta_boxes', array( new PRAutoBlogger_Post_Metabox(), 'on_register_metabox' ) );
+		add_action( 'admin_menu', array( new PRAutoBlogger_Metrics_Page(), 'on_register_menu' ) );
+		add_action( 'wp_dashboard_setup', array( new PRAutoBlogger_Dashboard_Widget(), 'on_register_widget' ) );
 
 		$review_queue = new PRAutoBlogger_Review_Queue();
-		add_action( 'admin_menu', [ $review_queue, 'on_register_menu' ] );
+		add_action( 'admin_menu', array( $review_queue, 'on_register_menu' ) );
 
-		$log_viewer = new PRAutoBlogger_Log_Viewer();
-		add_action( 'admin_menu', [ $log_viewer, 'on_register_menu' ] );
+		$ideas_browser = new PRAutoBlogger_Ideas_Browser();
+		add_action( 'admin_menu', array( $ideas_browser, 'on_register_menu' ) );
+		add_action( 'admin_menu', array( new PRAutoBlogger_Log_Viewer(), 'on_register_menu' ) );
 
-		// Block false update notifications from wordpress.org — our plugin name
-		// collides with a different "PRAutoBlogger" in the plugin directory.
-		add_filter( 'site_transient_update_plugins', [ $this, 'filter_block_false_updates' ] );
+		( new PRAutoBlogger_Post_List_Columns() )->register();
+
+		// Block false update notifications — our slug collides with another plugin.
+		add_filter( 'site_transient_update_plugins', array( $this, 'filter_block_false_updates' ) );
 	}
 
-	/**
-	 * Register frontend hooks (shortcode and REST API for posts widget).
-	 *
-	 * The shortcode renders a mount-point div; the React component hydrates it
-	 * on the client side by fetching posts from the REST endpoint.
-	 *
-	 * @return void
-	 */
+	/** Register frontend hooks (shortcode, REST, typography). */
 	private function register_frontend_hooks(): void {
 		$posts_widget = new PRAutoBlogger_Posts_Widget();
-		add_action( 'init', [ $posts_widget, 'on_register_shortcode' ] );
-		add_action( 'rest_api_init', [ $posts_widget, 'on_register_rest_route' ] );
+		add_action( 'init', array( $posts_widget, 'on_register_shortcode' ) );
+		add_action( 'rest_api_init', array( $posts_widget, 'on_register_rest_route' ) );
+
+		$typography = new PRAutoBlogger_Article_Typography();
+		add_action( 'wp_head', array( $typography, 'on_wp_head' ) );
+		add_action( 'wp_enqueue_scripts', array( $typography, 'on_enqueue_fonts' ) );
+		add_filter( 'the_content', array( $typography, 'on_wrap_tables' ), 99 );
 	}
 
 	/** Register cron-triggered hooks for scheduled generation and metrics. */
 	private function register_cron_hooks(): void {
-		add_action( 'prautoblogger_daily_generation', [ $this, 'on_daily_generation' ] );
-		add_action( 'prautoblogger_collect_metrics', [ $this, 'on_collect_metrics' ] );
+		add_action( 'prautoblogger_daily_generation', array( $this->executor, 'on_daily_generation' ) );
+		add_action( 'prautoblogger_collect_metrics', array( $this->executor, 'on_collect_metrics' ) );
+
+		// Manual "Generate Now" runs as a one-shot cron event to avoid
+		// Hostinger's 120-second web-server connection timeout.
+		add_action( 'prautoblogger_manual_generation', array( $this->executor, 'on_manual_generation' ) );
+
+		// Chained article generation — each queued article fires as its own
+		// cron event so it gets a fresh PHP process and execution time budget.
+		add_action(
+			PRAutoBlogger_Pipeline_Runner::CRON_ACTION,
+			array( $this->executor, 'on_process_article_queue' )
+		);
+
+		$registry = $this->executor->get_model_registry();
+		add_action( 'prautoblogger_refresh_model_registry', array( $registry, 'refresh' ) );
+		// v0.15.0: daily Runware model catalog sync to keep the live model list fresh.
+		add_action( 'prautoblogger_sync_runware_models', array( new PRAutoBlogger_Runware_Model_Catalog(), 'sync' ) );
+
+		// Opik observability: async trace/span dispatch.
+		add_action(
+			'prautoblogger_opik_dispatch',
+			static function (): void {
+				if ( ! defined( 'PRAUTOBLOGGER_OPIK_API_KEY' ) || empty( PRAUTOBLOGGER_OPIK_API_KEY ) ) {
+					return;
+				}
+				$client = new PRAutoBlogger_Opik_Client(
+					PRAUTOBLOGGER_OPIK_API_KEY,
+					PRAUTOBLOGGER_OPIK_WORKSPACE,
+					PRAUTOBLOGGER_OPIK_URL_OVERRIDE
+				);
+				$queue = new PRAutoBlogger_Opik_Span_Queue();
+				$dispatcher = new PRAutoBlogger_Opik_Dispatcher( $client, $queue );
+				$dispatcher->dispatch();
+				update_option( 'prautoblogger_opik_last_dispatch', time() );
+			}
+		);
+
+		// Opik settings registration.
+		if ( is_admin() ) {
+			new PRAutoBlogger_Opik_Settings();
+		}
+
+		// Single-idea generation from the Ideas browser page.
+		add_action( 'prautoblogger_generate_from_idea', array( 'PRAutoBlogger_Ideas_Browser', 'on_cron_generate_from_idea' ) );
+
+		// v0.8.1: daily reaper for orphan `llm_research` rows (when a
+		// pipeline dies before amortize_research_costs runs).
+		add_action( 'prautoblogger_reap_orphan_research_rows', array( 'PRAutoBlogger_Research_Reaper', 'on_cron' ) );
+
+		// v0.18.0: stuck-run sweep + audit-payload retention rides the SAME
+		// existing daily cron (no new schedule). See class-run-reaper.php.
+		add_action( 'prautoblogger_reap_orphan_research_rows', array( 'PRAutoBlogger_Run_Reaper', 'on_cron' ) );
+
+		// v0.8.1: WP-CLI manual trigger for the reaper. Only registers when
+		// WP-CLI is present; no-op in normal HTTP requests.
+		if ( defined( 'WP_CLI' ) && WP_CLI ) {
+			\WP_CLI::add_command(
+				'prautoblogger reap-research',
+				static function (): void {
+					$stats = PRAutoBlogger_Research_Reaper::reap();
+					\WP_CLI::success(
+						sprintf(
+							'Reaped %d, deleted %d (stale), skipped %d.',
+							(int) $stats['reaped'],
+							(int) $stats['deleted'],
+							(int) $stats['skipped']
+						)
+					);
+				}
+			);
+		}
 	}
 
 	/** Register AJAX handlers for admin actions. */
 	private function register_ajax_hooks(): void {
-		add_action( 'wp_ajax_prautoblogger_generate_now', [ $this, 'on_ajax_generate_now' ] );
-		add_action( 'wp_ajax_prautoblogger_test_connection', [ $this, 'on_ajax_test_connection' ] );
+		// Generation AJAX (start + status polling) stays on executor.
+		add_action( 'wp_ajax_prautoblogger_generate_now', array( $this->executor, 'on_ajax_generate_now' ) );
+		add_action( 'wp_ajax_prautoblogger_generation_status', array( $this->executor, 'on_ajax_generation_status' ) );
+
+		// Non-generation AJAX (images, models, test) on dedicated handler.
+		add_action( 'wp_ajax_prautoblogger_generate_image', array( $this->ajax_handlers, 'on_ajax_generate_image' ) );
+		add_action( 'wp_ajax_prautoblogger_test_connection', array( $this->ajax_handlers, 'on_ajax_test_connection' ) );
+		add_action( 'wp_ajax_prautoblogger_get_models', array( $this->ajax_handlers, 'on_ajax_get_models' ) );
+		add_action( 'wp_ajax_prautoblogger_refresh_models', array( new PRAutoBlogger_Model_Registry_Refresh( $this->ajax_handlers->get_registry() ), 'handle' ) );
+		add_action( 'wp_ajax_prautoblogger_sync_runware_models_now', array( $this->ajax_handlers, 'on_ajax_sync_runware_models_now' ) );
 
 		$review_queue = new PRAutoBlogger_Review_Queue();
-		add_action( 'wp_ajax_prautoblogger_approve_post', [ $review_queue, 'on_ajax_approve_post' ] );
-		add_action( 'wp_ajax_prautoblogger_reject_post', [ $review_queue, 'on_ajax_reject_post' ] );
+		add_action( 'wp_ajax_prautoblogger_approve_post', array( $review_queue, 'on_ajax_approve_post' ) );
+		add_action( 'wp_ajax_prautoblogger_reject_post', array( $review_queue, 'on_ajax_reject_post' ) );
 
-		$log_viewer = new PRAutoBlogger_Log_Viewer();
-		add_action( 'wp_ajax_prautoblogger_clear_logs', [ $log_viewer, 'on_ajax_clear_logs' ] );
+		add_action( 'wp_ajax_prautoblogger_clear_logs', array( new PRAutoBlogger_Log_Viewer(), 'on_ajax_clear_logs' ) );
+
+		$ideas = new PRAutoBlogger_Ideas_Browser();
+		add_action( 'wp_ajax_prautoblogger_generate_from_idea', array( $ideas, 'on_ajax_generate_from_idea' ) );
+		add_action( 'wp_ajax_prautoblogger_idea_gen_status', array( $ideas, 'on_ajax_idea_gen_status' ) );
 	}
 
 	/**
 	 * Check if database needs migration after plugin update.
-	 *
-	 * Compares stored DB version with current PRAUTOBLOGGER_DB_VERSION.
-	 * If different, re-runs activation to apply schema changes via dbDelta.
+	 * Compares stored DB version with PRAUTOBLOGGER_DB_VERSION; re-runs activation if different.
 	 *
 	 * Side effects: may update database schema and db_version option.
-	 *
-	 * @return void
 	 */
 	public function on_check_db_version(): void {
 		$stored_version = get_option( 'prautoblogger_db_version', '0' );
@@ -157,15 +222,86 @@ class PRAutoBlogger {
 			update_option( 'prautoblogger_migrated_gemini_flash_lite', '1' );
 		}
 
-		// One-time migration: re-wrap existing encrypted values with "enc:" prefix
-		// to prevent the double-encryption bug permanently.
+		// One-time migration (v0.8.0): the admin no longer has an independent
+		// Image Provider dropdown; provider is derived from the image model on
+		// save. Auto-heal any existing site where the saved provider doesn't
+		// match the saved model's provider (the root cause of posts 650/657
+		// silently missing their featured image on 2026-04-20). Runs once.
+		if ( ! get_option( 'prautoblogger_migrated_image_provider_v080' ) ) {
+			$saved_model = (string) get_option( 'prautoblogger_image_model', '' );
+			$provider    = PRAutoBlogger_Image_Model_Registry::provider_for( $saved_model );
+			if ( '' !== $provider ) {
+				update_option( 'prautoblogger_image_provider', $provider );
+			}
+			update_option( 'prautoblogger_migrated_image_provider_v080', '1' );
+		}
+
+		// One-time migration (v0.8.2): reschedule the daily-generation cron in
+		// the site's configured timezone. Pre-v0.8.2 activator interpreted the
+		// admin "Generation Time" input as UTC; after v0.8.2 it honours the
+		// site timezone. Clears the stale UTC-scheduled event and re-queues
+		// using the timezone-aware helper. See class-activator.php.
+		PRAutoBlogger_Activator::reschedule_daily_in_site_timezone_v082();
+
+		// One-time migration (v3): switch to single-panel newspaper comic style.
+		// Replaces both the old infomercial pastiche and the short-lived premium
+		// photography style. Force-update unless the user has a truly custom value.
+		if ( ! get_option( 'prautoblogger_migrated_style_suffix_v3' ) ) {
+			$known_old_prefixes = array(
+				'Style: a screengrab from a 1995',       // v1: infomercial.
+				'Style: premium scientific lifestyle',    // v2: photography.
+			);
+			$current            = get_option( 'prautoblogger_image_style_suffix', '' );
+			$is_old             = ( '' === $current );
+			foreach ( $known_old_prefixes as $prefix ) {
+				if ( false !== strpos( $current, $prefix ) ) {
+					$is_old = true;
+					break;
+				}
+			}
+			if ( $is_old ) {
+				update_option( 'prautoblogger_image_style_suffix', PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_SUFFIX );
+			}
+			update_option( 'prautoblogger_migrated_style_suffix_v3', '1' );
+		}
+		// One-time migration (v4): remove caption-in-image instruction from style suffix.
+		// Captions are now inserted as HTML below the image, not baked into the image.
+		if ( ! get_option( 'prautoblogger_migrated_style_suffix_v4' ) ) {
+			$current = get_option( 'prautoblogger_image_style_suffix', '' );
+			// Detect v3 style suffix (contains "caption text" instruction).
+			if ( false !== strpos( $current, 'caption text in a clean sans-serif font below the panel' ) ) {
+				update_option( 'prautoblogger_image_style_suffix', PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_SUFFIX );
+			}
+			update_option( 'prautoblogger_migrated_style_suffix_v4', '1' );
+		}
+
+		// One-time migration (v0.16.0): editorial pivot. The comic Style Suffix
+		// is replaced by the editorial Style Template. Mirror the old suffix
+		// value into a deprecated-keyed option for one version cycle (so a
+		// customised value is recoverable / auditable) and seed the new
+		// template with its editorial default. The old option is intentionally
+		// NOT deleted this cycle. See docs/proposals/2026-05-29-image-pipeline-in-plugin-brief.md §8 Commit 1.
+		if ( ! get_option( 'prautoblogger_migrated_style_template_v0160' ) ) {
+			$old_suffix = get_option( 'prautoblogger_image_style_suffix', '' );
+			if ( '' !== $old_suffix && false === get_option( 'prautoblogger_image_style_suffix_deprecated', false ) ) {
+				update_option( 'prautoblogger_image_style_suffix_deprecated', $old_suffix );
+			}
+			// Only seed the new template if the admin has not already set one.
+			if ( '' === (string) get_option( 'prautoblogger_image_style_template', '' ) ) {
+				update_option( 'prautoblogger_image_style_template', PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_TEMPLATE );
+			}
+			update_option( 'prautoblogger_migrated_style_template_v0160', '1' );
+		}
+
+		// v0.9.0 — Runware as default image model. v0.10.0 — remove CF Workers AI.
+		PRAutoBlogger_Activator::migrate_default_image_v090();
+		PRAutoBlogger_Migrate_Remove_Cloudflare_V0100::run();
+
+		// One-time migration: re-wrap existing encrypted values with "enc:" prefix.
 		if ( ! get_option( 'prautoblogger_migrated_enc_prefix' ) ) {
-			$enc_options = [ 'prautoblogger_openrouter_api_key', 'prautoblogger_ga4_credentials_json' ];
+			$enc_options = array( 'prautoblogger_openrouter_api_key', 'prautoblogger_ga4_credentials_json', 'prautoblogger_runware_api_key' );
 			foreach ( $enc_options as $opt ) {
 				$val = get_option( $opt, '' );
-				// If it has a value but no "enc:" prefix, it's a legacy encrypted value.
-				// Clear it — user must re-enter. We can't reliably tell if it's
-				// single or double encrypted, so a fresh entry is safest.
 				if ( '' !== $val && ! PRAutoBlogger_Encryption::is_encrypted( $val ) ) {
 					delete_option( $opt );
 				}
@@ -174,204 +310,78 @@ class PRAutoBlogger {
 		}
 	}
 
+	/**
+	 * Run the db-version check on cron requests (admin_init never fires
+	 * there). Gated to wp_doing_cron() so normal frontend requests pay
+	 * nothing beyond one autoloaded option read.
+	 *
+	 * Side effects: may run the same migrations as on_check_db_version().
+	 *
+	 * @return void
+	 */
+	public function on_check_db_version_for_cron(): void {
+		if ( function_exists( 'wp_doing_cron' ) && wp_doing_cron() ) {
+			$this->on_check_db_version();
+		}
+	}
+
 	/**
 	 * Add custom cron schedules (six-hourly for metrics collection).
 	 *
 	 * @param array<string, array{interval: int, display: string}> $schedules Existing schedules.
-	 *
-	 * @return array<string, array{interval: int, display: string}> Modified schedules.
+	 * @return array<string, array{interval: int, display: string}>
 	 */
 	public function filter_add_cron_schedules( array $schedules ): array {
-		$schedules['prautoblogger_six_hours'] = [
+		$schedules['prautoblogger_six_hours'] = array(
 			'interval' => 6 * HOUR_IN_SECONDS,
 			'display'  => __( 'Every Six Hours', 'prautoblogger' ),
-		];
+		);
 		return $schedules;
 	}
 
+	/** Register WP-CLI commands. */
+	private function register_cli_hooks(): void {
+		PRAutoBlogger_WP_CLI_Commands::register();
+	}
+
 	/**
 	 * Block false update notifications from wordpress.org.
-	 *
 	 * Our plugin slug may collide with a different plugin in the directory.
-	 * This filter removes any update notice that wordpress.org might push
-	 * for our plugin basename, since we manage updates via our own CI/CD.
 	 *
 	 * @param object $transient The update_plugins transient data.
-	 *
-	 * @return object Modified transient with our plugin removed from updates.
+	 * @return object Modified transient.
 	 */
 	public function filter_block_false_updates( $transient ) {
-		$plugin_basename = PRAUTOBLOGGER_PLUGIN_BASENAME;
-		if ( isset( $transient->response[ $plugin_basename ] ) ) {
-			unset( $transient->response[ $plugin_basename ] );
+		if ( isset( $transient->response[ PRAUTOBLOGGER_PLUGIN_BASENAME ] ) ) {
+			unset( $transient->response[ PRAUTOBLOGGER_PLUGIN_BASENAME ] );
 		}
 		return $transient;
 	}
 
-	/**
-	 * Handle the daily generation cron event.
-	 *
-	 * Uses a database-level atomic mutex to prevent overlapping runs.
-	 *
-	 * Side effects: API calls, database writes, WordPress post creation.
-	 *
-	 * @return void
-	 */
+	/** Expose the executor for external access (e.g., model registry). */
+	public function get_executor(): PRAutoBlogger_Executor {
+		return $this->executor;
+	}
+
+	// ── Backward-compatible proxies ──
+
+	/** @see PRAutoBlogger_Executor::on_daily_generation() */
 	public function on_daily_generation(): void {
-		if ( ! $this->acquire_generation_lock() ) {
-			PRAutoBlogger_Logger::instance()->info( 'Daily generation skipped: already running (lock held).', 'scheduler' );
-			return;
-		}
+		$this->executor->on_daily_generation(); }
 
-		try {
-			( new PRAutoBlogger_Pipeline_Runner() )->run();
-		} catch ( \Exception $e ) {
-			PRAutoBlogger_Logger::instance()->error( 'Daily generation FAILED: ' . $e->getMessage(), 'scheduler' );
-		} finally {
-			$this->release_generation_lock();
-		}
-	}
-
-	/**
-	 * Handle the metrics collection cron event.
-	 *
-	 * Side effects: API calls to GA4, database writes to ab_content_scores.
-	 *
-	 * @return void
-	 */
+	/** @see PRAutoBlogger_Executor::on_collect_metrics() */
 	public function on_collect_metrics(): void {
-		try {
-			$metrics = new PRAutoBlogger_Metrics_Collector();
-			$metrics->collect_all();
-		} catch ( \Exception $e ) {
-			PRAutoBlogger_Logger::instance()->error( 'Metrics collection FAILED: ' . $e->getMessage(), 'metrics' );
-		}
-	}
+		$this->executor->on_collect_metrics(); }
 
-	/**
-	 * AJAX handler: trigger manual generation.
-	 *
-	 * Verifies nonce and capability, then runs the generation pipeline.
-	 * Uses the same atomic DB lock as the cron handler.
-	 *
-	 * Side effects: API calls, database writes, WordPress post creation.
-	 *
-	 * @return void
-	 */
+	/** @see PRAutoBlogger_Executor::on_ajax_generate_now() */
 	public function on_ajax_generate_now(): void {
-		check_ajax_referer( 'prautoblogger_generate_now', 'nonce' );
+		$this->executor->on_ajax_generate_now(); }
 
-		if ( ! current_user_can( 'manage_options' ) ) {
-			wp_send_json_error( [ 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ], 403 );
-			return;
-		}
-
-		// LLM API calls can take 30-60+ seconds each. Extend PHP's execution
-		// limit so the pipeline isn't killed mid-generation. This may be
-		// blocked by Hostinger's hardcoded limits, but it's worth trying.
-		// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
-		@set_time_limit( 300 );
-
-		// Allow admins to force-clear a stale lock.
-		$force = isset( $_POST['force'] ) && '1' === $_POST['force'];
-		if ( $force ) {
-			$this->release_generation_lock();
-		}
-
-		if ( ! $this->acquire_generation_lock() ) {
-			wp_send_json_error( [ 'message' => __( 'A generation run is already in progress. Pass force=1 to clear the lock.', 'prautoblogger' ) ] );
-			return;
-		}
-
-		try {
-			// Manual runs skip dedup so "Generate Now" always produces content
-			// even when a related article was recently published.
-			$results = ( new PRAutoBlogger_Pipeline_Runner() )
-				->set_skip_dedup( true )
-				->run();
-			wp_send_json_success( $results );
-		} catch ( \Exception $e ) {
-			PRAutoBlogger_Logger::instance()->error( 'Manual generation FAILED: ' . $e->getMessage(), 'pipeline' );
-			wp_send_json_error( [ 'message' => $e->getMessage() ] );
-		} finally {
-			$this->release_generation_lock();
-		}
-	}
-
-	/** AJAX handler: test API connections (OpenRouter, Reddit). */
+	/** @see PRAutoBlogger_Ajax_Handlers::on_ajax_test_connection() */
 	public function on_ajax_test_connection(): void {
-		check_ajax_referer( 'prautoblogger_test_connection', 'nonce' );
-		if ( ! current_user_can( 'manage_options' ) ) {
-			wp_send_json_error( [ 'message' => __( 'Insufficient permissions.', 'prautoblogger' ) ], 403 );
-			return;
-		}
-
-		$service = isset( $_POST['service'] ) ? sanitize_text_field( wp_unslash( $_POST['service'] ) ) : '';
-		$results = [];
-
-		if ( 'openrouter' === $service || 'all' === $service ) {
-			$llm                   = new PRAutoBlogger_OpenRouter_Provider();
-			$results['openrouter'] = $llm->validate_credentials_detailed();
-		}
-		if ( 'reddit' === $service || 'all' === $service ) {
-			$reddit  = new PRAutoBlogger_Reddit_Provider();
-			$is_ok   = $reddit->validate_credentials();
-			$results['reddit'] = $is_ok
-				? [ 'status' => 'ok', 'message' => __( 'Reddit source available (RSS primary, .json fallback).', 'prautoblogger' ) ]
-				: [ 'status' => 'error', 'message' => __( 'Reddit sources unreachable (both RSS and .json failed).', 'prautoblogger' ) ];
-		}
-		wp_send_json_success( $results );
-	}
-
-	/**
-	 * Acquire a database-level atomic mutex for generation.
-	 *
-	 * Uses INSERT IGNORE into wp_options — option_name has a UNIQUE index so only
-	 * one process can insert the row. Expired locks (>1 hour) are cleaned up first.
-	 *
-	 * @return bool True if lock acquired, false if another process holds it.
-	 */
-	private function acquire_generation_lock(): bool {
-		global $wpdb;
-
-		$lock_name = 'prautoblogger_generation_lock';
-		$now       = (string) time();
-
-		// Clean up expired locks older than 1 hour — prevents permanent deadlock.
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
-		$wpdb->query(
-			$wpdb->prepare(
-				"DELETE FROM {$wpdb->options} WHERE option_name = %s AND CAST(option_value AS UNSIGNED) < %d",
-				$lock_name,
-				time() - HOUR_IN_SECONDS
-			)
-		);
-
-		// Atomic insert — UNIQUE constraint on option_name guarantees only one process succeeds.
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-		$result = $wpdb->query(
-			$wpdb->prepare(
-				"INSERT IGNORE INTO {$wpdb->options} (option_name, option_value, autoload) VALUES (%s, %s, %s)",
-				$lock_name,
-				$now,
-				'no'
-			)
-		);
-
-		return $result > 0;
-	}
-
-	/** Release the generation mutex. */
-	private function release_generation_lock(): void {
-		global $wpdb;
-
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
-		$wpdb->query(
-			$wpdb->prepare(
-				"DELETE FROM {$wpdb->options} WHERE option_name = %s",
-				'prautoblogger_generation_lock'
-			)
-		);
-	}
+		$this->ajax_handlers->on_ajax_test_connection(); }
 
+	/** @see PRAutoBlogger_Executor::get_model_registry() */
+	public function get_model_registry(): PRAutoBlogger_OpenRouter_Model_Registry {
+		return $this->executor->get_model_registry(); }
 }

includes/class-schema-installer.php

@@ -0,0 +1,143 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Creates / updates the plugin's custom database tables via `dbDelta`.
+ *
+ * Extracted from `PRAutoBlogger_Activator` in v0.8.2 to keep that class
+ * under the 300-line cap once the timezone-aware cron migration landed.
+ * The Activator delegates to `install()` on activate and on db-version
+ * upgrade; schema definitions live here and only here.
+ *
+ * Triggered by: PRAutoBlogger_Activator::activate().
+ * Dependencies: WordPress $wpdb, dbDelta() from wp-admin/includes/upgrade.php.
+ *
+ * @see class-activator.php      — Sole caller; delegates on activate and db-version bump.
+ * @see ARCHITECTURE.md          — Data model section documents each table's purpose.
+ */
+class PRAutoBlogger_Schema_Installer {
+
+	/**
+	 * Create (or upgrade) all plugin tables.
+	 *
+	 * `dbDelta` is idempotent and will create new tables, add missing
+	 * columns on existing tables, and add missing indexes — but it will
+	 * not drop columns or indexes. That matches the plugin's forward-only
+	 * schema-migration policy.
+	 *
+	 * Side effects: up to five `CREATE TABLE` / `ALTER TABLE` statements.
+	 *
+	 * @return void
+	 */
+	public static function install(): void {
+		global $wpdb;
+
+		$charset_collate = $wpdb->get_charset_collate();
+		$prefix          = $wpdb->prefix . 'prautoblogger_';
+
+		require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+
+		// Source data — raw posts/comments from social platforms.
+		$sql_source_data = "CREATE TABLE {$prefix}source_data (
+			id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+			source_type VARCHAR(50) NOT NULL,
+			source_id VARCHAR(255) NOT NULL,
+			subreddit VARCHAR(255) DEFAULT NULL,
+			title TEXT DEFAULT NULL,
+			content LONGTEXT DEFAULT NULL,
+			author VARCHAR(255) DEFAULT NULL,
+			score INT DEFAULT 0,
+			comment_count INT DEFAULT 0,
+			permalink VARCHAR(500) DEFAULT NULL,
+			collected_at DATETIME NOT NULL,
+			metadata_json LONGTEXT DEFAULT NULL,
+			PRIMARY KEY (id),
+			UNIQUE KEY source_unique (source_type, source_id),
+			KEY source_collected (source_type, collected_at)
+		) {$charset_collate};";
+
+		// Analysis results — detected patterns from source data.
+		$sql_analysis = "CREATE TABLE {$prefix}analysis_results (
+			id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+			analysis_type VARCHAR(50) NOT NULL,
+			topic VARCHAR(500) NOT NULL,
+			summary TEXT DEFAULT NULL,
+			frequency INT DEFAULT 1,
+			relevance_score FLOAT DEFAULT 0,
+			source_ids_json LONGTEXT DEFAULT NULL,
+			analyzed_at DATETIME NOT NULL,
+			metadata_json LONGTEXT DEFAULT NULL,
+			PRIMARY KEY (id),
+			KEY type_relevance (analysis_type, relevance_score),
+			KEY analyzed_at (analyzed_at)
+		) {$charset_collate};";
+
+		// Generation log — every API call with cost tracking. `run_id`
+		// groups all entries from a single pipeline execution so
+		// `link_generation_logs()` can accurately attribute costs to a post.
+		// v0.18.0 adds the nullable audit columns `agent_role` and
+		// `prompt_version` (dbDelta adds them additively on upgrade;
+		// historical rows stay valid with NULL).
+		$sql_generation_log = "CREATE TABLE {$prefix}generation_log (
+			id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+			post_id BIGINT UNSIGNED DEFAULT NULL,
+			run_id VARCHAR(36) DEFAULT NULL,
+			stage VARCHAR(50) NOT NULL,
+			provider VARCHAR(50) NOT NULL,
+			model VARCHAR(100) NOT NULL,
+			prompt_tokens INT DEFAULT 0,
+			completion_tokens INT DEFAULT 0,
+			estimated_cost DECIMAL(10,6) DEFAULT 0,
+			request_json LONGTEXT DEFAULT NULL,
+			response_status VARCHAR(20) NOT NULL DEFAULT 'success',
+			error_message TEXT DEFAULT NULL,
+			agent_role VARCHAR(50) DEFAULT NULL,
+			prompt_version VARCHAR(20) DEFAULT NULL,
+			created_at DATETIME NOT NULL,
+			PRIMARY KEY (id),
+			KEY post_id (post_id),
+			KEY run_id (run_id),
+			KEY created_at (created_at),
+			KEY stage (stage)
+		) {$charset_collate};";
+
+		// Content scores — post performance metrics for self-improvement.
+		$sql_content_scores = "CREATE TABLE {$prefix}content_scores (
+			id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+			post_id BIGINT UNSIGNED NOT NULL,
+			pageviews INT DEFAULT 0,
+			avg_time_on_page FLOAT DEFAULT 0,
+			bounce_rate FLOAT DEFAULT 0,
+			comment_count INT DEFAULT 0,
+			composite_score FLOAT DEFAULT 0,
+			score_factors_json LONGTEXT DEFAULT NULL,
+			measured_at DATETIME NOT NULL,
+			PRIMARY KEY (id),
+			KEY post_id (post_id),
+			KEY measured_at (measured_at),
+			KEY composite_score (composite_score)
+		) {$charset_collate};";
+
+		// Event log — structured application log entries for the admin log viewer.
+		$sql_event_log = "CREATE TABLE {$prefix}event_log (
+			id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+			level VARCHAR(10) NOT NULL DEFAULT 'info',
+			context VARCHAR(100) DEFAULT NULL,
+			message TEXT NOT NULL,
+			meta_json LONGTEXT DEFAULT NULL,
+			created_at DATETIME NOT NULL,
+			PRIMARY KEY (id),
+			KEY level (level),
+			KEY created_at (created_at),
+			KEY level_created (level, created_at)
+		) {$charset_collate};";
+
+		dbDelta( $sql_source_data );
+		dbDelta( $sql_analysis );
+		dbDelta( $sql_generation_log );
+		dbDelta( $sql_content_scores );
+		dbDelta( $sql_event_log );
+	}
+}

includes/core/class-analysis-prompts.php

@@ -0,0 +1,146 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Prompt construction for the content analysis LLM call.
+ *
+ * What: Builds system and user prompts for source-data analysis, including
+ *       past-performance context for self-improvement feedback loops.
+ * Who calls it: PRAutoBlogger_Content_Analyzer::analyze_recent_data().
+ * Dependencies: PRAutoBlogger_Prompt_Registry (versioned prompt bodies),
+ *               WordPress $wpdb (for performance lookup), no external APIs.
+ *
+ * @see core/class-content-analyzer.php — Orchestrates analysis and calls these builders.
+ * @see ARCHITECTURE.md                 — Data flow step 2.
+ */
+class PRAutoBlogger_Analysis_Prompts {
+
+	/**
+	 * Build the system prompt for content analysis.
+	 *
+	 * @param string $niche               Niche description from settings.
+	 * @param string $performance_context  Past performance data summary.
+	 * @param int    $target_count         Number of ideas the LLM should produce.
+	 * @return string System prompt text.
+	 */
+	public static function build_system_prompt( string $niche, string $performance_context, int $target_count = 6 ): string {
+		// Blocks carry their own separators when non-empty so the rendered
+		// output is byte-identical to the historical concatenation.
+		$performance_block = '' !== $performance_context ? $performance_context . "\n\n" : '';
+
+		$recent_context = self::get_recent_articles_context();
+		$recent_block   = '' !== $recent_context ? $recent_context . "\n\n" : '';
+
+		$instructions       = trim( (string) get_option( 'prautoblogger_analysis_instructions', '' ) );
+		$instructions_block = '' !== $instructions ? "Additional instructions:\n" . $instructions . "\n\n" : '';
+
+		return PRAutoBlogger_Prompt_Registry::render(
+			'analysis.system',
+			array(
+				'niche_clause'          => '' !== $niche ? " in the {$niche} niche" : '',
+				'target_count'          => (string) $target_count,
+				'performance_block'     => $performance_block,
+				'recent_articles_block' => $recent_block,
+				'instructions_block'    => $instructions_block,
+			)
+		);
+	}
+
+	/**
+	 * Build the user prompt containing the actual source data.
+	 *
+	 * @param string $summary      Formatted source data summary.
+	 * @param int    $target_count Number of ideas requested.
+	 * @return string User prompt text.
+	 */
+	public static function build_user_prompt( string $summary, int $target_count = 6 ): string {
+		return PRAutoBlogger_Prompt_Registry::render(
+			'analysis.user',
+			array(
+				'target_count' => (string) $target_count,
+				'summary'      => $summary,
+			)
+		);
+	}
+
+	/**
+	 * Get past content performance data to feed into analysis for self-improvement.
+	 *
+	 * Side effects: database read.
+	 *
+	 * @return string Summary of what topics performed well, or empty string if no data.
+	 */
+	public static function get_performance_context(): string {
+		global $wpdb;
+		$scores_table = $wpdb->prefix . 'prautoblogger_content_scores';
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+		$top_posts = $wpdb->get_results(
+			"SELECT cs.post_id, cs.composite_score, p.post_title
+			FROM {$scores_table} cs
+			JOIN {$wpdb->posts} p ON p.ID = cs.post_id
+			WHERE cs.composite_score > 0
+			ORDER BY cs.composite_score DESC
+			LIMIT 5",
+			ARRAY_A
+		);
+
+		if ( empty( $top_posts ) ) {
+			return '';
+		}
+
+		$lines = array( 'Top performing past articles (learn from these):' );
+		foreach ( $top_posts as $post ) {
+			$lines[] = sprintf(
+				'- "%s" (score: %.1f)',
+				$post['post_title'],
+				(float) $post['composite_score']
+			);
+		}
+
+		return implode( "\n", $lines );
+	}
+
+	/**
+	 * Get titles of recently published articles so the LLM avoids repeating them.
+	 *
+	 * Fetches generated posts from the last 30 days. A wider window than the
+	 * scorer's 7-day dedup because the LLM is smart enough to find genuinely
+	 * new angles even on adjacent topics — we just need it to know what exists.
+	 *
+	 * Side effects: database read via WP_Query.
+	 *
+	 * @return string Formatted context block, or empty string if no recent articles.
+	 */
+	public static function get_recent_articles_context(): string {
+		$query = new \WP_Query(
+			array(
+				'post_type'      => 'post',
+				'post_status'    => array( 'publish', 'draft', 'pending' ),
+				'meta_key'       => '_prautoblogger_generated',
+				'meta_value'     => '1',
+				'date_query'     => array( array( 'after' => '30 days ago' ) ),
+				'posts_per_page' => 100,
+				'fields'         => 'ids',
+				'no_found_rows'  => true,
+			)
+		);
+
+		if ( empty( $query->posts ) ) {
+			return '';
+		}
+
+		$titles = array();
+		foreach ( $query->posts as $post_id ) {
+			$titles[] = '- "' . get_the_title( $post_id ) . '"';
+		}
+
+		$block  = 'IMPORTANT — Topics already covered (last 30 days). Do NOT suggest topics that overlap with these. ';
+		$block .= "Find genuinely NEW angles, questions, or subjects that are NOT already covered:\n";
+		$block .= implode( "\n", $titles );
+
+		return $block;
+	}
+}

includes/core/class-article-worker.php

@@ -0,0 +1,284 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Generates a single article: content → editorial review → publish/draft.
+ *
+ * Extracted from Pipeline_Runner so each chained cron job has a focused,
+ * single-responsibility worker. One worker = one article = one PHP process.
+ *
+ * v0.18.0: per-article stage state (run_stages, item-scoped) makes resume
+ * idempotent — an already-published item is skipped outright, a done
+ * review is reused from its snapshot, and the writer reuses done LLM
+ * stages via Content_Generator::set_run_item(). Editorial verdicts and
+ * the sources that fed the article are persisted to the audit tables.
+ *
+ * Triggered by: Pipeline_Runner (directly for article 1, via cron for 2..N).
+ * Dependencies: Content_Generator, Chief_Editor, Publisher, Cost_Tracker,
+ *               Run_Stage_State, Audit_Writer.
+ *
+ * Opik instrumentation: Initializes trace context at start, creates spans
+ * for content generation and editorial review. Feature-flag gated (default off).
+ *
+ * @see core/class-pipeline-runner.php — Orchestrates and dispatches workers.
+ * @see core/class-content-generator.php — LLM content generation.
+ * @see core/class-chief-editor.php      — Editorial quality gate.
+ * @see core/class-publisher.php         — WordPress post creation.
+ * @see services/opik/class-opik-trace-context.php — Opik tracing.
+ */
+class PRAutoBlogger_Article_Worker {
+
+	private PRAutoBlogger_Cost_Tracker $cost_tracker;
+
+	/**
+	 * @param PRAutoBlogger_Cost_Tracker $cost_tracker Shared cost tracker.
+	 */
+	public function __construct( PRAutoBlogger_Cost_Tracker $cost_tracker ) {
+		$this->cost_tracker = $cost_tracker;
+	}
+
+	/**
+	 * Generate one article from an idea.
+	 *
+	 * Runs the full single-article pipeline: LLM content generation →
+	 * editorial review → publish or save as draft.
+	 *
+	 * Initializes Opik trace context if enabled and tears it down at end.
+	 *
+	 * Side effects: LLM API calls, database writes, WordPress post creation,
+	 * image generation, cost logging, Opik span queuing.
+	 *
+	 * @param PRAutoBlogger_Article_Idea $idea The scored idea to generate from.
+	 *
+	 * @return array{generated: int, published: int, rejected: int, cost: float}
+	 */
+	public function generate( PRAutoBlogger_Article_Idea $idea ): array {
+		$run_id = (string) ( $this->cost_tracker->get_run_id() ?? '' );
+		$item   = PRAutoBlogger_Run_Stage_State::item_key_for_idea( $idea );
+
+		$result = array(
+			'generated' => 0,
+			'published' => 0,
+			'rejected'  => 0,
+			'cost'      => 0.0,
+		);
+
+		// Idempotent resume: this item already completed its publish stage
+		// in this run — re-dispatching it must not create a second post or
+		// charge a second cent.
+		if ( '' !== $run_id && PRAutoBlogger_Run_Stage_State::is_done( $run_id, 'publish', '', $item ) ) {
+			PRAutoBlogger_Logger::instance()->info(
+				sprintf( 'Skipping "%s" — already completed in run %s (idempotent resume).', $idea->get_topic(), $run_id ),
+				'pipeline'
+			);
+			return $result;
+		}
+
+		// Initialize Opik trace context for this article generation.
+		$opik = $this->should_trace_with_opik();
+		if ( $opik ) {
+			PRAutoBlogger_Opik_Trace_Context::current()->init_trace();
+		}
+
+		$llm       = new PRAutoBlogger_OpenRouter_Provider();
+		$generator = new PRAutoBlogger_Content_Generator( $llm, $this->cost_tracker );
+		$generator->set_run_item( '' !== $run_id ? $run_id : null, $item );
+		$editor    = new PRAutoBlogger_Chief_Editor( $llm, $this->cost_tracker );
+		$publisher = new PRAutoBlogger_Publisher();
+
+		$auto_publish = in_array(
+			get_option( 'prautoblogger_auto_publish', '0' ),
+			array( '1', 'yes' ),
+			true
+		);
+
+		try {
+			PRAutoBlogger_Pipeline_Status::broadcast( __( 'Generating article draft via AI…', 'prautoblogger' ) );
+			$content             = $generator->generate( $idea );
+			$result['generated'] = 1;
+
+			PRAutoBlogger_Pipeline_Status::broadcast( __( 'Running editorial pass…', 'prautoblogger' ) );
+			$review = $this->review_with_state( $editor, $content, $idea, $run_id, $item );
+
+			PRAutoBlogger_Pipeline_Status::broadcast( __( 'Saving and publishing…', 'prautoblogger' ) );
+			PRAutoBlogger_Run_Stage_State::start( $run_id, 'publish', (string) PRAutoBlogger_Stage_Display_Map::default_agent_role( 'publish' ), $item );
+			$this->publish_or_draft(
+				$content,
+				$idea,
+				$review,
+				$publisher,
+				$auto_publish,
+				$result
+			);
+			PRAutoBlogger_Run_Stage_State::done( $run_id, 'publish', '', $item );
+
+			PRAutoBlogger_Audit_Writer::record_idea_sources( $run_id, $idea );
+		} catch ( \Throwable $e ) {
+			if ( '' !== $run_id ) {
+				PRAutoBlogger_Run_Stage_State::fail_open_for_item( $run_id, $item );
+			}
+			PRAutoBlogger_Logger::instance()->error(
+				sprintf(
+					'Article generation %s for "%s": %s',
+					get_class( $e ),
+					$idea->get_topic(),
+					$e->getMessage()
+				),
+				'pipeline'
+			);
+		}
+
+		$result['cost'] = $this->cost_tracker->get_current_run_cost();
+
+		// Finalize and queue Opik trace if enabled.
+		if ( $opik ) {
+			$this->finalize_opik_trace();
+		}
+
+		return $result;
+	}
+
+	/**
+	 * Editorial review with stage state: a done review is reused from its
+	 * snapshot (never re-charged); a fresh review is checkpointed and its
+	 * verdict recorded to the run_decisions audit table.
+	 *
+	 * Side effects: run_stages upserts, one run_decisions insert, and —
+	 * when not resuming — one LLM call via Chief_Editor.
+	 *
+	 * @param PRAutoBlogger_Chief_Editor $editor  Editor agent.
+	 * @param string                     $content Generated HTML content.
+	 * @param PRAutoBlogger_Article_Idea $idea    The idea under review.
+	 * @param string                     $run_id  Run UUID ('' outside a run).
+	 * @param string                     $item    Stage item key for this idea.
+	 * @return PRAutoBlogger_Editorial_Review
+	 */
+	private function review_with_state(
+		PRAutoBlogger_Chief_Editor $editor,
+		string $content,
+		PRAutoBlogger_Article_Idea $idea,
+		string $run_id,
+		string $item
+	): PRAutoBlogger_Editorial_Review {
+		if ( '' !== $run_id ) {
+			$snapshot = PRAutoBlogger_Run_Stage_State::get_output( $run_id, 'review', '', $item );
+			if ( null !== $snapshot ) {
+				$data = json_decode( $snapshot, true );
+				if ( is_array( $data ) && isset( $data['verdict'] ) ) {
+					PRAutoBlogger_Logger::instance()->info(
+						sprintf( 'Reusing completed review for "%s" (idempotent resume).', $idea->get_topic() ),
+						'pipeline'
+					);
+					return new PRAutoBlogger_Editorial_Review( $data );
+				}
+			}
+			PRAutoBlogger_Run_Stage_State::start( $run_id, 'review', (string) PRAutoBlogger_Stage_Display_Map::default_agent_role( 'review' ), $item );
+		}
+
+		$review = $editor->review( $content, $idea );
+
+		if ( '' !== $run_id ) {
+			$snapshot = (string) wp_json_encode(
+				array(
+					'verdict'         => $review->get_verdict(),
+					'notes'           => $review->get_notes(),
+					'revised_content' => $review->get_revised_content(),
+					'quality_score'   => $review->get_quality_score(),
+					'seo_score'       => $review->get_seo_score(),
+					'issues'          => $review->get_issues(),
+				)
+			);
+			PRAutoBlogger_Run_Stage_State::done( $run_id, 'review', '', $item, $snapshot );
+			PRAutoBlogger_Audit_Writer::record_decision( $run_id, 'review', $review->get_verdict(), $review->get_notes() );
+		}
+
+		return $review;
+	}
+
+	/**
+	 * Publish approved content or save as draft.
+	 *
+	 * @param string                         $content      Generated HTML content.
+	 * @param PRAutoBlogger_Article_Idea     $idea         Source idea.
+	 * @param PRAutoBlogger_Editorial_Review $review       Editor verdict.
+	 * @param PRAutoBlogger_Publisher         $publisher    Publisher instance.
+	 * @param bool                           $auto_publish Whether to auto-publish.
+	 * @param array                          &$result      Result counters (by ref).
+	 */
+	private function publish_or_draft(
+		string $content,
+		PRAutoBlogger_Article_Idea $idea,
+		PRAutoBlogger_Editorial_Review $review,
+		PRAutoBlogger_Publisher $publisher,
+		bool $auto_publish,
+		array &$result
+	): void {
+		$verdict = $review->get_verdict();
+		$run_id  = $this->cost_tracker->get_run_id();
+
+		if ( 'approved' === $verdict || 'revised' === $verdict ) {
+			$final = 'revised' === $verdict
+				? ( $review->get_revised_content() ?? $content )
+				: $content;
+
+			if ( $auto_publish ) {
+				$publisher->publish( $final, $idea, $review, $run_id, $this->cost_tracker );
+				++$result['published'];
+			} else {
+				$publisher->save_as_draft( $final, $idea, $review, $run_id, $this->cost_tracker );
+			}
+		} else {
+			$publisher->save_as_draft( $content, $idea, $review, $run_id, $this->cost_tracker );
+			++$result['rejected'];
+			PRAutoBlogger_Logger::instance()->info(
+				'Article rejected by editor: ' . $idea->get_topic(),
+				'pipeline'
+			);
+		}
+	}
+
+	/**
+	 * Check if Opik tracing is enabled and has credentials.
+	 *
+	 * @return bool
+	 */
+	private function should_trace_with_opik(): bool {
+		if ( ! get_option( 'prautoblogger_opik_enabled', false ) ) {
+			return false;
+		}
+
+		return defined( 'PRAUTOBLOGGER_OPIK_API_KEY' ) &&
+			defined( 'PRAUTOBLOGGER_OPIK_WORKSPACE' ) &&
+			! empty( PRAUTOBLOGGER_OPIK_API_KEY ) &&
+			! empty( PRAUTOBLOGGER_OPIK_WORKSPACE );
+	}
+
+	/**
+	 * Finalize and queue the Opik trace.
+	 *
+	 * Dispatches trace to queue for async posting.
+	 */
+	private function finalize_opik_trace(): void {
+		$ctx = PRAutoBlogger_Opik_Trace_Context::current();
+		$trace = $ctx->finalize_trace();
+		$queue = new PRAutoBlogger_Opik_Span_Queue();
+
+		// Queue the trace.
+		$queue->enqueue( $trace, 'trace' );
+
+		// Queue all spans.
+		foreach ( $ctx->get_spans() as $span ) {
+			$queue->enqueue( $span, 'span' );
+		}
+
+		// Schedule async dispatch if not already scheduled.
+		if ( ! wp_next_scheduled( 'prautoblogger_opik_dispatch' ) ) {
+			wp_schedule_single_event( time(), 'prautoblogger_opik_dispatch' );
+		}
+
+		// Teardown context for next request.
+		PRAutoBlogger_Opik_Trace_Context::teardown();
+	}
+}

includes/core/class-audit-writer.php

@@ -0,0 +1,132 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Writes run-scoped audit rows: sources considered + stage decisions.
+ *
+ * What: Thin, self-healing insert layer over the v0.18.0 audit child
+ *       tables. `record_decision()` persists a stage verdict (Phase 1:
+ *       the chief editor's review verdict; Phase 2 adds curate/editorial/
+ *       seo decisions and citation_score). `record_idea_sources()`
+ *       consolidates which collected sources fed a generated article —
+ *       the run_sources replacement for the historical source_ids_json /
+ *       `_prautoblogger_research_sources` scatter — for NEW runs only (no
+ *       backfill). Every method no-ops when the tables are missing.
+ * Who triggers it: Article_Worker (decision after review, sources after
+ *       publish), Phase-2 agents.
+ * Dependencies: WordPress $wpdb, Run_State (availability probe pattern).
+ *
+ * @see core/class-article-worker.php — Phase-1 call sites.
+ * @see ARCHITECTURE.md #21           — Audit substrate design.
+ */
+class PRAutoBlogger_Audit_Writer {
+
+	/** @var bool|null Per-request "audit tables exist" probe result. */
+	private static ?bool $tables_ok = null;
+
+	/**
+	 * Whether the audit child tables exist. Cached per request; never throws.
+	 *
+	 * @return bool
+	 */
+	public static function is_available(): bool {
+		if ( null !== self::$tables_ok ) {
+			return self::$tables_ok;
+		}
+		global $wpdb;
+		if ( null === $wpdb ) {
+			return false; // Not cached: $wpdb may appear later in boot.
+		}
+		$table = $wpdb->prefix . 'prautoblogger_run_decisions';
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$found           = $wpdb->get_var( $wpdb->prepare( 'SHOW TABLES LIKE %s', $table ) );
+		self::$tables_ok = ( $found === $table );
+		return self::$tables_ok;
+	}
+
+	/**
+	 * Persist a stage decision for a run.
+	 *
+	 * @param string     $run_id         Run UUID.
+	 * @param string     $stage          Deciding stage (see Stage_Display_Map).
+	 * @param string     $verdict        e.g. 'approved', 'revised', 'rejected'.
+	 * @param string     $rationale      Why (editor notes, governor message, …).
+	 * @param float|null $citation_score Phase-2 citation score (null in Phase 1).
+	 * @return void
+	 */
+	public static function record_decision( string $run_id, string $stage, string $verdict, string $rationale = '', ?float $citation_score = null ): void {
+		if ( '' === $run_id || ! self::is_available() ) {
+			return;
+		}
+		global $wpdb;
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$wpdb->insert(
+			$wpdb->prefix . 'prautoblogger_run_decisions',
+			array(
+				'run_id'         => $run_id,
+				'stage'          => $stage,
+				'verdict'        => $verdict,
+				'rationale'      => $rationale,
+				'citation_score' => $citation_score,
+				'created_at'     => current_time( 'mysql' ),
+			)
+		);
+	}
+
+	/**
+	 * Record the collected sources that fed a generated article (kept = 1;
+	 * Phase-2 curation adds discard rows with reasons + quality scores).
+	 *
+	 * Resolves the idea's source_data ids to permalinks in one query.
+	 *
+	 * @param string                     $run_id Run UUID.
+	 * @param PRAutoBlogger_Article_Idea $idea   The generated idea.
+	 * @return void
+	 */
+	public static function record_idea_sources( string $run_id, PRAutoBlogger_Article_Idea $idea ): void {
+		if ( '' === $run_id || ! self::is_available() ) {
+			return;
+		}
+		$source_ids = array_filter( array_map( 'intval', $idea->get_source_ids() ) );
+		if ( empty( $source_ids ) ) {
+			return;
+		}
+
+		global $wpdb;
+		$source_table = $wpdb->prefix . 'prautoblogger_source_data';
+		$placeholders = implode( ',', array_fill( 0, count( $source_ids ), '%d' ) );
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching,WordPress.DB.PreparedSQL.NotPrepared
+		$rows = $wpdb->get_results(
+			// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- $placeholders is a fixed %d list.
+			$wpdb->prepare( "SELECT id, source_type, permalink FROM {$source_table} WHERE id IN ({$placeholders})", $source_ids ),
+			ARRAY_A
+		);
+		if ( ! is_array( $rows ) ) {
+			return;
+		}
+
+		foreach ( $rows as $row ) {
+			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+			$wpdb->insert(
+				$wpdb->prefix . 'prautoblogger_run_sources',
+				array(
+					'run_id'        => $run_id,
+					'agent_role'    => 'analyst',
+					'source_url'    => (string) ( $row['permalink'] ?? '' ),
+					'doi'           => null,
+					'kept'          => 1,
+					'reason'        => sprintf( 'Cited by analyzer for "%s" (%s #%d)', $idea->get_topic(), (string) $row['source_type'], (int) $row['id'] ),
+					'quality_score' => null,
+					'created_at'    => current_time( 'mysql' ),
+				)
+			);
+		}
+	}
+
+	/** Reset per-request caches (tests). */
+	public static function flush_cache(): void {
+		self::$tables_ok = null;
+	}
+}

includes/core/class-chief-editor.php

@@ -2,18 +2,14 @@
 declare(strict_types=1);
 
 /**
- * Chief Editor agent — LLM-powered editorial review of generated content.
+ * Chief Editor agent — LLM-powered editorial review.
  *
- * Reviews articles for quality, accuracy, SEO, and tone before publishing.
- * Can approve, request revisions (and produce them), or reject content.
- * Rejected content is saved as a draft for human review.
+ * Reviews generated articles for quality, accuracy, SEO, tone.
+ * Approves, requests revisions, or rejects content.
+ * Opik instrumentation: spans per review LLM call.
  *
- * Triggered by: PRAutoBlogger::run_generation_pipeline() (step 5).
- * Dependencies: LLM_Provider_Interface, Cost_Tracker.
- *
- * @see core/class-content-generator.php — Produces the content we review.
- * @see core/class-publisher.php         — Publishes approved content.
- * @see ARCHITECTURE.md                  — Data flow step 5.
+ * Triggered by: PRAutoBlogger_Article_Worker.
+ * Dependencies: LLM_Provider_Interface, Cost_Tracker, Prompt_Registry.
  */
 class PRAutoBlogger_Chief_Editor {
 
@@ -31,15 +27,8 @@ class PRAutoBlogger_Chief_Editor {
 	/**
 	 * Review generated content and return an editorial verdict.
 	 *
-	 * The editor evaluates: content quality, factual tone, SEO elements,
-	 * readability, and alignment with the article idea. It can approve,
-	 * revise (and return revised content), or reject.
-	 *
-	 * Side effects: LLM API call(s), cost logging.
-	 *
 	 * @param string                     $content The generated HTML content.
-	 * @param PRAutoBlogger_Article_Idea   $idea    The original article idea.
-	 *
+	 * @param PRAutoBlogger_Article_Idea $idea    The original article idea.
 	 * @return PRAutoBlogger_Editorial_Review
 	 */
 	public function review( string $content, PRAutoBlogger_Article_Idea $idea ): PRAutoBlogger_Editorial_Review {
@@ -49,17 +38,45 @@ class PRAutoBlogger_Chief_Editor {
 		$system_prompt = $this->build_system_prompt( $niche );
 		$user_prompt   = $this->build_review_prompt( $content, $idea );
 
+		$ctx = PRAutoBlogger_Opik_Trace_Context::current();
+		$span_id = $ctx->start_span(
+			array(
+				'name'     => 'editorial_review',
+				'type'     => 'llm',
+				'model'    => $model,
+				'provider' => 'openrouter',
+			)
+		);
+
 		$response = $this->llm->send_chat_completion(
-			[
-				[ 'role' => 'system', 'content' => $system_prompt ],
-				[ 'role' => 'user', 'content' => $user_prompt ],
-			],
+			array(
+				array(
+					'role'    => 'system',
+					'content' => $system_prompt,
+				),
+				array(
+					'role'    => 'user',
+					'content' => $user_prompt,
+				),
+			),
 			$model,
-			[
+			array(
 				'temperature'     => 0.3,
 				'max_tokens'      => 5000,
-				'response_format' => [ 'type' => 'json_object' ],
-			]
+				'response_format' => array( 'type' => 'json_object' ),
+				'stage'           => 'review',
+			)
+		);
+
+		$ctx->end_span(
+			$span_id,
+			array(
+				'usage' => array(
+					'prompt_tokens'     => $response['prompt_tokens'],
+					'completion_tokens' => $response['completion_tokens'],
+					'total_tokens'      => $response['prompt_tokens'] + $response['completion_tokens'],
+				),
+			)
 		);
 
 		$this->cost_tracker->log_api_call(
@@ -75,101 +92,87 @@ class PRAutoBlogger_Chief_Editor {
 	}
 
 	/**
-	 * @param string $niche
+	 * Build system prompt for editorial review.
 	 *
-	 * @return string
+	 * v0.18.0: renders from the versioned registry ('editor.system') with a
+	 * byte-identical in-code fallback; the admin's extra editor
+	 * instructions stay a setting and are injected as a token value.
+	 *
+	 * @param string $niche Niche description from settings.
+	 * @return string System prompt text.
 	 */
 	private function build_system_prompt( string $niche ): string {
-		$prompt = "You are a senior blog editor";
-		if ( '' !== $niche ) {
-			$prompt .= " specializing in {$niche} content";
-		}
-		$prompt .= ". Your job is to review article drafts before publication.\n\n";
+		$instructions       = trim( (string) get_option( 'prautoblogger_editor_instructions', '' ) );
+		$instructions_block = '' !== $instructions ? "\nAdditional instructions:\n" . $instructions . "\n" : '';
 
-		$prompt .= "Evaluate the article on:\n";
-		$prompt .= "1. QUALITY: Is the writing clear, engaging, and well-structured?\n";
-		$prompt .= "2. ACCURACY: Does the content avoid making unsupported health/medical claims? Is the tone appropriately cautious for the topic?\n";
-		$prompt .= "3. SEO: Are headings properly structured? Are target keywords naturally used?\n";
-		$prompt .= "4. COMPLETENESS: Does it cover the key points? Does it have a proper intro and conclusion?\n";
-		$prompt .= "5. READABILITY: Is sentence variety good? Are paragraphs appropriate length?\n\n";
-
-		$prompt .= "You must respond with JSON in this format:\n";
-		$prompt .= "{\n";
-		$prompt .= '  "verdict": "approved" | "revised" | "rejected",' . "\n";
-		$prompt .= '  "quality_score": 0.0-1.0,' . "\n";
-		$prompt .= '  "seo_score": 0.0-1.0,' . "\n";
-		$prompt .= '  "issues": ["issue 1", "issue 2"],' . "\n";
-		$prompt .= '  "notes": "Brief editorial notes",' . "\n";
-		$prompt .= '  "revised_content": "Full revised HTML if verdict is revised, null otherwise"' . "\n";
-		$prompt .= "}\n\n";
-
-		$prompt .= "Rules:\n";
-		$prompt .= "- APPROVE if quality_score >= 0.7 and seo_score >= 0.6 and no critical issues\n";
-		$prompt .= "- REVISE if fixable issues exist — you MUST provide the full revised HTML\n";
-		$prompt .= "- REJECT only if the content is fundamentally flawed or off-topic\n";
-		$prompt .= "- When revising, fix the issues yourself. Don't just describe them.\n";
-
-		return $prompt;
-	}
-
-	/**
-	 * @param string                     $content
-	 * @param PRAutoBlogger_Article_Idea   $idea
-	 *
-	 * @return string
-	 */
-	private function build_review_prompt( string $content, PRAutoBlogger_Article_Idea $idea ): string {
-		return sprintf(
-			"Review this article draft:\n\n" .
-			"ORIGINAL BRIEF:\n" .
-			"- Title: %s\n" .
-			"- Topic: %s\n" .
-			"- Type: %s\n" .
-			"- Key points: %s\n" .
-			"- Target keywords: %s\n\n" .
-			"ARTICLE CONTENT:\n%s",
-			$idea->get_suggested_title(),
-			$idea->get_topic(),
-			$idea->get_article_type(),
-			implode( ', ', $idea->get_key_points() ),
-			implode( ', ', $idea->get_target_keywords() ),
-			$content
+		return PRAutoBlogger_Prompt_Registry::render(
+			'editor.system',
+			array(
+				'niche_clause'       => '' !== $niche ? " specializing in {$niche} content" : '',
+				'instructions_block' => $instructions_block,
+			)
 		);
 	}
 
 	/**
-	 * Parse the LLM's editorial review response.
+	 * Build user prompt for editorial review.
 	 *
-	 * @param string $content JSON response from LLM.
+	 * v0.18.0: renders from the versioned registry ('editor.review').
 	 *
-	 * @return PRAutoBlogger_Editorial_Review
+	 * @param string                     $content The generated HTML content.
+	 * @param PRAutoBlogger_Article_Idea $idea    The original article idea.
+	 * @return string User prompt text.
+	 */
+	private function build_review_prompt( string $content, PRAutoBlogger_Article_Idea $idea ): string {
+		return PRAutoBlogger_Prompt_Registry::render(
+			'editor.review',
+			array(
+				'title'        => $idea->get_suggested_title(),
+				'topic'        => $idea->get_topic(),
+				'article_type' => $idea->get_article_type(),
+				'key_points'   => implode( ', ', $idea->get_key_points() ),
+				'keywords'     => implode( ', ', $idea->get_target_keywords() ),
+				'content'      => $content,
+			)
+		);
+	}
+
+	/**
+	 * Parse LLM editorial review response.
 	 */
 	private function parse_review_response( string $content ): PRAutoBlogger_Editorial_Review {
-		$data = json_decode( $content, true );
+		$data = PRAutoBlogger_Json_Extractor::decode( $content );
 
 		if ( ! is_array( $data ) || ! isset( $data['verdict'] ) ) {
-			PRAutoBlogger_Logger::instance()->error( 'Chief editor response was not valid JSON. Defaulting to rejected.', 'editor' );
-			return new PRAutoBlogger_Editorial_Review( [
-				'verdict'       => 'rejected',
-				'notes'         => 'Editor response could not be parsed.',
-				'quality_score' => 0.0,
-				'seo_score'     => 0.0,
-				'issues'        => [ 'Unparseable editor response' ],
-			] );
+			PRAutoBlogger_Logger::instance()->error(
+				'Chief editor response unparseable (first 200 chars): ' . mb_substr( $content, 0, 200 ),
+				'editor'
+			);
+			return new PRAutoBlogger_Editorial_Review(
+				array(
+					'verdict'       => 'rejected',
+					'notes'         => 'Editor response unparseable',
+					'quality_score' => 0.0,
+					'seo_score'     => 0.0,
+					'issues'        => array( 'Unparseable editor response' ),
+				)
+			);
 		}
 
 		$verdict = sanitize_text_field( $data['verdict'] ?? 'rejected' );
-		if ( ! in_array( $verdict, [ 'approved', 'revised', 'rejected' ], true ) ) {
+		if ( ! in_array( $verdict, array( 'approved', 'revised', 'rejected' ), true ) ) {
 			$verdict = 'rejected';
 		}
 
-		return new PRAutoBlogger_Editorial_Review( [
-			'verdict'          => $verdict,
-			'notes'            => sanitize_textarea_field( $data['notes'] ?? '' ),
-			'revised_content'  => isset( $data['revised_content'] ) ? wp_kses_post( $data['revised_content'] ) : null,
-			'quality_score'    => (float) ( $data['quality_score'] ?? 0.0 ),
-			'seo_score'        => (float) ( $data['seo_score'] ?? 0.0 ),
-			'issues'           => array_map( 'sanitize_text_field', $data['issues'] ?? [] ),
-		] );
+		return new PRAutoBlogger_Editorial_Review(
+			array(
+				'verdict'         => $verdict,
+				'notes'           => sanitize_textarea_field( $data['notes'] ?? '' ),
+				'revised_content' => isset( $data['revised_content'] ) ? wp_kses_post( $data['revised_content'] ) : null,
+				'quality_score'   => (float) ( $data['quality_score'] ?? 0.0 ),
+				'seo_score'       => (float) ( $data['seo_score'] ?? 0.0 ),
+				'issues'          => array_map( 'sanitize_text_field', $data['issues'] ?? array() ),
+			)
+		);
 	}
 }

includes/core/class-content-analyzer.php

@@ -2,19 +2,24 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Analyzes collected source data using an LLM to detect recurring patterns:
  * questions people ask, complaints/pain points, and product comparisons.
  *
  * Uses a cheap model (configurable) to keep analysis costs low.
  * Batches source data into manageable chunks for the LLM context window.
+ * Prompt construction is delegated to PRAutoBlogger_Analysis_Prompts.
  *
  * Triggered by: PRAutoBlogger::run_generation_pipeline() (step 2).
- * Dependencies: LLM_Provider_Interface, Cost_Tracker, WordPress $wpdb.
+ * Dependencies: LLM_Provider_Interface, Cost_Tracker, PRAutoBlogger_Analysis_Prompts, WordPress $wpdb.
  *
- * @see providers/interface-llm-provider.php — LLM used for analysis.
- * @see core/class-cost-tracker.php          — Logs API costs.
- * @see core/class-idea-scorer.php           — Consumes analysis results.
- * @see ARCHITECTURE.md                      — Data flow step 2.
+ * @see core/class-analysis-prompts.php       — System/user prompt builders + performance context.
+ * @see providers/interface-llm-provider.php  — LLM used for analysis.
+ * @see core/class-cost-tracker.php           — Logs API costs.
+ * @see core/class-json-extractor.php         — Tolerant JSON parsing for LLM output.
+ * @see core/class-idea-scorer.php            — Consumes analysis results.
+ * @see ARCHITECTURE.md                       — Data flow step 2.
  */
 class PRAutoBlogger_Content_Analyzer {
 
@@ -37,46 +42,46 @@ class PRAutoBlogger_Content_Analyzer {
 	 *
 	 * Side effects: LLM API call, database reads/writes.
 	 *
-	 * @return PRAutoBlogger_Analysis_Result[] Detected patterns.
-	 */
-	/**
 	 * @param int $target_idea_count How many distinct topic ideas the LLM should produce.
 	 *                               Defaults to 6 so the scorer has enough to pick from.
+	 * @return PRAutoBlogger_Analysis_Result[] Detected patterns.
 	 */
 	public function analyze_recent_data( int $target_idea_count = 6 ): array {
 		$source_items = $this->fetch_recent_source_data();
 
 		if ( empty( $source_items ) ) {
 			PRAutoBlogger_Logger::instance()->info( 'No new source data to analyze.', 'analyzer' );
-			return [];
+			return array();
 		}
 
 		$niche = get_option( 'prautoblogger_niche_description', '' );
 		$model = get_option( 'prautoblogger_analysis_model', PRAUTOBLOGGER_DEFAULT_ANALYSIS_MODEL );
 
-		// Build the source data summary for the LLM (trim to avoid huge contexts).
-		$summary = $this->build_source_summary( $source_items );
-
-		// Include past performance data for self-improvement.
-		$performance_context = $this->get_performance_context();
-
-		$system_prompt = $this->build_system_prompt( $niche, $performance_context, $target_idea_count );
-		$user_prompt   = $this->build_user_prompt( $summary, $target_idea_count );
+		$summary             = $this->build_source_summary( $source_items );
+		$performance_context = PRAutoBlogger_Analysis_Prompts::get_performance_context();
+		$system_prompt       = PRAutoBlogger_Analysis_Prompts::build_system_prompt( $niche, $performance_context, $target_idea_count );
+		$user_prompt         = PRAutoBlogger_Analysis_Prompts::build_user_prompt( $summary, $target_idea_count );
 
 		$response = $this->llm->send_chat_completion(
-			[
-				[ 'role' => 'system', 'content' => $system_prompt ],
-				[ 'role' => 'user', 'content' => $user_prompt ],
-			],
+			array(
+				array(
+					'role'    => 'system',
+					'content' => $system_prompt,
+				),
+				array(
+					'role'    => 'user',
+					'content' => $user_prompt,
+				),
+			),
 			$model,
-			[
+			array(
 				'temperature'     => 0.5,
 				'max_tokens'      => 8000,
-				'response_format' => [ 'type' => 'json_object' ],
-			]
+				'response_format' => array( 'type' => 'json_object' ),
+				'stage'           => 'analysis',
+			)
 		);
 
-		// Log the cost.
 		$this->cost_tracker->log_api_call(
 			null,
 			'analysis',
@@ -86,15 +91,38 @@ class PRAutoBlogger_Content_Analyzer {
 			$response['completion_tokens']
 		);
 
-		// Parse LLM response into Analysis_Result objects.
 		$results = $this->parse_analysis_response( $response['content'], $source_items );
-
-		// Store in database.
 		$this->store_results( $results );
 
 		return $results;
 	}
 
+	// ── Backward-compatible proxies (prompt building moved to Analysis_Prompts) ──
+
+	/**
+	 * @deprecated Use PRAutoBlogger_Analysis_Prompts::build_system_prompt() directly.
+	 * @see core/class-analysis-prompts.php
+	 */
+	private function build_system_prompt( string $niche, string $performance_context, int $target_count = 6 ): string {
+		return PRAutoBlogger_Analysis_Prompts::build_system_prompt( $niche, $performance_context, $target_count );
+	}
+
+	/**
+	 * @deprecated Use PRAutoBlogger_Analysis_Prompts::build_user_prompt() directly.
+	 * @see core/class-analysis-prompts.php
+	 */
+	private function build_user_prompt( string $summary, int $target_count = 6 ): string {
+		return PRAutoBlogger_Analysis_Prompts::build_user_prompt( $summary, $target_count );
+	}
+
+	/**
+	 * @deprecated Use PRAutoBlogger_Analysis_Prompts::get_performance_context() directly.
+	 * @see core/class-analysis-prompts.php
+	 */
+	private function get_performance_context(): string {
+		return PRAutoBlogger_Analysis_Prompts::get_performance_context();
+	}
+
 	/**
 	 * Fetch source data collected in the last 24 hours.
 	 *
@@ -106,12 +134,12 @@ class PRAutoBlogger_Content_Analyzer {
 
 		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
 		return $wpdb->get_results(
-			$wpdb->prepare(
+			$wpdb->prepare(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
 				"SELECT * FROM {$table} WHERE collected_at >= %s ORDER BY score DESC LIMIT 200",
 				gmdate( 'Y-m-d H:i:s', time() - DAY_IN_SECONDS )
 			),
 			ARRAY_A
-		) ?: [];
+		) ?? array();
 	}
 
 	/**
@@ -120,21 +148,22 @@ class PRAutoBlogger_Content_Analyzer {
 	 * Prioritizes high-engagement content and keeps total text under ~8000 tokens.
 	 *
 	 * @param array<int, array<string, mixed>> $items Source data rows.
-	 *
 	 * @return string Formatted text summary.
 	 */
 	private function build_source_summary( array $items ): string {
-		$parts = [];
-		$char_limit = 30000; // Roughly ~7500 tokens.
+		$parts         = array();
+		$char_limit    = 30000; // Roughly ~7500 tokens.
 		$current_chars = 0;
 
 		foreach ( $items as $item ) {
+			// LLM research findings have no subreddit; use a cleaner label.
+			$source_label = 'llm_research' === $item['source_type']
+				? sprintf( '[LLM Research] Relevance: %d', (int) $item['score'] )
+				: sprintf( '[%s] r/%s | Score: %d | Comments: %d', $item['source_type'], $item['subreddit'] ?? 'unknown', (int) $item['score'], (int) $item['comment_count'] );
+
 			$entry = sprintf(
-				"[%s] r/%s | Score: %d | Comments: %d\nTitle: %s\n%s\n---",
-				$item['source_type'],
-				$item['subreddit'] ?? 'unknown',
-				(int) $item['score'],
-				(int) $item['comment_count'],
+				"%s\nTitle: %s\n%s\n---",
+				$source_label,
 				$item['title'] ?? '(comment)',
 				mb_substr( $item['content'] ?? '', 0, 500 )
 			);
@@ -143,143 +172,51 @@ class PRAutoBlogger_Content_Analyzer {
 				break;
 			}
 
-			$parts[] = $entry;
+			$parts[]        = $entry;
 			$current_chars += strlen( $entry );
 		}
 
 		return implode( "\n", $parts );
 	}
 
-	/**
-	 * Get past content performance data to feed into analysis for self-improvement.
-	 *
-	 * @return string Summary of what topics performed well/poorly.
-	 */
-	private function get_performance_context(): string {
-		global $wpdb;
-		$scores_table = $wpdb->prefix . 'prautoblogger_content_scores';
-
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-		$top_posts = $wpdb->get_results(
-			"SELECT cs.post_id, cs.composite_score, p.post_title
-			FROM {$scores_table} cs
-			JOIN {$wpdb->posts} p ON p.ID = cs.post_id
-			WHERE cs.composite_score > 0
-			ORDER BY cs.composite_score DESC
-			LIMIT 5",
-			ARRAY_A
-		);
-
-		if ( empty( $top_posts ) ) {
-			return '';
-		}
-
-		$lines = [ 'Top performing past articles (learn from these):' ];
-		foreach ( $top_posts as $post ) {
-			$lines[] = sprintf(
-				'- "%s" (score: %.1f)',
-				$post['post_title'],
-				(float) $post['composite_score']
-			);
-		}
-
-		return implode( "\n", $lines );
-	}
-
-	/**
-	 * Build the system prompt for content analysis.
-	 *
-	 * @param string $niche               Niche description from settings.
-	 * @param string $performance_context  Past performance data.
-	 *
-	 * @return string
-	 */
-	private function build_system_prompt( string $niche, string $performance_context, int $target_count = 6 ): string {
-		$prompt = "You are a content strategist analyzing social media discussions to find article ideas for a blog";
-		if ( '' !== $niche ) {
-			$prompt .= " in the {$niche} niche";
-		}
-		$prompt .= ".\n\n";
-
-		$prompt .= "IMPORTANT: You must identify exactly {$target_count} DISTINCT article ideas. ";
-		$prompt .= "Each idea must cover a substantially different topic — no two ideas should overlap ";
-		$prompt .= "in their main subject. Aim for diversity across these categories:\n";
-		$prompt .= "1. QUESTIONS: Recurring questions people ask (\"How do I...\", \"What is...\", \"Is it safe to...\")\n";
-		$prompt .= "2. COMPLAINTS: Pain points, frustrations, or problems people report\n";
-		$prompt .= "3. COMPARISONS: Product/method comparisons people discuss (\"X vs Y\", \"Which is better\")\n";
-		$prompt .= "4. NEWS: Recent developments, rule changes, or trends people are discussing\n";
-		$prompt .= "5. GUIDES: How-to topics, best practices, or educational content people need\n\n";
-
-		$prompt .= "Spread your {$target_count} ideas across multiple categories. ";
-		$prompt .= "Be specific — \"peptide dosing for BPC-157\" is better than \"peptide information\". ";
-		$prompt .= "Each idea should be narrow enough to be a single focused blog post.\n\n";
-
-		$prompt .= "For each idea, provide:\n";
-		$prompt .= "- type: 'question', 'complaint', 'comparison', 'news', or 'guide'\n";
-		$prompt .= "- topic: A clear, specific, narrow topic description\n";
-		$prompt .= "- summary: 1-2 sentence summary of why this topic matters\n";
-		$prompt .= "- frequency: How many of the provided posts relate to this topic\n";
-		$prompt .= "- relevance_score: 0.0 to 1.0 indicating how relevant and article-worthy this is\n";
-		$prompt .= "- suggested_title: A compelling, unique blog post title\n";
-		$prompt .= "- key_points: Array of 3-5 key points the article should cover\n";
-		$prompt .= "- target_keywords: Array of SEO keywords for this topic\n\n";
-
-		if ( '' !== $performance_context ) {
-			$prompt .= $performance_context . "\n\n";
-		}
-
-		$prompt .= "Respond with valid JSON containing exactly {$target_count} patterns:\n";
-		$prompt .= '{"patterns": [{"type": "...", "topic": "...", "summary": "...", "frequency": N, "relevance_score": 0.X, "suggested_title": "...", "key_points": [...], "target_keywords": [...]}]}';
-
-		return $prompt;
-	}
-
-	/**
-	 * Build the user prompt containing the actual source data.
-	 *
-	 * @param string $summary Formatted source data summary.
-	 *
-	 * @return string
-	 */
-	private function build_user_prompt( string $summary, int $target_count = 6 ): string {
-		return "Here are the recent social media posts and comments to analyze. "
-			. "Find {$target_count} distinct, diverse article ideas from this data:\n\n"
-			. $summary;
-	}
-
 	/**
 	 * Parse the LLM's JSON response into Analysis_Result objects.
 	 *
-	 * @param string                          $content      LLM response content (JSON).
-	 * @param array<int, array<string, mixed>> $source_items Original source data for ID mapping.
-	 *
+	 * @param string                            $content      LLM response content (JSON).
+	 * @param array<int, array<string, mixed>>  $source_items Original source data for ID mapping.
 	 * @return PRAutoBlogger_Analysis_Result[]
 	 */
 	private function parse_analysis_response( string $content, array $source_items ): array {
-		$data = json_decode( $content, true );
+		$data = PRAutoBlogger_Json_Extractor::decode( $content );
 		if ( ! isset( $data['patterns'] ) || ! is_array( $data['patterns'] ) ) {
-			PRAutoBlogger_Logger::instance()->error( 'Analysis response was not valid JSON or missing patterns key.', 'analyzer' );
-			return [];
+			PRAutoBlogger_Logger::instance()->error(
+				'Analysis response was not valid JSON or missing patterns key. Raw (first 500 chars): '
+				. mb_substr( $content, 0, 500 ),
+				'analyzer'
+			);
+			return array();
 		}
 
 		$source_ids = array_column( $source_items, 'id' );
-		$results    = [];
+		$results    = array();
 
 		foreach ( $data['patterns'] as $pattern ) {
-			$results[] = new PRAutoBlogger_Analysis_Result( [
-				'analysis_type'   => sanitize_text_field( $pattern['type'] ?? 'question' ),
-				'topic'           => sanitize_text_field( $pattern['topic'] ?? '' ),
-				'summary'         => sanitize_textarea_field( $pattern['summary'] ?? '' ),
-				'frequency'       => absint( $pattern['frequency'] ?? 1 ),
-				'relevance_score' => (float) ( $pattern['relevance_score'] ?? 0.0 ),
-				'source_ids'      => $source_ids,
-				'analyzed_at'     => current_time( 'mysql' ),
-				'metadata'        => [
-					'suggested_title'  => $pattern['suggested_title'] ?? '',
-					'key_points'       => $pattern['key_points'] ?? [],
-					'target_keywords'  => $pattern['target_keywords'] ?? [],
-				],
-			] );
+			$results[] = new PRAutoBlogger_Analysis_Result(
+				array(
+					'analysis_type'   => sanitize_text_field( $pattern['type'] ?? 'question' ),
+					'topic'           => sanitize_text_field( $pattern['topic'] ?? '' ),
+					'summary'         => sanitize_textarea_field( $pattern['summary'] ?? '' ),
+					'frequency'       => absint( $pattern['frequency'] ?? 1 ),
+					'relevance_score' => (float) ( $pattern['relevance_score'] ?? 0.0 ),
+					'source_ids'      => $source_ids,
+					'analyzed_at'     => current_time( 'mysql' ),
+					'metadata'        => array(
+						'suggested_title' => $pattern['suggested_title'] ?? '',
+						'key_points'      => $pattern['key_points'] ?? array(),
+						'target_keywords' => $pattern['target_keywords'] ?? array(),
+					),
+				)
+			);
 		}
 
 		return $results;
@@ -291,8 +228,6 @@ class PRAutoBlogger_Content_Analyzer {
 	 * Side effects: database inserts.
 	 *
 	 * @param PRAutoBlogger_Analysis_Result[] $results
-	 *
-	 * @return void
 	 */
 	private function store_results( array $results ): void {
 		global $wpdb;

includes/core/class-content-generator.php

@@ -4,22 +4,27 @@ declare(strict_types=1);
 /**
  * Writer agent — generates blog post content from article ideas.
  *
- * Supports two configurable pipeline modes:
- * - single_pass: One LLM call produces the complete article (cheaper, faster).
- * - multi_step: Outline → Draft → Polish pipeline (higher quality, more cost).
+ * Supports: single_pass (one LLM call) or multi_step (outline → draft → polish).
+ * Opik instrumentation: spans per LLM call when feature-flag enabled.
+ * v0.18.0: prompt copy renders from the versioned prompt registry (with
+ * byte-identical in-code fallback); every log row carries the run-pinned
+ * prompt_version. The four stage methods share one execute_stage() helper —
+ * span lifecycle, LLM dispatch, and cost logging are identical across stages.
  *
- * Triggered by: PRAutoBlogger::run_generation_pipeline() (step 4).
- * Dependencies: LLM_Provider_Interface, Cost_Tracker.
- *
- * @see core/class-chief-editor.php     — Reviews output of this class.
- * @see providers/interface-llm-provider.php — LLM used for generation.
- * @see ARCHITECTURE.md                 — Data flow step 4.
+ * Triggered by: PRAutoBlogger_Article_Worker.
+ * Dependencies: LLM_Provider_Interface, Cost_Tracker, Content_Prompts.
  */
 class PRAutoBlogger_Content_Generator {
 
 	private PRAutoBlogger_LLM_Provider_Interface $llm;
 	private PRAutoBlogger_Cost_Tracker $cost_tracker;
 
+	/** @var string|null Run UUID for stage-state checkpointing (null = off). */
+	private ?string $run_id = null;
+
+	/** @var string|null Stage item key scoping this article within the run. */
+	private ?string $item_key = null;
+
 	public function __construct(
 		PRAutoBlogger_LLM_Provider_Interface $llm,
 		PRAutoBlogger_Cost_Tracker $cost_tracker
@@ -28,20 +33,36 @@ class PRAutoBlogger_Content_Generator {
 		$this->cost_tracker = $cost_tracker;
 	}
 
+	/**
+	 * Enable per-stage state checkpointing for one article item (v0.18.0).
+	 *
+	 * When set, every LLM stage (outline/draft/polish or the single-pass
+	 * draft) records pending->running->done state and snapshots its output;
+	 * a re-entered done stage returns the snapshot WITHOUT a new LLM call
+	 * (never re-charged). When unset (default), behavior is exactly
+	 * pre-v0.18.0 — used by callers outside a run (e.g. eval mode).
+	 *
+	 * @param string|null $run_id   Run UUID, or null to disable.
+	 * @param string|null $item_key Item key from Run_Stage_State::item_key_for_idea().
+	 * @return $this
+	 */
+	public function set_run_item( ?string $run_id, ?string $item_key ): self {
+		$this->run_id   = $run_id;
+		$this->item_key = $item_key;
+		return $this;
+	}
+
 	/**
 	 * Generate a blog post from an article idea.
 	 *
-	 * Reads pipeline mode from settings and dispatches to the appropriate method.
-	 *
-	 * Side effects: LLM API calls (1-3 depending on mode), cost logging.
-	 *
-	 * @param PRAutoBlogger_Article_Idea $idea The scored idea to generate content for.
-	 *
+	 * @param PRAutoBlogger_Article_Idea $idea      The scored idea to generate content for.
+	 * @param bool                       $eval_mode True to suppress publish/image side effects.
 	 * @return string Generated HTML content.
-	 *
-	 * @throws \RuntimeException On generation failure.
 	 */
-	public function generate( PRAutoBlogger_Article_Idea $idea ): string {
+	public function generate( PRAutoBlogger_Article_Idea $idea, bool $eval_mode = false ): string {
+		// In eval mode, suppress publishing and image generation side effects.
+		define( 'PRAUTOBLOGGER_EVAL_MODE', $eval_mode );
+
 		$mode = get_option( 'prautoblogger_writing_pipeline', 'multi_step' );
 
 		$request = new PRAutoBlogger_Content_Request(
@@ -51,247 +72,223 @@ class PRAutoBlogger_Content_Generator {
 			absint( get_option( 'prautoblogger_min_word_count', 800 ) ),
 			absint( get_option( 'prautoblogger_max_word_count', 2000 ) ),
 			get_option( 'prautoblogger_niche_description', '' ),
-			json_decode( get_option( 'prautoblogger_topic_exclusions', '[]' ), true ) ?: []
+			json_decode( get_option( 'prautoblogger_topic_exclusions', '[]' ), true ) ?? array(),
+			get_option( 'prautoblogger_writing_instructions', '' )
 		);
 
-		if ( 'single_pass' === $mode ) {
-			return $this->generate_single_pass( $request );
-		}
-
-		return $this->generate_multi_step( $request );
+		return 'single_pass' === $mode
+			? $this->generate_single_pass( $request )
+			: $this->generate_multi_step( $request );
 	}
 
 	/**
-	 * Single-pass generation: one LLM call produces the complete article.
+	 * Single-pass: one LLM call produces complete article (Economy tier).
 	 *
-	 * @param PRAutoBlogger_Content_Request $request
+	 * The log row's stage stays 'draft' (historical contract: a draft row
+	 * without an outline row marks a single-pass run) but the prompt key
+	 * is passed explicitly — the stage map would resolve 'draft' to
+	 * 'content.draft'.
 	 *
+	 * @param PRAutoBlogger_Content_Request $request Generation request.
 	 * @return string Generated HTML content.
 	 */
 	private function generate_single_pass( PRAutoBlogger_Content_Request $request ): string {
-		$model    = get_option( 'prautoblogger_writing_model', PRAUTOBLOGGER_DEFAULT_WRITING_MODEL );
-		$idea     = $request->get_idea();
+		$model = get_option( 'prautoblogger_writing_model', PRAUTOBLOGGER_DEFAULT_WRITING_MODEL );
 
-		$system = $this->build_writer_system_prompt( $request );
-		$user   = $this->build_single_pass_prompt( $request );
-
-		$response = $this->llm->send_chat_completion(
-			[
-				[ 'role' => 'system', 'content' => $system ],
-				[ 'role' => 'user', 'content' => $user ],
-			],
+		return $this->execute_stage(
+			'draft',
+			'single_pass_generation',
+			PRAutoBlogger_Content_Prompts::build_single_pass( $request ),
+			$request,
 			$model,
-			[
+			array(
 				'temperature' => 0.7,
 				'max_tokens'  => 4000,
-			]
+			),
+			'content.single_pass'
 		);
-
-		$this->cost_tracker->log_api_call(
-			null,
-			'draft',
-			$this->llm->get_provider_name(),
-			$response['model'],
-			$response['prompt_tokens'],
-			$response['completion_tokens']
-		);
-
-		return $response['content'];
 	}
 
 	/**
-	 * Multi-step generation: Outline → Draft → Polish.
-	 *
-	 * @param PRAutoBlogger_Content_Request $request
+	 * Multi-step: outline → draft → polish.
 	 *
+	 * @param PRAutoBlogger_Content_Request $request Generation request.
 	 * @return string Generated HTML content.
 	 */
 	private function generate_multi_step( PRAutoBlogger_Content_Request $request ): string {
 		$model = get_option( 'prautoblogger_writing_model', PRAUTOBLOGGER_DEFAULT_WRITING_MODEL );
 
-		// Step 1: Generate outline.
-		$outline = $this->stage_outline( $request, $model );
-
-		// Step 2: Generate draft from outline.
-		$draft = $this->stage_draft( $request, $outline, $model );
-
-		// Step 3: Polish the draft.
-		$polished = $this->stage_polish( $request, $draft, $model );
-
-		return $polished;
-	}
-
-	/**
-	 * Multi-step stage 1: Generate an article outline.
-	 *
-	 * @param PRAutoBlogger_Content_Request $request
-	 * @param string                      $model
-	 *
-	 * @return string The outline text.
-	 */
-	private function stage_outline( PRAutoBlogger_Content_Request $request, string $model ): string {
-		$idea = $request->get_idea();
-
-		$prompt = sprintf(
-			"Create a detailed outline for a blog post titled: \"%s\"\n\n" .
-			"Topic: %s\nArticle type: %s\n\nKey points to cover:\n%s\n\n" .
-			"Target keywords: %s\n\n" .
-			"The outline should have 4-6 main sections with bullet points under each. " .
-			"Include an introduction hook and a conclusion with a call to action. " .
-			"Word count target: %d-%d words.",
-			$idea->get_suggested_title(),
-			$idea->get_topic(),
-			$idea->get_article_type(),
-			implode( "\n- ", $idea->get_key_points() ),
-			implode( ', ', $idea->get_target_keywords() ),
-			$request->get_min_word_count(),
-			$request->get_max_word_count()
-		);
-
-		$response = $this->llm->send_chat_completion(
-			[
-				[ 'role' => 'system', 'content' => $this->build_writer_system_prompt( $request ) ],
-				[ 'role' => 'user', 'content' => $prompt ],
-			],
+		$outline = $this->execute_stage(
+			'outline',
+			'outline_generation',
+			PRAutoBlogger_Content_Prompts::build_outline( $request ),
+			$request,
 			$model,
-			[ 'temperature' => 0.5, 'max_tokens' => 1500 ]
+			array(
+				'temperature' => 0.5,
+				'max_tokens'  => 1500,
+			)
 		);
 
-		$this->cost_tracker->log_api_call(
-			null, 'outline', $this->llm->get_provider_name(),
-			$response['model'], $response['prompt_tokens'], $response['completion_tokens']
-		);
-
-		return $response['content'];
-	}
-
-	/**
-	 * Multi-step stage 2: Write the full draft from the outline.
-	 *
-	 * @param PRAutoBlogger_Content_Request $request
-	 * @param string                      $outline
-	 * @param string                      $model
-	 *
-	 * @return string Draft HTML content.
-	 */
-	private function stage_draft( PRAutoBlogger_Content_Request $request, string $outline, string $model ): string {
-		$prompt = sprintf(
-			"Using this outline, write the full blog post in HTML format.\n\n" .
-			"OUTLINE:\n%s\n\n" .
-			"Requirements:\n" .
-			"- Write in a %s tone\n" .
-			"- Target %d-%d words\n" .
-			"- Use proper HTML headings (h2, h3), paragraphs, and lists\n" .
-			"- Include an engaging introduction and strong conclusion\n" .
-			"- Naturally incorporate these keywords: %s\n" .
-			"- Do NOT include the title in the HTML (it will be set separately)\n" .
-			"- Do NOT wrap in <html>, <head>, or <body> tags — just the article content",
-			$outline,
-			$request->get_tone(),
-			$request->get_min_word_count(),
-			$request->get_max_word_count(),
-			implode( ', ', $request->get_idea()->get_target_keywords() )
-		);
-
-		$response = $this->llm->send_chat_completion(
-			[
-				[ 'role' => 'system', 'content' => $this->build_writer_system_prompt( $request ) ],
-				[ 'role' => 'user', 'content' => $prompt ],
-			],
+		$draft = $this->execute_stage(
+			'draft',
+			'draft_generation',
+			PRAutoBlogger_Content_Prompts::build_draft( $request, $outline ),
+			$request,
 			$model,
-			[ 'temperature' => 0.7, 'max_tokens' => 4000 ]
+			array(
+				'temperature' => 0.7,
+				'max_tokens'  => 4000,
+			)
 		);
 
-		$this->cost_tracker->log_api_call(
-			null, 'draft', $this->llm->get_provider_name(),
-			$response['model'], $response['prompt_tokens'], $response['completion_tokens']
-		);
-
-		return $response['content'];
-	}
-
-	/**
-	 * Multi-step stage 3: Polish and refine the draft.
-	 *
-	 * @param PRAutoBlogger_Content_Request $request
-	 * @param string                      $draft
-	 * @param string                      $model
-	 *
-	 * @return string Polished HTML content.
-	 */
-	private function stage_polish( PRAutoBlogger_Content_Request $request, string $draft, string $model ): string {
-		$prompt = "Review and polish this blog post draft. Improve:\n" .
-			"1. Flow and readability\n" .
-			"2. SEO optimization (headings, keyword placement)\n" .
-			"3. Engagement (hooks, transitions, call-to-action)\n" .
-			"4. Accuracy and clarity\n" .
-			"5. Remove any filler or redundant sentences\n\n" .
-			"Return the polished HTML content only. Do not add commentary.\n\n" .
-			"DRAFT:\n" . $draft;
-
-		$response = $this->llm->send_chat_completion(
-			[
-				[ 'role' => 'system', 'content' => $this->build_writer_system_prompt( $request ) ],
-				[ 'role' => 'user', 'content' => $prompt ],
-			],
+		return $this->execute_stage(
+			'polish',
+			'polish_generation',
+			PRAutoBlogger_Content_Prompts::build_polish( $draft ),
+			$request,
 			$model,
-			[ 'temperature' => 0.4, 'max_tokens' => 4000 ]
+			array(
+				'temperature' => 0.4,
+				'max_tokens'  => 4000,
+			)
 		);
-
-		$this->cost_tracker->log_api_call(
-			null, 'polish', $this->llm->get_provider_name(),
-			$response['model'], $response['prompt_tokens'], $response['completion_tokens']
-		);
-
-		return $response['content'];
 	}
 
 	/**
-	 * Build the system prompt shared across all writing stages.
+	 * Run one writing stage: Opik span → LLM call → span close → cost log.
 	 *
-	 * @param PRAutoBlogger_Content_Request $request
+	 * Consolidates the per-stage boilerplate that was previously duplicated
+	 * across the four stage methods (v0.18.0). The system prompt is rebuilt
+	 * per stage exactly as before.
 	 *
-	 * @return string
+	 * Side effects: one OpenRouter API call, one Opik span (when tracing),
+	 * one generation_log row.
+	 *
+	 * @param string                        $stage       Log stage value ('outline'|'draft'|'polish').
+	 * @param string                        $span_name   Opik span name.
+	 * @param string                        $user_prompt Rendered user prompt for the stage.
+	 * @param PRAutoBlogger_Content_Request $request     Generation request (system prompt input).
+	 * @param string                        $model       Model identifier.
+	 * @param array<string, mixed>          $options     LLM options (temperature, max_tokens).
+	 * @param string|null                   $prompt_key  Explicit registry key for prompt_version
+	 *                                                   stamping (null = derive from stage).
+	 * @return string Stage output content.
 	 */
-	private function build_writer_system_prompt( PRAutoBlogger_Content_Request $request ): string {
-		$niche = $request->get_niche_description();
-		$prompt = "You are an expert blog writer";
-		if ( '' !== $niche ) {
-			$prompt .= " specializing in {$niche}";
+	private function execute_stage(
+		string $stage,
+		string $span_name,
+		string $user_prompt,
+		PRAutoBlogger_Content_Request $request,
+		string $model,
+		array $options,
+		?string $prompt_key = null
+	): string {
+		// Idempotent resume: a done stage returns its snapshot, no LLM call.
+		if ( null !== $this->run_id && null !== $this->item_key ) {
+			$cached = PRAutoBlogger_Run_Stage_State::get_output( $this->run_id, $stage, '', $this->item_key );
+			if ( null !== $cached ) {
+				PRAutoBlogger_Logger::instance()->info(
+					sprintf( 'Reusing completed %s stage output (idempotent resume).', $stage ),
+					'pipeline'
+				);
+				return $cached;
+			}
+			PRAutoBlogger_Run_Stage_State::start( $this->run_id, $stage, (string) PRAutoBlogger_Stage_Display_Map::default_agent_role( $stage ), $this->item_key );
 		}
-		$prompt .= ". Write well-researched, engaging, SEO-friendly content. ";
-		$prompt .= "Use a {$request->get_tone()} tone. ";
-		$prompt .= "Output HTML content only — no markdown, no code fences, no commentary.";
-		return $prompt;
+
+		// v0.18.1: stage metadata for the provider's empty-completion
+		// guard — warning logs and failed-attempt audit rows carry the
+		// real stage + registry key (never sent upstream).
+		$options['stage']      = $stage;
+		$options['prompt_key'] = $prompt_key;
+
+		$ctx = PRAutoBlogger_Opik_Trace_Context::current();
+
+		$span_id = $ctx->start_span(
+			array(
+				'name'     => $span_name,
+				'type'     => 'llm',
+				'model'    => $model,
+				'provider' => 'openrouter',
+			)
+		);
+
+		$response = $this->llm->send_chat_completion(
+			array(
+				array(
+					'role'    => 'system',
+					'content' => PRAutoBlogger_Content_Prompts::build_system( $request ),
+				),
+				array(
+					'role'    => 'user',
+					'content' => $user_prompt,
+				),
+			),
+			$model,
+			$options
+		);
+
+		// v0.18.1 writer-path guard (belt over the provider seam, which
+		// already throws for OpenRouter): no empty article may ever leave
+		// a writing stage — it would flow to the editor, be rejected as
+		// "draft text is missing", and land as an empty draft post.
+		if ( '' === trim( (string) $response['content'] ) ) {
+			throw new \RuntimeException(
+				sprintf(
+					/* translators: 1: writing stage name, 2: model identifier. */
+					__( 'Writing stage "%1$s" produced empty content (model %2$s) — failing the stage instead of passing an empty article downstream.', 'prautoblogger' ),
+					$stage,
+					(string) $response['model']
+				)
+			);
+		}
+
+		$ctx->end_span(
+			$span_id,
+			array(
+				'usage' => array(
+					'prompt_tokens'     => $response['prompt_tokens'],
+					'completion_tokens' => $response['completion_tokens'],
+					'total_tokens'      => $response['prompt_tokens'] + $response['completion_tokens'],
+				),
+			)
+		);
+
+		$this->cost_tracker->log_api_call(
+			null,
+			$stage,
+			$this->llm->get_provider_name(),
+			$response['model'],
+			$response['prompt_tokens'],
+			$response['completion_tokens'],
+			'success',
+			'',
+			null,
+			$prompt_key
+		);
+
+		if ( null !== $this->run_id && null !== $this->item_key ) {
+			PRAutoBlogger_Run_Stage_State::done(
+				$this->run_id,
+				$stage,
+				'',
+				$this->item_key,
+				(string) $response['content'],
+				$this->llm->estimate_cost( $response['model'], (int) $response['prompt_tokens'], (int) $response['completion_tokens'] )
+			);
+		}
+
+		return $response['content'];
 	}
 
 	/**
-	 * Build the user prompt for single-pass generation.
+	 * Generate content in eval mode (no publishing, no image generation).
 	 *
-	 * @param PRAutoBlogger_Content_Request $request
-	 *
-	 * @return string
+	 * @param PRAutoBlogger_Article_Idea $idea The scored idea to generate content for.
+	 * @return string Generated HTML content.
 	 */
-	private function build_single_pass_prompt( PRAutoBlogger_Content_Request $request ): string {
-		$idea = $request->get_idea();
-
-		return sprintf(
-			"Write a complete blog post in HTML format.\n\n" .
-			"Title: %s\nTopic: %s\nType: %s\n\nKey points:\n- %s\n\n" .
-			"Keywords: %s\n\n" .
-			"Requirements:\n" .
-			"- %d-%d words\n" .
-			"- Proper HTML (h2, h3, p, ul/li)\n" .
-			"- Engaging intro, strong conclusion with CTA\n" .
-			"- Do NOT include the title or <html>/<body> tags\n" .
-			"- Output HTML only, no markdown or commentary",
-			$idea->get_suggested_title(),
-			$idea->get_topic(),
-			$idea->get_article_type(),
-			implode( "\n- ", $idea->get_key_points() ),
-			implode( ', ', $idea->get_target_keywords() ),
-			$request->get_min_word_count(),
-			$request->get_max_word_count()
-		);
+	public function generate_eval( PRAutoBlogger_Article_Idea $idea ): string {
+		return $this->generate( $idea, true );
 	}
 }

includes/core/class-content-prompts.php

@@ -0,0 +1,192 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Builds all LLM prompts used by the content generation pipeline.
+ *
+ * Centralises prompt construction so Content_Generator stays lean and
+ * prompt logic (system prompt, stage prompts, linking rules) can evolve
+ * independently of the generation orchestration.
+ *
+ * Triggered by: PRAutoBlogger_Content_Generator (called for every stage).
+ * Dependencies: PRAutoBlogger_Prompt_Registry (versioned prompt bodies),
+ *               WordPress query functions (get_posts, get_the_title, get_permalink).
+ *
+ * @see core/class-content-generator.php — Consumer of these prompts.
+ * @see models/class-content-request.php — Data bag passed to every builder.
+ */
+class PRAutoBlogger_Content_Prompts {
+
+	/**
+	 * Build the system prompt shared across all writing stages.
+	 *
+	 * Includes niche, tone, mandatory style guide, internal link reference,
+	 * peptide database links, and the "never fabricate URLs" rule.
+	 *
+	 * v0.18.0: the prompt copy renders from the versioned registry
+	 * ('content.system', falls back to the identical in-code default);
+	 * the style guide and linking rules are data injection and stay here.
+	 *
+	 * @param PRAutoBlogger_Content_Request $request Content request with settings.
+	 * @return string Complete system prompt.
+	 */
+	public static function build_system( PRAutoBlogger_Content_Request $request ): string {
+		$niche  = $request->get_niche_description();
+		$prompt = PRAutoBlogger_Prompt_Registry::render(
+			'content.system',
+			array(
+				'niche_clause' => '' !== $niche ? " specializing in {$niche}" : '',
+				'tone'         => $request->get_tone(),
+			)
+		);
+
+		// Append user-defined writing instructions as a mandatory style guide.
+		$instructions = trim( $request->get_writing_instructions() );
+		if ( '' !== $instructions ) {
+			$prompt .= "\n\n--- MANDATORY STYLE GUIDE ---\n";
+			$prompt .= "You MUST follow every requirement below. These override any conflicting defaults:\n\n";
+			$prompt .= $instructions;
+			$prompt .= "\n--- END STYLE GUIDE ---";
+		}
+
+		$prompt .= "\n\n" . self::build_linking_rules();
+
+		return $prompt;
+	}
+
+	/**
+	 * Build the user prompt for single-pass generation.
+	 *
+	 * @param PRAutoBlogger_Content_Request $request Content request with settings.
+	 * @return string User prompt.
+	 */
+	public static function build_single_pass( PRAutoBlogger_Content_Request $request ): string {
+		$idea = $request->get_idea();
+
+		return PRAutoBlogger_Prompt_Registry::render(
+			'content.single_pass',
+			array(
+				'title'        => $idea->get_suggested_title(),
+				'topic'        => $idea->get_topic(),
+				'article_type' => $idea->get_article_type(),
+				'key_points'   => implode( "\n- ", $idea->get_key_points() ),
+				'keywords'     => implode( ', ', $idea->get_target_keywords() ),
+				'min_words'    => (string) $request->get_min_word_count(),
+				'max_words'    => (string) $request->get_max_word_count(),
+			)
+		);
+	}
+
+	/**
+	 * Build the outline stage prompt (multi-step stage 1).
+	 *
+	 * @param PRAutoBlogger_Content_Request $request Content request with settings.
+	 * @return string Outline prompt.
+	 */
+	public static function build_outline( PRAutoBlogger_Content_Request $request ): string {
+		$idea = $request->get_idea();
+
+		return PRAutoBlogger_Prompt_Registry::render(
+			'content.outline',
+			array(
+				'title'        => $idea->get_suggested_title(),
+				'topic'        => $idea->get_topic(),
+				'article_type' => $idea->get_article_type(),
+				'key_points'   => implode( "\n- ", $idea->get_key_points() ),
+				'keywords'     => implode( ', ', $idea->get_target_keywords() ),
+				'min_words'    => (string) $request->get_min_word_count(),
+				'max_words'    => (string) $request->get_max_word_count(),
+			)
+		);
+	}
+
+	/**
+	 * Build the draft stage prompt (multi-step stage 2).
+	 *
+	 * @param PRAutoBlogger_Content_Request $request Content request with settings.
+	 * @param string                        $outline The outline from stage 1.
+	 * @return string Draft prompt.
+	 */
+	public static function build_draft( PRAutoBlogger_Content_Request $request, string $outline ): string {
+		return PRAutoBlogger_Prompt_Registry::render(
+			'content.draft',
+			array(
+				'outline'   => $outline,
+				'tone'      => $request->get_tone(),
+				'min_words' => (string) $request->get_min_word_count(),
+				'max_words' => (string) $request->get_max_word_count(),
+				'keywords'  => implode( ', ', $request->get_idea()->get_target_keywords() ),
+			)
+		);
+	}
+
+	/**
+	 * Build the polish stage prompt (multi-step stage 3).
+	 *
+	 * @param string $draft The draft from stage 2.
+	 * @return string Polish prompt.
+	 */
+	public static function build_polish( string $draft ): string {
+		return PRAutoBlogger_Prompt_Registry::render(
+			'content.polish',
+			array( 'draft' => $draft )
+		);
+	}
+
+	/**
+	 * Build the linking rules section (internal articles + peptide database).
+	 *
+	 * Fetches published blog posts and peptide pages, formats them as a
+	 * reference list so the model uses real URLs instead of fabricating them.
+	 *
+	 * @return string Complete linking rules block.
+	 */
+	private static function build_linking_rules(): string {
+		$rules  = "--- LINKING RULES ---\n";
+		$rules .= "NEVER fabricate or invent URLs. You do NOT have access to external sources.\n";
+		$rules .= "Only use the internal links listed below when linking within the article.\n";
+		$rules .= "If no listed article is relevant to a section, do not insert a link.\n";
+		$rules .= "Do NOT add links for peptide names — those are injected automatically after generation.\n\n";
+
+		$rules .= self::build_article_links();
+
+		$rules .= '--- END LINKING RULES ---';
+
+		return $rules;
+	}
+
+	/**
+	 * Build a reference list of published blog posts for internal linking.
+	 *
+	 * @return string Formatted list, or a fallback note.
+	 */
+	private static function build_article_links(): string {
+		$posts = get_posts(
+			array(
+				'post_type'      => 'post',
+				'post_status'    => 'publish',
+				'posts_per_page' => 30,
+				'orderby'        => 'date',
+				'order'          => 'DESC',
+				'fields'         => 'ids',
+			)
+		);
+
+		if ( empty( $posts ) ) {
+			return "No published articles available for internal linking yet.\n";
+		}
+
+		$lines = array( "Available article links (use where topically relevant):\n" );
+		foreach ( $posts as $post_id ) {
+			$title = get_the_title( $post_id );
+			$url   = get_permalink( $post_id );
+			if ( $title && $url ) {
+				$lines[] = "- {$title}: {$url}";
+			}
+		}
+
+		return implode( "\n", $lines ) . "\n";
+	}
+}

includes/core/class-cost-ceiling-exception.php

@@ -0,0 +1,23 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Thrown when a reserve-before-call would push a run past its cost ceiling.
+ *
+ * What: Dedicated exception type so call paths can distinguish "this run
+ *       was halted by the per-run cost governor" from generic API
+ *       failures. By the time it is thrown the governor has already
+ *       marked the run `halted`, recorded the overage on the runs row,
+ *       and logged — catchers must NOT dispatch the call they were about
+ *       to make, and chained jobs abort via the run-status check in
+ *       Pipeline_Runner::process_next_queued_article().
+ * Who triggers it: PRAutoBlogger_Cost_Governor on a failed reservation.
+ * Dependencies: none (extends RuntimeException).
+ *
+ * @see core/class-cost-governor.php      — Sole thrower.
+ * @see core/class-pipeline-runner.php    — Aborts queued articles of halted runs.
+ */
+class PRAutoBlogger_Cost_Ceiling_Exception extends \RuntimeException {
+}

includes/core/class-cost-governor.php

@@ -0,0 +1,239 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Per-run cost governor — reserve-before-call against the run ledger.
+ *
+ * What: Net-new enforcement (the monthly Cost_Tracker cap only bounds the
+ *       month; `get_current_run_cost()` was an unguarded accumulator).
+ *       Before any governed call dispatches, its worst-case cost estimate
+ *       is atomically added to the run's `reserved_usd` via a single
+ *       conditional UPDATE — the same atomic-conditional-write discipline
+ *       as PRAutoBlogger_Generation_Lock (#10) — so concurrent writers
+ *       (curl_multi fan-outs, chained jobs) cannot slip past the ceiling
+ *       between check and call. Batches reserve their SUMMED estimate
+ *       before dispatch. After each response the reservation settles to
+ *       the actual cost, so a cheap call never holds its worst case.
+ *       Breach: the run is marked `halted` (sticky), the overage is
+ *       recorded on the runs row, the Review Queue surfaces it, and a
+ *       Cost_Ceiling_Exception aborts the un-dispatched call. Standalone
+ *       calls outside any run (no run context) are not run-governed —
+ *       exactly the historical behavior; the monthly cap and the
+ *       Cloudflare AI Gateway path are untouched everywhere.
+ * Who triggers it: PRAutoBlogger_OpenRouter_Provider::send_chat_completion
+ *       (every text-LLM call path), PRAutoBlogger_Image_Pipeline (image
+ *       curl_multi batch).
+ * Dependencies: Run_Context (which run is this process in),
+ *       Run_State (ledger row + halt), OpenRouter_Pricing (#18 chain),
+ *       WordPress $wpdb, Logger.
+ *
+ * @see class-generation-lock.php            — The atomic-write pattern this mirrors.
+ * @see core/class-run-state.php             — The ledger row reserved against.
+ * @see providers/class-open-router-provider.php — Text-call integration point.
+ * @see core/class-image-pipeline.php        — Batch reservation integration point.
+ * @see ARCHITECTURE.md #21                  — Design rationale.
+ */
+class PRAutoBlogger_Cost_Governor {
+
+	/**
+	 * Rough chars-per-token divisor for prompt-size estimation. An internal
+	 * estimator detail (NOT a behavior setting — the enforced ceiling is
+	 * the prautoblogger_per_run_cost_ceiling_usd SETTING).
+	 */
+	private const CHARS_PER_TOKEN = 4;
+
+	/**
+	 * Worst-case completion tokens assumed when a caller sets no
+	 * max_tokens. Every current call site sets one; this is belt-and-braces.
+	 */
+	private const DEFAULT_MAX_COMPLETION_TOKENS = 4096;
+
+	/**
+	 * Reserve the worst-case cost of one chat-completion call for the
+	 * process's current run. Call before dispatch.
+	 *
+	 * Returns null (call proceeds ungoverned, exactly as pre-v0.18.0) when
+	 * this process is not inside a run, the run row/ledger is unavailable
+	 * (half-migrated schema), or the run's ceiling is 0/disabled.
+	 *
+	 * @param string                                            $model    Model identifier.
+	 * @param array<int, array{role: string, content: string}>  $messages Chat messages (prompt-size estimate).
+	 * @param array<string, mixed>                              $options  Call options (max_tokens).
+	 * @return array{run_id: string, amount: float}|null Open reservation, or null when ungoverned.
+	 * @throws PRAutoBlogger_Cost_Ceiling_Exception When the reservation would breach the ceiling
+	 *                                              (the run is already halted when this throws).
+	 */
+	public static function open_chat_reservation( string $model, array $messages, array $options ): ?array {
+		return self::open_amount_reservation(
+			self::estimate_chat_cost( $model, $messages, $options ),
+			'llm:' . $model
+		);
+	}
+
+	/**
+	 * Reserve a pre-computed worst-case amount (e.g. a curl_multi image
+	 * batch's summed estimate) for the process's current run.
+	 *
+	 * @param float  $amount_usd Worst-case cost estimate in USD.
+	 * @param string $context    Short label for logs ('llm:<model>', 'image_batch').
+	 * @return array{run_id: string, amount: float}|null Open reservation, or null when ungoverned.
+	 * @throws PRAutoBlogger_Cost_Ceiling_Exception When the reservation would breach the ceiling.
+	 */
+	public static function open_amount_reservation( float $amount_usd, string $context ): ?array {
+		$run_id = PRAutoBlogger_Run_Context::current_run_id();
+		if ( null === $run_id || '' === $run_id || $amount_usd <= 0 ) {
+			return null;
+		}
+		if ( ! PRAutoBlogger_Run_State::is_available() ) {
+			return null; // Half-migrated schema — degrade to historical behavior.
+		}
+
+		PRAutoBlogger_Run_State::ensure_run( $run_id );
+		$run = PRAutoBlogger_Run_State::get_run( $run_id );
+		if ( null === $run ) {
+			return null;
+		}
+		if ( (float) $run['ceiling_usd'] <= 0 ) {
+			return null; // Ceiling disabled for this run.
+		}
+
+		if ( self::reserve( $run_id, $amount_usd ) ) {
+			return array(
+				'run_id' => $run_id,
+				'amount' => $amount_usd,
+			);
+		}
+
+		self::on_breach( $run_id, $amount_usd, $context );
+		return null; // Unreachable — on_breach always throws.
+	}
+
+	/**
+	 * Settle an open reservation to the call's actual cost: the hold is
+	 * released and the actual amount moves to settled_usd.
+	 *
+	 * @param array{run_id: string, amount: float}|null $reservation Reservation from open_*(), or null (no-op).
+	 * @param float                                     $actual_usd  Actual cost of the call.
+	 * @return void
+	 */
+	public static function settle( ?array $reservation, float $actual_usd ): void {
+		if ( null === $reservation || ! PRAutoBlogger_Run_State::is_available() ) {
+			return;
+		}
+		global $wpdb;
+		$table = PRAutoBlogger_Run_State::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$wpdb->query(
+			$wpdb->prepare(
+				"UPDATE {$table}
+				SET reserved_usd = GREATEST(reserved_usd - %f, 0),
+					settled_usd = settled_usd + %f,
+					updated_at = %s
+				WHERE run_id = %s",
+				$reservation['amount'],
+				max( $actual_usd, 0 ),
+				current_time( 'mysql' ),
+				$reservation['run_id']
+			)
+		);
+	}
+
+	/**
+	 * Release an open reservation without settling cost (failed call).
+	 *
+	 * @param array{run_id: string, amount: float}|null $reservation Reservation from open_*(), or null (no-op).
+	 * @return void
+	 */
+	public static function release( ?array $reservation ): void {
+		self::settle( $reservation, 0.0 );
+	}
+
+	/**
+	 * Worst-case cost estimate for a chat call: estimated prompt tokens
+	 * (message chars / 4) plus the call's max_tokens completion budget,
+	 * priced via the #18 pricing chain (hardcoded table -> cached model
+	 * registry -> conservative fallback).
+	 *
+	 * @param string                                           $model    Model identifier.
+	 * @param array<int, array{role: string, content: string}> $messages Chat messages.
+	 * @param array<string, mixed>                             $options  Call options.
+	 * @return float Estimated worst-case USD cost.
+	 */
+	public static function estimate_chat_cost( string $model, array $messages, array $options ): float {
+		$chars = 0;
+		foreach ( $messages as $message ) {
+			$chars += strlen( (string) ( $message['content'] ?? '' ) );
+		}
+		$prompt_tokens     = (int) ceil( $chars / self::CHARS_PER_TOKEN );
+		$completion_tokens = (int) ( $options['max_tokens'] ?? self::DEFAULT_MAX_COMPLETION_TOKENS );
+
+		return ( new PRAutoBlogger_OpenRouter_Pricing() )->estimate_cost( $model, $prompt_tokens, $completion_tokens );
+	}
+
+	/**
+	 * Atomic conditional reservation — the #10 discipline. One UPDATE
+	 * whose WHERE clause enforces `settled + reserved + estimate <=
+	 * ceiling` AND that the run is still open; affected-rows tells us who
+	 * won. Concurrent reservers serialize on the row lock.
+	 *
+	 * @param string $run_id Run UUID.
+	 * @param float  $amount Estimate to reserve.
+	 * @return bool True when the reservation was written.
+	 */
+	private static function reserve( string $run_id, float $amount ): bool {
+		global $wpdb;
+		$table = PRAutoBlogger_Run_State::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$updated = $wpdb->query(
+			$wpdb->prepare(
+				"UPDATE {$table}
+				SET reserved_usd = reserved_usd + %f, updated_at = %s
+				WHERE run_id = %s
+					AND status IN ('pending','running')
+					AND (reserved_usd + settled_usd + %f) <= ceiling_usd",
+				$amount,
+				current_time( 'mysql' ),
+				$run_id,
+				$amount
+			)
+		);
+		return 1 === (int) $updated;
+	}
+
+	/**
+	 * Handle a failed reservation: halt the run (sticky), record the
+	 * overage, log, throw. The Review Queue lists halted runs; chained
+	 * queue jobs abort via the run-status check.
+	 *
+	 * @param string $run_id  Run UUID.
+	 * @param float  $amount  The estimate that failed to reserve.
+	 * @param string $context Short label for logs.
+	 * @return void
+	 * @throws PRAutoBlogger_Cost_Ceiling_Exception Always.
+	 */
+	private static function on_breach( string $run_id, float $amount, string $context ): void {
+		$run      = PRAutoBlogger_Run_State::get_run( $run_id );
+		$ceiling  = null !== $run ? (float) $run['ceiling_usd'] : 0.0;
+		$held     = null !== $run ? (float) $run['reserved_usd'] + (float) $run['settled_usd'] : 0.0;
+		$overage  = max( ( $held + $amount ) - $ceiling, 0.0 );
+
+		PRAutoBlogger_Run_State::mark_status( $run_id, 'halted' );
+		PRAutoBlogger_Run_State::record_overage( $run_id, $overage );
+
+		$message = sprintf(
+			/* translators: 1: blocked amount USD, 2: call context, 3: committed USD, 4: ceiling USD, 5: run id. */
+			__( 'Per-run cost ceiling reached: reserving $%1$.4f for %2$s would push the run to $%3$.4f against a $%4$.2f ceiling. Run %5$s halted and routed to the Review Queue.', 'prautoblogger' ),
+			$amount,
+			$context,
+			$held + $amount,
+			$ceiling,
+			$run_id
+		);
+
+		PRAutoBlogger_Logger::instance()->error( $message, 'cost-governor' );
+
+		throw new PRAutoBlogger_Cost_Ceiling_Exception( $message );
+	}
+}

includes/core/class-cost-reporter.php

@@ -0,0 +1,203 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Provides historical cost reporting and analysis methods.
+ *
+ * Extracted from PRAutoBlogger_Cost_Tracker, this class handles all read-only
+ * reporting queries: monthly spend, daily spend trends, spend-by-stage breakdowns,
+ * and budget utilization percentage.
+ *
+ * Called by: Metrics dashboard, admin notices, and dashboard widget.
+ * Dependencies: WordPress $wpdb, get_option() for budget configuration.
+ *
+ * @see core/class-cost-tracker.php    — Complementary class for logging and budget enforcement.
+ * @see admin/class-metrics-page.php   — Displays cost reports.
+ * @see admin/class-admin-notices.php  — Shows budget warnings via get_budget_utilization().
+ * @see admin/class-dashboard-widget.php — Displays current month costs.
+ */
+class PRAutoBlogger_Cost_Reporter {
+
+	/**
+	 * Get total estimated spend for the current calendar month.
+	 *
+	 * @return float Total USD spend this month.
+	 */
+	public function get_monthly_spend(): float {
+		global $wpdb;
+		if ( null === $wpdb ) {
+			return 0.0;
+		}
+
+		$table = $wpdb->prefix . 'prautoblogger_generation_log';
+
+		$first_of_month = gmdate( 'Y-m-01 00:00:00' );
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$result = $wpdb->get_var(
+			$wpdb->prepare(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+				"SELECT COALESCE(SUM(estimated_cost), 0) FROM {$table} WHERE created_at >= %s AND response_status = 'success'",
+				$first_of_month
+			)
+		);
+
+		return (float) $result;
+	}
+
+	/**
+	 * Get daily spend for the last N days (for the metrics dashboard chart).
+	 *
+	 * @param int $days Number of days to look back.
+	 *
+	 * @return array<string, float> Associative array of date => total_cost.
+	 */
+	public function get_daily_spend( int $days = 30 ): array {
+		global $wpdb;
+		if ( null === $wpdb ) {
+			return array();
+		}
+
+		$table = $wpdb->prefix . 'prautoblogger_generation_log';
+
+		$start_date = gmdate( 'Y-m-d', time() - ( $days * DAY_IN_SECONDS ) );
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$results = $wpdb->get_results(
+			// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+			$wpdb->prepare(
+				"SELECT DATE(created_at) as day, SUM(estimated_cost) as total_cost
+				FROM {$table}
+				WHERE created_at >= %s AND response_status = 'success'
+				GROUP BY DATE(created_at)
+				ORDER BY day ASC",
+				$start_date . ' 00:00:00'
+			),
+			ARRAY_A
+		);
+
+		$daily = array();
+		foreach ( ( $results ?? array() ) as $row ) {
+			$daily[ $row['day'] ] = (float) $row['total_cost'];
+		}
+
+		return $daily;
+	}
+
+	/**
+	 * Get spend breakdown by pipeline stage for a given period.
+	 *
+	 * @param string $start_date Start date (Y-m-d).
+	 * @param string $end_date   End date (Y-m-d).
+	 *
+	 * @return array<string, array{cost: float, tokens: int, calls: int}> Breakdown by stage.
+	 */
+	public function get_spend_by_stage( string $start_date, string $end_date ): array {
+		global $wpdb;
+		if ( null === $wpdb ) {
+			return array();
+		}
+
+		$table = $wpdb->prefix . 'prautoblogger_generation_log';
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$results = $wpdb->get_results(
+			// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+			$wpdb->prepare(
+				"SELECT stage,
+					SUM(estimated_cost) as total_cost,
+					SUM(prompt_tokens + completion_tokens) as total_tokens,
+					COUNT(*) as call_count
+				FROM {$table}
+				WHERE created_at BETWEEN %s AND %s AND response_status = 'success'
+				GROUP BY stage",
+				$start_date . ' 00:00:00',
+				$end_date . ' 23:59:59'
+			),
+			ARRAY_A
+		);
+
+		$breakdown = array();
+		foreach ( ( $results ?? array() ) as $row ) {
+			$breakdown[ $row['stage'] ] = array(
+				'cost'   => (float) $row['total_cost'],
+				'tokens' => (int) $row['total_tokens'],
+				'calls'  => (int) $row['call_count'],
+			);
+		}
+
+		return $breakdown;
+	}
+
+	/**
+	 * Get budget utilization percentage for the current month.
+	 *
+	 * @return float Percentage (0-100+). Can exceed 100 if overspent.
+	 */
+	public function get_budget_utilization(): float {
+		$budget = (float) get_option( 'prautoblogger_monthly_budget_usd', 50.00 );
+		if ( $budget <= 0 ) {
+			return 0.0;
+		}
+		return ( $this->get_monthly_spend() / $budget ) * 100.0;
+	}
+	/**
+	 * Get average input/output token counts for given stages over a time period.
+	 *
+	 * Used by the model picker field renderer to calculate estimated costs
+	 * per generation based on historical token usage. Maps setting IDs to their
+	 * constituting stages (e.g., writing model controls outline + draft + polish).
+	 * Moved here from Cost_Tracker in v0.18.0 (read-only reporting query;
+	 * Cost_Tracker keeps a delegating wrapper for API compatibility).
+	 *
+	 * @param array<string> $stages Stage names ('analysis', 'outline', 'draft', 'polish', 'review').
+	 * @param int           $days   Historical window (default 30 days).
+	 *
+	 * @return array{avg_prompt_tokens: float, avg_completion_tokens: float, sample_size: int}
+	 *         Returns empty counters if no history. Never throws.
+	 */
+	public function get_avg_tokens_for_stages( array $stages, int $days = 30 ): array {
+		global $wpdb;
+
+		if ( empty( $stages ) ) {
+			return array(
+				'avg_prompt_tokens'      => 0.0,
+				'avg_completion_tokens'  => 0.0,
+				'sample_size'            => 0,
+			);
+		}
+
+		$cutoff_datetime = gmdate( 'Y-m-d H:i:s', time() - ( $days * DAY_IN_SECONDS ) );
+		$stage_list      = implode( ',', array_map( array( $wpdb, 'prepare' ), array_fill( 0, count( $stages ), '%s' ), $stages ) );
+		$table_name      = $wpdb->prefix . 'prautoblogger_generation_log';
+
+		// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- Prepared stage list via array_map + prepare
+		$query = $wpdb->prepare(
+			"SELECT AVG(prompt_tokens) as avg_prompt,
+                    AVG(completion_tokens) as avg_completion,
+                    COUNT(*) as sample_count
+             FROM $table_name
+             WHERE stage IN ( $stage_list )
+             AND created_at >= %s",
+			$cutoff_datetime
+		);
+
+		// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- phpcs pragma above
+		$result = $wpdb->get_row( $query, ARRAY_A );
+
+		if ( ! $result || 0 === (int) ( $result['sample_count'] ?? 0 ) ) {
+			return array(
+				'avg_prompt_tokens'      => 0.0,
+				'avg_completion_tokens'  => 0.0,
+				'sample_size'            => 0,
+			);
+		}
+
+		return array(
+			'avg_prompt_tokens'      => (float) ( $result['avg_prompt'] ?? 0 ),
+			'avg_completion_tokens'  => (float) ( $result['avg_completion'] ?? 0 ),
+			'sample_size'            => (int) ( $result['sample_count'] ?? 0 ),
+		);
+	}
+}

includes/core/class-cost-tracker.php

@@ -2,8 +2,9 @@
 declare(strict_types=1);
 
 /**
- * Tracks all API costs, enforces monthly budget limits, and provides
- * cost reporting data for the admin dashboard.
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Tracks all API costs and enforces monthly budget limits.
  *
  * Every LLM API call in the plugin is logged through this class. The budget
  * enforcement is a hard stop — if the monthly budget is exceeded, no further
@@ -16,7 +17,8 @@ declare(strict_types=1);
  * @see core/class-content-analyzer.php  — Calls log_api_call() after analysis.
  * @see core/class-content-generator.php — Calls log_api_call() after each stage.
  * @see core/class-chief-editor.php      — Calls log_api_call() after review.
- * @see admin/class-metrics-page.php     — Displays cost data from this class.
+ * @see core/class-cost-reporter.php     — Extracted reporting methods (read-only queries).
+ * @see admin/class-metrics-page.php     — Displays cost data via Cost_Reporter.
  * @see ARCHITECTURE.md                  — prab_generation_log table schema.
  */
 class PRAutoBlogger_Cost_Tracker {
@@ -45,6 +47,14 @@ class PRAutoBlogger_Cost_Tracker {
 	 */
 	public function set_run_id( string $run_id ): void {
 		$this->run_id = $run_id;
+		// v0.18.0: declaring a run id makes this PHP process part of that
+		// run — record the context (cost-governor guard, prompt-version
+		// stamping for components without a run reference), make sure the
+		// run ledger row exists, and pin the active prompt versions once.
+		// All three are self-healing no-ops on a half-migrated schema.
+		PRAutoBlogger_Run_Context::set_run_id( $run_id );
+		PRAutoBlogger_Run_State::ensure_run( $run_id );
+		PRAutoBlogger_Prompt_Registry::pin_for_run( $run_id );
 	}
 
 	/**
@@ -61,14 +71,20 @@ class PRAutoBlogger_Cost_Tracker {
 	 *
 	 * Side effects: database insert into prab_generation_log.
 	 *
-	 * @param int|null $post_id           WordPress post ID (null during generation, set later).
-	 * @param string   $stage             Pipeline stage: 'analysis', 'outline', 'draft', 'polish', 'review'.
-	 * @param string   $provider          Provider name: 'OpenRouter'.
-	 * @param string   $model             Model identifier used.
-	 * @param int      $prompt_tokens     Input tokens consumed.
-	 * @param int      $completion_tokens Output tokens generated.
-	 * @param string   $response_status   'success', 'error', or 'timeout'.
-	 * @param string   $error_message     Error details if status is not 'success'.
+	 * @param int|null    $post_id           WordPress post ID (null during generation, set later).
+	 * @param string      $stage             Pipeline stage (see PRAutoBlogger_Stage_Display_Map).
+	 * @param string      $provider          Provider name: 'OpenRouter'.
+	 * @param string      $model             Model identifier used.
+	 * @param int         $prompt_tokens     Input tokens consumed.
+	 * @param int         $completion_tokens Output tokens generated.
+	 * @param string      $response_status   'success', 'error', or 'timeout'.
+	 * @param string      $error_message     Error details if status is not 'success'.
+	 * @param string|null $agent_role        v0.18.0 — role that made the call; derived
+	 *                                       from the stage map when null.
+	 * @param string|null $prompt_key        v0.18.0 — registry key the call rendered
+	 *                                       with (e.g. 'content.single_pass'); derived
+	 *                                       from the stage map when null. Resolves the
+	 *                                       run-pinned prompt_version stamped on the row.
 	 *
 	 * @return void
 	 */
@@ -80,34 +96,50 @@ class PRAutoBlogger_Cost_Tracker {
 		int $prompt_tokens,
 		int $completion_tokens,
 		string $response_status = 'success',
-		string $error_message = ''
+		string $error_message = '',
+		?string $agent_role = null,
+		?string $prompt_key = null
 	): void {
 		$llm  = new PRAutoBlogger_OpenRouter_Provider();
 		$cost = $llm->estimate_cost( $model, $prompt_tokens, $completion_tokens );
 
 		$this->current_run_cost += $cost;
 
-		$log_entry = new PRAutoBlogger_Generation_Log( [
-			'post_id'           => $post_id,
-			'run_id'            => $this->run_id,
-			'stage'             => $stage,
-			'provider'          => $provider,
-			'model'             => $model,
-			'prompt_tokens'     => $prompt_tokens,
-			'completion_tokens' => $completion_tokens,
-			'estimated_cost'    => $cost,
-			'response_status'   => $response_status,
-			'error_message'     => $error_message,
-			'created_at'        => current_time( 'mysql' ),
-		] );
+		$log_entry = new PRAutoBlogger_Generation_Log(
+			array(
+				'post_id'           => $post_id,
+				'run_id'            => $this->run_id,
+				'stage'             => $stage,
+				'provider'          => $provider,
+				'model'             => $model,
+				'prompt_tokens'     => $prompt_tokens,
+				'completion_tokens' => $completion_tokens,
+				'estimated_cost'    => $cost,
+				'response_status'   => $response_status,
+				'error_message'     => $error_message,
+				'agent_role'        => $agent_role ?? PRAutoBlogger_Stage_Display_Map::default_agent_role( $stage ),
+				'prompt_version'    => $this->resolve_prompt_version( $stage, $prompt_key ),
+				'created_at'        => current_time( 'mysql' ),
+			)
+		);
 
 		global $wpdb;
 		$table = $wpdb->prefix . 'prautoblogger_generation_log';
 
 		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-		$wpdb->insert( $table, $log_entry->to_db_row() );
+		$inserted = $wpdb->insert( $table, $log_entry->to_db_row() );
 
-		if ( false === $wpdb->insert_id ) {
+		// Self-healing on a half-migrated schema (e.g. cron fires after a
+		// deploy but before any admin_init migration pass): retry without
+		// the v0.18.0 audit columns rather than losing the cost row.
+		if ( false === $inserted ) {
+			$legacy_row = $log_entry->to_db_row();
+			unset( $legacy_row['agent_role'], $legacy_row['prompt_version'] );
+			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+			$inserted = $wpdb->insert( $table, $legacy_row );
+		}
+
+		if ( false === $inserted || false === $wpdb->insert_id ) {
 			PRAutoBlogger_Logger::instance()->error( 'Failed to log API call: ' . $wpdb->last_error, 'cost-tracker' );
 		}
 	}
@@ -127,7 +159,8 @@ class PRAutoBlogger_Cost_Tracker {
 			return false;
 		}
 
-		$monthly_spend = $this->get_monthly_spend();
+		$reporter      = new PRAutoBlogger_Cost_Reporter();
+		$monthly_spend = $reporter->get_monthly_spend();
 
 		// Round to 4 decimal places (0.01 cent precision) to avoid
 		// floating-point representation artifacts triggering false positives.
@@ -135,25 +168,98 @@ class PRAutoBlogger_Cost_Tracker {
 	}
 
 	/**
-	 * Get total estimated spend for the current calendar month.
+	 * Log an image generation API call with a known cost.
 	 *
-	 * @return float Total USD spend this month.
+	 * Unlike log_api_call() which calculates cost from token counts, image
+	 * generation uses per-megapixel pricing that the image provider already
+	 * computed. This method accepts the pre-calculated cost directly.
+	 *
+	 * @param float  $cost_usd Estimated cost in USD (from image provider pricing).
+	 * @param string $model    Image model alias (e.g. 'flux-1-schnell').
+	 * @param int    $post_id  WordPress post ID the image is attached to.
+	 * @param string $stage    Pipeline stage ('image_a' or 'image_b').
+	 * @return void
 	 */
-	public function get_monthly_spend(): float {
+	public function log_image_generation( float $cost_usd, string $model, int $post_id, string $stage ): void {
+		$this->current_run_cost += $cost_usd;
+
 		global $wpdb;
+		if ( null === $wpdb ) {
+			return;
+		}
 		$table = $wpdb->prefix . 'prautoblogger_generation_log';
 
-		$first_of_month = gmdate( 'Y-m-01 00:00:00' );
-
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-		$result = $wpdb->get_var(
-			$wpdb->prepare(
-				"SELECT COALESCE(SUM(estimated_cost), 0) FROM {$table} WHERE created_at >= %s AND response_status = 'success'",
-				$first_of_month
-			)
+		$row = array(
+			'post_id'           => $post_id,
+			'run_id'            => $this->run_id,
+			'stage'             => $stage,
+			'provider'          => 'cloudflare-workers-ai',
+			'model'             => $model,
+			'prompt_tokens'     => 0,
+			'completion_tokens' => 0,
+			'estimated_cost'    => $cost_usd,
+			'response_status'   => 'success',
+			'error_message'     => '',
+			'agent_role'        => PRAutoBlogger_Stage_Display_Map::default_agent_role( $stage ),
+			'prompt_version'    => $this->resolve_prompt_version( $stage, null ),
+			'created_at'        => current_time( 'mysql' ),
 		);
 
-		return (float) $result;
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$inserted = $wpdb->insert( $table, $row );
+
+		// Self-healing on a half-migrated schema — see log_api_call().
+		if ( false === $inserted ) {
+			unset( $row['agent_role'], $row['prompt_version'] );
+			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+			$wpdb->insert( $table, $row );
+		}
+	}
+
+	/**
+	 * Resolve the pinned prompt version to stamp on a log row.
+	 *
+	 * Uses the explicit registry key when the call site passed one,
+	 * otherwise the stage's primary key from the display map. The version
+	 * comes from the run's pins; the run is this tracker's run_id or —
+	 * for standalone trackers inside a pipeline process (e.g. the image
+	 * prompt rewriter's) — the process-level run context. Null when there
+	 * is no run, no pins, or no key (historical behavior preserved).
+	 *
+	 * @param string      $stage      Stage being logged.
+	 * @param string|null $prompt_key Explicit registry key, or null to derive.
+	 * @return string|null Pinned version as string, or null.
+	 */
+	private function resolve_prompt_version( string $stage, ?string $prompt_key ): ?string {
+		$key = $prompt_key ?? PRAutoBlogger_Stage_Display_Map::default_prompt_key( $stage );
+		if ( null === $key ) {
+			return null;
+		}
+		$run_id = $this->run_id ?? PRAutoBlogger_Run_Context::current_run_id();
+		$pins   = PRAutoBlogger_Prompt_Registry::pins_for_run( $run_id );
+		return isset( $pins[ $key ] ) ? (string) $pins[ $key ] : null;
+	}
+
+	/**
+	 * Check if adding an estimated cost would exceed the monthly budget.
+	 *
+	 * Unlike is_budget_exceeded() which checks current state, this method
+	 * proactively checks whether a planned expenditure would push spend
+	 * over the budget. Used by the image pipeline to pre-check before
+	 * making an API call.
+	 *
+	 * @param float $estimated_cost_usd Estimated cost in USD for the planned operation.
+	 * @return bool True if (current spend + estimated cost) >= configured budget.
+	 */
+	public function would_exceed_budget( float $estimated_cost_usd ): bool {
+		$budget = (float) get_option( 'prautoblogger_monthly_budget_usd', 50.00 );
+		if ( $budget <= 0 ) {
+			return false;
+		}
+
+		$reporter  = new PRAutoBlogger_Cost_Reporter();
+		$projected = $reporter->get_monthly_spend() + $estimated_cost_usd;
+		return round( $projected, 4 ) >= round( $budget, 4 );
 	}
 
 	/**
@@ -166,89 +272,19 @@ class PRAutoBlogger_Cost_Tracker {
 	}
 
 	/**
-	 * Get daily spend for the last N days (for the metrics dashboard chart).
+	 * Get average input/output token counts for given stages over a time period.
 	 *
-	 * @param int $days Number of days to look back.
+	 * Thin delegate to PRAutoBlogger_Cost_Reporter (the read-only reporting
+	 * class) — kept here for API compatibility with the model-picker field
+	 * and existing tests. See Cost_Reporter for the query.
 	 *
-	 * @return array<string, float> Associative array of date => total_cost.
+	 * @param array<string> $stages Stage names ('analysis', 'outline', 'draft', 'polish', 'review').
+	 * @param int           $days   Historical window (default 30 days).
+	 *
+	 * @return array{avg_prompt_tokens: float, avg_completion_tokens: float, sample_size: int}
+	 *         Returns empty counters if no history. Never throws.
 	 */
-	public function get_daily_spend( int $days = 30 ): array {
-		global $wpdb;
-		$table = $wpdb->prefix . 'prautoblogger_generation_log';
-
-		$start_date = gmdate( 'Y-m-d', time() - ( $days * DAY_IN_SECONDS ) );
-
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-		$results = $wpdb->get_results(
-			$wpdb->prepare(
-				"SELECT DATE(created_at) as day, SUM(estimated_cost) as total_cost
-				FROM {$table}
-				WHERE created_at >= %s AND response_status = 'success'
-				GROUP BY DATE(created_at)
-				ORDER BY day ASC",
-				$start_date . ' 00:00:00'
-			),
-			ARRAY_A
-		);
-
-		$daily = [];
-		foreach ( ( $results ?: [] ) as $row ) {
-			$daily[ $row['day'] ] = (float) $row['total_cost'];
-		}
-
-		return $daily;
-	}
-
-	/**
-	 * Get spend breakdown by pipeline stage for a given period.
-	 *
-	 * @param string $start_date Start date (Y-m-d).
-	 * @param string $end_date   End date (Y-m-d).
-	 *
-	 * @return array<string, array{cost: float, tokens: int, calls: int}> Breakdown by stage.
-	 */
-	public function get_spend_by_stage( string $start_date, string $end_date ): array {
-		global $wpdb;
-		$table = $wpdb->prefix . 'prautoblogger_generation_log';
-
-		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-		$results = $wpdb->get_results(
-			$wpdb->prepare(
-				"SELECT stage,
-					SUM(estimated_cost) as total_cost,
-					SUM(prompt_tokens + completion_tokens) as total_tokens,
-					COUNT(*) as call_count
-				FROM {$table}
-				WHERE created_at BETWEEN %s AND %s AND response_status = 'success'
-				GROUP BY stage",
-				$start_date . ' 00:00:00',
-				$end_date . ' 23:59:59'
-			),
-			ARRAY_A
-		);
-
-		$breakdown = [];
-		foreach ( ( $results ?: [] ) as $row ) {
-			$breakdown[ $row['stage'] ] = [
-				'cost'   => (float) $row['total_cost'],
-				'tokens' => (int) $row['total_tokens'],
-				'calls'  => (int) $row['call_count'],
-			];
-		}
-
-		return $breakdown;
-	}
-
-	/**
-	 * Get budget utilization percentage for the current month.
-	 *
-	 * @return float Percentage (0-100+). Can exceed 100 if overspent.
-	 */
-	public function get_budget_utilization(): float {
-		$budget = (float) get_option( 'prautoblogger_monthly_budget_usd', 50.00 );
-		if ( $budget <= 0 ) {
-			return 0.0;
-		}
-		return ( $this->get_monthly_spend() / $budget ) * 100.0;
+	public function get_avg_tokens_for_stages( array $stages, int $days = 30 ): array {
+		return ( new PRAutoBlogger_Cost_Reporter() )->get_avg_tokens_for_stages( $stages, $days );
 	}
 }

includes/core/class-ga4-client.php

@@ -2,6 +2,8 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Google Analytics 4 API client for fetching post performance metrics.
  *
  * Handles OAuth2 service account authentication and the GA4 Data API.
@@ -29,32 +31,32 @@ class PRAutoBlogger_GA4_Client {
 	public function fetch_data( array $posts ): array {
 		$property_id = get_option( 'prautoblogger_ga4_property_id', '' );
 		if ( '' === $property_id ) {
-			return [];
+			return array();
 		}
 
 		$credentials_encrypted = get_option( 'prautoblogger_ga4_credentials_json', '' );
 		if ( '' === $credentials_encrypted ) {
-			return [];
+			return array();
 		}
 
 		$credentials = PRAutoBlogger_Encryption::decrypt( $credentials_encrypted );
 		if ( '' === $credentials ) {
-			return [];
+			return array();
 		}
 
 		// Build page paths for the GA4 query.
-		$page_paths = [];
-		$path_to_id = [];
+		$page_paths = array();
+		$path_to_id = array();
 		foreach ( $posts as $post ) {
 			$path = wp_parse_url( get_permalink( $post->ID ), PHP_URL_PATH );
 			if ( $path ) {
-				$page_paths[]         = $path;
+				$page_paths[]        = $path;
 				$path_to_id[ $path ] = (int) $post->ID;
 			}
 		}
 
 		if ( empty( $page_paths ) ) {
-			return [];
+			return array();
 		}
 
 		// GA4 Data API request.
@@ -62,40 +64,45 @@ class PRAutoBlogger_GA4_Client {
 		$access_token = $this->get_access_token( $credentials );
 		if ( '' === $access_token ) {
 			PRAutoBlogger_Logger::instance()->error( 'GA4: Failed to get access token. Possible causes: invalid service account JSON, expired or revoked private key, or network error reaching oauth2.googleapis.com. Verify credentials in PRAutoBlogger → Settings.', 'ga4' );
-			return [];
+			return array();
 		}
 
-		$request_body = [
-			'dateRanges'  => [ [ 'startDate' => '30daysAgo', 'endDate' => 'today' ] ],
-			'dimensions'  => [ [ 'name' => 'pagePath' ] ],
-			'metrics'     => [
-				[ 'name' => 'screenPageViews' ],
-				[ 'name' => 'averageSessionDuration' ],
-				[ 'name' => 'bounceRate' ],
-			],
-			'dimensionFilter' => [
-				'filter' => [
+		$request_body = array(
+			'dateRanges'      => array(
+				array(
+					'startDate' => '30daysAgo',
+					'endDate'   => 'today',
+				),
+			),
+			'dimensions'      => array( array( 'name' => 'pagePath' ) ),
+			'metrics'         => array(
+				array( 'name' => 'screenPageViews' ),
+				array( 'name' => 'averageSessionDuration' ),
+				array( 'name' => 'bounceRate' ),
+			),
+			'dimensionFilter' => array(
+				'filter' => array(
 					'fieldName'    => 'pagePath',
-					'inListFilter' => [ 'values' => $page_paths ],
-				],
-			],
-		];
+					'inListFilter' => array( 'values' => $page_paths ),
+				),
+			),
+		);
 
 		$response = wp_remote_post(
 			"https://analyticsdata.googleapis.com/v1beta/properties/{$property_id}:runReport",
-			[
+			array(
 				'timeout' => 30,
-				'headers' => [
+				'headers' => array(
 					'Authorization' => 'Bearer ' . $access_token,
 					'Content-Type'  => 'application/json',
-				],
+				),
 				'body'    => wp_json_encode( $request_body ),
-			]
+			)
 		);
 
 		if ( is_wp_error( $response ) ) {
 			PRAutoBlogger_Logger::instance()->error( 'GA4 API request failed (WP HTTP error): ' . $response->get_error_message(), 'ga4' );
-			return [];
+			return array();
 		}
 
 		$ga4_status = wp_remote_retrieve_response_code( $response );
@@ -105,20 +112,20 @@ class PRAutoBlogger_GA4_Client {
 				sprintf( 'GA4 API request failed (HTTP %d): %s', $ga4_status, substr( $ga4_body, 0, 500 ) ),
 				'ga4'
 			);
-			return [];
+			return array();
 		}
 
 		$data    = json_decode( wp_remote_retrieve_body( $response ), true );
-		$results = [];
+		$results = array();
 
-		foreach ( ( $data['rows'] ?? [] ) as $row ) {
+		foreach ( ( $data['rows'] ?? array() ) as $row ) {
 			$path = $row['dimensionValues'][0]['value'] ?? '';
 			if ( isset( $path_to_id[ $path ] ) ) {
-				$results[ $path_to_id[ $path ] ] = [
+				$results[ $path_to_id[ $path ] ] = array(
 					'pageviews'        => (int) ( $row['metricValues'][0]['value'] ?? 0 ),
 					'avg_time_on_page' => (float) ( $row['metricValues'][1]['value'] ?? 0 ),
 					'bounce_rate'      => (float) ( $row['metricValues'][2]['value'] ?? 0 ),
-				];
+				);
 			}
 		}
 
@@ -140,19 +147,26 @@ class PRAutoBlogger_GA4_Client {
 
 		// Build JWT for service account auth.
 		$now    = time();
-		$header = wp_json_encode( [ 'alg' => 'RS256', 'typ' => 'JWT' ] );
-		$claim  = wp_json_encode( [
-			'iss'   => $creds['client_email'],
-			'scope' => 'https://www.googleapis.com/auth/analytics.readonly',
-			'aud'   => 'https://oauth2.googleapis.com/token',
-			'exp'   => $now + 3600,
-			'iat'   => $now,
-		] );
+		$header = wp_json_encode(
+			array(
+				'alg' => 'RS256',
+				'typ' => 'JWT',
+			)
+		);
+		$claim  = wp_json_encode(
+			array(
+				'iss'   => $creds['client_email'],
+				'scope' => 'https://www.googleapis.com/auth/analytics.readonly',
+				'aud'   => 'https://oauth2.googleapis.com/token',
+				'exp'   => $now + 3600,
+				'iat'   => $now,
+			)
+		);
 
 		// phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode
 		$base64_header = rtrim( strtr( base64_encode( $header ), '+/', '-_' ), '=' );
 		// phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode
-		$base64_claim  = rtrim( strtr( base64_encode( $claim ), '+/', '-_' ), '=' );
+		$base64_claim = rtrim( strtr( base64_encode( $claim ), '+/', '-_' ), '=' );
 
 		$signing_input = $base64_header . '.' . $base64_claim;
 		$signature     = '';
@@ -171,13 +185,13 @@ class PRAutoBlogger_GA4_Client {
 
 		$response = wp_remote_post(
 			'https://oauth2.googleapis.com/token',
-			[
+			array(
 				'timeout' => 15,
-				'body'    => [
+				'body'    => array(
 					'grant_type' => 'urn:ietf:params:oauth:grant-type:jwt-bearer',
 					'assertion'  => $jwt,
-				],
-			]
+				),
+			)
 		);
 
 		if ( is_wp_error( $response ) ) {

includes/core/class-idea-scorer.php

@@ -2,27 +2,29 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Ranks and deduplicates article ideas from analysis results.
  *
- * Compares against existing published posts to avoid topic overlap,
- * scores ideas by relevance, frequency, and freshness, then returns
- * the top N ideas matching the daily target.
+ * Uses PRAutoBlogger_Semantic_Dedup for similarity detection — embedding-based
+ * cosine similarity with automatic fallback to keyword overlap if the embedding
+ * API is unavailable.
  *
- * Triggered by: PRAutoBlogger::run_generation_pipeline() (step 3).
- * Dependencies: WordPress $wpdb, WP_Query.
+ * Triggered by: PRAutoBlogger_Pipeline_Runner (step 3).
+ * Dependencies: Semantic_Dedup, WP_Query.
  *
+ * @see core/class-semantic-dedup.php    — Embedding + keyword dedup engine.
  * @see core/class-content-analyzer.php  — Produces the analysis results we consume.
  * @see core/class-content-generator.php — Consumes the ranked ideas we produce.
  * @see ARCHITECTURE.md                  — Data flow step 3.
  */
 class PRAutoBlogger_Idea_Scorer {
 
-	/** @var bool Whether to skip the has_similar_post() check. */
+	/** @var bool Whether to skip deduplication entirely. */
 	private bool $skip_dedup = false;
 
 	/**
 	 * @param bool $skip True to skip deduplication.
-	 *
 	 * @return $this
 	 */
 	public function set_skip_dedup( bool $skip ): self {
@@ -33,50 +35,97 @@ class PRAutoBlogger_Idea_Scorer {
 	/**
 	 * Score, deduplicate, and rank article ideas.
 	 *
-	 * @param PRAutoBlogger_Analysis_Result[] $analysis_results Raw analysis output.
-	 * @param int                           $target_count     Number of ideas to return.
+	 * Initializes the semantic dedup engine once, then checks each candidate
+	 * against (1) intra-batch duplicates and (2) recently published posts.
 	 *
-	 * @return PRAutoBlogger_Article_Idea[] Top-ranked ideas, sorted by score descending.
+	 * Side effects: embedding API calls (via Semantic_Dedup), WP_Query.
+	 *
+	 * @param PRAutoBlogger_Analysis_Result[] $analysis_results Raw analysis output.
+	 * @param int                             $target_count     Max ideas to return.
+	 *
+	 * @return PRAutoBlogger_Article_Idea[] Top-ranked ideas, sorted by score desc.
 	 */
 	public function score_and_rank( array $analysis_results, int $target_count ): array {
-		$exclusions = json_decode( get_option( 'prautoblogger_topic_exclusions', '[]' ), true ) ?: [];
-		$ideas      = [];
+		$exclusions     = json_decode( get_option( 'prautoblogger_topic_exclusions', '[]' ), true ) ?? array();
+		$ideas          = array();
+		$excluded_count = 0;
+		$deduped_count  = 0;
 
-		foreach ( $analysis_results as $result ) {
-			// Skip excluded topics.
-			if ( $this->is_excluded( $result->get_topic(), $exclusions ) ) {
-				continue;
-			}
-
-			// Skip if we've already published something very similar
-			// (unless dedup is disabled for manual runs).
-			if ( ! $this->skip_dedup && $this->has_similar_post( $result->get_topic() ) ) {
-				PRAutoBlogger_Logger::instance()->info(
-					sprintf( 'Skipping topic "%s" — similar post exists.', substr( $result->get_topic(), 0, 80 ) ),
-					'scorer'
-				);
-				continue;
-			}
-
-			$metadata = $result->get_metadata() ?? [];
-
-			$ideas[] = new PRAutoBlogger_Article_Idea( [
-				'topic'           => $result->get_topic(),
-				'article_type'    => $this->map_type( $result->get_analysis_type() ),
-				'suggested_title' => $metadata['suggested_title'] ?? $result->get_topic(),
-				'summary'         => $result->get_summary() ?? '',
-				'score'           => $this->compute_score( $result ),
-				'analysis_id'     => $result->get_id(),
-				'source_ids'      => $result->get_source_ids(),
-				'key_points'      => $metadata['key_points'] ?? [],
-				'target_keywords' => $metadata['target_keywords'] ?? [],
-			] );
+		$dedup = new PRAutoBlogger_Semantic_Dedup();
+		if ( ! $this->skip_dedup ) {
+			$dedup->initialize();
 		}
 
-		// Sort by score descending.
-		usort( $ideas, static function ( PRAutoBlogger_Article_Idea $a, PRAutoBlogger_Article_Idea $b ): int {
-			return $b->get_score() <=> $a->get_score();
-		} );
+		// Keyword sets kept for fallback (passed through to Semantic_Dedup).
+		$accepted_keyword_sets = array();
+
+		foreach ( $analysis_results as $result ) {
+			if ( $this->is_excluded( $result->get_topic(), $exclusions ) ) {
+				++$excluded_count;
+				continue;
+			}
+
+			if ( ! $this->skip_dedup ) {
+				$topic          = $result->get_topic();
+				$topic_keywords = $this->extract_meaningful_keywords( $topic );
+
+				if ( $dedup->is_batch_duplicate( $topic, $topic_keywords, $accepted_keyword_sets ) ) {
+					++$deduped_count;
+					PRAutoBlogger_Logger::instance()->info(
+						sprintf( 'Dedup(batch): skipping "%s"', substr( $topic, 0, 80 ) ),
+						'scorer'
+					);
+					continue;
+				}
+
+				if ( $dedup->is_recent_duplicate( $topic, $topic_keywords ) ) {
+					++$deduped_count;
+					PRAutoBlogger_Logger::instance()->info(
+						sprintf( 'Dedup(recent): skipping "%s"', substr( $topic, 0, 80 ) ),
+						'scorer'
+					);
+					continue;
+				}
+
+				$accepted_keyword_sets[] = $topic_keywords;
+				$dedup->record_accepted( $topic );
+			}
+
+			$metadata = $result->get_metadata() ?? array();
+
+			$ideas[] = new PRAutoBlogger_Article_Idea(
+				array(
+					'topic'           => $result->get_topic(),
+					'article_type'    => $this->map_type( $result->get_analysis_type() ),
+					'suggested_title' => $metadata['suggested_title'] ?? $result->get_topic(),
+					'summary'         => $result->get_summary() ?? '',
+					'score'           => $this->compute_score( $result ),
+					'analysis_id'     => $result->get_id(),
+					'source_ids'      => $result->get_source_ids(),
+					'key_points'      => $metadata['key_points'] ?? array(),
+					'target_keywords' => $metadata['target_keywords'] ?? array(),
+				)
+			);
+		}
+
+		PRAutoBlogger_Logger::instance()->info(
+			sprintf(
+				'Scorer: %d input → %d viable, %d deduped, %d excluded. Returning top %d.',
+				count( $analysis_results ),
+				count( $ideas ),
+				$deduped_count,
+				$excluded_count,
+				min( $target_count, count( $ideas ) )
+			),
+			'scorer'
+		);
+
+		usort(
+			$ideas,
+			static function ( PRAutoBlogger_Article_Idea $a, PRAutoBlogger_Article_Idea $b ): int {
+				return $b->get_score() <=> $a->get_score();
+			}
+		);
 
 		return array_slice( $ideas, 0, $target_count );
 	}
@@ -87,14 +136,12 @@ class PRAutoBlogger_Idea_Scorer {
 	 * Factors: LLM relevance score (50%), frequency (30%), recency bonus (20%).
 	 *
 	 * @param PRAutoBlogger_Analysis_Result $result
-	 *
 	 * @return float Score between 0 and 1.
 	 */
 	private function compute_score( PRAutoBlogger_Analysis_Result $result ): float {
 		$relevance = min( $result->get_relevance_score(), 1.0 );
 		$frequency = min( $result->get_frequency() / 10.0, 1.0 );
 
-		// Recency: analyzed within last 24h gets full bonus.
 		$hours_ago = ( time() - strtotime( $result->get_analyzed_at() ) ) / 3600.0;
 		$recency   = max( 0.0, 1.0 - ( $hours_ago / 48.0 ) );
 
@@ -106,7 +153,6 @@ class PRAutoBlogger_Idea_Scorer {
 	 *
 	 * @param string   $topic      Topic text.
 	 * @param string[] $exclusions List of excluded terms/phrases.
-	 *
 	 * @return bool
 	 */
 	private function is_excluded( string $topic, array $exclusions ): bool {
@@ -120,43 +166,146 @@ class PRAutoBlogger_Idea_Scorer {
 	}
 
 	/**
-	 * Check if a substantially similar post already exists.
+	 * Extract meaningful keywords from a text string (for fallback dedup).
 	 *
-	 * Uses a simple keyword overlap check against existing published post titles.
-	 *
-	 * @param string $topic Topic to check.
-	 *
-	 * @return bool True if a similar post exists.
+	 * @param string $text Input text.
+	 * @return string[] Unique lowercase keywords.
 	 */
-	private function has_similar_post( string $topic ): bool {
-		$query = new \WP_Query( [
-			'post_type'      => 'post',
-			'post_status'    => [ 'publish', 'draft', 'pending' ],
-			'meta_key'       => '_prautoblogger_generated',
-			'meta_value'     => '1',
-			's'              => $topic,
-			'posts_per_page' => 1,
-			'fields'         => 'ids',
-		] );
+	private function extract_meaningful_keywords( string $text ): array {
+		static $stopwords = array(
+			'a',
+			'an',
+			'the',
+			'and',
+			'or',
+			'but',
+			'is',
+			'are',
+			'was',
+			'were',
+			'in',
+			'on',
+			'at',
+			'to',
+			'for',
+			'of',
+			'with',
+			'by',
+			'from',
+			'as',
+			'it',
+			'its',
+			'this',
+			'that',
+			'your',
+			'you',
+			'how',
+			'what',
+			'when',
+			'why',
+			'where',
+			'which',
+			'who',
+			'do',
+			'does',
+			'did',
+			'not',
+			'no',
+			'can',
+			'will',
+			'should',
+			'could',
+			'would',
+			'may',
+			'might',
+			'have',
+			'has',
+			'had',
+			'be',
+			'been',
+			'being',
+			'about',
+			'into',
+			'through',
+			'during',
+			'before',
+			'after',
+			'above',
+			'below',
+			'between',
+			'same',
+			'up',
+			'down',
+			'out',
+			'off',
+			'over',
+			'under',
+			'again',
+			'then',
+			'here',
+			'there',
+			'all',
+			'each',
+			'every',
+			'both',
+			'few',
+			'more',
+			'most',
+			'other',
+			'some',
+			'such',
+			'than',
+			'too',
+			'very',
+			'just',
+			'also',
+			'only',
+			'own',
+			'so',
+			'if',
+			'while',
+			'because',
+			'until',
+			'vs',
+			'versus',
+			'guide',
+			'complete',
+			'ultimate',
+			'best',
+			'top',
+			'new',
+			'first',
+			'need',
+			'know',
+			'everything',
+		);
 
-		return $query->found_posts > 0;
+		$text  = strtolower( $text );
+		$words = preg_split( '/[^a-z0-9-]+/', $text, -1, PREG_SPLIT_NO_EMPTY );
+		$words = array_filter(
+			$words,
+			static function ( string $w ) use ( $stopwords ): bool {
+				return strlen( $w ) >= 2 && ! in_array( $w, $stopwords, true );
+			}
+		);
+
+		return array_values( array_unique( $words ) );
 	}
 
 	/**
 	 * Map analysis type to a reader-friendly article type.
 	 *
-	 * @param string $analysis_type 'question', 'complaint', 'comparison'.
-	 *
+	 * @param string $analysis_type 'question', 'complaint', 'comparison', etc.
 	 * @return string Article type label.
 	 */
 	private function map_type( string $analysis_type ): string {
-		$map = [
+		$map = array(
 			'question'   => 'guide',
 			'complaint'  => 'solution',
 			'comparison' => 'comparison',
 			'news'       => 'news',
 			'guide'      => 'guide',
-		];
+		);
 		return $map[ $analysis_type ] ?? 'article';
 	}
 }

includes/core/class-image-attacher.php

@@ -0,0 +1,169 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Persists generated images and composed variants for a post.
+ *
+ * Owns the media-library side of the image pipeline: sideloading the primary
+ * (featured) image with cost logging, sideloading composed OG/square variants
+ * with role/base meta-linking (no cost-tracker entries — composition is $0
+ * local CPU), and prepending the editable HTML caption to the post. Extracted
+ * from PRAutoBlogger_Image_Pipeline in v0.17.0 for 300-line compliance.
+ *
+ * Triggered by: PRAutoBlogger_Image_Pipeline during content generation run.
+ * Dependencies: PRAutoBlogger_Image_Media_Sideloader, PRAutoBlogger_Cost_Tracker,
+ *               PRAutoBlogger_Logger.
+ *
+ * @see core/class-image-pipeline.php         — Sole caller.
+ * @see core/class-image-composer.php         — Produces the variants this persists.
+ * @see core/class-image-media-sideloader.php — Media library import.
+ */
+class PRAutoBlogger_Image_Attacher {
+
+	/** Post meta key per composed variant role. */
+	private const ROLE_POST_META = array(
+		'og'     => '_prautoblogger_og_image_id',
+		'square' => '_prautoblogger_square_image_id',
+	);
+
+	/** @var PRAutoBlogger_Image_Media_Sideloader Imports bytes into the media library. */
+	private PRAutoBlogger_Image_Media_Sideloader $sideloader;
+
+	/** @var PRAutoBlogger_Cost_Tracker Logs primary image generation spend. */
+	private PRAutoBlogger_Cost_Tracker $cost_tracker;
+
+	/**
+	 * Construct with the pipeline's sideloader + cost tracker.
+	 *
+	 * @param PRAutoBlogger_Image_Media_Sideloader $sideloader   Media importer.
+	 * @param PRAutoBlogger_Cost_Tracker           $cost_tracker Spend logger.
+	 */
+	public function __construct( PRAutoBlogger_Image_Media_Sideloader $sideloader, PRAutoBlogger_Cost_Tracker $cost_tracker ) {
+		$this->sideloader   = $sideloader;
+		$this->cost_tracker = $cost_tracker;
+	}
+
+	/**
+	 * Sideload a primary image into the media library and log its cost.
+	 *
+	 * Side effects: media import, cost-tracker row, info log.
+	 *
+	 * @param array  $image_data Provider result with bytes, model, cost_usd.
+	 * @param int    $post_id    Post ID.
+	 * @param string $slot       Cost-tracking slot ('image_a' or 'image_b').
+	 * @param string $label      Human-readable label for logs.
+	 * @param string $alt_text   Alt text — the editorial caption (v0.17.0 bug
+	 *                           fix: previously the model name leaked here).
+	 *
+	 * @return int|\WP_Error Attachment ID on success.
+	 */
+	public function sideload_and_log( array $image_data, int $post_id, string $slot, string $label, string $alt_text = '' ) {
+		$attachment_id = $this->sideloader->sideload_image( $image_data, $post_id, $alt_text );
+
+		if ( is_wp_error( $attachment_id ) ) {
+			return $attachment_id;
+		}
+
+		$this->cost_tracker->log_image_generation(
+			$image_data['cost_usd'],
+			$image_data['model'] ?? 'unknown',
+			$post_id,
+			$slot
+		);
+
+		PRAutoBlogger_Logger::instance()->info(
+			sprintf( '%s for post %d (att %d, $%.4f)', $label, $post_id, $attachment_id, $image_data['cost_usd'] ),
+			'image_pipeline'
+		);
+
+		return $attachment_id;
+	}
+
+	/**
+	 * Sideload composed variants and meta-link them to post + base image.
+	 *
+	 * Each variant attachment gets `_prautoblogger_image_role` and
+	 * `_prautoblogger_base_attachment_id`; the post gets the role-specific
+	 * ID meta (see ROLE_POST_META). No cost-tracker entries — composition is
+	 * a $0 local stage. A failed variant sideload logs a WARNING and is
+	 * skipped; it never blocks the publish.
+	 *
+	 * @param array  $variants           Composed variants (role 'og'/'square' only are persisted).
+	 * @param int    $post_id            Post ID.
+	 * @param int    $base_attachment_id Featured attachment the variants derive from.
+	 * @param string $caption            Editorial caption (used as variant alt text).
+	 * @param string $model              Generation model recorded on the variant attachment.
+	 */
+	public function attach_variants( array $variants, int $post_id, int $base_attachment_id, string $caption, string $model ): void {
+		foreach ( $variants as $variant ) {
+			$role = (string) ( $variant['role'] ?? '' );
+			if ( ! isset( self::ROLE_POST_META[ $role ] ) ) {
+				continue;
+			}
+
+			$attachment_id = $this->sideloader->sideload_image(
+				array(
+					'bytes'      => (string) ( $variant['bytes'] ?? '' ),
+					'mime_type'  => (string) ( $variant['mime_type'] ?? 'image/png' ),
+					'width'      => (int) ( $variant['width'] ?? 0 ),
+					'height'     => (int) ( $variant['height'] ?? 0 ),
+					'model'      => $model,
+					'cost_usd'   => 0.0,
+					'latency_ms' => 0,
+				),
+				$post_id,
+				$caption,
+				$role
+			);
+
+			if ( is_wp_error( $attachment_id ) ) {
+				PRAutoBlogger_Logger::instance()->warning(
+					sprintf( 'Failed to sideload %s variant for post %d: %s', $role, $post_id, $attachment_id->get_error_message() ),
+					'image_composer'
+				);
+				continue;
+			}
+
+			update_post_meta( $attachment_id, '_prautoblogger_image_role', $role );
+			update_post_meta( $attachment_id, '_prautoblogger_base_attachment_id', $base_attachment_id );
+			update_post_meta( $post_id, self::ROLE_POST_META[ $role ], $attachment_id );
+
+			PRAutoBlogger_Logger::instance()->info(
+				sprintf( '%s variant for post %d (att %d, %dx%d)', $role, $post_id, $attachment_id, (int) $variant['width'], (int) $variant['height'] ),
+				'image_composer'
+			);
+		}
+	}
+
+	/**
+	 * Prepend the editorial caption as styled text at the top of the post.
+	 *
+	 * Only inserts the caption — NOT the image. The theme already displays
+	 * the featured image, so embedding it again would cause a duplicate.
+	 *
+	 * @param int    $post_id       Post ID.
+	 * @param int    $attachment_id Featured image attachment ID (unused; kept for parity with meta storage).
+	 * @param string $caption       Caption text shown below the image.
+	 */
+	public function prepend_caption_to_post( int $post_id, int $attachment_id, string $caption ): void {
+		$post = get_post( $post_id );
+		if ( ! $post ) {
+			return;
+		}
+
+		// Caption-only block — the theme handles the featured image display.
+		$caption_html = sprintf(
+			'<p class="prautoblogger-comic-caption" style="text-align:center;font-style:italic;color:#555;font-size:1.1em;margin:0 0 2em 0;">— "%s"</p>',
+			esc_html( $caption )
+		);
+
+		wp_update_post(
+			array(
+				'ID'           => $post_id,
+				'post_content' => $caption_html . "\n\n" . $post->post_content,
+			)
+		);
+	}
+}

includes/core/class-image-composer-canvas.php

@@ -0,0 +1,186 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Low-level Imagick canvas primitives for the deterministic image composer.
+ *
+ * Capability smoke test, base-image loading, cover-cropping, logo placement,
+ * and deterministic PNG encoding. No WordPress functions anywhere in this
+ * class — it runs unchanged inside the standalone render harness used to
+ * produce the PR sample images.
+ *
+ * Triggered by: PRAutoBlogger_Image_Composer_Imagick (renderer) per variant.
+ * Dependencies: ext-imagick (callers must gate on is_imagick_usable()).
+ *
+ * @see core/class-image-composer-imagick.php — Sole consumer.
+ * @see core/class-image-composer.php         — Caches the capability probe result.
+ */
+class PRAutoBlogger_Image_Composer_Canvas {
+
+	/**
+	 * Probe whether Imagick can do everything the renderer needs: PNG
+	 * encode plus TTF text annotation (the smoke test draws one glyph on a
+	 * tiny in-memory canvas). Cheap to run but callers should cache it.
+	 *
+	 * Side effects: none beyond a transient in-memory Imagick object.
+	 *
+	 * @param string $font_path Absolute path to a bundled TTF used for the smoke test.
+	 *
+	 * @return bool True when full compositing is available.
+	 */
+	public static function is_imagick_usable( string $font_path ): bool {
+		if ( ! extension_loaded( 'imagick' ) || ! class_exists( '\Imagick' ) ) {
+			return false;
+		}
+
+		try {
+			$formats = \Imagick::queryFormats( 'PNG' );
+			if ( empty( $formats ) ) {
+				return false;
+			}
+
+			if ( ! is_readable( $font_path ) ) {
+				return false;
+			}
+
+			$probe = new \Imagick();
+			$probe->newImage( 8, 8, new \ImagickPixel( '#ffffff' ), 'png' );
+			$draw = new \ImagickDraw();
+			$draw->setFont( $font_path );
+			$draw->setFontSize( 6 );
+			$probe->annotateImage( $draw, 1, 6, 0.0, 'P' );
+			$probe->clear();
+
+			return true;
+		} catch ( \Throwable $e ) {
+			return false;
+		}
+	}
+
+	/**
+	 * Load base image bytes into an Imagick object (first frame only).
+	 *
+	 * @param string $bytes Raw image bytes (PNG/JPEG/WebP — any readable format).
+	 *
+	 * @return \Imagick Loaded image.
+	 * @throws \RuntimeException When the bytes cannot be decoded.
+	 */
+	public static function load_base( string $bytes ): \Imagick {
+		$image = new \Imagick();
+		if ( ! $image->readImageBlob( $bytes ) ) {
+			throw new \RuntimeException( 'Composer could not decode base image bytes.' );
+		}
+		$image->setIteratorIndex( 0 );
+		$image = $image->coalesceImages()->current();
+		$image->setImagePage( 0, 0, 0, 0 );
+
+		return $image;
+	}
+
+	/**
+	 * Center cover-crop an image to exact target dimensions without upscaling.
+	 *
+	 * Crops the largest centered region matching the target aspect ratio,
+	 * then scales DOWN to the target. Refuses (returns false) when the source
+	 * is too small to fill the target without upscaling.
+	 *
+	 * Side effects: mutates $image in place on success.
+	 *
+	 * @param \Imagick $image  Source image (mutated).
+	 * @param int      $target_w Target width in px.
+	 * @param int      $target_h Target height in px.
+	 *
+	 * @return bool False when the crop would require upscaling.
+	 */
+	public static function cover_crop( \Imagick $image, int $target_w, int $target_h ): bool {
+		$width  = $image->getImageWidth();
+		$height = $image->getImageHeight();
+		if ( $width < 1 || $height < 1 ) {
+			return false;
+		}
+
+		$ratio = max( $target_w / $width, $target_h / $height );
+		if ( $ratio > 1.0 ) {
+			return false;
+		}
+
+		$src_w = min( $width, (int) round( $target_w / $ratio ) );
+		$src_h = min( $height, (int) round( $target_h / $ratio ) );
+		$x     = (int) floor( ( $width - $src_w ) / 2 );
+		$y     = (int) floor( ( $height - $src_h ) / 2 );
+
+		$image->cropImage( $src_w, $src_h, $x, $y );
+		$image->setImagePage( 0, 0, 0, 0 );
+		$image->resizeImage( $target_w, $target_h, \Imagick::FILTER_LANCZOS, 1 );
+
+		return true;
+	}
+
+	/**
+	 * Composite a brand PNG onto the canvas at a target height and opacity.
+	 *
+	 * @param \Imagick $canvas     Destination canvas (mutated).
+	 * @param string   $asset_path Absolute path to the brand PNG.
+	 * @param int      $target_h   Logo height in px (width keeps aspect).
+	 * @param int      $x          Left position on the canvas.
+	 * @param int      $y          Top position on the canvas.
+	 * @param float    $opacity    1.0 = opaque, 0.55 = subtle corner mark.
+	 *
+	 * @return int Rendered logo width in px (useful for caption x-offsets).
+	 * @throws \RuntimeException When the asset is missing or unreadable.
+	 */
+	public static function place_logo( \Imagick $canvas, string $asset_path, int $target_h, int $x, int $y, float $opacity = 1.0 ): int {
+		if ( ! is_readable( $asset_path ) ) {
+			throw new \RuntimeException( 'Composer brand asset missing: ' . basename( $asset_path ) );
+		}
+
+		$logo = new \Imagick( $asset_path );
+		$logo->setImagePage( 0, 0, 0, 0 );
+		$scale    = $target_h / max( 1, $logo->getImageHeight() );
+		$target_w = max( 1, (int) round( $logo->getImageWidth() * $scale ) );
+		$logo->resizeImage( $target_w, $target_h, \Imagick::FILTER_LANCZOS, 1 );
+
+		if ( $opacity < 1.0 ) {
+			$logo->evaluateImage( \Imagick::EVALUATE_MULTIPLY, max( 0.0, $opacity ), \Imagick::CHANNEL_ALPHA );
+		}
+
+		$canvas->compositeImage( $logo, \Imagick::COMPOSITE_OVER, $x, $y );
+		$logo->clear();
+
+		return $target_w;
+	}
+
+	/**
+	 * Encode a canvas as a deterministic PNG variant payload.
+	 *
+	 * Strips all metadata and excludes PNG date/time chunks so identical
+	 * inputs produce byte-identical output in the same environment.
+	 *
+	 * Side effects: destroys the Imagick object after encoding.
+	 *
+	 * @param \Imagick $image Finished canvas.
+	 * @param string   $role  Variant role: 'featured', 'og', or 'square'.
+	 *
+	 * @return array{bytes: string, mime_type: string, width: int, height: int, role: string}
+	 */
+	public static function finalize_png( \Imagick $image, string $role ): array {
+		$image->setImageFormat( 'png' );
+		$image->setImageDepth( 8 );
+		$image->stripImage();
+		$image->setOption( 'png:exclude-chunks', 'date,time' );
+		$image->setOption( 'png:compression-level', '9' );
+
+		$variant = array(
+			'bytes'     => $image->getImageBlob(),
+			'mime_type' => 'image/png',
+			'width'     => $image->getImageWidth(),
+			'height'    => $image->getImageHeight(),
+			'role'      => $role,
+		);
+		$image->clear();
+
+		return $variant;
+	}
+}

includes/core/class-image-composer-editor.php

@@ -0,0 +1,114 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Resize-only composer rung backed by wp_get_image_editor() (GD path).
+ *
+ * Used when Imagick is unusable: emits unbranded, caption-free center-crops
+ * at each variant's exact dimensions. Variants that would require upscaling
+ * (e.g. a 1080×1080 square from a 1200×632 base — WP's editor never upscales
+ * on crop-resize) are skipped; the OG crop is always achievable from the
+ * standard base. Output is GD PNG, which embeds no timestamps, so this rung
+ * is deterministic too.
+ *
+ * Triggered by: PRAutoBlogger_Image_Composer when the capability probe says 'gd'.
+ * Dependencies: wp_get_image_editor(), get_temp_dir(), PRAutoBlogger_Logger.
+ *
+ * @see core/class-image-composer.php — Orchestrator + degradation ladder.
+ * @see core/class-image-composer-imagick.php — The full-fidelity rung this replaces.
+ */
+class PRAutoBlogger_Image_Composer_Editor {
+
+	/**
+	 * Render resize-only variants for the requested roles.
+	 *
+	 * Side effects: temp file write/delete per variant; debug log on skips.
+	 *
+	 * @param string                               $bytes  Base image bytes.
+	 * @param string[]                             $roles  Variant roles to attempt ('og', 'square').
+	 * @param array<string, array<string, mixed>>  $layout Layout geometry (for target dimensions).
+	 *
+	 * @return array<int, array{bytes: string, mime_type: string, width: int, height: int, role: string}>
+	 *               Successfully resized variants only (possibly empty).
+	 */
+	public function compose_variants( string $bytes, array $roles, array $layout ): array {
+		$variants = array();
+
+		foreach ( $roles as $role ) {
+			$target_w = (int) ( $layout[ $role ]['width'] ?? 0 );
+			$target_h = (int) ( $layout[ $role ]['height'] ?? 0 );
+			if ( $target_w < 1 || $target_h < 1 ) {
+				continue;
+			}
+
+			$resized = $this->cover_crop( $bytes, $target_w, $target_h );
+			if ( null === $resized ) {
+				PRAutoBlogger_Logger::instance()->debug(
+					sprintf( 'Resize-only %s variant skipped (editor failure or would upscale).', $role ),
+					'image_composer'
+				);
+				continue;
+			}
+
+			$resized['role'] = $role;
+			$variants[]      = $resized;
+		}
+
+		return $variants;
+	}
+
+	/**
+	 * Center-crop bytes to exact dimensions with the portable WP editor.
+	 *
+	 * @param string $bytes    Source image bytes.
+	 * @param int    $target_w Target width in px.
+	 * @param int    $target_h Target height in px.
+	 *
+	 * @return array{bytes: string, mime_type: string, width: int, height: int}|null
+	 *               Null when the editor fails or cannot hit the exact size
+	 *               without upscaling.
+	 */
+	private function cover_crop( string $bytes, int $target_w, int $target_h ): ?array {
+		$temp = get_temp_dir() . uniqid( 'prab_compose_', true ) . '.png';
+		// phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents -- temp file, same pattern as the sideloader.
+		if ( false === file_put_contents( $temp, $bytes ) ) {
+			return null;
+		}
+
+		try {
+			$editor = wp_get_image_editor( $temp );
+			if ( is_wp_error( $editor ) ) {
+				return null;
+			}
+			if ( is_wp_error( $editor->resize( $target_w, $target_h, true ) ) ) {
+				return null;
+			}
+
+			$size = $editor->get_size();
+			if ( (int) $size['width'] !== $target_w || (int) $size['height'] !== $target_h ) {
+				return null; // Exact size not reachable without upscaling.
+			}
+
+			if ( is_wp_error( $editor->save( $temp, 'image/png' ) ) ) {
+				return null;
+			}
+			// phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- temp file we just wrote.
+			$out = file_get_contents( $temp );
+
+			return false === $out ? null : array(
+				'bytes'     => $out,
+				'mime_type' => 'image/png',
+				'width'     => $target_w,
+				'height'    => $target_h,
+			);
+		} catch ( \Throwable $e ) {
+			PRAutoBlogger_Logger::instance()->debug( 'WP image editor crop threw: ' . $e->getMessage(), 'image_composer' );
+			return null;
+		} finally {
+			// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- best-effort temp cleanup.
+			@unlink( $temp );
+		}
+	}
+}

includes/core/class-image-composer-imagick.php

@@ -0,0 +1,250 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Imagick renderer for the deterministic image composer (full-fidelity rung).
+ *
+ * Renders the three branded variants from one base image: corner-marked
+ * featured (1200×632), teal-band OG (1200×630), and card-layout square
+ * (1080×1080). No WordPress functions anywhere — layout geometry and asset
+ * directories arrive via the constructor, so the class runs unchanged inside
+ * the standalone render harness that produced the PR samples. Methods throw
+ * on failure; the orchestrator catches and degrades, so a renderer error can
+ * never fail a publish.
+ *
+ * Triggered by: PRAutoBlogger_Image_Composer when the capability probe says 'imagick'.
+ * Dependencies: ext-imagick, bundled brand PNGs + OFL fonts,
+ *               PRAutoBlogger_Image_Composer_Canvas (primitives),
+ *               PRAutoBlogger_Image_Composer_Layout (caption clamp).
+ *
+ * @see core/class-image-composer.php        — Orchestrator + degradation ladder.
+ * @see core/class-image-composer-canvas.php — Crop/logo/PNG primitives.
+ * @see core/class-image-composer-layout.php — Geometry defaults + clamp.
+ */
+class PRAutoBlogger_Image_Composer_Imagick {
+
+	/** @var array<string, array<string, mixed>> Layout geometry keyed by role. */
+	private array $layout;
+
+	/** @var string Absolute path to the vendored brand PNG directory (trailing slash). */
+	private string $brand_dir;
+
+	/** @var string Absolute path to the bundled font directory (trailing slash). */
+	private string $fonts_dir;
+
+	/**
+	 * Construct with resolved layout + asset locations.
+	 *
+	 * @param array<string, array<string, mixed>> $layout    Filtered layout (see Layout::defaults()).
+	 * @param string                              $brand_dir Brand PNG directory, trailing slash.
+	 * @param string                              $fonts_dir Font directory, trailing slash.
+	 */
+	public function __construct( array $layout, string $brand_dir, string $fonts_dir ) {
+		$this->layout    = $layout;
+		$this->brand_dir = $brand_dir;
+		$this->fonts_dir = $fonts_dir;
+	}
+
+	/**
+	 * Featured variant: base image untouched except a subtle corner mark.
+	 *
+	 * @param string $bytes Base image bytes.
+	 *
+	 * @return array{bytes: string, mime_type: string, width: int, height: int, role: string}
+	 * @throws \RuntimeException|\ImagickException On decode/asset failure.
+	 */
+	public function compose_featured( string $bytes ): array {
+		$conf   = $this->layout['featured'];
+		$canvas = PRAutoBlogger_Image_Composer_Canvas::load_base( $bytes );
+
+		$mark_h = (int) $conf['mark_height'];
+		$inset  = (int) $conf['mark_inset'];
+		// The mark asset is square, so rendered width equals the height.
+		PRAutoBlogger_Image_Composer_Canvas::place_logo(
+			$canvas,
+			$this->brand_dir . $conf['mark_asset'],
+			$mark_h,
+			$canvas->getImageWidth() - $mark_h - $inset,
+			$canvas->getImageHeight() - $mark_h - $inset,
+			(float) $conf['mark_opacity']
+		);
+
+		return PRAutoBlogger_Image_Composer_Canvas::finalize_png( $canvas, 'featured' );
+	}
+
+	/**
+	 * OG variant (1200×630): center-cropped base, bottom teal band with the
+	 * brand mark and the clamped caption in white.
+	 *
+	 * @param string $bytes   Base image bytes.
+	 * @param string $caption Editorial caption (clamped to 2 lines).
+	 *
+	 * @return array{bytes: string, mime_type: string, width: int, height: int, role: string}
+	 * @throws \RuntimeException|\ImagickException On decode/crop/asset failure.
+	 */
+	public function compose_og( string $bytes, string $caption ): array {
+		$conf   = $this->layout['og'];
+		$width  = (int) $conf['width'];
+		$height = (int) $conf['height'];
+		$band_h = (int) $conf['band_height'];
+		$band_y = $height - $band_h;
+
+		$canvas = PRAutoBlogger_Image_Composer_Canvas::load_base( $bytes );
+		if ( ! PRAutoBlogger_Image_Composer_Canvas::cover_crop( $canvas, $width, $height ) ) {
+			$canvas->clear();
+			throw new \RuntimeException( 'OG variant would require upscaling the base image.' );
+		}
+
+		$this->draw_rect( $canvas, 0, $band_y, $width, $height, (string) $conf['band_color'] );
+
+		$logo_h = (int) $conf['logo_height'];
+		$logo_w = PRAutoBlogger_Image_Composer_Canvas::place_logo(
+			$canvas,
+			$this->brand_dir . $conf['logo_asset'],
+			$logo_h,
+			(int) $conf['logo_x'],
+			$band_y + (int) floor( ( $band_h - $logo_h ) / 2 )
+		);
+
+		$lines = PRAutoBlogger_Image_Composer_Layout::clamp_caption(
+			$caption,
+			(int) $conf['caption_chars_per_line'],
+			(int) $conf['caption_max_lines']
+		);
+		$this->draw_lines(
+			$canvas,
+			$lines,
+			array(
+				'font'        => $this->fonts_dir . $conf['caption_font'],
+				'size'        => (float) $conf['caption_size'],
+				'color'       => (string) $conf['caption_color'],
+				'line_height' => (float) $conf['caption_line_height'],
+				'x'           => (int) $conf['logo_x'] + $logo_w + (int) $conf['caption_gap'],
+				'center_y'    => $band_y + (int) floor( $band_h / 2 ),
+				'align'       => \Imagick::ALIGN_LEFT,
+			)
+		);
+
+		return PRAutoBlogger_Image_Composer_Canvas::finalize_png( $canvas, 'og' );
+	}
+
+	/**
+	 * Square variant (1080×1080, card layout, no upscaling): full base
+	 * downscaled into the top slice, cream caption panel in Poppins Bold,
+	 * teal footer band with the horizontal reverse lockup.
+	 *
+	 * @param string $bytes   Base image bytes.
+	 * @param string $caption Editorial caption (clamped to 3 lines).
+	 *
+	 * @return array{bytes: string, mime_type: string, width: int, height: int, role: string}
+	 * @throws \RuntimeException|\ImagickException On decode/crop/asset failure.
+	 */
+	public function compose_square( string $bytes, string $caption ): array {
+		$conf     = $this->layout['square'];
+		$width    = (int) $conf['width'];
+		$height   = (int) $conf['height'];
+		$slice_h  = (int) $conf['slice_height'];
+		$footer_h = (int) $conf['footer_height'];
+		$footer_y = $height - $footer_h;
+
+		$slice = PRAutoBlogger_Image_Composer_Canvas::load_base( $bytes );
+		if ( ! PRAutoBlogger_Image_Composer_Canvas::cover_crop( $slice, $width, $slice_h ) ) {
+			$slice->clear();
+			throw new \RuntimeException( 'Square variant would require upscaling the base image.' );
+		}
+
+		$canvas = new \Imagick();
+		$canvas->newImage( $width, $height, new \ImagickPixel( (string) $conf['panel_color'] ), 'png' );
+		$canvas->compositeImage( $slice, \Imagick::COMPOSITE_OVER, 0, 0 );
+		$slice->clear();
+
+		$this->draw_rect( $canvas, 0, $footer_y, $width, $height, (string) $conf['footer_color'] );
+
+		$logo_h = (int) $conf['footer_logo_height'];
+		$logo   = new \Imagick( $this->brand_dir . $conf['footer_logo_asset'] );
+		$logo_w = (int) round( $logo->getImageWidth() * ( $logo_h / max( 1, $logo->getImageHeight() ) ) );
+		$logo->clear();
+		PRAutoBlogger_Image_Composer_Canvas::place_logo(
+			$canvas,
+			$this->brand_dir . $conf['footer_logo_asset'],
+			$logo_h,
+			(int) floor( ( $width - $logo_w ) / 2 ),
+			$footer_y + (int) floor( ( $footer_h - $logo_h ) / 2 )
+		);
+
+		$lines = PRAutoBlogger_Image_Composer_Layout::clamp_caption(
+			$caption,
+			(int) $conf['caption_chars_per_line'],
+			(int) $conf['caption_max_lines']
+		);
+		$this->draw_lines(
+			$canvas,
+			$lines,
+			array(
+				'font'        => $this->fonts_dir . $conf['caption_font'],
+				'size'        => (float) $conf['caption_size'],
+				'color'       => (string) $conf['caption_color'],
+				'line_height' => (float) $conf['caption_line_height'],
+				'x'           => (int) floor( $width / 2 ),
+				'center_y'    => $slice_h + (int) floor( ( $footer_y - $slice_h ) / 2 ),
+				'align'       => \Imagick::ALIGN_CENTER,
+			)
+		);
+
+		return PRAutoBlogger_Image_Composer_Canvas::finalize_png( $canvas, 'square' );
+	}
+
+	/**
+	 * Fill an axis-aligned rectangle on the canvas.
+	 *
+	 * @param \Imagick $canvas Destination canvas (mutated).
+	 * @param int      $x1     Left.
+	 * @param int      $y1     Top.
+	 * @param int      $x2     Right.
+	 * @param int      $y2     Bottom.
+	 * @param string   $color  Hex fill color.
+	 */
+	private function draw_rect( \Imagick $canvas, int $x1, int $y1, int $x2, int $y2, string $color ): void {
+		$draw = new \ImagickDraw();
+		$draw->setFillColor( new \ImagickPixel( $color ) );
+		$draw->rectangle( (float) $x1, (float) $y1, (float) $x2, (float) $y2 );
+		$canvas->drawImage( $draw );
+	}
+
+	/**
+	 * Draw pre-clamped caption lines vertically centered around center_y.
+	 *
+	 * @param \Imagick $canvas Destination canvas (mutated).
+	 * @param string[] $lines  Already-clamped lines (may be empty — no-op).
+	 * @param array{font: string, size: float, color: string, line_height: float, x: int, center_y: int, align: int} $opts Text options.
+	 *
+	 * @throws \RuntimeException When the bundled font file is missing.
+	 */
+	private function draw_lines( \Imagick $canvas, array $lines, array $opts ): void {
+		if ( empty( $lines ) ) {
+			return;
+		}
+		if ( ! is_readable( $opts['font'] ) ) {
+			throw new \RuntimeException( 'Composer font missing: ' . basename( $opts['font'] ) );
+		}
+
+		$draw = new \ImagickDraw();
+		$draw->setFont( $opts['font'] );
+		$draw->setFontSize( $opts['size'] );
+		$draw->setFillColor( new \ImagickPixel( $opts['color'] ) );
+		$draw->setTextAlignment( $opts['align'] );
+		$draw->setTextAntialias( true );
+
+		$metrics     = $canvas->queryFontMetrics( $draw, 'Hg' );
+		$line_step   = (int) round( $opts['size'] * $opts['line_height'] );
+		$block_h     = ( count( $lines ) - 1 ) * $line_step + (int) round( $metrics['ascender'] - $metrics['descender'] );
+		$baseline    = $opts['center_y'] - (int) floor( $block_h / 2 ) + (int) round( $metrics['ascender'] );
+
+		foreach ( $lines as $line ) {
+			$canvas->annotateImage( $draw, (float) $opts['x'], (float) $baseline, 0.0, $line );
+			$baseline += $line_step;
+		}
+	}
+}

includes/core/class-image-composer-layout.php

@@ -0,0 +1,173 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Geometry defaults and caption clamping for the deterministic image composer.
+ *
+ * Pure functions and constants only — no WordPress, no Imagick. This keeps
+ * the class unit-testable and usable from a standalone render harness. The
+ * orchestrator exposes defaults() through the `prautoblogger_image_compose_layout`
+ * filter; geometry is intentionally NOT a settings-page surface (promote to
+ * settings only if the CEO asks to tune it — see ARCHITECTURE.md #21).
+ *
+ * Triggered by: PRAutoBlogger_Image_Composer (orchestrator) at compose time.
+ * Dependencies: mbstring (bundled with WordPress via compat polyfills).
+ *
+ * @see core/class-image-composer.php          — Applies the layout filter.
+ * @see core/class-image-composer-imagick.php  — Consumes the geometry values.
+ * @see tests/unit/Core/ImageComposerLayoutTest.php — Clamp boundary cases.
+ */
+class PRAutoBlogger_Image_Composer_Layout {
+
+	/** Brand tokens (locked — see peptide-repo-brand README). */
+	public const COLOR_TEAL   = '#1B8A92';
+	public const COLOR_LIME   = '#7FD600';
+	public const COLOR_ORANGE = '#FF8A3D';
+	public const COLOR_INK    = '#0D0D0D';
+	public const COLOR_CREAM  = '#FAFAF7';
+
+	/** Ellipsis appended when a caption overflows its line budget. */
+	public const ELLIPSIS = '…';
+
+	/**
+	 * Default geometry for every composed variant.
+	 *
+	 * Asset filenames resolve against assets/brand/ and assets/fonts/ in the
+	 * plugin; sizes are px. Values were tuned against rendered samples (see
+	 * PR #thread 2026-06-image-composer assets).
+	 *
+	 * @return array<string, array<string, mixed>> Keyed by role: featured, og, square.
+	 */
+	public static function defaults(): array {
+		return array(
+			'featured' => array(
+				'mark_asset'   => 'logo-mark-small-56.png',
+				'mark_height'  => 28,
+				'mark_inset'   => 16,
+				'mark_opacity' => 0.55,
+			),
+			'og'       => array(
+				'width'                 => 1200,
+				'height'                => 630,
+				'band_height'           => 120,
+				'band_color'            => self::COLOR_TEAL,
+				'logo_asset'            => 'logo-mark-small-112.png',
+				'logo_height'           => 64,
+				'logo_x'                => 40,
+				'caption_font'          => 'Poppins-SemiBold.ttf',
+				'caption_size'          => 32,
+				'caption_color'         => '#FFFFFF',
+				'caption_gap'           => 24,
+				'caption_margin_right'  => 40,
+				'caption_max_lines'     => 2,
+				'caption_chars_per_line' => 52,
+				'caption_line_height'   => 1.3,
+			),
+			'square'   => array(
+				'width'                 => 1080,
+				'height'                => 1080,
+				'slice_height'          => 569,
+				'panel_color'           => self::COLOR_CREAM,
+				'footer_height'         => 96,
+				'footer_color'          => self::COLOR_TEAL,
+				'footer_logo_asset'     => 'logo-horizontal-reverse-128.png',
+				'footer_logo_height'    => 48,
+				'caption_font'          => 'Poppins-Bold.ttf',
+				'caption_size'          => 48,
+				'caption_color'         => self::COLOR_INK,
+				'caption_max_lines'     => 3,
+				'caption_chars_per_line' => 36,
+				'caption_side_padding'  => 64,
+				'caption_line_height'   => 1.3,
+			),
+		);
+	}
+
+	/**
+	 * Clamp and word-wrap a caption to a hard per-variant budget.
+	 *
+	 * Whitespace is collapsed, words wrap at word boundaries, words longer
+	 * than a full line are hard-split, and overflow beyond max_lines is cut
+	 * with a trailing ellipsis. Multibyte-safe (mb_* functions).
+	 *
+	 * Side effects: none (pure).
+	 *
+	 * @param string $caption        Raw caption text (any length, any script).
+	 * @param int    $chars_per_line Hard character budget per line (min 1).
+	 * @param int    $max_lines      Maximum number of lines (min 1).
+	 *
+	 * @return string[] Wrapped lines; empty array when the caption is blank.
+	 */
+	public static function clamp_caption( string $caption, int $chars_per_line, int $max_lines ): array {
+		$chars_per_line = max( 1, $chars_per_line );
+		$max_lines      = max( 1, $max_lines );
+		$normalized     = trim( (string) preg_replace( '/\s+/u', ' ', $caption ) );
+
+		if ( '' === $normalized ) {
+			return array();
+		}
+
+		$lines = array();
+		$line  = '';
+
+		foreach ( explode( ' ', $normalized ) as $word ) {
+			// Hard-split words longer than a full line so they cannot overflow.
+			while ( mb_strlen( $word ) > $chars_per_line ) {
+				if ( '' !== $line ) {
+					$lines[] = $line;
+					$line    = '';
+					if ( count( $lines ) >= $max_lines ) {
+						return self::ellipsize( $lines, $chars_per_line );
+					}
+				}
+				$lines[] = mb_substr( $word, 0, $chars_per_line );
+				$word    = mb_substr( $word, $chars_per_line );
+				if ( count( $lines ) >= $max_lines ) {
+					return self::ellipsize( $lines, $chars_per_line );
+				}
+			}
+
+			$candidate = ( '' === $line ) ? $word : $line . ' ' . $word;
+			if ( mb_strlen( $candidate ) <= $chars_per_line ) {
+				$line = $candidate;
+				continue;
+			}
+
+			$lines[] = $line;
+			$line    = $word;
+			if ( count( $lines ) >= $max_lines ) {
+				return self::ellipsize( $lines, $chars_per_line );
+			}
+		}
+
+		if ( '' !== $line ) {
+			$lines[] = $line;
+		}
+
+		return $lines;
+	}
+
+	/**
+	 * Append an ellipsis to the final line, trimming first if the line is
+	 * already at the character budget so the result never exceeds it.
+	 *
+	 * @param string[] $lines          Lines already at the max-line count.
+	 * @param int      $chars_per_line Hard character budget per line.
+	 *
+	 * @return string[] Lines with a trailing ellipsis on the last one.
+	 */
+	private static function ellipsize( array $lines, int $chars_per_line ): array {
+		$last_index = count( $lines ) - 1;
+		$last       = $lines[ $last_index ];
+
+		if ( mb_strlen( $last ) + 1 > $chars_per_line ) {
+			$last = rtrim( mb_substr( $last, 0, max( 0, $chars_per_line - 1 ) ) );
+		}
+
+		$lines[ $last_index ] = $last . self::ELLIPSIS;
+
+		return $lines;
+	}
+}

includes/core/class-image-composer.php

@@ -0,0 +1,298 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Orchestrates deterministic image composition with a capability ladder.
+ *
+ * Sits between the provider's raw bytes and the media sideloader. Probes the
+ * environment once (cached in an option keyed by a PHP/extension fingerprint,
+ * so it auto-invalidates when the host changes — Hostinger extension state
+ * has flipped before), then renders per the ladder: (1) Imagick usable →
+ * full branded compositing; (2) GD via WP editor → resize-only variants, no
+ * branding/text, WARNING once; (3) no image library → pass-through, WARNING
+ * once. compose() never throws and always returns a featured-first non-empty
+ * list, so a composition failure can never block a publish. Local CPU only:
+ * $0, no provider call; duration is logged on the image_composer channel.
+ *
+ * Triggered by: PRAutoBlogger_Image_Pipeline after batch results + NSFW retry,
+ *               before sideloading.
+ * Dependencies: Image_Composer_Imagick (rung 1), Image_Composer_Editor (rung 2),
+ *               Image_Composer_Canvas (probe), Image_Composer_Layout, Logger.
+ *
+ * @see core/interface-image-composer.php — The contract.
+ * @see core/class-image-pipeline.php     — Caller.
+ * @see core/class-image-attacher.php     — Persists returned variants.
+ * @see ARCHITECTURE.md                   — Decision #21.
+ */
+class PRAutoBlogger_Image_Composer implements PRAutoBlogger_Image_Composer_Interface {
+
+	/** Option keys (prautoblogger_ prefix keeps the uninstall sweep effective). */
+	public const OPTION_ENABLED      = 'prautoblogger_image_compose_enabled';
+	public const OPTION_VARIANTS     = 'prautoblogger_image_compose_variants';
+	public const OPTION_MARK_ENABLED = 'prautoblogger_image_featured_mark_enabled';
+	public const OPTION_CAPABILITY   = 'prautoblogger_image_compose_capability';
+
+	/** Capability rungs. */
+	public const CAP_IMAGICK = 'imagick';
+	public const CAP_GD      = 'gd';
+	public const CAP_NONE    = 'none';
+
+	/** @var PRAutoBlogger_Image_Composer_Imagick|null Lazily built; injectable for tests. */
+	private ?PRAutoBlogger_Image_Composer_Imagick $renderer;
+
+	/** @var bool Degradation WARNING fired this run (once per PHP process). */
+	private static bool $warned_this_run = false;
+
+	/**
+	 * Construct, optionally injecting a renderer (tests).
+	 * @param PRAutoBlogger_Image_Composer_Imagick|null $renderer Optional renderer override.
+	 */
+	public function __construct( ?PRAutoBlogger_Image_Composer_Imagick $renderer = null ) {
+		$this->renderer = $renderer;
+	}
+
+	/**
+	 * Compose final variants for one generated image. See the interface for
+	 * the full contract; this implementation never throws.
+	 * Side effects: reads options, may cache the capability probe, logs.
+	 *
+	 * @param array $image_data Provider result (bytes, mime_type, width, height, ...).
+	 * @param array $context    {post_id, caption, title, slot}.
+	 * @return array<int, array{bytes: string, mime_type: string, width: int, height: int, role: string}>
+	 */
+	public function compose( array $image_data, array $context ): array {
+		$passthrough = array( $this->passthrough_variant( $image_data ) );
+
+		if ( '' === $passthrough[0]['bytes'] || '1' !== (string) get_option( self::OPTION_ENABLED, '1' ) ) {
+			return $passthrough;
+		}
+
+		$started    = microtime( true );
+		$bytes      = $passthrough[0]['bytes'];
+		$capability = $this->resolve_capability();
+		$caption    = (string) ( $context['caption'] ?? '' );
+		$roles      = ( 'image_a' === (string) ( $context['slot'] ?? 'image_a' ) )
+			? $this->configured_variants()
+			: array();
+
+		if ( self::CAP_IMAGICK === $capability ) {
+			$variants = $this->compose_via_imagick( $bytes, $caption, $roles, $passthrough[0] );
+		} elseif ( self::CAP_GD === $capability ) {
+			$this->warn_once( 'Imagick unavailable — emitting resize-only variants without branding or caption.' );
+			$editor   = new PRAutoBlogger_Image_Composer_Editor();
+			$variants = array_merge( $passthrough, $editor->compose_variants( $bytes, $roles, $this->layout() ) );
+		} else {
+			$this->warn_once( 'No usable image library — base image passed through unbranded.' );
+			$variants = $passthrough;
+		}
+
+		PRAutoBlogger_Logger::instance()->info(
+			sprintf(
+				'Composed %d variant(s) for post %d in %dms ($0, local, capability: %s).',
+				count( $variants ),
+				(int) ( $context['post_id'] ?? 0 ),
+				(int) round( ( microtime( true ) - $started ) * 1000 ),
+				$capability
+			),
+			'image_composer'
+		);
+
+		return $variants;
+	}
+
+	/**
+	 * Full compositing rung. Each render is individually guarded: a featured
+	 * failure degrades to pass-through, a variant failure skips that variant.
+	 *
+	 * @param string $bytes       Base image bytes.
+	 * @param string $caption     Editorial caption for OG/square.
+	 * @param array  $roles       Variant roles to render ('og', 'square').
+	 * @param array  $passthrough Pass-through featured variant (fallback).
+	 * @return array<int, array<string, mixed>> Featured-first variant list.
+	 */
+	private function compose_via_imagick( string $bytes, string $caption, array $roles, array $passthrough ): array {
+		$variants = array();
+
+		if ( '1' === (string) get_option( self::OPTION_MARK_ENABLED, '1' ) ) {
+			$featured   = $this->try_render( 'featured', $bytes, $caption );
+			$variants[] = null === $featured ? $passthrough : $featured;
+		} else {
+			$variants[] = $passthrough;
+		}
+
+		foreach ( $roles as $role ) {
+			$variant = $this->try_render( $role, $bytes, $caption );
+			if ( null !== $variant ) {
+				$variants[] = $variant;
+			}
+		}
+
+		return $variants;
+	}
+
+	/**
+	 * Render one role via the Imagick renderer. Any throwable or malformed
+	 * result (empty bytes) maps to one per-run WARNING + null (caller degrades).
+	 * @param string $role    'featured', 'og', or 'square'.
+	 * @param string $bytes   Base image bytes.
+	 * @param string $caption Editorial caption.
+	 * @return array<string, mixed>|null Variant payload or null on failure.
+	 */
+	private function try_render( string $role, string $bytes, string $caption ): ?array {
+		try {
+			$renderer = $this->renderer();
+			if ( 'og' === $role ) {
+				$variant = $renderer->compose_og( $bytes, $caption );
+			} elseif ( 'square' === $role ) {
+				$variant = $renderer->compose_square( $bytes, $caption );
+			} else {
+				$variant = $renderer->compose_featured( $bytes );
+			}
+
+			if ( '' === (string) ( $variant['bytes'] ?? '' ) ) {
+				$this->warn_once( sprintf( 'Imagick render for %s variant returned no bytes — degrading.', $role ) );
+				return null;
+			}
+			$variant['role'] = $role;
+
+			return $variant;
+		} catch ( \Throwable $e ) {
+			$this->warn_once( sprintf( 'Imagick render failed for %s variant: %s', $role, $e->getMessage() ) );
+			return null;
+		}
+	}
+
+	/**
+	 * Resolve the capability rung: cached probe + override filter. The
+	 * same-named filter lets tests/ops force a rung (e.g. 'none').
+	 *
+	 * @return string One of the CAP_* constants.
+	 */
+	private function resolve_capability(): string {
+		$fingerprint = md5(
+			PHP_VERSION . '|' . ( extension_loaded( 'imagick' ) ? 'im1' : 'im0' ) . '|' . ( extension_loaded( 'gd' ) ? 'gd1' : 'gd0' )
+		);
+
+		$cached = get_option( self::OPTION_CAPABILITY, array() );
+		if ( is_array( $cached ) && ( $cached['fingerprint'] ?? '' ) === $fingerprint && isset( $cached['capability'] ) ) {
+			$capability = (string) $cached['capability'];
+		} else {
+			$capability = $this->probe_capability();
+			update_option(
+				self::OPTION_CAPABILITY,
+				array(
+					'fingerprint' => $fingerprint,
+					'capability'  => $capability,
+				),
+				false
+			);
+		}
+
+		$capability = (string) apply_filters( 'prautoblogger_image_compose_capability', $capability );
+
+		return in_array( $capability, array( self::CAP_IMAGICK, self::CAP_GD, self::CAP_NONE ), true )
+			? $capability
+			: self::CAP_NONE;
+	}
+
+	/**
+	 * Probe the host for the best available rung (uncached).
+	 * @return string One of the CAP_* constants.
+	 */
+	private function probe_capability(): string {
+		if ( PRAutoBlogger_Image_Composer_Canvas::is_imagick_usable( $this->fonts_dir() . 'Poppins-Bold.ttf' ) ) {
+			return self::CAP_IMAGICK;
+		}
+
+		$png_crop = array(
+			'mime_type' => 'image/png',
+			'methods'   => array( 'resize', 'crop' ),
+		);
+		if ( function_exists( 'wp_image_editor_supports' ) && wp_image_editor_supports( $png_crop ) ) {
+			return self::CAP_GD;
+		}
+
+		return self::CAP_NONE;
+	}
+
+	/**
+	 * Lazily build the Imagick renderer with filtered layout + asset paths.
+	 * @return PRAutoBlogger_Image_Composer_Imagick
+	 */
+	private function renderer(): PRAutoBlogger_Image_Composer_Imagick {
+		if ( null === $this->renderer ) {
+			$this->renderer = new PRAutoBlogger_Image_Composer_Imagick(
+				$this->layout(),
+				dirname( __DIR__, 2 ) . '/assets/brand/',
+				$this->fonts_dir()
+			);
+		}
+		return $this->renderer;
+	}
+
+	/**
+	 * Layout geometry: pure defaults behind the documented override filter.
+	 * @return array<string, array<string, mixed>>
+	 */
+	private function layout(): array {
+		return (array) apply_filters( 'prautoblogger_image_compose_layout', PRAutoBlogger_Image_Composer_Layout::defaults() );
+	}
+
+	/**
+	 * Bundled font directory (path-derived, no constants — unit-test safe).
+	 * @return string Absolute path with trailing slash.
+	 */
+	private function fonts_dir(): string {
+		return dirname( __DIR__, 2 ) . '/assets/fonts/';
+	}
+
+	/**
+	 * Variant roles from settings, whitelisted at point of use.
+	 * @return string[] Subset of ['og', 'square'], deduplicated, in config order.
+	 */
+	private function configured_variants(): array {
+		$raw   = (string) get_option( self::OPTION_VARIANTS, 'og,square' );
+		$roles = array();
+		foreach ( explode( ',', $raw ) as $piece ) {
+			$piece = strtolower( trim( $piece ) );
+			if ( in_array( $piece, array( 'og', 'square' ), true ) && ! in_array( $piece, $roles, true ) ) {
+				$roles[] = $piece;
+			}
+		}
+		return $roles;
+	}
+
+	/**
+	 * Build the pass-through featured variant from the provider result.
+	 * @param array $image_data Provider result.
+	 * @return array{bytes: string, mime_type: string, width: int, height: int, role: string}
+	 */
+	private function passthrough_variant( array $image_data ): array {
+		return array(
+			'bytes'     => (string) ( $image_data['bytes'] ?? '' ),
+			'mime_type' => (string) ( $image_data['mime_type'] ?? 'image/png' ),
+			'width'     => (int) ( $image_data['width'] ?? 0 ),
+			'height'    => (int) ( $image_data['height'] ?? 0 ),
+			'role'      => 'featured',
+		);
+	}
+
+	/**
+	 * Log a degradation WARNING once per run (one row is enough for ops).
+	 * @param string $message Warning text.
+	 */
+	private function warn_once( string $message ): void {
+		if ( self::$warned_this_run ) {
+			return;
+		}
+		self::$warned_this_run = true;
+		PRAutoBlogger_Logger::instance()->warning( $message, 'image_composer' );
+	}
+
+	/** Reset per-run state (unit tests only). */
+	public static function reset_run_state(): void {
+		self::$warned_this_run = false;
+	}
+}

includes/core/class-image-media-sideloader.php

@@ -0,0 +1,173 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Downloads generated images and imports them into the WordPress media library.
+ *
+ * Handles sideloading (importing external images as WordPress attachments),
+ * sets metadata (alt text, title), and cleans up temporary files on failure.
+ *
+ * Triggered by: PRAutoBlogger_Image_Pipeline during content generation run.
+ * Dependencies: WordPress media functions (media_handle_sideload, wp_insert_attachment).
+ *
+ * @see core/class-image-pipeline.php      — Consumes sideload_image().
+ * @see providers/interface-image-provider.php — Image metadata (bytes, mime_type, etc).
+ * @see ARCHITECTURE.md                    — Media library integration.
+ */
+class PRAutoBlogger_Image_Media_Sideloader {
+
+	/**
+	 * Download and sideload a generated image into WordPress media library.
+	 *
+	 * Creates a temporary file, imports it via media_handle_sideload(), and
+	 * cleans up the temp file on success or failure. Sets alt text and title
+	 * from the prompt if provided.
+	 *
+	 * @param array{
+	 *     bytes: string,
+	 *     mime_type: string,
+	 *     width: int,
+	 *     height: int,
+	 *     model: string,
+	 *     seed?: ?int,
+	 *     cost_usd: float,
+	 *     latency_ms: int,
+	 * } $image_data Raw image bytes + metadata from PRAutoBlogger_Image_Provider_Interface.
+	 * @param int    $post_id Target post ID to attach the image to.
+	 * @param string $alt_text Alt text for the image (the editorial caption).
+	 * @param string $filename_suffix Optional role hint appended to the filename
+	 *                                (e.g. 'og', 'square' for composed variants).
+	 *
+	 * @return int|\WP_Error Attachment ID on success, WP_Error on failure.
+	 */
+	public function sideload_image( array $image_data, int $post_id, string $alt_text = '', string $filename_suffix = '' ) {
+		// WordPress media functions live in wp-admin/includes/ and are NOT
+		// loaded automatically in cron or REST contexts. Load them if missing.
+		// Why: WP-Cron runs as a frontend request, so admin-only files like
+		// media.php, file.php, and image.php are not included by default.
+		if ( ! function_exists( 'media_handle_sideload' ) ) {
+			require_once ABSPATH . 'wp-admin/includes/media.php';
+			require_once ABSPATH . 'wp-admin/includes/file.php';
+			require_once ABSPATH . 'wp-admin/includes/image.php';
+		}
+
+		// Validate input.
+		if ( empty( $image_data['bytes'] ) ) {
+			return new \WP_Error( 'invalid_image_data', 'Image data (bytes) is empty.' );
+		}
+
+		// Create a temporary file.
+		$temp_file = $this->create_temp_file( $image_data['bytes'], $image_data['mime_type'] );
+		if ( is_wp_error( $temp_file ) ) {
+			return $temp_file;
+		}
+
+		// Prepare file array for media_handle_sideload().
+		$file_array = array(
+			'name'     => $this->generate_filename( $image_data['model'], $image_data['width'], $image_data['height'], $filename_suffix ),
+			'tmp_name' => $temp_file,
+		);
+
+		// Import the file into media library.
+		$attachment_id = media_handle_sideload( $file_array, $post_id );
+
+		// Clean up temp file.
+		@unlink( $temp_file );
+
+		if ( is_wp_error( $attachment_id ) ) {
+			PRAutoBlogger_Logger::instance()->error(
+				'Failed to sideload image: ' . $attachment_id->get_error_message(),
+				'image_media_sideloader'
+			);
+			return $attachment_id;
+		}
+
+		// Set alt text and metadata.
+		if ( ! empty( $alt_text ) ) {
+			update_post_meta( $attachment_id, '_wp_attachment_image_alt', sanitize_text_field( $alt_text ) );
+		}
+
+		// Store image generation metadata.
+		update_post_meta( $attachment_id, '_prautoblogger_image_model', sanitize_text_field( $image_data['model'] ) );
+		update_post_meta( $attachment_id, '_prautoblogger_image_width', (int) $image_data['width'] );
+		update_post_meta( $attachment_id, '_prautoblogger_image_height', (int) $image_data['height'] );
+		update_post_meta( $attachment_id, '_prautoblogger_image_cost_usd', (float) $image_data['cost_usd'] );
+		update_post_meta( $attachment_id, '_prautoblogger_image_latency_ms', (int) $image_data['latency_ms'] );
+
+		if ( isset( $image_data['seed'] ) && null !== $image_data['seed'] ) {
+			update_post_meta( $attachment_id, '_prautoblogger_image_seed', (int) $image_data['seed'] );
+		}
+
+		return $attachment_id;
+	}
+
+	/**
+	 * Create a temporary file containing the image bytes.
+	 *
+	 * @param string $bytes Raw image bytes.
+	 * @param string $mime_type MIME type (e.g., 'image/png').
+	 *
+	 * @return string|\WP_Error Path to temporary file on success, WP_Error on failure.
+	 */
+	private function create_temp_file( string $bytes, string $mime_type ) {
+		$temp_dir  = get_temp_dir();
+		$filename  = 'prautoblogger_img_' . wp_generate_uuid4() . $this->get_extension_for_mime( $mime_type );
+		$temp_path = $temp_dir . $filename;
+
+		$written = file_put_contents( $temp_path, $bytes );
+		if ( false === $written ) {
+			return new \WP_Error(
+				'temp_file_write_failed',
+				sprintf(
+					/* translators: %s: path to temp file */
+					esc_html__( 'Could not write temporary image file to %s', 'prautoblogger' ),
+					$temp_path
+				)
+			);
+		}
+
+		return $temp_path;
+	}
+
+	/**
+	 * Generate a descriptive filename for the attachment.
+	 *
+	 * @param string $model Model name (e.g., 'flux-1-schnell').
+	 * @param int    $width Image width.
+	 * @param int    $height Image height.
+	 * @param string $suffix Optional role hint (e.g. 'og', 'square'); back-compat default ''.
+	 *
+	 * @return string Sanitized filename.
+	 */
+	private function generate_filename( string $model, int $width, int $height, string $suffix = '' ): string {
+		$base = sprintf(
+			'prautoblogger_%s_%dx%d_%s%s',
+			sanitize_title( $model ),
+			$width,
+			$height,
+			gmdate( 'Y-m-d_H-i-s' ),
+			'' !== $suffix ? '_' . sanitize_title( $suffix ) : ''
+		);
+
+		return $base . '.png'; // Default to PNG — most image models output PNG.
+	}
+
+	/**
+	 * Get file extension for a MIME type.
+	 *
+	 * @param string $mime_type MIME type string.
+	 *
+	 * @return string File extension with leading dot (e.g., '.png').
+	 */
+	private function get_extension_for_mime( string $mime_type ): string {
+		$map = array(
+			'image/png'  => '.png',
+			'image/jpeg' => '.jpg',
+			'image/jpg'  => '.jpg',
+		);
+
+		return $map[ strtolower( $mime_type ) ] ?? '.png';
+	}
+}

includes/core/class-image-nsfw-retry.php

@@ -0,0 +1,141 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Single-shot retry of NSFW-blocked image slots with a sanitized prompt.
+ *
+ * When an image provider rejects a prompt via its content filter, its
+ * batch result carries
+ * `['error_type' => 'nsfw_blocked']`. This helper reruns just the blocked
+ * slot once with the rule-based fallback prompt (article title + style
+ * suffix, no LLM rewrite) and merges the new result back into the batch.
+ *
+ * Intentionally single-retry: if the fallback is also blocked, we log a
+ * WARNING and leave the `['error' => ...]` entry in place so the pipeline
+ * proceeds to publish without a featured image (current behaviour for any
+ * unrecoverable image failure).
+ *
+ * Gated behind the `prautoblogger_image_nsfw_retry` setting (default on).
+ *
+ * Triggered by: PRAutoBlogger_Image_Pipeline::generate_and_attach_images.
+ * Dependencies: PRAutoBlogger_Image_Provider_Interface (retry HTTP call),
+ *               PRAutoBlogger_Image_Prompt_Builder (fallback prompt),
+ *               PRAutoBlogger_Logger (warning + info lines).
+ *
+ * @see core/class-image-pipeline.php            — Sole caller.
+ * @see core/class-image-prompt-builder.php      — Supplies the fallback prompt.
+ * @see providers/class-image-nsfw-blocked.php   — Typed exception raised by providers.
+ */
+class PRAutoBlogger_Image_NSFW_Retry {
+
+	/**
+	 * Option key for the admin toggle.
+	 */
+	private const SETTING_KEY = 'prautoblogger_image_nsfw_retry';
+
+	/** @var PRAutoBlogger_Image_Provider_Interface */
+	private PRAutoBlogger_Image_Provider_Interface $provider;
+
+	/** @var PRAutoBlogger_Image_Prompt_Builder */
+	private PRAutoBlogger_Image_Prompt_Builder $prompt_builder;
+
+	/**
+	 * @param PRAutoBlogger_Image_Provider_Interface $provider       Provider to retry against.
+	 * @param PRAutoBlogger_Image_Prompt_Builder     $prompt_builder Fallback prompt source.
+	 */
+	public function __construct(
+		PRAutoBlogger_Image_Provider_Interface $provider,
+		PRAutoBlogger_Image_Prompt_Builder $prompt_builder
+	) {
+		$this->provider       = $provider;
+		$this->prompt_builder = $prompt_builder;
+	}
+
+	/**
+	 * Whether the admin setting currently allows NSFW retries.
+	 *
+	 * Defaults to on. Kept as a static so callers can short-circuit before
+	 * constructing a retry object when nothing needs retrying anyway.
+	 *
+	 * @return bool
+	 */
+	public static function is_enabled(): bool {
+		return '1' === (string) get_option( self::SETTING_KEY, '1' );
+	}
+
+	/**
+	 * Replace every NSFW-blocked slot in $batch_results with a fresh result
+	 * from a sanitized fallback prompt.
+	 *
+	 * Mutates $batch_results and $captions in place. Also updates the
+	 * per-slot entry in $captions so the caller writes the fallback
+	 * caption under the post if the retry succeeds.
+	 *
+	 * Side effects: up to one HTTP call per blocked slot; Logger lines
+	 * for every retry attempt (info on success, warning on second block).
+	 *
+	 * @param int                        $post_id        Target post ID (for logs).
+	 * @param array                      $batch_requests Original per-slot request map.
+	 * @param array<string, array|null>  $batch_results  Provider result map (mutated).
+	 * @param array<string, string>      $captions       Caption map (mutated).
+	 * @param array<string, mixed>       $article_data   Article data (for title).
+	 * @param array<string, mixed>|null  $source_data    Source data (for title on image_b).
+	 * @return void
+	 */
+	public function retry_blocked_slots(
+		int $post_id,
+		array $batch_requests,
+		array &$batch_results,
+		array &$captions,
+		array $article_data,
+		?array $source_data
+	): void {
+		foreach ( $batch_results as $key => $entry ) {
+			if ( ! is_array( $entry ) || 'nsfw_blocked' !== ( $entry['error_type'] ?? '' ) ) {
+				continue;
+			}
+
+			$title = 'image_b' === $key
+				? (string) ( $source_data['title'] ?? '' )
+				: (string) ( $article_data['post_title'] ?? $article_data['suggested_title'] ?? '' );
+
+			$fallback = $this->prompt_builder->build_fallback_prompt( $title );
+
+			PRAutoBlogger_Logger::instance()->info(
+				sprintf( 'NSFW retry for post %d slot "%s" with sanitized fallback prompt.', $post_id, $key ),
+				'image_pipeline'
+			);
+
+			$retry_request = array(
+				'prompt'  => $fallback['prompt'],
+				'width'   => (int) ( $batch_requests[ $key ]['width'] ?? 0 ),
+				'height'  => (int) ( $batch_requests[ $key ]['height'] ?? 0 ),
+				'options' => $batch_requests[ $key ]['options'] ?? array(),
+			);
+
+			$retry_results = $this->provider->generate_image_batch( array( $key => $retry_request ) );
+			$retry_entry   = $retry_results[ $key ] ?? array( 'error' => 'Retry provider returned no result.' );
+
+			if ( isset( $retry_entry['error'] ) ) {
+				PRAutoBlogger_Logger::instance()->warning(
+					sprintf(
+						'NSFW retry for post %d slot "%s" also failed: %s',
+						$post_id,
+						$key,
+						(string) $retry_entry['error']
+					),
+					'image_pipeline'
+				);
+				// Leave the original ['error' => ...] entry so the pipeline
+				// publishes without this image, matching current behaviour
+				// for any unrecoverable image failure.
+				continue;
+			}
+
+			$batch_results[ $key ] = $retry_entry;
+			$captions[ $key ]      = $fallback['caption'];
+		}
+	}
+}

includes/core/class-image-pipeline.php

@@ -0,0 +1,296 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Orchestrates image generation for published articles.
+ *
+ * Generates two images per article (A/B): Image A (article-driven) as featured
+ * image, Image B (source-driven) in post meta. Each is independently fallible.
+ * Since v0.17.0 every result passes through the deterministic image composer
+ * (branded variants for A, corner mark for B) before sideloading; composition
+ * degrades gracefully and never blocks a publish.
+ *
+ * Triggered by: PRAutoBlogger_Pipeline_Runner after publisher creates the post.
+ * Dependencies: Image provider, Prompt builder, Composer, Attacher, Cost tracker, Logger.
+ *
+ * @see core/class-pipeline-runner.php       — Calls this after publisher.
+ * @see core/class-image-prompt-builder.php  — Prompt generation (scene + caption).
+ * @see core/class-image-composer.php        — Deterministic variant composition.
+ * @see core/class-image-attacher.php        — Sideloading + variant meta-linking.
+ */
+class PRAutoBlogger_Image_Pipeline {
+
+	/**
+	 * Default image dimensions (landscape). 1200×632 is the closest
+	 * 8-aligned pair to the standard OG image size (1200×630). Some
+	 * providers require dimensions divisible by 8.
+	 */
+	private const DEFAULT_WIDTH  = 1200;
+	private const DEFAULT_HEIGHT = 632;
+
+	/** @var PRAutoBlogger_Image_Provider_Interface Image gen provider. */
+	private PRAutoBlogger_Image_Provider_Interface $provider;
+	/** @var PRAutoBlogger_Image_Prompt_Builder Builds scene + caption from article data. */
+	private PRAutoBlogger_Image_Prompt_Builder $prompt_builder;
+	/** @var PRAutoBlogger_Image_Media_Sideloader Downloads images into WP media library. */
+	private PRAutoBlogger_Image_Media_Sideloader $sideloader;
+	/** @var PRAutoBlogger_Cost_Tracker Logs image generation spend. */
+	private PRAutoBlogger_Cost_Tracker $cost_tracker;
+	/** @var PRAutoBlogger_Image_Composer_Interface Composes branded variants pre-sideload. */
+	private PRAutoBlogger_Image_Composer_Interface $composer;
+	/** @var PRAutoBlogger_Image_Attacher Sideloads + meta-links results and variants. */
+	private PRAutoBlogger_Image_Attacher $attacher;
+	/** @var PRAutoBlogger_Opik_Trace_Context|null Optional tracing context. */
+	private ?PRAutoBlogger_Opik_Trace_Context $trace_context;
+
+	/**
+	 * Construct with dependencies. When no provider is injected, the
+	 * `prautoblogger_image_provider` setting picks the concrete class
+	 * ('runware' or 'openrouter').
+	 *
+	 * @param PRAutoBlogger_Image_Provider_Interface|null $provider Optional provider override.
+	 * @param PRAutoBlogger_Cost_Tracker|null             $cost_tracker Optional cost tracker.
+	 * @param PRAutoBlogger_Opik_Trace_Context|null       $trace_context Optional tracing context.
+	 * @param PRAutoBlogger_Image_Composer_Interface|null $composer Optional composer override.
+	 */
+	public function __construct(
+		?PRAutoBlogger_Image_Provider_Interface $provider = null,
+		?PRAutoBlogger_Cost_Tracker $cost_tracker = null,
+		?PRAutoBlogger_Opik_Trace_Context $trace_context = null,
+		?PRAutoBlogger_Image_Composer_Interface $composer = null
+	) {
+		$this->provider       = $provider ?? self::create_default_provider();
+		$this->prompt_builder = new PRAutoBlogger_Image_Prompt_Builder( $trace_context );
+		$this->sideloader     = new PRAutoBlogger_Image_Media_Sideloader();
+		$this->cost_tracker   = $cost_tracker ?? new PRAutoBlogger_Cost_Tracker();
+		$this->composer       = $composer ?? new PRAutoBlogger_Image_Composer();
+		$this->attacher       = new PRAutoBlogger_Image_Attacher( $this->sideloader, $this->cost_tracker );
+		$this->trace_context  = $trace_context;
+	}
+
+	/**
+	 * Instantiate the image provider based on the admin setting. Defaults
+	 * to Runware on unrecognised values (CF was removed in v0.10.0).
+	 *
+	 * @return PRAutoBlogger_Image_Provider_Interface
+	 */
+	private static function create_default_provider(): PRAutoBlogger_Image_Provider_Interface {
+		$provider_id = (string) get_option( 'prautoblogger_image_provider', PRAUTOBLOGGER_DEFAULT_IMAGE_PROVIDER );
+		if ( 'openrouter' === $provider_id ) {
+			return new PRAutoBlogger_OpenRouter_Image_Provider();
+		}
+		return new PRAutoBlogger_Runware_Image_Provider();
+	}
+
+	/**
+	 * Generate and attach images to a published post.
+	 *
+	 * Builds all prompts upfront, fires a single batch call (parallel via
+	 * curl_multi on OpenRouter), then processes results. Wall-clock time
+	 * equals the slowest image, not the sum — solving the Image B timeout.
+	 *
+	 * @param int        $post_id      Post ID to attach images to.
+	 * @param array      $article_data Article title + content.
+	 * @param array|null $source_data  Optional source data for Image B.
+	 *
+	 * @return array{image_a_id?: int, image_b_id?: int, cost_usd: float, errors: string[]}
+	 */
+	public function generate_and_attach_images(
+		int $post_id,
+		array $article_data,
+		?array $source_data = null
+	): array {
+		$result = array(
+			'cost_usd' => 0.0,
+			'errors'   => array(),
+		);
+
+		if ( ! get_option( 'prautoblogger_image_enabled' ) ) {
+			PRAutoBlogger_Logger::instance()->info( 'Image generation disabled in settings.', 'image_pipeline' );
+			return $result;
+		}
+
+		// Check whether Image B is enabled in settings.
+		$image_b_enabled = get_option( 'prautoblogger_image_b_enabled', '1' );
+		$has_source_data = null !== $source_data && ! empty( $source_data );
+		$generate_b      = $has_source_data && '1' === $image_b_enabled;
+
+		// Budget pre-check: estimate cost for all images before any HTTP calls.
+		$image_count    = $generate_b ? 2 : 1;
+		$estimated_cost = $this->provider->estimate_cost( self::DEFAULT_WIDTH, self::DEFAULT_HEIGHT ) * $image_count;
+		if ( $this->cost_tracker->would_exceed_budget( $estimated_cost ) ) {
+			$result['errors'][] = 'Image generation would exceed monthly budget.';
+			return $result;
+		}
+
+		// v0.18.0 — per-run governor: reserve the curl_multi batch's SUMMED
+		// worst-case estimate before dispatch (no-op outside a governed
+		// run). A breach halts the run and skips the whole batch.
+		try {
+			$batch_reservation = PRAutoBlogger_Cost_Governor::open_amount_reservation( $estimated_cost, 'image_batch' );
+		} catch ( PRAutoBlogger_Cost_Ceiling_Exception $e ) {
+			$result['errors'][] = $e->getMessage();
+			return $result;
+		}
+
+		// Build all prompts upfront (LLM calls happen here, sequentially).
+		$article_prompt = $this->prompt_builder->build_article_prompt( $article_data );
+		$batch_requests = array(
+			'image_a' => array(
+				'prompt' => $article_prompt['prompt'],
+				'width'  => self::DEFAULT_WIDTH,
+				'height' => self::DEFAULT_HEIGHT,
+			),
+		);
+		$captions       = array( 'image_a' => $article_prompt['caption'] );
+
+		$source_prompt = null;
+		if ( $generate_b ) {
+			$source_prompt             = $this->prompt_builder->build_source_prompt( $source_data );
+			$batch_requests['image_b'] = array(
+				'prompt' => $source_prompt['prompt'],
+				'width'  => self::DEFAULT_WIDTH,
+				'height' => self::DEFAULT_HEIGHT,
+			);
+			$captions['image_b']       = $source_prompt['caption'];
+		}
+
+		// Fire all image generation requests in parallel.
+		try {
+			$batch_results = $this->provider->generate_image_batch( $batch_requests );
+		} catch ( \Throwable $e ) {
+			PRAutoBlogger_Cost_Governor::release( $batch_reservation );
+			PRAutoBlogger_Logger::instance()->error( 'Batch generation failed: ' . $e->getMessage(), 'image_pipeline' );
+			$result['errors'][] = $e->getMessage();
+			return $result;
+		}
+
+		// Settle the batch reservation to the actual per-image costs.
+		$actual_batch_cost = 0.0;
+		foreach ( $batch_results as $batch_entry ) {
+			$actual_batch_cost += (float) ( $batch_entry['cost_usd'] ?? 0 );
+		}
+		PRAutoBlogger_Cost_Governor::settle( $batch_reservation, $actual_batch_cost );
+
+		// Single-shot retry for any slot the provider flagged as NSFW-blocked.
+		if ( PRAutoBlogger_Image_NSFW_Retry::is_enabled() ) {
+			( new PRAutoBlogger_Image_NSFW_Retry( $this->provider, $this->prompt_builder ) )
+				->retry_blocked_slots( $post_id, $batch_requests, $batch_results, $captions, $article_data, $source_data );
+		}
+
+		$title = (string) ( $article_data['post_title'] ?? $article_data['suggested_title'] ?? '' );
+
+		// Process Image A result.
+		$this->process_slot( 'image_a', $post_id, $batch_results, $captions, $title, $result );
+
+		// Process Image B result (if requested).
+		if ( isset( $batch_results['image_b'] ) ) {
+			$this->process_slot( 'image_b', $post_id, $batch_results, $captions, $title, $result );
+		} elseif ( null === $source_data || empty( $source_data ) ) {
+			PRAutoBlogger_Logger::instance()->info(
+				sprintf( 'Image B skipped for post %d: no source data.', $post_id ),
+				'image_pipeline'
+			);
+		}
+
+		return $result;
+	}
+
+	/**
+	 * Process one slot's batch result: compose, sideload, link to the post.
+	 *
+	 * Image A becomes the featured image (role meta, caption prepend, and
+	 * composed OG/square variants meta-linked); Image B is stored in post
+	 * meta with a corner mark only. Alt text is the editorial caption
+	 * (v0.17.0 fix — the model name used to leak here).
+	 *
+	 * @param string $slot          'image_a' or 'image_b'.
+	 * @param int    $post_id       Post ID.
+	 * @param array  $batch_results Keyed results from generate_image_batch().
+	 * @param array  $captions      Keyed captions from prompt builder.
+	 * @param string $title         Post title (composer context).
+	 * @param array  $result        Pipeline result array (modified by reference).
+	 */
+	private function process_slot( string $slot, int $post_id, array $batch_results, array $captions, string $title, array &$result ): void {
+		$label      = 'image_a' === $slot ? 'Image A' : 'Image B';
+		$image_data = $batch_results[ $slot ] ?? null;
+
+		if ( ! $image_data || isset( $image_data['error'] ) ) {
+			$err_msg            = $image_data['error'] ?? sprintf( '%s missing from batch results.', $label );
+			$result['errors'][] = $err_msg;
+			// Log at WARNING so the path is visible even if the outer catch in the
+			// caller doesn't fire. See thread image-mime-bug Issue 2.
+			PRAutoBlogger_Logger::instance()->warning(
+				sprintf( '%s generation failed for post %d: %s', $label, $post_id, $err_msg ),
+				'image_pipeline'
+			);
+			return;
+		}
+
+		$caption  = (string) ( $captions[ $slot ] ?? '' );
+		$variants = $this->compose_variants( $image_data, $post_id, $caption, $title, $slot );
+		$featured = array_merge( $image_data, array_shift( $variants ) );
+
+		$attachment_id = $this->attacher->sideload_and_log( $featured, $post_id, $slot, $label, $caption );
+		if ( is_wp_error( $attachment_id ) ) {
+			$result['errors'][] = $attachment_id->get_error_message();
+			return;
+		}
+
+		$result[ $slot . '_id' ] = $attachment_id;
+		$result['cost_usd']     += $image_data['cost_usd'];
+
+		if ( '' !== $caption ) {
+			update_post_meta( $attachment_id, '_prautoblogger_image_caption', $caption );
+		}
+
+		if ( 'image_a' === $slot ) {
+			set_post_thumbnail( $post_id, $attachment_id );
+			update_post_meta( $attachment_id, '_prautoblogger_image_role', 'featured' );
+			if ( '' !== $caption ) {
+				$this->attacher->prepend_caption_to_post( $post_id, $attachment_id, $caption );
+			}
+			$this->attacher->attach_variants( $variants, $post_id, $attachment_id, $caption, (string) ( $image_data['model'] ?? 'unknown' ) );
+		} else {
+			update_post_meta( $post_id, '_prautoblogger_image_b_id', $attachment_id );
+		}
+	}
+
+	/**
+	 * Run the composer with a hard safety net: any failure (composer bugs
+	 * included — its own internals already degrade) falls back to passing
+	 * the base image through, so composition can never fail a publish.
+	 *
+	 * @param array  $image_data Provider result for one slot.
+	 * @param int    $post_id    Post ID (composer context).
+	 * @param string $caption    Editorial caption (composer context).
+	 * @param string $title      Post title (composer context).
+	 * @param string $slot       'image_a' or 'image_b'.
+	 * @return array<int, array<string, mixed>> Featured-first variant list (never empty).
+	 */
+	private function compose_variants( array $image_data, int $post_id, string $caption, string $title, string $slot ): array {
+		try {
+			$variants = $this->composer->compose(
+				$image_data,
+				array(
+					'post_id' => $post_id,
+					'caption' => $caption,
+					'title'   => $title,
+					'slot'    => $slot,
+				)
+			);
+			if ( ! empty( $variants ) ) {
+				return $variants;
+			}
+		} catch ( \Throwable $e ) {
+			PRAutoBlogger_Logger::instance()->warning(
+				'Image composition failed, publishing original image: ' . $e->getMessage(),
+				'image_composer'
+			);
+		}
+
+		return array( array_merge( $image_data, array( 'role' => 'featured' ) ) );
+	}
+}

includes/core/class-image-prompt-builder.php

@@ -0,0 +1,289 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Builds image prompts from article content or source data.
+ *
+ * Uses a cheap LLM (via OpenRouter) to distill article content into a concise
+ * 1-2 sentence editorial topic/mechanism summary, then substitutes that summary
+ * into the admin-editable editorial style template (the {{ topic_summary }}
+ * slot) to produce a text-free image-gen prompt. Falls back to rule-based
+ * synthesis if the LLM call fails, so image generation never blocks on a
+ * prompt-rewriting outage.
+ *
+ * Triggered by: PRAutoBlogger_Image_Pipeline during content generation run.
+ * Dependencies: PRAutoBlogger_OpenRouter_Provider (LLM call),
+ *               PRAutoBlogger_Image_Template_Filler (template substitution),
+ *               PRAutoBlogger_Cost_Tracker (logs prompt-rewrite cost),
+ *               PRAutoBlogger_Logger (diagnostics).
+ *
+ * @see core/class-image-pipeline.php — Consumes build_article_prompt() and build_source_prompt().
+ * @see providers/class-open-router-provider.php — LLM provider used for rewriting.
+ * @see ARCHITECTURE.md              — Image generation data flow.
+ */
+class PRAutoBlogger_Image_Prompt_Builder {
+
+	/**
+	 * Default system prompt that teaches the LLM how to write image-gen
+	 * prompts. Exposed as a `public const` so the admin-settings layer can
+	 * use it as the default value for `prautoblogger_image_prompt_instructions`.
+	 * The option, when non-empty, wins at call time (see rewrite_via_llm).
+	 *
+	 * Editorial pivot (v0.16.0): the model emits a concise topic/mechanism
+	 * summary as the SCENE — concrete, single centered focal subject, no text,
+	 * no people-as-gag, no logos — which the prompt builder substitutes into
+	 * the editorial style template's {{ topic_summary }} slot. The CAPTION line
+	 * is preserved unchanged for the existing HTML-caption-below-image path.
+	 */
+	public const REWRITER_SYSTEM_PROMPT = <<<'PROMPT'
+You write subject descriptions for a text-free editorial science illustration about peptides, supplements, or biohacking.
+
+Given an article title and summary, output TWO parts separated by a blank line:
+
+SCENE: A concise 1-2 sentence description of the article's core topic or mechanism, written as the SUBJECT of a single editorial illustration. Name ONE concrete, centered focal subject and the few supporting visual elements around it (e.g. a labelled-free vial and dropper, a stylised receptor on a cell membrane, a molecular chain, a dosing syringe, an organ cross-section). Favor a clear central focal point with margin around it so the image crops well. This is image-gen direction, not prose.
+
+CAPTION: A short, informative caption line (under 15 words) for display as HTML text below the image. Plain and editorial, not a joke.
+
+Rules:
+- The SCENE must depict the article's actual subject/mechanism, not a generic science scene.
+- NO text, words, captions, speech bubbles, labels, or logos described in the SCENE — the illustration is text-free; text is rendered separately.
+- NO people used as a visual gag and NO cartoon/comic framing. A human anatomical element (a cell, an organ, a hand holding a vial) is fine if it is the legitimate subject.
+- Do NOT personify molecules, peptides, hormones, or proteins (no "smiling molecule"); depict them as clean stylised diagrams or structures.
+- Keep the staging simple with one clear focal subject, readable at small sizes.
+- Output ONLY the scene and caption. No preamble, no explanation.
+
+Example output format:
+A single glass peptide vial on a clean surface with a fine dropper above it, a faint stylised molecular chain arcing behind as a backdrop, centered with generous negative space.
+
+A concentrated look at how the compound is prepared before use.
+PROMPT;
+
+	/**
+	 * Max tokens for the rewriter response. Enough room for the 1-2 sentence
+	 * topic/mechanism summary plus the short editorial caption line.
+	 */
+	private const REWRITER_MAX_TOKENS = 180;
+
+	/**
+	 * OpenRouter provider for LLM calls. Null until first use.
+	 *
+	 * @var PRAutoBlogger_OpenRouter_Provider|null
+	 */
+	private ?PRAutoBlogger_OpenRouter_Provider $llm = null;
+
+	/**
+	 * Opik trace context for instrumentation.
+	 *
+	 * @var PRAutoBlogger_Opik_Trace_Context|null
+	 */
+	private ?PRAutoBlogger_Opik_Trace_Context $trace_context = null;
+
+	/**
+	 * Constructor.
+	 *
+	 * @param PRAutoBlogger_Opik_Trace_Context|null $trace_context Optional trace context for instrumentation.
+	 */
+	public function __construct( ?PRAutoBlogger_Opik_Trace_Context $trace_context = null ) {
+		$this->trace_context = $trace_context;
+	}
+
+	/**
+	 * Build a visual prompt from finished article content.
+	 *
+	 * Tries LLM rewriting first; falls back to rule-based synthesis on
+	 * failure. Splits scene (the topic summary, for image gen) from caption
+	 * (HTML below the image) and substitutes the scene into the editorial
+	 * style template's {{ topic_summary }} slot.
+	 *
+	 * @param array{post_title?: string, post_content?: string, suggested_title?: string} $article_data
+	 * @return array{prompt: string, caption: string}
+	 */
+	public function build_article_prompt( array $article_data ): array {
+		$title      = $article_data['post_title'] ?? $article_data['suggested_title'] ?? 'Product';
+		$content    = $article_data['post_content'] ?? '';
+		$first_para = PRAutoBlogger_Image_Scene_Parser::extract_first_paragraph( $content );
+
+		$parsed = $this->rewrite_via_llm( $title, $first_para );
+
+		return array(
+			'prompt'  => PRAutoBlogger_Image_Template_Filler::fill( $parsed['scene'] ),
+			'caption' => $parsed['caption'],
+		);
+	}
+
+	/**
+	 * Build a visual prompt from source Reddit thread data. Tries LLM
+	 * rewriting first; falls back to rule-based synthesis on failure.
+	 *
+	 * @param array{title?: string, selftext?: string, comments?: string[]} $source_data
+	 * @return array{prompt: string, caption: string}
+	 */
+	public function build_source_prompt( array $source_data ): array {
+		$title    = $source_data['title'] ?? 'Reddit Discussion';
+		$comments = $source_data['comments'] ?? array();
+		$context  = is_array( $comments ) && ! empty( $comments ) ? $comments[0] : '';
+
+		$parsed = $this->rewrite_via_llm( $title, $context );
+
+		return array(
+			'prompt'  => PRAutoBlogger_Image_Template_Filler::fill( $parsed['scene'] ),
+			'caption' => $parsed['caption'],
+		);
+	}
+
+	/**
+	 * Use a cheap LLM to distill title + context into a visual scene + caption.
+	 *
+	 * The LLM response contains a SCENE line and a CAPTION line separated by a
+	 * blank line. This method parses them apart so the scene drives image gen
+	 * (no text baked in) and the caption is inserted as HTML below the image.
+	 *
+	 * Falls back to rule-based synthesis if the LLM call fails for any
+	 * reason (network, auth, timeout, unexpected response shape).
+	 *
+	 * Side effects: one OpenRouter API call; one cost-tracker log entry.
+	 *
+	 * @param string $title   Article or thread title.
+	 * @param string $context First paragraph or top comment.
+	 * @return array{scene: string, caption: string} Scene for image gen, caption for HTML.
+	 */
+	private function rewrite_via_llm( string $title, string $context ): array {
+		$title   = trim( sanitize_text_field( $title ) );
+		$context = trim( sanitize_text_field( $context ) );
+
+		// Truncate context to keep prompt tokens low.
+		if ( strlen( $context ) > 300 ) {
+			$context = substr( $context, 0, 300 ) . '...';
+		}
+
+		$user_message = "Article title: {$title}";
+		if ( '' !== $context ) {
+			$user_message .= "\n\nSummary: {$context}";
+		}
+
+		$span_id = null;
+
+		try {
+			if ( null !== $this->trace_context ) {
+				$span_id = $this->trace_context->start_span(
+					array(
+						'name'     => 'image_prompt_rewrite',
+						'type'     => 'llm',
+						'model'    => get_option( 'prautoblogger_analysis_model', PRAUTOBLOGGER_DEFAULT_ANALYSIS_MODEL ),
+						'provider' => 'openrouter',
+						'input'    => array(
+							'title'   => $title,
+							'context' => substr( $context, 0, 200 ),
+						),
+					)
+				);
+			}
+
+			$llm    = $this->get_llm_provider();
+			$model  = get_option( 'prautoblogger_analysis_model', PRAUTOBLOGGER_DEFAULT_ANALYSIS_MODEL );
+			$system = $this->resolve_system_prompt();
+
+			$result = $llm->send_chat_completion(
+				array(
+					array(
+						'role'    => 'system',
+						'content' => $system,
+					),
+					array(
+						'role'    => 'user',
+						'content' => $user_message,
+					),
+				),
+				$model,
+				array(
+					'temperature' => 0.7,
+					'max_tokens'  => self::REWRITER_MAX_TOKENS,
+					'stage'       => 'image_prompt_rewrite',
+				)
+			);
+
+			$raw = trim( $result['content'] ?? '' );
+
+			// Log the rewrite cost so it shows in the analytics dashboard.
+			( new PRAutoBlogger_Cost_Tracker() )->log_api_call(
+				null,
+				'image_prompt_rewrite',
+				'openrouter',
+				$model,
+				$result['prompt_tokens'] ?? 0,
+				$result['completion_tokens'] ?? 0
+			);
+
+			$cost = $llm->estimate_cost(
+				$model,
+				$result['prompt_tokens'] ?? 0,
+				$result['completion_tokens'] ?? 0
+			);
+
+			PRAutoBlogger_Logger::instance()->debug(
+				sprintf( 'Image prompt rewritten (%d→%d chars, $%.6f): %s', strlen( $user_message ), strlen( $raw ), $cost, substr( $raw, 0, 120 ) ),
+				'image_prompt_builder'
+			);
+
+			if ( null !== $span_id && null !== $this->trace_context ) {
+				$this->trace_context->end_span(
+					$span_id,
+					array(
+						'output' => array(
+							'raw_response' => substr( $raw, 0, 200 ),
+						),
+						'usage'  => array(
+							'prompt_tokens'     => $result['prompt_tokens'] ?? 0,
+							'completion_tokens' => $result['completion_tokens'] ?? 0,
+							'total_tokens'      => ( $result['prompt_tokens'] ?? 0 ) + ( $result['completion_tokens'] ?? 0 ),
+						),
+					)
+				);
+			}
+
+			if ( '' !== $raw ) {
+				return PRAutoBlogger_Image_Scene_Parser::parse_scene_and_caption( $raw );
+			}
+		} catch ( \Throwable $e ) {
+			// LLM failure is not fatal — fall back to rule-based synthesis.
+			PRAutoBlogger_Logger::instance()->warning(
+				sprintf( 'Image prompt LLM rewrite %s, using fallback: %s', get_class( $e ), $e->getMessage() ),
+				'image_prompt_builder'
+			);
+		}
+
+		return PRAutoBlogger_Image_Scene_Parser::synthesize_visual_concepts_fallback( $title, $context );
+	}
+
+	/**
+	 * Public entry into the rule-based fallback, used by NSFW retry to
+	 * rebuild a provider-safe prompt from just the article title. Matches
+	 * the return shape of build_article_prompt() / build_source_prompt().
+	 *
+	 * @param string $title Article or source title.
+	 * @return array{prompt: string, caption: string}
+	 */
+	public function build_fallback_prompt( string $title ): array {
+		$parsed = PRAutoBlogger_Image_Scene_Parser::synthesize_visual_concepts_fallback( $title, '' );
+		return array(
+			'prompt'  => PRAutoBlogger_Image_Template_Filler::fill( $parsed['scene'] ),
+			'caption' => $parsed['caption'],
+		);
+	}
+
+	/** Lazy-load the OpenRouter provider. */
+	private function get_llm_provider(): PRAutoBlogger_OpenRouter_Provider {
+		if ( null === $this->llm ) {
+			$this->llm = new PRAutoBlogger_OpenRouter_Provider();
+		}
+		return $this->llm;
+	}
+
+	/** Admin option wins; blank falls back to REWRITER_SYSTEM_PROMPT. */
+	private function resolve_system_prompt(): string {
+		$override = (string) get_option( 'prautoblogger_image_prompt_instructions', '' );
+		return '' !== trim( $override ) ? $override : self::REWRITER_SYSTEM_PROMPT;
+	}
+}

includes/core/class-image-scene-parser.php

@@ -0,0 +1,94 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Parses LLM output into scene/caption pairs and synthesises fallback prompts
+ * from article titles when the LLM call fails.
+ *
+ * Who calls it: PRAutoBlogger_Image_Prompt_Builder (static calls).
+ * Dependencies: None.
+ */
+class PRAutoBlogger_Image_Scene_Parser {
+
+	/**
+	 * Parse the LLM response into separate scene and caption parts.
+	 *
+	 * Expected format from the LLM:
+	 *   Scene description text here.
+	 *
+	 *   "Caption punchline here."
+	 *
+	 * Falls back gracefully: if no blank-line separator is found, the entire
+	 * response becomes the scene with an empty caption.
+	 *
+	 * @param string $raw Raw LLM response text.
+	 * @return array{scene: string, caption: string}
+	 */
+	public static function parse_scene_and_caption( string $raw ): array {
+		// Split on blank line (the format the system prompt requests).
+		$parts = preg_split( '/\n\s*\n/', $raw, 2 );
+
+		if ( count( $parts ) >= 2 ) {
+			$scene   = trim( $parts[0] );
+			$caption = trim( $parts[1] );
+			// Strip surrounding quotes from caption — the LLM wraps it in quotes.
+			$caption = trim( $caption, '"\'' );
+			return array(
+				'scene'   => $scene,
+				'caption' => $caption,
+			);
+		}
+
+		// No blank-line separator found — treat entire response as scene.
+		return array(
+			'scene'   => trim( $raw ),
+			'caption' => '',
+		);
+	}
+
+	/**
+	 * Extract the first paragraph from HTML content.
+	 *
+	 * Removes all tags and captures the text up to the first double-newline
+	 * or 200 characters, whichever comes first.
+	 *
+	 * @param string $html HTML content.
+	 * @return string Plain text of the first paragraph.
+	 */
+	public static function extract_first_paragraph( string $html ): string {
+		$text  = wp_strip_all_tags( $html );
+		$paras = preg_split( '/\n\n+/', $text );
+		$para  = isset( $paras[0] ) ? trim( $paras[0] ) : '';
+
+		if ( strlen( $para ) > 200 ) {
+			$para = substr( $para, 0, 200 ) . '...';
+		}
+
+		return $para;
+	}
+
+	/**
+	 * Rule-based fallback when LLM rewriting is unavailable.
+	 *
+	 * Kept deliberately simple — this only runs if OpenRouter is down. Produces
+	 * a text-free editorial-illustration subject (not a comic) so the prompt
+	 * builder always has a non-empty topic summary to substitute into the
+	 * style template, never shipping a blank prompt to the provider (brief A6).
+	 *
+	 * @param string $title           Main heading / topic.
+	 * @param string $supporting_text Additional context.
+	 * @return array{scene: string, caption: string} Scene for image gen, caption for HTML.
+	 */
+	public static function synthesize_visual_concepts_fallback( string $title, string $supporting_text ): array {
+		// Fallback produces a simple editorial-illustration subject when the LLM is unavailable.
+		$scene = sprintf(
+			'A clean, centered editorial science illustration representing the topic of %s, with a single clear focal subject and generous negative space.',
+			$title
+		);
+
+		return array(
+			'scene'   => trim( $scene ),
+			'caption' => '',
+		);
+	}
+}

includes/core/class-image-template-filler.php

@@ -0,0 +1,185 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Fills the admin-editable editorial image-prompt template with the
+ * rewriter-produced topic summary, replacing the old "scene + style suffix"
+ * concatenation.
+ *
+ * The template (option `prautoblogger_image_style_template`, default
+ * PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_TEMPLATE) contains exactly one
+ * `{{ topic_summary }}` token. This class:
+ *   - resolves the active template (admin override wins; blank → default),
+ *   - sanitises and length-clamps the topic summary (brief A5),
+ *   - substitutes the token, and
+ *   - degrades safely (brief A5/A6) so a blank or token-only prompt is never
+ *     emitted to the image provider.
+ *
+ * Who calls it: PRAutoBlogger_Image_Prompt_Builder (static call from each of
+ *               build_article_prompt / build_source_prompt / build_fallback_prompt).
+ * Dependencies: PRAutoBlogger_Logger (diagnostics only).
+ *
+ * @see core/class-image-prompt-builder.php — Sole caller.
+ * @see ARCHITECTURE.md                      — Image generation data flow.
+ */
+class PRAutoBlogger_Image_Template_Filler {
+
+	/** The single substitution token the template must contain. */
+	public const TOKEN = '{{ topic_summary }}';
+
+	/**
+	 * Max characters retained from the rewriter topic summary before it is
+	 * substituted into the template. Keeps the final provider prompt bounded
+	 * even if the rewriter ignores its length guidance.
+	 */
+	public const MAX_SUMMARY_CHARS = 320;
+
+	/**
+	 * Build the final image-generation prompt from a rewriter scene.
+	 *
+	 * @param string $scene Raw topic/mechanism summary from the rewriter (the
+	 *                      "scene" half of the scene/caption contract).
+	 * @return string Provider-ready prompt; never empty.
+	 */
+	public static function fill( string $scene ): string {
+		$template = self::resolve_template();
+		$summary  = self::sanitize_summary( $scene );
+
+		// Brief A6: never ship a blank or token-only prompt. If the rewriter
+		// produced nothing usable, return the template with the token removed
+		// only as a last resort — but the caller guards this by passing a
+		// rule-based fallback scene, so an empty summary here is unexpected.
+		if ( '' === $summary ) {
+			PRAutoBlogger_Logger::instance()->warning(
+				'Editorial prompt fill received an empty topic summary; emitting style-only prompt.',
+				'image_template_filler'
+			);
+			return self::strip_token( $template );
+		}
+
+		$token_count = substr_count( $template, self::TOKEN );
+
+		if ( 1 === $token_count ) {
+			return trim( str_replace( self::TOKEN, $summary, $template ) );
+		}
+
+		// Brief A5: admin removed or duplicated the token. Fall back to
+		// appending the summary to the style text and log a warning rather
+		// than shipping a malformed prompt.
+		PRAutoBlogger_Logger::instance()->warning(
+			sprintf(
+				'Image style template has %d "%s" tokens (expected 1); appending summary instead of substituting.',
+				$token_count,
+				self::TOKEN
+			),
+			'image_template_filler'
+		);
+
+		$base = self::strip_token( $template );
+		return trim( $base . ' ' . $summary );
+	}
+
+	/**
+	 * Sanitise and validate the admin-submitted style template on save.
+	 *
+	 * Multi-line, so sanitised with sanitize_textarea_field() (not
+	 * sanitize_text_field(), which would strip newlines). Per brief A5 the
+	 * template must contain exactly one TOKEN; otherwise the previous value is
+	 * kept and a settings error is surfaced. A blank submission falls back to
+	 * the editorial default so image generation can never be bricked.
+	 *
+	 * @param string $value Submitted template.
+	 * @return string Sanitised, validated template.
+	 */
+	public static function sanitize_for_save( string $value ): string {
+		$clean = sanitize_textarea_field( $value );
+
+		if ( '' === trim( $clean ) ) {
+			return PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_TEMPLATE;
+		}
+
+		$token_count = substr_count( $clean, self::TOKEN );
+		if ( 1 !== $token_count ) {
+			add_settings_error(
+				'prautoblogger_image_style_template',
+				'prautoblogger_image_style_template_token',
+				sprintf(
+					/* translators: 1: required token, 2: number of tokens found. */
+					esc_html__( 'The Style Template must contain exactly one %1$s token (found %2$d). Keeping the previous value.', 'prautoblogger' ),
+					esc_html( self::TOKEN ),
+					(int) $token_count
+				)
+			);
+			return (string) get_option( 'prautoblogger_image_style_template', PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_TEMPLATE );
+		}
+
+		return $clean;
+	}
+
+	/**
+	 * Resolve the active template: admin override wins; blank → default.
+	 *
+	 * @return string Non-empty template string.
+	 */
+	private static function resolve_template(): string {
+		$override = (string) get_option( 'prautoblogger_image_style_template', '' );
+		if ( '' !== trim( $override ) ) {
+			return $override;
+		}
+		return PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_TEMPLATE;
+	}
+
+	/**
+	 * Strip control characters and clamp length of the rewriter summary
+	 * (brief A5). Whitespace runs (including newlines) are collapsed to single
+	 * spaces so the summary sits cleanly inside the template.
+	 *
+	 * @param string $scene Raw rewriter scene.
+	 * @return string Sanitised, length-clamped summary (possibly empty).
+	 */
+	private static function sanitize_summary( string $scene ): string {
+		// Remove control characters (C0/C1) except via whitespace collapse below.
+		$clean = preg_replace( '/[\x00-\x1F\x7F]+/u', ' ', $scene );
+		if ( null === $clean ) {
+			// preg_replace can return null on bad UTF-8; degrade conservatively.
+			$clean = preg_replace( '/[\x00-\x1F\x7F]+/', ' ', $scene );
+			$clean = is_string( $clean ) ? $clean : '';
+		}
+
+		// Collapse whitespace runs to single spaces.
+		$collapsed = preg_replace( '/\s+/u', ' ', $clean );
+		$clean     = is_string( $collapsed ) ? $collapsed : $clean;
+		$clean     = trim( $clean );
+
+		if ( '' === $clean ) {
+			return '';
+		}
+
+		// Clamp length (multibyte-aware where available).
+		if ( function_exists( 'mb_strlen' ) ) {
+			if ( mb_strlen( $clean ) > self::MAX_SUMMARY_CHARS ) {
+				$clean = rtrim( mb_substr( $clean, 0, self::MAX_SUMMARY_CHARS ) ) . '...';
+			}
+		} elseif ( strlen( $clean ) > self::MAX_SUMMARY_CHARS ) {
+			$clean = rtrim( substr( $clean, 0, self::MAX_SUMMARY_CHARS ) ) . '...';
+		}
+
+		return $clean;
+	}
+
+	/**
+	 * Remove every occurrence of the token from a template, tidying the
+	 * leftover whitespace so the residual style text is still well-formed.
+	 *
+	 * @param string $template Template possibly containing the token.
+	 * @return string Token-free, trimmed template.
+	 */
+	private static function strip_token( string $template ): string {
+		$stripped = str_replace( self::TOKEN, '', $template );
+		$stripped = preg_replace( '/[ \t]+/', ' ', $stripped );
+		$stripped = is_string( $stripped ) ? $stripped : $template;
+		return trim( $stripped );
+	}
+}

includes/core/class-json-extractor.php

@@ -0,0 +1,62 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Extracts valid JSON from potentially dirty LLM response strings.
+ *
+ * Many models ignore the `response_format: json_object` instruction and wrap
+ * their output in markdown fences, add preamble text, or append trailing
+ * commentary. This class strips all of that and returns clean decoded data.
+ *
+ * Triggered by: Any class that parses JSON from an LLM response.
+ * Dependencies: None (pure utility).
+ *
+ * @see core/class-content-analyzer.php — Uses this for analysis JSON parsing.
+ * @see core/class-chief-editor.php     — Uses this for editorial review JSON parsing.
+ */
+class PRAutoBlogger_Json_Extractor {
+
+	/**
+	 * Decode JSON from an LLM response, tolerating markdown fences and preamble.
+	 *
+	 * Attempts, in order:
+	 * 1. Direct json_decode (model returned clean JSON).
+	 * 2. Strip ```json ... ``` fences, then decode.
+	 * 3. Find the first `{` and last `}` and decode that substring.
+	 *
+	 * @param string $raw The raw LLM response content.
+	 * @return array<string, mixed>|null Decoded associative array, or null on failure.
+	 */
+	public static function decode( string $raw ): ?array {
+		$trimmed = trim( $raw );
+
+		// 1. Clean JSON — best case.
+		$decoded = json_decode( $trimmed, true );
+		if ( is_array( $decoded ) ) {
+			return $decoded;
+		}
+
+		// 2. Markdown-fenced JSON (```json ... ``` or ``` ... ```).
+		if ( preg_match( '/```(?:json)?\s*\n?(.*?)\n?\s*```/s', $trimmed, $matches ) ) {
+			$decoded = json_decode( trim( $matches[1] ), true );
+			if ( is_array( $decoded ) ) {
+				return $decoded;
+			}
+		}
+
+		// 3. Brute-force: find outermost { ... } substring.
+		$first_brace = strpos( $trimmed, '{' );
+		$last_brace  = strrpos( $trimmed, '}' );
+		if ( false !== $first_brace && false !== $last_brace && $last_brace > $first_brace ) {
+			$candidate = substr( $trimmed, $first_brace, $last_brace - $first_brace + 1 );
+			$decoded   = json_decode( $candidate, true );
+			if ( is_array( $decoded ) ) {
+				return $decoded;
+			}
+		}
+
+		return null;
+	}
+}

includes/core/class-logger.php

@@ -2,6 +2,8 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Structured logging with configurable verbosity levels.
  *
  * Writes log entries to a custom database table and optionally forwards
@@ -26,19 +28,19 @@ class PRAutoBlogger_Logger {
 	public const LEVEL_INFO    = 2;
 	public const LEVEL_DEBUG   = 3;
 
-	private const LEVEL_MAP = [
+	private const LEVEL_MAP = array(
 		'error'   => self::LEVEL_ERROR,
 		'warning' => self::LEVEL_WARNING,
 		'info'    => self::LEVEL_INFO,
 		'debug'   => self::LEVEL_DEBUG,
-	];
+	);
 
-	private const LEVEL_LABELS = [
+	private const LEVEL_LABELS = array(
 		self::LEVEL_ERROR   => 'error',
 		self::LEVEL_WARNING => 'warning',
 		self::LEVEL_INFO    => 'info',
 		self::LEVEL_DEBUG   => 'debug',
-	];
+	);
 
 	/** Singleton instance. */
 	private static ?self $instance = null;
@@ -66,7 +68,7 @@ class PRAutoBlogger_Logger {
 	 * @param string $context  Origin class or pipeline stage.
 	 * @param array<string, mixed> $meta Optional structured data.
 	 */
-	public function error( string $message, string $context = '', array $meta = [] ): void {
+	public function error( string $message, string $context = '', array $meta = array() ): void {
 		$this->log( self::LEVEL_ERROR, $message, $context, $meta );
 	}
 
@@ -77,7 +79,7 @@ class PRAutoBlogger_Logger {
 	 * @param string $context
 	 * @param array<string, mixed> $meta
 	 */
-	public function warning( string $message, string $context = '', array $meta = [] ): void {
+	public function warning( string $message, string $context = '', array $meta = array() ): void {
 		$this->log( self::LEVEL_WARNING, $message, $context, $meta );
 	}
 
@@ -88,7 +90,7 @@ class PRAutoBlogger_Logger {
 	 * @param string $context
 	 * @param array<string, mixed> $meta
 	 */
-	public function info( string $message, string $context = '', array $meta = [] ): void {
+	public function info( string $message, string $context = '', array $meta = array() ): void {
 		$this->log( self::LEVEL_INFO, $message, $context, $meta );
 	}
 
@@ -99,7 +101,7 @@ class PRAutoBlogger_Logger {
 	 * @param string $context
 	 * @param array<string, mixed> $meta
 	 */
-	public function debug( string $message, string $context = '', array $meta = [] ): void {
+	public function debug( string $message, string $context = '', array $meta = array() ): void {
 		$this->log( self::LEVEL_DEBUG, $message, $context, $meta );
 	}
 
@@ -126,16 +128,24 @@ class PRAutoBlogger_Logger {
 		}
 
 		global $wpdb;
+		if ( null === $wpdb ) {
+			// No database available (unit test environment). PHP error_log
+			// was already called above for warnings/errors; silently skip DB write.
+			return;
+		}
 		$table = $wpdb->prefix . 'prautoblogger_event_log';
 
 		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-		$wpdb->insert( $table, [
-			'level'      => $label,
-			'context'    => substr( $context, 0, 100 ),
-			'message'    => substr( $message, 0, 2000 ),
-			'meta_json'  => ! empty( $meta ) ? wp_json_encode( $meta ) : null,
-			'created_at' => current_time( 'mysql' ),
-		] );
+		$wpdb->insert(
+			$table,
+			array(
+				'level'      => $label,
+				'context'    => substr( $context, 0, 100 ),
+				'message'    => substr( $message, 0, 2000 ),
+				'meta_json'  => ! empty( $meta ) ? wp_json_encode( $meta ) : null,
+				'created_at' => current_time( 'mysql' ),
+			)
+		);
 	}
 
 	/**
@@ -156,8 +166,8 @@ class PRAutoBlogger_Logger {
 	): array {
 		global $wpdb;
 		$table  = $wpdb->prefix . 'prautoblogger_event_log';
-		$where  = [];
-		$params = [];
+		$where  = array();
+		$params = array();
 
 		if ( 'all' !== $level_filter && isset( self::LEVEL_MAP[ $level_filter ] ) ) {
 			$where[]  = 'level = %s';
@@ -176,10 +186,10 @@ class PRAutoBlogger_Logger {
 
 		// Total count.
 		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
-		$total = (int) $wpdb->get_var(
-			empty( $params )
-				? "SELECT COUNT(*) FROM {$table} {$where_sql}"
-				: $wpdb->prepare( "SELECT COUNT(*) FROM {$table} {$where_sql}", ...$params )
+		$total = (int) $wpdb->get_var(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+			empty( $params )  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.DB.PreparedSQL.NotPrepared
+				? "SELECT COUNT(*) FROM {$table} {$where_sql}"  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.DB.PreparedSQL.NotPrepared
+			: $wpdb->prepare( "SELECT COUNT(*) FROM {$table} {$where_sql}", ...$params )  // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared
 		);
 
 		// Rows.
@@ -189,14 +199,17 @@ class PRAutoBlogger_Logger {
 
 		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
 		$rows = $wpdb->get_results(
-			$wpdb->prepare(
+			$wpdb->prepare(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
 				"SELECT * FROM {$table} {$where_sql} ORDER BY created_at DESC LIMIT %d OFFSET %d",
 				...$query_params
 			),
 			ARRAY_A
 		);
 
-		return [ 'rows' => $rows ?: [], 'total' => $total ];
+		return array(
+			'rows'  => $rows ?? array(),
+			'total' => $total,
+		);
 	}
 
 	/**
@@ -211,7 +224,7 @@ class PRAutoBlogger_Logger {
 
 		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
 		return (int) $wpdb->query(
-			$wpdb->prepare(
+			$wpdb->prepare(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
 				"DELETE FROM {$table} WHERE created_at < %s",
 				gmdate( 'Y-m-d H:i:s', time() - ( $days * DAY_IN_SECONDS ) )
 			)

includes/core/class-metrics-collector.php

@@ -2,6 +2,8 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Collects post performance metrics from WordPress native data and Google Analytics 4.
  *
  * Runs on a separate cron schedule (every 6 hours) to gather pageviews, bounce rate,
@@ -35,8 +37,8 @@ class PRAutoBlogger_Metrics_Collector {
 		}
 
 		$ga4_client = new PRAutoBlogger_GA4_Client();
-		$ga4_data = $ga4_client->fetch_data( $posts );
-		$scored   = 0;
+		$ga4_data   = $ga4_client->fetch_data( $posts );
+		$scored     = 0;
 
 		foreach ( $posts as $post ) {
 			$post_id    = (int) $post->ID;
@@ -47,11 +49,11 @@ class PRAutoBlogger_Metrics_Collector {
 				continue;
 			}
 
-			$ga_metrics = $ga4_data[ $post_id ] ?? [];
+			$ga_metrics = $ga4_data[ $post_id ] ?? array();
 
 			$score = $this->compute_composite_score( $wp_metrics, $ga_metrics, $post );
 			$this->store_score( $post_id, $wp_metrics, $ga_metrics, $score );
-			$scored++;
+			++$scored;
 		}
 
 		PRAutoBlogger_Logger::instance()->info( sprintf( 'Metrics collected for %d posts.', $scored ), 'metrics' );
@@ -64,15 +66,17 @@ class PRAutoBlogger_Metrics_Collector {
 	 * @return \WP_Post[]
 	 */
 	private function get_generated_posts(): array {
-		$query = new \WP_Query( [
-			'post_type'      => 'post',
-			'post_status'    => 'publish',
-			'meta_key'       => '_prautoblogger_generated',
-			'meta_value'     => '1',
-			'posts_per_page' => 100,
-			'orderby'        => 'date',
-			'order'          => 'DESC',
-		] );
+		$query = new \WP_Query(
+			array(
+				'post_type'      => 'post',
+				'post_status'    => 'publish',
+				'meta_key'       => '_prautoblogger_generated',
+				'meta_value'     => '1',
+				'posts_per_page' => 100,
+				'orderby'        => 'date',
+				'order'          => 'DESC',
+			)
+		);
 
 		return $query->posts;
 	}
@@ -93,10 +97,10 @@ class PRAutoBlogger_Metrics_Collector {
 			return null;
 		}
 
-		return [
+		return array(
 			'comment_count'  => (int) ( $post->comment_count ?? 0 ),
 			'days_published' => max( 1, (int) ( ( time() - strtotime( $post->post_date ) ) / DAY_IN_SECONDS ) ),
-		];
+		);
 	}
 
 
@@ -110,10 +114,10 @@ class PRAutoBlogger_Metrics_Collector {
 	 * @return array{score: float, factors: array<string, float>}
 	 */
 	private function compute_composite_score( array $wp_metrics, array $ga_metrics, \WP_Post $post ): array {
-		$factors = [];
+		$factors = array();
 
 		// Comment engagement (0-25 points).
-		$comments_per_day = $wp_metrics['comment_count'] / max( 1, $wp_metrics['days_published'] );
+		$comments_per_day    = $wp_metrics['comment_count'] / max( 1, $wp_metrics['days_published'] );
 		$factors['comments'] = min( 25.0, $comments_per_day * 25.0 );
 
 		// Pageview performance (0-30 points, if GA4 available).
@@ -142,10 +146,10 @@ class PRAutoBlogger_Metrics_Collector {
 
 		$total = array_sum( $factors );
 
-		return [
+		return array(
 			'score'   => round( $total, 2 ),
 			'factors' => $factors,
-		];
+		);
 	}
 
 	/**
@@ -162,16 +166,18 @@ class PRAutoBlogger_Metrics_Collector {
 		global $wpdb;
 		$table = $wpdb->prefix . 'prautoblogger_content_scores';
 
-		$entry = new PRAutoBlogger_Content_Score( [
-			'post_id'          => $post_id,
-			'pageviews'        => $ga_metrics['pageviews'] ?? 0,
-			'avg_time_on_page' => $ga_metrics['avg_time_on_page'] ?? 0.0,
-			'bounce_rate'      => $ga_metrics['bounce_rate'] ?? 0.0,
-			'comment_count'    => $wp_metrics['comment_count'] ?? 0,
-			'composite_score'  => $score_data['score'],
-			'score_factors'    => $score_data['factors'],
-			'measured_at'      => current_time( 'mysql' ),
-		] );
+		$entry = new PRAutoBlogger_Content_Score(
+			array(
+				'post_id'          => $post_id,
+				'pageviews'        => $ga_metrics['pageviews'] ?? 0,
+				'avg_time_on_page' => $ga_metrics['avg_time_on_page'] ?? 0.0,
+				'bounce_rate'      => $ga_metrics['bounce_rate'] ?? 0.0,
+				'comment_count'    => $wp_metrics['comment_count'] ?? 0,
+				'composite_score'  => $score_data['score'],
+				'score_factors'    => $score_data['factors'],
+				'measured_at'      => current_time( 'mysql' ),
+			)
+		);
 
 		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
 		$wpdb->insert( $table, $entry->to_db_row() );

includes/core/class-peptide-linker.php

@@ -0,0 +1,159 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Deterministic post-processor that hyperlinks peptide mentions in HTML content.
+ *
+ * Scans generated article HTML for any peptide name that exists in the PR Core
+ * database and wraps every mention in an <a> tag pointing to its /peptides/ page.
+ * Skips text that is already inside an existing <a> tag to avoid nested links.
+ *
+ * Triggered by: PRAutoBlogger_Publisher::create_post() (before wp_insert_post).
+ * Dependencies: PR Core plugin (pr_peptide CPT). Gracefully no-ops if PR Core is inactive.
+ *
+ * @see core/class-publisher.php — Calls inject_links() on post_content.
+ * @see peptide-repo-core/includes/cpt/class-pr-core-peptide-cpt.php — Peptide CPT.
+ */
+class PRAutoBlogger_Peptide_Linker {
+
+	/**
+	 * Inject peptide hyperlinks into HTML content.
+	 *
+	 * Every occurrence of a known peptide name is wrapped in a link to its
+	 * database page, except when the text is already inside an <a> tag.
+	 *
+	 * @param string $html Article HTML content.
+	 * @return string HTML with peptide names hyperlinked.
+	 */
+	public static function inject_links( string $html ): string {
+		if ( ! post_type_exists( 'pr_peptide' ) ) {
+			return $html;
+		}
+
+		$link_map = self::build_link_map();
+		if ( empty( $link_map ) ) {
+			return $html;
+		}
+
+		// Build a single regex alternation of all peptide names, longest first
+		// so "BPC-157" matches before a hypothetical "BPC" would.
+		$names = array_keys( $link_map );
+		usort(
+			$names,
+			static function ( string $a, string $b ): int {
+				return strlen( $b ) - strlen( $a );
+			}
+		);
+
+		$escaped = array_map(
+			static function ( string $name ): string {
+				return preg_quote( $name, '/' );
+			},
+			$names
+		);
+
+		// Word-boundary match, case-insensitive.
+		$pattern = '/\b(' . implode( '|', $escaped ) . ')\b/iu';
+
+		// Split HTML into segments: inside <a>…</a> tags vs. outside.
+		// Only replace in segments that are NOT inside an anchor tag.
+		return self::replace_outside_links( $html, $pattern, $link_map );
+	}
+
+	/**
+	 * Build a map of peptide display names → permalink URLs.
+	 *
+	 * Includes the canonical title and common aliases (e.g., "BPC-157" and
+	 * "BPC 157") so both hyphenated and space-separated forms get linked.
+	 *
+	 * @return array<string, string> Name → URL pairs, case-preserved keys.
+	 */
+	private static function build_link_map(): array {
+		$peptides = get_posts(
+			array(
+				'post_type'      => 'pr_peptide',
+				'post_status'    => 'publish',
+				'posts_per_page' => 200,
+				'orderby'        => 'title',
+				'order'          => 'ASC',
+				'fields'         => 'ids',
+			)
+		);
+
+		$map = array();
+		foreach ( $peptides as $peptide_id ) {
+			$title = get_the_title( $peptide_id );
+			$url   = get_permalink( $peptide_id );
+			if ( ! $title || ! $url ) {
+				continue;
+			}
+
+			// Canonical name (e.g., "BPC-157").
+			$map[ $title ] = $url;
+
+			// If the name contains hyphens, also match the space-separated
+			// variant (e.g., "BPC 157" → same URL as "BPC-157").
+			if ( strpos( $title, '-' ) !== false ) {
+				$space_variant         = str_replace( '-', ' ', $title );
+				$map[ $space_variant ] = $url;
+			}
+		}
+
+		return $map;
+	}
+
+	/**
+	 * Replace peptide names with links, but only outside existing <a> tags.
+	 *
+	 * Splits HTML into chunks by <a …>…</a> boundaries. Replacement only
+	 * runs on chunks that are outside anchors, preventing nested <a> tags.
+	 *
+	 * @param string              $html     Full HTML content.
+	 * @param string              $pattern  Regex pattern matching peptide names.
+	 * @param array<string,string> $link_map Name → URL map (case-preserved keys).
+	 * @return string HTML with replacements applied.
+	 */
+	private static function replace_outside_links( string $html, string $pattern, array $link_map ): string {
+		// Split on anchor tags, keeping the delimiters.
+		// This regex captures full <a …>…</a> blocks as array elements.
+		$parts = preg_split( '/(<a\s[^>]*>.*?<\/a>)/is', $html, -1, PREG_SPLIT_DELIM_CAPTURE );
+
+		if ( false === $parts ) {
+			return $html;
+		}
+
+		// Build a lowercase → URL lookup for case-insensitive matching.
+		$lower_map = array();
+		foreach ( $link_map as $name => $url ) {
+			$lower_map[ mb_strtolower( $name ) ] = $url;
+		}
+
+		$result = '';
+		foreach ( $parts as $part ) {
+			// If this chunk is an anchor tag, pass it through untouched.
+			if ( preg_match( '/^<a\s/i', $part ) ) {
+				$result .= $part;
+				continue;
+			}
+
+			// Replace peptide names with hyperlinks.
+			$result .= preg_replace_callback(
+				$pattern,
+				static function ( array $matches ) use ( $lower_map ): string {
+					$matched_text = $matches[0];
+					$key          = mb_strtolower( $matched_text );
+					$url          = $lower_map[ $key ] ?? '';
+					if ( '' === $url ) {
+						return $matched_text;
+					}
+					return '<a href="' . esc_url( $url ) . '">' . esc_html( $matched_text ) . '</a>';
+				},
+				$part
+			);
+		}
+
+		return $result;
+	}
+}

includes/core/class-pipeline-runner.php

@@ -2,41 +2,39 @@
 declare(strict_types=1);
 
 /**
- * Executes the full content generation pipeline.
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Executes the content generation pipeline using a chained-job architecture.
  *
  * Orchestrates: Budget check → Collect source data → Analyze patterns →
- * Score ideas → Generate content → Editorial review → Publish.
+ * Score ideas → Generate article 1 in-process → Queue articles 2..N as
+ * individual WP-Cron events so each gets its own PHP execution time budget.
  *
- * Triggered by: PRAutoBlogger::on_daily_generation() and PRAutoBlogger::on_ajax_generate_now().
- * Dependencies: All core content classes (Collector, Analyzer, Scorer, Generator, Editor, Publisher).
+ * Why chained jobs: Hostinger kills PHP processes at ~120s. A single article
+ * (LLM generation + editorial + 2 images) takes ~60-90s, so one-per-process
+ * is safe. Running N articles sequentially in one process times out at N≥2.
  *
- * @see class-prautoblogger.php         — Instantiates this class and calls run().
- * @see core/class-cost-tracker.php   — Tracks cumulative API costs throughout the run.
- * @see ARCHITECTURE.md               — Data flow diagram showing pipeline steps.
+ * Triggered by: PRAutoBlogger_Executor (daily cron + manual "Generate Now").
+ * Dependencies: Core content classes, Article_Worker, WP-Cron for chaining.
+ *
+ * @see class-executor.php              — Cron/AJAX handlers that call us.
+ * @see core/class-article-worker.php   — Single-article generation worker.
+ * @see core/class-cost-tracker.php     — Tracks costs throughout the run.
+ * @see ARCHITECTURE.md                 — Data flow diagram.
  */
 class PRAutoBlogger_Pipeline_Runner {
 
-	/**
-	 * Execute the full content generation pipeline.
-	 *
-	 * Steps: Budget check → Collect source data → Analyze patterns →
-	 *        Score ideas → Generate content → Editorial review → Publish.
-	 *
-	 * Side effects: API calls (OpenRouter, Reddit), database writes, post creation.
-	 *
-	 * @return array{generated: int, published: int, rejected: int, cost: float} Pipeline results.
-	 *
-	 * @throws \RuntimeException If budget is exceeded or critical step fails.
-	 */
-	/** @var bool Whether to skip duplicate-topic detection (used for manual runs). */
+	/** Option key for the article generation queue. */
+	private const QUEUE_KEY = 'prautoblogger_article_queue';
+
+	/** WP-Cron action for chained article generation. */
+	public const CRON_ACTION = 'prautoblogger_generate_queued_article';
+
+	/** @var bool Whether to skip duplicate-topic detection. */
 	private bool $skip_dedup = false;
 
 	/**
-	 * Allow manual runs to skip the has_similar_post() check so "Generate Now"
-	 * always produces content even when a related article was recently published.
-	 *
 	 * @param bool $skip True to skip deduplication.
-	 *
 	 * @return $this
 	 */
 	public function set_skip_dedup( bool $skip ): self {
@@ -44,104 +42,229 @@ class PRAutoBlogger_Pipeline_Runner {
 		return $this;
 	}
 
+	/**
+	 * Run orchestration and generate the first article in-process.
+	 *
+	 * Steps: Budget check → Collect → Analyze → Score → Generate article 1.
+	 * Remaining articles are queued as chained WP-Cron events.
+	 *
+	 * Side effects: API calls, DB writes, post creation, cron scheduling.
+	 *
+	 * @return array{generated: int, published: int, rejected: int, cost: float}
+	 * @throws \RuntimeException If budget exceeded.
+	 */
 	public function run(): array {
 		$cost_tracker = new PRAutoBlogger_Cost_Tracker();
-
-		// Tag all log entries in this run with a unique ID so link_generation_logs()
-		// can accurately attribute costs to the correct post in batch runs.
 		$cost_tracker->set_run_id( wp_generate_uuid4() );
 
-		// Hard stop if monthly budget is exceeded.
 		if ( $cost_tracker->is_budget_exceeded() ) {
 			throw new \RuntimeException(
 				__( 'Monthly API budget exceeded. Generation halted.', 'prautoblogger' )
 			);
 		}
 
-		$target_count = absint( get_option( 'prautoblogger_daily_article_target', 1 ) );
+		$ideas = $this->orchestrate( $cost_tracker );
+		if ( empty( $ideas ) ) {
+			PRAutoBlogger_Run_State::mark_status( (string) $cost_tracker->get_run_id(), 'done' );
+			return array(
+				'generated' => 0,
+				'published' => 0,
+				'rejected'  => 0,
+				'cost'      => 0.0,
+			);
+		}
 
-		// Step 1: Collect source data.
-		$collector = new PRAutoBlogger_Source_Collector();
-		$collector->collect_from_all_sources();
+		// Generate article 1 in this process — always fits within time limit.
+		$first_idea = array_shift( $ideas );
+		$worker     = new PRAutoBlogger_Article_Worker( $cost_tracker );
+		$result     = $worker->generate( $first_idea );
 
-		// Step 2: Analyze collected data for patterns.
-		// Pass a generous target so the LLM returns enough diverse ideas for
-		// scoring to pick from — ask for 2× the daily target so dedup has room.
+		// Queue remaining articles as chained cron events.
+		if ( ! empty( $ideas ) ) {
+			$this->queue_remaining( $ideas, $cost_tracker->get_run_id(), $result );
+		} else {
+			// Single-article run — amortize research costs now (1 article = full cost).
+			PRAutoBlogger_Post_Assembler::amortize_research_costs( $cost_tracker->get_run_id() );
+			PRAutoBlogger_Pipeline_Status::log_summary( $result );
+			PRAutoBlogger_Run_State::mark_status( (string) $cost_tracker->get_run_id(), 'done' );
+		}
+
+		return $result;
+	}
+
+	/**
+	 * Process the next article from the persistent queue.
+	 *
+	 * Called by WP-Cron for articles 2, 3, …N. Pops one idea, generates
+	 * it, updates running totals, and chains the next job or finalizes.
+	 *
+	 * Side effects: API calls, DB writes, post creation, cron scheduling.
+	 */
+	public function process_next_queued_article(): void {
+		$queue = get_option( self::QUEUE_KEY );
+		if ( ! is_array( $queue ) || empty( $queue['ideas'] ) ) {
+			$this->finish_queue();
+			return;
+		}
+
+		$idea_data    = array_shift( $queue['ideas'] );
+		$idea         = new PRAutoBlogger_Article_Idea( $idea_data );
+		$cost_tracker = new PRAutoBlogger_Cost_Tracker();
+		$cost_tracker->set_run_id( $queue['run_id'] );
+
+		if ( $cost_tracker->is_budget_exceeded() ) {
+			PRAutoBlogger_Logger::instance()->warning(
+				'Budget limit reached. Aborting remaining queued articles.',
+				'pipeline'
+			);
+			PRAutoBlogger_Run_State::mark_status( (string) $queue['run_id'], 'failed' );
+			$this->finish_queue();
+			return;
+		}
+
+		// v0.18.0 — a run halted by the per-run cost governor (or failed by
+		// the reaper) must not dispatch its remaining queued articles.
+		$run_status = PRAutoBlogger_Run_State::get_status( $queue['run_id'] );
+		if ( in_array( $run_status, array( 'halted', 'failed' ), true ) ) {
+			PRAutoBlogger_Logger::instance()->warning(
+				sprintf( 'Run %s is %s. Aborting remaining queued articles.', $queue['run_id'], $run_status ),
+				'pipeline'
+			);
+			$this->finish_queue();
+			return;
+		}
+
+		// Persist the consumed queue BEFORE generating so the status poller
+		// cannot re-schedule a cron event for the same idea. Without this,
+		// the DB still holds the old queue during the ~90s generation window,
+		// and the poller's orphan-recovery logic duplicates the last article.
+		if ( ! empty( $queue['ideas'] ) ) {
+			update_option( self::QUEUE_KEY, $queue, false );
+		} else {
+			delete_option( self::QUEUE_KEY );
+		}
+
+		$worker         = new PRAutoBlogger_Article_Worker( $cost_tracker );
+		$article_result = $worker->generate( $idea );
+
+		// Merge into running totals.
+		$queue['results']['generated'] += $article_result['generated'];
+		$queue['results']['published'] += $article_result['published'];
+		$queue['results']['rejected']  += $article_result['rejected'];
+		$queue['results']['cost']      += $article_result['cost'];
+
+		if ( ! empty( $queue['ideas'] ) ) {
+			update_option( self::QUEUE_KEY, $queue, false );
+			PRAutoBlogger_Pipeline_Status::update_queue_progress( $queue );
+			$this->schedule_next();
+		} else {
+			// All articles done — amortize shared research costs across them.
+			PRAutoBlogger_Post_Assembler::amortize_research_costs( $queue['run_id'] );
+			PRAutoBlogger_Pipeline_Status::write_final( $queue['results'] );
+			delete_option( self::QUEUE_KEY );
+			PRAutoBlogger_Generation_Lock::release();
+			PRAutoBlogger_Pipeline_Status::log_summary( $queue['results'] );
+			PRAutoBlogger_Run_State::mark_status( (string) $queue['run_id'], 'done' );
+		}
+	}
+
+	// ── Private helpers ─────────────────────────────────────────────────
+
+	/**
+	 * Collect → Analyze → Score. Returns ranked ideas.
+	 *
+	 * @param PRAutoBlogger_Cost_Tracker $cost_tracker
+	 * @return PRAutoBlogger_Article_Idea[]
+	 */
+	private function orchestrate( PRAutoBlogger_Cost_Tracker $cost_tracker ): array {
+		$target = absint( get_option( 'prautoblogger_daily_article_target', 1 ) );
+
+		$run_id = (string) $cost_tracker->get_run_id();
+
+		$enabled       = json_decode( get_option( 'prautoblogger_enabled_sources', '["reddit"]' ), true );
+		$source_labels = is_array( $enabled ) ? implode( ', ', $enabled ) : 'reddit';
+		/* translators: %s is a comma-separated list of enabled source names, e.g. "reddit, llm_research". */
+		PRAutoBlogger_Pipeline_Status::broadcast( sprintf( __( 'Collecting sources from %s…', 'prautoblogger' ), $source_labels ) );
+		PRAutoBlogger_Run_Stage_State::start( $run_id, 'research', (string) PRAutoBlogger_Stage_Display_Map::default_agent_role( 'research' ) );
+		( new PRAutoBlogger_Source_Collector() )
+			->set_cost_tracker( $cost_tracker )
+			->collect_from_all_sources();
+		PRAutoBlogger_Run_Stage_State::done( $run_id, 'research' );
+
+		PRAutoBlogger_Pipeline_Status::broadcast( __( 'Analyzing topics and scoring…', 'prautoblogger' ) );
+		PRAutoBlogger_Run_Stage_State::start( $run_id, 'analysis', (string) PRAutoBlogger_Stage_Display_Map::default_agent_role( 'analysis' ) );
 		$llm      = new PRAutoBlogger_OpenRouter_Provider();
 		$analyzer = new PRAutoBlogger_Content_Analyzer( $llm, $cost_tracker );
-		$analysis = $analyzer->analyze_recent_data( max( $target_count * 2, 6 ) );
+		$analysis = $analyzer->analyze_recent_data( max( $target * 2, 6 ) );
+		PRAutoBlogger_Run_Stage_State::done( $run_id, 'analysis' );
 
-		// Step 3: Score and deduplicate ideas.
+		PRAutoBlogger_Pipeline_Status::broadcast( __( 'Selecting best topic…', 'prautoblogger' ) );
 		$scorer = new PRAutoBlogger_Idea_Scorer();
 		$scorer->set_skip_dedup( $this->skip_dedup );
-		$ideas  = $scorer->score_and_rank( $analysis, $target_count );
+		$ideas = $scorer->score_and_rank( $analysis, $target );
 
 		if ( empty( $ideas ) ) {
-			PRAutoBlogger_Logger::instance()->info( 'No viable article ideas found. Skipping generation.', 'pipeline' );
-			return [ 'generated' => 0, 'published' => 0, 'rejected' => 0, 'cost' => 0.0 ];
+			PRAutoBlogger_Logger::instance()->info(
+				'No viable article ideas found. Skipping generation.',
+				'pipeline'
+			);
 		}
 
-		// Step 4 & 5: Generate content and run through editor for each idea.
-		$generator    = new PRAutoBlogger_Content_Generator( $llm, $cost_tracker );
-		$editor       = new PRAutoBlogger_Chief_Editor( $llm, $cost_tracker );
-		$publisher    = new PRAutoBlogger_Publisher();
-		$auto_publish = in_array( get_option( 'prautoblogger_auto_publish', '0' ), [ '1', 'yes' ], true );
+		return $ideas;
+	}
 
-		$generated = 0;
-		$published = 0;
-		$rejected  = 0;
-
-		foreach ( $ideas as $idea ) {
-			// Re-check budget before each article — stop early if we hit the limit.
-			if ( $cost_tracker->is_budget_exceeded() ) {
-				PRAutoBlogger_Logger::instance()->warning( 'Budget limit reached during generation. Stopping early.', 'pipeline' );
-				break;
-			}
-
-			try {
-				$content = $generator->generate( $idea );
-				$generated++;
-
-				$review = $editor->review( $content, $idea );
-
-				if ( 'approved' === $review->get_verdict() || 'revised' === $review->get_verdict() ) {
-					// Null-coalesce: if editor returns 'revised' verdict but
-					// get_revised_content() is null (e.g. malformed LLM response),
-					// fall back to the original generated content.
-					$final_content = 'revised' === $review->get_verdict()
-						? ( $review->get_revised_content() ?? $content )
-						: $content;
-
-					if ( $auto_publish ) {
-						$publisher->publish( $final_content, $idea, $review, $cost_tracker->get_run_id() );
-						$published++;
-					} else {
-						// Auto-publish disabled: send to review queue as draft.
-						$publisher->save_as_draft( $final_content, $idea, $review, $cost_tracker->get_run_id() );
-					}
-				} else {
-					$publisher->save_as_draft( $content, $idea, $review, $cost_tracker->get_run_id() );
-					$rejected++;
-					PRAutoBlogger_Logger::instance()->info( 'Article rejected by editor: ' . $idea->get_topic(), 'pipeline' );
-				}
-			} catch ( \Exception $e ) {
-				PRAutoBlogger_Logger::instance()->error( 'Failed to generate article for topic "' . $idea->get_topic() . '": ' . $e->getMessage(), 'pipeline' );
-				// Continue with next idea — don't let one failure stop the batch.
-			}
-		}
-
-		$total_cost = $cost_tracker->get_current_run_cost();
-
-		PRAutoBlogger_Logger::instance()->info(
-			sprintf( 'Pipeline complete: %d generated, %d published, %d rejected. Cost: $%.4f', $generated, $published, $rejected, $total_cost ),
-			'pipeline'
+	/**
+	 * Store remaining ideas and schedule the next chained job.
+	 *
+	 * @param PRAutoBlogger_Article_Idea[] $ideas  Remaining ideas (2..N).
+	 * @param string                       $run_id Pipeline run UUID.
+	 * @param array                        $first  Results from article 1.
+	 */
+	private function queue_remaining( array $ideas, string $run_id, array $first ): void {
+		$serialized = array_map(
+			static fn( PRAutoBlogger_Article_Idea $i ) => $i->to_array(),
+			$ideas
 		);
 
-		return [
-			'generated' => $generated,
-			'published' => $published,
-			'rejected'  => $rejected,
-			'cost'      => $total_cost,
-		];
+		$queue = array(
+			'run_id'  => $run_id,
+			'ideas'   => $serialized,
+			'results' => $first,
+		);
+
+		update_option( self::QUEUE_KEY, $queue, false );
+		PRAutoBlogger_Pipeline_Status::update_queue_progress( $queue );
+		$this->schedule_next();
+
+		PRAutoBlogger_Logger::instance()->info(
+			sprintf( 'Article 1 done. Queued %d more as chained jobs.', count( $serialized ) ),
+			'pipeline'
+		);
+	}
+
+	/** Schedule the next chained cron event and fire it immediately. */
+	private function schedule_next(): void {
+		if ( ! wp_next_scheduled( self::CRON_ACTION ) ) {
+			wp_schedule_single_event( time(), self::CRON_ACTION );
+		}
+		spawn_cron();
+		wp_remote_post(
+			site_url( 'wp-cron.php?doing_wp_cron=' . sprintf( '%.22F', microtime( true ) ) ),
+			array(
+				'timeout'   => 0.01,
+				'blocking'  => false,
+				'sslverify' => false,
+			)
+		);
+	}
+
+	/** Clean up a stale or empty queue. */
+	private function finish_queue(): void {
+		$queue = get_option( self::QUEUE_KEY );
+		if ( is_array( $queue ) && isset( $queue['results'] ) ) {
+			PRAutoBlogger_Pipeline_Status::write_final( $queue['results'] );
+		}
+		delete_option( self::QUEUE_KEY );
+		PRAutoBlogger_Generation_Lock::release();
 	}
 }

includes/core/class-pipeline-status.php

@@ -0,0 +1,106 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Frontend status-transient + summary-log helpers for pipeline runs.
+ *
+ * What: The generation-status transient plumbing (stage broadcast, queue
+ *       progress, final result) and the pipeline summary log line,
+ *       extracted verbatim from Pipeline_Runner / Article_Worker in
+ *       v0.18.0 (300-line cap; the two classes carried duplicate
+ *       broadcast helpers). Pure presentation/state — no business logic.
+ * Who triggers it: Pipeline_Runner, Article_Worker.
+ * Dependencies: WordPress transients, PRAutoBlogger_Logger.
+ *
+ * @see core/class-pipeline-runner.php — Queue progress + final status writes.
+ * @see core/class-article-worker.php  — Per-stage broadcasts.
+ * @see class-executor.php             — Poller that reads this transient.
+ */
+class PRAutoBlogger_Pipeline_Status {
+
+	/** Transient key polled by the admin frontend. */
+	private const KEY = 'prautoblogger_generation_status';
+
+	/** Seconds the status transient stays readable. */
+	private const TTL = 600;
+
+	/**
+	 * Update the live stage text (only while a run is broadcasting).
+	 *
+	 * @param string $stage Human-readable stage description.
+	 * @return void
+	 */
+	public static function broadcast( string $stage ): void {
+		$current = get_transient( self::KEY );
+		if ( is_array( $current ) && 'running' === ( $current['status'] ?? '' ) ) {
+			$current['stage']        = $stage;
+			$current['last_updated'] = time();
+			set_transient( self::KEY, $current, self::TTL );
+		}
+	}
+
+	/**
+	 * Update queue progress ("Generating article X of Y…").
+	 *
+	 * @param array $queue Queue array with 'results' + 'ideas'.
+	 * @return void
+	 */
+	public static function update_queue_progress( array $queue ): void {
+		$done  = $queue['results']['generated'] + $queue['results']['rejected'];
+		$total = $done + count( $queue['ideas'] );
+
+		$current = get_transient( self::KEY );
+		set_transient(
+			self::KEY,
+			array(
+				'status'       => 'running',
+				/* translators: 1: current article number, 2: total articles. */
+				'stage'        => sprintf( __( 'Generating article %1$d of %2$d…', 'prautoblogger' ), $done + 1, $total ),
+				'started'      => is_array( $current ) ? ( $current['started'] ?? time() ) : time(),
+				'last_updated' => time(),
+			),
+			self::TTL
+		);
+	}
+
+	/**
+	 * Write the final "complete" status.
+	 *
+	 * @param array $r Result counters (generated/published/rejected/cost).
+	 * @return void
+	 */
+	public static function write_final( array $r ): void {
+		set_transient(
+			self::KEY,
+			array(
+				'status'    => 'complete',
+				'generated' => $r['generated'],
+				'published' => $r['published'],
+				'rejected'  => $r['rejected'],
+				'cost'      => $r['cost'],
+			),
+			self::TTL
+		);
+	}
+
+	/**
+	 * Log the pipeline summary line.
+	 *
+	 * @param array $r Result counters (generated/published/rejected/cost).
+	 * @return void
+	 */
+	public static function log_summary( array $r ): void {
+		PRAutoBlogger_Logger::instance()->info(
+			sprintf(
+				'Pipeline complete: %d generated, %d published, %d rejected. Cost: $%.4f',
+				$r['generated'],
+				$r['published'],
+				$r['rejected'],
+				$r['cost']
+			),
+			'pipeline'
+		);
+	}
+}

includes/core/class-post-assembler.php

@@ -0,0 +1,274 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Post-creation assembly helpers: taxonomy, log linking, images, content sanitization.
+ *
+ * What: After wp_insert_post, assigns categories/tags, links generation logs,
+ *       generates and attaches images, and sanitizes raw LLM content.
+ * Who calls it: PRAutoBlogger_Publisher::create_post().
+ * Dependencies: WordPress taxonomy/meta APIs, PRAutoBlogger_Image_Pipeline, PRAutoBlogger_Logger.
+ *
+ * @see core/class-publisher.php — Orchestrates post creation and calls these helpers.
+ * @see core/class-image-pipeline.php — Image generation for attach_generated_images.
+ */
+class PRAutoBlogger_Post_Assembler {
+
+	/**
+	 * Assign category and tags to a generated post.
+	 *
+	 * @param int                        $post_id Post ID.
+	 * @param PRAutoBlogger_Article_Idea $idea    Article idea with type and keywords.
+	 */
+	public static function assign_taxonomy_terms( int $post_id, PRAutoBlogger_Article_Idea $idea ): void {
+		$type_category_map = array(
+			'guide'      => 'Guides',
+			'solution'   => 'Solutions',
+			'comparison' => 'Comparisons',
+			'article'    => 'Articles',
+		);
+
+		$category_name = $type_category_map[ $idea->get_article_type() ] ?? 'Articles';
+		$category      = get_term_by( 'name', $category_name, 'category' );
+
+		if ( ! $category ) {
+			$result = wp_insert_term( $category_name, 'category' );
+			if ( ! is_wp_error( $result ) ) {
+				wp_set_post_categories( $post_id, array( $result['term_id'] ) );
+			}
+		} else {
+			wp_set_post_categories( $post_id, array( $category->term_id ) );
+		}
+
+		$keywords = $idea->get_target_keywords();
+		if ( ! empty( $keywords ) ) {
+			wp_set_post_tags( $post_id, $keywords, true );
+		}
+	}
+
+	/**
+	 * Link generation log entries to the newly created post.
+	 * Uses run_id for precise linking; falls back to timestamp for legacy data.
+	 *
+	 * @param int         $post_id Post ID.
+	 * @param string|null $run_id  Pipeline run identifier, or null for legacy fallback.
+	 */
+	public static function link_generation_logs( int $post_id, ?string $run_id = null ): void {
+		global $wpdb;
+		$table = $wpdb->prefix . 'prautoblogger_generation_log';
+
+		if ( null !== $run_id && '' !== $run_id ) {
+			// Exclude 'llm_research' stage — those shared costs are amortized
+			// across all articles after the full pipeline completes, not linked
+			// to a single post. See amortize_research_costs().
+			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+			$wpdb->query(
+				$wpdb->prepare(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+					"UPDATE {$table} SET post_id = %d WHERE post_id IS NULL AND run_id = %s AND stage != 'llm_research'",
+					$post_id,
+					$run_id
+				)
+			);
+		} else {
+			// Legacy fallback: timestamp-based linking for pre-migration log entries.
+			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+			$wpdb->query(
+				$wpdb->prepare(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+					"UPDATE {$table} SET post_id = %d WHERE post_id IS NULL AND created_at >= %s",
+					$post_id,
+					gmdate( 'Y-m-d H:i:s', time() - HOUR_IN_SECONDS )
+				)
+			);
+		}
+	}
+
+	/**
+	 * Amortize shared LLM research costs across all articles in a pipeline run.
+	 *
+	 * The research LLM call runs once per pipeline execution before any articles
+	 * are generated. Its cost is logged with the run_id but no post_id. After all
+	 * articles finish, this method divides the research cost evenly and inserts
+	 * one 'llm_research' row per article so the cost breakdown popover includes
+	 * the amortized research overhead.
+	 *
+	 * Side effects: database SELECT, INSERT, DELETE on generation_log.
+	 *
+	 * @param string|null $run_id Pipeline run UUID. Null or empty is a no-op.
+	 */
+	public static function amortize_research_costs( ?string $run_id ): void {
+		if ( null === $run_id || '' === $run_id ) {
+			return;
+		}
+
+		global $wpdb;
+		$table = $wpdb->prefix . 'prautoblogger_generation_log';
+
+		// Find the unlinked research cost row for this run.
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$research_row = $wpdb->get_row(
+			$wpdb->prepare( // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+				"SELECT id, estimated_cost, provider, model, prompt_tokens, completion_tokens
+				FROM {$table}
+				WHERE run_id = %s AND stage = 'llm_research' AND post_id IS NULL
+				LIMIT 1",
+				$run_id
+			)
+		);
+
+		if ( ! $research_row || (float) $research_row->estimated_cost <= 0.0 ) {
+			return; // No research cost to amortize (LLM research not enabled or free).
+		}
+
+		// Count distinct articles produced in this run.
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$post_ids = $wpdb->get_col(
+			$wpdb->prepare(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+				"SELECT DISTINCT post_id FROM {$table} WHERE run_id = %s AND post_id IS NOT NULL",
+				$run_id
+			)
+		);
+
+		$post_count = count( $post_ids );
+		if ( $post_count < 1 ) {
+			return; // No articles produced — nothing to amortize into.
+		}
+
+		$total_cost       = (float) $research_row->estimated_cost;
+		$amortized_cost   = $total_cost / $post_count;
+		$total_prompt     = (int) $research_row->prompt_tokens;
+		$total_completion = (int) $research_row->completion_tokens;
+		$amortized_prompt = (int) round( $total_prompt / $post_count );
+		$amortized_compl  = (int) round( $total_completion / $post_count );
+
+		// Insert one amortized research row per article.
+		foreach ( $post_ids as $post_id ) {
+			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+			$wpdb->insert(
+				$table,
+				array(
+					'post_id'           => (int) $post_id,
+					'run_id'            => $run_id,
+					'stage'             => 'llm_research',
+					'provider'          => $research_row->provider,
+					'model'             => $research_row->model,
+					'prompt_tokens'     => $amortized_prompt,
+					'completion_tokens' => $amortized_compl,
+					'estimated_cost'    => $amortized_cost,
+					'response_status'   => 'success',
+					'error_message'     => '',
+					'created_at'        => current_time( 'mysql' ),
+				)
+			);
+		}
+
+		// Remove the original unlinked row — it's been replaced by per-article rows.
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$wpdb->delete( $table, array( 'id' => (int) $research_row->id ) );
+
+		PRAutoBlogger_Logger::instance()->info(
+			sprintf(
+				'Amortized LLM research cost $%.4f across %d articles ($%.4f each).',
+				$total_cost,
+				$post_count,
+				$amortized_cost
+			),
+			'cost-tracker'
+		);
+	}
+
+	/**
+	 * Strip common LLM output artifacts from generated content.
+	 * Removes markdown fences, HTML document wrappers, stray head-level tags.
+	 *
+	 * @param string $content Raw LLM output.
+	 * @return string Cleaned HTML suitable for post_content.
+	 */
+	public static function sanitize_llm_content( string $content ): string {
+		$content = trim( $content );
+
+		// Strip markdown code fences: ```html ... ``` or ``` ... ```
+		if ( preg_match( '/^```(?:\w+)?\s*\n(.*?)```\s*$/s', $content, $matches ) ) {
+			$content = trim( $matches[1] );
+		}
+
+		// Strip full HTML document wrappers — extract only <body> inner content.
+		if ( preg_match( '/<body[^>]*>(.*)<\/body>/is', $content, $matches ) ) {
+			$content = trim( $matches[1] );
+		}
+
+		// Remove stray document-level tags.
+		$content = preg_replace( '/<\/?(html|head|body|meta|title|!DOCTYPE)[^>]*>/i', '', $content );
+		$content = preg_replace( '/<link\s[^>]*>/i', '', $content );
+		$content = preg_replace( '/<style[^>]*>.*?<\/style>/is', '', $content );
+		$content = preg_replace( '/\n{3,}/', "\n\n", $content );
+
+		return trim( $content );
+	}
+
+	/**
+	 * Get the default author ID for generated posts.
+	 *
+	 * @return int WordPress user ID.
+	 */
+	public static function get_default_author_id(): int {
+		$author_id = absint( get_option( 'prautoblogger_default_author', 0 ) );
+		if ( $author_id > 0 ) {
+			return $author_id;
+		}
+
+		$admins = get_users(
+			array(
+				'role'   => 'administrator',
+				'number' => 1,
+				'fields' => 'ID',
+			)
+		);
+		return ! empty( $admins ) ? (int) $admins[0] : 1;
+	}
+
+	/**
+	 * Generate and attach images to a published post.
+	 * Non-blocking — logs errors but doesn't re-throw since the post is already created.
+	 *
+	 * @param int                        $post_id      Post ID.
+	 * @param PRAutoBlogger_Article_Idea $idea         Article idea (contains source IDs).
+	 * @param array                      $post_data    Post data array (for article content).
+	 * @param ?PRAutoBlogger_Cost_Tracker $cost_tracker Optional cost tracker for image generation cost logging.
+	 */
+	public static function attach_generated_images( int $post_id, PRAutoBlogger_Article_Idea $idea, array $post_data, ?PRAutoBlogger_Cost_Tracker $cost_tracker = null ): void {
+		// Fetch the original Reddit source data for Image B's source-driven prompt.
+		// The idea's source_ids point to rows in the source_data table collected
+		// during the pipeline's collection step.
+		$source_data = ( new PRAutoBlogger_Source_Collector() )->get_source_data_for_image( $idea->get_source_ids() );
+
+		try {
+			// The pipeline now sets featured image and Image B meta
+			// internally, immediately after each image generates. This
+			// ensures attachment persists even if the process times out
+			// before this method returns.
+			$result = ( new PRAutoBlogger_Image_Pipeline( null, $cost_tracker ) )->generate_and_attach_images( $post_id, $post_data, $source_data );
+
+			if ( ! empty( $result['errors'] ) ) {
+				foreach ( $result['errors'] as $error ) {
+					PRAutoBlogger_Logger::instance()->warning( 'Image warning for post ' . $post_id . ': ' . $error, 'publisher' );
+				}
+			}
+
+			if ( $result['cost_usd'] > 0.0 ) {
+				PRAutoBlogger_Logger::instance()->info(
+					sprintf( 'Image generation cost: $%.4f for post %d', $result['cost_usd'], $post_id ),
+					'publisher'
+				);
+			}
+		} catch ( \Throwable $e ) {
+			// Catch \Throwable (not just \Exception) so PHP 8 TypeError/Error
+			// doesn't kill the process silently without any log entry.
+			PRAutoBlogger_Logger::instance()->error(
+				sprintf( 'Image pipeline %s for post %d: %s', get_class( $e ), $post_id, $e->getMessage() ),
+				'publisher'
+			);
+		}
+	}
+}

includes/core/class-prompt-defaults-editorial.php

@@ -0,0 +1,147 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Canonical default bodies for the editor, research, and image registry keys.
+ *
+ * What: Companion to PRAutoBlogger_Prompt_Defaults (split for the 300-line
+ *       cap, mirroring the settings-fields/-extended split). Holds the
+ *       chief-editor and LLM-research prompt copy extracted verbatim from
+ *       their classes, and references the two image keys that form the
+ *       image-composer PR seam: `image.rewriter_system` (the illustration
+ *       rewriter prompt) and `image.style_template` (the Style Template,
+ *       ARCHITECTURE #20). The composer PR CONSUMES these keys — it must
+ *       not grow its own prompt storage, and the key names are frozen on
+ *       the pipeline-v2-phase1 convo thread.
+ * Who triggers it: PRAutoBlogger_Prompt_Registry (render fallback + seed),
+ *       PRAutoBlogger_Activator (seed migration).
+ * Dependencies: PRAutoBlogger_Image_Prompt_Builder::REWRITER_SYSTEM_PROMPT,
+ *       PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_TEMPLATE (referenced, not duplicated).
+ *
+ * @see core/class-prompt-defaults.php   — Content + analysis keys.
+ * @see core/class-prompt-registry.php   — Render/seed consumer.
+ * @see core/class-chief-editor.php      — Computes the editor token values.
+ * @see providers/class-llm-research-provider.php — research.system consumer.
+ */
+class PRAutoBlogger_Prompt_Defaults_Editorial {
+
+	/**
+	 * Chief-editor system prompt. instructions_block carries its own
+	 * leading newline + trailing newline when non-empty ('' when absent),
+	 * matching the historical concatenation byte-for-byte.
+	 */
+	public const EDITOR_SYSTEM = <<<'TPL'
+You are a senior blog editor{{ niche_clause }}. Review article drafts before publication.
+
+Evaluate on: QUALITY, ACCURACY, SEO, COMPLETENESS, READABILITY.
+Respond with JSON: {
+  "verdict": "approved" | "revised" | "rejected",
+  "quality_score": 0.0-1.0,
+  "seo_score": 0.0-1.0,
+  "issues": ["issue1", "issue2"],
+  "notes": "Editorial notes",
+  "revised_content": "Full revised HTML if revised, null otherwise"
+}
+
+Rules:
+- APPROVE if quality_score >= 0.7 and seo_score >= 0.6
+- REVISE if fixable issues exist — provide full revised HTML
+- REJECT if fundamentally flawed
+- Preserve formatting, links, lists when revising
+{{ instructions_block }}
+TPL;
+
+	/** Chief-editor review user prompt. */
+	public const EDITOR_REVIEW = <<<'TPL'
+Review this article draft:
+
+BRIEF: Title: {{ title }} | Topic: {{ topic }} | Type: {{ article_type }}
+KEY POINTS: {{ key_points }}
+TARGET KEYWORDS: {{ keywords }}
+
+CONTENT:
+{{ content }}
+TPL;
+
+	/**
+	 * LLM deep-research system prompt (fully static). The user-side
+	 * research brief stays the `prautoblogger_research_prompt` SETTING —
+	 * it is site configuration, not pipeline copy.
+	 */
+	public const RESEARCH_SYSTEM = <<<'TPL'
+You are a deep research analyst specializing in emerging trends, scientific developments, and community knowledge in niche health and biohacking domains. Your task is to identify substantive, actionable findings.
+
+Using your training knowledge, scan across:
+- Recent scientific literature and research directions
+- Active community discussions, debates, and evolving consensus
+- Emerging products, protocols, and methodologies gaining traction
+- Common questions, misconceptions, and points of confusion
+- Regulatory changes, safety concerns, and legal shifts
+- Gaps between what practitioners want to know and what content exists
+
+Your findings must be:
+1. SUBSTANTIVE — 2-3 paragraphs of detailed analysis per finding, not a headline
+2. ACTIONABLE — practical enough to seed a full article
+3. REALISTIC — grounded in what is actually discussed or researched; do NOT invent citations
+4. TIMELY — reflect current knowledge, recent shifts, or emerging questions
+
+Respond with valid JSON only (no preamble, no markdown fences):
+{"findings": [{"title": "string", "content": "string (2-3 paragraphs)", "relevance_score": 0-100, "category": "question|trend|comparison|guide|misconception|safety"}]}
+
+Generate 8-12 findings. Prioritize depth over breadth. Avoid generic or surface-level topics.
+TPL;
+
+	/**
+	 * Registry definitions for the editor / research / image keys.
+	 *
+	 * The image bodies are referenced from their existing single sources
+	 * of truth rather than duplicated. Note the image keys seed the
+	 * registry for the composer PR; the v0.16.0 option-override chain
+	 * (`prautoblogger_image_prompt_instructions`,
+	 * `prautoblogger_image_style_template`) is unchanged in Phase 1.
+	 *
+	 * @return array<string, array{body: string, model_option: ?string, params: array<string, mixed>}>
+	 */
+	public static function defs(): array {
+		return array(
+			'editor.system'         => array(
+				'body'         => self::EDITOR_SYSTEM,
+				'model_option' => 'prautoblogger_editor_model',
+				'params'       => array(
+					'temperature'     => 0.3,
+					'max_tokens'      => 5000,
+					'response_format' => array( 'type' => 'json_object' ),
+				),
+			),
+			'editor.review'         => array(
+				'body'         => self::EDITOR_REVIEW,
+				'model_option' => 'prautoblogger_editor_model',
+				'params'       => array(),
+			),
+			'research.system'       => array(
+				'body'         => self::RESEARCH_SYSTEM,
+				'model_option' => 'prautoblogger_research_model',
+				'params'       => array(
+					'temperature'     => 0.7,
+					'max_tokens'      => 8000,
+					'response_format' => array( 'type' => 'json_object' ),
+				),
+			),
+			'image.rewriter_system' => array(
+				'body'         => PRAutoBlogger_Image_Prompt_Builder::REWRITER_SYSTEM_PROMPT,
+				'model_option' => 'prautoblogger_analysis_model',
+				'params'       => array(
+					'temperature' => 0.7,
+					'max_tokens'  => 180,
+				),
+			),
+			'image.style_template'  => array(
+				'body'         => PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_TEMPLATE,
+				'model_option' => 'prautoblogger_image_model',
+				'params'       => array(),
+			),
+		);
+	}
+}

includes/core/class-prompt-defaults.php

@@ -0,0 +1,210 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Canonical default bodies for the content + analysis prompt-registry keys.
+ *
+ * What: The v0.16.0 hardcoded prompt texts, extracted verbatim into
+ *       `{{ token }}` templates. These constants are the single source of
+ *       truth twice over: the v1.2.0 migration seeds them into
+ *       `wp_prautoblogger_prompts` as version 1, AND the registry falls
+ *       back to them whenever the table is missing/empty — so a
+ *       half-migrated site renders byte-identical prompts and never
+ *       fatals. Versions in the table are immutable; to change a prompt,
+ *       create a new version (see Prompt_Registry).
+ * Who triggers it: PRAutoBlogger_Prompt_Registry (render fallback + seed),
+ *       PRAutoBlogger_Activator (seed migration).
+ * Dependencies: none — pure constants.
+ *
+ * @see core/class-prompt-registry.php           — Render/seed consumer.
+ * @see core/class-prompt-defaults-editorial.php — Editor/research/image keys.
+ * @see core/class-content-prompts.php           — Computes the token values.
+ * @see core/class-analysis-prompts.php          — Computes the token values.
+ */
+class PRAutoBlogger_Prompt_Defaults {
+
+	/**
+	 * System prompt shared across all writing stages. The mandatory style
+	 * guide block and the linking rules stay code-side (they are data
+	 * injection, not prompt copy) and are appended after this body.
+	 */
+	public const CONTENT_SYSTEM = 'You are an expert blog writer{{ niche_clause }}. Write well-researched, engaging, SEO-friendly content. Use a {{ tone }} tone. Output HTML content only — no markdown, no code fences, no commentary.';
+
+	/** Single-pass writer prompt (Economy tier — logs stage 'draft'). */
+	public const CONTENT_SINGLE_PASS = <<<'TPL'
+Write a complete blog post in HTML format.
+
+Title: {{ title }}
+Topic: {{ topic }}
+Type: {{ article_type }}
+
+Key points:
+- {{ key_points }}
+
+Keywords: {{ keywords }}
+
+Requirements:
+- {{ min_words }}-{{ max_words }} words
+- Proper HTML (h2, h3, p, ul/li)
+- Engaging intro, strong conclusion with CTA
+- Do NOT include the title or <html>/<body> tags
+- Output HTML only, no markdown or commentary
+- Follow EVERY formatting and structural requirement from your system prompt style guide
+TPL;
+
+	/** Multi-step stage 1: outline. */
+	public const CONTENT_OUTLINE = <<<'TPL'
+Create a detailed outline for a blog post titled: "{{ title }}"
+
+Topic: {{ topic }}
+Article type: {{ article_type }}
+
+Key points to cover:
+{{ key_points }}
+
+Target keywords: {{ keywords }}
+
+The outline should have 4-6 main sections with bullet points under each. Include an introduction hook and a conclusion with a call to action. Word count target: {{ min_words }}-{{ max_words }} words.
+
+Plan the structure to satisfy EVERY requirement in your system prompt style guide.
+TPL;
+
+	/** Multi-step stage 2: full draft from outline. */
+	public const CONTENT_DRAFT = <<<'TPL'
+Using this outline, write the full blog post in HTML format.
+
+OUTLINE:
+{{ outline }}
+
+Requirements:
+- Write in a {{ tone }} tone
+- Target {{ min_words }}-{{ max_words }} words
+- Use proper HTML headings (h2, h3), paragraphs, and lists
+- Include an engaging introduction and strong conclusion
+- Naturally incorporate these keywords: {{ keywords }}
+- Do NOT include the title in the HTML (it will be set separately)
+- Do NOT wrap in <html>, <head>, or <body> tags — just the article content
+- Follow EVERY formatting and structural requirement from your system prompt style guide
+TPL;
+
+	/** Multi-step stage 3: polish (canonical name — ARCHITECTURE once said 'edit'). */
+	public const CONTENT_POLISH = <<<'TPL'
+Review and polish this blog post draft. Improve:
+1. Flow and readability
+2. SEO optimization (headings, keyword placement)
+3. Engagement (hooks, transitions, call-to-action)
+4. Accuracy and clarity
+5. Remove any filler or redundant sentences
+
+IMPORTANT: Preserve all bullet points, numbered lists, hyperlinks, and structural elements from the draft. Do NOT flatten lists into prose or remove links. Ensure every requirement from your system prompt style guide is satisfied in the final output.
+
+Return the polished HTML content only. Do not add commentary.
+
+DRAFT:
+{{ draft }}
+TPL;
+
+	/**
+	 * Analyzer system prompt. The *_block tokens carry their own trailing
+	 * separators when non-empty ('' when absent) so the rendered output is
+	 * byte-identical to the historical concatenation.
+	 */
+	public const ANALYSIS_SYSTEM = <<<'TPL'
+You are a content strategist analyzing social media discussions to find article ideas for a blog{{ niche_clause }}.
+
+IMPORTANT: You must identify exactly {{ target_count }} DISTINCT article ideas. Each idea must cover a substantially different topic — no two ideas should overlap in their main subject. Aim for diversity across these categories:
+1. QUESTIONS: Recurring questions people ask ("How do I...", "What is...", "Is it safe to...")
+2. COMPLAINTS: Pain points, frustrations, or problems people report
+3. COMPARISONS: Product/method comparisons people discuss ("X vs Y", "Which is better")
+4. NEWS: Recent developments, rule changes, or trends people are discussing
+5. GUIDES: How-to topics, best practices, or educational content people need
+
+Spread your {{ target_count }} ideas across multiple categories. Be specific — "peptide dosing for BPC-157" is better than "peptide information". Each idea should be narrow enough to be a single focused blog post.
+
+For each idea, provide:
+- type: 'question', 'complaint', 'comparison', 'news', or 'guide'
+- topic: A clear, specific, narrow topic description
+- summary: 1-2 sentence summary of why this topic matters
+- frequency: How many of the provided posts relate to this topic
+- relevance_score: 0.0 to 1.0 indicating how relevant and article-worthy this is
+- suggested_title: A compelling, unique blog post title
+- key_points: Array of 3-5 key points the article should cover
+- target_keywords: Array of SEO keywords for this topic
+
+{{ performance_block }}{{ recent_articles_block }}{{ instructions_block }}Respond with valid JSON containing exactly {{ target_count }} patterns:
+{"patterns": [{"type": "...", "topic": "...", "summary": "...", "frequency": N, "relevance_score": 0.X, "suggested_title": "...", "key_points": [...], "target_keywords": [...]}]}
+TPL;
+
+	/** Analyzer user prompt wrapping the source-data summary. */
+	public const ANALYSIS_USER = <<<'TPL'
+Here are the recent social media posts and comments to analyze. Find {{ target_count }} distinct, diverse article ideas from this data:
+
+{{ summary }}
+TPL;
+
+	/**
+	 * Registry definitions for the content + analysis keys.
+	 *
+	 * Each entry: body (the v1 template), model_option (the wp_option that
+	 * selects the model at call time — informational in Phase 1) and params
+	 * (the call-time LLM parameters, snapshotted for audit comparability).
+	 *
+	 * @return array<string, array{body: string, model_option: ?string, params: array<string, mixed>}>
+	 */
+	public static function defs(): array {
+		return array(
+			'content.system'      => array(
+				'body'         => self::CONTENT_SYSTEM,
+				'model_option' => 'prautoblogger_writing_model',
+				'params'       => array(),
+			),
+			'content.single_pass' => array(
+				'body'         => self::CONTENT_SINGLE_PASS,
+				'model_option' => 'prautoblogger_writing_model',
+				'params'       => array(
+					'temperature' => 0.7,
+					'max_tokens'  => 4000,
+				),
+			),
+			'content.outline'     => array(
+				'body'         => self::CONTENT_OUTLINE,
+				'model_option' => 'prautoblogger_writing_model',
+				'params'       => array(
+					'temperature' => 0.5,
+					'max_tokens'  => 1500,
+				),
+			),
+			'content.draft'       => array(
+				'body'         => self::CONTENT_DRAFT,
+				'model_option' => 'prautoblogger_writing_model',
+				'params'       => array(
+					'temperature' => 0.7,
+					'max_tokens'  => 4000,
+				),
+			),
+			'content.polish'      => array(
+				'body'         => self::CONTENT_POLISH,
+				'model_option' => 'prautoblogger_writing_model',
+				'params'       => array(
+					'temperature' => 0.4,
+					'max_tokens'  => 4000,
+				),
+			),
+			'analysis.system'     => array(
+				'body'         => self::ANALYSIS_SYSTEM,
+				'model_option' => 'prautoblogger_analysis_model',
+				'params'       => array(
+					'temperature' => 0.5,
+					'max_tokens'  => 8000,
+				),
+			),
+			'analysis.user'       => array(
+				'body'         => self::ANALYSIS_USER,
+				'model_option' => 'prautoblogger_analysis_model',
+				'params'       => array(),
+			),
+		);
+	}
+}

includes/core/class-prompt-registry-writer.php

@@ -0,0 +1,143 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Write side of the versioned prompt registry: create / activate / seed.
+ *
+ * What: Companion to PRAutoBlogger_Prompt_Registry (split for the 300-line
+ *       cap). Owns every mutation of `wp_prautoblogger_prompts` and
+ *       enforces the immutability rule: a stored body is NEVER updated —
+ *       a change is a new (prompt_key, version) row, and `activate()`
+ *       flips the single active flag per key. `seed_v1()` writes the
+ *       canonical v0.16.0 texts as version 1 (idempotent — keys that
+ *       already have rows keep their history). This is the API surface
+ *       the Phase-2 in-admin Prompts editor will call; Phase 1 ships no UI.
+ * Who triggers it: PRAutoBlogger_Activator (seed migration on db 1.2.0),
+ *       Phase-2 admin (create/activate), WP-CLI (future).
+ * Dependencies: WordPress $wpdb, PRAutoBlogger_Prompt_Registry (table name,
+ *       availability probe, defs, cache flush).
+ *
+ * @see core/class-prompt-registry.php — Read side (render, pins, fallback).
+ * @see class-activator.php            — Calls seed_v1() once, flag-gated.
+ */
+class PRAutoBlogger_Prompt_Registry_Writer {
+
+	/**
+	 * All versions of a key, newest first (Phase-2 list/diff support).
+	 *
+	 * @param string $key Registry key.
+	 * @return array<int, array<string, mixed>>
+	 */
+	public static function list_versions( string $key ): array {
+		if ( ! PRAutoBlogger_Prompt_Registry::is_available() ) {
+			return array();
+		}
+		global $wpdb;
+		$table = PRAutoBlogger_Prompt_Registry::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$rows = $wpdb->get_results(
+			$wpdb->prepare( "SELECT * FROM {$table} WHERE prompt_key = %s ORDER BY version DESC", $key ),
+			ARRAY_A
+		);
+		return is_array( $rows ) ? $rows : array();
+	}
+
+	/**
+	 * Create a NEW immutable version of a key and (optionally) activate it.
+	 * Never mutates an existing row's body — that is the whole point.
+	 *
+	 * @param string                    $key      Registry key.
+	 * @param string                    $body     Template body.
+	 * @param string|null               $model    Optional model hint.
+	 * @param array<string, mixed>|null $params   Optional params snapshot.
+	 * @param string                    $author   Who created it (seed tag, login, agent).
+	 * @param bool                      $activate Flip active to this version (default true).
+	 * @return int New version number, or 0 on failure / table unavailable.
+	 */
+	public static function create_version( string $key, string $body, ?string $model, ?array $params, string $author, bool $activate = true ): int {
+		if ( ! PRAutoBlogger_Prompt_Registry::is_available() ) {
+			return 0;
+		}
+		global $wpdb;
+		$table = PRAutoBlogger_Prompt_Registry::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$max  = (int) $wpdb->get_var(
+			$wpdb->prepare( "SELECT MAX(version) FROM {$table} WHERE prompt_key = %s", $key )
+		);
+		$next = $max + 1;
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$ok = $wpdb->insert(
+			$table,
+			array(
+				'prompt_key'  => $key,
+				'version'     => $next,
+				'body'        => $body,
+				'model'       => $model,
+				'params_json' => null !== $params ? wp_json_encode( $params ) : null,
+				'author'      => $author,
+				'created_at'  => current_time( 'mysql' ),
+				'active'      => 0,
+			)
+		);
+		if ( false === $ok ) {
+			return 0;
+		}
+		if ( $activate ) {
+			self::activate( $key, $next );
+		}
+		return $next;
+	}
+
+	/**
+	 * Make one version the single active version of its key.
+	 *
+	 * @param string $key     Registry key.
+	 * @param int    $version Version to activate.
+	 * @return bool True when the version is now active.
+	 */
+	public static function activate( string $key, int $version ): bool {
+		if ( ! PRAutoBlogger_Prompt_Registry::is_available() ) {
+			return false;
+		}
+		global $wpdb;
+		$table = PRAutoBlogger_Prompt_Registry::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$wpdb->query( $wpdb->prepare( "UPDATE {$table} SET active = 0 WHERE prompt_key = %s", $key ) );
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$updated = $wpdb->query(
+			$wpdb->prepare( "UPDATE {$table} SET active = 1 WHERE prompt_key = %s AND version = %d", $key, $version )
+		);
+		PRAutoBlogger_Prompt_Registry::flush_cache();
+		return 1 === (int) $updated;
+	}
+
+	/**
+	 * Seed every registry key with its canonical v1 body. Idempotent: keys
+	 * that already have rows are left untouched (their history is theirs).
+	 *
+	 * Side effects: up to one INSERT + two UPDATEs per missing key.
+	 *
+	 * @param string $author Audit tag for the seed rows (e.g. 'seed:v0.18.0').
+	 * @return int Number of keys seeded.
+	 */
+	public static function seed_v1( string $author = 'seed:v0.18.0' ): int {
+		if ( ! PRAutoBlogger_Prompt_Registry::is_available() ) {
+			return 0;
+		}
+		$seeded = 0;
+		foreach ( PRAutoBlogger_Prompt_Registry::defs() as $key => $def ) {
+			if ( ! empty( self::list_versions( $key ) ) ) {
+				continue;
+			}
+			$model   = null !== $def['model_option'] ? (string) get_option( $def['model_option'], '' ) : null;
+			$version = self::create_version( $key, $def['body'], '' !== (string) $model ? $model : null, $def['params'], $author, true );
+			if ( $version > 0 ) {
+				++$seeded;
+			}
+		}
+		PRAutoBlogger_Prompt_Registry::flush_cache();
+		return $seeded;
+	}
+}

includes/core/class-prompt-registry.php

@@ -0,0 +1,214 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Versioned prompt registry — immutable versions, one active row per key.
+ *
+ * What: Read/write API over `wp_prautoblogger_prompts`. Rendering resolves
+ *       the ACTIVE body for a key and fills `{{ token }}` placeholders;
+ *       when the table is missing or has no row for the key (half-migrated
+ *       site, failed seed), it falls back to the canonical defaults the
+ *       seed itself uses — byte-identical output, no fatals (self-healing).
+ *       Versions are IMMUTABLE: there is no update path for a stored body;
+ *       changes create a new (prompt_key, version) row and flip `active`
+ *       (write side lives in PRAutoBlogger_Prompt_Registry_Writer).
+ *       Runs pin the active version of every key at start (stored on the
+ *       runs row) so generation_log rows can be stamped with the exact
+ *       prompt_version they rendered with. No admin UI in Phase 1 — the
+ *       list/activate/create API is what the Phase-2 Prompts screen needs.
+ * Who triggers it: Content_Prompts / Analysis_Prompts / Chief_Editor /
+ *       LLM_Research_Provider (render), Cost_Tracker (pins_for_run),
+ *       Activator (seed_v1), Cost_Tracker::set_run_id (pin_for_run).
+ * Dependencies: WordPress $wpdb, Prompt_Defaults(+Editorial), wp_json_encode.
+ *
+ * @see core/class-prompt-defaults.php           — Canonical v1 bodies (seed + fallback).
+ * @see core/class-prompt-defaults-editorial.php — Editor/research/image bodies.
+ * @see core/class-run-state.php                 — Owns the runs row the pins live on.
+ * @see ARCHITECTURE.md #21                      — Design rationale.
+ */
+class PRAutoBlogger_Prompt_Registry {
+
+	/** @var array<string, ?array<string, mixed>> Per-request active-row cache. */
+	private static array $active_cache = array();
+
+	/** @var array<string, array<string, int>> Per-request run-pins cache. */
+	private static array $pins_cache = array();
+
+	/** @var bool|null Per-request "table exists" probe result. */
+	private static ?bool $table_ok = null;
+
+	/** Fully-qualified prompts table name (shared with Prompt_Registry_Writer). */
+	public static function table_name(): string {
+		global $wpdb;
+		return $wpdb->prefix . 'prautoblogger_prompts';
+	}
+
+	/**
+	 * Whether the prompts table exists and is queryable. Cached per request;
+	 * never throws — any failure reads as "not available" and every consumer
+	 * falls back to the in-code defaults.
+	 *
+	 * @return bool
+	 */
+	public static function is_available(): bool {
+		if ( null !== self::$table_ok ) {
+			return self::$table_ok;
+		}
+		global $wpdb;
+		if ( null === $wpdb ) {
+			return false; // Not cached: $wpdb may appear later in boot.
+		}
+		$table = self::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$found          = $wpdb->get_var( $wpdb->prepare( 'SHOW TABLES LIKE %s', $table ) );
+		self::$table_ok = ( $found === $table );
+		return self::$table_ok;
+	}
+
+	/**
+	 * All registry definitions (content + analysis + editor + research + image).
+	 *
+	 * @return array<string, array{body: string, model_option: ?string, params: array<string, mixed>}>
+	 */
+	public static function defs(): array {
+		return array_merge(
+			PRAutoBlogger_Prompt_Defaults::defs(),
+			PRAutoBlogger_Prompt_Defaults_Editorial::defs()
+		);
+	}
+
+	/**
+	 * Canonical in-code default body for a key (the same text seeded as v1).
+	 *
+	 * @param string $key Registry key.
+	 * @return string|null Body template, or null for unknown keys.
+	 */
+	public static function default_body( string $key ): ?string {
+		$defs = self::defs();
+		return isset( $defs[ $key ] ) ? $defs[ $key ]['body'] : null;
+	}
+
+	/**
+	 * Active row for a key, or null when none / table unavailable.
+	 *
+	 * @param string $key Registry key.
+	 * @return array<string, mixed>|null Row with prompt_key, version, body, model, params_json, author, created_at, active.
+	 */
+	public static function get_active( string $key ): ?array {
+		if ( array_key_exists( $key, self::$active_cache ) ) {
+			return self::$active_cache[ $key ];
+		}
+		$row = null;
+		if ( self::is_available() ) {
+			global $wpdb;
+			$table = self::table_name();
+			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+			$row = $wpdb->get_row(
+				$wpdb->prepare(
+					"SELECT * FROM {$table} WHERE prompt_key = %s AND active = 1 ORDER BY version DESC LIMIT 1",
+					$key
+				),
+				ARRAY_A
+			);
+			$row = is_array( $row ) ? $row : null;
+		}
+		self::$active_cache[ $key ] = $row;
+		return $row;
+	}
+
+	/**
+	 * Render a prompt: active body for the key (fallback: canonical default),
+	 * with `{{ token }}` placeholders substituted.
+	 *
+	 * @param string                $key    Registry key (e.g. 'content.single_pass').
+	 * @param array<string, string> $tokens Token name => replacement value.
+	 * @return string Rendered prompt ('' only if the key is unknown AND absent).
+	 */
+	public static function render( string $key, array $tokens = array() ): string {
+		$active = self::get_active( $key );
+		$body   = null !== $active ? (string) $active['body'] : (string) self::default_body( $key );
+		return self::fill( $body, $tokens );
+	}
+
+	/**
+	 * Substitute `{{ token }}` placeholders in a template body.
+	 *
+	 * @param string                $body   Template body.
+	 * @param array<string, string> $tokens Token name => replacement value.
+	 * @return string
+	 */
+	public static function fill( string $body, array $tokens ): string {
+		foreach ( $tokens as $name => $value ) {
+			$body = str_replace( '{{ ' . $name . ' }}', (string) $value, $body );
+		}
+		return $body;
+	}
+
+	/**
+	 * Map of prompt_key => active version for every key present in the table.
+	 *
+	 * @return array<string, int>
+	 */
+	public static function active_versions(): array {
+		if ( ! self::is_available() ) {
+			return array();
+		}
+		global $wpdb;
+		$table = self::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$rows = $wpdb->get_results( "SELECT prompt_key, version FROM {$table} WHERE active = 1", ARRAY_A );
+		$map  = array();
+		foreach ( ( is_array( $rows ) ? $rows : array() ) as $row ) {
+			$map[ (string) $row['prompt_key'] ] = (int) $row['version'];
+		}
+		return $map;
+	}
+
+	/**
+	 * Pin the current active versions onto a run's row (once, at run start).
+	 * No-ops when the runs row already carries pins (resume keeps the
+	 * versions the run started with) or when tables are unavailable.
+	 *
+	 * @param string $run_id Pipeline run UUID.
+	 * @return void
+	 */
+	public static function pin_for_run( string $run_id ): void {
+		if ( '' === $run_id || ! self::is_available() ) {
+			return;
+		}
+		$pins = self::active_versions();
+		if ( empty( $pins ) ) {
+			return;
+		}
+		PRAutoBlogger_Run_State::set_pins_if_absent( $run_id, $pins );
+		unset( self::$pins_cache[ $run_id ] );
+	}
+
+	/**
+	 * The pinned prompt versions for a run (cached per request). Empty when
+	 * the run has no pins (pre-1.2.0 rows, standalone calls, missing table).
+	 *
+	 * @param string|null $run_id Pipeline run UUID, or null.
+	 * @return array<string, int>
+	 */
+	public static function pins_for_run( ?string $run_id ): array {
+		if ( null === $run_id || '' === $run_id ) {
+			return array();
+		}
+		if ( isset( self::$pins_cache[ $run_id ] ) ) {
+			return self::$pins_cache[ $run_id ];
+		}
+		$pins                          = PRAutoBlogger_Run_State::get_pins( $run_id );
+		self::$pins_cache[ $run_id ] = $pins;
+		return $pins;
+	}
+
+	/** Reset per-request caches (tests). */
+	public static function flush_cache(): void {
+		self::$active_cache = array();
+		self::$pins_cache   = array();
+		self::$table_ok     = null;
+	}
+}

includes/core/class-publisher.php

@@ -2,14 +2,19 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Creates WordPress posts from generated and editor-approved content.
  *
  * Handles both publishing (editor-approved) and saving as draft (editor-rejected).
  * Stores all generation metadata as post_meta for transparency and auditability.
  *
- * Triggered by: PRAutoBlogger::run_generation_pipeline() (step 6).
- * Dependencies: WordPress wp_insert_post(), post meta API.
+ * Triggered by: PRAutoBlogger_Pipeline_Runner (step 6).
+ * Dependencies: PRAutoBlogger_Post_Assembler (taxonomy, images, sanitization),
+ *               WordPress wp_insert_post(), post meta API.
  *
+ * @see core/class-post-assembler.php   — Post-creation helpers (taxonomy, images, logs).
+ * @see core/class-peptide-linker.php   — Injects peptide database hyperlinks into content.
  * @see core/class-chief-editor.php     — Produces the editorial review we consume.
  * @see core/class-content-generator.php — Produces the content we publish.
  * @see ARCHITECTURE.md                  — Data flow step 6.
@@ -19,27 +24,22 @@ class PRAutoBlogger_Publisher {
 	/**
 	 * Publish an editor-approved article.
 	 *
-	 * Creates a WordPress post with 'publish' status and stores all generation
-	 * metadata as post_meta.
-	 *
-	 * Side effects: Creates a WordPress post, writes post_meta.
-	 *
 	 * @param string                        $content The final HTML content.
 	 * @param PRAutoBlogger_Article_Idea      $idea    The original article idea.
 	 * @param PRAutoBlogger_Editorial_Review  $review  The editor's review.
 	 * @param string|null                   $run_id  Pipeline run ID for log linking.
-	 *
+	 * @param ?PRAutoBlogger_Cost_Tracker $cost_tracker Optional cost tracker for image generation cost logging.
 	 * @return int The created post ID.
-	 *
 	 * @throws \RuntimeException If post creation fails.
 	 */
 	public function publish(
 		string $content,
 		PRAutoBlogger_Article_Idea $idea,
 		PRAutoBlogger_Editorial_Review $review,
-		?string $run_id = null
+		?string $run_id = null,
+		?PRAutoBlogger_Cost_Tracker $cost_tracker = null
 	): int {
-		return $this->create_post( $content, $idea, $review, 'publish', $run_id );
+		return $this->create_post( $content, $idea, $review, 'publish', $run_id, $cost_tracker );
 	}
 
 	/**
@@ -49,18 +49,18 @@ class PRAutoBlogger_Publisher {
 	 * @param PRAutoBlogger_Article_Idea      $idea    The original article idea.
 	 * @param PRAutoBlogger_Editorial_Review  $review  The editor's review with rejection notes.
 	 * @param string|null                   $run_id  Pipeline run ID for log linking.
-	 *
+	 * @param ?PRAutoBlogger_Cost_Tracker $cost_tracker Optional cost tracker for image generation cost logging.
 	 * @return int The created post ID.
-	 *
 	 * @throws \RuntimeException If post creation fails.
 	 */
 	public function save_as_draft(
 		string $content,
 		PRAutoBlogger_Article_Idea $idea,
 		PRAutoBlogger_Editorial_Review $review,
-		?string $run_id = null
+		?string $run_id = null,
+		?PRAutoBlogger_Cost_Tracker $cost_tracker = null
 	): int {
-		return $this->create_post( $content, $idea, $review, 'draft', $run_id );
+		return $this->create_post( $content, $idea, $review, 'draft', $run_id, $cost_tracker );
 	}
 
 	/**
@@ -71,9 +71,7 @@ class PRAutoBlogger_Publisher {
 	 * @param PRAutoBlogger_Editorial_Review  $review      Editorial review.
 	 * @param string                        $post_status 'publish' or 'draft'.
 	 * @param string|null                   $run_id      Pipeline run ID for log linking.
-	 *
 	 * @return int Post ID.
-	 *
 	 * @throws \RuntimeException If wp_insert_post fails.
 	 */
 	private function create_post(
@@ -81,59 +79,79 @@ class PRAutoBlogger_Publisher {
 		PRAutoBlogger_Article_Idea $idea,
 		PRAutoBlogger_Editorial_Review $review,
 		string $post_status,
-		?string $run_id = null
+		?string $run_id = null,
+		?PRAutoBlogger_Cost_Tracker $cost_tracker = null
 	): int {
-		$post_data = [
-			'post_title'   => sanitize_text_field( $idea->get_suggested_title() ),
-			'post_content' => wp_kses_post( $this->sanitize_llm_content( $content ) ),
-			'post_status'  => $post_status,
-			'post_type'    => 'post',
-			'post_author'  => $this->get_default_author_id(),
-			'meta_input'   => $this->build_meta( $idea, $review ),
-		];
-
-		/**
-		 * Fires before an PRAutoBlogger post is created.
-		 *
-		 * Listeners registered in: class-prautoblogger.php (main loader).
-		 *
-		 * @param array                        $post_data Post data array.
-		 * @param PRAutoBlogger_Article_Idea     $idea      The article idea.
-		 * @param PRAutoBlogger_Editorial_Review $review    The editorial review.
-		 */
-		$post_data = apply_filters( 'prautoblogger_filter_post_data', $post_data, $idea, $review );
-
-		$post_id = wp_insert_post( $post_data, true );
-
-		if ( is_wp_error( $post_id ) ) {
+		// v0.18.1 belt-and-braces: never create a post whose content is
+		// empty once tags and whitespace are stripped — an empty "draft
+		// for human review" (2026-06-11 incident, post 921) reviews
+		// nothing and hides the underlying generation failure. The
+		// provider/writer guards make this unreachable on OpenRouter
+		// paths; this protects every other path into post creation.
+		if ( '' === trim( wp_strip_all_tags( $content ) ) ) {
 			throw new \RuntimeException(
 				sprintf(
-					/* translators: %s: WordPress error message */
-					__( 'Failed to create post: %s', 'prautoblogger' ),
-					$post_id->get_error_message()
+					/* translators: 1: intended post status, 2: article title. */
+					__( 'Refusing to create %1$s post "%2$s": generated content is empty.', 'prautoblogger' ),
+					$post_status,
+					$idea->get_suggested_title()
 				)
 			);
 		}
 
-		// Assign categories/tags based on article type and keywords.
-		$this->assign_taxonomy_terms( $post_id, $idea );
+		// v0.18.0 idempotency: post creation is keyed by run + idea
+		// (check-before-insert) so a retried/resumed run cannot create a
+		// duplicate post. One run_id spans all N articles of a batch, so
+		// the idea hash disambiguates within the run.
+		$idea_hash = PRAutoBlogger_Run_Stage_State::idea_hash( $idea );
+		if ( null !== $run_id && '' !== $run_id ) {
+			$existing_id = $this->find_existing_post( $run_id, $idea_hash );
+			if ( $existing_id > 0 ) {
+				PRAutoBlogger_Logger::instance()->info(
+					sprintf( 'Post for run %s / idea %s already exists (ID=%d) — skipping duplicate insert.', $run_id, $idea_hash, $existing_id ),
+					'publisher'
+				);
+				return $existing_id;
+			}
+		}
 
-		// Update generation log entries to reference this post.
-		$this->link_generation_logs( $post_id, $run_id );
+		// Clean LLM artifacts, then inject peptide hyperlinks deterministically
+		// before the content enters WordPress. Peptide linker no-ops gracefully
+		// if PR Core is not active.
+		$clean_content  = PRAutoBlogger_Post_Assembler::sanitize_llm_content( $content );
+		$linked_content = PRAutoBlogger_Peptide_Linker::inject_links( $clean_content );
+
+		$post_data = array(
+			'post_title'   => sanitize_text_field( $idea->get_suggested_title() ),
+			'post_content' => wp_kses_post( $linked_content ),
+			'post_status'  => $post_status,
+			'post_type'    => 'post',
+			'post_author'  => PRAutoBlogger_Post_Assembler::get_default_author_id(),
+			'meta_input'   => $this->build_meta( $idea, $review, $run_id, $idea_hash ),
+		);
+
+		/** @see class-prautoblogger.php — listeners registered in main loader. */
+		$post_data = apply_filters( 'prautoblogger_filter_post_data', $post_data, $idea, $review );
+
+		$post_id = wp_insert_post( $post_data, true );
+		if ( is_wp_error( $post_id ) ) {
+			throw new \RuntimeException(
+				sprintf( __( 'Failed to create post: %s', 'prautoblogger' ), $post_id->get_error_message() )
+			);
+		}
+
+		PRAutoBlogger_Post_Assembler::assign_taxonomy_terms( $post_id, $idea );
+		PRAutoBlogger_Post_Assembler::link_generation_logs( $post_id, $run_id );
+
+		if ( 'publish' === $post_status ) {
+			PRAutoBlogger_Post_Assembler::attach_generated_images( $post_id, $idea, $post_data, $cost_tracker );
+		}
 
 		PRAutoBlogger_Logger::instance()->info(
 			sprintf( 'Post created: ID=%d, status=%s, title="%s"', $post_id, $post_status, $idea->get_suggested_title() ),
 			'publisher'
 		);
 
-		/**
-		 * Fires after an PRAutoBlogger post is successfully created.
-		 *
-		 * @param int                          $post_id     The new post ID.
-		 * @param string                       $post_status 'publish' or 'draft'.
-		 * @param PRAutoBlogger_Article_Idea     $idea        The article idea.
-		 * @param PRAutoBlogger_Editorial_Review $review      The editorial review.
-		 */
 		do_action( 'prautoblogger_post_created', $post_id, $post_status, $idea, $review );
 
 		return $post_id;
@@ -142,169 +160,76 @@ class PRAutoBlogger_Publisher {
 	/**
 	 * Build post_meta array for generation metadata.
 	 *
+	 * The `_prautoblogger_run_id` key (added v0.8.1) lets the orphan-research
+	 * reaper attribute an orphan `llm_research` row back to its sibling
+	 * articles without re-walking the gen_log table. See
+	 * core/class-research-reaper.php.
+	 *
 	 * @param PRAutoBlogger_Article_Idea     $idea
 	 * @param PRAutoBlogger_Editorial_Review $review
-	 *
+	 * @param string|null                    $run_id Pipeline run UUID, or null in legacy paths.
 	 * @return array<string, mixed>
 	 */
 	private function build_meta(
 		PRAutoBlogger_Article_Idea $idea,
-		PRAutoBlogger_Editorial_Review $review
+		PRAutoBlogger_Editorial_Review $review,
+		?string $run_id = null,
+		string $idea_hash = ''
 	): array {
-		$pipeline_mode = get_option( 'prautoblogger_writing_pipeline', 'multi_step' );
-		$model         = get_option( 'prautoblogger_writing_model', PRAUTOBLOGGER_DEFAULT_WRITING_MODEL );
-
-		return [
-			'_prautoblogger_generated'        => '1',
-			'_prautoblogger_analysis_id'      => $idea->get_analysis_id(),
-			'_prautoblogger_source_ids'       => wp_json_encode( $idea->get_source_ids() ),
-			'_prautoblogger_model_used'       => $model,
-			'_prautoblogger_pipeline_mode'    => $pipeline_mode,
-			'_prautoblogger_editor_verdict'   => $review->get_verdict(),
-			'_prautoblogger_editor_notes'     => $review->get_notes(),
-			'_prautoblogger_quality_score'    => $review->get_quality_score(),
-			'_prautoblogger_seo_score'        => $review->get_seo_score(),
-			'_prautoblogger_generated_at'     => gmdate( 'c' ),
-			'_prautoblogger_topic'            => $idea->get_topic(),
-			'_prautoblogger_article_type'     => $idea->get_article_type(),
-			'_prautoblogger_target_keywords'  => wp_json_encode( $idea->get_target_keywords() ),
-		];
-	}
-
-	/**
-	 * Assign category and tags to a generated post.
-	 *
-	 * @param int                      $post_id
-	 * @param PRAutoBlogger_Article_Idea $idea
-	 *
-	 * @return void
-	 */
-	private function assign_taxonomy_terms( int $post_id, PRAutoBlogger_Article_Idea $idea ): void {
-		$type_category_map = [
-			'guide'      => 'Guides',
-			'solution'   => 'Solutions',
-			'comparison' => 'Comparisons',
-			'article'    => 'Articles',
-		];
-
-		$category_name = $type_category_map[ $idea->get_article_type() ] ?? 'Articles';
-
-		$category = get_term_by( 'name', $category_name, 'category' );
-		if ( ! $category ) {
-			$result = wp_insert_term( $category_name, 'category' );
-			if ( ! is_wp_error( $result ) ) {
-				wp_set_post_categories( $post_id, [ $result['term_id'] ] );
-			}
-		} else {
-			wp_set_post_categories( $post_id, [ $category->term_id ] );
-		}
-
-		$keywords = $idea->get_target_keywords();
-		if ( ! empty( $keywords ) ) {
-			wp_set_post_tags( $post_id, $keywords, true );
-		}
-	}
-
-	/**
-	 * Link generation log entries to the newly created post using run_id.
-	 *
-	 * The previous timestamp-based approach could misattribute costs in batch runs
-	 * where multiple articles are generated in the same pipeline execution. Using
-	 * run_id ensures each post is linked only to the log entries from its own run.
-	 *
-	 * Falls back to timestamp-based linking if no run_id is set (e.g. legacy data
-	 * from before the run_id migration).
-	 *
-	 * @param int         $post_id The newly created post ID.
-	 * @param string|null $run_id  Pipeline run identifier, or null for legacy fallback.
-	 *
-	 * @return void
-	 */
-	private function link_generation_logs( int $post_id, ?string $run_id = null ): void {
-		global $wpdb;
-		$table = $wpdb->prefix . 'prautoblogger_generation_log';
-
+		$meta = array(
+			'_prautoblogger_generated'       => '1',
+			'_prautoblogger_analysis_id'     => $idea->get_analysis_id(),
+			'_prautoblogger_source_ids'      => wp_json_encode( $idea->get_source_ids() ),
+			'_prautoblogger_model_used'      => get_option( 'prautoblogger_writing_model', PRAUTOBLOGGER_DEFAULT_WRITING_MODEL ),
+			'_prautoblogger_pipeline_mode'   => get_option( 'prautoblogger_writing_pipeline', 'multi_step' ),
+			'_prautoblogger_editor_verdict'  => $review->get_verdict(),
+			'_prautoblogger_editor_notes'    => $review->get_notes(),
+			'_prautoblogger_quality_score'   => $review->get_quality_score(),
+			'_prautoblogger_seo_score'       => $review->get_seo_score(),
+			'_prautoblogger_generated_at'    => gmdate( 'c' ),
+			'_prautoblogger_topic'           => $idea->get_topic(),
+			'_prautoblogger_article_type'    => $idea->get_article_type(),
+			'_prautoblogger_target_keywords' => wp_json_encode( $idea->get_target_keywords() ),
+		);
 		if ( null !== $run_id && '' !== $run_id ) {
-			// Precise linking via run_id — no risk of cross-article misattribution.
-			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-			$wpdb->query(
-				$wpdb->prepare(
-					"UPDATE {$table} SET post_id = %d WHERE post_id IS NULL AND run_id = %s",
-					$post_id,
-					$run_id
-				)
-			);
-		} else {
-			// Legacy fallback: timestamp-based linking for pre-migration log entries.
-			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
-			$wpdb->query(
-				$wpdb->prepare(
-					"UPDATE {$table} SET post_id = %d WHERE post_id IS NULL AND created_at >= %s",
-					$post_id,
-					gmdate( 'Y-m-d H:i:s', time() - HOUR_IN_SECONDS )
-				)
-			);
+			$meta['_prautoblogger_run_id'] = $run_id;
 		}
+		if ( '' !== $idea_hash ) {
+			$meta['_prautoblogger_idea_hash'] = $idea_hash;
+		}
+		return $meta;
 	}
 
 	/**
-	 * Strip common LLM output artifacts from generated content.
+	 * Find a post already created for this (run, idea) pair.
 	 *
-	 * LLMs sometimes ignore format instructions and wrap content in markdown
-	 * code fences (```html ... ```) or full HTML document structures
-	 * (<html><head><body>). This method strips those wrappers so only clean
-	 * article-body HTML reaches WordPress.
+	 * Direct postmeta self-join (any post_status, including trash) — the
+	 * idempotency check must see drafts and pending posts too.
 	 *
-	 * @param string $content Raw LLM output.
-	 *
-	 * @return string Cleaned HTML suitable for post_content.
+	 * @param string $run_id    Pipeline run UUID.
+	 * @param string $idea_hash Idea hash from Run_Stage_State::idea_hash().
+	 * @return int Existing post ID, or 0 when none.
 	 */
-	private function sanitize_llm_content( string $content ): string {
-		$content = trim( $content );
-
-		// Strip markdown code fences: ```html ... ``` or ``` ... ```
-		// Handles optional language identifier after opening fence.
-		if ( preg_match( '/^```(?:\w+)?\s*\n(.*?)```\s*$/s', $content, $matches ) ) {
-			$content = trim( $matches[1] );
+	private function find_existing_post( string $run_id, string $idea_hash ): int {
+		global $wpdb;
+		if ( null === $wpdb ) {
+			return 0;
 		}
-
-		// Strip full HTML document wrappers: <html>...<body>content</body>...</html>
-		// Extract only the <body> inner content.
-		if ( preg_match( '/<body[^>]*>(.*)<\/body>/is', $content, $matches ) ) {
-			$content = trim( $matches[1] );
-		}
-
-		// Remove stray <html>, </html>, <head>...</head>, <body>, </body> tags
-		// in case they appear without a proper document structure.
-		$content = preg_replace( '/<\/?(html|head|body|meta|title|!DOCTYPE)[^>]*>/i', '', $content );
-
-		// Remove leftover <link> and <style> tags that belong in <head>, not post content.
-		$content = preg_replace( '/<link\s[^>]*>/i', '', $content );
-		$content = preg_replace( '/<style[^>]*>.*?<\/style>/is', '', $content );
-
-		// Collapse any resulting excess whitespace (multiple blank lines → single).
-		$content = preg_replace( '/\n{3,}/', "\n\n", $content );
-
-		return trim( $content );
-	}
-
-	/**
-	 * Get the default author ID for generated posts.
-	 *
-	 * @return int WordPress user ID.
-	 */
-	private function get_default_author_id(): int {
-		$author_id = absint( get_option( 'prautoblogger_default_author', 0 ) );
-		if ( $author_id > 0 ) {
-			return $author_id;
-		}
-
-		$admins = get_users( [
-			'role'   => 'administrator',
-			'number' => 1,
-			'fields' => 'ID',
-		] );
-
-		return ! empty( $admins ) ? (int) $admins[0] : 1;
+		$postmeta = $wpdb->prefix . 'postmeta';
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$post_id = $wpdb->get_var(
+			$wpdb->prepare(
+				"SELECT pm_run.post_id FROM {$postmeta} pm_run
+				INNER JOIN {$postmeta} pm_hash
+					ON pm_hash.post_id = pm_run.post_id
+					AND pm_hash.meta_key = '_prautoblogger_idea_hash'
+					AND pm_hash.meta_value = %s
+				WHERE pm_run.meta_key = '_prautoblogger_run_id' AND pm_run.meta_value = %s
+				LIMIT 1",
+				$idea_hash,
+				$run_id
+			)
+		);
+		return null !== $post_id ? (int) $post_id : 0;
 	}
 }

includes/core/class-research-reaper.php

@@ -0,0 +1,191 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Daily cron that retroactively amortizes orphan `llm_research` rows.
+ *
+ * When a pipeline run dies between post creation and the final
+ * `Post_Assembler::amortize_research_costs()` call (Hostinger exec kill,
+ * OOM, LiteSpeed cut, fatal), the shared research-cost row stays in
+ * `wp_prautoblogger_generation_log` with `post_id = NULL` and the
+ * articles from that run understate their true cost in the popover.
+ *
+ * This reaper scans for such orphan rows once a day, finds their sibling
+ * posts via the `_prautoblogger_run_id` post_meta (primary) or the
+ * gen_log's own post-linked rows (fallback for legacy posts that
+ * predate the meta), and delegates to the existing idempotent
+ * `amortize_research_costs()` method. Orphans that still have no
+ * siblings after 7 days are deleted outright as sunk cost.
+ *
+ * Spec-wise the CTO asked for the reap method to live on Post_Assembler;
+ * hosting it here instead keeps Post_Assembler under the 300-line cap
+ * (it grew past 300 with the reap method attached) and colocates the
+ * attribution logic next to the cron/CLI plumbing that triggers it.
+ *
+ * Triggered by:
+ * - WP-Cron: `prautoblogger_reap_orphan_research_rows` (daily, 03:15).
+ * - WP-CLI:  `wp prautoblogger reap-research` (manual ops trigger).
+ * Dependencies: PRAutoBlogger_Post_Assembler (amortize_research_costs),
+ *               PRAutoBlogger_Logger, WordPress $wpdb + get_posts.
+ *
+ * @see core/class-post-assembler.php  — amortize_research_costs() does the work.
+ * @see class-activator.php            — Schedules the daily cron.
+ * @see class-deactivator.php          — Unschedules on deactivate.
+ * @see ARCHITECTURE.md                — Cost tracking data flow.
+ */
+class PRAutoBlogger_Research_Reaper {
+
+	/** Grace window — live pipelines have this long to finish amortizing before reaping. */
+	private const GRACE_WINDOW_SECONDS = 3600; // 1 hour.
+
+	/** Stale window — orphans with no sibling posts are deleted outright after this long. */
+	private const STALE_WINDOW_SECONDS = 7 * 86400; // 7 days.
+
+	/**
+	 * Cron action handler — entrypoint for the daily WP-Cron event.
+	 *
+	 * Pure delegate. Never throws.
+	 *
+	 * @return void
+	 */
+	public static function on_cron(): void {
+		self::reap();
+	}
+
+	/**
+	 * Scan and reap orphan `llm_research` rows. Returns a summary that the
+	 * WP-CLI command prints and the cron path ignores.
+	 *
+	 * Side effects: SELECT / INSERT / DELETE on generation_log; post_meta
+	 *               reads; one INFO log line per reaped or stale-deleted
+	 *               orphan; one WARNING on DB error.
+	 *
+	 * @return array{reaped: int, deleted: int, skipped: int}
+	 */
+	public static function reap(): array {
+		$stats = array(
+			'reaped'  => 0,
+			'deleted' => 0,
+			'skipped' => 0,
+		);
+
+		try {
+			global $wpdb;
+			$log_table = $wpdb->prefix . 'prautoblogger_generation_log';
+			$grace     = gmdate( 'Y-m-d H:i:s', time() - self::GRACE_WINDOW_SECONDS );
+
+			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+			$orphans = $wpdb->get_results(
+				$wpdb->prepare(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+					"SELECT id, run_id, created_at FROM {$log_table}
+					WHERE stage = 'llm_research' AND post_id IS NULL AND created_at < %s",
+					$grace
+				)
+			);
+			if ( ! is_array( $orphans ) ) {
+				return $stats;
+			}
+
+			$stale_cutoff = time() - self::STALE_WINDOW_SECONDS;
+			foreach ( $orphans as $orphan ) {
+				self::handle_orphan( $orphan, $stale_cutoff, $log_table, $stats );
+			}
+		} catch ( \Throwable $e ) {
+			PRAutoBlogger_Logger::instance()->warning(
+				'Reaper encountered DB error: ' . $e->getMessage(),
+				'cost-tracker'
+			);
+		}
+
+		return $stats;
+	}
+
+	/**
+	 * Route one orphan row: amortize if siblings exist, delete if stale,
+	 * otherwise skip and try again next run.
+	 *
+	 * @param object $orphan       DB row with id, run_id, created_at.
+	 * @param int    $stale_cutoff Unix timestamp — orphans older than this delete.
+	 * @param string $log_table    Fully-qualified gen_log table name.
+	 * @param array  $stats        Counters, mutated by reference.
+	 * @return void
+	 */
+	private static function handle_orphan( object $orphan, int $stale_cutoff, string $log_table, array &$stats ): void {
+		global $wpdb;
+		$run_id     = (string) ( $orphan->run_id ?? '' );
+		$created_ts = strtotime( (string) ( $orphan->created_at ?? '' ) );
+		$is_stale   = false !== $created_ts && $created_ts < $stale_cutoff;
+
+		if ( '' === $run_id ) {
+			if ( $is_stale ) {
+				// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+				$wpdb->delete( $log_table, array( 'id' => (int) $orphan->id ) );
+				++$stats['deleted'];
+			} else {
+				++$stats['skipped'];
+			}
+			return;
+		}
+
+		$post_ids = self::find_posts_for_run_id( $run_id );
+		if ( count( $post_ids ) >= 1 ) {
+			PRAutoBlogger_Post_Assembler::amortize_research_costs( $run_id );
+			PRAutoBlogger_Logger::instance()->info(
+				sprintf( 'Reaped research cost across %d articles for run %s.', count( $post_ids ), $run_id ),
+				'cost-tracker'
+			);
+			++$stats['reaped'];
+			return;
+		}
+
+		if ( $is_stale ) {
+			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+			$wpdb->delete( $log_table, array( 'id' => (int) $orphan->id ) );
+			PRAutoBlogger_Logger::instance()->info(
+				sprintf( 'Deleted 7-day-stale orphan research row for run %s — no articles to attribute.', $run_id ),
+				'cost-tracker'
+			);
+			++$stats['deleted'];
+			return;
+		}
+
+		++$stats['skipped'];
+	}
+
+	/**
+	 * Return distinct post IDs for a given run_id. Prefers post_meta;
+	 * falls back to gen_log rows for legacy posts.
+	 *
+	 * @param string $run_id Pipeline run UUID.
+	 * @return int[] Distinct post IDs.
+	 */
+	private static function find_posts_for_run_id( string $run_id ): array {
+		$meta_ids = get_posts(
+			array(
+				'post_type'        => 'any',
+				'post_status'      => 'any',
+				'meta_key'         => '_prautoblogger_run_id',
+				'meta_value'       => $run_id,
+				'fields'           => 'ids',
+				'posts_per_page'   => -1,
+				'suppress_filters' => true,
+			)
+		);
+		if ( is_array( $meta_ids ) && ! empty( $meta_ids ) ) {
+			return array_map( 'intval', $meta_ids );
+		}
+
+		global $wpdb;
+		$log_table = $wpdb->prefix . 'prautoblogger_generation_log';
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$ids = $wpdb->get_col(
+			$wpdb->prepare(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+				"SELECT DISTINCT post_id FROM {$log_table} WHERE run_id = %s AND post_id IS NOT NULL",
+				$run_id
+			)
+		);
+		return is_array( $ids ) ? array_map( 'intval', $ids ) : array();
+	}
+}

includes/core/class-run-context.php

@@ -0,0 +1,59 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Per-PHP-process holder for the active pipeline run id.
+ *
+ * What: A process-scoped static slot recording which run this PHP request
+ *       is executing, set whenever Cost_Tracker::set_run_id() is called
+ *       (daily cron, manual generation, queued-article jobs, ideas
+ *       browser). It lets components that are constructed without a run
+ *       reference — the OpenRouter provider (cost-governor guard) and
+ *       standalone Cost_Tracker instances (e.g. the image prompt
+ *       rewriter's) — resolve the surrounding run for reservation and
+ *       prompt-version stamping without threading a parameter through
+ *       every constructor. Mirrors the Opik_Trace_Context precedent.
+ * Who triggers it: PRAutoBlogger_Cost_Tracker::set_run_id() (set);
+ *       Cost_Governor + Cost_Tracker (read).
+ * Dependencies: none.
+ *
+ * @see core/class-cost-tracker.php  — Sets the context on set_run_id().
+ * @see core/class-cost-governor.php — Reads it to guard LLM calls.
+ */
+class PRAutoBlogger_Run_Context {
+
+	/** @var string|null Active run id for this PHP process, or null. */
+	private static ?string $run_id = null;
+
+	/**
+	 * Record the active run id for this process.
+	 *
+	 * @param string $run_id Pipeline run UUID.
+	 * @return void
+	 */
+	public static function set_run_id( string $run_id ): void {
+		if ( '' !== $run_id ) {
+			self::$run_id = $run_id;
+		}
+	}
+
+	/**
+	 * The active run id for this process, or null outside any run.
+	 *
+	 * @return string|null
+	 */
+	public static function current_run_id(): ?string {
+		return self::$run_id;
+	}
+
+	/**
+	 * Clear the context (tests / end of run).
+	 *
+	 * @return void
+	 */
+	public static function clear(): void {
+		self::$run_id = null;
+	}
+}

includes/core/class-run-reaper.php

@@ -0,0 +1,270 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Daily sweep for stuck runs + audit-payload retention (extends #19).
+ *
+ * What: Rides the EXISTING `prautoblogger_reap_orphan_research_rows` cron
+ *       (no new schedule) alongside the v0.8.1 Research_Reaper. Three jobs:
+ *       1. Stage sweep — run_stages rows stuck `running` longer than
+ *          2× the stage's expected wall-clock are marked `failed`
+ *          (Hostinger kills PHP at ~120s; a stage "running" for 10+
+ *          minutes is dead, its process gone).
+ *       2. Run sweep — runs rows still open (pending/running) with no
+ *          ledger/state activity for 2× the expected run wall-clock are
+ *          marked `failed` and their non-done stages reaped to `failed`;
+ *          such runs render as "incomplete" via incomplete_runs().
+ *       3. Retention — `request_json` on generation_log and stage output
+ *          payloads (`meta_json` on run_stages) are NULLed after R days;
+ *          R comes from the `prautoblogger_request_json_retention_days`
+ *          SETTING (default constant 14; 0 = keep forever) — never a
+ *          literal at the point of use.
+ * Who triggers it: WP-Cron `prautoblogger_reap_orphan_research_rows`
+ *       (daily 03:15, registered in class-prautoblogger.php).
+ * Dependencies: Run_State, Run_Stage_State, WordPress $wpdb, Logger.
+ *
+ * @see core/class-research-reaper.php — The #19 orphan-cost reaper (same cron).
+ * @see core/class-run-state.php       — Run rows swept here.
+ * @see ARCHITECTURE.md #21            — Design rationale.
+ */
+class PRAutoBlogger_Run_Reaper {
+
+	/**
+	 * Expected per-stage wall-clock seconds (sweep threshold = 2×). An
+	 * engineering constant (like Research_Reaper::GRACE_WINDOW_SECONDS),
+	 * overridable per stage via the
+	 * `prautoblogger_filter_stage_expected_seconds` filter.
+	 */
+	private const EXPECTED_STAGE_SECONDS = 300;
+
+	/**
+	 * Expected whole-run wall-clock seconds (collect + analyze + up to 10
+	 * chained articles ≈ 30 min worst case). Sweep threshold = 2×.
+	 * Overridable via `prautoblogger_filter_expected_run_seconds`.
+	 */
+	private const EXPECTED_RUN_SECONDS = 1800;
+
+	/**
+	 * Cron action handler — entrypoint. Pure delegate, never throws.
+	 *
+	 * @return void
+	 */
+	public static function on_cron(): void {
+		self::reap();
+	}
+
+	/**
+	 * Run all three sweeps. Returns a summary (cron path ignores it).
+	 *
+	 * Side effects: UPDATEs on run_stages / runs / generation_log; INFO
+	 * log lines for swept runs.
+	 *
+	 * @return array{stages_failed: int, runs_failed: int, payloads_pruned: int}
+	 */
+	public static function reap(): array {
+		$stats = array(
+			'stages_failed'   => 0,
+			'runs_failed'     => 0,
+			'payloads_pruned' => 0,
+		);
+
+		try {
+			$stats['stages_failed']   = self::sweep_stuck_stages();
+			$stats['runs_failed']     = self::sweep_stuck_runs();
+			$stats['payloads_pruned'] = self::prune_payloads();
+		} catch ( \Throwable $e ) {
+			PRAutoBlogger_Logger::instance()->warning(
+				'Run reaper encountered an error: ' . $e->getMessage(),
+				'run-reaper'
+			);
+		}
+
+		return $stats;
+	}
+
+	/**
+	 * Runs that died mid-pipeline, for audit surfaces: failed/halted runs
+	 * that still have non-done stage rows ("incomplete").
+	 *
+	 * @param int $limit Max rows (default 20).
+	 * @return array<int, array<string, mixed>>
+	 */
+	public static function incomplete_runs( int $limit = 20 ): array {
+		if ( ! PRAutoBlogger_Run_State::is_available() || ! PRAutoBlogger_Run_Stage_State::is_available() ) {
+			return array();
+		}
+		global $wpdb;
+		$runs   = PRAutoBlogger_Run_State::table_name();
+		$stages = PRAutoBlogger_Run_Stage_State::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$rows = $wpdb->get_results(
+			$wpdb->prepare(
+				"SELECT r.* FROM {$runs} r
+				WHERE r.status IN ('failed','halted')
+					AND EXISTS (SELECT 1 FROM {$stages} s WHERE s.run_id = r.run_id AND s.status != 'done')
+				ORDER BY r.updated_at DESC LIMIT %d",
+				$limit
+			),
+			ARRAY_A
+		);
+		return is_array( $rows ) ? $rows : array();
+	}
+
+	/**
+	 * Stage sweep: `running` rows older than 2× expected stage wall-clock
+	 * become `failed`.
+	 *
+	 * @return int Rows swept.
+	 */
+	private static function sweep_stuck_stages(): int {
+		if ( ! PRAutoBlogger_Run_Stage_State::is_available() ) {
+			return 0;
+		}
+		global $wpdb;
+		$table = PRAutoBlogger_Run_Stage_State::table_name();
+
+		/**
+		 * Filter the expected per-stage wall-clock seconds used by the
+		 * stuck-stage sweep (threshold is 2× this value).
+		 *
+		 * @param int $seconds Expected seconds (default 300).
+		 */
+		$expected = (int) apply_filters( 'prautoblogger_filter_stage_expected_seconds', self::EXPECTED_STAGE_SECONDS );
+		$cutoff   = gmdate( 'Y-m-d H:i:s', time() - ( 2 * $expected ) );
+		$now      = current_time( 'mysql' );
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$swept = $wpdb->query(
+			$wpdb->prepare(
+				"UPDATE {$table} SET status = 'failed', updated_at = %s, finished_at = %s
+				WHERE status = 'running' AND updated_at < %s",
+				$now,
+				$now,
+				$cutoff
+			)
+		);
+		return is_numeric( $swept ) ? (int) $swept : 0;
+	}
+
+	/**
+	 * Run sweep: open runs with no activity for 2× expected run wall-clock
+	 * are marked `failed`; their pending/running stages are reaped.
+	 *
+	 * @return int Runs swept.
+	 */
+	private static function sweep_stuck_runs(): int {
+		if ( ! PRAutoBlogger_Run_State::is_available() ) {
+			return 0;
+		}
+		global $wpdb;
+		$runs = PRAutoBlogger_Run_State::table_name();
+
+		/**
+		 * Filter the expected whole-run wall-clock seconds used by the
+		 * stuck-run sweep (threshold is 2× this value).
+		 *
+		 * @param int $seconds Expected seconds (default 1800).
+		 */
+		$expected = (int) apply_filters( 'prautoblogger_filter_expected_run_seconds', self::EXPECTED_RUN_SECONDS );
+		$cutoff   = gmdate( 'Y-m-d H:i:s', time() - ( 2 * $expected ) );
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$stuck = $wpdb->get_col(
+			$wpdb->prepare(
+				"SELECT run_id FROM {$runs} WHERE status IN ('pending','running') AND updated_at < %s",
+				$cutoff
+			)
+		);
+		if ( ! is_array( $stuck ) || empty( $stuck ) ) {
+			return 0;
+		}
+
+		$swept = 0;
+		foreach ( $stuck as $run_id ) {
+			$run_id = (string) $run_id;
+			if ( ! PRAutoBlogger_Run_State::mark_status( $run_id, 'failed' ) ) {
+				continue;
+			}
+			self::reap_open_stages( $run_id );
+			PRAutoBlogger_Logger::instance()->info(
+				sprintf( 'Run %s stuck past 2x expected wall-clock — marked failed (renders as incomplete).', $run_id ),
+				'run-reaper'
+			);
+			++$swept;
+		}
+		return $swept;
+	}
+
+	/**
+	 * Mark a failed run's pending/running stage rows as failed.
+	 *
+	 * @param string $run_id Run UUID.
+	 * @return void
+	 */
+	private static function reap_open_stages( string $run_id ): void {
+		if ( ! PRAutoBlogger_Run_Stage_State::is_available() ) {
+			return;
+		}
+		global $wpdb;
+		$table = PRAutoBlogger_Run_Stage_State::table_name();
+		$now   = current_time( 'mysql' );
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$wpdb->query(
+			$wpdb->prepare(
+				"UPDATE {$table} SET status = 'failed', updated_at = %s, finished_at = %s
+				WHERE run_id = %s AND status IN ('pending','running')",
+				$now,
+				$now,
+				$run_id
+			)
+		);
+	}
+
+	/**
+	 * Retention: NULL heavy payloads older than R days. R is read from the
+	 * `prautoblogger_request_json_retention_days` setting at every call
+	 * (default = PRAUTOBLOGGER_DEFAULT_REQUEST_JSON_RETENTION_DAYS;
+	 * 0 or negative = keep forever).
+	 *
+	 * @return int Rows pruned (both tables combined).
+	 */
+	private static function prune_payloads(): int {
+		$days = (int) get_option(
+			'prautoblogger_request_json_retention_days',
+			PRAUTOBLOGGER_DEFAULT_REQUEST_JSON_RETENTION_DAYS
+		);
+		if ( $days <= 0 ) {
+			return 0;
+		}
+
+		global $wpdb;
+		$cutoff = gmdate( 'Y-m-d H:i:s', time() - ( $days * DAY_IN_SECONDS ) );
+		$pruned = 0;
+
+		$gen_log = $wpdb->prefix . 'prautoblogger_generation_log';
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$result = $wpdb->query(
+			$wpdb->prepare(
+				"UPDATE {$gen_log} SET request_json = NULL WHERE request_json IS NOT NULL AND created_at < %s",
+				$cutoff
+			)
+		);
+		$pruned += is_numeric( $result ) ? (int) $result : 0;
+
+		if ( PRAutoBlogger_Run_Stage_State::is_available() ) {
+			$stages = PRAutoBlogger_Run_Stage_State::table_name();
+			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+			$result = $wpdb->query(
+				$wpdb->prepare(
+					"UPDATE {$stages} SET meta_json = NULL WHERE meta_json IS NOT NULL AND updated_at < %s",
+					$cutoff
+				)
+			);
+			$pruned += is_numeric( $result ) ? (int) $result : 0;
+		}
+
+		return $pruned;
+	}
+}

includes/core/class-run-stage-state.php

@@ -0,0 +1,313 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Per-run per-stage state machine over `wp_prautoblogger_run_stages`.
+ *
+ * One row per (run_id, stage, agent_role, item_key) holding
+ * pending|running|done|failed|halted plus the output snapshot (meta_json).
+ * Done stages are sticky and never re-charged on resume. Self-healing:
+ * a missing table degrades every method to a no-op/false.
+ *
+ * v0.18.2: role is resolved from Stage_Display_Map when caller passes ''
+ * so start/done/is_done/get_output are always symmetric. Explicit non-empty
+ * roles (Phase-2 fan-out) are honoured as-is. get() falls back to role=''
+ * on miss for mid-run-upgrade compat with v0.18.1 rows.
+ *
+ * @see core/class-run-state.php  — Run-level lifecycle + ledger row.
+ * @see core/class-run-reaper.php — Sweeps stages stuck in 'running'.
+ * @see ARCHITECTURE.md #22       — Pipeline v2 Phase 1 substrate.
+ */
+class PRAutoBlogger_Run_Stage_State {
+
+	/** @var bool|null Per-request "run_stages table exists" probe result. */
+	private static ?bool $table_ok = null;
+
+	/** @return string Fully-qualified run_stages table name. */
+	public static function table_name(): string {
+		global $wpdb;
+		return $wpdb->prefix . 'prautoblogger_run_stages';
+	}
+
+	/**
+	 * Whether the run_stages table exists and is queryable. Cached per request.
+	 *
+	 * @return bool
+	 */
+	public static function is_available(): bool {
+		if ( null !== self::$table_ok ) {
+			return self::$table_ok;
+		}
+		global $wpdb;
+		if ( null === $wpdb ) {
+			return false;
+		}
+		$table = self::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$found          = $wpdb->get_var( $wpdb->prepare( 'SHOW TABLES LIKE %s', $table ) );
+		self::$table_ok = ( $found === $table );
+		return self::$table_ok;
+	}
+
+	/**
+	 * Stable 16-hex hash for one article idea within a run.
+	 *
+	 * @param PRAutoBlogger_Article_Idea $idea The idea.
+	 * @return string
+	 */
+	public static function idea_hash( PRAutoBlogger_Article_Idea $idea ): string {
+		return substr( md5( $idea->get_suggested_title() . '|' . $idea->get_topic() ), 0, 16 );
+	}
+
+	/**
+	 * Stage item_key for an article idea ('' reserved for run-level stages).
+	 *
+	 * @param PRAutoBlogger_Article_Idea $idea The idea.
+	 * @return string e.g. 'idea:1a2b3c4d5e6f7a8b'.
+	 */
+	public static function item_key_for_idea( PRAutoBlogger_Article_Idea $idea ): string {
+		return 'idea:' . self::idea_hash( $idea );
+	}
+
+	/**
+	 * Mark a stage as running. Sticky: done stages are never demoted.
+	 *
+	 * @param string $run_id     Run UUID.
+	 * @param string $stage      Stage name (see Stage_Display_Map).
+	 * @param string $agent_role Fan-out dimension ('' = resolve from stage map).
+	 * @param string $item_key   Article scope ('' for run-level stages).
+	 */
+	public static function start( string $run_id, string $stage, string $agent_role = '', string $item_key = '' ): void {
+		if ( '' === $run_id || ! self::is_available() ) {
+			return;
+		}
+		$agent_role = self::resolve_role( $stage, $agent_role );
+		global $wpdb;
+		$table = self::table_name();
+		$now   = current_time( 'mysql' );
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$wpdb->query(
+			$wpdb->prepare(
+				"INSERT INTO {$table}
+				(run_id, stage, agent_role, item_key, status, attempt, started_at, updated_at)
+				VALUES (%s, %s, %s, %s, 'running', 1, %s, %s)
+				ON DUPLICATE KEY UPDATE
+					attempt = IF(status = 'done', attempt, attempt + 1),
+					status = IF(status = 'done', 'done', 'running'),
+					updated_at = VALUES(updated_at)",
+				$run_id,
+				$stage,
+				$agent_role,
+				$item_key,
+				$now,
+				$now
+			)
+		);
+	}
+
+	/**
+	 * Mark a stage done and persist its output for resume-without-recharge.
+	 *
+	 * @param string      $run_id     Run UUID.
+	 * @param string      $stage      Stage name.
+	 * @param string      $agent_role Fan-out dimension ('' = resolve from stage map).
+	 * @param string      $item_key   Article scope.
+	 * @param string|null $output     Stage output snapshot (pruned after R days).
+	 * @param float       $cost_usd   Cost attributed to this stage.
+	 */
+	public static function done( string $run_id, string $stage, string $agent_role = '', string $item_key = '', ?string $output = null, float $cost_usd = 0.0 ): void {
+		if ( '' === $run_id || ! self::is_available() ) {
+			return;
+		}
+		$agent_role = self::resolve_role( $stage, $agent_role );
+		global $wpdb;
+		$table = self::table_name();
+		$now   = current_time( 'mysql' );
+		$meta  = null !== $output ? wp_json_encode( array( 'output' => $output ) ) : null;
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$wpdb->query(
+			$wpdb->prepare(
+				"INSERT INTO {$table}
+				(run_id, stage, agent_role, item_key, status, attempt, cost_usd, meta_json, started_at, updated_at, finished_at)
+				VALUES (%s, %s, %s, %s, 'done', 1, %f, %s, %s, %s, %s)
+				ON DUPLICATE KEY UPDATE
+					status = 'done',
+					cost_usd = VALUES(cost_usd),
+					meta_json = VALUES(meta_json),
+					updated_at = VALUES(updated_at),
+					finished_at = VALUES(finished_at)",
+				$run_id,
+				$stage,
+				$agent_role,
+				$item_key,
+				$cost_usd,
+				$meta,
+				$now,
+				$now,
+				$now
+			)
+		);
+	}
+
+	/**
+	 * Mark a stage failed (does not demote a done stage).
+	 *
+	 * @param string $run_id     Run UUID.
+	 * @param string $stage      Stage name.
+	 * @param string $agent_role Fan-out dimension ('' = resolve from stage map).
+	 * @param string $item_key   Article scope.
+	 */
+	public static function fail( string $run_id, string $stage, string $agent_role = '', string $item_key = '' ): void {
+		if ( '' === $run_id || ! self::is_available() ) {
+			return;
+		}
+		$agent_role = self::resolve_role( $stage, $agent_role );
+		global $wpdb;
+		$table = self::table_name();
+		$now   = current_time( 'mysql' );
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$wpdb->query(
+			$wpdb->prepare(
+				"UPDATE {$table} SET status = 'failed', updated_at = %s, finished_at = %s
+				WHERE run_id = %s AND stage = %s AND agent_role = %s AND item_key = %s AND status != 'done'",
+				$now,
+				$now,
+				$run_id,
+				$stage,
+				$agent_role,
+				$item_key
+			)
+		);
+	}
+
+	/**
+	 * Fetch one stage row. Falls back to role='' on miss for mid-run-upgrade
+	 * compat with v0.18.1 rows (one extra indexed query, only on miss).
+	 *
+	 * @param string $run_id     Run UUID.
+	 * @param string $stage      Stage name.
+	 * @param string $agent_role Fan-out dimension ('' = resolve from stage map).
+	 * @param string $item_key   Article scope.
+	 * @return array<string, mixed>|null
+	 */
+	public static function get( string $run_id, string $stage, string $agent_role = '', string $item_key = '' ): ?array {
+		if ( '' === $run_id || ! self::is_available() ) {
+			return null;
+		}
+		$agent_role = self::resolve_role( $stage, $agent_role );
+		global $wpdb;
+		$table = self::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$row = $wpdb->get_row(
+			$wpdb->prepare(
+				"SELECT * FROM {$table} WHERE run_id = %s AND stage = %s AND agent_role = %s AND item_key = %s",
+				$run_id,
+				$stage,
+				$agent_role,
+				$item_key
+			),
+			ARRAY_A
+		);
+		if ( is_array( $row ) ) {
+			return $row;
+		}
+		// v0.18.1 upgrade compat: rows started before this fix carry role=''.
+		// One extra indexed query, only on miss, only for known stages.
+		if ( '' !== $agent_role ) {
+			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+			$legacy = $wpdb->get_row(
+				$wpdb->prepare(
+					"SELECT * FROM {$table} WHERE run_id = %s AND stage = %s AND agent_role = '' AND item_key = %s",
+					$run_id,
+					$stage,
+					$item_key
+				),
+				ARRAY_A
+			);
+			return is_array( $legacy ) ? $legacy : null;
+		}
+		return null;
+	}
+
+	/**
+	 * Whether a stage already completed (resume entry-point check).
+	 *
+	 * @param string $run_id     Run UUID.
+	 * @param string $stage      Stage name.
+	 * @param string $agent_role Fan-out dimension ('' = resolve from stage map).
+	 * @param string $item_key   Article scope.
+	 * @return bool
+	 */
+	public static function is_done( string $run_id, string $stage, string $agent_role = '', string $item_key = '' ): bool {
+		$row = self::get( $run_id, $stage, $agent_role, $item_key );
+		return null !== $row && 'done' === $row['status'];
+	}
+
+	/**
+	 * A done stage's stored output (null when absent, not done, or pruned).
+	 *
+	 * @param string $run_id     Run UUID.
+	 * @param string $stage      Stage name.
+	 * @param string $agent_role Fan-out dimension ('' = resolve from stage map).
+	 * @param string $item_key   Article scope.
+	 * @return string|null
+	 */
+	public static function get_output( string $run_id, string $stage, string $agent_role = '', string $item_key = '' ): ?string {
+		$row = self::get( $run_id, $stage, $agent_role, $item_key );
+		if ( null === $row || 'done' !== $row['status'] || empty( $row['meta_json'] ) ) {
+			return null;
+		}
+		$meta = json_decode( (string) $row['meta_json'], true );
+		return is_array( $meta ) && isset( $meta['output'] ) ? (string) $meta['output'] : null;
+	}
+
+	/**
+	 * Fail every still-open stage of one item. Done stages are untouched.
+	 *
+	 * @param string $run_id   Run UUID.
+	 * @param string $item_key Stage item key ('' = run-level stages).
+	 */
+	public static function fail_open_for_item( string $run_id, string $item_key ): void {
+		if ( '' === $run_id || ! self::is_available() ) {
+			return;
+		}
+		global $wpdb;
+		$table = self::table_name();
+		$now   = current_time( 'mysql' );
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$wpdb->query(
+			$wpdb->prepare(
+				"UPDATE {$table} SET status = 'failed', updated_at = %s, finished_at = %s
+				WHERE run_id = %s AND item_key = %s AND status IN ('pending','running')",
+				$now,
+				$now,
+				$run_id,
+				$item_key
+			)
+		);
+	}
+
+	/** Reset per-request caches (tests). */
+	public static function flush_cache(): void {
+		self::$table_ok = null;
+	}
+
+	/**
+	 * Resolve the effective agent role for a stage.
+	 *
+	 * '' → derive from Stage_Display_Map (unknown stages map to '').
+	 * Non-empty → returned as-is (Phase-2 explicit fan-out role).
+	 *
+	 * @param string $stage      Stage name.
+	 * @param string $agent_role Caller-supplied role ('' = auto-resolve).
+	 * @return string Effective agent role.
+	 */
+	private static function resolve_role( string $stage, string $agent_role ): string {
+		if ( '' !== $agent_role ) {
+			return $agent_role;
+		}
+		return (string) PRAutoBlogger_Stage_Display_Map::default_agent_role( $stage );
+	}
+}

includes/core/class-run-state.php

@@ -0,0 +1,259 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Run-level state: the `wp_prautoblogger_runs` ledger + lifecycle row.
+ *
+ * What: One row per pipeline run (keyed by run_id UUID) carrying the run
+ *       status (pending|running|done|failed|halted), the per-run cost
+ *       ledger the Cost_Governor reserves against (ceiling / reserved /
+ *       settled / overage), and the prompt versions pinned at run start.
+ *       Every method is self-healing: a missing table (half-migrated
+ *       site) degrades to no-ops/empty reads, never a fatal. Final states
+ *       are sticky — a halted or failed run cannot be flipped back to
+ *       running by a late writer. Per-stage state lives in
+ *       PRAutoBlogger_Run_Stage_State (run_stages table).
+ * Who triggers it: Cost_Tracker::set_run_id() (ensure_run + pinning),
+ *       Cost_Governor (ledger + halt), Run_Reaper (stuck-run sweep),
+ *       Review Queue (halted-run surfacing), Pipeline_Runner (completion).
+ * Dependencies: WordPress $wpdb, get_option (ceiling setting), wp_json_encode.
+ *
+ * @see core/class-cost-governor.php       — Reserves against this row atomically.
+ * @see core/class-prompt-registry.php     — Reads/writes pins via this class.
+ * @see core/class-run-stage-state.php     — Per-stage rows (commit 4).
+ * @see ARCHITECTURE.md #21                — Design rationale.
+ */
+class PRAutoBlogger_Run_State {
+
+	/** @var bool|null Per-request "runs table exists" probe result. */
+	private static ?bool $table_ok = null;
+
+	/** Fully-qualified runs table name (shared with Cost_Governor). */
+	public static function table_name(): string {
+		global $wpdb;
+		return $wpdb->prefix . 'prautoblogger_runs';
+	}
+
+	/**
+	 * Whether the runs table exists and is queryable. Cached per request;
+	 * never throws.
+	 *
+	 * @return bool
+	 */
+	public static function is_available(): bool {
+		if ( null !== self::$table_ok ) {
+			return self::$table_ok;
+		}
+		global $wpdb;
+		if ( null === $wpdb ) {
+			return false; // Not cached: $wpdb may appear later in boot.
+		}
+		$table = self::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$found          = $wpdb->get_var( $wpdb->prepare( 'SHOW TABLES LIKE %s', $table ) );
+		self::$table_ok = ( $found === $table );
+		return self::$table_ok;
+	}
+
+	/**
+	 * The per-run cost ceiling, read from the SETTING at call time
+	 * (never a literal at the point of use). 0 disables the per-run guard.
+	 *
+	 * @return float Ceiling in USD.
+	 */
+	public static function ceiling_setting(): float {
+		return (float) get_option( 'prautoblogger_per_run_cost_ceiling_usd', PRAUTOBLOGGER_DEFAULT_RUN_CEILING_USD );
+	}
+
+	/**
+	 * Create the run row if it does not exist (INSERT IGNORE — concurrent
+	 * callers cannot double-create). Snapshots the ceiling setting at run
+	 * start so a mid-run settings change cannot move the goalposts.
+	 *
+	 * Side effects: one INSERT IGNORE.
+	 *
+	 * @param string $run_id Pipeline run UUID.
+	 * @return void
+	 */
+	public static function ensure_run( string $run_id ): void {
+		if ( '' === $run_id || ! self::is_available() ) {
+			return;
+		}
+		global $wpdb;
+		$table = self::table_name();
+		$now   = current_time( 'mysql' );
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$wpdb->query(
+			$wpdb->prepare(
+				"INSERT IGNORE INTO {$table}
+				(run_id, status, ceiling_usd, reserved_usd, settled_usd, overage_usd, started_at, updated_at)
+				VALUES (%s, 'running', %f, 0, 0, 0, %s, %s)",
+				$run_id,
+				self::ceiling_setting(),
+				$now,
+				$now
+			)
+		);
+	}
+
+	/**
+	 * Fetch a run row.
+	 *
+	 * @param string $run_id Pipeline run UUID.
+	 * @return array<string, mixed>|null Row, or null when absent/unavailable.
+	 */
+	public static function get_run( string $run_id ): ?array {
+		if ( '' === $run_id || ! self::is_available() ) {
+			return null;
+		}
+		global $wpdb;
+		$table = self::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$row = $wpdb->get_row(
+			$wpdb->prepare( "SELECT * FROM {$table} WHERE run_id = %s", $run_id ),
+			ARRAY_A
+		);
+		return is_array( $row ) ? $row : null;
+	}
+
+	/**
+	 * Current run status, or null when the run has no row.
+	 *
+	 * @param string $run_id Pipeline run UUID.
+	 * @return string|null pending|running|done|failed|halted, or null.
+	 */
+	public static function get_status( string $run_id ): ?string {
+		$run = self::get_run( $run_id );
+		return null !== $run ? (string) $run['status'] : null;
+	}
+
+	/**
+	 * Store the pinned prompt versions — only if the run has none yet, so
+	 * a resumed run keeps the versions it started with.
+	 *
+	 * @param string             $run_id Pipeline run UUID.
+	 * @param array<string, int> $pins   prompt_key => version map.
+	 * @return void
+	 */
+	public static function set_pins_if_absent( string $run_id, array $pins ): void {
+		if ( '' === $run_id || empty( $pins ) || ! self::is_available() ) {
+			return;
+		}
+		self::ensure_run( $run_id );
+		global $wpdb;
+		$table = self::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$wpdb->query(
+			$wpdb->prepare(
+				"UPDATE {$table} SET pinned_prompts_json = %s, updated_at = %s
+				WHERE run_id = %s AND (pinned_prompts_json IS NULL OR pinned_prompts_json = '')",
+				wp_json_encode( $pins ),
+				current_time( 'mysql' ),
+				$run_id
+			)
+		);
+	}
+
+	/**
+	 * The pinned prompt versions for a run.
+	 *
+	 * @param string $run_id Pipeline run UUID.
+	 * @return array<string, int> prompt_key => version ({} when none).
+	 */
+	public static function get_pins( string $run_id ): array {
+		$run = self::get_run( $run_id );
+		if ( null === $run || empty( $run['pinned_prompts_json'] ) ) {
+			return array();
+		}
+		$pins = json_decode( (string) $run['pinned_prompts_json'], true );
+		return is_array( $pins ) ? array_map( 'intval', $pins ) : array();
+	}
+
+	/**
+	 * Move a run to a new status. Forward transitions only touch open
+	 * (pending/running) runs; `halted` and `failed` are sticky and `done`
+	 * cannot overwrite them.
+	 *
+	 * @param string $run_id Pipeline run UUID.
+	 * @param string $status One of done|failed|halted|running.
+	 * @return bool True when a row transitioned.
+	 */
+	public static function mark_status( string $run_id, string $status ): bool {
+		if ( '' === $run_id || ! self::is_available() ) {
+			return false;
+		}
+		if ( ! in_array( $status, array( 'running', 'done', 'failed', 'halted' ), true ) ) {
+			return false;
+		}
+		global $wpdb;
+		$table    = self::table_name();
+		$now      = current_time( 'mysql' );
+		$finished = in_array( $status, array( 'done', 'failed', 'halted' ), true ) ? $now : null;
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$updated = $wpdb->query(
+			$wpdb->prepare(
+				"UPDATE {$table} SET status = %s, updated_at = %s, finished_at = %s
+				WHERE run_id = %s AND status IN ('pending','running')",
+				$status,
+				$now,
+				$finished,
+				$run_id
+			)
+		);
+		return $updated >= 1;
+	}
+
+	/**
+	 * Record by how much a breaching reservation exceeded the ceiling.
+	 *
+	 * @param string $run_id  Pipeline run UUID.
+	 * @param float  $overage USD amount over the ceiling.
+	 * @return void
+	 */
+	public static function record_overage( string $run_id, float $overage ): void {
+		if ( '' === $run_id || $overage <= 0 || ! self::is_available() ) {
+			return;
+		}
+		global $wpdb;
+		$table = self::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
+		$wpdb->query(
+			$wpdb->prepare(
+				"UPDATE {$table} SET overage_usd = GREATEST(overage_usd, %f), updated_at = %s WHERE run_id = %s",
+				$overage,
+				current_time( 'mysql' ),
+				$run_id
+			)
+		);
+	}
+
+	/**
+	 * Recent halted runs, for the Review Queue surface.
+	 *
+	 * @param int $limit Max rows (default 10).
+	 * @return array<int, array<string, mixed>>
+	 */
+	public static function halted_runs( int $limit = 10 ): array {
+		if ( ! self::is_available() ) {
+			return array();
+		}
+		global $wpdb;
+		$table = self::table_name();
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
+		$rows = $wpdb->get_results(
+			$wpdb->prepare(
+				"SELECT * FROM {$table} WHERE status = 'halted' ORDER BY updated_at DESC LIMIT %d",
+				$limit
+			),
+			ARRAY_A
+		);
+		return is_array( $rows ) ? $rows : array();
+	}
+
+	/** Reset per-request caches (tests). */
+	public static function flush_cache(): void {
+		self::$table_ok = null;
+	}
+}

includes/core/class-semantic-dedup.php

@@ -0,0 +1,371 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Semantic deduplication using embedding cosine similarity.
+ *
+ * Embeds candidate topics and recent post titles in a single batch API call,
+ * then compares via cosine similarity. Falls back to keyword-overlap matching
+ * if the embedding API is unavailable or fails.
+ *
+ * Triggered by: PRAutoBlogger_Idea_Scorer::score_and_rank().
+ * Dependencies: OpenRouter_Embedding_Provider, WP_Query.
+ *
+ * @see core/class-idea-scorer.php                         — Consumer.
+ * @see providers/class-open-router-embedding-provider.php — Embedding API.
+ */
+class PRAutoBlogger_Semantic_Dedup {
+
+	/**
+	 * Cosine similarity threshold for "too similar". MiniLM embeddings treat
+	 * ~0.7+ as semantically equivalent for short texts. We use 0.72 to avoid
+	 * over-aggressive blocking while still catching rephrasings.
+	 */
+	private const SIMILARITY_THRESHOLD = 0.72;
+
+	/** @var float[][] Cached embeddings for recent post titles, keyed by index. */
+	private array $title_embeddings = array();
+
+	/** @var string[] Recent post titles. */
+	private array $recent_titles = array();
+
+	/** @var float[][] Cached embeddings for accepted ideas, accumulated per-batch. */
+	private array $accepted_embeddings = array();
+
+	/** @var bool Whether embeddings are available (false after API failure). */
+	private bool $embeddings_available = true;
+
+	/** @var PRAutoBlogger_OpenRouter_Embedding_Provider|null Reused across calls. */
+	private ?PRAutoBlogger_OpenRouter_Embedding_Provider $provider = null;
+
+	/**
+	 * Initialize by fetching recent titles and pre-computing their embeddings.
+	 *
+	 * Called once at the start of scoring. If the embedding API fails,
+	 * sets a flag so all subsequent checks fall back to keyword matching.
+	 *
+	 * Side effects: HTTP request to OpenRouter embedding API, WP_Query.
+	 */
+	public function initialize(): void {
+		$this->recent_titles = $this->fetch_recent_post_titles();
+		if ( empty( $this->recent_titles ) ) {
+			return;
+		}
+
+		try {
+			$this->provider         = new PRAutoBlogger_OpenRouter_Embedding_Provider();
+			$this->title_embeddings = $this->provider->get_embeddings( $this->recent_titles );
+		} catch ( \Throwable $e ) {
+			PRAutoBlogger_Logger::instance()->warning(
+				'Semantic dedup unavailable, falling back to keyword matching: ' . $e->getMessage(),
+				'scorer'
+			);
+			$this->embeddings_available = false;
+		}
+	}
+
+	/**
+	 * Check if a topic is too similar to any already-accepted idea in this batch.
+	 *
+	 * @param string   $topic            Candidate topic text.
+	 * @param string[] $topic_keywords   Pre-extracted keywords (for fallback).
+	 * @param array    $keyword_sets     Accepted keyword sets (for fallback).
+	 *
+	 * @return bool True if the topic should be skipped.
+	 */
+	public function is_batch_duplicate( string $topic, array $topic_keywords, array $keyword_sets ): bool {
+		if ( ! $this->embeddings_available || empty( $this->accepted_embeddings ) ) {
+			return $this->keyword_overlaps_any( $topic_keywords, $keyword_sets );
+		}
+
+		$embedding = $this->embed_single( $topic );
+		if ( null === $embedding ) {
+			return $this->keyword_overlaps_any( $topic_keywords, $keyword_sets );
+		}
+
+		foreach ( $this->accepted_embeddings as $accepted ) {
+			$sim = PRAutoBlogger_OpenRouter_Embedding_Provider::cosine_similarity( $embedding, $accepted );
+			if ( $sim >= self::SIMILARITY_THRESHOLD ) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Check if a topic is too similar to any recently published post.
+	 *
+	 * @param string   $topic          Candidate topic text.
+	 * @param string[] $topic_keywords Pre-extracted keywords (for fallback).
+	 *
+	 * @return bool True if a recent post is semantically too similar.
+	 */
+	public function is_recent_duplicate( string $topic, array $topic_keywords ): bool {
+		if ( ! $this->embeddings_available || empty( $this->title_embeddings ) ) {
+			return $this->keyword_matches_recent( $topic_keywords );
+		}
+
+		$embedding = $this->embed_single( $topic );
+		if ( null === $embedding ) {
+			return $this->keyword_matches_recent( $topic_keywords );
+		}
+
+		foreach ( $this->title_embeddings as $i => $title_emb ) {
+			$sim = PRAutoBlogger_OpenRouter_Embedding_Provider::cosine_similarity( $embedding, $title_emb );
+			if ( $sim >= self::SIMILARITY_THRESHOLD ) {
+				PRAutoBlogger_Logger::instance()->info(
+					sprintf(
+						'Semantic match (%.2f): "%s" ≈ "%s"',
+						$sim,
+						substr( $topic, 0, 60 ),
+						substr( $this->recent_titles[ $i ] ?? '', 0, 60 )
+					),
+					'scorer'
+				);
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Record an accepted idea's embedding for intra-batch dedup.
+	 *
+	 * @param string $topic The accepted topic text.
+	 */
+	public function record_accepted( string $topic ): void {
+		if ( ! $this->embeddings_available ) {
+			return;
+		}
+		$embedding = $this->embed_single( $topic );
+		if ( null !== $embedding ) {
+			$this->accepted_embeddings[] = $embedding;
+		}
+	}
+
+	// ── Private helpers ─────────────────────────────────────────────────
+
+	/**
+	 * Embed a single text, with error handling.
+	 *
+	 * @param string $text Text to embed.
+	 * @return float[]|null Embedding vector, or null on failure.
+	 */
+	private function embed_single( string $text ): ?array {
+		try {
+			if ( null === $this->provider ) {
+				$this->provider = new PRAutoBlogger_OpenRouter_Embedding_Provider();
+			}
+			$result = $this->provider->get_embeddings( array( $text ) );
+			return $result[0] ?? null;
+		} catch ( \Throwable $e ) {
+			// Degrade gracefully — one failed embed shouldn't kill the pipeline.
+			$this->embeddings_available = false;
+			PRAutoBlogger_Logger::instance()->warning(
+				'Embedding failed, disabling semantic dedup for this run: ' . $e->getMessage(),
+				'scorer'
+			);
+			return null;
+		}
+	}
+
+	/**
+	 * Keyword-overlap fallback for intra-batch dedup.
+	 *
+	 * @param string[] $keywords     Keywords to check.
+	 * @param array    $keyword_sets List of previously accepted keyword arrays.
+	 * @return bool
+	 */
+	private function keyword_overlaps_any( array $keywords, array $keyword_sets ): bool {
+		if ( count( $keywords ) < 2 ) {
+			return false;
+		}
+		foreach ( $keyword_sets as $existing ) {
+			$overlap = count( array_intersect( $keywords, $existing ) );
+			if ( $overlap / count( $keywords ) >= 0.6 ) {
+				return true;
+			}
+		}
+		return false;
+	}
+
+	/**
+	 * Keyword-overlap fallback for recent-post dedup.
+	 *
+	 * @param string[] $topic_keywords Pre-extracted keywords.
+	 * @return bool
+	 */
+	private function keyword_matches_recent( array $topic_keywords ): bool {
+		if ( count( $topic_keywords ) < 2 ) {
+			return false;
+		}
+		foreach ( $this->recent_titles as $title ) {
+			$title_keywords = $this->extract_meaningful_keywords( $title );
+			$overlap        = count( array_intersect( $topic_keywords, $title_keywords ) );
+			if ( $overlap / count( $topic_keywords ) >= 0.6 ) {
+				return true;
+			}
+		}
+		return false;
+	}
+
+	/**
+	 * Fetch titles of generated posts from the last 30 days.
+	 *
+	 * Widened from 7 days (the old keyword window) because semantic similarity
+	 * catches rephrasings that keywords miss — a wider net is safe here.
+	 *
+	 * @return string[]
+	 */
+	private function fetch_recent_post_titles(): array {
+		$query = new \WP_Query(
+			array(
+				'post_type'      => 'post',
+				'post_status'    => array( 'publish', 'draft', 'pending' ),
+				'meta_key'       => '_prautoblogger_generated',
+				'meta_value'     => '1',
+				'date_query'     => array( array( 'after' => '30 days ago' ) ),
+				'posts_per_page' => 100,
+				'fields'         => 'ids',
+				'no_found_rows'  => true,
+			)
+		);
+
+		$titles = array();
+		foreach ( $query->posts as $post_id ) {
+			$titles[] = get_the_title( $post_id );
+		}
+		return $titles;
+	}
+
+	/**
+	 * Extract meaningful keywords from text (fallback dedup).
+	 *
+	 * @param string $text Input text.
+	 * @return string[] Unique lowercase keywords.
+	 */
+	private function extract_meaningful_keywords( string $text ): array {
+		static $stopwords = array(
+			'a',
+			'an',
+			'the',
+			'and',
+			'or',
+			'but',
+			'is',
+			'are',
+			'was',
+			'were',
+			'in',
+			'on',
+			'at',
+			'to',
+			'for',
+			'of',
+			'with',
+			'by',
+			'from',
+			'as',
+			'it',
+			'its',
+			'this',
+			'that',
+			'your',
+			'you',
+			'how',
+			'what',
+			'when',
+			'why',
+			'where',
+			'which',
+			'who',
+			'do',
+			'does',
+			'did',
+			'not',
+			'no',
+			'can',
+			'will',
+			'should',
+			'could',
+			'would',
+			'may',
+			'might',
+			'have',
+			'has',
+			'had',
+			'be',
+			'been',
+			'being',
+			'about',
+			'into',
+			'through',
+			'during',
+			'before',
+			'after',
+			'above',
+			'below',
+			'between',
+			'same',
+			'up',
+			'down',
+			'out',
+			'off',
+			'over',
+			'under',
+			'again',
+			'then',
+			'here',
+			'there',
+			'all',
+			'each',
+			'every',
+			'both',
+			'few',
+			'more',
+			'most',
+			'other',
+			'some',
+			'such',
+			'than',
+			'too',
+			'very',
+			'just',
+			'also',
+			'only',
+			'own',
+			'so',
+			'if',
+			'while',
+			'because',
+			'until',
+			'vs',
+			'versus',
+			'guide',
+			'complete',
+			'ultimate',
+			'best',
+			'top',
+			'new',
+			'first',
+			'need',
+			'know',
+			'everything',
+		);
+
+		$text  = strtolower( $text );
+		$words = preg_split( '/[^a-z0-9-]+/', $text, -1, PREG_SPLIT_NO_EMPTY );
+		$words = array_filter(
+			$words,
+			static function ( string $w ) use ( $stopwords ): bool {
+				return strlen( $w ) >= 2 && ! in_array( $w, $stopwords, true );
+			}
+		);
+
+		return array_values( array_unique( $words ) );
+	}
+}

includes/core/class-source-collector.php

@@ -2,21 +2,44 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Orchestrates data collection from all enabled source providers.
  *
- * Iterates through enabled sources (currently Reddit), calls their
+ * Iterates through enabled sources (Reddit, LLM Research), calls their
  * collect_data() method, and stores results in the ab_source_data table.
  * Handles deduplication via UNIQUE index on (source_type, source_id).
+ * Re-seen items get their collected_at timestamp refreshed so the
+ * analyzer's 24-hour window picks them up for re-analysis.
  *
  * Triggered by: PRAutoBlogger::run_generation_pipeline() (step 1).
  * Dependencies: Source provider implementations, WordPress $wpdb.
  *
  * @see providers/interface-source-provider.php — Interface providers implement.
- * @see providers/class-reddit-provider.php     — Primary source provider.
+ * @see providers/class-reddit-provider.php       — Reddit source provider.
+ * @see providers/class-llm-research-provider.php — LLM deep research provider.
  * @see ARCHITECTURE.md                         — Data flow step 1.
  */
 class PRAutoBlogger_Source_Collector {
 
+	/**
+	 * Pipeline cost tracker — passed to providers that need run_id tagging.
+	 * Null when called outside the pipeline (e.g., manual test collection).
+	 */
+	private ?PRAutoBlogger_Cost_Tracker $cost_tracker = null;
+
+	/**
+	 * Inject the pipeline's cost tracker so source providers can log costs
+	 * with the correct run_id. Without this, provider costs are orphaned.
+	 *
+	 * @param PRAutoBlogger_Cost_Tracker $cost_tracker Pipeline cost tracker with run_id set.
+	 * @return $this
+	 */
+	public function set_cost_tracker( PRAutoBlogger_Cost_Tracker $cost_tracker ): self {
+		$this->cost_tracker = $cost_tracker;
+		return $this;
+	}
+
 	/**
 	 * Collect data from all enabled source providers and store in database.
 	 *
@@ -25,9 +48,12 @@ class PRAutoBlogger_Source_Collector {
 	 * @return int Total number of new records inserted.
 	 */
 	public function collect_from_all_sources(): int {
-		$enabled = json_decode( get_option( 'prautoblogger_enabled_sources', '["reddit"]' ), true );
+		$raw     = get_option( 'prautoblogger_enabled_sources', '["reddit"]' );
+		$enabled = json_decode( (string) $raw, true );
+		// Only fall back to reddit if the option is corrupt (non-JSON).
+		// An empty array '[]' is a valid choice — the user disabled all sources.
 		if ( ! is_array( $enabled ) ) {
-			$enabled = [ 'reddit' ];
+			$enabled = array( 'reddit' );
 		}
 
 		$total_inserted = 0;
@@ -40,33 +66,104 @@ class PRAutoBlogger_Source_Collector {
 			}
 
 			try {
-				$data     = $provider->collect_data( $this->get_config_for_source( $source_type ) );
-				$inserted = $this->store_data( $data );
+				$data            = $provider->collect_data( $this->get_config_for_source( $source_type ) );
+				$inserted        = $this->store_data( $data );
+				$refreshed       = count( $data ) - $inserted;
 				$total_inserted += $inserted;
 
 				PRAutoBlogger_Logger::instance()->info(
-					sprintf( 'Collected %d items from %s (%d new).', count( $data ), $source_type, $inserted ),
+					sprintf( 'Collected %d items from %s (%d new, %d refreshed).', count( $data ), $source_type, $inserted, $refreshed ),
 					'collector'
 				);
-			} catch ( \Exception $e ) {
-				PRAutoBlogger_Logger::instance()->error( "Collection from {$source_type} FAILED: " . $e->getMessage(), 'collector' );
-				// Continue with other sources — one failure shouldn't stop everything.
+			} catch ( \Throwable $e ) {
+				// Structured failure meta: model slug, HTTP status (parsed from message),
+				// and first ~200 chars of the error body — enables post-incident diagnosis
+				// without needing to re-run the failing collection. Added v0.18.2.
+				$config_for_log = $this->get_config_for_source( $source_type );
+				$model_slug     = (string) ( $config_for_log['model'] ?? '' );
+				$err_msg        = $e->getMessage();
+				// Extract HTTP status from "OpenRouter API error (HTTP NNN): ..." pattern.
+				$http_status = 0;
+				if ( preg_match( '/HTTP (\d{3})/', $err_msg, $m ) ) {
+					$http_status = (int) $m[1];
+				}
+				PRAutoBlogger_Logger::instance()->error(
+					sprintf(
+						'Collection %s from %s: %s',
+						get_class( $e ),
+						$source_type,
+						$e->getMessage()
+					),
+					'collector',
+					array(
+						'source'      => $source_type,
+						'model'       => $model_slug,
+						'http_status' => $http_status,
+						'error_body'  => mb_substr( $err_msg, 0, 200 ),
+					)
+				);
+				// Continue with other sources — one failure should not stop everything.
 			}
 		}
 
 		return $total_inserted;
 	}
 
+	/**
+	 * Retrieve source data rows by their database IDs.
+	 *
+	 * Used by the image pipeline to build Image B's source-driven prompt from
+	 * the source_ids stored on the Article_Idea. Returns the first matching
+	 * row's title and content; these map directly to what
+	 * Image_Prompt_Builder::build_source_prompt() expects.
+	 *
+	 * Side effects: one SELECT query.
+	 *
+	 * @param int[] $ids Database row IDs from the source_data table.
+	 * @return array{title: string, selftext: string}|null First source row, or null if none found.
+	 */
+	public function get_source_data_for_image( array $ids ): ?array {
+		if ( empty( $ids ) ) {
+			return null;
+		}
+
+		global $wpdb;
+		$table        = $wpdb->prefix . 'prautoblogger_source_data';
+		$placeholders = implode( ',', array_fill( 0, count( $ids ), '%d' ) );
+
+		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.PreparedSQLPlaceholders.UnfinishedPrepare
+		$row = $wpdb->get_row(
+			$wpdb->prepare(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+				"SELECT title, content, subreddit FROM {$table} WHERE id IN ({$placeholders}) ORDER BY score DESC LIMIT 1",
+				...$ids
+			),
+			ARRAY_A
+		);
+
+		if ( null === $row ) {
+			return null;
+		}
+
+		return array(
+			'title'    => $row['title'] ?? 'Reddit Discussion',
+			'selftext' => $row['content'] ?? '',
+		);
+	}
+
 	/**
 	 * Store collected source data in the database.
 	 *
-	 * Uses INSERT IGNORE to handle duplicates gracefully (UNIQUE index).
+	 * Uses INSERT … ON DUPLICATE KEY UPDATE so that re-seen items refresh
+	 * their collected_at timestamp (plus score/comment_count which change
+	 * on Reddit over time). Without this, items that age past the
+	 * analyzer's 24-hour window would never be re-analyzed even though
+	 * they keep appearing in the RSS feed.
 	 *
-	 * Side effects: database inserts.
+	 * Side effects: database inserts/updates.
 	 *
 	 * @param PRAutoBlogger_Source_Data[] $items
 	 *
-	 * @return int Number of new records inserted.
+	 * @return int Number of new records inserted (updates not counted).
 	 */
 	private function store_data( array $items ): int {
 		global $wpdb;
@@ -76,13 +173,18 @@ class PRAutoBlogger_Source_Collector {
 		foreach ( $items as $item ) {
 			$row = $item->to_db_row();
 
-			// Use INSERT IGNORE so duplicate (source_type, source_id) pairs are silently skipped.
+			// Upsert: insert new items, refresh timestamps on duplicates so
+			// the analyzer's 24-hour window picks them up again.
 			// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
 			$result = $wpdb->query(
-				$wpdb->prepare(
-					"INSERT IGNORE INTO {$table}
+				$wpdb->prepare(  // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+					"INSERT INTO {$table}
 					(source_type, source_id, subreddit, title, content, author, score, comment_count, permalink, collected_at, metadata_json)
-					VALUES (%s, %s, %s, %s, %s, %s, %d, %d, %s, %s, %s)",
+					VALUES (%s, %s, %s, %s, %s, %s, %d, %d, %s, %s, %s)
+					ON DUPLICATE KEY UPDATE
+						collected_at  = VALUES(collected_at),
+						score         = VALUES(score),
+						comment_count = VALUES(comment_count)",
 					$row['source_type'],
 					$row['source_id'],
 					$row['subreddit'],
@@ -97,8 +199,10 @@ class PRAutoBlogger_Source_Collector {
 				)
 			);
 
-			if ( false !== $result && $result > 0 ) {
-				$inserted++;
+			// ON DUPLICATE KEY UPDATE returns 2 for updates, 1 for inserts.
+			// Only count genuine inserts toward the "new" tally.
+			if ( false !== $result && 1 === (int) $result ) {
+				++$inserted;
 			}
 		}
 
@@ -113,10 +217,10 @@ class PRAutoBlogger_Source_Collector {
 	 * @return PRAutoBlogger_Source_Provider_Interface|null
 	 */
 	private function get_provider( string $source_type ): ?PRAutoBlogger_Source_Provider_Interface {
-		$providers = [
-			'reddit' => PRAutoBlogger_Reddit_Provider::class,
-			// New providers can be added here — see CONVENTIONS.md for how-to.
-		];
+		$providers = array(
+			'reddit'       => PRAutoBlogger_Reddit_Provider::class,
+			'llm_research' => PRAutoBlogger_LLM_Research_Provider::class,
+		);
 
 		/**
 		 * Filter the registered source providers.
@@ -153,15 +257,28 @@ class PRAutoBlogger_Source_Collector {
 	 */
 	private function get_config_for_source( string $source_type ): array {
 		if ( 'reddit' === $source_type ) {
-			return [
-				'subreddits'       => json_decode( get_option( 'prautoblogger_target_subreddits', '[]' ), true ) ?: [],
-				'limit'            => 25,
-				'time_filter'      => 'day',
-				'include_comments' => true,
+			return array(
+				'subreddits'        => json_decode( get_option( 'prautoblogger_target_subreddits', '[]' ), true ) ?? array(),
+				'limit'             => 25,
+				'time_filter'       => 'day',
+				'include_comments'  => true,
 				'comments_per_post' => 10,
-			];
+			);
 		}
 
-		return [];
+		if ( 'llm_research' === $source_type ) {
+			$config = array(
+				'model'  => get_option( 'prautoblogger_research_model', PRAUTOBLOGGER_DEFAULT_ANALYSIS_MODEL ),
+				'prompt' => get_option( 'prautoblogger_research_prompt', '' ),
+			);
+			// Pass the pipeline's cost tracker so research costs get tagged
+			// with the run_id for post-pipeline amortization across articles.
+			if ( null !== $this->cost_tracker ) {
+				$config['cost_tracker'] = $this->cost_tracker;
+			}
+			return $config;
+		}
+
+		return array();
 	}
 }

includes/core/class-stage-display-map.php

@@ -0,0 +1,172 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Display map for every generation_log / run_stages `stage` value, old and new.
+ *
+ * What: Single source of truth that renders historical stage values
+ *       (analysis, outline, draft, polish, review, llm_research, image_a,
+ *       image_b, image_prompt_rewrite, opik_eval_judge), the Pipeline v2
+ *       vocabulary (research, curate, draft, editorial, seo, publish), and
+ *       any unknown value (humanized fallback) coherently. Also maps each
+ *       stage to its default agent role and primary prompt-registry key so
+ *       audit stamping never hardcodes those associations at call sites.
+ *       The `stage` column is VARCHAR — this PHP map is the vocabulary,
+ *       there is no SQL enum.
+ * Who triggers it: Cost_Tracker (stamping), audit/metrics rendering, Run_State.
+ * Dependencies: none — pure static lookup.
+ *
+ * @see core/class-cost-tracker.php    — Derives agent_role / prompt key when not passed.
+ * @see core/class-prompt-registry.php — Owns the prompt keys referenced here.
+ * @see ARCHITECTURE.md                — Stage vocabulary (canonical edit-stage name: polish).
+ */
+class PRAutoBlogger_Stage_Display_Map {
+
+	/**
+	 * Stage definitions: label (translated lazily), default agent role,
+	 * and the primary prompt-registry key the stage renders with (null
+	 * when the stage has no registry-managed prompt).
+	 *
+	 * @var array<string, array{label: string, role: ?string, prompt_key: ?string}>
+	 */
+	private const MAP = array(
+		// ── Historical vocabulary (rows that exist on prod) ─────────────
+		'analysis'             => array(
+			'label'      => 'Topic Analysis',
+			'role'       => 'analyst',
+			'prompt_key' => 'analysis.system',
+		),
+		'outline'              => array(
+			'label'      => 'Outline',
+			'role'       => 'writer',
+			'prompt_key' => 'content.outline',
+		),
+		'draft'                => array(
+			'label'      => 'Draft',
+			'role'       => 'writer',
+			'prompt_key' => 'content.draft',
+		),
+		'polish'               => array(
+			'label'      => 'Polish',
+			'role'       => 'writer',
+			'prompt_key' => 'content.polish',
+		),
+		'review'               => array(
+			'label'      => 'Editorial Review',
+			'role'       => 'editor',
+			'prompt_key' => 'editor.system',
+		),
+		'llm_research'         => array(
+			'label'      => 'LLM Research',
+			'role'       => 'researcher',
+			'prompt_key' => 'research.system',
+		),
+		'image_a'              => array(
+			'label'      => 'Image A',
+			'role'       => 'illustrator',
+			'prompt_key' => 'image.style_template',
+		),
+		'image_b'              => array(
+			'label'      => 'Image B',
+			'role'       => 'illustrator',
+			'prompt_key' => 'image.style_template',
+		),
+		'image_prompt_rewrite' => array(
+			'label'      => 'Image Prompt Rewrite',
+			'role'       => 'illustrator',
+			'prompt_key' => 'image.rewriter_system',
+		),
+		'opik_eval_judge'      => array(
+			'label'      => 'Opik Eval Judge',
+			'role'       => 'judge',
+			'prompt_key' => null,
+		),
+		// ── Pipeline v2 vocabulary (new runs may write these) ───────────
+		'research'             => array(
+			'label'      => 'Research',
+			'role'       => 'researcher',
+			'prompt_key' => 'research.system',
+		),
+		'curate'               => array(
+			'label'      => 'Curate',
+			'role'       => 'curator',
+			'prompt_key' => null,
+		),
+		'editorial'            => array(
+			'label'      => 'Editorial Loop',
+			'role'       => 'editor',
+			'prompt_key' => null,
+		),
+		'seo'                  => array(
+			'label'      => 'SEO',
+			'role'       => 'seo',
+			'prompt_key' => null,
+		),
+		'publish'              => array(
+			'label'      => 'Publish',
+			'role'       => 'publisher',
+			'prompt_key' => null,
+		),
+	);
+
+	/**
+	 * Human-readable label for a stage value. Unknown stages are humanized
+	 * (underscores to spaces, words capitalized) so the audit view never
+	 * renders blank for a value this map predates or postdates.
+	 *
+	 * @param string $stage Raw stage value from the database.
+	 * @return string Translated display label.
+	 */
+	public static function label( string $stage ): string {
+		if ( isset( self::MAP[ $stage ] ) ) {
+			// phpcs:ignore WordPress.WP.I18n.NonSingularStringLiteralText -- labels are a fixed const set.
+			return __( self::MAP[ $stage ]['label'], 'prautoblogger' );
+		}
+		return ucwords( str_replace( array( '_', '-' ), ' ', $stage ) );
+	}
+
+	/**
+	 * Default agent role recorded for a stage when the call site does not
+	 * pass one explicitly. Null for unknown stages (column stays NULL).
+	 *
+	 * @param string $stage Raw stage value.
+	 * @return string|null Agent role slug, or null when unknown.
+	 */
+	public static function default_agent_role( string $stage ): ?string {
+		return self::MAP[ $stage ]['role'] ?? null;
+	}
+
+	/**
+	 * Primary prompt-registry key a stage renders with. Used to resolve the
+	 * pinned prompt_version stamped on generation_log rows when the call
+	 * site does not pass an explicit key (e.g. single-pass passes
+	 * 'content.single_pass' for its 'draft' row).
+	 *
+	 * @param string $stage Raw stage value.
+	 * @return string|null Registry key, or null when the stage has none.
+	 */
+	public static function default_prompt_key( string $stage ): ?string {
+		return self::MAP[ $stage ]['prompt_key'] ?? null;
+	}
+
+	/**
+	 * Whether the stage value is part of the known vocabulary.
+	 *
+	 * @param string $stage Raw stage value.
+	 * @return bool True when the stage is a known historical or v2 value.
+	 */
+	public static function is_known( string $stage ): bool {
+		return isset( self::MAP[ $stage ] );
+	}
+
+	/**
+	 * The full vocabulary, for audit listings and tests.
+	 *
+	 * @return array<string, array{label: string, role: ?string, prompt_key: ?string}>
+	 */
+	public static function all(): array {
+		return self::MAP;
+	}
+}

includes/core/interface-image-composer.php

@@ -0,0 +1,50 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Contract for image composers that turn raw provider bytes into final variants.
+ *
+ * A composer sits between the image provider (raw generated bytes) and the
+ * media sideloader. It receives one base image plus per-post context and
+ * returns one or more finished variants — the first is always the `featured`
+ * role (the bytes that become the post thumbnail), optionally followed by
+ * social variants (`og`, `square`). Implementations must NEVER throw out of
+ * compose(): on any internal failure they degrade to passing the base image
+ * through unmodified so publishing is never blocked.
+ *
+ * Triggered by: PRAutoBlogger_Image_Pipeline between batch results and sideload.
+ * Dependencies: none — this is the contract only.
+ *
+ * @see core/class-image-composer.php  — Default implementation (capability ladder).
+ * @see core/class-image-pipeline.php  — Caller.
+ * @see core/class-image-attacher.php  — Persists the returned variants.
+ */
+interface PRAutoBlogger_Image_Composer_Interface {
+
+	/**
+	 * Compose final image variant(s) from raw provider bytes.
+	 *
+	 * Side effects: implementations may read plugin options and write to the
+	 * activity log; they must not make network calls or fail the publish.
+	 *
+	 * @param array{
+	 *     bytes: string,
+	 *     mime_type: string,
+	 *     width: int,
+	 *     height: int,
+	 * } $image_data Base image bytes + metadata from the provider result.
+	 * @param array{
+	 *     post_id: int,
+	 *     caption: string,
+	 *     title: string,
+	 *     slot: string,
+	 * } $context Post ID, editorial caption, post title, and slot
+	 *            ('image_a' or 'image_b'); only image_a yields variants.
+	 *
+	 * @return array<int, array{bytes: string, mime_type: string, width: int, height: int, role: string}>
+	 *               Non-empty list; index 0 always carries role 'featured'.
+	 */
+	public function compose( array $image_data, array $context ): array;
+}

includes/frontend/class-article-typography.php

@@ -0,0 +1,264 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
+ * Injects frontend typography and table styles for PRAutoBlogger-generated posts.
+ *
+ * What: Outputs inline CSS on all single post pages, applying
+ *       user-configured font family, font size, and table border
+ *       styles from the Display admin settings.
+ * Who calls it: PRAutoBlogger::register_frontend_hooks() hooks this
+ *               into wp_head.
+ * Dependencies: Reads wp_options for typography settings.
+ *
+ * @see class-prautoblogger.php       — Registers the wp_head hook.
+ * @see class-settings-fields.php     — Defines the Display settings section.
+ * @see admin/class-admin-page.php    — Renders the settings form.
+ */
+class PRAutoBlogger_Article_Typography {
+
+	/** Option key for article font family. */
+	private const OPT_FONT_FAMILY = 'prautoblogger_article_font_family';
+
+	/** Option key for article body font size in pixels. */
+	private const OPT_FONT_SIZE = 'prautoblogger_article_font_size';
+
+	/** Option key for table border toggle. */
+	private const OPT_TABLE_BORDERS = 'prautoblogger_table_borders';
+
+	/**
+	 * Output inline CSS in <head> for single post pages.
+	 *
+	 * Applies to all posts — typography settings are site-wide.
+	 * The CSS targets .entry-content (PR Theme's article body class)
+	 * and overrides the theme's CSS custom properties so the cascade
+	 * works naturally with headings and sub-elements.
+	 *
+	 * Side effects: echoes a <style> block.
+	 *
+	 * @return void
+	 */
+	public function on_wp_head(): void {
+		if ( ! is_singular( 'post' ) ) {
+			return;
+		}
+
+		$css = $this->build_css();
+		if ( '' === $css ) {
+			return;
+		}
+
+		printf(
+			"\n<style id=\"prautoblogger-typography\">\n%s\n</style>\n",
+			$css // Already escaped — contains only sanitized option values.
+		);
+	}
+
+	/**
+	 * Build the CSS string from current settings.
+	 *
+	 * Reads each setting at call time (never cached) so changes
+	 * take effect immediately without cache invalidation.
+	 *
+	 * @return string CSS rules, or empty string if all defaults.
+	 */
+	private function build_css(): string {
+		$rules = array();
+
+		$font_family = $this->get_font_family_stack();
+		if ( '' !== $font_family ) {
+			$rules[] = sprintf(
+				".entry-content,\n.entry-content p,\n.entry-content li {\n\tfont-family: %s;\n}",
+				$font_family
+			);
+		}
+
+		$font_size = absint( get_option( self::OPT_FONT_SIZE, 0 ) );
+		if ( $font_size > 0 ) {
+			$rules[] = sprintf(
+				".entry-content,\n.entry-content p,\n.entry-content li {\n\tfont-size: %dpx;\n\tline-height: 1.7;\n}",
+				$font_size
+			);
+		}
+
+		// Restore bullet points — the theme's global reset strips
+		// list-style from all ul/ol, which removes bullets from article
+		// content. This re-applies them inside .entry-content only.
+		$rules[] = implode(
+			"\n",
+			array(
+				'.entry-content ul {',
+				"\tlist-style: disc;",
+				"\tpadding-left: 1.5em;",
+				"\tmargin: 1em 0;",
+				'}',
+				'.entry-content ol {',
+				"\tlist-style: decimal;",
+				"\tpadding-left: 1.5em;",
+				"\tmargin: 1em 0;",
+				'}',
+				'.entry-content li {',
+				"\tmargin-bottom: 0.4em;",
+				'}',
+			)
+		);
+
+		$table_borders = get_option( self::OPT_TABLE_BORDERS, '1' );
+		if ( '1' === $table_borders ) {
+			// Uses theme CSS custom properties for dark mode compatibility.
+			// --color-border-default, --color-bg-secondary, --color-bg-primary,
+			// --color-text-primary are set by PR Theme for both light and dark.
+			$rules[] = implode(
+				"\n",
+				array(
+					'.entry-content .prab-table-wrap {',
+					"\toverflow-x: auto;",
+					"\t-webkit-overflow-scrolling: touch;",
+					"\tmargin: 1.5em 0;",
+					'}',
+					'.entry-content table {',
+					"\tborder-collapse: collapse;",
+					"\twidth: 100%;",
+					"\tmin-width: 480px;",
+					'}',
+					'.entry-content th,',
+					'.entry-content td {',
+					"\tborder: 1px solid var(--color-border-default, #d1d5db);",
+					"\tpadding: 0.6em 1em;",
+					"\ttext-align: left;",
+					"\tcolor: var(--color-text-primary, #111827);",
+					'}',
+					'.entry-content thead th {',
+					"\tbackground: var(--color-bg-secondary, #f3f4f6);",
+					"\tfont-weight: 600;",
+					'}',
+					'.entry-content tbody tr:nth-child(even) {',
+					"\tbackground: var(--color-bg-secondary, #f9fafb);",
+					'}',
+					'@media (max-width: 600px) {',
+					"\t.entry-content th,",
+					"\t.entry-content td {",
+					"\t\tpadding: 0.4em 0.6em;",
+					"\t\tfont-size: 14px;",
+					"\t}",
+					'}',
+				)
+			);
+		}
+
+		return implode( "\n\n", $rules );
+	}
+
+	/**
+	 * Map the stored font-family key to a full CSS font stack.
+	 *
+	 * Returns empty string for 'default' (let the theme decide).
+	 *
+	 * @return string CSS font-family value, or empty for theme default.
+	 */
+	private function get_font_family_stack(): string {
+		$key = sanitize_text_field( get_option( self::OPT_FONT_FAMILY, 'default' ) );
+
+		$stacks = array(
+			'default'      => '',
+			'inter'        => '"Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+			'georgia'      => '"Georgia", "Times New Roman", Times, serif',
+			'merriweather' => '"Merriweather", Georgia, "Times New Roman", serif',
+			'lora'         => '"Lora", Georgia, "Times New Roman", serif',
+			'open_sans'    => '"Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+			'roboto'       => '"Roboto", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+			'system'       => '-apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", sans-serif',
+		);
+
+		return $stacks[ $key ] ?? '';
+	}
+
+	/**
+	 * Get available font choices for the settings UI.
+	 *
+	 * @return array<string, string> Map of key => display label.
+	 */
+	public static function get_font_choices(): array {
+		return array(
+			'default'      => __( 'Theme Default (Inter)', 'prautoblogger' ),
+			'inter'        => __( 'Inter (Sans-serif)', 'prautoblogger' ),
+			'georgia'      => __( 'Georgia (Serif)', 'prautoblogger' ),
+			'merriweather' => __( 'Merriweather (Serif)', 'prautoblogger' ),
+			'lora'         => __( 'Lora (Serif)', 'prautoblogger' ),
+			'open_sans'    => __( 'Open Sans (Sans-serif)', 'prautoblogger' ),
+			'roboto'       => __( 'Roboto (Sans-serif)', 'prautoblogger' ),
+			'system'       => __( 'System Default', 'prautoblogger' ),
+		);
+	}
+
+	/**
+	 * Enqueue Google Fonts stylesheet when a web font is selected.
+	 *
+	 * Only loads on singular post pages that use a Google-hosted font.
+	 *
+	 * Side effects: enqueues a remote stylesheet.
+	 *
+	 * @return void
+	 */
+	public function on_enqueue_fonts(): void {
+		if ( ! is_singular( 'post' ) ) {
+			return;
+		}
+
+		$font = sanitize_text_field( get_option( self::OPT_FONT_FAMILY, 'default' ) );
+
+		// Map font keys to Google Fonts URLs. Inter is already loaded by the theme.
+		$google_fonts = array(
+			'merriweather' => 'https://fonts.googleapis.com/css2?family=Merriweather:wght@400;700&display=swap',
+			'lora'         => 'https://fonts.googleapis.com/css2?family=Lora:wght@400;700&display=swap',
+			'open_sans'    => 'https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;600;700&display=swap',
+			'roboto'       => 'https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap',
+		);
+
+		if ( isset( $google_fonts[ $font ] ) ) {
+			wp_enqueue_style(
+				'prautoblogger-google-font',
+				$google_fonts[ $font ],
+				array(),
+				null // No version for external CDN URLs.
+			);
+		}
+	}
+
+	/**
+	 * Wrap bare <table> elements in a scrollable container for mobile.
+	 *
+	 * Tables wider than the viewport break mobile layouts. This wraps
+	 * each <table> not already inside a wrapper in a
+	 * <div class="prab-table-wrap"> that enables horizontal scrolling.
+	 *
+	 * Only runs on singular post pages.
+	 *
+	 * Side effects: modifies post HTML content via the_content filter.
+	 *
+	 * @param string $content Post HTML content.
+	 * @return string Modified content with tables wrapped.
+	 */
+	public function on_wrap_tables( string $content ): string {
+		if ( ! is_singular( 'post' ) ) {
+			return $content;
+		}
+
+		if ( '1' !== get_option( self::OPT_TABLE_BORDERS, '1' ) ) {
+			return $content;
+		}
+
+		// Wrap <table> elements not already inside a .prab-table-wrap.
+		return (string) preg_replace(
+			'/(?<!prab-table-wrap">)\s*(<table[\s>])/i',
+			'<div class="prab-table-wrap">$1',
+			(string) preg_replace(
+				'/<\/table>\s*/i',
+				'</table></div>',
+				$content
+			)
+		);
+	}
+}

includes/frontend/class-posts-widget.php

@@ -2,6 +2,8 @@
 declare(strict_types=1);
 
 /**
+ * phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
+ *
  * Registers the [prautoblogger_posts] shortcode and its supporting REST API endpoint.
  *
  * This is PRAutoBlogger's first public-facing frontend feature. It renders a React-powered
@@ -43,7 +45,7 @@ class PRAutoBlogger_Posts_Widget {
 	 * @return void
 	 */
 	public function on_register_shortcode(): void {
-		add_shortcode( 'prautoblogger_posts', [ $this, 'render_shortcode' ] );
+		add_shortcode( 'prautoblogger_posts', array( $this, 'render_shortcode' ) );
 	}
 
 	/**
@@ -59,9 +61,9 @@ class PRAutoBlogger_Posts_Widget {
 		register_rest_route(
 			self::REST_NAMESPACE,
 			self::REST_ROUTE,
-			[
+			array(
 				'methods'             => \WP_REST_Server::READABLE,
-				'callback'            => [ $this, 'handle_rest_request' ],
+				'callback'            => array( $this, 'handle_rest_request' ),
 				'permission_callback' => function () {
 					/**
 					 * Filter whether the posts widget REST endpoint is publicly accessible.
@@ -73,21 +75,21 @@ class PRAutoBlogger_Posts_Widget {
 					 */
 					return (bool) apply_filters( 'prautoblogger_rest_posts_public', true );
 				},
-				'args'                => [
-					'per_page' => [
+				'args'                => array(
+					'per_page' => array(
 						'type'              => 'integer',
 						'default'           => 6,
 						'minimum'           => 1,
 						'maximum'           => self::MAX_POSTS_PER_REQUEST,
 						'sanitize_callback' => 'absint',
-					],
-					'category' => [
+					),
+					'category' => array(
 						'type'              => 'string',
 						'default'           => '',
 						'sanitize_callback' => 'sanitize_text_field',
-					],
-				],
-			]
+					),
+				),
+			)
 		);
 	}
 
@@ -109,12 +111,12 @@ class PRAutoBlogger_Posts_Widget {
 	 */
 	public function render_shortcode( $atts ): string {
 		$atts = shortcode_atts(
-			[
+			array(
 				'count'    => '6',
 				'category' => '',
 				'title'    => __( 'Latest Research & Insights', 'prautoblogger' ),
 				'subtitle' => __( 'Evidence-based articles on peptides, protocols, and emerging research', 'prautoblogger' ),
-			],
+			),
 			$atts,
 			'prautoblogger_posts'
 		);
@@ -148,14 +150,14 @@ class PRAutoBlogger_Posts_Widget {
 		wp_enqueue_style(
 			'prautoblogger-posts-widget',
 			PRAUTOBLOGGER_PLUGIN_URL . 'assets/css/posts-widget.css',
-			[],
+			array(),
 			$version
 		);
 
 		wp_enqueue_script(
 			'prautoblogger-posts-widget',
 			PRAUTOBLOGGER_PLUGIN_URL . 'assets/js/posts-widget.js',
-			[ 'wp-element' ], // WordPress-bundled React.
+			array( 'wp-element' ), // WordPress-bundled React.
 			$version,
 			true // Load in footer for performance.
 		);
@@ -163,14 +165,14 @@ class PRAutoBlogger_Posts_Widget {
 		wp_localize_script(
 			'prautoblogger-posts-widget',
 			'prabPostsWidget',
-			[
+			array(
 				'restUrl'    => esc_url_raw( rest_url( self::REST_NAMESPACE . self::REST_ROUTE ) ),
 				'count'      => $count,
 				'category'   => sanitize_text_field( $atts['category'] ),
 				'title'      => sanitize_text_field( $atts['title'] ),
 				'subtitle'   => sanitize_text_field( $atts['subtitle'] ),
-				'archiveUrl' => esc_url( get_post_type_archive_link( 'post' ) ?: '' ),
-			]
+				'archiveUrl' => esc_url( get_post_type_archive_link( 'post' ) ?? '' ),
+			)
 		);
 	}
 
@@ -191,19 +193,19 @@ class PRAutoBlogger_Posts_Widget {
 		}
 		$category = sanitize_text_field( $request->get_param( 'category' ) ?? '' );
 
-		$query_args = [
+		$query_args = array(
 			'post_type'      => 'post',
 			'post_status'    => 'publish',
 			'posts_per_page' => $per_page,
 			'orderby'        => 'date',
 			'order'          => 'DESC',
-			'meta_query'     => [
-				[
+			'meta_query'     => array(
+				array(
 					'key'   => '_prautoblogger_generated',
 					'value' => '1',
-				],
-			],
-		];
+				),
+			),
+		);
 
 		// Optional category filter.
 		if ( ! empty( $category ) ) {
@@ -211,7 +213,7 @@ class PRAutoBlogger_Posts_Widget {
 		}
 
 		$query = new \WP_Query( $query_args );
-		$posts = [];
+		$posts = array();
 
 		foreach ( $query->posts as $post ) {
 			$posts[] = $this->format_post_for_response( $post );
@@ -249,7 +251,7 @@ class PRAutoBlogger_Posts_Widget {
 		$title   = html_entity_decode( get_the_title( $post ), ENT_QUOTES | ENT_HTML5, 'UTF-8' );
 		$excerpt = html_entity_decode( get_the_excerpt( $post ), ENT_QUOTES | ENT_HTML5, 'UTF-8' );
 
-		return [
+		return array(
 			'id'             => $post->ID,
 			'title'          => $title,
 			'excerpt'        => $excerpt,
@@ -257,8 +259,8 @@ class PRAutoBlogger_Posts_Widget {
 			'date'           => get_the_date( 'c', $post ),
 			'category_name'  => $category_name,
 			'category_slug'  => $category_slug,
-			'featured_image' => $featured_image ?: '',
+			'featured_image' => $featured_image ?? '',
 			'word_count'     => $word_count,
-		];
+		);
 	}
 }