pi-revit 0.3.0 → 0.3.1

package/src/Revit/ToolRegistry.cs

@@ -1,5 +1,5 @@
-using System.Text.Json;
-using System.Text.Json.Nodes;
+using System.Text.Json;
+using System.Text.Json.Nodes;
 using Autodesk.Revit.DB;
 using Autodesk.Revit.UI;
 using RevitBridge.Tools;
@@ -15,9 +15,9 @@ namespace RevitBridge
     internal sealed record ToolContext(Document? Document, UIApplication? UIApplication);
 
     /// <summary>
-    /// 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.
+    /// 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);
 
@@ -100,36 +100,36 @@ namespace RevitBridge
             description = tool.Description,
             category = tool.Write ? "write" : "read",
             tier = tool.Tier,
-            parameters = DescribeParameters(tool),
+            parameters = DescribeParameters(tool),
             executionMode = "sequential",
             write = tool.Write,
             requiresDocument = tool.RequiresDocument,
             promptSnippet = tool.PromptSnippet,
-            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;
-        }
+            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

@@ -1,64 +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.");
-    }
-}
+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

@@ -119,9 +119,9 @@ namespace RevitBridge.Tools
 
             using var dialogGuard = new DialogGuard(uiapp);
             using var transaction = new Transaction(doc, "execute_csharp");
-            if (transaction.Start() != TransactionStatus.Started)
-                throw new InvalidOperationException("Unable to start the execute_csharp transaction.");
-            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,24 +147,24 @@ namespace RevitBridge.Tools
             }
             catch (Exception ex)
             {
-                throw new InvalidOperationException(
-                    FormatRuntimeError(ex, dialogGuard.Suppressed) + " " + FailureGuard.RollBackAndDescribe(transaction), ex);
-            }
-
-            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(
-                    $"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}"
-                    + failureGuard.DescribeErrors()
-                    + DescribeDialogs(dialogGuard.Suppressed), ex);
-            }
+                throw new InvalidOperationException(
+                    FormatRuntimeError(ex, dialogGuard.Suppressed) + " " + FailureGuard.RollBackAndDescribe(transaction), ex);
+            }
+
+            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(
+                    $"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}"
+                    + failureGuard.DescribeErrors()
+                    + DescribeDialogs(dialogGuard.Suppressed), ex);
+            }
 
             stopwatch.Stop();
 
@@ -241,7 +241,7 @@ 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}"
-                + DescribeDialogs(suppressedDialogs);
+                + DescribeDialogs(suppressedDialogs);
         }
 
         private static string DescribeDialogs(IReadOnlyList<string> suppressed)

package/src/Revit/Tools/ExportDocuments.cs

@@ -1,6 +1,6 @@
-using System.IO;
-using System.Security.Cryptography;
-using System.Text;
+using System.IO;
+using System.Security.Cryptography;
+using System.Text;
 using System.Text.Json;
 using Autodesk.Revit.DB;
 
@@ -88,37 +88,37 @@ namespace RevitBridge.Tools
             // recent (a shared output_dir, another tool writing alongside) does not.
             var before = SnapshotWriteTimes(outputDir);
 
-            IReadOnlyList<string> commitWarnings = Array.Empty<string>();
-            try
-            {
-                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 = FindChangedFiles(outputDir, before)
+            IReadOnlyList<string> commitWarnings = Array.Empty<string>();
+            try
+            {
+                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 = FindChangedFiles(outputDir, before)
                 .Select(path => new Dictionary<string, object?>
                 {
                     ["path"] = path,
@@ -129,23 +129,23 @@ namespace RevitBridge.Tools
                 throw new InvalidOperationException($"The {format} export finished but produced no files in {outputDir}.");
 
             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).";
+            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);
+                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
@@ -227,29 +227,29 @@ 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 IReadOnlyList<string> 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)
                 options.FilterViewId = views[0].Id;
 
             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);
+            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.");
-                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 (Exception ex)
-            {
-                throw new InvalidOperationException($"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}", ex);
+                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 (Exception ex)
+            {
+                throw new InvalidOperationException($"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}", ex);
             }
         }
 
@@ -310,72 +310,72 @@ namespace RevitBridge.Tools
         }
 
         /// <summary>Per-model folder under the pi-revit workspace:
-        /// 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)
+        /// 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 identity = GetModelIdentity(doc);
-            string folder = Path.Combine(workspace, "Models", GetModelFolderName(doc.Title, identity));
-            Directory.CreateDirectory(folder);
-            TryRecordModelIdentity(folder, doc, identity);
-            return folder;
-        }
-
-        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)
+            string identity = GetModelIdentity(doc);
+            string folder = Path.Combine(workspace, "Models", GetModelFolderName(doc.Title, identity));
+            Directory.CreateDirectory(folder);
+            TryRecordModelIdentity(folder, doc, identity);
+            return folder;
+        }
+
+        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 line = $"{identity}\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

@@ -16,36 +16,36 @@ namespace RevitBridge.Tools
         public List<string> Warnings { get; } = new();
         public List<string> Errors { get; } = new();
 
-        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();
+        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);
             options.SetClearAfterRollback(true);
             transaction.SetFailureHandlingOptions(options);
-            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.";
-            }
-        }
+            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)
         {