genimg 0.1.0__py3-none-any.whl

genimg/__init__.py

@@ -0,0 +1,4 @@
+"""genimg — multi-provider image generation CLI."""
+from importlib.metadata import version
+
+__version__ = version("genimg")

genimg/__main__.py

@@ -0,0 +1,5 @@
+"""Enable `python -m genimg …` (used as a subprocess fallback by `genimg draw`)."""
+from .cli import app
+
+if __name__ == "__main__":
+  app()

genimg/_skills/genimg/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: genimg
+description: Generate and edit raster images with the genimg CLI (OpenAI GPT Image, Google Gemini Image, Codex subscription). Use before running any genimg command, and whenever the user wants an image made, edited or varied, such as a logo, icon, favicon, illustration, poster, photo, mockup, raster diagram, or a set of options to pick from. Skip it for charts and diagrams drawn as code (SVG, HTML, plotting libraries).
+---
+
+# genimg
+
+`genimg "PROMPT" [REF_PATHS...] [OPTIONS]` writes one PNG per image (`-o path`, else under `~/.genimg/generations/`). Read generation flags from the table below rather than `--help`. The subcommands (`auth`, `setup`, `models`, `grid`, `history`, `cost`, `config`) document themselves with `--help`, and most take `--json`.
+
+## Before the first call
+
+1. Load the `genimg-preferences` skill if it exists. Its taste overrides this skill's defaults; the current request overrides both. When the user states a lasting preference for all their images, record it as [references/preferences.md](references/preferences.md) describes.
+2. Pass `-m` on every call. genimg has no built-in model; `genimg models get-default` shows one the user saved.
+3. If a provider is not authenticated, `genimg auth --modes` names the env vars each auth mode reads. The user puts the key in the environment; never take it in chat or pass it as an argument. Then run `genimg setup` yourself: without a terminal it never prompts, saves each provider whose key validates, and exits 1 if none does. `genimg auth --check` runs a tiny live generation on the Google and OpenAI providers' fixed canary models (Codex: login only), which proves the provider, not the model you pick; adding `--json` skips that probe.
+4. Preflight any call with `-n > 1`, `-q high` or `-r 4K` with `--dry-run`: it prints model, resolved size, cost and planned paths without calling the API, and exits 1 with an `auth ✗` line when the run would fail on auth.
+
+## Choosing a model
+
+| Need | Model |
+| --- | --- |
+| Legible in-image text, glyphs, logos, UI | `oai:gi2` (gpt-image-2) |
+| Photographic or painterly quality | `gdm:nbp` (Gemini 3 Pro Image) |
+| Structured diagrams: arrows, labelled cells, fixed layout | `gdm:nb2` to explore, `gdm:nbp` for finals (see *Diagrams*) |
+| No API key, the user's ChatGPT subscription | `codex:image` |
+
+`genimg models` lists every model; `--aliases` adds the alias mappings.
+
+- **GPT Image 2.5:** `oai:gi2.5` (`gpt-image-2.5-sunburst`) and `oai:gi2.5-flare` generate and edit, and add `-q xhigh` and `-q max`. Availability depends on the endpoint, so the first real generation is what proves the model serves. On 2.5's cheaper price grid, `high` costs what gi2 `medium` does. The model comparisons in this skill were measured on gpt-image-2, not 2.5.
+- **Codex:** `codex:image` starts an ephemeral Codex agent on the user's ChatGPT login (`codex login`) and records the result in history. Generation, `-i`, references, `-n` and `-d` work. Codex picks the image model and size, so `-a` is a request and no flag selects a version: never promise GPT Image 2.5 or infer a version from a filename. A host `image_gen` tool call bypasses genimg and its history.
+
+## Flags (generation)
+
+| Flag | Short | Values | Constraints |
+| --- | --- | --- | --- |
+| `--model` | `-m` | alias or canonical id (`gdm:nb2`, `oai:gi2`, `codex:image`, `gpt-image-2`) | required unless a default is saved |
+| `--output` | `-o` | PNG path | `n>1` writes `stem_1.png … stem_n.png`; default `~/.genimg/generations/<id>.png` |
+| `--num` | `-n` | 1–10 | runs in parallel; pair with `-d`/`--deltas` for real variety |
+| `--diverse` | `-d` | flag | needs `-n >= 2`; curated deltas for #2..#n (#1 = base prompt) |
+| `--deltas` | | `"a, b, c"` or `@file` | your own deltas for #2..#n, implies `-d`; parallel mode only |
+| `--mode` | | `parallel` (default) \| `batch` | `batch` = ONE n-image request, Gemini only; rejected on OpenAI |
+| `--input` | `-i` | image path | image-to-image edit; stays close to the input |
+| `REF_PATHS` | | paths after the prompt | references for style/layout, order preserved, never edited |
+| `--aspect-ratio` | `-a` | `1:1 4:3 3:4 16:9 9:16 3:2 2:3 4:5 5:4 21:9`; `gdm:nb2`/`nb2-lite` add `1:4 1:8 4:1 8:1` | OpenAI: `16:9`/`9:16` need `-r 2K` or `4K`; `4:3`/`3:4` need `1K` or `2K`; `gi1`/`gi1-mini`/`gi1.5`: `1:1` only |
+| `--resolution` | `-r` | `512 1K 2K 4K` | `gdm:nb2`: all four; `gdm:nbp`: `1K 2K 4K`; `gdm:nb2-lite`: `1K`; OpenAI: `1K 2K 4K` per the aspect rule (`gi1`/`gi1-mini`/`gi1.5`: `1K` only); `codex:image`: none |
+| `--quality` | `-q` | `low medium high auto`; `oai:gi2.5`/`gi2.5-flare` add `xhigh max` | OpenAI only; default `medium`; `high` is 30–90 s/image |
+| `--thinking` | | `minimal` \| `high` | `gdm:nb2` and `gdm:nb2-lite` only |
+| `--profile` | | `[profiles.NAME]` from `~/.config/genimg/config.toml` | must match the model's provider; default = provider's first profile, else env detection |
+| `--auth` | | `azure` \| `direct` | OpenAI only; forces a mode for one run |
+| `--region` | | e.g. `global`, `us-central1` | Google only |
+| `--project` | | GCP project id | Google Vertex only |
+| `--name` | | one-line label | recorded in history; name any generation you may revisit |
+| `--grid` | `-g` | flag | with `-n >= 2`, also writes an HTML grid under `~/.genimg/grids/` |
+| `--open` | | flag | opens the grid (or the single image) in the browser; steals focus on macOS |
+| `--dry-run` | | flag | prints model, resolved size, cost and planned paths; no API call |
+
+`codex:image` accepts none of `-q -r --thinking --auth --region --project --mode batch`; `-a` becomes a prompt request.
+
+## Getting real variations
+
+- **Prompt for a SINGLE subject and let `-n N` make the variety.** A prompt asking to "explore variations" or "show options" packs a contact sheet into one image. Write "a SINGLE centered X, NOT a grid, not a montage". Make every set with one `-n` call, so the images share numbered outputs and one grid.
+- **Add `-d` for simple subjects** (logo, icon, single object). Plain `-n` converges on near-duplicates there. `-d` appends a curated style or composition delta to #2..#n (#1 keeps the base prompt), and the grid and metadata record each delta, so a pick is reproducible. Long, complex prompts often diversify without it.
+- **You are the tailored-diversity engine: write subject-specific `--deltas`.** genimg calls no text LLM, and the built-in `-d` pool is generic style, lighting and framing hints tuned for illustrations and logos; it transfers poorly to diagrams, photos and technical subjects. Pass `--deltas "blueprint schematic, hand-drawn whiteboard, isometric cutaway"` (inline splits on commas) or `--deltas @styles.txt` (one per line, commas allowed, `#` comments). Set `-n` to the delta count plus one: fewer deltas is an error, and extras are silently dropped.
+- **Pick the spread by intent.** `--deltas` or bare `-d` in parallel mode works on every provider and gives the most *controlled* spread: you name the axes. `-d --mode batch` on Gemini sends ONE request in which the model curates a deliberately different *set*; it may return fewer than n and takes about 30 s against 8 s. OpenAI rejects `--mode batch`: GPT Image n>1 returns near-duplicates of one prompt.
+
+## Editing versus referencing
+
+- **`-i FILE` edits that image and stays close to it.** Once a candidate is close, iterate with `-i` and a small instruction ("same icon, thicker strokes") rather than regenerating.
+- **A reference after the prompt guides style, not composition.** Use it for related but freely varied results: `genimg "new layout, same palette" ref.png -m gdm:nbp`.
+- **Style-lock a family of assets:** generate one hero asset, then pass it as a reference to every sibling. Check each reference path exists first; a missing reference fails the generation, and in a background job the error scrolls away.
+
+## Showing candidates to a human
+
+1. Generate to real `-o` paths. The output stem plus index (`gemini_3`, `gpt_1`) is each candidate's stable ID; never rename or renumber one someone has seen, and give a later round a new stem. Keep `selection-manifest.md` with run, model, delta, original index, filename and status (liked, rejected).
+2. Put every candidate in one grid and open it before asking anything: `-g --open` for one run, `genimg grid a.png b.png … -o cmp.html --open` across runs or providers. A generation grid lands under `~/.genimg/grids/`; use the path the CLI prints. To open without stealing focus on macOS, drop `--open` and run `open -g <grid.html>`. An arbitrary-file grid shows filenames rather than per-run metadata, so the manifest stays the source of truth.
+3. Hand the grid back as a `file://` link: `[grid.html](file:///abs/path/grid.html)`.
+4. For 3 to 20 strong candidates, point the user at the grid's **Tournament** button (pairwise picks, n−1 for a winner, one more for a top 3 unless there are exactly three) and ask them to paste back **Copy result (JSON)**: winner, ranking and every pick, by grid number, filename, and model when a sidecar knows it.
+
+The step is done when the user has chosen from images on screen. For a broad spread of serious options (a brief, three to six directions, several providers, recombining the winners), load `genimg-visual-exploration` if it is installed. Without it, run a Gemini spread of four to six (`-n 5 -d` or tailored `--deltas`), add one to three `oai:gi2` variants with explicit deltas when typography or UI matters, and compare all of them in one grid. If a provider or model changes after a failure, say so before presenting results.
+
+Make assets light unless the user asks for dark mode or paired themes; derive a requested dark variant from the chosen finalist.
+
+## Product screenshots and publication copy
+
+- For product updates, use an authentic screenshot or logo as the evidence layer and let generation add diagrams, illustration or framing around it. Pass screenshots as references for loose integration; composite deterministically when pixels must stay exact.
+- User-supplied copy is authoritative. Do a full-resolution defect pass for invented dates, misspellings, leaked instructions, wrong commands and garbled labels. If publication-critical text is unreliable in the raster, add it after generation.
+- Verify commands and factual labels against current project or package metadata before delivery.
+
+## Multi-view edits without drift
+
+- Start every view from source: use each original camera angle as `-i` and pass the same approved image as the locked appearance reference after the prompt.
+- Change one decision per call so any drift has one attributable cause.
+- Never feed a generated angle into the next angle. If a view visibly drifts, reset to the originals and the approved reference rather than editing the drifted result again.
+- Keep failed variants as human reject examples, not model inputs.
+
+genimg is the controlled front end for this workflow; it is not a separate image model. Record the provider and model actually used, such as GPT Image 2, with every result.
+
+## Diagrams
+
+Flowcharts, layered diagrams and anything with **arrows, a fixed grid of labelled cells, or a required spatial layout** behave differently from illustrations:
+
+- **Model choice flips to Gemini.** `gdm:nbp` and `gdm:nb2` follow spatial instructions (trajectories, start markers, adjacency, "don't skip a layer") far better; gpt-image-2 renders crisper text but reverts to generic per-cell arrows. At 1K `gdm:nb2` costs half of `gdm:nbp` (less of a saving at 2K and 4K; `--dry-run` prices each) and often matches it on layout, so explore with it. Use `oai:gi2` only when text crispness dominates and the layout is simple.
+- **Fix structure with a fresh prompt, cosmetics with `-i`.** `-i` handles small text and colour tweaks but ignores or mangles structural edits (reroute an arrow, move a cell) and piles up mess over rounds. When the structure is wrong, regenerate from a fully specified prompt. Keep `-i` for the last one or two cosmetic fixes and pass `-a` on them: an unflagged gpt-image-2 `-i` can default to 1024×1024 and squash the source.
+- **Pin every element.** Give an exact row-to-cell mapping ("Environment row: 'morning cue'; Behaviour row: 'brew' …") and state spatial rules as absolutes: "the path steps between ADJACENT rows only"; "one START dot per column"; "solid line = bottom-up, dotted = top-down".
+- **Phrase constraints so they cannot read as content.** Instructions leak into renders as labels (a "No empty boxes." instruction once printed in the legend), so scan every label for leaked phrases.
+- **Zoom for the defect pass.** Thumbnails hide skipped cells, duplicate icons and garbled labels. Crop each region and read it: `magick in.png -crop WxH+X+Y +repage region.png`.
+- **Quality sharpens rendering, not structure.** `-q high` leaves a wrong arrow layout wrong; `-q medium` is usually enough for `-i` edits.
+
+## Recipes
+
+```bash
+# Explore options for a human to pick (4 takes + grid + open).
+genimg "a SINGLE centered editorial illustration of a sprint board, flat vector, off-white bg, NOT a grid" -m gdm:nb2 -n 4 -g --open -a 16:9
+
+# Cross-provider portfolio, then one native comparison grid.
+genimg "a SINGLE light-mode editorial product-update poster, NOT a grid" app-light.png -m gdm:nb2 -n 5 -d -a 16:9 -o gemini.png
+genimg "a SINGLE crisp light-mode editorial product-update poster, NOT a grid" app-light.png -m oai:gi2 -n 2 --deltas "screen-led split layout" -a 16:9 -r 2K -q high -o gpt.png
+genimg grid gemini_*.png gpt_*.png -o finalists.html --open
+
+# Simple subject → engineer the spread with -d (per-generation prompt deltas, shown in the grid).
+genimg "a SINGLE minimal fox logo, NOT a grid" -m oai:gi2 -n 4 -d -g --open
+
+# Let the MODEL diversify instead: one Gemini request, model differentiates its own 4 takes.
+genimg "a SINGLE minimal fox logo, NOT a grid" -n 4 -d --mode batch -m gdm:nb2 -g --open
+
+# A logo or app icon: one mark, flat, exact colours, square.
+genimg "A SINGLE minimal flat-vector app icon, one mark centered, NOT a grid/montage: <subject>. Black line-art + one emerald-green accent on warm off-white. NO gradient, NO 3D, NO text." -m oai:gi2 -n 4 -g --open -a 1:1 -q high -o logo.png
+
+# Favicon from a chosen logo (downscale; browsers render one PNG fine).
+sips -z 128 128 logo_2.png --out public/favicon.png   # then <link rel="icon" href="/favicon.png">
+
+# Edit/iterate on a chosen result (stays close to it).
+genimg "same icon, slightly thicker strokes, larger marks" -m oai:gi2 -i logo_2.png -o logo-v2.png
+
+# Match an existing style with a new layout (reference, not edit).
+genimg "same palette and line weight, new composition" ref1.png ref2.png -m gdm:nbp -o styled.png
+
+# Pick a model explicitly.
+genimg "warm cinematic photo of a mountain cabin at night" -m gdm:nbp -o cabin.png
+```
+
+## Further reference
+
+- Before reporting spend, billing, provenance or speed, read [references/cost-and-provenance.md](references/cost-and-provenance.md).
+- Before cropping, matting out a background, slicing a sprite sheet, or embedding images in an HTML page of your own, read [references/post-processing.md](references/post-processing.md).
+- `genimg history` lists recent generations (`--json` gives absolute paths); `genimg history view` is a TUI for the user to browse every image.

