@adcp/sdk 6.13.2 → 6.15.0

package/skills/build-retail-media-agent/SKILL.md

@@ -5,20 +5,18 @@ description: Use when building an AdCP retail media network agent — a platform
 
 # Build a Retail Media Agent
 
-A retail media agent sells on-site placements driven by a product catalog and reports conversion outcomes back to buyers. The fastest path is to **fork a seller adapter** and add the catalog-driven surface (`syncCatalogs`, `syncEventSources`, `logEvent`, `providePerformanceFeedback`) on top.
+A retail media agent sells on-site placements driven by a product catalog and reports conversion outcomes back to buyers. The fastest path is to **fork a worked seller adapter** and replace its `// SWAP:` markers with calls to your backend.
 
 ## Pick your fork target
 
-There's no dedicated `hello_retail_media_adapter_*.ts` yet — retail-media is additive on top of `sales-non-guaranteed`, so adopters fork the seller adapter and add the catalog surface.
+| Specialism             | Status  | Fork this                                                                         | Mock upstream                       | Storyboard             |
+| ---------------------- | ------- | --------------------------------------------------------------------------------- | ----------------------------------- | ---------------------- |
+| `sales-catalog-driven` | stable  | [`hello_seller_adapter_social.ts`](../../examples/hello_seller_adapter_social.ts) | `npx adcp mock-server sales-social` | `sales_catalog_driven` |
+| `sales-retail-media`   | preview | Same                                                                              | Same                                | placeholder            |
 
-| Specialism | Status | Fork this | Add | Storyboard |
-| --- | --- | --- | --- | --- |
-| `sales-catalog-driven` | stable | [`hello_seller_adapter_non_guaranteed.ts`](../../examples/hello_seller_adapter_non_guaranteed.ts) | `syncCatalogs`, `syncEventSources`, `logEvent`, `providePerformanceFeedback` | `sales_catalog_driven` |
-| `sales-retail-media` | preview | Same | + retail-specific surface encoding in `publisher_properties` / `format_ids` (search vs PDP vs homepage vs offsite vs in-store) | placeholder |
+The social fork target is the closest baseline because it already implements the catalog-driven surface (`syncCatalogs`, `syncEventSources`, `logEvent`) on top of `SalesIngestionPlatform`. Walled-garden social platforms and retail media networks share the same wire-level shape — buyer pushes catalogs and audiences, platform reports conversions, both close the loop via `provide_performance_feedback`. Apply the retail-specific deltas below.
 
-A worked retail-media fork target is tracked as a follow-up. Until then, the seller `hello_seller_adapter_non_guaranteed.ts` is the closest baseline; the deltas are in [`docs/llms.txt`](../../docs/llms.txt) under `#### \`sync_catalogs\``, `#### \`sync_event_sources\``, `#### \`log_event\``, `#### \`provide_performance_feedback\``.
-
-For exact response shapes, error codes, and optional fields, `docs/llms.txt` is the canonical reference.
+For exact response shapes, error codes, and optional fields, [`docs/llms.txt`](../../docs/llms.txt) is the canonical reference. The fork target stays in sync with the spec because PR #1394's three-gate contract fails CI when it drifts.
 
 ## When to use this skill
 
@@ -36,31 +34,39 @@ For exact response shapes, error codes, and optional fields, `docs/llms.txt` is
 
 ## Cross-cutting rules
 
