@allthingsclaude/blueprints 0.4.7 → 0.4.8

package/README.md

@@ -140,7 +140,7 @@ Control which models power your agents:
 | `/email` | Create on-brand HTML email templates (newsletters, announcements, transactional) |
 | `/pitch` | Create an on-brand HTML presentation deck with speaker notes |
 | `/og` | Auto-generate Open Graph images for all pages in your project |
-| `/imagine` | Generate images using Nano Banana 2 (Gemini/fal.ai) |
+| `/imagine` | Generate images using Nano Banana 2 (Gemini/fal.ai) or GPT Image 2 (fal.ai), or both side-by-side |
 | `/storyboard` | Extract UI interaction specs from video mockups |
 | `/showcase` | Design an award-winning landing page with animations and micro-interactions |
 | `/diagram` | Generate Mermaid diagrams from your codebase |
@@ -442,7 +442,7 @@ Agents are specialized workers launched by commands. Each agent is assigned a mo
 | `finalize` | `/finalize` | Session wrap-up and commits |
 | `handoff` | `/handoff` | Context documentation |
 | `i18n` | `/i18n` | Internationalization auditing and setup |
-| `imagine` | `/imagine` | Image generation via Nano Banana 2 |
+| `imagine` | `/imagine` | Image generation via Nano Banana 2 or GPT Image 2 |
 | `implement` | `/implement` | Autonomous plan execution |
 | `migrate` | `/migrate` | Dependency upgrades and migrations |
 | `og` | `/og` | Open Graph image generation for all pages |

package/content/agents/imagine.md

@@ -1,6 +1,6 @@
 ---
 name: imagine
-description: Generate images via Nano Banana 2 API
+description: Generate images via Nano Banana 2 or GPT Image 2
 tools: Bash
 model: {{MODEL}}
 author: "@markoradak"
@@ -16,8 +16,10 @@ You generate images by running a single Bash command. Nothing else.
 - Do NOT search the web or use the Write tool
 - If the command fails, report the error and stop immediately
 - ONLY use these exact API endpoints:
-  - fal generate: `https://fal.run/fal-ai/nano-banana-2`
-  - fal edit: `https://fal.run/fal-ai/nano-banana-2/edit`
+  - fal nano generate: `https://fal.run/fal-ai/nano-banana-2`
+  - fal nano edit: `https://fal.run/fal-ai/nano-banana-2/edit`
+  - fal gpt generate: `https://fal.run/openai/gpt-image-2`
+  - fal gpt edit: `https://fal.run/openai/gpt-image-2/edit`
   - gemini: `https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent`
 
 ## CRITICAL: Shell escaping
@@ -30,6 +32,7 @@ You generate images by running a single Bash command. Nothing else.
 
 Extract from the prompt you received:
 - `prompt` — the enhanced image prompt
+- `model` — `nano-banana-2`, `gpt-image-2`, or `both`
 - `api` — "gemini" or "fal"
 - `mode` — "generate" or "edit"
 - `name` — snake_case name for the output file
@@ -37,9 +40,38 @@ Extract from the prompt you received:
 - `resolution` — "1K", "2K", or "4K"
 - `reference_images` — file paths (only if mode is "edit")
 
-Output file: `generated/imagine_{name}.png`
+## Template selection
 
