---
reliability: 4.3 # anchor cleanup edit −0.2, place_subject batch −0.3, detail-shot edit −0.2; ≤5 stages, all finishing deterministic, no E2E showcase
---

# E-commerce product — agent playbook

> Paste this whole file (with the BRIEF filled in) into Claude cowork, chat, or Code. The agent walks through it with you and stops for your approval at every step that matters.

## How the agent should run this (interaction contract)

1. **CONFIRM** — one line: SKU + lifestyle_setting + variant_count + "~$0.90–$2.10, ~18 min". If `product_photo_url` is missing or clearly not a clean white-bg shot, that's the ONE question; otherwise state assumptions and start.
2. **PREVIEW CHECKPOINT** — the **cleaned anchor + ONE test placement scene** (~$0.15) before the full `place_subject` fanout. If the test scene drifts the product (shade, logo, shape), fix the anchor first — every later scene inherits it.
3. **NARRATE** — one line per stage with job_id + ETA ("placing scene 3/5, ~30s each"); poll `get_create_media` every 10–15s; report per-scene fidelity flags from the `critique` field as they arrive.
4. **FAIL GRACEFULLY** — drifted scene → re-run ONLY that scene via `create_media action:"restyle"` with the anchor URL (never fresh text-to-image); `flux-erase` cleanup fail → fall through to the `kontext-edit` colour pass alone; ≤2 retries per scene, then deliver N−1 good scenes over nothing. One line each: what failed / why / fallback used.
5. **DELIVER** — 8 image URLs + the 2 HTML paths + one honest note ("logo fidelity is strong on flat surfaces — eyeball curved-surface reflections before upload") + ONE next step: upload in the listed image order.

## What you'll get

A complete product-page photography package for one SKU, built from a single existing white-background shot. No reshoots, no studio rental, no stylist — the same product in 5 different real-world environments:

- **1 clean white-bg hero** — your existing shot, cleaned up (dust, scuffs, color-balance fixes).
- **5 lifestyle scenes** — the SAME product placed in 5 different environments. Same shape, same color, same materials, same logo.
- **1 scale-reference shot** — the product in a hand or next to a known object so shoppers grasp the size.
- **1 detail / texture close-up** — the macro shot that converts hesitant buyers.
- **3 IG carousel posts** — your 3 strongest scenes with shop-ready captions.
- **Listing-page short copy** — 90-word product description + 5 bullet features.

**Time**: ~18 minutes wall clock. **Your attention**: about 5 minutes across 5 quick approvals. **Cost**: $0.90 – $2.10 end to end.

## Tell the agent about the product

```yaml
product_name:         # e.g. Field Mug
product_category:     # apparel / homewares / accessories / electronics / beauty / outdoor / etc.
product_photo_url:    # the existing white-bg shot — URL to your current listing image
brand_palette:        # 4 hex colors, e.g. #2D3D2F #D4A574 #F2EEE5 #1A1A1A
lifestyle_setting:    # e.g. cozy apartment morning / outdoor adventure / minimal studio / sun-drenched kitchen
variant_count:        # 1-5 — how many lifestyle scenes you want (default 5)
```

## Quality controls (new — auto-applied)

This playbook leverages the closed quality loop. The agent applies these by default; you don't have to ask:

- **Cost upfront.** Before any multi-step batch fires, the agent calls `submit_plan` with `confirm:false` and shows you the proposed steps + total cost. Nothing runs until you approve.
- **Auto-retry on weak shots.** The server default is `quality_threshold: 0.7`. For the white-bg hero and the lifestyle scenes the playbook step tells the agent to pass `quality_threshold: 0.85` so a low-confidence first try gets one auto-retry before you see it. Product identity is non-negotiable.
- **Critic verdict on the result.** When the 5-scene lifestyle batch finishes, the agent reads the `critique` field on the response (verdict: ship / iterate, plus per-scene product-fidelity flags) and surfaces it for your review.
- **One-click recovery.** If a step fails, `get_plan` returns a `recovery` hint pointing at `replan({plan_id})` — the agent classifies the failure and proposes a recovery plan you can approve.
- **End-of-project scorecard.** The final wrap-up calls `get_scorecard({project_id})` with succeeded count, mean quality score, critic verdict, total cost, and wall time.

You can override any of these per step.

## How this works

Five gates. The killer move is `place_subject` — the agent takes your existing white-bg product photo as the anchor and places the SAME product (same shape, same color, same logo) in 5 different environments. You don't reshoot. You don't ship anything to a stylist. The product stays itself.

## The steps

### Step 0 — Confirm the brief

The agent reads back the BRIEF — product name, category, palette, lifestyle setting, variant count — so you catch typos before any image renders.

**STOP**: "Brief looks right? (approve / edit [field] [new value])"

### Step 1 — Lock the product anchor (~30s, ~$0.05)

The agent fetches your `product_photo_url`, cleans it up with `create_media({ action: "restyle", source_url: product_photo_url, model_override: "flux-erase" })` for any dust/scuff/watermark removal then a `kontext-edit` color-balance pass, and sets the result as the **product anchor** — the canonical reference every lifestyle scene will be locked to.

It also calls `brand_kit_create({ palette: brand_palette, ... })` so the lifestyle scenes share a color story with your existing brand.

> **For the agent**: this is the identity gate. Lock the product anchor here. The `place_subject` call in step 3 passes this exact URL as its subject.

> **For the agent**: pass `quality_threshold: 0.85` on the cleanup — if the cleaned image drifts at all from the original, auto-retry.

