pi-revit 0.2.18 → 0.3.1

package/skills/pi-revit/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: pi-revit
-description: Work with the open Autodesk Revit model through the Revit bridge tools (ping, get_model_overview, get_elements, get_element_details, get_element_types, manage_selection, open_view, set_parameters, search_api_docs, execute_csharp, capture_view, export_documents, get_model_health). Use when the user asks about the Revit project, its elements, parameters, selection, or wants to change, script, capture, or export the model.
+description: Work with the open Autodesk Revit model through the Revit bridge tools (ping, get_model_overview, get_elements, get_element_details, get_element_types, manage_selection, open_view, set_parameters, search_api_docs, execute_csharp, capture_view, export_documents, get_model_health) and retrieve saved results with read_revit_result. Use when the user asks about the Revit project, its elements, parameters, selection, or wants to change, script, capture, or export the model.
 ---
 
 # Revit
 
-Work with the live Revit model. The tools call a headless bridge add-in inside Revit (2025, 2026, or 2027); Revit must be running with a project open (only `ping` and `search_api_docs` work without a document).
+Work with the live Revit model. The bridge targets Revit 2025, 2026, and 2027; the 0.3.0 changes were tested live on Revit 2025. Bridge document tools require Revit running with a project open; `ping` and `search_api_docs` work without a document. `read_revit_result` reads an already saved result locally without contacting Revit.
 
 ## Tool selection
 
@@ -24,30 +24,40 @@ Work with the live Revit model. The tools call a headless bridge add-in inside R
 | PNG snapshot of a view (visual QA) | `capture_view` (advanced) |
 | PDF/DWG/PNG/IFC file export | `export_documents` (advanced) |
 | Warnings / model quality audit | `get_model_health` (advanced) |
+| Continue a saved large tool result | `read_revit_result` (local, no Revit call) |
 
 Workflow guidance:
 
-- Call `get_model_overview` first when starting work on an unfamiliar model — one call returns project metadata, units, levels, grids, and category counts.
+- Call `get_model_overview` for the intended open model before changing it. Copy `project.documentId` unchanged into `expected_document_id` for `set_parameters`, `execute_csharp`, `export_documents`, `open_view`, and selection/zoom changes. `manage_selection` also requires it whenever `isolate_in_view: true`, even with action `get`. Pure reads may omit it; a supplied ID is always checked. A matching legacy `expected_document` title alone is insufficient.
+- The ID belongs to one open document in one bridge session. Refresh it after closing/reopening the model or restarting Revit. If the guard rejects a call, activate the intended model and obtain its overview again; do not blindly substitute the currently active model's ID.
 - `get_elements` is the listing/counting primitive (`count_only: true` for bare counts). It returns identity fields only (id, name, category, typeName, levelId); read parameter values with `get_element_details`. Prefer a `category` or `of_class` scope when filtering by a parameter's display name.
 - The selection pipeline is `get_elements` -> ids -> `manage_selection` (action `set`); there is no inline filter on selection.
-- `set_parameters` is the home for bulk parameter writes AND renames (the `Name` parameter covers levels, views, sheets, types). One transaction per batch; per-element failures are reported. Pass `expected_document` (the model title) when several models are open or the session is long — it makes the write fail cleanly instead of landing in a different active document.
+- `set_parameters` handles bulk parameter writes and renames (the `Name` parameter covers levels, views, sheets, types). It can commit a partially successful batch: inspect every failed update, `commitWarnings`, and the reported transaction outcome before describing what changed.
 - Parameter display names are LOCALIZED: in a non-English Revit UI, `Mark`, `Comments`, and every other display name appear under their translated names. When a display-name lookup or `parameter_names` filter finds nothing, or the document may be non-English, use the language-independent `BuiltInParameter` enum name instead (e.g. `ALL_MODEL_MARK` for Mark, `ALL_MODEL_INSTANCE_COMMENTS` for Comments) — `set_parameters`, `get_element_details.parameter_names`, and `get_elements` filter rules all accept them, and `get_element_details` reports each parameter's `builtInParameter` name for discovery.
 - Before writing `execute_csharp` code, verify unfamiliar classes/members with `search_api_docs` (works with no document open; first query builds the index and takes a few seconds). The top match carries its remarks, parameter docs, and returns inline, and every public API enum value is searchable — trust the result over guessing or web search; narrow the query to promote a different match into the top slot.
-- `export_documents` files its output under `Documents\pi-revit\Models\<model title>\exports` automatically when `output_dir` is omitted — keyed to the exported document, so it lands right even across many models. Pass `output_dir` only when the user names a different target.
+- `export_documents` defaults to `Documents\pi-revit\Models\<model title>--<identity hash>\exports`. Use its returned `outputDir` and file paths as authoritative; do not construct a destination from the title or opaque `project.documentId`. Saved paths and cloud/server identities determine the folder; unsaved/unavailable identities use a session fallback. Save As can select a new folder. Pass `output_dir` when the user requests a different destination. Existing title-only folders remain untouched.
+- Large tool payloads return a `result_id`, `file_path`, and continuation instructions. Call `read_revit_result` with that ID and `offset: 0`, then follow `next_offset` until `has_more` is false. Concatenate `text` fragments in order; each fragment is not a standalone JSON result. Offsets count UTF-16 code units. IDs last for the current extension instance; after reload, use the returned absolute file path with `read` while the file exists. Retrieval does not replace the original query's pagination or remove its limits.
 
 ## execute_csharp playbook
 
 - Globals: `doc` (Document), `uidoc` (UIDocument), `uiapp` (UIApplication), and `Dump(value)` to record intermediates into the result's `dumps[]`.
