Verify Photoshop is installed and reachable on this machine.

Use when: once at session start if connection status is unknown. Do NOT use when: on every tool call — call once, then use photoshop_get_state.

Returns: connection success or failure message. Preconditions: none. Side effects: may trigger Photoshop detection.

Return the detected Photoshop version string.

Use when: user asks about compatibility or before version-gated features. Do NOT use when: you need feature flags — prefer photoshop_get_capabilities.

Returns: version string. Preconditions: none. Side effects: none.

Create a new empty Photoshop document with specified dimensions and color mode.

Use when: starting a design from scratch or no document is open. Do NOT use when: opening an existing file — use photoshop_open_image.

Returns: created document id and name. Preconditions: none. Side effects: creates a new document and makes it active.

Get information about the active Photoshop document

List every open Photoshop document with id, dimensions, and which tab is active (read-only).

Use when: multiple documents are open and you need document_id before switching tabs or closing a specific file. Do NOT use when: you only need the active document — use photoshop_get_document_info or photoshop_get_state.

Returns: JSON { ok, summary, details: { count, documents[], active_document_id, context } }. Preconditions: none (safe when zero documents open). Side effects: none.

Switch the active document tab by document_id (preferred), zero-based index, or name.

Use when: working across multiple open files and mutations must target a specific document. Do NOT use when: only one document is open — it is already active. Do NOT use document_name when duplicate names exist — use document_id from photoshop_list_documents.

Returns: JSON { ok, summary, details: { activated: { id, name }, context } }. Preconditions: target document must be open. Provide exactly one of document_id, index, or document_name. Side effects: changes active tab.

Save the active document to disk in PSD, JPEG, or PNG format.

Use when: user requests export/save with a specific path and format. Do NOT use when: web-optimized resize+sharpen pipeline is needed — use photoshop_recipe_prepare_for_web.

Returns: confirmation with saved path and format. Preconditions: active document; path required. Side effects: writes file to disk.

Close the active Photoshop document

Create a new empty layer above the active layer.

Use when: user needs a blank layer for painting, fills, or stacking content. Do NOT use when: adding text — use photoshop_create_text_layer.

Returns: created layer name and context. Preconditions: active document. Side effects: adds layer to history.

Delete the active layer

Create a text layer with content, position, font size, and optional font.

Use when: adding labels, titles, or typography to the design. Do NOT use when: editing existing text — use photoshop_update_text_content.

Returns: layer name, text, position, fontSize, font (when fontName set), context. Use photoshop_list_fonts to discover font names; photoshop_set_text_font to change font later. Preconditions: active document. Side effects: adds text layer.

Fill the active layer with a color

List all layers in the active document with kind, visibility, and opacity.

Use when: choosing a layer to edit, debugging structure, or after organize_layers. Do NOT use when: only session summary is needed — use photoshop_get_state (lighter).

Returns: layerCount, layers array, context. Preconditions: active document. Side effects: none.

Select the active layer by exact name, including layers inside groups.

Use when: a transform or property tool must target a named layer (photoshop_scale_layer, etc.). Do NOT use when: the layer is already active — check photoshop_get_state first.

Returns: selected, layerName, kind, bounds (best-effort), context. First depth-first name match wins when duplicate names exist in different groups. Preconditions: active document. Side effects: changes active layer.

Resize the active image to specified dimensions

Crop the document to specified bounds

Place an external image file as a new layer in the active document.

x/y are absolute canvas coordinates for the placed layer's top-left bound in pixels (0,0 = document top-left). They are NOT an offset from Photoshop's default centered Place.

Use when: compositing assets into an open document at a known position. Do NOT use when: opening a file as a new document — use photoshop_open_image.

Returns: placed layer name, bounds, and position.semantics = absolute_top_left. Preconditions: active document; file must exist. Side effects: adds a new layer.

Open an image file as a new Photoshop document.

Use when: user provides a file path to edit or no document is open yet. Do NOT use when: adding to an existing composite — use photoshop_place_image.

Returns: document id, name, width, height. Preconditions: file must exist on disk. Side effects: opens document as active.

Convert the active layer (or a named layer) to an embedded Smart Object.

Users often say: convert to smart object, make smart layer, embed layer.

Use when: non-destructive transforms/filters are needed on a raster or shape layer. Do NOT use when: the layer is already a Smart Object — returns success with already_smart_object. Do NOT use on background layers — unlock or duplicate first.

