# THIS YOU — Product Visual Lock & Hero Fidelity System

## Goal

Increase first-shot HERO image accuracy so that generated clothing matches the **exact selected real products**, not just their broad category, color or vibe.

Current HERO generation already receives:

- reader identity/reference photos;
- selected product names;
- colors;
- prices;
- product URLs;
- a generic product-fidelity instruction.

However, this is not enough to reliably preserve visible garment construction.

Observed failure examples:

- exact half-zip shirt becomes a button-front shirt;
- jacket pocket count / placement changes;
- utility jacket becomes a different cargo/parka construction;
- closure type, collar, length or silhouette are approximated too freely.

The fix is to add a structured **PRODUCT VISUAL LOCK** layer between product selection and HERO generation, then validate the generated HERO against that lock.

---

# Core principle

> Product names and URLs are not sufficient visual instructions.

For every selected product, THIS YOU must extract and store the visible construction that a human would use to recognize the product:

- closure;
- collar;
- pocket count;
- pocket placement;
- pocket type;
- silhouette;
- length;
- sleeve construction;
- color;
- hardware;
- distinctive panels/details;
- forbidden/invented details.

The HERO model should receive both:

1. **product reference images**, and
2. **structured visual specifications**.

---

# New workflow

Recommended production flow:

```text
1. Product discovery
2. Exact product-page verification
3. Exact regular/base price verification
4. Product reference-image collection
5. PRODUCT VISUAL LOCK extraction
6. Human product approval
7. HERO generation
8. PRODUCT FIDELITY CHECK
9. Optional automatic correction pass
10. Human HERO approval
```

Do not generate the final HERO before steps 4–6 are complete.

---

# 1. Product reference images

For each selected product, fetch one or more images from the **exact verified product page / exact selected variant**.

Preferred reference set:

```text
front
back
detail
on-model
```

Minimum:

```text
1 clear front image
```

Recommended:

```text
2–3 images when visible construction is not clear from one angle
```

Never use:

- another colorway if the exact colorway is available;
- another version of the product;
- visually similar substitutes;
- search-result thumbnails when the exact retailer page exposes usable images.

---

# 2. Store product visual references

Extend each `selected_products[]` item with:

```json
"visual_references": [
  {
    "type": "front",
    "source": "official_product_page",
    "url": "https://...",
    "local_or_cached_asset_id": "optional"
  },
  {
    "type": "detail",
    "source": "official_product_page",
    "url": "https://...",
    "local_or_cached_asset_id": "optional"
  }
]
```

If the product image is downloaded/cached internally, preserve the original retailer URL as provenance.

---

# 3. Add `visual_spec`

Each product should receive a machine-readable visual specification.

Example structure:

```json
"visual_spec": {
  "garment_type": "relaxed pop-over shirt",
  "primary_color": "dark green",
  "silhouette": "loose straight fit",
  "length": "hip length",

  "collar": {
    "type": "pointed shirt collar",
    "must_match": true
  },

  "front_closure": {
    "type": "half_zip",
    "hardware_color": "silver metal",
    "position": "center front",
    "length": "upper chest",
    "must_match": true
  },

  "buttons": {
    "visible_front_buttons": false,
    "must_match": true
  },

  "pockets": {
    "count": 1,
    "items": [
      {
        "placement": "left chest",
        "type": "square patch pocket"
      }
    ],
    "must_match": true
  },

  "sleeves": {
    "length": "long",
    "fit": "relaxed"
  },

  "distinctive_details": [
    "clean front",
    "silver half-zip",
    "single chest patch pocket"
  ],

  "do_not_invent": [
    "button placket",
    "extra chest pockets",
    "cargo pockets",
    "logos",
    "contrast stitching"
  ]
}
```

---

# 4. Example — shirt visual lock

For an ARKET-style dark-green relaxed pop-over with visible half-zip construction:

```json
{
  "slot_name": "shirt",
  "visual_spec": {
    "garment_type": "relaxed pop-over shirt",
    "primary_color": "dark green",
    "silhouette": "relaxed / loose",
    "length": "hip length",

    "collar": {
      "type": "pointed shirt collar",
      "must_match": true
    },

    "front_closure": {
      "type": "half_zip",
      "hardware_color": "silver",
      "position": "center front",
      "must_match": true
    },

    "buttons": {
      "visible_front_buttons": false,
      "must_match": true
    },

    "pockets": {
      "count": 1,
      "items": [
        {
          "placement": "left chest",
          "type": "square patch pocket"
        }
      ],
      "must_match": true
    },

    "do_not_invent": [
      "full button placket",
      "polo buttons",
      "second chest pocket",
      "large utility pockets"
    ]
  }
}
```

