feat: add generative creative support to sync_creatives

CLAUDE.md

@@ -284,6 +284,37 @@ For major version changes:
 
 **Schema Validation**: All schemas must follow this convention. Tests will fail if format fields don't match the expected naming pattern.
 
+### Format ID Structure
+
+**CRITICAL**: Format IDs are structured objects, not strings, to avoid parsing issues and provide clear namespacing.
+
+**Structured Format ID**:
+```json
+{
+  "agent_url": "https://creatives.adcontextprotocol.org",
+  "id": "display_300x250"
+}
+```
+
+**When to use structured format IDs**:
+- **Request parameters** that accept a format ID (e.g., `target_format_id` in `build_creative`)
+- **Creative asset objects** that specify which format they conform to
+- Anywhere a format is being **referenced for action**
+
+**When to use string format IDs**:
+- **Product responses** listing supported formats (for compactness)
+- **Format definition objects** themselves (they have separate `format_id` and `agent_url` fields)
+- Lists where verbosity is a concern
+
+**Schema reference**:
+```json
+{
+  "target_format_id": {
+    "$ref": "/schemas/v1/core/format-id.json"
+  }
+}
+```
+
 ## Common Tasks
 
 ### Before Making Changes

docs/creative/formats.md

@@ -82,6 +82,37 @@ The creative agent at that URL is the definitive source for:
 
 Buyers query the agent_url for full format details, validation, and preview capabilities.
 
+## Referencing Formats
+
+When referencing a format in API requests (e.g., in `sync_creatives`, `build_creative`), use a structured format ID object that combines the agent URL and format identifier:
+
+```json
+{
+  "format_id": {
+    "agent_url": "https://creative.adcontextprotocol.org",
+    "id": "display_300x250"
+  }
+}
+```
+
+**Why structured objects?**
+- **No parsing needed**: Components are explicit
+- **Unambiguous**: Clear separation of namespace and identifier
+- **Extensible**: Can add version or other metadata later
+- **Validation-friendly**: Easy to validate with JSON Schema
+
+**When formats are referenced as strings:**
+In some contexts like product responses, format IDs appear as simple strings for compactness:
+
+```json
+{
+  "product_id": "ctv_premium",
+  "format_ids": ["video_30s_hosted", "video_15s_hosted"]
+}
+```
+
+These strings are shorthand references. To get the full format specification, use `list_creative_formats` which returns the complete format objects with `agent_url` and all details.
+
 ## Format Structure
 
 Formats are JSON objects with the following key fields:

docs/creative/generative-creative.md

@@ -12,7 +12,7 @@ The Creative Protocol provides AI-powered creative generation:
 - **`preview_creative`**: Generate previews of creative manifests
 - **`list_creative_formats`**: Discover supported creative formats
 
-Assets are provided via [Brand Card](../reference/brand-card) - no separate asset library management needed.
+Assets are provided via [Brand Manifest](../reference/brand-manifest) - no separate asset library management needed.
 
 ## Quick Start: Generate Your First Creative
 
@@ -81,15 +81,15 @@ Use the `context_id` to make improvements:
 
 ## Common Patterns
 
-### Using Brand Cards
+### Using Brand Manifests
 
 Provide brand context for better creative generation:
 
 ```json
 {
   "message": "Create a display ad for our coffee shop promotion",
   "format_id": "display_300x250",
-  "brand_card": {
+  "brand_manifest": {
     "url": "https://mycoffeeshop.com",
     "name": "Brew & Co",
     "colors": {
@@ -102,19 +102,19 @@ Provide brand context for better creative generation:
 }
 ```
 
-**Minimal Brand Card**: Start with just a URL for low-friction creative generation:
+**Minimal Brand Manifest**: Start with just a URL for low-friction creative generation:
 
 ```json
 {
   "message": "Create a coffee shop ad",
   "format_id": "display_native",
-  "brand_card": {
+  "brand_manifest": {
     "url": "https://mycoffeeshop.com"
   }
 }
 ```
 
