@rovela-ai/sdk 0.19.3 → 0.19.5

package/templates/store-template/.claude/skills/customize-theme/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: customize-theme
+description: Use when the user asks to change colors, fonts, spacing, layout, shadows, borders, or any visual styling. Covers CSS variables, globals.css, tailwind.config.ts, and theme tokens.
+---
+
+# Theme Customization
+
+> **Scope: STOREFRONT only.** Everything in this skill (these tokens, `globals.css` variables, Tailwind classes like `text-muted-foreground`/`bg-card`) styles the customer-facing store. The `/admin` dashboard has its OWN design system — `hsl(var(--admin-*))` tokens + `admin-*` classes, governed by CLAUDE.md §7.6 — and storefront tokens must never be used there.
+
+## Key Files
+
+- `/app/app/globals.css` — CSS variables (`:root` and `.dark` blocks)
+- `/app/tailwind.config.ts` — Maps CSS variables to Tailwind classes
+- `/app/.rovela/blueprint.json` — Original theme specification
+
+## CSS Variable System
+
+The theme uses HSL CSS variables. All colors are defined as `H S% L%` values (no `hsl()` wrapper — Tailwind adds it).
+
+### Color Variables in globals.css
+
+```css
+:root {
+  --background: 0 0% 100%;
+  --foreground: 0 0% 3.9%;
+  --primary: 0 0% 9%;
+  --primary-foreground: 0 0% 98%;
+  --secondary: 0 0% 96.1%;
+  --secondary-foreground: 0 0% 9%;
+  --muted: 0 0% 96.1%;
+  --muted-foreground: 0 0% 45.1%;
+  --accent: 0 0% 96.1%;
+  --accent-foreground: 0 0% 9%;
+  --destructive: 0 84.2% 60.2%;
+  --destructive-foreground: 0 0% 98%;
+  --border: 0 0% 89.8%;
+  --input: 0 0% 89.8%;
+  --ring: 0 0% 3.9%;
+  --card: 0 0% 100%;
+  --card-foreground: 0 0% 3.9%;
+  --popover: 0 0% 100%;
+  --popover-foreground: 0 0% 3.9%;
+  --radius: 0.5rem;
+}
+```
+
+### Usage in Components
+
+```tsx
+// Correct — use semantic tokens
+<div className="bg-background text-foreground">
+<button className="bg-primary text-primary-foreground">
+<p className="text-muted-foreground">
+<div className="border border-border rounded-lg">
+
+// Wrong — hardcoded colors bypass theming
+<div className="bg-white text-black">
+```
+
+## How to Change Colors
+
+1. Read `/app/app/globals.css` to see current values
+2. Modify the HSL values in `:root` (and `.dark` if dark mode exists)
+3. Run error check after saving
+
+### Example: Change primary to blue
+
+```css
+/* Before */
+--primary: 0 0% 9%;
+/* After */
+--primary: 221 83% 53%;
+```
+
+## How to Change Fonts
+
+1. Fonts are loaded in `/app/app/layout.tsx` via `next/font/google`
+2. CSS variables `--font-heading` and `--font-body` are set in globals.css
+3. Update both the import AND the CSS variable
+
+### Example: Change heading font
+
+```tsx
+// In layout.tsx
+import { Playfair_Display } from 'next/font/google';
+const heading = Playfair_Display({ subsets: ['latin'], variable: '--font-heading' });
+```
+
+## How to Change Spacing/Radius
+
+Modify `--radius` in globals.css:
+- `0.25rem` — sharp/minimal
+- `0.5rem` — balanced (default)
+- `0.75rem` — rounded
+- `1rem` — very rounded
+
+## Responsive Design Rules
+
+- Mobile-first: base styles for 320px, then `sm:`, `md:`, `lg:` breakpoints
+- Touch targets: minimum 44x44px for buttons and links
+- Body text: minimum 16px (prevents iOS zoom)
+- Use `flex-wrap` and responsive grids, never horizontal scroll
+
+## Brand-Expression Tokens — the polished feel layer
+
+Beyond the shadcn color variables, every store should ship a fixed scaffold of brand-expression CSS variables in `globals.css` `:root`. These are the named primitives that separate a generic shadcn theme from a brand-expressive one. Same names every store, values per-brand.
+
+```css
+:root {
+  /* shadcn color base (--primary, --background, etc.) above */
+
+  --primary-glow: [lighter HSL of primary, typically primary-300 from the derived scale];
+  --gradient-primary: linear-gradient(135deg, hsl(var(--primary)), hsl(var(--primary-glow)));
+  --gradient-subtle: linear-gradient(180deg, hsl(var(--background)), hsl(var(--muted)));
+  --shadow-elegant: 0 10px 30px -10px hsl(var(--primary) / 0.3);
+  --shadow-glow: 0 0 40px hsl(var(--primary-glow) / 0.4);
+  --transition-smooth: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+}
+```
+
+### When the merchant asks for a polished feel
+
+If the merchant asks to "make the hero feel more premium" / "add a glow to the CTAs" / "make this feel more designed" — reach for these tokens FIRST before inventing new ones.
+
+Usage examples:
+
+```tsx
+// Hero CTA — brand-tinted shadow, smooth transition
+<Button
+  style={{ background: 'var(--gradient-primary)', boxShadow: 'var(--shadow-elegant)', transition: 'var(--transition-smooth)' }}
+  className="hover:[box-shadow:var(--shadow-glow)]"
+>
+  Shop now
+</Button>
+
+// Section with layered subtle gradient background
+<section style={{ background: 'var(--gradient-subtle)' }}>
+  ...
+</section>
+
+// Card with brand-glow halo
+<Card className="shadow-[var(--shadow-glow)] transition-[var(--transition-smooth)]">
+  ...
+</Card>
+```
+
+### Iteration rule
+
+If a section feels generic mid-build, revisit `globals.css` + `tailwind.config.ts` to deepen these tokens (e.g. add `--gradient-radial-hero` for a specific section). NEVER change the merchant-frozen primary / secondary / heading / body — those are pinned by the platform per the Design Source of Truth routing in `/app/CLAUDE.md` §4. "Deepening" means adding expression tokens, not swapping brand identity.
+
+## Editorial Accent — off-palette color, one specific section
+
+If `theme_essentials.editorialAccent` is set in the brief, that hex is used at ONE specific location named in `editorialAccent.usage`. It is NOT bled across the page — it's an editorial moment, not a brand color. Examples:
+- Warm coffee brand (brown + cream primaries) + sage editorial accent on the pull-quote ribbon
+- Minimalist tech (black + white primaries) + warm amber editorial accent on the newsletter strip
+
+When the merchant asks to "add a pop color" or "make the pull-quote section feel different," check if `editorialAccent` is set first — use it. If not set, propose a new one consistent with the chromatic story and update `globals.css` with a comment noting the single-use intent.
+
+## Photography Style Lock — keep imagery cohesive
+
+If `theme_essentials.photographyStyleLock` is set (5 axes: camera, lighting, composition, tone, subject), ALL image generation prompts MUST reuse those 5 axes verbatim. Only the subject-specific details vary per image; the rest stays constant.
+
+When merchant asks "regenerate the hero photo" — keep the same STYLE LOCK, change only the subject specifics.
+
+When merchant asks "make the photos feel more Aesop" — apply the `aesop-coded` PHOTOGRAPHY_STYLE_TEMPLATE (Hasselblad-coded medium format 80mm prime, north-window natural light 4500K, three-quarter view with generous negative space, warm cream/sepia tone, raw materials no people) and store the 5 axes in the brief's style lock for future iterations.
+
+Other named templates: `glossier-coded`, `brutalist-raw`, `editorial-fashion`, `minimalist-product`, `studio-soft`, `documentary-natural`, `bright-saturated-pop`.

