editmamei 0.20.0 → 0.22.0

package/dist/tools/layer-transform-tools.js

@@ -1,5 +1,7 @@
 import { runScript } from '../utils/run-script.js';
 import { validateArgs } from '../utils/validate.js';
+import { OnnxLandmarkDetectionClient } from '../detection/landmark-detection-client.js';
+import { resolveExpectedPlacement, PLACEMENT_SCHEMA } from '../perception/grounding-locate.js';
 const fitLayerToDocumentSchema = {
     type: 'object',
     properties: {
@@ -74,6 +76,13 @@ const moveLayerSchema = {
             type: 'number',
             description: "CENTER mode: target Y for the layer's bounds CENTER point, in document pixels. Pair with center_on_x.",
         },
+        placement: {
+            ...PLACEMENT_SCHEMA,
+            description: 'ANCHOR-RELATIONAL move (preferred over guessing a pixel): a POINT relation (centroid/midpoint/offset) → ' +
+                'the layer\'s CENTER is moved to the resolved, gate-verified point (e.g. "center this layer on the detected ' +
+                'subject" / "…in the gap between the two people"). Moves ONLY if the gate PASSES. When set, delta_*/' +
+                'absolute_*/center_on_* are ignored. See ps_resolve_placement for the anchors + relation vocabulary.',
+        },
     },
 };
 const rotateLayerSchema = {
@@ -157,12 +166,12 @@ const TRANSFORM_INPUT_SCHEMA = {
     },
     required: ['op'],
 };
