# 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.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`.