-- The transaction is automatic: the whole script runs inside ONE backend-owned transaction — committed on success, rolled back on any exception. Do not open your own `Transaction` (sub-transactions are fine).
+- The script runs inside one backend-owned transaction. Do not start another transaction on `doc` (sub-transactions are allowed). The tool checks commit status and attempts rollback on script failure; read its actual outcome instead of assuming rollback succeeded. Result projection can fail after a successful commit and report `returnValueError`. Filesystem and UI effects are separate from model rollback.
 - Scripts must be fully synchronous: `await`/`async` is rejected at compile time; never block on `Task.Result`/`.Wait()`.
 - Return primitives, strings, or anonymous objects/lists; raw Revit API objects are projected to compact shapes (Element -> `{id,name,category,typeName,levelId}`, ElementId -> number, XYZ -> `{x,y,z}`).
 - Lengths are internal units (decimal feet) — convert with `UnitUtils.ConvertToInternalUnits`/`ConvertFromInternalUnits`.
-- Common pitfalls: call `FamilySymbol.Activate()` before `NewFamilyInstance`; use collector-level filtering (`OfCategory`/`OfClass`/`WhereElementIsNotElementType`) and bounded loops — the budget is 120s and Revit cannot be interrupted mid-script; modal dialogs are auto-dismissed and reported in `suppressedDialogs`.
+- Common pitfalls: call `FamilySymbol.Activate()` before `NewFamilyInstance`; use collector-level filtering (`OfCategory`/`OfClass`/`WhereElementIsNotElementType`) and bounded loops. The budget is 120s and Revit cannot be interrupted mid-script. The dialog guard attempts dismissive responses and reports `suppressedDialogs`; it cannot guarantee handling every modal dialog.
 - `capture_view` returns a `filePath` to a temp PNG, never image data — open it with the read tool to actually see it.
 
 ## Failure modes
 
+- **Identity rejected**: no tool action was performed. Verify the intended active model, refresh `project.documentId`, and pass `expected_document_id` unchanged.
+- **Partial UI/export effects**: selection or zoom can already have changed when isolation fails. Export errors can leave incomplete files, and IFC commit warnings are returned. Inspect the reported effects and output paths; model rollback does not remove files or reverse earlier UI actions.
+- **Large-result save failed**: Revit may already have completed the operation. Verify its effects before retrying a write.
 - **Bridge not reachable** ("Revit bridge is not available" / "Could not reach the Revit bridge"): Revit is not running or the add-in did not load. Ask the user to start Revit, then retry `ping`.
 - **HTTP 409 / "No active Revit document is open."** (`hasActiveDocument: false`): Revit is running but no project is open. Ask the user to open a project, then retry. This fails immediately; do not wait or retry blindly.
 - **Timeout** ("Revit did not answer within Ns", 30s default / 120s for execute_csharp, capture_view, export_documents): Revit is busy or showing a modal dialog. An already-started tool still runs to completion in Revit — verify model state (e.g. `get_elements`) before re-issuing a write.
 - **Cancelled**: same caveat — the bridge cannot abort queued or running work, so verify model state before retrying a write tool.
+
+## Upgrading from 0.2.x
+
+Version 0.3.0 requires exact document IDs for the operations above. Update the Pi package and deploy the matching add-in with Revit closed, then restart Revit and start a fresh Pi session so the new schemas and instructions are loaded. Obtain a fresh overview before writes. `ping` reports an installed/loaded version mismatch. Setup preserves existing workspace `AGENTS.md`; merge these targeting, result-reading, and folder rules into an older workspace's instructions when needed.

package/src/Revit/BridgeServer.cs

@@ -407,6 +407,7 @@ namespace RevitBridge
                     ? await _queue.RunAsync(uiApp =>
                     {
                         var document = uiApp.ActiveUIDocument?.Document ?? throw new NoActiveDocumentException();
+                        RevitBridge.Tools.DocumentGuard.CheckForTool(args, document, tool.Name);
                         return tool.Execute(args, new ToolContext(document, uiApp));
                     }, TimeSpan.FromMilliseconds(timeoutMs))
                     // RequiresDocument = false tools never touch the Revit API, so they
@@ -435,9 +436,9 @@ namespace RevitBridge
                 ? Math.Clamp(value, 1_000, 600_000)
                 : 30_000;
 
