pi-revit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmad Altahlawi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# pi-revit
+
+Native Revit tools for [Pi](https://pi.dev) — ask about, query, script, and modify the open
+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."
+
+You: rename level 'L1' to 'Ground Floor'
+Pi:  calls set_parameters → "Done — Level 'L1' is now 'Ground Floor'."
+```
+
+## How it works
+
+```text
+Pi terminal session
+   │  native tools (registered by the pi-revit extension)
+   ▼
+localhost HTTP bridge          ← per-start token; connection info in %APPDATA%\RevitBridge\
+   │
+   ▼
+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
+```
+
+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.
+
+## Requirements
+
+- Windows 10/11
+- Autodesk Revit 2025, 2026, or 2027
+- .NET SDK matching your Revit: [.NET 8](https://dotnet.microsoft.com/download/dotnet/8.0) for Revit 2025/2026, [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) for Revit 2027
+- [Node.js 20.3+](https://nodejs.org/)
+- [Pi coding agent](https://pi.dev): `npm install -g --ignore-scripts @earendil-works/pi-coding-agent`
+
+## Install
+
+Close Revit, then in PowerShell:
+
+```powershell
+git clone https://github.com/Triavision-ai/pi-revit.git
+cd pi-revit
+
+# 1. Build + deploy the Revit add-in (RevitBridge.dll + the Roslyn DLLs for execute_csharp)
+#    Auto-detects every supported Revit (2025+) installed under Program Files and deploys to each.
+#    Only need the .NET SDK for the versions you have (e.g. just .NET 8 if you only run 2025/2026).
+#    For a non-default install location, pass -RevitVersion and -RevitApiPath, e.g.:
+#      ... scripts\deploy.ps1 -RevitVersion 2027 -RevitApiPath "D:\Autodesk\Revit 2027"
+powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1
+
+# 2. Install the Pi package
+pi install ./
+
+# 3. Workspace + global pi-revit command
+powershell -ExecutionPolicy Bypass -File scripts\setup-workspace.ps1
+```
+
+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.
+
+## Use it
+
+Open **any terminal** — PowerShell, CMD, or Windows Terminal — and type:
+
+```powershell
+pi-revit
+```
+
+That's all. Pi starts with the Revit tools ready:
+
+```text
+> give me a model overview
+> how many doors per level?
+> select all structural columns
+```
+
+**How this works:** install step 3 placed a small `pi-revit` command in the same folder as the
+`pi` command itself. That folder is on your system PATH — which is exactly why *every* terminal
+finds `pi-revit`, with no extra configuration. When you run it, it switches to your workspace at
+`Documents\pi-revit` and starts Pi there, so your conventions file (`AGENTS.md`) loads
+automatically and all Revit session history lives in one predictable place. 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 project:** create one subfolder per Revit project under `Documents\pi-revit\Projects\`:
+
+```powershell
+pi-revit tower-b        # Pi scoped to that project — its notes and its session history
+pi-revit tower-b -c     # continue that project's last session
+```
+
+Plain `pi` from any folder also works; `pi-revit` just adds the right working folder on top.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `ping` | Is the bridge reachable? Revit version |
+| `get_model_overview` | Project info, units, levels, grids, category counts — call first |
+| `get_elements` | Query/count elements of any category: parameter filters, pagination |
+| `get_element_details` | Parameter values, location, bounding box, materials per element |
+| `get_element_types` | Element types / family symbols, optional placed-instance counts |
+| `manage_selection` | Get/set/clear the selection, zoom, temporary isolate |
+| `set_parameters` | Bulk parameter writes + rename anything (one transaction per batch) |
+| `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 |
+| `get_model_health` | Warnings grouped + worksets, phases, design options audit |
+
+## 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.
+- 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.
+- **One Revit instance at a time** is discoverable (last started wins).
+- A tool call that outlives its timeout is abandoned client-side but may still complete inside
+  Revit — verify model state before re-issuing a write.
+- Long-running scripts cannot be interrupted mid-execution (Revit's API is single-threaded);
+  the `execute_csharp` budget is 120s.
+
+## Uninstall
+
+Close Revit, then in PowerShell from the repo:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\uninstall.ps1
+```
+
+This removes the Revit bridge add-in (every installed Revit version), the global `pi-revit`
+command, the bridge runtime folder (`%APPDATA%\RevitBridge\`), and the Pi package registration.
+Your workspace at `Documents\pi-revit` (notes + session history) is **preserved** — add
+`-RemoveWorkspace` to delete it too, or `-RevitVersion 2026` to target a single Revit version.
+Pi itself is left installed; remove it with `npm uninstall -g @earendil-works/pi-coding-agent` if
+you want.

package/extensions/pi-revit/index.ts

@@ -0,0 +1,239 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type, type TSchema } from "typebox";
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+interface BridgeInfo {
+	baseUrl: string;
+	token: string;
+	pid?: number;
+	revitVersion?: string;
+}
+
+interface ContentBlock {
+	type: string;
+	text: string;
+}
+
+interface BridgeToolResponse {
+	success?: boolean;
+	toolName?: string;
+	content?: ContentBlock[];
+	details?: unknown;
+	isError?: boolean;
+	error?: boolean;
+	message?: string;
+	hasActiveDocument?: boolean;
+}
+
+/** One entry of GET /tools, as served by ToolRegistry.Describe() on the bridge. */
+interface BridgeToolDescriptor {
+	name: string;
+	label?: string;
+	description?: string;
+	category?: string;
+	tier?: string;
+	parameters?: unknown;
+	executionMode?: string;
+	write?: boolean;
+	requiresDocument?: boolean;
+	promptSnippet?: string | null;
+	promptGuidelines?: string[] | null;
+}
+
+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;
+
+/** 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. */
+const TOOL_TIMEOUTS_MS: Record<string, number> = {
+	execute_csharp: LONG_TIMEOUT_MS,
+	capture_view: LONG_TIMEOUT_MS,
+	export_documents: LONG_TIMEOUT_MS,
+};
+
+function toolTimeoutMs(name: string): number {
+	return TOOL_TIMEOUTS_MS[name] ?? DEFAULT_TIMEOUT_MS;
+}
+
+function bridgeInfoPath(): string {
+	const appData = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
+	return path.join(appData, "RevitBridge", "bridge.json");
+}
+
+export async function readBridgeInfo(): Promise<BridgeInfo> {
+	const infoPath = bridgeInfoPath();
+	let raw: string;
+	try {
+		raw = await readFile(infoPath, "utf8");
+	} catch {
+		throw new Error(
+			`Revit bridge is not available. Start Revit with the bridge add-in loaded, then retry. Expected bridge info file: ${infoPath}`,
+		);
+	}
+
+	let info: BridgeInfo;
+	try {
+		info = JSON.parse(raw) as BridgeInfo;
+	} catch {
+		throw new Error(`Revit bridge info file is invalid JSON: ${infoPath}`);
+	}
+	if (!info.baseUrl || !info.token) {
+		throw new Error(`Revit bridge info file is invalid: ${infoPath}`);
+	}
+	return info;
+}
+
+/** Cancelling or timing out only abandons the HTTP request: the bridge has no
+ * cancellation path, so a queued or already-running work item may still execute
+ * in Revit (queued items expire only at the bridge-side timeout_ms deadline). */
+function cancelledError(): Error {
+	return new Error(
+		"Revit bridge call was cancelled client-side; Revit may still run the queued or in-flight tool to completion. Verify model state (e.g. with get_elements/get_element_details) before retrying a write tool.",
+	);
+}
+
+function timeoutError(timeoutMs: number): Error {
+	return new Error(
+		`Revit did not answer within ${Math.ceil(timeoutMs / 1000)}s. Revit may be busy or showing a dialog; the request was abandoned client-side, but an already-started tool still runs to completion in Revit. Verify model state before retrying a write tool.`,
+	);
+}
+
+export async function bridgeRequest(
+	pathname: string,
+	init: { method: "GET" | "POST"; body?: string; query?: Record<string, string> },
+	signal?: AbortSignal,
+	timeoutMs = DEFAULT_TIMEOUT_MS,
+): Promise<unknown> {
+	const info = await readBridgeInfo();
+	const query = new URLSearchParams({ ...(init.query ?? {}), token: info.token });
+	const url = `${info.baseUrl}${pathname}?${query.toString()}`;
+
+	const timeoutSignal = AbortSignal.timeout(timeoutMs);
+	const signals = [timeoutSignal];
+	if (signal) signals.push(signal);
+
+	let response: Response;
+	try {
+		response = await fetch(url, {
+			method: init.method,
+			body: init.body,
+			headers: init.body ? { "content-type": "application/json; charset=utf-8" } : undefined,
+			signal: AbortSignal.any(signals),
+		});
+	} catch (error) {
+		if (signal?.aborted) throw cancelledError();
+		if (timeoutSignal.aborted) throw timeoutError(timeoutMs);
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new Error(
+			`Could not reach the Revit bridge at ${info.baseUrl} (${reason}). Revit may have been closed; start Revit and retry.`,
+		);
+	}
+
+	let payload: unknown;
+	try {
+		payload = await response.json();
+	} catch {
+		// The abort signal also cancels body consumption: a timeout/cancel that
+		// fires after headers arrive must not be misreported as a bad response.
+		if (signal?.aborted) throw cancelledError();
+		if (timeoutSignal.aborted) throw timeoutError(timeoutMs);
+		throw new Error(`Revit bridge returned a non-JSON response (HTTP ${response.status}).`);
+	}
+
+	const body = payload as BridgeToolResponse;
+	if (!response.ok || body.error || body.isError || body.success === false) {
+		throw new Error(body.message ?? body.content?.[0]?.text ?? `Revit bridge request failed (HTTP ${response.status}).`);
+	}
+	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;
+}
+
+async function runBridgeTool(name: string, args: unknown, signal: AbortSignal | undefined, timeoutMs: number) {
+	const payload = (await bridgeRequest(
+		`/tools/${encodeURIComponent(name)}/execute`,
+		{
+			method: "POST",
+			body: JSON.stringify(args ?? {}),
+			query: { timeout_ms: String(timeoutMs) },
+		},
+		signal,
+		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 };
+}
+
+function registerBridgeTool(pi: ExtensionAPI, descriptor: BridgeToolDescriptor) {
+	const timeoutMs = toolTimeoutMs(descriptor.name);
+	pi.registerTool({
+		name: descriptor.name,
+		label: descriptor.label ?? descriptor.name,
+		description: descriptor.description ?? `Revit bridge tool '${descriptor.name}'.`,
+		parameters: Type.Unsafe((descriptor.parameters ?? { type: "object", properties: {} }) as TSchema),
+		promptSnippet: descriptor.promptSnippet ?? undefined,
+		promptGuidelines: descriptor.promptGuidelines ?? undefined,
+		executionMode: descriptor.executionMode === "parallel" ? "parallel" : "sequential",
+		async execute(_toolCallId, params, signal) {
+			return runBridgeTool(descriptor.name, params, signal, timeoutMs);
+		},
+	});
+}
+
+function registerPing(pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "ping",
+		label: "Ping Revit Bridge",
+		description: "Check that the Revit bridge is reachable and report the Revit version.",
+		parameters: Type.Object({}),
+		promptSnippet: "Check Revit bridge availability.",
+		promptGuidelines: ["Use ping when Revit tools fail or bridge availability is unclear."],
+		executionMode: "sequential",
+		async execute(_toolCallId, _params, signal) {
+			const payload = await bridgeRequest("/ping", { method: "GET" }, signal, 10_000);
+			return {
+				content: [{ type: "text", text: JSON.stringify(payload) }],
+				details: payload,
+			};
+		},
+	});
+}
+
+export default async function revitConnector(pi: ExtensionAPI) {
+	// 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);
+
+	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;
+	}
+
+	for (const descriptor of descriptors) {
+		if (!descriptor || typeof descriptor.name !== "string" || !descriptor.name) continue;
+		if (descriptor.name === "ping") continue;
+		registerBridgeTool(pi, descriptor);
+	}
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "pi-revit",
+  "version": "0.1.0",
+  "description": "Native Pi connector for Autodesk Revit through a headless bridge add-in.",
+  "author": "Ahmad Altahlawi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Triavision-ai/pi-revit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Triavision-ai/pi-revit/issues"
+  },
+  "homepage": "https://github.com/Triavision-ai/pi-revit#readme",
+  "keywords": ["pi-package", "pi-extension", "revit", "bim", "autodesk", "revit-api"],
+  "files": ["extensions/", "skills/", "scripts/", "src/", "workspace/", "README.md"],
+  "pi": {
+    "extensions": ["./extensions/pi-revit/index.ts"],
+    "skills": ["./skills"]
+  },
+  "engines": {
+    "node": ">=20.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  }
+}

package/scripts/build.ps1

@@ -0,0 +1,37 @@
+#Requires -Version 5.1
+<#
+Builds the Revit bridge add-in.
+
+The project multi-targets net8.0-windows (Revit 2025/2026) and net10.0-windows (Revit 2027).
+Omit -TargetFramework to build both; pass one to build only it (e.g. when only one Revit is installed).
+
+Usage:
+  scripts\build.ps1
+  scripts\build.ps1 -Configuration Debug
+  scripts\build.ps1 -TargetFramework net10.0-windows -RevitApiPath "C:\Program Files\Autodesk\Revit 2027"
+#>
+param(
+    [string]$Configuration = 'Release',
+    [string]$RevitApiPath = '',
+    [string]$TargetFramework = ''
+)
+
+$ErrorActionPreference = 'Stop'
+$project = Join-Path $PSScriptRoot '..\src\Revit\RevitBridge.csproj'
+
+$buildArgs = @('build', $project, '-c', $Configuration)
+if ($TargetFramework) {
+    # Override TargetFrameworks (plural) rather than TargetFramework: NuGet restore ignores a
+    # single -p:TargetFramework and still restores every framework the project declares, so a
+    # machine without the .NET 10 SDK fails the whole build with NETSDK1045 even when only
+    # net8.0 was asked for. Overriding the list restricts restore + build to this one framework.
+    $buildArgs += "-p:TargetFrameworks=$TargetFramework"
+}
+if ($RevitApiPath) {
+    $buildArgs += "-p:RevitApiPath=$RevitApiPath"
+}
+
+& dotnet @buildArgs
+if ($LASTEXITCODE -ne 0) {
+    throw "dotnet build failed with exit code $LASTEXITCODE."
+}

package/scripts/deploy.ps1

@@ -0,0 +1,99 @@
+#Requires -Version 5.1
+<#
+Builds and deploys the Revit bridge add-in.
+
+By default it auto-detects every supported Revit installed under %ProgramFiles%\Autodesk
+(Revit 2025/2026 -> net8.0-windows, Revit 2027 -> net10.0-windows) and deploys to each one,
+building only the framework(s) those installs need. Pass -RevitVersion to target a single
+version explicitly (with -RevitApiPath when it is not in the default location).
+
+Layout after deploy (per version):
+  %APPDATA%\Autodesk\Revit\Addins\<version>\RevitBridge.addin
+  %APPDATA%\Autodesk\Revit\Addins\<version>\RevitBridge\  (RevitBridge.dll + the full
+    build output: Roslyn/Microsoft.CodeAnalysis dependencies for execute_csharp)
+
+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
+#>
+param(
+    [string]$RevitVersion = '',
+    [string]$Configuration = 'Release',
+    [string]$RevitApiPath = '',
+    [switch]$SkipBuild
+)
+
+$ErrorActionPreference = 'Stop'
+
+# Revit 2025/2026 run on .NET 8; 2027 on .NET 10. Versions below 2025 run on .NET Framework
+# and are not supported by this add-in.
+$MinSupported = 2025
+function Get-TargetFramework([int]$version) {
+    if ($version -ge 2027) { 'net10.0-windows' } else { 'net8.0-windows' }
+}
+
+# Resolve the targets to deploy as objects: { Version; Path; Tfm }.
+$targets = @()
+if ($RevitVersion) {
+    $v = [int]$RevitVersion
+    $path = if ($RevitApiPath) { $RevitApiPath } else { Join-Path $env:ProgramFiles "Autodesk\Revit $v" }
+    if (-not (Test-Path (Join-Path $path 'RevitAPI.dll'))) {
+        throw "RevitAPI.dll not found in '$path'. Pass -RevitApiPath with your Revit $v install folder."
+    }
+    $targets += [pscustomobject]@{ Version = $v; Path = $path; Tfm = (Get-TargetFramework $v) }
+}
+else {
+    # Auto-detect: scan %ProgramFiles%\Autodesk for "Revit <year>" folders that hold a RevitAPI.dll.
+    $autodesk = Join-Path $env:ProgramFiles 'Autodesk'
+    if (Test-Path $autodesk) {
+        Get-ChildItem -LiteralPath $autodesk -Directory -Filter 'Revit 20*' -ErrorAction SilentlyContinue |
+            ForEach-Object {
+                if (($_.Name -match '(\d{4})') -and (Test-Path (Join-Path $_.FullName 'RevitAPI.dll'))) {
+                    $v = [int]$matches[1]
+                    if ($v -ge $MinSupported) {
+                        $targets += [pscustomobject]@{ Version = $v; Path = $_.FullName; Tfm = (Get-TargetFramework $v) }
+                    }
+                    else {
+                        Write-Warning "Skipping Revit $v (only 2025+ is supported by this add-in)."
+                    }
+                }
+            }
+    }
+    if (-not $targets) {
+        throw "No supported Revit (2025+) found under '$autodesk'. Install Revit, or pass -RevitVersion and -RevitApiPath for a non-default location."
+    }
+    $targets = @($targets | Sort-Object Version)
+    Write-Host ("Detected Revit: " + (($targets | ForEach-Object { $_.Version }) -join ', ')) -ForegroundColor Cyan
+}
+
+# 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
+    }
+}
+
+# Deploy each detected version to its own Addins folder.
+foreach ($t in $targets) {
+    $sourceDir = Join-Path $PSScriptRoot "..\src\Revit\bin\$Configuration\$($t.Tfm)"
+    $dll = Join-Path $sourceDir 'RevitBridge.dll'
+    if (-not (Test-Path $dll)) {
+        throw "Build output not found: $dll. Run scripts\build.ps1 first (or omit -SkipBuild)."
+    }
+
+    $addinsDir = Join-Path $env:APPDATA "Autodesk\Revit\Addins\$($t.Version)"
+    $targetDir = Join-Path $addinsDir 'RevitBridge'
+    New-Item -ItemType Directory -Force -Path $targetDir | Out-Null
+
+    # execute_csharp ships Roslyn: copy the ENTIRE build output (RevitBridge.dll,
+    # the Microsoft.CodeAnalysis dependency closure, pdb and deps.json) into the add-in folder.
+    Copy-Item -Path (Join-Path $sourceDir '*') -Destination $targetDir -Recurse -Force
+    Copy-Item (Join-Path $PSScriptRoot '..\src\Revit\RevitBridge.addin') $addinsDir -Force
+
+    Write-Host "Deployed Revit bridge add-in to $addinsDir (Revit $($t.Version), $($t.Tfm))" -ForegroundColor Green
+}
+
+Write-Host 'Restart Revit to load it. Verify with: scripts\revit.ps1 ping'

package/scripts/revit.ps1

@@ -0,0 +1,112 @@
+#Requires -Version 5.1
+<#
+Manual debug client for the Revit bridge. Not used by the Pi extension
+(the extension calls the bridge directly with fetch).
+
+Usage:
+  scripts\revit.ps1 ping
+  scripts\revit.ps1 tools
+  scripts\revit.ps1 describe-tool get_model_overview
+  scripts\revit.ps1 run get_model_overview '{}'
+  scripts\revit.ps1 run get_elements '{"category":"Walls","count_only":true}'
+#>
+param(
+    [Parameter(Position = 0)]
+    [ValidateSet('ping', 'tools', 'describe-tool', 'run')]
+    [string]$Command = 'ping',
+
+    [Parameter(Position = 1)]
+    [string]$ToolName,
+
+    [Parameter(Position = 2)]
+    [string]$JsonArgs = '{}',
+
+    [int]$TimeoutSec = 0
+)
+
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+$OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+$bridgeInfoPath = Join-Path $env:APPDATA 'RevitBridge\bridge.json'
+
+function Write-JsonLine($value) {
+    [Console]::Out.WriteLine(($value | ConvertTo-Json -Compress -Depth 20))
+}
+
+function Write-JsonError($message) {
+    Write-JsonLine @{ error = $true; message = $message }
+    exit 1
+}
+
+if ($TimeoutSec -le 0) {
+    $envTimeout = 0
+    if ([int]::TryParse([string]$env:REVIT_BRIDGE_TIMEOUT_SEC, [ref]$envTimeout) -and $envTimeout -gt 0) {
+        $TimeoutSec = $envTimeout
+    } else {
+        $TimeoutSec = 30
+    }
+}
+
+if (-not (Test-Path $bridgeInfoPath)) {
+    Write-JsonError "Revit bridge info not found. Start Revit with the bridge add-in loaded. Expected: $bridgeInfoPath"
+}
+
+try {
+    $info = Get-Content $bridgeInfoPath -Raw | ConvertFrom-Json
+    if (-not $info.baseUrl -or -not $info.token) {
+        Write-JsonError "Revit bridge info is invalid: $bridgeInfoPath"
+    }
+
+    switch ($Command) {
+        'ping' {
+            $response = Invoke-RestMethod -Method Get -Uri "$($info.baseUrl)/ping`?token=$($info.token)" -TimeoutSec $TimeoutSec
+            Write-JsonLine $response
+        }
+        'tools' {
+            $response = Invoke-RestMethod -Method Get -Uri "$($info.baseUrl)/tools`?token=$($info.token)" -TimeoutSec $TimeoutSec
+            Write-JsonLine $response
+        }
+        'describe-tool' {
+            if ([string]::IsNullOrWhiteSpace($ToolName)) {
+                Write-JsonError 'describe-tool requires a tool name. Example: revit.ps1 describe-tool get_model_overview'
+            }
+            $encoded = [System.Uri]::EscapeDataString($ToolName)
+            $response = Invoke-RestMethod -Method Get -Uri "$($info.baseUrl)/tools/$encoded`?token=$($info.token)" -TimeoutSec $TimeoutSec
+            Write-JsonLine $response
+        }
+        'run' {
+            if ([string]::IsNullOrWhiteSpace($ToolName)) {
+                Write-JsonError "run requires a tool name. Example: revit.ps1 run get_model_overview '{}'"
+            }
+            if ([string]::IsNullOrWhiteSpace($JsonArgs)) { $JsonArgs = '{}' }
+            # Validate locally so callers get a clear error before the bridge call.
+            $null = $JsonArgs | ConvertFrom-Json
+            $encoded = [System.Uri]::EscapeDataString($ToolName)
+            $uri = "$($info.baseUrl)/tools/$encoded/execute`?token=$($info.token)"
+            # Send bytes: PowerShell 5.1 would otherwise encode a string body as ISO-8859-1.
+            $bodyBytes = [System.Text.Encoding]::UTF8.GetBytes($JsonArgs)
+            $response = Invoke-RestMethod -Method Post -Uri $uri -Body $bodyBytes -ContentType 'application/json; charset=utf-8' -TimeoutSec $TimeoutSec
+            Write-JsonLine $response
+        }
+    }
+}
+catch {
+    # Surface the bridge's JSON error body (409 no-document, 403 stale token,
+    # 400 bad args, 404 unknown tool) instead of Invoke-RestMethod's generic
+    # status-line message. The body is already one-line JSON; print it verbatim.
+    $body = $null
+    if ($_.ErrorDetails -and -not [string]::IsNullOrWhiteSpace($_.ErrorDetails.Message)) {
+        $body = $_.ErrorDetails.Message
+    } elseif ($_.Exception -is [System.Net.WebException] -and $_.Exception.Response) {
+        # Windows PowerShell 5.1: read the WebException response stream directly.
+        try {
+            $reader = [System.IO.StreamReader]::new($_.Exception.Response.GetResponseStream(), [System.Text.Encoding]::UTF8)
+            $body = $reader.ReadToEnd()
+        } catch { $body = $null }
+    }
+    if (-not [string]::IsNullOrWhiteSpace($body)) {
+        [Console]::Out.WriteLine($body.Trim())
+        exit 1
+    }
+    Write-JsonError $_.Exception.Message
+}