@adcp/sdk 6.6.0 → 6.8.0

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

@@ -9,6 +9,8 @@ description: Use when building an AdCP creative agent — an ad server, creative
 
 A creative agent manages the creative lifecycle: accepts assets from buyers, stores them in a library, builds serving tags, and renders previews. Unlike a generative seller (which also sells inventory), a creative agent is a standalone creative platform — it manages creatives but doesn't sell media.
 
+> **Common shape gotchas:** `PreviewCreativeResponse` is a three-way discriminated union (`single` | `batch` | `variant`); `BuildCreativeReturn` has 4 valid shapes (framework auto-wraps bare manifests); `VASTAsset` requires `delivery_type` (`'inline'` or `'redirect'`) before `content`/`vast_url`. See [SHAPE-GOTCHAS.md](../SHAPE-GOTCHAS.md) for the patterns adopters consistently get wrong on first pass — schema validators catch these at runtime; type checkers don't.
+
 ## When to Use
 
 - User wants to build an ad server, creative management platform, or creative rendering service
@@ -21,6 +23,8 @@ A creative agent manages the creative lifecycle: accepts assets from buyers, sto
 - Selling inventory (no creative management) → `skills/build-seller-agent/`
 - Serving audience segments → `skills/build-signals-agent/`
 
+**Often claimed alongside:** [`creative-generative`](../build-generative-seller-agent/SKILL.md) (hybrid creative platform — template-driven + AI-generated ads share the same library), [`sales-catalog-driven`](../build-retail-media-agent/SKILL.md) (retail-media dynamic-creative rendering). See [Common multi-specialism bundles](../../examples/README.md#common-multi-specialism-bundles).
+
 ## Specialisms This Skill Covers
 
 Creative specialisms are three distinct archetypes with materially different tool contracts. Pick the one that matches your platform — do not try to make one handler cover all three.
@@ -93,6 +97,27 @@ What happens when a creative is synced:
 > **Cross-cutting pitfalls matrix runs keep catching:**
 >
 > - **Declare `capabilities.specialisms: ['creative-ad-server'] as const` (or `'creative-template'` / `'creative-generative'`) on the `DecisioningPlatform` you pass to `createAdcpServerFromPlatform`.** Value is `string[]` of enum ids (not `[{id, version}]`). Agents that don't declare their specialism fail the grader with "No applicable tracks found" even if every tool works — tracks are gated on the specialism claim.
+> - **`list_creative_formats` response — each `Format` MUST have strict-shape `renders[]` and `assets[]`** (matrix v2 PR #1207 keeps catching this).
+>   - `renders[i]` requires `role` (string) PLUS exactly one of `dimensions: { width, height }` (object — NOT `{ width, height }` inline at the render root) OR `parameters_from_format_id: true`.
+>   - `assets[i]` requires the **discriminator quartet**: `item_type: 'individual' as const` + `asset_id` + `asset_type` (`'image'`/`'video'`/`'audio'`/`'text'`/`'click_url'`/`'html'`) + `required: boolean`. Missing any of these fails strict validation with `must match exactly one schema in oneOf`.
+>
+>   ```ts
+>   // ✗ WRONG — passes lenient mode but fails strict (the actual mistake matrix v2 catches)
+>   { format_id, renders: [{ width: 300, height: 250 }],
+>     assets: [{ asset_id: 'image', required: true }] }
+>
+>   // ✓ RIGHT — passes strict
+>   { format_id,
+>     renders: [{ role: 'primary', dimensions: { width: 300, height: 250 } }],
+>     assets: [{
+>       item_type: 'individual' as const,
+>       asset_id: 'image',
+>       asset_type: 'image',
+>       required: true,
+>       accepted_media_types: ['image/jpeg', 'image/png'],
+>     }] }
+>   ```
+>
 > - `build_creative` response is `{ creative_manifest: { format_id, assets } }` (single) or `{ creative_manifests: [...] }` (multi). Platform-native fields at the top level (`tag_url`, `creative_id`, `media_type`) are **invalid** — use `buildCreativeResponse({ creative_manifest })` / `buildCreativeMultiResponse({ creative_manifests })` from `@adcp/sdk/server` to lock the shape at compile time.
 > - Each asset in `creative_manifest.assets` requires an `asset_type` discriminator. Use the typed factories (`imageAsset`, `videoAsset`, `audioAsset`, `htmlAsset`, `urlAsset`, `textAsset`) so the discriminator is injected for you; a plain `{ serving_tag: { content: '<vast>...' } }` fails validation.
 > - `preview_creative` renders have the same pattern — each `renders[]` entry is a oneOf on `output_format`. Use `urlRender({...})`, `htmlRender({...})`, or `bothRender({...})` to inject the discriminator and require the matching `preview_url` / `preview_html` field automatically.
@@ -102,14 +127,14 @@ What happens when a creative is synced:
 
 **Handler bindings — read the Contract column entry before writing each return:**
 
-| Tool                    | Handler                        | Contract (field list)                                                 | Gotchas                                                                                                                                                                                                                              |
-| ----------------------- | ------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `get_adcp_capabilities` | auto-generated                 | n/a                                                                   | Do not register manually.                                                                                                                                                                                                            |
-| `list_creative_formats` | `creative.listCreativeFormats` | [`#list_creative_formats`](../../docs/llms.txt#list_creative_formats) | Each `renders[]` entry MUST have `role` + exactly one of `dimensions` (object) OR `parameters_from_format_id: true`. `{width, height}` shorthand fails — wrap in `dimensions`.                                                       |
-| `sync_creatives`        | `creative.syncCreatives`       | [`#sync_creatives`](../../docs/llms.txt#sync_creatives)               | Echo `creative_id`; `action` ∈ `created \| updated \| unchanged \| failed \| deleted`.                                                                                                                                               |
-| `list_creatives`        | `creative.listCreatives`       | [`#list_creatives`](../../docs/llms.txt#list_creatives)               | Honor `args.filters?.format_ids` when present. `created_date` + `updated_date` on each row are required ISO timestamps.                                                                                                              |
-| `preview_creative`      | `creative.previewCreative`     | [`#preview_creative`](../../docs/llms.txt#preview_creative)           | `renders[].output_format` is a discriminator — use `urlRender({...})`, `htmlRender({...})`, or `bothRender({...})` so the discriminator is injected and the required `preview_url`/`preview_html` field is enforced at compile time. |
-| `build_creative`        | `creative.buildCreative`       | [`#build_creative`](../../docs/llms.txt#build_creative)               | Check `args.target_format_id` → library lookup; fall back to `args.creative_id`. Response requires `creative_manifest.format_id` + `creative_manifest.assets`.                                                                       |
+| Tool                    | Handler                        | Contract (field list)                                                 | Gotchas                                                                                                                                                                                                                                                                                                                                                              |
+| ----------------------- | ------------------------------ | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `get_adcp_capabilities` | auto-generated                 | n/a                                                                   | Do not register manually.                                                                                                                                                                                                                                                                                                                                            |
+| `list_creative_formats` | `creative.listCreativeFormats` | [`#list_creative_formats`](../../docs/llms.txt#list_creative_formats) | Each `renders[]` entry MUST have `role` + exactly one of `dimensions` (object) OR `parameters_from_format_id: true` — `{width, height}` shorthand fails. Each `assets[]` entry MUST have `item_type: 'individual' as const` + `asset_id` + `asset_type` (image/video/audio/text/click_url/html) + `required: boolean`. See the strict-shape callout above the table. |
+| `sync_creatives`        | `creative.syncCreatives`       | [`#sync_creatives`](../../docs/llms.txt#sync_creatives)               | Echo `creative_id`; `action` ∈ `created \| updated \| unchanged \| failed \| deleted`.                                                                                                                                                                                                                                                                               |
+| `list_creatives`        | `creative.listCreatives`       | [`#list_creatives`](../../docs/llms.txt#list_creatives)               | Honor `args.filters?.format_ids` when present. `created_date` + `updated_date` on each row are required ISO timestamps.                                                                                                                                                                                                                                              |
+| `preview_creative`      | `creative.previewCreative`     | [`#preview_creative`](../../docs/llms.txt#preview_creative)           | `renders[].output_format` is a discriminator — use `urlRender({...})`, `htmlRender({...})`, or `bothRender({...})` so the discriminator is injected and the required `preview_url`/`preview_html` field is enforced at compile time.                                                                                                                                 |
+| `build_creative`        | `creative.buildCreative`       | [`#build_creative`](../../docs/llms.txt#build_creative)               | Check `args.target_format_id` → library lookup; fall back to `args.creative_id`. Response requires `creative_manifest.format_id` + `creative_manifest.assets`.                                                                                                                                                                                                       |
 
 Asset values use type-specific shapes, not a generic `asset_type` discriminator:
 
@@ -129,21 +154,21 @@ Some schemas also define an `ext` field for vendor-namespaced extensions. If you
 
 ## SDK Quick Reference
 
-| SDK piece                                               | Usage                                                            |
-| ------------------------------------------------------- | ---------------------------------------------------------------- |
-| `createAdcpServerFromPlatform(platform, opts)`          | Create server from a typed `DecisioningPlatform` — compile-time specialism enforcement, auto-capabilities |
-| `createAdcpServer(config)` *(legacy)*                   | v5 handler-bag entry. Mid-migration / escape-hatch only; reach via `@adcp/sdk/server/legacy/v5`            |
-| `serve(() => createAdcpServerFromPlatform(platform, opts))` | Start HTTP server on `:3001/mcp`                                                                       |
-| `creative: { listCreativeFormats, syncCreatives, ... }` | Domain group — register handlers by name                         |
-| `ctx.store.put(collection, id, data)`                   | Persist state (creative library) across requests                 |
-| `ctx.store.get(collection, id)`                         | Retrieve persisted state                                         |
-| `ctx.store.list(collection)`                            | List all items in a collection (for `list_creatives`)            |
-| `listCreativeFormatsResponse(data)`                     | Auto-applied response builder (don't call manually)              |
-| `syncCreativesResponse(data)`                           | Auto-applied response builder (don't call manually)              |
-| `listCreativesResponse(data)`                           | Auto-applied response builder (don't call manually)              |
-| `buildCreativeResponse(data)`                           | Auto-applied response builder (don't call manually)              |
-| `previewCreativeResponse(data)`                         | Auto-applied response builder (don't call manually)              |
-| `adcpError(code, { message })`                          | Structured error                                                 |
+| SDK piece                                                   | Usage                                                                                                     |
+| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `createAdcpServerFromPlatform(platform, opts)`              | Create server from a typed `DecisioningPlatform` — compile-time specialism enforcement, auto-capabilities |
+| `createAdcpServer(config)` _(legacy)_                       | v5 handler-bag entry. Mid-migration / escape-hatch only; reach via `@adcp/sdk/server/legacy/v5`           |
+| `serve(() => createAdcpServerFromPlatform(platform, opts))` | Start HTTP server on `:3001/mcp`                                                                          |
+| `creative: { listCreativeFormats, syncCreatives, ... }`     | Domain group — register handlers by name                                                                  |
+| `ctx.store.put(collection, id, data)`                       | Persist state (creative library) across requests                                                          |
+| `ctx.store.get(collection, id)`                             | Retrieve persisted state                                                                                  |
+| `ctx.store.list(collection)`                                | List all items in a collection (for `list_creatives`)                                                     |
+| `listCreativeFormatsResponse(data)`                         | Auto-applied response builder (don't call manually)                                                       |
+| `syncCreativesResponse(data)`                               | Auto-applied response builder (don't call manually)                                                       |
+| `listCreativesResponse(data)`                               | Auto-applied response builder (don't call manually)                                                       |
+| `buildCreativeResponse(data)`                               | Auto-applied response builder (don't call manually)                                                       |
+| `previewCreativeResponse(data)`                             | Auto-applied response builder (don't call manually)                                                       |
+| `adcpError(code, { message })`                              | Structured error                                                                                          |
 
 Import: `import { createAdcpServerFromPlatform, serve, adcpError } from '@adcp/sdk/server';`
 
@@ -246,63 +271,63 @@ class MyCreative implements DecisioningPlatform {
 
   creative: CreativeAdServerPlatform = {
     listCreativeFormats: async (params, ctx) => {
-        return { formats };
-      },
+      return { formats };
+    },
 
-      syncCreatives: async (params, ctx) => {
-        const results = [];
-        for (const creative of params.creatives) {
-          const now = new Date().toISOString();
-          const existing = await ctx.store.get('creatives', creative.creative_id);
-          await ctx.store.put('creatives', creative.creative_id, {
-            ...creative,
-            status: 'approved',
-            created_date: existing?.created_date ?? now,
-            updated_date: now,
-          });
-          results.push({
-            creative_id: creative.creative_id,
-            action: existing ? ('updated' as const) : ('created' as const),
-          });
-        }
-        return { creatives: results };
-      },
+    syncCreatives: async (params, ctx) => {
+      const results = [];
+      for (const creative of params.creatives) {
+        const now = new Date().toISOString();
+        const existing = await ctx.store.get('creatives', creative.creative_id);
+        await ctx.store.put('creatives', creative.creative_id, {
+          ...creative,
+          status: 'approved',
+          created_date: existing?.created_date ?? now,
+          updated_date: now,
+        });
+        results.push({
+          creative_id: creative.creative_id,
+          action: existing ? ('updated' as const) : ('created' as const),
+        });
+      }
+      return { creatives: results };
+    },
 
-      listCreatives: async (params, ctx) => {
-        // `ctx.store.list` returns `{ items, nextCursor? }` — destructure.
-        let { items: creatives } = await ctx.store.list('creatives');
-        if (params.filters?.format_ids) {
-          creatives = creatives.filter(c => params.filters!.format_ids!.some(fid => fid.id === c.format_id?.id));
-        }
-        return {
-          query_summary: { total_matching: creatives.length, returned: creatives.length, filters_applied: [] },
-          creatives,
-          pagination: { has_more: false },
-        };
-      },
+    listCreatives: async (params, ctx) => {
+      // `ctx.store.list` returns `{ items, nextCursor? }` — destructure.
+      let { items: creatives } = await ctx.store.list('creatives');
+      if (params.filters?.format_ids) {
+        creatives = creatives.filter(c => params.filters!.format_ids!.some(fid => fid.id === c.format_id?.id));
+      }
+      return {
+        query_summary: { total_matching: creatives.length, returned: creatives.length, filters_applied: [] },
+        creatives,
+        pagination: { has_more: false },
+      };
+    },
 
-      buildCreative: async (params, ctx) => {
-        // `ctx.store.list` returns `{ items, nextCursor? }` — destructure.
-        // Calling `.find`/`.map` on the raw result throws `TypeError` and
-        // the dispatcher wraps it as `SERVICE_UNAVAILABLE`.
-        const { items: creatives } = await ctx.store.list('creatives');
-        const match = params.target_format_id
-          ? creatives.find(c => c.format_id?.id === params.target_format_id!.id)
-          : params.creative_id
-            ? await ctx.store.get('creatives', params.creative_id)
-            : null;
-        // Return structured errors — don't throw. The dispatcher now unwraps
-        // thrown envelopes, but throwing still releases the idempotency claim
-        // before the throw is caught. If your handler mutated state before
-        // throwing, a retry with the same key re-executes the write. Returning
-        // an error envelope has the same claim-release semantics, so the rule
-        // holds for both paths: mutate last, or don't mutate at all on error.
-        if (!match) return adcpError('CREATIVE_NOT_FOUND', { message: 'No matching creative' });
-        return {
-          creative_manifest: { format_id: match.format_id, assets: match.assets ?? {} },
-          sandbox: true,
-        };
-      },
+    buildCreative: async (params, ctx) => {
+      // `ctx.store.list` returns `{ items, nextCursor? }` — destructure.
+      // Calling `.find`/`.map` on the raw result throws `TypeError` and
+      // the dispatcher wraps it as `SERVICE_UNAVAILABLE`.
+      const { items: creatives } = await ctx.store.list('creatives');
+      const match = params.target_format_id
+        ? creatives.find(c => c.format_id?.id === params.target_format_id!.id)
+        : params.creative_id
+          ? await ctx.store.get('creatives', params.creative_id)
+          : null;
+      // Return structured errors — don't throw. The dispatcher now unwraps
+      // thrown envelopes, but throwing still releases the idempotency claim
+      // before the throw is caught. If your handler mutated state before
+      // throwing, a retry with the same key re-executes the write. Returning
+      // an error envelope has the same claim-release semantics, so the rule
+      // holds for both paths: mutate last, or don't mutate at all on error.
+      if (!match) return adcpError('CREATIVE_NOT_FOUND', { message: 'No matching creative' });
+      return {
+        creative_manifest: { format_id: match.format_id, assets: match.assets ?? {} },
+        sandbox: true,
+      };
+    },
 
     previewCreative: async params => {
       return {
@@ -538,22 +563,22 @@ Common failure decoder:
 
 ## Common Mistakes
 
-| Mistake                                                                | Fix                                                                                                                                 |
-| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| Using `createTaskCapableServer` + `server.tool()`                      | Use `createAdcpServerFromPlatform` with a typed `creative: CreativeAdServerPlatform` (or `CreativeBuilderPlatform`) field           |
+| Mistake                                                                | Fix                                                                                                                                      |
+| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Using `createTaskCapableServer` + `server.tool()`                      | Use `createAdcpServerFromPlatform` with a typed `creative: CreativeAdServerPlatform` (or `CreativeBuilderPlatform`) field                |
 | Calling `createAdcpServer` directly in new code                        | Reach for `createAdcpServerFromPlatform`; `createAdcpServer` lives at `@adcp/sdk/server/legacy/v5` for mid-migration / escape-hatch only |
-| Manually registering `get_adcp_capabilities`                           | Auto-generated by `createAdcpServerFromPlatform` from your typed `DecisioningPlatform` — do not register it                         |
-| Calling `server.registerTool('preview_creative', ...)`                 | `AdcpServer` does not expose `registerTool` — put `previewCreative` in the `creative:` domain group like the other handlers         |
-| Using module-level Maps for state                                      | Use `ctx.store.put/get/list` — framework provides `InMemoryStateStore` by default                                                   |
-| Calling response builders manually in domain handlers                  | Handlers return raw data — response builders are auto-applied across the `creative:` group, including `preview_creative`            |
-| `list_creatives` ignores format filter                                 | Check `args.filters?.format_ids` and filter results                                                                                 |
-| `preview_creative` returns wrong response_type                         | Must be `'single'` for single creative previews                                                                                     |
-| `preview_creative` looks up by creative_id                             | Preview the `creative_manifest` from the request — no library lookup needed                                                         |
-| `build_creative` looks up by `args.creative_id` only                   | Storyboard sends `target_format_id` — find a synced creative matching that format                                                   |
-| `build_creative` missing creative_manifest                             | Required field — contains the built output                                                                                          |
-| `creative_manifest` includes `name` field                              | `CreativeManifest` has no `name` — only `format_id` and `assets`                                                                    |
-| HTML asset uses `{ html: '...' }`                                      | Use `{ content: '...' }` — the schema field is `content`, not `html`                                                                |
-| format_ids in list_creative_formats don't match what sellers reference | Sellers include your format_ids in their products — if the buyer can't look them up via list_creative_formats, creative sync breaks |
+| Manually registering `get_adcp_capabilities`                           | Auto-generated by `createAdcpServerFromPlatform` from your typed `DecisioningPlatform` — do not register it                              |
+| Calling `server.registerTool('preview_creative', ...)`                 | `AdcpServer` does not expose `registerTool` — put `previewCreative` in the `creative:` domain group like the other handlers              |
+| Using module-level Maps for state                                      | Use `ctx.store.put/get/list` — framework provides `InMemoryStateStore` by default                                                        |
+| Calling response builders manually in domain handlers                  | Handlers return raw data — response builders are auto-applied across the `creative:` group, including `preview_creative`                 |
+| `list_creatives` ignores format filter                                 | Check `args.filters?.format_ids` and filter results                                                                                      |
+| `preview_creative` returns wrong response_type                         | Must be `'single'` for single creative previews                                                                                          |
+| `preview_creative` looks up by creative_id                             | Preview the `creative_manifest` from the request — no library lookup needed                                                              |
+| `build_creative` looks up by `args.creative_id` only                   | Storyboard sends `target_format_id` — find a synced creative matching that format                                                        |
+| `build_creative` missing creative_manifest                             | Required field — contains the built output                                                                                               |
+| `creative_manifest` includes `name` field                              | `CreativeManifest` has no `name` — only `format_id` and `assets`                                                                         |
+| HTML asset uses `{ html: '...' }`                                      | Use `{ content: '...' }` — the schema field is `content`, not `html`                                                                     |
+| format_ids in list_creative_formats don't match what sellers reference | Sellers include your format_ids in their products — if the buyer can't look them up via list_creative_formats, creative sync breaks      |
 
 ## Storyboards
 
@@ -570,106 +595,25 @@ Common failure decoder:
 
 Storyboard: `creative_ad_server`. Stateful — the library is pre-loaded; buyers do **not** push assets via `sync_creatives` at runtime. Pricing and billing round-trips are first-class.
 
-**`list_creatives`** with `include_pricing=true` returns per-creative `pricing_options`:
+**Fork target**: [`examples/hello_creative_adapter_ad_server.ts`](../../examples/hello_creative_adapter_ad_server.ts) is the worked, passing reference adapter for this specialism. CI gates strict tsc + storyboard pass + upstream-traffic façade — all 7 storyboard steps pass on the worked build.
 
-```typescript
-listCreatives: async (params, ctx) => {
-  const { items } = await ctx.store.list('creatives');
-  const creatives = items.map((c) => ({
-    creative_id: c.creative_id,
-    name: c.name,
-    format_id: c.format_id,
-    status: 'approved' as const,
-    created_date: c.created_date,
-    updated_date: c.updated_date,
-    ...(params.include_pricing && {
-      pricing_options: [{
-        pricing_option_id: 'standard_cpm',
-        model: 'cpm' as const,
-        cpm: 2.5,
-        currency: 'USD',
-      }],
-    }),
-  }));
-  return {
-    query_summary: { total_matching: creatives.length, returned: creatives.length, filters_applied: [] },
-    creatives,
-    pagination: { has_more: false },
-  };
-},
-```
+The adapter demonstrates the stateful-library deltas vs `creative-template`:
 
-**`build_creative`** receives `media_buy_id`, `package_id`, `target_format_id`, and `pricing_option_id`. Return a VAST tag with macro placeholders, plus `vendor_cost` at CPM = 0 (billing happens via `report_usage`):
+- **Library shape** — `POST /v1/creatives` writes, `GET /v1/creatives` reads (cursor pagination + multi-id pass-through), `PATCH` mutates. Maps directly onto `CreativeAdServerPlatform.{syncCreatives, listCreatives}`. Library state is owned by the adopter's UI / API ingestion; the comply controller's `seed.creative` is the only test path that writes via the adapter.
+- **Tag generation** — `buildCreative` looks up the creative by id, calls upstream `POST /v1/creatives/{id}/render` for macro substitution against a stored snippet template (`{click_url}`, `{impression_pixel}`, `{cb}`, `{advertiser_id}`, `{creative_id}`, `{asset_url}` …), and returns `BuildCreativeSuccess` with `creative_manifest.assets` carrying the rendered tag (HTML / VAST / native). The mock's `tag_url` points at a real iframe-embeddable `/serve/{id}` endpoint adopters can iframe in storyboards.
+- **`previewCreative`** — `NoAccountCtx<TCtxMeta>` no-account tool; returns the same iframe URL as a `preview_url`. The resolver synthesizes a default-listing network so `ctx.account` resolves cleanly inside the no-account handler. See migration recipe #11.
+- **`listCreativeFormats`** — also `NoAccountCtx`. Project upstream catalog to closed-shape `Format.renders[]` (display fixed dims, video/CTV at 1080p baseline, parameterized with `accepts_parameters[]`) per the typed builders from `@adcp/sdk` (#1325).
+- **Per-creative pricing** — when the adopter bills through AdCP, `listCreatives` with `include_pricing=true` surfaces `pricing_options`, `buildCreative` echoes the applied `pricing_option_id`, and `reportUsage` closes the loop. Adopters that bill out of band (CM360-style flat license / SaaS contract) omit these fields and surface `report_usage` records as `not_accepted` rather than fake-accepting.
+- **`getCreativeDelivery`** — multi-id pass-through per #1342 + #1410; required top-level `currency` + `reporting_period` per the response schema.
 
-```typescript
-buildCreative: async (params, ctx) => {
-  const creative = await lookupCreativeForFormat(params.target_format_id, ctx);
-  const vast = `<?xml version="1.0"?>
-<VAST version="4.2">
-  <Ad id="${creative.creative_id}"><InLine>
-    <Impression><![CDATA[https://adserver.example/imp?cb=[CACHEBUSTER]&mb=${params.media_buy_id}]]></Impression>
-    <Creatives><Creative>
-      <Linear><Duration>00:00:30</Duration>
-        <MediaFiles><MediaFile type="video/mp4"><![CDATA[${creative.video_url}]]></MediaFile></MediaFiles>
-        <VideoClicks><ClickThrough><![CDATA[[CLICK_URL]https://landing.example]]></ClickThrough></VideoClicks>
-      </Linear>
-    </Creative></Creatives>
-  </InLine></Ad>
-</VAST>`;
-
-  return {
-    creative_manifest: {
-      format_id: params.target_format_id,
-      assets: { serving_tag: { content: vast } },     // HTML asset shape: { content: string }
-    },
-    pricing_option_id: params.pricing_option_id,      // echo
-    vendor_cost: { amount: 0, currency: 'USD' },      // CPM at build time — billing is separate
-    sandbox: true,
-  };
-},
-```
-
-**`report_usage`** is the billing reconciliation tool. Validate `idempotency_key` (return the same response for the same key) and echo `pricing_option_id` + `reporting_period`:
-
-```typescript
-reportUsage: async (params, ctx) => {
-  const existing = await ctx.store.get('usage_reports', params.idempotency_key);
-  if (existing) return existing;    // idempotent
-  const report = {
-    idempotency_key: params.idempotency_key,
-    creative_id: params.creative_id,
-    pricing_option_id: params.pricing_option_id,
-    reporting_period: params.reporting_period,
-    billable_amount: { amount: params.impressions * 2.5 / 1000, currency: 'USD' },
-    status: 'accepted' as const,
-  };
-  await ctx.store.put('usage_reports', params.idempotency_key, report);
-  return report;
-},
-```
-
-**`get_creative_delivery`** returns impressions/spend, optionally broken down by variant and filtered by `media_buy_ids`:
-
-```typescript
-getCreativeDelivery: async (params, ctx) => ({
-  reporting_period: params.reporting_period,
-  currency: 'USD',                                 // required top-level per get-creative-delivery-response.json
-  creatives: (params.creative_ids ?? []).map((id) => ({
-    creative_id: id,
-    impressions: 12500,
-    spend: { amount: 31.25, currency: 'USD' },
-    by_variant: [],
-  })),
-  sandbox: true,
-}),
-```
-
-Output formats returned by `list_creative_formats` for ad servers are **serving-tag formats** (VAST 4.2, display tag HTML, native JSON payload), not input visual formats.
+Output formats returned by `list_creative_formats` for ad servers are **serving-tag formats** (VAST 4.2, display tag HTML, native JSON payload), not input visual formats. Replace the `// SWAP:` markers with calls to your real backend.
 
 ### <a name="specialism-creative-template"></a>creative-template
 
 Storyboard: `creative_template`. Stateless — build from the inline `creative_manifest` in the request, do not call `ctx.store`.
 
+**Fork target**: `examples/hello_creative_adapter_template.ts` is the worked, passing reference adapter for this specialism. CI gates strict tsc + storyboard pass + upstream-traffic façade. Replace the `// SWAP:` markers with calls to your real backend.
+
 Formats declare `variables` the template will substitute:
 
 ```typescript

package/skills/build-decisioning-platform/advanced/MULTI-TENANT.md

@@ -5,43 +5,119 @@ When one process hosts many publishers (typical SaaS deployment), use `createTen
 ```ts
 import { createTenantRegistry, serve } from '@adcp/sdk/server';
 
-const registry = createTenantRegistry({
-  resolveTenant: async (req) => {
-    // Map host header / OAuth subject / path prefix to a tenant id
-    return { tenantId: extractTenantFromHost(req.headers.host) };
-  },
-  buildPlatform: async (tenantId) => {
-    // Load tenant config from your DB
-    const tenantConfig = await loadTenant(tenantId);
-    return new MyPlatform(tenantConfig);
-  },
-  // Health gates: 'healthy' / 'unverified' / 'disabled'
-  // Disabled tenants get 503 SERVICE_UNAVAILABLE without invoking the platform.
-});
+async function bootstrap() {
+  // 1. Create the registry (once, at startup)
+  const registry = createTenantRegistry({
+    defaultServerOptions: {
+      name: 'my-multi-tenant-host',
+      version: '1.0.0',
+      validation: { requests: 'strict', responses: 'strict' },
+    },
+    // jwksValidator: createNoopJwksValidator()  // dev/test only — skip brand.json roundtrip
+    autoValidate: true,
+  });
 
-serve(registry.host, { port: process.env.PORT });
+  // 2. Register each tenant explicitly (call register() once per tenant)
+  //    Load config from your DB, KMS, etc. at startup.
+  const tenantAConfig = await loadTenant('tenant_a');
+  await registry.register('tenant_a', {
+    agentUrl: 'https://tenant-a.example.com',
+    platform: new MyPlatform(tenantAConfig),
+    // signingKey: await loadSigningKeyFromKms('tenant_a'),  // optional in 3.x; required in 4.0
+    label: 'Tenant A',
+  }, { awaitFirstValidation: true });
+
+  // 3. Wire into serve() — resolve the tenant per request by host
+  serve(ctx => {
+    const resolved = registry.resolveByHost(ctx.host);
+    if (!resolved) throw new Error(`unknown host: ${ctx.host}`);
+    return resolved.server;
+  }, { port: process.env.PORT });
+}
 ```
 
-## Per-tenant config
+## Per-tenant health
 
-Each tenant can override `capabilities.config` independently:
+Health is per-tenant and isolated — one bad tenant doesn't block others:
+
+| State | Meaning | Traffic |
+|---|---|---|
+| `pending` | Registered; first JWKS validation not yet completed | **Refused** (503) |
+| `healthy` | JWKS validated at least once | Served normally |
+| `unverified` | Was healthy; latest recheck failed transiently | Served (graceful degradation) |
+| `disabled` | Permanent JWKS failure (key not in JWKS, malformed brand.json) | **Refused** until admin calls `recheck()` |
+
+## Runtime admin operations
+
+Register a new tenant without restarting (e.g., admin-save webhook):
 
 ```ts
-buildPlatform: async (tenantId) => {
+// POST /admin/tenants/:tenantId/activate  (gate with mTLS or signed admin token)
+async function activateTenant(tenantId: string, row: { agentUrl: string }) {
   const cfg = await loadTenant(tenantId);
-  return {
-    capabilities: {
-      ...,
-      config: { networkId: cfg.gamNetworkId, manualApprovalOperations: cfg.approvalOps },
-    },
-    accounts: { ... },
-    sales: { ... },
-  };
-};
+  await registry.register(tenantId, {
+    agentUrl: row.agentUrl,
+    platform: new MyPlatform(cfg),
+  }, { awaitFirstValidation: true });
+}
+```
+
+Re-validate JWKS after key rotation (**zero traffic gap**):
+
+```ts
+// POST /admin/tenants/:tenantId/recheck
+async function recheckTenant(tenantId: string) {
+  const status = await registry.recheck(tenantId);
+  // status.health transitions: disabled → healthy (if brand.json now matches)
+  return status;
+}
+```
+
+Update platform config (unregister → re-register, **brief ~503 gap**):
+
+```ts
+// ⚠️  resolveByHost returns null between these two calls (~<10ms for in-process)
+async function updateTenant(tenantId: string, agentUrl: string, newConfig: unknown) {
+  registry.unregister(tenantId);
+  await registry.register(tenantId, { agentUrl, platform: new MyPlatform(newConfig) },
+    { awaitFirstValidation: true });
+}
+```
+
+Remove a tenant — `resolveByHost` returns null immediately:
+
+```ts
+registry.unregister(tenantId);
+// In-flight requests that already resolved a server reference complete normally.
+// New resolve calls return null → respond with 503/404.
+```
+
+## Per-tenant config
+
+Each tenant registers its own `DecisioningPlatform` implementation independently.
+There is no shared `capabilities.config` override — per-tenant configuration is
+expressed via your platform's constructor or dependency-injection pattern:
+
+```ts
+registry.register(tenantId, {
+  agentUrl: row.agentUrl,
+  platform: new MyPlatform({
+    networkId: row.gamNetworkId,
+    manualApprovalOps: row.approvalOps,
+  }),
+});
 ```
 
 ## Per-tenant ctxMetadata
 
-Each `createAdcpServerFromPlatform` call gets its own `ctxMetadataStore` instance — multi-tenant hosts pass per-tenant store handles, not a shared one. Account scoping handles the rest (`account.id` in the storage key).
+Each `createAdcpServerFromPlatform` call (one per tenant) gets its own
+`ctxMetadataStore` instance — multi-tenant hosts pass per-tenant store handles,
+not a shared one. Account scoping handles request isolation
+(`account.id` is part of the storage key).
+
+## Worked example
+
+See `examples/decisioning-platform-multi-tenant-db.ts` for a complete DB-driven
+startup pattern with concurrent-recheck CI tests and admin-operation helpers.
 
-See `REFERENCE.md` for the full multi-tenant section + admin router for ops visibility.
+See `REFERENCE.md` for the admin router (ops visibility into registry health).

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

@@ -23,6 +23,8 @@ A generative seller that sells programmatic inventory MUST also accept standard
 - Standalone creative agent (renders but doesn't sell) → creative agent
 - Signals/audience data → `skills/build-signals-agent/`
 
+**Often claimed alongside:** [`creative-template`](../build-creative-agent/SKILL.md) — hybrid creative platforms (Celtra, Bannerflow) claim both; template-driven and AI-driven generation share the same creative library. See [Common multi-specialism bundles](../../examples/README.md#common-multi-specialism-bundles).
+
 ## Specialisms This Skill Covers
 
 A generative seller inherits every sales specialism it supports (usually `sales-non-guaranteed`, optionally `sales-catalog-driven`) **plus** `creative-generative`. Declare all three in your `get_adcp_capabilities` response so buyers can filter correctly.
@@ -349,14 +351,14 @@ Validate with: `adcp storyboard run <agent> deterministic_testing --json`
 
 ## SDK Quick Reference
 
-| SDK piece                               | Usage                                                                   |
-| --------------------------------------- | ----------------------------------------------------------------------- |
-| `createAdcpServerFromPlatform(platform, opts)` | Create server from a typed `DecisioningPlatform` — compile-time specialism enforcement, auto-generated capabilities, ctx_metadata round-trip |
-| `createAdcpServer(config)` *(legacy)*          | v5 handler-bag entry. Mid-migration / escape-hatch only; reach via `@adcp/sdk/server/legacy/v5`                                              |
-| `serve(() => createAdcpServerFromPlatform(platform, opts))` | Start HTTP server on `:3001/mcp`                                                                       |
-| `ctx.store`                             | State persistence — `get/put/patch/delete/list` domain objects          |
-| `adcpError(code, { message })`          | Structured error                                                        |
-| `registerTestController(server, store)` | Add `comply_test_controller` for deterministic testing                  |
+| SDK piece                                                   | Usage                                                                                                                                        |
+| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createAdcpServerFromPlatform(platform, opts)`              | Create server from a typed `DecisioningPlatform` — compile-time specialism enforcement, auto-generated capabilities, ctx_metadata round-trip |
+| `createAdcpServer(config)` _(legacy)_                       | v5 handler-bag entry. Mid-migration / escape-hatch only; reach via `@adcp/sdk/server/legacy/v5`                                              |
+| `serve(() => createAdcpServerFromPlatform(platform, opts))` | Start HTTP server on `:3001/mcp`                                                                                                             |
+| `ctx.store`                                                 | State persistence — `get/put/patch/delete/list` domain objects                                                                               |
+| `adcpError(code, { message })`                              | Structured error                                                                                                                             |
+| `registerTestController(server, store)`                     | Add `comply_test_controller` for deterministic testing                                                                                       |
 
 Response builders (`productsResponse`, `mediaBuyResponse`, `syncCreativesResponse`, etc.) are auto-applied by the framework. Handlers return raw data objects — the framework wraps them.
 
@@ -477,7 +479,11 @@ class MyGenerativeSeller implements DecisioningPlatform {
     buildCreative: async (req, ctx) => {
       // Generative path — read brief, call your model, return assets.
       // Framework auto-stores the build for refine/lookup via ctx_metadata.
-      return { creative_manifest: { /* generated assets */ } };
+      return {
+        creative_manifest: {
+          /* generated assets */
+        },
+      };
     },
     previewCreative: async (req, ctx) => {
       return { preview_url: '...' };