hanoman 0.9.38 → 0.9.39

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.9.38",
-  "sha": "fb8cc7c9",
-  "builtAt": "2026-10-31T04:05:47.472Z"
+  "version": "0.9.39",
+  "sha": "4c0f4d39",
+  "builtAt": "2026-10-31T04:13:34.564Z"
 }

package/dist/cli.js

@@ -38743,7 +38743,9 @@ function packageJsonFor(version2, deps) {
       prepublishOnly: "node dist/cli.js __verify"
     },
     engines: { node: ">=20" },
-    files: ["bin", "dist", "web", "prisma", "docs", "scripts", "README.md", "LICENSE"],
+    // Whitelist ini menang atas isi dist-npm: direktori yang tak disebut dibuang `npm pack` diam-diam
+    // (0.9.38 terbit tanpa `skills/`). Penjaganya di cli/test/pack.test.ts.
+    files: ["bin", "dist", "web", "prisma", "docs", "scripts", "skills", "README.md", "LICENSE"],
     dependencies: deps,
     // MIT: paket ini didistribusikan publik supaya orang `npm i -g`. `UNLICENSED` berarti "tak ada
     // izin pakai" — 0.1.0 terbit dengan kontradiksi itu, dan versi terbit tak bisa diperbaiki.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hanoman",
