editmamei 0.19.0 → 0.22.0

package/dist/tools/preview-tools.js

@@ -4,7 +4,6 @@ import { jsLit, jsNum } from '../utils/jsx.js';
 import { runScript } from '../utils/run-script.js';
 import { TempDir, userOwnedTempRoot } from '../utils/temp.js';
 import { validateArgs } from '../utils/validate.js';
-import { overlayCoordinateGrid } from '../preview/coordinate-grid.js';
 const COLOR_NAME_HEX = {
     red: '#FF0000',
     blue: '#0066FF',
@@ -129,47 +128,6 @@ const previewSchema = {
             description: "Optional list of visual annotations to draw onto the preview before rendering — rectangles (by explicit bounds OR by layer name), guides (horizontal / vertical reference lines), point markers, and the current document selection. Use this to verify SPATIAL work (placement, alignment, scaling) — pass both your TARGET rect and the ACTUAL placement (e.g. the layer's bounds) in different colors, then visually compare in the returned image. Skips the spatial-self-evaluation trap where the LLM tries to estimate alignment from a plain preview.",
             items: annotationSchema,
         },
-        coordinate_grid: {
-            type: 'object',
-            description: 'Overlay a LABELED coordinate grid on the preview (drawn server-side) so you can read exact DOCUMENT-pixel coordinates straight off the lines instead of estimating. Reach for this BEFORE any tool that needs precise coordinates (rectangle/polygon selections, point-driven filters, future warp meshes). Each gridline is labeled with its document-pixel value (top-left origin, matching Photoshop coordinates). Either pass `step_px` (regular grid every N document px), OR `columns`/`rows` (even divisions), OR neither (auto ~10 divisions on the long edge). Composes with `annotations` (those draw first, in Photoshop; the grid is layered on top in Node).',
-            properties: {
-                step_px: {
-                    type: 'number',
-                    description: 'Regular grid: line spacing in DOCUMENT pixels. Wins over columns/rows.',
-                    minimum: 1,
-                },
-                columns: {
-                    type: 'integer',
-                    description: 'Even-division grid: number of columns (draws columns−1 interior vertical lines). E.g. 3 = rule-of-thirds verticals.',
-                    minimum: 2,
-                },
-                rows: {
-                    type: 'integer',
-                    description: 'Even-division grid: number of rows (draws rows−1 interior horizontal lines).',
-                    minimum: 2,
-                },
-                label_every: {
-                    type: 'integer',
-                    description: 'Label every k-th line to reduce clutter on dense grids. Default 1 (every line).',
-                    minimum: 1,
-                    default: 1,
-                },
-                normalized: {
-                    type: 'boolean',
-                    description: 'Also print 0.0–1.0 normalized fraction labels along the bottom/right edges — for descriptors that take normalized coordinates (e.g. some filter centers). Default false.',
-                    default: false,
-                },
-                color: {
-                    type: 'string',
-                    description: 'Hex #RRGGBB tint for the line/label bright component. Default white (with a black shadow/outline so it reads on any background).',
-                },
-                cell_labels: {
-                    type: 'boolean',
-                    description: 'Cell-label mode: divide the document into columns×rows cells (default 8×10) and label each A1/B2/… at its corner. Pick the CELL a feature is in (a reliable discrete choice) instead of reading a continuous coordinate — then zoom into that cell to refine. The legend gives the cell→pixel-region mapping. Default false.',
-                    default: false,
-                },
-            },
-        },
     },
 };
 const boundsDiffSchema = {
@@ -239,8 +197,8 @@ export function createPreviewTools(connection, snippetClient) {
     return [
         {
             tool: {
-                name: 'photoshop_get_preview',
-                description: 'Render the active Photoshop document as a flattened, downscaled image and return it inline so the calling AI can see the current visual state. Use this to verify edits visually, judge whether adjustments went too far or not far enough, and decide what to do next. Read-only with respect to the working document (renders a duplicate that is closed immediately). The optional `annotations` array draws overlays in document-space coordinates: `rectangle` / `guide` / `point` / `selection` for spatial verification (Bundle Q, 2026-06-02), and `grid` / `composition` for coordinate readout and compositional evaluation (added 2026-06-09 — grid styles `every` / `thirds` / `quarters` / `phi`, composition styles `diagonals` / `triangles` / `fibonacci_grid` / `golden_spiral`). Use spatial annotations to verify ("did the placed image land inside the frame interior?") — pass both target and actual bounds in different colors. Use grid annotations when you need to translate a visual judgment ("subject is in the lower-left third") into pixel coordinates for a downstream tool call. Use composition annotations to evaluate balance, leading lines, focal-point placement against canonical photographic frameworks. The optional `coordinate_grid` overlays a server-side LABELED grid — each line tagged with its exact document-pixel value — so you can read coordinates straight off the image before any coordinate-dense tool call (selections, point-driven filters) instead of estimating. Without annotations or a coordinate grid, behaves identically to a plain preview.',
+                name: 'ps_get_preview',
+                description: 'Render the active Photoshop document as a flattened, downscaled image and return it inline so the calling AI can see the current visual state. Use this to verify edits visually, judge whether adjustments went too far or not far enough, and decide what to do next. Read-only with respect to the working document (renders a duplicate that is closed immediately). The optional `annotations` array draws overlays in document-space coordinates: `rectangle` / `guide` / `point` / `selection` for spatial verification (Bundle Q, 2026-06-02), and `grid` / `composition` for coordinate readout and compositional evaluation (added 2026-06-09 — grid styles `every` / `thirds` / `quarters` / `phi`, composition styles `diagonals` / `triangles` / `fibonacci_grid` / `golden_spiral`). Use spatial annotations to verify ("did the placed image land inside the frame interior?") — pass both target and actual bounds in different colors. Use grid / composition annotations to EVALUATE composition (balance, thirds, leading lines, focal-point placement) — not to read a coordinate for a tool call. To place or select precisely, do NOT read a pixel off a grid (unreliable) — NAME the intent to the on-device perception tools instead: `ps_detect` (COCO objects → real document-pixel boxes), `ps_select_by_reference` (a named target → a real selection, not a guessed rectangle), plus any spatial-grounding locator / selection tools present in `tools/list`. Without annotations, behaves identically to a plain preview.',
                 inputSchema: previewSchema,
                 outputSchema: {
                     type: 'object',
@@ -250,7 +208,6 @@ export function createPreviewTools(connection, snippetClient) {
                         dimensions: { type: 'string' },
                         bytes: { type: 'number' },
                         annotation_count: { type: 'number' },
-                        coordinate_grid_applied: { type: 'boolean' },
                         context: { type: 'object' },
                     },
                 },
@@ -264,7 +221,7 @@ export function createPreviewTools(connection, snippetClient) {
         },
         {
             tool: {
-                name: 'photoshop_get_layer_bounds_diff',
+                name: 'ps_get_layer_bounds_diff',
                 description: 'Numeric verification: compute the per-edge pixel deltas between a layer\'s actual bounds and a target rectangle. Returns left/top/right/bottom deltas (actual − target), scale ratio (actual_size / target_size), centroid offset, and a one-word verdict ("aligned", "shifted right", "layer too small", etc.). Use this AFTER place_image / scale_layer / move_layer to confirm the operation produced the intended result — far more reliable than eyeballing a preview for fine alignment. Read-only. Layers nested in groups are found by name recursively. Bundle Q (2026-06-02).',
                 inputSchema: boundsDiffSchema,
                 outputSchema: {
@@ -292,7 +249,7 @@ export function createPreviewTools(connection, snippetClient) {
         },
         {
             tool: {
-                name: 'photoshop_get_histogram',
+                name: 'ps_get_histogram',
                 description: "Whole-image (or per-channel) histogram — the quantitative answer to questions get_preview can't reliably answer by eye. Returns 256 bin counts plus mean / stdev / median. Cheap (~50ms), read-only. **Reach for this when**: (a) clipping detection — bins 0 and 255 carry the count of crushed shadows / blown highlights; you can't see clipping reliably in a downsampled JPEG preview; (b) exposure verification after a levels/curves/exposure adjustment — confirm the histogram actually shifted; (c) \"is this image neutral-gray?\" — compare R / G / B channel means; (d) confirming a destructive op did anything (two identical histograms = no-op regardless of the tool's success message). Composite reads the visible flattened image (any color mode). Per-channel reads require the document have that channel.",
                 inputSchema: histogramSchema,
                 outputSchema: {
@@ -323,7 +280,7 @@ export function createPreviewTools(connection, snippetClient) {
         },
         {
             tool: {
-                name: 'photoshop_compare_regions',
+                name: 'ps_compare_regions',
                 description: 'Quantitative region comparison — the NUMERIC verification answer when "does it look right?" via get_preview is too subjective. Captures the histogram of two rectangular regions on the same document and reports per-channel mean / stdev / median for each region plus the deltas. **Reach for this when**: (a) "did the placed image match the room\'s lighting?" — sample a region of the placed image vs a region of the surrounding wall; (b) "did this adjustment do anything visible in the shadows?" — sample the same dark region before and after; (c) "is region A noticeably warmer/cooler than region B?" — read the channel means directly. Single-pixel sampling via a 1×1 rect is supported. Read-only. Bundle Q (2026-06-02).',
                 inputSchema: compareRegionsSchema,
                 outputSchema: {
@@ -795,7 +752,6 @@ async function getPreview(connection, rawArgs) {
         const maxDimension = args.max_dimension;
         const quality = args.quality;
         const annotations = args.annotations ?? [];
-        const coordinateGrid = args.coordinate_grid;
         const annotationsScript = buildAnnotationsScript(annotations);
         const dir = process.platform === 'darwin'
             ? await TempDir.createWithRoot(userOwnedTempRoot(), 'editmamei-preview-')
@@ -882,37 +838,7 @@ async function getPreview(connection, rawArgs) {
       `;
             const execTimeoutMs = annotations.length > 0 ? 90000 : undefined;
             const result = (await runScript(connection, script, execTimeoutMs));
-            let bytes = await readFile(tempPath);
-            let gridNote = '';
-            let gridApplied = false;
-            if (coordinateGrid) {
-                const doc = result?.context
-                    ?.document;
-                if (typeof doc?.width === 'number' && typeof doc?.height === 'number') {
-                    try {
-                        const grid = overlayCoordinateGrid(bytes, {
-                            docWidth: doc.width,
-                            docHeight: doc.height,
-                            stepPx: coordinateGrid.step_px,
-                            columns: coordinateGrid.columns,
-                            rows: coordinateGrid.rows,
-                            labelEvery: coordinateGrid.label_every,
-                            normalized: coordinateGrid.normalized,
-                            color: coordinateGrid.color,
-                            cellLabels: coordinateGrid.cell_labels,
-                        });
-                        bytes = grid.jpeg;
-                        gridNote = ` ${grid.legend}`;
-                        gridApplied = true;
-                    }
-                    catch (gridErr) {
-                        gridNote = ` (coordinate grid skipped: ${gridErr instanceof Error ? gridErr.message : String(gridErr)})`;
-                    }
-                }
-                else {
-                    gridNote = ' (coordinate grid skipped: document dimensions unavailable)';
-                }
-            }
+            const bytes = await readFile(tempPath);
             const base64 = bytes.toString('base64');
             const dims = result?.width_px && result?.height_px
                 ? `${result.width_px}x${result.height_px}`
@@ -924,7 +850,7 @@ async function getPreview(connection, rawArgs) {
                     { type: 'image', data: base64, mimeType: 'image/jpeg' },
                     {
                         type: 'text',
-                        text: `Preview rendered (JPEG, ${dims}, ${formatBytes(bytes.length)}${annNote}). This is the current flattened state of the active document.${gridNote}`,
+                        text: `Preview rendered (JPEG, ${dims}, ${formatBytes(bytes.length)}${annNote}). This is the current flattened state of the active document.`,
                     },
                 ],
                 structuredContent: {
@@ -933,7 +859,6 @@ async function getPreview(connection, rawArgs) {
                     dimensions: dims,
                     bytes: bytes.length,
                     annotation_count: annotationCount,
-                    coordinate_grid_applied: gridApplied,
                     context: result?.context,
                 },
             };

package/dist/tools/retouch-tools.js

@@ -1,5 +1,23 @@
 import { runScript } from '../utils/run-script.js';
 import { validateArgs } from '../utils/validate.js';
+import { resolveExpectedPlacement, PLACEMENT_SCHEMA } from '../perception/grounding-locate.js';
+import { OnnxDetectionClient } from '../detection/detection-client.js';
+async function groundedOffset(connection, snippetClient, detClient, placement, label) {
+    const rp = await resolveExpectedPlacement(connection, detClient, placement, 'point', label);
+    const sel = (await runScript(connection, await snippetClient.build('getSelectionState')));
+    if (!sel.has_selection || !sel.bounds)
+        throw new Error(`${label} needs an active selection to move relative to — none found. Make the selection first.`);
+    const center = {
+        x: (sel.bounds.left + sel.bounds.right) / 2,
+        y: (sel.bounds.top + sel.bounds.bottom) / 2,
+    };
+    return {
+        offsetX: Math.round(rp.point.x - center.x),
+        offsetY: Math.round(rp.point.y - center.y),
+        point: rp.point,
+        center: { x: Math.round(center.x), y: Math.round(center.y) },
+    };
+}
 const APPLY_TO_ACTIVE_LAYER_PROP = {
     type: 'boolean',
     description: 'If false (default), the retouch op is applied to a duplicate of the active layer named "<OpName> (<Original Name>)" — the original is preserved and the LLM can undo by deleting the copy. If true, the op bakes directly into the active layer.',
@@ -62,13 +80,17 @@ const contentAwareFillSchema = {
 const patchSchema = {
     type: 'object',
     properties: {
+        source_placement: {
+            ...PLACEMENT_SCHEMA,
+            description: 'Grounded alternative to offset_x/offset_y: NAME the patch SOURCE (resolves to a POINT via the grounding resolver + objective gate — e.g. an extremum for the cleanest nearby skin, a grid intersection). The offset from the selection center to that point is computed for you. Wins over offset_x/offset_y. Provide THIS or offset_x + offset_y.',
+        },
         offset_x: {
             type: 'number',
-            description: 'Horizontal pixel offset from the selection to the patch source. Positive = source is to the right. Required.',
+            description: 'Horizontal pixel offset from the selection to the patch source. Positive = source is to the right. Required unless source_placement is given.',
         },
         offset_y: {
             type: 'number',
-            description: 'Vertical pixel offset from the selection to the patch source. Positive = source is below. Required.',
+            description: 'Vertical pixel offset from the selection to the patch source. Positive = source is below. Required unless source_placement is given.',
         },
         patch_structure: {
             type: 'integer',
@@ -108,18 +130,21 @@ const patchSchema = {
         },
         apply_to_active_layer: APPLY_TO_ACTIVE_LAYER_PROP,
     },
-    required: ['offset_x', 'offset_y'],
 };
 const contentAwareMoveSchema = {
     type: 'object',
     properties: {
+        destination_placement: {
+            ...PLACEMENT_SCHEMA,
+            description: 'Grounded alternative to offset_x/offset_y: NAME where to move the selection (resolves to a POINT via the grounding resolver + objective gate — a grid intersection, an object centroid, an extremum). The selection center is moved ONTO that point; the offset is computed for you. Wins over offset_x/offset_y. Provide THIS or offset_x + offset_y.',
+        },
         offset_x: {
             type: 'number',
-            description: 'Horizontal pixel delta to move the selected content. Positive = right.',
+            description: 'Horizontal pixel delta to move the selected content. Positive = right. Required unless destination_placement is given.',
         },
         offset_y: {
             type: 'number',
-            description: 'Vertical pixel delta to move the selected content. Positive = down.',
+            description: 'Vertical pixel delta to move the selected content. Positive = down. Required unless destination_placement is given.',
         },
         patch_structure: {
             type: 'integer',
@@ -159,7 +184,6 @@ const contentAwareMoveSchema = {
         },
         apply_to_active_layer: APPLY_TO_ACTIVE_LAYER_PROP,
     },
-    required: ['offset_x', 'offset_y'],
 };
 const RETOUCH_OUTPUT_SCHEMA = {
     type: 'object',
@@ -217,11 +241,21 @@ async function applyContentAwareFill(connection, snippetClient, rawArgs) {
         };
     }
 }
-async function applyPatch(connection, snippetClient, rawArgs) {
+async function applyPatch(connection, snippetClient, detClient, rawArgs) {
     try {
         const args = validateArgs(patchSchema, rawArgs);
-        const offsetX = args.offset_x;
-        const offsetY = args.offset_y;
+        let offsetX = args.offset_x;
+        let offsetY = args.offset_y;
+        let grounded;
+        if (args.source_placement) {
+            const g = await groundedOffset(connection, snippetClient, detClient, args.source_placement, 'patch source');
+            offsetX = g.offsetX;
+            offsetY = g.offsetY;
+            grounded = { point: g.point, center: g.center };
+        }
+        else if (offsetX === undefined || offsetY === undefined) {
+            throw new Error('provide offset_x + offset_y, or source_placement to NAME the patch source region.');
+        }
         const patchStructure = args.patch_structure ?? 5;
         const patchColor = args.patch_color ?? 5;
         const healSmoothFactor = args.heal_smooth_factor ?? 5;
@@ -245,14 +279,26 @@ async function applyPatch(connection, snippetClient, rawArgs) {
         const target = r.target_was_copy
             ? `new copy "${r.target_layer_name ?? '?'}"`
             : 'active layer (in place)';
+        const groundedNote = grounded
+            ? ` — source at (${Math.round(grounded.point.x)},${Math.round(grounded.point.y)}) via placement (gate PASS)`
+            : '';
+        const structured = result;
+        if (grounded) {
+            structured.source_placement = {
+                gate: { pass: true },
+                point: { x: Math.round(grounded.point.x), y: Math.round(grounded.point.y) },
+                selection_center: grounded.center,
+                offset: { x: offsetX, y: offsetY },
+            };
+        }
         return {
             content: [
                 {
                     type: 'text',
-                    text: `Patch applied to ${target} (offset ${offsetX}, ${offsetY}; structure ${patchStructure}, color ${patchColor}).`,
+                    text: `Patch applied to ${target} (offset ${offsetX}, ${offsetY}; structure ${patchStructure}, color ${patchColor})${groundedNote}.`,
                 },
             ],
-            structuredContent: result,
+            structuredContent: structured,
         };
     }
     catch (error) {
@@ -267,11 +313,21 @@ async function applyPatch(connection, snippetClient, rawArgs) {
         };
     }
 }
-async function applyContentAwareMove(connection, snippetClient, rawArgs) {
+async function applyContentAwareMove(connection, snippetClient, detClient, rawArgs) {
     try {
         const args = validateArgs(contentAwareMoveSchema, rawArgs);
-        const offsetX = args.offset_x;
-        const offsetY = args.offset_y;
+        let offsetX = args.offset_x;
+        let offsetY = args.offset_y;
+        let grounded;
+        if (args.destination_placement) {
+            const g = await groundedOffset(connection, snippetClient, detClient, args.destination_placement, 'content-aware move');
+            offsetX = g.offsetX;
+            offsetY = g.offsetY;
+            grounded = { point: g.point, center: g.center };
+        }
+        else if (offsetX === undefined || offsetY === undefined) {
+            throw new Error('provide offset_x + offset_y, or destination_placement to NAME where to move the selection.');
+        }
         const patchStructure = args.patch_structure ?? 4;
         const patchColor = args.patch_color ?? 5;
         const healSmoothFactor = args.heal_smooth_factor ?? 5;
@@ -295,14 +351,26 @@ async function applyContentAwareMove(connection, snippetClient, rawArgs) {
         const target = r.target_was_copy
             ? `new copy "${r.target_layer_name ?? '?'}"`
             : 'active layer (in place)';
+        const groundedNote = grounded
+            ? ` — moved onto (${Math.round(grounded.point.x)},${Math.round(grounded.point.y)}) via placement (gate PASS)`
+            : '';
+        const structured = result;
+        if (grounded) {
+            structured.destination_placement = {
+                gate: { pass: true },
+                point: { x: Math.round(grounded.point.x), y: Math.round(grounded.point.y) },
+                selection_center: grounded.center,
+                offset: { x: offsetX, y: offsetY },
+            };
+        }
         return {
             content: [
                 {
                     type: 'text',
-                    text: `Content-Aware Move applied to ${target} (delta ${offsetX}, ${offsetY}).`,
+                    text: `Content-Aware Move applied to ${target} (delta ${offsetX}, ${offsetY})${groundedNote}.`,
                 },
             ],
-            structuredContent: result,
+            structuredContent: structured,
         };
     }
     catch (error) {
@@ -326,8 +394,8 @@ const RETOUCH_INPUT_SCHEMA = {
             enum: [...RETOUCH_METHODS],
             description: 'Retouch technique (all require an active selection). ' +
                 'content_aware_fill: synthesize a fill from surrounding content (color_adaptation, opacity, blend_mode, rotate/scale/mirror). ' +
-                'patch: offset_x + offset_y REQUIRED — sample replacement pixels from that offset (patch_structure 1-7, patch_color 0-10, use_source). ' +
-                'content_aware_move: offset_x + offset_y REQUIRED — relocate the selection and fill the source (patch_structure, reshuffle).',
+                'patch: sample replacement pixels — offset_x + offset_y, OR source_placement to NAME the clean source region (patch_structure 1-7, patch_color 0-10, use_source). ' +
+                'content_aware_move: relocate the selection and fill the source — offset_x + offset_y, OR destination_placement to NAME where to move it (patch_structure, reshuffle).',
         },
         ...contentAwareFillSchema.properties,
         ...patchSchema.properties,
@@ -335,12 +403,12 @@ const RETOUCH_INPUT_SCHEMA = {
     },
     required: ['method'],
 };
-export function createRetouchTools(connection, snippetClient) {
+export function createRetouchTools(connection, snippetClient, detClient = new OnnxDetectionClient()) {
     return [
         {
             tool: {
-                name: 'photoshop_retouch',
-                description: 'Selection-driven content-aware retouch — choose the technique with `method`. Requires an active selection (throws if none, so Content-Aware Fill never silently fills the whole layer). Auto-duplicates the active layer by default so the original is preserved (auto-duplicate-first per Bundle O); pass `apply_to_active_layer: true` to bake into the original. `content_aware_fill` synthesizes a fill from surroundings (remove wires/objects/blemishes); `patch` samples replacement pixels from a chosen offset (skin retouch, known-clean source); `content_aware_move` relocates the selection and fills the source (reposition a subject without manual compositing).',
+                name: 'ps_retouch',
+                description: 'Selection-driven content-aware retouch — choose the technique with `method`. Requires an active selection (throws if none, so Content-Aware Fill never silently fills the whole layer). Auto-duplicates the active layer by default so the original is preserved (auto-duplicate-first per Bundle O); pass `apply_to_active_layer: true` to bake into the original. `content_aware_fill` synthesizes a fill from surroundings (remove wires/objects/blemishes); `patch` samples replacement pixels from a chosen offset — or NAME the source region with `source_placement` (grounded + gated); `content_aware_move` relocates the selection and fills the source — offset, or NAME where with `destination_placement`.',
                 inputSchema: RETOUCH_INPUT_SCHEMA,
                 outputSchema: RETOUCH_OUTPUT_SCHEMA,
                 annotations: {
@@ -349,20 +417,20 @@ export function createRetouchTools(connection, snippetClient) {
                     idempotentHint: false,
                 },
             },
-            handler: async (args) => retouch(connection, snippetClient, args),
+            handler: async (args) => retouch(connection, snippetClient, detClient, args),
         },
     ];
 }
-async function retouch(connection, snippetClient, rawArgs) {
+async function retouch(connection, snippetClient, detClient, rawArgs) {
     const method = rawArgs.method;
     const { method: _omit, ...rest } = rawArgs;
     switch (method) {
         case 'content_aware_fill':
             return applyContentAwareFill(connection, snippetClient, rest);
         case 'patch':
-            return applyPatch(connection, snippetClient, rest);
+            return applyPatch(connection, snippetClient, detClient, rest);
         case 'content_aware_move':
-            return applyContentAwareMove(connection, snippetClient, rest);
+            return applyContentAwareMove(connection, snippetClient, detClient, rest);
         default:
             return {
                 content: [

package/dist/tools/scene-tools.js

@@ -9,7 +9,7 @@ function makeProRefine(invokeTool) {
         try {
             if (req.kind === 'subject') {
                 const which = typeof req.instance === 'number' ? String(req.instance) : 'largest';
-                const res = await invokeTool('photoshop_select_subject_instance', {
+                const res = await invokeTool('ps_select_subject_instance', {
                     label: req.label,
                     which,
                     save_as: 'selection',
@@ -17,7 +17,7 @@ function makeProRefine(invokeTool) {
                 return res.isError !== true;
             }
             const feature = req.kind === 'face' ? 'face' : req.feature;
-            const res = await invokeTool('photoshop_select_face_feature', {
+            const res = await invokeTool('ps_select_face_feature', {
                 feature,
                 which: 'best',
                 save_as: 'selection',
@@ -32,7 +32,7 @@ function makeProRefine(invokeTool) {
 function makePrecomputeFace(invokeTool) {
     return async () => {
         try {
-            const res = await invokeTool('photoshop_select_face_feature', { precompute_all: true });
+            const res = await invokeTool('ps_select_face_feature', { precompute_all: true });
             if (res.isError)
                 return [];
             const saved = res.structuredContent?.saved ?? [];
@@ -73,11 +73,11 @@ const sceneSchema = {
         save_regions: {
             type: 'boolean',
             default: true,
-            description: 'Precompute every confident region (sky/ground/shadows/highlights/skin/subject/face — and, on a Pro host with a face, the face-feature set scene:face_skin/_eyes/_brows/_lips/_teeth/_nose/_under_eye/_cheeks) and SAVE each as a managed `scene:*` alpha channel, returning the `regions` MENU of what is confidently selectable (each with its method + confidence). photoshop_select_by_reference then loads the saved channel instantly. Set false for a light read with no channels.',
+            description: 'Precompute every confident region (sky/ground/shadows/highlights/skin/subject/face — and, on a Pro host with a face, the face-feature set scene:face_skin/_eyes/_brows/_lips/_teeth/_nose/_under_eye/_cheeks) and SAVE each as a managed `scene:*` alpha channel, returning the `regions` MENU of what is confidently selectable (each with its method + confidence). ps_select_by_reference then loads the saved channel instantly. Set false for a light read with no channels.',
         },
         composition_context: {
             type: 'object',
-            description: 'Optional: tune the confidence gate for an artistic/non-standard composition (e.g. profile:big_sky) so a legitimately large region is not rejected. Same shape as photoshop_select_by_reference.',
+            description: 'Optional: tune the confidence gate for an artistic/non-standard composition (e.g. profile:big_sky) so a legitimately large region is not rejected. Same shape as ps_select_by_reference.',
             properties: {
                 profile: {
                     type: 'string',
@@ -149,7 +149,7 @@ function summarizeScene(model) {
     ];
     if (main && cell)
         parts.push(`main subject in the ${cell.row}-${cell.col} third`);
-    return `Scene (${model.doc.width}×${model.doc.height}): ${parts.join('; ')}. Select named regions with photoshop_select_by_reference.`;
+    return `Scene (${model.doc.width}×${model.doc.height}): ${parts.join('; ')}. Select named regions with ps_select_by_reference.`;
 }
 async function scene(connection, snippet, client, rawArgs, proRefine, precomputeFace) {
     try {
@@ -284,7 +284,7 @@ async function selectByReference(connection, snippet, client, rawArgs, proRefine
                     content: [
                         {
                             type: 'text',
-                            text: `Selected "${target}" from the saved scene:${target} channel (precomputed by photoshop_scene). Verify with photoshop_get_selection_preview.`,
+                            text: `Selected "${target}" from the saved scene:${target} channel (precomputed by ps_read_scene). Verify with ps_get_selection_preview.`,
                         },
                     ],
                     structuredContent: {
@@ -314,7 +314,7 @@ async function selectByReference(connection, snippet, client, rawArgs, proRefine
         });
         const conf = res.confidence.toFixed(2);
         const summary = res.passed
-            ? `Selected "${target}" via ${res.method} (confidence ${conf}). Verify with photoshop_get_selection_preview.`
+            ? `Selected "${target}" via ${res.method} (confidence ${conf}). Verify with ps_get_selection_preview.`
             : `No confident "${target}" in this image (confidence ${conf}, below the gate) — nothing selected. ${res.reasons.join('; ')}. If this is an artistic/non-standard composition, pass composition_context to relax the prior.`;
         return {
             content: [{ type: 'text', text: summary }],
@@ -334,7 +334,7 @@ async function selectByReference(connection, snippet, client, rawArgs, proRefine
     catch (error) {
         const msg = error instanceof Error ? error.message : String(error);
         return {
-            content: [{ type: 'text', text: `Error in photoshop_select_by_reference: ${msg}` }],
+            content: [{ type: 'text', text: `Error in ps_select_by_reference: ${msg}` }],
             isError: true,
         };
     }
@@ -345,8 +345,8 @@ export function createSceneTools(connection, snippetClient, client = new OnnxDet
     return [
         {
             tool: {
-                name: 'photoshop_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 photoshop_select_by_reference instead of guessing a rectangle. Perception is cached per document state, so repeated reads are cheap.',
+                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.',
                 inputSchema: sceneSchema,
                 outputSchema: {
                     type: 'object',
@@ -372,8 +372,8 @@ export function createSceneTools(connection, snippetClient, client = new OnnxDet
         },
         {
             tool: {
-                name: 'photoshop_select_by_reference',
-                description: 'Select a region by NAME instead of coordinates — the natural-mask alternative to a rectangle — with a CONFIDENCE GATE. target=sky/ground/foliage/subject/face/shadows/highlights/skin/above_horizon resolves through the right Photoshop-native method (threshold for sky, invert-sky−subjects for ground, luminance for shadows/highlights, skin-tone colour ∩ the subject box, the detected face/subject box) and is SCORED before it is offered: a clean region is left selected; an unconfident one is NOT selected and reported as honest absence (the city with no real sky gets no sky). Pro adds precise FACE-FEATURE targets backed by the face mesh — face_skin (the retouch mask: face minus eyes/brows/lips), face_eyes, face_brows, face_lips, face_teeth (mouth opening), face_nose, face_under_eye, face_cheeks — each a real geometry-following selection, loaded instantly from the scene:face_* channel photoshop_scene precomputes. `passed`/`confidence` are returned. The structural floor (coherence, horizon alignment) is never tuned; for an artistic/non-standard shot pass `composition_context` (e.g. profile:big_sky) to relax the compositional priors so a legitimately large sky is not rejected. For target=subject with several present, pass `label` and/or `instance`. Build/inspect with photoshop_scene first; verify with photoshop_get_selection_preview (the red-overlay is the human/agent oversight view). Prefer this over a rectangle for any real-world region.',
+                name: 'ps_select_by_reference',
+                description: 'Select a region by NAME instead of coordinates — the natural-mask alternative to a rectangle — with a CONFIDENCE GATE. target=sky/ground/foliage/subject/face/shadows/highlights/skin/above_horizon resolves through the right Photoshop-native method (threshold for sky, invert-sky−subjects for ground, luminance for shadows/highlights, skin-tone colour ∩ the subject box, the detected face/subject box) and is SCORED before it is offered: a clean region is left selected; an unconfident one is NOT selected and reported as honest absence (the city with no real sky gets no sky). Pro adds precise FACE-FEATURE targets backed by the face mesh — face_skin (the retouch mask: face minus eyes/brows/lips), face_eyes, face_brows, face_lips, face_teeth (mouth opening), face_nose, face_under_eye, face_cheeks — each a real geometry-following selection, loaded instantly from the scene:face_* channel ps_read_scene precomputes. `passed`/`confidence` are returned. The structural floor (coherence, horizon alignment) is never tuned; for an artistic/non-standard shot pass `composition_context` (e.g. profile:big_sky) to relax the compositional priors so a legitimately large sky is not rejected. For target=subject with several present, pass `label` and/or `instance`. Build/inspect with ps_read_scene first; verify with ps_get_selection_preview (the red-overlay is the human/agent oversight view). Prefer this over a rectangle for any real-world region.',
                 inputSchema: selectByReferenceSchema,
                 outputSchema: {
                     type: 'object',