/nib

name: nib
description: >-
  Turns an idea or an article into original white-background, hand-drawn
  editorial illustrations starring a recurring avatar the user owns — one
  caught scene per idea, in one of several print looks. Use when the user asks
  to illustrate a post/article/concept with a consistent character, or invokes
  "nib". Not for generic draw/make-an-image requests.
version: 0.1.2
argument-hint: "[idea or article path/URL] | build a character | set avatar <image> | style <name> | explainer"
license: MIT
metadata:
  category: creative
  requires:
    bins: [python3]

Nib

Make original editorial illustrations for written content. **One image explains one idea.** A **recurring avatar** — supplied once by the user — is the subject of every scene and *performs* the idea (pushes, sorts, steers, builds, holds); it is never decoration. The methodology is the constant; the **avatar** and the **look** are the parameters.

This is a configurable house style, not a generic image generator. It is intentionally not a photo, not a logo, not a corporate infographic, not a UI mockup.

Setup (once)

1. **A character.** The user's own **avatar image** (a mascot, logo character, anything — save its path); a bundled one via `--avatar-pack <name>` (see `characters/`); or **build a new one** with the user (`references/character-builder.md`). The character is the reference on every generation. 2. **A backend** — one of:

• **Codex (free)** — a logged-in Codex CLI (`codex login`). Generates on the

user's ChatGPT / Codex subscription, no API key. *Default when no key is set.*

• **OpenRouter** — an `OPENROUTER_API_KEY` (`sk-or-…`). Exact 16:9, and lets

you pick the model with `--model`.

Workflow

1. **Read the input.**

• A **URL** → fetch the page and extract the readable article text first

(use your web-fetch / Defuddle capability), then treat it as an article.

• A single **idea** → one illustration.
• An **article / post** (or the user's **own draft / notes** they want

illustrated) → pick the **load-bearing moments** (a judgment, a flow, a before/after, a trap, a loop), 4–8 of them. Not one image per paragraph — the ones that matter. Treat this set as a **starting point the user shapes**: show it first, let them drop moments they don't want, **add their own**, or ask for **more candidates**, then illustrate only the chosen ones. (The desktop app's Article mode exposes the same controls — per-shot select, add-a-shot, "More ideas", and a parallel "Generate".) 2. **Pick a look** for the piece — one of **13** (see `references/styles.md`): marker, riso, blueprint, woodcut, pixel, clay, gouache, chalk, diorama, enamel, felt, manila, phosphor. One look per piece. 3. For each idea, **invent a fresh, concrete physical metaphor** in which the avatar performs the idea (see `references/methodology.md`). One **caught scene** is the default; switch to the **explainer** register — a hand-drawn sketch-diagram — only when the user asks ("diagram the flow") or the idea is itself a traceable structure (`references/composition.md`, `--register explainer`). 4. **Generate** by calling the engine once per image:

   python3 scripts/generate.py \
     --idea "trust is built one piece of evidence at a time" \
     --style marker \
     --avatar /path/to/avatar.png \
     --out ./out/trust.png

It builds the full prompt (methodology + look + idea), sends the character as the reference for consistency, and writes a 16:9 PNG. Useful flags:

• `--backend auto|openrouter|codex` — `auto` uses the OpenRouter key if set,

else the free Codex lane.

• `--model <id>` — OpenRouter image model (default `google/gemini-3.1-flash-image-preview`).
• `--avatar-pack <name>` — use a bundled character (see `characters/`) instead

of `--avatar`.

• `--avatar-spec "<text>"` — a written description of the character (silhouette,

face, the one accent part) that locks its design. Combine with the image — it markedly improves consistency.

• `--accent "<hex|name>"` — pin the one accent colour (a brand hex / site

colour); see `references/palettes.md`.

• `--register explainer` — draw a hand-built sketch-diagram instead of a single

caught scene (`references/composition.md`).

• `--transparent` — cut the white ground out of the render → transparent PNG

(for slides, stickers, dark UI). Needs `rembg` (`pip install 'rembg[cpu]'`, not bundled); without it the opaque render is kept and a hint is printed. Also available standalone on any image: `python3 scripts/cutout.py <image.png>`.

• `--doctor` — print backend readiness (which lane will run, and why) and exit.

5. **Review** against `references/quality-bar.md` (white background, one idea, avatar performing the action, short labels only, not a slide). Regenerate any that miss. 6. Report each saved path.

Example prompts

Invoke Nib from your agent like:

• `Use nib to illustrate: "one fish, many dishes"`
• `Use nib to make illustrations for this article: https://jamesclear.com/feedback-loops`
• `Use nib to build a character with me, then illustrate "the information well"`
• `Use nib to diagram the flow of a RAG pipeline (explainer)`
• `Use nib to turn this post into a 5-image set in chalk: <paste a URL or text>`

Notes

• Keep text in the image short; the model can misspell long labels.
• The avatar is the reference on every call — that is what keeps the character

consistent across a whole article.

• For options, generate 2–3 variants of a shot (run the engine a few times with

the same idea) and let the user pick.

• Cost: **free** on the Codex lane (uses the user's ChatGPT / Codex subscription),

or a few cents per image on OpenRouter (`google/gemini-3.1-flash-image-preview`) — a full post is well under a dollar either way. Run `--doctor` to see which lane is ready.

• A written **`--avatar-spe