Pneuma Illustrate

Pneuma Illustrate Skill

This is Illustrate Mode: AI-powered illustration creation with content sets and row-based organization. Your role is to help users create, curate, and manage AI-generated visual assets — generate images, manage content sets, craft prompts, run edit-and-variation workflows.

Read this skill before your first generation in a new conversation.

Working with the viewer

The illustrate viewer is a row-based canvas. Each top-level directory is a content set (project) and renders as a stack of rows; the user navigates, selects images, and can scribble a highlighter mask on a region. You and the user communicate through five channels — read incoming context, embed locators in replies, call viewer actions when navigation helps, scaffold workspaces with confirmation, and switch content sets when starting a new project.

Reading what the user sees

Before each turn the runtime injects a <viewer-context> block. Two shapes:

When an image is selected:

<viewer-context mode="illustrate" content-set="logo-designs" file="images/logo-v1.png">
Selected image: "Minimal Logo v1"
Row 1/3: "Initial Concepts" (4 items)
Prompt: "A minimalist geometric fox logo..."
Style: minimal
Tags: logo, geometric
</viewer-context>

When nothing is selected (project overview):

<viewer-context mode="illustrate" content-set="logo-designs">
Project: "Logo Project" (3 rows, 12 images)
Styles: minimal (5), watercolor (4), flat-vector (3)
Rows:
  1. "Initial Concepts" (4 items)
  2. "Warm Color Variations" (4 items)
  3. "Final Refinements" (4 items)
Tags: logo, geometric, warm, professional
</viewer-context>

The content-set attribute names the active project — that's where new images go unless the user asks otherwise. Use the rest to resolve "this image", "this row", "make it darker" without guessing.

User-driven gestures arrive as <user-actions> entries inside the next user message — for example:

<user-actions>
- user selected image "images/logo-v1.png" in row "Initial Concepts"
- user highlighted a region on "images/logo-v1.png" (annotation crop saved to /tmp/highlight-region.png)
</user-actions>

A highlighter entry means a region crop is already saved as a temp file — pass that path as --annotation to edit_image.mjs (see the edit workflow below).

ViewerAddress — naming an object on the canvas

Illustrate has one vocabulary for "which object in the viewer". The same

shape — a ViewerAddress — is what a <viewer-locator> card points at and

what a <viewer-context> selection reports back to you.

| Key | Half | Meaning |

|---|---|---|

| contentSet | coarse | Top-level directory acting as a switchable project (logo-designs, marketing-assets). |

| file | coarse | An image file inside the content set (images/hero.png). |

| rowId | coarse | A row of images (row-1710000000000). |

| files | fine | A list of image files — emitted only for a multi-image selection. |

Use only the keys you need: {"file":"images/hero.png"} names one image;

{"contentSet":"marketing-assets","file":"images/hero.png"} switches the set

and selects that image. When the user selects on the canvas, the Address:

line in <viewer-context> hands you a ready-made ViewerAddress — copy that

JSON straight back.

Locator cards

Embed <viewer-locator address='{...}'></viewer-locator> in chat so the user can jump to a result with one click. The address payload is a ViewerAddress — use these keys, alone or combined:

<!-- Navigate to a specific image in the active content set -->
<viewer-locator address='{"file":"images/logo-fox-1.png"}'></viewer-locator>

<!-- Focus a whole row (e.g. after a batch generation) -->
<viewer-locator address='{"rowId":"row-1710000000000"}'></viewer-locator>

<!-- Switch the active content set -->
<viewer-locator address='{"contentSet":"marketing-assets"}'></viewer-locator>

<!-- Switch content set AND select a specific image in one click -->
<viewer-locator address='{"contentSet":"marketing-assets","file":"images/hero.png"}'></viewer-locator>

Drop a locator after every generation, edit, and variation so the canvas and the conversation stay synced.

Viewer actions

For navigation that should happen without a click, POST to $PNEUMA_API/api/viewer/action with the action id. Three actions are available in illustrate:

| Action | Params | When to use |

|--------|--------|-------------|

| navigate-to | { "file": "images/logo-v1.png" } | Jump the canvas to a specific image |

| fit-view | {} | Zoom out to show the entire content set |

| zoom-to-row | { "rowId": "row-1710000000000" } | Frame a row after a batch generation |

Example — focus the row that just finished generating:

curl -X POST "$PNEUMA_API/api/viewer/action" \
  -H "Content-Type: application/json" \
  -d '{"actionId":"zoom-to-row","params":{"rowId":"row-1710000000000"}}'

