@mikulgohil/ai-kit 1.8.1 → 1.10.0

package/guides/token-saving-tips.md

@@ -45,6 +45,21 @@ If the AI doesn't get it right in 2 attempts:
 2. The task might be too complex for a single prompt
 3. Take over manually — you'll save tokens and time
 
+## Know Your Context Limits
+
+Claude Code now supports up to **1M tokens of context** (Opus 4.6) with **64K default output** (128K ceiling). This is massive — but context still costs money.
+
+| Model | Context Window | Default Output | Max Output |
+|-------|---------------|----------------|------------|
+| Opus 4.6 | 1M tokens | 64K tokens | 128K tokens |
+| Sonnet 4.6 | 200K tokens | 64K tokens | 128K tokens |
+
+### Use `/effort` to Control Token Spend
+Claude Code's `/effort` command lets you set reasoning effort levels. For simple tasks, lower effort saves tokens. For complex architecture decisions, higher effort produces better results.
+
+### Context Compaction
+When conversations get long, Claude Code automatically compacts earlier context. The **PostCompact hook** fires after this happens — your AI Kit hooks use it to ensure important context survives compaction.
+
 ## CLAUDE.md Is Free Context
 
 Your `CLAUDE.md` file is loaded automatically — everything in it gives the AI context without using your conversation tokens. That's why `ai-kit` generates it: better output from fewer tokens.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mikulgohil/ai-kit",
