Refactor: Split cost reporting into separate class

Extract read-only reporting methods from PRAutoBlogger_Cost_Tracker into a new
PRAutoBlogger_Cost_Reporter class. This reduces Cost_Tracker from 313 to 206
lines and Reporter to 141 lines, both under the 300-line cap.

Changed files:
- Create includes/core/class-cost-reporter.php with reporting methods:
  * get_monthly_spend(): float
  * get_daily_spend(int $days = 30): array
  * get_spend_by_stage(string $start_date, string $end_date): array
  * get_budget_utilization(): float

- Update includes/core/class-cost-tracker.php:
  * Remove reporting methods
  * Update is_budget_exceeded() and would_exceed_budget() to use Cost_Reporter
  * Keep get_current_run_cost() (tracks current pipeline run only)
  * Add @see cross-reference to Cost_Reporter

- Update templates and admin classes to instantiate Cost_Reporter:
  * templates/admin/metrics-page.php
  * templates/admin/settings-page.php
  * includes/admin/class-admin-notices.php
  * includes/admin/class-dashboard-widget.php

- Split tests/unit/Core/CostTrackerTest.php:
  * Create tests/unit/Core/CostReporterTest.php for reporter methods
  * Keep run ID and budget enforcement tests in CostTrackerTest

Autoloader automatically discovers PRAutoBlogger_Cost_Reporter class.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ARCHITECTURE.md

@@ -65,6 +65,14 @@ PRAutoBlogger is a WordPress plugin that monitors social media (starting with Re
              │
              ▼
 ┌─────────────────────────┐
+│  6b. Image Pipeline     │  (commit 1b) Generates two A/B images:
+│  (optional, if enabled) │  - Image A: article-driven (featured)
+│                         │  - Image B: source-driven (post meta)
+│                         │  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)
@@ -119,6 +127,9 @@ prautoblogger/
 │   │   ├── class-content-generator.php# Writer agent — manages the generation pipeline
 │   │   ├── class-chief-editor.php     # Editor agent — LLM-powered editorial review
 │   │   ├── class-publisher.php        # Creates WordPress posts from approved content
+│   │   ├── class-image-pipeline.php   # Orchestrates A/B image generation (commit 1b)
+│   │   ├── class-image-prompt-builder.php # Generates visual prompts from article/source data
+│   │   ├── class-image-media-sideloader.php # Imports images into WordPress media library
 │   │   ├── class-cost-tracker.php     # Logs all API costs, enforces budget limits
 │   │   ├── class-logger.php           # Structured logging singleton (error/warning/info/debug)
 │   │   ├── class-pipeline-runner.php  # Orchestrates the full generation pipeline
@@ -139,6 +150,12 @@ prautoblogger/
 │   │   ├── class-cloudflare-image-support.php   # Token, account, URL, and log helpers for the CF provider
 │   │   └── (new providers go here — see CONVENTIONS.md)
 │   │
+│   ├── services/
+│   │   ├── interface-model-registry.php           # Contract for provider-specific model registries
+│   │   ├── class-openrouter-model-registry.php    # Fetches, caches, queries the OpenRouter model list
+│   │   ├── class-openrouter-model-normalizer.php  # Maps raw OpenRouter data → standardized record shape
+│   │   └── (Phase 3: class-cloudflare-workers-ai-model-registry.php)
+│   │
 │   ├── frontend/
 │   │   └── class-posts-widget.php     # [prautoblogger_posts] shortcode + REST endpoint
 │   │
@@ -347,6 +364,8 @@ All prefixed with `prautoblogger_`:
 | `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_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 |
 
 ### Post Meta
 
@@ -425,6 +444,10 @@ Each pipeline execution generates a UUID (`run_id`) that tags every `prab_genera
 ### #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.
 
+### #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-openrouter-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.
+
 ### #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.
 

CHANGELOG.md

@@ -8,13 +8,49 @@ and this project uses [Semantic Versioning](https://semver.org/).
 ## [Unreleased]
 
 ### Added
-- **Image provider: Cloudflare Workers AI (FLUX.1 family).** First commit of
+- **Image pipeline integration: wires image generation into article flow** (commit 1b).
-  the image + Instagram A/B pipeline workstream. Ships the provider, its
+  Completes the image + Instagram A/B experiment workstream by adding three
+  orchestration classes that generate and sideload two images per published post.
+  - `includes/core/class-image-pipeline.php` — Orchestrates A/B image generation:
+    generates Image A (article-driven prompt) as featured image and Image B
+    (source-driven prompt) stored in post meta `_prautoblogger_image_b_id`. Each
+    image is independently fallible; article publishes even if both fail.
+  - `includes/core/class-image-prompt-builder.php` — Synthesizes visual prompts
+    from article title + first paragraph (for Image A) and Reddit thread title +
+    top comment (for Image B). Both prompts append the CEO-locked 90s infomercial
+    style suffix from settings. Prompts kept concise (under 200 words) for FLUX.1
+    generation quality.
+  - `includes/core/class-image-media-sideloader.php` — Downloads generated image
+    bytes, creates temporary file, imports via `media_handle_sideload()`, sets alt
+    text and generation metadata (`_prautoblogger_image_*`), cleans up temp files.
+  - Settings: `prautoblogger_image_enabled` (toggle, default off) — allows users to
+    enable/disable image generation after providing Cloudflare credentials.
+  - `PRAutoBlogger_Publisher::attach_generated_images()` — New private method that
+    runs the image pipeline post-creation and sets `_thumbnail_id` (Image A) and
+    `_prautoblogger_image_b_id` (Image B) post meta. Errors are logged but do not
+    block post publication.
+  - Tests: `tests/unit/Core/ImagePipelineTest.php` (orchestration, cost tracking,
+    graceful failure modes), `tests/unit/Core/ImagePromptBuilderTest.php` (prompt
+    generation from various article/source shapes, length limits).
+- ARCHITECTURE.md: added new image pipeline step (6b) to data flow, three new files
+  to core/ section of file tree.
+
+- **OpenRouter model registry (model-picker commit 1).** Foundation for the
+  smart model picker: fetches, normalizes, and caches the OpenRouter model
+  list (`/api/v1/models` — free, unauthenticated). Daily refresh via the
+  existing `prautoblogger_daily_generation` cron hook with 12h idempotency.
+  - `includes/services/interface-model-registry.php` — Phase 3-aware contract.
+  - `includes/services/class-openrouter-model-registry.php` — fetch + cache + query.
+  - `includes/services/class-openrouter-model-normalizer.php` — raw → standardized shape.
+  - Capability vocabulary: `text→text`, `text+image→text`, `text→embedding`, etc.
+  - Zero-coupling: no PRAUTOBLOGGER_* constants inside the class — Phase 2 lift
+    into a shared Composer package requires only a namespace rename.
+  - Cost impact: $0/month (free endpoint, no LLM tokens).
+
+- **Image provider: Cloudflare Workers AI (FLUX.1 family).** Ships the provider, its
   pricing + validator helpers, four new settings fields in a new "Images"
-  admin section, and unit tests with mocked HTTP. Nothing calls the provider
+  admin section, and unit tests with mocked HTTP.
-  yet from the article pipeline — integration lands in commit 1b.
+  - `includes/providers/interface-image-provider.php` — contract for any image provider.
-  - `includes/providers/interface-image-provider.php` (adopted from the CTO's
-    uncommitted draft) — contract for any image provider.
   - `includes/providers/class-cloudflare-image-provider.php` — FLUX on Workers
     AI, direct call to `/accounts/{id}/ai/run/...` (bypassing AI Gateway per
     decision D-001); exponential-backoff retries on 429 / 5xx / network,
@@ -29,10 +65,7 @@ and this project uses [Semantic Versioning](https://semver.org/).
     90s infomercial prompt).
   - Constants: `PRAUTOBLOGGER_DEFAULT_IMAGE_MODEL`,
     `PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_SUFFIX`.
-  - Tests: `tests/unit/Providers/CloudflareImageProviderTest.php` covers
+  - Tests: `tests/unit/Providers/CloudflareImageProviderTest.php`.
-    happy path (raw bytes + JSON envelope), dimension + empty-prompt
-    validation, 4xx loud-fail without retry, unexpected response shape,
-    cost scaling across models and dimensions, and missing-token diagnostics.
 - ARCHITECTURE.md: new key decision #16 (image pipeline: Cloudflare Workers
   AI), new external API integration row, new options rows, file tree updates.
 - CONVENTIONS.md: new "How To: Add a New Image Provider" section.

includes/admin/class-admin-notices.php