Returns: JSON { ok, summary, details: { layer_name, kind, already_smart_object? } }. Preconditions: active document; target layer must be selected or named. Side effects: one history step.

Replace the embedded contents of a Smart Object layer from an image file. Preserves transforms, warps, and Smart Filters on the layer.

Users often say: replace smart object, swap mockup screen, relink embedded file.

Use when: updating a mockup or template Smart Object with a new asset file. Do NOT use when: the target is not a Smart Object — convert first or use photoshop_place_image. Do NOT use for linked Smart Objects that need Relink to File — this replaces embedded contents.

Returns: JSON { ok, summary, details: { layer_name, file_path } }. Preconditions: Smart Object layer active or named; file_path must exist (absolute). Side effects: replaces embedded pixels.

Open a Smart Object for editing (double-click / Edit Contents). The embedded .psb becomes the active document until you save and close it.

Users often say: edit smart object, open embedded file, double-click smart layer.

Use when: modifying pixels inside an embedded Smart Object non-destructively. Do NOT use when: replacing the whole asset — use photoshop_replace_smart_object_contents.

Returns: JSON { ok, summary, details: { parent_document, embedded_document, layer_name } }. Preconditions: Smart Object layer active or named. Side effects: active document switches to the embedded .psb — save/close it to return to the parent document.

Create an independent Smart Object via Copy — unlinked duplicate with its own embedded contents.

Users often say: new smart object via copy, independent smart copy, duplicate smart object separately.

Use when: you need a second Smart Object that does not share embedded data with the original. Do NOT use when: you want linked instances — use photoshop_duplicate_layer (Layer via Copy).

Returns: JSON { ok, summary, details: { source_layer_name, new_layer_name, kind } }. Preconditions: Smart Object layer active or named. Side effects: adds a new Smart Object layer.

Scale the active layer to fit the document canvas while maintaining aspect ratio

Scale the active layer by a percentage

Move the active layer by specified offset

Rotate the active layer

Rasterize the active layer (convert text/smart object to normal layer)

Set the opacity of the active layer

Set the blend mode of the active layer.

COLOR is the Photoshop UI name (Colorize); it is mapped to ExtendScript BlendMode.COLORBLEND.

Show or hide the active layer

Lock or unlock the active layer

Rename the active layer

Duplicate the active layer. The duplicate becomes the active layer; returns its name and, when available, its layer id.

Merge all visible layers into one

Flatten all layers into a single background layer

Apply Gaussian Blur filter to the active layer

Apply Unsharp Mask (sharpen) filter to the active layer

Apply Add Noise filter to the active layer

Apply Motion Blur filter to the active layer

Apply the High Pass filter to the active raster layer — edge/detail extraction for sharpening workflows or frequency separation prep.

Users often say: high pass filter, sharpen edges, extract details, frequency separation high layer.

Use when: sharpening via overlay blend, detail extraction, or prepping a high-frequency layer. Do NOT use on text, Smart Objects, or the Background layer — rasterize or convert first (photoshop_rasterize_layer).

Returns: JSON { ok, summary, details: { filter, radius, context } }. Preconditions: active document; normal (raster) layer selected. Side effects: one history step.

Apply the Smart Blur filter to the active raster layer — edge-preserving blur for smoothing skin or simplifying backgrounds.

Users often say: smart blur, edge-preserving blur, smooth skin blur, blur but keep edges.

Use when: subtle smoothing that respects edges (portraits, product cleanup). Do NOT use on text, Smart Objects, or the Background layer — rasterize first (photoshop_rasterize_layer). Do NOT use when: uniform blur is enough — use photoshop_apply_gaussian_blur.

Returns: JSON { ok, summary, details: { filter, radius, threshold, mode, quality, context } }. Preconditions: active document; normal (raster) layer selected. Side effects: one history step.

Adjust brightness and contrast of the active layer.

Users often say: fix exposure, add contrast, brighten, darken.

Adjust hue, saturation, and lightness of the active layer

Apply auto levels adjustment to the active layer.

Users often say: fix flat image, auto tone, make it pop (mild).

Apply auto contrast adjustment to the active layer

Create a Curves adjustment layer on the active document.

Users often say: make it pop, S-curve, fix flat image, auto tone, improve contrast.

Use when: global tonal correction via a non-destructive Curves adjustment layer. Do NOT use when: stylistic cinematic grade — use photoshop_recipe_apply_color_grade.

