@adcp/sdk 6.14.0 → 6.15.1

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

@@ -2,76 +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.
+**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.
 
-Required tools: `sync_audiences` and `list_accounts`. `sync_audiences` is overloaded — it handles three cases through its request payload:
+Storyboard: `audience_sync` (track `audiences`).
 
-- **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`.
+## What's different from the social baseline
 
-There is no separate `delete_audience` tool — deletion rides on `sync_audiences`.
+`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.
 
-```typescript
-import {
-  createAdcpServerFromPlatform,
-  definePlatform,
-  defineAudiencePlatform,
-} from '@adcp/sdk/server';
+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`.
 
-const platform = definePlatform({
-  capabilities: {
-    specialisms: ['audience-sync', 'sales-non-guaranteed'] as const,
-    pricingModels: ['cpm'] as const,
-  },
-  accounts: {
-    resolve: async (ref, ctx) => /* lookup */ null,
-    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 };
-    },
-  },
-  audiences: defineAudiencePlatform({
-    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,
-          };
-        })),
-      };
-    },
-  }),
-});
+## Tool surface (audience-only)
 
-const server = createAdcpServerFromPlatform(platform, {
-  name: 'Audience-sync seller',
-  version: '1.0.0',
-});
-```
+- `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}`, 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.
+## Identifier rules
 
-**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.
+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.

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

@@ -0,0 +1,45 @@
+# Specialism: sales-streaming-tv
+
+Companion to [`../SKILL.md`](../SKILL.md). The SKILL.md baseline applies; this file covers only the deltas for `sales-streaming-tv`.
+
+**Status: preview.** The storyboard is a placeholder (`phases: []` in `index.yaml`); claim the specialism to advertise CTV intent. Today only the protocol baseline is enforced — the deltas below are forward-looking guidance so adopters write CTV-shaped responses now and gate-pass when phases land.
+
+**Fork target**: [`examples/hello_seller_adapter_guaranteed.ts`](../../../examples/hello_seller_adapter_guaranteed.ts) — CTV reservation inventory is guaranteed (impressions + audience). Inherit the IO-task envelope, three `create_media_buy` return shapes, and `targeting_overlay` echo pattern from [`sales-guaranteed.md`](sales-guaranteed.md). Apply the streaming deltas below. See [SHAPE-GOTCHAS.md](../../SHAPE-GOTCHAS.md) for response-shape pitfalls.
+
+## What's different from `sales-guaranteed`
+
+CTV sits between digital and broadcast. The buyer wants impressions and audience guarantees (digital), but the planning surface uses GRP-style reach/freq (broadcast). The differences from `sales-guaranteed` are mostly about which targeting / pricing axes you surface, not new protocol shapes.
+
+## Audience-vs-program targeting
+
+CTV inventory is sold two ways; the seller chooses per product:
+
+- **Audience-bought** — buyer specifies demos / segments via `targeting_overlay.audiences` and `targeting_overlay.signals`. Seller resolves to whichever programs match. Most CTV inventory ships this way.
+- **Program-bought** — buyer specifies titles / shows / genres via `targeting_overlay.contextual` (or a publisher-property list). Seller fulfills against that exact program slate.
+
+Declare which axis a product supports via its `format_ids` and `publisher_properties`. Don't accept program targeting on an audience-bought product — surface `INVALID_REQUEST` with a hint pointing at the supported overlay path. The `targeting_overlay` echo rule from [`sales-guaranteed.md`](sales-guaranteed.md) applies — persist verbatim, echo verbatim.
+
+## Forecast surface — `'reach_freq'` or `'availability'`
+
+CTV planning uses both:
+
+- **`reach_freq`** — unique reach + frequency on a target demo at planned weight. Each `Product.forecast.points[i].metrics` includes `reach_unique`, `frequency_avg`, `grps` (or `irps` for incremental reach), `spend`.
+- **`availability`** — for fully-spec'd reservations (single point, `metrics.impressions` + `metrics.audience_size`, `metrics.spend` is the quoted cost, no `budget`).
+
+Choose per product / per query. Drive from your real demo-projection upstream (Nielsen, VideoAmp, iSpot) — static `availability` blobs read as placeholder during the storyboard.
+
+## Day-of-week + daypart on streaming
+
+Live streaming inventory honors the broadcast `dayparts` enum (`early_morning`, `daytime`, `prime_access`, `prime`, `late_news`, `overnight`). VOD / library inventory typically ignores daypart — surface `INVALID_REQUEST` with a hint if the buyer sends `targeting_overlay.dayparts` against a VOD-only product.
+
+## Measurement windows — same shape as broadcast
+
+CTV billing typically settles on a digital window (`served`) or a panel-blended window (`c3` / `c7` for cross-screen reach). Use the broadcast `measurement_windows` shape from [`sales-broadcast-tv.md`](sales-broadcast-tv.md#measurement-windows--array-of-objects-not-enum-strings) — array of `MeasurementWindow` objects, not enum strings.
+
+## Frequency caps
+
+CTV buyers cap on user-day or user-campaign basis. Surface via `Product.frequency_capping_options` and accept on `packages[].frequency_caps`. Sellers that can't enforce a requested cap should reject with `INVALID_REQUEST` rather than silently dropping the cap.
+
+## Cross-screen attribution
+
+Cross-screen attribution (CTV → mobile / web) lands in AdCP 3.1 alongside the closed-loop attribution surface — out of scope for the 3.0 baseline. Sellers can attach `measurement_partners` to a product and let the buyer subscribe to the feed out-of-band.

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

@@ -9,25 +9,14 @@ A signals agent serves audience and contextual targeting segments to buyer agent
 
 ## Pick your fork target
 
-| Specialism | Archetype | Fork this | Mock upstream | Storyboard |
-| --- | --- | --- | --- | --- |
-| `signal-marketplace` | Multi-provider data marketplace (Oracle Data Cloud, LiveRamp, third-party data) | [`hello_signals_adapter_marketplace.ts`](../../examples/hello_signals_adapter_marketplace.ts) | `npx adcp mock-server signal-marketplace` | `signal_marketplace` |
-| `signal-owned` | First-party / single-provider data (CDP, identity provider, contextual) | Fork the marketplace adapter; see [deletion list below](#what-to-delete-if-youre-single-specialism-signal-owned) | — | `signal_owned` |
+| Specialism           | Archetype                                                                       | Fork this                                                                                            | Mock upstream                             | Storyboard           |
+| -------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------- |
+| `signal-marketplace` | Multi-provider data marketplace (Oracle Data Cloud, LiveRamp, third-party data) | [`hello_signals_adapter_marketplace.ts`](../../examples/hello_signals_adapter_marketplace.ts)        | `npx adcp mock-server signal-marketplace` | `signal_marketplace` |
+| `signal-owned`       | First-party / single-provider data (CDP, identity provider, contextual)         | Same — fork the marketplace adapter and apply the [single-provider deltas below](#specialism-deltas) | Same                                      | `signal_owned`       |
 
-Both specialisms share the same tool surface (`get_signals`, `activate_signal`, `list_accounts`); the difference is whether you serve segments from multiple `data_provider_domain` values or one. A `signal-owned` adapter is the marketplace adapter with the multi-provider directory simplified to a single seed.
+Both specialisms share the same tool surface (`get_signals`, `activate_signal`, `list_accounts`); the difference is whether you serve segments from multiple `data_provider_domain` values or one.
 
-### What to delete if you're single-specialism `signal-owned`
-
-**Forking the marketplace adapter for a `signal-owned` agent? Delete or replace these seams** — leaning on stable symbol names rather than line numbers (the adapter evolves; greppable identifiers don't):
-
-- Replace the multi-provider seed (the `UpstreamCohort` array seeded with multiple `data_provider_domain` / `data_provider_id` / `data_provider_name` triples) with your single-provider catalog. Every cohort gets the same `data_provider_domain` (your domain) and `data_provider_name` (your brand).
-- Strip the marketplace-discovery code paths in `getSignals` that filter `signals[]` by `(data_provider_domain, data_provider_id)` pairs — single-provider adopters either return everything or filter on signal id alone.
-- Set `signal_type: 'owned'` (not `'marketplace'`) in the `toAdcpSignal` projection. See [SHAPE-GOTCHAS §7](../SHAPE-GOTCHAS.md#7-signal_type-marketplace-vs-owned-vs-custom) for the `marketplace`/`owned`/`custom` decision table.
-- Drop the marketplace governance sub-scenario in your storyboard run if you don't model multi-provider consent flows — `signal_owned` storyboard is simpler.
-
-**Keep**: the `accounts` / `createTenantStore` block (single-tenant adapters pass one tenant entry), `agentRegistry`, the `signals` SignalsPlatform block (`getSignals`, `activateSignal`, `listAccounts`), platform vs agent activation polling logic, `forceDeploymentStatus` for compliance-test determinism.
-
-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.
+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. See [SHAPE-GOTCHAS.md](../SHAPE-GOTCHAS.md) — particularly [§1](../SHAPE-GOTCHAS.md#1-activationkey-oneof--keyvalue-are-top-level-not-nested) (flat `activation_key.key/value`), [§2](../SHAPE-GOTCHAS.md#2-signal_ids-is-signal_id-provenance-objects-not-string) (`signal_ids` is `SignalID[]`, not `string[]`), and [§7](../SHAPE-GOTCHAS.md#7-signal_type-marketplace-vs-owned-vs-custom) (`marketplace` / `owned` / `custom` decision).
 
 ## When to use this skill
 
@@ -61,11 +50,23 @@ Platform activations (`type: 'platform'`) take minutes-to-hours to propagate to
 
 Buyers fetch `https://{domain}/adagents.json` out-of-band to verify the provider. Use real domains even in demos, not `example.com`. For marketplace adopters, seed ≥2 different `data_provider_domain` values so the multi-provider nature is visible to the storyboard.
 
