rsc-universal 0.1.1

package/skills/replicate-images/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: replicate-images
+description: "Use when generating or editing images through the Replicate API, or when a modern image model keeps ignoring the prompt — running google/nano-banana-2, openai/gpt-image-1, Flux, or SeeDream from Node or Python, choosing aspect ratio, resolution, seed, and output format, doing image-to-image, multi-reference composition, or text-driven inpainting, and structuring prompts per model family. Triggers: 'replicate.run nano-banana-2', 'why does Flux ignore half my prompt', 'render readable text inside a generated product label', 'compose a product shot from two reference images', 'make the generation reproducible with a seed', 'generar y editar imágenes con la API de Replicate', 'per què Flux no segueix el prompt'. NOT general Replicate platform/auth/non-image models like LLMs or audio (that is replicate)."
+tags: [replicate, image-generation, image-editing, nano-banana, flux, prompting, gpt-image, seedream]
+recommends: [replicate, prompt-engineering, ai-media, fal]
+origin: risco
+---
+
+# Replicate image generation & prompt craft
+
+This skill is the **image layer on top of Replicate**: how to call an image model from code and how
+to write a prompt that the specific model family actually obeys. Two competencies braided together —
+**mechanics** (run path, output handling, levers, image inputs) and **prompt shape per family**
+(Gemini/Nano-Banana wants prose, Flux wants dense description, gpt-image wants instructions). If the
+question is platform plumbing — auth, billing, deployments, webhooks, running an LLM or audio model —
+that is `replicate`, not this skill.
+
+Pinned facts (verified 2026-06-02). Slugs and parameter names are the load-bearing details that make
+code run, and they drift — the full per-model schema lives in `references/models.md` so this file
+stays evergreen. Confirm any exact slug/param on the model page before quoting it as fact.
+
+## First move
+
+```bash
+export REPLICATE_API_TOKEN=r8_...     # both clients read this automatically
+npm install replicate                  # Node; pip install replicate for Python
+```
+
+```javascript
+import Replicate from "replicate";
+const replicate = new Replicate();     // reads REPLICATE_API_TOKEN from env
+
+const output = await replicate.run("google/nano-banana-2", {
+  input: { prompt: "a red ceramic mug on a sunlit wooden table, soft morning light" },
+});
+console.log(output[0].url());          // hosted URL of the first image
+```
+
+Rule: do not hand-build the token into the client — let `new Replicate()` read the env var. Why: a
+hardcoded token leaks into git and logs. Python is the same shape: `replicate.run("google/nano-banana-2", input={"prompt": ...})`.
+
+## Pick the model
+
+Pick by the dominant requirement, not by hype. Full input schemas and rough cost tiers per model are
+in `references/models.md`.
+
+| Need | Model slug | Why |
+|---|---|---|
+| Best editing + multi-image composition | `google/nano-banana-2` | Gemini 3.1 Flash Image; up to 14 reference images, conversational edits |
+| Top-quality / hard compositions, budget allows | `google/nano-banana-pro` | Gemini 3 Pro Image; ~2x the NB2 cost at 1K |
+| Dense photoreal, fine control of light/lens | `black-forest-labs/flux-1.1-pro` | rewards rich descriptive prompts; exposes seed, size |
+| Fast/cheap draft loop | `black-forest-labs/flux-schnell` | sync-optimized, lowest latency for iterating |
+| Strict instruction-following + crisp text | `openai/gpt-image-1` (OpenAI on Replicate) | follows complex instructions; needs your own OpenAI key wired in |
+| Up-to-4K + batch/sequential output | `bytedance/seedream-4` | unified text-to-image and editing, multi-reference |
+
+Rule: for anything involving editing an existing image or merging references, start at
+`google/nano-banana-2`. Why: it is purpose-built for semantic edits and accepts many reference images,
+which the Flux text-to-image models do not.
+
+## The three run paths
+
+```javascript
+// 1. run() — synchronous, the default. Use for interactive/script calls.
+const out = await replicate.run("google/nano-banana-2", { input: { prompt } });
+
+// 2. predictions.create + wait — when you need the full object (status, metrics, retry/cancel).
+const prediction = await replicate.predictions.create({
+  model: "black-forest-labs/flux-1.1-pro",
+  input: { prompt },
+});
+const done = await replicate.wait(prediction);   // done.output, done.status, done.metrics
+
+// 3. stream — progressive output for streaming-capable models.
+for await (const event of replicate.stream("black-forest-labs/flux-dev", { input: { prompt } })) {
+  process.stdout.write(event.data);              // { event, data }
+}
+```
+
+Rule: default to `run()`; reach for `predictions.create` + `wait` only when you actually read
+`status`/`metrics` or need to `cancel()`. Why: `run()` is the low-latency path optimized for file
+models — the extra object is overhead you do not need for a one-shot generation.
+
+## Handling output
+
+Since the file-output era, `replicate.run` returns **`FileOutput`** objects, not URL strings.
+Treating one as a string is the most common bug.
+
+```javascript
+const output = await replicate.run("google/nano-banana-2", { input: { prompt } });
+
+// Bad — output[0] is a FileOutput; this stringifies the object, not the image
+fs.writeFileSync("out.jpg", output[0]);
+
+// Good — read bytes via .blob(), or take the hosted link via .url()
+import { writeFile } from "node:fs/promises";
+const blob = await output[0].blob();
+await writeFile("out.jpg", Buffer.from(await blob.arrayBuffer()));
+console.log(output[0].url());                    // hosted URL if you'd rather link
+```
+
+`output` is an **array** even for a single image — index it. Pass `useFileOutput: false` to
+`new Replicate({ useFileOutput: false })` if you want plain URL strings back instead of `FileOutput`.
+
+Rule: index the array and call `.blob()` for bytes or `.url()` for the link. Why: silently coercing a
+`FileOutput` to a string writes a `[object]`-style repr and the corruption surfaces far from the cause.
+
+## Universal levers
+
+| Lever | What it does | Note |
+|---|---|---|
+| `aspect_ratio` | shape of the output (`"16:9"`, `"4:5"`, `"1:1"`, `match_input_image`, …) | nano-banana set listed in `references/models.md`; prefer it over `width`/`height` when offered |
+| `output_resolution` | `512px` / `1K` / `2K` / `4K` (nano-banana) | **the dominant cost lever** — see Cost discipline |
+| `output_format` | `jpg` (default) vs `png` | png for transparency / text crispness; jpg for smaller files |
+| `seed` | fixed integer → repeatable generation | use for A/B prompt diffs on Flux/SeeDream; Gemini image is less deterministic |
+| `num_outputs` | several variants in one call | where supported; multiplies cost |
+
+```javascript
+const out = await replicate.run("google/nano-banana-2", {
+  input: { prompt, aspect_ratio: "4:5", output_resolution: "1K", output_format: "png", seed: 42 },
+});
+```
+
+Rule: only pass parameters that exist on the model you call. Why: Replicate rejects unknown inputs —
+do not copy a Flux `width`/`height` onto a call that wants `aspect_ratio`, and do not invent a
+parameter. Allowed values per model are in `references/models.md`.
+
+## Image-to-image & editing
+
+Local files auto-upload, public URLs and `data:` URIs pass as strings. The single classic mistake is
+passing a **bare path string** for a local file — that uploads the literal text, not the bytes.
+
+```javascript
+import { readFile } from "node:fs/promises";
+
+// Bad — sends the string "./photo.jpg" as the image, not the file
+await replicate.run("google/nano-banana-2", { input: { prompt, image_input: ["./photo.jpg"] } });
+
+// Good — read the bytes (or pass a real https:// URL / data: URI string)
+const photo = await readFile("./photo.jpg");
+await replicate.run("google/nano-banana-2", {
+  input: {
+    prompt: "Remove the person on the left. Keep everything else identical.",
+    image_input: [photo],            // nano-banana takes up to 14 reference images
+    aspect_ratio: "match_input_image",
+  },
+});
+```
+
+For edits, write **what to change and what to preserve** in plain language — "keep everything else
+identical" is the idiom that stops the model from re-rendering the whole scene. Multi-image
+composition passes several references in `image_input` and describes how they combine. Copy-paste
+recipes (object removal, background swap, style transfer, 2-image composition, product shot with
+rendered text, character consistency) are in `references/editing-recipes.md`.
+
+Rule: never pass a bare local path as an image input. Why: clients only auto-upload file/Buffer
+values — a string is treated as a URL or literal, and the model silently generates from nothing.
+
+## Prompt structure per family
+
+Each family rewards a different prompt shape. Match the shape or the model "ignores" you.
+
+### Gemini / Nano-Banana — prose, not keywords
+
+Google's formula: **`[Subject] + [Action] + [Location/context] + [Composition] + [Style]`**, written
+as sentences. Editing is conversational and semantic. For text, put the literal string in quotes and
+name the font.
+
+```text
+Bad:  cat, hat, studio, 85mm, cinematic, 8k, highly detailed, trending
+Good: A ginger cat wearing a tiny red wool hat, sitting on a velvet stool in a
+      softly lit studio, shot from slightly above with a shallow depth of field,
+      warm cinematic color grade.
+```
+
+For a rendered label: `Add a banner reading "SUMMER SALE" in bold condensed sans-serif across the top`
+— quotes fix the literal text, the font name fixes the rendering. It can also translate text on request.
+
+### Flux — one dense descriptive paragraph
+
+Flux rewards a single rich paragraph weighting subject, lighting, and lens; thin prompts get filled
+in by the model. Use a fixed `seed` to A/B prompt edits.
+
+```text
+Bad:  a city at night, neon, rain
+Good: A rain-slicked Tokyo backstreet at night, neon signage reflected in the
+      puddles, a lone figure under a translucent umbrella, shot on a 35mm lens
+      with shallow focus and cool teal-magenta lighting.
+```
+
+### gpt-image — explicit instructions + constraints
+
+Write it like a brief with hard constraints; it follows complex instructions and renders readable
+text well. `Generate a 3-icon row on a white background; each icon flat-style, 2px stroke, evenly
+spaced; label them "Plan", "Build", "Ship" in a clean sans-serif.`
+
+### SeeDream — multi-reference and batch phrasing
+
+State the references and the relationship, and ask for the batch explicitly when you want a set:
+`Using image 1 as the character and image 2 as the outfit, generate 4 sequential poses, same lighting.`
+
+Rule: do not paste a keyword soup into a Gemini/Nano-Banana call. Why: these models parse natural
+language; a comma-list of tags reads as noise and the model drops half of it.
+
+## Cost & latency discipline
+
+- **Resolution is the cost lever.** For nano-banana, cost climbs sharply with `output_resolution`
+  (roughly: 0.5K cheapest → 1K default → 2K → 4K). Iterate at `1K`, render the chosen frame at `4K`.
+- **Do not 4K every draft.** A 20-iteration prompt loop at 4K can cost an order of magnitude more than
+  the same loop at 1K for output you are about to throw away.
+- **Pro tier ≈ 2x Flash at the same size** — reach for `nano-banana-pro` only when NB2 genuinely can't
+  do the job, not by default.
+- **Verify live pricing on the model page** before quoting a number to anyone — the figures here are
+  order-of-magnitude and Replicate may differ from upstream Google rates.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| Bare path string as an image input | Uploads the text, not the file; model generates from nothing | `await readFile(path)`, or a real URL / `data:` URI |
+| Keyword-soup prompt to Gemini/Nano-Banana | Parses as noise; half the request is dropped | Write the prose formula in sentences |
+| Treating `FileOutput` as a URL string | Writes an object repr, not the image bytes | Index the array, then `.blob()` / `.url()` |
+| 4K (or Pro) on every iteration | Multiplies cost on output you'll discard | Draft at 1K/Flash, render finals at 4K/Pro |
+| Inventing or copy-pasting parameters across models | Replicate rejects unknown inputs; the call 400s | Use only params from `references/models.md` |
+| Hardcoding a model version hash that rots | Pinned version gets deprecated; call breaks silently | Call by `owner/model` slug; pin a version only deliberately |
+| Quoting stale pricing as fact | Rates drift; you mis-quote a client | Re-check the model page; treat numbers as order-of-magnitude |
+| `run()` when you need metrics/retry | No access to status/metrics; can't cancel | `predictions.create` + `wait`, read `.status`/`.metrics` |
+
+## References
+
+- `references/models.md` — per-model slug, full input schema with allowed values, prompt shape,
+  pick-when, and rough cost tier for nano-banana-2, nano-banana-pro, flux-1.1-pro / flux-dev /
+  flux-schnell, openai/gpt-image-1, seedream-4. Header note: slugs and params drift — confirm on the model page.
+- `references/editing-recipes.md` — copy-paste recipes (object removal, background swap, style
+  transfer, 2-image composition, product shot with rendered text, character consistency), each as
+  goal + model + input shape + prompt template.
+
+`scripts/verify.sh` statically lints the Replicate image-calling code in **your project** — point it
+at a directory of emitted `.js`/`.mjs`/`.ts`/`.py` files (no network, no token). It checks that image
+slugs come from the allowlist, `aspect_ratio` literals are in the nano-banana set, `output_resolution`
+values are valid, and local image inputs use `readFile`/Buffer rather than a bare quoted path. It does
+not parse this skill's own Markdown fences — it scans source files, so run it where the code lands.