-        /// <summary>Compact text for model context; full payload in details. Tools may
-        /// return a ToolOutput (CompactText -> content, Payload -> details.payload) or
-        /// any plain object (serialized to both).</summary>
+        /// <summary>Complete bounded JSON for model context; the full payload always
+        /// remains in details for the extension's saved-result retrieval. ToolOutput
+        /// compact text is a display summary, not a substitute for requested data.</summary>
         private static object BuildToolResponse(string toolName, object? output)
         {
             object? payload = output;
@@ -448,12 +449,11 @@ namespace RevitBridge
                 compact = toolOutput.CompactText;
             }
 
-            string text = compact ?? JsonSerializer.Serialize(payload ?? new { });
+            string text = JsonSerializer.Serialize(payload);
             bool truncated = text.Length > MaxContentChars;
             if (truncated)
             {
-                string suffix = $"... [truncated at {MaxContentChars} chars; full payload is in details]";
-                text = text[..Math.Max(0, MaxContentChars - suffix.Length)] + suffix;
+                text = $"Result exceeds the {MaxContentChars}-character inline limit. The complete value is in details.payload; the Pi extension saves it locally and provides read_revit_result for bounded retrieval.";
             }
 
             return new
@@ -461,7 +461,7 @@ namespace RevitBridge
                 success = true,
                 toolName,
                 content = new[] { new { type = "text", text } },
-                details = new { payload, contentTruncated = truncated },
+                details = new { payload, summary = compact, contentTruncated = truncated },
                 isError = false,
             };
         }

package/src/Revit/ToolRegistry.cs

@@ -1,4 +1,5 @@
 using System.Text.Json;
+using System.Text.Json.Nodes;
 using Autodesk.Revit.DB;
 using Autodesk.Revit.UI;
 using RevitBridge.Tools;
@@ -14,9 +15,9 @@ namespace RevitBridge
     internal sealed record ToolContext(Document? Document, UIApplication? UIApplication);
 
     /// <summary>
-    /// Optional tool return shape: compact text for model context plus the full payload for
-    /// details. Tools may instead return any plain JSON-serializable object, which the bridge
-    /// serializes into both channels (capped in content).
+    /// Optional tool return shape: complete structured payload plus a display summary.
+    /// The bridge/extension expose complete bounded data or explicit result retrieval to
+    /// the model; structured details remain available for rendering and diagnostics.
     /// </summary>
     internal sealed record ToolOutput(object? Payload, string? CompactText = null);
 
@@ -99,12 +100,36 @@ namespace RevitBridge
             description = tool.Description,
             category = tool.Write ? "write" : "read",
             tier = tool.Tier,
-            parameters = tool.ParametersSchema,
+            parameters = DescribeParameters(tool),
             executionMode = "sequential",
             write = tool.Write,
             requiresDocument = tool.RequiresDocument,
             promptSnippet = tool.PromptSnippet,
-            promptGuidelines = tool.PromptGuidelines,
+            promptGuidelines = tool.RequiresDocument
+                ? (tool.PromptGuidelines ?? Array.Empty<string>()).Concat(new[]
+                {
+                    $"{tool.Name}: use project.documentId from get_model_overview as expected_document_id to bind the call to that exact open document. It is required for model writes, open_view, and selection changes; legacy expected_document titles alone are insufficient. Refresh after closing/reopening or restarting Revit."
+                }).ToArray()
+                : tool.PromptGuidelines,
         };
+
+        private static object DescribeParameters(ITool tool)
+        {
+            if (!tool.RequiresDocument) return tool.ParametersSchema;
+            var schema = JsonSerializer.SerializeToNode(tool.ParametersSchema)!.AsObject();
+            var properties = schema["properties"]!.AsObject();
+            properties["expected_document_id"] = new JsonObject
+            {
+                ["type"] = "string",
+                ["description"] = "Exact opaque project.documentId from get_model_overview. Required for document writes and UI mutations; optional for reads. Invalid after close/reopen or bridge restart."
+            };
+            if (DocumentGuard.AlwaysRequiresIdentity(tool.Name))
+            {
+                var required = schema["required"] as JsonArray ?? new JsonArray();
+                if (!required.Any(x => x?.GetValue<string>() == "expected_document_id")) required.Add("expected_document_id");
+                schema["required"] = required;
+            }
+            return schema;
+        }
     }
 }

package/src/Revit/Tools/DocumentGuard.cs

