illo

# Illo

Make original, distinctive editorial illustrations for written content. One
image explains one idea: a key judgment, a flow, a before/after, a trap, a
loop. A **recurring mascot** is the one performing the idea in every scene —
the subject, never decoration. When one idea advances through stages, it can
be a **mini-comic**: 2–4 panels inside a single image. And when the idea is
itself a traceable structure — a pipeline, a fan-out, a timeline, a loop —
it can be an **explainer**: the same mascot and look drawing the structure
as a hand-built sketch-diagram with arrows and callouts
(`references/composition.md`, "Two registers"; editorial scene is always
the default).

This is a configurable house style, not a generic image generator. The
**methodology is the constant**; the **character pack and palette are the
parameters** — and a character pack carries its **style** with it: one look
per pack, chosen from the bundled look library (riso — grainy halftone,
ink-layer offset, paper grain, one bold softly-rounded outline — plus
blueprint, woodcut, pixel, clay, manila, chalk, phosphor, enamel,
gouache, and felt) or a custom style file. The default mascot is
**Blot**, a deadpan ink-drop in riso. Palettes come
from presets, the user's own palette file, or one derived color. Whatever the
parameters, it is intentionally not a photo, not a logo, not a corporate
infographic, not a formal flowchart, not a UI mockup.

## Use cases — route the request

| The user wants | The path |
|---|---|
| **Illustrate an article / post / newsletter / URL** | Steps 0–7: route the source first (thesis → coverage: hero / hero+set / set / mini-comic — `references/composition.md`, "Source routing"), then shot list (hero row + anchors), one image per anchor, interleave by placement. |
| **One image for a single concept** | Step 1 concept branch (up to ~3 quick questions if the idea is thin), then a single image. |
| **A sequence — process, before→after, fail→fix** | One **mini-comic** when the progression sits in one place (shape routing in `references/composition.md` — the idea picks the shape, the destination never does). |
| **A traceable structure** — "show the flow", "diagram the pipeline", "map the steps", "as an explainer" | The **explainer register** (`references/composition.md`, "The explainer register"): a hand-built flow / fan-out / timeline / loop / stack / system slice in the active look, the mascot a working part of it. Also reachable without the phrases when a unit's thesis IS the structure (the register gate). |
| **Social-ready art** | 16:9 (or 1:1), bold `ink-punch`, watermark with the `x` handle if configured or asked. |
| **Blog / brand / site-matched art** | A named or custom palette, or derive the palette from one dominant color (`references/palettes.md`). |
| **Their own mascot** — "make me a character", "use our mascot", "replace Blot" | The character builder: read `references/character-builder.md` in full and follow it end to end. |
| **Community characters** — "what characters are available", "install blip", "update mole", "publish my character" | `references/pack-sharing.md` — engine `packs list/show/install/update`, publish via a GitHub PR. |
| **A different look** — "in blueprint", "woodcut style", "pixel version of blip" | Styles travel with character packs: build a **style variant pack** via `references/character-builder.md`, "Style variants". |
| **Options to pick from, or "which model is best"** | Step 5b: `--count` variations or a model loop → `gallery` with a recommendation. |
| **Fix an existing image** (stray title, recolor, mascot too decorative) | Edit prompts in `references/prompt-recipe.md`, passing the image back as `--ref`. |

## Prerequisites

The engine (`scripts/illo.py`, stdlib Python, no installs) renders through one
of **two backends**; `python3` and network access are the only hard
requirements.

- **Codex backend (free for Codex subscribers).** When the host has a usable
  **Codex CLI** — installed, `codex login`-ed, with the `image_generation`
  feature — illo can generate through the user's Codex subscription at no
  per-image charge (it draws on their Codex quota). No API key, no token: illo
  only shells out to the user's own CLI. Detected, not assumed; gpt-image-2 is
  automatic; unsupported on Windows/WSL.
- **OpenRouter backend (the universal fallback).** Needs an **OpenRouter API
  key** in the user's config file — the **single credential channel** —
  written once by the user-run `init` (mode 600). The engine never reads
  secrets from the environment and never accepts them as command-line
  arguments. This is the path on any host without Codex, and the fallback when
  Codex fails. It is **model-selectable** (`--model`).

Capsule of the backend model (resolution, the Codex-CLI requirement,
gpt-image-2 automatic, quota vs. charge, Windows/WSL, fallback): **read
`references/backends.md` in full before choosing or explaining a backend** —
the mechanics live there, once.

### Setup is the user's job (never enter the key yourself)

Entering an API key is something the **user** does. Do not type, paste, print,
or store the user's key — direct them to bootstrap it:

- **Bootstrap (user runs it):** `python3 "$SKILL_DIR/scripts/illo.py" init` —
  prompts for the key at a hidden prompt (never echoed) and writes the
  YAML config `${XDG_CONFIG_HOME:-~/.config}/illo/config.yaml` (mode 600). It
  can also store non-secret defaults: `--model`, `--palette`, `--aspect`,
  `--character`, `--watermark`. Use `--no-key` to update preferences without
  touching the stored key. (The config is read via PyYAML when installed;
  without it a minimal built-in parser still reads the flat keys — `apiKey`,
  `model`, … — so generation needs no installs. Only nested settings like
  `watermark` need PyYAML: `python -m pip install 'PyYAML==6.0.2'`.)
- **Non-secret prefs may be seeded** for the user with the same command and
  `--no-key`, but the key itself is theirs to enter.

### Her