comicforge 0.2.0__tar.gz → 0.2.1__tar.gz

{comicforge-0.2.0 → comicforge-0.2.1}/.claude/skills/comicforge/SKILL.md

@@ -17,7 +17,8 @@ description: >
 You write a **comic page as a YAML spec**; the engine renders it to SVG/PNG/PDF.
 This file is the authoring contract. For deeper explanations (path resolution,
 how to add characters/scenes, pixel-art format, Python API, full CLI reference)
-see [`reference.md`](reference.md) in this skill directory.
+see [`reference.md`](reference.md) in this skill directory, or the documentation
+site at <https://mojzis.github.io/comicforge/>.
 
 ## Loop
 

{comicforge-0.2.0 → comicforge-0.2.1}/.claude/skills/comicforge/reference.md

@@ -4,6 +4,9 @@ This guide covers everything you need to author comics with ComicForge — for b
 humans and LLMs. The [SKILL.md](SKILL.md) file is the quick-reference contract;
 this document goes deeper on structure, paths, and how all the pieces fit together.
 
+The same material, with rendered examples beside every spec, is published at
+<https://mojzis.github.io/comicforge/>.
+
 ---
 
 ## Engine + self-contained projects

comicforge-0.2.1/.github/workflows/docs.yml

@@ -0,0 +1,69 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "examples/**"     # the gallery renders from the demo project
+      - "comicforge/**"   # …through the engine, so a renderer change matters
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "examples/**"
+      - "comicforge/**"
+  workflow_dispatch:
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      # Every image on the site is rendered at build time by
+      # docs/hooks/render_demos.py, so the docs build needs cairo just like a
+      # normal render does.
+      - name: Install cairo
+        run: sudo apt-get update && sudo apt-get install -y libcairo2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - name: Sync docs dependencies
+        run: uv sync --group docs
+
+      # --strict fails the build on a broken cross-reference, a dead anchor, a
+      # missing snippet, or a demo spec that no longer renders.
+      - name: Build site
+        run: uv run mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site/
+
+  deploy:
+    # Pull requests get the build as a check; only main publishes.
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

{comicforge-0.2.0 → comicforge-0.2.1}/.gitignore

@@ -34,3 +34,12 @@ review.html
 
 # Source archive (redundant after flattening)
 *.zip
