pi-revit 0.3.1 → 0.5.0

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

@@ -0,0 +1,57 @@
+# get_linked_models
+
+## Purpose and preconditions
+
+Discover direct Revit link placements in the active host, including unloaded links, their identities, and transforms. Activate with `find_revit_tools`. This tool requires the intended active host document. It does not traverse nested links or load an unloaded link.
+
+<!-- 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:** `dd234c17c5678369`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `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 |
+| --- | --- |
+| Loading or reloading an unloaded link | Revit API: RevitLinkType.Load. Check all its members in one call: `search_api_docs` with query `RevitLinkType.Load`, then use `execute_csharp` within the requested scope. |
+| Nested links | Revit API: RevitLinkInstance.GetLinkDocument. Check all its members in one call: `search_api_docs` with query `RevitLinkInstance.GetLinkDocument`, then use `execute_csharp` within the requested scope. |
+<!-- generated:contract:end -->
+
+## Public inputs
+
+- Optional `offset`: default 0. Optional `limit`: 1–1000, default 100.
+- Optional `expected_document_id`: exact host document guard.
+- Optional `_operation_id`: exact previous operation ID for an identical retry, omitted for new reads.
+
+## Example
+
+```json
+{ "offset": 0, "limit": 100 }
+```
+
+## Results and verification
+
+Read `links`, `document_id`, `total_count`, `returned_count`, `has_more`, and `next_offset`. Placements sort by element ID. A row contains `link_instance_id`, `unique_id`, name/type ID, `loaded`, `linked_document_id`, document title, and `transform` with origin and basis vectors.
+
+Copy the exact `linked_document_id` and `link_instance_id` into `get_linked_elements`. Its `expected_document_id`, if supplied, remains the **host** identity. An unloaded row has no linked document identity to query. Refresh discovery after unloading/reloading or reopening the linked document.
+
+Transform origin uses internal feet; basis vectors encode orientation and scale and are not lengths to convert independently. The mapping is the instance's total transform into host coordinates. Two placements of one linked document have distinct instance identities and can produce different host coordinates. Preserve the placement when identifying linked elements.
+
+Follow the returned instance pages separately from any saved-response continuation in [execution rules](../execution-rules.md). Verify load status and intended host/link before a linked query; names alone do not establish identity or position.
+
+## Effects and recovery
+
+Read-only: no link loading/unloading, positioning, model edit, save, or UI change. If a follow-up reports a stale linked identity, reread this tool against the intended host instead of substituting a different link. Follow [operation recovery](../operation-recovery.md) for bridge errors.
+
+## Compatibility
+
+Source reference: PI-Revit 0.5.0, [GetLinkedModels.cs](../../../../src/Revit/Tools/GetLinkedModels.cs), registry guard, and extension retry inputs. Source-reviewed for Revit 2025–2027 bridge targets, without new live validation.

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

@@ -0,0 +1,64 @@
+# get_model_coordinates
+
+## Purpose and preconditions
+
+Read project/survey base points, active project location, site data, project-location pages, and optionally map supplied internal-axis points into the active shared-coordinate system. Activate with `find_revit_tools`. Requires the intended active **project** document; family documents are rejected.
+
+This reports Revit's mapping, not an inferred GIS coordinate reference system. Site latitude/longitude and base-point values alone do not establish a datum, projection, EPSG code, or external map units.
+
+<!-- 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:** `d8e8f92e2b035e4e`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `unit` | string | yes |  | `millimeters`, `centimeters`, `meters`, `feet`, `inches` |
+| `points` | array of array | 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 |
+| --- | --- |
+| Identifying the datum, projection or EPSG code | User action: Confirm the coordinate reference system with the surveyor or project standard |
+| Changing coordinates or acquiring shared coordinates | Revit API: ProjectLocation.SetProjectPosition; Document.AcquireCoordinates. Check all its members in one call: `search_api_docs` with query `ProjectLocation.SetProjectPosition; Document.AcquireCoordinates`, then use `execute_csharp` within the requested scope. |
+<!-- generated:contract:end -->
+
+## Public inputs
+
+- Required `unit`: `millimeters`, `centimeters`, `meters`, `feet`, or `inches`.
+- Optional `points`: up to 100 arrays of three finite numbers, expressed along document internal axes in the requested unit. Omit to inspect the coordinate setup without point conversion.
+- Optional `offset`: default 0; `limit`: 1–100, default 50. Paging applies only to project locations, not points.
+- Optional `expected_document_id`: exact read guard. Optional `_operation_id`: exact previous operation ID for identical retry only.
+
+## Example
+
+This reads how the active project location maps the internal origin. It does not change or establish coordinates.
+
+```json
+{ "unit": "meters", "points": [[0, 0, 0]], "limit": 50 }
+```
+
+## Results and verification
+
+The response includes `active_project_location`, project/survey base-point IDs and internal/shared positions, `site` name/latitude/longitude/time zone, location pages, and converted `points`. Each input point is mapped with the active location's `GetProjectPosition`, producing east/west, north/south, elevation, and angle.
+
+All returned lengths use the requested unit. Angles and latitude/longitude use degrees. Direction labels and `point_input_coordinates: "document_internal"` are part of the meaning; do not mix them with sheet coordinates or assume the input is already shared coordinates.
+
+Location rows sort by ID and include name, active flag, and the internal origin in that location's shared coordinates. Use `total_locations` and `next_offset` to complete their listing. Point results are not paged, and points always use the active location even while another location page is being read. Base-point entries can be null if unavailable.
+
+Verify the active project location, requested units, and source of input points before interpreting the output. Use [execution rules](../execution-rules.md) for document identity and any saved-response continuation. This tool does not validate the survey's real-world correctness.
+
+## Effects and recovery
+
+Read-only: no acquire/publish coordinates, base-point movement, active-location changes, model save, or export. Family documents, invalid units/vectors, or more than 100 points fail. Resolve the intended project/frame rather than silently changing it. See [operation recovery](../operation-recovery.md) for identity/transport failures.
+
+## Compatibility
+
+Source reference: PI-Revit 0.5.0, [GetModelCoordinates.cs](../../../../src/Revit/Tools/GetModelCoordinates.cs), shared length/vector parsing, and public identity/retry inputs. Revit 2025–2027 bridge targets; source-reviewed, without new live validation.

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

@@ -0,0 +1,53 @@
+# get_model_health
+
+## Purpose and preconditions
+
+Review Revit document warnings and basic model structure, for example before and after an authorized bulk change. Activate this advanced tool with `find_revit_tools`. It requires the intended active document. This is a bounded warning/structure report, not a complete compliance, geometry, or performance audit.
+
+<!-- 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:** `b8ec894975d2efe0`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `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 |
+| --- | --- |
+| Resolving warnings (report only) | Revit API: Document.GetWarnings; resolve with dedicated edit tools or custom code within scope. Check all its members in one call: `search_api_docs` with query `Document.GetWarnings`, then use `execute_csharp` within the requested scope. |
+| Geometry, performance or standards-compliance audits | Revit API: Custom inspection; verify members with search_api_docs. Check with `search_api_docs`, then use `execute_csharp` within the requested scope. |
+<!-- generated:contract:end -->
+
+## Public inputs
+
+There are no tool-specific inputs or paging controls. Optional `expected_document_id` binds the read to the exact known document. Optional `_operation_id` is only for retrying an identical earlier operation. See [execution rules](../execution-rules.md).
+
+## Example
+
+```json
+{}
+```
+
+## Results and verification
+
+`warnings.total` counts warning occurrences. `groupCount` counts descriptions; `groups` returns the top 100 groups by occurrence count. Each group reports description, severity from the first occurrence, occurrence `count`, distinct failing `elementCount`, and up to 20 failing element IDs/names. Inspect `groupsTruncated` and each group's `elementsTruncated` before claiming completeness.
+
+There is no continuation for the omitted groups or elements. `read_revit_result` can retrieve a large saved response, but cannot remove these tool-level caps. Report truncation and use a separately authorized targeted inspection if full detail is needed.
+
+The report also gives worksharing status/user worksets, phase and design-option names/counts, in-place family count, and total host non-type element count. These totals describe different populations. Missing warning details can be represented by fallback descriptions, null severity/name, or empty failing-element lists.
+
+Compare equivalent snapshots of the same document. A reduction in warnings does not establish that an edit preserved the design, and zero warnings does not establish complete model quality. Read relevant elements and verify the actual requested outcome.
+
+## Effects and recovery
+
+Read-only: no warning resolution, deletion, selection change, save, or export. Investigation does not authorize fixing warnings. Follow [operation recovery](../operation-recovery.md) for no-document, identity, and transport errors.
+
+## Compatibility
+
+Source reference: PI-Revit 0.5.0, [GetModelHealth.cs](../../../../src/Revit/Tools/GetModelHealth.cs), plus public identity/retry inputs. Revit 2025–2027 are bridge targets; no new live validation is claimed.

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

