pi-revit 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,12 +1,55 @@
-# Changelog
-
-All notable changes to pi-revit are documented here.
-Format follows [Keep a Changelog](https://keepachangelog.com/); version headers use
-`## [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
+# Changelog
+
+All notable changes to pi-revit are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/); version headers use
+`## [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.4.0] - 2026-09-22
+
+### Added
+
+- Linked-model discovery and filtered linked-element queries with exact linked document identities and host-coordinate bounds.
+- Schedule inspection with independent row and column pagination, and element relationship inspection.
+- `find_revit_tools` searches and activates specialist tools within the current Pi session while preserving other extensions' active tools.
+- `get_elements` can include up to 20 requested parameter identities per element, with optional type parameters and explicit missing or ambiguous matches. Raw values and formatted display values are returned separately.
+- `summarize_elements` counts the whole query scope by category, type, level, or exact raw parameter value, with independently paginated groups and a 10,000-element limit.
+- `manage_element_sets` retains query membership for repeat reads of current values and reports missing members. Sets are limited to 10,000 members and 32 retained sets, expire after 30 minutes, and belong to the exact open document and bridge session.
+- `get_revit_operation` reads operation receipts without waiting for Revit's model thread. Supporting bridges automatically track native tool calls; retrying with the same `_operation_id` and identical arguments does not repeat the action. Full results are bounded to 128 completed receipts / 32 MiB, while up to 10,000 receipt records keep IDs reserved for that bridge session. Restarting the bridge clears receipts; an unknown outcome must be checked against the original model.
+- `transform_elements` moves, copies, or rotates up to 200 selected elements together, with explicit input units, document-internal coordinates, and preview rollback. IDs created during previews are temporary.
+- `delete_elements` previews or performs a whole-selection deletion and returns Revit's deletion set, including dependents. An optional `expected_deleted_ids` check rejects changed deletion membership; cascades above 10,000 IDs roll back.
+- `change_element_types` validates up to 200 target/type pairs with per-target outcomes, optional atomic rollback, and previews. Results identify replacement elements; replacement IDs from rolled-back operations must not be reused.
+- `manage_revit_instances` lists reachable local bridge sessions and selects a target for the current Pi session. Each current bridge has its own discovery file; legacy discovery and opaque selectors remain supported. The first sole instance binds automatically, while multiple instances require explicit selection. Selection refreshes the tool catalogue; read a fresh model overview afterward.
+- `manage_views` creates plans, isometric 3D views, and sections, or duplicates and updates views, with compatible templates, scale checks, and previews. Sections use explicit units and document-internal coordinates.
+- `manage_sheets` creates, renames, or renumbers sheets, with an optional loaded titleblock at creation and preview rollback.
+- `manage_sheet_placements` lists, places, and moves viewports or schedule instances using paper-space coordinates. Viewport positions exclude labels; schedule positions are insertion points. Edits support previews with temporary created IDs, and every action, including listing, requires an exact document identity.
+- `get_schedule_fields` discovers eligible parameter/type pairs for regular schedules. `manage_schedules` creates or configures schedules with field headings, visibility, widths, itemization, sorting, and typed filters, including explicit units for measured numeric filters and preview rollback.
+- `create_tags` creates host element, room, space, or area tags with explicit tag-head positions, loaded tag types, partial or atomic batches, and preview rollback. Proposed tag IDs are temporary.
+- `query_spatial_elements` finds host elements by axis-aligned bounding-box intersection or containment in an explicitly sized region, with whole-scope candidate limits, paging, and missing-box counts.
+- `measure_geometry` measures exact distance between supplied points or approximate separation between host-element bounding boxes, with explicit units and an optional box-proximity threshold. Box overlap and threshold hits are not confirmed clashes or clearance failures.
+- Pi skill references provide room-documentation and model-audit/export workflows using native tools, previews, exact identities, and recorded output paths.
+- `manage_revit_scripts` saves immutable local script definitions without executing them, reads source, and runs an exact content-hash version with required named inputs. Local history records the version, document, input hash, and operation receipt without retaining raw inputs or results. Runs use the existing unrestricted script execution contract; no automatic runs or model saving are added.
+- `get_model_coordinates` reads project/survey base points, site/project locations, and the active shared-coordinate mapping for explicit internal points. Length units are required; no GIS reference system is inferred or coordinates changed.
+
+### Changed
+
+- `set_parameters` supports `preview` and `atomic` batches, with a subtransaction for each update and observed per-step before/after values. Committed updates appear in `succeeded`; accepted steps that were rolled back appear in `proposed`. Preview attempts commit validation before rolling back its transaction group when the batch is eligible; `commit_validation_performed` reports whether those checks ran. Default batches still commit partial successes.
+- A bound Revit session is no longer replaced implicitly after closing or restarting: list and select its new identity before further model calls. Operation receipt reads and identical retries continue to target their original bridge even when another instance is selected; unavailable originals are never redirected.
+- `get_schedules` now includes field specifications, grid/sheet widths in feet, filtering capabilities, and current sort/filter rules. Numeric filter values are reported in Revit internal units.
+- `execute_csharp` accepts structured JSON `inputs` as a separate `JsonElement` global, keeping input values separate from source code.
+
+### Fixed
+
+- `manage_schedules` accepts the Count parameter/type pair returned by `get_schedule_fields`, while preserving Count creation without a parameter ID. Discovery and editing descriptions now document both supported forms.
+
+## [0.3.1] - 2026-09-16
+
+### Fixed
+
+- The installer checks the selected .NET SDK before installing packages or building the add-in. Missing or older SDKs now produce a clear explanation, the matching Windows x64 SDK download link, and retry instructions. Interactive installs offer to open the download page. Manual builds and deployments also check the SDK before compiling.
+
 ## [0.3.0] - 2026-09-09
 
 ### Added
@@ -41,347 +84,347 @@ 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`
-  call) registers the bridge tools, the session is now told — the same announcement the
-  ping path has always given. Previously the tools appeared silently in the next system
-  prompt while nothing contradicted the session's earlier "Revit is not running", so the
-  agent could stay needlessly pessimistic. The note is queued for the next user prompt
-  and never interrupts. Extension-only change; the Revit add-in is unchanged (the
-  standard installer keeps both versions aligned).
-
-## [0.2.17] - 2026-08-21
-
-### Fixed
-- The bridge's no-document check no longer counts linked documents. With only links
-  loaded, Revit does not pump the bridge's work queue, so a call could wait out its full
-  timeout instead of failing immediately with the clean "no active document" answer.
-
-### Changed
-- Docs and tool descriptions describe localized parameter names generically instead of
-  quoting specific languages.
-- The full search_api_docs benchmark (641 live queries against RevitAPI.xml ground truth)
-  was re-run on Revit 2025 at 0.2.16: 100% recall, 98.75% top-1 on exact names, 100%
-  spacing-variant agreement, 0 false positives across 99 adversarial mutations, 50/50
-  parameter docs, p50 10 ms -- no regression across the 0.2.13-0.2.16 search changes.
-
-Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
-restart Revit).
-
-## [0.2.16] - 2026-08-21
-
-### Fixed
-- `search_api_docs`: an accessor-spelling query combined with `kind: "method"` — e.g.
-  `Element.get_Parameter(BuiltInParameter)` filtered to methods — returned "no matches",
-  because the accessor rewrite found the documented member but the kind filter rejected it:
-  a C# `get_X`/`set_X` accessor is a method to the caller, while the XML documents the
-  underlying member as a property or indexer. For accessor-rewritten candidates the
-  `method` filter now also admits properties, and the result note says so. Found by an
-  agent under a stress test that filtered its doc query to methods. Two benchmark probes
-  added (the widening plus a real-method control).
-
-Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
-restart Revit).
-
-## [0.2.15] - 2026-08-21
-
-### Fixed
-- `set_parameters`: the "parameter not found" error now mentions that display names are
-  localized and points to the language-independent BuiltInParameter enum name — the same
-  guidance `get_element_details` and `get_elements` already give. Previously it only
-  suggested the type-parameter cause, which sent the caller down the wrong path in
-  non-English UIs.
-- `get_elements`: the "filter parameter not found on any probed element" warning now
-  appears only when the query returned zero matches — that is where it distinguishes
-  "unknown parameter name" from "no matching elements". Next to real matches it was noise
-  (an unscoped query's probe window can simply miss the elements that carry the parameter).
-
-Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
-restart Revit).
-
-## [0.2.14] - 2026-08-21
-
-### Fixed
-- `get_elements`: text filter rules now compare case-insensitively on the post-scan path,
-  matching Revit's own collector rules (which ignore case -- verified empirically). The
-  same string rule previously matched case-insensitively when it ran inside the collector
-  but case-sensitively when it fell back to the per-element scan, so merely scoping a
-  query could change its results.
-- `search_api_docs`: queries in C# accessor spelling -- `Element.get_Parameter(BuiltInParameter)`,
-  `get_BoundingBox(View` -- now resolve to the documented property or indexer
-  (`Element.Parameter`, `Element.BoundingBox`), with a note explaining the rewrite. Members
-  documented with a literal `get_`/`set_` prefix still match directly; the rewrite is only
-  a fallback. Three benchmark probes added.
-
-Also investigated and cleared, no change needed: `Element.BoundingBox` and
-`LocationCurve.Curve` document null returns -- not exceptions -- for elements without
-geometry, so the suspected one-bad-element batch failure in `get_element_details` does
-not exist per the API contract.
-
-Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
-restart Revit).
-
-## [0.2.13] - 2026-08-21
-
-### Fixed
-- `get_elements`: a display-name filter rule that matches no parameter on any probed
-  in-scope element now carries an explicit WARNING in the result (content text and a
-  `warnings` payload field) instead of silently reporting 0 matches. The typical trap:
-  querying an English display name against a non-English UI, where the same parameter
-  carries a translated name -- the query looked valid and the honest answer was "unknown
-  parameter", not "0 matches". The warning points to the language-independent
-  BuiltInParameter enum name as the fix.
-- `get_elements`: a filter value that does not fit the parameter's storage type now fails
-  the same way regardless of scoping. Previously the identical query reported a clear error
-  when `category`/`of_class` was set (the rule ran inside Revit's collector) but silently
-  returned zero matches when it was not (the rule fell back to the per-element scan).
-- `execute_csharp`: a script that ran successfully but returned a value the result
-  serializer could not walk — a lazy sequence over a deleted element, a property that
-  throws — was rolled back and reported as "C# script threw". The script's changes now
-  commit, `returnValue` explains what happened, and `returnValueError` carries the detail.
-- `capture_view`: every snapshot stayed on disk forever (measured on one machine: 138
-  files, 28 MB, going back 15 months). Captures now go to `%LOCALAPPDATA%\pi-revit\captures`
-  and each capture sweeps the ones older than 24 hours. The folder had to become a fixed
-  one: `Path.GetTempPath()` can return a fresh per-session directory, so files left by
-  earlier sessions were unreachable from the current one. The file just produced is
-  untouched, so the read tool still finds it.
-- `export_documents`: the produced-file list compared pre-existing files against a wall
-  clock window, so an untouched file that merely happened to be recent was reported as
-  exported. Each file is now compared against its own pre-export timestamp.
-- The bridge reclaims `bridge.json` when its owner goes away. With two Revits open the
-  newer one still owns the file, but closing it no longer leaves the older, still-running
-  bridge undiscoverable — and a stale entry left by a crashed Revit is replaced within 30s
-  instead of failing every call with "could not reach the Revit bridge".
-
-### Changed
-- `scripts/deploy.ps1` replaces the add-in folder instead of copying over it, so files from
-  a previous release cannot linger next to the new ones. It reports clearly if Revit is
-  still running and holding the folder.
-- Docs: `open_view` was missing from the README tool table; the 0.2.10-0.2.12 changelog
-  entries were dated a day after their actual release.
-
-Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
-restart Revit).
-
-## [0.2.12] - 2026-07-21
-
-### Added
-- New tool `open_view`: activates a view or sheet in the Revit UI — the equivalent of
-  double-clicking it in the Project Browser. Identify the target by `view_id` or by
-  `name` (view name, sheet number like "A-101", or "number - name"). Uses Revit's
-  queued `RequestViewChange`, which is explicitly legal from the bridge's ExternalEvent
-  context; the activation completes the instant the call returns. Ends the
-  "please double-click the sheet yourself" gap after sheet/view creation.
-
-Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
-restart Revit).
-
-## [0.2.11] - 2026-07-21
-
-### Fixed
-- `search_api_docs`: signature queries now accept .NET type names and qualified names —
-  `Wall.Create(Document, Curve, ElementId, Boolean` and `...(System.String` match the
-  rendered `bool` / `string`, and `(Autodesk.Revit.DB.Document` matches `Document`.
-  Parameter types in the query are reduced exactly the way the index renders them
-  (namespace stripped, CLR name → C# keyword, case-insensitive).
-- `search_api_docs`: Creation-factory calls resolve — `Document.Create.NewRoom(Level, UV`
-  finds `Document.NewRoom`, and `Document.Create.NewFamilyInstance` finds the
-  `ItemFactoryBase` overloads (factory members documented on a base class). A note in the
-  result explains the rewrite. Applies only to the literal `Document.Create.` /
-  `Application.Create.` prefixes; ordinary members like `Wall.Create` are untouched, and
-  nonsense like `Document.Create.Banana` still honestly returns nothing.
-
-Both were observed live: pi stumbled on these five times across two modeling sessions.
-The benchmark gained six regression probes for them.
-
-Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
-restart Revit).
-
-## [0.2.10] - 2026-07-21
-
-### Fixed
-- `search_api_docs`: constructor overloads can now be targeted with the natural C#
-  spelling — `FilteredElementCollector(Document` matches even though constructors are
-  rendered as `new FilteredElementCollector(Document)`. Previously only the `new `-prefixed
-  form matched (the same typography-cliff family as the 0.2.8 comma-spacing fix).
-
-### Added
-- `scripts/benchmark-search-docs.py`: a reproducible ~630-query benchmark of
-  `search_api_docs` scored against Autodesk's own RevitAPI.xml — exact-name recall,
-  signature/spacing variants, hard syntax, namespace ambiguity, adversarial honesty
-  controls, documentation fidelity, and latency percentiles. Run it against any Revit
-  version with the bridge loaded. Measured on Revit 2025 at 0.2.9: 100% recall / 98.8%
-  top-1 on exact names, 100% spacing-variant agreement, 0 false positives across 99
-  adversarial mutations, 50/50 correct parameter docs, p50 8 ms.
-
-Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
-restart Revit).
-
-## [0.2.9] - 2026-07-21
-
-### Added
-- Self-healing tool discovery: when pi starts before Revit, the extension now keeps
-  retrying tool discovery in the background (every 15s) and also re-discovers on a
-  successful `ping` — no more sessions stuck with only `ping` registered until a fresh
-  pi start. When tools arrive mid-session, `ping`'s result says so.
-- `set_parameters` and `execute_csharp` accept an optional `expected_document` (the model
-  title): if the active document differs — e.g. the user switched models mid-session —
-  the write fails cleanly instead of landing in the wrong model.
-- `get_element_details.parameter_names` now also matches language-independent
-  BuiltInParameter enum names (e.g. `ALL_MODEL_MARK`), so filtering works in non-English
-  Revit UIs where display names are localized.
-
-### Fixed
-- `get_element_details` no longer reports a misleading "0 params" when a
-  `parameter_names` filter simply matched nothing — it now reports "N of M params
-  matched parameter_names" so localization misses are visible. (This explains the
-  earlier "0 params vs 38 params" reports: different filter arguments, not flaky reads.)
-- `get_elements`: a display-name filter rule in an **unscoped** query (no category /
-  of_class) is no longer promoted to a pinned collector filter based on a 50-element
-  probe — it stays on the per-element post-scan path, so categories beyond the probe
-  window can't be silently dropped when the same parameter name maps to different ids.
-
-### Changed
-- SKILL.md: guidance on localized parameter names (prefer BuiltInParameter enum names)
-  and on using `expected_document` for long sessions / multiple open models.
-- README: new "Safety model" section stating explicitly what the add-in enforces and
-  that write-confirmation UX is a client-side decision.
-
-Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
-restart Revit).
-
-## [0.2.8] - 2026-07-21
-
-### Fixed
-- `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
-- Write transactions (`set_parameters`, `execute_csharp`, and the temporary-isolate
-  branch of `manage_selection`) now register a failures preprocessor. Previously Revit
-  handled commit failures interactively: warnings popped the transient toast and spammed
-  the journal, and an error-severity failure showed the modal resolution dialog, blocking
-  the bridge until a human clicked. Now warnings are auto-dismissed and reported back
-  (`commitWarnings` in the result, e.g. duplicate Mark values), and errors roll the
-  transaction back with the actual Revit failure text in the error message.
-
-### Changed
-- `set_parameters` tool description tells the model to relay `commitWarnings` to the user.
-
-Requires redeploying the Revit add-in (`scripts\deploy.ps1` + Revit restart).
-
-## [0.2.5] - 2026-07-20
-
-### Fixed
-- `execute_csharp` dialog guard no longer answers every Revit popup with OK. On some
-  dialogs OK is the destructive choice (e.g. "Delete Element(s)"), so a script could
-  silently delete dimensions or constraints and still report success. Unrecognized
-  dialogs are now answered dismissively (Cancel, then Close, then No; OK only as the
-  last resort so Revit can never hang behind a popup), a small allowlist keeps OK for
-  dialogs that are safe to confirm, and `suppressedDialogs` now reports which answer
-  was given (e.g. `TaskDialog_… (answered Cancel)`).
-
-### Changed
-- The `execute_csharp` tool description tells the model that confirmation prompts may be
-  cancelled and to check `suppressedDialogs` when a result looks incomplete.
-
-Requires redeploying the Revit add-in (`scripts\deploy.ps1` + Revit restart) — `ping`
-warns on a version mismatch until then.
-
-## [0.2.4] - 2026-07-20
-
-### Added
-- This changelog. It ships inside the npm package and gets a `## [x.y.z]` entry with
-  **Added / Changed / Fixed** sections for every release, so updates report what actually
-  changed instead of just a version number.
-
-## [0.2.3] - 2026-07-20
-
-### Changed
-- `search_api_docs`: results with the same short name in different namespaces are now
-  disambiguated with their full namespace, so `Category` vs internal schedule types
-  can't be confused.
-
-### Fixed
-- Removed a hardcoded example from the overload note that could mislead the model into
-  copying a signature that didn't apply.
-
-## [0.2.2] - 2026-07-20
-
-### Added
-- `search_api_docs`: exception documentation ("Throws:") is now shown for matched members.
-- Overload-targeted queries: a query containing `(` matches against rendered signatures.
-
-### Changed
-- Overloads now rank simplest-first (fewest parameters), so the common form appears on top.
-
-## [0.2.1] - 2026-07-16
-
-### Added
-- Extension/add-in version handshake: `ping` reports both versions and warns when the
-  npm extension and the installed Revit add-in are out of sync (partial-update detection).
-
-## [0.2.0] - 2026-07-15
-
-### Changed
-- SKILL.md: documents the top-match inline docs behaviour and the automatic
-  `Models\<title>\exports` output location so the agent uses them without prompting.
-
-## [0.1.9] - 2026-07-15
-
-### Added
-- `search_api_docs` indexes every Revit API enum and surfaces `<remarks>` documentation.
-
-### Changed
-- The top match's full documentation is placed directly in the tool's text output
-  (where model attention is strongest) instead of only in the structured payload.
-
-## [0.1.8] - 2026-07-13
-
-### Added
-- Automatic per-model output sorting: exports, captures, and scripts land under
-  `Models\<model title>\` in the workspace, keyed to the source document.
-
-## [0.1.7] - 2026-07-13
-
-### Fixed
-- npm-install uninstall flow no longer blocks itself on its own installation folder.
-
-## [0.1.6] - 2026-07-13
-
-### Changed
-- The global launcher installs next to the user's permanent pi under npx.
-
-## [0.1.5] - 2026-07-13
-
-### Fixed
-- Uninstall of the npm-installed Pi package.
-- Workspace paths containing non-ASCII characters.
-
-First version published to npm.
-
-## [0.1.0] - 2026-06-17
-
-Initial public release: Revit bridge add-in (Revit 2025/2026/2027) plus Pi extension with
-`ping`, `get_model_overview`, `get_elements`, `get_element_details`, `set_parameters`,
-`manage_selection`, `capture_view`, `export_documents`, `execute_csharp`, and
-`search_api_docs`.
+
+### Fixed
+- When pi starts before Revit and the background rediscovery timer (rather than a `ping`
+  call) registers the bridge tools, the session is now told — the same announcement the
+  ping path has always given. Previously the tools appeared silently in the next system
+  prompt while nothing contradicted the session's earlier "Revit is not running", so the
+  agent could stay needlessly pessimistic. The note is queued for the next user prompt
+  and never interrupts. Extension-only change; the Revit add-in is unchanged (the
+  standard installer keeps both versions aligned).
+
+## [0.2.17] - 2026-08-21
+
+### Fixed
+- The bridge's no-document check no longer counts linked documents. With only links
+  loaded, Revit does not pump the bridge's work queue, so a call could wait out its full
+  timeout instead of failing immediately with the clean "no active document" answer.
+
+### Changed
+- Docs and tool descriptions describe localized parameter names generically instead of
+  quoting specific languages.
+- The full search_api_docs benchmark (641 live queries against RevitAPI.xml ground truth)
+  was re-run on Revit 2025 at 0.2.16: 100% recall, 98.75% top-1 on exact names, 100%
+  spacing-variant agreement, 0 false positives across 99 adversarial mutations, 50/50
+  parameter docs, p50 10 ms -- no regression across the 0.2.13-0.2.16 search changes.
+
+Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
+restart Revit).
+
+## [0.2.16] - 2026-08-21
+
+### Fixed
+- `search_api_docs`: an accessor-spelling query combined with `kind: "method"` — e.g.
+  `Element.get_Parameter(BuiltInParameter)` filtered to methods — returned "no matches",
+  because the accessor rewrite found the documented member but the kind filter rejected it:
+  a C# `get_X`/`set_X` accessor is a method to the caller, while the XML documents the
+  underlying member as a property or indexer. For accessor-rewritten candidates the
+  `method` filter now also admits properties, and the result note says so. Found by an
+  agent under a stress test that filtered its doc query to methods. Two benchmark probes
+  added (the widening plus a real-method control).
+
+Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
+restart Revit).
+
+## [0.2.15] - 2026-08-21
+
+### Fixed
+- `set_parameters`: the "parameter not found" error now mentions that display names are
+  localized and points to the language-independent BuiltInParameter enum name — the same
+  guidance `get_element_details` and `get_elements` already give. Previously it only
+  suggested the type-parameter cause, which sent the caller down the wrong path in
+  non-English UIs.
+- `get_elements`: the "filter parameter not found on any probed element" warning now
+  appears only when the query returned zero matches — that is where it distinguishes
+  "unknown parameter name" from "no matching elements". Next to real matches it was noise
+  (an unscoped query's probe window can simply miss the elements that carry the parameter).
+
+Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
+restart Revit).
+
+## [0.2.14] - 2026-08-21
+
+### Fixed
+- `get_elements`: text filter rules now compare case-insensitively on the post-scan path,
+  matching Revit's own collector rules (which ignore case -- verified empirically). The
+  same string rule previously matched case-insensitively when it ran inside the collector
+  but case-sensitively when it fell back to the per-element scan, so merely scoping a
+  query could change its results.
+- `search_api_docs`: queries in C# accessor spelling -- `Element.get_Parameter(BuiltInParameter)`,
+  `get_BoundingBox(View` -- now resolve to the documented property or indexer
+  (`Element.Parameter`, `Element.BoundingBox`), with a note explaining the rewrite. Members
+  documented with a literal `get_`/`set_` prefix still match directly; the rewrite is only
+  a fallback. Three benchmark probes added.
+
+Also investigated and cleared, no change needed: `Element.BoundingBox` and
+`LocationCurve.Curve` document null returns -- not exceptions -- for elements without
+geometry, so the suspected one-bad-element batch failure in `get_element_details` does
+not exist per the API contract.
+
+Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
+restart Revit).
+
+## [0.2.13] - 2026-08-21
+
+### Fixed
+- `get_elements`: a display-name filter rule that matches no parameter on any probed
+  in-scope element now carries an explicit WARNING in the result (content text and a
+  `warnings` payload field) instead of silently reporting 0 matches. The typical trap:
+  querying an English display name against a non-English UI, where the same parameter
+  carries a translated name -- the query looked valid and the honest answer was "unknown
+  parameter", not "0 matches". The warning points to the language-independent
+  BuiltInParameter enum name as the fix.
+- `get_elements`: a filter value that does not fit the parameter's storage type now fails
+  the same way regardless of scoping. Previously the identical query reported a clear error
+  when `category`/`of_class` was set (the rule ran inside Revit's collector) but silently
+  returned zero matches when it was not (the rule fell back to the per-element scan).
+- `execute_csharp`: a script that ran successfully but returned a value the result
+  serializer could not walk — a lazy sequence over a deleted element, a property that
+  throws — was rolled back and reported as "C# script threw". The script's changes now
+  commit, `returnValue` explains what happened, and `returnValueError` carries the detail.
+- `capture_view`: every snapshot stayed on disk forever (measured on one machine: 138
+  files, 28 MB, going back 15 months). Captures now go to `%LOCALAPPDATA%\pi-revit\captures`
+  and each capture sweeps the ones older than 24 hours. The folder had to become a fixed
+  one: `Path.GetTempPath()` can return a fresh per-session directory, so files left by
+  earlier sessions were unreachable from the current one. The file just produced is
+  untouched, so the read tool still finds it.
+- `export_documents`: the produced-file list compared pre-existing files against a wall
+  clock window, so an untouched file that merely happened to be recent was reported as
+  exported. Each file is now compared against its own pre-export timestamp.
+- The bridge reclaims `bridge.json` when its owner goes away. With two Revits open the
+  newer one still owns the file, but closing it no longer leaves the older, still-running
+  bridge undiscoverable — and a stale entry left by a crashed Revit is replaced within 30s
+  instead of failing every call with "could not reach the Revit bridge".
+
+### Changed
+- `scripts/deploy.ps1` replaces the add-in folder instead of copying over it, so files from
+  a previous release cannot linger next to the new ones. It reports clearly if Revit is
+  still running and holding the folder.
+- Docs: `open_view` was missing from the README tool table; the 0.2.10-0.2.12 changelog
+  entries were dated a day after their actual release.
+
+Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
+restart Revit).
+
+## [0.2.12] - 2026-07-21
+
+### Added
+- New tool `open_view`: activates a view or sheet in the Revit UI — the equivalent of
+  double-clicking it in the Project Browser. Identify the target by `view_id` or by
+  `name` (view name, sheet number like "A-101", or "number - name"). Uses Revit's
+  queued `RequestViewChange`, which is explicitly legal from the bridge's ExternalEvent
+  context; the activation completes the instant the call returns. Ends the
+  "please double-click the sheet yourself" gap after sheet/view creation.
+
+Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
+restart Revit).
+
+## [0.2.11] - 2026-07-21
+
+### Fixed
+- `search_api_docs`: signature queries now accept .NET type names and qualified names —
+  `Wall.Create(Document, Curve, ElementId, Boolean` and `...(System.String` match the
+  rendered `bool` / `string`, and `(Autodesk.Revit.DB.Document` matches `Document`.
+  Parameter types in the query are reduced exactly the way the index renders them
+  (namespace stripped, CLR name → C# keyword, case-insensitive).
+- `search_api_docs`: Creation-factory calls resolve — `Document.Create.NewRoom(Level, UV`
+  finds `Document.NewRoom`, and `Document.Create.NewFamilyInstance` finds the
+  `ItemFactoryBase` overloads (factory members documented on a base class). A note in the
+  result explains the rewrite. Applies only to the literal `Document.Create.` /
+  `Application.Create.` prefixes; ordinary members like `Wall.Create` are untouched, and
+  nonsense like `Document.Create.Banana` still honestly returns nothing.
+
+Both were observed live: pi stumbled on these five times across two modeling sessions.
+The benchmark gained six regression probes for them.
+
+Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
+restart Revit).
+
+## [0.2.10] - 2026-07-21
+
+### Fixed
+- `search_api_docs`: constructor overloads can now be targeted with the natural C#
+  spelling — `FilteredElementCollector(Document` matches even though constructors are
+  rendered as `new FilteredElementCollector(Document)`. Previously only the `new `-prefixed
+  form matched (the same typography-cliff family as the 0.2.8 comma-spacing fix).
+
+### Added
+- `scripts/benchmark-search-docs.py`: a reproducible ~630-query benchmark of
+  `search_api_docs` scored against Autodesk's own RevitAPI.xml — exact-name recall,
+  signature/spacing variants, hard syntax, namespace ambiguity, adversarial honesty
+  controls, documentation fidelity, and latency percentiles. Run it against any Revit
+  version with the bridge loaded. Measured on Revit 2025 at 0.2.9: 100% recall / 98.8%
+  top-1 on exact names, 100% spacing-variant agreement, 0 false positives across 99
+  adversarial mutations, 50/50 correct parameter docs, p50 8 ms.
+
+Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
+restart Revit).
+
+## [0.2.9] - 2026-07-21
+
+### Added
+- Self-healing tool discovery: when pi starts before Revit, the extension now keeps
+  retrying tool discovery in the background (every 15s) and also re-discovers on a
+  successful `ping` — no more sessions stuck with only `ping` registered until a fresh
+  pi start. When tools arrive mid-session, `ping`'s result says so.
+- `set_parameters` and `execute_csharp` accept an optional `expected_document` (the model
+  title): if the active document differs — e.g. the user switched models mid-session —
+  the write fails cleanly instead of landing in the wrong model.
+- `get_element_details.parameter_names` now also matches language-independent
+  BuiltInParameter enum names (e.g. `ALL_MODEL_MARK`), so filtering works in non-English
+  Revit UIs where display names are localized.
+
+### Fixed
+- `get_element_details` no longer reports a misleading "0 params" when a
+  `parameter_names` filter simply matched nothing — it now reports "N of M params
+  matched parameter_names" so localization misses are visible. (This explains the
+  earlier "0 params vs 38 params" reports: different filter arguments, not flaky reads.)
+- `get_elements`: a display-name filter rule in an **unscoped** query (no category /
+  of_class) is no longer promoted to a pinned collector filter based on a 50-element
+  probe — it stays on the per-element post-scan path, so categories beyond the probe
+  window can't be silently dropped when the same parameter name maps to different ids.
+
+### Changed
+- SKILL.md: guidance on localized parameter names (prefer BuiltInParameter enum names)
+  and on using `expected_document` for long sessions / multiple open models.
+- README: new "Safety model" section stating explicitly what the add-in enforces and
+  that write-confirmation UX is a client-side decision.
+
+Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
+restart Revit).
+
+## [0.2.8] - 2026-07-21
+
+### Fixed
+- `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
+- Write transactions (`set_parameters`, `execute_csharp`, and the temporary-isolate
+  branch of `manage_selection`) now register a failures preprocessor. Previously Revit
+  handled commit failures interactively: warnings popped the transient toast and spammed
+  the journal, and an error-severity failure showed the modal resolution dialog, blocking
+  the bridge until a human clicked. Now warnings are auto-dismissed and reported back
+  (`commitWarnings` in the result, e.g. duplicate Mark values), and errors roll the
+  transaction back with the actual Revit failure text in the error message.
+
+### Changed
+- `set_parameters` tool description tells the model to relay `commitWarnings` to the user.
+
+Requires redeploying the Revit add-in (`scripts\deploy.ps1` + Revit restart).
+
+## [0.2.5] - 2026-07-20
+
+### Fixed
+- `execute_csharp` dialog guard no longer answers every Revit popup with OK. On some
+  dialogs OK is the destructive choice (e.g. "Delete Element(s)"), so a script could
+  silently delete dimensions or constraints and still report success. Unrecognized
+  dialogs are now answered dismissively (Cancel, then Close, then No; OK only as the
+  last resort so Revit can never hang behind a popup), a small allowlist keeps OK for
+  dialogs that are safe to confirm, and `suppressedDialogs` now reports which answer
+  was given (e.g. `TaskDialog_… (answered Cancel)`).
+
+### Changed
+- The `execute_csharp` tool description tells the model that confirmation prompts may be
+  cancelled and to check `suppressedDialogs` when a result looks incomplete.
+
+Requires redeploying the Revit add-in (`scripts\deploy.ps1` + Revit restart) — `ping`
+warns on a version mismatch until then.
+
+## [0.2.4] - 2026-07-20
+
+### Added
+- This changelog. It ships inside the npm package and gets a `## [x.y.z]` entry with
+  **Added / Changed / Fixed** sections for every release, so updates report what actually
+  changed instead of just a version number.
+
+## [0.2.3] - 2026-07-20
+
+### Changed
+- `search_api_docs`: results with the same short name in different namespaces are now
+  disambiguated with their full namespace, so `Category` vs internal schedule types
+  can't be confused.
+
+### Fixed
+- Removed a hardcoded example from the overload note that could mislead the model into
+  copying a signature that didn't apply.
+
+## [0.2.2] - 2026-07-20
+
+### Added
+- `search_api_docs`: exception documentation ("Throws:") is now shown for matched members.
+- Overload-targeted queries: a query containing `(` matches against rendered signatures.
+
+### Changed
+- Overloads now rank simplest-first (fewest parameters), so the common form appears on top.
+
+## [0.2.1] - 2026-07-16
+
+### Added
+- Extension/add-in version handshake: `ping` reports both versions and warns when the
+  npm extension and the installed Revit add-in are out of sync (partial-update detection).
+
+## [0.2.0] - 2026-07-15
+
+### Changed
+- SKILL.md: documents the top-match inline docs behaviour and the automatic
+  `Models\<title>\exports` output location so the agent uses them without prompting.
+
+## [0.1.9] - 2026-07-15
+
+### Added
+- `search_api_docs` indexes every Revit API enum and surfaces `<remarks>` documentation.
+
+### Changed
+- The top match's full documentation is placed directly in the tool's text output
+  (where model attention is strongest) instead of only in the structured payload.
+
+## [0.1.8] - 2026-07-13
+
+### Added
+- Automatic per-model output sorting: exports, captures, and scripts land under
+  `Models\<model title>\` in the workspace, keyed to the source document.
+
+## [0.1.7] - 2026-07-13
+
+### Fixed
+- npm-install uninstall flow no longer blocks itself on its own installation folder.
+
+## [0.1.6] - 2026-07-13
+
+### Changed
+- The global launcher installs next to the user's permanent pi under npx.
+
+## [0.1.5] - 2026-07-13
+
+### Fixed
+- Uninstall of the npm-installed Pi package.
+- Workspace paths containing non-ASCII characters.
+
+First version published to npm.
+
+## [0.1.0] - 2026-06-17
+
+Initial public release: Revit bridge add-in (Revit 2025/2026/2027) plus Pi extension with
+`ping`, `get_model_overview`, `get_elements`, `get_element_details`, `set_parameters`,
+`manage_selection`, `capture_view`, `export_documents`, `execute_csharp`, and
+`search_api_docs`.