decoupled-cli 2.0.3 → 2.1.1

package/examples/GEMINI.md

@@ -5,7 +5,7 @@ This document provides Gemini with comprehensive instructions for building compl
 ## Project Overview
 
 **Architecture**: Headless Drupal backend with Next.js frontend
-**Backend**: Drupal 11 with GraphQL Compose and DCloud Import API
+**Backend**: Drupal 11 with GraphQL Compose and DC Import API
 **Frontend**: Next.js 15 with TypeScript, Tailwind CSS, and Apollo GraphQL
 **Environment**: DDEV local development
 
@@ -18,7 +18,7 @@ This document provides Gemini with comprehensive instructions for building compl
 - `DRUPAL_REVALIDATE_SECRET` - Secret for on-demand revalidation
 - `NODE_TLS_REJECT_UNAUTHORIZED=0` - Allow self-signed certificates (development)
 
-## DCloud CLI Setup
+## DC CLI Setup
 
 **First-time CLI setup:**
 ```bash
@@ -40,7 +40,7 @@ npx decoupled-cli spaces use <space_id>
 npx decoupled-cli spaces current
 ```
 
-**OAuth Prerequisites (for `dcloud auth oauth`):**
+**OAuth Prerequisites (for `decoupled-cli auth oauth`):**
 Your `.env.local` must contain:
 - `NEXT_PUBLIC_DRUPAL_BASE_URL=https://your-space.decoupled.io`
 - `DRUPAL_CLIENT_ID=your_oauth_client_id`
@@ -48,11 +48,11 @@ Your `.env.local` must contain:
 
 **Authentication Method Differences:**
 - **OAuth** → Works with your Drupal site API (content import, Drupal operations)
-- **Personal Access Token** → Works with DrupalCloud platform API (spaces, users, organizations)
+- **Personal Access Token** → Works with Decoupled Drupal platform API (spaces, users, organizations)
 
 **If CLI is not available locally:**
 - For projects with decoupled-cli in package.json: Run `npm install` then use `npx decoupled-cli`
-- For development: `cd cli && npm install && npm run build && npm link` then use `dcloud`
+- For development: `cd cli && npm install && npm run build && npm link` then use `decoupled-cli`
 - Always prefer using `npx decoupled-cli` for consistency and local package management
 
 ## End-to-End Development Workflow
@@ -73,8 +73,8 @@ Use OAuth authentication for direct Drupal content import, then frontend develop
 
 **Create a todo list for tracking progress:**
 ```markdown
-1. Verify DCloud CLI authentication (npx decoupled-cli auth status)
-2. Create DCloud Import JSON for [content_type]
+1. Verify DC CLI authentication (npx decoupled-cli auth status)
+2. Create DC Import JSON for [content_type]
 3. Import content type and sample content to Drupal (npx decoupled-cli content import)
 4. **CRITICAL**: Run schema generation (`npm run generate-schema`) to update GraphQL schema
 5. Create TypeScript types and GraphQL queries
@@ -84,11 +84,11 @@ Use OAuth authentication for direct Drupal content import, then frontend develop
 9. Validate end-to-end functionality
 ```
 
-**Legacy Platform Workflow (PAT + DrupalCloud Platform):**
+**Legacy Platform Workflow (PAT + Decoupled Drupal Platform):**
 ```markdown
-1. Verify DCloud CLI authentication (npx decoupled-cli auth status)
+1. Verify DC CLI authentication (npx decoupled-cli auth status)
 2. Set default space if needed (npx decoupled-cli spaces use <id>)
-3. Create DCloud Import JSON for [content_type]
+3. Create DC Import JSON for [content_type]
 4. Import content type and sample content via platform (npx decoupled-cli spaces content-import)
 5. **CRITICAL**: Run schema generation (`npm run generate-schema`) to update GraphQL schema
 6. Create TypeScript types and GraphQL queries
@@ -119,7 +119,7 @@ npx decoupled-cli spaces use <space_id>
 
 **If CLI authentication fails:**
 - For OAuth: Verify `.env.local` contains `NEXT_PUBLIC_DRUPAL_BASE_URL`, `DRUPAL_CLIENT_ID`, `DRUPAL_CLIENT_SECRET`
-- For personal tokens: Check that DCloud platform is accessible
+- For personal tokens: Check that DC platform is accessible
 - Ensure user has proper permissions for the operations you're trying to perform
 
 **Important: Command Availability by Authentication Method**
@@ -127,7 +127,7 @@ npx decoupled-cli spaces use <space_id>
 - **PAT-only commands**: `spaces list`, `spaces use`, `usage`, `org info`
 - **Universal commands**: `auth login`, `auth oauth`, `auth test`
 
-### 2. DCloud Import JSON Creation
+### 2. DC Import JSON Creation
 
 **Get example format with CLI:**
 ```bash
