Align UCP docs with A2A-only checkout transport

AGENTS.md

@@ -54,8 +54,8 @@ Use when working on discovery, capability negotiation, UCP status lifecycle, or
 
 Validate:
 - Statuses: `incomplete`, `requires_escalation`, `ready_for_complete`, `complete_in_progress`, `completed`, `canceled`
-- Headers: `UCP-Agent`, `API-Version`, `Idempotency-Key`
-- A2A methods: `a2a.ucp.checkout.create|get|update|complete|cancel`
+- Headers: `UCP-Agent`, `X-A2A-Extensions`
+- A2A method/action contract: JSON-RPC `message/send` with `create_checkout|get_checkout|update_checkout|complete_checkout|cancel_checkout`
 - Discovery contract: `/.well-known/ucp`
 
 Note: Merchant Activity ACP/UCP tabs switch backend protocol behavior. Apps SDK mode remains ACP-only.

docs/PRD.md

@@ -19,9 +19,9 @@ The platform implements **both protocols** to demonstrate production-grade comme
 
 Both protocols share the same intelligent agent layer (NAT-powered Promotion, Recommendation, and Post-Purchase agents) and backend services, showcasing how merchants can support multiple protocols simultaneously without duplicating business logic.
 
-**Protocol Toggle:** The Merchant Activity Panel provides a **tab switcher (ACP | UCP)** to toggle between protocols. The client agent flow remains unchanged - only the backend endpoints and protocol format change based on the toggle.
+**Protocol Toggle:** The Merchant Activity Panel provides a **tab switcher (ACP | UCP)** to toggle between protocols. The client agent flow remains unchanged - only the backend transport and protocol format change based on the toggle.
 
-**UCP scope in this project:** UCP support includes **Discovery + Checkout (REST + A2A)**. The A2A transport uses JSON-RPC 2.0 for agent-to-agent communication. Cart/Order/Identity Linking capabilities and MCP/Embedded transports are out of scope for this reference implementation.
+**UCP scope in this project:** UCP support includes **Discovery + Checkout over A2A only**. The A2A transport uses JSON-RPC 2.0 for agent-to-agent communication through `POST /a2a`. REST, Cart/Order/Identity Linking capabilities, MCP, and Embedded transports are out of scope for this reference implementation.
 
 ### The Technical Vision
 
@@ -41,7 +41,7 @@ For this project we will also build a **client agent simulator** that behaves li
 
 * **Implementation**: Static simulator with 4 pre-populated products
 * **Search Flow**: User enters prompt (e.g., "find some t-shirts") → displays 4 product cards with images
-* **Checkout Flow**: User clicks a product → initiates ACP checkout via `POST /checkout_sessions`
+* **Checkout Flow**: User clicks a product → initiates checkout through the selected protocol (ACP REST via `POST /checkout_sessions` or UCP A2A via `POST /a2a`)
 
 ## 1. Goals & Background Context
 
@@ -350,9 +350,9 @@ A "Glass Box" dashboard built with Next.js to visualize the underlying protocol
 
 ## 5. UCP Integration Requirements
 
-### 5.1 UCP Core Endpoints (Per Official Specification)
+### 5.1 UCP Discovery and A2A Transport
 
-Implement UCP-compliant endpoints alongside existing ACP endpoints (API Version: `2026-01-11`):
+Implement UCP discovery and A2A checkout transport alongside existing ACP endpoints (API Version: `2026-01-11`):
 
 #### FR-UCP-01: UCP Discovery Endpoint
 * **Endpoint**: `GET /.well-known/ucp`
@@ -367,9 +367,8 @@ Implement UCP-compliant endpoints alongside existing ACP endpoints (API Version:
         {
           "version": "2026-01-11",
           "spec": "https://ucp.dev/specification/overview",
-          "transport": "rest",
-          "endpoint": "https://merchant.example.com/ucp/v1",
-          "schema": "https://ucp.dev/services/shopping/rest.openapi.json"
+          "transport": "a2a",
+          "endpoint": "https://merchant.example.com/.well-known/agent-card.json"
         }
       ]
     },
