pi-revit 0.2.8 → 0.2.9

package/CHANGELOG.md

@@ -7,6 +7,39 @@ Format follows [Keep a Changelog](https://keepachangelog.com/); version headers
 Every published version gets an entry with **Added** / **Changed** / **Fixed** sections
 describing what the user will notice — not internal refactors.
 
+## [0.2.9] - 2026-07-21
+
+### Added
+- Self-healing tool discovery: when pi starts before Revit, the extension now keeps
+  retrying tool discovery in the background (every 15s) and also re-discovers on a
+  successful `ping` — no more sessions stuck with only `ping` registered until a fresh
+  pi start. When tools arrive mid-session, `ping`'s result says so.
+- `set_parameters` and `execute_csharp` accept an optional `expected_document` (the model
+  title): if the active document differs — e.g. the user switched models mid-session —
+  the write fails cleanly instead of landing in the wrong model.
+- `get_element_details.parameter_names` now also matches language-independent
+  BuiltInParameter enum names (e.g. `ALL_MODEL_MARK`), so filtering works in non-English
+  Revit UIs where display names are localized.
+
+### Fixed
+- `get_element_details` no longer reports a misleading "0 params" when a
+  `parameter_names` filter simply matched nothing — it now reports "N of M params
+  matched parameter_names" so localization misses are visible. (This explains the
+  earlier "0 params vs 38 params" reports: different filter arguments, not flaky reads.)
+- `get_elements`: a display-name filter rule in an **unscoped** query (no category /
+  of_class) is no longer promoted to a pinned collector filter based on a 50-element
+  probe — it stays on the per-element post-scan path, so categories beyond the probe
+  window can't be silently dropped when the same parameter name maps to different ids.
+
+### Changed
+- SKILL.md: guidance on localized parameter names (prefer BuiltInParameter enum names)
+  and on using `expected_document` for long sessions / multiple open models.
+- README: new "Safety model" section stating explicitly what the add-in enforces and
+  that write-confirmation UX is a client-side decision.
+
+Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
+restart Revit).
+
 ## [0.2.8] - 2026-07-21
 
 ### Fixed

package/README.md

