prautoblogger/docs/adr/0001-editorial-illustration-image-style.md

ADR-0001: Editorial illustration image style — pivot from comic to text-free illustration with caption-as-HTML

• Status: Accepted
• Date: 2026-05-29
• Deciders: CTO, Engineer PRAutoBlogger
• Supersedes: —
• Superseded by: —
• Related: ARCHITECTURE.md §#20; CHANGELOG.md [0.16.0]; PR #146 (d00e746); docs/proposals/2026-05-29-image-pipeline-in-plugin-brief.md; ARCHITECTURE.md §#21 (v0.17.0 deterministic composer, the follow-on commit)

---

Context

PRAutoBlogger generates two AI images (A/B pair) for each article and publishes them as featured images. From the initial comic-strip launch (commit b17ed47, feat: switch to single-panel newspaper comic style for article images) through v0.15.x, the image style was a single-panel newspaper comic — the rewriter LLM was asked to produce a comic gag or visual pun, and the result was appended to a style suffix and sent to the diffusion model.

By April 2026 two problems had accumulated:

1. Text legibility. Small diffusion models (FLUX.1 schnell is the default since v0.9.0 at ~$0.0006/image) cannot reliably render readable text inside an image. Comic panels depend on legible speech bubbles or captions burned into the image; both were routinely garbled (confirmed in the 2026-04-21 A/B finding documented in ARCHITECTURE.md §#21).

2. Caption path already existed. A separate HTML caption below the image had been extracted as early as commit 214f57b (Separate comic captions from generated images, 2026-04-18). The scene/caption split in Image_Scene_Parser was already live, meaning there was an established path for readable text that did not depend on the diffusion model rendering it.

Together these created pressure to stop asking the diffusion model to render text at all, and instead shift all readable copy to the HTML caption path that was already in place.

Decision drivers

1. Image quality on default model. FLUX.1 schnell (the default since v0.9.0) produces garbled text in generated images. A style that depends on readable in-image text degrades silently on the model we actually ship.
2. Editorial trust signal. Peptide Repo's editorial direction is science-informational; comic gags undercut the authority the site needs for health-adjacent content.
3. Reuse the existing caption path. The scene/caption split and HTML caption path were already live; the change is a prompt rewrite + template substitution with no new infrastructure.
4. Admin configurability. The style suffix was a single string appended to every prompt; a template with a named substitution token ({{ topic_summary }}) is more maintainable and admin-overridable without a code deploy.
5. Cost and provider neutrality. The change is prompt-only; provider, model, and pricing are unchanged.

Options considered

Option A — Keep the comic style, fix text rendering per-model

Ask the rewriter LLM to omit text from comic panels (no speech bubbles, no caption burns), and describe a visual scene instead. Keep the style suffix pattern.

Pros:

• Minimal code change — just a prompt edit.
• Comic aesthetic is recognisable and differentiating.

Cons:

• Does not solve the underlying mismatch: the style suffix is a static string that gives no per-article context to the diffusion model. The rewriter scene still has no slot to insert topic-specific imagery.
• Comic gags require the LLM to invent a joke per peptide, which is inconsistent in tone.
• Comic aesthetic conflicts with the editorial trust direction for health content.

Option B — Pivot to text-free editorial scientific illustration + template substitution (chosen)

Change the rewriter system prompt so the LLM emits a concise 1-2 sentence topic/mechanism summary as the SCENE — one concrete centered focal subject, no text, no people-as-gag, no logos. Replace the style suffix with an editable template (prautoblogger_image_style_template) that contains a single {{ topic_summary }} token filled per-article by PRAutoBlogger_Image_Template_Filler. The CAPTION line from the scene/caption split continues to flow to the HTML-caption-below-image path unchanged.

Pros:

• Diffusion model is never asked to render text; garbled-text failures are eliminated.
• The editorial scientific illustration style is consistent with the site's authority positioning.
• Template substitution gives admins a single editable field to control the entire visual style without touching the per-article rewriter logic.
• Degradation is explicit: missing token → append + warning; empty summary → style-only prompt; a blank prompt is never sent to the provider.
• Provider, model, and cost are unchanged.

Cons:

• Breaks the comic gag aesthetic for any site running PRAutoBlogger in a context where that was intentional (low risk for this deployment).
• The old prautoblogger_image_style_suffix option must be migrated (handled via one-time migration prautoblogger_migrated_style_template_v0160 and mirroring to _deprecated for one cycle).

Option C — Generate text overlays in PHP (deterministic composer only)

Skip the style change; solve legibility by compositing text onto images in PHP after the diffusion model runs.

Pros:

• Diffusion model input is unchanged (comic style preserved).
• Composited text is always readable regardless of model.

Cons:

• Compositing a comic-style gag is much harder than compositing a caption band (arbitrary layout vs. a fixed panel at the bottom).
• Does not address the editorial direction mismatch.
• The deterministic PHP composer (ARCHITECTURE.md §#21) was already planned as a follow-on commit specifically for OG/social variants — pursuing it as the sole fix conflates two separate problems.

Decision

Option B — pivot to text-free editorial scientific illustration with caption-as-HTML and template substitution.

This was shipped as v0.16.0 (2026-05-29, PR #146, commit d00e746). The changes are entirely in the prompt layer:

• Image_Prompt_Builder::REWRITER_SYSTEM_PROMPT now asks for a concise topic/mechanism SCENE and keeps the CAPTION line for the HTML path.
• PRAutoBlogger_Image_Template_Filler::fill() replaces the old trim($scene . ' ' . $style_suffix) concat at all three entry points (build_article_prompt, build_source_prompt, build_fallback_prompt).
• New admin setting prautoblogger_image_style_template with single-token validation replaces the Style Suffix field.
• One-time migration preserves the old suffix value for one cycle.

The deterministic PHP composer for OG/social branding (ARCHITECTURE.md §#21) was deliberately deferred to a follow-on commit (v0.17.0, #152) so that the prompt-only change could ship and be verified first.

Consequences

Accepted benefits:

• Garbled-text image failures are eliminated on the default FLUX.1 schnell model.
• The editorial scientific illustration style is consistent with the site's health-content positioning and sustainable across future model changes.
• The template + token pattern makes style updates admin-configurable without code changes.

Accepted costs:

• The comic aesthetic is gone and cannot be restored by toggling a setting; switching back requires a prompt and template change.
• The prautoblogger_image_style_suffix option is deprecated; the migration runs once on upgrade and the old option is not deleted until a future cycle.

Follow-up created:

• ARCHITECTURE.md §#21 (v0.17.0): deterministic PHP image composer to composite branded OG and square card variants — necessary because the social/OG image travels without the HTML caption and therefore needs text burned in by PHP, not by the diffusion model.