From 2294aec431364a6fc2c7a0b36051e4c3f189285d Mon Sep 17 00:00:00 2001
From: Abhinaysai Kamineni <66816045+askmy-stack@users.noreply.github.com>
Date: Sun, 2 Aug 2026 22:07:11 -0400
Subject: [PATCH] Sync architecture.md with shipped capture, probes, and
 adapters.

Reflect stdio MCP capture as supported, document probes/policy/config/
adapters/Action components, and call out remaining planned work.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/architecture.md | 44 +++++++++++++++++++++++++++++++++-----------
 1 file changed, 33 insertions(+), 11 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index 6077c03..10c26b3 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,6 +1,6 @@
 # Architecture
 
-Tool-Semantics separates **transport**, **normalization**, and **compatibility analysis** so the same diff engine can run on static manifests today and live MCP servers tomorrow.
+Tool-Semantics separates **transport**, **normalization**, and **compatibility analysis** so the same diff engine can run on static manifests and live MCP servers.
 
 ## Pipeline
 
@@ -8,25 +8,31 @@ Tool-Semantics separates **transport**, **normalization**, and **compatibility a
 flowchart TB
   subgraph inputs
     M[JSON tool manifest]
-    L[Live MCP server — planned]
+    L[Live MCP server — stdio supported]
+    SSE[Live MCP SSE — stubbed]
   end
   subgraph core
-    S[Scanner / capture]
+    S[Scanner / mcp_capture]
     N[InterfaceSnapshot]
     D[Diff engine]
+    P[Probes / policy]
+    A[Migration adapters]
     R[CompatibilityReport]
   end
   subgraph outputs
     CLI[Rich CLI table]
     MD[Markdown report]
     JSON[JSON artifact]
-    CI[Exit codes for CI]
+    CI[Exit codes / GitHub Action]
   end
   M --> S
-  L -.-> S
+  L --> S
+  SSE -.-> S
   S --> N
   N --> D
   D --> R
+  P --> R
+  A -.-> R
   R --> CLI
   R --> MD
   R --> JSON
@@ -37,15 +43,31 @@ flowchart TB
 
 | Component | Role |
 | --- | --- |
-| **Scanner** (`scanner.py`) | Import an interface and emit a versioned snapshot |
-| **Models** (`models.py`) | Normalized server metadata and tool contracts |
+| **Scanner** (`scanner.py`) | Import a static interface / manifest and emit a versioned snapshot |
+| **Live MCP capture** (`mcp_capture.py`) | Capture tools over **stdio** MCP (JSON-RPC); SSE is intentionally stubbed |
+| **Models** (`models.py`) | Normalized server metadata and tool contracts (`InterfaceSnapshot`) |
 | **Diff engine** (`diff.py`) | Stable change codes + severity levels |
+| **Probes** (`probes.py`) | Offline behavioral expectations (positive / side-effect / confirmation) |
+| **Release policy** (`policy.py`) | Configurable CI gate thresholds for severity |
+| **Config** (`config.py`) | TOML/YAML project config (ignore rules, policy overrides) |
+| **Migration adapters** (`adapters.py`) | Tool aliases, argument/enum maps, output wrappers |
 | **Report** (`report.py`) | Human-readable Markdown / styling helpers |
-| **CLI** (`cli.py`) | `capture` and `compare` entry points |
-| **Behavioral runner** | Planned model-provider-neutral probe runner |
-| **Adapter generator** | Planned compatibility aliases and transforms |
+| **CLI** (`cli.py`) | `capture`, `capture-mcp`, `compare`, and related entry points |
+| **GitHub Action** (`.github/actions/compare`) | CI compare + optional PR comment |
 
-See [change-codes.md](change-codes.md) for the full catalog of stable `Change.code` values.
+### Still planned
+
+- **Model-backed behavioral runners** — LLM-driven probe execution (M4 matrix)
+- **SSE live MCP transport** — beyond the current stub
+- Broader adapter / matrix automation beyond the shipped declarative adapters
+
+## Related docs
+
+- [change-codes.md](change-codes.md) — stable `Change.code` catalog
+- [adapters.md](adapters.md) — migration adapter model and examples
+- [adr-live-mcp-capture.md](adr-live-mcp-capture.md) — stdio-first live capture ADR
+- [config.md](config.md) — project configuration
+- [github-action.md](github-action.md) — composite Action usage
 
 ## Severity model