@adcp/sdk 6.7.0 → 6.9.0

package/skills/build-seller-agent/specialisms/sales-non-guaranteed.md

@@ -2,38 +2,16 @@
 
 Companion to [`../SKILL.md`](../SKILL.md). The SKILL.md baseline applies; this file covers only the deltas for `sales-non-guaranteed`.
 
-Storyboard: `media_buy_non_guaranteed`. The specialism hinges on `bid_price` and `update_media_buy`, neither of which the baseline example shows.
+Storyboard: `sales_non_guaranteed`. The specialism hinges on `bid_price` and `update_media_buy`, neither of which the baseline example shows.
 
-**Forecast surface**: `'spend'` (the default). Programmatic forward forecast — points at ascending budget levels show how impressions and clicks scale with spend. This is the planning surface every non-guaranteed buyer expects. Project your forecaster's spend curves directly onto `Product.forecast` points where each point is `{ budget: { mid }, metrics: { impressions: { low, mid, high }, clicks: { mid } } }`. See [Delivery Forecasts § Budget Curve](https://adcontextprotocol.org/docs/media-buy/product-discovery/media-products#budget-curve) for the canonical worked example.
+**Fork target**: [`examples/hello_seller_adapter_non_guaranteed.ts`](../../../examples/hello_seller_adapter_non_guaranteed.ts) is the worked, passing reference adapter for this specialism. CI gates strict tsc + storyboard pass + upstream-traffic façade.
 
-Packages on `create_media_buy` carry `bid_price`. Validate it against the product's `floor_price`:
+The adapter demonstrates the auction-mode deltas vs `sales-guaranteed`:
 
-```typescript
-createMediaBuy: async (params, ctx) => {
-  for (const pkg of params.packages ?? []) {
-    const product = PRODUCTS.find((p) => p.product_id === pkg.product_id);
-    const floor = product?.pricing_options[0].floor_price;
-    if (floor && pkg.bid_price != null && pkg.bid_price < floor) {
-      return adcpError('INVALID_REQUEST', {
-        message: `bid_price ${pkg.bid_price} below floor_price ${floor}`,
-      });
-    }
-  }
-  return {
-    media_buy_id: `mb_${randomUUID()}`,
-    status: 'active' as const,   // instant — no IO
-    packages: /* ... */,
-  };
-},
+- **Sync confirmation** — `createMediaBuy` returns `media_buy_id` immediately with `status: 'active'` (or `pending_creatives` until creatives attach). No `ctx.handoffToTask`, no IO poll, no task envelope. Auction inventory clears at request time.
+- **Floor pricing** — `pricing_options[].fixed_price` projected from upstream `min_cpm`; `min_spend` and `target_cpm` flow through to the wire when the upstream sets them. Reject `bid_price` below `floor_price` with `INVALID_REQUEST`.
+- **Spend-only forecast** — `forecast_range_unit: 'spend'`; no `availability` unit because non-guaranteed inventory isn't pre-committed. See [Delivery Forecasts § Budget Curve](https://adcontextprotocol.org/docs/media-buy/product-discovery/media-products#budget-curve) for the wire shape.
+- **Pacing propagation** — `even` / `asap` / `front_loaded` forwarded to upstream order; reflected in delivery curve. Validate raw input — reject typos rather than silently passing them through.
+- **`update_media_buy`** — bid/budget changes apply in-flight without re-issuing the order. `valid_actions` on an active non-guaranteed buy should include `pause`, `update_bid`, `get_delivery`; the framework auto-populates this when `status: 'active'`.
 
-updateMediaBuy: async (params, ctx) => {
-  const existing = await ctx.store.get('media_buys', params.media_buy_id);
-  if (!existing) return adcpError('NOT_FOUND', { message: `Media buy ${params.media_buy_id} not found` });
-  // Apply bid/budget updates from params.packages
-  const updated = { ...existing, packages: /* merged */ };
-  await ctx.store.put('media_buys', params.media_buy_id, updated);
-  return updated;
-},
-```
-
-`valid_actions` on an active non-guaranteed buy should include `pause`, `update_bid`, `get_delivery`. The framework auto-populates this when `createMediaBuy`/`updateMediaBuy` return with `status: 'active'`.
+Auction mode is the deletion-fork of the guaranteed sibling. If your backend has HITL approval, fork [`hello_seller_adapter_guaranteed.ts`](../../../examples/hello_seller_adapter_guaranteed.ts) instead. Replace the `// SWAP:` markers with calls to your real backend.

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

