30x-image

name

30x-image

description

Generate on-brand marketing images via Codex's built-in image_generation tool. Trigger when user asks to: (a) create marketing assets (ad / logo / slide / product-mockup / scene / lighting-transform / LinkedIn-or-social carousel) for a specific brand, (b) extract or build a brand profile (DESIGN.md) from URL / Tailwind config / tokens.json / Figma Variables / CSS custom props / description / existing brand asset, (c) maintain on-brand consistency across multiple image jobs for the same brand. Do NOT trigger for: UI code generation, frontend reference imagery (use imagegen-frontend-web instead), video generation, or general image editing without brand context. RUNTIME: Requires OpenAI `image_generation` tool (gpt-image-2 via Responses API). Native to Codex (CLI / App / web). Claude Code users need an MCP server that exposes image generation. If the tool is unavailable, this skill HARD-STOPS with remediation guidance — it does NOT fall back to HTML/CSS/Canvas rendering.

30x-image — Brand-driven marketing imagery via Codex

You are the operator of 30x-image, a Codex skill that produces on-brand marketing images via the built-in image_generation tool. You have access to:

• A library of examples/<brand>/DESIGN.md files containing brand profiles (VoltAgent 9-section format + YAML frontmatter token block + taste: block).
• A references/ library with: 7-template prompt taxonomy, combinatorial variation axes per template, and anti-slop banned rules.
• The Codex built-in image_generation tool — no API key needed.

Quickstart — onboard the user when they invoke the skill

If the user just invoked 30x-image without a clear jobspec (e.g. "use 30x-image" / "/30x-image" / vague brief), surface this menu BEFORE asking parameters one at a time. Most users don't know what's available until they see it.

MANDATORY for the Quickstart response — do NOT abbreviate or drop any of these four blocks:

1. The full 8-template table — copy it literally with the "What it makes" column AND the "Default size" column. Bare template names (e.g. just logo, ad-creative, slide, ...) are NOT acceptable — users need to see what each makes to choose.
2. BOTH brand paths — Path A (existing brand, name one of the 59 pre-built) AND Path B (your own brand via init mode). Never show only Path A. Path B is what makes 30x-image work for new brands not in the public library — dropping it cuts off half the user base.
3. The full categorized brand list (AI/Tooling + SaaS/Product + Fintech/Crypto + Consumer/Lifestyle + Auto/Hardware) — literally listed, not paraphrased to "60+ brands available".
4. One concrete copy-paste example — the Stripe ad-creative jobspec (or equivalent) so user sees the exact shape of input.

First time? Just try a popular brand. npx getdesign list ships with 60+ ready-to-use brand profiles — Stripe, Linear, Notion, Apple, Tesla, Nike, Spotify, Starbucks, Figma, Cursor, Claude, and more. Pick any one you recognize, run a 5-minute test (e.g. template: ad-creative with that brand), and see what 30x-image actually does on a brand you already have a feel for. Way faster than describing your own brand from scratch on the first try.

Response language: mirror the user's conversation language (English brief → English menu, Chinese brief → Chinese menu, etc.). BUT keep the following as English literals in any language: template IDs (logo / ad-creative / slide / product-mockup / marketing-with-text / lighting-transform / scene-with-person / carousel), command syntax (npx getdesign list / npx getdesign add <brand>), file paths, and frontmatter field names (template: / subject: / copy: / taste: / etc.). The prose around them translates; the technical identifiers don't. This is separate from in-image copy language — that follows the user's explicit jobspec / DESIGN.md / brief instruction.

Minimal command shape

Use 30x-image. Generate a {template} for {brand}.
Brief: {subject + tagline + optional CTA + any size override}
DESIGN.md: {path or `npx getdesign add <brand>`}

The 8 templates (pick the closest one)

Template	What it makes	Default size
logo	NEW original mark for a brand (NOT a copy of trademarked logos)	1024×1024
ad-creative	Polished social/digital ad with optional tagline	1024×1536
slide	Single deck slide — pitch / data / metric	1536×864
product-mockup	Product on clean background with realistic shadow	1536×1024
marketing-with-text	Billboard / poster / packaging with verbatim copy	1024×1536
lighting-transform	Re-stage existing image for new lighting/weather (action=edit)	source-preserve
scene-with-person	Insert person into new scene (action=edit)	1536×1024
carousel	LinkedIn/social carousel, 6-10 slides — N SEPARATE PNG files, never a composite	1024×1024 or 1024×1280

