adcontextprotocol · bokelley · May 4, 2026 · May 4, 2026
diff --git a/.changeset/docs-specialism-decision-tree.md b/.changeset/docs-specialism-decision-tree.md
@@ -0,0 +1,14 @@
+---
+---
+
+docs(compliance): add sales-specialism decision tree and deprecate sales-proposal-mode in docs (closes #4038)
+
+Adopters had no consolidated guide for choosing the right `sales-*` specialism — the only option was to read every specialism's narrative block and triangulate. A wrong claim wastes the adopter's first compliance run by grading them against storyboards their architecture doesn't support.
+
+Changes:
+
+- **`compliance-catalog.mdx`** — adds `## Choosing a sales specialism` section (using `<Steps>`) between the media-buy specialism table and `## How to claim`. The tree resolves adopters to `sales-broadcast-tv`, `sales-catalog-driven`, `sales-social`, `sales-guaranteed`, or `sales-non-guaranteed` in three steps, covers the multi-specialism case (hybrid guaranteed + auction platforms), and explains the `media_buy.supports_proposals` capability flag with JSON examples. Also fixes the `sales-proposal-mode` status row from `stable` to `deprecated`.
+
+- **`build-an-agent.mdx`** — removes `sales-proposal-mode` from the typical-specialisms table for `build-seller-agent` and rewrites the "Picking a sales specialism" section to link to the new decision tree and surface the `supports_proposals` flag.
+
+- **`get-test-ready.mdx`** — updates the example `get_adcp_capabilities` response: replaces `sales-proposal-mode` with `sales-guaranteed` + `media_buy.supports_proposals: true`, and fixes `"media-buy"` → `"media_buy"` in `supported_protocols` (wire form is snake_case).
diff --git a/docs/building/by-layer/L4/build-an-agent.mdx b/docs/building/by-layer/L4/build-an-agent.mdx
@@ -99,18 +99,18 @@ Each agent declares its `supported_protocols` (domains) and `specialisms` on `ge
 
 | Skill | Typical `supported_protocols` | Typical `specialisms` (pick one or combine) |
 |---|---|---|
-| `build-seller-agent` | `["media_buy", "creative"]` | `sales-guaranteed`, `sales-non-guaranteed`, `sales-proposal-mode` |
+| `build-seller-agent` | `["media_buy", "creative"]` | `sales-guaranteed`, `sales-non-guaranteed` |
 | `build-generative-seller-agent` | `["media_buy", "creative"]` | `creative-generative` + `sales-non-guaranteed` |
 | `build-retail-media-agent` | `["media_buy", "creative"]` | `sales-catalog-driven` |
 | `build-signals-agent` | `["signals"]` | `signal-owned`, `signal-marketplace` |
 | `build-creative-agent` | `["creative"]` | `creative-ad-server`, `creative-template` |
 
-**Picking a sales specialism:**
-- **`sales-guaranteed`** — you sell with IO approval against rate cards or fixed CPMs. Direct-sold CTV, premium video, broadcast TV, OOH.
-- **`sales-non-guaranteed`** — you sell on a real-time auction with floor pricing. Programmatic display, OLV, audio.
-- **`sales-proposal-mode`** — you negotiate per-buy (custom pricing, custom packages, custom terms), no rate card. Premium publisher direct, sponsorship, native at scale.
+**Picking a sales specialism:** See [Choosing a sales specialism](/docs/building/verification/compliance-catalog#choosing-a-sales-specialism) in the Compliance Catalog for the full decision tree. Quick reference:
+- **`sales-guaranteed`** — IO approval, fixed pricing. Set `media_buy.supports_proposals: true` if you support RFP/proposal flows; `false` (or omit) for direct-buy only.
+- **`sales-non-guaranteed`** — auction / PMP.
+- **`sales-broadcast-tv`**, **`sales-catalog-driven`**, **`sales-social`** — channel-specific; see the decision tree.
 
-You can claim more than one if you genuinely operate that way — but each claim adds a storyboard you must pass. Claim only what you sell. See the [Compliance Catalog](/docs/building/verification/compliance-catalog) for the full taxonomy and per-specialism storyboards.
+You can claim more than one. See the [Compliance Catalog](/docs/building/verification/compliance-catalog) for the full taxonomy and per-specialism storyboards.
 
 Building a **brand rights** agent (licensing talent, music, stock media)? There's no skill today — see the [Brand Protocol docs](/docs/brand-protocol) and claim `brand-rights` under the `brand` domain.
 
@@ -192,7 +192,7 @@ media_buy_seller (9 steps)
 </Warning>
 
 <Tip>
-Each skill includes variant storyboards for different business models — non-guaranteed, guaranteed with approval, proposal mode, and more. Run `npx @adcp/client@latest storyboard list` to see all available storyboards.
+Each skill includes variant storyboards for different business models — non-guaranteed, guaranteed with approval, direct-buy guaranteed, and more. Run `npx @adcp/client@latest storyboard list` to see all available storyboards.
 </Tip>
 
 See **[Validate Your Agent](/docs/building/verification/validate-your-agent)** for the full testing workflow — debugging failing steps, running compliance checks, and validating interactively through Addie.

diff --git a/docs/building/verification/compliance-catalog.mdx b/docs/building/verification/compliance-catalog.mdx
@@ -91,7 +91,7 @@ Specialisms are grouped below by parent protocol.
 |-----------|--------|---------|
 | `sales-guaranteed` | stable | Guaranteed media buys with human IO approval |
 | `sales-non-guaranteed` | stable | Non-guaranteed auction-based media buys |
-| `sales-proposal-mode` | stable | Media buys negotiated via proposal acceptance |
+| `sales-proposal-mode` | deprecated | **Deprecated in 3.1.** Drop this claim and replace with `sales-guaranteed` + `media_buy.supports_proposals: true`. See [#3823](https://github.com/adcontextprotocol/adcp/issues/3823). |
 | `sales-catalog-driven` | stable | Catalog-driven commerce with conversion tracking |
 | `sales-broadcast-tv` | stable | Broadcast linear TV with guaranteed inventory and FCC cancellation rules |
 | `sales-social` | stable | Social media advertising platform with self-service flows |
@@ -141,6 +141,73 @@ Specialisms are grouped below by parent protocol.
 |-----------|--------|---------|
 | `brand-rights` | stable | Brand identity and rights licensing (talent, music, stock media) |
 
+## Choosing a sales specialism
+
+The `sales-*` specialisms are not mutually exclusive — a hybrid platform with both a guaranteed direct desk and an auction floor should claim both `sales-guaranteed` and `sales-non-guaranteed`. Follow the steps below to resolve your claim.
+
+<Warning>
+**`sales-proposal-mode` is deprecated in 3.1.** Do not claim it for new agents. Existing agents that declare it must drop it entirely and replace it with `sales-guaranteed` + `media_buy.supports_proposals: true` in `get_adcp_capabilities`. See [#3823](https://github.com/adcontextprotocol/adcp/issues/3823).
+</Warning>
+
+<Steps>
+
+<Step title="Is your inventory channel-specific?">
+
+Three specialisms apply to specific delivery channels and have their own storyboards. If you only sell one of these channel types, claim only the matching specialism. If you also sell general display or video inventory outside these channels, continue to Step 2.
+
+| If you operate… | Claim |
+|---|---|
+| Broadcast linear TV with FCC cancellation rules | `sales-broadcast-tv` |
+| Catalog-driven dynamic ads (product listings, restaurant menus, hotel listings, local commerce) | `sales-catalog-driven` |
+| Social platform with platform-managed creative | `sales-social` |
+
+</Step>
+
+<Step title="What purchase model do you support?">
+
+| If you sell… | Claim |
+|---|---|
+| Guaranteed media (IO approval, fixed pricing) | `sales-guaranteed` → see Step 3 |
+| Auction / PMP non-guaranteed | `sales-non-guaranteed` |
+| Both guaranteed and non-guaranteed | `sales-guaranteed` + `sales-non-guaranteed` |
+
+</Step>
+
+<Step title="Set media_buy.supports_proposals (sales-guaranteed only)">
+
+`media_buy.supports_proposals` is a boolean in the `media_buy` capabilities block of your `get_adcp_capabilities` response. It gates whether the `proposal_finalize` compliance scenario runs.
+
+| If you… | Set |
+|---|---|
+| Accept RFPs, generate proposals, and finalize to committed status before IO | `media_buy.supports_proposals: true` |
+| Sell direct-buy guaranteed only (auction PG, retail SKU, quoted-rate — no RFP flow) | `media_buy.supports_proposals: false` (or omit — default is `false`) |
+
+```jsonc
+// Full-service guaranteed seller — proposal lifecycle graded
+{
+  "supported_protocols": ["media_buy"],
+  "specialisms": ["sales-guaranteed"],
+  "media_buy": {
+    "supports_proposals": true
+  }
+}
+```
+
+```jsonc
+// Direct-buy guaranteed seller — proposal scenario skipped as capability_unsupported
+{
+  "supported_protocols": ["media_buy"],
+  "specialisms": ["sales-guaranteed"],
+  "media_buy": {
+    "supports_proposals": false
+  }
+}
+```
+
+</Step>
+
+</Steps>
+
 ## How to claim
 
 Declare your protocols and specialisms in `get_adcp_capabilities`:

diff --git a/docs/building/verification/get-test-ready.mdx b/docs/building/verification/get-test-ready.mdx
@@ -23,12 +23,15 @@ You ship these three surfaces. The runner owns storyboard selection, fixture ord
 
 `get_adcp_capabilities` is how the runner picks which storyboards apply to you. It is also the [conformance](/docs/building/verification/conformance) contract: you are promising to pass every storyboard that matches what you declare.
 
-The example below is for a guaranteed + proposal seller. A broadcast-TV seller would claim `sales-broadcast-tv`; a creative-only agent would claim the `creative` protocol with `creative-hosting` or `creative-generative` specialisms; a signals provider would claim `signals`. The pattern is the same: declare only what you actually implement.
+The example below is for a full-service guaranteed seller (proposal lifecycle enabled). A direct-buy guaranteed seller would set `media_buy.supports_proposals: false` (or omit it). A broadcast-TV seller would claim `sales-broadcast-tv`; a creative-only agent would claim the `creative` protocol with `creative-ad-server` or `creative-generative` specialisms; a signals provider would claim `signals`. The pattern is the same: declare only what you actually implement.
 
 ```json
 {
-  "supported_protocols": ["media-buy", "creative"],
-  "specialisms": ["sales-guaranteed", "sales-proposal-mode"],
+  "supported_protocols": ["media_buy", "creative"],
+  "specialisms": ["sales-guaranteed"],
+  "media_buy": {
+    "supports_proposals": true
+  },
   "account": {
     "sandbox": true,
     "require_operator_auth": false

diff --git a/docs/learning/specialist/media-buy.mdx b/docs/learning/specialist/media-buy.mdx
@@ -23,7 +23,7 @@ Agents in the `media_buy` domain declare specific flows they support via the `sp
 |---|---|---|
 | `sales-guaranteed` | stable | Guaranteed media buys with human IO approval |
 | `sales-non-guaranteed` | stable | Non-guaranteed auction-based media buys |
-| `sales-proposal-mode` | stable | Media buys negotiated via proposal acceptance |
+| `sales-proposal-mode` | deprecated | **Deprecated in 3.1.** Replace with `sales-guaranteed` + `media_buy.supports_proposals: true`. |
 | `sales-catalog-driven` | stable | Catalog-driven commerce with conversion tracking |
 | `sales-broadcast-tv` | stable | Broadcast linear TV with guaranteed inventory and FCC cancellation rules |
 | `sales-social` | stable | Social media advertising platform with self-service flows |

diff --git a/docs/learning/tracks/publisher.mdx b/docs/learning/tracks/publisher.mdx
@@ -208,7 +208,7 @@ Declare `media_buy` in `supported_protocols` and choose the specialism that matc
 
 - `sales-guaranteed` — guaranteed with human IO approval
 - `sales-non-guaranteed` — auction-based
-- `sales-proposal-mode` — proposal-negotiated
+- `sales-proposal-mode` — **deprecated in 3.1**; use `sales-guaranteed` + `media_buy.supports_proposals: true` instead
 - `sales-catalog-driven` — catalog-driven commerce with conversion tracking
 - `sales-broadcast-tv` — broadcast linear TV
 - `sales-social` — social platform with self-service flows