@adcp/sdk 7.11.1 → 7.11.2

package/compliance/cache/{3.0.12.previous → 3.0.18}/universal/schema-validation.yaml

@@ -32,8 +32,26 @@ caller:
 
 prerequisites:
   description: |
-    The caller needs a brand identity for product discovery requests.
+    The caller needs a brand identity for product discovery requests. The runner
+    also seeds the product and pricing option referenced by the temporal
+    create_media_buy requests so date validation is isolated from catalog
+    availability.
   test_kit: "test-kits/acme-outdoor.yaml"
+  controller_seeding: true
+
+fixtures:
+  products:
+    - product_id: "test-product"
+      delivery_type: "non_guaranteed"
+      channels: ["display"]
+      format_ids:
+        - id: "display_300x250"
+  pricing_options:
+    - product_id: "test-product"
+      pricing_option_id: "test-pricing"
+      pricing_model: "cpm"
+      currency: "USD"
+      floor_price: 1.0
 
 phases:
   - id: capability_discovery
@@ -110,7 +128,9 @@ phases:
 
         sample_request:
           buying_mode: "brief"
-          brief: "Show all available advertising products"
+          brief: "Return a small representative sample of available advertising products"
+          pagination:
+            max_results: 5
           account:
             brand:
               domain: "acmeoutdoor.example"
@@ -158,6 +178,8 @@ phases:
         sample_request:
           buying_mode: "brief"
           brief: "Premium display inventory with pricing details"
+          pagination:
+            max_results: 5
           account:
             brand:
               domain: "acmeoutdoor.example"
@@ -224,7 +246,9 @@ phases:
 
         sample_request:
           buying_mode: "brief"
-          brief: "Show all available advertising products with creative format requirements"
+          brief: "Return one representative product with creative format requirements"
+          pagination:
+            max_results: 1
           account:
             brand:
               domain: "acmeoutdoor.example"
@@ -232,6 +256,9 @@ phases:
           context:
             correlation_id: "schema_validation--get_products_for_formats"
 
+        context_outputs:
+          - name: product_format_id
+            path: "products[0].format_ids[0]"
         validations:
           - check: response_schema
             description: "Response matches get-products-response.json schema"
@@ -261,9 +288,10 @@ phases:
       - id: list_formats_match
         title: "Verify format catalog includes product formats"
         narrative: |
-          Call list_creative_formats and verify that the formats returned include
-          the same agent_url as the format_ids on products. The seller's format
-          catalog must cover every format referenced by its products.
+          Call list_creative_formats for the first format_id returned on a
+          product and verify that the format catalog resolves that exact
+          reference. The seller's format catalog must cover that referenced
+          format.
         task: list_creative_formats
         schema_ref: "creative/list-creative-formats-request.json"
         response_schema_ref: "creative/list-creative-formats-response.json"
@@ -271,7 +299,7 @@ phases:
         comply_scenario: schema_compliance
         stateful: false
         expected: |
-          Return formats matching the agent's own product format_ids:
+          Return the format matching the agent's own product format_id:
           - format_id.agent_url must match the agent's own URL
           - format_id.id values must include those referenced by products
           - Each format must define asset requirements (types, dimensions, mime types)
@@ -280,6 +308,10 @@ phases:
           list_creative_formats, buyers cannot construct valid sync_creatives requests.
 
         sample_request:
+          format_ids:
+            - "$context.product_format_id"
+          pagination:
+            max_results: 1
           context:
             correlation_id: "schema_validation--list_formats_match"
 
@@ -292,6 +324,10 @@ phases:
           - check: field_present
             path: "formats[0].format_id.id"
             description: "Formats include format_id with id"
+          - check: field_value
+            path: "formats[0].format_id"
+            value: "$context.product_format_id"
+            description: "Filtered format response returns the product's exact format_id"
           - check: field_present
             path: "context"
             description: "Response echoes back the context object"
