From f4d9fb0e708e81101f212f071967c06c1dd5c7a4 Mon Sep 17 00:00:00 2001 From: Emma Mulitz Date: Mon, 16 Mar 2026 15:23:07 -0400 Subject: [PATCH 1/6] fix: restore granular .mintignore to unbreak versioned docs PR #1462 replaced the granular .mintignore with a blanket `dist/` ignore, which prevents Mintlify from serving versioned doc snapshots (2.5.3, 3.0.0-beta.3, rc.1, rc.2) that live under dist/docs/. Restore specific dist/ subdirectory ignores so dist/docs/ is served while dist/schemas/, dist/db/, etc. remain excluded. --- .mintignore | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/.mintignore b/.mintignore index 416c37d8cd..536a7a5760 100644 --- a/.mintignore +++ b/.mintignore @@ -1,5 +1,17 @@ -dist/ +dist/schemas/ +dist/db/ +dist/index.js +dist/index.js.map +dist/creative-agent/ .addie-repos/ .context/ .changeset/ node_modules/ +server/ +tests/ +scripts/ +skills/ +static/openapi/ +*.test.* +*.spec.* +CHANGELOG.md From da2497bfeba8772cc099a44912210d73fad542e6 Mon Sep 17 00:00:00 2001 From: Emma Mulitz Date: Mon, 16 Mar 2026 16:22:39 -0400 Subject: [PATCH 2/6] fix: repair broken docs links for list_creative_formats and sync_creatives These tasks moved from media-buy/task-reference/ to creative/task-reference/ in v3 but 18 internal links still pointed to the old location, breaking both the rc.2 versioned snapshot and the live source docs. --- dist/docs/3.0.0-rc.2/creative/formats.mdx | 2 +- dist/docs/3.0.0-rc.2/creative/private-assets.mdx | 4 ++-- .../creative/task-reference/list_creative_formats.mdx | 2 +- dist/docs/3.0.0-rc.2/learning/specialist/creative.mdx | 2 +- dist/docs/3.0.0-rc.2/learning/tracks/buyer.mdx | 2 +- dist/docs/3.0.0-rc.2/learning/tracks/publisher.mdx | 2 +- .../capability-discovery/implementing-standard-formats.mdx | 2 +- dist/docs/3.0.0-rc.2/media-buy/capability-discovery/index.mdx | 4 ++-- dist/docs/3.0.0-rc.2/media-buy/creatives/index.mdx | 2 +- dist/docs/3.0.0-rc.2/media-buy/product-discovery/index.mdx | 4 ++-- dist/docs/3.0.0-rc.2/media-buy/specification.mdx | 2 +- .../docs/3.0.0-rc.2/media-buy/task-reference/get_products.mdx | 2 +- dist/docs/3.0.0-rc.2/media-buy/task-reference/index.mdx | 4 ++-- .../3.0.0-rc.2/media-buy/task-reference/sync_catalogs.mdx | 2 +- docs/creative/formats.mdx | 2 +- docs/creative/task-reference/list_creative_formats.mdx | 2 +- docs/learning/tracks/publisher.mdx | 2 +- .../capability-discovery/implementing-standard-formats.mdx | 2 +- docs/media-buy/capability-discovery/index.mdx | 4 ++-- docs/media-buy/product-discovery/index.mdx | 4 ++-- docs/media-buy/specification.mdx | 2 +- docs/media-buy/task-reference/get_products.mdx | 2 +- docs/media-buy/task-reference/index.mdx | 4 ++-- docs/media-buy/task-reference/sync_catalogs.mdx | 2 +- 24 files changed, 31 insertions(+), 31 deletions(-) diff --git a/dist/docs/3.0.0-rc.2/creative/formats.mdx b/dist/docs/3.0.0-rc.2/creative/formats.mdx index 7a4cc62426..5727e2669d 100644 --- a/dist/docs/3.0.0-rc.2/creative/formats.mdx +++ b/dist/docs/3.0.0-rc.2/creative/formats.mdx @@ -782,4 +782,4 @@ This ensures a consistent user experience regardless of what format metadata is - [Asset Types](/dist/docs/3.0.0-rc.2/creative/asset-types) - Understanding asset specifications - [Channel Guides](/dist/docs/3.0.0-rc.2/creative/channels/video) - Detailed format documentation by media type - [Implementing Standard Format Support](/dist/docs/3.0.0-rc.2/media-buy/capability-discovery/implementing-standard-formats) - For sales agents -- [list_creative_formats Task](/dist/docs/3.0.0-rc.2/media-buy/task-reference/list_creative_formats) - API reference for format discovery +- [list_creative_formats Task](/dist/docs/3.0.0-rc.2/creative/task-reference/list_creative_formats) - API reference for format discovery diff --git a/dist/docs/3.0.0-rc.2/creative/private-assets.mdx b/dist/docs/3.0.0-rc.2/creative/private-assets.mdx index f3e5ee9898..491b30d7fc 100644 --- a/dist/docs/3.0.0-rc.2/creative/private-assets.mdx +++ b/dist/docs/3.0.0-rc.2/creative/private-assets.mdx @@ -126,7 +126,7 @@ Set presigned URL expiration long enough to cover the full workflow, but no long | --- | --- | | [`build_creative`](/dist/docs/3.0.0-rc.2/creative/task-reference/build_creative) only | 1 hour | | [`build_creative`](/dist/docs/3.0.0-rc.2/creative/task-reference/build_creative) + [`preview_creative`](/dist/docs/3.0.0-rc.2/creative/task-reference/preview_creative) | 2 hours | -| Full pipeline (build, preview, iterate, [`sync_creatives`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/sync_creatives)) | 4 hours | +| Full pipeline (build, preview, iterate, [`sync_creatives`](/dist/docs/3.0.0-rc.2/creative/task-reference/sync_creatives)) | 4 hours | If a presigned URL expires mid-workflow, the creative agent will receive an HTTP error when fetching the asset. The buyer agent must generate a new presigned URL and resubmit the request. @@ -206,4 +206,4 @@ Presigned URLs avoid this by encoding authorization into the URL itself: - [Creative manifests](/dist/docs/3.0.0-rc.2/creative/creative-manifests) — manifest structure and asset references - [Asset types](/dist/docs/3.0.0-rc.2/creative/asset-types) — requirements for each asset type - [`build_creative`](/dist/docs/3.0.0-rc.2/creative/task-reference/build_creative) — generating creatives from manifests -- [`sync_creatives`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/sync_creatives) — syncing creatives to a media buy +- [`sync_creatives`](/dist/docs/3.0.0-rc.2/creative/task-reference/sync_creatives) — syncing creatives to a media buy diff --git a/dist/docs/3.0.0-rc.2/creative/task-reference/list_creative_formats.mdx b/dist/docs/3.0.0-rc.2/creative/task-reference/list_creative_formats.mdx index ae8ffe24b1..f56fada3eb 100644 --- a/dist/docs/3.0.0-rc.2/creative/task-reference/list_creative_formats.mdx +++ b/dist/docs/3.0.0-rc.2/creative/task-reference/list_creative_formats.mdx @@ -30,7 +30,7 @@ Any agent implementing the Creative Protocol can serve `list_creative_formats`. **Sales agents implementing both protocols** — return their own self-hosted format definitions alongside referenced formats. See [Creative capabilities on sales agents](/dist/docs/3.0.0-rc.2/creative/sales-agent-creative-capabilities). -See [list_creative_formats (Sales Agent)](/dist/docs/3.0.0-rc.2/media-buy/task-reference/list_creative_formats) for sales agent-specific behavior. +See [list_creative_formats (Sales Agent)](/dist/docs/3.0.0-rc.2/creative/task-reference/list_creative_formats) for sales agent-specific behavior. ## Request Parameters diff --git a/dist/docs/3.0.0-rc.2/learning/specialist/creative.mdx b/dist/docs/3.0.0-rc.2/learning/specialist/creative.mdx index 382e5d89ed..4541f7b371 100644 --- a/dist/docs/3.0.0-rc.2/learning/specialist/creative.mdx +++ b/dist/docs/3.0.0-rc.2/learning/specialist/creative.mdx @@ -36,7 +36,7 @@ Passing earns the **AdCP specialist — Creative** credential. Preview creatives before deployment. - + Synchronize creative assets with publisher platforms. diff --git a/dist/docs/3.0.0-rc.2/learning/tracks/buyer.mdx b/dist/docs/3.0.0-rc.2/learning/tracks/buyer.mdx index 3dd47955dd..228a22c55f 100644 --- a/dist/docs/3.0.0-rc.2/learning/tracks/buyer.mdx +++ b/dist/docs/3.0.0-rc.2/learning/tracks/buyer.mdx @@ -143,7 +143,7 @@ How creative assets flow through AdCP: `build_creative`, `preview_creative`, `sy Previewing creatives before deployment. - + Synchronizing creative assets with publisher platforms. diff --git a/dist/docs/3.0.0-rc.2/learning/tracks/publisher.mdx b/dist/docs/3.0.0-rc.2/learning/tracks/publisher.mdx index 9f9d825cb0..708eb255b6 100644 --- a/dist/docs/3.0.0-rc.2/learning/tracks/publisher.mdx +++ b/dist/docs/3.0.0-rc.2/learning/tracks/publisher.mdx @@ -77,7 +77,7 @@ Deep dive on `list_creative_formats` and how buyer agents discover what your inv Real examples of product discovery queries from buyer agents. - + How creative format specifications work — dimensions, file types, render requirements. diff --git a/dist/docs/3.0.0-rc.2/media-buy/capability-discovery/implementing-standard-formats.mdx b/dist/docs/3.0.0-rc.2/media-buy/capability-discovery/implementing-standard-formats.mdx index 9a127d28d8..e9499ba3f1 100644 --- a/dist/docs/3.0.0-rc.2/media-buy/capability-discovery/implementing-standard-formats.mdx +++ b/dist/docs/3.0.0-rc.2/media-buy/capability-discovery/implementing-standard-formats.mdx @@ -487,4 +487,4 @@ The reference creative agent maintains format versions and compatibility: - [Creative Protocol Overview](/dist/docs/3.0.0-rc.2/creative) - How formats, manifests, and agents work together - [Creative Formats](/dist/docs/3.0.0-rc.2/creative/formats) - Understanding format specifications and discovery - [Channel Guides](/dist/docs/3.0.0-rc.2/creative/channels/video) - Detailed format documentation by media type -- [list_creative_formats Task](/dist/docs/3.0.0-rc.2/media-buy/task-reference/list_creative_formats) - API reference for format discovery +- [list_creative_formats Task](/dist/docs/3.0.0-rc.2/creative/task-reference/list_creative_formats) - API reference for format discovery diff --git a/dist/docs/3.0.0-rc.2/media-buy/capability-discovery/index.mdx b/dist/docs/3.0.0-rc.2/media-buy/capability-discovery/index.mdx index 4affbaefd5..d6b85f1a4e 100644 --- a/dist/docs/3.0.0-rc.2/media-buy/capability-discovery/index.mdx +++ b/dist/docs/3.0.0-rc.2/media-buy/capability-discovery/index.mdx @@ -41,7 +41,7 @@ These capability discovery tasks provide the reference data needed for effective ### [`get_adcp_capabilities`](/dist/docs/3.0.0-rc.2/protocol/get_adcp_capabilities) The primary capability discovery task. Returns protocol versions, supported features, portfolio information, and governance capabilities in a single call. Use this as your first interaction with any AdCP agent. -### [`list_creative_formats`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/list_creative_formats) +### [`list_creative_formats`](/dist/docs/3.0.0-rc.2/creative/task-reference/list_creative_formats) Discover all supported creative formats with detailed specifications including dimensions, file types, duration limits, and technical requirements. ## Integration Pattern @@ -49,7 +49,7 @@ Discover all supported creative formats with detailed specifications including d Capability discovery typically happens early in your AdCP workflow: 1. **Discover Capabilities**: Call [`get_adcp_capabilities`](/dist/docs/3.0.0-rc.2/protocol/get_adcp_capabilities) to learn what the agent supports -2. **Understand Formats**: Call [`list_creative_formats`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/list_creative_formats) to learn supported creative types +2. **Understand Formats**: Call [`list_creative_formats`](/dist/docs/3.0.0-rc.2/creative/task-reference/list_creative_formats) to learn supported creative types 3. **Validate Authorization**: Check the `media_buy.portfolio` from capabilities, then verify via publisher `adagents.json` 4. **Discover Products**: Search for advertising inventory with [`get_products`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/get_products) 5. **Plan Creatives**: Match discovered products to available formats for production planning diff --git a/dist/docs/3.0.0-rc.2/media-buy/creatives/index.mdx b/dist/docs/3.0.0-rc.2/media-buy/creatives/index.mdx index 7ae02df2dd..46c504bd99 100644 --- a/dist/docs/3.0.0-rc.2/media-buy/creatives/index.mdx +++ b/dist/docs/3.0.0-rc.2/media-buy/creatives/index.mdx @@ -173,7 +173,7 @@ Creative operations have varying response times: - **[`sync_creatives`](/dist/docs/3.0.0-rc.2/creative/task-reference/sync_creatives)** - Bulk creative management with upsert semantics - **[`list_creatives`](/dist/docs/3.0.0-rc.2/creative/task-reference/list_creatives)** - Advanced creative library querying and filtering -- **[`list_creative_formats`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/list_creative_formats)** - Understanding format requirements +- **[`list_creative_formats`](/dist/docs/3.0.0-rc.2/creative/task-reference/list_creative_formats)** - Understanding format requirements - **[Brand identity](/dist/docs/3.0.0-rc.2/brand-protocol/brand-json)** - Brand identity and asset management - **[Creative Formats](/dist/docs/3.0.0-rc.2/creative/formats)** - Understanding format specifications and discovery - **[Creative Channel Guides](/dist/docs/3.0.0-rc.2/creative/channels/video)** - Format examples across video, display, audio, DOOH, and carousels diff --git a/dist/docs/3.0.0-rc.2/media-buy/product-discovery/index.mdx b/dist/docs/3.0.0-rc.2/media-buy/product-discovery/index.mdx index b37a0bfe64..11b43be1bf 100644 --- a/dist/docs/3.0.0-rc.2/media-buy/product-discovery/index.mdx +++ b/dist/docs/3.0.0-rc.2/media-buy/product-discovery/index.mdx @@ -71,7 +71,7 @@ For catalog-driven campaigns (retail media, job boards, travel), pass a `catalog Product discovery works hand-in-hand with creative planning: 1. **Products return format IDs** for required creative specifications -2. **Use [`list_creative_formats`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/list_creative_formats)** to get detailed format requirements +2. **Use [`list_creative_formats`](/dist/docs/3.0.0-rc.2/creative/task-reference/list_creative_formats)** to get detailed format requirements 3. **Plan creative production** based on discovered format needs ## Brief Examples & Patterns @@ -110,7 +110,7 @@ Explore comprehensive examples in [Example Briefs](/dist/docs/3.0.0-rc.2/media-b Product discovery operations: - **[`get_products`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/get_products)**: ~60 seconds (AI processing) -- **[`list_creative_formats`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/list_creative_formats)**: ~1 second (database lookup) +- **[`list_creative_formats`](/dist/docs/3.0.0-rc.2/creative/task-reference/list_creative_formats)**: ~1 second (database lookup) ## Next Steps diff --git a/dist/docs/3.0.0-rc.2/media-buy/specification.mdx b/dist/docs/3.0.0-rc.2/media-buy/specification.mdx index f4aa23915b..b7d89628c8 100644 --- a/dist/docs/3.0.0-rc.2/media-buy/specification.mdx +++ b/dist/docs/3.0.0-rc.2/media-buy/specification.mdx @@ -130,7 +130,7 @@ Each `get_products` request with `buying_mode: "refine"` is self-contained — s **Schema**: [`media-buy/list-creative-formats-request.json`](https://adcontextprotocol.org/schemas/v2/media-buy/list-creative-formats-request.json) / [`media-buy/list-creative-formats-response.json`](https://adcontextprotocol.org/schemas/v2/media-buy/list-creative-formats-response.json) -**Reference**: [`list_creative_formats` task](/dist/docs/3.0.0-rc.2/media-buy/task-reference/list_creative_formats) +**Reference**: [`list_creative_formats` task](/dist/docs/3.0.0-rc.2/creative/task-reference/list_creative_formats) Discover creative format requirements and specifications. diff --git a/dist/docs/3.0.0-rc.2/media-buy/task-reference/get_products.mdx b/dist/docs/3.0.0-rc.2/media-buy/task-reference/get_products.mdx index 948acb02dc..5bf91cb492 100644 --- a/dist/docs/3.0.0-rc.2/media-buy/task-reference/get_products.mdx +++ b/dist/docs/3.0.0-rc.2/media-buy/task-reference/get_products.mdx @@ -1397,7 +1397,7 @@ After discovering products: 1. **Review Options**: Compare products, pricing, and targeting capabilities 2. **Create Media Buy**: Use [`create_media_buy`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/create_media_buy) to execute campaign -3. **Prepare Creatives**: Use [`list_creative_formats`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/list_creative_formats) to see format requirements +3. **Prepare Creatives**: Use [`list_creative_formats`](/dist/docs/3.0.0-rc.2/creative/task-reference/list_creative_formats) to see format requirements 4. **Upload Assets**: Use [`sync_creatives`](/dist/docs/3.0.0-rc.2/creative/task-reference/sync_creatives) to provide creative assets ## Learn More diff --git a/dist/docs/3.0.0-rc.2/media-buy/task-reference/index.mdx b/dist/docs/3.0.0-rc.2/media-buy/task-reference/index.mdx index d3243f775d..8f50ff287d 100644 --- a/dist/docs/3.0.0-rc.2/media-buy/task-reference/index.mdx +++ b/dist/docs/3.0.0-rc.2/media-buy/task-reference/index.mdx @@ -65,7 +65,7 @@ Start here to understand what's available and plan your campaign. - **[`get_adcp_capabilities`](/dist/docs/3.0.0-rc.2/protocol/get_adcp_capabilities)** - Discover agent capabilities, portfolio, and supported features (protocol-level task) - **[`get_products`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/get_products)** - The core discovery task using natural language briefs -- **[`list_creative_formats`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/list_creative_formats)** - Understand creative requirements +- **[`list_creative_formats`](/dist/docs/3.0.0-rc.2/creative/task-reference/list_creative_formats)** - Understand creative requirements ### Media Buy Management Create and manage your advertising campaigns. @@ -148,7 +148,7 @@ Long-running tasks provide: 1. **Discover Capabilities**: Use [`get_adcp_capabilities`](/dist/docs/3.0.0-rc.2/protocol/get_adcp_capabilities) to understand what the agent supports 2. **Find Inventory**: Use [`get_products`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/get_products) to find relevant inventory 3. **Refine Products**: Re-call [`get_products`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/get_products) with `buying_mode: "refine"` to iterate on budgets, pricing, and targeting -4. **Understand Formats**: Check [`list_creative_formats`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/list_creative_formats) for requirements +4. **Understand Formats**: Check [`list_creative_formats`](/dist/docs/3.0.0-rc.2/creative/task-reference/list_creative_formats) for requirements 5. **Sync Catalogs**: Use [`sync_catalogs`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/sync_catalogs) to push product feeds to the account 6. **Upload Creatives**: Use [`sync_creatives`](/dist/docs/3.0.0-rc.2/creative/task-reference/sync_creatives) for asset management 7. **Create Campaign**: Use [`create_media_buy`](/dist/docs/3.0.0-rc.2/media-buy/task-reference/create_media_buy) with selected products diff --git a/dist/docs/3.0.0-rc.2/media-buy/task-reference/sync_catalogs.mdx b/dist/docs/3.0.0-rc.2/media-buy/task-reference/sync_catalogs.mdx index 268ef43c8c..a0a81d41fe 100644 --- a/dist/docs/3.0.0-rc.2/media-buy/task-reference/sync_catalogs.mdx +++ b/dist/docs/3.0.0-rc.2/media-buy/task-reference/sync_catalogs.mdx @@ -257,4 +257,4 @@ Configure `push_notification_config` on the request to receive webhook notificat - [Catalogs](/dist/docs/3.0.0-rc.2/creative/catalogs) — Complete documentation on catalog types, sourcing, and format requirements - [Account state](/dist/docs/3.0.0-rc.2/building/integration/account-state) — How catalogs fit into the account setup sequence - [sync_creatives](/dist/docs/3.0.0-rc.2/creative/task-reference/sync_creatives) — Submit creatives that reference synced catalogs -- [list_creative_formats](/dist/docs/3.0.0-rc.2/media-buy/task-reference/list_creative_formats) — Discover format catalog requirements +- [list_creative_formats](/dist/docs/3.0.0-rc.2/creative/task-reference/list_creative_formats) — Discover format catalog requirements diff --git a/docs/creative/formats.mdx b/docs/creative/formats.mdx index 1a432cd343..74045f17d9 100644 --- a/docs/creative/formats.mdx +++ b/docs/creative/formats.mdx @@ -782,4 +782,4 @@ This ensures a consistent user experience regardless of what format metadata is - [Asset Types](/docs/creative/asset-types) - Understanding asset specifications - [Channel Guides](/docs/creative/channels/video) - Detailed format documentation by media type - [Implementing Standard Format Support](/docs/media-buy/capability-discovery/implementing-standard-formats) - For sales agents -- [list_creative_formats Task](/docs/media-buy/task-reference/list_creative_formats) - API reference for format discovery +- [list_creative_formats Task](/docs/creative/task-reference/list_creative_formats) - API reference for format discovery diff --git a/docs/creative/task-reference/list_creative_formats.mdx b/docs/creative/task-reference/list_creative_formats.mdx index 6a8b2efeea..d3a47b8ab7 100644 --- a/docs/creative/task-reference/list_creative_formats.mdx +++ b/docs/creative/task-reference/list_creative_formats.mdx @@ -30,7 +30,7 @@ Any agent implementing the Creative Protocol can serve `list_creative_formats`. **Sales agents implementing both protocols** — return their own self-hosted format definitions alongside referenced formats. See [Creative capabilities on sales agents](/docs/creative/sales-agent-creative-capabilities). -See [list_creative_formats (Sales Agent)](/docs/media-buy/task-reference/list_creative_formats) for sales agent-specific behavior. +See [list_creative_formats (Sales Agent)](/docs/creative/task-reference/list_creative_formats) for sales agent-specific behavior. ## Request Parameters diff --git a/docs/learning/tracks/publisher.mdx b/docs/learning/tracks/publisher.mdx index faf9d5b371..6dae956d89 100644 --- a/docs/learning/tracks/publisher.mdx +++ b/docs/learning/tracks/publisher.mdx @@ -77,7 +77,7 @@ Deep dive on `list_creative_formats` and how buyer agents discover what your inv Real examples of product discovery queries from buyer agents. - + How creative format specifications work — dimensions, file types, render requirements. diff --git a/docs/media-buy/capability-discovery/implementing-standard-formats.mdx b/docs/media-buy/capability-discovery/implementing-standard-formats.mdx index 43c6fe7f72..82a1affe8a 100644 --- a/docs/media-buy/capability-discovery/implementing-standard-formats.mdx +++ b/docs/media-buy/capability-discovery/implementing-standard-formats.mdx @@ -487,4 +487,4 @@ The reference creative agent maintains format versions and compatibility: - [Creative Protocol Overview](/docs/creative) - How formats, manifests, and agents work together - [Creative Formats](/docs/creative/formats) - Understanding format specifications and discovery - [Channel Guides](/docs/creative/channels/video) - Detailed format documentation by media type -- [list_creative_formats Task](/docs/media-buy/task-reference/list_creative_formats) - API reference for format discovery +- [list_creative_formats Task](/docs/creative/task-reference/list_creative_formats) - API reference for format discovery diff --git a/docs/media-buy/capability-discovery/index.mdx b/docs/media-buy/capability-discovery/index.mdx index 07490cede0..149f40a7a6 100644 --- a/docs/media-buy/capability-discovery/index.mdx +++ b/docs/media-buy/capability-discovery/index.mdx @@ -41,7 +41,7 @@ These capability discovery tasks provide the reference data needed for effective ### [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities) The primary capability discovery task. Returns protocol versions, supported features, portfolio information, and governance capabilities in a single call. Use this as your first interaction with any AdCP agent. -### [`list_creative_formats`](/docs/media-buy/task-reference/list_creative_formats) +### [`list_creative_formats`](/docs/creative/task-reference/list_creative_formats) Discover all supported creative formats with detailed specifications including dimensions, file types, duration limits, and technical requirements. ## Integration Pattern @@ -49,7 +49,7 @@ Discover all supported creative formats with detailed specifications including d Capability discovery typically happens early in your AdCP workflow: 1. **Discover Capabilities**: Call [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities) to learn what the agent supports -2. **Understand Formats**: Call [`list_creative_formats`](/docs/media-buy/task-reference/list_creative_formats) to learn supported creative types +2. **Understand Formats**: Call [`list_creative_formats`](/docs/creative/task-reference/list_creative_formats) to learn supported creative types 3. **Validate Authorization**: Check the `media_buy.portfolio` from capabilities, then verify via publisher `adagents.json` 4. **Discover Products**: Search for advertising inventory with [`get_products`](/docs/media-buy/task-reference/get_products) 5. **Plan Creatives**: Match discovered products to available formats for production planning diff --git a/docs/media-buy/product-discovery/index.mdx b/docs/media-buy/product-discovery/index.mdx index 354127b329..34ab6eb873 100644 --- a/docs/media-buy/product-discovery/index.mdx +++ b/docs/media-buy/product-discovery/index.mdx @@ -71,7 +71,7 @@ For catalog-driven campaigns (retail media, job boards, travel), pass a `catalog Product discovery works hand-in-hand with creative planning: 1. **Products return format IDs** for required creative specifications -2. **Use [`list_creative_formats`](/docs/media-buy/task-reference/list_creative_formats)** to get detailed format requirements +2. **Use [`list_creative_formats`](/docs/creative/task-reference/list_creative_formats)** to get detailed format requirements 3. **Plan creative production** based on discovered format needs ## Brief Examples & Patterns @@ -110,7 +110,7 @@ Explore comprehensive examples in [Example Briefs](/docs/media-buy/product-disco Product discovery operations: - **[`get_products`](/docs/media-buy/task-reference/get_products)**: ~60 seconds (AI processing) -- **[`list_creative_formats`](/docs/media-buy/task-reference/list_creative_formats)**: ~1 second (database lookup) +- **[`list_creative_formats`](/docs/creative/task-reference/list_creative_formats)**: ~1 second (database lookup) ## Next Steps diff --git a/docs/media-buy/specification.mdx b/docs/media-buy/specification.mdx index 444c511ea5..dd2cd9edef 100644 --- a/docs/media-buy/specification.mdx +++ b/docs/media-buy/specification.mdx @@ -130,7 +130,7 @@ Each `get_products` request with `buying_mode: "refine"` is self-contained — s **Schema**: [`media-buy/list-creative-formats-request.json`](https://adcontextprotocol.org/schemas/v2/media-buy/list-creative-formats-request.json) / [`media-buy/list-creative-formats-response.json`](https://adcontextprotocol.org/schemas/v2/media-buy/list-creative-formats-response.json) -**Reference**: [`list_creative_formats` task](/docs/media-buy/task-reference/list_creative_formats) +**Reference**: [`list_creative_formats` task](/docs/creative/task-reference/list_creative_formats) Discover creative format requirements and specifications. diff --git a/docs/media-buy/task-reference/get_products.mdx b/docs/media-buy/task-reference/get_products.mdx index 5e2d87dc53..7c09e024b8 100644 --- a/docs/media-buy/task-reference/get_products.mdx +++ b/docs/media-buy/task-reference/get_products.mdx @@ -1397,7 +1397,7 @@ After discovering products: 1. **Review Options**: Compare products, pricing, and targeting capabilities 2. **Create Media Buy**: Use [`create_media_buy`](/docs/media-buy/task-reference/create_media_buy) to execute campaign -3. **Prepare Creatives**: Use [`list_creative_formats`](/docs/media-buy/task-reference/list_creative_formats) to see format requirements +3. **Prepare Creatives**: Use [`list_creative_formats`](/docs/creative/task-reference/list_creative_formats) to see format requirements 4. **Upload Assets**: Use [`sync_creatives`](/docs/creative/task-reference/sync_creatives) to provide creative assets ## Learn More diff --git a/docs/media-buy/task-reference/index.mdx b/docs/media-buy/task-reference/index.mdx index c82af757a5..b86ba7f0ec 100644 --- a/docs/media-buy/task-reference/index.mdx +++ b/docs/media-buy/task-reference/index.mdx @@ -65,7 +65,7 @@ Start here to understand what's available and plan your campaign. - **[`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities)** - Discover agent capabilities, portfolio, and supported features (protocol-level task) - **[`get_products`](/docs/media-buy/task-reference/get_products)** - The core discovery task using natural language briefs -- **[`list_creative_formats`](/docs/media-buy/task-reference/list_creative_formats)** - Understand creative requirements +- **[`list_creative_formats`](/docs/creative/task-reference/list_creative_formats)** - Understand creative requirements ### Media Buy Management Create and manage your advertising campaigns. @@ -148,7 +148,7 @@ Long-running tasks provide: 1. **Discover Capabilities**: Use [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities) to understand what the agent supports 2. **Find Inventory**: Use [`get_products`](/docs/media-buy/task-reference/get_products) to find relevant inventory 3. **Refine Products**: Re-call [`get_products`](/docs/media-buy/task-reference/get_products) with `buying_mode: "refine"` to iterate on budgets, pricing, and targeting -4. **Understand Formats**: Check [`list_creative_formats`](/docs/media-buy/task-reference/list_creative_formats) for requirements +4. **Understand Formats**: Check [`list_creative_formats`](/docs/creative/task-reference/list_creative_formats) for requirements 5. **Sync Catalogs**: Use [`sync_catalogs`](/docs/media-buy/task-reference/sync_catalogs) to push product feeds to the account 6. **Upload Creatives**: Use [`sync_creatives`](/docs/creative/task-reference/sync_creatives) for asset management 7. **Create Campaign**: Use [`create_media_buy`](/docs/media-buy/task-reference/create_media_buy) with selected products diff --git a/docs/media-buy/task-reference/sync_catalogs.mdx b/docs/media-buy/task-reference/sync_catalogs.mdx index 4b56b298a8..a604c31814 100644 --- a/docs/media-buy/task-reference/sync_catalogs.mdx +++ b/docs/media-buy/task-reference/sync_catalogs.mdx @@ -257,4 +257,4 @@ Configure `push_notification_config` on the request to receive webhook notificat - [Catalogs](/docs/creative/catalogs) — Complete documentation on catalog types, sourcing, and format requirements - [Account state](/docs/building/integration/account-state) — How catalogs fit into the account setup sequence - [sync_creatives](/docs/creative/task-reference/sync_creatives) — Submit creatives that reference synced catalogs -- [list_creative_formats](/docs/media-buy/task-reference/list_creative_formats) — Discover format catalog requirements +- [list_creative_formats](/docs/creative/task-reference/list_creative_formats) — Discover format catalog requirements From 2246cb5a4be22772b5ae4832f08e941a92fc089e Mon Sep 17 00:00:00 2001 From: Emma Mulitz Date: Mon, 16 Mar 2026 17:50:16 -0400 Subject: [PATCH 3/6] chore: add changeset for versioned docs fix --- .changeset/fix-versioned-docs-mintignore.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 .changeset/fix-versioned-docs-mintignore.md diff --git a/.changeset/fix-versioned-docs-mintignore.md b/.changeset/fix-versioned-docs-mintignore.md new file mode 100644 index 0000000000..6b7315dc35 --- /dev/null +++ b/.changeset/fix-versioned-docs-mintignore.md @@ -0,0 +1,10 @@ +--- +"adcontextprotocol": patch +--- + +fix: restore versioned docs and repair broken links + +Replaced blanket `dist/` in .mintignore with granular ignores so versioned doc +snapshots (2.5.3, 3.0.0-rc.2, etc.) are served by Mintlify again. Fixed 18 +broken internal links where list_creative_formats and sync_creatives moved from +media-buy/task-reference/ to creative/task-reference/ in v3. From 9933daa499ed3aa4bf116dae0a017129c1439328 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 16 Mar 2026 17:59:13 -0400 Subject: [PATCH 4/6] fix: remove Documentation wrapper from 2.5 versioned nav The nav restructure in #1509 accidentally wrapped the 2.5 version's groups inside a "Documentation" group. This nesting pattern works for 3.0-rc but causes Mintlify to 404 on all 2.5.3 doc pages. Restores the flat groups array for the 2.5 version. Co-Authored-By: Claude Opus 4.6 --- .changeset/b247ca1bb18ed028.md | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 .changeset/b247ca1bb18ed028.md diff --git a/.changeset/b247ca1bb18ed028.md b/.changeset/b247ca1bb18ed028.md new file mode 100644 index 0000000000..9156318309 --- /dev/null +++ b/.changeset/b247ca1bb18ed028.md @@ -0,0 +1,4 @@ +--- +--- + +Fix 404 on versioned 2.5.3 docs pages by removing incorrect Documentation wrapper group from nav config. From 64956141525568a3ea1dea0cee3a5cd69e89f3c8 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 16 Mar 2026 18:30:58 -0400 Subject: [PATCH 5/6] test: add docs nav validation to catch versioned docs breakage The nav restructure in #1509 broke all 2.5.3 docs but no test caught it. The pre-push hook deletes dist/docs before running mintlify broken-links, and mintlify broken-links only checks cross-references, not nav structure. Adds tests/docs-nav-validation.test.cjs which validates: - All page references resolve to files on disk (including dist/docs/) - No empty groups in the navigation - Snapshot versions have consistent version prefixes - Snapshot versions use flat top-level groups (not a single wrapper) Wired into the test chain so it runs on every commit. Co-Authored-By: Claude Opus 4.6 --- package.json | 3 +- tests/docs-nav-validation.test.cjs | 153 +++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+), 1 deletion(-) create mode 100644 tests/docs-nav-validation.test.cjs diff --git a/package.json b/package.json index fb42749428..2abdbf0add 100644 --- a/package.json +++ b/package.json @@ -31,7 +31,8 @@ "test:registry": "vitest run server/tests --exclude 'server/tests/simulation/**'", "test:simulation": "vitest run server/tests/simulation/scenarios --pool forks --poolOptions.forks.singleFork --testTimeout 120000", "test:docker": "docker compose -f docker-compose.test.yml up --build --abort-on-container-exit", - "test": "npm run test:schemas && npm run test:examples && npm run test:extensions && npm run test:extension-schemas && npm run test:error-handling && npm run test:json-schema && npm run test:composed && npm run test:migrations && npm run test:hmac-vectors && npm run test:unit && npm run test:openapi && npm run typecheck", + "test:docs-nav": "node tests/docs-nav-validation.test.cjs", + "test": "npm run test:docs-nav && npm run test:schemas && npm run test:examples && npm run test:extensions && npm run test:extension-schemas && npm run test:error-handling && npm run test:json-schema && npm run test:composed && npm run test:migrations && npm run test:hmac-vectors && npm run test:unit && npm run test:openapi && npm run typecheck", "test:all": "npm run test:schemas && npm run test:examples && npm run test:extensions && npm run test:error-handling && npm run test:snippets && npm run typecheck", "precommit": "npm test", "prepare": "husky", diff --git a/tests/docs-nav-validation.test.cjs b/tests/docs-nav-validation.test.cjs new file mode 100644 index 0000000000..bcb4679911 --- /dev/null +++ b/tests/docs-nav-validation.test.cjs @@ -0,0 +1,153 @@ +#!/usr/bin/env node +/** + * Docs navigation validation test suite + * Validates that docs.json navigation structure is valid for Mintlify, + * including versioned docs that live under dist/docs/. + */ + +const fs = require('fs'); +const path = require('path'); + +const DOCS_JSON = path.join(__dirname, '../docs.json'); + +let totalTests = 0; +let passedTests = 0; +let failedTests = 0; + +function log(message, type = 'info') { + const colors = { + info: '\x1b[0m', + success: '\x1b[32m', + error: '\x1b[31m', + warning: '\x1b[33m' + }; + console.log(`${colors[type]}${message}\x1b[0m`); +} + +function test(name, fn) { + totalTests++; + try { + fn(); + passedTests++; + log(` ✓ ${name}`, 'success'); + } catch (error) { + failedTests++; + log(` ✗ ${name}`, 'error'); + log(` ${error.message}`, 'error'); + } +} + +/** + * Recursively collect all page paths from a navigation tree. + */ +function collectPages(node) { + if (typeof node === 'string') return [node]; + if (Array.isArray(node)) return node.flatMap(collectPages); + if (node && node.pages) return collectPages(node.pages); + return []; +} + +/** + * Recursively collect all groups (objects with a `group` key) from a navigation tree. + */ +function collectGroups(node) { + const groups = []; + if (Array.isArray(node)) { + node.forEach(item => groups.push(...collectGroups(item))); + } else if (node && typeof node === 'object') { + if (node.group) groups.push(node); + if (node.pages) groups.push(...collectGroups(node.pages)); + if (node.groups) groups.push(...collectGroups(node.groups)); + } + return groups; +} + +// --- Run tests --- + +log('\n🧪 Docs Navigation Validation Tests'); +log('====================================\n'); + +const docsConfig = JSON.parse(fs.readFileSync(DOCS_JSON, 'utf8')); +const { navigation } = docsConfig; + +if (!navigation || !navigation.versions) { + log('No navigation.versions found in docs.json', 'error'); + process.exit(1); +} + +const rootDir = path.join(__dirname, '..'); + +for (const versionEntry of navigation.versions) { + const { version, groups } = versionEntry; + log(`Version: ${version}`); + + const allPages = collectPages(groups); + const allGroups = collectGroups(groups); + + // Test 1: All page references resolve to files on disk + test(`all ${allPages.length} page files exist`, () => { + const missing = []; + for (const pagePath of allPages) { + const mdx = path.join(rootDir, pagePath + '.mdx'); + const md = path.join(rootDir, pagePath + '.md'); + if (!fs.existsSync(mdx) && !fs.existsSync(md)) { + missing.push(pagePath); + } + } + if (missing.length > 0) { + throw new Error(`Missing files:\n ${missing.slice(0, 10).join('\n ')}${missing.length > 10 ? `\n ... and ${missing.length - 10} more` : ''}`); + } + }); + + // Test 2: No empty groups + test('no empty groups', () => { + const empty = allGroups.filter(g => { + const pages = collectPages(g.pages || []); + return pages.length === 0; + }); + if (empty.length > 0) { + throw new Error(`Empty groups: ${empty.map(g => g.group).join(', ')}`); + } + }); + + // Test 3: Versioned (dist/docs/) pages must have consistent version prefix + const distPages = allPages.filter(p => p.startsWith('dist/docs/')); + if (distPages.length > 0) { + test('dist/docs pages share a consistent version prefix', () => { + const prefixes = new Set(distPages.map(p => { + const parts = p.split('/'); + return `${parts[0]}/${parts[1]}/${parts[2]}`; + })); + if (prefixes.size > 1) { + throw new Error(`Mixed version prefixes: ${[...prefixes].join(', ')}`); + } + }); + + // Test 4: Snapshot versions need flat top-level groups (not a single wrapper) + // Mintlify breaks when non-default versioned docs use a single wrapper group. + test('snapshot version uses flat top-level groups', () => { + if (groups.length === 1 && groups[0].pages) { + const innerPages = collectPages(groups[0].pages); + if (innerPages.length > 2) { + throw new Error( + `Version "${version}" has a single wrapper group "${groups[0].group}" ` + + `containing ${innerPages.length} pages. Snapshot (dist/docs/) versions ` + + `must use flat top-level groups to avoid Mintlify routing failures.` + ); + } + } + }); + } + + log(''); +} + +// --- Summary --- +log('===================================='); +log(`Tests completed: ${totalTests}`); +if (passedTests > 0) log(`✅ Passed: ${passedTests}`, 'success'); +if (failedTests > 0) { + log(`❌ Failed: ${failedTests}`, 'error'); + process.exit(1); +} +log('\n🎉 All docs navigation tests passed!\n', 'success'); From a3137a0cc1d275f9cb7b3edadda1341b59f4d523 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Mon, 16 Mar 2026 18:39:48 -0400 Subject: [PATCH 6/6] fix: also flatten latest version nav, improve test coverage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The test caught that the "latest" version had the same Documentation wrapper bug as 2.5 — confirmed broken on the live site via vibium. Flatten the latest version's nav to use flat top-level groups. Improve docs-nav-validation.test.cjs per review feedback: - Check all non-default versions (not just dist/docs snapshots) - Detect wrapper groups by structural nesting, not page count - Add duplicate page reference detection - Add file extension detection in page paths - Remove dead collectGroups branch Co-Authored-By: Claude Opus 4.6 --- .changeset/b247ca1bb18ed028.md | 4 - .changeset/fix-versioned-docs-mintignore.md | 4 +- docs.json | 1204 +++++++++---------- tests/docs-nav-validation.test.cjs | 41 +- 4 files changed, 635 insertions(+), 618 deletions(-) delete mode 100644 .changeset/b247ca1bb18ed028.md diff --git a/.changeset/b247ca1bb18ed028.md b/.changeset/b247ca1bb18ed028.md deleted file mode 100644 index 9156318309..0000000000 --- a/.changeset/b247ca1bb18ed028.md +++ /dev/null @@ -1,4 +0,0 @@ ---- ---- - -Fix 404 on versioned 2.5.3 docs pages by removing incorrect Documentation wrapper group from nav config. diff --git a/.changeset/fix-versioned-docs-mintignore.md b/.changeset/fix-versioned-docs-mintignore.md index 6b7315dc35..cfc346af97 100644 --- a/.changeset/fix-versioned-docs-mintignore.md +++ b/.changeset/fix-versioned-docs-mintignore.md @@ -1,5 +1,4 @@ --- -"adcontextprotocol": patch --- fix: restore versioned docs and repair broken links @@ -7,4 +6,5 @@ fix: restore versioned docs and repair broken links Replaced blanket `dist/` in .mintignore with granular ignores so versioned doc snapshots (2.5.3, 3.0.0-rc.2, etc.) are served by Mintlify again. Fixed 18 broken internal links where list_creative_formats and sync_creatives moved from -media-buy/task-reference/ to creative/task-reference/ in v3. +media-buy/task-reference/ to creative/task-reference/ in v3. Removed incorrect +Documentation wrapper group from non-default version nav configs. diff --git a/docs.json b/docs.json index 01bcf83146..f5ec600ccc 100644 --- a/docs.json +++ b/docs.json @@ -69,425 +69,425 @@ { "group": "Documentation", "pages": [ - "docs/intro", - { - "group": "Building with AdCP", - "expanded": false, - "pages": [ - "docs/building/index", + "docs/intro", { - "group": "AdCP 3.0", + "group": "Building with AdCP", "expanded": false, "pages": [ - "docs/reference/whats-new-in-v3", - "docs/reference/migration/index", - "docs/reference/migration/channels", - "docs/reference/migration/pricing", - "docs/reference/migration/geo-targeting", - "docs/reference/migration/creatives", - "docs/reference/migration/catalogs", - "docs/reference/migration/optimization-goals", - "docs/reference/migration/brand-identity", - "docs/reference/migration/signals", - "docs/reference/migration/audiences", - "docs/reference/migration/attribution" - ] - }, - "docs/protocol/architecture", - { - "group": "Understanding AdCP", - "pages": [ - "docs/building/understanding/index", - "docs/building/understanding/protocol-comparison", - "docs/building/understanding/adcp-vs-openrtb" - ] - }, - "docs/building/schemas-and-sdks", - { - "group": "Foundations", - "pages": [ - "docs/building/integration/index", - "docs/building/integration/mcp-guide", - "docs/building/integration/a2a-guide", - "docs/building/integration/a2a-response-format", - "docs/protocol/get_adcp_capabilities", - "docs/building/integration/context-sessions", - "docs/building/integration/authentication", - "docs/building/integration/account-state", - "docs/building/integration/accounts-and-agents" + "docs/building/index", + { + "group": "AdCP 3.0", + "expanded": false, + "pages": [ + "docs/reference/whats-new-in-v3", + "docs/reference/migration/index", + "docs/reference/migration/channels", + "docs/reference/migration/pricing", + "docs/reference/migration/geo-targeting", + "docs/reference/migration/creatives", + "docs/reference/migration/catalogs", + "docs/reference/migration/optimization-goals", + "docs/reference/migration/brand-identity", + "docs/reference/migration/signals", + "docs/reference/migration/audiences", + "docs/reference/migration/attribution" + ] + }, + "docs/protocol/architecture", + { + "group": "Understanding AdCP", + "pages": [ + "docs/building/understanding/index", + "docs/building/understanding/protocol-comparison", + "docs/building/understanding/adcp-vs-openrtb" + ] + }, + "docs/building/schemas-and-sdks", + { + "group": "Foundations", + "pages": [ + "docs/building/integration/index", + "docs/building/integration/mcp-guide", + "docs/building/integration/a2a-guide", + "docs/building/integration/a2a-response-format", + "docs/protocol/get_adcp_capabilities", + "docs/building/integration/context-sessions", + "docs/building/integration/authentication", + "docs/building/integration/account-state", + "docs/building/integration/accounts-and-agents" + ] + }, + { + "group": "Implementation Patterns", + "expanded": false, + "pages": [ + "docs/building/implementation/index", + "docs/building/implementation/task-lifecycle", + "docs/building/implementation/async-operations", + "docs/building/implementation/webhooks", + "docs/building/implementation/orchestrator-design", + "docs/building/implementation/error-handling", + "docs/building/implementation/security" + ] + }, + { + "group": "Accounts", + "expanded": false, + "pages": [ + "docs/accounts/overview", + "docs/accounts/tasks/sync_accounts", + "docs/accounts/tasks/list_accounts", + "docs/accounts/tasks/report_usage", + "docs/accounts/tasks/get_account_financials" + ] + } ] }, { - "group": "Implementation Patterns", + "group": "Industry Guides", "expanded": false, "pages": [ - "docs/building/implementation/index", - "docs/building/implementation/task-lifecycle", - "docs/building/implementation/async-operations", - "docs/building/implementation/webhooks", - "docs/building/implementation/orchestrator-design", - "docs/building/implementation/error-handling", - "docs/building/implementation/security" + "docs/guides/index", + "docs/guides/buying-ai-media", + "docs/guides/commerce-media", + "docs/guides/ai-media", + "docs/guides/ai-media-networks", + "docs/guides/ai-media-buying", + "docs/guides/seller-integration", + "docs/guides/how-agents-communicate", + "docs/guides/signals-ecosystem", + "docs/guides/industry-landscape" ] }, { - "group": "Accounts", + "group": "Protocol", "expanded": false, "pages": [ - "docs/accounts/overview", - "docs/accounts/tasks/sync_accounts", - "docs/accounts/tasks/list_accounts", - "docs/accounts/tasks/report_usage", - "docs/accounts/tasks/get_account_financials" - ] - } - ] - }, - { - "group": "Industry Guides", - "expanded": false, - "pages": [ - "docs/guides/index", - "docs/guides/buying-ai-media", - "docs/guides/commerce-media", - "docs/guides/ai-media", - "docs/guides/ai-media-networks", - "docs/guides/ai-media-buying", - "docs/guides/seller-integration", - "docs/guides/how-agents-communicate", - "docs/guides/signals-ecosystem", - "docs/guides/industry-landscape" - ] - }, - { - "group": "Protocol", - "expanded": false, - "pages": [ - { - "group": "Media Buy", - "expanded": false, - "pages": [ - "docs/media-buy/index", - { - "group": "Concepts", - "pages": [ - "docs/media-buy/product-discovery/index", - "docs/media-buy/product-discovery/brief-expectations", - "docs/media-buy/product-discovery/example-briefs", - "docs/media-buy/product-discovery/media-products", - "docs/media-buy/product-discovery/shows-and-episodes", - "docs/media-buy/product-discovery/refinement", - "docs/media-buy/media-buys/index", - "docs/media-buy/media-buys/optimization-reporting", - "docs/media-buy/media-buys/policy-compliance", - "docs/media-buy/creatives/index", - "docs/media-buy/conversion-tracking/index", - "docs/media-buy/advanced-topics/pricing-models", - "docs/media-buy/advanced-topics/targeting" - ] - }, - { - "group": "Building", - "pages": [ - "docs/media-buy/capability-discovery/index", - "docs/media-buy/capability-discovery/implementing-standard-formats", - "docs/media-buy/advanced-topics/agentic-execution-engine", - "docs/media-buy/advanced-topics/accounts-and-security", - "docs/media-buy/advanced-topics/sandbox" + { + "group": "Media Buy", + "expanded": false, + "pages": [ + "docs/media-buy/index", + { + "group": "Concepts", + "pages": [ + "docs/media-buy/product-discovery/index", + "docs/media-buy/product-discovery/brief-expectations", + "docs/media-buy/product-discovery/example-briefs", + "docs/media-buy/product-discovery/media-products", + "docs/media-buy/product-discovery/shows-and-episodes", + "docs/media-buy/product-discovery/refinement", + "docs/media-buy/media-buys/index", + "docs/media-buy/media-buys/optimization-reporting", + "docs/media-buy/media-buys/policy-compliance", + "docs/media-buy/creatives/index", + "docs/media-buy/conversion-tracking/index", + "docs/media-buy/advanced-topics/pricing-models", + "docs/media-buy/advanced-topics/targeting" + ] + }, + { + "group": "Building", + "pages": [ + "docs/media-buy/capability-discovery/index", + "docs/media-buy/capability-discovery/implementing-standard-formats", + "docs/media-buy/advanced-topics/agentic-execution-engine", + "docs/media-buy/advanced-topics/accounts-and-security", + "docs/media-buy/advanced-topics/sandbox" + ] + }, + { + "group": "Reference", + "expanded": false, + "pages": [ + "docs/media-buy/specification", + "docs/media-buy/task-reference/index", + "docs/media-buy/task-reference/get_products", + "docs/media-buy/task-reference/create_media_buy", + "docs/media-buy/task-reference/sync_catalogs", + "docs/media-buy/task-reference/get_media_buys", + "docs/media-buy/task-reference/get_media_buy_delivery", + "docs/media-buy/task-reference/update_media_buy", + "docs/media-buy/task-reference/provide_performance_feedback", + "docs/media-buy/task-reference/sync_event_sources", + "docs/media-buy/task-reference/log_event", + "docs/media-buy/task-reference/sync_audiences" + ] + } + ] + }, + { + "group": "Creative", + "expanded": false, + "pages": [ + "docs/creative/index", + { + "group": "Concepts", + "pages": [ + "docs/creative/key-concepts", + "docs/creative/ai-creative-overview", + "docs/creative/generative-creative", + "docs/creative/creative-libraries", + "docs/creative/catalogs", + "docs/creative/catalog-schemas" + ] + }, + { + "group": "Building Creative Agents", + "pages": [ + "docs/creative/implementing-creative-agents", + "docs/creative/sales-agent-creative-capabilities", + "docs/creative/multi-agent-orchestration", + "docs/creative/creative-manifests", + "docs/creative/private-assets" + ] + }, + { + "group": "Formats and Assets", + "pages": [ + "docs/creative/formats", + "docs/creative/asset-types", + "docs/creative/template-format-ids", + "docs/creative/universal-macros" + ] + }, + { + "group": "Channel Guides", + "pages": [ + "docs/creative/channels/video", + "docs/creative/channels/ctv", + "docs/creative/channels/display", + "docs/creative/channels/audio", + "docs/creative/channels/dooh", + "docs/creative/channels/carousels", + "docs/creative/channels/social-native" + ] + }, + { + "group": "Compliance", + "pages": [ + "docs/creative/accessibility", + "docs/creative/provenance" + ] + }, + { + "group": "Sponsored Intelligence", + "expanded": false, + "pages": [ + "docs/sponsored-intelligence/overview", + "docs/sponsored-intelligence/implementing-si-agents", + "docs/sponsored-intelligence/implementing-si-hosts", + "docs/sponsored-intelligence/specification", + "docs/sponsored-intelligence/tasks/index", + "docs/sponsored-intelligence/tasks/si_get_offering", + "docs/sponsored-intelligence/tasks/si_initiate_session", + "docs/sponsored-intelligence/tasks/si_send_message", + "docs/sponsored-intelligence/tasks/si_terminate_session" + ] + }, + { + "group": "Reference", + "expanded": false, + "pages": [ + "docs/creative/specification", + "docs/creative/task-reference/build_creative", + "docs/creative/task-reference/preview_creative", + "docs/creative/task-reference/preview_creative-advanced", + "docs/creative/task-reference/list_creative_formats", + "docs/creative/task-reference/list_creatives", + "docs/creative/task-reference/sync_creatives", + "docs/creative/task-reference/get_creative_delivery" + ] + } + ] + }, + { + "group": "Governance", + "expanded": false, + "pages": [ + "docs/governance/overview", + "docs/governance/embedded-human-judgment", + "docs/governance/policy-registry", + { + "group": "Property Governance", + "pages": [ + "docs/governance/property/index", + "docs/governance/property/adagents", + "docs/governance/property/authorized-properties", + "docs/governance/property/specification", + { + "group": "Tasks", + "pages": [ + "docs/governance/property/tasks/index", + "docs/governance/property/tasks/property_lists", + "docs/governance/property/tasks/validate_property_delivery" + ] + } + ] + }, + { + "group": "Content Standards", + "pages": [ + "docs/governance/content-standards/index", + "docs/governance/content-standards/artifacts", + "docs/governance/content-standards/implementation-guide", + { + "group": "Tasks", + "pages": [ + "docs/governance/content-standards/tasks/list_content_standards", + "docs/governance/content-standards/tasks/get_content_standards", + "docs/governance/content-standards/tasks/create_content_standards", + "docs/governance/content-standards/tasks/update_content_standards", + "docs/governance/content-standards/tasks/calibrate_content", + "docs/governance/content-standards/tasks/get_media_buy_artifacts", + "docs/governance/content-standards/tasks/validate_content_delivery" + ] + } + ] + }, + { + "group": "Creative Governance", + "pages": [ + "docs/governance/creative/index", + "docs/governance/creative/get_creative_features", + "docs/governance/creative/provenance-verification" + ] + }, + { + "group": "Campaign Governance", + "pages": [ + "docs/governance/campaign/index", + "docs/governance/campaign/safety-model", + "docs/governance/campaign/specification", + { + "group": "Tasks", + "pages": [ + "docs/governance/campaign/tasks/index", + "docs/governance/campaign/tasks/sync_plans", + "docs/governance/campaign/tasks/report_plan_outcome", + "docs/governance/campaign/tasks/check_governance", + "docs/governance/campaign/tasks/get_plan_audit_logs" + ] + } + ] + } + ] + }, + { + "group": "Brand", + "expanded": false, + "pages": [ + "docs/brand-protocol/index", + "docs/brand-protocol/key-concepts", + "docs/brand-protocol/walkthrough-rights-licensing", + "docs/brand-protocol/for-advertisers", + "docs/brand-protocol/for-rights-holders", + "docs/brand-protocol/brand-json", + "docs/brand-protocol/building-a-brand-agent", + { + "group": "Tasks", + "pages": [ + "docs/brand-protocol/tasks/get_brand_identity", + "docs/brand-protocol/tasks/get_rights", + "docs/brand-protocol/tasks/acquire_rights", + "docs/brand-protocol/tasks/update_rights" + ] + } + ] + }, + { + "group": "Signals", + "expanded": false, + "pages": [ + "docs/signals/overview", + "docs/signals/key-concepts", + "docs/signals/data-providers", + { + "group": "Reference", + "expanded": false, + "pages": [ + "docs/signals/specification", + "docs/signals/tasks/get_signals", + "docs/signals/tasks/activate_signal" + ] + } + ] + } ] }, + "docs/faq", { "group": "Reference", "expanded": false, "pages": [ - "docs/media-buy/specification", - "docs/media-buy/task-reference/index", - "docs/media-buy/task-reference/get_products", - "docs/media-buy/task-reference/create_media_buy", - "docs/media-buy/task-reference/sync_catalogs", - "docs/media-buy/task-reference/get_media_buys", - "docs/media-buy/task-reference/get_media_buy_delivery", - "docs/media-buy/task-reference/update_media_buy", - "docs/media-buy/task-reference/provide_performance_feedback", - "docs/media-buy/task-reference/sync_event_sources", - "docs/media-buy/task-reference/log_event", - "docs/media-buy/task-reference/sync_audiences" - ] - } - ] - }, - { - "group": "Creative", - "expanded": false, - "pages": [ - "docs/creative/index", - { - "group": "Concepts", - "pages": [ - "docs/creative/key-concepts", - "docs/creative/ai-creative-overview", - "docs/creative/generative-creative", - "docs/creative/creative-libraries", - "docs/creative/catalogs", - "docs/creative/catalog-schemas" - ] - }, - { - "group": "Building Creative Agents", - "pages": [ - "docs/creative/implementing-creative-agents", - "docs/creative/sales-agent-creative-capabilities", - "docs/creative/multi-agent-orchestration", - "docs/creative/creative-manifests", - "docs/creative/private-assets" - ] - }, - { - "group": "Formats and Assets", - "pages": [ - "docs/creative/formats", - "docs/creative/asset-types", - "docs/creative/template-format-ids", - "docs/creative/universal-macros" - ] - }, - { - "group": "Channel Guides", - "pages": [ - "docs/creative/channels/video", - "docs/creative/channels/ctv", - "docs/creative/channels/display", - "docs/creative/channels/audio", - "docs/creative/channels/dooh", - "docs/creative/channels/carousels", - "docs/creative/channels/social-native" - ] - }, - { - "group": "Compliance", - "pages": [ - "docs/creative/accessibility", - "docs/creative/provenance" - ] - }, - { - "group": "Sponsored Intelligence", - "expanded": false, - "pages": [ - "docs/sponsored-intelligence/overview", - "docs/sponsored-intelligence/implementing-si-agents", - "docs/sponsored-intelligence/implementing-si-hosts", - "docs/sponsored-intelligence/specification", - "docs/sponsored-intelligence/tasks/index", - "docs/sponsored-intelligence/tasks/si_get_offering", - "docs/sponsored-intelligence/tasks/si_initiate_session", - "docs/sponsored-intelligence/tasks/si_send_message", - "docs/sponsored-intelligence/tasks/si_terminate_session" + { + "group": "Registry API", + "openapi": { + "source": "static/openapi/registry.yaml", + "directory": "docs/registry/api-reference" + }, + "pages": [ + "docs/registry/index" + ] + }, + "docs/reference/gmsf-reference", + "docs/reference/media-channel-taxonomy", + "docs/reference/roadmap", + "docs/reference/release-notes", + "docs/reference/changelog", + "docs/reference/implementor-faq", + "docs/reference/glossary", + "docs/community/working-group" ] }, { - "group": "Reference", + "group": "Certification", "expanded": false, "pages": [ - "docs/creative/specification", - "docs/creative/task-reference/build_creative", - "docs/creative/task-reference/preview_creative", - "docs/creative/task-reference/preview_creative-advanced", - "docs/creative/task-reference/list_creative_formats", - "docs/creative/task-reference/list_creatives", - "docs/creative/task-reference/sync_creatives", - "docs/creative/task-reference/get_creative_delivery" - ] - } - ] - }, - { - "group": "Governance", - "expanded": false, - "pages": [ - "docs/governance/overview", - "docs/governance/embedded-human-judgment", - "docs/governance/policy-registry", - { - "group": "Property Governance", - "pages": [ - "docs/governance/property/index", - "docs/governance/property/adagents", - "docs/governance/property/authorized-properties", - "docs/governance/property/specification", + "docs/learning/overview", + "docs/learning/instructional-design", { - "group": "Tasks", + "group": "Basics (free)", "pages": [ - "docs/governance/property/tasks/index", - "docs/governance/property/tasks/property_lists", - "docs/governance/property/tasks/validate_property_delivery" + "docs/learning/foundations/a1-agentic-advertising", + "docs/learning/foundations/a2-protocol-architecture", + "docs/learning/foundations/a3-ecosystem-governance" ] - } - ] - }, - { - "group": "Content Standards", - "pages": [ - "docs/governance/content-standards/index", - "docs/governance/content-standards/artifacts", - "docs/governance/content-standards/implementation-guide", + }, { - "group": "Tasks", + "group": "Role tracks", "pages": [ - "docs/governance/content-standards/tasks/list_content_standards", - "docs/governance/content-standards/tasks/get_content_standards", - "docs/governance/content-standards/tasks/create_content_standards", - "docs/governance/content-standards/tasks/update_content_standards", - "docs/governance/content-standards/tasks/calibrate_content", - "docs/governance/content-standards/tasks/get_media_buy_artifacts", - "docs/governance/content-standards/tasks/validate_content_delivery" + "docs/learning/tracks/publisher", + "docs/learning/tracks/buyer", + "docs/learning/tracks/platform" ] - } - ] - }, - { - "group": "Creative Governance", - "pages": [ - "docs/governance/creative/index", - "docs/governance/creative/get_creative_features", - "docs/governance/creative/provenance-verification" - ] - }, - { - "group": "Campaign Governance", - "pages": [ - "docs/governance/campaign/index", - "docs/governance/campaign/safety-model", - "docs/governance/campaign/specification", + }, { - "group": "Tasks", + "group": "Specialist modules", "pages": [ - "docs/governance/campaign/tasks/index", - "docs/governance/campaign/tasks/sync_plans", - "docs/governance/campaign/tasks/report_plan_outcome", - "docs/governance/campaign/tasks/check_governance", - "docs/governance/campaign/tasks/get_plan_audit_logs" + "docs/learning/specialist/media-buy", + "docs/learning/specialist/creative", + "docs/learning/specialist/signals", + "docs/learning/specialist/governance", + "docs/learning/specialist/sponsored-intelligence" + ] + }, + { + "group": "Policies", + "expanded": false, + "pages": [ + "docs/learning/policies/nondiscrimination", + "docs/learning/policies/learner-records", + "docs/learning/policies/complaints", + "docs/learning/policies/conflict-of-interest", + "docs/learning/policies/intellectual-property", + "docs/learning/policies/personnel-qualifications", + "docs/learning/policies/refund" ] } ] } ] - }, - { - "group": "Brand", - "expanded": false, - "pages": [ - "docs/brand-protocol/index", - "docs/brand-protocol/key-concepts", - "docs/brand-protocol/walkthrough-rights-licensing", - "docs/brand-protocol/for-advertisers", - "docs/brand-protocol/for-rights-holders", - "docs/brand-protocol/brand-json", - "docs/brand-protocol/building-a-brand-agent", - { - "group": "Tasks", - "pages": [ - "docs/brand-protocol/tasks/get_brand_identity", - "docs/brand-protocol/tasks/get_rights", - "docs/brand-protocol/tasks/acquire_rights", - "docs/brand-protocol/tasks/update_rights" - ] - } - ] - }, - { - "group": "Signals", - "expanded": false, - "pages": [ - "docs/signals/overview", - "docs/signals/key-concepts", - "docs/signals/data-providers", - { - "group": "Reference", - "expanded": false, - "pages": [ - "docs/signals/specification", - "docs/signals/tasks/get_signals", - "docs/signals/tasks/activate_signal" - ] - } - ] - } - ] - }, - "docs/faq", - { - "group": "Reference", - "expanded": false, - "pages": [ - { - "group": "Registry API", - "openapi": { - "source": "static/openapi/registry.yaml", - "directory": "docs/registry/api-reference" - }, - "pages": [ - "docs/registry/index" - ] - }, - "docs/reference/gmsf-reference", - "docs/reference/media-channel-taxonomy", - "docs/reference/roadmap", - "docs/reference/release-notes", - "docs/reference/changelog", - "docs/reference/implementor-faq", - "docs/reference/glossary", - "docs/community/working-group" - ] - }, - { - "group": "Certification", - "expanded": false, - "pages": [ - "docs/learning/overview", - "docs/learning/instructional-design", - { - "group": "Basics (free)", - "pages": [ - "docs/learning/foundations/a1-agentic-advertising", - "docs/learning/foundations/a2-protocol-architecture", - "docs/learning/foundations/a3-ecosystem-governance" - ] - }, - { - "group": "Role tracks", - "pages": [ - "docs/learning/tracks/publisher", - "docs/learning/tracks/buyer", - "docs/learning/tracks/platform" - ] - }, - { - "group": "Specialist modules", - "pages": [ - "docs/learning/specialist/media-buy", - "docs/learning/specialist/creative", - "docs/learning/specialist/signals", - "docs/learning/specialist/governance", - "docs/learning/specialist/sponsored-intelligence" - ] - }, - { - "group": "Policies", - "expanded": false, - "pages": [ - "docs/learning/policies/nondiscrimination", - "docs/learning/policies/learner-records", - "docs/learning/policies/complaints", - "docs/learning/policies/conflict-of-interest", - "docs/learning/policies/intellectual-property", - "docs/learning/policies/personnel-qualifications", - "docs/learning/policies/refund" - ] - } - ] - } - ] } ] }, @@ -495,9 +495,11 @@ "version": "latest", "groups": [ { - "group": "Documentation", + "group": "Getting Started", "pages": [ - "docs/intro", + "docs/intro" + ] + }, { "group": "Building with AdCP", "expanded": false, @@ -591,210 +593,252 @@ "group": "Protocol", "expanded": false, "pages": [ - { - "group": "Media Buy", - "expanded": false, - "pages": [ - "docs/media-buy/index", - { - "group": "Concepts", - "pages": [ - "docs/media-buy/product-discovery/index", - "docs/media-buy/product-discovery/brief-expectations", - "docs/media-buy/product-discovery/example-briefs", - "docs/media-buy/product-discovery/media-products", - "docs/media-buy/product-discovery/shows-and-episodes", - "docs/media-buy/product-discovery/refinement", - "docs/media-buy/media-buys/index", - "docs/media-buy/media-buys/optimization-reporting", - "docs/media-buy/media-buys/policy-compliance", - "docs/media-buy/creatives/index", - "docs/media-buy/conversion-tracking/index", - "docs/media-buy/advanced-topics/pricing-models", - "docs/media-buy/advanced-topics/targeting" - ] - }, - { - "group": "Building", - "pages": [ - "docs/media-buy/capability-discovery/index", - "docs/media-buy/capability-discovery/implementing-standard-formats", - "docs/media-buy/advanced-topics/agentic-execution-engine", - "docs/media-buy/advanced-topics/accounts-and-security", - "docs/media-buy/advanced-topics/sandbox" - ] - }, { - "group": "Reference", + "group": "Media Buy", "expanded": false, "pages": [ - "docs/media-buy/specification", - "docs/media-buy/task-reference/index", - "docs/media-buy/task-reference/get_products", - "docs/media-buy/task-reference/create_media_buy", - "docs/media-buy/task-reference/sync_catalogs", - "docs/media-buy/task-reference/get_media_buys", - "docs/media-buy/task-reference/get_media_buy_delivery", - "docs/media-buy/task-reference/update_media_buy", - "docs/media-buy/task-reference/provide_performance_feedback", - "docs/media-buy/task-reference/sync_event_sources", - "docs/media-buy/task-reference/log_event", - "docs/media-buy/task-reference/sync_audiences" - ] - } - ] - }, - { - "group": "Creative", - "expanded": false, - "pages": [ - "docs/creative/index", - { - "group": "Concepts", - "pages": [ - "docs/creative/key-concepts", - "docs/creative/ai-creative-overview", - "docs/creative/generative-creative", - "docs/creative/creative-libraries", - "docs/creative/catalogs", - "docs/creative/catalog-schemas" - ] - }, - { - "group": "Building Creative Agents", - "pages": [ - "docs/creative/implementing-creative-agents", - "docs/creative/sales-agent-creative-capabilities", - "docs/creative/multi-agent-orchestration", - "docs/creative/creative-manifests", - "docs/creative/private-assets" - ] - }, - { - "group": "Formats and Assets", - "pages": [ - "docs/creative/formats", - "docs/creative/asset-types", - "docs/creative/template-format-ids", - "docs/creative/universal-macros" - ] - }, - { - "group": "Channel Guides", - "pages": [ - "docs/creative/channels/video", - "docs/creative/channels/ctv", - "docs/creative/channels/display", - "docs/creative/channels/audio", - "docs/creative/channels/dooh", - "docs/creative/channels/carousels", - "docs/creative/channels/social-native" - ] - }, - { - "group": "Compliance", - "pages": [ - "docs/creative/accessibility", - "docs/creative/provenance" + "docs/media-buy/index", + { + "group": "Concepts", + "pages": [ + "docs/media-buy/product-discovery/index", + "docs/media-buy/product-discovery/brief-expectations", + "docs/media-buy/product-discovery/example-briefs", + "docs/media-buy/product-discovery/media-products", + "docs/media-buy/product-discovery/shows-and-episodes", + "docs/media-buy/product-discovery/refinement", + "docs/media-buy/media-buys/index", + "docs/media-buy/media-buys/optimization-reporting", + "docs/media-buy/media-buys/policy-compliance", + "docs/media-buy/creatives/index", + "docs/media-buy/conversion-tracking/index", + "docs/media-buy/advanced-topics/pricing-models", + "docs/media-buy/advanced-topics/targeting" + ] + }, + { + "group": "Building", + "pages": [ + "docs/media-buy/capability-discovery/index", + "docs/media-buy/capability-discovery/implementing-standard-formats", + "docs/media-buy/advanced-topics/agentic-execution-engine", + "docs/media-buy/advanced-topics/accounts-and-security", + "docs/media-buy/advanced-topics/sandbox" + ] + }, + { + "group": "Reference", + "expanded": false, + "pages": [ + "docs/media-buy/specification", + "docs/media-buy/task-reference/index", + "docs/media-buy/task-reference/get_products", + "docs/media-buy/task-reference/create_media_buy", + "docs/media-buy/task-reference/sync_catalogs", + "docs/media-buy/task-reference/get_media_buys", + "docs/media-buy/task-reference/get_media_buy_delivery", + "docs/media-buy/task-reference/update_media_buy", + "docs/media-buy/task-reference/provide_performance_feedback", + "docs/media-buy/task-reference/sync_event_sources", + "docs/media-buy/task-reference/log_event", + "docs/media-buy/task-reference/sync_audiences" + ] + } ] }, { - "group": "Sponsored Intelligence", + "group": "Creative", "expanded": false, "pages": [ - "docs/sponsored-intelligence/overview", - "docs/sponsored-intelligence/implementing-si-agents", - "docs/sponsored-intelligence/implementing-si-hosts", - "docs/sponsored-intelligence/specification", - "docs/sponsored-intelligence/tasks/index", - "docs/sponsored-intelligence/tasks/si_get_offering", - "docs/sponsored-intelligence/tasks/si_initiate_session", - "docs/sponsored-intelligence/tasks/si_send_message", - "docs/sponsored-intelligence/tasks/si_terminate_session" + "docs/creative/index", + { + "group": "Concepts", + "pages": [ + "docs/creative/key-concepts", + "docs/creative/ai-creative-overview", + "docs/creative/generative-creative", + "docs/creative/creative-libraries", + "docs/creative/catalogs", + "docs/creative/catalog-schemas" + ] + }, + { + "group": "Building Creative Agents", + "pages": [ + "docs/creative/implementing-creative-agents", + "docs/creative/sales-agent-creative-capabilities", + "docs/creative/multi-agent-orchestration", + "docs/creative/creative-manifests", + "docs/creative/private-assets" + ] + }, + { + "group": "Formats and Assets", + "pages": [ + "docs/creative/formats", + "docs/creative/asset-types", + "docs/creative/template-format-ids", + "docs/creative/universal-macros" + ] + }, + { + "group": "Channel Guides", + "pages": [ + "docs/creative/channels/video", + "docs/creative/channels/ctv", + "docs/creative/channels/display", + "docs/creative/channels/audio", + "docs/creative/channels/dooh", + "docs/creative/channels/carousels", + "docs/creative/channels/social-native" + ] + }, + { + "group": "Compliance", + "pages": [ + "docs/creative/accessibility", + "docs/creative/provenance" + ] + }, + { + "group": "Sponsored Intelligence", + "expanded": false, + "pages": [ + "docs/sponsored-intelligence/overview", + "docs/sponsored-intelligence/implementing-si-agents", + "docs/sponsored-intelligence/implementing-si-hosts", + "docs/sponsored-intelligence/specification", + "docs/sponsored-intelligence/tasks/index", + "docs/sponsored-intelligence/tasks/si_get_offering", + "docs/sponsored-intelligence/tasks/si_initiate_session", + "docs/sponsored-intelligence/tasks/si_send_message", + "docs/sponsored-intelligence/tasks/si_terminate_session" + ] + }, + { + "group": "Reference", + "expanded": false, + "pages": [ + "docs/creative/specification", + "docs/creative/task-reference/build_creative", + "docs/creative/task-reference/preview_creative", + "docs/creative/task-reference/preview_creative-advanced", + "docs/creative/task-reference/list_creative_formats", + "docs/creative/task-reference/list_creatives", + "docs/creative/task-reference/sync_creatives", + "docs/creative/task-reference/get_creative_delivery" + ] + } ] }, { - "group": "Reference", + "group": "Governance", "expanded": false, "pages": [ - "docs/creative/specification", - "docs/creative/task-reference/build_creative", - "docs/creative/task-reference/preview_creative", - "docs/creative/task-reference/preview_creative-advanced", - "docs/creative/task-reference/list_creative_formats", - "docs/creative/task-reference/list_creatives", - "docs/creative/task-reference/sync_creatives", - "docs/creative/task-reference/get_creative_delivery" - ] - } - ] - }, - { - "group": "Governance", - "expanded": false, - "pages": [ - "docs/governance/overview", - "docs/governance/embedded-human-judgment", - "docs/governance/policy-registry", - { - "group": "Property Governance", - "pages": [ - "docs/governance/property/index", - "docs/governance/property/adagents", - "docs/governance/property/authorized-properties", - "docs/governance/property/specification", + "docs/governance/overview", + "docs/governance/embedded-human-judgment", + "docs/governance/policy-registry", { - "group": "Tasks", + "group": "Property Governance", + "pages": [ + "docs/governance/property/index", + "docs/governance/property/adagents", + "docs/governance/property/authorized-properties", + "docs/governance/property/specification", + { + "group": "Tasks", + "pages": [ + "docs/governance/property/tasks/index", + "docs/governance/property/tasks/property_lists", + "docs/governance/property/tasks/validate_property_delivery" + ] + } + ] + }, + { + "group": "Content Standards", + "pages": [ + "docs/governance/content-standards/index", + "docs/governance/content-standards/artifacts", + "docs/governance/content-standards/implementation-guide", + { + "group": "Tasks", + "pages": [ + "docs/governance/content-standards/tasks/list_content_standards", + "docs/governance/content-standards/tasks/get_content_standards", + "docs/governance/content-standards/tasks/create_content_standards", + "docs/governance/content-standards/tasks/update_content_standards", + "docs/governance/content-standards/tasks/calibrate_content", + "docs/governance/content-standards/tasks/get_media_buy_artifacts", + "docs/governance/content-standards/tasks/validate_content_delivery" + ] + } + ] + }, + { + "group": "Creative Governance", + "pages": [ + "docs/governance/creative/index", + "docs/governance/creative/get_creative_features", + "docs/governance/creative/provenance-verification" + ] + }, + { + "group": "Campaign Governance", "pages": [ - "docs/governance/property/tasks/index", - "docs/governance/property/tasks/property_lists", - "docs/governance/property/tasks/validate_property_delivery" + "docs/governance/campaign/index", + "docs/governance/campaign/safety-model", + "docs/governance/campaign/specification", + { + "group": "Tasks", + "pages": [ + "docs/governance/campaign/tasks/index", + "docs/governance/campaign/tasks/sync_plans", + "docs/governance/campaign/tasks/report_plan_outcome", + "docs/governance/campaign/tasks/check_governance", + "docs/governance/campaign/tasks/get_plan_audit_logs" + ] + } ] } ] }, { - "group": "Content Standards", + "group": "Brand", + "expanded": false, "pages": [ - "docs/governance/content-standards/index", - "docs/governance/content-standards/artifacts", - "docs/governance/content-standards/implementation-guide", + "docs/brand-protocol/index", + "docs/brand-protocol/key-concepts", + "docs/brand-protocol/walkthrough-rights-licensing", + "docs/brand-protocol/for-advertisers", + "docs/brand-protocol/for-rights-holders", + "docs/brand-protocol/brand-json", + "docs/brand-protocol/building-a-brand-agent", { "group": "Tasks", "pages": [ - "docs/governance/content-standards/tasks/list_content_standards", - "docs/governance/content-standards/tasks/get_content_standards", - "docs/governance/content-standards/tasks/create_content_standards", - "docs/governance/content-standards/tasks/update_content_standards", - "docs/governance/content-standards/tasks/calibrate_content", - "docs/governance/content-standards/tasks/get_media_buy_artifacts", - "docs/governance/content-standards/tasks/validate_content_delivery" + "docs/brand-protocol/tasks/get_brand_identity", + "docs/brand-protocol/tasks/get_rights", + "docs/brand-protocol/tasks/acquire_rights", + "docs/brand-protocol/tasks/update_rights" ] } ] }, { - "group": "Creative Governance", - "pages": [ - "docs/governance/creative/index", - "docs/governance/creative/get_creative_features", - "docs/governance/creative/provenance-verification" - ] - }, - { - "group": "Campaign Governance", + "group": "Signals", + "expanded": false, "pages": [ - "docs/governance/campaign/index", - "docs/governance/campaign/safety-model", - "docs/governance/campaign/specification", + "docs/signals/overview", + "docs/signals/key-concepts", + "docs/signals/data-providers", { - "group": "Tasks", + "group": "Reference", + "expanded": false, "pages": [ - "docs/governance/campaign/tasks/index", - "docs/governance/campaign/tasks/sync_plans", - "docs/governance/campaign/tasks/report_plan_outcome", - "docs/governance/campaign/tasks/check_governance", - "docs/governance/campaign/tasks/get_plan_audit_logs" + "docs/signals/specification", + "docs/signals/tasks/get_signals", + "docs/signals/tasks/activate_signal" ] } ] @@ -802,48 +846,11 @@ ] }, { - "group": "Brand", - "expanded": false, + "group": "FAQ", "pages": [ - "docs/brand-protocol/index", - "docs/brand-protocol/key-concepts", - "docs/brand-protocol/walkthrough-rights-licensing", - "docs/brand-protocol/for-advertisers", - "docs/brand-protocol/for-rights-holders", - "docs/brand-protocol/brand-json", - "docs/brand-protocol/building-a-brand-agent", - { - "group": "Tasks", - "pages": [ - "docs/brand-protocol/tasks/get_brand_identity", - "docs/brand-protocol/tasks/get_rights", - "docs/brand-protocol/tasks/acquire_rights", - "docs/brand-protocol/tasks/update_rights" - ] - } + "docs/faq" ] }, - { - "group": "Signals", - "expanded": false, - "pages": [ - "docs/signals/overview", - "docs/signals/key-concepts", - "docs/signals/data-providers", - { - "group": "Reference", - "expanded": false, - "pages": [ - "docs/signals/specification", - "docs/signals/tasks/get_signals", - "docs/signals/tasks/activate_signal" - ] - } - ] - } - ] - }, - "docs/faq", { "group": "Reference", "expanded": false, @@ -915,16 +922,11 @@ } ] } - ] - } ] }, { "version": "2.5", "groups": [ - { - "group": "Documentation", - "pages": [ { "group": "Getting Started", "expanded": false, @@ -1106,8 +1108,6 @@ "dist/docs/2.5.3/community/working-group" ] } - ] - } ] } ] diff --git a/tests/docs-nav-validation.test.cjs b/tests/docs-nav-validation.test.cjs index bcb4679911..c729693753 100644 --- a/tests/docs-nav-validation.test.cjs +++ b/tests/docs-nav-validation.test.cjs @@ -57,7 +57,6 @@ function collectGroups(node) { } else if (node && typeof node === 'object') { if (node.group) groups.push(node); if (node.pages) groups.push(...collectGroups(node.pages)); - if (node.groups) groups.push(...collectGroups(node.groups)); } return groups; } @@ -76,6 +75,7 @@ if (!navigation || !navigation.versions) { } const rootDir = path.join(__dirname, '..'); +const defaultVersion = navigation.default; for (const versionEntry of navigation.versions) { const { version, groups } = versionEntry; @@ -95,7 +95,7 @@ for (const versionEntry of navigation.versions) { } } if (missing.length > 0) { - throw new Error(`Missing files:\n ${missing.slice(0, 10).join('\n ')}${missing.length > 10 ? `\n ... and ${missing.length - 10} more` : ''}`); + throw new Error(`Missing files:\n ${missing.join('\n ')}`); } }); @@ -110,7 +110,24 @@ for (const versionEntry of navigation.versions) { } }); - // Test 3: Versioned (dist/docs/) pages must have consistent version prefix + // Test 3: No duplicate page references + test('no duplicate page references', () => { + const seen = new Set(); + const dupes = allPages.filter(p => seen.has(p) || !seen.add(p)); + if (dupes.length > 0) { + throw new Error(`Duplicate pages: ${dupes.join(', ')}`); + } + }); + + // Test 4: Page paths should not contain file extensions + test('page paths have no file extensions', () => { + const withExt = allPages.filter(p => /\.(mdx?|json|ya?ml)$/.test(p)); + if (withExt.length > 0) { + throw new Error(`Page paths should not include file extensions: ${withExt.join(', ')}`); + } + }); + + // Test 5: Versioned (dist/docs/) pages must have consistent version prefix const distPages = allPages.filter(p => p.startsWith('dist/docs/')); if (distPages.length > 0) { test('dist/docs pages share a consistent version prefix', () => { @@ -122,17 +139,21 @@ for (const versionEntry of navigation.versions) { throw new Error(`Mixed version prefixes: ${[...prefixes].join(', ')}`); } }); + } - // Test 4: Snapshot versions need flat top-level groups (not a single wrapper) - // Mintlify breaks when non-default versioned docs use a single wrapper group. - test('snapshot version uses flat top-level groups', () => { + // Test 6: Non-default versions must not use a single wrapper group containing sub-groups. + // Mintlify breaks routing when non-default versions nest all groups inside a wrapper. + if (version !== defaultVersion) { + test('non-default version uses flat top-level groups', () => { if (groups.length === 1 && groups[0].pages) { - const innerPages = collectPages(groups[0].pages); - if (innerPages.length > 2) { + const hasNestedGroups = groups[0].pages.some( + p => p && typeof p === 'object' && p.group + ); + if (hasNestedGroups) { throw new Error( `Version "${version}" has a single wrapper group "${groups[0].group}" ` + - `containing ${innerPages.length} pages. Snapshot (dist/docs/) versions ` + - `must use flat top-level groups to avoid Mintlify routing failures.` + `containing nested sub-groups. Non-default versions must use flat ` + + `top-level groups to avoid Mintlify routing failures.` ); } }