package/templates/store-template/.claude/skills/debug-errors/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: debug-errors
+description: Use when something is broken, not working, showing errors, or the user reports a bug. Covers the get_errors, read, fix, verify debugging loop.
+---
+
+# Debug & Fix Errors
+
+## Primary Tool
+
+Use `get_errors` via next-devtools MCP for instant error checking (under 1 second).
+
+**Never** run `npm run build` for error checking — it takes 30-60 seconds. Use `get_errors` instead.
+
+## Debugging Workflow
+
+1. **Check errors**: Run `get_errors` to see current TypeScript/compilation errors
+2. **Read the file**: Read the relevant file(s) to understand the current implementation
+3. **Identify root cause**: Look for the actual source of the issue, not just symptoms
+4. **Make minimal fix**: Targeted changes only — avoid modifying unrelated code
+5. **Verify fix**: Run `get_errors` again to confirm zero errors
+6. **Check regressions**: Ensure related functionality still works
+
+## Common Error Patterns
+
+### Missing 'use client' Directive
+**Symptom**: "useState is not defined" or "onClick handler in server component"
+**Fix**: Add `'use client'` at the top of components using hooks or event handlers
+
+### Import Resolution Errors
+**Symptom**: "Module not found" or "Cannot find module"
+**Fix**: Check SDK import paths against CLAUDE.md. Common mistake: wrong subpath.
+```tsx
+// Wrong
+import { ProductCard } from '@rovela-ai/sdk'
+// Correct
+import { ProductCard } from '@rovela-ai/sdk/products'
+```
+
+### Type Errors
+**Symptom**: "Type X is not assignable to type Y"
+**Fix**: Define proper interfaces for props. Check component prop types.
+```tsx
+interface Props {
+  title: string;
+  onClick: () => void;
+}
+```
+
+### Tailwind Class Errors
+**Symptom**: Styles not applying or build warnings
+**Fix**: Common mistake — `border-border` is invalid. Use `border` for border color with `border-border` for the utility.
+
+### SDK Hook Errors
+**Symptom**: Hook errors mentioning SDK files
+**Fix**: The issue is likely in YOUR code, not the SDK. SDK internals are pre-validated. Focus debugging on files in `/app`.
+
+## Stale Cache Issues
+
+If errors persist after fixing, clear the build cache:
+```
+nextjs_call with port="3000", toolName="clear_cache"
+```
+
+Then run `get_errors` again.
+
+## When to Use npm run build
+
+Only as **final verification** after all `get_errors` checks pass. Never use it as the primary debugging tool.

