pi-revit 0.3.1 → 0.5.0

package/skills/pi-revit/references/execution-rules.md

@@ -0,0 +1,41 @@
+# Shared execution rules
+
+Read for tasks that interact with a Revit model. For tool-specific inputs and limits, use the [tool index](tool-index.md). These instructions explain existing behavior; identity checks, transaction handling, and retry protections are enforced in executable code.
+
+## Scope and targeting
+
+Classify the request as explanation/planning, inspection, or modification/delivery. Use only the required path. Read-only findings do not authorize repairs. Follow the user's established scope and model-saving instructions without adding an approval ceremony to already-authorized work. If the requested target or consequential action is unclear, resolve that ambiguity before the dependent action.
+
+The first sole Revit instance can bind automatically. For multiple sessions, choose with [manage_revit_instances](tools/manage_revit_instances.md). Once selected, calls never silently fall back to another session. <!-- inv:no-session-fallback --> Selecting a bridge does not activate a document. Most bridge tools require an open document; `ping` and `search_api_docs` do not. A document-free API search still needs the bridge.
+
+Read `get_model_overview` for the intended model before changing it. Copy `project.documentId` unchanged into `expected_document_id`. It identifies one open document in one bridge session, not a stable project ID, export-directory key, or title. Refresh after closing/reopening, restart, or switching instances. On rejection, establish that the intended model is active before obtaining its ID; never blindly replace the ID with that of another active model. <!-- inv:identity-refresh-intent -->
+
+`get_model_overview` reports `project.documentKind`: `project` or `family`, and for a family its category, types and parameters. Each tool declares the document kinds it works in, and the bridge refuses a tool in any other kind before it runs, naming the route to use instead. In a family, types, parameters and formulas are edited through `FamilyManager` with `execute_csharp`. <!-- inv:document-kind-declared -->
+
+The exact guard is required for all model writes and previews, `execute_csharp`, `export_documents`, `open_view`, and selection/zoom changes. <!-- inv:document-identity-guard --> `manage_sheet_placements` requires it even for `list`, because its metadata classifies the whole tool as write-capable. `manage_selection` requires it for `isolate_in_view: true`, including with action `get`. Pure reads can omit it unless their public schema requires it; supply it when an inspection must remain bound to one model. A supplied identity is checked. Legacy `expected_document` titles alone do not satisfy the guard.
+
+## Discover before using
+
+Use [find_revit_tools](tools/find_revit_tools.md) to activate relevant specialist tools. Read their current public schemas and focused manuals. Tool activation does not run a model operation or automatically read arbitrary Markdown. Prefer a dedicated tool over custom C# when it covers the requested operation.
+
+Discover element, type, view, sheet, link, and field identities from results; examples do not provide usable project IDs. Linked identities remain in their linked document and must not be passed to host write or selection tools. <!-- inv:linked-ids-stay-linked --> The common selection sequence is `get_elements` → returned IDs → `manage_selection` with action `set`; selection has no inline query filter.
+
+## Parameters and units
+
+Display parameter names are localized. For missing display-name lookups or non-English documents, use discovered language-independent `BuiltInParameter` names, such as `ALL_MODEL_MARK` or `ALL_MODEL_INSTANCE_COMMENTS`, where supported. Parameter detail results expose `builtInParameter` for discovery. Shared parameters can use `guid:<GUID>` where the tool supports it. Distinguish missing values from empty values and ambiguous matches; never silently choose one duplicate display name. <!-- inv:parameter-ambiguity -->
+
+Raw measurable parameter values and most returned coordinates use internal Revit units, with lengths in feet. `displayValue` is separately formatted for the document. Numeric query-filter and write inputs can instead use their explicit `unit` or document display units. Read the individual contract; do not apply one conversion rule indiscriminately. Sheet placement uses paper-space coordinates without multiplication by view scale; shared/model/view coordinates are distinct.
+
+## Transactions and retained effects
+
+Use preview to examine consequential or uncertain edits when supported. `preview` and `atomic` are independent: preview rolls back; atomic rejects the whole batch on a failed step. Default batches can retain partial success. A preview may exercise commit checks then roll back an enclosing group; check `commit_validation_performed` before claiming commit validation happened.
+
+Read `committed`, `succeeded`, `proposed`, `failed`, `commitWarnings`, and tool-specific counts. `succeeded` represents committed steps, while `proposed` represents accepted steps rolled back by preview or atomic failure. Temporary IDs in proposals cannot be reused. Committed type changes can replace elements; follow the returned replacement identity. Per-step before/after values are not necessarily a final-model snapshot when the same parameter is written repeatedly or constraints affect other elements. Reread what matters.
+
+Every call of a tool that can change the model reports `model_changes`: the objects it added, modified and deleted (`observed: false` means no document change was seen), and for new views their visibility state. <!-- inv:model-changes-reported --> Use it to state what a call changed, including custom scripts. An object made from an existing one inherits its state: duplicates, copies and retyped elements report `inherited_state` (hidden categories and elements, filters, overrides, template, carried Mark or Comments). Compare it with the request and say what the result derives from. <!-- inv:derived-state-reported -->
+
+Objects that existed before the request are not yours. When the request asks you to create an object and one with that name already exists, or a creation fails with `name_collision`, do not edit, reuse, replace or delete the existing object; ask the user, or create under a distinct name and report the collision. <!-- inv:existing-objects-not-reused --> A PI-Revit scope note on a result means a call changed an object the request names that predates the request.
+
+A commit is not a file save. <!-- inv:no-tool-saves-model --> Model rollback does not reverse prior UI actions, files, or external effects; custom scripts can have all of those. Export and model saving must be within the user's scope. Use returned export paths as authoritative rather than constructing paths from the document title or opaque ID.
+
+For uncertain outcomes read [operation recovery](operation-recovery.md); for visible results read [visual verification](visual-verification.md). For oversized responses read [read_revit_result](tools/read_revit_result.md), while continuing to honor the original query's independent pagination and limits.

