pi-revit 0.4.0 → 0.5.0

package/src/Revit/Tools/ToolContract.cs

@@ -0,0 +1,48 @@
+namespace RevitBridge
+{
+    /// <summary>
+    /// A declared capability boundary: something the tool deliberately does not cover and
+    /// the route to use instead. Alternative kinds: "tool" (Ref names another public tool),
+    /// "api" (Ref names Revit API members to verify with search_api_docs before custom
+    /// execution), "user" (needs a user action or decision), or "revit_unsupported" (the
+    /// Revit API itself does not offer it; Ref states the evidence). A limit never ends at
+    /// "unsupported" without a route, so agents do not report a false impossibility.
+    /// Kept in its own file so every project that compiles tool sources shares one type.
+    /// </summary>
+    internal sealed record ToolLimit(string What, string Alternative, string? Ref = null)
+    {
+        public static readonly IReadOnlyList<string> AlternativeKinds = new[] { "tool", "api", "user", "revit_unsupported" };
+    }
+
+    /// <summary>Allowed ITool.Verification values; see ITool.Verification.</summary>
+    internal static class ToolVerification
+    {
+        public static readonly IReadOnlyList<string> Kinds = new[] { "reread", "capture", "inspect_output", "none" };
+    }
+
+    /// <summary>
+    /// Document kinds a tool works in (inv:document-kind-declared). Every bridge tool declares
+    /// ITool.DocumentKinds; the dispatcher refuses any other kind before the tool runs, with the
+    /// route to use instead. Revit-free, so the refusal is tested offline.
+    /// </summary>
+    internal static class DocumentKind
+    {
+        public const string Project = "project";
+        public const string Family = "family";
+        public static readonly IReadOnlyList<string> Both = new[] { Project, Family };
+        public static readonly IReadOnlyList<string> ProjectOnly = new[] { Project };
+
+        /// <summary>Revit API route for family types, parameters and formulas; also a declared limit alternative.</summary>
+        public const string FamilyApi = "FamilyManager.Types; FamilyManager.NewType; FamilyManager.Set; FamilyManager.AddParameter; FamilyManager.SetFormula";
+
+        /// <summary>Why a tool cannot run in the active document, with the alternative; null when it can.</summary>
+        public static string? Refusal(string tool, IReadOnlyList<string> supported, string active, string title)
+        {
+            if (supported.Count == 0 || supported.Contains(active)) return null;
+            string route = active == Family
+                ? $"A family document has no sheets, schedules, rooms, links or project coordinates. For family types, parameters and formulas use the Revit API: verify '{FamilyApi}' with search_api_docs, then use execute_csharp."
+                : "Open the family for editing (Document.EditFamily) or ask the user to open the family document.";
+            return $"{tool} works in {string.Join(" and ", supported)} documents; the active document '{title}' is a {active} document. Nothing was run. {route}";
+        }
+    }
+}

package/src/Revit/Tools/ToolSupport.cs

@@ -191,6 +191,10 @@ namespace RevitBridge.Tools
                     _ => null,
                 };
             }
+            // Shared projection: special or system-owned objects are flagged for every tool
+            // that lists elements (inv:special-objects-flagged). Ordinary elements add nothing.
+            if (ElementTraits.For(element) is { } traits)
+                row["traits"] = traits;
             return row;
         }
     }
@@ -259,4 +263,4 @@ namespace RevitBridge.Tools
         }
     }
 
-}
+}

package/src/Revit/Tools/TransformElements.cs