Returns: JSON { ok, summary, details: { layer_name, preset } }. Preconditions: active document. Side effects: adds Curves adjustment layer.

Desaturate the active layer (convert to grayscale)

Invert colors of the active layer

List installed fonts available to Photoshop.

Use when: choosing a font for photoshop_create_text_layer or photoshop_set_text_font. TextItem.font requires the PostScript name — use postScriptName from results, or pass display name to set/create tools (they resolve automatically).

Returns: fonts array ({ name, postScriptName, family, style }), total count, truncated flag. First call may be slow (app.fonts.length can exceed 1000). Side effects: none.

Set font family and size for active text layer.

Accepts display name (e.g. "Arial") or PostScript name (e.g. "ArialMT") — resolved via app.fonts. Use photoshop_list_fonts to discover available fonts.

Set color for active text layer

Set text alignment for active text layer

Update the text content of active text layer

Read the active pixel selection bounds in document pixels (read-only).

Use when: verifying selection exists and its size/position before mask, fill, or recipe steps. Do NOT use when: creating or modifying a selection — use photoshop_select_rectangle or photoshop_select_subject.

Returns: JSON { ok, summary, details: { has_selection, bounds?, context } }. Preconditions: active document. Side effects: none.

Create an elliptical pixel selection from a bounding box (anti-aliased).

Use when: circular or oval masks, vignettes, or radial edits inside a region. Do NOT use when: a rectangular region is enough — use photoshop_select_rectangle.

Returns: JSON { ok, summary, details: { shape, bounds?, context } }. Preconditions: active document; right > left and bottom > top. Side effects: replaces current selection.

Expand the active pixel selection outward by a pixel amount.

Use when: growing a tight subject selection or adding padding before feather/fill. Do NOT use when: no selection exists — create one first.

Returns: JSON { ok, summary, details: { pixels, bounds?, context } }. Preconditions: active document and active pixel selection. Side effects: modifies selection.

Contract (shrink) the active pixel selection inward by a pixel amount.

Use when: tightening a loose selection or trimming halo after expand. Do NOT use when: no selection exists — create one first.

Returns: JSON { ok, summary, details: { pixels, bounds?, context } }. Preconditions: active document and active pixel selection. Side effects: modifies selection.

Feather (soften) the edges of the active pixel selection.

Use when: soft transitions before fill, mask, or delete operations. Do NOT use when: a hard edge is required or no selection exists.

Returns: JSON { ok, summary, details: { pixels, bounds?, context } }. Preconditions: active document and active pixel selection. Side effects: modifies selection edges.

Save the active pixel selection to a new alpha channel.

Use when: preserving a selection for later reload or batch workflows. Do NOT use when: no selection exists — create one first.

Returns: JSON { ok, summary, details: { channel_name, context } }. Preconditions: active document and active pixel selection. Side effects: adds alpha channel.

Create a rectangular pixel selection from corner coordinates.

Use when: masking, cropping a region, or preparing for layer mask. Do NOT use when: subject isolation is needed — use photoshop_recipe_remove_background.

Returns: selection bounds [left, top, right, bottom]. Preconditions: active document. Side effects: replaces current selection.

Select the entire document

Deselect all selections

Invert the current selection

Create a layer mask on the active layer from the current selection (reveal selection).

Users often say: mask this, hide the background, non-destructive cutout (after selection).

Use when: non-destructive hide/show after a selection exists. Do NOT use when: no selection exists — create selection first or use remove_background recipe.

Returns: maskCreated confirmation. Preconditions: active document and active selection. Side effects: adds mask to active layer.

Delete the layer mask from active layer

Apply (merge) the layer mask to the layer

Run Select Subject on the active layer (creates a pixel selection only, no mask).

Users often say: cut out, isolate subject, select person, select object.

Use when: you need a subject selection for masking, fill, or further edits. Do NOT use when: full background removal with mask — use photoshop_recipe_remove_background.

Returns: JSON { ok, summary, details: { selected, method } }. Preconditions: PS ≥ 23, active document, non-Background active layer with a recognizable subject. Side effects: replaces current selection.

Fill the current pixel selection using Content-Aware Fill.

Users often say: remove distraction, erase object, content aware fill, inpaint selection.

Use when: a rectangular or other selection covers the area to remove/replace. Do NOT use when: no selection exists — use photoshop_select_rectangle first. Do NOT use when: generative remove is requested — not scriptable; use this fill or manual touch-up.

