ima2-gen 2.0.15 → 2.0.16

package/skills/ima2-front/references/anti-slop.md

@@ -0,0 +1,241 @@
+# Anti-Slop — Banned AI Design Patterns (2026)
+
+Specific patterns that mark output as "AI-generated." Comprehensive audit checklist
+for any frontend surface built with ima2 assets.
+
+---
+
+## Typography Slop Signals
+- Unexamined default typography: browser defaults, framework defaults, or "Inter everywhere" without a reason
+- Latin-first font choices applied to Hangul without testing CJK rhythm, line-height, and fallback
+- Space Grotesk as the automatic "anti-Inter" choice
+- System stacks as a shortcut instead of a deliberate product typography decision
+
+**Allowed when intentional**: `system-ui`, `-apple-system`, Pretendard, SUIT, Noto Sans KR, Apple SD Gothic Neo.
+
+**Do instead**: choose a domain-appropriate stack. Korean-first: CJK-safe product stack. Latin display: Geist, Outfit, Cabinet Grotesk, Satoshi, Clash Display, GT America, or Neue Machina.
+
+## Typography Audit
+- **Inter everywhere** -> deliberate stack for product and locale
+- **Headlines lack presence** -> increase size, tighten letter-spacing, reduce line-height
+- **Body too wide** -> limit to ~65ch, increase line-height
+- **Only 400 + 700** -> introduce 500, 600, or extremes (100 vs 900)
+- **Proportional numbers in data** -> `font-variant-numeric: tabular-nums`
+- **Missing letter-spacing** -> negative for large headers, positive for small caps
+- **All-caps everywhere** -> sentence case, small-caps, or lowercase italic
+- **Orphaned words** -> `text-wrap: balance` or `text-wrap: pretty`
+- **No `text-wrap`** -> apply `balance` globally to h1-h6 (see `typography-wrapping.md`)
+- **No `max-width` in `ch`** -> h1: 50ch, h2: 55ch, p: 65ch
+- **Heading breaks mid-phrase** -> review at 390px, 768px, 1440px
+- **Body exceeding 75 chars** -> `max-width: 65ch`
+
+---
+
+## Banned Color Patterns
+- Gradient soup: the 2026 #1 AI tell. Layered gradient washes, gradient cards, gradient borders, and glow soup
+- Purple gradient on white background
+- Blue-to-indigo gradient buttons
+- Oversaturated neon accents (saturation < 80%)
+- Equally distributed pastel rainbows
+- Pure black `#000000` -> off-black (`#0a0a0a`, Zinc-950)
+- Mixing warm and cool grays in same project
+- Generic box-shadow -> tint shadows to background hue
+
+**Do instead**: Zinc/Slate neutral base + ONE high-contrast accent.
+
+## Gradient Budget (FE-GRADIENT-01, DEFAULT)
+
+- Max 1 ambient gradient per viewport
+- No gradients on 3+ sibling cards
+- Background + card gradients + gradient borders + glow stacked = gradient soup
+- Radial glows behind dark heroes are decorative filler unless they model a real light source
+- Every gradient must encode something: depth, light, state, or one brand moment
+
+### Opaque Functional Surfaces (FE-GRADIENT-02, DEFAULT)
+
+Tinted gradient wash on an OPAQUE functional panel (cards, panels, sidebars,
+badges, buttons inside tools) is product-UI gradient soup. It reads as dated
+marketing chrome: color as decoration, contrast varies top-to-bottom.
+
+Decision rule:
+- Ambient/expressive/translucent -> gradient allowed for mood/light/depth/material
+- Opaque + functional (cards, panels, task UI) -> NO gradient. Emphasize with
+  ONE channel: flat tint | 1px border | accent bar | elevation shadow | status token
+
+## One-Note Theme Ban (FE-ONENOTE-01, DEFAULT)
+
+Full-page single-hue theming where bg, borders, text, badges, glows, and imagery
+all resolve to one hue family.
+
+- Terminal green / Matrix hacker = #1 dark-mode tell
+- Cyber cyan, retro CRT amber, synthwave magenta
+- Check: sample 5 random UI elements; if 4+ share one hue +/-30 deg = one-note
+- Generated imagery color-matched to theme hue compounds the problem
+
+**Do instead**: neutral dark (Zinc-950/`#0a0a0a`) + ONE accent at <10% surface area.
+
+## Premium-Consumer Palette Ban (DEFAULT)
+
+For premium-consumer briefs (cookware, wellness, artisan, luxury, heritage):
+
+**Banned backgrounds**: `#f5f1ea` `#f7f5f1` `#fbf8f1` `#efeae0` `#faf7f1`
+**Banned accents**: `#b08947` `#b6553a` `#9a2436` `#9c6e2a`
+**Banned text**: `#1a1714` `#1b1814`
+
+Override ONLY when the brand brief explicitly names warm beige/cream.
+
+---
+
+## Banned Layouts
+- Everything centered with uniform padding
+- Oversized bold hero inside tools, dashboards, admin, finance
+- 3 equal cards in a row (the "feature row" cliche)
+- Uniform rounded corners on every element
+- Centered hero + gradient background + Inter heading
+- Card-heavy dashboards where every metric is boxed
+- Complex flexbox calc -> CSS Grid
+- `height: 100vh` -> `min-height: 100dvh`
+- No max-width -> `max-w-7xl mx-auto`
+- Cards forced to equal height -> allow variable or masonry
+- Dashboard always left sidebar -> try top nav, command menu, collapsible
+- Symmetrical vertical padding -> bottom often needs slightly larger (optical)
+
+## 2026 Product Slop
+- Asset-free pages: gradients, blobs, generic icons where product/screenshot/diagram needed
+- Use `ima2 gen` to create real visual assets instead of CSS gradient washes
+- Fake dashboards with random numbers
+- Landing-page composition inside repeated-work tools
+- AI tool surfaces without pending, cancel, retry, undo, provenance states
+- Trust-heavy domains using playful visuals without purpose
+- Soft 3D miniatures from generic icon packs without brand adaptation
+- Giant centered Korean headlines as decoration rather than hierarchy
+
+## AI Tell Patterns
+
+- Version labels in heroes (V0.6, BETA, INVITE-ONLY)
+- Section-number eyebrows (001 - Capabilities)
+- Middle-dot overuse: max 1 per metadata line
+- "Quietly trusted by" social-proof headers
+- Weather/locale strips unless genuinely place-focused
+- Scroll cues ("scroll to explore")
+- Decorative dots before nav items
+- Photo-credit captions on AI-generated images
+- Fake product previews from styled divs
+- Version footers on marketing pages
+- Same generated image used twice on one page
+- Monospace uppercase micro-labels on every card
+
+### Self-Describing Meta Copy (FE-METACOPY-01, DEFAULT)
+
+UI copy must describe the product/user job, never the mockup, layout, or
+responsive behavior.
+
+- "벤토 보드에 겹쳐 보여주는 목업" = meta copy (banned)
+- "작은 화면에서 단일 열로 접힙니다" = meta copy (banned)
+- Cards named after design artifacts (VIEWPORT MATRIX) = meta copy (banned)
+
+**Test**: could a real user say what job this element does for them?
+
+---
+
+## Emoji Slop (STRICT)
+
+Emoji as visual elements is the strongest AI tell in 2026. Human designers
+never ship emoji as feature icons or section markers in production UI.
+
+| Context | Verdict | Do Instead |
+|---------|---------|------------|
+| Feature card icons | **BANNED** | Lucide/Phosphor/Heroicons SVG |
+| Section headers | **BANNED** | Typographic hierarchy or icon |
+| Button labels | **BANNED** | Text only, or SVG + text |
+| Chat/messaging content | Allowed | User-generated content exempt |
+| CLI output | Allowed | Functional indicators OK |
+
+---
+
+## Banned Logo/Integration Patterns
+- Generic stroke icons as brand logos -> use actual SVGs from Simple Icons, SVGL, or press kits (see `brand-asset-sourcing.md`)
+- Individual hover on non-clickable logo walls -> trust signals, not navigation
+- Grid with orphan cells -> flexbox center or marquee
+- Static grid for 8+ logos -> CSS marquee (30-40s, linear)
+- Missing `prefers-reduced-motion` on marquee
+- Missing edge fade on marquee
+
+## Korean Slop
+- Translationese: "원활한 경험을 제공합니다", "혁신적인 솔루션"
+- Bureaucratic labels where simple Korean works
+- Korean text clipped in fixed-width buttons
+- Negative letter-spacing on Hangul without testing
+- Cute visuals as Korean default (domain decision, not locale decision)
+- Oversized ultra-bold Hangul hero: 100px+ / 800-900 weight on Korean reads as heavy mass
+  Korean premium: 56-72px / 700 / line-height 1.25-1.4
+- Split-hero template (FE-HERO-SPLIT-01): left headline + right boxed screenshot is exhausted
+  Default: product visual is the stage, not a right-column card
+- "Tasteslop" serif shortcut: serif purely as AI-premium signal without editorial structure
+
+---
+
+## Banned Interaction Patterns
+- Generic circular spinners -> skeleton loaders matching layout
+- Default browser focus rings -> `focus-visible:ring-2`
+- Custom cursors (outdated, a11y issue)
+- Neon/outer glow box-shadow
+- No hover states -> add background shift, scale, or translate
+- No pressed feedback -> `scale(0.98)` or `translateY(1px)`
+- Zero-duration transitions -> 200-300ms
+- Dead `#` links -> real destinations or visually disable
+- Scroll jumping -> `scroll-behavior: smooth`
+- Animations using top/left/width/height -> transform+opacity
+
+## Banned Content ("Jane Doe" Effect)
+- Generic names: "John Doe", "Sarah Chan"
+- Generic companies: "Acme", "Nexus", "SmartFlow"
+- Predictable numbers: `99.99%`, `$9.99`
+- AI copywriting: "Elevate", "Seamless", "Unleash", "Next-Gen", "Delve"
+- Exclamation in success messages -> confident, not loud
+- "Oops!" errors -> "Connection failed. Please try again."
+- Lorem Ipsum -> write real draft copy
+- Title Case On Every Header -> sentence case
+
+## Banned Component Defaults
+- shadcn in default state -> customize radii, colors, shadows
+- Default Tailwind blue as primary
+- Lucide egg avatar -> picsum.photos or SVG UI Avatars
+- 3-card carousel testimonials -> masonry, embedded social, rotating quote
+- Modals for everything -> inline editing, slide-over, expandable
+- Sun/moon dark mode toggle -> dropdown or system preference
+- 4-column footer link farm -> simplify
+
+## Soft 3D / Character Asset Slop
+Not banned by default, but must pass `soft-3d-asset-gates.md`.
+
+Slop: generic pack, random cute object, inconsistent lighting, low-polish AI
+output, decorative overload, asset competing with headline.
+
+---
+
+## Strategic Omissions (What AI Forgets)
+- No legal links in footer
+- No "back" navigation (dead ends)
+- No custom 404 page
+- No form validation
+- No skip-to-content link
+- Random dark sections in light page -> commit to one theme
+
+## Anti-Convergence Rule
+
+Each generation MUST be visually distinct from the last:
+- Different font pairing
+- Different aesthetic archetype
+- Alternate light/dark themes
+- Vary layout patterns
+
+## Redesign Fix Priority
+
+1. **Font swap** (biggest instant improvement)
+2. **Color palette cleanup**
+3. **Hover + active states**
+4. **Layout + spacing**
+5. **Replace generic components**
+6. **Add loading/empty/error states**
+7. **Polish typography scale**