The HERO model must not interpret the word `shirt` as permission to invent a standard button-front shirt.

---

# 5. Example — jacket visual lock

Example structure for a washed-black relaxed jacket:

```json
{
  "slot_name": "outerwear",
  "visual_spec": {
    "garment_type": "relaxed washed utility jacket",
    "primary_color": "washed black",
    "silhouette": "relaxed boxy",
    "length": "hip length",

    "collar": {
      "type": "flat shirt-style collar",
      "must_match": true
    },

    "front_closure": {
      "type": "zip",
      "position": "center front",
      "must_match": true
    },

    "pockets": {
      "count": 2,
      "items": [
        {
          "placement": "use exact placement from product reference",
          "type": "use exact pocket construction from product reference"
        }
      ],
      "must_match": true
    },

    "do_not_invent": [
      "parka length",
      "hood",
      "extra chest flap pockets",
      "large cargo pockets",
      "four-pocket field-jacket layout"
    ]
  }
}
```

Important:

Pocket count and placement must be extracted from the actual product images.

Do not hardcode the example values globally.

---

# 6. Visual-spec extraction

The AI that creates `visual_spec` must analyze the official reference images.

It should not infer construction from the product title alone.

Recommended extraction prompt:

```text
Analyze the exact selected product reference images.

Describe only visible garment construction.

Extract:
- garment type;
- primary color;
- silhouette;
- overall length;
- collar type;
- front closure type;
- visible buttons;
- zipper type / position / hardware tone;
- pocket count;
- pocket placement;
- pocket type;
- sleeve length;
- cuffs;
- hem;
- distinctive visible panels/seams;
- visible logos/branding;
- details that must NOT be invented.

Do not guess hidden construction.
Do not infer details that are not visible.
If uncertain, mark the property as uncertain and require human review.
```

---

# 7. Confidence per extracted property

Recommended:

```json
"visual_spec_confidence": {
  "front_closure": 0.99,
  "collar": 0.98,
  "pockets": 0.92,
  "silhouette": 0.90,
  "fabric_texture": 0.65
}
```

If a critical field has low confidence, flag it for human verification.

Suggested rule:

```text
critical visual property confidence < 0.80
=> human visual-spec review required before HERO
```

---

# 8. Fidelity priorities

Not all product details are equally important.

Add:

```json
"fidelity_priority": {
  "must_match": [
    "front_closure",
    "collar",
    "pocket_configuration",
    "overall_length",
    "silhouette",
    "primary_color"
  ],

  "should_match": [
    "fabric_texture",
    "hardware_tone",
    "major_seam_placement",
    "hem_shape"
  ],

  "may_approximate": [
    "minor stitching",
    "hidden construction",
    "small interior details"
  ]
}
```

---

# 9. HERO prompt priority

Update `creative_rules.product_fidelity`.

Current generic logic such as:

```text
Preserve visible garment construction as closely as possible.
```

is too weak.

Replace/extend with:

```text
PRODUCT VISUAL LOCK:

Each selected product includes official product-image references and a structured visual_spec.

Treat all `fidelity_priority.must_match` properties as hard visual constraints.

MUST_MATCH details have higher priority than general styling aesthetics.

Never:
- replace a zipper with buttons;
- replace buttons with a zipper;
- change collar type;
- change pocket count;
- change pocket placement;
- invent additional visible pockets;
- change garment length category;
- change the core silhouette;
- change the primary color;
- invent visible logos or branding;
- introduce any feature listed under `do_not_invent`.

Use the official product reference images as the primary visual source for garment construction.

Use the text visual_spec to disambiguate details that may be missed in generation.
```

---

# 10. Image-reference priority

The HERO generator receives two different types of images:

## Reader references

Purpose:

```text
identity
face
hair
body proportions
height impression
```

## Product references

Purpose:

```text
clothing construction
silhouette
closure
pockets
color
shape
```

The generation prompt should explicitly distinguish them.

Example:

```text
REFERENCE PRIORITY:

Reader images define WHO the person is.

Product images define WHAT the garments look like.

Do not copy garments from the reader's original photos.

Do not use the selected-product images to alter the reader's identity.
```

---

# 11. `personalization_input.v2` extension

Recommended selected product structure:

```json
{
  "id": 200,
  "slot_name": "shirt",
  "brand": "ARKET",
  "product_name": "Relaxed Pop-Over Shirt",
  "color_name": "Dark Green",
  "price": 99,
  "price_basis": "regular_base_non_discounted",
  "currency": "EUR",
  "product_url": "https://...",

  "visual_references": [
    {
      "type": "front",
      "url": "https://..."
    }
  ],

  "visual_spec": {
    "garment_type": "relaxed pop-over shirt",
    "primary_color": "dark green",
    "collar": {
      "type": "pointed shirt collar",
      "must_match": true
    },
    "front_closure": {
      "type": "half_zip",
      "hardware_color": "silver",
      "must_match": true
    },
    "buttons": {
      "visible_front_buttons": false,
      "must_match": true
    },
    "pockets": {
      "count": 1,
      "must_match": true
    },
    "do_not_invent": [
      "button placket",
      "extra pockets"
    ]
  },

  "fidelity_priority": {
    "must_match": [
      "front_closure",
      "collar",
      "pocket_configuration",
      "silhouette",
      "primary_color"
    ]
  }
}
```

---

# 12. Do not rely on prose only

Avoid generating one large paragraph such as:

```text
Dark green relaxed pop-over shirt with zip and pocket...
```

as the only construction description.

Structured fields are better because they:

- reduce ambiguity;
- can be validated;
- can be compared after generation;
- can trigger regeneration;
- make admin review easier;
- allow product-specific constraints.

Prose may still be generated as a secondary human-readable summary.

---

# 13. HERO generation result

The HERO generator should not be trusted to self-report fidelity without verification.

The existing:

```json
"product_fidelity_notes": []
```

may remain, but it is informational only.

A separate validator must evaluate the final image.

---

# 14. Add PRODUCT FIDELITY CHECK

After HERO generation, run an independent vision comparison.

Inputs:

```text
generated HERO
+
product visual references
+
visual_spec
```

Output example:

```json
{
  "schema": "this_you.product_fidelity_check.v1",
  "chapter_number": 1,

  "products": [
    {
      "slot_name": "shirt",
      "checks": {
        "primary_color": "pass",
        "silhouette": "pass",
        "collar": "pass",
        "front_closure": "fail",
        "pocket_configuration": "pass"
      },
      "critical_failures": [
        "front_closure"
      ],
      "score": 0.82
    }
  ],

  "overall_score": 0.86,
  "regenerate_required": true
}
```

---

# 15. Fidelity-check rules

Recommended:

```text
Any MUST_MATCH failure
=> regenerate_required = true
```

Optional additional rule:

```text
overall_score < 0.85
=> regenerate_required = true
```

A `should_match` mismatch alone does not necessarily require regeneration.

---

# 16. Correction pass

Do not regenerate from scratch immediately.

First perform one targeted correction pass.

The correction prompt should contain only the failed details.

Example:

```text
Keep the current person, face, pose, body proportions, scene, trousers and shoes unchanged.

Correct only:

SHIRT:
- front closure must be a silver half-zip;
- remove all visible buttons;
- preserve the pointed collar;
- preserve one left-chest patch pocket.

JACKET:
- remove invented cargo pockets;
- restore exact pocket configuration from reference;
- preserve hip-length washed-black boxy silhouette.
```

This should reduce drift in already-correct parts of the image.

---

# 17. Maximum automatic correction attempts

Recommended:

```text
initial HERO
+
maximum 1 automatic correction pass
```

If MUST_MATCH failures remain after the correction pass:

```text
status = needs_human_review
```

Do not create endless image-generation loops.

---

# 18. Admin UI — PRODUCT VISUAL LOCK

For each approved product, show:

```text
PRODUCT
ARKET Relaxed Pop-Over Shirt

COLOR
Dark Green

VISUAL LOCK

Closure:
Half zip — MUST MATCH

Buttons:
None visible — MUST MATCH

Collar:
Pointed collar — MUST MATCH

Pockets:
1 × left chest patch pocket — MUST MATCH

Silhouette:
Relaxed

Do not invent:
Button placket
Extra pockets
```

Show the reference image beside the structured data.

Human reviewer should be able to edit incorrect extracted properties before HERO generation.

---

# 19. Admin UI — HERO FIDELITY

After generation show:

```text
SHIRT
Color                 PASS
Silhouette            PASS
Collar                 PASS
Closure                FAIL
Pocket configuration   PASS

JACKET
Color                  PASS
Length                 PASS
Closure                PASS
Pocket configuration   FAIL
```

Buttons:

```text
CORRECT FAILED DETAILS
APPROVE ANYWAY
REGENERATE HERO
```

---

# 20. Human review

Human review remains mandatory.

Automation is intended to:

```text
catch obvious product-construction drift before the human sees it
```

not to remove human approval.

---

# 21. Product-image provenance

Store enough metadata to know which exact image was used.

Example:

```json
{
  "source": "official_product_page",
  "product_url": "https://...",
  "image_url": "https://...",
  "captured_at": "2026-08-16T..."
}
```

