imgx-mcp 1.5.1 → 1.6.1

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 1.6.1 (2026-03-24)
+
+### Added
+
+- **README badges** — npm version, npm downloads, Cursor Directory, MIT license
+- **"What sets imgx-mcp apart" section** — highlights context-aware prompt optimization, 24 editing techniques, and session management with undo/redo
+- **Cursor Directory link** in README Links section
+
+### Changed
+
+- **Description updated** across package.json, server.json, plugin configs — now emphasizes context-aware prompt optimization, bundled editing techniques, and session undo/redo
+- **Listed on Cursor Directory** — https://cursor.directory/plugins/imgx-mcp
+
+## 1.6.0 (2026-03-06)
+
+### Added
+
+- **`gemini-2.5-flash-image` (Nano Banana)** — re-added as the only Gemini image model with a **free tier** (10 RPM / 500 RPD, no credit card required). Max 1024×1024, 7 aspect ratios. Ideal entry point for users without paid API access
+- **`gpt-image-1.5`** — OpenAI's latest image model. ~4x faster, 20% cheaper than gpt-image-1, improved text rendering and editing precision. Same API, drop-in replacement
+- **`gpt-image-1-mini`** — Budget OpenAI model at $0.005–$0.036/image. Same API compatibility
+- **`background` parameter** — `transparent`, `opaque`, or `auto` (OpenAI only). Available on `generate_image`, `edit_image`, and `edit_last` MCP tools, and as `--background` / `-b` CLI flag. Use `transparent` for icons, logos, and stickers with transparent PNG/WebP output
+- **`quality` parameter** — `low`, `medium`, `high`, or `auto` (OpenAI only). Direct quality control that overrides the resolution-based mapping. Available on all MCP tools and as `--quality` / `-q` CLI flag
+- **Viral style templates** — Ghibli, action figure, 3D clay, pixel art, and more in SKILL.md
+- **Specialized use case guides** — Icon set generation, seamless patterns, technical diagrams, story sequences with character consistency
+- **Multi-image consistency techniques** — Design token approach, character DNA template, style reference chains
+- **Platform size guide** — Recommended aspect ratios and resolutions for social media, OGP, app stores, print, and blog platforms
+- **Model aliases** — Nano Banana Pro, Nano Banana 2, Nano Banana, GPT Image 1.5, GPT Image Mini (+ Japanese variants) mapped in Skill for natural language model selection
+
+### Changed
+
+- **Default model changed to free tier** — `gemini-2.5-flash-image` (Nano Banana) is now the default model. Users start free (500 images/day, no credit card), and can upgrade to paid models (Nano Banana 2, Nano Banana Pro) when they need higher quality, 4K resolution, or extended aspect ratios
+- **Gemini 3.1 Flash model added** — `gemini-3.1-flash-image-preview` (Nano Banana 2) as paid alternative. Supports 4K resolution and 14 aspect ratios
+- **SKILL.md rewritten** — added detailed model specs (3 Gemini + 3 OpenAI), model selection guide, 9 use case templates (including transparent background), 24 editing techniques, prompt enhancement guide (Subject-Context-Style framework), and refinement patterns
+- **providers.md rewritten** — 3-model comparison table with per-model capabilities
+
 ## 1.5.1 (2026-03-05)
 
 ### Fixed

package/README.md

@@ -1,9 +1,20 @@
 # imgx-mcp
 