@@ -0,0 +1,64 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+/// <summary>Opaque identity of one open native document in this loaded bridge session.</summary>
+internal static class DocumentGuard
+{
+    private sealed record Identity(Document Document, string Value);
+    private static readonly string Generation = Guid.NewGuid().ToString("N");
+    private static readonly List<Identity> Identities = new();
+
+    public static string GetIdentity(Document document)
+    {
+        if (!document.IsValidObject)
+            throw new ArgumentException("The target document is closed or invalid. Read get_model_overview again.");
+        // Revit can supply multiple managed wrappers for the same native document.
+        // Its documented Equals semantics identify that native document; reference identity cannot.
+        // All accesses happen on the Revit API thread. Pruning avoids retaining closed documents.
+        Identities.RemoveAll(entry => !entry.Document.IsValidObject);
+        var existing = Identities.FirstOrDefault(entry => entry.Document.Equals(document));
+        if (existing != null) return existing.Value;
+        var created = new Identity(document, Generation + ":" + Guid.NewGuid().ToString("N"));
+        Identities.Add(created);
+        return created.Value;
+    }
+
+    public static bool AlwaysRequiresIdentity(string toolName)
+        => toolName is "set_parameters" or "execute_csharp" or "export_documents" or "open_view";
+
+    /// <summary>Must run on the Revit API thread immediately before the tool action.</summary>
+    public static void CheckForTool(JsonElement args, Document document, string toolName)
+    {
+        bool required = AlwaysRequiresIdentity(toolName)
+            || (toolName == "manage_selection"
+                && (!string.Equals((JsonArgs.GetString(args, "action") ?? "get").Trim(), "get", StringComparison.OrdinalIgnoreCase)
+                    || JsonArgs.GetBool(args, "isolate_in_view", false)));
+        if (required && !args.TryGetProperty("expected_document_id", out _))
+            throw new ArgumentException("expected_document_id is required for this operation. Read project.documentId from get_model_overview for the intended open document and pass it unchanged. A title alone cannot identify a document. No action was performed.");
+        CheckExpectedDocument(args, document);
+    }
+
+    public static void CheckExpectedDocument(JsonElement args, Document document)
+    {
+        if (args.TryGetProperty("expected_document_id", out var id))
+        {
+            if (id.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(id.GetString()))
+                throw new ArgumentException("expected_document_id must be a non-empty identity from get_model_overview. No action was performed.");
+            if (!string.Equals(id.GetString(), GetIdentity(document), StringComparison.Ordinal))
+                throw new ArgumentException($"The active document '{document.Title}' is not the exact open document this call expected, or that identity is stale after reopening/restarting. No action was performed. Activate the intended document and read get_model_overview again.");
+        }
+
+        // Retained as an additional human-readable check, never as a substitute for identity.
+        string? expected = JsonArgs.GetString(args, "expected_document");
+        if (string.IsNullOrWhiteSpace(expected)) return;
+        static string Normalize(string title)
+        {
+            string value = title.Trim();
+            return value.EndsWith(".rvt", StringComparison.OrdinalIgnoreCase) ? value[..^4] : value;
+        }
+        if (!string.Equals(Normalize(expected), Normalize(document.Title), StringComparison.OrdinalIgnoreCase))
+            throw new ArgumentException($"Active document is '{document.Title}' but this call expected title '{expected}'. No action was performed. Read get_model_overview for the intended document.");
+    }
+}

package/src/Revit/Tools/ExecuteCsharp.cs

@@ -59,7 +59,7 @@ namespace RevitBridge.Tools
 
         public string Name => "execute_csharp";
         public string Label => "Execute C#";
-        public string Description => "Compile and run a C# script on the Revit API thread against the open model — the escape hatch for anything without a dedicated tool: element creation, deletion, geometry edits (move/copy/rotate), views, sheets, schedules, tagging, families, links, worksets. Globals: doc (Document), uidoc (UIDocument), uiapp (UIApplication), and Dump(value) to record intermediate values into the result's dumps[]. Default imports: System, System.Linq, System.Collections.Generic, Autodesk.Revit.DB, Autodesk.Revit.UI — add using directives at the top for sub-namespaces (e.g. using Autodesk.Revit.DB.Architecture;). The entire run is wrapped in ONE transaction named 'execute_csharp': committed on success, rolled back on any exception, so a failed script never changes the model (do not open your own Transaction; sub-transactions are fine). The script's final expression or return statement becomes returnValue; return primitives, strings, or anonymous objects/lists — Revit API values are projected to safe shapes (Element -> {id,name,category,typeName,levelId}, ElementId -> number, XYZ -> {x,y,z}, Parameter -> {name,value,displayValue}; other API objects become strings) with depth and item caps, so never rely on raw API objects round-tripping. Lengths are in internal units (decimal feet) — convert with UnitUtils. Prefer collector-level filtering (FilteredElementCollector .OfCategory/.OfClass/.WhereElementIsNotElementType) and bounded loops: the call budget is 120s and Revit cannot be interrupted mid-script. Scripts must be fully synchronous — await/async is rejected at compile time, and blocking on tasks (Task.Result/.Wait()) can freeze Revit. Modal dialogs raised while running are auto-dismissed and reported in suppressedDialogs — unrecognized dialogs are answered dismissively (Cancel/Close/No) rather than confirmed, so an operation that raises a confirmation prompt may be cancelled; check suppressedDialogs when a result looks incomplete. Verify unfamiliar signatures with search_api_docs first.";
+        public string Description => "Compile and run a C# script on the Revit API thread against the open model — the escape hatch for anything without a dedicated tool: element creation, deletion, geometry edits (move/copy/rotate), views, sheets, schedules, tagging, families, links, worksets. Globals: doc (Document), uidoc (UIDocument), uiapp (UIApplication), and Dump(value) to record intermediate values into the result's dumps[]. Default imports: System, System.Linq, System.Collections.Generic, Autodesk.Revit.DB, Autodesk.Revit.UI — add using directives at the top for sub-namespaces (e.g. using Autodesk.Revit.DB.Architecture;). The entire run is wrapped in ONE transaction named 'execute_csharp': committed on success; on failure rollback is attempted and its confirmed status is reported (do not open your own Transaction; sub-transactions are fine). The script's final expression or return statement becomes returnValue; return primitives, strings, or anonymous objects/lists — Revit API values are projected to safe shapes (Element -> {id,name,category,typeName,levelId}, ElementId -> number, XYZ -> {x,y,z}, Parameter -> {name,value,displayValue}; other API objects become strings) with depth and item caps, so never rely on raw API objects round-tripping. Lengths are in internal units (decimal feet) — convert with UnitUtils. Prefer collector-level filtering (FilteredElementCollector .OfCategory/.OfClass/.WhereElementIsNotElementType) and bounded loops: the call budget is 120s and Revit cannot be interrupted mid-script. Scripts must be fully synchronous — await/async is rejected at compile time, and blocking on tasks (Task.Result/.Wait()) can freeze Revit. Modal dialogs raised while running are auto-dismissed and reported in suppressedDialogs — unrecognized dialogs are answered dismissively (Cancel/Close/No) rather than confirmed, so an operation that raises a confirmation prompt may be cancelled; check suppressedDialogs when a result looks incomplete. Verify unfamiliar signatures with search_api_docs first.";
         public bool Write => true;
 
         public object ParametersSchema => new
