@rovela-ai/sdk 0.19.4 → 0.19.5

package/docs/changelog/README.md

@@ -0,0 +1,53 @@
+# Rovela SDK Changelog — written for agents
+
+This directory is the knowledge base of the **store update system**. Its
+readers are (1) Claude Code inside a store sandbox executing an SDK update,
+and (2) the Rovela platform composing update prompts. It is NOT a
+marketing changelog — every line exists to make an update decision correct.
+
+## How it is used
+
+When a store updates from SDK vA to vB, the update prompt embeds every
+epoch entry whose range overlaps (vA, vB]. Claude Code then:
+1. **Audits** the store: diffs its template-contract files against the
+   stock reference (`node_modules/@rovela-ai/sdk/templates/store-template/`)
+   and greps its custom code for each entry's hazards.
+2. **Plans** a store-specific migration (impact-classified).
+3. **Prepares** the store at the old SDK (both-version-compatible edits,
+   new files, DB pre-heals) — no build gate during this stage.
+4. **Bumps** the pin, installs, then drives `get_errors` + `npm run build`
+   to green and walks each entry's verification checklist.
+
+## Entry schema (every epoch/release file follows it)
+
+```
+# EN <name> — <first version>..<last version>
+## What landed            — one paragraph, merchant-meaningful
+## SDK-internal (free)    — improvements a pin bump delivers with zero file changes
+## Template contract      — files whose SHAPE moved; per file: the semantic
+                            intent + what the stock shape provides. Apply by
+                            INTENT, adapted to the store's customizations —
+                            never by blind overwrite.
+## Behavior contracts     — semantics that changed under existing APIs. THE
+                            dangerous category for customized stores.
+## Custom-code hazards    — concrete greps to run against the STORE'S OWN
+                            code, with the fix for each hit.
+## DB                     — schema additions; whether each self-heals at
+                            runtime (ensure*) or should be pre-applied.
+## New surfaces           — admin routes/pages that exist in the stock
+                            template but not in older stores; adopt them
+                            through THIS store's structure (its dashboard
+                            layout, its navItems), never by assuming stock.
+## Verify                 — the post-update checklist for this epoch.
+```
+
+## Authoring rules
+
+- Dense, imperative, grep-anchored. No prose padding.
+- Every hazard names the grep AND the fix.
+- **Release ritual**: any SDK release that changes a template-contract file
+  or a behavior contract MUST add its entry here in the same change
+  (enforced by `scripts/check-prompts.sh` platform-side).
+- Epoch files consolidate the pre-0.19.4 history; per-release files
+  (`v0.19.5.md`, …) accumulate going forward and get consolidated into a
+  new epoch when a range stabilizes.

package/docs/changelog/epoch-01-chrome-consent.md