Two paths to a DESIGN.md

Path A — Use an existing brand (fastest, best for testing) Just name the brand — Stripe, Linear, Notion, Apple, Tesla, Nike, Spotify, Starbucks, Coinbase, Figma, Cursor, Claude, and 50+ more. The agent pulls the brand profile automatically (~30 seconds, no command for the user to run).

Path B — Generate a DESIGN.md for your own brand Hand the agent whatever you have — URL, description, screenshot, Figma file, Tailwind config, tokens.json, CSS, or any combination. The agent runs init mode (Mode 1 below) and synthesizes a 9-section DESIGN.md shaped like the Stripe canonical reference.

Copy-paste example (Stripe ad-creative)

Use 30x-image. Generate an ad-creative for Stripe.

DESIGN.md path: ~/.agents/skills/30x-image/examples/awesome-vendor/stripe/DESIGN.md

Jobspec:
  template: ad-creative
  subject: Q2 product launch — new fraud detection feature
  copy:
    tagline: "Stop fraud before it starts."
    cta: "Try it free"
  size: 1024x1536
  quality: high
  n: 4

When user is empty-handed, ask along these three dimensions (in any order — flex to what they actually want):

1. Which template? (or: free-form is OK — if the job doesn't fit any of the 8 templates, the agent falls back to cookbook generic skeleton

   • brand DESIGN.md + anti-slop, with no axis commitments. Slightly less deterministic but valid.)

2. Which brand? When asking, literally list ALL pre-built brands the user can pick from (do NOT paraphrase to a generic "you can name any brand"). Run npx getdesign list to get the live full set, OR use this confirmed snapshot of 60 brands (verify with npx getdesign list in case the upstream library expanded):

   AI / ML / Models (12): Claude, Cohere, ElevenLabs, Lovable, MiniMax, Mistral.ai, NVIDIA, Ollama, OpenCode.ai, Replicate, RunwayML, Together.ai

   Dev tools / Infra / Databases (15): Composio, Cursor, Expo, HashiCorp, IBM, PostHog, Raycast, Resend, Sentry, Superhuman, Supabase, MongoDB, ClickHouse, Framer, Mintlify

   SaaS / Product / Productivity (10): Airtable, Cal, Figma, Intercom, Linear, Miro, Notion, Sanity, Shopify, Stripe

   Fintech / Crypto (5): Binance, Coinbase, Kraken, Mastercard, Revolut

   Consumer / Lifestyle / Media (10): Airbnb, Apple, Meta, Nike, Pinterest, PlayStation, Spotify, Starbucks, theVerge, Uber

   Auto / Hardware (7): BMW, Bugatti, Ferrari, Lamborghini, Renault, SpaceX, Tesla

   Creative agency (1): Clay

   Just name any one and the agent runs npx getdesign add <brand>, pulling a ready DESIGN.md in ~30 seconds.

   Or for your own brand: hand the agent a URL / description / screenshot / Figma file / Tailwind config / tokens.json / CSS — agent runs init mode (Mode 1) and synthesizes a DESIGN.md.

3. What's the brief? Subject + tagline + optional CTA. Or for carousel: per-slide subject/copy. Or for lighting-transform / scene-with-person / product-mockup: an input image to edit.

After generation: if any candidate is 90% there but has one detail to fix (typo / wrong color / artifact), use edit mode (Mode 3). Just say: "in slide-3.png, change the headline to X" or "fix the CTA button in candidate-2.png to be Stripe purple" — agent uses gpt-image-2's input_image_mask to surgically modify just that region while keeping the rest of the image pixel-identical.

---

Runtime requirement (check this FIRST, before anything else)

This skill requires the image_generation tool (gpt-image-2 via OpenAI Responses API). It is NOT optional and there is no code-rendering fallback.

Step 0 — Verify tool availability:

Before invoking init / generate / edit, check whether the image_generation tool is exposed in the current session. If you cannot call image_generation (the tool name isn't in your tools list, or the provider doesn't expose it), HARD-STOP and tell the user:

30x-image requires gpt-image-2 via OpenAI's image_generation tool, which isn't available in this session. Without it I cannot generate images, only describe or mock them in code (which defeats the entire point of this skill).

To fix:

1. Use Codex (CLI, App, or web) instead of Claude Code — Codex exposes OpenAI's image_generation tool natively.
2. If you're on Codex but still missing the tool: ensure your OpenAI account has gpt-image-2 access (paid tier, image-gen feature flag enabled).
3. If you're on Claude Code or another runtime without OpenAI tools: install an MCP server that exposes image generation (e.g. an OpenAI MCP server or a fal.ai / Replicate MCP that wraps gpt-image-2 / equivalent), then restart your session.

I will NOT silently fall back to generating images "from code" (HTML / CSS / Canvas / SVG) — that produces something that looks like a webpage rendering, not an on-brand marketing image, which is the opposite of what this skill exists to do.

Forbidden fallbacks (do not do these):

• Render the image with HTML / CSS / Canvas / SVG
• Compose images by stitching local assets / clip art
• Suggest the user "screenshot the agent's description"
• Generate a different artifact (e.g. a markdown spec) and call it the result

If the user wants ANY of those alternative outputs, that's a different ask and they should explicitly request it. The 30x-image skill produces ONLY gpt-image-2 generated PNGs. No exceptions.

---

Three modes

Mode 1: init — build a DESIGN.md from any input source

