pi-revit 0.4.0 → 0.5.0

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.

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

@@ -0,0 +1,109 @@
+# manage_revit_scripts
+
+## Purpose and preconditions
+
+Maintain reusable C# definitions and run an explicitly chosen immutable version. The local library is `%APPDATA%\pi-revit\scripts`, containing versions and run history. `save`, `list`, `read`, and `history` work without Revit or an open model. `run` needs the intended open document, its exact identity, and a bridge with operation receipts.
+
+Read the exact saved source before running it. A library run has the same unrestricted model/UI/file/external effects as [execute_csharp](execute_csharp.md), including one backend-owned transaction, synchronous execution, and a 120-second budget. Saving a definition neither executes it nor saves the Revit model. There is no library preview mode or automatic model saving.
+
+<!-- generated:contract:start (npm run generate:contracts; do not edit this block) -->
+## Contract (generated)
+
+- **Source:** Pi extension utility, always active.
+- **Writes model:** yes. **Effects:** model, ui, files, external. **Requires an open document:** no.
+- **Verify the outcome:** `reread`: query the changed state again with a read tool.
+- **Contract hash:** `3a257b284de8dae5`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `action` | string | yes |  | `list`, `save`, `read`, `run`, `history` |
+| `name` | string | no |  |  |
+| `version` | string | no |  |  |
+| `description` | string | no |  |  |
+| `code` | string | no |  |  |
+| `input_types` | object | no |  |  |
+| `inputs` | object | no |  |  |
+| `expected_document_id` | string | no |  |  |
+| `_operation_id` | string | no |  |  |
+| `offset` | integer | no |  |  |
+| `limit` | integer | no |  |  |
+
+| Not covered by this tool | Use instead |
+| --- | --- |
+| Preview or rollback of a script run | Tool: dedicated tools with preview (set_parameters, transform_elements, delete_elements, manage_views, ...) |
+<!-- generated:contract:end -->
+
+## Public inputs
+
+| Field | Contract |
+| --- | --- |
+| `action` | Required `list`, `save`, `read`, `run`, or `history`. |
+| `name` | Required for save/read/run; optional exact filter for list/history. 1–64 lowercase letters, digits, underscores or hyphens, beginning with a letter. |
+| `version` | Required for read/run: exact saved 64-character lowercase SHA-256 hash. There is no implicit latest version. |
+| `description` | Required for save; string of at most 2,000 characters. |
+| `code` | Required for save; nonblank source of at most 100,000 characters. |
+| `input_types` | Required for save; object declaring at most 40 named inputs. Kinds: `string`, `number`, `integer`, `boolean`, `object`, `array`. |
+| `inputs` | Object for run, defaults to `{}`; every declared input is required, undeclared inputs are rejected. Maximum 100,000 JSON characters. |
+| `expected_document_id` | Required nonempty exact overview identity for run, even for code that only reads. |
+| `_operation_id` | Optional for an identical retry of run; copy the original ID and preserve version, inputs, and document. Omit for new work. |
+| `offset`, `limit` | List/history pagination: nonnegative offset default `0`; limit `1`–`100`, default `20`. |
+
+Input names start with a letter and contain at most 64 letters, digits, or underscores. Validation checks only top-level kinds; scripts must validate nested contents, ranges, units, IDs, and domain rules. `integer` requires a safe integer; `number` requires a finite number. Inputs reach the script as a separate `System.Text.Json.JsonElement`, never as substituted source text.
+
+## Examples
+
+Save a definition that only echoes a numeric check:
+
+```json
+{
+  "action": "save",
+  "name": "check_number",
+  "description": "Echo a supplied number and report whether it is nonnegative.",
+  "code": "var value = inputs.GetProperty(\"value\").GetDouble(); return new { value, nonnegative = value >= 0 };",
+  "input_types": { "value": "number" }
+}
+```
+
+Read it before running. Replace the illustrative hash below with the exact `version` returned by save:
+
+```json
+{
+  "action": "read",
+  "name": "check_number",
+  "version": "0000000000000000000000000000000000000000000000000000000000000001"
+}
+```
+
+Then run that version, replacing both the hash and document placeholder with actual returned identities:
+
+```json
+{
+  "action": "run",
+  "name": "check_number",
+  "version": "0000000000000000000000000000000000000000000000000000000000000001",
+  "expected_document_id": "<project.documentId from the intended model overview>",
+  "inputs": { "value": 12.5 }
+}
+```
+
+This source performs no model edit or save; its run still uses the normal script transaction and receipt. Inspect paged local run history:
+
+```json
+{ "action": "history", "name": "check_number", "offset": 0, "limit": 20 }
+```
+
+## Results and effects
+
+Save returns `name`, `version`, `created_at`, `file_path`, and `executed: false`. The hash covers source, description, and normalized input declarations. Saving identical content returns the same immutable definition; reads integrity-check saved content before use. Read returns the source, input declarations, and metadata. List returns versions with descriptions/input declarations and `next_offset`.
+
+Run forwards the saved source and validated inputs to `execute_csharp`; inspect its result and receipt rather than inferring a commit from local history. History returns records newest first, including version, document identity, input hash, timestamps, run ID, and available bridge/operation receipt identifiers. It excludes raw input values/results. `prepared` is not proof of dispatch or execution, `response_received` is not proof of a successful model edit, and `outcome_unconfirmed` requires receipt inspection.
+
+## Failures, recovery, and verification
+
+Invalid names/hashes, altered saved content, missing inputs, extra inputs, or invalid kinds are rejected. Read and inspect another version explicitly rather than guessing latest. If local history preparation fails, do not assume a dispatch occurred; follow the reported error/receipt. If final history updating fails after a response, the returned result warns about it: use the operation receipt.
+
+After interruption, check [get_revit_operation](get_revit_operation.md) before an identical retry with original `_operation_id`, version, document, and inputs. Client cancellation does not stop running C#. Follow [operation recovery](../operation-recovery.md) and inspect actual model/file/UI effects when uncertain. Use [visual verification](../visual-verification.md) for visible results. Library metadata and a returned response do not prove that a requested model outcome is correct.
+
+## Compatibility
+
+Contract source: `extensions/pi-revit/script-library.ts`, with dispatch through `extensions/pi-revit/index.ts`. Local storage operations depend on the package; run also depends on the bridge's `execute_csharp` contract and operation-tracking support. Check unfamiliar API members using [search_api_docs](search_api_docs.md) for the selected Revit version before saving/running code.

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