@@ -29,10 +29,32 @@ headless Revit add-in          ← no ribbon, no panels; just a bridge
 Revit API                      ← reads run directly; writes run in one named transaction
 ```
 
-The extension discovers its tools from the bridge at startup (`/reload` re-discovers), so the
-tool list always matches what the add-in serves. Everything between Pi and Revit is
-local-machine only; note that Pi sends conversation context and tool results to your selected
-LLM provider, like any Pi session.
+The extension discovers its tools from the bridge at startup (retrying in the background until
+Revit is up), so the tool list always matches what the add-in serves. Everything between Pi and
+Revit is local-machine only; note that Pi sends conversation context and tool results to your
+selected LLM provider, like any Pi session.
+
+## Safety model
+
+Be deliberate about pointing an LLM at a real project model. The add-in enforces what it can
+enforce mechanically, and is honest about what it cannot:
+
+- Every write tool is flagged `write: true` — that flag is the machine-readable signal a client
+  can gate on. Whether a write needs human confirmation is a **client-side decision**: the
+  add-in cannot know your policy, so confirmation UX belongs in the Pi client/agent layer, not
+  here.
+- All writes run in one named transaction: committed on success, rolled back on failure, always
+  visible in Revit's undo history. Commit-time warnings are reported back (`commitWarnings`);
+  error-severity failures roll back with Revit's failure text.
+- `execute_csharp` is an unrestricted escape hatch by design — scripts have full CLR access.
+  Treat it like giving the agent a macro editor, on a model you have saved or can restore.
+- Blocking popups are auto-answered so Revit can never hang behind a dialog; unrecognized
+  dialogs get the dismissive answer (Cancel/Close/No), never a blind OK.
+- Writes accept an optional `expected_document` check so a queued write cannot silently land in
+  a different model than intended.
+
+Practical advice: work on saved models, keep worksharing backups/central protection as usual,
+and review the agent's summary of what changed after any write session.
 
 ## Requirements
 

package/extensions/pi-revit/index.ts

@@ -275,7 +275,7 @@ async function announceUpdateOnce(notify: (message: string, level: "info") => vo
 	}
 }
 
-function registerPing(pi: ExtensionAPI) {
+function registerPing(pi: ExtensionAPI, onBridgeAlive?: () => Promise<"ready" | "registered" | "failed">) {
 	pi.registerTool({
 		name: "ping",
 		label: "Ping Revit Bridge",
@@ -287,18 +287,71 @@ function registerPing(pi: ExtensionAPI) {
 		async execute(_toolCallId, _params, signal) {
 			const payload = await bridgeRequest("/ping", { method: "GET" }, signal, 10_000);
 			const warning = versionMismatch((payload as { addinVersion?: string }).addinVersion);
+			// The bridge is alive: if this session started before Revit and only has
+			// ping, register the bridge tools now and tell the model they arrived.
+			let registrationNote = "";
+			if (onBridgeAlive) {
+				const state = await onBridgeAlive();
+				if (state === "registered")
+					registrationNote = "\nNOTE: The Revit bridge tools (get_elements, set_parameters, execute_csharp, ...) were just registered in this session and are available from now on.";
+				else if (state === "failed")
+					registrationNote = "\nNOTE: Bridge tool discovery failed even though ping succeeded; retry ping or restart pi.";
+			}
 			return {
-				content: [{ type: "text", text: JSON.stringify(payload) + (warning ? `\nWARNING: ${warning}` : "") }],
+				content: [{ type: "text", text: JSON.stringify(payload) + (warning ? `\nWARNING: ${warning}` : "") + registrationNote }],
 				details: payload,
 			};
 		},
 	});
 }
 
+const REDISCOVERY_INTERVAL_MS = 15_000;
+
 export default async function revitConnector(pi: ExtensionAPI) {
+	// Self-healing discovery: when pi starts before Revit is ready, the initial
+	// GET /tools fails and only ping is registered. Rather than requiring a
+	// fresh pi start (/reload does not reliably re-run async registration), a
+	// background retry keeps probing until the bridge appears, and a successful
+	// ping also triggers an immediate attempt.
+	let bridgeToolsRegistered = false;
+	let discoveryInFlight: Promise<boolean> | null = null;
+
+	async function discoverAndRegister(): Promise<boolean> {
+		if (bridgeToolsRegistered) return true;
+		if (discoveryInFlight) return discoveryInFlight;
+		discoveryInFlight = (async () => {
+			try {
+				const payload = (await bridgeRequest("/tools", { method: "GET" }, undefined, DISCOVERY_TIMEOUT_MS)) as {
+					tools?: BridgeToolDescriptor[];
+				};
+				const descriptors = Array.isArray(payload?.tools) ? payload.tools : [];
+				if (descriptors.length === 0) return false;
+				for (const descriptor of descriptors) {
+					if (!descriptor || typeof descriptor.name !== "string" || !descriptor.name) continue;
+					if (descriptor.name === "ping") continue;
+					registerBridgeTool(pi, descriptor);
+				}
+				bridgeToolsRegistered = true;
+				return true;
+			} catch {
+				// Bridge down (Revit closed, still starting, stale bridge.json):
+				// stay on ping only and try again later.
+				return false;
+			} finally {
+				discoveryInFlight = null;
+			}
+		})();
+		return discoveryInFlight;
+	}
+
 	// ping is hard-coded: it must work (and report clearly) even when the
-	// bridge is down, so it is never part of /tools discovery.
-	registerPing(pi);
+	// bridge is down, so it is never part of /tools discovery. A successful
+	// ping doubles as a re-discovery trigger — the natural first call in a
+	// session that finds itself without bridge tools.
+	registerPing(pi, async () => {
+		if (bridgeToolsRegistered) return "ready";
+		return (await discoverAndRegister()) ? "registered" : "failed";
+	});
 
 	// Surface an incomplete update (see versionMismatch) once per session, right
 	// where the user lands after running `pi update --extensions`. Bridge down at
@@ -314,21 +367,12 @@ export default async function revitConnector(pi: ExtensionAPI) {
 		}
 	});
 
-	let descriptors: BridgeToolDescriptor[];
-	try {
-		const payload = (await bridgeRequest("/tools", { method: "GET" }, undefined, DISCOVERY_TIMEOUT_MS)) as {
-			tools?: BridgeToolDescriptor[];
-		};
-		descriptors = Array.isArray(payload?.tools) ? payload.tools : [];
-	} catch {
-		// Bridge down at startup (Revit closed, stale bridge.json, ...): keep
-		// only ping registered and never block pi startup. /reload re-discovers.
-		return;
-	}
+	if (await discoverAndRegister()) return;
 
-	for (const descriptor of descriptors) {
-		if (!descriptor || typeof descriptor.name !== "string" || !descriptor.name) continue;
-		if (descriptor.name === "ping") continue;
-		registerBridgeTool(pi, descriptor);
-	}
+	// Never block pi startup on Revit: keep retrying quietly in the background
+	// and stop the moment discovery succeeds.
+	const timer = setInterval(async () => {
+		if (await discoverAndRegister()) clearInterval(timer);
+	}, REDISCOVERY_INTERVAL_MS);
+	timer.unref?.();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-revit",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "Native Pi connector for Autodesk Revit. Run npx.cmd -y pi-revit for the full Windows install.",
   "author": "Ahmad Altahlawi",
   "license": "MIT",

package/skills/pi-revit/SKILL.md

@@ -29,7 +29,8 @@ 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.
 - `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.
