feat: promote 4 protocol storyboards to canonical definitions

.changeset/deep-baboons-build.md

@@ -0,0 +1,2 @@
+---
+---

docs/storyboards/behavioral_analysis.yaml

@@ -0,0 +1,212 @@
+id: behavioral_analysis
+version: "1.0.0"
+title: "Behavioral analysis"
+category: behavioral_analysis
+summary: "Validates product discovery behavior: brief filtering, response consistency, and pricing edge cases."
+track: products
+required_tools:
+  - get_products
+platform_types:
+  - display_ad_server
+  - video_ad_server
+  - social_platform
+  - retail_media
+  - search_platform
+  - audio_platform
+  - dsp
+  - pmax_platform
+  - ai_ad_network
+  - ai_platform
+  - generative_dsp
+
+narrative: |
+  You expose a get_products task that accepts natural-language briefs and returns structured
+  product listings with pricing, delivery forecasts, and targeting. This storyboard verifies
+  three properties of that task:
+
+  1. Behavior analysis — do results change when the brief changes? Does the agent filter
+     products by brief content or return a static catalog?
+  2. Response consistency — given the same brief twice, does the agent return the same
+     product IDs? Deterministic responses are expected for identical inputs.
+  3. Pricing edge cases — do products declare valid pricing_options structures with
+     recognized delivery_type values (guaranteed or non_guaranteed)?
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - accepts_briefs
+  examples:
+    - "Yahoo"
+    - "Retail media networks"
+    - "Publisher platforms"
+
+caller:
+  role: buyer_agent
+  example: "Scope3 (DSP)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity for product discovery requests.
+    The test kit provides a sample brand (Acme Outdoor) with campaign parameters.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: behavior_analysis
+    title: "Brief filtering behavior"
+    narrative: |
+      Tests whether the agent filters products based on the brief content. Two different
+      briefs are sent — one narrow (podcast audio only) and one broad (all products across
+      all channels). If the agent interprets briefs, the narrow brief should return fewer
+      products than the broad brief.
+
+    steps:
+      - id: get_products_narrow
+        title: "Get products with narrow brief"
+        narrative: |
+          Send a narrow brief requesting only podcast audio advertising. Capture the
+          returned product IDs so they can be compared with a broader request.
+        task: get_products
+        schema_ref: "media-buy/get-products-request.json"
+        response_schema_ref: "media-buy/get-products-response.json"
+        doc_ref: "/media-buy/task-reference/get_products"
+        comply_scenario: behavior_analysis
+        stateful: false
+        expected: |
+          Return products matching the narrow brief. If the agent interprets briefs,
+          this should return fewer products than a broad request.
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "Podcast audio advertising only — 30-second pre-roll spots"
+          brand:
+            domain: "acmeoutdoor.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "products"
+            description: "Response contains a products array"
+
+      - id: get_products_broad
+        title: "Get products with broad brief"
+        narrative: |
+          Send a broad brief requesting all available products. Compare the result count
+          with the narrow brief — if the agent filters by brief, the broad request should
+          return more products.
+        task: get_products
+        schema_ref: "media-buy/get-products-request.json"
+        response_schema_ref: "media-buy/get-products-response.json"
+        doc_ref: "/media-buy/task-reference/get_products"
+        comply_scenario: behavior_analysis
+        stateful: false
+        expected: |
+          Return all available products. The product count should be greater than or
+          equal to the narrow brief response.
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "Show me everything — all channels, all formats, all inventory"
+          brand:
+            domain: "acmeoutdoor.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+
+  - id: response_consistency
+    title: "Response consistency"
+    narrative: |
+      Tests whether the agent returns deterministic results for identical inputs.
+      The same brief is sent twice — the response should contain the same product IDs
+      in both cases.
+
+    steps:
+      - id: get_products_first
+        title: "First request with identical brief"
+        narrative: |
+          Send a brief and capture the product IDs returned.
+        task: get_products
+        schema_ref: "media-buy/get-products-request.json"
+        response_schema_ref: "media-buy/get-products-response.json"
+        doc_ref: "/media-buy/task-reference/get_products"
+        comply_scenario: response_consistency
+        stateful: false
+        expected: |
+          Return products matching the brief. Product IDs will be compared with a
+          subsequent identical request.
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "Premium video inventory on sports publishers. Adults 25-54."
+          brand:
+            domain: "acmeoutdoor.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+
+      - id: get_products_second
+        title: "Second request with identical brief"
+        narrative: |
+          Send the exact same brief again. The returned product IDs should match the
+          first response.
+        task: get_products
+        schema_ref: "media-buy/get-products-request.json"
+        response_schema_ref: "media-buy/get-products-response.json"
+        doc_ref: "/media-buy/task-reference/get_products"
+        comply_scenario: response_consistency
+        stateful: false
+        expected: |
+          Return the same product IDs as the first request. Deterministic responses
+          are expected for identical inputs.
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "Premium video inventory on sports publishers. Adults 25-54."
+          brand:
+            domain: "acmeoutdoor.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+
+  - id: pricing_edge_cases
+    title: "Pricing structure validation"
+    narrative: |
+      Validates that products declare well-formed pricing_options with recognized
+      delivery_type values and complete pricing structures.
+
+    steps:
+      - id: get_products_pricing
+        title: "Validate pricing structures"
+        narrative: |
+          Send a brief and inspect the pricing structures on returned products.
+          Every product must have a recognized delivery_type and valid pricing_options.
+        task: get_products
+        schema_ref: "media-buy/get-products-request.json"
+        response_schema_ref: "media-buy/get-products-response.json"
+        doc_ref: "/media-buy/task-reference/get_products"
+        comply_scenario: pricing_edge_cases
+        stateful: false
+        expected: |
+          Products with valid pricing structures:
+          - delivery_type: "guaranteed" or "non_guaranteed"
+          - pricing_options with pricing_option_id and pricing_model
+
+        sample_request:
+          buying_mode: "brief"
+          brief: "All available products with detailed pricing"
+          brand:
+            domain: "acmeoutdoor.com"
+
+        validations:
+          - check: response_schema
+            description: "Response matches get-products-response.json schema"
+          - check: field_present
+            path: "products[0].delivery_type"
+            description: "Products declare delivery_type"
+          - check: field_present
+            path: "products[0].pricing_options"
+            description: "Products include pricing_options"

