create-content-sdk-app 2.2.0 → 2.2.1-beta.atoms.20260709124639

package/dist/templates/nextjs/.agents/docs/AGENTS-key-concepts.md

@@ -0,0 +1,33 @@
+# Key concepts (Pages Router)
+
+Optional, on-demand detail. The compact guide is [AGENTS.md](../../AGENTS.md).
+
+## Middleware (Edge proxy)
+
+- **Where:** `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.
+- **What it does:** Runs on each request (respecting the `config.matcher`). Chain order is **fixed:** PreviewProxy → BotTrackingProxy → MultisiteProxy → RedirectsProxy → PersonalizeProxy. PreviewProxy authorizes preview requests first; multisite resolves site (e.g. hostname or cookie) and rewrites; redirects and personalization run after.
+- **Config:** Uses `sitecore.config.ts` (multisite, redirects, personalize) and `.sitecore/sites.json`. **Do not change proxy order.** Use the `skip` callback and matcher to exclude `/api`, `/_next`, static files, and health checks so the proxy stays lightweight.
+
+## SitecoreClient
+
+- **Where:** Single shared instance in `src/lib/sitecore-client.ts` — `new SitecoreClient({ ...scConfig })` with config from `sitecore.config.ts`.
+- **Use for:** `getPage`, `getDictionary`, `getComponentData`, `getPreview`, `getDesignLibraryData`, `getPagePaths`. All Sitecore data fetching in the app goes through this client (in `[[...path]].tsx` getStaticProps/getServerSideProps and in API routes).
+- **Do not:** Create a second client or instantiate SitecoreClient elsewhere. Path comes from `extractPath(context)`; locale from `context.locale` (Next.js i18n).
+
+## Catch-all route
+
+- **Where:** `src/pages/[[...path]].tsx`. This is the **only** page component that renders Sitecore content; the optional `[[...path]]` segment captures the content path.
+- **Flow:** Use `extractPath(context)` (from `@sitecore-content-sdk/nextjs/utils`) to get the path array; use `context.locale` for locale. In getStaticProps/getServerSideProps: `client.getPage(path, { locale: context.locale })`, then `client.getDictionary({ site: page.siteName, locale: page.locale })` and `client.getComponentData(page.layout, context, components)`. For SSG, paths from `client.getPagePaths(sites, context?.locales)` with `sites` from `.sitecore/sites.json`. For preview, use `context.preview` and `context.previewData` with `client.getPreview(context.previewData)` or `client.getDesignLibraryData(context.previewData)`.
+- **Do not:** Add another page or catch-all for Sitecore content; keep this single entry point.
+
+## How locale works
+
+- **Config:** `next.config.js` → `i18n.locales` and `i18n.defaultLocale`. Match (or subset) Sitecore languages. There is no `[locale]` in the URL path; Next.js i18n handles locale via its built-in behavior (e.g. prefix or cookie).
+- **In the app:** Per-request locale is `context.locale` in `getStaticProps` and `getServerSideProps`. Pass it to `client.getPage(path, { locale: context.locale })`. After fetching the page, use `page.siteName` and `page.locale` (or `context.locale`) for `client.getDictionary` and `client.getComponentData`.
+- **Do not:** Assume locale from headers or a different source; always use `context.locale` and the page's site/locale for Sitecore calls.
+
+## Component map, editing, env
+
+- **Component map:** `.sitecore/component-map.ts` — auto-generated from `src/components/` during `npm run dev` (watch) and `npm run build`. Do not edit manually unless needed. Used by `getComponentData` and by the editing API routes.
+- **Editing/preview:** Use `context.preview` and `context.previewData` in the catch-all page; when in preview, use `client.getPreview(context.previewData)` or `client.getDesignLibraryData(context.previewData)`. Editing API routes: `src/pages/api/editing/config.ts`, `render.ts`, `feaas/render.ts`.
+- **Env:** All config via environment variables in `sitecore.config.ts`. Document vars in `.env.example` (or `.env.remote.example` / `.env.container.example`); never commit `.env` or `.env.local`.

package/dist/templates/nextjs/.agents/docs/AGENTS-overview.md

@@ -0,0 +1,25 @@
+# Project overview (Pages Router)
+
+This is a **Sitecore Content SDK** application built with **Next.js (Pages Router)** and **TypeScript**. AI agents work as developer assistants within this scaffolded head application. The app integrates with Sitecore XM Cloud for content, supports multisite and i18n, and uses Next.js API routes and Edge middleware for routing and SEO.
+
+**Scope:** This file applies to **this application only** (a scaffolded head app). It is **not** the Content SDK monorepo — for SDK package development use that repo's `AGENTS.md`. Here we edit app code and config (pages, components, API routes, config); we do not modify SDK packages or CI.
+
+## Application structure
+
+```
+src/
+  pages/             # Next.js Pages Router
+    [[...path]].tsx  # Catch-all Sitecore page (SSG or SSR)
+    _app.tsx
+    404.tsx, 500.tsx, _error.tsx
+    api/             # API routes (sitemap, robots, editing, healthz)
+  components/        # React components (Sitecore + app-specific)
+  lib/               # sitecore-client, component-props
+  Layout.tsx, Providers.tsx, Bootstrap.tsx, Scripts.tsx
+proxy.ts             # Edge middleware (multisite, redirects, personalize)
+.sitecore/           # component-map.ts, import-map.ts, sites.json, metadata.json
+sitecore.config.ts   # Sitecore config (api, defaultSite, defaultLanguage, multisite, etc.)
+next.config.js       # i18n (locales, defaultLocale), rewrites, images
+```
+
+**Component map:** `.sitecore/component-map.ts` is auto-generated from `src/components/` during `npm run dev` (watch) and `npm run build`. No manual action needed; the generator scans `src/components/` and creates entries for all Sitecore-registered components.

package/dist/templates/nextjs/.agents/docs/AGENTS-router-specifics.md

@@ -0,0 +1,57 @@
+# Next.js Pages Router specifics
+
+Optional, on-demand detail. The compact guide is [AGENTS.md](../../AGENTS.md).
+
+## Routing and data fetching
+
+- **_app.tsx:** Wraps the app and receives the page/layout from the catch-all's getStaticProps/getServerSideProps. Do not fetch Sitecore data in _app; all data flows from `[[...path]].tsx`.
+- **Single page for Sitecore content:** `src/pages/[[...path]].tsx` is the catch-all. Path comes from `extractPath(context)` (from `@sitecore-content-sdk/nextjs/utils`); locale from `context.locale` (Next.js i18n).
+- **SSG:** Uses `getStaticPaths` and `getStaticProps`. Paths from `client.getPagePaths(sites, context?.locales)` with `sites` from `.sitecore/sites.json`. Use `revalidate` for ISR.
+- **SSR:** Uses `getServerSideProps` only; no `getStaticPaths`.
+- **Preview:** `context.preview` and `context.previewData`; use `client.getPreview(context.previewData)` or `client.getDesignLibraryData(context.previewData)` when applicable.
+- **Page data:** `client.getPage(path, { locale: context.locale })`, then `client.getDictionary({ site: page.siteName, locale: page.locale })` and `client.getComponentData(page.layout, context, components)` for component props.
+
+## i18n (Pages Router)
+
+- **Config:** `next.config.js` → `i18n.locales` and `i18n.defaultLocale`. Match (or subset) Sitecore languages.
+- **Per-request locale:** Provided by Next.js as `context.locale` in `getStaticProps` / `getServerSideProps`. No `[locale]` in the path; locale is from Next.js i18n.
+
+## Multisite and Edge middleware (proxy)
+
+- **Site list:** `.sitecore/sites.json` — typically generated by the Sitecore CLI or deployment. Used by middleware and API routes. Avoid hand-editing unless you know the format.
+- **Edge middleware:** Implemented in **`src/proxy.ts`**. Next.js only runs middleware from a file named `middleware.ts` at root or in `src/`. If this app has only `proxy.ts`, add `src/middleware.ts` that re-exports it (e.g. `export { default } from './proxy';`) so the proxy runs.
+- **Proxy chain (order matters):** `defineProxy(preview, botTracking, multisite, redirects, personalize).exec(req)`:
+  - **PreviewProxy** — authorizes preview requests on the internal editing host; no-op elsewhere.
+  - **BotTrackingProxy** — bot detection.
+  - **MultisiteProxy** — resolves site from request (e.g. hostname or cookie), rewrites to internal path; uses `scConfig.api.edge` and `scConfig.multisite` (e.g. `useCookieResolution`).
+  - **RedirectsProxy** — handles redirects; uses `scConfig.redirects`, `scConfig.api.edge`, `scConfig.api.local`.
+  - **PersonalizeProxy** — personalization; uses `scConfig.personalize`; often disabled in dev.
+- **Skip function:** Each proxy has a `skip` callback. Use it to avoid running on certain paths (e.g. `/api`, `/_next`, static files) for performance.
+- **Config:** `sitecore.config.ts` → `multisite.enabled`, `redirects.enabled`, `personalize`; never commit secrets.
+
+## API routes
+
+- **Sitemap:** `src/pages/api/sitemap.ts` — `SitemapMiddleware(scClient, sites).getHandler()`. Serves sitemap XML; uses `sites` from `.sitecore/sites.json`.
+- **Robots:** `src/pages/api/robots.ts` — `RobotsMiddleware(scClient, sites).getHandler()`. Serves `robots.txt`; site can be resolved from request.
+- **Editing:** `src/pages/api/editing/config.ts`, `render.ts`, `feaas/render.ts` — used by Sitecore Editor (XM Cloud); use SDK middleware/handlers and `.sitecore/component-map`, `.sitecore/metadata.json`.
+- **Health:** `src/pages/api/healthz.ts` — health check. Rewrite in `next.config.js`: `/healthz` → `/api/healthz`.
+- **Rewrites:** `next.config.js` → `rewrites()` for `/robots.txt`, `/sitemap*.xml`, `/feaas-render` to the corresponding API routes.
+
+## Sitecore client and config
+
+- **Client:** `src/lib/sitecore-client.ts` — `new SitecoreClient({ ...scConfig })`. Use this instance for `getPage`, `getDictionary`, `getComponentData`, `getPreview`, `getPagePaths`, etc.
+- **Config:** `sitecore.config.ts` — `defineConfig({ api, defaultSite, defaultLanguage, editingSecret, redirects, multisite, personalize })`. Use env vars; no hardcoded secrets.
+
+## Component map and layout
+
+- **Component map:** `.sitecore/component-map.ts` — auto-generated from `src/components/` during `npm run dev` (watch) and `npm run build`. Do not edit manually unless needed.
+- **Layout:** `Layout.tsx` renders page layout and placeholders; `Providers` wrap component props and page context; `Bootstrap` handles site name and preview mode.
+- **404 / 500 / _error:** When the catch-all returns `notFound: true` (no page), Next.js renders `404.tsx`. When the server returns 500, Next.js renders `500.tsx`. Both can optionally fetch and show Sitecore error content via `client.getErrorPage(ErrorPage.NotFound)` / `ErrorPage.InternalServerError` in their getStaticProps (when `scConfig.generateStaticPaths`); otherwise they show a simple fallback. `_error.tsx` is Next.js's error boundary for uncaught errors (client and server); it does not fetch from Sitecore.
+
+## Best practices
+
+- **Quick checks:** If path or locale is wrong, ensure you use `extractPath(context)` and `context.locale` (from getStaticProps/getServerSideProps); do not assume path or locale from elsewhere. Keep the proxy chain order (PreviewProxy → BotTrackingProxy → Multisite → Redirects → Personalize).
+- **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 `skip` callback and `matcher` so middleware does not run on `/api`, `_next`, static files, or health checks. Use `revalidate` in getStaticProps for ISR where appropriate. Prefer server-side data fetching for Sitecore content.
+- **Sitecore patterns:** Use SDK field components (`<Text>`, `<RichText>`, `<Image>`) and validate field existence before render. Regenerate `.sitecore/component-map.ts` with `npm run sitecore-tools:generate-map` or `npm run sitecore-tools:generate-map:watch`; edit the map manually only when the generator cannot handle the change. Keep the single Sitecore client instance in `lib/sitecore-client.ts` and pass it (or use it) in API routes and getStaticProps/getServerSideProps.
+- **Consistency:** Follow the existing patterns in `[[...path]].tsx`, `_app.tsx`, and API routes. When adding API routes, add the corresponding rewrite in `next.config.js` and keep the middleware matcher in sync.

package/dist/templates/nextjs/.agents/docs/AGENTS-workflows-and-boundaries.md

@@ -0,0 +1,20 @@
+# Workflows and boundaries (Pages Router)
+
+Optional, on-demand detail. Guardrails stay in [AGENTS.md](../../AGENTS.md).
+
+## Example agent tasks
+
+- **Add a new Sitecore component:** Create the component under `src/components/` (map regenerates automatically during `npm run dev`; otherwise run `npm run sitecore-tools:generate-map`), and ensure it is rendered in the layout/placeholder as in existing components.
+- **Add an API route:** Create the route under `src/pages/api/`, add a rewrite in `next.config.js` if the route should be reached from a public URL (e.g. `/my-path` → `/api/my-handler`), and ensure the proxy `matcher` in `proxy.ts` still excludes it (or add the path to the matcher exclusions if needed).
+
+## Boundaries
+
+**Never edit:** `.next/`, `node_modules/`.
+
+**Environment variables:** You may add new env vars when needed. Do it carefully: add the variable to `.env.example` (or `.env.remote.example` / `.env.container.example` in this template) with a placeholder or comment; never put real secrets in example files. If editing `.env.local` for local dev, add only the variable name and tell the user to set the value. **Never commit** `.env` or `.env.local` — they are gitignored.
+
+**Edit with care:** `next.config.js` (rewrites, i18n), `sitecore.config.ts` (env only), `proxy.ts` (matcher and proxy order). When adding API routes or rewrites, keep middleware `matcher` and rewrite rules consistent.
+
+**Focus on:** `src/pages/`, `src/components/`, `src/lib/`, `Layout.tsx`, `Providers.tsx`, `sitecore.config.ts`, `next.config.js`, `proxy.ts`. `.sitecore/component-map.ts` is auto-generated — do not edit manually.
+
+**For head applications / empty starters:** Keep this app's `AGENTS.md` as the guide. Do not replace it with the Content SDK monorepo root `AGENTS.md` — that file describes the SDK source tree, not the head application.

package/dist/templates/nextjs/.agents/docs/README.md

@@ -0,0 +1,12 @@
+# Layered AI docs (Pages Router)
+
+Use [AGENTS.md](../../AGENTS.md) first (compact). Open **one** file below when you need depth.
+
+| File | Use when |
+|------|----------|
+| [AGENTS-overview.md](AGENTS-overview.md) | Project scope and what this head app is |
+| [AGENTS-key-concepts.md](AGENTS-key-concepts.md) | Middleware, SitecoreClient, catch-all, locale, component map |
+| [AGENTS-router-specifics.md](AGENTS-router-specifics.md) | Routing, i18n, proxy, data fetching, API routes, layout |
+| [AGENTS-workflows-and-boundaries.md](AGENTS-workflows-and-boundaries.md) | Example tasks and edit boundaries |
+
+Skills: [.agents/skills/](../skills/) — load **one** [SKILL.md](https://agentskills.io) per task. See [Skills.md](../../Skills.md).

package/dist/templates/nextjs/.agents/skills/content-sdk-component-data-strategy/SKILL.md

@@ -1,37 +1,25 @@
 ---
 name: content-sdk-component-data-strategy
-description: Component data for Pages Router: after getPage use client.getComponentData(page.layout, context, components) to resolve component props; pass result to layout renderer. All Sitecore-driven component data goes through this flow. Use when wiring component data or BYOC.
+description: Layout data from getPage/getComponentData; path/locale from extractPath/context.
 ---
 
-# Content SDK Component Data Strategy (Pages Router)
+# Component data strategy (Pages Router)
 
-This app **uses getComponentData**. After getPage, use **client.getComponentData(page.layout, context, components)** to resolve component props and pass the result to the layout renderer. All Sitecore-driven component data goes through this flow.
+**Detail:** [AGENTS-router-specifics.md#routing-and-data-fetching](../../docs/AGENTS-router-specifics.md#routing-and-data-fetching)
 
-## When to Use
+## When
 
-- User asks how to pass data to components, wire component props, or integrate custom/BYOC components.
-- Task involves getComponentData, component props, or BYOC.
-- User mentions "component data," "props," "BYOC," or "getComponentData."
+- How component receives Sitecore data
+- BYOC or serializable props to client
 
-## How to perform
+## Rules
 
-- In [[...path]].tsx: getPage(path, { locale: context.locale }), then getDictionary, then getComponentData(page.layout, context, components). Return props to Layout; do not fetch in _app or in child components. Register BYOC in .sitecore/component-map.ts; getComponentData passes resolved props.
+- Data from `getPage` + `getComponentData` in catch-all page
+- Pass serializable props to client components
+- BYOC must be registered in component map
 
-## Hard Rules
+## Stop
 
-- **Flow in catch-all page:** In getStaticProps/getServerSideProps: (1) `client.getPage(path, { locale: context.locale })`, (2) `client.getDictionary({ site: page.siteName, locale: page.locale })`, (3) `client.getComponentData(page.layout, context, components)` to resolve component props. Return `{ props: { page, dictionary, componentProps }, notFound: !page }`. Pass these props to Providers and Layout; do not fetch Sitecore data in _app.
-- Do not fetch per-component data in parallel outside this flow unless the app pattern explicitly does so. All Sitecore-driven component data goes through getComponentData.
-- Single client instance; do not create a new client inside components. The client is used in getStaticProps/getServerSideProps and in API routes.
-- **BYOC or custom components:** Must be registered in `.sitecore/component-map.ts` and receive props in the shape the layout expects (e.g. fields, params). getComponentData will pass the resolved props.
-- Do not fetch layout or page data inside a child component (e.g. another getPage call); fetch at the catch-all page level and pass props via getComponentData and layout.
+- Stop if introducing a second data-fetch path without clear need
 
-## Stop Conditions
-
-- Stop if the user wants to fetch page/layout data inside a child component; recommend fetching in [[...path]].tsx and passing via getComponentData and layout.
-- Do not duplicate getComponentData or getPage logic across components; keep data fetching in the catch-all page only.
-- Do not fetch Sitecore data in _app; all data flows from [[...path]].tsx.
-
-## References
-
-- content-sdk-graphql-data-fetching and [AGENTS.md](../../../AGENTS.md) for getPage, getComponentData, and data flow.
-- [Official Content SDK docs](https://doc.sitecore.com/sai/en/developers/content-sdk/sitecore-content-sdk-for-sitecoreai.html).
+Docs: [Content SDK](https://doc.sitecore.com/sai/en/developers/content-sdk/sitecore-content-sdk-for-sitecoreai.html).

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

@@ -1,36 +1,25 @@
 ---
 name: content-sdk-component-registration
-description: Registers Sitecore components in .sitecore/component-map.ts so layout and editing can resolve them. Pages Router uses a single map; used by getComponentData and editing API routes. Use when registering a new component or when layout/editor cannot find a component.
+description: Registers components in .sitecore/component-map.ts for Pages Router layout and editing.
 ---
 
-# Content SDK Component Registration (Pages Router)
+# Component registration (Pages Router)
 
-Register components in the Sitecore component map so the layout and editing pipeline can resolve and render them. This app has a **single** map: `.sitecore/component-map.ts`.
+**Detail:** [AGENTS-router-specifics.md#component-map-and-layout](../../docs/AGENTS-router-specifics.md#component-map-and-layout)
+**Read first:** `.sitecore/component-map.ts`
 
-## When to Use
+## When
 
-- 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`.
-- User asks how to register a component or fix component resolution.
+- Component not found in layout/editor
+- Task touches the component map
 
