editmamei 1.0.3 → 1.2.0

package/dist/tools/group-tools.js

@@ -1,11 +1,7 @@
 import { runScript } from '../utils/run-script.js';
 import { GROUP_BLEND_MODES } from '../utils/blend-modes.js';
 import { validateArgs } from '../utils/validate.js';
-import { toolErrorResult, runSnippetTool } from '../utils/tool-helpers.js';
-const emptySchema = {
-    type: 'object',
-    properties: {},
-};
+import { toolErrorResult, runSnippetTool, unknownDiscriminator } from '../utils/tool-helpers.js';
 const deleteGroupSchema = {
     type: 'object',
     properties: {
@@ -45,7 +41,7 @@ const moveLayerToGroupSchema = {
     properties: {
         layer_name: {
             type: 'string',
-            description: 'Name of the layer to move (recursive search).',
+            description: 'Name of the layer to move (recursive search). A layer is preferred over a group of the same name; a group is moved only when no layer matches, which is how one group is nested inside another.',
         },
         group_name: {
             type: 'string',
@@ -83,189 +79,193 @@ const ungroupSchema = {
     },
     required: ['name', 'confirm'],
 };
+const CLIPPING_MASK_OPS = ['create', 'release'];
+const clippingMaskSchema = {
+    type: 'object',
+    properties: {
+        op: {
+            type: 'string',
+            enum: [...CLIPPING_MASK_OPS],
+            description: 'create: clip the active layer to the layer directly below it (that layer becomes the alpha source); no-ops (already_clipped:true) when the layer is already clipped. ' +
+                'release: release the active layer from its clipping mask; no-ops (released:false) when the layer is not clipped.',
+        },
+    },
+    required: ['op'],
+};
+const clippingMaskOpArgsSchema = {
+    type: 'object',
+    properties: {},
+};
+const GROUP_OPS = ['create', 'delete', 'ungroup', 'add_layer', 'set_blend_mode'];
+export const GROUP_OP_SCHEMAS = {
+    create: createGroupSchema,
+    delete: deleteGroupSchema,
+    ungroup: ungroupSchema,
+    add_layer: moveLayerToGroupSchema,
+    set_blend_mode: setGroupBlendModeSchema,
+};
+const GROUP_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        op: {
+            type: 'string',
+            enum: [...GROUP_OPS],
+            description: "create: make a new group above the active layer named `name` (hoisted out of an active group by default; into_active_group:true keeps Photoshop's native nesting), optionally moving `layers` into it. " +
+                'delete: DESTRUCTIVE — delete group `name` and everything inside it (nested groups and their layers); requires confirm:true. To dissolve a group while keeping its contents, use ungroup instead. ' +
+                'ungroup: DESTRUCTIVE structural change — dissolve group `name`, promoting its contents to the parent level in their existing stack order; requires confirm:true. ' +
+                'add_layer: move `layer_name` into `group_name` (top of its stack). ' +
+                "set_blend_mode: set group `name`'s blend mode to `blend_mode` — PASSTHROUGH (default for new groups) lets adjustments inside affect layers below the group; NORMAL treats the group as a single composite.",
+        },
+        ...createGroupSchema.properties,
+        name: {
+            type: 'string',
+            description: 'Group name. create: name for the NEW group. delete/ungroup/set_blend_mode: the EXISTING group to act on (recursive search).',
+        },
+        confirm: {
+            type: 'boolean',
+            description: 'REQUIRED for op=delete and op=ungroup, ignored by the other ops. Must be true — guards against accidental loss of a group and (for delete) everything it contains.',
+        },
+        ...moveLayerToGroupSchema.properties,
+        blend_mode: setGroupBlendModeSchema.properties.blend_mode,
+    },
+    required: ['op'],
+};
 export function createGroupTools(connection, snippetClient) {
     return [
         {
             tool: {
-                name: 'ps_create_group',
-                description: `Create a new layer group (LayerSet) above the active layer with the given name — hoisted out of the active layer's group by default even though Photoshop's own Mk-layerSection placement rule would otherwise nest it INSIDE that group (pass into_active_group:true to keep that native nesting; this is why groups created one after another land as siblings rather than nested, so bottom-to-top group creation is safe). Optionally moves existing layers into it in one step. Non-destructive. Foundational for structured non-destructive editing — e.g. group all adjustment layers into an "edits" group so you can A/B toggle the whole stack via group visibility.`,
-                inputSchema: createGroupSchema,
+                name: 'ps_group',
+                description: 'Layer group (LayerSet) lifecycle and membership — choose the operation with `op`. create/delete/ungroup/add_layer/set_blend_mode. See the `op` enum for per-operation params. delete and ungroup are DESTRUCTIVE and require confirm:true — delete removes the group AND everything inside it; ungroup dissolves the group but promotes its contents to the parent level (use ungroup, not delete, to keep the layers).',
+                inputSchema: GROUP_INPUT_SCHEMA,
                 outputSchema: {
                     type: 'object',
                     properties: {
-                        created: { type: 'boolean' },
+                        created: { type: 'boolean', description: 'op=create: true on success.' },
+                        deleted: { type: 'boolean', description: 'op=delete: true on success.' },
+                        ungrouped: { type: 'boolean', description: 'op=ungroup: true on success.' },
+                        moved: { type: 'boolean', description: 'op=add_layer: true on success.' },
+                        set: { type: 'boolean', description: 'op=set_blend_mode: true on success.' },
                         groupName: { type: 'string' },
-                        moved_count: { type: 'number' },
-                        not_found: { type: 'array', items: { type: 'string' } },
+                        layerName: { type: 'string', description: 'op=add_layer: the moved layer.' },
+                        blendMode: { type: 'string', description: 'op=set_blend_mode: the mode applied.' },
+                        moved_count: { type: 'number', description: 'op=create: layers moved into it.' },
+                        not_found: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'op=create: requested layer names that were not found.',
+                        },
                         hoisted: {
                             type: 'boolean',
-                            description: 'True when the new group had to be moved back out of the previously-active group to honor into_active_group:false (the default). False when it landed correctly on its own, or when the move-back itself failed — check the layer tree if this matters and hoisted is false.',
+                            description: 'op=create: true when the new group had to be moved back out of the previously-active group to honor into_active_group:false.',
                         },
                         parent_path: {
                             type: ['array', 'null'],
                             items: { type: 'string' },
-                            description: 'The containing-group name chain (outermost first), empty array at the document root.',
+                            description: 'op=create: the containing-group name chain (outermost first), empty array at the document root.',
+                        },
+                        descendants_deleted: {
+                            type: 'number',
+                            description: 'op=delete: total layers removed with the group.',
+                        },
+                        children_promoted: {
+                            type: 'number',
+                            description: 'op=ungroup: children promoted to the parent level.',
+                        },
+                        child_names: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'op=ungroup: names of the promoted children.',
                         },
                         context: { type: 'object' },
                     },
                 },
                 annotations: {
-                    title: 'Create Layer Group',
-                    idempotentHint: false,
-                },
-            },
-            handler: async (args) => createGroup(connection, snippetClient, args),
-        },
-        {
-            tool: {
-                name: 'ps_move_layer_to_group',
-                description: 'Move a named layer into a named group. The layer is placed at the top of the group stack. Both layer_name and group_name are looked up recursively. Throws if either is not found, or if the layer IS the group itself.',
-                inputSchema: moveLayerToGroupSchema,
-                outputSchema: {
-                    type: 'object',
-                    properties: {
-                        moved: { type: 'boolean' },
-                        layerName: { type: 'string' },
-                        groupName: { type: 'string' },
-                        context: { type: 'object' },
-                    },
-                },
-                annotations: {
-                    title: 'Move Layer Into Group',
-                    idempotentHint: false,
-                },
-            },
-            handler: async (args) => moveLayerToGroup(connection, snippetClient, args),
-        },
-        {
-            tool: {
-                name: 'ps_set_group_blend_mode',
-                description: "Set a group's blend mode. The default for new groups is PASSTHROUGH (adjustments inside affect layers below the group). Change to NORMAL when treating the group as a single composite — required for masking a stack of adjustments with one mask.",
-                inputSchema: setGroupBlendModeSchema,
-                outputSchema: {
-                    type: 'object',
-                    properties: {
-                        set: { type: 'boolean' },
-                        groupName: { type: 'string' },
-                        blendMode: { type: 'string' },
-                        context: { type: 'object' },
-                    },
-                },
-                annotations: {
-                    title: 'Set Group Blend Mode',
-                    idempotentHint: true,
-                },
-            },
-            handler: async (args) => setGroupBlendMode(connection, snippetClient, args),
-        },
-        {
-            tool: {
-                name: 'ps_ungroup',
-                description: 'DESTRUCTIVE structural change: Dissolve a group, leaving its contents at the parent level in their existing stack order. The group itself is removed. Requires confirm:true. Recoverable only via Edit > Undo.',
-                inputSchema: ungroupSchema,
-                outputSchema: {
-                    type: 'object',
-                    properties: {
-                        ungrouped: { type: 'boolean' },
-                        groupName: { type: 'string' },
-                        children_promoted: { type: 'number' },
-                        child_names: { type: 'array', items: { type: 'string' } },
-                        context: { type: 'object' },
-                    },
-                },
-                annotations: {
-                    title: 'Ungroup Layer Set (destructive structural change)',
+                    title: 'Group',
                     destructiveHint: true,
                     idempotentHint: false,
                 },
             },
-            handler: async (args) => ungroup(connection, snippetClient, args),
+            handler: async (args) => groupDispatch(connection, snippetClient, args),
         },
         {
             tool: {
-                name: 'ps_create_clipping_mask',
-                description: 'Clip the active layer to the layer directly below it (uses that layer as the alpha source). Non-destructive — the upper layer is unchanged; PS just paints it only where the layer below has pixels. Common for masking adjustment-layer effect to a single underlying layer, or constraining a texture/photo to a shape. Equivalent to the PS menu Layer > Create Clipping Mask (Ctrl+Alt+G). Reverse it with the PS menu Layer > Release Clipping Mask, or ps_undo. This is the standalone primitive — the add_adjustment_layer tool already accepts clip_to_below for the adjustment-layer-specific case.',
-                inputSchema: { type: 'object', properties: {}, required: [] },
+                name: 'ps_clipping_mask',
+                description: 'Clip or un-clip the active layer against the layer directly below it — choose with `op`. `create`: use the layer below as the alpha source; PS paints the active layer only where the layer below has pixels. Non-destructive — the upper layer is unchanged. Common for constraining a texture/photo to a shape, or masking an effect to a single underlying layer (the add_adjustment_layer tool already accepts clip_to_below for the adjustment-layer-specific case). Equivalent to Layer > Create Clipping Mask (Ctrl+Alt+G). `release`: the inverse — the layer returns to compositing against the whole canvas. Both ops are idempotent: create no-ops (already_clipped:true) on an already-clipped layer; release no-ops (released:false) on a non-clipped layer.',
+                inputSchema: clippingMaskSchema,
                 outputSchema: {
                     type: 'object',
                     properties: {
                         clipped: { type: 'boolean' },
-                        layerName: { type: 'string' },
-                        context: { type: 'object' },
-                    },
-                },
-                annotations: {
-                    title: 'Create Clipping Mask',
-                    idempotentHint: false,
-                },
-            },
-            handler: async (args) => createClippingMask(connection, snippetClient, args),
-        },
-        {
-            tool: {
-                name: 'ps_release_clipping_mask',
-                description: "Release the active layer's clipping mask (the inverse of ps_create_clipping_mask). The layer returns to compositing against the whole canvas instead of just the layer below. Equivalent to PS menu Layer > Release Clipping Mask. Idempotent on a non-clipped layer (PS silently no-ops).",
-                inputSchema: { type: 'object', properties: {}, required: [] },
-                outputSchema: {
-                    type: 'object',
-                    properties: {
+                        already_clipped: { type: 'boolean' },
                         released: { type: 'boolean' },
                         layerName: { type: 'string' },
                         context: { type: 'object' },
                     },
                 },
                 annotations: {
-                    title: 'Release Clipping Mask',
+                    title: 'Clipping Mask',
                     idempotentHint: true,
                 },
             },
-            handler: async (args) => releaseClippingMask(connection, snippetClient, args),
-        },
-        {
-            tool: {
-                name: 'ps_delete_group',
-                description: 'DESTRUCTIVE: Delete a group AND ALL its contents (including nested groups and their layers). Requires confirm:true because the destructive scope is much larger than a single-layer delete. Recoverable only via Edit > Undo. To dissolve a group while keeping its contents, use ps_ungroup instead.',
-                inputSchema: deleteGroupSchema,
-                outputSchema: {
-                    type: 'object',
-                    properties: {
-                        deleted: { type: 'boolean' },
-                        groupName: { type: 'string' },
-                        descendants_deleted: { type: 'number' },
-                        context: { type: 'object' },
-                    },
-                },
-                annotations: {
-                    title: 'Delete Group (destructive, recursive)',
-                    destructiveHint: true,
-                    idempotentHint: false,
-                },
-            },
-            handler: async (args) => deleteGroup(connection, snippetClient, args),
+            handler: async (args) => clippingMask(connection, snippetClient, args),
         },
     ];
 }
