@mediaproc/image 1.0.0 → 1.1.0

package/README.md

@@ -1,22 +1,22 @@
 # 📸 MediaProc Image Plugin
 
-Professional image processing CLI powered by [Sharp](https://sharp.pixelplumbing.com/). Fast, efficient, and feature-rich image manipulation toolkit with **40 comprehensive commands**.
+Professional image processing CLI powered by [Sharp](https://sharp.pixelplumbing.com/). Fast, efficient, and feature-rich image manipulation toolkit with **49 comprehensive commands**.
 
 ## 📑 Table of Contents
 
 - [Features](#-features)
 - [Installation & Usage](#-installation--usage)
 - [Quick Start](#-quick-start)
+- [Global Options & Common Flags](#-global-options--common-flags)
 - [Commands Overview](#-commands-overview)
 - [Detailed Command Reference](#-detailed-command-reference)
-  - [Transform & Resize](#-transform--resize-7-commands)
-  - [Color & Tone](#-color--tone-6-commands)
-  - [Effects & Filters](#-effects--filters-6-commands)
+  - [Transform & Resize](#-transform--resize-10-commands)
+  - [Color & Tone](#-color--tone-10-commands)
+  - [Effects & Filters](#-effects--filters-9-commands)
   - [Advanced Operations](#-advanced-operations-6-commands)
   - [Smart/AI Operations](#-smartai-operations-6-commands)
-  - [Utility Commands](#-utility-9-commands)
+  - [Utility Commands](#-utility-8-commands)
 - [Real-World Workflows](#-real-world-workflows)
-- [Global Options](#-global-options)
 - [Usage Tips](#-usage-tips)
 - [Troubleshooting](#-troubleshooting)
 
@@ -25,7 +25,7 @@ Professional image processing CLI powered by [Sharp](https://sharp.pixelplumbing
 ## ✨ Features
 
 - 🚀 **High Performance** - Built on libvips for blazing fast processing
-- 🎨 **40 Commands** - Comprehensive + custom image manipulation toolkit
+- 🎨 **49 Commands** - Comprehensive image manipulation toolkit covering all Sharp operations
 - 🔧 **Professional Features** - Quality control, dry-run mode, verbose logging
 - 📦 **Modern Formats** - WebP, AVIF, JPEG, PNG, TIFF, GIF support
 - 🎯 **Simple CLI** - Intuitive command-line interface
@@ -72,6 +72,7 @@ mediaproc-image convert photo.jpg -f webp
 ## 🎯 Quick Start
 
 **With Universal CLI:**
+
 ```bash
 # Resize an image
 mediaproc image resize photo.jpg -w 800 -h 600
@@ -90,6 +91,7 @@ mediaproc image resize --help
 ```
 
 **With Standalone Plugin:**
+
 ```bash
 # Same commands, different prefix
 mediaproc-image resize photo.jpg -w 800 -h 600
@@ -97,57 +99,285 @@ mediaproc-image convert photo.jpg -f webp -q 85
 mediaproc-image thumbnail photo.jpg -s 150
 ```
 
+---
+
+## 🌐 Global Options & Common Flags
+
+All image commands share a consistent set of common flags for unified behavior:
+
+### Standard Flags (Available on All Commands)
+
+| Flag                | Alias | Description                       | Default                   |
+| ------------------- | ----- | --------------------------------- | ------------------------- |
+| `--output <path>`   | `-o`  | Output file path                  | `<input>-<command>.<ext>` |
+| `--quality <1-100>` | `-q`  | Output quality (1-100)            | `90`                      |
+| `--dry-run`         | -     | Preview changes without executing | `false`                   |
+| `--verbose`         | `-v`  | Show detailed processing output   | `false`                   |
+| `--help`            | -     | Display command-specific help     | -                         |
+
+### How Commands Work
+
+**1. Input Processing:**
+
+```bash
+# Commands accept file paths (relative or absolute)
+mediaproc image resize photo.jpg -w 800
+mediaproc image resize /path/to/photo.jpg -w 800
+mediaproc image resize ../images/photo.jpg -w 800
+```
+
+**2. Output Naming:**
+
+```bash
+# Default: <input>-<command>.<ext>
+mediaproc image blur photo.jpg           # → photo-blur.jpg
+
+# Custom output path:
+mediaproc image blur photo.jpg -o soft.jpg
+
+# Preserve format or change:
+mediaproc image blur photo.jpg -o output.webp  # Changes format
+```
+
+**3. Quality Control:**
+
+```bash
+# High quality (larger file size)
+mediaproc image resize photo.jpg -w 1920 -q 95
+
+# Balanced (default)
+mediaproc image resize photo.jpg -w 1920 -q 90
+
+# Compressed (smaller file size)
+mediaproc image resize photo.jpg -w 1920 -q 75
+
+# Note: Quality applies to lossy formats (JPEG, WebP)
+```
+
+**4. Dry-Run Mode:**
+
+```bash
+# Preview what will happen without processing
+mediaproc image resize photo.jpg -w 1920 --dry-run
+
+# Shows: input, output paths, and operation details
+# Useful for testing commands before batch processing
+```
+
+**5. Verbose Output:**
+
+```bash
+# Show detailed processing information
+mediaproc image resize photo.jpg -w 1920 -v
+
+# Displays:
+# - Configuration settings
+# - Processing steps
+# - Metadata information
+# - File size comparisons
+```
+
+### Command-Specific Options
+
+Each command has unique options for its specific operation:
+
+**Transform Commands:**
+
+- Resize: `--width`, `--height`, `--fit`, `--position`, `--kernel`
+- Rotate: `--angle`, `--background`
+- Crop: `--left`, `--top`, `--extract-strategy`
+
+**Color Commands:**
+
+- Modulate: `--brightness`, `--saturation`, `--hue`
+- Gamma: `--value`
+- Tint: `--color`
+
+**Effect Commands:**
+
+- Blur: `--sigma`
+- Sharpen: `--amount`, `--mode`
+- Threshold: `--value`
+
+**Advanced Commands:**
+
+- Composite: `--overlay`, `--blend`, `--gravity`
+- Boolean: `--operation`, `--operand`
+- Recomb: `--matrix`
+
+### Getting Help
+
+**View all available commands:**
+
+```bash
+# Universal CLI
+mediaproc image --help
+
+# Standalone plugin
+mediaproc-image --help
+```
+
+**Get command-specific help:**
+
+```bash
+# Shows detailed usage, options, examples
+mediaproc image resize --help
+mediaproc image blur --help
+mediaproc image composite --help
+```
+
+**Help includes:**
+
+- 📝 Description and purpose
+- 🎯 Usage syntax
+- ⚙️ Available options and flags
+- 💡 Practical examples
+- 📚 Use cases and workflows
+- 💪 Tips and best practices
+
+### Format Support
+
+**Input Formats:**
+
+- JPEG (`.jpg`, `.jpeg`)
+- PNG (`.png`)
+- WebP (`.webp`)
+- AVIF (`.avif`)
+- TIFF (`.tiff`, `.tif`)
+- GIF (`.gif`)
+- SVG (`.svg`)
+- HEIF (`.heic`, `.heif`)
+
+**Output Formats:**
+
+- JPEG - Best for photos (lossy)
+- PNG - Best for graphics with transparency (lossless)
+- WebP - 25-35% smaller than JPEG (lossy/lossless)
+- AVIF - 50% smaller than JPEG (lossy/lossless)
+- TIFF - Best for professional/print (lossless)
+- GIF - Best for simple animations (limited colors)
+
+### Performance Tips
+
+**1. Format Selection:**
+
+```bash
+# Use WebP for web (smaller, fast)
+mediaproc image convert photo.jpg -f webp -q 85
+
+# Use PNG for graphics with transparency
+mediaproc image convert logo.jpg -f png
+
+# Use AVIF for maximum compression (slower encoding)
+mediaproc image convert photo.jpg -f avif -q 80
+```
+
+**2. Quality vs Size:**
+
+```bash
+# High quality (minimal compression)
+-q 95   # Large file, excellent quality
+
+# Balanced (recommended)
+-q 85   # Good file size, great quality
+
+# Aggressive (maximum compression)
+-q 70   # Small file, acceptable quality
+```
+
+**3. Chaining Operations:**
+
+```bash
+# Instead of multiple commands:
+mediaproc image resize input.jpg -w 1920 -o step1.jpg
+mediaproc image blur step1.jpg -o step2.jpg
+mediaproc image sharpen step2.jpg -o final.jpg
+
+# Consider using pipeline/batch features:
+mediaproc image batch images/ --operation "resize -w 1920"
+```
+
+**4. Batch Processing:**
+
+```bash
+# Process multiple files efficiently
+for file in *.jpg; do
+  mediaproc image optimize "$file" -q 85
+done
+```
+
+---
+
 ## 📋 Commands Overview
 
-### 🔄 Transform & Resize
-- **resize** - Resize images with advanced fit modes
-- **crop** - Extract rectangular regions
-- **rotate** - Rotate by any angle
-- **flip** - Mirror horizontally/vertically
-- **trim** - Auto-remove borders
-- **extend** - Add padding/borders
-- **thumbnail** - Generate thumbnails
-
-### 🎨 Color & Tone
-- **modulate** - Adjust brightness, saturation, hue
-- **gamma** - Apply gamma correction
-- **tint** - Apply color tint overlay
-- **grayscale** - Convert to black & white
-- **negate** - Create negative image
-- **normalize** - Auto-enhance contrast
+All **49 commands** organized by category:
+
+### 🔄 Transform & Resize (10 commands)
+
+- **resize** - Resize images with advanced fit modes (cover, contain, fill, inside, outside)
+- **crop** - Extract rectangular regions with positioning options
+- **rotate** - Rotate by any angle with background control
+- **flip** - Vertical mirroring (top-to-bottom flip)
+- **flop** - Horizontal mirroring (left-to-right flip)
+- **auto-orient** - Auto-rotate based on EXIF orientation data
+- **affine** - Apply affine transformation matrix (scale, shear, reflect)
+- **trim** - Auto-remove uniform borders from edges
+- **extend** - Add padding/borders with custom colors
+- **thumbnail** - Generate thumbnails (64px to 512px)
 
-### ✨ Effects & Filters
-- **blur** - Gaussian blur effect
-- **sharpen** - Enhance image details
-- **median** - Noise reduction filter
+### 🎨 Color & Tone (10 commands)
+
+- **modulate** - Adjust brightness, saturation, and hue
+- **gamma** - Apply gamma correction for midtones (0.1-3.0)
+- **tint** - Apply color tint overlay (RGB hex colors)
+- **grayscale** - Convert to black & white
+- **negate** - Create negative/inverted image
+- **normalize** - Auto-enhance contrast and brightness
+- **linear** - Apply linear formula: output = (a * input) + b
+- **recomb** - Recombine RGB channels using transformation matrix
+- **flatten** - Remove alpha transparency with background color
+- **unflatten** - Add alpha channel (RGB→RGBA)
+
+### ✨ Effects & Filters (9 commands)
+
+- **blur** - Gaussian blur effect (0.3-1000 sigma)
+- **sharpen** - Enhance image details and edges
+- **median** - Noise reduction filter (1-50 size)
 - **sepia** - Vintage sepia tone effect
-- **vignette** - Darken edges for focus
-- **pixelate** - Retro pixel art effect
-
-### 🎯 Advanced Operations
-- **composite** - Layer images with blending
-- **extract** - Extract channels or regions
-- **border** - Add decorative frames
-- **clahe** - Contrast enhancement (medical imaging)
-- **convolve** - Custom kernel filters
-
-### 🤖 Smart/AI Operations
-- **smart-crop** - Intelligent content-aware cropping
-- **auto-enhance** - Automatic image enhancement
-- **palette** - Extract dominant color palette
+- **vignette** - Darken edges for artistic focus
+- **pixelate** - Retro pixel art effect with custom pixel size
+- **threshold** - Binary black/white conversion (0-255)
+- **dilate** - Morphological dilation (expand bright regions)
+- **erode** - Morphological erosion (expand dark regions)
+
+### 🎯 Advanced Operations (6 commands)
+
+- **composite** - Layer images with blend modes (overlay, multiply, screen)
+- **extract** - Extract color channels (R, G, B, alpha) or regions
+- **border** - Add decorative frames with custom colors
+- **clahe** - Contrast-limited adaptive histogram equalization
+- **convolve** - Apply custom convolution kernels (sharpen, emboss, edge)
+- **boolean** - Perform boolean operations between images (AND, OR, XOR)
+
+### 🤖 Smart/AI Operations (6 commands)
+
+- **smart-crop** - Intelligent content-aware cropping (attention/entropy)
+- **auto-enhance** - Automatic color and contrast enhancement
+- **palette** - Extract dominant color palettes (2-256 colors)
 - **dominant-color** - Quick dominant color extraction
 - **grid** - Combine images into collage layouts
-- **batch** - Process multiple images at once
-
-### 🔧 Utility
-- **convert** - Format conversion
-- **optimize** - Size optimization
-- **watermark** - Add watermarks
-- **stats** - Detailed image information
-- **split** - Split image into tiles
+- **batch** - Process multiple images at once with any operation
+
+### 🔧 Utility (8 commands)
+
+- **convert** - Format conversion (JPG, PNG, WebP, AVIF, TIFF, GIF)
+- **optimize** - Size optimization (up to 70% reduction)
+- **watermark** - Add watermarks with positioning and opacity
+- **stats** - Detailed technical image statistics
+- **split** - Split image into grid tiles
 - **stack** - Stack images horizontally/vertically
-- **mirror** - Create mirror/kaleidoscope effects
-- **metadata** - View/export/remove EXIF data
+- **mirror** - Create mirror/kaleidoscope effects (horizontal, vertical, quad)
+- **metadata** - View, export, or remove EXIF data
 
 ---
 
@@ -158,11 +388,13 @@ mediaproc-image thumbnail photo.jpg -s 150
 Resize images with advanced options for fit modes, aspect ratio control, and quality settings.
 
 **Usage:**
+
 ```bash
 mediaproc image resize <input> [options]
 ```
 
 **Options:**
+
 - `-w, --width <width>` - Target width in pixels
 - `-h, --height <height>` - Target height in pixels
 - `--fit <mode>` - Fit mode: cover, contain, fill, inside, outside (default: cover)
@@ -177,6 +409,7 @@ mediaproc image resize <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Resize to 800x600 (crop to fit)
 mediaproc image resize photo.jpg -w 800 -h 600
@@ -192,6 +425,7 @@ mediaproc image resize photo.jpg -w 2000 --kernel lanczos3 -q 95
 ```
 
 **Fit Modes:**
+
 - **cover** - Fill entire area, crop if needed (default)
 - **contain** - Fit inside with padding
 - **fill** - Stretch to fill (may distort)
@@ -205,11 +439,13 @@ mediaproc image resize photo.jpg -w 2000 --kernel lanczos3 -q 95
 Convert images between formats with quality control and compression options.
 
 **Usage:**
+
 ```bash
 mediaproc image convert <input> [options]
 ```
 
 **Options:**
+
 - `-f, --format <format>` - Output format: jpg, png, webp, avif, tiff, gif (default: webp)
 - `-q, --quality <quality>` - Quality 1-100 (default: 90)
 - `--compression <level>` - PNG compression level 0-9 (default: 9)
@@ -220,6 +456,7 @@ mediaproc image convert <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Convert to WebP
 mediaproc image convert photo.jpg -f webp
@@ -235,6 +472,7 @@ mediaproc image convert photo.jpg -f png --compression 9
 ```
 
 **Format Guide:**
+
 - **WebP** - Modern format, 25-35% smaller than JPG/PNG
 - **AVIF** - Newest format, even smaller than WebP
 - **JPG** - Best for photos, lossy compression
@@ -249,11 +487,13 @@ mediaproc image convert photo.jpg -f png --compression 9
 Convert images to grayscale (black and white).
 
 **Usage:**
+
 ```bash
 mediaproc image grayscale <input> [options]
 ```
 
 **Options:**
+
 - `-o, --output <path>` - Output file path
 - `-q, --quality <quality>` - Quality 1-100 (default: 90)
 - `--dry-run` - Preview without executing
@@ -261,6 +501,7 @@ mediaproc image grayscale <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Convert to grayscale
 mediaproc image grayscale photo.jpg
@@ -273,6 +514,7 @@ mediaproc image greyscale photo.jpg
 ```
 
 **Use Cases:**
+
 - Artistic black and white photography
 - Document scanning
 - Reducing file size
@@ -286,11 +528,13 @@ mediaproc image greyscale photo.jpg
 Apply Gaussian blur effect with configurable strength.
 
 **Usage:**
+
 ```bash
 mediaproc image blur <input> [options]
 ```
 
 **Options:**
+
 - `-s, --sigma <sigma>` - Blur strength 0.3-1000 (default: 5)
 - `-o, --output <path>` - Output file path
 - `-q, --quality <quality>` - Quality 1-100 (default: 90)
@@ -299,6 +543,7 @@ mediaproc image blur <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Default blur
 mediaproc image blur photo.jpg
@@ -311,6 +556,7 @@ mediaproc image blur photo.jpg -s 2
 ```
 
 **Blur Strength Guide:**
+
 - **1-5** - Light blur (slight softness)
 - **5-15** - Medium blur (noticeable effect)
 - **15-30** - Strong blur (heavy softness)
@@ -323,11 +569,13 @@ mediaproc image blur photo.jpg -s 2
 Sharpen images to enhance details and edges.
 
 **Usage:**
+
 ```bash
 mediaproc image sharpen <input> [options]
 ```
 
 **Options:**
+
 - `-s, --sigma <sigma>` - Sharpening strength 0.01-10 (default: 1)
 - `--flat <flat>` - Sharpening for flat areas (default: 1)
 - `--jagged <jagged>` - Sharpening for jagged areas (default: 2)
@@ -338,6 +586,7 @@ mediaproc image sharpen <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Default sharpening
 mediaproc image sharpen photo.jpg
@@ -350,6 +599,7 @@ mediaproc image sharpen photo.jpg -s 1.5 --flat 1.5 --jagged 2.5
 ```
 
 **Sharpening Guide:**
+
 - **0.3-0.7** - Subtle enhancement
 - **1.0-1.5** - Normal sharpening
 - **2.0-3.0** - Strong sharpening
@@ -362,11 +612,13 @@ mediaproc image sharpen photo.jpg -s 1.5 --flat 1.5 --jagged 2.5
 Rotate images by any angle with background color control.
 
 **Usage:**
+
 ```bash
 mediaproc image rotate <input> [options]
 ```
 
 **Options:**
+
 - `-a, --angle <degrees>` - Rotation angle in degrees (default: 90)
 - `--background <color>` - Background color (default: black)
 - `-o, --output <path>` - Output file path
@@ -376,6 +628,7 @@ mediaproc image rotate <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Rotate 90° clockwise
 mediaproc image rotate photo.jpg -a 90
@@ -391,6 +644,7 @@ mediaproc image rotate photo.jpg -a -90
 ```
 
 **Common Angles:**
+
 - **90** - Rotate right (clockwise)
 - **-90 or 270** - Rotate left (counter-clockwise)
 - **180** - Upside down
@@ -403,11 +657,13 @@ mediaproc image rotate photo.jpg -a -90
 Mirror images horizontally, vertically, or both.
 
 **Usage:**
+
 ```bash
 mediaproc image flip <input> [options]
 ```
 
 **Options:**
+
 - `-d, --direction <direction>` - Direction: horizontal, vertical, both (default: horizontal)
 - `-o, --output <path>` - Output file path
 - `-q, --quality <quality>` - Quality 1-100 (default: 90)
@@ -416,6 +672,7 @@ mediaproc image flip <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Flip horizontally (mirror left-right)
 mediaproc image flip photo.jpg
@@ -434,11 +691,13 @@ mediaproc image flip photo.jpg -d both
 Extract rectangular regions from images.
 
 **Usage:**
+
 ```bash
 mediaproc image crop <input> [options]
 ```
 
 **Options:**
+
 - `-x <pixels>` - X coordinate (left position, required)
 - `-y <pixels>` - Y coordinate (top position, required)
 - `-w, --width <pixels>` - Crop width (required)
@@ -450,6 +709,7 @@ mediaproc image crop <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Crop 800x600 region from top-left (0,0)
 mediaproc image crop photo.jpg -x 0 -y 0 -w 800 -h 600
@@ -468,11 +728,13 @@ mediaproc image crop photo.jpg -x 400 -y 300 -w 800 -h 600
 Optimize image file size with minimal quality loss.
 
 **Usage:**
+
 ```bash
 mediaproc image optimize <input> [options]
 ```
 
 **Options:**
+
 - `-q, --quality <quality>` - Quality 1-100 (default: 85)
 - `--aggressive` - More aggressive compression (quality 70)
 - `-o, --output <path>` - Output file path
@@ -481,6 +743,7 @@ mediaproc image optimize <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Optimize with quality 85
 mediaproc image optimize photo.jpg
@@ -493,6 +756,7 @@ mediaproc image optimize pic.jpg --aggressive
 ```
 
 **Quality Guide:**
+
 - **90-100** - Minimal compression, large files
 - **85-89** - Balanced (recommended for web)
 - **70-84** - Good compression, slight quality loss
@@ -505,11 +769,13 @@ mediaproc image optimize pic.jpg --aggressive
 Add watermarks to images with position and opacity control.
 
 **Usage:**
+
 ```bash
 mediaproc image watermark <input> <watermark> [options]
 ```
 
 **Options:**
+
 - `--position <position>` - Position: center, top-left, top-right, bottom-left, bottom-right (default: bottom-right)
 - `--opacity <opacity>` - Opacity 0-1 (default: 0.5)
 - `--scale <scale>` - Watermark scale 0.1-1 (default: 0.2)
@@ -520,6 +786,7 @@ mediaproc image watermark <input> <watermark> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Add watermark to bottom-right
 mediaproc image watermark photo.jpg logo.png
@@ -535,6 +802,7 @@ mediaproc image watermark photo.jpg brand.png --scale 0.3 --position top-right
 ```
 
 **Opacity Guide:**
+
 - **0.1-0.3** - Very subtle
 - **0.4-0.6** - Balanced (recommended)
 - **0.7-0.9** - Clearly visible
@@ -547,11 +815,13 @@ mediaproc image watermark photo.jpg brand.png --scale 0.3 --position top-right
 Generate thumbnails with configurable sizes.
 
 **Usage:**
+
 ```bash
 mediaproc image thumbnail <input> [options]
 ```
 
 **Options:**
+
 - `-s, --size <size>` - Thumbnail size in pixels (default: 150)
 - `--fit <fit>` - Fit mode: cover, contain, fill, inside, outside (default: cover)
 - `-q, --quality <quality>` - Quality 1-100 (default: 85)
@@ -561,6 +831,7 @@ mediaproc image thumbnail <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Generate 150x150 thumbnail
 mediaproc image thumbnail photo.jpg
@@ -573,6 +844,7 @@ mediaproc image thumbnail pic.jpg -s 100 --fit contain
 ```
 
 **Common Sizes:**
+
 - **64x64** - Favicon, small icons
 - **150x150** - Default thumbnail
 - **200x200** - Medium thumbnails
@@ -586,11 +858,13 @@ mediaproc image thumbnail pic.jpg -s 100 --fit contain
 Apply color tint overlay to images.
 
 **Usage:**
+
 ```bash
 mediaproc image tint <input> [options]
 ```
 
 **Options:**
+
 - `-c, --color <color>` - Tint color (hex, rgb, or name, default: #0000ff)
 - `-o, --output <path>` - Output file path
 - `-q, --quality <quality>` - Quality 1-100 (default: 90)
@@ -599,6 +873,7 @@ mediaproc image tint <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Apply blue tint
 mediaproc image tint photo.jpg -c blue
@@ -611,6 +886,7 @@ mediaproc image tint pic.jpg -c "rgb(255, 100, 50)"
 ```
 
 **Common Tints:**
+
 - **Sepia (#704214)** - Vintage/warm look
 - **Blue (#0066cc)** - Cool/cold mood
 - **Orange (#ff6600)** - Warm/sunset effect
@@ -624,11 +900,13 @@ mediaproc image tint pic.jpg -c "rgb(255, 100, 50)"
 Create negative/inverted images.
 
 **Usage:**
+
 ```bash
 mediaproc image negate <input> [options]
 ```
 
 **Options:**
+
 - `--alpha` - Also negate alpha/transparency channel
 - `-o, --output <path>` - Output file path
 - `-q, --quality <quality>` - Quality 1-100 (default: 90)
@@ -637,6 +915,7 @@ mediaproc image negate <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Create negative
 mediaproc image negate photo.jpg
@@ -646,6 +925,7 @@ mediaproc image negate image.png --alpha
 ```
 
 **Use Cases:**
+
 - Artistic effects
 - X-ray style images
 - Film negatives
@@ -659,11 +939,13 @@ mediaproc image negate image.png --alpha
 Normalize images by auto-enhancing contrast.
 
 **Usage:**
+
 ```bash
 mediaproc image normalize <input> [options]
 ```
 
 **Options:**
+
 - `-o, --output <path>` - Output file path
 - `-q, --quality <quality>` - Quality 1-100 (default: 90)
 - `--dry-run` - Preview without executing
@@ -671,6 +953,7 @@ mediaproc image normalize <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Auto-enhance contrast
 mediaproc image normalize photo.jpg
@@ -683,6 +966,7 @@ mediaproc image normalize overexposed.jpg
 ```
 
 **Best For:**
+
 - Underexposed photos
 - Overexposed photos
 - Low contrast images
@@ -696,11 +980,13 @@ mediaproc image normalize overexposed.jpg
 Adjust brightness, saturation, and hue.
 
 **Usage:**
+
 ```bash
 mediaproc image modulate <input> [options]
 ```
 
 **Options:**
+
 - `-b, --brightness <value>` - Brightness multiplier 0.1-10 (default: 1)
 - `-s, --saturation <value>` - Saturation multiplier 0.1-10 (default: 1)
 - `--hue <degrees>` - Hue rotation -360 to 360 (default: 0)
@@ -711,6 +997,7 @@ mediaproc image modulate <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Increase brightness by 20%
 mediaproc image modulate photo.jpg -b 1.2
@@ -726,12 +1013,14 @@ mediaproc image modulate photo.jpg -b 1.2 -s 1.3 --hue 30
 ```
 
 **Brightness:**
+
 - **0.5** - 50% darker
 - **1.0** - No change (default)
 - **1.5** - 50% brighter
 - **2.0** - Double brightness
 
 **Saturation:**
+
 - **0.0** - Grayscale
 - **1.0** - No change (default)
 - **1.5** - 50% more vibrant
@@ -744,11 +1033,13 @@ mediaproc image modulate photo.jpg -b 1.2 -s 1.3 --hue 30
 Apply gamma correction to adjust midtones.
 
 **Usage:**
+
 ```bash
 mediaproc image gamma <input> [options]
 ```
 
 **Options:**
+
 - `-g, --gamma <value>` - Gamma value 1-3 (default: 2.2)
 - `--gamma-out <value>` - Output gamma value (optional)
 - `-o, --output <path>` - Output file path
@@ -758,6 +1049,7 @@ mediaproc image gamma <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Standard sRGB gamma
 mediaproc image gamma photo.jpg -g 2.2
@@ -770,6 +1062,7 @@ mediaproc image gamma pic.jpg -g 2.8
 ```
 
 **Gamma Values:**
+
 - **1.0** - Linear (no correction)
 - **1.5** - Lighter midtones
 - **2.2** - Standard sRGB
@@ -783,11 +1076,13 @@ mediaproc image gamma pic.jpg -g 2.8
 Auto-trim/remove border edges from images.
 
 **Usage:**
+
 ```bash
 mediaproc image trim <input> [options]
 ```
 
 **Options:**
+
 - `-t, --threshold <value>` - Edge detection threshold 1-100 (default: 10)
 - `-o, --output <path>` - Output file path
 - `-q, --quality <quality>` - Quality 1-100 (default: 90)
@@ -796,6 +1091,7 @@ mediaproc image trim <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Auto-trim with default threshold
 mediaproc image trim photo.jpg
@@ -808,12 +1104,14 @@ mediaproc image trim pic.jpg -t 20
 ```
 
 **Threshold Guide:**
+
 - **1-5** - Very sensitive
 - **10** - Default (balanced)
 - **15-25** - Aggressive
 - **25+** - Very aggressive
 
 **Best For:**
+
 - Scanned documents
 - Screenshots
 - Solid color borders
@@ -827,11 +1125,13 @@ mediaproc image trim pic.jpg -t 20
 Add padding/borders around images.
 
 **Usage:**
+
 ```bash
 mediaproc image extend <input> [options]
 ```
 
 **Options:**
+
 - `--all <pixels>` - Padding on all sides (shortcut)
 - `--top <pixels>` - Top padding
 - `--bottom <pixels>` - Bottom padding
@@ -845,6 +1145,7 @@ mediaproc image extend <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Add 50px padding on all sides
 mediaproc image extend photo.jpg --all 50
@@ -860,6 +1161,7 @@ mediaproc image extend photo.jpg --all 30 --background "#ff0000"
 ```
 
 **Use Cases:**
+
 - Adding borders/frames
 - Letterbox/pillarbox effect
 - Preparing for specific dimensions
@@ -873,11 +1175,13 @@ mediaproc image extend photo.jpg --all 30 --background "#ff0000"
 Apply median filter for noise reduction.
 
 **Usage:**
+
 ```bash
 mediaproc image median <input> [options]
 ```
 
 **Options:**
+
 - `-s, --size <size>` - Filter size 1-50 (default: 3)
 - `-o, --output <path>` - Output file path
 - `-q, --quality <quality>` - Quality 1-100 (default: 90)
@@ -886,6 +1190,7 @@ mediaproc image median <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Default median filter
 mediaproc image median photo.jpg
@@ -898,12 +1203,14 @@ mediaproc image median scan.jpg -s 7
 ```
 
 **Filter Size:**
+
 - **1** - Minimal smoothing
 - **3** - Default (balanced)
 - **5-7** - Strong noise reduction
 - **10+** - Heavy smoothing
 
 **Best For:**
+
 - Salt-and-pepper noise
 - Scanner artifacts
 - JPEG compression noise
@@ -917,11 +1224,13 @@ mediaproc image median scan.jpg -s 7
 Composite/blend multiple images together with various blend modes and positioning.
 
 **Usage:**
+
 ```bash
 mediaproc image composite <base> <overlay> [options]
 ```
 
 **Options:**
+
 - `--blend <mode>` - Blend mode: over, add, multiply, screen, overlay (default: over)
 - `--gravity <position>` - Position: center, north, south, east, west, northeast, northwest, southeast, southwest (default: center)
 - `--opacity <value>` - Overlay opacity 0-1 (default: 1)
@@ -932,6 +1241,7 @@ mediaproc image composite <base> <overlay> [options]
 - `-v, --verbose` - Show detailed output
 
 **Examples:**
+
 ```bash
 # Overlay image on top
 mediaproc image composite base.jpg overlay.png
@@ -947,6 +1257,7 @@ mediaproc image composite base.jpg watermark.png -x 50 -y 50
 ```
 
 **Blend Modes:**
+
 - **over** - Normal overlay (default)
 - **add** - Additive blend
 - **multiply** - Darken blend
@@ -960,17 +1271,20 @@ mediaproc image composite base.jpg watermark.png -x 50 -y 50
 Extract specific color channels or regions from images.
 
 **Usage:**
+
 ```bash
 mediaproc image extract <input> [options]
 ```
 
 **Options:**
+
 - `--channel <channel>` - Channel: red, green, blue, alpha (default: red)
 - `-o, --output <path>` - Output file path
 - `--dry-run` - Preview without executing
 - `-v, --verbose` - Show detailed output
 
 **Examples:**
+
 ```bash
 # Extract red channel
 mediaproc image extract photo.jpg --channel red
@@ -983,6 +1297,7 @@ mediaproc image extract pic.jpg --channel green -o green-channel.jpg
 ```
 
 **Use Cases:**
+
 - Channel analysis
 - Alpha mask extraction
 - Color correction workflows
@@ -996,11 +1311,13 @@ mediaproc image extract pic.jpg --channel green -o green-channel.jpg
 Add colored borders/frames around images.
 
 **Usage:**
+
 ```bash
 mediaproc image border <input> [options]
 ```
 
 **Options:**
+
 - `-w, --width <pixels>` - Border width (default: 10)
 - `-c, --color <color>` - Border color (default: black)
 - `-o, --output <path>` - Output file path
@@ -1008,6 +1325,7 @@ mediaproc image border <input> [options]
 - `-v, --verbose` - Show detailed output
 
 **Examples:**
+
 ```bash
 # Default black border
 mediaproc image border photo.jpg
@@ -1023,6 +1341,7 @@ mediaproc image border photo.jpg -w 30 -c "#f0f0f0"
 ```
 
 **Popular Border Styles:**
+
 - **Black 10px** - Classic frame
 - **White 20-30px** - Instagram style
 - **Gray 5px** - Subtle separation
@@ -1035,15 +1354,18 @@ mediaproc image border photo.jpg -w 30 -c "#f0f0f0"
 Display detailed technical information about images.
 
 **Usage:**
+
 ```bash
 mediaproc image stats <input> [options]
 ```
 
 **Options:**
+
 - `-v, --verbose` - Show extended metadata and channel statistics
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Basic stats
 mediaproc image stats photo.jpg
@@ -1053,6 +1375,7 @@ mediaproc image stats image.png -v
 ```
 
 **Information Displayed:**
+
 - Format and dimensions
 - Color space and channels
 - File size and compression
@@ -1063,6 +1386,7 @@ mediaproc image stats image.png -v
 - Channel statistics (with -v)
 
 **Use Cases:**
+
 - Pre-processing analysis
 - Quality verification
 - Format identification
@@ -1076,17 +1400,20 @@ mediaproc image stats image.png -v
 Apply vintage sepia tone effect for classic photography look.
 
 **Usage:**
+
 ```bash
 mediaproc image sepia <input> [options]
 ```
 
 **Options:**
+
 - `-i, --intensity <value>` - Sepia intensity 0-100 (default: 80)
 - `-o, --output <path>` - Output file path
 - `--dry-run` - Preview without executing
 - `-v, --verbose` - Show detailed output
 
 **Examples:**
+
 ```bash
 # Classic sepia
 mediaproc image sepia photo.jpg
@@ -1099,6 +1426,7 @@ mediaproc image sepia modern.jpg -i 40
 ```
 
 **Intensity Guide:**
+
 - **20-40** - Subtle warm tint
 - **60-80** - Classic sepia (recommended)
 - **80-100** - Strong vintage effect
@@ -1110,11 +1438,13 @@ mediaproc image sepia modern.jpg -i 40
 Apply Contrast Limited Adaptive Histogram Equalization for advanced contrast enhancement.
 
 **Usage:**
+
 ```bash
 mediaproc image clahe <input> [options]
 ```
 
 **Options:**
+
 - `-w, --width <pixels>` - Region width (default: 8)
 - `-h, --height <pixels>` - Region height (default: 8)
 - `--max-slope <value>` - Maximum contrast slope 0-100 (default: 2.5)
@@ -1123,6 +1453,7 @@ mediaproc image clahe <input> [options]
 - `-v, --verbose` - Show detailed output
 
 **Examples:**
+
 ```bash
 # Default CLAHE
 mediaproc image clahe photo.jpg
@@ -1135,6 +1466,7 @@ mediaproc image clahe medical.png -w 16 -h 16
 ```
 
 **Best For:**
+
 - Medical imaging
 - Scientific photography
 - Underwater photos
@@ -1148,17 +1480,20 @@ mediaproc image clahe medical.png -w 16 -h 16
 Apply custom convolution kernels for advanced image filtering.
 
 **Usage:**
+
 ```bash
 mediaproc image convolve <input> [options]
 ```
 
 **Options:**
+
 - `-k, --kernel <name>` - Preset kernel: sharpen, emboss, edge-detect, box-blur, gaussian-blur, laplacian, high-pass
 - `-o, --output <path>` - Output file path
 - `--dry-run` - Preview without executing
 - `-v, --verbose` - Show detailed output
 
 **Examples:**
+
 ```bash
 # Edge detection
 mediaproc image convolve photo.jpg -k edge-detect
@@ -1171,6 +1506,7 @@ mediaproc image convolve pic.jpg -k high-pass
 ```
 
 **Preset Kernels:**
+
 - **sharpen** - Enhance edges
 - **emboss** - 3D relief effect
 - **edge-detect** - Detect edges
@@ -1186,17 +1522,20 @@ mediaproc image convolve pic.jpg -k high-pass
 Add vignette effect (darkened edges) for artistic focus.
 
 **Usage:**
+
 ```bash
 mediaproc image vignette <input> [options]
 ```
 
 **Options:**
+
 - `-i, --intensity <value>` - Vignette intensity 0-100 (default: 50)
 - `-o, --output <path>` - Output file path
 - `--dry-run` - Preview without executing
 - `-v, --verbose` - Show detailed output
 
 **Examples:**
+
 ```bash
 # Default vignette
 mediaproc image vignette photo.jpg
@@ -1209,6 +1548,7 @@ mediaproc image vignette landscape.jpg -i 80
 ```
 
 **Intensity Guide:**
+
 - **20-40** - Subtle focus
 - **40-60** - Balanced (recommended)
 - **60-80** - Dramatic effect
@@ -1229,18 +1569,21 @@ All commands support these global options:
 ## 💡 Usage Tips
 
 ### Quality Settings
+
 - **90-100**: Maximum quality, larger files
 - **85-90**: Recommended for web (best balance)
 - **70-85**: Good compression, slight quality loss
 - **Below 70**: High compression, noticeable quality loss
 
 ### File Formats
+
 - **WebP**: Best for web, 25-35% smaller than JPG/PNG
 - **AVIF**: Newest format, smaller than WebP
 - **JPG**: Best for photos
 - **PNG**: Best for graphics with transparency
 
 ### Batch Processing
+
 ```bash
 # Process multiple files
 for file in *.jpg; do
@@ -1254,7 +1597,9 @@ done
 ```
 
 ### Chaining Commands
+
 Use dry-run to test, then execute:
+
 ```bash
 # Test first
 mediaproc image resize photo.jpg -w 800 --dry-run
@@ -1274,6 +1619,7 @@ mediaproc image resize photo.jpg -w 800
 ## 📝 Examples
 
 ### Web Optimization Workflow
+
 ```bash
 # 1. Resize for web
 mediaproc image resize photo.jpg -w 1920 -h 1080
@@ -1286,6 +1632,7 @@ mediaproc image convert photo-1920x1080-optimized.jpg -f webp
 ```
 
 ### Photo Enhancement Workflow
+
 ```bash
 # 1. Normalize contrast
 mediaproc image normalize photo.jpg
@@ -1298,6 +1645,7 @@ mediaproc image sharpen photo-normalized-modulated.jpg -s 1.5
 ```
 
 ### Thumbnail Generation
+
 ```bash
 # Generate multiple sizes
 mediaproc image thumbnail photo.jpg -s 64 -o thumb-64.jpg
@@ -1314,11 +1662,13 @@ mediaproc image thumbnail photo.jpg -s 300 -o thumb-300.jpg
 Process multiple images in a directory with any operation.
 
 **Usage:**
+
 ```bash
 mediaproc image batch <directory> --operation <operation> [options]
 ```
 
 **Options:**
+
 - `-op, --operation <operation>` - Operation to apply: resize, convert, optimize, grayscale, etc. (required)
 - `-o, --output <directory>` - Output directory (default: ./output)
 - `-r, --recursive` - Process subdirectories
@@ -1328,6 +1678,7 @@ mediaproc image batch <directory> --operation <operation> [options]
 - `-q, --quality <quality>` - Quality setting
 
 **Examples:**
+
 ```bash
 # Resize all images
 mediaproc image batch ./photos --operation resize --width 1920
@@ -1351,17 +1702,20 @@ mediaproc image batch ./gallery -op thumbnail --width 200 --height 200
 Automatically crop to target dimensions while preserving important content.
 
 **Usage:**
+
 ```bash
 mediaproc image smart-crop <input> -w <width> -h <height> [options]
 ```
 
 **Options:**
+
 - `-w, --width <pixels>` - Target width (required)
 - `-h, --height <pixels>` - Target height (required)
 - `-s, --strategy <type>` - Strategy: entropy (edges/details) or attention (center-weighted) (default: entropy)
 - `-o, --output <path>` - Output file path
 
 **Examples:**
+
 ```bash
 # Social media banner
 mediaproc image smart-crop photo.jpg -w 1200 -h 630
@@ -1374,6 +1728,7 @@ mediaproc image smart-crop product.png -w 600 -h 600 -o thumbnail.png
 ```
 
 **Common Dimensions:**
+
 - `1200x630` - Facebook/LinkedIn posts
 - `1024x512` - Twitter cards
 - `1080x1080` - Instagram square
@@ -1386,15 +1741,18 @@ mediaproc image smart-crop product.png -w 600 -h 600 -o thumbnail.png
 Apply pixelate/mosaic effect for artistic or privacy purposes.
 
 **Usage:**
+
 ```bash
 mediaproc image pixelate <input> [options]
 ```
 
 **Options:**
+
 - `-p, --pixels <size>` - Pixel size 2-50 (default: 10) - larger = more pixelated
 - `-o, --output <path>` - Output file path
 
 **Examples:**
+
 ```bash
 # Default pixelation
 mediaproc image pixelate photo.jpg
@@ -1407,6 +1765,7 @@ mediaproc image pixelate game.jpg --pixels 8 -o retro.jpg
 ```
 
 **Use Cases:**
+
 - Retro gaming aesthetics (8-12 pixel size)
 - Privacy protection (15-25 pixel size)
 - Artistic effects
@@ -1419,15 +1778,18 @@ mediaproc image pixelate game.jpg --pixels 8 -o retro.jpg
 Extract and display dominant colors from images.
 
 **Usage:**
+
 ```bash
 mediaproc image palette <input> [options]
 ```
 
 **Options:**
+
 - `-c, --colors <count>` - Number of colors 1-10 (default: 5)
 - `-v, --verbose` - Show hex codes and RGB values
 
 **Examples:**
+
 ```bash
 # Extract 5 dominant colors
 mediaproc image palette photo.jpg
@@ -1440,6 +1802,7 @@ mediaproc image palette artwork.jpg --colors 10
 ```
 
 **Output Includes:**
+
 - Dominant colors ranked by prevalence
 - RGB and hex values
 - Color temperature (warm/cool)
@@ -1447,6 +1810,7 @@ mediaproc image palette artwork.jpg --colors 10
 - Saturation levels
 
 **Use Cases:**
+
 - Design inspiration
 - Brand color extraction
 - Theme generation
@@ -1459,11 +1823,13 @@ mediaproc image palette artwork.jpg --colors 10
 Automatically crop to target dimensions while preserving important content using edge detection.
 
 **Usage:**
+
 ```bash
 mediaproc image smart-crop <input> -w <width> -h <height> [options]
 ```
 
 **Options:**
+
 - `-w, --width <pixels>` - Target width (required)
 - `-h, --height <pixels>` - Target height (required)
 - `-s, --strategy <type>` - Strategy: entropy (edges/details) or attention (center-weighted) (default: entropy)
@@ -1472,6 +1838,7 @@ mediaproc image smart-crop <input> -w <width> -h <height> [options]
 - `-v, --verbose` - Show detailed output
 
 **Examples:**
+
 ```bash
 # Social media banner
 mediaproc image smart-crop photo.jpg -w 1200 -h 630
@@ -1484,12 +1851,14 @@ mediaproc image smart-crop product.png -w 600 -h 600
 ```
 
 **Strategies:**
+
 - **entropy** - Focus on edges and details (best for landscapes)
 - **attention** - Center-weighted (best for portraits)
 
 **Common Social Media Dimensions:**
+
 - **1200x630** - Facebook/LinkedIn posts
-- **1024x512** - Twitter cards  
+- **1024x512** - Twitter cards
 - **1080x1080** - Instagram square
 - **1080x1350** - Instagram portrait
 - **800x800** - General thumbnails
@@ -1501,17 +1870,20 @@ mediaproc image smart-crop product.png -w 600 -h 600
 Apply pixelate/mosaic effect for artistic or privacy purposes.
 
 **Usage:**
+
 ```bash
 mediaproc image pixelate <input> [options]
 ```
 
 **Options:**
+
 - `-p, --pixels <size>` - Pixel size 2-50 (default: 10) - larger = more pixelated
 - `-o, --output <path>` - Output file path
 - `--dry-run` - Preview without executing
 - `-v, --verbose` - Show detailed output
 
 **Examples:**
+
 ```bash
 # Default pixelation
 mediaproc image pixelate photo.jpg
@@ -1524,6 +1896,7 @@ mediaproc image pixelate game.jpg --pixels 8
 ```
 
 **Pixel Size Guide:**
+
 - **2-5** - Subtle texture
 - **8-12** - Retro gaming aesthetics
 - **15-25** - Privacy protection
@@ -1536,16 +1909,19 @@ mediaproc image pixelate game.jpg --pixels 8
 Extract and display dominant colors with detailed analysis.
 
 **Usage:**
+
 ```bash
 mediaproc image palette <input> [options]
 ```
 
 **Options:**
+
 - `-c, --colors <count>` - Number of colors 1-10 (default: 5)
 - `-v, --verbose` - Show hex codes and RGB values
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Extract 5 dominant colors
 mediaproc image palette photo.jpg
@@ -1558,6 +1934,7 @@ mediaproc image palette artwork.jpg --colors 10
 ```
 
 **Output Includes:**
+
 - Dominant colors ranked by prevalence
 - RGB and hex values
 - Color temperature (warm/cool)
@@ -1572,11 +1949,13 @@ mediaproc image palette artwork.jpg --colors 10
 Process multiple images in a directory with any supported operation.
 
 **Usage:**
+
 ```bash
 mediaproc image batch <directory> --operation <operation> [options]
 ```
 
 **Options:**
+
 - `-op, --operation <operation>` - Operation: resize, convert, optimize, grayscale, etc. (required)
 - `-o, --output <directory>` - Output directory (default: ./output)
 - `-r, --recursive` - Process subdirectories
@@ -1588,6 +1967,7 @@ mediaproc image batch <directory> --operation <operation> [options]
 - `-v, --verbose` - Show detailed output
 
 **Examples:**
+
 ```bash
 # Resize all images
 mediaproc image batch ./photos --operation resize --width 1920
@@ -1612,22 +1992,26 @@ resize, convert, optimize, grayscale, blur, sharpen, thumbnail, sepia, normalize
 Intelligently enhance images with automatic color, contrast, and sharpness adjustments.
 
 **Usage:**
+
 ```bash
 mediaproc image auto-enhance <input> [options]
 ```
 
 **Options:**
+
 - `-l, --level <level>` - Enhancement level: low, medium, high (default: medium)
 - `-o, --output <path>` - Output file path
 - `--dry-run` - Preview without executing
 - `-v, --verbose` - Show detailed output
 
 **Enhancement Levels:**
+
 - **low** - Normalize + Light sharpen (subtle, ~10% improvement)
 - **medium** - Normalize + Color boost + Sharpen (balanced, ~30% improvement)
 - **high** - Normalize + CLAHE + Strong color boost + Heavy sharpen (aggressive, ~50% improvement)
 
 **Examples:**
+
 ```bash
 # Default enhancement
 mediaproc image auto-enhance photo.jpg
@@ -1640,6 +2024,7 @@ mediaproc image auto-enhance good-photo.jpg -l low
 ```
 
 **What Gets Enhanced:**
+
 - ✅ Color normalization and balance
 - ✅ Contrast enhancement (CLAHE for high level)
 - ✅ Sharpness and clarity
@@ -1648,6 +2033,7 @@ mediaproc image auto-enhance good-photo.jpg -l low
 - ✅ Detail preservation
 
 **Best For:**
+
 - Quick photo fixes
 - Batch photo processing
 - Underexposed images
@@ -1661,20 +2047,24 @@ mediaproc image auto-enhance good-photo.jpg -l low
 Intelligently enhance images with one command.
 
 **Usage:**
+
 ```bash
 mediaproc image auto-enhance <input> [options]
 ```
 
 **Options:**
+
 - `-l, --level <level>` - Enhancement level: low, medium, high (default: medium)
 - `-o, --output <path>` - Output file path
 
 **Enhancement Levels:**
+
 - **low** - Normalize + Light sharpen (subtle)
 - **medium** - Normalize + Color boost + Sharpen (recommended)
 - **high** - Normalize + CLAHE + Strong color boost + Heavy sharpen (aggressive)
 
 **Examples:**
+
 ```bash
 # Default enhancement
 mediaproc image auto-enhance photo.jpg
@@ -1687,6 +2077,7 @@ mediaproc image auto-enhance good-photo.jpg -l low
 ```
 
 **What Gets Enhanced:**
+
 - Color normalization
 - Sharpness
 - Contrast
@@ -1701,11 +2092,13 @@ mediaproc image auto-enhance good-photo.jpg -l low
 Combine multiple images into professional grid/collage layouts with full control over spacing, sizing, and background.
 
 **Usage:**
+
 ```bash
 mediaproc image grid <images...> [options]
 ```
 
 **Options:**
+
 - `-c, --columns <number>` - Number of columns (auto-calculated if not specified)
 - `-r, --rows <number>` - Number of rows (auto-calculated if not specified)
 - `-w, --width <pixels>` - Width of each cell (default: 300)
@@ -1717,6 +2110,7 @@ mediaproc image grid <images...> [options]
 - `-v, --verbose` - Show detailed output
 
 **Examples:**
+
 ```bash
 # Auto 2x2 grid
 mediaproc image grid img1.jpg img2.jpg img3.jpg img4.jpg
@@ -1735,18 +2129,21 @@ mediaproc image grid portfolio/*.jpg -r 2 -c 5 -w 300 -h 300 -g 15
 ```
 
 **Auto Layout:**
+
 - If no columns/rows specified: Auto-calculates square-ish grid
 - If only columns specified: Auto-calculates rows
 - If only rows specified: Auto-calculates columns
 - 4 images → 2x2, 6 images → 2x3, 9 images → 3x3
 
 **Cell Sizing:**
+
 - All images resized to cell dimensions
 - Uses "cover" fit mode (maintains aspect ratio, crops if needed)
 - Images centered in cells
 - Quality preserved during resize
 
 **Common Grid Sizes:**
+
 - **2x2** - Four image collage (1200x1200 typical)
 - **3x3** - Instagram multi-post (1200x1200 or 1800x1800)
 - **1x3** - Horizontal trio (900x300 typical)
@@ -1754,6 +2151,7 @@ mediaproc image grid portfolio/*.jpg -r 2 -c 5 -w 300 -h 300 -g 15
 - **4x4** - Photo album page (1600x1600)
 
 **Social Media Presets:**
+
 ```bash
 # Instagram post (3x3)
 grid *.jpg -c 3 -w 400 -h 400 -g 0 -o insta.jpg
@@ -1766,6 +2164,7 @@ grid *.jpg -c 4 -w 250 -h 350 -g 15
 ```
 
 **Use Cases:**
+
 - 📱 Instagram multi-image posts
 - 📸 Photo albums and galleries
 - 🎨 Portfolio presentations
@@ -1776,6 +2175,7 @@ grid *.jpg -c 4 -w 250 -h 350 -g 15
 - 📚 Magazine-style layouts
 
 **Background Colors:**
+
 - **white** - Clean, professional
 - **black** - Dramatic, artistic
 - **#f5f5f5** - Subtle gray
@@ -1783,6 +2183,7 @@ grid *.jpg -c 4 -w 250 -h 350 -g 15
 - **#hex or rgb()** - Custom brand colors
 
 **Tips:**
+
 - Use zero gap (-g 0) for seamless grids
 - Larger cells (400-500px) for high quality
 - Consistent cell sizes look more professional
@@ -1793,32 +2194,34 @@ grid *.jpg -c 4 -w 250 -h 350 -g 15
 
 ### 40. **composite** - Advanced Layer Blending
 
-*See command #20 above for full composite documentation*
+_See command #20 above for full composite documentation_
 
 ---
 
 ## 🎯 Command Quick Reference
 
-| Category | Commands | Count |
-|----------|----------|-------|
-| **Transform** | resize, crop, rotate, flip, trim, extend, thumbnail | 7 |
-| **Color** | modulate, gamma, tint, grayscale, negate, normalize | 6 |
-| **Effects** | blur, sharpen, median, sepia, vignette, pixelate | 6 |
-| **Advanced** | composite, extract, border, clahe, convolve, watermark | 6 |
-| **Smart/AI** | smart-crop, auto-enhance, palette, dominant-color, grid, batch | 6 |
-| **Utility** | convert, optimize, stats, split, stack, mirror, metadata | 7 |
-| **TOTAL** | | **40** |
+| Category      | Commands                                                       | Count  |
+| ------------- | -------------------------------------------------------------- | ------ |
+| **Transform** | resize, crop, rotate, flip, trim, extend, thumbnail            | 7      |
+| **Color**     | modulate, gamma, tint, grayscale, negate, normalize            | 6      |
+| **Effects**   | blur, sharpen, median, sepia, vignette, pixelate               | 6      |
+| **Advanced**  | composite, extract, border, clahe, convolve, watermark         | 6      |
+| **Smart/AI**  | smart-crop, auto-enhance, palette, dominant-color, grid, batch | 6      |
+| **Utility**   | convert, optimize, stats, split, stack, mirror, metadata       | 7      |
+| **TOTAL**     |                                                                | **40** |
 
 ---
 
 Combine multiple images into a grid/collage layout with customizable spacing and background.
 
 **Usage:**
+
 ```bash
 mediaproc image grid <images...> [options]
 ```
 
 **Options:**
+
 - `-c, --columns <number>` - Number of columns (auto-calculated if not specified)
 - `-r, --rows <number>` - Number of rows (auto-calculated if not specified)
 - `-w, --width <pixels>` - Width of each cell (default: 300)
@@ -1828,6 +2231,7 @@ mediaproc image grid <images...> [options]
 - `-o, --output <path>` - Output file path (default: grid.png)
 
 **Examples:**
+
 ```bash
 # Create 2x2 grid
 mediaproc image grid img1.jpg img2.jpg img3.jpg img4.jpg
@@ -1846,17 +2250,20 @@ mediaproc image grid *.png -c 3 -g 20 -b black
 Divide large images into smaller tiles, perfect for Instagram carousels or large format printing.
 
 **Usage:**
+
 ```bash
 mediaproc image split <input> [options]
 ```
 
 **Options:**
+
 - `-t, --tiles <pattern>` - Grid pattern (e.g., "3x3", "1x10")
 - `-r, --rows <number>` - Number of rows
 - `-c, --columns <number>` - Number of columns
 - `-o, --output <dir>` - Output directory (default: ./tiles)
 
 **Examples:**
+
 ```bash
 # Split into 3x3 grid
 mediaproc image split photo.jpg --tiles 3x3
@@ -1872,11 +2279,13 @@ mediaproc image split before-after.jpg --tiles "1x2"
 ```
 
 **Tile Naming:**
+
 - Output files named: `tile_row_col.ext` (e.g., `tile_0_0.jpg`, `tile_0_1.jpg`)
 - Zero-indexed coordinates
 - Preserves original format
 
 **Common Patterns:**
+
 - **1x10** - Instagram carousel (panorama)
 - **2x2** - Four-way comparison
 - **3x3** - Nine-tile puzzle
@@ -1884,6 +2293,7 @@ mediaproc image split before-after.jpg --tiles "1x2"
 - **1x2** - Before/after split
 
 **Use Cases:**
+
 - Instagram carousel posts
 - Large format printing on small printers
 - Image puzzles
@@ -1897,11 +2307,13 @@ mediaproc image split before-after.jpg --tiles "1x2"
 View, export, or remove image metadata including EXIF, IPTC, and XMP data.
 
 **Usage:**
+
 ```bash
 mediaproc image metadata <input> [options]
 ```
 
 **Options:**
+
 - `--remove` - Remove all metadata (create clean copy)
 - `--export <path>` - Export metadata to JSON file
 - `-o, --output <path>` - Output file path (when removing metadata)
@@ -1909,6 +2321,7 @@ mediaproc image metadata <input> [options]
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # View basic metadata
 mediaproc image metadata photo.jpg
@@ -1927,6 +2340,7 @@ mediaproc image metadata photo.jpg --remove -o clean.jpg
 ```
 
 **Metadata Types:**
+
 - **EXIF** - Camera settings, date, GPS location, device info
 - **IPTC** - Copyright, caption, keywords, author
 - **XMP** - Extended metadata, Adobe properties
@@ -1934,6 +2348,7 @@ mediaproc image metadata photo.jpg --remove -o clean.jpg
 - **Orientation** - Image rotation data
 
 **Information Displayed:**
+
 - File size and modified date
 - Image dimensions and format
 - Color space and channels
@@ -1943,6 +2358,7 @@ mediaproc image metadata photo.jpg --remove -o clean.jpg
 - Copyright and attribution
 
 **Why Remove Metadata:**
+
 - 🔒 **Privacy** - Remove GPS location data
 - 📉 **File Size** - Metadata can add 10-50KB
 - 🛡️ **Security** - Remove camera/device info
@@ -1950,6 +2366,7 @@ mediaproc image metadata photo.jpg --remove -o clean.jpg
 - 🤝 **Clean Sharing** - Remove personal data
 
 **File Size Impact:**
+
 - Metadata typically: 10-50KB
 - GPS data: ~500 bytes
 - Thumbnails in EXIF: 5-30KB
@@ -1962,11 +2379,13 @@ mediaproc image metadata photo.jpg --remove -o clean.jpg
 Stack multiple images horizontally or vertically with alignment and spacing control.
 
 **Usage:**
+
 ```bash
 mediaproc image stack <images...> [options]
 ```
 
 **Options:**
+
 - `-d, --direction <direction>` - Stack direction: horizontal, vertical (default: horizontal)
 - `-a, --align <alignment>` - Alignment: start, center, end (default: center)
 - `-g, --gap <pixels>` - Gap between images in pixels (default: 0)
@@ -1976,6 +2395,7 @@ mediaproc image stack <images...> [options]
 - `-v, --verbose` - Show detailed output
 
 **Examples:**
+
 ```bash
 # Horizontal before/after comparison
 mediaproc image stack before.jpg after.jpg
@@ -1994,6 +2414,7 @@ mediaproc image stack story*.jpg -d vertical -g 10 -b black
 ```
 
 **Direction & Alignment:**
+
 - **horizontal + start** - Images aligned to top
 - **horizontal + center** - Images centered vertically (default)
 - **horizontal + end** - Images aligned to bottom
@@ -2002,6 +2423,7 @@ mediaproc image stack story*.jpg -d vertical -g 10 -b black
 - **vertical + end** - Images aligned to right
 
 **Use Cases:**
+
 - Before/after comparisons
 - Image sequences and timelines
 - Panorama creation
@@ -2012,6 +2434,7 @@ mediaproc image stack story*.jpg -d vertical -g 10 -b black
 - Story sequences
 
 **Tips:**
+
 - Use gaps (10-20px) for visual separation
 - Transparent background works best with PNG output
 - Horizontal for wide comparisons
@@ -2025,17 +2448,20 @@ mediaproc image stack story*.jpg -d vertical -g 10 -b black
 Create stunning mirror and kaleidoscope effects by reflecting images in various ways.
 
 **Usage:**
+
 ```bash
 mediaproc image mirror <input> [options]
 ```
 
 **Options:**
+
 - `-m, --mode <mode>` - Mirror mode: horizontal, vertical, both, quad (default: horizontal)
 - `-o, --output <path>` - Output file path (default: <input>-mirror-<mode>.ext)
 - `--dry-run` - Preview without executing
 - `-v, --verbose` - Show detailed output
 
 **Examples:**
+
 ```bash
 # Horizontal mirror (left-right symmetry)
 mediaproc image mirror photo.jpg
@@ -2051,23 +2477,22 @@ mediaproc image mirror photo.jpg --mode quad
 ```
 
 **Mirror Modes:**
+
 - **horizontal** - Mirror left to right (creates left-right symmetry)
   - Output: 2x original width
   - Perfect for face symmetry experiments
-  
 - **vertical** - Mirror top to bottom (creates top-bottom symmetry)
   - Output: 2x original height
   - Perfect for water reflections, sky mirrors
-  
 - **both** - Mirror on both axes (creates 4-way symmetry)
   - Output: 2x width × 2x height
   - Creates complete symmetry
-  
 - **quad** - Kaleidoscope effect (mirrors center quadrant)
   - Output: Original size with center mirrored 4 ways
   - Creates mandala-like patterns
 
 **Creative Uses:**
+
 - 🪞 Water reflections (vertical mode)
 - 👤 Symmetrical portraits
 - 🎨 Kaleidoscope art (quad mode)
@@ -2078,6 +2503,7 @@ mediaproc image mirror photo.jpg --mode quad
 - 🎭 Surreal art effects
 
 **Best Practices:**
+
 - Works best with asymmetric input images
 - Quad mode creates most dramatic effects
 - Combine with other effects for unique results
@@ -2090,17 +2516,20 @@ mediaproc image mirror photo.jpg --mode quad
 Quickly extract the most dominant colors from an image for instant palette generation.
 
 **Usage:**
+
 ```bash
 mediaproc image dominant-color <input> [options]
 ```
 
 **Options:**
+
 - `-c, --count <number>` - Number of dominant colors to extract (default: 5, max: 10)
 - `--export <path>` - Export color palette to JSON file
 - `-v, --verbose` - Show detailed RGB/HSL values
 - `--help` - Display help
 
 **Examples:**
+
 ```bash
 # Extract top 5 dominant colors
 mediaproc image dominant-color photo.jpg
@@ -2116,6 +2545,7 @@ mediaproc image dominant-color artwork.jpg -c 5 -v
 ```
 
 **Output Format:**
+
 - 🎨 **Visual Preview** - Colored blocks in terminal
 - 🔢 **Hex Codes** - #RRGGBB format
 - 📊 **Coverage Percentage** - How much of image uses each color
@@ -2123,12 +2553,14 @@ mediaproc image dominant-color artwork.jpg -c 5 -v
 - 🎨 **HSL Values** - (hue, saturation, lightness) with -v flag
 
 **Color Analysis:**
+
 - Colors sorted by dominance (most to least)
 - Percentage shows coverage in image
 - Bucketed to reduce near-identical colors
 - Automatically filters similar shades
 
 **Use Cases:**
+
 - 🎨 Generate color palettes for design projects
 - 🏢 Brand color extraction from logos
 - 🌐 Website theme generation
@@ -2139,6 +2571,7 @@ mediaproc image dominant-color artwork.jpg -c 5 -v
 - 🏠 Interior design palettes
 
 **Export JSON Format:**
+
 ```json
 {
   "source": "photo.jpg",
@@ -2155,6 +2588,7 @@ mediaproc image dominant-color artwork.jpg -c 5 -v
 ```
 
 **Tips:**
+
 - Use fewer colors (2-3) for minimalist palettes
 - 5-7 colors ideal for comprehensive palettes
 - Export to JSON for use in design tools
@@ -2166,11 +2600,14 @@ mediaproc image dominant-color artwork.jpg -c 5 -v
 ### 39. **grid** - Create Image Collages
 
 # Instagram carousel (10 horizontal slices)
+
 mediaproc image split panorama.jpg -t "1x10"
 
 # Large poster into 4x4 tiles
+
 mediaproc image split poster.jpg -r 4 -c 4 -o ./poster-tiles
-```
+
+````
 
 ---
 
@@ -2181,15 +2618,17 @@ View, export to JSON, or remove EXIF/IPTC/XMP metadata from images.
 **Usage:**
 ```bash
 mediaproc image metadata <input> [options]
-```
+````
 
 **Options:**
+
 - `--remove` - Remove all metadata (create clean copy)
 - `--export <path>` - Export metadata to JSON file
 - `-o, --output <path>` - Output file (when removing metadata)
 - `-v, --verbose` - Show detailed metadata
 
 **Examples:**
+
 ```bash
 # View metadata
 mediaproc image metadata photo.jpg
@@ -2211,11 +2650,13 @@ mediaproc image metadata photo.jpg --remove -o clean.jpg
 Stack multiple images horizontally or vertically with customizable alignment and spacing.
 
 **Usage:**
+
 ```bash
 mediaproc image stack <images...> [options]
 ```
 
 **Options:**
+
 - `-d, --direction <direction>` - Stack direction: horizontal, vertical (default: horizontal)
 - `-a, --align <alignment>` - Alignment: start, center, end (default: center)
 - `-g, --gap <pixels>` - Gap between images (default: 0)
@@ -2223,6 +2664,7 @@ mediaproc image stack <images...> [options]
 - `-o, --output <path>` - Output file path
 
 **Examples:**
+
 ```bash
 # Horizontal before/after comparison
 mediaproc image stack before.jpg after.jpg
@@ -2241,15 +2683,18 @@ mediaproc image stack panorama*.jpg -d horizontal -o panorama.jpg
 Create mirror and kaleidoscope effects by reflecting images horizontally, vertically, or in quadrants.
 
 **Usage:**
+
 ```bash
 mediaproc image mirror <input> [options]
 ```
 
 **Options:**
+
 - `-m, --mode <mode>` - Mirror mode: horizontal, vertical, both, quad (default: horizontal)
 - `-o, --output <path>` - Output file path
 
 **Examples:**
+
 ```bash
 # Horizontal mirror (left-right symmetry)
 mediaproc image mirror photo.jpg
@@ -2268,16 +2713,19 @@ mediaproc image mirror photo.jpg --mode quad
 Quickly extract the most dominant colors from an image for palette generation.
 
 **Usage:**
+
 ```bash
 mediaproc image dominant-color <input> [options]
 ```
 
 **Options:**
+
 - `-c, --count <number>` - Number of colors to extract (default: 5, max: 10)
 - `--export <path>` - Export color palette to JSON file
 - `-v, --verbose` - Show detailed RGB/HSL values
 
 **Examples:**
+
 ```bash
 # Extract top 5 colors
 mediaproc image dominant-color photo.jpg
@@ -2294,6 +2742,7 @@ mediaproc image dominant-color photo.jpg --export palette.json
 ## � Real-World Workflows
 
 ### Workflow 1: Web Optimization Pipeline
+
 ```bash
 # 1. Resize for responsive web
 mediaproc image resize photo.jpg -w 1920 --fit inside -o web-large.jpg
@@ -2311,6 +2760,7 @@ mediaproc image thumbnail web-large.jpg -s 300 -o thumb.jpg
 ```
 
 ### Workflow 2: Social Media Prep
+
 ```bash
 # Instagram square post
 mediaproc image smart-crop photo.jpg -w 1080 -h 1080 -o instagram.jpg
@@ -2326,6 +2776,7 @@ mediaproc image metadata instagram.jpg --remove -o instagram-clean.jpg
 ```
 
 ### Workflow 3: Photo Enhancement Pipeline
+
 ```bash
 # 1. Auto-enhance
 mediaproc image auto-enhance photo.jpg --level medium
@@ -2343,6 +2794,7 @@ mediaproc image sharpen photo-auto-enhanced-modulated-vignette.jpg -s 1.2
 ```
 
 ### Workflow 4: Batch Product Photos
+
 ```bash
 # Process entire product directory
 mediaproc image batch ./products --operation resize --width 1200 --height 1200 -o ./web-products
@@ -2358,6 +2810,7 @@ mediaproc image batch ./web-products -op optimize -q 90
 ```
 
 ### Workflow 5: Instagram Carousel Creation
+
 ```bash
 # 1. Create panorama from multiple images
 mediaproc image stack img1.jpg img2.jpg img3.jpg -d horizontal -o panorama.jpg
@@ -2372,6 +2825,7 @@ mediaproc image batch ./carousel -op optimize -q 90
 ```
 
 ### Workflow 6: Portfolio Grid
+
 ```bash
 # Create 3x3 portfolio grid
 mediaproc image grid portfolio/*.jpg -c 3 -w 500 -h 500 -g 15 -b "#f5f5f5" -o portfolio-grid.jpg
@@ -2384,6 +2838,7 @@ mediaproc image optimize portfolio-grid-watermark.jpg -q 88 -o final-portfolio.j
 ```
 
 ### Workflow 7: Before/After Comparison
+
 ```bash
 # Stack horizontally
 mediaproc image stack before.jpg after.jpg -d horizontal -g 20 -b white -o comparison.jpg
@@ -2396,6 +2851,7 @@ mediaproc image optimize comparison-border.jpg -q 90
 ```
 
 ### Workflow 8: Vintage Photo Restoration
+
 ```bash
 # 1. Denoise
 mediaproc image median old-photo.jpg -s 5
@@ -2413,6 +2869,7 @@ mediaproc image vignette old-photo-median-normalized-sepia.jpg -i 30
 ```
 
 ### Workflow 9: Privacy-Safe Sharing
+
 ```bash
 # 1. Remove all metadata (GPS, camera info)
 mediaproc image metadata vacation.jpg --remove -o clean.jpg
@@ -2427,6 +2884,7 @@ mediaproc image optimize clean-1200w.jpg -q 80
 ```
 
 ### Workflow 10: Creative Kaleidoscope Art
+
 ```bash
 # 1. Extract vibrant colors
 mediaproc image dominant-color photo.jpg -c 5 --export colors.json
@@ -2444,6 +2902,7 @@ mediaproc image border photo-modulated-mirror-quad.jpg -w 40 -c black
 ```
 
 ### Batch Processing Tips
+
 ```bash
 # Process all JPGs in directory
 for file in *.jpg; do
@@ -2467,6 +2926,7 @@ done
 ## �🐛 Troubleshooting
 
 ### Command Not Found
+
 ```bash
 # Ensure CLI is installed
 npm list -g @mediaproc/cli
@@ -2476,6 +2936,7 @@ npx @mediaproc/cli image resize photo.jpg -w 800
 ```
 
 ### Invalid Image Format
+
 ```bash
 # Check supported formats
 mediaproc image convert --help
@@ -2484,6 +2945,7 @@ mediaproc image convert --help
 ```
 
 ### Out of Memory
+
 ```bash
 # For very large images, consider:
 # 1. Resizing first