@@ -5,7 +5,7 @@ declare(strict_types=1);
  * 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 +51,8 @@ class PRAutoBlogger_Admin_Notices {
 	 * @return void
 	 */
 	private function check_budget_notice(): void {
-		$cost_tracker = new PRAutoBlogger_Cost_Tracker();
+		$cost_reporter = new PRAutoBlogger_Cost_Reporter();
-		$utilization  = $cost_tracker->get_budget_utilization();
+		$utilization   = $cost_reporter->get_budget_utilization();
 
 		if ( $utilization >= 100.0 ) {
 			printf(

includes/admin/class-dashboard-widget.php

@@ -8,7 +8,7 @@ declare(strict_types=1);
  * 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.
  */
@@ -37,10 +37,10 @@ class PRAutoBlogger_Dashboard_Widget {
 	 * @return void
 	 */
 	public function render_widget(): void {
-		$cost_tracker = new PRAutoBlogger_Cost_Tracker();
+		$cost_reporter = new PRAutoBlogger_Cost_Reporter();
-		$monthly_spend = $cost_tracker->get_monthly_spend();
+		$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' );
 

includes/admin/class-settings-fields.php

@@ -336,6 +336,14 @@ class PRAutoBlogger_Settings_Fields {
 			],
 
 			// ── Images ─────────────────────────────────────────────────
+			[
+				'id'          => 'prautoblogger_image_enabled',
+				'label'       => __( 'Enable Image Generation', 'prautoblogger' ),
+				'type'        => 'toggle',
+				'section'     => 'prautoblogger_images',
+				'default'     => '0',
+				'description' => __( 'When enabled, generate two images (A/B) for each published article. Requires Cloudflare credentials.', 'prautoblogger' ),
+			],
 			[
 				'id'          => 'prautoblogger_cloudflare_ai_token',
 				'label'       => __( 'Cloudflare API Token', 'prautoblogger' ),

includes/class-autoloader.php

@@ -26,6 +26,7 @@ class PRAutoBlogger_Autoloader {
 		'providers/',
 		'models/',
 		'frontend/',
+		'services/',
 	];
 
 	/**

includes/class-prautoblogger.php

@@ -18,11 +18,11 @@ declare(strict_types=1);
  */
 class PRAutoBlogger {
 
-	/**
-	 * Whether the plugin has been initialized.
-	 */
 	private bool $initialized = false;
 
+	/** @var PRAutoBlogger_OpenRouter_Model_Registry|null Lazy-loaded singleton. */
+	private ?PRAutoBlogger_OpenRouter_Model_Registry $model_registry = null;
+
 	/**
 	 * Register all hooks and initialize the plugin.
 	 *
@@ -118,6 +118,11 @@ class PRAutoBlogger {
 	private function register_cron_hooks(): void {
 		add_action( 'prautoblogger_daily_generation', [ $this, 'on_daily_generation' ] );
 		add_action( 'prautoblogger_collect_metrics', [ $this, 'on_collect_metrics' ] );
+
+		// Model registry refresh — fires inside on_daily_generation() before the
+		// generation lock, so a stuck lock doesn't freeze the registry too.
+		$registry = $this->get_model_registry();
+		add_action( 'prautoblogger_refresh_model_registry', [ $registry, 'refresh' ] );
 	}
 
 	/** Register AJAX handlers for admin actions. */
@@ -218,6 +223,10 @@ class PRAutoBlogger {
 	 * @return void
 	 */
 	public function on_daily_generation(): void {
+		// Refresh the OpenRouter model registry (idempotent, skips if <12h old).
+		// Fires BEFORE the generation lock so a stuck lock doesn't block the refresh.
+		do_action( 'prautoblogger_refresh_model_registry', false );
+
 		if ( ! $this->acquire_generation_lock() ) {
 			PRAutoBlogger_Logger::instance()->info( 'Daily generation skipped: already running (lock held).', 'scheduler' );
 			return;
@@ -361,6 +370,24 @@ class PRAutoBlogger {
 		return $result > 0;
 	}
 
+	/**
+	 * Lazy-load the OpenRouter model registry singleton.
+	 *
+	 * Config (option names, transient names) is injected here — the registry
+	 * class itself 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;
+	}
+
 	/** Release the generation mutex. */
 	private function release_generation_lock(): void {
 		global $wpdb;

includes/core/class-cost-reporter.php

@@ -0,0 +1,141 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * 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(
+				"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 [];
+		}
+
+		$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;
+		if ( null === $wpdb ) {
+			return [];
+		}
+
+		$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;
+	}
+}

includes/core/class-cost-tracker.php

@@ -2,8 +2,7 @@
 declare(strict_types=1);
 
 /**
- * Tracks all API costs, enforces monthly budget limits, and provides
+ * Tracks all API costs and enforces monthly budget limits.
- * cost reporting data for the admin dashboard.
  *
  * 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 +15,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 {
@@ -127,7 +127,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 +136,63 @@ 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->insert( $table, [
-			$wpdb->prepare(
+			'post_id'           => $post_id,
-				"SELECT COALESCE(SUM(estimated_cost), 0) FROM {$table} WHERE created_at >= %s AND response_status = 'success'",
+			'run_id'            => $this->run_id,
-				$first_of_month
+			'stage'             => $stage,
-			)
+			'provider'          => 'cloudflare-workers-ai',
-		);
+			'model'             => $model,
+			'prompt_tokens'     => 0,
+			'completion_tokens' => 0,
+			'estimated_cost'    => $cost_usd,
+			'response_status'   => 'success',
+			'error_message'     => '',
+			'created_at'        => current_time( 'mysql' ),
+		] );
+	}
 
-		return (float) $result;
+	/**
+	 * 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 );
 	}
 
 	/**
@@ -164,91 +203,4 @@ class PRAutoBlogger_Cost_Tracker {
 	public function get_current_run_cost(): float {
 		return $this->current_run_cost;
 	}
-
-	/**
-	 * 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;
-		$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;
-	}
 }

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

@@ -0,0 +1,157 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * 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 (from the generation prompt).
+	 *
+	 * @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 = '' ) {
+		// 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 = [
+			'name'     => $this->generate_filename( $image_data['model'], $image_data['width'], $image_data['height'] ),
+			'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.
+	 *
+	 * @return string Sanitized filename.
+	 */
+	private function generate_filename( string $model, int $width, int $height ): string {
+		$base = sprintf(
+			'prautoblogger_%s_%dx%d_%s',
+			sanitize_title( $model ),
+			$width,
+			$height,
+			gmdate( 'Y-m-d_H-i-s' )
+		);
+
+		return $base . '.png'; // Default to PNG since FLUX.1 outputs 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 = [
+			'image/png'  => '.png',
+			'image/jpeg' => '.jpg',
+			'image/jpg'  => '.jpg',
+		];
+
+		return $map[ strtolower( $mime_type ) ] ?? '.png';
+	}
+}

includes/core/class-image-pipeline.php

@@ -0,0 +1,280 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Orchestrates image generation for published articles.
+ *
+ * Generates two images per article (A/B experiment):
+ *   - Image A: Article-driven prompt → featured image
+ *   - Image B: Source-driven prompt → post meta (_prautoblogger_image_b_id)
+ *
+ * Each image is independently fallible — if A fails, still try B. If both fail,
+ * the article is published without images (graceful degradation).
+ *
+ * Triggered by: PRAutoBlogger_Pipeline_Runner after publisher creates the post.
+ * Dependencies: PRAutoBlogger_Image_Provider_Interface (concrete provider),
+ *               PRAutoBlogger_Image_Prompt_Builder, PRAutoBlogger_Image_Media_Sideloader,
+ *               PRAutoBlogger_Cost_Tracker, PRAutoBlogger_Logger.
+ *
+ * @see core/class-pipeline-runner.php       — Calls this after publisher.
+ * @see core/class-publisher.php             — Sets featured image + post meta.
+ * @see core/class-image-prompt-builder.php  — Prompt generation.
+ * @see core/class-image-media-sideloader.php — Media library integration.
+ * @see ARCHITECTURE.md                      — Image pipeline data flow.
+ */
+class PRAutoBlogger_Image_Pipeline {
+
+	/**
+	 * Default image dimensions (landscape).
+	 */
+	private const DEFAULT_WIDTH  = 1200;
+	private const DEFAULT_HEIGHT = 630;
+
+	/**
+	 * The image provider (FLUX.1 via Cloudflare or another).
+	 *
+	 * @var PRAutoBlogger_Image_Provider_Interface
+	 */
+	private PRAutoBlogger_Image_Provider_Interface $provider;
+
+	/**
+	 * Prompt builder.
+	 *
+	 * @var PRAutoBlogger_Image_Prompt_Builder
+	 */
+	private PRAutoBlogger_Image_Prompt_Builder $prompt_builder;
+
+	/**
+	 * Media library sideloader.
+	 *
+	 * @var PRAutoBlogger_Image_Media_Sideloader
+	 */
+	private PRAutoBlogger_Image_Media_Sideloader $sideloader;
+
+	/**
+	 * Cost tracker for logging spend.
+	 *
+	 * @var PRAutoBlogger_Cost_Tracker
+	 */
+	private PRAutoBlogger_Cost_Tracker $cost_tracker;
+
+	/**
+	 * Construct with dependencies.
+	 *
+	 * @param PRAutoBlogger_Image_Provider_Interface|null $provider Optional provider (defaults to Cloudflare).
+	 * @param PRAutoBlogger_Cost_Tracker|null             $cost_tracker Optional cost tracker.
+	 */
+	public function __construct(
+		?PRAutoBlogger_Image_Provider_Interface $provider = null,
+		?PRAutoBlogger_Cost_Tracker $cost_tracker = null
+	) {
+		$this->provider         = $provider ?? new PRAutoBlogger_Cloudflare_Image_Provider();
+		$this->prompt_builder   = new PRAutoBlogger_Image_Prompt_Builder();
+		$this->sideloader       = new PRAutoBlogger_Image_Media_Sideloader();
+		$this->cost_tracker     = $cost_tracker ?? new PRAutoBlogger_Cost_Tracker();
+	}
+
+	/**
+	 * Generate and attach images to a published post.
+	 *
+	 * Generates Image A (article-driven) and Image B (source-driven). If enabled
+	 * in settings. Each image is independently fallible.
+	 *
+	 * @param int                    $post_id Post ID to attach images to.
+	 * @param array{
+	 *     post_title?: string,
+	 *     post_content?: string,
+	 *     suggested_title?: string,
+	 * }                           $article_data Article title + content.
+	 * @param array{
+	 *     title?: string,
+	 *     selftext?: string,
+	 *     comments?: string[],
+	 * }|null                      $source_data Optional Reddit source data for Image B.
+	 *
+	 * @return array{
+	 *     image_a_id?: int,
+	 *     image_b_id?: int,
+	 *     cost_usd: float,
+	 *     errors: string[],
+	 * } Attachment IDs (if successful) and cost/errors.
+	 */
+	public function generate_and_attach_images(
+		int $post_id,
+		array $article_data,
+		?array $source_data = null
+	): array {
+		$result = [
+			'cost_usd' => 0.0,
+			'errors'   => [],
+		];
+
+		// Early exit if image generation is disabled.
+		if ( ! get_option( 'prautoblogger_image_enabled' ) ) {
+			PRAutoBlogger_Logger::instance()->info( 'Image generation disabled in settings.', 'image_pipeline' );
+			return $result;
+		}
+
+		// Generate Image A (article-driven prompt).
+		$image_a_result = $this->generate_image_a( $post_id, $article_data );
+		if ( ! is_wp_error( $image_a_result ) && isset( $image_a_result['attachment_id'] ) ) {
+			$result['image_a_id'] = $image_a_result['attachment_id'];
+		} else {
+			$result['errors'][] = is_wp_error( $image_a_result )
+				? $image_a_result->get_error_message()
+				: 'Image A generation produced no attachment ID.';
+		}
+		if ( ! is_wp_error( $image_a_result ) ) {
+			$result['cost_usd'] += $image_a_result['cost_usd'] ?? 0.0;
+		}
+
+		// Generate Image B (source-driven prompt) if source data is available.
+		if ( null !== $source_data && ! empty( $source_data ) ) {
+			$image_b_result = $this->generate_image_b( $post_id, $source_data );
+			if ( ! is_wp_error( $image_b_result ) && isset( $image_b_result['attachment_id'] ) ) {
+				$result['image_b_id'] = $image_b_result['attachment_id'];
+			} else {
+				$result['errors'][] = is_wp_error( $image_b_result )
+					? $image_b_result->get_error_message()
+					: 'Image B generation produced no attachment ID.';
+			}
+			if ( ! is_wp_error( $image_b_result ) ) {
+				$result['cost_usd'] += $image_b_result['cost_usd'] ?? 0.0;
+			}
+		}
+
+		return $result;
+	}
+
+	/**
+	 * Generate Image A from article content.
+	 *
+	 * @param int   $post_id Post ID.
+	 * @param array $article_data Article data.
+	 *
+	 * @return array{
+	 *     attachment_id?: int,
+	 *     cost_usd: float,
+	 * }|\WP_Error
+	 */
+	private function generate_image_a( int $post_id, array $article_data ) {
+		try {
+			// Build the article-driven prompt.
+			$prompt = $this->prompt_builder->build_article_prompt( $article_data );
+
+			// Estimate cost before generating.
+			$estimated_cost = $this->provider->estimate_cost( self::DEFAULT_WIDTH, self::DEFAULT_HEIGHT );
+			if ( $this->cost_tracker->would_exceed_budget( $estimated_cost ) ) {
+				return new \WP_Error(
+					'budget_exceeded',
+					'Image generation would exceed monthly budget.'
+				);
+			}
+
+			// Generate the image.
+			$image_data = $this->provider->generate_image( $prompt, self::DEFAULT_WIDTH, self::DEFAULT_HEIGHT );
+
+			// Sideload the image into media library.
+			$attachment_id = $this->sideloader->sideload_image(
+				$image_data,
+				$post_id,
+				substr( $prompt, 0, 100 ) // Use first 100 chars of prompt as alt text.
+			);
+
+			if ( is_wp_error( $attachment_id ) ) {
+				return $attachment_id;
+			}
+
+			// Log the cost.
+			$this->cost_tracker->log_image_generation(
+				$image_data['cost_usd'],
+				'flux-1-schnell',
+				$post_id,
+				'image_a'
+			);
+
+			PRAutoBlogger_Logger::instance()->info(
+				sprintf( 'Image A generated for post %d (attachment %d, cost $%.4f)', $post_id, $attachment_id, $image_data['cost_usd'] ),
+				'image_pipeline'
+			);
+
+			return [
+				'attachment_id' => $attachment_id,
+				'cost_usd'      => $image_data['cost_usd'],
+			];
+		} catch ( \Exception $e ) {
+			PRAutoBlogger_Logger::instance()->error(
+				'Image A generation failed: ' . $e->getMessage(),
+				'image_pipeline'
+			);
+
+			return new \WP_Error( 'image_generation_failed', $e->getMessage() );
+		}
+	}
+
+	/**
+	 * Generate Image B from source data.
+	 *
+	 * @param int   $post_id Post ID.
+	 * @param array $source_data Source Reddit data.
+	 *
+	 * @return array{
+	 *     attachment_id?: int,
+	 *     cost_usd: float,
+	 * }|\WP_Error
+	 */
+	private function generate_image_b( int $post_id, array $source_data ) {
+		try {
+			// Build the source-driven prompt.
+			$prompt = $this->prompt_builder->build_source_prompt( $source_data );
+
+			// Estimate cost before generating.
+			$estimated_cost = $this->provider->estimate_cost( self::DEFAULT_WIDTH, self::DEFAULT_HEIGHT );
+			if ( $this->cost_tracker->would_exceed_budget( $estimated_cost ) ) {
+				return new \WP_Error(
+					'budget_exceeded',
+					'Image generation would exceed monthly budget.'
+				);
+			}
+
+			// Generate the image.
+			$image_data = $this->provider->generate_image( $prompt, self::DEFAULT_WIDTH, self::DEFAULT_HEIGHT );
+
+			// Sideload the image into media library.
+			$attachment_id = $this->sideloader->sideload_image(
+				$image_data,
+				$post_id,
+				substr( $prompt, 0, 100 ) // Use first 100 chars of prompt as alt text.
+			);
+
+			if ( is_wp_error( $attachment_id ) ) {
+				return $attachment_id;
+			}
+
+			// Log the cost.
+			$this->cost_tracker->log_image_generation(
+				$image_data['cost_usd'],
+				'flux-1-schnell',
+				$post_id,
+				'image_b'
+			);
+
+			PRAutoBlogger_Logger::instance()->info(
+				sprintf( 'Image B generated for post %d (attachment %d, cost $%.4f)', $post_id, $attachment_id, $image_data['cost_usd'] ),
+				'image_pipeline'
+			);
+
+			return [
+				'attachment_id' => $attachment_id,
+				'cost_usd'      => $image_data['cost_usd'],
+			];
+		} catch ( \Exception $e ) {
+			PRAutoBlogger_Logger::instance()->error(
+				'Image B generation failed: ' . $e->getMessage(),
+				'image_pipeline'
+			);
+
+			return new \WP_Error( 'image_generation_failed', $e->getMessage() );
+		}
+	}
+}

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

@@ -0,0 +1,136 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Builds image prompts from article content or source data.
+ *
+ * Generates concise visual concepts suitable for FLUX.1 image generation,
+ * extracting key themes from article titles/content and Reddit source data.
+ *
+ * Triggered by: PRAutoBlogger_Image_Pipeline during content generation run.
+ * Dependencies: None — pure data transformation.
+ *
+ * @see core/class-image-pipeline.php — Consumes build_article_prompt() and build_source_prompt().
+ * @see ARCHITECTURE.md              — Image generation data flow.
+ */
+class PRAutoBlogger_Image_Prompt_Builder {
+
+	/**
+	 * Build a visual prompt from finished article content.
+	 *
+	 * Extracts the title and first paragraph to synthesize a product-marketing
+	 * angle visual concept suitable for a featured image. Appends the style suffix
+	 * from plugin options.
+	 *
+	 * @param array{
+	 *     post_title?: string,
+	 *     post_content?: string,
+	 *     suggested_title?: string,
+	 * } $article_data Article data with title and HTML content.
+	 *
+	 * @return string Concise prompt (under 200 words) with style suffix appended.
+	 */
+	public function build_article_prompt( array $article_data ): string {
+		$title   = $article_data['post_title'] ?? $article_data['suggested_title'] ?? 'Product';
+		$content = $article_data['post_content'] ?? '';
+
+		// Extract first paragraph from HTML content.
+		$first_para = $this->extract_first_paragraph( $content );
+
+		// Build visual concepts from title + first paragraph.
+		$concepts = $this->synthesize_visual_concepts( $title, $first_para );
+
+		// Append style suffix.
+		$style_suffix = get_option( 'prautoblogger_image_style_suffix', PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_SUFFIX );
+
+		return trim( $concepts . ' ' . $style_suffix );
+	}
+
+	/**
+	 * Build a visual prompt from source Reddit thread data.
+	 *
+	 * Extracts the Reddit thread title and top comments to synthesize an
+	 * editorial-cartoonist angle visual concept. Appends the style suffix
+	 * from plugin options.
+	 *
+	 * @param array{
+	 *     title?: string,
+	 *     selftext?: string,
+	 *     comments?: string[],
+	 * } $source_data Reddit source data with title and comments.
+	 *
+	 * @return string Concise prompt (under 200 words) with style suffix appended.
+	 */
+	public function build_source_prompt( array $source_data ): string {
+		$title    = $source_data['title'] ?? 'Reddit Discussion';
+		$comments = $source_data['comments'] ?? [];
+
+		// Build visual concepts from title + top comments.
+		$concepts = $this->synthesize_visual_concepts(
+			$title,
+			is_array( $comments ) && ! empty( $comments ) ? $comments[0] : ''
+		);
+
+		// Append style suffix.
+		$style_suffix = get_option( 'prautoblogger_image_style_suffix', PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_SUFFIX );
+
+		return trim( $concepts . ' ' . $style_suffix );
+	}
+
+	/**
+	 * 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.
+	 */
+	private function extract_first_paragraph( string $html ): string {
+		// Remove HTML tags.
+		$text = wp_strip_all_tags( $html );
+
+		// Split on double-newline and take the first paragraph.
+		$paras  = preg_split( '/\n\n+/', $text );
+		$para   = isset( $paras[0] ) ? trim( $paras[0] ) : '';
+
+		// Limit to first 200 chars to keep prompt concise.
+		if ( strlen( $para ) > 200 ) {
+			$para = substr( $para, 0, 200 ) . '...';
+		}
+
+		return $para;
+	}
+
+	/**
+	 * Synthesize visual concepts from a title and supporting text.
+	 *
+	 * Combines key words and themes into a short visual narrative that FLUX.1
+	 * can render. This is intentionally rule-based rather than LLM-driven to
+	 * avoid another API call per image generation.
+	 *
+	 * @param string $title Main heading / topic.
+	 * @param string $supporting_text Additional context (first para or comment).
+	 *
+	 * @return string Synthesized visual prompt concept.
+	 */
+	private function synthesize_visual_concepts( string $title, string $supporting_text ): string {
+		$title = trim( sanitize_text_field( $title ) );
+		$text  = trim( sanitize_text_field( $supporting_text ) );
+
+		// Build a simple declarative concept from title and text snippets.
+		$prompt = "A visual representation of: {$title}";
+
+		if ( ! empty( $text ) ) {
+			// Take first 150 chars to avoid bloating the prompt.
+			$snippet = strlen( $text ) > 150
+				? substr( $text, 0, 150 ) . '...'
+				: $text;
+
+			$prompt .= ". Context: {$snippet}";
+		}
+
+		return trim( $prompt );
+	}
+}

includes/core/class-logger.php

@@ -126,6 +126,11 @@ 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

includes/core/class-publisher.php

@@ -121,6 +121,11 @@ class PRAutoBlogger_Publisher {
 		// Update generation log entries to reference this post.
 		$this->link_generation_logs( $post_id, $run_id );
 
+		// Generate and attach images if published and images enabled.
+		if ( 'publish' === $post_status ) {
+			$this->attach_generated_images( $post_id, $idea, $post_data );
+		}
+
 		PRAutoBlogger_Logger::instance()->info(
 			sprintf( 'Post created: ID=%d, status=%s, title="%s"', $post_id, $post_status, $idea->get_suggested_title() ),
 			'publisher'
@@ -307,4 +312,76 @@ class PRAutoBlogger_Publisher {
 
 		return ! empty( $admins ) ? (int) $admins[0] : 1;
 	}
+
+	/**
+	 * Generate and attach images to a published post.
+	 *
+	 * Calls the image pipeline to generate Image A (featured image) and Image B
+	 * (secondary image). Sets _thumbnail_id and _prautoblogger_image_b_id post meta.
+	 * Gracefully handles image generation failures — post is already created, so
+	 * this is a non-blocking operation.
+	 *
+	 * @param int                        $post_id The newly created post ID.
+	 * @param PRAutoBlogger_Article_Idea   $idea    The article idea (contains source IDs).
+	 * @param array                      $post_data The post data array (for article content).
+	 *
+	 * @return void
+	 */
+	private function attach_generated_images( int $post_id, PRAutoBlogger_Article_Idea $idea, array $post_data ): void {
+		// Build source data from idea's source IDs (if available).
+		$source_data = null;
+		$source_ids  = $idea->get_source_ids();
+		if ( ! empty( $source_ids ) ) {
+			// Attempt to fetch the original source data for Image B.
+			// For now, we pass null; the image pipeline will handle gracefully.
+			$source_data = null;
+		}
+
+		try {
+			$image_pipeline = new PRAutoBlogger_Image_Pipeline();
+			$result         = $image_pipeline->generate_and_attach_images( $post_id, $post_data, $source_data );
+
+			// Set Image A as the featured image.
+			if ( isset( $result['image_a_id'] ) ) {
+				set_post_thumbnail( $post_id, $result['image_a_id'] );
+				PRAutoBlogger_Logger::instance()->info(
+					sprintf( 'Set featured image (attachment %d) for post %d', $result['image_a_id'], $post_id ),
+					'publisher'
+				);
+			}
+
+			// Store Image B ID in post meta for A/B tracking.
+			if ( isset( $result['image_b_id'] ) ) {
+				update_post_meta( $post_id, '_prautoblogger_image_b_id', $result['image_b_id'] );
+				PRAutoBlogger_Logger::instance()->info(
+					sprintf( 'Stored Image B (attachment %d) in post meta for post %d', $result['image_b_id'], $post_id ),
+					'publisher'
+				);
+			}
+
+			// Log errors if any occurred (but don't let them block post creation).
+			if ( ! empty( $result['errors'] ) ) {
+				foreach ( $result['errors'] as $error ) {
+					PRAutoBlogger_Logger::instance()->warning(
+						'Image generation warning for post ' . $post_id . ': ' . $error,
+						'publisher'
+					);
+				}
+			}
+
+			// Log total cost.
+			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 ( \Exception $e ) {
+			// Log the error but don't re-throw — post is already created.
+			PRAutoBlogger_Logger::instance()->warning(
+				'Image pipeline exception for post ' . $post_id . ': ' . $e->getMessage(),
+				'publisher'
+			);
+		}
+	}
 }

includes/services/class-openrouter-model-normalizer.php

@@ -0,0 +1,114 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Normalizes raw OpenRouter model data into the standardized record shape.
+ *
+ * Extracted from PRAutoBlogger_OpenRouter_Model_Registry so both classes stay
+ * under the 300-line cap. The registry orchestrates fetch + cache; this helper
+ * owns the mapping logic.
+ *
+ * Triggered by: PRAutoBlogger_OpenRouter_Model_Registry::refresh().
+ * Dependencies: None — pure data transformation, no I/O.
+ *
+ * @see services/class-openrouter-model-registry.php — Sole consumer.
+ * @see interface-model-registry.php                  — Defines the normalized record shape.
+ * @see ARCHITECTURE.md                               — Capability vocabulary.
+ */
+class PRAutoBlogger_OpenRouter_Model_Normalizer {
+
+	/**
+	 * Standardized capability vocabulary (CTO-locked). Derived from OpenRouter's
+	 * `architecture.input_modalities` + `architecture.output_modalities`.
+	 *
+	 * @var array<string, array{in: string[], out: string[]}>
+	 */
+	private const CAPABILITY_MAP = [
+		'text→text'        => [ 'in' => [ 'text' ],            'out' => [ 'text' ] ],
+		'text+image→text'  => [ 'in' => [ 'text', 'image' ],   'out' => [ 'text' ] ],
+		'text+audio→text'  => [ 'in' => [ 'text', 'audio' ],   'out' => [ 'text' ] ],
+		'text→image'       => [ 'in' => [ 'text' ],            'out' => [ 'image' ] ],
+		'text→audio'       => [ 'in' => [ 'text' ],            'out' => [ 'audio' ] ],
+		'text→video'       => [ 'in' => [ 'text' ],            'out' => [ 'video' ] ],
+		'text→embedding'   => [ 'in' => [ 'text' ],            'out' => [ 'embedding' ] ],
+	];
+
+	/**
+	 * Normalize raw OpenRouter model records into the standardized shape.
+	 *
+	 * Unknown architectures degrade to 'text→text' capability — never throws.
+	 * Pricing is converted from per-token (OpenRouter format) to per-million.
+	 *
+	 * @param array $raw_models Raw 'data' array from the OpenRouter API.
+	 *
+	 * @return array<int, array{
+	 *     id: string,
+	 *     name: string,
+	 *     provider: string,
+	 *     context_length: int,
+	 *     input_price_per_m: float,
+	 *     output_price_per_m: float,
+	 *     capabilities: string[],
+	 *     deprecated: bool,
+	 *     updated_at: int,
+	 * }> Normalized records, sorted by name ascending.
+	 */
+	public function normalize( array $raw_models ): array {
+		$normalized = [];
+
+		foreach ( $raw_models as $model ) {
+			if ( ! is_array( $model ) || ! isset( $model['id'] ) ) {
+				continue;
+			}
+
+			$input_modalities  = (array) ( $model['architecture']['input_modalities'] ?? [ 'text' ] );
+			$output_modalities = (array) ( $model['architecture']['output_modalities'] ?? [ 'text' ] );
+
+			$name_parts = explode( '/', (string) $model['id'], 2 );
+
+			// OpenRouter prices are per-token; convert to per-million.
+			$prompt_price     = (float) ( $model['pricing']['prompt'] ?? 0 );
+			$completion_price = (float) ( $model['pricing']['completion'] ?? 0 );
+
+			$normalized[] = [
+				'id'                 => (string) $model['id'],
+				'name'               => (string) ( $model['name'] ?? $model['id'] ),
+				'provider'           => $name_parts[0] ?? 'unknown',
+				'context_length'     => (int) ( $model['context_length'] ?? 0 ),
+				'input_price_per_m'  => round( $prompt_price * 1_000_000, 4 ),
+				'output_price_per_m' => round( $completion_price * 1_000_000, 4 ),
+				'capabilities'       => $this->derive_capabilities( $input_modalities, $output_modalities ),
+				'deprecated'         => false,
+				'updated_at'         => (int) ( $model['created'] ?? 0 ),
+			];
+		}
+
+		usort( $normalized, static function ( array $a, array $b ): int {
+			return strcasecmp( $a['name'], $b['name'] );
+		} );
+
+		return $normalized;
+	}
+
+	/**
+	 * Derive capability strings from input/output modality arrays.
+	 *
+	 * @param string[] $input_modalities  e.g. ['text', 'image']
+	 * @param string[] $output_modalities e.g. ['text']
+	 *
+	 * @return string[] Matched capability labels. Defaults to ['text→text'].
+	 */
+	private function derive_capabilities( array $input_modalities, array $output_modalities ): array {
+		$caps = [];
+
+		foreach ( self::CAPABILITY_MAP as $label => $requirements ) {
+			$input_match  = empty( array_diff( $requirements['in'], $input_modalities ) );
+			$output_match = empty( array_diff( $requirements['out'], $output_modalities ) );
+			if ( $input_match && $output_match ) {
+				$caps[] = $label;
+			}
+		}
+
+		return empty( $caps ) ? [ 'text→text' ] : $caps;
+	}
+}

includes/services/class-openrouter-model-registry.php

@@ -0,0 +1,226 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * OpenRouter model registry — fetches, normalizes, and caches the model list.
+ *
+ * All config is constructor-injected. No PRAUTOBLOGGER_* constants referenced
+ * inside this class — Phase 2 lifts it into a shared Composer package with
+ * zero internal edits.
+ *
+ * Storage: WP option (durable) fronted by a transient (fast reads, 24h TTL).
+ * On stale-and-fetch-fails, the option payload is served and a flag is set.
+ *
+ * Triggered by: `prautoblogger_refresh_model_registry` action, manual AJAX
+ *               (commit 3), PRAutoBlogger_Activator::activate().
+ * Dependencies: wp_remote_get(), PRAutoBlogger_Logger,
+ *               PRAutoBlogger_OpenRouter_Model_Normalizer.
+ *
+ * @see interface-model-registry.php               — Interface.
+ * @see class-openrouter-model-normalizer.php       — Normalization logic.
+ * @see class-prautoblogger.php                     — Hooks the refresh action.
+ * @see ARCHITECTURE.md                             — AI Model Registries section.
+ */
+class PRAutoBlogger_OpenRouter_Model_Registry implements PRAutoBlogger_Model_Registry_Interface {
+
+	private const PROVIDER_ID       = 'openrouter';
+	private const LOG_CONTEXT       = 'model-registry';
+	private const HTTP_TIMEOUT      = 15;
+	private const ADMIN_NOTICE_FLAG = 'prautoblogger_model_registry_stale';
+
+	private string $option_name;
+	private string $fetched_at_option;
+	private string $transient_name;
+	private string $endpoint;
+	private int $cache_ttl;
+	private int $idempotency_window;
+	private PRAutoBlogger_OpenRouter_Model_Normalizer $normalizer;
+
+	/**
+	 * @param string $option_name         WP option for the durable payload.
+	 * @param string $transient_name      WP transient for fast reads.
+	 * @param string $endpoint            OpenRouter models API URL.
+	 * @param int    $cache_ttl_seconds   Transient TTL (default 86400 = 24h).
+	 * @param int    $idempotency_seconds Skip refresh if younger than this (default 43200 = 12h).
+	 */
+	public function __construct(
+		string $option_name,
+		string $transient_name,
+		string $endpoint = 'https://openrouter.ai/api/v1/models',
+		int $cache_ttl_seconds = 86400,
+		int $idempotency_seconds = 43200
+	) {
+		$this->option_name        = $option_name;
+		$this->fetched_at_option  = $option_name . '_fetched_at';
+		$this->transient_name    = $transient_name;
+		$this->endpoint          = $endpoint;
+		$this->cache_ttl         = $cache_ttl_seconds;
+		$this->idempotency_window = $idempotency_seconds;
+		$this->normalizer        = new PRAutoBlogger_OpenRouter_Model_Normalizer();
+	}
+
+	/** {@inheritDoc} */
+	public function get_models(): array {
+		return $this->load_payload();
+	}
+
+	/** {@inheritDoc} */
+	public function get_models_with_capability( string $capability ): array {
+		return array_values(
+			array_filter(
+				$this->load_payload(),
+				static function ( array $model ) use ( $capability ): bool {
+					return in_array( $capability, $model['capabilities'] ?? [], true );
+				}
+			)
+		);
+	}
+
+	/** {@inheritDoc} */
+	public function find_model( string $id ): ?array {
+		foreach ( $this->load_payload() as $model ) {
+			if ( ( $model['id'] ?? '' ) === $id ) {
+				return $model;
+			}
+		}
+		return null;
+	}
+
+	/** {@inheritDoc} */
+	public function refresh( bool $force = false ): array {
+		$fetched_at = $this->get_fetched_at();
+
+		if ( ! $force && $fetched_at > 0 && ( time() - $fetched_at ) < $this->idempotency_window ) {
+			$payload = $this->load_payload();
+			return [ 'count' => count( $payload ), 'fetched_at' => $fetched_at ];
+		}
+
+		$raw_models = $this->fetch_from_api();
+		if ( null === $raw_models ) {
+			$this->flag_stale();
+			$stale = $this->load_from_option();
+			return [ 'count' => count( $stale ), 'fetched_at' => $fetched_at ];
+		}
+
+		$normalized = $this->normalizer->normalize( $raw_models );
+		$now        = time();
+
+		$this->save_payload( $normalized, $now );
+		$this->clear_stale_flag();
+
+		PRAutoBlogger_Logger::instance()->info(
+			sprintf( 'Model registry refreshed: %d models.', count( $normalized ) ),
+			self::LOG_CONTEXT
+		);
+
+		return [ 'count' => count( $normalized ), 'fetched_at' => $now ];
+	}
+
+	/** {@inheritDoc} */
+	public function get_fetched_at(): int {
+		return (int) get_option( $this->fetched_at_option, 0 );
+	}
+
+	/** {@inheritDoc} */
+	public function get_provider_name(): string {
+		return self::PROVIDER_ID;
+	}
+
+	/**
+	 * Load from transient (fast) falling back to option (durable).
+	 *
+	 * @return array<int, array>
+	 */
+	private function load_payload(): array {
+		$cached = get_transient( $this->transient_name );
+		if ( is_array( $cached ) && ! empty( $cached ) ) {
+			return $cached;
+		}
+		return $this->load_from_option();
+	}
+
+	/** @return array<int, array> */
+	private function load_from_option(): array {
+		$data = get_option( $this->option_name, [] );
+		return is_array( $data ) ? $data : [];
+	}
+
+	private function save_payload( array $payload, int $now ): void {
+		update_option( $this->option_name, $payload, false );
+		update_option( $this->fetched_at_option, $now, false );
+		set_transient( $this->transient_name, $payload, $this->cache_ttl );
+	}
+
+	/**
+	 * Fetch the model list from the OpenRouter API with exponential-backoff retry.
+	 *
+	 * @return ?array Raw 'data' array, or null on failure.
+	 */
+	private function fetch_from_api(): ?array {
+		$max_retries = defined( 'PRAUTOBLOGGER_MAX_RETRIES' ) ? PRAUTOBLOGGER_MAX_RETRIES : 3;
+		$base_delay  = defined( 'PRAUTOBLOGGER_RETRY_BASE_DELAY_SECONDS' ) ? PRAUTOBLOGGER_RETRY_BASE_DELAY_SECONDS : 2;
+
+		for ( $attempt = 1; $attempt <= $max_retries; $attempt++ ) {
+			$response = wp_remote_get( $this->endpoint, [ 'timeout' => self::HTTP_TIMEOUT ] );
+
+			if ( is_wp_error( $response ) ) {
+				PRAutoBlogger_Logger::instance()->warning(
+					sprintf( 'Model registry fetch attempt %d: %s', $attempt, $response->get_error_message() ),
+					self::LOG_CONTEXT
+				);
+				$this->backoff( $attempt, $base_delay );
+				continue;
+			}
+
+			$status = (int) wp_remote_retrieve_response_code( $response );
+			$body   = (string) wp_remote_retrieve_body( $response );
+
+			if ( $status >= 500 || 429 === $status ) {
+				PRAutoBlogger_Logger::instance()->warning(
+					sprintf( 'Model registry fetch attempt %d: HTTP %d', $attempt, $status ),
+					self::LOG_CONTEXT
+				);
+				$this->backoff( $attempt, $base_delay );
+				continue;
+			}
+
+			if ( $status >= 400 ) {
+				PRAutoBlogger_Logger::instance()->error(
+					sprintf( 'Model registry: HTTP %d: %s', $status, substr( $body, 0, 300 ) ),
+					self::LOG_CONTEXT
+				);
+				return null;
+			}
+
+			$decoded = json_decode( $body, true );
+			if ( ! is_array( $decoded ) || ! isset( $decoded['data'] ) || ! is_array( $decoded['data'] ) ) {
+				PRAutoBlogger_Logger::instance()->error( 'Model registry: unexpected response shape.', self::LOG_CONTEXT );
+				return null;
+			}
+
+			return $decoded['data'];
+		}
+
+		PRAutoBlogger_Logger::instance()->error(
+			sprintf( 'Model registry fetch failed after %d attempts.', $max_retries ),
+			self::LOG_CONTEXT
+		);
+		return null;
+	}
+
+	private function backoff( int $attempt, int $base_delay ): void {
+		$delay = $base_delay * (int) pow( 2, $attempt - 1 );
+		if ( $delay > 0 ) {
+			sleep( $delay );
+		}
+	}
+
+	private function flag_stale(): void {
+		update_option( self::ADMIN_NOTICE_FLAG, '1', false );
+		PRAutoBlogger_Logger::instance()->warning( 'Model registry: serving stale data after refresh failure.', self::LOG_CONTEXT );
+	}
+
+	private function clear_stale_flag(): void {
+		delete_option( self::ADMIN_NOTICE_FLAG );
+	}
+}

includes/services/interface-model-registry.php

@@ -0,0 +1,94 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Contract for a provider-specific AI model registry.
+ *
+ * Phase 1 (v1): single implementation for OpenRouter (`class-openrouter-model-registry.php`).
+ * Phase 3: a second implementation wraps Cloudflare Workers AI FLUX model data. A
+ * higher-level dispatcher iterates registered registries, calls each with the same
+ * capability, and unions the results — the per-registry interface stays unchanged.
+ *
+ * Implementations MUST:
+ *   - Store the normalized registry as a WP option + transient cache layer.
+ *   - Degrade gracefully when the source API is unreachable (serve last-good cache).
+ *   - Never throw on public read methods — empty arrays are acceptable fallbacks.
+ *   - Log refresh failures via PRAutoBlogger_Logger.
+ *
+ * Triggered by: Settings page field renderer (commit 2), AJAX refresh endpoint
+ *               (commit 3), daily cron via the main plugin loader.
+ * Dependencies: None at interface level — implementations wrap an HTTP API.
+ *
+ * @see services/class-openrouter-model-registry.php — Default implementation.
+ * @see admin/fields/class-openrouter-model-field.php — Field renderer that queries this interface.
+ * @see ARCHITECTURE.md                               — AI Model Registries section.
+ */
+interface PRAutoBlogger_Model_Registry_Interface {
+
+	/**
+	 * Return all models in the registry, normalized.
+	 *
+	 * @return array<int, array{
+	 *     id: string,
+	 *     name: string,
+	 *     provider: string,
+	 *     context_length: int,
+	 *     input_price_per_m: float,
+	 *     output_price_per_m: float,
+	 *     capabilities: string[],
+	 *     deprecated: bool,
+	 *     updated_at: int,
+	 * }> Normalized model records, sorted by name ascending.
+	 */
+	public function get_models(): array;
+
+	/**
+	 * Return only models matching a given capability string.
+	 *
+	 * @param string $capability One of the standardized capability strings:
+	 *                           'text→text', 'text+image→text', 'text+audio→text',
+	 *                           'text→image', 'text→audio', 'text→video',
+	 *                           'text→embedding'.
+	 *
+	 * @return array<int, array> Same record shape as get_models(), filtered.
+	 */
+	public function get_models_with_capability( string $capability ): array;
+
+	/**
+	 * Look up one model by its provider-qualified id (e.g. 'anthropic/claude-3.5-haiku').
+	 *
+	 * @param string $id Model identifier.
+	 *
+	 * @return ?array Normalized model record, or null if not in the registry.
+	 */
+	public function find_model( string $id ): ?array;
+
+	/**
+	 * Fetch fresh data from the upstream source and replace the cached payload.
+	 *
+	 * When `$force` is false, implementations SHOULD skip the HTTP call if the
+	 * payload is younger than a configured idempotency window (default 12h).
+	 *
+	 * Side effects: HTTP GET to the upstream API, wp_options write, transient set,
+	 *               log line on failure, admin notice flag on stale-and-failed.
+	 *
+	 * @param bool $force True to bypass the idempotency window (e.g. manual admin refresh).
+	 *
+	 * @return array{count: int, fetched_at: int} Number of models stored and unix timestamp.
+	 */
+	public function refresh( bool $force = false ): array;
+
+	/**
+	 * Unix timestamp of the last successful refresh. Zero if never refreshed.
+	 *
+	 * @return int
+	 */
+	public function get_fetched_at(): int;
+
+	/**
+	 * Machine-readable provider identifier (e.g. 'openrouter', 'cloudflare_workers_ai').
+	 *
+	 * @return string
+	 */
+	public function get_provider_name(): string;
+}

templates/admin/metrics-page.php

@@ -9,15 +9,15 @@ if ( ! defined( 'ABSPATH' ) ) {
 	exit;
 }
 
-$cost_tracker = new PRAutoBlogger_Cost_Tracker();
+$cost_reporter = new PRAutoBlogger_Cost_Reporter();
-$monthly_spend = $cost_tracker->get_monthly_spend();
+$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();
-$daily_spend   = $cost_tracker->get_daily_spend( 30 );
+$daily_spend   = $cost_reporter->get_daily_spend( 30 );
 
 $first_of_month = gmdate( 'Y-m-01' );
 $today          = gmdate( 'Y-m-d' );
-$stage_breakdown = $cost_tracker->get_spend_by_stage( $first_of_month, $today );
+$stage_breakdown = $cost_reporter->get_spend_by_stage( $first_of_month, $today );
 ?>
 <div class="wrap prautoblogger-metrics">
 	<h1><?php esc_html_e( 'PRAutoBlogger — Metrics & Costs', 'prautoblogger' ); ?></h1>

templates/admin/settings-page.php

@@ -14,8 +14,8 @@ if ( ! defined( 'ABSPATH' ) ) {
 }
 
 $active_tab     = isset( $_GET['tab'] ) ? sanitize_key( $_GET['tab'] ) : 'prautoblogger_api';
-$cost_tracker   = new PRAutoBlogger_Cost_Tracker();
+$cost_reporter  = new PRAutoBlogger_Cost_Reporter();
-$monthly_spend  = $cost_tracker->get_monthly_spend();
+$monthly_spend  = $cost_reporter->get_monthly_spend();
 $budget         = (float) get_option( 'prautoblogger_monthly_budget_usd', 50.00 );
 $utilization    = $budget > 0 ? ( $monthly_spend / $budget ) * 100.0 : 0;
 $next_run       = wp_next_scheduled( 'prautoblogger_daily_generation' );

tests/bootstrap.php

@@ -55,6 +55,11 @@ if ( ! defined( 'PRAUTOBLOGGER_DEFAULT_EDITOR_MODEL' ) ) {
     define( 'PRAUTOBLOGGER_DEFAULT_EDITOR_MODEL', 'google/gemini-2.5-flash-lite' );
 }
 
+// Default image style suffix used by ImagePromptBuilder and settings UI.
+if ( ! defined( 'PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_SUFFIX' ) ) {
+    define( 'PRAUTOBLOGGER_DEFAULT_IMAGE_STYLE_SUFFIX', 'Style: test infomercial style.' );
+}
+
 // WordPress database constants used in $wpdb queries.
 if ( ! defined( 'ARRAY_A' ) ) {
     define( 'ARRAY_A', 'ARRAY_A' );
@@ -92,3 +97,39 @@ if ( ! class_exists( 'WP_Query' ) ) {
         }
     }
 }
+
+// NOTE: Do NOT stub wp_strip_all_tags() or sanitize_text_field() here.
+// Brain Monkey / Patchwork manages these stubs in individual tests via
+// Functions\when(). Defining them in bootstrap causes Patchwork's
+// "DefinedTooEarly" error.
+
+// WP_Error stub — used by model registry and image pipeline tests.
+// This is safe to define here because it's a class (not a function),
+// so Patchwork doesn't need to intercept its definition.
+if ( ! class_exists( 'WP_Error' ) ) {
+    class WP_Error {
+        public $errors     = [];
+        public $error_data = [];
+
+        public function __construct( $code = '', $message = '', $data = '' ) {
+            if ( $code ) {
+                $this->errors[ $code ][] = $message;
+                if ( $data ) {
+                    $this->error_data[ $code ] = $data;
+                }
+            }
+        }
+
+        public function get_error_code() {
+            $codes = array_keys( $this->errors );
+            return $codes ? $codes[0] : '';
+        }
+
+        public function get_error_message( $code = '' ) {
+            if ( ! $code ) {
+                $code = $this->get_error_code();
+            }
+            return isset( $this->errors[ $code ] ) ? $this->errors[ $code ][0] : '';
+        }
+    }
+}

tests/unit/Core/CostReporterTest.php

@@ -0,0 +1,93 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_Cost_Reporter.
+ *
+ * Validates monthly spend, daily spend trends, spend-by-stage breakdowns,
+ * and budget utilization reporting methods.
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class CostReporterTest extends BaseTestCase {
+
+    /**
+     * @var \PHPUnit\Framework\MockObject\MockObject Mock $wpdb instance.
+     */
+    private $wpdb;
+
+    protected function setUp(): void {
+        parent::setUp();
+
+        $this->wpdb = $this->create_mock_wpdb();
+        $GLOBALS['wpdb'] = $this->wpdb;
+
+        // CostReporter methods call get_option for budget settings.
+        $this->stub_get_option( [
+            'prautoblogger_monthly_budget_usd' => '50.00',
+        ] );
+
+        // Stub current_time used in date-based queries.
+        $this->stub_current_time( '2026-04-12 10:00:00' );
+    }
+
+    protected function tearDown(): void {
+        unset( $GLOBALS['wpdb'] );
+        parent::tearDown();
+    }
+
+    /**
+     * Test get_monthly_spend returns float.
+     */
+    public function test_get_monthly_spend_returns_float(): void {
+        $this->wpdb->method( 'prepare' )->willReturn( 'prepared' );
+        $this->wpdb->method( 'get_var' )->willReturn( '10.50' );
+
+        $reporter = new \PRAutoBlogger_Cost_Reporter();
+        $spend = $reporter->get_monthly_spend();
+
+        $this->assertIsFloat( $spend );
+        $this->assertGreaterThanOrEqual( 0.0, $spend );
+    }
+
+    /**
+     * Test get_daily_spend returns array.
+     */
+    public function test_get_daily_spend_returns_array(): void {
+        $this->wpdb->method( 'prepare' )->willReturn( 'prepared' );
+        $this->wpdb->method( 'get_results' )->willReturn( [] );
+
+        $reporter = new \PRAutoBlogger_Cost_Reporter();
+        $daily = $reporter->get_daily_spend( 30 );
+
+        $this->assertIsArray( $daily );
+    }
+
+    /**
+     * Test get_spend_by_stage returns array.
+     */
+    public function test_get_spend_by_stage_returns_array(): void {
+        $this->wpdb->method( 'prepare' )->willReturn( 'prepared' );
+        $this->wpdb->method( 'get_results' )->willReturn( [] );
+
+        $reporter = new \PRAutoBlogger_Cost_Reporter();
+        $spend = $reporter->get_spend_by_stage( '2026-04-01', '2026-04-30' );
+
+        $this->assertIsArray( $spend );
+    }
+
+    /**
+     * Test get_budget_utilization returns float between 0 and 100+.
+     */
+    public function test_get_budget_utilization_returns_float(): void {
+        $reporter = new \PRAutoBlogger_Cost_Reporter();
+        $utilization = $reporter->get_budget_utilization();
+
+        $this->assertIsFloat( $utilization );
+        $this->assertGreaterThanOrEqual( 0.0, $utilization );
+    }
+}

tests/unit/Core/CostTrackerTest.php

@@ -68,20 +68,6 @@ class CostTrackerTest extends BaseTestCase {
         $this->assertFalse( $tracker->is_budget_exceeded() );
     }
 
-    /**
-     * Test get_monthly_spend returns float.
-     */
-    public function test_get_monthly_spend_returns_float(): void {
-        $this->wpdb->method( 'prepare' )->willReturn( 'prepared' );
-        $this->wpdb->method( 'get_var' )->willReturn( '10.50' );
-
-        $tracker = new \PRAutoBlogger_Cost_Tracker();
-        $spend = $tracker->get_monthly_spend();
-
-        $this->assertIsFloat( $spend );
-        $this->assertGreaterThanOrEqual( 0.0, $spend );
-    }
-
     /**
      * Test get_current_run_cost returns float.
      */
@@ -98,43 +84,6 @@ class CostTrackerTest extends BaseTestCase {
         $this->assertGreaterThanOrEqual( 0.0, $cost );
     }
 
-    /**
-     * Test get_daily_spend returns array.
-     */
-    public function test_get_daily_spend_returns_array(): void {
-        $this->wpdb->method( 'prepare' )->willReturn( 'prepared' );
-        $this->wpdb->method( 'get_results' )->willReturn( [] );
-
-        $tracker = new \PRAutoBlogger_Cost_Tracker();
-        $daily = $tracker->get_daily_spend( 30 );
-
-        $this->assertIsArray( $daily );
-    }
-
-    /**
-     * Test get_spend_by_stage returns array.
-     */
-    public function test_get_spend_by_stage_returns_array(): void {
-        $this->wpdb->method( 'prepare' )->willReturn( 'prepared' );
-        $this->wpdb->method( 'get_results' )->willReturn( [] );
-
-        $tracker = new \PRAutoBlogger_Cost_Tracker();
-        $spend = $tracker->get_spend_by_stage( '2026-04-01', '2026-04-30' );
-
-        $this->assertIsArray( $spend );
-    }
-
-    /**
-     * Test get_budget_utilization returns float between 0 and 1.
-     */
-    public function test_get_budget_utilization_returns_float(): void {
-        $tracker = new \PRAutoBlogger_Cost_Tracker();
-        $utilization = $tracker->get_budget_utilization();
-
-        $this->assertIsFloat( $utilization );
-        $this->assertGreaterThanOrEqual( 0.0, $utilization );
-    }
-
     /**
      * Test log_api_call with mock database.
      */

tests/unit/Core/ImagePipelineTest.php

@@ -0,0 +1,153 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_Image_Pipeline.
+ *
+ * Validates image generation orchestration, including A/B generation,
+ * cost tracking, and graceful failure handling.
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class ImagePipelineTest extends BaseTestCase {
+
+	protected function setUp(): void {
+		parent::setUp();
+
+		// Mock WordPress functions used by the pipeline and its dependencies.
+		Functions\when( 'is_wp_error' )->alias( function ( $thing ) {
+			return $thing instanceof \WP_Error;
+		} );
+		Functions\when( 'wp_generate_uuid4' )->justReturn( 'test-uuid' );
+		Functions\when( 'get_option' )->alias( function ( $key, $default = false ) {
+			static $options = [
+				'prautoblogger_image_enabled'      => '1',
+				'prautoblogger_image_style_suffix' => 'Style: test style',
+			];
+			return $options[ $key ] ?? $default;
+		} );
+		Functions\when( 'sanitize_text_field' )->returnArg();
+		Functions\when( 'wp_strip_all_tags' )->alias( function ( $str ) {
+			return trim( strip_tags( $str ) );
+		} );
+		Functions\when( 'update_post_meta' )->justReturn( true );
+		Functions\when( 'sanitize_title' )->returnArg();
+		Functions\when( 'esc_html__' )->returnArg();
+	}
+
+	/**
+	 * Test generate_and_attach_images() returns early if disabled.
+	 */
+	public function test_generate_and_attach_images_skipped_if_disabled(): void {
+		Functions\when( 'get_option' )->alias( function ( $key, $default = false ) {
+			static $options = [ 'prautoblogger_image_enabled' => '0' ];
+			return $options[ $key ] ?? $default;
+		} );
+
+		$provider = $this->createMock( \PRAutoBlogger_Image_Provider_Interface::class );
+		$provider->expects( $this->never() )->method( 'generate_image' );
+
+		$cost_tracker = $this->createMock( \PRAutoBlogger_Cost_Tracker::class );
+
+		$pipeline = new \PRAutoBlogger_Image_Pipeline( $provider, $cost_tracker );
+		$result   = $pipeline->generate_and_attach_images( 1, [ 'post_title' => 'Test' ] );
+
+		$this->assertArrayHasKey( 'cost_usd', $result );
+		$this->assertArrayHasKey( 'errors', $result );
+		$this->assertEmpty( $result['errors'] );
+	}
+
+	/**
+	 * Test generate_and_attach_images() returns cost and error array structure.
+	 */
+	public function test_generate_and_attach_images_returns_correct_structure(): void {
+		$provider = $this->createMock( \PRAutoBlogger_Image_Provider_Interface::class );
+		$provider->method( 'estimate_cost' )->willReturn( 0.05 );
+		$provider->method( 'generate_image' )->willReturn( [
+			'bytes'      => 'fake_image_data',
+			'mime_type'  => 'image/png',
+			'width'      => 1200,
+			'height'     => 630,
+			'model'      => 'flux-1-schnell',
+			'seed'       => 123,
+			'cost_usd'   => 0.05,
+			'latency_ms' => 2000,
+		] );
+
+		$cost_tracker = $this->createMock( \PRAutoBlogger_Cost_Tracker::class );
+		$cost_tracker->method( 'would_exceed_budget' )->willReturn( false );
+
+		$pipeline = new \PRAutoBlogger_Image_Pipeline( $provider, $cost_tracker );
+
+		// Mock file writing for sideload.
+		Functions\when( 'get_temp_dir' )->justReturn( '/tmp/' );
+		Functions\when( 'media_handle_sideload' )->justReturn( 42 );
+
+		$result = $pipeline->generate_and_attach_images( 1, [ 'post_title' => 'Test' ] );
+
+		$this->assertArrayHasKey( 'cost_usd', $result );
+		$this->assertArrayHasKey( 'errors', $result );
+		$this->assertIsFloat( $result['cost_usd'] );
+		$this->assertIsArray( $result['errors'] );
+	}
+
+	/**
+	 * Test that cost is accumulated when both images are generated.
+	 */
+	public function test_cost_is_accumulated_for_both_images(): void {
+		$provider = $this->createMock( \PRAutoBlogger_Image_Provider_Interface::class );
+		$provider->method( 'estimate_cost' )->willReturn( 0.05 );
+		$provider->method( 'generate_image' )->willReturn( [
+			'bytes'      => 'fake_image_data',
+			'mime_type'  => 'image/png',
+			'width'      => 1200,
+			'height'     => 630,
+			'model'      => 'flux-1-schnell',
+			'cost_usd'   => 0.05,
+			'latency_ms' => 2000,
+		] );
+
+		$cost_tracker = $this->createMock( \PRAutoBlogger_Cost_Tracker::class );
+		$cost_tracker->method( 'would_exceed_budget' )->willReturn( false );
+		$cost_tracker->expects( $this->exactly( 2 ) )->method( 'log_image_generation' );
+
+		$pipeline = new \PRAutoBlogger_Image_Pipeline( $provider, $cost_tracker );
+
+		Functions\when( 'get_temp_dir' )->justReturn( '/tmp/' );
+		Functions\when( 'media_handle_sideload' )->justReturn( 42 );
+
+		$result = $pipeline->generate_and_attach_images(
+			1,
+			[ 'post_title' => 'Test' ],
+			[ 'title' => 'Source' ]
+		);
+
+		// Cost should be accumulated from both images.
+		$this->assertGreaterThan( 0.05, $result['cost_usd'] );
+	}
+
+	/**
+	 * Test graceful handling when image generation fails.
+	 */
+	public function test_graceful_failure_when_image_generation_fails(): void {
+		$provider = $this->createMock( \PRAutoBlogger_Image_Provider_Interface::class );
+		$provider->method( 'estimate_cost' )->willReturn( 0.05 );
+		$provider->method( 'generate_image' )->willThrowException( new \Exception( 'API timeout' ) );
+
+		$cost_tracker = $this->createMock( \PRAutoBlogger_Cost_Tracker::class );
+		$cost_tracker->method( 'would_exceed_budget' )->willReturn( false );
+
+		$pipeline = new \PRAutoBlogger_Image_Pipeline( $provider, $cost_tracker );
+
+		$result = $pipeline->generate_and_attach_images( 1, [ 'post_title' => 'Test' ] );
+
+		// Should record error but return valid structure.
+		$this->assertIsArray( $result );
+		$this->assertNotEmpty( $result['errors'] );
+		$this->assertStringContainsString( 'API timeout', implode( ' ', $result['errors'] ) );
+	}
+}

tests/unit/Core/ImagePromptBuilderTest.php

@@ -0,0 +1,122 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_Image_Prompt_Builder.
+ *
+ * Validates prompt generation from article content and source data,
+ * including style suffix appending and HTML stripping.
+ *
+ * @package PRAutoBlogger\Tests\Core
+ */
+
+namespace PRAutoBlogger\Tests\Core;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class ImagePromptBuilderTest extends BaseTestCase {
+
+	protected function setUp(): void {
+		parent::setUp();
+
+		// Mock WordPress functions.
+		Functions\when( 'wp_strip_all_tags' )->alias( function ( $str ) {
+			return trim( strip_tags( $str ) );
+		} );
+		Functions\when( 'sanitize_text_field' )->returnArg();
+		Functions\when( 'get_option' )->alias( function ( $key, $default = false ) {
+			static $options = [];
+			return $options[ $key ] ?? $default;
+		} );
+	}
+
+	/**
+	 * Test build_article_prompt() generates a prompt from article title and content.
+	 */
+	public function test_build_article_prompt_from_content(): void {
+		$builder = new \PRAutoBlogger_Image_Prompt_Builder();
+
+		$article_data = [
+			'post_title'   => 'How to Train Your Dragon',
+			'post_content' => '<p>Dragons are fascinating creatures. Learn the secrets.</p>',
+		];
+
+		$prompt = $builder->build_article_prompt( $article_data );
+
+		$this->assertStringContainsString( 'How to Train Your Dragon', $prompt );
+		$this->assertStringContainsString( 'Dragons are fascinating', $prompt );
+		// Style suffix should be appended.
+		$this->assertNotEmpty( $prompt );
+		$this->assertGreaterThan( 50, strlen( $prompt ) );
+	}
+
+	/**
+	 * Test build_article_prompt() handles missing content gracefully.
+	 */
+	public function test_build_article_prompt_with_missing_content(): void {
+		$builder = new \PRAutoBlogger_Image_Prompt_Builder();
+
+		$article_data = [
+			'post_title' => 'Minimal Article',
+		];
+
+		$prompt = $builder->build_article_prompt( $article_data );
+
+		$this->assertStringContainsString( 'Minimal Article', $prompt );
+		$this->assertNotEmpty( $prompt );
+	}
+
+	/**
+	 * Test build_source_prompt() generates a prompt from Reddit data.
+	 */
+	public function test_build_source_prompt_from_reddit_data(): void {
+		$builder = new \PRAutoBlogger_Image_Prompt_Builder();
+
+		$source_data = [
+			'title'    => 'Help: My Robot Won\'t Stop Dancing',
+			'comments' => [
+				'Have you tried unplugging it?',
+				'Maybe it\'s just happy.',
+			],
+		];
+
+		$prompt = $builder->build_source_prompt( $source_data );
+
+		$this->assertStringContainsString( 'Robot', $prompt );
+		$this->assertStringContainsString( 'Dancing', $prompt );
+		$this->assertNotEmpty( $prompt );
+	}
+
+	/**
+	 * Test build_source_prompt() handles missing comments.
+	 */
+	public function test_build_source_prompt_without_comments(): void {
+		$builder = new \PRAutoBlogger_Image_Prompt_Builder();
+
+		$source_data = [
+			'title' => 'Standalone Title',
+		];
+
+		$prompt = $builder->build_source_prompt( $source_data );
+
+		$this->assertStringContainsString( 'Standalone Title', $prompt );
+		$this->assertNotEmpty( $prompt );
+	}
+
+	/**
+	 * Test that prompts don't exceed reasonable length.
+	 */
+	public function test_prompts_are_reasonably_sized(): void {
+		$builder = new \PRAutoBlogger_Image_Prompt_Builder();
+
+		$long_content = '<p>' . str_repeat( 'a', 5000 ) . '</p>';
+		$article_data = [
+			'post_title'   => 'Test',
+			'post_content' => $long_content,
+		];
+
+		$prompt = $builder->build_article_prompt( $article_data );
+
+		// Prompt should be under 500 chars (concept + style suffix).
+		$this->assertLessThan( 500, strlen( $prompt ) );
+	}
+}

tests/unit/Services/OpenRouterModelRegistryTest.php

@@ -0,0 +1,241 @@
+<?php
+/**
+ * Tests for PRAutoBlogger_OpenRouter_Model_Registry and its normalizer.
+ *
+ * Validates registry caching, idempotency, retry logic, stale fallback,
+ * capability filtering, and the normalize → find_model → get_models flow.
+ *
+ * @package PRAutoBlogger\Tests\Services
+ */
+
+namespace PRAutoBlogger\Tests\Services;
+
+use PRAutoBlogger\Tests\BaseTestCase;
+use Brain\Monkey\Functions;
+
+class OpenRouterModelRegistryTest extends BaseTestCase {
+
+	private const OPTION    = 'test_openrouter_model_registry';
+	private const TRANSIENT = 'test_openrouter_model_registry_cache';
+
+	protected function setUp(): void {
+		parent::setUp();
+
+		Functions\when( 'update_option' )->justReturn( true );
+		Functions\when( 'delete_option' )->justReturn( true );
+		Functions\when( 'is_wp_error' )->justReturn( false );
+		Functions\when( 'wp_remote_retrieve_response_code' )->justReturn( 200 );
+		Functions\when( 'wp_remote_retrieve_body' )->justReturn( '{"data":[]}' );
+	}
+
+	// ── Normalizer tests ────────────────────────────────────────
+
+	/**
+	 * Normalizer correctly maps input+output modalities → capability strings.
+	 */
+	public function test_normalize_maps_capabilities(): void {
+		$normalizer = new \PRAutoBlogger_OpenRouter_Model_Normalizer();
+		$raw        = [
+			[
+				'id'            => 'anthropic/claude-3.5-haiku',
+				'name'          => 'Claude 3.5 Haiku',
+				'context_length' => 200000,
+				'pricing'       => [ 'prompt' => '0.0000008', 'completion' => '0.000004' ],
+				'architecture'  => [
+					'input_modalities'  => [ 'text', 'image' ],
+					'output_modalities' => [ 'text' ],
+				],
+				'created'       => 1700000000,
+			],
+		];
+
+		$result = $normalizer->normalize( $raw );
+
+		$this->assertCount( 1, $result );
+		$model = $result[0];
+		$this->assertSame( 'anthropic/claude-3.5-haiku', $model['id'] );
+		$this->assertSame( 'Claude 3.5 Haiku', $model['name'] );
+		$this->assertSame( 'anthropic', $model['provider'] );
+		$this->assertSame( 200000, $model['context_length'] );
+		$this->assertEqualsWithDelta( 0.80, $model['input_price_per_m'], 0.01 );
+		$this->assertEqualsWithDelta( 4.00, $model['output_price_per_m'], 0.01 );
+		$this->assertContains( 'text→text', $model['capabilities'] );
+		$this->assertContains( 'text+image→text', $model['capabilities'] );
+	}
+
+	/**
+	 * Unknown modalities degrade to text→text, never empty capabilities.
+	 */
+	public function test_normalize_unknown_modalities_degrade_to_text(): void {
+		$normalizer = new \PRAutoBlogger_OpenRouter_Model_Normalizer();
+		$raw        = [
+			[
+				'id'           => 'custom/mystery-model',
+				'architecture' => [
+					'input_modalities'  => [ 'brainwaves' ],
+					'output_modalities' => [ 'hologram' ],
+				],
+			],
+		];
+
+		$result = $normalizer->normalize( $raw );
+		$this->assertSame( [ 'text→text' ], $result[0]['capabilities'] );
+	}
+
+	/**
+	 * Records without 'id' are silently skipped.
+	 */
+	public function test_normalize_skips_invalid_records(): void {
+		$normalizer = new \PRAutoBlogger_OpenRouter_Model_Normalizer();
+		$raw        = [
+			[ 'name' => 'orphan model without id' ],
+			'not an array',
+			[ 'id' => 'valid/model', 'name' => 'Valid' ],
+		];
+
+		$this->assertCount( 1, $normalizer->normalize( $raw ) );
+	}
+
+	/**
+	 * Results are sorted alphabetically by name.
+	 */
+	public function test_normalize_sorts_by_name(): void {
+		$normalizer = new \PRAutoBlogger_OpenRouter_Model_Normalizer();
+		$raw        = [
+			[ 'id' => 'z/zebra', 'name' => 'Zebra Model' ],
+			[ 'id' => 'a/alpha', 'name' => 'Alpha Model' ],
+			[ 'id' => 'm/mid', 'name' => 'Mid Model' ],
+		];
+
+		$result = $normalizer->normalize( $raw );
+		$this->assertSame( 'Alpha Model', $result[0]['name'] );
+		$this->assertSame( 'Zebra Model', $result[2]['name'] );
+	}
+
+	// ── Registry tests ──────────────────────────────────────────
+
+	/**
+	 * Idempotency: refresh(false) with a fresh payload skips HTTP.
+	 */
+	public function test_refresh_skips_when_fresh(): void {
+		// Simulate: fetched 1 hour ago, idempotency window = 12h.
+		$this->stub_get_option( [
+			self::OPTION . '_fetched_at' => time() - 3600,
+			self::OPTION               => [ [ 'id' => 'cached/model' ] ],
+			'prautoblogger_log_level'  => 'info',
+		] );
+
+		// wp_remote_get should NOT be called.
+		Functions\when( 'wp_remote_get' )->alias( function () {
+			throw new \RuntimeException( 'wp_remote_get should not be called' );
+		} );
+
+		$registry = new \PRAutoBlogger_OpenRouter_Model_Registry(
+			self::OPTION, self::TRANSIENT, 'https://test.example.com/models', 86400, 43200
+		);
+
+		$result = $registry->refresh( false );
+		$this->assertSame( 1, $result['count'] );
+	}
+
+	/**
+	 * refresh(true) bypasses idempotency and always fetches.
+	 */
+	public function test_refresh_force_fetches(): void {
+		$this->stub_get_option( [
+			self::OPTION . '_fetched_at' => time() - 60,
+			self::OPTION               => [],
+			'prautoblogger_log_level'  => 'info',
+		] );
+
+		$api_body = wp_json_encode( [
+			'data' => [
+				[ 'id' => 'fresh/model', 'name' => 'Fresh', 'architecture' => [ 'input_modalities' => [ 'text' ], 'output_modalities' => [ 'text' ] ] ],
+			],
+		] );
+
+		Functions\when( 'wp_remote_get' )->justReturn( [ 'response' => [ 'code' => 200 ] ] );
+		Functions\when( 'wp_remote_retrieve_response_code' )->justReturn( 200 );
+		Functions\when( 'wp_remote_retrieve_body' )->justReturn( $api_body );
+
+		$registry = new \PRAutoBlogger_OpenRouter_Model_Registry(
+			self::OPTION, self::TRANSIENT, 'https://test.example.com/models', 86400, 43200
+		);
+
+		$result = $registry->refresh( true );
+		$this->assertSame( 1, $result['count'] );
+	}
+
+	/**
+	 * get_models_with_capability filters correctly.
+	 */
+	public function test_capability_filtering(): void {
+		$models = [
+			[ 'id' => 'a', 'capabilities' => [ 'text→text' ] ],
+			[ 'id' => 'b', 'capabilities' => [ 'text+image→text', 'text→text' ] ],
+			[ 'id' => 'c', 'capabilities' => [ 'text→image' ] ],
+		];
+
+		// Serve from transient.
+		Functions\when( 'get_transient' )->alias( function ( $key ) use ( $models ) {
+			return $key === self::TRANSIENT ? $models : false;
+		} );
+
+		$registry = new \PRAutoBlogger_OpenRouter_Model_Registry(
+			self::OPTION, self::TRANSIENT
+		);
+
+		$text_to_text = $registry->get_models_with_capability( 'text→text' );
+		$this->assertCount( 2, $text_to_text );
+
+		$vision = $registry->get_models_with_capability( 'text+image→text' );
+		$this->assertCount( 1, $vision );
+		$this->assertSame( 'b', $vision[0]['id'] );
+	}
+
+	/**
+	 * find_model returns null for unknown models.
+	 */
+	public function test_find_model_returns_null_for_unknown(): void {
+		Functions\when( 'get_transient' )->justReturn( [] );
+		$this->stub_get_option( [ self::OPTION => [], 'prautoblogger_log_level' => 'info' ] );
+
+		$registry = new \PRAutoBlogger_OpenRouter_Model_Registry( self::OPTION, self::TRANSIENT );
+		$this->assertNull( $registry->find_model( 'nonexistent/model' ) );
+	}
+
+	/**
+	 * Stale-and-fetch-fails: serves option payload and flags admin notice.
+	 */
+	public function test_stale_fallback_on_fetch_failure(): void {
+		$cached_models = [ [ 'id' => 'stale/model', 'capabilities' => [ 'text→text' ] ] ];
+
+		$this->stub_get_option( [
+			self::OPTION . '_fetched_at' => time() - 100000,
+			self::OPTION               => $cached_models,
+			'prautoblogger_log_level'  => 'info',
+		] );
+
+		// Simulate network failure.
+		$wp_error = new \stdClass();
+		Functions\when( 'wp_remote_get' )->justReturn( $wp_error );
+		Functions\when( 'is_wp_error' )->justReturn( true );
+		$wp_error->get_error_message = function () {
+			return 'Connection timed out';
+		};
+		Functions\when( 'wp_remote_get' )->alias( function () {
+			return new \WP_Error( 'http_request_failed', 'Connection timed out' );
+		} );
+
+		// Accept that update_option will be called for the stale flag.
+		Functions\when( 'update_option' )->justReturn( true );
+
+		$registry = new \PRAutoBlogger_OpenRouter_Model_Registry(
+			self::OPTION, self::TRANSIENT, 'https://test.example.com/models', 86400, 43200
+		);
+
+		$result = $registry->refresh( true );
+		$this->assertSame( 1, $result['count'] );
+	}
+}
+