# Image Provider Audit + Caption Safe-Zone Pattern

Use this reference when a social-short pipeline needs to verify AI image provenance/quality tiers and harden mobile subtitle layout before approving a preview/final.

## Image provider audit checklist

1. Inspect Hermes config, not memory or assumptions:
   - `image_gen.provider`
   - `image_gen.model`
   - provider-specific subconfig if present, e.g. `image_gen.openai-codex.model`
2. Inspect registered image providers/capabilities from the provider registry:
   - available providers
   - available model tiers
   - active provider resolution/fallback behavior
3. For ChatGPT/Codex image generation in Hermes, the relevant practical tiers are:
   - `gpt-image-2-low`
   - `gpt-image-2-medium`
   - `gpt-image-2-high`
4. For premium keyframes/styleframes, prefer the highest available reasonable tier (`gpt-image-2-high` when available). For deterministic UI/mockups, do not use image generation.
5. Verify recent image runs by cache filenames and metadata. The Codex backend saves PNGs under `$HERMES_HOME/cache/images/` with names like:
   - `openai_codex_gpt-image-2-medium_...png`
   - `openai_codex_gpt-image-2-high_...png`
6. If needed, run exactly one neutral capability test image, not a batch. Save provider/model/quality/size/response metadata, file path, SHA256, and resolution.
7. Inspect PNG chunks for provenance. Codex/OpenAI PNG outputs may contain a `caBX` JUMBF/C2PA chunk (`jumb`, `jumdc2pa`, `urn:c2pa:`). PIL may show no normal `info` keys; raw chunk inspection is more reliable.
8. Note that C2PA/provenance in the original PNG cache is not reliably preserved after converting into JPEG contact sheets or MP4 renders.

## AutoShorts image policy

Use image generation only for approved premium styleframes/keyframes. Keep renderer-owned/deterministic assets for:

- fake invoices
- fake emails
- payment-route cards
- UI mockups
- documents with labels/numbers/text

Recommended policy values:

```text
allowed_image_provider = openai-codex
preferred_image_model = best_available_gpt_image_model
preferred_quality = highest_available_reasonable
max_styleframes_per_scene_without_approval = 3
max_retries_per_styleframe = 1
no_random_batches = true
no_ai_images_for_mockups_when_deterministic_renderer_is_better = true
```

## Caption safe-zone implementation pattern

Hard rules for mobile subtitles:

- No caption text may exceed the left/right safe area.
- Use max width around 86–90% of video width.
- At 1080px width, keep at least 60px horizontal margin; 70px is safer.
- Keep bottom margin platform-safe; for 1080x1920, around 260–310px works better than very low captions.
- Maximum two lines per segment.
- Prefer 4–7 words per static phrase segment.
- If a phrase would exceed two lines, split the phrase earlier.
- Dynamically shrink font size only down to a minimum; after that, split.
- Active-word highlight geometry must also fit inside safe bounds.
- Treat long domains like `example-company.com` as special width stress tests.

## Tests to add

Add tests for:

- long phrase wraps into two lines
- caption never exceeds safe width
- active word highlight never exceeds bounds
- no word clipped at left/right edge
- max two lines enforced by earlier phrase splitting
- bottom safe-zone respected
- long domain strings wrap or shrink safely

## Preview QA

After rendering, produce:

- MP4 preview
- contact sheet at known problem timestamps
- single subtitle-style preview frame
- manifest with file path, SHA256, size, duration/resolution, caption validation result, and delivery metadata

Use visual QA on the contact sheet. If any renderer-owned text card is clipped, fix it too; otherwise the preview still feels broken even if the formal subtitles pass.