-## fal + generate
+| model            | mode     | use template                |
+|------------------|----------|-----------------------------|
+| nano-banana-2    | generate | `gemini + generate` if api=gemini, else `fal nano + generate` |
+| nano-banana-2    | edit     | `gemini + edit` if api=gemini, else `fal nano + edit`         |
+| gpt-image-2      | generate | `fal gpt + generate`        |
+| gpt-image-2      | edit     | `fal gpt + edit`            |
+| both             | generate | `both + generate` (parallel fal nano + fal gpt) |
+| both             | edit     | `both + edit` (parallel fal nano + fal gpt)     |
+
+## Output file(s)
+
+- `model=nano-banana-2` or `gpt-image-2` → `generated/imagine_{name}.png`
+- `model=both` → `generated/imagine_{name}_nano.png` AND `generated/imagine_{name}_gpt.png`
+
+## aspect_ratio → image_size preset (gpt-image-2 only)
+
+gpt-image-2 doesn't take `aspect_ratio`/`resolution`. Map to fal preset name:
+
+| aspect_ratio | image_size preset  |
+|--------------|--------------------|
+| `1:1`        | `square_hd`        |
+| `16:9`       | `landscape_16_9`   |
+| `9:16`       | `portrait_16_9`    |
+| `4:3`        | `landscape_4_3`    |
+| `3:4`        | `portrait_4_3`     |
+| anything else| `landscape_4_3`    |
+
+Always pass `quality: "high"` for gpt-image-2.
+
+## fal nano + generate
 
 Copy this template exactly, substituting PROMPT, NAME, ASPECT, RESOLUTION:
 
@@ -51,7 +83,7 @@ PROMPTEOF
 node -e 'var fs=require("fs");fs.writeFileSync("/tmp/imagine_payload.json",JSON.stringify({prompt:fs.readFileSync("/tmp/imagine_prompt.txt","utf-8").trim(),aspect_ratio:"ASPECT",resolution:"RESOLUTION"}))' && curl -s "https://fal.run/fal-ai/nano-banana-2" -H "Authorization: Key $FAL_KEY" -H "Content-Type: application/json" -d @/tmp/imagine_payload.json -o /tmp/imagine_resp.json && IMG=$(node -p 'JSON.parse(require("fs").readFileSync("/tmp/imagine_resp.json","utf-8")).images[0].url') && curl -s "$IMG" -o generated/imagine_NAME.png && rm -f /tmp/imagine_resp.json /tmp/imagine_payload.json /tmp/imagine_prompt.txt
 ```
 
-## fal + edit
+## fal nano + edit
 
 Copy this template exactly, substituting PROMPT, NAME, ASPECT, RESOLUTION, PATH1/PATH2:
 
@@ -87,8 +119,62 @@ PROMPTEOF
 node -e 'var fs=require("fs"),prompt=fs.readFileSync("/tmp/imagine_prompt.txt","utf-8").trim(),imgs=["PATH1","PATH2"],parts=imgs.map(function(p){return {inline_data:{mime_type:"image/"+p.split(".").pop(),data:fs.readFileSync(p).toString("base64")}}});parts.push({text:prompt});fs.writeFileSync("/tmp/imagine_payload.json",JSON.stringify({contents:[{parts:parts}],generationConfig:{responseModalities:["IMAGE"],imageConfig:{aspectRatio:"ASPECT",imageSize:"RESOLUTION"}}}))' && curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" -H "Content-Type: application/json" -H "x-goog-api-key: $GEMINI_API_KEY" -d @/tmp/imagine_payload.json -o /tmp/imagine_resp.json && node -e 'var fs=require("fs"),r=JSON.parse(fs.readFileSync("/tmp/imagine_resp.json","utf-8")),c=r.candidates,p=c&&c[0]&&c[0].content&&c[0].content.parts,i=p&&p.find(function(x){return x.inlineData||x.inline_data});if(!i){var e=r.error;console.error(e&&e.message||"No image");process.exit(1)}var d=i.inlineData||i.inline_data;fs.writeFileSync("generated/imagine_NAME.png",Buffer.from(d.data,"base64"))' && rm -f /tmp/imagine_resp.json /tmp/imagine_payload.json /tmp/imagine_prompt.txt
 ```
 
