Contentstack Vibe Docs

---
description: Contentstack vibe-docs skill — routing, patterns, and conventions for AI-assisted Contentstack development
alwaysApply: true
---

# Contentstack Vibe Docs

This repo is an AI agent skill. The full routing table, decision helpers, and task combinations live in [`skills/contentstack-vibe-docs/SKILL.md`](skills/contentstack-vibe-docs/SKILL.md). **Read that first.** The skill has ~13,500 lines across 34 reference files — never read them all. Route to 1-3 files per task.

Reference files live at `skills/contentstack-vibe-docs/references/`.

## Security — non-negotiable

- Never ask for, output, log, or hardcode API keys, tokens, or secrets.
- Always use `process.env.*` in code.
- Never commit `.env` files.
- Management Tokens are **server-side only** — never in frontend code or public env vars (`NEXT_PUBLIC_*`, `NUXT_PUBLIC_*`).
- Delivery Tokens and Preview Tokens are client-safe; Management Tokens are not.
- If a developer pastes a real token in the conversation, warn them and recommend rotation.

Full decision tree: `skills/contentstack-vibe-docs/references/security/tokens-authentication.md`.

## Red flags

- Reading all reference files instead of routing to the right 1-3.
- Hardcoding region endpoints — use `@timbenniks/contentstack-endpoints`.
- Sharing a module-level Contentstack client across SSR preview requests — use a per-request factory (see `skills/contentstack-vibe-docs/references/live-preview/ssr-mode.md`).
- Calling `.includeReference()` on `.query()` — correct chain: `entry().includeReference([...]).query().find()`.
- Using `.descending()` / `.ascending()` — correct: `.orderByDescending()` / `.orderByAscending()`.
- `QueryOperation.NOT_EQUAL` / `GREATER_THAN` — correct: `NOT_EQUALS` / `IS_GREATER_THAN`.
- Enum/dropdown fields without `display_type: "dropdown"` — CMA rejects.
- `is_page: true` without a `url` field in the schema — CMA rejects and Visual Builder can't route.
- Mixing REST and GraphQL patterns, or Delivery SDK patterns with Management SDK patterns, in one call.
- `Contentstack.Stack()` (v3 style) instead of `contentstack.stack()` (v4+).
- Ignoring `X-RateLimit-Reset` and busy-looping on 429s.

## Ask before coding

- **Region?** (US / EU / AU / Azure NA-EU / GCP NA-EU) — every endpoint depends on this.
- **Credentials in env vars?** (never ask for actual values).
- **Framework?** (Next.js / Nuxt / Gatsby / other).
- **Data fetched server-side or client-side?** — determines Live Preview mode.