package/skills/pi-revit/references/model-audit-export.md

@@ -0,0 +1,40 @@
+# Model audit and export
+
+Use this workflow to establish model counts and data quality, inspect findings, and produce requested exports with a record of the model and scope used. An audit does not imply permission to repair the model or save its Revit file.
+
+For an explanation of auditing, describe the approach without connecting to a model. For an inspection request, perform only the relevant read steps. The correction and export sections apply only when those outcomes are within the user's scope; an audit alone does not require an export.
+
+Read [execution rules](execution-rules.md), then discover/activate only the required capabilities with [find_revit_tools](tools/find_revit_tools.md). Read the relevant focused manuals and current public schemas before calling them:
+
+| Stage | Focused manuals |
+| --- | --- |
+| Scope and counts | [Instances](tools/manage_revit_instances.md), [overview](tools/get_model_overview.md), [elements](tools/get_elements.md), [summaries](tools/summarize_elements.md) |
+| Review and retained findings | [Health](tools/get_model_health.md), [element sets](tools/manage_element_sets.md), [details](tools/get_element_details.md), [relationships](tools/get_element_relationships.md), [coordinates](tools/get_model_coordinates.md), [spatial queries](tools/query_spatial_elements.md), [measurement](tools/measure_geometry.md) |
+| Large results and requested corrections | [Saved results](tools/read_revit_result.md), [parameters](tools/set_parameters.md) |
+| Requested delivery | [Exports](tools/export_documents.md), [visual verification](visual-verification.md) |
+
+## Establish an auditable scope
+
+1. Select the intended Revit session with `manage_revit_instances` when needed, then call `get_model_overview`. Record the returned model identity, title, available persistent path/identity, Revit/add-in versions, and the inspection time. The opaque document ID identifies this open session; it is not a permanent project identifier or an export-folder key.
+2. Activate only tools needed for this audit with `find_revit_tools`: `get_model_health` for warnings, `summarize_elements` for grouped counts, and `manage_element_sets` only for retained query membership. Discover export tools only for a requested export. State the categories, levels, views, and parameter rules being audited. Pass `expected_document_id` on reads as well when keeping the audit tied to one model matters.
+3. Use `get_elements` for raw counts and parameter projections. Up to 20 `parameter_names` can be requested per row, with optional type parameters. Report missing and ambiguous matches separately from empty or null values. Prefer built-in identities or shared GUIDs for stable parameter targeting. Raw measurable values use internal units; retain `displayValue` and unit context for human-readable findings.
+4. Use `summarize_elements` for counts by category, type, level, or exact parameter value. The query covers all matches and rejects query-level paging. Narrow scopes above 10,000 candidates; outer pages contain groups, not partial element counts. Record each query and avoid adding overlapping scopes as though they were disjoint.
+
+## Review health and retain findings
+
+5. Call `get_model_health` for warning groups and model structure. Inspect truncation flags: it returns at most 100 warning groups and 20 element examples per group. A truncated example list is not the complete affected set, and a successful health read does not certify every model-quality rule.
+6. For a reusable filtered scope, create a set with `manage_element_sets`. Record its query, `set_id`, count, and expiry. Sets retain at most 10,000 members, expire 30 minutes after creation, and belong to the exact open document/bridge session. They store membership, not frozen parameter values. Repeated reads show current values and report deleted or identity-changed members in `missing`; follow `next_offset` using visited membership, not only returned rows.
+7. Inspect specific findings with `get_element_details` and `get_element_relationships`. For coordinate checks, use `get_model_coordinates` with explicit units and record the active project location; its shared mapping does not identify a GIS reference system. Spatial tools may narrow review candidates, but axis-aligned boxes do not prove clashes or clearance failures. Preserve each tool's method, units, limits, warnings, and approximation status in the findings.
+8. Retrieve oversized payloads with `read_revit_result` and follow every continuation. This recovers the current tool payload; it does not expand the original query page or remove warning/projection limits.
+
+## Apply only requested corrections
+
+9. If corrections are authorized, use `set_parameters` with exact document identity, explicit numeric input units, and `preview: true` to inspect proposed before/after values. Use `atomic: true` where the batch must succeed together. Check `commit_validation_performed`, failures, and warnings before applying the intended edit as a new operation. Only committed `succeeded` entries represent retained changes; proposed entries were rolled back.
+10. Reread the affected members and repeat relevant counts/health checks after changes. Distinguish a changed query membership from changed values within the original set. Preserve before/after evidence when reporting the correction; no call should save the Revit file unless the user requested that separately.
+
+## Export and record what was produced
+
+11. Discover and inspect the intended sheet/view IDs before `export_documents`. PDF/DWG/PNG require 1–100 explicit IDs. IFC exports the whole model by default or can use one supplied view; record that distinction. PDF combines outputs by default. Export has file effects, and IFC can also write model metadata inside its transaction; it is not a rollback-only preview.
+12. Omit `output_dir` to use the identity-derived model destination unless the user requests another location. Treat returned `outputDir` and `files[].path` as authoritative. Do not reconstruct a folder from model title or session ID. Use the verified model folder for accompanying audit notes according to workspace rules; never trigger an unnecessary export just to discover a folder.
+13. Record export time, format, requested IDs/scope, model identity evidence, operation ID, returned paths and sizes, and commit warnings. These identify what the export call reported. Directory-change detection can be confused by unrelated simultaneous writers, so avoid sharing the output folder with concurrent work.
+14. Open or inspect the produced artifact as appropriate to the deliverable. Existence and file size do not establish drawing quality or IFC schema/geometry validity. If export fails, report observed partial files; rollback does not remove them. For a timeout, follow [operation recovery](operation-recovery.md): inspect its original receipt before retrying with the same `_operation_id` and identical arguments. State remaining uncertainty explicitly rather than claiming an unverified export succeeded, and stop dependent modifications while a consequential earlier outcome remains unknown.