genimg/_skills/genimg/references/cost-and-provenance.md

@@ -0,0 +1,15 @@
+# Cost, provenance and timing
+
+## Cost
+
+- `--dry-run` prints the estimate for a planned call; `genimg cost` totals estimated spend, and `genimg history` shows it per generation.
+- Estimates count output tokens only. At 1024×1024: `oai:gi2` medium $0.053, high $0.211; `oai:gi2.5` medium $0.013, high $0.053, max $0.211. A wide 2K render can cost less than a 1K square: `oai:gi2` medium at 2048×1152 is $0.042.
+
+## Billing and provenance
+
+- Each generation records `billing` (`subscription` or `api`) from its route. `api_equivalent_cost` is a separate, theoretical comparison, and a rough range when the native quality is unknown: report it as a comparison, never as a charge, and keep it out of subscription spend. Unknown models and prices stay unknown.
+- genimg captures each image's C2PA claim (extracted offline, not signature-verified), generator, dimensions and hash. PNGs that carry credentials keep their bytes unchanged; genimg's own fields go in sidecar files.
+
+## Timing
+
+One-shot CLI wall time includes local setup and cold start, so it is not provider latency. Record setup time and provider-call time separately, and state which clock each comparison uses.

genimg/_skills/genimg/references/post-processing.md