Returns: JSON { ok, summary, details: { filled } }. Preconditions: active document and active pixel selection. Side effects: modifies pixels inside selection; deselects afterward.

Apply a linear black-to-white gradient on the active layer mask channel (fade/blend).

Users often say: fade into background, gradient mask, blend subject, soft edge fade.

This paints on an existing layer mask — not a Gradient Fill layer. Use when: softening edges or fading a layer into the background through its mask. Do NOT use when: subject is not isolated — use photoshop_recipe_remove_background or photoshop_create_layer_mask first.

Returns: JSON { ok, summary, details: { applied, direction, angle, mask_auto_created? } }. Preconditions: active document and active layer. Creates a reveal-all mask if none exists. Side effects: modifies layer mask pixels; two history steps when mask is auto-created.

Create a clipping mask on the active layer (or a named layer).

Users often say: clip to layer below, clipping mask, clip this layer, mask to shape below.

Use when: the active layer should be visible only where the layer directly below it has opaque pixels. Do NOT use when: the layer is already clipped — returns success with already_clipping. Do NOT use when: the layer is the bottom-most layer — there is no base layer to clip into.

Returns: JSON { ok, summary, details: { layer_name, is_clipping, already_clipping? } }. Preconditions: active document; target layer must sit directly above the base layer below it in the same group/stack. Side effects: one history step (groupEvent).

Release (remove) the clipping mask from the active layer (or a named layer).

Users often say: unclip, release clipping mask, remove clipping mask.

Use when: a clipped layer should become independent again. Do NOT use when: the layer is not clipped — returns not_clipping error.

Returns: JSON { ok, summary, details: { layer_name, is_clipping: false } }. Preconditions: active document; target layer must currently be a clipping mask (grouped). Side effects: sets layer.grouped = false; one history step.

Play a recorded action from the Actions palette

Execute custom ExtendScript (JSX) code inside Photoshop (advanced escape hatch).

Use when: no existing tool covers the operation and you can write safe JSX. Do NOT use when: a recipe or atomic tool exists — prefer photoshop_recipe_* or photoshop_* tools.

Returns: script return value serialized as text/JSON. IMPORTANT: Your code runs inside a wrapping IIFE. Use an explicit return to pass data back — a bare trailing expression returns undefined. Example: return { ok: true }; Objects are serialized with toSource() and parsed automatically on macOS and Windows. Preconditions: valid ExtendScript; active document if script expects one. Side effects: depends on code.

Undo the last operation(s) - equivalent to Ctrl/Cmd+Z

Redo the previously undone operation(s) - equivalent to Ctrl/Cmd+Shift+Z

Get the history states of the active document

Move the active layer relative to another layer

Move the active layer to the top of the layer stack

Move the active layer to the bottom of the layer stack

Move the active layer up one position in the layer stack

Move the active layer down one position in the layer stack

Return a cheap read-only snapshot of Photoshop session state (active document, layer, selection).

Use when: before any tool that needs an active document/layer, or after an error to recover context. Do NOT use when: you only need a visual preview — use photoshop_get_preview instead.

Returns: JSON with hasDocument, document.id/name/dimensions/colorMode, activeLayer kind/name, hasSelection. Capture document.id and pass it as document_id on later mutating calls. Preconditions: none (safe on empty session). Side effects: none.

Export the active document as a base64 JPEG preview for visual verification.

Use when: after visual edits to confirm result before reporting success to the user. Do NOT use when: you only need numeric state — use photoshop_get_state (much cheaper).

Returns: MCP image content block (JPEG) plus metadata text. Preconditions: active document required. Side effects: creates and deletes a temp file; does not modify the document.

Return version-aware feature flags for the installed Photoshop (Select Subject v2, Generative Fill, etc.).

Use when: once per session before suggesting AI-powered features or gated recipes. Do NOT use when: Photoshop version is already known from photoshop_get_version.

Returns: JSON { version, features: { select_subject_v2, generative_fill, ... } }. Preconditions: none. Side effects: none.

Fill the current selection using Adobe Generative Fill (Firefly) with a text prompt.

Use when: adding or replacing content inside a selection with generative AI. Do NOT use when: no selection exists — create one first or use photoshop_select_subject. Do NOT use when: Photoshop version lacks generative_fill — check photoshop_get_capabilities.

Returns: { ok, summary, details: { action_id, prompt, wait } }. Preconditions: PS 24+ with generative credits; active pixel selection. Side effects: modifies pixels in selection; may consume Adobe generative credits.