@@ -0,0 +1,90 @@
+# manage_schedules
+
+## Purpose and boundaries
+
+Create or configure a regular schedule as one atomic model-edit step. Templates, titleblock revision schedules, embedded schedules, and calculated/combined-field authoring are outside this tool. Use `get_schedules` to inspect definitions and displayed cells, `get_schedule_fields` to discover eligible additions, and `manage_sheet_placements` for sheet layout.
+
+Contract: PI-Revit 0.5.0 source, [ManageSchedules.cs](../../../../src/Revit/Tools/ManageSchedules.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 documents only; the bridge refuses other documents before running, with the route to use instead.
+- **Verify the outcome:** `reread`: query the changed state again with a read tool.
+- **Contract hash:** `d713a59aeac1e65c`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `action` | string | yes |  | `create`, `configure` |
+| `schedule_id` | integer | no |  |  |
+| `category` | string | no |  |  |
+| `name` | string | no |  |  |
+| `area_scheme_id` | integer | no |  |  |
+| `is_itemized` | boolean | no |  |  |
+| `preview` | boolean | no |  |  |
+| `add_fields` | array of object | no |  |  |
+| `update_fields` | array of object | no |  |  |
+| `sort_fields` | array of object | no |  |  |
+| `filters` | array of object | 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 |
+| --- | --- |
+| 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. |
+| Schedule templates, titleblock revision schedules and embedded schedules | Revit API: ViewSchedule and ScheduleDefinition members; verify with search_api_docs. Check all its members in one call: `search_api_docs` with query `ViewSchedule; ScheduleDefinition`, then use `execute_csharp` within the requested scope. |
+| Placing a schedule on a sheet | Tool: manage_sheet_placements |
+<!-- generated:contract:end -->
+
+## Inputs and preconditions
+
+Follow [execution rules](../execution-rules.md). There are two different field identities: eligible additions use `parameter_id` plus case-sensitive `field_type`; existing schedule fields use schedule-local `field_id`. Never infer either from a column position.
+
+| Input | Meaning |
+| --- | --- |
+| `action` | Required: `create` or `configure`. |
+| `category`, `name` | Both required for creation. Category is a supported category name/enum; optional nonempty `name` can rename during configure. A name another schedule already uses is rejected with `name_collision` and that schedule's ID; do not edit or rename the existing schedule unless the user asks. |
+| `area_scheme_id` | Creation-only option for area schedules. Category and area scheme are rejected during configure. |
+| `schedule_id` | Required existing regular schedule ID for configure. |
+| `is_itemized` | Optional boolean controlling whether instances remain separate. |
+| `add_fields` | At most 50 objects with required `field_type`, usually `parameter_id`, and optional `heading`, `hidden`, `width`, `unit`. |
+| `update_fields` | At most 50 objects with required actual `field_id`, and optional `heading`, `hidden`, `width`, `unit`. Duplicate update IDs are rejected. |
+| `sort_fields` | At most 4 objects with `field_id`, optional `descending` and `show_header` (both default false). Replaces the whole sort list when supplied. |
+| `filters` | At most 8 objects, described below. Replaces the whole filter list when supplied. |
+| `preview` | Default `false`; commit-validates then rolls back model changes. |
+| `expected_document_id` | Required for create/configure, including previews; exact current overview identity. |
+| `_operation_id` | Optional extension argument only for an identical retry. Omit for a new operation. |
+
+Omit `sort_fields` or `filters` to preserve the existing list; `[]` explicitly clears it. A positive field `width` requires a length `unit` (`millimeters`, `centimeters`, `meters`, `feet`, or `inches`) and updates grid and sheet widths together.
+
+For additions, pass a returned eligible `parameter_id`/`field_type` pair unchanged, including negative built-in parameter IDs. Count also supports `{ "field_type": "Count" }` without a parameter ID. If a Count pair is supplied it must be eligible; never guess its ID. Discover on a committed schedule, add fields, then reread the committed fields before writing sort/filter rules. Newly created schedule IDs and added field IDs from previews cannot be reused.
+
+Each filter requires `field_id`, `comparison` (`equals`, `not_equals`, `contains`, `greater_than`, `less_than`), `value_type` (`string`, `number`, `integer`, `element_id`), and a matching `value`. Measured `number` filters require an explicit unit compatible with the field specification, such as `meters` or `squareMeters`; omit units for unitless numbers. Use `get_schedules` metadata `spec_type_id`, `can_filter_value`, and `can_filter_substring` to inspect capabilities. Read results express numeric filter values in internal units and comparisons as Revit enum names, not the write strings above.
+
+## Example
+
+Create a preview with a Count field; this does not guess any parameter ID. Use a valid unique name for the intended document.
+
+```json
+{
+  "action": "create",
+  "category": "OST_Walls",
+  "name": "Wall count review",
+  "is_itemized": false,
+  "add_fields": [{ "field_type": "Count", "heading": "Count", "width": 25, "unit": "millimeters" }],
+  "preview": true,
+  "expected_document_id": "<project.documentId>"
+}
+```
+
+## Results, recovery and verification
+
+Inspect `committed`, `succeeded`, `proposed`, `failed`, `commitWarnings`, and `commit_validation_performed`. The single step returns schedule ID/unique ID/name, `created`, `id_is_temporary`, `added_field_ids`, `added_field_ids_are_temporary`, itemization, and field/filter/sort counts. Any rejected property rolls back this whole step.
+
+Read the committed definition and all required body row/column pages through `get_schedules`. Returned grid/sheet widths use feet. Body rows may be headings, groups, or totals; their row indices are not element IDs. To check layout, place the committed schedule on a sheet within the task scope and follow [visual verification](../visual-verification.md); standalone schedules cannot be captured by `capture_view`.
+
+Follow [operation recovery](../operation-recovery.md) for uncertain outcomes. A real edit after preview needs a new operation ID. This tool does not save or export the model.

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

@@ -0,0 +1,66 @@
+# manage_selection
+
+## Purpose and boundaries
+
+Read or change Revit's host-element selection, zoom to elements, or apply Temporary Hide/Isolate in the active view. Query with `get_elements` first, then pass returned IDs; selection has no inline element filter. Linked element IDs are not host IDs.
+
+Contract: PI-Revit 0.5.0 source, [ManageSelection.cs](../../../../src/Revit/Tools/ManageSelection.cs) and [DocumentGuard.cs](../../../../src/Revit/Tools/DocumentGuard.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, 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:** `0108ff205d518aaa`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `action` | string | no |  | `get`, `set`, `add`, `remove`, `clear`, `zoom` |
+| `element_ids` | array of integer | no |  |  |
+| `isolate_in_view` | 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 |
+| --- | --- |
+| Permanent hiding or view visibility changes | Revit API: View.HideElements; View.SetCategoryHidden. Check all its members in one call: `search_api_docs` with query `View.HideElements; View.SetCategoryHidden`, then use `execute_csharp` within the requested scope. |
+| Saved 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. |
+<!-- generated:contract:end -->
+
+## Inputs and preconditions
+
+| Input | Meaning |
+| --- | --- |
+| `action` | `get` (default), `set`, `add`, `remove`, `clear`, or `zoom`. |
+| `element_ids` | Host element IDs. Required and nonempty for `set`/`add`/`remove`. Zoom uses them when supplied; otherwise it uses the current nonempty selection. Use `clear` to empty selection. |
+| `isolate_in_view` | Default `false`. Temporarily isolates the resulting selection or zoom targets. An empty target set resets Temporary Hide/Isolate. Requires an active graphical view. |
+| `expected_document_id` | Optional in the public schema and for plain `get`, but required at execution for every non-`get` action and whenever `isolate_in_view: true`, including with `get`. A supplied identity is always checked. |
+| `_operation_id` | Optional extension argument only for an identical retry. Omit for a new operation. |
+
+Read [execution rules](../execution-rules.md) for document targeting. Use `get` when the user refers to the current selection. Invalid IDs are reported in `not_found` if valid IDs remain; a request containing IDs but no valid targets fails. Duplicate IDs are resolved once.
+
+## Example
+
+Illustrative IDs must be replaced with discovered host IDs. The identity is copied unchanged from the intended model's overview.
+
+```json
+{
+  "action": "set",
+  "element_ids": [12345, 12346],
+  "isolate_in_view": true,
+  "expected_document_id": "<project.documentId>"
+}
+```
+
+To reset isolation explicitly, use `action: "clear"` with `isolate_in_view: true` and the exact identity; this also clears selection.
+
+## Results, effects and recovery
+
+`get` returns `count` and element identities. Changes return `selectedCount`; zoom returns `shownCount`. Isolation reports `viewId`, `viewName`, `isolatedCount` or `temporaryIsolateReset`, and any `commitWarnings`.
+
+Selection and zoom alter UI state. Isolation changes temporary view state through a small internal transaction. The tool is read-classified but declares possible `ui` and `model` effects; classification is not permission to mutate. There is no `preview` or all-or-nothing contract covering selection plus isolation. Selection/zoom may already have completed when isolation fails; those effects are not rolled back.
+
+Read selection again or inspect the actual view to verify the requested result; use [visual verification](../visual-verification.md) for visible focus/isolation outcomes. For an uncertain result, follow [operation recovery](../operation-recovery.md) and inspect existing UI state before repeating. This does not save the model.

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

@@ -0,0 +1,82 @@
+# manage_sheet_placements
+
+## Purpose and boundaries
+
+List, place, or move viewports and schedule instances on a drawing sheet. This tool positions existing committed views; it does not create the source view or schedule. Coordinates are paper-space sheet coordinates, never multiplied by view scale.
+
+Contract: PI-Revit 0.5.0 source, [ManageSheetPlacements.cs](../../../../src/Revit/Tools/ManageSheetPlacements.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 documents only; the bridge refuses other documents before running, with the route to use instead.
+- **Verify the outcome:** `capture`: capture the visible result and inspect the image.
+- **Contract hash:** `1d9fd57c25d68159`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `action` | string | yes |  | `list`, `place`, `move` |
+| `sheet_id` | integer | no |  |  |
+| `view_id` | integer | no |  |  |
+| `placement_id` | integer | no |  |  |
+| `position` | array of number | no |  |  |
+| `unit` | string | no |  | `millimeters`, `centimeters`, `meters`, `feet`, `inches` |
+| `rotation` | string | no |  | `none`, `clockwise`, `counterclockwise` |
+| `offset` | integer | no |  |  |
+| `limit` | integer | 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 |
+| --- | --- |
+| Creating the source view or schedule | Tool: manage_views; manage_schedules |
+| Rotating schedule instances | Revit API: ScheduleSheetInstance.Rotation. Check all its members in one call: `search_api_docs` with query `ScheduleSheetInstance.Rotation`, then use `execute_csharp` within the requested scope. |
+| Changing the titleblock | Tool: change_element_types on the titleblock instance |
+<!-- generated:contract:end -->
+
+## Inputs and preconditions
+
+Follow [execution rules](../execution-rules.md); discover the intended sheet, source view/schedule, and current placements first.
+
+| Input | Meaning |
+| --- | --- |
+| `action` | Required: `list`, `place`, or `move`. |
+| `sheet_id` | Required for list/place. Optional for move as an extra check that the placement belongs to that sheet. |
+| `view_id` | Required for place: committed view or schedule ID. |
+| `placement_id` | Required for move: existing viewport or schedule-instance ID, not its source view ID. |
+| `position`, `unit` | Required for place/move: finite `[x,y,0]` in explicit `millimeters`, `centimeters`, `meters`, `feet`, or `inches`. |
+| `rotation` | Optional viewport-only `none`, `clockwise`, or `counterclockwise`. Omit entirely for schedules, including when no rotation is intended. |
+| `offset`, `limit` | List paging: nonnegative offset; limit default 100, range 1–200. |
+| `preview` | Edit default `false`; commit-validates then rolls back. List does not perform a preview/edit. |
+| `expected_document_id` | Required for every action, including `list`, because the tool is write-capable. Copy the intended model's current overview identity. |
+| `_operation_id` | Optional extension argument only for an identical retry. Omit for a new operation. |
+
+A viewport position is its box center excluding the label; a schedule position is its insertion point. Z must be zero. Pinned placements cannot be moved. Placeholder sheets cannot receive content. Revit validates view/schedule eligibility and can reject a view already placed elsewhere.
+
+## Example
+
+Illustrative sheet and source view IDs must be replaced with actual committed IDs. This previews placement at paper-space coordinates.
+
+```json
+{
+  "action": "place",
+  "sheet_id": 23456,
+  "view_id": 34567,
+  "position": [200, 150, 0],
+  "unit": "millimeters",
+  "preview": true,
+  "expected_document_id": "<project.documentId>"
+}
+```
+
+## Results, recovery and verification
+
+List returns `total_count`, `counts`, `returned_count`, `next_offset`, and `placements`; follow all pages. `counts` covers the whole sheet: `viewports`, `schedules`, and `titleblock_revision_schedules`. A titleblock revision schedule is part of the titleblock family, not content anyone placed, so it has its own `kind: "titleblock_revision_schedule"` and cannot be moved. A sheet with no views or schedules placed has zero `viewports` and `schedules`, even if its titleblock shows a revision schedule. <!-- inv:special-objects-flagged --> Placement descriptions include IDs, `kind`, sheet/source IDs, position, `position_kind`, and `traits` where applicable. Returned positions always use feet; viewport rotation returns Revit enum names.
+
+Edits return common transaction fields: `committed`, `succeeded`, `proposed`, `failed`, `commitWarnings`, `commit_validation_performed`. The step contains `before`, `placement`, `created`, and `id_is_temporary`. Each edit is one step; failure rolls it back. New placement IDs from preview are temporary and must not be reused.
+
+Reread placements and follow [visual verification](../visual-verification.md): inspect the actual sheet, labels, schedule extents, margins, and overlaps. Position values alone do not establish a readable layout. Follow [operation recovery](../operation-recovery.md) before repeating an uncertain placement. This does not save or export the model.

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

@@ -0,0 +1,71 @@
+# manage_sheets
+
+## Purpose and boundaries
+
+Create a drawing sheet or update its name/number. Use `manage_sheet_placements` to place or move views and schedules; `get_elements` to inspect sheets; `open_view` to activate a committed sheet; and `delete_elements` for removal.
+
+Contract: PI-Revit 0.5.0 source, [ManageSheets.cs](../../../../src/Revit/Tools/ManageSheets.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 documents only; the bridge refuses other documents before running, with the route to use instead.
+- **Verify the outcome:** `reread`: query the changed state again with a read tool.
+- **Contract hash:** `6e201549acd231ea`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `action` | string | yes |  | `create`, `update` |
+| `sheet_id` | integer | no |  |  |
+| `name` | string | no |  |  |
+| `number` | string | no |  |  |
+| `titleblock_type_id` | integer | 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 |
+| --- | --- |
+| Placing views or schedules on a sheet | Tool: manage_sheet_placements |
+| Revisions and revision clouds | Revit API: Revision.Create; RevisionCloud.Create. Check all its members in one call: `search_api_docs` with query `Revision.Create; RevisionCloud.Create`, then use `execute_csharp` within the requested scope. |
+| Deleting sheets | Tool: delete_elements |
+<!-- generated:contract:end -->
+
+## Inputs and preconditions
+
+| Input | Meaning |
+| --- | --- |
+| `action` | Required: `create` or `update`. |
+| `name`, `number` | Both required nonempty strings for creation; individually optional for update. Revit validates text; sheet names may repeat. A number another sheet already uses is rejected before Revit is asked: the failed row carries `name_collision` with that sheet's ID. That sheet predates the call; do not renumber or edit it to free the number unless the user asks. |
+| `sheet_id` | Required existing sheet ID for update. |
+| `titleblock_type_id` | Creation only: loaded titleblock `FamilySymbol`. Omission creates a sheet without a titleblock. Rejected for update. |
+| `preview` | Default `false`; commit-validates then rolls back the model changes. |
+| `expected_document_id` | Required for all calls, including previews; exact current `project.documentId`. |
+| `_operation_id` | Optional extension argument only for an identical retry. Omit for a new operation. |
+
+Follow [execution rules](../execution-rules.md). Discover loaded titleblock types with `get_element_types`, category `OST_TitleBlocks`. To change an existing titleblock type, identify its instance and call `change_element_types`; do not pass a type override to sheet update.
+
+## Example
+
+The example intentionally creates a sheet without a titleblock; discover and add `titleblock_type_id` when the task needs one. The number must be available in the intended model.
+
+```json
+{
+  "action": "create",
+  "name": "Room documentation",
+  "number": "A-901",
+  "preview": true,
+  "expected_document_id": "<project.documentId>"
+}
+```
+
+## Results, recovery and verification
+
+Inspect `committed`, `succeeded`, `proposed`, `failed`, `commitWarnings`, and `commit_validation_performed`. One step contains `before` where relevant, `sheet` (ID, unique ID, name, number, placeholder state), `created`, and `id_is_temporary`.
+
+All properties are part of the same step, so a rejected number/name/titleblock rolls that step back. Preview-created sheet IDs are temporary and cannot be used for placements. Use the committed ID, verify name/number/titleblock, and follow [visual verification](../visual-verification.md) for the actual sheet layout.
+
+Follow [operation recovery](../operation-recovery.md) after an uncertain outcome. A real creation after preview is a new operation. This tool neither saves the model nor exports the sheet; those actions need to be within the user's requested scope.

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

@@ -0,0 +1,95 @@
+# manage_views
+
+## Purpose and boundaries
+
+Create plan, isometric 3D, or section views; duplicate a view; or update its name, scale, and template. Each call is one model-edit step. Use `get_elements` to query views, `open_view` to activate a committed view, and `delete_elements` to remove one.
+
+Contract: PI-Revit 0.5.0 source, [ManageViews.cs](../../../../src/Revit/Tools/ManageViews.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:** `capture`: capture the visible result and inspect the image.
+- **Contract hash:** `a8633ed43c6fb869`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `action` | string | yes |  | `create_plan`, `create_3d`, `create_section`, `duplicate`, `update` |
+| `view_id` | integer | no |  |  |
+| `view_family_type_id` | integer | no |  |  |
+| `level_id` | integer | no |  |  |
+| `duplicate_option` | string | no |  | `duplicate`, `with_detailing`, `dependent` |
+| `name` | string | no |  |  |
+| `scale` | integer | no |  |  |
+| `view_template_id` | integer | no |  |  |
+| `unit` | string | no |  | `millimeters`, `centimeters`, `meters`, `feet`, `inches` |
+| `origin` | array of number | no |  |  |
+| `viewing_direction` | array of number | no |  |  |
+| `up` | array of number | no |  |  |
+| `width` | number | no |  |  |
+| `height` | number | no |  |  |
+| `depth` | 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 |
+| --- | --- |
+| Perspective (camera) 3D views | Revit API: View3D.CreatePerspective; ViewOrientation3D. Check all its members in one call: `search_api_docs` with query `View3D.CreatePerspective; ViewOrientation3D`, then use `execute_csharp` within the requested scope. |
+| Elevation, drafting and legend views | Revit API: ElevationMarker.CreateElevationMarker; ViewDrafting.Create. Check all its members in one call: `search_api_docs` with query `ElevationMarker.CreateElevationMarker; ViewDrafting.Create`, then use `execute_csharp` within the requested scope. |
+| View visibility and graphics (hiding, overrides, crop regions) | Revit API: View.SetCategoryHidden; View.HideElements; View.SetElementOverrides; View.CropBox. Check all its members in one call: `search_api_docs` with query `View.SetCategoryHidden; View.HideElements; View.SetElementOverrides; View.CropBox`, then use `execute_csharp` within the requested scope. |
+| Deleting views | Tool: delete_elements |
+<!-- generated:contract:end -->
+
+## Inputs and preconditions
+
+Follow [execution rules](../execution-rules.md). Discover compatible `ViewFamilyType` IDs using `get_element_types` with `of_class: "ViewFamilyType"`; find level and existing view IDs with `get_elements`.
+
+| Input | Meaning |
+| --- | --- |
+| `action` | Required: `create_plan`, `create_3d`, `create_section`, `duplicate`, or `update`. |
+| `view_family_type_id` | Compatible positive type ID, required for creation actions. A 3D view is isometric. |
+| `level_id` | Required positive level ID for `create_plan`. |
+| `view_id` | Required positive existing view ID for duplicate/update. |
+| `duplicate_option` | `duplicate` (default), `with_detailing`, or `dependent`; the view must support the selected option. |
+| `name` | Optional nonempty view name, applied in the same step. A name another view of the same type already uses is rejected: the failed row carries `name_collision` with the existing view's ID, and nothing is renamed or created. |
+| `scale` | Optional integer 1–24000; rejected when unavailable or controlled by the view template. |
+| `view_template_id` | Optional compatible template ID, or `-1` to intentionally remove a template. The tool does not remove a template implicitly to change scale. |
+| `unit`, `origin`, `viewing_direction`, `up`, `width`, `height`, `depth` | Required for a section; details below. |
+| `preview` | Default `false`; commit-validates then rolls back the model changes. |
+| `expected_document_id` | Required for all calls, including previews; exact current overview identity. |
+| `_operation_id` | Optional extension argument only for an identical retry. Omit for a new operation. |
+
+A section uses document internal coordinates. `unit` is `millimeters`, `centimeters`, `meters`, `feet`, or `inches`; it applies to finite `[x,y,z]` `origin` and all dimensions. `viewing_direction` and `up` are nonzero, orthogonal dimensionless vectors. Width/height extend symmetrically around the origin; depth extends along the viewing direction. Dimensions must be positive and exceed 0.000001 feet after conversion. These are model coordinates, not sheet placement coordinates.
+
+## Example
+
+IDs `34567` and `45678` are illustrative; discover the compatible plan type and level first.
+
+```json
+{
+  "action": "create_plan",
+  "view_family_type_id": 34567,
+  "level_id": 45678,
+  "name": "Room review plan",
+  "scale": 50,
+  "preview": true,
+  "expected_document_id": "<project.documentId>"
+}
+```
+
+## Results, recovery and verification
+
+Inspect `committed`, `succeeded`, `proposed`, `failed`, `commitWarnings`, and `commit_validation_performed`. The step returns `before` where relevant, a `view` description (ID, unique ID, name, type, template, scale), `created`, and `id_is_temporary`.
+
+A duplicate carries its source's visibility and graphics. Its row reports `inherited_state`: `derived_from`, `template`, `hidden_categories` (`OST_` identity and localized name), `hidden_elements` (count, sample IDs, whether the bounded scan completed), `filters` with their visibility, element and category override counts, and display settings. Compare it with the request before reporting: unhide what the request asks to show (View.UnhideElements, View.SetCategoryHidden through the API route), or disclose what stays hidden. The result's `model_changes` lists what the call added and modified.
+
+A `name_collision` means the named view existed before this call. Do not edit, rename, reuse or delete it to get past the collision; ask the user, or choose a distinct name and report the collision.
+
+Created/duplicated preview IDs are temporary; never use them in a later tag, placement, or capture call. Commit first and use the committed ID. A failure in name, template, scale, or creation rolls back the single step. Read back the committed view settings and use [visual verification](../visual-verification.md) to inspect framing, orientation, crop, and readability.
+
+Follow [operation recovery](../operation-recovery.md) for an uncertain outcome. A real creation after a preview uses a new operation ID. Creating a view does not activate it or save the model.