package/skills/replicate-images/evals/README.md

@@ -0,0 +1,13 @@
+# Evals — replicate-images
+
+`cases.yaml` is a trigger/routing and capability rubric, not an executable test of the Replicate API.
+`should_trigger` lists prompts (including a bug-framed one, a text-rendering one, a Spanish one, and a
+Catalan one) that must route here, so the non-English routing claimed in the description is actually tested; `should_not_trigger` lists near-miss prompts that must route to a named sibling
+(`replicate`, `prompt-engineering`, `fal`, `ai-media`) so the boundary against the platform skill and
+other providers stays sharp. The `capability` case is a scored rubric: give the scenario to an agent
+loaded with this skill and check the response covers every `must_include` item. Grade with whatever
+harness scores the skills repo — no Replicate token, GPU, or network call is needed. To exercise the
+checkable artifact, run `scripts/verify.sh` against a directory of generated image-calling code in a
+user's project (it scans `.js`/`.mjs`/`.ts`/`.py` source files, not Markdown, so it finds nothing
+inside this skill's own fences); it statically lints slugs, aspect ratios, resolutions, and
+image-input shapes without hitting the API.

package/skills/replicate-images/evals/cases.yaml

@@ -0,0 +1,41 @@
+skill: replicate-images
+
+should_trigger:
+  - prompt: "Write a Node script that generates a 16:9 hero image with google/nano-banana-2 and saves it."
+    why: "Core mechanics — run() call, aspect_ratio, FileOutput save; the most direct entry point."
+  - prompt: "My Flux images ignore half my prompt. How should I structure the prompt so it follows?"
+    why: "Non-obvious: framed as a bug, not 'generate' — routes to per-family prompt shape (dense paragraph)."
+  - prompt: "How do I edit an existing photo to remove a person using Replicate?"
+    why: "Image-to-image / text-driven inpainting with image_input and the 'keep everything else identical' idiom."
+  - prompt: "What aspect ratios and seed options does nano-banana-2 take, and how do I make a generation reproducible?"
+    why: "Universal levers — allowed aspect_ratio set, seed for reproducible A/B."
+  - prompt: "Generar y editar imágenes con la API de Replicate desde Node, eligiendo resolución y formato."
+    why: "Spanish trigger for the core image mechanics on Replicate."
+  - prompt: "How do I get a generated product label to show readable text 'SALE 20%' in a specific font?"
+    why: "Non-obvious text-rendering: quoted literal + named font, a family-specific prompt idiom."
+  - prompt: "Per què Flux no segueix el prompt i se salta la meitat del que li demano?"
+    why: "Catalan trigger (matches the description's Catalan phrasing); bug-framed, routes to per-family Flux prompt shape — exercises non-English routing, not just asserted in the description."
+
+should_not_trigger:
+  - prompt: "How do I run a Llama 3 LLM on Replicate and stream the tokens back?"
+    route_to: replicate
+    why: "Non-image model plus platform run mechanics — the platform layer, not image craft."
+  - prompt: "Help me tune the system prompt and few-shot examples for my GPT chatbot."
+    route_to: prompt-engineering
+    why: "Text-LLM prompt design, nothing to do with image models or Replicate image calls."
+  - prompt: "Generate images with fal.ai's flux endpoint instead of Replicate."
+    route_to: fal
+    why: "Different hosted-inference provider; this skill is Replicate-only for the run mechanics."
+  - prompt: "Build a pipeline that turns a script into a narrated video with background music."
+    route_to: ai-media
+    why: "Multi-modal media pipeline spanning audio and video, not single-image generation."
+
+capability:
+  - scenario: "Write a Node script that takes a product photo and a logo file, composes a 4:5 advertisement with the headline 'Summer Sale' rendered in a bold sans-serif font using nano-banana-2, and saves the result to disk."
+    must_include:
+      - "uses the correct slug google/nano-banana-2"
+      - "passes both images in an image_input array (fs.readFile/Buffer for local files, or URLs) — not bare path strings"
+      - "sets aspect_ratio: \"4:5\""
+      - "prompt puts the headline in quotes AND names the font (bold sans-serif)"
+      - "reads the FileOutput via .blob()/.url() and writes the bytes to disk (indexing the output array)"
+      - "does not invent unsupported parameters; only uses inputs that exist on the model"

