Docs freshness sweep: CHANGELOG backfill, version metadata, surface counts, deal-sync docs

CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to the IAB Tech Lab Seller Agent are documented here.
 
 ## [Unreleased]
 
+## [2.3.3] — 2026-07-29
+
+### Fixed
+- Replaced the retired manager-LLM default: Anthropic retired
+  `claude-opus-4-20250514` on June 15, 2026, so fresh installs using an
+  Anthropic key failed with `model_not_found`. `MANAGER_LLM_MODEL` now
+  defaults to `claude-opus-4-8` (Bedrock inference profile
+  `us.anthropic.claude-opus-4-8`) across settings, `.env.example`, and
+  the configuration guide. (#35)
+- Ported the surgical toolResult stripping from buyer-agent, restoring
+  patch parity between the two agents. (#36)
+- Default-catalog product IDs are now derived deterministically
+  (`uuid5` of the product name) instead of minted randomly on every
+  catalog build, so product IDs are stable across restarts and cache
+  resets. The reset-ids test was updated to the deterministic-ID
+  contract. (#37, follow-up to issue #34)
+
+## [2.3.2] — 2026-07-28
+
+### Added
+- deals-api-mcp deal-sync integration (#32): a new deal-sync connector
+  family — `DealSyncClient` ABC and `DealSyncRegistry`
+  (`clients/deal_sync_base.py`), a peer of the SSP registry — with
+  `DealsAPIMCPClient` pushing negotiated deals to the IAB
+  [deals-api-mcp](https://github.com/IABTechLab/deals-api-mcp) server
+  (IAB Deal Sync API v1.0) over MCP Streamable HTTP. See
+  `docs/integration/deals-api-mcp.md`.
+
+## [2.3.1] — 2026-07-22
+
+### Fixed
+- Agent card (`/.well-known/agent.json`) advertises only the protocols
+  the server actually serves; A2A documentation marked
+  designed-not-implemented.
+
+## [2.3.0] — 2026-07-22
+
 ### Added
 - OpenDirect 2.1 spec dialect on `POST /products/avails` (dialect
   convergence, shared avails contract): the published
@@ -17,21 +54,62 @@ All notable changes to the IAB Tech Lab Seller Agent are documented here.
   byte-for-byte unchanged. Requested volume/budget arrive on the spec
   dialect as the contract's Investment `producttargeting` entries and
   feed the same honest-availability policy. Regenerated
-  `docs/api/openapi.json`.
+  `docs/api/openapi.json`. (primitives v0.5.0)
+
+## [2.2.2] — 2026-07-22
+
+### Fixed
+- Proposal availability is grounded in `check_avails`; volume
+  shortfalls now produce a counter-offer instead of a rejection.
+- CSV inventory is included in the product catalog; `update_package`
+  applies a field whitelist.
+
+## [2.2.1] — 2026-07-22
+
+### Fixed
+- Catalog-aware package resolution and idempotent inventory sync
+  (issue #34).
+
+## [2.2.0] — 2026-07-21
+
+### Changed
 - Avails endpoint (`POST /products/avails`) adopted the shared avails wire
   contract: request/response models are now
   `iab_agentic_primitives.protocol.AvailsRequest`/`AvailsResponse`
   (re-exported through `ad_seller.interfaces.api.schemas`), the canonical
-  home of the contract. Same wire dialect and field set.
-
-### Changed
+  home of the contract. Same wire dialect and field set. (primitives
+  v0.4.0)
 - Avails responses no longer null-pad valueless optionals: per the shared
   contract policy, `deliveryConfidence` is omitted entirely (this
   reference seller has no forecast data source), `guaranteedImpressions`
   appears only for PG-capable products, and `availableTargeting` is
   omitted when the product declares no targeting dicts. Readers that
   parsed the previous explicit nulls parse the omitted form identically
   under the shared models. Regenerated `docs/api/openapi.json`.
+
+### Added
+- Leak-prevention guardrails: git hooks and hygiene CI; internal issue
+  tracker removed from the public tree.
+
+## [2.1.1] — 2026-07-21
+
+### Changed
+- Universal lowball counter: all below-floor offers are countered at
+  floor rather than rejected (spec change).
+- Bounded proposal-flow latency with a deterministic fallback.
+
+### Added
+- Cold-start negotiation surface: proposal persistence, quote-led
+  opens, and booking honors `ACCEPTED` proposals.
+- Grounded quote availability and enriched catalog metadata.
+
+### Fixed
+- Docs CI deploys without installing the app (private dependency); the
+  OpenAPI artifact is committed.
+
+## [2.1.0] — 2026-07-20
+
+### Added
 - MCP Streamable HTTP transport at `/mcp` (current MCP standard, protocol 2025-06-18) — resolves buyer agent 405 errors on MCP connection
 - Legacy HTTP+SSE transport kept at `/mcp-sse/sse` for backwards compatibility with older Claude Desktop / ChatGPT clients
 - FreeWheel OAuth 2.1 PKCE authentication integration:
@@ -43,20 +121,38 @@ All notable changes to the IAB Tech Lab Seller Agent are documented here.
 - CSV ad server adapter with full CRUD and atomic writes (61 tests)
 - 9 MCP prompts (slash commands) for Claude Desktop/web (/setup, /status, /inventory, /deals, /queue, /new-deal, /configure, /buyers, /help)
 - 3 composite tools: get_inbound_queue, get_buyer_activity, list_configurable_flows
+- Avails endpoint `POST /products/avails` with honest-availability policy
+- Auto-generated tool/endpoint/event inventories (`docs/reference/`) with a CI drift guard
+- Tested quickstart: smoke test boots the documented entrypoint and asserts core routes respond
+- Server-side trust-tier verification with `VerifiedTrust` persisted on price-moving paths; agent-registry wiring
+- Threshold-driven mandatory approval gates; approval endpoints authenticated and stamped with the verified principal
 - Comprehensive unit tests (86 new tests) and integration tests (38 new tests)
 - Troubleshooting guide
 - Buyer agent compatibility report
 
 ### Changed
+- Service layer extracted: MCP tools, CLI, and chat interface are thin adapters over it; background REST sidecar removed from the AgentCore MCP entrypoint
+- Shared iab-agentic-primitives contracts adopted at the Quote, Deal-booking, Negotiation, and Catalog wire edges
+- OpenDirect tier-1 wire aliases on the public wire surface
+- Two-way main/v2 reconciliation: GAM adapter restored, LLM provider configuration unified
 - Renamed "Deal Jockey" to "Deal Library" across codebase and documentation
 - Linted and formatted entire codebase with ruff
 - Removed `FREEWHEEL_BC_CLIENT_ID` and `FREEWHEEL_BC_CLIENT_SECRET` settings (Beeswax uses session cookie auth, not OAuth client_credentials)
 
 ### Fixed
+- CPM hallucination: `pricing_type` enum + quote validation (#7)
+- Route shadowing: `/api/v1/deals/export` registered before `/{deal_id}`
+- Auth header binding in `_get_optional_api_key_record`; audit trail fails closed
+- `MANAGER_LLM_MODEL` default: `opus-4-20250514` → `sonnet-4-5-20250929` (#19)
+- CrewAI shutdown telemetry hang disabled; agent memory respects `crew_memory_enabled` (#21, #22)
+- Shared `Product.ad_formats` populated from `inventory_type`
 - Documentation tool count (41 MCP tools, not "45+")
 - Documentation endpoint count (82 REST endpoints, not "70+")
 - Port typo in media-kit guide (8001 → 8000)
 
+### Removed
+- Unused `services/openrtb_parser.py` and `services/setup_wizard.py`; abandoned CrewAI tool subpackages (gam, pricing, proposal, availability, deal_library)
+
 ## [2.0.0] — 2026-03-23
 
 ### Added

README.md

@@ -8,7 +8,7 @@ An AI-powered inventory management system for **publishers and SSPs** to automat
 
 ## What This Does
 
-- **Manage your seller agent from Claude** (desktop or web) — interactive setup wizard + 41 MCP tools for day-to-day operations
+- **Manage your seller agent from Claude** (desktop or web) — interactive setup wizard + 46 MCP tools for day-to-day operations
 - **Expose your inventory** via a tiered Media Kit with public and authenticated views
 - **Automate deal negotiations** with AI agents that understand your pricing rules
 - **Offer tiered pricing** based on buyer identity (public, seat, agency, advertiser)
@@ -29,9 +29,9 @@ The seller agent exposes four communication interfaces:
 
 | Interface | Protocol | Use Case |
 |-----------|----------|----------|
-| **MCP** | `/mcp` (Streamable HTTP), `/mcp-sse/sse` (legacy) | Primary interface — 41 tools for Claude, ChatGPT, Codex, Cursor, and buyer agents |
+| **MCP** | `/mcp` (Streamable HTTP), `/mcp-sse/sse` (legacy) | Primary interface — 46 tools for Claude, ChatGPT, Codex, Cursor, and buyer agents |
 | **A2A** | `/a2a/{agent}/jsonrpc` | Conversational JSON-RPC 2.0 for natural language queries |
-| **REST** | `/api/v1/*` | Programmatic access — 82 endpoints across 15 groups |
+| **REST** | `/api/v1/*` | Programmatic access — 87 endpoints across 25 groups |
 | **Chat** | `/chat` | Web-based conversational interface for human buyers |
 
 > [Protocol Documentation](https://iabtechlab.github.io/seller-agent/api/mcp/)
@@ -51,7 +51,7 @@ Buyer Agents ──→ A2A / REST ───────────────
                     │                               │                      │
                     ▼                               ▼                      ▼
               Ad Server Layer               Storage (SQLite/PG)      Event Bus
-              ┌──────────────┐              (products, packages,     (16 event types)
+              ┌──────────────┐              (products, packages,     (22 event types)
               │ GAM    ✅    │               orders, sessions,
               │ FreeWheel ✅ │               deals, curators)
               │ CSV    ✅    │
@@ -67,6 +67,13 @@ Buyer Agents ──→ A2A / REST ───────────────
               │ Your SSP*       │
               └──────────────────┘
               * Pluggable via SSPClient
+                    │
+              Deal Sync
+              ┌──────────────────┐
+              │ deals-api-mcp ✅ │
+              │ Your service*    │
+              └──────────────────┘
+              * Pluggable via DealSyncClient
 ```
 
 ### Agent Hierarchy
@@ -121,20 +128,24 @@ The wizard guides you through: publisher identity → agent behavior → media k
 
 ## Key Features
 
-### MCP Tools (41 tools for Claude / ChatGPT / Codex / Cursor)
+### MCP Tools (46 tools for Claude / ChatGPT / Codex / Cursor)
 
 | Category | Tools | Examples |
 |----------|-------|---------|
-| Setup | 4 | `get_setup_status`, `health_check`, `get_config` |
-| Inventory | 4 | `list_products`, `sync_inventory`, `list_inventory` |
-| Media Kit | 3 | `list_packages`, `create_package`, `search_packages` |
-| Pricing | 4 | `get_rate_card`, `update_rate_card`, `get_pricing` |
-| Deals | 12 | `create_deal_from_template`, `push_deal_to_buyers`, `distribute_deal_via_ssp`, `migrate_deal`, `deprecate_deal`, `get_deal_lineage` |
+| Setup | 4 | `get_setup_status`, `health_check`, `get_config`, `set_publisher_identity` |
+| Inventory | 4 | `list_products`, `sync_inventory`, `list_inventory`, `get_sync_status` |
+| Media Kit | 2 | `list_packages`, `create_package` |
+| Pricing & Quotes | 4 | `get_rate_card`, `update_rate_card`, `get_pricing`, `request_quote` |
+| Deals | 9 | `create_deal_from_template`, `push_deal_to_buyers`, `migrate_deal`, `deprecate_deal`, `get_deal_lineage`, `export_deals`, `bulk_deal_operations` |
+| Orders & Reporting | 4 | `list_orders`, `transition_order`, `list_gam_orders`, `get_gam_delivery_report` |
 | Approvals | 3 | `list_pending_approvals`, `approve_or_reject`, `set_approval_gates` |
-| Buyer Agents | 4 | `list_buyer_agents`, `register_buyer_agent`, `set_agent_trust` |
-| Curators | 3 | `list_curators`, `create_curated_deal` |
-| SSPs | 3 | `list_ssps`, `distribute_deal`, `troubleshoot_deal` |
-| Admin | 5 | `create_api_key`, `list_api_keys`, `list_sessions` |
+| Buyer Agents | 4 | `list_buyer_agents`, `register_buyer_agent`, `set_agent_trust`, `list_agents` |
+| Curators | 2 | `list_curators`, `create_curated_deal` |
+| SSPs | 3 | `list_ssps`, `distribute_deal_via_ssp`, `troubleshoot_deal` |
+| Admin & Sessions | 4 | `create_api_key`, `list_api_keys`, `revoke_api_key`, `list_sessions` |
+| Composite | 3 | `get_inbound_queue`, `get_buyer_activity`, `list_configurable_flows` |
+
+Full inventory: [MCP Tools reference](https://iabtechlab.github.io/seller-agent/reference/mcp-tools/).
 
 ### Deal Distribution (3 paths)
 
@@ -200,28 +211,37 @@ INDEX_EXCHANGE_API_URL=https://api.indexexchange.com
 
 ## API Reference
 
-82 endpoints across 15 groups:
+87 endpoints across 25 groups:
 
 | Group | Endpoints | Description |
 |-------|-----------|-------------|
 | Media Kit | 4 | Public inventory catalog (no auth) |
-| Packages | 7 | Tier-gated package CRUD |
-| Products | 5 | Product catalog + inventory type overrides |
+| Packages | 7 | Tier-gated package CRUD, assembly, and sync |
+| Products | 6 | Product catalog, avails, inventory type overrides |
 | Quotes | 2 | Non-binding price quotes (IAB Deals API) |
-| Deal Booking | 12 | Deals, from-template, push, distribute, migrate, deprecate, lineage, export |
-| Proposals | 6 | Proposal lifecycle + counter-offers |
-| Orders | 8 | Order CRUD + state transitions |
-| Change Requests | 5 | Post-deal modification requests |
-| Supply Chain | 1 | sellers.json-like self-description |
+| Deal Booking | 11 | Deals, from-template, push, distribute, migrate, deprecate, lineage, export |
+| Deals | 1 | Deal creation from accepted proposals |
 | Deal Performance | 1 | Delivery metrics |
 | Bulk Operations | 1 | Batch deal create/update/cancel |
+| Proposals | 1 | Proposal submission |
+| Negotiation | 3 | Counter-offers + negotiation state and messages |
+| Discovery | 1 | Natural-language inventory discovery |
+| Audience | 1 | Agentic audience matching |
+| Orders | 6 | Order CRUD, history, transitions, reporting |
+| Audit | 1 | Order audit trail |
+| Change Requests | 5 | Post-deal modification requests |
+| Approvals | 4 | Human-in-the-loop approval decisions |
+| Supply Chain | 1 | sellers.json-like self-description |
 | Curators | 4 | Curator registration + curated deals |
-| Sessions | 4 | Multi-turn session persistence |
-| Authentication | 3 | API key management |
-| Agent Registry | 5 | Agent trust + discovery |
+| Sessions | 5 | Multi-turn session persistence |
+| Authentication | 4 | API key management |
+| Agent Registry | 6 | Agent card, trust + discovery |
 | Pricing | 3 | Rate card + pricing calculation |
-| Inventory Sync | 3 | Scheduler status, trigger, watermark |
-| Core | 2 | Health check + root |
+| Events | 2 | Event log queries |
+| Reporting | 2 | GAM orders + delivery reports |
+| Core | 5 | Health check, root, inventory-sync status/trigger/watermark |
+
+Full inventory: [REST Endpoints reference](https://iabtechlab.github.io/seller-agent/reference/endpoints/).
 
 > [Full API Reference](https://iabtechlab.github.io/seller-agent/api/overview/)
 

docs/api/mcp.md

@@ -1,6 +1,6 @@
 # MCP (Model Context Protocol)
 
-MCP is the **primary interface** for the seller agent. Publishers manage their agent from Claude (desktop or web), ChatGPT, Codex, Cursor, or any MCP-compatible assistant via 41 tools. Buyer agents also call seller tools through MCP for automated workflows.
+MCP is the **primary interface** for the seller agent. Publishers manage their agent from Claude (desktop or web), ChatGPT, Codex, Cursor, or any MCP-compatible assistant via 46 tools. Buyer agents also call seller tools through MCP for automated workflows.
 
 ## Connection
 

docs/api/overview.md

@@ -1,6 +1,6 @@
 # API Overview
 
-The Ad Seller System API exposes **59 endpoints** across **19 tags**. All endpoints are served from a single FastAPI application.
+The Ad Seller System API exposes **87 endpoints** across **25 tags**. All endpoints are served from a single FastAPI application. The complete auto-generated route inventory is in the [REST Endpoints reference](../reference/endpoints.md).
 
 **Base URL:** `http://localhost:8000`
 **OpenAPI docs:** `http://localhost:8000/docs`

docs/architecture/overview.md

@@ -20,7 +20,7 @@ graph LR
     subgraph "Seller Agent"
         MCP_S["/mcp/ (Streamable HTTP)<br/>MCP Server"]
         A2A_S["/a2a/seller/jsonrpc<br/>A2A Server"]
-        REST_S["REST API<br/>58 endpoints"]
+        REST_S["REST API<br/>87 endpoints"]
         NLP[NL Processing]
         TOOLS[Seller Tools]
         FLOWS[CrewAI Flows]
@@ -61,7 +61,7 @@ graph TB
         subgraph "Protocol Layer"
             MCP[MCP Server<br/>/mcp/ Streamable HTTP]
             A2A[A2A Server<br/>/a2a/seller/jsonrpc]
-            API[REST API<br/>58 endpoints, 19 tags]
+            API[REST API<br/>87 endpoints, 25 tags]
         end
 
         AUTH[Auth & API Keys]
@@ -135,7 +135,7 @@ graph TB
 
 ### API Layer
 
-**FastAPI application** with 58 endpoints across 19 OpenAPI tags. Handles HTTP routing, request validation, authentication, and response serialization. See [API Overview](../api/overview.md).
+**FastAPI application** with 87 endpoints across 25 OpenAPI tags. Handles HTTP routing, request validation, authentication, and response serialization. See [API Overview](../api/overview.md).
 
 ### Authentication and Agent Registry
 
@@ -156,9 +156,17 @@ graph TB
 - **DealGenerationFlow** --- Converts accepted proposals into deals with OpenRTB parameters.
 - **DiscoveryInquiryFlow** --- Handles natural-language inventory queries from buyers.
 
+### Connector Layer
+
+Three pluggable connector families move inventory and deals between the seller agent and external systems:
+
+- **AdServerClient** --- Inventory sync and deal setup in the publisher's ad server (Google Ad Manager, FreeWheel, CSV).
+- **SSPClient** --- Deal distribution through SSP exchanges to DSPs (PubMatic MCP, Index Exchange REST, Magnite REST).
+- **DealSyncClient** --- Deal sync through an external deal-sync service. Implementations register in the `DealSyncRegistry` (a peer of the SSP registry); the day-one implementation is `DealsAPIMCPClient`, which pushes negotiated deals to the IAB [deals-api-mcp](https://github.com/IABTechLab/deals-api-mcp) server (IAB Deal Sync API v1.0) over MCP Streamable HTTP. See [deals-api-mcp Integration](../integration/deals-api-mcp.md).
+
 ### Infrastructure
 
-- **Event Bus** --- Emits and stores events for all system activity. 21 event types across 7 categories. See [Event Bus](../event-bus/overview.md).
+- **Event Bus** --- Emits and stores events for all system activity. 22 event types across 7 categories. See [Event Bus](../event-bus/overview.md).
 - **Order State Machine** --- Formal state machine with 12 states and 20 transitions. Full audit trail. See [Order Lifecycle](../state-machines/order-lifecycle.md).
 - **Change Request Manager** --- Handles post-deal modifications with severity classification and approval routing. See [Change Requests](../api/change-requests.md).
 - **Approval Gate** --- Human-in-the-loop approval workflow for proposals and high-value decisions.

docs/event-bus/overview.md

@@ -77,7 +77,7 @@ Each event contains:
 | Field | Type | Description |
 |-------|------|-------------|
 | `event_id` | string | UUID |
-| `event_type` | EventType | One of the 21 event types above |
+| `event_type` | EventType | One of the 22 event types above |
 | `timestamp` | datetime | When the event occurred |
 | `flow_id` | string | Associated workflow flow ID |
 | `flow_type` | string | Type of flow (e.g., `proposal_handling`) |

docs/getting-started/quickstart.md

@@ -62,7 +62,7 @@ Expected response:
 
 ## Browse the API Docs
 
-Open `http://localhost:8000/docs` in a browser for the auto-generated Swagger UI with all 58 endpoints.
+Open `http://localhost:8000/docs` in a browser for the auto-generated Swagger UI with all 87 endpoints.
 
 ## First API Calls
 
@@ -118,6 +118,6 @@ Returns a confirmed deal with a Deal ID, OpenRTB parameters, and DSP activation
 
 ## Next Steps
 
-- [API Overview](../api/overview.md) --- see all 58 endpoints
+- [API Overview](../api/overview.md) --- see all 87 endpoints
 - [Authentication](../api/authentication.md) --- set up API keys for authenticated access
 - [Buyer Agent Integration](../integration/buyer-agent.md) --- connect a buyer agent