@alisaitteke/photoshop-mcp 1.1.2 → 1.2.0

package/README.md

@@ -1,4 +1,7 @@
 # Photoshop MCP Server
+
+*v1.1+ — recipe workflows, fewer round-trips, snappier sessions.*
+
 > **Note:** This is an unofficial, community-maintained project and is not affiliated with or endorsed by Adobe Inc.
 
 [![npm version](https://img.shields.io/npm/v/@alisaitteke/photoshop-mcp.svg)](https://www.npmjs.com/package/@alisaitteke/photoshop-mcp)
@@ -6,13 +9,15 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
 [![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS-lightgrey.svg)]()
 
-A Model Context Protocol (MCP) server that enables AI assistants like Claude and Cursor to control Adobe Photoshop programmatically. This allows you to create designs, manipulate images, and automate Photoshop workflows through natural language commands while working in your IDE.
+A Model Context Protocol (MCP) server that enables AI assistants like Claude and Cursor to control Adobe Photoshop programmatically. This allows you to create designs, manipulate images, and automate Photoshop workflows through natural language commands while working in your IDE — or through the bundled **standalone web UI**, which supports both API keys and CLI subscription accounts (Claude Code / Gemini CLI).
 
 ## 🖥️ Standalone UI (no IDE required)
 
 Don't want to wire this into Claude Desktop or Cursor? The same package ships a
 fully local web UI that lets you chat with an AI model and drive Photoshop
-through this MCP server underneath.
+through this MCP server underneath. Connect with a provider API key **or**, for
+Anthropic and Google, reuse the OAuth session from **Claude Code** or **Gemini
+CLI** — no separate API key required.
 
 ![Standalone UI Screenshot](./images/frame_generic_light.png)
 
@@ -25,26 +30,54 @@ default browser opens the chat UI automatically.
 
 ### Supported providers
 
-Pick any of the following on first launch — bring your own API key:
+Pick any of the following on first launch — use an API key **or** your existing
+CLI subscription account (Anthropic and Google):
 
-| Provider | Models | Get a key |
-|---|---|---|
-| **Anthropic** | Claude Sonnet / Opus / Haiku | [console.anthropic.com](https://console.anthropic.com/settings/keys) |
-| **OpenAI** | GPT-5, GPT-4.1, o-series | [platform.openai.com](https://platform.openai.com/api-keys) |
-| **Google** | Gemini 2.5 Pro / Flash / Flash-Lite | [aistudio.google.com](https://aistudio.google.com/apikey) |
-| **OpenRouter** | 100+ models from any provider | [openrouter.ai](https://openrouter.ai/keys) |
+| Provider | Models | API key | CLI account |
+|---|---|---|---|
+| **Anthropic** | Claude Sonnet / Opus / Haiku | [console.anthropic.com](https://console.anthropic.com/settings/keys) | `npm i -g @anthropic-ai/claude-code` → `claude auth login` |
+| **OpenAI** | GPT-5, GPT-4.1, o-series | [platform.openai.com](https://platform.openai.com/api-keys) | — |
+| **Google** | Gemini 2.5 Pro / Flash / Flash-Lite | [aistudio.google.com](https://aistudio.google.com/apikey) | `npm i -g @google/gemini-cli` → `gemini auth login` |
+| **OpenRouter** | 100+ models from any provider | [openrouter.ai](https://openrouter.ai/keys) | — |
+
+### Authentication modes
+
+- **`api_key` (default)** — Vercel AI SDK + your provider API key. Usage is billed
+  per token at API rates; the UI shows estimated cost per chat.
+- **`cli_account`** — Uses your local Claude Code or Gemini CLI OAuth session.
+  No API key is stored; the UI probes `claude auth status` / `gemini` headless
+  to verify login. Usage counts against your **subscription quota**, not API
+  billing — the status bar shows "Included in subscription".
+
+You can switch auth method per provider in Settings without losing the other
+credential (e.g. keep an API key while trying CLI account, then switch back).
 
 ### What happens on first launch
 
-1. Pick a provider and paste your API key.
-2. The key is validated against the provider, then stored locally at
-   `~/.photoshop-mcp/data.db` (SQLite, `chmod 600`). It never leaves your
-   machine.
+1. Pick a provider and choose **API key** or **Uses your account**.
+2. Validate the key or check the CLI connection. Config is stored locally at
+   `~/.photoshop-mcp/data.db` (SQLite, `chmod 600`). API keys never leave your
+   machine; CLI mode inherits OAuth from `~/.claude/` or `~/.gemini/`.
 3. Type natural-language prompts. The UI streams the model's reply, runs
    Photoshop tool calls in real time, and renders each tool call as an
    inspectable card (input + result).
-4. Switch provider or model anytime from the model selector — chats, costs and
-   tool history are persisted across sessions.
+4. Switch provider, auth method, or model anytime from Settings / model selector
+   — chats, costs and tool history are persisted across sessions.
+
+### Switching auth method later
+
+Open **Settings** from the sidebar at any time:
+
+| Action | API key mode | CLI account mode |
+|---|---|---|
+| Set up | Paste key → **Save** | Install CLI → `auth login` → **Check connection** |
+| Switch away | Choose **API key** — stored key is kept | Choose **Uses your account** — key is not deleted |
+| Custom binary | — | Optional **CLI path** if `claude` / `gemini` is not on `PATH` |
+| Cost display | Per-token estimate in status bar | **Included in subscription** badge |
+
+Auth method is stored per provider in `~/.photoshop-mcp/data.db` (`authMethod`:
+`api_key` or `cli_account`). Existing configs without `authMethod` default to
+`api_key` and keep working unchanged.
 
 ### CLI flags
 
@@ -57,15 +90,152 @@ photoshop-mcp-ui [--port 5174] [--host 127.0.0.1] [--no-open]
 - The agent is restricted to Photoshop MCP tools only — built-in shell, file
   and web tools are disabled.
 - Tech stack: Vue 3 + Tailwind v4 + [shadcn-vue](https://www.shadcn-vue.com/)
-  on the frontend; [Hono](https://hono.dev/) + the [Vercel AI SDK](https://sdk.vercel.ai/)
-  on the backend. The agent loop talks to this same Photoshop MCP server over
-  STDIO — same code path as the IDE integration.
+  on the frontend; [Hono](https://hono.dev/) on the backend. API-key mode uses
+  the [Vercel AI SDK](https://sdk.vercel.ai/); CLI account mode uses the
+  [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/mcp) (Anthropic)
+  or Gemini CLI headless `stream-json` (Google). All paths talk to this same
+  Photoshop MCP server over STDIO.
+- **CLI account limitations:** Gemini headless may open a new session each turn
+  (history is prepended to the prompt). Anthropic CLI account consumes
+  subscription quota. OAuth login is macOS-first (`claude auth login` /
+  `gemini auth login` in Terminal).
 
 ---
 
+## AI/Prompt Layer for Photoshop
+
+On top of atomic `photoshop_*` tools, the server ships an opinionated AI/prompt
+layer that helps host LLMs (Cursor, Claude Desktop, etc.) translate vague user
+requests into reliable Photoshop actions:
+
+- **Server `instructions`** — workflow contract advertised on MCP `initialize`
+  (ping once, state-before-action, prefer recipes, error recovery). See
+  [`src/prompts/instructions.ts`](src/prompts/instructions.ts).
+- **MCP `prompts` primitive** — 16 pre-engineered templates (12 recipe + 4 guide:
+  `ps.enhance_portrait`, `ps.remove_background`, `ps.gradient_fade`, `ps.sky_blend`, …)
+  via `prompts/list` and `prompts/get`.
+- **Recipe tools** — 12 outcome-oriented `photoshop_recipe_*` tools (remove
+  background, enhance portrait, prepare for web, export social variants, color
+  grade, frequency separation, batch mockup, organize layers, gradient fade,
+  sky blend, dodge & burn, remove distraction). Each wraps steps in a single
+  Photoshop history state (one Undo reverts all). **80 tools total** (68 atomic
+  + 12 recipe).
+- **State & preview** — `photoshop_get_state` (cheap snapshot),
+  `photoshop_get_preview` (base64 JPEG for vision verification),
+  `photoshop_get_capabilities` (version-aware feature flags).
+- **Structured errors** — failures return JSON envelopes with `code` and
+  `suggested_next_tool` for self-correction.
+
+Full reference: [`docs/prompt-layer.md`](docs/prompt-layer.md).
+
+Verify parity: `npm run verify:photoshop-prompts`. Latest results:
+[`docs/development.md#integration-test-results`](docs/development.md#integration-test-results).
+
 ## Example Prompts
 
-Below are example prompts you can use with AI assistants (Claude, Cursor, etc.) when this MCP server is configured:
+Below are example prompts you can use with AI assistants (Claude, Cursor, etc.)
+when this MCP server is configured. Prefer **recipe tools** (`photoshop_recipe_*`)
+for multi-step outcomes — each recipe is a single undo step. Use atomic
+`photoshop_*` tools only for fine-grained edits no recipe covers.
+
+<details>
+<summary>🧠 State-aware session (recommended first step)</summary>
+
+```
+Ping Photoshop and read capabilities for my installed version.
+Get the current document state before changing anything.
+Open portrait.jpg, get a downscaled preview so you can verify the subject.
+After each major recipe, get another preview to confirm the result.
+```
+
+</details>
+
+<details>
+<summary>👤 Portrait retouch (recipe)</summary>
+
+```
+Enhance the portrait on the active layer at medium intensity with skin smoothing.
+Use the enhance-portrait recipe — I want frequency separation + auto-tone in one undoable step.
+If the active layer is text or a Smart Object, rasterize first or pick a raster layer.
+Show me a preview when done.
+```
+
+Equivalent MCP prompt template: `ps.enhance_portrait` with `{ intensity: "medium", skin_smoothing: "true" }`.
+
+</details>
+
+<details>
+<summary>✂️ Background removal (recipe)</summary>
+
+```
+Remove the background from the active portrait layer.
+Use Select Subject + a layer mask with a 2px feather. Keep the original pixels behind the mask.
+The subject must be on the active layer — not a flat color fill.
+```
+
+Equivalent MCP prompt template: `ps.remove_background` with `{ feather_px: "2", keep_shadow: "false" }`.
+
+</details>
+
+<details>
+<summary>🎨 Color grade (recipe)</summary>
+
+```
+Apply a warm film color grade to the open document as non-destructive adjustment layers.
+Use the apply-color-grade recipe with preset warm_film.
+Preview the result when finished.
+```
+
+</details>
+
+<details>
+<summary>🔬 Frequency separation setup (recipe)</summary>
+
+```
+Set up frequency separation on the active raster layer with a 6px blur radius.
+I will paint on the Low and High layers myself — do not apply extra smoothing.
+Tell me which layers to edit when the stack is ready.
+```
+
+Equivalent MCP prompt template: `ps.frequency_separation` with `{ radius_px: "6" }`.
+
+</details>
+
+<details>
+<summary>🌐 Prepare for web + social export (recipes)</summary>
+
+```
+Prepare the active document for web: sRGB, downscale, sharpen, export one optimized JPEG to ~/.photoshop-mcp/exports.
+Then export Instagram post and X post variants as separate JPEGs from the same document.
+List the output paths in a table.
+```
+
+Equivalent templates: `ps.prepare_for_web`, `ps.export_social_variants`.
+
+</details>
+
+<details>
+<summary>📦 Batch mockup replace (recipe)</summary>
+
+```
+I have a mockup PSD open with a Smart Object layer named "Screen".
+Replace it with every PNG/JPG in ~/assets/mockups/ and export one JPEG per asset.
+Do not place flat layers — swap the Smart Object so perspective is preserved.
+```
+
+Equivalent MCP prompt template: `ps.batch_mockup_replace`.
+
+</details>
+
+<details>
+<summary>🗂️ Organize layers (recipe)</summary>
+
+```
+Organize the layer stack: rename by kind, auto-group related layers, preserve originals.
+Run the organize-layers recipe, then list layers so I can review the new structure.
+```
+
+</details>
 
 <details>
 <summary>🎨 Basic Design Creation</summary>
@@ -100,10 +270,9 @@ Save as adventure.jpg with quality 10.
 
 ```
 Open photo.jpg from my Desktop in Photoshop.
-Apply auto levels and auto contrast.
-Apply unsharp mask with amount 120%, radius 1.5, threshold 0.
-Increase saturation by 15.
-Crop to remove 100px from each edge.
+Get state, then run the enhance-portrait recipe at low intensity.
+If I only need quick tone fixes, apply auto levels, auto contrast, and unsharp mask (120%, 1.5, 0) on the active layer instead.
+Adjust hue +15 and saturation +15, or use prepare-for-web when I'm ready to export.
 Save as enhanced-photo.jpg with quality 12.
 ```
 
@@ -241,28 +410,40 @@ Redo 1 step to bring back one operation.
 ```
 
 </details>
----
-> **🎨 50+ Tools** | **🖥️ Cross-Platform** | **📦 NPX Ready** | **🔧 ExtendScript API** | **⏮️ Undo/Redo**
+
+<details>
+<summary>🔁 Error recovery (structured envelopes)</summary>
+
+```
+If a recipe returns version_unsupported or generative_unavailable, call get_capabilities and tell me which Photoshop feature is missing.
+If a tool fails with suggested_next_tool, follow that hint (e.g. rasterize_layer before a raster-only recipe).
+Never guess — read get_state after a failure and propose the next single step.
+```
+
+</details>
 
 ## Features
 
-- ✅ **Works on both Windows and macOS**
-- ✅ **Supports Photoshop 2012-2025+**
-- ✅ **ExtendScript API**: Universal compatibility via AppleScript/COM automation
-- ✅ **Auto-Detection**: Automatically finds Photoshop installation on your system
-- ✅ **50+ Tools**: Comprehensive Photoshop automation
-- ✅ **Document Management**: Create, open, save, close, crop documents
-- ✅ **Layer Operations**: Create, delete, duplicate, merge, transform layers
-- ✅ **Layer Properties**: Opacity, blend modes, visibility, locking
-- ✅ **Text Formatting**: Font, size, color, alignment controls
-- ✅ **Image Placement**: Place images, open files, fit to document
-- ✅ **Filters**: Gaussian Blur, Sharpen, Noise, Motion Blur
-- ✅ **Color Adjustments**: Brightness/Contrast, Hue/Saturation, Auto Levels/Contrast
-- ✅ **Selections & Masks**: Rectangular selections, layer masks
-- ✅ **History Control**: Undo/Redo operations, view history states
-- ✅ **Actions**: Play recorded actions, execute custom scripts
-- ✅ **Auto-Rasterize**: Automatically converts layers when needed for filters
-- ✅ **Context Tracking**: Returns document/layer state after each operation for AI context awareness
+- **Standalone web UI** — local chat interface (`photoshop-mcp-ui`); API key or CLI
+  subscription auth per provider (Anthropic, Google)
+- **Works on both Windows and macOS**
+- **Supports Photoshop 2012-2025+**
+- **ExtendScript API**: Universal compatibility via AppleScript/COM automation
+- **Auto-Detection**: Automatically finds Photoshop installation on your system
+- **78 Tools**: 66 atomic `photoshop_*` + 12 recipe `photoshop_recipe_*`
+- **AI/Prompt Layer**: 16 MCP prompt templates (12 recipe + 4 guide), server instructions, state/preview/capabilities tools
+- **Document Management**: Create, open, save, close, crop documents
+- **Layer Operations**: Create, delete, duplicate, merge, transform layers
+- **Layer Properties**: Opacity, blend modes, visibility, locking
+- **Text Formatting**: Font, size, color, alignment controls
+- **Image Placement**: Place images, open files, fit to document
+- **Filters**: Gaussian Blur, Sharpen, Noise, Motion Blur
+- **Color Adjustments**: Brightness/Contrast, Hue/Saturation, Curves, Auto Levels/Contrast
+- **Selections & Masks**: Rectangular selections, select subject, content-aware fill, gradient mask, layer masks
+- **History Control**: Undo/Redo operations, view history states
+- **Actions**: Play recorded actions, execute custom scripts
+- **Auto-Rasterize**: Automatically converts layers when needed for filters
+- **Context Tracking**: Returns document/layer state after each operation for AI context awareness
 
 ## Installation
 
@@ -274,14 +455,7 @@ No installation required! Just configure your MCP client:
 npx @alisaitteke/photoshop-mcp
 ```
 
-### From Source
-
-```bash
-git clone https://github.com/alisaitteke/photoshop-mcp.git
-cd photoshop-mcp
-npm install
-npm run build
-```
+To hack on the repo locally, see [From Source](docs/development.md#from-source) in the development guide.
 
 ## Configuration
 
@@ -328,832 +502,9 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
 
 ## Available Tools
 
-### Connection & Info
-
-#### `photoshop_ping`
-Test connection to Photoshop.
-
-```javascript
-// Example: Check if Photoshop is accessible
-photoshop_ping()
-```
-
-#### `photoshop_get_version`
-Get Photoshop version information.
-
-```javascript
-// Example: Get version details
-photoshop_get_version()
-```
-
-### Document Management
-
-#### `photoshop_create_document`
-Create a new Photoshop document.
-
-**Parameters:**
-- `width` (number, required): Document width in pixels
-- `height` (number, required): Document height in pixels
-- `resolution` (number, optional): DPI resolution (default: 72)
-- `colorMode` (string, optional): Color mode - RGB, CMYK, or Grayscale (default: RGB)
-
-```javascript
-// Example: Create a 1920x1080 RGB document
-photoshop_create_document({
-  width: 1920,
-  height: 1080,
-  resolution: 72,
-  colorMode: "RGB"
-})
-```
-
-#### `photoshop_get_document_info`
-Get information about the active document.
-
-```javascript
-// Example: Get current document details
-photoshop_get_document_info()
-```
-
-#### `photoshop_save_document`
-Save the active document.
-
-**Parameters:**
-- `path` (string, required): Full path where to save
-- `format` (string, optional): PSD, JPEG, or PNG (default: PSD)
-- `quality` (number, optional): JPEG quality 1-12 (default: 8)
-
-```javascript
-// Example: Save as JPEG
-photoshop_save_document({
-  path: "/Users/username/Desktop/output.jpg",
-  format: "JPEG",
-  quality: 10
-})
-```
-
-#### `photoshop_close_document`
-Close the active document.
-
-**Parameters:**
-- `save` (boolean, optional): Save before closing (default: false)
-
-```javascript
-// Example: Close without saving
-photoshop_close_document({ save: false })
-```
-
-### Layer Operations
-
-#### `photoshop_create_layer`
-Create a new layer.
-
-**Parameters:**
-- `name` (string, optional): Layer name
-
-```javascript
-// Example: Create a named layer
-photoshop_create_layer({ name: "Background" })
-```
-
-#### `photoshop_delete_layer`
-Delete the active layer.
-
-```javascript
-// Example: Delete current layer
-photoshop_delete_layer()
-```
-
-#### `photoshop_create_text_layer`
-Create a text layer.
-
-**Parameters:**
-- `text` (string, required): Text content
-- `x` (number, optional): X position in pixels (default: 100)
-- `y` (number, optional): Y position in pixels (default: 100)
-- `fontSize` (number, optional): Font size in points (default: 24)
-
-```javascript
-// Example: Create a text layer
-photoshop_create_text_layer({
-  text: "Hello World",
-  x: 200,
-  y: 150,
-  fontSize: 48
-})
-```
-
-#### `photoshop_fill_layer`
-Fill the active layer with a solid color.
-
-**Parameters:**
-- `red` (number, required): Red component (0-255)
-- `green` (number, required): Green component (0-255)
-- `blue` (number, required): Blue component (0-255)
-
-```javascript
-// Example: Fill with blue
-photoshop_fill_layer({
-  red: 0,
-  green: 100,
-  blue: 255
-})
-```
-
-#### `photoshop_get_layers`
-Get list of all layers in the active document.
-
-```javascript
-// Example: List all layers
-photoshop_get_layers()
-```
-
-#### `photoshop_set_layer_opacity`
-Set the opacity of the active layer.
-
-**Parameters:**
-- `opacity` (number, required): Opacity value (0-100)
-
-```javascript
-// Example: Set opacity to 75%
-photoshop_set_layer_opacity({ opacity: 75 })
-```
-
-#### `photoshop_set_layer_blend_mode`
-Set the blend mode of the active layer.
-
-**Parameters:**
-- `blendMode` (string, required): Blend mode (NORMAL, MULTIPLY, SCREEN, OVERLAY, etc.)
-
-```javascript
-// Example: Set blend mode to multiply
-photoshop_set_layer_blend_mode({ blendMode: "MULTIPLY" })
-```
-
-Available blend modes: NORMAL, DISSOLVE, DARKEN, MULTIPLY, COLORBURN, LINEARBURN, DARKERCOLOR, LIGHTEN, SCREEN, COLORDODGE, LINEARDODGE, LIGHTERCOLOR, OVERLAY, SOFTLIGHT, HARDLIGHT, VIVIDLIGHT, LINEARLIGHT, PINLIGHT, HARDMIX, DIFFERENCE, EXCLUSION, SUBTRACT, DIVIDE, HUE, SATURATION, COLOR, LUMINOSITY
-
-#### `photoshop_set_layer_visibility`
-Show or hide the active layer.
-
-**Parameters:**
-- `visible` (boolean, required): Visibility state
-
-```javascript
-// Example: Hide layer
-photoshop_set_layer_visibility({ visible: false })
-```
-
-#### `photoshop_set_layer_locked`
-Lock or unlock the active layer.
-
-**Parameters:**
-- `locked` (boolean, required): Lock state
-
-```javascript
-// Example: Lock layer
-photoshop_set_layer_locked({ locked: true })
-```
-
-#### `photoshop_rename_layer`
-Rename the active layer.
-
-**Parameters:**
-- `name` (string, required): New layer name
+Full reference for all atomic `photoshop_*` tools (parameters, examples, and usage):
+[`docs/available-tools.md`](docs/available-tools.md).
 
-```javascript
-// Example: Rename layer
-photoshop_rename_layer({ name: "Hero Image" })
-```
-
-#### `photoshop_duplicate_layer`
-Duplicate the active layer.
-
-**Parameters:**
-- `newName` (string, optional): Name for duplicated layer
-
-```javascript
-// Example: Duplicate layer with new name
-photoshop_duplicate_layer({ newName: "Background Copy" })
-```
-
-#### `photoshop_merge_visible_layers`
-Merge all visible layers into one.
-
-```javascript
-// Example: Merge visible layers
-photoshop_merge_visible_layers()
-```
-
-#### `photoshop_flatten_image`
-Flatten all layers into a single background layer.
-
-```javascript
-// Example: Flatten image
-photoshop_flatten_image()
-```
-
-#### `photoshop_rasterize_layer`
-Rasterize the active layer (convert text/smart object to normal layer).
-
-```javascript
-// Example: Rasterize layer
-photoshop_rasterize_layer()
-```
-
-### Layer Ordering
-
-#### `photoshop_move_layer_to_position`
-Move the active layer relative to another layer.
-
-**Parameters:**
-- `targetLayerName` (string, required): Name of the reference layer
-- `position` (string, required): ABOVE, BELOW, TOP, or BOTTOM
-
-```javascript
-// Example: Move layer above "Background"
-photoshop_move_layer_to_position({
-  targetLayerName: "Background",
-  position: "ABOVE"
-})
-```
-
-#### `photoshop_move_layer_to_top`
-Move the active layer to the top of the layer stack.
-
-```javascript
-// Example: Move to top
-photoshop_move_layer_to_top()
-```
-
-#### `photoshop_move_layer_to_bottom`
-Move the active layer to the bottom of the layer stack.
-
-```javascript
-// Example: Move to bottom
-photoshop_move_layer_to_bottom()
-```
-
-#### `photoshop_move_layer_up`
-Move the active layer up one position.
-
-```javascript
-// Example: Move up
-photoshop_move_layer_up()
-```
-
-#### `photoshop_move_layer_down`
-Move the active layer down one position.
-
-```javascript
-// Example: Move down
-photoshop_move_layer_down()
-```
-
-### Layer Transformations
-
-#### `photoshop_fit_layer_to_document`
-Scale the active layer to fit the document canvas while maintaining aspect ratio.
-
-**Parameters:**
-- `fillDocument` (boolean, optional): If true, fills entire canvas (may crop). If false, fits within canvas (may have margins). Default: false
-
-```javascript
-// Example: Fit layer within canvas
-photoshop_fit_layer_to_document({ fillDocument: false })
-
-// Example: Fill entire canvas (cropping if needed)
-photoshop_fit_layer_to_document({ fillDocument: true })
-```
-
-#### `photoshop_scale_layer`
-Scale the active layer by a percentage.
-
-**Parameters:**
-- `scalePercent` (number, required): Scale percentage (e.g., 50 for 50%, 200 for 200%)
-- `centerAnchor` (boolean, optional): Scale from center (true) or top-left (false). Default: true
-
-```javascript
-// Example: Scale to 150%
-photoshop_scale_layer({
-  scalePercent: 150,
-  centerAnchor: true
-})
-```
-
-#### `photoshop_move_layer`
-Move the active layer by specified offset.
-
-**Parameters:**
-- `deltaX` (number, required): Horizontal offset in pixels
-- `deltaY` (number, required): Vertical offset in pixels
-
-```javascript
-// Example: Move layer 100px right and 50px down
-photoshop_move_layer({
-  deltaX: 100,
-  deltaY: 50
-})
-```
-
-#### `photoshop_rotate_layer`
-Rotate the active layer.
-
-**Parameters:**
-- `degrees` (number, required): Rotation angle in degrees (positive = clockwise)
-
-```javascript
-// Example: Rotate 45 degrees clockwise
-photoshop_rotate_layer({ degrees: 45 })
-```
-
-### Filters
-
-#### `photoshop_apply_gaussian_blur`
-Apply Gaussian Blur filter to the active layer.
-
-**Parameters:**
-- `radius` (number, required): Blur radius in pixels (0.1-250)
-
-```javascript
-// Example: Apply 10px blur
-photoshop_apply_gaussian_blur({ radius: 10 })
-```
-
-#### `photoshop_apply_sharpen`
-Apply Unsharp Mask (sharpen) filter.
-
-**Parameters:**
-- `amount` (number, required): Sharpening amount in percent (1-500)
-- `radius` (number, required): Radius in pixels (0.1-250)
-- `threshold` (number, optional): Threshold levels (0-255, default: 0)
-
-```javascript
-// Example: Sharpen image
-photoshop_apply_sharpen({
-  amount: 100,
-  radius: 1.5,
-  threshold: 0
-})
-```
-
-#### `photoshop_apply_noise`
-Apply Add Noise filter.
-
-**Parameters:**
-- `amount` (number, required): Noise amount in percent (0.1-400)
-- `distribution` (string, optional): UNIFORM or GAUSSIAN (default: UNIFORM)
-- `monochromatic` (boolean, optional): Monochromatic noise (default: false)
-
-```javascript
-// Example: Add noise
-photoshop_apply_noise({
-  amount: 10,
-  distribution: "GAUSSIAN",
-  monochromatic: false
-})
-```
-
-#### `photoshop_apply_motion_blur`
-Apply Motion Blur filter.
-
-**Parameters:**
-- `angle` (number, required): Blur angle in degrees (-360 to 360)
-- `radius` (number, required): Blur distance in pixels (1-999)
-
-```javascript
-// Example: Apply motion blur
-photoshop_apply_motion_blur({
-  angle: 45,
-  radius: 20
-})
-```
-
-### Color Adjustments
-
-#### `photoshop_adjust_brightness_contrast`
-Adjust brightness and contrast.
-
-**Parameters:**
-- `brightness` (number, required): Brightness adjustment (-100 to 100)
-- `contrast` (number, required): Contrast adjustment (-100 to 100)
-
-```javascript
-// Example: Increase brightness and contrast
-photoshop_adjust_brightness_contrast({
-  brightness: 20,
-  contrast: 15
-})
-```
-
-#### `photoshop_adjust_hue_saturation`
-Adjust hue, saturation, and lightness.
-
-**Parameters:**
-- `hue` (number, required): Hue shift (-180 to 180)
-- `saturation` (number, required): Saturation adjustment (-100 to 100)
-- `lightness` (number, required): Lightness adjustment (-100 to 100)
-
-```javascript
-// Example: Adjust colors
-photoshop_adjust_hue_saturation({
-  hue: 30,
-  saturation: 20,
-  lightness: 0
-})
-```
-
-#### `photoshop_auto_levels`
-Apply auto levels adjustment.
-
-```javascript
-// Example: Auto levels
-photoshop_auto_levels()
-```
-
-#### `photoshop_auto_contrast`
-Apply auto contrast adjustment.
-
-```javascript
-// Example: Auto contrast
-photoshop_auto_contrast()
-```
-
-#### `photoshop_desaturate`
-Desaturate the layer (convert to grayscale).
-
-```javascript
-// Example: Desaturate
-photoshop_desaturate()
-```
-
-#### `photoshop_invert`
-Invert colors of the layer.
-
-```javascript
-// Example: Invert colors
-photoshop_invert()
-```
-
-### Text Formatting
-
-#### `photoshop_set_text_font`
-Set font family and size for active text layer.
-
-**Parameters:**
-- `fontName` (string, required): Font family name
-- `fontSize` (number, optional): Font size in points
-
-```javascript
-// Example: Change font
-photoshop_set_text_font({
-  fontName: "Helvetica",
-  fontSize: 48
-})
-```
-
-#### `photoshop_set_text_color`
-Set color for active text layer.
-
-**Parameters:**
-- `red` (number, required): Red component (0-255)
-- `green` (number, required): Green component (0-255)
-- `blue` (number, required): Blue component (0-255)
-
-```javascript
-// Example: Set text to blue
-photoshop_set_text_color({
-  red: 0,
-  green: 100,
-  blue: 255
-})
-```
-
-#### `photoshop_set_text_alignment`
-Set text alignment.
-
-**Parameters:**
-- `alignment` (string, required): LEFT, CENTER, RIGHT, LEFTJUSTIFIED, CENTERJUSTIFIED, RIGHTJUSTIFIED, FULLYJUSTIFIED
-
-```javascript
-// Example: Center align text
-photoshop_set_text_alignment({ alignment: "CENTER" })
-```
-
-#### `photoshop_update_text_content`
-Update text content of active text layer.
-
-**Parameters:**
-- `text` (string, required): New text content
-
-```javascript
-// Example: Update text
-photoshop_update_text_content({ text: "New Text" })
-```
-
-### Selections & Masks
-
-#### `photoshop_select_rectangle`
-Create a rectangular selection.
-
-**Parameters:**
-- `left`, `top`, `right`, `bottom` (number, required): Selection bounds in pixels
-
-```javascript
-// Example: Select area
-photoshop_select_rectangle({
-  left: 100,
-  top: 100,
-  right: 500,
-  bottom: 400
-})
-```
-
-#### `photoshop_select_all`
-Select the entire document.
-
-```javascript
-// Example: Select all
-photoshop_select_all()
-```
-
-#### `photoshop_deselect`
-Clear all selections.
-
-```javascript
-// Example: Deselect
-photoshop_deselect()
-```
-
-#### `photoshop_invert_selection`
-Invert the current selection.
-
-```javascript
-// Example: Invert selection
-photoshop_invert_selection()
-```
-
-#### `photoshop_create_layer_mask`
-Create a layer mask from the current selection.
-
-```javascript
-// Example: Create mask
-photoshop_create_layer_mask()
-```
-
-#### `photoshop_delete_layer_mask`
-Delete the layer mask from active layer.
-
-```javascript
-// Example: Delete mask
-photoshop_delete_layer_mask()
-```
-
-#### `photoshop_apply_layer_mask`
-Apply (merge) the layer mask to the layer.
-
-```javascript
-// Example: Apply mask
-photoshop_apply_layer_mask()
-```
-
-### History & Undo/Redo
-
-#### `photoshop_undo`
-Undo the last operation(s) - equivalent to Ctrl/Cmd+Z.
-
-**Parameters:**
-- `steps` (number, optional): Number of steps to undo (default: 1)
-
-```javascript
-// Example: Undo last operation
-photoshop_undo()
-
-// Example: Undo last 3 operations
-photoshop_undo({ steps: 3 })
-```
-
-#### `photoshop_redo`
-Redo previously undone operation(s) - equivalent to Ctrl/Cmd+Shift+Z.
-
-**Parameters:**
-- `steps` (number, optional): Number of steps to redo (default: 1)
-
-```javascript
-// Example: Redo last undone operation
-photoshop_redo()
-
-// Example: Redo last 2 undone operations
-photoshop_redo({ steps: 2 })
-```
-
-#### `photoshop_get_history`
-Get the history states of the active document.
-
-```javascript
-// Example: View history
-photoshop_get_history()
-```
-
-### Actions & Automation
-
-#### `photoshop_play_action`
-Play a recorded action from the Actions palette.
-
-**Parameters:**
-- `actionName` (string, required): Action name
-- `actionSetName` (string, required): Action set name
-
-```javascript
-// Example: Play action
-photoshop_play_action({
-  actionName: "My Action",
-  actionSetName: "Default Actions"
-})
-```
-
-#### `photoshop_execute_script`
-Execute custom ExtendScript code (advanced).
-
-**Parameters:**
-- `code` (string, required): ExtendScript code
-
-```javascript
-// Example: Execute custom code
-photoshop_execute_script({
-  code: "app.beep();"
-})
-```
-
-### Image Manipulation
-
-#### `photoshop_resize_image`
-Resize the active image.
-
-**Parameters:**
-- `width` (number, required): New width in pixels
-- `height` (number, required): New height in pixels
-
-```javascript
-// Example: Resize to Instagram post size
-photoshop_resize_image({
-  width: 1080,
-  height: 1080
-})
-```
-
-#### `photoshop_crop_document`
-Crop the document to specified bounds.
-
-**Parameters:**
-- `left` (number, required): Left edge in pixels
-- `top` (number, required): Top edge in pixels
-- `right` (number, required): Right edge in pixels
-- `bottom` (number, required): Bottom edge in pixels
-
-```javascript
-// Example: Crop document
-photoshop_crop_document({
-  left: 100,
-  top: 100,
-  right: 1820,
-  bottom: 980
-})
-```
-
-#### `photoshop_place_image`
-Place an image file as a layer in the active document.
-
-**Parameters:**
-- `filePath` (string, required): Full path to the image file
-- `x` (number, optional): X position offset in pixels (default: 0)
-- `y` (number, optional): Y position offset in pixels (default: 0)
-
-```javascript
-// Example: Place an image at specific position
-photoshop_place_image({
-  filePath: "/Users/username/Pictures/photo.jpg",
-  x: 100,
-  y: 200
-})
-```
-
-#### `photoshop_open_image`
-Open an image file as a new document.
-
-**Parameters:**
-- `filePath` (string, required): Full path to the image file
-
-```javascript
-// Example: Open an image
-photoshop_open_image({
-  filePath: "/Users/username/Pictures/photo.jpg"
-})
-```
-
-
----
-
-## Usage Examples
-
-### Create a Simple Design
-
-```javascript
-// 1. Create a new document
-photoshop_create_document({
-  width: 800,
-  height: 600,
-  colorMode: "RGB"
-})
-
-// 2. Create a background layer
-photoshop_create_layer({ name: "Background" })
-
-// 3. Fill it with a color
-photoshop_fill_layer({
-  red: 240,
-  green: 240,
-  blue: 255
-})
-
-// 4. Add a text layer
-photoshop_create_text_layer({
-  text: "My Design",
-  x: 400,
-  y: 300,
-  fontSize: 64
-})
-
-// 5. Save the result
-photoshop_save_document({
-  path: "/Users/username/Desktop/design.psd",
-  format: "PSD"
-})
-```
-
-### Batch Process Images
-
-```javascript
-// 1. Open existing document (manual step)
-// 2. Resize image
-photoshop_resize_image({ width: 1920, height: 1080 })
-
-// 3. Save as JPEG
-photoshop_save_document({
-  path: "/Users/username/Desktop/resized.jpg",
-  format: "JPEG",
-  quality: 12
-})
-
-// 4. Close document
-photoshop_close_document({ save: false })
-```
-
-### Create Design with Stock Images (using Pexels MCP)
-
-This example shows how to combine Photoshop MCP with Pexels MCP:
-
-```javascript
-// 1. Search for images on Pexels (using Pexels MCP server)
-// Note: You need to have Pexels MCP server configured
-pexels_photos_search({
-  query: "nature landscape",
-  per_page: 5
-})
-
-// 2. Download the image you want (manually or via script)
-// 3. Create a new Photoshop document
-photoshop_create_document({
-  width: 1920,
-  height: 1080,
-  colorMode: "RGB"
-})
-
-// 4. Place the downloaded image
-photoshop_place_image({
-  filePath: "/Users/username/Downloads/pexels-photo.jpg",
-  x: 0,
-  y: 0
-})
-
-// 5. Fit the image to document (NEW!)
-photoshop_fit_layer_to_document({
-  fillDocument: true  // Fill entire canvas
-})
-
-// 6. Add text overlay
-photoshop_create_text_layer({
-  text: "Beautiful Nature",
-  x: 960,
-  y: 100,
-  fontSize: 72
-})
-
-// 7. Save the final design
-photoshop_save_document({
-  path: "/Users/username/Desktop/nature-design.psd",
-  format: "PSD"
-})
-```
 
 ## Context Tracking
 
@@ -1218,6 +569,9 @@ This context helps AI assistants remember what document and layer they're workin
 - Uses AppleScript/OSA for Photoshop communication
 - Spotlight-based auto-detection
 - Supports multiple Photoshop versions installed simultaneously
+- **CLI account auth** (standalone UI) is macOS-first: run `claude auth login` /
+  `gemini auth login` in Terminal; credentials live under `~/.claude/` and
+  `~/.gemini/`
 
 ## Supported Photoshop Versions
 
@@ -1227,123 +581,32 @@ This context helps AI assistants remember what document and layer they're workin
 
 ## Troubleshooting
 
-### "Photoshop not found"
-
-1. Make sure Photoshop is installed in the default location
-2. Or set `PHOTOSHOP_PATH` environment variable to custom installation path
-
-```json
-{
-  "env": {
-    "PHOTOSHOP_PATH": "C:\\Custom\\Path\\Adobe Photoshop 2025\\Photoshop.exe"
-  }
-}
-```
-
-### "Failed to connect to Photoshop"
-
-1. Ensure Photoshop is running (the server will try to launch it if not)
-2. Check that scripting is enabled in Photoshop preferences
-3. On Windows, verify COM automation is not blocked by security settings
-
-### "Script execution timeout"
+Common connection, scripting, and logging issues:
+[`docs/troubleshooting.md`](docs/troubleshooting.md).
 
-- Some operations may take longer on large documents
-- The default timeout is 30 seconds
-- For complex operations, consider breaking them into smaller steps
+### Standalone UI — CLI account auth
 
-### Debug Logging
-
-Enable detailed logging by setting `LOG_LEVEL=0`:
-
-```json
-{
-  "env": {
-    "LOG_LEVEL": "0"
-  }
-}
-```
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `cli_not_found` | Claude Code / Gemini CLI not installed | `npm i -g @anthropic-ai/claude-code` or `npm i -g @google/gemini-cli` |
+| `not_authenticated` | No OAuth session | Run `claude auth login` or `gemini auth login` in Terminal |
+| `claude` / `gemini` not on `PATH` | Custom install location | Settings → **CLI path** → **Check connection** |
+| Chat works in IDE but not UI (CLI mode) | OAuth tokens are CLI-only | Use **CLI account** in UI; API keys and CLI sessions are separate |
+| Gemini multi-turn feels forgetful | Headless CLI may start a fresh session each turn | Known limitation; history is prepended to the prompt (MVP) |
 
 ## Development
 
-### Build
-
-```bash
-npm run build
-```
-
-### Watch Mode
-
-```bash
-npm run dev
-```
-
-### Lint & Format
-
-```bash
-npm run lint
-npm run format
-```
-
-## Quick Start Examples
-
-### 💡 Common Use Cases
-
-| Task | Prompt Example |
-|------|----------------|
-| **Basic Design** | "Create 1920x1080 document, add blue background, center text 'Hello'" |
-| **Photo Edit** | "Open photo.jpg, apply auto levels, sharpen 100%, save as edited.jpg" |
-| **Stock Image** | "Place image.jpg, fit to fill canvas, add overlay text 'Summer 2026'" |
-| **Layer Effects** | "Set active layer blend mode to MULTIPLY, opacity 80%" |
-| **Filters** | "Apply 10px Gaussian blur to current layer" |
-| **Text Styling** | "Change text to Helvetica 64pt, color red, center aligned" |
-| **Batch Work** | "Resize to 1080x1080, auto contrast, save as square.jpg, close" |
-| **Masks** | "Select rectangle 100,100 to 500,500, create layer mask" |
-
----
+From-source setup, build, lint, integration tests (with latest results), and usage examples:
+[`docs/development.md`](docs/development.md).
 
 ## Architecture
 
-```
-photoshop-mcp/
-├── src/
-│   ├── core/              # MCP server core
-│   │   ├── server.ts      # Main MCP server
-│   │   ├── session.ts     # Session management
-│   │   └── tool-registry.ts  # Tool registration system
-│   ├── platform/          # Platform-specific detection & execution
-│   │   ├── detector.ts    # Main detector
-│   │   ├── connection.ts  # Connection manager
-│   │   ├── windows-detector.ts  # Windows registry detection
-│   │   ├── windows-executor.ts  # Windows COM automation
-│   │   ├── macos-detector.ts    # macOS Spotlight detection
-│   │   └── macos-executor.ts    # macOS AppleScript execution
-│   ├── api/              # Photoshop API abstractions
-│   │   ├── photoshop-api.ts    # API factory
-│   │   ├── batch-play.ts       # UXP batchPlay helpers (legacy)
-│   │   └── extendscript.ts     # ExtendScript snippets library
-│   ├── tools/            # MCP tool implementations (42+ tools)
-│   │   ├── document-tools.ts        # Document operations
-│   │   ├── layer-tools.ts           # Layer creation/deletion
-│   │   ├── layer-properties-tools.ts # Opacity, blend modes, etc.
-│   │   ├── layer-transform-tools.ts  # Scale, rotate, move
-│   │   ├── image-tools.ts           # Resize, crop
-│   │   ├── image-placement-tools.ts # Place/open images
-│   │   ├── filter-tools.ts          # Blur, sharpen, noise
-│   │   ├── adjustment-tools.ts      # Color adjustments
-│   │   ├── text-tools.ts            # Text formatting
-│   │   ├── selection-tools.ts       # Selections & masks
-│   │   └── action-tools.ts          # Actions & custom scripts
-│   └── utils/            # Utilities
-│       └── logger.ts     # Logging system (stderr-based)
-└── examples/             # Configuration examples
-    ├── cursor-config.json
-    └── claude-desktop-config.json
-```
+Repository layout and module map:
+[`docs/architecture.md`](docs/architecture.md).
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
 
 ## License