---
name: lucy-image-production
description: One-shot Lucy asset generation and deterministic export for Skill Heaven.
---

# Lucy Image Production

This is the Skill Heaven specialization of Gaia Image Production. It governs
every generated Lucy raster, background removal, upscale, crop, filter, and
WebP export in this repository.

## Authority

Read these before production, in this order:

1. `packages/site/src/assets/lucy/authority/lucy-character-sheet-master.png`
2. `docs/lucy/authority/LUCY_CANONICAL_CHARACTER_SHEET.md`
3. `docs/lucy/authority/lucy-canon.json`
4. `packages/site/src/assets/lucy/authority/lucy-original-reference.jpg`
5. The assigned job in `docs/lucy/production/ASSET_PRODUCTION_PLAN.md`

The final sheet and written canon win over every earlier iteration. Lucy is one
character. Her anatomy and outfit do not transform between states.

## Paid generation contract

- Use `gpt-image-2` only.
- Make exactly one generation call for each assigned `GEN-*` job.
- Do not request alternates, variations, or a second attempt.
- Include the authority images in the generation context.
- Preserve the first result even when it fails a gate; mark the job blocked.
- Self-review the result once. Continue only with deterministic local
  processing: crop, resize, alpha extraction, cleanup, compositing, inversion,
  color filtering, and WebP export.
- An owner-authorized candidate brief may define multiple named candidates.
  Treat each named candidate or bounded edit as its own one-call job. Never add
  replacements beyond the explicit candidate count, and never promote a
  candidate before the brief's human selection gate.

## Storage contract

- Raw/master/intermediate PNGs:
  `packages/site/assets/workbench/lucy/<job-id>/` (gitignored).
- As-is backup: run `scripts/assets/backup-lucy-pngs.sh` after any PNG lands.
- Production deliverables:
  `packages/site/src/assets/lucy/` as WebP.
- The only tracked production PNG is
  `authority/lucy-character-sheet-master.png`.
- Write a receipt to `docs/lucy/production/runs/<job-id>.md` with model,
  prompt path or full prompt, input authorities, raw path, outputs, dimensions,
  alpha result, self-review results, and any blocked item.

## Transparency and chroma fallback

When a brief says transparent, the final production WebP must contain real
alpha. No white, black, gray, or colored matte may remain in translucent edges.

1. Request a transparent background in generation.
2. Inspect the PNG alpha channel itself. A painted checkerboard is opaque art,
   not transparency, even when the RGB preview looks correct.
3. If the generator returns an opaque background, accept that one result and
   use deterministic removal. Prefer a flat `#00FF00` chroma field requested in
   the original brief; chroma green is deliberately distant from Lucy's cyan,
   blue, gold, red, silver, and skin palette.
4. Reject opaque white, gray, scene, simulated transparency, and baked-checker
   sources at the matte gate. Do not reconstruct a checker into speculative
   alpha. Never use purple or magenta as a Lucy chroma field.
5. Run `scripts/assets/lucy-matte-guard.py` for native-alpha validation or
   verified flat-green extraction. Supply a semantic-region JSON for character
   masters so face core, head, hair, torso, both arms/hands, both legs/feet,
   wings, and weapons must each pass alpha-density gates. The face-core region
   must have at least 70 percent of pixels at alpha 192 or higher and median
   nonzero alpha of at least 224. Head and hair must also meet the tool's
   median-alpha floors; nonzero ghost pixels do not count as completeness.
6. Inspect the generated white, black, mid-gray, light-checker, dark-checker,
   inverted-RGB checker, and raw-alpha audits for halos, holes, ghost pixels,
   missing pale features, and contaminated glass edges.
7. Require zero strong-green and zero strong-magenta pixels in the
   exterior-connected partial-alpha band. Do not infer completeness from RGB;
   the alpha silhouette is the authority.
8. Export a lossless-alpha WebP and re-open it to verify alpha survived.

