@sonordev/site-kit 7.1.1 → 7.2.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # @sonordev/site-kit Changelog
 
+## 7.2.0
+
+Forms, popups and booking now work the way AI agent browsers, autofill and screen readers expect, Sonor's schema can't put a template's placeholders on a live page, and the retired Engage module is gone from the kit. No site changes needed: update the package and rebuild.
+
+### Engage is gone
+
+Engage was retired in Sonor; its chat lives in Messages and its popups in Website. The kit now matches.
+
+- **Chat and popups load on their own.** Website chat is `@sonordev/site-kit/chat` and popups are `@sonordev/site-kit/website/popups`. `SiteKitLayout` mounts `SiteChat` and `SitePopups` as separate deferred siblings, so a site with popups off never downloads the chat, and the other way round. The popups entry is 16% smaller.
+- **Popups render from blocks only.** A popup made in Engage Studio (one without blocks) isn't drawn: make it again in Website → Popups & Banners. `DesignRenderer` and its types are removed.
+- **New:** `SiteChat` in `./chat`, the standalone chat mount (idle-deferred, gated like analytics), and the popup types under their own names in `./website/popups` (`SitePopup`, `SitePopupConfig`, `SitePopupTargeting`, `SitePopupTrigger`, `SitePopupType`).
+- **`@sonordev/site-kit/engage` still builds through 7.x.** `ChatWidget` and the chat types re-export from it, the popup types keep their old names (`EngageElement` is `SitePopup`), and `EngageWidget` draws `SiteChat` and `SitePopups`. sonor-setup's codemod moves the imports. It's removed in 8.0.
+
+See [Website chat](src/chat/README.md) and [Popups and banners](src/website/README.md).
+
+### Agent-ready forms
+
+- **Autocomplete tokens.** Name, email, phone, company, address and website fields carry the matching `autocomplete` token (`given-name`, `email`, `tel`, `organization`, `postal-code`, and so on), read from the field's CRM destination, then its type, slug or a short label. A field it can't match confidently gets none, since a wrong token is worse than no token.
+- **Accessible wiring.** Every control is tied to its label, help text and error (`aria-describedby`, `aria-invalid`, errors announced with `role="alert"`). Radio and checkbox groups are named by their question, rating stars say which one is chosen, and the required asterisk is hidden from assistive tech, since `required` already says it.
+- **WebMCP.** The interactive form declares itself as a tool (`toolname`, `tooldescription`, and `toolparamdescription` on fields with help text), so a browser that supports WebMCP can offer it to an agent. Forms never set `toolautosubmit`: an agent fills the form and the person still sends it. When an agent does send it, the browser gets the outcome back, and the submission is marked "Sent by an AI assistant" in Sonor.
+- **Nothing typed is lost.** The server-rendered form stays on the page until the interactive one has loaded. What was typed or autofilled carries across, focus stays in its field, and a Send pressed early is held and sent once the form is ready. The server form's Send button is disabled until it can catch a submit, and a visitor without JavaScript is told why the form won't send.
+- **`submit()` returns the outcome.** From `useForm` and the form render props: `{ status: 'sent' | 'invalid' | 'failed' | 'busy' | 'next_step', ... }`. `useForm` also returns `handleSubmit` and `toolAttributes` for custom markup: `<form {...toolAttributes} onSubmit={handleSubmit}>`.
+- `ServerForm`'s `enhance` prop is deprecated and ignored. Every server form upgrades to the interactive one.
+
+See [Forms](src/forms/README.md).
+
+### Popups wait for forms, and every popup is a named dialog
+
+- A popup or toast that opens on its own (immediately, after a delay, on scroll or on exit intent) waits while the visitor is in the middle of a form: focus in a field, a filled-in field not yet sent, or a form that's sending. It opens a moment after they leave the form, or once it's sent. Banners still show at once.
+- A popup is a modal dialog named by its heading: it takes focus, keeps Tab inside, closes on Escape and returns focus where it was. A toast is a named non-modal dialog and a bar is a named region. Close buttons are named "Close".
+
+See [Popups and banners](src/website/README.md).
+
+### BookingWidget
+
+- Day buttons are named with the full date, year included ("Wednesday, October 7, 2026"), and time buttons with the time and date in the booking's time zone. The picked day and time are pressed (`aria-pressed`). Confirm is named with what it confirms ("Confirm 10:30 AM, Wednesday, October 7, 2026"). Every name starts with what its button shows, so voice control still works. What the widget sends is unchanged.
+
+See [Sync](src/sync/README.md).
+
+### SEO and AI visibility
+
+- **Template placeholders never reach the page.** `ManagedSchema`, `LLMSchema` and `generateAllArticleSchemas` drop placeholder nodes from Sonor-supplied schema: a URL on a reserved example domain, a name like "Example" or "Your Business Name", a placeholder phone, a slot like `[Resident Name]` or `{plan.name}`, or an object that's only a note. Real siblings and parents stay, and an article whose stored schema is nothing but placeholders gets its generated schema instead. Your own `additionalSchemas` are never touched. The rule is `@sonordev/contracts/schema-placeholders`.
+- **llms.txt summaries end at a word.** A long page summary ends at a sentence or a whole word, never mid-word.
+
+See [SEO](src/seo/README.md) and [Articles](src/articles/README.md).
+
+### Also
+
+- Built and tested against Next.js 16.3.8, the September 30 security release. Update `next` on each site; the peer range is unchanged.
+- The 7.0 migration guide covers sonor-setup 7.1.2's proxy fix: on a `src/app` site the proxy belongs in `src/`.
+
+## 7.1.2
+
+Docs and comments only; no code changes.
+
+- The module READMEs, `AGENTS.md`, the 7.0 migration guide and the code comments use fictional businesses and example.com in their examples, and describe spam protection without the detail of how it decides.
+- Messages and comments say "Sonor" where they said "Portal", the product's old name. Identifiers are unchanged.
+- This changelog starts at 7.0. Earlier releases are listed in the repository's `docs/CHANGELOG-BEFORE-7.md`.
+
 ## 7.1.1
 
 - BookingWidget now asks every guest for a phone number before confirming a meeting, and sends it with the booking for CRM and Google Contacts use.
@@ -92,13 +151,13 @@ A major: one entry per Sonor module, a root that runs nothing, ESM only,
 Next 16 only, a 0.6 MB package, Cache Components support, and MCP tools
 every site can give agents. Most sites move in one command when next
 touched: `npx sonor-setup codemod --write`, then build. The full guide is
-[docs/MIGRATING-TO-7.md](docs/MIGRATING-TO-7.md). Copies of three fleet
-sites on 4.2, 5.8 and 6.5 were migrated that way and built.
+[docs/MIGRATING-TO-7.md](docs/MIGRATING-TO-7.md). Copies of sites on 4.2,
+5.8 and 6.5 were migrated that way and built.
 
 ### Agents: MCP tools for every site (new)
 
-- **`@sonordev/site-kit/mcp/sonor`**: the tools ten sites hand-rolled, once,
-  over the fetchers the site's own pages use. `sonorMcpServer` /
+- **`@sonordev/site-kit/mcp/sonor`**: the tools sites used to hand-roll,
+  written once over the fetchers the site's own pages use. `sonorMcpServer` /
   `sonorMcpTools`: `get_business_profile`, `list_services`, `search_faq`,
   `find_pages`, `list_articles`, `get_article`, `get_reviews`, plus opt-in
   `list_offerings`, `check_availability` and `get_inquiry_form` +
@@ -113,7 +172,7 @@ sites on 4.2, 5.8 and 6.5 were migrated that way and built.
   with reporting, the server card at both well-known paths, and on Netlify
   the rate-limited relay plus `MCP_TRANSPORT_SECRET`.
 - **A custom MCP server is left alone.** A site that runs its own
-  (upforge.io, re-site-kit sites) gets nothing automatic: `sonor-setup mcp`
+  (a re-site-kit site, say) gets nothing automatic: `sonor-setup mcp`
   writes nothing there, and no llms.txt section is added. Every piece is
   opt-in for it (reporting, some built-in tools, the section). See
   src/mcp/README.md.
@@ -128,7 +187,7 @@ sites on 4.2, 5.8 and 6.5 were migrated that way and built.
 - **ESM only.** `"type": "module"`; each export is `{ types, default }`. Next
   and the kits are unaffected; Node 20.19+/22.12+ `require()` it, which
   covers a `next.config.ts`. `engines.node` is `>=20.19`.
-- **Next 16 only** (`next` peer `^16`; every fleet site is on 16).
+- **Next 16 only** (`next` peer `^16`).
 - **The root entry is types-only** (plus `SITE_KIT_VERSION`). `BookingWidget`
   → `./sync`, `AffiliatesWidget`/`useAffiliates` → the new `./affiliates`,
   commerce → `./commerce`, `ManagedImage` → `./website/images`, signal →
@@ -166,10 +225,9 @@ sites on 4.2, 5.8 and 6.5 were migrated that way and built.
   render stamp is set on mount). The integration harness builds the fixture
   both ways.
 - **`@sonordev/contracts`**, a new dependency-free package: the rules
-  site-kit shares with sonor-api, signal-api and the dashboard (popup
-  blocks, site hosts, seo_pages resolution, title quality, llms sanitizers,
-  honeypot, fleet, slots, portfolio). site-kit's `*/contract` entries are
-  the same code; the APIs' byte-identical copies and drift tests are gone.
+  site-kit shares with the Sonor APIs and the dashboard (popup blocks, site
+  hosts, seo_pages resolution, title quality, llms sanitizers, forms, fleet,
+  slots, portfolio). site-kit's `*/contract` entries are the same code.
 - **`sonor-setup codemod`** moves `middleware.ts` to `proxy.ts` (Next 16's
   rename) with `createMiddleware` → `createProxy`, deterministically and
   offline. It flags a file that sets `runtime` instead of moving it.
@@ -192,3419 +250,3 @@ sites on 4.2, 5.8 and 6.5 were migrated that way and built.
 - `SiteKitLayout`'s `engage` prop, alongside `chat` and `popups`.
 - Deprecated options sites still pass (`contentSignals`, `nativeReturnTo`,
   `ManagedScripts`) are no-ops until 8.0.