package/skills/pi-revit/references/operation-recovery.md

@@ -0,0 +1,33 @@
+# Operation recovery
+
+Read after a timeout, cancellation, uncertain result, or a failure that may have left effects. [get_revit_operation](tools/get_revit_operation.md) documents receipt inputs and outputs. The bridge's deduplication and session routing enforce retry behavior; Markdown does not supply these guarantees.
+
+## Resolve the original outcome
+
+1. Retain the exact original tool, arguments, intended document identity, operation ID, and bridge identity. Supporting bridges assign IDs automatically; the extension includes them in responses or request errors.
+2. Read the original receipt with `get_revit_operation`. This bypasses the model thread and does not queue another model action. Receipt reads and identical retries route to the original bridge regardless of the selected target for new calls; they do not change selection.
+3. Interpret state and result together. `queued` or `running` is unfinished. `expired_before_start` confirms no tool action began. `succeeded` means the call completed, not that a change committed: a successful preview can report `committed: false`. `failed` and `result_unavailable` do not establish rollback. `unknown`, an unavailable original bridge, or a restarted session does not prove the action never ran. <!-- inv:uncertain-outcome -->
+4. If a retry is needed, add the exact `_operation_id` to the original tool call and preserve every other argument. <!-- inv:receipt-routing --> The bridge waits for or returns that operation's result without repeating it. A tool/argument mismatch is rejected. Omitting `_operation_id` creates a new operation. Applying a preview is a new operation because the arguments change, but do that only after the preview outcome is known.
+5. If the receipt cannot establish the outcome, inspect the original model and other effects before issuing a new modification. Stop dependent edits when the outcome remains consequentially uncertain; report what is known and what access or evidence is missing. Do not change instances or manufacture a new ID to bypass uncertainty.
+
+## Retention and restart limits
+
+The bridge keeps at most 128 full completed results totaling 32 MiB. Eviction leaves the ID and outcome reserved for the remainder of that bridge session, with `result_available: false`; an identical retry neither reconstructs the result nor executes again. At 10,000 records, new tracked calls are rejected while retained receipts remain queryable. Restart clears receipts and changes bridge identity. An old operation ID cannot be replayed against the new session. Older bridges without tracking have no receipt guarantee.
+
+Client cancellation does not cancel bridge execution. A queued operation may still begin before its deadline, and started work cannot be interrupted. Standard bridge calls have a 30-second client budget; `execute_csharp`, `capture_view`, and `export_documents` have 120 seconds. A timeout can leave already-started work running. Wait or inspect the existing receipt according to the task; do not flood the queue with fresh calls.
+
+## Failure triage
+
+| Symptom | Interpretation and next action |
+| --- | --- |
+| Exact document identity rejected | No tool action was performed. Activate the intended model, read its overview, and pass the refreshed identity unchanged. |
+| Several instances or selected session unavailable | [List/select the intended instance](tools/manage_revit_instances.md) and refresh the overview for new work. Choosing another instance does not resolve an old operation. |
+| Bridge unavailable | Revit is closed, still starting, or the add-in did not load. Use [ping](tools/ping.md); when user action is needed, explain that Revit/add-in must be running. |
+| HTTP 409, `hasActiveDocument: false` | Revit is running without an open project. Open the intended project before document calls; blindly waiting/retrying cannot fix this. |
+| Timeout or modal dialog | Work may be queued or running. Inspect its receipt and any actual effects before a new action. |
+| Large-result local save failed | Revit may already have finished. The error carries the operation ID on tracked bridges; recover the retained result through the receipt. Do not rerun a write to recover its display. |
+| Partial selection/isolation/export failure | Earlier UI changes or incomplete files may remain. Inspect reported paths/effects; rollback cannot undo files or earlier UI actions. IFC commit warnings also need inspection. |
+| Script `returnValueError` | Result projection can fail after the model committed. Read commit status and inspect effects; do not infer rollback from missing output. |
+| Installed/loaded version mismatch | Use [ping](tools/ping.md) and the package's installation/upgrade guidance. Updating the Pi package alone does not deploy a matching Revit add-in. |
+
+Large recovered receipts may themselves use [saved-result continuation](tools/read_revit_result.md). Keep receipt status, transaction status, artifact existence, and visual correctness separate in the final report.

