pi-revit 0.4.0 → 0.5.0

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

@@ -0,0 +1,66 @@
+# delete_elements
+
+## Purpose and boundaries
+
+Delete explicitly selected host elements and report the full deletion set returned by Revit, including deleted dependents. This is a single model-edit step. `get_element_relationships` dependents alone do not predict the complete deletion cascade, and the returned deleted IDs do not audit surviving elements modified by constraints.
+
+Contract: PI-Revit 0.5.0 source, [DeleteElements.cs](../../../../src/Revit/Tools/DeleteElements.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:** `7c3880c989b85bb0`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `element_ids` | array of integer | yes |  |  |
+| `preview` | boolean | no |  |  |
+| `expected_deleted_ids` | array of integer | 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 |
+| --- | --- |
+| Pinned elements (rejected, never unpinned automatically) | User action: Confirm unpinning (Element.Pinned) first |
+| Elements inside linked models | User action: Edit the linked model itself |
+| One-step purge of unused types | Tool: get_element_types with include_instance_count, then delete_elements |
+<!-- generated:contract:end -->
+
+## Inputs and preconditions
+
+Follow [execution rules](../execution-rules.md), identify the exact requested removal, and inspect a preview before committing a deletion with dependencies.
+
+| Input | Meaning |
+| --- | --- |
+| `element_ids` | Required: 1–200 distinct positive host IDs. Every requested element must exist and must not be pinned. |
+| `preview` | Default `false`; validate through commit then roll back the enclosing group. |
+| `expected_deleted_ids` | Optional exact full set of 1–10,000 distinct positive IDs from a prior preview. A different deletion set causes rollback. |
+| `expected_document_id` | Required for preview and real deletion; copy the intended open model's exact current identity. |
+| `_operation_id` | Optional extension argument only for an identical retry. Omit for a new operation. |
+
+The selection succeeds or rolls back together. Cascades above 10,000 deleted IDs are rejected and rolled back. The tool never unpins requested elements. `expected_deleted_ids` protects the deletion set, not every property, constraint, or surviving dependent effect since preview.
+
+## Example
+
+ID `12345` is illustrative. Discover the intended host target and use the actual overview identity.
+
+```json
+{
+  "element_ids": [12345],
+  "preview": true,
+  "expected_document_id": "<project.documentId>"
+}
+```
+
+For an authorized real deletion, use the complete returned preview `deleted_ids` as `expected_deleted_ids` and set `preview: false`. That changed request is a new operation; do not reuse the preview's `_operation_id`. If the set changes, inspect a fresh preview rather than dropping the check.
+
+## Results, recovery and verification
+
+Read `committed`, `succeeded`, `proposed`, `failed`, `commitWarnings`, and `commit_validation_performed`. The successful/proposed step contains `deleted_ids`, `deleted_count`, and `dependent_ids`. A preview reports proposed removals; it does not remove the live targets after rollback.
+
+After commit, verify the requested removals and inspect consequential model/visible changes. Follow [visual verification](../visual-verification.md) where appearance or documentation changes. Follow [operation recovery](../operation-recovery.md) before repeating a timed-out deletion; an absent client response does not mean nothing was deleted. This tool does not save the model.

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

@@ -0,0 +1,81 @@
+# execute_csharp
+
+## Purpose and boundaries
+
+Compile and execute synchronous C# on Revit's API thread for a task that available dedicated tools do not cover. Prefer dedicated query/edit tools when they support the operation. This is unrestricted code with possible model, UI, filesystem, and external effects; the transaction covers model edits only.
+
+Contract: PI-Revit 0.5.0 source, [ExecuteCsharp.cs](../../../../src/Revit/Tools/ExecuteCsharp.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, ui, files, external. **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:** `2fa53a38ab9692cf`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `code` | string | yes |  |  |
+| `inputs` | object | no |  |  |
+| `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 |
+| --- | --- |
+| Automatic preview or rollback of custom code | Tool: dedicated tools with preview (set_parameters, transform_elements, delete_elements, manage_views, ...) |
+| Undoing file, UI or external effects on rollback | User action: Inspect and clean up those effects explicitly |
+| Saving the model | User action: Save only when the user asks |
+<!-- generated:contract:end -->
+
+## Inputs and preconditions
+
+Read [execution rules](../execution-rules.md). Verify unfamiliar classes, methods, enum names, and overloads using `search_api_docs` against the installed API before writing code. Its top match includes detailed documentation; narrow a query to promote the required match. Use `manage_revit_scripts` to store and inspect an exact reusable version when appropriate; saving a script does not execute it or save a model.
+
+| Input | Meaning |
+| --- | --- |
+| `code` | Required nonempty C# top-level script. Additional `using` directives are allowed at the top. |
+| `inputs` | Optional JSON object, default `{}`, available separately as the `inputs` global. At most 100,000 JSON characters. Values are never interpolated into code. Validate types, nested values, ranges, units, and target identities inside the script. |
+| `expected_document_id` | Required even for code intended only to inspect: copy the intended model's exact current overview identity. |
+| `expected_document` | Optional additional document-title check; never replaces identity. |
+| `_operation_id` | Optional extension argument only for an identical retry of the original request. Omit for a new operation. |
+
+There is no `preview` argument and no automatic preview mode. Do not imply that a script execution will roll back merely because the user asked to preview. Use a dedicated tool with a preview contract or prepare an explicit non-editing inspection when that satisfies the request. Model saving, exports, UI actions, and external access must be within the requested scope.
+
+## Script execution rules
+
+- Available globals are `doc` (`Document`), `uidoc` (`UIDocument`), `uiapp` (`UIApplication`), `inputs` (`System.Text.Json.JsonElement`), and `Dump(value)` for intermediate result values.
+- Default imports are `System`, `System.Linq`, `System.Collections.Generic`, `Autodesk.Revit.DB`, and `Autodesk.Revit.UI`. Add other namespaces explicitly, such as `Autodesk.Revit.DB.Architecture`.
+- The backend owns one transaction named `execute_csharp`. Do not start another `Transaction` on `doc`; subtransactions are allowed. Compilation occurs before opening it. Normal completion commits; failure attempts rollback and reports confirmed cleanup status.
+- Code must be fully synchronous. `async` and `await` are rejected at compilation checks. Never block on `Task.Result` or `.Wait()`; they can freeze the Revit thread.
+- Lengths use internal decimal feet. Convert deliberately with `UnitUtils.ConvertToInternalUnits`/`ConvertFromInternalUnits`. Discover exact API signatures and document units rather than assuming meters.
+- Filter at collector level (`OfCategory`, `OfClass`, `WhereElementIsNotElementType`) and keep loops bounded. Activate a required `FamilySymbol` before `NewFamilyInstance`.
+- The call budget is 120 seconds, not a force-stop guarantee. Running Revit work cannot be interrupted mid-script. A client timeout or cancellation does not cancel backend work.
+- The dialog guard attempts dismissive responses and returns `suppressedDialogs`. It can cancel a confirmation-dependent action and cannot guarantee handling every modal dialog. Inspect its report rather than assuming the requested action completed.
+
+## Example
+
+This script performs no model edit or save, but still uses the normal script transaction and required document guard. Replace the identity placeholder with the exact current overview identity.
+
+```json
+{
+  "code": "var value = inputs.GetProperty(\"value\").GetDouble(); if (!double.IsFinite(value)) throw new ArgumentException(\"value must be finite\"); return new { value, nonnegative = value >= 0 };",
+  "inputs": { "value": 12.5 },
+  "expected_document_id": "<project.documentId>"
+}
+```
+
+## Results, recovery and verification
+
+The final expression/return becomes `returnValue`; `Dump` values appear in `dumps`; `durationMs` reports execution duration. Return primitives, strings, or anonymous objects/lists. Projection converts elements to compact identity objects, `ElementId` to an integer, `XYZ` to `{x,y,z}`, and parameters to value summaries. Other raw Revit objects do not round-trip.
+
+Ordinary CLR value projection is bounded: 200 dumps, depth 6, 100 sequence/dictionary items, 40 properties, and 4,000 characters per string. Special projections, including copied `JsonElement` values, follow their own paths. These intrinsic caps differ from large-result retrieval through `read_revit_result`; paging the saved response cannot recover values never serialized. Explicitly bound and summarize returned data, and make completeness clear.
+
+The bridge adds `model_changes` to every committed script result: the elements the script added, modified and deleted (counts plus up to 20 items with name and category), and `new_views` with the visibility state of up to three new views. A script that changed nothing reports only `{ "observed": false }`. In a family document, `model_changes.family` lists family types and parameters added, removed or changed; they are not elements and never appear in `added` or `modified`. `modified` also lists elements Revit updated as a side effect of regeneration (`modified_note` says so): report as changed only what the script targeted. A view duplicated in a script inherits its source's hidden categories, hidden elements and overrides; `new_views` shows them, so compare that state with the request instead of relying on a capture. `modified` lists existing objects the script changed; a PI-Revit scope note marks one that predates the request and that the request names.
+
+A `returnValueError` can accompany a successfully committed script whose return value failed projection. Do not rerun the script merely to recover that value. Report `commitWarnings` and `suppressedDialogs`; inspect errors for whether rollback was actually confirmed. Files, UI, and external effects are not undone by model rollback.
+
+Follow [operation recovery](../operation-recovery.md) after a timeout, cancellation, failed result save, or uncertain response. Reuse an operation ID only with identical code, inputs, identity, and all other arguments. Reread the affected model state; follow [visual verification](../visual-verification.md) for visible results. No automatic model save is performed by the tool, but arbitrary code can request one, so inspect intended code effects before executing it.

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

@@ -0,0 +1,75 @@
+# export_documents
+
+## Purpose and boundaries
+
+Export explicit sheets/views to PDF, DWG, or PNG, or export the model/one view's content to IFC. This tool writes files; IFC also commits model-side IFC GUID changes in a backend-owned transaction. There is no preview mode, no general file rollback, and no automatic Revit model save.
+
+Contract: PI-Revit 0.5.0 source, [ExportDocuments.cs](../../../../src/Revit/Tools/ExportDocuments.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, files. **Requires an open document:** yes.
+- **Works in:** project and family documents.
+- **Verify the outcome:** `inspect_output`: open and inspect the produced file.
+- **Contract hash:** `09e7464757ff2e48`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `format` | string | yes |  | `pdf`, `dwg`, `png`, `ifc` |
+| `ids` | array of integer | no |  |  |
+| `output_dir` | string | no |  |  |
+| `file_name_prefix` | string | no |  |  |
+| `combine` | 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 |
+| --- | --- |
+| Formats other than PDF, DWG, PNG and IFC | Revit API: Document.Export overloads (e.g. DXFExportOptions, NavisworksExportOptions); verify the installed exporter. Check all its members in one call: `search_api_docs` with query `Document.Export; NavisworksExportOptions`, then use `execute_csharp` within the requested scope. |
+| Printing to a physical printer | Revit API: PrintManager. Check all its members in one call: `search_api_docs` with query `PrintManager`, then use `execute_csharp` within the requested scope. |
+<!-- generated:contract:end -->
+
+## Inputs and preconditions
+
+Exports and destinations must be within the user's requested scope. Read [execution rules](../execution-rules.md), discover target IDs with `get_elements`, and verify the intended model and view/sheet contents before delivery.
+
+| Input | Meaning |
+| --- | --- |
+| `format` | Required: `pdf`, `dwg`, `png`, or `ifc`. |
+| `ids` | PDF/DWG/PNG require 1–100 view/sheet IDs. IFC accepts at most one view ID; omission exports the whole model. Templates are rejected; PNG also rejects schedules. |
+| `output_dir` | Optional explicit destination, created if absent. Omit for the model-specific default described below. |
+| `file_name_prefix` | Optional base name, default document title; invalid filename characters are sanitized. Revit appends view/sheet suffixes for multi-file exports. |
+| `combine` | PDF only: default true combines sheets/views into one PDF. False uses Revit's per-view naming rules. |
+| `expected_document_id` | Required for every format, including PDF/PNG; use the intended model's exact current overview identity. |
+| `_operation_id` | Optional extension argument only for an identical retry. Omit for a new operation. |
+
+PNG uses a 2048-pixel horizontal fit; this differs from `capture_view`'s 1568-pixel long-edge cap. DWG availability depends on the Revit installation. Remaining export eligibility and format behavior are validated by Revit.
+
+The default folder is `Documents\pi-revit\Models\<model title>--<identity hash>\exports`. Saved file paths or cloud/server identity determine the model folder; unsaved/unavailable identities use a session fallback. Save As can change the folder. The hash is not `project.documentId`. Use returned `outputDir` and file paths as authoritative; never reconstruct them from the title or opaque document ID. Existing title-only folders remain untouched.
+
+## Example
+
+Export only when requested. IDs `23456` and `23457` are illustrative committed sheet IDs; replace them with verified targets.
+
+```json
+{
+  "format": "pdf",
+  "ids": [23456, 23457],
+  "combine": true,
+  "file_name_prefix": "Room documentation",
+  "expected_document_id": "<project.documentId>"
+}
+```
+
+## Results, recovery and verification
+
+The result contains `format`, `outputDir`, `fileCount`, `files` with `path`/`fileSizeBytes`, and `commitWarnings`. New/changed files are detected by comparing output-directory timestamps; inspect actual returned paths and expected artifacts, especially in a shared destination. Existing filenames may be overwritten.
+
+A failed export may leave partial files; errors identify observed changed files where possible. IFC model rollback does not remove already-written files. Report IFC warnings and inspect actual effects. No files are automatically removed on export failure.
+
+Follow [operation recovery](../operation-recovery.md) after timeout/cancellation; the 120-second call budget does not prove export stopped. Do not retry with a new ID until the original outcome and output files are understood.
+
+Verify that each expected file exists, is usable, and represents the requested scope. For drawings, open/render the actual exported artifact and follow [visual verification](../visual-verification.md), including readability and page completeness. A path or nonzero file size is not sufficient visual proof. Exporting evidence does not authorize saving the model.

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

@@ -0,0 +1,96 @@
+# find_revit_tools
+
+## Purpose and preconditions
+
+Find PI-Revit capabilities by task wording, see what each tool does **not** cover and what to use instead, and activate relevant registered tools before calling them. Registration, activation, and reading guidance are separate steps; this tool does not run the discovered Revit operation or read the manual for you.
+
+Use default `scope: "available"` for native utilities and the selected bridge's last-discovered tools. A tool registered earlier in this Pi session can remain registered after switching bridges while no longer appearing in that available catalogue. Use `scope: "documentation"` to find packaged guidance without contacting Revit or activating tools, including while Revit is closed. A documentation entry is not proof that the selected bridge supports a capability.
+
+<!-- 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:** `none`: no durable outcome to check; report what was done.
+- **Contract hash:** `25e8fc4224d36256`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `scope` | string | no |  | `available`, `documentation` |
+| `query` | string | no |  |  |
+| `names` | array of string | no |  |  |
+| `activate` | boolean | no |  |  |
+| `offset` | integer | no |  |  |
+| `limit` | integer | no |  |  |
+
+| Not covered by this tool | Use instead |
+| --- | --- |
+| Reading manual contents | Tool: read (open the returned path) |
+<!-- generated:contract:end -->
+
+## Public inputs and examples
+
+`query` takes short English task words. Tool vocabulary is English; when the user writes in another language, translate the request into English search words first and still reply in the user's language. Matching ignores case, accents, simple plural and word forms, and numbers, which are call arguments. Words are matched against each tool's name, declared keywords, packaged summary, declared limits, input names and live description. Tools that match every word are returned first, followed by strong partial matches. If no tool matches every word, the response has `match: "partial"` or `"none"`. Use separate queries or `names` for different capabilities.
+
+Find and activate a known specialist:
+
+```json
+{
+  "names": ["manage_schedules"],
+  "activate": true
+}
+```
+
+Search by task wording, translated into English if the user wrote in another language:
+
+```json
+{ "query": "count walls per level" }
+```
+
+Find manuals for an explanation without connecting to Revit:
+
+```json
+{
+  "scope": "documentation",
+  "names": ["manage_schedules", "get_schedule_fields"],
+  "limit": 20
+}
+```
+
+Browse without activating:
+
+```json
+{ "offset": 0, "limit": 20 }
+```
+
+## Results and effects
+
+The response reports `scope`, `match` (`all`, `partial`, `none`, `names` or `browse`), `bridge_catalog_known`, `bridge_catalog_observed_at`, paging fields (`total_count`, `offset`, `returned_count`, `next_offset`), `tools`, and `guidance`. A successful empty bridge catalogue is known empty; unknown means no successful discovery snapshot. Each tool entry gives its description, tier, effects and `source` (`native` or `bridge`), and these separate states:
+
+- `registered`: the tool was registered in this Pi extension session. Bridge registrations can survive a switch even when the tool becomes inactive and the new bridge does not advertise it.
+- `advertised_by_selected_bridge`: the selected bridge's last successful discovery snapshot advertises this tool. It is `null` before a successful snapshot and for native utilities; false can be meaningful after a known empty snapshot.
+- `active`: the tool is exposed to the model. This does not prove current bridge support, a live connection, or a successful operation.
+- `limits`: what the tool deliberately does not cover, each with an `alternative`. The kinds are `tool` (another public tool), `api` (Revit API members to verify with `search_api_docs` before custom execution), `user` (needs a user action or decision) or `revit_unsupported` (the Revit API itself does not offer it; the reference states the evidence). A tool from a newer bridge without declared limits reports them as unknown.
+- `verification`: the minimum sufficient check of the tool's outcome (`reread`, `capture`, `inspect_output` or `none`).
+
+When a query matches only partially or not at all, the result includes a `fallback` route. A missing dedicated tool is not evidence that the operation is impossible: verify the needed API members with `search_api_docs`, then use `execute_csharp` within the requested scope. Report "not possible" only after that check, naming what was checked. <!-- inv:limits-have-alternatives -->
+
+`guidance` lists matching workflows, shared references and skills, including subject skills added to the package later, with absolute paths to read.
+
+Each tool also carries a `documentation` object: `key`, absolute `path` when available, `status` (`available` or `missing`), `revision`, `package_version`, `packaged_contract_hash`, `live_contract_hash`, `observed_bridge_version` and `compatibility`. Missing, unreadable, non-file or outside-root manual targets are reported as missing without failing discovery; paths are resolved only inside the package. <!-- inv:manual-path-containment --> Compatibility compares the executable contract (input schema and declared effects) of the selected bridge's live tool with the contract its manual was generated from:
+
+- `contract_match`: the manual was generated from this exact contract.
+- `contract_changed`: the live contract differs. The active schema is authoritative; do not assume features the manual describes.
+- `undocumented`: a newer bridge tool with no packaged manual.
+- `unknown`: no live contract observed yet.
+- `package_local`: a native utility shipped with this extension.
+
+Wording changes to descriptions or guidelines do not change the contract.
+
+Available-scope activation is additive: it preserves other Pi tools and activates the returned page, not every matching page. Partial pages default to five entries. Follow `next_offset` if more matches are needed. Newly activated schemas become available on the next model request; inspect them before constructing a call. Documentation scope only discovers references and leaves activation/connection state unchanged.
+
+## Failures, recovery, and verification
+
+Unknown exact names are rejected; check spelling, scope, and current bridge discovery. If a bridge tool is only in documentation scope, establish the intended running bridge and refresh via [ping](ping.md) before using it. If a selected instance becomes unavailable, use [manage_revit_instances](manage_revit_instances.md); the catalogue is not a live health check. Missing manuals do not establish tool unavailability, and manuals alone do not establish executability.
+
+Verify the returned tool name, source, registration/activation, compatibility, and current schema. No document guard or `_operation_id` applies: discovery is not a model operation. Contract sources: `extensions/pi-revit/tool-catalog.ts`, `extensions/pi-revit/discovery.ts`, the generated contract snapshot and the documentation manifest. The inventory grows with the package; the current tool count is not an architectural limit.

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

@@ -0,0 +1,66 @@
+# get_element_details
+
+## Purpose and preconditions
+
+Inspect known host elements: parameters, type information, location, model bounding box, or materials. This core tool requires the intended active document and discovered element IDs. For listing/filtering use `get_elements`; linked IDs do not identify elements in the host document.
+
+<!-- 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:** `37ca1810049de7e3`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `element_ids` | array of integer | yes |  |  |
+| `parameter_names` | array of string | no |  |  |
+| `include` | object | 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 |
+| --- | --- |
+| Listing or filtering elements | Tool: get_elements |
+| Elements inside linked models | Tool: get_linked_elements |
+| Exact solid geometry or faces | Revit API: Element.Geometry(Options). Check all its members in one call: `search_api_docs` with query `Element.Geometry`, then use `execute_csharp` within the requested scope. |
+<!-- generated:contract:end -->
+
+## Public inputs
+
+- Required `element_ids`: 1–50 integer IDs per call. Batch larger requests yourself.
+- Optional `parameter_names`: exact case-insensitive localized display names or `BuiltInParameter` enum names. Omission or an empty list returns all applicable parameters. This details filter does **not** support `guid:<GUID>` lookup; that syntax belongs to `get_elements` projections and filters.
+- Optional `include`: `parameters` defaults true; `type_parameters`, `location`, `bounding_box`, and `materials` default false. Type parameters can be requested independently of instance parameters.
+- Optional `expected_document_id`: exact document read guard. Optional `_operation_id`: previous exact operation ID for identical retry only.
+
+## Example
+
+The numeric ID is illustrative: replace it with an ID discovered in the intended host model.
+
+```json
+{
+  "element_ids": [12345],
+  "parameter_names": ["ALL_MODEL_MARK", "ALL_MODEL_INSTANCE_COMMENTS"],
+  "include": { "parameters": true, "type_parameters": true, "location": true, "bounding_box": true }
+}
+```
+
+## Results and verification
+
+`count` and `elements` cover found inputs; always inspect `not_found`. Returned identity includes type ID/name and level ID. Parameter rows carry `storageType`, `isType`, `isReadOnly`, `value`, and `displayValue`, with `builtInParameter`, shared GUID, and display-unit metadata where available. Preserve multiple same-named parameters; their names alone do not prove a unique writable identity.
+
+Raw measurable values are internal Revit units, independent of the field named `unit` (which describes the formatted display unit). Locations, curve lengths, and bounding boxes use internal feet; point rotation is radians; material area/volume use square/cubic feet. There is no requested output-unit input. `displayValue` is formatted text and may be null.
+
+`location` can be null, a point, or a bound curve's endpoints/length. `boundingBox` can be null and is not exact geometry. Material data comes from non-paint material IDs; unavailable areas/volumes can be omitted. Empty/partial geometry metadata is not evidence that an element has no physical geometry.
+
+There is no query paging: batches are capped at 50 IDs. Finish any separately saved large response using [execution rules](../execution-rules.md). An empty parameter-name match in a localized model should prompt discovery of the actual name or built-in identity, not an assumption that the value is absent.
+
+## Effects and recovery
+
+Read-only: no edits, selection changes, saves, or exports. Missing individual IDs appear in `not_found`; an empty or oversized input batch fails. Re-discover replaced/deleted elements before a later write. Use [operation recovery](../operation-recovery.md) for identity/transport uncertainty; visual appearance still needs [visual verification](../visual-verification.md) when the broader task changes visible content.
+
+## Compatibility
+
+Source reference: PI-Revit 0.5.0, [GetElementDetails.cs](../../../../src/Revit/Tools/GetElementDetails.cs), with registry identity and extension retry inputs. Revit 2025–2027 bridge targets; source-reviewed, not newly validated live.

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

@@ -0,0 +1,61 @@
+# get_element_relationships
+
+## Purpose and preconditions
+
+Inspect relationships of one known host element. Activate with `find_revit_tools`; discover the ID in the intended active document. Links are not traversed. Logical dependents are not a complete prediction of deletion effects; use an authorized `delete_elements` preview for its Revit-reported deletion cascade.
+
+<!-- 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:** `c597f56ba5735470`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `element_id` | integer | yes |  |  |
+| `relationships` | array of string | no |  | `type`, `level`, `owner_view`, `host`, `parent`, `subcomponents`, `group`, `assembly`, `members`, `joined`, `dependents` |
+| `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 |
+| --- | --- |
+| A complete prediction of deletion effects | Tool: delete_elements with preview |
+<!-- generated:contract:end -->
+
+## Public inputs
+
+- Required `element_id`: integer host element ID.
+- Optional `relationships`: array chosen from `type`, `level`, `owner_view`, `host`, `parent`, `subcomponents`, `group`, `assembly`, `members`, `joined`, and `dependents`. Omission requests all; names are case-sensitive.
+- Optional `offset`: default 0; `limit`: 1–200, default 100. The same window is applied independently to every requested relationship.
+- Optional `expected_document_id`: exact read guard. Optional `_operation_id`: exact ID for an identical previous-request retry only.
+
+## Example
+
+Replace the illustrative ID with an actual host element ID. A targeted relationship list keeps the result focused.
+
+```json
+{ "element_id": 12345, "relationships": ["type", "host", "dependents"], "limit": 100 }
+```
+
+## Results and verification
+
+The result identifies `document_id` and `element_id`; `relationships` contains one independently paginated result per requested kind. Each has `total_count`, `returned_count`, `offset`, `has_more`, `next_offset`, and element identities. Results remove duplicate/invalid IDs and sort by element ID. Continue unfinished kinds individually rather than assuming one continuation covers all kinds.
+
+`host`, `parent`, and `subcomponents` are family-instance relationships. `members` covers group or assembly members; `group` and `assembly` identify an element's containing membership. Empty results can mean the relationship is inapplicable. Null related-element metadata is not permission to assume a missing element's identity.
+
+In a family document, explicitly request kinds excluding `joined`; the default includes it and fails because `JoinGeometryUtils` requires a project. Joined geometry is distinct from physical overlap and from hosted/dependent relationships.
+
+Verify the relationship kind answers the question and preserve host-document context when using returned IDs. No coordinate/unit conversion is involved. Separately finish any saved-response retrieval under [execution rules](../execution-rules.md).
+
+## Effects and recovery
+
+Read-only: no join, unjoin, deletion, selection change, save, or export. Invalid element IDs or relationship kinds fail. Relationship discovery does not authorize editing dependents. Follow [operation recovery](../operation-recovery.md) for stale document or bridge failures.
+
+## Compatibility
+
+Source reference: PI-Revit 0.5.0, [GetElementRelationships.cs](../../../../src/Revit/Tools/GetElementRelationships.cs), plus identity/retry inputs. Revit 2025–2027 bridge targets; source review only, with no new live validation.

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

@@ -0,0 +1,67 @@
+# get_element_types
+
+## Purpose and preconditions
+
+Discover loaded element types and family symbols, optionally distinguishing placed types from unused loaded types. This core tool requires the intended active document. Returned type IDs can scope `get_elements` or supply an appropriate later creation/type-change operation; availability alone does not establish compatibility with a target element.
+
+<!-- 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:** `1eb28b6511ebb61e`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `category` | string | no |  |  |
+| `of_class` | string | no |  |  |
+| `name_filter` | string | no |  |  |
+| `include_instance_count` | 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 |
+| --- | --- |
+| Creating or duplicating types | Revit API: ElementType.Duplicate. Check all its members in one call: `search_api_docs` with query `ElementType.Duplicate`, then use `execute_csharp` within the requested scope. |
+| Loading families | Revit API: Document.LoadFamily. Check all its members in one call: `search_api_docs` with query `Document.LoadFamily`, then use `execute_csharp` within the requested scope. |
+| The types of the family being edited 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 -->
+
+## Public inputs
+
+All are optional:
+
+- `category`: localized category or built-in category name.
+- `of_class`: element type class such as `WallType`, `FamilySymbol`, or `ViewFamilyType`.
+- `name_filter`: case-insensitive substring of the type name or family name.
+- `include_instance_count`: default false. Adds a pass through the scoped category, or the whole host model without a category.
+- `offset`: default 0; `limit`: 1–1000, default 200.
+- `expected_document_id`: exact optional read guard. `_operation_id`: optional identical-retry ID; omit on new calls.
+
+## Example
+
+```json
+{ "category": "OST_Doors", "include_instance_count": true, "limit": 100 }
+```
+
+For view creation, use `of_class: "ViewFamilyType"`; for titleblocks use `category: "OST_TitleBlocks"`. Choose from actual returned IDs, not sample or remembered numbers.
+
+## Results and verification
+
+Read `types`, `total_count`, `returned_count`, `has_more`, and `next_offset`. Pages sort by family then type name. Rows contain `id`, `name`, `familyName`, `category`, and `isFamilySymbol`; `instanceCount` appears only when requested.
+
+A zero instance count means no placed host instances counted for that type, not that the type is unloaded or safe to delete. Counts exclude linked contents. Verify family/category and inspect the type with `get_element_details` when a subsequent task depends on parameter values or compatibility. Type-name equality alone does not prove two types are interchangeable.
+
+Follow query pagination and, independently, any saved-response continuation described in [execution rules](../execution-rules.md). There are no coordinate or unit inputs.
+
+## Effects and recovery
+
+Read-only; no type activation, creation, deletion, save, or selection change. Resolve invalid category/class errors using the installed API or current model information. Handle stale identity or bridge uncertainty through [operation recovery](../operation-recovery.md).
+
+## Compatibility
+
+Source reference: PI-Revit 0.5.0, [GetElementTypes.cs](../../../../src/Revit/Tools/GetElementTypes.cs), registry identity guard, and extension retry argument. Supported bridge targets: Revit 2025–2027. No new live validation is claimed.

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

@@ -0,0 +1,87 @@
+# get_elements
+
+## Purpose and preconditions
+
+List or count host-document instances of any category, including views, sheets, rooms, and levels. Use returned IDs for further inspection or host operations. This core tool requires an active document in the intended session. It excludes element types; use `get_element_types` for those. It does not traverse linked model contents.
+
+<!-- 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:** `638881fcadf80086`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `category` | string | no |  |  |
+| `of_class` | string | no |  |  |
+| `filter` | object | no |  |  |
+| `level` | string | no |  |  |
+| `type_id` | integer | no |  |  |
+| `in_active_view` | boolean | no |  |  |
+| `count_only` | boolean | no |  |  |
+| `parameter_names` | array of string | no |  |  |
+| `include_type_parameters` | boolean | no |  |  |
+| `fields` | array of string | no |  | `id`, `name`, `category`, `typeName`, `levelId` |
+| `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 |
+| --- | --- |
+| Elements inside linked models | Tool: get_linked_elements |
+| Grouped counts or statistics over a whole scope | Tool: summarize_elements |
+| Spatial containment or intersection | Tool: query_spatial_elements |
+<!-- generated:contract:end -->
+
+## Public inputs
+
+All inputs are optional:
+
+- Scope: `category` (display name or `BuiltInCategory` such as `OST_Walls`), `of_class` (Revit class name), `level` (name or ID represented as a string in the public schema), `type_id` (integer), and `in_active_view` (default false).
+- `filter`: `{ "match": "all" | "any", "rules": [...] }`, default AND. Each rule requires `param` and `op`; `value` and `unit` depend on the operation. Parameters accept localized display names, built-in enum names, or `guid:<GUID>`.
+- Rule `op`: `equals`, `not_equals`, `greater`, `greater_or_equal`, `less`, `less_or_equal`, `contains`, `is_empty`, `is_not_empty`, or `regex`. Empty checks do not need `value`; regex takes a pattern. Numeric comparison values use the supplied compatible `unit`, or the document's display units for that parameter.
+- `count_only` (default false) returns only count information. `fields` selects identity fields `id`, `name`, `category`, `typeName`, `levelId`; `id` is always included, and all five are the default.
+- `parameter_names`: up to 20 requested parameter identities. `include_type_parameters` (default false) also projects those identities from the type. Count-only mode ignores projections.
+- `offset`: default 0. `limit`: 1–1000, default 200.
+- `expected_document_id`: optional exact identity guard for this read. `_operation_id`: optional exact identical-retry ID. See [execution rules](../execution-rules.md) and [operation recovery](../operation-recovery.md).
+
+## Examples
+
+Count all host walls without transferring rows:
+
+```json
+{ "category": "OST_Walls", "count_only": true }
+```
+
+Inspect a small parameter projection on matching doors:
+
+```json
+{
+  "category": "OST_Doors",
+  "filter": { "rules": [{ "param": "ALL_MODEL_MARK", "op": "is_not_empty" }] },
+  "parameter_names": ["ALL_MODEL_MARK", "ALL_MODEL_INSTANCE_COMMENTS"],
+  "limit": 100
+}
+```
+
+## Results and verification
+
+Listing returns `total_count`, `returned_count`, `elements`, `offset`, `has_more`, and `next_offset`; follow every page required by the task. `total_count` covers all matches, not the page. Count-only results have `count_only: true` and no rows. A separately saved result has its own text-fragment continuation; reading that cannot recover element pages never requested.
+
+Each parameter projection reports `requested`, `isType`, `found`, `ambiguous`, and `matches`. Preserve every match instead of silently choosing a duplicate name. Rows of special or system-owned objects carry a `traits` object, such as `titleblock_revision_schedule`, `placeholder_sheet`, `view_template`, `dependent_view_of`, `group_id`, `design_option_id` or `pinned`; ordinary elements have none. <!-- inv:special-objects-flagged --> Raw `value` uses Revit storage/internal numeric units; `displayValue` is formatted separately, and a reported `unit` names the display unit. This differs from numeric filter inputs.
+
+Prefer built-in or shared GUID identities for stable filtering. Display-name rules and regex can scan the narrowed scope; a display name need not identify one globally uniform parameter. Narrow by category/class where possible. An unexpected zero plus a missing-parameter warning may be a localization problem, not absence of elements. Inspect details and use the discovered built-in identity. `is_empty` also matches elements that lack the parameter entirely. When the named parameter was not found on the probed elements, its warning is kept even though matches exist, because the matches may be elements without the parameter. <!-- inv:missing-not-silent --> A display name that matches several parameters on one element fails the query with their exact identities rather than silently choosing one; use one of those identities. <!-- inv:parameter-ambiguity -->
+
+Verify scope before reporting counts. `in_active_view` is visibility-based and needs a suitable active view. Host IDs from this tool do not authorize changing the selection: use `manage_selection` separately within the requested scope.
+
+## Effects and recovery
+
+Read-only; no selection, model edit, save, or export. Invalid categories/classes/levels, malformed filters, or excessive projections fail. Recheck names and parameter identities rather than broadening a failed query silently. Query results are live reads, not retained snapshots; use `manage_element_sets` when fixed membership is needed. Follow shared recovery for identity and transport failures.
+
+## Compatibility
+
+Source reference: PI-Revit 0.5.0, [GetElements.cs](../../../../src/Revit/Tools/GetElements.cs) and [GetElementDetails.cs](../../../../src/Revit/Tools/GetElementDetails.cs) projection helper, plus public identity/retry inputs. Supported bridge targets are Revit 2025–2027; this is source review, not live validation.