@@ -314,6 +350,7 @@ phases:
           Send a create_media_buy request where end_time is before start_time. The agent
           must reject this with an INVALID_REQUEST error.
         task: create_media_buy
+        requires_tool: create_media_buy
         schema_ref: "media-buy/create-media-buy-request.json"
         response_schema_ref: "media-buy/create-media-buy-response.json"
         doc_ref: "/media-buy/task-reference/create_media_buy"
@@ -334,8 +371,8 @@ phases:
               domain: "acmeoutdoor.example"
             operator: "pinnacle-agency.example"
           idempotency_key: "$generate:uuid_v4#schema-validation-reversed-dates"
-          start_time: "2026-12-31T00:00:00Z"
-          end_time: "2026-01-01T00:00:00Z"
+          start_time: "2099-12-31T00:00:00Z"
+          end_time: "2099-01-01T00:00:00Z"
           packages:
             - product_id: "test-product"
               budget: 10000
@@ -380,6 +417,7 @@ phases:
           universal/idempotency.yaml), and the storyboard couldn't tell
           which rule fired.
         task: create_media_buy
+        requires_tool: create_media_buy
         schema_ref: "media-buy/create-media-buy-request.json"
         response_schema_ref: "media-buy/create-media-buy-response.json"
         doc_ref: "/media-buy/task-reference/create_media_buy"
@@ -387,7 +425,7 @@ phases:
         expect_error: true
         negative_path: payload_well_formed
         stateful: false
-        contributes: true
+        contributes_to: past_start_handled
         expected: |
           Reject the request with:
           - Error code: INVALID_REQUEST
@@ -401,7 +439,7 @@ phases:
               domain: "acmeoutdoor.example"
             operator: "pinnacle-agency.example"
           start_time: "2020-01-01T00:00:00Z"
-          end_time: "2026-12-31T23:59:59Z"
+          end_time: "2099-12-31T23:59:59Z"
           packages:
             - product_id: "test-product"
               budget: 10000
@@ -448,12 +486,13 @@ phases:
           auto-adjusts the start_time forward, and returns a media_buy_id.
           idempotency_key is present because the request is a real mutation.
         task: create_media_buy
+        requires_tool: create_media_buy
         schema_ref: "media-buy/create-media-buy-request.json"
         response_schema_ref: "media-buy/create-media-buy-response.json"
         doc_ref: "/media-buy/task-reference/create_media_buy"
         comply_scenario: temporal_validation
         stateful: false
-        contributes: true
+        contributes_to: past_start_handled
         expected: |
           Accept the request with auto-adjusted dates:
           - Response matches create-media-buy-response.json schema
@@ -468,7 +507,7 @@ phases:
               domain: "acmeoutdoor.example"
             operator: "pinnacle-agency.example"
           start_time: "2020-01-01T00:00:00Z"
-          end_time: "2026-12-31T23:59:59Z"
+          end_time: "2099-12-31T23:59:59Z"
           packages:
             - product_id: "test-product"
               budget: 10000

package/compliance/cache/{3.0.12 → 3.0.18}/universal/security.yaml

@@ -2,7 +2,7 @@ id: security_baseline
 version: "1.0.0"
 title: "Authentication baseline"
 category: security
-summary: "Every AdCP agent MUST require authentication on protected operations. At least one of API key or OAuth MUST be implemented and correctly advertised."
+summary: "Every AdCP agent MUST require authentication on protected operations. At least one of static credentials or OAuth MUST be implemented and correctly advertised."
 track: security
 required_tools: []  # protocol-level, not tool-level
 
@@ -18,31 +18,42 @@ narrative: |
   `list_creative_formats`, `get_products` without pricing) are public; operations
   that return tenant-scoped data or modify state (`list_creatives`, `create_media_buy`,
   `get_media_buy_delivery`, `sync_creatives`, etc.) require credentials. See
