Add headless CMS reference and integration guides (#174)

* feat: add headless CMS reference and integration guides Add CMS selection guide, content modeling patterns, and editorial workflow reference for marketers. Add integration guides for Sanity (GROQ API), Contentful (CDA/CMA), and Strapi (v5 REST). Register all three in REGISTRY.md and link from content-strategy skill. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: address review feedback on headless CMS guides - Use {curly_brace} placeholder convention for Strapi relation example - Add note that Contentful CMA create uses PUT with client-generated ID - Add URL-encoding note for Sanity GROQ query parameter - Switch Sanity mutation example from createOrReplace to create (no _id needed) - Add Content-Type header to Contentful update entry example - Fix outdated "Assembly" product name to "Studio" for Contentful Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-09 23:21:58 -07:00
parent 3a8d01283d
commit 51146da746
6 changed files with 682 additions and 1 deletions
@@ -0,0 +1,160 @@
+# Contentful
+
+Enterprise headless CMS with multi-locale support, two-API architecture, and composable content.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Content Delivery API (read), Content Management API (write) |
+| MCP | - | No official MCP server |
+| CLI | ✓ | `contentful-cli` for spaces, content types, migrations |
+| SDK | ✓ | `contentful` (delivery), `contentful-management` (management) |
+
+## Authentication
+
+- **Delivery API (CDA)**: `Authorization: Bearer {delivery_token}`
+  - Base URL: `https://cdn.contentful.com`
+  - Read-only, CDN-cached
+- **Preview API (CPA)**: `Authorization: Bearer {preview_token}`
+  - Base URL: `https://preview.contentful.com`
+  - Read-only, returns draft content
+- **Management API (CMA)**: `Authorization: Bearer {management_token}`
+  - Base URL: `https://api.contentful.com`
+  - Read/write, not cached
+- **Tokens**: Create in Settings → API keys (delivery) or Settings → CMA tokens (management)
+
+## Common Agent Operations
+
+### Get entries (Delivery API)
+
+```bash
+GET https://cdn.contentful.com/spaces/{space_id}/environments/{environment}/entries?content_type=blogPost&limit=10
+
+Authorization: Bearer {delivery_token}
+```
+
+### Get single entry
+
+```bash
+GET https://cdn.contentful.com/spaces/{space_id}/environments/{environment}/entries/{entry_id}
+
+Authorization: Bearer {delivery_token}
+```
+
+### Search and filter
+
+```bash
+# By field value
+GET https://cdn.contentful.com/spaces/{space_id}/environments/{environment}/entries?content_type=blogPost&fields.slug=my-post
+
+# Full-text search
+GET https://cdn.contentful.com/spaces/{space_id}/environments/{environment}/entries?query=marketing+strategy
+
+# By date range
+GET https://cdn.contentful.com/spaces/{space_id}/environments/{environment}/entries?content_type=blogPost&fields.publishDate[gte]=2024-01-01
+```
+
+### Create entry (Management API)
+
+CMA uses PUT with a client-generated `entry_id`. To auto-generate, use POST without an ID in the path.
+
+```bash
+PUT https://api.contentful.com/spaces/{space_id}/environments/{environment}/entries/{entry_id}
+Content-Type: application/vnd.contentful.management.v1+json
+X-Contentful-Content-Type: blogPost
+Authorization: Bearer {management_token}
+
+{
+  "fields": {
+    "title": {"en-US": "New Post"},
+    "slug": {"en-US": "new-post"},
+    "body": {"en-US": "Post content here"}
+  }
+}
+```
+
+### Update entry
+
+```bash
+PUT https://api.contentful.com/spaces/{space_id}/environments/{environment}/entries/{entry_id}
+Content-Type: application/vnd.contentful.management.v1+json
+X-Contentful-Version: {current_version}
+Authorization: Bearer {management_token}
+
+{
+  "fields": {
+    "title": {"en-US": "Updated Title"}
+  }
+}
+```
+
+### Publish entry
+
+```bash
+PUT https://api.contentful.com/spaces/{space_id}/environments/{environment}/entries/{entry_id}/published
+X-Contentful-Version: {current_version}
+Authorization: Bearer {management_token}
+```
+
+### Unpublish entry
+
+```bash
+DELETE https://api.contentful.com/spaces/{space_id}/environments/{environment}/entries/{entry_id}/published
+X-Contentful-Version: {current_version}
+Authorization: Bearer {management_token}
+```
+
+## CLI Commands
+
+```bash
+# Login
+contentful login
+
+# List spaces
+contentful space list
+
+# Export space content
+contentful space export --space-id {space_id}
+
+# Import content
+contentful space import --space-id {space_id} --content-file export.json
+
+# Create migration
+contentful space migration --space-id {space_id} migration.js
+
+# List content types
+contentful content-type list --space-id {space_id}
+```
+
+## Key Objects
+
+- **Space** — Top-level container for content (one per project)
+- **Environment** — Isolated content branch (`master`, `staging`, etc.)
+- **Content Type** — Schema definition with fields and validations
+- **Entry** — Content item of a specific content type
+- **Asset** — Media file (image, video, document)
+- **Locale** — Language/region variant (e.g., `en-US`, `de-DE`)
+
+## When to Use
+
+- Multi-locale marketing content (global sites)
+- Enterprise content operations with approval workflows
+- Composable content architecture
+- Teams needing established vendor support and SLAs
+- Content reuse across multiple channels
+
+## Rate Limits
+
+Rate limits are plan-dependent. Check `X-Contentful-RateLimit-Second-Limit` response header for your actual limits.
+
+- Delivery API (CDA): Varies by plan (typically high throughput)
+- Preview API (CPA): Lower than CDA (varies by plan)
+- Management API (CMA): ~10 requests per second (default)
+- See [Contentful technical limits](https://www.contentful.com/developers/docs/technical-limits/) for current values
+
+## Relevant Skills
+
+- content-strategy (CMS selection, content modeling)
+- programmatic-seo (CMS as data source for generated pages)
+- site-architecture (multi-locale URL structure)
@@ -0,0 +1,148 @@
+# Sanity
+
+Headless CMS with real-time collaboration, GROQ query language, and schema-as-code.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | GROQ queries, Mutations API, Assets API |
+| MCP | - | No official MCP server |
+| CLI | ✓ | `sanity` CLI for studio, datasets, deployment |
+| SDK | ✓ | `@sanity/client`, `next-sanity`, `@sanity/image-url` |
+
+## Authentication
+
+- **Type**: API Token (Bearer)
+- **Header**: `Authorization: Bearer skXXXXXX`
+- **Tokens**: Create in Sanity Manage → API → Tokens
+- **Permissions**: Read-only or Read+Write per token
+
+## Common Agent Operations
+
+### Query documents (GROQ)
+
+URL-encode the `query` parameter value in practice.
+
+```bash
+GET https://{projectId}.api.sanity.io/v2024-01-01/data/query/{dataset}?query=*[_type == "post"]{title, slug, publishedAt}
+```
+
+### Query with parameters
+
+```bash
+GET https://{projectId}.api.sanity.io/v2024-01-01/data/query/{dataset}?query=*[_type == "post" && slug.current == $slug][0]&$slug="my-post"
+```
+
+### Get document by ID
+
+```bash
+GET https://{projectId}.api.sanity.io/v2024-01-01/data/doc/{dataset}/{documentId}
+```
+
+### Create document (Mutations API)
+
+```bash
+POST https://{projectId}.api.sanity.io/v2024-01-01/data/mutate/{dataset}
+
+{
+  "mutations": [
+    {
+      "create": {
+        "_type": "post",
+        "title": "New Post",
+        "slug": {"_type": "slug", "current": "new-post"},
+        "body": [{"_type": "block", "children": [{"_type": "span", "text": "Hello"}]}]
+      }
+    }
+  ]
+}
+```
+
+Use `createOrReplace` instead if you want to upsert (requires `_id` field).
+
+### Delete document
+
+```bash
+POST https://{projectId}.api.sanity.io/v2024-01-01/data/mutate/{dataset}
+
+{
+  "mutations": [
+    {"delete": {"id": "document-id"}}
+  ]
+}
+```
+
+### Patch document
+
+```bash
+POST https://{projectId}.api.sanity.io/v2024-01-01/data/mutate/{dataset}
+
+{
+  "mutations": [
+    {
+      "patch": {
+        "id": "document-id",
+        "set": {"title": "Updated Title"}
+      }
+    }
+  ]
+}
+```
+
+## CLI Commands
+
+```bash
+# Create a new Sanity project
+sanity init
+
+# Start the studio locally
+sanity dev
+
+# Deploy studio to Sanity hosting
+sanity deploy
+
+# Export dataset
+sanity dataset export production ./backup.tar.gz
+
+# Import dataset
+sanity dataset import ./data.ndjson production
+
+# List datasets
+sanity dataset list
+
+# Run a GROQ query
+sanity documents query '*[_type == "post"][0..9]{title, slug}'
+```
+
+## Key Objects
+
+- **Document** — Top-level content item with `_id`, `_type`, `_rev`
+- **Asset** — Images and files stored in Sanity CDN
+- **Reference** — Link between documents (`{_type: "reference", _ref: "doc-id"}`)
+- **Portable Text** — Rich text as structured array of blocks
+- **Dataset** — Isolated content database (e.g., `production`, `staging`)
+- **Slug** — URL-friendly identifier (`{_type: "slug", current: "my-slug"}`)
+
+## When to Use
+
+- Structured content for marketing sites and blogs
+- Multi-channel content delivery (web, mobile, email)
+- Real-time collaborative editing workflows
+- Content-heavy sites with complex models
+- Next.js or React-based frontends
+
+## Rate Limits
+
+Rate limits vary by plan. Documented defaults:
+
+- CDN API (queries): High throughput, globally distributed (no hard per-second cap published)
+- API (without CDN): Rate-limited per project (varies by plan)
+- Mutations: Rate-limited per project (varies by plan)
+- See [Sanity technical limits](https://www.sanity.io/docs/technical-limits) for current values
+
+## Relevant Skills
+
+- content-strategy (CMS selection, content modeling)
+- programmatic-seo (CMS as data source for generated pages)
+- site-architecture (URL structure from CMS slugs)
@@ -0,0 +1,167 @@
+# Strapi
+
+Open-source headless CMS with self-hosted option, REST and GraphQL APIs, and customizable admin panel. Targets Strapi 5.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | REST (default), GraphQL (plugin) |
+| MCP | - | No official MCP server |
+| CLI | ✓ | `strapi` CLI for project setup, content types, plugins |
+| SDK | ✓ | `@strapi/sdk-js`, `@strapi/blocks-react-renderer` |
+
+## Authentication
+
+- **Type**: API Token or Users & Permissions JWT
+- **Header**: `Authorization: Bearer {api_token}`
+- **Tokens**: Create in Settings → API Tokens (full access, read-only, or custom)
+- **JWT**: `POST /api/auth/local` with identifier + password returns JWT
+
+## Common Agent Operations
+
+### List documents
+
+```bash
+GET http://localhost:1337/api/articles?populate=*
+
+Authorization: Bearer {api_token}
+```
+
+### Get single document
+
+```bash
+GET http://localhost:1337/api/articles/{documentId}?populate=*
+
+Authorization: Bearer {api_token}
+```
+
+### Filter and sort
+
+```bash
+# Filter by field
+GET http://localhost:1337/api/articles?filters[slug][$eq]=my-post
+
+# Multiple filters
+GET http://localhost:1337/api/articles?filters[category][name][$eq]=Marketing&filters[publishedAt][$notNull]=true
+
+# Sort
+GET http://localhost:1337/api/articles?sort=publishedAt:desc
+
+# Pagination
+GET http://localhost:1337/api/articles?pagination[page]=1&pagination[pageSize]=10
+```
+
+### Create document
+
+```bash
+POST http://localhost:1337/api/articles
+Content-Type: application/json
+Authorization: Bearer {api_token}
+
+{
+  "data": {
+    "title": "New Article",
+    "slug": "new-article",
+    "body": "Article content here",
+    "category": "{category_documentId}"
+  }
+}
+```
+
+### Update document
+
+```bash
+PUT http://localhost:1337/api/articles/{documentId}
+Content-Type: application/json
+Authorization: Bearer {api_token}
+
+{
+  "data": {
+    "title": "Updated Title"
+  }
+}
+```
+
+### Delete document
+
+```bash
+DELETE http://localhost:1337/api/articles/{documentId}
+
+Authorization: Bearer {api_token}
+```
+
+### Get draft content
+
+```bash
+# Strapi 5 uses status parameter (replaces v4 publicationState)
+GET http://localhost:1337/api/articles?status=draft
+
+Authorization: Bearer {api_token}
+```
+
+Publishing and unpublishing are managed through the Strapi admin panel or Document Service API (server-side). The public REST API does not expose dedicated publish/unpublish endpoints.
+
+### Populate relations and components
+
+```bash
+# Populate all relations
+GET http://localhost:1337/api/articles?populate=*
+
+# Populate specific relations
+GET http://localhost:1337/api/articles?populate[0]=author&populate[1]=category
+
+# Deep populate
+GET http://localhost:1337/api/articles?populate[author][populate]=avatar
+```
+
+## CLI Commands
+
+```bash
+# Create new Strapi project
+npx create-strapi@latest my-project
+
+# Start development server
+strapi develop
+
+# Build admin panel
+strapi build
+
+# Generate content type
+strapi generate content-type
+
+# Generate controller
+strapi generate controller
+
+# Add GraphQL plugin
+npm install @strapi/plugin-graphql
+```
+
+## Key Objects
+
+- **Content Type** — Schema definition (collection type or single type)
+- **Document** — Content item identified by `documentId` (Strapi 5 pattern)
+- **Component** — Reusable field group (e.g., SEO fields, CTA block)
+- **Dynamic Zone** — Flexible content area accepting multiple component types
+- **Media** — Files managed through the Media Library
+- **Locale** — i18n locale for content translation (plugin-based)
+
+## When to Use
+
+- Self-hosted CMS with full data ownership
+- Budget-conscious projects (no per-seat pricing)
+- Custom admin panel or plugin requirements
+- Teams with DevOps capability
+- Projects needing both REST and GraphQL access
+
+## Rate Limits
+
+- Self-hosted: No built-in rate limits (configure via middleware or reverse proxy)
+- Strapi Cloud: Varies by plan
+- Recommended: Add rate limiting middleware for production APIs
+
+## Relevant Skills
+
+- content-strategy (CMS selection, content modeling)
+- programmatic-seo (CMS as data source for generated pages)
+- site-architecture (URL structure from CMS slugs)