Merge pull request #62 from IABTechLab/docs/buyer-docs-improvement

Docs: Streamline buyer website for clarity and storytelling

Author: atc964

docs/api/a2a-client.md

@@ -2,6 +2,18 @@
 
 The buyer agent uses the **Agent-to-Agent (A2A) protocol** for conversational discovery and negotiation with seller agents. A2A sends natural language messages over JSON-RPC 2.0; the seller's AI interprets the request and executes the appropriate tools.
 
+## When to Use A2A
+
+| Scenario | A2A | MCP |
+|----------|-----|-----|
+| Exploratory discovery queries | Preferred | -- |
+| Complex negotiations with context | Preferred | -- |
+| Ambiguous or open-ended requests | Preferred | -- |
+| Automated booking workflows | -- | Preferred |
+| Deterministic, repeatable results | -- | Preferred |
+
+Use A2A when the request benefits from natural language interpretation --- for example, asking "What CTV inventory do you have under $25 with household targeting?" rather than constructing exact filter parameters. For structured, deterministic operations, see the [MCP Client](mcp-client.md).
+
 ## A2AClient Class
 
 The `A2AClient` connects to a seller's A2A endpoint and sends natural language messages.
@@ -239,18 +251,6 @@ async with A2AClient(base_url="http://seller:8001") as client:
     )
 ```
 
-## When to Use A2A
-
-| Scenario | A2A | MCP |
-|----------|-----|-----|
-| Exploratory discovery queries | Preferred | -- |
-| Complex negotiations with context | Preferred | -- |
-| Ambiguous or open-ended requests | Preferred | -- |
-| Automated booking workflows | -- | Preferred |
-| Deterministic, repeatable results | -- | Preferred |
-
-Use A2A when the request benefits from natural language interpretation --- for example, asking "What CTV inventory do you have under $25 with household targeting?" rather than constructing exact filter parameters.
-
 ## Error Handling
 
 The client raises `A2AError` when the seller returns a JSON-RPC error response. HTTP-level errors (connection refused, timeouts) raise standard `httpx` exceptions.

docs/api/bookings.md

@@ -1,5 +1,7 @@
 # Bookings API
 
+A **booking** is the buyer agent's end-to-end process of turning a campaign brief into confirmed advertising deals. You submit a brief describing your campaign objectives, budget, audience, and timeline; the buyer agent allocates budget across channels, researches inventory from connected sellers, optionally negotiates pricing, and presents recommendations for your approval. Once approved, the agent books confirmed line items via the seller's OpenDirect API. Use these endpoints to start a booking, poll its progress, and approve or reject the resulting recommendations.
+
 The bookings endpoints manage the full campaign booking lifecycle --- from brief submission through approval to deal execution.
 
 ## Status Lifecycle

docs/api/change-requests.md

@@ -2,9 +2,6 @@
 
 Change requests allow the buyer to propose post-deal modifications to orders on the seller. Each request is validated against the current order state, assigned a severity level, and routed through the appropriate approval path on the seller side.
 
-!!! info "Planned client"
-    The buyer does not yet have a dedicated `ChangeRequestsClient`. The workflows below document the seller's REST API that the buyer calls directly. A typed client is planned for a future release.
-
 !!! tip "Seller-side reference"
     For the full server-side behavior --- including severity auto-classification, validation rules, and the review/apply workflow --- see the [Seller Change Requests docs](https://iabtechlab.github.io/seller-agent/api/change-requests/).
 
@@ -33,6 +30,9 @@ sequenceDiagram
 
 The buyer submits a change request and receives a change request ID. Minor changes (e.g., small flight date shifts, creative swaps) are auto-approved and applied immediately. Material and critical changes enter a review queue on the seller side.
 
+!!! info "Planned client"
+    The buyer does not yet have a dedicated `ChangeRequestsClient`. The workflows below document the seller's REST API that the buyer calls directly. A typed client is planned for a future release.
+
 ---
 
 ## Severity Levels

docs/api/mcp-client.md

@@ -2,6 +2,21 @@
 
 The buyer agent uses the **Model Context Protocol (MCP)** as its primary protocol for calling seller agent tools. MCP provides deterministic, structured tool execution over HTTP --- ideal for automated workflows where the buyer knows exactly which operation to perform.
 
+## When to Use MCP
+
+| Scenario | MCP | A2A |
+|----------|-----|-----|
+| Automated booking workflows | Preferred | -- |
+| Structured CRUD operations | Preferred | -- |
+| Deterministic, repeatable results | Preferred | -- |
+| Exploratory discovery | -- | Preferred |
+| Complex multi-turn negotiation | -- | Preferred |
+
+Use MCP when you know the exact tool and arguments. The buyer's CrewAI tools default to MCP for all standard operations. For open-ended discovery and negotiation, see the [A2A Client](a2a-client.md).
+
+!!! note "Automatic protocol selection"
+    The `UnifiedClient` selects MCP by default for standard operations. You do not need to choose the protocol manually unless you have a specific reason to prefer A2A.
+
 ## Client Implementations
 
 The buyer includes two MCP client implementations, selected based on environment and dependency availability.
@@ -97,18 +112,6 @@ async with IABMCPClient(base_url="http://seller:8001") as client:
     )
 ```
 
