@adcp/sdk 6.5.0 → 6.7.0

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

@@ -9,6 +9,8 @@ description: Use when building an AdCP signals agent, creating an audience data
 
 A signals agent serves audience segments to buyers for campaign targeting. Two tools: `get_signals` (discovery) and `activate_signal` (push to DSPs or sales agents). The business model — marketplace vs owned data — shapes every implementation decision. Determine that first.
 
+> **Common shape gotchas:** `signal_ids[]` in `get_signals` is `signal_id[]` (provenance objects with `source`/`data_provider_domain`/`id`), not bare strings. `activate_signal` returns deployments with `ActivationKey` `oneOf` — for `type: 'key_value'` the `key` and `value` fields sit at the TOP level of `activation_key`, NOT nested under a `key_value` sub-field. See [SHAPE-GOTCHAS.md](../SHAPE-GOTCHAS.md) for the patterns adopters consistently get wrong on first pass.
+
 ## When to Use
 
 - User wants to build an agent that serves audience/targeting data

package/skills/call-adcp-agent.previous/SKILL.md

@@ -118,8 +118,12 @@ Every validation failure produces:
 - `issues[].pointer` — RFC 6901 JSON Pointer to the field.
 - `issues[].keyword` — AJV keyword (`required`, `type`, `oneOf`, `anyOf`, `additionalProperties`, `format`, `enum`).
 - `issues[].variants` — when the keyword is `oneOf` or `anyOf`, each entry lists one variant's `required` + declared `properties`. **Pick ONE variant**, send only its `required` fields. This is the fastest recovery path when you didn't know the field was a union.
+- `issues[].discriminator` — when an SDK ≥6.7 picks a "best surviving variant" of a const-discriminated union, this is the `[{field, value}, …]` pairs that variant requires. Reads as the validator's verdict on which branch you were inferred to be targeting. Example: `discriminator: [{field: 'type', value: 'key_value'}]` plus `pointer: '/deployments/0/activation_key/key'` and `keyword: 'required'` means "you picked the `key_value` activation_key variant and it requires top-level `key` and `value`." Compound discriminators like `audience-selector`'s `(type, value_type)` produce two-entry arrays.
+- `issues[].schemaId` — `$id` of the rejecting schema. For tools served from the bundled tree this is usually the response root; for flat-tree tools it can land on the deeper sub-schema. Diagnostic only; the actionable lever is `discriminator` + `variants` + `pointer`.
+- `issues[].allowedValues` — closed enum lists for `keyword: 'enum'` issues. Picking from this list closes the case in one round.
+- `issues[].hint` — SDK ≥6.8 only. One-sentence curated recipe for known shape gotchas: discriminator nesting (`activation_key`, VAST `delivery_type`), shape mismatches (`format_id` object, `budget` number, `signal_ids` provenance objects), and discriminator merging (`account`). When present, the hint is the most-direct fix path; read it before walking variants. Absent on the long tail — no hint just means there's no curated rule for the pattern.
 
-Patch the pointers, don't re-guess what the skill or the `variants` already told you, resend. Three attempts should cover every field.
+**Recovery order**: read `hint` first (when present, it's the validated fix path); then `discriminator` (names which branch to fix); then `variants` (lists every option if you're not in a branch); then `pointer` + `keyword` + `message` for the leaf fix. Patch and resend. Three attempts should cover every field.
 
 ## Minimal working examples
 
@@ -205,7 +209,6 @@ Returns `{ signals: [{ signal_agent_segment_id, match_rate, pricing, ... }] }`.
 ## Transport notes
 
 - **MCP**: `tools/call` with `{ name: 'tool_name', arguments: {...} }`. Returns `{ content, structuredContent, isError? }`. Read `structuredContent` for the typed response.
-  - **Use the official `@modelcontextprotocol/sdk` client.** The Streamable HTTP transport requires `Accept: application/json, text/event-stream` on every request — a raw `fetch()` with only `Accept: application/json` gets an unhelpful `406 Not Acceptable` from the server before any AdCP framing runs. The official client sets the header correctly; reach for it instead of rolling your own HTTP plumbing.
 - **A2A**: `message/send` with a `DataPart` of shape `{ skill: 'tool_name', input: {...} }` (the legacy key `parameters` is also accepted). Returns an A2A `Task`; the typed response is at `task.artifacts[0].parts[0].data`.
 
 Both transports share: idempotency, error shape, schema enforcement, and handler semantics. If a call works on one, the equivalent call works on the other.
