create-content-sdk-app 2.0.0 → 2.0.2-canary.0

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-component-registration/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: content-sdk-component-registration
+description: Registers Sitecore components in the component map so layout and editing can resolve them. App Router uses .sitecore/component-map.ts (Server) and .sitecore/component-map.client.ts (Client). Use when registering a new component or when layout/editor cannot find a component.
+---
+
+# Content SDK Component Registration (App Router)
+
+Register components in the Sitecore component maps so the layout and editing pipeline can resolve and render them. This app has **two** maps: server and client.
+
+## When to Use
+
+- After scaffolding or adding a new Sitecore component (must be registered).
+- User reports a component not rendering, "component not found," or layout/placeholder showing raw component name.
+- Task involves `.sitecore/component-map.ts` or `.sitecore/component-map.client.ts`.
+- User asks how to register a component or fix component resolution.
+
+## How to perform
+
+- Open `.sitecore/component-map.ts` (Server) or `.sitecore/component-map.client.ts` (Client). Add an entry mapping the layout component name to the React component import. Keep keys consistent with layout and existing map entries.
+
+## Hard Rules
+
+- Every component rendered from Sitecore layout must be registered. Keep the maps in sync with `src/components/`.
+- **Server components** (no `'use client'`): Register in `.sitecore/component-map.ts` only.
+- **Client components** (`'use client'`): Register in `.sitecore/component-map.client.ts` only. Editing API routes use both maps (e.g. `clientComponents` from the client map).
+- Use consistent component names (same key in map as used in layout). Follow existing naming in the maps.
+- Do not remove or rename registrations without updating all references (layout, editing routes).
+
+## Stop Conditions
+
+- Stop if it is unclear whether the new component is Server or Client; ask or follow app convention.
+- Stop if modifying the maps would break existing layout or editing; suggest a safe change or ask for confirmation.
+- Do not edit `.sitecore/metadata.json` or import-map unless the task explicitly requires it.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for component maps and editing routes.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-component-scaffold/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: content-sdk-component-scaffold
+description: Creates new Sitecore components with correct file structure, props interface, and placement under src/components/. Use when adding a new component from scratch or scaffolding a component. App Router: decide Server vs Client and register in the appropriate map.
+---
+
+# Content SDK Component Scaffold (App Router)
+
+Scaffold new Sitecore components so they integrate with the layout and editing pipeline. This app uses App Router with separate server and client component maps.
+
+## When to Use
+
+- User asks to add a new Sitecore component, create a component from scratch, or scaffold a component.
+- Task involves creating a new React component that will be rendered from Sitecore layout/placeholders.
+- User mentions "new component," "add component," or "component file structure."
+
+## How to perform
+
+- Create a new file under `src/components/` (or existing feature folder). Define props (fields, params), export a single default component.
+- Decide Server vs Client: default Server; add `'use client'` only if the component needs hooks or event handlers.
+- Register the component in the correct map (content-sdk-component-registration). Run `npm run build` to verify.
+
+## Hard Rules
+
+- Place components under `src/components/`. Use existing folder conventions.
+- Define a props interface with the component's fields (e.g. `fields: { title: Field; ... }`) and any params. Use types from `@sitecore-content-sdk/react` or the app's types.
+- Export a single default component; one component per file unless the app pattern differs.
+- **Server vs Client:** Use Server Components by default. Add `'use client'` only for interactivity (hooks, event handlers). Register Server components in `.sitecore/component-map.ts`; Client components in `.sitecore/component-map.client.ts`.
+- After creating the component file, register it in the correct component map (see content-sdk-component-registration). Do not leave the component unregistered.
+
+## Stop Conditions
+
+- Stop and ask if the component should be a Server or Client Component when the app does not have a clear convention.
+- Do not create components in `.next/`, `node_modules/`, or build output.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for app structure and component maps.
+- [Skills.md](../../../Skills.md) for capability map. [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-component-variants/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: content-sdk-component-variants
+description: Implements component variants: different renderings or data-driven variants of the same component type. App Router: register in component-map.ts or component-map.client.ts as appropriate. Use when one component has multiple presentations.
+---
+
+# Content SDK Component Variants (App Router)
+
+One component definition can have multiple presentations or data-driven variants. Keep registration and layout aligned. This app does not use getComponentData; layout/placeholder data comes from getPage.
+
+## When to Use
+
+- User asks for different "variants," "versions," or "presentations" of a component.
+- Task involves rendering the same component type with different layouts or props based on data (e.g. variant field or style).
+- User mentions "component variants," "variations," or "multiple renderings."
+
+## How to perform
+
+- Prefer one component that accepts variant/style via props and branches internally; or multiple map entries if the app pattern uses one key per variant. Use layout/fields/params for variant; register in the correct component map (Server or Client). Align with existing app convention.
+
+## Hard Rules
+
+- Prefer a single component registration that accepts variant/style data (e.g. params or fields) and branches internally, over multiple map entries for the same logical component unless the app pattern uses separate registrations per variant.
+- Use props (fields, params) from layout to decide variant; do not rely on global state or URL for variant selection when data comes from Sitecore.
+- Register in `.sitecore/component-map.ts` (Server) or `.sitecore/component-map.client.ts` (Client) as appropriate. If the app uses one key per variant, register each; if one key with variant param, single registration. Follow existing app convention.
+- Keep component maps in sync with src/components/.
+
+## Stop Conditions
+
+- Stop if the variant model (one registration vs many) is unclear; ask or follow the app's existing pattern.
+- Do not add new component map entries without ensuring layout and editing can provide the corresponding data.
+- Do not assume variant field names (e.g. "variant," "style") without checking the layout definition.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) and content-sdk-component-registration for maps.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-dictionary-and-i18n/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: content-sdk-dictionary-and-i18n
+description: Dictionary and i18n for App Router: next-intl with src/i18n/routing.ts and request.ts. Request locale is site_locale; call setRequestLocale in the page; in request.ts parse and load dictionary with client.getDictionary. Use when adding or changing translated content or locale behavior.
+---
+
+# Content SDK Dictionary and i18n (App Router)
+
+This app uses **next-intl**. Locale is in the URL as [locale]. Request locale is encoded as `${site}_${locale}` for next-intl.
+
+## When to Use
+
+- User asks to add or change translated content, locale, or dictionary.
+- Task involves getDictionary, next-intl, or locale in URL/request.
+- User mentions "dictionary," "i18n," "locale," "translation," or "next-intl."
+
+## How to perform
+
+- Locales and routing: `src/i18n/routing.ts`. Request config: `src/i18n/request.ts` — parse `requestLocale` (e.g. `${site}_${locale}`), call `client.getDictionary({ locale, site })`, return `{ locale, messages }`. In the page, call `setRequestLocale(\`${site}_${locale}\`)` at the top. Use a single getDictionary per request.
+
+## Hard Rules
+
+- **Config:** `src/i18n/routing.ts` — `defineRouting({ locales, defaultLocale, localePrefix })`. Align `locales` with Sitecore languages (e.g. from sitecore.config.ts defaultLanguage).
+- **Request config:** `src/i18n/request.ts` — `getRequestConfig` receives `requestLocale`. This app uses `${site}_${locale}` (set by `setRequestLocale(\`${site}_${locale}\`)` in the page). Parse requestLocale (e.g. `split('_')`) to get site and locale; load dictionary with `client.getDictionary({ locale, site })` and return `{ locale, messages }`.
+- **In the page:** Call `setRequestLocale(\`${site}_${locale}\`)` at the **top** of the page so next-intl and request config see the correct locale. Do not omit when adding new page branches.
+- **Do not** change the `${site}_${locale}` convention without updating request.ts and all pages that call setRequestLocale.
+- Use a single client.getDictionary per request for the active site/locale. Never assume locale from headers or global state; use route params (site, locale).
+
+## Stop Conditions
+
+- Stop if the user wants to change to a different encoding for requestLocale; this affects request.ts and all setRequestLocale call sites.
+- Stop if adding a new locale without confirming it exists in Sitecore and in routing.ts.
+- Do not duplicate dictionary fetching (e.g. in layout and page) without a clear need.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for next-intl, setRequestLocale, and getDictionary usage.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-editing-safe-rendering/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: content-sdk-editing-safe-rendering
+description: Ensures components render safely in XM Cloud editing and preview. App Router uses draftMode() and getPreview/getDesignLibraryData from searchParams. Use when making components work in the Sitecore editor or fixing preview/editing behavior.
+---
+
+# Content SDK Editing-Safe Rendering (App Router)
+
+Ensure components behave correctly in XM Cloud editing, preview, and design library. This app uses **draftMode()** and **searchParams** for editing data.
+
+## When to Use
+
+- User asks about editing, preview, design library, or "component not working in editor."
+- Task involves draft mode, editing chromes, or design library integration.
+- Fixing issues where components render differently or break in editor vs published.
+- User mentions getPreview, getDesignLibraryData, or editing API routes.
+
+## How to perform
+
+- In the page or layout: call `draftMode()`; when enabled, read editing params from searchParams, use `isDesignLibraryPreviewData(editingParams)` to choose getDesignLibraryData vs getPreview; otherwise use getPage. Editing routes: config route uses `createEditingConfigRouteHandler`, render route uses `createEditingRenderRouteHandlers`; set `dynamic = 'force-dynamic'` on both.
+
+## Hard Rules
+
+- Use `draftMode()` in Server Components (e.g. in the page or [site] layout). When `draft.isEnabled`, get editing params from **searchParams** and use `isDesignLibraryPreviewData(editingParams)` to distinguish: if true, use `client.getDesignLibraryData(editingParams)`; otherwise use `client.getPreview(editingParams)`. When not in draft mode, use `getPage(path ?? [], { site, locale })`.
+- Do not assume editing/preview context in components that might run in static or non-editing contexts; guard on `draftMode()`.
+- Editing API routes: `src/app/api/editing/config/route.ts` uses `createEditingConfigRouteHandler({ components, clientComponents, metadata })` (import from `.sitecore/component-map`, `.sitecore/component-map.client`, `.sitecore/metadata.json`). `src/app/api/editing/render/route.ts` uses `createEditingRenderRouteHandlers({})`. Set `export const dynamic = 'force-dynamic'` on both. Do not duplicate client creation; config and render routes use the same component maps as the app.
+- Never commit editing secrets; use environment variables and document in .env.example only.
+
+## Stop Conditions
+
+- Stop and clarify if the issue is preview vs design library vs published; behavior differs.
+- Do not change proxy or middleware order to "fix" editing; editing is driven by API routes and draft/preview data.
+- Do not recommend disabling secret validation without explicit user request and warning.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for data fetching, preview flow, and editing routes.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-field-usage-image-link-text/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: content-sdk-field-usage-image-link-text
+description: Renders Sitecore fields using SDK field components (Text, RichText, Image, Link) with proper validation and fallbacks. Use when rendering content fields or when the user mentions Text, RichText, Image, Link, or field components.
+---
+
+# Content SDK Field Usage (App Router)
+
+Use SDK field components to render Sitecore fields with proper validation and fallbacks.
+
+## When to Use
+
+- User asks how to render a title, body, image, or link from Sitecore.
+- Task involves displaying content fields, fixing empty/broken images or links, or using RichText/Text/Image/Link components.
+- User mentions "field," "Image," "Link," "Text," "RichText," or "field value."
+
+## How to perform
+
+- Use SDK field components: `<Text field={fields?.title} />`, `<RichText field={fields?.content} />`, `<Image field={fields?.image} />`, `<Link field={fields?.link} />`. Guard with `fields?.` when optional; use tag prop on Text when needed. Do not hardcode media or link URLs from Sitecore.
+
+## Hard Rules
+
+- Prefer SDK field components over manual field value extraction: `<Text field={fields?.title} />`, `<RichText field={fields?.content} />`, `<Image field={fields?.image} />`, `<Link field={fields?.link} />`. Use tag prop for Text when needed (e.g. tag="h1").
+- Validate or guard field existence before rendering when fields can be optional (e.g. `fields?.title`). Handle null/undefined and empty fields gracefully.
+- Do not hardcode image or link URLs when the data comes from Sitecore; use the field components or helpers that resolve media/URLs.
+- Follow the app's import pattern (e.g. from lib or components).
+
+## Stop Conditions
+
+- Stop if the field structure (name or type) is unknown; suggest checking the layout/data shape or asking the user.
+- Do not assume field names (e.g. "title") without confirmation when the template might use different names.
+- Do not commit or log raw field values that might contain PII or secrets.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for component and Sitecore patterns.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-graphql-data-fetching/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: content-sdk-graphql-data-fetching
+description: Fetches page data and dictionary via the single Sitecore client. App Router: getPage(path ?? [], { site, locale }), getDictionary, getAppRouterStaticParams; for preview use draftMode() and getPreview/getDesignLibraryData from searchParams. Use when fetching page or dictionary content.
+---
+
+# Content SDK GraphQL Data Fetching (App Router)
+
+All Sitecore data fetching goes through the single client in `src/lib/sitecore-client.ts`. Use getPage, getDictionary, and related methods correctly. This app does **not** use getComponentData; layout data comes from getPage.
+
+## When to Use
+
+- User asks how to fetch page data, layout, or dictionary phrases.
+- Task involves getPage, getDictionary, getErrorPage, getPreview, getDesignLibraryData, or getAppRouterStaticParams.
+- User mentions "sitecore client," "Layout Service," "page data," or "dictionary."
+
+## How to perform
+
+- Use the client from `src/lib/sitecore-client.ts` only. In the catch-all page: `await params`, then `client.getPage(path ?? [], { site, locale })`. For SSG use `generateStaticParams` and `client.getAppRouterStaticParams(siteNames, locales)`. For preview use `draftMode()` and `getPreview`/`getDesignLibraryData` from searchParams.
+
+## Hard Rules
+
+- Use the single SitecoreClient instance in `src/lib/sitecore-client.ts`. Do not create a second client or instantiate SitecoreClient elsewhere.
+- Pass **site** and **locale** from route params (e.g. `await params` in the page). Do not rely on global state for site/locale in server code.
+- **Catch-all page:** `client.getPage(path ?? [], { site, locale })`. Params are a Promise (Next.js 15+); use `await params` to get `{ site, locale, path? }`.
+- **Preview:** Use `draftMode()`; if `draft.isEnabled`, use `client.getPreview(editingParams)` or `client.getDesignLibraryData(editingParams)` from **searchParams**. Otherwise use getPage with site and locale.
+- **SSG:** `generateStaticParams` — use `client.getAppRouterStaticParams(siteNames, locales)` where site names come from `.sitecore/sites.json` (e.g. `sites.map((s) => s.name)`), locales from `src/i18n/routing.ts` (e.g. `routing.locales.slice()`). Return at least one default param when not generating full paths (e.g. `{ site, locale, path: [] }`).
+- Config for the client comes from `sitecore.config.ts`; use environment variables, never hardcode secrets.
+
+## Stop Conditions
+
+- Stop if the task requires moving the client to another folder without clear requirement; suggest keeping a single instance in lib.
+- Do not add direct GraphQL or fetch to Layout Service bypassing the client unless the task explicitly requires it.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for SitecoreClient, getPage, getDictionary, and SSG.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-multisite-management/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: content-sdk-multisite-management
+description: Handles multisite: site resolution, .sitecore/sites.json, and proxy in src/proxy.ts. App Router proxy order is fixed: LocaleProxy → AppRouterMultisiteProxy → RedirectsProxy → PersonalizeProxy. Use when working with multiple sites or hostnames.
+---
+
+# Content SDK Multisite Management (App Router)
+
+Site resolution from request (e.g. hostname or cookie); proxy rewrites to /[site]/[locale]/...path. **Locale must run first** so next-intl and multisite see the correct locale.
+
+## When to Use
+
+- User asks about multiple sites, hostnames, or site resolution.
+- Task involves .sitecore/sites.json, multisite config, or proxy/middleware for site.
+- User mentions "multisite," "site resolution," "hostname," or "sites.json."
+
+## How to perform
+
+- Site list: `.sitecore/sites.json`. Proxy logic lives in `src/proxy.ts`; ensure `src/middleware.ts` re-exports it if present. Keep chain order: LocaleProxy → AppRouterMultisiteProxy → RedirectsProxy → PersonalizeProxy. Exclude API, _next, static assets in the matcher.
+
+## Hard Rules
+
+- Site list is in `.sitecore/sites.json` (typically generated by Sitecore CLI or deployment). Avoid hand-editing unless the format is known.
+- **Proxy:** Implemented in `src/proxy.ts`. Next.js runs middleware from `middleware.ts` at root or in `src/` — if the app only has `proxy.ts`, add `src/middleware.ts` that re-exports it.
+- **Chain order is fixed:** LocaleProxy → AppRouterMultisiteProxy → RedirectsProxy → PersonalizeProxy. **Do not change this order.** LocaleProxy runs first so i18n and multisite see the correct locale. AppRouterMultisiteProxy rewrites to /[site]/[locale]/[...path].
+- **Matcher:** Exclude API routes, _next/, sitemap, robots, healthz, Sitecore paths, and static assets so the proxy stays lightweight.
+- Config: sitecore.config.ts → multisite, redirects, personalize. Single SitecoreClient; pass resolved site and locale from route params into getPage, getDictionary, etc.
+
+## Stop Conditions
+
+- Stop if the user wants to reorder the proxy chain; explain that LocaleProxy must run first for App Router.
+- Stop if sites.json format is unknown and the change could break resolution; suggest checking SDK docs or CLI output.
+- Do not add a second site resolution mechanism; use the existing proxy and config.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for proxy chain, matcher, and multisite config.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-route-configuration/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: content-sdk-route-configuration
+description: Configures routing and layout for App Router. Single catch-all at src/app/[site]/[locale]/[[...path]]/page.tsx; call setRequestLocale at top of page. Use when changing routing, placeholders, or Layout.
+---
+
+# Content SDK Route Configuration (App Router)
+
+Single catch-all route and layout hierarchy. Site and locale are **in the path**; proxy rewrites incoming requests to /[site]/[locale]/...path.
+
+## When to Use
+
+- User asks to change routing, add a route, or fix 404/not-found behavior.
+- Task involves catch-all route, placeholders, root layout, or Layout.tsx.
+- User mentions "[site]," "[locale]," "[[...path]]," "placeholder," or "layout hierarchy."
+
+## How to perform
+
+- Single Sitecore page: `src/app/[site]/[locale]/[[...path]]/page.tsx`. Use `await params` for `{ site, locale, path? }`; pass to getPage and call `setRequestLocale(\`${site}_${locale}\`)` at the top. Layout: app/layout.tsx → app/[site]/layout.tsx (Bootstrap, draftMode) → page. Not-found: use getCachedPageParams and getErrorPage in the route's not-found.tsx.
+
+## Hard Rules
+
+- **Single Sitecore page:** `src/app/[site]/[locale]/[[...path]]/page.tsx`. This is the **only** page that renders Sitecore content. Do not add another page or catch-all for Sitecore content.
+- **Params:** Next.js 15+ — `params` is a Promise. Use `await params` to get `{ site, locale, path? }`. Pass `site` and `locale` to `client.getPage(path ?? [], { site, locale })`.
+- **Locale for next-intl:** Call `setRequestLocale(\`${site}_${locale}\`)` at the **top** of the page so next-intl and `src/i18n/request.ts` see the correct locale. Do not omit when adding new page branches.
+- **Layout hierarchy:** `app/layout.tsx` → `app/[site]/layout.tsx` (Bootstrap with `siteName={site}` and `draftMode()`) → page. Do not put site/locale-specific data fetching in the root layout.
+- Placeholders are rendered by the layout (e.g. Placeholder component); do not change placeholder names or structure without aligning with Sitecore layout definition.
+- **Not-found:** `src/app/[site]/[locale]/[[...path]]/not-found.tsx`. For Sitecore-driven 404 use `getCachedPageParams()` from `@sitecore-content-sdk/nextjs` for site/locale, then `client.getErrorPage(ErrorPage.NotFound, { site, locale })`.
+
+## Stop Conditions
+
+- Stop if the user wants to add a second catch-all or a different URL shape for Sitecore pages; explain single-entry-point constraint.
+- Stop if changing proxy/middleware order; order is fixed (LocaleProxy → AppRouterMultisiteProxy → RedirectsProxy → PersonalizeProxy).
+- Do not move or rename the catch-all file without updating all references.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for exact paths, params, and layout hierarchy.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-site-setup-and-env/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: content-sdk-site-setup-and-env
+description: Configures site and environment: sitecore.config.ts, environment variables, default site and language. Use when configuring the app or adding env vars. Document in .env.example only; never commit .env or .env.local.
+---
+
+# Content SDK Site Setup and Environment (App Router)
+
+Central config in sitecore.config.ts; all secrets and environment-specific values via env vars.
+
+## When to Use
+
+- User asks to configure site, default language, API host, or environment.
+- Task involves sitecore.config.ts, .env, or defaultSite/defaultLanguage.
+- User mentions "config," "environment variables," "API key," or "default site."
+
+## How to perform
+
+- Edit `sitecore.config.ts` with `defineConfig`; read all secrets and env-specific values from `process.env.*`. Add or change vars in `.env.example` (or `.env.remote.example` / `.env.container.example`) with placeholders; never commit `.env` or `.env.local`.
+
+## Hard Rules
+
+- Use `sitecore.config.ts` with `defineConfig` from the SDK. Expose api (edge, local), defaultSite, defaultLanguage, editingSecret, multisite, redirects, personalize as needed.
+- All sensitive or environment-specific values must come from environment variables (e.g. process.env.SITECORE_API_KEY). Never hardcode API keys, secrets, or production URLs in source.
+- Document every new or changed env var in `.env.example` (or `.env.remote.example` / `.env.container.example`). Use placeholder or empty value and a short comment; never put real secrets in example files.
+- Never commit `.env` or `.env.local`; they are gitignored. Example files are the source of truth for which vars exist.
+
+## Stop Conditions
+
+- Stop if the user wants to commit real secrets or production values; insist on env vars and .env.example only.
+- Stop if adding a new env var would require CI or deployment changes without explicit instruction; document the var and note that deployment must set it.
+- Do not edit .next/, node_modules/, or lockfiles unless the task explicitly requires it.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for boundaries and env rules.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-sitemap-robots/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: content-sdk-sitemap-robots
+description: Sitemap and robots.txt for App Router: src/app/api/sitemap/route.ts and src/app/api/robots/route.ts with createSitemapRouteHandler and createRobotsRouteHandler. Rewrites in next.config.ts. Use when configuring sitemap, robots.txt, or SEO.
+---
+
+# Content SDK Sitemap and Robots (App Router)
+
+Sitemap and robots.txt are served via **route handlers** and rewrites. Use the SDK route handler helpers and sites from .sitecore/sites.json.
+
+## When to Use
+
+- User asks to add or change sitemap or robots.txt.
+- Task involves SEO, sitemap.xml, or robots route.
+- User mentions "sitemap," "robots," "SEO," or "rewrites."
+
+## How to perform
+
+- Sitemap: `src/app/api/sitemap/route.ts` with `createSitemapRouteHandler({ client, sites })`; robots: `src/app/api/robots/route.ts` with `createRobotsRouteHandler({ client, sites })`. Use sites from `.sitecore/sites.json`. Add rewrites in `next.config.ts` for `/sitemap*.xml` and `/robots.txt` with `locale: false`. Set `dynamic = 'force-dynamic'` if needed.
+
+## Hard Rules
+
+- **Sitemap:** `src/app/api/sitemap/route.ts` — use `createSitemapRouteHandler({ client, sites })`. Export `{ GET }`. Use `sites` from `.sitecore/sites.json`. Set `export const dynamic = 'force-dynamic'` if the handler relies on request.
+- **Robots:** `src/app/api/robots/route.ts` — use `createRobotsRouteHandler({ client, sites })`. Same pattern.
+- **Rewrites:** In `next.config.ts`, add rewrites for `/sitemap*.xml` and `/robots.txt` to these route handlers. Use `locale: false` so they are not localized.
+- Use the same SitecoreClient instance as the rest of the app; do not create a dedicated client for sitemap/robots.
+- Avoid hardcoding the site list; use .sitecore/sites.json.
+
+## Stop Conditions
+
+- Stop if the user wants to serve sitemap/robots from a different origin or with different auth; document and suggest proxy or edge config.
+- Do not add new env vars for sitemap/robots without documenting them in .env.example.
+- Do not change rewrite paths without updating docs and any references.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for API routes and rewrites.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-troubleshoot-editing/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: content-sdk-troubleshoot-editing
+description: Troubleshoots XM Cloud editing, preview, and design library for App Router. Check draftMode(), getPreview/getDesignLibraryData from searchParams, setRequestLocale, and component maps. Use when editing or preview does not behave as expected.
+---
+
+# Content SDK Troubleshoot Editing (App Router)
+
+This skill focuses on **diagnosing** editing, preview, and design library issues. For implementing editing-safe rendering (draftMode, getPreview/getDesignLibraryData, API routes), use the **content-sdk-editing-safe-rendering** skill; the two are complementary (implementation vs. troubleshooting).
+
+Diagnose and fix editing, preview, and design library issues without breaking the single client or proxy order. This app uses **draftMode()** and **searchParams** for preview data.
+
+## When to Use
+
+- User reports that editing, preview, or design library is broken or inconsistent.
+- Task involves debugging "not working in editor," missing chromes, or wrong data in preview.
+- User mentions "editing broken," "preview not working," "design library," or "editor issues."
+
+## How to perform
+
+- Confirm `draftMode()` and searchParams-based getPreview/getDesignLibraryData; ensure `setRequestLocale` is called at the top of the page. Verify editing API routes are not rewritten (check proxy matcher) and both component maps include the component. Check env (editingSecret, API config) and .env.example documentation.
+
+## Hard Rules
+
+- **Preview flow:** Use `draftMode()` in Server Components; when enabled, use `client.getPreview(editingParams)` or `client.getDesignLibraryData(editingParams)` from **searchParams**. Ensure site/locale are passed correctly (e.g. from route params or editingParams).
+- **next-intl:** Ensure `setRequestLocale(\`${site}_${locale}\`)` is called at the top of the page; missing setRequestLocale can cause locale or dictionary issues in editor.
+- Editing API routes (`src/app/api/editing/config/route.ts`, `editing/render/route.ts`) must be reachable and use the same component maps (component-map.ts and component-map.client.ts) and config as the app. Check matcher in proxy.ts so /api/editing is not rewritten or blocked.
+- Check that both component maps include all components used in the layout; missing registration causes "component not found" in editor.
+- Environment: editingSecret and API config must be set (in env); document in .env.example only. Do not log or commit secrets.
+
+## Stop Conditions
+
+- Stop if the fix would require changing CI, deployment, or XM Cloud project settings; suggest the user do that and document the required env or config.
+- Stop if the issue might be in Sitecore (layout, template) rather than the app; suggest checking layout and content in XM Cloud.
+- Do not recommend disabling security (e.g. skipping secret validation) without explicit user request and warning.
+
+## References
+
+- content-sdk-editing-safe-rendering skill and [AGENTS.md](../../../AGENTS.md) for preview and editing flow.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-upgrade-assistant/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: content-sdk-upgrade-assistant
+description: Guides upgrading @sitecore-content-sdk/* packages: version bumps, breaking changes, migration steps. Use when moving to a newer SDK or package version. Check Content SDK repo CHANGELOG and upgrade guides.
+---
+
+# Content SDK Upgrade Assistant (App Router)
+
+Upgrade @sitecore-content-sdk/* packages safely; follow the Content SDK repo changelog and migration guides.
+
+## When to Use
+
+- User asks to upgrade SDK packages, update to a new version, or apply a migration.
+- Task involves version bumps, @sitecore-content-sdk/* dependencies, or breaking changes.
+- User mentions "upgrade," "migration," "new version," or "breaking change."
+
+## How to perform
+
+- Bump all @sitecore-content-sdk/* to consistent versions; read the Content SDK repo CHANGELOG (and MIGRATION/upgrade docs) for breaking changes and migration steps. Update package.json, run `npm install` and `npm run build`; test editing and preview after upgrade.
+
+## Hard Rules
+
+- Prefer upgrading all @sitecore-content-sdk/* packages together to a consistent set of versions unless the user requests a partial upgrade. Check peer dependencies and compatibility.
+- Update dependencies in package.json; run `npm install` and `npm run build`. Test editing and preview after upgrade.
+- Read the **Content SDK repository** CHANGELOG (and any MIGRATION.md or upgrade guide) for breaking changes and required code/config updates. Apply migration steps before or with the version bump.
+- Do not edit .next/, node_modules/, or lockfiles unless required for the upgrade. Do not change CI or root tooling unless the task explicitly includes it.
+
+## Stop Conditions
+
+- Stop if the target version is not specified or unclear; ask or suggest checking the Content SDK CHANGELOG and supported versions.
+- Stop if a breaking change requires product or deployment decisions (e.g. new env vars, config schema); list required changes and ask the user to confirm.
+
+## References
+
+- Content SDK repo [CHANGELOG](https://github.com/Sitecore/content-sdk/blob/dev/CHANGELOG.md) and upgrade docs.
+- [AGENTS.md](../../../AGENTS.md) for build commands.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).