create-content-sdk-app 2.2.0 → 2.2.1-canary.20260630132751

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

@@ -16,11 +16,11 @@ Register components in the Sitecore component map so the layout and editing pipe
 
 ## How to perform
 
-- 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.
+- The component map at `.sitecore/component-map.ts` is generated from `src/components/` during `npm run dev` or `npm run build`; run `npm run sitecore-tools:generate-map` to refresh it manually, and edit the file only when the generator cannot handle your case.
 
 ## Hard Rules
 
-- Every component rendered from Sitecore layout must be registered in `.sitecore/component-map.ts`. Keep the map in sync with `src/components/`.
+- Every component rendered from Sitecore layout must be registered in `.sitecore/component-map.ts`. Prefer the project's `sitecore-tools:generate-map` script to keep the map in sync with `src/components/`. Do not hand-edit generated map entries unless necessary.
 - 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).

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

@@ -15,14 +15,17 @@ Scaffold new Sitecore components so they integrate with the layout and editing p
 
 ## How to perform
 
-- 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.
+- Create a new file under `src/components/` (or existing feature folder). Define props (fields, params), export a single default component.
+- **Map:** Regenerates automatically during `npm run dev` and `npm run build`; otherwise run `npm run sitecore-tools:generate-map` (see content-sdk-component-registration).
+- Run `npm run build` to verify.
 
 ## Hard Rules
 
 - Place components under `src/components/`. Use existing folder conventions.
+- Prefer `npm run sitecore-tools:generate-map` to regenerate `.sitecore/component-map.ts` instead of hand-editing it. Only manually register the component if the generator cannot handle the change.
 - 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.
+- Ensure the component map regenerates (or update `.sitecore/component-map.ts` manually only if the generator cannot handle the case) before considering the task complete (see content-sdk-component-registration). Pages Router has a single map used by getComponentData and editing API routes.
 
 ## Stop Conditions
 

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

@@ -22,7 +22,7 @@ One component definition can have multiple presentations or data-driven variants
 - 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/.
+- Prefer `sitecore-tools:generate-map` to keep the map in sync with `src/components/`.
 
 ## Stop Conditions
 

package/dist/templates/nextjs/AGENTS.md

@@ -21,6 +21,8 @@ npm run type-check   # Run TypeScript compiler
 
 **Environment:** Copy `.env.example` to `.env.local` and set Sitecore API endpoint, key, default site, and language. Never commit `.env` or `.env.local`.
 
+**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.
+
 ---
 
 ## Application Structure (Pages Router)
@@ -73,7 +75,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 ### More (component map, editing, env)
 
-- **Component map:** `.sitecore/component-map.ts` — register every Sitecore component here; keep in sync with `src/components/`. Used by `getComponentData` and by the editing API routes.
+- **Component map:** `.sitecore/component-map.ts` — Lists every Sitecore component the layout can render, the map is auto-generated from `src/components/`. 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`.
 
@@ -121,7 +123,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 ### Component map and layout
 
-- **Component map:** `.sitecore/component-map.ts` — register all Sitecore components. Keep in sync with components under `src/components/`.
+- **Component map:** `.sitecore/component-map.ts` — Lists every Sitecore component the layout can render, the map is auto-generated from `src/components/`. 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.
 
@@ -132,7 +134,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 - **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 (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. Register new components in `.sitecore/component-map.ts`. Keep the single Sitecore client instance in `lib/sitecore-client.ts` and pass it (or use it) in API routes and getStaticProps/getServerSideProps.
+- **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.
 
 ---
@@ -164,7 +166,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 ## Example agent tasks
 
-- **Add a new Sitecore component:** Create the component under `src/components/`, register it in `.sitecore/component-map.ts`, and ensure it is rendered in the layout/placeholder as in existing components.
+- **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).
 
 ---
@@ -177,7 +179,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 **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`.
+**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.
 
 ---
 

package/dist/templates/nextjs/Skills.md

@@ -16,11 +16,11 @@ Grouping related capabilities makes it easier to know which area of the app appl
 
 ### content-sdk-component-scaffold
 