@@ -226,6 +229,8 @@ Quick lookup before reading the full envelope. Match what you see in `adcp_error
 | Symptom | What it means | Fix |
 |---|---|---|
 | `keyword: 'oneOf'` with `variants[]` | Discriminated union — you sent fields from multiple variants, or none | Pick ONE variant from `variants[]`. Send only its `required` fields. |
+| `discriminator: [{field, value}]` on a `required` issue | Validator inferred which branch you targeted; you missed required fields IN that branch | Read the `discriminator` pair, fill the missing required fields at the same level (don't nest under the discriminator field name). |
+| `hint:` field present on the issue | SDK matched a curated shape-gotcha rule | Apply the hint directly — it's the validated fix path. |
 | 2-3 `additionalProperties` errors at the same pointer | You merged `oneOf` variants ({account_id, brand, operator, …}) | Drop to one variant. Don't keep "extra" fields "for completeness". |
 | `keyword: 'required'`, `pointer: '/idempotency_key'` | Mutating tool, no UUID | Generate fresh UUID per logical operation. Reuse it on retries. |
 | `keyword: 'type'` or `additionalProperties` at `/budget` | Sent `{amount, currency}` | `budget` is a number. Currency is implied by `pricing_option_id`. |
@@ -233,93 +238,10 @@ Quick lookup before reading the full envelope. Match what you see in `adcp_error
 | `keyword: 'enum'` at `/destinations/*/type` | Made-up destination type | Use `'platform'` (with `platform`) or `'agent'` (with `agent_url`). |
 | Response carries `status: 'submitted'` and `task_id` | Async — work is queued, NOT done | Poll via `tasks/get` (A2A) or the MCP async task extension using `task_id`. |
 | `recovery: 'transient'` (rate limit, 5xx, timeout) | Server-side, retry-safe | Retry with the **same** `idempotency_key`. |
-| `406 Not Acceptable` before any AdCP framing | Hand-rolled HTTP without `Accept: text/event-stream` (MCP transport) | Use `@modelcontextprotocol/sdk` client; it sets the right Accept header. |
-| `recovery: 'correctable'` | Buyer-side fix | Read `issues[]`, patch the pointers, resend. Most cases close in one attempt. (See exceptions below — four codes are technically `correctable` but operator-semantically human-escalate.) |
+| `recovery: 'correctable'` | Buyer-side fix | Read `issues[]`, patch the pointers, resend. Most cases close in one attempt. |
 | `recovery: 'terminal'` (account suspended, payment required, …) | Requires human action | Don't retry. Surface to the user. |
 | HTTP 401 with `WWW-Authenticate` header | Missing or expired credential | Add `Authorization` per the agent's auth spec; re-auth if applicable. |
 