-## When to Use MCP
-
-| Scenario | MCP | A2A |
-|----------|-----|-----|
-| Automated booking workflows | Preferred | -- |
-| Structured CRUD operations | Preferred | -- |
-| Deterministic, repeatable results | Preferred | -- |
-| Exploratory discovery | -- | Preferred |
-| Complex multi-turn negotiation | -- | Preferred |
-
-Use MCP when you know the exact tool and arguments. The buyer's CrewAI tools default to MCP for all standard operations.
-
 ## Error Handling
 
 MCP client errors fall into two categories: connection-level failures (cannot reach the seller) and tool-level failures (the tool call itself failed).

docs/api/media-kit.md

@@ -1,6 +1,9 @@
-# Media Kit Discovery
+# Media Kit API Reference
 
-The media kit is a seller's **inventory catalog** — a curated collection of ad packages that buyer agents browse to discover available inventory. The buyer agent includes a dedicated `MediaKitClient` for consuming seller media kits.
+The media kit is a seller's **inventory catalog** --- a curated collection of ad packages that buyer agents browse to discover available inventory. The buyer agent includes a dedicated `MediaKitClient` for consuming seller media kits. This page documents the client's methods, parameters, data models, and error handling.
+
+!!! tip "Looking for usage patterns?"
+    For practical guidance on browsing strategies, progressive identity revelation, cross-seller comparison, and connecting discovery to the buying workflow, see the [Media Kit Browsing Guide](../guides/media-kit.md).
 
 ## Overview
 
@@ -198,38 +201,6 @@ Sellers apply tier-based discounts. Higher identity revelation unlocks better pr
 !!! tip "Progressive Identity Revelation"
     Start with public browsing to evaluate inventory, then authenticate to see exact pricing. Provide agency/advertiser identity during search to unlock the best rates.
 
-## Identity-Based Access
-
-Beyond the API key, the buyer can reveal its identity for seller-side tier resolution. The `SearchFilter` supports this:
-
-```python
-# Search with full identity context
-results = await client.search_packages(
-    seller_url,
-    query="premium video",
-    filters=SearchFilter(
-        buyer_tier="advertiser",
-        agency_id="omnicom-456",
-        advertiser_id="coca-cola",
-    ),
-)
-```
-
-Alternatively, the `BuyerIdentity` model can generate identity headers for direct HTTP calls:
-
-```python
-from ad_buyer.models.buyer_identity import BuyerIdentity
-
-identity = BuyerIdentity(
-    seat_id="ttd-seat-123",
-    agency_id="omnicom-456",
-    advertiser_id="coca-cola",
-)
-
-# Produces: {"X-DSP-Seat-ID": "...", "X-Agency-ID": "...", "X-Advertiser-ID": "..."}
-headers = identity.to_header_dict()
-```
-
 ## Data Models
 
 ### PackageSummary (Public)
@@ -322,31 +293,10 @@ Common error scenarios:
 | HTTP 4xx/5xx | `MediaKitError` with status code |
 | Failed seller in aggregation | Silently skipped, warning logged |
 
-## Workflow: From Media Kit to Booking
-
-The media kit is the first step in the deal lifecycle:
-
-```mermaid
-graph LR
-    A[Browse Media Kit] --> B[Select Package]
-    B --> C[Get Exact Pricing]
-    C --> D[Request Quote]
-    D --> E[Negotiate]
-    E --> F[Book Deal]
-```
-
-1. **Browse** the seller's media kit (public or authenticated)
-2. **Select** a package that matches campaign requirements
-3. **Get exact pricing** by authenticating with your API key
-4. **Request a quote** via the [OpenDirect](https://iabtechlab.com/standards/opendirect/) API for specific products in the package
-5. **Negotiate** if your tier allows it (Agency/Advertiser)
-6. **Book** the deal through the standard booking flow
-
-See [Booking Lifecycle](bookings.md) and [Seller Agent Integration](../integration/seller-agent.md) for the full workflow.
-
 ## Related
 
-- [Seller Agent Media Kit Setup](https://iabtechlab.github.io/seller-agent/guides/media-kit/) — How publishers configure their media kit
-- [Authentication](authentication.md) — API key setup for authenticated access
-- [Products](products.md) — Product search endpoint
-- [Seller Agent Integration](../integration/seller-agent.md) — Full integration guide
+- [Media Kit Browsing Guide](../guides/media-kit.md) --- Practical patterns for browsing, cross-seller comparison, and connecting discovery to the buying workflow
+- [Seller Agent Media Kit Setup](https://iabtechlab.github.io/seller-agent/guides/media-kit/) --- How publishers configure their media kit
+- [Authentication](authentication.md) --- API key setup for authenticated access
+- [Products](products.md) --- Product search endpoint
+- [Seller Agent Integration](../integration/seller-agent.md) --- Full integration guide

docs/api/products.md

@@ -1,6 +1,6 @@
 # Products API
 
-The products endpoint lets you search the seller agent's product catalog directly, outside of a booking workflow.
+The products endpoint lets you search the seller agent's product catalog directly, outside of a booking workflow. Use this for quick inventory lookups when you already know what channel, format, or price range you need --- for richer browsing with package metadata, tier-based pricing, and cross-seller comparison, use the [Media Kit API](media-kit.md) instead.
 
 ## POST /products/search