@@ -0,0 +1,63 @@
+# E1 Chrome & consent — 0.1.0..0.5.0
+
+## What landed
+The store foundations: catalog/cart/checkout/admin baseline, zone-based tax,
+returns/refunds, the 4-role admin user management with the two-cookie auth
+split, cookie consent (EDPB), product videos, the reworked product list +
+dashboard metrics + setup guide, and the (since-retired) storefront admin
+bar.
+
+## SDK-internal (free via pin bump)
+Everything the store thin-mounts: admin pages, checkout, cart, auth forms.
+Later SDKs keep this entire era's imports working (AdminGuard, AdminLayout,
+CartProvider, CartDrawer, StoreSettingsProvider, SignIn/SignUpForm…) with
+ONE exception below.
+
+## Template contract
+- `app/LayoutContent.tsx` — stores generated between SDK 0.3.13 and ~0.4.3
+  carry `import { AdminBarBanner } from '@rovela-ai/sdk/admin'` and mount
+  `<AdminBarBanner />` in the customer branch. **That export no longer
+  exists** (retired 2026-05-24). The store's provider tree may have been
+  customized — find the import + JSX wherever they live and REMOVE both
+  (the banner's job is covered by platform-side navigation now). This is
+  the ONLY hard compile break in the SDK's history.
+- `app/layout.tsx` reads `findSettings()` for `cookieBannerEnabled`
+  (0.3.19+); stores older than that predate the cookie banner mount — the
+  changelog entries of LATER epochs describe the current LayoutContent
+  shape if you are adopting new providers.
+
+## Behavior contracts
+- Two-cookie auth split (0.3.20): admin and customer sessions are separate
+  configs, separate cookies, separate endpoints (`/api/admin-auth/…` vs
+  `/api/auth/…`). Custom code assuming one unified session breaks — check
+  for direct NextAuth cookie reads.
+- Discounts/tax in this era are the LEGACY Stripe-coupon surfaces. They
+  keep working after an update, but the native discounts engine (E2)
+  supersedes them as the merchant surface.
+
+## Custom-code hazards (greps)
+- `grep -rn "AdminBarBanner" app/ components/` — remove import + JSX
+  wherever found (see Template contract). MUST be done for the build to
+  pass after the bump.
+- `grep -rn "AdminHeader" app/ components/` — removed at 0.3.15; extremely
+  rare, replace with the current AdminLayout chrome if found.
+- `grep -rn "next-auth" app/ components/ lib/ --include=*.tsx --include=*.ts | grep -v "@rovela"` —
+  custom direct NextAuth usage should go through the SDK's `useAuth` /
+  `useAdminSession`.
+
+## DB
+`store_settings` (+ `cookie_banner_enabled`), admin user-management tables,
+return/refund columns, tax zones — all present from this era or self-healed
+by later SDKs' `ensure*` functions at their chokepoints. Nothing to
+pre-apply manually.
+
+## New surfaces
+This era already has: /admin products, customers, discounts (legacy
+Stripe), tax, users, account, auth pages. Later epochs ADD analytics,
+locations, files, emails — see their entries.
+
+## Verify
+- Build passes with zero references to `AdminBarBanner`.
+- Admin login works (two-cookie: signing into /admin does not affect a
+  customer session in the same browser).
+- Storefront renders with the cookie banner if enabled in settings.

package/docs/changelog/epoch-02-platform-commerce.md

@@ -0,0 +1,108 @@
+# E2 Storefront platform & commerce core — 0.5.2..0.9.2
+
+## What landed
+First-party storefront analytics, path-bar sync, the storefront SEO/GEO
+overhaul (canonical-host redirect, JSON-LD, per-store llms.txt), zone-native
+free shipping — and the ENTIRE commerce core: server-priced checkout
+(`buildQuote`), manual payment methods, the native discounts engine,
+customer accounts/addresses/groups, click & collect, and group-gated
+visibility.
+
+## SDK-internal (free via pin bump)
+The analytics module (`AnalyticsProvider`, admin Dashboards/Events/Visitors
+views), the whole checkout pricing core, payment-methods/discounts/groups/
+locations managers, address book, `OrderTimeline`, bulk-selection
+primitives. All mounted from the SDK — a pin bump delivers the machinery;
+the NEW SURFACES below make it reachable.
+
+## Template contract
+- `app/LayoutContent.tsx` — INTENT: the customer branch mounts
+  `<AnalyticsProvider>` (from `@rovela-ai/sdk/analytics`) INSIDE
+  `CookieConsentProvider` (consent-gated ingestion), wrapping
+  `<CartProvider>`. Also mounts `<PathSyncBridge />` (a small local client
+  component posting `rovela:navigation` to the platform iframe parent —
+  copy from the stock reference or create per its ~30-line contract).
+- `proxy.ts` — CREATED in this epoch: canonical-host 308 redirect
+  (collapses `*.rovela.app`/`*.vercel.app` onto a verified custom domain;
+  inert without one). If the store has NO proxy.ts, add the stock one.
+- `next.config.js` — adds a headers() rule serving `/llms.txt` as
+  markdown + noindex. Additive.
+- `app/layout.tsx` — enriched Organization/WebSite JSON-LD. Additive;
+  adopt only if the store's layout is stock-shaped or the merchant wants
+  the SEO surfaces.
+
+## Behavior contracts
+1. **Checkout is server-priced (`buildQuote` is the ONLY money source).**
+   Client-submitted amounts/customerId/groupId are ignored or rejected
+   (`PricingError` → 4xx). Custom checkout code that POSTs its own totals
+   or passes `customerId` in the body must be reworked to let the server
+   price (catalog price + discounts + shipping + tax) and to rely on the
+   session for identity.
+2. **Native discounts replace Stripe coupons as the merchant surface.**
+   Legacy Stripe-coupon helpers still exist (feature-card usage) but the
+   admin Discounts manager + `/api/checkout/discount` are the system now.
+3. **`orders.payment_provider`** (default 'stripe') exists — custom order
+   readers must not assume every order is a Stripe order (manual methods
+   create `pending` orders with `manual_*` idempotency keys).
+4. **Free shipping is a PER-ZONE rate** (0.5.5). The global
+   `free_shipping_threshold` column is dormant/display-only — checkout no
+   longer injects a synthetic free-shipping line from it.
+5. Analytics ingestion is CONSENT-GATED — do not mount AnalyticsProvider
+   outside CookieConsentProvider.
+
+## Custom-code hazards (greps)
+- `grep -rn "free_shipping_threshold\|freeShippingThreshold" app/ components/ lib/` —
+  any custom logic treating it as checkout-enforced must be re-pointed at
+  per-zone rates (a zero-price rate with min_order_amount).
+- `grep -rn "customerId" app/checkout app/api/checkout components/checkout 2>/dev/null` —
+  custom checkout paths passing client identity must drop it (server
+  resolves via session).
+- `grep -rn "createCheckoutSession\|/api/checkout" app/ components/ | grep -v node_modules` —
+  verify custom callers send items + selections only, never totals.
+- `grep -rn "status === 'paid'\|paymentIntent" app/ components/ lib/` —
+  order readers should tolerate `payment_provider !== 'stripe'` and
+  `pending` manual orders.
+
+## DB (ALL self-heal — pre-applying the idempotent ALTERs is optional)
+`analytics_events` (ensureAnalyticsTable) · `customer_addresses` +
+`customers.phone/updated_at` (ensureCustomerAddressSchema) ·
+`customer_groups` + `customers.group_id` (ensureCustomerGroupsSchema, wired
+into every customer read incl. login) · `payment_methods` +
+`orders.payment_provider/payment_method_*` (ensurePaymentMethodsSchema) ·
+`discounts` + `discount_redemptions` (ensureDiscountsSchema) ·
+`store_locations` + `orders.pickup_location_id` (ensureStoreLocationsSchema)
+· `visible_to_groups` on payment_methods/shipping_rates/tax_zones
+(ensureVisibilityColumns) · `store_settings.store_country`,
+`orders.currency` snapshot.
+
+## New surfaces (thin mounts to ADD if absent, wired through THIS store's
+dashboard layout + navItems — never assume stock structure)
+- `/admin/analytics` (+ `/events`, `/visitors`, shared layout) and
+  `/api/admin/analytics/*` + `/api/analytics/track`
+- `/admin/locations` + `/api/admin/locations/*` + `/api/checkout/pickup-locations`
+- `/api/account/addresses*`, `/api/admin/customers/[id]/addresses*`
+- `/api/admin/customer-groups*`, `/api/admin/payment-methods*`,
+  `/api/admin/discounts*`, `/api/checkout/{manual,payment-methods,discount}`
+- `/api/admin/{customers,orders,products}/bulk`
+(Each is a 1–15 line re-export of SDK handlers — see the stock reference.)
+
+## Existing components that gained dependencies (silent-degradation risk)
+An SDK component the store ALREADY mounts now calls a NEW route — if that
+route is missing the component renders but silently does nothing. These are
+NOT "new surfaces" (the page already exists); they're new wiring under a page
+you must not miss:
+- `<PaymentSettings>` (admin payments page) now reads/writes
+  `/api/admin/payment-methods*` — without it the manual-methods manager loads
+  empty and saves fail.
+- `<CheckoutFlow>` (storefront checkout) now calls
+  `/api/checkout/{manual,payment-methods,discount}` — without them the payment
+  step shows no manual methods and discount codes never validate.
+
+## Verify
+- `/admin/analytics` renders its three tabs; a storefront visit with
+  consent accepted records an event.
+- Checkout end-to-end: a cart prices server-side; a discount code
+  previews; the payment step shows Stripe (+ any manual methods).
+- `/admin/locations` loads; storefront picks up pickup only when a
+  pickup-enabled location exists.
+- Custom domain stores: apex/vercel hosts 308 to the canonical domain.

