Illustrated stories: images in, images out.

0. Setup

Both examples are checked in and runnable. You need an image-capable model provider configured (the examples default to OpenAI’s image model for rendering and a vision model for authoring), and the weavemark CLI on your path. Work from the repository root.

cd weavemark
export OPENAI_API_KEY=sk-...   # or your provider's key

1. Images as input and output

Two small language facts unlock everything in this tutorial.

![Style reference](@{style_reference})
![Character sheet 1](@{character_sheet_1})

@output type: image
  size: 1536x1024
  quality: high
  edit: on

2. Run the reference-driven comic

The comic example feeds a style-reference strip and four character sheets into the model, authors a scripted 5-panel strip, renders it, and inspects its own output until it passes. Run it:

bash examples/saved-artifact-workflows/comic-strip-en/run.sh

The runner first writes compiled-chain.json so you can inspect the prompts and reflection settings before reviewing the generated image and its inspection trace.

Under the hood that is a single weavemark --run over one spec — no external script does the orchestration:

weavemark library builtin:catalog/executable/comic-strip \
  --run \
  --vars-file examples/saved-artifact-workflows/comic-strip-en/inputs/vars.json \
  --output-dir examples/saved-artifact-workflows/comic-strip-en/outputs \
  --trace-output examples/saved-artifact-workflows/comic-strip-en/outputs/inspection-log.md \
  --batch-only

See the transfer for yourself. One of the inputs is this character sheet — the reference for Doctor Krazy and his robot cat Deimotron:

And here is the finished strip. Notice how those exact traits — Krazy’s hair, goggles and coat, Deimotron’s glowing eyes and mechanical joints — carry straight from the sheet into the rendered panels where each character appears:

That is the whole point: the reference images keep the cast on-model and hold the reference’s soft pastel palette. The character sheets and the style-reference comic are attached as inputs to both the authoring and the rendering stages, so one drawing transfers faithfully into another.

3. The self-inspecting render loop

The comic runs on @execute reflection, which is a production chain followed by a critique → revise loop. critique and revise are reserved roles; every other @prompt stage is a production step. The last production stage yields the artifact the loop refines.

@execute reflection
  rounds: 3

@prompt author
  @refine module:weavemark.domains.creative.illustrated_story_core
    with story_format: "comic-strip"
    with references: true

@prompt generate
  @output type: image
    file: comic-strip.png
    size: 1536x1024
    quality: high
    edit: on
  @{author}
  @if style_reference
    ![Style reference — match line art, coloring, lettering, panel framing](@{style_reference})

@prompt critique
  You are a strict comic-strip art director inspecting the attached RENDERED
  comic strip against its specification.

  Specification the image must satisfy:
  -----
  @{author}
  -----

  Reply with exactly "OK" if the image faithfully satisfies the specification
  with none of these defects. Otherwise reply with a short bullet list of the
  concrete, fixable defects, citing the panel. List only defects.

@prompt revise
  @output type: image
    size: 1536x1024
    quality: high
    edit: on
  @{author}

  The previous render had these defects — fix ALL of them exactly, and do NOT
  introduce any new issues:
  {{critique}}

Full spec: comic-strip.weavemark.md · shared core: illustrated-story-core.weavemark.md

4. Direct every frame with a dynamic beat sheet

The story is not improvised. The concrete spec carries a dynamic beat sheet. Instead of enumerating a fixed number of dotted paths in the promplet, the author stage receives the complete @{panels} object and requires exactly @{panel_count} ordered entries.

## Panel beat sheet — exactly what happens in each panel

Realize these EXACT beats, in this order, one per panel. The staging and
dialogue of each panel are fixed: flesh out expression, framing, and comedic
timing around them, but do not add, drop, reorder, or merge beats, and keep
every line of dialogue verbatim as short hand-lettered speech balloons. Let the
final panel land the punchline cleanly. Use all @{panel_count} supplied entries
and preserve every staging beat and dialogue string exactly.

Supplied `panels` beat sheet:

@{panels}

The panels themselves live in the companion variables, so rewriting the story never touches the spec — you edit data. This valid JSON reduction keeps one exact panel entry:

{
  "panels": {
    "1": {
      "staging": "Wide establishing shot of the sunlit kitchen-diner. Doctor Krazy bursts in from the left, arms flung wide, presenting Deimotron — his metallic silver-grey robot cat with glowing cyan eyes — on the table like a prize. Deimos sits upright at the same table with his teacup, eyes half-lidded, thoroughly unimpressed.",
      "dialogue": "Doctor Krazy (beaming): \"Behold! DEIMOTRON — the perfect cat. ZERO bad habits!\"  Deimos (flat): \"Bold claim.\""
    }
  }
}

5. Run the children’s picture book

The storybook reuses the very same core, pinned to the picture-book format, and runs on @execute chain: an author stage writes the whole book, then a page stage is repeated once per page, rendering and persisting each illustration.

@execute chain
  repeat: page
  count: @{page_count}

@prompt author
  @refine module:weavemark.domains.creative.illustrated_story_core
    with story_format: "picture-book"

  ## Page beat sheet — exactly what happens on each page

  Build the book to this exact page-by-page spine, in order — one entry per page.
  For each supplied entry, turn its `scene` into a full, on-model illustration
  prompt (restating every character's visual anchor), and use its `text` as that
  page's narration. Preserve the exact provided text and distinctive staging;
  refine only surrounding illustration detail and read-aloud rhythm. Do not skip,
  reorder, merge, truncate, or invent entries, and ensure all @{page_count}
  authored beats are represented.

  Supplied `pages` beat sheet:

  @{pages}

@prompt page
  @output type: image
    file: pages/page-@{index}.png
    size: @{image_size}
  You are the illustrator for the picture book below. Render page @{index} of
  @{count} as ONE finished illustration.

  The full authored book (JSON), for story context and cross-page consistency:
  @{author}

With narration lettered directly into each illustration, every image is a complete, printable page. Run it:

bash examples/saved-artifact-workflows/childrens-book-orion-en/run.sh

The runner writes compiled-chain.json before execution, then persists each rendered page as it becomes available and packages the final HTML and PDF.

Full spec: childrens-book.weavemark.md

6. Package the pages into a printable book

Rendering twelve pages is only half the job — you still need a deliverable. The @package directive assembles produced artifacts after execution, entirely in the language:

@package instructions: module:weavemark.domains.creative.picture_book_html file: book.html
@package from: book.html file: book.pdf

The result is a folder with pages/page-1.png … page-12.png, a book.html that references them in order, and a single book.pdf you can send to a printer — all from one weavemark --run.

Packaging instructions: picture-book-html.weavemark.md

Final step: Use the output

These examples are not just prompt generators. When you run the scripts with a configured image-capable model, the WeaveMark pipeline executes and writes the finished media artifacts.

What you learned

• A Markdown image link becomes a real multimodal input; @output type: image makes a stage render an output.
• @execute reflection is a production chain plus a critique → revise loop — the model inspects and repairs its own rendered artifact.
• @execute chain with repeat renders a sequence (one page after another) and @output file: persists each one.
• Dynamic @{panels} and @{pages} objects let one source handle any declared panel or page count while every beat stays explicit data.
• @package turns produced artifacts into deliverables (HTML, PDF) fully in the language — no glue script.
• One reusable core (illustrated-story-core) powers both the comic and the book; the concrete specs only pin what differs.