@adcp/sdk 6.14.0 → 6.15.0

package/examples/hello_creative_adapter_ad_server.ts

@@ -66,7 +66,7 @@ import {
   type DecisioningPlatform,
   type SyncCreativesRow,
 } from '@adcp/sdk/server';
-import { FormatAsset } from '@adcp/sdk';
+import { FormatAsset, buildCreativeReturn, previewCreative, urlRender } from '@adcp/sdk';
 import type {
   BuildCreativeRequest,
   BuildCreativeSuccess,
@@ -511,16 +511,17 @@ class CreativeAdServerAdapter implements DecisioningPlatform<Record<string, neve
       // satisfying creative-manifest.json:14. Each `assets[key]` is a
       // discriminated AssetVariant — `asset_type` selects the matching
       // schema (html requires `content`, etc.).
-      return {
-        creative_manifest: {
+      // `buildCreativeReturn.singleEnveloped({...})` injects the wire-shape
+      // discriminator: takes a flat `manifest` field (renamed to
+      // `creative_manifest` on the wire). SHAPE-GOTCHAS §5.
+      return buildCreativeReturn.singleEnveloped({
+        manifest: {
           format_id: { agent_url: FORMAT_AGENT_URL, id: creative.format_id },
           assets: {
             serving_tag: { asset_type: 'html', content: rendered.tag_html },
           },
         },
-        // CAST: oneOf-emitter — picking variant 0 (single creative_manifest)
-        // of the BuildCreativeResponse oneOf. Adopters keep this cast.
-      } as unknown as BuildCreativeSuccess;
+      });
     },
 
     /**
@@ -553,26 +554,24 @@ class CreativeAdServerAdapter implements DecisioningPlatform<Record<string, neve
         });
       }
       const rendered = await upstream.renderCreative(networkCode, creativeId, {});
-      return {
-        response_type: 'single',
+      // `previewCreative.single({...})` injects
+      // `response_type: 'single'`. SHAPE-GOTCHAS §4.
+      return previewCreative.single({
         previews: [
           {
             preview_id: `prv_${creative.creative_id}`,
             renders: [
-              {
+              urlRender({
                 render_id: `rnd_${creative.creative_id}`,
                 preview_url: rendered.preview_url,
                 role: 'primary',
-              },
+              }),
             ],
             input: { name: 'default' },
           },
         ],
         expires_at: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
-        // CAST: oneOf-emitter — picking the `single` discriminator branch
-        // of the PreviewCreativeResponse 3-way union (single | batch | variant).
-        // See SHAPE-GOTCHAS §4. Adopters keep this cast.
-      } as unknown as PreviewCreativeResponse;
+      });
     },
 
     listCreativeFormats: async (_req, _ctx): Promise<ListCreativeFormatsResponse> => {

package/examples/hello_creative_adapter_template.ts

@@ -52,6 +52,8 @@ import {
   javascriptAsset,
   audioAsset,
   urlRender,
+  buildCreativeReturn,
+  previewCreative,
   type Format,
   type ListCreativeFormatsResponse,
   type BuildCreativeRequest,
@@ -446,12 +448,13 @@ class CreativeTemplateAdapter implements DecisioningPlatform<Record<string, neve
         return projectRenderToManifest(completed, { agent_url: PUBLIC_AGENT_URL, id: target.id });
       };
 
-      // Multi-format request — return `CreativeManifest[]`; framework wraps
-      // as `{ creative_manifests: [...] }`. See BuildCreativeReturn (4-arm
-      // discriminated union) — returning the wrong arm fails wire-schema
-      // validation. SHAPE-GOTCHAS.md §5.
+      // `buildCreativeReturn.multi(...)` / `.single(...)` pin which arm of
+      // the 4-shape `BuildCreativeReturn` union you're emitting. The framework
+      // wraps `multi` into `{ creative_manifests: [...] }` and `single` into
+      // `{ creative_manifest: <obj> }` on the wire. SHAPE-GOTCHAS §5.
       if (req.target_format_ids && req.target_format_ids.length > 0) {
-        return Promise.all(req.target_format_ids.map((t, i) => buildOne(t, i)));
+        const manifests = await Promise.all(req.target_format_ids.map((t, i) => buildOne(t, i)));
+        return buildCreativeReturn.multi(manifests);
       }
 
       // Single-format request.
@@ -461,7 +464,7 @@ class CreativeTemplateAdapter implements DecisioningPlatform<Record<string, neve
           field: 'target_format_id',
         });
       }
-      return buildOne(req.target_format_id, 0);
+      return buildCreativeReturn.single(await buildOne(req.target_format_id, 0));
     },
 
     previewCreative: async (req: PreviewCreativeRequest, ctx): Promise<PreviewCreativeResponse> => {
@@ -516,12 +519,11 @@ class CreativeTemplateAdapter implements DecisioningPlatform<Record<string, neve
         throw new AdcpError('INVALID_REQUEST', { message: 'upstream returned no preview_url' });
       }
 
-      // PreviewCreativeResponse is a 3-way discriminated union (single |
-      // batch | variant). Single mode requires `previews[].renders[]` even
-      // for one preview — and each render needs the `output_format`
-      // discriminator. urlRender({...}) injects it. SHAPE-GOTCHAS.md §4.
-      return {
-        response_type: 'single',
+      // `previewCreative.single({...})` injects
+      // `response_type: 'single'`. The render slot's `output_format`
+      // discriminator is in turn injected by `urlRender({...})`.
+      // SHAPE-GOTCHAS §4.
+      return previewCreative.single({
         previews: [
           {
             preview_id: `prv_${created.render_id}`,
@@ -539,7 +541,7 @@ class CreativeTemplateAdapter implements DecisioningPlatform<Record<string, neve
           },
         ],
         expires_at: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
-      };
+      });
     },
   });
 }

package/examples/hello_signals_adapter_marketplace.ts

@@ -36,6 +36,7 @@ import {
   type CachedBuyerAgentRegistry,
 } from '@adcp/sdk/server';
 import type { GetSignalsResponse, ActivateSignalRequest, ActivateSignalSuccess } from '@adcp/sdk/types';
+import { activationKey, signalId } from '@adcp/sdk';
 import { createUpstreamRecorder, toQueryUpstreamTrafficResponse } from '@adcp/sdk/upstream-recorder';
 import { createHash, randomUUID } from 'node:crypto';
 
@@ -292,11 +293,10 @@ function toAdcpSignal(c: UpstreamCohort): GetSignalsResponse['signals'][number]
   const coverage = c.total_universe > 0 ? Math.round((c.member_count / c.total_universe) * 100) : 0;
   return {
     signal_agent_segment_id: c.cohort_id,
-    signal_id: {
-      source: 'catalog',
+    signal_id: signalId.catalog({
       data_provider_domain: c.data_provider_domain,
       id: c.data_provider_id,
-    },
+    }),
     name: c.name,
     description: c.description,
     value_type: c.value_type,
@@ -449,18 +449,16 @@ class SignalMarketplaceAdapter implements DecisioningPlatform<Record<string, nev
               client_request_id: `${idempotency}.${i}`,
             });
             if (dest.type === 'agent') {
-              // ActivationKey oneOf — for `type: 'key_value'`, `key` and `value`
-              // sit at the TOP level (not nested under a `key_value` field).
-              // `value` MUST be string. See skills/SHAPE-GOTCHAS.md §1.
+              // `activationKey.keyValue({...})` injects `type: 'key_value'`
+              // and accepts the flat `{ key, value }` shape. SHAPE-GOTCHAS §1.
               return {
                 type: 'agent' as const,
                 agent_url: dest.agent_url,
                 is_live: true,
-                activation_key: {
-                  type: 'key_value' as const,
+                activation_key: activationKey.keyValue({
                   key: 'agent_segment',
                   value: activation.agent_activation_key?.agent_segment ?? activation.activation_id,
-                },
+                }),
                 deployed_at: new Date().toISOString(),
               };
             }
@@ -468,10 +466,9 @@ class SignalMarketplaceAdapter implements DecisioningPlatform<Record<string, nev
               type: 'platform' as const,
               platform: dest.platform,
               is_live: false,
-              activation_key: {
-                type: 'segment_id' as const,
+              activation_key: activationKey.segment({
                 segment_id: activation.segment_id ?? activation.activation_id,
-              },
+              }),
               estimated_activation_duration_minutes: 30,
             };
           })

package/examples/signals-agent.ts

@@ -18,6 +18,7 @@
 
 import { createAdcpServer, serve } from '@adcp/sdk/server/legacy/v5';
 import { createIdempotencyStore, memoryBackend } from '@adcp/sdk/server';
+import { activationKey, signalId } from '@adcp/sdk';
 import type { GetSignalsResponse, ServeContext } from '@adcp/sdk';
 
 // ---------------------------------------------------------------------------
@@ -28,11 +29,10 @@ type Signal = GetSignalsResponse['signals'][number];
 const SEGMENTS: Signal[] = [
   {
     signal_agent_segment_id: 'high_intent_shoppers',
-    signal_id: {
-      source: 'catalog',
+    signal_id: signalId.catalog({
       data_provider_domain: 'example-signals.com',
       id: 'high_intent_shoppers',
-    },
+    }),
     name: 'High Intent Shoppers',
     description: 'Users who visited product pages 3+ times in the last 7 days without purchasing.',
     value_type: 'binary',
@@ -51,11 +51,10 @@ const SEGMENTS: Signal[] = [
   },
   {
     signal_agent_segment_id: 'lapsed_subscribers',
-    signal_id: {
-      source: 'catalog',
+    signal_id: signalId.catalog({
       data_provider_domain: 'example-signals.com',
       id: 'lapsed_subscribers',
-    },
+    }),
     name: 'Lapsed Subscribers',
     description: 'Email subscribers who have not opened in 90+ days but previously had high engagement.',
     value_type: 'binary',
@@ -74,11 +73,10 @@ const SEGMENTS: Signal[] = [
   },
   {
     signal_agent_segment_id: 'geo_urban_commuters',
-    signal_id: {
-      source: 'catalog',
+    signal_id: signalId.catalog({
       data_provider_domain: 'example-signals.com',
       id: 'geo_urban_commuters',
-    },
+    }),
     name: 'Urban Commuters',
     description: 'Users whose location data indicates daily commute patterns through major metro areas.',
     value_type: 'binary',
@@ -171,21 +169,19 @@ function createSignalsAgent({ taskStore }: ServeContext) {
               platform: dest.platform,
               is_live: false,
               estimated_activation_duration_minutes: 30,
-              activation_key: {
-                type: 'segment_id' as const,
+              activation_key: activationKey.segment({
                 segment_id: `${dest.platform}_${params.signal_agent_segment_id}`,
-              },
+              }),
             };
           }
           return {
             type: 'agent' as const,
             agent_url: dest.agent_url,
             is_live: true,
-            activation_key: {
-              type: 'key_value' as const,
+            activation_key: activationKey.keyValue({
               key: 'audience',
               value: params.signal_agent_segment_id,
-            },
+            }),
             deployed_at: new Date().toISOString(),
           };
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "6.14.0",
+  "version": "6.15.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -361,5 +361,5 @@
     },
     "minimatch": "^10.2.1"
   },
-  "adcp_version": "3.0.7"
+  "adcp_version": "3.0.8"
 }

package/skills/SHAPE-GOTCHAS.md

@@ -10,7 +10,7 @@ Six patterns surfaced repeatedly while building reference adapters (`examples/he
 
 When returning `activate_signal` deployments with `type: 'key_value'` activation keys, `key` and `value` sit at the TOP level of `activation_key`. NOT nested under a `key_value` sub-field.
 
-✗ Wrong (intuitive — the discriminator name *suggests* nesting):
+✗ Wrong (intuitive — the discriminator name _suggests_ nesting):
 
 ```ts
 activation_key: {
@@ -37,6 +37,17 @@ activation_key: { type: 'segment_id', segment_id: 'plat_seg_xyz' }
 
 — same flatness, single string ID under the discriminator.
 
+**Prevent at write time:** import `activationKey` from `@adcp/sdk`. The
+typed factory injects the `type` discriminator and accepts the flat shape:
+
+```ts
+activation_key: activationKey.keyValue({ key: 'segment', value: 'abc123' });
+activation_key: activationKey.segment({ segment_id: 'plat_seg_xyz' });
+```
+
+The nested-`key_value` mistake doesn't typecheck — `activationKey.keyValue`
+takes `{ key, value }`, not `{ key_value: {...} }`.
+
 ---
 
 ## 2. `signal_ids` is `signal_id[]` (provenance objects), not `string[]`
@@ -46,7 +57,9 @@ activation_key: { type: 'segment_id', segment_id: 'plat_seg_xyz' }
 ✗ Wrong:
 
 ```ts
-{ signal_ids: ['cohort_abc', 'cohort_xyz'] }
+{
+  signal_ids: ['cohort_abc', 'cohort_xyz'];
+}
 ```
 
 ✓ Right (matches `/schemas/3.0/core/signal-id.json`):
@@ -62,11 +75,23 @@ activation_key: { type: 'segment_id', segment_id: 'plat_seg_xyz' }
 
 `SignalID` is a discriminated union: `source: 'catalog'` (with `data_provider_domain` + `id`) or `source: 'agent'` (with `agent_url` + `id`). When implementing the filter on the seller side, narrow on `source` before reading `data_provider_domain` — only the catalog variant has it.
 
+**Prevent at write time:** import `signalId` from `@adcp/sdk`. The typed
+factory injects the `source` discriminator and only takes the fields the
+selected variant requires:
+
+```ts
+signalId.catalog({ data_provider_domain: 'tridentauto.example', id: 'likely_ev_buyers' });
+signalId.agent({ agent_url: 'https://liveramp.com/.well-known/adcp/signals', id: 'custom_auto_intenders' });
+```
+
+A bare-string `signal_ids` filter is rejected by the request type as soon
+as you stop typing it as `any`.
+
 ---
 
 ## 3. `VASTAsset` requires an embedded `delivery_type` discriminator
 
-`asset_type: 'vast'` is itself a discriminator at the asset level. A *second* discriminator (`delivery_type`) picks between inline VAST XML and a redirect URL. Both are required; you can't pass `content` or `vast_url` without `delivery_type`.
+`asset_type: 'vast'` is itself a discriminator at the asset level. A _second_ discriminator (`delivery_type`) picks between inline VAST XML and a redirect URL. Both are required; you can't pass `content` or `vast_url` without `delivery_type`.
 
 ✗ Wrong (flat `content` without `delivery_type`):
 
@@ -125,6 +150,28 @@ Same pattern applies to `DAASTAsset` (audio).
 
 Each `PreviewRender` requires `render_id`, `output_format: 'url'` (or `'inline_html'`), `preview_url`, and `role`. Don't omit `role` — the validator requires it.
 
+**Prevent at write time:** import `previewCreative` from
+`@adcp/sdk`. The typed factory injects the `response_type` discriminator
+and pairs naturally with `urlRender({...})` / `htmlRender({...})` /
+`bothRender({...})` for the per-render `output_format`:
+
+```ts
+previewCreative.single({
+  previews: [
+    {
+      preview_id: 'prv_abc',
+      renders: [urlRender({ render_id: 'rnd_1', preview_url: 'https://...', role: 'primary' })],
+      input: { name: 'default' },
+    },
+  ],
+  expires_at: '2026-05-03T00:00:00Z',
+});
+previewCreative.batch({ results: [...] });
+previewCreative.variant({ variant_id, creative_id, previews });
+```
+
+A flat `{ preview: {...} }` shape doesn't typecheck.
+
 ---
 
 ## 5. `BuildCreativeReturn` has 4 valid shapes — framework auto-wraps the bare manifest
@@ -133,13 +180,13 @@ Each `PreviewRender` requires `render_id`, `output_format: 'url'` (or `'inline_h
 
 ```ts
 type BuildCreativeReturn =
-  | CreativeManifest                    // bare single — framework wraps as { creative_manifest: <obj> }
-  | CreativeManifest[]                  // bare multi  — framework wraps as { creative_manifests: <arr> }
-  | BuildCreativeSuccess                // shaped single — passthrough; you set sandbox/expires_at/preview
-  | BuildCreativeMultiSuccess           // shaped multi  — passthrough
+  | CreativeManifest // bare single — framework wraps as { creative_manifest: <obj> }
+  | CreativeManifest[] // bare multi  — framework wraps as { creative_manifests: <arr> }
+  | BuildCreativeSuccess // shaped single — passthrough; you set sandbox/expires_at/preview
+  | BuildCreativeMultiSuccess; // shaped multi  — passthrough
 ```
 
-Easy mistake: return a bare `CreativeManifest` and confirm the response *seems* fine via tests that read `response.format_id` directly. The wire shape after framework wrapping is `response.creative_manifest.format_id` — a level deeper. Storyboards check the wire path; if you didn't go through the framework wrapper in your test, the storyboard will surface "field missing at `creative_manifest.format_id`" while your local test passes.
+Easy mistake: return a bare `CreativeManifest` and confirm the response _seems_ fine via tests that read `response.format_id` directly. The wire shape after framework wrapping is `response.creative_manifest.format_id` — a level deeper. Storyboards check the wire path; if you didn't go through the framework wrapper in your test, the storyboard will surface "field missing at `creative_manifest.format_id`" while your local test passes.
 
 If you need to set `sandbox: true` or attach `preview` previews, return the shaped envelope directly:
 
@@ -151,16 +198,29 @@ return {
 };
 ```
 
+**Prevent at write time:** import `buildCreativeReturn` from `@adcp/sdk`.
+The typed factory pins which arm of the 4-shape union you're emitting and
+handles the singular/plural manifest-field rename for the shaped envelopes:
+
+```ts
+return buildCreativeReturn.single(manifest); // bare — framework wraps as { creative_manifest }
+return buildCreativeReturn.multi(manifests); // bare — framework wraps as { creative_manifests }
+return buildCreativeReturn.singleEnveloped({ manifest, sandbox: true, expires_at });
+return buildCreativeReturn.multiEnveloped({ manifests, sandbox: true });
+```
+
+Mixing `manifest` / `manifests` arms doesn't typecheck.
+
 ---
 
 ## 6. `log_event` projection for walled-garden CAPIs
 
 Sales-social adopters fronting walled-garden conversion APIs translate AdCP's `log_event` wire shape onto the upstream CAPI's. Three projections trip every walled-garden integration on the first pass — the upstream returns `400` and the AdCP wire surface gives no hint that the field name or encoding was the problem.
 
-| AdCP wire (`Event`)                                                            | Walled-garden CAPI                                                                          | Translation                                                                  |
-| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| `event_type` (string)                                                          | `event_name` (string)                                                                       | rename on the way out                                                        |
-| `event_time` (ISO 8601 string)                                                 | `event_time` (UNIX seconds, number)                                                         | `Math.floor(new Date(t).getTime() / 1000)`                                   |
+| AdCP wire (`Event`)                                                                                      | Walled-garden CAPI                                                       | Translation                                                                  |
+| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| `event_type` (string)                                                                                    | `event_name` (string)                                                    | rename on the way out                                                        |
+| `event_time` (ISO 8601 string)                                                                           | `event_time` (UNIX seconds, number)                                      | `Math.floor(new Date(t).getTime() / 1000)`                                   |
 | `user_match` (`hashed_email` / `hashed_phone` / `uids[]` / `click_id` / `client_ip`+`client_user_agent`) | `user_data.{email_sha256,phone_sha256,external_id_sha256}` (≥1 required) | map per the upstream's identifier types; drop events with empty `user_match` |
 
 ### 6.1 `event_name`, not `event_type`
@@ -187,13 +247,17 @@ upstream.trackEvents({
 ✗ Wrong:
 
 ```ts
-{ event_time: e.event_time }                 // '2026-04-05T14:30:00Z'
+{
+  event_time: e.event_time;
+} // '2026-04-05T14:30:00Z'
 ```
 
 ✓ Right:
 
 ```ts
-{ event_time: Math.floor(new Date(e.event_time).getTime() / 1000) }
+{
+  event_time: Math.floor(new Date(e.event_time).getTime() / 1000);
+}
 ```
 
 ### 6.3 Hashed-identifier requirement — read `Event.user_match`, drop on empty
@@ -221,11 +285,11 @@ The `examples/hello_seller_adapter_social.ts` reference adapter codifies all thr
 
 The spec definitions:
 
-| Value | Use when | Example adopter |
-| --- | --- | --- |
-| `marketplace` | Resold third-party segments. Provider's authorization is verifiable via their `adagents.json`. | LiveRamp marketplace; Oracle Data Cloud catalog; reseller of third-party panels |
-| `owned` | First-party segments derived from data the signal agent **directly owns**. | Retailer purchase data (Kroger 84.51°, Walmart Connect); publisher behavioral data (NYT subscribers); telco data |
-| `custom` | Agent-native segment built **on demand** from models, composites, or buyer inputs. Not attributable to a standing upstream provider. | Contextual classifier you train per-request; lookalike model output computed from a buyer's seed audience |
+| Value         | Use when                                                                                                                             | Example adopter                                                                                                  |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `marketplace` | Resold third-party segments. Provider's authorization is verifiable via their `adagents.json`.                                       | LiveRamp marketplace; Oracle Data Cloud catalog; reseller of third-party panels                                  |
+| `owned`       | First-party segments derived from data the signal agent **directly owns**.                                                           | Retailer purchase data (Kroger 84.51°, Walmart Connect); publisher behavioral data (NYT subscribers); telco data |
+| `custom`      | Agent-native segment built **on demand** from models, composites, or buyer inputs. Not attributable to a standing upstream provider. | Contextual classifier you train per-request; lookalike model output computed from a buyer's seed audience        |
 
 **`owned` is the default for first-party data agents.** Most non-marketplace adopters mis-classify their segments as `custom` because the segment was "built" — but the test is provenance, not lifecycle. If you can point at a stable data-asset you own (a customer table, a pixel, a panel), it's `owned`. `custom` is reserved for segments that don't have a standing data asset behind them — the agent computed them per-call.
 

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

@@ -9,16 +9,18 @@ A creative agent accepts assets from buyers, stores or transforms them, and retu
 
 ## Pick your fork target
 
-Three creative archetypes; two have dedicated worked adapters, the third lives in `build-generative-seller-agent` because it's coupled with selling inventory.
+Three creative archetypes. Two have dedicated worked adapters; the third (`creative-generative`) reuses the template adapter and applies brief-to-creative deltas.
 
-| Specialism | Archetype | Fork this | Mock upstream | Storyboard |
-| --- | --- | --- | --- | --- |
-| `creative-ad-server` | Stateful library, pricing + billing (Innovid, Flashtalking, CM360, GAM-creative) | [`hello_creative_adapter_ad_server.ts`](../../examples/hello_creative_adapter_ad_server.ts) | `npx adcp mock-server creative-ad-server` | `creative_ad_server` |
-| `creative-template` | Stateless transform from inline manifest (Celtra, AudioStack, ElevenLabs, Resemble) | [`hello_creative_adapter_template.ts`](../../examples/hello_creative_adapter_template.ts) | `npx adcp mock-server creative-template` | `creative_template` |
-| `creative-generative` | Brief-to-creative generation (AI ad networks coupled with sales) | → `skills/build-generative-seller-agent/` | — | `creative_generative` |
+| Specialism            | Archetype                                                                               | Fork this                                                                                      | Mock upstream                             | Storyboard            |
+| --------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------- | --------------------- |
+| `creative-ad-server`  | Stateful library, pricing + billing (Innovid, Flashtalking, CM360, GAM-creative)        | [`hello_creative_adapter_ad_server.ts`](../../examples/hello_creative_adapter_ad_server.ts)    | `npx adcp mock-server creative-ad-server` | `creative_ad_server`  |
+| `creative-template`   | Stateless transform from inline manifest (Celtra, AudioStack, ElevenLabs, Resemble)     | [`hello_creative_adapter_template.ts`](../../examples/hello_creative_adapter_template.ts)      | `npx adcp mock-server creative-template`  | `creative_template`   |
+| `creative-generative` | Brief-to-creative generation (standalone generative platform; not coupled with selling) | Same — fork the template adapter and apply the [generative deltas below](#creative-generative) | Same                                      | `creative_generative` |
 
 The `interaction_model` in each specialism's `index.yaml` is the forcing function: `stateful_ad_server`, `stateless_transform`, `stateless_generate`. Decide which one matches your business, then fork the adapter for that row.
 
+> **Coupling generation with selling inventory?** That's the AI-ad-network shape (e.g., generative DSPs that sell programmatic inventory and generate the creative). See [`skills/build-generative-seller-agent/`](../build-generative-seller-agent/SKILL.md) — combine `sales-non-guaranteed` + `creative-generative`.
+
 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.
 
 ## When to use this skill
@@ -29,7 +31,7 @@ For exact response shapes, error codes, and optional fields, `docs/llms.txt` is
 **Not this skill:**
 
 - Brief-to-creative generation coupled with selling inventory (AI ad network) → `skills/build-generative-seller-agent/`
-- Publisher creative service that pairs with selling — usually a `build-seller-agent` adopter that omits a creative-* specialism claim
+- Publisher creative service that pairs with selling — usually a `build-seller-agent` adopter that omits a creative-\* specialism claim
 
 ## Cross-cutting rules
 
@@ -90,7 +92,20 @@ curl -H 'Authorization: Bearer mock_creative_template_key_do_not_use_in_prod' \
 # Final: { ..., "status": "complete", "output": { "audio_url": "….mp3", "preview_url": "...", "assets": [{ "kind": "audio_url", "mime_type": "audio/mpeg" }] } }
 ```
 
-**`creative-generative`** — generate from `message` + `brand.domain`; honor `quality: draft|production`; support refinement (re-send manifest in). Goes through `skills/build-generative-seller-agent/` because it's coupled with selling inventory.
+### `creative-generative`
+
+Forking [`hello_creative_adapter_template.ts`](../../examples/hello_creative_adapter_template.ts) for a `creative-generative` agent? Apply these deltas — the template adapter already handles the stateless `build_creative` flow, manifest projection, and async render polling. Generative just changes the **input semantics** (brief, not template inputs) and adds brand resolution.
+
+- **`build_creative` accepts `message` + `brand.domain`** — no `template_id`, no slot inputs. Treat `message` as the creative brief and `brand.domain` as the brand identity.
+- **Honor `quality: draft|production`** — drafts are cheap/fast (lower-quality model, no human review); production goes through full safety + brand checks.
+- **Refinement loop** — buyers re-send the prior `creative_manifest` plus a new `message` to iterate. Detect "iterating on this manifest" by manifest-id presence and route to your refine endpoint instead of generate.
+- **Brand resolution via `sync_accounts`** — buyers sync an account with `brand.domain`; treat that domain as resolvable for subsequent `build_creative` calls. Don't hardcode a brand allowlist; storyboards use fictional `.example` TLD brands.
+- **Response shape stays the same** — `{ creative_manifest: { format_id, assets } }`, **not** `{ creative_id, status, preview_url }` (those are `sync_creatives` fields).
+- **Delete the template-input slot validation** in the template adapter's `build_creative` handler — generative agents accept free-form briefs and can't validate slot presence/types up front.
+
+The `creative_generative` storyboard exercises the same async render contract as `creative_template` — `build_creative` returns a render id, the buyer polls until status flips to complete. The template adapter's polling pattern transfers verbatim.
+
+If your platform also sells inventory (AI ad network), claim both `sales-non-guaranteed` + `creative-generative` and see [`../build-generative-seller-agent/`](../build-generative-seller-agent/SKILL.md) for the combined wiring.
 
 ## Validate locally
 

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