+- `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.
+- Parameter display names are LOCALIZED: in a non-English Revit UI, `Mark` is `Kennzeichen` (German), `マーク` (Japanese), etc. 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.
 

package/src/Revit/Tools/ExecuteCsharp.cs

@@ -72,6 +72,11 @@ namespace RevitBridge.Tools
                     type = "string",
                     description = "C# script body (top-level statements; using directives allowed at the top). Globals doc/uidoc/uiapp and Dump(value) are in scope. The final expression or a return statement is the result.",
                 },
+                expected_document = new
+                {
+                    type = "string",
+                    description = "Optional safety check: title of the document this script is meant for (as reported by get_model_overview). If the active document differs (user switched models), the call fails before running anything.",
+                },
             },
             required = new[] { "code" },
         };
@@ -88,6 +93,7 @@ namespace RevitBridge.Tools
             var doc = context.Document ?? throw new NoActiveDocumentException();
             var uiapp = context.UIApplication ?? throw new NoActiveDocumentException();
             var uidoc = uiapp.ActiveUIDocument ?? throw new NoActiveDocumentException();
+            DocumentGuard.CheckExpectedDocument(args, doc);
 
             string code = JsonArgs.GetString(args, "code") ?? string.Empty;
             if (string.IsNullOrWhiteSpace(code))

package/src/Revit/Tools/GetElementDetails.cs

@@ -27,7 +27,7 @@ namespace RevitBridge.Tools
                 {
                     type = "array",
                     items = new { type = "string" },
-                    description = "Only return these parameters (case-insensitive exact names). Default: all.",
+                    description = "Only return these parameters. Matches the display name OR the BuiltInParameter enum name (case-insensitive exact). Display names are localized (e.g. 'Mark' is 'Kennzeichen' in a German UI) — prefer enum names like ALL_MODEL_MARK for language-independent filtering. Default: all.",
                 },
                 include = new
                 {
@@ -101,12 +101,13 @@ namespace RevitBridge.Tools
                 };
 
                 int parameterCount = 0;
+                int parameterTotal = 0;
                 if (withParameters)
                 {
                     var parameters = new List<Dictionary<string, object?>>();
-                    AppendParameters(doc, element, nameFilter, isType: false, parameters);
+                    parameterTotal += AppendParameters(doc, element, nameFilter, isType: false, parameters);
                     if (withTypeParameters && elementType != null)
-                        AppendParameters(doc, elementType, nameFilter, isType: true, parameters);
+                        parameterTotal += AppendParameters(doc, elementType, nameFilter, isType: true, parameters);
                     dto["parameters"] = parameters;
                     parameterCount = parameters.Count;
                 }
@@ -119,7 +120,12 @@ namespace RevitBridge.Tools
                     dto["materials"] = DescribeMaterials(doc, element);
 
                 elements.Add(dto);
-                compactParts.Add($"'{element.Name}' (id {id}, {element.Category?.Name ?? "no category"}{(withParameters ? $", {parameterCount} params" : string.Empty)})");
+                // 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
+                    : nameFilter != null ? $", {parameterCount} of {parameterTotal} params matched parameter_names"
+                    : $", {parameterCount} params";
+                compactParts.Add($"'{element.Name}' (id {id}, {element.Category?.Name ?? "no category"}{paramSummary})");
             }
 
             string compact = $"{elements.Count} element(s)"
@@ -131,18 +137,32 @@ namespace RevitBridge.Tools
             return new ToolOutput(new { count = elements.Count, elements, not_found = notFound }, compact);
         }
 
-        private static void AppendParameters(Document doc, Element element, HashSet<string>? nameFilter, bool isType, List<Dictionary<string, object?>> target)
+        /// <summary>Appends matching parameter rows and returns how many parameters the
+        /// element exposes in total (before the name filter).</summary>
+        private static int AppendParameters(Document doc, Element element, HashSet<string>? nameFilter, bool isType, List<Dictionary<string, object?>> target)
         {
             var rows = new List<Dictionary<string, object?>>();
+            int total = 0;
             foreach (Parameter parameter in element.Parameters)
             {
+                total++;
                 string name = parameter.Definition?.Name ?? string.Empty;
                 if (nameFilter != null && !nameFilter.Contains(name))
-                    continue;
+                {
+                    // Display names are localized; accept the language-independent
+                    // BuiltInParameter enum name (e.g. ALL_MODEL_MARK) as an alias.
+                    string? builtIn = parameter.Definition is InternalDefinition internalDefinition
+                        && internalDefinition.BuiltInParameter != BuiltInParameter.INVALID
+                        ? internalDefinition.BuiltInParameter.ToString()
+                        : null;
+                    if (builtIn is null || !nameFilter.Contains(builtIn))
+                        continue;
+                }
                 rows.Add(DescribeParameter(doc, parameter, name, isType));
             }
             rows.Sort((a, b) => string.Compare(a["name"] as string, b["name"] as string, StringComparison.OrdinalIgnoreCase));
             target.AddRange(rows);
+            return total;
         }
 
         private static Dictionary<string, object?> DescribeParameter(Document doc, Parameter parameter, string name, bool isType)

package/src/Revit/Tools/GetElements.cs

@@ -287,6 +287,14 @@ namespace RevitBridge.Tools
                     break;
             }
 
+            // Display-name promotion is only trustworthy inside one category/class: the
+            // probe sees just the first ProbeSize elements in collector order, so in an
+            // unscoped query a unanimous sample can still hide other categories further
+            // on whose same-named parameter has a different id — and a pinned quick rule
+            // would silently drop their matches.
+            bool scoped = !string.IsNullOrWhiteSpace(JsonArgs.GetString(args, "category"))
+                || !string.IsNullOrWhiteSpace(JsonArgs.GetString(args, "of_class"));
+
             foreach (var rule in rules)
             {
                 if (rule.Op is RuleOp.Regex or RuleOp.IsEmpty or RuleOp.IsNotEmpty)
@@ -296,12 +304,11 @@ namespace RevitBridge.Tools
                     continue;
                 // BuiltInParameter/guid rules address one global parameter id. A plain
                 // display name can resolve to DIFFERENT ids per category or family
-                // (e.g. 'Width' -> DOOR_WIDTH vs WINDOW_WIDTH), and a quick rule pinned
-                // to one exemplar's id would silently drop every other category's
-                // matches. Promote only when all probed elements agree on the id;
-                // otherwise the rule stays on the (per-element, correct) post-scan path.
+                // (e.g. 'Width' -> DOOR_WIDTH vs WINDOW_WIDTH). Promote a display-name
+                // rule only when the query is scoped AND all probed elements agree on
+                // the id; otherwise it stays on the (per-element, correct) post-scan path.
                 bool oneGlobalId = rule.BuiltIn != null || rule.SharedGuid != null
-                    || found.All(parameter => parameter!.Id == found[0]!.Id);
+                    || (scoped && found.All(parameter => parameter!.Id == found[0]!.Id));
                 if (oneGlobalId)
                     rule.QuickRule = TryBuildQuickRule(doc, rule, found[0]!);
             }

package/src/Revit/Tools/SearchApiDocs.cs

@@ -222,11 +222,12 @@ namespace RevitBridge.Tools
             return markdown.ToString();
         }
 
-        /// <summary>The model sees only this markdown — details.payload never reaches it —
-        /// so the top match carries its remarks, parameter, return, and exception docs
-        /// inline (capped for display; the payload keeps full text). Lines that would blow
-        /// the markdown budget are dropped individually. When the top match is one of
-        /// several same-named overloads, a note says how to target another one.</summary>
+        /// <summary>The model can read details.payload (the cap note above even points it
+        /// there), but this markdown is what lands in the strongest-attention position of
+        /// the tool result — so the top match carries its remarks, parameter, return, and
+        /// exception docs inline (capped for display; the payload keeps full text). Lines
+        /// that would blow the markdown budget are dropped individually. When the top match
+        /// is one of several same-named overloads, a note says how to target another one.</summary>
         private static void AppendTopMatchDocs(StringBuilder markdown, ApiMember member, int overloadCount)
         {
             var lines = new List<string>(5);

package/src/Revit/Tools/SetParameters.cs

@@ -44,6 +44,11 @@ namespace RevitBridge.Tools
                         required = new[] { "element_id", "parameter", "value" },
                     },
                 },
+                expected_document = new
+                {
+                    type = "string",
+                    description = "Optional safety check: title of the document these writes are meant for (as reported by get_model_overview). If the active document differs (user switched models), the call fails without changing anything.",
+                },
             },
             required = new[] { "updates" },
         };
@@ -58,6 +63,7 @@ namespace RevitBridge.Tools
         public object? Execute(JsonElement args, ToolContext context)
         {
             var doc = context.Document ?? throw new NoActiveDocumentException();
+            DocumentGuard.CheckExpectedDocument(args, doc);
             var updates = ParseUpdates(args);
 
             var succeeded = new List<Dictionary<string, object?>>();

package/src/Revit/Tools/ToolSupport.cs

@@ -1,261 +1,301 @@
-using System.Text.Json;
-using Autodesk.Revit.DB;
-
-namespace RevitBridge.Tools
-{
-    /// <summary>
-    /// Resolves a user-facing category string (friendly alias, category display name,
-    /// or BuiltInCategory enum name like OST_Walls) to a category ElementId usable
-    /// with FilteredElementCollector.OfCategoryId. Shared by the query tools.
-    /// </summary>
-    internal static class CategoryResolver
-    {
-        private static readonly IReadOnlyDictionary<string, BuiltInCategory> Aliases = new Dictionary<string, BuiltInCategory>(StringComparer.OrdinalIgnoreCase)
-        {
-            ["wall"] = BuiltInCategory.OST_Walls,
-            ["walls"] = BuiltInCategory.OST_Walls,
-            ["door"] = BuiltInCategory.OST_Doors,
-            ["doors"] = BuiltInCategory.OST_Doors,
-            ["window"] = BuiltInCategory.OST_Windows,
-            ["windows"] = BuiltInCategory.OST_Windows,
-            ["floor"] = BuiltInCategory.OST_Floors,
-            ["floors"] = BuiltInCategory.OST_Floors,
-            ["room"] = BuiltInCategory.OST_Rooms,
-            ["rooms"] = BuiltInCategory.OST_Rooms,
-            ["area"] = BuiltInCategory.OST_Areas,
-            ["areas"] = BuiltInCategory.OST_Areas,
-            ["column"] = BuiltInCategory.OST_Columns,
-            ["columns"] = BuiltInCategory.OST_Columns,
-            ["roof"] = BuiltInCategory.OST_Roofs,
-            ["roofs"] = BuiltInCategory.OST_Roofs,
-            ["stair"] = BuiltInCategory.OST_Stairs,
-            ["stairs"] = BuiltInCategory.OST_Stairs,
-            ["ceiling"] = BuiltInCategory.OST_Ceilings,
-            ["ceilings"] = BuiltInCategory.OST_Ceilings,
-            ["furniture"] = BuiltInCategory.OST_Furniture,
-            ["pipe"] = BuiltInCategory.OST_PipeCurves,
-            ["pipes"] = BuiltInCategory.OST_PipeCurves,
-            ["duct"] = BuiltInCategory.OST_DuctCurves,
-            ["ducts"] = BuiltInCategory.OST_DuctCurves,
-            ["beam"] = BuiltInCategory.OST_StructuralFraming,
-            ["beams"] = BuiltInCategory.OST_StructuralFraming,
-            ["structural framing"] = BuiltInCategory.OST_StructuralFraming,
-            ["generic model"] = BuiltInCategory.OST_GenericModel,
-            ["generic models"] = BuiltInCategory.OST_GenericModel,
-            ["level"] = BuiltInCategory.OST_Levels,
-            ["levels"] = BuiltInCategory.OST_Levels,
-            ["grid"] = BuiltInCategory.OST_Grids,
-            ["grids"] = BuiltInCategory.OST_Grids,
-            ["sheet"] = BuiltInCategory.OST_Sheets,
-            ["sheets"] = BuiltInCategory.OST_Sheets,
-            ["view"] = BuiltInCategory.OST_Views,
-            ["views"] = BuiltInCategory.OST_Views,
-        };
-
-        public static ElementId Resolve(Document doc, string input)
-        {
-            string trimmed = input.Trim();
-            if (trimmed.Length == 0)
-                throw new ArgumentException("category must be a non-empty string.");
-
-            if (Aliases.TryGetValue(trimmed, out var alias))
-                return new ElementId(alias);
-            if (TryParseBuiltInCategory(trimmed, out var builtIn))
-                return new ElementId(builtIn);
-            if (TryParseBuiltInCategory("OST_" + trimmed.Replace(" ", string.Empty), out builtIn))
-                return new ElementId(builtIn);
-
-            foreach (Category category in doc.Settings.Categories)
-            {
-                if (string.Equals(category.Name, trimmed, StringComparison.OrdinalIgnoreCase))
-                    return category.Id;
-            }
-
-            throw new ArgumentException($"Unknown category: {input}. Use a BuiltInCategory enum name (e.g. OST_Walls) or a category display name as shown in Revit (e.g. Walls, Doors, Sheets, Views).");
-        }
-
-        private static bool TryParseBuiltInCategory(string text, out BuiltInCategory category)
-        {
-            category = BuiltInCategory.INVALID;
-            return text.Length > 0
-                && char.IsLetter(text[0])
-                && Enum.TryParse(text, true, out category)
-                && category != BuiltInCategory.INVALID;
-        }
-    }
-
-    /// <summary>
-    /// Resolves a Revit API class name ("Wall", "ViewSheet", "WallType", or a full
-    /// name like "Autodesk.Revit.DB.Mechanical.Duct") to its Type for OfClass filters.
-    /// </summary>
-    internal static class ElementClassResolver
-    {
-        private static readonly Lazy<IReadOnlyDictionary<string, Type>> BySimpleName = new(BuildSimpleNameMap);
-
-        public static Type Resolve(string input)
-        {
-            string trimmed = input.Trim();
-            var assembly = typeof(Element).Assembly;
-            Type? match = trimmed.Contains('.') ? assembly.GetType(trimmed, false, true) : null;
-            match ??= assembly.GetType("Autodesk.Revit.DB." + trimmed, false, true);
-            if (match is null)
-                BySimpleName.Value.TryGetValue(trimmed, out match);
-
-            if (match is null || !typeof(Element).IsAssignableFrom(match))
-                throw new ArgumentException($"Unknown Revit element class: {input}. Use an Element subclass from the Revit API (e.g. Wall, FamilyInstance, ViewSheet, Level, WallType) or a full name like Autodesk.Revit.DB.Mechanical.Duct.");
-            if (match == typeof(Element))
-                throw new ArgumentException("of_class must be a concrete Element subclass, not Element itself.");
-            return match;
-        }
-
-        private static IReadOnlyDictionary<string, Type> BuildSimpleNameMap()
-        {
-            Type[] types;
-            try
-            {
-                types = typeof(Element).Assembly.GetTypes();
-            }
-            catch (System.Reflection.ReflectionTypeLoadException ex)
-            {
-                types = ex.Types.OfType<Type>().ToArray();
-            }
-
-            var map = new Dictionary<string, Type>(StringComparer.OrdinalIgnoreCase);
-            foreach (var type in types)
-            {
-                if (!type.IsPublic || !typeof(Element).IsAssignableFrom(type))
-                    continue;
-                // Prefer the root Autodesk.Revit.DB namespace when simple names collide.
-                if (!map.TryGetValue(type.Name, out var existing) || (type.Namespace == "Autodesk.Revit.DB" && existing.Namespace != "Autodesk.Revit.DB"))
-                    map[type.Name] = type;
-            }
-            return map;
-        }
-    }
-
-    /// <summary>
-    /// Resolves friendly forge unit names ("millimeters", "squareMeters") or full forge
-    /// ids ("autodesk.unit.unit:millimeters-1.0.1") to UnitTypeId values, and back.
-    /// </summary>
-    internal static class UnitResolver
-    {
-        private static readonly Lazy<IReadOnlyDictionary<string, ForgeTypeId>> ByName = new(Build);
-
-        public static ForgeTypeId Resolve(string unit)
-        {
-            string trimmed = unit.Trim();
-            if (ByName.Value.TryGetValue(trimmed, out var match))
-                return match;
-            throw new ArgumentException($"Unknown unit: {unit}. Use a forge unit name like millimeters, meters, feet, inches, squareMeters, cubicFeet, degrees.");
-        }
-
-        /// <summary>"autodesk.unit.unit:millimeters-1.0.1" -> "millimeters".</summary>
-        public static string ShortName(ForgeTypeId unit)
-        {
-            string id = unit.TypeId ?? string.Empty;
-            int colon = id.IndexOf(':');
-            string tail = colon >= 0 ? id[(colon + 1)..] : id;
-            int dash = tail.IndexOf('-');
-            return dash >= 0 ? tail[..dash] : tail;
-        }
-
-        private static IReadOnlyDictionary<string, ForgeTypeId> Build()
-        {
-            var map = new Dictionary<string, ForgeTypeId>(StringComparer.OrdinalIgnoreCase);
-            foreach (ForgeTypeId unit in UnitUtils.GetAllUnits())
-            {
-                map[ShortName(unit)] = unit;
-                map[unit.TypeId] = unit;
-            }
-            return map;
-        }
-    }
-
-    /// <summary>Identity-only element row shared by the query tools.</summary>
-    internal static class ElementIdentity
-    {
-        public static readonly IReadOnlyList<string> Fields = new[] { "id", "name", "category", "typeName", "levelId" };
-
-        public static Dictionary<string, object?> Build(Document doc, Element element, IReadOnlyList<string> fields)
-        {
-            var row = new Dictionary<string, object?>(fields.Count);
-            foreach (string field in fields)
-            {
-                row[field] = field switch
-                {
-                    "id" => (object?)element.Id.Value,
-                    "name" => element.Name,
-                    "category" => element.Category?.Name,
-                    "typeName" => doc.GetElement(element.GetTypeId())?.Name,
-                    "levelId" => element.LevelId is { } levelId && levelId != ElementId.InvalidElementId ? levelId.Value : (long?)null,
-                    _ => null,
-                };
-            }
-            return row;
-        }
-    }
-
-    /// <summary>Small JsonElement argument readers shared by the tools.</summary>
-    internal static class JsonArgs
-    {
-        public static string? GetString(JsonElement args, string name)
-            => args.ValueKind == JsonValueKind.Object && args.TryGetProperty(name, out var value) && value.ValueKind == JsonValueKind.String
-                ? value.GetString()
-                : null;
-
-        public static bool GetBool(JsonElement args, string name, bool fallback)
-            => args.ValueKind == JsonValueKind.Object && args.TryGetProperty(name, out var value) && value.ValueKind is JsonValueKind.True or JsonValueKind.False
-                ? value.GetBoolean()
-                : fallback;
-
-        public static int GetInt(JsonElement args, string name, int fallback)
-            => args.ValueKind == JsonValueKind.Object && args.TryGetProperty(name, out var value) && value.ValueKind == JsonValueKind.Number && value.TryGetInt32(out int parsed)
-                ? parsed
-                : fallback;
-
-        public static long? GetLong(JsonElement args, string name)
-        {
-            if (args.ValueKind != JsonValueKind.Object || !args.TryGetProperty(name, out var value))
-                return null;
-            if (value.ValueKind == JsonValueKind.Number && value.TryGetInt64(out long fromNumber))
-                return fromNumber;
-            if (value.ValueKind == JsonValueKind.String && long.TryParse(value.GetString(), out long fromString))
-                return fromString;
-            return null;
-        }
-
-        public static List<long> GetLongArray(JsonElement args, string name)
-        {
-            if (args.ValueKind != JsonValueKind.Object || !args.TryGetProperty(name, out var value) || value.ValueKind != JsonValueKind.Array)
-                throw new ArgumentException($"Missing or invalid required field: {name} must be an array of element ids.");
-
-            var result = new List<long>(value.GetArrayLength());
-            foreach (var item in value.EnumerateArray())
-            {
-                if (item.ValueKind == JsonValueKind.Number && item.TryGetInt64(out long fromNumber))
-                    result.Add(fromNumber);
-                else if (item.ValueKind == JsonValueKind.String && long.TryParse(item.GetString(), out long fromString))
-                    result.Add(fromString);
-                else
-                    throw new ArgumentException($"{name} must contain only integer element ids.");
-            }
-            return result;
-        }
-
-        public static List<string>? GetStringArray(JsonElement args, string name)
-        {
-            if (args.ValueKind != JsonValueKind.Object || !args.TryGetProperty(name, out var value) || value.ValueKind != JsonValueKind.Array)
-                return null;
-
-            var result = new List<string>(value.GetArrayLength());
-            foreach (var item in value.EnumerateArray())
-            {
-                string? text = item.ValueKind == JsonValueKind.String ? item.GetString() : null;
-                if (string.IsNullOrWhiteSpace(text))
-                    throw new ArgumentException($"{name} must contain only non-empty strings.");
-                result.Add(text.Trim());
-            }
-            return result;
-        }
-    }
-}
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools
+{
+    /// <summary>
+    /// Resolves a user-facing category string (friendly alias, category display name,
+    /// or BuiltInCategory enum name like OST_Walls) to a category ElementId usable
+    /// with FilteredElementCollector.OfCategoryId. Shared by the query tools.
+    /// </summary>
+    internal static class CategoryResolver
+    {
+        private static readonly IReadOnlyDictionary<string, BuiltInCategory> Aliases = new Dictionary<string, BuiltInCategory>(StringComparer.OrdinalIgnoreCase)
+        {
+            ["wall"] = BuiltInCategory.OST_Walls,
+            ["walls"] = BuiltInCategory.OST_Walls,
+            ["door"] = BuiltInCategory.OST_Doors,
+            ["doors"] = BuiltInCategory.OST_Doors,
+            ["window"] = BuiltInCategory.OST_Windows,
+            ["windows"] = BuiltInCategory.OST_Windows,
+            ["floor"] = BuiltInCategory.OST_Floors,
+            ["floors"] = BuiltInCategory.OST_Floors,
+            ["room"] = BuiltInCategory.OST_Rooms,
+            ["rooms"] = BuiltInCategory.OST_Rooms,
+            ["area"] = BuiltInCategory.OST_Areas,
+            ["areas"] = BuiltInCategory.OST_Areas,
+            ["column"] = BuiltInCategory.OST_Columns,
+            ["columns"] = BuiltInCategory.OST_Columns,
+            ["roof"] = BuiltInCategory.OST_Roofs,
+            ["roofs"] = BuiltInCategory.OST_Roofs,
+            ["stair"] = BuiltInCategory.OST_Stairs,
+            ["stairs"] = BuiltInCategory.OST_Stairs,
+            ["ceiling"] = BuiltInCategory.OST_Ceilings,
+            ["ceilings"] = BuiltInCategory.OST_Ceilings,
+            ["furniture"] = BuiltInCategory.OST_Furniture,
+            ["pipe"] = BuiltInCategory.OST_PipeCurves,
+            ["pipes"] = BuiltInCategory.OST_PipeCurves,
+            ["duct"] = BuiltInCategory.OST_DuctCurves,
+            ["ducts"] = BuiltInCategory.OST_DuctCurves,
+            ["beam"] = BuiltInCategory.OST_StructuralFraming,
+            ["beams"] = BuiltInCategory.OST_StructuralFraming,
+            ["structural framing"] = BuiltInCategory.OST_StructuralFraming,
+            ["generic model"] = BuiltInCategory.OST_GenericModel,
+            ["generic models"] = BuiltInCategory.OST_GenericModel,
+            ["level"] = BuiltInCategory.OST_Levels,
+            ["levels"] = BuiltInCategory.OST_Levels,
+            ["grid"] = BuiltInCategory.OST_Grids,
+            ["grids"] = BuiltInCategory.OST_Grids,
+            ["sheet"] = BuiltInCategory.OST_Sheets,
+            ["sheets"] = BuiltInCategory.OST_Sheets,
+            ["view"] = BuiltInCategory.OST_Views,
+            ["views"] = BuiltInCategory.OST_Views,
+        };
+
+        public static ElementId Resolve(Document doc, string input)
+        {
+            string trimmed = input.Trim();
+            if (trimmed.Length == 0)
+                throw new ArgumentException("category must be a non-empty string.");
+
+            if (Aliases.TryGetValue(trimmed, out var alias))
+                return new ElementId(alias);
+            if (TryParseBuiltInCategory(trimmed, out var builtIn))
+                return new ElementId(builtIn);
+            if (TryParseBuiltInCategory("OST_" + trimmed.Replace(" ", string.Empty), out builtIn))
+                return new ElementId(builtIn);
+
+            foreach (Category category in doc.Settings.Categories)
+            {
+                if (string.Equals(category.Name, trimmed, StringComparison.OrdinalIgnoreCase))
+                    return category.Id;
+            }
+
+            throw new ArgumentException($"Unknown category: {input}. Use a BuiltInCategory enum name (e.g. OST_Walls) or a category display name as shown in Revit (e.g. Walls, Doors, Sheets, Views).");
+        }
+
+        private static bool TryParseBuiltInCategory(string text, out BuiltInCategory category)
+        {
+            category = BuiltInCategory.INVALID;
+            return text.Length > 0
+                && char.IsLetter(text[0])
+                && Enum.TryParse(text, true, out category)
+                && category != BuiltInCategory.INVALID;
+        }
+    }
+
+    /// <summary>
+    /// Resolves a Revit API class name ("Wall", "ViewSheet", "WallType", or a full
+    /// name like "Autodesk.Revit.DB.Mechanical.Duct") to its Type for OfClass filters.
+    /// </summary>
+    internal static class ElementClassResolver
+    {
+        private static readonly Lazy<IReadOnlyDictionary<string, Type>> BySimpleName = new(BuildSimpleNameMap);
+
+        public static Type Resolve(string input)
+        {
+            string trimmed = input.Trim();
+            var assembly = typeof(Element).Assembly;
+            Type? match = trimmed.Contains('.') ? assembly.GetType(trimmed, false, true) : null;
+            match ??= assembly.GetType("Autodesk.Revit.DB." + trimmed, false, true);
+            if (match is null)
+                BySimpleName.Value.TryGetValue(trimmed, out match);
+
+            if (match is null || !typeof(Element).IsAssignableFrom(match))
+                throw new ArgumentException($"Unknown Revit element class: {input}. Use an Element subclass from the Revit API (e.g. Wall, FamilyInstance, ViewSheet, Level, WallType) or a full name like Autodesk.Revit.DB.Mechanical.Duct.");
+            if (match == typeof(Element))
+                throw new ArgumentException("of_class must be a concrete Element subclass, not Element itself.");
+            return match;
+        }
+
+        private static IReadOnlyDictionary<string, Type> BuildSimpleNameMap()
+        {
+            Type[] types;
+            try
+            {
+                types = typeof(Element).Assembly.GetTypes();
+            }
+            catch (System.Reflection.ReflectionTypeLoadException ex)
+            {
+                types = ex.Types.OfType<Type>().ToArray();
+            }
+
+            var map = new Dictionary<string, Type>(StringComparer.OrdinalIgnoreCase);
+            foreach (var type in types)
+            {
+                if (!type.IsPublic || !typeof(Element).IsAssignableFrom(type))
+                    continue;
+                // Prefer the root Autodesk.Revit.DB namespace when simple names collide.
+                if (!map.TryGetValue(type.Name, out var existing) || (type.Namespace == "Autodesk.Revit.DB" && existing.Namespace != "Autodesk.Revit.DB"))
+                    map[type.Name] = type;
+            }
+            return map;
+        }
+    }
+
+    /// <summary>
+    /// Resolves friendly forge unit names ("millimeters", "squareMeters") or full forge
+    /// ids ("autodesk.unit.unit:millimeters-1.0.1") to UnitTypeId values, and back.
+    /// </summary>
+    internal static class UnitResolver
+    {
+        private static readonly Lazy<IReadOnlyDictionary<string, ForgeTypeId>> ByName = new(Build);
+
+        public static ForgeTypeId Resolve(string unit)
+        {
+            string trimmed = unit.Trim();
+            if (ByName.Value.TryGetValue(trimmed, out var match))
+                return match;
+            throw new ArgumentException($"Unknown unit: {unit}. Use a forge unit name like millimeters, meters, feet, inches, squareMeters, cubicFeet, degrees.");
+        }
+
+        /// <summary>"autodesk.unit.unit:millimeters-1.0.1" -> "millimeters".</summary>
+        public static string ShortName(ForgeTypeId unit)
+        {
+            string id = unit.TypeId ?? string.Empty;
+            int colon = id.IndexOf(':');
+            string tail = colon >= 0 ? id[(colon + 1)..] : id;
+            int dash = tail.IndexOf('-');
+            return dash >= 0 ? tail[..dash] : tail;
+        }
+
+        private static IReadOnlyDictionary<string, ForgeTypeId> Build()
+        {
+            var map = new Dictionary<string, ForgeTypeId>(StringComparer.OrdinalIgnoreCase);
+            foreach (ForgeTypeId unit in UnitUtils.GetAllUnits())
+            {
+                map[ShortName(unit)] = unit;
+                map[unit.TypeId] = unit;
+            }
+            return map;
+        }
+    }
+
+    /// <summary>Identity-only element row shared by the query tools.</summary>
+    internal static class ElementIdentity
+    {
+        public static readonly IReadOnlyList<string> Fields = new[] { "id", "name", "category", "typeName", "levelId" };
+
+        public static Dictionary<string, object?> Build(Document doc, Element element, IReadOnlyList<string> fields)
+        {
+            var row = new Dictionary<string, object?>(fields.Count);
+            foreach (string field in fields)
+            {
+                row[field] = field switch
+                {
+                    "id" => (object?)element.Id.Value,
+                    "name" => element.Name,
+                    "category" => element.Category?.Name,
+                    "typeName" => doc.GetElement(element.GetTypeId())?.Name,
+                    "levelId" => element.LevelId is { } levelId && levelId != ElementId.InvalidElementId ? levelId.Value : (long?)null,
+                    _ => null,
+                };
+            }
+            return row;
+        }
+    }
+
+    /// <summary>Small JsonElement argument readers shared by the tools.</summary>
+    internal static class JsonArgs
+    {
+        public static string? GetString(JsonElement args, string name)
+            => args.ValueKind == JsonValueKind.Object && args.TryGetProperty(name, out var value) && value.ValueKind == JsonValueKind.String
+                ? value.GetString()
+                : null;
+
+        public static bool GetBool(JsonElement args, string name, bool fallback)
+            => args.ValueKind == JsonValueKind.Object && args.TryGetProperty(name, out var value) && value.ValueKind is JsonValueKind.True or JsonValueKind.False
+                ? value.GetBoolean()
+                : fallback;
+
+        public static int GetInt(JsonElement args, string name, int fallback)
+            => args.ValueKind == JsonValueKind.Object && args.TryGetProperty(name, out var value) && value.ValueKind == JsonValueKind.Number && value.TryGetInt32(out int parsed)
+                ? parsed
+                : fallback;
+
+        public static long? GetLong(JsonElement args, string name)
+        {
+            if (args.ValueKind != JsonValueKind.Object || !args.TryGetProperty(name, out var value))
+                return null;
+            if (value.ValueKind == JsonValueKind.Number && value.TryGetInt64(out long fromNumber))
+                return fromNumber;
+            if (value.ValueKind == JsonValueKind.String && long.TryParse(value.GetString(), out long fromString))
+                return fromString;
+            return null;
+        }
+
+        public static List<long> GetLongArray(JsonElement args, string name)
+        {
+            if (args.ValueKind != JsonValueKind.Object || !args.TryGetProperty(name, out var value) || value.ValueKind != JsonValueKind.Array)
+                throw new ArgumentException($"Missing or invalid required field: {name} must be an array of element ids.");
+
+            var result = new List<long>(value.GetArrayLength());
+            foreach (var item in value.EnumerateArray())
+            {
+                if (item.ValueKind == JsonValueKind.Number && item.TryGetInt64(out long fromNumber))
+                    result.Add(fromNumber);
+                else if (item.ValueKind == JsonValueKind.String && long.TryParse(item.GetString(), out long fromString))
+                    result.Add(fromString);
+                else
+                    throw new ArgumentException($"{name} must contain only integer element ids.");
+            }
+            return result;
+        }
+
+        public static List<string>? GetStringArray(JsonElement args, string name)
+        {
+            if (args.ValueKind != JsonValueKind.Object || !args.TryGetProperty(name, out var value) || value.ValueKind != JsonValueKind.Array)
+                return null;
+
+            var result = new List<string>(value.GetArrayLength());
+            foreach (var item in value.EnumerateArray())
+            {
+                string? text = item.ValueKind == JsonValueKind.String ? item.GetString() : null;
+                if (string.IsNullOrWhiteSpace(text))
+                    throw new ArgumentException($"{name} must contain only non-empty strings.");
+                result.Add(text.Trim());
+            }
+            return result;
+        }
+    }
+
+    /// <summary>
+    /// Optional wrong-document protection for write tools. A write queued while the
+    /// user switches models would otherwise land in whichever document is active when
+    /// the queued call runs -- possibly silently, since low element ids resolve in
+    /// most documents. Tools pass the caller's optional expected_document through
+    /// here before touching the model.
+    /// </summary>
+    internal static class DocumentGuard
+    {
+        /// <summary>Throws when expected_document is provided and does not match the
+        /// active document's title (case-insensitive; the .rvt extension and a
+        /// detached suffix are tolerated). No-op when the argument is absent.</summary>
+        public static void CheckExpectedDocument(JsonElement args, Document doc)
+        {
+            string? expected = JsonArgs.GetString(args, "expected_document");
+            if (string.IsNullOrWhiteSpace(expected))
+                return;
+            string actual = doc.Title;
+            if (Matches(expected, actual))
+                return;
+            throw new ArgumentException(
+                $"Active document is '{actual}' but this call expected '{expected}'. Nothing was changed. "
+                + "The user switched models (or several are open); re-read the target model (get_model_overview) and retry against the right one.");
+        }
+
+        private static bool Matches(string expected, string actual)
+        {
+            static string Normalize(string value)
+            {
+                string v = value.Trim();
+                if (v.EndsWith(".rvt", StringComparison.OrdinalIgnoreCase))
+                    v = v[..^4];
+                if (v.EndsWith("_detached", StringComparison.OrdinalIgnoreCase))
+                    v = v[..^"_detached".Length];
+                return v;
+            }
+            return string.Equals(Normalize(expected), Normalize(actual), StringComparison.OrdinalIgnoreCase);
+        }
+    }
+}