pi-revit 0.4.0 → 0.5.0

package/skills/pi-revit/references/tools/measure_geometry.md

@@ -0,0 +1,71 @@
+# measure_geometry
+
+## Purpose and preconditions
+
+Measure exact distance between explicitly supplied points or approximate separation of two host elements' model bounding boxes. Activate with `find_revit_tools`; both modes require an active document. Linked contents are not traversed. Choose a mode that answers the question without overstating what was measured.
+
+<!-- generated:contract:start (npm run generate:contracts; do not edit this block) -->
+## Contract (generated)
+
+- **Source:** bridge tool, advanced tier: activate it with `find_revit_tools`.
+- **Writes model:** no. **Effects:** none. **Requires an open document:** yes.
+- **Works in:** project and family documents.
+- **Contract hash:** `34cc9bf1c26888bd`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `mode` | string | yes |  | `point_distance`, `bounding_box_gap` |
+| `unit` | string | yes |  | `millimeters`, `centimeters`, `meters`, `feet`, `inches` |
+| `point_a` | array of number | no |  |  |
+| `point_b` | array of number | no |  |  |
+| `element_a_id` | integer | no |  |  |
+| `element_b_id` | integer | no |  |  |
+| `clearance` | number | no |  |  |
+| `expected_document_id` | string | no |  |  |
+
+Bridge calls also accept `_operation_id`, only to retry an identical earlier request (see [operation recovery](../operation-recovery.md)).
+
+| Not covered by this tool | Use instead |
+| --- | --- |
+| Exact solid-to-solid distance or clash detection | Revit API: ElementIntersectsElementFilter; ElementIntersectsSolidFilter; ReferenceIntersector. Check all its members in one call: `search_api_docs` with query `ElementIntersectsElementFilter; ElementIntersectsSolidFilter; ReferenceIntersector`, then use `execute_csharp` within the requested scope. |
+<!-- generated:contract:end -->
+
+## Public inputs
+
+- Required `mode`: `point_distance` or `bounding_box_gap`.
+- Required `unit`: `millimeters`, `centimeters`, `meters`, `feet`, or `inches`; applies to point inputs, clearance threshold, and all returned coordinates/distances.
+- Point mode requires `point_a` and `point_b`, each three finite coordinates in document internal axes. Omit both element IDs and `clearance` entirely.
+- Box mode requires positive integer `element_a_id` and `element_b_id` in the host; omit point arguments. Optional `clearance` is a finite nonnegative box-proximity threshold in the selected unit.
+- Optional `expected_document_id`: exact read guard. Optional `_operation_id`: exact previous ID for identical retry only.
+
+## Examples
+
+The supplied points are illustrative; the result measures those points, not any implied element surfaces.
+
+```json
+{ "mode": "point_distance", "unit": "meters", "point_a": [0, 0, 0], "point_b": [3, 4, 0] }
+```
+
+Replace these illustrative IDs with two discovered host elements:
+
+```json
+{ "mode": "bounding_box_gap", "unit": "millimeters", "element_a_id": 12345, "element_b_id": 12346, "clearance": 100 }
+```
+
+## Results and verification
+
+Point mode returns `approximate: false`, exact Euclidean `distance`, signed `delta` from A to B, both input points, coordinate frame, and unit. Exactness applies to the given points, not to how those points were chosen.
+
+Box mode returns `approximate: true`, `distance`, nonnegative `axis_gaps`, element identities/bounds, `boxes_overlap_or_touch`, and the optional threshold classification. `box_gap_below_clearance` uses strict less-than; equality does not pass it. `boxes_overlap_or_touch` includes contact. There is no pagination.
+
+A box gap is only a lower bound on physical geometry separation; boxes can include nonphysical geometry. Zero gap means enclosing boxes touch/overlap, not that solids clash. A threshold hit identifies a candidate for further review, not a verified clearance violation. Preserve the result's method and approximation labels. A missing model box fails the whole measurement rather than treating it as zero distance.
+
+Verify units, frame, element identities, and intended measurement meaning. Use exact geometry investigation for claims requiring actual surfaces. See [execution rules](../execution-rules.md) for document/result handling and [visual verification](../visual-verification.md) if the wider task produces visible changes.
+
+## Effects and recovery
+
+Read-only: no geometry edits, dimensions, markers, UI changes, save, or export. Mixed mode arguments, invalid numbers/units, missing elements, or absent boxes fail. Reinspect inputs rather than substituting another mode without explaining its meaning. Follow [operation recovery](../operation-recovery.md) for bridge/identity uncertainty.
+
+## Compatibility
+
+Source reference: PI-Revit 0.5.0, [MeasureGeometry.cs](../../../../src/Revit/Tools/MeasureGeometry.cs), shared length/vector parsing, and public identity/retry inputs. Revit 2025–2027 bridge targets; no new live validation is claimed.

package/skills/pi-revit/references/tools/open_view.md