@@ -119,9 +119,9 @@ namespace RevitBridge.Tools
 
             using var dialogGuard = new DialogGuard(uiapp);
             using var transaction = new Transaction(doc, "execute_csharp");
-            var failureGuard = FailureGuard.Attach(transaction);
             if (transaction.Start() != TransactionStatus.Started)
                 throw new InvalidOperationException("Unable to start the execute_csharp transaction.");
+            var failureGuard = FailureGuard.Attach(transaction);
 
             object? returnValue;
             string? projectionError = null;
@@ -147,23 +147,24 @@ namespace RevitBridge.Tools
             }
             catch (Exception ex)
             {
-                try
-                {
-                    if (transaction.GetStatus() == TransactionStatus.Started)
-                        transaction.RollBack();
-                }
-                catch
-                {
-                    // Reporting the script failure outranks a rollback hiccup.
-                }
-                throw new InvalidOperationException(FormatRuntimeError(ex, dialogGuard.Suppressed));
+                throw new InvalidOperationException(
+                    FormatRuntimeError(ex, dialogGuard.Suppressed) + " " + FailureGuard.RollBackAndDescribe(transaction), ex);
             }
 
-            if (transaction.Commit() != TransactionStatus.Committed)
+            try
+            {
+                var status = transaction.Commit();
+                var finalStatus = transaction.GetStatus();
+                if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
+                    throw new InvalidOperationException($"The execute_csharp commit returned {status}; current transaction status is {finalStatus}.");
+            }
+            catch (Exception ex)
+            {
                 throw new InvalidOperationException(
-                    "Revit rolled back the execute_csharp transaction during commit (failure processing rejected the changes); no model changes were saved."
+                    $"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}"
                     + failureGuard.DescribeErrors()
-                    + DescribeDialogs(dialogGuard.Suppressed));
+                    + DescribeDialogs(dialogGuard.Suppressed), ex);
+            }
 
             stopwatch.Stop();
 
@@ -240,7 +241,6 @@ namespace RevitBridge.Tools
             string line = TryGetScriptLine(ex) is { } scriptLine ? $" at script line {scriptLine}" : string.Empty;
             string inner = ex.InnerException is { } innerEx ? $" Inner: {innerEx.GetType().Name}: {innerEx.Message}" : string.Empty;
             return $"C# script threw {ex.GetType().Name}{line}: {ex.Message}.{inner}"
-                + " The execute_csharp transaction was rolled back; no model changes were saved."
                 + DescribeDialogs(suppressedDialogs);
         }
 

package/src/Revit/Tools/ExportDocuments.cs

@@ -1,4 +1,6 @@
 using System.IO;
+using System.Security.Cryptography;
+using System.Text;
 using System.Text.Json;
 using Autodesk.Revit.DB;
 
@@ -19,7 +21,7 @@ namespace RevitBridge.Tools
 
         public string Name => "export_documents";
         public string Label => "Export Documents";