@@ -1,355 +1,92 @@
 ---
 name: build-si-agent
-description: Use when building an AdCP sponsored intelligence agent — a platform that serves conversational sponsored content within user sessions.
+description: Use when building an AdCP sponsored intelligence agent — a brand-side conversational AI experience that an LLM host (ChatGPT, Claude, Perplexity, Arc) can hand off to.
 ---
 
 # Build a Sponsored Intelligence Agent
 
-## Overview
+A sponsored intelligence (SI) agent runs a brand-side conversational AI experience that an LLM host can hand off to. The buyer agent calls four tools across the session lifecycle:
 
-A sponsored intelligence (SI) agent serves conversational sponsored content within user sessions. Buyers discover offerings, initiate sessions, exchange messages, and terminate when done. The agent manages session state and delivers sponsored content in conversational form.
+1. `si_get_offering` — discover what's available, get an `offering_token`
+2. `si_initiate_session` — start a conversation, receive `session_id`
+3. `si_send_message` — exchange turns, optionally surface a handoff hint
+4. `si_terminate_session` — end the session, optionally return ACP checkout payload
 
-## When to Use
+The agent owns the brand voice, transcript state, and product knowledge. The host owns the user, identity consent, and ACP checkout. SI is the AdCP surface that connects them.
 
-- User wants to build an agent that serves sponsored conversational content
-- User mentions sponsored intelligence, SI sessions, conversational ads, or sponsored chat
-- User references `si_initiate_session`, `si_send_message`, or the SI protocol
+## Pick your fork target
 
-**Not this skill:**
-
-- Selling display/video inventory → `skills/build-seller-agent/`
-- Serving audience segments → `skills/build-signals-agent/`
-- Managing creatives → `skills/build-creative-agent/`
-
-## Specialisms This Skill Covers
-
-| Specialism   | Status | Delta                                                                                                                                                                                     |
-| ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| _(none yet)_ | —      | SI has no specialisms in AdCP 3.0 — pass the `sponsored_intelligence` *protocol* baseline (declared via `supported_protocols: ['sponsored_intelligence']`). Specialism storyboards for conversational-ad-specific patterns are pending future AdCP releases. |
-
-## Before Writing Code
-
-### 1. What Offerings?
+| Protocol | Fork this | Storyboard |
+| --- | --- | --- |
+| `sponsored-intelligence` | [`hello_si_adapter_brand.ts`](../../examples/hello_si_adapter_brand.ts) | `si_baseline` |
 
-Each offering represents a sponsored content experience. Define:
+SI is a **protocol** in AdCP 3.0, not a specialism. Declare it via the `sponsoredIntelligence` field on the v6 `DecisioningPlatform`; the framework auto-derives `'sponsored_intelligence'` into `supported_protocols` from the four registered SI tools. There's no `specialisms: ['sponsored-intelligence']` claim today (tracked at adcontextprotocol/adcp#3961 for 3.1).
 
