@leejungkiin/awkit 1.7.0 → 1.7.4

package/skills/generate-gui-assets/references/catalog-schema.md

@@ -0,0 +1,58 @@
+# GUI Asset Catalog Schema
+
+## catalog.json
+
+Use one catalog per generation run.
+
+```json
+{
+  "runId": "gui-v1",
+  "createdAt": "2026-05-23T00:00:00Z",
+  "styleNotes": "cozy mobile wellness garden icons",
+  "chromaKey": "#FF00FF",
+  "packs": [
+    {
+      "id": "ui_nav_core",
+      "grid": "4x3",
+      "icons": ["home", "garden"],
+      "promptFile": "prompts/ui_nav_core.txt",
+      "rawFile": "raw/ui_nav_core.png",
+      "source": {
+        "generator": "imagegen",
+        "path": "/absolute/path/to/generated/ig_*.png",
+        "recordedAt": "2026-05-23T00:00:00Z"
+      },
+      "qa": {
+        "state": "pending",
+        "notes": ""
+      }
+    }
+  ]
+}
+```
+
+## icons_manifest.json
+
+Use after extraction/copy approval.
+
+```json
+{
+  "runId": "gui-v1",
+  "sourceDir": "assets/ui/generated/gui-v1/manual_crop/extracted_icons_mask",
+  "technique": "copy-approved-icons-as-is",
+  "icons": [
+    {
+      "name": "home",
+      "file": "icons/home.png",
+      "source": "source-file.png"
+    }
+  ]
+}
+```
+
+## Rules
+
+- Keep paths relative to the run directory when possible.
+- Store absolute generator source paths only for provenance.
+- Use `qa.state` values: `pending`, `approved`, `regenerate`, or `rejected`.
+- Do not mark a pack approved until a contact sheet or direct visual inspection exists.

package/skills/generate-gui-assets/references/extraction-techniques.md

@@ -0,0 +1,21 @@
+# Extraction Techniques
+
+## Approved Extraction Rule
+
+When a source package says an extraction method is approved, do not recut, resegment, resize, or visually modify the source icons.
+
+Allowed deterministic actions:
+
+- Copy icons as-is into a flat `icons/` folder.
+- Rename by semantic mapping.
+- Add duplicate-safe suffixes such as `_2` and `_3`.
+- Record full provenance in `icons_manifest.json`.
+
+## When To Stop
+
+Stop and ask for direction if:
+
+- The source icon count does not match the semantic mapping.
+- The source package includes mixed extraction methods and no approved technique is identified.
+- The user asks for visual cleanup that would alter approved pixels.
+- File names cannot be mapped deterministically to semantic names.

package/skills/generate-gui-assets/references/prompt-patterns.md

@@ -0,0 +1,58 @@
+# GUI Asset Prompt Patterns
+
+## Master Atlas
+
+Use for early style discovery across many related packs.
+
+```text
+Create one high-resolution GUI asset master atlas on a flat #FF00FF chroma-key background.
+Style: <product/game style>, consistent palette, crisp clean edges, readable silhouettes.
+Groups: <number> labeled only in this prompt, not in the image.
+Each group uses its own grid: <pack name> <grid> with icons <names in row order>.
+Layout: equal spacing, centered icons, 10% safe margin, no object touches cell borders.
+Quality rules: no text, no labels, no guide marks, no shadows, no glow, no scenery, no duplicate generic placeholders, no clipping, no overlap.
+```
+
+## Bulk Canvas Atlas
+
+Use after the user confirms preview style and chooses a uniform slicing grid. This is the default bulk strategy for reducing generation count.
+
+```text
+Create one GUI icon atlas on a flat #FF00FF chroma-key background.
+Style lock: match the approved preview exactly: <frozen style language>.
+Canvas grid: <columns>x<rows> total icon cells, equal cell size, consistent spacing, centered icons, 10% safe margin.
+Icons in row order, left to right then top to bottom: <names>.
+Keep related icons near each other when possible, but preserve one icon per grid cell.
+Quality rules: no text, no labels, no guide marks, no shadows, no glow, no scenery, no duplicate generic placeholders, no clipping, no overlap.
+```
+
+## Focused Pack
+
+Use when one pack is weak but the global style is approved.
+
+```text
+Create one GUI icon atlas on a flat #FF00FF chroma-key background.
+Style lock: match the approved pack family: <frozen style language>.
+Grid: <columns>x<rows>, equal cells, centered icons, generous padding.
+Icons in row order: <names>.
+Quality rules: no text, no labels, no shadows, no glow, no guides, no duplicate placeholders, no clipping, no overlap.
+```
+
+## Game HUD Pack
+
+```text
+Create a game HUD asset atlas on a flat #FF00FF chroma-key background.
+Style: <game art direction>, readable at small sizes, clean silhouettes.
+Grid: <columns>x<rows>, equal cells.
+Assets in row order: <health, mana, coin, timer, etc.>.
+Do not include numbers, text, labels, panels, background scenery, cast shadows, glow, or particle effects.
+```
+
+## Repair Language
+
+Add only the failing constraint:
+
+- For clipping: `Every icon must stay 10-12% away from cell borders; no icon touches or crosses an edge.`
+- For semantic drift: `Each icon must clearly represent its exact named concept; do not use generic circles or repeated placeholders.`
+- For style drift: `Match the approved family exactly: same outline weight, palette, shape language, and shading depth.`
+- For extraction issues: `Use a perfectly flat #FF00FF background with no antialiasing into the background color.`