+## fal gpt + generate
+
+Copy this template exactly, substituting PROMPT, NAME, IMAGE_SIZE (mapped from aspect_ratio per the table above):
+
+```
+mkdir -p generated
+cat << 'PROMPTEOF' > /tmp/imagine_prompt.txt
+PROMPT
+PROMPTEOF
+node -e 'var fs=require("fs");fs.writeFileSync("/tmp/imagine_payload.json",JSON.stringify({prompt:fs.readFileSync("/tmp/imagine_prompt.txt","utf-8").trim(),image_size:"IMAGE_SIZE",quality:"high"}))' && curl -s "https://fal.run/openai/gpt-image-2" -H "Authorization: Key $FAL_KEY" -H "Content-Type: application/json" -d @/tmp/imagine_payload.json -o /tmp/imagine_resp.json && IMG=$(node -p 'JSON.parse(require("fs").readFileSync("/tmp/imagine_resp.json","utf-8")).images[0].url') && curl -s "$IMG" -o generated/imagine_NAME.png && rm -f /tmp/imagine_resp.json /tmp/imagine_payload.json /tmp/imagine_prompt.txt
+```
+
+## fal gpt + edit
+
+Copy this template exactly, substituting PROMPT, NAME, IMAGE_SIZE, PATH1/PATH2:
+
+```
+mkdir -p generated
+cat << 'PROMPTEOF' > /tmp/imagine_prompt.txt
+PROMPT
+PROMPTEOF
+node -e 'var fs=require("fs"),prompt=fs.readFileSync("/tmp/imagine_prompt.txt","utf-8").trim(),imgs=["PATH1","PATH2"],urls=imgs.map(function(p){return "data:image/"+p.split(".").pop()+";base64,"+fs.readFileSync(p).toString("base64")});fs.writeFileSync("/tmp/imagine_payload.json",JSON.stringify({prompt:prompt,image_urls:urls,image_size:"IMAGE_SIZE",quality:"high"}))' && curl -s "https://fal.run/openai/gpt-image-2/edit" -H "Authorization: Key $FAL_KEY" -H "Content-Type: application/json" -d @/tmp/imagine_payload.json -o /tmp/imagine_resp.json && IMG=$(node -p 'JSON.parse(require("fs").readFileSync("/tmp/imagine_resp.json","utf-8")).images[0].url') && curl -s "$IMG" -o generated/imagine_NAME.png && rm -f /tmp/imagine_resp.json /tmp/imagine_payload.json /tmp/imagine_prompt.txt
+```
+
+## both + generate
+
+Runs fal nano-banana-2 and fal gpt-image-2 in parallel within a single Bash call. Substitute PROMPT, NAME, ASPECT, RESOLUTION, IMAGE_SIZE:
+
+```
+mkdir -p generated
+cat << 'PROMPTEOF' > /tmp/imagine_prompt.txt
+PROMPT
+PROMPTEOF
+node -e 'var fs=require("fs"),p=fs.readFileSync("/tmp/imagine_prompt.txt","utf-8").trim();fs.writeFileSync("/tmp/imagine_nano_payload.json",JSON.stringify({prompt:p,aspect_ratio:"ASPECT",resolution:"RESOLUTION"}));fs.writeFileSync("/tmp/imagine_gpt_payload.json",JSON.stringify({prompt:p,image_size:"IMAGE_SIZE",quality:"high"}))' && (curl -s "https://fal.run/fal-ai/nano-banana-2" -H "Authorization: Key $FAL_KEY" -H "Content-Type: application/json" -d @/tmp/imagine_nano_payload.json -o /tmp/imagine_nano_resp.json & curl -s "https://fal.run/openai/gpt-image-2" -H "Authorization: Key $FAL_KEY" -H "Content-Type: application/json" -d @/tmp/imagine_gpt_payload.json -o /tmp/imagine_gpt_resp.json & wait) && NANO=$(node -p 'JSON.parse(require("fs").readFileSync("/tmp/imagine_nano_resp.json","utf-8")).images[0].url') && GPT=$(node -p 'JSON.parse(require("fs").readFileSync("/tmp/imagine_gpt_resp.json","utf-8")).images[0].url') && (curl -s "$NANO" -o generated/imagine_NAME_nano.png & curl -s "$GPT" -o generated/imagine_NAME_gpt.png & wait) && rm -f /tmp/imagine_nano_resp.json /tmp/imagine_gpt_resp.json /tmp/imagine_nano_payload.json /tmp/imagine_gpt_payload.json /tmp/imagine_prompt.txt
+```
+
+## both + edit
+
+Runs fal nano-banana-2/edit and fal gpt-image-2/edit in parallel. Substitute PROMPT, NAME, ASPECT, RESOLUTION, IMAGE_SIZE, PATH1/PATH2:
+
+```
+mkdir -p generated
+cat << 'PROMPTEOF' > /tmp/imagine_prompt.txt
+PROMPT
+PROMPTEOF
+node -e 'var fs=require("fs"),prompt=fs.readFileSync("/tmp/imagine_prompt.txt","utf-8").trim(),imgs=["PATH1","PATH2"],urls=imgs.map(function(p){return "data:image/"+p.split(".").pop()+";base64,"+fs.readFileSync(p).toString("base64")});fs.writeFileSync("/tmp/imagine_nano_payload.json",JSON.stringify({prompt:prompt,aspect_ratio:"ASPECT",resolution:"RESOLUTION",image_urls:urls}));fs.writeFileSync("/tmp/imagine_gpt_payload.json",JSON.stringify({prompt:prompt,image_urls:urls,image_size:"IMAGE_SIZE",quality:"high"}))' && (curl -s "https://fal.run/fal-ai/nano-banana-2/edit" -H "Authorization: Key $FAL_KEY" -H "Content-Type: application/json" -d @/tmp/imagine_nano_payload.json -o /tmp/imagine_nano_resp.json & curl -s "https://fal.run/openai/gpt-image-2/edit" -H "Authorization: Key $FAL_KEY" -H "Content-Type: application/json" -d @/tmp/imagine_gpt_payload.json -o /tmp/imagine_gpt_resp.json & wait) && NANO=$(node -p 'JSON.parse(require("fs").readFileSync("/tmp/imagine_nano_resp.json","utf-8")).images[0].url') && GPT=$(node -p 'JSON.parse(require("fs").readFileSync("/tmp/imagine_gpt_resp.json","utf-8")).images[0].url') && (curl -s "$NANO" -o generated/imagine_NAME_nano.png & curl -s "$GPT" -o generated/imagine_NAME_gpt.png & wait) && rm -f /tmp/imagine_nano_resp.json /tmp/imagine_gpt_resp.json /tmp/imagine_nano_payload.json /tmp/imagine_gpt_payload.json /tmp/imagine_prompt.txt
+```
+
 ## After the command completes
 