-async function createClippingMask(connection, snippetClient, rawArgs) {
-    return runSnippetTool({
-        connection,
-        snippetClient,
-        rawArgs,
-        schema: emptySchema,
-        snippet: 'createClippingMask',
-        errorPrefix: 'Error creating clipping mask',
-        successText: (result) => `Clipped layer "${result.layerName ?? ''}" to the layer below.`,
-    });
+async function clippingMask(connection, snippetClient, rawArgs) {
+    const op = rawArgs.op;
+    const { op: _omit, ...rest } = rawArgs;
+    switch (op) {
+        case 'create':
+            return runSnippetTool({
+                connection,
+                snippetClient,
+                rawArgs: rest,
+                schema: clippingMaskOpArgsSchema,
+                snippet: 'createClippingMask',
+                errorPrefix: 'Error creating clipping mask',
+                successText: (result) => {
+                    const r = result;
+                    return r.already_clipped === true
+                        ? `Layer "${r.layerName ?? ''}" is already clipped — nothing to do.`
+                        : `Clipped layer "${r.layerName ?? ''}" to the layer below.`;
+                },
+            });
+        case 'release':
+            return runSnippetTool({
+                connection,
+                snippetClient,
+                rawArgs: rest,
+                schema: clippingMaskOpArgsSchema,
+                snippet: 'releaseClippingMask',
+                errorPrefix: 'Error releasing clipping mask',
+                successText: (result) => {
+                    const r = result;
+                    return r.released === false
+                        ? `Layer "${r.layerName ?? ''}" is not clipped — nothing to release.`
+                        : `Released clipping mask on layer "${r.layerName ?? ''}".`;
+                },
+            });
+        default:
+            return unknownDiscriminator('clipping_mask op', op, CLIPPING_MASK_OPS);
+    }
 }
-async function releaseClippingMask(connection, snippetClient, rawArgs) {
-    return runSnippetTool({
-        connection,
-        snippetClient,
-        rawArgs,
-        schema: emptySchema,
-        snippet: 'releaseClippingMask',
-        errorPrefix: 'Error releasing clipping mask',
-        successText: (result) => `Released clipping mask on layer "${result.layerName ?? ''}".`,
-    });
+async function groupDispatch(connection, snippetClient, rawArgs) {
+    const op = rawArgs.op;
+    const { op: _omit, ...rest } = rawArgs;
+    switch (op) {
+        case 'create':
+            return createGroup(connection, snippetClient, rest);
+        case 'delete':
+            return deleteGroup(connection, snippetClient, rest);
+        case 'ungroup':
+            return ungroup(connection, snippetClient, rest);
+        case 'add_layer':
+            return moveLayerToGroup(connection, snippetClient, rest);
+        case 'set_blend_mode':
+            return setGroupBlendMode(connection, snippetClient, rest);
+        default:
+            return unknownDiscriminator('group op', op, GROUP_OPS);
+    }
 }
 async function createGroup(connection, snippetClient, rawArgs) {
     return runSnippetTool({

package/dist/tools/history-tools.js

@@ -39,7 +39,7 @@ export function createHistoryTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_undo',
-                description: 'Step backward in the document history (equivalent to Ctrl/Cmd+Z). WHEN TO REACH FOR THIS: after an experimental destructive bake (ps_merge mode=visible/flatten, ps_apply_filter type=*_blur/sharpen/noise) produced a wrong result; after a play_action whose scope you mispredicted; or to revert an entire branch of exploration. Non-destructive workflows (adjustment layers + masks) rarely need this — just tweak/delete the offending layer instead. Reversible via ps_redo as long as no new edit has been made since. Returns current history state, remaining steps, and document context.',
+                description: 'Step backward in the document history (equivalent to Ctrl/Cmd+Z). WHEN TO REACH FOR THIS: after an experimental destructive bake (ps_merge mode=visible/flatten, ps_filter op=apply type=*_blur/sharpen/noise) produced a wrong result; after a play_action whose scope you mispredicted; or to revert an entire branch of exploration. Non-destructive workflows (adjustment layers + masks) rarely need this — just tweak/delete the offending layer instead. Reversible via ps_redo as long as no new edit has been made since. Returns current history state, remaining steps, and document context.',
                 inputSchema: undoSchema,
                 outputSchema: HISTORY_STEP_RESULT_SCHEMA,
                 annotations: {

package/dist/tools/inspect-tools.js

@@ -2,7 +2,14 @@ import { getMetadata, getMetadataSchema } from './metadata-tools.js';
 import { getHistory } from './history-tools.js';
 import { getLayerTree } from './layer-tools.js';
 import { getSelectionInfoHandler } from './selection-tools.js';
-const INSPECT_WHATS = ['metadata', 'layer_tree', 'history', 'selection_info'];
+import { getSmartObjectInfoHandler } from './smart-object-tools.js';
+const INSPECT_WHATS = [
+    'metadata',
+    'layer_tree',
+    'history',
+    'selection_info',
+    'smart_object',
+];
 const INSPECT_INPUT_SCHEMA = {
     type: 'object',
     properties: {
@@ -13,7 +20,8 @@ const INSPECT_INPUT_SCHEMA = {
                 'metadata: document/IPTC/camera-EXIF/GPS/ACR develop settings + active context (optionally subset with `sections`; sections=["context"] is the cheap orientation probe). ' +
                 'layer_tree: the full recursive layer tree (name/kind/visibility/opacity/blend/clipping/bounds) — use whenever you need what is inside a group. ' +
                 'history: all history states + the current cursor, for deciding how far to undo. ' +
-                'selection_info: current selection bounds/coverage/edge-complexity without modifying anything.',
+                'selection_info: current selection bounds/coverage/edge-complexity without modifying anything. ' +
+                'smart_object: whether the ACTIVE layer is a Smart Object and, if so, whether its source is embedded or linked to a file on disk, plus how many Smart Filters it carries.',
         },
         ...getMetadataSchema.properties,
     },
@@ -24,7 +32,7 @@ export function createInspectTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_inspect',
-                description: 'Read-only document inspection — choose with `what` (metadata / layer_tree / history / selection_info). This is the assess/orientation surface: call it at the start of a workflow and whenever you need fresh state. For metadata, pass `sections` to subset (e.g. ["context"] for a cheap probe). For an IMAGE-based check use ps_get_preview; for NUMERIC verification use ps_get_histogram / ps_compare_regions / ps_get_layer_bounds_diff (these stay separate, named tools on purpose). Read-only and idempotent.',
+                description: 'Read-only document inspection — choose with `what` (metadata / layer_tree / history / selection_info / smart_object). This is the assess/orientation surface: call it at the start of a workflow and whenever you need fresh state. For metadata, pass `sections` to subset (e.g. ["context"] for a cheap probe). For an IMAGE-based check use ps_get_preview; for NUMERIC verification use ps_get_histogram / ps_compare_regions / ps_get_layer_bounds_diff (these stay separate, named tools on purpose). Read-only and idempotent.',
                 inputSchema: INSPECT_INPUT_SCHEMA,
                 outputSchema: {
                     type: 'object',
@@ -47,6 +55,15 @@ export function createInspectTools(connection, snippetClient) {
                         canRedo: { type: 'boolean' },
                         states: { type: 'array' },
                         selection_info: { type: 'object' },
+                        is_smart_object: { type: 'boolean' },
+                        linked: { type: 'boolean' },
+                        file_reference: { type: ['string', 'null'] },
+                        document_id: { type: ['string', 'null'] },
+                        placed: { type: ['string', 'null'] },
+                        smart_filter_count: { type: 'number' },
+                        layer_name: { type: 'string' },
+                        layer_kind: { type: 'string' },
+                        bounds: { type: 'array' },
                     },
                 },
                 annotations: {
@@ -72,6 +89,8 @@ async function inspect(connection, snippetClient, rawArgs) {
             return getHistory(connection, snippetClient);
         case 'selection_info':
             return getSelectionInfoHandler(connection, snippetClient);
+        case 'smart_object':
+            return getSmartObjectInfoHandler(connection, snippetClient);
         default:
             return {
                 content: [

package/dist/tools/layer-tools.js

@@ -19,7 +19,7 @@ const deleteLayerSchema = {
     },
 };
 const PS_TEXT_COORD_MAX = 300_000;
-const createTextLayerSchema = {
+export const createTextLayerSchema = {
     type: 'object',
     properties: {
         text: {
@@ -195,7 +195,7 @@ export function createLayerTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_create_layer',
-                description: 'Create a new empty raster layer above the currently active layer. Non-destructive. Use ps_create_text_layer for text, ps_add_adjustment_layer for adjustments.',
+                description: 'Create a new empty raster layer above the currently active layer. Non-destructive. Use ps_text (op=create) for text, ps_add_adjustment_layer for adjustments.',
                 inputSchema: createLayerSchema,
                 outputSchema: {
                     type: 'object',
@@ -220,7 +220,7 @@ export function createLayerTools(connection, snippetClient) {
         {
             tool: {
                 name: 'ps_delete_layer',
-                description: 'DESTRUCTIVE: Delete a layer. With no arg, deletes the currently active layer (backward-compatible). With `name`, recurses into groups and deletes the first layer matching that name — useful for cleanup workflows where the dead layer is not currently active. Recoverable only via Edit > Undo. To delete a group and all its contents, use ps_delete_group.',
+                description: 'DESTRUCTIVE: Delete a layer. With no arg, deletes the currently active layer (backward-compatible). With `name`, recurses into groups and deletes the first LAYER matching that name — useful for cleanup workflows where the dead layer is not currently active. A name that matches a group is refused rather than deleted; use ps_group(op=delete) to delete a group and all its contents. Recoverable only via Edit > Undo.',
                 inputSchema: deleteLayerSchema,
                 outputSchema: {
                     type: 'object',
@@ -238,29 +238,6 @@ export function createLayerTools(connection, snippetClient) {
             },
             handler: async (args) => deleteLayer(connection, snippetClient, args),
         },
-        {
-            tool: {
-                name: 'ps_create_text_layer',
-                description: 'Create a new text layer with the given content, position, and font size. The text is editable (vector). Use ps_set_text (property=font / color) afterwards to style.',
-                inputSchema: createTextLayerSchema,
-                outputSchema: {
-                    type: 'object',
-                    properties: {
-                        created: { type: 'boolean' },
-                        layerName: { type: 'string' },
-                        text: { type: 'string' },
-                        position: { type: 'object' },
-                        fontSize: { type: 'number' },
-                        context: { type: 'object' },
-                    },
-                },
-                annotations: {
-                    title: 'Create Text Layer',
-                    idempotentHint: false,
-                },
-            },
-            handler: async (args) => createTextLayer(connection, snippetClient, args),
-        },
         {
             tool: {
                 name: 'ps_fill_layer',
@@ -382,7 +359,7 @@ async function deleteLayer(connection, snippetClient, rawArgs) {
         },
     });
 }
-async function createTextLayer(connection, snippetClient, rawArgs) {
+export async function createTextLayer(connection, snippetClient, rawArgs) {
     return runSnippetTool({
         connection,
         snippetClient,

package/dist/tools/overview-tools.js

@@ -19,6 +19,8 @@ Every non-trivial edit follows the same six phases:
 
 1. **Assess** — \`ps_inspect\` (what=metadata / layer_tree / history /
    selection_info) + \`ps_get_preview\` to understand what you're working with.
+   If \`ps_open_document\` reported \`is_raw_source: true\`, see
+   "Raw-sourced documents" below.
 2. **Plan** — name the intent, the layers/regions involved, and the
    exit criteria. Tell the user before you execute.
 3. **Enact** — call the tools.
@@ -31,6 +33,33 @@ Every non-trivial edit follows the same six phases:
    \`ps_save_psd\`. Confirm the user wants to flatten before
    destructive saves.
 
+## Raw-sourced documents
+
+\`ps_open_document\` reports \`is_raw_source: true\` for raw captures
+(DNG, NEF, CR3, ARW, …) — the open applied last-used/default Camera
+Raw settings, so no deliberate develop has happened yet. When
+\`tools/list\` includes a camera-raw develop tool, the FIRST enacting
+step on a raw document is that develop pass on the base smart object —
+NOT stacked Levels/Curves adjustment layers. The develop pass owns
+global tone and color; adjustment layers come after, for local/masked
+corrections and finishing moves.
+
+Make the first develop pass a complete grade in ONE call, not a timid
+nudge: tone endpoints (exposure, contrast, highlights/shadows AND
+whites/blacks), presence (texture, clarity, dehaze), a parametric
+curve, white balance + vibrance + per-channel HSL where colors need
+steering, color grading, capture sharpening + noise reduction (raws
+get none by default), optics/vignette where they serve the image.
+Three sliders at small values reads as "untouched." Large moves are
+safe — the develop is a re-editable smart filter, nothing bakes:
+start bold, check preview + histogram, ease off.
+
+To refine, call the develop tool again in its adjust-existing mode —
+it preserves every slider you don't pass. Never add a second
+camera-raw filter. If no camera-raw develop tool is in \`tools/list\`,
+say so in one sentence and build global tone with adjustment layers.
+Explicit user instructions always win.
+
 ## Capabilities map
 
 This map covers the workflow categories. For specific tool names and
@@ -40,8 +69,9 @@ schemas in this session, consult \`tools/list\`.
   covers brightness/contrast, levels, curves, hue/sat, color balance,
   photo filter, vibrance, channel mixer, selective color, black & white,
   gradient map, exposure, color lookup, invert. Always prefer this over
-  destructive filters for tone/color work.
-- **Filters (destructive)** — \`ps_apply_filter\` with a
+  destructive filters for tone/color work — except raw-sourced
+  documents: the camera-raw develop pass goes first (see above).
+- **Filters (destructive)** — \`ps_filter\` with a
   \`type\` (gaussian_blur, motion_blur, lens_blur, radial_blur, sharpen,
   smart_sharpen, noise, reduce_noise, high_pass, pixelate, distort,
   displace, oil_paint). Auto-duplicates the active layer by default so
@@ -81,16 +111,15 @@ schemas in this session, consult \`tools/list\`.
   locally. Reach for these to get REAL coordinates rather than
   estimating from the preview — they're the antidote to spatial
   guessing.
-- **Text** — \`ps_create_text_layer\`, then \`ps_set_text\`
-  (property font / color / alignment / content; font resolves family
-  names to PostScript).
+- **Text** — \`ps_text\` (op create, then set_font / set_color /
+  set_alignment / set_content; font resolves family names to
+  PostScript).
 - **Image** — \`ps_place_image\` (links external files as smart
   objects), \`ps_resize_image\`, \`ps_crop_document\`,
   \`ps_convert_image_mode\`, open / close / save_psd, and
   \`ps_export\` (format jpeg/png).
-- **Groups** — \`ps_create_group\`,
-  \`ps_move_layer_to_group\`, \`ps_set_group_blend_mode\`,
-  \`ps_ungroup\`, \`ps_delete_group\`.
+- **Groups** — \`ps_group\` (op create / delete / ungroup /
+  add_layer / set_blend_mode).
 - **Verification** — see below; this is the most underused part of
   the surface.
 - **Templates** — when template tools are present in \`tools/list\`,

package/dist/tools/preview-tools.js

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { getContextInfo, normNameHelper } from '../api/extendscript/_helpers.js';
+import { getContextInfo, normNameHelper, notFoundMessageHelper, } from '../api/extendscript/_helpers.js';
 import { jsLit, jsNum } from '../utils/jsx.js';
 import { runScript } from '../utils/run-script.js';
 import { TempDir, userOwnedTempRoot } from '../utils/temp.js';
@@ -899,6 +899,7 @@ async function getLayerBoundsDiff(connection, rawArgs) {
       var doc = app.activeDocument;
 
       ${normNameHelper}
+      ${notFoundMessageHelper}
       // Em-dash / en-dash tolerant comparison (Bug I) via normName — the
       // LLM routinely swaps these silently; raw equality would miss.
       // Depth cap is defense-in-depth (see selectLayer's identical comment).
@@ -919,7 +920,7 @@ async function getLayerBoundsDiff(connection, rawArgs) {
         return null;
       }
       var lyr = findLayerByName(doc.layers);
-      if (!lyr) throw new Error('Layer not found: ' + ${jsLit(layer)});
+      if (!lyr) throw new Error(__notFoundMessage('Layer', ${jsLit(layer)}, false));
 
       var b = (lyr.boundsNoEffects !== undefined) ? lyr.boundsNoEffects : lyr.bounds;
       var aLeft = b[0].as('px');

package/dist/tools/scene-tools.js

@@ -367,7 +367,7 @@ export function createSceneTools(connection, snippetClient, opts = {}) {
         {
             tool: {
                 name: 'ps_read_scene',
-                description: 'Build a structured SCENE MODEL of the active document using LOCAL on-device vision + classical CV — the "look before you select" read. Returns detected subjects (with the main one flagged) and faces in document pixels, a coarse sky/ground region map, the horizon line (y + placement + confidence), tonal zones (shadow/midtone/highlight bands + coverage), and composition geometry (which thirds cell the subject sits in, balance, headroom), plus an annotated preview. The image never leaves the machine. Read-only: renders a throwaway duplicate. Run this first to SEE the menu of selectable named regions, then select them by name with ps_select_by_reference instead of guessing a rectangle. Perception is cached per document state, so repeated reads are cheap.',
+                description: 'The full scene model — run this before a spatially-targeted edit, not the cheaper ps_detect: detected subjects (with the main one flagged) and faces in document pixels, a coarse sky/ground region map, the horizon line (y + placement + confidence), tonal zones (shadow/midtone/highlight bands + coverage), composition geometry (which thirds cell the subject sits in, balance, headroom), plus an annotated preview and the menu of selectable named regions. Built using LOCAL on-device vision + classical CV; the image never leaves the machine. Select regions by name with ps_select_by_reference instead of guessing a rectangle. Read-only: renders a throwaway duplicate. Perception is cached per document state, so repeated reads are cheap.',
                 inputSchema: sceneSchema,
                 outputSchema: {
                     type: 'object',