Port #61/#62/#63: one-image icon prompt, honest seed provenance, size_class values

CHANGELOG.md

@@ -6,6 +6,8 @@ All notable changes to `github-showcase-skill` are recorded here. Versions follo
 
 ### Added
 
+- The pre-#61 override compatibility test now uses a minimal synthetic legacy art-direction fixture (`tests/fixtures/content/ART_DIRECTION.synthetic-legacy.md`, placeholder names and neutral colours, no production brand data) instead of a copy of the previous bundled template; the original stays in git history.
+- `content icon prompt` takes `--seed N` to request an image seed. The prompt states it only when asked, and the markdown provenance line `Requested: 1 image; seed: ...` records `N` or `not supported` (#63). An invalid or missing glyph `size_class` stays `needs-writer` and the result (`note`, `invalid`) lists the allowed values WIDE, TALL, SQUARE and DIAGONAL with a one-line meaning each; the values are listed in `SKILL.md`, `references/content.md` and `references/art-direction.md` (#62).
 - `content icon normalize` auto mode keys any uniform ground to transparent unless it is a dark night tile (luminance < 0.2 and not within dE 12 of the card colour), so a flat pale ground on a dark card no longer needs `--ground transparent`; `--ground keep|transparent` are unchanged. New `--ground-tolerance DE` (default 3.0) widens the corner match for slightly vignetted grounds (e.g. `--ground-tolerance 5`); above it `icon-ground` names the measured corner dE and the flag. A raised tolerance widens the keying threshold only above 3.0 and flattens a kept night tile so QA accepts it. Auto falls back to keying when a kept night tile would exceed the 300 KB budget; non-finite or negative `--ground-tolerance` is a usage error, and `--ground-tolerance 0` accepts identical corners as one ground (a positive tolerance keeps the strict boundary). The option A icon prompt (bundled and estate-format templates) states the exact flat `card_fill` ground with no vignette, texture, gradient, shadow or glow; the estate BACKGROUND heading now says one flat ground (not the avatar night tile), and the exact ground clause is now appended whenever a BACKGROUND replacement removed it (checked after all replacements). The soft 3 dE key alpha ramp applies only with a raised `--ground-tolerance`; the default transparent key is unchanged (original 0/255 step).
 - `content icon normalize` flattens a vignetted kept night tile with a feathered ramp (6 dE) instead of a hard threshold, and the transparent key uses a soft alpha ramp, so a glow around a solid glyph keeps its continuity with no hard outer ring; the glyph edge stays hard. `--ground-tolerance` is covered through the CLI (a raised value is applied; `nan` and negative values exit 2), and the estate-template numbered BACKGROUND paragraph is replaced by the flat-ground wording, including explicit colour or radial-gradient text.
 - `content icon check` and `content icon normalize` take `--ocr` (opt-in, off by default) to read the icon with `tesseract` on `PATH` for text: words of 2 or more alphanumerics warn (fail with `--strict`); without the tool the check is skipped with `needs-input:ocr-unavailable` and `no-text` stays a manual review, so the result and exit code do not change. An unreadable or undecodable PNG (bad structure, or valid structure with corrupt compressed data) fails the icon as a structured `png` check, so `content icon check` then prints a JSON result with a `logs` list and exits 1 (bad arguments still exit 2); `logs` names the unreadable image as `unreadable-image:<path>`, with and without `--ocr`; the command never ends in a traceback. `content icon normalize` handles an unreadable or undecodable `--in` candidate the same way (exit 1, no file written, with and without `--ocr`; `logs` names the `--in` source as `unreadable-image:<path>` plus `art-fail:icon-qa`); a missing `--in` file stays a usage error (exit 2).
@@ -15,6 +17,11 @@ All notable changes to `github-showcase-skill` are recorded here. Versions follo
 - `org labels ORG --repos-from-gh` plans labels across accessible repositories without the private estate registry, with paginated read-only GitHub capture, optional verified local checkouts, unchanged reference guards, and a documented org-default-forms-first workflow. Registry-backed plans still require the org registry row, and checkout repository names match GitHub case-insensitively, including resolved pending renames. Registry-free runs also isolate lazy brand lookups from estate decision files, and held reference rewrites retain their file/line guidance with an incomplete result. Workflow/labeler/release/Renovate references remain final skips rather than unresolved input requests. Missing Windows device-named checkouts fall back to captured metadata instead of aborting the org plan. Pending transfers check the repository's current owner's default issue forms and hold renames when that evidence is unavailable. Sparse or partially missing checkouts retain reference holds based on captured paths and the Git index, while unrelated omitted files remain allowed.
 - `references/art-direction.md` documents the Codex image-generation recipe for the icon pipeline (the `codex exec` command, reading the image path from the run output, and the retry and attempt limits). Image-folder and sandbox notes are labelled as observed runtime behaviour, not OpenAI-documented, and the exact returned path is the rule. Each distinct returned path is one candidate, and the attempt cap is per candidate slot (four slots, 3 empty attempts each); unreadable-only output counts as an empty attempt and ends in `art-fail` after 3. Documentation and static wording tests only; no behaviour change.
 
+### Changed
+
+- `content icon check` and `content icon normalize` measure an explicitly configured contrast floor (`--min-contrast` or the family key `icon_min_contrast`) on the most common actual ink colour, not the 16-level bucket midpoint, which falsely failed grey #707070 on #F8FAFC (really 4.73:1) and falsely passed #808080 on #032530 (really 4.06:1) at 4.5; the unconfigured default keeps the legacy midpoint measurement. `--ground-tolerance` must be a finite number from 0 to 12; NaN, a negative, 12.5 or 1000 is a usage error (exit 2) instead of keying the whole glyph away (`icon-empty`). The `references/art-direction.md` recipe selects the first readable path an invocation reports for its single slot, so a run that reports an unreadable sandbox copy and a readable `generated_images` file fills the slot; only a run with no readable path is an empty run (#61, ported from the epic review fixes; #64 privacy and retry limits unchanged).
+- `content icon prompt` now asks the image tool for ONE image (`Produce one image.`) instead of four candidates, writes the output path without the `-c{1..4}` suffix, and no longer asserts the family seed it used to infer; the provenance template line `Candidates: 4 or 8` became `Images requested`. The `references/art-direction.md` recipe and pipeline rule 7 now run the four-candidate selection round as four single-image invocations (then four more once), each slot with the existing per-slot cap of 3 attempts and the exact returned path; the #64 privacy, retrieval and retry semantics are unchanged. CLI help only documents flags: only a returned readable image path proves that an image was generated (#61, #63).
+
 ### Fixed
 
 - `readme --bootstrap --write` no longer regenerates a marked footer that holds authored content. When the edited-template upgrade is refused by the never-drop-a-line check and the marked footer carries a partner or foreign image, the command now exits with a check failure (`readme-shrink`) and leaves `README.md` unchanged instead of falling back to a header refresh that rewrote the footer; a plain old footer copy still takes the fallback. The same refusal now applies in every bootstrap state (pristine and unmarked as well as edited), checked before any write, so a pristine or unmarked template can no longer silently replace a partner or foreign footer image.

SKILL.md

@@ -140,8 +140,11 @@ The four command groups follow the same rules as the repository commands: read-o
 
 `content icon` defaults to the installed skill's `references/art-direction.md`,
 including a repository glyph template for option A and the illustration template
-for option B. Palette values come from `references/brand.yaml`; documented family
-seeds are used when available, otherwise the prompt uses the tool's default seed. Use
+for option B. Palette values come from `references/brand.yaml`. The prompt asks for
+one image and asserts no seed; pass `--seed N` to request one (recorded in the prompt and
+its provenance line, otherwise "not supported"). The glyph `size_class` is WIDE, TALL,
+SQUARE or DIAGONAL (case-insensitive); anything else stays `needs-writer` and the result
+lists the four values with their meanings. Use
 `--art-direction FILE` to select another file; relative paths use the current
 directory, and missing files report `needs-input:art-direction` with the selected path.
 Older custom configs without `icon_ink`/`icon_spark` keep normalization and checks
@@ -222,7 +225,7 @@ project readme --capture FILE --owner OWNER [--out FILE]
 project estate-plan [--copied FILE] [--user-id ID] [--source OWNER/N] [--jobs FILE]
 content social [--out PATH] [--title TEXT] [--icon PATH] [--job] [--allow-unmeasured] [--allow-hold]
 content icon prompt|normalize|check [--option A|B] [--glyph FILE] [--art-direction FILE] [--in PNG]
-    [--ground auto|transparent|keep] [--ground-tolerance DE] [--out PATH] [--preview PATH]
+    [--ground auto|transparent|keep] [--ground-tolerance DE (0 to 12)] [--seed N] [--out PATH] [--preview PATH]
     [--strict] [--min-contrast RATIO] [--ocr]
 content links [FILE...] [--readme-path PATH] [--base-ref REF] [--online] [--cache FILE] [--strict] [--diff]
 content linguist [--min-share 0.02] [--language NAME]