pi-revit 0.2.6 → 0.2.8

package/CHANGELOG.md

@@ -7,6 +7,28 @@ Format follows [Keep a Changelog](https://keepachangelog.com/); version headers
 Every published version gets an entry with **Added** / **Changed** / **Fixed** sections
 describing what the user will notice — not internal refactors.
 
+## [0.2.8] - 2026-07-21
+
+### Fixed
+- `search_api_docs`: overload-targeted queries no longer fail on comma spacing.
+  `Wall.Create(Document,Curve` (no space) and `Wall.Create( Document, Curve` now match the
+  same overloads as `Wall.Create(Document, Curve` — the query's spacing around commas and
+  parentheses is normalized to the rendered signature style before matching.
+
+Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then restart
+Revit).
+
+## [0.2.7] - 2026-07-21
+
+### Added
+- Update announcements: after a pi-revit update, the next pi session shows a one-time
+  "What's new in pi-revit" note listing the changelog entries for every version since the
+  last one announced — the same mechanism pi uses for its own updates. The last-announced
+  version is remembered in `%APPDATA%\pi-revit\state.json` (kept outside the package
+  folder so npm updates can't erase it). Fresh installs stay silent.
+
+Extension-only change: no Revit add-in redeploy or Revit restart needed.
+
 ## [0.2.6] - 2026-07-20
 
 ### Fixed

package/extensions/pi-revit/index.ts

@@ -1,8 +1,9 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type, type TSchema } from "typebox";
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { version as packageVersion } from "../../package.json";
 
 interface BridgeInfo {
@@ -207,6 +208,73 @@ function versionMismatch(addinVersion: unknown): string | null {
 	return `pi-revit ${packageVersion} is installed, but the Revit add-in ${state} — the update is incomplete. Close Revit and run: npx.cmd -y pi-revit (or ask the agent to run scripts\\deploy.ps1 from the installed package, then restart Revit).`;
 }
 
+// ------------------------------------------------------------- what's new
+
+/** Stable per-user state file. Deliberately NOT under node_modules: npm wipes
+ * the package folder on every update, which is exactly when the last-announced
+ * version must survive. */
+function announcerStatePath(): string {
+	const appData = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
+	return path.join(appData, "pi-revit", "state.json");
+}
+
+function compareVersions(a: string, b: string): number {
+	const pa = a.split(".").map((part) => Number.parseInt(part, 10) || 0);
+	const pb = b.split(".").map((part) => Number.parseInt(part, 10) || 0);
+	for (let i = 0; i < 3; i++) {
+		if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) - (pb[i] ?? 0);
+	}
+	return 0;
+}
+
+/** Parses `## [x.y.z]` entries from the packaged CHANGELOG.md (the same header
+ * format pi's own changelog parser reads) and returns the ones newer than
+ * sinceVersion, newest first — so a 0.2.5 -> 0.2.9 jump shows all four. */
+async function newChangelogEntries(sinceVersion: string): Promise<{ version: string; body: string }[]> {
+	const changelogPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "CHANGELOG.md");
+	const markdown = await readFile(changelogPath, "utf8");
+	const headers = [...markdown.matchAll(/^##\s+\[?(\d+\.\d+\.\d+)\]?[^\n]*$/gm)];
+	const entries: { version: string; body: string }[] = [];
+	for (let i = 0; i < headers.length; i++) {
+		const version = headers[i][1];
+		if (compareVersions(version, sinceVersion) <= 0) continue;
+		const start = (headers[i].index ?? 0) + headers[i][0].length;
+		const end = i + 1 < headers.length ? headers[i + 1].index : markdown.length;
+		entries.push({ version, body: markdown.slice(start, end).trim() });
+	}
+	return entries;
+}
+
+/** Shows the changelog entries between the last announced version and the
+ * current one, once per update, then records the current version. A fresh
+ * install records silently (nothing is "new" yet). Every failure is swallowed:
+ * the announcer must never break a session. */
+async function announceUpdateOnce(notify: (message: string, level: "info") => void): Promise<void> {
+	try {
+		const statePath = announcerStatePath();
+		let lastVersion: string | null = null;
+		try {
+			const state = JSON.parse(await readFile(statePath, "utf8")) as { lastAnnouncedVersion?: string };
+			if (typeof state.lastAnnouncedVersion === "string") lastVersion = state.lastAnnouncedVersion;
+		} catch {
+			// First run: no state yet.
+		}
+		if (lastVersion === packageVersion) return;
+
+		if (lastVersion) {
+			const entries = await newChangelogEntries(lastVersion);
+			if (entries.length > 0) {
+				const text = entries.map((entry) => `pi-revit ${entry.version}\n${entry.body}`).join("\n\n");
+				notify(`What's new in pi-revit (updated from ${lastVersion}):\n\n${text}`, "info");
+			}
+		}
+		await mkdir(path.dirname(statePath), { recursive: true });
+		await writeFile(statePath, JSON.stringify({ lastAnnouncedVersion: packageVersion }, null, 2), "utf8");
+	} catch {
+		// Never let the announcer break a session.
+	}
+}
+
 function registerPing(pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "ping",
@@ -236,6 +304,7 @@ export default async function revitConnector(pi: ExtensionAPI) {
 	// where the user lands after running `pi update --extensions`. Bridge down at
 	// session start is the normal Revit-closed case: stay quiet.
 	pi.on("session_start", async (_event, ctx) => {
+		await announceUpdateOnce((message, level) => ctx.ui.notify(message, level));
 		try {
 			const payload = (await bridgeRequest("/ping", { method: "GET" }, undefined, 3_000)) as { addinVersion?: string };
 			const warning = versionMismatch(payload.addinVersion);

package/package.json

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

package/scripts/setup-workspace.ps1

@@ -1,80 +1,80 @@
-#Requires -Version 5.1
-<#
-Sets up the pi-revit user environment on this PC:
-
-  1. Workspace at Documents\pi-revit (AGENTS.md conventions, Models\ output tree,
-     double-click launcher). An existing AGENTS.md is never overwritten.
-  2. Global `pi-revit` command installed next to the `pi` command, so any terminal can run:
-       pi-revit              -> Pi in the workspace
-       pi-revit -c           -> continue the last session
-     Model output sorts itself: the Revit tools file each export under
-     Models\<model title>\ automatically, keyed by the document it came from.
-
-Idempotent — safe to re-run. Usage:
-  scripts\setup-workspace.ps1
-  scripts\setup-workspace.ps1 -WorkspaceDir "D:\work\pi-revit"
-#>
-param(
-    [string]$WorkspaceDir = (Join-Path ([Environment]::GetFolderPath('MyDocuments')) 'pi-revit')
-)
-
-$ErrorActionPreference = 'Stop'
-$templates = Join-Path (Split-Path $PSScriptRoot -Parent) 'workspace'
-
-# 1. Workspace folders. Models\ is where the Revit tools file per-model output.
-New-Item -ItemType Directory -Force -Path (Join-Path $WorkspaceDir 'Models') | Out-Null
-
-# Conventions / notes: copy only when missing so user edits survive re-runs.
-$workspaceAgents = Join-Path $WorkspaceDir 'AGENTS.md'
-if (-not (Test-Path $workspaceAgents)) {
-    Copy-Item (Join-Path $templates 'AGENTS.md') $workspaceAgents
-}
-
-# Launcher is code, not user data: always refresh.
-Copy-Item (Join-Path $templates 'pi-revit-here.cmd') (Join-Path $WorkspaceDir 'pi-revit.cmd') -Force
-
-Write-Host "Workspace ready: $WorkspaceDir" -ForegroundColor Green
-
-# 2. Global pi-revit command next to pi (that directory is on PATH by definition).
-#    The template's workspace path is rewritten to honor -WorkspaceDir.
-#    Under `npx pi-revit`, npx prepends its ephemeral cache's node_modules\.bin to
-#    PATH, and that folder holds a pi shim pulled in via peerDependencies. A launcher
-#    written next to that shim lands in a folder that is neither on the user's own
-#    PATH nor long-lived, so skip pi entries inside this package's node_modules tree
-#    or any npx cache and use the user's permanent pi instead.
-function Get-PermanentPiCommand {
-    # Long-form both sides of the prefix comparison: PATH entries may carry 8.3
-    # short names (AHMAD~1.TAH) while $PSScriptRoot is normalized, and a form
-    # mismatch would silently defeat the own-tree exclusion.
-    function Resolve-LongPath([string]$p) {
-        try { (Get-Item -LiteralPath $p -ErrorAction Stop).FullName } catch { $p }
-    }
-    $ownTree = $null
-    $repoRoot = Resolve-LongPath (Split-Path $PSScriptRoot -Parent)
-    $idx = $repoRoot.LastIndexOf('\node_modules\', [StringComparison]::OrdinalIgnoreCase)
-    if ($idx -ge 0) { $ownTree = $repoRoot.Substring(0, $idx + '\node_modules\'.Length) }
-    Get-Command pi -All -ErrorAction SilentlyContinue | Where-Object {
-        if (-not $_.Source) { return $false }
-        $src = Resolve-LongPath $_.Source
-        ($src -notmatch '\\_npx\\') -and
-        (-not $ownTree -or -not $src.StartsWith($ownTree, [StringComparison]::OrdinalIgnoreCase))
-    } | Select-Object -First 1
-}
-
-$pi = Get-PermanentPiCommand
-if ($pi) {
-    $binDir = Split-Path $pi.Source -Parent
-    # Literal line swap (no regex): the workspace path may contain characters
-    # like $ that a -replace replacement string would misinterpret.
-    $globalCmd = Get-Content (Join-Path $templates 'pi-revit-global.cmd') | ForEach-Object {
-        if ($_ -like 'set "WORKSPACE=*') { 'set "WORKSPACE=' + $WorkspaceDir + '"' } else { $_ }
-    }
-    # cmd.exe parses .cmd files in the console's OEM code page: write the launcher
-    # in that encoding so workspace paths with non-ASCII characters (user names,
-    # localized folder names) stay intact.
-    Set-Content -Path (Join-Path $binDir 'pi-revit.cmd') -Value $globalCmd -Encoding Oem
-    Write-Host "Global command installed: $(Join-Path $binDir 'pi-revit.cmd')" -ForegroundColor Green
-    Write-Host 'Run pi-revit from any terminal (pi-revit -c continues the last session).'
-} else {
-    Write-Warning 'No permanent pi command found on PATH. Install Pi first (npm install -g --ignore-scripts @earendil-works/pi-coding-agent), then run npx.cmd -y pi-revit again (or re-run this script) to get the global pi-revit command.'
-}
+#Requires -Version 5.1
+<#
+Sets up the pi-revit user environment on this PC:
+
+  1. Workspace at Documents\pi-revit (AGENTS.md conventions, Models\ output tree,
+     double-click launcher). An existing AGENTS.md is never overwritten.
+  2. Global `pi-revit` command installed next to the `pi` command, so any terminal can run:
+       pi-revit              -> Pi in the workspace
+       pi-revit -c           -> continue the last session
+     Model output sorts itself: the Revit tools file each export under
+     Models\<model title>\ automatically, keyed by the document it came from.
+
+Idempotent — safe to re-run. Usage:
+  scripts\setup-workspace.ps1
+  scripts\setup-workspace.ps1 -WorkspaceDir "D:\work\pi-revit"
+#>
+param(
+    [string]$WorkspaceDir = (Join-Path ([Environment]::GetFolderPath('MyDocuments')) 'pi-revit')
+)
+
+$ErrorActionPreference = 'Stop'
+$templates = Join-Path (Split-Path $PSScriptRoot -Parent) 'workspace'
+
+# 1. Workspace folders. Models\ is where the Revit tools file per-model output.
+New-Item -ItemType Directory -Force -Path (Join-Path $WorkspaceDir 'Models') | Out-Null
+
+# Conventions / notes: copy only when missing so user edits survive re-runs.
+$workspaceAgents = Join-Path $WorkspaceDir 'AGENTS.md'
+if (-not (Test-Path $workspaceAgents)) {
+    Copy-Item (Join-Path $templates 'AGENTS.md') $workspaceAgents
+}
+
+# Launcher is code, not user data: always refresh.
+Copy-Item (Join-Path $templates 'pi-revit-here.cmd') (Join-Path $WorkspaceDir 'pi-revit.cmd') -Force
+
+Write-Host "Workspace ready: $WorkspaceDir" -ForegroundColor Green
+
+# 2. Global pi-revit command next to pi (that directory is on PATH by definition).
+#    The template's workspace path is rewritten to honor -WorkspaceDir.
+#    Under `npx pi-revit`, npx prepends its ephemeral cache's node_modules\.bin to
+#    PATH, and that folder holds a pi shim pulled in via peerDependencies. A launcher
+#    written next to that shim lands in a folder that is neither on the user's own
+#    PATH nor long-lived, so skip pi entries inside this package's node_modules tree
+#    or any npx cache and use the user's permanent pi instead.
+function Get-PermanentPiCommand {
+    # Long-form both sides of the prefix comparison: PATH entries may carry 8.3
+    # short names (SOMEUS~1.NAM) while $PSScriptRoot is normalized, and a form
+    # mismatch would silently defeat the own-tree exclusion.
+    function Resolve-LongPath([string]$p) {
+        try { (Get-Item -LiteralPath $p -ErrorAction Stop).FullName } catch { $p }
+    }
+    $ownTree = $null
+    $repoRoot = Resolve-LongPath (Split-Path $PSScriptRoot -Parent)
+    $idx = $repoRoot.LastIndexOf('\node_modules\', [StringComparison]::OrdinalIgnoreCase)
+    if ($idx -ge 0) { $ownTree = $repoRoot.Substring(0, $idx + '\node_modules\'.Length) }
+    Get-Command pi -All -ErrorAction SilentlyContinue | Where-Object {
+        if (-not $_.Source) { return $false }
+        $src = Resolve-LongPath $_.Source
+        ($src -notmatch '\\_npx\\') -and
+        (-not $ownTree -or -not $src.StartsWith($ownTree, [StringComparison]::OrdinalIgnoreCase))
+    } | Select-Object -First 1
+}
+
+$pi = Get-PermanentPiCommand
+if ($pi) {
+    $binDir = Split-Path $pi.Source -Parent
+    # Literal line swap (no regex): the workspace path may contain characters
+    # like $ that a -replace replacement string would misinterpret.
+    $globalCmd = Get-Content (Join-Path $templates 'pi-revit-global.cmd') | ForEach-Object {
+        if ($_ -like 'set "WORKSPACE=*') { 'set "WORKSPACE=' + $WorkspaceDir + '"' } else { $_ }
+    }
+    # cmd.exe parses .cmd files in the console's OEM code page: write the launcher
+    # in that encoding so workspace paths with non-ASCII characters (user names,
+    # localized folder names) stay intact.
+    Set-Content -Path (Join-Path $binDir 'pi-revit.cmd') -Value $globalCmd -Encoding Oem
+    Write-Host "Global command installed: $(Join-Path $binDir 'pi-revit.cmd')" -ForegroundColor Green
+    Write-Host 'Run pi-revit from any terminal (pi-revit -c continues the last session).'
+} else {
+    Write-Warning 'No permanent pi command found on PATH. Install Pi first (npm install -g --ignore-scripts @earendil-works/pi-coding-agent), then run npx.cmd -y pi-revit again (or re-run this script) to get the global pi-revit command.'
+}

package/scripts/uninstall.ps1

@@ -1,146 +1,146 @@
-#Requires -Version 5.1
-<#
-Removes everything the pi-revit install scripts placed on this PC:
-
-  - Revit bridge add-in:  %APPDATA%\Autodesk\Revit\Addins\<version>\RevitBridge.addin
-                          %APPDATA%\Autodesk\Revit\Addins\<version>\RevitBridge\
-  - Global command:       the pi-revit command next to the pi command
-  - Bridge runtime:       %APPDATA%\RevitBridge\ (per-start connection token / bridge.json)
-  - Pi package:           the pi-revit registration (pi remove), best-effort when pi is on PATH
-
-The workspace at Documents\pi-revit holds YOUR data (AGENTS.md notes, per-project
-session history) and is preserved by default. Pass -RemoveWorkspace to delete it too.
-
-Pi itself (the global coding agent) is yours to manage and is never touched.
-
-Close Revit before running. Idempotent — safe to re-run.
-
-Usage:
-  scripts\uninstall.ps1
-  scripts\uninstall.ps1 -RevitVersion 2027
-  scripts\uninstall.ps1 -RemoveWorkspace
-#>
-param(
-    [string]$RevitVersion = '',
-    [string]$WorkspaceDir = (Join-Path ([Environment]::GetFolderPath('MyDocuments')) 'pi-revit'),
-    [switch]$RemoveWorkspace
-)
-
-$ErrorActionPreference = 'Stop'
-
-function Remove-IfExists {
-    param([string]$Path, [string]$Label)
-    if (Test-Path -LiteralPath $Path) {
-        Remove-Item -LiteralPath $Path -Recurse -Force
-        Write-Host "Removed $Label : $Path" -ForegroundColor Green
-    } else {
-        Write-Host "Not present, skipped $Label : $Path"
-    }
-}
-
-# 1. Revit add-in. With no -RevitVersion, sweep every Addins\<version> folder so the
-#    user need not remember which Revit they deployed to.
-$addinsRoot = Join-Path $env:APPDATA 'Autodesk\Revit\Addins'
-$versions = if ($RevitVersion) {
-    @($RevitVersion)
-} elseif (Test-Path -LiteralPath $addinsRoot) {
-    Get-ChildItem -LiteralPath $addinsRoot -Directory | ForEach-Object { $_.Name }
-} else {
-    @()
-}
-foreach ($v in $versions) {
-    $dir = Join-Path $addinsRoot $v
-    Remove-IfExists (Join-Path $dir 'RevitBridge.addin') "Revit $v add-in manifest"
-    Remove-IfExists (Join-Path $dir 'RevitBridge')       "Revit $v add-in folder"
-}
-
-# 2. Global pi-revit command next to the user's permanent pi. When this script runs
-#    from an npx cache or a node_modules copy, PATH may lead Get-Command to a pi shim
-#    inside that ephemeral tree first (see setup-workspace.ps1) — the launcher was
-#    never installed there, so resolve the permanent pi the same way setup does.
-function Get-PermanentPiCommand {
-    # Long-form both sides of the prefix comparison: PATH entries may carry 8.3
-    # short names (AHMAD~1.TAH) while $PSScriptRoot is normalized, and a form
-    # mismatch would silently defeat the own-tree exclusion.
-    function Resolve-LongPath([string]$p) {
-        try { (Get-Item -LiteralPath $p -ErrorAction Stop).FullName } catch { $p }
-    }
-    $ownTree = $null
-    $repoRoot = Resolve-LongPath (Split-Path $PSScriptRoot -Parent)
-    $idx = $repoRoot.LastIndexOf('\node_modules\', [StringComparison]::OrdinalIgnoreCase)
-    if ($idx -ge 0) { $ownTree = $repoRoot.Substring(0, $idx + '\node_modules\'.Length) }
-    Get-Command pi -All -ErrorAction SilentlyContinue | Where-Object {
-        if (-not $_.Source) { return $false }
-        $src = Resolve-LongPath $_.Source
-        ($src -notmatch '\\_npx\\') -and
-        (-not $ownTree -or -not $src.StartsWith($ownTree, [StringComparison]::OrdinalIgnoreCase))
-    } | Select-Object -First 1
-}
-
-$pi = Get-Command pi -ErrorAction SilentlyContinue
-$piPermanent = Get-PermanentPiCommand
-if ($piPermanent) {
-    $binDir = Split-Path $piPermanent.Source -Parent
-    Remove-IfExists (Join-Path $binDir 'pi-revit.cmd') 'global pi-revit command'
-} else {
-    Write-Host 'No permanent pi found on PATH; skipping the global pi-revit command.'
-}
-
-# 3. Bridge runtime folder (connection token; recreated on each Revit start).
-Remove-IfExists (Join-Path $env:APPDATA 'RevitBridge') 'bridge runtime folder'
-
-# 4. Pi package registration. Pi keys a package by its install source: the npm
-#    installer (npx.cmd -y pi-revit) registers `npm:pi-revit`, while an install
-#    from a clone of this repo (`pi install ./`) registers the repo path resolved
-#    from the repo root. Try both forms; each succeeds only for the source that
-#    is actually registered, so a machine with both gets both removed.
-if ($pi) {
-    $repoRoot = Split-Path $PSScriptRoot -Parent
-    # When this script runs from the npm-installed copy, `pi remove npm:pi-revit`
-    # deletes the very folder the script lives in — and Windows fails that delete
-    # (EBUSY) while any working directory sits inside it. Step our own process out
-    # if needed; the calling shell's location we can only warn about.
-    if ($repoRoot -match '\\node_modules\\' -and
-        (Get-Location).Path.StartsWith($repoRoot, [StringComparison]::OrdinalIgnoreCase)) {
-        Set-Location $env:SystemRoot
-        Write-Warning "This PowerShell was started inside $repoRoot. If the package removal below fails, run 'cd \' in your shell and re-run the uninstall."
-    }
-    try {
-        $removed = @()
-        # './' resolves against the repo root, so it runs from there — and first,
-        # while this folder is guaranteed to still exist. 'npm:pi-revit' then runs
-        # from a neutral directory so no working directory blocks the folder delete.
-        foreach ($source in @('./', 'npm:pi-revit')) {
-            Push-Location $(if ($source -eq './') { $repoRoot } else { $env:SystemRoot })
-            try {
-                $global:LASTEXITCODE = 0
-                & pi remove $source
-                if ($LASTEXITCODE -eq 0) {
-                    $removed += $source
-                }
-            } finally {
-                Pop-Location
-            }
-        }
-        if ($removed.Count -gt 0) {
-            Write-Host "Removed the pi-revit Pi package ($($removed -join ', '))." -ForegroundColor Green
-        } else {
-            Write-Warning "No pi-revit Pi package registration was found. If pi still lists it, run 'pi remove npm:pi-revit' (npm install) or 'pi remove ./' from this repo (install from source)."
-        }
-    } catch {
-        Write-Warning "Could not auto-remove the Pi package; run 'pi remove npm:pi-revit' (npm install) or 'pi remove ./' from this repo (install from source). ($_)"
-    }
-}
-
-# 5. Workspace (user data) — opt-in only.
-if ($RemoveWorkspace) {
-    Remove-IfExists $WorkspaceDir 'workspace'
-} else {
-    Write-Host ''
-    Write-Host "Workspace preserved (your notes + session history): $WorkspaceDir" -ForegroundColor Yellow
-    Write-Host 'Pass -RemoveWorkspace to delete it too.'
-}
-
-Write-Host ''
-Write-Host 'pi-revit uninstalled. Pi itself is untouched; remove it yourself if you want:' -ForegroundColor Green
-Write-Host '  npm uninstall -g @earendil-works/pi-coding-agent'
+#Requires -Version 5.1
+<#
+Removes everything the pi-revit install scripts placed on this PC:
+
+  - Revit bridge add-in:  %APPDATA%\Autodesk\Revit\Addins\<version>\RevitBridge.addin
+                          %APPDATA%\Autodesk\Revit\Addins\<version>\RevitBridge\
+  - Global command:       the pi-revit command next to the pi command
+  - Bridge runtime:       %APPDATA%\RevitBridge\ (per-start connection token / bridge.json)
+  - Pi package:           the pi-revit registration (pi remove), best-effort when pi is on PATH
+
+The workspace at Documents\pi-revit holds YOUR data (AGENTS.md notes, per-project
+session history) and is preserved by default. Pass -RemoveWorkspace to delete it too.
+
+Pi itself (the global coding agent) is yours to manage and is never touched.
+
+Close Revit before running. Idempotent — safe to re-run.
+
+Usage:
+  scripts\uninstall.ps1
+  scripts\uninstall.ps1 -RevitVersion 2027
+  scripts\uninstall.ps1 -RemoveWorkspace
+#>
+param(
+    [string]$RevitVersion = '',
+    [string]$WorkspaceDir = (Join-Path ([Environment]::GetFolderPath('MyDocuments')) 'pi-revit'),
+    [switch]$RemoveWorkspace
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Remove-IfExists {
+    param([string]$Path, [string]$Label)
+    if (Test-Path -LiteralPath $Path) {
+        Remove-Item -LiteralPath $Path -Recurse -Force
+        Write-Host "Removed $Label : $Path" -ForegroundColor Green
+    } else {
+        Write-Host "Not present, skipped $Label : $Path"
+    }
+}
+
+# 1. Revit add-in. With no -RevitVersion, sweep every Addins\<version> folder so the
+#    user need not remember which Revit they deployed to.
+$addinsRoot = Join-Path $env:APPDATA 'Autodesk\Revit\Addins'
+$versions = if ($RevitVersion) {
+    @($RevitVersion)
+} elseif (Test-Path -LiteralPath $addinsRoot) {
+    Get-ChildItem -LiteralPath $addinsRoot -Directory | ForEach-Object { $_.Name }
+} else {
+    @()
+}
+foreach ($v in $versions) {
+    $dir = Join-Path $addinsRoot $v
+    Remove-IfExists (Join-Path $dir 'RevitBridge.addin') "Revit $v add-in manifest"
+    Remove-IfExists (Join-Path $dir 'RevitBridge')       "Revit $v add-in folder"
+}
+
+# 2. Global pi-revit command next to the user's permanent pi. When this script runs
+#    from an npx cache or a node_modules copy, PATH may lead Get-Command to a pi shim
+#    inside that ephemeral tree first (see setup-workspace.ps1) — the launcher was
+#    never installed there, so resolve the permanent pi the same way setup does.
+function Get-PermanentPiCommand {
+    # Long-form both sides of the prefix comparison: PATH entries may carry 8.3
+    # short names (SOMEUS~1.NAM) while $PSScriptRoot is normalized, and a form
+    # mismatch would silently defeat the own-tree exclusion.
+    function Resolve-LongPath([string]$p) {
+        try { (Get-Item -LiteralPath $p -ErrorAction Stop).FullName } catch { $p }
+    }
+    $ownTree = $null
+    $repoRoot = Resolve-LongPath (Split-Path $PSScriptRoot -Parent)
+    $idx = $repoRoot.LastIndexOf('\node_modules\', [StringComparison]::OrdinalIgnoreCase)
+    if ($idx -ge 0) { $ownTree = $repoRoot.Substring(0, $idx + '\node_modules\'.Length) }
+    Get-Command pi -All -ErrorAction SilentlyContinue | Where-Object {
+        if (-not $_.Source) { return $false }
+        $src = Resolve-LongPath $_.Source
+        ($src -notmatch '\\_npx\\') -and
+        (-not $ownTree -or -not $src.StartsWith($ownTree, [StringComparison]::OrdinalIgnoreCase))
+    } | Select-Object -First 1
+}
+
+$pi = Get-Command pi -ErrorAction SilentlyContinue
+$piPermanent = Get-PermanentPiCommand
+if ($piPermanent) {
+    $binDir = Split-Path $piPermanent.Source -Parent
+    Remove-IfExists (Join-Path $binDir 'pi-revit.cmd') 'global pi-revit command'
+} else {
+    Write-Host 'No permanent pi found on PATH; skipping the global pi-revit command.'
+}
+
+# 3. Bridge runtime folder (connection token; recreated on each Revit start).
+Remove-IfExists (Join-Path $env:APPDATA 'RevitBridge') 'bridge runtime folder'
+
+# 4. Pi package registration. Pi keys a package by its install source: the npm
+#    installer (npx.cmd -y pi-revit) registers `npm:pi-revit`, while an install
+#    from a clone of this repo (`pi install ./`) registers the repo path resolved
+#    from the repo root. Try both forms; each succeeds only for the source that
+#    is actually registered, so a machine with both gets both removed.
+if ($pi) {
+    $repoRoot = Split-Path $PSScriptRoot -Parent
+    # When this script runs from the npm-installed copy, `pi remove npm:pi-revit`
+    # deletes the very folder the script lives in — and Windows fails that delete
+    # (EBUSY) while any working directory sits inside it. Step our own process out
+    # if needed; the calling shell's location we can only warn about.
+    if ($repoRoot -match '\\node_modules\\' -and
+        (Get-Location).Path.StartsWith($repoRoot, [StringComparison]::OrdinalIgnoreCase)) {
+        Set-Location $env:SystemRoot
+        Write-Warning "This PowerShell was started inside $repoRoot. If the package removal below fails, run 'cd \' in your shell and re-run the uninstall."
+    }
+    try {
+        $removed = @()
+        # './' resolves against the repo root, so it runs from there — and first,
+        # while this folder is guaranteed to still exist. 'npm:pi-revit' then runs
+        # from a neutral directory so no working directory blocks the folder delete.
+        foreach ($source in @('./', 'npm:pi-revit')) {
+            Push-Location $(if ($source -eq './') { $repoRoot } else { $env:SystemRoot })
+            try {
+                $global:LASTEXITCODE = 0
+                & pi remove $source
+                if ($LASTEXITCODE -eq 0) {
+                    $removed += $source
+                }
+            } finally {
+                Pop-Location
+            }
+        }
+        if ($removed.Count -gt 0) {
+            Write-Host "Removed the pi-revit Pi package ($($removed -join ', '))." -ForegroundColor Green
+        } else {
+            Write-Warning "No pi-revit Pi package registration was found. If pi still lists it, run 'pi remove npm:pi-revit' (npm install) or 'pi remove ./' from this repo (install from source)."
+        }
+    } catch {
+        Write-Warning "Could not auto-remove the Pi package; run 'pi remove npm:pi-revit' (npm install) or 'pi remove ./' from this repo (install from source). ($_)"
+    }
+}
+
+# 5. Workspace (user data) — opt-in only.
+if ($RemoveWorkspace) {
+    Remove-IfExists $WorkspaceDir 'workspace'
+} else {
+    Write-Host ''
+    Write-Host "Workspace preserved (your notes + session history): $WorkspaceDir" -ForegroundColor Yellow
+    Write-Host 'Pass -RemoveWorkspace to delete it too.'
+}
+
+Write-Host ''
+Write-Host 'pi-revit uninstalled. Pi itself is untouched; remove it yourself if you want:' -ForegroundColor Green
+Write-Host '  npm uninstall -g @earendil-works/pi-coding-agent'

package/src/Revit/Tools/SearchApiDocs.cs

@@ -1,5 +1,6 @@
 using System.IO;
 using System.Text;
+using System.Text.RegularExpressions;
 using System.Text.Json;
 using System.Xml;
 using System.Xml.Linq;
@@ -124,7 +125,13 @@ namespace RevitBridge.Tools
 
         private static (List<ApiMember> Top, int Total) Search(DocIndex index, string query, char? kindFilter, int maxResults)
         {
+            // Signatures are rendered exactly one way ("Name(Type, Type)"): normalize the
+            // query's spacing around commas and parentheses so 'Wall.Create(Document,Curve'
+            // and 'Wall.Create( Document, Curve' hit the same rendered text instead of
+            // failing on typography.
             string q = query.ToLowerInvariant();
+            q = Regex.Replace(q, @"\s*,\s*", ", ");
+            q = Regex.Replace(q, @"\(\s+", "(");
             string[] words = q.Split(WordSeparators, StringSplitOptions.RemoveEmptyEntries);
 
             var scored = new List<(ApiMember Member, int Score)>();