package/templates/store-template/.claude/skills/frontend-design/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
+---
+
+> **Languages**: on multilingual stores (`store_settings.enabled_locales` has
+> more than one entry), every user-visible string must be authored in ALL
+> enabled languages via the store dictionary (CLAUDE.md §5.5). Internal links
+> always use `LocaleLink` from `@rovela-ai/sdk/core`.
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
+
+## Content Voice — short, specific, sounds-human
+
+The merchant will replace most copy with their own product details. Your job is short, specific placeholder content that demonstrates voice and structure — not paragraphs the merchant has to delete before they can think. This applies to BOTH initial generation AND chat-edit rewrites.
+
+**Length caps (hard, per section):**
+- Hero: headline ≤ 8 words. Subhead ≤ 14 words. NO additional paragraph below the subhead.
+- Features: 3–4 cards. Each card: title ≤ 4 words + description ≤ 16 words. Total feature prose ≤ 80 words.
+- Trust / About: 2–3 sentences, ≤ 80 words total. No three-paragraph "Our story" essay. No "Founded in..." preamble unless the merchant actually said so.
+- CTA: headline ≤ 8 words. Subhead ≤ 12 words. Button label ≤ 3 words.
+- FAQ (when included): question ≤ 12 words, answer ≤ 30 words, max 5 entries.
+
+**Banned vocabulary (AI tells — do NOT use in storefront copy):**
+elevate, enhance, delve, embrace, embark, leverage, unlock, navigate, harness, streamline, optimize, seamless, robust, transform, empower, discover, unveil, journey, treasure trove, game-changer, world-class, cutting-edge, next-generation, premium, modern, clean, sophisticated, elevated.
+
+**Banned structures:**
+- "Not just X — it's Y" / "It's not about X, it's about Y" (AI negation cliché).
+- "In today's world..." / "In the digital age..." (throat-clearing preambles).
+- Em-dash overuse: max 1 em-dash per section.
+- Generic adjective stacks ("premium, modern, clean") — guaranteed AI tell.
+
+**Write like a human who knows the product:**
+- Specifics over abstractions: "hand-stitched Italian calfskin" beats "premium leather."
+- Real numbers, names, places: "ships in 4 days from Brooklyn" beats "fast shipping."
+- Verbs over adjectives: "roasted in small batches" beats "high-quality coffee."
+- Sensory details for taste/feel/touch: "tastes of charred sugar and tobacco" beats "rich flavor."
+- Plain English: "for people who" beats "designed for the discerning individual who."
+
+Source the specifics from the merchant's business_description in CLAUDE.md §2 first. If the merchant wrote one good concrete sentence, lift that language verbatim or close. The brief's `brand_essentials.voice.vocabulary.preferred` list is the safe phrase pool; `vocabulary.avoid` is the additional per-merchant banned list on top of the universal one above.
+
+**Chat-edit application**: when the merchant asks you to rewrite a section ("make the hero punchier", "shorten this", "less AI-sounding"), the same caps apply. Going OVER cap is a regression — never lengthen unless the merchant explicitly asked for more copy.
+
+## Aesthetic Ritual — commit before you code
+
+Before writing any major redesign or new section, pause and write a 4-bullet commitment in your narration. This forces concrete decisions and prevents drift to safe defaults. This applies to BOTH initial generation AND chat-edit redesigns ("make the hero more premium", "redesign this section to feel editorial").
+
+1. **What this brand evokes** — one sentence. Concrete, sensory, specific. NOT "premium / modern / clean."
+2. **Design inspirations** — one sentence. If the merchant referenced specific designs or supplied screenshots, those ARE your inspirations; name them. Otherwise name 1–2 specific influences (an aesthetic era, a specific brand category, a material world).
+3. **Palette commitment** — list the primary + secondary + accent hex codes you're committing to. If editing, confirm the existing palette OR propose specific replacements with reasoning.
+4. **Motion commitment** — list the 2–3 specific motion moments you'll implement (entrance, hover, signature). Cite ms timings.
+
+## Component Customization Pattern — variants, not inline overrides
+
+When customizing buttons / cards / pills / badges from shadcn or the SDK, CREATE NEW cva variants using semantic tokens. Variant definitions live in the component file's cva() block.
+
+```tsx
+// ✅ CORRECT — new variant lives in the component
+const buttonVariants = cva("...", {
+  variants: {
+    variant: {
+      default: "bg-primary text-primary-foreground hover:bg-primary/90",
+      hero: "bg-gradient-primary text-primary-foreground shadow-elegant hover:shadow-glow transition-smooth",
+      editorial: "bg-transparent border border-foreground/20 text-foreground hover:bg-foreground hover:text-background",
+    },
+  },
+});
+
+// At the call site:
+<Button variant="hero">Shop now</Button>
+```
+
+```tsx
+// ❌ WRONG — inline overrides bypass the design system
+<Button className="bg-primary/90 hover:bg-primary text-white px-6 shadow-xl">
+  Shop now
+</Button>
+```
+
+Inline raw-class overrides at call sites rot. Variants compose, stay coherent across chat-edits, and let the design system evolve as a single unit.
+
+## Contrast Trap — real bug-class warning
+
+When alternating section backgrounds (background → muted → card → background), verify text contrast in BOTH light AND dark modes. White text on bg-muted in light-mode often disappears; dark text on bg-card in dark-mode often does too. Sanity-check every section-pair you ship — this is the single most common visual bug class.
+
+## Layout Vocabulary — pattern catalog for chat-edits
+
+When the merchant asks to change a section's layout (e.g. "make the hero more editorial" / "switch the products to a bento grid" / "this footer feels generic, can it be more like Aesop's"), look up the named pattern from one of these catalogs and apply the matching skeleton.
+
+**HERO PATTERNS** (9):
+- `split` — text + image side-by-side, equal weight
+- `center` — text-only, vertically stacked, max-w-3xl
+- `bg-image` — full-bleed photographic bg + text overlay
+- `immersive` — viewport-height with full-bleed bg; cinematic
+- `editorial` — asymmetric magazine, oversized type on non-center column, image floats
+- `bento` — compartmentalized grid hero (4-6 tiles, one large + smaller + text card)
+- `type-first` — kinetic huge typography dominates; size jump 5×+
+- `parallax-bg` — full-bleed with CSS 3D parallax (translateZ + perspective)
+- `video-bg` — variant of immersive with autoPlay/muted/loop/playsInline video
+
+**SECTION SEPARATION** (6):
+- `soft` — subtle bg-color shifts, no borders
+- `clean` — distinct stripes with whitespace/thin borders
+- `cards` — every section wrapped in card chrome
+- `editorial-interleave` — non-commerce section every 2 commerce (pull-quote / craft vignette / founder photo)
+- `scroll-snap` — full-page snap sections (scroll-snap-type: y mandatory)
+- `asymmetric-alt` — alternate left → right → full-bleed → center
+
+**PRODUCT SHOWCASE** (6):
+- `grid` — uniform 3-col responsive grid
+- `list` — vertical full-width rows
+- `lookbook` — asymmetric, one hero + smaller tiles
+- `editorial-2col` — magazine spread, product + prose alternating
+- `horizontal-snap` — horizontal scroll-snap carousel
+- `bento-grid` — hero product + smaller tiles + ONE text/copy card peer
+
+**HEADER PATTERNS** (5):
+- `transparent-to-solid` — transparent on load, solidifies on scroll
+- `sticky-condensed` — shrinks + condenses after 80px scroll
+- `mega-menu` — compact top + rich hover mega-menus (Stripe-style)
+- `editorial-minimal` — centered logo, sparse nav, no utility row (Aesop)
+- `utility-first` — cart + search prominent, nav secondary
+
+**FOOTER PATTERNS** (4):
+- `editorial-massive` — multi-column newsletter + values + craft-story + sitemap
+- `minimal-utility` — logo + 5 links + copyright, one row
+- `newsletter-first` — newsletter dominates, sitemap secondary
+- `brand-narrative` — long-form brand-story prose body (Aesop)
+
+**TYPOGRAPHY MODES** (5):
+- `decorative` — standard hierarchy, conservative
+- `kinetic` — aggressive jumps 5×+, weight extremes (300/900), animated stagger
+- `editorial-display` — refined oversized display (200 or 700), generous tracking, slow fade
+- `marquee` — scrolling type bands as brand statement
+- `variable-axis` — variable fonts with weight/width transitions tied to scroll
+
+**SIGNATURE MOVES** (12 named): slow-page-fade, cursor-halo, scroll-progress-bar, parallax-vertical-mark, letter-stagger-reveal, color-shift-on-scroll, sticky-cta-reveal, marquee-headline, ambient-grain, intersection-reveal, custom-cursor, page-load-stagger. Pick ONE per store; CSS-only when possible; respect `prefers-reduced-motion`.
+
+**SIGNATURE COMPONENT CATEGORIES** (7): decorative-divider, custom-product-card, themed-indicator, narrative-interlude, signature-button, decorative-frame, parallax-mark.
+
+When CLAUDE.md §4's Design Source of Truth routing table names a pattern, that pattern is FROZEN — do not propose alternatives unless the merchant explicitly asks to change it.