-- Product/brand being sponsored
-- Content style (informational, promotional, interactive)
-- Supported modalities: conversational (text), rich_media (images/video)
-
-### 2. Session Behavior
-
-How should the agent respond during a session?
-
-- **Informational** — answers questions about the sponsored product
-- **Promotional** — proactively highlights features and benefits
-- **Interactive** — guided product exploration with branching content
-
-## Tools and Required Response Shapes
-
-> **Before writing any handler's return statement, fetch [`docs/llms.txt`](../../docs/llms.txt) and grep for `#### \`<tool_name>\``(e.g.`#### \`si_initiate_session\``) to read the exact required + optional field list.** The schema-derived contract lives there; this skill covers patterns, gotchas, and domain-specific examples. Strict response validation is on by default in dev — it will tell you the exact field path if you drift, so write the obvious thing and trust the contract.
->
-> **Cross-cutting pitfalls matrix runs keep catching:**
->
-> - **Do NOT declare a `sponsored-intelligence` specialism.** SI is a *protocol* in AdCP 3.0 — declared via `supported_protocols: ['sponsored_intelligence']` on the `get_adcp_capabilities` response. There is no SI specialism in the `AdCPSpecialism` enum yet, so adopters wire SI through the v5 handler-bag path (`createAdcpServer` from `@adcp/sdk/server/legacy/v5`). The v6 `DecisioningPlatform` interface does not yet expose a `sponsoredIntelligence` field. (Tracking: SI specialism + auto-hydration of `req.session` is planned for a later v6.x — adopters today persist sessions explicitly via `ctx.store`.)
-
-**`get_adcp_capabilities`** — register first, empty `{}` schema
-
-```
-capabilitiesResponse({
-  adcp: { major_versions: [3] },
-  supported_protocols: ['sponsored_intelligence'],
-})
-```
+The storyboard at `compliance/cache/latest/protocols/sponsored-intelligence/index.yaml` has three phases (capability_discovery, offering_discovery, session_lifecycle) covering all four tools. The reference adapter passes 3/3.
 
-**`si_get_offering`** — `SIGetOfferingRequestSchema.shape`
+For exact response shapes, error codes, and optional fields, `docs/llms.txt` is the canonical reference.
 
-Check if an offering is available. Return `available: true` with an `offering_token` the buyer passes to `si_initiate_session`.
+## When to use this skill
 
-```
-taskToolResponse({
-  available: true,            // required — boolean
-  offering_token: string,     // token for session initiation
-  ttl_seconds: 300,           // how long the token is valid
-})
-```
-
-**`si_initiate_session`** — `SIInitiateSessionRequestSchema.shape`
-
-Create a new session. Return `session_id` and `session_status`.
-
-```
-taskToolResponse({
-  session_id: string,         // required — unique session identifier
-  session_status: 'active',   // required — NB: 'session_status' not 'status'
-})
-```
-
-**`si_send_message`** — `SISendMessageRequestSchema.shape`
-
-Process a user message and return sponsored content.
-
-```
-taskToolResponse({
-  session_id: string,         // required — echo from request
-  session_status: 'active',   // required
-  response: {
-    content: string,          // the sponsored content text
-    content_type: 'text',
-  },
-})
-```
-
-**`si_terminate_session`** — `SITerminateSessionRequestSchema.shape`
-
-End the session.
-
-```
-taskToolResponse({
-  session_id: string,         // required — echo from request
-  terminated: true,           // required — boolean confirming termination
-})
-```
+- User wants to build a brand-agent platform that hosts conversational ads (Salesforce Agentforce, OpenAI Assistants brand mode, custom in-house brand chat)
+- User mentions sponsored intelligence, SI sessions, conversational ads, brand handoff, or ACP checkout
+- User references `si_initiate_session`, `si_send_message`, `si_get_offering`, or `si_terminate_session`
 
