@adcp/client 4.21.0 → 4.22.1

package/docs/llms.txt

@@ -0,0 +1,634 @@
+# Ad Context Protocol (AdCP)
+
+> Generated at: 2026-04-08
+> Library: @adcp/client v4.20.0
+> AdCP major version: 3
+> Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt
+
+## What is AdCP
+
+AdCP is an open protocol for AI agents to buy, manage, and optimize advertising programmatically. It defines MCP tools that agents call on publisher ad servers — discover inventory, create media buys, sync creatives, manage brand safety, and track delivery. Every tool follows request/response JSON schemas; the TypeScript client wraps them with async task handling, conversation context, and governance middleware.
+
+## Are you building a client or a server?
+
+- **Client** (calling existing agents): Continue reading — the Quick Start below is for you.
+- **Server** (implementing an agent that others call): Read `docs/guides/BUILD-AN-AGENT.md` instead. Minimal example:
+
+```typescript
+import { createTaskCapableServer, taskToolResponse, serve, GetSignalsRequestSchema } from '@adcp/client';
+
+function createAgent({ taskStore }) {
+  const server = createTaskCapableServer('My Agent', '1.0.0', { taskStore });
+  server.tool('get_signals', 'Discover segments.', GetSignalsRequestSchema.shape, async (args) => {
+    return taskToolResponse({ signals: [...], sandbox: true }, 'Found segments');
+  });
+  return server;
+}
+
+serve(createAgent); // http://localhost:3001/mcp
+```
+
+## Quick Start (Client)
+
+```typescript
+import { ADCPMultiAgentClient } from '@adcp/client';
+
+const client = ADCPMultiAgentClient.simple('https://agent.example.com/mcp/', {
+  authToken: process.env.ADCP_TOKEN,
+});
+const agent = client.agent('default-agent');
+
+// Discover products
+const products = await agent.getProducts({ buying_mode: 'brief', brief: 'coffee brands' });
+if (products.status === 'completed') console.log(products.data.products);
+
+// Create a media buy
+const buy = await agent.createMediaBuy({
+  account: { account_id: 'acct_1' },
+  brand: { domain: 'coffee.example.com' },
+  start_time: 'asap',
+  end_time: '2026-06-01T00:00:00Z',
+  packages: [{ buyer_ref: 'pkg-1', product_id: 'prod_1', pricing_option_id: 'cpm_1', budget: 5000 }],
+});
+```
+
+## Tools
+
+Every tool is an MCP tool called via `agent.<methodName>(params)`. Returns `TaskResult<T>` with `status`, `data`, `error`, `deferred`, or `submitted`.
+
+### Protocol
+
+#### `get_adcp_capabilities`
+
+Request parameters for cross-protocol capability discovery.
+
+Optional: `protocols: string[]`, `context: Context`
+
+### Account Management
+
+#### `list_accounts`
+
+Request parameters for listing accounts accessible to the authenticated agent.
+
+Optional: `status: 'active' | 'pending_approval' | 'rejected' | 'payment_required' | 'suspended' | 'closed'`, `pagination: Pagination Request`, `sandbox: boolean`, `context: Context`
+
+#### `sync_accounts`
+
+Request parameters for syncing advertiser accounts with a seller.
+
+Required: `accounts: object[]`
+Optional: `delete_missing: boolean`, `dry_run: boolean`, `push_notification_config: Push Notification Config`, `context: Context`
+
+#### `sync_governance`
+
+Request parameters for registering governance agent endpoints on accounts.
+
+Required: `accounts: object[]`
+Optional: `context: Context`
+
+#### `report_usage`
+
+Request parameters for reporting vendor service consumption after delivery.
+
+Required: `reporting_period: Datetime Range`, `usage: object[]`
+Optional: `idempotency_key: string`, `context: Context`
+
+#### `get_account_financials`
+
+Request parameters for querying financial status of an operator-billed account.
+
+Required: `account: Account Ref`
+Optional: `period: Date Range`, `context: Context`
+
+**Deep dive:**
+- docs/getting-started.md — authentication and account setup
+
+### Media Buying
+
+#### `get_products`
+
+Request parameters for discovering available advertising products.
+
+Required: `buying_mode: 'brief' | 'wholesale' | 'refine'`
+Optional: `brief: string`, `refine: object[]`, `brand: Brand Ref`, `catalog: Catalog`, `account: Account Ref`, `preferred_delivery_types: object[]`, `filters: Product Filters`, `property_list: Property List Ref`, +5 more
+
+#### `list_creative_formats`
+
+Request parameters for discovering format IDs and creative agents supported by this sales agent.
+
+Optional: `format_ids: object[]`, `asset_types: object[]`, `max_width: integer`, `max_height: integer`, `min_width: integer`, `min_height: integer`, `is_responsive: boolean`, `name_search: string`, +7 more
+
+#### `create_media_buy`
+
+Request parameters for creating a media buy.
+
+Required: `account: Account Ref`, `brand: Brand Ref`, `start_time: Start Timing`, `end_time: string`
+Optional: `idempotency_key: string`, `plan_id: string`, `proposal_id: string`, `total_budget: object`, `packages: object[]`, `advertiser_industry: Advertiser Industry`, `invoice_recipient: Business Entity`, `io_acceptance: object`, +5 more
+
+#### `update_media_buy`
+
+Request parameters for updating campaign and package settings.
+
+Required: `media_buy_id: string`
+Optional: `revision: integer`, `paused: boolean`, `canceled: 'true'`, `cancellation_reason: string`, `start_time: Start Timing`, `end_time: string`, `packages: object[]`, `invoice_recipient: Business Entity`, +5 more
+
+#### `get_media_buys`
+
+Request parameters for retrieving media buy status, creative approvals, and delivery snapshots.
+
+Optional: `account: Account Ref`, `media_buy_ids: string[]`, `status_filter: Media Buy Status | object[]`, `include_snapshot: boolean`, `include_history: integer`, `pagination: Pagination Request`, `context: Context`
+
+#### `get_media_buy_delivery`
+
+Request parameters for retrieving comprehensive delivery metrics.
+
+Optional: `account: Account Ref`, `media_buy_ids: string[]`, `status_filter: Media Buy Status | object[]`, `start_date: string`, `end_date: string`, `include_package_daily_breakdown: boolean`, `attribution_window: object`, `reporting_dimensions: object`, +1 more
+
+#### `provide_performance_feedback`
+
+Request parameters for sharing performance outcomes with publishers.
+
+Required: `media_buy_id: string`, `measurement_period: Datetime Range`, `performance_index: number`
+Optional: `idempotency_key: string`, `package_id: string`, `creative_id: string`, `metric_type: Metric Type`, `feedback_source: Feedback Source`, `context: Context`
+
+#### `sync_event_sources`
+
+Request parameters for configuring event sources on an account.
+
+Required: `account: Account Ref`
+Optional: `event_sources: object[]`, `delete_missing: boolean`, `context: Context`
+
+#### `log_event`
+
+Request parameters for logging conversion or marketing events.
+
+Required: `event_source_id: string`, `events: object[]`
+Optional: `test_event_code: string`, `idempotency_key: string`, `context: Context`
+
+#### `sync_audiences`
+
+Request parameters for managing CRM-based audiences on an account.
+
+Required: `account: Account Ref`
+Optional: `audiences: object[]`, `delete_missing: boolean`, `context: Context`
+
+#### `sync_catalogs`
+
+Request parameters for syncing catalog feeds (products, inventory, stores, promotions, offerings) with approval workflow.
+
+Required: `account: Account Ref`
+Optional: `catalogs: object[]`, `catalog_ids: string[]`, `delete_missing: boolean`, `dry_run: boolean`, `validation_mode: Validation Mode`, `push_notification_config: Push Notification Config`, `context: Context`
+
+**Deep dive:**
+- docs/getting-started.md — installation, auth, basic usage
+- docs/guides/ASYNC-DEVELOPER-GUIDE.md — async task patterns (submitted, deferred, input-required)
+- docs/guides/PUSH-NOTIFICATION-CONFIG.md — webhook setup for delivery reports
+- docs/guides/REAL-WORLD-EXAMPLES.md — end-to-end buying flows
+
+### Creative
+
+#### `build_creative`
+
+Request parameters for AI-powered creative generation.
+
+Optional: `message: string`, `creative_manifest: Creative Manifest`, `creative_id: string`, `concept_id: string`, `media_buy_id: string`, `package_id: string`, `target_format_id: Format Id`, `target_format_ids: object[]`, +10 more
+
+#### `preview_creative`
+
+Request parameters for generating creative previews.
+
+
+#### `list_creative_formats`
+
+Request parameters for discovering creative formats from this creative agent.
+
+Optional: `format_ids: object[]`, `type: 'audio' | 'video' | 'display' | 'dooh'`, `asset_types: string[]`, `max_width: integer`, `max_height: integer`, `min_width: integer`, `min_height: integer`, `is_responsive: boolean`, +8 more
+
+#### `get_creative_delivery`
+
+Request parameters for retrieving creative delivery data with variant-level breakdowns.
+
+Optional: `account: Account Ref`, `media_buy_ids: string[]`, `creative_ids: string[]`, `start_date: string`, `end_date: string`, `max_variants: integer`, `pagination: Pagination Request`, `context: Context`
+
+#### `list_creatives`
+
+Request parameters for querying creative library with filtering and pagination.
+
+Optional: `filters: Creative Filters`, `sort: object`, `pagination: Pagination Request`, `include_assignments: boolean`, `include_snapshot: boolean`, `include_items: boolean`, `include_variables: boolean`, `fields: string[]`, +1 more
+
+#### `sync_creatives`
+
+Request parameters for syncing creative assets with upsert semantics.
+
+Required: `account: Account Ref`, `creatives: object[]`
+Optional: `creative_ids: string[]`, `assignments: object[]`, `idempotency_key: string`, `delete_missing: boolean`, `dry_run: boolean`, `validation_mode: Validation Mode`, `push_notification_config: Push Notification Config`, `context: Context`
+
+**Deep dive:**
+- docs/guides/BUILD-AN-AGENT.md — building a creative agent (server-side)
+- schemas/cache/latest/creative/asset-types/index.json — asset type definitions
+
+### Signals
+
+#### `get_signals`
+
+Request parameters for discovering signals based on description.
+
+Optional: `account: Account Ref`, `signal_spec: string`, `signal_ids: object[]`, `destinations: object[]`, `countries: string[]`, `filters: Signal Filters`, `max_results: integer`, `pagination: Pagination Request`, +1 more
+
+#### `activate_signal`
+
+Request parameters for activating a signal on a specific platform/account.
+
+Required: `signal_agent_segment_id: string`, `destinations: object[]`
+Optional: `action: 'activate' | 'deactivate'`, `pricing_option_id: string`, `account: Account Ref`, `idempotency_key: string`, `context: Context`
+
+**Deep dive:**
+- docs/guides/BUILD-AN-AGENT.md — signals agent example
+
+### Governance
+
+#### `create_property_list`
+
+Request parameters for creating a new property list.
+
+Required: `name: string`
+Optional: `description: string`, `base_properties: object[]`, `filters: Property List Filters`, `brand: Brand Ref`, `idempotency_key: string`, `context: Context`
+
+#### `update_property_list`
+
+Request parameters for updating an existing property list.
+
+Required: `list_id: string`
+Optional: `name: string`, `description: string`, `base_properties: object[]`, `filters: Property List Filters`, `brand: Brand Ref`, `webhook_url: string`, `context: Context`, `idempotency_key: string`
+
+#### `get_property_list`
+
+Request parameters for retrieving a property list with resolved properties.
+
+Required: `list_id: string`
+Optional: `resolve: boolean`, `pagination: object`, `context: Context`
+
+#### `list_property_lists`
+
+Request parameters for listing property lists.
+
+Optional: `principal: string`, `name_contains: string`, `pagination: Pagination Request`, `context: Context`
+
+#### `delete_property_list`
+
+Request parameters for deleting a property list.
+
+Required: `list_id: string`
+Optional: `context: Context`, `idempotency_key: string`
+
+#### `list_content_standards`
+
+Request parameters for listing content standards configurations.
+
+Optional: `channels: object[]`, `languages: string[]`, `countries: string[]`, `pagination: Pagination Request`, `context: Context`
+
+#### `get_content_standards`
+
+Request parameters for retrieving a specific standards configuration.
+
+Required: `standards_id: string`
+Optional: `context: Context`
+
+#### `create_content_standards`
+
+Request parameters for creating a new content standards configuration.
+
+Required: `scope: object`, `policy: string`
+Optional: `registry_policy_ids: string[]`, `calibration_exemplars: object`, `idempotency_key: string`, `context: Context`
+
+#### `update_content_standards`
+
+Request parameters for updating an existing content standards configuration.
+
+Required: `standards_id: string`
+Optional: `scope: object`, `registry_policy_ids: string[]`, `policy: string`, `calibration_exemplars: object`, `context: Context`, `idempotency_key: string`
+
+#### `calibrate_content`
+
+Request parameters for collaborative calibration dialogue.
+
+Required: `standards_id: string`, `artifact: Artifact`
+Optional: `idempotency_key: string`
+
+#### `validate_content_delivery`
+
+Request parameters for batch validating delivery records.
+
+Required: `standards_id: string`, `records: object[]`
+Optional: `feature_ids: string[]`, `include_passed: boolean`, `context: Context`
+
+#### `get_media_buy_artifacts`
+
+Request parameters for retrieving content artifacts from a media buy.
+
+Required: `media_buy_id: string`
+Optional: `account: Account Ref`, `package_ids: string[]`, `failures_only: boolean`, `time_range: object`, `pagination: object`, `context: Context`
+
+#### `get_creative_features`
+
+Request parameters for evaluating creative features from a governance agent.
+
+Required: `creative_manifest: Creative Manifest`
+Optional: `feature_ids: string[]`, `account: Account Ref`, `context: Context`
+
+#### `sync_plans`
+
+Push campaign plans to the governance agent.
+
+Required: `plans: object[]`
+
+#### `report_plan_outcome`
+
+Report the outcome of an action to the governance agent.
+
+Required: `plan_id: string`, `outcome: Outcome Type`, `governance_context: string`
+Optional: `check_id: string`, `idempotency_key: string`, `seller_response: object`, `delivery: object`, `error: object`
+
+#### `get_plan_audit_logs`
+
+Retrieve governance state and audit trail for a plan.
+
+Optional: `plan_ids: string[]`, `portfolio_plan_ids: string[]`, `include_entries: boolean`
+
+#### `check_governance`
+
+Orchestrator or seller calls the governance agent to validate an action against the campaign plan.
+
+Required: `plan_id: string`, `caller: string`
+Optional: `tool: string`, `payload: object`, `governance_context: string`, `media_buy_id: string`, `phase: Governance Phase`, `planned_delivery: Planned Delivery`, `delivery_metrics: object`, `modification_summary: string`, +1 more
+
+**Deep dive:**
+- docs/guides/HANDLER-PATTERNS-GUIDE.md — input handler patterns for governance flows
+
+### Sponsored Intelligence
+
+#### `si_get_offering`
+
+Get offering details, availability, and optionally matching products before session handoff.
+
+Required: `offering_id: string`
+Optional: `context: string`, `include_products: boolean`, `product_limit: integer`
+
+#### `si_initiate_session`
+
+Host initiates SI session with brand agent - includes context, identity, and capability negotiation.
+
+Required: `context: string`, `identity: Si Identity`
+Optional: `media_buy_id: string`, `placement: string`, `offering_id: string`, `supported_capabilities: Si Capabilities`, `offering_token: string`, `idempotency_key: string`
+
+#### `si_send_message`
+
+Send a message within an active SI session.
+
+Required: `session_id: string`
+Optional: `message: string`, `action_response: object`
+
+#### `si_terminate_session`
+
+Terminate an SI session with reason (handoff_transaction, handoff_complete, user_exit, session_timeout, host_terminated).
+
+Required: `session_id: string`, `reason: 'handoff_transaction' | 'handoff_complete' | 'user_exit' | 'session_timeout' | 'host_terminated'`
+Optional: `termination_context: object`
+
+**Deep dive:**
+- docs/guides/ASYNC-DEVELOPER-GUIDE.md — session lifecycle patterns
+
+### Trusted Match (TMP)
+
+Real-time execution layer. These are HTTP operations, not MCP tools.
+
+#### `context_match`
+
+Evaluate available packages against content context.
+
+#### `identity_match`
+
+Evaluate user eligibility for packages using an opaque identity token.
+
+## Common Flows
+
+These are the standard tool call sequences from the AdCP storyboards. Each flow shows the tools called in order.
+
+### Audiences
+
+**Audience sync** — Tests sync_audiences: account discovery, audience creation with hashed identifiers, and audience deletion.
+Flow: `list_accounts → sync_audiences`
+
+### Products
+
+**Behavioral analysis** — Validates product discovery behavior, response consistency, and pricing edge cases.
+Flow: `get_products`
+
+### Core
+
+**Brand rights flow** — Agent that provides brand identity, queries rights, and supports rights acquisition.
+Flow: `get_brand_identity → get_rights → acquire_rights`
+
+**Deterministic testing** — Uses comply_test_controller to force state transitions and simulate delivery/budget, verifying state machines and reporting.
+Flow: `comply_test_controller → list_accounts → comply_test_controller → create_media_buy → comply_test_controller → get_media_buys → comply_test_controller → sync_creatives → comply_test_controller → si_initiate_session → comply_test_controller → si_send_message → create_media_buy → comply_test_controller → get_media_buy_delivery → create_media_buy → comply_test_controller`
+
+### Creative
+
+**Creative ad server** — Stateful ad server with pre-loaded creatives. Generates serving tags per media buy.
+Flow: `list_creatives → list_creative_formats → build_creative → get_creative_delivery`
+
+**Sales agent with creative capabilities** — Stateful sales agent that accepts pushed creative assets and renders them in its environment.
+Flow: `list_creative_formats → sync_creatives → preview_creative`
+
+**Creative template and transformation agent** — Stateless creative agent that takes assets in, applies templates, and produces tags or rendered output.
+Flow: `list_creative_formats → preview_creative → build_creative`
+
+### Error Handling
+
+**Error handling and compliance** — Validates that agents return properly structured AdCP errors with correct codes, recovery hints, and transport bindings.
+Flow: `create_media_buy → get_products → create_media_buy`
+
+### Governance
+
+**Governance content standards** — Content standards discovery, calibration, and delivery validation.
+Flow: `list_content_standards → get_content_standards → calibrate_content → validate_content_delivery`
+
+**Governance property list management** — CRUD lifecycle for property lists with filter round-trip validation.
+Flow: `create_property_list → get_property_list → update_property_list → list_property_lists → delete_property_list → get_property_list → create_property_list → get_property_list → delete_property_list`
+
+### Media Buy
+
+**Catalog-driven creative and conversion tracking** — Seller that renders dynamic ads from product catalogs, tracks conversions, and optimizes delivery based on performance feedback.
+Flow: `sync_accounts → list_creative_formats → sync_catalogs → get_products → create_media_buy → sync_event_sources → log_event → provide_performance_feedback → get_media_buy_delivery`
+
+**Guaranteed media buy with human IO approval** — Seller agent that requires human-in-the-loop IO signing before guaranteed media buys go live.
+Flow: `sync_accounts → get_products → create_media_buy → get_media_buys → sync_creatives → get_media_buy_delivery`
+
+**Non-guaranteed auction-based media buy** — Seller agent for auction-based, non-guaranteed buying where the buyer sets bid prices and budgets.
+Flow: `get_products → create_media_buy → get_media_buys → update_media_buy → get_media_buy_delivery`
+
+**Media buy via proposal acceptance** — Seller agent that generates curated media plan proposals the buyer can review, refine, and accept.
+Flow: `sync_accounts → get_products → create_media_buy → list_creative_formats → sync_creatives → get_media_buy_delivery`
+
+**Media buy state machine lifecycle** — Validates media buy state transitions: create, pause, resume, cancel, and terminal state enforcement.
+Flow: `get_products → create_media_buy → update_media_buy`
+
+### Campaign Governance
+
+**Governance denial and human escalation** — Buyer's governance agent denies a media buy that exceeds spending authority, escalates to a human who approves with conditions.
+Flow: `sync_accounts → sync_governance → sync_plans → get_products → check_governance → create_media_buy → report_plan_outcome → get_plan_audit_logs`
+
+### Reporting
+
+**Media buy seller agent** — Seller agent that receives briefs, returns products, accepts media buys, and reports delivery.
+Flow: `sync_accounts → sync_governance → get_products → create_media_buy → get_media_buys → list_creative_formats → sync_creatives → get_media_buy_delivery`
+
+### Sponsored Intelligence (SI)
+
+**Sponsored intelligence session** — SI agent that serves offerings, manages conversational sessions, and handles purchase handoffs.
+Flow: `si_get_offering → si_initiate_session → si_send_message → si_terminate_session → si_send_message → si_initiate_session → si_send_message → si_terminate_session`
+
+### Signals
+
+**Marketplace signal agent** — Signal agent that resells third-party data provider signals with verifiable catalog provenance.
+Flow: `get_signals → activate_signal`
+
+**Owned signal agent** — Signal agent serving first-party or proprietary audience data without external catalog verification.
+Flow: `get_signals → activate_signal`
+
+## Error Codes
+
+Agents use the `recovery` classification to decide what to do: `transient` → retry after delay, `correctable` → fix parameters and retry, `terminal` → stop and report.
+
+| Code | Recovery | Description |
+|------|----------|-------------|
+| `INVALID_REQUEST` | correctable | The request is malformed or contains invalid parameters |
+| `AUTH_REQUIRED` | correctable | Authentication is required or the provided credentials are invalid |
+| `RATE_LIMITED` | transient | Too many requests; retry after the specified delay |
+| `SERVICE_UNAVAILABLE` | transient | The service is temporarily unavailable |
+| `POLICY_VIOLATION` | correctable | The request violates a platform or advertiser policy |
+| `PRODUCT_NOT_FOUND` | correctable | The requested product does not exist |
+| `PRODUCT_UNAVAILABLE` | transient | The product exists but is not currently available |
+| `PROPOSAL_EXPIRED` | correctable | The proposal has expired and is no longer valid |
+| `BUDGET_TOO_LOW` | correctable | The specified budget is below the minimum threshold |
+| `CREATIVE_REJECTED` | correctable | One or more creatives failed review or validation |
+| `UNSUPPORTED_FEATURE` | terminal | The requested feature is not supported by this seller |
+| `AUDIENCE_TOO_SMALL` | correctable | The target audience is too small to deliver against |
+| `ACCOUNT_NOT_FOUND` | terminal | The specified account does not exist |
+| `ACCOUNT_SETUP_REQUIRED` | terminal | The account requires additional setup before use |
+| `ACCOUNT_AMBIGUOUS` | correctable | Multiple accounts match; provide a more specific identifier |
+| `ACCOUNT_PAYMENT_REQUIRED` | terminal | The account has an outstanding payment issue |
+| `ACCOUNT_SUSPENDED` | terminal | The account has been suspended |
+| `COMPLIANCE_UNSATISFIED` | correctable | Compliance requirements have not been met |
+| `BUDGET_EXHAUSTED` | terminal | The budget has been fully spent |
+| `BUDGET_EXCEEDED` | correctable | Operation would exceed the allocated budget for the media buy or package |
+| `CONFLICT` | correctable | The request conflicts with the current state of the resource |
+| `INVALID_STATE` | correctable | Operation is not permitted for the resource's current status |
+| `MEDIA_BUY_NOT_FOUND` | correctable | Referenced media buy does not exist or is not accessible |
+| `NOT_CANCELLABLE` | correctable | The media buy or package cannot be canceled in its current state |
+| `PACKAGE_NOT_FOUND` | correctable | Referenced package does not exist within the specified media buy |
+| `VALIDATION_ERROR` | correctable | Request contains invalid field values or violates business rules beyond schema validation |
+
+Unknown codes: fall back to the HTTP status code (4xx = correctable, 5xx = transient).
+
+## Test Scenarios
+
+Run compliance tests with `adcp test <agent> <scenario>`. 24 built-in scenarios:
+
+| Scenario | What it tests |
+|----------|---------------|
+| `health_check` | Basic connectivity check - verify agent responds |
+| `discovery` | Test get_products, list_creative_formats, list_authorized_properties |
+| `create_media_buy` | Discovery + create a test media buy (dry-run by default) |
+| `full_sales_flow` | Full lifecycle: discovery → create → update → delivery |
+| `creative_sync` | Test sync_creatives flow |
+| `creative_inline` | Test inline creatives in create_media_buy |
+| `creative_flow` | Creative agent: list_formats → build → preview |
+| `signals_flow` | Signals agent: get_signals → activate |
+| `error_handling` | Verify agent returns proper error responses |
+| `validation` | Test schema validation (invalid inputs should be rejected) |
+| `pricing_edge_cases` | Test auction vs fixed pricing, min spend, bid_price |
+| `temporal_validation` | Test date/time ordering and format validation |
+| `behavior_analysis` | Analyze agent behavior: auth, brief relevance, filtering |
+| `response_consistency` | Check for schema errors, pagination bugs, data mismatches |
+| `capability_discovery` | Test get_adcp_capabilities and verify v3 protocol support |
+| `governance_property_lists` | Test property list CRUD (create, get, update, delete) |
+| `governance_content_standards` | Test content standards listing and calibration |
+| `si_session_lifecycle` | Test full SI session: initiate → messages → terminate |
+| `si_availability` | Quick check for SI offering availability |
+| `campaign_governance` | Full governance lifecycle: sync_plans → check → execute → report |
+| `campaign_governance_denied` | Denied flow: over-budget, unauthorized market |
+| `campaign_governance_conditions` | Conditions flow: apply conditions → re-check |
+| `campaign_governance_delivery` | Delivery monitoring with drift detection |
+| `seller_governance_context` | Verify seller persists governance_context from media buy lifecycle |
+
+**Deep dive:** storyboards/ directory has full YAML definitions for each flow
+
+## Key Types
+
+See docs/TYPE-SUMMARY.md for field-level detail. Key types at a glance:
+
+| Type | Purpose |
+|------|---------|
+| `AgentConfig` | Agent connection config (uri, protocol, auth) |
+| `TaskResult<T>` | Return type of every tool call (status + data/error/deferred/submitted) |
+| `InputHandler` | Callback for agent clarification requests |
+| `ConversationContext` | Passed to InputHandler with messages, question, helpers |
+| `Product` | Advertising inventory item with formats, pricing, targeting |
+| `MediaBuy` | Purchased campaign with packages, budget, schedule |
+| `CreativeAsset` | Creative with type, format, dimensions, status |
+| `Targeting` | Audience criteria (geo, demo, behavioral, contextual, device) |
+| `PricingOption` | Price model (CPM, vCPM, CPC, CPCV, CPV, CPP, CPA, FlatRate, Time) |
+| `GovernanceConfig` | Buyer-side governance middleware config |
+
+## Task Statuses
+
+Every tool call returns a `TaskResult` with one of these statuses:
+
+- `completed` — Success. Data in `result.data`.
+- `input-required` — Agent needs clarification. Use `InputHandler` or `result.deferred.resume(answer)`.
+- `submitted` — Long-running. Poll via `result.submitted.waitForCompletion()` or use webhooks.
+- `working` — In progress (intermediate, usually not seen by callers).
+- `deferred` — Requires human decision. Token in `result.deferred.token`.
+- `governance-denied` / `governance-escalated` — Blocked or flagged by governance middleware.
+
+**Deep dive:** docs/guides/ASYNC-DEVELOPER-GUIDE.md, docs/guides/ASYNC-API-REFERENCE.md
+
+## Protocols
+
+AdCP tools are served over MCP (Model Context Protocol) or A2A (Agent-to-Agent). The client auto-detects based on `AgentConfig.protocol`. MCP endpoints end with `/mcp/`. Auth is via bearer token in `x-adcp-auth` header.
+
+**Deep dive:** docs/development/PROTOCOL_DIFFERENCES.md
+
+## Discovery
+
+Publishers declare agents in `/.well-known/adagents.json`. Brands declare identity in `/.well-known/brand.json`. Use `PropertyCrawler` or `adcp registry` CLI to discover agents.
+
+## Where to Read More
+
+These docs are available locally in the repo and hosted at https://adcontextprotocol.github.io/adcp-client/
+
+| Need | Local path | Hosted |
+|------|-----------|--------|
+| Full type signatures | docs/TYPE-SUMMARY.md | [link](https://adcontextprotocol.github.io/adcp-client/TYPE-SUMMARY.md) |
+| Getting started / install | docs/getting-started.md | [link](https://adcontextprotocol.github.io/adcp-client/getting-started.md) |
+| Build a server-side agent | docs/guides/BUILD-AN-AGENT.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/BUILD-AN-AGENT.md) |
+| Async patterns (polling, webhooks, deferred) | docs/guides/ASYNC-DEVELOPER-GUIDE.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/ASYNC-DEVELOPER-GUIDE.md) |
+| Async API reference | docs/guides/ASYNC-API-REFERENCE.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/ASYNC-API-REFERENCE.md) |
+| Input handler patterns | docs/guides/HANDLER-PATTERNS-GUIDE.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/HANDLER-PATTERNS-GUIDE.md) |
+| Webhook configuration | docs/guides/PUSH-NOTIFICATION-CONFIG.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/PUSH-NOTIFICATION-CONFIG.md) |
+| Real-world code examples | docs/guides/REAL-WORLD-EXAMPLES.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/REAL-WORLD-EXAMPLES.md) |
+| CLI reference | docs/CLI.md | [link](https://adcontextprotocol.github.io/adcp-client/CLI.md) |
+| Zod runtime validation | docs/ZOD-SCHEMAS.md | [link](https://adcontextprotocol.github.io/adcp-client/ZOD-SCHEMAS.md) |
+| Testing strategy | docs/guides/TESTING-STRATEGY.md | [link](https://adcontextprotocol.github.io/adcp-client/guides/TESTING-STRATEGY.md) |
+| Protocol differences (MCP vs A2A) | docs/development/PROTOCOL_DIFFERENCES.md | [link](https://adcontextprotocol.github.io/adcp-client/development/PROTOCOL_DIFFERENCES.md) |
+| TypeDoc API reference | docs/api/index.html | [link](https://adcontextprotocol.github.io/adcp-client/api/index.html) |
+
+JSON schemas (source of truth): `schemas/cache/latest/index.json` (local only)
+
+## External Resources
+
+- Documentation: https://adcontextprotocol.github.io/adcp-client/
+- npm: https://www.npmjs.com/package/@adcp/client
+- Spec: https://adcontextprotocol.org
+- CLI: `npx @adcp/client`