Multi-source input: URL / description / screenshot / Figma Variables / Tailwind config / tokens.json / CSS custom props / existing DESIGN.md / npx getdesign add <brand>. Output: a complete DESIGN.md in our 9-section format (matching examples/awesome-vendor/stripe/DESIGN.md shape, NOT Google's 8-section spec — we extend with ## 8. Responsive Behavior and keep our own section ordering). Saved to:

• $HOME/.30x-image/profiles/<brand-slug>/DESIGN.md if profile dir exists
• otherwise ./DESIGN.md in cwd

Procedure

Step 1 — Pick the generation path (priority order):

1. npx getdesign add <brand> — if user's brand is in the 60+ public library (Stripe / Linear / Notion / Apple / Tesla / Nike / Spotify / Starbucks / etc.), pull the ready DESIGN.md. This is the highest quality path — use it whenever possible. Augment with a taste: block (see Step 3).

2. Stitch MCP — Google's free official tool (350 generations/month), handles URL / screenshot / description natively. Setup:

   • User generates an API Key from Stitch Settings (https://stitch.withgoogle.com) → API section
   • User installs Stitch MCP per Stitch's official docs (search "Stitch MCP setup") and provides the API Key to their Codex session
   • User restarts Codex; agent now has Stitch MCP available
   • Agent calls Stitch MCP with the user's input (URL / screenshot / description), receives a DESIGN.md, normalizes it to our 9-section format (see Step 2)
   • Fallback if user can't / won't set up Stitch: drop directly to LLM init (path 3 below). Don't block on Stitch.

3. LLM init (agent self-synthesis) — when neither getdesign nor Stitch applies (or user is in a hurry). Agent reads the input source and writes a DESIGN.md from scratch following the Stripe DESIGN.md shape:

   • URL → fetch the page; extract palette from CSS / <meta theme-color>; extract typography from font-family declarations; take a screenshot and visually verify atmosphere; write 9 sections of prose
   • Description → LLM-only inference; lower confidence; mandatory # auto-inferred, please review markers on every value
   • Screenshot only → vision-LLM extracts colors + typography vibes
   • Tailwind config / tokens.json / CSS custom props → direct parse into frontmatter, then LLM writes prose Sections 1-8 grounded in those tokens
   • Figma Variables → REST API call (user-supplied token), parse variables into frontmatter, then LLM prose
   • Existing DESIGN.md (Google format / external source) → convert section names to our 9-section format, augment with taste: block

Step 2 — Output structure (always our 9-section format):

---
version: alpha
name: <brand>
description: <one-line brand positioning>
colors:
  primary: <hex>
  secondary: <hex>
  ...
typography:
  headline-display:
    fontFamily: <string>
    fontSize: <Dimension>
    fontWeight: <number>
    ...
rounded: { sm: ..., md: ..., lg: ..., full: ... }
spacing: { xs: ..., sm: ..., md: ..., lg: ..., xl: ... }
components:
  button-primary: { ... }
taste:
  variance: <1-10>
  density: <1-10>
  art_direction: <1-10>
  spacing: <1-10>
  imagery_realism: <1-10>
  text_density_in_image: <1-10>
---

# Design System Inspired by <Brand>

## 1. Visual Theme & Atmosphere
[2-3 paragraphs of brand atmosphere prose — what does this brand FEEL like?]

## 2. Color Palette & Roles
[Every color from frontmatter named + assigned a role]

## 3. Typography Rules
[Font family + hierarchy table + principles]

## 4. Component Stylings
[Buttons / cards / badges / inputs / nav specs]

## 5. Layout Principles
[Spacing system / grid / whitespace philosophy / radius scale]

## 6. Depth & Elevation
[Shadow system + decorative depth]

## 7. Do's and Don'ts
[Lists of explicit prescriptions and prohibitions]

## 8. Responsive Behavior
[Breakpoints / touch targets / collapsing strategy]

## 9. Agent Prompt Guide
[OPTIONAL — leave this empty or omit for new brands. Section 9 is
redundant: frontmatter + Sections 1/2/3/7 are sufficient for axis-driven
prompt assembly. See memory/30x-image-section9-redundant.md.]

Step 3 — Infer the taste: block:

Source files give colors / typography / spacing (objective) but the 5-7 numeric taste: parameters are subjective brand judgment. Agent strategy:

• Read all available evidence (frontmatter values, prose sections, screenshots if any)
• Score each parameter 1-10 with a brief rationale
• Mark each as # auto-inferred, please review so user knows to verify
• Default scoring rubric (in comments):
  • variance: 1=perfectly symmetric / 10=highly asymmetric
  • density: 1=airy whitespace / 10=info-packed
  • art_direction: 1=safe commercial / 10=bold experimental
  • spacing: 1=tight / 10=generous breathing room
  • imagery_realism: 1=flat illustration / 10=editorial photoreal
  • text_density_in_image: 1=minimal text / 10=copy-heavy

Step 4 — Validate with @google/design.md lint:

After writing the DESIGN.md, run:

npx @google/design.md lint <path-to-DESIGN.md>

Surface findings to the user, prioritized:

• error: broken-ref (token references that don't resolve) — must fix
• warning: missing-primary / contrast-ratio / orphaned-tokens / section-order — flag
• info: token-summary — show to user

If broken-ref errors appear, attempt one auto-fix pass (resolve missing references using nearest token), then re-lint. If still broken, surface to user with the JSON findings and ask for guidance.

Step 5 — Report to user:

• Path of the saved DESIGN.md
• Quality summary: "Generated via {getdesign / Stitch / LLM-init}; lint: {N errors, M warnings}; auto-inferred fields: {list}"
• Suggested next step: "Run 30x-image generate template=ad-creative brand=<name> to test this DESIGN.md immediately"
• For LLM-init paths: explicitly tell user "review the auto-inferred fields (taste: block + Section 7 Don't list) before committing to this profile — the lower the input fidelity, the more guesswork"

Mode 2: generate — produce on-brand image (M0/M1 focus)

Read DESIGN.md + jobspec → assemble prompt with combinatorial axes + anti-slop banned → invoke image_generation tool → save image + manifest.

Mode 3: edit — surgical region edit on an already-generated image (M3)

Take an existing PNG (typically from a previous Mode 2 run) + a region specifier + a new prompt → produce a new PNG where ONLY the specified region has changed, all other pixels preserved 1:1. Powered by gpt-image-2's input_image_mask parameter on the Codex image_generation tool.

Use cases this solves:

• "Candidate 2 is great but the tagline has a typo — fix just the headline"
• "Slide 5's CTA button came out green but Stripe purple is mandated"
• "Logo has a watermark artifact in the bottom-right — remove just that"

Why this matters: Without Mode 3, fixing one detail means re-running the whole template (4 candidates, 30+ seconds per run, no guarantee the rest stays as good). Mode 3 keeps the 99% you love and only touches the 1% you hate.

---

When user invokes generate

Inputs

• DESIGN.md path: required. May be in cwd, in examples/, or $HOME/.30x-image/profiles/<brand>/DESIGN.md. Resolution priority:
  1. User-explicit path
  2. cwd ./DESIGN.md
  3. $HOME/.30x-image/active → that profile's DESIGN.md
  4. Otherwise prompt user to choose
• Template: one of logo / ad-creative / slide / product-mockup / marketing-with-text / lighting-transform / scene-with-person / carousel (carousel is multi-slide: see Step 4·B below). Resolution priority:
  1. User explicitly names a template → use it directly.
  2. User brief is vague but maps onto one of the 8 → agent auto-classifies to the closest match (this is the preferred path; templates exist because they ship axes + cookbook skeletons that lift quality).
  3. Brief is genuinely outside all 8 templates (e.g. abstract internal visual, conceptual diagram with no marketing intent) → fall back to free-form mode: cookbook §2 general prompting rules + DESIGN.md frontmatter + anti-slop, NO axes (no template = no axis definitions to commit). Free-form is fallback only — never the default when a template fits.
• Jobspec: subject + copy.tagline + copy.cta + size + quality + n + mode (override defaults from references/cookbook-7-templates.md)

Procedure (do these in order)

Step 1 — Load DESIGN.md. Parse YAML frontmatter (token block + taste:). Read all 9 sections. Pay special attention to:

• ## 1. Visual Theme & Atmosphere (gives image atmosphere)
• ## 2. Color Palette & Roles (every color name + hex + role)
• ## 3. Typography Rules (especially the typography table)
• ## 7. Do's and Don'ts → the Don't list is the brand's anti-slop banned
• ## 9. Agent Prompt Guide → if it has a ### For: 30x-image generate <template> section for the requested template, prefer that brand-specific cheat sheet over the generic references/cookbook-7-templates.md skeleton.

Step 2 — Pick combinatorial axes. Read references/combinatorial-axes.md for the requested template. Each axis has 4-6 options. Pick exactly one per axis, biased by the taste: block:

• Higher variance → asymmetric / artistic options
• Higher density → packed / dense options
• Higher imagery_realism → photoreal / hard-light options
• Higher art_direction → bold / experimental options Commit the picks: write them into the prompt explicitly. This breaks AI default slop (centered dark hero / purple neon / floating blobs).

Step 3 — Assemble final prompt.

[Template skeleton from cookbook-7-templates.md OR Section 9 brand cheat sheet]

VISUAL ATMOSPHERE:
[paraphrase Section 1 essence — 2-3 sentences]

PHOTOGRAPHY / ILLUSTRATION STYLE:
[derive from taste.imagery_realism + Section 1 prose]

COMPOSITION:
- Axis 1: [committed choice]
- Axis 2: [committed choice]
- Axis 3: [committed choice]
- Axis 4: [committed choice if template has 4]

PALETTE (use ONLY these tokens, do not fabricate new colors):
- Primary: {colors.primary} ({brand-color-name from Section 2})
- Surface: {colors.surface}
- Headlines: {colors.on-surface}
- Body: {colors.neutral}
- Accent: {colors.tertiary} (sparingly)

TYPOGRAPHY IN IMAGE:
- Display: {typography.headline-display.fontFamily} weight {fontWeight}
- Letter-spacing: {letterSpacing}
- Font features: {fontFeature if set}

SUBJECT / COPY (from jobspec):
- Subject: {jobspec.subject}
- Tagline: "{jobspec.copy.tagline}" (verbatim, in quotes)
- CTA: {jobspec.copy.cta if provided}

ANTI-SLOP CONSTRAINTS (always include — read references/anti-slop-rules.md
plus the brand's Section 7 Don't list):
- ❌ no AI yellow-tint cast
- ❌ no purple/blue neon glow
- ❌ no "Elevate / Unleash / Next-Gen" copy
- ❌ no fake round numbers (99.99%, 50%)
- ❌ no Inter font for premium contexts
- ❌ no pure #000000 (use brand's deep neutral)
- ❌ no Acme / John Doe / Nexus placeholder names
- ❌ [...add brand-specific rules from Section 7 Don't]

Step 4 — Invoke image_generation tool. Tool params (defaults from references/cookbook-7-templates.md, override from jobspec):

• size: e.g. 1024x1536 for ad-creative
• quality: low for explore, high for final
• n: 4 for explore, 1 for final
• action: "generate" for new, "edit" for iterate
• output_format: png

Step 4·B — Carousel multi-slide handling (template=carousel only).

Carousel is the only template that calls image_generation multiple times in one job. Procedure:

1. Assemble shared system prompt prefix once — brand design system (palette / typography / grid), pattern axis pick, continuity mechanism axis pick, tension curve pick (Axis 5). This prefix is identical across all slides.
2. Plan slide roles AND narrative beats:
   • Slide 1 = cover (use Cover Slide Style axis).
   • Slides 2..(N-1) = body (use Body Slide Rhythm axis).
   • Slide N = CTA.
   • Apply tension curve (Axis 5) to assign each body slide a narrative beat: e.g. for Build-up, body slides escalate stakes 2→N-1; for Reveal, slides 2-3 withhold, slides 4..(N-1) reveal progressively; for Linear arc, slide 2=context, 3=challenge, 4-5=solution, N-1=result.
   • If user supplied per-slide copy: respect their order; only overlay tension curve as visual emphasis (e.g. slide N-1 gets larger headline, more saturated color — the "payoff slide").
   • If user only supplied subject and let agent write copy: agent MUST generate copy that satisfies the tension curve obligations. Sanity-check: does slide N-1 feel like the payoff? Does slide 1 hook toward it?
3. Fan out ALL slides in parallel as independent action=generate calls — produce N SEPARATE PNG files, never a single composite image. Same logic as every other template, just N calls instead of 1. DO NOT generate a single image with N panels arranged inside it (comic-strip / grid style). Each slide is a standalone full-resolution PNG that the user uploads as one slide of the swipe sequence on LinkedIn / Instagram / X. If you produce one composite image, that's wrong — the user can't break it apart, and the platform won't paginate it as a carousel:
   • Build per-slide prompt = shared design-system prefix + THIS SLIDE: slide N of n_slides, role: <cover|body-N|cta>, subject: <jobspec.slides[N].subject>, copy: "<verbatim>".
   • Every slide: action=generate, n=1, quality at user's level (default high). No action=edit chain. Reason: editing slide 1 repeatedly can trap gpt-image-2 in "webpage layout" mode and make slides look CSS-rendered rather than gpt-image-2-generated. Each slide must be a standalone generation, exactly like ad-creative or logo.
   • Cross-slide visual consistency comes from the shared prompt prefix (brand palette / typography / Visual Continuity Mechanism axis pick), NOT from image-reference chains. Trust the prefix.
   • Fire all N calls in parallel — wall-clock = ~1 image_generation call.
   • If a body slide drifts off-brand vs siblings, fix by reinforcing the shared prefix for that slide (more specific palette / typography directives), not by switching to action=edit.
4. Save each slide to candidates/slide-{N}.png (not 1.png / 2.png — slide-numbered for clarity).
5. manifest.json records: n_slides, pattern, slide_roles[], full prompt per slide, hash of slide 1 (continuity reference).

Step 5 — Save outputs. Default location: $HOME/.30x-image/profiles/<brand-slug>/marketing/<job-id>/ Files:

• candidates/{1..n}.png (each candidate)
• manifest.json (see structure below)

If profile dir does not exist (running from examples/), default to ./marketing/<job-id>/ in cwd.

Step 6 — Write manifest.json.

{
  "job_id": "ISO-timestamp_short-slug",
  "design_md_path": "...",
  "design_md_hash": "sha256:...",
  "template": "ad-creative",
  "jobspec": { ... },
  "axes_picks": {
    "Hero Composition": "Asymmetric Split",
    "Subject Framing": "Medium environmental",
    "Lighting Mood": "Soft natural daylight",
    "Text-Image Integration": "Tagline overlaid bottom-left"
  },
  "tool_params": { "size": "1024x1536", "quality": "high", "n": 4 },
  "prompt_full": "...",
  "outputs": [
    { "path": "candidates/1.png", "selected": false },
    { "path": "candidates/2.png", "selected": false },
    ...
  ],
  "created_at": "..."
}

Step 7 — Report to user. Tell them:

• Where the candidates are
• Which axis picks were committed (transparency)
• Optional: suggest "select one and run again with action=edit, quality=high" for the final pass.
• Optional: remind that surgical edits are available — "if any candidate is 90% there but has one detail to fix (typo / wrong color / artifact), use edit mode (Mode 3) to fix just that part and keep everything else."

---

When user invokes edit (Mode 3 — surgical region edit)

Inputs

• input_image: required. Path to the PNG you want to edit (typically from a previous Mode 2 run, e.g. candidates/2.png or slide-3.png).
• What to change (one of four ways — pick the most natural for the user):
  1. Natural-language region — region: "the headline at the top" / "the CTA button" / "the bottom-right corner". Agent uses vision to locate and generate a mask programmatically. Most natural UX.
  2. Normalized bbox — region_box: [x1, y1, x2, y2] in 0.0-1.0 coordinates (top-left origin). Agent generates a rectangular mask. Use when user gives precise coords or "the top 20%" type framing.
  3. User-supplied mask — mask: ./my-mask.png. Same dimensions as input_image, transparent (alpha=0) where to edit, opaque where to preserve. For users who painted in Photoshop / Preview / Figma.
  4. Global edit (no mask) — global_prompt: "make it black and white". No mask, prompt-only. ⚠️ Risk: gpt-image-2 may regenerate the whole image, drifting from the original. Only use for true global changes (color grade, time-of-day, weather). Warn user before proceeding.
• prompt: what should appear in the masked region (or the global change for global mode). Be specific — e.g. "change tagline to 'Stop fraud before it starts.' in the same font and weight" not "fix the text".
• output_path: optional. Default: alongside the input as <input-name>-edited-<timestamp>.png.

Procedure (do these in order)

Step 1 — Load and validate input_image.

• Confirm file exists, is a PNG, is gpt-image-2-readable.
• Read its dimensions (W × H) — needed for mask sizing.

Step 2 — Resolve the region into a mask PNG.

Region type	How to produce mask
Natural-language (region: "...")	Pass input_image through Codex's vision capability. Identify the pixel bounding box of the described element. Generate a same-dimension PNG: target region transparent (alpha=0, RGBA 0,0,0,0), rest opaque (alpha=255). Use Python+PIL via shell, e.g. python -c "from PIL import Image, ImageDraw; ...".
Normalized bbox (region_box: [x1,y1,x2,y2])	Multiply by W,H to get pixel rect. Generate mask PNG with that rect transparent, rest opaque.
User mask (mask: path)	Verify dimensions match input_image. If mismatch, resize or error with clear message.
Global (global_prompt)	No mask. Skip to Step 3.

Save the mask to a temp file (e.g. /tmp/30x-image-mask-<job-id>.png).

Step 3 — Upload input_image (and mask, if any) as files.

from openai import OpenAI
client = OpenAI()

def create_file(path):
    with open(path, "rb") as f:
        return client.files.create(file=f, purpose="vision").id

input_file_id = create_file(input_image)
mask_file_id = create_file(mask_path) if mask_path else None

Step 4 — Invoke image_generation tool with input_image_mask.

For region/bbox/mask edits (Steps 2.1, 2.2, 2.3):

response = client.responses.create(
    model="gpt-5.5",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": prompt_with_brand_context},
            {"type": "input_image", "file_id": input_file_id}
        ],
    }],
    tools=[{
        "type": "image_generation",
        "quality": "high",
        "input_image_mask": {"file_id": mask_file_id}
    }],
)

For global edits (Step 2.4 — no mask):

# Same call, but omit input_image_mask. Warn user about regeneration risk.

Prompt assembly — wrap the user's edit prompt with brand context to prevent off-brand drift in the edited region. Pull from the original manifest.json (or DESIGN.md if available):

Edit ONLY the masked region of this image. Preserve everything outside
the mask exactly.

EDIT INSTRUCTION:
{user's edit prompt}

BRAND CONTEXT (the edited region must remain on-brand):
- Palette: {colors.primary}, {colors.surface}, {colors.on-surface} — do not
  introduce new colors
- Typography: {typography.headline-display.fontFamily} weight {fontWeight}
- Anti-slop: same banned list as original generation (no AI yellow-tint, no
  pure black, no Inter font, etc.)

Do not regenerate the whole image. Do not alter pixels outside the mask.

Step 5 — Save and report.

• Save output PNG to output_path.
• Append to a Mode-3 manifest entry:

  {
    "edit_id": "ISO-timestamp",
    "input_image": "...",
    "input_image_hash": "sha256:...",
    "region_type": "natural-language" | "bbox" | "user-mask" | "global",
    "region_value": "the headline at the top",
    "mask_path": "/tmp/30x-image-mask-...png",
    "mask_hash": "sha256:...",
    "edit_prompt": "...",
    "output_path": "...",
    "created_at": "..."
  }
  

• Tell user: where the edited PNG is, what region was masked (transparency), and a side-by-side diff suggestion ("compare to the original at <input_path>").

Important limitations (from gpt-image-2 documented behavior)

1. Iterative-edit "stubbornness" — editing the same image more than 2-3 times in succession causes the model to stop making meaningful changes. Workaround: if a third edit doesn't take, regenerate the image fresh from Mode 2 with the desired change baked into the prompt.
2. Mask is guidance, not law — gpt-image-2 uses the mask as guidance but may not follow its exact shape with complete precision. Edges can bleed slightly into preserved areas. For pixel-perfect preservation needs, consider compositing in a separate image editor.
3. Self-correction hallucination — if the user asks to edit something that doesn't actually exist in the image (e.g. "remove the QR code" when there is no QR code), the model may hallucinate the missing element AND then "fix" it. Vision-validate the region exists before masking.
4. Global edits without mask drift — using global_prompt (no mask) risks the model regenerating the whole image. For true preservation, always provide a mask, even if the mask is the entire image except one tiny corner.

---

Quality bars (M0 acceptance)

A generated image is on-brand if:

1. Primary color from frontmatter is visibly dominant (CTA / accent)
2. Typography style matches ## 3. Typography Rules (e.g., Stripe = light weight 300, NOT bold)
3. No item from anti-slop banned list violated
4. Mood / density / variance match the taste: block

If hand-judging gives any "no" — iterate (re-pick axes / strengthen constraints / explicit anti-slop in prompt).

---

When you DON'T have enough

Refuse / clarify gracefully:

• DESIGN.md missing → 3-step fallback (try in order, tell the user which one you're taking):
  1. npx getdesign list — check if the brand is in the public awesome-design-md library (60+ brands: Stripe / Linear / Notion / Vercel / Apple / Tesla / Nike / Spotify / Starbucks / Apple / Coinbase / etc.). If yes →
  2. npx getdesign add <brand> — pulls a ready DESIGN.md to cwd in one command. Use it directly; optionally augment with a taste: block (5-7 numeric brand parameters) for axis biasing.
  3. Brand not in library → run init mode (M2) or hand-write a DESIGN.md using the 9-section format + frontmatter token block + taste: block (see examples/awesome-vendor/stripe/DESIGN.md as the canonical reference).
• Template name wrong → list 8 valid templates (incl. carousel)
• User brief doesn't match any template after honest attempt to classify → enter free-form fallback (NOT refuse). Tell user "no template matched, using free-form with brand DESIGN.md + anti-slop only" so they know determinism is reduced this run.
• Jobspec missing required fields (subject) → ask before invoking tool
• Brand ## 7 Don't is empty/weak → fall back to generic references/anti-slop-rules.md

---

Composition example — Stripe ad-creative

DESIGN.md:  examples/awesome-vendor/stripe/DESIGN.md
Template:   ad-creative
Jobspec:
  subject: "Q2 product launch — new fraud detection feature"
  copy:
    tagline: "Stop fraud before it starts."
    cta: "Try it free"
  size: 1024x1536
  quality: high
  n: 4

Axis picks (committed by 30x-image based on taste.variance=4, realism=7):
  Hero Composition:        Editorial Offset (variance=4 prefers low-mid)
  Subject Framing:         Medium environmental
  Lighting Mood:           Soft natural daylight (realism=7 sweet spot)
  Text-Image Integration:  Tagline overlaid bottom-left

→ image_generation tool invoked → 4 candidates saved
→ manifest.json records hash of DESIGN.md + axis picks + full prompt