-Every retail-media agent hits the cross-cutting rules in [`../cross-cutting.md`](../cross-cutting.md). Plus all the seller cross-cutting from [`../build-seller-agent/SKILL.md`](../build-seller-agent/SKILL.md) — retail-media is additive on top of the seller baseline. The high-traffic ones for retail-media (deep-linked to the rule):
+Every retail-media agent hits the cross-cutting rules in [`../cross-cutting.md`](../cross-cutting.md) plus the seller cross-cutting from [`../build-seller-agent/SKILL.md`](../build-seller-agent/SKILL.md) — retail-media is additive on top of the seller baseline. The high-traffic ones for retail-media:
+
+- [`idempotency_key`](../cross-cutting.md#idempotency_key-is-required-on-every-mutating-call) on `sync_catalogs`, `sync_event_sources`, `log_event`, `provide_performance_feedback`
+- [Webhooks](../cross-cutting.md#webhooks-stable-operation_id-across-retries) — for catalog-ingestion completions, use `catalog_sync.${catalog_id}.${batch_id}` as the stable `operation_id`
+- [SHAPE-GOTCHAS §6](../SHAPE-GOTCHAS.md#6-log_event-projection-for-walled-garden-capis) — `log_event` field-name + UNIX-seconds + `user_match` projections (shared with sales-social CAPIs)
+
+## Specialism deltas
 
-- [`idempotency_key`](../cross-cutting.md#idempotency_key-is-required-on-every-mutating-call) on `sync_catalogs`, `sync_event_sources`, `log_event`, `provide_performance_feedback` (in addition to the seller-side mutating tools)
-- [Webhooks](../cross-cutting.md#webhooks-stable-operation_id-across-retries) — for catalog-ingestion completions, use `catalog_sync.${catalog_id}.${batch_id}` as a stable `operation_id`
+### `sales-catalog-driven`
 
-## Specialism deltas at a glance
+What's different from the social baseline you forked:
 
-**`sales-catalog-driven`** —
+- **Products declare catalog support**: `supports_catalog: true` and `supports_conversion_tracking: true` on each `Product`.
+- **`create_media_buy` accepts `packages[].catalogs[]`** — references to previously-synced catalog ids. The seller renders the dynamic ad from the catalog row at serve time.
+- **`sync_catalogs`** ingests product feeds (JSON / CSV / XML). Required per-row fields: `product_id`, `title`, `price`, `image_url`, `category`. Reject rows missing any of these with a structured error and surface the per-row failures in the response.
+- **`sync_event_sources`** registers conversion endpoints — `purchase`, `add_to_cart`, `page_view`, `search`. Each event source has a `source_id` the buyer references on subsequent `log_event` calls.
+- **`log_event` accepts `content_ids`** — the catalog row IDs the conversion attaches to. Counter-only responses pass the storyboard today; closed-loop attribution lands in 3.1.
+- **`provide_performance_feedback`** accepts buyer optimization signals (clicked / not-clicked / converted / not-converted on specific impressions). Use it to close the bid-quality loop.
 
-- Products declare `supports_catalog: true` and `supports_conversion_tracking: true`
-- `create_media_buy` accepts `packages[].catalogs[]` referencing previously-synced catalog ids
-- `sync_catalogs` ingests product feeds (JSON/CSV/XML) with at minimum `product_id`, `title`, `price`, `image_url`, `category`
-- `sync_event_sources` registers conversion endpoints (purchase, add_to_cart, page_view, search)
-- `log_event` accepts conversion events with `content_ids` and returns a `match_quality` score; counter-only responses pass the storyboard (closed-loop attribution lands in 3.1)
-- `provide_performance_feedback` accepts buyer optimization signals back
+### `sales-retail-media`
 
-**`sales-retail-media`** — currently a v3.1 placeholder (empty `phases`). Ship the catalog-driven baseline plus retail-specific surface encoding in `publisher_properties` / `format_ids`. Claim the specialism to advertise intent.
+Currently a v3.1 placeholder (empty `phases` in `index.yaml`); the protocol baseline is all that's enforced today. Claim the specialism to advertise intent. The forward-looking deltas on top of `sales-catalog-driven`:
 
-Attribution linkage (`log_event.content_ids` → catalog `item_id` → `media_buy_id`) is deliberately out-of-scope for AdCP 3.0 — the storyboard accepts counter-only responses. Closed-loop attribution + ROAS reporting land in 3.1.
+- **Onsite placement encoding** in `publisher_properties` and `format_ids` — search results, product detail page (PDP), homepage, category, offsite (display retargeting), in-store (DOOH).
+- **Sponsored-product vs sponsored-display** distinction surfaces as separate `format_ids` per product.
+- **Offsite + in-store** require `publisher_properties.environment` to disambiguate the rendering surface (web vs DOOH vs CTV) — the buyer's targeting overlays vary by environment.
+- **Closed-loop ROAS** lands with attribution in 3.1.
 
 ## Validate locally
 
 ```bash
-# Run the fork-matrix gate against the seller-non-guaranteed baseline
-npm run compliance:fork-matrix -- --test-name-pattern="hello-seller-adapter-non-guaranteed"
+# Run the fork-matrix gate against the social baseline
+npm run compliance:fork-matrix -- --test-name-pattern="hello-seller-adapter-social"
 
 # Or validate your forked agent directly against the catalog-driven storyboard
 adcp storyboard run http://127.0.0.1:3005/mcp sales_catalog_driven \
@@ -73,7 +79,7 @@ For deeper validation: [`docs/guides/VALIDATE-YOUR-AGENT.md`](../../docs/guides/
 
 ## Common shape gotchas
 
-`get_media_buy_delivery /reporting_period/start|end` are ISO 8601 **date-time** strings, not date-only. Per-package billing rows require `package_id`, `spend`, `pricing_model`, `rate`, `currency`. `sync_accounts` rows require `action: 'created' | 'updated' | 'unchanged' | 'failed'`. See [`../SHAPE-GOTCHAS.md`](../SHAPE-GOTCHAS.md).
+`get_media_buy_delivery /reporting_period/start|end` are ISO 8601 **date-time** strings, not date-only. Per-package billing rows require `package_id`, `spend`, `pricing_model`, `rate`, `currency`. `sync_accounts` rows require `action: 'created' | 'updated' | 'unchanged' | 'failed'`. See [`../SHAPE-GOTCHAS.md`](../SHAPE-GOTCHAS.md) and [§6](../SHAPE-GOTCHAS.md#6-log_event-projection-for-walled-garden-capis) for `log_event` field-rename + UNIX-seconds patterns shared with social CAPIs.
 
 ## Migration notes
 

package/skills/build-seller-agent/SKILL.md

@@ -11,14 +11,19 @@ A seller agent receives briefs from buyers, returns products, accepts media buys
 
 Each of these is a worked, currently-running, three-gate-tested reference adapter. Fork it, swap the upstream, ship.
 
-| Specialism | Fork this | Mock upstream | Storyboard |
-| --- | --- | --- | --- |
-| `sales-guaranteed` | [`hello_seller_adapter_guaranteed.ts`](../../examples/hello_seller_adapter_guaranteed.ts) | `npx adcp mock-server sales-guaranteed` | `sales_guaranteed` |
-| `sales-non-guaranteed` | [`hello_seller_adapter_non_guaranteed.ts`](../../examples/hello_seller_adapter_non_guaranteed.ts) | `npx adcp mock-server sales-non-guaranteed` | `sales_non_guaranteed` |
-| `sales-social` | [`hello_seller_adapter_social.ts`](../../examples/hello_seller_adapter_social.ts) | `npx adcp mock-server sales-social` | `sales_social` |
-| Multi-tenant holdco hub | [`hello_seller_adapter_multi_tenant.ts`](../../examples/hello_seller_adapter_multi_tenant.ts) | composed | per specialism |
+| Specialism              | Fork this                                                                                         | Mock upstream                               | Storyboard             |
+| ----------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------- | ---------------------- |
+| `sales-guaranteed`      | [`hello_seller_adapter_guaranteed.ts`](../../examples/hello_seller_adapter_guaranteed.ts)         | `npx adcp mock-server sales-guaranteed`     | `sales_guaranteed`     |
+| `sales-non-guaranteed`  | [`hello_seller_adapter_non_guaranteed.ts`](../../examples/hello_seller_adapter_non_guaranteed.ts) | `npx adcp mock-server sales-non-guaranteed` | `sales_non_guaranteed` |
+| `sales-social`          | [`hello_seller_adapter_social.ts`](../../examples/hello_seller_adapter_social.ts)                 | `npx adcp mock-server sales-social`         | `sales_social`         |
+| Multi-tenant holdco hub | [`hello_seller_adapter_multi_tenant.ts`](../../examples/hello_seller_adapter_multi_tenant.ts)     | composed                                    | per specialism         |
 
-The other sales-* specialisms (`sales-broadcast-tv`, `sales-streaming-tv`, `sales-exchange`, `sales-proposal-mode`) currently fork from `sales-guaranteed` or `sales-non-guaranteed` and apply specialism deltas — see `specialisms/<id>.md`. `sales-streaming-tv` and `sales-exchange` are preview specialisms with placeholder storyboards (claim them to advertise intent; baseline is all that's enforced today).
+The other sales-\* specialisms reuse one of the primary fork targets and apply specialism deltas:
+
+- [`sales-broadcast-tv`](specialisms/sales-broadcast-tv.md) — forks `hello_seller_adapter_guaranteed.ts`; deltas around DMA, GRP, daypart, agency estimate number, measurement windows.
+- [`sales-streaming-tv`](specialisms/sales-streaming-tv.md) — forks `hello_seller_adapter_guaranteed.ts`; deltas around CTV (audience-vs-program targeting, reach/freq forecast). Preview specialism — placeholder storyboard.
+- [`sales-proposal-mode`](specialisms/sales-proposal-mode.md) — forks `hello_seller_adapter_proposal_mode.ts`; deltas around `ProposalManager` two-platform composition, `ctx.recipes` hydration, sole-stateful exemption.
+- `sales-exchange` — forks `hello_seller_adapter_non_guaranteed.ts`; preview specialism (placeholder storyboard).
 
 For exact response shapes, error codes, and optional fields, `docs/llms.txt` is the canonical reference. The fork target stays in sync with the spec because PR #1394's three-gate contract fails CI when it drifts.
 
@@ -38,7 +43,7 @@ For exact response shapes, error codes, and optional fields, `docs/llms.txt` is
 
 ## Cross-cutting rules
 
-Every sales-* seller hits the cross-cutting rules in [`../cross-cutting.md`](../cross-cutting.md). The high-traffic ones for sellers (deep-linked to the rule):
+Every sales-\* seller hits the cross-cutting rules in [`../cross-cutting.md`](../cross-cutting.md). The high-traffic ones for sellers (deep-linked to the rule):
 
 - [`idempotency_key`](../cross-cutting.md#idempotency_key-is-required-on-every-mutating-call) on every mutating request — `create_media_buy`, `update_media_buy`, `sync_creatives`, `sync_audiences`, etc.
 - [Resolve-then-authorize](../cross-cutting.md#resolve-then-authorize--uniform-errors-for-not-found--not-yours) — byte-equivalent errors for `media_buy_id` cross-tenant lookups
@@ -53,6 +58,7 @@ The fork target covers the baseline. Specialism subpages cover the deltas — wh
 - [`specialisms/sales-guaranteed.md`](specialisms/sales-guaranteed.md) — **read before coding if you claim `sales-guaranteed`**: IO-task envelope, three `create_media_buy` return shapes (task envelope / `pending_creatives` / `active`), `TERMS_REJECTED` on aggressive `measurement_terms`. Applying only the task-envelope path fails 5 storyboard `create_media_buy` steps.
 - [`specialisms/sales-non-guaranteed.md`](specialisms/sales-non-guaranteed.md) — **read if your inventory clears at request time** (programmatic auction, no HITL approval): sync confirmation, `bid_price`, `update_media_buy` for in-flight changes.
 - [`specialisms/sales-broadcast-tv.md`](specialisms/sales-broadcast-tv.md) — **read if you sell linear / broadcast TV**: `agency_estimate_number`, Ad-ID `industry_identifiers`, `measurement_windows` (Live/C3/C7).
+- [`specialisms/sales-streaming-tv.md`](specialisms/sales-streaming-tv.md) — **read if you sell CTV / OTT streaming inventory** (preview): audience-vs-program targeting, reach/freq forecast, frequency caps.
 - [`specialisms/sales-social.md`](specialisms/sales-social.md) — **read if you're a social platform** (Snap, Meta, TikTok, etc.): additive — claim alongside `sales-non-guaranteed`. Adds `sync_audiences`, `sync_catalogs` (DPA), `log_event` (conversions), `get_account_financials`.
 - [`specialisms/sales-proposal-mode.md`](specialisms/sales-proposal-mode.md) — **read if you negotiate via proposals before line-itemizing**: `proposals[]` with `budget_allocations`, `buying_mode: 'refine'`.
 - [`specialisms/audience-sync.md`](specialisms/audience-sync.md) — **read if buyers push audiences to you** (walled-garden + identity-provider patterns): `sync_audiences` track. Hashed identifiers, match-rate telemetry.

package/skills/build-seller-agent/deployment.md

@@ -8,7 +8,7 @@ Companion to [`SKILL.md`](./SKILL.md). Read this only when you need deployment s
 
 - **Mounting under an existing Express app** (especially alongside OAuth 2.1 Authorization Server routes like `mcpAuthRouter({ provider })`) — use `createExpressAdapter`.
 - **Stdio transport** — for CLI / desktop / local-subprocess agents.
-- **Hand-rolled HTTP** — when even `createExpressAdapter` doesn't fit; `createAdcpServer().connect(transport)` is the raw escape hatch.
+- **Hand-rolled HTTP** — when even `createExpressAdapter` doesn't fit; `createAdcpServerFromPlatform(...).connect(transport)` is the raw escape hatch.
 
 ### Multi-host HTTP
 
@@ -16,16 +16,23 @@ Pass functions for `publicUrl` and `protectedResource`, branch on `ctx.host` in
 
 ```typescript
 import { UnknownHostError, hostname } from '@adcp/sdk';
-import { verifyBearer } from '@adcp/sdk/server';
-import { serve, createAdcpServer } from '@adcp/sdk/server/legacy/v5';
-
-// Host → adapter config. Whatever shape suits your deployment (DB, env, static).
-// Cache the CONFIG (not the AdcpServer). serve() still instantiates the
-// server per request today, but a config Map keeps the expensive part
-// (handler bundle, idempotency store, DB pool) at module scope.
-const adapters = new Map<string, { name: string; handlers: MediaBuyHandlers }>([
-  ['snap.agentic-adapters.scope3.com', { name: 'Snap seller', handlers: snapHandlers }],
-  ['meta.agentic-adapters.scope3.com', { name: 'Meta seller', handlers: metaHandlers }],
+import {
+  createAdcpServerFromPlatform,
+  serve,
+  verifyBearer,
+  type DecisioningPlatform,
+} from '@adcp/sdk/server';
+
+declare const snapPlatform: DecisioningPlatform;
+declare const metaPlatform: DecisioningPlatform;
+
+// Host → platform. Whatever shape suits your deployment (DB, env, static).
+// Cache the PLATFORM (not the AdcpServer). serve() still instantiates the
+// server per request today, but a platform Map keeps the expensive part
+// (platform handlers, idempotency store, DB pool) at module scope.
+const adapters = new Map<string, { name: string; platform: DecisioningPlatform }>([
+  ['snap.agentic-adapters.scope3.com', { name: 'Snap seller', platform: snapPlatform }],
+  ['meta.agentic-adapters.scope3.com', { name: 'Meta seller', platform: metaPlatform }],
   // ... one entry per hostname you front
 ]);
 
@@ -40,11 +47,9 @@ serve(
     // UnknownHostError → 404 (generic body, routing table stays off the wire).
     // Any other thrown error still surfaces as 500.
     if (!cfg) throw new UnknownHostError(`No adapter configured for ${ctx.host}`);
-    return createAdcpServer({
+    return createAdcpServerFromPlatform(cfg.platform, {
       name: cfg.name,
       version: '1.0.0',
-      resolveAccount: async (ref, { authInfo }) => lookupAccount(ctx.host, ref, authInfo),
-      mediaBuy: cfg.handlers,
     });
   },
   {
@@ -77,9 +82,9 @@ Each unique host runs its resolver once and the result is cached. Every host adv
 
 **Unknown hosts: throw `UnknownHostError` from the factory.** `serve()` catches it and responds 404 with a generic body (the routing table never crosses the wire). Throwing any other `Error` stays as a 500 so unrelated bugs remain loud.
 
-**Factory runs per request.** `serve()` calls the factory on every incoming request (to avoid cross-request state bleed). By default it closes the returned server at the end of each request — so caching the `AdcpServer` from one call to the next is unsafe without opt-in. Keep the default-path factory cheap: look up a pre-built adapter config from a module-scoped `Map`, and let `createAdcpServer(...)` build a fresh wrapper from that config on every call.
+**Factory runs per request.** `serve()` calls the factory on every incoming request (to avoid cross-request state bleed). By default it closes the returned server at the end of each request — so caching the `AdcpServer` from one call to the next is unsafe without opt-in. Keep the default-path factory cheap: look up a pre-built platform from a module-scoped `Map`, and let `createAdcpServerFromPlatform(...)` build a fresh wrapper from that platform on every call.
 
-**Pass `reuseAgent: true` to cache `AdcpServer` instances per host.** When the tool-registration cost inside `createAdcpServer(...)` is a measurable part of request latency (common in multi-host deployments with many tools per host), flip the flag and cache the returned server in the factory:
+**Pass `reuseAgent: true` to cache `AdcpServer` instances per host.** When the tool-registration cost inside `createAdcpServerFromPlatform(...)` is a measurable part of request latency (common in multi-host deployments with many tools per host), flip the flag and cache the returned server in the factory:
 
 ```typescript
 const agents = new Map<string, AdcpServer>();
@@ -89,11 +94,9 @@ serve(
     if (!agent) {
       const cfg = adapters.get(ctx.host);
       if (!cfg) throw new UnknownHostError(`No adapter for ${ctx.host}`);
-      agent = createAdcpServer({
+      agent = createAdcpServerFromPlatform(cfg.platform, {
         name: cfg.name,
         version: '1.0.0',
-        resolveAccount: cfg.resolveAccount,
-        mediaBuy: cfg.handlers,
       });
       agents.set(ctx.host, agent);
     }
@@ -117,18 +120,19 @@ When your agent is _both_ an OAuth 2.1 AS (issues tokens) and a protected resour
 
 ```typescript
 import express from 'express';
-import { createExpressAdapter, verifyBearer, anyOf, verifyApiKey } from '@adcp/sdk/server';
-import { createAdcpServer } from '@adcp/sdk/server/legacy/v5';
+import {
+  createAdcpServerFromPlatform,
+  createExpressAdapter,
+  verifyBearer,
+  anyOf,
+  verifyApiKey,
+} from '@adcp/sdk/server';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { mcpAuthRouter } from '@modelcontextprotocol/sdk/server/auth/router.js';
 
-const agent = createAdcpServer({
+const agent = createAdcpServerFromPlatform(snapPlatform, {
   name: 'Snap seller',
   version: '1.0.0',
-  resolveAccount: async (ref, { authInfo }) => lookupAccount(ref, authInfo),
-  mediaBuy: {
-    /* ... */
-  },
 });
 
 const adapter = createExpressAdapter({
@@ -192,7 +196,7 @@ The shape when one Node process fronts N hostnames AND each hostname is also its
 ```typescript
 import express from 'express';
 import {
-  createAdcpServer,
+  createAdcpServerFromPlatform,
   createExpressAdapter,
   verifyBearer,
   resolveHost,
@@ -218,11 +222,9 @@ const app = express();
 // AS routes, and the MCP endpoint.
 const routersByHost = new Map<string, express.Router>();
 for (const [host, cfg] of adapters) {
-  const agent = createAdcpServer({
+  const agent = createAdcpServerFromPlatform(cfg.platform, {
     name: cfg.name,
     version: '1.0.0',
-    resolveAccount: async (ref, { authInfo }) => cfg.lookupAccount(ref, authInfo),
-    mediaBuy: cfg.handlers,
   });
 
   const adapter = createExpressAdapter({
@@ -390,15 +392,11 @@ You own: the `mcpAuthRouter` wiring (provider-specific), the per-request `transp
 
 ```typescript
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { createAdcpServer } from '@adcp/sdk/server/legacy/v5';
+import { createAdcpServerFromPlatform } from '@adcp/sdk/server';
 
-const server = createAdcpServer({
+const server = createAdcpServerFromPlatform(localSellerPlatform, {
   name: 'Local Seller',
   version: '1.0.0',
-  resolveAccount: async ref => lookupAccount(ref),
-  mediaBuy: {
-    /* ... */
-  },
 });
 
 await server.connect(new StdioServerTransport());

package/skills/build-seller-agent/specialisms/audience-sync.md

@@ -2,60 +2,30 @@
 
 Companion to [`../SKILL.md`](../SKILL.md). The SKILL.md baseline applies; this file covers only the deltas for `audience-sync`.
 
-Storyboard: `audience_sync`. Track is `audiences` — separate from the core seller lifecycle, but lives in this skill because identifier sync and account discovery sit next to media-buying.
-
-Required tools: `sync_audiences` and `list_accounts`. `sync_audiences` is overloaded — it handles three cases through its request payload:
-
-- **Discovery**: call with no `audiences` array (or empty). Returns the audiences already on the platform for the account.
-- **Add**: each audience entry has an `add: [{ hashed_email }, { hashed_phone }, ...]` array of hashed identifiers.
-- **Delete**: each audience entry has `delete: true`.
-
-There is no separate `delete_audience` tool — deletion rides on `sync_audiences`.
-
-```typescript
-createAdcpServer({
-  accounts: {
-    syncAccounts: /* baseline */,
-    listAccounts: async (params, ctx) => {
-      const { items } = await ctx.store.list('accounts');
-      const brandFilter = params.brand?.domain;
-      return { accounts: brandFilter ? items.filter((a) => a.brand.domain === brandFilter) : items };
-    },
-  },
-  eventTracking: {
-    syncAudiences: async (params, ctx) => {
-      // Discovery mode — no audiences in request
-      if (!params.audiences?.length) {
-        const { items } = await ctx.store.list('audiences');
-        return { audiences: items.map((a) => ({ audience_id: a.audience_id, name: a.name, status: 'active' as const })) };
-      }
-      // Add / delete mode
-      return {
-        audiences: await Promise.all(params.audiences.map(async (a) => {
-          if (a.delete) {
-            await ctx.store.delete('audiences', a.audience_id);
-            return { audience_id: a.audience_id, name: a.name, action: 'deleted' as const, status: 'inactive' as const };
-          }
-          const identifiers = a.add ?? [];
-          const uploaded = identifiers.length;
-          const matched = Math.floor(uploaded * 0.72);   // simulated match rate
-          await ctx.store.put('audiences', a.audience_id, { ...a, uploaded, matched });
-          return {
-            audience_id: a.audience_id,
-            name: a.name,
-            action: 'created' as const,
-            status: 'active' as const,
-            uploaded_count: uploaded,
-            matched_count: matched,
-            effective_match_rate: uploaded ? matched / uploaded : 0,
-          };
-        })),
-      };
-    },
-  },
-});
-```
-
-**Identifier rules:** each `add` entry is a single-identifier object (`{hashed_email}` OR `{hashed_phone}`, not both). Values are SHA-256 of lowercased, trimmed input. Salting/normalization is out-of-band between buyer and platform — document your expected input format.
-
-**Platform types:** destinations span `['dsp', 'retail_media', 'social', 'audio', 'pmax']`. Each has its own `activation_key` shape — see `skills/build-signals-agent/SKILL.md` for activation patterns, which are shared across signals and audience sync.
+**Fork target**: [`examples/hello_seller_adapter_social.ts`](../../../examples/hello_seller_adapter_social.ts) is the worked, passing reference for the audience surface — it already implements `syncAudiences` + `listAccounts` against an `AudiencePlatform` and a walled-garden mock upstream. Replace the `// SWAP:` markers with calls to your real backend. See [SHAPE-GOTCHAS.md](../../SHAPE-GOTCHAS.md) for response-shape pitfalls.
+
+Storyboard: `audience_sync` (track `audiences`).
+
+## What's different from the social baseline
+
+`audience-sync` is the **audiences-only slice** of `sales-social` — same `AudiencePlatform` surface, no `SalesCorePlatform` (no `getProducts` / `createMediaBuy`). Single-specialism `audience-sync` adopters are typically identity providers / data onboarders that don't sell media inventory; they push hashed audiences upstream and report match rates.
+
+If you also sell media (Snap, Meta, TikTok, retail media), claim **both** `audience-sync` and `sales-social` (or whichever sales specialism fits) and keep the full `SalesIngestionPlatform`.
+
+## Tool surface (audience-only)
+
+- `sync_audiences` — overloaded by request payload:
+  - **Discovery**: empty/missing `audiences` array → return audiences already on the platform for the account.
+  - **Add**: each audience entry has `add: [{ hashed_email } | { hashed_phone } | …]` — hashed identifiers to push.
+  - **Delete**: each audience entry has `delete: true` (no separate `delete_audience` tool).
+- `list_accounts` — buyer-side account discovery; supports `brand` filter.
+
+## Identifier rules
+
+Each `add` entry is a **single-identifier object** (`{hashed_email}` OR `{hashed_phone}`, never both in one entry). Values are SHA-256 of lowercased, trimmed input. Salting/normalization is out-of-band between buyer and platform — document your expected input format in your `capabilities.features`.
+
+Drop entries that fail your validation rather than synthesize identifiers — see [SHAPE-GOTCHAS §6.3](../../SHAPE-GOTCHAS.md#63-hashed-identifier-requirement--read-eventuser_match-drop-on-empty) for the parallel pattern on `log_event`.
+
+## Activation destinations
+
+Destinations span `['dsp', 'retail_media', 'social', 'audio', 'pmax']`. Each has its own `activation_key` shape — see [SHAPE-GOTCHAS §1](../../SHAPE-GOTCHAS.md#1-activationkey-oneof--keyvalue-are-top-level-not-nested) for the flat-vs-nested gotcha and `skills/build-signals-agent/SKILL.md` for the broader activation-polling pattern (shared across signals and audience sync).

package/skills/build-seller-agent/specialisms/sales-broadcast-tv.md

@@ -2,70 +2,69 @@
 
 Companion to [`../SKILL.md`](../SKILL.md). The SKILL.md baseline applies; this file covers only the deltas for `sales-broadcast-tv`.
 
-Storyboard: `media_buy_broadcast_seller`. Broadcast has four protocol surfaces not used in digital.
+**Fork target**: [`examples/hello_seller_adapter_guaranteed.ts`](../../../examples/hello_seller_adapter_guaranteed.ts) — broadcast linear inventory is guaranteed by definition (spots are reserved against demo'd ratings). Inherit the IO-task envelope, three `create_media_buy` return shapes, and `targeting_overlay` echo pattern from [`sales-guaranteed.md`](sales-guaranteed.md). Replace the `// SWAP:` markers with calls to your traffic / ratings stack and apply the broadcast deltas below.
 
-**Forecast surface**: `'reach_freq'` or `'package'`. Broadcast plans aren't quoted in spend curves — buyers want unique reach and frequency at a planned weight (GRPs), or a fully-priced package. Project your reach/freq tool (Nielsen, etc.) onto `Product.forecast` points where each point's `metrics` includes `reach_unique`, `frequency_avg`, `grps`, `spend`, and a `package: { spots, dayparts }` breakdown. Use `'package'` when the seller quotes a fixed bundle of spots; use `'reach_freq'` when the buyer is exploring weight levels. See [Delivery Forecasts § CTV with GRP Demographics](https://adcontextprotocol.org/docs/media-buy/product-discovery/media-products#ctv-with-grp-demographics) for the canonical worked example.
+Storyboard: `media_buy_broadcast_seller`. See [SHAPE-GOTCHAS.md](../../SHAPE-GOTCHAS.md) for response-shape pitfalls.
 
-**Pricing** — unit-based (cost per spot). Until a `pricing_model: 'unit'` lands, express as CPM with a very high `fixed_price` that represents the cost per thousand spots equivalent, or use a custom pricing option ID and clarify in `description`.
+## What's different from `sales-guaranteed`
 
-**Agency estimate number** — top-level on `create_media_buy`. Echo it on the response:
+Five protocol surfaces digital sellers don't use: GRP-based forecasting, DMA + daypart targeting overlays, agency estimate numbers, per-package measurement terms, and Ad-ID validation on creatives.
 
-```typescript
-{
-  media_buy_id,
-  agency_estimate_number: params.agency_estimate_number,  // "PNNL-NM-2026-Q4-0847"
-  status: 'submitted',
-  // ...
-}
-```
+## Forecast surface — `'reach_freq'` or `'package'`
 
-**Measurement terms** — per-package on the request:
+Broadcast plans aren't quoted in spend curves:
 
-```typescript
-packages: [
-  {
-    product_id: 'primetime_30s_mf',
-    measurement_terms: {
-      billing_measurement: {
-        vendor: { domain: 'videoamp.com' },
-        measurement_window: 'c7',
-        max_variance_percent: 10,
-      },
-    },
-  },
-];
-```
+- **`reach_freq`** — unique reach + frequency at a planned weight. Each `Product.forecast.points[i].metrics` includes `reach_unique`, `frequency_avg`, `grps`, `spend`. Use when the buyer is exploring weight levels.
+- **`package`** — fully-priced spot bundle. Add `metrics.package: { spots, dayparts }` per point.
+
+See [Delivery Forecasts § CTV with GRP Demographics](https://adcontextprotocol.org/docs/media-buy/product-discovery/media-products#ctv-with-grp-demographics) for the worked example (it covers GRP-based linear too).
+
+## DMA + daypart targeting
+
+DMA codes (Designated Market Areas) ride on `targeting_overlay.geo`; daypart codes (`early_morning`, `daytime`, `prime_access`, `prime`, `late_news`, `overnight`) ride on `targeting_overlay.dayparts`. Echo on `get_media_buys` per the `sales-guaranteed` `targeting_overlay` echo rule — `createMediaBuyStore` handles persistence verbatim. The seller is responsible for collapsing DMA + daypart overlays into the correct station-and-time inventory upstream.
+
+## Pricing — unit-based (cost per spot)
 
-Echo `measurement_terms` on the response's package entries — the buyer uses `c7` as the guarantee basis for reconciliation.
+Until a `pricing_model: 'unit'` lands, express as CPM with a high `fixed_price` representing cost-per-thousand-spots equivalent, or use a custom `pricing_option_id` and clarify in `pricing_options[].description`.
 
-**Ad-ID on creatives** — `sync_creatives` rejects spots without a valid Ad-ID:
+## Agency estimate number
+
+Top-level on `create_media_buy`. Echo on the response next to `media_buy_id` (e.g., `agency_estimate_number: "PNNL-NM-2026-Q4-0847"`).
+
+## Measurement terms — per-package on the request
+
+Buyers send `packages[].measurement_terms.billing_measurement` with `vendor`, `measurement_window` (`'live' | 'c3' | 'c7'`), and `max_variance_percent`. Echo on response package entries — the buyer uses `c7` as the guarantee basis for reconciliation.
+
+## Ad-ID validation on `sync_creatives`
+
+Reject spots without a valid Ad-ID in `industry_identifiers`:
 
 ```typescript
-syncCreatives: async (params) => ({
-  creatives: params.creatives.map((c) => {
-    const adId = c.industry_identifiers?.find((x) => x.type === 'ad_id')?.value;
-    if (!adId) return { creative_id: c.creative_id, action: 'created', status: 'rejected',
-      rejection_reason: 'Ad-ID required for broadcast spots' };
-    return { creative_id: c.creative_id, action: 'created', status: 'accepted' };
-  }),
-}),
+const adId = c.industry_identifiers?.find(x => x.type === 'ad_id')?.value;
+if (!adId) {
+  return {
+    creative_id: c.creative_id,
+    action: 'created',
+    status: 'rejected',
+    rejection_reason: 'Ad-ID required for broadcast spots',
+  };
+}
 ```
 
-**Measurement windows on products** — `reporting_capabilities.measurement_windows` is an **array of objects**, not string enum values. Each window object must match `MeasurementWindowSchema`:
+## Measurement windows — array of objects, not enum strings
+
+`reporting_capabilities.measurement_windows` is an array of `MeasurementWindow` objects. Don't pass bare strings (`['live', 'c3', 'c7']`) — the schema rejects them:
 
 ```typescript
-reporting_capabilities: {
-  // ...standard reporting fields...
-  measurement_windows: [
-    { window_id: 'live', duration_days: 0, expected_availability_days: 1,  is_guarantee_basis: false },
-    { window_id: 'c3',   duration_days: 3, expected_availability_days: 4,  is_guarantee_basis: false },
-    { window_id: 'c7',   duration_days: 7, expected_availability_days: 8,  is_guarantee_basis: true },
-  ],
-}
+measurement_windows: [
+  { window_id: 'live', duration_days: 0, expected_availability_days: 1, is_guarantee_basis: false },
+  { window_id: 'c3', duration_days: 3, expected_availability_days: 4, is_guarantee_basis: false },
+  { window_id: 'c7', duration_days: 7, expected_availability_days: 8, is_guarantee_basis: true },
+];
 ```
 
-Don't declare `measurement_windows: ['live', 'c3', 'c7']` — the Zod schema rejects bare strings and your product won't validate.
+Each delivery row tags `measurement_window`, `is_final`, and `supersedes_window` (for window upgrades). Live ratings mature in 24h, C3 in ~4d, C7 in ~8d. Final reconciliation lands ~15d after last air date.
 
-**Measurement windows on delivery** — each delivery row tags `measurement_window: 'live' | 'c3' | 'c7'`, `is_final: boolean`, and `supersedes_window` (for window upgrades). Live ratings mature in 24h, C3 in ~4d, C7 in ~8d. Final reconciliation lands ~15d after last air date.
+## Window-update webhooks
 
-**Emit window_update webhooks** via `ctx.emitWebhook` (see [§ Webhooks](#webhooks-async-completion-signed-outbound) above). Use `operation_id: \`window_update.${media_buy_id}.${stage}\`` so C3 → C7 supersession retries share a stable idempotency_key.
+Emit via `ctx.emitWebhook` with `operation_id: \`window_update.${media_buy_id}.${stage}\`` so C3 → C7 supersession retries share a stable idempotency key. See [`../../cross-cutting.md` § Webhooks](../../cross-cutting.md#webhooks-stable-operation_id-across-retries).

package/skills/build-seller-agent/specialisms/sales-proposal-mode.md

@@ -2,48 +2,50 @@
 
 Companion to [`../SKILL.md`](../SKILL.md). The SKILL.md baseline applies; this file covers only the deltas for `sales-proposal-mode`.
 
-Storyboard: `media_buy_proposal_mode`. The acceptance path inverts the baseline — buyer sends `proposal_id` + `total_budget`, no `packages`.
-
-`get_products` returns a `proposals[]` array alongside products:
-
-```typescript
-return {
-  products: PRODUCTS,
-  proposals: [
-    {
-      proposal_id: 'balanced_reach_q2',
-      name: 'Balanced Reach Plan',
-      rationale: 'CTV for premium reach, OLV for sports frequency, display for always-on context.',
-      total_budget: { amount: 50000, currency: 'USD' },
-      budget_allocations: [
-        { product_id: 'ctv_outdoor_lifestyle', pricing_option_id: 'ctv_cpm', amount: 25000, currency: 'USD' },
-        { product_id: 'olv_sports', pricing_option_id: 'olv_cpm', amount: 15000, currency: 'USD' },
-        { product_id: 'display_endemic', pricing_option_id: 'display_cpm', amount: 10000, currency: 'USD' },
-      ],
-      forecast: { impressions: 3_500_000, reach: 1_200_000, frequency: 2.9 },
-    },
-  ],
-  sandbox: true,
-};
-```
-
-Handle `buying_mode: 'refine'` by returning an updated `proposals[]` plus `refinement_applied[]` describing what changed.
-
-`create_media_buy` with `proposal_id`:
-
-```typescript
-createMediaBuy: async (params, ctx) => {
-  if (params.proposal_id) {
-    const proposal = PROPOSALS[params.proposal_id];
-    if (!proposal) return adcpError('INVALID_REQUEST', { message: `Unknown proposal_id: ${params.proposal_id}` });
-    // TTL check — return PROPOSAL_EXPIRED if the proposal has aged out
-    return {
-      media_buy_id: `mb_${randomUUID()}`,
-      status: 'active' as const,       // instant on proposal accept
-      proposal_id: proposal.proposal_id,
-      packages: proposal.budget_allocations.map((a, i) => ({ /* expand server-side */ })),
-    };
-  }
-  // ... fall through to baseline packages path
-},
-```
+**Fork target**: [`examples/hello_seller_adapter_proposal_mode.ts`](../../../examples/hello_seller_adapter_proposal_mode.ts) is the worked, passing reference adapter for this specialism. It demonstrates the v1.5 `ProposalManager` + `DecisioningPlatform` two-platform composition: `ProposalManager` curates, refines, and finalizes; `SalesCorePlatform.createMediaBuy` reads the committed recipe from `ctx.recipes` and creates the order. Replace the `// SWAP:` markers with calls to your real backend. See [SHAPE-GOTCHAS.md](../../SHAPE-GOTCHAS.md) for response-shape pitfalls.
+
+Storyboard: `media_buy_seller/proposal_finalize` (subset of `media_buy_seller`).
+
+## What's different from the baseline seller flow
+
+The acceptance path inverts the baseline. Instead of the buyer composing a `packages[]` array and calling `create_media_buy`, the seller curates a media plan, the buyer iterates, and `create_media_buy(proposal_id=…, total_budget=…)` accepts the locked plan in one call.
+
+Three new surfaces:
+
+| Surface             | Owned by            | Does                                                                                            |
+| ------------------- | ------------------- | ----------------------------------------------------------------------------------------------- |
+| `get_products`      | `ProposalManager`   | Returns curated `proposals[]` alongside `products[]` when the request carries a `brief`.        |
+| `refine_products`   | `ProposalManager`   | Applies buyer asks to a draft proposal, returns updated `proposals[]` + `refinement_applied[]`. |
+| `finalize_proposal` | `ProposalManager`   | Locks pricing, hands committed recipes to the framework's `InMemoryProposalStore`.              |
+| `create_media_buy`  | `SalesCorePlatform` | Reads `ctx.recipes` (hydrated from the committed proposal); never re-fetches upstream.          |
+
+The framework owns proposal-state transitions (`draft → committed → consumed`) via `InMemoryProposalStore`. The adapter is stateless — it projects upstream proposal documents onto the AdCP wire shape and lets the framework manage lifecycle.
+
+## `ctx_metadata` for proposal-side identifiers
+
+The fork target stashes the network code on the resolved account (`ctx.account.ctx_metadata.network_code`) so every proposal call routes to the correct upstream tenant without re-resolving. **Do not put bearer tokens or signing secrets in `ctx_metadata`** — re-derive credentials from `ctx.authInfo` per call. See [`docs/guides/CTX-METADATA-SAFETY.md`](../../../docs/guides/CTX-METADATA-SAFETY.md).
+
+`ProposalManager.finalizeProposal` writes `upstream_ids.proposal_id` and `upstream_ids.line_item_template_id` onto the recipe. Those non-secret upstream IDs are exactly what `ctx_metadata` is for; the framework persists them in the committed-proposal store and rehydrates them in `sales.createMediaBuy(ctx)`.
+
+## Sole-stateful-step exemption
+
+The proposal-mode storyboard treats `finalize_proposal` as a sole stateful step in some scenarios — when the only stateful peer (e.g., a parallel governance check) was skipped, the runner applies the sole-stateful-step exemption (`adcp#4053`, `adcp-client#1146/#1545`) so the downstream `create_media_buy` step doesn't cascade-skip. The fork target's tests cover this branch (`hello_seller_adapter_proposal_mode` exercises the exemption path under the storyboard runner).
+
+If your adapter fails this scenario with `cascade-skip-on-skip`, check that `finalize_proposal` returns a populated `recipes` map — an empty map looks to the runner like the proposal didn't commit, which suppresses the exemption.
+
+## Refinement loop
+
+`refine_products` accepts a `refine[]` array on the request. Each entry has `scope: 'request' | 'proposal'` and (when `scope='proposal'`) a `proposal_id` plus an `ask` string. Return:
+
+- Updated `proposals[]` reflecting the applied ask.
+- `refinement_applied[]` echoing each `refine[]` entry with `status: 'applied' | 'rejected'` so the buyer can audit which asks landed.
+
+Reject `refine_products` calls without at least one `scope: 'proposal'` entry — there's nothing to refine.
+
+## TTL + `PROPOSAL_EXPIRED`
+
+Committed proposals carry `expires_at`. On `create_media_buy(proposal_id=…)`, validate the TTL; return structured `PROPOSAL_EXPIRED` (use the SDK's typed-error helper) if the proposal aged out. The framework's `expiresAtGraceSeconds` capability lets you tolerate clock skew (the fork target sets 60 seconds).
+
+## When `proposal_id` is missing
+
+Sellers that **only** accept proposals (no direct package-based buying) should reject `create_media_buy` without `proposal_id` with `INVALID_REQUEST` and a hint pointing at the proposal flow. The fork target shows the pattern. Sellers that accept both can fall through to the baseline packages path.