@@ -1,58 +1,73 @@
-using System.Text.Json;
-using Autodesk.Revit.DB;
-
-namespace RevitBridge.Tools;
-
-internal sealed class TransformElements : ITool
-{
-    public string Name => "transform_elements";
-    public string Label => "Transform Elements";
-    public string Tier => "advanced";
-    public bool Write => true;
-    public string Description => "Move, copy or rotate 1–200 elements together in the active document. Coordinates use the document internal origin and axes; unit is required. Rotation uses a right-handed axis and angle_degrees. The whole selection succeeds or rolls back as one step; pinned elements are never automatically unpinned. Revit may move constrained/hosted dependents too. preview=true validates commit then rolls back; any created IDs in a preview are temporary and must not be reused. Snapshots describe requested elements, not a complete dependent-change audit.";
-    public object ParametersSchema => new
-    {
-        type = "object", properties = new
-        {
-            action = new { type = "string", @enum = new[] { "move", "copy", "rotate" } },
-            element_ids = ModelEditInputs.IdsSchema,
-            unit = ModelEditInputs.LengthUnitSchema,
-            translation = ModelEditInputs.VectorSchema("Move/copy displacement [x,y,z] in unit."),
-            axis_origin = ModelEditInputs.VectorSchema("Rotation axis origin [x,y,z] in unit, relative to internal origin."),
-            axis_direction = ModelEditInputs.VectorSchema("Nonzero rotation axis direction [x,y,z], dimensionless."),
-            angle_degrees = new { type = "number", description = "Signed right-hand rotation angle in degrees." },
-            preview = ModelEditInputs.PreviewSchema,
-        }, required = new[] { "action", "element_ids", "unit" },
-    };
-
-    public object Execute(JsonElement args, ToolContext context)
-    {
-        var doc = context.Document ?? throw new NoActiveDocumentException();
-        var ids = ModelEditInputs.Ids(args);
-        string action = JsonArgs.GetString(args, "action") ?? "";
-        if (action is not ("move" or "copy" or "rotate")) throw new ArgumentException("action must be move, copy or rotate.");
-        double scale = ModelEditInputs.LengthScale(args);
-        XYZ? translation = action != "rotate" ? ModelEditInputs.Vector(args, "translation").Multiply(scale) : null;
-        XYZ? origin = action == "rotate" ? ModelEditInputs.Vector(args, "axis_origin").Multiply(scale) : null;
-        XYZ? direction = action == "rotate" ? ModelEditInputs.Vector(args, "axis_direction") : null;
-        double angle = action == "rotate" ? ModelEditInputs.Number(args, "angle_degrees") * Math.PI / 180 : 0;
-        if (direction != null && direction.GetLength() < 1e-12) throw new ArgumentException("axis_direction must be nonzero.");
-        var result = ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(
-            new() { ["action"] = action, ["element_ids"] = ids.Select(x => x.Value).ToArray() }, () =>
-            {
-                var elements = ids.Select(id => doc.GetElement(id) ?? throw new ArgumentException($"Element {id.Value} not found.")).ToArray();
-                if (action != "copy" && elements.Any(e => e.Pinned)) throw new ArgumentException("Selection contains pinned elements; no elements were unpinned.");
-                var before = elements.Select(ModelEditInputs.Snapshot).ToArray();
-                ICollection<ElementId> outputIds = ids;
-                if (action == "move") ElementTransformUtils.MoveElements(doc, ids, translation!);
-                else if (action == "copy") outputIds = ElementTransformUtils.CopyElements(doc, ids, translation!);
-                else ElementTransformUtils.RotateElements(doc, ids, Line.CreateUnbound(origin!, direction!.Normalize()), angle);
-                doc.Regenerate();
-                return new() { ["before"] = before, ["after"] = outputIds.Select(doc.GetElement).Where(e => e != null).Select(ModelEditInputs.Snapshot).ToArray(),
-                    ["created_ids"] = action == "copy" ? outputIds.Select(id => id.Value).ToArray() : Array.Empty<long>(),
-                    ["coordinate_system"] = "document_internal", ["snapshot_unit"] = "feet",
-                    ["created_ids_are_temporary"] = action == "copy" && JsonArgs.GetBool(args, "preview", false) };
-            }) });
-        return result.Payload;
-    }
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class TransformElements : ITool
+{
+    public string Name => "transform_elements";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+    public IReadOnlyList<string> Keywords => new[] { "move", "copy", "rotate", "shift", "offset", "relocate" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Mirroring", "api", "ElementTransformUtils.MirrorElements"),
+        new ToolLimit("Pinned elements (move and rotate reject them)", "user", "Confirm unpinning (Element.Pinned) first"),
+        new ToolLimit("Elements inside linked models", "user", "Edit the linked model itself"),
+    };
+    public string? Verification => "reread";
+    public string Label => "Transform Elements";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "Move, copy or rotate 1–200 elements together in the active document. Coordinates use the document internal origin and axes; unit is required. Rotation uses a right-handed axis and angle_degrees. The whole selection succeeds or rolls back as one step; pinned elements are never automatically unpinned. Revit may move constrained/hosted dependents too. A copy's result reports inherited_state: values and traits the copies carried over, such as Mark, Comments, group or design-option membership. preview=true validates commit then rolls back; any created IDs in a preview are temporary and must not be reused. Snapshots describe requested elements, not a complete dependent-change audit.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            action = new { type = "string", @enum = new[] { "move", "copy", "rotate" } },
+            element_ids = ModelEditInputs.IdsSchema,
+            unit = ModelEditInputs.LengthUnitSchema,
+            translation = ModelEditInputs.VectorSchema("Move/copy displacement [x,y,z] in unit."),
+            axis_origin = ModelEditInputs.VectorSchema("Rotation axis origin [x,y,z] in unit, relative to internal origin."),
+            axis_direction = ModelEditInputs.VectorSchema("Nonzero rotation axis direction [x,y,z], dimensionless."),
+            angle_degrees = new { type = "number", description = "Signed right-hand rotation angle in degrees." },
+            preview = ModelEditInputs.PreviewSchema,
+        }, required = new[] { "action", "element_ids", "unit" },
+    };
+
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        var ids = ModelEditInputs.Ids(args);
+        string action = JsonArgs.GetString(args, "action") ?? "";
+        if (action is not ("move" or "copy" or "rotate")) throw new ArgumentException("action must be move, copy or rotate.");
+        double scale = ModelEditInputs.LengthScale(args);
+        XYZ? translation = action != "rotate" ? ModelEditInputs.Vector(args, "translation").Multiply(scale) : null;
+        XYZ? origin = action == "rotate" ? ModelEditInputs.Vector(args, "axis_origin").Multiply(scale) : null;
+        XYZ? direction = action == "rotate" ? ModelEditInputs.Vector(args, "axis_direction") : null;
+        double angle = action == "rotate" ? ModelEditInputs.Number(args, "angle_degrees") * Math.PI / 180 : 0;
+        if (direction != null && direction.GetLength() < 1e-12) throw new ArgumentException("axis_direction must be nonzero.");
+        var result = ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(
+            new() { ["action"] = action, ["element_ids"] = ids.Select(x => x.Value).ToArray() }, () =>
+            {
+                var elements = ids.Select(id => doc.GetElement(id) ?? throw new ArgumentException($"Element {id.Value} not found.")).ToArray();
+                if (action != "copy" && elements.Any(e => e.Pinned)) throw new ArgumentException("Selection contains pinned elements; no elements were unpinned.");
+                var before = elements.Select(ModelEditInputs.Snapshot).ToArray();
+                ICollection<ElementId> outputIds = ids;
+                if (action == "move") ElementTransformUtils.MoveElements(doc, ids, translation!);
+                else if (action == "copy") outputIds = ElementTransformUtils.CopyElements(doc, ids, translation!);
+                else ElementTransformUtils.RotateElements(doc, ids, Line.CreateUnbound(origin!, direction!.Normalize()), angle);
+                doc.Regenerate();
+                var result = new Dictionary<string, object?> { ["before"] = before, ["after"] = outputIds.Select(doc.GetElement).Where(e => e != null).Select(ModelEditInputs.Snapshot).ToArray(),
+                    ["created_ids"] = action == "copy" ? outputIds.Select(id => id.Value).ToArray() : Array.Empty<long>(),
+                    ["coordinate_system"] = "document_internal", ["snapshot_unit"] = "feet",
+                    ["created_ids_are_temporary"] = action == "copy" && JsonArgs.GetBool(args, "preview", false) };
+                // Copies carry their sources' values and traits (inv:derived-state-reported). CopyElements
+                // returns copies in no guaranteed order, so each copy is reported without pairing it to one source.
+                if (action == "copy")
+                    result["inherited_state"] = outputIds.Take(InheritedState.ListCap).Select(doc.GetElement).Where(e => e != null)
+                        .Select(copy => new { id = copy!.Id.Value, state = InheritedState.OfElement(copy, null) }).Where(row => row.state != null).ToArray();
+                return result;
+            }) });
+        return result.Payload;
+    }
 }

