@sonordev/site-kit 7.1.1 → 7.2.0

package/src/{engage → chat}/README.md

@@ -1,58 +1,69 @@
-# Engage — `@sonordev/site-kit/engage`
+# Website chat — `@sonordev/site-kit/chat`
 
-Popups, nudges, bars, slide-ins, and chat widgets — all configured from the Sonor dashboard.
+Echo's chat launcher and conversation on your site, configured in Sonor
+(Messages → Chat settings). AI answers, live handoff to your team, and an
+offline form when nobody's around.
 
 ## Usage
 
-Auto-included by `SiteKitLayout`. For standalone use:
+`SiteKitLayout` mounts it for you, after the page goes idle:
+
+```tsx
+<SiteKitLayout>{children}</SiteKitLayout>                          // chat on (default)
+<SiteKitLayout chat={{ offsetBottom: '88px' }}>{children}</SiteKitLayout>
+<SiteKitLayout chat={false}>{children}</SiteKitLayout>             // no chat
+```
+
+On a site without `SiteKitLayout`, mount `SiteChat` the same way:
 
 ```tsx
 'use client'
-import { EngageWidget } from '@sonordev/site-kit/engage'
-
-export default function Layout({ children }) {
-  return (
-    <>
-      {children}
-      <EngageWidget />
-    </>
-  )
+import { SiteChat } from '@sonordev/site-kit/chat'
+
+export function Chat() {
+  return <SiteChat position="bottom-right" />
 }
 ```
 
+`SiteChat` waits for the browser to go idle, skips cross-origin frames and
+localhost (like analytics), and downloads the chat widget only when it
+renders. `ChatWidget` is the widget itself, for a page that resolves those
+choices on its own.
+
 ## Props
 
 ```ts
-interface EngageWidgetProps {
-  apiUrl?: string             // Default: https://api.sonor.io
-  apiKey?: string             // From SiteKitLayout or env
-  projectId?: string          // For chat routing
+interface SiteChatProps {
+  apiUrl?: string                            // Default: from SiteKitLayout, else https://api.sonor.io
+  apiKey?: string                            // Default: from SiteKitLayout
+  projectId?: string                         // For chat routing. Resolved from the key when absent
   position?: 'bottom-right' | 'bottom-left'  // Default: 'bottom-right'
   offsetBottom?: string | number             // Default: '20px'. See "Launcher placement"
-  zIndex?: number             // Default: 9999. Popups, nudges, bars and the chat. See "Stacking"
-  chatEnabled?: boolean       // Default: true. See "The chat switch"
-  debug?: boolean
+  zIndex?: number                            // Default: 9999. See "Stacking"
+  allowInFrame?: boolean                     // Show inside a cross-origin frame. Default: false
+  allowLocalhost?: boolean                   // Show on localhost. Default: false
 }
 ```
 
-Through `SiteKitLayout`, the same options go in `engage={{ ... }}`.
+Through `SiteKitLayout`, the placement options go in `chat={{ ... }}`. The
+deprecated `engage={{ ... }}` still works through 7.x.
 
 ## The chat switch
 
-Echo follows the project's **Enable Chat Widget** switch in Sonor (Engage,
-Chat settings). A project that has never saved chat settings counts as on, so
-Echo is on by default and only an owner who switches it off hides it. It also
-needs the project's **Engage** module on (Project Settings); without it Sonor
-answers off, since the chat has nowhere to take a visitor's message.
+Echo follows the project's **Show the chat widget** switch in Sonor
+(Messages → Chat settings). A project that has never saved chat settings
+counts as on, so Echo is on by default and only an owner who switches it off
+hides it. It also needs the project's **Website chat** module on (Project
+Settings); without it Sonor answers off, since the chat has nowhere to take a
+visitor's message.
 
 - The launcher appears once `GET /engage/widget/config` answers. Nothing
   renders before that, so a switched-off site never flashes a launcher, and
   it never starts Echo's availability polling.
 - If the config can't be fetched, the launcher stays hidden. The chat can't
   run without the API anyway.