package/skills/generate-gui-assets/scripts/build_gui_contact_sheet.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Build a GUI asset contact sheet from catalog raw files."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import shutil
+import subprocess
+from pathlib import Path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--run-dir", required=True)
+    parser.add_argument("--output", default="qa/contact_sheet.png")
+    parser.add_argument("--background", default="#FFF9F1")
+    args = parser.parse_args()
+
+    run_dir = Path(args.run_dir)
+    catalog = json.loads((run_dir / "catalog.json").read_text(encoding="utf-8"))
+    images = [run_dir / pack["rawFile"] for pack in catalog.get("packs", []) if (run_dir / pack["rawFile"]).exists()]
+    if not images:
+        raise SystemExit("no raw pack images found")
+
+    output = run_dir / args.output
+    output.parent.mkdir(parents=True, exist_ok=True)
+
+    magick = shutil.which("magick")
+    montage = shutil.which("montage")
+    if magick:
+        tile_cols = min(3, max(1, math.ceil(math.sqrt(len(images)))))
+        tile = f"{tile_cols}x"
+        subprocess.run(
+            [magick, "montage", *map(str, images), "-tile", tile, "-geometry", "+18+18", "-background", args.background, str(output)],
+            check=True,
+        )
+    elif montage:
+        subprocess.run(
+            [montage, *map(str, images), "-tile", "3x", "-geometry", "+18+18", "-background", args.background, str(output)],
+            check=True,
+        )
+    else:
+        raise SystemExit("ImageMagick not found: install magick or montage to build contact sheet")
+
+    print(output)
+
+
+if __name__ == "__main__":
+    main()

