pi-revit 0.4.0 → 0.5.0

package/src/Revit/Tools/ChangeElementTypes.cs

@@ -1,60 +1,74 @@
-using System.Text.Json;
-using Autodesk.Revit.DB;
-
-namespace RevitBridge.Tools;
-
-internal sealed class ChangeElementTypes : ITool
-{
-    public string Name => "change_element_types";
-    public string Label => "Change Element Types";
-    public string Tier => "advanced";
-    public bool Write => true;
-    public string Description => "Change the type of 1–200 elements using explicit element_id/type_id pairs. Revit validates each type against the target; invalid or pinned targets are reported per update. Some type changes replace the original element: always use resulting_id/unique_id afterward. Default partial success; atomic=true rolls back all if any update fails. preview=true commit-validates then rolls back, and replacement IDs from previews are temporary. Revit constraints can affect connected/hosted elements; results describe requested targets, not every dependent effect.";
-    public object ParametersSchema => new
-    {
-        type = "object", properties = new
-        {
-            updates = new { type = "array", minItems = 1, maxItems = 200, items = new
-            {
-                type = "object", properties = new { element_id = new { type = "integer", minimum = 1 }, type_id = new { type = "integer", minimum = 1 } },
-                required = new[] { "element_id", "type_id" },
-            } },
-            preview = ModelEditInputs.PreviewSchema,
-            atomic = new { type = "boolean", description = "Roll back the complete batch if any update fails. Default false." },
-        }, required = new[] { "updates" },
-    };
-    public object Execute(JsonElement args, ToolContext context)
-    {
-        var doc = context.Document ?? throw new NoActiveDocumentException();
-        if (!args.TryGetProperty("updates", out var updates) || updates.ValueKind != JsonValueKind.Array || updates.GetArrayLength() is < 1 or > 200)
-            throw new ArgumentException("updates must contain 1–200 element_id/type_id pairs.");
-        var seen = new HashSet<long>();
-        var steps = new List<ModelEditBatch.Step>();
-        foreach (var update in updates.EnumerateArray())
-        {
-            long elementId = JsonArgs.GetLong(update, "element_id") ?? 0;
-            long typeId = JsonArgs.GetLong(update, "type_id") ?? 0;
-            if (elementId <= 0 || typeId <= 0 || !seen.Add(elementId)) throw new ArgumentException("Each update needs positive IDs, and element_id must be unique within the batch.");
-            steps.Add(new(new() { ["element_id"] = elementId, ["type_id"] = typeId }, () =>
-            {
-                var element = doc.GetElement(new ElementId(elementId)) ?? throw new ArgumentException($"Element {elementId} not found.");
-                if (element.Pinned) throw new ArgumentException("Target is pinned; it was not unpinned.");
-                var type = doc.GetElement(new ElementId(typeId)) as ElementType ?? throw new ArgumentException($"Type {typeId} not found.");
-                if (!element.IsValidType(type.Id)) throw new ArgumentException($"Type {typeId} is not valid for element {elementId}.");
-                var before = ModelEditInputs.Snapshot(element);
-                var replacement = element.ChangeTypeId(type.Id);
-                doc.Regenerate();
-                var resultId = replacement == ElementId.InvalidElementId ? new ElementId(elementId) : replacement;
-                var result = doc.GetElement(resultId) ?? throw new InvalidOperationException("Changed element could not be resolved.");
-                return new() { ["before"] = before, ["after"] = ModelEditInputs.Snapshot(result),
-                    ["resulting_id"] = result.Id.Value, ["unique_id"] = result.UniqueId,
-                    ["replaced"] = result.Id.Value != elementId,
-                    ["resulting_id_is_temporary"] = result.Id.Value != elementId && JsonArgs.GetBool(args, "preview", false) };
-            }));
-        }
-        var batch = ModelEditBatch.Run(doc, Name, args, steps);
-        foreach (var row in batch.Proposed)
-            if (row["replaced"] is true) row["resulting_id_is_temporary"] = true;
-        return batch.Payload;
-    }
-}
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class ChangeElementTypes : ITool
+{
+    /// <summary>Updates whose per-view graphics are scanned; each scan visits every view.</summary>
+    private const int ViewGraphicsLimit = 20;
+    public string Name => "change_element_types";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+    public IReadOnlyList<string> Keywords => new[] { "swap type", "replace type", "change family type", "retype", "switch type" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Editing a type definition's parameters", "tool", "set_parameters"),
+        new ToolLimit("Creating a new type", "api", "ElementType.Duplicate"),
+        new ToolLimit("Loading a family", "api", "Document.LoadFamily"),
+    };
+    public string? Verification => "reread";
+    public string Label => "Change Element Types";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "Change the type of 1–200 elements using explicit element_id/type_id pairs. Revit validates each type against the target; invalid or pinned targets are reported per update. Some type changes replace the original element: always use resulting_id/unique_id afterward. Each update reports inherited_state: instance values, traits and, for the first 20 updates, views that hide or override the retyped element. Default partial success; atomic=true rolls back all if any update fails. preview=true commit-validates then rolls back, and replacement IDs from previews are temporary. Revit constraints can affect connected/hosted elements; results describe requested targets, not every dependent effect.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            updates = new { type = "array", minItems = 1, maxItems = 200, items = new
+            {
+                type = "object", properties = new { element_id = new { type = "integer", minimum = 1 }, type_id = new { type = "integer", minimum = 1 } },
+                required = new[] { "element_id", "type_id" },
+            } },
+            preview = ModelEditInputs.PreviewSchema,
+            atomic = new { type = "boolean", description = "Roll back the complete batch if any update fails. Default false." },
+        }, required = new[] { "updates" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        if (!args.TryGetProperty("updates", out var updates) || updates.ValueKind != JsonValueKind.Array || updates.GetArrayLength() is < 1 or > 200)
+            throw new ArgumentException("updates must contain 1–200 element_id/type_id pairs.");
+        var seen = new HashSet<long>();
+        var steps = new List<ModelEditBatch.Step>();
+        foreach (var update in updates.EnumerateArray())
+        {
+            long elementId = JsonArgs.GetLong(update, "element_id") ?? 0;
+            long typeId = JsonArgs.GetLong(update, "type_id") ?? 0;
+            if (elementId <= 0 || typeId <= 0 || !seen.Add(elementId)) throw new ArgumentException("Each update needs positive IDs, and element_id must be unique within the batch.");
+            int index = steps.Count;
+            steps.Add(new(new() { ["element_id"] = elementId, ["type_id"] = typeId }, () =>
+            {
+                var element = doc.GetElement(new ElementId(elementId)) ?? throw new ArgumentException($"Element {elementId} not found.");
+                if (element.Pinned) throw new ArgumentException("Target is pinned; it was not unpinned.");
+                var type = doc.GetElement(new ElementId(typeId)) as ElementType ?? throw new ArgumentException($"Type {typeId} not found.");
+                if (!element.IsValidType(type.Id)) throw new ArgumentException($"Type {typeId} is not valid for element {elementId}.");
+                var before = ModelEditInputs.Snapshot(element);
+                var replacement = element.ChangeTypeId(type.Id);
+                doc.Regenerate();
+                var resultId = replacement == ElementId.InvalidElementId ? new ElementId(elementId) : replacement;
+                var result = doc.GetElement(resultId) ?? throw new InvalidOperationException("Changed element could not be resolved.");
+                return new() { ["before"] = before, ["after"] = ModelEditInputs.Snapshot(result),
+                    ["resulting_id"] = result.Id.Value, ["unique_id"] = result.UniqueId,
+                    ["replaced"] = result.Id.Value != elementId,
+                    ["resulting_id_is_temporary"] = result.Id.Value != elementId && JsonArgs.GetBool(args, "preview", false),
+                    // What the retyped element keeps: instance values, traits and per-view graphics (inv:derived-state-reported).
+                    ["inherited_state"] = InheritedState.OfElement(result, result.Id.Value != elementId ? elementId : null, viewGraphics: index < ViewGraphicsLimit) };
+            }));
+        }
+        var batch = ModelEditBatch.Run(doc, Name, args, steps);
+        foreach (var row in batch.Proposed)
+            if (row["replaced"] is true) row["resulting_id_is_temporary"] = true;
+        return batch.Payload;
+    }
+}

