feat(docs+compliance): implementer DX — troubleshooting, known-ambiguities, idempotency opt-out (#2607, #2608)

[bokelley]

Summary

Two implementer-facing docs pages + a one-line storyboard edit that unblocks the idempotency missing-key vector through the reference SDK.

• `static/compliance/source/universal/idempotency.yaml` — `create_media_buy_missing_key` now declares `omit_idempotency_key: true`. Without it, the `@adcp/client` SDK auto-injects `idempotency_key` before dispatch and the vector never probes the missing-key rejection path. The SDK already supports this opt-out (`Step.omit_idempotency_key` → `skipIdempotencyAutoInject` in `task-map.js`/`runner.js`); the missing piece was the storyboard declaration. Chose option 1 from the issue (SDK opt-out) over option 2 (raw-HTTP probe) because the SDK's opt-out is first-class, already tested, and documented for this exact use case.
• `storyboard-schema.yaml` — documents `omit_idempotency_key` alongside the other step-level directives so future authors discover it.
• `docs/building/implementation/storyboard-troubleshooting.mdx` (new) — error pattern → root cause → fix. Sections: unknown fixtures, RFC 9421 signature challenges, `errors[]` vs `adcp_error` envelope drift, context echo, capability-vector mismatches, `requireAuthenticatedOrSigned` composition, `INVALID_STATE` vs `INVALID_TRANSITION`.
• `docs/building/implementation/known-ambiguities.mdx` (new) — open spec gaps with workarounds. Entries tracked to Spec: conditional-approval response schema for check_governance — 'conditions' field shape undefined #2603, Spec: storyboards assert fields not required by response schemas (list_id echo, catalog counts, pricing_options, vendor_cost) #2604, Spec clarification: PRM + auth-server metadata required when sandbox has no real OAuth issuer? #2606, Testing infrastructure: idempotency 'missing key' vector can't probe through reference SDK client #2607 (plus spec(compliance): #2373 review follow-ups — schema-mutating lint + past_start_date split (#2376, #2377) #2389 closed for historical reference). Entries will be removed as the underlying issues close.
• `docs.json` — both pages registered in both Implementation Patterns nav arrays (duplicate arrays exist for the versioned / unversioned variants).
• `docs/building/validate-your-agent.mdx` — cross-links both new pages under a new "When a storyboard fails" section above "What's next".

Closes #2607, closes #2608.

Signature error taxonomy

The troubleshooting guide references `RequestSignatureError` from `@adcp/client/signing` with `.code: RequestSignatureErrorCode` (not `signatureErrorCodeFromCause` — that symbol does not exist in the SDK). Full taxonomy: `request_signature_required`, `request_signature_header_malformed`, `request_signature_tag_invalid`, `request_signature_window_invalid`, `request_signature_key_unknown`, and 11 more.

Scope notes

• `INVALID_STATE` vs `INVALID_TRANSITION`: `INVALID_STATE` is canonical for media-buy state rejections (`media-buy/specification.mdx`, `media-buy/media-buys/index.mdx`). `INVALID_TRANSITION` is specific to the `comply_test_controller` sandbox primitive (`comply-test-controller.mdx#state-machine-transitions`). Documented so authors don't accidentally emit `INVALID_TRANSITION` outside the test controller.
• `comply-test-controller.mdx` is orphaned from docs.json nav (exists but isn't in either Implementation Patterns array). Not fixed in this PR — tracked separately.
• Changeset is empty-form (`---\n---`) because this is a docs + runner-hint change, not a protocol-surface change.

Test plan

• `npm run build:compliance` — storyboard scoping lint passes
• `npm run test:docs-nav` — 15/15 pass (both new pages found in both nav arrays)
• Pre-commit — `test:unit` (631/631) + `typecheck` pass
• Reviewer: read the troubleshooting page top-to-bottom and flag any section where the error-text example doesn't match what implementers actually see in the wild

🤖 Generated with Claude Code

[github-actions]

Schema Link Check Results

Commit: 64d24fd - docs: fix anchors, drop closed entry, add conformance cross-link

⚠️ Warnings (schema not yet released)

These schemas exist in source but haven't been released yet. The links will be broken until the next version is published:

• https://adcontextprotocol.org/schemas/v3/enums/specialism.json
  • Schema exists in latest (source) but not yet released in v3
  • Action: This link will work after next 3.x release is published

---

To fix: Either:

1. Wait for the next release and merge this PR after the release is published
2. Use latest instead of a version alias if you need the link to work immediately (note: latest is the development version and may change)
3. Coordinate with maintainers to cut a new release before merging