Skip to content

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

docs: consolidate roadmap and remove obsolete task files

A. Sam Mohammad8a6da9dc63e3
diff --git a/AGENT-TASK-A1.md b/AGENT-TASK-A1.md
deleted file mode 100644
index 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.md
deleted file mode 100644
index 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.md
deleted file mode 100644
index 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.md
deleted file mode 100644
index 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.md
deleted file mode 100644
index 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.md
index 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.md
deleted file mode 100644
index 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.md
deleted file mode 100644
index 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.md
deleted file mode 100644
index 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.md
deleted file mode 100644
index 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.md
deleted file mode 100644
index 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.md
deleted file mode 100644
index 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).