-        public string Description => "Export documents from the open Revit model. format 'pdf'/'dwg'/'png' export the given sheet/view ids to files: pdf combines everything into one file by default (combine=false writes one PDF per sheet/view, named by Revit's naming rule); png renders 2048 px wide; ifc exports the whole model, or just what one given view shows. Files sort themselves per model: with output_dir omitted they land in Documents\\pi-revit\\Models\\<model title>\\exports, derived from the document being exported (pass output_dir only for a different explicit target); file_name_prefix sets the base file name (default: the document title; Revit appends view/sheet suffixes for multi-file exports). Returns the produced file paths with sizes. Find sheet/view ids with get_elements (category 'Sheets' or 'Views') first.";
+        public string Description => "Export documents from the open Revit model. format 'pdf'/'dwg'/'png' export the given sheet/view ids to files: pdf combines everything into one file by default (combine=false writes one PDF per sheet/view, named by Revit's naming rule); png renders 2048 px wide; ifc exports the whole model, or just what one given view shows. Files sort themselves per model: with output_dir omitted they land in Documents\\pi-revit\\Models\\<model title>--<identity hash>\\exports, derived from the document being exported (pass output_dir only for a different explicit target); file_name_prefix sets the base file name (default: the document title; Revit appends view/sheet suffixes for multi-file exports). Returns the produced file paths with sizes. Find sheet/view ids with get_elements (category 'Sheets' or 'Views') first.";
         public bool Write => true;
         public string Tier => "advanced";
 
@@ -43,7 +45,7 @@ namespace RevitBridge.Tools
                 output_dir = new
                 {
                     type = "string",
-                    description = "Output directory, created if missing. Default: Documents\\pi-revit\\Models\\<model title>\\exports — files sort under the exported model automatically; omit unless the user names a different target.",
+                    description = "Output directory, created if missing. Default: Documents\\pi-revit\\Models\\<model title>--<identity hash>\\exports — files sort under the exported model automatically; omit unless the user names a different target.",
                 },
                 file_name_prefix = new
                 {
@@ -86,17 +88,37 @@ namespace RevitBridge.Tools
             // recent (a shared output_dir, another tool writing alongside) does not.
             var before = SnapshotWriteTimes(outputDir);
 
-            switch (format)
+            IReadOnlyList<string> commitWarnings = Array.Empty<string>();
+            try
             {
-                case "pdf": ExportPdf(doc, views, outputDir, baseName, combine); break;
-                case "dwg": ExportDwg(doc, views, outputDir, baseName); break;
-                case "png": ExportPng(doc, views, outputDir, baseName); break;
-                default: ExportIfc(doc, views, outputDir, baseName); break;
+                switch (format)
+                {
+                    case "pdf": ExportPdf(doc, views, outputDir, baseName, combine); break;
+                    case "dwg": ExportDwg(doc, views, outputDir, baseName); break;
+                    case "png": ExportPng(doc, views, outputDir, baseName); break;
+                    default: commitWarnings = ExportIfc(doc, views, outputDir, baseName); break;
+                }
+            }
+            catch (Exception ex)
+            {
+                // A failed export may already have written some files. A Revit
+                // transaction rollback cannot undo those filesystem changes.
+                string observed;
+                try
+                {
+                    var changed = FindChangedFiles(outputDir, before).ToList();
+                    observed = changed.Count == 0
+                        ? "No changed files were observed."
+                        : $"Observed {changed.Count} new or changed file(s): {string.Join(", ", changed.Take(20))}{(changed.Count > 20 ? " (additional files omitted)" : string.Empty)}.";
+                }
+                catch (Exception scanError)
+                {
+                    observed = $"Could not inspect remaining files: {scanError.Message}.";
+                }
+                throw new InvalidOperationException($"{ex.Message} The export failed; files in '{outputDir}' may be incomplete and were not removed. {observed}", ex);
             }
 
-            var files = Directory.GetFiles(outputDir)
-                .Where(path => !before.TryGetValue(path, out DateTime writtenBefore) || SafeWriteTime(path) != writtenBefore)
-                .OrderBy(path => path, StringComparer.OrdinalIgnoreCase)
+            var files = FindChangedFiles(outputDir, before)
                 .Select(path => new Dictionary<string, object?>
                 {
                     ["path"] = path,
@@ -108,15 +130,23 @@ namespace RevitBridge.Tools
 
             string sample = string.Join(", ", files.Take(3).Select(file => Path.GetFileName((string)file["path"]!)));
             string compact = $"Exported {files.Count} {format.ToUpperInvariant()} file(s) to {outputDir}: {sample}{(files.Count > 3 ? $" (+{files.Count - 3} more)" : string.Empty)}.";
+            if (commitWarnings.Count > 0)
+                compact += $" {commitWarnings.Count} Revit warning(s) auto-dismissed (see commitWarnings).";
             return new ToolOutput(new
             {
                 format,
                 outputDir,
                 fileCount = files.Count,
                 files,
+                commitWarnings,
             }, compact);
         }
 
+        private static IEnumerable<string> FindChangedFiles(string directory, IReadOnlyDictionary<string, DateTime> before)
+            => Directory.GetFiles(directory)
+                .Where(path => !before.TryGetValue(path, out DateTime writtenBefore) || SafeWriteTime(path) != writtenBefore)
+                .OrderBy(path => path, StringComparer.OrdinalIgnoreCase);
+
         /// <summary>path -> last write time for the files already in the output directory.
         /// A file whose time cannot be read is left out, so the export reports it if it
         /// shows up afterwards rather than silently swallowing a produced file.</summary>
@@ -197,7 +227,7 @@ namespace RevitBridge.Tools
         /// <summary>The IFC exporter writes IFC GUID parameters onto exported elements,
         /// so the Revit API requires a transaction around it — owned here, matching
         /// Revit's own behavior of committing those GUIDs on export.</summary>
-        private static void ExportIfc(Document doc, List<View> views, string outputDir, string baseName)
+        private static IReadOnlyList<string> ExportIfc(Document doc, List<View> views, string outputDir, string baseName)
         {
             var options = new IFCExportOptions();
             if (views.Count == 1)
@@ -206,18 +236,20 @@ namespace RevitBridge.Tools
             using var transaction = new Transaction(doc, "export_documents: ifc");
             if (transaction.Start() != TransactionStatus.Started)
                 throw new InvalidOperationException("Unable to start the IFC export transaction.");
+            var failureGuard = FailureGuard.Attach(transaction);
             try
             {
                 if (!Run(() => doc.Export(outputDir, baseName, options), "IFC"))
                     throw new InvalidOperationException("Revit reported a failed IFC export.");
-                if (transaction.Commit() != TransactionStatus.Committed)
-                    throw new InvalidOperationException("The IFC export transaction failed to commit.");
+                var status = transaction.Commit();
+                var finalStatus = transaction.GetStatus();
+                if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
+                    throw new InvalidOperationException($"The IFC export commit returned {status}; current transaction status is {finalStatus}." + failureGuard.DescribeErrors());
+                return failureGuard.Warnings;
             }
-            catch
+            catch (Exception ex)
             {
-                if (transaction.GetStatus() == TransactionStatus.Started)
-                    transaction.RollBack();
-                throw;
+                throw new InvalidOperationException($"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}", ex);
             }
         }
 
@@ -278,27 +310,72 @@ namespace RevitBridge.Tools
         }
 
         /// <summary>Per-model folder under the pi-revit workspace:
-        /// Documents\pi-revit\Models\&lt;model title&gt;. The exporting tool is the one
-        /// component that knows with certainty which model a file belongs to, so the
-        /// sorting is automatic — never an agent or user decision. model.txt records
-        /// the model's identity so same-titled models stay distinguishable.</summary>
+        /// Documents\pi-revit\Models\&lt;model title&gt;--&lt;identity hash&gt;.
+        /// Existing title-only folders are left untouched; identity markers are
+        /// diagnostic records, not the mechanism that separates exports.</summary>
         private static string ModelFolder(Document doc)
         {
             string workspace = Path.Combine(
                 Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments), "pi-revit");
-            string title = SanitizeFileName(string.IsNullOrWhiteSpace(doc.Title) ? "untitled" : doc.Title);
-            string folder = Path.Combine(workspace, "Models", title);
+            string identity = GetModelIdentity(doc);
+            string folder = Path.Combine(workspace, "Models", GetModelFolderName(doc.Title, identity));
             Directory.CreateDirectory(folder);
-            TryRecordModelIdentity(folder, doc);
+            TryRecordModelIdentity(folder, doc, identity);
             return folder;
         }
 