@@ -0,0 +1,59 @@
+# open_view
+
+## Purpose and boundaries
+
+Queue activation of an existing view or sheet in the Revit UI, like opening it in the Project Browser. It creates no view and edits no model data. Use `manage_views` or `manage_sheets` for authoring.
+
+Contract: PI-Revit 0.5.0 source, [OpenView.cs](../../../../src/Revit/Tools/OpenView.cs). The current public schema is authoritative. This page documents source behavior, not a live-model test.
+
+<!-- generated:contract:start (npm run generate:contracts; do not edit this block) -->
+## Contract (generated)
+
+- **Source:** bridge tool, core tier: active by default.
+- **Writes model:** no. **Effects:** ui. **Requires an open document:** yes.
+- **Works in:** project and family documents.
+- **Verify the outcome:** `none`: no durable outcome to check; report what was done.
+- **Contract hash:** `6bb71caab2e5304b`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `view_id` | integer | no |  |  |
+| `name` | string | no |  |  |
+| `expected_document_id` | string | yes |  |  |
+
+Bridge calls also accept `_operation_id`, only to retry an identical earlier request (see [operation recovery](../operation-recovery.md)).
+
+| Not covered by this tool | Use instead |
+| --- | --- |
+| Creating views | Tool: manage_views |
+<!-- generated:contract:end -->
+
+## Inputs and preconditions
+
+| Input | Meaning |
+| --- | --- |
+| `view_id` | Existing view or sheet ID. Takes precedence over `name`. Discover with `get_elements` or use a committed creation result. |
+| `name` | When no ID is supplied: exact view name, sheet number such as `A-101`, or `number - name`, matched case-insensitively. Ambiguous names fail; use an ID. |
+| `expected_document_id` | Required even though the tool is read-classified: activation changes UI state. Copy the intended model's exact current `project.documentId`. |
+| `_operation_id` | Optional extension argument only for an identical retry. Omit for a new operation. |
+
+At least one of `view_id` or `name` is required at execution. View templates and Revit views that cannot be activated are rejected. An active edit can prevent activation; resolve it before retrying. Follow [execution rules](../execution-rules.md).
+
+## Example
+
+ID `23456` is illustrative; replace it with a discovered or committed view ID.
+
+```json
+{
+  "view_id": 23456,
+  "expected_document_id": "<project.documentId>"
+}
+```
+
+## Results, effects and verification
+
+The result contains `requestedViewId`, `viewName`, and `viewType`. It confirms that activation was queued, not that a screenshot already shows that view. Revit performs the view change after control returns to it.
+
+There is no preview transaction and no model save. A capture relying on the active view in the same call batch can show the previous view. Prefer a subsequent `capture_view` with the explicit target `view_id`, open the returned image, and follow [visual verification](../visual-verification.md).
+
+If a call times out or its status is unclear, follow [operation recovery](../operation-recovery.md); check the requested view and actual UI before issuing a new operation.

package/skills/pi-revit/references/tools/ping.md

@@ -0,0 +1,41 @@
+# ping
+
+## Purpose and preconditions
+
+Check whether the selected local Revit bridge is reachable and which Revit/add-in version is loaded. No open document is required. Pi registers this utility independently of bridge tool discovery, so it remains available when Revit is closed or specialist tools are missing. Multiple sessions may require [explicit selection](manage_revit_instances.md).
+
+<!-- generated:contract:start (npm run generate:contracts; do not edit this block) -->
+## Contract (generated)
+
+- **Source:** Pi extension utility, always active.
+- **Writes model:** no. **Effects:** none. **Requires an open document:** no.
+- **Contract hash:** `aefaeb4355d5d822`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| _(none)_ | | | | |
+
+| Not covered by this tool | Use instead |
+| --- | --- |
+| Whether a project document is open | Tool: get_model_overview |
+<!-- generated:contract:end -->
+
+## Public inputs and example
+
+The public input is an empty object. This utility does not accept document-identity or retry fields.
+
+```json
+{}
+```
+
+## Results and effects
+
+The current bridge returns `ok`, `service`, `revitVersion`, `pid`, `addinVersion`, `bridgeId`, and `supportsOperationTracking`. The extension appends a warning when installed package and loaded add-in versions differ, or a note when tool registration just succeeded or failed. Ping can trigger discovery/registration, but does not execute a model operation or activate all specialist tools. It may bind an initial sole session through normal instance routing.
+
+## Failures and recovery
+
+A missing bridge usually means Revit is closed, still starting, or the add-in did not load. When user action is needed, identify that requirement. A successful ping can coexist with failed tool discovery; retry ping or restart Pi if discovery remains unavailable. Do not treat ping success as proof that a document is open. Selected-session failures require listing/selecting the intended current instance rather than automatic fallback.
+
+## Verification and compatibility
+
+Check the returned Revit/add-in version and any warning before relying on version-specific contracts. This utility uses a 10-second request budget and has no model operation receipt. Updating the Pi package does not replace the already loaded add-in; use the package's installation/upgrade procedure for a matching deployment. Do not deploy or restart merely because an unrelated task requested inspection. Contract source: `extensions/pi-revit/index.ts` (`registerPing`); bridge response: `src/Revit/BridgeServer.cs` (`/ping`).

package/skills/pi-revit/references/tools/query_spatial_elements.md