-  [/docs/building/integration/authentication](/docs/building/integration/authentication).
-
-  AdCP accepts two credential mechanisms: static API keys (Authorization: Bearer <key>)
-  or OAuth 2.0 + RFC 8707 resource indicators. An agent MUST implement at least one.
-  It MAY implement both. This storyboard verifies that (a) a protected operation is
-  rejected when called without credentials, (b) a deliberately invalid key is also
-  rejected (an agent that 200s on an unauth call and 200s on a bad-key call is
-  ignoring credentials entirely), and (c) at least one auth mechanism is present and
-  correctly advertised.
-
-  Pass semantics are encoded in the step flow: the unauth probe and invalid-key
-  probe (when a test-kit key is present) are always required, and at least one of
-  the API key phase or the OAuth discovery phase must contribute
-  `auth_mechanism_verified`. Agents that fail any required phase, or advertise no
-  working auth mechanism, are non-conformant.
-
-  **API-key-only agents (no OAuth).** An agent with no OAuth issuer — sandbox,
-  staging, or any production deployment that chose Bearer-only auth — does NOT
-  need to advertise RFC 9728 protected-resource metadata. Declare
-  `auth.api_key` in the test-kit and do not serve
-  `/.well-known/oauth-protected-resource/...`. The `api_key_path` phase
-  contributes `auth_mechanism_verified` and `oauth_discovery` is allowed to fail
-  silently as an optional phase — no fake issuer URL or stub RFC 8414 metadata
-  document is required. Agents that DO advertise `authorization_servers` in
-  their PRM MUST stand up the RFC 8414 auth-server metadata document to match;
+  [/docs/building/by-layer/L2/authentication](/docs/building/by-layer/L2/authentication).
+
+  AdCP accepts three credential mechanisms: static API keys (Authorization:
+  Bearer <key>), HTTP Basic credentials sent in the Authorization header, or OAuth
+  2.0 + RFC 8707 resource indicators. An agent MUST implement at least one. It
+  MAY implement more than one. This storyboard verifies that (a) a protected
+  operation is rejected when called without credentials, (b) deliberately invalid
+  credentials are also rejected (an agent that 200s on an unauth call and 200s on
+  a bad-credential call is ignoring credentials entirely), and (c) at least one
+  auth mechanism is present and correctly advertised.
+
+  Pass semantics are encoded in the step flow: the unauth probe and
+  invalid-credential probe (when a test-kit key or Basic credential is present)
+  are always required, and at least one of the API key phase, Basic phase, or
+  OAuth discovery phase must contribute `auth_mechanism_verified`. Agents that
+  fail any required phase, or advertise no working auth mechanism, are
+  non-conformant.
+
+  Positive static-credential probes MUST run through the normal protocol
+  session lifecycle. For MCP, that means the runner authenticates the
+  Streamable HTTP session with the test-kit credential, performs `initialize`,
+  and then calls the protected probe task on that initialized session. A server
+  that rejects a direct, unauthenticated-session `tools/call` carrying only an
+  `Authorization: Bearer ...` header is not failing this phase; the raw direct
+  path is reserved for unauthenticated and deliberately invalid-credential
+  rejection probes.
+
+  **Static-credential agents (no OAuth).** An agent with no OAuth issuer -
+  sandbox, staging, or any production deployment that chose Bearer or Basic auth
+  - does NOT need to advertise RFC 9728 protected-resource metadata. Declare
+  `auth.api_key` or `auth.basic` in the test-kit and do not serve
+  `/.well-known/oauth-protected-resource/...`. The matching static-credential
+  phase contributes `auth_mechanism_verified` and `oauth_discovery` is allowed
+  to fail silently as an optional phase - no fake issuer URL or stub RFC 8414
+  metadata document is required. Agents that DO advertise `authorization_servers`
+  in their PRM MUST stand up the RFC 8414 auth-server metadata document to match;
   advertising an issuer without serving its metadata is the failure mode this
   storyboard was written to catch.
 