package/src/Revit/Tools/ChangeSet.cs

@@ -0,0 +1,39 @@
+namespace RevitBridge.Tools
+{
+    /// <summary>
+    /// Net element changes of one tool call, from Revit's DocumentChanged operations. Pure, so it
+    /// is tested offline. A rolled-back or undone group discards what was recorded before it, so a
+    /// preview (commit inside a rolled-back group) reports no net change.
+    /// </summary>
+    internal sealed class ChangeSet
+    {
+        private readonly HashSet<long> _added = new(), _modified = new(), _deleted = new();
+        public bool Observed { get; private set; }
+        public bool RolledBack { get; private set; }
+        public IReadOnlyCollection<long> Added => _added;
+        public IReadOnlyCollection<long> Modified => _modified;
+        public IReadOnlyCollection<long> Deleted => _deleted;
+
+        public void Record(string operation, IEnumerable<long> added, IEnumerable<long> modified, IEnumerable<long> deleted)
+        {
+            Observed = true;
+            if (operation is not ("TransactionCommitted" or "TransactionRedone"))
+            {
+                // Undo or rollback: everything recorded in this call is no longer a net change.
+                _added.Clear(); _modified.Clear(); _deleted.Clear();
+                RolledBack = true;
+                return;
+            }
+            foreach (var id in added) { _added.Add(id); _deleted.Remove(id); }
+            foreach (var id in modified) if (!_added.Contains(id)) _modified.Add(id);
+            foreach (var id in deleted)
+            {
+                _modified.Remove(id);
+                // Created and deleted within one call leaves nothing behind.
+                if (!_added.Remove(id)) _deleted.Add(id);
+            }
+        }
+
+        public bool IsEmpty => _added.Count == 0 && _modified.Count == 0 && _deleted.Count == 0;
+    }
+}

