deanwhitex/aiw2.0stack/nano-banana

Nano Banana Hero Image Skill (Stage 9)

How this skill is customised

The factory ships niche-agnostic. The composition rules that make a hero image unmistakably "this niche" (a contractor's branded vehicle + region-correct home; a boutique hotel's golden-hour exterior with hosted dinner foreground; an e-commerce brand's product still-life with brand colour backdrop) are not in this file. They live in the niche playbook:

templates/{active-niche-slug}/niche-playbook/hero-composition.md
templates/{active-niche-slug}/niche-playbook/hero-mood-mapping.json

hero-composition.md is a prompt fragment that Module 2D writes from the top-of-niche analysis it did in Stage 2D. hero-mood-mapping.json maps brand-dna.hero.mood values to specific lighting briefs.

If either file is missing, the agent halts and points the student at Module 2D.

Architecture

Inputs

Required:

• clients/[Client Name]/Pipeline Data/brand/brand-dna.json (palette, region, hero.mood)
• clients/[Client Name]/[Client Name] Assets/logo/logo.{png,svg,jpg} (HALT if missing)
• templates/{active-niche}/niche-playbook/hero-composition.md
• templates/{active-niche}/niche-playbook/hero-mood-mapping.json

Optional (used when present, requirement varies per niche):

• clients/[Client Name]/Pipeline Data/research/research.json
• clients/[Client Name]/Pipeline Data/intake/intake.json
• People / subject reference photos at the path the niche playbook prescribes (e.g.

founder-photos/owner.{jpg,png} for contractor; host-photos/host.{jpg,png} for hospitality)

Universal composition rules

These apply regardless of niche. The niche playbook may add but never override.

• Target size: 1500×700 (Gemini variance allowed: ≥ 1000×500)
• Non-zero bytes, not solid colour, validates on output
• LEFT 40% of frame stays relatively unobstructed (reserved for text overlay zone)
• Logo as multimodal reference is non-negotiable (logo must be used, never re-coloured or

re-styled in the output)

• No watermarks, no overlaid text not part of the source photography
• Photorealistic (no illustration, no painterly filter)

Niche composition rules

Loaded from niche-playbook/hero-composition.md. The niche playbook defines:

• Subject placement and scale
• Foreground/midground/background composition
• Whether people are in the frame and where
• Whether a vehicle, product, room, or scenic element is in the frame
• Mood lighting baseline for the niche

Hero mood mapping

brand-dna.hero.mood selects from the niche's mood map at niche-playbook/hero-mood-mapping.json. Every niche playbook ships at minimum these moods (values mapped to lighting briefs the prompt fragment inherits):

• golden_hour_warm
• overcast_calm
• dramatic_dusk
• bright_midday_clean
• dawn_soft_optimistic

A niche may add niche-specific moods (e.g. candlelit_intimate for hospitality; storm_dramatic for storm-restoration contractors).

If brand-dna.hero.mood is not set, default to the niche playbook's default_mood field.

Region defaults

The niche playbook may define region-specific defaults at niche-playbook/hero-regions.json (house style for contractor regions, climate descriptors for hospitality regions, etc.). The agent passes brand-dna.region to look up the row; research.json overrides per field.

Process (what the agent does)

1. Asset gate. Confirm logo exists. If missing, write MANUAL-DROP-NEEDED.md and halt

the pipeline.

1. Niche playbook gate. Confirm niche-playbook/hero-composition.md and

hero-mood-mapping.json exist. Halt with a Module-2D pointer if missing.

1. Subject gate (soft). Detect people/subject reference photos per the niche

playbook's spec. If required by the playbook and missing, soft-halt (write SUBJECT-PHOTO-NEEDED.md; pipeline may continue with a subject-less composition).

1. Prompt assembly. Substitute per-client tokens into the niche's complete prompt

template at templates/{active-niche}/niche-playbook/hero-composition.md: company name, city/state, region defaults, brand-dna.palette, services, mood lighting brief (looked up from niche mood map), and any reference-photo blocks. The template is a complete scaffold Module 2D wrote per-niche; there is no separate universal scaffold to layer on top.

1. API call. Run python3 tools/generate-hero.py --client "[Client Name]". The script

handles multimodal upload, retries x3 with exponential backoff on API errors, validates output dimensions and sanity (not solid colour, non-zero bytes).

1. Output. Save image to hero-final.png, prompt to hero-prompt.md, metadata to

hero-metadata.json.

1. Pipeline state. Update pipeline-state.json with stage_9: complete.

Failure handling

What this skill never does

• Generates without the client logo as a multimodal reference (logo is non-negotiable)
• Uses generic stock-photo aesthetics
• Places subjects or branded objects in the LEFT 40% of frame (text overlay zone)
• Generates multiple candidates (one image, retry on failure)
• Modifies the logo (no recolouring, no simplification)

CLI usage (manual runs / debugging)

python3 tools/generate-hero.py --client "[Client Name]"
python3 tools/generate-hero.py --client "[Client Name]" --no-owner

Pass gate

• hero-final.png exists, dimensions ≥ 1000×500, non-zero bytes, not solid colour
• hero-prompt.md saved for audit
• hero-metadata.json records: logo used, subject used (or null), mood, region, model, byte size
• OR REGENERATION-NEEDED.md written and noted in pipeline-state