@@ -65,13 +76,16 @@ prerequisites:
     — an auth-required, read-only task the agent supports (`list_creatives`,
     `get_media_buy_delivery`, `get_signals`, etc.). The runner defaults to
     `list_creatives` if unspecified. This is the task used for both the unauth and
-    invalid-key probes, since public tasks like `get_adcp_capabilities` return 200
-    without credentials by design.
+    invalid-credential probes, since public tasks like `get_adcp_capabilities`
+    return 200 without credentials by design.
 
-    The test kit MAY also provide an API key at `auth.api_key`. If absent, the API
-    key phase is skipped and the OAuth discovery phase MUST succeed instead. OAuth
-    discovery probes the well-known endpoint directly and does not require any
-    test-kit input.
+    The test kit MAY also provide an API key at `auth.api_key` or HTTP Basic
+    credentials at `auth.basic`. Positive static-credential probes use those
+    credentials as the runner's normal transport authentication, including the
+    protocol initialization handshake before the protected task call. If both
+    are absent, the static-credential phases are skipped and the OAuth discovery
+    phase MUST succeed instead. OAuth discovery probes the well-known endpoint
+    directly and does not require any test-kit input.
 
     Agent URLs MUST use `https://` in production compliance runs. The runner rejects
     `http://` agent URLs outright unless invoked with `--allow-http` for local dev.
@@ -89,11 +103,12 @@ phases:
       apply to an anonymous caller. Anything else (200, 500, network hang) is
       non-conformant.
 
-      On 401, the response MUST include a `WWW-Authenticate` header per RFC 6750 §3
-      so clients know how to authenticate. A correct example:
+      On 401, the response MUST include a `WWW-Authenticate` header so clients
+      know how to authenticate. Correct examples:
 
       ```
       WWW-Authenticate: Bearer realm="https://agent.example.com/mcp", as_uri="https://auth.example.com"
+      WWW-Authenticate: Basic realm="https://agent.example.com/mcp"
       ```
 
     steps:
@@ -118,8 +133,9 @@ phases:
         expected: |
           The agent rejects the request with:
           - http_status: 401 (preferred) or 403
-          - On 401, a `WWW-Authenticate: Bearer ...` header per RFC 6750 §3
+          - On 401, a `WWW-Authenticate` header naming the supported scheme
           - Example: `WWW-Authenticate: Bearer realm="<agent-url>", as_uri="<auth-server>"`
+          - Example: `WWW-Authenticate: Basic realm="<agent-url>"`
 
         sample_request:
           context:
@@ -131,12 +147,12 @@ phases:
             description: "Agent returned 200 or 5xx on an unauthenticated protected call — it MUST reject with 401 (and send WWW-Authenticate) or 403"
           - check: on_401_require_header
             value: "www-authenticate"
-            description: "401 responses MUST include a WWW-Authenticate header per RFC 6750 §3 (e.g. `Bearer realm=\"<agent-url>\", as_uri=\"<auth-server>\"`)"
+            description: "401 responses MUST include a WWW-Authenticate header naming the supported scheme (e.g. `Bearer realm=\"<agent-url>\", as_uri=\"<auth-server>\"` or `Basic realm=\"<agent-url>\"`)"
 
   - id: api_key_path
     title: "API key mechanism"
     narrative: |
-      **This phase OR `oauth_discovery` MUST pass — see `mechanism_required`.**
+      **This phase OR `basic_path` OR `oauth_discovery` MUST pass — see `mechanism_required`.**
 
       If the test kit provides an API key, the agent MUST accept it on the protected
       probe task AND MUST reject a deliberately invalid key. Both checks together
@@ -154,30 +170,25 @@ phases:
       - id: probe_api_key
         title: "Call the protected probe task with the provided API key"
         narrative: |