@@ -186,14 +186,14 @@ npx decoupled-cli spaces content-import --example > my-content-type.json
 - **For image fields**: Use full URLs with the Drupal domain from `.env.local`, not relative paths:
   ```json
   "featured_image": {
-    "uri": "${DRUPAL_BASE_URL}/modules/custom/dcloud_import/resources/placeholder.png",
+    "uri": "${DRUPAL_BASE_URL}/modules/custom/dc_import/resources/placeholder.png",
     "alt": "Description of the image",
     "title": "Image title"
   }
   ```
   Always read the `NEXT_PUBLIC_DRUPAL_BASE_URL` from `.env.local` and use that as the base for image URIs to ensure images load correctly from the Drupal backend.
 
-### 3. Import via DCloud CLI
+### 3. Import via DC CLI
 
 **Import Content Type:**
 ```bash
@@ -203,7 +203,7 @@ npx decoupled-cli content import --file content-type-import.json
 # Or preview first to see what will be imported
 npx decoupled-cli content import --file content-type-import.json --preview
 
-# LEGACY: Import via DrupalCloud platform (requires PAT authentication and space setup)
+# LEGACY: Import via Decoupled Drupal platform (requires PAT authentication and space setup)
 npx decoupled-cli spaces content-import --file content-type-import.json
 npx decoupled-cli spaces content-import <space_id> --file content-type-import.json
 ```
@@ -220,7 +220,7 @@ npx decoupled-cli content import --example > content-type-import.json
 - Field machine names (auto-generated)
 - Node IDs created
 - GraphQL schema updates
