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.

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:

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:

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

Item Fields

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

1. Determine the content set — Work in the appropriate project directory. Create a new content set if the user is starting a new project.
2. Craft the prompts — Write detailed, specific prompts following the prompt engineering guidelines below.
3. Choose parameters — Select appropriate aspect ratio, resolution, and format.
4. Add placeholder row — Write the new row to manifest.json with "status": "generating" on each item. The user sees placeholder cards immediately.
5. 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.
6. Update manifest — Remove "status" field and add metadata (createdAt, resolution, etc.) for each completed item.
7. 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

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:

GPT-Image-2 only:

Gemini 3 Pro 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

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

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:

1. Save the annotation crop to a temporary file (the viewer provides it as a data URL)
2. Send both images — original + annotation — to the edit script
3. 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:

1. Read the original item from manifest.json to get the file path and metadata
2. Determine input path — construct full path: <workspace>/<content-set>/images/<file>
3. If highlighter annotation exists — save the region data URL to a temp file, pass as --annotation
4. 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.
5. Craft the edit prompt — describe the change clearly, referencing the annotation if present
6. Run the edit — edit_image.mjs for annotation-driven, or generate_image.mjs --image-urls ... --mask-url ... for URL+mask
7. Update manifest — remove "status" from the item and add metadata
8. Keep the original — don't modify or delete the original image/row

Variation Workflow

When the user selects an image and asks for variations:

1. Read the original item from the row in manifest.json
2. Modify the prompt based on feedback (e.g., "make it darker" → adjust lighting/color descriptors)
3. Generate with new filenames — Append a suffix like -v2, -warm, -alt
4. Create a new row below — Label it "Variations of [original title]" or describe the change
5. 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:

1. Create a new top-level directory with a descriptive name (e.g. logo-project/, app-mockups/)
2. Create manifest.json with title and empty rows
3. Create images/ subdirectory
4. 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:

1. Subject — What is the main subject? Be specific.
2. Style — Art style, medium, technique (e.g., "digital watercolor", "flat vector", "photorealistic")
3. Composition — Framing, perspective, layout (e.g., "close-up", "bird's eye view", "centered")
4. Lighting — Light quality and direction (e.g., "soft golden hour", "dramatic side lighting")
5. Color palette — Dominant colors and mood (e.g., "warm earth tones", "neon cyberpunk palette")
6. Details — Textures, atmosphere, background elements
7. 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:

1. Define a style guide — Establish color palette, art style, and mood upfront
2. Use a template prompt — Create a base prompt and vary only the subject
3. Match aspect ratios — Use the same ratio for images that will appear together
4. Consistent lighting — Keep the same lighting direction and quality
5. 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:

1. Plan first — List all images with titles and prompts before generating
2. Generate sequentially — One at a time, so the user can review and adjust
3. Add all to one row — A batch generation task is a single row with multiple items
4. 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.)