@@ -0,0 +1,74 @@
+# query_spatial_elements
+
+## Purpose and preconditions
+
+Find host elements whose model axis-aligned bounding boxes intersect or fit inside a specified region. Activate with `find_revit_tools`; use the intended active document. This is an approximate candidate query, not a solid-intersection or clash detector, and it does not traverse linked contents.
+
+<!-- generated:contract:start (npm run generate:contracts; do not edit this block) -->
+## Contract (generated)
+
+- **Source:** bridge tool, advanced tier: activate it with `find_revit_tools`.
+- **Writes model:** no. **Effects:** none. **Requires an open document:** yes.
+- **Works in:** project documents only; the bridge refuses other documents before running, with the route to use instead.
+- **Contract hash:** `0018676c125da56c`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `query` | object | no |  |  |
+| `min` | array of number | yes |  |  |
+| `max` | array of number | yes |  |  |
+| `unit` | string | yes |  | `millimeters`, `centimeters`, `meters`, `feet`, `inches` |
+| `relation` | string | no |  | `intersects`, `inside` |
+| `offset` | integer | no |  |  |
+| `limit` | integer | no |  |  |
+| `expected_document_id` | string | no |  |  |
+
+Bridge calls also accept `_operation_id`, only to retry an identical earlier request (see [operation recovery](../operation-recovery.md)).
+
+| Not covered by this tool | Use instead |
+| --- | --- |
+| Solid-intersection clash detection | Revit API: ElementIntersectsElementFilter; ElementIntersectsSolidFilter. Check all its members in one call: `search_api_docs` with query `ElementIntersectsElementFilter; ElementIntersectsSolidFilter`, then use `execute_csharp` within the requested scope. |
+| Elements inside linked models | Tool: get_linked_elements with host_bounds |
+<!-- generated:contract:end -->
+
+## Public inputs
+
+- Required `min` and `max`: arrays of three finite numbers along document internal axes. Every minimum coordinate must be less than or equal to its maximum.
+- Required `unit`: `millimeters`, `centimeters`, `meters`, `feet`, or `inches`. This covers region coordinates and output lengths.
+- Optional `relation`: `intersects` (default) or `inside`. Both include touching boundaries; inside requires the entire element box to fit in the region.
+- Optional `query`: whole-scope `get_elements` filters (`category`, `of_class`, `level`, `type_id`, `in_active_view`, `filter`). No query-level paging, count-only mode, fields, or projections are accepted.
+- Optional outer `offset`: default 0; `limit`: 1–200, default 100. Pages spatial matches.
+- Optional `expected_document_id`: exact read guard. Optional `_operation_id`: exact previous operation ID for identical retry only.
+
+## Example
+
+This illustrative region is in internal document axes. Replace it with bounds established for the requested part of the intended model; it is not a shared/GIS region.
+
+```json
+{
+  "query": { "category": "OST_Walls" },
+  "min": [0, 0, 0],
+  "max": [10, 10, 3],
+  "unit": "meters",
+  "relation": "intersects",
+  "limit": 100
+}
+```
+
+## Results and verification
+
+The candidate query is capped at 10,000 elements **before** spatial testing, even if few boxes intersect. Narrow the category/level/type/filter scope first. `candidate_count` is distinct from spatial `total_count`; `without_bounds_count` counts candidates omitted because no model bounding box exists. Preserve warnings.
+
+The result states `method: "axis_aligned_bounding_boxes"`, `approximate: true`, `coordinate_system: "document_internal"`, selected unit/relation, and the normalized region. Element rows include IDs, unique identities, names/categories, and bounds in the requested unit. Results sort by ID; follow `next_offset` for remaining matches.
+
+Bounds can include nonphysical geometry. Intersection or containment of enclosing boxes does not establish a physical collision, exact shape containment, or clearance failure. Report candidates with the returned approximation/method labels, then inspect actual geometry if the task requires stronger conclusions. [Visual verification](../visual-verification.md) can support review but does not by itself turn box testing into exact geometry computation.
+
+Check coordinate frame, unit, candidate coverage, absent bounds, and page coverage before reporting. Any saved-response continuation is separate; see [execution rules](../execution-rules.md).
+
+## Effects and recovery
+
+Read-only: no model or UI edits, save, or export. Invalid units/vectors, reversed region bounds, unsupported query fields, or too many candidates fail. Correct the region/scope; do not reinterpret coordinates silently. Use [operation recovery](../operation-recovery.md) for bridge/identity failures.
+
+## Compatibility
+
+Source reference: PI-Revit 0.5.0, [QuerySpatialElements.cs](../../../../src/Revit/Tools/QuerySpatialElements.cs), shared whole-query scope, and identity/retry inputs. Revit 2025–2027 bridge targets; source-reviewed without new live validation.

package/skills/pi-revit/references/tools/read_revit_result.md