-> **⚠️ Four codes are technically `correctable` but operator-semantically human-escalate. Don't auto-tweak.**
->
-> - **`POLICY_VIOLATION`** — buyer's content/targeting violates seller policy. Auto-mutating creative or targeting and resubmitting **looks like evasion** to the seller's governance reviewer. Surface to a human.
-> - **`COMPLIANCE_UNSATISFIED`** — required disclosure can't be satisfied by the chosen format. Auto-relaxing the compliance section IS the compliance failure. Surface to a human.
-> - **`GOVERNANCE_DENIED`** — registered governance agent rejected the spend. Auto-shrinking budget and retrying looks like governance evasion. Surface to the plan operator.
-> - **`AUTH_REQUIRED`** — conflates missing creds (genuinely correctable) with revoked / expired creds (operator must rotate). Until [adcontextprotocol/adcp#3730](https://github.com/adcontextprotocol/adcp/issues/3730) splits this into `auth_missing` + `auth_invalid`, treat as escalate-after-one-attempt.
->
-> Spec recovery on these is `correctable`; operator behavior is human-in-loop. The pattern: read `error.message` + `error.suggestion`, surface to the user, **don't loop**.
-
-### Operationalize the recovery rules — `decideRetry`
-
-`@adcp/sdk` exports `decideRetry(error, ctx?)` which encodes the operator-grade defaults from the table above plus this section. It returns a discriminated `RetryDecision` so the type system enforces the same-vs-fresh `idempotency_key` rule:
-
-```typescript
-import { decideRetry } from '@adcp/sdk';
-import { randomUUID } from 'node:crypto';
-
-async function callWithRetry(toolName: string, params: Record<string, unknown>): Promise<unknown> {
-  let attempt = 1;
-  let idempotencyKey = randomUUID();
-
-  while (true) {
-    try {
-      return await agent.call(toolName, { ...params, idempotency_key: idempotencyKey });
-    } catch (e) {
-      const error = extractAdcpError(e); // your SDK's error extractor
-      if (!error) throw e; // not an AdCP-shaped failure — let it bubble
-
-      const decision = decideRetry(error, { attempt });
-
-      if (decision.action === 'retry') {
-        // Server-side transient (RATE_LIMITED, SERVICE_UNAVAILABLE, CONFLICT).
-        // Replay with the SAME idempotency_key after the suggested delay.
-        await sleep(decision.delayMs);
-        attempt++;
-        continue;
-      }
-
-      if (decision.action === 'mutate-and-retry') {
-        // Buyer-fixable. Apply the seller's correction (decision.field /
-        // decision.suggestion) and mint a FRESH idempotency_key — payload
-        // changed, so the seller's replay-window must NOT dedupe.
-        params = applyCorrection(params, error, decision); // your domain logic
-        idempotencyKey = randomUUID();
-        await sleep(decision.delayMs); // small jitter (~125-250ms by default)
-        attempt++;
-        continue;
-      }
-
-      // 'escalate' — stop the loop and surface to a human. Includes
-      // commercial-relationship signals (POLICY_VIOLATION etc.), auth
-      // failures, IDEMPOTENCY_EXPIRED (do a natural-key check first!),
-      // attempt-cap exhaustion, and unknown vendor codes.
-      throw new EscalationRequired(decision.reason, decision.message);
-    }
-  }
-}
-```
-
-The discriminated union means TypeScript narrows correctly in each branch — `decision.delayMs` is only available on retry/mutate-and-retry, `decision.field` only on mutate-and-retry, `decision.message` only on escalate.
-
-For per-vertical overrides (e.g., a creative-template platform that legitimately auto-fixes `CREATIVE_REJECTED` format mismatches), instantiate `BuyerRetryPolicy` directly:
-
-```typescript
-import { BuyerRetryPolicy } from '@adcp/sdk';
-
-const policy = new BuyerRetryPolicy({
-  overrides: {
-    CREATIVE_REJECTED: (error) => {
-      if (error.field === 'creative.format' && /unsupported_format/.test(error.message)) {
-        return { action: 'mutate-and-retry', delayMs: 0, attemptCap: 2, sameIdempotencyKey: false, reason: 'capability' };
-      }
-      return null; // fall through to default (escalate as commercial)
-    },
-  },
-});
-
-const decision = policy.decide(error, { attempt });
-```
-
-Default policy is intentionally conservative — see the source comments in `src/lib/utils/buyer-retry-policy.ts` for per-code reasoning.
-
 If your symptom isn't here, fall through to the next section.
 
 ## If you get stuck

package/skills/run-by-experts/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: run-by-experts
+description: Use before opening a SUBSTANTIVE PR (protocol changes, multi-tenant or auth surfaces, adopter-facing examples, refactors that span specialism modules). Fires multiple expert reviewers in parallel and uses convergence as the blocker signal — items flagged by 2+ reviewers are real; single-reviewer findings are usually preferences. Skip for trivial changes (single-line fixes, README typos, mechanical refactors).
+---
+
+# Run by Experts
+
+## Overview
+
+Multi-reviewer parallel review where **convergence is the load-bearing signal**. Items flagged by two or more reviewers are real blockers. Single-reviewer findings are usually preferences worth considering but not gating.
+
+This skill exists because solo Claude review on a non-trivial PR catches obvious bugs but misses domain-specific landmines (multi-tenant isolation, protocol shape, type-system gotchas, adopter-DX cliffs). Each expert reviewer carries different domain priors; running them in parallel and acting on the intersection produces a better signal than any single review.
+
+## When to use
+
+**Always run before opening:**
+
+- Protocol-level changes (request/response shapes, error codes, new specialism interfaces)
+- Multi-tenant or auth surfaces (isolation gates, credential handling, sandbox boundaries)
+- Adopter-facing examples (`examples/hello_*`, skill files, public docs)
+- Bug fixes where the root cause might be either side of an interface boundary
+
+**Optional but high-value:**
+
+- Refactors that span multiple specialism modules
+- API surface changes (export shape, type changes, deprecations)
+- New subagent prompts or skill files
+
+**Skip:**
+
+- Trivial changes (changesets, single-line bug fixes with obvious test coverage, README typos)
+- Pure mechanical refactors (rename, dead-code removal) where you've verified no behavior change
+
+## The reviewer set
+
+Pick the relevant subset for the PR. Default for a substantive change is all four:
+
+| Reviewer                  | Focus                                                                                                       | Fire when                                                                                           |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `ad-tech-protocol-expert` | Wire shape vs spec, error code placement, schema conformance, protocol contract                             | Any protocol-touching change                                                                        |
+| `code-reviewer`           | Correctness, type-safety, dead code, casts, edge cases, hidden control flow                                 | All non-trivial code changes                                                                        |
+| `security-reviewer`       | Tenant isolation, auth/credential handling, prompt-injection surfaces, fail-open vs fail-closed gates, SSRF | Any change that touches auth, multi-tenancy, or buyer-supplied data flowing through error envelopes |
+| `dx-expert`               | Forkability, SWAP markers, header doc clarity, copy-paste anti-patterns, README discoverability             | Any adopter-facing example or doc change                                                            |
+
+For protocol-only / spec-side changes, `adtech-product-expert` (buy-side / sell-side product fit) is often a fifth.
+
+## How to fire
+
+Single message, multiple `Agent` tool calls in parallel — never sequential. Run-in-background unless the PR is so small that you'll wait on the first one. Each prompt is **self-contained**: the agent has no memory of the conversation, so include:
+
+- File paths in scope
+- Branch name
+- Specific items the prior round (if any) claimed to fix — verify each
+- Specific concerns you want flagged (don't ask "what do you think?" — that produces shallow review)
+- Word budget ("Under 500 words")
+- Format expectation ("Report: blockers / concerns / fine, per item")
+
+Example brief shape (excerpted from `bokelley/hello-adapters-gov-rights` round 2):
+
+> Re-review of PR #XXXX. Prior round flagged 17 findings; all blockers + must-fix concerns claimed addressed. Verify, and flag any NEW issues introduced by the fixes.
+>
+> Files in scope: `examples/foo.ts` (new, ~1200 lines).
+>
+> Prior-round items that should be fixed — verify each:
+>
+> 1. ...
+> 2. ...
+>
+> New questions for this round:
+>
+> 1. ...
+>
+> Report: blockers / suggestions / nits. Under 500 words. Don't restate prior-round findings unless the fix introduces a new issue.
+
+## Reading the results
+
+**Convergence (2+ reviewers same finding) = real blocker.** Act on these unconditionally.
+
+**Single-reviewer must-fix = should-fix.** Read the reasoning; usually it's worth doing but defensibly skippable. Push back if the finding contradicts the convergent signals.
+
+**Advisory = nice-to-have.** Roll into a follow-up issue or comment-only fix.
+
+The convergence signal is doing real work. From the production example (round 1 of the multi-tenant adapter PR):
+
+- The `as unknown as { account?: ... }` cast was flagged by THREE of four reviewers (code: "may be reading a runtime-undefined field"; DX: "cargo-cult-bait"; protocol: implicitly endorsed by saying "should pull from `ctx.account`"). All three independently spotted that the cast was a real bug, not a style preference.
+- Single-reviewer concerns were mostly preferences (helper extraction style, comment placement nits). Worth doing but not gating.
+
+## Two-round pattern
+
+For substantive PRs, run **two rounds**:
+
+1. **Round 1 — initial review.** Fire all relevant reviewers on the unreviewed code. Consolidate findings by convergence. Apply blockers + must-fix.
+2. **Round 2 — re-review of fixes.** Fire the same reviewers again, asking each to (a) verify each prior-round finding is fixed and (b) flag any NEW issues the fix introduced.
+
+Round-2 finds the regressions fix-blindness misses. Production example: round 2 caught a fail-OPEN tenant gate that round 1's fix had introduced (the gate was `if (homeTenantId && tenantId !== homeTenantId)` — when `homeTenantId` is undefined, the check skips; round 1 hadn't considered that path).
+
+## Process artifacts to ship with the PR
+
+After all rounds land, the PR description should include:
+
+- A consolidated "Expert review" section listing each round's blockers and how each was addressed
+- The reviewer convergence signal (e.g., "3 of 4 flagged X" → "this was the real bug")
+- Any single-reviewer items that were intentionally NOT fixed, with reasoning
+- Cross-links to upstream-spec issues filed during review (if storyboards or spec gaps surfaced — see `skills/triage-storyboard-failure/`)
+
+## What this skill is NOT
+
+- A replacement for human reviewers — convergent expert review surfaces issues fast, but humans make the final call on whether to merge
+- An excuse to skip writing tests — reviewers can't verify behavior they can't run
+- A substitute for `npm run typecheck` / `npm run format:check` / CI — those gate-before-review
+
+## See also
+
+- `skills/triage-storyboard-failure/` — when an expert review (or your own testing) surfaces a storyboard-vs-spec mismatch
+- `examples/CONTRIBUTING.md` — the SWAP-marker and DO-NOT-DEPLOY-AS-IS conventions DX reviewers will check for
+- `~/.claude/commands/prep-for-pr.md` (personal command) — calls this skill plus the build/test/security-review chain

package/skills/triage-storyboard-failure/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: triage-storyboard-failure
+description: Use when an AdCP compliance storyboard fails on an adapter you believe is spec-correct. Walks the rubric for deciding whether to fix the SDK, the adapter, or file upstream against the spec/storyboard.
+---
+
+# Triage a Storyboard Failure
+
+## Overview
+
+Storyboards in `compliance/cache/<version>/` are assertions about adopter behavior. They are **not** the spec — they are tests authored against the spec. Storyboards drift. When one fails, the question is _which side is wrong_: the adapter, the SDK, or the storyboard itself.
+
+This skill is the rubric for that decision. It exists because adopter-facing failures look identical regardless of cause, and the wrong-direction fix (changing the SDK to satisfy a storyboard that disagrees with the spec) compounds drift across the ecosystem.
+
+## When to Use
+
+- A `storyboard run` step fails on an adapter you believe satisfies the spec
+- The runner reports `expect_error.code` mismatch, `context_outputs path did not resolve`, or a `response_schema` failure on a response that round-trips through the generated TS types
+- You're tempted to add a field, change an error code, or adjust a response shape "to make the test pass"
+
+**Not this skill:**
+
+- Real adopter bugs (your handler returns malformed data, throws unexpectedly, ignores a required field) — fix the adapter
+- Wire-schema validation failures (`additionalProperties`, missing required) on requests YOU sent — fix the request
+
+## The rubric
+
+For any failing step, work the three checks in order. **Stop at the first answer.**
+
+### 1. Does the spec define the contract the storyboard is asserting?
+
+Open the schema the storyboard's step references (`schemas/cache/<version>/<protocol>/<tool>-response.json` or similar). Find the field, error code, or shape the storyboard expects.
+
+- **Field exists in the spec, with the shape the storyboard expects** → continue to step 2.
+- **Field exists in the spec but with a different shape** → spec or storyboard mismatch; the storyboard is wrong. File upstream against `adcontextprotocol/adcp`. Cite the schema file path + line.
+- **Field does NOT exist in the spec** → the storyboard authored an opinion that has no spec basis. The storyboard is wrong. File upstream.
+- **Spec is silent** (the contract is ambiguous) → flag the spec gap upstream. The storyboard's interpretation may be reasonable, but adopters can't know which interpretation to follow without spec clarity.
+
+### 2. Does the SDK shape match the spec?
+
+If the spec defines the contract correctly, check whether the SDK's generated TS types and runtime validators match it. Read the relevant `src/lib/types/*.generated.ts` interface and confirm:
+
+- Every `required` field in the schema is present and non-optional in the TS type
+- Every discriminator (e.g., `asset_type`, `status`) is preserved (codegen sometimes strips `oneOf` discriminators when generating union types)
+- Format constraints (date vs date-time, URL pattern, idempotency_key length/pattern) are reflected in either the TS type or the framework's runtime validator
+
+- **TS type matches spec, runtime validation works** → continue to step 3.
+- **TS type allows what spec rejects (or vice versa)** → SDK bug. Fix the codegen or hand-fix the type. File against `adcp-client`.
+
+### 3. Is the storyboard's expectation actually testable from the request the runner sent?
+
+Run the failing step in step mode (`adcp storyboard step <agent> <storyboard_id> <step_id> --json`) and inspect:
+
+- The actual request payload the runner sent
+- The actual response your adapter returned
+- Each `validations[]` entry's pass/fail
+
+Common patterns:
+
+- **`context_outputs path did not resolve`** → the runner couldn't capture a value from your response under the expected path. Check whether the path matches what the spec defines (e.g., adcp#3892 captured `rights_grant_id` but the spec field is `rights_id` — storyboard was wrong).
+- **`expect_error: code: X`** but your adapter returned a structured success response (e.g., `AcquireRightsRejected` with `reason`) → storyboard is asserting a thrown-error shape when the spec gives a first-class denial arm. Storyboard convention, not spec contract. File upstream.
+- **`unresolved context variables from prior steps`** → the runner can't seed a variable the storyboard requires. Runner gap. File upstream against the storyboard runner.
+
+## Heuristics
+
+- **Generated TS types** are not always tighter than the schema. Discriminator fields, `additionalProperties: false` constraints, and `oneOf` arms can be loosened during codegen. Trust the JSON Schema as ground truth.
+- **`response_schema` validation passes but the step still fails** → almost always a storyboard `context_outputs` or `expect_error` mismatch. Your response is correct; the test's assertion is wrong.
+- **A storyboard expects a thrown error code** (`expect_error: true` + `code: X`) when the spec defines a structured denial arm → the storyboard is shipping a non-spec convention. The Rejected/Pending/Acquired union is the canonical shape; thrown error codes are for system failures (timeout, unreachable), not policy decisions.
+- **`requires_scenarios:`** in a storyboard YAML lists prerequisite scenarios that must run first. Step-mode runs lose this dependency; use full `storyboard run` mode to verify, then re-step the failing piece for diagnostics.
+
+## What to file
+
+When the rubric points upstream, file with this template:
+
+> **Title**: `<storyboard_id>` step `<step_id>`: `<assertion>` is non-spec — `<canonical_shape>` is the canonical wire shape
+>
+> **Repro**: Run any spec-compliant adapter; show the failing step's `--json` output.
+>
+> **Root cause**: Cite the spec schema file path + line that defines (or is silent on) the contract the storyboard asserts.
+>
+> **Fix**: Update the storyboard YAML (or the spec doc-comment, if the spec is genuinely ambiguous).
+
+Cross-link to the adapter PR that surfaced it. The storyboard maintainers see the convergent signal across adopters and can prioritize.
+
+## Examples from production
+
+Real triage walks from this codebase:
+
+- **adcontextprotocol/adcp#3892** (closed): brand-rights storyboard's `acquire_rights` step captured `rights_grant_id` via `context_outputs`. Spec field is `rights_id`. Cascading skip on next step. **Resolution**: spec → field is `rights_id`; storyboard is wrong; filed; closed.
+- **adcontextprotocol/adcp#3914** (open): brand-rights/governance_denied storyboard's `acquire_rights_denied` step expected thrown `code: GOVERNANCE_DENIED`. Spec gives `AcquireRightsRejected` arm with `reason`. **Resolution**: storyboard is asserting a non-spec convention; filed upstream; adapter ships spec-correct shape.
+- **adcontextprotocol/adcp#3913** (open): `brand_rights/governance_denied` storyboard step `sync_governance` skips because `$context.governance_agent_url` is unresolved; runner has no `--context` flag for full `storyboard run` mode. **Resolution**: runner gap, not adapter or spec gap; filed upstream.
+
+## See also
+
+- CLAUDE.md (this repo): "When a compliance storyboard fails, triage before patching" — the inline guidance this skill expands.
+- `docs/guides/VALIDATE-YOUR-AGENT.md` — adopter-facing validation flow that runs storyboards.
+- `docs/development/WIRE-VERSION-COMPAT.md` — storyboard cache layout per spec version.