package/src/Revit/Tools/CreateTags.cs

@@ -1,95 +1,107 @@
-using System.Text.Json;
-using Autodesk.Revit.DB;
-using Autodesk.Revit.DB.Architecture;
-using Autodesk.Revit.DB.Mechanical;
-
-namespace RevitBridge.Tools;
-
-internal sealed class CreateTags : ITool
-{
-    public string Name => "create_tags";
-    public string Label => "Create Tags";
-    public string Tier => "advanced";
-    public bool Write => true;
-    public string Description => "Create up to 100 tags for host-document elements in one explicit view using a loaded tag FamilySymbol. kind=element uses IndependentTag; room, space and area use their corresponding spatial tag APIs. Targets contain element_id and head_position [x,y,z] in document internal coordinates with explicit length unit. head_position always means the tag head, including with leader=true. Spatial tags require a compatible plan view and positions at that spatial element's level; orientation applies only to element tags. Templates, perspective views and unlocked 3D views cannot host independent tags. Default partial success; atomic=true rolls back all on any failure. preview=true commit-validates then rolls back; all proposed tag IDs are temporary. Linked targets and face/subelement references are outside this tool.";
-    public object ParametersSchema => new
-    {
-        type = "object", properties = new
-        {
-            kind = new { type = "string", @enum = new[] { "element", "room", "space", "area" } },
-            view_id = new { type = "integer", minimum = 1 }, tag_type_id = new { type = "integer", minimum = 1 }, unit = ModelEditInputs.LengthUnitSchema,
-            targets = new { type = "array", minItems = 1, maxItems = 100, items = new { type = "object", properties = new { element_id = new { type = "integer", minimum = 1 }, head_position = ModelEditInputs.VectorSchema("Tag head in document internal coordinates, in unit.") }, required = new[] { "element_id", "head_position" } } },
-            leader = new { type = "boolean" }, orientation = new { type = "string", @enum = new[] { "horizontal", "vertical" } },
-            preview = ModelEditInputs.PreviewSchema, atomic = new { type = "boolean" },
-        }, required = new[] { "kind", "view_id", "tag_type_id", "unit", "targets" },
-    };
-    public object Execute(JsonElement args, ToolContext context)
-    {
-        var doc = context.Document ?? throw new NoActiveDocumentException();
-        string kind = JsonArgs.GetString(args, "kind") ?? "";
-        if (kind is not ("element" or "room" or "space" or "area")) throw new ArgumentException("Unknown tag kind.");
-        var view = doc.GetElement(new ElementId(JsonArgs.GetLong(args, "view_id") ?? 0)) as View ?? throw new ArgumentException("view_id is not a view.");
-        if (view.IsTemplate || (view is View3D three && (three.IsPerspective || !three.IsLocked))) throw new ArgumentException("Tags require a non-template view; 3D views must be orthographic and locked.");
-        if (kind != "element" && view is not ViewPlan) throw new ArgumentException("Spatial tags require a plan view.");
-        var type = doc.GetElement(new ElementId(JsonArgs.GetLong(args, "tag_type_id") ?? 0)) as FamilySymbol ?? throw new ArgumentException("tag_type_id must identify a loaded tag FamilySymbol.");
-        bool leader = false;
-        if (args.TryGetProperty("leader", out var leaderValue))
-        {
-            if (leaderValue.ValueKind is not (JsonValueKind.True or JsonValueKind.False)) throw new ArgumentException("leader must be boolean.");
-            leader = leaderValue.GetBoolean();
-        }
-        if (kind != "element" && args.TryGetProperty("orientation", out _)) throw new ArgumentException("orientation applies only to element tags.");
-        var orientation = (JsonArgs.GetString(args, "orientation") ?? "horizontal") switch
-        {
-            "horizontal" => TagOrientation.Horizontal, "vertical" => TagOrientation.Vertical, _ => throw new ArgumentException("Invalid orientation."),
-        };
-        if (!args.TryGetProperty("targets", out var targets) || targets.ValueKind != JsonValueKind.Array || targets.GetArrayLength() is < 1 or > 100) throw new ArgumentException("targets must contain 1–100 tag requests.");
-        double scale = ModelEditInputs.LengthScale(args);
-        var steps = new List<ModelEditBatch.Step>();
-        foreach (var input in targets.EnumerateArray())
-        {
-            if (input.ValueKind != JsonValueKind.Object) throw new ArgumentException("Each target must be an object.");
-            long id = JsonArgs.GetLong(input, "element_id") ?? 0;
-            if (id <= 0) throw new ArgumentException("Target element_id must be positive.");
-            var point = ModelEditInputs.Vector(input, "head_position").Multiply(scale);
-            steps.Add(new(new() { ["element_id"] = id }, () =>
-            {
-                var element = doc.GetElement(new ElementId(id)) ?? throw new ArgumentException($"Element {id} not found.");
-                if (!type.IsActive) { type.Activate(); doc.Regenerate(); }
-                Element tag;
-                if (kind == "element")
-                {
-                    var independent = IndependentTag.Create(doc, type.Id, view.Id, new Reference(element), false, orientation, point);
-                    independent.HasLeader = leader;
-                    independent.TagHeadPosition = point;
-                    tag = independent;
-                }
-                else
-                {
-                    if (element.Location is not LocationPoint location || view.GenLevel == null || element.LevelId != view.GenLevel.Id)
-                        throw new ArgumentException("A spatial tag target must be placed on the plan view's level.");
-                    var anchor = new UV(location.Point.X, location.Point.Y);
-                    SpatialElementTag spatial = kind switch
-                    {
-                        "room" when element is Room => doc.Create.NewRoomTag(new LinkElementId(element.Id), anchor, view.Id),
-                        "space" when element is Space space => doc.Create.NewSpaceTag(space, anchor, view),
-                        "area" when element is Area area => doc.Create.NewAreaTag((ViewPlan)view, area, anchor),
-                        _ => throw new ArgumentException($"Element {id} does not match kind {kind}."),
-                    };
-                    if (!spatial.IsValidType(type.Id)) throw new ArgumentException("Tag type does not match the spatial tag category.");
-                    var replacement = spatial.ChangeTypeId(type.Id);
-                    if (replacement != ElementId.InvalidElementId) spatial = (SpatialElementTag)doc.GetElement(replacement);
-                    spatial.HasLeader = leader; spatial.TagHeadPosition = point;
-                    tag = spatial;
-                }
-                doc.Regenerate();
-                var actual = tag is IndependentTag independentResult ? independentResult.TagHeadPosition : ((SpatialElementTag)tag).TagHeadPosition;
-                return new() { ["tag_id"] = tag.Id.Value, ["unique_id"] = tag.UniqueId, ["tag_type_id"] = tag.GetTypeId().Value, ["view_id"] = tag.OwnerViewId.Value,
-                    ["kind"] = kind, ["head_position"] = new[] { actual.X, actual.Y, actual.Z }, ["unit"] = "feet", ["leader"] = leader, ["id_is_temporary"] = false };
-            }));
-        }
-        var batch = ModelEditBatch.Run(doc, Name, args, steps);
-        foreach (var row in batch.Proposed) row["id_is_temporary"] = true;
-        return batch.Payload;
-    }
-}
+using System.Text.Json;
+using Autodesk.Revit.DB;
+using Autodesk.Revit.DB.Architecture;
+using Autodesk.Revit.DB.Mechanical;
+
+namespace RevitBridge.Tools;
+
+internal sealed class CreateTags : ITool
+{
+    public string Name => "create_tags";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.ProjectOnly;
+    public IReadOnlyList<string> Keywords => new[] { "tag", "label", "annotate", "annotation", "room tag", "door tag" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Tagging elements inside linked models", "api", "Reference.CreateLinkReference; IndependentTag.Create"),
+        new ToolLimit("Tagging faces or subelements", "api", "IndependentTag.Create with a face Reference"),
+        new ToolLimit("Creating or loading tag families", "api", "Document.LoadFamily"),
+        new ToolLimit("Text notes, dimensions and other annotation", "api", "TextNote.Create; Creation.ItemFactoryBase.NewDimension"),
+    };
+    public string? Verification => "capture";
+    public string Label => "Create Tags";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "Create up to 100 tags for host-document elements in one explicit view using a loaded tag FamilySymbol. kind=element uses IndependentTag; room, space and area use their corresponding spatial tag APIs. Targets contain element_id and head_position [x,y,z] in document internal coordinates with explicit length unit. head_position always means the tag head, including with leader=true. Spatial tags require a compatible plan view and positions at that spatial element's level; orientation applies only to element tags. Templates, perspective views and unlocked 3D views cannot host independent tags. Default partial success; atomic=true rolls back all on any failure. preview=true commit-validates then rolls back; all proposed tag IDs are temporary. Linked targets and face/subelement references are outside this tool.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            kind = new { type = "string", @enum = new[] { "element", "room", "space", "area" } },
+            view_id = new { type = "integer", minimum = 1 }, tag_type_id = new { type = "integer", minimum = 1 }, unit = ModelEditInputs.LengthUnitSchema,
+            targets = new { type = "array", minItems = 1, maxItems = 100, items = new { type = "object", properties = new { element_id = new { type = "integer", minimum = 1 }, head_position = ModelEditInputs.VectorSchema("Tag head in document internal coordinates, in unit.") }, required = new[] { "element_id", "head_position" } } },
+            leader = new { type = "boolean" }, orientation = new { type = "string", @enum = new[] { "horizontal", "vertical" } },
+            preview = ModelEditInputs.PreviewSchema, atomic = new { type = "boolean" },
+        }, required = new[] { "kind", "view_id", "tag_type_id", "unit", "targets" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        string kind = JsonArgs.GetString(args, "kind") ?? "";
+        if (kind is not ("element" or "room" or "space" or "area")) throw new ArgumentException("Unknown tag kind.");
+        var view = doc.GetElement(new ElementId(JsonArgs.GetLong(args, "view_id") ?? 0)) as View ?? throw new ArgumentException("view_id is not a view.");
+        if (view.IsTemplate || (view is View3D three && (three.IsPerspective || !three.IsLocked))) throw new ArgumentException("Tags require a non-template view; 3D views must be orthographic and locked.");
+        if (kind != "element" && view is not ViewPlan) throw new ArgumentException("Spatial tags require a plan view.");
+        var type = doc.GetElement(new ElementId(JsonArgs.GetLong(args, "tag_type_id") ?? 0)) as FamilySymbol ?? throw new ArgumentException("tag_type_id must identify a loaded tag FamilySymbol.");
+        bool leader = false;
+        if (args.TryGetProperty("leader", out var leaderValue))
+        {
+            if (leaderValue.ValueKind is not (JsonValueKind.True or JsonValueKind.False)) throw new ArgumentException("leader must be boolean.");
+            leader = leaderValue.GetBoolean();
+        }
+        if (kind != "element" && args.TryGetProperty("orientation", out _)) throw new ArgumentException("orientation applies only to element tags.");
+        var orientation = (JsonArgs.GetString(args, "orientation") ?? "horizontal") switch
+        {
+            "horizontal" => TagOrientation.Horizontal, "vertical" => TagOrientation.Vertical, _ => throw new ArgumentException("Invalid orientation."),
+        };
+        if (!args.TryGetProperty("targets", out var targets) || targets.ValueKind != JsonValueKind.Array || targets.GetArrayLength() is < 1 or > 100) throw new ArgumentException("targets must contain 1–100 tag requests.");
+        double scale = ModelEditInputs.LengthScale(args);
+        var steps = new List<ModelEditBatch.Step>();
+        foreach (var input in targets.EnumerateArray())
+        {
+            if (input.ValueKind != JsonValueKind.Object) throw new ArgumentException("Each target must be an object.");
+            long id = JsonArgs.GetLong(input, "element_id") ?? 0;
+            if (id <= 0) throw new ArgumentException("Target element_id must be positive.");
+            var point = ModelEditInputs.Vector(input, "head_position").Multiply(scale);
+            steps.Add(new(new() { ["element_id"] = id }, () =>
+            {
+                var element = doc.GetElement(new ElementId(id)) ?? throw new ArgumentException($"Element {id} not found.");
+                if (!type.IsActive) { type.Activate(); doc.Regenerate(); }
+                Element tag;
+                if (kind == "element")
+                {
+                    var independent = IndependentTag.Create(doc, type.Id, view.Id, new Reference(element), false, orientation, point);
+                    independent.HasLeader = leader;
+                    independent.TagHeadPosition = point;
+                    tag = independent;
+                }
+                else
+                {
+                    if (element.Location is not LocationPoint location || view.GenLevel == null || element.LevelId != view.GenLevel.Id)
+                        throw new ArgumentException("A spatial tag target must be placed on the plan view's level.");
+                    var anchor = new UV(location.Point.X, location.Point.Y);
+                    SpatialElementTag spatial = kind switch
+                    {
+                        "room" when element is Room => doc.Create.NewRoomTag(new LinkElementId(element.Id), anchor, view.Id),
+                        "space" when element is Space space => doc.Create.NewSpaceTag(space, anchor, view),
+                        "area" when element is Area area => doc.Create.NewAreaTag((ViewPlan)view, area, anchor),
+                        _ => throw new ArgumentException($"Element {id} does not match kind {kind}."),
+                    };
+                    if (!spatial.IsValidType(type.Id)) throw new ArgumentException("Tag type does not match the spatial tag category.");
+                    var replacement = spatial.ChangeTypeId(type.Id);
+                    if (replacement != ElementId.InvalidElementId) spatial = (SpatialElementTag)doc.GetElement(replacement);
+                    spatial.HasLeader = leader; spatial.TagHeadPosition = point;
+                    tag = spatial;
+                }
+                doc.Regenerate();
+                var actual = tag is IndependentTag independentResult ? independentResult.TagHeadPosition : ((SpatialElementTag)tag).TagHeadPosition;
+                return new() { ["tag_id"] = tag.Id.Value, ["unique_id"] = tag.UniqueId, ["tag_type_id"] = tag.GetTypeId().Value, ["view_id"] = tag.OwnerViewId.Value,
+                    ["kind"] = kind, ["head_position"] = new[] { actual.X, actual.Y, actual.Z }, ["unit"] = "feet", ["leader"] = leader, ["id_is_temporary"] = false,
+                    // A retyped spatial tag may be replaced by a new element (inv:derived-state-reported).
+                    ["inherited_state"] = InheritedState.OfElement(tag, null) };
+            }));
+        }
+        var batch = ModelEditBatch.Run(doc, Name, args, steps);
+        foreach (var row in batch.Proposed) row["id_is_temporary"] = true;
+        return batch.Payload;
+    }
+}