-
-## 6.6.0
-
-### Popups in the site's own design (Website → Popups & Banners)
-
-- **Blocks.** A popup is now an ordered list of blocks (heading, formatted
-  text, image, button, divider), drawn by one renderer, `PopupBlocks`, in
-  the site's own colors, fonts and corners. It's an accessible dialog
-  (labelled, focus kept inside and handed back, Escape closes), and it
-  re-sanitizes text when it renders. `EngageWidget` prefers blocks when
-  sonor-api sends them and lazy-loads the whole path, so the engage bundle
-  grows 0.7%. Kits before 6.6 keep drawing `design_json`, which sonor-api
-  still sends.
-- **The site's design, measured.** `SiteDesignReporter` (mounted by
-  `SiteKitLayout`) reads the rendered home page at idle: page background,
-  the text most copy is set in, the accent its buttons share, fonts, radius
-  and card surfaces. It reports them to Sonor when they change (or weekly),
-  never from a cross-origin frame or localhost, so the popup builder
-  previews in the same design. `--sk-*` variables count as declared, and a
-  new `design` prop declares anything outright (`{ primary: 'var(--brand)' }`),
-  keeps it on the site (`{ report: false }`) or turns it off (`false`).
-- **`@sonordev/site-kit/website/contract`**: the pure contract (design
-  tokens, popup blocks, the text sanitizer, URL rules) that sonor-api and
-  the dashboard share.
-
-### One entry per Sonor module
-
-Someone who knows the dashboard can now guess the import path:
-
-- `./website/{popups,images,slots,cms,landing,cta-bar}` (Website);
-- `./seo/{sitemap,robots,indexnow,redirects,og,llms}` and
-  `./seo/{meta,pages}/contract` (SEO);
-- `./chat` (Website chat, out of `./engage`).
-
-Each is a re-export of the module's existing home. **Old paths keep
-working** and resolve to the same module; the agent manifest marks them
-deprecated with their new home. `SiteKitLayout` gains `chat` and `popups`
-props; `engage` stays as an alias (`engage={false}` still turns both off).
-
-### Fixes
-
-- **Reputation:** `fetchReviews` kept one cache for every call, so a second
-  caller with different options (another service, a limit, featured-only)
-  got the first caller's reviews. The cache is now keyed by key and URL, and
-  a keyless call never reads it.
-
-## 6.5.0
-
-### Portfolio: client-reported numbers
-
-`@sonordev/site-kit/portfolio/contract` now owns **metric provenance**: the
-three sources a case-study number can have, and what each may do.
-
-- **`measured`**: we measured it. **`reported`**: the client told us, and a
-  named person at the client stands behind it. **`estimated`**: a projection.
-  (`METRIC_SOURCES`, `MetricSource`, `isMetricSource`.)
-- **A reported number must say whose it is.** It carries
-  `reportedBy: { name, role?, organization, date }`, and
-  `metricSourceProblem()` refuses one without it (or with an unknown source).
-  The KPI JSON schema enforces the same with `if`/`then`.
-- **What may headline** (a hero tile, a gallery card, a carousel, a social
-  post): `isHeadlineMetric()`: measured, or reported with a name behind it.
-  Never an estimate, never an unlabelled legacy number.
-- **Credits:** `formatAttribution()` gives "Reported by Scott Mann, Director
-  of Business Development, True Power Systems, September 25, 2026";
-  `shortAttribution()` gives "per True Power Systems"; `metricSourceLabel()`
-  gives the badge text.
-- **`carryReportedMetrics()`** keeps a person's reported numbers through a
-  regeneration. The generator can't author one (it can't see a client's
-  books), so a rewritten hero would otherwise erase them.
-
-Additive: nothing changes for a site until it reads `source: 'reported'`.
-sonor-api keeps a byte-identical mirror, guarded by the same test vectors.
-
-### Showcase frames: tell the embedder, stay out of its page
-
-Agency case studies show a client's live site in device frames over a
-screenshot of it. The embedder can't tell from outside whether a
-cross-origin frame painted (its document reads as null either way), so the
-screenshot never gave way.
-
-- **`announceFrameReady()`**: a page framed by another origin posts
-  `{ type: 'sonor:frame-ready', v: 1 }` to its parent once it has loaded and
-  painted. `SiteKitClientProviders` calls it; nothing to configure. At the
-  top level or in a same-origin frame it does nothing.
-- **`FRAME_READY_MESSAGE` / `isFrameReadyMessage`** are exported from
-  `@sonordev/site-kit/portfolio/contract` for the embedder's side.
-- **Engage stays out of someone else's page**: no popups or chat launcher in
-  a cross-origin frame (the agency's visitor isn't this site's, and the
-  impressions would count here). Opt back in with `engage.allowInFrame`, the
-  same default and switch analytics has had since the send gate.
-
-## 6.4.0
-
-Two pieces of fleet logic that sites were copying between each other now live
-in the kit; nothing changes for a site until it imports them. Author JSON-LD
-does change on upgrade: author pages become ProfilePages and a person carries
-one `@id` across sites (last section). Engage popups also get safer and
-better-behaved (next section).
-
-### Engage: popups, banners and toasts
-
-Popups made in Sonor (Website → Popups & Banners, or by an agent through the
-Sonor MCP) work on every released kit from 3.2 on: Sonor sends the shape the
-widget already renders. This release is the kit's own half:
-
-- **Links and images are checked here too.** `DesignRenderer` follows a
-  button or link only to a site path, an anchor, http(s), mailto or tel, and
-  loads only http(s) or same-site images (`safeActionUrl`, `safeImageSrc` in
-  `engage/element-rules.ts`). Sonor refuses anything else when a popup is
-  saved; before, the renderer would have run a `javascript:` URL.
-- **Clicking the button counts as seen.** The frequency cap was recorded
-  only on close, so a "once" popup came back on the page its own button led
-  to.
-- **Popups leave pages they don't target.** On a client-side navigation the
-  widget re-checks every element and hides one that no longer matches (it
-  used to stay up until closed).
-- **One centred popup at a time.** A second waits until the first is closed;
-  banners and toasts still show alongside.
-- **Buttons take an accessible name** (`props.ariaLabel`), which Sonor sets on
-  the close button.
-- The elements request sends `deviceType`.
-
-### MCP: `@sonordev/site-kit/mcp/transport`, the rate-limited public relay
-
-Netlify rate-limits a native function, never a Next.js route handler, so
-upforge.io (2026-09-21) and gmwlaw.org put their public MCP endpoint behind a
-native function that signs each call and relays it to a Next route. Both sites
-carried the same four files. The new subpath is that relay:
-
-- `createNetlifyMcpRelay(options?)`: the default export for
-  `netlify/functions/mcp.mjs`. HMAC-SHA256 signature in a transport header
-  (overwriting any client-sent value), relay to `/api/mcp-internal` on the
-  deploy permalink, 64 KB body cap, `redirect: 'error'`, 55 s timeout, 502 on
-  upstream failure, `Cache-Control: no-store` and the
-  `netlify-rate-limited-v1` marker on responses. The function file keeps its
-  own literal `config` (`path` + `rateLimit`), because Netlify reads it
-  statically.
-- `protectMcpHandlers(handlers, options?)` for `/api/mcp`: 403 for unsigned
-  calls when `NODE_ENV === 'production'`.
-- `createMcpInternalRoute(handlers, options?)` for `/api/mcp-internal`: 403
-  unless signed, in every environment, then dispatch by method.
-- `hasMcpTransportAuthorization(request, options?)` and `signMcpTransport`,
-  constant-time via `timingSafeEqual`.
-
-Header and label are configurable (`{ header, label }`) and default to
-`x-site-mcp-transport` / `site-mcp-transport-v1`, so a site with live names
-(upforge.io's `x-upforge-mcp-transport`, which its release check asserts) keeps
-them. The entry is Node only, imports no `server-only` (it throws in a plain
-Node function) and is not re-exported from `@sonordev/site-kit/mcp`. Setup and
-the three files: `src/mcp/README.md`, step 5.
-
-### llms: `createSeoRevalidationHandler`, Sonor's SEO webhook
-
-heinrich-law-nextjs and wirsch-law-nextjs each carried
-`lib/seo-revalidation.ts`, the `/api/seo-revalidate` handler Sonor calls when
-a title, description or schema changes. It is now
-`createSeoRevalidationHandler({ secret, revalidatePath, revalidateTag, publicationBasePath? })`
-in `@sonordev/site-kit/llms`, wrapping `createLlmsRevalidateHandler`:
-
-- `Authorization: Bearer` only, constant-time compare. No `?secret=` form.
-- 16 KB body cap, read without buffering past it (413). At most 100 paths and
-  tags; every path must be a same-site local path, even after
-  percent-decoding (400, nothing revalidated).
-- Regenerates the named pages, `/sitemap.xml` and both llms files. A full or
-  tag-only `seo` refresh also regenerates the root layout. Tags expire now
-  (`{ expire: 0 }`).
-- `publicationBasePath` (optional) also refreshes the publication index and
-  feeds, and maps legacy `/blog/...` paths onto the publication root.
-
-`parseSeoRevalidationPayload` is exported for sites that want the validation
-alone.
-
-Three options let a package build on the handler instead of copying it.
-agency-site-kit 0.9.0's portfolio `createRevalidateHandler` is now a
-configuration of it:
-
-- `secret` may be a getter, read on every call, so a route can create the
-  handler once at module scope.
-- `extraPaths`: local paths regenerated on every call (a portfolio hub).
-  Validated when the handler is created.
-- `extendPayload(payload, body)`: add paths or tags from body fields the
-  handler doesn't read (portfolio `slug`/`slugs`, a default tag). Its result
-  is validated like the body, and a throw is a 400, so an extension can't
-  widen what a caller may revalidate.
-
-### llms: `createLlmsRevalidateHandler` compares its secret in constant time
-
-It used `!==`. It now shares the constant-time compare with the SEO handler.
-Behavior is otherwise unchanged, including the documented `?secret=` form.
-
-### Articles: author pages are ProfilePages, one Person `@id` everywhere
-
-Google reads an author page as a profile when it is a `ProfilePage` whose
-`mainEntity` is the `Person`, and it joins mentions of one person when every
-page gives them the same `@id`. The kit emitted a bare `Person` with no id, so
-Ramsey Deal's upforge.io author page, his Forge articles and ramseydeal.com
-described three unlinked people (2026-09-24, while working toward his
-Knowledge Panel).
-
-- **`generateAuthorSchema` now returns a `ProfilePage`** (`@id`
-  `<page>#profilepage`, `url`, `name`, `dateCreated`/`dateModified` from the
-  row) with the `Person` as `mainEntity`. Every current caller (upforge.io,
-  qcr-nextjs, `AuthorPage`) renders it as its own script, so none double-wraps.
-  To embed the person in a bigger graph, use the new
-  **`generateAuthorPersonSchema`**: the same `Person`, without `@context`.
-- **One `@id` rule, `authorEntityId`.** The author row's new `entity_id`
-  (`blog_authors.entity_id`, an absolute https URI such as
-  `https://ramseydeal.com/#person`) wins; otherwise the Person is
-  `<author profile URL>#person`. A relative URL (no `siteUrl`) gives no `@id`.
-  sonor-api serves author rows with `select('*')`, so the column reaches sites
-  with no API change; the author DTOs accept it for writes.
-- **Article bylines share it.** `generateArticleSchema` and
-  `generateClusterArticleSchema` build `author` through the new
-  `generateArticleAuthorNode`, which adds `@id` and the author page `url`. A
-  byline links to an author page only when the site declares one (the new
-  **`authorPages`** routing option) or the row has `author_page_url`: bd-aec,
-  ccc and heinrich have no author pages, and a byline URL that 404s is worse
-  than none. A post with no author now omits `author` instead of emitting a
-  nameless `Person`.
-- **Stored `schema_json` too.** Signal freezes a byline into the post at
-  publish time. `generateAllArticleSchemas` now passes stored nodes through
-  `withArticleAuthorIdentity`, which adds the author's `@id` and `url` to an
-  article node whose `Person` byline has the same name and lacks them. Stored
-  values always win and the row is never rewritten.
-- **`authorPages` routing option**: `true` for author pages at
-  `<publication>/author/<slug>`, or a function for a custom path (upforge.io
-  serves `/author/<slug>` beside a `/theforge` publication).
-- **`AuthorPage` takes `siteUrl`, `siteName` and `jsonLd`.** Without
-  `siteUrl` its JSON-LD had relative URLs and no id. `jsonLd={false}` turns it
-  off for a page that renders `generateAuthorSchema` itself.
-
-Upgrading a site:
-
-- **upforge.io** renders `generateAuthorSchema` *and* `<AuthorPage>`, so each
-  author page carries two author schemas today (one with a relative `url`).
-  Keep the page's own `generateAuthorSchema` (server-side, with `siteUrl` and
-  its root `/author` route) and pass `jsonLd={false}` to `AuthorPage`. Don't
-  hand `AuthorPage` a function `routing.authorPages` from a server page: it's
-  exported from the client-stamped `articles` barrel, and Next can't pass a
-  function to a client component. (Corrected after publish; the first version
-  of this note said to do exactly that.)
-- **qcr-nextjs** (author pages under `/paddlewheel-post/author`): add
-  `authorPages: true` to `paddlewheelRouting` so article bylines link.
-- Set `entity_id` on an author row only for a person with a canonical id of
-  their own (Ramsey: `https://ramseydeal.com/#person`).
-
-## 6.3.5
-
-### Forms: the first submit on a reCAPTCHA form works again
-
-On a cold page, `enterprise.js` fires `onload` while `grecaptcha.enterprise`
-is still Google's loader stub, which has `ready()` and no `execute`.
-`getRecaptchaToken` checked for `execute` before awaiting `ready()`, saw the
-stub, returned no token, and `submitForm` threw "Verification could not be
-completed". The visitor saw "Something went wrong sending your submission" and
-**no request reached Sonor**, so nothing was stored or refused either. It hit
-the first submit on every form of a project with `requireRecaptcha` (upforge.io
-and upforgeapps.com). A second click usually worked, which is why it hid.
-Rania Lombera (Pollard Properties) filled in upforge.io/free-audit on
-2026-09-21, pressed submit once, got the error and booked a call instead.
-
-- `getRecaptchaToken` now loads, awaits `ready()` (bounded), and only then
-  requires `execute`.
-- Every managed form starts loading reCAPTCHA on its first field focus
-  (`preloadRecaptcha`, wired through `FormClient` and `useForm`), so the script
-  is ready long before the submit. Tokens are still minted at submit; they
-  expire after about two minutes.
-
-### Forms: `onSuccess` gets the submitted values
-
-`onSuccess` was typed as `FormSubmission` (a server row with `data`,
-`routing_type`, `is_spam`...) but received Sonor's receipt,
-`{ success, message, submissionId, redirectUrl }`, so `submission.data` was
-always undefined. It now receives `FormSubmitResult`: the receipt plus `id` and
-`data`, the visible values that were sent. `FormSubmission` is now a deprecated
-alias of `FormSubmitResult`, so annotated callbacks keep compiling. Code that
-read `routing_type`, `is_spam` or similar was reading undefined and now fails
-to compile, which is the point: Sonor answers spam and accepted submissions
-identically on purpose.
-
-## 6.3.4
-
-### robots.txt: no more Content-Signal line
-
-`createRobotsTxtHandler` no longer writes a `Content-Signal:` line. Google's
-robots.txt parser reports it as an "Unknown directive" error in Search Console
-(cincinnaticondoconnection.com, 2026-09-22), and robots.txt is the one file
-every crawler has to parse cleanly. 37 fleet sites were sending it.
-
-- `contentSignals` is a deprecated no-op, kept so existing call sites
-  type-check. Remove it when you next touch a site's `app/robots.txt/route.ts`.
-- `formatContentSignals` is deprecated. Express AI-training preferences with
-  `buildAiCrawlerRules({ training: 'allow' | 'block' })`, which every crawler
-  understands.
-- The handler now emits only User-Agent, Allow, Disallow, Sitemap and Host.
-
-## 6.3.3
-
-### Maps: no Google key in page HTML
-
-`SiteKitLayout` no longer copies `NEXT_PUBLIC_GOOGLE_MAPS_API_KEY` (or
-`GOOGLE_MAPS_BROWSER_KEY`) into every page. It shipped the key in the HTML of
-every route, even on sites with no Google map, and Netlify's secrets scanner
-now fails the build on it (cincinnaticondoconnection.com, 2026-09-22).
-
-Client maps already got their key from Sonor first: `fetchMapsConfig()` calls
-`/api/public/maps/config`, which returns Sonor's managed, HTTP-referrer and
-API-restricted browser key, and `fetchNearbyPlaces()` proxies Places through
-Sonor's server key. That's now the only client path, so **a site needs no
-Google key of its own**: delete `NEXT_PUBLIC_GOOGLE_MAPS_API_KEY` from its env.
-A server render can still fall back to that variable if it's set.
-
-- `publishSiteCredential` no longer takes `mapsBrowserKey` or sets
-  `window.__GOOGLE_MAPS_API_KEY__`.
-
-## 6.3.2
-
-### Forms: the no-JavaScript submission path is gone
-
-Managed forms no longer render a native `action` pointing at
-`/api/public/forms/submit-native` or a hidden `_sk_token`, and sonor-api no
-longer has that endpoint. The token sat in the page's HTML, so a bot only had
-to download the page to borrow it: from 2026-08-14 that path took 10,500 bot
-submissions across the fleet and not one real lead.
-
-A form now takes exactly two routes in: a browser running site-kit, or a named
-agent through `/forms/agent-inquiry`.
-
-- `StaticForm` and the classic form render `method="post"` with no `action`,
-  so a click before hydration never puts what someone typed in a URL.
-- `nativeReturnTo` (ManagedForm, FormEnhancer, StaticForm) and `returnTo`
-  (ServerForm) are deprecated no-ops, kept so existing call sites still
-  type-check. Remove them when you next touch the file.
-- `native_token` is gone from `ManagedFormConfig`.
-
-## 6.3.1
-
-### admin-auth: gated API routes and `getRequestSession`
-
-- **`apiPaths`** on `createSonorSso`: API prefixes the middleware should
-  guard (e.g. `['/api/studio']`). Without a session they answer 401 JSON
-  instead of redirecting to the login page. Handlers still check the session
-  themselves; this is the second lock, not the only one.
-- **`getRequestSession(request)`**: the identity from a request's cookie, for
-  middleware and route handlers that have the request in hand.
-
-## 6.3.0
-
-### Sign in with Sonor: `@sonordev/site-kit/admin-auth`
-
-A site's own admin area (a bid tool, a registrations dashboard, a design
-studio, a property editor) can now sit behind a Sonor login with one factory
-instead of a hand-copied auth folder. 4m-lawn-care, legacy-clay-classic and
-the CCG builder each carried their own copy of this handshake, and the copies
-had drifted: different crypto, different session lengths, roles in only one.
-
-```ts
-// lib/sonor-sso.ts
-export const sso = createSonorSso({ paths: '/admin' })
-
-// middleware.ts
-export default createProxy({ before: sso.gate, securityHeaders: true })
-
-// app/api/auth/callback/route.ts
-export const GET = sso.handleCallback
-
-// app/api/auth/logout/route.ts
-export const GET = sso.handleLogout
-export const POST = sso.handleLogout
-```
-
-- **`gate`** plugs into `createProxy({ before })`. It redirects to the login
-  page with a `return_to`, marks the area `noindex`, and returns nothing for
-  public pages so redirects and AI discovery headers still run there.
-- **`getSession()`** is the check for server components, server actions and
-  API routes. The middleware matcher skips `/api/*`, so every API route that
-  exposes admin data has to call it.
-- **`getLoginUrl({ returnTo })`** builds the `app.sonor.io/sso/grant` link.
-  The project id comes from `SONOR_API_KEY`; no extra env var.
-- **`handleCallback`** verifies the token with Sonor, which rejects tokens
-  issued for any other project, and sets a signed httpOnly cookie. The
-  return path is limited to the gated area, so the callback can't be used as
-  an open redirect. The token's URL gets `Referrer-Policy: no-referrer`.
-- Sessions last **30 days** by default (`sessionLifetimeSeconds`). Rotating
-  `SONOR_SESSION_SECRET` (`secretEnv` to rename it) signs everyone out.
-- **`adminEmails`** marks admins within the area. `isAdmin` is computed from
-  the verified cookie on every read, never stored in it.
-- Web Crypto throughout, so the gate runs in Edge middleware. The cookie
-  format matches the pre-kit copies: pass a site's old `cookieName` and
-  `secretEnv` and nobody is signed out by the switch.
-- Outside production the gate lets everyone through as a dev identity
-  (`devBypass: false` to turn that off).
-
-## 6.2.0
-
-### Motion: `<CountUp>`, `scrollIn`, and parallax anchored at load
-
-Two helpers every animated site ended up writing for itself now live in the
-kit. hometown-mortgage and art-realty each carried their own copies.
-
-- **`<CountUp>`** (`@sonordev/site-kit/motion/gsap`): a stat that rolls up
-  to its value as it scrolls into view. Pass the formatted value as its
-  text (`<CountUp>$412,500</CountUp>`); it rolls the first number and keeps
-  the formatting around it. The server HTML is the real text, a stat
-  already on screen keeps its number, and the real text is restored at the
-  end of the roll and by the no-scroll failsafe. `parseCountUp` is exported.
-- **`scrollIn(gsap, el, build, { start })`** (same subpath): the fold check,
-  offscreen arm and 2.5s no-scroll failsafe as one helper for any
-  below-the-fold entrance built in a `useGsap` setup. CountUp is built on
-  it.
-- **`anchor: 'load'`** on `registerScene`, `useScrollScene` and
-  `<Parallax>` / `useParallax`: progress counts from where the page was
-  when the scene first rendered, so an above-the-fold layer (a hero photo,
-  usually the LCP element) renders its rest state and moves only when the
-  visitor scrolls. Before, it jumped on hydration to the frame for its
-  partway-through-the-trip position. The rate is unchanged, and a scene
-  that arms below the fold behaves exactly as before. `SceneAnchor` is
-  exported.
-
-### Motion: `useGsap` loads gsap at idle, not on approach
-
-`useGsap` used to start downloading gsap + ScrollTrigger only once its
-element came within 200px of the viewport. A visitor scrolling at a normal
-pace reached the section before the ~46KB chunk had arrived, so setup ran
-with the section already on screen and its animation was skipped or started
-late.
-
-- gsap now loads once per page at idle: after the `load` event, on the next
-  `requestIdleCallback` (2s timeout; Safari, which lacks it, waits 200ms
-  after load). Still off the LCP critical path and clear of hydration.
-- Setup timing is unchanged: it still runs when the element comes within
-  `near` (default `200px 0px`), now with gsap already in hand.
-- Reduced-motion visitors still never download gsap.
-- New export `whenIdle()` from `@sonordev/site-kit/motion/gsap`: the idle
-  gate itself, for anything else that should wait for the same moment.
-
-Echo now follows the project's **Enable Chat Widget** switch in Sonor. Before,
-the launcher showed on every site with engage on, whatever the switch said:
-`ChatWidget` fetched the setting and never read it.
-
-- A project that never saved chat settings counts as on (its config has no
-  `is_enabled`, and only an explicit `false` hides Echo), so no site that
-  shows Echo today loses it. As of this release no project has switched it
-  off.
-- `ChatWidget` renders nothing until the widget config arrives, so a
-  switched-off site never flashes a launcher. If the config can't be fetched,
-  the launcher stays hidden.
-- Availability polling starts only once Echo is on, instead of on every page
-  of every engage site.
-- `isChatEnabled(config)` is the one visibility check. The Echo UI moved into
-  `EchoChat`, which `ChatWidget` mounts; it isn't part of the public API.
-
-### Echo: a chat started from a quick-action chip showed the visitor's message twice
-
-Clicking a welcome quick-action chip on an AI-mode widget drew the visitor's
-message as two consecutive bubbles, on every Echo site. `startChat` drew the
-bubble, then the session-init effect drew it again before sending it to Echo.
-Only the doubled bubble was wrong: Echo was called once and answered once.
-Live-chat (socket) mode never doubled; the server doesn't echo a visitor's own
-message back.
-
-- One rule now, in `src/engage/chat-messages.ts`: a visitor's bubble is drawn
-  once, when they act. Delivery afterwards only sends. `openingMessages`
-  draws the chip's message when the chat begins; `deliverOpeningMessage`
-  sends it once the session is up and has no way to draw it.
-- The composer, the `suggest_action` chips and the opening message share one
-  AI turn, `askEcho`. Three copies of the reply/error/loading handling
-  collapsed into one, and the composer's "talk to a person" offer now reads the
-  message it just sent instead of the visitor's previous one.
-- Regression tests replay the opening sequence against a plain transcript
-  (the package's vitest has no DOM), in AI and live mode, plus a source guard
-  that fails if `ChatWidget` builds a visitor bubble or an Echo error reply
-  inline again. Checked in Chrome against the old code: two bubbles before,
-  one after.
-
-## 6.1.3
-
-### `CtaBarAction` is polymorphic on `as`
-
-`as` forwarded every prop to the component at runtime, but the props type
-only admitted anchor and button attributes. `<CtaBarAction
-as={ScheduleTourButton} values={tourValues}>` failed with TS2322, so the MDG
-unit pages wrapped the tour button in a local adapter just to bind `values`.
-
-- `CtaBarActionProps<C>` is generic on `as`. With `as`, the action takes that
-  component's own props, required ones included, minus the five it owns
-  (`icon`, `variant`, `collapse`, `children`, `className`). A Next `Link`
-  takes its object `href` and `prefetch`; forgetting a prop the component
-  requires is now a type error instead of a silent runtime gap.
-- Without `as`, nothing changes: the same anchor and button attributes as
-  6.1.0, and unknown props still error.
-- Type-level tests in `src/cta-bar/cta-bar.test-d.tsx`. `pnpm test` now runs
-  vitest's typecheck mode for `*.test-d.ts[x]` files, so type contracts are
-  guarded by the same command as the rest (checked with a negative control:
-  the 6.1.2 typing fails seven assertions). `tsconfig.build.json` keeps them
-  out of `dist`.
-
-## 6.1.2
-
-Echo drew the raw brand colour as text on its light panel. On a light brand
-that failed WCAG AA: Gunning Homes' `#d4af37` gold sat at 2.1:1, and the
-fleet's teal `#39bfb0` at 2.3:1. It predates 6.1 (the solid white window had
-the same problem).
-
-- One helper, `src/engage/brand-color.ts`, now derives Echo's brand text
-  colour. It's the raw brand when that already clears 4.5:1 against the panel
-  and its brand-tinted chips; otherwise the brand is pulled toward black on a
-  light panel, or white on a dark one, only as far as AA needs. Gold becomes
-  `#887023` (4.8:1), keeping its hue. Blues, reds and other dark brands are
-  unchanged, and so are dark panels whose brand already reads (the TPS power
-  studies microsites' navy Echo).
-- It covers the welcome quick-action chips, the "Or call us at" phone link,
-  markdown link buttons, suggestion chips (Echo's and the inline
-  `suggest_action` ones), the "Talk to a person" button and the sent-message
-  check. Fills (launcher, avatar tile, the visitor's bubbles, buttons) keep
-  the raw brand.
-- `--sk-primary` in `rgb()`, `hsl()` or 3-digit hex is now read properly.
-  Before, a non-hex brand put white text on a light brand's buttons and
-  bubbles and tinted every chip with the default blue.
-- The inline Echo form's submit button drew white text on the brand
-  regardless of the brand; it now follows the rest of the widget (dark text
-  on a light brand).
-- Colour parsing moved to `src/shared/color.ts`, shared with the brand-profile
-  extractor, instead of two parsers that disagreed.
-
-## 6.1.1
-
-Found piloting 6.1.0 on gunning-homes.
-
-- The CTA bar, its spacer, the Echo launcher and the Echo window stay off
-  paper (`@media print`). Fixed chrome repeats on every printed sheet;
-  sites were hiding it by hand.
-- Echo's reduced-motion rule moved into a hoisted `sk-echo` stylesheet, so it
-  is present before the window first opens.
-- The fixture app now also renders a page-level bar inside `<main>` (how
-  gunning-homes and the MDG unit pages use it), so the axe gate covers both
-  placements. It passes: axe 4.13 retired `landmark-complementary-is-top-level`.
-
-## 6.1.0: Liquid Glass
-
-One glass material for the kit's floating chrome (`src/shared/glass.tsx`),
-and the two places visitors touch it most: a new mobile CTA bar, and Echo.
-No breaking API changes. Echo looks different on every site that bumps.
-
-### New: `@sonordev/site-kit/cta-bar`
-
-`<CtaBar>` + `<CtaBarAction>`, the floating glass capsule that keeps a site's
-one or two highest-intent actions a thumb away on phones. It replaces the
-fleet's eleven hand-rolled sticky mobile bars, each of which had solved a
-different part of the same problem:
-
-- `hideOver`: steps aside while the form it points at (or the footer) is on screen.
-- `showAfter`: stays off the hero until the hero CTA scrolls away; server-rendered hidden, so nothing slides over the hero during hydration.
-- `hideWhileTyping` (default on): never sits on the on-screen keyboard.
-- `compactOnScroll` (default on): tightens on the way down, an icon-bearing secondary action folds to its icon, and scrolling up restores it.
-- Lifts the Echo launcher above itself while it's on screen, below its breakpoint, by setting `--sk-echo-offset-bottom`. No site CSS.
-- Reserves its own height at the end of the page (a spacer), so sites drop their `padding-bottom` hacks. Or pass `spacer={false}` and pad the footer with `--sk-cta-bar-space`, published on `<html>` while a bar is present, so the footer's background runs under the bar.
-- Emits `cta_click` through the standalone analytics dispatch.
-- Server component with a childless behaviour island: a server layout passes `as={Link}` directly. About 4.4 KB gzipped, glass and analytics included.
-- Solid when there's no `backdrop-filter`, reduced transparency or more contrast; no transitions under reduced motion; visible with JS off.
-
-### Echo: the Liquid Glass update
-
-- The launcher is brand-tinted glass, and its icon turns dark on a light brand (it was always white).
-- The chat window is a glass panel that grows out of the launcher's corner. The header is part of the sheet with a brand wash instead of a solid gradient block; the brand lives on the avatar tile, the visitor's bubbles, the send button and the launcher.
-- Bubbles and the composer stay near-opaque on the glass, for contrast.
-- The launcher glides when a CTA bar lifts it.
-- Chat input, offline form and inline Echo form fields are 16px, so iOS Safari no longer zooms the page when a visitor taps into them.
-- `--sk-glass-panel-opacity: 100%` restores a solid window; `--sk-glass-brand-opacity: 100%` a solid launcher.
-
-## 6.0.1
-
-### Build-time llms.txt links clusters to the site's own article path
-
-6.0 moved the default publication path to `/articles`. `generateLLMsTxt`
-took a `publication` option, but the two writers that run at build time
-didn't pass one, so a site whose articles live at `/blog` or `/insights`
-would get topic-cluster links to `/articles` whenever llms.txt falls back to
-local generation.
-
-- `createSitemap({ publication: { basePath: '/insights' } })` passes it to
-  the build-time llms.txt write.
-- `writeLLMsTxtToPublic({ publication })` passes it through.
-- `sonor-register-sitemap --write-llms --publication /insights` for
-  postbuild writers.
-
-## 6.0.0
-
-### Breaking: blog is now articles
-
-Sonor publishes articles from Broadcast, and site-kit's API says so.
-`@sonordev/site-kit/blog*` is `@sonordev/site-kit/articles*`, every
-Blog-named export has an Article or Publication name, the default publication
-path is `/articles`, and default CSS classes are `.sk-article-*`. No aliases.
-The full old-to-new table and the one thing that moves URLs (`basePath`) are
-in MIGRATION.md.
-
-- The `articles` client barrel no longer exports async server components;
-  they're in `articles/server-ui`. That removes the last exception in the
-  client-entry boundary test.
-- Reads go to `/public/articles/*` on the Sonor API.
-- llms.txt topic-cluster links use the site's publication routes (new
-  `publication` option) instead of a hardcoded `/blog/<slug>`.
-- Author Person schema URLs follow the publication's author route.
-
-### IndexNow key route: Bing hears about an article the moment it's published
-
-Sonor now submits every published, edited or removed article to IndexNow
-(Bing, and through it ChatGPT search and Copilot, plus Yandex, Seznam and
-Naver). IndexNow only accepts that from a host that serves the project's key,
-and Sonor checks the host first, so a site gets it by adding one file:
-
-```ts
-// app/indexnow.txt/route.ts
-export { GET } from '@sonordev/site-kit/robots/indexnow'
-```
-
-The key comes from Sonor with the site's `SONOR_API_KEY` and isn't a secret.
-Without the route the site is skipped, never refused.
-
-### Image sitemap and Google News sitemap for articles
-
-- `generateArticleSitemap` adds each post's featured image as an `images` entry,
-  which Next renders as `<image:image>`.
-- `createSitemap`'s `additionalPaths` items take `images` (relative URLs
-  resolve against the site) and `lastModified`, so a site listing its own
-  articles gets an image sitemap and real modified dates instead of the build
-  time.
-- New `generateNewsSitemap({ siteUrl, publicationName, ...routing })` returns a
-  Google News sitemap of posts published in the last two days. Serve it from
-  `app/news-sitemap.xml/route.ts` and list it in robots.txt. The pure builder
-  (`buildNewsSitemapXml`) is exported for sites with their own post source.
-
-### Feeds carry the 20 newest posts, not 100
-
-`generateRssFeed` and `generateAtomFeed` put every post's full HTML in the
-feed, and fetched up to 100 posts, so an active blog's feed ran past half a
-megabyte, where some readers and aggregators stop fetching. They now carry the
-20 newest (`maxItems` to change it); older posts stay in the sitemap. A `]]>`
-inside a post body no longer ends the CDATA section early and breaks the feed.
-
-## 5.8.3
-
-### AEO components and SpeakableSchema get a client-safe entry point
-
-`@sonordev/site-kit/llms` is one barrel that also exports `writeLLMsTxtToPublic`
-and the `createLLMsTxtHandler`/`createLLMsFullTxtHandler` route handlers, both
-of which import Node's `fs` at module scope. Importing `AEOBlock` (or any AEO
-component, or `SpeakableSchema`) from a Client Component pulls that whole
-module graph into the browser bundle, and `fs` doesn't resolve there — the
-build fails outright, even though the component itself never touches the
-filesystem. Hit on spade-nextjs, cincy-mahjong-club-nextjs, and the MDG
-apartment sites' apply page during the 2026-09-16 fleet AEO rollout.
-
-- New `@sonordev/site-kit/llms/client` exports the ten `AEO*` components,
-  `SpeakableSchema`, `createSpeakableSchema`, and their types, nothing else.
-  Import AEO markup from here in a Client Component; keep using
-  `@sonordev/site-kit/llms` from server components and route handlers.
-
-### commerce/server's helpers were 404ing: missing `/api` segment
-
-Every server-side commerce helper (`getOfferingBySlug`, `getOfferings`,
-`getOfferingPaths`, `getUpcomingEvents`, and their `*Result` variants)
-fetched `${apiUrl}/public/commerce/...`, missing the `/api` segment the Sonor
-API actually serves. Every other module in the package, including
-`commerce/api.ts` (the client-side fetcher for the same data), already used
-`/api/public/commerce/...`; only the server helpers had drifted. Two sites
-(gwa-nextjs, moore-canine-co-nextjs) had worked around it with a raw fetch
-instead of these helpers.
-
-- Fixed the endpoint on all seven calls. Added a test asserting the real URL
-  for each exported helper — the existing regression tests mocked `fetch`
-  without ever inspecting what was passed to it, so the wrong path shipped
-  with a green suite.
-
-### ManagedSchema stopped double-counting a breadcrumb inside a managed `@graph`
-
-Its auto-generated BreadcrumbList only fires when none of the combined
-schemas already has one, but the check looked for `@type === 'BreadcrumbList'`
-on the top level only. Sonor's `managed_schema` and entity-enhanced schemas
-are frequently shipped as one `{ "@graph": [...] }` wrapper rather than a flat
-node, so a breadcrumb nested inside the graph was invisible to it —
-art-realty-nextjs was shipping three BreadcrumbList blocks on some pages (its
-own component's, Sonor's, and the kit's synthesized one) before this was
-caught.
-
-- The check now looks inside `@graph` too, and treats a string-array `@type`
-  as a match.
-
-## 5.8.2
-
-### A form that changes slug mid-fill no longer wipes what was typed
-
-`useForm` re-seeded its values from scratch every time a config arrived, so a
-form whose slug changed while someone was filling it in lost everything they
-had entered. That is not an exotic case: notification recipients are per-form,
-so a site that routes to different inboxes has to put a picker on the form and
-swap which managed form receives the lead. Choosing from that picker emptied
-the name, email and phone the visitor had already given.
-
-- Values now carry across a config change, for any slug the new config still
-  has. Precedence, weakest first: config defaults, the caller's
-  `initialValues`, then anything already entered.
-- A field the new config does NOT have is dropped rather than carried, so a
-  value can't be submitted invisibly on a form that never asked for it.
-- An entered empty string counts as entered, so a default cannot silently
-  refill a field the visitor deliberately cleared.
-- Errors are pruned the same way. A message on a field that is gone could
-  never be cleared: nothing on screen corrects it and validation never
-  revisits it.
-- The precedence lives in `forms/form-values.ts` as a pure function, following
-  `field-rules.ts`, so it is tested on its own. `FormClient` does not use it:
-  its config comes from a prop and never changes.
-
-## 5.8.1
-
-### The published package is 40% smaller
-
-`sonor-setup` bundles Babel for its migrate codemods, and the source maps for
-that bundle — maps describing Babel's own source, which no consuming site ever
-steps through — were 2.4 MB of the tarball's 3.9 MB of gzipped maps. Over half
-the package existed to debug the CLI.
-
-- A build step (`scripts/prune-cli-maps.cjs`, run from tsup's `onSuccess`, so
-  `pnpm build` and `prepublishOnly` both get it) drops source maps for output
-  nothing but the CLI can reach. It reads reachability from the emitted files
-  rather than a hand-kept list, and prunes a file only when it is unreachable
-  from every non-CLI entry, so anything shared with the library keeps its map.
-- **Library maps are untouched, embedded sources and all.** A site stepping
-  through analytics, forms or blog in devtools still lands on real site-kit
-  source.
-- Declarations no longer include tests. 109 `.test.d.ts` files were shipping to
-  every site. `tsconfig.build.json` drives the declaration build now;
-  `tsconfig.json` still includes the tests, so `pnpm typecheck` keeps checking
-  them — that's where the compile-time guards live.
-
-Net: **5.92 MB → 3.53 MB packed**, 26.9 → 15.1 MB unpacked, 1540 → 1304 files.
-That's install and CI download time only. Nothing a site ships to browsers
-changes, and the per-entry bundle budgets are unchanged.
-
-## 5.8.0
-
-### Build-time reads stopped replaying an old build's response
-
-`public/llms.txt` could be frozen for months. The build-time fetch behind it
-carried no cache option, so a statically prerendered route stored it in Next's
-Data Cache with a one-year revalidate, and hosts persist `.next/cache` between
-builds — every later build rewrote the same stale file. Found on
-vsfconsultingservices.com on 2026-09-15: nine new pages were missing from a file
-last refreshed on Aug 26, and llms.txt is the file handed straight to AI
-crawlers.
-
-- `shared/fresh-fetch.ts` is the single source of truth for requests that must
-  skip the Data Cache: it calls the original fetch Next keeps on its patched
-  one, so nothing is cached and the route's staticness is untouched.
-  `cache: 'no-store'` (bails static generation) and `next: { revalidate }`
-  (lowers the route's window) are both wrong here, and the file says why. The
-  mint's `resolveFetch` moved here; `server/mint-site-token` re-exports it.
-- `getOptimizedLLMsTxt` always reads fresh. `writeLLMsTxtToPublic` also asks its
-  local fallback for fresh reads (`fresh` on `generateLLMsTxt`), and
-  `createSitemap`'s Sonor reads are fresh during `next build` and unchanged at
-  request time. The llms route handlers keep their one-hour window.
-
-**Rebuild once on this version to refresh a stale `public/llms.txt`.** Nothing
-else to change.
-
-### The llms.txt write can no longer fail a build, and has a home that fits
-
-With reads fresh, the in-route write runs for real on every build, and Sonor
-generates llms.txt with an LLM call that took ~56s for a 147-page site — more
-than the 60s Next allows a prerendered route. The sitemap route then exhausted
-its retries and the build exited.
-
-- The write now gets what's left of a 50s share of the route's budget
-  (`llmsWriteTimeoutMs` still overrides). If Sonor answers in time the file
-  refreshes; if not, the existing file keeps serving, the build passes, and the
-  warning names the fix below. The old 120000ms default outlasted the route.
-- `sonor-register-sitemap --write-llms` (and `--write-llms-full`) writes the
-  file from your postbuild, where no 60s ceiling applies, after the sync the
-  generation reads. It runs on the skip path too, which is the common one for a
-  site whose sitemap route owns the sync. For a guaranteed refresh every build:
-  `optimizedLLMsTxt: false` in `createSitemap`, and
-  `"postbuild": "sonor-register-sitemap --write-llms"`.
-
-### One set of field rules for every form
-
-`useForm` and `FormClient` each carried their own copy of conditional
-visibility (`show_when`) and validation, and the copies had drifted. They now
-share `src/forms/field-rules.ts`, as do the stage and spotlight experiences.
-Where the copies disagreed or were wrong, the merged rules decide:
-
-- **`contains` / `not_contains` read an unanswered field as empty text.**
-  Managed forms read it as the text "undefined", so `contains "n"` showed a
-  field before the visitor had typed anything.
-- **A multi-value answer is searched option by option,** so a needle can't
-  match across two options ("r,W" in Solar, Wind).
-- **An emptied checkbox group or multi-select is unanswered.** Ticking then
-  unticking every option left `[]`, which passed `required`, so the form
-  submitted with nothing selected. It also showed the valid tick, and
-  `is_empty` said it wasn't empty.
-- **A number 0 is an answer**: it satisfies `required`, and `min`/`max` apply.
-  An unticked single checkbox is still unanswered for `required` and
-  `is_empty`.
-
-### Forms report field-level drop-off, and abandonment on every kind of leave
-
-The Sonor app's Field Performance card reads `form_analytics.field_interactions`
-and `abandonment_field`, and nothing wrote either: 0 of ~80.6k form sessions on
-2026-09-15. Abandonment only came from `beforeunload`, which iOS Safari never
-fires and which client-side navigation doesn't trigger, so only ~3.8k of those
-sessions were ever marked abandoned.
-
-- **Per-field tracking.** Every managed form (classic, stage, spotlight) now
-  records, per field slug, how often the visitor focused it, how long they
-  spent in it, and whether it held a complete, valid value. That goes out as
-  `fieldInteractions` with the step, complete and abandon calls. The abandon
-  call also carries `abandonmentField`, the field the visitor was on.
-  Requires the matching sonor-api release; older APIs ignore the new keys.
-- **Abandonment is reported on page hide, pagehide, and when the form
-  unmounts** (client-side navigation, a closed modal), no longer on
-  `beforeunload`. The page-hide pair is now one shared helper
-  (`shared/page-leave.ts`) that Signal's flush and scroll depth use too.
-- **Only a visit that touched the form can be abandoned.** The session opens
-  when the form mounts, so a page load where nobody focused a field, typed,
-  or changed step is a view, not an abandonment. Expect `abandoned` rows to
-  mean "started and left" from this release on.
-- A visitor who comes back to a hidden tab and keeps going is reported again,
-  with where they got to, when they leave. A later submit clears it.
-- The completion call now uses `keepalive`, so a form with a `redirect_url`
-  no longer loses it to the navigation.
-- `useForm` and custom renderers (`FormRenderProps`) get `trackFieldFocus` /
-  `trackFieldBlur` to wire to their own inputs. Value changes through
-  `setFieldValue` are tracked without them.
-
-### Brand profile: theme from luminance, and the push is opt-in
-
-The brand-profile extractor called a site "dark" whenever its CSS contained
-the substring `.dark` or `dark:`. That caught shadcn's
-`@custom-variant dark (&:is(.dark *))`, a `--surface-dark:` color token, and
-even `.btn-outline-dark:hover`. Postbuilds on 2026-09-15 relabelled seven
-light sites (background `#ffffff`) as dark in production: Watson, Reinhart
-and the five MDG property sites.
-
-- **Theme comes from the page background's luminance**, falling back to the
-  text color: what `html`/`body` paint, else the usual tokens, with `var()`
-  chains resolved (including Tailwind v4 `@theme`). Reads hex, `rgb()`,
-  `hsl()`, shadcn's bare HSL triples and `oklch()`. Dark-mode overrides
-  (`.dark`, `:root.dark`, `[data-theme=dark]`, `@media
-  (prefers-color-scheme: dark)`) are skipped, so the create-next-app default
-  no longer reads as dark. When nothing resolves, `theme` is omitted rather
-  than guessed.
-- **New `supports_dark_mode`** records what the old check actually detected:
-  the site ships a dark variant.
-- **New `extractor_version: 2`** on every push. The API doesn't trust the
-  `theme` of a push without it.
-- **CSS comments are stripped before scanning.** A `{}` inside a `:root`
-  comment used to end the block early (upforge.io's background never got read).
-- **`sonor-register-sitemap` no longer pushes the brand profile by default.**
-  Pass `--brand-profile` (or `brandProfile: true` to `registerLocalSitemap`)
-  to opt in. Brand data has nothing to do with the sitemap, and a heuristic
-  that runs on every build of every site shouldn't write to production by
-  default. A plain `sonor-register-sitemap --auto-discover` postbuild is back
-  to syncing pages only.
-
-### createSitemap follows `trailingSlash` from next.config
-
-On a site with `trailingSlash: true`, Next 308-redirects `/about` to
-`/about/`. createSitemap didn't know about the setting and emitted `/about`,
-so every entry except `/` redirected, and the sitemap disagreed with the
-site's own canonicals. All five MDG property sites shipped like this
-(found 2026-09-15 by crawling the built sites).
-
-createSitemap now emits the URL the site serves. With `trailingSlash: true`,
-every path ends in `/` except `/` itself, file-like paths (a `.` in the last
-segment, like `/llms.txt` or `/feed.xml`) and `/.well-known/*`, which is the
-same rule Next's own redirects use.
-
-- **No config needed.** The option defaults to the site's next.config value.
-  Next inlines `trailingSlash` into every module it bundles
-  (`process.env.__NEXT_TRAILING_SLASH`), so the kit reads it with no file
-  I/O. Verified on Next 16.3.2 with Turbopack, and with webpack plus
-  `transpilePackages`.
-- **`trailingSlash?: boolean` on `SitemapConfig`** for the rare site that
-  loads the kit outside Next's bundler (`serverExternalPackages`). An explicit
-  value always wins.
-- **The Sonor sync doesn't change.** `register-sitemap` still gets unslashed
-  paths, which is how seo_pages stores them, and dedupe, `exclude`,
-  `priorities` and `intelligentPriority` still match on the unslashed path.
-- **llms.txt links follow the same rule.** Portal builds llms.txt links from
-  `business.website` plus the unslashed page path, so on a `trailingSlash`
-  site each one redirected. `writeLLMsTxtToPublic` now adds the slash to this
-  site's links, both absolute and root-relative, before it writes
-  (createSitemap passes its setting through). `generateLLMsTxt` and the
-  llms.txt route handlers do the same. Links to other hosts, files and the
-  bare origin are left alone. Both take a `trailingSlash` option, which
-  defaults to next.config. Pass it explicitly when you call
-  `writeLLMsTxtToPublic` from a plain-Node postbuild script, where there's
-  no Next bundle to read the setting from.
-- **`ClusterNavigation`'s `trailingSlash` prop** defaults to next.config too,
-  and runs through the same rule.
-
-`## Optional` entries in a generated llms.txt that aren't in the page list
-used to get a slash forced onto them, which redirected on a default site.
-They now follow the site's setting like every other link.
-
-### `sonor-setup doctor` flags sitemap URLs that redirect
-
-The new `sitemap.trailing-slash` check warns when next.config sets
-`trailingSlash: true` and the sitemap lists unslashed URLs. It reads the
-built sitemap (`.next/server/app/sitemap.xml.body`, or the
-`generateSitemaps` shards) when there is one, because that's what crawlers
-get, however the route was written. Without a build, it checks the source for
-a `trailingSlash: false` that overrides next.config.
-
-**What changes on upgrade:** sites with `trailingSlash: true` get slashed
-sitemap and llms.txt URLs on their next build. For sites that wrapped
-createSitemap to add the slash themselves (the MDG property template), the
-wrapper can go. Sites on Next's default see no change.
-
-### A missing blog post is a 404, not a soft 404
-
-`BlogPost` rendered its "Post Not Found" message with HTTP 200, and
-`generateBlogPostMetadata` gave it an indexable "Post Not Found" title, so
-every mistyped or deleted post URL was a soft 404 (vsf-consulting-nextjs
-/insights, 2026-09-15). Both now call Next's `notFound()`, and there's a
-helper for the page:
-
-- **`requireBlogPost(slug, { site? })`** from `@sonordev/site-kit/blog/server`
-  returns the post or calls `notFound()`. Call it from `generateMetadata`:
-  metadata resolves before the page streams, so the status is a real 404.
-- **`generateBlogPostMetadata`** calls `notFound()` for a missing post.
-  `notFound: false` returns the old placeholder, now marked `noindex`.
-- **`BlogPost`** calls `notFound()` for a missing post. `notFound={false}`
-  renders the message instead.
-
-A failed fetch still counts as a missing post, as it always has.
-
-**What changes on upgrade:** unknown post slugs answer 404 with `noindex`.
-Sites that wrote their own `requirePost()` (vsf-consulting-nextjs) can switch
-to `requireBlogPost`.
-
-### `generateBlogPostMetadata({ images: false })` for posts with their own card
-
-The featured image was always declared as `openGraph.images` and
-`twitter.images`, and Next lets declared images beat a route's
-`opengraph-image` file, so a per-post card never shipped. `images: false`
-leaves both keys out entirely. (Not `images: undefined`: Next checks
-`hasOwnProperty('images')`, so even an undefined value hides the card.) The
-doctor flags a post route with an `opengraph-image.tsx` whose page doesn't
-pass it.
-
-### `createOgImage`: the runtime card for `opengraph-image.tsx`
-
-`createOgImageRoute` returns `GET(request, { params })`, but a metadata image
-file is called as `default({ params })`, so watsonhac.com, reinhart and
-vsf-consulting-nextjs each wrote an adapter that built a dummy Request.
-`createOgImage(async (params, { id }) => card | null)` is that file's default
-export: params (and a `generateImageMetadata` id) arrive awaited, null is a
-404. `size` and `contentType` are exported for re-export from the file. Both
-factories render through one function.
-
-### The runtime card fits its title, and its bar is readable
-
-The runtime (Satori) card set the title at a fixed 84px, uppercase, with no
-fitting, so a long post title ran off the card beside the photo. Sites dropped
-the photo past a hand-picked 40 or 50 characters. The title is now fitted over
-the build-time card's range (104px down to the 56px floor) from a width
-estimate, since Satori can't measure, and clipped on a whole line as a
-backstop. When it can't fit beside the photo even at the floor, the photo is
-dropped. A relative `photoUrl`, which Satori can't load, is ignored instead of
-failing the render.
-
-The bar set `theme.text` on `theme.accent`: navy on crimson on watsonhac.com,
-ink on green on reinhart, so both left the bar off. Both cards now pick the
-bar text from one rule (`og/contrast.ts`): `theme.barText` if set, else the
-first of `surface`, `bg`, `text` that reaches 3:1 (WCAG AA for large text) on
-the accent. The build-time card always used `surface`, and keeps it wherever
-it already read. `barText` is new on `OgTheme`, and the runtime theme accepts
-og.config.ts's `theme` as is.
-
-**What changes on upgrade:** per-post cards with long titles shrink instead
-of overflowing. A bar whose `surface` failed on the accent changes color.
-
-### `sonor-setup og`: nested routes, per-URL cards, and cleaner titles
-
-- **Static routes under a dynamic segment get a card.** `properties/[slug]/about`
-  is keyed `/properties/*/about` and titled from its own name. The generator
-  stopped at the first dynamic segment, so 30 Green Bay and SS Oshkosh pages
-  shipped with no og:image.
-- **Per-URL cards.** A `cards` key naming one URL under a dynamic route
-  (`/floor-plans/1-bedroom`, `/properties/tall-pines/about`) renders to
-  `public/_og/<url>.jpg`, with that URL's managed copy under the override.
-  The page declares it with `paramCardImage(path, { config })` from
-  `@sonordev/site-kit/og`, which answers undefined for a page with no entry.
-  The kit owns `public/_og/` and clears it every run. The files end in `.jpg`,
-  so `trailingSlash: true` never redirects them. They need `sharp`. The MDG
-  sites rendered these with their own script (`og-param-cards.mjs`) served by
-  a code route per segment.
-- **Code cards on `trailingSlash` sites.** Next serves `opengraph-image.tsx`
-  at an extensionless URL, which `trailingSlash: true` 308-redirects.
-  `codeCardImage(path)` gives the slashed URL for the page to declare, and the
-  wiring check (og and doctor) flags a code card on such a site whose page
-  doesn't.
-- **A route handler at `opengraph-image/route.tsx` counts as a code card.**
-  The generator wrote `opengraph-image.jpg` beside that folder, which Next
-  refuses to build. It's the shape og/route's own docs suggested.
-- **Titles lose broken suffixes.** A dangling separator (`About Us |`) and a
-  domain after a comma (`Privacy Policy, abbeyglenapts.com`) are dropped like
-  a brand suffix. A hyphen inside a word is no longer a separator: `Custom
-  Walk-In Closets` used to become `Custom Walk`.
-- A `cards` key that matches a dynamic pattern isn't reported as unmatched.
-
-**What changes on upgrade:** sites with static routes under a dynamic segment
-get new `opengraph-image.jpg` files there on the next `sonor-setup og`.
-
-### doctor `og.card` stops guessing
-
-- **managed_og_image is reported only when it's set.** The check warned on
-  every site with per-page cards that `managed_og_image` might override them,
-  whether or not any page had one. `sonor-setup og` now reads it while it
-  titles cards and names the pages that set one. `doctor --online` does the
-  same. Offline, it says nothing.
-- **`summary_large_image` is found where sites set it.** The check grepped the
-  root layout only. It now reads the layout, every page, and what they import:
-  `lib/` helpers through tsconfig paths, and monorepo workspace packages. A
-  `twitter-image` file counts too.
-
-### Answer engines: Amazonbot, MistralAI-User and YouBot
-
-`buildAiCrawlerRules` names three more agents. MistralAI-User (Le Chat
-fetching for a user) and YouBot (You.com search) are retrieval crawlers.
-Amazonbot is a training crawler, because Amazon says what it collects may
-train its models, so `training: 'block'` covers it. vsf-consulting-nextjs kept
-these three in a local `NOT_YET_IN_KIT` list.
-
-`@sonordev/site-kit/robots` now re-exports `buildAiCrawlerRules`,
-`createRobotsTxtHandler`, `formatContentSignals` and the two lists, which is
-where people looked for them. Same functions as `@sonordev/site-kit/llms`.
-The llms README's robots example used a hand-rolled list and now uses
-`buildAiCrawlerRules`.
-
-**What changes on upgrade:** robots.txt built with `buildAiCrawlerRules`
-gains three named groups. No crawler's access changes on an allow-all site.
-
-### The llms discovery header can't come from a layout
-
-The llms README's "Option B" told sites to `export async function headers()`
-from the root layout. That isn't a Next API (`headers()` is a next.config
-option), so those sites sent no Link header, and `sonor-setup geo` passed
-them. The README now recommends `createProxy({ llmsDiscovery })`, with
-`withSiteKitConfig({ llmsTxtDiscoveryLink: true })` for sites without a
-proxy, and geo fails a layout `headers()` export and says why.
-
-### `llmsDiscovery` sends Link to requests with no Accept header
-
-The proxy only sent `Link: rel="describedby"` when the Accept header named
-text/html or `*/*`, so it skipped every request that sends none: curl, link
-checkers, and many crawlers and AI fetchers, which the header is for. A
-missing Accept header means anything, so it counts now. Still skipped:
-non-GET/HEAD requests, Accept headers that name only non-HTML types,
-file-like paths (`/llms.txt`, `/sitemap.xml`), `/api/` routes, and Next's RSC
-navigation requests. The rule is `wantsLlmsDiscoveryLink`, exported from
-`@sonordev/site-kit/llms`.
-
-### `useGsap` loads plugins inside its context
-
-The docs said to `import('gsap/SplitText')` inside the setup. gsap.context
-only records what runs synchronously inside it, so everything the plugin made
-landed outside the context: unscoped, and never reverted on unmount.
-vsf-consulting-nextjs's SplitHeading built a second context to clean up. Pass
-plugins as `options.plugins: { SplitText: () => import('gsap/SplitText') }`.
-They load with gsap (once per page), get registered, and reach setup as
-`plugins.SplitText`, so setup stays synchronous. Setup also gets `context`,
-for anything it has to start later (`context.add(() => ...)`).
-`loadGsapPlugins` and `runGsapSetup` are exported.
-
-### `ManagedSchema` `excludeTypes` drops nested nodes
-
-`excludeTypes` dropped a schema row only when its `schema_type` matched, so a
-FAQPage embedded in a page-level row got through (MDG Green Bay's Georgetown
-and Westbrooke pages, whose FAQPage describes Q&A the pages don't show). An
-excluded type now goes wherever it sits in Sonor's schema: a whole row, an
-`@graph` member, or a nested value like `mainEntity`, in `managed_schema` and
-the entity graph too. A row left empty is dropped. Your `additionalSchemas`
-are never filtered, and `includeTypes` is unchanged.
-
-**What changes on upgrade:** a site that passes `excludeTypes` loses nodes of
-those types that were nested in other rows.
-
-### doctor and geo read helpers and workspace packages
-
-Both read only the file in the site, so wiring in a helper was invisible: geo
-failed three MDG sites whose `app/sitemap.ts` calls the workspace package's
-createSitemap (which turns the build-time llms.txt off) until each restated
-`optimizedLLMsTxt: false`. Route, sitemap, proxy and metadata checks now read
-the file plus what it imports, through one reader (`shared/source-graph.ts`):
-relative imports, tsconfig `paths`, and workspace packages resolved through
-their `exports`. Published packages in node_modules, this kit included, are
-never followed, and comments are ignored, so a helper's doc comment can't pass
-or fail a check.
-
-### `sonor-register-sitemap` sends the site host
-
-The CLI registered pages with no `site`, so on a multi-site project every
-page synced as unattributed rather than as this host's. It now sends
-`NEXT_PUBLIC_SITE_URL`'s host (it loads `.env` and `.env.local`), or the host
-from `--site`. `registerSitemap` and `registerLocalSitemap` on `seo/server`
-had the same gap and take `site` too. All of them and createSitemap's own sync
-build the request in one place (`seo/register-sitemap-request.ts`).
-
-**What changes on upgrade:** a microsite's postbuild sync tags its pages with
-its host. Single-site projects and API servers that predate the site
-dimension ignore it.
-
-## 5.7.2
-
-### Managed FAQs, internal links and content blocks send the site host
-
-Multi-site projects can now have managed SEO content per site. A managed FAQ,
-internal link or content block with no site applies to every host. One tagged
-`bd-charlotte.com` applies only there. The API answers each read with the
-asking host's rows plus the project-wide ones, and treats a read with no site
-as the project's primary domain, so these reads now say which site is asking:
-
-- `getFAQData`, `getInternalLinks` and `getContentBlock` (and so
-  `ManagedFAQ`, `ManagedInternalLinks` and `ManagedContent`) carry `site` in
-  the POST body to `/api/public/seo/faq`, `/internal-links` and `/content`.
-- `getFAQItems` from `@sonordev/site-kit/llms` carries `?site=`, like the
-  other llms reads.
-- The host comes from `resolveSiteHost`, the same resolver the blog, sitemap
-  and llms.txt reads use: an explicit `site`, then the `NEXT_PUBLIC_SITE_URL`
-  host, then `window.location.host` in the browser. When nothing resolves,
-  `site` is left off entirely.
-
-**What changes on upgrade:** nothing for most sites. Every microsite already
-sets `NEXT_PUBLIC_SITE_URL`, so its managed content is scoped on the next
-deploy. Single-site projects get the same rows as before, and API servers that
-predate the site column ignore the field.
-
-To pin a host, pass `site`. The three components take it as a prop. The
-fetchers take it as a new optional last argument:
-`getFAQData(path, site)`, `getInternalLinks(path, { position, limit, site })`,
-`getContentBlock(path, section, site)`,
-`getManagedContentData(path, section, site)` and
-`getFAQItems(projectId, limit, site)`. Existing calls keep working unchanged.
-
-## 5.7.1
-
-### Blog reads send the site host, so each host gets its own posts
-
-Multi-site projects (one Sonor project serving many domains, like bd-aec.com
-and its city microsites) can now have a blog per site. A post with no site is
-project-wide and shows on every host. A post tagged `bd-charlotte.com` shows
-only there. For the API to tell them apart, it has to know which site is
-asking, so every blog read now says:
-
-- Every GET under `/public/blog/*` carries `?site=<host>`: posts, slugs,
-  categories, tags, recent, clusters and authors.
-- The related-posts and view-count POSTs carry `site` in the body.
-- The host comes from `resolveSiteHost`, the same resolver the sitemap sync
-  and llms.txt reads use: an explicit `site`, then the `NEXT_PUBLIC_SITE_URL`
-  host, then `window.location.host` in the browser. When nothing resolves,
-  `site` is left off entirely.
-
-**What changes on upgrade:** nothing for most sites. Every microsite already
-sets `NEXT_PUBLIC_SITE_URL`, so its blog reads are scoped on the next deploy.
-Single-site projects see the same posts as before, and API servers that
-predate the site dimension ignore the param.
-
-To pin a host, pass `site`. Components take it as a prop (`BlogList`,
-`BlogPost`, `BlogSidebar`, `BlogLayout`, `RelatedPosts`,
-`ClusterLandingPage`). Fetchers that take arguments accept
-`{ site }`, for example `getBlogPost(slug, { site })`,
-`getAllBlogPosts({ site })` and `getRelatedInsights(slug, { site })`.
-`getAllBlogSlugs()` and `getAllAuthorSlugs()` stay zero-argument so they can
-still be exported as `generateStaticParams`, and always use
-`NEXT_PUBLIC_SITE_URL`. `BlogPost`'s view counter uses its `site` prop, or
-else the host SiteKitLayout published, the same one analytics tags page views
-with.
-
-The code that appends `site` is shared by the llms and blog reads
-(`sites/site-param`). The post, category and related-posts fetches that were
-copied between `blog/server` and the components now share one module too.
-
-### `normalizeSiteHost` from `@sonordev/site-kit/blog` is now `linkClassificationHost`
-
-The blog module had its own `normalizeSiteHost`, which strips `www.` to decide
-whether a link in a post is internal or external. It shared a name with the
-multi-site `normalizeSiteHost` from `sites/contract`, which keeps `www.`
-because `www.example.com` and `example.com` can be different sites. It's now
-called `linkClassificationHost`, with the same behavior. The old name is still
-exported from `@sonordev/site-kit/blog` as a deprecated alias, so existing
-imports keep working.
-
-## 5.7.0
-
-5.6.1 was versioned in the repo but never published to npm, so its changes ship
-in this release. Everything in this section is new since 5.6.0.
-
-### llms.txt handlers send `X-Robots-Tag: noindex` by default
-
-`createLLMsTxtHandler` and `createLLMsFullTxtHandler` now send
-`X-Robots-Tag: noindex`. llms.txt is a plain-text restatement of pages the site
-already serves as HTML, so a search index that picks it up holds a thin
-duplicate of the site. AI crawlers still fetch it: they request `/llms.txt` by
-convention, and noindex doesn't stop them.
-
-- Pass `noindex: false` to either handler if you want the file in search
-  results.
-- A static `public/llms.txt` (the build-time write) is served straight from the
-  CDN and never runs the handler. Set the header in `netlify.toml`,
-  `public/_headers` or `vercel.json` instead. The llms README has the
-  `netlify.toml` block.
-- Keep llms.txt out of the XML sitemap, which lists indexable HTML pages.
-  `includeLlmsTxtInSitemap` and `includeLlmsFullTxtInSitemap` already defaulted
-  to off. `sonor-setup scaffold` no longer turns them on, and `sonor-setup geo`
-  now warns when a sitemap lists them (it used to fail sites that didn't).
-
-**What changes on upgrade:** every site that serves llms.txt through these
-handlers starts sending the header on its next deploy. No code change is needed.
-
-### `export const generateStaticParams = generateBlogStaticParams` type-checks again
-
-Since 5.4.0, `generateBlogStaticParams` took `BlogRoutingOptions` as its first
-parameter, so the documented direct export failed Next 16's route type check:
-
-```
-.next/types/validator.ts: Type '(options?: BlogRoutingOptions) => Promise<...>'
-is not assignable to type '(props: { params: { slug: string } }) => any[] | Promise<any[]>'.
-```
-
-Webpack builds failed the older `.next/types/app/**/page.ts` guard as well.
-At runtime Next's `{ params }` argument was also being read as routing options.
-It was harmless because no keys overlap, but it only worked by luck. Found when
-spade-nextjs went from 4.2.2 to 5.6.0.
-
-- `generateBlogStaticParams` now has a second overload that accepts Next's
-  props (`NextStaticParamsProps`, exported from `blog/server`), and any
-  argument with a `params` key is ignored. Direct exports type-check under both
-  of Next's checks and use the default routes.
-- Routing options still work the same way from a wrapper:
-  `export function generateStaticParams() { return generateBlogStaticParams(routing) }`.
-- `generateCategoryStaticParams` and `generateAuthorStaticParams` take no
-  arguments, so they were never affected. A compile-time test now covers all
-  three against both of Next's checks.
-
-**If your site patched around this:** a wrapper like
-`export function generateStaticParams() { return generateBlogStaticParams() }`
-keeps working. You can switch back to the one-line export, but you don't have to.
-
-### robots.txt never blocks `/_next/`
-
-`createRobots`, `buildAiCrawlerRules` and `createRobotsTxtHandler` now drop
-any `/_next` disallow path (`/_next`, `/_next/`, `/_next/*`,
-`/_next/static`, `/_next/image`) and log a warning for each one. Googlebot
-renders pages with the CSS, JS and optimized images served from `/_next/`,
-and `/_next/image` is how a site's photos reach Google Images. A 2026-09
-fleet sweep found ten sites disallowing it, two of them through these
-helpers. None of the helpers ever added it by default. `isNextInternalsPath`
-is exported from `@sonordev/site-kit/robots` for sites that build robots.txt
-by hand.
-
-### `resolveManagedRedirect()` is deprecated: it made every page dynamic
-
-Calling `resolveManagedRedirect()` from `app/not-found.tsx` opts every route
-into dynamic rendering. Next renders the root not-found boundary inside every
-page, and the resolver reads `headers()`. On nkylawfirm.com every static route
-turned dynamic, and reverting only `not-found.jsx` put them back. The 404
-boundary can't be made static-safe: skipping the lookup at build time leaves
-the 404 page prerendered static, so the redirects would never run.
-
-- The recommended setup is `createProxy({ redirects: true })` again (it was
-  always the default). The rule list is cached in memory for five minutes, so
-  page loads rarely wait on it. The proxy docs no longer tell sites to prefer
-  `redirects: false`.
-- `sonor-setup scaffold` now writes `createProxy({ redirects: true })` and a
-  plain `not-found.tsx` that reads no request APIs.
-- `resolveManagedRedirect()` still works, so existing sites keep building, but
-  it's marked `@deprecated` and logs a one-time warning.
-- The agent manifest has a new failure mode, `static.dynamic-not-found`, and a
-  caution on `redirects/not-found`.
-
-**If your site calls it:** delete the call from `not-found.tsx`, set
-`redirects: true` in `proxy.ts`, and rebuild. The route table should show ○/●
-again instead of ƒ.
-
-### Blog metadata no longer hides a route's OG card
-
-`generateBlogPostMetadata`, `generateBlogIndexMetadata`,
-`generateBlogCategoryMetadata` and `generateAuthorPageMetadata` returned
-`images: undefined` on `openGraph` and `twitter` when there was no image. Next
-reads the bare key as "this route has no images", which hid the route's own
-`opengraph-image` card. The key is now left out, the same way
-`getManagedMetadata` already did it. Found on nkylawfirm.com, where `/insights`
-served no `og:image` despite having a card file.
-
-### `sonor-setup og` leaves code-based cards alone
-
-The generator wrote a static `opengraph-image.jpg` into every page folder,
-including ones that already render their own card with
-`opengraph-image.(tsx|jsx|ts|js)`, such as a per-city or per-article card. That
-left two `opengraph-image` files in one folder. Those folders are now skipped
-and reported (`og.code-card`), and a static card an earlier run left there is
-removed.
-
-### `sonor-setup` reads `.jsx` sites and proxy-based discovery correctly
-
-The CLI gave false failures on heinrich-law-nextjs, whose app files are `.jsx`,
-and on nkylawfirm.com, which sends its llms discovery header from `proxy.ts`.
-
-- `doctor` reported "no app/layout.tsx found" when the root layout was
-  `app/layout.jsx`. Every lookup of the root layout, pages, route handlers and
-  proxy/middleware now accepts `.tsx`, `.ts`, `.jsx` and `.js`, and checks
-  `app/` before `src/app/` the way Next does. That covers `doctor`'s layout,
-  sitemap and proxy checks, `init`'s layout injection, `og`, and route
-  discovery.
-- The `og.card` check now counts code-generated cards (`opengraph-image.tsx`
-  and friends) as page cards.
-- `geo` failed the discovery-header check for sites using
-  `createProxy({ llmsDiscovery })`. It now reads proxy/middleware (root and
-  `src/`), next.config, the root layout and host config, and treats
-  `llmsDiscovery: false` as off.
-- `geo --ensure-routes` no longer writes `route.ts` beside an existing
-  `route.js`, which Next refuses to build.
-- `migrateSitemap` wrote `sitemap.ts` into `src/app/` when a project had both
-  `app/` and `src/app/`. Next reads `app/`, so the file was ignored. It now
-  writes to `app/`.
-- Route auto-discovery skipped `page.ts` routes, in the CLI and in
-  `registerLocalSitemap({ autoDiscover: true })`. It finds them now.
-
-## 5.6.0
-
-### Local builds stay out of production analytics
-
-Browser pages on `localhost`, `*.localhost`, `127.0.0.1`, `[::1]`, and
-`0.0.0.0` no longer send analytics, fleet heartbeats, or client-side sitemap
-registrations. Engage stays unmounted there, including its chat transport and
-impression/click tracking. This covers `next start`, Lighthouse, and headless
-verification, regardless of `NODE_ENV` or a production `analytics.site` /
-`NEXT_PUBLIC_SITE_URL` setting. The gate reads the actual browser hostname.
-
-Explicitly enable local reporting with
-`<SiteKitLayout analytics={{ allowLocalhost: true }}>`. Standalone
-AnalyticsProvider, WebVitals, FleetHeartbeat, SitemapSync, EngageWidget and
-sendFleetHeartbeat accept the same option. Local cross-origin frames need both
-`allowLocalhost` and `allowInFrame`. These options also flow from the layout to
-fleet, Engage and SitemapSync, which now share the analytics send gate.
-
-Build-time sitemap sync and Node fleet sends are unchanged. This client release
-doesn't protect sites still on older kit versions; see
-[the read-only audit and server follow-up](docs/localhost-analytics-audit.md).
-No analytics rows were deleted.
-
-### CLI project config and Sonor state paths
-
-`sonor-setup migrate`, `setup`, `faqs`, and `locations` now share one config
-resolver and work with only the `SONOR_API_KEY` written by `init`. Commands
-that need a full project UUID resolve it through the API; saved IDs and the
-key's eight-character prefix are never used as the full UUID. API URL
-overrides apply to both project resolution and subsequent requests.
-
-CLI state writes now use `.sonor/templates`, `.sonor-images.json`, and
-`~/.sonor/credentials.json`; `.sonor/config.json` is the preferred config
-path. Legacy state remains a read-only fallback, including image refresh.
-The auth client is renamed to `src/cli/api/sonor.ts`, and the environment
-variable regression test now covers the CLI too.
-
-### One calendar entry per booked meeting
-
-When the host has Google Calendar connected, Google invites the guest to the
-host's event. BookingWidget's success screen still offered Google, Outlook and
-iCal "Add to your calendar" buttons, and the Google and Outlook ones build a
-separate personal event with no tie to that invitation. A guest who clicked
-one had two entries for the same meeting.
-
-`BookingResult` has a new `invitation` field, `'google' | 'sonor'`, that says
-who sends the guest's invite. When it's `'google'`, the success screen drops
-the buttons and says who the invite is coming from: "Your calendar invite is
-on its way from Jordan Lee." When it's `'sonor'`, or when an older API doesn't
-send it, the buttons stay. The API keeps sending `calendarLinks` for every
-booking, so widgets on older versions work as before. A custom success screen
-built on `createBooking` should check `invitation` before it renders
-`calendarLinks`.
-
-### Booking errors explain the next step
-
-Sync's format, availability and reservation requests now share one error
-reader that understands both Sonor's nested error response and older flat
-responses. An address outside the travel radius shows the server's guidance
-to meet virtually or at the office. Invalid or missing responses use a
-visitor-facing fallback.
-
-## 5.5.0 — 2026-09-10
-
-### The chat launcher can be moved without `!important`
-
-The Echo launcher's placement is an inline style: fixed, 20px from the side,
-`calc(20px + env(safe-area-inset-bottom))` from the bottom, z-index 9999.
-`EngageConfig` offered a corner and nothing else, and an inline style beats any
-stylesheet, so a site that needed the launcher somewhere else had one tool: an
-`!important` rule aimed at the kit's markup. Three sites wrote one.
-
-gunninghomes.com is the one that cost something. Its mobile pages carry a
-full-width conversion bar, and at 390x844 the launcher occupied x 310-370,
-y 764-824 while the bar's call to action spanned x 76-374. The bubble covered
-the right 60px of the primary button on every phone, and at z-index 9999
-against the bar's 40 it always won.
-
-`offsetBottom` sets the launcher's distance from the bottom edge:
-
-```tsx
-<SiteKitLayout engage={{ offsetBottom: '88px' }}>…</SiteKitLayout>
-```
-
-Any CSS length works, and a number is pixels. The safe-area inset is still
-added on top, so pass the clearance you want, not the inset.
-
-When the offset depends on the page or the breakpoint, set
-`--sk-echo-offset-bottom` from a stylesheet instead; it wins over the option.
-The launcher is portalled to `<body>`, so a declaration on `body` reaches it:
-
-```css
-@media (max-width: 1023.98px) {
-  body:has(.sticky-cta) {
-    --sk-echo-offset-bottom: 5.5rem;
-  }
-}
-```
-
-That is now gunninghomes.com's entire override. It declares a value the kit
-reads instead of beating the kit's inline style, and it no longer names the
-kit's markup. The kit never declares the property itself, which is
-load-bearing: an unset property falls through to `offsetBottom`, then to 20px.
-
-### The chat popup opens above the launcher, wherever the launcher is
-
-The popup had its own hardcoded `bottom: calc(90px + inset)`. An override that
-lifted only the launcher `<button>` left the popup behind, and the launcher
-then sat on top of the popup's input row and send button. Both elements are
-now placed from one clearance (`engage/launcher-placement.ts`). The popup
-opens 70px above the launcher's bottom edge (its 60px height plus a 10px gap),
-and its max height gives up the same clearance plus 100px, so it keeps 30px
-clear of the top edge.
-
-With nothing set, the geometry is what it was: launcher at 20px, popup at
-90px, max height `100dvh - 120px`. One deliberate difference: the safe-area
-inset now also comes off the popup's max height. Before, on a phone with a
-home indicator (34px) and a short viewport, a full-height popup ran 4px past
-the top of the screen.
-
-### `VisualViewportGap` moves into the kit
-
-queencityriverboats.com and destinyyachtcharters.com each shipped a
-byte-identical `VisualViewportGap.tsx`. On a phone the layout viewport can be
-taller than what the visitor sees, `position: fixed` is measured against the
-layout viewport, and so their launcher sat below the fold. The component
-measures the difference and publishes it on `<html>` as `--sk-vv-layout-gap`.
-
-It is now exported from `@sonordev/site-kit/client` as `VisualViewportGap`
-(and `useVisualViewportGap`, for an existing client component), and the
-launcher and popup include `var(--sk-vv-layout-gap, 0px)` in their placement.
-Mounting it is all a site needs. It also writes the property only when the
-value changes: a custom property on `<html>` restyles the whole document, and
-`visualViewport` fires continuously during a pinch or a toolbar animation.
-
-It stays opt-in. While a field has focus the gap grows to the keyboard's
-height, which lifts everything that reads it above the keyboard. That suits
-those two sites; it is not a default to impose on the fleet. Without the
-tracker the property is unset, resolves to 0px, and nothing moves.
-
-The `./client` export stays in place, including for the QCR and Destiny
-migrations already prepared for 5.5.0. Its integration bundle baseline is
-deliberately refreshed for this shared viewport tracker. The gate measures
-the barrel's entire static import graph before consumer tree-shaking, so
-it counts the tracker even when a site only imports `useDeferredActivation`.
-The package declares JS side-effect-free, allowing consumer bundlers to
-remove the unused tracker. The 10% growth limit remains unchanged.
-
-### One placement type
-
-`position` was declared separately on the layout's `EngageConfig`, engage's
-`EngageConfig`, `EngageWidget`'s props and `ChatConfig`. All four now extend
-`ChatLauncherPlacement` (exported from `@sonordev/site-kit/engage`), which is
-where `offsetBottom` lives, so the next placement option is added once.
-
-### `zIndex` reaches the chat
-
-`engage={{ zIndex }}` stacked popups, nudges and bars, but the chat never got
-it. ChatWidget hardcoded 9999 on the launcher and 9998 on the popup, and
-EngageWidget didn't pass the value on, so
-`<SiteKitLayout engage={{ zIndex: 50 }}>` left the chat above everything a
-site drew. EngageWidget now passes it through: the launcher sits on `zIndex`
-and the popup one layer beneath it, the same relationship as before. Unset,
-both render exactly as they did.
-
-`zIndex` joined `position` and `offsetBottom` in `ChatLauncherPlacement`, so
-its three separate declarations (both `EngageConfig`s and `EngageWidget`'s
-props) are now one, and `ChatConfig` accepts it for a `ChatWidget` mounted on
-its own. At `zIndex` 0 or below the popup shares the launcher's layer rather
-than dropping to -1, which would paint it behind the page.
-
-### `SiteKitConfig` is deprecated
-
-The root export `SiteKitConfig` was the props shape of `SiteKitProvider`. 4.0
-removed the provider, and nothing in the kit reads the type now. Its
-`engage` field is a fifth copy of launcher placement (`position` and `zIndex`,
-no `offsetBottom`), and it stopped matching the day the other four became
-`ChatLauncherPlacement`.
-
-No fleet site imports it, so it's marked `@deprecated` rather than reworked,
-and it goes in 6.0 (removing an exported type is breaking). Code that still
-uses it should switch to `SiteKitLayout`'s config types, `EngageConfig` and
-`AnalyticsConfig` from `@sonordev/site-kit/layout`.
-
-### `ManagedImage`'s picker toggle is `?sonor_dev=true`
-
-The image picker could be forced open on any host with `?uptrade_dev=true`,
-the last Uptrade name on a runtime path. It's `?sonor_dev=true` now, read as a
-real query parameter instead of a substring match. Nothing in the workspace
-generated the old parameter, so there's no alias: a bookmarked `uptrade_dev`
-link just stops opening the picker. `localhost`, `NODE_ENV=development` and
-`forceDevMode` behave as before.
-
-### `sonor-setup migrate` stops writing `SONOR_PROJECT_ID` into sites
-
-The migrator's templates put `projectId={process.env.SONOR_PROJECT_ID!}` on
-every `ManagedSchema`, `ManagedFAQ` and `getManagedMetadata` call they added.
-The prop has been ignored since the project started coming from the key, and
-sites configure exactly one env var. Generated code now passes only `path`.
-Sites migrated earlier keep working; delete the stray prop whenever the file is
-next touched.
-
-### `ssr.render` stops blaming the layout
-
-Since 3.0.2 `SiteKitLayout` renders `{children}` first and mounts analytics,
-engage, sitemap sync and the heartbeat after them as deferred, childless
-siblings, and 4.0 made that structural. The CLI never caught up. When a route
-bailed to client rendering, `verify` and `doctor` told the site to run
-`SiteKitLayout analytics={false}` and hand-roll a deferred analytics sibling,
-which was the workaround from before 3.0.2. On a current install that changes
-nothing: the plain layout isn't the cause, so the real one survives the fix.
-
-Measured on the integration fixture under Next 16.3: a plain `<SiteKitLayout>`
-prerenders every route static with its content in the HTML, and none of the 9
-initial scripts carries analytics code. A site's own
-`next/dynamic({ ssr: false })` provider around `{children}` bails the route to
-0 content tags, and the old fix pointed at the layout anyway.
-
-- The `ssr.render` fix now says to keep the layout, find the component around
-  `{children}` that skips server rendering, and import it statically or mount
-  it childless. `analytics={false}` survives only as a stopgap below 3.0.2. The
-  text lives in `src/cli/agent/ssr-bailout.ts`, and a test pins the agent
-  manifest's `ssr.bailout` failure mode to it.
-- The `analytics-sibling` codemod no longer flags a plain
-  `<SiteKitLayout>{children}</SiteKitLayout>` (the manifest's own blessed
-  layout) as a manual follow-up. It still flags `<AnalyticsProvider>` wrapped
-  around `{children}`.
-- AGENTS.md, the site-kit skill, the manifest's `analytics.deferred-sibling`
-  pattern and the analytics README describe the plain layout. The README's
-  standalone example no longer wraps `{children}` or mounts a second
-  `WebVitals`, and custom events use `trackEvent` / `trackConversion`, because
-  `useAnalytics()` throws outside a provider.
-- The integration fixture runs a plain `SiteKitLayout`, so the prepublish SSR
-  gate covers the layout sites are told to use.
-
-Nothing breaks for a site that still carries `analytics={false}` plus its own
-deferred sibling (two fleet sites do). It can delete both the next time its
-layout is touched.
-
-### Upgrading
-
-Nothing moves until a site opts in. A site that overrides the launcher by hand
-should drop the override in the same deploy that picks up this release, and
-not before: 5.4.x ignores `--sk-echo-offset-bottom` and exports no
-`VisualViewportGap`, so an early migration either puts the launcher back where
-it was or fails the build.
-
-- A `button[data-sk-echo-launcher] { bottom: … !important }` rule becomes
-  `offsetBottom`, or a `--sk-echo-offset-bottom` declaration if the rule was
-  scoped to a page or a breakpoint.
-- A local `VisualViewportGap` becomes the kit's. Keep any
-  `var(--sk-vv-layout-gap)` in the site's own CSS; the property name is
-  unchanged.
-
-### `optionalPagePaths` moves pages to `## Optional` instead of listing them twice
-
-This was written up as 5.4.1 and never released on its own; it ships here.
-
-llmstxt.org's `## Optional` is the section a short-context parser may skip, so
-it can spend its budget on the pages that matter. `optionalPagePaths` is how a
-site puts pages there, but the generator only ever **appended** the section.
-`## Site Pages` was still built from the full page list, so every demoted page
-was listed twice. The page a parser was told it could skip was still in the part
-it reads, and it still used up one of the index's `maxPages` slots.
-
-It was measured on live sites, not just read in the code. homesinkentucky.com
-(art-realty-nextjs) lists three of its four demoted pages (`/privacy`,
-`/accessibility`, `/fair-housing`) in both sections. nkylawfirm.com
-(heinrich-law-nextjs) lists `/accessibility` in both, and its `## Site Pages` is
-full at exactly 50 entries, so the duplicate pushes a real page out of the
-index. gunning-homes-nextjs tried `optionalPagePaths:
-['/privacy']` on 5.4.0, got the privacy policy twice, and turned the option back
-off. A comment in its llms.txt route explains why.
-
-Matching pages now **move**. They're filtered out of `## Site Pages` before
-`maxPages` is applied, so demoting a page frees its slot for the next one rather
-than using one up. Matching ignores leading and trailing slashes (`/privacy`,
-`privacy` and `/privacy/` are one page, and get one line), and one normaliser
-serves both sections, so the index and Optional can't disagree about which page
-a path means.
-
-A moved page also keeps the line it had in the index: the same URL, the same
-note. Optional used to rebuild the URL from the path with a forced trailing
-slash. On a site with Next's default `trailingSlash: false`, that's a 308:
-`https://nkylawfirm.com/accessibility/` redirects to the URL `## Site Pages` had
-already given. Both sections now render a page through one `formatPageLine`, so
-moving a page doesn't change where it links. A path with no matching page is
-still listed under Optional, unchanged.
-
-`## Optional` still needs a resolvable base URL. Without one it's skipped, as
-before, and the demoted pages now stay in `## Site Pages` rather than dropping
-out of the file.
-
-### Upgrading for `optionalPagePaths`
-
-Sites on `^5.3.0` or later pick this up on a plain reinstall. Sites that already
-set the option (art-realty-nextjs, heinrich-law-nextjs) lose their duplicate
-listings, and their Optional links will match the index URLs. gunning-homes-nextjs
-can turn `optionalPagePaths` on now.
-
-## 5.4.0 — 2026-09-09
-
-### Meeting formats and recoverable booking
-
-BookingWidget supports virtual meetings, office visits, and visits to the guest's
-location when the project's meeting settings enable them. It validates the
-location before loading availability and carries the prepared meeting through
-the time reservation and booking request. Pending requests show their actual
-status and don't offer confirmation-only calendar links.
-
-Guests can change formats or return to the service selector without losing their
-address, access notes, or contact details. Navigation is locked during reservation
-and booking requests. Stale responses can't reopen old steps, and abandoned holds
-are released. Expired reservations offer recovery with the guest's details intact.
-A valid hold remains usable after its preparation token expires, until the hold's
-own deadline.
-
-### Article artwork and complete cards
-
-`BlogPost` exposes optional `editorial_image` and `editorial_image_alt` fields.
-The stock article component and generated article schemas use editorial artwork
-when available. Explicit empty alt text remains empty for decorative artwork.
-Older API responses fall back to the featured image.
-
-Homepage/list, related, sidebar, and author cards keep the complete featured
-image. Sonor's composed cards render without cropping or image hover zoom;
-editor-selected photographs retain their existing layout. OG, Twitter, and feed
-share images remain on the featured card. Supplied editorial schemas aren't
-rewritten. Custom layouts can use `resolveBlogArtwork(post, 'article' | 'card')`.
-
-### Accessible article tables
-
-The stock article wraps tables in named, keyboard-focusable scroll regions with
-native touch scrolling and themed scrollbars. It preserves captions, table
-semantics, and the author's HTML, leaves code examples alone, and doesn't force
-small tables to scroll. Custom layouts can use `wrapBlogTables` and `blogTableCss`.
-
-### One publication routing contract
-
-`createBlogRoutes` supplies the publication root and article, category, cluster,
-author, and feed paths. Use `basePath`, `includeCategoryInPath`, or custom
-`postPath`/`categoryPath` callbacks. Existing `blogBasePath` metadata configuration
-continues to work. Stock components accept a shared `routing` prop; metadata,
-schema, RSS, Atom, sitemap, and static-parameter helpers accept the same options.
-
-Generated SEO URLs and feeds honor supplied canonical URLs. Sitemap generation
-reads full, paginated post records so canonical URLs and category segments agree
-with the article, without the feed's 100-post cap. Sitemap category and cluster
-entries can be disabled when those routes aren't implemented. `/blog` remains
-the default, and existing cluster navigation behavior is retained when no new
-routing configuration is supplied.
-
-### Upgrading
-
-Deploy the compatible Sonor booking API and migrations before enabling meeting
-formats. Upgrade and deploy consuming sites before enabling the format setting;
-older widgets can't send a prepared meeting token. Projects without meeting
-formats retain their existing booking flow.
-
-The publishing fixes need no new schema or generated artwork. The atmospheric
-Forge header remains an Upforge design choice; package styles use the shared
-`--sk-*` theme tokens.
-
-## 5.3.2 — 2026-09-09
-
-### Embedded previews no longer report analytics against the site they embed
-
-A site loaded in a **cross-origin iframe** now sends nothing: 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 produced was phantom traffic in the analytics its owner
-reads — and, for an agency, reports to the client.
-
-This was measured, not theorised. Upforge case studies embed each client's
-whole production site in three eager iframes (`DeviceTrifolio`), which
-`DEFAULT_FRAME_ANCESTORS` has permitted since it was introduced. The
-screenshot overlay in those frames hides the **pixels**, not the
-**JavaScript**: the embedded site still loads, hydrates and runs its
-analytics. In `analytics_page_views` on 2026-09-08 the signature was
-unmistakable — three views of `/` sharing one session_id and one visitor_id,
-21-80ms apart, referrer `https://upforge.io/`:
-
-```
-abbeyglenapts.com     20:02:13.852 / .900 / .921
-goldenmilenky.com     04:12:23.840 / .868 / 24.624
-queencityriverboats   22:12:33.609 / .690 / .784
-```
-
-23 client sites carried this traffic, the oldest row from 2026-06-11. Three
-loads of one page inside 70 milliseconds is not a person; it is the desktop,
-tablet and mobile frames of one case study.
-
-**Same-origin frames still report.** The block is on cross-origin embedding,
-not on being framed at all. A site embedding itself (a preview pane, 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 when the frame IS the product** — a widget, a partner-hosted
-booking or menu page, anything deliberately distributed as an embed:
-
-```tsx
-<SiteKitLayout analytics={{ allowInFrame: true }}>…</SiteKitLayout>
-```
-
-`SitemapSync` is gated by the same frame fact, for a different reason. Its
-rows would not be mis-attributed (inside the frame the document still resolves
-its own host and its own sitemap), but a **write** triggered by a third
-party's page view runs a fetch + DOMParser on a visitor's main thread in a
-page that gets nothing from it, and it bumps `seo_pages.updated_at` — the
-tiebreaker in `pickSeoPageRow`'s "most recent" fallback. On a multi-site
-project that is how a shared path like `/` starts resolving to a different
-host's row. A third party's traffic should not be able to move which row wins.
-
-### One send gate instead of eight hand-rolled copies
-
-`analytics/send-gate.ts` is now the single source of truth for "may this
-document report analytics, and where to". Every phone-home in the module
-resolves credentials through `resolveAnalyticsTarget` and sends through
-`analyticsSend` / `analyticsBeacon`; the eight separate copies of that
-resolution it replaced are exactly how a rule gets fixed in one place and left
-broken in seven. `send-gate.test.ts` fails the build if a new direct
-`sonorFetch` / `sonorBeacon` call appears in the analytics module.
-
-The frame **fact** lives apart from the analytics **policy**:
-`shared/frame.ts` owns how a cross-origin frame is detected (and why
-`window.top` rather than `window.parent`), `send-gate.ts` owns what analytics
-does about it.
-
-New exports from `@sonordev/site-kit/analytics` — `isCrossOriginFrame`,
-`isFramed`, `isTopFrameSameOrigin` — so a site can branch on the same answer
-analytics uses (skipping its own third-party pixels in an embed, say) rather
-than hand-rolling a second `window.top` check that drifts from this one.
-
-### `BlogPost` exposes the publication index artwork
-
-`index_image` and `index_image_alt`, the dedicated index frame from Sonor's
-atmosphere + content-stage renderer. Both optional; a post without one falls
-back to `featured_image` as before.
-
-### Upgrading
-
-Sites on `^5.3.0` pick this up on a plain reinstall. **Check any site you
-deliberately distribute as an embed** before deploying: it needs
-`analytics={{ allowInFrame: true }}` or it will go quiet. Sites that are only
-ever framed by Upforge case studies want exactly the new default.
-
-## 5.3.1 — 2026-09-08
-
-### `frame-ancestors` reaches upforgelabs.com, which is its own apex
-
-Every managed site's default framing policy was `'self' https://upforge.io
-https://*.upforge.io`. upforgelabs.com is a **separate apex domain**, not a
-subdomain of upforge.io, so `https://*.upforge.io` never matched it and never
-could. Labs case studies embed the live client site in device frames, so every
-one of those frames was refused with `ERR_BLOCKED_BY_RESPONSE`.
-
-The failure is quiet in the way these always are: the page still renders, with
-an empty rectangle where the client's site should be. It surfaced on
-upforgelabs.com/work/abbey-glen as a Lighthouse **Best Practices 92 instead of
-100** — three blocked frames failing both `errors-in-console` and
-`inspector-issues` — rather than as the missing centrepiece of the page.
-
-`DEFAULT_FRAME_ANCESTORS` now carries `https://upforgelabs.com` and
-`https://*.upforgelabs.com`. `X-Frame-Options` is still not emitted alongside
-it: XFO has no allowlist form, and a stray `DENY` re-blocks what
-`frame-ancestors` just allowed.
-
-upforgeapps.com is deliberately **not** added. It is a third Upforge apex, but
-it only links to case studies on upforge.io/work and frames no client site —
-an origin earns a place on this list by embedding, not by belonging to Upforge.
-
-**This ships to a site only when that site upgrades and redeploys.** Sites on
-`^5.3.0` pick it up on a plain reinstall; sites pinned to 4.x or 5.0.0 need an
-explicit bump. Until then they keep the old policy and keep blocking Labs.
-
-### A dark form field stops handing you near-black text
-
-`--sk-input-text` fell back straight to `#111827`, so a site that themed
-`--sk-input-bg` dark and `--sk-text-primary` light — never having heard of a
-field-specific token — got near-black text on a dark field anyway. Measured at
-**1.03:1** on upforgelabs.com's contact form: not a contrast score to nudge, a
-field you cannot read your own answer in.
-
-The fallback chain is now `--sk-input-text` → `--sk-text-primary` → `#111827`,
-so naming the field colour still wins and theming the page's text is enough on
-its own. Placeholders follow `--sk-text-tertiary` at `opacity: 1`, since the
-UA's own placeholder alpha compounds the same problem. Neither token is
-declared in `:root`, which is load-bearing rather than an omission — a token
-with a value can never reach the second argument of its own `var()` fallback.
-
-
-## 5.3.0 — 2026-09-02
-
-### Motion: the Upforge motion standard ships in the kit
-
-Seventeen of thirty-six sites in the fleet carry GSAP, fourteen of them with
-their own `ScrollReveal` implementation, and every one of those copies is a
-place the same bug has to be fixed. This release replaces them with one
-module, tiered by what each library actually costs, so a site only installs
-and ships what it imports.
-
-**`@sonordev/site-kit/motion` (tier 0, zero dependencies, ~2KB).** What every
-site gets:
-
-- `<Reveal>` — scroll-entrance reveal on a CSS transition. The server HTML is
-  fully visible, above-the-fold content is never touched, and a headless
-  renderer that never scrolls (Google's included) gets the content back
-  after 2.5s, so the indexed snapshot is never transparent.
-- `<Parallax>` / `useParallax` — scroll-linked transform and opacity,
-  compositor-only.
-- `<ScrollScene>` / `useScrollScene` — a pinned scene: sticky stage, progress
-  0→1 written to a CSS custom property (`--sk-p`) so choreography can be pure
-  CSS, plus an `onProgress` callback for anything that needs code.
-- `registerScene` — the engine itself: one shared requestAnimationFrame for
-  every scene on the page, native scroll only, offscreen scenes not rendered,
-  `prefers-reduced-motion` held at a still frame. Extracted from
-  upforgelabs.com.
-
-**`@sonordev/site-kit/motion/gsap` (tier 1, optional peer `gsap`).**
-`useGsap` runs a setup inside `gsap.context` when its element nears the
-viewport, so the ~46KB of core + ScrollTrigger never sits on the LCP path;
-`loadGsap` and `useExpandCollapse` come along. ScrollSmoother is deliberately
-not included: it drives scrolling by transforming the page body, which fights
-native scroll and costs INP on mobile.
-
-**`@sonordev/site-kit/motion/three` (tier 2, optional peer `three`).**
-`useThreeStage` mounts a renderer on a pinned scene and drives it from
-scroll, owning the canvas, sizing, DPR, context loss, and disposal.
-`canRunWebGL()` keeps the server-rendered still for reduced-motion,
-Save-Data, and no-WebGL visitors. `loadTexture` never throws.
-
-The tiers are enforced, not suggested: a test fails the build if anything
-outside `src/motion/gsap.ts` imports gsap or anything outside
-`src/motion/three.ts` imports three, because bundlers resolve even a dynamic
-`import()` at build time and a stray import would force every consumer of
-`./motion` to install a library it never asked for.
-
-Nothing here is mounted by `SiteKitLayout`. Motion is opt-in per element and
-never wraps the page. Full API in `src/motion/README.md`.
-
-## 5.2.0 — 2026-08-31
-
-### Lead conversions can now be reported by Sonor instead of the browser
-
-If your site fires a Google Ads or GA4 conversion when a form is submitted, it
-has been counting spam as leads. That is not a bug in your site — it is
-unavoidable from the browser. Sonor answers every submission with a byte
-identical success payload whether it accepted the lead or quarantined it as
-spam, deliberately, so a bot never learns it was caught. Your page therefore
-cannot tell the two apart, and Smart Bidding learns to buy more of whatever
-traffic produced the spam.
-
-The accept or reject verdict only exists on the server, so that is where the
-conversion has to be reported from. This release supplies the one piece the
-server was missing.
-
-**Every form submission now carries the visitor's existing GA4 identity** —
-`gaClientId` from the `_ga` cookie, and `gaSessions` (a map of container id to
-session id) from the `_ga_<CONTAINER>` cookies. Nothing new is written or
-tracked; these are cookies Google's own tag already set, and they are read, not
-created. The session map is keyed by property so a page carrying two GA4
-properties cannot attach a lead to the wrong one.
-
-**`ManagedFormConfig` gained `server_side_lead_conversion`.** When true, Sonor
-is reporting this project's lead conversions and your site must NOT fire its
-own on submit, or every real lead is counted twice:
-
-```tsx
-const { form } = useForm(slug, {
-  onSuccess: () => {
-    if (form?.server_side_lead_conversion) return  // Sonor reports it
-    gtag('event', 'conversion', { send_to: '...' })
-  },
-})
-```
-
-**Nothing changes until a project turns it on.** The flag is false for every
-project that has not configured server-side reporting in Sonor, so existing
-sites behave exactly as they do today. Turn it on under Forms, Settings, Lead
-Conversion Reporting.
-
-## 5.1.0 — 2026-08-27
-
-### Server commerce helpers can finally tell "empty" from "broken"
-
-Every server-side commerce helper returned `[]` (or `null`) when the fetch
-failed, identically to a genuinely empty result. That let calling pages state a
-business fact they did not know.
-
-It bit a real customer: QCR's /public-cruises rendered that `[]` as **"No public
-cruises currently on the schedule"** while three cruises were on sale, and the
-client emailed asking why the site said they had no events. Because the route was
-statically revalidated, Next then cached the claim.
-
-**New `*Result` helpers** return `{ ok, data }`, where `ok: false` means the
-request failed and `ok: true` with empty data means genuinely empty:
-
-- `getUpcomingEventsResult` — use this wherever the UI renders "no upcoming events"
-- `getOfferingsResult` — use this wherever it renders "nothing available"
-- `getOfferingBySlugResult` — separates "no such offering" from "unreachable", so
-  a transient failure no longer `notFound()`s a page that exists and de-indexes it
-- `getNextEventResult`
-- `ServerResult<T>` is exported for typing your own wrappers
-
-**Nothing breaks.** `getUpcomingEvents`, `getOfferings`, `getOfferingBySlug` and
-`getNextEvent` keep their exact signatures and behaviour, delegating to the new
-helpers. Existing sites need no change; adopt the `*Result` variants where the
-distinction matters.
-
-### Framework signals are no longer swallowed as fetch failures
-
-`apiFetch`/`apiPost` caught everything, including Next's own control-flow throws.
-A `DYNAMIC_SERVER_USAGE` digest means "this route can't be prerendered", and
-`redirect()`/`notFound()` throw too — swallowing those logged a fake fetch error
-on every build and made a real outage look identical to the framework working
-correctly. These now rethrow.
-
-### Failed static-path generation is no longer silent
-
-`getProductPaths` / `getEventPaths` / `getOfferingPaths` returning `[]` on a
-failed fetch prerenders ZERO pages while the build still reports success — a site
-ships with its whole catalogue missing and nothing says so. They now log an
-explicit error. (Return shape unchanged.)
-
-### Known gap
-
-These helpers still issue a plain `fetch` with no cache control, so a site that
-needs `next: { revalidate }` (to keep a route static rather than flipping to
-per-request SSR) must still wrap them. That is why QCR keeps its own fetcher.
-
-## 5.0.0 — 2026-08-26
-
-The blog module got a full contract audit against the deployed Sonor API and
-the live database schema. Seventeen confirmed defects, most of them silent —
-clean 200s hiding wrong or empty results. Everything below works against
-today's api.sonor.io and improves further when the paired API deploy lands.
-
-### The headline: several blog features have never worked
-
-**Related posts always returned nothing.** Two independent bugs: the fetch
-called a path that does not exist, and once that was fixed, the body sent
-`currentPostId` where the API reads `current_post_id`. Both fixed. If your
-site mounts `RelatedPosts` or calls `getRelatedInsights`, a populated
-related-posts section appears for the first time with no change on your
-side — budget for the layout. (The packaged `BlogPost` has its own internal
-related fetch and is unaffected.) `getRelatedInsights`' `category` option is
-still accepted and still ignored; the server derives relatedness from the
-current post.
-
-**RSS and Atom feeds were capped at 12 posts.** The feed fetch sent `limit`,
-a parameter the API never read, so every feed silently got the default page.
-Feeds now paginate properly and include up to 100 posts — so a feed that has
-been serving 12 items grows on the next build, and readers may see older
-posts arrive as "new". A mid-pagination failure now returns the posts
-gathered so far instead of an empty feed. `getPostsByCategory` goes from 12
-to 50 for the same reason.
-
-**"X min read" never rendered.** The components gated on
-`reading_time_minutes`; the API returns `reading_time`. One shared helper
-(`readingTimeMinutes`) now feeds every render site.
-
-**Tag pages were empty for any multi-word tag.** The sidebar linked by
-slugified slug ("case-study") while the API filters by exact stored name
-("Case Study"). Links now carry the encoded raw name, and the paired API
-deploy also accepts slugs — so old shipped links heal too. Note the URL
-shape changed: sidebar tag links are now `?tag=Case%20Study`, not
-`?tag=case-study`. A site that reads the `tag` search param itself, or that
-has canonicalised the old shape, should expect the new value.
-
-**Signal-generated E-E-A-T JSON-LD was discarded.** The schema resolver now
-reads `schema ?? schema_json`, so stored structured data reaches pages
-instead of falling back to the generic generated Article.
-
-**Author social links now render** from the real `blog_authors` columns
-(linkedin_url, twitter_url, website_url) via one shared helper, in the post
-byline, `AuthorCard`, and `AuthorPage`. The byline normalizer stopped
-dropping those columns on the floor.
-
-### New
-
-**`BlogViewTracker`** — `BlogPost` now mounts a childless client island that
-counts actual readers: one POST to `/public/blog/view` per post per browser
-session (deduped through a `__sonor_blog_viewed__:<slug>` sessionStorage
-key), deferred to idle, no retries (the increment is not idempotent). Under
-ISR the old server-side count incremented when the *cache revalidated*, so
-`view_count` was measuring cache churn, not people.
-
-This is new outbound traffic from every blog post page, including the
-custom `children` render-prop path, which previously shipped no client
-islands at all. It requires `SiteKitLayout` (it reads the layout's globals
-and sends the minted token) and silently no-ops without it.
-
-The endpoint it calls is already live, so counting starts the moment you
-upgrade — but the *old* server-side increment keeps running until the
-paired api.sonor.io deploy removes it, so a site on 5.0.0 against the
-un-deployed API counts both readers and revalidations for that window.
-Upgrade near the deploy, or expect an inflated stretch. Historical counts
-are left as-is either way: treat pre-cutover numbers as a different metric,
-not a comparable series.
-
-**`NewsletterWidget` actually subscribes people.** The old widget rendered a
-form whose submit handler discarded the email. It now takes either an
-`onSubmit` callback or a `formSlug` pointing at a managed Sonor form —
-formSlug mode drives the managed-forms rail, inheriting newsletter routing,
-honeypot, reCAPTCHA, and attribution. The forms engine is lazy-loaded so
-blog pages that never mount it pay nothing. With neither prop the widget
-renders nothing and warns: a dead form that swallows emails must not come
-back.
-
-**Safe imports for async server components.** `BlogLayout`, `BlogPage`,
-`BlogPostPage`, `CategoryPage`, `BlogSidebar`, and `RelatedPosts` are
-exported from `@sonordev/site-kit/blog/server-ui`. Importing them from
-`@sonordev/site-kit/blog` (a client-stamped entry) produces an HTTP 500 in
-production — that path remains only for backwards compatibility, and a
-ratcheted guard test now pins the offender list so it can only shrink.
-
-### Also fixed
-
-- Category metadata builds its og:url from a slug — "Case Studies" produced
-  `/blog/category/case%20studies` against a real route of
-  `/blog/category/case-studies`. Takes an explicit `categorySlug`, respects
-  `blogBasePath`.
-- `BlogList` accepts `cluster` to filter by topic-cluster slug; the `author`
-  filter is documented as slug-preferred (the paired API deploy resolves
-  slugs).
-- `getAuthorPosts` gained an `offset` parameter and hydrates the full author
-  row when an older API returns the stripped `{name, slug}` shape.
-- Topic cluster mapping carries `created_at`, and the detail path prefers
-  the authoritative `pillar_post_id` over the embedded pillar's id.
-- OG metadata and JSON-LD stopped reading fields that do not exist
-  (`og_image`, image width/height columns): image resolution goes straight
-  to `featured_image`, and schema images are plain URL strings instead of
-  ImageObjects with fabricated dimensions.
-- `sonor-setup sync --blog` stopped POSTing to an endpoint that has never
-  existed (every run 404'd). It now inventories local markdown and says
-  plainly that the Sonor blog is dashboard-managed.
-
-### Breaking
-
-The type surface stopped promising fields the wire never carries. **No
-runtime change** — every removed field was already `undefined` at runtime —
-but reads of them are now compile errors, which is the point.
-
-- `BlogTag` is `{ name, slug, post_count? }`. Tags are synthesized from
-  post tag strings; no server version can ever supply `id`/`project_id`.
-- `BlogCategory.id` and `.project_id` are optional (real columns, stripped
-  from the public response).
-- `BlogPost` loses `og_image`, `featured_image_width`,
-  `featured_image_height`, `scheduled_at`, `is_featured`. The real columns
-  — `featured` and `scheduled_for` — are typed.
-- `BlogAuthor` loses `email` (the API now strips it server-side too).
-- The `BlogAnalytics` interface is gone; `BlogViewTracker` supersedes it.
-- **`<NewsletterWidget />` with no props now renders nothing** (and warns)
-  where 4.x rendered a visible subscribe form. That form discarded every
-  email it collected, so this is deliberate — but it is a visible sidebar
-  block disappearing, with no compile error to warn you. Pass `onSubmit` or
-  `formSlug` to keep it. Sites that already passed `onSubmit` get the
-  opposite surprise in their favour: 4.x never invoked it (the prop was
-  declared but never destructured), and 5.0.0 does.
-
-**Behaviour change worth reading twice.** On blogs that render the packaged
-`BlogPost` with cluster posts on a *flat* URL structure (no category
-segment), the cluster navigation's pillar link changes from
-`/blog/<slug>` (accidentally correct) to the category-segmented form,
-matching how sibling links already behaved. An explicit URL-shape control
-on `ClusterNavigation` is planned; until then flat-URL blogs with clusters
-should hold on 4.x or pass their own cluster nav.
-
-### Paired API deploy
-
-The api.sonor.io deploy that pairs with this release fixes the other half
-of several contracts: the author embed no longer shadows the byline column
-(bylines return fleet-wide with zero site rebuilds), `schema_json` is
-mapped to `schema`, internal scoring fields and author emails stop shipping
-publicly, `limit` works as a `per_page` alias, tag and author filters
-accept slugs, category counts stop including drafts, and
-`GET posts/:slug` no longer increments `view_count`. Deploy order is free:
-every site-kit change degrades gracefully against the old API and vice
-versa.
-
-## 4.3.2 — 2026-08-25
-
-### A site now describes itself, not its neighbours
-
-One Sonor project can host many domains. `seo_pages` is unique on
-`(project_id, site, url)`, so a shared path like `/` or `/terms` legitimately
-keeps one row per host. The build path never said which host it was, which left
-both halves of that guessing.
-
-**The build-time sitemap sync is tagged with the host.** `createSitemap` now
-sends `site` to `register-sitemap`, the same way the runtime `SitemapSync` and
-the reconciler cron already did. Before this, pages a build discovered landed
-unattributed, so nothing could tell one sibling's rows from another's.
-
-**Every llms.txt read is scoped to the building host.** `?site=` goes out on
-`/api/public/llms/{data,services,pages,txt}`. On a 49-domain network this is the
-difference between a homepage entry that describes the site and one that
-describes whichever sibling deployed most recently. It also stops a host
-advertising paths it does not serve: the hub was publishing `/terms` and
-`/privacy` borrowed from its microsites, both of which answered 404.
-
-**Behaviour change worth reading twice.** A `full-replace` sitemap sync that
-carries a `site` prunes that host's stale rows. A sync without one is the legacy
-project-wide mode, and on a multi-site project the API refuses deletions
-outright. So on projects that span several hosts, build-time pruning becomes
-active where it was previously skipped. That is the correct behaviour and it is
-what makes per-host page sets converge, but it is new, and it is why a build
-whose `additionalPaths()` silently returns short now costs rows rather than
-being absorbed. Single-site projects are unaffected: their scope was already
-everything.
-
-**Host resolution has one source and a defined order.** `resolveSiteHost` moved
-into `sites/resolve`, shared by the browser (which publishes
-`__SITE_KIT_SITE__`) and the build. Precedence is `site` option, then `baseUrl`,
-then `NEXT_PUBLIC_SITE_URL`, then the resolved base URL. A per-call `baseUrl`
-outranks the environment variable deliberately: it is set by this repo for this
-build, while `NEXT_PUBLIC_SITE_URL` is process-wide and can be stale or point at
-a sibling. Because `site` is part of page identity, getting that order wrong
-does not fail loudly, it mints a duplicate page set.
-
-Also on Next 16.3.2. The peer range is unchanged at `^15.0.0 || ^16.0.0`; this
-is the version site-kit itself builds and tests against.
-
-Requires the matching Sonor API release. Older API builds ignore `site` and keep
-working.
-
-## 4.2.4 — 2026-08-15
-
-### The generated cards now look like someone made them
-
-4.2.3 shipped per-page cards that all *fit*. Then someone asked whether they
-were actually any good, and looking at all nineteen instead of the two I had
-checked found four problems the fit report could never catch — it measures
-geometry, not whether copy reads well.
-
-**The home page kept its hand-written card.** Deriving every route from its
-managed title meant `/` lost the crafted headline ("Built by brothers") for the
-SEO string ("Custom Closets Cincinnati Tri-State") — four lines that restated
-the kicker directly above them. `og.config.ts` `content` IS the home page's
-card: it is the one route whose subject is the whole site, and it is written by
-hand. It is no longer overwritten.
-
-**Redundant kickers are dropped.** Managed titles carry the section and the
-city, so a derived kicker frequently repeated the title back at itself. When
-either contains the other, or every kicker word already appears in the title,
-the title wins and the kicker goes — which also returns a line of the frame to
-the headline.
-
-**Subtitles refuse rather than truncate.** A managed description is 150+
-characters of prose written for a SERP row, and at card size no truncation of it
-looks deliberate. A word cut gave "across Cincinnati and…"; cutting at the last
-comma gave "home offices designed, built", which is worse because without an
-ellipsis it looks complete and merely ungrammatical. `clampSubtitle` now takes a
-whole sentence when one fits and otherwise returns nothing, so the card falls
-back to the site's own short subtitle. A clean generic line beats a mangled
-specific one, and the title is already page-specific.
-
-**The bar is checked on both axes.** A long segment wrapped INSIDE its span, so
-`scrollWidth` never exceeded `clientWidth` while the text grew past the bar's
-fixed height and spilled over the copy above it — and the renderer passed it.
-Segments are `white-space: nowrap` now, which turns that into horizontal
-overflow the existing check sees, plus a height check as belt-and-braces. Found
-by rendering a real campaign card with a deadline in the bar.
-
-None of these were visible from the fit report, which is the lesson: the
-renderer can prove a card fits, and only a person can say whether it reads.
-
-## 4.2.3 — 2026-08-15
-
-### OG cards: one per page, and cards that verify themselves
-
-Written after being the factory's first real consumer. Two of the three problems
-below only surfaced because a human opened the PNG.
-
-**Every page gets its own card.** `sonor-setup og` still writes the site card to
-`public/og.png`, and now also renders one card per route through the same
-headless-Chrome path. Copy comes from Sonor's managed title and description, so a
-card and its search result say the same thing; without a key the route path is
-titled. Theme, fonts, logo and photo are inherited from `og.config.ts` so the set
-reads as one family, and `cards: { '/path': {…} }` hand-writes the few that
-deserve it. Cards are written as Next's `opengraph-image` file convention beside
-each `page.tsx`, so a site needs no per-page metadata. `--no-pages` opts out.
-
-**Two things about Next metadata that are the opposite of the intuition.** Both
-verified against real builds, both wrong in the first implementation:
-
-1. *Config metadata beats the file convention.* A route returning
-   `openGraph.images` overrides its own card file. With images declared, all 32
-   routes on a real site served the site card and every generated page card was
-   inert; removing the declaration made each serve its own. This matters most
-   for `seo_pages.managed_og_image`, which site-kit serves into
-   `openGraph.images` for every managed page — set it and it silently suppresses
-   the entire set from the dashboard.
-2. *File metadata does not cascade.* A card at `services/` is not inherited by
-   `services/[city]`; those pages shipped with no `og:image` at all until dynamic
-   segments got their own. One static file in a dynamic segment covers every
-   param.
-
-**The wiring rule now has one implementation.** It had two — the CLI's
-post-render check and the doctor's `og.card` check — and both said the same wrong
-thing: "add `openGraph.images: ['/og.png']` to the root layout". Since per-page
-cards landed, that advice breaks the site. Both now call `og/wiring.ts`, which
-knows which mode a site is in and, in per-page mode, treats a declared images
-array as the defect. The old CLI check read only the root layout and reported
-"wiring looks right" while 16 routes had no image at all.
-
-**Cards fail loudly instead of silently.** The first card generated in anger had
-the kicker off-canvas, the subtitle buried under the bottom bar and the bar
-wrapped into the crop; the CLI printed a tick. The renderer has a live DOM, so it
-measures before screenshotting: an in-page fitter waits for
-`document.fonts.ready`, steps the title down from 104px until it fits **both**
-axes — height alone is not enough, since an unbreakable word like "WORKBENCHES"
-overflows sideways at a size that fits vertically — and reports anything still
-clipped. `--screenshot` and `--dump-dom` run in one Chrome invocation, so the
-report always describes the image that was actually written. Copy that cannot fit
-fails the command with the element and the overflow in pixels.
-
-104px is an opening size now rather than a fixed one, with a 56px legibility
-floor: below that a headline stops reading at the ~300px thumbnail width
-platforms actually show, so the answer is shorter copy, not smaller type.
-
-**Smaller fixes**
-
-- `logo` was silently dropped in `split` layout (that branch renders copy+photo
-  and never touches the plate). It now renders as a mark above the kicker; the
-  "no `.plate` in split" invariant still holds.
-- Page cards are re-encoded to JPEG when `sharp` resolves: 5.6 MB → 1.4 MB across
-  18 cards, at no visible cost on a photo-plus-flat-colour card.
-- Subtitles clamp to a real sentence where one fits, and no longer produce `….`
-  by appending an ellipsis after existing punctuation.
-- The legibility preview moved out of `public/` (where it deployed with the site)
-  to `.sonor/`, and the Facebook debugger link is pre-filled with the site's
-  domain.
-- New `src/og/README.md` documents the precedence rule, the copy budget, and the
-  tier-2 escape hatch.
-
-**Upgrading:** running `sonor-setup og` now writes `opengraph-image` files into
-your app directory and, if it finds them, asks you to REMOVE `openGraph.images`
-from the root layout and clear `managed_og_image` in Sonor. That is the correct
-direction — it is what makes per-page cards take effect — but it is a change of
-advice from every previous version, so read the wiring output rather than
-skimming it. `--no-pages` keeps the old single-card behaviour.
-
-## 4.2.2 — 2026-08-14
-
-> 4.2.1 was tagged but never published, so upgrading from 4.2.0 also picks up
-> its `sitemapSync` default flip — see the note at the end of this entry.
-
-### Every managed form logged two "form started" rows per page load
-
-One page load wrote **two** `form_analytics` rows, milliseconds apart, each with
-its own `session_id`. `form_analytics` is the start signal behind funnel
-reporting, so every reported start → submission conversion rate was **half its
-true value** — a page converting at 10% reported 5%.
-
-The cause was two trackers on one form. `ManagedForm` called `useForm`, which
-tracks, *and* rendered `FormClient`, which tracks again. Two independent
-`useFormTracking` instances, two session uuids, two `POST /analytics/start`.
-Both `ServerForm`/`FormEnhancer` and a plain client `<ManagedForm>` end up in
-the same place, which is why every rendering path doubled.
-
-It was not an effect firing twice. The proof is in the shape of the data: paired
-rows where exactly one ever completed (only `FormClient`'s instance owns submit,
-so `useForm`'s row could never be completed) but **both** abandoned. One hook has
-one analytics row id and one `beforeunload` listener — it cannot abandon two
-rows. Only two independent instances can. So every successful submission also
-wrote a phantom abandonment.
-
-The fix is one owner per form. `ManagedForm` now passes `trackAnalytics: false`
-to `useForm` — it delegates rendering, step navigation and submission to
-`FormClient`, so `FormClient` owns the funnel. `useForm` and `FormClient` remain
-fully tracked when used on their own; only the composition changed.
-
-Underneath that, `forms/tracking-session.ts` is now the single source of truth:
-one start per `formId` per page load, with every mounted tracker joining one
-session and **sharing** its analytics row id. Sharing rather than silencing the
-second tracker is deliberate — whichever component owns submit can still
-complete the row no matter which one opened it, so the guard does not depend on
-which instance mounts first. A short grace period on unmount also absorbs React
-StrictMode's dev-mode remount and the `FormEnhancer` static → interactive swap,
-both of which are one page load and must stay one row.
-
-Two smaller correctness fixes came with it:
-
-- Abandonment is now recorded once per row rather than once per tracker, and a
-  completed form is never also reported as abandoned.
-- `trackStepChange` / `trackComplete` now wait on an in-flight start instead of
-  silently dropping. A fast submit used to race the start POST and lose the
-  completion, understating conversions the same way double-starting overstated
-  them.
-
-`sonor-api` gained a matching server-side guard (a partial unique index on
-`form_analytics`, keyed on the request rather than the client's `sessionId`),
-since sites pin their own site-kit version and the fleet updates slowly.
-
-**Historical data:** rows written before this fix are affected but **not
-uniformly** — 96% of page loads doubled in 2026-01, 40% in 2026-07, across up to
-29 projects, because only the `ManagedForm` path double-tracked. Do not apply a
-blanket 50% correction. To recount a period honestly, collapse rows sharing
-`(form_id, date_trunc('second', started_at))` rather than scaling totals.
-
-### Also included: `sitemapSync` now defaults to false (from the unpublished 4.2.1)
-
-Sitemap registration is a build-time and server-side job — build-time
-`createSitemap` is canonical, and sonor-api's nightly reconciler fetches each
-host's `/sitemap.xml` itself. But `sitemapSync` defaulted to `true` and both its
-guards live in browser storage (throttle in `sessionStorage`, content hash in
-`localStorage`), so every first-time visitor, incognito tab and crawler missed
-both and re-POSTed the entire sitemap. Sitemap traffic scaled with visitor count.
-`SiteKitLayout` now defaults it off; sites that genuinely want runtime sync can
-still pass `sitemapSync`.
-
-## 4.2.0 — 2026-08-14
-
-### `landing/server`: the landing module's own documented pattern builds again
-
-`@sonordev/site-kit/landing` documents this:
-
-```tsx
-export const metadata = landingPageMetadata({ ... })
-```
-
-It did not build. Next forbids exporting `metadata` from a client module, and
-`landingPageMetadata` was shipping from a chunk stamped `'use client'` — so
-every campaign route following the README failed, and the workaround was to
-hand-write the noindex robots block and skip the helper.
-
-Neither helper needed the client. `landing/metadata.ts` and
-`landing/contract.ts` have no hooks, no directive and no browser globals. The
-stamp did NOT come from `CLIENT_ENTRIES` (`landing/index` is not in it): the
-build also stamps any shared chunk that *contains* React hooks, `<LandingPage>`
-has them, and the two pure functions were bundled alongside it. The same
-mechanism put `DatePicker`'s hooks on the `FormField` chunk in 4.0.2.
-
-```tsx
-import { LandingPage } from '@sonordev/site-kit/landing'
-import { landingPageMetadata } from '@sonordev/site-kit/landing/server'
-```
-
-Splitting the entry also gives the helpers their own hook-free chunk, so the
-original barrel import works again too. That is a consequence of chunk
-splitting and could silently re-merge, so the dedicated entry is the guarantee
-and `landing/server-entry.test.ts` pins it at source level.
-
-This is the third instance of one root cause — a server-usable export made
-unusable by sharing a chunk with hook-bearing code. `forms/static` (4.0.2) and
-the `FIELD_CONTROLS` injection (4.0.2) were the first two. A build-time guard
-that fails when a hook-free module lands in a stamped chunk would catch the
-fourth before a consumer's build does.
-
-## 4.1.0 — 2026-08-14
-
-### The CMS module builds on Next 16 again
-
-Every site importing `@sonordev/site-kit/cms` has been failing `next build` at
-page-data collection with:
-
-```
-Error: dynamic usage of require is not supported
-```
-
-`cms/server-api.ts` reached for React's `cache` with
-`const { cache } = require('react')`. tsup compiles a bare `require` in ESM
-output to its `__require` interop shim, and Turbopack refuses to evaluate that.
-Five other modules — `seo/api.ts`, `seo/server-api.ts`, `llms/api.ts`,
-`slots/server-api.ts`, `seo/LocationPageContent.tsx` — already did the same
-thing correctly with a static `import { cache } from 'react'`. This one file
-had drifted, and it took the whole CMS module down with it.
-
-This was **not** a 4.0.3 regression — published 4.0.2 fails identically. It has
-been broken for as long as sites have been on Next 16. A test now scans all
-shipped source (everything outside `src/cli`, which is CJS by design) for bare
-`require()` calls, so the next drift fails here instead of at a customer build.
-
-### React 19 is now the floor
-
-`peerDependencies` asked for `react: ^18.0.0 || ^19.0.0`. That was never true.
-Six modules import React's `cache` statically — `cms/server-api.ts`,
-`seo/api.ts`, `seo/server-api.ts`, `llms/api.ts`, `slots/server-api.ts` and
-`seo/LocationPageContent.tsx` — and **React 18 does not export `cache` at all**
-(confirmed `undefined` in both 18.2.0 and 18.3.1). A site on React 18 could not
-have used site-kit's SEO, CMS, LLMs or slots modules regardless of what the
-range claimed.
-
-- `react` / `react-dom` peers are now `^19.0.0`.
-- `next` peer drops `^14.0.0` (now `^15.0.0 || ^16.0.0`): Next 14 pins React
-  18.2, so `next@14` + `react@19` was an unsatisfiable pair once React 18 was
-  gone. Every repo in the fleet is on Next 15 or 16 — none on 14.
-- The `next` devDependency moves 16.3.0 → 16.3.1 to match current.
-
-This narrows a published range, so treat it as the breaking part of this
-release. In practice the blast radius is zero: every fleet repo is already on
-React 19, and the single React 18 project doesn't depend on site-kit.
-
-### Sanity packages are optional peers now
-
-`@portabletext/react` and `@sanity/image-url` moved from `dependencies` to
-optional `peerDependencies`. They serve only the CMS module — 8 packages and
-~1.7 MB that every site on the fleet was installing to render Sanity content
-most of them never touch.
-
-**If you use `@sonordev/site-kit/cms`, add them:**
-
-```bash
-npm i @portabletext/react @sanity/image-url
-```
-
-**If you don't, there's nothing to do** — you simply stop installing them.
-`@sonordev/site-kit/cms/server` is unaffected either way; it has no Sanity
-imports and needs no peers.
-
-This ships as a minor rather than a major because the blast radius is narrow
-and the failure is loud: only a site that explicitly imports `./cms` is
-affected, and it gets a build-time `Module not found: Can't resolve
-'@portabletext/react'` naming exactly what to install — not a silent runtime
-break. Verified on real Next 16 builds in all three states: no-CMS site builds
-and skips the packages, CMS site without peers fails with that message, CMS
-site with peers builds and renders.
-
-The same treatment is **not** possible for `react-markdown` (85 packages,
-~8 MB), even though it is used by a single component. It is reachable from
-`./engage`, which chat sites do import, and bundlers resolve even a *dynamic*
-import at build time — so there is no runtime fallback to degrade into. What
-makes the Sanity packages safe is subpath isolation: nothing outside
-`src/cms/` imports them and no shared chunk carries them, exactly like
-`@vis.gl/react-google-maps` for `./maps`. Both rules are asserted by tests.
-
-## 4.0.3 — 2026-08-14
-
-### Security: 4.0.3 is the version that clears the socket.io advisories
-
-**Bump the fleet to 4.0.3 to clear all four.** Sites on 4.0.2 and earlier
-inherit them through the Engage chat's socket.io dependency:
-
-| Advisory | Package | Severity | Patched at |
-|---|---|---|---|
-| [GHSA-96hv-2xvq-fx4p](https://github.com/advisories/GHSA-96hv-2xvq-fx4p) — memory exhaustion DoS from tiny fragments | ws | High | 8.21.0 |
-| [GHSA-58qx-3vcg-4xpx](https://github.com/advisories/GHSA-58qx-3vcg-4xpx) — uninitialized memory disclosure | ws | Moderate | 8.20.1 |
-| [GHSA-2m8v-j782-fhvr](https://github.com/advisories/GHSA-2m8v-j782-fhvr) — zero-attachment memory exhaustion | socket.io-parser | High | 4.2.7 |
-| [GHSA-677m-j7p3-52f9](https://github.com/advisories/GHSA-677m-j7p3-52f9) — unbounded binary attachments | socket.io-parser | High | 4.2.6 |
-
-The obvious fix doesn't exist: `socket.io-client@4.8.3` is already the latest
-release, and its own ranges (`engine.io-client: ~6.6.1`,
-`socket.io-parser: ~4.2.4`) are wide enough to resolve *either* the vulnerable
-or the patched versions. A fresh install today happens to land on the patched
-ones. That's the trap — it means the ranges look fine while the fleet isn't.
-
-What actually pins a site to the vulnerable tree is its **lockfile**. npm won't
-touch a transitive dependency that still satisfies the existing range, so a
-site can bump site-kit, see the version change, and keep shipping ws 8.18.3.
-Verified on a stale lockfile: bumping with the ranges alone left
-engine.io-client 6.6.4 / ws 8.18.3 / socket.io-parser 4.2.5 in place and three
-advisories still open.
-
-So 4.0.3 raises the declared floor instead. `engine.io-client: ^6.6.6` and
-`socket.io-parser: ^4.2.7` are now direct dependencies — not because anything
-imports them, but because a *library* can't fix this any other way: npm and
-pnpm only honour `overrides`/`resolutions` from the root project, so site-kit's
-own overrides would never reach a consuming site. A declared floor does.
-6.6.6 is the exact floor that matters — 6.6.5 still pulls ws `~8.20.1`, which
-is short of the High-severity DoS fix; only 6.6.6 depends on ws `~8.21.0`.
-
-- **Fleet sequencing:** bump to `@sonordev/site-kit@4.0.3` and run
-  `npm install` (or `pnpm install`) so the lockfile regenerates. `npm ci`
-  against an un-regenerated lockfile will fail rather than quietly reinstall
-  the vulnerable tree, which is the intended behaviour — the floors make the
-  stale lock impossible to satisfy instead of merely unlucky.
-- No API change, no bundle change. socket.io is still lazy-loaded on chat open
-  by `engage/socket-loader`, so the resolved versions move but nothing new
-  enters the initial chunk.
-- The Engage `ChatWidget` websocket path was verified end-to-end against the
-  patched stack: namespace handshake, `visitor:message`/`message` round trip,
-  binary attachments over the patched parser, and auto-reconnect after a
-  transport drop.
-### Repo hygiene that came out of the same investigation
-
-- **One lockfile.** The repo tracked both `package-lock.json` and
-  `pnpm-lock.yaml`. They had drifted six days apart, and the npm one was the
-  artifact still holding the vulnerable pins. `package-lock.json` is deleted
-  and gitignored, and `packageManager` now pins pnpm so the fork can't recur.
-- **`pnpm audit` was never going to catch this.** No lockfile ships in the
-  published tarball, so a repo-local audit describes a tree no consumer ever
-  installs — and it buries the signal under devDependency noise. New
-  `pnpm audit:consumer` packs the real tarball, installs it into a throwaway
-  project, and audits the production tree only. It runs in `prepublishOnly`,
-  so a release that would hand the fleet an advisory now fails to publish.
-- **`react-markdown` stays a dependency, deliberately.** It's 85 packages /
-  ~8 MB for one component, so making it an optional peer looks like free
-  savings. It isn't possible: bundlers resolve even a *dynamic* import at
-  build time, so a site that didn't install it fails with "Module not found"
-  before any runtime fallback can run — confirmed against Next 16 / Turbopack.
-  A test now records this so the experiment doesn't get repeated.
-
-## 4.0.2 — 2026-08-13
-
-Managed forms are Server Components. The client runtime is now the optional
-half.
-
-### The form renders on the server, with zero JavaScript
-
-`ManagedForm` was a client component for reasons that stopped being true:
-it fetched its own config (4.0's `getFormConfig` ended that) and it could
-only submit over JSON (4.0.1's native endpoint ended that). Nobody moved the
-boundary afterward, so every site that put a form on a page shipped the whole
-forms runtime — validation, spotlight, celebration, momentum — as an INITIAL
-script on the LCP-critical path.
-
-Measured on upforge.io's homepage: 48 KB of form code in the initial chunk set
-cost **6 Lighthouse points** (88 → 82, LCP 3.8s → 4.7s). Deferring the client
-component recovered the score but deleted the form from the HTML, taking the
-no-JS floor and crawlable fields with it. Neither half was acceptable.
-
-```tsx
-import { ServerForm } from '@sonordev/site-kit/forms/server'
-
-export default function ContactPage() {
-  return <ServerForm formId="contact" returnTo="https://example.com/contact/" />
-}
-```
-
-One line, in a Server Component. Fetches the config server-side, renders a
-complete working `<form>` into the HTML, and upgrades it to the interactive
-experience at idle. Client JS on the critical path drops from ~48 KB to
-**4.8 KB** (the enhancer plus the shared idle gate) — a 90% cut — and the
-Lighthouse regression is fully recovered at 88 with LCP back to 3.8s.
-
-The progression is now: no JS at all → native POST, works. JS but pre-idle →
-native POST, works. Post-idle → JSON submit with the full experience. Chunk
-fails to load → the shell stays and still submits. A form is never blank.
-
-- **`ServerForm`** (`forms/server`) — the recommended way to render a form.
-- **`StaticForm`** (`forms/server`) — the zero-JS form alone, if you want to
-  compose the enhancement yourself. `enhance={false}` on ServerForm ships no
-  form JavaScript at all.
-- **`FormEnhancer`** (`forms`) — the ~3 KB client boundary that swaps the
-  shell for the interactive form at idle.
-- The client `ManagedForm` is unchanged and still exported. Use it when the
-  form must live inside an existing client component (a modal, a chat panel)
-  where a Server Component cannot go.
-
-### Entrance animation for the idle upgrade
-
-An above-the-fold form upgrades while the visitor is looking at it, so the
-swap must not pop. The mount wrapper carries `data-sk-form-mount`
-(`shell` → `enhanced`) and the arriving form gets `data-sk-enter` for one
-frame, with defaults driven by `--sk-form-enter-duration` / `-easing` /
-`-distance`. `enter="none"` opts out; `enter="custom"` emits the hooks and no
-styles so the site owns the animation entirely. All defaults collapse under
-`prefers-reduced-motion`.
-
-### One field renderer, two modes
-
-`FormField` lost its `'use client'` directive and now renders controlled
-(client) or uncontrolled/`defaultValue` (server) from the same code, so the
-shell and the enhancement cannot drift — a divergence would show up to a
-visitor as a jump on swap. `field-parity` tests pin the structure.
-
-- The file-upload branch moved to `FileField.tsx`; it was the only thing in
-  the file that needed state.
-- `DatePicker` and `FileField` are now **injected and fetched on demand**
-  (`useFieldControls`) rather than imported. Importing them put 17 hooks in
-  `FormField`'s chunk and the build stamped the whole thing `'use client'` —
-  a "server" field renderer that shipped 38 KB of date picker to render one
-  text input. Injection alone still left both in the forms entry's eager
-  graph, so every form paid for a date picker most forms have no field for;
-  the hook now loads each control only when the field list contains one.
-  Until the chunk lands — and in static mode, and if the fetch fails — the
-  browser's own `date` / `file` controls render, and they submit natively
-  anyway, so the wait is invisible and never costs a submission.
-- `normalizeFormConfig` moved to `normalize-config.ts` so the server shell and
-  the client fetch share one normalizer.
-
-### Fixed: a `url` field rendered no input at all
-
-`FieldType` had no `'url'` branch, so a field configured as a URL emitted its
-label and **no control**. On upforge.io's free-audit form that silently
-dropped the one required value the entire feature needs — the site to audit —
-and it only surfaced by grepping the built HTML. Every field type is now
-covered by a test asserting it emits a named, submittable control.
-
-## 4.0.1 — 2026-08-13
-
-### No-JS submissions: the floor under every managed form
-
-A single-step managed form now works with JavaScript disabled. When the
-forms/config response carries a `native_token` (sonor-api mints it once the
-no-JS train is deployed), the classic form — which is already the SSR/no-JS
-surface under the spotlight and stage experiences — renders a real
-`action`/`method` pointing at `POST /api/public/forms/submit-native`, plus a
-hidden `_sk_token` control field. With JS running, nothing changes: the
-existing `onSubmit` intercepts and the JSON path wins. Without JS, the
-browser performs an ordinary form-encoded POST, sonor-api authenticates via
-the signed token, runs the honeypot + render-timestamp + quarantine spam
-stack, and 303s back to the page with `?submitted=1`.
-
-- New `nativeReturnTo` prop on `ManagedForm` — the absolute page URL the
-  native redirect should land on. Optional: without it the server falls back
-  to the Referer origin (right site, homepage instead of this page).
-- Token-less configs (older API deployments) and multi-step forms render
-  exactly as before — no action attribute, so a browser is never pointed at
-  an endpoint that would reject it. Step navigation is JS; the native floor
-  is deliberately single-step, which is the overwhelming lead-capture case.
-- `getApiConfig`'s server branch now honors `SONOR_API_URL`, matching what
-  `SiteKitLayout` feeds the client — so SSR-rendered absolute URLs point at
-  the same API the browser uses (staging sites included).
-
-## 4.0.0 — 2026-08-13
-
-Major release. Absorbs the unpublished 3.9.0 (Next 16 alignment + the
-redirect rail off the hot path) and adds the provider-island removal, the
-OG card factory, site search, events polish, and hardening below.
-
-### The provider island is gone (children are never wrapped)
-
-The prerender-bailout / force-static / remount-flash bug class traced to one
-structural fact: client providers wrapped page children. Now children render
-first and every module mounts as a keyed childless sibling. SiteKitProvider
-(deprecated) and SiteKitIdentityProvider are removed; useSiteKitIdentity reads
-the storage singletons; useSignal reads a buffering module store and — BREAKING
-— no longer throws outside a bridge (bounded no-op stub instead).
-
-### OG card factory
-
-`sonor-setup og` renders og.config.ts (defineOgCard — the SITE owns the theme;
-Sonor brand is only the zero-config seed) through headless Chrome to a static
-public/og.png + a 300px legibility preview, and verifies metadata wiring.
-Doctor gains `og.card`. 24 of 66 fleet sites had no card.
-
-### Per-entity runtime OG cards (tier 2)
-
-createOgImageRoute() in @sonordev/site-kit/og/route: unique cards per blog
-post/event/product via next/og in a route handler — resolver returns the
-card (title, page photo as absolute URL, theme) or null for a clean 404.
-Satori constraints documented; fonts passed as ArrayBuffers.
-
-### Fleet migration command
-
-sonor-setup next16 wraps the official middleware-to-proxy codemod and
-verifies the result with the doctor check — fleet sweeps as a command
-instead of bespoke bash.
-
-### Parts contract on legacy commerce components
-
-CalendarView (nav, month title), EventTile, OfferingCard, and EventsWidget
-cards now carry data-sk-part alongside data-category.
-
-### Site search (new)
-
-@sonordev/site-kit/search: useSiteSearch + unstyled SiteSearch against the new
-POST /api/public/search (pages + posts + offerings, ranked; multi-site aware).
-Degrades to inert against older APIs.
-
-### Events polish
-
-ICS + Google Calendar links (RFC 5545, all-day correct), EventJsonLd
-(schema.org/Event with seat-count-honest availability), CapacityBadge
-(spots_remaining is the only honest sold-out signal), and EventsAgenda — the
-month-grouped list layout with range + all-day support and data-sk-part
-theming hooks. Commerce surfaces expose data-category/data-offering-type.
-
-### Security posture (verified during the 4.0 audit)
-
-Of the tracked key-leak bypass trio: the blog barrel is pinned shut by the
-client-entry boundary test; Echo chat HTTP flows through sonorFetch's token
-path; and the chat WebSocket handshake carries NO credential at all (project
-+ visitor + session ids only). The remaining bypass lives in
-@sonordev/agency-site-kit and ships with that package's own release. No-JS
-form submission is specced (docs/SITE-KIT-4.0-NOJS-FORMS.md) but gated on
-sonor-api spam-defense work — a native POST cannot carry a reCAPTCHA token.
-
-### Hardening
-
-- Honeypot is CSS-proof: inert + belt-and-suspenders inline hiding +
-  data-sk-honeypot (a site's own form CSS once un-hid it).
-- SpeculationRules component / `speculation` prop on SiteKitLayout:
-  declarative prerender-on-intent for static sites, zero JS.
-- Scaffold emits og.config.ts; postbuild gating recipe: `sonor-setup verify`
-  and `doctor` already exit non-zero on error-level checks — wire them into CI.
-
-### Absorbed from the unpublished 3.9.0
-
-Next 16 alignment + the redirect rail moves off the hot path. Driven by fleet
-research: both redirect tables have 0 rows platform-wide, yet 33 sites paid a
-blocking rules fetch on every request (measured: ~130ms warm TTFB, 2.4s cold).
-
-### Redirects: bounded, and resolvable at the 404 boundary
-
-- `fetchRedirectRules` now aborts at 300ms (`fetchTimeoutMs`, guarded
-  AbortSignal.timeout) and caches failures for 30s. Previously it failed open
-  on error but NOT on slow — a degraded Portal became every site's TTFB.
-  Build-time `generateNextRedirects` uses a 10s budget.
-- NEW `resolveManagedRedirect()` in `@sonordev/site-kit/redirects/not-found`:
-  resolve managed redirects in `app/not-found.tsx` — the only place they can
-  matter — instead of on 100% of page loads. Dashboard edits still apply
-  instantly. The proxy always stamps `x-sk-path` (pathname + search) on the
-  request so the 404 boundary knows the URL; pure header write, no fetch.
-- Proxy `redirects: true` still works (now bounded) but is documented as
-  legacy; the scaffold emits `redirects: false` + the not-found resolver.
-
-### Next 16 correctness
-
-- Scaffold emits `proxy.ts` (not deprecated `middleware.ts`) with the matcher
-  INLINED — `export const config = siteKitMatcher` is a Turbopack build error
-  because matchers must be statically analyzable. All docs updated;
-  `siteKitMatcher` is now documented as a copy-source reference value.
-- Doctor: recognizes `proxy.ts`/`src/proxy.ts` (previously reported "No
-  middleware file" on correctly-configured Next 16 sites), errors on any
-  `runtime` option in proxy files (Next 16 throws on it), warns on the
-  deprecated middleware convention with the official codemod command, and no
-  longer gates on netlify.toml (UI-deployed Netlify sites have none).
-
-### Commerce
-
-- `getUpcomingEvents`/`getNextEvent` (server) now use the events endpoint and
-  return offerings WITH `schedules[]` and `category` embedded — the offerings
-  list endpoint never embedded schedules, so the server helper was useless for
-  calendars and sites hand-rolled fetchers. Falls back to the legacy query on
-  older APIs.
-- Commerce surfaces expose `data-category` / `data-offering-type` attributes
-  (CalendarView/EventCalendar chips, EventTile, EventsWidget, OfferingCard) so
-  sites can theme categories with CSS attribute selectors.
-
-### Forms
-
-- NEW `getFormConfig()` in `@sonordev/site-kit/forms/server` +
-  `ManagedForm initialConfig` prop: fetch the form config in a Server
-  Component and the fields render on the first client render — no more
-  "Loading form..." flash. Falls back to the client fetch on any failure, and
-  both paths share one normalizer so they cannot drift.
-- **NEW: the delight layer.** Forms are the conversion surface — filling one
-  now feels like progress, not paperwork. All zero-config on every
-  `ManagedForm`, all `--sk-primary`-themed, all collapsed by
-  `prefers-reduced-motion`:
-  - `FormCelebration` success state: brand disc springs in, the check draws
-    itself, a particle burst fires, plus a soft haptic tick on mobile.
-  - Field lock-in: a valid field earns a drawn check + ripple ring and a
-    one-shot border flash. Focused fields lift with a brand aura.
-  - `FormMomentum`: a fields-completed meter (endowed progress) with live
-    sheen, advance flash, leading-edge spark, and an "N of M" label that
-    flips to READY and charges the bar when every requirement clears.
-  - The submit button wakes up (pop + breathing glow) the moment the form is
-    actually submittable, and pulses while submitting
-    (`data-sk-ready` / `data-sk-state` hooks for site-level styling).
-  - Every element carries `data-sk-part` hooks, and all chrome mixes
-    `--sk-primary` toward `currentColor`, so it stays visible even inside
-    sections painted with the brand color itself.
-- **NEW `FormReveal` — entrance theater for form/CTA tiles.** The tile
-  animates open when scrolled into view and its contents cascade in; pass a
-  brand mark (`logoPath`) and the logo pops in and **morphs into the tile**
-  (MorphSVG, free since GSAP 3.13) before handing off to the cascade.
-  `animate` prop: `auto` (default — static when the tile starts inside the
-  viewport, so above-the-fold forms never pay an entrance), `off`, `reveal`,
-  `morph`. SSR markup is always fully visible (LCP-safe by construction);
-  reduced motion, missing IntersectionObserver, or a failed chunk all degrade
-  to static, with a safety un-hide timer behind the observer.
-- **gsap is now a site-kit dependency** (`^3.13.0`), loaded ONLY via the
-  shared idle loader (`loadGsap` / `warmGsapAtIdle`): dynamically imported in
-  its own chunk, prefetched at browser idle, never in the critical bundle —
-  static tiles still warm it so interaction animations are ready on first
-  touch. Fleet sites already shipping their own gsap dedupe to one copy.
-- Inputs now inline `color: var(--sk-input-text, #111827)` paired with the
-  existing `--sk-input-bg` default, and the border width is themeable via
-  `--sk-input-border-w`. fg/bg must come from the same source: the kit used
-  to inline the background but let `color` cascade from the section, which
-  produced cream-on-white inputs on brand-colored panels. Theme inputs
-  through the `--sk-input-*` variables (raw `input {}` rules can't beat the
-  inline layer).
-
-### Scaffold & guardrails
-
-- Scaffold writes `.env.local` (skipped when present) instead of
-  `.env.example` — one real env file per project.
-- Doctor: new `images.dims-drift` check compares `<Image width/height>`
-  against the referenced SVG's actual viewBox and warns on >2% drift (a
-  re-exported logo changed aspect 3.16:1 → 5.52:1 and the stale props kept
-  the old shape).
-- New regression test bans raw `crypto.randomUUID()` outside the guarded
-  shared helpers — the 3.6.0 hydration-crash class, made unrepresentable.
-
-## 3.3.1 — 2026-07-21
-
-Sitemap-sync safety release. Fixes the "sitemap oscillation" bug where the
-`sonor-register-sitemap --auto-discover` postbuild fought a site's
-`app/sitemap.{ts,js}` on every build — deleting and recreating each other's
-`seo_pages` rows, and destroying managed metadata, Signal optimizations, LLM
-schemas, and Search Console history on real (especially dynamic-route) pages.
-No API surface changes. **Behavior change:** `--auto-discover` no longer does a
-`full-replace` by default — see below. Recommended for every site.
-
-### Fixed: `--auto-discover` can no longer delete pages it can't see
-
-The root cause was architectural: a filesystem scan of `app/` is structurally
-**incomplete** — it can't enumerate the params of a dynamic route
-(`/work/[slug]`, `/blog/[cat]/[id]`) and it ignores the app's sitemap `exclude`
-config. Driving a `full-replace` from that incomplete set tells the API to
-delete every page not in it. Two independent fixes, both shipped:
-
-- **Self-skip when a sitemap route exists.** `--auto-discover` now detects an
-  `app/sitemap.{ts,tsx,js,jsx,mjs}` (or `src/app/…`) and **skips entirely** with
-  a clear message. That route's `/sitemap.xml` is the authoritative page set,
-  and site-kit's runtime `SitemapSync` already mirrors it (additively). The
-  postbuild line is now **safe to leave in any site** — it self-skips. The
-  brand-profile push still runs on the skip path, so keeping the line doesn't
-  silently stop refreshing brand awareness.
-- **Additive by default otherwise.** When there's no sitemap route (a
-  pure-static site where the CLI is the only page source), the sync is now
-  `additive` — it adds/updates pages but **never deletes**. Pass the new
-  **`--full-replace`** flag to opt back into pruning removed pages.
-
-The same `autoDiscover → full-replace` default was also fixed in the
-programmatic `registerLocalSitemap` export (`@sonordev/site-kit/seo/server`):
-it now defaults to `additive`; pass `mode: 'full-replace'` for the old behavior.
-
-### Changed: consolidated triplicated sitemap logic
-
-`inferPageType` and the sitemap URL/path-normalization helpers were copy-pasted
-(and had already drifted) across `createSitemap`, the runtime `SitemapSync`
-component, and the CLI. They now live in one pure, browser-safe module
-(`sitemap/shared.ts`), and the filesystem route-discovery — previously duplicated
-between the CLI impl and `seo/routing.ts` — is unified in `sitemap/discover.ts`.
-No public API change.
-
-## 3.3.0 — 2026-07-21
-
-BookingWidget friction + theming release. No breaking changes — a drop-in bump
-for every 3.x site. New behavior is on by default but can be disabled.
-
-### Added: auto-select first available day (`autoSelectFirstDay`, default true)
-
-When the calendar loads, the widget now probes availability starting at the
-earliest bookable day (min-notice aware, bounded sequential probe, stops at the
-first day with open slots), selects that day, and shows its times — guests land
-on pickable times instead of an empty "select a date" state. The probe's fetch
-is reused for the selected day (no duplicate request), aborts cleanly if the
-guest clicks a day mid-probe, and fails silent (manual picking still works).
-Pass `autoSelectFirstDay={false}` to restore the old behavior.
-
-### Added: skeleton loading for time slots
-
-Slot loading (and the auto-select probe) now renders shimmer placeholders
-sized like real slot buttons instead of a spinner, so the times column doesn't
-collapse and jump. Respects `prefers-reduced-motion`.
-
-### Fixed: dark-theme derived colors
-
-`--sk-primary-light` now mixes the primary color with `styles.backgroundColor`
-instead of always white, so selected-slot/hold-notice tints no longer glow on
-dark panels. The error banner's hardcoded light-red palette is now derived from
-`--sk-error` + `--sk-bg` the same way.
-
-### Improved: tap targets and keyboard focus
-
-Time-slot buttons and the slot Confirm button are now ≥44px tall and the
-submit button ≥48px (mobile tap-target guidance); all widget buttons and links
-get a visible `:focus-visible` outline in the primary color.
-
-## 3.2.1 — 2026-07-13
-
-Accessibility patch. No API changes, no breaking changes — a drop-in bump for
-every 3.x site. Recommended for any site using the commerce (events/products),
-forms, engage, or booking widgets.
-
-### Fixed: default status colors now pass WCAG AA contrast (both directions)
-
-The default `--sk-error`, `--sk-success`, and `--sk-warning` tokens shipped as
-the Tailwind -500/-600 shades, all of which fail WCAG AA (4.5:1) — both as text
-on white and as a solid background under white text. Lighthouse flagged this on
-mahjcincy.com, where the events widget's "N left" urgency badge renders white on
-`--sk-error`. Because contrast is symmetric, one darker value fixes both uses:
-
-| Token | Was | Now | Contrast on white |
-|-------|-----|-----|-------------------|
-| `--sk-error` | `#ef4444` (red-500) | `#dc2626` (red-600) | 3.76 → **4.83** ✓ |
-| `--sk-success` | `#059669` (emerald-600) | `#047857` (emerald-700) | 3.77 → **5.48** ✓ |
-| `--sk-warning` | `#d97706` (amber-600) | `#b45309` (amber-700) | 3.19 → **5.02** ✓ |
-
-- Updated the canonical defaults in `brand.css`, the `forms/styles.css` mirror,
-  every inline `var(--sk-error, …)` fallback across forms/engage/commerce, the
-  `BookingWidget` inline token root (whose success/warning were the even-lighter
-  -500 shades), and the one hardcoded `#ef4444` in `ManagedForm` (now uses the
-  token). The light-tint error-bg pattern (`--sk-error-bg #fef2f2` + `#dc2626`
-  text) was already correct and is unchanged.
-- This only moves the **defaults**. Any site that sets its own `--sk-error`
-  (etc.) is unaffected. Sites can't pick up the fix without re-installing, so as
-  an interim they may override `--sk-error: #dc2626` in their own `:root`.
-- New `src/brand/status-contrast.test.ts` (vitest) reads the real CSS defaults
-  and every inline status fallback in `src/` and asserts each clears 4.5:1 on
-  white — with a teeth self-check proving it catches the old failing values. The
-  integration axe harness now renders an error/success/warning swatch block on
-  the `/form` fixture route (real-browser contrast) plus a teeth check that flips
-  the tokens back to the -500s and confirms axe reports `color-contrast`.
-
-## 3.2.0 — 2026-07-13
-
-Transport, trust, and tooling release. No breaking changes; recommended target for every 2.x/3.0.x site. (Supersedes unpublished 3.0.6/3.1.0 work.)
-
-### New: agent-native CLI — the site-kit toolchain is now driveable by coding agents
-
-`sonor-setup` is built to be driven by a coding agent (Claude Code et al.), not
-just a human reading `README.md`. North star: an agent takes a bare Next.js repo
-→ a fully wired, **verified-green** Sonor site with zero human intervention. See
-`docs/SITE-KIT-AGENT-NATIVE.md` and the new shipped `AGENTS.md`.
-
-- **Machine-readable everything.** New shared output layer (`src/cli/agent/`):
-  every agent-native command supports `--json`, emitting exactly one stable
-  envelope (`schemaVersion: 1`) to stdout — all human logs go to stderr, so
-  stdout is always `JSON.parse`-clean. Frozen exit-code set (`0` OK · `1` FAILED
-  · `2` USAGE · `3` CONFIG · `4` NETWORK · `5` INTERNAL). Wired on `verify`,
-  `doctor`, `status`, `codemod`, `manifest`, `init`, `install`, `upgrade`.
-- **Never hangs an agent.** When `--json`, `--yes`, or a non-TTY is detected, no
-  command creates an interactive prompt — a command that needs input exits `3`
-  with an actionable `fix` naming the exact flag. `init` runs fully
-  non-interactive with `--api-key … --yes`.
-- **`verify` — the definition of done.** New command composes static health + a
-  key-validity ping + a **post-build SSR check** (asserts the built/live page
-  server-renders real content instead of shipping an empty shell + RSC flight
-  data — the #1 fleet perf trap). Exit 0 only when the integration is genuinely
-  green. `--url <url>` checks a live/preview deploy; `--offline` skips the ping.
-- **`doctor` — fast, offline health** with stable check ids (`env.api-key`,
-  `layout.sitekit`, `ssr.render`, `middleware.netlify`, `key.valid`, …), each
-  carrying a `fix`/`fixCommand`. `status` is the same engine for humans. All
-  check logic is consolidated in one library (`src/cli/agent/checks.ts`) — no
-  more forked copies (the old `status.ts` hand-rolled them; a broken WIP
-  `doctor.ts` imported non-exported helpers — both replaced).
-- **`codemod` — deterministic 2.x→3.x transforms.** Offline, idempotent,
-  minimal-diff. Dry-run by default; `--write` applies (with `.bak`); `--check`
-  is the CI/agent gate (exit 1 if pending). Transforms: `provider-to-layout`
-  (SiteKitProvider→SiteKitLayout), `uptrade-to-sonor` (package/env/token
-  remnants; flags `uptrade_` key *values* it can't mint a replacement for), and
-  `analytics-sibling` (detects the SSR-bailout wrapper and flags the exact fix
-  rather than risk a blind rewrite).
-- **The package ships its own agent instructions.** `AGENTS.md`
-  (consumer/agent-facing), `agent-manifest.json` (machine manifest — modules
-  derived from `package.json` exports so it can't drift, plus env contract,
-  blessed patterns, and failure modes), and a Claude Code skill under `skills/`
-  are now in the npm tarball. Read them with `cat node_modules/@sonordev/site-kit/AGENTS.md`
-  or `npx sonor-setup manifest --json` — no web access needed. Contributor
-  branding rules moved to `CONTRIBUTING.md`.
-- **MCP server: evaluated, deferred.** For agents with a shell (the target),
-  `npx sonor-setup <cmd> --json` already beats an MCP tool on install/config
-  friction and CI parity — recommendation is CLI-first, revisit a thin MCP
-  wrapper only for shell-less agents (rationale in the design doc §9).
-
-### New: canonical client transport (`sonorFetch`)
-
-Every client-side module (analytics, forms, commerce, engage config/telemetry,
-maps, images, SitemapSync) now routes through one shared transport instead of
-bare `fetch()`:
-
-- **Per-attempt timeout + retry with backoff.** A hung request left to the
-  browser's own network timeout logs `net::ERR_TIMED_OUT` and fails the
-  Lighthouse best-practices `errors-in-console` audit (observed in production
-  via SitemapSync). Non-idempotent paths (checkout, payment intents, uploads,
-  page-views) run `retries: 0` — timeout only, never an automatic retry.
-- **`x-sitekit-version` header on every request.** The platform can now see
-  which kit version each site runs from live traffic — the foundation for
-  fleet visibility.
-- **Auth circuit breaker.** After a 401/403 the key is paused for 5 minutes
-  with ONE friendly `console.info` — a site on a stale or canceled key no
-  longer spams the API or the visitor's console.
-- **Beacons keep the key out of URLs.** Unload-time telemetry (session end,
-  scroll depth) previously used `sendBeacon` with `?key=` in the URL — which
-  lands in server/CDN access logs. It now uses keepalive fetch with header
-  auth (`sonorBeacon`).
-- Deliberately excluded: `engage/ChatWidget` message paths (Echo replies can
-  exceed the transport timeout; will be brought under with tuned limits).
-
-### New: canonical cross-repo contracts
-
-`sites/contract` (host normalization), `seo-pages/contract` (seo_pages row
-resolution), `portfolio/contract` (Lighthouse KPI display policy), and
-`forms/contract` (honeypot field) — the logic that previously lived as
-"keep these in sync" comment-twins across sonor-api, signal-api, and
-agency-site-kit. Both APIs now import these; they require this release.
-
-### New: agent-native CLI engine + integration harness
-
-All CLI health logic consolidated in `cli/agent/checks.ts` with a stable JSON
-envelope (`--json` everywhere, exit codes as verdicts, fix commands attached):
-`doctor` (fast, offline-by-default), `status` (same engine, network on), and
-`verify` (health + key + SSR = definition of done). The package ships an
-agent manifest (`agent-manifest.json`) generated at build. A Playwright
-integration harness (fixture Next app: SSR-integrity, axe, zero-console, and
-per-entry gzipped bundle budgets) now gates `npm publish`.
-
-### New: `@sonordev/site-kit/fleet` — fleet heartbeat (contract v1)
-
-Fire-and-forget, idle-deferred heartbeat reporting the site's own build
-fingerprint (kit version, active client modules, Next.js version) so the
-platform can see what the fleet actually runs. No visitor data; project
-identity resolves server-side from x-api-key like every public endpoint.
-`fleet/contract` is the wire contract for the sonor-api ingest side (same
-pattern as `llms/contract` / `slots/contract`).
-
-### New: `sonor-setup doctor`
-
-Executable health checks with `--json` (stable schema; exit code is the
-verdict) so agents and CI can consume it: env + API connectivity + **real key
-validity** (authed endpoint, not `/health`), **SSR integrity** (detects pages
-that bailed to client rendering — only RSC flight data, no content tags),
-sitemap, llms.txt, and the Netlify `runtime: 'nodejs'` middleware trap.
-
-### New: client auth hardening — minted tokens, domain-binding, per-key limits
-
-The project API key (`sonor_{uuid8}_{secret}`) is a long-lived secret; shipping
-it to every visitor's browser (`window.__SITE_KIT_API_KEY__`) let anyone scrape
-it and reuse it anywhere, forever — the form-spam incident. Three layered,
-backward-compatible changes (2.x sites keep sending raw keys forever):
-
-- **Minted tokens.** `SiteKitLayout` (a server component) now mints a
-  short-lived (~1h), project-scoped HMAC token server-to-server and injects
-  THAT instead of the raw key. `sonorFetch` refreshes a stale/expired token
-  transparently (a static page's seed can be days old on first view) and
-  retries once on a 401. If minting is unavailable (older API, transient
-  outage) the layout falls back to the raw key — the build never breaks. New
-  endpoints on api.sonor.io: `POST /api/public/site-token` (mint, server-side),
-  `POST /api/public/site-token/refresh` (browser, domain-bound). Guards on both
-  APIs accept a token OR a raw key.
-- **Domain-binding.** A browser-originated credential is checked against the
-  project's registered domains (`projects.domain` + settings + the multi-site
-  `site` hosts). Server-to-server calls (no Origin) are unaffected, so SSR keeps
-  working. Rolls out log-only; enforced per project via
-  `settings.site_auth.enforce_domain_binding` once its domains are verified. Not
-  a hard wall (Origin is forgeable by non-browser clients) — it stops casual
-  cross-origin reuse and pairs with the token + rate-limit layers.
-- **Per-key rate limits.** Token mint/refresh and the AI/widget endpoints are
-  throttled per project credential (not per IP), so a distributed bot on one
-  site's key hits one bucket. Signal API's global throttler is now key-scoped.
-- **Incident response.** Bumping `settings.site_auth.token_version` instantly
-  invalidates every outstanding token for a project; deactivating a key kills
-  its tokens.
-- **doctor:** adds `Token minting` + `Key is domain-bound` online checks.
-
-Set `SITE_TOKEN_SECRET` (same value on api + signal) to enable minting; unset,
-the kit transparently keeps injecting the raw key. See `docs/CLIENT-AUTH.md` for
-the endpoint contracts and rollout runbook.
-
-### Fixed
-
-- **Forms: honeypot input hidden from assistive technology.** The spam
-  honeypot (`_hp_field`) had no `aria-hidden`, so screen readers announced an
-  unlabeled input and Lighthouse failed the accessibility `label` audit on any
-  page with a managed form. Now `aria-hidden="true"`.
-- **Default brand color now passes WCAG AA color-contrast.** `--sk-primary`
-  (and the mirrored `--sk-btn-bg` in `forms/styles.css`) was blue-500
-  `#3b82f6` — only ~3.68:1 against the white button text, a "serious" axe
-  color-contrast violation. Any fleet site that shipped the default without
-  overriding its brand color failed Lighthouse's a11y contrast audit on the
-  submit button. The default is now blue-600 `#2563eb` (~5.2:1, AA), hover
-  blue-700 `#1d4ed8`. Sites that set their own `--sk-primary` are unaffected.
-  The same blue-500 default was swept out of every `var(--sk-primary, …)`
-  fallback and JS brand default across forms/blog/engage so the package-wide
-  default is consistent (commerce already defaulted to `#2563eb`).
-- **Load-path `console.error` downgraded to `console.warn`** in commerce,
-  maps, and images. Error-level console output from transient API failures
-  fails the best-practices audit; the kit's production paths now stay at
-  warn/info.
-- `sonor-setup status`: the Sitemap Sync check only recognized legacy
-  `uptrade` postbuild scripts; it now recognizes `sonor` ones.
-
-### Internal
-
-- `fetchWithRetry` moved from `src/forms/` to `src/shared/` — single source of
-  truth for resilient fetch; `sonorFetch` wraps it. Removed maps' third
-  hand-rolled retry implementation.
-- `src/shared/version.ts` (`SITE_KIT_VERSION`) — asserted against
-  package.json in tests and at publish (verify-dts).
-
-## 3.0.0 — 2026-06-18
-
-**Site-Kit 3.0 — "the site acts."** The 3.0 line begins the shift from
-site-as-sensor to site-as-actuator (see `docs/SITE-KIT-3.0-VISION.md`). This
-first release ships the foundation: the Managed Slots primitive, visitor→contact
-identity binding, and an opt-in edge identity/segment pass. It is **additive
-over 2.x** for every existing module (SEO, Analytics, Engage, Forms, Blog, CMS,
-Commerce, …) — upgrading does not change their behavior.
-
-### New module: `@sonordev/site-kit/slots` — Managed Slots (Pillar 1 of the 3.0 vision)
-
-First slice of the 3.0 "the site acts" spine (see `docs/SITE-KIT-3.0-VISION.md` and
-`docs/SITE-KIT-3.0-SPEC-SLOTS.md`). A slot is a named, Sonor-managed text region
-inside an element the developer still owns:
-
-```tsx
-<h1 className="hero-title">
-  <ManagedSlot id="home-hero-headline">
-    New Homes in Cincinnati & Northern Kentucky
-  </ManagedSlot>
-</h1>
-```
-
-No managed content → the static children render, byte-for-byte what the site ships
-today. Content exists in Sonor (owner edit or approved Signal proposal) → it renders
-instead, with no deploy.
-
-Design guarantees, all tested:
-
-- **Static-safe**: RSC resolution via ISR-cached fetch (`tags: ['sonor-slots']`),
-  no request access, fragment render with zero hydration cost — pages stay `○`.
-- **Fallback-first**: every failure (missing key, network, HTTP error, 404 while the
-  API endpoint isn't deployed, malformed payload) renders the fallback; slots can
-  never break a build or a page.
-- **Signed from contract v1**: payloads carry an HMAC-SHA256 signature keyed with the
-  project API key (`slots/contract`, shared with sonor-api like `llms/contract`);
-  site-kit drops anything unsigned or tampered. Plain-text content type only in v1 —
-  rendered escaped, never as HTML.
-- `createSlotsRevalidateHandler` gives Sonor an on-demand cache-bust webhook so
-  approved changes go live in seconds.
-
-Resolve requests also report each slot's current static text (`fallback`,
-sent automatically when ManagedSlot children are a plain string) so the
-dashboard editor shows the live copy next to the slot id instead of a bare
-identifier.
-
-New module is Sonor-only auth (`SONOR_API_KEY`) — 3.0 code does not implement the
-deprecated `UPTRADE_*` fallbacks. The server side is BUILT: sonor-api `SlotsModule`
-(`POST /api/public/slots/resolve` + portal CRUD with `checkProjectAccess` tenancy
-asserts), the `managed_slots` table (applied 2026-06-11), and the dashboard editor
-(Website module → Text Slots). The June 2026 security remediation landed first;
-this endpoint follows the hardened pattern.
-
-Also: vitest now includes `.test.tsx` files (`vitest.config.ts` include pattern).
-
-### Forms: visitor identity on submissions (Pillar 5 — identity graph)
-
-`submitForm` now sends the anonymous visitor id (`_sk_vid`, the same id Analytics
-and Signal stamp on page views) with each submission, so Sonor can bind the
-resulting CRM lead to its browsing session — closing the page → lead attribution
-loop. Additive and silent: no change to the `submitForm` signature or to callers
-(`<ManagedForm>` / `useForm`). Pairs with the sonor-api side that stores
-`form_submissions.visitor_id` and stamps `contacts.visitor_id` on routing.
-
-### Middleware: opt-in edge identity + visitor segment (the "one edge pass")
-
-`createMiddleware({ identity: true })` adds an edge identity pass to the existing
-redirects + security + discovery chain. When enabled it ensures a first-party
-`_sk_vid` visitor cookie (server-authoritative id) and resolves a coarse visitor
-segment — new-vs-returning + marketing source (paid / organic / social /
-referral / direct) + campaign — into a `_sk_seg` cookie, for segment-aware slots
-and personalization. **Purely additive: it only writes cookies, never changes
-the rendered HTML, so it stays LCP/static-safe. Default OFF** — existing sites
-are unaffected until they opt in. New exports from `@sonordev/site-kit/middleware`:
-`resolveVisitorSegment`, `encodeSegment`, `decodeSegment`, and the `VisitorSegment`
-/ `SegmentSource` types.
-
-### Upgrading from 2.x
-
-This release is additive for every shipped module — a drop-in upgrade. Notes:
-
-- The long-deprecated `SiteKitProvider` is **not** part of the public exports;
-  use `SiteKitLayout` (RSC-safe), which has been the recommended pattern since 2.x.
-- 3.0 modules (`slots`, the edge `identity` pass) are **Sonor-only** auth
-  (`SONOR_API_KEY`). The deprecated `UPTRADE_*` fallbacks still work for the
-  older modules so pre-rebrand sites keep building.
-
-## 2.9.0
-
-### /llms.txt now prerenders statically — no more "Dynamic server usage" build errors
-
-Every consumer site's `next build` logged a scary (but non-fatal) error:
-
-```
-@sonordev/llms: Error generating llms.txt: Error: Dynamic server usage:
-Route /llms.txt couldn't be rendered statically because it used `request.headers`.
-```
-
-and the route was demoted to dynamic (`ƒ`), served as a serverless function
-with no static/CDN caching — for what is effectively a static text file.
-
-**Cause.** `createLLMsTxtHandler` / `createLLMsFullTxtHandler` read
-`request.headers.get('if-none-match')` to serve 304s themselves. During
-prerendering, ANY access to the incoming Request's headers throws
-`DynamicServerError` and flags the route dynamic — and because the access sat
-inside the handlers' own `try/catch`, the error was also caught and logged on
-every build.
-
-**Fix.** The returned GET handlers no longer touch the incoming `Request` at
-all (signature is now `(request?: Request) => Promise<Response>`). In-handler
-`If-None-Match`/304 matching is removed; the weak `ETag` is still emitted and
-conditional requests are answered by the Next static layer / CDN, which
-already does this for prerendered responses. With the route opted into
-prerendering (Next 15+: `export const revalidate = 3600` or
-`dynamic = 'force-static'` in the route file), `/llms.txt` now builds as
-static (`○`) and the build-log error is gone. Verified on a Next 16.1.2
-consumer site: `ƒ /llms.txt` + error before, `○ /llms.txt` + clean log after.
-
-### New `baseUrl` option for llms.txt link resolution
-
-`GenerateLLMSTxtOptions` (and therefore both handler factories and
-`generateLLMsTxt` / `generateLLMsFullTxt`) accepts an explicit `baseUrl`,
-matching the sitemap helper's convention. The link base resolves as:
-
-1. explicit `baseUrl` option
-2. Portal/local `business.website` (existing behavior, unchanged default)
-3. `NEXT_PUBLIC_SITE_URL`, then `SITE_URL` env vars
-
-It is never derived from request headers, so the route stays statically
-prerenderable. The resolved base is normalized (trailing slashes stripped —
-this also fixes double-slash links like `https://x.com//about` when
-`business.website` had a trailing slash), and sections that previously
-required `business.website` (`## Optional`, the `linkToFullLlms` block, the
-`**Website:**` header line) now also render when only an env base is
-available.
-
-### Breaking changes
-
-None for the documented usage (`export const GET = createLLMsTxtHandler()`).
-Behavioral note: the handlers no longer answer conditional requests with 304
-themselves — on dynamic deployments that's now handled by the CDN layer (or
-clients simply get a full 200, which is valid HTTP).
-
-### `@sonordev/site-kit/sync` now ships its TypeScript declarations
-
-The `./sync` subpath (`BookingWidget`) shipped runtime JS but **no `.d.ts`**
-in 2.7.2 and 2.8.1. `package.json` pointed `exports["./sync"].types` at
-`./dist/sync/index.d.ts`, but that file was never built — so consumer sites
-on `moduleResolution: "bundler"` + `strict` hit:
-
-```
-error TS2307: Cannot find module '@sonordev/site-kit/sync'
-```
-
-and had to add an ambient module shim to compile.
-
-**Cause.** `tsup.config.ts` kept the DTS entry list as a hand-maintained
-second copy of the main `entry` map, and the two drifted: `sync/index` was
-in `entry` (so JS built) but missing from `dts.entry` (so no declarations).
-
-**Fix.** The DTS entry set is now *derived* from the single `entry` map
-(every entry minus the CLI binaries), so a subpath can never again ship JS
-without types. The `prepublishOnly` guard was also strengthened — it now
-verifies **every** `exports[*].types` target exists on disk (via
-`scripts/verify-dts.cjs`), not just the root `index.d.ts`, so a missing
-subpath declaration fails the publish instead of slipping through.
-
-Consumer sites that added a `*/sync.d.ts` ambient shim can delete it once on
-this version.
-
-### Breaking changes
-
-None. Packaging-only fix — no runtime, API, or export-surface change.
-
-## 2.8.1
-
-### `@sonordev/site-kit/reputation/server` — RSC-safe entry
-
-The reputation module's API functions (`fetchReviews`, `fetchReviewStats`)
-were previously bundled with `TestimonialSection`, which is a Client
-Component. Because the shared chunk carried a `'use client'` directive,
-calling the API functions from a React Server Component failed at build
-time with *"Attempted to call fetchReviews() from the server but
-fetchReviews is on the client"*.
-
-2.9.0 adds a new `./reputation/server` entry point that exports only the
-data fetchers and types — no client taint — so they can be called from
-RSC, route handlers, `generateMetadata`, etc.
-
-```ts
-// React Server Component
-import { fetchReviews, fetchReviewStats } from '@sonordev/site-kit/reputation/server'
-
-export default async function Page() {
-  const reviews = await fetchReviews({ limit: 6 })
-  // ...
-}
-
-// Client Component — unchanged
-import { TestimonialSection } from '@sonordev/site-kit/reputation'
-```
-
-This matches the existing split on `./seo/server`, `./blog/server`,
-`./images/server`, and `./commerce/server`.
-
-### Breaking changes
-
-None. The existing `./reputation` entry continues to export
-`TestimonialSection`, `fetchReviews`, `fetchReviewStats`, and types for
-backwards compatibility — only the recommended import path for RSC
-contexts has changed.
-
----
-
-## 2.8.0
-
-### Multi-site projects — forms + sitemap
-
-`@sonordev/site-kit` 2.7.0 introduced the `analytics.site` dimension so one
-Sonor project could host many sub-sites (e.g. the True Power Systems project
-hosts truepowersystems.com + 16 state-themed microsites) with each event
-tagged by its host. 2.8.0 extends the same dimension across two more
-surfaces so the dashboard can scope by sub-site everywhere:
-
-- **`SitemapSync`** now sends the host (`__SITE_KIT_SITE__`) alongside each
-  registration, tagging every `seo_pages` row with its sub-site. The Sonor
-  dashboard's page-tree sidebar filters by this when the site picker is
-  set.
-- **`submitForm`** includes `site` in submission metadata so leads are
-  attributed to the originating microsite even after the form definition
-  is moved or merged. Persisted on `form_submissions.site`.
-- **`formsApi.sync` / `CreateFormInput`** gained an optional `site` field.
-  CLI scripts (`migrate-contact-form.ts`) should derive it from
-  `NEXT_PUBLIC_SITE_URL` host so one Sonor project can host one form per
-  microsite (`ohio-quote → ohiopowerstudies.com`,
-  `georgia-quote → georgiapowerstudies.com`, etc.).
-
-The Sonor API (`api.sonor.io`) accepts `?site=ohiopowerstudies.com` on
-every analytics, SEO, and forms read endpoint to scope results. The
-dashboard's site picker (introduced alongside this release) sets this
-filter globally per project.
-
-### Breaking changes
-
-None. All new fields are optional — single-site projects continue to work
-unchanged, and older versions of site-kit can still submit forms / sync
-sitemaps (the server stores `site = NULL` for those events).
-
----
-
-## 2.7.0
-
-### Multi-site analytics
-
-- **`AnalyticsConfig.site`** — new sub-site identifier. One Sonor project
-  can now host many sites (e.g. TPS hosting truepowersystems.com + 16
-  microsites) with every page-view, event, session, scroll, web-vital, and
-  heatmap event tagged by host. Resolved with precedence: explicit
-  `analytics.site` > `NEXT_PUBLIC_SITE_URL` host > `window.location.host`.
-- **`window.__SITE_KIT_SITE__`** — global set by SiteKitClientProviders,
-  read by every analytics/sitemap surface.
-
-### Breaking changes
-
-None. Sites that don't opt in continue to behave exactly as before.
-
----
-
-## 2.4.0
-
-### GEO / AEO
-
-- **LLM GEO contract** (`src/llms/contract.ts`, `LLM_GEO_CONTRACT.md`) — versioned payload rules, `sanitizeLlmsPublicSummary`, `pickManagedLlmSchemaForJsonLd`.
-- **llms.txt** — optional `optionalPagePaths`, `linkToFullLlms`; page list prefers `llms_public_summary`; `meta.last_updated` in header blockquote when API returns it.
-- **Handlers** — `llmsResponseHeaders`, weak `ETag`, `stale-while-revalidate`, `If-None-Match` / 304; `GET` handlers receive `Request` (use `export const GET = createLLMsTxtHandler()`).
-- **`buildAiDiscoveryHeaders`** — opt-in `Link: rel=describedby` for `/llms.txt`.
-- **Sitemap** — `includeLlmsTxtInSitemap`, `includeLlmsFullTxtInSitemap` (default false).
-- **`LLMSchema`** — filtered JSON-LD + `isPartOf` → `WebSite` when project `site_url` exists.
-- **`createWebSiteOrganizationStub`** — optional grounding when Portal does not emit org/site nodes.
-- **CLI `status`** — optional `llms.txt` smoke check when `NEXT_PUBLIC_SITE_URL` / `SITE_BASE_URL` set.
-- **SiteKitLayout** — `showLlmsTxtFooterLink` (default false).
-
-## 1.3.0
-
-### Performance
-
-- **Suspense-wrapped all async server components** — `ManagedSchema`, `LLMSchema`, `ManagedFAQ`, `ManagedContent`, `ManagedInternalLinks`, `ManagedScripts`, `ManagedNoScripts`, and `LocationPageContent` now stream independently. API fetches no longer block page content from flushing, dramatically improving LCP on pages that use these components. Zero config — works automatically for all sites.
-- **Parallelized ManagedSchema API calls** — `getSchemaMarkups`, `getSEOPageData`, and `getEntityEnhancedSchema` now run via `Promise.all` instead of sequentially, cutting schema fetch time to the slowest single call.
-- **Deferred AnalyticsProvider by default** — `AnalyticsProvider` now lazy-loads internally (dynamic import, `ssr: false`) so analytics JS is excluded from the critical hydration path without sites needing `next/dynamic` wrappers.
-
-### Breaking Changes
-
-- None. All changes are backwards-compatible. Sites that already wrap these components in `<Suspense>` will have a harmless double-wrap (no functional impact).
-
----
-
-## 1.2.10
-
-### Fixes
-
-- Deferred analytics loading pattern added to `AnalyticsProvider` export
-
----
-
-## 1.2.9
-
-### Changes
-
-- Package rename from `@uptrademedia/site-kit` to `@sonordev/site-kit`
-- Updated all API endpoints from `api.uptrademedia.com` to `api.sonor.io`
-- Updated CLI commands from `uptrade-*` to `sonor-*`
-
----
-
-## 1.2.2 and earlier
-
-- Legacy versions published under `@uptrademedia/site-kit`