@adcp/client 4.22.0 → 4.23.0

package/storyboards/brand_rights.yaml

@@ -1,131 +1,228 @@
 id: brand_rights
 version: "1.0.0"
-title: "Brand rights flow"
+title: "Brand identity and rights licensing"
 category: brand_rights
-summary: "Agent that provides brand identity, queries rights, and supports rights acquisition."
+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 rights platform — a system that manages brand identity information,
-  tracks rights associated with brands, and facilitates rights acquisition. A caller
-  connects to retrieve brand identity details, query existing rights, and initiate
-  new rights acquisitions.
+  You run a brand agent — a system that holds brand identity data (logos, colors, fonts,
+  tone of voice) and licenses rights for AI-generated content. A buyer agent connects to
+  discover your brand identity, browse available rights, acquire licenses, manage them over
+  time, and submit generated creatives for brand approval.
 
-  The caller starts by fetching the brand identity for a given domain. Then they
-  query what rights are currently associated with that brand. Finally, they request
-  acquisition of additional rights, optionally in dry_run mode to preview without
-  committing.
+  Brand agents are the bridge between brand owners and generative AI. When a DSP or
+  creative platform wants to generate an ad for your brand, they call your brand agent
+  to get the identity guidelines, license the right to generate content, and then submit
+  the result for approval before it goes live.
 
-  This storyboard walks through the complete brand rights flow from discovery
-  through acquisition.
+  This storyboard covers the full brand rights lifecycle: discovering the brand, browsing
+  rights, acquiring a license, managing it, and approving generated content.
 
 agent:
-  interaction_model: brand_rights
+  interaction_model: brand_rights_holder
   capabilities:
     - brand_identity
-    - rights_management
+    - rights_licensing
   examples:
-    - "Brand registry platforms"
-    - "Rights management systems"
-    - "Brand safety and compliance platforms"
+    - "Rights management platforms"
+    - "Talent agencies"
+    - "Brand licensing services"
+    - "Enterprise brand portals"
 
 caller:
   role: buyer_agent
-  example: "Agency brand compliance tool"
+  example: "Pinnacle Agency (creative buyer)"
 
 prerequisites:
   description: |
-    The caller needs a brand domain to query. The test uses example.com as a
-    default domain suitable for validating the brand rights protocol flow.
+    The caller needs brand context for identity discovery and campaign parameters for
+    rights acquisition. The test kit provides a sample brand with visual identity assets.
+  test_kit: "test-kits/acme-outdoor.yaml"
 
 phases:
-  - id: brand_rights_flow
-    title: "Brand rights flow"
+  - id: identity_discovery
+    title: "Brand identity discovery"
     narrative: |
-      The caller retrieves brand identity, queries existing rights, and initiates
-      rights acquisition. Each step builds on the previous: the brand identity
-      confirms the brand exists, the rights query shows what is already held,
-      and the acquisition request adds new rights.
+      The buyer retrieves the brand's public identity — logos, colors, fonts, tone of
+      voice, and visual guidelines. This is the foundation for any generative content:
+      the buyer needs to know what the brand looks like and sounds like before generating
+      anything.
 
     steps:
       - id: get_brand_identity
         title: "Retrieve brand identity"
         narrative: |
-          The caller requests brand identity information for a specific domain.
-          The agent returns the brand name, domain, and any associated guidelines
-          or metadata. This confirms the brand is known to the platform.
+          The buyer calls get_brand_identity to retrieve the brand's visual and verbal
+          identity. Public-tier access returns basic assets. Authorized access (after
+          account linking) provides high-resolution assets, voice configs, and detailed
+          tone guidelines.
         task: get_brand_identity
+        schema_ref: "brand/get-brand-identity-request.json"
+        response_schema_ref: "brand/get-brand-identity-response.json"
+        doc_ref: "/brand-protocol/tasks/get_brand_identity"
         stateful: false
         expected: |
-          Return the brand identity:
-          - request_id: echoes the caller's request_id
-          - brand_name: human-readable brand name
-          - brand_domain: the queried domain
-          - guidelines: brand usage guidelines (optional)
+          Return brand identity data:
+          - Logos at multiple resolutions
+          - Brand colors (primary, secondary, accent)
+          - Typography (fonts, weights, sizes)
+          - Tone of voice guidelines
+          - Visual style guidelines
 
         sample_request:
-          type: "get_brand_identity_request"
-          request_id: "e2e-brand-id-001"
-          brand_domain: "example.com"
+          brand:
+            domain: "acmeoutdoor.com"
 
         validations:
-          - check: field_present
-            path: "brand_name"
-            description: "Response includes the brand name"
-          - check: field_present
-            path: "brand_domain"
-            description: "Response includes the brand domain"
+          - check: response_schema
+            description: "Response matches get-brand-identity-response.json schema"
 
+  - id: rights_search
+    title: "Browse available rights"
+    narrative: |
+      The buyer discovers what rights are available for licensing. Rights define what
+      generative content can be created — image generation, video synthesis, voice
+      cloning, copy writing — and at what terms.
+
+    steps:
       - id: get_rights
-        title: "Query current brand rights"
-        requires_tool: get_rights
+        title: "Discover available rights"
         narrative: |
-          The caller queries what rights are currently associated with the brand.
-          The agent returns a list of rights with their types, scopes, and
-          expiration dates.
+          The buyer calls get_rights to see what content generation rights the brand
+          offers. Each right specifies the type of content, pricing, duration, and
+          any constraints (impression caps, geo restrictions, etc.).
         task: get_rights
+        schema_ref: "brand/get-rights-request.json"
+        response_schema_ref: "brand/get-rights-response.json"
+        doc_ref: "/brand-protocol/tasks/get_rights"
         stateful: false
         expected: |
-          Return the current rights:
-          - request_id: echoes the caller's request_id
-          - rights: array of right objects, each with type, scope, and optional expires_at
+          Return available rights with pricing:
+          - Right types (image_generation, video_synthesis, copy_writing, etc.)
+          - Pricing options per right
+          - Duration and renewal terms
+          - Usage constraints (impression caps, geo restrictions)
 
         sample_request:
-          type: "get_rights_request"
-          request_id: "e2e-rights-001"
-          brand_domain: "example.com"
+          brand:
+            domain: "acmeoutdoor.com"
 
         validations:
-          - check: field_present
-            path: "rights"
-            description: "Response includes a rights array"
+          - check: response_schema
+            description: "Response matches get-rights-response.json schema"
 
+  - id: rights_acquisition
+    title: "Acquire a rights license"
+    narrative: |
+      The buyer selects a right and acquires a license. This is the contractual commitment —
+      the buyer pays for the right to generate content of a specific type for a defined
+      period. The brand agent issues generation credentials.
+
+    steps:
       - id: acquire_rights
-        title: "Acquire brand rights"
-        requires_tool: acquire_rights
+        title: "Purchase a rights license"
         narrative: |
-          The caller initiates acquisition of brand rights. The dry_run flag
-          allows previewing the acquisition without committing. The agent
-          returns the acquisition status and a rights_id for tracking.
+          The buyer acquires a specific right by selecting a pricing option and providing
+          campaign context. The brand agent validates the request, processes payment,
+          and returns a rights grant with generation credentials.
         task: acquire_rights
