@sonordev/site-kit 7.3.0 → 8.0.0

package/docs/MIGRATING-TO-8.md

@@ -0,0 +1,183 @@
+# Moving a site to site-kit 8
+
+site-kit 8 moves commerce into its own package, [`@sonordev/commerce-kit`](https://sonor.dev/commerce-kit), which also carries the new memberships module, and removes the entries for two modules Sonor retired, Engage and the Sanity CMS. Most sites need no changes at all: if yours uses none of these, update site-kit and rebuild. A site's `^7` range never picks up 8, so nothing forces the move before you next touch the site.
+
+## Who's affected
+
+Only sites that do one of these:
+
+- Import from `@sonordev/site-kit/commerce` or `@sonordev/site-kit/commerce/server` (products, services, events, checkout, calendars).
+- Import a commerce type from the root, such as `import type { CommerceOffering } from '@sonordev/site-kit'`.
+- Turn on the opt-in `list_offerings` agent tool by passing `offerings` to `sonorMcpServer`. See [The MCP change](#the-mcp-change).
+- Import one of the entries that were [removed](#what-was-removed): `@sonordev/site-kit/engage`, `/cms`, `/website/cms` (or their `/server` entries), or `ManagedContent`, `getManagedContentData` or `getContentBlock` from `/seo`.
+
+Not sure which you are? Search the site for the old paths, then for root imports:
+
+```bash
+grep -rnE "@sonordev/site-kit/(commerce|memberships|engage|cms|website/cms)" . \
+  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' \
+  --include='*.mjs' --include='*.cjs' --include='*.mts' --include='*.cts' --include='*.mdx' \
+  --exclude-dir=node_modules --exclude-dir=.next
+
+grep -rnE "ManagedContent|getManagedContentData|getContentBlock" . \
+  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' --exclude-dir=node_modules --exclude-dir=.next
+
+grep -rnE "from ['\"]@sonordev/site-kit['\"]" . \
+  --include='*.ts' --include='*.tsx' --exclude-dir=node_modules --exclude-dir=.next
+```
+
+The root entry is types-only (plus `SITE_KIT_VERSION`), so the last search turns up type imports. Look for the commerce types listed under [What moved](#what-moved) and the Engage type names under [What was removed](#what-was-removed). If the first two searches find nothing, none of the root imports are those types, and you don't pass `offerings` to `sonorMcpServer`, you're done: raise site-kit to `^8` whenever you like.
+
+## Steps
+
+### 1. Install both packages
+
+```bash
+pnpm add @sonordev/site-kit@^8 @sonordev/commerce-kit
+```
+
+`npm install @sonordev/site-kit@^8 @sonordev/commerce-kit` does the same. commerce-kit lists site-kit 8 or newer as a peer dependency, so it uses your site's one copy of site-kit. If your package manager reports that commerce-kit needs `@sonordev/site-kit >=8.0.0` (npm stops with an `ERESOLVE` error, pnpm and Yarn warn), site-kit is still on 7. Like site-kit, commerce-kit needs React 19. Next 16 is an optional peer: only the memberships server helpers use it.
+
+### 2. Run the codemod
+
+Dry run first:
+
+```bash
+npx sonor-setup codemod --only site-kit-8
+```
+
+It prints what it would change and writes nothing. When the diff looks right, apply it:
+
+```bash
+npx sonor-setup codemod --only site-kit-8 --write
+```
+
+The codemod needs sonor-setup 7.3.0 or later, and `npx` fetches the latest. It reads source files anywhere in the project (`pages/`, `hooks/` and `scripts/` count, not just `app/` and `src/`), but not `node_modules`, build output or `public/`. It rewrites your imports (the table below). When your code imports commerce, it also adds `@sonordev/commerce-kit` to package.json and raises site-kit's range to `^8.0.0`, and if `pnpm-workspace.yaml` lists site-kit under `minimumReleaseAgeExclude` it adds commerce-kit there too. Anything it can't rewrite safely it flags, with the fix, so you can finish those by hand: a `require()` of an old path (commerce-kit is ESM only, so that call needs an `import`), an import of a [removed](#what-was-removed) entry, or a `sonorMcpServer` whose `offerings` has no reader (see [The MCP change](#the-mcp-change)). Run it in the app's folder: in a monorepo, once per app that imports commerce, because it stops at a workspace root.
+
+`--check` is the gate: it exits 1 while a file needs rewriting and while a manual follow-up remains, so exit 0 means there's nothing left for you to do.
+
+If it changed package.json, install before you build:
+
+```bash
+pnpm install
+```
+
+No codemod handy? The swap is mechanical: replace the package name in each import and add commerce-kit to package.json. The subpath stays the same.
+
+### 3. Build
+
+```bash
+pnpm build
+```
+
+A build is the real test. Nothing is left behind at the old paths, so an import you missed fails with "Module not found" instead of quietly running something stale. A bump you didn't build is a guess.
+
+## What moved
+
+The subpath stays the same; only the package name changes.
+
+| Was | Now |
+|---|---|
+| `@sonordev/site-kit/commerce` | `@sonordev/commerce-kit/commerce` |
+| `@sonordev/site-kit/commerce/server` | `@sonordev/commerce-kit/commerce/server` |
+| `@sonordev/site-kit/memberships` | `@sonordev/commerce-kit/memberships` |
+| `@sonordev/site-kit/memberships/server` | `@sonordev/commerce-kit/memberships/server` |
+| Commerce types from the root, `@sonordev/site-kit` | `@sonordev/commerce-kit` |
+
+Memberships never shipped in a site-kit release, so those two rows only matter if you tried an unreleased build. The root types are `CommerceOffering`, `CommerceCategory`, `CommerceVariant`, `CommerceSchedule`, `OfferingType`, `Cart`, `CartItem`, `EventCheckoutProps` and `CheckoutLineItem`.
+
+```tsx
+// before
+import { OfferingCard, ProductPage } from '@sonordev/site-kit/commerce'
+import { getOfferingBySlug } from '@sonordev/site-kit/commerce/server'
+import type { CommerceOffering } from '@sonordev/site-kit'
+
+// after
+import { OfferingCard, ProductPage } from '@sonordev/commerce-kit/commerce'
+import { getOfferingBySlug } from '@sonordev/commerce-kit/commerce/server'
+import type { CommerceOffering } from '@sonordev/commerce-kit'
+```
+
+The new entries export what the old ones did, under the same names. `/commerce` is a client entry and `/commerce/server` is server code, the same split as before. commerce-kit's root is types-only, so import anything that runs from one of its module entries.
+
+What stays where it was:
+
+- **Your CSS.** The components keep their `site-kit-` class names (`site-kit-product-grid`, `site-kit-calendar-event` and the rest), so your styles still apply. Brand tokens still come from site-kit's `brand.css`, which your site imports as before.
+- **Your credential.** commerce-kit uses the credential `SiteKitLayout` already publishes, so there's no new environment variable.
+
+What's different besides the import path, all in [commerce-kit's changelog](https://sonor.dev/commerce-kit/changelog):
+
+- The shopping events (`product_view`, `add_to_cart`, `begin_checkout`, `checkout_start` and `purchase`) reach Sonor. site-kit 7 reported them through a hook that returns nothing under `SiteKitLayout`, so they were never sent.
+- The server helpers return whole offerings (gallery, size chart and options included), and they're server-only now. Each response is cached for 60 seconds under the `commerce` tag, which Sonor expires when you edit an offering, and a request gives up after 30 seconds. Pass `{ revalidate: 0 }` in the config if a page needs every request fresh.
+- A product marked sold out in Sonor keeps its page, shown as unavailable, instead of answering "no such product".
+- Checkout works in a browser set to block site data.
+- When a server fetch fails, the log line starts with `[commerce-kit]` instead of `[site-kit/commerce]`. If you filter or alert on that prefix, update it.
+
+## What was removed
+
+These modules were retired in Sonor, and their entries were kept through 7.x so old imports kept building. They're gone in 8, and nothing replaces them:
+
+| Removed | Use instead |
+|---|---|
+| `@sonordev/site-kit/engage` | `@sonordev/site-kit/chat` and `@sonordev/site-kit/website/popups`. The 7 codemod (`npx sonor-setup codemod --write`) moves the names that have a home there and flags `EngageWidget`, which `SiteKitLayout` already mounts |
+| `@sonordev/site-kit/cms`, `/cms/server`, `/website/cms`, `/website/cms/server` | Managed copy: `ManagedSlot`, `ManagedRichText`, `ManagedLink` and `ManagedList` from `@sonordev/site-kit/website/slots`. You can uninstall `@portabletext/react` and `@sanity/image-url` |
+| `ManagedContent`, `getManagedContentData`, `getContentBlock` and their types, from `@sonordev/site-kit/seo` | `ManagedRichText` from `@sonordev/site-kit/website/slots` |
+| `EngageElement`, `WidgetConfig`, `EngageConfig` and the other Engage type names, from the root | `SitePopup`, `SitePopupConfig` and the rest of `@sonordev/site-kit/website/popups`. (The `engage` prop on `SiteKitLayout` and its own `EngageConfig` type stay.) |
+
+They rendered nothing in 7.x, so most sites never imported them and have nothing to do. `npx sonor-setup manifest --json` lists them under `removed`.
+
+## The MCP change
+
+`list_offerings` is the opt-in agent tool that lists priced products, services and events. It used to read the commerce fetchers directly. It takes its reader as an option now, so site-kit doesn't depend on commerce-kit:
+
+```ts
+// before (site-kit 7)
+sonorMcpServer({ businessName: 'Example Studio', offerings: { path: '/shop' } })
+
+// after (site-kit 8)
+import { getOfferingsResult } from '@sonordev/commerce-kit/commerce/server'
+
+sonorMcpServer({ businessName: 'Example Studio', offerings: { path: '/shop', read: getOfferingsResult } })
+```
+
+`read` is `getOfferingsResult` from `@sonordev/commerce-kit/commerce/server`. It reports a failed request as "the catalog is unavailable" instead of an empty catalog; the plain `getOfferings` from the same entry also works, but it reads an outage as empty. `path` is still optional and still defaults to `/shop`. The tool, how it ranks a query, and its rule that a price the business keeps private is never shown all stay in site-kit.
+
+If `read` is missing, `sonorMcpServer` throws when the server is built, with a message that says what to pass. A TypeScript site sees the same reminder as a type error. A site that doesn't pass `offerings` changes nothing, and neither does `list_services`: it reads the site's core data, not commerce. See [MCP and agent tools](../src/mcp/README.md).
+
+## Check your work
+
+1. The first two searches from [Who's affected](#whos-affected) come back empty, and none of the root imports the last one finds are commerce or Engage types.
+2. `pnpm build` passes.
+3. `pnpm ls @sonordev/site-kit @sonordev/commerce-kit` (or `npm ls`) shows site-kit 8.x and commerce-kit 1.x.
+4. On a preview deploy or in dev, load a product or events page and start a checkout.
+5. `npx sonor-setup verify` still exits 0.
+
+## Staying on 7.x
+
+Staying on 7 is fine while you plan the move. A `^7` range never picks up 8, and everything in 7.4 keeps working, commerce included. Two things to know: commerce-kit needs site-kit 8, so a site on 7 can't install it, and the memberships module ships only in commerce-kit. If a dependency update raised your range to 8 before you were ready, pin it back with `pnpm add @sonordev/site-kit@^7.4.0`.
+
+## Questions
+
+### Why is commerce a separate package?
+
+It versions and releases on its own. Checkout is the busiest money path on a site, and most sites don't sell anything, so a fix there shouldn't wait for a site-kit release (or the other way round). commerce-kit builds on site-kit and takes its transport, credential, analytics and server data from it instead of carrying copies. The one entry site-kit added for it, [`@sonordev/site-kit/runtime`](../src/runtime/README.md), is public API, and a site doesn't need to import it.
+
+### Does this make my site's JavaScript smaller?
+
+No, and it was never meant to. site-kit's root entry was already types-only and no core entry referenced commerce, so visitors to a site without commerce never downloaded any of it. For a site that does sell, the components are the same code, now built and shipped from commerce-kit. What shrinks is site-kit's package: about 8% fewer bytes to download and about 13% fewer on disk than 7.4.0, which is install size, not page weight.
+
+### Why 8.0, and not a 7.x release with the old paths still working?
+
+Removing a published entry is a breaking change, and a `^7` range would have picked it up on the next install. Keeping the old paths alive would have meant a second copy of the code, or site-kit depending on a package that depends back on it. It wouldn't have saved an edit either, since commerce-kit has to be added to package.json whichever way. (The retired Engage and CMS entries were promised for 8.0 in the 7.0, 7.1 and 7.2 notes, so they go with it.)
+
+### Do my styles, environment variables or API key change?
+
+No. The class names, the brand tokens and the credential are all as they were. See [What moved](#what-moved).
+
+### Did anything else leave site-kit in 8.0?
+
+Only [what was removed](#what-was-removed). Every other entry works as it did in 7.4, including the deprecated aliases for renamed modules (`./middleware`, `./sitemap`, `./robots`, `./redirects`, `./og`, `./llms`, `./images`, `./slots`, `./landing` and `./cta-bar`), because sites still import them. Earlier notes said those would go in 8.0; they stay, and will go in a later major once sites have moved off them. [Migrating to 7](MIGRATING-TO-7.md) lists them, and the codemod (`npx sonor-setup codemod --write`) that moves a site onto their new homes.
+
+### Where are the commerce docs now?
+
+At [sonor.dev/commerce-kit](https://sonor.dev/commerce-kit): [Commerce](https://sonor.dev/commerce-kit/commerce), [Memberships](https://sonor.dev/commerce-kit/memberships) and the [changelog](https://sonor.dev/commerce-kit/changelog).

package/docs.json

@@ -2,13 +2,14 @@
   "$comment": "What sonor.dev renders for this package, in nav order. sonor.dev reads this file from the published tarball (latest on npm), so a release IS the docs deploy: add a page here and ship it in package.json `files`. scripts/verify-docs.cjs fails the publish if a listed file is missing from the pack.",
   "schemaVersion": 1,
   "title": "site-kit",
-  "summary": "One package, one env var, every Sonor module on a Next.js site: SEO, analytics, forms, articles, commerce, chat, AI visibility, agent tools and motion.",
+  "summary": "One package, one env var, the Sonor modules a Next.js site needs: SEO, analytics, forms, articles, booking, chat, AI visibility, agent tools and motion. Commerce and memberships live in commerce-kit.",
   "groups": [
     {
       "title": "Start here",
       "pages": [
         { "slug": "", "title": "Overview", "file": "README.md" },
         { "slug": "migrating-to-7", "title": "Migrating to 7", "file": "docs/MIGRATING-TO-7.md" },
+        { "slug": "migrating-to-8", "title": "Migrating to 8", "file": "docs/MIGRATING-TO-8.md" },
         { "slug": "agents", "title": "For coding agents", "file": "AGENTS.md" }
       ]
     },
@@ -41,16 +42,10 @@
         { "slug": "chat", "title": "Website chat", "file": "src/chat/README.md" },
         { "slug": "popups", "title": "Popups and banners", "file": "src/website/README.md" },
         { "slug": "cta-bar", "title": "CTA bar", "file": "src/cta-bar/README.md" },
+        { "slug": "booking", "title": "Booking", "file": "src/sync/README.md" },
         { "slug": "signal", "title": "Signal (A/B)", "file": "src/signal/README.md" }
       ]
     },
-    {
-      "title": "Commerce",
-      "pages": [
-        { "slug": "commerce", "title": "Commerce", "file": "src/commerce/README.md" },
-        { "slug": "booking", "title": "Booking", "file": "src/sync/README.md" }
-      ]
-    },
     {
       "title": "AI visibility",
       "pages": [
@@ -62,6 +57,7 @@
       "title": "More",
       "pages": [
         { "slug": "motion", "title": "Motion", "file": "src/motion/README.md" },
+        { "slug": "runtime", "title": "Building a kit", "file": "src/runtime/README.md" },
         { "slug": "admin-auth", "title": "Sign in with Sonor", "file": "src/admin-auth/README.md" }
       ]
     }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@sonordev/site-kit",
-  "version": "7.3.0",
+  "version": "8.0.0",
   "type": "module",
   "packageManager": "pnpm@11.5.3",
-  "description": "Complete client-side integration kit for Sonor - SEO, Analytics, Engage, Forms, Blog",
+  "description": "The Sonor modules a Next.js site needs, from one package and one API key: SEO, analytics, forms, articles, chat, booking, AI visibility and agent tools. Selling online? Add @sonordev/commerce-kit.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -13,7 +13,7 @@
     "**/*.css"
   ],
   "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
     "sonor-register-sitemap": "dist/seo/register-sitemap-cli.js"
@@ -43,10 +43,6 @@
       "types": "./dist/analytics/index.d.ts",
       "default": "./dist/analytics/index.js"
     },
-    "./engage": {
-      "types": "./dist/engage/index.d.ts",
-      "default": "./dist/engage/index.js"
-    },
     "./signal": {
       "types": "./dist/signal/index.d.ts",
       "default": "./dist/signal/index.js"
@@ -75,14 +71,6 @@
       "types": "./dist/articles/server-ui.d.ts",
       "default": "./dist/articles/server-ui.js"
     },
-    "./commerce": {
-      "types": "./dist/commerce/index.d.ts",
-      "default": "./dist/commerce/index.js"
-    },
-    "./commerce/server": {
-      "types": "./dist/commerce/server.d.ts",
-      "default": "./dist/commerce/server.js"
-    },
     "./sync": {
       "types": "./dist/sync/index.d.ts",
       "default": "./dist/sync/index.js"
@@ -207,14 +195,6 @@
       "types": "./dist/website/slots/contract.d.ts",
       "default": "./dist/website/slots/contract.js"
     },
-    "./website/cms": {
-      "types": "./dist/website/cms.d.ts",
-      "default": "./dist/website/cms.js"
-    },
-    "./website/cms/server": {
-      "types": "./dist/website/cms/server.d.ts",
-      "default": "./dist/website/cms/server.js"
-    },
     "./website/landing": {
       "types": "./dist/website/landing.d.ts",
       "default": "./dist/website/landing.js"
@@ -323,14 +303,6 @@
       "types": "./dist/config/index.d.ts",
       "default": "./dist/config/index.js"
     },
-    "./cms": {
-      "types": "./dist/cms/index.d.ts",
-      "default": "./dist/cms/index.js"
-    },
-    "./cms/server": {
-      "types": "./dist/cms/server.d.ts",
-      "default": "./dist/cms/server.js"
-    },
     "./maps": {
       "types": "./dist/maps/index.d.ts",
       "default": "./dist/maps/index.js"
@@ -355,6 +327,10 @@
       "types": "./dist/client/index.d.ts",
       "default": "./dist/client/index.js"
     },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "default": "./dist/runtime/index.js"
+    },
     "./brand.css": "./dist/brand.css",
     "./forms/styles.css": "./dist/forms/styles.css",
     "./forms/static": {
@@ -375,6 +351,7 @@
     "docs.json",
     "CHANGELOG.md",
     "docs/MIGRATING-TO-7.md",
+    "docs/MIGRATING-TO-8.md",
     "src/*/README.md"
   ],
   "scripts": {
@@ -395,13 +372,15 @@
     "typecheck": "tsc --noEmit",
     "typecheck:setup": "tsc --noEmit -p packages/sonor-setup/tsconfig.json",
     "version": "node scripts/sync-version.cjs && node scripts/gen-agent-manifest.cjs && git add src/shared/version.ts agent-manifest.json",
-    "prepublishOnly": "rm -rf dist && NODE_OPTIONS=--max-old-space-size=8192 tsup && pnpm build:types && node scripts/gen-agent-manifest.cjs && node scripts/verify-dts.cjs && node scripts/prepublish-integration.cjs && node scripts/audit-as-consumer.cjs && node scripts/verify-docs.cjs",
+    "prepublishOnly": "vitest run && tsc --noEmit -p packages/commerce-kit/tsconfig.json && rm -rf dist && NODE_OPTIONS=--max-old-space-size=8192 tsup && pnpm build:types && node scripts/gen-agent-manifest.cjs && node scripts/verify-dts.cjs && node scripts/verify-no-local-paths.cjs dist agent-manifest.json && node scripts/prepublish-integration.cjs && node scripts/audit-as-consumer.cjs && node scripts/verify-docs.cjs",
     "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly --noEmit false && node scripts/alias-dts.cjs",
-    "verify:docs": "node scripts/verify-docs.cjs"
+    "verify:docs": "node scripts/verify-docs.cjs",
+    "build:commerce": "node scripts/check-kit-build-order.cjs && NODE_OPTIONS=--max-old-space-size=8192 tsup --config packages/commerce-kit/tsup.config.ts && tsc -p packages/commerce-kit/tsconfig.build.json && node packages/commerce-kit/scripts/verify-dist.cjs && node packages/commerce-kit/scripts/verify-against-site-kit.cjs",
+    "test:commerce": "vitest run packages/commerce-kit && tsc --noEmit -p packages/commerce-kit/tsconfig.json",
+    "typecheck:commerce": "tsc --noEmit -p packages/commerce-kit/tsconfig.json",
+    "verify:docs:commerce": "node scripts/verify-docs.cjs packages/commerce-kit"
   },
   "peerDependencies": {
-    "@portabletext/react": "^8.0.0",
-    "@sanity/image-url": "^2.1.1",
     "@vis.gl/react-google-maps": ">=1.0.0",
     "gsap": "^3.13.0",
     "next": "^16.0.0",
@@ -422,12 +401,6 @@
     "@vis.gl/react-google-maps": {
       "optional": true
     },
-    "@portabletext/react": {
-      "optional": true
-    },
-    "@sanity/image-url": {
-      "optional": true
-    },
     "gsap": {
       "optional": true
     },
@@ -446,8 +419,6 @@
     "@babel/parser": "^8.0.4",
     "@babel/traverse": "^8.0.4",
     "@babel/types": "^8.0.4",
-    "@portabletext/react": "^8.0.0",
-    "@sanity/image-url": "^2.1.1",
     "@types/babel__generator": "^7.27.0",
     "@types/babel__traverse": "^7.28.0",
     "@types/inquirer": "^9.0.10",
@@ -480,7 +451,7 @@
     "seo",
     "analytics",
     "forms",
-    "engage",
+    "chat",
     "articles",
     "publishing",
     "nextjs",

package/skills/site-kit/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: site-kit
-description: Integrate, upgrade, or debug a Next.js site's Sonor integration via @sonordev/site-kit. Use when wiring a site to Sonor, migrating a 2.x integration to 3.x, or diagnosing SSR/analytics/key issues on a site that installs @sonordev/site-kit. Trigger on "wire up Sonor", "connect this site to Sonor", "site-kit", "sonor-setup", "SiteKitLayout", "analytics bailout / CSR", or a failing `sonor-setup verify`.
+description: Integrate, upgrade, or debug a Next.js site's Sonor integration via @sonordev/site-kit. Use when wiring a site to Sonor, migrating a 2.x integration to 3.x, or diagnosing SSR/analytics/key issues on a site that installs @sonordev/site-kit. Also use when moving a site to site-kit 8, or when adding commerce, events or memberships through @sonordev/commerce-kit. Trigger on "wire up Sonor", "connect this site to Sonor", "site-kit", "sonor-setup", "SiteKitLayout", "commerce-kit", "analytics bailout / CSR", or a failing `sonor-setup verify`.
 ---
 
-# @sonordev/site-kit — integration skill
+# @sonordev/site-kit: integration skill
 
 You are integrating a Next.js site with Sonor using `@sonordev/site-kit`. The
 package ships its own machine-readable contract; use it instead of guessing.
@@ -16,7 +16,7 @@ package ships its own machine-readable contract; use it instead of guessing.
    (`verify`, `doctor`, `codemod`, `manifest`, `init`, `install`, `upgrade`)
    prints ONE JSON envelope to stdout. Parse it; branch on `exitCode`/`checks`.
 3. **Never let a command prompt.** Pass `--yes` (and `--api-key` to `init`) so it
-   runs non-interactively. Exit `3` means you're missing a flag — the error's
+   runs non-interactively. Exit `3` means you're missing a flag; the error's
    `fix` names it.
 4. **One env var: `SONOR_API_KEY`** (server-side, no `NEXT_PUBLIC_` prefix). Never
    add `UPTRADE_*`, `NEXT_PUBLIC_SONOR_API_KEY`, or `SONOR_PROJECT_ID`.
@@ -25,7 +25,7 @@ package ships its own machine-readable contract; use it instead of guessing.
    anywhere below the fold; `./motion/gsap` and `./motion/three` need their
    peer installed first (`npm i gsap` / `npm i three`). Never wrap page
    content in a `dynamic(ssr:false)` component and never animate the hero
-   in — the server HTML must stay fully visible. See `src/motion/README.md`.
+   in; the server HTML must stay fully visible. See `src/motion/README.md`.
 6. **The sticky mobile CTA bar comes from `@sonordev/site-kit/cta-bar`, never a
    per-site `MobileCTABar`.** Render `<CtaBar>` once per page (the layout root
    for a site-wide bar, inside the page for a page-specific one), with
@@ -33,8 +33,17 @@ package ships its own machine-readable contract; use it instead of guessing.
    own bar, its body `padding-bottom`, and any `--sk-echo-offset-bottom` rule
    written for it: the kit reserves the space and lifts the Echo launcher.
    See `src/cta-bar/README.md`.
-
-## First step — discover, don't assume
+7. **Commerce, events and memberships come from `@sonordev/commerce-kit`, not
+   site-kit (since site-kit 8).** Install it beside site-kit with
+   `npm i @sonordev/commerce-kit` and import from
+   `@sonordev/commerce-kit/commerce`, `/commerce/server`, `/memberships` or
+   `/memberships/server`. The old site-kit commerce entries are gone, and
+   `npx sonor-setup manifest --json` lists every moved subpath under
+   `relocated`, the root types that moved under `relocatedTypes`, and what was
+   retired for good (Engage, the CMS, content blocks) under `removed`.
+   Docs: https://sonor.dev/commerce-kit.
+
+## First step: discover, don't assume
 
 ```bash
 cat node_modules/@sonordev/site-kit/AGENTS.md      # human-skimmable guide
@@ -55,7 +64,7 @@ npx sonor-setup verify --json
 
 ```bash
 npx sonor-setup codemod --check --json     # exit 1 ⇒ work pending
-npx sonor-setup codemod --write --json     # apply (idempotent; writes .bak). Review the diff.
+npx sonor-setup codemod --write --json     # apply (idempotent; originals go to a temp folder). Review the diff.
 next build                                 # a bump you didn't build is a guess
 npx sonor-setup verify --json
 ```
@@ -69,22 +78,43 @@ Codemod transforms: `provider-to-layout` (SiteKitProvider→SiteKitLayout),
 (flags an `<AnalyticsProvider>` wrapped around `{children}`; remove it by hand.
 A plain `<SiteKitLayout>{children}</SiteKitLayout>` is correct and isn't flagged).
 
+## Move a 7.x site that sells to site-kit 8
+
+Commerce left site-kit in 8.0 (memberships is new, and ships only in
+commerce-kit). A site that doesn't use commerce needs nothing but the version bump.
+
+```bash
+npm i @sonordev/site-kit@^8 @sonordev/commerce-kit
+npx sonor-setup codemod --only site-kit-8 --check --json   # exit 1 ⇒ imports still to move
+npx sonor-setup codemod --only site-kit-8 --write --json   # swaps the package name in each import
+next build
+npx sonor-setup verify --json
+```
+
+It rewrites the imports, adds `@sonordev/commerce-kit` to package.json, raises
+site-kit's range to `^8.0.0` and flags what it can't rewrite. A site that passes
+`offerings` to `sonorMcpServer` also needs `read: getOfferingsResult`, imported from
+`@sonordev/commerce-kit/commerce/server`. See `docs/MIGRATING-TO-8.md`.
+
 ## Debug a red integration
 
 Run `npx sonor-setup doctor --online --json` (or `verify`). Each `checks[]`
 finding has a stable `id`, a `fix`, and often a `fixCommand`. Highest-signal ids:
 
-- `ssr.render` — page bailed to client rendering. On site-kit ≥3.0.2 a plain
+- `ssr.render`: page bailed to client rendering. On site-kit ≥3.0.2 a plain
   `SiteKitLayout` is never the cause: it already mounts analytics as a
   deferred, childless sibling, so don't reach for `analytics={false}`. Find
   what else wraps `{children}` (usually a `next/dynamic({ ssr: false })`
   component, often the site's own Providers) and import it statically or mount
   it as a childless sibling. On <3.0.2, upgrade. Confirm with
   `verify --url <url>`.
-- `key.valid` — key rejected/stale. Put the current `sonor_` key in `.env.local`
+- `key.valid`: key rejected/stale. Put the current `sonor_` key in `.env.local`
   and redeploy (hosts don't pick up env changes without a redeploy).
-- `middleware.netlify` — `middleware.ts` sets `runtime: 'nodejs'`, which
+- `middleware.netlify`: `middleware.ts` sets `runtime: 'nodejs'`, which
   `proxy.ts` rejects. Remove the export, then run the codemod to move it.
-- `layout.sitekit` — deprecated `SiteKitProvider`; run the codemod.
+- `layout.sitekit`: deprecated `SiteKitProvider`; run the codemod.
+- A build that can't resolve a site-kit commerce path: the site is on site-kit 8,
+  where commerce moved to `@sonordev/commerce-kit`. Run the site-kit 8 steps
+  above.
 
 Apply fixes, then re-run `verify --json`. Done when it exits 0.

package/src/analytics/README.md

@@ -1,4 +1,4 @@
-# Analytics — `@sonordev/site-kit/analytics`
+# Analytics: `@sonordev/site-kit/analytics`
 
 Automatic page view tracking, custom events, conversions, scroll depth, heatmap clicks, and Core Web Vitals. All data flows through the Sonor API.
 
@@ -157,22 +157,22 @@ interface AnalyticsConfig {
   trackScrollDepth?: boolean   // Default: true
   sessionTimeout?: number      // Minutes (default: 30)
   excludePaths?: string[]      // Don't track these paths
-  allowInFrame?: boolean       // Default: false — see below
-  allowLocalhost?: boolean     // Default: false — local builds report nothing
+  allowInFrame?: boolean       // Default: false (see below)
+  allowLocalhost?: boolean     // Default: false (local builds report nothing)
   debug?: boolean              // Log events to console
 }
 ```
 
 ## What Gets Tracked Automatically
 
-- **Page views** — on every route change (path, URL, title, referrer, UTM params, device/browser/OS)
-- **Web Vitals** — LCP, CLS, TTFB, INP, FCP with good/needs-improvement/poor ratings
-- **Contact clicks** — `tel:` and `mailto:` links tracked as conversions, once `<ContactTracking />` is mounted (it isn't by default)
-- **DOM metadata** — full snapshot per page view (meta tags, H1, word count, links, content, FAQs)
+- **Page views**: on every route change (path, URL, title, referrer, UTM params, device/browser/OS)
+- **Web Vitals**: LCP, CLS, TTFB, INP, FCP with good/needs-improvement/poor ratings
+- **Contact clicks**: `tel:` and `mailto:` links tracked as conversions, once `<ContactTracking />` is mounted (it isn't by default)
+- **DOM metadata**: full snapshot per page view (meta tags, H1, word count, links, content, FAQs)
 
 ## Embedded pages report nothing (`analytics.allowInFrame`)
 
-When this site is loaded inside a **cross-origin iframe**, nothing is sent —
+When this site is loaded inside a **cross-origin iframe**, nothing is sent:
 no page views, journey/session rows, scroll depth, heatmap clicks, web vitals,
 events or conversions. The visitor is on whoever framed the page, not on this
 site, so every metric the frame produces is phantom traffic in the analytics
@@ -189,8 +189,8 @@ the pixels, not the JavaScript.
 a print view, an on-domain booking frame) has a real visitor really on that
 site and no other tenant to pollute.
 
-Opt back in only when the frame IS the product — a widget or partner-hosted
-page deliberately distributed as an embed:
+Opt back in only when the frame IS the product (a widget or partner-hosted
+page deliberately distributed as an embed):
 
 ```tsx
 <SiteKitLayout analytics={{ allowInFrame: true }}>…</SiteKitLayout>
@@ -199,7 +199,7 @@ page deliberately distributed as an embed:
 There is deliberately no env var or window global for this. A silent switch
 that turns cross-tenant tracking back on is the failure mode, not the feature.
 
-The decision lives in one place — `shared/reporting-gate.ts`, over the frame
+The decision lives in one place, `shared/reporting-gate.ts`, over the frame
 primitive in `shared/frame.ts`. Every send in the module routes through it, and
 `send-gate.test.ts` fails the build if a new one does not. `isCrossOriginFrame()`
 is exported from `@sonordev/site-kit/analytics` if a site needs the same answer
@@ -229,8 +229,8 @@ Neither option bypasses authentication. No environment variable or global
 silently enables local reporting.
 
 This is a browser gate: build-time `createSitemap` and Node fleet reporting
-still run. It doesn't disable forms, commerce, or Signal. When verifying those
-modules locally, point them at a test API as well.
+still run. It doesn't disable forms, Signal, or [commerce-kit](https://sonor.dev/commerce-kit).
+When verifying those modules locally, point them at a test API as well.
 
 ## Environment
 
@@ -257,6 +257,6 @@ site without forcing each microsite into its own Sonor project.
 </SiteKitLayout>
 ```
 
-Most projects leave it implicit — `NEXT_PUBLIC_SITE_URL` is already set per
+Most projects leave it implicit: `NEXT_PUBLIC_SITE_URL` is already set per
 microsite, so the dimension fills in automatically. The dashboard shows a
 "Site" picker + a "Sites" tab as soon as ≥2 distinct hosts are detected.

package/src/chat/README.md

@@ -46,7 +46,7 @@ interface SiteChatProps {
 ```
 
 Through `SiteKitLayout`, the placement options go in `chat={{ ... }}`. The
-deprecated `engage={{ ... }}` still works through 7.x.
+deprecated `engage={{ ... }}` still works; it goes in a later major.
 
 ## The chat switch
 
@@ -233,10 +233,10 @@ interface ChatConfig {
 Popups, banners and toasts are their own module now:
 [Popups and banners](../website/README.md) (`@sonordev/site-kit/website/popups`).
 
-## `@sonordev/site-kit/engage` (deprecated)
+## Engage (retired)
 
-Engage was retired in Sonor. Its entry stays through 7.x so old imports keep
-building: `ChatWidget` and the chat types re-export from here, and
-`EngageWidget` draws `SiteChat` and `SitePopups`. Engage Studio's renderer
-(`DesignRenderer`) is gone; popups render from blocks. Import
-`@sonordev/site-kit/chat` and `@sonordev/site-kit/website/popups` instead.
+Engage was retired in Sonor, and `@sonordev/site-kit/engage` was removed in
+site-kit 8. `ChatWidget` and the chat types are here, popups are in
+`@sonordev/site-kit/website/popups`, and `SiteKitLayout` mounts both for you.
+Engage Studio's renderer (`DesignRenderer`) is gone; popups render from blocks.
+`npx sonor-setup codemod --write` moves the names that have a home.