package/skills/pi-revit/references/room-documentation.md

@@ -0,0 +1,39 @@
+# Room documentation
+
+Use this workflow to prepare a room plan or section, tags, a schedule, and a drawing sheet. Match the user's requested deliverables and model-saving instructions. Creation and placement calls change the open document; a tool commit does not save the Revit file.
+
+For an explanation or plan, describe the procedure without executing it. For inspection of an existing room sheet, use only discovery/read steps and the requested verification. Creating documentation follows the modification path. An illustrative full workflow does not expand a narrower request.
+
+Read [execution rules](execution-rules.md) first and [visual verification](visual-verification.md) before checking visible results. Discover/activate only the tools needed through [find_revit_tools](tools/find_revit_tools.md); read each relevant manual and its public schema before use:
+
+| Stage | Focused manuals |
+| --- | --- |
+| Identity and resources | [Instances](tools/manage_revit_instances.md), [overview](tools/get_model_overview.md), [elements](tools/get_elements.md), [details](tools/get_element_details.md), [types](tools/get_element_types.md) |
+| Views and tags | [Views](tools/manage_views.md), [tags](tools/create_tags.md) |
+| Schedule and sheet | [Read schedules](tools/get_schedules.md), [eligible fields](tools/get_schedule_fields.md), [edit schedules](tools/manage_schedules.md), [sheets](tools/manage_sheets.md), [placements](tools/manage_sheet_placements.md) |
+| Verification and requested delivery | [Open view](tools/open_view.md), [capture](tools/capture_view.md), [export](tools/export_documents.md) |
+
+## Establish the room and drawing resources
+
+1. If needed, use `manage_revit_instances` to select the intended bridge. Call `get_model_overview` and retain its exact `project.documentId`. Pass it as `expected_document_id` throughout, including previews and placement listing. After a bridge restart or document reopen, select the intended session and refresh the overview.
+2. Activate the required tools with `find_revit_tools`. Query rooms using `get_elements` with category `OST_Rooms`. Project room number/name parameters using built-in identities discovered through `get_element_details`. Follow query pages and distinguish missing values from empty ones. Select the intended room by its identity, not a name alone.
+3. Read the room's level, location, bounds, and relevant parameters with `get_element_details`. Check that it is placed and suitable for documentation. Record units: detail coordinates are internal feet. A box is only an enclosure and does not establish the room's exact boundary or a valid tag location.
+4. Discover existing views/levels with `get_elements`, view-family types using `get_element_types` with `of_class: "ViewFamilyType"`, and compatible room-tag/titleblock symbols with `get_element_types`. Reuse suitable loaded resources; do not invent type IDs.
+
+## Build and check the views
+
+5. Use `manage_views` to duplicate an appropriate plan, or create a plan with the room's `level_id` and a compatible `view_family_type_id`. Choose a clear name and supported scale/template. A new floor plan is not automatically cropped to the room. Confirm the actual view extent before describing it as a room drawing.
+6. If a section is requested, use `manage_views` with action `create_section`, an explicit internal-coordinate origin, orthogonal view/up vectors, dimensions, and length unit. Derive the extent from the intended room and drawing requirements; do not assume its bounding-box faces are finished wall faces. Use preview when assessing the proposed change, inspect failures and `commit_validation_performed`, then apply the intended edit with a new operation ID. Preview-created IDs are temporary.
+7. Read the committed view ID, then use `create_tags` with `kind: "room"`, a compatible plan view and loaded room-tag type. Place `head_position` at the room's level in internal coordinates using the specified unit. It always refers to the tag head, including when a leader is enabled. Omit `orientation` for room tags. Preview, then create the intended tags; check all per-target results. Use `atomic: true` when the requested tag batch must succeed together.
+
+## Add the schedule and sheet
+
+8. Reuse a suitable existing schedule or create a regular `OST_Rooms` schedule with `manage_schedules`. On the committed schedule, call `get_schedule_fields` to discover eligible `parameter_id`/`field_type` pairs for room number, name, area, and any requested data. Add those fields, then read `get_schedules` for actual schedule-local `field_id` values.
+9. Configure headings, explicit-unit widths, itemization, sorting, and any room-number filter with `manage_schedules`. Supplied filter/sort arrays replace their entire lists. Use measured numeric filter units explicitly. Verify all row and column pages; grouped rows and totals are not element IDs. Do not reuse field IDs created only in a preview.
+10. Create or update the sheet with `manage_sheets`, using the requested name/number and an optional loaded titleblock type. Preview first when assessing the proposed layout changes, then retain the committed sheet ID.
+11. Place committed views and the schedule with `manage_sheet_placements`. Specify paper-space `[x,y,0]` coordinates and units; never multiply by view scale. A viewport position is its box center excluding its label, while a schedule position is its insertion point. Omit schedule rotation. Use `list` to inspect placements and `move` to refine them; previews produce no reusable placement IDs.
+
+## Verify and deliver
+
+12. Activate the sheet with `open_view`, capture it with `capture_view`, and open the returned PNG using Pi's image-capable read tool. Check tag legibility, view extent, scale, schedule contents, titleblock data, and overlaps. Numeric placement alone does not confirm visual layout quality.
+13. If export is requested, export the committed sheet ID through `export_documents` and report the returned paths. Respect the user's file-saving instruction separately from export. Summarize committed views, tags, schedules, and sheets, along with remaining failures or warnings. For timeouts or uncertainty, follow [operation recovery](operation-recovery.md): check the original receipt before an identical retry, preserve the original `_operation_id`, and stop dependent edits if the original outcome cannot be established.

