[create-content-sdk-app] document auto-generated component maps in agent guides

.changeset/forty-lions-hug.md

@@ -0,0 +1,5 @@
+---
+'create-content-sdk-app': minor
+---
+
+[create-content-sdk-app] Update template agent docs to describe auto-generated component maps

packages/create-content-sdk-app/src/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.

packages/create-content-sdk-app/src/templates/nextjs-app-router-cache-components/.agents/skills/content-sdk-component-scaffold/SKILL.md

@@ -16,12 +16,14 @@ 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 `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`.

packages/create-content-sdk-app/src/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
 

packages/create-content-sdk-app/src/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)
@@ -109,7 +111,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) — register every Sitecore component here; 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).
 
@@ -188,7 +190,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) — register all Sitecore components. 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.
 
 ---
@@ -198,7 +200,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.
 
 ---
@@ -236,7 +238,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`.
 
@@ -250,7 +252,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.
 
 ---
 

packages/create-content-sdk-app/src/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
 

packages/create-content-sdk-app/src/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.

packages/create-content-sdk-app/src/templates/nextjs-app-router/.agents/skills/content-sdk-component-scaffold/SKILL.md

@@ -16,12 +16,14 @@ 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 `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`.

packages/create-content-sdk-app/src/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