pi-revit 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -1,465 +1,483 @@
-# 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.5.0] - 2026-09-29
-
-### Added
-
-- Every tool now declares what it does not cover and what to use instead (another tool, specific Revit API members, a user action, or "the Revit API does not offer it" with evidence). `find_revit_tools` shows these limits. When nothing matches, it states the remaining route (API search, then custom code) instead of returning an empty list, so PI-Revit no longer treats "no dedicated tool" as "impossible".
-- One always-present PI-Revit protocol for every tool. It covers checking capability before saying no, doing only what was asked, verifying with the tool's declared method and then stopping and reporting, naming evidence, document identity, and replying in the user's language while searching in English.
-- A completion check. When the same verification is repeated after further edits, PI-Revit asks the agent to compare against the request, stop and report, and offer extras as suggestions.
-- `ping` reports what is actually loaded: extension package, guidance revision, source revision, and whether each tool's manual matches the connected bridge's exact contract.
-- `find_revit_tools` also returns matching workflows, shared guides and skills, including subject skills added to the package later.
-- `manage_sheet_placements` list reports per-kind counts. The titleblock's own revision schedule has its own kind and cannot be moved, so "which sheets have nothing placed?" is answered correctly. Special objects (revision schedules, templates, placeholder sheets, dependent views, group and design-option members, pinned elements) carry `traits` in element listings.
-- Every model-changing call reports `model_changes`: the objects it added, modified and deleted, and for new views their hidden categories and elements. This includes custom C# scripts, so a view duplicated in a script shows what it inherited.
-- Duplicating a view, copying elements and changing types report `inherited_state`: hidden categories and elements, filters, overrides, template and carried values such as Mark or Comments. The agent checks it against the request instead of trusting an image.
-- Objects that existed before a request are protected from silent reuse. A name that another view, schedule, level, grid, type, material or filter already uses (or a sheet number already taken) is rejected with the existing object's ID. When a call changes a pre-existing object the request names, PI-Revit adds a note, and the protocol requires asking the user or reporting it.
-- `search_api_docs` verifies several API members in one call (names separated by `;`). Each API limit shown by `find_revit_tools` and in the manuals carries a ready one-call lookup.
-- Contributor platform: contracts generated from code into manuals and the tool index, a register of every "never/must" rule with its enforcing test, a discovery quality corpus, a prompt-size budget, architecture gates, and a repeatable agent-evaluation suite (`tests/agent-eval`).
-- One focused manual for each public PI-Revit tool, shared execution/recovery/visual guidance, and explicit explanation, inspection and modification paths in the skill and workflows.
-- Offline manual lookup through `find_revit_tools` with `scope: "documentation"`, plus local manual paths, registration/activation state and version evidence in discovery results.
-- Contributor `AGENTS.md`, architecture/ownership documentation, and offline checks that compare manual examples with the actual public input schemas.
-
-### Changed
-
-- A display-name parameter that matches several parameters on one element is no longer resolved to an arbitrary one. Writes and filters fail with the exact candidate identities, and projections flag the ambiguity.
-- An `is_empty` filter on a parameter that was not found keeps its warning even when elements match, because missing parameters also count as empty.
-- Manual compatibility is an exact per-tool contract comparison (`contract_match`, `contract_changed`, `undocumented`, `unknown`) instead of a version-number match; rewording documentation never flags a bridge.
-- The completion check counts only calls that actually changed the model (from `model_changes`), so a read-only script no longer counts as an edit.
-- Tool search uses English task vocabulary with word-form matching, input names and declared limits. Requests in other languages are translated by the model rather than by language tables.
-- Prompt guidance per tool is shorter: identity, manual location and protocol rules appear once instead of once per tool. `expected_document_id` descriptions now agree with whether the schema requires it.
-- The entry skill routes to relevant references instead of carrying every tool's detailed contract. Installation history remains in the README/change log.
-- `find_revit_tools` includes the six Pi-side utilities alongside the selected bridge catalogue. Native utilities remain discoverable when the bridge is unavailable; bridge availability is identified as a discovery snapshot.
-
-### Fixed
-
-- Advanced tool registration preserves its prompt snippet and guidelines so Pi can use them after activation. Tool guidance also links the matching local manual.
-- Tool search retains packaged summary terms after connecting to Revit, so searches such as `warnings` continue to find the relevant manual and available tool.
-
-## [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
-
-- `read_revit_result` retrieves complete large tool results in bounded fragments.
-  Result IDs belong to the current Pi extension session; saved files remain
-  readable by path while available.
-
-### Changed
-
-- **Breaking:** writes and UI mutations require `expected_document_id` from
-  `get_model_overview`'s `project.documentId`. Refresh it after close/reopen or
-  bridge restart. A legacy title alone is insufficient; supplied IDs on reads
-  are also checked.
-- Default export folders include a model-identity hash, separating same-title
-  models. Existing folders remain untouched; explicit output directories work
-  as before.
-
-### Fixed
-
-- Requested values and all returned rows reach Pi instead of only UI/debug
-  details. Large-result retrieval preserves each tool's pagination and limits.
-- Scoped display-name filters resolve each element's parameter, including
-  matches beyond the first 50 elements; explicit built-in/GUID filters stay optimized.
-- Type-only parameter requests work independently of instance-parameter inclusion.
-- Transaction results distinguish confirmed commit/rollback from incomplete
-  cleanup. Failure handling follows the transaction lifecycle; UI and export
-  errors disclose effects or files already produced.
-
-Update both the Pi package and Revit add-in with Revit closed, then restart Revit
-and start a fresh Pi session. Live verification covered bounded workflows on
-Revit 2025.4.3; Revit 2026/2027 were not tested for this release.
-
-## [0.2.18] - 2026-08-21
-
-### Fixed
-- When pi starts before Revit and the background rediscovery timer (rather than a `ping`
-  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`.
+# 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.5.2] - 2026-10-01
+
+### Changed
+
+- The public repository and npm package contain the reusable tools, installation scripts and user documentation. Testing infrastructure, contributor tooling and detailed evaluation history are maintained separately.
+- npm packaging uses a focused file allowlist. The bridge source, generated contracts, all tool manuals and workspace templates remain included.
+- Repository ignore rules protect local Revit files, evaluation fixtures and output, credentials, runtime discovery records and diagnostics from accidental commits.
+- The architecture guide describes the distributed runtime and its contracts. Revit tool behavior is unchanged.
+
+## [0.5.1] - 2026-09-29
+
+### Changed
+
+- README describes the 0.5.0 tools: a "Works in" column (project, family or both) in the tool table, family documents, `model_changes`, `inherited_state`, `name_collision`, scope notes, multi-member `search_api_docs` lookups, and what 0.5.0 was actually tested on. No tool behavior changed; redeploy the add-in so its version matches the package.
+
+## [0.5.0] - 2026-09-29
+
+### Added
+
+- Family documents: every tool declares which document kinds it works in. Ten tools are project-only (sheets, sheet placements, schedules, tags, spatial query, links, coordinates) and refuse a family document before running, with the route to use instead. `get_model_overview` reports `documentKind` and, for a family, its category, current type, type names and parameters. In a family, `model_changes` also lists types and parameters added, removed or changed.
+- Scope notes match the names a request mentions in any writing system; there are no per-language rules.
+
+- Every tool now declares what it does not cover and what to use instead (another tool, specific Revit API members, a user action, or "the Revit API does not offer it" with evidence). `find_revit_tools` shows these limits. When nothing matches, it states the remaining route (API search, then custom code) instead of returning an empty list, so PI-Revit no longer treats "no dedicated tool" as "impossible".
+- One always-present PI-Revit protocol for every tool. It covers checking capability before saying no, doing only what was asked, verifying with the tool's declared method and then stopping and reporting, naming evidence, document identity, and replying in the user's language while searching in English.
+- A completion check. When the same verification is repeated after further edits, PI-Revit asks the agent to compare against the request, stop and report, and offer extras as suggestions.
+- `ping` reports what is actually loaded: extension package, guidance revision, source revision, and whether each tool's manual matches the connected bridge's exact contract.
+- `find_revit_tools` also returns matching workflows, shared guides and skills, including subject skills added to the package later.
+- `manage_sheet_placements` list reports per-kind counts. The titleblock's own revision schedule has its own kind and cannot be moved, so "which sheets have nothing placed?" is answered correctly. Special objects (revision schedules, templates, placeholder sheets, dependent views, group and design-option members, pinned elements) carry `traits` in element listings.
+- Every model-changing call reports `model_changes`: the objects it added, modified and deleted, and for new views their hidden categories and elements. This includes custom C# scripts, so a view duplicated in a script shows what it inherited.
+- Duplicating a view, copying elements, changing types and tagging report `inherited_state`: hidden categories and elements, filters, overrides, template and carried values such as Mark or Comments. The agent checks it against the request instead of trusting an image.
+- Objects that existed before a request are protected from silent reuse. A name that another view, schedule, level, grid, type, material, filter or family type already uses (or a sheet number already taken) is rejected with the existing object's ID. When a call changes a pre-existing object the request names, PI-Revit adds a note, and the protocol requires asking the user or reporting it.
+- `search_api_docs` verifies several API members in one call (names separated by `;`). Each API limit shown by `find_revit_tools` and in the manuals carries a ready one-call lookup.
+- Tool contracts and the tool index are generated from code; documentation and discovery behavior are validated before release.
+- One focused manual for each public PI-Revit tool, shared execution/recovery/visual guidance, and explicit explanation, inspection and modification paths in the skill and workflows.
+- Offline manual lookup through `find_revit_tools` with `scope: "documentation"`, plus local manual paths, registration/activation state and version evidence in discovery results.
+- Architecture documentation and validated manual examples that match the public input schemas.
+
+### Changed
+
+- A display-name parameter that matches several parameters on one element is no longer resolved to an arbitrary one. Writes and filters fail with the exact candidate identities, and projections flag the ambiguity.
+- An `is_empty` filter on a parameter that was not found keeps its warning even when elements match, because missing parameters also count as empty.
+- Manual compatibility is an exact per-tool contract comparison (`contract_match`, `contract_changed`, `undocumented`, `unknown`) instead of a version-number match; rewording documentation never flags a bridge.
+- The completion check counts only calls that actually changed the model (from `model_changes`), so a read-only script no longer counts as an edit.
+- Tool search uses English task vocabulary with word-form matching, input names and declared limits. Requests in other languages are translated by the model rather than by language tables.
+- Prompt guidance per tool is shorter: identity, manual location and protocol rules appear once instead of once per tool. `expected_document_id` descriptions now agree with whether the schema requires it.
+- The entry skill routes to relevant references instead of carrying every tool's detailed contract. Installation history remains in the README/change log.
+- `find_revit_tools` includes the six Pi-side utilities alongside the selected bridge catalogue. Native utilities remain discoverable when the bridge is unavailable; bridge availability is identified as a discovery snapshot.
+
+### Fixed
+
+- Advanced tool registration preserves its prompt snippet and guidelines so Pi can use them after activation. Tool guidance also links the matching local manual.
+- Tool search retains packaged summary terms after connecting to Revit, so searches such as `warnings` continue to find the relevant manual and available tool.
+
+## [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
+
+- `read_revit_result` retrieves complete large tool results in bounded fragments.
+  Result IDs belong to the current Pi extension session; saved files remain
+  readable by path while available.
+
+### Changed
+
+- **Breaking:** writes and UI mutations require `expected_document_id` from
+  `get_model_overview`'s `project.documentId`. Refresh it after close/reopen or
+  bridge restart. A legacy title alone is insufficient; supplied IDs on reads
+  are also checked.
+- Default export folders include a model-identity hash, separating same-title
+  models. Existing folders remain untouched; explicit output directories work
+  as before.
+
+### Fixed
+
+- Requested values and all returned rows reach Pi instead of only UI/debug
+  details. Large-result retrieval preserves each tool's pagination and limits.
+- Scoped display-name filters resolve each element's parameter, including
+  matches beyond the first 50 elements; explicit built-in/GUID filters stay optimized.
+- Type-only parameter requests work independently of instance-parameter inclusion.
+- Transaction results distinguish confirmed commit/rollback from incomplete
+  cleanup. Failure handling follows the transaction lifecycle; UI and export
+  errors disclose effects or files already produced.
+
+Update both the Pi package and Revit add-in with Revit closed, then restart Revit
+and start a fresh Pi session. Live verification covered bounded workflows on
+Revit 2025.4.3; Revit 2026/2027 were not tested for this release.
+
+## [0.2.18] - 2026-08-21
+
+### Fixed
+- When pi starts before Revit and the background rediscovery timer (rather than a `ping`
+  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`.