package/skills/replicate-images/references/editing-recipes.md

@@ -0,0 +1,129 @@
+# Editing & composition recipes
+
+Copy-paste starting points. Each = goal + model + input shape + prompt template. Default to
+`google/nano-banana-2` for edits and composition; swap in `nano-banana-pro` when fidelity matters.
+Pass local files as bytes (`await readFile(path)`), never as a bare path string. See `models.md` for
+the full input schema and allowed `aspect_ratio` / `output_resolution` values.
+
+```javascript
+import Replicate from "replicate";
+import { readFile, writeFile } from "node:fs/promises";
+const replicate = new Replicate();
+
+async function save(output, path) {
+  const blob = await output[0].blob();
+  await writeFile(path, Buffer.from(await blob.arrayBuffer()));
+}
+```
+
+---
+
+## 1. Object / person removal
+
+Model: `google/nano-banana-2`. Input: one source image + edit prompt; keep the rest intact.
+
+```javascript
+const src = await readFile("./scene.jpg");
+const out = await replicate.run("google/nano-banana-2", {
+  input: {
+    prompt: "Remove the person standing on the left. Keep everything else identical, "
+          + "including the lighting and the shadows on the ground.",
+    image_input: [src],
+    aspect_ratio: "match_input_image",
+  },
+});
+await save(out, "scene-clean.jpg");
+```
+
+Idiom: name what to remove **and** "keep everything else identical" so the model edits rather than
+re-renders the whole frame.
+
+---
+
+## 2. Background swap
+
+Model: `google/nano-banana-2`. Input: subject image + description of the new background.
+
+```text
+prompt: "Replace the background with a softly blurred sunlit beach at golden hour.
+         Keep the subject, their pose, and the rim lighting on their hair unchanged."
+image_input: [subject]
+```
+
+---
+
+## 3. Style transfer
+
+Model: `google/nano-banana-2` (or `flux-1.1-pro` for painterly looks). Input: content image + a
+described target style (or a style reference image).
+
+```text
+prompt: "Re-render this photo in the style of a 1960s screen-printed travel poster:
+         flat color blocks, limited palette, bold outlines. Preserve the composition."
+image_input: [content]
+```
+
+For a reference-driven style, pass both images and say which is content and which is style.
+
+---
+
+## 4. Two-image composition
+
+Model: `google/nano-banana-2`. Input: two (up to 14) references in `image_input`; describe how they
+combine.
+
+```javascript
+const product = await readFile("./bottle.png");
+const scene   = await readFile("./kitchen.jpg");
+const out = await replicate.run("google/nano-banana-2", {
+  input: {
+    prompt: "Place the bottle from image 1 on the kitchen counter from image 2, "
+          + "matching the scene's warm lighting and adding a soft contact shadow.",
+    image_input: [product, scene],
+    aspect_ratio: "4:5",
+    output_resolution: "2K",
+  },
+});
+await save(out, "composite.jpg");
+```
+
+---
+
+## 5. Product shot with rendered text
+
+Model: `google/nano-banana-2` or `openai/gpt-image-1` (both render readable text). Quote the literal string,
+name the font.
+
+```javascript
+const photo = await readFile("./product.jpg");
+const logo  = await readFile("./logo.png");
+const out = await replicate.run("google/nano-banana-2", {
+  input: {
+    prompt: "Compose a 4:5 advertisement: the product from image 1 centered on a clean "
+          + "gradient background, the logo from image 2 in the top-left corner, and a "
+          + "headline reading \"Summer Sale\" in bold sans-serif across the bottom.",
+    image_input: [photo, logo],
+    aspect_ratio: "4:5",
+    output_format: "png",
+  },
+});
+await save(out, "ad.png");
+```
+
+Idiom: literal text in quotes fixes the characters; the named font fixes the rendering style.
+
+---
+
+## 6. Character consistency across images
+
+Model: `google/nano-banana-2` (or `bytedance/seedream-4` for batches). Input: one or more reference
+images of the character; restate the identity each call.
+
+```text
+prompt: "Using the character in the reference image, generate the same person now sitting
+         at a cafe table reading a book. Keep the face, hairstyle, and outfit identical."
+image_input: [character]
+```
+
+For a coherent set, prefer SeeDream's batch/sequential generation and ask for N poses with the same
+lighting in one call.

