pi-revit 0.2.18 → 0.3.0

package/CHANGELOG.md

@@ -5,9 +5,42 @@ Format follows [Keep a Changelog](https://keepachangelog.com/); version headers
 `## [x.y.z] - YYYY-MM-DD` so tooling (and Pi's changelog parser format) can read them.
 
 Every published version gets an entry with **Added** / **Changed** / **Fixed** sections
-describing what the user will notice — not internal refactors.
-
-## [0.2.18] - 2026-08-21
+describing what the user will notice — not internal refactors.
+
+## [0.3.0] - 2026-09-09
+
+### Added
+
+- `read_revit_result` retrieves complete large tool results in bounded fragments.
+  Result IDs belong to the current Pi extension session; saved files remain
+  readable by path while available.
+
+### Changed
+
+- **Breaking:** writes and UI mutations require `expected_document_id` from
+  `get_model_overview`'s `project.documentId`. Refresh it after close/reopen or
+  bridge restart. A legacy title alone is insufficient; supplied IDs on reads
+  are also checked.
+- Default export folders include a model-identity hash, separating same-title
+  models. Existing folders remain untouched; explicit output directories work
+  as before.
+
+### Fixed
+
+- Requested values and all returned rows reach Pi instead of only UI/debug
+  details. Large-result retrieval preserves each tool's pagination and limits.
+- Scoped display-name filters resolve each element's parameter, including
+  matches beyond the first 50 elements; explicit built-in/GUID filters stay optimized.
+- Type-only parameter requests work independently of instance-parameter inclusion.
+- Transaction results distinguish confirmed commit/rollback from incomplete
+  cleanup. Failure handling follows the transaction lifecycle; UI and export
+  errors disclose effects or files already produced.
+
+Update both the Pi package and Revit add-in with Revit closed, then restart Revit
+and start a fresh Pi session. Live verification covered bounded workflows on
+Revit 2025.4.3; Revit 2026/2027 were not tested for this release.
+
+## [0.2.18] - 2026-08-21
 
 ### Fixed
 - When pi starts before Revit and the background rediscovery timer (rather than a `ping`

package/README.md

@@ -1,17 +1,17 @@
 # pi-revit
 
 Native Revit tools for [Pi](https://pi.dev) — ask about, query, script, and modify the open
-Autodesk Revit model from your terminal.
-
+Autodesk Revit model from your terminal.
+
 ```text
 You: how many levels in the model?
 Pi:  calls get_model_overview → "There are 14 levels in the Revit model."
 
 You: select all structural columns
-Pi:  get_elements → manage_selection → "Selected 222 structural columns."
+Pi:  get_model_overview → get_elements → manage_selection → "Selected 222 structural columns."
 
 You: rename level 'L1' to 'Ground Floor'
-Pi:  calls set_parameters → "Done — Level 'L1' is now 'Ground Floor'."
+Pi:  get_model_overview → set_parameters → "Done — Level 'L1' is now 'Ground Floor'."
 ```
 
 ## How it works
@@ -26,7 +26,7 @@ localhost HTTP bridge          ← per-start token; connection info in %APPDATA%
 headless Revit add-in          ← no ribbon, no panels; just a bridge
    │  ExternalEvent queue (Revit API thread)
    ▼
-Revit API                      ← reads run directly; writes run in one named transaction
+Revit API                      ← tool-owned model transactions; separate UI/file effects
 ```
 
 The extension discovers its tools from the bridge at startup (retrying in the background until
@@ -39,19 +39,51 @@ selected LLM provider, like any Pi session.
 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.
+- Tool metadata describes its classification; UI actions such as selection and view
+  activation can change state even when `write` is false. Confirmation policy belongs
+  to the client. Exact document targeting is enforced separately as described below.
+- Parameter writes, C# scripts, temporary isolation, and IFC export own named Revit
+  transactions. Failure handling is attached after transaction start, and results
+  check transaction outcomes before claiming commit or rollback. `set_parameters`
+  can commit a partially successful batch; inspect every failed update and
+  `commitWarnings`. An unconfirmed rollback is reported as such.
 - `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.
+- `execute_csharp` has a dialog guard that attempts dismissive responses to dialogs
+  raised while the script runs. It does not establish that every Revit dialog or
+  failure mode can be handled automatically.
+- A model transaction does not undo filesystem output or earlier selection/zoom
+  changes. A failed export can leave incomplete files; its error reports the output
+  location and observed changed files. An isolation failure reports any earlier
+  selection action that already completed.
+
+### Target the exact open document
+
+Call `get_model_overview` for the intended model and copy `project.documentId`
+unchanged into `expected_document_id` on subsequent operations:
+
+```json
+{
+  "expected_document_id": "<project.documentId from the current overview>",
+  "updates": [{ "element_id": 12345, "parameter": "ALL_MODEL_INSTANCE_COMMENTS", "value": "Reviewed" }]
+}
+```
+
+Replace the placeholders with the current document ID and an actual element ID.
+The exact ID is required for `set_parameters`, `execute_csharp`,
+`export_documents`, and `open_view`. It is also required for selection/zoom
+changes and any `manage_selection` call with `isolate_in_view: true`, including
+action `get`. Pure reads may omit it; a supplied ID is always checked.
+
+The identity represents one currently open native document in one loaded bridge
+session. It is not a persistent project ID, path, export-folder key, or credential.
+Closing/reopening the document or restarting the bridge invalidates prior IDs.
+Read the intended document's overview again after those transitions. The guard
+checks the actual target on Revit's API thread immediately before execution.
+
+Legacy `expected_document` titles remain an optional additional sanity check.
+A title alone no longer satisfies the required guard, even when it matches.
+Clients must refresh discovery and supply the new field after upgrading to 0.3.0.
 
 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.
@@ -114,10 +146,19 @@ git clone https://github.com/Triavision-ai/pi-revit.git
 cd pi-revit
 powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1
 pi install ./
-powershell -ExecutionPolicy Bypass -File scripts\setup-workspace.ps1
-```
-
-## Use it
+powershell -ExecutionPolicy Bypass -File scripts\setup-workspace.ps1
+```
+
+### Upgrading to 0.3.0
+
+**Breaking change:** writes and UI mutations now require `expected_document_id`.
+Close Revit, update the Pi package and redeploy the add-in using the installation
+steps above, then restart Revit and start a fresh Pi session. Both components must
+be updated. Call `get_model_overview` and copy `project.documentId` into subsequent
+mutating calls; a legacy `expected_document` title alone is insufficient. Refresh
+the ID after closing/reopening a document or restarting Revit.
+
+## Use it
 
 Open **any terminal** — PowerShell, CMD, or Windows Terminal — and type:
 
@@ -141,12 +182,18 @@ automatically and all Revit session history lives in one predictable place (`pi-
 continues the last session). The Revit tools themselves are installed globally in Pi, and the
 extension discovers them live from the bridge inside Revit each time a session starts.
 
-**Per model, automatically:** files sort themselves. Exports land in
-`Documents\pi-revit\Models\<model title>\exports` — the add-in derives the folder from the
-document being exported, so even a session that touches many models files every output under
-the right one, with no naming decision from you or the AI. Each model folder carries a
-`model.txt` recording the model's GUID and file path, so two models that share a title stay
-distinguishable.
+**Per model, automatically:** files sort themselves. Exports land in
+`Documents\pi-revit\Models\<model title>--<identity hash>\exports`. The suffix derives
+from the normalized saved-file path, cloud region/project/model identity, or Revit
+Server path. Distinct saved paths therefore use different destinations even when
+their titles or inherited project IDs match. Save As to another path selects a new
+destination. Unsaved models or unavailable persistent identities use a token stable
+only for that open document; their destination may change after reopening.
+
+`model.txt` records the identity used. Existing title-only directories remain
+untouched; upgrading does not migrate or merge old exports. An explicit
+`output_dir` still overrides the default. File attribution uses a directory
+snapshot, so avoid unrelated concurrent writers in a shared output directory.
 
 Plain `pi` from any folder also works; `pi-revit` just adds the right working folder on top.
 
@@ -165,19 +212,58 @@ Plain `pi` from any folder also works; `pi-revit` just adds the right working fo
 | `search_api_docs` | Search the offline Revit API docs (works with no document open) |
 | `execute_csharp` | Run a C# script in one auto-managed transaction — the escape hatch |
 | `capture_view` | PNG snapshot of a view to a temp file (read the returned path to see it) |
-| `export_documents` | PDF/DWG/PNG/IFC export of sheets and views — auto-sorted into `Models\<model>\exports` |
-| `get_model_health` | Warnings grouped + worksets, phases, design options audit |
+| `export_documents` | PDF/DWG/PNG/IFC export of sheets and views — sorted into `Models\<title>--<identity hash>\exports` |
+| `get_model_health` | Warnings grouped + worksets, phases, design options audit |
+| `read_revit_result` | Read bounded fragments of a saved large tool result; extension-only, no Revit call |
+
+### Read complete results
+
+Requested rows and parameter values are included in model-visible tool content.
+Results up to 12,000 characters are complete inline. For a larger result, the Pi
+extension saves the complete tool payload as UTF-8 JSON and returns `result_id`,
+`file_path`, `total_chars`, `complete_inline: false`, and retrieval instructions.
+
+Call `read_revit_result` with the returned ID and `offset: 0`, then follow each
+`next_offset` until `has_more` is false. A requested fragment is at most 8,000
+UTF-16 code units; it may be smaller so the escaped response stays within the
+message limit. Concatenate each page's `text` in order. Individual fragments are
+not standalone JSON objects from the original result. Use the returned offsets,
+not byte counts or a guessed increment.
+
+Result IDs are registered in memory by the current extension instance. After an
+extension reload or new Pi process, an old ID may no longer resolve; use the
+original absolute `file_path` with Pi's normal `read` tool while that file remains
+available. Saved results live in a unique OS temporary directory, can contain
+model data, and are subject to eventual OS/user cleanup. If saving fails after
+Revit completed an operation, inspect actual model state before retrying a write.
+
+Complete payload retrieval does not expand a tool's own query page or declared
+limits. Continue `get_elements`/`get_element_types` pagination separately, and
+check warning-group or projection truncation indicators. A bridge-only client
+must consume `details.payload` for oversized results; `read_revit_result` belongs
+to the Pi extension.
+
+Display-name parameter filters now resolve on every element, including inside a
+category/class scope. Explicit built-in IDs and shared GUIDs can retain collector
+optimization. In `get_element_details`, `include.parameters` and
+`include.type_parameters` are independent; disabling instance parameters still
+allows a type-only result.
 
 ## Limitations — read before using on real projects
 
 - **Write tools are unrestricted by design.** `set_parameters` and `execute_csharp` modify the
   open model directly — there is no confirmation prompt and no sandbox. Writes run in named
-  transactions, undoable with Ctrl+Z in Revit (`execute_csharp` rolls back entirely on any
-  error; `set_parameters` commits partial successes and reports each failure), but the model is
-  yours to protect: test on copies, keep backups, read the result's `failed` lists.
+  transactions (`execute_csharp` attempts rollback after script failure;
+  `set_parameters` commits partial successes and reports each failure). Read the
+  actual transaction outcome and failed lists. Script result-projection failure
+  can leave a successful edit committed with a `returnValueError`; filesystem and
+  UI effects are separate from model rollback.
 - The add-in multi-targets .NET 8 (Revit 2025/2026) and .NET 10 (Revit 2027); `deploy.ps1`
   auto-detects the Revit versions you have installed and builds only the matching framework(s),
-  so you only need the SDK for the Revit you run. Verified on Revit 2025 and 2027.
+  so you only need the SDK for the Revit you run. The 0.3.0 changes were tested live
+  on Revit 2025.4.3 (build 25.4.30.30, German UI). Revit 2026/2027 and large-model
+  performance were not tested for this release. Export API/file checks do not
+  establish full DWG drawing or IFC schema/geometry validation.
 - **One Revit instance at a time** is discoverable (last started wins). When that instance
   closes or crashes, another one that is still running takes the slot over within 30s.
 - A tool call that outlives its timeout is abandoned client-side but may still complete inside

package/bin/pi-revit.js

@@ -1,13 +1,15 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 const { spawnSync } = require("node:child_process");
 const fs = require("node:fs");
 const path = require("node:path");
 
-const root = path.resolve(__dirname, "..");
-const scriptsDir = path.join(root, "scripts");
+const root = path.resolve(__dirname, "..");
+const scriptsDir = path.join(root, "scripts");
+const packageVersion = require(path.join(root, "package.json")).version;
+const packageSpec = `npm:pi-revit@${packageVersion}`;
 
 function usage() {
-	console.log(`pi-revit installer\n\nUsage:\n  npx.cmd -y pi-revit\n\nWhat it does on Windows:\n  1. Runs: pi install npm:pi-revit\n  2. Builds and deploys the Revit bridge add-in\n  3. Creates the Documents\\pi-revit workspace and global pi-revit command\n\nClose Revit before running. Revit 2025, 2026, or 2027 and the matching .NET SDK are required.`);
+	console.log(`pi-revit installer\n\nUsage:\n  npx.cmd -y pi-revit\n\nWhat it does on Windows:\n  1. Runs: pi install ${packageSpec}\n  2. Builds and deploys the matching Revit bridge add-in\n  3. Creates the Documents\\pi-revit workspace and global pi-revit command\n\nClose Revit before running. Revit 2025, 2026, or 2027 and the matching .NET SDK are required.`);
 }
 
 function fail(message) {
@@ -84,7 +86,7 @@ if (revitIsRunning()) {
 console.log("pi-revit full installer");
 console.log("This installs the Pi package, deploys the Revit add-in, and creates the workspace/global command.");
 
-runCmd("Install the Pi package from npm", "pi install npm:pi-revit");
+runCmd("Install the matching Pi package from npm", `pi install ${packageSpec}`);
 runPowerShellScript("deploy.ps1");
 runPowerShellScript("setup-workspace.ps1");
 

package/extensions/pi-revit/index.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type, type TSchema } from "typebox";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+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";
@@ -47,7 +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_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. */
@@ -153,11 +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 at ${MAX_MODEL_CONTENT_CHARS} chars; full payload is in details]`;
-	return text.slice(0, Math.max(0, MAX_MODEL_CONTENT_CHARS - suffix.length)) + suffix;
-}
+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(
@@ -171,14 +255,7 @@ async function runBridgeTool(name: string, args: unknown, signal: AbortSignal |
 		timeoutMs,
 	)) as BridgeToolResponse;
 
-	const content =
-		Array.isArray(payload.content) && payload.content.length > 0
-			? payload.content.map((block) =>
-					typeof block.text === "string" ? { ...block, text: capText(block.text) } : block,
-				)
-			: [{ type: "text", text: capText(JSON.stringify(payload.details ?? {})) }];
-
-	return { content, details: payload.details };
+	return { content: await modelContent(name, payload), details: payload.details };
 }
 
 function registerBridgeTool(pi: ExtensionAPI, descriptor: BridgeToolDescriptor) {
@@ -307,7 +384,8 @@ function registerPing(pi: ExtensionAPI, onBridgeAlive?: () => Promise<"ready" |
 
 const REDISCOVERY_INTERVAL_MS = 15_000;
 
-export default async function revitConnector(pi: ExtensionAPI) {
+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
@@ -328,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") 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.2.18",
+  "version": "0.3.0",
   "description": "Native Pi connector for Autodesk Revit. Run npx.cmd -y pi-revit for the full Windows install.",
   "author": "Ahmad Altahlawi",
   "license": "MIT",
@@ -27,7 +27,8 @@
     "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:search": "dotnet run --project tests/search-engine",
+    "test:installer": "node tests/installer/installer.test.cjs"
   },
   "files": [
     "bin/",

package/skills/pi-revit/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: pi-revit
-description: Work with the open Autodesk Revit model through the Revit bridge tools (ping, get_model_overview, get_elements, get_element_details, get_element_types, manage_selection, open_view, set_parameters, search_api_docs, execute_csharp, capture_view, export_documents, get_model_health). Use when the user asks about the Revit project, its elements, parameters, selection, or wants to change, script, capture, or export the model.
+description: Work with the open Autodesk Revit model through the Revit bridge tools (ping, get_model_overview, get_elements, get_element_details, get_element_types, manage_selection, open_view, set_parameters, search_api_docs, execute_csharp, capture_view, export_documents, get_model_health) and retrieve saved results with read_revit_result. Use when the user asks about the Revit project, its elements, parameters, selection, or wants to change, script, capture, or export the model.
 ---
 
 # Revit
 
-Work with the live Revit model. The tools call a headless bridge add-in inside Revit (2025, 2026, or 2027); Revit must be running with a project open (only `ping` and `search_api_docs` work without a document).
+Work with the live Revit model. The bridge targets Revit 2025, 2026, and 2027; the 0.3.0 changes were tested live on Revit 2025. Bridge document tools require Revit running with a project open; `ping` and `search_api_docs` work without a document. `read_revit_result` reads an already saved result locally without contacting Revit.
 
 ## Tool selection
 
@@ -23,31 +23,41 @@ Work with the live Revit model. The tools call a headless bridge add-in inside R
 | 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) |
+| Warnings / model quality audit | `get_model_health` (advanced) |
+| Continue a saved large tool result | `read_revit_result` (local, no Revit call) |
 
 Workflow guidance:
 
-- Call `get_model_overview` first when starting work on an unfamiliar model — one call returns project metadata, units, levels, grids, and category counts.
+- Call `get_model_overview` for the intended open model before changing it. Copy `project.documentId` unchanged into `expected_document_id` for `set_parameters`, `execute_csharp`, `export_documents`, `open_view`, and selection/zoom changes. `manage_selection` also requires it whenever `isolate_in_view: true`, even with action `get`. Pure reads may omit it; a supplied ID is always checked. A matching legacy `expected_document` title alone is insufficient.
+- The ID belongs to one open document in one bridge session. Refresh it after closing/reopening the model or restarting Revit. If the guard rejects a call, activate the intended model and obtain its overview again; do not blindly substitute the currently active model's ID.
 - `get_elements` is the listing/counting primitive (`count_only: true` for bare counts). It returns identity fields only (id, name, category, typeName, levelId); read parameter values with `get_element_details`. Prefer a `category` or `of_class` scope when filtering by a parameter's display name.
 - The selection pipeline is `get_elements` -> ids -> `manage_selection` (action `set`); there is no inline filter on selection.
-- `set_parameters` is the home for bulk parameter writes AND renames (the `Name` parameter covers levels, views, sheets, types). One transaction per batch; per-element failures are reported. Pass `expected_document` (the model title) when several models are open or the session is long — it makes the write fail cleanly instead of landing in a different active document.
+- `set_parameters` handles bulk parameter writes and renames (the `Name` parameter covers levels, views, sheets, types). It can commit a partially successful batch: inspect every failed update, `commitWarnings`, and the reported transaction outcome before describing what changed.
 - Parameter display names are LOCALIZED: in a non-English Revit UI, `Mark`, `Comments`, and every other display name appear under their translated names. When a display-name lookup or `parameter_names` filter finds nothing, or the document may be non-English, use the language-independent `BuiltInParameter` enum name instead (e.g. `ALL_MODEL_MARK` for Mark, `ALL_MODEL_INSTANCE_COMMENTS` for Comments) — `set_parameters`, `get_element_details.parameter_names`, and `get_elements` filter rules all accept them, and `get_element_details` reports each parameter's `builtInParameter` name for discovery.
 - Before writing `execute_csharp` code, verify unfamiliar classes/members with `search_api_docs` (works with no document open; first query builds the index and takes a few seconds). The top match carries its remarks, parameter docs, and returns inline, and every public API enum value is searchable — trust the result over guessing or web search; narrow the query to promote a different match into the top slot.
-- `export_documents` files its output under `Documents\pi-revit\Models\<model title>\exports` automatically when `output_dir` is omitted — keyed to the exported document, so it lands right even across many models. Pass `output_dir` only when the user names a different target.
+- `export_documents` defaults to `Documents\pi-revit\Models\<model title>--<identity hash>\exports`. Use its returned `outputDir` and file paths as authoritative; do not construct a destination from the title or opaque `project.documentId`. Saved paths and cloud/server identities determine the folder; unsaved/unavailable identities use a session fallback. Save As can select a new folder. Pass `output_dir` when the user requests a different destination. Existing title-only folders remain untouched.
+- Large tool payloads return a `result_id`, `file_path`, and continuation instructions. Call `read_revit_result` with that ID and `offset: 0`, then follow `next_offset` until `has_more` is false. Concatenate `text` fragments in order; each fragment is not a standalone JSON result. Offsets count UTF-16 code units. IDs last for the current extension instance; after reload, use the returned absolute file path with `read` while the file exists. Retrieval does not replace the original query's pagination or remove its limits.
 
 ## execute_csharp playbook
 
 - Globals: `doc` (Document), `uidoc` (UIDocument), `uiapp` (UIApplication), and `Dump(value)` to record intermediates into the result's `dumps[]`.
-- The transaction is automatic: the whole script runs inside ONE backend-owned transaction — committed on success, rolled back on any exception. Do not open your own `Transaction` (sub-transactions are fine).
+- The script runs inside one backend-owned transaction. Do not start another transaction on `doc` (sub-transactions are allowed). The tool checks commit status and attempts rollback on script failure; read its actual outcome instead of assuming rollback succeeded. Result projection can fail after a successful commit and report `returnValueError`. Filesystem and UI effects are separate from model rollback.
 - Scripts must be fully synchronous: `await`/`async` is rejected at compile time; never block on `Task.Result`/`.Wait()`.
 - Return primitives, strings, or anonymous objects/lists; raw Revit API objects are projected to compact shapes (Element -> `{id,name,category,typeName,levelId}`, ElementId -> number, XYZ -> `{x,y,z}`).
 - Lengths are internal units (decimal feet) — convert with `UnitUtils.ConvertToInternalUnits`/`ConvertFromInternalUnits`.
-- Common pitfalls: call `FamilySymbol.Activate()` before `NewFamilyInstance`; use collector-level filtering (`OfCategory`/`OfClass`/`WhereElementIsNotElementType`) and bounded loops — the budget is 120s and Revit cannot be interrupted mid-script; modal dialogs are auto-dismissed and reported in `suppressedDialogs`.
+- Common pitfalls: call `FamilySymbol.Activate()` before `NewFamilyInstance`; use collector-level filtering (`OfCategory`/`OfClass`/`WhereElementIsNotElementType`) and bounded loops. The budget is 120s and Revit cannot be interrupted mid-script. The dialog guard attempts dismissive responses and reports `suppressedDialogs`; it cannot guarantee handling every modal dialog.
 - `capture_view` returns a `filePath` to a temp PNG, never image data — open it with the read tool to actually see it.
 
-## Failure modes
-
+## 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.
+- **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,8 +406,9 @@ namespace RevitBridge
                 object? output = tool.RequiresDocument
                     ? await _queue.RunAsync(uiApp =>
                     {
-                        var document = uiApp.ActiveUIDocument?.Document ?? throw new NoActiveDocumentException();
-                        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.
@@ -435,9 +436,9 @@ namespace RevitBridge
                 ? Math.Clamp(value, 1_000, 600_000)
                 : 30_000;
 
-        /// <summary>Compact text for model context; full payload in details. Tools may
-        /// return a ToolOutput (CompactText -> content, Payload -> details.payload) or
-        /// any plain object (serialized to both).</summary>
+        /// <summary>Complete bounded JSON for model context; the full payload always
+        /// remains in details for the extension's saved-result retrieval. ToolOutput
+        /// compact text is a display summary, not a substitute for requested data.</summary>
         private static object BuildToolResponse(string toolName, object? output)
         {
             object? payload = output;
@@ -448,12 +449,11 @@ namespace RevitBridge
                 compact = toolOutput.CompactText;
             }
 
-            string text = compact ?? JsonSerializer.Serialize(payload ?? new { });
+            string text = JsonSerializer.Serialize(payload);
             bool truncated = text.Length > MaxContentChars;
             if (truncated)
             {
-                string suffix = $"... [truncated at {MaxContentChars} chars; full payload is in details]";
-                text = text[..Math.Max(0, MaxContentChars - suffix.Length)] + suffix;
+                text = $"Result exceeds the {MaxContentChars}-character inline limit. The complete value is in details.payload; the Pi extension saves it locally and provides read_revit_result for bounded retrieval.";
             }
 
             return new
@@ -461,7 +461,7 @@ namespace RevitBridge
                 success = true,
                 toolName,
                 content = new[] { new { type = "text", text } },
-                details = new { payload, contentTruncated = truncated },
+                details = new { payload, summary = compact, contentTruncated = truncated },
                 isError = false,
             };
         }