package/skills/pi-revit/references/tool-index.md

@@ -0,0 +1,89 @@
+# PI-Revit tool index
+
+Use this index to choose a capability, then read only the relevant manual. The tables below are generated from the tool contracts and the documentation manifest. They list every public tool in this package, but that inventory is not a limit on future tools. The current public schema determines accepted inputs; a manual is explanatory guidance.
+
+Use [find_revit_tools](tools/find_revit_tools.md) to search with English task words; translate a request written in another language first. With its default `scope: "available"`, it finds registered capabilities and activates returned tools. `scope: "documentation"` returns packaged manuals without contacting Revit or activating tools. Results carry each tool's declared **limits with alternatives**, its **verification** method and its **contract compatibility** with the selected bridge. A manual's presence does not establish that a selected bridge advertises the tool.
+
+A tool that does not cover a request is not evidence that the request is impossible. <!-- inv:capability-claims-checked --> Follow its declared alternative. When nothing dedicated fits, check [search_api_docs](tools/search_api_docs.md), then use [execute_csharp](tools/execute_csharp.md) within the requested scope.
+
+Read [execution rules](execution-rules.md) for model work, [operation recovery](operation-recovery.md) for uncertain outcomes, and [visual verification](visual-verification.md) for visible changes. Bridge tools include the transport-added `_operation_id`. Document guards and action requirements can be added beyond the tool class's own declared inputs. Use the final registered schema and manual together.
+
+<!-- generated:tool-index:start (npm run generate:contracts; do not edit this block) -->
+
+## Connection, discovery, and local utilities
+
+| Manual | Use | Tier | Verify |
+| --- | --- | --- | --- |
+| [find_revit_tools](tools/find_revit_tools.md) | Discover tools, activate capabilities, or find packaged documentation. | native | none |
+| [get_revit_operation](tools/get_revit_operation.md) | Inspect an original operation receipt after uncertain results. | native |  |
+| [manage_revit_instances](tools/manage_revit_instances.md) | List and select local Revit bridge sessions. | native | reread |
+| [manage_revit_scripts](tools/manage_revit_scripts.md) | Save, inspect and run exact versions of reusable scripts. | native | reread |
+| [ping](tools/ping.md) | Check Revit bridge availability and versions. | native |  |
+| [read_revit_result](tools/read_revit_result.md) | Read saved large results in bounded fragments. | native |  |
+
+## Model inspection and review
+
+| Manual | Use | Tier | Verify |
+| --- | --- | --- | --- |
+| [get_element_details](tools/get_element_details.md) | Inspect element parameters, geometry bounds and identity. | core |  |
+| [get_element_relationships](tools/get_element_relationships.md) | Inspect hosts, joined elements, members and dependents. | advanced |  |
+| [get_element_types](tools/get_element_types.md) | Discover available element types and family symbols. | core |  |
+| [get_elements](tools/get_elements.md) | Query, count and filter elements and project parameter values. | core |  |
+| [get_model_health](tools/get_model_health.md) | Inspect model warnings and health information. | advanced |  |
+| [get_model_overview](tools/get_model_overview.md) | Inspect project identity, units, levels and category counts. | core |  |
+| [manage_element_sets](tools/manage_element_sets.md) | Retain query membership and reread current member values. | advanced | none |
+| [summarize_elements](tools/summarize_elements.md) | Count a whole element query grouped by type, category, level or parameter. | advanced |  |
+
+## Links, coordinates, and spatial analysis
+
+| Manual | Use | Tier | Verify |
+| --- | --- | --- | --- |
+| [get_linked_elements](tools/get_linked_elements.md) | Query elements inside a selected linked document. | advanced |  |
+| [get_linked_models](tools/get_linked_models.md) | Discover loaded and unloaded Revit link instances. | advanced |  |
+| [get_model_coordinates](tools/get_model_coordinates.md) | Read base points, project locations and shared-coordinate mappings. | advanced |  |
+| [measure_geometry](tools/measure_geometry.md) | Measure point distance or approximate element bounding-box gaps. | advanced |  |
+| [query_spatial_elements](tools/query_spatial_elements.md) | Query elements by bounding-box intersection or containment. | advanced |  |
+
+## Selection and editing
+
+| Manual | Use | Tier | Verify |
+| --- | --- | --- | --- |
+| [change_element_types](tools/change_element_types.md) | Change element types with partial or atomic outcomes. | advanced | reread |
+| [delete_elements](tools/delete_elements.md) | Preview or perform deletion including dependent elements. | advanced | reread |
+| [manage_selection](tools/manage_selection.md) | Read or change selection, zoom and temporary isolation. | core | reread |
+| [open_view](tools/open_view.md) | Activate a Revit view or sheet. | core | none |
+| [set_parameters](tools/set_parameters.md) | Edit or preview parameter values with optional atomic rollback. | core | reread |
+| [transform_elements](tools/transform_elements.md) | Move, copy or rotate elements with preview rollback. | advanced | reread |
+
+## Drawings, schedules, and delivery
+
+| Manual | Use | Tier | Verify |
+| --- | --- | --- | --- |
+| [capture_view](tools/capture_view.md) | Capture a view as an image for visual verification. | advanced | inspect_output |
+| [create_tags](tools/create_tags.md) | Create host element, room, space and area tags. | advanced | capture |
+| [export_documents](tools/export_documents.md) | Export sheets, views or the model to PDF, DWG, PNG or IFC. | advanced | inspect_output |
+| [get_schedule_fields](tools/get_schedule_fields.md) | Discover eligible parameter and field-type pairs. | advanced |  |
+| [get_schedules](tools/get_schedules.md) | Inspect schedule fields, sorting, filters and table cells. | advanced |  |
+| [manage_schedules](tools/manage_schedules.md) | Create and configure schedules, fields, filters and sorting. | advanced | reread |
+| [manage_sheet_placements](tools/manage_sheet_placements.md) | List, place and move viewports and schedules on sheets. | advanced | capture |
+| [manage_sheets](tools/manage_sheets.md) | Create, rename and renumber sheets. | advanced | reread |
+| [manage_views](tools/manage_views.md) | Create, duplicate and update plans, sections and 3D views. | advanced | capture |
+
+## API and custom execution
+
+| Manual | Use | Tier | Verify |
+| --- | --- | --- | --- |
+| [execute_csharp](tools/execute_csharp.md) | Execute custom synchronous C# in Revit. | core | reread |
+| [search_api_docs](tools/search_api_docs.md) | Search installed Revit API classes, methods, signatures and enums. | core |  |
+
+## Workflows and shared guidance
+
+| Guide | Kind | Use |
+| --- | --- | --- |
+| [execution-rules](execution-rules.md) | reference | Shared rules for model targeting, document identity, parameters, units and transactions. |
+| [operation-recovery](operation-recovery.md) | reference | Recover after timeouts, cancellations and uncertain outcomes using operation receipts. |
+| [visual-verification](visual-verification.md) | reference | Capture and inspect visible results and exported deliverables, then stop when the request is verified. |
+| [tool-index](tool-index.md) | reference | Every public tool grouped by task, with manual links. |
+| [room-documentation](room-documentation.md) | workflow | Room plans, sections, tags, schedules and sheets as one documentation workflow. |
+| [model-audit-export](model-audit-export.md) | workflow | Multi-step model audit, data review and requested exports. |
+<!-- generated:tool-index:end -->

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