package/skills/replicate-images/references/models.md

@@ -0,0 +1,131 @@
+# Image model reference (Replicate)
+
+Verified 2026-06-02. **Slugs and parameter names drift.** Treat this table as a starting point and
+confirm the exact input schema and allowed values on the model page (`replicate.com/<owner>/<model>`)
+before relying on a parameter. Pricing figures are order-of-magnitude upstream rates; Replicate may
+mark up — re-check the model page before quoting a number.
+
+---
+
+## google/nano-banana-2 — Gemini 3.1 Flash Image
+
+Google's fast image generation + editing model (announced 2026-02-26): Pro-level quality at Flash
+speed and price. Best default for editing and multi-image composition.
+
+Identity corroboration (two independent sources, since the slug and "Gemini 3.1 Flash Image" tie are
+load-bearing for the whole skill): the live Replicate model page `replicate.com/google/nano-banana-2`
+(fetched 2026-06-02) states verbatim "Nano Banana 2 is Google's latest image generation model, built
+on Gemini 3.1 Flash Image" — confirming both the slug and the underlying model. This matches the
+2026-02-26 google blog announcement and the Google Cloud model docs
+(`docs.cloud.google.com/gemini-enterprise-agent-platform/models/gemini/3-1-flash-image`). If the model
+page no longer resolves or names a different base model, treat the slug below as drifted and re-verify.
+
+Inputs:
+- `prompt` — string, prose (see prompt shape).
+- `image_input` — array of up to **14** reference images for editing/composition. Each entry is a
+  file/Buffer (auto-uploaded), an `https://` URL string, or a `data:` URI string.
+- `aspect_ratio` — one of: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`,
+  `match_input_image`. (The model page's prose mentions extreme `1:4`/`4:1`/`1:8`/`8:1` ratios as
+  "new", but the formal aspect-ratio spec lists only the set above — treat the extremes as unconfirmed
+  and verify on the model page before using one.)
+- `output_format` — `jpg` (default) or `png`.
+- `output_resolution` — `512px`, `1K` (default), `2K`, `4K`.
+
+Prompt shape: prose, `[Subject] + [Action] + [Location/context] + [Composition] + [Style]`. Edits are
+conversational ("Remove X. Keep everything else identical."). Text: literal string in quotes + named
+font; can translate text.
+
+Cost (relative tiers, not exact dollars): per-image price climbs with resolution — `512px` cheapest
+→ `1K` (default) → `2K` → `4K` dearest, with the high tiers costing several times the low tier.
+Resolution dominates cost. As of the 2026-06-02 fetch the model page `replicate.com/google/nano-banana-2`
+shows **no fixed per-image dollar block** — this skill deliberately states tiers, not dollars, because
+the only exact figures circulating are on non-authoritative aggregators. Read the live "Pricing" block
+on the model page (authoritative) before quoting any number; do not lift a dollar figure from a blog.
+
+Pick when: editing an existing image, merging multiple references, or rendering text in a layout.
+
+---
+
+## google/nano-banana-pro — Gemini 3 Pro Image
+
+Higher-quality sibling of NB2 for hard compositions and maximum fidelity.
+
+Inputs: same shape as nano-banana-2 (`prompt`, `image_input`, `aspect_ratio`, `output_format`,
+`output_resolution`) — confirm exact set on the model page.
+
+Cost: roughly **2x** NB2 at the same resolution (relative tier only, not an exact dollar figure —
+confirm on the model page's live pricing block; do not quote a per-image dollar amount from a blog).
+
+Pick when: NB2 genuinely can't nail the composition/quality and the budget allows. Not the default.
+
+---
+
+## black-forest-labs/flux-1.1-pro
+
+Flux flagship with strong control over style, lighting, and composition.
+
+Inputs (confirm on model page):
+- `prompt` — dense single-paragraph description.
+- `aspect_ratio` and/or `width` / `height`.
+- `seed` — integer for reproducibility.
+- `output_format` — `jpg` / `png` / `webp` depending on the model.
+
+Prompt shape: one rich paragraph weighting subject + lighting + lens. Thin prompts get auto-filled.
+
+Pick when: dense photoreal with fine control of light/lens; A/B prompt iteration via fixed `seed`.
+
+---
+
+## black-forest-labs/flux-dev
+
+Open-weight Flux for general text-to-image; supports `seed`, `aspect_ratio`/`width`/`height`,
+`output_format`, and `num_outputs` where applicable. Streaming-capable in the JS client.
+
+Pick when: a balance of quality and cost without the Pro premium.
+
+---
+
+## black-forest-labs/flux-schnell
+
+Fastest, cheapest Flux; listed as sync-optimized in the JS client README.
+
+Pick when: rapid draft loops and previews. Render finals on a higher-quality model.
+
+---
+
+## openai/gpt-image-1 (OpenAI on Replicate)
+
+OpenAI's image model exposed on Replicate. Follows complex instructions and renders readable text
+well; usable as an editor. **Requires an OpenAI key wired into the Replicate model.**
+
+Prompt shape: instructional brief with explicit constraints (layout, stroke, spacing, labels).
+
+Pick when: strict instruction-following or crisp readable text matters more than photoreal style.
+
+---
+
+## bytedance/seedream-4 — Seedream 4.0
+
+Unified text-to-image + editing; up to 4K; multi-reference and batch/sequential generation. (Seedream
+4.5 exists upstream — check the model page for the current Replicate version.)
+
+Inputs (confirm exact names on the model page): `prompt`, `size` (resolution), `image_input`
+(references), `max_images` / `sequential_image_generation` for batches, `seed`.
+
+Prompt shape: state the references and their relationship; ask for the batch count explicitly.
+
+Pick when: you need up-to-4K output or a coherent batch/sequence from references.
+
+---
+
+## Slug allowlist (used by scripts/verify.sh)
+
+```text
+google/nano-banana-2
+google/nano-banana-pro
+black-forest-labs/flux-1.1-pro
+black-forest-labs/flux-dev
+black-forest-labs/flux-schnell
+openai/gpt-image-1
+bytedance/seedream-4
+```