Remove content using the AI Remove tool (or generative fill fallback) on the current selection.

Use when: erasing distractions, people, or objects with generative AI. Do NOT use when: generative unavailable — fallback to photoshop_recipe_remove_distraction.

Returns: { ok, summary, details }. Preconditions: selection or auto_select_subject; generative_fill capability. Side effects: inpaints selected region; consumes generative credits when cloud-backed.

Extend the canvas beyond its edges using Generative Expand (Firefly).

Use when: outpainting, extending background, or expanding composition.

Returns: { ok, summary, details: { direction, prompt, wait } }. Preconditions: active document; generative_fill capability. Side effects: enlarges canvas with generated content.

Upscale the active document using Generative Upscale (PS 27+).

Use when: increasing resolution with AI detail recovery. Do NOT use when: generative_upscale flag is false — use photoshop_resize_image.

Returns: { ok, summary, details }. Preconditions: generative_upscale capability; signed-in Adobe account.

Replace the sky using Photoshop native Sky Replacement when available.

Use when: a sky image path is provided and native AI sky replacement is supported. Fallback: photoshop_recipe_sky_blend for manual composite.

Returns: { ok, summary, details }. Preconditions: active document; optional sky_image_path for custom sky.

Generate image content from a text prompt (text-to-image) on blank or active document.

Use when: creating new imagery from a description.

Returns: { ok, summary, details }. Preconditions: generative_fill capability; Adobe generative credits.

Apply a Photoshop Neural Filter via the companion UXP bridge plugin.

Use when: skin smoothing, harmonize composite layers, depth blur, super zoom, or colorizing B&W photos. Do NOT use when: uxp_bridge_reachable is false — install uxp-plugin per docs/development.md.

Returns: { ok, summary, details }. Preconditions: UXP bridge plugin running in Photoshop; PS 22+.

Apply a layer style (drop shadow, outer glow, stroke, bevel & emboss) to the active layer via Action Manager layer effects.

Users often say: add shadow, glow effect, outline this layer, stroke, bevel, 3D button look, katmana gölge ver.

Use when: quick presentational effects on the active layer (cards, buttons, mockups, text pop). Do NOT use when: you need full custom layer-effects control — use photoshop_execute_script with a custom layerEffects descriptor.

Returns: JSON { ok, summary, details: { style, layer_name } }. Preconditions: active document with an active pixel/text layer. Side effects: sets the chosen effect on the active layer. Drop shadow uses the given angle (Use Global Light is off).

Apply a Color Lookup (3D LUT) adjustment layer for cinematic color grading. Accepts a built-in LUT name (e.g. "Crisp_Warm.3dl", "Kodak 5218 Fuji 3510.3dl", "Moonlight.3dl") or an absolute path to a .cube/.3dl/.look file.

Users often say: cinematic grade, film look, teal and orange, apply LUT, sinematik renk.

Use when: stylistic non-destructive color grade in one step. Do NOT use when: basic tonal fixes — use photoshop_adjust_curves or photoshop_auto_levels.

Returns: JSON { ok, summary, details: { layer_name, lut, lut_source } }. Preconditions: active document. Side effects: adds a Color Lookup adjustment layer.

Create a Vibrance adjustment layer. Vibrance boosts muted colors while protecting skin tones.

Users often say: make colors pop (safely), boost saturation without clown look.

Returns: JSON { ok, summary, details: { layer_name, vibrance, saturation } }. Preconditions: active document. Side effects: adds a Vibrance adjustment layer.

Create an Exposure adjustment layer (stops, offset, gamma correction).

Users often say: fix underexposed photo, brighten by a stop, gamma fix.

Returns: JSON { ok, summary, details: { layer_name, exposure, offset, gamma } }. Preconditions: active document. Side effects: adds an Exposure adjustment layer.

Create a Photo Filter adjustment layer (warming/cooling/custom tint with density control).

Users often say: warm it up, cool it down, add a tint, golden hour look.

Returns: JSON { ok, summary, details: { layer_name, color, density } }. Preconditions: active document. Side effects: adds a Photo Filter adjustment layer.

Create a Gradient Map adjustment layer (black→white by default) for duotone/B&W tonal remapping.

Users often say: duotone look, gradient map B&W, remap tones.

Returns: JSON { ok, summary, details: { layer_name, reverse } }. Preconditions: active document. Side effects: adds a Gradient Map adjustment layer.