@@ -0,0 +1,53 @@
+# read_revit_result
+
+## Purpose and preconditions
+
+Read bounded fragments of an oversized response saved locally by this extension. Revit and an open model are unnecessary. Use the opaque `result_id` returned with `file_path` and `complete_inline: false`; this is not an arbitrary file-reading tool or a new query against Revit. <!-- inv:saved-result-sandbox -->
+
+<!-- generated:contract:start (npm run generate:contracts; do not edit this block) -->
+## Contract (generated)
+
+- **Source:** Pi extension utility, always active.
+- **Writes model:** no. **Effects:** none. **Requires an open document:** no.
+- **Contract hash:** `b318aeb83a3acd30`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `result_id` | string | yes |  |  |
+| `offset` | integer | no |  |  |
+| `limit` | integer | no |  |  |
+
+| Not covered by this tool | Use instead |
+| --- | --- |
+| Paging the original query | Tool: the original query tool (for example get_elements) with its next_offset |
+<!-- generated:contract:end -->
+
+## Public inputs and example
+
+| Field | Contract |
+| --- | --- |
+| `result_id` | Required string returned by this extension instance. |
+| `offset` | Optional nonnegative integer; default `0`. Use the previous `next_offset`. |
+| `limit` | Optional integer `1`–`8000`; default `8000`. JSON escaping may shorten the actual fragment. |
+
+Replace the illustrative UUID with the real returned ID:
+
+```json
+{
+  "result_id": "00000000-0000-4000-8000-000000000001",
+  "offset": 0,
+  "limit": 8000
+}
+```
+
+## Results and effects
+
+The result contains `result_id`, `offset`, `returned_chars`, `total_chars`, `has_more`, `next_offset`, `fragment: true`, and `text`. Concatenate `text` fragments in order; each page is not a standalone JSON result. Offsets count UTF-16 code units, not bytes or Unicode characters. Follow returned offsets until `has_more` is false when complete data is needed. The model-facing response remains bounded including JSON metadata/escaping, so do not infer progress from requested `limit`.
+
+This reads a local saved file without contacting Revit or changing the model. Result IDs last for the current extension instance. After reload, use the original absolute `file_path` with Pi's `read` tool while the file exists. Saved-result continuation does not remove the original query's limits or replace its own row/column/group pagination.
+
+## Failures, recovery, and verification
+
+An unknown ID can mean the extension reloaded; use the original path. An offset past `total_chars` or invalid limit is rejected. A missing local file requires another source of the original result. On a tracked bridge, [get_revit_operation](get_revit_operation.md) may retain it; do not repeat a model write just to recover its output. A large-result save error can occur after Revit finished, so follow [operation recovery](../operation-recovery.md).
+
+Confirm continuity of returned offsets and final completion before treating the reconstructed payload as complete. Keep the query's truncation and pagination labels intact. Contract source: `extensions/pi-revit/index.ts` (`modelContent`, `registerResultReader`); this is a local package contract independent of the loaded Revit version.

package/skills/pi-revit/references/tools/search_api_docs.md

@@ -0,0 +1,65 @@
+# search_api_docs
+
+## Purpose and preconditions
+
+Search the API documentation belonging to the selected running Revit installation before writing unfamiliar C# calls. This is a core tool; it requires a reachable bridge but no open document. The index reads `RevitAPI.xml` and `RevitAPIUI.xml` beside the loaded assemblies and supplements public enum members from assembly metadata. It does not search Autodesk product Help or explain a complete modeling workflow.
+
+<!-- generated:contract:start (npm run generate:contracts; do not edit this block) -->
+## Contract (generated)
+
+- **Source:** bridge tool, core tier: active by default.
+- **Writes model:** no. **Effects:** none. **Requires an open document:** no.
+- **Contract hash:** `dea6dc11655529a1`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `query` | string | yes |  |  |
+| `kind` | string | no |  | `type`, `method`, `property`, `field`, `event` |
+| `max_results` | integer | no |  |  |
+
+Bridge calls also accept `_operation_id`, only to retry an identical earlier request (see [operation recovery](../operation-recovery.md)).
+
+| Not covered by this tool | Use instead |
+| --- | --- |
+| Autodesk product Help or modeling guidance | User action: Autodesk Revit Help or project standards |
+| Proof that code compiles or works | Tool: execute_csharp |
+<!-- generated:contract:end -->
+
+## Public inputs
+
+- Required `query`: a nonempty class/member name or substring. Prefer `Wall.Create`, `FilteredElementCollector`, or an enum value over a natural-language question. To verify several members at once, separate up to 10 names with `;`, for example the reference of a tool's API limit.
+- Optional `kind`: `type`, `method`, `property`, `field`, or `event`. Methods include constructors; enum values are fields.
+- Optional `max_results`: 1–50, default 10; for a multi-member query, per member, default 3. There is no offset or continuation page.
+- Optional `_operation_id`: only for an identical retry of a previous bridge request; omit for new searches. This tool has no `expected_document_id` input.
+
+## Example
+
+Narrow the signature to choose an overload; inspect the result rather than assuming the example identifies the required overload for your task.
+
+```json
+{ "query": "Wall.Create(Document, Curve", "kind": "method", "max_results": 5 }
+```
+
+Verify every member a script needs in one call instead of one search per member. `find_revit_tools` gives each API limit a ready `lookup` query of this form:
+
+```json
+{ "query": "View3D.CreatePerspective; ViewOrientation3D; View.CropBox" }
+```
+
+## Results and verification
+
+A multi-member query returns `lookups` and `results` instead of `matches`: per member its `query`, `totalMatches`, the `best` match (signature, summary, shortened remarks, parameters, returns, and up to three documented exceptions, which state when a member refuses), up to two `alternatives` by signature, and a `note` for a rewrite or a miss. Search a member again on its own when its full remarks or other overloads matter.
+
+For a single query, inspect `matches`, `totalMatches`, `returnedCount`, `sources`, and `warnings`. Each match includes signature, assembly, summary, remarks, parameter/return/exception documentation, and `since` where documented. Exact names rank ahead of prefixes and substrings; same-named overloads favor simpler signatures. Narrow the query to bring the relevant overload to the top.
+
+Pi receives the structured JSON payload with the full available documentation for returned matches, or a saved-result envelope when it is large; retrieve that result as described in [execution rules](../execution-rules.md). The bridge also builds compact display text, but the current Pi extension does not present it to the model. A top match's presence does not establish that its class is suitable for the desired modeling operation. Read parameter restrictions and confirm the installed Revit version.
+
+Creation-factory queries such as `Document.Create.NewRoom` and accessor queries such as `Element.get_Parameter` can be rewritten to the documented member. Verify the returned signatures: the rewrite note exists only in the bridge's compact display text and is not included in Pi's structured result. Public enum values can be searchable even when the XML gives them no description. Missing XML content is a documentation limitation, not proof that a member is absent from the API.
+
+## Effects and recovery
+
+The first query builds a process-wide lazy index and may take several seconds. Later searches reuse it. It performs no model/UI mutation, save, or export. Missing or unparsable documentation yields warnings; an empty index fails. For transport uncertainty use [operation recovery](../operation-recovery.md). Do not invent signatures when documentation is incomplete; report the gap and use verified API sources or inspection.
+
+## Compatibility
+
+Source reference: PI-Revit 0.5.0, [SearchApiDocs.cs](../../../../src/Revit/Tools/SearchApiDocs.cs), with the extension's optional retry input. This manual describes source behavior, not a new live validation. Search results depend on the selected installed Revit version (supported bridge targets: 2025–2027).