@@ -0,0 +1,57 @@
+# get_model_overview
+
+## Purpose and preconditions
+
+Orient work on the active model: project metadata, document identity, display units, levels, grids, major category counts, and totals. This core tool requires a reachable selected Revit session with an active document. Select the intended session first; the tool does not switch documents or instances.
+
+Use it before model changes to obtain `project.documentId`. Pure explanation tasks do not need a model overview. See [execution rules](../execution-rules.md).
+
+<!-- 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:** yes.
+- **Works in:** project and family documents.
+- **Contract hash:** `b8ec894975d2efe0`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `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 |
+| --- | --- |
+| Switching the active document or Revit session | Tool: manage_revit_instances |
+<!-- generated:contract:end -->
+
+## Public inputs
+
+There are no tool-specific inputs.
+
+- Optional `expected_document_id`: bind this read to an already-known exact open document identity. Omit when initially discovering it, then verify the returned project is the intended one.
+- Optional `_operation_id`: exact previous operation ID for an identical retry; omit for a new overview.
+
+## Example
+
+```json
+{}
+```
+
+## Results and verification
+
+- `project` includes title, opaque `documentId`, project name/number/client/address, file path, Revit version, and display units. Copy the identity unchanged; never reconstruct it from the title or path. Refresh after close/reopen or bridge restart.
+- `project.documentKind` is `project` or `family`. For a family, `project.family` gives its category (localized name and `builtInCategory`), current type, type names and parameters (name, instance or type, formula). Project-only tools refuse a family document before running; edit family types, parameters and formulas through `FamilyManager` with `execute_csharp`.
+- `levels` includes IDs, names, raw `elevation_ft` in internal feet, and formatted `elevation_display`. `grids` includes IDs and names.
+- `counts` covers the tool's predefined major categories, not every possible category. Category count exceptions are represented as zero; use a focused `get_elements` query to investigate a surprising count.
+- `totals.elements` counts non-type host elements; `totals.views` excludes templates and sheets; sheets, levels, and grids also have totals. These are different populations and should not be added together.
+
+No query pagination is exposed. If the extension saves a large response, finish its separate `read_revit_result` continuation. Confirm project metadata before passing the identity to a write, export, or UI change. An overview does not establish visual quality or a complete model audit.
+
+## Effects and recovery
+
+Read-only: no model edit, document activation, selection change, save, or export. No active document produces an immediate error; an identity mismatch rejects the call. Verify the intended model instead of substituting another document's identity. See [operation recovery](../operation-recovery.md) for bridge/timeout failures.
+
+## Compatibility
+
+Source reference: PI-Revit 0.5.0, [GetModelOverview.cs](../../../../src/Revit/Tools/GetModelOverview.cs), plus registry document identity and extension retry inputs. Source-reviewed for the 2025–2027 bridge targets; no new live validation is claimed.

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

@@ -0,0 +1,54 @@
+# get_revit_operation
+
+## Purpose and preconditions
+
+Read a retained operation receipt after timeout, cancellation, or another uncertain outcome. The original bridge must remain reachable and support operation tracking. No open document or Revit model-thread execution is required. Selection of another bridge does not redirect old receipt reads.
+
+<!-- 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:** `a21eea435d7eef6d`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `operation_id` | string | yes |  |  |
+
+| Not covered by this tool | Use instead |
+| --- | --- |
+| Operations from an earlier bridge session | User action: Inspect the model state directly; receipts do not survive a restart |
+<!-- generated:contract:end -->
+
+## Public inputs and example
+
+`operation_id` is a required string of 1–120 characters copied exactly from the original response or error. It contains a bridge generation and request UUID. Do not invent an ID from an element or document ID. There is no `expected_document_id` or `_operation_id` input on this reader.
+
+Replace the example with the real original ID:
+
+```json
+{
+  "operation_id": "00000000000000000000000000000001:00000000-0000-4000-8000-000000000002"
+}
+```
+
+## Results and interpretation
+
+A known receipt returns `operation_id`, `bridge_id`, `tool`, `state`, timestamps, `result_available`, `result_http_status`, and the retained `result` when present. An unknown receipt returns its identity, `state: "unknown"`, and an explanatory message. Large receipts can use [saved-result continuation](read_revit_result.md).
+
+| State | Meaning |
+| --- | --- |
+| `queued`, `running` | Work is unfinished; the reader does not cancel it. |
+| `succeeded` | Call completed. Inspect transaction/result fields; a successful preview need not commit. |
+| `failed` | Inspect the failure and effects; this does not prove rollback. |
+| `expired_before_start` | No tool action began. |
+| `result_unavailable` | Response/receipt construction failed; effects may already exist. |
+| `unknown` | No receipt in that session; this does not prove the action never ran. |
+
+`result_available: false` can also mean a completed result was evicted while its receipt/outcome stayed reserved. Receipt retrieval does not execute the original tool, change the selected instance, or cancel work. Its request budget is 10 seconds.
+
+## Failures, recovery, and verification
+
+An unavailable original bridge cannot be replaced with a different selected instance. Restart changes its identity and clears receipts. Follow [operation recovery](../operation-recovery.md), preserving the original tool and all arguments. Only repeat an identical request through its original tool with the original `_operation_id`; a reader call itself is not the retry.
+
+Compare the receipt result with actual model/UI/file effects when needed. Retained limits are 128 full results / 32 MiB, with up to 10,000 reserved operation records per bridge session; eviction does not allow re-execution. Older bridges without tracking cannot supply this guarantee. Contract sources: `extensions/pi-revit/index.ts` (`registerOperationReader`), `extensions/pi-revit/instance-router.ts`, and `src/Revit/OperationStore.cs`.

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

@@ -0,0 +1,62 @@
+# get_schedule_fields
+
+## Purpose and preconditions
+
+Discover fields eligible for addition to one existing regular schedule. Activate with `find_revit_tools`; obtain a current schedule ID from `get_schedules` in the intended document. Templates and titleblock revision schedules are rejected. Calculated/combined-field authoring is outside this tool.
+
+<!-- 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:** `f7cac60f69eaf4b3`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `schedule_id` | integer | yes |  |  |
+| `name_filter` | string | 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 |
+| --- | --- |
+| Calculated (formula) fields | Not offered by the Revit API (Revit 2025 API exposes ScheduleFieldType.Formula but no member to author a formula). Report this with the evidence checked. |
+| Combined-parameter fields | Revit API: ScheduleDefinition.InsertCombinedParameterField. Check all its members in one call: `search_api_docs` with query `ScheduleDefinition.InsertCombinedParameterField`, then use `execute_csharp` within the requested scope. |
+<!-- generated:contract:end -->
+
+## Public inputs
+
+- Required `schedule_id`: positive integer ID of an existing schedule.
+- Optional `name_filter`: case-insensitive substring of the localized field name.
+- Optional `offset`: nonnegative, default 0. `limit`: 1–200, default 100; invalid ranges are rejected.
+- Optional `expected_document_id`: exact document read guard. Optional `_operation_id`: previous exact identical-retry ID only.
+
+## Example
+
+Replace the illustrative ID with a schedule actually present in the intended model. Omit an English name filter initially if localization is uncertain.
+
+```json
+{ "schedule_id": 12345, "offset": 0, "limit": 100 }
+```
+
+## Results and verification
+
+`fields` contains `parameter_id`, case-sensitive `field_type`, localized `name`, and `included`. Identity is the **pair** `parameter_id` + `field_type`; negative built-in parameter IDs are valid. `included` indicates whether that pair already appears in this schedule. Results sort by parameter ID then field type; continue `next_offset` until the necessary candidates are covered.
+
+Pass discovered pairs unchanged to `manage_schedules.add_fields`. They are not the schedule-local `field_id` values needed for updating, sorting, or filtering existing fields. Read those from `get_schedules` after a committed addition. Preview-added fields and schedules disappear on rollback; their temporary IDs are unusable afterward.
+
+When Count appears, preserve its discovered pair. `manage_schedules` also accepts an addition containing only `field_type: "Count"`; do not invent a parameter ID. An English name filter returning no results may be a localization mismatch, not lack of field support.
+
+Inspect `total_count`, `returned_count`, and `next_offset`. Reading a separately saved result does not remove field paging; see [execution rules](../execution-rules.md). Discovery establishes eligibility for that schedule, not that a chosen field is meaningful for the user's report or visually laid out correctly.
+
+## Effects and recovery
+
+Read-only: no added fields, schedule changes, save, or export. Invalid schedule kind/ID or paging range fails. Correct the request from current discovery. See [operation recovery](../operation-recovery.md) for bridge and identity errors, and [visual verification](../visual-verification.md) after later visible schedule changes.
+
+## Compatibility
+
+Source reference: PI-Revit 0.5.0, [GetScheduleFields.cs](../../../../src/Revit/Tools/GetScheduleFields.cs), with public identity/retry inputs. Revit 2025–2027 bridge targets; no new live validation is claimed.

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

@@ -0,0 +1,71 @@
+# get_schedules
+
+## Purpose and preconditions
+
+List host schedules, or inspect one schedule's fields, sorting/filtering, and formatted body cells. Activate with `find_revit_tools`; use the intended active document. The list excludes templates and titleblock revision schedules. Reading an explicit schedule rejects templates. This is a data read, not a graphical capture.
+
+<!-- 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:** `518da1bdb73e1de9`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `schedule_id` | integer | no |  |  |
+| `name_filter` | string | no |  |  |
+| `offset` | integer | no |  |  |
+| `limit` | integer | no |  |  |
+| `column_offset` | integer | no |  |  |
+| `column_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 |
+| --- | --- |
+| Titleblock revision schedules and schedule templates | Revit API: ViewSchedule.IsTitleblockRevisionSchedule; ViewSchedule.GetTableData. Check all its members in one call: `search_api_docs` with query `ViewSchedule.IsTitleblockRevisionSchedule; ViewSchedule.GetTableData`, then use `execute_csharp` within the requested scope. |
+| Graphical layout of a schedule on a sheet | Tool: capture_view |
+<!-- generated:contract:end -->
+
+## Public inputs
+
+- Optional `schedule_id`: omit to list; supply a discovered integer ID to inspect one schedule.
+- Optional `name_filter`: case-insensitive substring used for the list.
+- Optional `offset`: list offset or body-row offset, default 0. `limit`: 1–200, default 50.
+- Optional `column_offset`: default 0; `column_limit`: 1–50, default 50. These apply to the body read.
+- Optional `expected_document_id`: exact read guard. Optional `_operation_id`: exact previous ID for an identical retry only.
+
+## Examples
+
+```json
+{ "name_filter": "Room", "limit": 50 }
+```
+
+Replace this illustrative number with a schedule ID from the list:
+
+```json
+{ "schedule_id": 12345, "offset": 0, "limit": 50, "column_offset": 0, "column_limit": 50 }
+```
+
+## Results and verification
+
+The list returns schedule identity, category, itemization, field count, and the usual `total_count`/`returned_count`/`has_more`/`next_offset` fields.
+
+A body read returns all `fields`, current `sort_fields` and `filters`, plus a page of `rows`. Field metadata includes schedule-local `field_id`, `parameter_id`, case-sensitive `field_type`, localized name/heading, hidden state, specification ID, grid/sheet widths in feet, and filter capabilities. Use the schedule-local `field_id` for configuring existing fields/sorts/filters. The eligible parameter/type pair from `get_schedule_fields` serves a different purpose: adding fields.
+
+Cells use formatted Revit text and may represent headings, grouped rows, or totals. Neither a row index nor a cell value establishes an element ID. Hidden field definitions do not map one-to-one to displayed columns. Read `row_index` and `first_column_index`; do not guess index origins.
+
+Body reads have two independent continuations: `next_offset` for rows and `next_column_offset` for columns. Read every column page at one row offset before advancing rows, then reset column offset. `total_rows`, `total_columns`, `returned_rows`, and `returned_columns` expose coverage. A saved large response has an additional text-fragment continuation; see [execution rules](../execution-rules.md).
+
+Returned filter comparison names are Revit enum names, not the input strings accepted by `manage_schedules`; measured numeric filter values are internal units. Do not copy them into edit arguments without the required translation and explicit unit. Verify committed schedule edits by rereading fields/rules and, for visible layout, following [visual verification](../visual-verification.md), usually with the schedule placed on a sheet.
+
+## Effects and recovery
+
+Read-only: no schedule creation, modification, view activation, save, or export. An invalid schedule ID or template read fails. Re-discover after deletion or preview rollback; preview-created schedule/field IDs are temporary. Use [operation recovery](../operation-recovery.md) for identity or transport uncertainty.
+
+## Compatibility
+
+Source reference: PI-Revit 0.5.0, [GetSchedules.cs](../../../../src/Revit/Tools/GetSchedules.cs), plus public identity/retry inputs. Revit 2025–2027 bridge targets; source review does not claim new live validation.

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