-- `chatEnabled: false` (or `engage={false}`) in code still turns chat off
-  whatever the switch says. Code can turn Echo off; it can't force it on over
-  the owner's switch.
+- `chat={false}` in code still turns chat off whatever the switch says. Code
+  can turn Echo off; it can't force it on over the owner's switch.
 
 ## Liquid Glass (6.1.0)
 
@@ -75,7 +86,7 @@ recipe (`src/shared/glass.tsx`), the same material as the mobile CTA bar
   panel, and otherwise pulls it toward black (light panel) or white (dark
   panel) just far enough to clear it: `#d4af37` gold becomes `#887023`. Fills
   (launcher, avatar, the visitor's bubbles, buttons) keep the raw brand. One
-  helper decides this, `src/engage/brand-color.ts`; route any new brand
+  helper decides this, `src/chat/brand-color.ts`; route any new brand
   foreground through it. `--sk-primary` can be hex, `rgb()` or `hsl()`.
 - **Fields are 16px.** iOS Safari zooms the whole page into any focused field
   under 16px; the chat input and the inline Echo forms were 13.5-14px.
@@ -104,7 +115,7 @@ it without `!important`. Don't write that override; declare the offset instead.
 **A fixed offset, every page:** pass `offsetBottom`.
 
 ```tsx
-<SiteKitLayout engage={{ offsetBottom: '88px' }}>{children}</SiteKitLayout>
+<SiteKitLayout chat={{ offsetBottom: '88px' }}>{children}</SiteKitLayout>
 ```
 
 Any CSS length works (`'5.5rem'`, `'calc(4rem + 8px)'`); a number is pixels.
@@ -148,13 +159,14 @@ popup maxHeight = 100dvh - launcher bottom - 100px
 
 ### Stacking
 
-`zIndex` is the one layer everything Engage renders sits on: popups, nudges,
-bars and the chat launcher. The chat popup sits one layer beneath the
-launcher. The default is 9999, above almost anything a site draws, so lower it
-when your own fixed UI (a mobile menu, a cookie banner) has to cover the chat:
+`zIndex` is the layer the chat launcher sits on, with the chat window one
+layer beneath it. Through `SiteKitLayout` the same number also stacks the
+site's popups, banners and toasts. The default is 9999, above almost anything
+a site draws, so lower it when your own fixed UI (a mobile menu, a cookie
+banner) has to cover the chat:
 
 ```tsx
-<SiteKitLayout engage={{ zIndex: 40 }}>{children}</SiteKitLayout>
+<SiteKitLayout chat={{ zIndex: 40 }}>{children}</SiteKitLayout>
 ```
 
 ```
@@ -162,9 +174,9 @@ launcher z-index = zIndex (default 9999)
 popup z-index    = zIndex - 1
 ```
 
-At `zIndex` 0 or below the popup shares the launcher's layer instead, because
--1 would put it behind the page's own content. The launcher still paints on
-top.
+At `zIndex` 0 or below the chat window shares the launcher's layer instead,
+because -1 would put it behind the page's own content. The launcher still
+paints on top.
 
 ### Layout vs visual viewport on phones
 
@@ -194,29 +206,9 @@ It's opt-in: while a field has focus the gap grows to the keyboard's height,
 so everything that reads it rides above the keyboard. `useVisualViewportGap()`
 is the hook form for an existing client component.
 
-## Element Types
-
-| Type | Description |
-|------|-------------|
-| `popup` | Modal overlay with CTA |
-| `nudge` | Small corner notification |
-| `bar` | Top/bottom sticky bar |
-| `slide-in` | Side panel |
-| `chat` | AI/live chat widget |
+## Chat config
 
-## Targeting & Triggers
-
-All configured in the Sonor dashboard — no code changes needed:
-
-- **Page targeting** — include/exclude paths with wildcard support
-- **Device targeting** — desktop, mobile, tablet
-- **Visitor targeting** — new vs returning visitors
-- **Triggers** — immediate, delay (seconds), scroll (%), exit-intent, click, custom
-- **Frequency capping** — once, once-per-session, every N days
-
-## Chat Widget
-
-Supports AI mode (Echo), live mode, and hybrid (AI + human handoff):
+AI mode (Echo), live mode, and hybrid (AI with a human handoff). `ChatWidget` takes these as `config`; Sonor sends the rest from Chat settings:
 
 ```ts
 interface ChatConfig {
@@ -236,6 +228,15 @@ interface ChatConfig {
 }
 ```
 
-## Tracking
+## Popups
+
+Popups, banners and toasts are their own module now:
+[Popups and banners](../website/README.md) (`@sonordev/site-kit/website/popups`).
+
+## `@sonordev/site-kit/engage` (deprecated)
 
-Impressions and clicks are automatically tracked via the Sonor API. Shares visitor ID (`_sk_vid`) with Analytics for cross-module attribution.
+Engage was retired in Sonor. Its entry stays through 7.x so old imports keep
+building: `ChatWidget` and the chat types re-export from here, and
+`EngageWidget` draws `SiteChat` and `SitePopups`. Engage Studio's renderer
+(`DesignRenderer`) is gone; popups render from blocks. Import
+`@sonordev/site-kit/chat` and `@sonordev/site-kit/website/popups` instead.

package/src/cta-bar/README.md

@@ -3,17 +3,17 @@
 The Liquid Glass mobile CTA bar (6.1.0). A floating frosted capsule that
 keeps a site's one or two highest-intent actions a thumb away on phones.
 
-It replaces every hand-rolled sticky mobile bar in the fleet. Those eleven
-copies had each solved part of the same problem set; this one does all of it:
+It replaces a hand-rolled sticky mobile bar, and handles what each of those
+ends up solving on its own:
 
-| Behaviour | Before | Here |
-|---|---|---|
-| Hide while the form it points at is on screen | two sites, hand-built | `hideOver` |
-| Stay off the hero until the hero CTA scrolls away | one site | `showAfter` |
-| Get out from under the Echo launcher | two sites (`body:has`, a 72px dead corner) | automatic |
-| Ride out the iOS toolbar collapsing | one site (a GSAP tween) | `--sk-vv-layout-gap` |
-| Get out of the way of the keyboard | nobody | `hideWhileTyping` |
-| Tell Sonor which action converts | one site (hand-wired) | `cta_click` event |
+| Behaviour | How |
+|---|---|
+| Hide while the form it points at is on screen | `hideOver` |
+| Stay off the hero until the hero CTA scrolls away | `showAfter` |
+| Get out from under the Echo launcher | automatic |
+| Ride out the iOS toolbar collapsing | `--sk-vv-layout-gap` |
+| Get out of the way of the keyboard | `hideWhileTyping` |
+| Tell Sonor which action converts | `cta_click` event |
 
 ## Use it
 
@@ -28,7 +28,7 @@ import { CtaBar, CtaBarAction } from '@sonordev/site-kit/cta-bar'
   <main>{children}</main>
   <Footer />
   <CtaBar label="Call or request a quote" hideOver="#quote">
-    <CtaBarAction href="tel:+15135550100" variant="secondary" icon={<Phone />}>
+    <CtaBarAction href="tel:+15555550100" variant="secondary" icon={<Phone />}>
       Call now
     </CtaBarAction>
     <CtaBarAction as={Link} href="/quote" icon={<ClipboardCheck />}>

package/src/forms/README.md

@@ -47,8 +47,8 @@ Three things hold for every experience:
   the form still works and still submits.
 - **Nobody pays for what they don't use.** Experience code is loaded on
   demand, so a `classic` form downloads none of it.
-- **Same engine.** Identical validation, honeypot, reCAPTCHA, and CRM routing
-  — an experience is a rendering, not a fork.
+- **Same engine.** Identical validation, spam protection and CRM routing.
+  An experience is a rendering, not a fork.
 
 ### Editing what the form says back
 
@@ -78,12 +78,12 @@ import { useForm } from '@sonordev/site-kit/forms'
 
 export function ContactForm() {
   const {
-    fields, values, errors, setFieldValue, submit, isSubmitting,
+    fields, values, errors, setFieldValue, handleSubmit, toolAttributes, isSubmitting,
     step, totalSteps, isMultiStep, nextStep, prevStep, isLastStep,
   } = useForm('contact-form')
 
   return (
-    <form onSubmit={(e) => { e.preventDefault(); submit() }}>
+    <form {...toolAttributes} onSubmit={handleSubmit}>
       {fields.map(field => (
         <div key={field.slug}>
           <label>{field.label}</label>
@@ -166,7 +166,12 @@ interface UseFormReturn {
   canGoPrev: boolean
   isLastStep: boolean
   validate: () => boolean
-  submit: () => Promise<void>
+  // Resolves with what happened: { status: 'sent' | 'invalid' | 'failed' | 'busy' | 'next_step', ... }
+  submit: (options?: FormSubmitOptions) => Promise<FormSubmitOutcome>
+  // A ready-made <form onSubmit>: steps or submits, and answers an AI agent (see below)
+  handleSubmit: (event: FormEvent<HTMLFormElement>) => void
+  // WebMCP attributes for your <form>; null until the config loads
+  toolAttributes: { toolname: string; tooldescription: string } | null
   isSubmitting: boolean
   isComplete: boolean
   reset: () => void
@@ -202,13 +207,56 @@ Submissions auto-route based on `form_type`:
 | `newsletter` | Email Subscribers | Newsletter signups |
 | `custom` | Form Submissions only | Custom handling |
 
-## Anti-Bot Protection
-
-- **Honeypot fields** — hidden fields that bots fill (server-side rejection)
-- **reCAPTCHA Enterprise** — optional Google reCAPTCHA v3 scoring
-- **Submission timing** — forms that submit in < 3 seconds are flagged
-- **Composite spam scoring** — name patterns, email domain, user-agent, IP rate, message content
-- **NestJS ThrottlerGuard** — 10 requests/minute per IP at HTTP level
+## Spam protection
+
+Sonor screens every submission on its side, and there's nothing to configure.
+It only accepts a submission with evidence that a real browser rendered the
+page, which `<ManagedForm>` and `useForm` send automatically. A hand-rolled
+`fetch` to the forms API, or a proxy through your own API route, can't send
+it, so Sonor refuses those before anything is written: the visitor sees an
+error and you get no lead. Submit through site-kit, and define the form's
+fields in Sonor so both can render and validate them.
+
+## Agent-ready forms (7.2.0)
+
+People increasingly ask an AI assistant to fill out a form for them: a quote
+request, a booking, a newsletter signup. Assistants act on what the page's
+markup says each control is, so managed forms now say it clearly. There's
+nothing to configure.
+
+- **Autocomplete tokens.** Name, email, phone, company, website and address
+  fields carry the right `autocomplete` token (`given-name`, `email`, `tel`,
+  `organization`, `url`, `postal-code`, ...), read from the field's CRM
+  destination in Sonor, then its type, slug and label. Browser autofill and
+  password managers use the same tokens.
+- **Accessible wiring.** Error and help text are tied to their control
+  (`aria-describedby`), an errored control says so (`aria-invalid`), radio and
+  checkbox groups are named by their question, and rating stars by their
+  value.
+- **WebMCP.** Every interactive managed form carries the declarative WebMCP
+  attributes (`toolname`, `tooldescription`), so a browser agent that supports
+  WebMCP can treat it as a tool. It fills the same fields a person would, and
+  the submit runs the same validation. There's no `toolautosubmit`: the
+  assistant fills the form and the person it's helping presses Send.
+  Browsers without WebMCP ignore the attributes.
+- **Agent-sent leads are tagged.** When the browser reports that an agent
+  pressed submit (`SubmitEvent.agentInvoked`), the submission carries that
+  flag and the lead is tagged in Sonor, so you can see how those leads compare
+  over time. It's the browser's word, so it never changes how a submission is
+  checked. The agent is handed the outcome of its submit (`respondWith`).
+- **Nothing typed before the form loads is lost.** `ServerForm` renders the
+  form in the page HTML and loads the interactive version at idle. Since
+  7.2.0, typing into the server-rendered form starts that upgrade at once and
+  what was typed carries over, and a Send pressed before the upgrade is held
+  and sent the moment it lands. The server-rendered Send button stays disabled
+  until the page can catch the click.
+
+With `useForm`, spread `toolAttributes` on your `<form>` and use
+`handleSubmit` as its `onSubmit` to get the same behavior.
+
+`ServerForm`'s `enhance` prop is ignored since 7.2.0. Only the interactive
+form can send a managed form, so `enhance={false}` only ever produced a form
+that silently went nowhere.
 
 ## Styles
 

package/src/layout/README.md

@@ -28,9 +28,11 @@ interface SiteKitLayoutProps {
   children: React.ReactNode
   apiKey?: string                         // Defaults to SONOR_API_KEY env var
   apiUrl?: string                         // Defaults to SONOR_API_URL, then https://api.sonor.io
-  projectId?: string                      // For Engage chat routing (auto-resolved if omitted)
+  projectId?: string                      // For chat routing (auto-resolved if omitted)
   analytics?: boolean | AnalyticsConfig   // Default: true
-  engage?: boolean | EngageConfig         // Default: true
+  chat?: boolean | ChatLayoutConfig       // Default: true (website chat; config = launcher placement)
+  popups?: boolean                        // Default: true (Website → Popups & Banners)
+  engage?: boolean | EngageConfig         // Deprecated: false turns chat and popups off; an object configures the launcher
   signal?: boolean | SignalConfig         // Default: false
   sitemapSync?: boolean                   // Default: false (build-time + server reconciler own this)
   fleet?: boolean                         // Default: true (once-per-session kit version heartbeat)
@@ -43,7 +45,7 @@ interface SiteKitLayoutProps {
 }
 ```
 
-Module options live with each module: [Analytics](../analytics/README.md) (`trackPageViews`, `excludePaths`, `site`, `allowInFrame`, `allowLocalhost`) and [Engage](../engage/README.md) (`position`, `chatEnabled`, and launcher placement).
+Module options live with each module: [Analytics](../analytics/README.md) (`trackPageViews`, `excludePaths`, `site`, `allowInFrame`, `allowLocalhost`) [Website chat](../chat/README.md) (`position`, `offsetBottom`, `zIndex`, `allowInFrame`) and [Popups and banners](../website/README.md).
 
 ## What It Composes
 
@@ -54,12 +56,13 @@ Module options live with each module: [Analytics](../analytics/README.md) (`trac
 
 **Client-side (lazy-loaded island):**
 - `AnalyticsProvider` — page views, scroll depth, heatmap clicks, Web Vitals
-- `EngageWidget` — popups, nudges, chat
+- `SitePopups` — popups, banners and toasts
+- `SiteChat` — website chat (Echo)
 - `SignalBridge` — A/B experiments, behavior tracking (opt-in)
 - `SitemapSync` — parses `/sitemap.xml` and syncs to Sonor (opt-in)
 - `FleetHeartbeat` — reports the kit version and enabled modules once per session
 
-Since 4.0.0 none of these wrap your page. `{children}` renders first and every module mounts after it as a childless sibling, so `SiteKitLayout` never pushes a route to client rendering. Analytics, Engage, SitemapSync and the heartbeat also wait for window load + idle (or the first interaction) unless you pass `defer={false}`. `SignalBridge` isn't deferred, so experiment variants apply early. Visitor and session IDs come from a shared storage singleton rather than a provider.
+Since 4.0.0 none of these wrap your page. `{children}` renders first and every module mounts after it as a childless sibling, so `SiteKitLayout` never pushes a route to client rendering. Analytics, chat, popups, SitemapSync and the heartbeat also wait for window load + idle (or the first interaction) unless you pass `defer={false}`. `SignalBridge` isn't deferred, so experiment variants apply early. Visitor and session IDs come from a shared storage singleton rather than a provider.
 
 ## Note
 

package/src/llms/README.md

@@ -315,7 +315,7 @@ Business description...
 
 ## Portfolio & Case Studies
 
-### [Project Title](https://live-url.com)
+### [Project Title](https://example.com/work/project)
 
 Description of the project.
 
@@ -355,7 +355,7 @@ We follow a proven process...
 
 ### Family Law Basics
 Topic: Family Law
-Area: Cincinnati, OH
+Area: Springfield
 Articles: 8
 Service page: https://example.com/services/family-law
 Pillar: [Complete Guide to Family Law](/article/family-law-guide)
@@ -515,7 +515,7 @@ export default function DivorcePage() {
         title="Key Facts"
         points={[
           '25+ years of family law experience',
-          'Serving Northern Kentucky and Cincinnati',
+          'Serving Springfield and the surrounding counties',
           'Free initial consultation available',
         ]}
         speakable

package/src/mcp/README.md

@@ -82,11 +82,11 @@ endpoint and card (automatic in the build-time file once `/api/mcp` exists),
 and `createProxy({ llmsDiscovery: { siteUrl, mcpServerCard: true } })` adds
 `Link: <.../.well-known/mcp-server-card>; rel="service-desc"`.
 
-### A custom MCP server (upforge.io) is left alone
+### A custom MCP server is left alone
 
 The built-in tools are opt-in, never automatic. A site that runs its own MCP
-server (its own tools, transport names or llms.txt section, like upforge.io
-or a re-site-kit site) is a **custom implementation**, and site-kit keeps its
+server (its own tools, transport names or llms.txt section, like a
+re-site-kit site) is a **custom implementation**, and site-kit keeps its
 hands off:
 
 | What | Built-in server | Custom server |
@@ -257,8 +257,8 @@ What the relay does, so you don't have to re-derive it:
 
 The header and label default to `x-site-mcp-transport` and
 `site-mcp-transport-v1`. A site with names already live passes the same
-`{ header, label }` to all three factories (upforge.io uses
-`x-upforge-mcp-transport` / `upforge-mcp-transport-v1`). This entry is Node
+`{ header, label }` to all three factories (for example
+`x-example-mcp-transport` / `example-mcp-transport-v1`). This entry is Node
 only and imports no `server-only`, so the plain-Node function can load it. It
 is not re-exported from `@sonordev/site-kit/mcp`, which stays runtime-neutral.
 
@@ -333,8 +333,8 @@ single property check — not a request, and not a byte of page weight.
 `<WebMcpTools>` registers thin wrappers that POST `tools/call` to this site's
 own endpoint, so the in-page tool and the remote tool run the same server-side
 handler. It also keeps `SONOR_API_KEY` out of the client bundle — registering
-real handlers client-side would pull server code into a `'use client'` graph,
-which is how a raw `sonor_` key once shipped in a public chunk.
+real handlers client-side would pull server code, and the key with it, into a
+`'use client'` graph and a public chunk.
 
 Tools that genuinely need live DOM state go in `localTools` and run in-page.
 

package/src/motion/README.md

@@ -348,7 +348,7 @@ Per-site components map onto `<Reveal>` almost one to one:
 | Site prop | `<Reveal>` |
 |-----------|-----------|
 | `from="up"`, `direction="up"` | `from="up"` |
-| `y={30}` (upforge.io) | `distance={30}` |
+| `y={30}` | `distance={30}` |
 | `stagger` (boolean) | `stagger` |
 | `delay`, `duration` | same, in seconds |
 | `threshold`, `rootMargin` | `threshold` |

package/src/og/README.md

@@ -47,8 +47,8 @@ to child segments.** A card at `services/` is not inherited by
 param), which the generator does automatically.
 
 `sonor-setup og` and `sonor-setup doctor` both check this through one shared
-rule (`og/wiring.ts`). Do not re-implement it — there were two copies once and
-both told sites to do the wrong thing. The rule reads the site's code through
+rule (`og/wiring.ts`), so the two never disagree. The rule reads the site's
+code through
 `shared/source-graph.ts`, which follows imports into `lib/` helpers and monorepo
 workspace packages, so `twitter.card` set in a metadata helper counts. It used
 to read the root layout alone.
@@ -62,16 +62,16 @@ zero-config seed for sites that have no config yet.
 import { defineOgCard } from '@sonordev/site-kit/og'
 
 export default defineOgCard({
-  theme: { bg: '#0A0A0A', text: '#f5f5f7', accent: '#C41E3A', surface: '#141418' },
-  fonts: [{ family: 'Playfair Display', weights: [800] }],
+  theme: { bg: '#0F172A', text: '#F8FAFC', accent: '#F59E0B', surface: '#1E293B' },
+  fonts: [{ family: 'Fraunces', weights: [800] }],
   logo: '/logo-white.svg',
   layout: 'split',
-  photo: { src: '/team.jpg' },
+  photo: { src: '/crew.jpg' },
   content: {
-    kicker: 'Custom Closets · Cincinnati',
-    title: 'Built by\nbrothers',
-    subtitle: 'Designed, built, and installed by the same two people.',
-    bar: ['Free design', 'example.com'],
+    kicker: 'Remodeling · Springfield',
+    title: 'Built by\nneighbors',
+    subtitle: 'Designed, built and installed by one local crew.',
+    bar: ['Free estimate', 'example.com'],
   },
 })
 ```
@@ -86,10 +86,10 @@ The title opens at 104px and the renderer steps it down until it fits **both**
 axes, stopping at a 56px legibility floor — below that a headline stops reading
 at the ~300px thumbnail width platforms actually show.
 
-If copy still does not fit at the floor, the command **fails** and names the
-element and the overflow in pixels. That is deliberate: the failure it exists to
-catch was a card that shipped with the kicker off-canvas and the subtitle buried
-under the bottom bar, while the CLI printed a tick.
+If copy still doesn't fit at the floor, the command **fails** and names the
+element and the overflow in pixels. That's deliberate: otherwise a card can ship
+with the kicker off-canvas and the subtitle buried under the bottom bar while
+the CLI prints a tick.
 
 Rules of thumb: about 10 uppercase characters per title line, and about 29 for
 the kicker. `\n` in a title is a hard break, so choose the wrap yourself rather
@@ -106,8 +106,8 @@ Hand-write the few that deserve it:
 
 ```ts
 cards: {
-  '/free-3d-design': {
-    content: { kicker: 'Free 3D design', title: 'See it\nfirst' },
+  '/free-estimate': {
+    content: { kicker: 'Free estimate', title: 'Know the\ncost first' },
     photo: { src: '/lp/hero.jpg' },
   },
 },
@@ -119,8 +119,8 @@ so an entry only states what differs.
 Managed titles carry the brand for the SERP (`About Us | Acme`); the card drops
 it. It also drops the two broken suffixes managed titles turn up with: a dangling
 separator with no brand after it (`About Us |`) and a domain after a comma
-(`Privacy Policy, abbeyglenapts.com`). A hyphen inside a word is never a
-separator (`Walk-In Closets` stays whole).
+(`Privacy Policy, example.com`). A hyphen inside a word is never a
+separator (`Walk-In Showers` stays whole).
 
 ### Dynamic routes are keyed by pattern, one `*` per level
 
@@ -141,23 +141,22 @@ cards: {
 },
 ```
 
-This was a real bug: both directories keyed to `/services/*`, so 120
-service-by-metro pages shipped the service pages' card and the `/services/*/*`
-override matched nothing — silently. A `cards` key that matches no rendered
-route is now reported by `sonor-setup og` (`og.cards`, a warning).
+The generator keys each depth separately, so a `/services/*/*` entry reaches
+the service-by-metro pages and nothing else. A `cards` key that matches no
+rendered route is reported by `sonor-setup og` (`og.cards`, a warning), since
+otherwise it would match nothing, silently.
 
 > **Writing a nested pattern in a comment.** `/services/*/*` contains `*/`,
 > which **closes a `/* */` block comment early**. In TypeScript put it in a
-> string, a `//` line comment, or spell the depth out in prose — this bit the
-> fix for the bug above, inside the comment explaining the bug.
+> string, a `//` line comment, or spell the depth out in prose. It's an easy
+> slip in exactly the comment that explains the pattern.
 
 ### Static routes under a dynamic segment get a card too
 
 `properties/[slug]/about` is a static route under a dynamic one. It gets its
 own card, keyed `/properties/*/about` and titled from its own name ("About",
 kicker "properties"). The generator used to stop at the first dynamic segment,
-so these pages shipped with no og:image at all, 30 of them on two
-property sites.
+which left these pages with no og:image at all.
 
 ### Per-URL cards: one per floor plan, one per community
 
@@ -213,7 +212,7 @@ The URL ends in `.jpg`, so a `trailingSlash: true` site never redirects it.
 Per-URL cards need `sharp` (they have to be `.jpg`); without it the command
 fails those cards and says so. Their copy comes from Sonor's managed title for
 that URL, like any route card. A per-URL key matches a pattern one segment per
-`*`, so `/properties/tall-pines/about` falls under `/properties/*/about`.
+`*`, so `/properties/maple-court/about` falls under `/properties/*/about`.
 
 Cards are re-encoded to JPEG when `sharp` resolves — on a real 18-card site that
 was 5.6 MB → 1.4 MB. Without sharp they stay PNG, which is correct, just heavier.
@@ -249,7 +248,7 @@ export default createOgImage<{ slug: string }>(async ({ slug }) => {
     kicker: 'From the publication',
     title: post.title,
     photoUrl: post.featured_image, // must be absolute
-    bar: 'acme.com',
+    bar: 'example.com',
   }
 })
 ```

package/src/proxy/README.md

@@ -114,7 +114,7 @@ into a dynamic one. The resolver is deprecated.
 | Header | Value |
 |--------|-------|
 | X-DNS-Prefetch-Control | `on` |
-| Content-Security-Policy | `frame-ancestors 'self' https://upforge.io https://*.upforge.io` |
+| Content-Security-Policy | `frame-ancestors` from `DEFAULT_FRAME_ANCESTORS` (below) |
 | X-Content-Type-Options | `nosniff` |
 | X-XSS-Protection | `1; mode=block` |
 | Referrer-Policy | `strict-origin-when-cross-origin` |
@@ -124,23 +124,23 @@ Note there is no `X-Frame-Options` row — that is deliberate, see below.
 
 ### Framing / `frame-ancestors`
 
-Upforge showcases live client work in iframes on its portfolio and area
-pages, so managed sites ship a CSP `frame-ancestors` allowlist instead of
-`X-Frame-Options`. XFO has no allowlist form (`ALLOW-FROM` is dead), and
-emitting both would let a stray `DENY` silently re-block the embed — so
-`X-Frame-Options` is **omitted** whenever `frameAncestors` is active.
-Every origin not on the list is still blocked.
+Managed sites ship a CSP `frame-ancestors` allowlist instead of
+`X-Frame-Options`. The default, `DEFAULT_FRAME_ANCESTORS`, is `'self'`,
+Sonor's dashboard (`https://app.sonor.io`, for Edit on page) and the Upforge
+showcase origins (`upforge.io`, `upforgelabs.com` and their subdomains), where
+live client sites appear in portfolio frames. XFO has no allowlist form
+(`ALLOW-FROM` is dead), and emitting both would let a stray `DENY` silently
+re-block the embed, so `X-Frame-Options` is **omitted** whenever
+`frameAncestors` is active. Every origin not on the list is still blocked.
+
+`frameAncestors` replaces the default, so spread it to add an origin:
 
 ```ts
+import { createProxy, DEFAULT_FRAME_ANCESTORS } from '@sonordev/site-kit/proxy'
+
 createProxy({
-  // extend the allowlist
   securityHeaders: {
-    frameAncestors: [
-      "'self'",
-      'https://upforge.io',
-      'https://*.upforge.io',
-      'https://partner.example.com',
-    ],
+    frameAncestors: [...DEFAULT_FRAME_ANCESTORS, 'https://partner.example.com'],
   },
 })