-Creating new Sitecore components: file structure, props interface, and placement under `src/components/`. Use when adding a new component from scratch. Register in `.sitecore/component-map.ts`.
+Creating new Sitecore components: file structure, props interface, and placement under `src/components/`. Use when adding a new component from scratch. Map regenerates automatically during `npm run dev`; run `npm run sitecore-tools:generate-map` if dev is not running.
 
 ### content-sdk-component-registration
 
-Registering components in `.sitecore/component-map.ts` only. Required so layout and editing can resolve and render components. Used by getComponentData and editing API routes. Pages Router has a single map.
+Registering components in `.sitecore/component-map.ts` only. Required so layout and editing can resolve and render components. Regenerate `.sitecore/component-map.ts` with `npm run sitecore-tools:generate-map`; edit the map manually only when the generator cannot handle the change. Used by getComponentData and editing API routes.
 
 ### content-sdk-editing-safe-rendering
 
@@ -56,7 +56,7 @@ Sitemap and robots: `src/pages/api/sitemap.ts` and `src/pages/api/robots.ts` wit
 
 ### content-sdk-component-variants
 
-Component variants: different renderings or data-driven variants of the same component type. Use when one component has multiple presentations. Register in `.sitecore/component-map.ts`; getComponentData resolves props.
+Component variants: different renderings or data-driven variants of the same component type. Use when one component has multiple presentations. Regenerate the component map; getComponentData resolves props.
 
 ### content-sdk-troubleshoot-editing
 

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

@@ -16,11 +16,11 @@ Register components in the Sitecore component maps so the layout and editing pip
 
 ## 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.
+- The component maps at `.sitecore/component-map.ts` and `.sitecore/component-map.client.ts` are generated from `src/components/` during `npm run dev` or `npm run build` (each component goes to the server or client map based on `'use client'`); run `npm run sitecore-tools:generate-map` to refresh them manually, and edit the maps only when the generator cannot handle your case.
 
 ## Hard Rules
 
-- Every component rendered from Sitecore layout must be registered. Keep the maps in sync with `src/components/`.
+- Every component rendered from Sitecore layout must be registered. Prefer the project's `sitecore-tools:generate-map` script to keep the maps in sync with `src/components/`. Do not hand-edit generated map entries unless necessary.
 - **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.

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

@@ -16,16 +16,18 @@ Scaffold new Sitecore components so they integrate with the layout and editing p
 ## 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.
+- Decide Server vs Client: default Server; add `'use client'` only for hooks or event handlers.
+- **Map:** Regenerates automatically during `npm run dev` and `npm run build`; otherwise run `npm run sitecore-tools:generate-map` (see content-sdk-component-registration).
+- Run `npm run build` to verify.
 
 ## Hard Rules
 
 - Place components under `src/components/`. Use existing folder conventions.
+- Prefer `npm run sitecore-tools:generate-map` to regenerate the component maps instead of hand-editing them. Only manually register the component if the generator cannot handle the change.
 - 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.
+- **Server vs Client:** Use Server Components by default. Add `'use client'` only for interactivity (hooks, event handlers). The generator places Server components in `.sitecore/component-map.ts` and Client components in `.sitecore/component-map.client.ts`.
+- Ensure the component appears in the correct map after regeneration (or update the map manually only if the generator cannot handle the case) before considering the task complete (see content-sdk-component-registration).
 
 ## Stop Conditions
 

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

@@ -22,7 +22,7 @@ One component definition can have multiple presentations or data-driven variants
 - 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/.
+- Prefer `sitecore-tools:generate-map` to keep the maps in sync with `src/components/`.
 
 ## Stop Conditions
 

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

@@ -21,6 +21,8 @@ npm run type-check   # Run TypeScript compiler
 
 **Environment:** Copy `.env.example` to `.env.local` and set Sitecore API endpoint, key, default site, and language. Never commit `.env` or `.env.local`.
 