package/workspace/AGENTS.md

@@ -1,15 +1,17 @@
 # pi-revit workspace
 
-This folder tree is the working area for Pi + Revit sessions. The pi-revit tools talk to the
-Revit bridge add-in, targeting Revit 2025, 2026, and 2027. The 0.3.0 changes were
-tested live on Revit 2025. Bridge document tools require a project open; `ping` and
-`search_api_docs` work without a document. `read_revit_result` reads saved local
-results without contacting Revit.
+This folder tree is the working area for Pi + Revit sessions. The pi-revit tools talk to the
+Revit bridge add-in, targeting Revit 2025, 2026, and 2027. This file owns workspace
+and output conventions. The `pi-revit` skill and focused tool manuals own current
+operating guidance. `find_revit_tools` with `scope: "documentation"` returns manual
+paths even while Revit is closed. Most bridge tools require a project open; `ping`
+and `search_api_docs` need the bridge but no document. `read_revit_result` reads
+saved local results without contacting Revit.
 
 ## File rules — where every file goes
 
 Work sorts by model, automatically. The export tool files its output under the model it came
-from — never a decision for you or the user to make:
+from; it is not a decision for you or the user to make:
 
 ```text
 Documents\pi-revit\
@@ -36,23 +38,26 @@ Documents\pi-revit\
    `outputDir`. If no folder has been established, identify it from existing model
    markers or choose an explicit destination for the task; do not trigger an
    unnecessary export or guess a title-only folder. Create subfolders on first use.
-3. **Never create files loose in the workspace root.** The root holds `AGENTS.md`,
+3. **Never create files loose in the workspace root.** <!-- inv:workspace-root-clean --> The root holds `AGENTS.md`,
    `pi-revit.cmd`, `Models\`, and Pi's own session data — nothing else, ever.
 
 ## Tool habits
 
-- Start unfamiliar models with `get_model_overview`; use `get_elements` for any listing or
-  counting; read parameter values with `get_element_details`.
+- Distinguish explanations, inspections, and requested changes. General questions
+  need not connect to a model. An audit alone does not authorize repairs or exports.
+- For model work, use the skill's execution rules, select the intended session,
+  and start unfamiliar models with `get_model_overview`. Discover dedicated tools
+  and read their returned manual paths and current schemas before using custom code.
 - Copy the intended model's `project.documentId` unchanged into `expected_document_id`
-  for `set_parameters`, `execute_csharp`, `export_documents`, `open_view`, and
-  selection/zoom changes. Any `manage_selection` call with `isolate_in_view: true`
-  also requires it, including action `get`. Pure reads may omit it; supplied IDs
-  are checked. Legacy `expected_document` titles alone do not satisfy the guard.
-  After a rejection, verify the intended model before refreshing its ID. Closing
-  and reopening a model or restarting Revit invalidates earlier IDs.
+  whenever required by the schema/runtime, including writes, previews, export,
+  view/selection changes and every `manage_sheet_placements` action. Selection
+  isolation also requires it with action `get`. Supplied IDs on reads are checked.
+  A title alone is insufficient. On rejection verify the intended target before
+  refreshing the ID; reopening a document or restarting Revit invalidates old IDs.
 - Before `execute_csharp`, verify unfamiliar API signatures with `search_api_docs`.
-- Write tools (`set_parameters`, `execute_csharp`) change the real model — state clearly what
-  was changed. `set_parameters` commits partial successes: always check its `failed` list.
+- Report actual retained changes. `set_parameters` defaults to partial success;
+  previews roll back, and atomic failures roll back the batch. Read the manual and
+  distinguish `succeeded`, `proposed`, and `failed`; discard rolled-back IDs.
   Inspect `commitWarnings` and the actual transaction outcome. A failed
   `execute_csharp` attempts rollback; do not assume rollback succeeded. A
   `returnValueError` can follow a committed edit. Earlier UI actions and created
@@ -65,8 +70,9 @@ Documents\pi-revit\
 
 ## Upgrade notes
 
-After installing 0.3.0, deploy the matching add-in with Revit closed, restart Revit,
+After a package/add-in upgrade, deploy the matching add-in with Revit closed, restart Revit,
 and start a fresh Pi session to load the new tool schemas. Obtain a new overview
 before changing a document. Setup preserves existing `AGENTS.md`; older workspaces
-need these exact-ID, saved-result, and identity-derived folder rules merged into
-their existing instructions.
+need updated exact-ID, saved-result, identity-derived folder and guidance-routing
+rules merged into their existing instructions. These are upgrade steps, not
+actions to perform during an ordinary model question or documentation check.