Nanogen

• keyResolved: true → proceed. keySource tells you where the key came from (env:GEMINI_API_KEY, env:GOOGLE_API_KEY, or a .env path).
• keyResolved: false → STOP. Point the user to reports/nanogen-api-key-setup.md, which covers getting a key and putting it in .env at the repo root.

Do NOT use printenv GEMINI_API_KEY as the preflight — it ONLY reads shell-exported env vars and misses the documented setup workflow (key in .env, not exported). The CLI's own resolver walks .env files, so the dry-run probe is the authoritative check.

If the user gets stuck on E_MISSING_API_KEY, do not retry blindly — the CLI fails fast and gives no interactive prompt. Point them at the setup doc and wait for them to add the key.

1. Two modes

The CLI has exactly two modes, selected by whether any --image flag is present:

• Generate mode — no --image. Text-to-image. --prompt is required.
• Edit mode — one or more --image (up to 14). Either --prompt or --region must be supplied (or both).

Decision tree:

• User already has an image they want modified? → Edit mode (--image <path> + describe the change in --prompt or --region).
• User wants a new image from a description alone? → Generate mode (--prompt "..." --output out.png).

Output format is determined by the extension of --output: .png, .jpg/.jpeg, or .webp.

2. Picking styles

The catalog has 72 preset slugs across 10 categories: pixel-art, flat-vector, painterly, drawing-ink, photographic, animation-cartoon, fine-art-historical, game-style, design-technical, speculative-niche. See reference.md for the full catalog.

Rules:

1. Skim the 10-category summary in reference.md.
2. Match user intent to 1–3 relevant categories.
3. Pick 1–2 style slugs (rarely more — excessive stacking produces muddy output).
4. If the user's request is already highly specified ("photorealistic studio shot of X with 85mm f/1.4 lens"), default to no style — the prompt itself is doing the work.

Pass styles via --style <slug> (repeatable). Each resolves to a preset prompt fragment appended as Style: ... to the base text.

3. Asset-type defaults

When the user invokes /nanogen without a --output path, infer an asset type from the request, then pick defaults for (a) output path, (b) model, (c) aspect, (d) size, (e) style hints.

Output path convention

Route outputs into assets/<category>/<slug>.<ext> under the caller's cwd. Mirrors imagegen's layout so repos that use both skills stay tidy. The CLI's fs.mkdirSync(..., {recursive: true}) handles missing subdirectories automatically when you pass a nested --output.

Rules for <slug>:

• Derive from the user's description: lowercase, kebab-case, ≤ 40 chars. Example: "a 16-bit warrior with a huge sword" → warrior-16bit-huge-sword or warrior-16bit.
• If the user already supplied a file path in --output, honor it verbatim. Do not reroute into assets/.
• If the user asked for a specific directory ("save it in /tmp"), honor that.

Rules for <ext> — important for Gemini's real output behavior:

• Prefer .jpg for pixel-art, flat-vector, design-technical, animation-cartoon, drawing-ink, photographic, and painterly output. Gemini predominantly returns JPEG bytes for image requests regardless of the filename we pass. Naming the output .jpg up-front means the CLI's ext-vs-returned-MIME warning doesn't fire and the file doesn't need renaming after.
• Reserve .png for cases where the user explicitly asks for PNG (and accept that Gemini may still return JPEG bytes, triggering a stderr warning and a follow-up rename).
• .webp is available if the user asks; rare.

Model / aspect / size defaults

Text-in-image rendered below 2K is frequently garbled; if the user wants readable text in the image, default to 2K+ and --thinking high.

4. Iteration verbs

Map user intent → CLI action:

History ids come from .nanogen-history.jsonl in the caller's cwd (one JSONL row per successful or refused invocation). --history-continue is exactly one turn deep; longer chains happen by continuing from the newly-created row.

5. Refusal recovery

On exit 1 with code=E_REFUSED or code=E_CONTENT_POLICY:

• Do NOT retry the same prompt. The model already declined; identical text will decline again.
• Rephrase away from the flagged concept. Common triggers: named real people, violent subjects, copyrighted characters, real public figures, minors in sensitive contexts.
• Tell the user what you changed and why. Transparency matters — don't silently swap in a watered-down prompt.

Mixed IMAGE+TEXT output is sometimes returned as a pure-text refusal even when the user expects pixels; same recovery applies.

6. Error code reference

One-line recovery hints. Longer root-cause paragraphs live in reference.md. Grouped by category.

Arg validation

Env

Continuation

HTTP

7. Multi-turn editing (--history-continue)

Use --history-continue <id> to iteratively refine a prior generation. The CLI round-trips the prior entry's thoughtSignature automatically — this signature must be byte-for-byte identical to what Gemini returned last time, or the API rejects the follow-up with a 400. nanogen handles this correctly; do not try to reconstruct the signature by hand.

--history-continue vs --history-parent:

• --history-continue <id> sends a full two-turn conversation (prior user prompt + prior model output + your new prompt). The model can directly refine its prior image.
• --history-parent <id> is a metadata link only — the prior row is not replayed; it just records that this generation is a child of the parent row for history bookkeeping.

Continuation is exactly one step deep. For longer chains, continue from the newly-created row each turn.

If the prior row was generated with a different --model, nanogen will warn on stderr and continue anyway. Gemini may 400 on format mismatch — if it does, re-run with the original model.

8. Cost awareness

Rule of thumb: 10 images at pro-4K is ≈ $2.40. Favor flash-3.1 at 1K for iteration; escalate to pro for finals or text-heavy output.

9. SynthID

Every image produced by the Gemini image API carries an invisible Google SynthID watermark embedded in the pixel data. This is NOT the visible logo overlay that the consumer Gemini app adds — API outputs have no visible overlay. The watermark identifies images as Gemini-generated and cannot be disabled through the CLI. It survives light editing but can be degraded by aggressive re-encoding. Assume any image produced via this skill is identifiable as AI-generated.

10. Troubleshooting pointers

When things go wrong, consult the matching section in reference.md:

• Text in the image is garbled. reference.md → "Known gotchas" — upgrade to 2K+ with --thinking high.
• Model switching mid-conversation 400s. reference.md → "Pinned stderr-warning strings" (the model-mismatch warning) + "Known gotchas" (thoughtSignature is per-model).
• The image has white bars / was centered in a non-square canvas. reference.md → "Aspect ratio guidance".
• Region edit did the wrong part of the image. reference.md → Asset templates / region phrasing tips; Gemini has no bitmap mask, so prose must be spatially unambiguous.
• Refusals that feel over-broad. reference.md → "Error code reference" (E_REFUSED / E_CONTENT_POLICY root causes).