-## Specialism deltas at a glance
+## Specialism deltas
+
+### `signal-marketplace` (the baseline fork target)
+
+Multi-provider directory: `signals[].data_provider_domain` varies across cohorts. Platform-activation polling pattern is fully exercised. The marketplace governance sub-scenario in the storyboard exercises consent flows across providers; if you can't model multi-provider consent yet, surface `INVALID_REQUEST` rather than silently fall through. Use `signal_type: 'marketplace'` only when `data_provider_domain` resolves to a real `adagents.json`.
+
+### `signal-owned` (single-provider)
+
+Forking the marketplace adapter for a `signal-owned` agent? Apply these deltas — leaning on stable symbol names rather than line numbers (the adapter evolves; greppable identifiers don't):
 
-**`signal-marketplace`** — multi-provider directory (`signals[].data_provider_domain` varies), platform-activation polling pattern, marketplace governance sub-scenario in the storyboard exercises consent flows.
+- **Replace the multi-provider seed.** The adapter ships an `UpstreamCohort` array seeded with multiple `data_provider_domain` / `data_provider_id` / `data_provider_name` triples. Replace with your single-provider catalog: every cohort gets the same `data_provider_domain` (your domain) and `data_provider_name` (your brand).
+- **Strip marketplace-discovery filters in `getSignals`** that filter `signals[]` by `(data_provider_domain, data_provider_id)` pairs — single-provider adopters either return everything or filter on signal id alone.
+- **Set `signal_type: 'owned'`** (not `'marketplace'`) in the `toAdcpSignal` projection. See [SHAPE-GOTCHAS §7](../SHAPE-GOTCHAS.md#7-signal_type-marketplace-vs-owned-vs-custom) for the decision table — `owned` is the default for first-party data agents.
+- **Drop the marketplace governance sub-scenario** from your storyboard run if you don't model multi-provider consent flows. The `signal_owned` storyboard is simpler.
+- **`value_type` drives targeting semantics** for owned segments: `binary` (in/out), `categorical` (with `allowed_values: [...]`), `numeric` (with `min`, `max`, optional `units`).
 
-**`signal-owned`** — single `data_provider_domain` across all signals. `value_type` drives targeting semantics: `binary` (in/out), `categorical` (with `allowed_values: [...]`), `numeric` (with `min`, `max`, optional `units`). For the `signal_type` value (`marketplace`/`owned`/`custom`) decision, see [SHAPE-GOTCHAS §7](../SHAPE-GOTCHAS.md#7-signal_type-marketplace-vs-owned-vs-custom).
+**Keep**: the `accounts` / `createTenantStore` block (single-tenant adapters pass one tenant entry), `agentRegistry`, the `signals` `SignalsPlatform` block (`getSignals`, `activateSignal`, `listAccounts`), platform-vs-agent activation polling logic, `forceDeploymentStatus` for compliance-test determinism.
 
 ## Validate locally