Open-source Revit MCP server: let Claude and other AI assistants read and edit BIM models, with human approval on every change.
Python aecai-agentsautodeskautomationbimclaudeifcmcpmcp-servermodel-context-protocolnavisworksrevitrevit-addinrevit-apirhino
docs: consolidate roadmap and remove obsolete task files
A. Sam Mohammad8a6da9dc63e3
diff --git a/AGENT-TASK-A1.md b/AGENT-TASK-A1.mddeleted file mode 100644index e9c8231..0000000--- a/AGENT-TASK-A1.md+++ /dev/null@@ -1,43 +0,0 @@-# Build Task A1 — Consolidate Speckle to a single provider--You are an autonomous implementation agent for AEC Model Bridge, working in an isolated git worktree on branch `task/A1-speckle`. Complete ONLY task A1, then stop.--## Read first-- `docs/agent-task-plan.md` (card A1) and `docs/system-blueprint-and-workflows.md` §0 + §9 item 1-- `packages/mcp-server-revit/src/revit_mcp_server/providers/speckle.py` (orphaned legacy provider, 2 tools, unregistered)-- `packages/mcp-server-revit/src/revit_mcp_server/providers/cloud.py` (registered SpeckleProvider: OAuth PKCE + GraphQL, 14 tools)-- `packages/mcp-server-revit/src/revit_mcp_server/mcp_server.py`, `tests/test_cloud_providers.py`--## Standing rules (binding)-1. Back-compat: existing `revit_*` tool names, `revit.*` routes, `MCP_REVIT_*` env vars keep working.-2. Mock-first: all tests must pass offline without licensed software; network calls mocked.-3. No secrets/tokens in code, test fixtures, results, or logs.-4. Touch only files this task needs. NEVER edit `docs/agent-task-plan.md` or `AGENT-TASK.md`.-5. Finish with ONE commit on the current branch, message starting `A1: `. Use targeted `git add <paths>` (never `git add -A`). Do not push.--## Environment setup-From repo root:-```-python -m venv packages/mcp-server-revit/.venv-packages/mcp-server-revit/.venv/Scripts/python -m pip install -e "packages/mcp-server-revit[dev]"-```-If `ifcopenshell` has no wheel for this Python, list versions with `py -0p` and recreate the venv with `py -3.12` or `py -3.11`.--## The task-1. Port the uniquely useful behavior from `providers/speckle.py` into the `SpeckleProvider` in `cloud.py`: a zero-OAuth fast path using Speckle Manager local credentials (`specklepy` `get_default_account()`), exposed as new tools `speckle_send_object` and `speckle_receive_object`. If no local account exists, raise a typed error with a clear message (do not return error strings as results).-2. Fix the legacy bug: model *name* must not be passed where a model **ID** is required — resolve name → ID via a models query first (mockable).-3. `speckle_receive_object` must deserialize and return actual object data (not just `get_member_names()`).-4. Replace any error-string-as-success returns with raised typed exceptions consistent with `errors.py` patterns.-5. Delete `providers/speckle.py`; clean up any imports/references (`__init__.py`, tests).-6. Tests (mocked, offline): name→ID resolution; send path; receive deserialization; no-local-account error path. Extend redaction coverage if any new fields could carry tokens.--If the card's description contradicts what you find in the code, follow reality and note the discrepancy in your final summary.--## Verify (must pass before committing)-```-packages/mcp-server-revit/.venv/Scripts/python -m pytest packages/mcp-server-revit/tests -k "speckle or cloud"-packages/mcp-server-revit/.venv/Scripts/python -m pytest packages/mcp-server-revit/tests-```--## Deliverable-Final message: files changed, test counts (passed/failed), discrepancies found, anything deliberately left out of scope.diff --git a/AGENT-TASK-A3.md b/AGENT-TASK-A3.mddeleted file mode 100644index a47696a..0000000--- a/AGENT-TASK-A3.md+++ /dev/null@@ -1,41 +0,0 @@-# Build Task A3 — Fix McpProxyProvider connect lifecycle--You are an autonomous implementation agent for AEC Model Bridge, working in an isolated git worktree on branch `task/A3-proxy`. Complete ONLY task A3, then stop.--## Read first-- `docs/agent-task-plan.md` (card A3) and `docs/system-blueprint-and-workflows.md` §0 + §9 item 2-- `packages/mcp-server-revit/src/revit_mcp_server/providers/proxy.py` — known defect: `_connect()` exists but is never called, so `_connected` stays `False` and every `execute_tool` raises `RuntimeError("ProxyProvider not connected")`-- `providers/base.py` (AECProvider contract), existing tests for patterns--## Standing rules (binding)-1. Back-compat: existing `revit_*` tool names, `revit.*` routes, `MCP_REVIT_*` env vars keep working.-2. Mock-first: all tests pass offline; no real SSE endpoints — use a fake/in-process server or stubbed transport.-3. No secrets/tokens in code, results, or logs.-4. Touch only files this task needs. **Scope guard:** do NOT register the provider in `mcp_server.py` — that is task A4, not yours. NEVER edit `docs/agent-task-plan.md` or `AGENT-TASK.md`.-5. Finish with ONE commit on the current branch, message starting `A3: `. Targeted `git add <paths>` only. Do not push.--## Environment setup-From repo root:-```-python -m venv packages/mcp-server-revit/.venv-packages/mcp-server-revit/.venv/Scripts/python -m pip install -e "packages/mcp-server-revit[dev]"-```-If `ifcopenshell` has no wheel for this Python, list versions with `py -0p` and recreate the venv with `py -3.12` or `py -3.11`.--## The task-1. Give the provider a real connect lifecycle: an async `initialize()` (called by the owner) AND/OR lazy connect on first `execute_tool`/`get_tools` — pick the pattern most consistent with `base.py` and document the choice in the docstring.-2. Add reconnect-with-exponential-backoff (bounded retries, jittered) when the SSE session drops mid-use; a clean typed error when the target is unreachable.-3. Surface the remote server's tool list into this provider's capability manifest (names namespaced to avoid collisions, preserving remote descriptions/schemas).-4. Graceful `shutdown()`/disconnect.-5. Tests with a fake MCP/SSE server (in-process): tools listed through proxy; tool call round-trip; one disconnect→reconnect cycle; unreachable-target error path. Use the `mcp` library's test utilities if convenient, otherwise stub the transport layer.--If the card contradicts the actual code, follow reality and note the discrepancy in your final summary.--## Verify (must pass before committing)-```-packages/mcp-server-revit/.venv/Scripts/python -m pytest packages/mcp-server-revit/tests -k proxy-packages/mcp-server-revit/.venv/Scripts/python -m pytest packages/mcp-server-revit/tests-```--## Deliverable-Final message: files changed, test counts, the lifecycle pattern chosen and why, discrepancies found.diff --git a/AGENT-TASK-A5.md b/AGENT-TASK-A5.mddeleted file mode 100644index 9e5d309..0000000--- a/AGENT-TASK-A5.md+++ /dev/null@@ -1,43 +0,0 @@-# Build Task A5 — Generated tool catalog--You are an autonomous implementation agent for AEC Model Bridge, working in an isolated git worktree on branch `task/A5-catalog`. Complete ONLY task A5, then stop.--## Read first-- `docs/agent-task-plan.md` (card A5) and `docs/system-blueprint-and-workflows.md` §2 rule 3 (manifests are the single source of truth)-- `packages/mcp-server-revit/src/revit_mcp_server/mcp_server.py` (how providers are registered; optional providers may fail init and be absent)-- `providers/base.py` (`ProviderTool` shape — check which metadata fields actually exist), `providers/registry.py`-- `docs/tools.md` (legacy hand-written catalog of the original 26 revit.* tools)-- `.github/workflows/ci.yml` (python job)--## Standing rules (binding)-1. Back-compat: existing tool names and configs untouched.-2. Mock-first: the generator must run offline with no credentials — providers that fail to initialize (cloud/Rhino) are listed in the output as "not initialized in this environment" rather than crashing the generator.-3. No secrets in output. 4. Touch only files this task needs. NEVER edit `docs/agent-task-plan.md` or `AGENT-TASK.md`.-5. Finish with ONE commit on the current branch, message starting `A5: `. Targeted `git add <paths>` only. Do not push.--## Environment setup-From repo root:-```-python -m venv packages/mcp-server-revit/.venv-packages/mcp-server-revit/.venv/Scripts/python -m pip install -e "packages/mcp-server-revit[dev]"-```-If `ifcopenshell` has no wheel for this Python, list versions with `py -0p` and recreate the venv with `py -3.12` or `py -3.11`.--## The task-1. Create `packages/mcp-server-revit/scripts/generate_tool_docs.py`: builds the provider registry the same way `mcp_server.py` does (mock mode, no credentials), introspects every registered provider, and writes `docs/tools-generated.md` — one section per provider with a table: tool name, description (first sentence), mutating? (emit `?` if the metadata field does not exist yet — note this in the file header), sync/async if known.-2. Output must be deterministic (stable sort) so reruns are byte-identical — this enables the CI drift check.-3. CI: in `.github/workflows/ci.yml` python job, add a step that runs the generator then `git diff --exit-code docs/tools-generated.md` (fails CI if the catalog drifted from code).-4. Add a short banner at the top of `docs/tools.md`: legacy document covering the original 26 tools; the complete generated catalog lives in `docs/tools-generated.md`.-5. Commit the generated `docs/tools-generated.md` (it should list all providers/tools available in a clean offline environment — expect roughly 7 providers and 120+ tools; cloud ones may be absent).--If `ProviderTool` lacks fields the card assumes, follow reality, degrade the column gracefully, and note the discrepancy in your final summary.--## Verify (must pass before committing)-```-packages/mcp-server-revit/.venv/Scripts/python packages/mcp-server-revit/scripts/generate_tool_docs.py-git diff --exit-code docs/tools-generated.md (run generator twice; second run produces no diff)-packages/mcp-server-revit/.venv/Scripts/python -m pytest packages/mcp-server-revit/tests-```--## Deliverable-Final message: files changed, provider/tool counts in the generated catalog, test counts, discrepancies found.diff --git a/AGENT-TASK-A8.md b/AGENT-TASK-A8.mddeleted file mode 100644index c5fec3f..0000000--- a/AGENT-TASK-A8.md+++ /dev/null@@ -1,43 +0,0 @@-# Build Task A8 — Parameterized provider contract tests--You are an autonomous implementation agent for AEC Model Bridge, working in an isolated git worktree on branch `task/A8-contract-tests`. Complete ONLY task A8, then stop.--## Read first-- `docs/agent-task-plan.md` (card A8) and `docs/system-blueprint-and-workflows.md` §10 standing practices-- `packages/mcp-server-revit/src/revit_mcp_server/providers/fake.py` and `providers/base.py` (the contract surface)-- `providers/registry.py`, `mcp_server.py` (which providers register in a clean offline env)-- `security/audit.py` (`redact_data`), existing `tests/test_providers.py` for fixtures/patterns--## Standing rules (binding)-1. Back-compat: production code changes only if a provider genuinely violates the contract — if so, fix minimally and flag it prominently in your summary.-2. Mock-first: the suite must pass offline with no credentials. Parameterize over providers that register in a clean environment (Revit mock, IFC, mapper, exporter, jobs, graph, fake; skip cloud/Rhino/proxy gracefully when their init prerequisites are absent — use pytest skip with reason, not silent omission).-3. No secrets in fixtures. 4. Touch only files this task needs. NEVER edit `docs/agent-task-plan.md` or `AGENT-TASK.md`.-5. Finish with ONE commit on the current branch, message starting `A8: `. Targeted `git add <paths>` only. Do not push.--## Environment setup-From repo root:-```-python -m venv packages/mcp-server-revit/.venv-packages/mcp-server-revit/.venv/Scripts/python -m pip install -e "packages/mcp-server-revit[dev]"-```-If `ifcopenshell` has no wheel for this Python, list versions with `py -0p` and recreate the venv with `py -3.12` or `py -3.11`.--## The task-Create `packages/mcp-server-revit/tests/test_provider_contract.py` — ONE suite parameterized over every registrable provider, asserting for each:-1. `identity` is a stable, non-empty string, unique across the registry.-2. The tool list is non-empty; tool names are unique globally (across all providers); every tool has a non-empty description.-3. Input schema: where the tool metadata carries a schema, it is valid JSON-schema-shaped (dict with `type` or `properties`); where the field doesn't exist, record that as an xfail/note rather than failing (follow reality).-4. Calling an unknown tool name raises a typed error (not a bare Exception or a string result).-5. Redaction: a synthetic result containing a fake bearer token, a Windows path, and a POSIX path passes through `redact_data` with all three redacted — run per provider result envelope shape.-6. Mutating-flag presence: assert the metadata field exists where defined; emit a single consolidated report (in test output) of providers/tools missing mutation metadata — informational, not failing (it becomes input for later manifest work).--If the contract in `base.py` differs from what the card assumes, follow reality and note the discrepancy in your final summary.--## Verify (must pass before committing)-```-packages/mcp-server-revit/.venv/Scripts/python -m pytest packages/mcp-server-revit/tests -k contract -v-packages/mcp-server-revit/.venv/Scripts/python -m pytest packages/mcp-server-revit/tests-```--## Deliverable-Final message: files changed, how many providers the suite parameterizes over (and which were skipped + why), test counts, any contract violations found in production code and how you handled them.diff --git a/AGENT.md b/AGENT.mddeleted file mode 100644index 586c365..0000000--- a/AGENT.md+++ /dev/null@@ -1,28 +0,0 @@-# AGENT.md — Accumulated Agent Learnings--Working notes written by agents for future agents. Append dated bullets under Learnings (newest first). Keep entries to one or two lines; this file is read at the start of every loop iteration.--## How to build and test--- Python hub tests: `python -m pytest packages/mcp-server-revit/tests`-- Dev install: `pip install -e packages/mcp-server-revit[dev]`-- Add-in build: `.\scripts\build-addin.ps1 -RevitVersion <2024|2025|2026|2027> -Configuration Release`-- Tool catalog regen (CI drift-checks this): `python packages/mcp-server-revit/scripts/generate_tool_docs.py`-- Backlog + rules: `docs/agent-task-plan.md` · Architecture: `docs/system-blueprint-and-workflows.md`--## Standing gotchas--- Scripts must be PowerShell 5.1 compatible: no `&&`, no ternary, no `?.`.-- Mock-first: CI must pass with no Revit/Navisworks installed; live tests only behind `AEC_LIVE_TESTS=1`.-- Secrets/tokens never appear in tool args, results, logs, or commits — extend `security/audit.py` redaction tests for anything new.-- Existing `revit_*` tool names, `revit.*` routes, and `MCP_REVIT_*` env vars must keep working (back-compat regression = failed task).--## Learnings--- 2026-06-13 · Navisworks 2026 API changes from earlier versions: `DocumentSavedViewpoints.ToGroupItem()` → `.RootItem`; `DocumentCurrentViewpoint.ToSavedItem()` → `doc.SavedViewpoints.CaptureRuntimeOverrides()`; `ClashResult.Selection1/2` is `ModelItemCollection` — use `.Item1/.Item2` (single `ModelItem`) instead; iterate `TestsData.Tests` as `SavedItem` and cast to `ClashTest` to access `TestType`/`Status`.-- 2026-06-13 · `BridgeCommandFactory` static constructor in Navisworks addin had a missing closing brace — all methods inside appeared to be inside the constructor, causing CS1513. Fix: ensure the constructor body closes before `CreateHandlerDelegate`.-- 2026-06-13 · When C# code uses `BridgeCommandAttribute`-based reflection discovery, every command class (e.g. `ClashCommands`) must be explicitly listed in the `types[]` array in the static constructor — it does NOT auto-discover subclasses.-- 2026-06-13 · Blueprint §3.2 result envelope (`ok`/`data`) differs from the legacy Revit bridge envelope (`Status`/`Result`). `BridgeClient.call_tool()` now handles both via `if "ok" in response` branching — backward-compat for Revit, correct for Navisworks.-- 2026-06-13 · When adding custom pytest markers (e.g. `@pytest.mark.perf`), register them in `pyproject.toml` under `[tool.pytest.ini_options]` `markers` to avoid warnings.-- 2026-06-13 · If a card's instructions contradict reality (e.g., requested files already deleted), follow reality, note the discrepancy in the evidence line, and proceed.-- 2026-06-13 · File seeded during the Chapter 2 roadmap session (`docs/next-chapter.md`). Agents: append discoveries above this line.diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 0cadd88..32fc7cf 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,17 @@# Changelog+## 1.2.0 - 2026-06-13++- Implement Phase B Switch Contract v2 with ADR 0002 specification.+- Add hub discovery registry reader and bearer-token client with legacy fallback.+- Enhance Revit add-in with Contract v2 runtime, token generation, and capability manifest generation via reflection.+- Introduce Navisworks command routing infrastructure with attribute-based registry.+- Establish baseline hub performance posture with ADR 0007.+- Add parameterized provider contract tests and automated tool catalog generation.+- Implement SQLiteExporterProvider for local database exports and graph mapping.+- Add multi-provider integration, persistent background event loop, and data redaction.+- Perform repository hygiene by removing obsolete agent task files and temporary branches.+## 1.1.0 - 2026-06-11- Rewrite the README as a shorter product and installation guide.diff --git a/PROMPT.md b/PROMPT.mddeleted file mode 100644index a75debc..0000000--- a/PROMPT.md+++ /dev/null@@ -1,23 +0,0 @@-# Ralph Loop Prompt — AEC Omni-Bridge--You are an implementation agent running one iteration of an unattended loop. You get a fresh context every run; all memory lives on disk (this repo, `docs/agent-task-plan.md`, `AGENT.md`, git history). Do exactly one task card, then stop.--## The loop--1. Read `docs/agent-task-plan.md` (the backlog) and `AGENT.md` (accumulated learnings). Read the `docs/system-blueprint-and-workflows.md` sections the card you select references.-2. Select ONE card: the first `[ ]` task in the earliest active phase whose "Depends on" tasks are all `[x]`. Skip `[H]` (human-only) and `[B]` (blocked) cards.-3. Before writing anything: **search the codebase first.** Never assume something is missing or broken until you have looked. If the card's instructions contradict reality, follow reality and note the discrepancy in your evidence line.-4. Implement the card fully: real code, the tests the card demands, and make the card's **Verify** command(s) pass. Run the relevant test suite for whatever you touched.-5. Update the card's marker: `[x]` + today's date + one evidence line (test summary or commit hash). If you could not finish, mark `[~]` or `[B]` with a one-line reason. Append one line to the Progress Log (section 5 of the task plan).-6. Append any non-obvious learning (build quirk, API gotcha, flaky test, naming trap) as a dated bullet to `AGENT.md` so future iterations don't rediscover it.-7. Commit with message `<task-id>: <summary>` on branch `task/<task-id>`. Never commit to `main`.-8. Obey every Standing Rule in `docs/agent-task-plan.md` §2 (back-compat is sacred; mock-first; no vendor binaries; no secrets in logs/results; manifests over hand-written catalogs; PowerShell 5.1 syntax in scripts; conventional commits).-9. STOP. One card per run.--## Hard bans--- No placeholder, stub, or "TODO: implement later" code — a card is done or it is `[~]`.-- Never comment out, delete, or skip a failing test to make the suite pass — fix the cause or mark the card `[B]`.-- Do not touch files outside the card's surface (its Lane territory + the files it names).-- Do not "improve" unrelated code you happen to read.-- Do not start a second card, even if the first finished quickly.diff --git a/docs/agent-task-plan.md b/docs/agent-task-plan.mddeleted file mode 100644index ac9c0ab..0000000--- a/docs/agent-task-plan.md+++ /dev/null@@ -1,627 +0,0 @@-# AEC Omni-Bridge — Agent Task Plan (Master Scaffolding Backlog)--**Status:** Living execution backlog (v1.1, 2026-06-13)-**Companion docs:** `docs/system-blueprint-and-workflows.md` (the architecture — canonical), `docs/agent-handover-prompt.md` (dispatch context), ADR 0001.-**Purpose:** Decompose the road from the current verified state (blueprint §0) to the **Ultimate State** (§1 below) into small, independently verifiable tasks that can be delegated to coding agents one at a time (Ralph-style loop) or in parallel lanes (GSD-style dispatch).-------## 0. How to Use This Document--### Task states-Every task title starts with a state marker. Agents must update it when they finish:--- `[ ]` — open, may be picked up if all dependencies are `[x]`-- `[~]` — in progress (add agent/branch name)-- `[x]` — done (append: date · evidence, e.g. test command output summary or commit hash)-- `[B]` — blocked (append one line: exactly what is missing; never guess past a blocker)-- `[H]` — requires the human (license purchase, vendor account, legal review, store submission)--### Dispatch mode 1 — Ralph loop (one agent, one task per iteration)-Paste this prompt to the agent (or into the loop runner) verbatim:--```text-You are an implementation agent for AEC Model Bridge.-1. Read docs/agent-task-plan.md. Read docs/system-blueprint-and-workflows.md- sections referenced by the task you select.-2. Select the FIRST task in the earliest active phase whose marker is [ ] and- whose "Depends on" tasks are all [x]. Skip [H] tasks — those are human-only.-3. Complete that ONE task fully: implement, write the tests the card demands,- run the Verify command(s), and make them pass.-4. Update the task marker in docs/agent-task-plan.md to [x] with today's date- and one evidence line. If you could not finish, mark [~] or [B] with a- one-line reason.-5. Commit with message "<task-id>: <summary>" on a branch named task/<task-id>.-6. Obey every Standing Rule in section 2. Then STOP. One task per run.-```--### Dispatch mode 2 — GSD parallel lanes (multiple agents, worktrees)-Tasks are tagged with a **Lane**. Tasks in different lanes touch disjoint files and may run in parallel worktrees safely. Tasks in the same lane run sequentially. Map to your GSD planning: Phase = goal, Epic = project, task card = next-action (each card carries its own context and done-definition, so it is dispatchable without extra briefing).--| Lane | Territory | Typical agent |-| --- | --- | --- |-| **PY** | `packages/mcp-server-revit/**` (Python hub) | Python-capable agent |-| **NET** | `packages/revit-bridge-addin/**`, `packages/navisworks-bridge-addin/**`, future C#/Java switches | .NET-capable agent on Windows |-| **DOCS** | `docs/**`, `README.md`, docs site | Any agent |-| **DATA** | Power BI templates, lakehouse layout, sample assets | BI-capable agent or human |-| **HUMAN** | Legal, vendor accounts, store submissions, live licensed-software runs | You |--### Sizing-**S** ≤ ~2 h of agent work · **M** ≤ ~1 day · **L** = multi-day (cards marked L should usually be split further by the agent before starting — splitting is allowed, deleting scope is not).-------## 1. Definition of the Ultimate State (what "done" means for the whole program)--The program is complete when ALL of the following are true:--1. **Switches** (each independently installable, Contract v2 compliant — blueprint §3):- Revit ✦ Navisworks ✦ Rhino (proxy + optional native plugin) ✦ Solibri ✦ Excel (headless + Graph) ✦ Speckle ✦ ACC/Forma — live; Archicad/Tekla/SketchUp/iTwin/Trimble/Procore/P6 have decision-ready specs (Phase G).-2. **Orchestrator:** declarative recipe engine with fallbacks, confirmation gates, idempotency, progress notifications; flagship recipes W1–W5 pass mock-mode e2e in CI and have recorded live-run evidence.-3. **Provenance:** every run emits a versioned Run Record (blueprint §5.2); identity map persisted per workspace.-4. **Data plane:** Speckle commits + local Parquet/DuckDB lakehouse; two published `.pbit` Power BI templates work against the Run Record schema.-5. **Security:** per-session tokens, dynamic ports, discovery registry, policy layer (allow-list, destructive gates), redaction tests for every provider.-6. **Distribution:** per-switch release packages with checksums, docs site with generated tool catalog, zero-switch IFC demo as the first-run tutorial.-7. **No doc describes anything that does not exist.** (The §0 baseline discipline, permanent.)-8. **Any-AI access (Chapter 2):** the hub is drivable from whatever AI the user already has — MCP stdio, remote MCP (Streamable HTTP) with per-key auth, a REST/OpenAPI facade, and a bundled bring-your-own-LLM console (incl. fully offline via Ollama); a non-developer installs and connects in ≤10 minutes.-9. **Neutral-layer bridges (Chapter 2):** BCF in/out (clash → issues any tool can open), IFC→glTF shareable web viewer, model digest for LLMs, Archicad (Tapir), Grasshopper definition runner, drop-folder automation — the coordination layer no vendor builds across competitors' tools.-------## 2. Standing Rules (binding on every agent, every task)--1. **Back-compat is sacred:** existing `revit_*` MCP tool names, `revit.*` bridge routes, and `MCP_REVIT_*` env vars keep working. Regression = failed task.-2. **Mock-first:** every feature must be testable in CI without licensed software. Live tests go behind explicit env flags (`AEC_LIVE_TESTS=1`) and are excluded from default pytest runs.-3. **No vendor SDK binaries in the repo.** Reference assemblies installed with the host product (as the Revit/Navisworks csproj files already do).-4. **Secrets and tokens never appear** in tool args, results, logs, code, or commits. Extend `security/audit.py` redaction tests for anything new.-5. **Manifests over hand-written catalogs:** new tools must be described by capability manifests; docs are generated (task A5).-6. **One ADR per architectural decision**, numbered sequentially in `docs/`, amending — never silently contradicting — the blueprint.-7. **Verify before done:** the card's Verify command(s) must pass. Paste a one-line result summary as evidence. Python tests: `python -m pytest packages/mcp-server-revit/tests`. Add-in builds: `.\scripts\build-addin.ps1 -RevitVersion <year> -Configuration Release`.-8. **PowerShell 5.1 syntax** in any scripts (no `&&`, no ternary).-9. **If a card's instructions contradict reality** (file moved, API changed), follow reality, note the discrepancy in the evidence line, and update the card text.-10. **Conventional commits**, task ID prefixed. Never commit directly to `main`.-------## 3. Switch Inventory — every connector needed for the Ultimate State--| Software | Connector type | Add-in/plugin required? | Status today | Built by tasks |-| --- | --- | --- | --- | --- |-| **Revit** | Desktop switch, C# add-in, loopback HTTP | Yes — **exists** (2024–2027) | Operational; needs Contract v2 upgrade | B4, B5 |-| **Navisworks Manage** | Desktop switch, C# add-in | Yes — **exists as stub** | `/health` only; no clash routes; no Python provider | B6–B11 |-| **Rhino/Grasshopper** | (a) SSE proxy to an existing Rhino MCP plugin; (b) Rhino.Compute provider; (c) optional own `.rhp` | (a) no — reuse; (c) yes, optional | Compute provider registered; proxy broken/unregistered | A3, A4, F8 |-| **Solibri Office** | Desktop switch via Solibri REST API (local, enabled with `--rest-api-server-port`, default 10876 — verify current docs) or Java Open API plugin; fallback: IFC-in/BCF-out file exchange | Possibly (Java plugin) — decided by spike | Not started | E8–E10 |-| **Excel (local)** | Headless switch inside hub (openpyxl) | No | Not started | E1–E3 |-| **Excel (SharePoint/OneDrive)** | Cloud provider via Microsoft Graph | No | Not started | E4 |-| **Speckle** | Cloud provider (OAuth PKCE, GraphQL) | No | Operational, needs consolidation | A1, A2 |-| **ACC / Forma (APS)** | Cloud provider (APS OAuth) | No | 12 tools exist; needs AEC Data Model + Issues | E5–E7 |-| **IFC (IfcOpenShell)** | Headless, in-hub | No | Operational | D5 extends |-| **Archicad** | Hub-side provider over Archicad's local JSON API (default port 19723 — verify) — **no add-in needed** | No | Spec only | G1 |-| **Tekla Structures** | Desktop switch, .NET local adapter | Yes | Spec only | G2 |-| **SketchUp** | Desktop switch, Ruby extension | Yes | Spec only | G3 |-| **iTwin / Trimble Connect / Procore / P6** | Cloud providers | No | Spec only | G4–G7 |-------## 4. Milestone Map--```text-PHASE A (hygiene)──► PHASE B (Contract v2 + Navisworks + policy)──► PHASE C (orchestrator + recipes)- │- PHASE F (docs site, SDK template, releases) ◄── partially parallel from A5/B1- ▼- PHASE D (data plane + Power BI)──► PHASE E (Excel, ACC, Solibri)- │- PHASE G (Wave-3 specs, anytime after C)- │- CHAPTER 2: PHASE H (any-AI access layer) ◄── after B14/C6 ─┤- PHASE I (popularity pack: BCF, viewer, digest, │- Archicad, Grasshopper, watcher) ◄──────┘-```--**Phase gates:** a phase is closed when all its non-`[H]` tasks are `[x]` and the gate check listed at the end of the phase passes.-------## PHASE A — Truth & Hygiene--> Goal: the codebase matches its documentation; known defects from blueprint §9 are fixed. Mostly Lane-PY.--#### [x] A0 — Author canonical blueprint + rewrite handover prompt-Done 2026-06-12 · `docs/system-blueprint-and-workflows.md`, `docs/agent-handover-prompt.md`, strategy doc created.--#### [~] A1 — Consolidate Speckle to a single provider *(dispatched: codex/gpt-5.4, branch task/A1-speckle, 2026-06-12)*-- **Lane:** PY · **Size:** M · **Depends on:** —-- **Context:** `providers/speckle.py` (orphaned, 2 tools), `providers/cloud.py` (registered, 14 tools), `mcp_server.py`, `tests/test_cloud_providers.py`.-- **Do:** Port anything uniquely useful from `speckle.py` (the simple `send_data` convenience using Speckle Manager's `get_default_account()` is worth keeping as a zero-OAuth fast path) into `cloud.py` as `speckle_send_object` / `speckle_receive_object`; fix the bug where model *name* is passed as `model_id` (resolve name → ID via a models query first); replace error-strings-as-results with raised typed exceptions; delete `providers/speckle.py`.-- **Done when:** one Speckle provider exists; name→ID resolution covered by a unit test; receive path deserializes data (not just member names).-- **Verify:** `python -m pytest packages/mcp-server-revit/tests -k "speckle or cloud"`--#### [ ] A2 — Fix specklepy dependency pin-- **Lane:** PY · **Size:** S · **Depends on:** A1-- **Do:** In `packages/mcp-server-revit/pyproject.toml` change `specklepy>=2.17.0` to `specklepy>=3,<4`; run the Speckle test suite against the installed 3.x; fix any API drift found.-- **Verify:** fresh `pip install -e packages/mcp-server-revit[dev]` resolves specklepy 3.x; Speckle tests pass.--#### [~] A3 — Fix McpProxyProvider connect lifecycle *(dispatched: codex/gpt-5.4, branch task/A3-proxy, 2026-06-12)*-- **Lane:** PY · **Size:** M · **Depends on:** —-- **Context:** `providers/proxy.py` — `_connect()` exists but is never called; `_connected` stays `False`; every `execute_tool` raises.-- **Do:** Add an async `initialize()` (or lazy first-call connect) that establishes the SSE session; add reconnect-with-backoff on dropped connections; surface remote tool list into the capability manifest; add unit tests with a fake SSE server.-- **Done when:** a fake MCP server's tools are callable through the proxy in tests, including one disconnect/reconnect cycle.-- **Verify:** `python -m pytest packages/mcp-server-revit/tests -k proxy`--#### [ ] A4 — Register the proxy provider + Rhino pairing config-- **Lane:** PY · **Size:** S · **Depends on:** A3-- **Do:** Register `McpProxyProvider` in `mcp_server.py` inside a try/except (absent → warning, like other optional providers); config via `MCP_PROXY_TARGETS` (e.g. `rhino=http://localhost:9876/sse`); document the pairing with an external Rhino MCP plugin in `docs/configuration-reference.md` and README (replacing the currently inaccurate `:9876` claim).-- **Verify:** proxy tools appear in `list_tools()` when a fake target is configured in tests; absent target degrades to a logged warning.--#### [~] A5 — Generated tool catalog *(dispatched: codex/gpt-5.4, branch task/A5-catalog, 2026-06-12)*-- **Lane:** PY (generator) + DOCS (output) · **Size:** M · **Depends on:** —-- **Do:** Add a script (e.g. `packages/mcp-server-revit/scripts/generate_tool_docs.py`) that introspects the provider registry and writes `docs/tools-generated.md`: one section per provider, one row per tool (name, description, mutating?, sync/async). Wire into CI as a drift check (regenerate + `git diff --exit-code`). Mark the old hand-written `docs/tools.md` as legacy with a banner pointing at the generated file.-- **Verify:** CI step passes; generated file lists all ~155 tools across 9 providers.--#### [ ] A6 — Correct stale architecture docs-- **Lane:** DOCS · **Size:** S · **Depends on:** A5-- **Do:** Fix `docs/architecture.md` ("25 tools" claim and any single-provider framing); align `docs/security.md` so unimplemented config keys are clearly marked "planned — see task B14" until B14 lands.-- **Verify:** grep for "25 tools" returns nothing; docs review.--#### [x] A7 — Repo hygiene (2026-06-13 · files already deleted, .gitignore updated, tests pass)-- **Lane:** PY · **Size:** S · **Depends on:** —-- **Do:** Delete `docs/Untitled.3dm` + `docs/Untitled.3dm.rhl`; add `.gitignore` entries for `packages/*/build/`, `packages/*/.venv/`; decide and document `dist/` policy (recommend: remove from git, attach to GitHub Releases only — record decision in `CONTRIBUTING.md`). Note: 3dm files were already missing in reality.-- **Verify:** `git status` clean after build; repo size reduced; CI green.--#### [~] A8 — Parameterized provider contract tests *(dispatched: codex/gpt-5.4, branch task/A8-contract-tests, 2026-06-12)*-- **Lane:** PY · **Size:** M · **Depends on:** —-- **Context:** `providers/fake.py` and existing `tests/test_providers.py`.-- **Do:** Build one pytest suite parameterized over every registered provider asserting the contract: identity is stable; every manifest tool has valid input schema; unknown tool → typed error; manifest `is_mutating` flags exist; results survive `redact_data` without leaking paths/tokens.-- **Verify:** `python -m pytest packages/mcp-server-revit/tests -k contract` covers ≥9 providers.--#### [H] A9 — Licensing review for non-Revit switches-- **Lane:** HUMAN · **Size:** M · **Depends on:** —-- **Do (you):** Obtain a written position on GPL linking exceptions for Navisworks (already shipped — retroactive), Rhino, Solibri, Tekla. Decide per-connector exceptions vs a generalized host-application exception. Record in `LICENSING.md` + new exception file(s).-- **Done when:** position documented; blocking ambiguity removed for E8–E10 and F5.--#### [H] A10 — Repo rename to `aec-model-bridge` (blueprint OD5)-- **Lane:** HUMAN · **Size:** S · **Depends on:** —-- **Do (you):** Rename on GitHub (auto-redirect preserves old links); update badge URLs, clone URLs, MCP registry entry.--#### [x] A11 — ADR 0007: hub performance posture (2026-06-13 · test_perf passed)-- **Lane:** DOCS+PY · **Size:** S · **Depends on:** —-- **Do:** Record the language/runtime decision so no agent drifts into a rewrite: the hub stays **Python** — the ecosystem is the moat (MCP SDK, IfcOpenShell, specklepy, ifctester, openpyxl, pyarrow/DuckDB), and hub latency is dominated by host applications and network/disk I/O, not the interpreter. Rules: performance-critical paths must use native-backed libraries (IfcOpenShell's C++ core for geometry, pyarrow/DuckDB for the lake, `orjson` for large payloads); a single module may be dropped to Rust/C++ as a Python extension (PyO3/nanobind) ONLY when a recorded profile shows it dominating a workflow budget — never a whole-hub rewrite. Desktop switches remain native by construction (C# in-process with each host). Define budgets in the ADR: hub tool-dispatch overhead < 10 ms; W3 health audit on the sample IFC < 60 s on a laptop. Add one perf smoke test (skip-by-default marker) asserting the dispatch-overhead budget.-- **Verify:** ADR merged with budgets table; `python -m pytest packages/mcp-server-revit/tests -k perf -m perf` passes locally.--**Phase A gate:** CI green; `pytest` full suite passes; one Speckle provider; proxy registered; generated catalog live; A9 position recorded.-------## PHASE B — Switch Contract v2, Navisworks Completion, Policy Layer--> Goal: secure modular discovery (blueprint §3), a real Navisworks switch, and the policy gates. Lanes PY and NET run largely in parallel after B1.--#### [x] B1 — ADR 0002: Switch Contract v2 specification (2026-06-13 · ADR merged)-- **Lane:** DOCS · **Size:** M · **Depends on:** —-- **Do:** Write `docs/0002-switch-contract-v2.md` finalizing: registry file JSON schema (path `%LOCALAPPDATA%\AECModelBridge\registry\<provider>-<pid>.json`; fields per blueprint §3.3), token rules (generation, ACL, header `Authorization: Bearer`), `/capabilities` manifest schema (reuse ADR 0001 §3), protocol_version=2 negotiation, legacy fixed-port fallback + deprecation timeline, stale-entry pruning rules (PID liveness + max age).-- **Done when:** ADR merged; both PY and NET lanes can implement from it without further decisions.--#### [x] B2 — Hub: discovery registry reader (2026-06-13 · test_discovery passed)-- **Lane:** PY · **Size:** M · **Depends on:** B1-- **Do:** New module (e.g. `bridge/discovery.py`): scan registry dir, validate schema, check PID liveness, prune stale files, expose `discover_switches()`; integrate into provider initialization so desktop providers resolve endpoint+token dynamically; env override `MCP_REVIT_BRIDGE_URL` still wins (back-compat).-- **Verify:** unit tests with temp registry dirs: valid entry, stale PID, malformed JSON, ACL-denied file.--#### [x] B3 — Hub: bearer-token client + legacy fallback-- **Lane:** PY · **Size:** M · **Depends on:** B1-- **Do:** `BridgeClient` sends the discovered session token; on no registry entry, probe legacy `:3000`/`:3002` tokenless with a deprecation warning logged once. Tokens excluded from logs/audit (extend redaction tests).-- **Verify:** tests: token attached; legacy path warns; token never in audit log fixture.--#### [x] B4 — Revit add-in: capability manifest generation (2026-06-13 · Build passed, route parity verified)-- **Lane:** NET · **Size:** L (split allowed) · **Depends on:** B1-- **Context:** `src/Bridge/BridgeCommandFactory.cs` (~103 route switch).-- **Do:** Introduce a `[BridgeCommand(Name, IsMutating, ConfirmationRequired, ExecutionMode)]` attribute; annotate handlers (mechanical but large — split by command registry file); build factory routing AND `/capabilities` JSON from the attributes at startup. The switch expression goes away; one source of truth.-- **Done when:** `GET /capabilities` returns all routes with correct mutating flags; route count matches pre-refactor (regression-tested by comparing route lists).-- **Verify:** `.\scripts\build-addin.ps1 -RevitVersion 2026 -Configuration Release`; route-parity test.--#### [x] B5 — Revit add-in: Contract v2 runtime (port, registry file, token) (2026-06-13 · Build passed, limits added)-- **Lane:** NET · **Size:** M · **Depends on:** B4-- **Do:** Bind OS-assigned loopback port (config override to pin 3000 for legacy clients, default ON for one release); generate session token; write/delete registry file on startup/shutdown (and on crash: stale-file tolerance is B2's job); enforce token on `/execute` (skip when legacy fixed-port mode is active); add request size + concurrency limits.-- **Verify:** build all four Revit targets; manual smoke: `Invoke-RestMethod` health with and without token.--#### [x] B6 — Navisworks add-in: command routing infrastructure (2026-06-13 · build 2026/net48 succeeded; navis.echo registered; §3.2 envelope; ClashCommands registered; API fixes for 2026 DLLs; 108 Python tests pass)-- **Lane:** NET · **Size:** M · **Depends on:** B1-- **Context:** `packages/navisworks-bridge-addin/src/` — currently `/execute` returns doc title only.-- **Do:** Mirror the Revit add-in's pattern at small scale: attribute-based command registry (same design as B4 from day one — no switch-expression detour), main-thread execution guard (Navisworks API calls must run on the UI thread — use the plugin's synchronization context), result envelope per blueprint §3.2.-- **Verify:** builds for net48 + net8.0-windows; a `navis.echo` test command round-trips.--#### [x] B7 — Navisworks routes: model tree, selection, append/refresh-- **Lane:** NET · **Size:** M · **Depends on:** B6-- **Do:** Routes: `navis.get_document_info`, `navis.get_model_tree` (depth-limited, with item paths + GUIDs where present), `navis.get_selection`, `navis.append_file`, `navis.refresh`. Use `Autodesk.Navisworks.Api` Document/Models/ModelItem APIs.-- **Verify:** build passes; route list includes the five; manual smoke against a sample NWD recorded in evidence.--#### [x] B8 — Navisworks routes: saved viewpoints-- **Lane:** NET · **Size:** S · **Depends on:** B6-- **Do:** `navis.list_viewpoints`, `navis.create_viewpoint`, `navis.activate_viewpoint` (SavedViewpoints API).-- **Verify:** build; smoke evidence.--#### [x] B9 — Navisworks routes: Clash Detective-- **Lane:** NET · **Size:** L · **Depends on:** B6-- **Do:** Routes: `navis.list_clash_tests`, `navis.create_clash_test` (two selection sets by model/path), `navis.run_clash_test`, `navis.get_clash_results` (grouped; per clash: status, distance, point, both item identities — path + IFC GUID property when available). Use `Autodesk.Navisworks.Api.Clash` (`DocumentClash.TestsData`, run via `TestsRunTest…`). Results may be large → support paging params.-- **Done when:** a two-model clash test runs and returns identifiable items end-to-end via HTTP.-- **Verify:** build; live smoke against Navisworks Manage with a sample federated model — record version + date.--#### [x] B10 — Navisworks add-in: Contract v2 runtime-- **Lane:** NET · **Size:** S · **Depends on:** B5 (reuse its implementation), B6-- **Do:** Port the B5 port/registry/token/capabilities code (extract shared source or copy with attribution — no shared binary between add-ins to keep installs independent).-- **Verify:** registry file appears on plugin load; token enforced.--#### [x] B11 — Hub: NavisworksProvider + mock + tests-- **Lane:** PY · **Size:** M · **Depends on:** B2 (discovery), B7–B9 (route shapes from ADR/B-lane PRs — can start from the ADR contract before NET lane finishes)-- **Do:** New `providers/navisworks.py` exposing `navisworks_*` tools mapping 1:1 to B7–B9 routes; `MockNavisworksBridge` with deterministic clash fixtures; register in `mcp_server.py` (optional-provider pattern); contract tests via A8 suite.-- **Verify:** `python -m pytest packages/mcp-server-revit/tests -k navisworks` (mock mode, no Navisworks needed).--#### [x] B12 — Hub tool: `aec_bridge_status`-- **Lane:** PY · **Size:** S · **Depends on:** B2-- **Do:** One tool reporting every known switch: installed/alive/version/protocol/capability digest, plus "what installing X would unlock" (from a static capability→workflow map). This is the diagnostic entry point (blueprint §4.3).-- **Verify:** unit test over fake registry states (all-alive, one-stale, none).--#### [x] B13 — CLI: `aec-bridge doctor`-- **Lane:** PY · **Size:** S · **Depends on:** B12-- **Do:** Console entry point (add to `pyproject.toml [project.scripts]`) wrapping B12 for humans: colorized table, exit code 0/1, install-pointer URLs for missing switches.-- **Verify:** `aec-bridge doctor` runs in a clean venv; snapshot test of output.--#### [ ] B14 — Policy layer (close the security.md gap)-- **Lane:** PY · **Size:** M · **Depends on:** A8-- **Do:** Implement in config + one enforcement point (registry execute path): `allowed_tools` allow-list, `allow_destructive` (default false → mutating tools refused with actionable message), `destructive_confirm` (require `confirm: true` arg on confirmation_required tools), `high_risk_enabled` (reflection/`execute_python` gated separately, default off). Update `docs/security.md` to describe reality.-- **Verify:** security tests: destructive call w/o opt-in refused; allow-list enforced; high-risk off by default.--#### [ ] B15 — Redaction & abuse-case test extension-- **Lane:** PY · **Size:** S · **Depends on:** B3, B14-- **Do:** Tests for: oversized request rejection, malformed manifest handling, stale discovery record, path traversal via workspace tools, token never present in any tool result or audit line (fuzz across providers).-- **Verify:** suite green; cases enumerated in evidence line.--**Phase B gate:** W2's switch-side prerequisites exist (clash runs via HTTP); `aec-bridge doctor` correctly reports a machine with only Revit installed; tokenless legacy mode warns; policy tests pass.-------## PHASE C — Omni-Bridge Orchestrator & Flagship Recipes--> Goal: blueprint §5 — the recipe engine, Run Records, and recipes W1–W4 proven in mock mode, then live. Lane PY throughout; C-tasks are mostly sequential through C6, then C7–C12 parallelize.--#### [ ] C1 — ADR 0003: recipe engine & schema-- **Lane:** DOCS+PY · **Size:** M · **Depends on:** B-gate-- **Do:** Finalize blueprint §5.1 into `docs/0003-recipe-engine.md` + Pydantic models (`orchestrator/schema.py`): recipe doc (YAML authoring, JSON wire — blueprint OD1 leaning), step types (tool / capability / built-in), binding syntax (`$step_id.field`), `requires/prefer/fallback`, confirmation + idempotency semantics, error policy (fail-fast vs continue-with-degradation per step).-- **Verify:** schema round-trips the §5.1 example recipe; invalid recipes produce precise validation errors (tested).--#### [ ] C2 — Capability naming layer-- **Lane:** PY · **Size:** S · **Depends on:** C1-- **Do:** Add optional `capability` field to provider tool manifests (e.g. `revit_create_elements_batch` → `revit.create_elements`; `navisworks_run_clash_test` and `graph_audit_clashes` both → `clash`); registry API `resolve_capability(name) -> [tools ordered by preference]`.-- **Verify:** unit tests incl. multi-provider capability with preference order.--#### [ ] C3 — Engine core: step execution + bindings-- **Lane:** PY · **Size:** M · **Depends on:** C1, C2-- **Do:** `orchestrator/engine.py`: execute steps sequentially on the job pipeline (`workflow_run` returns a JobReference); resolve bindings; collect per-step results, warnings, artifacts into run state.-- **Verify:** 3-step recipe against FakeProvider passes e2e in tests.--#### [ ] C4 — Engine: capability fallbacks + degradation records-- **Lane:** PY · **Size:** S · **Depends on:** C3-- **Do:** When the preferred tool's provider is absent/unhealthy, fall through the C2 preference list; record each degradation (string per blueprint §5.2) in run state; if nothing resolves, fail the step with the "install X from URL" message pattern (B12's map).-- **Verify:** test with preferred provider removed → fallback used → degradation recorded.--#### [ ] C5 — Engine: confirmation gates, idempotency, dry-run-- **Lane:** PY · **Size:** M · **Depends on:** C3, B14-- **Do:** Steps marked `confirmation: required` pause the workflow (job status `awaiting_confirmation`, resumable via `workflow_confirm` tool); idempotency keys derived from `run_id + step_id` passed to mutating tools; `workflow_run(dry_run=true)` executes only read-only steps and emits the would-do plan for mutating ones.-- **Verify:** tests: paused→confirmed→resumed; duplicate run with same key is rejected by a FakeProvider asserting single execution; dry-run mutates nothing.--#### [ ] C6 — Workflow MCP tools + progress notifications-- **Lane:** PY · **Size:** S · **Depends on:** C3-- **Do:** Register `workflow_list`, `workflow_describe`, `workflow_run`, `workflow_status`, `workflow_confirm`, `workflow_cancel`; emit MCP progress notifications per step start/finish.-- **Verify:** tool-level tests; progress events observed in test harness.--#### [ ] C7 — Run Record schema v1 + builder-- **Lane:** PY · **Size:** M · **Depends on:** C3-- **Do:** Pydantic `RunRecord` per blueprint §5.2 (versioned, documented in `docs/run-record-schema.md` — generated from the model); builder collects switches/inputs/outputs/identity_map/degradations/artifacts; every workflow emits one; written to `<workspace>/runs/<run_id>.json`.-- **Verify:** schema doc generated; every engine test asserts a valid record.--#### [ ] C8 — Identity registry persistence + auto-registration-- **Lane:** PY · **Size:** M · **Depends on:** C3-- **Do:** Move `identity_mapper.py` store to SQLite per workspace (reuse exporter's SQLite plumbing — blueprint OD3); engine auto-registers mappings emitted by mutating steps (e.g. created Revit elements carrying source Rhino UUIDs); mappings appear in Run Records.-- **Verify:** mappings survive process restart in tests; W1 mock run populates the map.--#### [ ] C9 — Recipe W1: Concept-to-BIM (Rhino → Revit)-- **Lane:** PY · **Size:** M · **Depends on:** C4–C8-- **Do:** Author `recipes/concept-to-bim.yaml` per blueprint §6 W1; may require adding a `revit_create_elements_batch` hub tool composing existing bridge routes (create_wall/floor/column/level) with per-element idempotency; mock e2e test with fixture massing JSON.-- **Verify:** mock e2e in CI: fixture massing → ≥3 element categories in MockBridge → quantities in Run Record.--#### [ ] C10 — Recipe W2: Coordination Loop-- **Lane:** PY · **Size:** S · **Depends on:** C4–C8, B11-- **Do:** `recipes/coordination-loop.yaml`: append models → run clash (capability `clash`, prefer navisworks, fallback graph) → translate clash item IDs via mapper → Run Record.-- **Verify:** mock e2e both paths (Navisworks mock present; absent→graph fallback with degradation).--#### [ ] C11 — Recipe W3: Model Health & Compliance (zero-switch)-- **Lane:** PY · **Size:** M · **Depends on:** C4–C8 (IDS part arrives with D5 — score without IDS first)-- **Do:** `recipes/model-health.yaml`: IFC open → graph compile → audits (clashes, disconnected, load paths) → weighted health score (document the scoring rubric in the recipe) → Run Record. Must run with zero desktop software (blueprint §4.2).-- **Verify:** CI e2e against a committed sample IFC fixture produces a scored record.--#### [ ] C12 — Recipe W4: Data-Lake Drop-- **Lane:** PY · **Size:** S · **Depends on:** C7; Speckle path needs A1/A2; Parquet path needs D1 (either alone passes)-- **Do:** `recipes/data-lake-drop.yaml`: take any Run Record → Speckle version commit AND/OR Parquet write; either target alone is valid (blueprint §6 W4).-- **Verify:** mock e2e: record → fake transport commit; (after D1) → Parquet file readable.--#### [H] C13 — Live verification runs + evidence-- **Lane:** HUMAN (drives) + PY agent (fixes found issues) · **Size:** M · **Depends on:** C9–C12-- **Do (you):** Run W1 (Rhino+Revit live), W2 (Navisworks live), W3 (laptop, no Autodesk), W4 (real Speckle project + Parquet). Record host versions, dates, gaps in blueprint §10 C5 table. File defects as new tasks.--**Phase C gate:** all four recipes green in CI mock mode; live evidence recorded; `workflow_run` is the single entry point an MCP client needs for the hero demo.-------## PHASE D — Data Plane & Dashboards--#### [ ] D1 — Parquet/DuckDB exporter for Run Records-- **Lane:** PY · **Size:** M · **Depends on:** C7-- **Do:** Extend `providers/exporter.py`: `exporter_run_to_parquet` flattening a Run Record into tables (`runs`, `elements`, `clashes`, `quantities`, `identity_map`) under `<workspace>/lake/`; append-mode so history accumulates; add `duckdb` + `pyarrow` as optional extra `[lake]`.-- **Verify:** tests: two runs → DuckDB query `SELECT count(*) FROM clashes GROUP BY run_id` returns both.--#### [ ] D2 — Lakehouse layout doc + history queries-- **Lane:** DOCS · **Size:** S · **Depends on:** D1-- **Do:** `docs/lakehouse.md`: directory layout, table schemas (generated from D1 models), five copy-paste DuckDB queries (clash trend, health score over time, quantities by category…), Power BI direct-Parquet import steps.--#### [ ] D3 — Power BI template: Model Health (W3)-- **Lane:** DATA · **Size:** M · **Depends on:** D1, C11-- **Do:** `.pbit` over the lake tables: health score trend, findings by severity, element counts. Ship in `templates/powerbi/` with a README and a sample lake generated from fixtures.-- **Done when:** template + one fixture Run Record → working dashboard in <10 min (blueprint D2 criterion).--#### [ ] D4 — Power BI template: Coordination (W2)-- **Lane:** DATA · **Size:** M · **Depends on:** D1, C10-- **Do:** `.pbit`: clash counts by test/status/run, new-vs-resolved trend, top clashing element pairs (via identity map).--#### [ ] D5 — IDS rule checking in IfcProvider-- **Lane:** PY · **Size:** M · **Depends on:** —(parallel any time)-- **Do:** Add `ifc_validate_ids(ifc_path, ids_path)` using the `ifctester` package (IfcOpenShell family); structured findings (spec, requirement, pass/fail, failing GUIDs); wire into W3's score; commit two sample IDS fixture files.-- **Verify:** tests against fixtures: one passing, one failing spec.--#### [ ] D6 — Completion webhooks (Teams/Slack)-- **Lane:** PY · **Size:** M · **Depends on:** C6-- **Do:** `webhook_register(url, events)` persisted per workspace; on workflow completion/failure POST an Adaptive Card (Teams) / Block Kit (Slack) summary of the Run Record; secrets-safe (URL stored, never echoed); retries with jitter.-- **Verify:** tests with a local HTTP capture server; payload snapshot tests.--#### [x] D7 — GraphML export (optional, strategic roadmap item 4)-- **Lane:** PY · **Size:** S · **Depends on:** —-- **Do:** `graph_export_graphml(path)` on the semantic graph provider (networkx has native support); document the Neo4j import one-liner.--**Phase D gate:** the hero demo (W2/W3 → dashboard refresh shows new data within a minute) works via both the Speckle path and the local Parquet path.-------## PHASE E — Wave 2 Switches: Excel, ACC/Forma, Solibri--#### [ ] E1 — Excel headless switch: core read/write-- **Lane:** PY · **Size:** M · **Depends on:** B14 (mutation gates)-- **Do:** New `providers/excel.py` (in-hub, openpyxl, optional extra `[excel]`): `excel_read_table`, `excel_write_table` (real Excel Tables/ListObjects, not bare ranges), `excel_list_sheets`; workspace-sandboxed paths only; mutating flags set.-- **Verify:** tests round-trip a table on a fixture workbook; sandbox violation refused.--#### [ ] E2 — Excel: dry-run diff + write-back-- **Lane:** PY · **Size:** M · **Depends on:** E1-- **Do:** `excel_diff_table` producing a cell-level JSON diff (the W5 "show before write" requirement); `excel_write_table(confirm=…)` honoring B14 gates.-- **Verify:** diff snapshot tests; gated write tests.--#### [ ] E3 — Recipe W5: QTO round-trip-- **Lane:** PY · **Size:** M · **Depends on:** E2, C-gate-- **Do:** `recipes/qto-roundtrip.yaml`: Revit schedules → Excel table → (human edits rates) → diff → write rates into Revit shared parameters (confirmation-gated). Mock e2e; live evidence task appended to C13 list.-- **Verify:** mock e2e in CI per blueprint §6 W5 acceptance.--#### [ ] E4 — Excel cloud variant (Microsoft Graph)-- **Lane:** PY · **Size:** L · **Depends on:** E1; **[H]** sub-step: Azure app registration (you)-- **Do:** `providers/msgraph.py` (OAuth PKCE per cloud provider pattern in `cloud.py`): workbook table read/write on SharePoint/OneDrive; same tool names with `graph_` prefix; live tests behind `AEC_LIVE_TESTS`.--#### [ ] E5 — ACC/Forma: AEC Data Model reads-- **Lane:** PY · **Size:** M · **Depends on:** A-gate; **[H]** sub-step: APS app + ACC project access (you)-- **Do:** Extend `AutodeskDataProvider`: AEC Data Model GraphQL queries (elements + properties of cloud-hosted designs), hub/project/folder navigation hardening, pagination + rate-limit handling.-- **Verify:** mocked GraphQL tests; live evidence recorded.--#### [ ] E6 — ACC: Issues publishing from W2-- **Lane:** PY · **Size:** M · **Depends on:** E5, C10-- **Do:** `acc_create_issue` (ACC Issues API) + W2 recipe option `publish_issues: acc` mapping clash rows → issues (title, location, linked element IDs); idempotency so re-runs update rather than duplicate.-- **Verify:** mocked API tests; live: clash from W2 appears as an ACC issue (evidence).--#### [ ] E7 — ACC webhooks (model-updated triggers)-- **Lane:** PY · **Size:** M · **Depends on:** E5, D6-- **Do:** Register APS webhooks (model version added) → local handler endpoint or polling fallback → optionally auto-trigger a named recipe (the "dashboards never stale" loop closed end-to-end).--#### [ ] E8 — Solibri spike → ADR 0004-- **Lane:** PY (research) + **[H]** Solibri license (you) · **Size:** M · **Depends on:** A9-- **Do:** Verify against current Solibri docs: REST API availability/port/launch flags (historically `--rest-api-server-port=10876`, `/solibri/v1/…`), Open API (Java) plugin terms, what's automatable (open model, open ruleset, run checking, export BCF/Excel). Decide track (a) REST switch, (b) Java plugin, (c) file-exchange fallback (IFC in / BCF out, no Solibri API at all). Record as `docs/0004-solibri-integration.md` with evidence.--#### [ ] E9 — Solibri switch implementation-- **Lane:** per ADR 0004 (PY if REST; NET/Java if plugin) · **Size:** L · **Depends on:** E8-- **Do:** Implement the chosen track as `providers/solibri.py` (+ plugin if required): `solibri_open_model`, `solibri_run_ruleset`, `solibri_get_results`, `solibri_export_bcf`; mock + tests; Contract v2 registry entry if it's a desktop switch.-- **Verify:** mock e2e; live run evidence with Solibri Office version recorded.--#### [ ] E10 — W3 extension: Solibri findings in the health score-- **Lane:** PY · **Size:** S · **Depends on:** E9, C11-- **Do:** Add optional Solibri step to `model-health.yaml` (capability `rule_check`, fallback: skip with degradation); merge findings into the score; BCF artifacts attached to the Run Record.--**Phase E gate:** W5 live round-trip done; a clash published as an ACC issue; Solibri findings (or a documented fallback) in the health score.-------## PHASE F — Platform, Distribution & Docs (parallel lane from early on)--#### [ ] F1 — Switch SDK template-- **Lane:** NET · **Size:** M · **Depends on:** B5 (reference implementation)-- **Do:** Extract a `templates/switch-csharp/` template (cookiecutter-style): HttpListener loop, attribute command registry, Contract v2 (token/registry/capabilities), result envelope — so Solibri/Tekla/SketchUp switches start from a working skeleton. Include a `TEMPLATE-README` with the 10-step "new switch" checklist.-- **Verify:** template instantiates and builds as a standalone "echo" switch.--#### [ ] F2 — MkDocs documentation site-- **Lane:** DOCS · **Size:** M · **Depends on:** A5, A6-- **Do:** MkDocs Material in-repo; nav: Getting Started (zero-switch IFC demo FIRST), per-switch install guides, workflows W1–W5, generated tool catalog, Run Record schema, security model, licensing/commercial page (strategy doc Rung 1 funnel); GitHub Pages deploy workflow.-- **Verify:** site builds in CI; deployed.--#### [ ] F3 — First-run tutorial: the zero-switch demo-- **Lane:** DOCS+PY · **Size:** M · **Depends on:** C11, F2-- **Do:** A guided "10 minutes, no licenses" walkthrough: install hub → sample IFC (commit a small open-licensed fixture) → run W3 → open results; plus a `aec-bridge demo` CLI command that scaffolds the sample workspace.-- **Verify:** executed verbatim on a clean machine/VM; timing recorded.--#### [ ] F4 — Release automation per switch-- **Lane:** PY/NET · **Size:** M · **Depends on:** B5, B10-- **Do:** Extend `release.yml`: independent versioned artifacts per switch (revit-switch-<year>-vX.zip, navisworks-switch-…), SHA256SUMS, hub wheel + `.mcpb`; release notes generated from conventional commits; (stretch) winget manifest for the hub.-- **Verify:** tag → draft release with all artifacts + checksums.--#### [H] F5 — Autodesk App Store submission prep-- **Lane:** HUMAN · **Size:** L · **Depends on:** A9, B5, B10, F4-- **Do (you):** Publisher account, store packaging requirements (MSI/bundle, help docs, support URL), submission for Revit switch first, Navisworks second. Credibility badge per strategy doc.--#### [ ] F6 — Sample assets pack-- **Lane:** DATA · **Size:** S · **Depends on:** C9–C12-- **Do:** `samples/`: small open IFC, massing JSON fixture, demo recipes, one pre-baked lake with 5 Run Records (feeds D3/D4 templates and F3 tutorial).--#### [ ] F7 — README + ecosystem story refresh-- **Lane:** DOCS · **Size:** S · **Depends on:** C-gate-- **Do:** Rewrite README around the orchestration story (workflows first, tool counts second), accurate switch matrix with per-switch install links, hero GIF placeholder, link to docs site.--#### [ ] F8 — Rhino native plugin decision (blueprint OD2)-- **Lane:** DOCS→NET · **Size:** S (decision) + L (optional build) · **Depends on:** C13 (live W1 evidence shows whether proxy suffices)-- **Do:** ADR: proxy-first verdict with evidence. Only if proxy proves limiting: build `.rhp` from F1 template exposing live-document geometry/layers/usertext routes; Food4Rhino packaging.-------## PHASE G — Wave 3 Specification Cards (spec-only; each must "earn its place" before implementation)--Each G-task produces a 1–2 page spec in `docs/specs/` answering: named workflow it enables · API surface + auth · adapter type (per blueprint §3/§8 taxonomy) · licensing position (extends A9) · test-access plan · go/no-go recommendation. **No packages, no code** (integration-expansion-handover rule: no empty connector packages).--#### [ ] G1 — Archicad provider spec + spike-- **Size:** M · Highest-priority G: Archicad's local JSON API (official Python package, default port 19723 — verify) means a **hub-side provider with no add-in**, unusually low friction. Spike: connect to a running Archicad, list elements/properties. Target workflow: W3 health audit on Archicad projects. **Implementation promoted to I5** (2026-06 ecosystem research: the community Tapir JSON command schema auto-generated 137 tools — integration is nearly free).--#### [ ] G2 — Tekla Structures adapter spec-- **Size:** S · .NET local adapter (Tekla Open API connects to the running instance); target workflow: structural QTO into W5; licensing + version-pinning notes mandatory.--#### [ ] G3 — SketchUp switch spec-- **Size:** S · Ruby extension implementing Contract v2; target: early-design massing into W1 as an alternative concept source.--#### [ ] G4 — Bentley iTwin provider spec-- **Size:** S · Cloud OAuth; target: changeset-aware W3 audits for infrastructure clients.--#### [ ] G5 — Trimble Connect provider spec-- **Size:** S · Cloud; target: BCF topic publishing from W2 (vendor-neutral alternative to ACC Issues).--#### [ ] G6 — Procore provider spec-- **Size:** S · Cloud; target: W2 clash → Procore observations/RFIs for GC-side users.--#### [ ] G7 — Primavera (P6/Cloud) provider spec-- **Size:** S · Cloud; target: 4D — join Run Record quantities to schedule activities in the lakehouse.-------## PHASE H — Any-AI Access Layer (Chapter 2)--> Goal: the average BIM professional drives the hub from **whatever AI they already have** — Claude, ChatGPT, Copilot, Gemini, or a local model — and installs everything without being a developer. This turns the machine (A–G) into a product anyone can use. H1's ADR amends blueprint §2 Layer 0.--#### [ ] H1 — ADR 0005: access-layer architecture (the four doors)-- **Lane:** DOCS+PY · **Size:** M · **Depends on:** B14-- **Do:** Write `docs/0005-any-ai-access-layer.md` deciding: the hub exposes four doors — (1) MCP stdio (today, unchanged); (2) **remote MCP** over Streamable HTTP — the universal door, since Claude, ChatGPT connectors, Copilot Studio, Gemini CLI and most agent frameworks speak MCP-over-HTTP as of 2026; (3) **REST/OpenAPI facade** for AIs and automation tools without MCP (custom GPT Actions, Power Automate, n8n, Zapier); (4) bundled **BYO-LLM console** (H5). Decide: auth = per-client API keys mapped to B14 policy scopes; remote default exposure = workflows + read-only tools (raw mutating/high-risk tools need an explicit scope); bind defaults to loopback.-- **Done when:** ADR merged; blueprint §2 Layer-0 diagram amended; H2–H7 are implementable without further decisions.--#### [ ] H2 — Remote MCP endpoint (Streamable HTTP) + API-key auth-- **Lane:** PY · **Size:** M · **Depends on:** H1-- **Do:** Serve the existing MCP server over Streamable HTTP (configurable host/port, default `127.0.0.1:8787`; SSE fallback for legacy clients); API keys created via `aec-bridge keys` (hashed at rest), each key carrying a B14 policy scope; audit every remote call (redaction rules apply).-- **Verify:** pytest MCP-client-over-HTTP round-trip (list + call); missing/bad key → 401; key never appears in logs or audit fixtures.--#### [ ] H3 — REST facade + generated OpenAPI spec-- **Lane:** PY · **Size:** M · **Depends on:** H1, C6-- **Do:** HTTP API `/api/v1`: `GET /tools`, `POST /tools/{name}`, `GET /workflows`, `POST /workflows/{name}/run`, `GET /jobs/{id}`, `POST /runs/{id}/confirm` — generated from the same capability manifests as the tool catalog (one source of truth, per Standing Rule 5); publish `docs/openapi-howto.md` with paste-into-custom-GPT-Action and n8n/Power Automate walkthroughs.-- **Verify:** generated `openapi.json` validates; e2e REST test drives the FakeProvider 3-step recipe.--#### [ ] H4 — `aec-bridge connect`: client config generator-- **Lane:** PY · **Size:** S · **Depends on:** H2-- **Do:** CLI command printing/writing ready-to-paste configs per client: Claude Desktop/Code, VS Code `mcp.json`, Cursor, ChatGPT connector (remote URL + key), Copilot Studio, Gemini CLI, plus a generic remote-MCP block; `--all` writes them under `<workspace>/connect/`. `aec-bridge doctor` (B13) reports which doors are live.-- **Verify:** snapshot tests per client template.--#### [ ] H5 — BYO-LLM chat console (`aec-bridge ui`)-- **Lane:** PY · **Size:** L (split allowed) · **Depends on:** H3-- **Do:** Minimal local web app served by the hub: chat pane wired to ANY OpenAI-compatible endpoint (cloud key or local Ollama/LM Studio — endpoint + model picker), tool-calling against the REST facade, live job/run feed, confirmation buttons for gated steps, Run Record viewer. No heavy frontend build: static page + a light JS approach, shipped inside the wheel.-- **Done when:** a user with only Ollama on a laptop runs W3 end-to-end from the browser, fully offline.-- **Verify:** e2e test against a scripted fake OpenAI-compatible server; manual Ollama smoke recorded as evidence.--#### [ ] H6 — Recipe-authoring kit for AIs-- **Lane:** PY+DOCS · **Size:** M · **Depends on:** C1, C6-- **Do:** `workflow_validate(recipe)` tool returning precise schema errors; publish the recipe JSON Schema; `docs/authoring-recipes.md` with a copy-paste "author a recipe" prompt so any LLM can draft → validate → dry-run → save; user recipes in `<workspace>/recipes/` are listed by `workflow_list`.-- **Verify:** invalid recipe → actionable errors (tested); a saved authored recipe runs in mock mode.--#### [ ] H7 — Network exposure hardening-- **Lane:** PY · **Size:** M · **Depends on:** H2, H3-- **Do:** Non-loopback bind requires explicit opt-in env + logged warning; per-key rate limits; request size caps; key rotation/revocation; CORS rules for the console; optional TLS via user certs; extend B15 abuse tests to the remote surface; update `docs/security.md`.-- **Verify:** security suite: LAN bind refused by default; rate limit → 429; revoked key refused.--#### [ ] H8 — Non-developer install path-- **Lane:** PY/NET · **Size:** M · **Depends on:** F4, B13, H4-- **Do:** One Windows entry point (PowerShell one-liner and/or winget) that installs the hub, detects installed Revit/Navisworks versions, offers the matching switch installers, then runs `doctor` + `connect`; "10-minute" quickstart page on the F2 docs site.-- **Verify:** clean Windows VM → connected AI client in ≤10 min; timing recorded ([H] assists the VM run).--**Phase H gate:** a user with only ChatGPT (or any remote-MCP client) drives W3 through the remote door; a user with only Ollama does it offline through the console; neither needed a text editor to install.-------## PHASE I — Popularity Pack: neutral-layer bridges (research-ranked, Chapter 2)--> Goal: ship the marginal capabilities most likely to go popular, ranked by (popularity among average BIM professionals) × (ease of integration) — 2026-06 ecosystem research. Strategic through-line: desktop Revit MCP is being commoditized (Revit 2027 ships a built-in MCP server; many community servers exist). The defensible position is the **neutral coordination layer** — IFC + BCF + Speckle + clash + identity — that no vendor will build across competitors' tools.--#### [ ] I1 — BCF provider (open gap: no MCP bridge exists anywhere)-- **Lane:** PY · **Size:** M · **Depends on:** A8-- **Do:** `providers/bcf.py` (in-hub, optional extra `[bcf]`, e.g. IfcOpenShell's bcf module): `bcf_read`, `bcf_create_topic`, `bcf_add_viewpoint`, `bcf_write` for BCF 2.1 + 3.0 files; topics carry element GUIDs through the identity mapper.-- **Verify:** round-trip tests on fixture `.bcf` files (2.1 and 3.0); A8 contract suite passes.--#### [ ] I2 — W2 → BCF publishing (the killer demo)-- **Lane:** PY · **Size:** S · **Depends on:** I1, C10-- **Do:** W2 recipe option `publish_issues: bcf` mapping clash results → BCF topics with viewpoints + components; the `.bcf` attached to the Run Record as an artifact; idempotent re-runs update topics instead of duplicating.-- **Verify:** mock e2e: clash fixtures → valid BCF parsed back by an independent reader in the test.--#### [ ] I3 — IFC→glTF + self-contained web-viewer artifact-- **Lane:** PY · **Size:** M · **Depends on:** C7-- **Do:** `ifc_to_gltf(ifc_path)` (IfcOpenShell geometry/IfcConvert, optional extra); `aec_make_viewer(gltf)` emitting ONE self-contained HTML file (embedded glTF + bundled minimal three.js viewer) attached as a Run Record artifact — the "show me the model/clash" answer that opens in any browser and travels by email.-- **Verify:** fixture IFC → `.glb` + `.html`; the HTML loads offline in a headless-browser test.--#### [ ] I4 — `aec_describe_model`: the model digest-- **Lane:** PY · **Size:** S · **Depends on:** C7-- **Do:** One tool: IFC/Revit source → semantic-graph-powered digest designed for LLM consumption (counts by category/level, spatial tree summary, units, georeferencing, top warnings), markdown + JSON forms — the "explain this model" feature, zero desktop software required.-- **Verify:** fixture IFC digest snapshot test.--#### [ ] I5 — Archicad provider via Tapir (promoted from G1)-- **Lane:** PY · **Size:** M · **Depends on:** G1-- **Do:** `providers/archicad.py` over Archicad's local JSON/Tapir API; generate the tool surface from Tapir's command schema (community precedent auto-generated 137 tools); read-first scope (elements, properties, project navigation); target workflow: W3 health audit on a live Archicad project.-- **Verify:** mocked JSON-API tests; live evidence against a running Archicad recorded.--#### [ ] I6 — Grasshopper definition runner-- **Lane:** PY · **Size:** M · **Depends on:** A4-- **Do:** `gh_run_definition(path, inputs)` via Rhino.Compute (Hops pattern): submit a `.gh` definition, bind inputs, return outputs/geometry — the computational-design on-ramp into W1 for the large GH community; document limits (no live canvas).-- **Verify:** mocked Compute tests; live smoke against Rhino.Compute recorded.--#### [ ] I7 — Drop-folder automation-- **Lane:** PY · **Size:** M · **Depends on:** C6, D6-- **Do:** `aec-bridge watch <folder> --recipe model-health`: file watcher triggering a named recipe on new/changed IFC (debounced); results to `<workspace>/runs/` + optional D6 webhook — zero-prompt automation for users who will never open a chat window.-- **Verify:** e2e test: drop a fixture IFC into a temp dir → Run Record appears.--#### [ ] I8 — ADR 0006: Revit 2027 built-in MCP coexistence-- **Lane:** DOCS+PY · **Size:** M · **Depends on:** A4-- **Do:** Position against Autodesk's built-in Revit 2027 MCP server — **wrap, don't compete**: a `McpProxyProvider` target preset for the built-in server; capability mapping so recipes prefer our add-in on 2024–2026 and can use the built-in on 2027+; document the orchestrator (recipes, Run Records, identity, policy) as the value layer above any vendor MCP.-- **Verify:** ADR merged; proxy preset covered by a config test against a mock target.--**Phase I gate:** a clash run produces a BCF file another tool opens; "show me" yields a shareable offline HTML viewer; a dropped IFC produces a health report with zero prompts; Archicad participates in W3.-------## 5. Progress Log--Agents append one line per completed task (newest first): `YYYY-MM-DD · <task-id> · <branch/commit> · <evidence summary>`--- 2026-06-13 · B6 · task/B6 · Fixed brace bug in static constructor; added ClashCommands to registry; added navis.echo; §3.2 envelope; fixed API for Navisworks 2026 (ClashTest cast, Item1/2, RootItem, CaptureRuntimeOverrides); csproj conditional net48/net8.0-windows; 108 Python tests pass.-- 2026-06-13 · B5 · task/B5 · Added legacy mode config, token enforcement skip for legacy, concurrency limit, and payload size limit.-- 2026-06-13 · B4 · task/B4 · Replaced giant switch with BridgeCommandAttribute reflection-based routing and /capabilities manifest generation.-- 2026-06-13 · B3 · task/B3 · Implemented Contract v2 dynamic port, token auth, capabilities, and registry creation.-- 2026-06-13 · B2 · task/B2 · Implemented discovery registry reader and integrated into RevitProvider.-- 2026-06-13 · B1 · task/B1 · Authored docs/0002-switch-contract-v2.md establishing registry schema and auth.-- 2026-06-13 · A11 · task/A11 · Implemented ADR 0007 and added test_perf.py asserting < 10ms dispatch overhead.-- 2026-06-13 · A7 · task/A7 · Updated .gitignore for build artifacts and venv, confirmed CONTRIBUTING.md dist policy, noted missing 3dm files.-- 2026-06-12 · A0 · — · Blueprint, strategy doc, handover rewrite authored (docs only, no code).-------**Changelog**-- 2026-06-13 — v1.1 — Chapter 2 added: Phase H (Any-AI Access Layer, H1–H8) and Phase I (Popularity Pack: BCF, web viewer, model digest, Archicad/Tapir, Grasshopper runner, drop-folder, Revit 2027 coexistence, I1–I8); Ultimate State items 8–9; G1 implementation promoted to I5; milestone map extended; A11 performance-posture ADR card added. Rationale + dispatch kit: `docs/next-chapter.md`.-- 2026-06-12 — v1.0 — Initial backlog: 7 phases, ~70 task cards, dispatch protocols for Ralph-loop and GSD-lane delegation.diff --git a/docs/architecture.md b/docs/architecture.mddeleted file mode 100644index e09e1e3..0000000--- a/docs/architecture.md+++ /dev/null@@ -1,437 +0,0 @@-# Architecture--AEC Model Bridge is a two-tier system connecting MCP clients to Revit software through a Python server and .NET bridge add-in.--## System Overview--```-┌──────────────────────────────────────────────────────────────────┐-│ MCP Client (Claude Desktop, custom apps, automation scripts) │-└────────────────────────────┬─────────────────────────────────────┘- │- │ MCP Protocol (stdio)- │ JSON-RPC messages- │-┌────────────────────────────▼─────────────────────────────────────┐-│ MCP Server (Python) │-│ ┌────────────────┐ ┌──────────────┐ ┌────────────────────┐ │-│ │ Schema │ │ Workspace │ │ Audit │ │-│ │ Validation │ │ Sandbox │ │ Recorder │ │-│ │ (Pydantic) │ │ (pathlib) │ │ (JSONL logs) │ │-│ └────────────────┘ └──────────────┘ └────────────────────┘ │-│ │-│ ┌──────────────────────────────────────────────────────────┐ │-│ │ Tool Handlers (25 tools) │ │-│ │ - revit.health, revit.open_document, revit.export_* │ │-│ └──────────────────────────────────────────────────────────┘ │-│ │-│ ┌──────────────────────────────────────────────────────────┐ │-│ │ Bridge Client │ │-│ │ ┌────────────────┐ ┌────────────────────────┐ │ │-│ │ │ Mock Bridge │ OR │ HTTP Client (httpx) │ │ │-│ │ │ (deterministic)│ │ -> localhost:3000 │ │ │-│ │ └────────────────┘ └────────────────────────┘ │ │-│ └──────────────────────────────────────────────────────────┘ │-└────────────────────────────┬─────────────────────────────────────┘- │- │ HTTP POST (localhost only)- │ {"tool": "...", "payload": {...}}- │-┌────────────────────────────▼─────────────────────────────────────┐-│ AEC Model Bridge add-in (.NET, version-specific target) │-│ ┌──────────────────────────────────────────────────────────┐ │-│ │ BridgeServer (HttpListener on 127.0.0.1:3000) │ │-│ └────────────────────────────┬─────────────────────────────┘ │-│ │ │-│ ┌────────────────────────────▼─────────────────────────────┐ │-│ │ BridgeCommandFactory (tool router) │ │-│ │ - Routes tool requests to handlers │ │-│ │ - Serializes/deserializes JSON │ │-│ └────────────────────────────┬─────────────────────────────┘ │-│ │ │-│ ┌────────────────────────────▼─────────────────────────────┐ │-│ │ ExternalEventHandler (Revit API queue) │ │-│ │ - Queues operations on UI thread │ │-│ │ - Executes Revit API calls safely │ │-│ └────────────────────────────┬─────────────────────────────┘ │-└────────────────────────────────┼─────────────────────────────────┘- │- │ Revit API- │-┌────────────────────────────────▼─────────────────────────────────┐-│ Autodesk Revit (2024-2027) │-│ - Document operations │-│ - Element queries and modifications │-│ - Export operations (PDF, DWG, IFC, CSV) │-│ - QA metric calculations │-└──────────────────────────────────────────────────────────────────┘-```--## Components--### MCP Server (Python)--**Location**: [packages/mcp-server-revit/](../packages/mcp-server-revit/)--**Responsibilities**:-- Listen for MCP protocol messages on stdin/stdout-- Validate tool inputs against JSON schemas (Pydantic)-- Enforce workspace sandboxing (all file paths within allowed directories)-- Route tool requests to appropriate handlers-- Record audit logs for every invocation-- Communicate with bridge (HTTP) or mock implementation--**Key Modules**:-- [server.py](../packages/mcp-server-revit/src/revit_mcp_server/server.py): Main MCP protocol handler-- [config.py](../packages/mcp-server-revit/src/revit_mcp_server/config.py): Environment-based configuration-- [schemas.py](../packages/mcp-server-revit/src/revit_mcp_server/schemas.py): Pydantic models for all 25 tools-- [tools/handlers.py](../packages/mcp-server-revit/src/revit_mcp_server/tools/handlers.py): Tool implementation functions-- [security/workspace.py](../packages/mcp-server-revit/src/revit_mcp_server/security/workspace.py): Path validation-- [security/audit.py](../packages/mcp-server-revit/src/revit_mcp_server/security/audit.py): Audit log writing-- [bridge/client.py](../packages/mcp-server-revit/src/revit_mcp_server/bridge/client.py): HTTP bridge client-- [bridge/mock.py](../packages/mcp-server-revit/src/revit_mcp_server/bridge/mock.py): Deterministic mock responses--**Configuration**:-```bash-MCP_REVIT_MODE=mock|bridge # Execution mode-MCP_REVIT_WORKSPACE_DIR=/path/to/workspace # Root directory for file operations-MCP_REVIT_ALLOWED_DIRECTORIES=... # Colon/semicolon-separated paths-MCP_REVIT_BRIDGE_URL=http://... # Bridge HTTP endpoint (bridge mode only)-MCP_REVIT_AUDIT_LOG=/path/to/log # Audit log file-```--### AEC Model Bridge Add-in (.NET)--**Location**: [packages/revit-bridge-addin/](../packages/revit-bridge-addin/)--**Responsibilities**:-- Start HTTP listener on Revit startup (IExternalApplication)-- Accept JSON POST requests from MCP server-- Queue operations on Revit UI thread via ExternalEvent-- Execute Revit API operations-- Return JSON responses to MCP server--**Key Classes**:-- [App.cs](../packages/revit-bridge-addin/src/Bridge/App.cs): Add-in entry point (IExternalApplication)-- [BridgeServer.cs](../packages/revit-bridge-addin/src/Bridge/BridgeServer.cs): HTTP listener (HttpListener on port 3000)-- [BridgeCommandFactory.cs](../packages/revit-bridge-addin/src/Bridge/BridgeCommandFactory.cs): Tool request router-- [ExternalEventHandler.cs](../packages/revit-bridge-addin/src/Bridge/ExternalEventHandler.cs): Revit API execution queue--**Deployment**:-1. Build with MSBuild or Visual Studio-2. Output DLL: `packages/revit-bridge-addin/bin/Release/{year}/{framework}/AECModelBridge.dll`-3. Manifest file: [AECModelBridge.addin](../packages/revit-bridge-addin/AECModelBridge.addin)-4. Install per-user to: `%APPDATA%\Autodesk\Revit\Addins\{year}\AECModelBridge.addin`-5. Installed binaries: `C:\ProgramData\AECModelBridge\bin\{year}\`--**Communication Protocol**:--Request format:-```json-POST http://localhost:3000/-Content-Type: application/json--{- "tool": "revit.export_schedules",- "payload": {- "request_id": "req_001",- "output_path": "C:\\workspace\\schedules.csv"- }-}-```--Response format:-```json-{- "schedules": ["Door Schedule", "Window Schedule"],- "output_path": "C:\\workspace\\schedules.csv"-}-```--Error response:-```json-{- "error": "RevitAPIException",- "message": "Failed to export schedule: Document not open"-}-```--## Execution Models--### Mock Mode--**Use case**: CI/CD, testing, development without Revit--**Behavior**:-- All tools return deterministic stub responses-- No bridge HTTP communication-- Workspace sandboxing still enforced-- Audit logging still active--**Advantages**:-- No Windows/Revit dependency-- Fast execution (no I/O delays)-- Repeatable outputs for regression tests-- Safe for automated pipelines--**Configuration**:-```bash-export MCP_REVIT_MODE=mock-```--### Bridge Mode--**Use case**: Production Revit automation--**Behavior**:-- MCP server sends HTTP requests to bridge-- Bridge queues operations on Revit UI thread-- Real Revit API operations execute-- Actual files generated (CSV, PDF, DWG, IFC)--**Requirements**:-- Windows 10/11-- Revit 2024-2027 running-- Bridge add-in installed and loaded--**Configuration**:-```bash-export MCP_REVIT_MODE=bridge-export MCP_REVIT_BRIDGE_URL=http://localhost:3000-```--## Why the Bridge Exists--### Revit API Constraints--1. **UI Thread Requirement**: Most Revit API operations must run on the main UI thread-2. **External Event Pattern**: Out-of-process calls must use `IExternalEventHandler`-3. **.NET Framework Dependency**: Revit API requires .NET 4.8 (not .NET Core)-4. **Windows-Only**: Revit runs exclusively on Windows--### Design Decisions--**Why not Python → Revit directly?**-- Revit API is .NET only-- pythonnet/.NET interop is complex and fragile-- Process boundary provides cleaner separation--**Why HTTP instead of named pipes/IPC?**-- Simple debugging (curl/Postman can test bridge)-- No Windows-specific IPC complexity-- HTTP is language-agnostic for future clients-- Localhost-only binding is secure--**Why separate add-in instead of Revit macros?**-- Add-ins start automatically with Revit-- No manual macro execution required-- Persistent HTTP listener across sessions-- Better error handling and logging--## Trust Boundaries--### Boundary 1: MCP Client → MCP Server--**Threat**: Malicious client sends path traversal attacks--**Mitigation**:-- Schema validation rejects malformed inputs-- Workspace sandbox blocks paths outside allowed directories-- All file paths resolved to absolute paths before validation--### Boundary 2: MCP Server → Bridge--**Threat**: Compromised bridge returns malicious data--**Mitigation**:-- Bridge runs on localhost only (127.0.0.1)-- No authentication needed (same-machine trust)-- Responses validated against output schemas-- Audit log records all bridge communications--### Boundary 3: Bridge → Revit--**Threat**: Bridge exploits Revit API vulnerabilities--**Mitigation**:-- ExternalEvent enforces UI thread execution-- Revit API's own security model applies-- Document operations respect Revit's file permissions-- Bridge cannot execute arbitrary code--## Scaling and Performance--### Current Limitations--- Single-threaded bridge (one request at a time)-- Synchronous HTTP requests (blocking)-- No request queuing or batching-- Each tool invocation is independent--### Future Improvements--- Async HTTP client in MCP server-- Request queue in bridge with parallel execution-- Batch operations (e.g., export 100 sheets in one call)-- Persistent document cache (avoid repeated opening)--## Testing Strategy--### Unit Tests--**Location**: [packages/mcp-server-revit/tests/](../packages/mcp-server-revit/tests/)--**Coverage**:-- Schema validation (valid/invalid inputs)-- Workspace path enforcement-- Tool handler registration-- Mock bridge responses--**Run**:-```bash-pytest packages/mcp-server-revit/tests-```--### Integration Tests--**Approach**: Use mock mode to test end-to-end without Revit--```python-# Set mock mode-os.environ["MCP_REVIT_MODE"] = "mock"--# Run server and send MCP messages-response = mcp_server.handle_tool_request({- "tool": "revit.export_schedules",- "payload": {"request_id": "test_001", "output_path": "/workspace/test.csv"}-})--# Validate response matches schema-assert "schedules" in response-assert response["output_path"] == "/workspace/test.csv"-```--### Manual Testing (Bridge Mode)--1. Build and install bridge add-in-2. Start Revit-3. Verify HTTP listener: `curl http://localhost:3000/`-4. Connect an MCP client using the configuration in [marketplaces.md](marketplaces.md)-5. Check audit log for recorded requests--## Security Considerations--See [security.md](security.md) for comprehensive security model.--**Key points**:-- All file paths sandboxed to allowed directories-- Bridge binds to localhost only (no external exposure)-- Audit logs record every tool invocation-- Schema validation prevents injection attacks-- Mock mode safe for untrusted CI environments--## Extending the System--### Adding a New Tool--1. Define input/output schemas in [schemas.py](../packages/mcp-server-revit/src/revit_mcp_server/schemas.py):-```python-class MyToolInput(RequestPayload):- document_id: str- parameter_name: str--class MyToolOutput(BaseModel):- value: str-```--2. Implement handler in [handlers.py](../packages/mcp-server-revit/src/revit_mcp_server/tools/handlers.py):-```python-def my_tool(payload: dict, workspace: WorkspaceMonitor) -> dict:- input_model = MyToolInput(**payload)- # Mock implementation- return MyToolOutput(value="mock_result").model_dump()-```--3. Register in `TOOL_HANDLERS`:-```python-TOOL_HANDLERS["revit.my_tool"] = my_tool-```--4. Update bridge [BridgeCommandFactory.cs](../packages/revit-bridge-addin/src/Bridge/BridgeCommandFactory.cs):-```csharp-case "revit.my_tool":- // Revit API implementation- var doc = GetActiveDocument();- var param = GetParameter(doc, payload["parameter_name"]);- return new { value = param.AsString() };-```--5. Add tests in [test_tools.py](../packages/mcp-server-revit/tests/test_tools.py)--6. Document in [tools.md](tools.md)--## Deployment Topologies--### Local Development--```-Developer Machine:- - Revit 2024- - Bridge add-in- - MCP server (Python venv)- - Demo client-```--### CI/CD Pipeline--```-GitHub Actions (Windows runner):- - MCP server (mock mode)- - Pytest- - No Revit dependency-```--### Production Automation--```-Dedicated Windows Server:- - Revit 2024 (licensed)- - Bridge add-in (installed)- - MCP server (systemd/Windows service)- - Cron/scheduled tasks invoke demo client- - Audit logs → monitoring system-```--## Troubleshooting--### Bridge Not Responding--**Symptoms**: MCP server reports "Connection refused"--**Diagnosis**:-1. Check Revit is running-2. Verify add-in loaded: Check Revit Journal file-3. Test bridge directly: `curl http://localhost:3000/`-4. Review add-in manifest path in `AECModelBridge.addin`--### Workspace Violations--**Symptoms**: `WorkspaceViolation` errors--**Diagnosis**:-1. Print allowed directories: `echo $MCP_REVIT_ALLOWED_DIRECTORIES`-2. Verify paths are absolute-3. Check path separators (Windows: `\\` or `/`)-4. Ensure directories exist and are readable--### Schema Validation Failures--**Symptoms**: `SchemaValidationError` on tool invocation--**Diagnosis**:-1. Review tool schema in [tools.md](tools.md)-2. Check required vs optional fields-3. Validate JSON syntax-4. Review error message for specific field issues--See [install.md](install.md) for additional troubleshooting.diff --git a/docs/integration-expansion-handover.md b/docs/integration-expansion-handover.mddeleted file mode 100644index 583a6db..0000000--- a/docs/integration-expansion-handover.md+++ /dev/null@@ -1,472 +0,0 @@-# Multi-Platform Integration Handover--Research date: 2026-06-11--This document hands AEC Model Bridge to the next implementation agent. It-summarizes the current repository, the most useful AEC integration targets,-their official API surfaces, and the decisions that must be made before adding-connectors.--## Short Handover Prompt--```text-Act as the lead architect and implementation owner for AEC Model Bridge.--Read docs/integration-expansion-handover.md, inspect the repository, and verify-any API detail that may have changed against the linked official documentation.-Evolve the current Revit-only MCP system into a multi-provider AEC automation-platform without breaking existing Revit tool names, configuration, packaging,-or tests.--First write a concise architecture decision record covering provider discovery,-transport types, capability manifests, object references, authentication,-mutation controls, asynchronous jobs, licensing boundaries, and compatibility.-Then implement the smallest complete vertical slice: a provider contract and-registry, a compatibility adapter for the existing Revit bridge, and a-production-quality read-only IFC connector using IfcOpenShell. Expose a small,-coherent IFC tool set for health, file metadata, spatial structure, element-query, properties, quantities, and validation. Do not create empty connector-packages or attempt a universal BIM object model.--Keep host-specific SDK code out of the platform core. Treat desktop products as-separate local adapters, cloud products as OAuth providers, and batch engines as-asynchronous job providers. Add reusable provider contract tests, IFC fixtures,-mock coverage, migration documentation, and security tests. Preserve the-working Revit path throughout. Run the relevant Python tests and all supported-Revit add-in builds before finishing, and report exact results and remaining-vendor-account or licensed-application test gaps.-```--## Current Baseline--AEC Model Bridge currently has two runtime tiers:--1. A Python MCP server in `packages/mcp-server-revit`.-2. A C# add-in in `packages/revit-bridge-addin` that runs inside Revit.--The local bridge contract is already useful beyond Revit:--```text-GET /health-GET /tools-POST /execute-```--The Python client discovers the bridge tool catalog and sends a tool name,-payload, and request ID. The Revit add-in queues work onto the Revit UI thread.-The repository currently contains about 100 MCP tools and 110 unique Revit-bridge routes.--Important constraints in the present implementation:--- Configuration is Revit-specific through the `MCP_REVIT_` prefix.-- One bridge URL represents one active provider.-- Tool registration and argument translation are largely hard-coded.-- Revit bridge routing is concentrated in `BridgeCommandFactory.cs`.-- Mock mode, workspace restrictions, and JSONL audit logging already exist.-- The bridge binds to loopback, but it does not authenticate local requests.-- Existing Revit tool names and behavior are a public compatibility surface.--The next architecture should extract reusable provider behavior incrementally.-It should not rewrite the working Revit implementation before another provider-proves the abstraction.--## Integration Priority--The recommended order balances user value, API maturity, development friction,-and the ability to test without paid desktop software.--| Order | Integration | Why it belongs here | First useful release |-| --- | --- | --- | --- |-| 1 | IFC and IfcOpenShell | Open, headless, cross-platform, and useful as the interoperability baseline | Read IFC metadata, hierarchy, elements, properties, quantities, geometry summaries, IDS validation, and BCF references |-| 2 | Rhino and Grasshopper | Mature developer APIs and high value for computational design | Inspect the active model, query objects and user text, exchange geometry, run named Grasshopper definitions, and return artifacts |-| 3 | Autodesk Forma Data Management / ACC | Adds projects, documents, published model data, and construction issues | OAuth connection, account/project/file discovery, AEC Data Model queries, issue workflows, and webhooks |-| 4 | Tekla Structures | High-value structural detailing and fabrication workflows | Query model objects, assemblies, profiles, drawings, and selected safe modifications through a local .NET adapter |-| 5 | Navisworks | Strong coordination, aggregation, viewpoints, and clash workflows | Query selection/model tree, manage viewpoints, inspect clash tests, and export coordination data |-| 6 | Archicad | Important authoring platform with an official local JSON automation interface | Project info, elements, properties, classifications, layouts, and selected documentation workflows |-| 7 | Speckle | Useful vendor-neutral data and event layer with Python, .NET, GraphQL, and webhooks | Project/model/version discovery, object transfer, and update-triggered automation |-| 8 | Bentley iTwin | Strategic for infrastructure digital twins, changesets, synchronization, and reality data | iTwin/iModel discovery, changeset queries, synchronization status, and reporting |-| 9 | Trimble Connect | Useful common data environment with file, model, property, and BCF services | Project/file/model access, property sets, BCF topics, and events |-| 10 | Procore | Important construction management platform | Project discovery, document and issue workflows, RFIs, and webhooks |-| 11 | Primavera Cloud / P6 | Important schedule and portfolio data, but not the first modeling connector | Projects, WBS, activities, relationships, progress, and schedule analytics |-| 12 | SketchUp | Broad early-design adoption and a mature in-process Ruby API | Model/entity query, attributes, selection, and controlled geometry operations |-| 13 | Microsoft 365 / Excel | Common operational data source rather than a BIM host | Read and update controlled workbook tables in SharePoint or OneDrive for Business |--This sequence is not a promise to support every product. Each connector should-earn its place through a concrete workflow, test access, and maintainable API-coverage.--## Platform Findings--### OpenBIM Foundation--IfcOpenShell should be the first new provider. Its official documentation-exposes Python and C++ APIs for IFC parsing, authoring, geometry, schema-queries, validation, conversion, BCF, IDS-related testing, cost, scheduling,-clash detection, and other utilities. It can be developed and tested without a-licensed desktop host.--Use IFC as an exchange and validation foundation, not as a forced replacement-for every host application's native data model. Add BCF for issue exchange and-IDS for machine-readable information requirements. Consider bSDD later for-classification and dictionary references.--Official sources:--- [IfcOpenShell documentation](https://docs.ifcopenshell.org/)-- [buildingSMART BCF](https://technical.buildingsmart.org/standards/bcf/)-- [buildingSMART standards and API portfolio](https://www.buildingsmart.org/standards/)--### Rhino and Grasshopper--RhinoCommon is the primary .NET SDK for Rhino plug-ins and Grasshopper-components. Rhino's developer site also documents Python scripting, openNURBS-for `.3dm` file access, Grasshopper APIs, Rhino.Compute, and Hops.--Use a local Rhino plug-in for live document and UI-dependent operations.-Rhino.Compute is a separate HTTP geometry service suited to scalable or-headless geometry calculations. It should be modeled as a job or compute-provider, not as a substitute for all live Rhino document operations.--Official sources:--- [Rhino and Grasshopper developer documentation](https://developer.rhino3d.com/)-- [Rhino API references](https://developer.rhino3d.com/api)-- [Rhino.Compute overview](https://developer.rhino3d.com/guides/compute/compute-faq/)-- [Grasshopper Hops](https://developer.rhino3d.com/guides/compute/hops-component/)--### Tekla Structures--Tekla Structures Open API is a .NET API for plug-ins, macros, and external-applications. The official examples cover model objects, properties, geometry,-cuts, fittings, drawings, and creating structural elements.--Development requires Tekla Structures access and version-specific assembly-references. Keep Tekla SDK dependencies inside a local Windows adapter. The-platform core should communicate with that adapter through a stable,-vendor-neutral transport contract.--Official sources:--- [Tekla Structures Open API getting started](https://developer.tekla.com/documentation/get-started-tekla-structures-open-api)-- [Tekla Developer Center](https://developer.tekla.com/)--### Autodesk Forma and Construction Cloud--Autodesk now presents Forma as an industry cloud with multiple API families.-Do not treat "Forma" as one connector:--- Forma Data Management / Construction Cloud APIs cover files, projects,- issues, reviews, cost, assets, and other construction data.-- AEC Data Model is a GraphQL API for granular cloud-hosted design data and- currently depends on appropriate Forma Data Management access.-- Forma Site Design API is a separate conceptual-design API and is documented- as beta.-- Data Exchange supports selective data exchange between supported products.-- Automation API runs headless Autodesk product engines for batch work.--Start with read-only project, file, issue, and AEC Data Model access. Add writes-only after OAuth scopes, account provisioning, regional behavior, rate limits,-and webhook handling are covered by tests. Treat Automation API calls as-asynchronous jobs with cost and retry metadata.--Official sources:--- [Autodesk Forma APIs](https://aps.autodesk.com/autodesk-forma)-- [Forma / Construction Cloud API overview](https://aps.autodesk.com/en/docs/acc/v1/overview/)-- [AEC Data Model API](https://aps.autodesk.com/en/docs/aecdatamodel/v1/developers_guide/onboarding)-- [Forma Site Design API beta](https://aps.autodesk.com/en/docs/forma/v1)-- [Automation API](https://aps.autodesk.com/en/docs/design-automation/v3)-- [Revit Automation tutorial](https://aps.autodesk.com/en/docs/design-automation/v3/tutorials/revit/)-- [Data Exchange API](https://aps.autodesk.com/apis-and-services/data-exchange-api)--### Navisworks--Navisworks Manage and Simulate include a .NET API and SDK documentation for-plug-ins and applications. A local adapter is appropriate for the active model,-selection, viewpoints, model hierarchy, saved searches, and clash workflows.--Keep Navisworks distinct from APS Model Derivative. Model Derivative is useful-for cloud translation and extraction, while a Navisworks plug-in can interact-with the live desktop coordination session.--Official source:--- [Navisworks API overview](https://aps.autodesk.com/developer/overview/navisworks-api)--### Archicad--Archicad exposes an Automation API through a local JSON interface. Graphisoft's-official Python package communicates with a running Archicad instance over-HTTP. It is a relatively low-friction path for properties, classifications,-layouts, navigator items, and other documented automation commands.--Use the JSON/Python route first. Consider the C++ Add-On API only when a-required workflow cannot be implemented through the automation interface.--Official sources:--- [Archicad JSON interface](https://archicadapi.graphisoft.com/JSONInterfaceDocumentation/)-- [Archicad Python connection](https://archicadapi.graphisoft.com/getting-started-with-archicad-python-connection)-- [Archicad automation technologies](https://archicadapi.graphisoft.com/archicad-extension-and-automation-technologies)--### Cloud and Data Platforms--These platforms should use authenticated cloud providers rather than local-desktop bridges:--- Bentley iTwin provides APIs for iTwins, iModels, changesets,- synchronization, reality data, validation, and reporting.-- Trimble Connect provides cloud APIs for projects, files, models, model- queries, property sets, and BCF-compatible topics.-- Procore provides OAuth 2.0 REST APIs and webhooks for construction workflows.-- Speckle provides GraphQL, Python and .NET SDKs, object transport, viewer- tooling, webhooks, and automation.-- Primavera Cloud and P6 expose REST APIs for project and schedule data.-- Microsoft Graph can read and modify supported Excel workbooks stored in- OneDrive for Business and SharePoint.--Official sources:--- [Bentley iTwin Platform](https://developer.bentley.com/)-- [iModels API](https://developer.bentley.com/apis/imodels-v2/overview/)-- [iTwin Synchronization API](https://developer.bentley.com/apis/synchronization/overview/)-- [Trimble Connect Core API](https://developer.trimble.com/docs/connect/reference/openapi/core/)-- [Trimble Connect Model API](https://developer.trimble.com/docs/connect/reference/openapi/model/)-- [Procore developer documentation](https://developers.procore.com/documentation/introduction)-- [Procore webhooks](https://developers.procore.com/documentation/webhooks)-- [Speckle developer documentation](https://docs.speckle.systems/developers/introduction)-- [Oracle Primavera Cloud REST API](https://docs.oracle.com/en/industries/construction-engineering/primavera-cloud/rest-api/index.html)-- [Primavera P6 EPPM REST API](https://docs.oracle.com/cd/F37125_01/English/Integration_Documentation/rest_api/index.html)-- [Microsoft Graph Excel API](https://learn.microsoft.com/en-us/graph/api/resources/excel?view=graph-rest-1.0)--### SketchUp--SketchUp's Ruby API provides live access to the desktop model and UI. Its-desktop SDK supports file-level `.skp` access under separate access terms. A-small in-process Ruby extension can expose the same local bridge contract used-by other desktop hosts.--Official source:--- [SketchUp Developer Center](https://developer.sketchup.com/)--## Required Architecture Decisions--The next agent should document these decisions before implementing the shared-core.--### 1. Provider Contract--Every provider needs a small common lifecycle:--```text-identity-health-capabilities-execute-shutdown or disconnect-```--The capability manifest should be generated from provider code and include:--- Stable tool name and version.-- Input and output JSON schemas.-- Read-only or mutating classification.-- Required confirmation policy.-- Authentication and entitlement requirements.-- Synchronous or asynchronous execution.-- Supported host and connector versions.-- Expected artifacts and side effects.--Do not maintain separate handwritten catalogs in the MCP layer and connector-layer when one generated manifest can be authoritative.--### 2. Runtime Types--Support four runtime types explicitly:--| Runtime | Examples | Execution characteristics |-| --- | --- | --- |-| Desktop host adapter | Revit, Rhino, Tekla, Navisworks, SketchUp | Separate process boundary, host UI-thread rules, local discovery, version-specific deployment |-| Headless file provider | IfcOpenShell, openNURBS file access | In-process or isolated worker, deterministic fixtures, no desktop UI |-| Cloud provider | Forma/ACC, iTwin, Trimble Connect, Procore, Speckle, Primavera, Microsoft Graph | OAuth, scopes, pagination, rate limits, webhooks, regional endpoints |-| Batch/compute provider | Autodesk Automation, Rhino.Compute | Long-running jobs, polling, cancellation, cost metadata, downloadable artifacts |--One `BridgeClient` implementation may not be sufficient for every runtime, but-the providers should return a consistent result envelope.--### 3. Compatibility--Existing `revit_*` MCP names and `revit.*` bridge routes must continue to work.-Introduce the provider registry behind the current public surface, then migrate-internals in small steps.--New tools should use a stable provider namespace. Avoid duplicating a broad-generic tool set for every product. Prefer provider-native tools, with a small-set of normalized cross-platform operations only where semantics are genuinely-equivalent.--### 4. Object References--Do not design a universal BIM object class before real connectors exist.-Instead, use a reference envelope that can preserve native identity:--```json-{- "provider": "ifc",- "project_id": null,- "model_id": "example.ifc",- "object_id": "12345",- "stable_id": null,- "ifc_guid": "2XQ$n5SLP5MBLyL6JQj8Z0",- "version": null-}-```--Provider-native data remains authoritative. Cross-platform workflows can map-references through IFC GUIDs, external IDs, URNs, Data Exchange identifiers,-or an explicit mapping store.--### 5. Discovery and Local Security--Multiple desktop hosts cannot all assume port `3000`. Define dynamic port-allocation and a local provider registry or discovery mechanism.--Each local adapter should:--- Bind only to loopback.-- Publish its provider, host version, connector version, process ID, endpoint,- and capability digest.-- Use a random per-session bearer token or equivalent nonce.-- Reject stale registrations and requests from unsupported protocol versions.-- Apply request size and concurrency limits.--Do not generalize reflection, arbitrary method invocation, or arbitrary script-execution as cross-provider capabilities. Those operations require a separate,-explicitly enabled high-risk policy.--### 6. Cloud Authentication--Tokens must never appear in MCP tool arguments, model-visible results, audit-logs, or repository configuration.--Use an OS credential store or another established secret backend. Cloud-providers need:--- OAuth authorization code with PKCE for user-delegated access where supported.-- Service-to-service credentials only where the vendor supports the workflow.-- Scoped account and project selection.-- Refresh, revocation, and expiry handling.-- Pagination, retries with jitter, rate-limit handling, and regional endpoints.-- Redacted structured logging.--### 7. Mutations and Jobs--Mutating tools need:--- Preview or dry-run where practical.-- Explicit confirmation metadata.-- Transaction or undo integration where the host supports it.-- Idempotency keys for cloud writes and retried requests.-- Before/after references and audit records.--Long-running operations should return a job reference with status, progress,-warnings, artifacts, cancellation support, and terminal error details.--### 8. Licensing Boundary--The current GPL linking exception is specific to Autodesk Revit. It should not-be assumed to cover Rhino, Tekla, Navisworks, Archicad, SketchUp, or other-proprietary SDKs.--Before distributing another desktop connector:--- Review the vendor SDK and marketplace terms.-- Keep proprietary SDK binaries out of the repository unless redistribution is- expressly allowed.-- Prefer references to assemblies installed with the host product.-- Decide whether a connector-specific exception or a broader host-application- linking exception is required.-- Obtain qualified legal review before publishing revised exception language.--Cloud REST integrations also require review of API terms, branding rules,-commercial-use limits, and data retention requirements.--## Recommended Repository Direction--The exact package names belong in the architecture decision, but ownership-should move toward these boundaries:--```text-packages/- aec-model-bridge-core/ provider contracts, registry, policy, audit- aec-model-bridge-mcp/ MCP composition and compatibility aliases- mcp-server-revit/ existing package during migration- revit-bridge-addin/ existing Revit desktop adapter- connector-ifc/ first headless provider- connector-rhino/ future local host adapter- connector-autodesk-forma/ future OAuth cloud provider- connector-tekla/ future local host adapter-```--Do not create all of these directories immediately. Add a package only when it-contains an implemented provider, tests, and documentation.--Cross-provider workflows belong in the orchestration layer. Connectors should-remain thin translators around vendor APIs and should not call each other-directly.--## First Implementation Slice--The first implementation after the architecture decision should deliver:--1. A typed provider protocol and capability manifest.-2. A provider registry with one fake provider for contract tests.-3. A compatibility adapter around the existing Revit bridge client.-4. An IfcOpenShell provider with read-only tools:- - Health and library version.- - Open/close or scoped file session.- - File schema, header, units, and georeferencing summary.- - Spatial hierarchy.- - Element query by IFC class, GUID, name, and property criteria.- - Property sets and quantities.- - Geometry or bounding-box summary without returning oversized meshes by- default.- - IFC validation and structured findings.-5. Small IFC fixtures covering IFC2X3 and IFC4 when licensing permits.-6. Contract, security, schema, and regression tests.-7. Documentation showing existing Revit configuration and the new- multi-provider configuration side by side.--Writes, geometry authoring, BCF creation, and IDS workflows should follow only-after the read-only provider is stable.--## Acceptance Criteria--The architecture foundation is complete when:--- Existing Revit clients work without tool-name or configuration regressions.-- Provider discovery is data-driven rather than another central switch table.-- A fake provider and the Revit compatibility adapter pass the same contract- tests.-- IFC tools work without Revit or any licensed desktop application.-- Mutating, high-risk, and asynchronous capabilities are represented in the- manifest even if the first IFC release is read-only.-- Local provider requests are authenticated and use collision-free endpoints.-- Cloud credential interfaces exist only when a cloud provider is implemented.-- Tests cover malformed manifests, unavailable providers, stale discovery- records, path traversal, oversized requests, and redacted logs.-- The Python suite passes and Revit 2024 through 2027 add-in builds remain- successful.--## Evidence Limits--Vendor APIs, product names, entitlements, beta status, pricing, and marketplace-rules change. This research establishes a direction, not a substitute for-checking the official documentation during implementation.--Some integrations cannot be verified fully without paid accounts or installed,-licensed desktop applications. Keep those tests behind explicit live-test-flags and record the exact product version, account entitlement, region, and-date used for each verification.diff --git a/docs/next-chapter.md b/docs/next-chapter.mddeleted file mode 100644index 9699cb8..0000000--- a/docs/next-chapter.md+++ /dev/null@@ -1,154 +0,0 @@-# Chapter 2 — From Machine to Mainstream--**Status:** Roadmap chapter (v1.0, 2026-06-13)-**Companion docs:** `docs/agent-task-plan.md` v1.1 (the canonical backlog — all task cards live THERE, this doc never duplicates card text), `docs/system-blueprint-and-workflows.md` (architecture), root `PROMPT.md` + `AGENT.md` (Ralph loop files).-**Purpose:** Record the 2026-06-13 program review, the roadmap amendments it produced, the strategy for Chapter 2 (Phases H + I), and the dispatch kit for delegating the whole backlog to building agents.-------## 1. Where the program stands (review verdict, 2026-06-13)--| Layer | State |-| --- | --- |-| Revit switch (C# add-in, 2024–2027) | **5/5** — operational, ~103 routes |-| Hub tool surface | **Real** — 157 MCP tools across 10 providers, 12 test suites, CI green incl. catalog drift check |-| IFC / graph / mapper / exporter / jobs | **4/5** — working headless core |-| Speckle / APS cloud providers | **3/5** — working, consolidation in flight (A1) |-| Navisworks switch | **1/5** — health-only stub |-| Orchestrator (recipes, Run Records, policy, discovery) | **0/5 — pure blueprint.** This is the entire value thesis and none of it is code yet |-| Phase A | 1 done (A0), 4 in flight (A1/A3/A5/A8), 4 open, 2 human |--**Verdict:** the switch layer is ahead of plan; the orchestration layer is the critical path; and the roadmap had a blind spot — it assumed MCP-native developer clients (Claude Desktop, VS Code) and had **no path for the average BIM professional using ChatGPT, Copilot, Gemini, or a local model, and no non-developer install story.** Chapter 2 closes that.--## 2. What the review changed (amendments to the v1.0 plan)--1. **Phase H added — Any-AI Access Layer (H1–H8).** Four doors into the hub: MCP stdio (today), remote MCP over Streamable HTTP (the universal door — Claude, ChatGPT connectors, Copilot Studio, Gemini all speak it as of 2026), a REST/OpenAPI facade (custom GPT Actions, n8n, Power Automate, Zapier), and a bundled bring-your-own-LLM chat console that works fully offline with Ollama. Plus `aec-bridge connect` config generation and a 10-minute non-developer install.-2. **Phase I added — Popularity Pack (I1–I8),** research-ranked by popularity × ease. Headline findings from the 2026-06 ecosystem scan: desktop Revit MCP is **commoditized** (Revit 2027 ships a built-in MCP server; many community servers exist); **BCF has zero MCP bridges anywhere** — an open killer-demo gap we can own; Archicad's Tapir JSON API makes that bridge nearly free; headless no-Blender IFC (which we already have) is itself a marketable wedge.-3. **Strategic position sharpened:** wrap, don't compete. The defensible "orchestration bed" is the **neutral coordination layer** — IFC + BCF + Speckle + clash + cross-tool identity + Run Records — that no vendor will build across competitors' tools. I8 (ADR 0006) encodes coexistence with Autodesk's own MCP servers; E5's APS work should wrap official Autodesk MCPs where they exist rather than re-implement.-4. **G1 (Archicad) promoted** from spec-only to implementation (I5).-5. **Early dispatch note:** I1 (BCF) depends only on A8 — it does not need to wait for Phases B–C and should be dispatched early; it is the cheapest high-visibility win in the whole backlog.-6. **Ralph loop made turnkey:** root `PROMPT.md` (loop prompt, re-read fresh every iteration) and `AGENT.md` (accumulated learnings file) now exist, so any loop runner can drive the backlog unattended.-7. **Performance posture decided (A11 → ADR 0007):** the hub stays **Python**; no C/Rust rewrite. Hub latency is dominated by the host applications (Revit API calls run on Revit's UI thread), network, and disk — not the interpreter — and the Python ecosystem (MCP SDK, IfcOpenShell, specklepy, ifctester, pyarrow/DuckDB) is the project's moat. The genuinely hot paths already execute in native code (IfcOpenShell's C++ core, Arrow/DuckDB). Escape hatch: a single profiled module may drop to Rust/C++ as a Python extension (PyO3), never a rewrite. The parts running *inside* the software are already native C# add-ins.--## 3. Chapter 2 thesis--Chapter 1 (Phases A–G) builds the machine: switches, contract, orchestrator, data plane, distribution. Chapter 2 makes the machine reachable: **any AI the user already has (Phase H) × the bridges most likely to spread by word of mouth (Phase I).** The end-state demo that proves the vision: a BIM coordinator with no developer tools installs the bridge in 10 minutes, connects it to whatever AI account they have (or a free local model), says "check this federated model and file the clashes," and gets a health score, a BCF file their team's tools can open, and a 3D viewer link they can email — across Revit, Navisworks, Rhino, Archicad, and plain IFC.--Phase ordering stays honest: H and I sit **after** their dependencies (policy B14, workflow tools C6, Run Records C7), not before — exposing 157 raw tools to the open internet without the policy layer would be the wrong kind of popular. The only Chapter 2 card safe to run early is I1 (BCF), plus the two ADRs (H1, I8) once B14's semantics are settled.--## 4. Dispatch kit (hand this section to building agents)--### Mode 1 — Ralph loop (one agent, sequential)--Run any loop harness against root `PROMPT.md`, e.g.:--```powershell-while ($true) { Get-Content PROMPT.md -Raw | claude -p --dangerously-skip-permissions }-```--The prompt enforces: one card per iteration, search-before-assume, no placeholders, verify-before-done, marker + Progress Log update, learnings appended to `AGENT.md`, commit per task on `task/<id>`. Babysit the first few loops and add guardrail lines to `PROMPT.md` when the agent misbehaves (tune the prompt, not the output).--### Mode 2 — GSD parallel lanes (multiple agents, worktrees)--One agent per lane in separate worktrees; lanes touch disjoint files (see lane table in `agent-task-plan.md` §0). Brief each agent with: `docs/agent-task-plan.md` + "work ONLY lane `<X>`, one card at a time, same rules as PROMPT.md". Suggested waves:--- **Wave 0 (now):** merge in-flight A1/A3/A5/A8 branches → dispatch A2, A4, A6, A7 (PY/DOCS) ∥ B1 ADR (DOCS) ∥ I1 BCF (PY).-- **Wave 1:** B2/B3/B12/B13/B14 (PY) ∥ B4→B5 (NET, split B4 first) ∥ B6→B9 (NET) ∥ F2 docs site (DOCS).-- **Wave 2:** C1→C8 (PY, mostly sequential) ∥ B10/B11/B15 ∥ F1 (NET) ∥ H1 + I8 ADRs (DOCS).-- **Wave 3:** C9–C12 recipes ∥ D1/D5 ∥ I2/I3/I4 ∥ H2→H3→H4 + H6.-- **Wave 4:** D2–D4 ∥ H5/H7/H8 ∥ I5/I6/I7 ∥ F3/F6/F7 ∥ E-phase ∥ G specs.-- **Human queue (anytime):** A9, A10, C13, E4/E5/E8 sub-steps, F5, H8 VM run.--### Short-form task index (one line per open card; full cards are canonical in `agent-task-plan.md`)--```text-A2 PY S pin specklepy>=3,<4 and fix API drift-A4 PY S register McpProxyProvider + MCP_PROXY_TARGETS Rhino pairing docs-A6 DOC S fix stale architecture/security docs ("25 tools" etc.)-A7 PY S delete stray .3dm, gitignore build dirs, dist/ policy-A11 DOC S ADR 0007: Python-first perf posture + budgets + perf smoke test-B1 DOC M ADR 0002: Switch Contract v2 (registry file, tokens, /capabilities)-B2 PY M discovery registry reader (scan, validate, prune, discover_switches)-B3 PY S bearer-token client + legacy fixed-port fallback-B4 NET L Revit add-in: [BridgeCommand] attributes → /capabilities manifest-B5 NET M Revit add-in: dynamic port + token + registry file runtime-B6 NET M Navisworks: attribute command routing infrastructure-B7 NET M Navisworks routes: doc info, model tree, selection, append-B8 NET S Navisworks routes: saved viewpoints-B9 NET L Navisworks routes: Clash Detective (tests, run, paged results)-B10 NET S Navisworks: Contract v2 runtime (port from B5)-B11 PY M NavisworksProvider + mock clash fixtures + tests-B12 PY S aec_bridge_status diagnostic tool-B13 PY S aec-bridge doctor CLI-B14 PY M policy layer: allowed_tools, destructive gates, high-risk flag-B15 PY S redaction + abuse-case test extension-C1 PY M ADR 0003 + Pydantic recipe schema-C2 PY S capability naming layer + resolve_capability()-C3 PY M engine core: steps, bindings, job pipeline-C4 PY S capability fallbacks + degradation records-C5 PY M confirmation gates, idempotency keys, dry-run-C6 PY S workflow_* MCP tools + progress notifications-C7 PY M Run Record schema v1 + builder + runs/ output-C8 PY M identity map → SQLite persistence + auto-registration-C9 PY M recipe W1 concept-to-BIM (Rhino→Revit) mock e2e-C10 PY S recipe W2 coordination loop (clash, fallback graph)-C11 PY M recipe W3 model health (zero-switch IFC) mock e2e-C12 PY S recipe W4 data-lake drop (Speckle/Parquet)-D1 PY M Run Record → Parquet/DuckDB lake exporter-D2 DOC S lakehouse layout doc + 5 DuckDB queries-D3 BI M Power BI template: model health-D4 BI M Power BI template: coordination-D5 PY M ifc_validate_ids via ifctester + fixtures-D6 PY M completion webhooks (Teams/Slack cards)-D7 PY S graph_export_graphml-E1 PY M Excel headless provider (openpyxl tables, sandboxed)-E2 PY M excel_diff_table + gated write-back-E3 PY M recipe W5 QTO round-trip mock e2e-E4 PY L Excel via Microsoft Graph (OAuth)-E5 PY M APS AEC Data Model GraphQL reads-E6 PY M acc_create_issue + W2 publish_issues: acc-E7 PY M ACC webhooks → auto-trigger recipes-E8 PY M Solibri spike → ADR 0004 (REST vs plugin vs file-exchange)-E9 ?? L Solibri switch per ADR 0004-E10 PY S Solibri findings into W3 health score-F1 NET M switch SDK template (csharp echo switch)-F2 DOC M MkDocs site + GitHub Pages deploy-F3 DOC M zero-switch 10-min tutorial + aec-bridge demo-F4 PY/NET M release automation per switch + checksums-F6 BI S samples/ pack (IFC, massing, recipes, baked lake)-F7 DOC S README rewrite around orchestration story-F8 DOC S Rhino native plugin ADR (proxy-first verdict)-G1 PY M Archicad Tapir spike (impl promoted to I5)-G2–G7 DOC S spec cards: Tekla, SketchUp, iTwin, Trimble, Procore, P6-H1 DOC M ADR 0005: four-door access layer + key/scope model-H2 PY M remote MCP endpoint (Streamable HTTP) + API keys-H3 PY M REST facade + generated OpenAPI + GPT-Action/n8n howto-H4 PY S aec-bridge connect: per-client config generator-H5 PY L BYO-LLM chat console (OpenAI-compatible incl. Ollama)-H6 PY M workflow_validate + recipe JSON Schema + authoring prompt-H7 PY M remote hardening: bind policy, rate limits, key rotation-H8 PY/NET M one-line Windows install → doctor → connect (≤10 min)-I1 PY M BCF 2.1/3.0 provider (read/write topics+viewpoints) ← EARLY, only needs A8-I2 PY S W2 clash → BCF publishing (killer demo)-I3 PY M IFC→glTF + self-contained HTML viewer artifact-I4 PY S aec_describe_model LLM-ready digest-I5 PY M Archicad provider via Tapir schema-generated tools-I6 PY M gh_run_definition via Rhino.Compute-I7 PY M drop-folder watcher → auto-run recipe-I8 DOC M ADR 0006: Revit 2027 built-in MCP coexistence (wrap, don't compete)-HUMAN: A9 licensing · A10 repo rename · C13 live runs · E4/E5/E8 accounts · F5 App Store · H8 VM evidence-```--### Rules every dispatched agent must follow--The 10 Standing Rules in `agent-task-plan.md` §2, plus the loop discipline baked into `PROMPT.md`: one card per run · search the codebase before assuming something is missing · no placeholder or stubbed implementations · the card's Verify command must pass before marking `[x]` · append non-obvious learnings to `AGENT.md` · commit per task, never to `main`.--## 5. Critical path--A-merge → B1 → B2/B14 → C1→C6/C7 → (C9–C12 ∥ H1→H2/H3) → H5/H8 + I2/I3. Everything else hangs off this spine in parallel lanes. The two cards most likely to need splitting before dispatch: B4 (annotate ~103 routes) and H5 (console UI).-------**Changelog**--- 2026-06-13 — v1.0 — Chapter authored from the 2026-06-13 program review + ecosystem research; companion to agent-task-plan v1.1.diff --git a/docs/tools.md b/docs/tools.mddeleted file mode 100644index 88b64f1..0000000--- a/docs/tools.md+++ /dev/null@@ -1,605 +0,0 @@-# Tool Catalog--> [!WARNING]-> This is a legacy document covering the original 26 tools.-> The complete generated catalog of all current tools lives in [tools-generated.md](tools-generated.md).--AEC Model Bridge exposes tools for health checks, document operations, QA audits, export operations, and automation workflows.--All tools accept JSON inputs validated against Pydantic schemas and return structured JSON responses.--## Tool Categories--- [Health & Status](#health--status)-- [Document Operations](#document-operations)-- [QA & Audits](#qa--audits)-- [Export Operations](#export-operations)-- [Sheet Automation](#sheet-automation)-- [Baseline Tracking](#baseline-tracking)-------## Health & Status--### revit.health--**Purpose**: Check bridge connectivity and server health--**Input Schema**:-```json-{- "request_id": "req_001",- "check_interval": 30-}-```--| Field | Type | Required | Description |-|-------|------|----------|-------------|-| `request_id` | string | Yes | Unique request identifier |-| `check_interval` | integer | No | Seconds between retries (default: 30) |--**Output Schema**:-```json-{- "status": "healthy",- "requests_handled": 1,- "message": "Bridge ready"-}-```--| Field | Type | Description |-|-------|------|-------------|-| `status` | enum | `healthy`, `degraded`, or `failing` |-| `requests_handled` | integer | Request count since startup |-| `message` | string | Human-readable status message |--**Example Request/Response**:-```json-// Request-{- "tool": "revit.health",- "payload": {- "request_id": "health_check_001"- }-}--// Response-{- "status": "healthy",- "requests_handled": 42,- "message": "Bridge connectivity is verified."-}-```-------## Document Operations--### revit.open_document--**Purpose**: Open a Revit document (.rvt or .rfa)--**Input Schema**:-```json-{- "request_id": "req_002",- "file_path": "C:\\workspace\\project.rvt",- "detach": false-}-```--| Field | Type | Required | Description |-|-------|------|----------|-------------|-| `request_id` | string | Yes | Unique request identifier |-| `file_path` | string | Yes | Absolute path to Revit document (must be in allowed directories) |-| `detach` | boolean | No | Detach from central (default: false) |--**Output Schema**:-```json-{- "document_id": "project",- "title": "project.rvt",- "model_path": "C:\\workspace\\project.rvt"-}-```--**Example Request/Response**:-```json-// Request-{- "tool": "revit.open_document",- "payload": {- "request_id": "open_001",- "file_path": "C:\\workspace\\hospital_model.rvt",- "detach": true- }-}--// Response-{- "document_id": "hospital_model",- "title": "hospital_model.rvt",- "model_path": "C:\\workspace\\hospital_model.rvt"-}-```--### revit.list_views--**Purpose**: List all views in the active or specified document--**Input Schema**:-```json-{- "request_id": "req_003",- "document_id": null-}-```--| Field | Type | Required | Description |-|-------|------|----------|-------------|-| `request_id` | string | Yes | Unique request identifier |-| `document_id` | string | No | Document ID (null = active document) |--**Output Schema**:-```json-{- "views": [- {- "view_id": "view-1",- "name": "Floor Plan - Level 1",- "discipline": "Architectural"- }- ]-}-```--**Example Request/Response**:-```json-// Request-{- "tool": "revit.list_views",- "payload": {- "request_id": "list_views_001"- }-}--// Response-{- "views": [- {"view_id": "view-1", "name": "Floor Plan", "discipline": "Architectural"},- {"view_id": "view-2", "name": "Ceiling Plan", "discipline": "Mechanical"}- ]-}-```-------## QA & Audits--All audit tools share a common input/output schema.--**Common Input Schema**:-```json-{- "request_id": "req_004",- "document_id": null-}-```--**Common Output Schema**:-```json-{- "issues_found": 0,- "severity": "info"-}-```--### revit.model_health_summary--**Purpose**: Generate overall model health report (warnings, errors, performance)--### revit.warning_triage_report--**Purpose**: Categorize and prioritize Revit warnings--### revit.naming_standards_audit--**Purpose**: Validate element names against naming conventions--### revit.parameter_compliance_audit--**Purpose**: Check required parameters are populated--### revit.shared_parameter_binding_audit--**Purpose**: Verify shared parameter bindings and consistency--### revit.view_template_compliance_check--**Purpose**: Audit views for template application--### revit.tag_coverage_audit--**Purpose**: Identify untagged elements--### revit.room_space_completeness_report--**Purpose**: Check room/space data completeness--### revit.link_monitor_report--**Purpose**: Audit linked file status and paths--### revit.coordinate_sanity_check--**Purpose**: Validate project coordinates and survey points--**Example Request/Response** (any audit tool):-```json-// Request-{- "tool": "revit.naming_standards_audit",- "payload": {- "request_id": "audit_001"- }-}--// Response-{- "issues_found": 12,- "severity": "warning"-}-```-------## Export Operations--### revit.export_schedules--**Purpose**: Export schedules to CSV files--**Input Schema**:-```json-{- "request_id": "req_005",- "output_path": "C:\\workspace\\exports\\schedules.csv"-}-```--**Output Schema**:-```json-{- "schedules": ["Door Schedule", "Window Schedule"],- "output_path": "C:\\workspace\\exports\\schedules.csv"-}-```--**Example**:-```json-// Request-{- "tool": "revit.export_schedules",- "payload": {- "request_id": "export_sched_001",- "output_path": "C:\\workspace\\door_schedule.csv"- }-}--// Response-{- "schedules": ["Door Schedule"],- "output_path": "C:\\workspace\\door_schedule.csv"-}-```--### revit.export_quantities--**Purpose**: Export material quantities/takeoffs to CSV--**Input Schema**:-```json-{- "request_id": "req_006",- "output_path": "C:\\workspace\\quantities.csv"-}-```--**Output Schema**:-```json-{- "categories_exported": 5,- "output_path": "C:\\workspace\\quantities.csv"-}-```--### revit.export_pdf_by_sheet_set--**Purpose**: Export sheets to PDF based on sheet set configuration--**Input Schema**:-```json-{- "request_id": "req_007",- "csv_path": "C:\\workspace\\sheet_config.csv"-}-```--**Output Schema**:-```json-{- "file_path": "C:\\workspace\\export.pdf",- "status": "success"-}-```--### revit.export_dwg_by_sheet_set--**Purpose**: Export sheets to DWG format--**Input Schema**: Same as PDF export--**Output Schema**:-```json-{- "file_path": "C:\\workspace\\export.dwg",- "status": "success"-}-```--### revit.export_ifc_named_setup--**Purpose**: Export model to IFC using named export configuration--**Input Schema**:-```json-{- "request_id": "req_008",- "csv_path": "C:\\workspace\\ifc_config.csv"-}-```--**Output Schema**:-```json-{- "file_path": "C:\\workspace\\setup.ifc",- "status": "success"-}-```--### revit.export_report--**Purpose**: Generate comprehensive export summary report--**Input Schema**: Standard audit input--**Output Schema**: Standard audit output-------## Sheet Automation--### revit.batch_create_sheets_from_csv--**Purpose**: Create multiple sheets from CSV specification--**Input Schema**:-```json-{- "request_id": "req_009",- "csv_path": "C:\\workspace\\sheets.csv"-}-```--CSV format:-```csv-sheet_number,sheet_name,titleblock-A101,Floor Plan Level 1,A0 Titleblock-A102,Floor Plan Level 2,A0 Titleblock-```--**Output Schema**:-```json-{- "sheets_created": 3-}-```--### revit.batch_place_views_on_sheets--**Purpose**: Automatically place views on sheets--**Input Schema**: Standard audit input--**Output Schema**: Standard audit output--### revit.titleblock_fill_from_csv--**Purpose**: Populate titleblock parameters from CSV data--**Input Schema**: Standard audit input--**Output Schema**: Standard audit output--### revit.create_print_set--**Purpose**: Create a print set (collection of sheets)--**Input Schema**: Standard audit input--**Output Schema**: Standard audit output-------## Baseline Tracking--### revit.baseline_export--**Purpose**: Export model state snapshot for comparison--**Input Schema**:-```json-{- "request_id": "req_010",- "output_path": "C:\\workspace\\baseline.json"-}-```--**Output Schema**:-```json-{- "snapshot_id": "baseline-2025-01-07T10:30:00",- "output_path": "C:\\workspace\\baseline.json"-}-```--**Example**:-```json-// Request-{- "tool": "revit.baseline_export",- "payload": {- "request_id": "baseline_001",- "output_path": "C:\\workspace\\baseline_v1.json"- }-}--// Response-{- "snapshot_id": "baseline-2025-01-07T14:22:33.123456",- "output_path": "C:\\workspace\\baseline_v1.json"-}-```--### revit.baseline_diff--**Purpose**: Compare two baseline snapshots and report differences--**Input Schema**:-```json-{- "request_id": "req_011",- "baseline_a": "C:\\workspace\\baseline_v1.json",- "baseline_b": "C:\\workspace\\baseline_v2.json"-}-```--**Output Schema**:-```json-{- "differences": [- "10 elements added",- "5 parameters changed",- "2 views deleted"- ]-}-```-------## Package Builder--### revit.publish_package_builder--**Purpose**: Generate Revit package (.rfa, .addin, or custom package) for distribution--**Input Schema**: Standard audit input--**Output Schema**: Standard audit output-------## Common Patterns--### Request IDs-All tools require a `request_id` field for audit log correlation. Use unique identifiers:-```json-{- "request_id": "workflow_001_step_02"-}-```--### File Paths-All file paths must:-- Be absolute paths (not relative)-- Fall within configured `allowed_directories`-- Use forward slashes or escaped backslashes: `C:/workspace` or `C:\\workspace`--Invalid paths raise `WorkspaceViolation` errors.--### Error Handling-Failed tool invocations return error responses:-```json-{- "error": "WorkspaceViolation",- "message": "Path outside allowed directories: C:\\system32\\file.txt"-}-```--Common errors:-- `WorkspaceViolation`: File path outside sandbox-- `SchemaValidationError`: Invalid input format-- `BridgeError`: Bridge communication failure-- `RevitMCPError`: General tool execution error--### Mock vs Bridge Mode--In **mock mode**, tools return deterministic stub data without Revit:-```json-{- "status": "healthy",- "message": "Bridge ready"-}-```--In **bridge mode**, tools execute real Revit API operations:-```json-{- "status": "healthy",- "revit_version": "2024",- "message": "Connected to Revit 2024"-}-```-------## Full Tool List Summary--| Tool | Category | Purpose |-|------|----------|---------|-| `revit.health` | Health | Check bridge status |-| `revit.open_document` | Document | Open Revit file |-| `revit.list_views` | Document | List all views |-| `revit.model_health_summary` | QA | Overall health report |-| `revit.warning_triage_report` | QA | Categorize warnings |-| `revit.naming_standards_audit` | QA | Validate naming |-| `revit.parameter_compliance_audit` | QA | Check parameters |-| `revit.shared_parameter_binding_audit` | QA | Audit shared params |-| `revit.view_template_compliance_check` | QA | View template audit |-| `revit.tag_coverage_audit` | QA | Untagged elements |-| `revit.room_space_completeness_report` | QA | Room/space data |-| `revit.link_monitor_report` | QA | Linked file audit |-| `revit.coordinate_sanity_check` | QA | Coordinate validation |-| `revit.export_schedules` | Export | Export schedules to CSV |-| `revit.export_quantities` | Export | Export quantities to CSV |-| `revit.export_pdf_by_sheet_set` | Export | Export sheets to PDF |-| `revit.export_dwg_by_sheet_set` | Export | Export sheets to DWG |-| `revit.export_ifc_named_setup` | Export | Export model to IFC |-| `revit.export_report` | Export | Export summary report |-| `revit.baseline_export` | Baseline | Create snapshot |-| `revit.baseline_diff` | Baseline | Compare snapshots |-| `revit.batch_create_sheets_from_csv` | Sheet | Create sheets from CSV |-| `revit.batch_place_views_on_sheets` | Sheet | Place views on sheets |-| `revit.titleblock_fill_from_csv` | Sheet | Fill titleblocks from CSV |-| `revit.create_print_set` | Sheet | Create print set |-| `revit.publish_package_builder` | Package | Build distribution package |-------## Schema Reference--All schemas are defined in [schemas.py](../packages/mcp-server-revit/src/revit_mcp_server/schemas.py) using Pydantic models.--Tool handler implementations are in [handlers.py](../packages/mcp-server-revit/src/revit_mcp_server/tools/handlers.py).--For client configuration examples, see [MCP marketplaces and clients](marketplaces.md).