@@ -414,12 +413,15 @@ Implement UCP-compliant endpoints alongside existing ACP endpoints (API Version:
 }
 ```
 
-#### FR-UCP-02: Create Checkout Session (UCP)
-* **Endpoint**: `POST /checkout-sessions` (hyphenated per UCP spec)
+#### FR-UCP-02: Create Checkout Session (UCP over A2A)
+* **Endpoint**: `POST /a2a`
+* **A2A method/action**: JSON-RPC `message/send` with `action: "create_checkout"`
 * **Purpose**: Initialize UCP checkout session with capability negotiation
-* **Required Header**: `UCP-Agent: profile="https://platform.example/profile.json"` (RFC 8941 dictionary structured field)
-* **Idempotency**: Mutating operations include `Idempotency-Key` for retry safety
-* **Request Schema**:
+* **Required Headers**:
+  * `UCP-Agent: profile="https://platform.example/profile.json"` (RFC 8941 dictionary structured field)
+  * `X-A2A-Extensions: https://ucp.dev/specification/reference?v=2026-01-11`
+* **Idempotency**: Mutating operations rely on A2A `messageId` idempotency through the shared `IdempotencyStore`
+* **DataPart Payload**:
 ```json
 {
   "line_items": [
@@ -435,18 +437,20 @@ Implement UCP-compliant endpoints alongside existing ACP endpoints (API Version:
   }
 }
 ```
-* **Response**: Full checkout state with `ucp` metadata, `status`, `line_items`, `totals`
+* **Response**: JSON-RPC result containing a DataPart keyed by `a2a.ucp.checkout` with `ucp` metadata, `status`, `line_items`, and `totals`
 * **Status Transition**: `incomplete` (initial state)
 
-#### FR-UCP-03: Update Checkout Session (UCP)
-* **Endpoint**: `PUT /checkout-sessions/{id}` (PUT, not POST)
-* **Purpose**: Update checkout session with full replacement semantics
+#### FR-UCP-03: Update Checkout Session (UCP over A2A)
+* **Endpoint**: `POST /a2a`
+* **A2A method/action**: JSON-RPC `message/send` with `action: "update_checkout"`
+* **Purpose**: Update checkout session through the active A2A context/session mapping
 * **Status Transition**: `incomplete` → `ready_for_complete` when all required fields present
 
-#### FR-UCP-04: Complete Checkout (UCP)
-* **Endpoint**: `POST /checkout-sessions/{id}/complete`
+#### FR-UCP-04: Complete Checkout (UCP over A2A)
+* **Endpoint**: `POST /a2a`
+* **A2A method/action**: JSON-RPC `message/send` with `action: "complete_checkout"`
 * **Purpose**: Finalize transaction with payment instruments
-* **Request Schema**:
+* **Payment DataPart Payload**:
 ```json
 {
   "payment": {
@@ -473,21 +477,23 @@ Implement UCP-compliant endpoints alongside existing ACP endpoints (API Version:
 ```
 * **Status Transition**: `ready_for_complete` → `completed`
 
-#### FR-UCP-05: Cancel Checkout (UCP)
-* **Endpoint**: `POST /checkout-sessions/{id}/cancel`
+#### FR-UCP-05: Cancel Checkout (UCP over A2A)
+* **Endpoint**: `POST /a2a`
+* **A2A method/action**: JSON-RPC `message/send` with `action: "cancel_checkout"`
 * **Status Transition**: Any → `canceled`
 
-#### FR-UCP-06: Get Checkout Session (UCP)
-* **Endpoint**: `GET /checkout-sessions/{id}`
+#### FR-UCP-06: Get Checkout Session (UCP over A2A)
+* **Endpoint**: `POST /a2a`
+* **A2A method/action**: JSON-RPC `message/send` with `action: "get_checkout"`
 * **Purpose**: Retrieve current checkout state
 
-**UCP request headers (all endpoints):**
+**UCP request headers (A2A endpoint):**
 - `UCP-Agent: profile="..."` is required and uses RFC 8941 dictionary structured field syntax
-- `Idempotency-Key` is required for mutating operations (`POST`, `PUT`, `complete`, `cancel`)
+- `X-A2A-Extensions` is required and must include the UCP A2A extension URL
 - `Authorization` is optional and depends on the business's policy
 