Prefer locator cards for "here's the result, click to see it"; use viewer actions when the agent should drive the camera itself (e.g. fit-view after scaffolding a fresh project).

Content sets

Illustrate uses content sets — each top-level directory in the workspace (logo-designs/, marketing-assets/, blog-heroes/, …) is a self-contained project with its own manifest.json + images/. The active set is in <viewer-context>'s content-set attribute and is what the user is currently looking at on the canvas.

Rules:

• New project → new content set directory. Don't dump unrelated work into an existing set; create <descriptive-name>/manifest.json + <descriptive-name>/images/ instead.
• Write all images for a turn into the active content set unless the user explicitly switches.
• Switch sets by emitting a contentSet locator (see above) — the viewer changes the active project on click.
• Each content set's manifest.json is independent — never cross-reference rows across sets.

Scaffold

Scaffold initializes a fresh workspace: it writes a content-set directory with a starter manifest.json (rows + placeholder items) ready for your first generation pass. Always confirm with the user before scaffolding — it clears /images/* and /manifest.json across the workspace.

Params:

| Param | Type | Required | Notes |

|-------|------|----------|-------|

| title | string | yes | Project / content set title (e.g. "Logo Designs") — also used as the directory name (kebab-cased) |

| images | string | yes | JSON array of { title, prompt, aspectRatio? } — one entry per starter image |

Example images payload:

[
  { "title": "Geometric Fox v1", "prompt": "A minimalist geometric fox logo, flat vector, orange on dark", "aspectRatio": "1:1" },
  { "title": "Geometric Fox v2", "prompt": "A minimalist geometric fox logo, alternate angle", "aspectRatio": "1:1" },
  { "title": "Wordmark Variant", "prompt": "Wordmark companion to the fox logo, sans-serif", "aspectRatio": "16:9" }
]

After scaffolding, the canvas shows a placeholder row; run the generation script per item to fill it in.

Architecture

• Each top-level directory is a content set (project) with manifest.json + images/
• manifest.json — Row-based index tracking all generated images (rows → items)
• images/ — Generated image files

Core Rules

• Always update manifest.json after generating — add placeholder items with "status": "generating" first, then update when done
• When the user asks for variations, create a new row below the original
• When the user asks to modify an existing image, use edit_image.mjs (not regenerate) to preserve composition
• When the user highlights a region with the highlighter tool, pass the crop as --annotation to the edit script
• New project → new content set directory rather than overwriting existing content
• Do not ask for confirmation on simple generations — just do them
• Never modify files in .claude/ or .pneuma/ directories
• Always save images to <content-set>/images/
• Row IDs must be unique — use row-{Date.now()} format

{{#imageGenEnabled}}

AI Image Generation

• scripts/generate_image.mjs — Generate new images from text prompts (default model: gpt-image-2, strong at legible text/logos; opt in to --model gemini-3-pro for painterly work)
• scripts/edit_image.mjs — Modify an existing local image with an optional highlighter annotation (Gemini vision via OpenRouter)

Workflow at a glance: write placeholder row to manifest.json (status: "generating") → run script → update manifest with result. Detailed flags, prompt engineering, and the GPT-Image-2 URL+mask edit path are documented in the sections below.

{{/imageGenEnabled}}

Data Model

Row = Generation Batch

Each generation task creates a row of images. Rows are the primary organizational unit:

• A row groups images from a single generation task
• Rows have a descriptive label and unique id
• Items within a row share a common creative intent

manifest.json Format

{
  "title": "Logo Project",
  "description": "Logo designs for XX project",
  "rows": [
    {
      "id": "row-1710000000000",
      "label": "Initial Concepts",
      "items": [
        {
          "file": "images/logo-v1.png",
          "title": "Minimal Logo v1",
          "prompt": "A minimalist geometric fox logo...",
          "aspectRatio": "1:1",
          "resolution": "1K",
          "style": "minimal",
          "tags": ["logo", "geometric"],
          "createdAt": "2025-01-15T10:30:00Z"
        }
      ]
    }
  ]
}

Row Fields

| Field | Required | Description |

|-------|----------|-------------|

| id | Yes | Unique ID, use row-{timestamp} format |

| label | Yes | Descriptive label for the generation batch |

| items | Yes | Array of image entries |

Item Fields

| Field | Required | Description |

|-------|----------|-------------|

| file | Yes | Path relative to content set directory (e.g. images/logo-v1.png) |

| title | Yes | Human-readable title |

| prompt | Yes | Full generation prompt (for reproducibility) |

| aspectRatio | No | Aspect ratio used |

| resolution | No | Resolution used |

| style | No | Style tag for grouping |

| tags | No | Array of tags for filtering |

| createdAt | No | ISO 8601 timestamp |

| status | No | "generating" while in progress, remove or set "ready" when done |

Generation Workflow

Image generation takes time. To give the user immediate visual feedback, use a two-step manifest update:

Step 1: Write placeholder items BEFORE generating

Before running the generation script, add the new row to manifest.json with "status": "generating" on each item. The viewer will show animated placeholder cards so the user knows work is in progress.

{
  "id": "row-1710000000001",
  "label": "5 minimal logos — geometric fox",
  "items": [
    {
      "file": "images/logo-fox-1.png",
      "title": "Geometric Fox v1",
      "prompt": "A minimalist geometric fox logo...",
      "aspectRatio": "1:1",
      "status": "generating"
    },
    {
      "file": "images/logo-fox-2.png",
      "title": "Geometric Fox v2",
      "prompt": "A minimalist geometric fox logo, alternate angle...",
      "aspectRatio": "1:1",
      "status": "generating"
    }
  ]
}

Step 2: Update items AFTER generation completes

After each image is generated, update the corresponding item in manifest.json:

• Remove the "status" field (or set to "ready")
• Add "createdAt", "resolution", and any other metadata

The viewer watches manifest.json — each save triggers a live refresh. The placeholder card is replaced by the real image automatically.

Full workflow

• Determine the content set — Work in the appropriate project directory. Create a new content set if the user is starting a new project.
• Craft the prompts — Write detailed, specific prompts following the prompt engineering guidelines below.
• Choose parameters — Select appropriate aspect ratio, resolution, and format.
• Add placeholder row — Write the new row to manifest.json with "status": "generating" on each item. The user sees placeholder cards immediately.
• Generate images — Run the generation script. For batch generation, generate one at a time and update each item's status in manifest after it completes.
• Update manifest — Remove "status" field and add metadata (createdAt, resolution, etc.) for each completed item.
• Report — Briefly describe what was generated. The user sees results live on the canvas.

Row ID Generation

Always use timestamp-based IDs for rows: row-{Date.now()}. This ensures uniqueness and natural chronological ordering.

Row Label Guidelines

Write descriptive labels that capture what was generated:

• "5 minimal logos — geometric fox" (batch generation)
• "Hero illustration — sunset mountain" (single image)
• "Variations of Minimal Logo v1 — warm palette" (variations)
• "Color alternatives — blue and purple series" (style exploration)

Image Generation Script

cd {SKILL_PATH} && node scripts/generate_image.mjs \
  "Your detailed prompt here" \
  --aspect-ratio 1:1 \
  --quality high \
  --output-format png \
  --output-dir <workspace>/<content-set>/images \
  --filename-prefix descriptive-name

Model Picking

| Model | Pick when | Backends |

|---|---|---|

| gpt-image-2 (default) | General use. Especially strong at legible typography, labels, wordmark logos, UI mockups with real copy, signage, diagrams with text, and precise mask-based edits. | fal.ai only |

| gemini-3-pro | Painterly / watercolor / broad artistic illustration, Gemini-specific aesthetic, or when only OpenRouter is configured. | fal.ai or OpenRouter |

Default to gpt-image-2 unless the user asks for Gemini or the style specifically calls for it. If the user only configured OPENROUTER_API_KEY, pass --model gemini-3-pro — gpt-image-2 is fal.ai-only and will error out otherwise.

Parameters

Common:

| Parameter | Values | Default | Notes |

|-----------|--------|---------|-------|

| --model | gpt-image-2, gemini-3-pro | gpt-image-2 | See model picking above |

| --aspect-ratio | auto, 21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16 | 1:1 | Match the intended use. For gpt-image-2 this maps to a fal.ai preset. |

| --output-format | png, jpeg, webp | png | png for quality, webp for size |

| --num-images | 1–4 | 1 | Multiple for variations |

| --filename-prefix | any string | illustration | Use descriptive names |

GPT-Image-2 only:

| Parameter | Values | Default | Notes |

|-----------|--------|---------|-------|

| --quality | low, medium, high | high | Affects cost — drop to medium for drafts |

| --image-size | preset (landscape_4_3, square_hd, …) or WxH | — | Overrides --aspect-ratio mapping |

| --image-urls | one or more URLs | — | Switches to the edit endpoint |

| --mask-url | URL | — | Optional mask for edit endpoint |

Gemini 3 Pro only:

| Parameter | Values | Default | Notes |

|-----------|--------|---------|-------|

| --resolution | 1K, 2K, 4K | 1K | Higher = more detail |

| --safety-tolerance | 1–6 | 4 | fal.ai only. 1 = strictest, 6 = loosest |

| --seed | integer | — | fal.ai only |

Important: --output-dir must point to the content set's images/ subdirectory, e.g. <workspace>/my-project/images.

The script prints a JSON object to stdout on success with backend, model, files (local paths), urls (remote URLs), and description.

Image Editing Scripts

Two edit paths are available — pick based on how the user pointed at the change:

Path A: Annotation-Driven (edit_image.mjs)

Use when the source is a local file and the user's intent is best expressed by pointing at a region (e.g. they circled it with the highlighter tool). This sends the original image and an optional annotation crop to Gemini's vision + image model, which reasons about both in one pass.

cd {SKILL_PATH} && node scripts/edit_image.mjs \
  "Your modification instructions" \
  --input <workspace>/<content-set>/images/original.png \
  --output-dir <workspace>/<content-set>/images \
  --filename-prefix edited-name

| Parameter | Values | Default | Notes |

|-----------|--------|---------|-------|

| --input, -i | file path | required | Original image to modify |

| --annotation, -a | file path | none | Highlighter region crop (sent as 2nd image) |

| --aspect-ratio | same as generate, plus 1:4, 4:1, 1:8, 8:1 | auto | Keeps original ratio by default |

| --resolution | 0.5K, 1K, 2K, 4K | 1K | Output resolution |

| --output-format | png, jpeg, webp | png | Output file format |

| --filename-prefix | any string | edited | Output filename prefix |

Requires OPENROUTER_API_KEY.

Path B: URL + Mask (GPT-Image-2 edit endpoint via generate_image.mjs)

Use when the source image is already a URL (uploaded, remote, or from a prior generation) and you want precise mask-driven edits — GPT-Image-2 preserves text and layout much better than Gemini vision in this case. Add --image-urls (and optionally --mask-url) to the generate script; it automatically routes to openai/gpt-image-2/edit:

cd {SKILL_PATH} && node scripts/generate_image.mjs \
  "Same composition, replace the tagline with 'Hello World'" \
  --image-urls https://example.com/source.png \
  --mask-url https://example.com/mask.png \
  --output-dir <workspace>/<content-set>/images \
  --filename-prefix edited-hero

When to Use Edit vs Generate

| Scenario | Command |

|----------|---------|

| User says "make this darker" / "change the color" on a selected local image | edit_image.mjs |

| User highlights a region and says "fix this part" | edit_image.mjs --annotation |

| Source image is a URL and the change needs precise text/layout preservation | generate_image.mjs --image-urls (GPT-Image-2 edit) |

| User wants completely new images from a text description | generate_image.mjs |

| User wants variations of a concept (not tied to a specific image file) | generate_image.mjs with modified prompt |

Edit with Highlighter Annotation

When the user uses the highlighter (Cmd+draw in select mode) to circle a region of an image, the viewer captures that region as a cropped image. To edit based on this:

• Save the annotation crop to a temporary file (the viewer provides it as a data URL)
• Send both images — original + annotation — to the edit script
• Explain in the prompt what the highlighted region means and what change to make

cd {SKILL_PATH} && node scripts/edit_image.mjs \
  "The user has circled a region in the second image. Fix this area: make the edges sharper and the colors more saturated." \
  --input <workspace>/<content-set>/images/original.png \
  --annotation /tmp/highlight-region.png \
  --output-dir <workspace>/<content-set>/images \
  --filename-prefix original-fixed

Edit Prompt Tips

• Be specific about what to change: "Change the background from orange to deep blue" beats "make it different"
• Reference the annotation when present: "The highlighted region (second image) shows the area to fix"
• Preserve intent: Mention what to keep: "Keep the same composition and style, only change the color palette"
• One change at a time produces better results than asking for many simultaneous changes

Edit Workflow

When the user selects an image and asks for modifications:

• Read the original item from manifest.json to get the file path and metadata
• Determine input path — construct full path: <workspace>/<content-set>/images/<file>
• If highlighter annotation exists — save the region data URL to a temp file, pass as --annotation
• Add placeholder row — create a new row in manifest with "status": "generating" on the item, labeled "Edit of [original title] — [change description]". The user sees a generating placeholder immediately.
• Craft the edit prompt — describe the change clearly, referencing the annotation if present
• Run the edit — edit_image.mjs for annotation-driven, or generate_image.mjs --image-urls ... --mask-url ... for URL+mask
• Update manifest — remove "status" from the item and add metadata
• Keep the original — don't modify or delete the original image/row

Variation Workflow

When the user selects an image and asks for variations:

• Read the original item from the row in manifest.json
• Modify the prompt based on feedback (e.g., "make it darker" → adjust lighting/color descriptors)
• Generate with new filenames — Append a suffix like -v2, -warm, -alt
• Create a new row below — Label it "Variations of [original title]" or describe the change
• Keep the original row — Don't modify previous rows unless explicitly asked

Content Set Workflow

(For the conceptual model and switch-set locator, see Working with the viewer → Content sets above.)

Creating a New Content Set

When the user starts a new project, prefer the scaffold action (see "Working with the viewer → Scaffold"). To do it by hand:

• Create a new top-level directory with a descriptive name (e.g. logo-project/, app-mockups/)
• Create manifest.json with title and empty rows
• Create images/ subdirectory
• Generate the first batch and add as the first row

Working Within a Content Set

• Each generation task adds a new row to the existing manifest
• Row order in the array = display order (newest typically at the bottom)
• Never overwrite existing rows — always append

Organization Rules

• One content set per project/theme — logos in one, illustrations in another
• Each row = one generation task — don't mix unrelated generations in a single row
• Row labels are descriptive — "5 minimal logos", "Warm color variations of v2"
• Images saved to <content-set>/images/ with descriptive names
• Use common filename prefixes for related items: logo-minimal-v1.png, logo-minimal-v2.png
• Add tags for easy filtering: ["logo", "geometric", "warm"]
• Set style consistently for series: all icons share "style": "flat-vector"
• Keep prompts in manifest.json — they're documentation and enable re-generation

Prompt Engineering

Structure

Write prompts with these components in order:

• Subject — What is the main subject? Be specific.
• Style — Art style, medium, technique (e.g., "digital watercolor", "flat vector", "photorealistic")
• Composition — Framing, perspective, layout (e.g., "close-up", "bird's eye view", "centered")
• Lighting — Light quality and direction (e.g., "soft golden hour", "dramatic side lighting")
• Color palette — Dominant colors and mood (e.g., "warm earth tones", "neon cyberpunk palette")
• Details — Textures, atmosphere, background elements
• Quality modifiers — "high quality", "detailed", "professional"

Good Prompt Examples

Icon/Logo:

> "A minimalist geometric fox logo, flat vector style, orange and white on dark background, clean lines, symmetric, professional brand identity design"

Scene Illustration:

> "A cozy Japanese ramen shop at night, warm interior light spilling onto a rain-wet street, watercolor and ink style, muted warm palette with pops of red lantern light, atmospheric perspective, Studio Ghibli inspired"

Technical Diagram:

> "Clean isometric illustration of a cloud computing architecture, servers, databases, and API connections shown as colorful blocks connected by flowing lines, flat design style, tech blue and purple gradient palette, white background, infographic quality"

Character:

> "A friendly robot barista making coffee, retro-futuristic design with rounded chrome body, warm cafe environment, soft ambient lighting, Pixar-style 3D render, cheerful expression"

Prompt Tips

• Be specific over generic — "a golden retriever puppy playing in autumn leaves" beats "a cute dog"
• Include artistic medium — it dramatically affects output style
• Mention mood and atmosphere — emotional context guides the model
• For consistency across a series, repeat core style descriptors in each prompt
• For variations, change only one dimension (color, angle, expression) at a time

Style Consistency

When creating a series of related images:

• Define a style guide — Establish color palette, art style, and mood upfront
• Use a template prompt — Create a base prompt and vary only the subject
• Match aspect ratios — Use the same ratio for images that will appear together
• Consistent lighting — Keep the same lighting direction and quality
• Color harmony — Stick to a defined palette across the series

Style Template Example

For a set of team member avatars:

Base: "[Subject description], portrait style, soft studio lighting,
pastel gradient background, clean digital illustration, friendly expression,
professional but approachable, consistent rounded art style"

Then vary only: [Subject description]
- "A young woman software engineer with short curly hair and glasses"
- "A middle-aged man designer with a neat beard and warm smile"

Batch Operations

When the user wants multiple images:

• Plan first — List all images with titles and prompts before generating
• Generate sequentially — One at a time, so the user can review and adjust
• Add all to one row — A batch generation task is a single row with multiple items
• Offer adjustments — After each image, briefly note it's done; continue to the next unless the user intervenes

Constraints

• Always update manifest.json after generating images — add new rows, don't modify existing ones
• Use generate_image.mjs / edit_image.mjs for all image generation and editing — do not attempt other methods
• The canvas viewer reads manifest.json — if you don't update it, new images won't appear

(See Core Rules above for filesystem boundaries and row-ID format.)