-### Context and Ext Passthrough
-
-The framework auto-echoes the request's `context` into every response — **do not set `context` yourself** on responses for tools whose request-side `context` is the protocol echo object (`core/context.json`).
-
-**SI override.** `si_get_offering` and `si_initiate_session` override `context` on the request as a domain-specific **string** (natural-language intent hint, per spec: _'mens size 14 near Cincinnati'_). The response schema still keeps `context` as the protocol echo object. The framework detects this mismatch and skips the auto-echo for non-object values — your response simply won't carry a `context` field unless you populate it. If you want correlation tracking for SI responses, construct the context object in your handler (e.g., from a buyer-supplied `ext.correlation_id` or your own generator) and return it on the response.
-
-`si_send_message` and `si_terminate_session` use the standard protocol echo object on both sides — leave `context` out of the handler return and the framework will echo it.
-
-## SDK Quick Reference
-
-| SDK piece                                                            | Usage                                                                                                                                                                                                                                                                                                                                                                          |
-| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `createAdcpServer(config)` *(use this for SI)*                       | v5 handler-bag entry. The only path that ships SI dispatch (the `sponsoredIntelligence: { getOffering, initiateSession, sendMessage, terminateSession }` sub-bag). Reach via `@adcp/sdk/server/legacy/v5`. v6 `createAdcpServerFromPlatform` does not yet expose an SI specialism — when it does, this skill will document the migration. |
-| `serve(() => createAdcpServer(config))`                              | Start HTTP server on `:3001/mcp`                                                                                                                                                                                                                                                                                                                                                |
-| `ctx.store`                                                          | State persistence — `get/put/patch/delete/list` domain objects. SI sessions live here today (no auto-hydration yet).                                                                                                                                                                                                                                                            |
-| `adcpError(code, { message })`                                       | Structured error                                                                                                                                                                                                                                                                                                                                                               |
-
-Handlers return raw data objects. The framework auto-wraps responses and auto-generates `get_adcp_capabilities` from registered handlers.
-
-Import: `import { createAdcpServer, serve, adcpError } from '@adcp/sdk/server/legacy/v5';`
-
-## Setup
-
-```bash
-npm init -y
-npm install @adcp/sdk
-npm install -D typescript @types/node
-```
-
-Minimal `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "Node16",
-    "moduleResolution": "Node16",
-    "strict": true,
-    "skipLibCheck": true,
-    "outDir": "dist"
-  }
-}
-```
-
-`skipLibCheck: true` avoids false-positive errors from transitive `.d.ts` files (e.g., `@opentelemetry/api`).
-
-## Implementation
-
-1. Single `.ts` file — wire `createAdcpServer` from `@adcp/sdk/server/legacy/v5` with a `sponsoredIntelligence` handler bag
-2. Do not register `get_adcp_capabilities` — the framework generates it from registered handlers
-3. Return raw data objects from handlers — the framework wraps responses automatically
-4. Use `ctx.store` to persist active sessions — track state: active → terminated. **Sessions are NOT auto-hydrated yet** (planned for v6.x). Read `req.session_id` and look the session up in `ctx.store` on every `si_send_message`.
-5. Handlers receive `(params, ctx)` — `ctx.store` for state, `ctx.account` (when `resolveAccount` is wired) for resolved account
-
-```typescript
-import { randomUUID } from 'node:crypto';
-import {
-  createAdcpServer,
-  serve,
-  adcpError,
-  createIdempotencyStore,
-  memoryBackend,
-} from '@adcp/sdk/server/legacy/v5';
-
-const idempotency = createIdempotencyStore({
-  backend: memoryBackend(),
-  ttlSeconds: 86400,
-});
-
-serve(() =>
-  createAdcpServer({
-    name: 'SI Agent',
-    version: '1.0.0',
-    idempotency,
-    // Principal scope for idempotency. MUST never return undefined. The
-    // framework additionally auto-scopes `si_send_message` by `session_id`,
-    // so the same key under two sessions doesn't cross-replay.
-    resolveSessionKey: () => 'default-principal',
-    capabilities: {
-      // SI is a *protocol*, not a specialism. Declare it here; the framework
-      // adds it to `get_adcp_capabilities.supported_protocols`.
-      supported_protocols: ['sponsored_intelligence'],
-    },
-    sponsoredIntelligence: {
-      getOffering: async (req, ctx) => ({
-        available: true,
-        offering_token: `tok_${randomUUID()}`,
-        ttl_seconds: 300,
-      }),
-      initiateSession: async (req, ctx) => {
-        // session_id MUST be high-entropy (≥122 bits) per spec — it's the
-        // scope key for conversational isolation. Never use Date.now() or
-        // predictable counters; a guessable session_id lets one buyer
-        // impersonate another's session.
-        const sessionId = `sess_${randomUUID()}`;
-        await ctx.store.put('session', sessionId, { status: 'active' });
-        return {
-          session_id: sessionId,
-          session_status: 'active',
-        };
-      },
-      sendMessage: async (req, ctx) => {
-        // No auto-hydration of sessions yet — read explicitly. (v6.x will
-        // attach `req.session` for free; until then this lookup is your
-        // session-loss guard.)
-        const session = await ctx.store.get('session', req.session_id);
-        // Return the error — the framework echoes returned adcpError
-        // responses verbatim. Thrown errors are caught and converted to
-        // SERVICE_UNAVAILABLE, which hides your custom code from the buyer.
-        if (!session) return adcpError('RESOURCE_NOT_FOUND', { message: 'Session not found' });
-        return {
-          session_id: req.session_id,
-          session_status: 'active' as const,
-          response: {
-            content: 'Sponsored content response',
-            content_type: 'text',
-          },
-        };
-      },
-      terminateSession: async (req, ctx) => {
-        await ctx.store.delete('session', req.session_id);
-        return {
-          session_id: req.session_id,
-          terminated: true,
-        };
-      },
-    },
-  })
-);
-```
+**Not this skill:**
 
