dominus-cli 2.2.1 → 2.4.0

package/dist/mcp.js

@@ -109,6 +109,19 @@ var CliMsg = {
   V2_READ_SCRIPT: "studio:v2:read_script",
   V2_UPDATE_SCRIPT: "studio:v2:update_script",
   V2_APPLY: "studio:v2:apply",
+  V2_CREATE_PARTS: "studio:v2:create_parts",
+  V2_CLONE_INSTANCES: "studio:v2:clone_instances",
+  V2_GROUP_INSTANCES: "studio:v2:group_instances",
+  V2_UNGROUP_INSTANCES: "studio:v2:ungroup_instances",
+  V2_TRANSFORM_INSTANCES: "studio:v2:transform_instances",
+  V2_CREATE_WELDS: "studio:v2:create_welds",
+  V2_QUERY_PARTS: "studio:v2:query_parts",
+  V2_SET_SELECTION: "studio:v2:set_selection",
+  V2_GET_METADATA: "studio:v2:get_metadata",
+  V2_SET_ATTRIBUTES: "studio:v2:set_attributes",
+  V2_UPDATE_TAGS: "studio:v2:update_tags",
+  V2_LIST_CALLABLE_METHODS: "studio:v2:list_callable_methods",
+  V2_INVOKE_METHODS: "studio:v2:invoke_methods",
   V2_DELETE: "studio:v2:delete",
   V2_BUILD_UI: "studio:v2:build_ui",
   V2_SNAPSHOT_UI: "studio:v2:snapshot_ui",
@@ -561,11 +574,20 @@ Required workflow for Studio changes:
 
 For broad tasks with independent Studio branches, prefer run_parallel_task when the MCP client supports Sampling. Dominus partitions immediate child scopes, runs proposal-only workers concurrently, rejects unknown refs and overlapping writes, applies only the coordinator-approved atomic plan, and reads the result back. Use the normal workflow when Sampling is unavailable or the task is a simple edit.
 
+Building workflow:
+- Use studio_create_parts for multi-part structures instead of many generic create operations.
+- Use studio_clone_instances when an existing instance or model is the intended template. Clone rather than manually recreating descendants and properties.
+- Use studio_get_metadata, studio_set_attributes, and studio_update_tags for saved Instance metadata. Do not create runtime bootstrap scripts or attribute mirrors when direct tags or attributes satisfy the task.
+- Use studio_list_callable_methods before studio_invoke_methods when a task needs an Instance method not covered by a dedicated tool. Dedicated tools remain preferred for common writes.
+- Use studio_transform_instances for Models and BaseParts so model layouts move through PVInstance pivots.
+- Use studio_group_instances and studio_ungroup_instances to organize hierarchy, studio_create_welds for rigid assemblies, and studio_query_parts to inspect crowded 3D regions before editing.
+- Use studio_set_selection when surfacing completed objects to the Studio user.
+
 Safety rules:
 - Never invent instance IDs or Roblox API members.
 - Do not retry a failed write unchanged. Inspect the error and current state first.
 - Deletion is a separate destructive tool and requires explicit user intent.
-- studio_apply is transactional. Keep related edits together, but stay within its documented limits.
+- studio_apply is transactional and supports setProperties, setAttributes, updateTags, create, clone, and move operations. Keep related edits together, but stay within its documented limits.
 - UI fidelity work must snapshot and inspect the result after building; verify fonts, UDim2 values, colors, strokes, and hierarchy.
 - Dominus intentionally has no arbitrary Luau execution tool.`;
 
@@ -632,6 +654,8 @@ function failure(error, data) {
     data
   });
 }
+
+// src/mcp/tools/shared.ts
 var instanceRefSchema = z.object({
   instanceId: z.string().uuid().optional(),
   pathSegments: z.array(z.string().min(1).max(256)).min(1).max(100).optional()
@@ -664,7 +688,245 @@ function ref(value) {
   return value;
 }
 
-// src/mcp/tools/connections.ts
+// src/mcp/tools/building.ts
+var finiteNumber = z.number().finite();
+var vector3Schema = z.object({ x: finiteNumber, y: finiteNumber, z: finiteNumber }).strict();
+var propertiesSchema = z.record(z.unknown()).refine(
+  (properties) => Object.keys(properties).length <= 100 && !Object.keys(properties).some((name) => ["Parent", "ClassName", "Source"].includes(name)),
+  "At most 100 properties are allowed; Parent, ClassName, and Source require dedicated operations"
+);
+var partSchema = z.object({
+  name: z.string().min(1).max(100),
+  className: z.enum([
+    "Part",
+    "WedgePart",
+    "CornerWedgePart",
+    "TrussPart",
+    "MeshPart",
+    "SpawnLocation",
+    "Seat",
+    "VehicleSeat"
+  ]).optional().default("Part"),
+  shape: z.enum(["Block", "Ball", "Cylinder", "Wedge", "CornerWedge"]).optional(),
+  position: vector3Schema.optional(),
+  orientation: vector3Schema.optional(),
+  size: vector3Schema.optional(),
+  color: z.string().min(1).max(100).optional(),
+  material: z.string().min(1).max(100).optional(),
+  transparency: z.number().min(0).max(1).optional(),
+  anchored: z.boolean().optional().default(true),
+  canCollide: z.boolean().optional(),
+  properties: propertiesSchema.optional()
+});
+var cloneRequestSchema = z.object({
+  target: instanceRefSchema,
+  parent: instanceRefSchema.optional(),
+  name: z.string().min(1).max(100).optional(),
+  count: z.number().int().min(1).max(50).optional().default(1),
+  offset: vector3Schema.optional(),
+  stepOffset: vector3Schema.optional(),
+  properties: propertiesSchema.optional()
+});
+var cframeSchema = z.array(finiteNumber).refine((value) => value.length === 3 || value.length === 12, "CFrame requires 3 or 12 numbers");
+var transformOperationSchema = z.object({
+  target: instanceRefSchema,
+  mode: z.enum(["absolute", "relative"]).optional().default("absolute"),
+  cframe: cframeSchema.optional(),
+  position: vector3Schema.optional(),
+  orientation: vector3Schema.optional(),
+  offset: vector3Schema.optional(),
+  rotationOffset: vector3Schema.optional(),
+  space: z.enum(["world", "local"]).optional().default("world")
+}).refine(
+  (value) => value.mode === "relative" ? Boolean(value.offset || value.rotationOffset) : Boolean(value.cframe || value.position || value.orientation),
+  "Absolute transforms require cframe, position, or orientation; relative transforms require offset or rotationOffset"
+);
+function registerBuildingTools(server, bridge) {
+  server.registerTool(
+    "studio_create_parts",
+    {
+      title: "Build Roblox Parts",
+      description: "Create up to 200 typed BaseParts in one undoable batch, optionally grouped under a new Model or Folder. Supports positions, orientations, sizes, colors, materials, shapes, and additional writable properties.",
+      inputSchema: {
+        parent: instanceRefSchema.optional(),
+        groupName: z.string().min(1).max(100).optional(),
+        groupClass: z.enum(["Model", "Folder"]).optional().default("Model"),
+        parts: z.array(partSchema).min(1).max(200)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ parent, groupName, groupClass, parts }) => callStudio(bridge, CliMsg.V2_CREATE_PARTS, { parent, groupName, groupClass, parts }, 12e4)
+  );
+  server.registerTool(
+    "studio_clone_instances",
+    {
+      title: "Clone Roblox Instances",
+      description: "Deep-clone instances and descendants with Instance:Clone(), optionally rename, reparent, override root properties, and create repeated spatial copies using offsets. The entire request is undoable and rolls back on failure.",
+      inputSchema: { requests: z.array(cloneRequestSchema).min(1).max(100) },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ requests }) => callStudio(bridge, CliMsg.V2_CLONE_INSTANCES, { requests }, 12e4)
+  );
+  server.registerTool(
+    "studio_group_instances",
+    {
+      title: "Group Roblox Instances",
+      description: "Create a Model or Folder and move up to 100 independent instances into it in one undoable operation.",
+      inputSchema: {
+        targets: z.array(instanceRefSchema).min(1).max(100),
+        name: z.string().min(1).max(100),
+        className: z.enum(["Model", "Folder"]).optional().default("Model"),
+        parent: instanceRefSchema.optional()
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ targets, name, className, parent }) => callStudio(bridge, CliMsg.V2_GROUP_INSTANCES, { targets, name, className, parent }, 6e4)
+  );
+  server.registerTool(
+    "studio_ungroup_instances",
+    {
+      title: "Ungroup Roblox Instances",
+      description: "Move every child out of up to 20 Models or Folders, then remove the empty containers in one undoable operation.",
+      inputSchema: {
+        targets: z.array(instanceRefSchema).min(1).max(20),
+        parent: instanceRefSchema.optional(),
+        confirm: z.literal(true)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ targets, parent, confirm }) => callStudio(bridge, CliMsg.V2_UNGROUP_INSTANCES, { targets, parent, confirm }, 6e4)
+  );
+  server.registerTool(
+    "studio_transform_instances",
+    {
+      title: "Transform Roblox Models and Parts",
+      description: "Move or rotate up to 100 Models and BaseParts through PVInstance:PivotTo. Supports exact absolute CFrames and world/local relative offsets without breaking model layouts.",
+      inputSchema: { operations: z.array(transformOperationSchema).min(1).max(100) },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ operations }) => callStudio(bridge, CliMsg.V2_TRANSFORM_INSTANCES, { operations }, 6e4)
+  );
+  server.registerTool(
+    "studio_create_welds",
+    {
+      title: "Create Roblox Welds",
+      description: "Create up to 200 WeldConstraints between explicit BasePart refs in one undoable operation.",
+      inputSchema: {
+        welds: z.array(
+          z.object({
+            part0: instanceRefSchema,
+            part1: instanceRefSchema,
+            name: z.string().min(1).max(100).optional(),
+            parent: instanceRefSchema.optional()
+          })
+        ).min(1).max(200)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ welds }) => callStudio(bridge, CliMsg.V2_CREATE_WELDS, { welds }, 6e4)
+  );
+  server.registerTool(
+    "studio_query_parts",
+    {
+      title: "Query Parts in 3D Space",
+      description: "Find BaseParts intersecting an oriented box or radius using WorldRoot spatial queries. Returns stable refs, positions, and sizes for inspection or later mutations.",
+      inputSchema: {
+        root: instanceRefSchema.optional(),
+        mode: z.enum(["box", "radius"]).optional().default("box"),
+        position: vector3Schema,
+        orientation: vector3Schema.optional(),
+        size: vector3Schema.optional(),
+        radius: z.number().finite().positive().optional(),
+        maxParts: z.number().int().min(1).max(500).optional().default(200),
+        filter: z.array(instanceRefSchema).max(100).optional(),
+        filterType: z.enum(["Include", "Exclude"]).optional().default("Exclude"),
+        respectCanCollide: z.boolean().optional().default(false)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({
+      root,
+      mode,
+      position,
+      orientation,
+      size,
+      radius,
+      maxParts,
+      filter,
+      filterType,
+      respectCanCollide
+    }) => callStudio(bridge, CliMsg.V2_QUERY_PARTS, {
+      root,
+      mode,
+      position,
+      orientation,
+      size,
+      radius,
+      maxParts,
+      filter,
+      filterType,
+      respectCanCollide
+    })
+  );
+  server.registerTool(
+    "studio_set_selection",
+    {
+      title: "Set Roblox Studio Selection",
+      description: "Replace the current Studio selection with up to 200 stable instance refs. Pass an empty array to clear selection.",
+      inputSchema: { targets: z.array(instanceRefSchema).max(200) },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({ targets }) => callStudio(bridge, CliMsg.V2_SET_SELECTION, { targets })
+  );
+}
 function registerConnectionTools(server, bridge) {
   server.registerTool(
     "dominus_status",
@@ -1192,7 +1454,261 @@ function registerDocsTools(server) {
     }
   );
 }
-var propertiesSchema = z.record(z.unknown()).refine(
+var finiteNumber2 = z.number().finite();
+var vector2Value = z.object({ x: finiteNumber2, y: finiteNumber2 }).strict();
+var vector3Value = z.object({ x: finiteNumber2, y: finiteNumber2, z: finiteNumber2 }).strict();
+var color3Object = z.object({ r: finiteNumber2, g: finiteNumber2, b: finiteNumber2 }).strict();
+var color3Value = z.union([
+  z.string().min(1).max(100),
+  color3Object,
+  z.tuple([finiteNumber2, finiteNumber2, finiteNumber2])
+]);
+var cframeValue = z.array(finiteNumber2).refine((value) => value.length === 3 || value.length === 12, "CFrame requires 3 or 12 numbers");
+var numberSequenceKeypoint = z.union([
+  z.tuple([finiteNumber2, finiteNumber2]),
+  z.tuple([finiteNumber2, finiteNumber2, finiteNumber2])
+]);
+var colorSequenceKeypoint = z.tuple([finiteNumber2, color3Value]);
+var typedString = z.object({ type: z.literal("string"), value: z.string() }).strict();
+var typedBoolean = z.object({ type: z.literal("boolean"), value: z.boolean() }).strict();
+var typedNumber = z.object({ type: z.literal("number"), value: finiteNumber2 }).strict();
+var typedUDim = z.object({
+  type: z.literal("UDim"),
+  value: z.union([
+    z.object({ scale: finiteNumber2, offset: finiteNumber2 }).strict(),
+    z.tuple([finiteNumber2, finiteNumber2])
+  ])
+}).strict();
+var typedUDim2 = z.object({
+  type: z.literal("UDim2"),
+  value: z.union([
+    z.object({
+      xScale: finiteNumber2,
+      xOffset: finiteNumber2,
+      yScale: finiteNumber2,
+      yOffset: finiteNumber2
+    }).strict(),
+    z.tuple([finiteNumber2, finiteNumber2, finiteNumber2, finiteNumber2])
+  ])
+}).strict();
+var typedBrickColor = z.object({ type: z.literal("BrickColor"), value: z.string().min(1).max(100) }).strict();
+var typedColor3 = z.object({ type: z.literal("Color3"), value: color3Value }).strict();
+var typedVector2 = z.object({
+  type: z.literal("Vector2"),
+  value: z.union([vector2Value, z.tuple([finiteNumber2, finiteNumber2])])
+}).strict();
+var typedVector3 = z.object({
+  type: z.literal("Vector3"),
+  value: z.union([vector3Value, z.tuple([finiteNumber2, finiteNumber2, finiteNumber2])])
+}).strict();
+var typedCFrame = z.object({ type: z.literal("CFrame"), value: cframeValue }).strict();
+var typedNumberSequence = z.object({
+  type: z.literal("NumberSequence"),
+  value: z.union([finiteNumber2, z.array(numberSequenceKeypoint).min(1).max(100)])
+}).strict();
+var typedColorSequence = z.object({
+  type: z.literal("ColorSequence"),
+  value: z.union([color3Value, z.array(colorSequenceKeypoint).min(1).max(100)])
+}).strict();
+var typedNumberRange = z.object({
+  type: z.literal("NumberRange"),
+  value: z.union([finiteNumber2, z.tuple([finiteNumber2, finiteNumber2])])
+}).strict();
+var typedRect = z.object({
+  type: z.literal("Rect"),
+  value: z.tuple([finiteNumber2, finiteNumber2, finiteNumber2, finiteNumber2])
+}).strict();
+var typedFont = z.object({
+  type: z.literal("Font"),
+  value: z.union([
+    z.object({
+      family: z.string().min(1).max(500),
+      weight: z.string().min(1).max(100).optional(),
+      style: z.string().min(1).max(100).optional()
+    }).strict(),
+    z.object({
+      Family: z.string().min(1).max(500),
+      Weight: z.string().min(1).max(100).optional(),
+      Style: z.string().min(1).max(100).optional()
+    }).strict()
+  ])
+}).strict();
+var attributeValueSchema = z.discriminatedUnion("type", [
+  typedString,
+  typedBoolean,
+  typedNumber,
+  typedUDim,
+  typedUDim2,
+  typedBrickColor,
+  typedColor3,
+  typedVector2,
+  typedVector3,
+  typedCFrame,
+  typedNumberSequence,
+  typedColorSequence,
+  typedNumberRange,
+  typedRect,
+  typedFont
+]);
+var methodArgumentSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("nil") }).strict(),
+  typedString,
+  typedBoolean,
+  typedNumber,
+  typedUDim,
+  typedUDim2,
+  typedBrickColor,
+  typedColor3,
+  typedVector2,
+  typedVector3,
+  typedCFrame,
+  typedNumberSequence,
+  typedColorSequence,
+  typedNumberRange,
+  typedRect,
+  typedFont,
+  z.object({ type: z.literal("Instance"), value: instanceRefSchema }).strict()
+]);
+var callableMethodSchema = z.enum([
+  "GetAttribute",
+  "GetAttributes",
+  "GetTags",
+  "HasTag",
+  "GetFullName",
+  "IsA",
+  "IsAncestorOf",
+  "IsDescendantOf",
+  "FindFirstChild",
+  "FindFirstChildOfClass",
+  "FindFirstChildWhichIsA",
+  "FindFirstAncestor",
+  "FindFirstAncestorOfClass",
+  "FindFirstAncestorWhichIsA",
+  "GetChildren",
+  "GetDescendants",
+  "GetPivot",
+  "GetScale",
+  "GetBoundingBox",
+  "AddTag",
+  "RemoveTag",
+  "SetAttribute",
+  "PivotTo",
+  "ScaleTo"
+]);
+var attributeUpdateSchema = z.object({
+  target: instanceRefSchema,
+  set: z.array(
+    z.object({
+      name: z.string().min(1).max(100),
+      value: attributeValueSchema
+    })
+  ).max(100).optional().default([]),
+  remove: z.array(z.string().min(1).max(100)).max(100).optional().default([])
+});
+var tagUpdateSchema = z.object({
+  target: instanceRefSchema,
+  add: z.array(z.string().min(1).max(100)).max(100).optional().default([]),
+  remove: z.array(z.string().min(1).max(100)).max(100).optional().default([])
+});
+function registerMetadataTools(server, bridge) {
+  server.registerTool(
+    "studio_get_metadata",
+    {
+      title: "Get Roblox Tags and Attributes",
+      description: "Read persistent Instance tags and typed attributes for up to 100 instances. Use this instead of runtime bootstrap scripts or attribute mirrors when inspecting saved Studio metadata.",
+      inputSchema: {
+        targets: z.array(instanceRefSchema).min(1).max(100)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({ targets }) => callStudio(bridge, CliMsg.V2_GET_METADATA, { targets })
+  );
+  server.registerTool(
+    "studio_set_attributes",
+    {
+      title: "Set Roblox Attributes",
+      description: "Set or remove persistent typed Instance attributes in one undoable batch. Values are explicitly typed and saved with the place; no Play-mode bootstrap is required.",
+      inputSchema: {
+        operations: z.array(attributeUpdateSchema).min(1).max(100)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({ operations }) => callStudio(bridge, CliMsg.V2_SET_ATTRIBUTES, { operations }, 6e4)
+  );
+  server.registerTool(
+    "studio_update_tags",
+    {
+      title: "Update Roblox Tags",
+      description: "Add or remove persistent Instance tags in one undoable batch using Instance:AddTag and RemoveTag. Tags are saved directly in Studio and replicate normally.",
+      inputSchema: {
+        operations: z.array(tagUpdateSchema).min(1).max(100)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({ operations }) => callStudio(bridge, CliMsg.V2_UPDATE_TAGS, { operations }, 6e4)
+  );
+  server.registerTool(
+    "studio_list_callable_methods",
+    {
+      title: "List Safe Instance Methods",
+      description: "List the guarded Instance methods Dominus can invoke on a specific target, including required classes, argument types, and whether each method reads or writes Studio state.",
+      inputSchema: {
+        target: instanceRefSchema
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({ target }) => callStudio(bridge, CliMsg.V2_LIST_CALLABLE_METHODS, { target })
+  );
+  server.registerTool(
+    "studio_invoke_methods",
+    {
+      title: "Invoke Safe Instance Methods",
+      description: "Invoke a bounded allowlist of typed Instance methods. Supports hierarchy queries, metadata methods, GetPivot/GetBoundingBox/GetScale, and undoable AddTag/RemoveTag/SetAttribute/PivotTo/ScaleTo writes. Arbitrary, destructive, yielding, network, and signal methods are blocked in the Studio plugin.",
+      inputSchema: {
+        calls: z.array(
+          z.object({
+            target: instanceRefSchema,
+            method: callableMethodSchema,
+            arguments: z.array(methodArgumentSchema).max(10).optional().default([])
+          })
+        ).min(1).max(50)
+      },
+      outputSchema: toolOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    ({ calls }) => callStudio(bridge, CliMsg.V2_INVOKE_METHODS, { calls }, 6e4)
+  );
+}
+var propertiesSchema2 = z.record(z.unknown()).refine(
   (properties) => Object.keys(properties).length <= 100 && !Object.keys(properties).some((name) => ["Parent", "ClassName", "Source"].includes(name)),
   "At most 100 properties are allowed; Parent, ClassName, and Source require dedicated operations"
 );
@@ -1200,20 +1716,30 @@ var mutationOperationSchema = z.discriminatedUnion("op", [
   z.object({
     op: z.literal("setProperties"),
     target: instanceRefSchema,
-    properties: propertiesSchema
+    properties: propertiesSchema2
   }),
   z.object({
     op: z.literal("create"),
     parent: instanceRefSchema,
     className: z.string().min(1).max(100),
     name: z.string().min(1).max(256),
-    properties: propertiesSchema.optional()
+    properties: propertiesSchema2.optional()
   }),
   z.object({
     op: z.literal("move"),
     target: instanceRefSchema,
     parent: instanceRefSchema
-  })
+  }),
+  z.object({
+    op: z.literal("clone"),
+    target: instanceRefSchema,
+    parent: instanceRefSchema,
+    name: z.string().min(1).max(100),
+    offset: z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }).optional(),
+    properties: propertiesSchema2.optional()
+  }),
+  attributeUpdateSchema.extend({ op: z.literal("setAttributes") }),
+  tagUpdateSchema.extend({ op: z.literal("updateTags") })
 ]);
 var workerProposalSchema = z.object({
   workerId: z.string().min(1).max(64),
@@ -1441,7 +1967,7 @@ async function runWorker(server, bridge, goal, assignment, constraints, taskType
         systemPrompt: [
           "You are a read-only Dominus worker. Inspect only the Studio evidence in the request.",
           "You cannot write to Studio. Return one strict JSON WorkerProposal and no Markdown.",
-          "Only propose setProperties, create, or move operations using exact instance refs copied from evidence.",
+          "Only propose setProperties, setAttributes, updateTags, create, clone, or move operations using exact instance refs copied from evidence.",
           "Never invent instanceId values. Never propose delete, script edits, or arbitrary execution."
         ].join(" "),
         messages: [
@@ -1472,6 +1998,25 @@ async function runWorker(server, bridge, goal, assignment, constraints, taskType
                         op: "move",
                         target: { instanceId: "uuid", pathSegments: ["..."] },
                         parent: { instanceId: "uuid", pathSegments: ["..."] }
+                      },
+                      {
+                        op: "clone",
+                        target: { instanceId: "uuid", pathSegments: ["..."] },
+                        parent: { instanceId: "uuid", pathSegments: ["..."] },
+                        name: "CloneName",
+                        offset: { x: 0, y: 0, z: 0 }
+                      },
+                      {
+                        op: "setAttributes",
+                        target: { instanceId: "uuid", pathSegments: ["..."] },
+                        set: [{ name: "PlotId", value: { type: "number", value: 1 } }],
+                        remove: []
+                      },
+                      {
+                        op: "updateTags",
+                        target: { instanceId: "uuid", pathSegments: ["..."] },
+                        add: ["Plot"],
+                        remove: []
                       }
                     ],
                     risks: ["string"],
@@ -1556,7 +2101,7 @@ function validateWorkerResults(results) {
 function validateOperations(assignment, operations) {
   const errors = [];
   for (const [index, operation] of operations.entries()) {
-    const refs = operation.op === "create" ? [operation.parent] : operation.op === "move" ? [operation.target, operation.parent] : [operation.target];
+    const refs = operation.op === "create" ? [operation.parent] : operation.op === "move" || operation.op === "clone" ? [operation.target, operation.parent] : [operation.target];
     for (const ref2 of refs) {
       if (!isKnownParallelRef(ref2, assignment.knownRefKeys)) {
         errors.push(`Operation ${index} references an instance absent from worker evidence`);
@@ -1702,15 +2247,18 @@ async function verifyPlan(bridge, rootRef, originalRoot, operations) {
   );
   const knownPaths = collectInstancePaths(originalRoot);
   const expectedCreates = operations.flatMap((operation) => {
-    if (operation.op !== "create") return [];
+    if (operation.op !== "create" && operation.op !== "clone") return [];
     const parentPath = resolveRefPath(operation.parent, knownPaths);
     return parentPath ? [pathKey([...parentPath, operation.name])] : [];
   });
   const missingCreates = expectedCreates.filter((path5) => !paths.has(path5));
-  const inspectOperations = operations.filter((operation) => operation.op !== "create");
+  const inspectOperations = operations.filter(
+    (operation) => operation.op === "setProperties" || operation.op === "move"
+  );
   const inspectFailures = [];
   const propertyMismatches = [];
   const moveMismatches = [];
+  const metadataMismatches = [];
   for (let offset = 0; offset < inspectOperations.length; offset += 20) {
     const batch = inspectOperations.slice(offset, offset + 20);
     const targets = batch.map((operation) => operation.target);
@@ -1755,8 +2303,77 @@ async function verifyPlan(bridge, rootRef, originalRoot, operations) {
       }
     });
   }
+  const metadataOperations = operations.filter(
+    (operation) => operation.op === "setAttributes" || operation.op === "updateTags"
+  );
+  for (let offset = 0; offset < metadataOperations.length; offset += 100) {
+    const batch = metadataOperations.slice(offset, offset + 100);
+    const metadata = await requestStudio(bridge, CliMsg.V2_GET_METADATA, {
+      targets: batch.map((operation) => operation.target)
+    });
+    const results = Array.isArray(metadata.results) ? metadata.results : [];
+    batch.forEach((operation, index) => {
+      const result = results[index];
+      const targetLabel = refLabel(operation.target);
+      if (!result) {
+        inspectFailures.push(`${targetLabel}: missing metadata inspection result`);
+        return;
+      }
+      if (operation.op === "setAttributes") {
+        const attributes = Array.isArray(result.attributes) ? result.attributes : [];
+        const actual = new Map(attributes.map((entry) => [String(entry.name), entry.value]));
+        for (const item of operation.set) {
+          const actualValue = actual.get(item.name);
+          if (!actual.has(item.name) || !valuesEquivalent(item.value, actualValue)) {
+            metadataMismatches.push({
+              target: targetLabel,
+              kind: "attribute",
+              name: item.name,
+              expected: item.value,
+              actual: actualValue
+            });
+          }
+        }
+        for (const name of operation.remove) {
+          if (actual.has(name)) {
+            metadataMismatches.push({
+              target: targetLabel,
+              kind: "attribute",
+              name,
+              expected: "absent",
+              actual: actual.get(name)
+            });
+          }
+        }
+      } else {
+        const tags = new Set(Array.isArray(result.tags) ? result.tags.map(String) : []);
+        for (const name of operation.add) {
+          if (!tags.has(name)) {
+            metadataMismatches.push({
+              target: targetLabel,
+              kind: "tag",
+              name,
+              expected: true,
+              actual: false
+            });
+          }
+        }
+        for (const name of operation.remove) {
+          if (tags.has(name)) {
+            metadataMismatches.push({
+              target: targetLabel,
+              kind: "tag",
+              name,
+              expected: false,
+              actual: true
+            });
+          }
+        }
+      }
+    });
+  }
   return {
-    passed: !tree.truncated && missingCreates.length === 0 && propertyMismatches.length === 0 && moveMismatches.length === 0 && inspectFailures.length === 0,
+    passed: !tree.truncated && missingCreates.length === 0 && propertyMismatches.length === 0 && moveMismatches.length === 0 && metadataMismatches.length === 0 && inspectFailures.length === 0,
     treeNodeCount: tree.nodeCount,
     treeTruncated: tree.truncated,
     expectedCreates: expectedCreates.length,
@@ -1764,6 +2381,7 @@ async function verifyPlan(bridge, rootRef, originalRoot, operations) {
     missingCreates,
     propertyMismatches,
     moveMismatches,
+    metadataMismatches,
     inspectFailures
   };
 }
@@ -1772,12 +2390,17 @@ function findRepairOperations(operations, verification, originalRoot) {
   const missingCreates = new Set(verification.missingCreates);
   const mismatchedTargets = new Set(verification.propertyMismatches.map((item) => item.target));
   const mismatchedMoves = new Set(verification.moveMismatches.map((item) => item.target));
+  const mismatchedMetadata = new Set(verification.metadataMismatches.map((item) => item.target));
   return operations.filter((operation) => {
     if (operation.op === "create") {
       const parentPath = resolveRefPath(operation.parent, knownPaths);
       return Boolean(parentPath && missingCreates.has(pathKey([...parentPath, operation.name])));
     }
+    if (operation.op === "clone") return false;
     if (operation.op === "setProperties") return mismatchedTargets.has(refLabel(operation.target));
+    if (operation.op === "setAttributes" || operation.op === "updateTags") {
+      return mismatchedMetadata.has(refLabel(operation.target));
+    }
     return mismatchedMoves.has(refLabel(operation.target));
   });
 }
@@ -1846,7 +2469,7 @@ function isParallelRefWithinScopes(ref2, scopes) {
   return scopes.some((scope) => Boolean(ref2.instanceId && scope.instanceId === ref2.instanceId));
 }
 function operationTarget(operation) {
-  if (operation.op === "create") {
+  if (operation.op === "create" || operation.op === "clone") {
     const parentPath = operation.parent.pathSegments;
     return {
       key: `${refKey(operation.parent)}/create:${operation.name}`,
@@ -1951,37 +2574,50 @@ function emit(server, type, data) {
 function toErrorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
-var propertiesSchema2 = z.record(z.unknown()).refine(
+var propertiesSchema3 = z.record(z.unknown()).refine(
   (properties) => Object.keys(properties).length <= 100 && !Object.keys(properties).some((name) => ["Parent", "ClassName", "Source"].includes(name)),
   "At most 100 properties are allowed; Parent, ClassName, and Source require dedicated operations"
 );
 var setPropertiesOperation = z.object({
   op: z.literal("setProperties"),
   target: instanceRefSchema,
-  properties: propertiesSchema2
+  properties: propertiesSchema3
 });
 var createOperation = z.object({
   op: z.literal("create"),
   parent: instanceRefSchema,
   className: z.string().min(1).max(100),
   name: z.string().min(1).max(256),
-  properties: propertiesSchema2.optional()
+  properties: propertiesSchema3.optional()
 });
 var moveOperation = z.object({
   op: z.literal("move"),
   target: instanceRefSchema,
   parent: instanceRefSchema
 });
+var cloneOperation = z.object({
+  op: z.literal("clone"),
+  target: instanceRefSchema,
+  parent: instanceRefSchema.optional(),
+  name: z.string().min(1).max(100).optional(),
+  offset: z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }).optional(),
+  properties: propertiesSchema3.optional()
+});
+var setAttributesOperation = attributeUpdateSchema.extend({ op: z.literal("setAttributes") });
+var updateTagsOperation = tagUpdateSchema.extend({ op: z.literal("updateTags") });
 var mutationOperation = z.discriminatedUnion("op", [
   setPropertiesOperation,
   createOperation,
-  moveOperation
+  cloneOperation,
+  moveOperation,
+  setAttributesOperation,
+  updateTagsOperation
 ]);
 var uiNodeSchema = z.lazy(
   () => z.object({
     ClassName: z.string().min(1).max(100),
     Name: z.string().min(1).max(256).optional(),
-    properties: propertiesSchema2.optional(),
+    properties: propertiesSchema3.optional(),
     Children: z.array(uiNodeSchema).max(1e3).optional()
   })
 );
@@ -2085,7 +2721,7 @@ function registerStudioTools(server, bridge) {
     "studio_apply",
     {
       title: "Apply Atomic Studio Mutations",
-      description: "Atomically set properties, create instances, and move instances. Any failed operation cancels and undoes the entire batch.",
+      description: "Atomically set properties or typed attributes, update tags, create instances, deep-clone instances, and move instances. Any failed operation cancels and undoes the entire batch.",
       inputSchema: { operations: z.array(mutationOperation).min(1).max(100) },
       outputSchema: toolOutputSchema,
       annotations: {
@@ -2211,7 +2847,7 @@ function registerStudioTools(server, bridge) {
     "studio_get_reflection",
     {
       title: "Read Live Roblox Reflection",
-      description: "Read current ReflectionService fields for a class in the connected Studio, including Type, Display category, and permission metadata.",
+      description: "Read current ReflectionService fields for a class in the connected Studio, including Type, Display category, and permission metadata. Reflection discovers APIs but does not grant call permission; use studio_list_callable_methods for that.",
       inputSchema: { className: z.string().min(1).max(100) },
       outputSchema: toolOutputSchema,
       annotations: {
@@ -2226,7 +2862,7 @@ function registerStudioTools(server, bridge) {
 }
 
 // src/mcp/server.ts
-var VERSION = "2.2.1";
+var VERSION = "2.4.0";
 function createDominusMcpServer(bridge) {
   const server = new McpServer(
     {
@@ -2239,6 +2875,8 @@ function createDominusMcpServer(bridge) {
   );
   registerConnectionTools(server, bridge);
   registerStudioTools(server, bridge);
+  registerBuildingTools(server, bridge);
+  registerMetadataTools(server, bridge);
   registerParallelTaskTool(server, bridge);
   registerDocsTools(server);
   registerDominusResources(server, bridge);