package/skills/ima2-front/references/asset-requirements.md

@@ -0,0 +1,431 @@
+# Asset Requirements
+
+Visual surfaces need real visual evidence. Abstract backgrounds, blobs, and generic icons are not enough when users need to understand a product, place, object, workflow, game, or state.
+
+## Asset Decision Table
+
+| Surface | Required Asset Type |
+| --- | --- |
+| Product / object / venue / person page | real or generated bitmap showing the subject |
+| Marketing / landing page | concrete product, scene, screenshot, or generated hero image |
+| Dashboard / tool | real state preview, chart, table, workflow screenshot, or diagram |
+| AI tool | process state, provenance, result preview, permission boundary, or diagram |
+| Education / kids / community | illustration, character, or guided visual allowed |
+| Fintech / gov / B2B | restrained screenshot, data view, trust visual, or high-polish semantic 3D |
+| Game | game assets mandatory |
+| Documentation | screenshots or diagrams when they clarify a task |
+
+## What Does Not Count
+
+- abstract gradient mesh
+- decorative blob/orb
+- generic icon row
+- fake dashboard with random numbers
+- low-polish AI image
+- stock photo unrelated to the task
+- public 3D icon pack used without brand adaptation
+- integration/partner logo wall using generic icons instead of brand SVGs (see `brand-asset-sourcing.md`)
+
+## Asset Sourcing Workflow
+
+This source-priority list applies to CONTENT assets used in builds: photos,
+illustrations, textures, motion clips, screenshots, diagrams, charts, and
+brand-safe SVGs. The concept-mockup pass in `ima2-uiux` is a process
+step outside this sourcing order; when its trigger fires, it runs before code
+even though its outputs are not shippable UI pixels.
+
+For build assets, try each source in order. Stop at the first that produces a
+usable asset.
+
+| Priority | Source | When to Use |
+|----------|--------|-------------|
+| 1 | Project existing assets | `images/`, `public/`, `assets/` in the repo |
+| 2 | `ima2` CLI (canonical) or `ima2 gen` skill fallback | Hero images, product shots, custom illustrations, textures, and motion assets. Probe `ima2 status`; if unavailable, attempt `ima2 serve` and re-check before falling back. Use `ima2 gen`, `ima2 edit`, or `ima2 video` with a detailed prompt per § Agent Image Prompt Protocol. Fall back to `ima2 gen` only when ima2 is truly unavailable |
+| 3 | Stock photo API | `source.unsplash.com/800x600/?coffee`, Pexels. Always include `alt` text and credit |
+| 4 | CSS device frame + screenshot | App mockup heroes (Toss/카카오 style). Pure CSS phone/laptop frame wrapping a real screenshot or UI |
+| 5 | Placeholder service (last resort) | `picsum.photos/800/600`, `placehold.co`. Mark as TODO for replacement |
+
+### Korean Service Patterns
+
+Korean product pages almost always use concrete visual evidence in the first viewport:
+
+| Pattern | Example | Implementation |
+|---------|---------|---------------|
+| Device mockup hero | Toss, 카카오뱅크, 당근 | CSS device frame (`border-radius: 40px`, `box-shadow`) + app screenshot inside |
+| Real product photo | 배민, 무신사, 마켓컬리 | Full-bleed or contained product image, not a gradient placeholder |
+| App screenshot carousel | 토스, 네이버 | Horizontal scroll of actual app screens |
+| Data visualization hero | 토스증권, 뱅크샐러드 | Real (or realistic) chart/graph as primary visual |
+
+Never ship a Korean-facing product page with only SVG icons and text. If no image source is available, state the gap explicitly rather than filling with gradients or decorative shapes.
+
+## Mockup Production Pipeline (verified 2026-07-09)
+
+When a product/device mockup asset is required (product-led heroes, app
+screenshots in scenes):
+
+- **Device-mockup tools** (Rotato, MockRocket, Shots, Smartmockups, Figma
+  mockup plugins): map a real screenshot onto a 3D device render; stills and
+  short movies, no 3D skills needed.
+- **AI scene + real screenshot compositing**: generate the environment/scene
+  image, then composite the actual product UI screenshot into or above it;
+  never AI-generate the shipped product UI itself - the interface pixels must
+  be real in shipped assets.
+- **Frame extraction**: for scroll-driven playback, render the mockup motion
+  to video and extract frames (see motion.md § Frame Sequence Format Guide).
+
+The screenshot inside any mockup must be a real, current capture of the
+product; a fabricated UI in a real frame is still a fake asset.
+
+### Concept Mockup Boundary (FE-ASSET-CONCEPT-01, DEFAULT)
+
+Generated CONCEPT mockups of a page or component, including `ima2` concept
+passes and mockup references, are exploration artifacts. They are legal and
+encouraged before code when the concept-pass trigger fires, but they must never
+ship as UI pixels.
+
+The "never AI-generate the product UI itself" rule is scoped to shipped
+assets. It does not ban pre-code concept exploration, and it does not ban
+generated photographic, texture, illustration, or motion CONTENT assets in real
+builds. Those content assets are not product UI pixels; they may ship when
+they satisfy provenance, licensing, accessibility, performance, and visual QA
+requirements.
+
+## Rules
+
+- Use the repo's existing asset system first.
+- If no asset exists and the surface needs one, follow the sourcing workflow above.
+- For external or generated assets, record provenance/licensing in the dev note, PR description, or project asset manifest when one exists.
+- For captured third-party reference material, use `reference-capture.md` and keep the required manifest next to the capture. Captured assets never move into shipped project assets.
+- Make the first viewport identify the product/place/object when relevant.
+- Do not obscure text or primary actions with visuals.
+- Verify assets render on mobile and desktop.
+- Verify intrinsic dimensions, aspect ratio, crop, alt text, and loading behavior.
+- Optimize heavy media; do not ship huge 3D/video assets without a reason.
+- Ship gate: no captured third-party asset may appear in the shipped build.
+
+## Agent Image Prompt Protocol
+
+### Long Prompt and Motion Rule (FE-ASSET-PROMPT-01, DEFAULT)
+
+When an AI agent generates image prompts (for `ima2 gen`, `ima2 multimode`,
+`ima2 edit`, `ima2 video`, or the `ima2 gen` fallback), the prompt must be
+**exhaustively detailed**. Vague one-liners produce generic, unusable output.
+Write every prompt as if you are briefing a senior photographer, illustrator,
+or motion designer who cannot ask follow-up questions.
+
+Image assets need very explicit long prompts covering subject, composition,
+palette, lighting, style or medium, materials, aspect ratio, constraints, and
+avoid-list. When motion is wanted, use `ima2 video` rather than simulating
+richness with static CSS washes. Prefer real photographic, generated bitmap,
+texture, illustration, or video assets over CSS gradient backgrounds; gradients
+remain scarce semantic devices under `anti-slop.md` FE-GRADIENT-01.
+
+### Required Spec Fields
+
+Every agent-authored prompt MUST include all applicable fields below. Omit a
+field only when it genuinely does not apply (e.g. no text in the image).
+
+```text
+Use case: <taxonomy slug from imagegen skill>
+Asset type: <where the asset will be used: hero, OG image, card, avatar, icon, texture, etc.>
+Primary request: <one clear sentence describing the desired image>
+Scene/backdrop: <specific environment, not "nice background">
+Subject: <main subject with identifying details — material, color, shape, posture, expression>
+Style/medium: <exact style: editorial photography, flat illustration, 3D render, watercolor, etc.>
+Composition/framing: <camera angle, crop, subject placement, negative space intent>
+Lighting/mood: <light source, direction, color temperature, mood, time of day>
+Color palette: <specific colors or named palette — not "modern colors">
+Materials/textures: <surface details: matte plastic, brushed steel, linen, weathered wood, etc.>
+Text (verbatim): "<exact text to render>" with font style, size, placement
+Dimensions: <target pixel dimensions and aspect ratio>
+Constraints: <must-keep invariants>
+Avoid: <explicit negative constraints>
+```
+
+### Specificity Rules
+
+| Bad (vague) | Good (specific) |
+|---|---|
+| "a nice hero image" | "wide landscape product shot of a matte black thermos on a wet granite countertop, soft morning window light from the left, shallow depth of field, warm neutral tones, negative space on the right for headline overlay" |
+| "modern background" | "soft radial gradient from #f8f9fa center to #e9ecef edges, subtle paper grain texture at 3% opacity, no objects, no patterns" |
+| "Korean food photo" | "overhead flat-lay of budae-jjigae in a black stone pot, surrounded by small banchan dishes on a dark wood table, steam visible, warm tungsten lighting, editorial food photography style" |
+| "logo on white" | "centered geometric mark: two interlocking triangles forming a hexagonal negative space, flat #1a1a2e on #ffffff, no gradients, strong silhouette at 32px, generous padding" |
+| "a dashboard screenshot" | "realistic SaaS dashboard UI: top nav with avatar, left sidebar with 6 nav items, main area showing a line chart (3 series, 12 months) and a 4-column data table with 8 rows, light theme, Inter font, compact density" |
+
+### Quality and Size Selection
+
+| Asset Purpose | Quality | Size |
+|---|---|---|
+| Quick draft / iteration | `low` | `1024x1024` |
+| Final hero / product shot | `high` | `1536x1024` (landscape) or target aspect |
+| OG / social card | `high` | `1200x630` (round to nearest 16px multiple) |
+| Mobile hero | `high` | `1024x1536` (portrait) |
+| Print / 4K | `high` | `3840x2160` or `2160x3840` |
+| Texture / tile | `medium` | `1024x1024` |
+| Icon / avatar | `medium` | `512x512` or `256x256` |
+
+### Multi-Candidate Strategy
+
+For important visual assets (hero images, key illustrations), generate multiple
+candidates and select the best:
+
+```bash
+# Generate 4 candidates in one request
+ima2 gen "<detailed prompt>" -n 4 -d ./candidates --quality high
+
+# Or use multimode for structurally different directions
+ima2 multimode "<detailed prompt>" --max-images 4 -d ./candidates
+```
+
+After generation, inspect every candidate with `view_image` before selecting.
+Do not blindly use the first result.
+
+### Parallel Generation Patterns (FE-ASSET-PARALLEL-01, DEFAULT)
+
+ima2 supports three parallel generation strategies. Choose by intent:
+
+| Strategy | Command | When to Use | Server Behavior |
+|----------|---------|-------------|-----------------|
+| **Single-request batch** | `ima2 gen "<prompt>" -n 4 -d ./out` | Same prompt, want quick variations | One request, server returns N images |
+| **Multimode** | `ima2 multimode "<prompt>" --max-images 4` | Same prompt, want structurally different directions | SSE streaming, slot-by-slot progress, each slot is an independent generation |
+| **Independent CLI parallel** | Multiple `ima2 gen` in background | Different prompts, or mixed providers/models | Each is a separate server request, fully independent |
+
+**Single-request batch** is fastest for same-prompt variations. **Multimode**
+is better when you want to see each candidate arrive and potentially cancel
+early. **Independent CLI parallel** is for concept exploration with different
+prompts or provider/model mixes.
+
+#### Independent CLI Parallel Recipe
+
+```bash
+# Launch 3 different prompts concurrently
+ima2 gen "editorial hero with serif headline" --quality high -o ./out/editorial.png &
+ima2 gen "product-led hero with device mockup" --quality high -o ./out/product.png &
+ima2 gen "abstract gradient hero with floating shapes" --quality high -o ./out/abstract.png &
+
+# Monitor active jobs
+ima2 ps --json
+
+# Cancel a job if a better candidate arrives first
+ima2 cancel <requestId>
+
+# Wait for all to finish
+wait
+```
+
+#### Monitoring and Cancellation
+
+For long-running generation (high quality, large size, video), monitor with:
+
+```bash
+# List active jobs with phase and elapsed time
+ima2 ps --json
+
+# Output: requestId, kind, phase, startedAt, prompt (truncated)
+# Cancel a stuck or unwanted job
+ima2 cancel <requestId>
+```
+
+#### Capacity Guard
+
+The ima2 server enforces a concurrent job limit (default: 24). When exceeded,
+requests return `TOO_MANY_JOBS` (HTTP 429) with `Retry-After: 5`. Agent
+pattern: check `ima2 ps --json` before launching a batch; if active job count
+is near the limit, wait or cancel low-priority jobs first.
+
+#### `ima2 gen` Fallback
+
+When ima2 is unavailable, the `ima2 gen` tool generates one image per call.
+For parallel exploration, generate sequentially and inspect each before the
+next. Multimode and independent CLI parallel have no `ima2 gen` equivalent;
+degrade to single-image iteration with prompt refinement between rounds.
+
+### Variant Selection Workflow (FE-ASSET-SELECT-01, DEFAULT)
+
+After generating multiple candidates (via `-n`, multimode, or independent
+parallel), select using a two-stage process:
+
+**Stage 1 — Exploration (broad):** Generate 3-5 candidates with different
+directions. Inspect all with `view_image`. Do not select yet.
+
+**Stage 2 — Synthesis (not winner-picking):** Do NOT pick one winner. Build
+an element ledger — for each design token (palette, composition, type
+treatment, hero visual, stat row, section rhythm), note WHICH candidate did
+it best and WHY. The final direction is assembled from the best elements
+across all candidates. This mirrors `ima2-uiux` UX-CONCEPT-GEN-01 step 3.
+
+#### Selection Scorecard
+
+Rate each candidate on these axes before synthesizing:
+
+| Axis | What to Check |
+|------|---------------|
+| Subject fidelity | Does the main subject match the brief? |
+| Composition | Framing, negative space, visual weight balance |
+| Palette | Color harmony, brand alignment, contrast |
+| Text render | Korean/English text legibility (if applicable) |
+| Asset-type fit | Right dimensions, crop safety, overlay space |
+| Technical quality | No artifacts, correct lighting, clean edges |
+
+#### `ima2 gen` Fallback
+
+With `ima2 gen`, generate 1-2 candidates, inspect with `view_image`, refine
+the prompt based on what is wrong, and iterate. The synthesis step still
+applies when comparing across iteration rounds.
+
+### Provider Routing (FE-ASSET-PROVIDER-01, DEFAULT)
+
+When ima2 is available with multiple providers configured, choose by asset type:
+
+| Asset Type | Recommended Provider | Why |
+|-----------|---------------------|-----|
+| Product hero, editorial, UI mockup | GPT OAuth (`--provider oauth`) | Best composition, text rendering, style control |
+| Trending/cultural reference needed | Grok (`--provider grok`) | Mandatory web search grounds the generation |
+| Budget draft, quick iteration | Gemini (`--provider gemini-api`) | Cheapest per-image cost |
+| High-fidelity product photo | GPT OAuth + `--quality high` | Best detail, lighting, material rendering |
+| Korean text in image | GPT OAuth + `--mode direct` | Best Hangul rendering with exact-text prompts |
+
+Override per-request only: `ima2 gen "prompt" --provider grok --model grok-imagine-image-quality`
+
+#### `ima2 gen` Fallback
+
+The `ima2 gen` tool uses a single provider (the Codex-native image generation
+path). No provider routing is needed; quality and style are controlled through
+prompt detail and the `quality` parameter alone.
+
+### Reference Image Workflow
+
+When a design reference, brand guide, or existing asset exists, always attach it:
+
+```bash
+# Style reference
+ima2 gen "<prompt>" --ref style-guide.png --quality high
+
+# Multiple references (composition + style)
+ima2 gen "<prompt>" --ref layout-ref.png --ref brand-colors.png --quality high
+```
+
+Label each reference's role in the prompt text: "Use Image 1 as composition
+reference. Use Image 2 as color/style reference."
+
+### Korean Text in Images
+
+When generating images with Korean text:
+- Write the exact Korean string in quotes: `"오늘의 추천"`, not "some Korean text"
+- Specify font style: `고딕체 (Gothic/Sans)` or `명조체 (Myeongjo/Serif)`
+- Specify placement and approximate size relative to the canvas
+- For mixed Korean + English, specify which script appears where
+- Verify rendered text after generation — garbled Hangul is common and must be caught
+
+### Asset Background Strategy (FE-ASSET-BG-01, DEFAULT)
+
+GPT Image 2 does not reliably produce true transparent (alpha) backgrounds.
+Requesting "transparent background" or "PNG with alpha" yields unpredictable
+results — sometimes a faint checkerboard pattern, sometimes a solid color
+pretending to be transparent. Use the solid-background-then-remove strategy:
+
+**Generation: pure solid background.**
+
+For cutout assets (icons, product shots, 3D objects, illustrations, logos,
+stickers, UI elements that must float over arbitrary backgrounds):
+
+```bash
+# Pure black background — best for light/reflective subjects (chrome, glass, metal)
+ima2 gen "3D render of a liquid chrome splash blob, organic starburst shape, \
+  mirror-polished surface with iridescent cyan and gold reflections. \
+  Floating on a PURE SOLID BLACK background. The background must be 100% flat \
+  pure black hex #000000. No checkerboard, no transparency pattern, no gradient, \
+  no floor plane, no shadow, no vignette, no ambient glow on the background." \
+  --quality high --size 1024x1024 --mode direct -o chrome-splash.png
+
+# Pure white background — best for dark/opaque subjects (products, dark UI elements)
+ima2 gen "Clean product photo of a matte black wireless earbud, centered, \
+  floating at slight angle. PURE SOLID WHITE background hex #ffffff. \
+  No shadow, no gradient, no surface, no reflection plane." \
+  --quality high --size 1024x1024 --mode direct -o earbud-cutout.png
+
+# Solid brand color background — when the target surface color is known
+ima2 gen "Flat illustration of a coffee cup with steam, centered. \
+  PURE SOLID background hex #f5f0eb (exact match required). \
+  No gradient, no texture, no shadow." \
+  --quality medium --size 512x512 --mode direct -o coffee-icon.png
+```
+
+**Background prompt rules:**
+- State the exact hex code and repeat the constraint: "PURE SOLID [color] background hex #XXXXXX"
+- Explicitly ban common AI additions: "No checkerboard, no transparency pattern, no gradient, no floor plane, no shadow, no vignette, no ambient glow"
+- Use `--mode direct` to prevent server-side prompt rewriting that might soften the constraint
+- Black works best for reflective/metallic/glass subjects; white for dark/matte subjects
+- Match the target page background color when the destination is known
+
+**Post-processing: background removal.**
+
+| Method | When to Use | How |
+|--------|-------------|-----|
+| **CSS `mix-blend-mode`** | Black bg → light page | `mix-blend-mode: screen` makes black transparent, keeps light content |
+| **CSS `mix-blend-mode`** | White bg → dark page | `mix-blend-mode: multiply` makes white transparent, keeps dark content |
+| **ima2 Canvas Mode** | Interactive cleanup | Open in Canvas Mode → background cleanup → export with alpha or matte |
+| **Programmatic removal** | Build pipeline | `sharp` / ImageMagick / rembg for batch processing |
+| **ima2 edit** | Targeted fix | `ima2 edit asset.png --prompt "remove the background completely, keep only the [subject]"` |
+
+**CSS blend-mode recipe (zero post-processing):**
+
+```css
+/* Black background asset on a light page */
+.chrome-asset {
+  mix-blend-mode: screen;  /* black → transparent, light content preserved */
+}
+
+/* White background asset on a dark page */
+.product-asset {
+  mix-blend-mode: multiply;  /* white → transparent, dark content preserved */
+}
+
+/* For arbitrary backgrounds, layer with isolation */
+.asset-container {
+  isolation: isolate;  /* prevent blend from leaking to parent */
+}
+```
+
+**`ima2 gen` fallback:** same solid-background prompting strategy applies.
+No Canvas Mode available; use CSS blend modes or programmatic removal only.
+
+**Anti-pattern:** requesting "transparent background" or "PNG with alpha channel"
+directly in the prompt. The model will often produce a fake checkerboard pattern
+burned into the image, or ignore the request entirely. Always use the
+solid-background strategy above.
+
+### Prompt Iteration
+
+- Start with one high-detail prompt. Inspect the result with `view_image`.
+- On the next iteration, make ONE targeted change and re-specify all constraints.
+  Do not rewrite the entire prompt from scratch.
+- Repeat invariants every iteration to prevent drift.
+- If the model consistently fails on a detail, try rephrasing or breaking the
+  request into a base generation + edit pass.
+
+### Frontend Asset Quick Recipes
+
+**Hero image (landing page):**
+```bash
+ima2 gen "Use case: product-mockup. Asset type: landing page hero. A premium wireless headphone floating at a slight angle against a soft warm-gray studio backdrop. Matte black finish with brushed aluminum accents. Soft three-point studio lighting, key light from upper-left. Shallow depth of field. Wide composition with generous negative space on the right for headline overlay. No text, no logos, no watermark." \
+  --quality high --size 1536x1024 -o hero.png
+```
+
+**OG / social share image:**
+```bash
+ima2 gen "Use case: ads-marketing. Asset type: social share card. Clean product flat-lay of a notebook, pen, and ceramic mug on a white marble desk. Overhead shot. Soft diffused daylight. Space in the upper third for title overlay. Warm neutral palette. No text, no logos, no watermark." \
+  --quality high --size 1200x640 -o og-image.png
+```
+
+**App screenshot mockup background:**
+```bash
+ima2 gen "Use case: stylized-concept. Asset type: hero background for device mockup. Soft abstract gradient from #f0f4f8 to #dbeafe with subtle geometric shapes at 5% opacity. Clean, modern, minimal. No objects, no patterns, no text." \
+  --quality medium --size 1920x1088 -o mockup-bg.png
+```
+
+**Avatar / profile placeholder:**
+```bash
+ima2 gen "Use case: stylized-concept. Asset type: user avatar. Friendly stylized portrait of a young professional, neutral expression, looking slightly left. Flat illustration style with subtle shadows. Solid #e5e7eb background. Circular crop safe. No text." \
+  --quality medium --size 512x512 -o avatar.png
+```