Docs freshness sweep: CHANGELOG backfill, version metadata, surface counts, deal-sync docs (#40)

* docs: backfill CHANGELOG into dated 2.1.0–2.3.3 releases; version 2.3.3

Cut the stale [Unreleased] blob into dated release sections assigned by
tag history (git tag dates, first-parent merges per tag range), and add
the missing 2.1.1–2.3.3 entries. [Unreleased] is left empty at the top
for the next release's notes. Bump the long-stale pyproject version
(0.1.0) to the current release, 2.3.3.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: refresh stale surface counts — 46 MCP tools, 87 endpoints, 22 event types

Counts drifted across README and docs while the auto-generated
inventories (docs/reference/) stayed current. Bring every user-facing
count in line with the live registries: 46 MCP tools (was 41), 87 REST
endpoints across 25 OpenAPI tags (was 82/58/59 across 15–19), 22 event
types (was 16/21). Regenerate the README tool-category and
endpoint-group tables from the inventories (the old tables summed to 45
and 76 and cited two tools that no longer exist). Update the Bedrock
model example in the configuration guide to the current id used by
.env.example, and reword the reset_catalog_cache docstring to the
deterministic uuid5 product-id contract (#37 — comment-only change).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: surface reference inventories in nav; document the deal-sync subsystem

Add a Reference section to the mkdocs nav linking the auto-generated
inventories (REST endpoints, MCP tools, event types) that were
previously orphaned, and add the Troubleshooting guide to the Publisher
Guide section. Document the #32 deal-sync connector family
(DealSyncClient / DealSyncRegistry, clients/deal_sync_base.py — a peer
of the SSP registry) in the architecture overview's new Connector Layer
section and in the README architecture diagram, linking the existing
deals-api-mcp integration guide.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: atc964

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