package/docs/changelog/epoch-03-i18n-files.md

@@ -0,0 +1,72 @@
+# E3 Languages & files — 0.10.0..0.13.1
+
+## What landed
+Native multilingual storefronts (§61): path-prefix locale routing
+(`/en/...`), key-symmetric UI catalogs, per-locale catalog content
+overlays, hreflang alternates, the admin Languages toggle — plus the admin
+files library (§60).
+
+## SDK-internal (free via pin bump)
+The whole `core/i18n` module (`useT`/`getT`, `LocaleLink`/`useLocalePath`,
+`LanguageSwitcher`, catalog overlay `localizeCatalogRow`), the
+`@rovela-ai/sdk/locales` edge-safe subpath, `FilesManager` +
+`MediaLibraryPicker`, the Settings → Languages control. A store that skips
+the template migration stays single-language and loses nothing.
+
+## Template contract (the i18n adoption — the ONE structural migration)
+Adopting multilingual requires reshaping three files BY INTENT:
+- `proxy.ts` — parse a leading locale prefix (`/en|/fr…` from
+  `SUPPORTED_LOCALES` in `@rovela-ai/sdk/locales`), rewrite to the bare
+  path, and set `x-rovela-locale` / `x-rovela-geo-locale` /
+  `x-rovela-pathname` headers. `/api` and `/admin` are NEVER localized.
+  Keep the store's existing canonical-host logic intact.
+- `app/layout.tsx` — resolve the request locale server-side
+  (`resolveStoreLocaleConfig`, `resolveRequestLocale`,
+  `resolveLocaleRedirect` from `@rovela-ai/sdk/core`; `localizedAlternates`
+  from `core/server`): 308 `permanentRedirect` for structural strips
+  (disabled/unknown/default-locale prefixes), temporary redirect for
+  preference hops; thread `locale`/`defaultLocale`/`enabledLocales` down.
+- `app/LayoutContent.tsx` — accept those props and wrap the WHOLE tree in
+  `<RovelaLocaleProvider>` (OUTSIDE CookieConsentProvider). HYDRATION RULE
+  (load-bearing): locale config must come from these server-resolved props,
+  NEVER from a client fetch — a late fetch mis-resolves the default locale
+  at first paint and bounces hard loads of prefixed URLs.
+If this store's layout/LayoutContent are heavily customized, graft the
+locale resolution AROUND the customizations — the provider nesting order
+and the server-threaded props are the contract; everything else is theirs.
+
+## Behavior contracts
+- Internal links in multilingual stores go through `LocaleLink` /
+  `useLocalePath` — a bare `<Link href="/products">` drops the prefix.
+- New user-visible strings on a multilingual store must exist in EVERY
+  enabled locale (store dictionary pattern — CLAUDE.md §5.5).
+- Latent `formatPrice` hazard EXISTS IN THIS ERA'S SDK (integers > 100
+  treated as cents) — it is FIXED in E5; see E5's money contract for the
+  post-update behavior.
+- Menu labels: a translated `section.name` now beats a hand-set
+  `meta.label`.
+
+## Custom-code hazards (greps)
+- On stores adopting i18n: `grep -rn "href=\"/" app/ components/ | grep -v admin | grep -v api` —
+  storefront internal links should migrate to `LocaleLink` (mechanical but
+  wide; scope to nav/header/footer/product cards first).
+- `grep -rn "useSearchParams\|usePathname" components/` — custom routing
+  logic may need the locale-stripped pathname (`x-rovela-pathname`).
+
+## DB (self-heal)
+`products.translations` + `categories.translations`
+(ensureCatalogTranslationsSchema) · `store_settings.default_locale` +
+`enabled_locales` (settings ensure) · `orders.locale` / `customers.locale`.
+
+## New surfaces
+- `/admin/files` + `/api/admin/files` (files library — thin mounts).
+- Languages control lives INSIDE Settings (no new route).
+
+## Verify
+- Single-language store post-update: storefront byte-identical behavior,
+  no locale prefixes anywhere.
+- If multilingual was adopted: `/xx/products` renders translated UI, bare
+  paths serve the default locale, `/admin` and `/api` unaffected,
+  hreflang alternates emitted, hard-load of a prefixed checkout URL does
+  NOT bounce to the bare path.
+- `/admin/files` lists the store's media.

