pi-revit 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -7,6 +7,12 @@ 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.3.1] - 2026-09-16
+
+### Fixed
+
+- The installer checks the selected .NET SDK before installing packages or building the add-in. Missing or older SDKs now produce a clear explanation, the matching Windows x64 SDK download link, and retry instructions. Interactive installs offer to open the download page. Manual builds and deployments also check the SDK before compiling.
+
 ## [0.3.0] - 2026-09-09
 
 ### Added

package/README.md

@@ -107,9 +107,18 @@ npx.cmd -y pi-revit
 ```
 
 This installs the Pi package, builds and deploys the Revit bridge add-in, creates the
-`Documents\pi-revit` workspace, and installs the global `pi-revit` command.
-
-Start Revit (click **Always Load** on the unsigned add-in prompt once) and open any
+`Documents\pi-revit` workspace, and installs the global `pi-revit` command.
+
+The installer first checks the selected .NET SDK. If it is missing or too old,
+installation stops with the required version, a download link, and retry steps.
+Interactive terminals also offer to open the download page. Revit uses a runtime
+to run; compiling this add-in also needs the SDK. For Revit 2027, install the
+[.NET 10 SDK for Windows x64](https://dotnet.microsoft.com/en-us/download/dotnet/10.0),
+reopen PowerShell, and rerun the installer. Existing .NET versions can stay installed.
+If an older SDK is still selected, check `dotnet --list-sdks`, your `PATH`, and any
+`global.json` in the current directory or its parents.
+
+Start Revit (click **Always Load** on the unsigned add-in prompt once) and open any
 project. No panel or ribbon appears — the add-in is headless.
 
 ### Manual npm install

package/bin/pi-revit.js

@@ -37,10 +37,10 @@ function runCmd(title, commandLine) {
 	if (result.status !== 0) process.exit(result.status ?? 1);
 }
 
-function runPowerShellScript(scriptName) {
+function runPowerShellScript(scriptName, args = []) {
 	const scriptPath = path.join(scriptsDir, scriptName);
 	if (!fs.existsSync(scriptPath)) fail(`missing script: ${scriptPath}`);
-	run(scriptName, "powershell.exe", ["-ExecutionPolicy", "Bypass", "-File", scriptPath]);
+	run(scriptName, "powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", scriptPath, ...args]);
 }
 
 function revitIsRunning() {
@@ -74,9 +74,7 @@ if (!commandExists("pi")) {
 	fail("the 'pi' command was not found on PATH. Install Pi first: npm install -g --ignore-scripts @earendil-works/pi-coding-agent");
 }
 
-if (!commandExists("dotnet")) {
-	fail("the 'dotnet' command was not found on PATH. Install the .NET SDK required by your Revit version.");
-}
+runPowerShellScript("deploy.ps1", ["-CheckOnly", "-OfferDownload"]);
 
 if (revitIsRunning()) {
 	waitForEnter();

package/extensions/pi-revit/index.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type, type TSchema } from "typebox";
-import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
+import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -48,13 +48,13 @@ interface BridgeToolDescriptor {
 const DEFAULT_TIMEOUT_MS = 30_000;
 const LONG_TIMEOUT_MS = 120_000;
 const DISCOVERY_TIMEOUT_MS = 10_000;
-const MAX_MODEL_CONTENT_CHARS = 12_000;
-const MAX_RESULT_PAGE_CHARS = 8_000;
-
-// IDs only resolve results created by this extension instance. A caller cannot
-// turn read_revit_result into an arbitrary filesystem read by supplying a path.
-const savedResults = new Map<string, string>();
-let resultDirectory: Promise<string> | undefined;
+const MAX_MODEL_CONTENT_CHARS = 12_000;
+const MAX_RESULT_PAGE_CHARS = 8_000;
+
+// IDs only resolve results created by this extension instance. A caller cannot
+// turn read_revit_result into an arbitrary filesystem read by supplying a path.
+const savedResults = new Map<string, string>();
+let resultDirectory: Promise<string> | undefined;
 
 /** Tools with a longer budget; everything else gets DEFAULT_TIMEOUT_MS. The same
  * value is sent to the bridge as timeout_ms and used client-side via AbortSignal. */
@@ -160,88 +160,88 @@ export async function bridgeRequest(
 	return payload;
 }
 
-export function capText(text: string): string {
-	if (text.length <= MAX_MODEL_CONTENT_CHARS) return text;
-	const suffix = `... [truncated preview at ${MAX_MODEL_CONTENT_CHARS} chars]`;
-	return text.slice(0, Math.max(0, MAX_MODEL_CONTENT_CHARS - suffix.length)) + suffix;
-}
-
-async function modelContent(name: string, payload: BridgeToolResponse): Promise<{ type: "text"; text: string }[]> {
-	const details = payload.details;
-	const value = details !== null && typeof details === "object" && Object.hasOwn(details, "payload")
-		? (details as { payload: unknown }).payload
-		: details;
-	// Current and older bridges both carry the full value in details.payload.
-	// Pi sends content to the model; details alone is only available to its UI.
-	const text = details !== undefined
-		? JSON.stringify(value, null, 2) ?? "null"
-		: payload.content?.map((block) => block.text).join("\n") ?? "{}";
-	if (text.length <= MAX_MODEL_CONTENT_CHARS) return [{ type: "text", text }];
-
-	const resultId = randomUUID();
-	let filePath: string;
-	try {
-		const directory = await (resultDirectory ??= mkdtemp(path.join(os.tmpdir(), "pi-revit-results-")).catch((error) => {
-			// A transient failure must not poison every later large result in this session.
-			resultDirectory = undefined;
-			throw error;
-		}));
-		filePath = path.join(directory, `${resultId}.json`);
-		await writeFile(filePath, text, { encoding: "utf8", flag: "wx", mode: 0o600 });
-	} catch (error) {
-		const reason = error instanceof Error ? error.message : String(error);
-		throw new Error(`Revit completed '${name}', but its large result could not be saved locally: ${reason}. Verify model state before retrying a write.`);
-	}
-	savedResults.set(resultId, filePath);
-	return [{ type: "text", text: JSON.stringify({
-		result_id: resultId,
-		file_path: filePath,
-		total_chars: text.length,
-		complete_inline: false,
-		retrieval: { tool: "read_revit_result", result_id: resultId, offset: 0, limit: MAX_RESULT_PAGE_CHARS },
-		instructions: "The complete result is saved locally. Call read_revit_result, then follow next_offset until has_more is false. Each page is a fragment of the saved text, not a standalone result. Offsets count UTF-16 code units. The absolute file can also be opened with read; it remains available after an extension reload, when this session's result ID may no longer resolve.",
-	}) }];
-}
-
-function registerResultReader(pi: ExtensionAPI) {
-	pi.registerTool({
-		name: "read_revit_result",
-		label: "Read Saved Revit Result",
-		description: "Read a bounded fragment of a large Revit tool result using its opaque result_id. This reads a saved local result and does not contact Revit. Follow next_offset until has_more is false; text fragments concatenate to the complete saved result. Offsets count UTF-16 code units.",
-		parameters: Type.Object({
-			result_id: Type.String({ description: "Opaque result_id returned by a Revit tool in this extension session." }),
-			offset: Type.Optional(Type.Integer({ minimum: 0, description: "Character offset from the previous page's next_offset; default 0." })),
-			limit: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_RESULT_PAGE_CHARS, description: "Maximum characters to return; default 8000. Escaping may require a smaller fragment." })),
-		}),
-		executionMode: "sequential",
-		async execute(_toolCallId, params) {
-			const offset = params.offset ?? 0;
-			const limit = params.limit ?? MAX_RESULT_PAGE_CHARS;
-			if (!Number.isSafeInteger(offset) || offset < 0) throw new Error("offset must be a non-negative integer.");
-			if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_RESULT_PAGE_CHARS)
-				throw new Error(`limit must be an integer from 1 to ${MAX_RESULT_PAGE_CHARS}.`);
-			const filePath = savedResults.get(params.result_id);
-			if (!filePath) throw new Error("Unknown result_id for this extension session. Use the original result's file_path with read if the extension was reloaded.");
-			const text = await readFile(filePath, "utf8");
-			if (offset > text.length) throw new Error(`offset exceeds this result's ${text.length} characters.`);
-			const encode = (count: number) => JSON.stringify({
-				result_id: params.result_id, offset, returned_chars: count, total_chars: text.length,
-				has_more: offset + count < text.length,
-				next_offset: offset + count < text.length ? offset + count : null,
-				fragment: true, text: text.slice(offset, offset + count),
-			});
-			// Bound the actual model message, including JSON escaping and metadata.
-			let low = 0;
-			let high = Math.min(limit, text.length - offset);
-			while (low < high) {
-				const count = Math.ceil((low + high) / 2);
-				if (encode(count).length <= MAX_MODEL_CONTENT_CHARS) low = count;
-				else high = count - 1;
-			}
-			return { content: [{ type: "text", text: encode(low) }], details: { filePath } };
-		},
-	});
-}
+export function capText(text: string): string {
+	if (text.length <= MAX_MODEL_CONTENT_CHARS) return text;
+	const suffix = `... [truncated preview at ${MAX_MODEL_CONTENT_CHARS} chars]`;
+	return text.slice(0, Math.max(0, MAX_MODEL_CONTENT_CHARS - suffix.length)) + suffix;
+}
+
+async function modelContent(name: string, payload: BridgeToolResponse): Promise<{ type: "text"; text: string }[]> {
+	const details = payload.details;
+	const value = details !== null && typeof details === "object" && Object.hasOwn(details, "payload")
+		? (details as { payload: unknown }).payload
+		: details;
+	// Current and older bridges both carry the full value in details.payload.
+	// Pi sends content to the model; details alone is only available to its UI.
+	const text = details !== undefined
+		? JSON.stringify(value, null, 2) ?? "null"
+		: payload.content?.map((block) => block.text).join("\n") ?? "{}";
+	if (text.length <= MAX_MODEL_CONTENT_CHARS) return [{ type: "text", text }];
+
+	const resultId = randomUUID();
+	let filePath: string;
+	try {
+		const directory = await (resultDirectory ??= mkdtemp(path.join(os.tmpdir(), "pi-revit-results-")).catch((error) => {
+			// A transient failure must not poison every later large result in this session.
+			resultDirectory = undefined;
+			throw error;
+		}));
+		filePath = path.join(directory, `${resultId}.json`);
+		await writeFile(filePath, text, { encoding: "utf8", flag: "wx", mode: 0o600 });
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new Error(`Revit completed '${name}', but its large result could not be saved locally: ${reason}. Verify model state before retrying a write.`);
+	}
+	savedResults.set(resultId, filePath);
+	return [{ type: "text", text: JSON.stringify({
+		result_id: resultId,
+		file_path: filePath,
+		total_chars: text.length,
+		complete_inline: false,
+		retrieval: { tool: "read_revit_result", result_id: resultId, offset: 0, limit: MAX_RESULT_PAGE_CHARS },
+		instructions: "The complete result is saved locally. Call read_revit_result, then follow next_offset until has_more is false. Each page is a fragment of the saved text, not a standalone result. Offsets count UTF-16 code units. The absolute file can also be opened with read; it remains available after an extension reload, when this session's result ID may no longer resolve.",
+	}) }];
+}
+
+function registerResultReader(pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "read_revit_result",
+		label: "Read Saved Revit Result",
+		description: "Read a bounded fragment of a large Revit tool result using its opaque result_id. This reads a saved local result and does not contact Revit. Follow next_offset until has_more is false; text fragments concatenate to the complete saved result. Offsets count UTF-16 code units.",
+		parameters: Type.Object({
+			result_id: Type.String({ description: "Opaque result_id returned by a Revit tool in this extension session." }),
+			offset: Type.Optional(Type.Integer({ minimum: 0, description: "Character offset from the previous page's next_offset; default 0." })),
+			limit: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_RESULT_PAGE_CHARS, description: "Maximum characters to return; default 8000. Escaping may require a smaller fragment." })),
+		}),
+		executionMode: "sequential",
+		async execute(_toolCallId, params) {
+			const offset = params.offset ?? 0;
+			const limit = params.limit ?? MAX_RESULT_PAGE_CHARS;
+			if (!Number.isSafeInteger(offset) || offset < 0) throw new Error("offset must be a non-negative integer.");
+			if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_RESULT_PAGE_CHARS)
+				throw new Error(`limit must be an integer from 1 to ${MAX_RESULT_PAGE_CHARS}.`);
+			const filePath = savedResults.get(params.result_id);
+			if (!filePath) throw new Error("Unknown result_id for this extension session. Use the original result's file_path with read if the extension was reloaded.");
+			const text = await readFile(filePath, "utf8");
+			if (offset > text.length) throw new Error(`offset exceeds this result's ${text.length} characters.`);
+			const encode = (count: number) => JSON.stringify({
+				result_id: params.result_id, offset, returned_chars: count, total_chars: text.length,
+				has_more: offset + count < text.length,
+				next_offset: offset + count < text.length ? offset + count : null,
+				fragment: true, text: text.slice(offset, offset + count),
+			});
+			// Bound the actual model message, including JSON escaping and metadata.
+			let low = 0;
+			let high = Math.min(limit, text.length - offset);
+			while (low < high) {
+				const count = Math.ceil((low + high) / 2);
+				if (encode(count).length <= MAX_MODEL_CONTENT_CHARS) low = count;
+				else high = count - 1;
+			}
+			return { content: [{ type: "text", text: encode(low) }], details: { filePath } };
+		},
+	});
+}
 
 async function runBridgeTool(name: string, args: unknown, signal: AbortSignal | undefined, timeoutMs: number) {
 	const payload = (await bridgeRequest(
@@ -255,7 +255,7 @@ async function runBridgeTool(name: string, args: unknown, signal: AbortSignal |
 		timeoutMs,
 	)) as BridgeToolResponse;
 
-	return { content: await modelContent(name, payload), details: payload.details };
+	return { content: await modelContent(name, payload), details: payload.details };
 }
 
 function registerBridgeTool(pi: ExtensionAPI, descriptor: BridgeToolDescriptor) {
@@ -384,8 +384,8 @@ function registerPing(pi: ExtensionAPI, onBridgeAlive?: () => Promise<"ready" |
 
 const REDISCOVERY_INTERVAL_MS = 15_000;
 
-export default async function revitConnector(pi: ExtensionAPI) {
-	registerResultReader(pi);
+export default async function revitConnector(pi: ExtensionAPI) {
+	registerResultReader(pi);
 	// 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
@@ -406,7 +406,7 @@ export default async function revitConnector(pi: ExtensionAPI) {
 				if (descriptors.length === 0) return false;
 				for (const descriptor of descriptors) {
 					if (!descriptor || typeof descriptor.name !== "string" || !descriptor.name) continue;
-					if (descriptor.name === "ping" || descriptor.name === "read_revit_result") continue;
+					if (descriptor.name === "ping" || descriptor.name === "read_revit_result") continue;
 					registerBridgeTool(pi, descriptor);
 				}
 				bridgeToolsRegistered = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-revit",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Native Pi connector for Autodesk Revit. Run npx.cmd -y pi-revit for the full Windows install.",
   "author": "Ahmad Altahlawi",
   "license": "MIT",
@@ -27,8 +27,9 @@
     "deploy": "powershell -ExecutionPolicy Bypass -File scripts/deploy.ps1",
     "setup": "powershell -ExecutionPolicy Bypass -File scripts/setup-workspace.ps1",
     "uninstall:revit": "powershell -ExecutionPolicy Bypass -File scripts/uninstall.ps1",
-    "test:search": "dotnet run --project tests/search-engine",
-    "test:installer": "node tests/installer/installer.test.cjs"
+    "test:search": "dotnet run --project tests/search-engine",
+    "test:installer": "node --test tests/installer/*.test.cjs",
+    "test:sdk": "powershell -NoProfile -ExecutionPolicy Bypass -File tests/installer/sdk.test.ps1"
   },
   "files": [
     "bin/",

package/scripts/build.ps1

@@ -17,9 +17,15 @@ param(
 )
 
 $ErrorActionPreference = 'Stop'
-$project = Join-Path $PSScriptRoot '..\src\Revit\RevitBridge.csproj'
-
-$buildArgs = @('build', $project, '-c', $Configuration)
+$project = Join-Path $PSScriptRoot '..\src\Revit\RevitBridge.csproj'
+
+. (Join-Path $PSScriptRoot 'check-sdk.ps1')
+$frameworks = if ($TargetFramework) { $TargetFramework -split ';' } else {
+    ([xml](Get-Content $project -Raw)).Project.PropertyGroup.TargetFrameworks | Where-Object { $_ } | ForEach-Object { $_ -split ';' }
+}
+if (-not (Test-PiRevitSdk -TargetFrameworks $frameworks)) { exit 1 }
+
+$buildArgs = @('build', $project, '-c', $Configuration)
 
 # Stamp the package version into the assembly so the bridge can report which release
 # the deployed add-in came from; the pi extension compares it against its own package

package/scripts/check-sdk.ps1

@@ -0,0 +1,66 @@
+#Requires -Version 5.1
+
+function Test-PiRevitSdk {
+    param(
+        [string[]]$TargetFrameworks,
+        [string]$Context = 'Revit bridge build',
+        [switch]$OfferDownload
+    )
+
+    # Check the SDK selected in the build's working directory, not just installed
+    # SDKs: global.json or PATH can still select an older SDK.
+    $requiredMajor = 0
+    foreach ($framework in $TargetFrameworks) {
+        if ($framework -notmatch '^net(\d+)\.') {
+            throw "Cannot determine the required .NET SDK for '$framework'."
+        }
+        $requiredMajor = [Math]::Max($requiredMajor, [int]$matches[1])
+    }
+    if ($requiredMajor -eq 0) { throw 'No target frameworks were supplied for the SDK check.' }
+
+    $selectedVersion = $null
+    if (Get-Command dotnet -ErrorAction SilentlyContinue) {
+        try {
+            $versionOutput = @(& dotnet --version 2>&1)
+            if ($LASTEXITCODE -eq 0) {
+                foreach ($line in $versionOutput) {
+                    if ("$line".Trim() -match '^(\d+)\.\d+\.\d+(?:-[\w.-]+)?$') {
+                        $selectedVersion = "$line".Trim()
+                        if ([int]$matches[1] -ge $requiredMajor) { return $true }
+                    }
+                }
+            }
+        }
+        catch {
+            # A runtime-only installation or an unresolved global.json can make
+            # --version fail. Present the same actionable prerequisite message.
+        }
+    }
+
+    $downloadUrl = "https://dotnet.microsoft.com/en-us/download/dotnet/$requiredMajor.0"
+    Write-Host "`npi-revit prerequisite check: $Context" -ForegroundColor Yellow
+    Write-Host "Building this add-in requires the .NET $requiredMajor SDK or a newer compatible SDK."
+    if ($selectedVersion) {
+        Write-Host "Your build tools currently use .NET SDK $selectedVersion."
+    }
+    else {
+        Write-Host 'No usable .NET SDK could be selected in this terminal.'
+    }
+    Write-Host 'Revit can run normally with its runtime; compiling the pi-revit add-in also needs the SDK.'
+    Write-Host "Install the .NET $requiredMajor SDK for Windows x64 (choose SDK, not Runtime)."
+    Write-Host 'You can keep your existing .NET versions installed.'
+    Write-Host "Download: $downloadUrl"
+    Write-Host 'Then reopen PowerShell and rerun your install or build command.'
+    Write-Host 'If the SDK is already installed, check dotnet --list-sdks, PATH, and any global.json selecting an older SDK.'
+
+    if ($OfferDownload -and [Environment]::UserInteractive -and -not [Console]::IsInputRedirected) {
+        try {
+            $answer = Read-Host 'Open the SDK download page now? [y/N]'
+            if ($answer -match '^(?i:y|yes)$') { Start-Process $downloadUrl | Out-Null }
+        }
+        catch {
+            Write-Host "Open the download link above in your browser."
+        }
+    }
+    return $false
+}

package/scripts/deploy.ps1

@@ -16,13 +16,16 @@ Usage:
   scripts\deploy.ps1                                              # auto-detect + deploy to all installed
   scripts\deploy.ps1 -RevitVersion 2026
   scripts\deploy.ps1 -RevitVersion 2027 -RevitApiPath "D:\Autodesk\Revit 2027"
-  scripts\deploy.ps1 -SkipBuild
+  scripts\deploy.ps1 -SkipBuild
+  scripts\deploy.ps1 -CheckOnly                                 # check prerequisites without installing
 #>
 param(
     [string]$RevitVersion = '',
     [string]$Configuration = 'Release',
     [string]$RevitApiPath = '',
-    [switch]$SkipBuild
+    [switch]$SkipBuild,
+    [switch]$CheckOnly,
+    [switch]$OfferDownload
 )
 
 $ErrorActionPreference = 'Stop'
@@ -68,11 +71,20 @@ else {
     Write-Host ("Detected Revit: " + (($targets | ForEach-Object { $_.Version }) -join ', ')) -ForegroundColor Cyan
 }
 
-# Build once per distinct target framework, compiling against a matching RevitAPI.dll.
+# Validate every target before starting any build or deployment.
+if ($CheckOnly -or -not $SkipBuild) {
+    . (Join-Path $PSScriptRoot 'check-sdk.ps1')
+    $context = 'Detected Revit: ' + (($targets | ForEach-Object { $_.Version }) -join ', ')
+    if (-not (Test-PiRevitSdk -TargetFrameworks @($targets.Tfm) -Context $context -OfferDownload:$OfferDownload)) { exit 1 }
+}
+if ($CheckOnly) { exit 0 }
+
+# Build once per distinct target framework, compiling against a matching RevitAPI.dll.
 if (-not $SkipBuild) {
     foreach ($group in ($targets | Group-Object Tfm)) {
         $apiPath = ($group.Group | Select-Object -First 1).Path
-        & (Join-Path $PSScriptRoot 'build.ps1') -Configuration $Configuration -RevitApiPath $apiPath -TargetFramework $group.Name
+        & (Join-Path $PSScriptRoot 'build.ps1') -Configuration $Configuration -RevitApiPath $apiPath -TargetFramework $group.Name
+        if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
     }
 }
 

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) 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.
+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 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.
+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
 
@@ -23,41 +23,41 @@ Work with the live Revit model. The bridge targets Revit 2025, 2026, and 2027; t
 | Everything else (create, delete, move, views, sheets, tagging, ...) | `execute_csharp` |
 | 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) |
+| 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` 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.
+- 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` 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.
+- `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` 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.
+- `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 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.
+- 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. The dialog guard attempts dismissive responses and reports `suppressedDialogs`; it cannot guarantee handling every modal dialog.
+- 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.
+## 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.
+- **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

@@ -406,9 +406,9 @@ namespace RevitBridge
                 object? output = tool.RequiresDocument
                     ? 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));
+                        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
                     // run right here on the server task instead of the CommandQueue.
@@ -436,9 +436,9 @@ namespace RevitBridge
                 ? Math.Clamp(value, 1_000, 600_000)
                 : 30_000;
 
-        /// <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>
+        /// <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;
@@ -449,11 +449,11 @@ namespace RevitBridge
                 compact = toolOutput.CompactText;
             }
 
-            string text = JsonSerializer.Serialize(payload);
+            string text = JsonSerializer.Serialize(payload);
             bool truncated = text.Length > MaxContentChars;
             if (truncated)
             {
-                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.";
+                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, summary = compact, contentTruncated = truncated },
+                details = new { payload, summary = compact, contentTruncated = truncated },
                 isError = false,
             };
         }