-  "version": "0.9.38",
+  "version": "0.9.39",
   "description": "Orchestrator + dashboard workflow docs-driven untuk sesi Claude Code / Codex",
   "type": "module",
   "repository": {
@@ -24,6 +24,7 @@
     "prisma",
     "docs",
     "scripts",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/codex-image/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: codex-image
+description: Use when a task needs a raster image that does not exist yet — mascot or character art, illustrations, hero and banner images, sprite sheets, textures, product or UI mockups, concept art, transparent-background cutouts — or when an existing PNG/JPG needs an AI edit (background removal, object swap, style transfer, relighting). Also use when you are about to hand-write SVG, CSS shapes, or an emoji placeholder to stand in for artwork you cannot actually draw, or when asked to "generate an image", "buatkan ilustrasi", "bikin gambar".
+---
+
+# Generating images with Codex
+
+## Overview
+
+You cannot render bitmaps. Codex can: its built-in `image_gen` tool (GPT Image) needs no
+`OPENAI_API_KEY` — it rides the user's ChatGPT login. So image generation is **delegated**,
+not simulated.
+
+**Core principle: a request for artwork is a request for pixels.** A hand-written SVG of a
+fox is not a fox illustration. If the deliverable is a picture, spawn Codex and return a
+verified PNG file path.
+
+## Pick the engine first
+
+This skill ships with hanoman (bundled in the npm package, seeded into
+`$HANOMAN_HOME/skills/codex-image`, injected into every agent session). Which engine you use
+depends on the runtime you are:
+
+| You are | Engine | How |
+|---|---|---|
+| **Codex** (you have the built-in `image_gen` tool) | `image_gen` directly, via Codex's own `imagegen` skill | Do **not** shell out to `codex exec` from inside Codex. Generate, then copy the chosen file from `$CODEX_HOME/generated_images/...` (default `~/.codex/generated_images/...`) to the destination path. |
+| **Anything else** (Claude Code, Antigravity, other CLIs) | `scripts/codex-image.sh` (spawns `codex exec`) | Everything below. Needs the `codex` CLI installed and logged in (`codex login`) on this machine. |
+
+The spec format, sizes, verification rules and the "no substitute" rule below apply to both.
+
+## When to use
+
+Delegate to Codex when the deliverable is a **bitmap that has to be drawn**:
+
+- mascots, characters, avatars, sprite sheets
+- illustrations, hero/banner/OG images, backgrounds, textures
+- photorealistic product shots, packaging and merch mockups
+- concept art, storyboards, book/comic panels
+- transparent-background cutouts and object isolation
+- editing an existing raster: remove/replace an object, change lighting or season,
+  swap a background, apply a reference style, sketch → render
+
+## When NOT to use
+
+Reach for code, not Codex, when the output is **structural rather than drawn**:
+
+| Task | Do this instead |
+|---|---|
+| Charts, plots, dashboards | Load the `dataviz` skill and write chart code |
+| Flowcharts, architecture diagrams | Inline SVG or mermaid |
+| Icons matching an existing SVG icon set | Edit the vector set directly |
+| Logo systems already defined in vector | Edit the source vector |
+| UI built from real components | Build it in HTML/CSS |
+| Screenshot of something that exists | Run it and capture it |
+
+Generated bitmaps cannot be diffed, recolored by token, or scaled cleanly. If the asset
+belongs to a design system, that is a reason to draw it in code.
+
+## Quick reference
+
+```bash
+S="${HANOMAN_HOME:-$HOME/.hanoman}/skills/codex-image/scripts/codex-image.sh"
+
+# one asset
+"$S" --out assets/mascot.png --size 1024x1024 --transparent --fit <<'SPEC'
+Use case: illustration-story
+Asset type: dashboard empty-state mascot
+Primary request: a small orange fox sitting, waving one paw
+Style/medium: flat vector-style illustration, thick clean outlines
+Composition/framing: full body, centered, generous margin
+Color palette: warm orange, cream, one teal accent
+Constraints: no text, no watermark, no drop shadow
+SPEC
+
+# several assets, with references
+"$S" --out-dir assets/icons --name icon --count 4 --ref brand/palette.png <<'SPEC'
+...
+SPEC
+```
+
+Run `"$S" --help` for every flag.
+
+**Budget 1–3 minutes per image.** A default shell call times out at two minutes, so run the
+script as a background command and pick it up from the notification — or raise the timeout past
+`--count x 180s`. Three concurrent jobs are safe; use them for independent assets rather than
+raising `--count`, so one bad asset does not cost you the batch.
+
+## hanoman `Mockup` phase
+
+In hanoman's `Mockup` phase (ADR-0233) the deliverable is a UI mockup that a human approves before
+planning. One image per changed screen or state, at most 6, saved as
+`docs/mockups/<spec-id>/<NN>-<slug>.png`:
+
+```bash
+"$S" --out docs/mockups/spec-123/01-backlog-detail.png --size 1536x1024 --fit <<'SPEC'
+Use case: ui-mockup
+Asset type: product UI mockup for design approval (desktop, 1536x1024)
+Primary request: backlog detail screen with a new "Mockup" section showing three thumbnails
+Style/medium: crisp flat product UI screenshot, real-looking components, no device frame
+Composition/framing: full screen, left sidebar, content column, generous whitespace
+Color palette: <the project's design-system tokens, e.g. bone paper #F4EFE6, ink #1F1B16, brass #B08A3E>
+Text (verbatim): "Mockup", "Lihat mockup (3)"
+Constraints: follow the existing layout of the screen; only the new section changes
+Avoid: lorem ipsum, watermark, browser chrome, illegible text
+SPEC
+```
+
+Add `--size 1024x1536` mobile variants when the change touches a responsive layout. A missing
+`codex` or a failed login is a blocker to report and ask about — never a reason to hand-draw.
+
+## Writing the spec
+
+Codex's `imagegen` skill expects a labeled spec. Fill only the lines that carry information —
+an unused line is noise, and a vague line ("nice colors") is worse than an absent one.
+
+```text
+Use case: <photorealistic-natural | product-mockup | ui-mockup | infographic-diagram |
+           ads-marketing | logo-brand | illustration-story | stylized-concept |
+           background-extraction | precise-object-edit | style-transfer | compositing>
+Asset type: <where this will actually be used>
+Primary request: <the subject, in one sentence>
+Scene/backdrop: <environment>
+Style/medium: <flat illustration | studio photo | 3D render | watercolor | ...>
+Composition/framing: <wide/close/top-down, placement, margins>
+Lighting/mood: <lighting + mood>
+Color palette: <named colors or hex>
+Text (verbatim): "<exact string, spelled out letter by letter if tricky>"
+Constraints: <what must be kept>
+Avoid: <what must not appear>
+```
+
+**Editing an existing image:** pass it with `--ref`, set an edit `Use case`, and state the
+invariants explicitly — `change only the background; keep the product, its edges and its
+colors unchanged`. Repeat those invariants on every retry; they drift otherwise.
+
+## Sizes
+
+`gpt-image-2` accepts `auto` or `WIDTHxHEIGHT` where both edges are multiples of 16, the
+long edge is ≤ 3840, the ratio is ≤ 3:1, and total pixels fall between 655,360 and 8,294,400.
+
+| Size | Use |
+|---|---|
+| `1024x1024` | square default, fastest |
+| `1536x1024` / `1024x1536` | landscape / portrait |
+| `2048x1152` | 2K landscape, hero images |
+| `3840x2160` / `2160x3840` | 4K |
+
+`image_gen` reads this as guidance, not a contract, and will return a nearby size. Pass `--fit`
+whenever the layout depends on exact pixels.
+
+## Verifying the result
+
+The script already does this, and its exit code is the honest signal:
+
+| Exit | Meaning | Next step |
+|---|---|---|
+| 0 | every requested PNG exists and `file` confirms it | report the paths |
+| 2 | usage error | fix the flags |
+| 3 | Codex turn failed | read the reason; if auth, run `codex login` |
+| 4 | Codex produced no image | retry with a more concrete spec |
+| 5 | timeout | raise `--timeout`, or lower `--count` |
+| 6 | `--transparent` asked, opaque result | the file is kept — look at it, then retry with `no checkerboard` in `Avoid` |
+
+Never report an image as delivered without an `OK <path>` line. `ls` the file if you want a
+second opinion — but do not describe what the picture looks like unless you read it with the
+image-reading tool, and say so when you have not looked.
+
+## When generation fails
+
+**A substitute is not the asset.** If Codex cannot generate the image, deliver **no file** and
+report the blocker. Do not hand-author an SVG, CSS shape, or emoji composite, rasterise it, and
+save it under the filename that was asked for — the caller cannot tell the difference from the
+file, and the next person to touch it inherits a fake.
+
+Measured baseline: an agent given a 6-minute budget hit the auth wall, wrote fox-shaped SVG
+paths by hand, rasterised them to `mascot.png`, and shipped it. Its reasoning: *"the 6-minute
+budget doesn't tolerate betting on a single path."*
+
+| Rationalization | Reality |
+|---|---|
+| "I'll build a fallback in parallel to be safe" | The fallback becomes the deliverable. Fix the blocker instead; it is usually one `codex login`. |
+| "It's still a real raster PNG with real alpha" | The file format was never the requirement. The artwork was. |
+| "I disclosed it in my report" | The report is thrown away; the file is committed. Filename `mascot.png` claims to be the mascot. |
+| "The deadline doesn't allow a retry" | A missing asset is a known gap. A hand-drawn stand-in is an unknown one. Report the gap. |
+| "Close enough to unblock the layout" | Then name it `mascot.placeholder.svg` and say it is a placeholder — never the requested filename. |
+
+Blocked on auth? Say so plainly and give the user the one command: `codex login`.
+
+## Common mistakes
+
+| Mistake | Reality |
+|---|---|
+| Trusting `codex exec`'s exit code | It exits **0** on a failed turn. Only the JSONL event stream and the file on disk tell the truth — the script checks both. |
+| Trusting `codex login status` | It reports "Logged in using ChatGPT" while the refresh token is revoked. A `turn.failed` mentioning `revoked` / 401 is the real answer: run `codex login`. |
+| Letting Codex post-process | Its imagegen skill will happily run `remove_chroma_key.py --despill`, which **cuts red out of reds** — gold goes olive, red cloth goes dull. The script forbids it; do your own keying downstream. |
+| Asking for "16-bit pixel art" | You get a high-resolution illustration that merely looks pixelated. Real pixels only come from a nearest-neighbour downscale afterwards. |
+| Feeding a `.webp` reference | `--ref` takes PNG/JPG. Convert first: `dwebp in.webp -o out.png`. |
+| Generating into the repo blindly | Raw outputs also land in `~/.codex/generated_images/<thread-id>/`. Put deliverables where the project expects them, and add large raws to `.gitignore`. |
+| One prompt, `n` variants, many assets | Distinct assets need distinct calls. `--count` issues one `image_gen` call per file. |
+| Correcting a retry with just the fix | A partial correction makes the model forget the constraints it already satisfied. Restate the **whole** spec plus the new constraint. |
+| Assuming `--size` is honoured | `image_gen` treats size as a **hint**. Measured: `1024x1024` requested, `1254x1254` returned. The script prints a NOTE on any mismatch; pass `--fit` when the pixel dimensions are a real requirement. |
+| Polling the destination while the job runs | The script copies into place only at the very end. An empty destination mid-run is not a failure — wait for the `OK <path>` line and the exit code. |
+| Combining `--ref` with `--transparent` | A reference image routes the request through the **edit** path, which flattens alpha. Measured on one spec: 0.0% clear pixels with a reference (twice), ~59% without (twice). Anti-checkerboard wording does not rescue it. For a transparent asset, anchor style in **words**, not an attachment — and expect line weight to drift, so state it numerically ("uniform charcoal contour ~8px at 1024"). |
+| Believing `--transparent` produced transparency | The model can **paint the checkerboard** — the visual convention for transparency — as opaque pixels. Measured: a retry came back 0.0% transparent while the first attempt was 58.9%, same flag, valid PNG, exit 0. The script now gates this (exit 6); always put `no checkerboard, no fake transparency grid` in `Avoid`. |
+| Expecting a batch to be a matched *set* | One job gives you consistent style but not consistent **optical scale**. Measured on a 4-icon set: alpha bbox filled 81%, 82%, 95%, 85% of the frame. Normalize in post with `scripts/normalize-set.py` rather than regenerating. |
+| Assuming the palette line is binding | It is a strong hint, not a constraint. In the same set one icon came back with red and blue ruled lines (1.0% off-palette pixels against 0.0% for the other three). Measure hue drift instead of eyeballing it. |
+| Editing the script while a job is running | Bash reads a script incrementally from disk; patching it mid-run shifts the offsets and kills the job with a bogus syntax error. Finish the run first. |
+
+## Finishing an icon or asset set
+
+One job gives a set consistent style but not consistent size. Even out the optical scale
+deterministically instead of burning generations on it:
+
+```bash
+python3 "${HANOMAN_HOME:-$HOME/.hanoman}/skills/codex-image/scripts/normalize-set.py" \
+  assets/icons/icon-*.png --dry-run          # see the scale factors first
+```
+
+It crops each icon to its alpha bounding box, rescales so the set matches on one metric, and
+re-pads to the original canvas. `--metric bbox` (default) makes every icon fill the same box;
+`--metric area` suits a set where one subject is mostly empty space. Look at a contact sheet
+over a mid-grey ground before committing — transparency hides scale problems on white.
+
+For sprite sheets and animation strips, read `references/sprite-sheets.md` — the grid, tail,
+and registration traps there cost days to rediscover.

package/skills/codex-image/references/sprite-sheets.md

@@ -0,0 +1,60 @@
+# Sprite sheets and animation strips
+
+Generating an animated character is not "generate 8 images". It is one sheet, then a
+cutting-and-registration pipeline you own. These traps were each paid for once.
+
+## Generating the sheet
+
+Ask for **one sheet** (e.g. `1536x1024`, one row of 8 frames) rather than 8 separate images —
+separate calls give you 8 different characters. Then:
+
+- **Ask for the raw sheet only.** Codex's imagegen skill will otherwise run
+  `remove_chroma_key.py --soft-matte --despill` on its own. Despill against magenta **subtracts
+  red from red pixels**: gold turns olive, red cloth turns dull. Do the keying yourself.
+- **Key on green `#00FF00`, not magenta**, for the same reason.
+- Keep the standing character well under the cell height (a 192px character in a 192px cell
+  spills its tail into the neighbour; ~168px inside 192px is safe) and clip per cell. Treat
+  spill as a gate failure, not a rounding error.
+- Floating ornaments (stars, sparkles) must **touch the character silhouette**. A detached blob
+  smaller than ~40×80px and ≥8 columns away gets dropped silently by blob detection.
+- "16-bit pixel art" in the prompt yields a high-resolution illustration that looks pixelated.
+  Real pixels come from `resize(NEAREST)` to the logical size afterwards.
+
+## Cutting
+
+**The model does not obey your grid.** Bounding boxes drift up to ~97px along a row and sprites
+cross cell borders. Detect sprites from transparent gutters, never by slicing at fixed offsets.
+
+## Registration
+
+Anchoring on the feet alone jitters ±15px, because the tail tip enters the foot bounding box.
+
+- **Find feet by mass, not by side.** In the bottom band, a grazing tail is a thin line
+  (~80–100px of mass) next to real feet (~300–600px). A "rightmost run" rule is exactly wrong
+  for a walk-left row drawn with the tail on the right, and mid-stride feet are two runs.
+- Register with an XOR-mask over the static region (rows ≥45%, columns ≥ feet−12) plus a ±8%
+  scale search. That gets residual to 0.01–0.07; the remainder is shape difference.
+- **Pinning the static region freezes a rectangle** and will amputate a hand that moves through
+  it. Plain erosion cuts the arm while the palm survives — the hand reads as severed. Use
+  morphological reconstruction: grow the eroded seed inside the difference map until stable.
+- Do not normalise the frame-1 bbox to a fixed height — anything that lengthens the bbox (a
+  dangling tail) silently shrinks the character. Gate on `body_ratio` (eroded bbox height ÷ full
+  bbox height); healthy rows sit at 0.84–0.91. For curled poses gate on body **mass** instead.
+
+## Reviewing
+
+- Onion-skin (mean alpha across frames, pixel ratio 0.2–0.8) is the cheapest jitter measure.
+- A QA GIF with a **per-frame adaptive palette** shifts colours every frame and reads as a
+  flicker that is not in the strip. Use one global palette.
+- The **8→1 loop seam is invisible** in both contact sheets and onion-skins. Gate it as a
+  ratio of largest to smallest inter-frame step (threshold ~3.5), not an absolute value, and
+  guard it with "visible motion ≥ 0.10" — otherwise a barely-moving row passes vacuously.
+- Calibrate residual gates across all rows, not on the idle row. A gate tuned to idle punishes
+  correct animation.
+
+## Retrying
+
+Restate the **entire** constraint set on every retry, including the constraints already
+satisfied. A partial correction makes the model forget what it had got right.
+
+Cost of record: 1–3 attempts per row; ~1–3 minutes per sheet; 3 concurrent jobs are safe.

package/skills/codex-image/scripts/codex-image.sh

@@ -0,0 +1,253 @@
+#!/usr/bin/env bash
+# codex-image.sh — spawn Codex to generate raster images, land verified PNGs on disk.
+# Codex's built-in image_gen tool needs no OPENAI_API_KEY; it uses the ChatGPT login.
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+codex-image.sh — generate PNG assets via Codex's built-in image_gen tool.
+
+Usage:
+  codex-image.sh --out FILE.png            [options] < spec.txt
+  codex-image.sh --out-dir DIR --count N   [options] < spec.txt
+
+The image spec is read from stdin (use a heredoc or a file).
+
+Options:
+  -o, --out FILE        Destination PNG for a single asset. Implies --count 1.
+      --out-dir DIR     Destination directory when generating several assets.
+      --name PREFIX     Filename prefix under --out-dir (default: asset).
+  -n, --count N         Number of distinct assets to generate (default: 1, max 8).
+  -r, --ref FILE        Reference image passed to Codex (repeatable, PNG/JPG).
+  -s, --size WxH        Pixel size (default: 1024x1024). Both edges multiples of 16,
+                        max edge 3840, ratio <= 3:1, 655360..8294400 total pixels.
+  -t, --transparent     Ask for a genuinely transparent background.
+      --fit             Resize the result to exactly --size (image_gen treats size as a hint).
+      --raw             Harvest from ~/.codex/generated_images instead of Codex's copies.
+      --effort LEVEL    Codex reasoning effort: low|medium|high (default: low).
+      --timeout SEC     Hard timeout (default: 900).
+      --keep            Keep the staging directory for debugging.
+  -h, --help            Show this help.
+
+Exit codes:
+  0 success (every requested PNG exists and is a real PNG)
+  2 usage error
+  3 Codex turn failed (see the printed reason)
+  4 Codex produced no image
+  5 timeout
+  6 --transparent was asked for but the result is opaque (file kept for inspection)
+USAGE
+}
+
+OUT_FILE=""; OUT_DIR=""; NAME="asset"; COUNT=1; SIZE="1024x1024"
+TRANSPARENT=0; RAW=0; EFFORT="low"; TIMEOUT=900; KEEP=0; FIT=0
+REFS=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -o|--out)         OUT_FILE="$2"; shift 2 ;;
+    --out-dir)        OUT_DIR="$2"; shift 2 ;;
+    --name)           NAME="$2"; shift 2 ;;
+    -n|--count)       COUNT="$2"; shift 2 ;;
+    -r|--ref)         REFS+=("$2"); shift 2 ;;
+    -s|--size)        SIZE="$2"; shift 2 ;;
+    -t|--transparent) TRANSPARENT=1; shift ;;
+    --fit)            FIT=1; shift ;;
+    --raw)            RAW=1; shift ;;
+    --effort)         EFFORT="$2"; shift 2 ;;
+    --timeout)        TIMEOUT="$2"; shift 2 ;;
+    --keep)           KEEP=1; shift ;;
+    -h|--help)        usage; exit 0 ;;
+    *) echo "codex-image: unknown option: $1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+command -v codex >/dev/null 2>&1 || { echo "codex-image: codex CLI not found on PATH" >&2; exit 2; }
+
+if [[ -n "$OUT_FILE" ]]; then
+  [[ -n "$OUT_DIR" ]] && { echo "codex-image: use --out or --out-dir, not both" >&2; exit 2; }
+  COUNT=1
+  OUT_DIR="$(cd "$(dirname "$OUT_FILE")" 2>/dev/null && pwd)" || {
+    echo "codex-image: destination directory does not exist: $(dirname "$OUT_FILE")" >&2; exit 2; }
+elif [[ -n "$OUT_DIR" ]]; then
+  mkdir -p "$OUT_DIR"
+  OUT_DIR="$(cd "$OUT_DIR" && pwd)"
+else
+  echo "codex-image: --out or --out-dir is required" >&2; usage >&2; exit 2
+fi
+
+[[ "$COUNT" =~ ^[1-8]$ ]] || { echo "codex-image: --count must be 1..8" >&2; exit 2; }
+[[ "$SIZE" =~ ^[0-9]+x[0-9]+$ ]] || { echo "codex-image: --size must look like 1536x1024" >&2; exit 2; }
+for r in "${REFS[@]+"${REFS[@]}"}"; do
+  [[ -f "$r" ]] || { echo "codex-image: reference image not found: $r" >&2; exit 2; }
+done
+
+if [[ "$TRANSPARENT" == "1" && ${#REFS[@]} -gt 0 ]]; then
+  echo "codex-image: WARNING --ref together with --transparent reliably returns an OPAQUE image" >&2
+  echo "codex-image: (measured: 0.0% clear with a reference, ~59% without, same spec). Reference" >&2
+  echo "codex-image: images route through the edit path, which flattens alpha and paints a fake" >&2
+  echo "codex-image: transparency checkerboard. Describe the style in words instead of attaching one." >&2
+fi
+
+SPEC="$(cat)"
+[[ -n "${SPEC//[[:space:]]/}" ]] || { echo "codex-image: empty spec on stdin" >&2; exit 2; }
+
+STAGE="$(mktemp -d "${TMPDIR:-/tmp}/codex-image.XXXXXX")"
+cleanup() { [[ "$KEEP" == "1" ]] || rm -rf "$STAGE"; }
+trap cleanup EXIT
+[[ "$KEEP" == "1" ]] && echo "codex-image: staging dir $STAGE" >&2
+
+# --- build the prompt: the caller's spec plus a hard output contract ---
+{
+  echo "Generate raster image assets with your built-in image_gen tool (imagegen skill)."
+  echo
+  echo "=== IMAGE SPEC ==="
+  echo "$SPEC"
+  echo
+  echo "Size: ${SIZE}."
+  [[ "$TRANSPARENT" == "1" ]] && echo "Background: genuinely transparent; preserve the alpha channel."
+  if [[ ${#REFS[@]} -gt 0 ]]; then
+    echo "Attached images are references for style, subject and composition — not edit targets,"
+    echo "unless the spec above says otherwise."
+  fi
+  echo
+  echo "=== OUTPUT CONTRACT ==="
+  echo "Your deliverable is exactly ${COUNT} PNG file(s) in your current working directory:"
+  for i in $(seq 1 "$COUNT"); do printf '  %s-%02d.png\n' "$NAME" "$i"; done
+  if [[ "$COUNT" -gt 1 ]]; then
+    echo "If the spec above enumerates ${COUNT} distinct subjects, render them in the order listed,"
+    echo "one subject per file, sharing the style, palette and framing stated once at the top."
+    echo "If it describes a single subject, render ${COUNT} variants of that subject instead."
+  fi
+  echo "Each file is the image_gen output written to disk unchanged — same pixels, same alpha,"
+  echo "same dimensions as generated. Issue one image_gen call per file."
+  echo "Write nothing else: no README, no notes, no scripts, no edits to any other file."
+  echo "Do not run remove_chroma_key.py, do not despill, do not crop, resize or recolor."
+  echo "Finish with one line per file, and nothing after them:"
+  echo "SAVED: <absolute path>"
+} > "$STAGE/prompt.txt"
+
+GEN_DIR="${CODEX_HOME:-$HOME/.codex}/generated_images"
+mkdir -p "$GEN_DIR"
+CODEX_ARGS=(exec --skip-git-repo-check -s workspace-write -C "$STAGE" --add-dir "$GEN_DIR"
+            -c "model_reasoning_effort=\"$EFFORT\"" --json -o "$STAGE/last.txt")
+for r in "${REFS[@]+"${REFS[@]}"}"; do CODEX_ARGS+=(-i "$r"); done
+CODEX_ARGS+=(-)
+
+echo "codex-image: generating ${COUNT} image(s) at ${SIZE} (timeout ${TIMEOUT}s)…" >&2
+codex "${CODEX_ARGS[@]}" < "$STAGE/prompt.txt" > "$STAGE/events.jsonl" 2> "$STAGE/stderr.txt" &
+CODEX_PID=$!
+WAITED=0
+while kill -0 "$CODEX_PID" 2>/dev/null; do
+  if [[ "$WAITED" -ge "$TIMEOUT" ]]; then
+    kill -TERM "$CODEX_PID" 2>/dev/null || true; sleep 2
+    kill -KILL "$CODEX_PID" 2>/dev/null || true
+    echo "codex-image: TIMEOUT after ${TIMEOUT}s" >&2
+    exit 5
+  fi
+  sleep 3; WAITED=$((WAITED + 3))
+done
+wait "$CODEX_PID" 2>/dev/null || true   # codex exec exits 0 even when the turn failed
+
+# --- codex exec's exit code lies; the events stream is the source of truth ---
+FAIL="$(python3 - "$STAGE/events.jsonl" <<'PY'
+import json, sys
+reason = ""
+for line in open(sys.argv[1], encoding="utf-8", errors="replace"):
+    line = line.strip()
+    if not line: continue
+    try: ev = json.loads(line)
+    except Exception: continue
+    if ev.get("type") == "turn.failed":
+        reason = (ev.get("error") or {}).get("message", "turn failed")
+    elif ev.get("type") == "error" and not reason:
+        reason = ev.get("message", "error")
+print(reason)
+PY
+)"
+if [[ -n "$FAIL" ]]; then
+  echo "codex-image: Codex turn FAILED: $FAIL" >&2
+  case "$FAIL" in
+    *revoked*|*"log in again"*|*[Uu]nauthorized*|*401*)
+      echo "codex-image: the ChatGPT login is stale. Run 'codex login' and retry." >&2 ;;
+  esac
+  exit 3
+fi
+
+THREAD="$(python3 - "$STAGE/events.jsonl" <<'PY'
+import json, sys
+for line in open(sys.argv[1], encoding="utf-8", errors="replace"):
+    try: ev = json.loads(line)
+    except Exception: continue
+    if ev.get("type") == "thread.started":
+        print(ev.get("thread_id", "")); break
+PY
+)"
+
+# --- harvest: Codex's saved deliverables, else the raw generated_images drop ---
+RAW_DIR="${CODEX_HOME:-$HOME/.codex}/generated_images/$THREAD"
+FOUND=()
+if [[ "$RAW" == "0" ]]; then
+  while IFS= read -r f; do FOUND+=("$f"); done < <(find "$STAGE" -maxdepth 1 -name '*.png' | sort)
+fi
+if [[ ${#FOUND[@]} -eq 0 && -d "$RAW_DIR" ]]; then
+  [[ "$RAW" == "0" ]] && echo "codex-image: no PNG in staging; falling back to raw $RAW_DIR" >&2
+  while IFS= read -r f; do FOUND+=("$f"); done < <(ls -t "$RAW_DIR"/*.png 2>/dev/null | head -n "$COUNT" | sort)
+fi
+if [[ ${#FOUND[@]} -eq 0 ]]; then
+  echo "codex-image: Codex produced no image. Its final message was:" >&2
+  sed 's/^/  | /' "$STAGE/last.txt" >&2 2>/dev/null || true
+  exit 4
+fi
+if [[ ${#FOUND[@]} -lt "$COUNT" ]]; then
+  echo "codex-image: WARNING wanted $COUNT image(s), got ${#FOUND[@]}" >&2
+fi
+
+# --- verify every file really is a PNG, then place it ---
+STATUS=0; i=0
+for src in "${FOUND[@]}"; do
+  i=$((i + 1)); [[ "$i" -gt "$COUNT" ]] && break
+  if [[ -n "$OUT_FILE" ]]; then dst="$OUT_FILE"; else dst="$(printf '%s/%s-%02d.png' "$OUT_DIR" "$NAME" "$i")"; fi
+  cp -f "$src" "$dst"
+  if ! file -b "$dst" | grep -qi '^PNG image data'; then
+    echo "codex-image: NOT a PNG: $dst ($(file -b "$dst"))" >&2; STATUS=4; continue
+  fi
+  read_dims() { file -b "$1" | sed -n 's/.*, \([0-9]*\) x \([0-9]*\),.*/\1x\2/p'; }
+  dims="$(read_dims "$dst")"
+  if [[ -n "$dims" && "$dims" != "$SIZE" ]]; then
+    if [[ "$FIT" == "1" ]] && command -v sips >/dev/null 2>&1; then
+      sips -z "${SIZE#*x}" "${SIZE%x*}" "$dst" --out "$dst" >/dev/null 2>&1
+      echo "codex-image: resized $dims -> $SIZE (--fit)" >&2
+      dims="$(read_dims "$dst")"
+    else
+      echo "codex-image: NOTE image_gen returned $dims, not the requested $SIZE — it treats size as a hint. Pass --fit to resize." >&2
+    fi
+  fi
+  if [[ "$TRANSPARENT" == "1" ]]; then
+    chk="$(python3 - "$dst" <<'PYCHK'
+import sys
+try:
+    from PIL import Image
+except ImportError:
+    print("skip"); raise SystemExit
+im = Image.open(sys.argv[1]).convert("RGBA")
+clear = sum(im.getchannel("A").histogram()[:9]) / (im.width * im.height)
+corners = [im.getpixel(p)[3] for p in
+           [(0, 0), (im.width - 1, 0), (0, im.height - 1), (im.width - 1, im.height - 1)]]
+print("ok" if clear >= 0.05 and max(corners) < 16 else "opaque %.1f%%" % (clear * 100))
+PYCHK
+)"
+    case "$chk" in
+      ok) ;;
+      skip) echo "codex-image: NOTE Pillow missing, transparency not verified: $dst" >&2 ;;
+      *) echo "codex-image: TRANSPARENCY FAILED $dst (only $chk of pixels are clear)." >&2
+         echo "codex-image: the model most likely PAINTED a transparency checkerboard instead of" >&2
+         echo "codex-image: leaving alpha. Add 'no checkerboard, no fake transparency grid' to Avoid." >&2
+         printf 'BAD %s (%s) — opaque background, not delivered as transparent\n' \
+                "$dst" "${dims:-unknown size}"
+         STATUS=6; continue ;;
+    esac
+  fi
+  printf 'OK %s (%s, %s bytes)\n' "$dst" "${dims:-unknown size}" "$(wc -c < "$dst" | tr -d ' ')"
+done
+[[ "$STATUS" == "0" ]] || exit "$STATUS"

package/skills/codex-image/scripts/normalize-set.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""Normalize a set of transparent PNG icons to one optical scale.
+
+One generation job gives consistent style but not consistent size: subjects come back
+filling anywhere from 80% to 95% of the frame, so the set looks ragged in a row.
+
+Scaling by bounding box is wrong for mixed shapes — a pocket watch on a chain is tall,
+so bbox-matching shrinks its face next to a wide open book. This matches *ink area*
+(sqrt of opaque pixel count), which is what the eye actually reads as "the same size",
+then clamps anything that would overflow the frame.
+
+Three metrics, because no single one is right for mixed shapes:
+
+  bbox    match the longest edge, so every icon fills the same box (default). This is
+          what icon systems usually specify, and it won a side-by-side on a measured
+          4-icon set: area and hybrid both shrank a dense solid object (a monitor, to
+          73% and 79% of frame) until it read as weaker than its neighbours.
+  area    match sqrt(opaque pixel count). Reach for it when one icon is mostly empty
+          space — a long thin antenna or tail — and bbox would shrink the real subject.
+  hybrid  geometric mean of the two.
+
+Always check with --dry-run and a contact sheet before committing; the right metric is a
+property of the particular set, not a rule.
+
+  normalize-set.py icon-*.png [--metric hybrid] [--margin 0.08] [--out-dir DIR] [--dry-run]
+"""
+import argparse, sys
+from pathlib import Path
+
+try:
+    from PIL import Image
+except ImportError:
+    sys.exit("normalize-set: needs Pillow — pip install pillow")
+
+ALPHA_FLOOR = 8  # ignore near-transparent halo pixels
+
+
+def measure(path):
+    im = Image.open(path).convert("RGBA")
+    mask = im.getchannel("A").point(lambda v: 255 if v > ALPHA_FLOOR else 0)
+    bbox = mask.getbbox()
+    if bbox is None:
+        raise ValueError(f"{path.name} is fully transparent")
+    area = mask.crop(bbox).histogram()[255]
+    return im, bbox, area
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("files", nargs="+", type=Path)
+    ap.add_argument("--metric", choices=("bbox", "area", "hybrid"), default="bbox",
+                    help="what to equalize across the set (default: bbox)")
+    ap.add_argument("--margin", type=float, default=0.08,
+                    help="fraction of the canvas kept clear on the long edge (default 0.08)")
+    ap.add_argument("--out-dir", type=Path, default=None,
+                    help="write here instead of overwriting the inputs")
+    ap.add_argument("--dry-run", action="store_true")
+    a = ap.parse_args()
+
+    items = []
+    for f in a.files:
+        im, bbox, area = measure(f)
+        items.append({"path": f, "im": im, "bbox": bbox, "area": area})
+
+    canvas = items[0]["im"].size
+    for it in items:
+        if it["im"].size != canvas:
+            sys.exit(f"normalize-set: {it['path'].name} is {it['im'].size}, expected {canvas} "
+                     "— resize the set to one canvas first")
+
+    limit = min(canvas) * (1 - a.margin)
+    target_area = sum(it["area"] for it in items) / len(items)
+    target_edge = sum(max(it["bbox"][2] - it["bbox"][0],
+                          it["bbox"][3] - it["bbox"][1]) for it in items) / len(items)
+
+    print(f"{'file':<22}{'fill before':>12}{'scale':>8}{'fill after':>12}")
+    for it in items:
+        w, h = it["bbox"][2] - it["bbox"][0], it["bbox"][3] - it["bbox"][1]
+        before = max(w, h) / max(canvas)
+        s_area = (target_area / it["area"]) ** 0.5
+        s_bbox = target_edge / max(w, h)
+        scale = {"area": s_area, "bbox": s_bbox,
+                 "hybrid": (s_area * s_bbox) ** 0.5}[a.metric]
+        if max(w, h) * scale > limit:          # clamp: never overflow the frame
+            scale = limit / max(w, h)
+        nw, nh = max(1, round(w * scale)), max(1, round(h * scale))
+
+        out = Image.new("RGBA", canvas, (0, 0, 0, 0))
+        out.alpha_composite(it["im"].crop(it["bbox"]).resize((nw, nh), Image.LANCZOS),
+                            ((canvas[0] - nw) // 2, (canvas[1] - nh) // 2))
+
+        dst = it["path"] if a.out_dir is None else a.out_dir / it["path"].name
+        if not a.dry_run:
+            if a.out_dir:
+                a.out_dir.mkdir(parents=True, exist_ok=True)
+            out.save(dst)
+        print(f"{it['path'].name:<22}{before:>11.1%}{scale:>8.3f}{max(nw, nh)/max(canvas):>11.1%}")
+
+    if a.dry_run:
+        print("\n(dry run — nothing written)")
+
+
+if __name__ == "__main__":
+    main()