-Report the output path: `generated/imagine_{name}.png`
+Report the output path(s):
+- single model → `generated/imagine_{name}.png`
+- both → `generated/imagine_{name}_nano.png` and `generated/imagine_{name}_gpt.png`
 
 If the command failed, report the error. Do NOT retry.
+
+### Known caveat
+
+`gpt-image-2/edit` accepts `image_urls` per its schema, but the official examples only show HTTPS URLs. Data URIs may or may not be accepted — if you see an error like "invalid url" or "unable to fetch image" coming from the gpt-image-2 edit endpoint, surface it verbatim and stop. Do not attempt to upload reference images to a host as a workaround.

package/content/commands/imagine.md

@@ -14,13 +14,23 @@ $ARGUMENTS
 
 ## Instructions
 
-1. If no API key is available, stop and tell the user to set `GEMINI_API_KEY` or `FAL_KEY`.
+1. **API key check.** If no API key is available, stop and tell the user to set `GEMINI_API_KEY` or `FAL_KEY`.
 
-2. Determine `api`: "gemini" if GEMINI_API_KEY is available, "fal" otherwise.
+2. **Determine `model`** — one of `nano-banana-2`, `gpt-image-2`, or `both`. Resolve in this order; first match wins:
+   1. **Explicit flag** in `$ARGUMENTS`: `--model=nano-banana-2`, `--model=gpt-image-2`, or `--model=both`. Strip the flag from the prompt.
+   2. **Prefix**: `nano:`, `gpt:`, or `both:` at the start. Strip it.
+   3. **Natural language mention**: phrases like "with gpt-image-2", "use gpt image", "using gpt", "with nano banana", "using nano", "with both models", "compare both", "render with both". Map to the right model and remove the directive cleanly from the prompt.
+   4. **Auto-heuristic** — only if none of the above matched. Bias conservatively toward `nano-banana-2` since gpt-image-2 is materially more expensive on fal:
+      - **Strong text-rendering signals** → `gpt-image-2`. Only triggers when the user clearly wants legible text rendered: quoted strings the prompt asks to render (`"..."`, `'...'` paired with verbs like "that says", "with the words", "reading", "labeled"), or explicit "render this text", "billboard that reads", "sign that says", "headline:", "caption:", "infographic with text". Soft typography hints alone ("logo", "poster", "book cover", "magazine cover") do **not** trigger gpt — those go to nano.
+      - **Otherwise** → `nano-banana-2` (default — covers people, scenes, products, soft typography, and ambiguous cases).
 