List the data sets defined on the active document (Image > Variables > Data Sets).

Use when: before applying data sets or debugging a data-driven template.

Returns: JSON { ok, summary, details: { datasets, active, count } }. Preconditions: active document with variables/data sets defined.

Import a Photoshop variables/data-sets XML file into the active document (the same file Image > Variables > Data Sets > Import accepts).

Users often say: load data sets, import variables XML, data-driven graphics.

Use when: the template PSD already has variable-bound layers and you want to load rows from an XML file. Do NOT use when: generating a batch from a CSV directly — use photoshop_recipe_csv_to_cards.

Returns: JSON { ok, summary, details: { count, datasets } }. Preconditions: active document with variables defined (Image > Variables > Define).

Batch-export the active document once per data set: applies each data set, saves a copy, moves on. "Mail merge for images".

Users often say: generate all variants, batch personalize, render every row.

Use when: data sets are already imported (photoshop_import_datasets) and you want one file per row.

Returns: JSON { ok, summary, details: { exported, skipped, output_paths } }. Preconditions: active document with data sets. Side effects: writes files to output_dir.

Load 2+ image files into one document, convert to a smart object and apply a stack mode (mean/median/max/min/...). Classic "remove tourists from N shots" or noise reduction — no generative AI involved.

Users often say: remove tourists, median stack, average these photos, noise stack, turistleri sil.

Use when: the user has multiple aligned shots of the same scene and wants a statistical blend. Do NOT use when: removing a single object from one photo — use photoshop_generative_remove or photoshop_content_aware_fill.

Returns: JSON { ok, summary, details: { file_count, mode, layer_name } }. Preconditions: 2+ existing image files. Side effects: opens the files; the stacked result becomes the active document.

Export a copy of the active document as PNG, JPEG, WebP or AVIF without changing the open document. WebP/AVIF require Photoshop 23.2+/recent builds and return a clear error when unsupported.

Users often say: export for web, save as webp, quick export png.

Use when: web-ready delivery formats are needed (WebP/AVIF/modern pipelines). Do NOT use when: saving the working document itself — use photoshop_save_document.

Returns: JSON { ok, summary, details: { path, format, method } }. Preconditions: active document. Side effects: writes one file to path.

THE tool for "remove background" / "arka planı sil" / cut out / isolate subject. Call this once and stop. Unlocks a locked Background layer, then runs Photoshop native Remove Background (Select Subject / Color Range only if native is unavailable). One undo reverts everything.

Use when: the user wants the background gone. Hair, busy interiors, product shots — still this tool. Do NOT rasterize, duplicate, hide layers, select_subject, create_layer_mask, or execute_script instead of this recipe.

Returns: { ok, summary, undo_history_states_consumed, details.method = remove_background | remove_layer_background | select_subject | color_range_fallback }.

Preconditions: an active document. Native Remove Background needs a current Photoshop; Select Subject fallback needs PS ≥ 23. Side effects: may unlock/rename the Background layer; attaches a pixel mask; no pixels destroyed; one undo reverts everything.

Set up a non-destructive portrait enhancement: duplicates the active layer, builds a frequency separation pair (low/high) for skin smoothing, and adds an auto-tone curves adjustment on top. Grouped as "Enhance Portrait" and reversible with one undo.

Users often say: smooth skin, retouch portrait, fix blemishes, clean up face.

Use when: the user asks to "enhance", "retouch", "clean up" or "smooth" a portrait photo and is happy with a baseline that they can further tweak interactively. Do NOT use when: the user wants destructive, final edits — recommend manual frequency separation work via photoshop_recipe_frequency_separation instead so they can paint by hand.

Returns: { ok, summary, details: { intensity, radius_px, group_name } }.

Preconditions: active document with a NORMAL or background-converted raster layer. Side effects: appends one layer group of 2-3 layers above the active layer; original layer untouched.

Export a web-optimized version of the active document: duplicate, convert to sRGB, downscale longest edge, sharpen for screen, save to disk. The source PSD stays untouched.

Use when: the user wants a shareable JPEG/PNG sized for the web from the current artwork. Do NOT use when: the user wants multiple platform-specific exports — use photoshop_recipe_export_social_variants. Do NOT call photoshop_save_document afterwards; this recipe already wrote the file.

Returns: { ok, summary, output_paths, undo_history_states_consumed }.

