content icon normalize --ground auto keeps pale grounds opaque on dark-card families and blows the 300 KB budget #52

Status: Reported by agent sessions during the rollout. The mechanism was checked by reading the code; the failure was not re-run on current main.

Part of epic: Epic: Make the repo-icon pipeline reliable and honest.

Summary

auto compares the generated ground to the family card_fill. When they differ it keeps an opaque tile, so a flat pale background becomes a 500 to 620 KB file and fails icon-budget. The prompt only says "keep the background empty", so generators add vignettes that also fail icon-ground (corner ΔE 3.1 to 3.4 against 3.0).

Evidence

• Mechanism read in normalize_icon (near_card decides keep vs transparent).
• Reported by at least six sessions: sizes 467 to 624 KB; ground failures at ΔE 3.11, 3.29, 3.44; every case succeeded with --ground transparent.
• Not re-run on current code: PR Add opt-in T3 showcase support and Pick Your AI identity #20 switches the Pick Your AI card to light, which hides it for that family. Other dark-card families (for example LibreEvolve) are exposed.

Impact

Wasted generation attempts and manual flags on every dark-card family.

Proposed fix

State the exact flat ground colour in the prompt, key out any near-uniform ground regardless of the card colour, and expose a tolerance.

Acceptance criteria

• Flat-ground fixtures on pale and dark grounds normalize without --ground.
• Vignetted grounds up to a documented tolerance still pass.

Tasks

Each task below is a sub-issue.

Prior work

Prior work: open PR #20 (opt-in --allow-t3 and the Pick Your AI family), open #7 and PR #13 (variant J badges), merged PRs #14 to #19 (icon art-direction path, UTF-8 output, registry-free org health and label planning, Windows test portability, footer URL repair) and closed issues #8 to #12. Nothing here duplicates those; where an item is already handled it is linked, not refiled.

Fresh VM verification: not run. Findings were verified on a Windows host; hosted CI is separate evidence.