package/skills/pi-revit/references/tools/set_parameters.md

@@ -0,0 +1,75 @@
+# set_parameters
+
+## Purpose and boundaries
+
+Write parameters or rename elements in the active host document. Use `Name` to rename levels, views, sheets, types, and other elements that support `Element.Name`; the implementation falls back to that property when the Name parameter is missing, read-only, or rejects the write. That fallback rejects a name another object of the same kind already uses (views of one type, levels, grids, types, materials, filters), reporting `name_collision` with the existing object's ID. This tool does not change element types; use `change_element_types` for that.
+
+Contract: PI-Revit 0.5.0 source, [SetParameters.cs](../../../../src/Revit/Tools/SetParameters.cs). The current public schema is authoritative. This page documents source behavior, not a live-model test.
+
+<!-- generated:contract:start (npm run generate:contracts; do not edit this block) -->
+## Contract (generated)
+
+- **Source:** bridge tool, core tier: active by default.
+- **Writes model:** yes. **Effects:** model. **Requires an open document:** yes.
+- **Works in:** project and family documents.
+- **Verify the outcome:** `reread`: query the changed state again with a read tool.
+- **Contract hash:** `20ad3893ff59afa6`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `preview` | boolean | no |  |  |
+| `atomic` | boolean | no |  |  |
+| `updates` | array of object | yes |  |  |
+| `expected_document` | string | no |  |  |
+| `expected_document_id` | string | yes |  |  |
+
+Bridge calls also accept `_operation_id`, only to retry an identical earlier request (see [operation recovery](../operation-recovery.md)).
+
+| Not covered by this tool | Use instead |
+| --- | --- |
+| Changing an element's type | Tool: change_element_types |
+| Element properties that are not parameters, such as pinned state | Revit API: Element.Pinned. Check all its members in one call: `search_api_docs` with query `Element.Pinned`, then use `execute_csharp` within the requested scope. |
+| Moving or rotating elements | Tool: transform_elements |
+| Family parameters, family types and formulas in a family document | Revit API: FamilyManager.Types; FamilyManager.NewType; FamilyManager.Set; FamilyManager.AddParameter; FamilyManager.SetFormula. Check all its members in one call: `search_api_docs` with query `FamilyManager.Types; FamilyManager.NewType; FamilyManager.Set; FamilyManager.AddParameter; FamilyManager.SetFormula`, then use `execute_csharp` within the requested scope. |
+<!-- generated:contract:end -->
+
+## Inputs and preconditions
+
+Read [execution rules](../execution-rules.md) before a write or preview. Inspect targets and parameters with `get_element_details` first.
+
+| Input | Meaning |
+| --- | --- |
+| `updates` | Required array of 1–200 objects with `element_id`, `parameter`, `value`, and optional `unit`. Each update has its own subtransaction. |
+| `parameter` | Localized display name, language-independent `BuiltInParameter` name, or `guid:<GUID>` for a shared parameter. Prefer an exact identity if display names are missing or ambiguous. |
+| `value` | Matches the parameter storage type: text, number, integer, element ID integer, or boolean for yes/no. Empty text clears a string parameter. Renaming requires nonempty text. |
+| `unit` | For measured numeric values, an explicit compatible unit such as `millimeters`, `feet`, `squareMeters`, or `degrees`. Omission uses this document's display units for the parameter. Omit units for unitless values. |
+| `preview` | Default `false`. Commit-validates accepted changes, then rolls back the enclosing transaction group. |
+| `atomic` | Default `false`: valid updates can commit despite other failures. `true` rolls the whole batch back if any update fails. |
+| `expected_document_id` | Required for every call, including previews: exact current `project.documentId` from `get_model_overview`. |
+| `expected_document` | Optional additional title check; never replaces exact identity. |
+| `_operation_id` | Optional extension argument only for an identical retry of the original request. Omit for a new operation. |
+
+Type parameters live on the element type: pass its ID, and assess all affected instances before changing a shared type. `get_element_details` reports `builtInParameter`; for example, `ALL_MODEL_MARK` and `ALL_MODEL_INSTANCE_COMMENTS` avoid translated display names. A display name that matches several parameters on the element fails that update and lists their exact identities (`BuiltInParameter` name or `guid:<GUID>`); nothing is written to an arbitrary one. <!-- inv:parameter-ambiguity --> Retry with one of the listed identities.
+
+## Example
+
+Illustrative ID `12345` must be replaced with a discovered host element; replace the document placeholder with the exact current identity. This previews a complete batch without retaining changes.
+
+```json
+{
+  "expected_document_id": "<project.documentId>",
+  "preview": true,
+  "atomic": true,
+  "updates": [
+    { "element_id": 12345, "parameter": "ALL_MODEL_INSTANCE_COMMENTS", "value": "Reviewed" }
+  ]
+}
+```
+
+## Results, recovery and verification
+
+Inspect `committed`, `succeeded`, `proposed`, `failed`, `commitWarnings`, and `commit_validation_performed`. `updated` counts committed steps, not distinct elements. Entries contain zero-based input `index`, observed `before`/`after`, and `newDisplayValue`; numeric parameter snapshots use internal units with separately formatted display values. Repeated writes to one parameter form a sequence, so an intermediate `after` is not a final-model snapshot. A proposal is not a retained change.
+
+An atomic rejection can report proposals without reaching commit validation. Revit commit errors can roll back the whole batch; warnings are auto-dismissed and returned for reporting. Reread affected parameters after a committed change. Follow [visual verification](../visual-verification.md) when the values affect visible results.
+
+For an uncertain timeout or cancellation, follow [operation recovery](../operation-recovery.md) before any repeat. A real write following a preview is a new operation because the arguments changed. This tool does not save the model or authorize additional edits.

