Document the Codex image-generation workflow and its pitfalls #64

Status: Verified during the Pick Your AI rollout (reproduced, or read directly in the code).

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

Summary

Using Codex to draw icons worked, but several non-obvious problems cost time on every run.

Evidence

• Images are saved under the user's Codex generated-images folder; copies written inside Codex's own sandbox are locked against the user (access denied).
• Taking the "newest" image is wrong when sessions run in parallel.
• Parallel runs sometimes produced no image path (retry succeeded).

Impact

Agents lose attempts and sometimes normalize the wrong image.

Proposed fix

Add a documented, tested recipe (command, where to read the image, retry policy, privacy rule).

Acceptance criteria

• references/art-direction.md has the recipe.
• The recipe says only public facts go into prompts.

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.