Preconditions: active document. Format is jpeg (default) or png. Side effects: writes one file to disk; the source document is unchanged.

Render one JPEG per requested social-media platform from the active document. Each variant is center-cropped/resized to the platform spec and saved to disk.

Use when: the user wants multi-platform deliverables in one shot. Do NOT use when: only one export is needed (use photoshop_recipe_prepare_for_web instead) or when platforms differ by content rather than crop (recipe does not change content, only frame).

Returns: { ok, summary, output_paths, details: { variants } }.

Preconditions: active document. Aspect ratios that differ from the source result in a center-crop (no padding). Side effects: writes one file per platform; source unchanged.

Apply a named color grading preset as a non-destructive layer group (Hue/Saturation adjustment + brightness/contrast tweak).

Users often say: cinematic look, teal and orange, moody grade, color grade.

Use when: the user wants a quick stylistic look applied to the active document. Do NOT use when: the user wants subject-specific color edits (e.g. only the skin) — current recipe applies globally.

Returns: { ok, summary, details: { preset, group_name } }.

Preconditions: active document in RGB mode. CMYK/Grayscale return unsupported_color_mode. Side effects: adds one layer group with adjustment layers; one undo reverts.

Build a frequency separation stack (Low + High) on top of the active layer for hands-on retouching. Does not apply any smoothing itself — the user paints into the layers afterwards.

Users often say: frequency separation, split texture and color, manual retouch setup.

Use when: the user explicitly wants frequency separation setup, typically for portrait or product retouching. Do NOT use when: the user wants a one-shot result without painting — use photoshop_recipe_enhance_portrait instead.

Returns: { ok, summary, details: { radius_px, group_name } }.

Preconditions: active document with a NORMAL raster active layer. Side effects: appends a "Frequency Separation" layer group with 2 prepared layers; one undo reverts everything.

Iterate a directory of asset images, replace the contents of the named Smart Object in the active mockup PSD for each asset, and export a flattened JPEG per variant. The mockup's perspective/warp on the Smart Object is preserved.

Use when: the user has a mockup PSD and wants to render it once per design asset (logos, screens, product photos). Do NOT use when: the asset is not a single layer (use photoshop_place_image manually) or when the active document has no Smart Object with the requested name.

Returns: { ok, summary, output_paths, details: { variants: [{ source_asset, output_path }] } }.

Preconditions: active document containing a Smart Object layer named exactly as requested; assets_dir must exist and be readable. Side effects: writes one JPEG per asset; the active mockup PSD ends up with the LAST asset placed.

Tidy the active document's layer stack: rename layers using a consistent scheme and optionally auto-group them by kind. Never deletes, merges or rasterizes — visual output stays identical.

Use when: the user complains about layer mess ("layer 1 copy 2", "untitled 7") or asks for organization. Do NOT use when: the user wants smart, semantic naming based on layer content beyond text — recipe only summarizes text layers, not image content.

Returns: { ok, summary, details: { renamed_count, group_count } }.

Preconditions: active document. Side effects: renames top-level layers and (optionally) moves them into kind-grouped folders; one undo reverts everything.

One-shot gradient fade on the active layer mask: creates a reveal-all mask if needed, then paints a linear black-to-white gradient for soft edge blending. Wrapped in a single undoable history step.

Users often say: fade into background, gradient mask, blend subject, soft edge fade, arka planı yumuşat.

This applies a linear gradient on the layer mask channel — not a Gradient Fill layer. Use when: the user wants the active layer to fade into the background or layers below through its mask. Do NOT use when: the subject is not isolated — use photoshop_recipe_remove_background first. Do NOT use when: replacing the sky with an external image — use photoshop_recipe_sky_blend.

Returns: { ok, summary, undo_history_states_consumed, details: { direction, start_pct, end_pct, mask_created, layer_name } }.

Preconditions: active document with an active layer. Side effects: creates or modifies the active layer mask; one undo reverts everything.

One-shot sky composite: places an external sky image, adds a layer mask, and applies a horizon gradient fade. Wrapped in a single undoable history step.

Users often say: replace sky, fix blown sky, better clouds, swap sky background.

Use when: the user provides a sky image path and native sky replacement is unavailable or manual blend is preferred. Do NOT use when: no sky_image_path is available — ask the user for an absolute file path first. Do NOT use when: fading the active subject layer only — use photoshop_recipe_gradient_fade.