package/skills/pi-revit/references/tools/summarize_elements.md

@@ -0,0 +1,64 @@
+# summarize_elements
+
+## Purpose and preconditions
+
+Count the whole matching host scope grouped by category, type name, level ID, or a single raw parameter value. Activate with `find_revit_tools`; use the intended active document. It does not traverse links and supports at most 10,000 matching elements. Use `get_elements.count_only` for a bare total that does not need grouping.
+
+<!-- generated:contract:start (npm run generate:contracts; do not edit this block) -->
+## Contract (generated)
+
+- **Source:** bridge tool, advanced tier: activate it with `find_revit_tools`.
+- **Writes model:** no. **Effects:** none. **Requires an open document:** yes.
+- **Works in:** project and family documents.
+- **Contract hash:** `27ddae42a59b01cb`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `query` | object | no |  |  |
+| `group_by` | string | yes |  | `category`, `typeName`, `levelId`, `parameter` |
+| `parameter` | string | no |  |  |
+| `type_parameter` | boolean | no |  |  |
+| `offset` | integer | no |  |  |
+| `limit` | integer | no |  |  |
+| `expected_document_id` | string | no |  |  |
+
+Bridge calls also accept `_operation_id`, only to retry an identical earlier request (see [operation recovery](../operation-recovery.md)).
+
+| Not covered by this tool | Use instead |
+| --- | --- |
+| Linked-model contents | Tool: get_linked_elements |
+| Scopes above 10,000 elements | Tool: narrow the query, or get_elements with count_only for a total |
+<!-- generated:contract:end -->
+
+## Public inputs
+
+- Required `group_by`: exactly `category`, `typeName`, `levelId`, or `parameter`.
+- Optional `query`: whole-scope [get_elements](get_elements.md) filters: `category`, `of_class`, `level`, `type_id`, `in_active_view`, and `filter`. Omission covers all host non-type elements subject to the cap.
+- Query-level `offset`, `limit`, `count_only`, `fields`, `parameter_names`, and `include_type_parameters` are rejected, as are unknown query properties. Place identity/retry arguments at the outer level.
+- `parameter` is required when `group_by` is `parameter`: display name, built-in name, or `guid:<GUID>`. Optional `type_parameter` (default false) chooses the type's parameter rather than the instance's.
+- Optional outer `offset`: default 0. `limit`: 1–500, default 100; these page groups, not input elements.
+- Optional `expected_document_id`: exact read guard. Optional `_operation_id`: exact previous identical-retry ID only.
+
+## Example
+
+```json
+{ "query": { "category": "OST_Walls" }, "group_by": "typeName", "limit": 100 }
+```
+
+## Results and verification
+
+`total_elements` counts the entire matching scope; `total_groups` is independent of returned group count. Each `groups` row has `value`, `missing`, and `count`. Groups sort by descending count then an internal serialized key. Follow `next_offset` for remaining groups.
+
+Parameter groups use exact raw values, including internal numeric units. A missing parameter (`missing: true`) is distinct from a present parameter whose value is null. Ambiguous display-name matches fail instead of choosing one parameter; use a discovered built-in identity or shared GUID. Names are localized. `typeName` groups by name, so different types with the same name can share a group; it is not a unique-type-ID inventory.
+
+The query still interprets numeric **filter inputs** in explicit or document display units, while grouped numeric **output values** are raw internal units. Preserve this difference. Check warnings alongside an unexpected zero and confirm the filter scope. Summing counts from all groups should describe `total_elements`; a single group's page does not describe the full distribution.
+
+For more than 10,000 matches, narrow the scope meaningfully and report any partitioning. Do not remove the cap by pretending a single page represents all elements. Any saved-response retrieval is separate from group paging; see [execution rules](../execution-rules.md).
+
+## Effects and recovery
+
+Read-only: no grouping changes in Revit, selection, save, or export. Oversized scope, invalid query fields, missing parameter input, or ambiguous identities fail. Correct the query rather than silently excluding problematic elements. Use [operation recovery](../operation-recovery.md) for document/bridge uncertainty.
+
+## Compatibility
+
+Source reference: PI-Revit 0.5.0, [SummarizeElements.cs](../../../../src/Revit/Tools/SummarizeElements.cs) and [ElementQueryScope.cs](../../../../src/Revit/Tools/ElementQueryScope.cs), with public identity/retry overlays. Revit 2025–2027 bridge targets; no new live validation is claimed.