@@ -0,0 +1,62 @@
+# capture_view
+
+## Purpose and boundaries
+
+Export a temporary PNG of a graphical Revit view or sheet for visual inspection. The response contains a file path and metadata, never image data. Open the returned `filePath` with Pi's image-capable read tool to see the result. Capturing alone does not perform visual verification.
+
+Contract: PI-Revit 0.5.0 source, [CaptureView.cs](../../../../src/Revit/Tools/CaptureView.cs). Activate this advanced tool through `find_revit_tools`. The public schema is authoritative; this page documents source behavior, not a live-model test.
+
+<!-- generated:contract:start (npm run generate:contracts; do not edit this block) -->
+## Contract (generated)
+
+- **Source:** bridge tool, advanced tier: activate it with `find_revit_tools`.
+- **Writes model:** no. **Effects:** 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:** `f8989e7bb68815d2`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `view_id` | 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 |
+| --- | --- |
+| Image contents or visual judgement (returns a file path only) | Tool: read (open the returned PNG) |
+| Deliverable PDF, DWG or IFC files | Tool: export_documents |
+<!-- generated:contract:end -->
+
+## Inputs and preconditions
+
+| Input | Meaning |
+| --- | --- |
+| `view_id` | Optional existing graphical view/sheet ID; defaults to the active view. Use an explicit committed ID for reproducible evidence. |
+| `expected_document_id` | Optional exact current overview identity; always checked if supplied. Supplying it binds the capture to the intended model. |
+| `_operation_id` | Optional extension argument only for an identical retry. Omit for a new operation. |
+
+Revit must have an open document. Explicit view templates and schedules are rejected; use `get_schedules` for schedule data or capture a sheet hosting the schedule when its layout matters. Discovery uses `get_elements`; an ID from a rolled-back preview is invalid.
+
+Follow [execution rules](../execution-rules.md) and [visual verification](../visual-verification.md). Frame the actual view so the requested content is readable. An `open_view` activation is queued; a same-batch capture based on active view can show the previous view. Use the explicit target ID in a subsequent call.
+
+## Example
+
+ID `23456` is illustrative; replace it with the intended committed view/sheet ID.
+
+```json
+{
+  "view_id": 23456,
+  "expected_document_id": "<project.documentId>"
+}
+```
+
+## Results, effects and verification
+
+The result contains `filePath`, `viewId`, `viewName`, `width`, `height`, and `fileSizeBytes`. Images are fitted to a maximum 1568-pixel long edge; a later export/readable close-up may be needed to inspect dense sheets. This is Revit's image export, not a screenshot of UI chrome or a proof of selection highlighting.
+
+The tool writes files and performs no model transaction or model save. Captures normally live in `%LOCALAPPDATA%\pi-revit\captures` with a temporary-directory fallback. Later captures best-effort prune owned PNGs older than 24 hours. Retain required evidence in the task's evidence location before relying on long-term availability.
+
+Open the image and inspect visibility, positioning, readability, clipping, and overlaps. A blank or tiny drawing is insufficient proof. Retain before/after images when useful, and report verification as incomplete if inspection is unavailable. Do not infer appearance from dimensions or filenames.
+
+The call budget is 120 seconds. Follow [operation recovery](../operation-recovery.md) for uncertain outcomes; an identical retry may return the original capture result, not a fresh image of later model changes. Capturing evidence does not authorize saving the Revit model.

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

