Skip to content

Open-source Revit MCP server: let Claude and other AI assistants read and edit BIM models, with human approval on every change.

docs: add demo runbook for the missing door Mark demo (#72)

A. Sam Mohammad34d937323519
diff --git a/docs/README.md b/docs/README.md
index 92b74fa..bb33412 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -14,6 +14,7 @@ Start with the [installation guide](install.md). The main [README](../README.md)
- [versioning.md](versioning.md): version numbers, release tags and release assets.
- [clash-triage.md](clash-triage.md): read-only matching of Navisworks clashes to Revit elements, with a confidence label (unverified on live projects).
- [roadmap.md](roadmap.md): coordinator workflows, demo scope and the next fixes.
+- [demo-runbook.md](demo-runbook.md): step-by-step script for the missing-door-Mark demo, with expected counts and a rejected-plan run.
## For contributors
diff --git a/docs/demo-runbook.md b/docs/demo-runbook.md
new file mode 100644
index 0000000..e37ca2e
--- /dev/null
+++ b/docs/demo-runbook.md
@@ -0,0 +1,326 @@
+# Demo runbook: missing door Marks
+
+This is the script for the core demo: ask, plan, preview, approve in Revit,
+verify, undo. It runs on a synthetic fixture with 12 doors that have no Mark
+and 3 rooms that have no Number. It also covers a run where the plan is
+rejected and nothing changes.
+
+**Writes are untested in a real Revit.** An architecture review found that
+`BridgeCommandFactory.CreateTransaction(Document, string)` in the add-in calls
+itself, so as written on `main` every model write (including
+`revit_set_parameter_value`) would recurse until Revit crashes. The fix is
+hotfix PR #95, which is open and not merged. Do not run Step 6 or the undo
+steps against anything you care about until #95 is merged and the add-in is
+rebuilt from it, and treat the first real write on a throwaway copy as a test
+in its own right. Steps 1 to 5 and the rejected-plan run do not write to the
+model.
+
+Nobody has run this end to end against live Revit yet. The expected counts come
+from the [seeded defect manifest](../fixtures/canonical-model/seeded-defects.json)
+and the rule pack, not from a recorded session. Record what you actually see
+and treat any difference as a finding. Background on why the demo looks like
+this is in the [roadmap](roadmap.md).
+
+## How to read the status tags
+
+- **Checked in code**: the tool or panel feature exists on `main` and I read
+ how it behaves. That does not mean it has been seen working in Revit.
+- **UNVERIFIED (live Revit)**: it needs a running Revit session with the
+ add-in. Nothing in this runbook has been confirmed that way.
+- **UNVERIFIED (unmerged)**: it depends on work that is not on `main`.
+ Preview in the model is in open PR #64. Skip that step, or do it by hand,
+ until it lands. Proof bundles and `plan_revert` (#62) and the draft-plan gate
+ fix (#63) are merged, so they are tagged "checked in code" below, not
+ unmerged. The write-path crash fix is open PR #95 (see above).
+
+## What you need
+
+- Windows with a supported Revit version (2024 to 2027) and the add-in
+ installed. See the [install guide](install.md).
+- The MCP server connected to an MCP client, and the Revit side panel open.
+- A throwaway copy of the fixture. Never run this on a project model.
+- Approval mode left at its default (`required`). Do not set
+ `MCP_REVIT_APPROVAL_MODE=auto`; that turns the human check off.
+
+Write down before you start: Revit version, git commit, date, and the document
+name. The roadmap asks for these with every recorded run.
+
+## Step 0: build the fixture
+
+From the repository root, with Revit open and the add-in loaded:
+
+```powershell
+python scripts\revit\generate_canonical_test_model.py
+```
+
+The script saves to `fixtures/canonical-model/generated/canonical_test_model.rvt`.
+If Revit does not activate the new document, open a clean project template
+yourself and rerun with `--use-active-document`. Details are in the
+[fixture README](../fixtures/canonical-model/README.md).
+
+Expected: per the manifest, the last 12 generated doors have no Mark and the
+last 3 generated rooms have no Number. The manifest also expects the core rule
+pack to report 15 findings in total on this model (12 + 3). UNVERIFIED (live
+Revit): the generator itself.
+
+If it fails: confirm the add-in is loaded and a document is open. The script
+looks for the bridge under `%LOCALAPPDATA%\AECModelBridge\registry\` and falls
+back to `http://127.0.0.1:3000`. Save the generated model under a new name so
+you can reopen a clean copy for the rejected-plan run.
+
+## Step 1: capture a snapshot
+
+Ask the assistant: "Take a snapshot of the active model." The tool is
+`revit_extract_snapshot`. Keep the `snapshot_id` it returns; every check and
+parameter call below needs it.
+
+Why: on `main`, the QA checker and the parameter manager refuse to run in live
+mode without a `snapshot_id` and tell you to capture one (change #59). They only
+fall back to generated sample data when `MCP_REVIT_MODE=mock`. Sample data is not
+your model, so do not run the demo in mock mode and call it live.
+
+What to look for: a snapshot id comes back, with no error. I have not seen the
+exact output, so I will not quote it. Note the id and the time.
+
+If it fails:
+
+- "requires a snapshot_id" means you skipped this step or the id was not passed.
+- A connection error means the add-in is not running or the server cannot find
+ it. Check the panel's status area, then see the install guide.
+- The snapshot file must be readable by the Python server. The add-in and the
+ server each have a workspace setting. If the server says the snapshot is not
+ found, confirm both point at the same workspace folder. The roadmap flags this
+ as something to verify, so treat it as a likely first failure.
+
+UNVERIFIED (live Revit).
+
+## Step 2: ask (find the problems)
+
+Ask: "Run the core QA check on that snapshot and list the issues."
+
+Tools: `qaqc_checker_run_check` (with `snapshot_id` and rule pack `core`), then
+`qaqc_checker_list_issues`. Note the `doc_guid` that `run_check` returns and
+pass it to `list_issues` together with `status` set to `open`. The issue store
+is persistent and `list_issues` defaults to every document and every status, so
+an unscoped call on a repeated demo, or after the doors are fixed, also returns
+old and resolved findings and will not match the counts below.
+
+Expected counts, from the manifest:
+
+| Rule | Expected findings |
+| --- | --- |
+| `door_missing_mark` | 12 |
+| `room_missing_number` | 3 |
+| Total | 15 |
+
+Other core rules may report findings on this model. The manifest lists several
+rules the fixture cannot seed, so do not be alarmed by extra or absent lines for
+other rules. Only the two rows above are the demo baseline.
+
+If the counts differ: do not adjust the story to fit. Check that the snapshot
+came from the fixture document, rebuild the fixture, and retake the snapshot. The
+roadmap's bar is the same counts on two runs. If a run gives different numbers,
+write down both.
+
+Panel note: the panel's "Run Health Check" button on the Findings tab calls the
+same check, but as written it sends no `snapshot_id`. In live mode that will be
+rejected. Use the MCP client for this step. UNVERIFIED (live Revit) whether the
+panel path works in your build.
+
+## Step 3: plan
+
+Ask: "Propose a unique Mark for each of the 12 doors without one, using the
+pattern D-101 to D-112. Show me the exact values before anything is changed."
+
+Agree the numbering pattern yourself first. The demo only works if the
+coordinator chooses the rule; the assistant should not guess one.
+
+Before building actions, get the numeric element ids. The QA findings carry
+only `element_uid`, but `revit_set_parameter_value` needs the integer
+`element_id`, and `plan_actions` does not convert one to the other. Look them up
+in the snapshot: `parameter_manager_filter_params` (pass the snapshot id,
+`param_name` `Mark`, and a filter for doors with an empty Mark) returns each
+match with both `uid` and `element_id`; `model_inspector_ask` also returns
+`element_id`. Match them to the 12 `element_uid` values from Step 2 and do not
+guess ids. The add-in's snapshot writer includes `element_id`; that it comes
+through correctly is UNVERIFIED (live Revit).
+
+Tool: `plan_actions`, with one `revit_set_parameter_value` action per door
+(`element_id`, `parameter_name` = `Mark`, `value`). On `main`, `plan_actions`
+reads each door's current Mark and stores it as the plan's before-state.
+`parameter_manager_plan_set_params` can also build a draft, but it sets one
+value for every matched element, so it does not fit unique Marks. Use it only
+if you want to show a shared value.
+
+Expected: a plan with 12 actions, state `pending`, 12 distinct values, and an
+empty before-state for each door.
+
+Things to check before going further:
+
+- Exactly 12 element ids, none of them rooms, and each one matches a finding's
+ `element_uid` from Step 2.
+- No duplicate values within the plan, and none that clash with the 48 doors that
+ already have a Mark. The code does not check uniqueness of the proposed values
+ for you. This is on the human.
+- If a before-value shows as missing for an element, say so. Rollback in Step 8
+ depends on it.
+
+If it fails: an assistant that tries to change a parameter directly, without a
+plan, should get an authorization error naming the missing `plan_id`. That is the
+gate working. Go back and create the plan. If the assistant lists
+`list_pending_plans` and your plan is not there, plan creation failed; ask it to
+report the error text.
+
+## Step 4: preview
+
+Two previews, different status:
+
+- **In the panel (checked in code)**: open the Plans tab and press Refresh. The
+ plan appears with its state and a one-line list of the tools in it. The panel
+ today shows tool names, not per-door old and new values. So read the
+ old/new values from the assistant's plan output, and compare the count
+ yourself.
+- **In the model (UNVERIFIED, unmerged, PR #64)**: showing the pending change on
+ the actual elements in Revit is not on `main`. Skip it for now, or select the
+ 12 doors and eyeball them. Use `revit_select_by_unique_ids` with the 12
+ `element_uid` values; it selects and zooms in the active view. Do not use
+ `selection_tools_select_by_query` for this: it only writes the matching UIDs to
+ `pending_selection.json` in the workspace, and nothing in the add-in reads that
+ file, so nothing would be selected in Revit. Selecting is a Revit UI action.
+ UNVERIFIED (live Revit).
+
+Expected: 1 pending plan, 12 actions.
+
+## Step 5: approve in Revit
+
+In the panel's Plans tab, press Approve on the plan. The panel sends
+`approve_plan` through the hub. The assistant cannot approve its own plan: the
+approval tools are withheld from the native chat backend by design.
+
+Expected: the plan leaves the pending list. The Run Log gets a `Plan approve`
+entry as soon as you click, and a `Plans updated` entry after the refresh; both
+are normal and neither proves the hub accepted the call. Nothing in the model has changed yet; approval only unlocks execution.
+
+If it fails: an `Error: plan.approve` entry in the Run Log (or an error toast)
+means the hub rejected the call. Any other Run Log entry is not a failure.
+Press Refresh and check the plan's state. Do not approve a plan you
+rejected; the code does not stop you from changing a plan's state, so check
+the state each time.
+
+UNVERIFIED (live Revit).
+
+## Step 6: execute
+
+Ask the assistant: "The plan is approved. Run it." Tool: `execute_plan`.
+
+Expected: the result lists 12 actions, each executed. In the add-in each
+`revit_set_parameter_value` call runs in its own transaction, which Revit's
+Undo list should show as `AMB: Set Parameter Value`, one entry per door, not one
+entry for the whole plan. The add-in only appends ` #<action id>` to the name
+when the call carries an `action_id`, and `execute_plan` does not pass one, so
+expect no suffix and 12 identical-looking entries. This is only reachable once
+#95 is merged (see the top of this page). UNVERIFIED (live Revit).
+
+If some actions fail: execution reports and continues. The plan is marked
+`partial`, not `executed`, and the proof bundle's outcome is `partial` or
+`failed`. Do not tell the audience it worked. Read which actions failed
+(read-only or owned elements are the usual suspects), then go to Step 7 and look
+at what changed.
+
+## Step 7: verify
+
+Take a new snapshot (Step 1 again, new id) and rerun the check on it. Never
+verify with the old snapshot; it still shows the old values.
+
+Expected after a clean run:
+
+| Rule | Before | After |
+| --- | --- | --- |
+| `door_missing_mark` | 12 | 0 |
+| `room_missing_number` | 3 | 3 (unchanged on purpose) |
+
+The 3 room findings staying put is the point: the approval covered doors only,
+and nothing else moved. Also read back two or three of the new Marks with
+`revit_get_parameter_value` and compare with the plan.
+
+If the door count is not 0: list the remaining issues and match them to the
+plan's failed actions. Say what happened plainly. If the room count changed,
+stop. Something outside the plan wrote to the model; check the
+[audit logs](logging-and-audit.md) to match requested changes against what Revit
+executed.
+
+## Step 8: undo
+
+There are two ways back. Use whichever you can show honestly.
+
+1. **Revit Undo (checked in code that transactions are named, behavior
+ UNVERIFIED)**. Immediately after execution, in the same Revit session, press
+ Ctrl+Z. Because each parameter write is its own named transaction, you may
+ need to press it 12 times. Take a fresh snapshot afterwards and expect the
+ baseline of 12 and 3 again. ADR 0008 describes a single named transaction
+ per plan; the code on `main` names one per action. The ADR and the code do
+ not yet agree, so do not promise one-click undo.
+2. **`rollback_plan` (checked in code)**. It only works on a plan in state
+ `executed`, and it writes each recorded before-value back. One catch: it
+ skips an action when no before-value was recorded, and reports that as a
+ warning. These doors started empty. If the before-state is stored as empty,
+ rollback may skip all 12 and leave the Marks in place. Read the warnings in
+ the result and verify with a new snapshot. If it skipped them, use Ctrl+Z
+ instead. UNVERIFIED (live Revit). The model-facing chat cannot call rollback;
+ a person does it from the client.
+3. **`plan_revert` (checked in code, merged in #62)**. It drafts a new pending
+ plan from the proof bundle; you still approve and execute it. It refuses when
+ an element has no recorded before-value, and an empty value counts as not
+ recorded. These doors started with an empty Mark, so expect `plan_revert` to
+ refuse here. Treat that as the documented behaviour, not a bug, and fall back
+ to Ctrl+Z. It would work for a parameter that had a value before. Its
+ write-back is UNVERIFIED (live Revit) and subject to #95 like every write.
+
+Proof of the change: `get_proof_bundle(plan_id)` returns the proof file written
+after `execute_plan` (see [proof and revert](proof-and-revert.md)). Pass
+`snapshot_id` to `plan_actions` if you want the document identity in it. The
+bundle is a server-side record, not an observation of the model, so the evidence
+that the model really changed or reverted is still the two snapshots and the
+check counts. UNVERIFIED (live Revit).
+
+## Rejected-plan run
+
+This proves a rejected plan leaves the model alone. Start from a clean copy of
+the fixture (the baseline of 12 and 3) and a new snapshot.
+
+1. Steps 1 to 4 as above. Note the snapshot id and the 12 before-values.
+2. In the panel's Plans tab, press Reject. This sends `reject_plan`. The plan is
+ closed and archived.
+3. Ask the assistant to run it anyway. Expected: `execute_plan` refuses, saying
+ the plan is `rejected`, not `approved`. A direct parameter write with that
+ plan id is blocked the same way.
+4. Take a new snapshot and rerun the check. Expected: 12 missing door Marks and 3
+ missing room Numbers, exactly as in Step 2. Read two doors' Marks back: still
+ empty.
+5. Compare the new snapshot with the first one. Nothing should differ.
+ `parameter_manager_diff_params` compares two snapshots and lists differences.
+ Expected: no parameter differences.
+
+If anything is different, that is a bug in the gate. Stop and capture the plan
+file, the audit log and both snapshot ids.
+
+## Quick reference: when it goes wrong
+
+| What you see | What to say | What to do |
+| --- | --- | --- |
+| "requires a snapshot_id" | The tool is protecting us from sample data. | Take a snapshot, pass its id. |
+| Counts are not 12 and 3 | The baseline is off; I am not going to hide that. | Rebuild the fixture, retake the snapshot, record both runs. |
+| Error naming a missing or unapproved `plan_id` | The gate is blocking an unapproved write. | Create or approve the plan. |
+| Approve does nothing in the panel | I will confirm the plan state before going on. | Refresh, look for an `Error:` entry in the Run Log, check the plan state. |
+| Revit crashes or hangs on the first write | Known: write path is broken until #95. | Stop. Check that #95 is merged and the add-in rebuilt. |
+| Some actions failed on execute | This is a partial result, not a finished fix. | Read the per-action errors, verify with a new snapshot. |
+| Door count after is not 0 | Not everything was fixed. | List the remaining issues, match them to failed actions. |
+| Rollback skipped actions | Rollback could not restore empty values. | Use Revit Undo, then verify with a new snapshot. |
+| Anything touching rooms changed | Stop the demo. | Check the audit logs. |
+
+## Record for each run
+
+Date, commit, Revit version, fixture generation command, snapshot ids (before
+and after), prompts used, the actual counts at each step, plan ids, and
+what failed. The roadmap asks for the same list. Publish a recording only after a
+run matches the expected counts twice.