package/docs/changelog/epoch-04-emails.md

@@ -0,0 +1,65 @@
+# E4 Email editor — 0.14.0..0.15.2
+
+## What landed
+The merchant email editor (§62): every transactional email brand-themed
+from the store's blueprint, block-editable per language, testable, plus
+merchant-created custom emails.
+
+## SDK-internal (free via pin bump)
+The entire emails module rebuild: brand-derived shared theme (full Google
+Fonts), block engine + registry, `prepareEmail` overrides at the send
+boundary, FR localizer, `EmailsManager` admin UI. Existing email sends keep
+working untouched — no `store_emails` row means byte-identical shipped
+templates (fail-open by design).
+
+## Template contract
+- `next.config.js` — MUST gain
+  `outputFileTracingIncludes: { '/**': ['./.rovela/blueprint.json'] }`.
+  WHY: the email theme reads the blueprint at runtime through a
+  bundler-invisible loader; without this line, Vercel functions that don't
+  statically import `core/config` ship WITHOUT the blueprint and merchant
+  emails silently render DEFAULT branding (fail-open, no crash — easy to
+  miss). Anchored insert into the existing config object; preserve
+  everything else in the store's next.config.
+- New thin mounts: `app/admin/(dashboard)/emails/page.tsx` +
+  `app/api/admin/emails/{route,preview/route,test/route}.ts` — 1-line
+  re-exports; wire the nav entry through THIS store's `navItems`.
+
+## Behavior contracts
+- The emails module graph must stay free of static node-builtin imports
+  (it is client-reachable via the auth barrel; a static `fs` import fails
+  `next build`). Relevant only if custom code imports from
+  `@rovela-ai/sdk/emails` into client components — don't.
+- Email amounts are decimal STRINGS end-to-end; order numbers pass through
+  `bareOrderNumber()` (templates add their own `#`).
+
+## Custom-code hazards (greps)
+- `grep -rn "from '@rovela-ai/sdk/emails" app/ components/ | grep -v "api/"` —
+  emails imports in client components are a build hazard; move to server.
+- Stores with custom email senders: they keep working; the editor covers
+  registry emails only.
+
+## DB (self-heal)
+`store_emails` table (ensureStoreEmailsSchema) ·
+`store_settings.email_theme` (settings ensure).
+
+## New surfaces
+`/admin/emails` (nav: Sales → Emails) + the three API mounts above.
+
+## Existing components that gained dependencies (silent-degradation risk)
+- Every EXISTING transactional email sender (order confirmation, shipping,
+  admin invites…) now renders through the brand-derived theme, which reads
+  `.rovela/blueprint.json` at runtime. Without the `next.config.js`
+  `outputFileTracingIncludes` line (Template contract above), Vercel
+  functions that don't statically import `core/config` ship WITHOUT the
+  blueprint and emails silently fall back to DEFAULT branding — no error,
+  no crash, just unbranded emails. The store's email code needs zero
+  changes; the config line is the whole dependency.
+
+## Verify
+- `/admin/emails` lists the registry; opening one renders a themed preview
+  (store colors/fonts, not default green).
+- Send test delivers to the signed-in admin.
+- AFTER PUBLISH (Vercel only): trigger any transactional email and confirm
+  it renders with the store's branding — this is the
+  outputFileTracingIncludes check; the sandbox can't prove it.