+**Component maps:** `.sitecore/component-map.ts` (Server) and `.sitecore/component-map.client.ts` (Client) are 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 in the appropriate map (Server vs Client based on `'use client'`).
+
 ---
 
 ## Application Structure (App Router)
@@ -82,7 +84,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 ### More (component maps, editing, env)
 
-- **Component maps:** `.sitecore/component-map.ts` (Server) and `.sitecore/component-map.client.ts` (Client). Register every Sitecore component here; keep in sync with `src/components/`.
+- **Component maps:** `.sitecore/component-map.ts` (Server) and `.sitecore/component-map.client.ts` (Client) — Lists every Sitecore component the layout can render, the maps are auto-generated from `src/components/`. Do not edit manually unless needed.
 - **Editing/preview:** Use `draftMode()` in Server Components; when enabled, use `client.getPreview(searchParams)` or `client.getDesignLibraryData(searchParams)`. Editing API routes live under `src/app/api/editing/`.
 - **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`.
 
@@ -144,7 +146,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 ### Component maps and layout
 
-- **Server/client components:** `.sitecore/component-map.ts` (Server); `.sitecore/component-map.client.ts` (Client). Register all Sitecore components; keep in sync with `src/components/`.
+- **Server/client components:** `.sitecore/component-map.ts` (Server) and `.sitecore/component-map.client.ts` (Client) — Lists every Sitecore component the layout can render, the maps are auto-generated from `src/components/`. Do not edit manually unless needed.
 - **Layout:** `Layout.tsx` renders page layout and placeholders; `Providers` wrap page and component context; `Bootstrap` in `[site]/layout.tsx` receives `siteName={site}` and preview state.
 
 ---
@@ -154,7 +156,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 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.
+- **Sitecore patterns:** Use SDK field components (`<Text>`, `<RichText>`, `<Image>`) and validate field existence before render. Regenerate the component maps with `npm run sitecore-tools:generate-map` or `npm run sitecore-tools:generate-map:watch`; edit the maps manually only when the generator cannot handle the change. 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.
 
 ---
@@ -188,7 +190,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 ## Example agent tasks
 
-- **Add a new Sitecore component:** Create the component under `src/components/`, register it in `.sitecore/component-map.ts` and `.sitecore/component-map.client.ts` as appropriate (client components in the client map), and ensure it is rendered in the layout/placeholder as in existing components.
+- **Add a new Sitecore component:** Create the component under `src/components/` (maps regenerate 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/app/api/` (e.g. `src/app/api/my-route/route.ts`), add a rewrite in `next.config.ts` if the route should be reached from a public URL, and ensure the proxy `matcher` in `proxy.ts` still excludes it (e.g. `api/` is already excluded).
 
 ---
@@ -201,7 +203,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 **Edit with care:** `next.config.ts` (rewrites, next-intl plugin), `sitecore.config.ts` (env only), `proxy.ts` (matcher and proxy order), `src/i18n/routing.ts` and `request.ts`. When adding routes or rewrites, keep middleware `matcher` and rewrite rules consistent.
 
-**Focus on:** `src/app/`, `src/components/`, `src/lib/`, `src/i18n/`, `Layout.tsx`, `Providers.tsx`, `sitecore.config.ts`, `next.config.ts`, `proxy.ts`, `.sitecore/component-map.ts`, `.sitecore/component-map.client.ts`.
+**Focus on:** `src/app/`, `src/components/`, `src/lib/`, `src/i18n/`, `Layout.tsx`, `Providers.tsx`, `sitecore.config.ts`, `next.config.ts`, `proxy.ts`. `.sitecore/component-map.ts` and `.sitecore/component-map.client.ts` are auto-generated — do not edit manually.
 
 ---
 

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

@@ -16,11 +16,11 @@ Grouping related capabilities makes it easier to know which area of the app appl
 
 ### content-sdk-component-scaffold
 
