@sonordev/site-kit 7.3.0 → 8.0.0

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

package/src/proxy/README.md

@@ -2,10 +2,11 @@
 
 Composable Next.js Proxy factory. Zero-config redirects + security headers. Opt-in AI discovery headers.
 
-Next 16 renamed the `middleware` file convention to `proxy`. Through 7.x this
-module is also served on `@sonordev/site-kit/middleware`, with `createMiddleware`
-as an alias of `createProxy`; both go in 8.0. `npx sonor-setup codemod --write`
-moves a site over (the file too).
+Next 16 renamed the `middleware` file convention to `proxy`. This module is
+also served on `@sonordev/site-kit/middleware`, with `createMiddleware` as an
+alias of `createProxy`. Both are deprecated and still work in 8; they'll go in a
+later major, so move off them when you next touch the file.
+`npx sonor-setup codemod --write` moves a site over (the file too).
 
 ## Usage
 

package/src/reputation/README.md

@@ -27,6 +27,7 @@ interface TestimonialSectionProps {
   autoplay?: boolean              // Auto-rotate reviews
   autoplayInterval?: number       // ms between rotations
   showRating?: boolean            // Display star ratings
+  showPhoto?: boolean             // Show attached business photo (default true)
   maxReviews?: number             // Limit displayed count
   featuredOnly?: boolean          // Show featured reviews only
   service?: string                // Filter by service tag
@@ -34,6 +35,29 @@ interface TestimonialSectionProps {
 }
 ```
 
+## Visual review cards
+
+Render a photo and its original review together with a responsive, server-rendered gallery:
+
+```tsx
+import { fetchReviews, VisualReviewGallery } from '@sonordev/site-kit/reputation/server'
+
+export default async function ReviewsPage() {
+  const reviews = await fetchReviews({ limit: 12 })
+  return <VisualReviewGallery reviews={reviews} title="What Our Clients Say" />
+}
+```
+
+`VisualReviewCard` accepts one `review`, optional `showRating` and `className`.
+`VisualReviewGallery` accepts `reviews`, optional `title`, `subtitle`, `showRating`
+and `className`. Both use the site's `--sk-*` brand tokens and work in React
+Server Components. Import `@sonordev/site-kit/brand.css` once for token defaults,
+then override them in your site's CSS.
+
+Text-only reviews stay visible while a photo is pending. Adding or removing a
+photo in Sonor updates the public review feed; `image` continues to mean the
+reviewer's avatar. Only HTTPS photo URLs are displayed.
+
 ## API Functions
 
 ```ts
@@ -50,6 +74,7 @@ interface Review {
   id: string; quote: string; name: string; role?: string;
   rating: number; image?: string; date?: string;
   platform?: string; isFeatured?: boolean; serviceTags?: string[];
+  photo?: { fileId: string; url: string; altText: string; caption: string } | null;
 }
 
 interface ReviewStats {

package/src/revalidate/README.md

@@ -15,7 +15,7 @@ tells you when it's missing.
 
 Everything site-kit fetches from Sonor is cached, and pages built from those
 fetches are served from your host's CDN. When content changes in Sonor
-(managed copy, a page's title or description, an article, a portfolio item),
+(managed copy, a page's title or description, an article, a portfolio item, a product or event),
 Sonor sends this route the paths and cache tags that changed. The route checks
 the call was signed with your project's API key, then expires only those
 pages and tags. The next visitor gets the new version, and every other page
@@ -60,7 +60,7 @@ A POST with `Authorization: Bearer <SONOR_API_KEY>` and a JSON body:
 | Field | Meaning |
 |---|---|
 | `paths` | Local paths to regenerate. `/sitemap.xml`, `/llms.txt` and `/llms-full.txt` are always refreshed too. |
-| `tags` | Cache tags to expire. The ones Sonor uses are `SITE_CACHE_TAGS`: `sonor-slots` (managed copy), `seo` (metadata, schema, FAQs), `blog` (articles), `editorial-taxonomy` and `portfolio`. |
+| `tags` | Cache tags to expire. The ones Sonor uses are `SITE_CACHE_TAGS`: `sonor-slots` (managed copy), `seo` (metadata, schema, FAQs), `blog` (articles), `editorial-taxonomy`, `portfolio` and `commerce` (products, services, events and membership plans, from [commerce-kit](https://sonor.dev/commerce-kit)). |
 | `revalidateAll` | Regenerate every page. |
 | `ping` | `{ "ping": true }` on its own regenerates nothing and answers `{ "ok": true, "ping": true, "version": "…" }`. Sonor uses it to confirm the route is installed. |
 

package/src/runtime/README.md

@@ -0,0 +1,51 @@
+# Runtime
+
+`@sonordev/site-kit/runtime` is how a package that builds on site-kit talks to Sonor from the browser, so it never needs a transport of its own. [commerce-kit](https://sonor.dev/commerce-kit) is built on it.
+
+Building a site? You don't need this entry. Forms, analytics, articles and the rest of site-kit already use the same transport.
+
+## What it gives a kit
+
+| Export | Use it to |
+|---|---|
+| `sonorFetch(url, init?, options?)` | Call the Sonor API from the browser. It sends the site credential you pass as `apiKey`, retries transient failures with a timeout, refreshes an expired site token once, and pauses for a few minutes after an authentication failure, so a misconfigured site doesn't hammer the API. |
+| `getClientApiConfig(options?)` | Find the API origin and credential. In the browser that's what `SiteKitLayout` published. During server rendering it's the server's `SONOR_API_URL`, and with `{ serverKey: true }` its `SONOR_API_KEY`. |
+| `readPublishedApiConfig()` | Exactly what `SiteKitLayout` published, with no fallbacks. For code that must stay quiet on a page without the layout. |
+| `DEFAULT_SONOR_API_URL` | `https://api.sonor.io`. |
+| `readAnalyticsIdentity()` | Get the visitor's analytics ids, `{ sessionId, visitorId }`, so what you send to Sonor ties to the visit analytics recorded. It only reads: either id is `null` during server rendering and before analytics has started a session in the tab. It never throws, including when the browser blocks site storage. |
+
+The types `SonorFetchOptions`, `FetchRetryOptions`, `ClientApiConfigOptions` and `AnalyticsIdentity` come with them.
+
+```ts
+import { getClientApiConfig, sonorFetch } from '@sonordev/site-kit/runtime'
+
+export async function startCheckout(payload: unknown) {
+  const { apiUrl, apiKey } = getClientApiConfig()
+  // Anything that isn't safe to repeat (checkout, payments, uploads) passes retries: 0.
+  const response = await sonorFetch(
+    `${apiUrl}/api/public/example/checkout`,
+    { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) },
+    { apiKey, retries: 0 },
+  )
+  return response.json()
+}
+```
+
+Pass `apiKey` from `getClientApiConfig()` and `sonorFetch` sets the `x-api-key` header itself, using the site's freshest token when the site uses one. Don't set `x-api-key` or `Authorization` yourself: on a site that uses tokens, a stale header you set is replaced by the fresh one.
+
+## Rules for kits
+
+- **Use this entry for browser calls.** Don't read `window.__SITE_KIT_*` and don't call `fetch` on the Sonor API directly. A second transport is a second copy of the credential, retry and breaker logic, and it drifts.
+- **Get the visitor's ids from `readAnalyticsIdentity()`.** Where site-kit keeps them is its own business and can change.
+- **Server data goes through `@sonordev/site-kit/server`.** `serverApiFetch` sends the key, bounds each call in time and retries transient failures. Tag what you fetch with your content's entry in `SITE_CACHE_TAGS` so an edit in Sonor refreshes it, and if you catch errors around your own server calls, rethrow the ones `isNextControlFlow` recognizes: they're Next steering the render (a page turning dynamic, `redirect()`, `notFound()`), not failures.
+- **Events go through `trackEvent` and `trackConversion`** from `@sonordev/site-kit/analytics` (`@sonordev/site-kit/client` exports them too). They wait for the analytics provider, which mounts after the page. Don't use the `useAnalytics` hooks in a kit: under `SiteKitLayout` your components sit outside the provider, so the hooks have nothing to return.
+- **Lead capture goes through `ManagedForm`** from `@sonordev/site-kit/forms`.
+- **List site-kit as a peer dependency** and mark it external in your bundler, so every kit shares the site's one copy.
+
+## Why it's its own entry
+
+`@sonordev/site-kit/client` is stamped `'use client'`. A function imported from a stamped module into a server component becomes a client reference there and can't be called, and `getClientApiConfig` is built to run during server rendering. So `runtime` isn't stamped, imports neither React nor Next, and works the same from a server component, a route handler or a client component.
+
+## Stability
+
+This entry is public API under semver. New exports arrive in minor releases; nothing in the list above is removed or changed in a minor or patch release.

package/src/seo/README.md

@@ -1,6 +1,6 @@
 # SEO: `@sonordev/site-kit/seo`
 
-Server Components and server helpers that render what you manage in the SEO module at [app.sonor.io](https://app.sonor.io): page metadata, JSON-LD, FAQs, internal links, content blocks, redirects and robots directives.
+Server Components and server helpers that render what you manage in the SEO module at [app.sonor.io](https://app.sonor.io): page metadata, JSON-LD, FAQs, internal links, redirects and robots directives.
 
 The project comes from `SONOR_API_KEY`. Nothing in this module takes a project ID. A few option types and props still carry an optional `projectId` from older versions; it's ignored, so leave it out.
 
@@ -55,6 +55,7 @@ export async function generateMetadata({ params }: { params: Promise<{ slug: str
 | `fallback` | `Metadata` | Fills any field Sonor has no managed value for. Used in full when the page isn't in Sonor at all. |
 | `overrides` | `Partial<Metadata>` | Applied last, so it wins over managed values. |
 | `favicon` | `'metadata' \| 'component'` | `'metadata'` (default) adds `icons` from the project logo. Pass `'component'` when your layout already renders the favicon, which `SiteKitLayout` does by default, so icons aren't emitted twice. |
+| `scope` | `'page' \| 'layout'` | `'page'` (default) applies Sonor's managed canonical and hreflang for `path`. Pass `'layout'` when you call this from a root or shared layout, whose metadata every route beneath it inherits. See [Canonical URLs](#canonical-urls). |
 
 It returns a Next.js `Metadata` object with two extra flags, `_managed` and `_source`. Managed fields map like this:
 
@@ -70,6 +71,27 @@ It returns a Next.js `Metadata` object with two extra flags, `_managed` and `_so
 
 When the page exists in Sonor but has neither a title nor a description, the call asks Signal to write them in the background and returns your fallback for now. The generated copy shows up once the cached response refreshes (see [Caching](#caching)).
 
+### Canonical URLs
+
+Every page gets a canonical, so you never have to set one by hand. When Sonor has no `managed_canonical` for the page, `getManagedMetadata` returns `alternates.canonical: './'`. Next resolves that against your `metadataBase` and the route being rendered, so each page names itself (`https://example.com/about` for `/about`). Without a `metadataBase`, Next emits the path alone (`/about`), which is still valid. Set `metadataBase` in your root layout for absolute URLs.
+
+The order, lowest to highest: the self-referencing default, then Sonor's managed canonical and hreflang, then your `fallback`, then your `overrides`. `alternates` merges key by key, so passing only `languages` keeps the canonical, and `canonical: null` opts out.
+
+**Calling it from a layout.** A layout's metadata is inherited by every page under it. If your root layout calls `getManagedMetadata({ path: '/' })`, pass `scope: 'layout'`. Otherwise a managed canonical set for the homepage in Sonor is stamped on every page without its own, and each one tells search engines it's a copy of the homepage:
+
+```tsx
+// app/layout.tsx
+export async function generateMetadata() {
+  return getManagedMetadata({
+    path: '/',
+    scope: 'layout',
+    fallback: { title: 'Example Co', description: 'Plumbing in Cincinnati.' },
+  })
+}
+```
+
+Don't set an absolute `alternates.canonical` in a layout for the same reason. Use `'./'`, or leave it to this helper.
+
 **Title templates.** The managed title comes back as a plain string, so a root-layout `title.template` still applies to it. If your managed titles already include the brand, you'll get it twice. Mark the title absolute:
 
 ```ts
@@ -100,7 +122,7 @@ export const generateMetadata = withManagedMetadata('/about', async () => ({
 }))
 ```
 
-Whatever `pageMetadata` returns wins over Sonor's values. `openGraph` and `twitter` merge one level deep. It calls `getManagedMetadata` with the default `favicon: 'metadata'`.
+Whatever `pageMetadata` returns wins over Sonor's values. `openGraph`, `twitter` and `alternates` merge one level deep, so a page that returns only `alternates.languages` keeps its canonical. It calls `getManagedMetadata` with the default `favicon: 'metadata'`.
 
 ### A/B-tested titles and descriptions
 
@@ -221,10 +243,6 @@ Renders the internal links Sonor has for `path` at that position, or nothing whe
 
 `limit` defaults to 5. `renderLink(link)` replaces the default `<a>`, and `className` replaces the default `sk-internal-links sk-internal-links--{position}`. `site` pins the sub-site host (see [Multi-site projects](#multi-site-projects)).
 
-## Content blocks: `<ManagedContent>` (deprecated)
-
-Deprecated in 7.1 and removed in 8.0. Page copy is [managed copy](../slots/README.md) now: wrap the text in `<ManagedSlot>` or `<ManagedRichText>` and edit it in Sonor under Website → Content, with drafts, history and Edit on page. Sonor no longer creates content blocks, so `ManagedContent` renders its `fallback`.
-
 ## Multi-site projects
 
 One Sonor project can serve many domains (example.com plus its city microsites). Managed FAQs and internal links can be project-wide (every host) or tagged with one host (that host only). `ManagedFAQ` and `ManagedInternalLinks` send the site host with every read, so each microsite gets its own rows plus the project-wide ones, never a sibling's.
@@ -235,7 +253,6 @@ The host resolves from `NEXT_PUBLIC_SITE_URL`, which every microsite already set
 <ManagedFAQ path="/contact" site="charlotte.example.com" />
 await getFAQData('/contact', 'charlotte.example.com')
 await getInternalLinks('/contact', { position: 'bottom', site: 'charlotte.example.com' })
-await getContentBlock('/contact', 'hero', 'charlotte.example.com')
 ```
 
 When no host resolves, `site` is left off and the API answers for the project's primary domain. Single-site projects and older API servers ignore it.
@@ -288,7 +305,6 @@ Every component above is built on these. They're server-only, take paths rather
 | `getSchemaMarkups(path, { includeTypes?, excludeTypes? })` | Schema rows (`schema_type`, `schema_json`, ...). `excludeTypes` also prunes matching nodes inside each row. |
 | `getFAQData(path, site?)` | The FAQ (`title`, `description`, `items`, `include_schema`), or `null` |
 | `getInternalLinks(path, { position?, limit?, site? })` | Link rows |
-| `getContentBlock(path, section, site?)` | The content block, or `null` |
 | `getABTest(path, field)` | The running test for that field, or `null` |
 | `recordABImpression(testId, variant, sessionId?)` | `void` |
 | `getRedirectData(path)` | The raw redirect row, or `null` |

package/src/sync/README.md

@@ -1,6 +1,6 @@
-# Sync (Booking) — `@sonordev/site-kit/sync`
+# Sync (Booking): `@sonordev/site-kit/sync`
 
-Embeddable booking/scheduling widget — like Calendly, built into Sonor. Appointments, consultations, classes.
+Embeddable booking/scheduling widget, like Calendly, built into Sonor. Appointments, consultations, classes.
 
 ## Usage
 

package/src/website/README.md

@@ -129,5 +129,6 @@ import { PopupBlocks } from '@sonordev/site-kit/website/popups'
 Engage was retired in Sonor, and its popups with it. Popups made in Engage
 Studio (a `design_json` without blocks) aren't drawn by site-kit 7.2 or later;
 make them again in Website → Popups & Banners. `@sonordev/site-kit/engage`
-still builds through 7.x: its `EngageWidget` draws `SitePopups` and the
-website chat.
+was removed in site-kit 8: `SiteKitLayout` mounts `SitePopups` and the website
+chat for you, and `npx sonor-setup codemod --write` moves the names that have
+a home.

package/dist/AnalyticsProvider-DJQA66AG.js

@@ -1,11 +0,0 @@
-export { AnalyticsProvider, useAnalytics, useAnalyticsOptional, useTrackEvent } from './chunk-MKMD2HJW.js';
-import './chunk-LCDVPAMR.js';
-import './chunk-24QZEO3Q.js';
-import './chunk-L2V5PUFN.js';
-import './chunk-GJWI74ZZ.js';
-import './chunk-43OCZ3JA.js';
-import './chunk-EKBEOXTH.js';
-import './chunk-BEBR4OJD.js';
-import './chunk-WGG6GTKW.js';
-import './chunk-56KNHB4U.js';
-import './chunk-PKBMQBKP.js';

package/dist/ManagedForm-JRZAJ7SZ.js

@@ -1,16 +0,0 @@
-export { ManagedForm } from './chunk-WGIDC6QP.js';
-import './chunk-ZKHI4E2B.js';
-import './chunk-DXO6SBMD.js';
-import './chunk-4NTBQNHA.js';
-import './chunk-EPT6FJUY.js';
-import './chunk-Q6E4OPGG.js';
-import './chunk-C2FZBUSS.js';
-import './chunk-5SQK3D53.js';
-import './chunk-HW7B43E5.js';
-import './chunk-NJCTQH2P.js';
-import './chunk-L2V5PUFN.js';
-import './chunk-GJWI74ZZ.js';
-import './chunk-BEBR4OJD.js';
-import './chunk-WGG6GTKW.js';
-import './chunk-56KNHB4U.js';
-import './chunk-PKBMQBKP.js';

package/dist/SiteChat-EGEZJJVV.js

@@ -1,5 +0,0 @@
-export { SiteChat } from './chunk-RDPW4D33.js';
-import './chunk-27FISYK4.js';
-import './chunk-43OCZ3JA.js';
-import './chunk-EKBEOXTH.js';
-import './chunk-PKBMQBKP.js';

package/dist/SiteDesignReporter-YEEWJKWN.js

@@ -1,11 +0,0 @@
-export { SiteDesignReporter } from './chunk-MRQ2U4LZ.js';
-import './chunk-I2YX3HVD.js';
-import './chunk-IHG36STL.js';
-import './chunk-YC7ELZS3.js';
-import './chunk-S22FSH7C.js';
-import './chunk-43OCZ3JA.js';
-import './chunk-EKBEOXTH.js';
-import './chunk-BEBR4OJD.js';
-import './chunk-WGG6GTKW.js';
-import './chunk-56KNHB4U.js';
-import './chunk-PKBMQBKP.js';

package/dist/SitePopups-LQBIXIFV.js

@@ -1,10 +0,0 @@
-export { SitePopups } from './chunk-YJLS6JBI.js';
-import './chunk-27FISYK4.js';
-import './chunk-24QZEO3Q.js';
-import './chunk-GJWI74ZZ.js';
-import './chunk-43OCZ3JA.js';
-import './chunk-EKBEOXTH.js';
-import './chunk-BEBR4OJD.js';
-import './chunk-WGG6GTKW.js';
-import './chunk-56KNHB4U.js';
-import './chunk-PKBMQBKP.js';

package/dist/SitemapSync-LSZ2EYOF.js

@@ -1,8 +0,0 @@
-export { SitemapSync } from './chunk-T4DLETKR.js';
-import './chunk-YVKRYQRG.js';
-import './chunk-43OCZ3JA.js';
-import './chunk-EKBEOXTH.js';
-import './chunk-BEBR4OJD.js';
-import './chunk-WGG6GTKW.js';
-import './chunk-56KNHB4U.js';
-import './chunk-PKBMQBKP.js';

package/dist/chunk-24QZEO3Q.js

@@ -1,41 +0,0 @@
-'use client';
-import { uuid } from './chunk-GJWI74ZZ.js';
-import { useState } from 'react';
-
-function getOrCreateVisitorId() {
-  if (typeof window === "undefined") return "";
-  let visitorId = localStorage.getItem("_sk_vid");
-  if (!visitorId) {
-    visitorId = uuid();
-  }
-  localStorage.setItem("_sk_vid", visitorId);
-  return visitorId;
-}
-function getOrCreateSessionId(timeoutMinutes = 30) {
-  if (typeof window === "undefined") return "";
-  const now = Date.now();
-  const timeoutMs = timeoutMinutes * 60 * 1e3;
-  const existingSession = sessionStorage.getItem("_sk_sid");
-  const lastActivity = sessionStorage.getItem("_sk_stime");
-  if (existingSession && lastActivity) {
-    const elapsed = now - parseInt(lastActivity, 10);
-    if (elapsed < timeoutMs) {
-      sessionStorage.setItem("_sk_stime", now.toString());
-      sessionStorage.setItem("_sk_sid", existingSession);
-      return existingSession;
-    }
-  }
-  const newSession = uuid();
-  sessionStorage.setItem("_sk_sid", newSession);
-  sessionStorage.setItem("_sk_stime", now.toString());
-  return newSession;
-}
-function useSiteKitIdentity() {
-  const [identity] = useState(() => ({
-    visitorId: getOrCreateVisitorId(),
-    sessionId: getOrCreateSessionId()
-  }));
-  return identity;
-}
-
-export { getOrCreateSessionId, getOrCreateVisitorId, useSiteKitIdentity };

package/dist/chunk-BU66S5B7.js

@@ -1 +0,0 @@
-