Contentstack vibe-docs skill

# Contentstack Vibe Docs

This repo is an AI agent skill (~10,000 lines across 20 reference files). **Never read all files.** Use the routing table to read only the 1–3 files needed for the current task.

## Routing Table

| Task | File |
|------|------|
| Quick code pattern lookup | `references/QUICK_REFERENCE.md` |
| Contentstack basics | `references/concepts/base-concepts.md` |
| Region/endpoint config | `references/concepts/regions.md` |
| Fetch content (REST) | `references/api/rest-api.md` |
| Fetch content (GraphQL) | `references/api/graphql-api.md` |
| CRUD / publish content | `references/api/content-management-api.md` |
| Image transforms | `references/api/image-delivery-api.md` |
| TypeScript Delivery SDK | `references/sdk/delivery-sdk.md` |
| Live Preview concepts | `references/live-preview/concepts.md` |
| Live Preview CSR (ssr:false) | `references/live-preview/csr-mode.md` |
| Live Preview SSR (ssr:true) | `references/live-preview/ssr-mode.md` |
| Next.js integration | `references/frameworks/nextjs.md` |
| Nuxt integration | `references/frameworks/nuxt.md` |
| Gatsby integration | `references/frameworks/gatsby.md` |
| OAuth / Auth.js | `references/authentication/oauth.md` |
| CLI plugins | `references/extensions/cli-plugins.md` |
| Developer Hub apps | `references/extensions/devhub-apps.md` |
| Real-world examples | `references/examples/practical-examples.md` |
| Package versions | `references/VERSIONS.md` |

## Common Task Combos

| Scenario | Files (in order) |
|----------|-----------------|
| New Next.js project | base-concepts → delivery-sdk → nextjs |
| New Nuxt project | base-concepts → delivery-sdk → nuxt |
| Add Live Preview (Next.js) | live-preview/concepts → ssr-mode → nextjs |
| Add Live Preview (Nuxt) | live-preview/concepts → csr-mode → nuxt |
| Content pipeline (CRUD) | content-management-api |
| Responsive images | image-delivery-api |
| Full-stack with auth | delivery-sdk → nextjs → oauth |
| Content migration | content-management-api → regions |

## Decision Helpers

### Which API?

- **Read published content** → REST API, GraphQL API, or Delivery SDK
- **Create/update/delete/publish** → Content Management API (server-side only)
- **Image resize/crop/format** → Image Delivery API

### Which SDK?

- `@contentstack/delivery-sdk` — reading content (frontend or backend)
- `@contentstack/management` — writing content (backend only, never frontend)

### Which Live Preview mode?

The `ssr` setting controls how updates work inside the CMS iframe, NOT the site's rendering strategy.

- **`ssr: false`** — postMessage: CMS pushes data, client JS re-renders instantly
- **`ssr: true`** — iframe refresh: server reads `?live_preview=hash&entry_uid=...` query params

## Stack Init Pattern

```typescript
import contentstack from "@contentstack/delivery-sdk";
import { getContentstackEndpoints } from "@timbenniks/contentstack-endpoints";

const endpoints = getContentstackEndpoints(
  process.env.CONTENTSTACK_REGION || "us",
  true
);

export const stack = contentstack.stack({
  apiKey: process.env.CONTENTSTACK_API_KEY!,
  deliveryToken: process.env.CONTENTSTACK_DELIVERY_TOKEN!,
  environment: process.env.CONTENTSTACK_ENVIRONMENT!,
  region: process.env.CONTENTSTACK_REGION || "us",
  live_preview: {
    enable: true,
    preview_token: process.env.CONTENTSTACK_PREVIEW_TOKEN,
    host: endpoints.contentPreview,
  },
});
```

## Core Packages

| Package | Min Version |
|---------|------------|
| `@contentstack/delivery-sdk` | `>=4.10.3` |
| `@contentstack/live-preview-utils` | `>=4.1.2` |
| `@contentstack/management` | `>=1.25.1` |
| `@timbenniks/contentstack-endpoints` | `>=2.1.0` |
| Node.js | `>=20.0.0` |

## Security — Non-negotiable

- **NEVER** ask for or output actual API keys, tokens, or secrets
- **ALWAYS** use `process.env.*` references in code
- **NEVER** hardcode credentials or commit `.env` files
- **NEVER** use Management Tokens in frontend code
- If a developer pastes a real token, warn them and suggest rotation

## Red Flags

- Reading all reference files instead of routing to the right 1–3
- Skipping error handling (always try-catch async operations)
- Mixing Delivery SDK patterns with Management SDK patterns
- Mixing REST and GraphQL patterns incorrectly
- Forgetting `.includeReference()` when content types have references
- Hardcoding region endpoints instead of using `@timbenniks/contentstack-endpoints`

## Questions to Ask First

1. **Region?** (US, EU, AU, Azure, GCP) — determines endpoints
2. **Credentials in env vars?** (never ask for actual values)
3. **Framework?** (Next.js, Nuxt, Gatsby, React, Vue)
4. **Data fetching?** (client-side vs server-side) — determines Live Preview mode
5. **Content types needed?** — shapes query patterns
6. **Need references/modular blocks?** — rendering patterns
7. **Multiple locales?** — locale handling