-export function createLayerTransformTools(connection, snippetClient) {
+export function createLayerTransformTools(connection, snippetClient, client = new OnnxLandmarkDetectionClient()) {
     return [
         {
             tool: {
-                name: 'photoshop_transform_layer',
-                description: 'Transform the active layer — choose the operation with `op`. `fit` scales to fit (letterbox) or fill (crop) the canvas and centers (idempotent). `scale` does uniform (scale_percent) or non-uniform stretch/squash (scale_x_percent/scale_y_percent) — multiplicative, not idempotent. `move` translates via exactly one of delta (relative), absolute (top-left target), or center_on (center target — best for "place inside the frame opening"); mixing modes errors. `rotate` rotates by relative degrees around center. `flip` mirrors horizontal/vertical. `skew` slants the layer (skew_h_degrees/skew_v_degrees). `free` is a numeric free-transform (scale + degrees + offset). scale/move/rotate/flip/skew/free auto-promote the background layer (background_promoted=true).',
+                name: 'ps_transform_layer',
+                description: 'Transform the active layer — choose the operation with `op`. `fit` scales to fit (letterbox) or fill (crop) the canvas and centers (idempotent). `scale` does uniform (scale_percent) or non-uniform stretch/squash (scale_x_percent/scale_y_percent) — multiplicative, not idempotent. `move` translates via exactly one of delta (relative), absolute (top-left target), center_on (center target — best for "place inside the frame opening"), or an anchor-relational `placement` (preferred: a point relation → the layer center moves to the resolved, gate-verified point); mixing the raw modes errors. `rotate` rotates by relative degrees around center. `flip` mirrors horizontal/vertical. `skew` slants the layer (skew_h_degrees/skew_v_degrees). `free` is a numeric free-transform (scale + degrees + offset). scale/move/rotate/flip/skew/free auto-promote the background layer (background_promoted=true).',
                 inputSchema: TRANSFORM_INPUT_SCHEMA,
                 outputSchema: {
                     type: 'object',
@@ -190,6 +199,16 @@ export function createLayerTransformTools(connection, snippetClient) {
                         applied_delta_y: { type: 'number' },
                         new_bounds: { type: 'object' },
                         background_promoted: { type: 'boolean' },
+                        placement: {
+                            type: 'object',
+                            description: 'Present when op=move used anchor-relational placement: the resolved point + gate verdict.',
+                            properties: {
+                                target: { type: 'string' },
+                                gate: { type: 'object' },
+                                anchors: { type: 'object' },
+                                geometry: { type: 'object' },
+                            },
+                        },
                         context: { type: 'object' },
                     },
                 },
@@ -198,11 +217,11 @@ export function createLayerTransformTools(connection, snippetClient) {
                     idempotentHint: false,
                 },
             },
-            handler: async (args) => transformLayer(connection, snippetClient, args),
+            handler: async (args) => transformLayer(connection, snippetClient, client, args),
         },
     ];
 }
-async function transformLayer(connection, snippetClient, rawArgs) {
+async function transformLayer(connection, snippetClient, client, rawArgs) {
     const op = rawArgs.op;
     const { op: _omit, ...rest } = rawArgs;
     switch (op) {
@@ -211,7 +230,7 @@ async function transformLayer(connection, snippetClient, rawArgs) {
         case 'scale':
             return scaleLayer(connection, snippetClient, rest);
         case 'move':
-            return moveLayer(connection, snippetClient, rest);
+            return moveLayer(connection, snippetClient, client, rest);
         case 'rotate':
             return rotateLayer(connection, snippetClient, rest);
         case 'flip':
@@ -338,39 +357,47 @@ async function flipLayer(connection, snippetClient, rawArgs) {
         };
     }
 }
-async function moveLayer(connection, snippetClient, rawArgs) {
+async function moveLayer(connection, snippetClient, client, rawArgs) {
     try {
         const args = validateArgs(moveLayerSchema, rawArgs);
-        const hasDelta = args.delta_x !== undefined || args.delta_y !== undefined;
-        const hasAbsolute = args.absolute_x !== undefined || args.absolute_y !== undefined;
-        const hasCenter = args.center_on_x !== undefined || args.center_on_y !== undefined;
-        const modeCount = (hasDelta ? 1 : 0) + (hasAbsolute ? 1 : 0) + (hasCenter ? 1 : 0);
-        if (modeCount === 0) {
-            throw new Error('No positioning mode specified. Pass exactly one pair: delta_x+delta_y (relative), absolute_x+absolute_y (target top-left), or center_on_x+center_on_y (target center).');
-        }
-        if (modeCount > 1) {
-            throw new Error('Mixed positioning modes. Pass exactly ONE pair: delta_x+delta_y OR absolute_x+absolute_y OR center_on_x+center_on_y.');
-        }
-        if (hasDelta && (args.delta_x === undefined || args.delta_y === undefined)) {
-            throw new Error('Delta mode requires both delta_x and delta_y.');
+        let mode;
+        let deltaX = 0, deltaY = 0, absoluteX = 0, absoluteY = 0, centerOnX = 0, centerOnY = 0;
+        let placementInfo;
+        if (args.placement) {
+            const rp = await resolveExpectedPlacement(connection, client, args.placement, 'point', 'move');
+            mode = 'center';
+            centerOnX = rp.point.x;
+            centerOnY = rp.point.y;
+            placementInfo = { target: rp.target, anchors: rp.anchors, point: rp.point };
         }
-        if (hasAbsolute && (args.absolute_x === undefined || args.absolute_y === undefined)) {
-            throw new Error('Absolute mode requires both absolute_x and absolute_y.');
-        }
-        if (hasCenter && (args.center_on_x === undefined || args.center_on_y === undefined)) {
-            throw new Error('Center mode requires both center_on_x and center_on_y.');
+        else {
+            const hasDelta = args.delta_x !== undefined || args.delta_y !== undefined;
+            const hasAbsolute = args.absolute_x !== undefined || args.absolute_y !== undefined;
+            const hasCenter = args.center_on_x !== undefined || args.center_on_y !== undefined;
+            const modeCount = (hasDelta ? 1 : 0) + (hasAbsolute ? 1 : 0) + (hasCenter ? 1 : 0);
+            if (modeCount === 0) {
+                throw new Error('No positioning mode specified. Pass a placement (anchors + a point relation), or exactly one pair: delta_x+delta_y (relative), absolute_x+absolute_y (target top-left), or center_on_x+center_on_y (target center).');
+            }
+            if (modeCount > 1) {
+                throw new Error('Mixed positioning modes. Pass exactly ONE pair: delta_x+delta_y OR absolute_x+absolute_y OR center_on_x+center_on_y.');
+            }
+            if (hasDelta && (args.delta_x === undefined || args.delta_y === undefined)) {
+                throw new Error('Delta mode requires both delta_x and delta_y.');
+            }
+            if (hasAbsolute && (args.absolute_x === undefined || args.absolute_y === undefined)) {
+                throw new Error('Absolute mode requires both absolute_x and absolute_y.');
+            }
+            if (hasCenter && (args.center_on_x === undefined || args.center_on_y === undefined)) {
+                throw new Error('Center mode requires both center_on_x and center_on_y.');
+            }
+            mode = hasAbsolute ? 'absolute' : hasCenter ? 'center' : 'delta';
+            deltaX = args.delta_x ?? 0;
+            deltaY = args.delta_y ?? 0;
+            absoluteX = args.absolute_x ?? 0;
+            absoluteY = args.absolute_y ?? 0;
+            centerOnX = args.center_on_x ?? 0;
+            centerOnY = args.center_on_y ?? 0;
         }
-        const mode = hasAbsolute
-            ? 'absolute'
-            : hasCenter
-                ? 'center'
-                : 'delta';
-        const deltaX = args.delta_x ?? 0;
-        const deltaY = args.delta_y ?? 0;
-        const absoluteX = args.absolute_x ?? 0;
-        const absoluteY = args.absolute_y ?? 0;
-        const centerOnX = args.center_on_x ?? 0;
-        const centerOnY = args.center_on_y ?? 0;
         const script = await snippetClient.build('moveLayer', {
             deltaX,
             deltaY,
@@ -381,11 +408,13 @@ async function moveLayer(connection, snippetClient, rawArgs) {
             centerOnY,
         });
         const result = (await runScript(connection, script));
-        const summary = mode === 'delta'
-            ? `Layer moved by (${deltaX}, ${deltaY})px (relative)`
-            : mode === 'absolute'
-                ? `Layer top-left moved to (${absoluteX}, ${absoluteY})px — applied delta (${result.applied_delta_x ?? '?'}, ${result.applied_delta_y ?? '?'})`
-                : `Layer center moved to (${centerOnX}, ${centerOnY})px — applied delta (${result.applied_delta_x ?? '?'}, ${result.applied_delta_y ?? '?'})`;
+        const summary = placementInfo
+            ? `Layer center moved to (${centerOnX}, ${centerOnY})px via placement (gate PASS) — applied delta (${result.applied_delta_x ?? '?'}, ${result.applied_delta_y ?? '?'})`
+            : mode === 'delta'
+                ? `Layer moved by (${deltaX}, ${deltaY})px (relative)`
+                : mode === 'absolute'
+                    ? `Layer top-left moved to (${absoluteX}, ${absoluteY})px — applied delta (${result.applied_delta_x ?? '?'}, ${result.applied_delta_y ?? '?'})`
+                    : `Layer center moved to (${centerOnX}, ${centerOnY})px — applied delta (${result.applied_delta_x ?? '?'}, ${result.applied_delta_y ?? '?'})`;
         const bgNote = result.background_promoted ? ' (background layer auto-promoted)' : '';
         return {
             content: [
@@ -394,7 +423,17 @@ async function moveLayer(connection, snippetClient, rawArgs) {
                     text: `${summary}${bgNote}\nResult: ${JSON.stringify(result)}`,
                 },
             ],
-            structuredContent: result,
+            structuredContent: placementInfo
+                ? {
+                    ...result,
+                    placement: {
+                        target: placementInfo.target,
+                        gate: { pass: true },
+                        anchors: placementInfo.anchors,
+                        geometry: placementInfo.point,
+                    },
+                }
+                : result,
         };
     }
     catch (error) {

package/dist/tools/overview-tools.js

@@ -9,26 +9,26 @@ already know which tool fits.
 
 If you reference a tool by name that isn't in your \`tools/list\`,
 work around it — don't speculate that it's there. The discovery chain
-is \`photoshop_ping\` (liveness) → this overview (workflow) →
-\`photoshop_list_capabilities\` (a compact, live map of what exists,
+is \`ps_ping\` (liveness) → this overview (workflow) →
+\`ps_list_capabilities\` (a compact, live map of what exists,
 grouped by capability) → \`tools/list\` (full schemas).
 
 ## The workflow contract
 
 Every non-trivial edit follows the same six phases:
 
-1. **Assess** — \`photoshop_inspect\` (what=metadata / layer_tree / history /
-   selection_info) + \`photoshop_get_preview\` to understand what you're working with.
+1. **Assess** — \`ps_inspect\` (what=metadata / layer_tree / history /
+   selection_info) + \`ps_get_preview\` to understand what you're working with.
 2. **Plan** — name the intent, the layers/regions involved, and the
    exit criteria. Tell the user before you execute.
 3. **Enact** — call the tools.
-4. **Check** — \`photoshop_get_preview\` after every load-bearing change.
+4. **Check** — \`ps_get_preview\` after every load-bearing change.
    For spatial questions ("is this aligned?"), use annotations or
-   \`photoshop_get_layer_bounds_diff\` — see Verification below.
+   \`ps_get_layer_bounds_diff\` — see Verification below.
 5. **Iterate** — up to 3 correction loops. If the third attempt still
    misses, surface the gap to the user instead of looping further.
-6. **Finish** — \`photoshop_export\` (format jpeg/png) /
-   \`photoshop_save_psd\`. Confirm the user wants to flatten before
+6. **Finish** — \`ps_export\` (format jpeg/png) /
+   \`ps_save_psd\`. Confirm the user wants to flatten before
    destructive saves.
 
 ## Capabilities map
@@ -36,61 +36,61 @@ Every non-trivial edit follows the same six phases:
 This map covers the workflow categories. For specific tool names and
 schemas in this session, consult \`tools/list\`.
 
-- **Adjustments (non-destructive)** — \`photoshop_add_adjustment_layer\`
+- **Adjustments (non-destructive)** — \`ps_add_adjustment_layer\`
   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)** — \`photoshop_apply_filter\` with a
+- **Filters (destructive)** — \`ps_apply_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
   the original is preserved (\`target_was_copy: true\` in the response);
   pass \`apply_to_active_layer: true\` only when the user explicitly
   wants to bake into the original. Destructive tonal bakes with no
-  adjustment-layer equivalent live in \`photoshop_apply_adjustment\`
+  adjustment-layer equivalent live in \`ps_apply_adjustment\`
   (type shadows_highlights / equalize / color_lookup).
 - **Layers** — create / delete / duplicate / select / rasterize /
-  convert-to-smart-object / add layer style, plus \`photoshop_set_layer\`
+  convert-to-smart-object / add layer style, plus \`ps_set_layer\`
   (property opacity / blend_mode / visibility / locked / name),
-  \`photoshop_merge\` (mode visible / stamp / flatten), and
-  \`photoshop_transform_layer\` (op move / rotate / scale / fit / flip —
+  \`ps_merge\` (mode visible / stamp / flatten), and
+  \`ps_transform_layer\` (op move / rotate / scale / fit / flip —
   auto-promotes the background layer, so you don't have to duplicate
   first).
-- **Masks** — \`photoshop_layer_mask\` (op create / delete / apply).
+- **Masks** — \`ps_layer_mask\` (op create / delete / apply).
   \`op: "create"\` automatically uses the current selection if one is
   active (reveals selection, hides outside); with no selection it
   creates a reveal-all mask. This is the right tool for "mask the placed
   image to the frame opening" — make the selection first, then call it.
   Don't write \`Mk Chnl At=Msk\` AM scripts for this — it's a one-call
-  native. For VECTOR masks + work paths, see \`photoshop_vector_mask\`
-  (op add / delete / link / unlink) and \`photoshop_path\`
+  native. For VECTOR masks + work paths, see \`ps_vector_mask\`
+  (op add / delete / link / unlink) and \`ps_path\`
   (selection↔path round-trip, stroke / fill / clip).
-- **Selection** — \`photoshop_select\` (mode rectangle / color_range /
+- **Selection** — \`ps_select\` (mode rectangle / color_range /
   luminance_range / magic_wand / all / none / inverse),
-  \`photoshop_modify_selection\` (op feather / refine_edge),
-  \`photoshop_selection_channel\` (op save / load),
-  \`photoshop_inspect\` (what=selection_info), \`photoshop_get_selection_preview\`.
+  \`ps_modify_selection\` (op feather / refine_edge),
+  \`ps_selection_channel\` (op save / load),
+  \`ps_inspect\` (what=selection_info), \`ps_get_selection_preview\`.
   Smart-selection (AI subject / sky) helpers may be available in
   \`tools/list\` — check there.
-- **Perception (on-device CV)** — \`photoshop_detect\` (faces +
-  COCO-80 objects → real document-pixel boxes), \`photoshop_scene\`
+- **Perception (on-device CV)** — \`ps_detect\` (faces +
+  COCO-80 objects → real document-pixel boxes), \`ps_read_scene\`
   (a structured read of subjects / horizon / tonal zones), and
-  \`photoshop_select_by_reference\` (a NAMED target → a real pixel
+  \`ps_select_by_reference\` (a NAMED target → a real pixel
   selection instead of a guessed rectangle). The image is analyzed
   locally. Reach for these to get REAL coordinates rather than
   estimating from the preview — they're the antidote to spatial
   guessing.
-- **Text** — \`photoshop_create_text_layer\`, then \`photoshop_set_text\`
+- **Text** — \`ps_create_text_layer\`, then \`ps_set_text\`
   (property font / color / alignment / content; font resolves family
   names to PostScript).
-- **Image** — \`photoshop_place_image\` (links external files as smart
-  objects), \`photoshop_resize_image\`, \`photoshop_crop_document\`,
-  \`photoshop_convert_image_mode\`, open / close / save_psd, and
-  \`photoshop_export\` (format jpeg/png).
-- **Groups** — \`photoshop_create_group\`,
-  \`photoshop_move_layer_to_group\`, \`photoshop_set_group_blend_mode\`,
-  \`photoshop_ungroup\`, \`photoshop_delete_group\`.
+- **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\`.
 - **Verification** — see below; this is the most underused part of
   the surface.
 - **Templates** — when template tools are present in \`tools/list\`,
@@ -107,20 +107,20 @@ Vision-language models are bad at fine spatial estimation. You will
 hallucinate "looks good" when reviewing your own output. The fix is
 to convert spatial questions into semantic ones:
 
-- **\`photoshop_get_preview\`** with the \`annotations\` array — draw
+- **\`ps_get_preview\`** with the \`annotations\` array — draw
   rectangles (by explicit bounds OR by layer name), guides, points,
   or selection markers ON the preview. "Is the placed image aligned
   with the frame?" becomes "Is the red wireframe touching the frame
   edges?" — a question you can answer reliably.
-- **\`photoshop_get_layer_bounds_diff\`** — pass a target rectangle
+- **\`ps_get_layer_bounds_diff\`** — pass a target rectangle
   + a layer name + a tolerance. Returns a one-word verdict
   ("aligned" / "shifted right" / "layer too small") and numeric
   deltas. Use this when you need a yes/no on placement accuracy,
   not a visual judgment.
-- **\`photoshop_compare_regions\`** — per-channel histogram stats
+- **\`ps_compare_regions\`** — per-channel histogram stats
   for two rectangles. Reach for this when you need a numeric diff
   (matched tones across two crops, before/after for an adjustment).
-- **\`photoshop_get_histogram\`** — full-image or per-channel. Reach
+- **\`ps_get_histogram\`** — full-image or per-channel. Reach
   for this for clipping detection, exposure verification, or "is
   this image neutral-gray?" — \`get_preview\` + eyeballing doesn't
   surface clipping reliably.
@@ -134,12 +134,12 @@ fill black, for example. Re-read your inventory first.
 
 Common false escape-hatch reaches we want you to avoid:
 - "Add a layer mask from the current selection" →
-  \`photoshop_layer_mask\` (op create) does this automatically when a
+  \`ps_layer_mask\` (op create) does this automatically when a
   selection is live.
 - "Move the layer so its center is at (x, y)" →
-  \`photoshop_transform_layer\` (op move) with \`center_on_x\` /
+  \`ps_transform_layer\` (op move) with \`center_on_x\` /
   \`center_on_y\`.
-- "Rotate this background layer" → \`photoshop_transform_layer\`
+- "Rotate this background layer" → \`ps_transform_layer\`
   (op rotate); it auto-promotes the background layer.
 
 If no typed tool fits AND the operation isn't a composition, surface
@@ -148,7 +148,7 @@ the gap to the user rather than fabricating a workaround.
 ## Known gaps
 
 - Frame opening / arbitrary edge detection — no general primitive.
-  Best path: \`photoshop_select\` (mode magic_wand) inside the dark
+  Best path: \`ps_select\` (mode magic_wand) inside the dark
   interior + read the selection bounds via \`get_selection_info\`.
 - Smart Object editing — no native tool to enter / exit smart-object
   edit mode from outside the document. Plan around it.
@@ -159,7 +159,7 @@ the gap to the user rather than fabricating a workaround.
 
 If you've lost track of what's available — this brief scrolled out of
 context, or you're not sure which tool exists for a job — call
-\`photoshop_list_capabilities\`. It returns a compact, live map of every
+\`ps_list_capabilities\`. It returns a compact, live map of every
 tool grouped by capability (each group's purpose + the tool names in
 it). It's cheaper than re-reading this overview and more current than
 any static list. Use it to find the right tool name, then \`tools/list\`
@@ -179,7 +179,7 @@ export function createOverviewTools(_connection, _snippetClient) {
     return [
         {
             tool: {
-                name: 'photoshop_overview',
+                name: 'ps_overview',
                 description: 'Orientation brief for the entire MCP — workflow contract, capabilities map by category, verification primitives, escape-hatch policy, known gaps. READ THIS FIRST when the user gives you an open-ended editing task. Read-only, idempotent, no document required, no Photoshop call (returns a static markdown brief). Skip it for trivial single-tool requests where you already know which tool fits.',
                 inputSchema: overviewSchema,
                 outputSchema: {

package/dist/tools/path-tools.js

@@ -1,8 +1,11 @@
 import { SUPPORTED_BRUSH_TOOLS } from '../api/brush-tool-names.js';
 import { runScript } from '../utils/run-script.js';
 import { validateArgs } from '../utils/validate.js';
+import { OnnxLandmarkDetectionClient } from '../detection/landmark-detection-client.js';
+import { resolveExpectedPlacement, PLACEMENT_SCHEMA } from '../perception/grounding-locate.js';
 const PATH_OPS = [
     'create_from_selection',
+    'create_from_placement',
     'save',
     'list',
     'delete',
@@ -20,6 +23,7 @@ const pathInputSchema = {
             type: 'string',
             enum: [...PATH_OPS],
             description: 'create_from_selection: convert the active selection into a work path (tolerance = crude↔detailed dial; CLEARS the selection). ' +
+                'create_from_placement: NAME a curve (placement → a path relation: `along` a traced edge / landmark curve, or a `segment` between anchors) and get an editable, saved vector path following it — the grounded pen; needs `name` (+ optional `closed`). ' +
                 'save: persist the current work path under a name (required for stroke/clip-by-name and to survive the next create). ' +
                 'list: inventory all paths (name, kind, subpath + anchor counts) — read-only. ' +
                 'delete: remove a path (name → that saved path; omit name → the current work path). ' +
@@ -30,7 +34,16 @@ const pathInputSchema = {
         },
         name: {
             type: 'string',
-            description: 'Path name. REQUIRED for save and set_clipping. Optional for delete / load_as_selection / stroke / fill — when omitted those target the current work path. Ignored by create_from_selection / list.',
+            description: 'Path name. REQUIRED for save, set_clipping, and create_from_placement (the new saved path is named). Optional for delete / load_as_selection / stroke / fill — when omitted those target the current work path. Ignored by create_from_selection / list.',
+        },
+        placement: {
+            ...PLACEMENT_SCHEMA,
+            description: 'create_from_placement only: NAME the curve the path follows, as an anchor-relational placement that resolves to a PATH (relation `along` a traced edge / a Pro landmark curve, or a `segment` between two anchors). The spatial-grounding resolver + objective gate produce AND verify the curve; the path is created ONLY if the gate PASSES. Name the curve — do NOT hand-type anchor points.',
+        },
+        closed: {
+            type: 'boolean',
+            default: false,
+            description: 'create_from_placement only: close the path into a loop (connect the last anchor back to the first). Default false (an open path).',
         },
         tolerance: {
             type: 'number',
@@ -59,7 +72,7 @@ const pathInputSchema = {
         tool: {
             type: 'string',
             enum: SUPPORTED_BRUSH_TOOLS,
-            description: "stroke only: which brush-family tool paints the path. Default 'brush'. Same 16-tool set as photoshop_apply_brush_stroke.",
+            description: "stroke only: which brush-family tool paints the path. Default 'brush'. Same 16-tool set as ps_apply_brush_stroke.",
             default: 'brush',
         },
         color: {
@@ -98,12 +111,12 @@ const pathInputSchema = {
     },
     required: ['op'],
 };
-export function createPathTools(connection, snippetClient) {
+export function createPathTools(connection, snippetClient, client = new OnnxLandmarkDetectionClient()) {
     return [
         {
             tool: {
-                name: 'photoshop_path',
-                description: 'Work with editable vector PATHS — the connective tissue between selections, brush strokes, and clipping. One op-discriminated tool: `create_from_selection` (selection → work path), `save` (name the work path), `list`, `delete`, `load_as_selection` (path → selection), `stroke` (paint a brush-family tool along a path), `fill` (fill a path region), `set_clipping` (mark a saved path as the clipping path). **Reach for this when**: turning a precise selection into a reusable/strokeable outline, converting a saved path back to a selection, or outlining/filling a shape exactly. create_from_selection and load_as_selection are an exact round-trip. stroke/fill bake pixels and auto-duplicate the target layer (Bundle O). Every op returns path_info (counts + per-path subpath/anchor totals) so you can verify the path landed; load_as_selection also returns selection_info.',
+                name: 'ps_path',
+                description: 'Work with editable vector PATHS — the connective tissue between selections, brush strokes, and clipping. One op-discriminated tool: `create_from_selection` (selection → work path), `create_from_placement` (NAME a curve → editable saved path, the grounded pen), `save` (name the work path), `list`, `delete`, `load_as_selection` (path → selection), `stroke` (paint a brush-family tool along a path), `fill` (fill a path region), `set_clipping` (mark a saved path as the clipping path). **Reach for this when**: tracing a named curve (an edge, a landmark contour) into an editable path, turning a precise selection into a reusable/strokeable outline, converting a saved path back to a selection, or outlining/filling a shape exactly. create_from_selection and load_as_selection are an exact round-trip. stroke/fill bake pixels and auto-duplicate the target layer (Bundle O). Every op returns path_info (counts + per-path subpath/anchor totals) so you can verify the path landed; load_as_selection also returns selection_info.',
                 inputSchema: pathInputSchema,
                 outputSchema: {
                     type: 'object',
@@ -118,6 +131,9 @@ export function createPathTools(connection, snippetClient) {
                         name: { type: 'string' },
                         path_name: { type: 'string' },
                         tolerance: { type: 'number' },
+                        anchors: { type: 'number' },
+                        closed: { type: 'boolean' },
+                        placement: { type: 'object' },
                         selection_consumed: { type: 'boolean' },
                         operation: { type: 'string' },
                         tool: { type: 'string' },
@@ -139,22 +155,32 @@ export function createPathTools(connection, snippetClient) {
                     idempotentHint: false,
                 },
             },
-            handler: async (args) => runPathOp(connection, snippetClient, args),
+            handler: async (args) => runPathOp(connection, snippetClient, client, args),
         },
     ];
 }
-async function runPathOp(connection, snippetClient, rawArgs) {
+async function runPathOp(connection, snippetClient, client, rawArgs) {
     try {
         const args = validateArgs(pathInputSchema, rawArgs);
         const op = args.op;
         const name = args.name;
         let snippet;
         let params;
+        let placementInfo;
         switch (op) {
             case 'create_from_selection':
                 snippet = 'createPathFromSelection';
                 params = { tolerance: args.tolerance };
                 break;
+            case 'create_from_placement': {
+                if (!name)
+                    return errorResult('create_from_placement requires a "name" for the new saved path (pathItems.add needs one).');
+                const rp = await resolveExpectedPlacement(connection, client, args.placement, 'path', 'path');
+                snippet = 'createPathFromPoints';
+                params = { name, points: rp.curve, closed: args.closed ?? false };
+                placementInfo = { curve: rp.curve, anchors: rp.anchors, summary: rp.summary };
+                break;
+            }
             case 'save':
                 if (!name)
                     return missingName('save');
@@ -219,8 +245,20 @@ async function runPathOp(connection, snippetClient, rawArgs) {
         }
         const script = await snippetClient.build(snippet, params);
         const result = (await runScript(connection, script));
+        if (placementInfo) {
+            result.placement = {
+                target: 'path',
+                gate: { pass: true },
+                anchors: placementInfo.anchors,
+                points: placementInfo.curve.length,
+                summary: placementInfo.summary,
+            };
+        }
+        const text = placementInfo
+            ? `${summarize(op, result)} Path follows the resolved ${placementInfo.summary} (placement gate PASS).`
+            : summarize(op, result);
         return {
-            content: [{ type: 'text', text: summarize(op, result) }],
+            content: [{ type: 'text', text }],
             structuredContent: result,
         };
     }
@@ -229,7 +267,7 @@ async function runPathOp(connection, snippetClient, rawArgs) {
             content: [
                 {
                     type: 'text',
-                    text: `Error in photoshop_path: ${error instanceof Error ? error.message : String(error)}`,
+                    text: `Error in ps_path: ${error instanceof Error ? error.message : String(error)}`,
                 },
             ],
             isError: true,
@@ -241,12 +279,15 @@ function missingName(op) {
         content: [
             {
                 type: 'text',
-                text: `photoshop_path op=${op} requires a "name" (the saved path to act on). Use op=save to name the current work path first.`,
+                text: `ps_path op=${op} requires a "name" (the saved path to act on). Use op=save to name the current work path first.`,
             },
         ],
         isError: true,
     };
 }
+function errorResult(msg) {
+    return { content: [{ type: 'text', text: `ps_path: ${msg}` }], isError: true };
+}
 function summarize(op, r) {
     const info = r.path_info;
     const pathCount = info?.count ?? r.count;
@@ -254,6 +295,8 @@ function summarize(op, r) {
     switch (op) {
         case 'create_from_selection':
             return `Created a work path from the selection (tolerance ${r.tolerance}); the selection was consumed.${suffix}`;
+        case 'create_from_placement':
+            return `Created editable path "${r.name}" from the named curve (${r.anchors} anchors${r.closed ? ', closed' : ''}).${suffix}`;
         case 'save':
             return `Saved path "${r.name}".${suffix}`;
         case 'list':

package/dist/tools/portrait-tools.js

@@ -112,7 +112,7 @@ async function runPortraitOp(connection, snippet, client, rawArgs) {
     catch (error) {
         const msg = error instanceof Error ? error.message : String(error);
         return {
-            content: [{ type: 'text', text: `Error in photoshop_portrait_touchup: ${msg}` }],
+            content: [{ type: 'text', text: `Error in ps_portrait_touchup: ${msg}` }],
             isError: true,
         };
     }
@@ -121,8 +121,8 @@ export function createPortraitTools(connection, snippetClient, client = new Onnx
     return [
         {
             tool: {
-                name: 'photoshop_portrait_touchup',
-                description: 'Detection-driven face touch-ups using LOCAL on-device face detection. op=dodge_face brightens the detected face(s) with a non-destructive masked adjustment layer. op=soften_skin applies a soft blur over the face(s) on a duplicate layer (light, bounding-box-level smoothing). Works from the face bounding box — precise landmark ops (eyes/teeth/lips) are a Pro feature. Multiple faces are handled together. Pair with photoshop_detect (target=faces) to preview detection first.',
+                name: 'ps_portrait_touchup',
+                description: 'Detection-driven face touch-ups using LOCAL on-device face detection. op=dodge_face brightens the detected face(s) with a non-destructive masked adjustment layer. op=soften_skin applies a soft blur over the face(s) on a duplicate layer (light, bounding-box-level smoothing). Works from the face bounding box — precise landmark ops (eyes/teeth/lips) are a Pro feature. Multiple faces are handled together. Pair with ps_detect (target=faces) to preview detection first.',
                 inputSchema: portraitSchema,
                 outputSchema: {
                     type: 'object',