-Creating new Sitecore components: file structure, props interface, and placement under `src/components/`. Use when adding a new component from scratch. In App Router, decide Server vs Client and register in the appropriate map.
+Creating new Sitecore components: file structure, props interface, and placement under `src/components/`. Use when adding a new component from scratch. Map regenerates automatically during `npm run dev`; run `npm run sitecore-tools:generate-map` if dev is not running. In App Router, decide Server vs Client (`'use client'`) so the generator places the entry in the correct map.
 
 ### content-sdk-component-registration
 
-Registering components in `.sitecore/component-map.ts` (Server) and `.sitecore/component-map.client.ts` (Client). Required so layout and editing can resolve and render components. App Router has separate server and client maps.
+Registering components in `.sitecore/component-map.ts` (Server) and `.sitecore/component-map.client.ts` (Client). Required so layout and editing can resolve and render components. Regenerate with `npm run sitecore-tools:generate-map`; edit the maps manually only when the generator cannot handle the change. App Router has separate server and client maps.
 
 ### content-sdk-editing-safe-rendering
 
@@ -56,7 +56,7 @@ Sitemap and robots: `src/app/api/sitemap/route.ts` and `src/app/api/robots/route
 
 ### content-sdk-component-variants
 
-Component variants: different renderings or data-driven variants of the same component type. Use when one component has multiple presentations. Register in the appropriate component map (server or client).
+Component variants: different renderings or data-driven variants of the same component type. Use when one component has multiple presentations. Regenerate the component maps.
 
 ### content-sdk-troubleshoot-editing
 

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

@@ -16,11 +16,11 @@ Register components in the Sitecore component maps so the layout and editing pip
 
 ## 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.
+- The component maps at `.sitecore/component-map.ts` and `.sitecore/component-map.client.ts` are generated from `src/components/` during `npm run dev` or `npm run build` (each component goes to the server or client map based on `'use client'`); run `npm run sitecore-tools:generate-map` to refresh them manually, and edit the maps only when the generator cannot handle your case.
 
 ## Hard Rules
 
-- Every component rendered from Sitecore layout must be registered. Keep the maps in sync with `src/components/`.
+- Every component rendered from Sitecore layout must be registered. Prefer the project's `sitecore-tools:generate-map` script to keep the maps in sync with `src/components/`. Do not hand-edit generated map entries unless necessary.
 - **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.

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

@@ -16,17 +16,19 @@ Scaffold new Sitecore components so they integrate with the layout and editing p
 ## 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.
+- Decide Server vs Client: default Server; add `'use client'` only for hooks or event handlers.
+- **Map:** Regenerates automatically during `npm run dev` and `npm run build`; otherwise run `npm run sitecore-tools:generate-map` (see content-sdk-component-registration).
+- Run `npm run build` to verify.
 
 ## Hard Rules
 
 - Place components under `src/components/`. Use existing folder conventions.
+- Prefer `npm run sitecore-tools:generate-map` to regenerate the component maps instead of hand-editing them. Only manually register the component if the generator cannot handle the change.
 - 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`.
+- **Server vs Client:** Use Server Components by default. Add `'use client'` only for interactivity (hooks, event handlers). The generator places Server components in `.sitecore/component-map.ts` and Client components in `.sitecore/component-map.client.ts`.
 - Do not fetch Sitecore data inside the component (no `getSitecorePage` / `client.getPage` calls). Component data comes from the cached page read at the page level.
-- After creating the component file, register it in the correct component map (see content-sdk-component-registration). Do not leave the component unregistered.
+- Ensure the component appears in the correct map after regeneration (or update the map manually only if the generator cannot handle the case) before considering the task complete (see content-sdk-component-registration).
 
 ## Stop Conditions
 

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

@@ -22,7 +22,7 @@ One component definition can have multiple presentations or data-driven variants
 - 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/.
+- Prefer `sitecore-tools:generate-map` to keep the maps in sync with `src/components/`.
 
 ## Stop Conditions
 

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

@@ -23,6 +23,8 @@ npm run type-check   # Run TypeScript compiler
 
 **Environment:** Copy `.env.example` to `.env.local` and set Sitecore API endpoint, key, default site, language, and `SITECORE_REVALIDATE_SECRET` (used by `POST /api/revalidate`). Never commit `.env` or `.env.local`.
 