-          Authenticate with the API key supplied by the test kit (as a Bearer token
-          in the Authorization header) and expect a normal 200 response on the
-          declared protected task. This confirms the static-credential path works
-          end to end.
+          Authenticate the protocol session with the API key supplied by the
+          test kit (as a Bearer token in the Authorization header), perform the
+          normal transport initialization handshake, and call the declared
+          protected task. This confirms the static-credential path works end
+          to end for a real buyer session.
         task: "$test_kit.auth.probe_task"
         task_default: list_creatives
         doc_ref: "/protocol/authentication"
         comply_scenario: security_api_key
         stateful: false
-        auth:
-          type: api_key
-          from_test_kit: true
         expected: |
-          The agent accepts the API key and returns a well-formed response with
-          http_status 200.
+          The initialized session accepts the API key and returns a well-formed
+          successful response.
 
         sample_request:
           context:
             correlation_id: "security_baseline--probe_api_key"
 
         validations:
-          - check: http_status
-            value: 200
-            description: "Agent accepts the provided API key on the protected probe task"
           - check: field_present
             path: "context"
             description: "Response echoes back the context object"
@@ -230,17 +241,114 @@ phases:
             value: "www-authenticate"
             description: "401 responses on invalid credentials MUST include WWW-Authenticate with `error=\"invalid_token\"` per RFC 6750 §3"
 
+  - id: basic_path
+    title: "HTTP Basic auth mechanism"
+    narrative: |
+      **This phase OR `api_key_path` OR `oauth_discovery` MUST pass — see
+      `mechanism_required`.**
+
+      If the test kit provides Basic credentials, the agent MUST accept them on
+      the protected probe task AND MUST reject deliberately invalid Basic
+      credentials. Both checks together prove the Basic credential is actually
+      enforced. Basic is a static shared-secret mechanism like a Bearer API key;
+      it is acceptable for conformance when sent in the Authorization header over
+      HTTPS and validated on every protected request. If no Basic credential is
+      provided the phase is skipped and another auth mechanism must succeed
+      instead.
+
+    optional: true
+    skip_if: "!test_kit.auth.basic"
+    branch_set:
+      id: auth_mechanism_verified
+      semantics: any_of
+
+    steps:
+      - id: probe_basic
+        title: "Call the protected probe task with the provided Basic credential"
+        narrative: |
+          Authenticate the protocol session with the Basic credential supplied
+          by the test kit (as an `Authorization: Basic ...` header), perform
+          the normal transport initialization handshake, and call the declared
+          protected task. This confirms the Basic credential path works end to
+          end for a real buyer session.
+        task: "$test_kit.auth.probe_task"
+        task_default: list_creatives
+        doc_ref: "/protocol/authentication"
+        comply_scenario: security_basic
+        stateful: false
+        expected: |
+          The initialized session accepts the Basic credential and returns a
+          well-formed successful response.
+
+        sample_request:
+          context:
+            correlation_id: "security_baseline--probe_basic"
+
+        validations:
+          - check: field_present
+            path: "context"
+            description: "Response echoes back the context object"
+          - check: field_value
+            path: "context.correlation_id"
+            value: "security_baseline--probe_basic"
+            description: "Context correlation_id returned unchanged"
+
+      - id: probe_invalid_basic
+        title: "Reject deliberately invalid Basic credentials"
+        narrative: |
+          Send the same protected task with Basic credentials the runner generates
+          per-run from random bytes. A conformant agent rejects this with 401/403.
+          An agent that returns 200 here is ignoring credentials entirely and
+          falsely appeared to pass `probe_basic` - only the pair of (200 with
+          valid Basic, 401/403 with random-invalid Basic) proves the credential is
+          actually checked. The credential is randomized per run so no allowlist
+          can collide with it by accident.
+
+          Contributes `auth_mechanism_verified` only when *both* this step and
+          `probe_basic` succeed.
+        task: "$test_kit.auth.probe_task"
+        task_default: list_creatives
+        doc_ref: "/protocol/authentication"
+        comply_scenario: security_invalid_basic_rejection
+        stateful: false
+        auth:
+          type: basic
+          value_strategy: random_invalid
+        contributes: true
+        contributes_if: "prior_step.probe_basic.passed"
+        expect_error: true
+        negative_path: schema_invalid
+        expected: |
+          The agent rejects the random-invalid Basic credential with:
+          - http_status: 400 (credential format validation failure), 401
+            (preferred), or 403
+          - On 401, a `WWW-Authenticate: Basic ...` header
+
+        sample_request:
+          context:
+            correlation_id: "security_baseline--probe_invalid_basic"
+
+        validations:
+          - check: http_status_in
+            allowed_values: [400, 401, 403]
+            description: "Agent returned 200 on known-bad Basic credentials — credentials are not being validated. MUST reject with 400 (credential-format validation failure), 401 (preferred), or 403"
+          - check: on_401_require_header
+            value: "www-authenticate"
+            description: "401 responses on invalid Basic credentials MUST include WWW-Authenticate (for example, `Basic realm=\"<agent-url>\"`)"
+
   - id: oauth_discovery
     title: "OAuth discovery and audience binding"
     narrative: |