@@ -0,0 +1,65 @@
+# change_element_types
+
+## Purpose and boundaries
+
+Assign discovered element types to explicit host elements. Use `get_element_types` to find types and inspect target compatibility. This does not edit a type definition; use `set_parameters` on a type ID when that is the intended change. Revit constraints may affect connected or hosted elements beyond the returned target snapshots.
+
+Contract: PI-Revit 0.5.0 source, [ChangeElementTypes.cs](../../../../src/Revit/Tools/ChangeElementTypes.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:** `810351ef8bac44ab`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `updates` | array of object | yes |  |  |
+| `preview` | boolean | no |  |  |
+| `atomic` | 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 |
+| --- | --- |
+| Editing a type definition's parameters | Tool: set_parameters |
+| Creating a new type | 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 a family | 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. |
+<!-- generated:contract:end -->
+
+## Inputs and preconditions
+
+| Input | Meaning |
+| --- | --- |
+| `updates` | Required: 1–200 objects with positive `element_id` and `type_id`. Each target element may appear only once. |
+| `preview` | Default `false`; commit-validates accepted changes then rolls them back. |
+| `atomic` | Default `false`: valid targets can commit independently of failures. `true` rolls the entire batch back if any target fails. |
+| `expected_document_id` | Required for every call, including previews. Use the intended model's exact current overview identity. |
+| `_operation_id` | Optional extension argument only for an identical retry. Omit for a new operation. |
+
+Follow [execution rules](../execution-rules.md). Revit validates that each type is an existing `ElementType` acceptable to the target. Missing, pinned, or incompatible targets fail per update. The tool does not unpin them.
+
+## Example
+
+IDs are illustrative; replace them with an inspected host target and a compatible discovered type.
+
+```json
+{
+  "updates": [{ "element_id": 12345, "type_id": 34567 }],
+  "preview": true,
+  "atomic": true,
+  "expected_document_id": "<project.documentId>"
+}
+```
+
+## Results, recovery and verification
+
+Read `committed`, `succeeded`, `proposed`, `failed`, `commitWarnings`, and `commit_validation_performed`. Entries include `before`, `after`, `resulting_id`, `unique_id`, `replaced`, `resulting_id_is_temporary` and `inherited_state`. Snapshot locations are internal feet. `inherited_state` lists what the retyped element keeps: its traits, Mark and Comments and, for the first 20 updates, how many views hide or override it. A replaced element (new ID) loses per-view hiding and overrides.
+
+Revit can replace an element during a type change. After commit, use `resulting_id` and `unique_id`, not an assumed unchanged ID. Any replacement ID in `proposed` is temporary after either preview or atomic rollback; it must not be reused. An atomic rejection can lack commit validation.
+
+Reread committed results, confirm assigned types, inspect affected dependents, and follow [visual verification](../visual-verification.md) for visible changes. Follow [operation recovery](../operation-recovery.md) for timeouts or uncertain outcomes. A write following a preview is a new operation. This does not save the model.

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

@@ -0,0 +1,85 @@
+# create_tags
+
+## Purpose and boundaries
+
+Create element, room, space, or area tags for host-document targets in one explicit view using a loaded tag family type. Linked targets and face/subelement references are unsupported. This tool creates tags, not tag families or target elements.
+
+Contract: PI-Revit 0.5.0 source, [CreateTags.cs](../../../../src/Revit/Tools/CreateTags.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:** `61b4ced397d41d57`. `find_revit_tools` compares it with the selected bridge's live contract.
+
+| Input | Type | Required | Default | Allowed values |
+| --- | --- | --- | --- | --- |
+| `kind` | string | yes |  | `element`, `room`, `space`, `area` |
+| `view_id` | integer | yes |  |  |
+| `tag_type_id` | integer | yes |  |  |
+| `unit` | string | yes |  | `millimeters`, `centimeters`, `meters`, `feet`, `inches` |
+| `targets` | array of object | yes |  |  |
+| `leader` | boolean | no |  |  |
+| `orientation` | string | no |  | `horizontal`, `vertical` |
+| `preview` | boolean | no |  |  |
+| `atomic` | 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 |
+| --- | --- |
+| Tagging elements inside linked models | Revit API: Reference.CreateLinkReference; IndependentTag.Create. Check all its members in one call: `search_api_docs` with query `Reference.CreateLinkReference; IndependentTag.Create`, then use `execute_csharp` within the requested scope. |
+| Tagging faces or subelements | Revit API: IndependentTag.Create with a face Reference. Check all its members in one call: `search_api_docs` with query `IndependentTag.Create`, then use `execute_csharp` within the requested scope. |
+| Creating or loading tag 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. |
+| Text notes, dimensions and other annotation | Revit API: TextNote.Create; Creation.ItemFactoryBase.NewDimension. Check all its members in one call: `search_api_docs` with query `TextNote.Create; Creation.ItemFactoryBase.NewDimension`, then use `execute_csharp` within the requested scope. |
+<!-- generated:contract:end -->
+
+## Inputs and preconditions
+
+Follow [execution rules](../execution-rules.md). Discover a compatible loaded `FamilySymbol`, the intended view, and host targets before requesting placement.
+
+| Input | Meaning |
+| --- | --- |
+| `kind` | Required: `element`, `room`, `space`, or `area`. |
+| `view_id` | Required existing view ID. Templates, perspective views, and unlocked 3D views are rejected. Spatial tags require a compatible plan view. |
+| `tag_type_id` | Required loaded tag `FamilySymbol` ID; Revit validates tag compatibility. The tool activates an inactive symbol within the edit. |
+| `unit` | Required length unit: `millimeters`, `centimeters`, `meters`, `feet`, or `inches`. |
+| `targets` | Required array of 1–100 objects containing positive `element_id` and finite `head_position: [x,y,z]`. |
+| `leader` | Optional boolean, default false. Position still means the tag head when a leader is enabled. |
+| `orientation` | Element tags only: `horizontal` (default) or `vertical`. Omit entirely for room/space/area tags. |
+| `preview` | Default `false`; commit-validates accepted tags then rolls back model changes. |
+| `atomic` | Default false: valid target tags may commit despite others failing. True rolls back all tags if any target fails. |
+| `expected_document_id` | Required for all calls, including preview; exact current overview identity. |
+| `_operation_id` | Optional extension argument only for an identical retry. Omit for a new operation. |
+
+Positions use the document's internal coordinates, not sheet coordinates. For room/space/area tags, the target must have a point location on the plan view's level; supply the head at that spatial level. The tool creates the spatial tag at the target location before applying the requested head and leader.
+
+## Example
+
+IDs and positions are illustrative. Replace them with an inspected compatible plan, loaded room-tag type, room, and head position on its level.
+
+```json
+{
+  "kind": "room",
+  "view_id": 23456,
+  "tag_type_id": 34567,
+  "unit": "meters",
+  "targets": [{ "element_id": 12345, "head_position": [4, 6, 0] }],
+  "leader": false,
+  "preview": true,
+  "atomic": true,
+  "expected_document_id": "<project.documentId>"
+}
+```
+
+## Results, recovery and verification
+
+Inspect `committed`, `succeeded`, `proposed`, `failed`, `commitWarnings`, and `commit_validation_performed`. Per-target entries include `tag_id`, `unique_id`, actual `tag_type_id`, owner `view_id`, `kind`, actual `head_position` in feet, `leader`, and `id_is_temporary`.
+
+Every tag in `proposed` is temporary, including atomic rollback results. Only reuse IDs from committed `succeeded` entries. Preview validates model acceptance but cannot establish final visual readability after rollback.
+
+Read committed tags and follow [visual verification](../visual-verification.md) to inspect text, head positions, leader paths, overlaps, and clipping in the actual view. Follow [operation recovery](../operation-recovery.md) before repeating an uncertain call to avoid duplicate tags. A real call after preview is a new operation. This tool does not save the model.

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.