package/src/Revit/Tools/DeleteElements.cs

@@ -1,44 +1,53 @@
-using System.Text.Json;
-using Autodesk.Revit.DB;
-
-namespace RevitBridge.Tools;
-
-internal sealed class DeleteElements : ITool
-{
-    public string Name => "delete_elements";
-    public string Label => "Delete Elements";
-    public string Tier => "advanced";
-    public bool Write => true;
-    public string Description => "Delete 1–200 explicitly selected elements in one atomic step, returning the full set of IDs returned by Revit's deletion API, including dependents. Use preview=true to inspect that set with commit validation and confirmed rollback. Optional expected_deleted_ids rejects a changed deletion set before commit; pass the full preview set to bind a later deletion to that set. Pinned requested elements are rejected. At most 10,000 deleted IDs are permitted; a larger cascade rolls back. Returned IDs include dependencies removed by Document.Delete, not a complete audit of surviving elements modified by Revit.";
-    public object ParametersSchema => new
-    {
-        type = "object", properties = new
-        {
-            element_ids = ModelEditInputs.IdsSchema,
-            preview = ModelEditInputs.PreviewSchema,
-            expected_deleted_ids = new { type = "array", minItems = 1, maxItems = 10000, uniqueItems = true, items = new { type = "integer", minimum = 1 }, description = "Exact full deleted_ids set from a previous preview; mismatches roll back." },
-        }, required = new[] { "element_ids" },
-    };
-    public object Execute(JsonElement args, ToolContext context)
-    {
-        var doc = context.Document ?? throw new NoActiveDocumentException();
-        var ids = ModelEditInputs.Ids(args);
-        List<long>? expected = args.TryGetProperty("expected_deleted_ids", out _) ? JsonArgs.GetLongArray(args, "expected_deleted_ids") : null;
-        if (expected != null && (expected.Count is < 1 or > 10000 || expected.Any(x => x <= 0) || expected.Distinct().Count() != expected.Count))
-            throw new ArgumentException("expected_deleted_ids must contain 1–10,000 distinct positive IDs.");
-        return ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(
-            new() { ["element_ids"] = ids.Select(x => x.Value).ToArray() }, () =>
-            {
-                foreach (var id in ids)
-                {
-                    var element = doc.GetElement(id) ?? throw new ArgumentException($"Element {id.Value} not found.");
-                    if (element.Pinned) throw new ArgumentException($"Element {id.Value} is pinned; no elements were unpinned.");
-                }
-                var deleted = doc.Delete(ids).Select(id => id.Value).OrderBy(id => id).ToArray();
-                if (deleted.Length > 10000) throw new ArgumentException("Deletion exceeds the 10,000-ID cascade limit.");
-                if (expected != null && !deleted.ToHashSet().SetEquals(expected)) throw new ArgumentException("The deletion set changed since the preview; deletion was rolled back. Run a fresh preview.");
-                return new() { ["deleted_ids"] = deleted, ["deleted_count"] = deleted.Length,
-                    ["dependent_ids"] = deleted.Except(ids.Select(x => x.Value)).ToArray() };
-            }) }).Payload;
-    }
-}
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class DeleteElements : ITool
+{
+    public string Name => "delete_elements";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+    public IReadOnlyList<string> Keywords => new[] { "remove", "erase", "cleanup", "delete view", "delete sheet" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Pinned elements (rejected, never unpinned automatically)", "user", "Confirm unpinning (Element.Pinned) first"),
+        new ToolLimit("Elements inside linked models", "user", "Edit the linked model itself"),
+        new ToolLimit("One-step purge of unused types", "tool", "get_element_types with include_instance_count, then delete_elements"),
+    };
+    public string? Verification => "reread";
+    public string Label => "Delete Elements";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "Delete 1–200 explicitly selected elements in one atomic step, returning the full set of IDs returned by Revit's deletion API, including dependents. Use preview=true to inspect that set with commit validation and confirmed rollback. Optional expected_deleted_ids rejects a changed deletion set before commit; pass the full preview set to bind a later deletion to that set. Pinned requested elements are rejected. At most 10,000 deleted IDs are permitted; a larger cascade rolls back. Returned IDs include dependencies removed by Document.Delete, not a complete audit of surviving elements modified by Revit.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            element_ids = ModelEditInputs.IdsSchema,
+            preview = ModelEditInputs.PreviewSchema,
+            expected_deleted_ids = new { type = "array", minItems = 1, maxItems = 10000, uniqueItems = true, items = new { type = "integer", minimum = 1 }, description = "Exact full deleted_ids set from a previous preview; mismatches roll back." },
+        }, required = new[] { "element_ids" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        var ids = ModelEditInputs.Ids(args);
+        List<long>? expected = args.TryGetProperty("expected_deleted_ids", out _) ? JsonArgs.GetLongArray(args, "expected_deleted_ids") : null;
+        if (expected != null && (expected.Count is < 1 or > 10000 || expected.Any(x => x <= 0) || expected.Distinct().Count() != expected.Count))
+            throw new ArgumentException("expected_deleted_ids must contain 1–10,000 distinct positive IDs.");
+        return ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(
+            new() { ["element_ids"] = ids.Select(x => x.Value).ToArray() }, () =>
+            {
+                foreach (var id in ids)
+                {
+                    var element = doc.GetElement(id) ?? throw new ArgumentException($"Element {id.Value} not found.");
+                    if (element.Pinned) throw new ArgumentException($"Element {id.Value} is pinned; no elements were unpinned.");
+                }
+                var deleted = doc.Delete(ids).Select(id => id.Value).OrderBy(id => id).ToArray();
+                if (deleted.Length > 10000) throw new ArgumentException("Deletion exceeds the 10,000-ID cascade limit.");
+                if (expected != null && !deleted.ToHashSet().SetEquals(expected)) throw new ArgumentException("The deletion set changed since the preview; deletion was rolled back. Run a fresh preview.");
+                return new() { ["deleted_ids"] = deleted, ["deleted_count"] = deleted.Length,
+                    ["dependent_ids"] = deleted.Except(ids.Select(x => x.Value)).ToArray() };
+            }) }).Payload;
+    }
+}