package/docs/changelog/epoch-05-admin-experience.md

@@ -0,0 +1,98 @@
+# E5 Admin experience — 0.15.3..0.18.7
+
+## What landed
+The complete admin redesign ("LEDGER"): Shopify-style chrome (identity top
+bar + nav-only sidebar), the branding architecture (R2-truth logo/favicon),
+the save-bar and toast grammars, the auth-shell front door, the settings
+correctness wave (timezone, store identity, currency, cookie-consent
+configurator), and the consolidation kit (one modal, one empty state, one
+search input, one pagination, one switch, one status badge).
+
+## SDK-internal (free via pin bump)
+Everything above ships through SDK components stores already mount:
+`AdminLayout`/`AdminNav`/`AdminTopBar` chrome, `AdminPageHeader`,
+`AdminSaveBar`+`useDirtyState`, `adminToast`+`AdminToaster` (mounted by
+AdminLayout), `AdminModal`/`DeleteConfirmDialog`/`DiscardChangesModal`,
+`AdminEmptyState`/`AdminSearchInput`/`AdminPagination`/`AdminSwitch`/
+`OrderStatusBadge`, `AdminAuthShell`, `BrandingAssetUpload` (logo+favicon),
+`CookieBannerConfigurator`, the rebuilt Products/Orders/Customers tables,
+dashboard metrics, `useAdminDates`. Old inline patterns keep compiling
+(`AdminToast` component, `LogoUpload` remain exported for back-compat) —
+they are DEPRECATED in favor of the kit but never break.
+
+## Template contract
+- `app/admin/layout.tsx` — INTENT: the admin segment loads Plus Jakarta
+  Sans via `next/font` exposing `--admin-font-jakarta`, and declares
+  `export const viewport` (device-width) + `export const dynamic =
+  'force-dynamic'` (admin is session-gated, never static; also silences a
+  benign per-page "Failed to read session" build-log block). Old stores
+  missing these exports still build — add them; they are additive.
+- Admin auth pages (`app/admin/{login,forgot-password,reset-password,
+  accept-invite}/page.tsx`) — INTENT: thin mounts on the SDK's
+  `AdminAuthShell`-based forms. EXCEPTION: the login page's LoginForm/
+  SetupForm are deliberately INLINED in the template (platform postMessage
+  auto-login contract) — if this store's login page is the old inline
+  version it keeps working; update its JSX chrome only if adopting the new
+  look, and NEVER replace the inline forms with SDK imports.
+- Branding: logo/favicon live at fixed R2 keys and mirror into
+  `store_settings.logo_url` / `favicon_url`; storefront + admin read
+  settings-first with env fallback.
+
+## Behavior contracts (READ CAREFULLY — the dangerous ones)
+1. **MONEY (0.18.1)**: `formatPrice` (emails + core) DROPPED the
+   integer-cents heuristic ("whole number > 100 means cents, divide by
+   100"). Money is DECIMAL CURRENCY UNITS end-to-end (`29.99`), cents only
+   at the Stripe API boundary. A store whose custom code passes CENTS to
+   SDK formatters displayed correctly before and will display 100× after.
+2. **TIMEZONE (0.18.0)**: date rendering falls back to UTC (never
+   America/New_York); admin dates go through `useAdminDates` /
+   `formatDayLabel` in the STORE timezone; day-bucket queries use the store
+   timezone server-side.
+3. **Settings-first identity (0.17.0+)**: storeName/email/logo/favicon/
+   currency read LIVE from `store_settings` (`useStoreSettings` /
+   `findSettings`); `NEXT_PUBLIC_*` env is a build-time fallback only.
+4. **`orders.currency` snapshot**: order displays use the order's own
+   currency, not the store's current one.
+5. **Notification grammar**: events → `adminToast`; states → inline
+   `admin-alert`; document saves → the save bar morph (never a success
+   toast alongside it). Native `confirm()`/`alert()` are banned in admin.
+
+## Custom-code hazards (greps against THIS store's code)
+- `grep -rn "formatPrice" app/ components/ lib/` — for each call site,
+  verify the value passed is decimal units. If the store stores/computes
+  cents anywhere outside a Stripe call, convert at the source (÷100 once,
+  where the cents enter) — do NOT reintroduce a display heuristic.
+- `grep -rn "toLocaleString\|toLocaleDateString\|Intl.DateTimeFormat" app/admin components/` —
+  admin-facing dates hardcoding a locale/timezone should move to
+  `useAdminDates`.
+- `grep -rn "NEXT_PUBLIC_STORE_LOGO_URL\|NEXT_PUBLIC_STORE_NAME" app/ components/` —
+  fine as fallbacks; if used as the ONLY source in custom components,
+  prefer `useStoreSettings()`.
+- `grep -rn "<AdminToast\b" app/ components/` — old component still works;
+  when touching those files anyway, migrate outcomes to `adminToast`.
+- Custom admin pages built by feature cards in this store: they keep
+  working, but any YOU touch during this update must follow CLAUDE.md §7.6
+  (kit components, admin tokens, no Loader2/Sparkles).
+
+## DB
+`store_settings` gains `store_country`, `favicon_url`, `email_theme`,
+`cookie_consent` (+ locale columns from E4). ALL self-heal via
+`ensureStoreSettingsSchema` at the settings chokepoints — you MAY pre-run
+`ALTER TABLE store_settings ADD COLUMN IF NOT EXISTS …` for each (idempotent)
+so the first post-update request is clean, but it is not required.
+
+## New surfaces
+None route-level in this epoch (chrome replaced in place). The auth pages'
+new look ships via SDK; only adopt template-side JSX if the store's pages
+are stock-shaped.
+
+## Verify
+- Admin loads with the top bar + nav-only sidebar; store name and logo tile
+  render (skeletons while loading, never "Admin"/"A" placeholders).
+- Open a product with a known price: displays the SAME amount as before
+  the update (the money-contract check — if it shows 100×, a custom call
+  site is passing cents).
+- Order detail: dates in store timezone; totals in the order's currency.
+- Settings page: edit a field → save bar rises; Save → morph; no double
+  toast.
+- Login page still auto-logs-in from the platform (if you touched it).

package/docs/changelog/epoch-06-mobile-integrity.md

@@ -0,0 +1,72 @@
+# E6 Mobile + integrity — 0.19.0..0.19.4
+
+## What landed
+The save-grammar completion across every admin manager, full mobile
+responsiveness for the admin, the analytics views' migration onto admin
+tokens, catalog schema self-heals that ended the fresh-store outage class,
+and build-log hygiene.
+
+## SDK-internal (free via pin bump)
+- Save bar everywhere it belongs (0.19.0): Discounts/Locations editors,
+  CustomerDetails edit, account profile, EmailsManager (per-locale drafts,
+  theme) — with `DiscardChangesModal` back-guards. ProductForm/CategoryForm
+  fixed: no phantom "Unsaved changes" on open (dirty baseline captured only
+  after the fetch), translations echoed so saves can't wipe them.
+- Mobile (0.19.1): sidebar becomes an overlay drawer under 767px, modals
+  become bottom sheets under 640px, `admin-col-optional` columns hide under
+  480px, `pointer: coarse` touch sizing, shared `scroll-lock`.
+- Analytics views on admin tokens with stacked CompactTable rows (0.19.2);
+  Recent Orders is a stacked two-line list; Low Stock pairs 6 rows (0.19.3).
+- Catalog ensures (0.19.2): `products.metafields` + `translations` and
+  `store_settings.public_metafield_keys` self-heal at read chokepoints —
+  older branches converge on first query.
+- Session helpers rethrow Next's static-prerender bailout (0.19.4) instead
+  of logging it as a failure.
+
+## Template contract
+- `app/admin/layout.tsx` — adds `export const dynamic = 'force-dynamic'`
+  (0.19.4) on top of E5's viewport/font. Additive; removes ~21 benign
+  "Failed to read session" blocks per build.
+- `app/admin/(dashboard)/users/[id]/page.tsx` — the details grid became
+  `grid grid-cols-1 sm:grid-cols-2` (mobile). Apply the responsive prefix
+  if the store's copy is stock-shaped.
+- `app/products/page.tsx` — one message per state: on `error`, render ONLY
+  the error banner and SKIP `<ProductGrid>` (its built-in empty state
+  doubled the message); when empty, pass the page's copy via the grid's
+  `emptyState` prop and delete the standalone empty block. This page is
+  often customized — apply the INTENT (mutually exclusive error/empty
+  branches), not the stock markup. If the store's version already branches
+  exclusively, leave it.
+
+## Behavior contracts
+- A `<table>` never sits bare in a card: 2–4 column cards use stacked row
+  lists; dense tables get `overflow-x-auto` wrappers + `admin-col-optional`.
+  Applies to any custom admin page you touch.
+- Custom admin pages must hold at 375px (CLAUDE.md §7.6 mobile rules).
+
+## Custom-code hazards
+- `grep -rn "text-muted-foreground\|bg-card\|border-border" app/admin/` —
+  storefront tokens inside custom admin pages render against the merchant
+  theme and now visibly clash with the admin system; migrate hits you touch
+  to `hsl(var(--admin-*))` / `admin-*` classes.
+- `grep -rn "body.style.overflow" app/ components/` — custom overlays must
+  not lock scroll directly; use the SDK's shared lock (AdminModal has it
+  built in).
+- Custom pages with `<table>` in small cards: check them at 375px.
+
+## DB
+Nothing new; 0.19.2's ensures ADD `metafields`/`translations`/
+`public_metafield_keys` on older branches automatically. Pre-running the
+idempotent ALTERs is optional.
+
+## New surfaces
+None.
+
+## Verify
+- Resize the admin to 375px: drawer opens from the hamburger, closes on
+  scrim/Escape; a delete dialog docks as a bottom sheet; Products table
+  scrolls itself (page never scrolls horizontally); Recent Orders shows
+  stacked rows.
+- Storefront `/products`: exactly ONE message in the error state and ONE
+  when no products match.
+- `npm run build` log: zero "Failed to read session" blocks.