+        schema_ref: "brand/acquire-rights-request.json"
+        response_schema_ref: "brand/acquire-rights-response.json"
+        doc_ref: "/brand-protocol/tasks/acquire_rights"
+        stateful: true
+        expected: |
+          Return the acquired rights grant:
+          - rights_grant_id: unique identifier
+          - status: active
+          - Generation credentials
+          - Expiration date and usage limits
+          - Terms and constraints
+
+        sample_request:
+          brand:
+            domain: "acmeoutdoor.com"
+          right_type: "image_generation"
+          pricing_option_id: "standard_monthly"
+          campaign:
+            name: "Acme Outdoor Summer 2026"
+            start_date: "2026-04-01"
+            end_date: "2026-06-30"
+
+        validations:
+          - check: response_schema
+            description: "Response matches acquire-rights-response.json schema"
+
+  - id: rights_management
+    title: "Manage rights"
+    narrative: |
+      The buyer modifies an existing rights grant — extending the end date, adjusting
+      impression caps, or pausing generation while keeping the license active.
+
+    steps:
+      - id: update_rights
+        title: "Modify an existing rights grant"
+        narrative: |
+          The buyer updates an active rights grant. Changes may include extending the
+          duration, increasing impression caps, or pausing/resuming generation. The
+          brand agent re-issues credentials if necessary.
+        task: update_rights
+        schema_ref: "brand/update-rights-request.json"
+        response_schema_ref: "brand/update-rights-response.json"
+        doc_ref: "/brand-protocol/tasks/update_rights"
+        stateful: true
+        expected: |
+          Return the updated rights grant:
+          - Updated expiration or caps
+          - New generation credentials if changed
+          - Status confirmation
+
+        sample_request:
+          rights_grant_id: "rg_acme_summer_2026"
+          updates:
+            end_date: "2026-09-30"
+            impression_cap: 5000000
+
+        validations:
+          - check: response_schema
+            description: "Response matches update-rights-response.json schema"
+
+  - id: creative_approval
+    title: "Creative approval"
+    narrative: |
+      After generating content using the licensed rights, the buyer submits the creative
+      for brand approval. The brand agent reviews the generated content against brand
+      guidelines and either approves, requests changes, or rejects it.
+
+    steps:
+      - id: creative_approval
+        title: "Submit generated creative for brand approval"
+        narrative: |
+          The buyer submits a generated creative for the brand's review. The brand agent
+          evaluates it against identity guidelines, tone of voice, and any contractual
+          constraints from the rights grant.
+        task: creative_approval
+        schema_ref: "brand/creative-approval-request.json"
+        response_schema_ref: "brand/creative-approval-response.json"
+        doc_ref: "/brand-protocol/walkthrough-rights-licensing"
         stateful: true
         expected: |
-          Return the acquisition result:
-          - request_id: echoes the caller's request_id
-          - status: granted, pending, denied, or dry_run
-          - rights_id: identifier for the acquired or pending rights
-          - dry_run: true when the request was a preview
+          Return an approval decision:
+          - decision: approved, changes_requested, or rejected
+          - Feedback on brand compliance
+          - Specific issues if changes requested or rejected
 
         sample_request:
-          type: "acquire_rights_request"
-          request_id: "e2e-acquire-001"
-          brand_domain: "example.com"
-          rights_type: "usage"
-          dry_run: true
+          rights_grant_id: "rg_acme_summer_2026"
+          creative:
+            creative_id: "gen_trail_pro_display"
+            format: "display_300x250"
+            assets:
+              - asset_type: "image"
+                url: "https://cdn.pinnacle-agency.example/gen-trail-pro-300x250.png"
 
         validations:
-          - check: field_present
-            path: "status"
-            description: "Response includes acquisition status"
+          - check: response_schema
+            description: "Response matches creative-approval-response.json schema"

package/storyboards/campaign_governance_conditions.yaml