@@ -0,0 +1,6 @@
+# Post-processing generated images
+
+- **Crop with Pillow by scanning rows** for the first and last dark pixels (`r/g/b < ~210`), plus a margin. `getbbox()` fails on anti-aliased near-white edges.
+- **Solidify after background-key matting.** Keying out a background by colour distance turns pale subject pixels semi-transparent and leaves interior holes that hide at thumbnail size. Flood-fill transparency from the border to find the truly external pixels, fill interior holes with the nearest opaque colour, and snap body alpha ≥ ~90 to 255. Verify at 2× zoom on the flagged region and by counting alpha pixels before and after.
+- **Slice a sprite sheet by alpha column runs, not a fixed grid.** Columns whose alpha never passes the threshold separate irregular sprites (ignore runs under ~30 px). The same per-column coverage profile measures composition flaws before you crop.
+- **Embed images as base64 in HTML for the Claude Code preview panel.** The panel sandboxes the page, so a relative `<img src="sibling.png">` renders blank there; inline `data:image/png;base64,…` instead. A normal browser tab loads relative paths fine. For comparing candidates, `genimg grid` already builds the page.

genimg/_skills/genimg/references/preferences.md

@@ -0,0 +1,19 @@
+# Recording the user's image preferences
+
+The first time the user states a lasting preference for all their images (a style, a palette, "always sober"), create a `genimg-preferences` skill and record the preference in the user's words. Add later preferences to the same file; when one replaces or retracts an entry, edit or delete that entry so the file never contradicts itself. Create it only once the user has stated a preference; a guess about their taste stays out of it. A preference for one project or brand belongs in that project's own agent instructions.
+
+Put it where the agent loads user-level skills, next to the installed `genimg` skill, even when genimg is installed in a project, so the preferences follow the user:
+
+- Claude Code: `~/.claude/skills/genimg-preferences/SKILL.md`
+- Agents that read `~/.agents/skills/`: `~/.agents/skills/genimg-preferences/SKILL.md`
+
+Start the file with:
+
+```markdown
+---
+name: genimg-preferences
+description: "The user's lasting preferences for generated images. Load with genimg before every generation or edit."
+---
+```
+
+The skill belongs to the user. genimg never ships it, so updating genimg never overwrites it.