+[![npm version](https://img.shields.io/npm/v/imgx-mcp)](https://www.npmjs.com/package/imgx-mcp)
+[![npm downloads](https://img.shields.io/npm/dw/imgx-mcp)](https://www.npmjs.com/package/imgx-mcp)
+[![Cursor Directory](https://img.shields.io/badge/Cursor_Directory-listed-blue)](https://cursor.directory/plugins/imgx-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](https://opensource.org/licenses/MIT)
+
 AI image generation and editing MCP server. Works with Claude Code, Gemini CLI, Cursor, Windsurf, and any MCP-compatible tool.
 
 Generate images from text, edit existing images with text instructions, iterate on results — all from your AI coding environment.
 
+### What sets imgx-mcp apart
+
+- **No prompt engineering** — Your AI agent keeps conversation context and auto-constructs optimized prompts. Say what you need; the agent handles prompt structure, model selection, and platform-specific sizing
+- **24 editing techniques built in** — Atmosphere, composition, style transfer, element manipulation, and trending styles — bundled as a Skill your agent applies on demand
+- **Session management with undo/redo** — Edit iteratively, step back to any point, branch off, or switch between parallel sessions — version control for images
+
 ## Quick start
 
 Add to your tool's MCP config (`.mcp.json`, `settings.json`, etc.):
@@ -70,9 +81,18 @@ Claude Desktop supports skills via ZIP upload:
 
 > Update the skill by re-downloading and re-uploading the ZIP after new releases.
 
-### What the skill does
+### What the Skill brings
+
+The MCP server gives the AI the *ability* to generate and edit images. The Skill adds the *knowledge* of how to use those tools well — so you don't need to learn prompt syntax, model specifications, or service-specific parameters.
+
+- **Automatic prompt construction** — Say "I need a cover image." The AI builds a structured prompt using the Subject-Context-Style framework: what to show, where to place it, how it should look
+- **24 editing techniques** — Atmosphere adjustment, composition changes, element manipulation, style transfer. "Make it warmer" or "add depth of field" — the AI selects the right instruction for the model
+- **Intelligent model selection** — Starts with the free model. Suggests paid upgrades only when your needs exceed free tier capabilities, and explains what changes
+- **Platform-aware sizing** — "Twitter OGP" or "App Store screenshot" — the AI picks the correct aspect ratio and resolution. Covers social media, OGP, app stores, print, and blog platforms
+- **Trending style templates** — Ghibli, action figure in box, 3D clay, pixel art, chibi, and more. Name the style and the AI applies the right prompt structure
+- **Multi-image consistency** — Design tokens and character DNA templates maintain visual coherence across slide decks, social media series, and brand assets
 
-The skill guides Claude Code through image workflows: blog covers, iterative editing, provider comparison, icon generation. It knows the MCP tool parameters and best practices, so you get better results with less effort.
+The image generation models already have these capabilities. The Skill is what makes them accessible without specialized knowledge.
 
 ### MCP server vs Skill
 
@@ -157,7 +177,7 @@ edit_last                  → imgx-a1b2c3d4-1.png
 
 Set up at least one provider:
 
-**Gemini** — get a key from [Google AI Studio](https://aistudio.google.com/apikey) (free tier available):
+**Gemini** — get a key from [Google AI Studio](https://aistudio.google.com/apikey) (free tier available for `gemini-2.5-flash-image`):
 
 ```bash
 imgx config set api-key YOUR_GEMINI_API_KEY --provider gemini
@@ -277,8 +297,8 @@ The same `npx` pattern works with Cursor, Windsurf, Continue.dev, Cline, Zed, an
 
 | Provider | Models | Capabilities |
 |----------|--------|-------------|
-| Gemini | `gemini-3-pro-image-preview`, `gemini-2.5-flash-image` | Generate, edit, aspect ratio, resolution, reference images, person control |
-| OpenAI | `gpt-image-1` | Generate, edit, aspect ratio, multi-output, output format (PNG/JPEG/WebP) |
+| Gemini | `gemini-2.5-flash-image` (Nano Banana — **free tier**, default), `gemini-3-pro-image-preview` (Nano Banana Pro), `gemini-3.1-flash-image-preview` (Nano Banana 2) | Generate, edit, aspect ratio (up to 14 ratios), resolution (up to 4K), reference images, person control |
+| OpenAI | `gpt-image-1`, `gpt-image-1.5` (faster, 20% cheaper), `gpt-image-1-mini` (budget) | Generate, edit, aspect ratio, multi-output, output format (PNG/JPEG/WebP), background transparency |
 
 ## Architecture
 
@@ -360,10 +380,12 @@ imgx capabilities       # Detailed capabilities of current provider
 | `--output` | `-o` | Output file path (auto-generated if omitted) |
 | `--input` | `-i` | Input image to edit (`edit` command only) |
 | `--last` | `-l` | Use last output as input (`edit` command only) |
-| `--aspect-ratio` | `-a` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` |
+| `--aspect-ratio` | `-a` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` + Gemini 3.x: `1:4`, `1:8`, `4:1`, `4:5`, `5:4`, `8:1`, `21:9` |
 | `--resolution` | `-r` | `1K`, `2K`, `4K` |
 | `--count` | `-n` | Number of images to generate |
 | `--format` | `-f` | Output format: `png`, `jpeg`, `webp` (OpenAI only) |
+| `--background` | `-b` | Background: `transparent`, `opaque`, `auto` (OpenAI only) |
+| `--quality` | `-q` | Quality: `low`, `medium`, `high`, `auto` (OpenAI only) |
 | `--model` | `-m` | Model name |
 | `--provider` | | Provider name (default: `gemini`) |
 | `--output-dir` | `-d` | Output directory |
@@ -503,6 +525,7 @@ MIT — [SOMA COFFEE KYOTO](https://github.com/somacoffeekyoto)
 - [Official page](https://somacoffee.net/imgx-mcp/)
 - [GitHub](https://github.com/somacoffeekyoto/imgx-mcp)
 - [npm](https://www.npmjs.com/package/imgx-mcp)
+- [Cursor Directory](https://cursor.directory/plugins/imgx-mcp)
 - [MCP Registry](https://registry.modelcontextprotocol.io)
 - [SOMA COFFEE KYOTO](https://somacoffee.net)
 - [X (@somacoffeekyoto)](https://x.com/somacoffeekyoto)

package/dist/cli.bundle.js

@@ -39527,8 +39527,12 @@ var Capability;
 // build/providers/gemini/capabilities.js
 var GEMINI_PROVIDER_INFO = {
   name: "gemini",
-  models: ["gemini-3-pro-image-preview", "gemini-2.5-flash-image"],
-  defaultModel: "gemini-3-pro-image-preview",
+  models: [
+    "gemini-3-pro-image-preview",
+    "gemini-3.1-flash-image-preview",
+    "gemini-2.5-flash-image"
+  ],
+  defaultModel: "gemini-2.5-flash-image",
   capabilities: /* @__PURE__ */ new Set([
     Capability.TEXT_TO_IMAGE,
     Capability.ASPECT_RATIO,
@@ -39539,12 +39543,19 @@ var GEMINI_PROVIDER_INFO = {
   ]),
   aspectRatios: [
     "1:1",
+    "1:4",
+    "1:8",
     "2:3",
     "3:2",
     "3:4",
+    "4:1",
     "4:3",
+    "4:5",
+    "5:4",
+    "8:1",
     "9:16",
-    "16:9"
+    "16:9",
+    "21:9"
   ],
   resolutions: ["1K", "2K", "4K"]
 };
@@ -39646,7 +39657,7 @@ import { readFileSync as readFileSync4 } from "node:fs";
 // build/providers/openai/capabilities.js
 var OPENAI_PROVIDER_INFO = {
   name: "openai",
-  models: ["gpt-image-1"],
+  models: ["gpt-image-1", "gpt-image-1.5", "gpt-image-1-mini"],
   defaultModel: "gpt-image-1",
   capabilities: /* @__PURE__ */ new Set([
     Capability.TEXT_TO_IMAGE,
@@ -39734,8 +39745,9 @@ var OpenAIProvider = class {
           prompt: input.prompt,
           n: input.count || 1,
           size: mapSize(input.aspectRatio),
-          quality: mapQuality(input.resolution),
-          ...input.outputFormat ? { output_format: input.outputFormat } : {}
+          quality: input.quality || mapQuality(input.resolution),
+          ...input.outputFormat ? { output_format: input.outputFormat } : {},
+          ...input.background ? { background: input.background } : {}
         })
       });
       const json = await response.json();
@@ -39763,8 +39775,9 @@ var OpenAIProvider = class {
       prompt: input.prompt,
       n: String(input.count || 1),
       size: mapSize(input.aspectRatio),
-      quality: mapQuality(input.resolution),
-      ...input.outputFormat ? { output_format: input.outputFormat } : {}
+      quality: input.quality || mapQuality(input.resolution),
+      ...input.outputFormat ? { output_format: input.outputFormat } : {},
+      ...input.background ? { background: input.background } : {}
     };
     const { body, contentType: ct } = buildMultipart(fields, [
       {
@@ -39865,7 +39878,9 @@ async function runGenerate(provider, args) {
     aspectRatio: args.aspectRatio,
     count: args.count,
     resolution: args.resolution,
-    outputFormat: args.outputFormat
+    outputFormat: args.outputFormat,
+    background: args.background,
+    quality: args.quality
   }, args.model);
   if (!result.success || result.images.length === 0) {
     fail(result.error || "Generation failed");
@@ -39904,7 +39919,9 @@ async function runEdit(provider, args) {
     prompt: args.prompt,
     aspectRatio: args.aspectRatio,
     resolution: args.resolution,
-    outputFormat: args.outputFormat
+    outputFormat: args.outputFormat,
+    background: args.background,
+    quality: args.quality
   }, args.model);
   if (!result.success || result.images.length === 0) {
     fail(result.error || "Edit failed");
@@ -40293,7 +40310,7 @@ function runRedo() {
 }
 
 // build/cli/index.js
-var VERSION2 = "1.5.1";
+var VERSION2 = "1.6.1";
 var HELP = `imgx v${VERSION2} \u2014 AI image generation and editing for MCP-compatible AI agents
 
 Commands:
@@ -40322,6 +40339,8 @@ Options:
   -n, --count <number>       Number of images to generate
   -r, --resolution <size>    Resolution: 1K, 2K, 4K
   -f, --format <type>        Output format: png, jpeg, webp (OpenAI only)
+  -b, --background <type>    Background: transparent, opaque, auto (OpenAI only)
+  -q, --quality <level>      Quality: low, medium, high, auto (OpenAI only)
   -m, --model <model>        Model name
   --provider <name>          Provider: gemini, openai (default: gemini)
   -d, --output-dir <dir>     Output directory
@@ -40411,6 +40430,8 @@ function main() {
       count: { type: "string", short: "n" },
       resolution: { type: "string", short: "r" },
       format: { type: "string", short: "f" },
+      background: { type: "string", short: "b" },
+      quality: { type: "string", short: "q" },
       model: { type: "string", short: "m" },
       provider: { type: "string" },
       "output-dir": { type: "string", short: "d" },
@@ -40447,6 +40468,8 @@ function main() {
     aspectRatio: values["aspect-ratio"] || resolveDefault("aspectRatio") || void 0,
     resolution: values.resolution || resolveDefault("resolution") || void 0,
     outputFormat: values.format || void 0,
+    background: values.background || void 0,
+    quality: values.quality || void 0,
     model,
     count: values.count ? parseInt(values.count, 10) : void 0
   };

package/dist/mcp.bundle.js

@@ -69664,8 +69664,12 @@ var Capability;
 // build/providers/gemini/capabilities.js
 var GEMINI_PROVIDER_INFO = {
   name: "gemini",
-  models: ["gemini-3-pro-image-preview", "gemini-2.5-flash-image"],
-  defaultModel: "gemini-3-pro-image-preview",
+  models: [
+    "gemini-3-pro-image-preview",
+    "gemini-3.1-flash-image-preview",
+    "gemini-2.5-flash-image"
+  ],
+  defaultModel: "gemini-2.5-flash-image",
   capabilities: /* @__PURE__ */ new Set([
     Capability.TEXT_TO_IMAGE,
     Capability.ASPECT_RATIO,
@@ -69676,12 +69680,19 @@ var GEMINI_PROVIDER_INFO = {
   ]),
   aspectRatios: [
     "1:1",
+    "1:4",
+    "1:8",
     "2:3",
     "3:2",
     "3:4",
+    "4:1",
     "4:3",
+    "4:5",
+    "5:4",
+    "8:1",
     "9:16",
-    "16:9"
+    "16:9",
+    "21:9"
   ],
   resolutions: ["1K", "2K", "4K"]
 };
@@ -69787,7 +69798,7 @@ import { readFileSync as readFileSync4 } from "node:fs";
 // build/providers/openai/capabilities.js
 var OPENAI_PROVIDER_INFO = {
   name: "openai",
-  models: ["gpt-image-1"],
+  models: ["gpt-image-1", "gpt-image-1.5", "gpt-image-1-mini"],
   defaultModel: "gpt-image-1",
   capabilities: /* @__PURE__ */ new Set([
     Capability.TEXT_TO_IMAGE,
@@ -69875,8 +69886,9 @@ var OpenAIProvider = class {
           prompt: input.prompt,
           n: input.count || 1,
           size: mapSize(input.aspectRatio),
-          quality: mapQuality(input.resolution),
-          ...input.outputFormat ? { output_format: input.outputFormat } : {}
+          quality: input.quality || mapQuality(input.resolution),
+          ...input.outputFormat ? { output_format: input.outputFormat } : {},
+          ...input.background ? { background: input.background } : {}
         })
       });
       const json2 = await response.json();
@@ -69904,8 +69916,9 @@ var OpenAIProvider = class {
       prompt: input.prompt,
       n: String(input.count || 1),
       size: mapSize(input.aspectRatio),
-      quality: mapQuality(input.resolution),
-      ...input.outputFormat ? { output_format: input.outputFormat } : {}
+      quality: input.quality || mapQuality(input.resolution),
+      ...input.outputFormat ? { output_format: input.outputFormat } : {},
+      ...input.background ? { background: input.background } : {}
     };
     const { body, contentType: ct } = buildMultipart(fields, [
       {
@@ -69982,7 +69995,7 @@ function buildImageContent(images, paths, extra) {
 }
 var server = new McpServer({
   name: "imgx",
-  version: "1.5.1"
+  version: "1.6.1"
 });
 initGemini();
 initOpenAI();
@@ -70003,6 +70016,8 @@ server.tool("generate_image", "Generate an image from a text prompt", {
   resolution: external_exports3.enum(["1K", "2K", "4K"]).optional().describe("Output resolution"),
   count: external_exports3.number().int().min(1).max(4).optional().describe("Number of images"),
   output_format: external_exports3.enum(["png", "jpeg", "webp"]).optional().describe("Output format"),
+  background: external_exports3.enum(["transparent", "opaque", "auto"]).optional().describe("Background transparency (OpenAI only). Use 'transparent' for transparent PNG/WebP"),
+  quality: external_exports3.enum(["low", "medium", "high", "auto"]).optional().describe("Image quality (OpenAI only). Overrides resolution-based quality mapping"),
   model: external_exports3.string().optional().describe("Model name"),
   provider: external_exports3.string().optional().describe("Provider name")
 }, async (args) => {
@@ -70013,7 +70028,9 @@ server.tool("generate_image", "Generate an image from a text prompt", {
       aspectRatio: args.aspect_ratio,
       resolution: args.resolution,
       count: args.count,
-      outputFormat: args.output_format
+      outputFormat: args.output_format,
+      background: args.background,
+      quality: args.quality
     };
     const result = await prov.generate(input, args.model);
     if (!result.success || result.images.length === 0) {
@@ -70049,6 +70066,8 @@ server.tool("edit_image", "Edit an existing image with text instructions", {
   aspect_ratio: external_exports3.enum(["1:1", "2:3", "3:2", "3:4", "4:3", "9:16", "16:9"]).optional().describe("Aspect ratio"),
   resolution: external_exports3.enum(["1K", "2K", "4K"]).optional().describe("Output resolution"),
   output_format: external_exports3.enum(["png", "jpeg", "webp"]).optional().describe("Output format"),
+  background: external_exports3.enum(["transparent", "opaque", "auto"]).optional().describe("Background transparency (OpenAI only)"),
+  quality: external_exports3.enum(["low", "medium", "high", "auto"]).optional().describe("Image quality (OpenAI only)"),
   model: external_exports3.string().optional().describe("Model name"),
   provider: external_exports3.string().optional().describe("Provider name")
 }, async (args) => {
@@ -70064,7 +70083,9 @@ server.tool("edit_image", "Edit an existing image with text instructions", {
       inputImage: args.input,
       aspectRatio: args.aspect_ratio,
       resolution: args.resolution,
-      outputFormat: args.output_format
+      outputFormat: args.output_format,
+      background: args.background,
+      quality: args.quality
     };
     const result = await prov.edit(input, args.model);
     if (!result.success || result.images.length === 0) {
@@ -70094,6 +70115,8 @@ server.tool("edit_last", "Edit the last generated/edited image with new text ins
   aspect_ratio: external_exports3.enum(["1:1", "2:3", "3:2", "3:4", "4:3", "9:16", "16:9"]).optional().describe("Aspect ratio"),
   resolution: external_exports3.enum(["1K", "2K", "4K"]).optional().describe("Output resolution"),
   output_format: external_exports3.enum(["png", "jpeg", "webp"]).optional().describe("Output format"),
+  background: external_exports3.enum(["transparent", "opaque", "auto"]).optional().describe("Background transparency (OpenAI only)"),
+  quality: external_exports3.enum(["low", "medium", "high", "auto"]).optional().describe("Image quality (OpenAI only)"),
   model: external_exports3.string().optional().describe("Model name"),
   provider: external_exports3.string().optional().describe("Provider name")
 }, async (args) => {
@@ -70115,7 +70138,9 @@ server.tool("edit_last", "Edit the last generated/edited image with new text ins
       inputImage: active.filePaths[0],
       aspectRatio: args.aspect_ratio,
       resolution: args.resolution,
-      outputFormat: args.output_format
+      outputFormat: args.output_format,
+      background: args.background,
+      quality: args.quality
     };
     const result = await prov.edit(input, args.model);
     if (!result.success || result.images.length === 0) {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "imgx-mcp",
-  "version": "1.5.1",
+  "version": "1.6.1",
   "mcpName": "io.github.somacoffeekyoto/imgx",
-  "description": "AI image generation and editing for Claude Code, Codex CLI, and MCP-compatible AI agents",
+  "description": "AI image generation and editing MCP server with context-aware prompt optimization, 24 editing techniques, and session undo/redo",
   "type": "module",
   "bin": {
     "imgx": "dist/cli.bundle.js",

package/skills/image-generation/SKILL.md

@@ -7,12 +7,44 @@ description: Generate and edit AI images using Gemini or OpenAI. Text-to-image,
 
 Generate and edit images using the imgx MCP tools. Gemini and OpenAI providers supported.
 
+## Default model behavior
+
+**When the user does not specify a model, use Nano Banana (`gemini-2.5-flash-image`)** — the free tier model. This lets users start immediately without paid API access (500 images/day, no credit card).
+
+Suggest upgrading to a paid model when:
+- The user is unsatisfied with quality and wants improvement
+- The user needs 4K resolution or extended aspect ratios (1:4, 1:8, 4:1, 8:1, 21:9)
+- The user needs high text rendering accuracy (→ Nano Banana 2)
+- The user explicitly asks for higher quality or a specific paid model
+- The task clearly requires maximum quality (e.g. final production assets, print)
+
+When suggesting an upgrade, briefly explain what the paid model adds. Example:
+> "This was generated with the free model (Nano Banana). For higher resolution (up to 4K) and more aspect ratio options, I can re-generate with Nano Banana 2 or Pro — these require paid API access."
+
 ## When to use
 
 - User asks to create, generate, or make an image
 - User asks to edit, modify, or change an existing image
 - User needs a cover image, diagram, icon, or visual asset
 - User wants to refine an image iteratively ("make it darker", "change the background")
+- User mentions a model by alias (Nano Banana, NB2, etc.) — see Model aliases below
+
+## Model aliases
+
+Users may refer to models by their alias. Map these to the correct `model` parameter value:
+
+| Alias (case-insensitive) | Model ID | Provider |
+|--------------------------|----------|----------|
+| Nano Banana Pro, NanoBanana Pro, NB Pro, ナノバナナプロ | `gemini-3-pro-image-preview` | gemini |
+| Nano Banana 2, NanoBanana 2, NB2, ナノバナナ2, ナノバナナツー | `gemini-3.1-flash-image-preview` | gemini |
+| Nano Banana, NanoBanana, NB, ナノバナナ | `gemini-2.5-flash-image` | gemini |
+| GPT Image, gpt-image | `gpt-image-1` | openai |
+| GPT Image 1.5 | `gpt-image-1.5` | openai |
+| GPT Image Mini, gpt-mini | `gpt-image-1-mini` | openai |
+
+When the user says "ナノバナナ2で画像作って" → use `generate_image` with `model="gemini-3.1-flash-image-preview"`.
+When the user says "Nano Banana Proで前の画像を作り直して" → use `edit_last` with `model="gemini-3-pro-image-preview"`.
+When the user says "ナノバナナで画像作って" or "NB" → use `generate_image` with `model="gemini-2.5-flash-image"` (free tier model).
 
 ## Setup
 
@@ -53,7 +85,7 @@ After adding, restart Claude Code for the MCP server to connect.
 
 Get at least one API key:
 
-- **Gemini** (default, free tier available): [Google AI Studio](https://aistudio.google.com/apikey)
+- **Gemini** (default): [Google AI Studio](https://aistudio.google.com/apikey)
 - **OpenAI**: [OpenAI Platform](https://platform.openai.com/api-keys)
 
 Set the key in the `.mcp.json` env section (above), or via CLI:
@@ -61,6 +93,132 @@ Set the key in the `.mcp.json` env section (above), or via CLI:
 npx imgx-mcp config set api-key YOUR_KEY --provider gemini
 ```
 
+### 3. Project root (optional but recommended)
+
+imgx-mcp uses the project root to determine where `.imgx/` (history + default image output) is created. Without it, images go to `~/Pictures/imgx/` and history to `~/.config/imgx/`.
+
+| Method | Scope | How to set |
+|--------|-------|------------|
+| `IMGX_PROJECT_ROOT` env var | Per-client (highest priority) | Add to `env` in `.mcp.json` or `claude_desktop_config.json` |
+| Auto-detection (MCP roots / `.imgxrc` search) | Automatic | Works on CLI agents (Claude Code, Gemini CLI). Not available on Claude Desktop |
+| `imgx config set project-root /path` | All clients on the machine | Stored in user config |
+
+Detection priority: env var > MCP roots > `.imgxrc` upward search > user config `projectRoot`.
+
+**Claude Code** usually auto-detects via MCP roots — no extra config needed. **Claude Desktop** does not support auto-detection, so set `IMGX_PROJECT_ROOT` in the env.
+
+#### `.imgxrc` project config
+
+Create with `npx imgx-mcp init` or manually. Shared via Git (do not put API keys here):
+
+```json
+{
+  "defaults": {
+    "model": "gemini-2.5-flash-image",
+    "outputDir": "./assets/images",
+    "aspectRatio": "16:9"
+  }
+}
+```
+
+#### Claude Desktop config example
+
+```json
+{
+  "mcpServers": {
+    "imgx": {
+      "command": "npx",
+      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
+      "env": {
+        "GEMINI_API_KEY": "your-key",
+        "IMGX_PROJECT_ROOT": "C:\\Users\\you\\my-project"
+      }
+    }
+  }
+}
+```
+
+## Models and image specs
+
+### Nano Banana Pro — `gemini-3-pro-image-preview`
+
+Google's highest-quality image generation model. Paid only.
+
+| Spec | Value |
+|------|-------|
+| Resolution | 1K (1024px), 2K (2048px), 4K (4096px) |
+| Aspect ratios | 14: `1:1`, `1:4`, `1:8`, `2:3`, `3:2`, `3:4`, `4:1`, `4:3`, `4:5`, `5:4`, `8:1`, `9:16`, `16:9`, `21:9` |
+| Output format | PNG |
+| Text rendering | Good |
+| Photorealism | High |
+| Cost | ~$0.134/image |
+| Best for | High-quality hero images, photorealistic scenes, detailed illustrations |
+
+### Nano Banana 2 — `gemini-3.1-flash-image-preview`
+
+Fast model with Pro-level capabilities at lower cost. Improved text rendering.
+
+| Spec | Value |
+|------|-------|
+| Resolution | 1K (1024px), 2K (2048px), 4K (4096px) |
+| Aspect ratios | 14: `1:1`, `1:4`, `1:8`, `2:3`, `3:2`, `3:4`, `4:1`, `4:3`, `4:5`, `5:4`, `8:1`, `9:16`, `16:9`, `21:9` |
+| Output format | PNG |
+| Text rendering | High (~90% accuracy) |
+| Photorealism | Good |
+| Cost | $0.045-$0.151/image (resolution dependent) |
+| Best for | Rapid iteration, text-heavy images, marketing mockups, cost-sensitive workflows |
+
+### Nano Banana — `gemini-2.5-flash-image`
+
+The only Gemini image model with a **free tier**. Best entry point for trying imgx-mcp without cost.
+
+| Spec | Value |
+|------|-------|
+| Resolution | 1K (1024px) max |
+| Aspect ratios | 7: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9` |
+| Output format | PNG |
+| Text rendering | Fair |
+| Photorealism | Good |
+| Free tier | **Yes** — 10 RPM / 500 RPD (no credit card required) |
+| Paid tier | $0.039/image |
+| Best for | Free usage, quick prototyping, learning the workflow |
+| Limitations | No 4K, no extended aspect ratios (1:4, 1:8, 4:1, 8:1, 21:9 etc.) |
+
+### OpenAI models
+
+3 models available. All share the same capabilities (multi-output, format selection). Same API, same parameters.
+
+| Spec | gpt-image-1 | gpt-image-1.5 | gpt-image-1-mini |
+|------|-------------|----------------|------------------|
+| Resolution | Auto | Auto | Auto |
+| Aspect ratios | 7 | 7 | 7 |
+| Output format | PNG, JPEG, WebP | PNG, JPEG, WebP | PNG, JPEG, WebP |
+| Text rendering | Good | High (improved) | Fair |
+| Speed | Standard | ~4x faster | Standard |
+| Cost | $0.02-$0.19/image | ~20% cheaper than gpt-image-1 | $0.005-$0.036/image |
+| Best for | General use | Fast iteration, text-heavy, editing precision | Budget, bulk generation |
+
+### Model selection guide
+
+| Situation | Recommended model |
+|-----------|-------------------|
+| **Default / no model specified** | **Nano Banana** (free, 500/day) |
+| User wants better quality | Nano Banana Pro (`model="gemini-3-pro-image-preview"`) — paid |
+| Fast iteration with 4K / extended ratios | Nano Banana 2 (`model="gemini-3.1-flash-image-preview"`) — paid |
+| Text on images (logos, cards, mockups) | Nano Banana 2 (best text rendering) — paid |
+| Ultra-wide / tall images (8:1, 1:8, 21:9) | Gemini 3.x models (14 aspect ratios) — paid |
+| Need transparent PNG (icons, logos) | OpenAI (`background="transparent"`) — paid |
+| Need JPEG/WebP output | OpenAI (`output_format="jpeg"`) — paid |
+| Multiple variations at once | OpenAI (`count=3`) — paid |
+| OpenAI fast + cheap | gpt-image-1.5 (`model="gpt-image-1.5"`) — 4x faster, 20% cheaper |
+| OpenAI ultra-budget | gpt-image-1-mini (`model="gpt-image-1-mini"`) — $0.005/image |
+| OpenAI fast draft (low cost) | Any OpenAI model with `quality="low"` — fastest, cheapest |
+| OpenAI maximum detail | Any OpenAI model with `quality="high"` — best quality, slower |
+| Compare providers side-by-side | Generate with Gemini, then OpenAI |
+| Budget-conscious bulk generation | Nano Banana 2 (lowest per-image cost in paid tier) |
+
+**Upgrade path**: Nano Banana (free) → Nano Banana 2 (fast, affordable paid) → Nano Banana Pro (highest quality paid)
+
 ## MCP tools
 
 Use these tools directly. No Bash needed.
@@ -72,11 +230,13 @@ Generate an image from a text prompt.
 | Parameter | Required | Description |
 |-----------|----------|-------------|
 | `prompt` | Yes | Image description |
-| `aspect_ratio` | No | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` |
+| `aspect_ratio` | No | See model specs above for supported ratios |
 | `resolution` | No | `1K`, `2K`, `4K` (Gemini only) |
 | `count` | No | Number of images (OpenAI only) |
 | `output_format` | No | `png`, `jpeg`, `webp` (OpenAI only) |
-| `model` | No | Model name |
+| `background` | No | `transparent`, `opaque`, `auto` (OpenAI only). Use `transparent` for transparent PNG/WebP |
+| `quality` | No | `low`, `medium`, `high`, `auto` (OpenAI only). Overrides resolution-based mapping |
+| `model` | No | Model name or use alias mapping above |
 | `provider` | No | `gemini` (default) or `openai` |
 | `output` | No | Output file path |
 | `output_dir` | No | Output directory |
@@ -92,7 +252,9 @@ Edit an existing image with text instructions. No mask needed — the model dete
 | `aspect_ratio` | No | Output aspect ratio |
 | `resolution` | No | Output resolution (Gemini only) |
 | `output_format` | No | `png`, `jpeg`, `webp` (OpenAI only) |
-| `model` | No | Model name |
+| `background` | No | `transparent`, `opaque`, `auto` (OpenAI only) |
+| `quality` | No | `low`, `medium`, `high`, `auto` (OpenAI only) |
+| `model` | No | Model name or use alias mapping above |
 | `provider` | No | `gemini` (default) or `openai` |
 | `output` | No | Output file path |
 | `output_dir` | No | Output directory |
@@ -107,7 +269,9 @@ Edit the last generated or edited image. No input path needed — automatically
 | `aspect_ratio` | No | Output aspect ratio |
 | `resolution` | No | Output resolution (Gemini only) |
 | `output_format` | No | `png`, `jpeg`, `webp` (OpenAI only) |
-| `model` | No | Model name |
+| `background` | No | `transparent`, `opaque`, `auto` (OpenAI only) |
+| `quality` | No | `low`, `medium`, `high`, `auto` (OpenAI only) |
+| `model` | No | Model name or use alias mapping above |
 | `provider` | No | `gemini` (default) or `openai` |
 | `output` | No | Output file path |
 | `output_dir` | No | Output directory |
@@ -165,10 +329,11 @@ Change the default output directory for generated images.
 ### Blog cover image
 
 ```
-1. generate_image: prompt="A developer's desk with laptop showing terminal, coffee cup, warm morning light" aspect_ratio="16:9" resolution="2K"
+1. generate_image: prompt="A developer's desk with laptop showing terminal, coffee cup, warm morning light" aspect_ratio="16:9"
+   (uses free Nano Banana model by default)
 2. Review the result with the user
 3. edit_last: prompt="Make the color palette warmer" (if user wants changes)
-4. edit_last: prompt="Add subtle vignette effect" (further refinement)
+4. If user wants higher quality → re-generate with model="gemini-3-pro-image-preview" resolution="2K"
 ```
 
 ### Iterative refinement
@@ -176,7 +341,7 @@ Change the default output directory for generated images.
 The `edit_last` tool is the key to conversational image editing. Each call takes the previous output as input:
 
 ```
-generate_image → edit_last → edit_last → edit_last → done
+generate_image -> edit_last -> edit_last -> edit_last -> done
 ```
 
 Tell the user what was generated, ask if they want changes, and use `edit_last` to apply them. This is the most natural workflow.
@@ -186,10 +351,12 @@ Tell the user what was generated, ask if they want changes, and use `edit_last`
 Use `undo_edit` and `redo_edit` to navigate through edit history:
 
 ```
-generate_image → edit_last → edit_last → undo_edit → undo_edit → redo_edit
+generate_image -> edit_last -> edit_last -> undo_edit -> undo_edit -> redo_edit
 ```
 
-Each generate starts a new session. Use `edit_history` to see all sessions, and `switch_session` to resume work on a previous image chain.
+After undo, calling `edit_last` branches from the current position — abandoned entries and their files are automatically deleted from disk.
+
+Each generate starts a new session. Use `edit_history` to see all sessions, and `switch_session` to resume work on a previous image chain. `edit_last` uses the current position in the switched session.
 
 ### Comparing providers
 
@@ -210,19 +377,357 @@ Generate the same prompt with different providers to let the user choose:
 2. For Gemini, generate multiple times with slight prompt variations
 ```
 
+## Common use cases and techniques
+
+When the user describes what they need, suggest appropriate parameters and approach based on context.
+
+### Use case: OGP / social share images
+
+- Aspect ratio: `16:9` (Twitter/X, Facebook) or `1.91:1` (use `2:3` as closest)
+- Start with Nano Banana (free) for drafting. Upgrade to `2K` resolution with Nano Banana 2 or Pro for final
+- For text on the image — suggest Nano Banana 2 (best text rendering, paid)
+- Prompt tip: Describe the scene plus any text overlay you want rendered directly
+
+### Use case: Blog / article cover
+
+- Aspect ratio: `16:9` or `3:2`
+- Resolution: `2K` (balances quality and file size)
+- Prompt tip: Describe the main visual concept. Avoid metaphorical descriptions — be literal about what should appear
+
+### Use case: Presentation slides
+
+- Aspect ratio: `16:9`
+- Resolution: `2K`
+- Use a consistent visual theme across slides (describe the same color palette, style, and composition framing)
+- Prompt tip: Include "slide design" or "presentation visual" for cleaner layout
+
+### Use case: App store screenshots / product images
+
+- Aspect ratio: `9:16` (portrait), `16:9` (landscape), `1:1` (square)
+- Draft with Nano Banana (free), then `4K` with Nano Banana 2 or Pro (paid) for retina
+- Prompt tip: Describe the device frame and screen content you want shown
+
+### Use case: Vertical content (Stories, Reels, Shorts)
+
+- Aspect ratio: `9:16`
+- Full-bleed imagery works best — describe edge-to-edge scenes
+
+### Use case: Ultra-wide banner
+
+- Aspect ratio: `21:9` or `8:1` — requires Gemini 3.x models (paid)
+- Good for website hero banners, email headers, panoramic scenes
+- Note: Nano Banana (free) does not support extended ratios. Suggest upgrade if user needs these
+
+### Use case: Tall / narrow (Pinterest, infographic header)
+
+- Aspect ratio: `1:4` or `1:8` — requires Gemini 3.x models (paid)
+- Describe vertical flow — elements stacked top to bottom
+
+### Use case: Icons, logos, stickers (transparent background)
+
+- Use OpenAI with `background="transparent"` and `output_format="png"` (or `webp`)
+- JPEG does not support transparency — use PNG or WebP
+- Aspect ratio: `1:1` for icons
+- Prompt tip: Describe only the subject. Do not describe the background — the API handles removal
+
+### Use case: WordPress / web content
+
+- Prefer `output_format="jpeg"` (OpenAI) for smaller file size
+- Or generate with Gemini (PNG) and let the CMS handle conversion
+- `2K` resolution is sufficient for web
+
+## Popular editing techniques
+
+When the user wants to modify an image, suggest these proven approaches with `edit_last`:
+
+### Atmosphere and mood
+
+| Technique | Prompt example |
+|-----------|---------------|
+| Warm up | "Make the color palette warmer, shift toward golden/amber tones" |
+| Cool down | "Shift the color palette to cooler blue tones" |
+| Dramatic lighting | "Add dramatic side lighting with deep shadows" |
+| Golden hour | "Change the lighting to golden hour, warm sun low on the horizon" |
+| Night / dark mode | "Convert to a nighttime scene with dark sky and artificial lighting" |
+| Foggy / misty | "Add atmospheric fog in the background" |
+
+### Composition adjustments
+
+| Technique | Prompt example |
+|-----------|---------------|
+| Simplify background | "Replace the busy background with a clean, solid dark background" |
+| Add depth of field | "Blur the background to create shallow depth of field, keep foreground sharp" |
+| Add vignette | "Add a subtle vignette effect, darker edges" |
+| Change perspective | "Change the viewpoint to a top-down bird's eye view" |
+| Zoom in | "Crop tighter on the main subject, remove surrounding elements" |
+
+### Element manipulation
+
+| Technique | Prompt example |
+|-----------|---------------|
+| Add object | "Add a steaming coffee cup on the left side of the desk" |
+| Remove object | "Remove the laptop from the scene" |
+| Change color | "Change the shirt color from blue to red" |
+| Add text | "Add the text 'HELLO WORLD' in bold white letters at the top" |
+| Swap material | "Change the wooden table to marble" |
+| Change season | "Change the scene from summer to autumn, add fall foliage" |
+| Add weather | "Add rain falling and puddles on the ground" |
+
+### Style transfer
+
+| Technique | Prompt example |
+|-----------|---------------|
+| Illustration style | "Convert to a flat vector illustration style" |
+| Watercolor | "Redraw as a watercolor painting with soft edges" |
+| Pencil sketch | "Convert to a detailed pencil sketch" |
+| Pixel art | "Redraw as pixel art in 16-bit style" |
+| Anime / manga | "Redraw in anime art style" |
+| Vintage photo | "Apply a vintage film photo look with grain and faded colors" |
+
+### Practical refinement patterns
+
+These multi-step sequences are common in real workflows:
+
+**Quality escalation**: Start with Nano Banana (free) for drafting. When the concept is right, offer to re-generate with Nano Banana 2 (paid, fast, 4K) or Nano Banana Pro (paid, highest quality) for the final version.
+
+**A/B comparison**: Generate the same prompt with `provider="gemini"` then `provider="openai"` and show both to the user.
+
+**Iterative detail building**: Start broad ("a coffee shop interior"), then add details step by step ("add plants by the window", "put a barista behind the counter", "add warm overhead lighting").
+
+**Style exploration**: Generate a base image, then apply different style transfers with `edit_last` to find the right mood. Use `undo_edit` to return to the base and try another style.
+
+## Viral and trending image styles
+
+Popular AI image styles that users may request. Use these prompt templates with `generate_image` or `edit_last`.
+
+| Style | Prompt template | Notes |
+|-------|----------------|-------|
+| Ghibli / anime scene | "Redraw in Studio Ghibli anime style, soft watercolor textures, warm natural lighting, pastoral atmosphere" | Apply via `edit_last` to transform existing images |
+| Action figure in box | "A realistic action figure of [subject] in a sealed toy box with clear plastic window, product packaging, brand logo area at top, accessories visible" | Works well with `1:1` or `3:4` aspect ratio |
+| 3D clay figure | "A cute 3D clay figure of [subject], rounded smooth surfaces, soft pastel colors, miniature diorama, studio lighting" | The original "Nano Banana" viral style |
+| "Hug your past self" | "A person in [current clothing] hugging a smaller version of themselves as a [child/teenager], warm emotional lighting, photo-realistic" | Emotional / personal branding content |
+| Pet portrait (humanized) | "A [breed] dog/cat dressed in [outfit], sitting in a [setting], portrait style, dignified pose, realistic fur texture" | Popular for social media profiles |
+| Chibi character | "A chibi-style character of [description], oversized head, small body, big expressive eyes, simple background, cute proportions" | Good for avatars and stickers |
+| Pixel art retro | "16-bit pixel art of [subject], retro game aesthetic, limited color palette, clean pixel edges" | Nostalgic developer/gaming content |
+
+When the user requests a trending style, use the appropriate template and adjust based on their subject. Combine with `background="transparent"` (OpenAI) for stickers.
+
+## Specialized use case guides
+
+### Icon set generation
+
+Generate multiple icons with consistent style for an app or project:
+
+```
+1. Define the style: "Flat minimalist icon, 2px stroke, rounded corners, single accent color #FF6B35 on white"
+2. generate_image: prompt="[style] of a home/house symbol" aspect_ratio="1:1"
+3. generate_image: prompt="[style] of a settings gear symbol" aspect_ratio="1:1"
+4. generate_image: prompt="[style] of a user profile symbol" aspect_ratio="1:1"
+```
+
+Key: Repeat the exact same style description in every prompt. This is more reliable than using `edit_last` for style consistency across separate icons.
+
+For transparent icons: Use OpenAI with `background="transparent"` and describe only the icon subject.
+
+### Seamless pattern
+
+```
+1. generate_image: prompt="Seamless tileable pattern of [elements], evenly distributed, no visible seam edges, [style]"
+2. edit_last: prompt="Make the pattern more evenly distributed, ensure elements don't cluster at edges"
+```
+
+Tip: Include "seamless tileable pattern" and "no visible seam edges" in the prompt.
+
+### Technical diagram / architecture
+
+```
+1. generate_image: prompt="Clean technical architecture diagram showing [components], labeled boxes connected by arrows, white background, minimal style, clear hierarchy"
+2. edit_last: prompt="Add a label '[text]' to the top box"
+```
+
+For accurate text labels, use Nano Banana 2 (best text rendering) or OpenAI gpt-image-1.5.
+
+### Story sequence (consistent characters)
+
+Maintain visual consistency across a sequence of images:
+
+```
+1. Define a character DNA: "A woman with short dark hair, round glasses, wearing a navy blue cardigan and white t-shirt"
+2. generate_image: prompt="[character DNA], sitting at a desk reading a book, warm indoor lighting"
+3. generate_image: prompt="[character DNA], standing at a coffee shop counter ordering, morning light through windows"
+4. generate_image: prompt="[character DNA], walking on a city street with a tote bag, afternoon sun"
+```
+
+Key: Copy the exact character description into every prompt. Add scene-specific context after the character DNA. Consistency improves when using the same model and provider across all images.
+
+## Multi-image consistency techniques
+
+When the user needs multiple images that look like they belong together (slide decks, social media series, brand assets):
+
+### Design token approach
+
+Define visual constants and reuse them across all prompts:
+
+```
+Color:     "earth tones, warm browns (#8B6914) and sage green (#87A96B)"
+Style:     "flat illustration with subtle paper texture, 2D, no gradients"
+Lighting:  "soft diffused natural light, no harsh shadows"
+Framing:   "centered subject, 20% padding, clean background"
+```
+
+Prepend these tokens to every prompt: `"[tokens], [subject-specific content]"`
+
+### Character DNA template
+
+For recurring characters or mascots, write a fixed description block:
+
+```
+Character: "A friendly robot with a round head, single blue eye, matte silver body, short stubby arms, standing upright"
+```
+
+Never paraphrase — copy the exact same text each time.
+
+### Style reference chain
+
+Use one generated image as the style anchor:
+
+```
+1. generate_image: prompt="[detailed style + first scene]" → establish the look
+2. For subsequent images: describe the same style explicitly + new scene content
+3. If style drifts: undo_edit back, regenerate with more explicit style description
+```
+
+### Consistency tips
+
+- **Same model, same provider** across all images in a set
+- **Front-load the style description** before scene-specific content
+- **Use exact phrases** — "soft watercolor" not sometimes "watercolor" and sometimes "painted in watercolors"
+- **Generate at the same resolution** — mixing resolutions changes perceived style
+- **Review and regenerate** — if one image in a set drifts, regenerate it rather than trying to edit it to match
+
+## Platform size guide
+
+Recommended aspect ratios and resolutions for common platforms. When the user mentions a platform, suggest these settings automatically.
+
+### Social media
+
+| Platform | Use case | Aspect ratio | Resolution | Notes |
+|----------|----------|-------------|------------|-------|
+| Twitter/X | Post image | `16:9` | `2K` | 1200x675 recommended, larger is fine |
+| Twitter/X | Profile header | `3:1` (use `21:9`) | `2K` | 1500x500 recommended |
+| Facebook | Shared post | `16:9` | `2K` | |
+| Facebook | Cover photo | `21:9` | `2K` | 820x312 recommended |
+| Instagram | Feed post | `1:1` or `4:5` | `2K` | Square or portrait |
+| Instagram | Story/Reel | `9:16` | `2K` | 1080x1920 |
+| LinkedIn | Post image | `16:9` or `1:1` | `2K` | |
+| YouTube | Thumbnail | `16:9` | `2K` | 1280x720 minimum |
+
+### OGP (Open Graph Protocol)
+
+| Platform | Recommended size | Aspect ratio | Notes |
+|----------|-----------------|-------------|-------|
+| Twitter/X Cards | 1200x630 | `~1.91:1` (use `16:9`) | Summary with large image |
+| Facebook OGP | 1200x630 | `~1.91:1` (use `16:9`) | Same as Twitter |
+| LinkedIn OGP | 1200x627 | `~1.91:1` (use `16:9`) | Same ratio |
+| Slack unfurl | 1200x630 | `16:9` | Same as OGP standard |
+
+For OGP images: Use `16:9` at `2K` resolution. This covers all major platforms.
+
+### App stores
+
+| Platform | Use case | Aspect ratio | Resolution |
+|----------|----------|-------------|------------|
+| iOS App Store | Screenshot (iPhone) | `9:16` | `4K` (retina) |
+| iOS App Store | Screenshot (iPad) | `3:4` | `4K` |
+| Google Play | Screenshot | `9:16` | `4K` |
+| App Store | Feature graphic | `16:9` | `2K` |
+
+### Print and documents
+
+| Use case | Aspect ratio | Resolution | Notes |
+|----------|-------------|------------|-------|
+| A4 document | `3:4` | `4K` | Portrait orientation |
+| Letter | `4:5` | `4K` | US letter approximation |
+| Presentation (16:9) | `16:9` | `2K`–`4K` | Standard widescreen |
+| Business card | `16:9` or `3:2` | `2K` | Landscape orientation |
+
+### Blog platforms
+
+| Platform | Cover image | Aspect ratio | Notes |
+|----------|-------------|-------------|-------|
+| note.com | Header | `16:9` | PNG recommended |
+| Dev.to | Cover | `16:9` | 1000x420 minimum |
+| Medium | Header | `16:9` or `3:2` | |
+| WordPress | Featured image | `16:9` | JPEG for file size |
+| Qiita | OGP | `16:9` | Auto-generated if not set |
+
+## Writing effective prompts
+
+Structure prompts with three layers: **Subject → Context → Style**. Each layer adds specificity.
+
+### Subject (what)
+
+Name the main subject concretely. Avoid abstract descriptions.
+
+| Weak | Strong |
+|------|--------|
+| "coffee scene" | "a ceramic pour-over dripper on a wooden table with a freshly brewed cup" |
+| "developer working" | "a developer's hands on a laptop keyboard, terminal showing green text on dark background" |
+| "nature" | "a single oak tree on a grass hill, autumn leaves half-fallen" |
+
+### Context (where / when / with what)
+
+Add environment, lighting, and surrounding elements.
+
+| Element | Example |
+|---------|---------|
+| Lighting | "soft natural light from a left window", "harsh overhead fluorescent", "golden hour backlight" |
+| Setting | "in a minimalist Scandinavian kitchen", "on a rainy Tokyo street at night" |
+| Surrounding objects | "with a notebook and pen beside it", "next to a stack of books" |
+| Time/season | "early morning", "winter snowfall outside the window" |
+
+### Style (how it looks)
+
+Specify the visual treatment.
+
+| Element | Example |
+|---------|---------|
+| Photography style | "shallow depth of field, f/1.8", "wide-angle shot from below" |
+| Art style | "flat vector illustration", "watercolor with soft edges", "detailed pencil sketch" |
+| Color palette | "earth tones, warm browns and greens", "monochrome with single red accent" |
+| Mood | "calm and contemplative", "energetic and vibrant" |
+
+### Complete prompt example
+
+```
+Subject:  A barista pouring steamed milk into a latte, creating a rosetta pattern
+Context:  At a wooden counter in a small coffee shop, warm pendant light overhead, coffee equipment in the background
+Style:    Close-up shot, shallow depth of field, warm earth tones, natural lighting
+```
+
+→ `"A barista pouring steamed milk into a latte creating a rosetta pattern, at a wooden counter in a small coffee shop, warm pendant light overhead, coffee equipment in background, close-up shot, shallow depth of field, warm earth tones, natural lighting"`
+
+### Prompt tips
+
+- **Be literal, not metaphorical** — "a bridge connecting two cliffs" not "bridging the gap between ideas"
+- **Front-load the subject** — The model weights the beginning of the prompt more heavily
+- **Specify what you don't want** sparingly — "no text" or "no people" can help, but negative prompts are less reliable than positive descriptions
+- **For text in images** — Put the exact text in quotes: `"with the text 'HELLO WORLD' in bold white sans-serif at the top center"`
+- **For editing** — Describe only the change, not the entire image. "Make the sky sunset orange" not "A scene with everything the same but the sky is now sunset orange"
+
 ## Tips
 
 - **Be specific in prompts**: "A wooden table with a ceramic pour-over dripper, steam rising, soft natural light from left" works better than "coffee scene"
 - **Use edit_last for iteration**: Don't ask the user to specify file paths. Just use `edit_last` after any generation or edit
 - **Check provider capabilities**: Use `list_providers` if unsure what a provider supports
-- **Where `.imgx/` is created**: The `.imgx/` directory holds both edit history (`output-history.json`) and default image output. When a project root is detected, it's created at `<project-root>/.imgx/`. Without a project root, images go to `~/Pictures/imgx/` and history to `~/.config/imgx/`. All clients sharing the same project root share the same history
+- **Where `.imgx/` is created**: The `.imgx/` directory holds both edit history (`output-history.json`) and default image output. When a project root is detected, it's created at `<project-root>/.imgx/`. Without a project root, images go to `~/Pictures/imgx/` and history to `~/.config/imgx/`. All clients sharing the same project root share the same history. See the **Project root** setup section above for configuration methods
 - **Default output**: Images save to `<project-root>/.imgx/<session-id>/` (project auto-detected). Falls back to `~/Pictures/imgx/` when no project is detected. Use `output` or `output_dir` to customize
 - **Custom output_dir and history**: When `output_dir` is specified on `generate_image`, the path is recorded as session metadata in `output-history.json`. `edit_last` reads this to inherit the output location. Only image files go to the custom path — history always stays in `.imgx/` (or global config directory)
 - **Inline preview**: MCP responses include base64 image data for inline display in supported clients
 - **Undo/redo**: Use `undo_edit` and `redo_edit` to step through edit history. Each session holds up to 10 entries
 - **Sessions**: Each `generate_image` starts a new session. Use `edit_history` to see all sessions and `switch_session` to resume a previous one
-- **Sequential naming**: When `output` specifies a filename, `edit_last` appends sequential numbers: `cover.png` → `cover-1.png` → `cover-2.png`. Undo automatically deletes discarded files
-- **Project scope**: History is stored per-project in `<project-root>/.imgx/output-history.json`. `clear_history` only affects the current project
+- **Sequential naming**: When `output` specifies a filename, `edit_last` appends sequential numbers: `cover.png` -> `cover-1.png` -> `cover-2.png`. Undo automatically deletes discarded files
+- **Project scope**: History is stored per-project in `<project-root>/.imgx/output-history.json`. `clear_history` only affects the current project. Relative paths in `output` and `output_dir` are resolved against the project root
 
 ## CLI fallback
 

package/skills/image-generation/references/providers.md

@@ -5,18 +5,20 @@
 | Item | Value |
 |------|-------|
 | Provider name | `gemini` |
-| Default model | `gemini-3-pro-image-preview` |
-| Alternative model | `gemini-2.5-flash-image` |
+| Default model | `gemini-2.5-flash-image` (Nano Banana — **free tier**) |
+| Paid models | `gemini-3-pro-image-preview` (Nano Banana Pro), `gemini-3.1-flash-image-preview` (Nano Banana 2) |
 | API key env var | `GEMINI_API_KEY` |
 
 ### Model comparison
 
-| Feature | gemini-3-pro-image-preview | gemini-2.5-flash-image |
-|---------|---------------------------|------------------------|
-| Quality | Higher | Good |
-| Speed | Slower | Faster |
-| Cost | ~$0.134/image | Lower |
-| Resolution | 1K, 2K, 4K | 1K, 2K |
+| Feature | Nano Banana Pro (`gemini-3-pro-image-preview`) | Nano Banana 2 (`gemini-3.1-flash-image-preview`) | Nano Banana (`gemini-2.5-flash-image`) |
+|---------|------------------------------------------------|--------------------------------------------------|----------------------------------------|
+| Quality | Highest | Good (improved text rendering, ~90% accuracy) | Good |
+| Speed | Slower | Faster | Fast |
+| Cost | ~$0.134/image | $0.045-$0.151/image (resolution dependent) | $0.039/image |
+| Resolution | 1K, 2K, 4K | 1K, 2K, 4K | 1K (1024px max) |
+| Aspect ratios | 14 | 14 | 7 |
+| Free tier | No | No | **Yes** (10 RPM / 500 RPD) |
 
 ### Capabilities
 
@@ -24,8 +26,8 @@
 |------------|---------------|-------------|
 | TEXT_TO_IMAGE | (default) | Generate from text |
 | IMAGE_EDITING | `input` | Edit with text instructions |
-| ASPECT_RATIO | `aspect_ratio` | 7 ratios: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9` |
-| RESOLUTION_CONTROL | `resolution` | `1K`, `2K`, `4K` |
+| ASPECT_RATIO | `aspect_ratio` | 3.x models: 14 ratios (`1:1`, `1:4`, `1:8`, `2:3`, `3:2`, `3:4`, `4:1`, `4:3`, `4:5`, `5:4`, `8:1`, `9:16`, `16:9`, `21:9`). 2.5 Flash: 7 ratios (`1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9`) |
+| RESOLUTION_CONTROL | `resolution` | 3.x models: `1K`, `2K`, `4K`. 2.5 Flash: `1K` only |
 | REFERENCE_IMAGES | — | Use reference images (future) |
 | PERSON_CONTROL | — | Control person generation (future) |
 
@@ -35,6 +37,7 @@
 |------|-------|
 | Provider name | `openai` |
 | Default model | `gpt-image-1` |
+| Additional models | `gpt-image-1.5` (faster, 20% cheaper), `gpt-image-1-mini` (budget, $0.005/image) |
 | API key env var | `OPENAI_API_KEY` |
 
 ### Capabilities
@@ -46,15 +49,19 @@
 | ASPECT_RATIO | `aspect_ratio` | 7 ratios: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9` |
 | MULTIPLE_OUTPUTS | `count` | Generate up to 4 images per request |
 | OUTPUT_FORMAT | `output_format` | PNG, JPEG, WebP |
+| BACKGROUND | `background` | `transparent`, `opaque`, `auto`. Transparent PNG/WebP for icons, logos, stickers |
+| QUALITY | `quality` | `low`, `medium`, `high`, `auto`. Direct quality control (overrides resolution mapping) |
 
 ### Provider comparison
 
 | Feature | Gemini | OpenAI |
 |---------|--------|--------|
 | Edit (text-only, no mask) | Yes | Yes |
-| Resolution control | Yes (1K/2K/4K) | No |
+| Resolution control | Yes (3.x: 1K/2K/4K, 2.5: 1K only) | No |
+| Aspect ratios | 3.x: 14, 2.5: 7 | 7 |
 | Multiple outputs | No | Yes (up to 4) |
 | Output format selection | No (PNG only) | Yes (PNG/JPEG/WebP) |
+| Background transparency | No | Yes (`transparent`/`opaque`/`auto`) |
 | Iterative editing (`edit_last`) | Yes | Yes |
 
 ## Adding new providers