-- **Important**: GraphQL field names may differ from DCloud field IDs (check actual schema)
+- **Important**: GraphQL field names may differ from DC field IDs (check actual schema)
 
 **CRITICAL: Immediately Update GraphQL Schema After Import:**
 ```bash
@@ -500,7 +500,7 @@ npm run dev
 ### 6. Testing Checklist
 
 **Verify each step:**
-- [ ] DCloud import successful with no errors
+- [ ] DC import successful with no errors
 - [ ] GraphQL schema includes new content type
 - [ ] TypeScript types are properly defined
 - [ ] Build process completes without errors
@@ -540,7 +540,7 @@ npm run dev
 ```json
 "product_images": [
   {
-    "uri": "${DRUPAL_BASE_URL}/modules/custom/dcloud_import/resources/placeholder.png",
+    "uri": "${DRUPAL_BASE_URL}/modules/custom/dc_import/resources/placeholder.png",
     "alt": "Product showcase image",
     "title": "Product Image"
   }
@@ -588,7 +588,7 @@ npm run dev
 **Sample content with image URI:**
 ```json
 "profile_image": {
-  "uri": "${DRUPAL_BASE_URL}/modules/custom/dcloud_import/resources/placeholder.png",
+  "uri": "${DRUPAL_BASE_URL}/modules/custom/dc_import/resources/placeholder.png",
   "alt": "Team member headshot",
   "title": "Profile Photo"
 }
@@ -617,7 +617,7 @@ npm run dev
 ```json
 "project_images": [
   {
-    "uri": "${DRUPAL_BASE_URL}/modules/custom/dcloud_import/resources/placeholder.png",
+    "uri": "${DRUPAL_BASE_URL}/modules/custom/dc_import/resources/placeholder.png",
     "alt": "Project screenshot showing main interface",
     "title": "Project Interface"
   }
@@ -628,7 +628,7 @@ npm run dev
 
 ### Common Issues
 
-**1. DCloud Import Fails**
+**1. DC Import Fails**
 - Check OAuth token expiration
 - Verify JSON structure matches `schema/sample.json` format
 - Ensure field IDs don't start with `field_`
@@ -645,15 +645,15 @@ npm run dev
 - Verify GraphQL query syntax
 
 **4. Content Not Displaying**
-- Check GraphQL query field names match Drupal fields (may not match DCloud field IDs)
+- Check GraphQL query field names match Drupal fields (may not match DC field IDs)
 - Verify content was created and published
 - Check query variables and pagination
 - For HTML content showing raw tags, use `dangerouslySetInnerHTML={{ __html: field.processed }}`
 
-**5. GraphQL Schema Not Updated After DCloud Import**
-- **Critical Issue**: DCloud imports create content types successfully but GraphQL schema may not update immediately
+**5. GraphQL Schema Not Updated After DC Import**
+- **Critical Issue**: DC imports create content types successfully but GraphQL schema may not update immediately
 - Content exists in Drupal but `nodeProducts` query returns "field not found" errors
-- This is the most common issue with DCloud imports
+- This is the most common issue with DC imports
 
 **Solution Process**:
 1. Clear Drupal caches (if you have admin access)
@@ -663,7 +663,7 @@ npm run dev
 
 ### Essential Schema Generation Workflow
 
-**CRITICAL**: Always run schema generation after DCloud imports to ensure GraphQL integration works properly.
+**CRITICAL**: Always run schema generation after DC imports to ensure GraphQL integration works properly.
 
 ```bash
 # Generate updated GraphQL schema after content type imports
@@ -677,7 +677,7 @@ This command:
 - Validates that new content types are available in GraphQL
 
 **Add this to your workflow**:
-1. Import content type via DCloud API
+1. Import content type via DC API
 2. **Immediately run**: `npm run generate-schema`
 3. Check generated schema includes your new content type
 4. Test GraphQL queries
@@ -713,7 +713,7 @@ npx decoupled-cli spaces list
 # Check current default space
 npx decoupled-cli spaces current
 
-# Get health status of DCloud platform
+# Get health status of DC platform
 npx decoupled-cli health check
 
 # Check organization info
@@ -778,7 +778,7 @@ npx decoupled-cli content import --file your-content.json
 7. **Include proper TypeScript types** for all data structures
 8. **Test the full user journey** from listing to detail pages
 9. **Use `dangerouslySetInnerHTML`** for processed HTML content from Drupal to avoid raw tag display
-10. **Verify GraphQL field names** match actual schema, not DCloud field IDs
+10. **Verify GraphQL field names** match actual schema, not DC field IDs
 
 ## Success Criteria
 
@@ -796,7 +796,7 @@ A successful end-to-end implementation should:
 
 Based on successful product catalog implementation, here are critical learnings to avoid common pitfalls:
 
-### DCloud Import Format Issues
+### DC Import Format Issues
 
 **Problem**: Field values incorrectly formatted with "field_" prefix
 ```json
@@ -817,14 +817,14 @@ Based on successful product catalog implementation, here are critical learnings
 
 ### GraphQL Field Name Mapping
 
-**Problem**: Assuming GraphQL field names match DCloud field IDs
+**Problem**: Assuming GraphQL field names match DC field IDs
 ```typescript
 // WRONG - Field names may be transformed
-price: string           // DCloud field ID
+price: string           // DC field ID
 fieldPrice: string      // What you might expect in GraphQL
 
 // CORRECT - Check actual schema
-price: string          // Actual GraphQL field name (can match DCloud ID)
+price: string          // Actual GraphQL field name (can match DC ID)
 inStock: boolean       // camelCase transformation
 productImages: object  // snake_case to camelCase
 ```
@@ -833,7 +833,7 @@ productImages: object  // snake_case to camelCase
 
 ### GraphQL Field Value Structure Discovery
 
-**Critical Learning**: GraphQL field values from DCloud imports return as simple types, not objects:
+**Critical Learning**: GraphQL field values from DC imports return as simple types, not objects:
 
 ```typescript
 // WRONG - Assuming field values are objects with .processed
@@ -844,7 +844,7 @@ fieldFeatures?: Array<{
   processed: string
 }>
 
-// CORRECT - DCloud imports create simple value fields
+// CORRECT - DC imports create simple value fields
 price?: string
 features?: string[]
 ```
@@ -957,29 +957,29 @@ npm run dev    # Test in development mode
 
 The most important learning from the product catalog implementation is the **mandatory schema generation step**:
 
-**Problem**: DCloud imports successfully create content types and content, but GraphQL schema doesn't update automatically.
+**Problem**: DC imports successfully create content types and content, but GraphQL schema doesn't update automatically.
 **Symptoms**:
 - `nodeProducts` query returns "field not found" errors
 - Content exists in Drupal but not accessible via GraphQL
 - Route queries work but content type queries fail
 
-**Solution**: **ALWAYS run schema generation immediately after DCloud imports**:
+**Solution**: **ALWAYS run schema generation immediately after DC imports**:
 
 ```bash
-# After any DCloud import, immediately run:
+# After any DC import, immediately run:
 npm run generate-schema
 
 # This step is MANDATORY for GraphQL integration to work
 ```
 
 **Why this is critical**:
-- DCloud API creates Drupal content types but doesn't trigger GraphQL schema rebuilds
+- DC API creates Drupal content types but doesn't trigger GraphQL schema rebuilds
 - The `generate-schema` script performs fresh introspection and updates local schema files
 - Without this step, frontend development will fail with "type not found" errors
 - This step bridges the gap between Drupal content type creation and Next.js GraphQL integration
 
 **Workflow Integration**:
-1. Import via DCloud API ✅
+1. Import via DC API ✅
 2. **Run `npm run generate-schema`** ✅ ← CRITICAL STEP
 3. Verify schema includes new content type ✅
 4. Proceed with frontend development ✅
@@ -989,7 +989,7 @@ This learning transforms the development workflow from "sometimes works" to "rel
 ### Additional Key Learnings
 
 #### GraphQL Field Name Discovery (CRITICAL)
-**Always verify actual GraphQL field names after DCloud import** - they may differ from field IDs used in import JSON.
+**Always verify actual GraphQL field names after DC import** - they may differ from field IDs used in import JSON.
 
 **Field Name Transformations**:
 - `in_stock` becomes `inStock` (camelCase)
@@ -1039,7 +1039,7 @@ const getActiveTab = () => {
 #### Build Process Integration
 **Essential Commands Sequence**:
 ```bash
-# After DCloud import, always run:
+# After DC import, always run:
 npm run generate-schema  # Updates GraphQL schema
 npm run build           # Validates TypeScript and builds
 npm run dev            # Test in development

package/examples/content-import-sample.json

@@ -1,114 +1,289 @@
 {
   "model": [
     {
-      "bundle": "event",
-      "description": "Content type for managing events, conferences, and gatherings",
-      "label": "Event",
+      "bundle": "article",
+      "description": "Blog articles and news posts with rich media and categorization",
+      "label": "Article",
       "body": true,
       "fields": [
         {
-          "id": "event_date",
-          "label": "Event Date",
-          "type": "datetime"
-        },
-        {
-          "id": "location",
-          "label": "Location",
-          "type": "string"
+          "id": "summary",
+          "label": "Summary",
+          "type": "string",
+          "description": "Short text field (max 255 chars) for article preview"
         },
         {
           "id": "featured_image",
           "label": "Featured Image",
-          "type": "image"
+          "type": "image",
+          "description": "Single image upload for article hero"
         },
         {
-          "id": "event_details",
-          "label": "Event Details",
-          "type": "paragraph(event_detail)[]"
+          "id": "published_date",
+          "label": "Published Date",
+          "type": "datetime",
+          "description": "Date and time field for publication scheduling"
+        },
+        {
+          "id": "author",
+          "label": "Author Name",
+          "type": "string"
         },
         {
           "id": "tags",
           "label": "Tags",
-          "type": "term(tags)[]"
+          "type": "term(tags)[]",
+          "description": "Multiple taxonomy term references"
         },
         {
           "id": "featured",
-          "label": "Featured",
-          "type": "bool"
+          "label": "Featured Article",
+          "type": "bool",
+          "description": "Boolean flag for promoting articles"
+        },
+        {
+          "id": "key_points",
+          "label": "Key Points",
+          "type": "string[]",
+          "description": "Multiple string values - best for simple lists without HTML"
+        },
+        {
+          "id": "gallery",
+          "label": "Image Gallery",
+          "type": "image[]",
+          "description": "Multiple image uploads"
+        },
+        {
+          "id": "content_blocks",
+          "label": "Content Blocks",
+          "type": "paragraph(content_block)[]",
+          "description": "Multiple paragraph entity references for structured content"
         }
       ]
     },
     {
       "entity": "paragraph",
-      "bundle": "event_detail",
-      "description": "Reusable content blocks for event information and details",
-      "label": "Event Detail",
+      "bundle": "content_block",
+      "description": "Reusable content blocks with images and formatted text",
+      "label": "Content Block",
       "fields": [
         {
-          "id": "detail_title",
-          "label": "Detail Title",
-          "type": "string!"
+          "id": "block_title",
+          "label": "Block Title",
+          "type": "string!",
+          "description": "Required field (note the ! suffix)"
         },
         {
-          "id": "detail_content",
-          "label": "Detail Content",
-          "type": "text"
+          "id": "block_content",
+          "label": "Block Content",
+          "type": "text",
+          "description": "Long text with HTML formatting"
         },
         {
-          "id": "detail_image",
-          "label": "Detail Image",
+          "id": "block_image",
+          "label": "Block Image",
           "type": "image"
         }
       ]
+    },
+    {
+      "bundle": "product",
+      "description": "E-commerce products with pricing, inventory, and specifications",
+      "label": "Product",
+      "body": true,
+      "fields": [
+        {
+          "id": "price",
+          "label": "Price",
+          "type": "string",
+          "description": "Product price as formatted string (e.g. '$299.99')"
+        },
+        {
+          "id": "sku",
+          "label": "SKU",
+          "type": "string",
+          "description": "Product identifier"
+        },
+        {
+          "id": "in_stock",
+          "label": "In Stock",
+          "type": "bool"
+        },
+        {
+          "id": "product_images",
+          "label": "Product Images",
+          "type": "image[]",
+          "description": "Multiple product photos"
+        },
+        {
+          "id": "features",
+          "label": "Key Features",
+          "type": "string[]",
+          "description": "List of product features (plain text, no HTML)"
+        },
+        {
+          "id": "specifications",
+          "label": "Specifications",
+          "type": "string[]",
+          "description": "Technical specifications"
+        },
+        {
+          "id": "category",
+          "label": "Product Category",
+          "type": "term(product_category)[]"
+        }
+      ]
     }
   ],
   "content": [
     {
-      "id": "detail1",
-      "type": "paragraph.event_detail",
+      "id": "block1",
+      "type": "paragraph.content_block",
       "values": {
-        "detail_title": "Schedule",
-        "detail_content": "The event will run from 9:00 AM to 5:00 PM with lunch break at noon.",
-        "detail_image": {
-          "uri": "/modules/custom/dcloud_import/resources/placeholder.png",
-          "alt": "Event schedule timeline showing sessions and breaks",
-          "title": "Conference Schedule"
+        "block_title": "Introduction",
+        "block_content": "<p>This is an <strong>example content block</strong> with formatted text.</p>",
+        "block_image": {
+          "uri": "${DRUPAL_BASE_URL}/modules/custom/dc_import/resources/placeholder.png",
+          "alt": "Content block illustration",
+          "title": "Block Image"
         }
       }
     },
     {
-      "id": "detail2",
-      "type": "paragraph.event_detail",
+      "id": "article1",
+      "type": "node.article",
+      "path": "/articles/getting-started-with-drupal",
       "values": {
-        "detail_title": "Speakers",
-        "detail_content": "Join us for presentations by industry experts and thought leaders."
+        "title": "Getting Started with Decoupled Drupal",
+        "summary": "Learn how to build modern web applications with Drupal as a headless CMS",
+        "body": "<p>Decoupled Drupal enables you to use Drupal as a powerful content management backend while building your frontend with modern JavaScript frameworks.</p><p>This architecture provides flexibility, performance, and an excellent developer experience.</p>",
+        "published_date": "2024-03-15T09:00:00",
+        "author": "Jane Smith",
+        "featured": true,
+        "key_points": [
+          "Use Drupal for content management",
+          "Build frontend with Next.js, React, or Vue",
+          "Connect via GraphQL or REST API",
+          "Deploy frontend and backend independently"
+        ],
+        "featured_image": {
+          "uri": "${DRUPAL_BASE_URL}/modules/custom/dc_import/resources/placeholder.png",
+          "alt": "Decoupled Drupal architecture diagram",
+          "title": "Architecture Overview"
+        },
+        "gallery": [
+          {
+            "uri": "${DRUPAL_BASE_URL}/modules/custom/dc_import/resources/placeholder.png",
+            "alt": "Screenshot of content management interface",
+            "title": "CMS Interface"
+          },
+          {
+            "uri": "${DRUPAL_BASE_URL}/modules/custom/dc_import/resources/placeholder.png",
+            "alt": "Frontend application example",
+            "title": "Frontend App"
+          }
+        ],
+        "tags": [
+          "drupal",
+          "headless-cms",
+          "web-development"
+        ],
+        "content_blocks": [
+          "@block1"
+        ]
       }
     },
     {
-      "id": "event1",
-      "type": "node.event",
-      "path": "/events/web-dev-conference-2024",
+      "id": "product1",
+      "type": "node.product",
+      "path": "/products/wireless-charger-pro",
       "values": {
-        "title": "Web Development Conference 2024",
-        "body": "<p>Join us for a full day of learning about modern web development...</p>",
-        "event_date": "2024-03-15T09:00:00",
-        "location": "Convention Center Downtown",
-        "featured_image": {
-          "uri": "/modules/custom/dcloud_import/resources/placeholder.png",
-          "alt": "Web Development Conference 2024 promotional image",
-          "title": "Conference Hero Image"
-        },
-        "tags": [
-          "web-development",
-          "conference",
-          "technology"
+        "title": "Wireless Charger Pro",
+        "body": "<p>Experience the future of charging with our premium wireless charging pad. Sleek design meets powerful performance.</p>",
+        "price": "$79.99",
+        "sku": "WCP-2024-BLK",
+        "in_stock": true,
+        "features": [
+          "Fast 15W wireless charging",
+          "Qi-compatible with all devices",
+          "Non-slip rubberized surface",
+          "LED charging indicator",
+          "Overheat protection"
         ],
-        "featured": true,
-        "event_details": [
-          "@detail1",
-          "@detail2"
+        "specifications": [
+          "Input: USB-C 5V/3A",
+          "Output: 15W max",
+          "Size: 4 x 4 x 0.5 inches",
+          "Weight: 3.2 oz",
+          "Color: Matte Black"
+        ],
+        "product_images": [
+          {
+            "uri": "${DRUPAL_BASE_URL}/modules/custom/dc_import/resources/placeholder.png",
+            "alt": "Wireless Charger Pro front view",
+            "title": "Product Front"
+          },
+          {
+            "uri": "${DRUPAL_BASE_URL}/modules/custom/dc_import/resources/placeholder.png",
+            "alt": "Wireless Charger Pro with phone charging",
+            "title": "In Use"
+          }
+        ],
+        "category": [
+          "electronics",
+          "accessories"
         ]
       }
     }
-  ]
+  ],
+  "_comments": {
+    "field_types": {
+      "string": "Short text (max 255 chars), plain text only",
+      "text": "Long text with HTML formatting support",
+      "string[]": "Multiple string values - best for simple lists like features, tags, specifications",
+      "text[]": "Multiple text values with HTML - use sparingly, prefer string[] for lists",
+      "image": "Single image upload with uri, alt, title properties",
+      "image[]": "Multiple image uploads",
+      "datetime": "Date and time in ISO 8601 format (YYYY-MM-DDTHH:mm:ss)",
+      "bool": "Boolean true/false value",
+      "term(vocabulary)[]": "Taxonomy term references, creates/assigns terms automatically",
+      "paragraph(bundle)[]": "References to paragraph entities for structured content",
+      "string!": "Required field (note the ! suffix)"
+    },
+    "image_format": {
+      "description": "Images require full URLs with Drupal domain, not relative paths",
+      "example": {
+        "uri": "${DRUPAL_BASE_URL}/modules/custom/dc_import/resources/placeholder.png",
+        "alt": "Descriptive alt text for accessibility",
+        "title": "Image title"
+      },
+      "note": "Replace ${DRUPAL_BASE_URL} with actual Drupal URL from .env.local"
+    },
+    "content_references": {
+      "description": "Reference other content items using @id syntax",
+      "example": "\"content_blocks\": [\"@block1\", \"@block2\"]",
+      "note": "Referenced content must be defined earlier in the content array"
+    },
+    "field_naming": {
+      "important": "In DC import JSON, use field 'id' directly (e.g., 'price'), NOT 'field_price'",
+      "note": "Drupal automatically prefixes with 'field_' internally",
+      "graphql": "GraphQL field names may transform to camelCase (e.g., in_stock → inStock)"
+    },
+    "best_practices": [
+      "Use string[] for simple lists (features, specifications) - avoids HTML rendering complexity",
+      "Use text[] only when you need rich HTML formatting within each list item",
+      "Always include sample content for immediate testing",
+      "Use descriptive field IDs that are clear and consistent",
+      "Include alt text for all images for accessibility",
+      "Set body: true to include standard body field",
+      "Use path aliases following /content-type/slug pattern"
+    ],
+    "common_patterns": {
+      "e-commerce": "price (string), sku (string), in_stock (bool), product_images (image[]), features (string[])",
+      "blog": "summary (string), author (string), published_date (datetime), tags (term[]), featured (bool)",
+      "events": "event_date (datetime), location (string), registration_url (string), speakers (string[])",
+      "team": "position (string), profile_image (image), bio (text), social_links (string[])",
+      "portfolio": "project_url (string), technologies (string[]), project_images (image[]), client (string)"
+    }
+  }
 }