-## How to perform
+## Rules
 
-- Open `.sitecore/component-map.ts` and add an entry mapping the layout component name to the React component import. The map is used by getComponentData and editing API routes; keep keys consistent with layout and existing entries.
+- Every layout component must be in `.sitecore/component-map.ts`
+- Prefer auto-generation from `src/components/`; edit manually only when generator cannot handle the case
 
-## Hard Rules
+## Stop
 
-- Every component rendered from Sitecore layout must be registered in `.sitecore/component-map.ts`. Keep the map in sync with `src/components/`.
-- The map is used by `getComponentData(page.layout, context, components)` in the catch-all page and by editing API routes (`src/pages/api/editing/config.ts`, `render.ts`, `feaas/render.ts`).
-- Use consistent component names (same key in map as used in layout). Follow existing naming in the map.
-- Do not remove or rename registrations without updating all references (layout, getComponentData, editing routes).
+- Stop if renaming map entries would break published layout without Sitecore-side update
 
-## Stop Conditions
-
-- Stop if modifying the component map 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 map and editing routes.
-- [Official Content SDK docs](https://doc.sitecore.com/sai/en/developers/content-sdk/sitecore-content-sdk-for-sitecoreai.html).
+Docs: [Content SDK](https://doc.sitecore.com/sai/en/developers/content-sdk/sitecore-content-sdk-for-sitecoreai.html).

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

@@ -1,34 +1,25 @@
 ---
 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. Pages Router: register in .sitecore/component-map.ts only.
+description: Creates new Sitecore components under src/components/. Pages Router; map auto-regenerates on dev/build.
 ---
 
-# Content SDK Component Scaffold (Pages Router)
+# Component scaffold (Pages Router)
 
-Scaffold new Sitecore components so they integrate with the layout and editing pipeline. This app uses Pages Router with a single component map.
+**Detail:** [AGENTS-router-specifics.md#component-map-and-layout](../../docs/AGENTS-router-specifics.md#component-map-and-layout)
+**Read first:** `src/components/`
 
-## When to Use
+## When
 
-- 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."
+- Adding a new Sitecore component from scratch
+- User asks for component file structure or props
 
-## How to perform
+## Rules
 
-- Create a new file under `src/components/` (or existing feature folder). Define props (fields, params), export a single default component. Register in `.sitecore/component-map.ts` (content-sdk-component-registration). Run `npm run build` to verify.
+- Place components under `src/components/`
+- Map regenerates during `npm run dev` / `npm run build`; run `npm run sitecore-tools:generate-map` if dev is not running
 
-## Hard Rules
+## Stop
 
-- 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.
-- After creating the component file, register it in `.sitecore/component-map.ts` (see content-sdk-component-registration). Do not leave the component unregistered. Pages Router has a single map used by getComponentData and editing API routes.
+- Stop if unclear whether component needs client-side interactivity
 
-## Stop Conditions
-
-- Do not create components in `.next/`, `node_modules/`, or build output.
-
-## References
-
-- [AGENTS.md](../../../AGENTS.md) for app structure and component map.
-- [Skills.md](../../../Skills.md) for capability map. [Official Content SDK docs](https://doc.sitecore.com/sai/en/developers/content-sdk/sitecore-content-sdk-for-sitecoreai.html).
+Docs: [Content SDK](https://doc.sitecore.com/sai/en/developers/content-sdk/sitecore-content-sdk-for-sitecoreai.html).

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

@@ -1,36 +1,23 @@
 ---
 name: content-sdk-component-variants
-description: Implements component variants: different renderings or data-driven variants of the same component type. Pages Router: register in .sitecore/component-map.ts; getComponentData resolves props. Use when one component has multiple presentations.
+description: Multiple renderings of one component type; regenerate component map after changes.
 ---
 
-# Content SDK Component Variants (Pages Router)
+# Component variants (Pages Router)
 
-One component definition can have multiple presentations or data-driven variants. Component props are resolved by **getComponentData(page.layout, context, components)**; keep registration and layout aligned.
+**Detail:** [AGENTS-router-specifics.md#component-map-and-layout](../../docs/AGENTS-router-specifics.md#component-map-and-layout)
 
-## When to Use
+## When
 
-- 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."
+- One component type with multiple presentations or variants
 
-## How to perform
+## Rules
 
-- Prefer one component that accepts variant/style via props and branches internally; or multiple map entries if the app uses one key per variant. Use layout/fields/params for variant; register in `.sitecore/component-map.ts`. getComponentData resolves props; align with existing app convention.
+- Follow existing variant patterns in `src/components/`
+- Regenerate component map after changes
 
-## Hard Rules
+## Stop
 
-- 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. getComponentData passes the layout-driven props to the component.
-- Register in `.sitecore/component-map.ts` only. If the app uses one key per variant, register each; if one key with variant param, single registration. Follow existing app convention.
-- Keep the component map in sync with src/components/.
+- Stop if variant rename would break layout without Sitecore update
 
-## 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 the map.
-- [Official Content SDK docs](https://doc.sitecore.com/sai/en/developers/content-sdk/sitecore-content-sdk-for-sitecoreai.html).
+Docs: [Content SDK](https://doc.sitecore.com/sai/en/developers/content-sdk/sitecore-content-sdk-for-sitecoreai.html).

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

@@ -1,35 +1,23 @@
 ---
 name: content-sdk-dictionary-and-i18n
-description: Dictionary and i18n for Pages Router: Next.js i18n in next.config.js (i18n.locales, defaultLocale). Per-request locale is context.locale in getStaticProps/getServerSideProps. Fetch dictionary with client.getDictionary({ site: page.siteName, locale: page.locale }) after getPage. Use when adding or changing translated content or locale behavior.
+description: Next.js i18n via next.config.js; locale from context.locale in data methods.
 ---
 
-# Content SDK Dictionary and i18n (Pages Router)
+# Dictionary and i18n (Pages Router)
 
-This app uses **Next.js built-in i18n**. There is no [locale] in the URL path; locale is provided by Next.js as `context.locale` in getStaticProps/getServerSideProps.
+**Detail:** [AGENTS-router-specifics.md#i18n-pages-router](../../docs/AGENTS-router-specifics.md#i18n-pages-router)
 
-## When to Use
+## When
 
-- User asks to add or change translated content, locale, or dictionary.
-- Task involves getDictionary, Next.js i18n, or context.locale.
-- User mentions "dictionary," "i18n," "locale," or "translation."
+- i18n locales, dictionary, or context.locale issues
 
-## How to perform
+## Rules
 
-- Locales: `next.config.js` → i18n.locales, defaultLocale. In getStaticProps/getServerSideProps use context.locale; after getPage use client.getDictionary({ site: page.siteName, locale: page.locale }). Use a single getDictionary per request. Do not assume locale from headers.
+- `next.config.js` → `i18n.locales` / `defaultLocale` aligned with Sitecore
+- Always pass `context.locale` to `client.getPage`
 
-## Hard Rules
+## Stop
 
-- **Config:** `next.config.js` → `i18n.locales` and `i18n.defaultLocale`. Match (or subset) Sitecore languages.
-- **Per-request locale:** Use `context.locale` in getStaticProps and getServerSideProps. Pass it to `client.getPage(path, { locale: context.locale })`. After fetching the page, use `page.siteName` and `page.locale` (or `context.locale`) for `client.getDictionary({ site: page.siteName, locale: page.locale })` and for getComponentData.
-- Align locales in next.config.js with Sitecore languages (e.g. from sitecore.config.ts defaultLanguage). Use a single client.getDictionary per request for the active site/locale.
-- **Do not** assume locale from headers or a different source; always use `context.locale` and the page's site/locale for Sitecore calls.
+- Stop if assuming locale from headers instead of `context.locale`
 
-## Stop Conditions
-
-- Stop if adding a new locale without confirming it exists in Sitecore and in next.config.js i18n.
-- Do not duplicate dictionary fetching without a clear need; prefer one fetch per request in the catch-all page.
-
-## References
-
-- [AGENTS.md](../../../AGENTS.md) for Next.js i18n and getDictionary usage.
-- [Official Content SDK docs](https://doc.sitecore.com/sai/en/developers/content-sdk/sitecore-content-sdk-for-sitecoreai.html).
+Docs: [Content SDK](https://doc.sitecore.com/sai/en/developers/content-sdk/sitecore-content-sdk-for-sitecoreai.html).

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

@@ -1,37 +1,24 @@
 ---
 name: content-sdk-editing-safe-rendering
-description: Ensures components render safely in XM Cloud editing and preview. Pages Router uses context.preview and context.previewData; use client.getPreview(context.previewData) or getDesignLibraryData(context.previewData) when in preview. Use when making components work in the Sitecore editor or fixing preview/editing behavior.
+description: Preview/editing for Pages Router via context.preview and context.previewData in [[...path]].tsx.
 ---
 
-# Content SDK Editing-Safe Rendering (Pages Router)
+# Editing-safe rendering (Pages Router)
 
-Ensure components behave correctly in XM Cloud editing, preview, and design library. This app uses **context.preview** and **context.previewData** in getStaticProps/getServerSideProps for editing data.
+**Detail:** [AGENTS-router-specifics.md#routing-and-data-fetching](../../docs/AGENTS-router-specifics.md#routing-and-data-fetching)
 
-## When to Use
+## When
 
-- 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.
+- Editing or preview broken
+- Component must work in Page Editor or design library
 
-## How to perform
+## Rules
 
-- In [[...path]].tsx getStaticProps/getServerSideProps: check context.preview; when true use isDesignLibraryPreviewData(context.previewData) to choose getDesignLibraryData vs getPreview; otherwise getPage + getDictionary + getComponentData. Editing routes: config uses EditingConfigMiddleware, render uses EditingRenderMiddleware, feaas/render uses FEAASRenderMiddleware; export handler as default.
+- Use `context.preview` / `context.previewData` in getStaticProps/getServerSideProps
+- When preview: `client.getPreview(context.previewData)` or `getDesignLibraryData(context.previewData)`
 
-## Hard Rules
+## Stop
 
-- In the catch-all page (`src/pages/[[...path]].tsx`), use `context.preview` and `context.previewData`. When in preview, use `isDesignLibraryPreviewData(context.previewData)` to distinguish: if true, use `client.getDesignLibraryData(context.previewData)`; otherwise use `client.getPreview(context.previewData)`. When not in preview, use `getPage(path, { locale: context.locale })` then getDictionary and getComponentData as usual.
-- Do not assume editing/preview context in components that might run in static or non-editing contexts; guard on context.preview in getStaticProps/getServerSideProps.
-- Editing API routes: `src/pages/api/editing/config.ts` uses `EditingConfigMiddleware({ components, metadata }).getHandler()` (import components from `.sitecore/component-map`, metadata from `.sitecore/metadata.json`). `src/pages/api/editing/render.ts` uses `EditingRenderMiddleware().getHandler()`. `src/pages/api/editing/feaas/render.ts` uses `FEAASRenderMiddleware().getHandler()`. Export the handler as default. Do not duplicate client creation; config uses the same component map as the app.
-- Never commit editing secrets; use environment variables and document in .env.example only.
+- Stop if changing preview flow would break editing API routes
 
-## 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 context.previewData.
-- 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/sai/en/developers/content-sdk/sitecore-content-sdk-for-sitecoreai.html).
+Docs: [Content SDK](https://doc.sitecore.com/sai/en/developers/content-sdk/sitecore-content-sdk-for-sitecoreai.html).

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

@@ -1,36 +1,24 @@
 ---
 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.
+description: Renders Sitecore fields with SDK components Text, RichText, Image, Link.
 ---
 
-# Content SDK Field Usage (Pages Router)
+# Field usage (Text, Image, Link) (Pages Router)
 
-Use SDK field components to render Sitecore fields with proper validation and fallbacks.
+**Detail:** [AGENTS-router-specifics.md#component-map-and-layout](../../docs/AGENTS-router-specifics.md#component-map-and-layout)
 
-## When to Use
+## When
 
-- 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."
+- Rendering Sitecore fields
+- User mentions Text, RichText, Image, or Link
 
-## How to perform
+## Rules
 
-- 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.
+- Use `<Text>`, `<RichText>`, `<Image>`, `<Link>` from the SDK
+- Validate field existence before render
 
-## Hard Rules
+## Stop
 
-- 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 if bypassing SDK field components for user-controlled HTML without sanitization
 
-## 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/sai/en/developers/content-sdk/sitecore-content-sdk-for-sitecoreai.html).
+Docs: [Content SDK](https://doc.sitecore.com/sai/en/developers/content-sdk/sitecore-content-sdk-for-sitecoreai.html).

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

@@ -1,38 +1,26 @@
 ---
 name: content-sdk-graphql-data-fetching
-description: Fetches page, dictionary, and component data via the single Sitecore client. Pages Router: getPage(path, { locale: context.locale }), getDictionary({ site: page.siteName, locale: page.locale }), getComponentData(page.layout, context, components); for SSG use getPagePaths(sites, context?.locales). Use when fetching page or dictionary content.
+description: Page/dictionary fetch via SitecoreClient in [[...path]].tsx getStaticProps/getServerSideProps.
 ---
 
-# Content SDK GraphQL Data Fetching (Pages Router)
+# Data fetching (Pages Router)
 
-All Sitecore data fetching goes through the single client in `src/lib/sitecore-client.ts`. Use getPage, getDictionary, and **getComponentData** in the catch-all page. Path from **extractPath(context)**; locale from **context.locale**.
+**Detail:** [AGENTS-router-specifics.md#routing-and-data-fetching](../../docs/AGENTS-router-specifics.md#routing-and-data-fetching)
+**Read first:** `src/pages/[[...path]].tsx`, `src/lib/sitecore-client.ts`
 
-## When to Use
+## When
 
-- User asks how to fetch page data, layout, or dictionary phrases.
-- Task involves getPage, getDictionary, getComponentData, getPreview, getDesignLibraryData, or getPagePaths.
-- User mentions "sitecore client," "Layout Service," "page data," or "dictionary."
+- Fetching page or dictionary data
+- SSG paths or preview data
 
-## How to perform
+## Rules
 
-- Use the client from `src/lib/sitecore-client.ts` only. In [[...path]].tsx: use `extractPath(context)` and `context.locale`; call getPage(path, { locale: context.locale }), then getDictionary and getComponentData(page.layout, context, components). For SSG use getPagePaths in getStaticPaths. For preview use context.preview and getPreview/getDesignLibraryData(context.previewData).
+- Path from `extractPath(context)`; locale from `context.locale`
+- `client.getPage(path, { locale })` then `getDictionary` and `getComponentData`
+- SSG paths: `client.getPagePaths(sites, context?.locales)`
 
-## Hard Rules
+## Stop
 
-- Use the single SitecoreClient instance in `src/lib/sitecore-client.ts`. Do not create a second client or instantiate SitecoreClient elsewhere.
-- **Path and locale:** Use `extractPath(context)` (from `@sitecore-content-sdk/nextjs/utils`) to get the path array; use `context.locale` for locale. Do not assume path or locale from elsewhere.
-- **Catch-all page flow:** In getStaticProps/getServerSideProps: `client.getPage(path, { locale: context.locale })`, then `client.getDictionary({ site: page.siteName, locale: page.locale })` and `client.getComponentData(page.layout, context, components)` for component props. Pass the result to the layout renderer.
-- **SSG:** In getStaticPaths, use `client.getPagePaths(siteNames, context?.locales || [])` where site names come from `.sitecore/sites.json` (e.g. `sites.map((s) => s.name)`). Use `revalidate` in getStaticProps for ISR.
-- **Preview:** Use `context.preview` and `context.previewData`; when in preview, use `client.getPreview(context.previewData)` or `client.getDesignLibraryData(context.previewData)`.
-- Config for the client comes from `sitecore.config.ts`; use environment variables, never hardcode secrets.
+- Stop if fetching in client components when SSR/SSG is intended
 
-## 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.
-- Do not fetch in _app; all data flows from [[...path]].tsx.
-
-## References
-
-- [AGENTS.md](../../../AGENTS.md) for SitecoreClient, getPage, getDictionary, getComponentData, and SSG/SSR.
-- [Official Content SDK docs](https://doc.sitecore.com/sai/en/developers/content-sdk/sitecore-content-sdk-for-sitecoreai.html).
+Docs: [Content SDK](https://doc.sitecore.com/sai/en/developers/content-sdk/sitecore-content-sdk-for-sitecoreai.html).