**STOP**: "Approve the cleaned product anchor? (approve / refine [direction])"

### Step 2 — Clean white-bg hero (no extra cost, already done in step 1)

The cleaned anchor IS the white-bg hero. The agent just exports it at listing-page resolution (typically 2000×2000 for Shopify, 1600×1600 for Etsy). Goes up as the first listing image.

This step is just an export — no separate STOP gate.

### Step 3 — Place the product in 5 lifestyle scenes (~5 min, ~$0.60)

The agent makes ONE `place_subject({ subject_url: <product anchor>, scenes: [...N environment prompts...] })` call — it fans out to N nano-banana renders with the subject-preservation preamble auto-applied, so the SAME product appears in N different environments. Same shape, same color, same materials, same logo, in N different contexts. (One call, not N — `place_subject` is the killer move here.)

Examples by lifestyle_setting:
- **cozy apartment** → on a wood coffee table next to a book, on a kitchen counter with morning light, in a hand by a window seat, on a desk next to a laptop, on a side table with a candle
- **outdoor adventure** → on a flat rock by a river, in a hand at a campsite, on a picnic blanket, on a fence post, packed into a backpack
- **minimal studio** → on a marble surface, on a linen drape, on a concrete floor, in a hand against a neutral wall, on a wooden block

> **For the agent**: `place_subject` routes to nano-banana for identity preservation — that's correct, don't override the model. Pass `quality_threshold: 0.85` on the batch — the product MUST look like the same product across all N scenes. Auto-retry fires once on any scene where the critic grades product fidelity below 0.85. For a re-render of one drifted scene, use `create_media action:"restyle"` with the anchor URL (not a fresh text-to-image).

> **Critic verdict** — the 5-scene batch returns a `critique` field with per-scene product-fidelity flags. If verdict=iterate, the critic flags the specific scene where the product drifted (wrong shade of blue, missing logo, different shape). Surface that here so the user can target a re-render at exactly that scene.

**STOP**: "Which scenes to keep? (keep all / redo [scene #] [direction])"

### Step 4 — Scale-reference + detail close-up (~2 min, ~$0.20)

> **De-engineered:** fold the scale-reference into the Step 3 `place_subject` call as scene N+1 ("held in a hand…") — one fanout, not two. Only the detail close-up needs its own `kontext-edit` pass.

Two more shots, both anchored so the product stays the product:

- **Scale-reference** — the product held in a hand, OR placed next to a known object (a coffee cup, a smartphone). This is the shot that answers "how big is it?" — the #1 question shoppers ask.
- **Detail / texture close-up** — the macro shot via `kontext-edit` on the anchor (push in on stitching, wood grain, weave, metal finish). This is the shot that converts the hesitant buyer.

**STOP**: "Approve the scale + detail shots? (approve / refine [which one] [direction])"

### Step 5 — IG carousel + listing copy (~2 min, ~$0.10)

The agent assembles:

- **3 IG carousel posts** — your 3 strongest lifestyle scenes with shop-ready captions. Captions are short (under 60 chars), benefit-led, hashtag pack at the end.
- **Listing-page copy** — 90-word product description + 5 bullet features. Reads like a confident product spec, not a sales pitch. Mentions material, dimensions (from scale ref), care, and one emotional benefit.

Saved to `public/launches/{product-slug}-social.html` and `public/launches/{product-slug}-listing.html`.

**STOP**: "Approve the carousel + copy? (approve / refine [which one] [direction])"

### Final step — scorecard wrap-up

After all deliverables ship, call:

```
get_scorecard({ project_id: "{the project id from earlier steps}" })
```

The response is a one-page report card:

```
Scorecard for cjob_xxx
{N}/{N} scenes shipped — critic: SHIP (or ITERATE)
Title: <product_name>
Steps: N/N succeeded (100%)
Quality: mean X.XX · M/N passed · K retries
Critic: SHIP/ITERATE
Cost: $X.XX actual (est $Y.YY) · Ts wall time
Viewer: <project URL>
```

Paste the scorecard into your seller channel so the person doing the upload sees the quality numbers before pushing live.

## When you're done

The agent prints:

```
✅ White-bg hero: <URL>
✅ Lifestyle scenes (5): <viewer URL>
✅ Scale reference: <URL>
✅ Detail close-up: <URL>
✅ IG carousel: public/launches/{product-slug}-social.html
✅ Listing copy page: public/launches/{product-slug}-listing.html

Total spent: $X.XX
Total wall-clock: MM:SS
```

## What can disappoint (cap ceilings)

`place_subject` holds shape, colour, and materials well, but **fine logo text and curved-surface reflections drift** — inspect them per scene before upload. The macro "detail" shot is plausible texture in your product's style, not a photograph of your actual stitching; don't use it where buyers will compare thread-for-thread.

## What to do next

1. **Upload the 8 images to your listing** — Shopify / Etsy / Amazon. Order: white-bg hero → 3 lifestyle scenes → scale-ref → 2 more lifestyle scenes → detail close-up. Listings with 7+ images convert 30% better.
2. **Paste the listing copy** into the product description field. Bullet features go in the bullet-points field on Amazon, or the "Highlights" field on Shopify.
3. **Schedule the IG carousel** with `publora_publish_post` (check `publora_list_platforms` first), or through your normal scheduler.
4. **Save the brief + product anchor** — when you do a seasonal variant ("Winter Field Mug"), re-use the same product anchor and just change the lifestyle_setting. The product stays the product.