Chroma is a workbench surface, never a brand color. Do not regenerate because
alpha removal is inconvenient.

Example fail-closed matte invocation:

```bash
python3 scripts/assets/lucy-matte-guard.py \
  --input packages/site/assets/workbench/lucy/JOB/raw.png \
  --output packages/site/assets/workbench/lucy/JOB/intermediate/alpha.png \
  --audit-dir packages/site/assets/workbench/lucy/JOB/audit \
  --report packages/site/assets/workbench/lucy/JOB/matte-report.json \
  --regions packages/site/assets/workbench/lucy/JOB/semantic-regions.json \
  --candidate JOB
```

## Deterministic processing

Use free local processing wherever possible. The preferred portable runtime is:

```bash
npx -y --package=tsx --package=sharp --package=@img/sharp-wasm32 tsx <script>
```

Keep reusable processing logic in `scripts/assets/`; do not hide the workflow
inside an untracked one-off command. Derivatives from the same generation—wide
composites, state cards, portraits, social crops, filtered plates, and mobile
crops—are not new image-generation jobs.

## State gates

- **Zero:** seated zen, closed eyes, normal gravity, one katana, no wings and
  absolutely no shards.
- **Heaven:** unique falling pose, both diamond eyes open, one katana, ordered
  saturated cyan-blue glass-shard wings.
- **Hell:** generate a complete Heaven-palette source with both eyes naturally
  closed and one continuous tear from the eyelid down the full face, then apply
  one exact full-foreground RGB inversion. The source tear must be the cyan
  complement that becomes the final vivid red tear. Use one katana and
  fragmented shards. Never patch eyelids or recolor the tear after inversion;
  all Hell-related derivatives descend from the untouched inverted master.
- **Ultra:** unique decisive falling pose, one gold diamond eye open, the other
  closed with a red tear, two matching katanas, gold shards, never inverted.

All states retain shoulder-length silver-white hair, dark sailor uniform,
prismatic ribbon, barefoot anatomy, real steel katana construction, and glass
shards with no feathers or membranes.

## One-pass self-review checklist

- [ ] Same canonical Lucy, proportions, uniform, hair length, ribbon, bare feet.
- [ ] Assigned pose, gravity, eye state, tear, weapon count, and shard language.
- [ ] No text, labels, signature, watermark, frame, or accidental UI.
- [ ] Full silhouette and required effects are not clipped.
- [ ] Transparent deliverables have real alpha and no matte/halo.
- [ ] Head, face, hair, torso, limbs, wings, and weapons have nonzero alpha in
      their declared semantic regions.
- [ ] White, black, gray, normal-checker, dark-checker, and inverted previews
      preserve hair, skin, glass, and steel edges.
- [ ] Exterior partial-alpha edges contain no strong green or magenta pixels.
- [ ] The two-pixel interior foreground boundary contains no strong green key
      spill. This includes opaque hair/glass edge pixels: exact Hell inversion
      would turn missed green spill into a magenta rim.
- [ ] For Hell, enforce that green-boundary rule on the pre-inversion source.
      The final exact-inverted Hell may use the guard's explicit
      `--exact-inverted-hell` mode only after the source report passes and the
      inversion report proves full-foreground RGB inversion plus byte-identical
      alpha. This avoids misclassifying legitimate green produced by inverting
      canonical source magenta.
- [ ] Hell inversion receipts must verify the source tear contains vivid cyan
      pixels in the declared face-core, the exact inversion contains the same
      number of vivid-red pixels, and the red pixels span at least 35 percent
      of the face-core height. Human composite review still decides eyelid
      contact and unbroken eyelid-to-jaw continuity.
- [ ] Output dimensions and file paths match the production plan.
- [ ] Production WebP re-opens successfully and stays within its target size.
- [ ] Raw PNG was backed up as-is.
- [ ] Receipt records pass/fail honestly; failed gates are not silently hidden.