Universal-Commerce-Protocol · wry-ry · Jan 24, 2026 · Jan 21, 2026 · Jan 21, 2026 · Jan 22, 2026
diff --git a/a2a/DEVELOPER_GUIDE.md b/a2a/DEVELOPER_GUIDE.md
@@ -0,0 +1,82 @@
+# Cymbal Retail Agent - Developer Guide
+
+## TL;DR
+
+- **ADK Agent** with 8 shopping tools (search, checkout, payment) using Gemini 3.0 Flash
+- **UCP Integration** for standardized commerce data types and capability negotiation
+- **A2A Protocol** for agent discovery and JSON-RPC messaging
+
+## About This Guide
+
+This guide is for developers who want to understand how the sample works internally.
+
+**Prerequisites:** Complete the [Quick Start in README.md](README.md#quick-start) first.
+
+**What you'll learn:**
+- System architecture and component responsibilities
+- How UCP and A2A protocols integrate with ADK
+- The checkout state machine and commerce flows
+- How to extend and customize the sample
+
+## Reading Roadmap
+
+Choose your path based on your goal:
+
+| Goal | Start Here | Then Read |
+|------|------------|-----------|
+| **New to AI agents?** | [Glossary](docs/00-glossary.md) | This guide → 01-architecture |
+| **Understand the system** | [Architecture](docs/01-architecture.md) | 02-adk-agent → 03-ucp-integration |
+| **Add a new tool** | [ADK Agent](docs/02-adk-agent.md) | 06-extending |
+| **Modify checkout flow** | [Commerce Flows](docs/04-commerce-flows.md) | 06-extending |
+| **Customize the UI** | [Frontend](docs/05-frontend.md) | - |
+| **Debug an issue** | [Testing Guide](docs/07-testing-guide.md) | - |
+| **Deploy to production** | [Production Notes](docs/08-production-notes.md) | - |
+| **Use AI assistant** | [SKILLS.md](SKILLS.md) | Context for Claude Code, Gemini CLI, Cursor, Codex |
+
+## Architecture
+
+<div align="center">
+  <img src="assets/diagrams/00_01_architecture_overview.webp" alt="Cymbal Retail Agent Architecture" width="800">
+  <p><em>System architecture — Chat Client (React + A2A Client) communicates via JSON-RPC to the Cymbal Retail Agent (A2A Server → ADKAgentExecutor → ADK Agent → RetailStore). Discovery endpoints expose agent capabilities and UCP profile.</em></p>
+</div>
+
+## Quick Reference
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `business_agent/src/business_agent/agent.py` | ADK agent + 8 tools |
+| `business_agent/src/business_agent/store.py` | Checkout state machine |
+| `business_agent/src/business_agent/agent_executor.py` | A2A ↔ ADK bridge |
+| `chat-client/App.tsx` | React app + A2A messaging |
+
+### Endpoints
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /.well-known/agent-card.json` | A2A agent discovery |
+| `GET /.well-known/ucp` | UCP merchant profile |
+| `POST /` | A2A JSON-RPC endpoint |
+
+### State Keys
+
+| Key | Purpose |
+|-----|---------|
+| `user:checkout_id` | Current checkout session |
+| `__ucp_metadata__` | Negotiated capabilities |
+| `__payment_data__` | Payment instrument |
+
+## Deep Dive Guides
+
+| Guide | Topics |
+|-------|--------|
+| [Glossary](docs/00-glossary.md) | Key terms, acronyms, state keys |
+| [Architecture](docs/01-architecture.md) | System components, data flow |
+| [ADK Agent](docs/02-adk-agent.md) | Tools, callbacks, session management |
+| [UCP Integration](docs/03-ucp-integration.md) | Capabilities, profiles, negotiation |
+| [Commerce Flows](docs/04-commerce-flows.md) | Checkout lifecycle, payment |
+| [Frontend](docs/05-frontend.md) | React components, A2A client |
+| [Extending](docs/06-extending.md) | Add tools, products, capabilities |
+| [Testing Guide](docs/07-testing-guide.md) | Testing, debugging, troubleshooting |
+| [Production Notes](docs/08-production-notes.md) | Security gaps, deployment checklist |
diff --git a/a2a/README.md b/a2a/README.md
@@ -39,7 +39,7 @@ The sample uses **[Google ADK](https://google.github.io/adk-docs/)** (Agent Deve
 <b>Complete Shopping Flow</b><br/>
 <i>Product search → Add items to Checkout → Payment → Order confirmation</i>
 <br/><br/>
-<img src="assets/ucp_a2a_demo.gif" alt="UCP A2A Demo" width="800" />
+<img src="assets/ucp_a2a_demo.webp" alt="UCP A2A Demo" width="800" />
 <br/><br/>
 <a href="https://github.com/user-attachments/assets/8d3d17f5-dbcc-4cc8-91b9-2b7d48b3f2df">▶️ Watch the full demo video</a>
 </p>
@@ -50,7 +50,7 @@ The sample uses **[Google ADK](https://google.github.io/adk-docs/)** (Agent Deve
 <b>System Architecture</b><br/>
 <i>How Client, A2A Protocol, Cymbal Retail Agent, and Store interact</i>
 <br/><br/>
-<img src="assets/architecture_diagram.jpeg" alt="Architecture Diagram" width="900" />
+<img src="assets/architecture_diagram.webp" alt="Architecture Diagram" width="900" />
 </p>
 
 **Key points:**
@@ -103,13 +103,13 @@ This starts the Cymbal Retail Agent on port 10999. You can verify by accessing:
 <td width="50%" align="center">
 <b>Agent Card</b><br/><code>/.well-known/agent-card.json</code>
 <br/><br/>
-<img src="assets/agent_card.png" alt="Agent Card" width="400" />
+<img src="assets/agent_card.webp" alt="Agent Card" width="400" />
 <br/><i>Declares UCP extension with capabilities</i>
 </td>
 <td width="50%" align="center">
 <b>UCP Profile</b><br/><code>/.well-known/ucp</code>
 <br/><br/>
-<img src="assets/well_known.png" alt="UCP Profile" width="400" />
+<img src="assets/well_known.webp" alt="UCP Profile" width="400" />
 <br/><i>Defines supported capabilities & payment handlers</i>
 </td>
 </tr>
@@ -139,7 +139,7 @@ The Chat Client UCP Profile can be found at http://localhost:3000/profile/agent-
 <table>
 <tr>
 <td width="50%" align="center">
-<img src="assets/ucp_a2a_demo.gif" alt="Demo" width="400" />
+<img src="assets/ucp_a2a_demo.webp" alt="Demo" width="400" />
 <br/><a href="https://github.com/user-attachments/assets/8d3d17f5-dbcc-4cc8-91b9-2b7d48b3f2df">▶️ Watch full video</a>
 </td>
 <td width="50%" valign="top">
@@ -158,6 +158,19 @@ The Chat Client UCP Profile can be found at http://localhost:3000/profile/agent-
 </tr>
 </table>
 
+> **Note**: This sample is for demonstration purposes only. See [Production Notes](docs/08-production-notes.md) for security considerations and deployment requirements.
+
+## Next Steps
+
+Ready to understand how it works?
+
+| Goal | Resource |
+|------|----------|
+| **Understand the architecture** | [Developer Guide](DEVELOPER_GUIDE.md) |
+| **Deep dive into code** | [Architecture](docs/01-architecture.md) |
+| **Extend the sample** | [Extending Guide](docs/06-extending.md) |
+| **AI assistant context** | [SKILLS.md](SKILLS.md) - Context for Claude Code, Gemini CLI, Cursor, Codex |
+
 ## What is UCP?
 
 **Universal Commerce Protocol (UCP)** is an open standard that enables interoperability between commerce platforms, merchants, and payment providers. It provides standardized data types for commerce transactions.
@@ -177,40 +190,6 @@ This sample uses the following UCP capabilities:
 | **[A2A Protocol](https://a2a-protocol.org/latest/)** | Communication | Agent discovery via Agent Card, JSON-RPC messaging, task management |
 | **[UCP](https://ucp.dev)** | Commerce Standard | Standardized product, checkout, payment, and order data types |
 
-## Components
-
-### Cymbal Retail Agent (`business_agent/`)
-
-AI shopping assistant built with Google ADK, exposed via A2A interface with UCP extension.
-
-| File | Purpose |
-|------|---------|
-| `agent.py` | ADK Agent with Gemini 3.0 Flash + 8 shopping tools |
-| `agent_executor.py` | Bridges ADK ↔ A2A protocol |
-| `store.py` | Mock RetailStore (products, checkouts, orders) |
-| `data/ucp.json` | UCP Profile served at `/.well-known/ucp` |
-
-### Chat Client (`chat-client/`)
-
-React UI (TypeScript, Vite, Tailwind) that communicates via A2A and renders UCP data types.
-
-| File | Purpose |
-|------|---------|
-| `App.tsx` | A2A messaging + state management |
-| `components/` | ProductCard, Checkout, PaymentMethodSelector |
-| `profile/agent_profile.json` | Client's UCP capabilities |
-
-## Mock Store
-
-The Cymbal Retail Agent uses an in-memory `RetailStore` to simulate a real backend:
-
-- **Products** - Loaded from `data/products.json` (cookies, chips, fruits, etc.)
-- **Checkouts** - Session-based checkout management with line items
-- **Orders** - Created when checkout completes successfully
-- **Payments** - Mock processor simulates payment flow
-
-Prices are in USD, tax is calculated at 10%, and shipping costs vary by method.
-
 ## Related Resources
 
 - [UCP Specification](https://ucp.dev/specification/overview/)