@sonordev/site-kit 7.4.0 → 8.0.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@sonordev/site-kit",
-  "version": "7.4.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.

package/src/forms/README.md

@@ -1,4 +1,4 @@
-# Forms — `@sonordev/site-kit/forms`
+# Forms: `@sonordev/site-kit/forms`
 
 Sonor-managed forms with multi-step support, conditional logic, validation, anti-bot protection, and automatic CRM routing.
 
@@ -21,7 +21,7 @@ Fetches form config from Sonor, renders fields, handles submission, routes to CR
 Since 4.0 that one line gets you the **spotlight** experience by default: the
 familiar layout, alive. A glowing ring visits the field you're in, completed
 fields earn a check, and each finished row collapses into a sentence the form
-says back — "Nice to meet you, Jordan." / "We'll follow up at jordan@…" — with
+says back ("Nice to meet you, Jordan." or "We'll follow up at jordan@…"), with
 an edit control to reopen it.
 
 | Experience | What it is | How to get it |
@@ -36,7 +36,7 @@ an edit control to reopen it.
 <ManagedForm formId="contact-form" experience="classic" /> // opt out
 ```
 
-Sonor can decide instead of the site, with no deploy on either side — set the
+Sonor can decide instead of the site, with no deploy on either side: set the
 form's `layout` to `classic`, `stage`, or `spotlight`. An explicit
 `experience` prop always wins over the config.
 
@@ -68,7 +68,7 @@ Welcome aboard, {first_name}. We'll reach you at {email}.
 ```
 
 Leave it empty to keep the built-in sentence. Unknown or unanswered tokens
-render as nothing — never raw braces.
+render as nothing, never raw braces.
 
 ### Option 2: Headless Hook (full UI control)
 
@@ -101,6 +101,59 @@ export function ContactForm() {
 }
 ```
 
+#### Autocomplete on your own controls
+
+`ManagedForm` puts the right `autocomplete` token on each field that has one, so
+browser autofill, password managers and AI assistants know what the field wants.
+When you draw the controls yourself, with `useForm` or the render prop below, ask
+for the same token with `autocompleteFor` (since 8.0.0) and pass it to
+`autoComplete`:
+
+```tsx
+'use client'
+import { useForm, autocompleteFor } from '@sonordev/site-kit/forms'
+
+export function QuoteForm() {
+  const { fields, values, setFieldValue, handleSubmit, toolAttributes } = useForm('quote-request')
+
+  return (
+    <form {...toolAttributes} onSubmit={handleSubmit}>
+      {fields.map(field => (
+        <label key={field.slug}>
+          {field.label}
+          <input
+            name={field.slug}
+            autoComplete={autocompleteFor(field)}
+            value={String(values[field.slug] || '')}
+            onChange={(e) => setFieldValue(field.slug, e.target.value)}
+          />
+        </label>
+      ))}
+      <button type="submit">Request a quote</button>
+    </form>
+  )
+}
+```
+
+It returns a token such as `given-name`, `email`, `tel`, `organization` or
+`postal-code`, or `undefined` when a field has no confident match, and React
+leaves the attribute off for `undefined`. Only text, email and phone fields and
+selects get a token, so a message box, a number, a date or a checkbox gets
+`undefined`. To stay short, the example draws every field as a text input and
+leaves out error messages and steps; draw each field with the control it calls
+for and pass the same `autoComplete={autocompleteFor(field)}` to all of them.
+
+Use it instead of typing tokens per field. It works the token out from the
+field's type, slug and label, so your markup doesn't keep a list of its own that
+can drift. `@sonordev/site-kit/forms` is a client module, like `useForm`, so call
+`autocompleteFor` from a client component (a file that starts with
+`'use client'`). Calling it in a Server Component fails the build.
+
+To type a field you pass around, use `UseFormReturn['fields'][number]`, or
+`AutocompleteField` for a helper that only needs the token. Don't use the
+`FormField` this entry exports: that's the shape `formsApi` takes (camelCase keys
+such as `fieldType`), not what `useForm` returns.
+
 ### Option 3: Render Prop
 
 ```tsx
@@ -228,7 +281,8 @@ nothing to configure.
   fields carry the right `autocomplete` token (`given-name`, `email`, `tel`,
   `organization`, `url`, `postal-code`, ...), read from the field's CRM
   destination in Sonor, then its type, slug and label. Browser autofill and
