appshot-cli 1.0.2 → 2.0.0

package/README.md

@@ -10,19 +10,13 @@
 [![Node.js Version](https://img.shields.io/node/v/appshot-cli.svg)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-🆕 **Version 1.0.0** - **MCP Server & Agent-First Architecture**
+🆕 **Version 2.0.0** - **Layout v2 + Agent-First Architecture**
 - **MCP Server**: Full Model Context Protocol support for AI agents (Claude Desktop, Claude Code, etc.)
-- **17 MCP Tools**: Complete coverage - init, build, captions, gradients, backgrounds, fonts, config, validate, specs, doctor, presets, localize, languages, frame, export, clean, projectInfo
+- **20 MCP Tools**: Complete coverage - init, build, wizard, quickstart, template, captions, gradients, backgrounds, fonts, config, validate, specs, doctor, presets, localize, languages, frame, export, clean, projectInfo
 - **Claude Code Skill**: Install with `appshot skill` - includes templates, troubleshooting guides
 - **Auto-Caption**: Generate captions from filenames with `--auto-caption` or MCP `action: "auto"`
 - **Direct Tool Access**: Agents can manage entire screenshot workflows without shell access
 
-**Version 0.9.x** - **Layout Engine, Templates & Fastlane**
-- **Fastlane Export**: Seamless integration with `appshot export` and screenshot ordering
-- **8 Professional Templates**: modern, minimal, bold, elegant, showcase, playful, corporate, nerdy
-- **Unified Layout Engine**: Single planner for all caption/device combinations
-- **Safety Insets**: Automatic 40px protection for App Store cropping
-
 ## 📖 Table of Contents
 
 - [Why Appshot?](#-why-appshot)
@@ -30,7 +24,9 @@
 - [Quick Start](#-quick-start)
   - [Prerequisites](#prerequisites)
   - [Installation](#installation)
+  - [Wizard (Recommended)](#wizard-recommended)
   - [Your First Screenshot](#your-first-screenshot)
+  - [Cleaning & Reset](#cleaning--reset)
 - [MCP Server & Agent Integration](#-mcp-server--agent-integration)
 - [Core Concepts](#-core-concepts)
 - [Visual Customization](#-visual-customization)
@@ -38,7 +34,6 @@
   - [Font System](#font-system)
   - [Device Frames](#device-frames)
   - [Caption System](#caption-system)
-  - [Style System Guide](#style-system-guide)
 - [Localization & Translation](#-localization--translation)
 - [Device Support](#-device-support)
 - [Fastlane Integration](#-fastlane-integration)
@@ -55,7 +50,7 @@
 
 Appshot is the only **agent-first CLI tool** designed for automated App Store screenshot generation. Built for LLM agents, CI/CD pipelines, and developers who value automation over GUIs.
 
-**NEW in v0.9.0**: One-line preset commands! Generate professional screenshots instantly with `appshot preset bold --caption "Amazing App" --devices iphone,watch`
+**NEW in v2.0.0**: Fixed layout zones and v2 templates for clean, predictable screenshots out of the box.
 
 ### Key Differentiators
 
@@ -66,6 +61,20 @@ Appshot is the only **agent-first CLI tool** designed for automated App Store sc
 - ⚡ **Fast & Parallel** - Process hundreds of screenshots with configurable concurrency
 - 🛠️ **Pure CLI** - No web UI, no GUI, just predictable commands perfect for automation
 
+## 📱 iPhone Screenshot Examples (v2)
+
+These are generated by the v2 templates included in `template-samples/iphone/`:
+
+| Ocean Header | Sunset Footer | Clean Screenshot |
+| --- | --- | --- |
+| ![Ocean Header](template-samples/iphone/ocean-header-iphone.png) | ![Sunset Footer](template-samples/iphone/sunset-footer-iphone.png) | ![Clean Screenshot](template-samples/iphone/clean-screenshot-iphone.png) |
+| Pastel Header | Noir Footer | Silver Header |
+| ![Pastel Header](template-samples/iphone/pastel-header-iphone.png) | ![Noir Footer](template-samples/iphone/noir-footer-iphone.png) | ![Silver Header](template-samples/iphone/silver-header-iphone.png) |
+| Slate Footer | Midnight Header | Tropical Header |
+| ![Slate Footer](template-samples/iphone/slate-footer-iphone.png) | ![Midnight Header](template-samples/iphone/midnight-header-iphone.png) | ![Tropical Header](template-samples/iphone/tropical-header-iphone.png) |
+
+> For the full template gallery, open `template-samples/index.html`.
+
 ## ✨ Features
 
 - 🖼️ **Smart Frames** - Automatically detects portrait/landscape and selects appropriate device frame
@@ -89,7 +98,7 @@ Appshot is the only **agent-first CLI tool** designed for automated App Store sc
 
 ### Prerequisites
 
-- **Node.js 16+** - Required for ESM modules
+- **Node.js 18+** - Required for ESM modules
 - **npm** or **yarn** - Package manager
 - **Operating System** - macOS, Linux, or Windows
 - **Optional**: OpenAI API key for translation features
@@ -109,6 +118,25 @@ appshot --version
 
 > **Note**: The package is called `appshot-cli` on NPM, but the command is `appshot`
 
+### Wizard (Recommended)
+
+The wizard is the fastest way to get v2 screenshots, because it:
+- **Applies a template** (optional) for layout + background + caption styling
+- **Auto-detects orientation** from your screenshots and sets `resolution`
+- **Generates captions** (from filenames or manual entry)
+- **Localizes + enhances** (optional)
+- **Builds** in one pass
+
+```bash
+# Interactive wizard (templates included)
+appshot wizard
+
+# Non-interactive (CI)
+appshot wizard --no-interactive --devices iphone,ipad --template ocean-header --caption-source filenames --langs en,es,fr
+```
+
+> **Tip:** If no screenshots exist yet, the wizard keeps `resolution` unset so build uses the real screenshot dimensions later.
+
 ### Your First Screenshot - Two Ways
 
 #### Option 1: Quick Start with Templates (NEW! 🎨)
@@ -119,8 +147,11 @@ The fastest way to get professional screenshots:
 # One command interactive setup
 appshot quickstart
 
+# One-shot v2 flow (layout → captions → build)
+appshot wizard
+
 # Or apply a specific template
-appshot template modern --caption "Your Amazing App"
+appshot template ocean-header --caption "Your Amazing App"
 
 # Build your screenshots
 appshot build
@@ -197,6 +228,23 @@ final/
         └── dashboard.png  # 2048×2732 iPad Pro screenshot
 ```
 
+### Cleaning & Reset
+
+When you want a clean slate without deleting screenshots:
+
+```bash
+# Remove outputs + .appshot/ but keep screenshots/
+appshot clean --reset --yes
+
+# Remove outputs + .appshot/ + temp files
+appshot clean --all --yes
+
+# Clear caption history only
+appshot clean --history
+```
+
+`--reset` is safe for projects: it keeps `screenshots/` intact and wipes generated files.
+
 ## 🤖 MCP Server & Agent Integration
 
 Appshot provides a full Model Context Protocol (MCP) server, enabling AI agents like Claude Desktop and Claude Code to manage screenshot workflows directly through tool calls.
@@ -234,8 +282,11 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 |------|-------------|
 | `appshot_projectInfo` | Get project metadata (devices, languages, config) |
 | `appshot_init` | Initialize new project structure |
+| `appshot_quickstart` | Quick start setup with templates + captions |
+| `appshot_wizard` | One-shot v2 flow (template/layout → captions → translate/enhance → build) |
 | `appshot_build` | Generate final screenshots |
 | `appshot_frame` | Apply device frames only (transparent background) |
+| `appshot_template` | Apply v2 template presets |
 | `appshot_captions` | Read/write caption text, auto-generate from filenames |
 | `appshot_gradients` | List/apply gradient presets |
 | `appshot_backgrounds` | Configure background images |
@@ -268,13 +319,24 @@ Agent: I'll set up your App Store screenshots.
 **Auto-Caption Workflow** (generate captions from filenames):
 ```
 1. appshot_init with force: true
-2. appshot_template with template: "modern"
+2. appshot_template with template: "ocean-header"
 3. appshot_captions with device: "iphone", action: "auto"
 4. appshot_build with devices: ["iphone"]
 
 ✓ Captions auto-generated: "home-screen.png" → "Home Screen"
 ```
 
+**Wizard Workflow (single tool call):**
+```
+appshot_wizard with {
+  devices: ["iphone", "ipad"],
+  template: "ocean-header",
+  captionSource: "filenames",
+  languages: ["en", "es", "fr"],
+  noInteractive: true
+}
+```
+
 ### Claude Code Skill
 
 For Claude Code users, install the appshot skill for guided workflows:
@@ -292,9 +354,9 @@ appshot skill --uninstall
 
 The skill provides:
 - Project workflow guidance (init → captions → styling → build)
-- Template recommendations by app type (dev tools → nerdy, business → corporate)
+- Template recommendations by app type (dev tools → midnight-header, business → slate-footer)
 - Troubleshooting guide for common errors
-- Reference files for all 24 gradients, 10 fonts, and 8 templates
+- Reference files for all 24 gradients, 10 fonts, and 9 templates
 
 ### Agent-Friendly Features
 
@@ -305,7 +367,7 @@ The skill provides:
 
 ### Claude Desktop Support
 
-Claude Desktop is fully supported as of v1.0.1. Add appshot to your Claude Desktop configuration:
+Claude Desktop is fully supported as of v2.0.0. Add appshot to your Claude Desktop configuration:
 
 **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
 
@@ -320,12 +382,19 @@ Claude Desktop is fully supported as of v1.0.1. Add appshot to your Claude Deskt
 }
 ```
 
-Restart Claude Desktop after adding the configuration. All 19 MCP tools will be available.
+Restart Claude Desktop after adding the configuration. All MCP tools will be available.
 
 > **Tip:** When using Claude Desktop, always provide the full `configPath` parameter pointing to your project directory, since Claude Desktop runs from the home directory.
 
 ## 📘 Core Concepts
 
+🧭 **Layout v2** - **Fixed Zones + Three Layout Modes**
+- **Modes**: header, footer, screenshot-only (overlay removed)
+- **Fixed Regions**: Caption/device ratios are deterministic per device type
+- **Device-Based Font Scaling**: Text size scales by output resolution (iPad/Mac larger, Watch smaller)
+- **Config v2**: `version: 2` configs only allow styling, not layout proportions
+- **Docs**: See `docs/layout-v2.md` for full rules
+
 ### Project Structure
 
 Appshot creates and manages the following directory structure in your project:
@@ -374,23 +443,27 @@ All settings are stored in `.appshot/config.json`:
 
 ```json
 {
-  "output": "./final",
-  "gradient": {
-    "colors": ["#0077BE", "#33CCCC"],
-    "direction": "diagonal"
-  },
+  "version": 2,
+  "layout": "header",
   "caption": {
-    "font": "SF Pro",
-    "fontsize": 64,
-    "color": "#FFFFFF",
-    "position": "above"
+    "font": "SF Pro Display Bold",
+    "color": "#FFFFFF"
+  },
+  "background": {
+    "mode": "gradient",
+    "gradient": {
+      "colors": ["#0077BE", "#33CCCC"],
+      "direction": "diagonal"
+    }
   },
   "devices": {
     "iphone": {
-      "resolution": "1290x2796",
-      "autoFrame": true
+      "input": "./screenshots/iphone",
+      "resolution": "1290x2796"
     }
-  }
+  },
+  "output": "./final",
+  "frames": "./frames"
 }
 ```
 
@@ -404,9 +477,9 @@ All settings are stored in `.appshot/config.json`:
 
 ## 🎨 Visual Customization
 
-### Template System (NEW! 🚀)
+### Template System (v2)
 
-Appshot now includes professional screenshot templates that configure everything with a single command. Each template includes carefully designed backgrounds, device positioning, caption styling, and device-specific optimizations.
+Appshot v2 templates map to fixed layout modes (header/footer/screenshot-only) plus curated gradients and caption styling defaults. Layout proportions are deterministic per device and **not** user-adjustable in v2. Overlay mode is removed. See `docs/layout-v2.md` for the full rules.
 
 #### Quick Start with Templates
 
@@ -415,85 +488,59 @@ Appshot now includes professional screenshot templates that configure everything
 appshot quickstart
 
 # Apply a specific template
-appshot template modern
+appshot template ocean-header
 
 # Apply template with caption
-appshot template minimal --caption "Beautiful & Simple"
+appshot template pastel-header --caption "Beautiful & Simple"
 
 # Preview template settings
-appshot template --preview bold
+appshot template --preview noir-footer
 
 # List all templates
 appshot template --list
 ```
 
-#### Available Templates
-
-📸 **[View Template Gallery](./template-samples/index.html)** - See visual examples of all templates
+#### Available Templates (v2)
 
 | Template | Description | Best For |
 |----------|-------------|----------|
-| **modern** | Vibrant gradient with floating device and clean captions | Most apps, eye-catching |
-| **minimal** | Soft pastel background with elegant typography | Clean, simple apps |
-| **bold** | Dark dramatic gradient with overlay captions | Gaming, entertainment |
-| **elegant** | Sophisticated monochrome design | Professional, business |
-| **showcase** | Auto-detects custom backgrounds, partial frames | Apps with branded assets |
-| **playful** | Bright, fun gradients | Games, kids apps |
-| **corporate** | Clean, professional look | Business, productivity |
-| **nerdy** | JetBrains Mono typography with OSS grid background | Developer tools |
+| **ocean-header** | Cool blue gradient + header layout | General purpose |
+| **sunset-footer** | Warm sunset gradient + footer layout | Bold marketing |
+| **clean-screenshot** | Minimal background + screenshot-only | Product-focused |
+| **pastel-header** | Soft pastel gradient + header layout | Clean, friendly apps |
+| **noir-footer** | Dark dramatic gradient + footer layout | Entertainment, gaming |
+| **silver-header** | Elegant silver gradient + header layout | Professional apps |
+| **tropical-header** | Bright tropical gradient + header layout | Playful brands |
+| **slate-footer** | Professional slate gradient + footer layout | Business, productivity |
+| **midnight-header** | Deep blue gradient + header layout | Developer tools |
 
-![Template Gallery](./template-samples/gallery/template-gallery.png)
-
-##### Rebuild the Gallery Locally
-
-```bash
-# From repo root
-npm run samples
-```
+📸 **Template Gallery (v2)**: Open `template-samples/index.html` to browse the current v2 template gallery.
 
-This generates:
-- Device samples: `template-samples/{iphone|ipad|watch|mac}/<template>-<device>.png`
-- Gallery cards: `template-samples/gallery/*-sample.png`
-- Combined image: `template-samples/gallery/template-gallery.png`
-
-#### Template Features
+#### Template Features (v2)
 
 Each template automatically configures:
-- **Background**: Gradient colors and direction or image settings
-- **Device Scale**: Optimal size for visual balance (70-110%)
-- **Device Position**: Top, center, bottom, or custom percentage
-- **Caption Style**: Font, size, color, and position
-- **Caption Background**: Optional semi-transparent background with padding
-- **Caption Border**: Optional border with customizable radius
-- **Partial Frames**: Modern look with cut-off device bottoms
-- **Device Overrides**: Optimized settings for watch, iPad, etc.
+- **Layout Mode**: header, footer, or screenshot-only
+- **Background**: Gradient colors and direction
+- **Caption Style**: Font family, color, background, and opacity
+- **Device Strategies**: Fixed ratios, scaling, and line limits per device type
 
 #### Template Examples
 
 ```bash
-# Modern Template - Perfect for most apps
-appshot template modern
-# → Vibrant diagonal gradient (#667eea → #764ba2 → #f093fb)
-# → 85% device scale, centered
-# → White captions with dark semi-transparent background
-
-# Minimal Template - Clean and simple
-appshot template minimal  
-# → Soft pastel gradient (#ffecd2 → #fcb69f)
-# → 75% device scale, lower position
-# → Dark text on light background
+# Ocean Header - General purpose
+appshot template ocean-header
+# → Header layout + cool blue gradient
+# → Fixed zones, centered caption
 
-# Bold Template - Make a statement
-appshot template bold
-# → Dark gradient (#0f0c29 → #302b63 → #24243e)
-# → 110% device scale with partial frame
-# → Large overlay captions with border
+# Clean Screenshot - Product-forward
+appshot template clean-screenshot
+# → Screenshot-only layout
+# → Minimal background styling
 
-# Showcase Template - Feature your backgrounds
-appshot template showcase
-# → Auto-detects background.png in device folders
-# → 90% scale with 25% partial frame
-# → Glass-morphism caption effect
+# Noir Footer - Bold marketing
+appshot template noir-footer
+# → Footer layout + dark gradient
+# → High-contrast caption styling
 ```
 
 #### Customizing Templates
@@ -502,10 +549,10 @@ Templates provide a starting point that you can further customize:
 
 ```bash
 # 1. Apply a template
-appshot template modern
+appshot template ocean-header
 
-# 2. Fine-tune specific settings
-appshot style --device iphone  # Adjust positioning
+# 2. Adjust styling (layout proportions are fixed in v2)
+appshot style                 # Pick layout + gradient + caption color
 appshot fonts --set "Poppins Bold"  # Change font
 appshot caption --device iphone  # Update captions
 
@@ -844,266 +891,43 @@ When dimensions are ambiguous, use `--device` to specify the target device.
 
 ### Device Frames
 
-#### Smart Frame Selection
-
-Appshot automatically detects screenshot orientation and selects the appropriate frame:
-
-```json
-{
-  "devices": {
-    "iphone": {
-      "autoFrame": true,  // Auto-detect orientation
-      "preferredFrame": "iphone-16-pro-max-portrait"  // Override
-    }
-  }
-}
-```
-
-#### Partial Frames
-
-Create modern App Store screenshots with cut-off device frames:
-
-```json
-{
-  "devices": {
-    "iphone": {
-      "partialFrame": true,
-      "frameOffset": 25,      // Cut 25% from bottom
-      "framePosition": 40,    // Position at 40% from top
-      "frameScale": 0.85      // Scale to 85%
-    }
-  }
-}
-```
-
-#### Frame Positioning System
-
-**Important**: The `framePosition` value (0-100) behaves differently depending on your caption positioning mode.
-
-##### Relative vs Absolute Positioning
-
-When using `captionPosition: "above"` or `"below"`:
-- **Frame positioning is RELATIVE to the remaining space** after accounting for the caption
-- `framePosition: 0` = Top of available space (immediately after/before caption)
-- `framePosition: 50` = Center of remaining space
-- `framePosition: 100` = Bottom of available space
-
-When using `captionPosition: "overlay"`:
-- **Frame positioning is ABSOLUTE to the entire canvas**
-- `framePosition: 0` = Top of canvas (pixel 0)
-- `framePosition: 50` = Center of entire canvas
-- `framePosition: 100` = Bottom of canvas
-
-##### Visual Examples
-
-```json
-// Example 1: Caption above with framePosition: 0
-{
-  "devices": {
-    "iphone": {
-      "captionPosition": "above",
-      "framePosition": 0  // Device starts right after caption
-    }
-  }
-}
-// Result: [Caption] then [Device at top of remaining space]
-
-// Example 2: Caption overlay with framePosition: 0
-{
-  "devices": {
-    "iphone": {
-      "captionPosition": "overlay",
-      "framePosition": 0  // Device at absolute top
-    }
-  }
-}
-// Result: [Device at canvas top] with [Caption overlaid at bottom]
-```
-
-##### The Math Behind Positioning
-
-For **"above" mode**, the device position is calculated as:
-```
-deviceTop = topMargin + captionHeight + (availableSpace * framePosition/100)
-where availableSpace = canvasHeight - topMargin - captionHeight - bottomMargin - deviceHeight
-```
-
-For **"overlay" mode**, the device position is calculated as:
-```
-deviceTop = availableSpace * (framePosition/100)
-where availableSpace = canvasHeight - bottomMargin - deviceHeight
-```
-
-##### Practical Implications
-
-1. **Same framePosition, Different Results**: A `framePosition: 0` will place the device at different absolute positions:
-   - With `above` caption: Device starts after the caption (e.g., at pixel 198)
-   - With `overlay` caption: Device starts at the top (pixel 0)
-
-2. **Caption Height Affects Layout**: In `above`/`below` modes, varying caption lengths change the available space, affecting all frame positions. Use `overlay` mode for consistent device positioning across screenshots with different caption lengths.
-
-3. **Best Practices**:
-   - Use `above`/`below` for guaranteed caption-device separation
-   - Use `overlay` for consistent device positioning across all screenshots
-   - Set fixed caption heights (`minHeight`/`maxHeight`) for uniform layouts
-
-📚 **[Visual Preset Showcase](./positioning-guide/preset-showcase.html)** - Interactive visual guide showing all available preset templates and their styles
-
-### Caption System
-
-#### Dynamic Caption Box
-
-Intelligent caption rendering that adapts to content:
-
-```json
-{
-  "caption": {
-    "position": "above",      // above, below, or overlay
-    "box": {
-      "autoSize": true,       // Dynamic height
-      "maxLines": 3,          // Line limit
-      "lineHeight": 1.4,      // Line spacing
-      "minHeight": 100,
-      "maxHeight": 500
-    }
-  }
-}
-```
-
-#### Caption Positioning Options
-
-- **`above`** (default): Caption appears above the device frame
-- **`below`** (new in v0.7.0): Caption appears below the device frame  
-- **`overlay`**: Caption overlays on the gradient background
+Appshot auto-detects orientation and selects the best-fitting device frame for each screenshot. Frames are always based on the full device image; the screenshot is inset into the frame’s `screenRect`.
 
 ```bash
-# Configure caption below device
-appshot style --device iphone
-# → Select "Below device frame" option
+# Disable frames entirely
+appshot build --no-frame
 
-# Or set directly in config
-{
-  "devices": {
-    "iphone": {
-      "captionPosition": "below"
-    }
-  }
-}
+# Frame-only mode (no captions or gradients)
+appshot frame ./screenshots
 ```
 
-#### Safe Layout Defaults (NEW in v0.9.2)
-
-- **40 px Safety Insets** automatically pad the top/bottom of every canvas so captions survive App Store rounding—no manual margins required.
-- **48 px Above / 36 px Below Gaps** keep the caption box visually detached from the device; override with `caption.box.marginTop` only if you truly need a different gap.
-- **Bottom breathing room**: Increase `caption.box.marginBottom` per device (e.g., 80 px for iPad, 140 px for MacBook) whenever App Store Connect crops the screenshot bottom edge; the planner pushes the device up while keeping captions pinned.
-- **Templates Only Style**: Built-in presets now just set fonts/colors; spacing always comes from the planner, so switching templates won’t break compliance.
-- **Verbose Metrics**: Run `appshot build --dry-run --verbose` to see `Insets`, `Caption gap`, and `Overlay bottom spacing` lines for each device, then tweak the per-device `captionBox` margins without touching the template math.
-
-#### Caption Styling (Enhanced in v0.8.7)
+### Caption System (v2)
 
-Create professional captions with customizable backgrounds and borders:
+Captions render inside fixed layout zones (header/footer only). Text is centered within the caption region and truncated with ellipsis if it exceeds the max line count for the device. Font size is computed from output dimensions, with device-specific min/max bounds.
 
 ```json
 {
+  "version": 2,
+  "layout": "header",
   "caption": {
-    "color": "#FFFFFF",           // Text color (hex)
-    "background": {
-      "color": "#000000",         // Background color (hex)
-      "opacity": 0.8,             // Transparency (0-1)
-      "padding": 20               // Padding around text
-    },
-    "border": {
-      "color": "#FFFFFF",         // Border color (hex)
-      "width": 2,                 // Border thickness (1-10)
-      "radius": 12                // Rounded corners (0-30); used for background too
-    }
-  }
-}
-```
-
-**Key Features:**
-- **Full-width styling** - Backgrounds and borders span device width for uniformity
-- **Flexible positioning** - Works with above, below, and overlay positions
-- **Device-specific overrides** - Customize styling per device type
-- **Professional appearance** - Rounded corners and padding for polished look
- - **Vertical anchoring (NEW)** - Align caption text to top or center of the box
- - **Unified side margins (NEW)** - Control caption box width with `caption.background.sideMargin`
-
-**Interactive Configuration:**
-```bash
-# Configure caption styling interactively
-appshot style --device iphone
-# → Choose caption position (above/below/overlay)
-# → Configure background color and opacity
-# → Set border color, width, and radius
-# → Set vertical alignment (top/center)
-# → Set side margin, min/max height, max lines
-```
-
-**Examples:**
-
-```json
-// Dark background with white border
-{
-  "caption": {
+    "font": "SF Pro Display Bold",
     "color": "#FFFFFF",
     "background": {
       "color": "#000000",
-      "opacity": 0.9,
-      "padding": 30
-    },
-    "border": {
-      "color": "#FFFFFF",
-      "width": 3,
-      "radius": 16
-    }
-  }
-}
-
-// Subtle gradient-matched styling
-{
-  "caption": {
-    "color": "#FFFFFF",
-    "background": {
-      "color": "#FF5733",
-      "opacity": 0.6,
-      "padding": 25,
-      "sideMargin": 24
+      "opacity": 0.75
     }
   }
 }
 ```
 
-#### Fixed vs Adaptive Caption Height
-
-```json
-{
-  "caption": {
-    "position": "above",
-    "box": {
-      "autoSize": false,       // Fixed height banner
-      "minHeight": 320,
-      "maxHeight": 320,
-      "verticalAlign": "top"   // Pin text to top of banner
-    }
-  }
-}
-```
+Tips:
+- Use `appshot build --dry-run --verbose` to inspect computed regions and sizes.
+- Use `appshot style` to pick layout + gradient + caption color.
+- Use `appshot caption` to edit caption text per device.
 
-- Set `autoSize: true` plus `minHeight`/`maxHeight` clamps for adaptive banners.
-- Use `verticalAlign: 'top'` to avoid recenters when height changes.
+### Template Gallery
 
-### Preset Templates Guide
-
-An interactive showcase of all available preset templates is available at `positioning-guide/preset-showcase.html`.
-
-- Visual preview of all 7 professional templates (modern, minimal, bold, elegant, showcase, playful, corporate)
-- Side-by-side comparison across iPhone, iPad, Mac, and Watch devices
-- Shows gradient backgrounds, device positioning, and caption styles
-- Helps you choose the perfect template for your app's style
-- One-line command examples for each preset
-
-Open the file in a browser to explore all available templates before applying them via `appshot preset` or `appshot template`.
+Browse the current v2 template gallery in `template-samples/index.html`.
 
 #### Caption Autocomplete
 
@@ -1558,7 +1382,7 @@ appshot quickstart [options]
 ```
 
 **Options:**
-- `--template <id>` - Template to use (default: modern)
+- `--template <id>` - Template to use (default: ocean-header)
 - `--caption <text>` - Main caption for screenshots
 - `--no-interactive` - Skip interactive prompts
 - `--force` - Overwrite existing configuration
@@ -1575,10 +1399,48 @@ appshot quickstart [options]
 appshot quickstart
 
 # Quick setup with template
-appshot quickstart --template minimal --caption "My App"
+appshot quickstart --template pastel-header --caption "My App"
 
 # Non-interactive
-appshot quickstart --template bold --no-interactive
+appshot quickstart --template noir-footer --no-interactive
+```
+
+### `appshot wizard` (NEW!)
+
+One-shot v2 flow that sets layout, captions, translations, enhancement, and build in a single pass.
+
+```bash
+appshot wizard [options]
+```
+
+**Options:**
+- `--devices <list>` - Comma-separated device list (default: iphone)
+- `--layout <mode>` - header | footer | screenshot-only
+- `--template <id>` - Apply a v2 template preset (ocean-header, sunset-footer, clean-screenshot, etc.)
+- `--caption-source <mode>` - filenames | manual
+- `--langs <codes>` - Languages to build (default: en,es,fr)
+- `--model <name>` - OpenAI model (default: gpt-5-mini)
+- `--enhance` / `--no-enhance` - Toggle caption enhancement (default: on)
+- `--no-interactive` - Skip prompts (CI-friendly)
+- `--dry-run` - Print the planned commands only
+- `--require-ai` - Fail if AI steps are requested but OPENAI_API_KEY is missing
+
+**What it does:**
+1. Ensures v2 config
+2. Applies a template (optional) or sets layout
+3. Auto-detects screenshot resolution + orientation (when available)
+4. Generates captions (auto or manual)
+5. Translates (if languages > 1)
+6. Enhances captions (optional)
+7. Builds screenshots
+
+**Examples:**
+```bash
+# Interactive wizard
+appshot wizard
+
+# Non-interactive with template + translations
+appshot wizard --no-interactive --devices iphone,ipad --template ocean-header --caption-source filenames --langs en,es,fr
 ```
 
 ### `appshot template` (NEW!)
@@ -1590,7 +1452,7 @@ appshot template [template] [options]
 ```
 
 **Arguments:**
-- `[template]` - Template ID (modern, minimal, bold, elegant, showcase, playful, corporate)
+- `[template]` - Template ID (ocean-header, sunset-footer, clean-screenshot, pastel-header, noir-footer, silver-header, tropical-header, slate-footer, midnight-header)
 
 **Options:**
 - `--list` - List all available templates
@@ -1606,16 +1468,16 @@ appshot template [template] [options]
 appshot template --list
 
 # Apply template
-appshot template modern
+appshot template ocean-header
 
 # With caption
-appshot template minimal --caption "Beautiful App"
+appshot template pastel-header --caption "Beautiful App"
 
 # Preview settings
-appshot template --preview bold
+appshot template --preview noir-footer
 
 # Device-specific
-appshot template elegant --device iphone
+appshot template silver-header --device iphone
 ```
 
 ### `appshot preset` (NEW!)
@@ -1627,7 +1489,7 @@ appshot preset <preset-name> [options]
 ```
 
 **Arguments:**
-- `<preset-name>` - Template to use (modern, bold, minimal, elegant, showcase, playful, corporate)
+- `<preset-name>` - Template to use (ocean-header, sunset-footer, clean-screenshot, pastel-header, noir-footer, silver-header, tropical-header, slate-footer, midnight-header)
 
 **Options:**
 - `-c, --caption <text>` - Add caption to all screenshots
@@ -1640,22 +1502,22 @@ appshot preset <preset-name> [options]
 **Examples:**
 ```bash
 # Quick professional screenshots
-appshot preset modern --caption "Amazing Features"
+appshot preset ocean-header --caption "Amazing Features"
 
 # Multiple devices
-appshot preset bold --devices iphone,ipad,watch
+appshot preset noir-footer --devices iphone,ipad,watch
 
 # Multiple languages
-appshot preset minimal --langs en,es,fr,de
+appshot preset pastel-header --langs en,es,fr,de
 
 # Custom output
-appshot preset elegant --output ./marketing/screenshots
+appshot preset silver-header --output ./marketing/screenshots
 
 # Preview mode
-appshot preset corporate --dry-run
+appshot preset slate-footer --dry-run
 
 # Full example
-appshot preset showcase \
+appshot preset clean-screenshot \
   --caption "Summer Sale!" \
   --devices iphone,ipad \
   --langs en,es,fr \
@@ -1741,6 +1603,9 @@ appshot caption --device <name> [options]
 - `--translate` - Enable real-time AI translation
 - `--langs <codes>` - Target languages for translation
 - `--model <name>` - OpenAI model (default: gpt-4o-mini)
+- `--auto-caption` - Generate captions from filenames (non-interactive)
+
+> If OPENAI_API_KEY is missing, translation is skipped with a warning.
 
 **Examples:**
 ```bash
@@ -1750,10 +1615,40 @@ appshot caption --device iphone
 # With translation
 appshot caption --device iphone --translate --langs es,fr,de
 
+# Auto-generate captions and translate (non-interactive)
+appshot caption --device iphone --auto-caption --translate --langs es,fr
+
 # Custom model
 appshot caption --device ipad --translate --langs ja --model gpt-5
 ```
 
+### `appshot caption enhance`
+
+Enhance existing captions using OpenAI without translating languages.
+
+```bash
+appshot caption enhance --device <name> [options]
+```
+
+**Options:**
+- `--device <name>` - Device name (required)
+- `--lang <code>` - Primary language (default: en)
+- `--langs <codes>` - Languages to enhance (comma-separated)
+- `--model <name>` - OpenAI model (default: gpt-5-mini)
+- `--dry-run` - Preview changes without writing
+
+**Examples:**
+```bash
+# Enhance English captions
+appshot caption enhance --device iphone
+
+# Enhance only French + Japanese captions
+appshot caption enhance --device ipad --langs fr,ja
+
+# Explicit GPT-5 model selection
+appshot caption enhance --device mac --model gpt-5-mini
+```
+
 ### `appshot check`
 
 Validate project configuration and assets.
@@ -1782,6 +1677,7 @@ appshot clean [options]
 
 **Options:**
 - `--all` - Remove all generated files including `.appshot/`
+- `--reset` - Remove generated files but keep `screenshots/`
 - `--history` - Clear caption autocomplete history
 - `--keep-history` - Preserve history when using `--all`
 - `--yes` - Skip confirmation prompt
@@ -1794,6 +1690,9 @@ appshot clean
 # Full reset
 appshot clean --all --yes
 
+# Reset but keep screenshots
+appshot clean --reset --yes
+
 # Clear history
 appshot clean --history
 ```
@@ -2022,7 +1921,7 @@ appshot skill --uninstall
 
 **Skill contents:**
 - `SKILL.md` - Main documentation with workflows and scenarios
-- `references/templates.md` - All 8 templates with recommendations by app type
+- `references/templates.md` - v2 template guidance and recommendations by app type
 - `references/gradients.md` - All 24 gradient presets with colors
 - `references/fonts.md` - All 10 embedded font families
 - `references/troubleshooting.md` - Common errors and solutions
@@ -2151,31 +2050,6 @@ appshot init [options]
 - `screenshots/` directories
 - Default configuration
 
-### `appshot migrate`
-
-Migrate project structure to latest version.
-
-```bash
-appshot migrate [options]
-```
-
-**Options:**
-- `--output-structure` - Migrate to language subdirectory structure
-- `--dry-run` - Preview changes without making them
-- `--lang <code>` - Language to use for migration (default: system language)
-
-**Examples:**
-```bash
-# Migrate existing screenshots to language subdirectories
-appshot migrate --output-structure
-
-# Preview migration without changes
-appshot migrate --output-structure --dry-run
-
-# Specify target language
-appshot migrate --output-structure --lang fr
-```
-
 ### `appshot localize`
 
 Batch translate all captions using AI.
@@ -2278,35 +2152,6 @@ This is particularly useful for:
 - Automating screenshot generation pipelines
 - Planning resource allocation for new devices
 
-### `appshot style`
-
-Configure device styling interactively.
-
-```bash
-appshot style --device <name> [options]
-```
-
-**Options:**
-- `--device <name>` - Device name (required)
-- `--reset` - Reset to defaults
-
-**Configures:**
-- Font selection
-- Frame settings
-- Partial frames
-- Frame positioning
-- Frame scaling
-- Caption settings
-
-**Examples:**
-```bash
-# Configure iPhone
-appshot style --device iphone
-
-# Reset to defaults
-appshot style --device iphone --reset
-```
-
 ### `appshot validate`
 
 Validate screenshots against App Store requirements.
@@ -2327,132 +2172,33 @@ appshot validate [options]
 
 ## ⚙️ Configuration Reference
 
-### Complete Schema
-
 ```json
 {
-  "output": "./final",           // Output directory
-  "frames": "./frames",          // Frame directory
-  "defaultLanguage": "en",       // Default language for builds (optional)
-  "gradient": {
-    "colors": ["#hex1", "#hex2"],
-    "direction": "top-bottom"    // or diagonal, left-right
-  },
+  "version": 2,
+  "layout": "header",             // header | footer | screenshot-only
   "caption": {
-    "font": "Font Name",
-    "fontsize": 64,              // Pixels
-    "color": "#FFFFFF",         // Text color (hex)
-    "align": "center",           // left, center, right
-    "position": "above",         // above, below, overlay
-    "paddingTop": 100,
-    "paddingBottom": 60,
-    "background": {              // Optional background styling
-      "color": "#000000",        // Background color (hex)
-      "opacity": 0.8,            // Transparency (0-1)
-      "padding": 20              // Padding around text
-    },
-    "border": {                  // Optional border styling
-      "color": "#FFFFFF",        // Border color (hex)
-      "width": 2,                // Border thickness (1-10)
-      "radius": 12               // Rounded corners (0-30)
-    },
-    "box": {
-      "autoSize": true,          // Dynamic height
-      "maxLines": 3,
-      "lineHeight": 1.4,
-      "minHeight": 100,
-      "maxHeight": 500
-    }
+    "font": "SF Pro Display Bold",
+    "color": "#FFFFFF"
   },
-  "devices": {
-    "iphone": {
-      "input": "./screenshots/iphone",
-      "resolution": "1290x2796",
-      "autoFrame": true,
-      "preferredFrame": "frame-name",
-      "partialFrame": false,
-      "frameOffset": 25,         // Percentage
-      "framePosition": "center", // or top, bottom, 0-100
-      "frameScale": 0.9,         // 0.5-2.0
-      "captionFont": "Override",
-      "captionSize": 72,
-      "captionPosition": "above",
-      "captionBox": {
-        "autoSize": false,
-        "minHeight": 320,
-        "maxHeight": 320
-      }
+  "background": {
+    "mode": "gradient",
+    "gradient": {
+      "colors": ["#667eea", "#764ba2"],
+      "direction": "top-bottom"
     }
-  }
-}
-```
-
-### Device Configuration
-
-Each device can override global settings:
-
-```json
-{
+  },
   "devices": {
-    "iphone": {
-      // Required
-      "input": "./screenshots/iphone",
-      "resolution": "1290x2796",
-      
-      // Frame options
-      "autoFrame": true,
-      "preferredFrame": "iphone-16-pro-max-portrait",
-      "partialFrame": true,
-      "frameOffset": 25,
-      "framePosition": 40,
-      "frameScale": 0.85,
-      
-      // Caption overrides
-      "captionFont": "SF Pro",
-      "captionSize": 64,
-      "captionPosition": "above",
-      "captionBackground": {     // Device-specific background
-        "color": "#FF5733",
-        "opacity": 0.7,
-        "padding": 25
-      },
-      "captionBorder": {         // Device-specific border
-        "color": "#FFFFFF",
-        "width": 3,
-        "radius": 16
-      },
-      "captionBox": {
-        "autoSize": false,
-        "minHeight": 320,
-        "maxHeight": 320,
-        "maxLines": 3
-      }
-    }
-  }
+    "iphone": "./screenshots/iphone",
+    "ipad": "./screenshots/ipad",
+    "mac": "./screenshots/mac",
+    "watch": "./screenshots/watch"
+  },
+  "output": "./final",
+  "frames": "./frames"
 }
 ```
 
-### Fixed Layout Configuration
-
-For consistent screenshots regardless of caption length:
-
-```json
-{
-  "devices": {
-    "iphone": {
-      "autoFrame": false,
-      "preferredFrame": "iphone-16-pro-max-portrait",
-      "frameScale": 0.85,
-      "framePosition": 40,
-      "captionBox": {
-        "autoSize": false,    // Critical
-        "minHeight": 320,     // Fixed height
-        "maxHeight": 320      // Same as min
-      }
-    }
-  }
-}
-```
+> v2 uses fixed layout zones and per-device strategies. See `docs/layout-v2.md`.
 
 ## 🤖 Agent & Automation Guide
 
@@ -2695,26 +2441,25 @@ appshot validate --strict
 
 ### Consistent Marketing Screenshots
 
-For identical device positioning across all screenshots:
+For identical device positioning across all screenshots (v2 uses fixed zones):
 
 ```json
 {
-  "devices": {
-    "iphone": {
-      "resolution": "1290x2796",
-      "autoFrame": false,
-      "preferredFrame": "iphone-16-pro-max-portrait",
-      "frameScale": 0.85,
-      "framePosition": 40,
-      "partialFrame": true,
-      "frameOffset": 25,
-      "captionBox": {
-        "autoSize": false,
-        "minHeight": 320,
-        "maxHeight": 320,
-        "maxLines": 3
-      }
+  "version": 2,
+  "layout": "header",
+  "caption": {
+    "font": "SF Pro Display Bold",
+    "color": "#FFFFFF"
+  },
+  "background": {
+    "mode": "gradient",
+    "gradient": {
+      "colors": ["#111111", "#333333"],
+      "direction": "top-bottom"
     }
+  },
+  "devices": {
+    "iphone": "./screenshots/iphone"
   }
 }
 ```
@@ -2723,15 +2468,18 @@ For identical device positioning across all screenshots:
 
 ```json
 {
-  "gradient": {
-    "colors": ["#BrandColor1", "#BrandColor2"],
-    "direction": "diagonal"
+  "version": 2,
+  "layout": "header",
+  "background": {
+    "mode": "gradient",
+    "gradient": {
+      "colors": ["#BrandColor1", "#BrandColor2"],
+      "direction": "diagonal"
+    }
   },
   "caption": {
     "font": "Brand Font Name",
-    "fontsize": 72,
-    "color": "#BrandTextColor",
-    "align": "center"
+    "color": "#BrandTextColor"
   }
 }
 ```
@@ -2832,14 +2580,9 @@ appshot caption --device iphone --translate --model gpt-4o-mini
 # Ensure high-res input
 # Minimum: 1242x2208 for iPhone
 
-# Check scaling
-{
-  "devices": {
-    "iphone": {
-      "frameScale": 1.0  // No scaling
-    }
-  }
-}
+# v2 uses fixed layout zones and deterministic device scaling.
+# If output is blurry, use higher-res inputs or match the exact device resolution.
+# You can also try --no-frame to remove any frame scaling.
 ```
 
 #### Memory Issues with Large Batches
@@ -3030,32 +2773,30 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
 ### Completed ✅
 - [x] Official App Store specifications
-- [x] Caption positioning (above/below/overlay)
-- [x] Partial frame support
+- [x] Layout v2 fixed zones (header/footer/screenshot-only)
 - [x] Intelligent caption autocomplete
 - [x] Apple Watch optimizations
 - [x] Gradient presets system (24+ gradients)
 - [x] AI-Powered Translations (GPT-4o, GPT-5, o1, o3)
 - [x] Comprehensive Font System (v0.4.0)
 - [x] Frame-Only Mode (v0.8.0)
-- [x] MCP Server with 17 tools (v1.0.0)
-- [x] Claude Code Skill (v1.0.0)
-- [x] Fastlane Export Integration (v0.9.1)
-- [x] Professional Template System (v0.9.0)
-- [x] Auto-Caption from Filenames (v0.9.2)
+- [x] MCP Server with 17 tools (v2.0.0)
+- [x] Claude Code Skill (v2.0.0)
+- [x] Fastlane Export Integration
+- [x] Professional Template System (v2)
+- [x] Auto-Caption from Filenames
 
 ### In Progress 🚧
-- [x] Claude Desktop MCP compatibility ✅ (v1.0.1)
+- [x] Claude Desktop MCP compatibility ✅ (v2.0.0)
 - [ ] Android Device Support (Google Play Store)
 
 ### Planned 📋
 - [ ] GitHub Actions Marketplace Action
 - [ ] CI/CD Templates (Jenkins, GitLab CI, CircleCI)
-- [ ] AI-Powered Caption Enhancement
+- [ ] AI-Powered Caption Enhancement (OpenAI)
 - [ ] WebP/AVIF Support
 - [ ] Screenshot A/B Testing Framework
 - [ ] Differential Builds
-- [ ] Screenshot A/B Testing Framework
 
 ## 📄 License & Support
 
@@ -3077,7 +2818,7 @@ For security vulnerabilities, please see [SECURITY.md](SECURITY.md).
 ### NPM Package
 
 - 📦 [appshot-cli on NPM](https://www.npmjs.com/package/appshot-cli)
-- 🔄 Latest version: 1.0.1
+- 🔄 Latest version: 2.0.0
 
 ---