Epic: Make the repo-icon pipeline reliable and honest #51

Goal

Of the icons generated during the rollout, many first attempts failed QA for avoidable reasons (budget, ground noise, dim ink), and weak icons could pass with only a warning. Align the prompt, the ground detection and the QA, and document the image-generation workflow.

Exit criteria

• A flat-ground icon passes normalize without manual flags. (content icon normalize --ground auto keeps pale grounds opaque on dark-card families and blows the 300 KB budget #52, PR Make the repo-icon ground handling reliable: key flat pale grounds in auto mode, add --ground-tolerance #126: --ground auto keys flat pale grounds with a tolerance; verified at main 04fbc0a)
• QA fails (not warns) on off-brand ink. (Icon QA lets weak or off-brand icons pass #57, PR content icon: --strict, --min-contrast and optional --ocr checks (#57) #127: --strict or the family key icon_strict_family_ink makes the family-ink check FAIL; by default it stays a warning, because behaviour-changing defaults are off. Default QA does not hard-fail.)
• The Codex workflow is documented. (Document the Codex image-generation workflow and its pitfalls #64, PR Document the Codex image-generation workflow and its pitfalls (#64) #128 and content icon prompt UX: invalid size_class is not explained, and the prompt asks for things generators cannot do #61, PR Port #61/#62/#63: one-image icon prompt, honest seed provenance, size_class values #129: the recipe in references/art-direction.md, one-image prompt and honest provenance)

Scope

• E3.1: content icon normalize --ground auto keeps pale grounds opaque on dark-card families and blows the 300 KB budget
• E3.2: Icon QA lets weak or off-brand icons pass
• E3.3: content icon prompt UX: invalid size_class is not explained, and the prompt asks for things generators cannot do
• E3.4: Document the Codex image-generation workflow and its pitfalls

Progress is tracked through this issue's sub-issues.

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.