-      **This phase OR `api_key_path` MUST pass — see `mechanism_required`.**
-
-      **Skip for API-key-only agents.** If your agent has no OAuth issuer,
-      declare `auth.api_key` in the test-kit and do not serve PRM. This phase
-      will fail its probes (404 on the well-known path), but failures inside
-      an `optional: true` phase do not fail the storyboard — the api_key path
-      carries `auth_mechanism_verified` on its own. Do NOT serve PRM pointing
-      at a fake issuer to "pass" this phase; that triggers the
+      **This phase OR `api_key_path` OR `basic_path` MUST pass — see
+      `mechanism_required`.**
+
+      **Skip for static-credential-only agents.** If your agent has no OAuth
+      issuer, declare `auth.api_key` or `auth.basic` in the test-kit and do not
+      serve PRM. This phase will fail its probes (404 on the well-known path),
+      but failures inside an `optional: true` phase do not fail the storyboard —
+      the static credential path carries `auth_mechanism_verified` on its own.
+      Do NOT serve
+      PRM pointing at a fake issuer to "pass" this phase; that triggers the
       advertised-but-unserved failure mode below.
 
       OAuth-enabled agents advertise their auth server at the well-known path defined
@@ -406,7 +514,7 @@ phases:
     title: "At least one mechanism must be verified"
     narrative: |
       Logical check — not a network call. The storyboard runner fails this phase
-      if neither `api_key_path` nor `oauth_discovery` contributed
+      if none of `api_key_path`, `basic_path`, or `oauth_discovery` contributed
       `auth_mechanism_verified`. An agent that rejects unauthenticated requests
       but advertises no working auth mechanism cannot actually be called by a
       compliant buyer, so it does not pass the baseline.
@@ -422,10 +530,11 @@ phases:
         stateful: false
         expected: |
           At least one of the API key path (both valid-key and invalid-key steps
-          must succeed) or the OAuth path (correct metadata AND token validation
-          both must succeed) contributed `auth_mechanism_verified`.
+          must succeed), Basic path (both valid-credential and invalid-credential
+          steps must succeed), or OAuth path (correct metadata AND token
+          validation both must succeed) contributed `auth_mechanism_verified`.
 
         validations:
           - check: any_of
             allowed_values: ["auth_mechanism_verified"]
