create-content-sdk-app 2.0.0 → 2.0.1

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).

package/dist/templates/nextjs-app-router/.sitecore/import-map.server.ts

@@ -16,7 +16,7 @@ import { Suspense } from 'react';
 import React from 'react';
 import { componentMap } from '.sitecore/component-map';
 import client from 'src/lib/sitecore-client';
-import { pageView } from '@sitecore-cloudsdk/events/browser';
+import { pageView } from '@sitecore-content-sdk/events';
 import config from 'sitecore.config';
 
 const importMapServer = [
@@ -48,7 +48,7 @@ const importMapServer = [
     exports: [{ name: 'default', value: client }],
   },
   {
-    module: '@sitecore-cloudsdk/events/browser',
+    module: '@sitecore-content-sdk/events',
     exports: [{ name: 'pageView', value: pageView }],
   },
   {

package/dist/templates/nextjs-app-router/AGENTS.md

@@ -120,15 +120,14 @@ These are the main head-app–specific concepts. Details are in the sections bel
 - **SSG:** `generateStaticParams` — use `client.getAppRouterStaticParams(sites, routing.locales)` (sites from `.sitecore/sites.json`). Return at least one default param when not generating full paths (e.g. dev or when `generateStaticPaths` is off).
 - **Metadata:** `generateMetadata` in the same segment can call `client.getPage(path ?? [], { site, locale })` and derive `title` (e.g. from route fields). Next.js will cache as appropriate.
 
-### Server vs Client components and PPR
+### Server vs Client components
 
 - **Default:** Components are Server Components. Use `'use client'` only for interactivity (e.g. hooks, event handlers).
-- **PPR (Partial Prerendering):** Dynamic work (e.g. `draftMode()`, data fetching) is wrapped in `<Suspense>` (e.g. `DynamicPageContent`, `DynamicLayoutContent`, `DynamicNotFoundContent`). Keep the same pattern when adding new dynamic branches so PPR and caching behave correctly.
 - **draftMode:** Used in layout and page; call `await draftMode()` in Server Components that need to know preview state.
 
 ### Not-found and error page
 
-- **Segment not-found:** `src/app/[site]/[locale]/[[...path]]/not-found.tsx`. For Sitecore-driven 404, read site/locale from the rewrite header: `parseRewriteHeader(headers())` from `@sitecore-content-sdk/nextjs/utils`, then `client.getErrorPage(ErrorPage.NotFound, { site, locale })` and render layout if a page is returned. Wrap in `Suspense` if using async logic.
+- **Segment not-found:** `src/app/[site]/[locale]/[[...path]]/not-found.tsx`. Uses `getCachedPageParams()` from `@sitecore-content-sdk/nextjs` for site/locale, then `client.getErrorPage(ErrorPage.NotFound, { site, locale })` and renders layout if a page is returned.
 - **Root not-found:** `src/app/not-found.tsx` — minimal fallback when no segment handles the route.
 
 ### API route handlers
@@ -154,7 +153,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 - **Quick checks:** If locale or dictionary is wrong, ensure `setRequestLocale(\`${site}_${locale}\`)` is called at the top of the page and `src/i18n/request.ts` parses `requestLocale` and calls `client.getDictionary`. If not-found doesn't show Sitecore content, use `parseRewriteHeader(headers())` for site/locale. Always `await params` (Next.js 15+).
 - **Security:** Use only environment variables in `sitecore.config.ts`; never hardcode API keys, editing secret, or host URLs. Do not expose secrets in client-side code or in logs. Validate and sanitize user input at boundaries.
-- **Performance:** Keep middleware lightweight; use the proxy `matcher` so it does not run on API routes, `_next`, sitemap, robots, or static assets. Use Server Components and Suspense for dynamic content; add `'use client'` only where interactivity is needed. Use `generateStaticParams` and caching as in the existing page.
+- **Performance:** Keep middleware lightweight; use the proxy `matcher` so it does not run on API routes, `_next`, sitemap, robots, or static assets. Use Server Components for data fetching; add `'use client'` only where interactivity is needed. Use `generateStaticParams` and caching as in the existing page.
 - **Sitecore patterns:** Use SDK field components (`<Text>`, `<RichText>`, `<Image>`) and validate field existence before render. Register new components in `.sitecore/component-map.ts` and `.sitecore/component-map.client.ts` as appropriate. Use the single Sitecore client in `lib/sitecore-client.ts` for all data fetching.
 - **Consistency:** Follow the existing patterns in `[site]/[locale]/[[...path]]/page.tsx`, layout hierarchy, `i18n/request.ts` (site_locale), and API route handlers. When adding routes or rewrites, keep the middleware matcher and next-intl config in sync.
 
@@ -168,7 +167,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 | Pass `{ site, locale }` to `client.getPage` and `getDictionary` | Assume site/locale from headers inside page without using params |
 | Run LocaleProxy before AppRouterMultisiteProxy in middleware | Change proxy order (locale must run first for i18n) |
 | Call `setRequestLocale(\`${site}_${locale}\`)` in the page for next-intl | Omit setRequestLocale when adding new page branches |
-| Use Suspense around async Server Components that use draftMode or fetch | Put async data fetching in client components when SSR is intended |
+| Use Server Components for async data fetching | Put async data fetching in client components when SSR is intended |
 | Use `parseRewriteHeader(headers())` in not-found for site/locale | Hardcode site/locale in not-found or error pages |
 | Use createXRouteHandler and `.sitecore/sites.json` for sitemap/robots | Hardcode site list or commit `.env` |
 | Use Sitecore field components and validate fields | Expose API keys or editing secret in client code |
@@ -179,7 +178,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 ## Guardrails for agentic AI
 
-- **Preserve behavior:** Do not change the proxy order (LocaleProxy → AppRouterMultisiteProxy → …), the `[site]/[locale]/[[...path]]` route shape, or the way `setRequestLocale` and `i18n/request.ts` use `{site}_{locale}`. Preserve PPR/Suspense boundaries and draftMode handling.
+- **Preserve behavior:** Do not change the proxy order (LocaleProxy → AppRouterMultisiteProxy → …), the `[site]/[locale]/[[...path]]` route shape, or the way `setRequestLocale` and `i18n/request.ts` use `{site}_{locale}`. Preserve draftMode handling in layout and page.
 - **Do not expand scope:** Limit edits to the app (app router, components, API routes, i18n, config). Do not modify SDK packages or monorepo tooling unless explicitly asked. Do not change CI, lockfiles, or root config.
 - **Follow existing patterns:** When adding routes, layouts, or components, mirror the existing structure. Use the same Sitecore client, component maps, and env-based config. Do not introduce a different way to resolve site/locale or a second client without clear need.
 - **Verify and stay safe:** After edits, the app should build with `npm run build`. Do not commit secrets or `.env`; only document variables in `.env.example`. Do not add npm dependencies without explicit approval. When in doubt, prefer the existing implementation and ask for clarification.
@@ -208,6 +207,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 ## References
 
+- **Skills.md** — Capability groupings for this app; [.agents/skills/](.agents/skills/) provides each capability as an Agent Skill (when-to-use, hard rules, stop conditions) for tools that support the [Agent Skills](https://agentskills.io) standard.
 - **CLAUDE.md** — Full coding standards and Sitecore patterns for this template.
 - **.cursor/rules/** — App Router and Sitecore rules.
 - [Sitecore Content SDK](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html) — Official docs.

package/dist/templates/nextjs-app-router/CLAUDE.md

@@ -1,274 +1,9 @@
-# Claude Code Agent Guide for Sitecore Content SDK Next.js App Router Project
+# Claude Code — Sitecore Content SDK Next.js (App Router) App
 
-## Project Purpose and Tech Stack
+At the start of every session, read these files for full project guidance:
 
-This is a **Sitecore Content SDK** application built with **Next.js App Router** and **TypeScript**. The project follows Sitecore best practices for XM Cloud development and leverages the latest Next.js App Router features for improved performance and developer experience.
+1. **`AGENTS.md`** — Canonical source of truth for this app: overview, commands, App Router structure, middleware, SitecoreClient, [site]/[locale]/[[...path]], next-intl, DO/DON'T, guardrails, boundaries
+2. **`.cursor/rules/`** — Coding rules for this template: general, javascript, sitecore, app-router-setup
+3. **`Skills.md`** and **`.agents/skills/`** — Capability-specific guidance (component registration, data fetching, editing, i18n, etc.) for tools that support the [Agent Skills](https://agentskills.io) standard.
 
-### Key Technologies
-- **Next.js App Router** - React framework with Server Components and modern routing
-- **Sitecore Content SDK** - Official SDK for Sitecore XM Cloud integration
-- **TypeScript** - Type-safe JavaScript development
-- **Sitecore XM Cloud** - Headless CMS platform
-- **React Server Components** - Server-side rendering for better performance
-- **next-intl** - Internationalization support
-
-## Coding Standards
-
-### TypeScript Standards
-- Use **strict mode** in tsconfig.json
-- Prefer type assertions over `any`: `value as ContentItem`
-- Use discriminated unions for complex state management
-- Enable strict null checks and strict function types
-
-### Naming Conventions
-- **Variables/Functions**: camelCase (`getUserData()`, `isLoading`, `currentUser`)
-- **Components**: PascalCase (`SitecoreComponent`, `PageLayout`, `ContentBlock`)
-- **Constants**: UPPER_SNAKE_CASE (`API_ENDPOINT`, `DEFAULT_TIMEOUT`)
-- **Directories**: kebab-case (`src/components`, `src/api-clients`)
-- **Types/Interfaces**: PascalCase (`ContentItem`, `LayoutProps`, `SitecoreConfig`)
-
-### Modular Layout (App Router)
-```
-src/
-  app/                 # App Router pages and layouts
-  components/          # UI components (React)
-  lib/                 # Configuration and utilities
-  i18n/                # Internationalization setup
-  types/               # TypeScript type definitions
-  hooks/               # Custom React hooks
-```
-
-## Library Usage
-
-### @sitecore-content-sdk
-- Use `SitecoreClient` for content fetching
-- Implement proper error handling with try/catch blocks
-- Cache API responses using React Query or SWR
-- Handle content preview vs. published content scenarios
-
-```typescript
-import { SitecoreClient } from '@sitecore-content-sdk/nextjs/client';
-import scConfig from 'sitecore.config';
-
-const client = new SitecoreClient({
-  ...scConfig,
-});
-```
-
-### React App Router Patterns
-- Use **Server Components** for data fetching and static content (default)
-- Use **Client Components** for interactivity (use 'use client' directive)
-- Implement proper error boundaries with error.tsx
-- Use loading.tsx for loading states
-- Leverage layout.tsx for shared page structure
-
-### Sitecore Field Components
-- Always use Sitecore field components: `<Text>`, `<RichText>`, `<Image>`
-- Validate field existence before rendering
-- Handle empty/null fields gracefully
-- Prefer Sitecore field components over manual rendering
-
-```typescript
-// Good: Using Sitecore field components
-<Text field={fields?.title} tag="h1" />
-<RichText field={fields?.content} />
-<Image field={fields?.backgroundImage} />
-
-// Avoid: Manual field value extraction unless necessary
-```
-
-## Example Patterns and Prompts
-
-### Server Component Development
-```typescript
-// Server Component example (default in App Router)
-import { SitecoreClient } from '@sitecore-content-sdk/nextjs/client';
-import scConfig from 'sitecore.config';
-
-const client = new SitecoreClient({
-  ...scConfig,
-});
-
-export default async function SitecorePage({ params }: { params: { path: string[] } }) {
-  try {
-    const pageData = await client.getPage(params.path.join('/'));
-    return <SitecoreLayout layoutData={pageData?.layout} />;
-  } catch (error) {
-    return <div>Content not found</div>;
-  }
-}
-```
-
-### Client Component Integration
-
-Interactive Sitecore Components:
-
-- Use 'use client' directive when needed
-- Keep client components focused on interactivity
-- Pass server-fetched data as props
-- Handle hydration mismatches carefully
-
-```typescript
-'use client';
-
-interface InteractiveSitecoreComponentProps {
-  fields: {
-    title: Field;
-    content: Field;
-  };
-}
-
-export default function InteractiveSitecoreComponent({
-  fields,
-}: InteractiveSitecoreComponentProps) {
-  // Client-side interactivity here
-  return (
-    <div>
-      <Text field={fields?.title} tag="h2" />
-      <RichText field={fields?.content} />
-    </div>
-  );
-}
-```
-
-### Component Development
-```typescript
-// Component props interface
-interface HeroProps {
-  fields: {
-    title: Field;
-    subtitle: Field;
-    backgroundImage: Field;
-  };
-}
-
-export default function Hero({ fields }: HeroProps) {
-  return (
-    <div>
-      <Text field={fields?.title} tag="h1" />
-      <Text field={fields?.subtitle} tag="p" />
-      <Image field={fields?.backgroundImage} />
-    </div>
-  );
-}
-```
-
-### Error Handling
-
-API Calls:
-
-- Always wrap in try/catch blocks
-- Throw custom errors with context: `SitecoreFetchError`, `ConfigurationError`
-- Handle edge cases with guard clauses
-
-```typescript
-async function fetchPageData(path: string): Promise<Page | null> {
-  if (!path) {
-    throw new Error('Page path is required');
-  }
-
-  try {
-    const pageData = await client.getPage(path);
-    return pageData;
-  } catch (error) {
-    throw new SitecoreFetchError(`Failed to fetch page data for ${path}`, error);
-  }
-}
-```
-
-### Configuration
-```typescript
-// sitecore.config.ts
-import { defineConfig } from '@sitecore-content-sdk/nextjs/config';
-
-export default defineConfig({
-  api: {
-    edge: {
-      contextId: process.env.SITECORE_EDGE_CONTEXT_ID || '',
-      clientContextId: process.env.NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID,
-      edgeUrl:
-        process.env.NEXT_PUBLIC_SITECORE_EDGE_PLATFORM_HOSTNAME ||
-        process.env.SITECORE_EDGE_PLATFORM_HOSTNAME ||
-        'https://edge-platform.sitecorecloud.io',
-    },
-    local: {
-      apiKey: process.env.SITECORE_API_KEY || '',
-      apiHost: process.env.SITECORE_API_HOST || '',
-    },
-  },
-  defaultSite: process.env.NEXT_PUBLIC_DEFAULT_SITE_NAME || 'default',
-  defaultLanguage: process.env.NEXT_PUBLIC_DEFAULT_LANGUAGE || 'en',
-  editingSecret: process.env.SITECORE_EDITING_SECRET,
-});
-```
-
-### Internationalization
-
-Multi-language Support:
-
-- Configure next-intl for language routing
-- Handle Sitecore language contexts
-- Implement language switching
-- Use proper locale-based data fetching
-
-```typescript
-// Language-aware data fetching
-import { getTranslations } from 'next-intl/server';
-
-export default async function LocalizedPage() {
-  const t = await getTranslations('common');
-  // Fetch Sitecore content for current locale
-}
-```
-
-## Development Workflow
-
-1. **Install dependencies**: `npm install`
-2. **Configure environment**: Copy `.env.example` to `.env.local`
-3. **Start development**: `npm run dev`
-4. **Build for production**: `npm run build`
-
-## App Router Best Practices
-
-### Server vs Client Components
-- Use Server Components for Sitecore content rendering (default)
-- Use Client Components for user interactions
-- Minimize client-side JavaScript
-- Leverage server-side data fetching
-
-### Routing and Layouts
-- Use layout.tsx for shared page structure
-- Implement loading.tsx for loading states
-- Create error.tsx for error boundaries
-- Use page.tsx for route content
-- Use [...path] for Sitecore catch-all routes
-
-### Performance Optimization
-- Leverage Server Components for better performance
-- Use streaming for improved loading experience
-- Implement proper caching strategies
-- Optimize images with Next.js Image component
-
-## Best Practices
-
-### Performance
-- Optimize images using Next.js Image component
-- Implement proper loading states
-- Cache expensive operations appropriately
-- Consider server-side rendering implications
-- Lazy-load non-critical modules
-- Use Server Components for better performance
-
-### Security
-- Sanitize user inputs before processing
-- Validate data at application boundaries
-- Use HTTPS for all Sitecore connections
-- Never expose sensitive configuration in client-side code
-- Escape content when rendering to prevent XSS
-
-### Code Quality
-- Follow DRY principle - extract common functionality
-- Use SOLID principles for maintainable code
-- Write self-documenting code with clear intent
-- Implement proper error boundaries
-- Test behavior, not implementation details
+This file applies to **this scaffolded head application only**. For the Content SDK monorepo (packages, CLI, templates source), use that repo's root `AGENTS.md` and `.cursor/rules/`.

package/dist/templates/nextjs-app-router/README.md

@@ -5,39 +5,3 @@
 -->
 
 [Documentation](https://doc.sitecore.com/xmc/en/developers/xm-cloud/sitecore-javascript-rendering-sdk--jss--for-next-js.html)
-
-## Next.js Cache Components
-
-Cache Components is **disabled by default** in this template. To enable it:
-
-1. **Enable in `next.config.ts`**:
-   ```typescript
-   const nextConfig: NextConfig = {
-     cacheComponents: true,
-     // ... rest of config
-   };
-   ```
-
-2. **Add uncached data access** in all server components that call client methods:
-   
-   Next.js 16 with Cache Components requires accessing uncached data (`draftMode()`, `cookies()`, `headers()`, or `searchParams`) before any operations that might use `new Date()` or other time-related functions.
-   
-   Example:
-   ```typescript
-   export default async function Page({ params, searchParams }: PageProps) {
-     // Access uncached data first
-     await draftMode();
-     
-     const { site, locale, path } = await params;
-     // ... rest of component
-   }
-   ```
-   
-   Apply this pattern to:
-   - Page components that call `client.getPage()`, `client.getPreview()`, etc.
-   - `generateMetadata` functions
-   - Layout components that call client methods
-   - Not-found handlers
-   - Any server component calling Sitecore client methods
-
-3. **See the sample app** (`samples/nextjs-app-router`) for a working example with Cache Components enabled.