-  password managers use the same tokens.
+  password managers use the same tokens. A headless form adds them with
+  `autocompleteFor` (see [Autocomplete on your own controls](#autocomplete-on-your-own-controls)).
 - **Accessible wiring.** Error and help text are tied to their control
   (`aria-describedby`), an errored control says so (`aria-invalid`), radio and
   checkbox groups are named by their question, and rating stars by their
@@ -252,7 +306,8 @@ nothing to configure.
   until the page can catch the click.
 
 With `useForm`, spread `toolAttributes` on your `<form>` and use
-`handleSubmit` as its `onSubmit` to get the same behavior.
+`handleSubmit` as its `onSubmit` to get the WebMCP behavior and the agent-sent
+tag, and add `autocompleteFor` to your controls for the autofill tokens.
 
 `ServerForm`'s `enhance` prop is ignored since 7.2.0. Only the interactive
 form can send a managed form, so `enhance={false}` only ever produced a form

package/src/mcp/README.md

@@ -1,4 +1,4 @@
-# `@sonordev/site-kit/mcp` — WebMCP & Model Context Protocol
+# `@sonordev/site-kit/mcp`: WebMCP & Model Context Protocol
 
 Make a marketing site something an AI agent can **use**, not just read.
 
@@ -8,12 +8,12 @@ definitions:
 
 | Surface | Who uses it | Entry point |
 |---|---|---|
-| Remote MCP endpoint (Streamable HTTP) | Off-browser agents — Claude, Cursor, any MCP client | `createMcpHandler` |
+| Remote MCP endpoint (Streamable HTTP) | Off-browser agents: Claude, Cursor, any MCP client | `createMcpHandler` |
 | Server card and experimental AI catalog | Crawlers and clients discovering the endpoint | `createMcpServerCardHandler`, `createMcpAiCatalogHandler` |
 | In-page WebMCP | Browser-driving agents | `<WebMcpTools>`, `declarativeToolForm` |
 
-One definition feeding all three is the point. The alternative — a tool list for
-the endpoint and a separate one for the page — drifts, and a stale tool
+One definition feeding all three is the point. The alternative, a tool list for
+the endpoint and a separate one for the page, drifts, and a stale tool
 definition is worse than none, because the agent believes it.
 
 ---
@@ -36,7 +36,7 @@ site's pages use, so an agent gets what a visitor gets.
 | `find_pages` | The page that covers a topic |
 | `list_articles`, `get_article` | Its articles (`articles: false` drops them) |
 | `get_reviews` | Reviews verbatim, with who wrote them, and the rating |
-| `list_offerings` | Priced products, services, events (opt-in: `offerings: { path }`); private prices are left out |
+| `list_offerings` | Priced products, services, events (opt-in: `offerings: { path, read }`, see below); private prices are left out |
 | `check_availability` | Open appointment times, read only (opt-in: `booking: { path }`) |
 | `get_inquiry_form`, `send_inquiry` | An inquiry for a person (opt-in: `inquiry: { form }`) |
 
@@ -63,6 +63,47 @@ export const { POST, GET, DELETE, OPTIONS } = createMcpHandler({
 })
 ```
 
+**`list_offerings` needs a reader (8.0).** The catalog it lists belongs to
+[commerce-kit](https://sonor.dev/commerce-kit), so you hand the tool commerce-kit's
+fetcher instead of site-kit importing it:
+
+```ts
+// lib/mcp.ts
+import 'server-only'
+import { sonorMcpServer } from '@sonordev/site-kit/mcp/sonor'
+import { getOfferingsResult } from '@sonordev/commerce-kit/commerce/server'
+
+export const mcpServer = sonorMcpServer({
+  businessName: 'Example Studio',
+  offerings: { path: '/shop', read: getOfferingsResult },
+})
+```
+
+`read` is required and is `getOfferingsResult` from
+`@sonordev/commerce-kit/commerce/server`, so the site needs commerce-kit installed
+(`npm install @sonordev/commerce-kit`). When a request fails it tells the agent the
+catalog is unavailable; the plain `getOfferings` from the same entry also works, but
+it reads an outage as an empty catalog. The other tools, `list_services` included,
+don't. `path` is where the offerings' pages live: each offering links to
+`<path>/<slug>` on the site, and `path` defaults to `/shop`. An agent can narrow the
+list with `type` (`product`, `service` or `event`), search it with `query`, and cap
+it with `limit` (at most 20). 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.
+
+`read` is typed `McpOfferingsReader`, and what it returns is a list of `McpOffering`s
+(a name, type, slug, descriptions and a price), or `{ ok, data }` around that list. Both
+types are exported from `@sonordev/site-kit/mcp/sonor`. commerce-kit's fetchers satisfy
+them as they are, so you only meet the types if you supply the catalog from somewhere
+else: write a function that takes `({ apiUrl, apiKey, projectId }, { type, limit })` and
+returns the offerings, and answer `{ ok: false, data: [] }` when the request fails, so
+the agent hears "unavailable" instead of "nothing for sale".
+
+Without `read`, `sonorMcpServer` throws when the server is built, with a message that
+names the fix. `npx sonor-setup mcp --offerings /shop` writes this wiring for a new
+site, import included, and tells you to install commerce-kit. Before 8.0 the option
+was `offerings: { path }`; see
+[Moving a site to site-kit 8](../../docs/MIGRATING-TO-8.md#the-mcp-change).
+
 **`send_inquiry` has a person behind it.** It refuses unless
 `person_confirmed` is true (the person asked to be contacted and agreed to
 share their details), files through Sonor's agent-inquiry door with the
@@ -205,7 +246,7 @@ aliases for clients that already use them. The card handler's default remains
 ### 4. Register in-page (optional, for browser agents)
 
 ```tsx
-// app/layout.tsx — a CHILDLESS SIBLING, never a wrapper
+// app/layout.tsx: a CHILDLESS SIBLING, never a wrapper
 <SiteKitLayout>{children}</SiteKitLayout>
 <WebMcpTools endpoint="/api/mcp" />
 ```
@@ -290,13 +331,13 @@ The header and label default to `x-site-mcp-transport` and
 `{ header, label }` to all three factories (for example
 `x-example-mcp-transport` / `example-mcp-transport-v1`). This entry is Node
 only and imports no `server-only`, so the plain-Node function can load it. It
-is not re-exported from `@sonordev/site-kit/mcp`, which stays runtime-neutral.
+isn't re-exported from `@sonordev/site-kit/mcp`, which stays runtime-neutral.
 
 ---
 
 ## Design notes
 
-### The card does not list tools — on purpose
+### The card doesn't list tools, on purpose
 
 The card's discovery shape omits primitives: what a server exposes can
 vary with auth state and configuration, so the authoritative list is whatever
@@ -306,8 +347,8 @@ source of truth that goes stale silently.
 We still publish a **summary** (name + description + read-only flag) under
 `_meta['io.sonor.site-kit/tools']`. `_meta` is the spec's sanctioned extension
 point and requires a reverse-DNS prefix, so the hint rides along without
-pretending to be standard — useful for crawlers that index the card and never
-connect.
+pretending to be standard. That's useful for crawlers that index the card and
+never connect.
 
 ### Experimental discovery and compatibility paths
 
@@ -323,21 +364,21 @@ URLs working while adding the catalog.
 
 `dispatch()` answers both protocol eras on one endpoint:
 
-- **Modern (`2026-07-28`)** — stateless, per-request `_meta` carrying the
+- **Modern (`2026-07-28`)**: stateless, per-request `_meta` carrying the
   protocol version, mirrored into `MCP-Protocol-Version`. `server/discover`
   replaces the handshake. No sessions, no GET stream (both return `405`).
-- **Legacy (`≤ 2025-11-25`)** — the `initialize` handshake, which is what most
+- **Legacy (`≤ 2025-11-25`)**: the `initialize` handshake, which is what most
   shipped clients and SDKs still speak.
 
 Supporting only the current revision would be spec-correct and unusable today.
 
-### Header mirroring: mismatch is fatal, absence is not
+### Header mirroring: mismatch is fatal, absence isn't
 
 The modern revision mirrors `method` and `params.name` into `Mcp-Method` and
 `Mcp-Name` so intermediaries can route without parsing bodies, and requires
 servers to reject disagreements (`-32020`).
 
-We always reject a **mismatch** — that is the real security property, stopping
+We always reject a **mismatch**; that's the real security property, stopping
 a load balancer and the server from acting on different values. A merely
 **absent** header is tolerated unless you set `strictHeaders: true`, because a
 public marketing endpoint exists to be reachable and today's clients frequently
@@ -360,13 +401,13 @@ one or the other makes you invisible to a large slice of the ecosystem.
 
 `<WebMcpTools>` does nothing at all unless `document.modelContext` exists. That
 gate comes before the `tools/list` fetch, so the cost for a human visitor is a
-single property check — not a request, and not a byte of page weight.
+single property check: not a request, and not a byte of page weight.
 
 ### In-page tools are proxied, not re-implemented
 
 `<WebMcpTools>` registers thin wrappers that POST `tools/call` to this site's
 own endpoint, so the in-page tool and the remote tool run the same server-side
-handler. It also keeps `SONOR_API_KEY` out of the client bundle — registering
+handler. It also keeps `SONOR_API_KEY` out of the client bundle: registering
 real handlers client-side would pull server code, and the key with it, into a
 `'use client'` graph and a public chunk.
 
@@ -376,13 +417,13 @@ Tools that genuinely need live DOM state go in `localTools` and run in-page.
 
 `<WebMcpTools>` waits for the page to go quiet (`useDeferredActivation`) before
 touching `document.modelContext`. Agents poll or listen for `toolchange`, so a
-few hundred milliseconds costs nothing — a blocked LCP costs a lot.
+few hundred milliseconds costs nothing, while a blocked LCP costs a lot.
 
 ---
 
 ## Writing good tools
 
-The `description` is the highest-leverage field in this module. It is the only
+The `description` is the highest-leverage field in this module. It's the only
 thing a model reads when deciding whether to call the tool.
 
 - **Verb-led `snake_case` names**: `get_services`, `request_site_audit`.
@@ -391,10 +432,10 @@ thing a model reads when deciding whether to call the tool.
 - **Set `annotations` honestly.** `readOnlyHint` on lookups; `destructiveHint`
   on anything creating a record. Good agents use these to decide what needs a
   human.
-- **Never `toolautosubmit` a lead form.** That is how an agent files fifty
+- **Never `toolautosubmit` a lead form.** That's how an agent files fifty
   audit requests by accident.
 - **Return the caveat with the data.** A pricing tool should return the ranges
-  *and* the fact that they are ranges — otherwise the model quotes a number as
+  *and* the fact that they're ranges; otherwise the model quotes a number as
   a commitment.
 
 ## Testing an endpoint by hand