-            description: "No auth mechanism was verified. Three things to check: (1) your test kit declares `auth.probe_task` pointing at a read-only authenticated task your agent supports (defaults to `list_creatives`); (2) you provide `auth.api_key` in your test kit AND the agent both accepts it and rejects a random-invalid key; OR (3) you serve protected-resource metadata at /.well-known/oauth-protected-resource/<path> with `resource` equal to your agent URL."
+            description: "No auth mechanism was verified. Three things to check: (1) your test kit declares `auth.probe_task` pointing at a read-only authenticated task your agent supports (defaults to `list_creatives`); (2) you provide `auth.api_key` or `auth.basic` in your test kit AND the agent accepts it and rejects random-invalid credentials; OR (3) you serve protected-resource metadata at /.well-known/oauth-protected-resource/<path> with `resource` equal to your agent URL."

package/compliance/cache/{3.0.12 → 3.0.18}/universal/storyboard-schema.yaml

@@ -185,8 +185,17 @@
 #     id                 string (short identifier)
 #     auth.api_key       string (`demo-<kit>-v1` pattern; the demo Bearer the
 #                        runner sends on positive api-key probes)
+#       OR
+#     auth.basic         object (the demo HTTP Basic credential the runner sends
+#                        on positive Basic probes). Shape is either:
+#                          username: string
+#                          password: string
+#                        or:
+#                          credentials: string
+#                        where `credentials` is the unencoded `username:password`
+#                        pair used to build the Authorization header.
 #     auth.probe_task    string (the protected read the runner calls under
-#                        `auth: none` and with a random-invalid key)
+#                        `auth: none` and with random-invalid credentials)
 #     brand              object (house + brand_id + names + logos + colors +
 #                        fonts + tone — full brand.json payload)
 #     + optional products, creatives, pricing_options, destinations, etc.
@@ -214,9 +223,10 @@
 #   "no credentials" property is temporal, not structural.
 #
 # Enforcement. `scripts/lint-storyboard-test-kits.cjs` fails the build if a
-# kit under `test-kits/` declares neither `auth.api_key` nor `applies_to` —
-# that's the bimodal partition this section describes. The lint tolerates
-# kits that declare both (the future-branded-runner case above).
+# kit under `test-kits/` declares none of `auth.api_key`, `auth.basic`, or
+# `applies_to` — that's the bimodal partition this section describes. The lint
+# tolerates kits that declare both a credential marker and `applies_to` (the
+# future-branded-runner case above).
 #
 # Composition. Storyboards that need BOTH a brand identity AND a harness
 # contract declare the brand kit in `prerequisites.test_kit` and opt into the
@@ -238,9 +248,9 @@
 # docs).
 #
 # `test_kit=<path>` in the contradiction-lint fingerprint disambiguates the
-# two flavors — `auth=kit_default` resolves to the kit's api_key for brand
-# kits and to no-credential for runner contracts, but the two never collide
-# because the `test_kit=` component separates them.
+# two flavors — `auth=kit_default` resolves to the kit's static credential for
+# brand kits and to no-credential for runner contracts, but the two never
+# collide because the `test_kit=` component separates them.
 #
 # Future: if a storyboard ever needs to compose TWO runner contracts
 # simultaneously (e.g., signed-requests + substitution-observer), the step-
@@ -294,6 +304,10 @@
 #   auth: { type: api_key, value_strategy: random_invalid }
 #                                                         → use a per-run random bogus API key (for invalid-key probes).
 #                                                           Runner generates `invalid-<32 random bytes>` per run.
+#   auth: { type: basic, from_test_kit: "auth.basic" }   → use the Basic credential at `auth.basic` in the test kit
+#   auth: { type: basic, value_strategy: random_invalid }
+#                                                         → use a per-run random bogus Basic credential (for invalid-Basic probes).
+#                                                           Runner generates random username/password bytes per run.
 #   auth: { type: oauth_bearer, value_strategy: random_invalid_jwt }
 #                                                         → use a per-run random JWT-shaped bogus Bearer token.
 #                                                           Runner generates `<base64url random>.<base64url random>.<base64url random>` per run.