@@ -0,0 +1,92 @@
+# manage_element_sets
+
+## Purpose and boundaries
+
+Retain a temporary snapshot of matching host-element identities for reuse, without changing model contents or selection. Membership stays fixed; reads show current values and report members that were deleted or whose identity changed. This is not a saved Revit selection set or a live query subscription.
+
+Contract: PI-Revit 0.5.0 source, [ManageElementSets.cs](../../../../src/Revit/Tools/ManageElementSets.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:** no. **Effects:** session. **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:** `6933cbc169654cfd`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `action` | string | yes |  | `create`, `list`, `read`, `forget` |
+| `query` | object | no |  |  |
+| `label` | string | no |  |  |
+| `set_id` | string | no |  |  |
+| `offset` | integer | no |  |  |
+| `limit` | integer | no |  |  |
+| `parameter_names` | array of string | no |  |  |
+| `include_type_parameters` | boolean | 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 |
+| --- | --- |
+| Saved Revit selection sets | Revit API: SelectionFilterElement.Create. Check all its members in one call: `search_api_docs` with query `SelectionFilterElement.Create`, then use `execute_csharp` within the requested scope. |
+| Live query subscriptions | Tool: get_elements (run the query again) |
+<!-- generated:contract:end -->
+
+## Inputs and preconditions
+
+Read [execution rules](../execution-rules.md). Every action requires an open document, including list/forget; a set belongs to the exact open document and bridge session.
+
+| Input | Meaning |
+| --- | --- |
+| `action` | Required: `create`, `list`, `read`, or `forget`. |
+| `query` | Creation scope with `category`, `of_class`, `level`, `type_id`, `in_active_view`, and `filter` supported by `get_elements`. Omission means all host instances, subject to the cap. |
+| `label` | Optional creation label up to 160 characters, default `Element set`. |
+| `set_id` | Required for read/forget: exact returned set ID. |
+| `offset`, `limit` | Read paging, default 0/100; limit range 1–1000. |
+| `parameter_names` | Read projections: at most 20 display names, built-in enum names, or `guid:<GUID>` identities. |
+| `include_type_parameters` | Read option, default false; also project the requested identities from each element's type. |
+| `expected_document_id` | Optional current exact overview identity, always checked if supplied. A saved set separately enforces its own original document identity. |
+| `_operation_id` | Optional extension argument only for an identical retry. Omit for a new operation. |
+
+Creation covers the entire query scope, with at most 10,000 matched elements. Query-level `offset`, `limit`, `count_only`, `fields`, and parameter projections are rejected; place read paging/projections at the outer level. Filter semantics and units are those of `get_elements`: numeric filter inputs use explicit units or document display units. Prefer exact built-in/GUID parameter identities over translated or ambiguous names.
+
+At most 32 sets are retained across the bridge session. Sets expire 30 minutes after creation; reads do not extend expiry. They do not survive document close/reopen or bridge restart. `list` shows only sets for the current document. Forget an unneeded set or narrow the scope rather than assuming additional capacity.
+
+## Example
+
+Create a host-wall snapshot for later inspection; replace the document placeholder with the intended model's identity.
+
+```json
+{
+  "action": "create",
+  "query": { "category": "OST_Walls" },
+  "label": "Walls for audit",
+  "expected_document_id": "<project.documentId>"
+}
+```
+
+Read the returned set ID with optional projections:
+
+```json
+{
+  "action": "read",
+  "set_id": "<set_id from create>",
+  "offset": 0,
+  "limit": 100,
+  "parameter_names": ["ALL_MODEL_INSTANCE_COMMENTS"],
+  "expected_document_id": "<project.documentId>"
+}
+```
+
+## Results, recovery and verification
+
+Create returns `set_id`, `document_id`, `label`, `total_count`, `expires_at`, and query warnings. List returns metadata for current-document sets. Forget returns `forgotten: true`.
+
+Read returns `snapshot_count`, `visited_count`, `returned_count`, `next_offset`, current `elements`, and `missing` with `deleted`/`identity_changed` reasons. Follow `next_offset`, which advances by visited members including missing ones; `returned_count` can be smaller. Do not rerun the original filters implicitly: previously matched elements may now have different values.
+
+Parameter projections include `requested`, `isType`, `found`, `ambiguous`, and all matching values. Treat missing/ambiguous matches explicitly. Measurable numeric raw `value` uses internal units; `displayValue` is document-formatted. Check missing identities before passing current returned IDs to write tools, and obtain authorization for the actual modification separately from creating a set.
+
+Effects are bridge-session memory only; there is no model transaction, preview, or save. Follow [operation recovery](../operation-recovery.md) for uncertain outcomes. An identical retry retrieves the original response, not fresh set contents; a new read is needed for current state. Unknown/expired sets require fresh discovery and creation, not guessing old membership.

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

@@ -0,0 +1,63 @@
+# manage_revit_instances
+
+## Purpose and preconditions
+
+List reachable local Revit sessions or select the intended session for this Pi extension instance. No open document is required. Selection chooses a bridge process; it does not activate a document inside it.
+
+<!-- generated:contract:start (npm run generate:contracts; do not edit this block) -->
+## Contract (generated)
+
+- **Source:** Pi extension utility, always active.
+- **Writes model:** no. **Effects:** session. **Requires an open document:** no.
+- **Verify the outcome:** `reread`: query the changed state again with a read tool.
+- **Contract hash:** `68347717d8c667e6`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `action` | string | no |  | `list`, `select` |
+| `bridge_id` | string | no |  |  |
+
+| Not covered by this tool | Use instead |
+| --- | --- |
+| Activating a document inside a Revit session | User action: Open or activate the document in Revit |
+<!-- generated:contract:end -->
+
+## Public inputs and examples
+
+| Field | Contract |
+| --- | --- |
+| `action` | Optional `list` (default) or `select`. |
+| `bridge_id` | Required for `select`; exact opaque 32-character lowercase hexadecimal identity returned by `list`. |
+
+List available sessions:
+
+```json
+{ "action": "list" }
+```
+
+Select one, replacing the illustrative identity with the actual returned value:
+
+```json
+{
+  "action": "select",
+  "bridge_id": "00000000000000000000000000000001"
+}
+```
+
+No document guard or operation-retry field applies to this utility.
+
+## Results and effects
+
+Listing returns `instances` with `bridge_id`, `pid`, `revit_version`, `addin_version`, `selected`, and `supports_operation_tracking`. Selection returns the selected identity/process/add-in details, instructions, and `tool_catalog_ready`. It refreshes tool discovery for the newly selected session. A false readiness value means selection can have succeeded while discovery is pending; retry [ping](ping.md), then inspect available tools.
+
+Before initial binding, a sole reachable session binds automatically; multiple sessions require explicit selection. Once bound, the extension never silently falls back, even if only one different session remains. After closing/restarting the selected session, list again and explicitly select the intended new identity. Read `get_model_overview` afterward for a fresh exact document identity before edits.
+
+Current bridges publish separate discovery files in `%APPDATA%\RevitBridge\instances\<bridgeId>.json`; the legacy `bridge.json` is also read. Older bridges without generation IDs receive opaque hash selectors. Copy returned selectors unchanged. One legacy file cannot independently advertise several older bridges; current add-ins are needed in those sessions for independent discovery.
+
+## Failures, recovery, and verification
+
+An invalid or unreachable `bridge_id` is rejected and selection stays unchanged. No automatic redirect to another model occurs. Verify selected status, `tool_catalog_ready`, and the intended model overview, not just a process title. Operation receipt reads and identical retries route to the original bridge encoded in their operation ID regardless of this selection. Selecting another session cannot recover a lost receipt or establish what happened in the original model.
+
+## Compatibility
+
+This is a Pi-native session utility, implemented in `extensions/pi-revit/index.ts` and `extensions/pi-revit/instance-router.ts`. Availability/operation tracking depends on the reachable add-in. Tool activation from the previous session should not be mistaken for current bridge support; inspect refreshed discovery. Session selection changes extension routing only and does not modify or save a Revit model.