-#### UCP Response Schema (All Endpoints)
-All successful responses return the full checkout state with UCP metadata:
+#### UCP Response Schema (A2A Responses)
+All successful A2A responses return a JSON-RPC result with a DataPart keyed by `a2a.ucp.checkout`. That checkout payload contains the full checkout state with UCP metadata:
 ```json
 {
   "ucp": {

docs/architecture.md

@@ -16,7 +16,7 @@
 The **Intelligent Commerce Middleware** is a Python **3.12+**-based reference architecture designed to host autonomous merchant agents. It exposes **two protocol implementations**:
 
 1. **ACP (Agentic Commerce Protocol)** - Five RESTful endpoints compliant with v2026-01-16
-2. **UCP (Universal Commerce Protocol)** - Industry-standard protocol aligned to v2026-01-11 (Discovery + Checkout, REST only in this project)
+2. **UCP (Universal Commerce Protocol)** - Industry-standard protocol aligned to v2026-01-11 (Discovery + Checkout over A2A only in this project)
 
 Both protocols utilize the **NVIDIA NeMo Agent Toolkit** to perform real-time business logic optimization. The system uses an "Async Parallel Orchestration" pattern to ensure fast, responsive agent reasoning while sharing the same intelligent agent layer and backend services.
 
@@ -25,7 +25,7 @@ We will also build a **client agent simulator** that plays the "client" role:
 
 * **Implementation**: Static simulator with pre-defined user flows and 4 pre-populated products
 * **Search Flow**: User enters a prompt (e.g., "find some t-shirts") → Simulator displays 4 product cards
-* **Checkout Flow**: User clicks a product → Simulator initiates `POST /checkout_sessions` to start the ACP checkout
+* **Checkout Flow**: User clicks a product → Simulator initiates checkout through the selected protocol (ACP REST or UCP A2A)
 
 **2. High-Level Project Diagram**
 
@@ -47,7 +47,7 @@ graph TD
     subgraph "Intelligent Middleware (FastAPI)"
         ROUTER[Protocol Router Layer]
         ACP_ROUTER[ACP Endpoints]
-        UCP_ROUTER[UCP Endpoints + Discovery]
+        UCP_ROUTER[UCP Discovery + A2A Endpoint]
         ROUTER --> ACP_ROUTER & UCP_ROUTER
         C[Shared Business Logic Layer]
         D[NAT Promotion Agent]
@@ -90,7 +90,7 @@ graph TD
     REC_CAROUSEL -.->|Fetches 3 items| E
     SHOP_CART -->|callTool checkout| ACP_ROUTER
     A -->|ACP REST| ACP_ROUTER
-    A -->|UCP REST + UCP-Agent header| UCP_ROUTER
+    A -->|UCP A2A + UCP-Agent/X-A2A headers| UCP_ROUTER
     D & E & F <-->|SQL Queries| G & H & I
     A -.->|Simulation View| K1
     ACP_ROUTER -.->|ACP JSON| K2_ACP
@@ -121,8 +121,8 @@ The system implements **both ACP and UCP protocols** to demonstrate how merchant
 │   └───────┬────────┴────────┬───────┘                                   │
 │           │                 │                                            │
 │           ▼                 ▼                                            │
-│   POST /checkout_sessions   POST /checkout-sessions (REST)              │
-│   (underscore, REST)        OR a2a.ucp.checkout.create (A2A)            │
+│   POST /checkout_sessions   POST /a2a (message/send)                    │
+│   (underscore, REST)        with create_checkout / update_checkout       │
 │                                                                          │
 │   ✓ Same Client Agent UI   ✓ Same Client Agent UI                       │
 │   ✓ Same NAT Agents        ✓ Same NAT Agents                            │
@@ -135,11 +135,11 @@ graph TD
     subgraph "Protocol Router Layer"
         DISC[GET /.well-known/ucp]
         ACP[ACP Endpoints]
-        UCP[UCP Endpoints]
+        UCP[UCP A2A Endpoint]
         ACP1[POST /checkout_sessions]
         ACP2[GET /checkout_sessions/:id]
-        UCP1[POST /checkout-sessions]
-        UCP2[GET /checkout-sessions/:id]
+        UCP1[POST /a2a message/send]
+        UCP2[create/get/update/complete/cancel actions]
 
         DISC -.->|UCP Discovery| UCP
         ACP --> ACP1 & ACP2
@@ -178,9 +178,9 @@ graph TD
 |--------|-----|-----|
 | **Discovery** | Static config | `GET /.well-known/ucp` |
 | **Versioning** | Header: `API-Version: 2026-01-16` | Profile + negotiation: `2026-01-11` |
-| **Transport** | REST only | REST + A2A (JSON-RPC 2.0) |
-| **Session Endpoint** | `POST /checkout_sessions` | `POST /checkout-sessions` or `a2a.ucp.checkout.create` |
-| **Update Method** | `POST /checkout_sessions/{id}` | `PUT /checkout-sessions/{id}` or `a2a.ucp.checkout.update` |
+| **Transport** | REST only | A2A (JSON-RPC 2.0) only in this implementation |
+| **Session Endpoint** | `POST /checkout_sessions` | `POST /a2a` with `message/send` + `create_checkout` |
+| **Update Method** | `POST /checkout_sessions/{id}` | `POST /a2a` with `message/send` + `update_checkout` |
 | **Status Names** | `not_ready_for_payment`, `ready_for_payment` | `incomplete`, `requires_escalation`, `ready_for_complete`, `complete_in_progress` |
 | **Response Metadata** | Payment provider info | `ucp` object with capabilities |
 | **Platform Advertisement** | API key (`Authorization` / `X-API-Key`) + `API-Version` | `UCP-Agent: profile="..."` (RFC 8941) |
@@ -235,8 +235,8 @@ Client Agent
 **UCP Flow:**
 ```
 Client Agent
