@forgecart/cli 2.202610052310.0 → 2.202610060357.0

package/templates/storefront-shadcn/SEO-MIGRATION.md

@@ -0,0 +1,708 @@
+# Storefront SEO migration
+
+This document migrates a storefront that was built before the platform's locale and SEO layer
+existed. It is written for the agent that edits this storefront. The operator (the person who runs
+this store) hands it to you; no platform process runs it. Follow it top to bottom, as one piece of
+work, and finish with the DONE summary in the last section.
+
+**This file is platform-owned. Do not edit this file**, and do not record progress in it. The
+operator does not edit it either. `forgecart refresh` replaces an unchanged copy with every newer
+version and leaves an edited copy alone, reporting it under `conflicts` — an edited copy stops
+receiving corrections. Your progress goes in the DONE summary.
+
+**How it arrived.** The operator ran the template refresh with no `adopt` list. The refresh:
+
+- wrote every platform file that was missing, or unchanged since it was generated, at the current
+  platform version, and listed it under `rendered`;
+- left every platform file that differs from the current platform version untouched, and listed it
+  under `conflicts`;
+- listed every platform file that already matched under `upToDate`;
+- never touched a file the platform does not ship.
+
+**Does the migration apply?** Yes, when that refresh listed `src/lib/locale/grammar.ts` or
+`src/lib/seo/metadata.ts` under `rendered`: neither file existed in this storefront before. There
+is no version number to check instead. If you do not have the report, run the sweep in the
+deletion list: any match outside the listed platform matches means the migration applies. With no
+such match there is nothing to migrate — report that, with the sweep as evidence, and stop.
+
+**What `conflicts` contains.** A provisioned storefront usually has no
+`.forgecart/template-manifest.json` before its first refresh, so the refresh cannot tell a file the
+merchant customized from a file that is only an older platform version: `conflicts` lists every
+platform file that differs from the current version. The merge steps handle both kinds the same
+way. The refresh wrote the manifest, so every later refresh is exact.
+
+**The tree is mixed until you finish.** New platform modules now sit next to old files. For
+example, `src/app/sitemap.ts` imports `getProductSeoEntries` and `getServedPageRoutes` from
+`src/lib/forgecart.ts`; an older `src/lib/forgecart.ts` exports neither, so `/sitemap.xml` fails
+until that file is merged. Therefore:
+
+1. Do the migration as its own work. Do not mix feature changes into the same turns.
+2. Put the deletions and the platform-file merges in the same promote.
+3. Do not ask the operator to publish until every step of the verification section passes.
+
+**The refresh operation.** You call it to take the platform version of a file (to adopt it):
+
+```text
+CallAdminOperation { "name": "workspaceTemplate.adminRefreshWorkspaceTemplate", "args": { "input": { "adopt": ["src/middleware.ts", "src/lib/forgecart.ts"] } } }
+```
+
+It is the admin mutation `refreshWorkspaceTemplate(input: { adopt: [...] })` and returns
+`rendered`, `conflicts`, `adopted`, `upToDate` and `dependenciesChanged`. Each `adopt` path must
+be one a refresh reported under `conflicts`. When `dependenciesChanged` is `true`, dependencies were
+re-installed before the call returned. `WORKSPACE_TEMPLATE_REFRESH_UNAVAILABLE` means the
+workspace is not running yet; retry.
+
+## What the platform now ships
+
+The layer the migration moves this storefront onto. Every rule below is implemented by a platform
+file; your job is to call it, never to reimplement it.
+
+- **The URL is the only language selector.** The channel's default language is served unprefixed
+  (`/products`); every other language under its two-letter prefix (`/de/products`). Both render the
+  SAME route: the middleware rewrites `/de/products` to `/products` and passes the language on. There
+  is no `[locale]` segment, no query parameter and no cookie that selects a language.
+- **Two-letter top-level segments are reserved** for languages. Routes that exist once per store —
+  `/sitemap.xml`, `/robots.txt`, `/ping`, `/api`, `/__fc`, `/__forge_beacon`, `/verify`,
+  `/reset-password` — never take a prefix.
+- **The root layout decides the status.** A prefix naming the default language answers 308 to the
+  unprefixed URL (`/en/products` → `/products`); a prefix the channel does not offer answers 404.
+- **Links stay in their language.** Every internal link is a `LocaleLink` with the unprefixed path;
+  outside JSX, `localizedPath(path, binding)`. The language switcher uses plain anchors with
+  `hrefLang`, so switching loads a new document.
+- **`src/middleware.ts` is the only `Content-Language` emitter.** Every page under a language prefix
+  answers with exactly one `Content-Language: <xx>`; an unprefixed page answers with none — its
+  `<html lang>` states the language.
+- **Metadata is composed, never hand-built.** Every route's `generateMetadata` returns
+  `routeMetadata(...)`; the root layout returns `shellMetadata(...)`; an entity's title, description
+  and social image come from `entityMetadata(...)`. Canonical, hreflang, `x-default`, robots and
+  social tags are produced together and cannot disagree.
+- **Product URLs resolve themselves.** `resolveProductPath` answers a stale slug, a renamed
+  product's previous slug and another language's slug with one 308 to the current address. Product
+  renames never need a redirect entry.
+- **The XML sitemap** is `/sitemap.xml`, built by `src/app/sitemap.ts` from `STATIC_ROUTES`, the
+  fragments in `src/seo/routes.d/`, the published pages under `/pages/<route>` and the catalog.
+- **`robots.txt`** is built by `src/app/robots.ts` from `NOINDEX_PATHS` and `NOINDEX_QUERY_KEYS`.
+- **One noindex mechanism:** the metadata `robots` field. No `X-Robots-Tag` header anywhere.
+- **Structured data** is Product + BreadcrumbList on a product page and exactly one BlogPosting on a
+  blog post, nothing else. Organization, WebSite, logo, `sameAs` and SearchAction are refused.
+- **Rename redirects** live in `REDIRECTS` in `src/seo/redirects.ts` and work without a restart.
+- **Preview posture.** A deployment without `FORGECART_PUBLIC_ORIGIN` — every preview — marks every
+  page noindex, emits relative canonicals, serves `robots.txt` as `Disallow: /` and an empty XML
+  sitemap. A published deployment gets its origin from `forgecart init --public-origin`.
+- **One SDK client per language.** Changing the language of a shared client is the defect this
+  replaces.
+- **Site verification.** The root layout reads the search-console verification placements with
+  `getSiteVerifications()` and passes them to `shellMetadata`, so every page serves them as
+  `<meta>` tags.
+
+The platform files, and the symbols they export:
+
+| File                                  | What it gives you                                                                                 | Symbols                                                                                                                        |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `src/lib/locale/grammar.ts`           | The URL grammar: default language unprefixed, others under `/<xx>/`, reserved segments            | `isLocaleSegment`, `isUnprefixedPath`, `parseLocalePath`, `stripLocalePrefix`, `localePrefixedPath`                            |
+| `src/lib/locale/middleware-plan.ts`   | The locale-rewrite decision the middleware applies                                                | `planLocaleRewrite`, `localeRequestHeaders`, `hasServerAuthoredHeaders`, `LOCALE_REQUEST_HEADER`                               |
+| `src/middleware.ts`                   | Rename redirects, the locale rewrite, the `Content-Language` header, visitor and campaign cookies | `middleware`, `config`                                                                                                         |
+| `src/lib/locale/request-binding.ts`   | The request's language, resolved once per request                                                 | `getRequestLocale`, `RequestLocale`                                                                                            |
+| `src/lib/locale/request-locale.ts`    | Render, 308 to the unprefixed default, or 404 for a language the channel does not offer           | `decideRequestLocale`, `LocaleDecision`                                                                                        |
+| `src/lib/locale/localized-path.ts`    | Paths in the current language, and the switcher's target                                          | `localizedPath`, `switchedLocalePath`, `LocaleBinding`                                                                         |
+| `src/components/LocaleLink.tsx`       | The internal link                                                                                 | `LocaleLink`, `LocaleLinkProps`                                                                                                |
+| `src/components/LanguageSwitcher.tsx` | The language switcher                                                                             | `LanguageSwitcher`                                                                                                             |
+| `src/lib/seo/metadata.ts`             | Title, description, canonical, hreflang, robots, social and verification tags, composed           | `routeMetadata`, `shellMetadata`, `entityMetadata`, `buildMetadata`, `buildShellMetadata`, `pageTitle`, `SiteVerificationMeta` |
+| `src/lib/seo/alternates.ts`           | Self-canonical and reciprocal hreflang with `x-default`                                           | `buildAlternates`, `staticPathsByLocale`, `PathsByLocale`                                                                      |
+| `src/lib/seo/resolve-path.ts`         | The product slug law: 308 for stale, previous and other-language slugs                            | `resolveProductPath`, `productPathsByLocale`, `PathResolution`                                                                 |
+| `src/lib/seo/noindex.ts`              | Which pages and query states are noindex                                                          | `NOINDEX_PATHS`, `NOINDEX_QUERY_KEYS`, `shouldNoindex`, `routeRobots`, `deploymentRefusesIndexing`, `NOINDEX_ROBOTS`           |
+| `src/lib/seo/public-origin.ts`        | The deployment's public origin, absent on previews                                                | `getPublicOrigin`, `resolvePublicOrigin`                                                                                       |
+| `src/app/sitemap.ts`                  | The XML sitemap at `/sitemap.xml`                                                                 | `sitemap`, `dynamic`                                                                                                           |
+| `src/lib/seo/sitemap-entries.ts`      | The route table and the rules for the XML sitemap's rows                                          | `STATIC_ROUTES`, `StaticRoute`, `SCAFFOLDED_ROUTES_DIR`, `mergeScaffoldedRoutes`, `pageSitemapRoutes`, `MAX_SITEMAP_URLS`      |
+| `src/lib/seo/scaffolded-routes.ts`    | Reads the `src/seo/routes.d/*.json` fragments                                                     | `readScaffoldedRoutes`                                                                                                         |
+| `src/app/robots.ts`                   | `robots.txt`                                                                                      | `robots`, `dynamic`                                                                                                            |
+| `src/lib/seo/json-ld.ts`              | Product, BreadcrumbList and BlogPosting nodes, and their safe serialization                       | `productJsonLd`, `breadcrumbJsonLd`, `blogPostingJsonLd`, `serializeJsonLd`, `JsonLdNode`                                      |
+| `src/seo/redirects.ts`                | The rename-redirect table you fill                                                                | `REDIRECTS`, `RedirectRule`                                                                                                    |
+| `src/lib/seo/redirect-plan.ts`        | The redirect rule: exact match, chains collapsed, cycles refused                                  | `planRedirect`, `MAX_REDIRECT_HOPS`                                                                                            |
+| `src/lib/seo/site-verification.ts`    | The search-console verification placements, read per request                                      | `getSiteVerifications`                                                                                                         |
+| `src/lib/forgecart.ts`                | One shop client per language, and the reads the XML sitemap and the product page use              | `getShopClientForLocale`, `getShopClient`, `getProductBySlug`, `ProductWithSeo`, `getProductSeoEntries`, `getServedPageRoutes` |
+| `src/app/layout.tsx`                  | `<html lang>`, the 308 and 404 decisions, and the metadata floor every page inherits              | `generateMetadata`, `RootLayout`                                                                                               |
+| `src/app/products/[slug]/page.tsx`    | The product page: slug law, entity metadata, Product and BreadcrumbList                           | `generateMetadata`, `ProductDetailPage`                                                                                        |
+| `src/lib/asset-alt.ts`                | The `alt` text of an asset image                                                                  | `getAssetAlt`                                                                                                                  |
+
+## The deletion list
+
+Each class below is improvised code that the platform now provides. For every class:
+
+1. Find it with the sweep rows the class names.
+2. Delete the files listed under **Delete:** — under whatever name this storefront used.
+3. Remove the code listed under **Remove:** from the files that stay.
+4. Use what **Replaced by:** names instead.
+5. Add every deleted path to the DONE summary's `Deleted:` list.
+
+**Who deletes.** The platform's storefront agent cannot delete files yet: its file tools are
+`Read`, `Write`, `Edit`, `Glob` and `Grep`. A `DeleteFile` storefront tool is a tracked follow-up.
+Until it ships, the **Delete:** steps are carried out by an agent or operator with file-deletion
+capability on the workspace. Before the promote that carries the deletions, confirm with `Glob`
+that every path on your `Deleted:` list is gone.
+
+Rules that apply to every class:
+
+- **Replace, never keep both.** An improvised helper left beside the platform one is a second source
+  of truth, and the next change calls the wrong one.
+- **Never delete a platform file.** Every platform file appears in exactly one list of the refresh
+  report (`rendered`, `conflicts`, `adopted`, `upToDate`). A path on any of those lists is merged —
+  see the merge steps — never deleted.
+- **Delete a file only when nothing imports it.** Grep for its module path first and move every
+  importer onto the platform helper in the same change.
+
+### The sweep
+
+Run every row on the whole storefront. `Grep` rows are extended regular expressions (the Grep tool
+runs `grep -E`); escape them as JSON strings when you pass them. `Glob` rows are file patterns from
+the storefront root. The platform matches listed on each row are platform files that match on
+purpose — leave them. Every other match is improvised code this migration removes.
+
+- **S1** Glob `middleware.*` — platform matches: none
+- **S2** Glob `src/middleware.*` — platform matches: `src/middleware.ts`
+- **S3** Glob `proxy.*` — platform matches: none
+- **S4** Glob `src/proxy.*` — platform matches: none
+- **S5** Grep `NextResponse\.rewrite` in `src` — platform matches: `src/middleware.ts`
+- **S6** Grep `(function|const) (localizedPath|withLocale|buildHref|localizeHref|localePath)` in `src` — platform matches: `src/lib/locale/localized-path.ts`
+- **S7** Grep `/\$\{(lang|locale|language)\}` in `src` — platform matches: `src/lib/locale/grammar.ts`
+- **S8** Grep `from ['"]next/link['"]` in `src` — platform matches: `src/components/LocaleLink.tsx`
+- **S9** Glob `src/lib/seo.*` — platform matches: none
+- **S10** Grep `<link rel=['"](canonical|alternate)` in `src` — platform matches: `src/components/LanguageSwitcher.tsx`, `src/lib/seo/json-ld.ts`
+- **S11** Grep `<html lang=['"]` in `src` — platform matches: `src/app/global-error.tsx`, `src/lib/locale/channel-locales-loader.ts`
+- **S12** Glob `src/app/sitemap*` — platform matches: `src/app/sitemap.ts`
+- **S13** Glob `public/sitemap*` — platform matches: none
+- **S14** Glob `next-sitemap.config.*` — platform matches: none
+- **S15** Glob `src/app/robots*` — platform matches: `src/app/robots.ts`
+- **S16** Glob `public/robots.txt` — platform matches: none
+- **S17** Grep `(redirects|headers)(\(\) *\{| *:)|i18n *:` in `next.config.js` — platform matches: none
+- **S18** Grep `Response\.redirect\(` in `src` — platform matches: `src/middleware.ts`
+- **S19** Grep `['"]Content-Language['"]` in `src` — platform matches: `src/middleware.ts`
+- **S20** Grep `[hH]ttp-?[eE]quiv` in `src` — platform matches: none
+- **S21** Grep `[?&](lang|locale)=` in `src` — platform matches: none
+- **S22** Grep `[pP]arams\.(lang|locale)|\.get\(['"][A-Za-z_-]*(lang|locale|language)['"]\)` in `src` — platform matches: none
+- **S23** Glob `src/components/language-switcher.*` — platform matches: none
+- **S24** Grep `[Aa]ccept-[Ll]anguage|NEXT_LOCALE` in `src` — platform matches: none
+- **S25** Grep `application/ld\+json` in `src` — platform matches: `src/app/products/[slug]/page.tsx`, `src/lib/seo/json-ld.ts`
+- **S26** Grep `['"]@type['"]: *['"](Organization|WebSite)` in `src` — platform matches: none
+- **S27** Grep `\.setLanguageCode\(` in `src` — platform matches: `src/lib/shop-session.ts`
+- **S28** Grep `['"]X-Robots-Tag['"]` in `src` — platform matches: none
+
+One check is by inspection: Glob `src/app/*` and read the top-level route directories. A
+`[locale]`, `[lang]` or two-letter directory (`src/app/de/`) belongs to the `[locale]` class below.
+
+### Improvised middleware locale stages
+
+- **Find:** S1–S5. A second middleware or proxy file, or a rewrite outside `buildBaseResponse` in
+  `src/middleware.ts`.
+- **Delete:** `middleware.ts`, `middleware.js`, `src/middleware.js`, `proxy.ts`, `src/proxy.ts`
+- **Remove:** a language rewrite, redirect or matcher inside `src/middleware.ts` — by merging that
+  file (merge steps).
+- **Replaced by:** the platform `src/middleware.ts` and `planLocaleRewrite`. That file is merged,
+  never deleted: it also carries the rename redirects and the visitor and campaign cookies.
+
+### `localizedPath` twins and bare links
+
+- **Find:** S6–S8. A link helper defined outside the platform files, a path built by hand as
+  `/${locale}/…`, or `next/link` imported anywhere but `LocaleLink`.
+- **Delete:** `src/lib/localized-path.ts`
+- **Remove:** hand-prefixed hrefs and bare `next/link` imports in components that stay.
+- **Replaced by:** `LocaleLink` in JSX (`href` is the unprefixed path, `locale` is the request's
+  `LocaleBinding`) and `localizedPath(path, binding)` outside JSX. Trap: the platform file
+  `src/lib/locale/localized-path.ts` has the same basename as the usual twin. Keep it.
+
+### Hand-written `seo.ts` metadata helpers
+
+- **Find:** S9–S11. A metadata helper module, hand-written head tags, a literal `<html lang>`.
+- **Delete:** `src/lib/seo.ts`
+- **Remove:** hand-written `<link rel="canonical">` and `<link rel="alternate" hreflang>` tags,
+  static `export const metadata` objects, and `alternates`, `canonical` or `robots` values built
+  by hand in a route's metadata.
+- **Replaced by:** `routeMetadata(...)` in every route's `generateMetadata`, `shellMetadata(...)` in
+  the root layout, and `entityMetadata(...)` for an entity (`src/lib/seo/metadata.ts`).
+
+### XML sitemap emitters other than `src/app/sitemap.ts`
+
+- **Find:** S12–S14.
+- **Delete:** `src/app/sitemap.xml/route.ts`, `public/sitemap.xml`, `next-sitemap.config.js`
+- **Remove:** a `postbuild` script that runs `next-sitemap`, and the `next-sitemap` dependency (see
+  `package.json` in the merge steps).
+- **Replaced by:** `src/app/sitemap.ts`. A route handler at `src/app/sitemap.xml/route.ts` claims
+  the same URL as that file and must go.
+
+### `robots.txt` files other than `src/app/robots.ts`
+
+- **Find:** S15–S16.
+- **Delete:** `public/robots.txt`, `src/app/robots.txt/route.ts`
+- **Replaced by:** `src/app/robots.ts`. To keep a page out of search, make it noindex (see the
+  static pages below); never hand-edit a disallow list.
+
+### Ad-hoc rename redirects and Pages Router `i18n`
+
+- **Find:** S17–S18. `redirects()` or an `i18n` key in `next.config.js`, a redirect map in the old
+  middleware, a route handler that only redirects a moved page.
+- **Delete:** `src/app/<old-path>/route.ts`
+- **Remove:** the `redirects()` function and the `i18n` key from `next.config.js` (merge steps).
+- **Replaced by:** one `REDIRECTS` entry per moved page (see the rename redirects below) and the
+  locale grammar.
+
+### Duplicate `Content-Language` emitters
+
+- **Find:** S17, S19–S20.
+- **Delete:** no file.
+- **Remove:** every `Content-Language` header set outside the rewrite branch of `src/middleware.ts`
+  — a `headers()` entry in `next.config.js`, a second `headers.set('Content-Language', …)`, a route
+  handler — and every `<meta httpEquiv="content-language">`.
+- **Replaced by:** the rewrite branch of `src/middleware.ts` (`buildBaseResponse`). Do not add a
+  header to unprefixed pages: they carry none by design, and a second emitter produces two header
+  lines, which the promote gate reports as `SEO_DUPLICATE_LOCALE_HEADER`.
+
+### `?lang=` and `?locale=` switchers
+
+- **Find:** S21–S23.
+- **Delete:** `src/components/language-switcher.tsx`
+- **Remove:** every read of a `lang` or `locale` query parameter, and every link or `router.push`
+  that sets one.
+- **Replaced by:** `LanguageSwitcher` (`src/components/LanguageSwitcher.tsx`), which
+  `src/components/Header.tsx` already renders. Trap: `language-switcher.tsx` and
+  `LanguageSwitcher.tsx` differ only in letter case. Delete the lowercase file by its exact path;
+  the platform file exports `LanguageSwitcher` and imports `switchedLocalePath`.
+
+### Language state outside the URL
+
+- **Find:** S24, plus any cookie or `localStorage` entry that stores the language and any redirect
+  of `/` by language.
+- **Delete:** no file.
+- **Remove:** the cookie and storage reads and writes, the `Accept-Language` negotiation, the
+  redirect.
+- **Replaced by:** the URL: the default language unprefixed, every other language under `/<xx>/`.
+
+### `[locale]` segments and per-language route copies
+
+- **Find:** the inspection of `src/app/*` above.
+- **Delete:** `src/app/[locale]/`, `src/app/[lang]/`, `src/app/de/`
+- **Remove:** `generateStaticParams` over languages in the pages you keep.
+- **Replaced by:** one route per page in the flat tree: `src/app/our-story/page.tsx` serves
+  `/our-story` and, through the middleware rewrite, `/de/our-story`. Move each page to its
+  unprefixed route before you delete the segment, and merge per-language copies into that one route:
+  it reads its copy in the request's language (`getRequestLocale()`). A route left in a two-letter
+  directory is reported as `SEO_RESERVED_LOCALE_SEGMENT`.
+
+### Hand-built JSON-LD
+
+- **Find:** S25–S26.
+- **Delete:** no file.
+- **Remove:** every hand-built `<script type="application/ld+json">` and every Organization,
+  WebSite, logo, `sameAs` or SearchAction node.
+- **Replaced by:** `productJsonLd`, `breadcrumbJsonLd`, `blogPostingJsonLd` and `serializeJsonLd`
+  (`src/lib/seo/json-ld.ts`). Anything else is reported as `SEO_FORBIDDEN_JSONLD`.
+
+### Language set on a shared SDK client
+
+- **Find:** S27.
+- **Delete:** no file.
+- **Remove:** every `setLanguageCode(` call on a server-side client, and every module-level client
+  shared across languages.
+- **Replaced by:** `getShopClient()` for the request's language and `getShopClientForLocale(locale)`
+  for an explicit one (`src/lib/forgecart.ts`). Trap: `src/lib/shop-session.ts` calls
+  `client.setLanguageCode(...)` on the shopper's browser session client when the language changes.
+  That is platform code; leave it.
+
+### A second noindex mechanism
+
+- **Find:** S17, S28.
+- **Delete:** no file.
+- **Remove:** every `X-Robots-Tag` header.
+- **Replaced by:** the metadata `robots` field, which `routeMetadata` sets from `NOINDEX_PATHS`,
+  `NOINDEX_QUERY_KEYS`, the deployment's posture and the route's `contentIndexable`.
+
+## Merge steps per platform file — replace, don't add
+
+Every file the refresh listed under `conflicts` is merged with this procedure:
+
+1. **Read it and list what the merchant customized:** markup, copy, styling, extra components,
+   extra helpers, non-SEO settings. Anything the deletion list covers is not a customization — it is
+   what the migration replaces.
+2. **Adopt it** — take the platform version:
+   `CallAdminOperation { "name": "workspaceTemplate.adminRefreshWorkspaceTemplate", "args": { "input": { "adopt": ["<path>"] } } }`.
+   Adopt a file BEFORE you edit it in the turn, never after: adopting writes the live file at once,
+   and an edit made before it was based on the old content, so the promote reports it as a conflict.
+   Adopt several files in one call when you can.
+3. **Re-apply the customizations from step 1 onto the platform version**, through the platform
+   helpers: links as `LocaleLink`, metadata through `routeMetadata`, structured data through
+   `json-ld.ts`. Never paste the old implementation back beside the new one.
+4. **Record it.** With nothing to re-apply, the file is "Adopted as-is". Otherwise it is "Merged".
+
+A merged file keeps appearing under `conflicts` in every later refresh: it now differs from the
+platform version on purpose. An adopted-as-is file appears under `upToDate`.
+
+### `src/middleware.ts`
+
+- This is the one middleware. Keep the platform order inside `middleware()`: `planRedirect(...)`
+  with `REDIRECTS` first (308), then `planLocaleRewrite`, then the visitor and campaign cookie
+  stages.
+- Merchant logic that is not about language or SEO (an access gate, extra response headers) goes
+  inside `middleware()` after the redirect stage. It never rewrites or redirects by language.
+- Keep the platform `export const config` matcher. Never add a second `config`.
+- Never set `Content-Language` or `X-Robots-Tag` here or anywhere else.
+- A rename redirect the old middleware carried becomes a `REDIRECTS` entry, not code here.
+
+### `src/app/layout.tsx`
+
+- `RootLayout` stays `async` and reads `await getRequestLocale()`. It raises
+  `permanentRedirect(decision.to)` and `notFound()` in the shell, before any markup.
+- `<html lang={binding.locale}>` — never a literal language.
+- `generateMetadata` returns `shellMetadata({ shopName, channelResolved, siteVerifications })` with
+  `siteVerifications` from `await getSiteVerifications()`. No static `export const metadata`.
+- Keep the development-only revision stamp: it is merged into `other`, which carries the
+  verification tags — never overwrite `other`.
+- No `<Suspense>` above `<body>`. Keep `CartProvider` with
+  `getBrowserShopConfig(binding.locale)` and `<Header locale={binding} languageCodes={languageCodes} />`.
+- Re-apply the merchant's header and footer chrome and copy; every internal link is
+  `<LocaleLink href="/unprefixed-path" locale={binding}>`.
+
+### `src/app/products/[slug]/page.tsx`
+
+- Keep the slug law in the page shell: `resolveProductPath({ requestedSlug, product, binding })`,
+  `notFound()` for a missing product, `permanentRedirect(resolution.to)` for a redirect.
+- Keep the one product read shared by `generateMetadata` and the page (`productForRequest`).
+- `generateMetadata` returns `routeMetadata` with `pathsByLocale: productPathsByLocale(product)`,
+  title, description and social image from `entityMetadata(product, binding.locale)`, and
+  `contentIndexable` from the resolution.
+- Structured data only through `productJsonLd`, `breadcrumbJsonLd` and `serializeJsonLd`, gated on
+  `routeRobots` exactly as the platform file does it.
+- Re-apply the merchant's display markup inside `ProductDetail`: exactly one `<h1>`, images with
+  `alt={getAssetAlt(asset)}`.
+- Delete language-specific slug lookups: the shop API resolves slugs per language, including a
+  product's previous slug.
+
+### `src/lib/forgecart.ts`
+
+- One shop client per language: `getShopClient()` for the request's language,
+  `getShopClientForLocale(locale)` for an explicit one. No module-level shared client, no
+  `setLanguageCode(`.
+- Keep `getProductBySlug` returning `ProductWithSeo`, `getProductSeoEntries` and
+  `getServedPageRoutes`: `src/app/sitemap.ts` and the product page import them.
+- Re-apply merchant reads as functions on `await getShopClient()`, through the SDK's typed methods.
+
+### `next.config.js`
+
+- Remove `redirects()` (its entries become `REDIRECTS` entries), every `headers()` entry that sets
+  `Content-Language` or `X-Robots-Tag`, and the Pages Router `i18n` key.
+- Keep `cacheComponents: false` as an explicit key. Next re-enables an absent key, and with the
+  option on, the root layout can no longer answer its 308 and 404.
+- Keep the platform's `output`, `serverExternalPackages`, `allowedDevOrigins`, `experimental` and
+  `turbopack` settings.
+- Re-apply merchant settings that are not about language or SEO — for example a narrower
+  `images.remotePatterns`.
+
+### Every other file in `conflicts`
+
+Typical ones: `src/app/page.tsx`, `src/app/products/page.tsx`, `src/components/Header.tsx`,
+`src/components/ProductCard.tsx`, `package.json`. The same procedure applies:
+
+- links as `LocaleLink`; route metadata through `routeMetadata` with
+  `staticPathsByLocale(languageCodes, '<route>')`; images with `alt={getAssetAlt(asset)}`;
+- `package.json`: adopt it. Adopting keeps every package the storefront declares that the platform
+  version does not, and takes the platform's range for a package both declare. Then delete the
+  packages the deletion list removed, such as `next-sitemap`, from it; the promote reinstalls the
+  dependencies. A `package.json` that still declares a package of the storefront's is Merged, with
+  those packages as its customizations.
+
+### Routes the platform does not ship
+
+A merchant route (for example `src/app/our-story/page.tsx`) is not in the refresh report. Migrate
+it in place: `generateMetadata` returns `routeMetadata(...)`, every internal link is a
+`LocaleLink`, the page has exactly one `<h1>`, and it joins the XML sitemap (next section). A route
+that sets `other` in its metadata passes `siteVerifications: await getSiteVerifications()` to
+`routeMetadata` and merges its own keys into the returned `other` — otherwise it replaces the
+verification tags the root layout serves.
+
+### The data tables — never adopt them
+
+`src/seo/redirects.ts` (`REDIRECTS`) and `src/lib/seo/sitemap-entries.ts` (`STATIC_ROUTES`) are
+tables. Never adopt either once it carries a row you or the merchant added: adopting replaces the
+table with the platform's. `src/seo/redirects.ts` with your rows appears under `conflicts` in every
+later refresh — expected. Do not add rows to `STATIC_ROUTES` in this migration: pages join the XML
+sitemap through fragments (next section), which keeps `src/lib/seo/sitemap-entries.ts` identical to
+the platform version, so later refreshes keep updating it.
+
+## Existing rename redirects and static pages
+
+### Rename redirects
+
+1. Collect every rename the old storefront served: `redirects()` in `next.config.js`, redirect
+   maps in the old middleware, route handlers that only redirect a moved page (sweep rows S17, S18).
+2. For each moved page, add one entry to `REDIRECTS` in `src/seo/redirects.ts`:
+   `{ from: '/old-path', to: '/new-path' }`.
+   - Paths are rooted and unprefixed. `/old-path` covers `/de/old-path` too, and each redirects
+     inside its own language. Never write a prefixed path: it covers one language only.
+   - Matching is exact: one entry per moved page. Chains collapse into one 308, and cycles are
+     refused.
+   - Routes that exist once per store (`/sitemap.xml`, `/robots.txt`, `/api/…`, `/ping`,
+     `/verify`, `/reset-password`) are never redirected.
+3. **Product renames are never `REDIRECTS` entries.** The shop API keeps a product's previous slug,
+   and `resolveProductPath` answers it with a 308. Drop the old product redirect instead of moving
+   it.
+4. Remove the old mechanism in the same change (deletion list).
+5. A page that only moved out of a `[locale]` segment or a two-letter directory keeps its URLs —
+   `/de/our-story` is now served by `src/app/our-story/page.tsx` through the rewrite — and needs no
+   entry. A default-language URL the old storefront served under a prefix (`/en/our-story`) is
+   redirected by the platform; it needs no entry either.
+
+### Static pages
+
+1. Every page that is not a platform file and not an ACF page joins the XML sitemap with one
+   fragment file, `src/seo/routes.d/<page>.json`:
+
+   ```json
+   { "path": "/our-story", "indexable": true }
+   ```
+
+   - `path` is rooted and unprefixed. One file per page; the file name names the page.
+   - A malformed fragment is skipped and named in the server log.
+   - A path already in `STATIC_ROUTES` keeps the platform's row; a fragment cannot override it.
+
+2. A session or funnel page (sign-in, account, order status) gets `"indexable": false` in its
+   fragment and `contentIndexable: false` in its `routeMetadata(...)`.
+3. The page's `generateMetadata` has the shape of the one in `src/app/products/page.tsx`:
+
+   ```ts
+   export async function generateMetadata({
+     searchParams,
+   }: {
+     searchParams: Promise<RouteSearchParams>;
+   }): Promise<Metadata> {
+     const [resolvedSearchParams, { binding, languageCodes, shopName, channelResolved }] =
+       await Promise.all([searchParams, getRequestLocale()]);
+     return routeMetadata({
+       binding,
+       shopName,
+       channelResolved,
+       pathname: '/our-story',
+       pathsByLocale: staticPathsByLocale(languageCodes, '/our-story'),
+       searchParams: resolvedSearchParams,
+       title: 'Our story',
+     });
+   }
+   ```
+
+4. ACF pages under `/pages/<route>` join the XML sitemap by themselves. Write no fragment for them.
+5. A page in a two-letter top-level directory moves to a name of three letters or more, with a
+   `REDIRECTS` entry for the old path.
+
+### SEO source mapping for imported page-kind definitions
+
+A route that renders the records of a page-kind definition the merchant imported — a blog, a
+journal, a lookbook, for example `src/app/blog/[slug]/page.tsx` — maps its SEO sources at the route:
+its `generateMetadata` passes the record's own fields, in the request's language, to
+`routeMetadata`. The target is no `SEO_UNMAPPED_PAGE_KIND` on those routes.
+
+ACF pages the platform serves at `/pages/<route>` render the page's name as their title and no
+description, so they report `SEO_UNMAPPED_PAGE_KIND` (a WARN) whatever you do in this migration. Do
+not edit `src/app/pages/[slug]/page.tsx` to silence it; list those routes under Remaining WARNs.
+
+Sign off every imported definition against this table:
+
+| Element          | Where it comes from                                                                       | How you check it                                                              |
+| ---------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| Title tag        | `routeMetadata({ title })` from the record's title field; the shop name is appended       | `<title>` on every language's URL; `SEO_TITLE_MISSING`                        |
+| Meta description | `routeMetadata({ description })` from the record's excerpt field — never the body         | `<meta name="description">` on every language's URL; `SEO_UNMAPPED_PAGE_KIND` |
+| H1               | Exactly one `<h1>`, carrying the text the title comes from                                | `SEO_H1_MISSING`, `SEO_H1_DUPLICATE`                                          |
+| Slug             | The route path, unprefixed; a changed code-page path gets a `REDIRECTS` entry             | `SEO_RENAME_WITHOUT_REDIRECT`                                                 |
+| Excerpt (dek)    | Rendered as the intro paragraph under the `<h1>`, and the same words as the description   | The snapshot of each language's page                                          |
+| Social opt-in    | `socialImage` only when the record has a stored social image; otherwise leave it out      | No `og:*` or `twitter:*` tags without one                                     |
+| Canonical        | Produced by `routeMetadata`; never written by hand                                        | `SEO_CANONICAL_MISSING_OR_FOREIGN` on the published deployment                |
+| Author           | `authorName` in `blogPostingJsonLd(...)`                                                  | The BlogPosting node                                                          |
+| Dates            | `publishedAt` and `updatedAt` in `blogPostingJsonLd(...)`: the shop API's ISO-8601 stamps | `SEO_SCHEMA_BLOGPOSTING_INVALID`                                              |
+| BlogPosting      | Exactly one node per post, from `blogPostingJsonLd(...)` and `serializeJsonLd(...)`       | `SEO_SCHEMA_BLOGPOSTING_INVALID`                                              |
+| Alt              | `alt={getAssetAlt(asset)}` for asset images; an embed's own `alt` for body images         | `SEO_IMG_ALT_MISSING`                                                         |
+| Indexability     | `contentIndexable` in `routeMetadata(...)`, and `indexable` in the page's fragment        | `SEO_NOINDEX_MISSING`                                                         |
+
+### Alt-text backfill
+
+Migrated media arrive with no alt text: an image rendered through `getAssetAlt(asset)` renders
+`alt=""` until its asset is described.
+
+1. Describe each content image once, on its asset — one value for every language:
+   `CallAdminOperation { "name": "asset.updateAsset", "args": { "input": { "id": "<asset id>", "altText": "<what the image shows>" } } }`.
+   The operator can do the same in the dashboard's media library.
+2. Start with hero and featured images, then images inside bodies. An image embedded in a rich-text
+   body carries its own `alt`, per language, in that body.
+3. Decorative images stay `alt=""`. Never fill alt text with a file name or a product name.
+
+Until the backfill is done, `SEO_IMG_ALT_MISSING` WARNs on the routes you change are expected and
+do not block the migration. List the remaining ones in the DONE summary.
+
+## Verification — the crawler assertions and the per-locale browser round
+
+Every step runs on the final tree, after the promote that applied it. Read the channel's languages
+first: `CallAdminOperation { "name": "channel.channels", "args": { "options": { "take": 1 } } }`
+returns `defaultLanguageCode` and `availableLanguageCodes`. The examples use `en` as the default and
+`de` as another language.
+
+### 1. The sweep is clean
+
+Run every sweep row (S1–S28) again. Each returns exactly its platform matches. Then check:
+
+- every path on your `Deleted:` list is gone;
+- no path on your `Deleted:` list appears in any list of the refresh report.
+
+### 2. The crawler assertions — the promote gate
+
+Every promote runs the platform's SEO gate: it crawls the routes the promote changed, in every
+language, on the storefront's own server, plus `/`, `/robots.txt` and `/sitemap.xml`. It is the
+crawler that verifies this migration; `SEO_RED` rolls the promote back and names each finding with
+its route.
+
+- Findings on the routes the promote changed are RED. Findings on routes it did not change, on the
+  links out of `/`, and four codes on every route (`SEO_H1_MISSING`, `SEO_H1_DUPLICATE`,
+  `SEO_IMG_ALT_MISSING`, `SEO_UNMAPPED_PAGE_KIND`) are WARN. `/robots.txt` and `/sitemap.xml` are
+  always RED.
+- It plans at most 25 changed routes per promote and names the ones it skipped. Migrate merchant
+  routes in batches of at most 25, after the promote that carries the deletions and the platform
+  merges.
+- **The preview asserts nothing about its address.** It has no public origin — whether it is the
+  local `<code>.127.0.0.1.nip.io:8081` host or a hosted preview — so every page is noindex, canonicals
+  are relative, `robots.txt` is `Disallow: /` and the XML sitemap is empty. That is correct. The
+  gate therefore SKIPS `SEO_CANONICAL_MISSING_OR_FOREIGN`, `SEO_HREFLANG_SET_INCOMPLETE`,
+  `SEO_XDEFAULT_MISSING` and `SEO_SITEMAP_ROUTE_MISSING` there and prints why. A skip is not a pass:
+  step 6 checks them on the published deployment. A wrong claim is still reported on the preview —
+  a foreign canonical, a `?lang=` hreflang, a set that is not reciprocated.
+- Fix a RED at the named route before anything else, and never re-promote an unchanged tree hoping
+  it passes: the gate is deterministic.
+
+| Code                               | Severity on a changed route      | What it means after a migration                               | Fix                                                                     |
+| ---------------------------------- | -------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `SEO_HTML_LANG_MISMATCH`           | RED                              | `<html lang>` is a literal or ignores the URL's language      | `<html lang={binding.locale}>` in `src/app/layout.tsx`                  |
+| `SEO_CANONICAL_MISSING_OR_FOREIGN` | RED                              | A hand-written or missing canonical                           | `routeMetadata(...)`; delete the hand-written tag                       |
+| `SEO_HREFLANG_NOT_RECIPROCAL`      | RED                              | Language versions list different alternate sets               | `staticPathsByLocale` or `productPathsByLocale` for `pathsByLocale`     |
+| `SEO_HREFLANG_SET_INCOMPLETE`      | RED on catalog routes, else WARN | The alternate set omits a language the store serves           | Build `pathsByLocale` from `languageCodes`                              |
+| `SEO_HREFLANG_QUERY_PARAM`         | RED                              | An alternate points at `?lang=`                               | The deletion list's `?lang=` class                                      |
+| `SEO_XDEFAULT_MISSING`             | RED on catalog routes, else WARN | Hand-built alternates without `x-default`                     | `routeMetadata(...)`                                                    |
+| `SEO_LOCALE_PREFIX_NOT_REDIRECTED` | RED                              | `/en/…` answers 200: an improvised stage or segment serves it | Delete the improvised stage or `[locale]` segment                       |
+| `SEO_LOCALE_ORPHAN_LINK`           | RED                              | A link leaves its language: a hand-built or bare link remains | `LocaleLink` or `localizedPath`                                         |
+| `SEO_TITLE_MISSING`                | RED                              | A route emits no title                                        | `generateMetadata` returning `routeMetadata({ title })`                 |
+| `SEO_RESERVED_LOCALE_SEGMENT`      | RED                              | A route sits in a two-letter or infrastructure directory      | Move it to a longer name, with a `REDIRECTS` entry                      |
+| `SEO_RENAME_WITHOUT_REDIRECT`      | RED                              | A moved or removed route has no redirect                      | A `REDIRECTS` entry                                                     |
+| `SEO_NOINDEX_MISSING`              | RED                              | A session, funnel or query-state page is indexable            | `contentIndexable: false`; delete a second noindex mechanism            |
+| `SEO_FORBIDDEN_JSONLD`             | RED                              | Hand-built or forbidden structured data                       | `json-ld.ts` builders only                                              |
+| `SEO_SITEMAP_INVALID`              | RED                              | An improvised emitter answers `/sitemap.xml`, or it fails     | Delete the emitter; merge `src/lib/forgecart.ts`                        |
+| `SEO_SITEMAP_ROUTE_MISSING`        | RED                              | An indexable route has no XML sitemap row                     | A `src/seo/routes.d/<page>.json` fragment                               |
+| `SEO_ROUTE_UNREACHABLE`            | RED                              | A changed route does not answer 200                           | `TailServerLogs`: usually an import of a deleted file or missing export |
+| `SEO_DUPLICATE_LOCALE_HEADER`      | RED                              | Two `Content-Language` values on one response                 | Delete the duplicate emitter                                            |
+| `SEO_SCHEMA_BLOGPOSTING_INVALID`   | RED                              | A blog post's node is missing, doubled or unreadable          | One `blogPostingJsonLd(...)` node                                       |
+| `SEO_H1_MISSING`                   | WARN                             | No `<h1>`                                                     | Exactly one `<h1>`                                                      |
+| `SEO_H1_DUPLICATE`                 | WARN                             | More than one `<h1>`                                          | Exactly one `<h1>`                                                      |
+| `SEO_IMG_ALT_MISSING`              | WARN                             | An image has no alt text                                      | The alt-text backfill                                                   |
+| `SEO_UNMAPPED_PAGE_KIND`           | WARN                             | A page-kind route renders no description of its own           | The route-level SEO source mapping                                      |
+
+### 3. Route probes
+
+`ProbeRoute` requests one route on the storefront's server without following redirects and reports
+the status and the start of the body. Probe:
+
+| Route                                                | Expected                                                 |
+| ---------------------------------------------------- | -------------------------------------------------------- |
+| `/`                                                  | 200; the `<html` tag carries `lang="en"`                 |
+| `/de`                                                | 200; `lang="de"`                                         |
+| `/de/products`                                       | 200; `lang="de"`                                         |
+| `/en/products`                                       | 308 — the default language is never prefixed             |
+| `/zz/products`, with `zz` not offered                | 404                                                      |
+| `/products?lang=de`                                  | 200; `lang="en"` — a query parameter selects no language |
+| Every `from` path in `REDIRECTS`, and its `/de` form | 308                                                      |
+| `/sitemap.xml`                                       | 200; empty on the preview                                |
+| `/robots.txt`                                        | 200; `Disallow: /` on the preview                        |
+
+`ProbeRoute` does not report headers. `Content-Language` is covered twice: in the source by sweep
+row S19, whose only match is `src/middleware.ts`, and on the wire by the promote gate
+(`SEO_DUPLICATE_LOCALE_HEADER`). The expected wire state: exactly one `Content-Language: de` on
+`/de` and every `/de/…` page, and none on an unprefixed page.
+
+### 4. The per-locale browser round
+
+After the promote — the preview serves the promoted tree — `browser_navigate` to every language's
+URL of every route the migration touched: the default language unprefixed, every other language
+under its prefix. For each one, `browser_snapshot` and confirm:
+
+- the page shows that language's own copy, not the default language's;
+- `html lang` equals that language;
+- the language switcher's target is the same page in the other language;
+- every internal link stays in the language: `/de/…` on a German page, unprefixed on a
+  default-language page.
+
+### 5. The refresh settles
+
+After the last promote, call the refresh operation once more with an empty `adopt` list. Without
+an `adopt` list it never overwrites a file that differs from the platform version. Expect:
+
+- `rendered` and `adopted` are empty;
+- `conflicts` is exactly your Merged list, plus `src/seo/redirects.ts` when you added redirects;
+- every Adopted-as-is file and `SEO-MIGRATION.md` are in `upToDate`.
+
+A file in `conflicts` that is not on your Merged list was never merged: merge it.
+
+### 6. Publish, then check the published deployment
+
+Ask the operator to publish the storefront; an agent cannot deploy. On the published deployment:
+
+- `robots.txt` names `Sitemap: <origin>/sitemap.xml` and disallows the noindex paths;
+- `/sitemap.xml` lists every indexable route in every language;
+- every indexable page carries an absolute canonical and a complete hreflang set with `x-default`;
+- every page serves the search-console verification `<meta>` tags. Until the published deployment
+  serves them, the platform records `SEO_VERIFICATION_PLACEMENT_NOT_SERVED` for the connected
+  search console. That is expected and is not a failed verification (`SITE_NOT_VERIFIED`); it
+  clears on the platform's next sync after the publish.
+
+### How the platform tests this document
+
+The `retrofit` phase, the last phase of the platform's storefront crawler harness
+(`tool/storefront-verify`), follows this document on a storefront built by the real CLI. It turns
+that storefront into an improvised pre-SEO one: ten defects drawn from the deletion list, and no
+`.forgecart/template-manifest.json`, like a provisioned storefront. It runs the refresh with no
+`adopt` list. It then applies a DONE summary in the form of the last section, in this document's
+order: the deletions; one adopting refresh of the merged and adopted files, before any edit to
+them; the re-applied customizations; a rename moved into `src/seo/redirects.ts`; a merchant page
+migrated in place and joined by a `src/seo/routes.d/<page>.json` fragment; the final refresh. Its
+49 assertions run in three stages:
+
+- `migrated` (5) reads the tree and the three refresh reports. The first refresh renders this
+  document and passes the applicability test above. The deletion list names every class the
+  storefront carried (`retrofit-the-document-names-every-deletion-class`). No improvisation
+  survives beside its replacement. The final refresh settles exactly as step 5 expects
+  (`retrofit-the-final-refresh-is-settled`).
+- `served` (43) serves the migrated storefront with one `next dev` boot. There is one
+  `Content-Language` emitter, the migrated page stays in its language, `?lang=` selects nothing,
+  the moved rename answers 308 in every language, and the XML sitemap lists the migrated page with
+  the hreflang set the page emits. Every re-applied customization still acts, and the crawler's 37
+  locale and SEO assertions pass again, each as `retrofit:<id>`.
+- `restored` (1) proves that the harness's workspace is back byte for byte, whether the phase
+  passed or failed (`retrofit-the-workspace-is-restored-byte-for-byte`).
+
+It is a platform test: your workspace does not contain it, and nothing here asks you to run it.
+
+## The DONE summary lists the deleted files
+
+Report the migration in exactly this form:
+
+```text
+SEO migration — DONE
+Deleted:
+- <every removed path, one per line>
+Merged (platform version taken, customizations re-applied):
+- <path> — <the customizations re-applied>
+Adopted as-is:
+- <path>
+Redirects added to src/seo/redirects.ts:
+- /old-path → /new-path
+Routes joined the XML sitemap:
+- src/seo/routes.d/<page>.json — /<page>, indexable: true|false
+Remaining WARNs:
+- <CODE> at <url> — <why it remains>
+```
+
+- The summary lists every deleted file: `Deleted:` names every path the migration removed, and
+  nothing else. `src/middleware.ts` and every other platform file belong under Merged or Adopted
+  as-is, never under `Deleted:`.
+- A summary whose `Deleted:` list is empty has replaced nothing: either the sweep found no
+  improvised code — then say so and quote it — or the migration is not done.
+- Write "none" under a heading that has no entries. Never leave a heading out.