@@ -315,12 +329,14 @@
 #                         that a later assert_contribution step can require)
 # contributes: boolean (optional — shorthand for `contributes_to: <enclosing phase's branch_set.id>`
 #                       introduced alongside first-class `branch_set:` declarations.
-#                       Legal only inside a phase that declares `branch_set:`; the runner's
-#                       loader resolves `contributes: true` to the phase's branch_set.id
-#                       and raises a storyboard-load error on `contributes: true` outside
+#                       Legal only inside a phase that declares `branch_set:`; current
+#                       SDK runners resolve `contributes: true` to the phase's branch_set.id
+#                       and raise a storyboard-load error on `contributes: true` outside
 #                       a branch_set phase or on a step that also declares `contributes_to`.
-#                       See adcp-client#693 and `lint:storyboard-branch-sets` for the
-#                       full rule set.)
+#                       Use explicit `contributes_to` when a storyboard must remain
+#                       compatible with older runners that grade before loader
+#                       normalization. See adcp-client#693 and
+#                       `lint:storyboard-branch-sets` for the full rule set.)
 # contributes_if: string (optional — runner-evaluated expression gating the contribution)
 #   Supported grammar (single form; not a general-purpose DSL):
 #     "prior_step.<step_id>.passed"   → true if the named prior step in the same storyboard passed
@@ -537,10 +553,11 @@
 #   `@adcp/client` 5.8.0+ also accepts the boolean shorthand
 #   `contributes: true` on a step inside a branch_set phase — the runner's
 #   loader resolves it to the enclosing phase's `branch_set.id`. The two
-#   forms are semantically identical; `contributes: true` is preferred
-#   inside a branch_set phase because it eliminates the typo surface (the
-#   string form must equal `branch_set.id` exactly). Authors may use
-#   either; the lint enforces both.
+#   forms are semantically identical in current SDK runners. Use explicit
+#   `contributes_to: <branch_set.id>` for storyboards that need to run against
+#   older graders that may inspect the field before loader normalization;
+#   use `contributes: true` only when the target runner line is known to
+#   support shorthand normalization. The lint enforces both forms.
 #
 #   New storyboards MUST declare branch-set membership with a `branch_set:`
 #   object. The implicit-detection fallback below exists only so pre-#2633
@@ -556,11 +573,13 @@
 #   Per-step contribution signalling is REQUIRED on each contributing step —
 #   the phase-level `branch_set:` declares membership but does not replace
 #   the step-level flag. Runners accumulate contributions at the step level.
-#   Two equivalent forms:
-#     - `contributes: true` (preferred inside a branch_set phase; resolves
-#       to the enclosing phase's `branch_set.id`)
-#     - `contributes_to: <branch_set.id>` (string form; required outside a
-#       branch_set phase and must equal `branch_set.id` inside one)
+#   Two equivalent forms in current SDK runners:
+#     - `contributes_to: <branch_set.id>` (compatibility-safe string form;
+#       required outside a branch_set phase and must equal `branch_set.id`
+#       inside one)
+#     - `contributes: true` (shorthand inside a branch_set phase; resolves
+#       to the enclosing phase's `branch_set.id` on runners that support
+#       shorthand normalization)
 #
 #   Authoring rules (enforced by `lint:storyboard-branch-sets`):
 #     - A phase with `branch_set:` MUST set `optional: true`. A
@@ -924,8 +943,9 @@
 # for the reference contract (endpoint modes, retry-replay shape, client-primitive
 # hooks). Storyboard authors MUST declare the contract in prerequisites; the
 # webhook-emission universal (universal/webhook-emission.yaml) is the reference
-# consumer, and universal/idempotency.yaml uses it for the "no duplicate webhooks
-# on replay" assertion.
+# consumer, including idempotency replay side-effect assertions that need
+# webhook observation. Keep those assertions on webhook-specific storyboards so
+# core idempotency requests do not depend on runner-only URL templating.
 #
 # --- Substitution variables (webhook-receiver enabled) ---
 #