genimg/_skills/genimg-infographic/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jim Liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

genimg/_skills/genimg-infographic/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: genimg-infographic
+description: "Turn a text, file, URL or topic into one publication-ready raster infographic with GenIMG. Use when the user asks for an infographic, visual summary, high-density visual guide, 信息图 or 可视化. Skip it for charts whose numbers must plot exactly (draw those in code)."
+---
+
+# GenIMG Infographic
+
+Adapted from Jim Liu's `baoyu-infographic` v1.117.4 under the MIT licence. Preserve its layout/style methodology and attribution; use `genimg` for every render.
+
+Load the `genimg` skill before invoking the CLI.
+
+## Rules
+
+- Preserve source statistics, quotes, names, dates and technical terms exactly, and add no new facts.
+- Strip credentials, tokens and secrets from source material before writing output files.
+- Render with GenIMG. The deliverable is a raster image; SVG, HTML, canvas or CSS art is a different deliverable that needs the user's say-so.
+- Correct wrong rendered text by fixing the prompt and regenerating; never paint over the bitmap.
+- Save the full final prompt under `prompts/` before generating.
+
+## Output structure
+
+```text
+infographic/<topic-slug>/
+├── source.<ext>
+├── analysis.md
+├── structured-content.md
+├── refs/                      # only when references were supplied
+│   └── 01-ref-<slug>.<ext>
+├── prompts/
+│   └── infographic.md
+├── candidates/                 # only for multi-candidate work
+├── iterations/                 # only when regenerating a single candidate
+├── infographic.png
+├── selection-manifest.md       # whenever more than one render or iteration exists
+└── comparison.html             # only for multi-candidate work
+```
+
+Use a 2-4 word kebab-case slug. If the directory exists, append `-YYYYMMDD-HHMMSS` rather than overwrite prior work.
+
+## Workflow
+
+### 1. Load preferences
+
+Read the first `EXTEND.md` found:
+
+1. `.genimg/infographic/EXTEND.md`
+2. `${XDG_CONFIG_HOME:-$HOME/.config}/genimg/infographic/EXTEND.md`
+3. `$HOME/.genimg/infographic/EXTEND.md`
+
+If none exists, use the automatic defaults in `references/config/first-time-setup.md` and continue without creating a file or asking setup questions. When the user asks to change preferences, edit or remove the first matching file; the fields are in `references/config/preferences-schema.md`.
+
+### 2. Analyse the source
+
+Load `references/analysis-framework.md`.
+
+1. Save the supplied text, file, URL content or topic material as `source.<ext>`.
+2. If the user supplied reference images, preserve and classify them as `references/reference-images.md` describes.
+3. Identify the topic, data type, complexity, tone, audience, language, learning objectives and visual opportunities.
+4. Extract critical facts verbatim.
+5. Save `analysis.md`.
+
+### 3. Structure the content
+
+Load `references/structured-content-template.md` and write `structured-content.md` containing:
+
+- Title and 1-3 learning objectives.
+- Sections with a key concept, verbatim content, visual element and exact labels.
+- A consolidated list of statistics, quotes and key terms.
+- User-provided design instructions.
+
+### 4. Select automatically
+
+Select one coherent configuration without a question panel, in this priority order:
+
+1. Explicit constraints in the current request.
+2. A compatible saved preference.
+3. A matching keyword shortcut (table below).
+4. Source structure, tone, audience, language and visual density, using the content-type pairings in `references/analysis-framework.md`.
+
+Choose:
+
+- the layout and style from the galleries below (without other signals, `bento-grid` + `craft-handmade`);
+- the aspect: `landscape` (`16:9`), `portrait` (`9:16`), `square` (`1:1`) or another ratio the model supports;
+- the output language;
+- the resolution (`2K` unless the model or output needs another);
+- the model, through *Model selection* below;
+- one final image, unless the user asked for alternatives.
+
+State the selected configuration in a concise progress update, then continue immediately. Do not present a menu or ask for confirmation unless the user explicitly asks to compare or choose among alternatives. If constraints conflict, preserve source fidelity and legibility, record the trade-off, and proceed with the strongest fit.
+
+### 5. Build the prompt
+
+Load:
+
+- `references/base-prompt.md`
+- `references/layouts/<layout>.md`
+- `references/styles/<style>.md` for a built-in style, or the configured `prompt_fragment` for a custom style
+- `structured-content.md`
+
+Assemble one complete prompt at `prompts/infographic.md`, with reference provenance in its frontmatter and any extracted style or palette traits appended. Pin every required cell, row, arrow, label and metric explicitly. Phrase constraints so they cannot be mistaken for visible labels.
+
+`genimg` treats its whole first argument as prompt text, so the frontmatter would leak into the render as pseudo-labels, and a leading `---` can parse as a flag. Strip it into a variable and pass that to the preflight and every generate call:
+
+```bash
+PROMPT=$(awk 'NR==1 && /^---$/{skip=1; next} skip && /^---$/{skip=0; next} !skip' prompts/infographic.md)
+```
+
+### 6. Preflight
+
+Run the exact planned command with `--dry-run`, passing only `direct` reference images positionally after the prompt:
+
+```bash
+genimg "$PROMPT" [refs...] \
+  -m <model> -a <ratio> -r <resolution> \
+  -o infographic.png --dry-run
+```
+
+Check the model, parameters, output path and estimated cost, and resolve any mismatch. Before a material batch, report the estimated cost (as information, not a request for permission), then render and inspect one candidate at the lowest resolution the exact model and aspect support (OpenAI `16:9` and `9:16` need at least `2K`). A dry-run checks only the local plan and calls no API; `genimg auth --check` proves each Google and OpenAI provider on its fixed canary model and checks only the login for Codex. That first real render is what proves the selected model serves.
+
+### 7. Generate
+
+For one image:
+
+```bash
+mkdir -p iterations
+genimg "$PROMPT" [refs...] \
+  -m <model> -a <ratio> -r <resolution> \
+  -o iterations/01-initial.png
+```
+
+For alternatives, keep one subject and one information architecture. Write `prompts/style-deltas.txt` with exactly `<count> - 1` subject-specific lines (candidate 1 keeps the base prompt; candidates 2 to `<count>` get the deltas in order), then make one `-n` call:
+
+```bash
+mkdir -p candidates
+genimg "$PROMPT" [refs...] \
+  -m <model> -a <ratio> -r <resolution> \
+  -n <count> --deltas @prompts/style-deltas.txt \
+  -o candidates/infographic.png
+```
+
+Record each candidate's stable ID (`infographic_2`), model, original index, filename and review state in `selection-manifest.md`.
+
+### 8. Inspect and iterate
+
+Open every candidate at full resolution. For dense diagrams, crop and inspect each title, panel, legend, footer and connection path. Check:
+
+- Exact text and numbers.
+- Required cells and labels are present once.
+- Arrows and spatial relationships follow the prompt.
+- No instruction text leaked into the artwork.
+- Nothing important is cropped or illegible.
+
+If the structure is wrong, regenerate from a corrected full prompt to a new versioned path such as `iterations/02-corrected-arrows.png`. Use `-i` only for a small cosmetic edit to a selected image, passing the aspect again and writing a new versioned file. Every attempt gets a fresh path and a row in `selection-manifest.md`; flawed candidates stay for comparison. After acceptance, copy the selected file unchanged to `infographic.png`.
+
+For multiple candidates, build the grid and open it for the user before asking them to choose:
+
+```bash
+genimg grid <candidate-files...> -o comparison.html --open
+```
+
+Done when `infographic.png` passes every check above, or the user has picked it from the grid.
+
+### 9. Report
+
+Report the topic, layout, style, aspect, language, model, resolution, estimated or recorded cost, output paths and any remaining defects. Name the recommended candidate when there is one.
+
+## Model selection
+
+1. Honour a model explicitly named in the current request.
+2. Use `preferred_model` from `EXTEND.md` when it currently works; otherwise fall through, and state the substitution.
+3. Otherwise run `genimg auth --check` (without `--json`, which skips the live probe) and read `genimg models --json`, then choose:
+   - `gdm:nb2` for multi-cell diagrams, arrows, fixed spatial layouts and broad exploration.
+   - `gdm:nbp` for painterly or highly illustrative infographics where structure still matters.
+   - `oai:gi2` for simple layouts where exact typography and crisp UI treatment dominate.
+4. If no suitable configured model serves, stop and explain the available setup path.
+
+Always pass `-m`.
+
+## Keyword shortcuts
+
+A match makes the mapped layout the leading selection, promotes its listed styles, and supplies the default aspect, unless explicit constraints, a compatible saved preference or the source structure require another choice.
+
+| User keyword | Layout | Recommended styles | Default aspect | Prompt notes |
+| --- | --- | --- | --- | --- |
+| `高密度信息大图` / `high-density-info` | `dense-modules` | `morandi-journal`, `pop-laboratory`, `retro-pop-grid`, `retro-popup-pop` | portrait | — |
+| `信息图` / `infographic` | `bento-grid` | `craft-handmade` | landscape | Clean canvas, ample whitespace, no complex background textures; simple cartoon elements and icons only. |
+
+## Layout gallery
+
+| Layout | Best for |
+| --- | --- |
+| `linear-progression` | Timelines, processes, tutorials |
+| `binary-comparison` | A vs B, before/after, pros/cons |
+| `comparison-matrix` | Multi-factor comparisons |
+| `hierarchical-layers` | Pyramids, priority levels |
+| `tree-branching` | Categories, taxonomies |
+| `hub-spoke` | Central concept with related items |
+| `structural-breakdown` | Exploded views, cross-sections |
+| `bento-grid` | Multiple topics and overviews |
+| `iceberg` | Surface vs hidden aspects |
+| `bridge` | Problem to solution |
+| `funnel` | Conversion and filtering |
+| `isometric-map` | Spatial relationships |
+| `dashboard` | Metrics and KPIs |
+| `periodic-table` | Categorised collections |
+| `comic-strip` | Narratives and sequences |
+| `story-mountain` | Plot structure and tension arcs |
+| `jigsaw` | Interconnected parts |
+| `venn-diagram` | Overlapping concepts |
+| `winding-roadmap` | Journeys and milestones |
+| `circular-flow` | Cycles and recurring processes |
+| `dense-modules` | High-density, data-rich guides |
+
+## Style gallery
+
+| Style | Description |
+| --- | --- |
+| `craft-handmade` | Hand-drawn paper craft |
+| `claymation` | 3D clay figures and stop-motion |
+| `kawaii` | Japanese cute and pastels |
+| `storybook-watercolor` | Soft painted and whimsical |
+| `chalkboard` | Chalk on black board |
+| `cyberpunk-neon` | Neon and futuristic |
+| `bold-graphic` | Comic style and halftone |
+| `aged-academia` | Vintage science and sepia |
+| `corporate-memphis` | Flat vector and vibrant |
+| `technical-schematic` | Blueprint and engineering |
+| `origami` | Folded paper and geometry |
+| `pixel-art` | Retro 8-bit |
+| `ui-wireframe` | Grayscale interface mockup |
+| `subway-map` | Transit diagram |
+| `ikea-manual` | Minimal line art |
+| `knolling` | Organised flat-lay |
+| `lego-brick` | Toy brick construction |
+| `pop-laboratory` | Blueprint grid and lab precision |
+| `morandi-journal` | Warm muted doodle journal |
+| `retro-pop-grid` | 1970s pop art and Swiss grid |
+| `hand-drawn-edu` | Pastel educational drawing |
+| `retro-popup-pop` | Vintage UI collage and flat pop colour |
+
+A configured custom style uses its `prompt_fragment` directly, with no style file.

genimg/_skills/genimg-infographic/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GenIMG Infographic"
+  short_description: "Create structured infographics with GenIMG"
+  default_prompt: "Use $genimg-infographic to turn this material into a polished infographic."