docs/storyboards/brand_rights.yaml

@@ -3,6 +3,9 @@ version: "1.0.0"
 title: "Brand identity and rights licensing"
 category: brand_rights
 summary: "Brand agent that serves identity assets and licenses rights for AI-generated content."
+track: core
+required_tools:
+  - get_brand_identity
 
 narrative: |
   You run a brand agent — a system that holds brand identity data (logos, colors, fonts,

docs/storyboards/campaign_governance_conditions.yaml

@@ -3,6 +3,10 @@ version: "1.0.0"
 title: "Campaign governance — conditional approval"
 category: campaign_governance_conditions
 summary: "Governance agent approves a media buy with conditions. Buyer re-checks after meeting the conditions."
+track: campaign_governance
+required_tools:
+  - sync_plans
+  - check_governance
 
 narrative: |
   The buyer's governance agent evaluates a media buy that falls within spending authority but

docs/storyboards/campaign_governance_delivery.yaml

@@ -3,6 +3,9 @@ version: "1.0.0"
 title: "Campaign governance — delivery monitoring with drift detection"
 category: campaign_governance_delivery
 summary: "Governance agent monitors delivery, detects budget drift past thresholds, and triggers re-evaluation."
+track: campaign_governance
+required_tools:
+  - check_governance
 
 narrative: |
   After a media buy is confirmed with governance approval, the governance agent monitors

docs/storyboards/campaign_governance_denied.yaml

@@ -3,6 +3,10 @@ version: "1.0.0"
 title: "Campaign governance — denied"
 category: campaign_governance_denied
 summary: "Governance agent denies a media buy that exceeds the agent's spending authority. No human escalation — the buy is blocked."
+track: campaign_governance
+required_tools:
+  - sync_plans
+  - check_governance
 
 narrative: |
   The buyer's governance agent registers a plan with strict spending authority. The buyer

docs/storyboards/capability_discovery.yaml

@@ -3,6 +3,7 @@ version: "1.0.0"
 title: "Capability discovery"
 category: capability_discovery
 summary: "Buyer calls get_adcp_capabilities to discover what an agent supports before making any buying or creative decisions."
+track: core
 
 narrative: |
   Before doing anything else, a buyer agent calls get_adcp_capabilities to learn what your

docs/storyboards/content_standards.yaml

@@ -3,6 +3,9 @@ version: "1.0.0"
 title: "Content standards"
 category: content_standards
 summary: "Define creative quality rules, calibrate content against them, and validate that delivered ads met the standards."
+track: governance
+required_tools:
+  - list_content_standards
 
 narrative: |
   You run a governance agent that manages content standards — rules that define what

docs/storyboards/creative_ad_server.yaml

@@ -3,6 +3,9 @@ version: "1.1.0"
 title: "Creative ad server"
 category: creative_ad_server
 summary: "Stateful ad server with pre-loaded creatives. Generates serving tags per media buy with pricing and billing."
+track: creative
+required_tools:
+  - build_creative
 
 narrative: |
   You run a creative ad server — think Innovid, Flashtalking, or CM360. Your clients

docs/storyboards/creative_lifecycle.yaml

@@ -3,6 +3,9 @@ version: "1.0.0"
 title: "Creative lifecycle"
 category: creative_lifecycle
 summary: "Full creative lifecycle on a stateful platform: sync multiple creatives, list with filtering, build and preview across formats, observe status transitions."
+track: creative
+required_tools:
+  - list_creative_formats
 
 narrative: |
   You run a creative platform with a persistent library — an ad server, creative management

docs/storyboards/creative_sales_agent.yaml

@@ -3,6 +3,9 @@ version: "1.0.0"
 title: "Sales agent with creative capabilities"
 category: creative_sales_agent
 summary: "Stateful sales agent that accepts pushed creative assets and renders them in its environment."
+track: creative
+required_tools:
+  - sync_creatives
 
 narrative: |
   You run a publisher platform, retail media network, or other sell-side system that

docs/storyboards/creative_template.yaml

@@ -3,6 +3,9 @@ version: "1.0.0"
 title: "Creative template and transformation agent"
 category: creative_template
 summary: "Stateless creative agent that takes assets in, applies templates, and produces tags or rendered output."
+track: creative
+required_tools:
+  - build_creative
 
 narrative: |
   You build a creative management or rich media platform — think Celtra, a format