-  ↓ POST /checkout-sessions (Header: UCP-Agent: profile="...")
-UCP Router
+  ↓ POST /a2a (Headers: UCP-Agent: profile="...", X-A2A-Extensions)
+UCP A2A Router
   ↓ fetch platform profile, compute capabilities
   ↓ normalize to internal format
 Shared Checkout Service
@@ -245,9 +245,9 @@ NAT Agents (Promotion, Recommendation)
   ↓ return decisions
 Shared Checkout Service
   ↓ transform to UCP response format
-UCP Router
+UCP A2A Router
   ↓ inject negotiated capabilities relevant to checkout in ucp metadata
-  ↓ Response with ucp.capabilities, status: ready_for_complete
+  ↓ JSON-RPC result with a2a.ucp.checkout data, ucp.capabilities, status: ready_for_complete
 Client Agent
 ```
 
@@ -289,7 +289,7 @@ graph TD
 * **Simulator Flow**:
   1. User enters search query (e.g., "find some t-shirts")
   2. Simulator displays 4 product cards with images and prices
-  3. User clicks a product to start checkout via ACP protocol
+  3. User clicks a product to start checkout through the selected protocol (ACP REST or UCP A2A)
 * **Static Product Catalog**: 4 pre-populated products stored in SQLite.
 * **Delegated Payments (PSP)** - ACP-compliant payment flow (UCP uses payment handlers; this demo may map handlers to the same PSP flow):
   1. **Client/Agent obtains vault token**: `POST /agentic_commerce/delegate_payment`

docs/features.md

@@ -15,7 +15,7 @@ Both protocols share the same intelligent agent layer (NAT-powered Promotion, Re
 
 **Protocol Toggle:** The Merchant Activity Panel provides a tab switcher (ACP | UCP). The client agent flow remains unchanged - only the backend protocol changes based on the toggle.
 
-**UCP scope in this project:** Discovery + Checkout (REST + A2A). The A2A transport uses JSON-RPC 2.0 for agent-to-agent communication. Cart/Order/Identity Linking and MCP/Embedded transports are out of scope for Feature 17.
+**UCP scope in this project:** Discovery + Checkout over A2A only. The A2A transport uses JSON-RPC 2.0 for agent-to-agent communication through `POST /a2a`. Cart/Order/Identity Linking and REST/MCP/Embedded transports are out of scope for Feature 17.
 
 ## Quick Links
 
@@ -37,6 +37,6 @@ Both protocols share the same intelligent agent layer (NAT-powered Promotion, Re
 | 14 | [Enhanced Checkout (Payment & Shipping)](./features/feature-14-enhanced-checkout.md) | ✅ Complete |
 | 15 | [Multi-Language Post-Purchase Messages](./features/feature-15-multi-language.md) | ✅ Complete |
 | 16 | [Apps SDK Integration (Merchant Iframe)](./features/feature-16-apps-sdk.md) | 🔲 Planned |
-| 17 | [UCP Protocol Integration](./features/feature-17-ucp-integration.md) | 🔲 Planned |
+| 17 | [UCP Protocol Integration](./features/feature-17-ucp-integration.md) | 🟡 In Progress |
 
 For the full overview including implementation phases and non-functional requirements, see the [Feature Overview](./features/index.md).