@@ -0,0 +1,187 @@
+id: campaign_governance_conditions
+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
+  triggers policy conditions — for example, the buy targets a channel that requires weekly
+  reporting, or the creative format requires brand safety review.
+
+  The governance agent returns approved_with_conditions, attaching conditions the buyer must
+  honor during the campaign. The buyer can proceed with the media buy by passing the
+  governance context, but the conditions are binding.
+
+  This storyboard tests the middle path between outright approval and denial: the buy is
+  allowed, but with strings attached.
+
+agent:
+  interaction_model: media_buy_seller
+  capabilities:
+    - sells_media
+    - governance_aware
+  examples:
+    - "Publisher platform with governance support"
+    - "SSP that respects governance checks"
+
+caller:
+  role: buyer_agent
+  example: "Pinnacle Agency (buyer)"
+
+prerequisites:
+  description: |
+    The caller needs a brand identity, operator credentials, and a governance agent URL.
+    The governance plan defines policy conditions that trigger on specific buy parameters.
+  test_kit: "test-kits/acme-outdoor.yaml"
+
+phases:
+  - id: plan_registration
+    title: "Register governance plan with policy conditions"
+    narrative: |
+      The buyer registers a governance plan that allows the agent full spending authority
+      but attaches policy conditions for specific channels or formats. Buys that trigger
+      these policies are approved with conditions rather than denied.
+
+    steps:
+      - id: sync_plans
+        title: "Register a governance plan with policy conditions"
+        narrative: |
+          The buyer's governance agent registers a plan with full spending authority but
+          custom policies that require weekly reporting for CTV buys and brand safety
+          review for user-generated content placements.
+        task: sync_plans
+        schema_ref: "governance/sync-plans-request.json"
+        response_schema_ref: "governance/sync-plans-response.json"
+        doc_ref: "/governance/campaign/tasks/sync_plans"
+        comply_scenario: campaign_governance_conditions
+        stateful: true
+        expected: |
+          Acknowledge the governance plan:
+          - plan_id: identifier for this governance plan
+          - authority_level: agent_full
+          - custom_policies: policy conditions registered
+
+        sample_request:
+          plans:
+            - plan_name: "Acme Outdoor conditional governance"
+              brand:
+                domain: "acmeoutdoor.com"
+              operator: "pinnacle-agency.com"
+              authority_level: "agent_full"
+              custom_policies:
+                - "CTV buys require weekly delivery reporting"
+                - "UGC placements require brand safety review before go-live"
+
+        validations:
+          - check: response_schema
+            description: "Response matches sync-plans-response.json schema"
+
+  - id: governance_check_conditions
+    title: "Governance check — approved with conditions"
+    narrative: |
+      The buyer proposes a media buy that includes CTV inventory. The governance agent
+      approves the buy but attaches the weekly reporting condition from the plan. The
+      buyer receives a governance context that encodes these conditions.
+
+    steps:
+      - id: check_governance_conditions
+        title: "Pre-buy governance check (approved with conditions)"
+        narrative: |
+          The buyer calls check_governance with a media buy that includes CTV products.
+          The governance agent approves the buy but attaches conditions: weekly delivery
+          reporting is required for the CTV line items.
+        task: check_governance
+        schema_ref: "governance/check-governance-request.json"
+        response_schema_ref: "governance/check-governance-response.json"
+        doc_ref: "/governance/campaign/tasks/check_governance"
+        comply_scenario: campaign_governance_conditions
+        stateful: true
+        expected: |
+          Return an approved governance decision with conditions:
+          - decision: approved
+          - conditions: array of requirements the buyer must honor
+            - e.g., "Weekly delivery reporting required for CTV line items"
+          - governance_context: token the buyer passes to create_media_buy
+          - findings: may include should-severity findings noting the conditions
+
+        sample_request:
+          plan_id: "gov_acme_conditional"
+          binding:
+            type: "media_buy"
+            account:
+              brand:
+                domain: "acmeoutdoor.com"
+              operator: "pinnacle-agency.com"
+            total_budget: 40000
+            packages:
+              - product_id: "sports_ctv_q2"
+                budget: 25000
+              - product_id: "lifestyle_display_q2"
+                budget: 15000
+
+        validations:
+          - check: response_schema
+            description: "Response matches check-governance-response.json schema"
+          - check: field_present
+            path: "decision"
+            description: "Response contains a governance decision"
+          - check: field_present
+            path: "conditions"
+            description: "Approval includes conditions"
+          - check: field_present
+            path: "governance_context"
+            description: "Response includes governance context for the media buy"
+
+  - id: create_buy_with_conditions
+    title: "Create media buy with governance conditions"
+    narrative: |
+      The buyer creates the media buy, passing the governance context from the conditional
+      approval. The seller validates the governance approval and confirms the buy. The
+      conditions from the governance check are now binding for the campaign duration.
+
+    steps:
+      - id: create_media_buy
+        title: "Create a media buy with conditional governance approval"
+        narrative: |
+          The buyer creates the media buy with the governance_context token from the
+          conditional approval. The seller confirms the buy. The buyer is now bound by
+          the conditions (weekly reporting for CTV line items).
+        task: 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: campaign_governance_conditions
+        stateful: true
+        expected: |
+          Confirm the media buy with governance approval:
+          - media_buy_id: your platform's identifier
+          - status: confirmed or active
+          - governance_context: echoed back confirming governance was validated
+          - packages: confirmed line items
+
+        sample_request:
+          account:
+            brand:
+              domain: "acmeoutdoor.com"
+            operator: "pinnacle-agency.com"
+          brand:
+            domain: "acmeoutdoor.com"
+          governance_context: "gov_ctx_acme_conditional_approved"
+          start_time: "2026-04-01T00:00:00Z"
+          end_time: "2026-06-30T23:59:59Z"
+          packages:
+            - product_id: "sports_ctv_q2"
+              budget: 25000
+              pricing_option_id: "cpm_guaranteed"
+            - product_id: "lifestyle_display_q2"
+              budget: 15000
+              pricing_option_id: "cpm_standard"
+
+        validations:
+          - check: response_schema
+            description: "Response matches create-media-buy-response.json schema"