This helps debugging if the retailer later changes images.

---

# 22. Cache policy for product images

Product references may be cached internally after verification so HERO generation is stable.

Important distinction:

```text
PRICE verification:
must use fresh/revalidated product-page data.

VISUAL reference used for an already-approved product:
may use the exact cached approved image asset.
```

Reason:

The approved visual reference should not unexpectedly change between product approval and HERO generation.

Store its retailer provenance and timestamp.

---

# 23. Product unavailable after approval

Do not silently replace the garment during HERO generation.

If a selected product becomes unavailable after approval:

```text
HERO still uses the approved product visual lock.
```

Replacement product discovery is a separate product-selection action requiring human review.

The HERO generator must never search for or invent a replacement.

---

# 24. Visual lock creation timing

Create the visual lock immediately after exact product selection / verification.

Recommended state flow:

```text
candidate
↓
product_verified
↓
visual_lock_generated
↓
visual_lock_reviewed
↓
product_approved
↓
hero_ready
```

---

# 25. Error handling

If exact product images cannot be obtained:

```text
visual_lock_status = insufficient_reference
```

Do not pretend high fidelity is possible.

Options:

```text
1. human uploads/selects reference image;
2. choose another product with usable references;
3. allow generation with explicit low-confidence warning.
```

Recommended default:

```text
do not proceed to final HERO without at least one usable official visual reference for every clearly visible product.
```

---

# 26. Suggested schemas

## Product visual lock

```json
{
  "schema": "this_you.product_visual_lock.v1",
  "product_id": 200,
  "slot_name": "shirt",
  "visual_references": [],
  "visual_spec": {},
  "fidelity_priority": {},
  "human_review_required": true
}
```

## Fidelity check

```json
{
  "schema": "this_you.product_fidelity_check.v1",
  "issue_slug": "new-york-autumn-2026",
  "reader_id": 4,
  "chapter_number": 1,
  "products": [],
  "overall_score": 0,
  "regenerate_required": false,
  "human_review_required": true
}
```

---

# 27. Acceptance criteria

## Before HERO

- [ ] Every visible selected product has at least one exact official visual reference.
- [ ] References belong to the exact selected product/variant.
- [ ] A structured `visual_spec` exists for every visible garment.
- [ ] Closure type is explicitly described.
- [ ] Collar type is explicitly described.
- [ ] Pocket count is explicitly described where visible.
- [ ] Pocket placement/type is explicitly described where visible.
- [ ] Silhouette is explicitly described.
- [ ] Length is explicitly described.
- [ ] Primary color is explicitly described.
- [ ] `do_not_invent` exists for critical likely failure modes.
- [ ] `fidelity_priority.must_match` exists.
- [ ] Human product/visual-lock approval is complete.

## HERO prompt

- [ ] Reader references are identified as identity references.
- [ ] Product references are identified as garment-construction references.
- [ ] MUST_MATCH properties override general styling freedom.
- [ ] Generator is explicitly forbidden from changing closure type.
- [ ] Generator is explicitly forbidden from changing pocket configuration.
- [ ] Generator is explicitly forbidden from inventing visible construction.
- [ ] Generator does not search for replacement products.

## After HERO

- [ ] Generated image is compared against each product's visual lock.
- [ ] Every MUST_MATCH field receives pass/fail.
- [ ] Any MUST_MATCH failure triggers correction.
- [ ] Maximum one automatic targeted correction pass is allowed.
- [ ] Remaining critical mismatches are surfaced to human review.
- [ ] Final HERO cannot be marked fully approved without human review.

---

# 28. Expected effect

This system will not guarantee pixel-identical reproduction of commercial product photography.

The realistic target is:

```text
recognizably the same garment construction
```

instead of:

```text
a generic garment inspired by the product category
```

It should materially reduce failures such as:

```text
half-zip → buttons
1 pocket → 4 cargo pockets
short jacket → parka
pointed collar → polo collar
wide tailored trouser → generic straight trouser
silver low-profile sneaker → unrelated chunky sneaker
```

---

# Final architecture

```text
REAL PRODUCT
    ↓
EXACT PRODUCT PAGE
    ↓
OFFICIAL PRODUCT IMAGES
    ↓
PRODUCT VISUAL LOCK
    ↓
HUMAN VERIFY
    ↓
HERO GENERATION
    ↓
PRODUCT FIDELITY CHECK
    ↓
TARGETED CORRECTION (if required)
    ↓
HUMAN HERO APPROVAL
```

The key architectural change is:

> **The selected product is no longer represented only by its name and URL. It becomes a verified visual specification that the HERO generator is explicitly required to reproduce.**