appshot-cli 0.3.0 → 0.4.0

package/README.md

@@ -1,1013 +1,1557 @@
 # Appshot 📸
 
-> 🎉 **Now available on NPM!** Install with `npm install -g appshot-cli`
-
-Generate beautiful, App Store-ready screenshots with device frames, gradients, and captions.
+> **AI-First CLI for App Store Screenshots** - Generate beautiful, localized screenshots with device frames, gradients, and captions.
 
 [![CI](https://github.com/chrisvanbuskirk/appshot/actions/workflows/ci.yml/badge.svg)](https://github.com/chrisvanbuskirk/appshot/actions/workflows/ci.yml)
 [![npm version](https://badge.fury.io/js/appshot-cli.svg)](https://www.npmjs.com/package/appshot-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Features
+🆕 **Version 0.4.0** - Language-aware output directories, comprehensive font system, and system locale detection!
+
+> ⚠️ **BREAKING CHANGE in v0.4.0**: Output structure now always uses language subdirectories.
+> Single language builds now output to `final/device/lang/` instead of `final/device/`.
+> Run `appshot migrate --output-structure` to update existing projects.
+
+## 📖 Table of Contents
+
+- [Why Appshot?](#-why-appshot)
+- [Features](#-features)
+- [Quick Start](#-quick-start)
+  - [Prerequisites](#prerequisites)
+  - [Installation](#installation)
+  - [Your First Screenshot](#your-first-screenshot)
+- [Core Concepts](#-core-concepts)
+- [Visual Customization](#-visual-customization)
+  - [Gradient System](#gradient-system)
+  - [Font System](#font-system)
+  - [Device Frames](#device-frames)
+  - [Caption System](#caption-system)
+- [Localization & Translation](#-localization--translation)
+- [Device Support](#-device-support)
+- [Command Reference](#-command-reference)
+- [Configuration Reference](#️-configuration-reference)
+- [Agent & Automation Guide](#-agent--automation-guide)
+- [Recipes & Examples](#-recipes--examples)
+- [Troubleshooting](#-troubleshooting)
+- [Development](#-development)
+- [Roadmap](#-roadmap)
+- [License & Support](#-license--support)
+
+## 🌟 Why Appshot?
+
+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.
+
+### Key Differentiators
+
+- 🤖 **Agent-First Design** - JSON outputs, predictable commands, no interactive prompts in automation mode
+- 🎯 **Smart Automation** - Auto-detects orientation, selects appropriate frames, handles batch operations
+- 🌍 **AI-Powered Localization** - Translate captions in real-time using GPT-4o, GPT-5, o1, and o3 models
+- 📏 **App Store Compliant** - Built-in validation for all official Apple App Store specifications
+- ⚡ **Fast & Parallel** - Process hundreds of screenshots with configurable concurrency
+- 🛠️ **Pure CLI** - No web UI, no GUI, just predictable commands perfect for automation
+
+## ✨ Features
 
 - 🖼️ **Smart Frames** - Automatically detects portrait/landscape and selects appropriate device frame
-- 🎨 **Gradients** - Beautiful gradient backgrounds with customizable colors
-- ✏️ **Captions** - Add marketing text with full typography control (above or overlay)
-- 🌍 **Localization** - Multi-language support with AI-powered translations for international app stores
-- 📱 **Multi-Device** - Support for iPhone, iPad, Mac, Apple TV, Vision Pro, and Apple Watch
-- 📏 **App Store Specs** - Built-in support for all official App Store screenshot resolutions
-- ✅ **Validation** - Verify screenshots meet App Store requirements
-- 🔄 **Orientation Detection** - Intelligently handles both portrait and landscape screenshots
-- ⚡ **Fast** - Parallel processing with configurable concurrency
-- 🤖 **AI Translation** - Real-time and batch translation using OpenAI models (GPT-4o, GPT-5, o1, o3)
-- 🛠️ **CLI** - Simple command-line interface designed for agents and automation
-
-## Quick Start
+- 🎨 **Gradient Presets** - 24+ beautiful gradients with visual preview and easy application
+- 🔤 **Font System** - 50+ font mappings, direct font setting, interactive selection, and system detection
+- ✏️ **Dynamic Captions** - Smart text wrapping, auto-sizing, and multi-line support
+- 🌍 **AI Translation** - Real-time and batch translation using OpenAI's latest models
+- 📱 **Multi-Device** - iPhone, iPad, Mac, Apple TV, Vision Pro, and Apple Watch support
+- 📏 **App Store Specs** - All official resolutions with validation and presets
+- 🔄 **Orientation Detection** - Intelligently handles both portrait and landscape
+- ⚡ **Parallel Processing** - Configurable concurrency for large batches
+- 🔍 **Caption Autocomplete** - Intelligent suggestions with fuzzy search and learning
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- **Node.js 16+** - Required for ESM modules
+- **npm** or **yarn** - Package manager
+- **Operating System** - macOS, Linux, or Windows
+- **Optional**: OpenAI API key for translation features
 
 ### Installation
 
 ```bash
+# Install globally via npm
 npm install -g appshot-cli
+
+# Or with yarn
+yarn global add appshot-cli
+
+# Verify installation
+appshot --version
 ```
 
-> **Note**: The package is called `appshot-cli` on NPM, but the command is still `appshot`
+> **Note**: The package is called `appshot-cli` on NPM, but the command is `appshot`
 
-### Initialize a new project
+### Your First Screenshot
+
+Create App Store-ready screenshots in 5 simple steps:
 
 ```bash
+# 1. Initialize your project
 appshot init
-```
 
-This creates:
-- `.appshot/config.json` - Main configuration file
-- `.appshot/captions/` - Device-specific caption files
-- `screenshots/` - Directory structure for your screenshots
+# 2. Add your screenshots
+cp ~/Desktop/screenshots/*.png screenshots/iphone/
 
-### Add your screenshots
+# 3. Add captions interactively
+appshot caption --device iphone
 
-Place your app screenshots in the appropriate device folders:
-```
-screenshots/
-├── iphone/
-├── ipad/
-├── mac/
-└── watch/
-```
+# 4. Apply a gradient preset
+appshot gradients --apply ocean
+
+# 5. Build final screenshots
+appshot build
 
-### Add captions
+# ✨ Output ready in final/ directory!
+```
 
-Use the interactive caption editor with autocomplete:
+### Example Output Structure
 
-```bash
-appshot caption --device iphone
+```
+final/
+├── iphone/
+│   └── en/           # Language subdirectory (always created)
+│       ├── home.png       # 1284×2778 with frame, gradient, and caption
+│       ├── features.png   
+│       └── settings.png
+└── ipad/
+    └── en/           # Language subdirectory
+        └── dashboard.png  # 2048×2732 iPad Pro screenshot
 ```
 
-Features:
-- 🔍 **Autocomplete** - Smart suggestions as you type
-- 📊 **Frequency tracking** - Most-used captions appear first  
-- 🎯 **Device-specific** - Suggestions tailored to device type
-- ⌨️ **Keyboard shortcuts** - Tab to complete, arrows to navigate
+## 📘 Core Concepts
 
-### Build final screenshots
+### Project Structure
 
-Generate your App Store-ready screenshots:
+Appshot uses a simple, predictable directory structure:
 
-```bash
-appshot build
+```
+your-project/
+├── .appshot/
+│   ├── config.json          # Main configuration
+│   ├── captions/            # Device-specific captions
+│   │   ├── iphone.json
+│   │   └── ipad.json
+│   └── caption-history.json # Autocomplete history
+├── screenshots/             # Original screenshots
+│   ├── iphone/
+│   ├── ipad/
+│   └── mac/
+├── frames/                  # Device frames (auto-downloaded)
+└── final/                   # Generated output
 ```
 
-Output appears in the `final/` directory, ready for upload!
-
-## Configuration
+### Configuration Overview
 
-Edit `.appshot/config.json` to customize your screenshots:
+All settings are stored in `.appshot/config.json`:
 
 ```json
 {
   "output": "./final",
-  "frames": "./frames",
   "gradient": {
-    "colors": ["#FF5733", "#FFC300"],
-    "direction": "top-bottom"
+    "colors": ["#0077BE", "#33CCCC"],
+    "direction": "diagonal"
   },
   "caption": {
     "font": "SF Pro",
     "fontsize": 64,
     "color": "#FFFFFF",
-    "align": "center",
-    "paddingTop": 100
+    "position": "above"
   },
   "devices": {
     "iphone": {
-      "input": "./screenshots/iphone",
       "resolution": "1284x2778",
-      "autoFrame": true,
-      "preferredFrame": "iphone-15-pro-max"
+      "autoFrame": true
     }
   }
 }
 ```
 
-### Gradient Options
+### Workflow
+
+1. **Capture** - Take screenshots from simulator/device or design tool
+2. **Configure** - Set up gradients, fonts, and device settings
+3. **Caption** - Add marketing text with optional AI translation
+4. **Build** - Generate final App Store-ready screenshots
+5. **Validate** - Ensure compliance with App Store requirements
 
-- **colors**: Array of hex color codes
-- **direction**: `top-bottom`, `bottom-top`, `left-right`, `right-left`, `diagonal`
+## 🎨 Visual Customization
 
-#### Using Gradient Presets
+### Gradient System
 
-Instead of manually configuring gradients, you can use one of the 24+ built-in presets:
+Appshot includes 24+ professional gradient presets organized by category:
+
+#### Browse & Apply Gradients
 
 ```bash
-# Browse available gradients
+# View all gradients with color preview
 appshot gradients
 
-# Apply a preset
+# Apply a gradient to your project
 appshot gradients --apply sunset
 
-# Interactive selection with visual preview
+# Interactive selection
 appshot gradients select
 
 # Generate preview image
 appshot gradients --preview ocean
 
-# Create samples of all gradients
+# Create sample gallery
 appshot gradients --sample
 ```
 
-##### Available Presets by Category
-
-**Warm Gradients** 🔥
-- **sunset** - Warm orange to pink (#FF5733 → #FFC300)
-- **autumn** - Fall foliage colors (#D2691E → #FF4500)
-- **golden** - Rich golden tones (#FFD700 → #FFA500)
-- **coral** - Soft coral reef (#FF6B6B → #FFE66D)
-
-**Cool Gradients** ❄️
-- **ocean** - Deep blue waves (#0077BE → #33CCCC)
-- **arctic** - Icy blue frost (#E0F7FA → #81D4FA)
-- **mint** - Fresh mint green (#00C9A7 → #00F5FF)
-- **twilight** - Evening sky (#667EEA → #764BA2)
-
-**Vibrant Gradients** 🎨
-- **neon** - Electric glow (#FF006E → #8338EC → #3A86FF)
-- **tropical** - Paradise colors (#FE6B8B → #FF8E53)
-- **rainbow** - Full spectrum (#FF0000 → #FF7F00 → #FFFF00 → #00FF00 → #0000FF → #8B00FF)
-- **vivid** - Bold and bright (#F72585 → #7209B7 → #3A0CA3)
-
-**Subtle Gradients** 🕊️
-- **pastel** - Soft blend (#E8D8F5 → #D6E6FF)
-- **lavender** - Gentle purple (#E6E6FA → #DDA0DD)
-- **peach** - Soft peach tones (#FFDAB9 → #FFE4E1)
-- **sky** - Clear day (#87CEEB → #E0F6FF)
-
-**Monochrome Gradients** ⚫⚪
-- **noir** - Deep black (#000000 → #434343)
-- **silver** - Metallic shine (#C0C0C0 → #F5F5F5)
-- **charcoal** - Dark grey (#36454F → #708090)
-- **pearl** - Soft white (#F8F8FF → #FFFFFF)
-
-**Brand-Inspired Gradients** 🏢
-- **instagram** - Brand colors (#833AB4 → #FD1D1D → #FCB045)
-- **spotify** - Green energy (#1DB954 → #191414)
-- **twitter** - Blue bird (#1DA1F2 → #14171A)
-- **slack** - Workspace hues (#4A154B → #36C5F0 → #2EB67D)
-
-### Caption Options
-
-- **font**: Font family name
-- **fontsize**: Size in pixels
-- **color**: Hex color code
-- **align**: `left`, `center`, `right`
-- **paddingTop**: Space from top in pixels
-- **paddingBottom**: Space from bottom in pixels
-- **position**: `above` (above device frame) or `overlay` (on gradient)
-- **box**: Caption box configuration (see Dynamic Caption Box section)
-
-### Device Options
-
-- **input**: Directory containing screenshots
-- **resolution**: Output resolution (use App Store specs or custom)
-- **autoFrame**: Enable automatic frame selection based on screenshot orientation (default: true)
-- **preferredFrame**: Preferred frame name from the registry (optional)
-- **partialFrame**: Cut off bottom portion of frame for dynamic look (default: false)
-- **frameOffset**: Percentage to cut off when partialFrame is true (default: 25)
-
-## Commands
-
-### `appshot init`
-Initialize a new appshot project with scaffolding.
+#### Gradient Categories
 
-Options:
-- `--force` - Overwrite existing files
+- **🔥 Warm**: sunset, autumn, golden, coral
+- **❄️ Cool**: ocean, arctic, mint, twilight  
+- **🎨 Vibrant**: neon, tropical, rainbow, vivid
+- **🕊️ Subtle**: pastel, lavender, peach, sky
+- **⚫⚪ Monochrome**: noir, silver, charcoal, pearl
+- **🏢 Brand**: instagram, spotify, twitter, slack
 
-### `appshot caption`
-Interactively add or edit captions for screenshots with intelligent autocomplete and AI-powered translation.
+#### Custom Gradients
 
-Features:
-- **Autocomplete suggestions** - Shows previous captions as you type
-- **Fuzzy search** - Finds captions even with typos
-- **Usage tracking** - Frequently used captions appear first
-- **Learning system** - Improves suggestions over time
-- **Device-specific** - Prioritizes captions used for the same device
-- **Real-time translation** - Instantly translate captions as you type (requires OpenAI API key)
+```json
+{
+  "gradient": {
+    "colors": ["#FF5733", "#FFC300", "#FF1493"],
+    "direction": "diagonal"  // top-bottom, left-right, diagonal
+  }
+}
+```
 
-Options:
-- `--device <name>` - Device name (required)
-- `--lang <code>` - Primary language code (default: en)
-- `--translate` - Enable AI-powered real-time translation
-- `--langs <codes>` - Target languages for translation (comma-separated)
-- `--model <name>` - OpenAI model to use (default: gpt-4o-mini)
+### Font System
 
-Example with translation:
-```bash
-# Add captions with instant translation to Spanish and French
-appshot caption --device iphone --translate --langs es,fr
+Version 0.4.0 introduces comprehensive font management with intelligent fallbacks.
 
-# Use a specific model for translation
-appshot caption --device iphone --translate --langs zh-CN,ja --model gpt-5
-```
+#### Font Commands
 
-Keyboard shortcuts:
-- **Tab** - Autocomplete the top suggestion
-- **↑↓** - Navigate through suggestions
-- **Enter** - Select current suggestion
-- **Esc** - Dismiss suggestions
+```bash
+# Browse recommended fonts
+appshot fonts
 
-### `appshot gradients`
-Browse, preview, and apply gradient presets for stunning backgrounds.
-
-Options:
-- `--list` - List all available gradient presets (default)
-- `--category <name>` - Filter by category (warm, cool, vibrant, subtle, monochrome, brand)
-- `--preview <id>` - Generate preview image for a specific gradient
-- `--sample` - Generate sample images for all gradients with HTML preview
-- `--apply <id>` - Apply gradient preset to current project
-
-Subcommands:
-- `select` - Interactive gradient selection with visual preview
-
-Features:
-- **24+ Beautiful Presets** - Curated collection of professional gradients
-- **6 Categories** - Warm, Cool, Vibrant, Subtle, Monochrome, Brand-inspired
-- **Visual Preview** - See color blocks in terminal with ANSI approximation
-- **Sample Generation** - Create PNG samples of all gradients
-- **HTML Preview Page** - Browse all gradients in your browser
-- **Quick Apply** - Instantly update project configuration
-- **Direction Support** - All gradient directions (top-bottom, diagonal, etc.)
-
-Example usage:
-```bash
-# Browse all gradients with color previews
-appshot gradients
+# Set font directly (NEW in v0.4.0)
+appshot fonts --set "Montserrat"
 
-# Filter by category
-appshot gradients --category warm
+# Interactive font selection (NEW in v0.4.0)
+appshot fonts --select
 
-# Preview a specific gradient (creates gradient-sunset.png)
-appshot gradients --preview sunset
+# Set device-specific font (NEW in v0.4.0)
+appshot fonts --set "SF Pro" --device iphone
 
-# Apply a gradient to your project
-appshot gradients --apply ocean
+# List ALL system fonts
+appshot fonts --all
 
-# Interactive selection with arrow keys
-appshot gradients select
+# Validate a font
+appshot fonts --validate "SF Pro"
 
-# Generate samples for all gradients (creates gradient-samples/ directory)
-appshot gradients --sample
-# Then open gradient-samples/preview.html in your browser
+# Get JSON output for automation
+appshot fonts --json
 ```
 
-#### How Gradient Presets Work
+#### Font Setting Methods
 
-1. **Browsing** - The `gradients` command displays all presets with:
-   - Visual color blocks showing the gradient colors
-   - Name and description
-   - Category grouping
-   - Gradient ID for applying
+You have three ways to set fonts:
 
-2. **Previewing** - Generate a sample image to see exactly how a gradient looks:
+1. **Direct Command** (Fastest):
    ```bash
-   appshot gradients --preview neon
-   # Creates: gradient-neon.png (400x800px)
+   appshot fonts --set "Helvetica"
+   appshot fonts --set "SF Pro" --device iphone
    ```
 
-3. **Applying** - Updates your `.appshot/config.json` automatically:
+2. **Interactive Selection**:
    ```bash
-   appshot gradients --apply twilight
-   # Updates gradient.colors and gradient.direction in config
+   appshot fonts --select
+   appshot style --device iphone  # Also includes font selection
    ```
 
-4. **Sample Generation** - Creates a gallery of all gradients:
-   ```bash
-   appshot gradients --sample
-   # Creates: gradient-samples/
-   #   ├── sunset.png
-   #   ├── ocean.png
-   #   ├── neon.png
-   #   └── preview.html (view all in browser)
-   ```
-
-5. **Interactive Selection** - Visual menu for choosing gradients:
-   ```bash
-   appshot gradients select
-   # Use arrow keys to navigate, Enter to apply, Esc to cancel
+3. **Manual Configuration**:
+   ```json
+   {
+     "caption": {
+       "font": "Montserrat",     // Global default
+       "fontsize": 64
+     },
+     "devices": {
+       "iphone": {
+         "captionFont": "SF Pro"  // Device override
+       }
+     }
+   }
    ```
 
-### `appshot style`
-Configure device positioning and caption styling interactively.
-
-Options:
-- `--device <name>` - Device name (iphone, ipad, mac, watch)
-- `--reset` - Reset device styling to defaults (removes all custom settings)
-
-Features:
-- **Auto frame selection** - Enable/disable automatic frame selection based on screenshot dimensions
-- **Preferred frame** - Choose specific device frame when auto selection is disabled
-- **Partial frames** - Toggle on/off and adjust cut-off percentage (15%-50%)
-- **Frame positioning** - Top, center, bottom, or custom positioning (0-100%)
-- **Frame scaling** - Control device size (75%-130% or custom)
-- **Caption customization** - Device-specific size, position, and box behavior
-- **Caption box** - Auto-sizing, max lines, line height adjustments
-- **Interactive prompts** - Step-by-step configuration with visual descriptions
-
-### `appshot build`
-Generate final screenshots with frames, gradients, and captions.
-
-Options:
-- `--devices <list>` - Comma-separated device list
-- `--preset <ids>` - Use specific App Store presets (e.g., iphone-6-9,ipad-13)
-- `--config <file>` - Use specific config file (default: .appshot/config.json)
-- `--langs <list>` - Comma-separated language codes
-- `--preview` - Generate low-res previews
-- `--concurrency <n>` - Parallel processing limit
-- `--no-frame` - Skip device frames
-- `--no-gradient` - Skip gradient backgrounds
-- `--no-caption` - Skip captions
+#### Intelligent Fallbacks
 
-### `appshot specs`
-Display device specifications and resolutions.
+Every font automatically includes appropriate fallback chains:
 
-### `appshot clean`
-Remove generated screenshots and temporary files.
+- **SF Pro** → `system-ui, -apple-system, Helvetica, Arial, sans-serif`
+- **Custom Serif** → `'Custom Serif', Georgia, Times New Roman, serif`
+- **Code Font** → `'Code Font', Monaco, Consolas, monospace`
 
-Options:
-- `--all` - Remove all generated files including .appshot/ directory
-- `--history` - Clear caption autocomplete history
-- `--keep-history` - Preserve caption history when using --all
-- `--yes` - Skip confirmation prompt
+#### System Font Detection
 
-Options:
-- `--device <name>` - Filter by device type
-- `--json` - Output as JSON
+- **macOS**: Uses `system_profiler` for complete font list
+- **Linux**: Uses `fc-list` for fontconfig fonts
+- **Windows**: PowerShell queries font registry
 
-### `appshot check`
-Validate project configuration and assets.
+### Device Frames
 
-Options:
-- `--fix` - Attempt to fix issues automatically
+#### Smart Frame Selection
 
-### `appshot presets`
-Manage App Store screenshot presets for all official resolutions.
+Appshot automatically detects screenshot orientation and selects the appropriate frame:
 
-Options:
-- `--list` - List all available presets
-- `--required` - Show only required presets for App Store submission
-- `--generate <ids>` - Generate config for specific preset IDs (comma-separated)
-- `--category <type>` - Filter by category (iphone, ipad, mac, appletv, visionpro, watch)
-- `--output <file>` - Output file for generated config (default: appshot-presets.json)
+```json
+{
+  "devices": {
+    "iphone": {
+      "autoFrame": true,  // Auto-detect orientation
+      "preferredFrame": "iphone-16-pro-max-portrait"  // Override
+    }
+  }
+}
+```
 
-### `appshot validate`
-Validate screenshots against App Store requirements.
+#### Partial Frames
 
-Options:
-- `--strict` - Validate against required presets only
-- `--fix` - Suggest fixes for invalid screenshots
+Create modern App Store screenshots with cut-off device frames:
 
-### `appshot localize`
-Generate translations for all existing captions using OpenAI's powerful language models.
+```json
+{
+  "devices": {
+    "iphone": {
+      "partialFrame": true,
+      "frameOffset": 25,      // Cut 25% from bottom
+      "framePosition": 40,    // Position at 40% from top
+      "frameScale": 0.85      // Scale to 85%
+    }
+  }
+}
+```
 
-Options:
-- `--langs <codes>` - Target languages (comma-separated, required)
-- `--device <name>` - Specific device or all devices
-- `--model <name>` - OpenAI model to use (default: gpt-4o-mini)
-- `--source <lang>` - Source language (default: en)
-- `--review` - Review translations before saving
-- `--overwrite` - Overwrite existing translations
+### Caption System
 
-Supported models:
-- **GPT-4o models**: gpt-4o, gpt-4o-mini (using max_tokens)
-- **GPT-5 models**: gpt-5, gpt-5-mini, gpt-5-nano (using max_completion_tokens)
-- **o1 models**: o1, o1-mini (reasoning models)
-- **o3 models**: o3, o3-mini (latest reasoning models)
+#### Dynamic Caption Box
 
-Example usage:
-```bash
-# Translate all captions to Spanish, French, and German
-appshot localize --langs es,fr,de
+Intelligent caption rendering that adapts to content:
 
-# Translate iPhone captions only, with review
-appshot localize --device iphone --langs ja,ko --review
+```json
+{
+  "caption": {
+    "position": "above",      // above or overlay
+    "box": {
+      "autoSize": true,       // Dynamic height
+      "maxLines": 3,          // Line limit
+      "lineHeight": 1.4,      // Line spacing
+      "minHeight": 100,
+      "maxHeight": 500
+    }
+  }
+}
+```
 
-# Use GPT-5 for higher quality translations
-appshot localize --langs zh-CN,zh-TW --model gpt-5
+#### Caption Autocomplete
 
-# Overwrite existing translations with new ones
-appshot localize --langs es,fr --overwrite
-```
+The caption command includes intelligent autocomplete:
 
-Setup:
 ```bash
-# Set your OpenAI API key
-export OPENAI_API_KEY="your-api-key-here"
+appshot caption --device iphone
+# Features:
+# - Fuzzy search
+# - Frequency tracking
+# - Device-specific suggestions
+# - Pattern detection
 ```
 
-## AI-Powered Translation 🤖
+Keyboard shortcuts:
+- **Tab** - Complete suggestion
+- **↑↓** - Navigate suggestions
+- **Enter** - Select
+- **Esc** - Dismiss
+
+## 🌍 Localization & Translation
+
+### AI-Powered Translation
 
-Appshot includes powerful AI translation capabilities using OpenAI's latest models, including GPT-4o, GPT-5, and reasoning models (o1, o3).
+Appshot integrates with OpenAI for instant caption translation.
 
-### Setup
+#### Setup
 
-First, set your OpenAI API key:
 ```bash
 export OPENAI_API_KEY="your-api-key-here"
 ```
 
-### Real-Time Translation
-
-Translate captions instantly as you type them:
+#### Real-Time Translation
 
 ```bash
-# Add captions with automatic translation to Spanish and French
-appshot caption --device iphone --translate --langs es,fr
-
-# Use a specific model for higher quality
-appshot caption --device iphone --translate --langs zh-CN,ja --model gpt-5
-```
+# Translate as you type
+appshot caption --device iphone --translate --langs es,fr,de
 
-When you enter a caption, translations appear immediately below:
-```
-? home.png: Welcome to the future
-  es: Bienvenido al futuro
-  fr: Bienvenue dans le futur
+# Output:
+# ? home.png: Welcome to the future
+#   es: Bienvenido al futuro
+#   fr: Bienvenue dans le futur
+#   de: Willkommen in der Zukunft
 ```
 
-### Batch Translation
-
-Translate all existing captions at once:
+#### Batch Translation
 
 ```bash
-# Translate all captions to multiple languages
+# Translate all existing captions
 appshot localize --langs es,fr,de,ja,zh-CN
 
-# Translate specific device only
+# Device-specific translation
 appshot localize --device iphone --langs es,fr
 
-# Review translations before saving
-appshot localize --langs es,fr --review
-
-# Use GPT-5 for best quality
+# Use premium model
 appshot localize --langs ja,ko --model gpt-5
+
+# Review before saving
+appshot localize --langs es --review
 ```
 
 ### Supported Models
 
-Appshot intelligently handles different OpenAI models and their specific requirements:
+| Model Series | Best For | Parameter | Temperature |
+|-------------|----------|-----------|-------------|
+| **GPT-4o** | Fast, cost-effective | `max_tokens` | 0.3 |
+| **GPT-5** | High-quality, nuanced | `max_completion_tokens` | 1.0 |
+| **o1** | Deep reasoning | `max_completion_tokens` | 1.0 |
+| **o3** | State-of-the-art | `max_completion_tokens` | 1.0 |
 
-#### GPT-4o Series (General Purpose)
-- **Models**: `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`
-- **Best for**: Fast, cost-effective translations
-- **Parameter**: Uses `max_tokens`
-- **Temperature**: Configurable (default 0.3)
+### Supported Languages
 
-#### GPT-5 Series (Advanced)
-- **Models**: `gpt-5`, `gpt-5-mini`, `gpt-5-nano`
-- **Best for**: High-quality, nuanced translations
-- **Parameter**: Uses `max_completion_tokens`
-- **Temperature**: Fixed at 1.0 (reasoning model requirement)
+25+ languages including:
+- **European**: es, fr, de, it, pt, nl, sv, no, da, fi, pl, ru
+- **Asian**: ja, ko, zh-CN, zh-TW, hi, th, vi, id, ms
+- **Middle Eastern**: ar, he, tr
+- **Variants**: pt-BR
 
-#### o1 Series (Deep Reasoning)
-- **Models**: `o1`, `o1-mini`
-- **Best for**: Complex marketing copy with cultural adaptation
-- **Parameter**: Uses `max_completion_tokens`
-- **Temperature**: Fixed at 1.0
+### Multi-Language Workflow
 
-#### o3 Series (Latest Reasoning)
-- **Models**: `o3`, `o3-mini`
-- **Best for**: State-of-the-art translation quality
-- **Parameter**: Uses `max_completion_tokens`
-- **Temperature**: Fixed at 1.0
+```bash
+# 1. Add captions with translation
+appshot caption --device iphone --translate --langs es,fr
 
-### Language Support
+# 2. Build localized screenshots
+appshot build --langs en,es,fr
 
-Built-in support for 25+ languages:
-- **European**: Spanish (es), French (fr), German (de), Italian (it), Portuguese (pt), Dutch (nl), Swedish (sv), Norwegian (no), Danish (da), Finnish (fi), Polish (pl), Russian (ru)
-- **Asian**: Japanese (ja), Korean (ko), Simplified Chinese (zh-CN), Traditional Chinese (zh-TW), Hindi (hi), Thai (th), Vietnamese (vi), Indonesian (id), Malay (ms)
-- **Middle Eastern**: Arabic (ar), Hebrew (he), Turkish (tr)
-- **Portuguese Variants**: Brazilian Portuguese (pt-BR)
+# Output structure (always uses language subdirectories):
+# final/
+#   iphone/
+#     en/
+#     es/
+#     fr/
+```
 
-### Translation Features
+## 📱 Device Support
 
-#### Smart Caching
-Translations are cached to avoid duplicate API calls. If you translate the same caption again, it returns instantly without using API credits.
+### Apple Devices
 
-#### Marketing-Optimized Prompts
-The system uses specialized prompts designed for app marketing text:
-- Maintains marketing tone and impact
-- Keeps translations concise
-- Ensures cultural appropriateness
-- Preserves call-to-action strength
+| Device | Orientations | Frame Variants | Special Features |
+|--------|-------------|----------------|------------------|
+| **iPhone** | Portrait, Landscape | 15+ models | Notch/Dynamic Island support |
+| **iPad** | Portrait, Landscape | 10+ models | Multiple sizes |
+| **Mac** | Landscape | 4 resolutions | 16:10 aspect ratio |
+| **Apple Watch** | Portrait | 5 sizes | Band cropping |
+| **Apple TV** | Landscape | HD, 4K | TV frame |
+| **Vision Pro** | Landscape | 3840×2160 | Spatial computing |
 
-#### Error Handling
-- Graceful fallback if API is unavailable
-- Clear error messages for rate limits
-- Automatic retry with delays for batch operations
-- Continues with other translations if one fails
+### App Store Specifications
 
-### Advanced Configuration
+#### Required Resolutions
 
-Create `.appshot/ai-config.json` for custom settings:
+**iPhone** (choose one):
+- 6.9" Display: 1290×2796 (iPhone 16/15 Pro Max)
+- 6.5" Display: 1284×2778 (iPhone 14 Plus)
 
-```json
-{
-  "defaultModel": "gpt-5",
-  "temperature": 0.3,
-  "cache": true,
-  "systemPrompt": "You are translating premium app marketing text. Keep it impactful and concise."
-}
-```
+**iPad**:
+- 13" Display: 2064×2752 or 2048×2732
 
-### Cost Optimization Tips
+**Mac**:
+- 16:10 aspect: 2880×1800, 2560×1600, 1440×900, or 1280×800
 
-1. **Use `gpt-4o-mini`** for draft translations (very cost-effective)
-2. **Enable caching** to avoid retranslating identical text
-3. **Batch operations** are more efficient than real-time for large projects
-4. **Review mode** lets you verify before committing translations
+**Apple Watch**:
+- Must use same size across all localizations
 
-### Example Workflow
+#### Preset Management
 
 ```bash
-# 1. Initialize project
-appshot init
-
-# 2. Add screenshots
-cp ~/Desktop/screenshots/*.png screenshots/iphone/
+# View all presets
+appshot presets
 
-# 3. Add captions with instant translation
-appshot caption --device iphone --translate --langs es,fr,de
+# Show required only
+appshot presets --required
 
-# 4. Build localized screenshots
-appshot build --langs en,es,fr,de
+# Generate config for specific presets
+appshot presets --generate iphone-6-9,ipad-13
 
-# Output structure:
-# final/
-#   iphone/
-#     en/
-#       home.png
-#     es/
-#       home.png
-#     fr/
-#       home.png
-#     de/
-#       home.png
+# Build with presets
+appshot build --preset iphone-6-9,ipad-13
 ```
 
-## Multi-Language Support
+### Validation
 
-Captions are stored with all translations in JSON format:
+```bash
+# Validate against App Store requirements
+appshot validate
 
-```json
-{
-  "home.png": {
-    "en": "Organize your life",
-    "fr": "Organisez votre vie",
-    "es": "Organiza tu vida",
-    "de": "Organisieren Sie Ihr Leben",
-    "ja": "人生を整理する"
-  }
-}
+# Strict mode (required presets only)
+appshot validate --strict
+
+# Get fix suggestions
+appshot validate --fix
 ```
 
-Build for specific languages:
+## 📝 Command Reference
+
+### `appshot build`
+
+Generate final screenshots with frames, gradients, and captions.
 
 ```bash
-appshot build --langs en,fr,es
+appshot build [options]
 ```
 
-## App Store Specifications
+**Options:**
+- `--devices <list>` - Comma-separated device list (default: all)
+- `--preset <ids>` - Use App Store presets (e.g., `iphone-6-9,ipad-13`)
+- `--config <file>` - Custom config file (default: `.appshot/config.json`)
+- `--langs <list>` - Build for specific languages (if not specified, auto-detects)
+- `--preview` - Generate low-res previews
+- `--concurrency <n>` - Parallel processing limit (default: 5)
+- `--no-frame` - Skip device frames
+- `--no-gradient` - Skip gradient backgrounds
+- `--no-caption` - Skip captions
 
-Appshot includes all official App Store screenshot resolutions. View them with:
+**Language Detection:**
+When `--langs` is not specified, appshot automatically determines languages in this order:
+1. Languages found in caption files (if using multi-language captions)
+2. `defaultLanguage` setting in config.json
+3. System locale (e.g., `fr` for French systems)
+4. Fallback to `en`
 
+**Examples:**
 ```bash
-# Show all presets
-appshot presets
+# Build all devices
+appshot build
 
-# Show only required presets
-appshot presets --required
+# Specific devices and languages
+appshot build --devices iphone,ipad --langs en,fr,es
 
-# Generate config for specific devices
-appshot presets --generate iphone-6-9,ipad-13,mac-2880,watch-ultra
-```
+# Use App Store presets
+appshot build --preset iphone-6-9-portrait,ipad-13-landscape
 
-### Required Resolutions
+# Preview mode
+appshot build --preview --devices iphone
+```
 
-**iPhone** (choose one):
-- **6.9" Display**: 1290×2796 (iPhone 16 Pro Max, 15 Pro Max, etc.)
-- **6.5" Display**: 1284×2778 (iPhone 14 Plus, 13 Pro Max, etc.)
+**Exit Codes:**
+- `0` - Success
+- `1` - Configuration error
+- `2` - Missing screenshots
+- `3` - Processing error
 
-**iPad** (required):
-- **13" Display**: 2064×2752 or 2048×2732
+### `appshot caption`
 
-**Mac** (for Mac apps):
-- **16:10 aspect ratio**: 2880×1800, 2560×1600, 1440×900, or 1280×800
+Add or edit captions with autocomplete and AI translation.
 
-**Apple Watch** (for Watch apps):
-- **Ultra**: 410×502
-- **Series 10**: 416×496
-- **Series 9/8/7**: 396×484
+```bash
+appshot caption --device <name> [options]
+```
 
-### Quick Preset Usage
+**Options:**
+- `--device <name>` - Device name (required)
+- `--lang <code>` - Primary language (default: en)
+- `--translate` - Enable real-time AI translation
+- `--langs <codes>` - Target languages for translation
+- `--model <name>` - OpenAI model (default: gpt-4o-mini)
 
+**Examples:**
 ```bash
-# Build with iPhone 6.9" and iPad 13" presets
-appshot build --preset iphone-6-9,ipad-13
+# Basic caption entry
+appshot caption --device iphone
 
-# Validate existing screenshots
-appshot validate --strict
-```
+# With translation
+appshot caption --device iphone --translate --langs es,fr,de
 
-## Examples
+# Custom model
+appshot caption --device ipad --translate --langs ja --model gpt-5
+```
 
-See the `examples/minimal-project` directory for a complete example setup.
+### `appshot check`
 
-## Development
+Validate project configuration and assets.
 
 ```bash
-# Clone the repository
-git clone https://github.com/chrisvanbuskirk/appshot.git
-cd appshot
+appshot check [options]
+```
 
-# Install dependencies
-npm install
+**Options:**
+- `--fix` - Attempt automatic fixes
 
-# Build
-npm run build
+**Checks:**
+- Configuration file validity
+- Screenshot presence
+- Frame availability
+- Directory structure
+- Caption files
 
-# Run tests
-npm test
+### `appshot clean`
 
-# Link for local development
-npm link
+Remove generated files and temporary data.
+
+```bash
+appshot clean [options]
 ```
 
-## Contributing
+**Options:**
+- `--all` - Remove all generated files including `.appshot/`
+- `--history` - Clear caption autocomplete history
+- `--keep-history` - Preserve history when using `--all`
+- `--yes` - Skip confirmation prompt
 
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+**Examples:**
+```bash
+# Clean output only
+appshot clean
 
-## Security
+# Full reset
+appshot clean --all --yes
 
-For security issues, please see [SECURITY.md](SECURITY.md).
+# Clear history
+appshot clean --history
+```
 
-## License
+### `appshot fonts`
 
-MIT © Chris Van Buskirk
+Browse, validate, and set fonts for captions.
 
-## Advanced Features
+```bash
+appshot fonts [options]
+```
 
-### Smart Frame Selection
+**Options:**
+- `--all` - List all system fonts
+- `--recommended` - Show recommended fonts only (default)
+- `--validate <name>` - Check if font is available
+- `--set <name>` - Set the caption font
+- `--select` - Interactive font selection
+- `--device <name>` - Target specific device (with --set or --select)
+- `--json` - Output as JSON
 
-Appshot automatically detects whether your screenshots are portrait or landscape and selects the appropriate device frame:
+**Examples:**
+```bash
+# Browse recommended fonts
+appshot fonts
 
-- **iPhone screenshots** automatically use portrait frames for vertical shots and landscape frames for horizontal ones
-- **iPad screenshots** work seamlessly in both orientations  
-- **Mac screenshots** always use landscape frames
-- **Watch screenshots** always use portrait frames
+# Set global font directly
+appshot fonts --set "Montserrat"
 
-Override automatic selection with `preferredFrame` in your device configuration.
+# Interactive font selection
+appshot fonts --select
 
-### Partial Frames
+# Set device-specific font
+appshot fonts --set "SF Pro" --device iphone
 
-Create dynamic App Store screenshots with partial device frames in `.appshot/config.json`:
+# Validate before setting
+appshot fonts --validate "My Font" && appshot fonts --set "My Font"
 
-```json
-{
-  "devices": {
-    "iphone": {
-      "partialFrame": true,
-      "frameOffset": 25  // Cut off bottom 25%
-    }
-  }
-}
+# List all system fonts
+appshot fonts --all
+
+# JSON output for automation
+appshot fonts --json > fonts.json
 ```
 
-### Caption Positioning
+### `appshot gradients`
 
-Place captions above the device frame (recommended) or as an overlay:
+Manage gradient presets.
 
-```json
-{
-  "caption": {
-    "position": "above",  // or "overlay"
-    "paddingTop": 120,
-    "paddingBottom": 80
-  }
-}
+```bash
+appshot gradients [options]
+appshot gradients select
 ```
 
-### Dynamic Caption Box System
+**Options:**
+- `--list` - List all presets (default)
+- `--category <name>` - Filter by category
+- `--preview <id>` - Generate preview image
+- `--sample` - Generate all samples with HTML
+- `--apply <id>` - Apply preset to project
+
+**Examples:**
+```bash
+# Browse all
+appshot gradients
 
-Appshot features an intelligent caption system that automatically adapts to your content and device positioning:
+# Apply preset
+appshot gradients --apply ocean
 
-#### How It Works
+# Interactive selection
+appshot gradients select
 
-1. **Automatic Text Wrapping** - Long captions automatically wrap to multiple lines based on available width
-2. **Dynamic Height Calculation** - Caption area expands or contracts based on:
-   - Text content length
-   - Device frame position
-   - Available space constraints
-3. **Smart Positioning** - Caption space adjusts to device placement:
-   - Device at **top** → Minimal caption space (15% of screen)
-   - Device at **center** → Balanced caption space
-   - Device at **bottom** → Maximum caption space (up to 50% of screen)
+# Generate samples
+appshot gradients --sample
+```
 
-#### Configuration
+### `appshot init`
 
-Global caption box settings in `.appshot/config.json`:
+Initialize new project with scaffolding.
 
-```json
-{
-  "caption": {
-    "fontsize": 64,
-    "box": {
-      "autoSize": true,      // Auto-size height based on content
-      "maxLines": 3,         // Maximum lines before truncation
-      "lineHeight": 1.4,     // Line spacing (1.2-1.8)
-      "minHeight": 100,      // Minimum caption area height
-      "maxHeight": 500       // Maximum caption area height
-    }
-  }
-}
+```bash
+appshot init [options]
 ```
 
-Device-specific overrides:
+**Options:**
+- `--force` - Overwrite existing files
 
-```json
-{
-  "devices": {
-    "iphone": {
-      "captionBox": {
-        "autoSize": true,
-        "maxLines": 4,       // iPhone can show more lines
-        "lineHeight": 1.5    // More spacing for readability
-      }
-    },
-    "watch": {
-      "captionBox": {
-        "maxLines": 2,       // Watch limited to 2 lines
-        "lineHeight": 1.3    // Tighter spacing
-      }
-    }
-  }
-}
+**Creates:**
+- `.appshot/config.json`
+- `.appshot/captions/`
+- `screenshots/` directories
+- Default configuration
+
+### `appshot migrate`
+
+Migrate project structure to latest version.
+
+```bash
+appshot migrate [options]
 ```
 
-#### Examples
+**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)
 
-**Long Caption Handling:**
-- Input: "This is a very long caption that needs multiple lines to display properly"
-- Result: Automatically wrapped to 2-3 centered lines with proper spacing
+**Examples:**
+```bash
+# Migrate existing screenshots to language subdirectories
+appshot migrate --output-structure
 
-**Device Position Impact:**
-- `framePosition: "top"` → Caption gets ~400px height
-- `framePosition: "center"` → Caption gets ~700px height  
-- `framePosition: "bottom"` → Caption gets ~1400px height
+# Preview migration without changes
+appshot migrate --output-structure --dry-run
 
-**Best Practices:**
-- Keep captions concise (under 100 characters)
-- Use 3-4 lines maximum for readability
-- Test with `appshot build --preview` to quickly iterate
-- Adjust `lineHeight` for visual balance (1.4 recommended)
+# Specify target language
+appshot migrate --output-structure --lang fr
+```
 
-### Device-Specific Styling
+### `appshot localize`
 
-Use the `appshot style` command or configure directly in `.appshot/config.json`:
+Batch translate all captions using AI.
 
-```json
-{
+```bash
+appshot localize --langs <codes> [options]
+```
+
+**Options:**
+- `--langs <codes>` - Target languages (required)
+- `--device <name>` - Specific device only
+- `--model <name>` - OpenAI model (default: gpt-4o-mini)
+- `--source <lang>` - Source language (default: en)
+- `--review` - Review before saving
+- `--overwrite` - Replace existing translations
+
+**Examples:**
+```bash
+# Translate all
+appshot localize --langs es,fr,de
+
+# Device-specific
+appshot localize --device iphone --langs ja,ko
+
+# Premium model with review
+appshot localize --langs zh-CN --model gpt-5 --review
+```
+
+### `appshot presets`
+
+Manage App Store screenshot presets.
+
+```bash
+appshot presets [options]
+```
+
+**Options:**
+- `--list` - List all presets (default)
+- `--required` - Show required only
+- `--generate <ids>` - Generate config for presets
+- `--category <type>` - Filter by device type
+- `--output <file>` - Output file for config
+
+**Examples:**
+```bash
+# View all
+appshot presets
+
+# Required only
+appshot presets --required
+
+# Generate config
+appshot presets --generate iphone-6-9,ipad-13
+```
+
+### `appshot specs`
+
+Display device specifications.
+
+```bash
+appshot specs [options]
+```
+
+**Options:**
+- `--device <name>` - Filter by device
+- `--json` - Output as JSON
+
+**Shows:**
+- Supported resolutions
+- Frame availability
+- Orientation support
+- App Store requirements
+
+### `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.
+
+```bash
+appshot validate [options]
+```
+
+**Options:**
+- `--strict` - Validate required presets only
+- `--fix` - Show fix suggestions
+
+**Validates:**
+- Resolution compliance
+- Aspect ratios
+- Required presets
+- File formats
+
+## ⚙️ 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
+  },
+  "caption": {
+    "font": "Font Name",
+    "fontsize": 64,              // Pixels
+    "color": "#FFFFFF",
+    "align": "center",           // left, center, right
+    "position": "above",         // above, overlay
+    "paddingTop": 100,
+    "paddingBottom": 60,
+    "box": {
+      "autoSize": true,          // Dynamic height
+      "maxLines": 3,
+      "lineHeight": 1.4,
+      "minHeight": 100,
+      "maxHeight": 500
+    }
+  },
   "devices": {
     "iphone": {
-      "partialFrame": true,          // Enable partial frame
-      "frameOffset": 25,             // Cut off bottom 25%
-      "framePosition": "center",     // or "top", "bottom", 0-100
-      "frameScale": 0.9,             // Size multiplier (0.5-2.0)
-      "captionSize": 72,             // Override global caption size
-      "captionPosition": "above",    // Override global position
-      "captionBox": {                // Caption box configuration
-        "autoSize": true,            // Auto-size based on content
-        "maxLines": 4,               // Maximum lines before truncation
-        "lineHeight": 1.4            // Line spacing multiplier
+      "input": "./screenshots/iphone",
+      "resolution": "1284x2778",
+      "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
       }
-    },
-    "watch": {
-      "framePosition": "bottom",     // Position at bottom
-      "frameScale": 1.3,             // Make watch larger
-      "partialFrame": true,          // Cut off band
-      "frameOffset": 30              // Cut 30% from bottom
     }
   }
 }
 ```
 
-### Achieving Consistent Device Positioning
+### Device Configuration
 
-⚠️ **Important**: Caption sizing can affect device frame positioning and size. Here's how to achieve perfectly consistent screenshots:
+Each device can override global settings:
 
-#### The Problem
-
-By default, appshot uses dynamic caption sizing which causes:
-- **Variable device sizes** - Longer captions = smaller devices
-- **Variable device positions** - Caption height affects vertical placement
-- **Inconsistent layouts** - Each screenshot looks different
+```json
+{
+  "devices": {
+    "iphone": {
+      // Required
+      "input": "./screenshots/iphone",
+      "resolution": "1284x2778",
+      
+      // 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",
+      "captionBox": {
+        "autoSize": false,
+        "minHeight": 320,
+        "maxHeight": 320,
+        "maxLines": 3
+      }
+    }
+  }
+}
+```
 
-#### The Solution: Fixed Layout Configuration
+### Fixed Layout Configuration
 
-To ensure all screenshots have identical device size and position regardless of caption length:
+For consistent screenshots regardless of caption length:
 
 ```json
 {
   "devices": {
     "iphone": {
-      "autoFrame": false,              // Disable auto frame selection
-      "preferredFrame": "iphone-16-pro-max-portrait",  // Use specific frame
-      "frameScale": 0.85,              // Lock device at 85% size
-      "framePosition": 40,             // Position at 40% from top
+      "autoFrame": false,
+      "preferredFrame": "iphone-16-pro-max-portrait",
+      "frameScale": 0.85,
+      "framePosition": 40,
       "captionBox": {
-        "autoSize": false,             // CRITICAL: Disable auto-sizing
-        "minHeight": 320,              // CRITICAL: Set fixed height
-        "maxHeight": 320               // CRITICAL: Same as minHeight
+        "autoSize": false,    // Critical
+        "minHeight": 320,     // Fixed height
+        "maxHeight": 320      // Same as min
       }
     }
   }
 }
 ```
 
-#### Key Settings Explained
+## 🤖 Agent & Automation Guide
+
+### Design Principles
+
+Appshot is built for automation:
+
+1. **Predictable** - Consistent commands and outputs
+2. **Scriptable** - JSON configs, exit codes, no GUI
+3. **Composable** - Unix philosophy, pipe-friendly
+4. **Fast** - Parallel processing, no overhead
+
+### JSON Output Mode
+
+Most commands support JSON output for parsing:
+
+```bash
+# Device specs as JSON
+appshot specs --json
+
+# Font list as JSON
+appshot fonts --json
+
+# Preset data as JSON
+appshot presets --json
+
+# Validation results as JSON
+appshot validate --json
+```
+
+### Exit Codes
+
+| Code | Meaning | Commands |
+|------|---------|----------|
+| 0 | Success | All |
+| 1 | Configuration error | build, check |
+| 2 | Missing files | build, validate |
+| 3 | Processing error | build |
+| 4 | Invalid input | All |
+| 5 | API error | localize, caption |
+
+### Batch Operations
+
+```bash
+# Process multiple devices
+appshot build --devices iphone,ipad,mac
+
+# Multiple languages
+appshot build --langs en,es,fr,de,ja
+
+# Parallel processing
+appshot build --concurrency 10
+```
+
+### CI/CD Integration
+
+#### GitHub Actions
+
+```yaml
+name: Generate Screenshots
+on: [push]
+
+jobs:
+  screenshots:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v2
+      
+      - name: Setup Node
+        uses: actions/setup-node@v2
+        with:
+          node-version: '18'
+      
+      - name: Install Appshot
+        run: npm install -g appshot-cli
+      
+      - name: Generate Screenshots
+        run: |
+          appshot init --force
+          appshot gradients --apply ocean
+          appshot build --preset iphone-6-9,ipad-13
+      
+      - name: Upload Artifacts
+        uses: actions/upload-artifact@v2
+        with:
+          name: screenshots
+          path: final/
+```
+
+#### Shell Script Automation
+
+```bash
+#!/bin/bash
+set -e
+
+# Configure
+cat > .appshot/config.json << EOF
+{
+  "gradient": {"colors": ["#FF5733", "#FFC300"]},
+  "devices": {
+    "iphone": {"resolution": "1284x2778"}
+  }
+}
+EOF
+
+# Add captions programmatically
+echo '{"home.png": "Welcome"}' > .appshot/captions/iphone.json
+
+# Build
+appshot build --devices iphone
+
+# Validate
+appshot validate --strict || exit 1
+```
+
+### MCP Integration
 
-1. **`autoFrame: false`** - Disables automatic frame selection
-   - Use with `preferredFrame` to specify exact device frame
-   - Ensures consistent frame across all screenshots
+Works with Model Context Protocol tools:
 
-2. **`frameScale`** - Controls device size (0.5 to 2.0)
-   - Set explicitly to lock device size
-   - Without this, device scales based on available space
+```bash
+# MCP captures screenshot
+mcp-screenshot capture --output ./screenshots/iphone/home.png
 
-3. **`framePosition`** - Vertical positioning (0-100 or "top"/"center"/"bottom")
-   - Number = percentage from top of available space
-   - Keeps device at consistent height
+# Appshot processes
+appshot build --devices iphone --no-interactive
+```
 
-4. **`captionBox.autoSize: false`** - Disables dynamic caption sizing
-   - MUST be false for consistent layouts
-   - Default is true (adapts to content)
+### Python Automation
+
+```python
+import subprocess
+import json
+
+def generate_screenshots(device, captions):
+    # Configure
+    config = {
+        "gradient": {"colors": ["#0077BE", "#33CCCC"]},
+        "devices": {
+            device: {"resolution": "1284x2778"}
+        }
+    }
+    
+    with open('.appshot/config.json', 'w') as f:
+        json.dump(config, f)
+    
+    # Add captions
+    with open(f'.appshot/captions/{device}.json', 'w') as f:
+        json.dump(captions, f)
+    
+    # Build
+    result = subprocess.run(
+        ['appshot', 'build', '--devices', device],
+        capture_output=True,
+        text=True
+    )
+    
+    return result.returncode == 0
+
+# Usage
+captions = {
+    "home.png": "Your Dashboard",
+    "settings.png": "Customize Everything"
+}
+generate_screenshots("iphone", captions)
+```
+
+### Node.js Automation
+
+```javascript
+import { exec } from 'child_process';
+import { writeFileSync } from 'fs';
+
+async function generateScreenshots() {
+  // 1. Initialize
+  await execPromise('appshot init --force');
+  
+  // 2. Configure
+  const config = {
+    gradient: { colors: ['#FF5733', '#FFC300'] },
+    caption: { font: 'SF Pro', fontsize: 64 }
+  };
+  writeFileSync('.appshot/config.json', JSON.stringify(config));
+  
+  // 3. Add captions
+  const captions = {
+    'home.png': {
+      en: 'Welcome',
+      es: 'Bienvenido',
+      fr: 'Bienvenue'
+    }
+  };
+  writeFileSync('.appshot/captions/iphone.json', JSON.stringify(captions));
+  
+  // 4. Build with multiple languages
+  await execPromise('appshot build --langs en,es,fr');
+}
+
+function execPromise(cmd) {
+  return new Promise((resolve, reject) => {
+    exec(cmd, (error, stdout) => {
+      if (error) reject(error);
+      else resolve(stdout);
+    });
+  });
+}
+```
 
-5. **`minHeight` = `maxHeight`** - Forces exact caption height
-   - Both MUST be set to same value
-   - Creates fixed caption area regardless of text length
+## 🎯 Recipes & Examples
 
-#### Complete Example for Consistent iPhone Screenshots
+### App Store Submission Workflow
+
+```bash
+# 1. Initialize project
+appshot init
+
+# 2. Configure for App Store
+appshot presets --generate iphone-6-9,ipad-13 > .appshot/config.json
+
+# 3. Add screenshots
+cp simulator/*.png screenshots/iphone/
+
+# 4. Add captions with translation
+export OPENAI_API_KEY="sk-..."
+appshot caption --device iphone --translate --langs es,fr,de,ja,zh-CN
+
+# 5. Apply premium gradient
+appshot gradients --apply twilight
+
+# 6. Configure styling
+appshot style --device iphone
+
+# 7. Build all localizations
+appshot build --preset iphone-6-9,ipad-13 --langs en,es,fr,de,ja,zh-CN
+
+# 8. Validate
+appshot validate --strict
+
+# 9. Output ready in final/
+```
+
+### Consistent Marketing Screenshots
+
+For identical device positioning across all screenshots:
 
 ```json
 {
-  "gradient": {
-    "colors": ["#FF5733", "#FFC300"],
-    "direction": "top-bottom"
-  },
-  "caption": {
-    "fontsize": 64,
-    "color": "#FFFFFF",
-    "align": "center",
-    "paddingTop": 100
-  },
   "devices": {
     "iphone": {
-      "input": "./screenshots/iphone",
       "resolution": "1284x2778",
       "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
-      },
-      "frameScale": 0.85,
-      "framePosition": 40
+      }
     }
   }
 }
 ```
 
-With this configuration:
-- ✅ All devices are exactly the same size
-- ✅ All devices are at the same vertical position
-- ✅ Caption area is always 320px tall
-- ✅ Long captions truncate instead of expanding
-- ✅ Professional, consistent App Store screenshots
+### Brand Guidelines Compliance
+
+```json
+{
+  "gradient": {
+    "colors": ["#BrandColor1", "#BrandColor2"],
+    "direction": "diagonal"
+  },
+  "caption": {
+    "font": "Brand Font Name",
+    "fontsize": 72,
+    "color": "#BrandTextColor",
+    "align": "center"
+  }
+}
+```
+
+### Multi-Device Campaign
+
+```bash
+# Configure each device
+appshot style --device iphone
+appshot style --device ipad
+appshot style --device mac
+
+# Build all at once
+appshot build --devices iphone,ipad,mac --langs en,es,fr
+
+# Output structure (language subdirectories):
+# final/
+#   iphone/
+#     en/ es/ fr/
+#   ipad/
+#     en/ es/ fr/
+#   mac/
+#     en/ es/ fr/
+```
+
+### A/B Testing Different Styles
 
-#### Interactive Styling
+```bash
+# Version A - Ocean gradient
+appshot gradients --apply ocean
+appshot build --devices iphone --output final-ocean
 
-Run `appshot style --device iphone` for step-by-step configuration:
-1. **Partial Frame** - Choose whether to cut off device bottom
-2. **Frame Offset** - Select how much to cut (15%, 25%, 35%, 50%, or custom)
-3. **Frame Position** - Set vertical position (top, center, bottom, or 0-100%)
-4. **Frame Scale** - Adjust device size
-5. **Caption Settings** - Customize text size, position, and box behavior
+# Version B - Sunset gradient
+appshot gradients --apply sunset
+appshot build --devices iphone --output final-sunset
 
-#### Reset Styling
+# Version C - Monochrome
+appshot gradients --apply noir
+appshot build --devices iphone --output final-noir
+```
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+#### Screenshots Not Found
 
-To reset a device to default settings:
 ```bash
-appshot style --device iphone --reset
+# Check path configuration
+appshot check
+
+# Verify screenshot location
+ls screenshots/iphone/
+
+# Fix: Update config
+{
+  "devices": {
+    "iphone": {
+      "input": "./correct/path/to/screenshots"
+    }
+  }
+}
 ```
 
-## Agent-First Design 🤖
+#### Font Not Rendering
 
-Appshot is designed to work seamlessly with LLM agents and automation tools. The CLI interface is structured for predictable, scriptable operations that agents can easily control.
+```bash
+# 1. Validate font availability
+appshot fonts --validate "Font Name"
 
-### Working with AI Agents
+# 2. Use fallback font
+appshot fonts --recommended
 
-- **Structured Commands** - All commands have consistent, predictable outputs
-- **JSON Support** - Most commands support `--json` output for agent parsing
-- **Error Codes** - Consistent exit codes for automation workflows
-- **File-Based Config** - Agents can modify `.appshot/config.json` directly
-- **Batch Operations** - Process multiple devices/languages in single commands
+# 3. Set web-safe font
+{
+  "caption": {
+    "font": "Arial"  // Always works
+  }
+}
+```
 
-### MCP (Model Context Protocol) Integration
+#### Translation Not Working
 
-Appshot works perfectly with MCP screenshot tools:
+```bash
+# Check API key
+echo $OPENAI_API_KEY
+
+# Test with different model
+appshot caption --device iphone --translate --model gpt-4o-mini
+
+# Check rate limits
+# Wait 60 seconds between large batches
+```
+
+#### Blurry Output
 
 ```bash
-# Agent takes screenshot via MCP
-mcp-screenshot capture --app "MyApp" --output ./screenshots/iphone/home.png
+# Ensure high-res input
+# Minimum: 1242x2208 for iPhone
 
-# Agent processes with appshot
+# Check scaling
+{
+  "devices": {
+    "iphone": {
+      "frameScale": 1.0  // No scaling
+    }
+  }
+}
+```
+
+#### Memory Issues with Large Batches
+
+```bash
+# Reduce concurrency
+appshot build --concurrency 2
+
+# Process in batches
 appshot build --devices iphone
+appshot build --devices ipad
 ```
 
-### Agent Workflow Example
+### Performance Tips
 
-```python
-# Example: Agent automating screenshot generation
-def generate_app_store_screenshots():
-    # 1. Agent captures screenshots from simulator/device
-    run_command("xcrun simctl io booted screenshot screen1.png")
-    
-    # 2. Agent initializes appshot project
-    run_command("appshot init")
-    
-    # 3. Agent configures styling
-    modify_json(".appshot/config.json", {
-        "gradient": {"colors": ["#FF5733", "#FFC300"]},
-        "devices": {"iphone": {"frameScale": 0.85}}
-    })
-    
-    # 4. Agent adds captions programmatically
-    modify_json(".appshot/captions/iphone.json", {
-        "screen1.png": "Your perfect companion"
-    })
-    
-    # 5. Agent builds final screenshots
-    run_command("appshot build --devices iphone")
+1. **Use appropriate concurrency**
+   ```bash
+   # For 8GB RAM
+   appshot build --concurrency 3
+   
+   # For 16GB+ RAM
+   appshot build --concurrency 8
+   ```
+
+2. **Optimize images before processing**
+   ```bash
+   # Use imagemagick to optimize
+   mogrify -quality 95 screenshots/iphone/*.png
+   ```
+
+3. **Cache translations**
+   - Translations are automatically cached
+   - Reuse improves speed and reduces costs
+
+4. **Use preview mode for testing**
+   ```bash
+   appshot build --preview
+   ```
+
+### Error Messages
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Frame not found` | Missing frame file | Run `appshot check --fix` |
+| `Invalid resolution` | Wrong dimensions | Check with `appshot validate` |
+| `Font validation failed` | Font not available | Use `appshot fonts` to find alternatives |
+| `API rate limit` | Too many requests | Add delays or reduce batch size |
+| `Out of memory` | Large images | Reduce concurrency or image size |
+
+## 🧑‍💻 Development
+
+### Building from Source
+
+```bash
+# Clone repository
+git clone https://github.com/chrisvanbuskirk/appshot.git
+cd appshot
+
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Run tests
+npm test
+
+# Link for local development
+npm link
+
+# Run in development mode
+npm run dev -- build --devices iphone
+```
+
+### Project Structure
+
+```
+appshot/
+├── src/
+│   ├── cli.ts              # Entry point
+│   ├── commands/           # Command implementations
+│   ├── core/              # Core functionality
+│   ├── services/          # Services (fonts, translation)
+│   └── types.ts           # TypeScript definitions
+├── tests/                 # Test files
+├── frames/               # Device frame images
+└── examples/            # Example projects
 ```
 
-### Why CLI-Only?
+### Testing
+
+Appshot includes comprehensive test coverage with unit tests, integration tests, and CI/CD validation.
+
+#### Test Suites
+
+- **Unit Tests** (50+ test files)
+  - Device detection and frame selection
+  - Gradient rendering and presets
+  - Font validation and fallbacks
+  - Caption positioning and text wrapping
+  - Multi-language support
+  - App Store specifications validation
 
-- **Predictable** - Agents need consistent, scriptable interfaces
-- **Composable** - Integrates with any automation pipeline
-- **Version Control** - All config is text files, perfect for Git
-- **Fast** - No UI overhead, pure processing power
-- **Universal** - Works on any system with Node.js
+- **Integration Tests** (`tests/integration/`)
+  - Full CLI command testing
+  - End-to-end workflow validation
+  - Multi-platform compatibility
+  - Error handling scenarios
+
+- **CI/CD Testing**
+  - Automated testing on every PR
+  - Multi-OS testing (Ubuntu, macOS, Windows)
+  - Multi-Node version testing (18.x, 20.x, 22.x)
+  - Visual validation workflows
+  - Screenshot artifact generation
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test
+npm test -- fonts.test.ts
+
+# Run integration tests
+npm test -- tests/integration/cli-integration.test.ts
+
+# Watch mode
+npm run test:watch
+
+# Run with coverage
+npm run test:coverage
+```
 
-## Roadmap
+### Contributing
 
-- [x] Official App Store specifications support
-- [x] Caption positioning (above/overlay)  
+We welcome contributions! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new features
+4. Ensure all tests pass
+5. Submit a pull request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## 🗺️ Roadmap
+
+### Completed ✅
+- [x] Official App Store specifications
+- [x] Caption positioning (above/overlay)
 - [x] Partial frame support
 - [x] Intelligent caption autocomplete
 - [x] Apple Watch optimizations
 - [x] Gradient presets system (24+ gradients)
-- [x] **AI-Powered Translations** - Translate captions using OpenAI models (GPT-4o, GPT-5, o1, o3)
-- [ ] **MCP Integration Guide** - Documentation for screenshot tool integration
-- [ ] **Agent API Mode** - Structured JSON input/output for all commands
-- [ ] **Android Device Support** - Google Play Store specifications
-- [ ] **Batch Config Files** - Process multiple configurations in one run
-- [ ] **Screenshot Validation API** - Programmatic validation for CI/CD
-- [ ] **Auto-Caption Generation** - Use AI to generate marketing captions from screenshots
-- [ ] **Smart Frame Detection** - AI-powered frame selection based on screenshot content
-- [ ] **Pipeline Mode** - Stream processing for large batches
-- [ ] **WebP/AVIF Support** - Modern image formats for smaller files
-- [ ] **Differential Builds** - Only rebuild changed screenshots
-
-## Support
-
-- [Report issues](https://github.com/chrisvanbuskirk/appshot/issues)
-- [Request features](https://github.com/chrisvanbuskirk/appshot/issues/new?labels=enhancement)
-- [Documentation](https://github.com/chrisvanbuskirk/appshot/wiki)
+- [x] AI-Powered Translations (GPT-4o, GPT-5, o1, o3)
+- [x] Comprehensive Font System (v0.4.0)
+
+### In Progress 🚧
+- [ ] MCP Integration Guide
+- [ ] Agent API Mode
+
+### Planned 📋
+- [ ] Android Device Support (Google Play Store)
+- [ ] Batch Config Files
+- [ ] Screenshot Validation API
+- [ ] Auto-Caption Generation
+- [ ] Smart Frame Detection
+- [ ] Pipeline Mode
+- [ ] WebP/AVIF Support
+- [ ] Differential Builds
+
+## 📄 License & Support
+
+### License
+
+MIT © Chris Van Buskirk
+
+### Support
+
+- 🐛 [Report Issues](https://github.com/chrisvanbuskirk/appshot/issues)
+- 💡 [Request Features](https://github.com/chrisvanbuskirk/appshot/issues/new?labels=enhancement)
+- 📚 [Documentation Wiki](https://github.com/chrisvanbuskirk/appshot/wiki)
+- 💬 [Discussions](https://github.com/chrisvanbuskirk/appshot/discussions)
+
+### Security
+
+For security vulnerabilities, please see [SECURITY.md](SECURITY.md).
+
+### NPM Package
+
+- 📦 [appshot-cli on NPM](https://www.npmjs.com/package/appshot-cli)
+- 🔄 Latest version: 0.4.0
+- ⬇️ Weekly downloads: ![npm](https://img.shields.io/npm/dw/appshot-cli)
+
+---
+
+<div align="center">
+Built with ❤️ for developers and AI agents who automate everything.
+</div>