-3. Check if the user included any image file paths. If yes, mode is "edit". If no, mode is "generate".
+3. **Determine `api`** based on `model`:
+   - `gpt-image-2` or `both` → `fal` (requires `FAL_KEY`; if missing, stop and tell the user).
+   - `nano-banana-2` → `gemini` if `GEMINI_API_KEY` is available, else `fal`.
 
-4. Determine `aspect_ratio` and `resolution`:
+4. **Mode**: if the user included any image file paths, `mode` is `edit`. Otherwise `generate`.
+
+5. **Determine `aspect_ratio` and `resolution`** (used by nano-banana-2; mapped to `image_size` preset by the agent for gpt-image-2):
    - If the user explicitly requests a size or ratio (e.g., "16:9", "square", "4K"), use that.
    - If the user describes where the image will be used, infer the best fit:
      - Hero banner / website header → `16:9`, `2K`
@@ -34,17 +44,21 @@ $ARGUMENTS
    - Valid aspect ratios: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`
    - Valid resolutions: `1K`, `2K`, `4K`
 
-5. Enhance the user's description into a detailed prompt (~100 words max). Add lighting, composition, camera angle, style, mood — stay faithful to the original request.
+6. Enhance the user's description into a detailed prompt (~100 words max). Add lighting, composition, camera angle, style, mood — stay faithful to the original request. Do NOT strip out text the user wants rendered in the image (quoted strings, headlines, etc.) — preserve it verbatim.
 
-6. Derive a short snake_case name (e.g., `mountain_cabin`).
+7. Derive a short snake_case name (e.g., `mountain_cabin`).
 
-7. Launch the imagine agent via Task tool with `subagent_type="imagine"` passing:
+8. Launch the imagine agent via Task tool with `subagent_type="imagine"` passing:
    - `prompt`: the enhanced prompt text
-   - `api`: "gemini" or "fal"
-   - `mode`: "generate" or "edit"
+   - `model`: `nano-banana-2`, `gpt-image-2`, or `both`
+   - `api`: `gemini` or `fal`
+   - `mode`: `generate` or `edit`
    - `name`: the snake_case name
-   - `aspect_ratio`: e.g., "16:9"
-   - `resolution`: e.g., "2K"
+   - `aspect_ratio`: e.g., `16:9`
+   - `resolution`: e.g., `2K`
    - `reference_images`: list of absolute file paths (if edit mode)
 
-8. After the agent returns, use the Read tool to display `generated/imagine_{name}.png` inline. Show the path.
+9. After the agent returns, display the output(s) inline with the Read tool:
+   - `model=nano-banana-2` or `gpt-image-2` → `generated/imagine_{name}.png`
+   - `model=both` → `generated/imagine_{name}_nano.png` AND `generated/imagine_{name}_gpt.png`
+   Show the path(s).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allthingsclaude/blueprints",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "Claude Code commands and agents for enhanced AI-assisted development workflows",
   "type": "module",
   "main": "dist/index.js",