Returns: { ok, summary, undo_history_states_consumed, details: { sky_image_path, layer_name, horizon_pct, feather_pct, direction } }.

Preconditions: active document; sky image file must exist on disk. Side effects: adds a placed sky layer with gradient mask; one undo reverts everything.

One-shot dodge & burn setup: creates a 50% gray layer in Overlay or Soft Light mode for non-destructive light sculpting. Wrapped in a single undoable history step.

Users often say: dodge and burn, sculpt light, lighten face, darken shadows.

Use when: the user wants a ready-to-paint dodge & burn layer above the subject. Do NOT use when: the user wants automated retouch — this only sets up the paint layer; paint white (dodge) and black (burn) manually at low opacity. Do NOT use when: automated portrait smoothing is enough — use photoshop_recipe_enhance_portrait instead.

Returns: { ok, summary, undo_history_states_consumed, details: { layer_name, blend_mode } }.

Preconditions: active document with a raster-compatible active layer. Side effects: adds one "Dodge & Burn" layer above the active layer; one undo reverts.

One-shot distraction removal: generative AI remove when available, else content-aware fill. Wrapped in a single undoable history step.

Users often say: remove that person, erase distraction, content aware remove, clone out object.

Use when: the user has selected the object or region to remove. Do NOT use when: no selection exists — use photoshop_select_rectangle or photoshop_select_subject first.

Returns: { ok, summary, undo_history_states_consumed, details }. Preconditions: active document with an active pixel selection. Side effects: fills/removes selected pixels; clears selection.

Split the active wide document into N equal vertical slices and export them as sequentially numbered files for a seamless Instagram/TikTok carousel (panorama swipe effect).

Use when: the user wants a seamless/swipeable carousel, split panorama, or multi-slide export of one wide design. Typical request: "split this into a 5-slide carousel". Do NOT use when: the user wants the same content reframed per platform (use photoshop_recipe_export_social_variants) or a single crop (use photoshop_crop_document).

Returns: { ok, summary, output_paths (in slide order), details: { slides, slice_width } }.

Preconditions: active document whose width is at least slides pixels. Side effects: writes one file per slide; source document is unchanged.

Apply a text or logo watermark to every image in a folder and export watermarked JPEGs. Replaces the clunky record-an-action + File > Automate > Batch workflow.

Use when: the user wants to watermark many photos at once (copyright text, studio logo). Do NOT use when: watermarking a single open document (use photoshop_create_text_layer / photoshop_place_image directly) or removing watermarks (not supported).

Returns: { ok, summary, output_paths, details: { processed, failed: [{ file, error }] } }. Files that fail are skipped, not fatal.

Preconditions: assets_dir exists; either text or logo_path given. No active document required. Side effects: writes one JPEG per source image; source files are never modified.

Turn the active portrait into a passport/ID photo: removes the background via Select Subject, replaces it with white, crops around the subject with ICAO-style headroom, resizes to the exact official pixel size at 300 DPI, and exports a JPEG. Optionally also builds a 10×15 cm print sheet with multiple copies.

Use when: passport photo, visa photo, ID photo, vesikalık, biyometrik fotoğraf. Do NOT use when: the document has no clear single subject, or official compliance must be guaranteed — head-size rules are approximated from subject bounds (no face detection); official acceptance is NOT guaranteed.

Returns: { ok, summary, output_paths, details: { spec, width, height, sheet } }.

Preconditions: PS ≥ 23 (Select Subject v2); active document with a single-person portrait. Side effects: writes one JPEG (+ one sheet JPEG when make_sheet); source document is unchanged.

Data-driven graphics batch: convert a CSV file into Photoshop data sets, apply each row to the active template document and export one image per row. "Mail merge for images" — name cards, badges, certificates, personalized banners.

Users often say: csv to images, batch name cards, personalized banners, generate badges from spreadsheet, sertifika bastır.

CSV rules: first row = variable names matching the variables defined in the template PSD (Image > Variables > Define). A cell holding an absolute path to an image file (.png/.jpg/.webp/.tif/.psd) is treated as a pixel-replacement variable.

Use when: the user has a template PSD with variable-bound layers and a CSV of rows. Do NOT use when: the document has no variables defined — define them in Photoshop first (Image > Variables > Define).

Returns: { ok, summary, details: { rows, exported, output_paths, xml_path } }.

Preconditions: active document with variable-bound layers; readable CSV file. Side effects: writes a temp variables XML and one output file per row into output_dir.