-See [Brand Card Reference](../reference/brand-card) for comprehensive examples.
+See [Brand Manifest Reference](../reference/brand-manifest) for comprehensive examples.
 
 ### Using Your Own Assets
 
@@ -124,7 +124,7 @@ Provide existing assets to incorporate into the creative:
 {
   "message": "Create a display ad featuring our signature latte",
   "format_id": "display_300x250",
-  "brand_card": {
+  "brand_manifest": {
     "url": "https://mycoffeeshop.com"
   },
   "assets": [
@@ -191,12 +191,12 @@ If you get a format error, the publisher may not support that format. Try:
 ### Creative Quality Issues
 To improve creative output:
 1. Be more specific in your message: "Create a minimalist coffee ad with earth tones"
-2. Provide comprehensive brand card with assets and guidelines
+2. Provide comprehensive brand manifest with assets and guidelines
 3. Use the conversational refinement feature to iterate (via `context_id`)
 
 ### Asset Management
-Assets are provided via [Brand Card](../reference/brand-card):
-1. Include assets in brand card with descriptive tags
+Assets are provided via [Brand Manifest](../reference/brand-manifest):
+1. Include assets in brand manifest with descriptive tags
 2. Use `asset_filters` in requests to select specific assets
 3. Reference product catalogs for large inventories
 

docs/creative/task-reference/build_creative.md

@@ -7,43 +7,18 @@ sidebar_position: 13
 
 Build creative content for a specific format using a creative agent that can generate either a creative manifest (static mode) or executable code (dynamic mode). This tool supports conversational refinement through a series of messages.
 
-## Format Lookup
-
-Creative agents need to understand format requirements to generate appropriate creatives. The format lookup process works as follows:
-
-1. **Standard AdCP Formats**: If `format_source` is omitted or null, the `format_id` refers to a standard AdCP format (e.g., "display_native", "video_standard_30s")
-
-2. **Publisher-Specific Formats**: If `format_source` is provided, the creative agent calls `list_creative_formats` on that sales agent URL to discover the format definition
-
-3. **Format Discovery**: Sales agents should make `list_creative_formats` accessible without authentication for creative agents to discover format requirements
-
-### Format Source Examples
-
-```json
-// Standard AdCP format
-{
-  "format_id": "display_native"
-  // format_source omitted = standard format
-}
-
-// Publisher-specific format
-{
-  "format_id": "premium_video_30s",
-  "format_source": "https://publisher.com/.well-known/adcp/sales"
-}
-```
+For information about format IDs and how to reference formats, see [Creative Formats - Referencing Formats](../formats.md#referencing-formats).
 
 ## Request Parameters
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `message` | string | Yes | The request message (initial brief or refinement instructions) |
-| `format_source` | string | No | Source URL for format lookup (sales agent URL). If null/omitted, assumes standard AdCP format |
-| `format_id` | string | Yes | Format identifier to look up from the format source |
+| `source_format_id` | object | No | Format ID of existing creative to transform (optional - omit when creating from scratch). Object with `agent_url` and `id` fields. |
+| `target_format_id` | object | Yes | Format ID to generate. Object with `agent_url` and `id` fields. The format definition specifies whether output is manifest-based or code-based. |
 | `context_id` | string | No | Session context from previous message for continuity |
-| `brand_card` | BrandCard | No | Brand information manifest for creative generation context. See [Brand Card](../../reference/brand-card) for details. Replaces legacy `brand_guidelines`. |
+| `brand_manifest` | BrandManifest | No | Brand information manifest containing all assets, themes, and information necessary to ensure creatives are aligned with the brand's goals and that the publisher is comfortable with what's being advertised. See [Brand Manifest](../../reference/brand-manifest) for details. |
 | `assets` | array | No | References to asset libraries and specific assets |
-| `output_mode` | string | No | `"manifest"` for creative manifest or `"code"` for executable (default: `"manifest"`) |
 | `preview_options` | object | No | Options for generating preview |
 | `finalize` | boolean | No | Set to true to finalize the creative (default: false) |
 
@@ -105,11 +80,16 @@ Creative agents need to understand format requirements to generate appropriate c
 
 ### Creative Output Formats
 
-#### Manifest Mode (Static Creative)
+The format definition determines whether the output is a creative manifest (asset-based) or executable code (dynamic). Both types are shown below.
+
+#### Creative Manifest (Asset-Based)
 ```json
 {
   "type": "creative_manifest",
-  "format_id": "display_native",
+  "target_format_id": {
+    "agent_url": "https://creatives.adcontextprotocol.org",
+    "id": "display_native"
+  },
   "assets": {
     "headline": "Premium Dog Nutrition",
     "description": "Veterinarian recommended formula with real salmon",
@@ -136,11 +116,14 @@ Creative agents need to understand format requirements to generate appropriate c
 }
 ```
 
-#### Code Mode (Dynamic Creative)
+#### Creative Code (Dynamic)
 ```json
 {
   "type": "creative_code",
-  "format_id": "html5",
+  "target_format_id": {
+    "agent_url": "https://creatives.adcontextprotocol.org",
+    "id": "html5"
+  },
   "code": "<div id='adcp-creative'>\n  <script>\n    (function() {\n      // Dynamic creative logic\n      const context = window.ADCP_CONTEXT || {};\n      const assets = {\n        sunny: 'outdoor-dog.jpg',\n        rainy: 'indoor-cozy.jpg'\n      };\n      \n      // Select asset based on weather\n      const heroImage = assets[context.weather] || assets.sunny;\n      \n      // Render creative\n      document.getElementById('adcp-creative').innerHTML = `\n        <img src=\"${heroImage}\" />\n        <h2>${context.time === 'morning' ? 'Start Their Day Right' : 'Premium Nutrition'}</h2>\n        <button>Shop Now</button>\n      `;\n    })();\n  </script>\n</div>",
   "dependencies": {
     "context_required": ["weather", "time"],
@@ -175,15 +158,17 @@ Creative agents need to understand format requirements to generate appropriate c
 
 ## Examples
 
-### Example 1: Building a Native Ad with Brand Card (Manifest Mode)
+### Example 1: Building a Native Ad with Brand Manifest
 
-#### Initial Request with Brand Card
+#### Initial Request with Brand Manifest
 ```json
 {
   "message": "Create a native ad for Yahoo promoting Purina Pro Plan. Focus on the veterinarian recommendation and that real salmon is the #1 ingredient.",
-  "format_id": "display_native",
-  "output_mode": "manifest",
-  "brand_card": {
+  "target_format_id": {
+    "agent_url": "https://creatives.adcontextprotocol.org",
+    "id": "display_native"
+  },
+  "brand_manifest": {
     "url": "https://purina.com",
     "name": "Purina Pro Plan",
     "logos": [
@@ -210,13 +195,15 @@ Creative agents need to understand format requirements to generate appropriate c
 }
 ```
 
-#### Simple Request (Minimal Brand Card)
+#### Simple Request (Minimal Brand Manifest)
 ```json
 {
   "message": "Create a native ad for Yahoo promoting Purina Pro Plan. Focus on the veterinarian recommendation and that real salmon is the #1 ingredient. Use an informative and trustworthy tone with 'Learn More' as the CTA.",
-  "format_id": "display_native",
-  "output_mode": "manifest",
-  "brand_card": {
+  "target_format_id": {
+    "agent_url": "https://creatives.adcontextprotocol.org",
+    "id": "display_native"
+  },
+  "brand_manifest": {
     "url": "https://purina.com"
   },
   "assets": [
@@ -236,7 +223,10 @@ Creative agents need to understand format requirements to generate appropriate c
   "status": "draft",
   "creative_output": {
     "type": "creative_manifest",
-    "format_id": "display_native",
+    "target_format_id": {
+    "agent_url": "https://creatives.adcontextprotocol.org",
+    "id": "display_native"
+  },
     "assets": {
       "headline": "Veterinarian Recommended Nutrition",
       "description": "Pro Plan with real salmon as the #1 ingredient provides complete nutrition for your dog's sensitive skin and stomach.",
@@ -307,7 +297,10 @@ Creative agents need to understand format requirements to generate appropriate c
   "status": "ready",
   "creative_output": {
     "type": "creative_manifest",
-    "format_id": "display_native",
+    "target_format_id": {
+    "agent_url": "https://creatives.adcontextprotocol.org",
+    "id": "display_native"
+  },
     "assets": {
       "headline": "Veterinarian Recommended Grain-Free Nutrition",
       "description": "Pro Plan's grain-free formula with real salmon as the #1 ingredient provides complete nutrition without grains that can upset sensitive stomachs.",
@@ -339,7 +332,10 @@ Creative agents need to understand format requirements to generate appropriate c
   "status": "ready",
   "creative_output": {
     "type": "creative_manifest",
-    "format_id": "display_native",
+    "target_format_id": {
+    "agent_url": "https://creatives.adcontextprotocol.org",
+    "id": "display_native"
+  },
     "assets": {
       "headline": "Veterinarian Recommended Grain-Free Nutrition",
       "description": "Pro Plan's grain-free formula with real salmon as the #1 ingredient provides complete nutrition without grains that can upset sensitive stomachs.",
@@ -359,14 +355,16 @@ Creative agents need to understand format requirements to generate appropriate c
 }
 ```
 
-### Example 2: Building Dynamic Video Creative (Code Mode)
+### Example 2: Building Dynamic Video Creative
 
 #### Initial Conversation
 ```json
 {
   "message": "I need a dynamic 30-second video for Purina that adapts based on viewer context. It should be upbeat and personalized, focusing on premium nutrition tailored for each dog's needs. The CTA should be 'Find Your Formula'.",
-  "format_id": "video_standard_30s",
-  "output_mode": "code",
+  "target_format_id": {
+    "agent_url": "https://creatives.adcontextprotocol.org",
+    "id": "video_standard_30s"
+  },
   "assets": [
     {
       "library_id": "purina_video_library",
@@ -431,9 +429,11 @@ Creative agents need to understand format requirements to generate appropriate c
 ```json
 {
   "message": "Create a short-form video ad featuring user-generated content style. Keep it authentic and fun, focusing on real pet parents and their transformation stories. Use 'See Their Story' as the CTA.",
-  "format_id": "custom_short_form_video",
+  "target_format_id": {
+    "agent_url": "https://publisher.com/.well-known/adcp/sales",
+    "id": "custom_short_form_video"
+  },
   "format_source": "https://videoplatform.com/.well-known/adcp/sales",
-  "output_mode": "manifest"
 }
 ```
 
@@ -442,7 +442,10 @@ Creative agents need to understand format requirements to generate appropriate c
 {
   "context_id": "ctx-video-123",
   "creative": {
-    "format_id": "custom_short_form_video",
+    "target_format_id": {
+    "agent_url": "https://publisher.com/.well-known/adcp/sales",
+    "id": "custom_short_form_video"
+  },
   "format_source": "https://videoplatform.com/.well-known/adcp/sales",
       "id": "custom_short_form_video",
       "name": "Short Form Video Ad",
@@ -502,8 +505,9 @@ Creative agents need to understand format requirements to generate appropriate c
 
 ## Usage Notes
 
-- **Manifest Mode**: Returns structured data that can be used with any ad server
-- **Code Mode**: Returns executable HTML/JS that handles its own rendering
+- **Creative Manifest**: Returns structured asset data that can be used with any ad server
+- **Creative Code**: Returns executable HTML/JS that handles its own rendering
+- **Output Type**: Determined by the format definition, not a parameter
 - **Previews**: Always check previews to ensure creative meets expectations
 - **Custom Formats**: Publishers should provide preview templates for non-standard formats
 - **Conversations**: Use natural language messages to guide the creative process