@sonordev/site-kit 7.0.1 → 7.1.0

package/CHANGELOG.md

@@ -0,0 +1,3606 @@
+# @sonordev/site-kit Changelog
+
+## 7.1.0
+
+### Live updates (new)
+
+- **`@sonordev/site-kit/revalidate`**: the route Sonor calls when content
+  changes, as a one-line file. Pages stay cached, and an edit in Sonor
+  (managed copy, metadata, an article, a portfolio item) regenerates only the
+  pages and cache tags it touched, within seconds:
+
+  ```ts
+  // app/api/seo-revalidate/route.ts
+  export { POST } from '@sonordev/site-kit/revalidate'
+  ```
+
+  `createRevalidateRoute({ publicationBasePath })` for a site with articles.
+  It reads `SONOR_API_KEY` on every call, so there's no new secret. See
+  [Live updates](src/revalidate/README.md).
+- **Ping**: `{ "ping": true }` on its own regenerates nothing and answers
+  `{ ok, ping, version }`, so Sonor can confirm the route is installed before
+  it promises an edit will go live in seconds. `createSeoRevalidationHandler`
+  answers it too, so existing routes built on it need no change.
+- SEO fetches carry the `seo` cache tag and slot fetches take theirs from the
+  shared list (`SITE_CACHE_TAGS`, `@sonordev/contracts/site-cache`), the
+  names Sonor sends.
+- The Managed copy docs pointed at a separate slots route with its own
+  secret, which Sonor never called. They point at the one route now.
+
+### Edit on page (new)
+
+- Sonor's dashboard can open the live site with its managed copy outlined:
+  click any of it to edit it, and see text, rich-text and link changes on the
+  page before publishing. Nothing to install beyond 7.1: no login, no secret,
+  no route. The overlay loads only when Sonor frames the page with
+  `?sonor_edit`; every other visitor gets an unchanged page and about 40
+  bytes of extra JavaScript. It finds copy by its visible text, so markup and
+  CSS stay exactly as written, and it never writes anything itself.
+- `DEFAULT_FRAME_ANCESTORS` adds `https://app.sonor.io`, so the dashboard
+  can frame the site. A site that sets its own `frame-ancestors` should use
+  the default list.
+
+### Managed copy: rich text, links and lists
+
+- **`<ManagedRichText>`**: paragraphs, bold, italic, links and lists, edited
+  in Sonor and rendered as elements (never HTML). A string child is the
+  fallback.
+- **`<ManagedLink>`**: a label and a destination editable together; renders
+  a plain `<a>`, or pass a render function for your own button.
+- **`<ManagedList>`**: repeatable items (title, body, link, image) with your
+  markup, e.g. a services grid or an FAQ.
+- `getSlot(id, { type, fallbackValue })` resolves any of them without a
+  component. A value is only used when its kind matches what the code
+  renders, so changing a slot's kind in code falls back rather than breaking.
+- Slots contract v2: the signature covers the structured value. Sonor still
+  serves text to older site-kit releases.
+- New docs page: [Managed copy](src/slots/README.md).
+- List items take photos: Sonor uploads them with the project's files and
+  records their size, so a gallery is a `<ManagedList>` (see "Lists with
+  photos" in the Managed copy docs).
+
+### Deprecated (removed in 8.0)
+
+- **`./cms`, `./cms/server`, `./website/cms`, `./website/cms/server`**: the
+  Sanity CMS is retired. No project had CMS pages and Sonor no longer serves
+  them, so these render nothing. Use managed copy.
+- **`<ManagedContent>` / `getManagedContentData`** (`./seo`): content blocks
+  are retired for the same reason. Use `<ManagedRichText>`.
+
+## 7.0.2
+
+- The docs ship in the package: every module README, the migration guide and
+  this changelog, listed in a new `docs.json`. [sonor.dev](https://sonor.dev)
+  reads them straight from the published release, so the docs there always
+  match `latest`.
+- README fixes: a broken link to the articles docs, "Portal" where it meant
+  Sonor, and a reCAPTCHA variable site-kit no longer reads.
+
+## 7.0.1
+
+- `reportToolCallsToSonor` sends the `x-sitekit-version` header every other
+  site-kit request carries, so Sonor records which site-kit a tool call came
+  from (its `kit_version` was empty).
+
+## 7.0.0
+
+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.
+
+### 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` /
+  `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` +
+  `send_inquiry`. `send_inquiry` goes through Sonor's agent-inquiry door:
+  the person must have said yes, and the call carries the agent's badge and
+  `human_approved`.
+- **Who called.** `createMcpHandler` takes `onToolCall`; `reportToolCallsToSonor`
+  sends each call (tool, outcome, the agent's name, never the arguments) to
+  Sonor after the response. The dashboard's AI Visibility tab and Echo show
+  which agents used the site, and Echo offers the fix for a failing tool.
+- **`npx sonor-setup mcp`** writes the whole wiring: server file, endpoint
+  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`
+  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.
+- **Discovery.** llms.txt gains an "Agent access" section (added to the
+  build-time file automatically for the built-in server only; `mcp: false`,
+  `createSitemap({ llmsAgentAccess })` or `--no-agent-access` turn it off), and
+  `createProxy({ llmsDiscovery: { mcpServerCard: true } })` links the card as
+  `rel="service-desc"`.
+
+### Breaking
+
+- **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).
+- **The root entry is types-only** (plus `SITE_KIT_VERSION`). `BookingWidget`
+  → `./sync`, `AffiliatesWidget`/`useAffiliates` → the new `./affiliates`,
+  commerce → `./commerce`, `ManagedImage` → `./website/images`, signal →
+  `./signal`, reputation → `./reputation`, redirects → `./seo/redirects`,
+  `LandingPage` → `./website/landing`; `formatBookingTime`/`formatBookingDate`
+  are `formatTime`/`formatDate` on `./sync`. The codemod rewrites these.
+- **The setup CLI is its own package, `sonor-setup`.** `npx sonor-setup`
+  works unchanged; a site whose scripts run it adds it as a dev dependency
+  (the codemod does). The `site-kit` bin alias is gone.
+  `sonor-register-sitemap` stays here.
+- **No source maps in the package**, and no `.d.ts.map`s.
+- **Removed, no site used them:** `./search`, `./search/contract`,
+  `./redirects/not-found` (with `x-sk-path` and `SK_PATH_HEADER`), `./setup`,
+  `LocationPageContent`/`getLocationSection`, `identifyTopicClusters`,
+  `formatContentSignals`, the `SiteKitConfig` type, and the postinstall GEO
+  bootstrap (site-kit runs nothing at install; use `npx sonor-setup geo`).
+- **The register-sitemap bin's .env precedence is Next.js's**: the real
+  environment wins, then `.env.production.local`, `.env.local`,
+  `.env.production`, `.env`. It used to let `.env.local` override a
+  variable the host had set. `dotenv` is gone (Node's `util.parseEnv`).
+
+### Smaller and lighter
+
+- The tarball is **0.60 MB** (2.24 MB unpacked), from 4.03 MB (17 MB) in 6.x.
+- **One markdown library, `marked`.** The chat widget renders its lexer
+  tokens as React elements (raw HTML shows as text; only http(s), mailto,
+  tel and relative links keep an address). react-markdown and its 85
+  packages (~8 MB) are gone from every site's install.
+
+### New
+
+- **Cache Components.** A site can turn on Next 16's `cacheComponents`:
+  nothing in site-kit's render path reads the wall clock or `Math.random`
+  any more (deadlines, TTLs and jitter use `performance.now()`; the forms'
+  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.
+- **`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.
+
+### Fixed
+
+- The seo/website homes one directory deeper than their source shipped
+  declarations that pointed at themselves (e.g. `seo/og/route` exported
+  nothing to TypeScript); `./website/slots` dropped `./slots`' default
+  export; `BookingWidget` and `TestimonialSection` could land in a
+  non-client entry and fail a server page's prerender. verify-dts and the
+  build now check all three.
+
+### Kept through 7.x
+
+- Every 6.6 path (`./sitemap`, `./og`, `./llms`, `./images`, `./engage`,
+  `./middleware`, …) still works as an alias of its new home, marked
+  deprecated in the agent manifest; so do `createMiddleware` and
+  `SiteKitMiddlewareConfig`. They go in 8.0.
+- `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`