package/skills/pi-revit/references/tools/transform_elements.md

@@ -0,0 +1,79 @@
+# transform_elements
+
+## Purpose and boundaries
+
+Move, copy, or rotate explicit host elements together in one model-edit step. It does not accept linked targets or perform collision analysis. Constrained or hosted dependents may also move; returned target snapshots are not a complete dependent-change audit.
+
+Contract: PI-Revit 0.5.0 source, [TransformElements.cs](../../../../src/Revit/Tools/TransformElements.cs). Activate this advanced tool through `find_revit_tools`. The public schema is authoritative; this page documents source behavior, not a live-model test.
+
+<!-- generated:contract:start (npm run generate:contracts; do not edit this block) -->
+## Contract (generated)
+
+- **Source:** bridge tool, advanced tier: activate it with `find_revit_tools`.
+- **Writes model:** yes. **Effects:** model. **Requires an open document:** yes.
+- **Works in:** project and family documents.
+- **Verify the outcome:** `reread`: query the changed state again with a read tool.
+- **Contract hash:** `538f5336f11a299e`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `action` | string | yes |  | `move`, `copy`, `rotate` |
+| `element_ids` | array of integer | yes |  |  |
+| `unit` | string | yes |  | `millimeters`, `centimeters`, `meters`, `feet`, `inches` |
+| `translation` | array of number | no |  |  |
+| `axis_origin` | array of number | no |  |  |
+| `axis_direction` | array of number | no |  |  |
+| `angle_degrees` | number | no |  |  |
+| `preview` | boolean | no |  |  |
+| `expected_document_id` | string | yes |  |  |
+
+Bridge calls also accept `_operation_id`, only to retry an identical earlier request (see [operation recovery](../operation-recovery.md)).
+
+| Not covered by this tool | Use instead |
+| --- | --- |
+| Mirroring | Revit API: ElementTransformUtils.MirrorElements. Check all its members in one call: `search_api_docs` with query `ElementTransformUtils.MirrorElements`, then use `execute_csharp` within the requested scope. |
+| Pinned elements (move and rotate reject them) | User action: Confirm unpinning (Element.Pinned) first |
+| Elements inside linked models | User action: Edit the linked model itself |
+<!-- generated:contract:end -->
+
+## Inputs and preconditions
+
+Read [execution rules](../execution-rules.md), inspect targets, and confirm the requested scope first.
+
+| Input | Meaning |
+| --- | --- |
+| `action` | Required: `move`, `copy`, or `rotate`. |
+| `element_ids` | Required: 1–200 distinct positive host IDs. |
+| `unit` | Required: `millimeters`, `centimeters`, `meters`, `feet`, or `inches`. |
+| `translation` | Required for move/copy: finite `[x,y,z]` displacement in `unit`. |
+| `axis_origin` | Required for rotate: finite `[x,y,z]` position in `unit`, relative to the document internal origin. |
+| `axis_direction` | Required for rotate: nonzero dimensionless direction `[x,y,z]`; normalized internally. |
+| `angle_degrees` | Required for rotate: finite signed angle using the right-hand rule. |
+| `preview` | Default `false`; commit-validates then rolls back all model changes. |
+| `expected_document_id` | Required for every call, including preview. Exact current model identity from the overview. |
+| `_operation_id` | Optional extension argument only for an identical retry. Omit for a new operation. |
+
+Coordinates follow the document's internal origin and axes, not sheet coordinates or shared coordinates. All requested elements form one step: the whole selection succeeds or rolls back. Move and rotate reject pinned targets; copy does not pre-reject pinned sources, but Revit still validates it. The tool never automatically unpins elements.
+
+## Example
+
+Illustrative IDs must be replaced with discovered targets. This previews a 250 mm move along internal X.
+
+```json
+{
+  "action": "move",
+  "element_ids": [12345, 12346],
+  "unit": "millimeters",
+  "translation": [250, 0, 0],
+  "preview": true,
+  "expected_document_id": "<project.documentId>"
+}
+```
+
+## Results, recovery and verification
+
+Inspect common fields `committed`, `succeeded`, `proposed`, `failed`, `commitWarnings`, and `commit_validation_performed`. Snapshots contain requested/created element identities, type, and point or curve-endpoint locations in feet; they do not include complete geometry. `created_ids` comes from copy and can include elements Revit creates with the copied selection. A copy also reports `inherited_state`: per copy, what it carried over from its source, such as Mark, Comments, group or design-option membership. Per-view hiding and overrides are keyed by element ID, so copies do not inherit them. Check carried values against the request; a copied Mark usually needs a new value.
+
+Copy preview IDs are temporary (`created_ids_are_temporary`) and must never be reused after rollback. Use committed results, then reread targets and inspect affected dependents. A real operation after a preview has changed arguments and needs a new operation ID.
+
+Follow [operation recovery](../operation-recovery.md) for uncertain outcomes and [visual verification](../visual-verification.md) for before/after positions and orientation. A successful API step alone does not establish correct placement. This tool does not save the model.