package/templates/store-template/.claude/skills/generate-images/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: generate-images
+description: Use when generating visual assets (hero, product photos, feature graphics, section backgrounds, testimonial headshots) for a store. Covers the mcp__r2__generate_image tool, aspect ratios per section, prompt writing, filename conventions, and the gradient fallback. Triggers on any mention of image generation, hero image, product photos, or missing visuals.
+---
+
+# Generate Images
+
+## Rule zero
+
+**Call `mcp__r2__generate_image` directly from this skill's execution context, in sequence.** Directly-spawned `Agent`/`Task` subagents outside of skill context do not reliably inherit MCP tool access (github anthropics/claude-code #7296, #38920) — delegation outside this skill means silent failure and missing images. Inside this skill, calls you make execute in a context that has MCP access, so just call the tool directly.
+
+## When to generate
+
+| Surface | Count (typical full homepage) |
+|---|---|
+| **Hero** — background or foreground image | 1 |
+| **Features** — one image per feature card | 1–3 of the most visual cards |
+| **Products** — photo per seed product if no image provided | 1 per product |
+| **Testimonials** — headshots (optional, brand-dependent) | 0–1 |
+| **Trust / other sections** | Only if the blueprint requests imagery |
+
+Total: around 5–6 `mcp__r2__generate_image` calls for a typical full homepage generation. Sequential. ~30–45 seconds total.
+
+## Prompt format
+
+40–75 words. Anchor on the Visual Creative Brief in CLAUDE.md §4 (personality, color philosophy, imagery direction). Include photography terminology: lighting, angle, subject, mood, color palette, lens, texture.
+
+Example (Cofme — editorial Parisian atelier):
+
+> Editorial Parisian atelier, unmade silk pillows in dusty rose and cream, morning light streaming through tall windows, warm bronze accents, shallow depth of field, soft grainy texture, 85mm portrait lens, 4:3 aspect ratio.
+
+Example (Tech / SaaS store):
+
+> Minimal product flat-lay on matte charcoal surface, single cyan accent light from upper-left, subtle blue gradient background, precise geometric composition, studio lighting with soft shadows, 50mm macro lens, 1:1 square aspect ratio.
+
+## Aspect ratios by context
+
+| Context | Aspect | Notes |
+|---|---|---|
+| Hero — full-screen layout | 16:9 | Landscape, widescreen |
+| Hero — split layout | 3:4 | Portrait side panel |
+| Feature card | 4:3 | Balanced landscape |
+| Product photo | 1:1 | Square grid |
+| Testimonial portrait | 1:1 | Square headshot |
+| Section background | 16:9 | Wide background |
+
+Pass the aspect ratio both in the prompt text AND as the `aspect_ratio` parameter to `mcp__r2__generate_image`.
+
+## Filename convention
+
+`{section}-{index}-{slug}.webp` — for example `hero-1-atelier.webp`, `feature-2-bespoke-pillows.webp`, `product-3-silk-cream.webp`. Human-readable and visible in R2 storage when debugging.
+
+## Fallback on error
+
+If `mcp__r2__generate_image` returns an error (Gemini rate limit, safety block, timeout), use a CSS gradient with the brand primary colors from the Visual Creative Brief. **Never** hardcode external URLs (Unsplash, placeholder.com, picsum.photos). **Never** leave a broken `<img>` tag.
+
+```tsx
+// Fallback pattern — no broken images, no external URLs
+<div className="bg-gradient-to-br from-primary/20 via-primary/10 to-transparent h-full w-full" />
+```
+
+## Canonical call sequence for a full homepage
+
+**Preferred — single batched call** (`mcp__r2__generate_images`, plural):
+
+```
+mcp__r2__generate_images({
+  images: [
+    { prompt: "...", filename: "hero-1-{slug}",       aspect_ratio: "16:9" },
+    { prompt: "...", filename: "feature-1-{slug}",    aspect_ratio: "4:3" },
+    { prompt: "...", filename: "feature-2-{slug}",    aspect_ratio: "4:3" },
+    { prompt: "...", filename: "feature-3-{slug}",    aspect_ratio: "4:3" },
+    { prompt: "...", filename: "about-1-{slug}",      aspect_ratio: "4:3" },
+    { prompt: "...", filename: "product-1-{slug}",    aspect_ratio: "1:1" },
+    { prompt: "...", filename: "product-2-{slug}",    aspect_ratio: "1:1" },
+    { prompt: "...", filename: "product-3-{slug}",    aspect_ratio: "1:1" },
+  ]
+})
+```
+
+Returns `{ images: [{ success, url?, key?, size?, error? }, ...] }` preserving input order. The server fans out at concurrency 4 → typical 8-image batch lands in ~12s wall-clock vs ~48s sequential. **Use this for the initial homepage build whenever you have 3+ images planned up front.** Max 12 entries per call.
+
+**Per-entry fallback contract is unchanged** — if `images[i].success === false`, use a CSS gradient for that one image only and continue with the rest. Don't abort the page over one Gemini error.
+
+**Singular `mcp__r2__generate_image` is still preferred for:**
+
+- Edit-mode iteration (merchant asks "regenerate just the hero" — one image at a time)
+- Workflows where the prompt for image N depends on what image N-1 produced
+- <3 images total
+
+**Sequential singular fallback** (if `generate_images` ever returns an error for the whole call):
+
+```
+1. mcp__r2__generate_image — hero (16:9 or 3:4 depending on layout)
+2. mcp__r2__generate_image — feature 1 (4:3)
+3. mcp__r2__generate_image — feature 2 (4:3)
+...
+```
+
+Call them one after the other in THIS session. Not via Agent/Task. ~6s each, ~30-45s total for a homepage — slower than the plural batch but guaranteed-compatible with older sandbox images.
+
+## Common anti-patterns
+
+- ❌ `Agent(prompt="Generate 5 images via mcp__r2__generate_image")` outside this skill → subagent won't have MCP access, silent failure
+- ❌ "I'll use Task in parallel to generate all images outside the skill" → don't; stay inside this skill's execution
+- ❌ Using singular `generate_image` 8 times in a row for a homepage build → use the plural tool instead, saves ~30s of wall-clock
+- ❌ Using plural `generate_images` for a single-image edit-mode iteration → wasteful, use singular
+- ❌ Treating `generate_images` whole-call failure differently from per-image failure → check `images[i].success` per entry, not the call's outer success
+- ❌ Using `imageUrl` from blueprint without checking if it's null/empty
+- ❌ `src="https://images.unsplash.com/..."` or any other external URL
+- ❌ Leaving `<img>` without src — always either a generated URL or replace with a gradient `<div>`
+- ✅ One plural `mcp__r2__generate_images` call for the initial homepage build
+- ✅ One-by-one singular `mcp__r2__generate_image` calls for edit-mode iteration
+- ✅ Brand-specific scene descriptions drawn from the Visual Creative Brief
+- ✅ Gradient `<div>` fallback if a single image's `success` is `false`