package/skills/generate-gui-assets/scripts/clean_chroma_edges.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""Clean leftover chroma-key fringe from transparent PNG assets.
+
+This is intentionally conservative: it only targets low-alpha pixels close to the
+configured key color, then bleeds nearby foreground RGB into fully transparent
+edge pixels so image scaling cannot sample hidden chroma color.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+
+DEFAULT_PATHS = (
+    "assets/ui/icons/v2/final",
+    "assets/mascot/v2/final",
+    "assets/mascot/v3/final",
+    "assets/illustrations/v1/final",
+)
+
+
+def smoothstep(edge0: float, edge1: float, x: np.ndarray) -> np.ndarray:
+    t = np.clip((x - edge0) / (edge1 - edge0), 0.0, 1.0)
+    return t * t * (3.0 - 2.0 * t)
+
+
+def shifted(values: np.ndarray, dy: int, dx: int) -> np.ndarray:
+    out = np.zeros_like(values)
+    src_y0 = max(0, -dy)
+    src_y1 = values.shape[0] - max(0, dy)
+    src_x0 = max(0, -dx)
+    src_x1 = values.shape[1] - max(0, dx)
+    dst_y0 = max(0, dy)
+    dst_y1 = values.shape[0] - max(0, -dy)
+    dst_x0 = max(0, dx)
+    dst_x1 = values.shape[1] - max(0, -dx)
+    out[dst_y0:dst_y1, dst_x0:dst_x1] = values[src_y0:src_y1, src_x0:src_x1]
+    return out
+
+
+def bleed_rgb(
+    rgb: np.ndarray,
+    alpha: np.ndarray,
+    chroma_mask: np.ndarray,
+    target_mask: np.ndarray,
+    iterations: int,
+) -> np.ndarray:
+    result = rgb.copy()
+    valid = (alpha > 8) & ~chroma_mask
+    seed = valid.copy()
+    remaining = target_mask.copy()
+
+    for _ in range(iterations):
+        accum = np.zeros_like(result, dtype=np.float32)
+        counts = np.zeros(alpha.shape, dtype=np.float32)
+
+        for dy in (-1, 0, 1):
+            for dx in (-1, 0, 1):
+                if dy == 0 and dx == 0:
+                    continue
+                neighbor_valid = shifted(seed, dy, dx)
+                fill = remaining & neighbor_valid
+                if not np.any(fill):
+                    continue
+                neighbor_rgb = shifted(result, dy, dx)
+                accum[fill] += neighbor_rgb[fill]
+                counts[fill] += 1.0
+
+        filled = counts > 0
+        if not np.any(filled):
+            break
+        result[filled] = np.clip(accum[filled] / counts[filled, None], 0, 255).astype(np.uint8)
+        seed[filled] = True
+        remaining[filled] = False
+
+    return result
+
+
+def expand_mask(mask: np.ndarray, iterations: int) -> np.ndarray:
+    result = mask.copy()
+    for _ in range(iterations):
+        expanded = result.copy()
+        for dy in (-1, 0, 1):
+            for dx in (-1, 0, 1):
+                if dy == 0 and dx == 0:
+                    continue
+                expanded |= shifted(result, dy, dx)
+        if np.array_equal(expanded, result):
+            break
+        result = expanded
+    return result
+
+
+def clean_array(
+    rgba: np.ndarray,
+    key: tuple[int, int, int],
+    hard_dist: float,
+    soft_dist: float,
+    max_alpha: int,
+    bleed_iterations: int,
+    edge_despill: bool,
+    edge_radius: int,
+    edge_strength: float,
+) -> tuple[np.ndarray, dict[str, int]]:
+    arr = rgba.copy()
+    rgb = arr[..., :3].astype(np.float32)
+    alpha = arr[..., 3].astype(np.float32)
+    key_rgb = np.array(key, dtype=np.float32)
+    dist = np.sqrt(np.sum((rgb - key_rgb) ** 2, axis=2))
+
+    candidate = (alpha > 0) & (alpha <= max_alpha) & (dist < soft_dist)
+    hard = candidate & (dist <= hard_dist)
+    feather = candidate & (dist > hard_dist)
+
+    matte = smoothstep(hard_dist, soft_dist, dist)
+    new_alpha = alpha.copy()
+    new_alpha[hard] = 0.0
+    new_alpha[feather] = np.minimum(new_alpha[feather], alpha[feather] * matte[feather])
+
+    old_a = np.clip(alpha / 255.0, 1.0 / 255.0, 1.0)
+    unmixed = (rgb - key_rgb * (1.0 - old_a[..., None])) / old_a[..., None]
+    spill = candidate & ~hard
+    rgb[spill] = np.clip(unmixed[spill], 0, 255)
+
+    chroma_mask = dist < soft_dist
+    rgb_uint8 = np.clip(rgb, 0, 255).astype(np.uint8)
+    alpha_uint8 = np.clip(np.rint(new_alpha), 0, 255).astype(np.uint8)
+    near_foreground = expand_mask(alpha_uint8 > 8, min(3, bleed_iterations))
+    hidden_chroma = (alpha <= 8) & chroma_mask & near_foreground
+    rgb_uint8 = bleed_rgb(rgb_uint8, alpha_uint8, chroma_mask, hidden_chroma, bleed_iterations)
+
+    arr[..., :3] = rgb_uint8
+    arr[..., 3] = alpha_uint8
+
+    edge_pixels = 0
+    if edge_despill:
+        arr, edge_pixels = despill_opaque_edge(arr, edge_radius, edge_strength, bleed_iterations)
+
+    changed = np.any(arr != rgba, axis=2)
+    stats = {
+        "changed": int(np.count_nonzero(changed)),
+        "keyed": int(np.count_nonzero(hard)),
+        "feathered": int(np.count_nonzero(feather)),
+        "edge": edge_pixels,
+    }
+    return arr, stats
+
+
+def despill_opaque_edge(
+    rgba: np.ndarray,
+    radius: int,
+    strength: float,
+    bleed_iterations: int,
+) -> tuple[np.ndarray, int]:
+    arr = rgba.copy()
+    rgb = arr[..., :3].astype(np.uint8)
+    alpha = arr[..., 3]
+    opaque = alpha > 8
+    edge = expand_mask(~opaque, radius) & opaque
+
+    r = rgb[..., 0].astype(np.int16)
+    g = rgb[..., 1].astype(np.int16)
+    b = rgb[..., 2].astype(np.int16)
+    magenta_score = (np.minimum(r, b) - g) + (b - g)
+    edge_spill = (
+        edge
+        & (r > 130)
+        & (b > 115)
+        & ((np.minimum(r, b) - g) > 22)
+        & ((b - g) > 18)
+    )
+    if not np.any(edge_spill):
+        return arr, 0
+
+    repaired_rgb = bleed_rgb(rgb, alpha, edge_spill, edge_spill, bleed_iterations)
+    matte = smoothstep(55.0, 275.0, magenta_score.astype(np.float32))
+    new_alpha = alpha.astype(np.float32)
+    new_alpha[edge_spill] *= 1.0 - np.clip(strength, 0.0, 1.0) * matte[edge_spill]
+
+    arr[..., :3] = repaired_rgb
+    arr[..., 3] = np.clip(np.rint(new_alpha), 0, 255).astype(np.uint8)
+    return arr, int(np.count_nonzero(edge_spill))
+
+
+def png_paths(paths: list[str]) -> list[Path]:
+    files: list[Path] = []
+    for item in paths:
+        path = Path(item)
+        if path.is_file() and path.suffix.lower() == ".png":
+            files.append(path)
+        elif path.is_dir():
+            files.extend(sorted(path.rglob("*.png")))
+    return sorted(set(files))
+
+
+def parse_key(value: str) -> tuple[int, int, int]:
+    raw = value.strip().lstrip("#")
+    if len(raw) != 6:
+        raise argparse.ArgumentTypeError("key must be a 6-digit hex color")
+    return tuple(int(raw[i : i + 2], 16) for i in (0, 2, 4))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("paths", nargs="*", default=list(DEFAULT_PATHS))
+    parser.add_argument("--key", type=parse_key, default=parse_key("#ff00ff"))
+    parser.add_argument("--hard-dist", type=float, default=42.0)
+    parser.add_argument("--soft-dist", type=float, default=118.0)
+    parser.add_argument("--max-alpha", type=int, default=180)
+    parser.add_argument("--bleed-iterations", type=int, default=10)
+    parser.add_argument("--edge-despill", action="store_true")
+    parser.add_argument("--edge-radius", type=int, default=3)
+    parser.add_argument("--edge-strength", type=float, default=0.75)
+    parser.add_argument("--apply", action="store_true")
+    args = parser.parse_args()
+
+    files = png_paths(args.paths)
+    totals = {"files": 0, "changed": 0, "keyed": 0, "feathered": 0}
+
+    for path in files:
+        original = np.array(Image.open(path).convert("RGBA"))
+        cleaned, stats = clean_array(
+            original,
+            args.key,
+            args.hard_dist,
+            args.soft_dist,
+            args.max_alpha,
+            args.bleed_iterations,
+            args.edge_despill,
+            args.edge_radius,
+            args.edge_strength,
+        )
+        if stats["changed"] == 0:
+            continue
+
+        totals["files"] += 1
+        totals["changed"] += stats["changed"]
+        totals["keyed"] += stats["keyed"]
+        totals["feathered"] += stats["feathered"]
+        totals["edge"] = totals.get("edge", 0) + stats["edge"]
+        action = "cleaned" if args.apply else "would clean"
+        print(
+            f"{action} {path}: changed={stats['changed']} "
+            f"keyed={stats['keyed']} feathered={stats['feathered']} edge={stats['edge']}"
+        )
+        if args.apply:
+            Image.fromarray(cleaned, "RGBA").save(path)
+
+    mode = "APPLIED" if args.apply else "DRY_RUN"
+    print(
+        f"{mode} files={totals['files']} changed={totals['changed']} "
+        f"keyed={totals['keyed']} feathered={totals['feathered']} edge={totals.get('edge', 0)}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/generate-gui-assets/scripts/copy_approved_icons.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""Copy approved extracted GUI icons as-is and write a manifest."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+from collections import defaultdict
+from pathlib import Path
+
+
+def unique_name(name: str, seen: defaultdict[str, int]) -> str:
+    seen[name] += 1
+    if seen[name] == 1:
+        return name
+    return f"{name}_{seen[name]}"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--source-dir", required=True)
+    parser.add_argument("--run-dir", required=True)
+    parser.add_argument("--mapping", required=True, help="JSON list of {source,name} entries")
+    parser.add_argument("--technique", default="copy-approved-icons-as-is")
+    args = parser.parse_args()
+
+    source_dir = Path(args.source_dir)
+    run_dir = Path(args.run_dir)
+    mapping = json.loads(Path(args.mapping).read_text(encoding="utf-8"))
+    icons_dir = run_dir / "final" / "icons"
+    icons_dir.mkdir(parents=True, exist_ok=True)
+
+    seen: defaultdict[str, int] = defaultdict(int)
+    records = []
+    for item in mapping:
+        source_name = item["source"]
+        semantic_name = unique_name(item["name"], seen)
+        source_path = source_dir / source_name
+        if not source_path.exists():
+            raise SystemExit(f"missing source icon: {source_path}")
+        destination = icons_dir / f"{semantic_name}{source_path.suffix.lower()}"
+        shutil.copy2(source_path, destination)
+        records.append(
+            {
+                "name": semantic_name,
+                "file": str(destination.relative_to(run_dir / "final")),
+                "source": str(source_path),
+            }
+        )
+
+    manifest = {
+        "runId": run_dir.name,
+        "sourceDir": str(source_dir),
+        "technique": args.technique,
+        "icons": records,
+    }
+    manifest_path = run_dir / "final" / "icons_manifest.json"
+    manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+    print(manifest_path)
+
+
+if __name__ == "__main__":
+    main()

package/skills/generate-gui-assets/scripts/prepare_gui_asset_run.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""Prepare a GUI asset generation run folder and catalog."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def parse_pack(value: str) -> dict:
+    parts = value.split(":", 2)
+    if len(parts) != 3:
+        raise argparse.ArgumentTypeError("pack must be id:grid:icon1,icon2")
+    pack_id, grid, icons_csv = parts
+    icons = [item.strip() for item in icons_csv.split(",") if item.strip()]
+    if not pack_id or "x" not in grid or not icons:
+        raise argparse.ArgumentTypeError("pack must include id, grid like 4x3, and icons")
+    return {"id": pack_id.strip(), "grid": grid.strip(), "icons": icons}
+
+
+def prompt_for_pack(pack: dict, style_notes: str, chroma_key: str, phase: str) -> str:
+    phase_line = (
+        "Mode: PREVIEW. Prioritize style and semantic fidelity for approval before bulk generation."
+        if phase == "preview"
+        else "Mode: BULK. Keep style locked to approved preview and maximize consistency across many packs."
+    )
+    return "\n".join(
+        [
+            f"Create one GUI icon atlas on a flat {chroma_key} chroma-key background.",
+            phase_line,
+            f"Style: {style_notes}.",
+            f"Grid: {pack['grid']}, equal cells, centered icons, 10% safe margin.",
+            "Icons in row order: " + ", ".join(pack["icons"]) + ".",
+            (
+                "Quality rules: no text, no labels, no shadows, no glow, no guides, "
+                "no duplicate generic placeholders, no clipping, no overlap, no scenery."
+            ),
+            "Output only the atlas image.",
+        ]
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--run-id", required=True)
+    parser.add_argument("--output-root", default="assets/ui/generated")
+    parser.add_argument("--style-notes", required=True)
+    parser.add_argument("--chroma-key", default="#FF00FF")
+    parser.add_argument("--phase", choices=["preview", "bulk"], default="preview")
+    parser.add_argument("--pack", action="append", type=parse_pack, required=True)
+    args = parser.parse_args()
+
+    run_dir = Path(args.output_root) / args.run_id
+    raw_dir = run_dir / "raw"
+    prompts_dir = run_dir / "prompts"
+    qa_dir = run_dir / "qa"
+    for directory in (raw_dir, prompts_dir, qa_dir):
+        directory.mkdir(parents=True, exist_ok=True)
+
+    packs = []
+    for pack in args.pack:
+        prompt_path = prompts_dir / f"{pack['id']}.txt"
+        prompt_path.write_text(prompt_for_pack(pack, args.style_notes, args.chroma_key, args.phase), encoding="utf-8")
+        packs.append(
+            {
+                "id": pack["id"],
+                "grid": pack["grid"],
+                "icons": pack["icons"],
+                "promptFile": str(prompt_path.relative_to(run_dir)),
+                "rawFile": str((raw_dir / f"{pack['id']}.png").relative_to(run_dir)),
+                "source": None,
+                "qa": {"state": "pending", "notes": ""},
+            }
+        )
+
+    catalog = {
+        "runId": args.run_id,
+        "createdAt": datetime.now(timezone.utc).isoformat(),
+        "phase": args.phase,
+        "styleNotes": args.style_notes,
+        "chromaKey": args.chroma_key,
+        "packs": packs,
+    }
+    (run_dir / "catalog.json").write_text(json.dumps(catalog, indent=2) + "\n", encoding="utf-8")
+    print(run_dir)
+
+
+if __name__ == "__main__":
+    main()

package/skills/generate-gui-assets/scripts/suggest_grid_options.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Suggest GUI atlas canvas options ordered from large to small."""
+
+from __future__ import annotations
+
+import argparse
+
+
+CANVAS_ORDER = [
+    ("8x6", 48),
+    ("8x5", 40),
+    ("6x6", 36),
+    ("6x5", 30),
+    ("7x4", 28),
+    ("5x5", 25),
+    ("6x4", 24),
+    ("4x4", 16),
+    ("4x3", 12),
+    ("3x3", 9),
+]
+QUALITY_ORDER = [("6x5", 30), ("5x5", 25), ("6x4", 24), ("4x4", 16), ("4x3", 12), ("3x3", 9), ("8x6", 48)]
+
+
+def quality_note(grid: str) -> str:
+    if grid == "8x6":
+        return "maximum throughput, up to 48 icons in one image; use after preview approval"
+    if grid in {"8x5", "6x6"}:
+        return "high throughput with slightly more breathing room than 8x6"
+    if grid in {"6x5", "7x4", "5x5", "6x4"}:
+        return "balanced bulk mode for cleaner semantics"
+    if grid == "4x4":
+        return "quality-priority compact bulk mode"
+    return "precision fallback for difficult icon semantics"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--icon-count", type=int, required=True)
+    parser.add_argument(
+        "--strategy",
+        choices=["throughput", "quality"],
+        default="throughput",
+        help="throughput: recommend max icon count per image; quality: recommend safer dense canvas",
+    )
+    args = parser.parse_args()
+
+    icon_count = max(1, args.icon_count)
+    print(f"icon_count={icon_count}")
+    print("canvas_options_large_to_small:")
+    for grid, capacity in CANVAS_ORDER:
+        fits = "fits" if capacity >= icon_count else "does_not_fit"
+        print(f"- {grid} capacity={capacity} {fits} note=\"{quality_note(grid)}\"")
+
+    if args.strategy == "throughput":
+        recommended = "8x6"
+    else:
+        recommended = next((grid for grid, capacity in QUALITY_ORDER if capacity >= icon_count), "5x5")
+    print(f"strategy={args.strategy}")
+    print(f"recommended_grid={recommended}")
+
+
+if __name__ == "__main__":
+    main()