-## Idempotency
+- Selling display/video inventory → `skills/build-seller-agent/`
+- Serving audience segments → `skills/build-signals-agent/`
+- Managing creatives → `skills/build-creative-agent/`
+- Brand identity + rights licensing → `skills/build-brand-rights-agent/`
 
-AdCP v3 requires an `idempotency_key` on every mutating request — for SI agents that's `si_initiate_session` and `si_send_message`. `si_terminate_session` is exempt (naturally idempotent via `session_id`; terminating a terminated session is a no-op, and its schema keeps `idempotency_key` optional). `si_get_offering` is read-only.
+## Cross-cutting rules
 
-Idempotency is wired in the example above. What the framework handles for you:
+Every SI agent hits the cross-cutting rules in [`../cross-cutting.md`](../cross-cutting.md). The high-traffic ones for SI (deep-linked to the rule):
 
-- Rejects missing or malformed `idempotency_key` with `INVALID_REQUEST`. The spec pattern is `^[A-Za-z0-9_.:-]{16,255}$` — short test keys like `"key1"` fail length, not idempotency logic.
-- **`si_send_message` is auto-scoped by `session_id`** in addition to the principal. The same `idempotency_key` used across two sessions does NOT cross-replay — each session has its own idempotency namespace. You don't have to implement this; the framework does it.
-- JCS-canonicalized payload hashing; `IDEMPOTENCY_CONFLICT` on same-key-different-payload (no payload leak — error body is code + message only).
-- `IDEMPOTENCY_EXPIRED` past the TTL (±60s clock-skew tolerance).
-- `replayed: true` on `result.structuredContent.replayed` for cache hits; fresh executions omit the field.
-- Auto-declares `adcp.idempotency.replay_ttl_seconds` on `get_adcp_capabilities`.
-- Only successful responses cache — a failed generation re-executes on retry so buyers can safely retry transient errors without burning the key or double-billing.
+- [`idempotency_key`](../cross-cutting.md#idempotency_key-is-required-on-every-mutating-call) on `si_initiate_session` and `si_send_message`
+- [Authentication](../cross-cutting.md#authentication-is-mandatory) — `serve({ authenticate })` baseline
+- [`ctx_metadata` is not for credentials](../cross-cutting.md#ctx_metadata-is-not-for-credentials) — important for SI because session state is naturally rich; production engines own full transcripts in their own backend, not in `ctx_metadata`
 
-`ttlSeconds` must be in `[3600, 604800]` — out of range throws at `createIdempotencyStore` construction. Don't pass minutes thinking they're seconds.
+One SI-specific note on idempotency:
 
-## Protecting your agent
+`si_initiate_session` and `si_send_message` are mutating and require `idempotency_key`. `si_terminate_session` is naturally idempotent on `session_id` and intentionally lacks the key (re-terminating a closed session must return the same payload). `si_get_offering` is read-only.
 
-**An AdCP agent that accepts unauthenticated requests is non-compliant** (see `security_baseline` in the universal storyboard bundle). Ask the operator: "API key, OAuth, or both?" — then wire one of these into `serve()`.
+## Specialism deltas at a glance
 
-```typescript
-import { serve, verifyApiKey, verifyBearer, anyOf } from '@adcp/sdk/server/legacy/v5';
+**`sponsored-intelligence` protocol** —
 
-// API key — simplest, good for B2B integrations
-serve(createAgent, {
-  authenticate: verifyApiKey({
-    verify: async token => {
-      const row = await db.api_keys.findUnique({ where: { token } });
-      return row ? { principal: row.account_id } : null;
-    },
-  }),
-});
+- **Single brand per deployment is typical** — one Agentforce instance per advertiser, one OpenAI Assistant per brand. Multi-brand variants route via per-API-key tenant binding inside `accounts.resolve`, not by carrying `account` on the wire (SI tool schemas don't have it).
+- **Session state**: the framework auto-hydrates a small `req.session` record (intent, offering scoping, identity consent, negotiated capabilities) onto `si_send_message` / `si_terminate_session`. Production brand engines almost always own full transcript state in their own backend (Postgres, Redis, vector store) — full transcripts, RAG embeddings, tool-call logs are too rich for `ctx_metadata` and easily exceed the 16KB blob cap. Treat `req.session` as a convenience, not authoritative state.
+- **Offerings**: each represents a sponsored experience — product/brand being sponsored, conversation style (informational/promotional/interactive), modalities (text/voice/video/A2UI), TTL on the `offering_token`.
+- **Handoff modes**: `si_terminate_session.reason` is a closed enum — `user_exit | session_timeout | host_terminated | handoff_transaction | handoff_complete`. `handoff_transaction` returns `acp_handoff` with `checkout_url`, `checkout_token`, `expires_at`; `handoff_complete` is conversation-concluded-naturally with no checkout.
 
-// OAuth — best when buyers authenticate as themselves
-const AGENT_URL = 'https://my-agent.example.com/mcp';
-serve(createAgent, {
-  publicUrl: AGENT_URL, // canonical RFC 8707 audience — also served as `resource` in protected-resource metadata
-  authenticate: verifyBearer({
-    jwksUri: 'https://auth.example.com/.well-known/jwks.json',
-    issuer: 'https://auth.example.com',
-    audience: AGENT_URL, // MUST equal publicUrl
-  }),
-  protectedResource: { authorization_servers: ['https://auth.example.com'] },
-});
+## Common shape gotchas
 
-// Both
-serve(createAgent, {
-  publicUrl: AGENT_URL,
-  authenticate: anyOf(verifyApiKey({ verify: lookupKey }), verifyBearer({ jwksUri, issuer, audience: AGENT_URL })),
-  protectedResource: { authorization_servers: [issuer] },
-});
-```
+- **Field is `session_status`, not `status`** — values `'active' | 'pending_handoff' | 'complete' | 'terminated'`. `status: 'active'` fails wire validation.
+- **Termination uses boolean `terminated: true`**, not `status: 'terminated'`.
+- **`si_send_message` response requires `session_id`** even though it's also in the request — echo from `req.session_id`.
+- **`si_get_offering` requires `available: boolean`** at the top level.
+- **`reason` enum is closed** — see above. Anything else fails wire validation.
+- **`product_card` in `ui_elements` requires `data.title` + `data.price`** (not `name`/`display_price`); `action_button` requires `data.label` + `data.action`. Project per-`type` from upstream vocabulary in your handler.
 
-The framework produces RFC 6750-compliant `WWW-Authenticate: Bearer` 401s on failure, and serves `/.well-known/oauth-protected-resource<mountPath>` with `publicUrl` as the `resource` field so buyers get tokens bound to the right audience. The default JWT allowlist is asymmetric-only (RS*/ES*/PS\*/EdDSA) to prevent algorithm-confusion attacks.
+See [`../SHAPE-GOTCHAS.md`](../SHAPE-GOTCHAS.md).
 
-## Validate Locally
-
-**Full validation checklist:** [docs/guides/VALIDATE-YOUR-AGENT.md](../../docs/guides/VALIDATE-YOUR-AGENT.md). SI-specific commands:
+## Validate locally
 
 ```bash
-# Boot
-npx tsx agent.ts &
-
-# Happy path — session lifecycle
-npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp si_baseline --auth $TOKEN
+# Run the fork-matrix gate
+npm run compliance:fork-matrix -- --test-name-pattern="hello-si-adapter-brand"
 
-# Cross-cutting obligations
-npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp \
-  --storyboards security_baseline,idempotency,schema_validation,error_compliance --auth $TOKEN
-
-# Rejection-surface fuzz
-npx @adcp/sdk@latest fuzz http://localhost:3001/mcp \
-  --tools si_get_offering --auth-token $TOKEN
+# Or validate your forked agent directly against the SI baseline
+adcp storyboard run http://127.0.0.1:3007/mcp si_baseline \
+  --bearer "$ADCP_AUTH_TOKEN" --include-bundles --json
 ```
 
-Common failure decoder:
-
-- `status` field on session response → rename to `session_status` (the canonical field name)
-- `status: 'terminated'` → use boolean `terminated: true`
-- Missing `session_id` on `si_send_message` response → echo from request — required
-- Missing `available` boolean on `si_get_offering` → required even for mock data
-- Missing `reason` on `si_terminate_session` request → enum: `user_exit` / `session_timeout` / `host_terminated` / `handoff_transaction` / `handoff_complete`
-
-**Keep iterating until all steps pass.** Can't bind ports? `npm run compliance:skill-matrix -- --filter si` runs an isolated end-to-end test.
-
-## Common Mistakes
-
-| Mistake                                                      | Fix                                                                                                                                                                                                    |
-| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Manually registering `get_adcp_capabilities`                 | Framework auto-generates it from registered handlers — do not register it yourself                                                                                                                     |
-| Using `server.tool()` instead of domain groups               | Use `sponsoredIntelligence: { getOffering, initiateSession, ... }` — framework wires schemas and response builders                                                                                     |
-| Using in-memory Maps for session state                       | Use `ctx.store.put/get/delete` — built-in state persistence                                                                                                                                            |
-| Returns `status` instead of `session_status`                 | Field name is `session_status` — `status` will fail schema validation                                                                                                                                  |
-| Returns `status: 'terminated'` instead of `terminated: true` | Termination response uses boolean `terminated` field                                                                                                                                                   |
-| Missing `session_id` in si_send_message response             | Echo `session_id` back from request — required                                                                                                                                                         |
-| Missing `available` in si_get_offering                       | Boolean `available` is required — even for mock data                                                                                                                                                   |
-| Missing `reason` in si_terminate_session request             | `reason` is required — one of: `user_exit`, `session_timeout`, `host_terminated`, `handoff_transaction`, `handoff_complete`                                                                            |
-| Dropping `context` from responses                            | Let the framework echo — except for `si_get_offering` / `si_initiate_session`, whose request `context` is a string. For those, build your own response context object if correlation tracking matters. |
-
-## Storyboards
+The fork-matrix gate is the three-gate contract from [`docs/guides/EXAMPLE-TEST-CONTRACT.md`](../../docs/guides/EXAMPLE-TEST-CONTRACT.md): tsc strict / storyboard zero-failures / upstream façade.
 
-| Storyboard   | Tests                                                             |
-| ------------ | ----------------------------------------------------------------- |
-| `si_session` | Full session lifecycle: offering → initiate → message → terminate |
+For deeper validation: [`docs/guides/VALIDATE-YOUR-AGENT.md`](../../docs/guides/VALIDATE-YOUR-AGENT.md).
 
-## Reference
+## Migration notes
 
-- `storyboards/si_session.yaml` — full SI session storyboard
-- `docs/guides/BUILD-AN-AGENT.md` — SDK patterns
-- `docs/TYPE-SUMMARY.md` — curated type signatures
-- `docs/llms.txt` — full protocol reference
+- 6.6 → 6.7: SI v6 platform shipped (protocol-keyed dispatch, auto-hydrated session, storyboard 3/3 pass) in 6.7. See [`docs/migration-6.6-to-6.7.md`](../../docs/migration-6.6-to-6.7.md).
+- 4.x → 5.x: A2A session continuity + typed errors landed in 5.9. See [`docs/migration-4.x-to-5.x.md`](../../docs/migration-4.x-to-5.x.md).