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 product vision, backlog, and architecture plans

A. Sam Mohammad4ccd7fc3de75
diff --git a/docs/product/AEC_MODEL_BRIDGE_PRODUCT_VISION.md b/docs/product/AEC_MODEL_BRIDGE_PRODUCT_VISION.md
new file mode 100644
index 0000000..35d5bc9
--- /dev/null
+++ b/docs/product/AEC_MODEL_BRIDGE_PRODUCT_VISION.md
@@ -0,0 +1,83 @@
+# AEC Model Bridge — Product Vision
+
+> Canonical product name: **AEC Model Bridge** (repo `Sam-AEC/aec-model-bridge`).
+> "AEC Omni-Bridge" is legacy internal branding — permitted only as the name of the *multi-app orchestration vision* (Rhino/Navisworks/PowerBI switches), never as the product name. See `DECISIONS_AND_RISKS.md` D-001.
+
+## 1. Product definition
+
+AEC Model Bridge is a **plugin-style AEC productivity platform** that connects live authoring tools (Revit first; Rhino, Navisworks, Power BI as switches) to AI agents through MCP — with **native BIM semantics as the source of truth** and a **human approval layer** between AI intent and model mutation.
+
+Concretely, it is three layers that already partially exist in this repo:
+
+1. **Switches** — thin C# add-ins inside each host app (`packages/revit-bridge-addin`, `rhino-bridge-addin`, `navisworks-bridge-addin`, `powerbi-bridge-tool`) exposing HTTP `/execute` on the host's API thread.
+2. **Hub** — the Python MCP server (`packages/mcp-server-revit`, `mcp_server.py`) with a provider registry, ~170 tools, async jobs, identity mapping, semantic graph, and exporters.
+3. **Surface** — Claude Code / any MCP client today; a **dockable in-Revit panel with chat, approval queue, and run log** as the MVP product surface for normal Revit users.
+
+## 2. Target users
+
+| Persona | Today's pain | What they get |
+|---|---|---|
+| **BIM coordinator / manager** (primary MVP) | Repetitive QA, parameter cleanup, sheet drudgery; Dynamo scripts nobody maintains | Ask the model questions, run health checks, approve bulk fixes from a panel — no code |
+| **Façade / computational designer** (Sam's own persona) | Rhino→Revit means dumb DirectShapes or manual rebuilds | Semantic roundtrip: GH panel data → native curtain panels/adaptive components |
+| **Automation engineer / BIM developer** | Every firm rebuilds the same Revit-API plumbing | Stable MCP tool surface + module SDK; script in Python against a live model |
+| **Project engineer / QA lead** | Model quality invisible until clash day | Rule-based validation → issue lists → Excel/Power BI dashboards |
+
+## 3. Core user problems
+
+1. **BIM data is trapped.** Answering "how many fire-rated doors on level 3 lack a rating parameter?" requires a schedule, a filter, and 20 minutes — or a developer.
+2. **Automation has a cliff.** Below the cliff: manual clicking. Above it: Dynamo graphs and pyRevit scripts that rot. Nothing in between speaks natural language.
+3. **Cross-tool workflows are lossy.** Rhino→Revit, Revit→Navisworks, Revit→Power BI each drop semantics; every firm hand-rolls the glue.
+4. **AI can't be trusted with models.** No mainstream tool lets an LLM near a production RVT because there is no approval, audit, or rollback layer. That layer *is* the product.
+
+## 4. Why this matters / why it is different
+
+| Alternative | What it is | Why AEC Model Bridge is different |
+|---|---|---|
+| **Dynamo** | Visual programming per-task | We are conversational + persistent tooling, not per-task graphs; Dynamo becomes an *integration target* (Phase 12) |
+| **pyRevit** | Script framework + toolbar for Python devs | pyRevit serves scripters; we serve non-programmers via AI + approval UI, and expose a *stable machine interface* (MCP) pyRevit lacks |
+| **Speckle** | Data platform / versioned object transport | Speckle moves data between apps; we *act* inside apps. Speckle is one of our transports (17 `speckle_*` tools already exist) |
+| **Rhino.Inside.Revit** | Rhino/GH runtime inside Revit process | RiR is a geometry pipe; we add the semantic layer that turns GH output into *native* Revit elements, and RiR is an execution backend option (Phase 12) |
+| **Ordinary Revit add-ins** | Fixed-function buttons | We are a *platform*: module registry, AI surface, cross-app orchestration |
+| **Ordinary MCP servers** | Tool lists bolted to one API | We add the things production BIM needs: mutation metadata, approval queue, transaction discipline, identity mapping across apps, semantic graph, audit trail |
+
+**Moat in one sentence:** the only tool where an AI agent can safely *read, reason about, and — with human approval — modify* a live Revit model using native elements, and carry those semantics across Rhino, Navisworks, IFC, Speckle, and Power BI.
+
+## 5. The plugin-style app vision
+
+Not a script collection. The user experience:
+
+- **Ribbon tab "AEC Bridge"** (exists today with Connection/Tools panels) grows to ~5 product commands: *Open Panel, Run Health Check, Review Pending Actions, Reports, Settings*.
+- **Dockable panel** (WPF + WebView2): chat with the model, see proposed actions as structured cards (element counts, parameter diffs), **Approve / Reject / Approve-all-similar**, live run log.
+- **Modules** (see `PLUGIN_MODULE_SYSTEM.md`): Model Inspector, QA/QC Checker, Parameter Manager, Report Generator… discovered from a registry, each declaring its commands, permissions, and schemas.
+- **Everything auditable**: every mutation is a logged, transaction-named, reversible action tied to the approving user.
+
+## 6. Role of each layer
+
+- **AI agents** — intent → plan → tool calls. Agents *propose*; they never mutate silently. Long tasks run through the existing `JobManager` (`job_status`/`job_cancel`).
+- **MCP tools** — the stable contract. Today: 100 `revit_*`, 19 `rhino_*`, 7 `ifc_*`, 7 `graph_*`, 17 `speckle_*`, 12 `autodesk_*`, 3 `aec_*` mapper, 3 exporter, 2 job tools. Gap to close: `is_mutating`/`execution_mode` metadata on the Python side (C# already has it via `[BridgeCommand]`).
+- **Revit-native automation** — all mutations happen as native elements inside named `Transaction`s on the API thread via the existing `ExternalEvent`/`CommandQueue` path. **DirectShape only for preview or explicit fallback** — never the deliverable.
+
+## 7. Top daily-dependence workflows
+
+Ranked by (frequency × pain × feasibility) — full specs in `AEC_WORKFLOW_CATALOG.md`:
+
+1. **Ask the model** — natural-language Q&A over elements/params/levels/views (read-only; builds trust).
+2. **Model health check** — one click → rule-based QA report with clickable element IDs.
+3. **Bulk parameter ops with approval** — preview diff → approve → transactional apply → rollback available.
+4. **Sheet/view automation** — batch sheets from CSV, renumber, apply templates (tools already exist: `revit_batch_create_sheets_from_csv`, `revit_renumber_sheets`, `revit_apply_view_template`).
+5. **BIM report export** — model → SQLite/Excel/Power BI (exporter + PowerBI switch).
+6. **Façade roundtrip** (flagship, post-MVP) — GH diagrid → semantic panels → native curtain panels.
+
+## 8. MVP direction
+
+Ship the **three data workflows** (inspect → validate → fix) on **one semantic layer** with the **approval panel**, targeting Revit 2024 (net48) + 2025/26 (net8) — multi-targeting already exists in `RevitBridge.csproj`. Detail in `MVP_EXECUTION_PLAN.md`.
+
+Explicitly **not** MVP: façade configurator, Navisworks/PowerBI registration fixes beyond health, orchestrator/recipes, cloud/remote MCP, marketplace.
+
+## 9. Long-term direction
+
+- **Phase-2 flagship:** façade configurator roundtrip (Rhino/GH → semantic panel schema → native Revit), proving the semantic layer publicly.
+- **Orchestrator** (roadmap Phase C): YAML recipes spanning switches — "export Revit → clash in Navisworks → dashboard in Power BI".
+- **Data plane** (roadmap Phase D): Parquet/DuckDB, `.pbit` templates, IDS validation.
+- **Open-core:** GPL platform + commercial modules/enterprise features (dual license already in `LICENSING.md`; strategy details stay in the private strategy doc, not here).
+- **Ecosystem:** module marketplace, switch SDK for third-party hosts (Archicad, Tekla — roadmap Phase G).
diff --git a/docs/product/AEC_WORKFLOW_CATALOG.md b/docs/product/AEC_WORKFLOW_CATALOG.md
new file mode 100644
index 0000000..ebd7e20
--- /dev/null
+++ b/docs/product/AEC_WORKFLOW_CATALOG.md
@@ -0,0 +1,170 @@
+# AEC Workflow Catalog
+
+Each workflow lists: user story · input → output · Revit objects · MCP tools (existing tool names verbatim; **[NEW]** = to build) · modules · UI · safety · failure cases · validation · MVP vs advanced. Modules refer to `PLUGIN_MODULE_SYSTEM.md`; safety gate refers to `PLUGIN_APP_ARCHITECTURE.md` §4.
+
+Tiers: **T1** = MVP (read + gated write), **T2** = flagship/post-MVP, **T3** = later phases.
+
+---
+
+## W1 — Ask AI about the current model (T1)
+
+- **Story:** "As a BIM coordinator I ask 'how many doors on Level 3 have no fire rating?' and get an answer with clickable element IDs in under a minute."
+- **In:** natural-language question. **Out:** answer + element UniqueId list + optional saved query.
+- **Revit objects:** any FilteredElementCollector-reachable element; Levels, Categories, Parameters.
+- **Tools:** `revit_get_document_info`, `revit_list_elements`, `revit_get_elements_by_type`, `revit_get_element_parameters`, `revit_list_levels`, `revit_get_categories`, `snapshot_query` **[NEW]** (query the semantic snapshot instead of N round-trips).
+- **Module:** Model Inspector. **UI:** panel chat; results as element chips → click = `revit_set_selection` + zoom.
+- **Safety:** read-only — no gate. Token guard: cap result payloads; large queries via snapshot, not element-by-element.
+- **Failures:** no doc open (`revit_health` first); stale snapshot (show snapshot age, offer refresh); param name ambiguity (ask user).
+- **Validation:** cross-check counts against a Revit schedule on the test model.
+- **MVP:** count/filter/list on snapshot. **Advanced:** multi-hop questions via `graph_query_relations`, saved queries as QA rules.
+
+## W2 — Inspect selected elements (T1)
+
+- **Story:** "I select elements and ask 'what is this and what's wrong with it?'"
+- **In:** live selection. **Out:** type/family/host/level/params card + rule findings.
+- **Tools:** `revit_get_selection`, `revit_get_element_parameters`, `revit_get_element_type`, `revit_get_element_bounding_box`, `revit_get_warnings`.
+- **Module:** Selection Tools + Model Inspector. **UI:** ribbon "Inspect Selection" + panel card. **Safety:** read-only.
+- **Failures:** empty selection; view-specific elements; huge selections (summarize, don't enumerate).
+- **Validation:** matches Revit Properties palette on test model.
+- **MVP:** property card. **Advanced:** per-selection QA findings, "fix" suggestions feeding W5.
+
+## W3 — Extract model groups (T1)
+
+- **Story:** "List all model groups, members, and instance counts so I can audit group hygiene."
+- **In:** none/filter. **Out:** group table (name, instances, member categories, nesting).
+- **Revit objects:** `Group`, `GroupType`. **Tools:** `revit_list_elements` (OST_IOSModelGroups), `revit_get_group_members`.
+- **Module:** Model Inspector. **UI:** panel table + CSV export. **Safety:** read-only.
+- **Failures:** nested groups (recurse with depth cap); groups in links (out of scope, flag).
+- **MVP:** table. **Advanced:** duplicate-group detection, group-vs-group diff.
+
+## W4 — Manipulate model groups safely (T1, gated)
+
+- **Story:** "Rename/ungroup/convert selections to groups in bulk without corrupting instances."
+- **In:** group selection + operation. **Out:** applied changes + audit entries.
+- **Tools:** `revit_create_group`, `revit_ungroup`, `revit_convert_to_group`, `revit_move_element`, `plan_actions` **[NEW]**.
+- **Module:** Selection Tools. **UI:** plan cards in approval queue. **Safety:** ActionPlan required; ungroup flagged destructive; per-plan TransactionGroup.
+- **Failures:** group instances in other views/phases (report affected count in plan); attached details lost on ungroup (warn).
+- **Validation:** instance counts before/after; Revit undo restores exactly.
+- **MVP:** rename/ungroup with plan preview. **Advanced:** re-group after edit, group content sync.
+
+## W5 — Read & update parameters (T1, gated — killer workflow #3)
+
+- **Story:** "Set `FireRating='60'` on all EI-60 doors; I see the before/after diff, approve, and can roll back."
+- **In:** filter + param + value (or CSV mapping). **Out:** diff table → applied plan → audit + inverse plan.
+- **Tools:** `revit_get_element_parameters`, `revit_get_parameter_value`, `revit_set_parameter_value`, `revit_batch_set_parameters`, `revit_batch_set_parameters_by_filter`, `revit_get_type_parameters`, `revit_set_type_parameter`, `plan_actions` **[NEW]**.
+- **Module:** Parameter Manager. **UI:** diff grid (element, param, before → after) with per-row/all approve.
+- **Safety:** capture before-values (enables inverse plan); read-only params and type-vs-instance mismatches blocked at plan time; storage-type validation (string/double/ElementId); unit handling via spec type.
+- **Failures:** param not bound on category; workshared element owned by other user (report, skip, list); formula-driven params (read-only).
+- **Validation:** re-read after apply == intended; undo restores before-values on test model.
+- **MVP:** filter-based batch set with diff+approval. **Advanced:** CSV/Excel roundtrip, shared-param creation (`revit_create_shared_parameter`), rule-driven fixes from W7.
+
+## W6 — Validate families & types (T1)
+
+- **Story:** "Flag families that break our standard: naming, duplicate types, oversized, in-place."
+- **In:** ruleset (naming regex, size caps, banned categories). **Out:** findings list per family/type.
+- **Tools:** `revit_list_families`, `revit_get_type_parameters`, `revit_get_elements_by_type`, `revit_edit_family` (advanced), `snapshot_query` **[NEW]**.
+- **Module:** Family/Type Mapper + QA/QC Checker. **UI:** findings table, severity-grouped. **Safety:** read-only (fixes route through W5/W9 plans).
+- **Failures:** family size requires doc extraction (defer to advanced); in-place families lack types (special-case).
+- **MVP:** naming + duplicate-type + in-place count checks. **Advanced:** type-catalog compliance, `revit_replace_family_type` remediation plans.
+
+## W7 — Model health checks: walls/doors/windows/rooms/levels/views/sheets/schedules (T1 — killer workflow #2)
+
+- **Story:** "One click, model health report in 2 minutes: unplaced rooms, unnamed views, doors without hosts, duplicate marks, views-not-on-sheets…"
+- **In:** ruleset id (YAML rule packs). **Out:** findings report (severity, rule, elements, suggested fix).
+- **Revit objects:** Walls, Doors, Windows, Openings, Rooms, Levels, Views, ViewSheets, Schedules, Warnings.
+- **Tools:** snapshot + `revit_get_warnings`, `revit_list_views`, `revit_list_sheets`, `revit_get_schedule_data`, `revit_list_levels`, `graph_audit_disconnected`, `graph_audit_clashes`; `run_qa_ruleset` **[NEW]**.
+- **Module:** QA/QC Checker. **UI:** ribbon "Run Health Check" → progress (JobManager) → report in panel; export via W8.
+- **Safety:** read-only; suggested fixes become ActionPlans only on user click.
+- **Failures:** huge models → async job with progress (`job_status`); rules referencing unbound params → rule skipped + noted, not crash.
+- **Validation:** seeded test model with known defects → rule pack finds exactly those (golden findings file in CI).
+- **MVP:** ~15 core rules (unplaced/unenclosed rooms, unnamed/duplicate views, views not on sheets, doors/windows without host, duplicate marks, untagged doors, warning count by type, empty schedules, model group count sanity, unused families threshold). **Advanced:** firm-custom rule packs, IDS-based checking, scheduled runs, trend tracking across snapshots.
+
+## W8 — Generate BIM reports / export structured data (T1)
+
+- **Story:** "Export model + QA findings to SQLite/Excel; my Power BI dashboard refreshes from it."
+- **In:** snapshot + findings. **Out:** `.sqlite` / `.xlsx` / (later `.parquet`).
+- **Tools:** `exporter_to_sqlite`, `exporter_graph_to_sqlite`, `exporter_db_health`, `export_excel` **[NEW]** (openpyxl), `revit_get_schedule_data`.
+- **Module:** Report Generator + Data Exporter. **UI:** ribbon "Reports" → format + destination (workspace-sandboxed paths).
+- **Safety:** writes only inside workspace sandbox (exists); redaction on paths/PII (exists).
+- **Failures:** file locked by Excel/PBI (retry w/ timestamped name); schema drift between exports (schema_version column).
+- **MVP:** SQLite + Excel with fixed schema. **Advanced:** Parquet/DuckDB, `.pbit` template auto-refresh, scheduled exports.
+
+## W9 — QA/QC issue lists (T1)
+
+- **Story:** "Findings become a tracked issue list I can assign, mark resolved, and re-check."
+- **In:** W7 findings. **Out:** issue records (id, rule, elements, status, assignee) persisted per document GUID; re-run auto-resolves fixed issues.
+- **Tools:** `run_qa_ruleset` **[NEW]**, issue store **[NEW]** (SQLite in workspace), `autodesk_data_create_issue` (advanced → ACC), `speckle_send_object` (advanced).
+- **Module:** QA/QC Checker. **UI:** issues tab in panel; click issue → select+zoom elements.
+- **Safety:** issue store is external metadata — no model writes.
+- **Failures:** elements deleted since finding (mark orphaned via UniqueId miss); doc SaveAs changes GUID (re-anchor prompt).
+- **MVP:** local issue store + re-check lifecycle. **Advanced:** ACC Issues / BCF export, assignment via email.
+
+## W10 — Automate view/sheet workflows (T1, gated)
+
+- **Story:** "Create 40 sheets from CSV, place plans, populate title blocks, renumber — as one approved plan."
+- **Tools (all exist):** `revit_batch_create_sheets_from_csv`, `revit_create_sheet`, `revit_place_viewport_on_sheet`, `revit_populate_titleblock`, `revit_list_titleblocks`, `revit_renumber_sheets`, `revit_duplicate_sheet`, `revit_create_floor_plan_view`, `revit_apply_view_template`, `revit_get_view_templates`.
+- **Module:** View/Sheet Automator. **UI:** CSV picker + preview table (sheet number/name/view/titleblock) → approve.
+- **Safety:** duplicate-sheet-number pre-check at plan time; deletes (`revit_delete_sheet`) always destructive-flagged.
+- **Failures:** titleblock family missing (halt plan with fix hint); viewport placement collisions (grid heuristic + report).
+- **Validation:** sheet count/numbers match CSV exactly; undo removes all created sheets (TransactionGroup).
+- **MVP:** CSV → sheets + titleblock params. **Advanced:** auto viewport layout, revision management (`revit_get_revision_sequences`), print/export sets.
+
+## W11 — Façade configurator (T2 — flagship)
+
+- **Story:** "I tune a diagrid façade in Rhino/GH; approved panel layout lands in Revit as native curtain panels/adaptive components with type mapping and parameters — not DirectShape."
+- **In:** GH/Rhino panel geometry + `facade_zone` semantic spec (see `SEMANTIC_BIM_DATA_MODEL.md` §facade). **Out:** native Revit elements + identity mappings + variant record.
+- **Revit objects:** Curtain systems/panels, adaptive component families, mullions, reference points.
+- **Tools:** `rhino_run_python`, `rhino_generate_diagrid_tower`, `rhino_get_scene`, `aec_register_mapping`, `aec_translate_id`, `revit_place_family_instance`, `revit_batch_set_parameters`, `facade_apply_zone` **[NEW]** (semantic spec → placement plan); preview via DirectShape **only** with visible "PREVIEW" marker + auto-cleanup.
+- **Modules:** Façade Configurator + Rhino Bridge. **UI:** variant cards (panel counts, type breakdown, deltas vs current) → approve variant.
+- **Safety:** variant apply = one TransactionGroup; re-apply diffs against mapped identities (update/create/delete sets shown before approval); deletes always itemized.
+- **Failures:** adaptive family missing (block with load instruction); panel outside tolerance of host face (report skipped panels — never silently skip: count must reconcile, cf. the 1476-panel discipline in CLAUDE.md); unit mismatches (metres end-to-end, exists in Rhino bridge).
+- **Validation:** panel count Rhino == Revit == mapping table; roundtrip re-export matches within tolerance.
+- **MVP(T2):** one zone, one adaptive family, apply + re-apply diff. **Advanced:** multi-zone, type optimization (panel similarity clustering), GH live-link via `g1_*`/Rhino.Inside.
+
+## W12 — Rhino.Inside.Revit workflows (T2)
+
+- **Story:** "Run GH definitions against live Revit geometry inside the Revit process; results land as native elements through the same approval gate."
+- **Method:** RiR as *execution backend* — GH definition emits our semantic spec (JSON), hub turns it into an ActionPlan. Custom GH components **[NEW]** wrap hub endpoints.
+- **Tools:** `facade_apply_zone` **[NEW]**, `aec_*` mapper; RiR-side components **[NEW]**.
+- **Safety:** identical gate — RiR gets no write bypass. **Failures:** RiR version/Rhino version matrix (document supported pairs); unit system differences.
+- **MVP(T2):** one exemplar GH definition → semantic spec → native elements. **Advanced:** bidirectional (Revit selection → GH input).
+
+## W13 — Grasshopper/Dynamo workflows (T2/T3)
+
+- **GH (T2):** via Rhino bridge `rhino_run_python` + existing MCP `g1_*` canvas tools; GH exports semantic spec, not meshes. Existing scratch assets (`facade_gh_builder.py`, `facade_system.gh`) become the exemplar.
+- **Dynamo (T3):** Dynamo package **[NEW]** with ZeroTouch nodes calling hub HTTP endpoints; same spec, same gate. `scratch/facade_dyn_builder.py` is prior art.
+- **Failures:** graph solves mid-edit producing partial specs → spec must carry `complete: true` flag; version pinning of node packages.
+- **MVP(T2):** GH exemplar. **Advanced:** Dynamo node package, graph-as-module registration.
+
+## W14 — Semantic roundtrip back to Revit (T2 — the differentiator)
+
+- **Story:** "External tools edit *data about* elements (a JSON of walls/panels/params); the bridge reconciles it into the live model as native edits."
+- **In:** semantic delta document (schema §roundtrip). **Out:** reconciliation plan (create/update/delete/skip) → approved apply → updated mappings.
+- **Tools:** `snapshot_export` **[NEW]**, `snapshot_diff` **[NEW]**, `plan_actions` **[NEW]**, `aec_translate_id`, all relevant `revit_create_*`/`revit_set_*`.
+- **Safety:** three-way awareness — delta vs snapshot vs live model; if live model changed since snapshot, conflicting actions are flagged, never auto-overwritten.
+- **Failures:** UniqueId misses (element deleted) → orphan report; type not loadable → blocked action with hint.
+- **Validation:** apply → re-export → diff == empty.
+- **MVP(T2):** parameters + placement of known families. **Advanced:** geometry-bearing types (walls by curve, floors by boundary), variant management.
+
+## W15 — IFC / Navisworks / Speckle workflows (T2/T3)
+
+- **IFC (T1-adjacent, tools exist):** open IFC alongside RVT — `ifc_get_spatial_structure`, `ifc_query_elements`, `ifc_get_properties`, `ifc_validate`; map to Revit via `aec_register_mapping` (GlobalId ↔ UniqueId, mapper exists). MVP: IFC Q&A + Revit-vs-IFC param comparison.
+- **Navisworks (T2):** register `NavisworksProvider` in shipped hub **[fix]**, widen provider to the 16 C# commands (model tree, viewpoints, `navis.run_clash_test`, `navis.get_clash_results`); clash results → identity mapper → Revit element selection ("show me clash #12 in Revit"). Failure: clash GUID ↔ Revit UniqueId mapping fidelity — validate on test pair.
+- **Speckle (T2, 17 tools exist):** publish semantic snapshots as Speckle versions (`speckle_publish_version`), receive external edits → W14 reconciliation. Failure: OAuth expiry mid-job (refresh flow exists).
+
+## W16 — Excel / Power BI workflows (T1 Excel, T2 PBI)
+
+- **Story:** "Model data and QA trends in the tools management already uses."
+- **Excel (T1):** `export_excel` **[NEW]** — elements/params/findings sheets; CSV param roundtrip back through W5 plans.
+- **Power BI (T2):** wire orphaned `PowerBIProvider` **[fix]** → `powerbi_execute_dax` against live PBI Desktop (:3006 external tool exists in C#); or file-based: SQLite/Parquet + provided `.pbit` template (roadmap Phase D).
+- **Failures:** ADOMD connection lifetime (PBI restarts change server/db args — re-handshake); Excel file locks.
+- **MVP:** Excel export. **Advanced:** DAX Q&A ("ask your dashboard"), auto-refresh pipeline, DuckDB layer.
+
+---
+
+## Cross-cutting requirements
+
+1. Every T1 write workflow goes through **ActionPlan → approval → named transaction → audit → inverse plan** without exception.
+2. Every workflow must work on the **canonical test model** (Phase 17) with golden outputs in CI.
+3. Every workflow's tool calls appear in `tools-generated.md` with correct mutation metadata.
+4. Payload discipline: snapshot-first querying; never stream 50k elements through chat context.
diff --git a/docs/product/AI_AGENT_SWARM_PLAN.md b/docs/product/AI_AGENT_SWARM_PLAN.md
new file mode 100644
index 0000000..b7c1292
--- /dev/null
+++ b/docs/product/AI_AGENT_SWARM_PLAN.md
@@ -0,0 +1,48 @@
+# AI Agent Swarm Plan
+
+How Claude Code agents build this product in parallel without stepping on each other. Ground rules first, then the roster.
+
+## Ground rules (all agents)
+
+- **Source of truth:** `docs/product/*` (this package) for *what to build*; `docs/system-blueprint-and-workflows.md` + ADRs for *how the system works*; `SCAFFOLDING_TASK_LIST.md` for *task ownership*.
+- **Conflict avoidance = ownership by path.** Each agent has "allowed edit areas"; editing outside them requires the orchestrating session's sign-off. Two agents never own the same path in the same phase.
+- **Worktrees** (`EnterWorktree` / `isolation: worktree`): mandatory for any agent touching code in parallel with another code agent; unnecessary for single-agent doc work. C# and Python agents can share a branch only if their paths are disjoint (`packages/revit-bridge-addin` vs `packages/mcp-server-revit`).
+- **Handover format (uniform):** every agent ends with: *changed files · commands run + results (build/test output verbatim) · contracts touched (tool names, schemas) · open questions · next task recommendation*. Written to the task's phase section or `NEXT_AGENT_HANDOVER.md`.
+- **Required checks before "done":** Python — `pytest` + `ruff`; C# — `dotnet build -c Release` for **net48 and net8** targets; docs — no broken relative links; contract changes — regenerate `docs/tools-generated.md`.
+- **Human approval required for:** deleting/archiving any existing file (audit §9 list), changing a shipped tool's name/schema (breaking change), flipping runtime defaults (LegacyMode, approval_mode), anything touching `LICENSES/`, `LICENSING.md`, `TRADEMARKS.md`, publishing/pushing, and any git history rewrite.
+- **Model/effort:** exploration and doc-summarization agents run cheap (Explore/haiku-class); architecture and Revit-API-threading work runs at highest reasoning. Don't spawn an agent for work smaller than its briefing.
+
+## Roster
+
+| Agent | Responsibility | Inputs | Outputs | Allowed edit areas |
+|---|---|---|---|---|
+| **Repo Audit** | Keep `CURRENT_REPO_AUDIT.md` true; verify claims vs code after each phase; regen tool docs | whole repo (read) | audit doc updates, drift reports | `docs/product/CURRENT_REPO_AUDIT.md`, `docs/tools-generated.md` |
+| **Product Architect** | Guard vision/architecture coherence; arbitrate cross-agent contract disputes; own ADRs | product package, ADRs | ADR updates, decision entries | `docs/product/*`, `docs/000*.md`, `DECISIONS_AND_RISKS.md` |
+| **Revit API** | C# add-in: snapshot extraction command, transaction discipline, Contract v2 default, dockable pane host, dead-tree resolution | `PLUGIN_APP_ARCHITECTURE.md`, `SEMANTIC_BIM_DATA_MODEL.md`, `BridgeCommandFactory.cs` | C# code + `docs/revit-addin-lifecycle.md` updates | `packages/revit-bridge-addin/**` |
+| **MCP Tooling** | Hub: tool metadata, approval-gate tools, module provider adapter, retire legacy `server.py`/`tools/`, register Navisworks | hub source, module spec | Python code + tests | `packages/mcp-server-revit/src/**`, `tests/**` |
+| **Plugin App** | Module registry, built-in MVP modules (inspector, params, qaqc, reports, sheets, selection) | `PLUGIN_MODULE_SYSTEM.md`, workflow catalog | `modules/**` + manifests + tests | `packages/mcp-server-revit/src/revit_mcp_server/modules/**` |
+| **Semantic BIM Data** | Snapshot/delta/zone schemas, diff engine, reconciliation, mapper extensions | `SEMANTIC_BIM_DATA_MODEL.md` | JSON schemas, `semantic/` package, tests | `packages/mcp-server-revit/src/revit_mcp_server/semantic/**`, `schemas/**` |
+| **UI/UX** | WebView2 panel app (chat, plan cards, findings, run log), ribbon layout | architecture §2, workflow UI specs | panel HTML/JS/CSS + C# pane host (coordinate w/ Revit API agent) | `packages/revit-bridge-addin/src/UI/**`, `panel/**` |
+| **Integration** | Speckle/APS/IFC/PowerBI wiring per `INTEGRATION_STRATEGY.md`; Excel exporter | strategy doc, provider code | provider updates, `export_excel` | `providers/cloud.py`, `providers/ifc.py`, `providers/powerbi.py`, `providers/exporter.py` |
+| **Rhino/Grasshopper** | Façade zone spec exporter, bridge Contract v2, RiR exemplar, GH `g1_*` playbooks | `rhino-bridge-addin`, W11–W13, `/rhino-skills` | C# bridge updates, GH defs, scratch→product promotion | `packages/rhino-bridge-addin/**`, `modules/facade_configurator/**` |
+| **QA/QC BIM** | Rule engine + core rule pack, issue store, golden findings; the domain expert for what rules matter | W7/W9, rule format | `rules/core/**`, rule engine in qaqc module | `modules/qaqc_checker/**` |
+| **Testing** | Canonical test model script, e2e harness (extends `test_e2e.py`), CI matrix, contract tests for module metadata | all contracts | `tests/**`, `.github/workflows/**`, fixtures | `tests/**`, `.github/**`, `fixtures/**` |
+| **Documentation** | User docs, tutorials, rewrite stale `docs/security.md`, fix README links/CLAUDE.md ports, MkDocs site | audit §4 stale list | docs | `docs/**` (not `docs/product/` — Architect owns), `README.md`, `CLAUDE.md` |
+| **Release** | Version reconciliation (1.1.0→CHANGELOG parity), installers, `server.json`, marketplace listings | `docs/build-and-install-scripts.md`, `marketplaces.md` | scripts, installer defs, release notes | `scripts/**`, `dist/` config (not artifacts), `server.json`, `CHANGELOG.md` |
+| **Security/Safety** | Approval gate review, permission enforcement tests, redaction coverage, bearer-token default flip, threat model refresh | ADR 0002, gate code | security tests, `docs/security.md` (with Documentation agent), threat notes | `tests/test_security*.py`, review-only elsewhere |
+
+## Parallelization map
+
+- **Wave 1 (independent):** Revit API (snapshot command, C#) ∥ MCP Tooling (metadata + gate, Python) ∥ Documentation (stale-doc cleanup) ∥ Testing (test model script). Different path ownership → same branch or worktrees, no conflicts.
+- **Wave 2 (after gate + snapshot):** Plugin App (modules) ∥ UI/UX (panel) ∥ Semantic BIM Data (diff/reconcile) — modules mock the panel; panel mocks modules via the command-list endpoint contract fixed in Wave 1.
+- **Wave 3:** QA/QC rules ∥ Integration wiring ∥ Release packaging.
+- **Contract freeze points:** tool metadata shape (end W1), `module.json` schema (start W2), snapshot schema (start W2). After a freeze, changes go through Product Architect + human approval.
+- **Merge order:** hub contracts → C# → modules → UI. The orchestrating session (main Claude Code context) merges; agents never merge to `development` themselves.
+
+## When human (Sam) must decide
+
+1. Audit §9 deletions/archival (260 MB binaries, private strategy doc, dead C# tree, legacy server).
+2. LegacyMode/auth default flip (breaks existing local setups).
+3. Any tool rename on the shipped ~170-tool surface.
+4. Installer signing, marketplace publishing, license/pricing surfaces.
+5. Approving each phase's Definition of Done in `SCAFFOLDING_TASK_LIST.md`.
diff --git a/docs/product/CURRENT_REPO_AUDIT.md b/docs/product/CURRENT_REPO_AUDIT.md
new file mode 100644
index 0000000..b7298fd
--- /dev/null
+++ b/docs/product/CURRENT_REPO_AUDIT.md
@@ -0,0 +1,127 @@
+# Current Repo Audit — aec-model-bridge
+
+Audited 2026-07-08 on branch `development`. **Nothing was deleted or moved.** Files flagged for consolidation/archival are listed in §9 pending approval.
+
+## 1. Identity
+
+Four names in circulation — the single biggest branding problem:
+
+| Name | Where | Verdict |
+|---|---|---|
+| **AEC Model Bridge** | README, LICENSING, `pyproject.toml` (`aec-model-bridge`), `server.json`, `Server("aec-model-bridge")`, logo | **Canonical** (decision D-001) |
+| AEC Omni-Bridge | CLAUDE.md title, ecosystem-strategy doc, blueprint | Legacy narrative brand — migrate |
+| Autodesk-Revit-MCP-Server | Local folder name only | Stale; remote is already `Sam-AEC/aec-model-bridge` |
+| RevitBridge / AECModelBridge | C#: namespace `RevitBridge`, assembly `AECModelBridge`, both `dist/RevitMCP/` and `dist/AECModelBridge/` exist | Mid-flight rename; reconcile |
+
+Also: `server.json`/`pyproject.toml` descriptions still say "for Autodesk Revit" despite multi-platform positioning; package `mcp-server-revit` / module `revit_mcp_server` are Revit-centric names for a multi-provider hub.
+
+## 2. Packages
+
+### `packages/mcp-server-revit` (Python hub) — mature, with dead weight
+- Python ≥3.11; deps: `mcp`, `pydantic`, `httpx`, `ifcopenshell`, `networkx`, `specklepy>=3,<4`.
+- **Shipped server:** `src/revit_mcp_server/mcp_server.py` — MCP stdio, registers **9 providers**: Revit, IFC, AECMapper, SQLiteExporter, Job, Rhino, SemanticGraph, Speckle, AutodeskData. Proxy via `MCP_PROXY_TARGETS`.
+- **Legacy server (dead-parallel):** `server.py` — line-JSON protocol, registers Navisworks (shipped server doesn't), uses different env var `MCP_PROXY_URL`, and calls `proxy._connect()` **which does not exist** on `McpProxyProvider`. Several tests target this server, not the shipped one.
+- **Orphaned legacy tool system:** `tools/handlers.py`, `tools/document.py`, `tools/health.py`, `schemas.py` — the pre-provider 25-tool system that `docs/security.md` still documents.
+- Providers dir: `base.py`, `registry.py`, `revit.py`, `ifc.py`, `identity_mapper.py`, `rhino.py`, `navisworks.py`, `graph.py`, `cloud.py`, `job_provider.py`, `exporter.py`, `proxy.py`, `powerbi.py` (orphaned), `fake.py` (test-only).
+- Tests: 14 modules incl. provider-contract and perf; good breadth but partly aimed at legacy code.
+
+### `packages/revit-bridge-addin` (C#) — flagship, operational
+- Multi-target **net48 / net8.0-windows / net10.0-windows** (Revit 2024/2025-26/2027). Serilog, IronPython, Revit API via local DLLs or Nice3point NuGet fallback.
+- `App.cs` (IExternalApplication) → `CommandQueue` → `ExternalEvent` → `RevitCommandExecutor` → `BridgeCommandFactory`. Correct API-thread discipline.
+- `BridgeServer.cs`: `/health`, `/tools`, `/capabilities`, `POST /execute`; semaphore(10); 5 MB cap. **Contract v2 (dynamic port + bearer token + registry file) implemented but OFF by default** — `LegacyMode` defaults true → fixed port 3000, no auth, unless `MCP_REVIT_LEGACY_PORT=false`.
+- **Real surface: 110 `[BridgeCommand("revit.*")]` handlers** in `BridgeCommandFactory.cs` (~4,300 lines), attribute carries `IsMutating`/`ConfirmationRequired`.
+- **Dead tree:** `src/Commands/Core|Advanced|Specialized|Enhancements/**` (Family/Geometry/MEP/Stairs/Structural/Worksharing commands, `Phase*CommandRegistry`) — `<Compile Remove>`d in `RevitBridge.csproj:67-73`, zero `[BridgeCommand]` attributes, never in the shipped DLL.
+
+### `packages/rhino-bridge-addin` (C#) — built ✓
+- net48, RhinoCommon 7.16, hardcoded port **3004**, `switch`-based routing (not the attribute pattern).
+- ~18 commands: doc/scene/layers, primitives, booleans, materials, transforms, `run_python` (IronPython), `generate_diagrid_tower`, reflection trio.
+
+### `packages/navisworks-bridge-addin` (C#) — routing infra only
+- net48, port **3002** (or Contract-v2 dynamic). **16 attribute-registered commands** incl. model tree, viewpoints, clash tests.
+- **But:** Python `NavisworksProvider` exposes only 4 tools and is registered **only in legacy `server.py`** → the entire C# surface is unreachable through the shipped hub.
+
+### `packages/powerbi-bridge-tool` (C#) — stub, fully orphaned
+- External-tool console app (`AdomdClient`, port **3006**), `.pbitool.json` configs, root `deploy_pbi.ps1`.
+- `providers/powerbi.py` (5 tools incl. `powerbi_execute_dax`) is **imported/registered nowhere**. No PowerBI tool is reachable.
+
+## 3. MCP tool inventory (shipped hub, ~170 tools)
+
+| Provider | Count | Tools |
+|---|---|---|
+| Revit | 100 | `revit_*`: doc/health (7), modeling (12), elements (21), views/sheets (15), parameters (11), annotation (5), materials/QA (4), exports (5), groups/worksharing (9), schedules/phasing (7), escape hatches `revit_invoke_method` / `revit_reflect_get` / `revit_reflect_set` / `revit_execute_python` |
+| Rhino | 19 | `rhino_*` incl. `rhino_run_python`, `rhino_generate_diagrid_tower` |
+| Speckle | 17 | OAuth-PKCE + projects/models/versions/publish/merge |
+| Autodesk/APS | 12 | OAuth + hubs/projects/items/issues |
+| IFC | 7 | metadata, spatial structure, query, properties, bbox, validate |
+| Semantic graph | 7 | `graph_compile`, relations, clash/disconnected/load audits |
+| Mapper | 3 | `aec_translate_id`, `aec_register_mapping`, `aec_map_workspace_path` |
+| Exporter | 3 | SQLite model + graph export |
+| Jobs | 2 | `job_status`, `job_cancel` |
+
+**Defined but NOT reachable:** Navisworks (4 tools, legacy server only), PowerBI (5 tools, nowhere), `fake_tool` (tests), proxy tools (env-gated).
+
+## 4. Docs inventory
+
+| File | Verdict |
+|---|---|
+| `README.md` | Good landing, but **broken links** to nonexistent `docs/tools.md`, `docs/architecture.md`, `docs/integration-expansion-handover.md`; describes Rhino via SSE :9876 (as-built is HTTP :3004); presents Navisworks as shipped |
+| `CHANGELOG.md` | At 1.2.0 while `pyproject.toml`/`RevitBridge.csproj`/`server.json` say **1.1.0** |
+| `CLAUDE.md` | Titled "Omni-Bridge"; **wrong Navisworks port (3005 vs 3002)**; points to nonexistent `docs/agent-task-plan.md` as "canonical backlog" |
+| `docs/0001-multi-provider-architecture.md` | Accurate ADR, status still "Proposed" though built — flip to Accepted |
+| `docs/0002-switch-contract-v2.md` | Accurate; note v2 is opt-in at runtime |
+| `docs/0007-hub-performance-posture.md` | Current |
+| `docs/system-blueprint-and-workflows.md` | **Most valuable doc** (36 KB, self-auditing §0), but references deleted docs and gone `providers/speckle.py` |
+| `docs/roadmap-and-plans.md` | Real roadmap (Phases A–I); overstates Navisworks/PowerBI as shipped; overlaps blueprint §10 |
+| `docs/security.md` | **Most stale doc**: documents the dead 25-tool system and config keys (`allow_destructive`, `allowed_tools`, `destructive_confirm`) that **don't exist in `config.py`**; contradicts ADR 0002 on auth |
+| `docs/tools-generated.md` | Auto-generated; lists Navisworks/PowerBI tools the hub doesn't register; `Mutating?` columns all "?" (metadata gap) |
+| `docs/ecosystem-strategy-and-monetization.md` | Flagged private, **currently committed to a public-destined repo — exposure risk** |
+| `configuration-reference.md`, `install.md`, `build-and-install-scripts.md`, `marketplaces.md`, `revit-addin-lifecycle.md`, `logging-and-audit.md` | Current and accurate |
+| `target-frameworks-and-dependencies.md` | Mostly current; dependency list omits `mcp`, `ifcopenshell`, `networkx`, `specklepy` |
+| CONTRIBUTING / LICENSING / SECURITY / TRADEMARKS / NOTICE | Current; licensing hygiene is genuinely mature |
+
+## 5. As-documented vs as-built divergences
+
+1. Navisworks switch advertised; provider unregistered in shipped hub.
+2. PowerBI advertised (badges, CHANGELOG, commit 949d2e5); provider orphaned.
+3. README says Rhino = SSE :9876/Rhino.Compute; reality = HTTP :3004 provider.
+4. Two hub servers; tests split across them; `server.py` has the `_connect()` bug.
+5. Source tree advertises MEP/stairs/structural command modules that are compile-excluded.
+6. `security.md` says "no auth" while ADR 0002 + code implement bearer tokens — but LegacyMode default makes "no auth" the *runtime* truth. Both docs need one story.
+7. Approval/destructive-action config documented but not implemented → this is the MVP's core build item, not a config fix.
+8. Version drift 1.2.0 vs 1.1.0; port drift (CLAUDE.md Navis 3005 vs 3002).
+
+## 6. Strong
+
+- Provider abstraction (`AECProvider` + registry) — adding an integration is one class.
+- 110 working Revit commands with correct ExternalEvent threading + IronPython escape hatch.
+- Async jobs, PII/path redaction, workspace sandboxing, semantic graph, SQLite exporter, OAuth-PKCE cloud connectors.
+- 14-module test suite incl. contract + perf tests; mock mode for CI.
+- ADRs + self-auditing blueprint; mature dual-licensing/trademark hygiene; multi-target C# build already in place.
+
+## 7. Weak
+
+- Naming chaos (§1). Two servers + legacy tool system obscure the real surface.
+- Doc drift everywhere a user would look first (README links, security.md, tool catalog).
+- Advertised-but-unreachable connectors erode trust in all other claims.
+- No mutation metadata on Python tools; no approval layer; no UI beyond ribbon stub.
+- ~260 MB stray Rhino binaries in `docs/` (`Untitled*.3dm/.3dmbak/.rhl`); stray `Omni_LiveGeometryStats.csv`; tracked caches (`.pytest_cache/`, `.ruff_cache/`); committed `dist/` incl. legacy `dist/RevitMCP/`.
+
+## 8. Missing
+
+- Approval/undo layer (the product's core promise). Dockable panel UI. Module registry. Semantic BIM schema (identity mapper exists; no element-level roundtrip schema). Orchestrator/recipes (Phase C). Parquet/DuckDB + `.pbit` (Phase D). MkDocs site. `.env.example` covering `SPECKLE_CLIENT_ID`, `APS_CLIENT_ID`, `MCP_PROXY_TARGETS`, `MCP_REVIT_LEGACY_PORT`, etc.
+
+## 9. Consolidation / archival candidates — **approval required before touching**
+
+**Delete (accidental binaries):** `docs/Untitled.3dm`, `docs/Untitled2.3dm`, `docs/Untitled.3dmbak`, `docs/Untitled2.3dmbak`, `docs/Untitled.3dm.rhl` (~260 MB), `Omni_LiveGeometryStats.csv`.
+
+**Untrack:** `dist/` (both trees; CONTRIBUTING says don't commit), `.pytest_cache/`, `.ruff_cache/`, empty `metrics/`.
+
+**Move to private repo:** `docs/ecosystem-strategy-and-monetization.md`.
+
+**Retire after test migration:** `revit_mcp_server/server.py`, `tools/{handlers,document,health}.py`, legacy parts of `schemas.py`, `providers/fake.py` (or move under `tests/`).
+
+**Delete or revive (decide):** `packages/revit-bridge-addin/src/Commands/**` dead tree.
+
+**Rewrite:** `docs/security.md` (against as-built), README links, CLAUDE.md port table + backlog pointer; regenerate `docs/tools-generated.md` after mutation-metadata work.
+
+**Keep, reconcile:** `roadmap-and-plans.md` vs blueprint §10 overlap → roadmap stays strategy, blueprint stays architecture, this `docs/product/` package becomes the buildable plan; version bump artifacts to match CHANGELOG.
diff --git a/docs/product/DECISIONS_AND_RISKS.md b/docs/product/DECISIONS_AND_RISKS.md
new file mode 100644
index 0000000..7645c31
--- /dev/null
+++ b/docs/product/DECISIONS_AND_RISKS.md
@@ -0,0 +1,72 @@
+# Decisions & Risks Log
+
+Append-only. Decisions carry status: **Decided** (by Sam) / **Proposed** (needs Sam) / **Open**.
+
+## Decisions
+
+| ID | Decision | Status | Rationale |
+|---|---|---|---|
+| D-001 | Product name = **AEC Model Bridge**; "Omni-Bridge" = legacy/ecosystem narrative only | **Decided** 2026-07-08 | Matches repo slug, PyPI, server.json; ends 4-name chaos |
+| D-002 | MVP = inspect (W1) → QA/QC (W7/W9) → parameters (W5); **façade roundtrip deferred** to Phase-2 flagship | **Decided** 2026-07-08 | Three workflows share one semantic layer; façade proves it publicly afterwards |
+| D-003 | MVP audience = **normal Revit users**; dockable WebView2 panel + approval queue in first release | **Decided** 2026-07-08 | Product differentiation is the safety UX, not the tool count |
+| D-004 | One hub server: `mcp_server.py`; retire `server.py` + legacy `tools/`/25-tool system after test migration | Proposed | Two servers with divergent providers/env vars confuse everything; `server.py` has a known `_connect()` bug |
+| D-005 | Revit targets: **net48 (2024) + net8 (2025/26)** shipped; net10 (2027) experimental | **Decided** 2026-07-08 | Multi-target already in csproj; broadest firm reach |
+| D-006 | Contract v2 (dynamic port + bearer) becomes **runtime default**; legacy :3000 opt-in | Proposed | Unauthenticated default contradicts the safety story; ADR 0002 already accepted |
+| D-007 | Approval gate enforced in the **hub** (single choke point), C# `ConfirmationRequired` stays defense-in-depth | Proposed | One enforcement point across all switches; direct-HTTP callers still guarded |
+| D-008 | Panel UI = WebView2-hosted web app, WPF only as pane chrome | Proposed | Iteration speed; reusable across hosts; spike memory/load-order in P16.1 first |
+| D-009 | Power BI: **file lane first** (SQLite→.pbit); live ADOMD lane wired health-only until pulled | Proposed | External-tool session handshake is fragile; file lane delivers value now |
+| D-010 | Hub install for non-programmers: bundled Python runtime in installer (pipx as expert path) | Open | Decide at P19; bundled ≈ +80 MB but zero-friction |
+| D-011 | Dead C# tree `src/Commands/**`: delete after per-subsystem salvage review | Open — needs Sam | 0 registered commands, compile-excluded; keeping it misleads every future agent |
+| D-012 | CI Revit e2e: self-hosted runner vs scripted-local-only | Open | Depends on Sam's hardware/licensing; goldens must run *somewhere* nightly |
+| D-013 | Git history rewrite to purge 92 MB binaries (BFG) vs plain `git rm` | Open — needs Sam | Rewrite breaks clones/forks; rm leaves history heavy |
+| D-014 | Docs package lives in `docs/product/`, monetization content excluded (private doc moves out, P0.2) | **Decided** 2026-07-08 | Public-repo hygiene |
+
+## Risks
+
+### Revit API
+- **R1 Threading/deadlock:** all writes must ride the existing ExternalEvent queue; any new code path that touches the API off-thread crashes Revit. *Mitigation:* single choke point (`RevitCommandExecutor`), reviewed by Security/Safety agent; no async API access ever.
+- **R2 Snapshot perf on big models:** 100k+ elements × params is minutes, not seconds. *Mitigation:* incremental extraction via `DocumentChanged` dirty-list (P3.4), category filtering, measure before optimizing (ADR 0007 budgets).
+- **R3 Multi-target drift:** net48 vs net8 API differences (nullable, some API changes 2024→2025). *Mitigation:* CI builds both; `#if` islands kept minimal; Nice3point packages per version.
+- **R4 Worksharing:** writes to elements owned by others fail mid-plan. *Mitigation:* ownership check at plan time; partial-apply policy = report-and-continue with explicit summary (never silent).
+
+### MCP
+- **R5 Tool-count bloat (~170+):** agents pick wrong tools. *Mitigation:* metadata + module namespacing; curated tool subsets per surface; snapshot-first querying reduces call volume.
+- **R6 MCP SDK churn** (`mcp>=0.9.0`): breaking spec changes. *Mitigation:* pin + contract tests; adapter layer is thin.
+- **R7 Breaking the shipped surface:** renames strand existing users. *Mitigation:* additive-only within 1.x; renames need human approval (swarm rule).
+
+### Plugin app
+- **R8 WebView2 in Revit process:** memory pressure, runtime missing, load-order clashes with other add-ins. *Mitigation:* P16.1 spike before committing; WPF fallback documented as plan B.
+- **R9 Installer/AV friction:** unsigned DLLs + local HTTP server look suspicious. *Mitigation:* code-signing cert (P19), loopback-only listener, clear firewall docs.
+
+### Semantic data
+- **R10 Schema churn after freeze:** downstream (rules, panel, exporters) all break. *Mitigation:* append-only within major; `schema_version` everywhere from first byte.
+- **R11 UniqueId edge cases:** SaveAs, detach, IFC re-export change identity anchors. *Mitigation:* doc-guid anchoring + re-anchor prompt (W9); mapper keeps provenance.
+
+### AI agents
+- **R12 Silent mutation = product death.** One incident of an AI changing a model without approval kills trust permanently. *Mitigation:* gate default-on, `approve_plan` not callable by agents on panel surface, audit ledger, `agent_reviewer` second-model check (P2 tier). **This is the risk the whole architecture exists to kill.**
+- **R13 Query hallucination:** wrong answers about the model are almost as bad. *Mitigation:* DSL-validated `snapshot_query` is the only query path; answers cite element uids; golden Q&A tests.
+- **R14 Swarm merge conflicts / context loss:** *Mitigation:* path ownership, contract freezes, worktrees, handover format (swarm plan).
+
+### Integrations
+- **R15 Version matrices** (Rhino×RiR×Revit, Dynamo×Revit, PBI sessions): support cost explodes. *Mitigation:* pinned supported matrix per release; everything else "community-tested".
+- **R16 OAuth secrets/tokens** (Speckle/APS) on disk. *Mitigation:* existing redaction + OS credential store at P20; never in workspace exports.
+
+### Performance
+- **R17 Chat context flooding:** dumping element lists into LLM context. *Mitigation:* payload caps, snapshot files + summaries, uid-chip pattern.
+
+### Security
+- **R18 Unauthenticated legacy port** during transition (today's default!). *Mitigation:* D-006 flip early (P3.1); loopback-only binding already in place.
+- **R19 `*_execute_python` / reflection escape hatches** bypass all semantics. *Mitigation:* `python.host` permission, expert-mode only, off by default, always audited.
+- **R20 Third-party modules run arbitrary code.** *Mitigation:* trust-model doc, explicit enable per module dir, firm allowlist (P20.1).
+
+### Adoption
+- **R21 "Another automation tool" skepticism + AI-in-production fear.** *Mitigation:* the demo arc leads with approval/rollback, not with AI magic; read-only workflows first in every firm rollout.
+- **R22 Solo-maintainer bus factor / burnout.** *Mitigation:* the swarm plan and this package *are* the mitigation — any capable agent session can resume from `NEXT_AGENT_HANDOVER.md`.
+
+## Open questions
+
+1. D-010/D-011/D-012/D-013 need Sam's call (installer runtime, dead tree, CI runner, history rewrite).
+2. Which Revit version is on Sam's machine right now? (Determines the first e2e loop; multi-target can compile blind but e2e cannot.)
+3. Panel LLM plumbing for non-Claude-Code users: MVP assumes Claude Code/desktop as the agent host — does v1.3.0 need an embedded API-key client, or is "bring Claude" acceptable for first release?
+4. Rule pack authorship: which 15 rules does Sam's project experience rank highest? (P10.2 review gate.)
+5. Canonical test model style: generic office tower vs façade-heavy tower (dual-purpose for P11 demo)?
diff --git a/docs/product/INTEGRATION_STRATEGY.md b/docs/product/INTEGRATION_STRATEGY.md
new file mode 100644
index 0000000..52c337d
--- /dev/null
+++ b/docs/product/INTEGRATION_STRATEGY.md
@@ -0,0 +1,98 @@
+# Integration Strategy
+
+Priorities: **P0** = MVP, **P1** = flagship/next, **P2** = after P1, **Future**. "Exists" reflects the audit in `CURRENT_REPO_AUDIT.md`.
+
+| # | Integration | Priority | Exists today |
+|---|---|---|---|
+| 1 | Revit API | P0 | 110 C# commands / 100 MCP tools ✓ |
+| 2 | MCP | P0 | hub + 9 providers ✓ |
+| 3 | Claude Code | P0 | via MCP stdio ✓ |
+| 4 | VS Code | P0 | via MCP config ✓ |
+| 5 | GitHub | P0 | repo/CI workflows ✓ |
+| 6 | Excel | P0 | ✗ (SQLite exists; xlsx new) |
+| 7 | IFC | P0 | 7 tools ✓ |
+| 8 | Rhino / Grasshopper | P1 | 19 tools + bridge :3004 ✓ |
+| 9 | Rhino.Inside.Revit | P1 | ✗ |
+| 10 | Speckle | P1 | 17 tools ✓ (OAuth) |
+| 11 | Navisworks | P1 | C# 16 cmds ✓ / provider unregistered ✗ |
+| 12 | Power BI | P1 | C# tool :3006 partial / provider orphaned ✗ |
+| 13 | Dynamo | P2 | scratch prototypes only |
+| 14 | DuckDB / Parquet | P2 | ✗ (roadmap Phase D) |
+| 15 | APS / ACC | P2 | 12 tools ✓ (OAuth) |
+| 16 | Local AI agents (BYO-LLM) | P2 | ✗ (roadmap Phase H) |
+| 17 | MS Graph | Future | ✗ |
+| 18 | Cloud / remote MCP | Future | ✗ (roadmap Phase H) |
+
+---
+
+### 1. Revit API — P0
+- **Purpose/value:** the product's substrate; native reads/writes. **Data:** elements, params, views, sheets, transactions.
+- **Method:** existing add-in (`HttpListener` → `ExternalEvent` → `BridgeCommandFactory`), Contract v2 flipped to default. Multi-target net48 (2024) + net8 (2025/26); net10 (2027) stays experimental.
+- **SDK:** RevitAPI.dll local or `Nice3point.Revit.Api.*` (both wired).
+- **MVP:** stabilize 110 commands, add snapshot extraction command, mutation metadata parity. **Advanced:** revive/kill dead `Commands/**` tree per subsystem; worksharing-aware writes.
+- **Risks:** API-thread deadlocks (mitigated by existing queue); version drift across targets. **Test:** e2e against canonical model per Revit version (CI matrix where licensable; else scripted local runs).
+
+### 2. MCP — P0
+- **Purpose:** stable machine contract for all agents/clients. **Data:** tool schemas, results, job refs.
+- **Method:** `mcp_server.py` only (retire `server.py`); `ProviderTool` gains `is_mutating`/`destructive`/`execution_mode`/`permissions`; regenerate `tools-generated.md`.
+- **MVP:** metadata + approval-gate tools (`plan_actions`, `approve_plan`, `list_pending_plans`). **Advanced:** MCP resources for snapshots, prompts for common workflows.
+- **Risks:** spec evolution (`mcp>=0.9.0` pin — track SDK releases); tool-count bloat degrading agent tool choice (group via module namespacing). **Test:** existing `test_provider_contract.py` extended to assert metadata on every tool.
+
+### 3. Claude Code — P0
+- **Purpose:** expert surface + the swarm that builds the product. **Method:** `server.json` MCP config; project skills (`/rhino-god-mode` exists); `CLAUDE.md` corrections (ports, backlog pointer).
+- **MVP:** clean install docs + working config. **Advanced:** packaged workflow skills (`/model-health`, `/param-batch`). **Risk:** none structural. **Test:** fresh-clone smoke script.
+
+### 4. VS Code — P0
+- **Purpose:** developer/automation-engineer surface. **Method:** same MCP server via VS Code MCP config; no bespoke extension for MVP (Future: status/log viewer extension). **Test:** documented setup walkthrough.
+
+### 5. GitHub — P0
+- **Purpose:** CI, releases, module distribution. **Method:** existing repo + Actions: pytest + `dotnet build` matrix (net48/net8), DLL license scan (exists per LICENSING), release artifacts (installer + wheel). **MVP:** CI green on both stacks. **Advanced:** module marketplace via releases/registry repo. **Risk:** Revit API DLLs not redistributable — CI uses Nice3point NuGet fallback (already supported).
+
+### 6. Excel — P0
+- **Purpose:** the report format management actually opens. **Data:** element/param/finding tables; CSV param roundtrip.
+- **Method:** `openpyxl` in hub (`export_excel` tool). **MVP:** 3-sheet workbook (elements, parameters, findings). **Advanced:** formatted QA dashboards, roundtrip validation. **Risks:** file locks; huge sheets (row cap + link to SQLite). **Test:** golden workbook diff on canonical model.
+
+### 7. IFC — P0
+- **Purpose:** open-standard read/validation lane; non-Revit data QA. **Data:** GlobalId, spatial tree, psets.
+- **Method:** `ifcopenshell` provider (exists, 7 tools) + mapper (GlobalId↔UniqueId). **MVP:** IFC Q&A + Revit-vs-IFC comparison. **Advanced:** IDS validation (Phase D), IFC export QA (`revit_export_ifc` then re-validate). **Risks:** ifcopenshell wheel/platform pinning. **Test:** sample IFC fixtures in repo.
+
+### 8. Rhino / Grasshopper — P1
+- **Purpose:** computational design lane; façade flagship. **Data:** panel geometry, semantic zone specs, preview meshes.
+- **Method:** existing C# bridge :3004 (`run_python` is the workhorse) + MCP `g1_*` GH canvas tools; GH emits semantic spec JSON, not meshes.
+- **MVP(P1):** façade zone spec exporter GH definition. **Advanced:** live-link, `CurtainWallDetailer`/`DiagridGenerator` productization. **Risks:** RhinoCommon v7 vs v8 API drift (reflection helpers exist); hardcoded port (move to Contract v2). **Test:** scripted Rhino headless run → spec → golden diff.
+
+### 9. Rhino.Inside.Revit — P1
+- **Purpose:** GH against live Revit geometry, in-process. **Method:** custom GH components wrapping hub endpoints; RiR emits semantic specs → ActionPlans (no write bypass).
+- **SDK:** RiR nuget/SDK; supported version matrix documented. **MVP(P1):** one exemplar definition. **Advanced:** Revit-selection-driven GH inputs. **Risks:** RiR/Rhino/Revit version triangle; load order with our add-in. **Test:** manual matrix checklist + exemplar run.
+
+### 10. Speckle — P1
+- **Purpose:** versioned transport + web viewing + external collaborators. **Data:** semantic snapshots as Speckle objects.
+- **Method:** 17 existing tools (`specklepy>=3`); publish snapshot → receive delta → W14 reconciliation. **MVP(P1):** publish/receive snapshot roundtrip. **Advanced:** branch-per-variant façade workflow. **Risks:** Speckle v3 API churn; OAuth token lifetime (refresh exists). **Test:** `test_cloud_providers.py` extended with mock server (exists) + live smoke.
+
+### 11. Navisworks — P1
+- **Purpose:** coordination/clash results back into the loop. **Data:** model tree, clash tests/results, viewpoints.
+- **Method:** **register `NavisworksProvider` in `mcp_server.py`** and widen it to the 16 C# commands (`navis.run_clash_test`, `navis.get_clash_results`, viewpoints, tree); clash GUIDs → mapper → Revit selection.
+- **MVP(P1):** health + model tree + clash results → Revit element selection. **Advanced:** auto-viewpoint per QA finding; NWD export pipeline from `revit_export_navisworks` (exists). **Risks:** Navisworks COM quirks; GUID mapping fidelity. **Test:** RVT+NWF fixture pair.
+
+### 12. Power BI — P1
+- **Purpose:** live dashboards; "ask your dashboard" DAX Q&A. **Data:** DAX queries/results; exported tables.
+- **Method (two lanes):** (a) file lane — SQLite→(later Parquet) + shipped `.pbit`; (b) live lane — wire orphaned `PowerBIProvider` to the :3006 ADOMD external tool.
+- **MVP(P1):** file lane + provider registration with health. **Advanced:** DAX Q&A, auto-refresh. **Risks:** external-tool launch args change per PBI session (re-handshake needed); ADOMD licensing/runtime deps. **Test:** DAX smoke against a fixture PBIX.
+
+### 13. Dynamo — P2
+- **Purpose:** meet Revit users where they are. **Method:** ZeroTouch node package calling hub HTTP; nodes = thin wrappers over the same semantic spec + gate. **MVP(P2):** 5 nodes (connect, snapshot, query, plan, apply). **Risks:** Dynamo versioning per Revit release. **Test:** sample graph in repo.
+
+### 14. DuckDB / Parquet — P2 (roadmap Phase D)
+- **Purpose:** analytics-grade data plane; multi-model portfolio queries. **Method:** exporter grows Parquet writer; DuckDB for local SQL; PBI reads Parquet. **MVP(P2):** Parquet mirror of SQLite schema. **Risks:** schema evolution discipline (`schema_version` from day one — see W8). **Test:** row-count parity SQLite↔Parquet.
+
+### 15. APS / ACC — P2
+- **Purpose:** cloud model/issue integration for enterprise. **Method:** 12 existing `autodesk_*` tools; QA findings → ACC Issues (`autodesk_data_create_issue` exists). **MVP(P2):** findings→Issues. **Risks:** APS app provisioning/scopes; rate limits. **Test:** mocked + sandbox hub.
+
+### 16. Local AI agents / BYO-LLM — P2 (roadmap Phase H)
+- **Purpose:** firms that can't send model data to cloud LLMs. **Method:** hub is client-agnostic already (MCP); document Ollama/LM Studio MCP-client setups; approval gate matters *more* here. **Risk:** small-model tool-choice quality → provide curated tool subsets per module.
+
+### 17. MS Graph — Future
+- Teams notifications of QA runs, SharePoint report drops, Planner tasks from findings. Method: Graph SDK in hub; requires tenant app registration. Park until enterprise pull.
+
+### 18. Cloud / remote MCP — Future
+- REST/OpenAPI facade + hosted hub (roadmap Phase H). Blockers: auth story beyond localhost bearer, multi-tenant workspace isolation. Do not start before packaging (Phase 19) is done.
diff --git a/docs/product/MVP_EXECUTION_PLAN.md b/docs/product/MVP_EXECUTION_PLAN.md
new file mode 100644
index 0000000..d4170ef
--- /dev/null
+++ b/docs/product/MVP_EXECUTION_PLAN.md
@@ -0,0 +1,80 @@
+# MVP Execution Plan
+
+Locked decisions (2026-07-08): audience = **normal Revit users first** (dockable panel + approvals); killer workflows = **inspect → validate → fix** (façade roundtrip deferred to Phase-2 flagship); targets = **Revit 2024 (net48) + 2025/26 (net8)**, multi-target already in `RevitBridge.csproj`.
+
+## Build first (in order)
+
+1. **Phase 0 cleanup** — the repo must stop contradicting itself before anything ships (README links, security.md, ports, 260 MB binaries, version drift).
+2. **Approval gate + tool metadata** (P4) — the product's core promise; everything else hangs off it.
+3. **Snapshot extraction** (P3.3 + P6) — one data layer that all three workflows query.
+4. **Three killer workflows** as modules (P7, P10, P9 — in that order: read → validate → write).
+5. **Dockable panel** (P16, parallel from step 3 behind fixed endpoint contracts).
+6. **Installer** (P19 minimal) — a BIM manager must install without pip knowledge.
+
+## Delay (explicitly)
+
+Façade configurator (P11 — flagship demo *after* MVP proves the layer), RiR/GH components (P12), Speckle/Navisworks workflows beyond provider registration (P13), Power BI live lane, Parquet/DuckDB (P14 partial), orchestrator/recipes (P15), Dynamo, APS, remote MCP, marketplace.
+
+## Do not overbuild
+
+- **Module system:** discovery + manifest + permissions only; no marketplace, no sandboxing beyond the trust-model doc, no hot reload.
+- **Panel:** chat + plan cards + findings + log. No dashboards, no settings sprawl, no theming.
+- **QA rules:** 15 curated rules that are *right*, not 100 that are noisy.
+- **Rollback:** undo + inverse-for-parameters. No general time-travel.
+- **Snapshot:** bbox-level geometry refs only; no mesh pipelines in MVP.
+- **Auth:** localhost bearer (Contract v2). No user accounts, no cloud.
+
+## First 3 killer workflows
+
+1. **W1 Ask the model** — NL question → snapshot query → answer with clickable element chips.
+2. **W7 Model health check** — one click → 15-rule findings report → exportable, trackable (W9-lite issue list).
+3. **W5 Batch parameters with approval** — filter → diff grid → approve → apply → rollback.
+
+Demo arc (one sitting, canonical model): *ask "how many doors lack fire ratings?" → run health check, see it as a finding among others → fix all 37 via approved batch-set → re-check shows resolved → export Excel report → hit Undo/rollback to prove safety.*
+
+## First 10 MCP tools (new/changed; the ~170 existing stay)
+
+| # | Tool | Phase |
+|---|---|---|
+| 1 | `snapshot_take` | P6 |
+| 2 | `snapshot_query` | P6 |
+| 3 | `snapshot_diff` | P6 |
+| 4 | `plan_actions` | P4 |
+| 5 | `list_pending_plans` | P4 |
+| 6 | `approve_plan` (panel-only surface; agents may not self-approve) | P4 |
+| 7 | `rollback_plan` | P4 |
+| 8 | `qaqc_run_health_check` | P10 |
+| 9 | `qaqc_list_issues` | P10 |
+| 10 | `export_excel` | P14.1 (pulled into MVP) |
+
+Plus metadata backfill on all existing tools (P4.1) and `revit.extract_snapshot` on the C# side (P3.3).
+
+## First 5 plugin UI commands (ribbon)
+
+1. **Open Bridge Panel** 2. **Run Health Check** 3. **Review Pending Actions** (badge = pending count) 4. **Inspect Selection** 5. **Export Report**
+
+## First semantic data schema
+
+`amb.snapshot/1` exactly as `SEMANTIC_BIM_DATA_MODEL.md` §2 — ElementRecord + Relations (hosts/bounds/on_level/in_group/on_sheet) + TypeRecord. Delta/zone/variant schemas are frozen on paper but implemented post-MVP.
+
+## First test model
+
+Generator script (P17.1), not a binary: 5 levels, ~200 walls, 60 doors (12 missing FireRating), 40 windows, 25 rooms (3 unplaced, 2 unenclosed), 30 views (6 unnamed, 8 not on sheets), 10 sheets (2 duplicate numbers), 4 model groups, 2 in-place families, seeded warnings. Every seeded defect maps to exactly one core rule → golden findings file.
+
+## First demo scenario
+
+The demo arc above, recorded on the canonical model, driven entirely from the panel (no code visible) — this is also tutorial 2 and the flagship-pitch opener.
+
+## First release checklist (v1.3.0)
+
+- [ ] Phase 0 complete: no doc/code contradictions, versions reconciled, binaries purged (with Sam's approval)
+- [ ] Contract v2 default; unauthenticated :3000 requires explicit opt-in
+- [ ] All tools metadata-complete; `tools-generated.md` regenerated without "?"
+- [ ] Approval gate: mutating call without approved plan is rejected (test-proven)
+- [ ] 3 killer workflows green on canonical model goldens (CI or scripted local e2e)
+- [ ] Panel drives all 3 workflows; hub-down/no-doc states handled
+- [ ] Installer on clean Windows 11 + Revit 2024 and 2025 → tutorial 1 in <15 min
+- [ ] Audit ledger records every mutation with plan/action ids; rollback demo passes
+- [ ] Docs: quickstart, 3 tutorials, security model rewrite, module authoring stub
+- [ ] `LICENSES/` DLL scan green; no `Co-Authored-By` trailers anywhere in release history
+- [ ] Sam sign-off on demo recording
diff --git a/docs/product/NEXT_AGENT_HANDOVER.md b/docs/product/NEXT_AGENT_HANDOVER.md
new file mode 100644
index 0000000..c387b4f
--- /dev/null
+++ b/docs/product/NEXT_AGENT_HANDOVER.md
@@ -0,0 +1,31 @@
+# Next Agent Handover
+
+**Session:** 2026-07-08, planning/scaffolding only — **no production code written, nothing deleted.**
+
+## What was inspected
+Full repo audit (delegated to an Explore subagent): all root + `docs/` markdown, all 5 packages (hub providers/servers/tests, Revit add-in incl. `BridgeCommandFactory.cs` and csproj exclusions, Rhino/Navisworks bridges, PowerBI tool), `scripts/`, `dist/`, `server.json`, git log vs CHANGELOG. Findings preserved in `CURRENT_REPO_AUDIT.md`.
+
+## What was created (all new, in `docs/product/`)
+`AEC_MODEL_BRIDGE_PRODUCT_VISION.md` · `CURRENT_REPO_AUDIT.md` · `PLUGIN_APP_ARCHITECTURE.md` · `AEC_WORKFLOW_CATALOG.md` (W1–W16) · `INTEGRATION_STRATEGY.md` (18 integrations, P0–Future) · `PLUGIN_MODULE_SYSTEM.md` · `SEMANTIC_BIM_DATA_MODEL.md` · `AI_AGENT_SWARM_PLAN.md` (14 agents) · `SCAFFOLDING_TASK_LIST.md` (Phases 0–21) · `MVP_EXECUTION_PLAN.md` · `DECISIONS_AND_RISKS.md` · this file.
+
+## What was NOT changed
+No existing file edited or deleted. CLAUDE.md still has the wrong Navisworks port (3005→3002) and dead backlog pointer; README links still broken; `docs/security.md` still stale; 260 MB stray `.3dm*` binaries still in `docs/`; private strategy doc still in repo; versions still 1.1.0 vs CHANGELOG 1.2.0. All of that is **Phase 0** work awaiting Sam's approval of the deletion list (`CURRENT_REPO_AUDIT.md` §9).
+
+## Main findings (from the audit)
+1. Shipped hub = `mcp_server.py`, 9 providers, ~170 tools; a **legacy parallel server** (`server.py` + 25-tool `tools/` system) confuses tests and docs, and has a real bug (`proxy._connect()` doesn't exist).
+2. **Navisworks provider is not registered** in the shipped hub; **PowerBI provider registered nowhere** — both are advertised as working.
+3. Revit add-in is solid (110 attribute-registered commands, correct ExternalEvent threading), but `src/Commands/**` is a compile-excluded dead tree, and **Contract v2 auth exists but LegacyMode (port 3000, no auth) is the runtime default**.
+4. The approval/destructive-action layer documented in `docs/security.md` **was never implemented** — it is the MVP's core build item.
+5. Four competing product names; D-001 fixes it as **AEC Model Bridge**.
+
+## Decisions locked with Sam (see DECISIONS_AND_RISKS.md)
+D-001 name · D-002 MVP = inspect/QA-QC/parameters, façade deferred to flagship · D-003 normal-Revit-user audience with dockable panel + approvals · D-005 net48+net8 targets · D-014 docs in `docs/product/`, strategy-free.
+
+## Biggest risks
+R12 (silent AI mutation — the gate must be default-on and agent-unapprovable), R2 (snapshot perf on large models), R8 (WebView2-in-Revit spike unproven), D-013 (92 MB binaries may warrant history rewrite — needs Sam).
+
+## Recommended next task
+**Phase 0** (`SCAFFOLDING_TASK_LIST.md`): present the §9 deletion list to Sam, then execute the doc/version cleanup. It's low-risk, unblocks everything, and makes the repo stop contradicting itself. First *code* task after that: **P4.1 tool metadata + P4.2 approval gate** (pure Python, testable without Revit open).
+
+## Exact next prompt
+> Read docs/product/NEXT_AGENT_HANDOVER.md and docs/product/SCAFFOLDING_TASK_LIST.md. Execute Phase 0: first show me the deletion/untrack/move list from CURRENT_REPO_AUDIT.md §9 for approval, then apply approved items, fix CLAUDE.md (port 3002, backlog pointer → docs/product/SCAFFOLDING_TASK_LIST.md, retitle AEC Model Bridge), fix README broken links and the Rhino transport description, rewrite docs/security.md against the as-built provider system, and reconcile versions to CHANGELOG. Commit in logical chunks on development, no Co-Authored-By trailers.
diff --git a/docs/product/PLUGIN_APP_ARCHITECTURE.md b/docs/product/PLUGIN_APP_ARCHITECTURE.md
new file mode 100644
index 0000000..d5d4e0b
--- /dev/null
+++ b/docs/product/PLUGIN_APP_ARCHITECTURE.md
@@ -0,0 +1,86 @@
+# Plugin App Architecture
+
+Builds on what exists: `revit-bridge-addin` (110 commands, ExternalEvent path), the Python hub (9 providers, ~170 tools), ADR 0001/0002. New layers are marked **[NEW]**.
+
+## 1. Layer map
+
+```
+┌─ Surface ──────────────────────────────────────────────────────────┐
+│ Revit dockable panel [NEW] Ribbon tab (exists, grows) │
+│ Claude Code / MCP clients (exists) VS Code (exists via MCP) │
+├─ AI agent layer ───────────────────────────────────────────────────┤
+│ Claude via MCP stdio (exists) · agent proposes ActionPlans [NEW] │
+├─ Hub (Python, packages/mcp-server-revit) ──────────────────────────┤
+│ mcp_server.py · ProviderRegistry (exists) │
+│ Approval Gate [NEW] · Module Registry [NEW] · Audit log (extend) │
+│ Semantic BIM layer [NEW] · IdentityMapper/Graph/Exporter (exist) │
+│ JobManager async (exists) · Redaction/workspace sandbox (exist) │
+├─ Switches (C# HTTP, Contract v2) ──────────────────────────────────┤
+│ Revit :3000/v2 (exists) · Rhino :3004 · Navis :3002 · PBI :3006 │
+├─ Host APIs ────────────────────────────────────────────────────────┤
+│ Revit API (ExternalEvent+Transaction) · RhinoCommon · Navis .NET │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+## 2. Revit add-in layer (C#)
+
+Keep the proven pipeline: `BridgeServer` (HttpListener) → `CommandQueue.Enqueue` → `ExternalEvent.Raise()` → `RevitCommandExecutor` on API thread → `BridgeCommandFactory`.
+
+Changes:
+- **Contract v2 becomes default** (flip `LegacyMode`): dynamic loopback port, registry file `%LOCALAPPDATA%\AECModelBridge\registry\revit-<pid>.json`, bearer token on `/execute`. Kill unauthenticated :3000 default. (D-006)
+- **Transaction discipline [NEW policy]:** every mutating handler wraps exactly one named `Transaction` (`"AMB: <module>.<command> #<action_id>"`). Multi-step actions use `TransactionGroup` and assimilate. Name = the undo entry the user sees; `action_id` links Revit undo history to the audit log.
+- **Dockable panel [NEW]:** `IDockablePaneProvider` hosting **WebView2**; panel UI is HTML/JS talking to the add-in over the WebView2 message bridge, and to the hub via localhost. WPF only for the pane chrome. Rationale: web UI iterates fast, reuses across hosts later.
+- **Ribbon:** existing `AEC Bridge` tab grows to: Open Panel · Run Health Check · Review Pending Actions · Reports · Settings.
+- **Dead tree decision:** `src/Commands/**` (compile-excluded) is deleted or revived per subsystem — audit item, human call (D-011).
+
+## 3. MCP server layer (Python hub)
+
+- **One server.** `mcp_server.py` is canonical; `server.py` + legacy `tools/` retire after test migration (D-004).
+- **Register the strays:** NavisworksProvider into `mcp_server.py`; PowerBIProvider wired or explicitly parked.
+- **Tool metadata [NEW]:** extend `ProviderTool` with `is_mutating: bool`, `destructive: bool`, `execution_mode: sync|async`, `permissions: [str]` — mirrored from the C# `[BridgeCommand]` attributes so `tools-generated.md` stops printing "?".
+
+## 4. Safety & approval layer [NEW — the core product build]
+
+The keystone. `docs/security.md` documents `allow_destructive`/`destructive_confirm` keys that were never implemented; this replaces them.
+
+- **ActionPlan:** agents that want to mutate call `plan_actions` (new hub tool) with a list of intended tool calls + args. Hub validates schemas, dry-runs read-side (element counts, parameter before-values), returns a plan with `plan_id` and per-action diffs.
+- **Approval Gate:** mutating tools called without an approved `plan_id` are rejected when `approval_mode=required` (default in panel mode; `auto` available for headless/expert use, off by default). Pending plans surface in the dockable panel as cards → Approve / Reject / Approve-all-similar.
+- **Execution:** approved plan executes through the normal provider path; each action's transaction carries the `action_id`.
+- **Rollback:** per-action = Revit undo (named transaction); per-plan = `TransactionGroup` rollback while open, otherwise a generated inverse plan (e.g. restore captured before-values for parameter writes) — inverse plans only for reversible action types; others marked `irreversible: true` and require explicit confirm.
+- Enforcement lives in the **hub** (single choke point for all switches); the C# `ConfirmationRequired` attribute stays as defense-in-depth for direct HTTP callers.
+
+## 5. Logging & audit
+
+Extend the existing two-layer logging (`docs/logging-and-audit.md`): add an **audit ledger** (JSONL, `%LOCALAPPDATA%\AECModelBridge\audit\<doc-guid>\*.jsonl`): `{ts, user, agent, plan_id, action_id, tool, args_redacted, element_uids, before, after, result, transaction_name}`. Panel run-log reads this. Redaction pipeline (exists) applies before write.
+
+## 6. Data extraction & semantic BIM layer
+
+- **Extraction (exists):** `revit_list_elements`, `revit_get_element_parameters`, exporter → SQLite; IFC provider; graph provider.
+- **Semantic layer [NEW]:** typed element snapshots keyed by **Revit UniqueId**, with category/type/host/level/room relations — schema in `SEMANTIC_BIM_DATA_MODEL.md`. Built on `IdentityMapper` (exists) for cross-app identity. This is what QA rules, diffs, reports, and the façade roundtrip all consume — build once.
+
+## 7. Module registry & tool execution [NEW]
+
+Modules = manifest (JSON) + Python module class exposing commands that compose existing MCP tools; C# only when a new host-side primitive is needed. Discovery: `modules/` dir + entry points. Full spec: `PLUGIN_MODULE_SYSTEM.md`. Execution routes through the same registry → approval gate → provider path; long tasks via `JobManager`.
+
+## 8. Integration & reporting layers
+
+- Integration: providers (exist) + identity mapper + Contract v2 registry discovery. Strategy per system: `INTEGRATION_STRATEGY.md`.
+- Reporting: semantic snapshot → SQLite (exists) → Excel (openpyxl [NEW]) → Power BI (switch DAX or file-based). DuckDB/Parquet later (roadmap Phase D).
+
+## 9. Packaging & installer
+
+- Per-host add-in MSI/EXE (WiX or Inno) installing `.addin` + multi-target DLLs into version folders (build scripts exist: `docs/build-and-install-scripts.md`).
+- Hub via `pipx install aec-model-bridge` or bundled runtime in the installer (decide at Phase 19; bundled favors non-programmers).
+- MCP client config via existing `server.json` / marketplace listing (`docs/marketplaces.md`).
+
+## 10. What belongs where
+
+| Concern | Home |
+|---|---|
+| Anything touching Revit API objects, transactions, ExternalEvent, dockable pane hosting | **C# add-in** |
+| Providers, approval gate, module registry, semantic layer, identity, jobs, exporters, QA rules, report generation | **Python hub** |
+| Stable, schema'd, metadata-rich contract for agents; one tool = one capability | **MCP tools** |
+| Chat, plan cards, approve/reject, run log, report viewer (WebView2 HTML/JS) | **Plugin UI** |
+| Multi-step reasoning, repo/dev automation, orchestration recipes | **Claude Code / agent layer** |
+| OAuth'd cloud data (Speckle/APS), file formats (IFC), BI (DAX) | **External integrations via providers** |
+| Preview meshes only — GH previews, Navis overlay. **Never** deliverable geometry; native elements or explicit fallback with user consent | **DirectShape / dumb geometry** |
diff --git a/docs/product/PLUGIN_MODULE_SYSTEM.md b/docs/product/PLUGIN_MODULE_SYSTEM.md
new file mode 100644
index 0000000..71ee495
--- /dev/null
+++ b/docs/product/PLUGIN_MODULE_SYSTEM.md
@@ -0,0 +1,149 @@
+# Plugin Module System
+
+A **module** is the unit of product functionality: a manifest + a Python class in the hub that composes existing MCP tools into user-facing commands, plus optional UI cards and QA rules. C# changes are needed only when a module requires a new host-side primitive.
+
+## 1. Discovery
+
+Three sources, merged by the **ModuleRegistry** (new hub component, sibling of `ProviderRegistry`):
+
+1. **Built-in:** `revit_mcp_server/modules/<name>/` shipped with the wheel.
+2. **User/firm:** `%LOCALAPPDATA%\AECModelBridge\modules\<name>\` (workspace-sandbox rules apply).
+3. **Entry points:** `[project.entry-points."aec_model_bridge.modules"]` for pip-installed third-party modules.
+
+Load order: built-in → entry points → user (user wins on id collision, with a logged warning). A module = directory with `module.json` + `module.py` (+ `rules/*.yaml`, `ui/*.html`, `templates/`).
+
+## 2. Manifest format (`module.json`)
+
+```json
+{
+ "id": "qaqc_checker",
+ "name": "QA/QC Checker",
+ "version": "0.3.0",
+ "schema_version": 1,
+ "min_hub_version": "1.3.0",
+ "description": "Rule-based model health checks and issue tracking.",
+ "author": "AEC Model Bridge",
+ "license": "GPL-3.0-or-later",
+ "requires_providers": ["revit", "graph"],
+ "requires_tools": ["revit_get_warnings", "graph_audit_disconnected"],
+ "permissions": ["model.read", "workspace.write"],
+ "commands": [
+ {
+ "id": "run_health_check",
+ "title": "Run Health Check",
+ "surface": ["ribbon", "panel", "mcp"],
+ "mcp_tool": "qaqc_run_health_check",
+ "execution_mode": "async",
+ "is_mutating": false,
+ "destructive": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "ruleset": {"type": "string", "default": "core"},
+ "categories": {"type": "array", "items": {"type": "string"}}
+ }
+ },
+ "output_schema": {"$ref": "schemas/findings.json"}
+ },
+ {
+ "id": "apply_fixes",
+ "title": "Apply Suggested Fixes",
+ "surface": ["panel", "mcp"],
+ "mcp_tool": "qaqc_apply_fixes",
+ "execution_mode": "async",
+ "is_mutating": true,
+ "destructive": false,
+ "requires_plan": true,
+ "permissions": ["model.write"]
+ }
+ ],
+ "ui": {"panel_card": "ui/findings_card.html", "icon": "assets/icon.svg"},
+ "hooks": {"validate": "module:QaqcModule.validate", "on_result": "module:QaqcModule.log_summary"}
+}
+```
+
+## 3. Command exposure
+
+- **To users:** `surface: ["ribbon"|"panel"]` → the add-in queries the hub's `module_list_commands` at panel startup and renders buttons/cards. Ribbon slots are limited; modules mark at most one command `ribbon_priority`.
+- **To MCP:** every command with `"mcp"` surface registers as tool `<module_id>_<command_id>` through a `ModuleProvider` adapter, indistinguishable from provider tools and carrying the same metadata (`is_mutating`, `destructive`, `execution_mode`, `permissions`).
+
+## 4. Permissions
+
+Declared in manifest, enforced by the hub at call time; the panel shows them at install/enable time (consent screen).
+
+| Permission | Grants |
+|---|---|
+| `model.read` | read-only provider tools |
+| `model.write` | mutating tools — **always through ActionPlan gate** |
+| `model.delete` | destructive-flagged tools (separate consent) |
+| `workspace.write` | file output inside workspace sandbox (exists) |
+| `net.local` | other local switches (rhino/navis/pbi) |
+| `net.cloud` | speckle/aps/graph-API tools |
+| `python.host` | `revit_execute_python` / `rhino_run_python` escape hatches — expert-mode only, off by default |
+
+No permission → tool call rejected with a structured error naming the missing grant.
+
+## 5. I/O schema, validation & logging hooks
+
+- **Schemas:** JSON Schema per command (inline or `schemas/*.json`). Hub validates input before dispatch and output before return — a module that returns off-schema fails loudly in CI (contract test iterates all modules, same pattern as `test_provider_contract.py`).
+- **`validate` hook:** runs at plan time — semantic checks beyond schema (e.g. "sheet numbers unique"). Returns `ok | warnings[] | blockers[]`; blockers stop the plan before approval.
+- **`on_result` hook:** post-execution — audit summary lines, issue-store updates, notifications. Hooks are sync, budgeted (fail-open with logged warning on timeout).
+
+## 6. Rollback strategy
+
+Modules never implement rollback themselves. They declare per command:
+
+- `reversible: "undo"` — single named transaction; Revit undo suffices (default).
+- `reversible: "inverse"` — module's `build_inverse(plan, before_state)` produces a counter-plan (e.g. parameter restore).
+- `reversible: "none"` — irreversible (file exports are trivially none; model deletes need `model.delete` + explicit confirm).
+
+The approval gate persists `before_state` captured at plan time for inverse-capable commands.
+
+## 7. Versioning
+
+- Module semver + `schema_version` (manifest format) + `min_hub_version` gate.
+- Hub refuses to load incompatible modules with a clear panel message, never a crash.
+- Command input schemas are append-only within a major version (add optional fields only) — same discipline as switch Contract v2 (ADR 0002).
+
+## 8. Example modules (target roster)
+
+| id | Tier | Composes | New host primitives needed |
+|---|---|---|---|
+| `model_inspector` | MVP | snapshot query, `revit_list_*`, `revit_get_element_*` | `revit.extract_snapshot` (C#) |
+| `selection_tools` | MVP | `revit_get/set_selection`, filters, save/restore selections | — |
+| `parameter_manager` | MVP | `revit_batch_set_parameters*`, diff grid, CSV roundtrip | — |
+| `qaqc_checker` | MVP | rules → findings → issue store → fix plans | — |
+| `report_generator` | MVP | `exporter_*`, `export_excel`, templates | — |
+| `viewsheet_automator` | MVP | 10 existing sheet/view tools | — |
+| `familytype_mapper` | P1 | family audit, `revit_replace_family_type` mapping tables | family metadata extraction |
+| `facade_configurator` | P1 | zone spec → placement plans, variant mgmt | adaptive-component batch placement |
+| `rhino_bridge` | P1 | 19 `rhino_*` tools, spec import | — |
+| `speckle_ifc_bridge` | P1 | `speckle_*`, `ifc_*`, mapper | — |
+| `data_exporter` | P1 | SQLite/Excel/Parquet lanes | — |
+| `agent_reviewer` | P2 | second-model review of pending ActionPlans (flags risky plans before human sees them) | — |
+
+## 9. QA rule format (used by `qaqc_checker`)
+
+```yaml
+# rules/core/rooms.yaml
+- id: room.unplaced
+ title: Unplaced rooms
+ severity: warning # info | warning | error
+ category: Rooms
+ query: { source: snapshot, filter: { category: "OST_Rooms", placed: false } }
+ message: "{count} unplaced room(s)"
+ fix: null # or a command ref: { command: "qaqc.apply_fixes", args_template: {...} }
+
+- id: door.no_fire_rating
+ title: Doors missing fire rating
+ severity: error
+ category: Doors
+ query:
+ source: snapshot
+ filter: { category: "OST_Doors", parameter: { name: "FireRating", empty: true } }
+ fix:
+ command: parameter_manager.batch_set
+ args_template: { parameter: "FireRating", value_prompt: true }
+```
+
+Rule packs are versioned directories (`core`, firm packs under user modules dir); a rule that fails to evaluate is reported as `rule_error`, never crashes the run (cf. W7 failure cases).
diff --git a/docs/product/SCAFFOLDING_TASK_LIST.md b/docs/product/SCAFFOLDING_TASK_LIST.md
new file mode 100644
index 0000000..b6fbaad
--- /dev/null
+++ b/docs/product/SCAFFOLDING_TASK_LIST.md
@@ -0,0 +1,204 @@
+# Scaffolding Task List
+
+Buildable backlog for the agent swarm (roster + rules in `AI_AGENT_SWARM_PLAN.md`). Every phase carries: Epic · Subtasks · Owner · Files · Notes (technical / Revit-BIM concepts / integration points) · Tests · Acceptance / DoD · Dependencies · Risks. Task IDs `P<phase>.<n>`. MVP = Phases 0–10 + 16–19 subset (see `MVP_EXECUTION_PLAN.md`).
+
+Global DoD (applies to every phase): builds green (pytest+ruff; `dotnet build` net48+net8), no broken doc links, `tools-generated.md` regenerated if the tool surface changed, handover block written, human sign-off on the phase.
+
+---
+
+## Phase 0 — Repository audit & documentation consolidation
+**Epic:** make the repo tell one true story before building on it. **Owner:** Documentation + Repo Audit + Release. **Deps:** none — start immediately.
+- P0.1 Present audit §9 deletion list to Sam; on approval remove stray binaries (`docs/Untitled*.3dm*`, `Omni_LiveGeometryStats.csv`), untrack `dist/`, caches, empty `metrics/`; extend `.gitignore`. ⚠ human approval; consider `git rm --cached` vs history rewrite (92 MB files — recommend BFG later, separate decision).
+- P0.2 Move `docs/ecosystem-strategy-and-monetization.md` to private repo; leave stub pointer. ⚠ human approval.
+- P0.3 Fix `CLAUDE.md`: Navisworks port 3005→3002, replace dead `docs/agent-task-plan.md` pointer with `docs/product/SCAFFOLDING_TASK_LIST.md`, retitle to AEC Model Bridge.
+- P0.4 Fix README broken links (`docs/tools.md`, `docs/architecture.md`, `docs/integration-expansion-handover.md`) → real targets; correct Rhino transport description (HTTP :3004, not SSE :9876); mark Navisworks/PowerBI "in progress" honestly.
+- P0.5 Rewrite `docs/security.md` against as-built (provider system, ADR 0002, no phantom config keys). Flip ADR 0001 status Proposed→Accepted.
+- P0.6 Version reconciliation: bump `pyproject.toml`, `RevitBridge.csproj`, `server.json` to match CHANGELOG 1.2.0 (or re-cut CHANGELOG; Release agent proposes).
+- **Tests:** link checker over docs; grep for "3005", "agent-task-plan", "Omni-Bridge" (outside legacy-note contexts) returns nothing.
+- **Acceptance/DoD:** fresh reader gets zero contradictions between README, CLAUDE.md, docs/, and code. **Risk:** deleting something Sam wanted (mitigated: list-first rule).
+
+## Phase 1 — Product definition
+**Epic:** lock the product package. **Owner:** Product Architect. **Deps:** P0 readable repo.
+- P1.1 Review `docs/product/*` (this package) with Sam; resolve open questions in `DECISIONS_AND_RISKS.md`.
+- P1.2 Reconcile `docs/roadmap-and-plans.md` with this package (roadmap = strategy narrative; this = buildable plan; add cross-links, delete duplicated phase tables from roadmap).
+- P1.3 Update README positioning to the vision doc's one-liner.
+- **Acceptance:** Sam signs decisions D-001…D-012; no competing roadmaps. **Risk:** scope re-litigating — timebox.
+
+## Phase 2 — Plugin-style app architecture
+**Epic:** freeze contracts so waves can parallelize. **Owner:** Product Architect + MCP Tooling + Revit API. **Deps:** P1.
+- P2.1 ADR-0008: approval gate + ActionPlan lifecycle (states: draft→validated→pending→approved/rejected→executed→rolled-back).
+- P2.2 ADR-0009: module system (manifest schema v1 frozen from `PLUGIN_MODULE_SYSTEM.md` §2).
+- P2.3 ADR-0010: snapshot schema v1 frozen from `SEMANTIC_BIM_DATA_MODEL.md` §2.
+- P2.4 ADR-0011: panel architecture (WebView2, message bridge, hub endpoints the panel calls).
+- **Acceptance:** four ADRs Accepted; contract-freeze points from swarm plan in force. **Risk:** over-designing before contact with Revit reality — ADRs stay ≤2 pages each.
+
+## Phase 3 — Revit-native foundation
+**Epic:** the C# add-in becomes a safe, modern substrate. **Owner:** Revit API (+ Security/Safety review). **Files:** `packages/revit-bridge-addin/src/**`. **Deps:** P2.
+- P3.1 Flip Contract v2 to default (LegacyMode opt-in via `MCP_REVIT_LEGACY_PORT=true`); hub discovery via registry files already exists — verify end-to-end. ⚠ human approval (breaks old setups).
+- P3.2 Transaction discipline: audit all 110 handlers in `BridgeCommandFactory.cs`; enforce named `Transaction`/`TransactionGroup` pattern (`"AMB: <cmd> #<action_id>"`); thread `action_id` through `/execute` payload.
+- P3.3 New command `revit.extract_snapshot` (full + `dirty_only` incremental using the existing `DocumentChanged` hook) emitting ElementRecords per schema; streams to workspace file, returns path + counts (never inline 50k elements).
+- P3.4 New command `revit.get_snapshot_delta` (dirty-list since snapshot_id).
+- P3.5 Dead-tree resolution: per-subsystem verdict on `src/Commands/**` (revive as `[BridgeCommand]`s or delete). ⚠ human approval on deletes.
+- **Revit concepts:** FilteredElementCollector perf, ElementMulticategoryFilter, UniqueId vs ElementId, DocumentChanged, workshared ownership. **Integration:** feeds Phase 6.
+- **Tests:** e2e snapshot on canonical model (Phase 17 model, early script version); handler transaction-name audit is a unit test over reflection metadata.
+- **Acceptance/DoD:** snapshot of 10k-element model < 30 s full / < 2 s incremental (ADR 0007 spirit); v2 auth on by default; all handlers carry named transactions. **Risks:** perf on huge models (mitigate: parallel param reads are NOT thread-safe — single-thread extraction, measure first); regressions across net48/net8 (CI matrix).
+
+## Phase 4 — MCP tool foundation
+**Epic:** one hub, honest metadata, approval gate. **Owner:** MCP Tooling (+ Security/Safety). **Files:** `packages/mcp-server-revit/src/revit_mcp_server/**`. **Deps:** P2 (can start parallel to P3).
+- P4.1 Extend `ProviderTool` with `is_mutating/destructive/execution_mode/permissions`; backfill all ~170 tools (mirror C# `[BridgeCommand]` attrs via `/capabilities`).
+- P4.2 Approval gate: `plan_actions`, `list_pending_plans`, `approve_plan`, `reject_plan`, `rollback_plan` tools + `ApprovalGate` middleware rejecting un-planned mutating calls when `approval_mode=required`; persist plans + before-state in workspace.
+- P4.3 Register `NavisworksProvider` in `mcp_server.py`; widen to the 16 C# commands.
+- P4.4 Retire legacy: migrate tests off `server.py` + `tools/` + old `schemas.py`, then archive. ⚠ human approval. Fix or delete the `proxy._connect()` bug with it.
+- P4.5 Wire or park `PowerBIProvider` (decision D-009); if wired: register + health-only for now.
+- P4.6 Regenerate `docs/tools-generated.md` — no more "?" columns; document gate tools.
+- **Tests:** `test_provider_contract.py` asserts metadata on every tool; new `test_approval_gate.py` (mutating-without-plan rejected, plan lifecycle, rollback restores before-state via mock provider).
+- **Acceptance/DoD:** single server; every tool metadata-complete; gate enforced; Navisworks reachable. **Risks:** breaking existing users' tool list (additive only; renames need approval), plan-store corruption (atomic writes).
+
+## Phase 5 — Plugin module registry
+**Epic:** modules as first-class citizens. **Owner:** Plugin App. **Files:** `revit_mcp_server/modules/__init__.py`, `module_registry.py`, `ModuleProvider` adapter. **Deps:** P4.
+- P5.1 ModuleRegistry (discovery: built-in, entry points, user dir; id-collision policy; version gates).
+- P5.2 `module.json` validation (JSON Schema), permission enforcement at dispatch, validate/on_result hooks with timeout budget.
+- P5.3 `ModuleProvider` exposing module commands as MCP tools; `module_list_commands` endpoint for the panel.
+- P5.4 Hello-world module + module-author guide (`docs/module-authoring.md`).
+- **Tests:** contract test iterating all discovered modules (schema-valid manifests, schemas resolve, permissions known); hostile-manifest fixtures.
+- **Acceptance/DoD:** drop-in module dir appears as tools + panel commands with zero hub code changes. **Risk:** entry-point security (user modules run arbitrary code — document trust model; firm dir requires explicit enable).
+
+## Phase 6 — Semantic BIM data layer
+**Epic:** the snapshot/diff/reconcile engine. **Owner:** Semantic BIM Data. **Files:** `revit_mcp_server/semantic/**`, `schemas/amb.snapshot.v1.json` etc. **Deps:** P3 (extract command) + P4.
+- P6.1 Pydantic models + JSON Schemas for snapshot/delta/zone/variant (from `SEMANTIC_BIM_DATA_MODEL.md`).
+- P6.2 `snapshot_take` (calls `revit.extract_snapshot`, stores, indexes to SQLite via existing exporter), `snapshot_query` (filter DSL used by rules + W1), `snapshot_diff`.
+- P6.3 Delta reconciliation → ActionPlan (three-way conflict detection per §5).
+- P6.4 Mapper integration: every snapshot registers uids → `amb_uid`.
+- **BIM concepts:** UniqueId stability, phase/design-option filtering, workset ownership, storage types + spec units.
+- **Tests:** golden snapshot on canonical model; diff of known edit script == expected; conflict fixtures.
+- **Acceptance/DoD:** W1 questions answerable from snapshot alone; diff correct on 20-edit scenario. **Risk:** schema churn after freeze (append-only rule).
+
+## Phase 7 — Model inspection workflows (W1–W3)
+**Epic:** killer workflow #1 ships. **Owner:** Plugin App (+ QA/QC BIM for query DSL review). **Files:** `modules/model_inspector/**`, `modules/selection_tools/**` (read side). **Deps:** P5+P6.
+- P7.1 `model_inspector` module: `ask` (NL → snapshot_query via agent), `summarize_model`, `list_groups`, element chips payload (uid, label, category) for panel.
+- P7.2 Selection inspect: `inspect_selection` (W2 card: type/host/level/params/warnings).
+- P7.3 Saved queries (named, per-doc, re-runnable).
+- **Tests:** query results == Revit schedule counts on canonical model (golden numbers).
+- **Acceptance/DoD:** the W1 user story demo runs end-to-end in Claude Code (panel comes in P16). **Risk:** LLM query hallucination → `snapshot_query` DSL is the only query path; agent must emit DSL, hub validates it.
+
+## Phase 8 — Selection & model group workflows (W2 write side, W4)
+**Epic:** first gated writes. **Owner:** Plugin App. **Deps:** P7 + gate (P4).
+- P8.1 `selection_tools` write side: set/save/restore selections; select-by-query.
+- P8.2 Group ops as plans: rename/ungroup/convert (W4) with affected-instance counts in plan preview.
+- **Revit concepts:** Group/GroupType semantics, attached details, view-specific membership.
+- **Tests:** ungroup plan on canonical model → undo restores; plan preview counts == actual.
+- **Acceptance/DoD:** W4 demo with approval + rollback. **Risk:** group edge cases (nested, mirrored) — document unsupported cases explicitly rather than half-support.
+
+## Phase 9 — Parameter / family / type workflows (W5, W6)
+**Epic:** killer workflow #3. **Owner:** Plugin App + Revit API (type params edge cases). **Files:** `modules/parameter_manager/**`, `modules/familytype_mapper/**`. **Deps:** P8.
+- P9.1 `parameter_manager`: filter → diff grid → plan → apply → inverse plan (before-values). CSV import/export lane.
+- P9.2 Plan-time validation: storage type, readonly, binding, type-vs-instance, unit conversion via spec (SI internal).
+- P9.3 `familytype_mapper` read side: family audit (W6 core rules), type mapping tables (feeds W11 later).
+- **Tests:** batch-set 500 params → re-read == intended; rollback == original; workshared-owned element skip path (mock).
+- **Acceptance/DoD:** W5 user story end-to-end incl. rollback; wrong-type writes impossible (blocked at plan). **Risks:** formula/readonly params, shared-param GUID collisions.
+
+## Phase 10 — QA/QC validation workflows (W7, W9)
+**Epic:** killer workflow #2. **Owner:** QA/QC BIM. **Files:** `modules/qaqc_checker/**`, `rules/core/**`. **Deps:** P6 (+P9 for fixes).
+- P10.1 Rule engine: YAML rule packs (format in `PLUGIN_MODULE_SYSTEM.md` §9) over `snapshot_query` + `graph_*` audits + `revit_get_warnings`; rule failure = reported, never fatal.
+- P10.2 Core pack (~15 rules from W7 MVP list) with severities + fix templates.
+- P10.3 Issue store (SQLite, per doc-guid): lifecycle open→resolved(auto on re-check)→orphaned(uid miss).
+- P10.4 Async run via JobManager with progress.
+- **Tests:** seeded-defect canonical model → golden findings file byte-diffed in CI.
+- **Acceptance/DoD:** one-click health check < 2 min on canonical model; findings clickable (uid list). **Risk:** rule quality = product reputation — every core rule reviewed by Sam against real-project intuition.
+
+## Phase 11 — Façade configurator workflows (W11) — post-MVP flagship
+**Epic:** the differentiator demo. **Owner:** Rhino/Grasshopper + Semantic BIM Data + Revit API. **Files:** `modules/facade_configurator/**`, `packages/rhino-bridge-addin/**`, adaptive family templates in `fixtures/families/`. **Deps:** P6, P9; Rhino bridge exists.
+- P11.1 Zone spec exporter: GH definition + `rhino_run_python` script emitting `amb.facade_zone/1` (promote `scratch/glass_diamond.py` conventions — gpt/cc, counts_expected).
+- P11.2 `facade_apply_zone`: spec → type mapping → adaptive placement plan (batch `revit_place_family_instance` or new batched C# command if perf demands).
+- P11.3 Variant management: spec-hash variants, re-apply as diff (update/create/delete itemized).
+- P11.4 Preview lane: DirectShape with PREVIEW marker + auto-cleanup, behind explicit user opt-in.
+- **BIM concepts:** adaptive components, curtain systems, family loading, panel count reconciliation (no silent skips).
+- **Tests:** 1476-panel golden case — Rhino count == plan count == placed count == mapping rows.
+- **Acceptance/DoD:** tune-in-Rhino → approve variant → native panels in Revit → re-tune → diff-apply. **Risks:** placement perf (batch command likely needed — measure at 500 panels first), family availability UX.
+
+## Phase 12 — Rhino.Inside.Revit / Grasshopper bridge (W12, W13-GH)
+**Epic:** meet computational designers in-process. **Owner:** Rhino/Grasshopper. **Deps:** P11.
+- P12.1 GH components (`AMB Connect`, `AMB Snapshot`, `AMB Zone Out`, `AMB Plan Preview`) wrapping hub HTTP.
+- P12.2 RiR exemplar definition + supported version matrix doc.
+- P12.3 Rhino bridge hardening: Contract v2 (dynamic port + token) replacing hardcoded :3004.
+- **Tests:** exemplar runs scripted; version matrix manually checklisted per release.
+- **Acceptance/DoD:** W12 story demo; no write path bypasses gate. **Risk:** RiR/Rhino/Revit version triangle — pin and document, don't chase.
+
+## Phase 13 — Speckle / IFC / Navisworks bridge (W15)
+**Epic:** coordination loop closes. **Owner:** Integration. **Deps:** P4 (Navis registration), P6.
+- P13.1 Speckle: snapshot publish/receive (`speckle_publish_version` lane) → delta → reconciliation.
+- P13.2 IFC: Revit-vs-IFC comparison report (mapper GlobalId↔UniqueId); `ifc_validate` surfaced in qaqc pack.
+- P13.3 Navisworks: clash results → mapper → Revit selection + issue-store import; viewpoint per finding.
+- **Tests:** RVT+IFC+NWF fixture triple; mocked Speckle server (exists) + live smoke.
+- **Acceptance/DoD:** "show clash #12 in Revit" works; IFC comparison report on fixtures. **Risk:** GUID mapping fidelity across export paths — validate early with the fixture triple.
+
+## Phase 14 — Excel / Power BI / DuckDB reporting (W8, W16)
+**Epic:** management-grade outputs. **Owner:** Integration + Report Generator module (Plugin App). **Deps:** P6, P10.
+- P14.1 `export_excel` (openpyxl): elements/params/findings workbook + formatted QA summary sheet.
+- P14.2 `report_generator` module: templates, destinations (sandboxed), schedule-able via jobs.
+- P14.3 Power BI file lane: SQLite (exists) + shipped `.pbit` template; live lane per D-009 (DAX health + `powerbi_execute_dax`).
+- P14.4 Parquet mirror + DuckDB queries (P2 priority — can slip).
+- **Tests:** golden workbook diff; `.pbit` refresh smoke (manual checklist); SQLite↔Parquet row parity.
+- **Acceptance/DoD:** W8 demo: health check → Excel + PBI dashboard refresh. **Risk:** schema evolution — `schema_version` column enforced from first export.
+
+## Phase 15 — AI agent orchestration
+**Epic:** multi-step, multi-app recipes (roadmap Phase C, scoped down). **Owner:** MCP Tooling + Product Architect. **Deps:** P10, P13.
+- P15.1 Recipe format (YAML: steps = tool calls with arg templating + conditionals) + run records.
+- P15.2 `recipe_run/status/list` tools; recipes respect the gate (mutating steps produce plans).
+- P15.3 Three shipped recipes: nightly-health-check→Excel; export→clash→issue-import; snapshot→Speckle publish.
+- P15.4 `agent_reviewer` module (P2): second-model review of pending plans.
+- **Acceptance/DoD:** the three recipes run end-to-end. **Risk:** building a workflow engine — keep it linear steps + conditionals, no DAG until pulled.
+
+## Phase 16 — UI/UX & plugin command surface
+**Epic:** the product face (runs parallel from P5 behind endpoint contracts). **Owner:** UI/UX + Revit API (pane host). **Files:** `packages/revit-bridge-addin/src/UI/**`, `panel/**`. **Deps:** P2 ADR-0011; integrates against P4/P5/P7/P10 endpoints.
+- P16.1 Dockable pane host (`IDockablePaneProvider` + WebView2 + message bridge).
+- P16.2 Panel app: chat view, plan cards (approve/reject/approve-similar), findings tab, run log (audit tail), settings.
+- P16.3 Ribbon: 5 product commands (Open Panel, Health Check, Pending Actions, Reports, Settings); keep existing Connection panel.
+- P16.4 Empty/error states: hub down, no doc, stale snapshot, offline LLM.
+- **Tests:** panel↔hub contract tests (endpoint fixtures); manual UX checklist per release; WebView2 runtime absence fallback message.
+- **Acceptance/DoD:** the W7+W5 stories fully driven from the panel by a non-programmer. **Risks:** WebView2 in Revit process (memory, load order — spike first in P16.1); UI scope creep (card set is fixed for MVP).
+
+## Phase 17 — Testing & sample models
+**Epic:** trust through goldens. **Owner:** Testing (starts Wave 1 — the model script is a P3 dependency!). **Files:** `fixtures/**`, `tests/e2e/**`, `.github/workflows/**`.
+- P17.1 Canonical test model **generator script** (idempotent: builds the RVT via bridge tools — levels, 200 walls, doors/windows, rooms incl. seeded defects, views/sheets, groups, families). Script, not binary, so it's diffable and per-version buildable.
+- P17.2 Seeded-defect register (which rule catches what) → golden findings.
+- P17.3 e2e harness extending `test_e2e.py`: hub+add-in round trip, gate paths, snapshot goldens.
+- P17.4 CI: pytest+ruff; dotnet matrix net48/net8 (Nice3point NuGet); doc link check; e2e nightly on self-hosted runner with Revit (or scripted local `make e2e` if no runner). ⚠ decide runner story (D-012).
+- **Acceptance/DoD:** every MVP workflow has a golden; CI green gate on PRs. **Risk:** Revit-in-CI licensing → local scripted fallback documented.
+
+## Phase 18 — Documentation & tutorials
+**Epic:** docs a firm can adopt from. **Owner:** Documentation. **Deps:** MVP features stable.
+- P18.1 MkDocs site (roadmap Phase F): install, quickstart, workflows (one page per W#), module authoring, tool reference (generated), security model.
+- P18.2 Three tutorials: "Ask your model", "Health check + fix", "Batch parameters from Excel".
+- P18.3 Video/demo script for the flagship demo (P11).
+- **Acceptance/DoD:** cold-start user completes tutorial 1 in <15 min without help.
+
+## Phase 19 — Packaging, installer, release
+**Epic:** double-click install. **Owner:** Release (+ Security for signing). **Deps:** P16.
+- P19.1 Add-in installer (WiX/Inno): `.addin` + multi-target DLLs into per-version folders; WebView2 runtime bootstrap.
+- P19.2 Hub packaging decision D-010 (pipx vs bundled runtime) implemented; `server.json`/marketplace listings updated (`docs/marketplaces.md`).
+- P19.3 Release pipeline: tag → build matrix → DLL license scan (exists) → artifacts → CHANGELOG cut. Code-signing cert acquisition. ⚠ human: signing + publishing.
+- **Acceptance/DoD:** clean Windows machine → installer → tutorial 1 works. **Risk:** unsigned binaries = SmartScreen friction (budget for cert).
+
+## Phase 20 — Enterprise readiness
+**Epic:** what firms ask before rollout. **Owner:** Security/Safety + Release.
+- P20.1 Central config (firm-managed settings file: approval_mode lockdown, module allowlist, telemetry off switch).
+- P20.2 Audit-ledger export + retention policy; threat model doc refresh.
+- P20.3 Workshared/BIM360 model behavior matrix (ownership, sync etiquette: never `revit_sync_to_central` without explicit plan).
+- P20.4 License enforcement for commercial modules (open-core seam — mechanism only, pricing stays private).
+- **Acceptance/DoD:** enterprise checklist doc answerable "yes" line-by-line.
+
+## Phase 21 — Future roadmap
+**Epic:** parked, explicitly. **Owner:** Product Architect. Contents: remote MCP/REST facade (roadmap H), BYO-LLM guides, Dynamo package (W13-D), APS Issues at scale, MS Graph, additional switches (Archicad/Tekla — roadmap G), marketplace, IDS full support, BCF. Each graduates only via a `DECISIONS_AND_RISKS.md` entry with a pull signal (user request, revenue, demo need).
+
+---
+
+## Dependency spine
+
+```
+P0 → P1 → P2 ─┬→ P3 (C#) ──┐
+ ├→ P4 (hub) ─┼→ P5 → P6 → P7 → P8 → P9 → P10 ─┬→ P11 → P12
+ └→ P17.1 ────┘ (P16 UI parallel from P5)├→ P13 → P15
+ └→ P14
+P16+P17+P18 → P19 → P20 P21 parked
+```
diff --git a/docs/product/SEMANTIC_BIM_DATA_MODEL.md b/docs/product/SEMANTIC_BIM_DATA_MODEL.md
new file mode 100644
index 0000000..6d7905d
--- /dev/null
+++ b/docs/product/SEMANTIC_BIM_DATA_MODEL.md
@@ -0,0 +1,152 @@
+# Semantic BIM Data Model
+
+The shared data layer that W1/W7/W5 (MVP) and W11/W14 (roundtrip) all consume. Builds on the existing `IdentityMapper` (`aec_translate_id`, `aec_register_mapping`) and `SemanticGraph` provider; adds the element-level **snapshot** and **roundtrip** schemas that don't exist yet.
+
+## 1. Identity strategy
+
+- **Primary key: Revit `UniqueId`** (episode GUID + id — stable across sessions, survives central/local roundtrips). Every record, finding, mapping, and audit entry keys on it.
+- **`ElementId` is a cache, never persisted as identity** — it can change (workshared reassignments, audit ops). Stored alongside for fast API calls within a session, always re-resolvable from UniqueId.
+- **Cross-app identity** via the existing mapper: `(app, native_id) ↔ amb_uid`. Revit UniqueId, IFC GlobalId, Speckle object id, Rhino object GUID, Navisworks item GUID all register against one `amb_uid` (ULID).
+- **Document identity:** Revit `Document.CreationGUID` + `WorksharingCentralGUID` when workshared; SaveAs detection prompts re-anchor (cf. W9 failure case).
+
+## 2. Snapshot schema (JSON, one document per extraction)
+
+```json
+{
+ "schema": "amb.snapshot/1",
+ "snapshot_id": "01J...ULID",
+ "taken_at": "2026-07-08T14:02:11Z",
+ "source": {
+ "app": "revit", "app_version": "2025.2",
+ "doc_guid": "...", "central_guid": "...", "doc_title": "Tower_A.rvt",
+ "units": "SI", "phase_map": {"3": "Existing", "4": "New Construction"}
+ },
+ "elements": [ { ...ElementRecord... } ],
+ "relations": [ { ...Relation... } ],
+ "types": [ { ...TypeRecord... } ],
+ "counts": {"by_category": {"OST_Doors": 214}}
+}
+```
+
+**ElementRecord:**
+
+```json
+{
+ "uid": "revit-uniqueid-string",
+ "amb_uid": "01J...",
+ "element_id": 316221,
+ "category": "OST_Doors",
+ "class": "FamilyInstance",
+ "type_uid": "type-uniqueid",
+ "family": "Door_Single_Flush", "type_name": "0915 x 2134mm",
+ "level_uid": "…", "phase_created": 4, "phase_demolished": null,
+ "design_option": null, "workset": "Shell",
+ "group_uid": null, "host_uid": "wall-uniqueid",
+ "room_uids": {"from": "…", "to": "…"},
+ "location": {"kind": "point", "xyz": [12.4, 3.1, 0.0], "rotation": 1.5708},
+ "bbox": {"min": [..], "max": [..]},
+ "params": {
+ "Mark": {"v": "D-104", "storage": "String", "instance": true, "readonly": false},
+ "FireRating": {"v": null, "storage": "String", "instance": true, "readonly": false},
+ "Width": {"v": 0.915, "storage": "Double", "spec": "Length", "instance": false}
+ },
+ "geometry_ref": {"kind": "none|bbox|mesh_uri", "uri": null},
+ "materials": ["mat-uid-1"]
+}
+```
+
+Notes:
+- **Units: SI internally everywhere** (metres/radians), matching the Rhino bridge convention; converters at the edges only.
+- `params` carries storage type + spec + writability → plan-time validation for W5 needs no extra round-trip.
+- `geometry_ref` keeps snapshots light: geometry is *referenced* (bbox by default; mesh exported on demand to workspace files), never inlined. BIM semantics travel; dumb geometry stays home.
+
+**Relations** (edges, feeding/mirroring the existing `graph_*` provider):
+
+```json
+{"kind": "hosts", "from": "wall-uid", "to": "door-uid"}
+{"kind": "bounds", "from": "room-uid", "to": "wall-uid"}
+{"kind": "on_level", "from": "door-uid", "to": "level-uid"}
+{"kind": "in_group", "from": "elem-uid", "to": "group-uid"}
+{"kind": "opening_in", "from": "opening-uid","to": "wall-uid"}
+{"kind": "on_sheet", "from": "view-uid", "to": "sheet-uid"}
+{"kind": "references_grid", "from": "col-uid", "to": "grid-uid"}
+```
+
+Wall/opening/window/door chains are thus first-class queryable: `door —hosted_by→ wall ←opening_in— opening`, room adjacency via shared `bounds` walls.
+
+**TypeRecord:** `{uid, category, family, type_name, params{...}, family_source: "system|loadable|inplace"}` — feeds W6 family validation and W11 type mapping.
+
+## 3. Domain specifics
+
+- **Model groups:** `group_uid` on members + `GroupRecord {uid, group_type_uid, member_uids[], instance_count}`; W3/W4 read this, never raw geometry.
+- **Rooms/spaces:** placed/unplaced/unenclosed state captured at extraction (`placed: bool`, `area: m²`, `bounding: [wall_uids]`) — the W7 room rules run on snapshot alone.
+- **Levels/grids:** always extracted (cheap, universally referenced); elements carry `level_uid` + optional grid refs.
+- **Materials/layers:** `MaterialRecord {uid, name, class, appearance_hash}`; wall compound structure as ordered layer list on the TypeRecord — needed for façade/IFC comparisons.
+- **Façade zones (W11):**
+
+```json
+{
+ "schema": "amb.facade_zone/1",
+ "zone_id": "tower-a-south",
+ "host": {"kind": "loft_surface|curtain_system|mass_face", "ref": "rhino:guid|revit:uid"},
+ "grid": {"u_divs": 20, "v_divs": 36, "seam": "v0"},
+ "panels": [
+ {"pid": "A_03_17", "panel_type": "A", "corners_m": [[x,y,z],[..],[..],[..]],
+ "target_family": "AMB_GlassPanel_Adaptive", "type_map": "glass-clear",
+ "params": {"Area": 2.31}, "amb_uid": null}
+ ],
+ "counts_expected": {"A": 720, "B": 684, "bot": 36, "top": 36}
+}
+```
+
+`counts_expected` enforces the no-silent-skip rule (the 1476-panel discipline from CLAUDE.md); `amb_uid` fills on placement → re-apply becomes a diff, not a rebuild.
+
+- **Design variants:** `VariantRecord {variant_id, zone_id, spec_hash, applied_at, plan_id, element_uids[]}` — variants are compared by spec, applied as plans, and reversible as plan inverses.
+
+## 4. Change tracking
+
+- Snapshots are immutable, ULID-ordered. `snapshot_diff(a, b)` → `{added[], removed[], modified[{uid, param_changes{...}, moved: bool}]}`.
+- The add-in already hooks `DocumentChanged` — extend it to append touched ElementIds to a session dirty-list, so incremental snapshot refresh extracts only dirty elements (big-model performance, ADR 0007 budgets).
+- Audit ledger entries reference `snapshot_id` at plan time → every approved change is anchored to what the user actually saw.
+
+## 5. Roundtrip format (W14)
+
+A **delta document** — the only thing external tools (GH, Excel, Speckle apps) send back:
+
+```json
+{
+ "schema": "amb.delta/1",
+ "base_snapshot": "01J...",
+ "actions": [
+ {"op": "update", "uid": "door-uid", "set": {"FireRating": "60"}},
+ {"op": "create", "temp_id": "t1", "class": "FamilyInstance",
+ "family": "AMB_GlassPanel_Adaptive", "type_name": "glass-clear",
+ "placement": {"kind": "adaptive_points", "points_m": [[..],[..],[..],[..]]},
+ "set": {"Mark": "P-0317"}},
+ {"op": "delete", "uid": "old-panel-uid", "reason": "variant re-apply"}
+ ]
+}
+```
+
+Reconciliation (hub): resolve uids against **live** model → three-way check vs `base_snapshot` (conflict = live changed since base → flag, never overwrite) → produce ActionPlan → approval gate → apply → register created `temp_id → UniqueId` mappings.
+
+## 6. What is needed to recreate native Revit elements
+
+Per creatable class, the delta must carry (validated at plan time, blocked with hints if missing):
+
+| Class | Required |
+|---|---|
+| Wall | level_uid, wall type (or type_map), location curve (m), height/top constraint, structural flag |
+| FamilyInstance (hosted) | family+type loadable in doc, host_uid, placement point/face ref, level_uid |
+| FamilyInstance (adaptive) | family+type, N adaptive points in order |
+| Floor/Roof | level_uid, type, boundary loops (m), slope data |
+| Room | level_uid, phase, location point (placed) — geometry comes from bounding walls |
+| Sheet/View | titleblock type / view template uid, number+name (uniqueness pre-checked) |
+| Group instance | group_type_uid, insertion point |
+
+Type-mapping tables (`familytype_mapper` module) translate external names → loaded Revit types; unresolvable mappings are plan blockers, **never** DirectShape fallbacks unless the user explicitly opts in (`fallback: "directshape_preview"`).
+
+## 7. Storage
+
+- Snapshots/deltas: JSON (gzip) in workspace `snapshots/`; latest also mirrored to SQLite via existing `exporter_to_sqlite` schema for SQL querying (one schema, documented, `schema_version` column).
+- Mappings: existing mapper store. Issues: `issues.sqlite` (W9). Audit: JSONL ledger (architecture §5).