pi-revit 0.3.1 → 0.4.0

package/README.md

@@ -45,8 +45,10 @@ enforce mechanically, and is honest about what it cannot:
 - Parameter writes, C# scripts, temporary isolation, and IFC export own named Revit
   transactions. Failure handling is attached after transaction start, and results
   check transaction outcomes before claiming commit or rollback. `set_parameters`
-  can commit a partially successful batch; inspect every failed update and
-  `commitWarnings`. An unconfirmed rollback is reported as such.
+  defaults to partial success; `atomic: true` rolls back the batch if any update
+  fails, and `preview: true` rolls back proposed model changes after validation.
+  Inspect every failed update, the validation status, and `commitWarnings`.
+  An unconfirmed rollback is reported as such.
 - `execute_csharp` is an unrestricted escape hatch by design — scripts have full CLR access.
   Treat it like giving the agent a macro editor, on a model you have saved or can restore.
 - `execute_csharp` has a dialog guard that attempts dismissive responses to dialogs
@@ -70,8 +72,13 @@ unchanged into `expected_document_id` on subsequent operations:
 ```
 
 Replace the placeholders with the current document ID and an actual element ID.
-The exact ID is required for `set_parameters`, `execute_csharp`,
-`export_documents`, and `open_view`. It is also required for selection/zoom
+The exact ID is required for `set_parameters`, `transform_elements`,
+`delete_elements`, `change_element_types`, `manage_views`, `manage_sheets`,
+`manage_sheet_placements`, `manage_schedules`, `create_tags`, `execute_csharp`,
+`export_documents`, and `open_view`,
+including supported previews. `manage_sheet_placements` requires it even for its
+read-only `list` action because the tool is classified as write-capable.
+It is also required for selection/zoom
 changes and any `manage_selection` call with `isolate_in_view: true`, including
 action `get`. Pure reads may omit it; a supplied ID is always checked.
 
@@ -208,22 +215,416 @@ Plain `pi` from any folder also works; `pi-revit` just adds the right working fo
 
 ## Tools
 
-| Tool | What it does |
-|---|---|
-| `ping` | Is the bridge reachable? Revit version |
-| `get_model_overview` | Project info, units, levels, grids, category counts — call first |
-| `get_elements` | Query/count elements of any category: parameter filters, pagination |
+| Tool | What it does |
+|---|---|
+| `find_revit_tools` | Search the native tool catalogue and activate specialist tools for the current Pi session. |
+| `ping` | Is the bridge reachable? Revit version |
+| `manage_revit_instances` | List reachable local Revit sessions or select the target for this Pi session |
+| `get_model_overview` | Project info, units, levels, grids, category counts — call first |
+| `get_model_coordinates` | Read base points and site/project locations; map internal points through the active shared coordinates |
+| `get_elements` | Query/count elements: parameter filters, optional parameter values, pagination |
+| `summarize_elements` | Count all matching elements by category, type, level, or raw parameter value |
+| `manage_element_sets` | Create, list, read, or forget temporary snapshots of matching host elements |
 | `get_element_details` | Parameter values, location, bounding box, materials per element |
-| `get_element_types` | Element types / family symbols, optional placed-instance counts |
+| `get_element_types` | Element types / family symbols, optional placed-instance counts |
+| `get_linked_models` | Direct Revit link instances, load status, document identities, placement transforms |
+| `get_linked_elements` | Query/count one loaded link, with optional bounding boxes in host coordinates |
+| `query_spatial_elements` | Find host elements by approximate bounding-box intersection or containment in a region |
+| `measure_geometry` | Measure exact point distance or approximate host-element bounding-box separation |
+| `get_schedules` | List schedules or read fields, widths, specifications, sort/filter rules, and displayed cells |
+| `get_schedule_fields` | Discover eligible field parameter/type pairs for an existing schedule |
+| `manage_schedules` | Create or configure regular schedules, including fields, widths, sorting, and filters |
+| `create_tags` | Create host element, room, space, or area tags, with partial/atomic batches and preview |
+| `get_element_relationships` | Host, type, level, members, joined geometry, and logical dependents of one element |
 | `manage_selection` | Get/set/clear the selection, zoom, temporary isolate |
 | `open_view` | Activate a view or sheet in the Revit UI (like double-clicking it in the browser) |
-| `set_parameters` | Bulk parameter writes + rename anything (one transaction per batch) |
+| `set_parameters` | Bulk parameter writes and renames, with previews and optional atomic batches |
+| `transform_elements` | Move, copy, or rotate a whole selection, with explicit units and preview |
+| `delete_elements` | Preview or delete selected elements and report Revit's full deletion set |
+| `change_element_types` | Change types per target, with preview and optional atomic rollback |
+| `manage_views` | Create plans, isometric 3D views, or sections; duplicate or update views |
+| `manage_sheets` | Create, rename, or renumber sheets, with an optional titleblock at creation |
+| `manage_sheet_placements` | List, place, or move viewports and schedule instances in sheet paper space |
 | `search_api_docs` | Search the offline Revit API docs (works with no document open) |
-| `execute_csharp` | Run a C# script in one auto-managed transaction — the escape hatch |
+| `execute_csharp` | Run a C# script with separate JSON inputs in one auto-managed transaction |
+| `manage_revit_scripts` | Save immutable local script versions, inspect source, run an exact version, and read history |
 | `capture_view` | PNG snapshot of a view to a temp file (read the returned path to see it) |
 | `export_documents` | PDF/DWG/PNG/IFC export of sheets and views — sorted into `Models\<title>--<identity hash>\exports` |
 | `get_model_health` | Warnings grouped + worksets, phases, design options audit |
 | `read_revit_result` | Read bounded fragments of a saved large tool result; extension-only, no Revit call |
+| `get_revit_operation` | Inspect a bridge operation receipt and its retained result without waiting for the model thread |
+
+### Choose a Revit instance
+
+`manage_revit_instances` defaults to `action: "list"`. It reports reachable
+local bridge sessions with an opaque `bridge_id`, process ID, Revit/add-in
+versions, selection status, and operation-tracking support. Choose the intended
+session with `action: "select"` and the exact returned `bridge_id`. Selection
+belongs to the current Pi extension session; it does not activate a document
+or change the model.
+
+When the first connection finds a sole instance, Pi binds to it automatically.
+If several instances are available before a target is bound, explicitly select
+one before model calls. Once bound, Pi keeps that exact bridge session. If it
+closes or restarts, calls fail instead of switching to another instance, even
+when only one remains. List again and explicitly select the intended new
+identity. Selection refreshes the tool catalogue; check `tool_catalog_ready`,
+and retry `ping` if discovery has not completed. Then read `get_model_overview`
+for a fresh document identity before continuing work.
+
+Each current bridge publishes its own discovery file in
+`%APPDATA%\RevitBridge\instances\<bridgeId>.json`. The legacy `bridge.json`
+discovery file is still supported. Older bridges without a generation ID receive
+an opaque hash selector in the instance list; copy it unchanged rather than
+constructing one. Legacy discovery can expose only the older instance named by
+that shared file, so updating each add-in enables discovery of all instances.
+
+Operation receipts and identical `_operation_id` retries route to the original
+bridge encoded in the operation ID, even after selecting a different instance.
+They do not switch the target for new calls. If the original bridge is unavailable,
+the request fails without sending the action to another session.
+
+### Read project coordinates
+
+`get_model_coordinates` reads project/survey base points, the active project
+location, site data, and paginated project locations. Supply a length `unit`;
+optional `points` accepts up to 100 positions along document internal axes.
+Revit's active project location maps those points to shared coordinates. Returned
+lengths use the requested unit, while angles and latitude/longitude use degrees.
+Location pages default to 50 entries (maximum 100); follow `next_offset`.
+The tool requires a project document, makes no coordinate changes, and does not
+infer a GIS coordinate reference system or datum.
+
+### Query regions and measure distances
+
+`query_spatial_elements` takes a region `min`/`max` in the document's internal
+axes and an explicit length `unit`. It compares host-element axis-aligned
+bounding boxes with the region, using `intersects` (default) or `inside`.
+Containment requires the whole box to fit; touching boundaries are included.
+The nested `query` uses whole-scope element filters and must match at most
+10,000 candidates before region testing. Query-level paging and projections
+are not accepted. Results sort by element ID with outer paging (default 100,
+maximum 200); follow `next_offset`. `without_bounds_count` reports candidates
+omitted because they have no model bounding box.
+
+`measure_geometry` measures exact Euclidean distance between supplied points
+with `mode: "point_distance"`, or approximate bounding-box separation between
+two host elements with `mode: "bounding_box_gap"`. Point mode returns signed
+A-to-B `delta`; box mode returns nonnegative axis gaps. The required `unit`
+applies to all inputs and outputs: millimeters, centimeters, meters, feet, or
+inches. Both modes use document internal axes; linked contents are not traversed.
+
+Bounding-box gaps are lower bounds on geometry separation. Boxes can enclose
+nonphysical geometry, so touching/overlapping boxes do not establish a clash.
+An optional nonnegative `clearance` in box mode flags gaps strictly below that
+threshold; it identifies review candidates, not verified clearance failures.
+Keep the returned method and approximation status with any reported result.
+
+Practical workflows are available in the Pi skill references:
+[room documentation](skills/pi-revit/references/room-documentation.md) and
+[model audit and export](skills/pi-revit/references/model-audit-export.md).
+
+### Read parameter values and summarize queries
+
+Add `parameter_names` to `get_elements` to read up to 20 requested parameters
+alongside element identity fields. Names can be display names, built-in parameter
+names, or `guid:<GUID>` identities. `include_type_parameters: true` also reads
+those parameters from each element's type. Projections expose missing and
+ambiguous matches and include every matching parameter. Raw `value` uses Revit
+internal units for measurable numbers; `displayValue` uses document formatting.
+Bare counts return no parameter projections.
+
+`summarize_elements` groups a host-element `query` by `category`, `typeName`,
+`levelId`, or `parameter`. Parameter grouping uses exact raw values, with a
+separate missing-parameter group, and rejects ambiguous display names. Set
+`type_parameter: true` to group by a parameter on the type. The outer
+`offset`/`limit` pages groups (default 100, maximum 500); counts always cover the
+whole matching scope.
+
+`summarize_elements` and element-set creation accept category, class, level,
+type, active-view, and parameter filters inside `query`. They reject query-level
+paging, projections, and `count_only`, and require at most 10,000 matching
+elements. Narrow larger queries; an omitted query covers all host instances.
+
+### Reuse an element set
+
+Use `manage_element_sets` with `action: "create"` to snapshot query membership,
+then `read` its `set_id`, `list` active-document sets, or `forget` a set. This
+changes neither the model nor selection. The bridge retains at most 32 sets;
+each expires 30 minutes after creation and belongs to the exact open document
+and bridge session. Reads do not renew it. Reopening the document or restarting
+the bridge requires a fresh set.
+
+Read pages return current values for the original members, without reapplying
+the query. Deleted or identity-changed members appear in `missing`. Check those
+entries before passing surviving IDs to other tools. Pages default to 100
+members (maximum 1000); follow `next_offset`, which includes missing members in
+`visited_count`. Set reads also support `parameter_names` and
+`include_type_parameters`.
+
+### Preview parameter changes
+
+`set_parameters` accepts 1–200 updates and defaults to committing successful
+updates while reporting failures. Each update has its own subtransaction.
+`atomic: true` rolls back the entire batch if any update fails. `preview: true`
+performs eligible commit checks inside a transaction group, then rolls the
+group back. Both options require the same exact document identity as an ordinary
+write and can be combined.
+
+Read `commit_validation_performed`: an atomic batch rejected before commit, or
+a batch with no accepted updates, has not passed commit-time validation.
+Successful preview responses confirm model rollback. Errors report the cleanup
+outcome instead; inspect it before retrying.
+
+Only committed updates appear in `succeeded`. Accepted steps from previews or
+rolled-back batches appear in `proposed`, with `updated: 0` and
+`committed: false`. Their `before`/`after` values describe each step in input
+order, identified by its zero-based `index`. Repeated writes can have intermediate
+values; reread the element when final values matter. Inspect `failed` and
+`commitWarnings` as well. Numeric write inputs use the explicit `unit` or the
+document's display units; raw numeric values in the returned snapshots use
+Revit internal units.
+
+### Transform, delete, and change types
+
+These advanced tools can be activated with `find_revit_tools`. They operate on
+the active host document and require `expected_document_id` for both previews
+and writes. Their results use the same `succeeded`, `proposed`, `failed`,
+`committed`, and commit-validation fields as parameter batches. `updated` counts
+steps: one whole-selection transform or deletion counts as one step.
+
+`transform_elements` moves, copies, or rotates 1–200 distinct `element_ids`
+together. Always supply `unit`: `millimeters`, `centimeters`, `meters`, `feet`,
+or `inches`. Move/copy takes a `translation` vector. Rotation takes an
+`axis_origin`, a nonzero dimensionless `axis_direction`, and signed right-hand
+`angle_degrees`. Coordinates refer to the document's internal origin and axes;
+returned location snapshots use feet, regardless of input units. The selection
+succeeds or rolls back as one step. Move/rotate rejects pinned requested
+elements; the tool never unpins them automatically. Copy previews return
+temporary `created_ids`, which must not be reused after rollback.
+
+`delete_elements` deletes 1–200 distinct requested elements in one step, rejecting
+pinned requested elements. Use `preview: true` to inspect Revit's complete
+`deleted_ids` set and its `dependent_ids`, with rollback. A cascade exceeding
+10,000 IDs rolls back. To check a later deletion against the preview, optionally
+pass the full `deleted_ids` as `expected_deleted_ids`; a changed set causes
+rollback before commit. This compares membership only. The actual deletion is
+a new request, not an identical retry of the preview, so do not reuse the
+preview's `_operation_id` for it.
+
+`change_element_types` accepts 1–200 `element_id`/`type_id` pairs in `updates`,
+with each target appearing once. Invalid types or pinned targets fail individually;
+other valid changes can commit by default. `atomic: true` rolls back the complete
+batch on any failure. Some type changes replace the original element: use the
+committed `resulting_id` and `unique_id` afterward. Replacement IDs reported in
+`proposed` are temporary after preview or atomic rollback.
+
+Transforms and type changes can affect constrained or hosted elements beyond
+the target snapshots. Deletion IDs cover elements returned by Revit's deletion
+API, not surviving elements Revit may also modify. Review these results as
+bounded descriptions of the operation, not a complete audit of every effect.
+
+### Create views and arrange sheets
+
+Activate `manage_views`, `manage_sheets`, and `manage_sheet_placements` through
+`find_revit_tools`. Edits support `preview: true` and require the exact document
+identity. Each call edits one view, sheet, or placement in one step. Created IDs
+in previews are marked `id_is_temporary` and must not be reused after rollback.
+Inspect the common transaction outcome and validation fields. Use `open_view`
+to display committed views/sheets and `delete_elements` to remove them.
+
+`manage_views` supports `create_plan`, `create_3d`, `create_section`, `duplicate`,
+and `update`. Creation uses a compatible `view_family_type_id`; discover it with
+`get_element_types` and `of_class: "ViewFamilyType"`. Plans also need `level_id`;
+3D creation produces an isometric view. Duplicate/update targets `view_id`.
+Duplication options are `duplicate`, `with_detailing`, and `dependent` where
+supported. Optional name, scale, and template apply in the same step. Template
+ID `-1` removes a template explicitly; incompatible templates or controlled
+scale changes fail without automatically removing the template.
+
+Sections use the document's internal coordinate frame. Supply `origin`, explicit
+length `unit`, orthogonal nonzero `viewing_direction` and `up`, and positive
+width/height/depth. Width and height center on the origin; depth extends in the
+viewing direction. Direction vectors are dimensionless.
+
+`manage_sheets` creates a sheet from `name` and `number`, optionally using a loaded
+titleblock `FamilySymbol` specified by `titleblock_type_id`. Omitting it creates
+a sheet without a titleblock. Updates use `sheet_id` and name/number; changing
+an existing titleblock type uses `change_element_types` on its instance instead.
+
+`manage_sheet_placements` lists both viewports and schedule instances for a
+`sheet_id` (default 100 per page, maximum 200). Follow `next_offset`. Although
+listing changes no model state, the tool's write-capable metadata means
+`expected_document_id` is required for this action too.
+
+To place content, supply `sheet_id`, `view_id`, explicit `unit`, and
+`position: [x,y,0]`; to move it, supply `placement_id`, unit, and position.
+Positions are paper-space sheet coordinates and must never be multiplied by
+view scale. Viewports use their box center excluding the label; schedules use
+their insertion point. Returned positions use feet and state `position_kind`.
+Viewports support rotation `none`, `clockwise`, or `counterclockwise`; omit
+rotation for schedules. Pinned placements cannot be moved, placeholder sheets
+cannot receive content, and Revit checks whether a view can be placed.
+
+### Configure schedules and create tags
+
+`manage_schedules` creates a regular schedule from `category` and `name`, with
+an optional `area_scheme_id` for area schedules. Configure an existing schedule
+with `schedule_id`. Each call is one atomic step, requires `expected_document_id`,
+and supports preview rollback. Revision schedules, templates, embedded schedules,
+and calculated/combined-field authoring are outside this tool.
+
+Use `get_schedule_fields` to discover eligible fields for an existing schedule.
+It supports localized name filtering and paging (default 100, maximum 200).
+`add_fields` identifies each field by its `parameter_id` plus `field_type` pair;
+negative built-in parameter IDs are valid. When Count appears in discovery,
+pass its returned pair unchanged, just like other fields. Count can also be
+added as `{ "field_type": "Count" }` without a parameter ID. A supplied pair
+must be eligible for the target schedule; do not guess its parameter ID.
+`included` marks pairs already present.
+
+In contrast, `update_fields`, `sort_fields`, and `filters` use the schedule-local
+`field_id` returned by `get_schedules`. These IDs are neither parameter IDs nor
+column indices. Read newly committed fields before assigning their sort/filter
+rules. New schedule and field IDs returned by previews are temporary.
+
+Field additions and updates support heading, hidden state, and width, with up
+to 50 entries each. Widths require explicit length units and apply to both grid
+and sheet columns. `sort_fields` allows four rules; `filters` allows eight.
+Supplying either array replaces its entire list, including clearing it with
+`[]`; omitting the property preserves it. `is_itemized` controls itemization.
+
+Filter comparisons are `equals`, `not_equals`, `contains`, `greater_than`, or
+`less_than`. Supply a matching `value_type` and value. Measured numeric filters
+require an explicit compatible `unit`; unitless numbers must omit it.
+`get_schedules` exposes each field's specification, filtering capabilities,
+grid/sheet widths in feet, and current sort/filter rules. Returned numeric filter
+values use internal units; returned comparison names use Revit enums rather
+than the write schema's comparison strings.
+
+`create_tags` accepts 1–100 host-document targets in one explicit view, using a
+loaded tag `FamilySymbol`. Choose `kind` as `element`, `room`, `space`, or `area`.
+Each target has `element_id` and `head_position: [x,y,z]` in document internal
+coordinates, using the required length `unit`. The position always means the
+tag head, including when `leader: true`; returned positions use feet. Linked
+targets and face/subelement references are unsupported.
+
+Element tags support horizontal/vertical orientation. Spatial tags require a
+compatible plan view and positions at the spatial element's level; omit their
+orientation property. Independent tags cannot use templates, perspective views,
+or unlocked 3D views. Creation requires exact document targeting, defaults to
+partial success, and supports `atomic: true` and `preview: true`. IDs in
+`proposed` are temporary after preview or atomic rollback; use only committed
+tag IDs for subsequent calls.
+
+### Inspect links, schedules, and relationships
+
+Call `get_linked_models` before querying a link. Pass its `link_instance_id` and
+`linked_document_id` to `get_linked_elements` as `link_instance_id` and
+`expected_linked_document_id`. The optional `expected_document_id` still identifies
+the active host model. Refresh discovery after unloading or reloading a link.
+Queries support `get_elements` filters and pagination, except active-view scoping.
+Unloaded links cannot be queried, and nested links are not traversed.
+
+Keep the full `reference` returned for each linked element: its numeric ID belongs
+to the linked document and must not be used with host selection or write tools.
+Different placements of one linked model can produce different host coordinates.
+Optional `host_bounds` use internal feet and enclose all eight transformed box
+corners; they are axis-aligned bounds, not exact geometry. A missing box is null.
+
+Use `get_schedules` without an ID to list schedules, or with `schedule_id` to read
+field definitions, width/specification metadata, sort/filter rules, and displayed
+body cells. Text follows Revit's formatting and
+can include grouped entries, headings, and totals; rows are not element IDs.
+Hidden field definitions need not correspond to displayed columns. Follow both
+`next_offset` and `next_column_offset`: finish the column pages for a row page
+before moving to the next rows. List/body pages default to 50 entries (maximum
+200); column pages default to 50 (maximum 50).
+
+`get_element_relationships` reports each requested relationship separately, with
+its own count and continuation offset. It reads host-document relationships only;
+logical dependents are not a complete deletion-impact prediction. In family
+documents, request relationship kinds that exclude `joined`. Relationship pages
+default to 100 entries (maximum 200). Link-instance pages default to 100 (maximum
+1000), and linked-element pages default to 200 (maximum 1000).
+
+### Reuse a script with structured inputs
+
+`execute_csharp` accepts an optional `inputs` JSON object separately from its
+source code. The script reads it through the `inputs` `JsonElement` global,
+for example `inputs.GetProperty("value").GetDouble()`. Inputs default to an
+empty object and are not interpolated into source text. Scripts validate their
+contents; the serialized object is limited to 100,000 characters.
+
+`manage_revit_scripts` stores reusable definitions under
+`%APPDATA%\pi-revit\scripts`. Its actions are `save`, `list`, `read`, `run`, and
+`history`. Saving requires a name, description, code, and `input_types`; it never
+executes the script. Versions are immutable 64-character SHA-256 hashes of the
+saved definition. Read a version to inspect its source, then explicitly run that
+exact name/hash with current `expected_document_id` and inputs. Runs verify
+saved content integrity and require a bridge with operation receipts.
+
+Up to 40 named `input_types` can be declared as string, number, integer, boolean,
+object, or array. Every declared input is required and extra inputs are rejected.
+Validation covers top-level kinds only: scripts still validate nested objects,
+array contents, ranges, units, and model-specific rules. The Pi skill includes
+a short save/read/run example using a numeric input.
+
+Library runs use unrestricted `execute_csharp`, with the same model, UI, file,
+and external effects, synchronous execution, transaction, and timeout behavior.
+There is no preview mode, scheduled execution, or automatic model saving. A saved
+script is not a saved Revit model.
+
+List/history pages default to 20 entries (maximum 100), with optional exact-name
+filtering. Local history stores version, document identity, input hash,
+timestamps, and receipt IDs, rather than raw inputs or results. History states
+record dispatch/response progress, not a model transaction outcome. After a
+timeout or interruption, inspect `get_revit_operation`; an identical retry uses
+the original `_operation_id`, script version, inputs, and document identity.
+
+### Check an operation after a timeout
+
+With a bridge that supports operation tracking, Pi automatically assigns an
+operation ID to each bridge tool call and includes it in responses or request
+errors. Call the native `get_revit_operation` tool with that `operation_id` to
+check progress or recover the original result. This extension tool contacts the
+operation's original local bridge directly, even when another instance is selected,
+so it works while Revit's model thread is busy or no
+document is open; the bridge must still be running.
+
+| Receipt state | Meaning |
+|---|---|
+| `queued` | Waiting to begin; no tool execution has started. |
+| `running` | Execution started; a client timeout or cancellation does not stop it. |
+| `succeeded` | The tool returned successfully; inspect its payload for the actual model outcome. |
+| `failed` | The call returned an error; this alone does not confirm rollback or absence of effects. |
+| `expired_before_start` | Its queue deadline passed before execution; no tool action was performed. |
+| `result_unavailable` | The tool finished, but a response could not be retained correctly; effects may already exist. |
+| `unknown` | This bridge session has no receipt; the outcome is unknown. |
+
+A successful receipt is not proof of a committed edit. For example, a completed
+parameter preview can have receipt state `succeeded` while its payload reports
+`preview: true`, `committed: false`, and proposed changes that were rolled back.
+Inspect `committed`, validation flags, failures, and warnings in the retained
+tool result.
+
+To retry the same request, pass its exact ID as `_operation_id` on the original
+tool call and preserve all original arguments. Within the same bridge session,
+this waits for the existing operation or returns its cached response; it never
+executes that ID a second time. Reusing the ID with a different tool or arguments
+is rejected. Omitting `_operation_id` creates a new operation, so establish the
+previous outcome before retrying an edit that way.
+
+The bridge retains at most 128 completed full results, with a combined 32 MiB
+limit. Older or oversized results can be evicted, but their receipt records
+remain reserved for the session and report `result_available: false`. Replaying
+an evicted result returns an error without repeating the action. At 10,000
+receipt records, new tracked calls are rejected; existing receipts remain
+queryable. A bridge restart clears all receipts and changes its identity. Old
+IDs cannot be replayed in the new session. An unavailable original bridge or an
+`unknown` receipt does not prove that an earlier edit never ran. Changing the
+selected instance does not redirect old receipts or retries. Inspect the original
+model before deciding on a new operation.
 
 ### Read complete results
 
@@ -260,23 +661,26 @@ allows a type-only result.
 
 ## Limitations — read before using on real projects
 
-- **Write tools are unrestricted by design.** `set_parameters` and `execute_csharp` modify the
-  open model directly — there is no confirmation prompt and no sandbox. Writes run in named
-  transactions (`execute_csharp` attempts rollback after script failure;
-  `set_parameters` commits partial successes and reports each failure). Read the
+- **Writes change the open model directly.** There is no confirmation prompt.
+  Typed editing tools provide preview and transaction outcomes; `execute_csharp`
+  remains unrestricted and attempts rollback after script failure. Parameter
+  and type-change batches default to partial success, with optional atomic rollback.
+  Transforms and deletions apply the whole selection in one step. Read the
   actual transaction outcome and failed lists. Script result-projection failure
   can leave a successful edit committed with a `returnValueError`; filesystem and
   UI effects are separate from model rollback.
 - The add-in multi-targets .NET 8 (Revit 2025/2026) and .NET 10 (Revit 2027); `deploy.ps1`
   auto-detects the Revit versions you have installed and builds only the matching framework(s),
-  so you only need the SDK for the Revit you run. The 0.3.0 changes were tested live
-  on Revit 2025.4.3 (build 25.4.30.30, German UI). Revit 2026/2027 and large-model
+  so you only need the SDK for the Revit you run. The 0.4.0 tools were tested in bounded live
+  workflows on Revit 2025. Revit 2026/2027 and large-model
   performance were not tested for this release. Export API/file checks do not
   establish full DWG drawing or IFC schema/geometry validation.
-- **One Revit instance at a time** is discoverable (last started wins). When that instance
-  closes or crashes, another one that is still running takes the slot over within 30s.
-- A tool call that outlives its timeout is abandoned client-side but may still complete inside
-  Revit — verify model state before re-issuing a write.
+- Pi targets one bridge session at a time. Use `manage_revit_instances` to select
+  among reachable instances. Closing or restarting the selected bridge requires
+  explicit selection of an available identity; model calls never fall back to another.
+- A tool call that outlives its timeout is abandoned client-side but may still complete inside
+  Revit. Check its receipt with `get_revit_operation`; when retrying the identical request,
+  reuse `_operation_id`. If its outcome remains unknown, inspect the model before a new write.
 - Long-running scripts cannot be interrupted mid-execution (Revit's API is single-threaded);
   the `execute_csharp` budget is 120s.