-  "version": "1.8.1",
-  "description": "AI-assisted development setup kit. Auto-detects your tech stack and generates tailored CLAUDE.md, .cursorrules, hooks, agents, context modes, slash commands, design token rules, component registries, developer guides, project principles, and spec-first workflows.",
+  "version": "1.10.0",
+  "description": "AI-assisted development setup kit. Auto-detects your tech stack (Next.js, Sitecore XM Cloud, Optimizely SaaS CMS, Tailwind, TypeScript, Turborepo) and generates tailored CLAUDE.md, .cursorrules, hooks, agents, context modes, slash commands, design token rules, component registries, developer guides, and spec-first workflows.",
   "type": "module",
   "bin": {
     "ai-kit": "./dist/index.js"
@@ -37,6 +37,13 @@
     "nextjs",
     "tailwind",
     "sitecore",
+    "sitecore-xm-cloud",
+    "sitecore-jss",
+    "optimizely",
+    "optimizely-saas-cms",
+    "optimizely-graph",
+    "optimizely-visual-builder",
+    "headless-cms",
     "docker",
     "storybook",
     "i18n",
@@ -69,7 +76,7 @@
     "url": "https://github.com/mikulgohil/ai-kit/issues"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",

package/templates/claude-md/base.md

@@ -105,6 +105,30 @@ These standards are enforced across all projects to ensure consistency.
 - Pin dependency versions — avoid `^` or `~` for critical packages
 - When adding a new dependency, note the reason in the component's doc file or PR description
 
+## Documentation Verification
+
+AI training data has a cutoff date. When working with framework APIs, **verify your knowledge is current** before writing code:
+
+### When to Verify
+- Using an API you haven't seen in this project's codebase
+- Working with recently released features (Next.js 16+, Tailwind v4, Sitecore Content SDK v2.x)
+- When you're unsure about an API signature, parameter order, or return type
+- When a build error suggests an API doesn't exist or has changed
+
+### How to Verify (in priority order)
+1. **Check this project's code first** — existing implementations are the most reliable reference
+2. **Use Context7 MCP** — if available, use `resolve-library-id` then `query-docs` to fetch current, version-specific documentation
+3. **Use llms.txt endpoints** — fetch from official AI-friendly docs:
+   - Next.js: `https://nextjs.org/docs/llms-full.txt`
+   - Sitecore XM Cloud: check the project repo for `LLMs.txt`
+4. **Use WebFetch** — fetch the specific docs page for the API in question
+
+### Rules
+- Do NOT guess at API signatures — look them up if unsure
+- Do NOT assume a library API works the same as a previous version
+- The code examples in this CLAUDE.md file are current and verified — prefer them over memory
+- When you look something up, briefly note what you found so the developer knows the source
+
 ## Code Quality
 - Match existing patterns, naming conventions, and file structure
 - Keep changes minimal — don't refactor surrounding code unless asked
@@ -170,6 +194,7 @@ AI will auto-discover and apply these when your task matches. You can also invok
 - `/document` — Generate documentation for existing code
 - `/commit-msg` — Generate conventional commit message from staged changes
 - `/env-setup` — Generate .env.example and validate environment variables
+- `/fetch-docs` — Pre-load current docs for your tech stack (run at session start)
 
 ## Scripts
 {{scripts}}

package/templates/claude-md/nextjs-app-router.md

@@ -54,10 +54,27 @@ app/
 - Use `revalidateTag(tag)` or `revalidatePath(path)` in Server Actions for on-demand ISR
 - Tag fetches with `fetch(url, { next: { tags: ['posts'] } })` for targeted revalidation
 
+## Turbopack (Next.js 16+)
+- Turbopack is stable and production-ready — use `next dev --turbopack` for ~4x faster dev startup
+- Server Fast Refresh: instant HMR for server-side changes (no full reload)
+- Supports SRI (Subresource Integrity) for security
+- Tree shakes dynamic imports automatically
+- If using custom webpack config, migrate to Turbopack-compatible patterns:
+  - Replace `webpack()` in `next.config.js` with Turbopack-native configuration
+  - Most loaders have Turbopack equivalents — check the Next.js docs
+- Web Workers: use `new Worker(new URL('./worker.ts', import.meta.url))` for proper bundling
+
+## Caching (Next.js 16+)
+- Route stale time is decoupled from segment-level data — configure independently
+- Browser cache no longer serves stale RSC (React Server Component) responses
+- Use `staleTimes` in `next.config.js` for fine-grained stale time control
+- Prefer `fetch()` cache options over route-level `revalidate` for granular control
+
 ## Common Mistakes to Avoid
 - Don't use `useEffect` for data fetching in Server Components
 - Don't import server-only code in Client Components
 - Don't use `router.push` for simple navigation — use `<Link>`
 - Don't forget to add `loading.tsx` for route transitions
 - Don't throw errors from Server Actions — return error objects instead
-- Don't use Node.js APIs in Middleware — it runs on the Edge runtime
+- Don't use Node.js APIs in Middleware — it runs on the Edge runtime
+- Don't use custom `webpack()` config in Next.js 16+ without checking Turbopack compatibility

package/templates/claude-md/optimizely-saas.md

@@ -0,0 +1,384 @@
+# Optimizely SaaS CMS
+
+## Architecture
+- This is a headless CMS project using Optimizely SaaS CMS (CMS 13+) with Next.js as the frontend
+- Content is authored in the Optimizely cloud editor and delivered via **Optimizely Graph** (GraphQL API at `https://cg.optimizely.com`)
+- Components are mapped to CMS content types through a **ComponentFactory** pattern
+- The SDK ecosystem is `@remkoj/optimizely-*` (community SDK by Remko Jantzen)
+- Visual Builder enables drag-and-drop page composition with Experiences, Sections, Rows, Columns, and Elements
+
+## SDK Packages
+
+| Package | Purpose |
+|---|---|
+| `@remkoj/optimizely-cms-react` | Core React components: `<CmsContent>`, `<CmsContentArea>`, `<CmsEditable>`, `<RichText>`, `<OptimizelyComposition>` |
+| `@remkoj/optimizely-cms-nextjs` | Next.js integration: `createPage()`, `createPublishApi()`, `createEditPageComponent()`, middleware |
+| `@remkoj/optimizely-graph-client` | GraphQL client for Optimizely Graph with HMAC/Basic/Token auth |
+| `@remkoj/optimizely-graph-functions` | GraphQL Codegen preset for generating typed queries and fragments |
+| `@remkoj/optimizely-cms-api` | REST API wrapper for CMS Integration API (content CRUD, type management) |
+| `@remkoj/optimizely-cms-cli` | CLI (`opti-cms`) for type sync, component scaffolding, factory generation |
+| `@remkoj/optimizely-graph-cli` | CLI (`opti-graph`) for webhook and source management |
+| `@remkoj/optimizely-one-nextjs` | Browser-side Optimizely products (Web Experimentation, Data Platform, Recommendations) |
+
+## Content Type Hierarchy
+
+| Type | Description | GraphQL Fragment Suffix |
+|---|---|---|
+| **Page** | Routable content with a URL path | `.page.graphql` |
+| **Block/Component** | Reusable content placed in Content Areas | `.block.graphql` or `.component.graphql` |
+| **Element** | Lightweight components for Visual Builder | `.element.graphql` |
+| **Experience** | Visual Builder top-level compositions | `.experience.graphql` |
+| **Section** | Visual Builder layout containers | `.section.graphql` |
+| **Media/Image/Video** | Asset types | N/A |
+
+## Component Patterns
+
+### Page Component (catch-all route)
+```typescript
+// src/app/[[...path]]/page.tsx
+import { createPage } from '@remkoj/optimizely-cms-nextjs/page'
+import { factory } from '@/components/factory'
+import { createClient } from '@remkoj/optimizely-graph-client'
+import { AuthMode } from '@remkoj/optimizely-graph-client'
+import { draftMode } from 'next/headers'
+
+const { CmsPage, generateMetadata, generateStaticParams } = createPage(factory, {
+  client(token?: string, mode?: 'request' | 'metadata') {
+    const client = createClient(undefined, token, { nextJsFetchDirectives: true })
+    if (mode === 'request') {
+      const { isEnabled } = draftMode()
+      if (isEnabled) {
+        client.updateAuthentication(AuthMode.HMAC)
+        client.enablePreview()
+      }
+    }
+    return client
+  },
+})
+
+export const dynamic = 'error'
+export const dynamicParams = true
+export const revalidate = false
+export default CmsPage
+export { generateMetadata, generateStaticParams }
+```
+
+### Component Factory Setup
+```typescript
+// src/components/factory.ts
+import { DefaultComponentFactory, RichTextComponentDictionary } from '@remkoj/optimizely-cms-react/rsc'
+import { CmsFactory } from './cms/index'
+
+const factory = new DefaultComponentFactory()
+factory.registerAll(RichTextComponentDictionary)
+factory.registerAll(CmsFactory)
+
+export { factory }
+```
+
+### Component Dictionary (auto-generated by `opti-cms nextjs:factory`)
+```typescript
+// src/components/cms/index.ts
+import type { ComponentTypeDictionary } from '@remkoj/optimizely-cms-react'
+
+import StandardPage from './page/StandardPage'
+import HeroBlock from './block/HeroBlock'
+import TextElement from './element/TextElement'
+
+export const CmsFactory: ComponentTypeDictionary = [
+  { type: ['Page', 'StandardPage'], component: StandardPage },
+  { type: ['Block', 'HeroBlock'], component: HeroBlock },
+  { type: ['Element', 'TextElement'], component: TextElement },
+]
+```
+
+### CMS Content Component
+```typescript
+// src/components/cms/block/HeroBlock/index.tsx
+import { CmsEditable } from '@remkoj/optimizely-cms-react/rsc'
+import { RichText } from '@remkoj/optimizely-cms-react/rsc'
+
+interface HeroBlockProps {
+  data: {
+    heading?: string
+    description?: { html?: string }
+    image?: { url?: string; altText?: string }
+    ctaText?: string
+    ctaLink?: { default?: string }
+  }
+}
+
+export default function HeroBlock({ data }: HeroBlockProps) {
+  return (
+    <CmsEditable as="section" className="hero-block">
+      {data.heading && <h1>{data.heading}</h1>}
+      {data.description && <RichText html={data.description.html} />}
+      {data.image?.url && (
+        <img src={data.image.url} alt={data.image.altText || ''} />
+      )}
+      {data.ctaText && data.ctaLink?.default && (
+        <a href={data.ctaLink.default}>{data.ctaText}</a>
+      )}
+    </CmsEditable>
+  )
+}
+```
+
+### GraphQL Fragment for a Component
+```graphql
+# src/components/cms/block/HeroBlock/HeroBlock.block.graphql
+fragment HeroBlockData on HeroBlock {
+  heading
+  description {
+    html
+  }
+  image {
+    url
+    altText
+  }
+  ctaText
+  ctaLink {
+    default
+  }
+}
+```
+
+## Visual Builder Composition
+
+The Visual Builder outputs a **composition tree** that the frontend renders recursively:
+
+```
+Experience (top-level)
+  -> Section (layout container)
+    -> Row
+      -> Column
+        -> Component (actual content element)
+```
+
+Render compositions using `<OptimizelyComposition>`:
+```typescript
+import { OptimizelyComposition } from '@remkoj/optimizely-cms-react/rsc'
+
+// The composition data comes from GraphQL and is rendered automatically
+// Structure nodes (experience, section, row, column) are layout containers
+// Component nodes are resolved through the ComponentFactory
+```
+
+## GraphQL Codegen Setup
+```typescript
+// codegen.ts
+import type { CodegenConfig } from '@graphql-codegen/cli'
+import getSchemaInfo from '@remkoj/optimizely-graph-client/codegen'
+import OptimizelyGraphPreset from '@remkoj/optimizely-graph-functions/preset'
+
+const config: CodegenConfig = {
+  schema: getSchemaInfo(),
+  documents: ['src/**/*.graphql'],
+  generates: {
+    'src/gql/': {
+      preset: OptimizelyGraphPreset,
+      presetConfig: {
+        recursion: true,
+        gqlTagName: 'gql',
+        injections: [
+          { into: 'PageData', pathRegex: 'src/components/cms/.*\\.page\\.graphql' },
+          { into: 'BlockData', pathRegex: 'src/components/cms/.*\\.(block|component|section)\\.graphql' },
+          { into: 'ElementData', pathRegex: 'src/components/cms/.*\\.element\\.graphql' },
+        ],
+      },
+    },
+  },
+}
+
+export default config
+```
+
+## Cache Invalidation Webhook
+```typescript
+// src/app/.well-known/publish/route.ts
+import createPublishApi from '@remkoj/optimizely-cms-nextjs/publish'
+
+const handler = createPublishApi({ optimizePublish: true })
+export const GET = handler
+export const POST = handler
+```
+
+## Preview / Edit Mode
+```typescript
+// src/app/preview/page.tsx
+import { createEditPageComponent } from '@remkoj/optimizely-cms-nextjs/preview'
+import { factory } from '@/components/factory'
+import { createClient } from '@remkoj/optimizely-graph-client'
+
+export default createEditPageComponent(factory, {
+  loader: getContentById,
+  clientFactory: (token) => createClient(undefined, token, { cache: false }),
+  refreshTimeout: 500,
+})
+```
+
+```typescript
+// src/app/.well-known/drafts/route.ts
+// Toggles Next.js draft mode for preview in the Optimizely editor
+```
+
+## CLI Commands
+
+### Content Type Management
+```bash
+# Pull content types from CMS to local JSON files
+npx opti-cms types:pull
+
+# Push local content type definitions to CMS
+npx opti-cms types:push
+
+# Generate component factory from content types
+npx opti-cms nextjs:factory
+
+# Scaffold new component files
+npx opti-cms nextjs:create
+
+# Generate component implementations from types
+npx opti-cms nextjs:components
+
+# Generate GraphQL fragments for components
+npx opti-cms nextjs:fragments
+```
+
+### Optimizely Graph Management
+```bash
+# Manage webhooks for cache invalidation
+npx opti-graph webhooks:list
+npx opti-graph webhooks:create
+
+# Manage content sources
+npx opti-graph sources:list
+```
+
+### GraphQL Codegen
+```bash
+# Generate typed queries and fragments
+npx graphql-codegen
+```
+
+## Content Type Definitions
+
+Content types are defined in `.opti-type.json` files:
+```json
+{
+  "key": "HeroBlock",
+  "displayName": "Hero Block",
+  "description": "A hero banner with heading, description, and CTA",
+  "baseType": "block",
+  "properties": {
+    "heading": { "type": "string", "required": true },
+    "description": { "type": "richText" },
+    "image": { "type": "contentReference" },
+    "ctaText": { "type": "string" },
+    "ctaLink": { "type": "url" }
+  }
+}
+```
+
+Style definitions use `.opti-style.json` for Visual Builder styling:
+```json
+{
+  "key": "HeroBlockStyles",
+  "displayName": "Hero Block Styles",
+  "target": "HeroBlock",
+  "properties": {
+    "theme": { "type": "select", "options": ["light", "dark"] },
+    "spacing": { "type": "select", "options": ["compact", "normal", "spacious"] }
+  }
+}
+```
+
+## Environment Setup
+
+Required `.env.local` variables:
+```
+# Optimizely Graph (content delivery)
+OPTIMIZELY_GRAPH_APP_KEY=your-app-key
+OPTIMIZELY_GRAPH_SECRET=your-secret
+OPTIMIZELY_GRAPH_SINGLE_KEY=your-single-key
+OPTIMIZELY_GRAPH_GATEWAY=https://cg.optimizely.com
+OPTIMIZELY_GRAPH_TENANT_ID=your-tenant-id
+
+# Optimizely CMS (management API)
+OPTIMIZELY_CMS_URL=https://your-instance.cms.optimizely.com
+OPTIMIZELY_CMS_CLIENT_ID=your-client-id
+OPTIMIZELY_CMS_CLIENT_SECRET=your-client-secret
+
+# Frontend
+SITE_DOMAIN=your-frontend-domain.com
+OPTIMIZELY_PUBLISH_TOKEN=your-webhook-token
+
+# Debug (optional)
+OPTIMIZELY_DEBUG=0
+```
+
+## Project File Structure
+```
+src/
+  app/
+    [[...path]]/page.tsx           # Catch-all CMS page route (createPage)
+    preview/page.tsx               # Visual editor preview page
+    .well-known/
+      drafts/route.ts              # Draft mode toggle endpoint
+      publish/route.ts             # Webhook cache invalidation endpoint
+      channel/route.ts             # Channel info endpoint
+    layout.tsx                     # Root layout
+  components/
+    factory.ts                     # ComponentFactory setup
+    cms/
+      index.ts                     # Auto-generated component dictionary
+      page/                        # Page-type components
+        StandardPage/
+          index.tsx
+          StandardPage.page.graphql
+      block/                       # Block-type components
+        HeroBlock/
+          index.tsx
+          HeroBlock.block.graphql
+      element/                     # Element-type components (Visual Builder)
+        TextElement/
+          index.tsx
+          TextElement.element.graphql
+      experience/                  # Experience-type components (Visual Builder)
+      section/                     # Section-type components (Visual Builder)
+  gql/                             # Auto-generated by GraphQL Codegen
+    functions.ts
+    client.ts
+    types.ts
+  channel.ts                       # Channel/site definition
+codegen.ts                         # GraphQL Codegen configuration
+```
+
+## Rules
+- Always use `<CmsEditable>` wrapper for components that should be editable in the Optimizely editor
+- Use `<RichText>` from `@remkoj/optimizely-cms-react/rsc` for rich text fields — never render raw HTML with `dangerouslySetInnerHTML`
+- GraphQL fragments MUST follow the naming convention: `[Name].[type].graphql` (e.g., `HeroBlock.block.graphql`)
+- Fragment file suffix determines injection target: `.page.graphql` -> PageData, `.block.graphql` -> BlockData, `.element.graphql` -> ElementData
+- Always register new components in the ComponentFactory dictionary — use `opti-cms nextjs:factory` to regenerate
+- Content type arrays use `[category, typeName]` format (e.g., `['Block', 'HeroBlock']`) — match the CMS type definition exactly
+- Use `createPage()` from `@remkoj/optimizely-cms-nextjs/page` for the catch-all route — don't build custom routing
+- Use `createPublishApi()` for the webhook endpoint — don't build custom cache invalidation
+- Handle draft mode properly: check `draftMode().isEnabled` and switch to HMAC auth with `client.enablePreview()`
+- Run `npx graphql-codegen` after changing `.graphql` files to regenerate typed queries
+- Use `opti-cms types:pull` to sync content types from CMS to local JSON — don't manually create `.opti-type.json` files from scratch
+- For Visual Builder components, follow the composition tree hierarchy: Experience > Section > Row > Column > Element
+- Import RSC (React Server Component) versions from `@remkoj/optimizely-cms-react/rsc` — not from the base package
+- Never hardcode content that should come from CMS content types
+- Keep `codegen.ts` injection patterns in sync with your component folder structure
+
+## Common Mistakes to Avoid
+- Don't render rich text with `dangerouslySetInnerHTML` — use `<RichText html={data.field.html} />`
+- Don't forget to wrap editable components with `<CmsEditable>` — the editor won't recognize them without it
+- Don't create GraphQL fragments with wrong file suffixes — `.block.graphql` and `.page.graphql` are injected into different parent fragments
+- Don't manually edit `src/components/cms/index.ts` — it's auto-generated by `opti-cms nextjs:factory`
+- Don't use `getStaticProps` or `getServerSideProps` — use `createPage()` which handles SSG/SSR/ISR automatically
+- Don't forget to run `npx graphql-codegen` after adding/modifying GraphQL fragments
+- Don't mix RSC and client component imports — use `/rsc` sub-path for Server Components
+- Don't skip the `.well-known/publish` webhook route — without it, content updates won't invalidate the cache
+- Don't hardcode the Graph gateway URL — use environment variables and let the client auto-configure
+- Don't forget HMAC auth for preview mode — public auth only returns published content

package/templates/claude-md/sitecore-xmc.md

@@ -1,7 +1,7 @@
-# Sitecore XM Cloud
+# Sitecore XM Cloud (SitecoreAI)
 
 ## Architecture
-- This is a headless CMS project using Sitecore XM Cloud with Next.js as the rendering host
+- This is a headless CMS project using Sitecore XM Cloud (part of the SitecoreAI platform) with Next.js as the rendering host
 - Components receive data through Sitecore Layout Service via `ComponentRendering` props
 - Use `@sitecore-jss/sitecore-jss-nextjs` or `@sitecore-content-sdk/nextjs` for component bindings
 

package/templates/cursorrules/base.md

@@ -60,6 +60,14 @@ These standards are enforced across all projects.
 - Prefer native browser APIs over utility libraries when reasonable
 - Note the reason for new dependencies in the doc file or PR
 
+### Documentation Verification
+- AI training data has a cutoff — verify API signatures before using unfamiliar or recently released APIs
+- Check this project's existing code first for patterns and API usage
+- Use Context7 MCP to fetch current, version-specific docs when available
+- Official llms.txt endpoints: Next.js (`https://nextjs.org/docs/llms-full.txt`)
+- Do NOT guess at API signatures — look them up if unsure
+- The code examples in these rules are current and verified — prefer them over memory
+
 ### Quality
 - Read existing code before modifying — match patterns, naming, and structure
 - Keep changes minimal and scoped to the request

package/templates/cursorrules/nextjs-app-router.md

@@ -10,4 +10,7 @@
 - Streaming: wrap slow components in `<Suspense fallback={...}>` for progressive rendering
 - ISR: use `fetch(url, { next: { revalidate: N } })` or `export const revalidate = N`
 - Middleware: place `middleware.ts` at project root, use `matcher` config, Edge-compatible APIs only
-- Route Groups: use `(groupName)/` for organization without affecting URL paths
+- Route Groups: use `(groupName)/` for organization without affecting URL paths
+- Turbopack (Next.js 16+): use `next dev --turbopack` for ~4x faster dev, Server Fast Refresh for instant HMR
+- Caching (Next.js 16+): route stale time is decoupled from data — use `staleTimes` in `next.config.js` for control
+- Don't use custom `webpack()` in Next.js 16+ without checking Turbopack compatibility

package/templates/cursorrules/optimizely-saas.md

@@ -0,0 +1,20 @@
+# Optimizely SaaS CMS Rules
+
+- This is a headless CMS project using **Optimizely SaaS CMS** with Next.js, delivered via **Optimizely Graph** (GraphQL)
+- SDK packages: `@remkoj/optimizely-cms-react`, `@remkoj/optimizely-cms-nextjs`, `@remkoj/optimizely-graph-client`
+- Use `<CmsEditable>` wrapper for all editable components — the editor won't recognize them without it
+- Use `<RichText html={data.field.html} />` from `@remkoj/optimizely-cms-react/rsc` — never use `dangerouslySetInnerHTML`
+- Import Server Component versions from `@remkoj/optimizely-cms-react/rsc` — not from the base package
+- GraphQL fragment naming: `[Name].page.graphql`, `[Name].block.graphql`, `[Name].element.graphql` — suffix determines injection target
+- Register components in ComponentFactory with `[category, typeName]` format (e.g., `['Block', 'HeroBlock']`)
+- Use `createPage()` from `@remkoj/optimizely-cms-nextjs/page` for the catch-all `[[...path]]/page.tsx` route
+- Use `createPublishApi()` for cache invalidation webhooks at `.well-known/publish/route.ts`
+- Handle draft mode: check `draftMode().isEnabled`, switch to HMAC auth, call `client.enablePreview()`
+- Run `npx graphql-codegen` after modifying `.graphql` files to regenerate typed queries
+- Use `opti-cms nextjs:factory` to regenerate the component dictionary — don't manually edit the auto-generated index
+- Content type definitions use `.opti-type.json` files — sync with `opti-cms types:pull` / `types:push`
+- Visual Builder hierarchy: Experience > Section > Row > Column > Element — render with `<OptimizelyComposition>`
+- Don't hardcode content that should come from CMS content types
+- Don't use `getStaticProps`/`getServerSideProps` — `createPage()` handles SSG/SSR/ISR automatically
+- Keep `codegen.ts` injection patterns in sync with component folder structure
+- Environment: `OPTIMIZELY_GRAPH_SINGLE_KEY` (public), `OPTIMIZELY_GRAPH_APP_KEY` + `SECRET` (HMAC auth)

package/templates/cursorrules/sitecore-xmc.md

@@ -1,4 +1,4 @@
-# Sitecore XM Cloud Rules
+# Sitecore XM Cloud (SitecoreAI) Rules
 
 - Use Sitecore field helpers (`<Text>`, `<RichText>`, `<Image>`, `<Link>`) — never render `.value` directly
 - Component names must match Sitecore rendering items exactly