+**Component maps:** `.sitecore/component-map.ts` (Server) and `.sitecore/component-map.client.ts` (Client) are 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 in the appropriate map (Server vs Client based on `'use client'`).
+
 ---
 
 ## Application Structure (App Router + Cache Components)
@@ -110,7 +112,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 ### More (component maps, editing, env)
 
-- **Component maps:** `.sitecore/component-map.ts` (Server) and `.sitecore/component-map.client.ts` (Client). Register every Sitecore component here; keep in sync with `src/components/`.
+- **Component maps:** `.sitecore/component-map.ts` (Server) and `.sitecore/component-map.client.ts` (Client) — Lists every Sitecore component the layout can render, the maps are auto-generated from `src/components/`. Do not edit manually unless needed.
 - **Editing/preview:** Use `draftMode()` in Server Components; when enabled, use `client.getPreview(searchParams)` or `client.getDesignLibraryData(searchParams)` **directly** (do not route preview through the cache helpers). Editing API routes live under `src/app/api/editing/`.
 - **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`. `SITECORE_REVALIDATE_SECRET` is optional (see `.env.*.example` comments).
 
@@ -189,7 +191,7 @@ This template ships **two** not-found components and a segment layout that ties
 
 ### Component maps and layout
 
-- **Server/client components:** `.sitecore/component-map.ts` (Server); `.sitecore/component-map.client.ts` (Client). Register all Sitecore components; keep in sync with `src/components/`.
+- **Server/client components:** `.sitecore/component-map.ts` (Server) and `.sitecore/component-map.client.ts` (Client) — Lists every Sitecore component the layout can render, the maps are auto-generated from `src/components/`. Do not edit manually unless needed.
 - **Layout:** `Layout.tsx` renders page layout and placeholders; `Providers` wrap page and component context; `Bootstrap` in `[site]/layout.tsx` receives `siteName={site}` and preview state.
 
 ---
@@ -199,7 +201,7 @@ This template ships **two** not-found components and a segment layout that ties
 - **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 `getSitecoreDictionary`. If a content change does not appear, verify the webhook posted to `POST /api/revalidate` with the right secret and check the tag families (`sc:route`, `sc:item`, `sc:dict`) returned by the cache helpers.
 - **Security:** Use only environment variables in `sitecore.config.ts`; never hardcode API keys, editing secret, or `SITECORE_REVALIDATE_SECRET`. Do not expose secrets in client-side code or logs. Validate and sanitize user input at boundaries.
 - **Performance:** Keep middleware lightweight; use the proxy `matcher` so it does not run on `/api/*`, `_next`, sitemap, robots, or static assets. Use Server Components for data fetching and the cache helpers under `'use cache'` so cached payloads carry the right tags. 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 cache helpers in `src/lib/cache/` for all non-preview Sitecore reads so tags stay consistent across the app.
+- **Sitecore patterns:** Use SDK field components (`<Text>`, `<RichText>`, `<Image>`) and validate field existence before render. Regenerate the component maps with `npm run sitecore-tools:generate-map` or `npm run sitecore-tools:generate-map:watch`; edit the maps manually only when the generator cannot handle the change. Use the cache helpers in `src/lib/cache/` for all non-preview Sitecore reads so tags stay consistent across the app.
 - **Consistency:** Follow the existing patterns in `[site]/[locale]/[[...path]]/page.tsx`, `not-found.tsx`, `i18n/request.ts` (site_locale + `getSitecoreDictionary`), and API route handlers. When adding routes or rewrites, keep the middleware matcher and next-intl config in sync.
 
 ---
@@ -238,7 +240,7 @@ This template ships **two** not-found components and a segment layout that ties
 
 ## Example agent tasks
 
-- **Add a new Sitecore component:** Create the component under `src/components/`, register it in `.sitecore/component-map.ts` and `.sitecore/component-map.client.ts` as appropriate (client components in the client map), and ensure it is rendered in the layout/placeholder as in existing components.
+- **Add a new Sitecore component:** Create the component under `src/components/` (maps regenerate 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/app/api/` (e.g. `src/app/api/my-route/route.ts`), add a rewrite in `next.config.ts` if the route should be reached from a public URL, and ensure the proxy `matcher` in `proxy.ts` still excludes it (e.g. `api/` is already excluded). If the route returns cached data, decide whether to use `'use cache'` with a Sitecore tag and how it should be invalidated.
 - **Add a new cache helper:** Add a file under `src/lib/cache/`. Inside the function, declare `'use cache';`, call the SDK client, compute Sitecore tags via the SDK helpers (`collectSitecorePageCacheTags`, `buildSitecoreDictionaryCacheTag`, etc.), and call `cacheTag(tag)` for each one. Match the style of `get-sitecore-page.ts`.
 
@@ -252,7 +254,7 @@ This template ships **two** not-found components and a segment layout that ties
 
 **Edit with care:** `next.config.ts` (`cacheComponents: true`, rewrites, next-intl plugin), `sitecore.config.ts` (env only; keep dictionary cache disabled), `proxy.ts` (matcher and proxy order), `src/i18n/routing.ts` and `request.ts`, `src/lib/cache/*` (tag computation). When adding routes or rewrites, keep middleware `matcher` and rewrite rules consistent.
 
-**Focus on:** `src/app/`, `src/components/`, `src/lib/`, `src/lib/cache/`, `src/i18n/`, `Layout.tsx`, `Providers.tsx`, `sitecore.config.ts`, `next.config.ts`, `proxy.ts`, `.sitecore/component-map.ts`, `.sitecore/component-map.client.ts`.
+**Focus on:** `src/app/`, `src/components/`, `src/lib/`, `src/lib/cache/`, `src/i18n/`, `Layout.tsx`, `Providers.tsx`, `sitecore.config.ts`, `next.config.ts`, `proxy.ts`. `.sitecore/component-map.ts` and `.sitecore/component-map.client.ts` are auto-generated — do not edit manually.
 
 ---
 

package/dist/templates/nextjs-app-router-cache-components/Skills.md

@@ -16,11 +16,11 @@ Grouping related capabilities makes it easier to know which area of the app appl
 
 ### content-sdk-component-scaffold
 
-Creating new Sitecore components: file structure, props interface, and placement under `src/components/`. Use when adding a new component from scratch. In App Router, decide Server vs Client and register in the appropriate map.
+Creating new Sitecore components: file structure, props interface, and placement under `src/components/`. Use when adding a new component from scratch. Map regenerates automatically during `npm run dev`; run `npm run sitecore-tools:generate-map` if dev is not running. In App Router, decide Server vs Client (`'use client'`) so the generator places the entry in the correct map.
 
 ### content-sdk-component-registration
 
-Registering components in `.sitecore/component-map.ts` (Server) and `.sitecore/component-map.client.ts` (Client). Required so layout and editing can resolve and render components. App Router has separate server and client maps.
+Registering components in `.sitecore/component-map.ts` (Server) and `.sitecore/component-map.client.ts` (Client). Required so layout and editing can resolve and render components. Regenerate with `npm run sitecore-tools:generate-map`; edit the maps manually only when the generator cannot handle the change. App Router has separate server and client maps.
 
 ### content-sdk-editing-safe-rendering
 
@@ -56,7 +56,7 @@ Sitemap and robots: `src/app/api/sitemap/route.ts` and `src/app/api/robots/route
 
 ### content-sdk-component-variants
 
-Component variants: different renderings or data-driven variants of the same component type. Use when one component has multiple presentations. Register in the appropriate component map (server or client).
+Component variants: different renderings or data-driven variants of the same component type. Use when one component has multiple presentations. Regenerate the component maps.
 
 ### content-sdk-troubleshoot-editing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-content-sdk-app",
-  "version": "2.2.0",
+  "version": "2.2.1-canary.20260630132751",
   "description": "Sitecore Content SDK initializer",
   "bin": "./dist/index.js",
   "scripts": {