package/skills/pi-revit/references/visual-verification.md

@@ -0,0 +1,36 @@
+# Visual verification and exported evidence
+
+Read when the task creates or changes sheets, drawings, views, tags, schedule layout, geometry placement, or another visible result, or requests graphical deliverables. General explanations and bare counts do not need this workflow. API success establishes execution status, not visual correctness.
+
+## Capture the actual result
+
+- Use [capture_view](tools/capture_view.md) or a requested [image export](tools/export_documents.md) of the actual committed result. `capture_view` returns a temporary PNG path, not image contents.
+- Open that returned file with Pi's image-capable `read` tool and inspect its contents. Do not infer appearance from a filename, image dimensions, successful export, or numeric positions.
+- Frame the real view before capturing. A tiny drawing surrounded by blank space is not sufficient evidence. Use a readable full-sheet image and close-ups when necessary. Place schedules on a sheet when a graphical check of their sheet layout is needed and that placement is within the task scope.
+- Use before/after images when needed to demonstrate movement, rotation, placement changes, or isolation. Preserve useful evidence without repeatedly exporting unrelated views.
+
+## Assess the requested outcome
+
+Check that the requested objects are visible and correctly positioned, view extents are appropriate, labels and schedule contents are readable, and the composition has no unintended overlap or clipping. Check scale/template/titleblock requirements when part of the request. Model coordinates and successful placement calls alone do not establish a good drawing layout.
+
+If a correction is within the user's task, make it using the same identity and transaction rules, then inspect the changed result. If evidence is unavailable or unreadable, state that visual verification is blocked or incomplete and identify what remains unchecked; do not label the visible work fully verified.
+
+## Stop when the request is verified
+
+Verification checks the request; it is not an open-ended improvement loop. Before capturing, list the request's explicit requirements. Then:
+
+- Correct only defects that break one of those requirements, such as a requested object missing or unreadable, an overlap in a requested layout, or a wrong name or target.
+- Once every requirement is verified, stop and report. Offer anything else you noticed (graphic styles, hidden clutter, detail level, framing) as a suggestion; do not do it unrequested.
+- Do not hide, remove or crop away content the request asks to show. For example, a view of "the whole building" keeps its roofs.
+- A result derived from an existing object, such as a duplicated view, copied element or reused type, inherits that object's state. Its result reports `inherited_state`, and a view made by a script appears in `model_changes.new_views` with its hidden categories and elements. Check that state against the request, not just the framing: an image can look complete while roofs or walls are hidden.
+- If the same capture has been repeated after further edits and requirements still seem unmet, stop and report what is met, what is not, and why, rather than continuing to adjust. <!-- inv:completion-proportionate -->
+
+The extension also notices repeated identical verification calls after further edits in one run, and asks for this check.
+
+## Retain and deliver
+
+Retain inspected pictures with the task's evidence and show or link them with concise captions describing what was actually verified. Do not fabricate an image as proof of Revit output. `capture_view` uses temporary files; preserve them in the task's permitted evidence location when long-term retention is needed.
+
+Use export's returned `outputDir` and file paths as authoritative. The default model directory derives from saved/cloud identity or a session fallback, not just the title; Save As can change the destination. Do not reconstruct paths from `project.documentId` or trigger an unrelated export merely to discover a directory.
+
+For PDF/DWG/PNG/IFC deliverables, inspect the resulting artifact as appropriate. Existence and file size do not establish drawing quality or IFC geometry/schema validity. Failed exports can leave partial files. Record meaningful limits and warnings. Evidence capture or export does not authorize saving the Revit model; honor the user's scope and save instructions.