-        private static void TryRecordModelIdentity(string folder, Document doc)
+        internal static string GetModelFolderName(string title, string identity)
+        {
+            string cleanTitle = SanitizeFileName(string.IsNullOrWhiteSpace(title) ? "untitled" : title);
+            // Bound the default path component, leaving room for the identity and exports.
+            if (cleanTitle.Length > 80)
+                cleanTitle = cleanTitle[..80];
+            string hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(identity))).ToLowerInvariant()[..24];
+            return $"{cleanTitle}--{hash}";
+        }
+
+        // Revit can return different managed wrappers for one open native document.
+        // Document.Equals/GetHashCode identify that open document, unlike reference
+        // equality in ConditionalWeakTable. Closed document entries are pruned below.
+        // Tool execution and this dictionary are confined to the Revit API thread.
+        private static readonly Dictionary<Document, string> OpenDocumentIdentities = new();
+
+        internal static string GetModelIdentity(Document doc)
+        {
+            try
+            {
+                if (doc.IsModelInCloud)
+                {
+                    var path = doc.GetCloudModelPath();
+                    return $"cloud:{path.Region.ToUpperInvariant()}:{path.GetProjectGUID():D}:{path.GetModelGUID():D}";
+                }
+                string pathName = doc.PathName;
+                if (!string.IsNullOrWhiteSpace(pathName))
+                {
+                    // Revit file paths are Windows paths; canonicalize separators,
+                    // relative segments and case. Revit Server identities use RSN URLs.
+                    if (pathName.StartsWith("RSN://", StringComparison.OrdinalIgnoreCase))
+                        return "server:" + pathName.Replace('\\', '/').TrimEnd('/').ToUpperInvariant();
+                    return "file:" + Path.GetFullPath(pathName).Replace('/', '\\').ToUpperInvariant();
+                }
+            }
+            catch
+            {
+                // An unavailable identity must not collapse unrelated documents into
+                // a shared title-only directory. Use the same safe fallback as unsaved docs.
+            }
+            foreach (var closed in OpenDocumentIdentities.Keys.Where(key => !key.IsValidObject).ToList())
+                OpenDocumentIdentities.Remove(closed);
+            if (!OpenDocumentIdentities.TryGetValue(doc, out string? identity))
+                OpenDocumentIdentities[doc] = identity = $"session:{Guid.NewGuid():N}";
+            return identity;
+        }
+
+        private static void TryRecordModelIdentity(string folder, Document doc, string identity)
         {
             try
             {
-                string guid = doc.ProjectInformation?.UniqueId ?? string.Empty;
-                string line = $"{guid}\t{doc.PathName}";
+                string line = $"{identity}\t{doc.PathName}";
                 string marker = Path.Combine(folder, "model.txt");
                 if (!File.Exists(marker) || !File.ReadAllLines(marker).Contains(line))
                     File.AppendAllLines(marker, new[] { line });

package/src/Revit/Tools/FailureGuard.cs

@@ -18,6 +18,8 @@ namespace RevitBridge.Tools
 
         public static FailureGuard Attach(Transaction transaction)
         {
+            if (transaction.GetStatus() != TransactionStatus.Started)
+                throw new InvalidOperationException("FailureGuard must be attached after the transaction starts; Start resets failure handling options.");
             var guard = new FailureGuard();
             var options = transaction.GetFailureHandlingOptions();
             options.SetFailuresPreprocessor(guard);
@@ -26,6 +28,25 @@ namespace RevitBridge.Tools
             return guard;
         }
 
+        /// <summary>Best-effort cleanup that preserves the original failure and never
+        /// claims a rollback unless Revit confirms its final transaction status.</summary>
+        public static string RollBackAndDescribe(Transaction transaction)
+        {
+            try
+            {
+                if (transaction.GetStatus() == TransactionStatus.Started)
+                    transaction.RollBack();
+                var status = transaction.GetStatus();
+                return status == TransactionStatus.RolledBack
+                    ? "The transaction was rolled back; no changes from this transaction were saved."
+                    : $"Transaction status is {status}; rollback is not confirmed. Inspect Revit before retrying.";
+            }
+            catch (Exception ex)
+            {
+                return $"Rollback could not be confirmed ({ex.GetType().Name}: {ex.Message}). Inspect Revit before retrying.";
+            }
+        }
+
         public FailureProcessingResult PreprocessFailures(FailuresAccessor accessor)
         {
             bool hasError = false;

package/src/Revit/Tools/GetElementDetails.cs

@@ -36,7 +36,7 @@ namespace RevitBridge.Tools
                     properties = new
                     {
                         parameters = new { type = "boolean", description = "Instance parameter values. Default true." },
-                        type_parameters = new { type = "boolean", description = "Also include the element type's parameters, marked isType=true. Default false." },
+                        type_parameters = new { type = "boolean", description = "Include the element type's parameters, marked isType=true, independently of the instance parameters flag. Default false." },
                         location = new { type = "boolean", description = "Location point or curve (coordinates in internal feet). Default false." },
                         bounding_box = new { type = "boolean", description = "Model bounding box min/max (internal feet). Default false." },
                         materials = new { type = "boolean", description = "Material ids/names with area/volume (internal units). Default false." },
@@ -72,6 +72,7 @@ namespace RevitBridge.Tools
                 : default;
             bool withParameters = JsonArgs.GetBool(include, "parameters", true);
             bool withTypeParameters = JsonArgs.GetBool(include, "type_parameters", false);
+            bool withAnyParameters = withParameters || withTypeParameters;
             bool withLocation = JsonArgs.GetBool(include, "location", false);
             bool withBoundingBox = JsonArgs.GetBool(include, "bounding_box", false);
             bool withMaterials = JsonArgs.GetBool(include, "materials", false);
@@ -102,10 +103,11 @@ namespace RevitBridge.Tools
 
                 int parameterCount = 0;
                 int parameterTotal = 0;
-                if (withParameters)
+                if (withAnyParameters)
                 {
                     var parameters = new List<Dictionary<string, object?>>();
-                    parameterTotal += AppendParameters(doc, element, nameFilter, isType: false, parameters);
+                    if (withParameters)
+                        parameterTotal += AppendParameters(doc, element, nameFilter, isType: false, parameters);
                     if (withTypeParameters && elementType != null)
                         parameterTotal += AppendParameters(doc, elementType, nameFilter, isType: true, parameters);
                     dto["parameters"] = parameters;
@@ -122,7 +124,7 @@ namespace RevitBridge.Tools
                 elements.Add(dto);
                 // With a name filter active, "0 params" is ambiguous (none matched vs none
                 // exist): report matched-of-total so a localization miss is visible.
-                string paramSummary = !withParameters ? string.Empty
+                string paramSummary = !withAnyParameters ? string.Empty
                     : nameFilter != null ? $", {parameterCount} of {parameterTotal} params matched parameter_names"
                     : $", {parameterCount} params";
                 compactParts.Add($"'{element.Name}' (id {id}, {element.Category?.Name ?? "no category"}{paramSummary})");