+
+# Docs site: `mkdocs build` output, and the demo renders the build hook draws
+# (every image on the site is regenerated from a spec — never checked in).
+site/
+docs/assets/renders/
+
+# …except the one raster the `image:` demo needs as *input*, which `*.png` above
+# would otherwise swallow.
+!docs/demos/raster-art/*.png

{comicforge-0.2.0 → comicforge-0.2.1}/CLAUDE.md

@@ -21,6 +21,7 @@ comicforge/              The engine — pure code, no bundled art.
 examples/pes/            A self-contained demo project (characters, scenes, pixel, pages).
                          Develop against the engine the same way a downstream project would.
 skills/comicforge/       The portable authoring skill (SKILL.md + reference.md).
+docs/                    The documentation site (MkDocs Material) — see below.
 tests/                   pytest suite.
 ```
 
@@ -82,6 +83,29 @@ cmf scene  examples/pes/pages/dvur-scene.yaml -o dvur.png
 cmf panel  examples/pes/pages/slepice.yaml -o panels/ --all
 ```
 
+## Docs site
+
+`docs/` is a MkDocs Material site published to GitHub Pages by
+`.github/workflows/docs.yml`.
+
+```bash
+uv sync --group docs
+poe docs          # serve with live reload
+poe docs-build    # mkdocs build --strict — what CI runs
+```
+
+**Every image on the site is rendered at build time** by
+`docs/hooks/render_demos.py`, from a spec in `docs/demos/` or from
+`examples/pes/`. Nothing is a checked-in screenshot, so a renderer change that
+breaks a demo breaks the docs build. To add an illustrated example: write
+`docs/demos/<name>.yaml` (small custom `page:`, `library:` pointing at
+`../../examples/pes/characters`), `cmf validate` it, then reference
+`assets/renders/<name>.png` and include the spec with a `pymdownx.snippets`
+include — see `docs/guide/bubbles.md` for the pattern.
+
+`--strict` plus the `validation:` block in `mkdocs.yml` fails the build on a
+broken cross-reference, a dead anchor, a missing snippet or a missing render.
+
 ## Conventions / invariants
 
 - **Content-free engine:** never hardcode an asset name, path, or default project
@@ -91,7 +115,8 @@ cmf panel  examples/pes/pages/slepice.yaml -o panels/ --all
 - The CLI subcommands (`render`/`scene`/`panel`/`characters`/`scenes`) are the
   stable surface; `characters`/`scenes` emit JSON manifests other tools depend on.
 - When you change the spec grammar or CLI, update the authoring skill in
-  `skills/comicforge/` (both `SKILL.md` and `reference.md`) in the same change.
+  `skills/comicforge/` (both `SKILL.md` and `reference.md`) **and** the affected
+  pages under `docs/` in the same change.
 - Demo art is hand/LLM-authored crisp SVG, edited directly in `examples/pes/`
   (there is no procedural generator). Use `comicforge inspire` for *reference*
   images only — never auto-vectorize them; it breaks overlay/anchor registration.

{comicforge-0.2.0 → comicforge-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: comicforge
-Version: 0.2.0
+Version: 0.2.1
 Summary: A tiny, scriptable comic-page engine — author comics as YAML, render to SVG / PNG / PDF
 Requires-Python: >=3.13
 Requires-Dist: cairosvg>=2.7
@@ -13,12 +13,18 @@ Description-Content-Type: text/markdown
 
 # ComicForge
 
+**📖 Documentation: <https://mojzis.github.io/comicforge/>**
+
 A tiny, scriptable comic-page engine. Characters are a **base SVG + stackable
 variant overlays** (faces, arms, …); a comic page is a **declarative YAML spec**;
 output is **SVG / PNG / PDF**. Built so an LLM (or you) can author pages as plain
-text — see the authoring skill [`skills/comicforge/SKILL.md`](skills/comicforge/SKILL.md)
-for the full authoring contract and [`skills/comicforge/reference.md`](skills/comicforge/reference.md)
-for a deeper reference. Working **on the engine** instead? See [`CLAUDE.md`](CLAUDE.md).
+text.
+
+- [Your first comic](https://mojzis.github.io/comicforge/quickstart/) — a project, a character, a strip
+- [Spec reference](https://mojzis.github.io/comicforge/reference/spec/) · [CLI reference](https://mojzis.github.io/comicforge/reference/cli/) · [Gallery](https://mojzis.github.io/comicforge/gallery/)
+- [`skills/comicforge/SKILL.md`](skills/comicforge/SKILL.md) — the authoring contract an LLM reads
+- Working **on the engine**? See [`CLAUDE.md`](CLAUDE.md) and
+  [Contributing](https://mojzis.github.io/comicforge/contributing/).
 
 ## Start a project
 
@@ -32,13 +38,17 @@ cmf init my-comic                  # scaffold characters/ scenes/ pixel/ pages/
 cd my-comic && cmf render pages/hello.yaml
 ```
 
-See [`docs/starting-a-project.md`](docs/starting-a-project.md) for the data-only
-setup, version pinning, and when to make it a real Python project.
+See [Starting a project](https://mojzis.github.io/comicforge/starting-a-project/)
+for the data-only setup, version pinning, and when to make it a real Python
+project.
 
 ## Working on the engine
 
 ```bash
 uv sync                            # create .venv and install deps
+uv run poe test                    # the tight loop
+uv run poe check                   # everything, before opening a PR
+uv run poe docs                    # serve the documentation site locally
 ```
 
 ## Use
@@ -114,8 +124,10 @@ pixel_dir:  "../pixel"        # pixel-art sprites
 CLI flags (`--library`, `--scenes`, `--pixel-dir`) override spec keys and are
 treated as relative to the current working directory.
 
-See [`skills/comicforge/reference.md`](skills/comicforge/reference.md) for the full path
-resolution rule, how to add characters/scenes/sprites, and the complete CLI reference.
+The [documentation site](https://mojzis.github.io/comicforge/) covers the full
+path-resolution rule, how to add characters / scenes / sprites, and the complete
+CLI and spec references — every picture on it is rendered from a spec at build
+time.
 
 ## Design choices
 

{comicforge-0.2.0 → comicforge-0.2.1}/README.md

@@ -1,11 +1,17 @@
 # ComicForge
 
+**📖 Documentation: <https://mojzis.github.io/comicforge/>**
+
 A tiny, scriptable comic-page engine. Characters are a **base SVG + stackable
 variant overlays** (faces, arms, …); a comic page is a **declarative YAML spec**;
 output is **SVG / PNG / PDF**. Built so an LLM (or you) can author pages as plain
-text — see the authoring skill [`skills/comicforge/SKILL.md`](skills/comicforge/SKILL.md)
-for the full authoring contract and [`skills/comicforge/reference.md`](skills/comicforge/reference.md)
-for a deeper reference. Working **on the engine** instead? See [`CLAUDE.md`](CLAUDE.md).
+text.
+
+- [Your first comic](https://mojzis.github.io/comicforge/quickstart/) — a project, a character, a strip
+- [Spec reference](https://mojzis.github.io/comicforge/reference/spec/) · [CLI reference](https://mojzis.github.io/comicforge/reference/cli/) · [Gallery](https://mojzis.github.io/comicforge/gallery/)
+- [`skills/comicforge/SKILL.md`](skills/comicforge/SKILL.md) — the authoring contract an LLM reads
+- Working **on the engine**? See [`CLAUDE.md`](CLAUDE.md) and
+  [Contributing](https://mojzis.github.io/comicforge/contributing/).
 
 ## Start a project
 
@@ -19,13 +25,17 @@ cmf init my-comic                  # scaffold characters/ scenes/ pixel/ pages/
 cd my-comic && cmf render pages/hello.yaml
 ```
 
-See [`docs/starting-a-project.md`](docs/starting-a-project.md) for the data-only
-setup, version pinning, and when to make it a real Python project.
+See [Starting a project](https://mojzis.github.io/comicforge/starting-a-project/)
+for the data-only setup, version pinning, and when to make it a real Python
+project.
 
 ## Working on the engine
 
 ```bash
 uv sync                            # create .venv and install deps
+uv run poe test                    # the tight loop
+uv run poe check                   # everything, before opening a PR
+uv run poe docs                    # serve the documentation site locally
 ```
 
 ## Use
@@ -101,8 +111,10 @@ pixel_dir:  "../pixel"        # pixel-art sprites
 CLI flags (`--library`, `--scenes`, `--pixel-dir`) override spec keys and are
 treated as relative to the current working directory.
 
-See [`skills/comicforge/reference.md`](skills/comicforge/reference.md) for the full path
-resolution rule, how to add characters/scenes/sprites, and the complete CLI reference.
+The [documentation site](https://mojzis.github.io/comicforge/) covers the full
+path-resolution rule, how to add characters / scenes / sprites, and the complete
+CLI and spec references — every picture on it is rendered from a spec at build
+time.
 
 ## Design choices
 

{comicforge-0.2.0 → comicforge-0.2.1}/comicforge/scaffold.py

@@ -82,6 +82,8 @@ A **data-only** ComicForge project: YAML specs + SVG / pixel art, no Python.
 Paths in a spec resolve relative to the spec file, so `library: ../characters`
 works from anywhere. See the skill for the full spec grammar, and add your own
 characters under `characters/` to start placing actors.
+
+Documentation: https://mojzis.github.io/comicforge/
 """
 
 _GITIGNORE = "output/\n"

comicforge-0.2.1/docs/art/characters.md

@@ -0,0 +1,205 @@
+# Making a character
+
+A character is a directory of SVG files and one manifest. No code, no build
+step, no registration anywhere in the engine — drop the directory into
+`characters/` and it exists.
+
+There are two on-disk shapes. Use the simple one until you need more than one
+body.
+
+## Single-pose (flat)
+
+Everything drawn in one `viewBox`:
+
+```
+characters/<name>/
+  base.svg                 the body
+  <slot>-<variant>.svg     overlays, in the SAME viewBox
+  character.yaml           the manifest
+```
+
+```yaml title="character.yaml"
+name: tom                  # internal id — must match the directory name
+label: Tom                 # display name, used in the manifest
+viewbox: [200, 320]        # the shared local canvas [width, height]
+default:
+  face: neutral            # used whenever a spec omits the slot
+  arms: down
+slots:
+  arms: [down, wave, point, crossed, hips, thumbsup]
+  face: [neutral, happy, surprised, sad, angry, laugh, wink]
+```
+
+Every file — base and overlays alike — declares the same `viewBox`. That is the
+whole registration mechanism: the engine strips each SVG to its inner markup and
+stacks them in one coordinate system, so a mouth drawn at `(100, 92)` lands at
+`(100, 92)` on the body.
+
+The stacking order is the slot order in `character.yaml`, so a slot listed later
+draws over one listed earlier. Put `face` after `arms` if a raised hand should
+never cover the mouth.
+
+### Drawing rules that matter
+
+- **One `viewBox`, no exceptions.** An overlay with a different viewBox will be
+  scaled to the pose's and land in the wrong place.
+- **Draw only the part that varies.** `face-happy.svg` contains eyes and a
+  mouth, not a head. The head is in `base.svg`, and drawing it twice means one
+  outline peeking out from behind the other.
+- **Leave the head alone across expressions.** Same size, same position — the
+  variation is in the features.
+- **Name files `<slot>-<variant>.svg`.** The file name *is* the lookup; a slot
+  listed in the manifest with no matching file fails at load time.
+
+Here is a complete, minimal character — the one from
+[Your first comic](../quickstart.md):
+
+=== "base.svg"
+
+    ```svg
+    --8<-- "demos/tutorial-art/characters/pip/base.svg"
+    ```
+
+=== "face-neutral.svg"
+
+    ```svg
+    --8<-- "demos/tutorial-art/characters/pip/face-neutral.svg"
+    ```
+
+=== "face-happy.svg"
+
+    ```svg
+    --8<-- "demos/tutorial-art/characters/pip/face-happy.svg"
+    ```
+
+=== "character.yaml"
+
+    ```yaml
+    --8<-- "demos/tutorial-art/characters/pip/character.yaml"
+    ```
+
+## Multiple poses
+
+When the **body** changes — sitting versus walking, legs in a different place —
+one viewBox is no longer enough. Give each pose its own base, and let the
+expressions stay shared.
+
+```
+characters/<name>/
+  character.yaml           identity + SHARED slots + default + the pose list
+  <slot>-<variant>.svg     SHARED overlays, drawn around the canonical anchor
+  poses/
+    sit/
+      pose.yaml            viewbox, anchor, optional pose-specific slots
+      base.svg             this pose's body
+    walk/
+      pose.yaml
+      base.svg
+      <slot>-<variant>.svg optional overlays that only exist in this pose
+```
+
+```yaml title="character.yaml"
+name: bara
+label: Bára
+anchor: [120, 72]                 # the canonical point shared overlays draw around
+slots:  {face: [neutral, happy]}  # SHARED across poses
+default: {pose: sit, face: neutral}
+poses: [sit, walk]
+```
+
+```yaml title="poses/walk/pose.yaml"
+viewbox: [240, 180]
+anchor: [132, 64]                 # where THIS pose's head centre lands
+slots:  {arms: [trot]}            # optional, pose-specific
+default: {arms: trot}
+```
+
+### The anchor
+
+The anchor is the trick that makes one face file work on every body. It is a
+reference point — the head centre is the natural choice — that you agree on
+once:
+
+- The **character's** `anchor` is where the head centre sits in the coordinate
+  system the shared overlays are drawn in.
+- Each **pose's** `anchor` is where that same head centre sits in *that pose's*
+  viewBox.
+
+When composing, the engine shifts every shared overlay by
+`pose.anchor − character.anchor`. So `face-happy.svg`, authored once, lands
+correctly whether Bára is sitting or walking.
+
+<figure class="cf-demo" markdown>
+![Bára sitting and walking, with the same shared face variants](../assets/renders/poses.png)
+<figcaption>Two bodies, one set of faces. The <code>happy</code> face in the middle and right panels is the same file as the one drawn for <code>sit</code>.</figcaption>
+</figure>
+
+!!! warning "Translate only"
+
+    The shift is a translation and nothing else — no scaling, no rotation. Keep
+    the head the **same size** across every pose and move only its position. A
+    pose that draws a bigger head will wear a face that is too small for it.
+
+### Composition order
+
+For one actor, the engine assembles:
+
+1. the chosen pose's `base.svg`
+2. that pose's **pose-specific** overlays, in `pose.yaml` slot order
+3. the **shared** overlays, in `character.yaml` slot order, each wrapped in the
+   anchor translate
+
+Then the whole thing is scaled to the requested height and centred at the
+requested point.
+
+### Flat is a special case of posed
+
+A flat character is the posed model with one implicit pose whose anchor is
+`[0, 0]` and whose viewBox is the character's. Both render through exactly the
+same code path, which is why adding poses to an existing flat character later is
+a restructuring rather than a rewrite.
+
+## Adding to an existing character
+
+| You want | Do this |
+|---|---|
+| A new shared expression | Draw it around the canonical anchor, save as `<slot>-<variant>.svg` at the character root, add the variant to `slots` in `character.yaml` |
+| A new pose | Add `poses/<name>/` with its own `base.svg` and `pose.yaml` (set its `anchor`), and list the name under `poses:` |
+| A new overlay on a flat character | Save `<slot>-<variant>.svg` in the shared viewBox, add it to `slots` |
+| A whole new slot | Add the slot to `slots`, add a variant file for each value, and give it an entry in `default` |
+
+No code changes in any case.
+
+## Checking your work
+
+```bash
+cmf characters --library characters        # what does the engine think exists?
+cmf character bara walk happy --library characters
+cmf character tom --library characters     # everything at its default
+```
+
+`cmf character` renders one character alone on a plain canvas, cropped to its
+pose — the fastest way to see whether an overlay lines up. It writes the full
+render plus a smaller `<name>.small.png` companion; when an agent is reading the
+result back, the small one costs far fewer tokens.
+
+Common failures and what they mean:
+
+| Symptom | Cause |
+|---|---|
+| `is not a well-formed <svg>…</svg> file` | The overlay is missing its outer `<svg>` element |
+| Overlay lands in the wrong place | Its `viewBox` differs from the base's, or the pose anchor is wrong |
+| `slot 'face' has no variant 'grin'` | The variant is not listed in the manifest — or the file name does not match |
+| A double outline around the head | The overlay redraws part of the base |
+| The face is too small on one pose | That pose draws the head at a different size — anchors translate, they do not scale |
+
+## Where the art comes from
+
+The demo art in `examples/pes/` is hand- and LLM-authored SVG, edited directly.
+There is no procedural generator, and there is no vectorizer in the pipeline.
+
+A visual model is genuinely useful for *inspiration* — generate a reference
+image, then author the crisp SVG from it. [`cmf inspire`](inspire.md) does that
+part. What you must not do is auto-vectorize the result: tracing produces
+thousands of paths in one flat layer, which destroys the slot structure and the
+anchor registration that make the character poseable at all.

comicforge-0.2.1/docs/art/inspire.md

@@ -0,0 +1,147 @@
+# Reference images
+
+`cmf inspire` blends a project-wide **theme** with per-item **descriptions** and
+asks an image model to paint them. The output is **reference art to draw from** —
+never a shipped asset.
+
+```bash
+cmf inspire references.yaml --dry-run     # compose the prompts, call nothing
+cmf inspire references.yaml --review      # generate, plus a review.html grid
+```
+
+!!! danger "Do not auto-vectorize the result"
+
+    Tracing a generated image produces thousands of paths in one flat layer.
+    That destroys the slot structure and the anchor registration that make a
+    character poseable — you end up with a picture, not a character. Look at the
+    reference, then author the SVG. See
+    [Making a character](characters.md).
+
+## Two files
+
+### `theme.yaml` — the project's look
+
+Applied to every image, so the whole cast comes back in one style.
+
+```yaml title="theme.yaml"
+style: >
+  Hand-drawn children's-book comic illustration. Bold, clean black ink outlines
+  with flat cheerful fills and simple friendly shapes. Light, uncluttered
+  background. Centered subject filling the frame.
+
+palette:
+  - "#f4d35e"  # sunny yellow
+  - "#ee964b"  # warm orange
+  - "#0d3b66"  # deep blue
+  - "#faf0ca"  # cream
+  - "#f95738"  # coral
+
+mood: warm, playful, gentle
+
+negative: No text, no letters, no words, no watermark, no signature.
+
+aspect_ratio: "1:1"
+# model: google/imagen-3
+```
+
+| Key | Default | Meaning |
+|---|---|---|
+| `style` | — | The look, in words. Prepended to every prompt |
+| `palette` | — | Hex colours fed to the model as a colour scale |
+| `mood` | — | One line of tone |
+| `negative` | no text / watermark / signature | What to avoid |
+| `aspect_ratio` | `"1:1"` | Passed to the model |
+| `model` | `google/imagen-3` | Any Replicate model id |
+
+A missing `theme.yaml` is not an error — you just get the defaults.
+
+### `references.yaml` — the things to depict
+
+```yaml title="references.yaml"
+items:
+  - id: tom
+    prompt: >
+      A cheerful 8-year-old boy named Tom in a striped t-shirt and shorts,
+      full body, standing, neutral friendly expression, simple cartoon style.
+
+  - id: dvur
+    prompt: >
+      A sunny Czech village farmyard: a wooden fence, a small chicken coop,
+      a few hens pecking, a cobbled yard, a tree to one side.
+```
+
+Each entry needs an id (`id` or `name`) and a description (`prompt`,
+`description` or `desc`). A bare list without the `items:` key works too. The id
+becomes the filename.
+
+## The composed prompt
+
+`style` → `Subject: <prompt>` → palette → mood → negative, joined by blank
+lines:
+
+```text title="references/tom.prompt.txt"
+Hand-drawn children's-book comic illustration. Bold, clean black ink outlines
+with flat cheerful fills and simple friendly shapes. Light, uncluttered
+background. Centered subject filling the frame.
+
+Subject: A cheerful 8-year-old boy named Tom in a striped t-shirt and shorts,
+full body, standing, neutral friendly expression, simple cartoon style.
+
+Use this color palette: #f4d35e, #ee964b, #0d3b66, #faf0ca, #f95738.
+
+Mood: warm, playful, gentle.
+
+No text, no letters, no words, no watermark, no signature.
+```
+
+The sidecar is written next to every image, so you can always see exactly what
+produced a picture. `--dry-run` writes only the sidecars — use it to iterate on
+wording without spending a call or needing a token.
+
+## Output and flags
+
+Each item writes `<out_dir>/<id>.png` and `<out_dir>/<id>.prompt.txt`.
+`theme.yaml` and the output directory default to siblings of the references
+spec.
+
+```bash
+cmf inspire references.yaml -o refs/        # choose the output directory
+cmf inspire references.yaml --theme t.yaml  # a different theme
+cmf inspire references.yaml --only tom,dvur # a subset
+cmf inspire references.yaml --force         # regenerate images that already exist
+cmf inspire references.yaml --review        # also write review.html
+```
+
+By default an item whose `.png` already exists is skipped, so re-running after
+adding one entry costs one call. `--review` writes a `review.html` grid of every
+image beside its prompt — the fastest way to judge a batch and decide what to
+re-word.
+
+## Setup for live generation
+
+```bash
+uv tool install "comicforge[inspire]"      # adds replicate + python-dotenv
+export REPLICATE_API_TOKEN=...             # or a .env beside the spec
+```
+
+The token is read from the environment, or from a `.env` file next to the
+references spec or in the current directory. Live calls are paced — the default
+model caps at roughly six requests a minute, so a batch takes about eleven
+seconds per image.
+
+Neither the extra nor the token is needed for `--dry-run`.
+
+## How to actually use the output
+
+1. Write the description, run `--dry-run`, read the composed prompt.
+2. Generate a handful with `--review` and pick the one that reads best as a
+   *shape* — silhouette, proportions, the pose you want as a base.
+3. Author `base.svg` by hand from it: clean outlines, flat fills, in one
+   viewBox.
+4. Draw the overlays around the same head position, and write
+   `character.yaml`.
+5. Keep the reference in `references/` as documentation of the intent. It never
+   goes into `characters/`.
+
+Step 3 is the work, and there is no shortcut through it. The reference exists to
+make a design decision, not to become the asset.