@sonordev/site-kit 7.0.1 → 7.0.2

package/src/proxy/README.md

@@ -0,0 +1,152 @@
+# Proxy — `@sonordev/site-kit/proxy`
+
+Composable Next.js Proxy factory. Zero-config redirects + security headers. Opt-in AI discovery headers.
+
+Next 16 renamed the `middleware` file convention to `proxy`. Through 7.x this
+module is also served on `@sonordev/site-kit/middleware`, with `createMiddleware`
+as an alias of `createProxy`; both go in 8.0. `npx sonor-setup codemod --write`
+moves a site over (the file too).
+
+## Usage
+
+```ts
+// proxy.ts — at the project root, or in src/
+import { createProxy } from '@sonordev/site-kit/proxy'
+
+export default createProxy()
+
+// Inlined on purpose. See "The matcher must be inlined" below — importing
+// siteKitMatcher here is a build error.
+export const config = {
+  matcher: [
+    '/((?!_next/static|_next/image|favicon\\.ico|.*\\.(?:ico|png|jpg|jpeg|gif|webp|svg|woff2?)$).*)',
+  ],
+}
+```
+
+With options:
+
+```ts
+export default createProxy({
+  securityHeaders: { frameAncestors: ["'self'", 'https://partner.example.com'] },
+  llmsDiscovery: { siteUrl: 'https://example.com' },
+  before: (req) => {
+    // Custom auth check, geolocation, etc.
+  },
+})
+```
+
+## The matcher must be inlined
+
+**`export const config = siteKitMatcher` is a build error.** Next statically
+parses `config.matcher` at build time and Turbopack rejects any imported value,
+so the array has to be a literal in your own file. Copy it from the example
+above, or read it off `siteKitMatcher` — but paste the contents, don't export
+the binding.
+
+`siteKitMatcher` exists so the canonical pattern lives in one place that the
+scaffold, the docs, and the tests all read. It is a **reference value**.
+
+## Migrating from `middleware.ts`
+
+```bash
+npx sonor-setup next16
+```
+
+Runs the codemod's `next-16-proxy` transform (deterministic and offline: it
+moves the file, renames a named `middleware` export to `proxy`, and never
+moves onto an existing `proxy.ts`) and re-runs the doctor check afterwards, so
+the result is verified rather than assumed. Safe to run twice. A file that
+sets `runtime` is flagged rather than moved (see below).
+
+Two Next 16 traps to know:
+
+- **No `runtime` export.** Proxy defaults to the Node.js runtime and the
+  `runtime` config option is unavailable in proxy files — setting it throws at
+  build time. (`middleware.ts` still accepts `runtime: 'nodejs'`, and it does
+  run on Netlify; remove the export before moving the file.)
+- **The matcher**, as above.
+
+## Config
+
+```ts
+interface SiteKitProxyConfig {
+  redirects?: boolean | RedirectConfig               // Sonor-managed redirects (default: true)
+  securityHeaders?: boolean | SecurityHeadersConfig  // Security headers (default: true)
+  llmsDiscovery?: LlmsDiscoveryConfig | false        // AI crawler discovery header
+  identity?: boolean | IdentityConfig                // Opt-in edge identity pass
+
+  before?: (req: NextRequest) => NextResponse | undefined | Promise<NextResponse | undefined>
+  after?: (req: NextRequest, res: NextResponse) => NextResponse | Promise<NextResponse>
+}
+
+interface LlmsDiscoveryConfig {
+  siteUrl: string          // e.g. 'https://example.com'
+  llmsPath?: string        // Default: '/llms.txt'
+  mcpServerCard?: boolean | string  // Also link the MCP server card (rel="service-desc"); true = '/.well-known/mcp-server-card'
+}
+```
+
+`redirects: true` (the default) checks managed rules before each page render.
+The rule list is cached in memory for five minutes per instance, and a fetch is
+bounded at 300ms with a 30s cooldown after a failure, so page loads rarely wait
+on it. Set `redirects: false` only on a site that uses no Sonor-managed
+redirects.
+
+Don't resolve redirects in `app/not-found.tsx` with `resolveManagedRedirect()`.
+Next renders the root not-found boundary inside every page, so its `headers()`
+call makes every route dynamic: on a Next 16 build every static route turned
+into a dynamic one. The resolver is deprecated.
+
+## What It Handles (in order)
+
+1. **Before hook** — optional custom logic (return `NextResponse` to short-circuit)
+2. **Sonor-managed redirects** — 301/302/307/308 with query param preservation
+3. **Security headers** — see the table below
+4. **AI discovery header** — `Link: <url>; rel="describedby"; type="text/markdown"` on every request that
+   could be for a page: GET or HEAD, an Accept header that allows HTML (or no Accept header at all, which is
+   how curl and many crawlers ask), not a file-like path (`/llms.txt`, `/sitemap.xml`), not `/api/`, and not
+   a Next RSC navigation request. See `wantsLlmsDiscoveryLink` in `@sonordev/site-kit/llms`.
+5. **After hook** — mutate response headers
+
+## Security Headers (defaults)
+
+| Header | Value |
+|--------|-------|
+| X-DNS-Prefetch-Control | `on` |
+| Content-Security-Policy | `frame-ancestors 'self' https://upforge.io https://*.upforge.io` |
+| X-Content-Type-Options | `nosniff` |
+| X-XSS-Protection | `1; mode=block` |
+| Referrer-Policy | `strict-origin-when-cross-origin` |
+| Permissions-Policy | `camera=(), microphone=(), geolocation=()` |
+
+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.
+
+```ts
+createProxy({
+  // extend the allowlist
+  securityHeaders: {
+    frameAncestors: [
+      "'self'",
+      'https://upforge.io',
+      'https://*.upforge.io',
+      'https://partner.example.com',
+    ],
+  },
+})
+
+// opt out entirely → falls back to X-Frame-Options: DENY
+createProxy({ securityHeaders: { frameAncestors: false } })
+```
+
+`DEFAULT_FRAME_ANCESTORS` is the single source of truth — add origins there
+rather than re-forking the list into individual sites.

package/src/redirects/README.md

@@ -0,0 +1,74 @@
+# Redirects — `@sonordev/site-kit/redirects`
+
+Sonor-managed 301/302/307/308 redirect rules. Used by `createProxy()` or standalone.
+
+## Usage
+
+Automatically handled when using `createProxy()`:
+
+```ts
+// proxy.ts
+import { createProxy } from '@sonordev/site-kit/proxy'
+
+export default createProxy()  // redirects: true by default
+
+// Inlined: an imported `config.matcher` is a build error. See the proxy README.
+export const config = {
+  matcher: [
+    '/((?!_next/static|_next/image|favicon\\.ico|.*\\.(?:ico|png|jpg|jpeg|gif|webp|svg|woff2?)$).*)',
+  ],
+}
+```
+
+For standalone use:
+
+```ts
+import { handleManagedRedirects } from '@sonordev/site-kit/redirects'
+
+export async function middleware(request: NextRequest) {
+  const redirect = await handleManagedRedirects(request, {})
+  if (redirect) return redirect
+  return NextResponse.next()
+}
+```
+
+## API
+
+```ts
+handleManagedRedirects(request: NextRequest, config: RedirectConfig): Promise<NextResponse | undefined>
+fetchRedirectRules(config: RedirectConfig): Promise<RedirectRule[]>
+generateNextRedirects(config: RedirectConfig): Promise<Redirect[]>  // For next.config.js
+clearRedirectCache(): void  // Dev helper
+```
+
+## Config
+
+```ts
+interface RedirectConfig {
+  domain?: string              // Resolved from Sonor when using apiKey
+  apiKey?: string              // Project API key
+  site?: string                // Multi-site host, sent as ?site= and cached per host (default: NEXT_PUBLIC_SITE_URL host)
+  portalApiUrl?: string        // Default: https://api.sonor.io
+  cacheSeconds?: number        // Default: 300 (5 minutes)
+}
+```
+
+## Behavior
+
+1. Checks in-memory cache first
+2. Fetches rules from Sonor API if expired
+3. Matches pathname (exact or trailing-slash variant)
+4. Preserves query parameters on redirect
+5. Tracks redirect hit (fire-and-forget)
+6. Skips static assets and API routes
+
+## Types
+
+```ts
+interface RedirectRule {
+  from_path: string
+  to_path: string
+  redirect_type: '301' | '302' | '307' | '308'
+  is_enabled: boolean
+}
+```

package/src/reputation/README.md

@@ -0,0 +1,64 @@
+# Reputation — `@sonordev/site-kit/reputation`
+
+Display client reviews, testimonials, and rating statistics from Sonor.
+
+## Usage
+
+```tsx
+import { TestimonialSection } from '@sonordev/site-kit/reputation'
+
+export default function ReviewsPage() {
+  return (
+    <TestimonialSection
+      title="What Our Clients Say"
+      showRating
+      maxReviews={6}
+    />
+  )
+}
+```
+
+## TestimonialSection Props
+
+```ts
+interface TestimonialSectionProps {
+  title?: string
+  subtitle?: string
+  autoplay?: boolean              // Auto-rotate reviews
+  autoplayInterval?: number       // ms between rotations
+  showRating?: boolean            // Display star ratings
+  maxReviews?: number             // Limit displayed count
+  featuredOnly?: boolean          // Show featured reviews only
+  service?: string                // Filter by service tag
+  className?: string
+}
+```
+
+## API Functions
+
+```ts
+import { fetchReviews, fetchReviewStats } from '@sonordev/site-kit/reputation'
+
+const reviews = await fetchReviews({ service: 'divorce', limit: 10, featured: true })
+const stats = await fetchReviewStats()  // { total_reviews, average_rating, distribution }
+```
+
+## Types
+
+```ts
+interface Review {
+  id: string; quote: string; name: string; role?: string;
+  rating: number; image?: string; date?: string;
+  platform?: string; isFeatured?: boolean; serviceTags?: string[];
+}
+
+interface ReviewStats {
+  total_reviews: number
+  average_rating: number
+  distribution: { 1: number; 2: number; 3: number; 4: number; 5: number }
+}
+```
+
+## Caching
+
+Uses in-memory cache (60s TTL) with retry-on-429 backoff to prevent rate limiting during dev hot reload.

package/src/seo/README.md

@@ -0,0 +1,359 @@
+# SEO: `@sonordev/site-kit/seo`
+
+Server Components and server helpers that render what you manage in the SEO module at [app.sonor.io](https://app.sonor.io): page metadata, JSON-LD, FAQs, internal links, content blocks, redirects and robots directives.
+
+The project comes from `SONOR_API_KEY`. Nothing in this module takes a project ID. A few option types and props still carry an optional `projectId` from older versions; it's ignored, so leave it out.
+
+## Setup
+
+```bash
+# .env.local
+SONOR_API_KEY=sonor_xxxxxxxx_xxxxx
+```
+
+That's the only variable you need. Keep it server-side, with no `NEXT_PUBLIC_` prefix. `SONOR_API_URL` is optional and defaults to `https://api.sonor.io`.
+
+If the key is missing, the server helpers throw:
+
+```
+@sonordev/seo: SONOR_API_KEY environment variable is required for server-side SEO functions
+```
+
+## Entry points
+
+| Import | Runs on | Contains |
+|--------|---------|----------|
+| `@sonordev/site-kit/seo` | Server only | Everything on this page except `registerLocalSitemap` |
+| `@sonordev/site-kit/seo/server` | Server only | The [data fetchers](#data-fetchers), `getManagedMetadata`, `getManagedMetadataWithAB`, `generateSitemap`, `registerLocalSitemap`, and the types |
+| `@sonordev/site-kit/seo/client` | Client | `SitemapSync` only |
+
+Both server entries import `server-only`, so importing either one from a Client Component fails the build. That's deliberate: it keeps the key out of the browser bundle.
+
+## Page metadata
+
+### `getManagedMetadata(options)`
+
+```tsx
+// app/services/[slug]/page.tsx
+import { getManagedMetadata } from '@sonordev/site-kit/seo'
+
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params
+  return getManagedMetadata({
+    path: `/services/${slug}`,
+    fallback: {
+      title: 'Our Services',
+      description: 'What we do and where we do it.',
+    },
+  })
+}
+```
+
+| Option | Type | Notes |
+|--------|------|-------|
+| `path` | `string` | Required. The page path as Sonor has it. |
+| `fallback` | `Metadata` | Fills any field Sonor has no managed value for. Used in full when the page isn't in Sonor at all. |
+| `overrides` | `Partial<Metadata>` | Applied last, so it wins over managed values. |
+| `favicon` | `'metadata' \| 'component'` | `'metadata'` (default) adds `icons` from the project logo. Pass `'component'` when your layout already renders the favicon, which `SiteKitLayout` does by default, so icons aren't emitted twice. |
+
+It returns a Next.js `Metadata` object with two extra flags, `_managed` and `_source`. Managed fields map like this:
+
+| Sonor field | Metadata field |
+|-------------|----------------|
+| `managed_title` | `title` |
+| `managed_meta_description` | `description` |
+| `managed_keywords` | `keywords` |
+| `managed_robots` | `robots` |
+| `managed_canonical` | `alternates.canonical` |
+| `language_alternates` | `alternates.languages` |
+| `managed_og_title`, `managed_og_description`, `managed_og_image` | `openGraph` and `twitter` (`summary_large_image`), falling back to the title and description |
+
+When the page exists in Sonor but has neither a title nor a description, the call asks Signal to write them in the background and returns your fallback for now. The generated copy shows up once the cached response refreshes (see [Caching](#caching)).
+
+**Title templates.** The managed title comes back as a plain string, so a root-layout `title.template` still applies to it. If your managed titles already include the brand, you'll get it twice. Mark the title absolute:
+
+```ts
+const metadata = await getManagedMetadata({ path: '/about' })
+return typeof metadata.title === 'string'
+  ? { ...metadata, title: { absolute: metadata.title } }
+  : metadata
+```
+
+### `withManagedMetadata(path, pageMetadata?)`
+
+Builds the `generateMetadata` function for you. Pick one of these forms:
+
+```ts
+import { withManagedMetadata } from '@sonordev/site-kit/seo'
+
+// A fixed path
+export const generateMetadata = withManagedMetadata('/about')
+
+// A path built from params
+export const generateMetadata = withManagedMetadata(
+  async ({ params }) => `/services/${(await params).slug}`,
+)
+
+// Page-level values on top of Sonor's
+export const generateMetadata = withManagedMetadata('/about', async () => ({
+  title: 'About Us',
+}))
+```
+
+Whatever `pageMetadata` returns wins over Sonor's values. `openGraph` and `twitter` merge one level deep. It calls `getManagedMetadata` with the default `favicon: 'metadata'`.
+
+### A/B-tested titles and descriptions
+
+`getManagedMetadataWithAB` works like `getManagedMetadata`, then swaps in the assigned variant of any running title or description test for that path. `getABVariant({ path, field, sessionId? })` does the same for one field (`'title' | 'description' | 'content'`) and returns `{ testId, variant, value }`, or `null` when nothing's running.
+
+```ts
+import { cookies } from 'next/headers'
+import { getManagedMetadataWithAB } from '@sonordev/site-kit/seo'
+
+export async function generateMetadata() {
+  const sessionId = (await cookies()).get('visitor_id')?.value
+  return getManagedMetadataWithAB({ path: '/pricing', sessionId })
+}
+```
+
+Pass a stable visitor ID your site already keeps. The kit doesn't set a cookie for this, and without one every request gets a random variant. Reading cookies makes the route dynamic, and each variant lookup records an impression.
+
+## JSON-LD
+
+### `<ManagedSchema>`
+
+```tsx
+import { ManagedSchema } from '@sonordev/site-kit/seo'
+
+export default function Page() {
+  return (
+    <>
+      <ManagedSchema path="/services/plumbing" />
+      <main>{/* ... */}</main>
+    </>
+  )
+}
+```
+
+It renders one `application/ld+json` script (an `@graph` when there's more than one node) that combines:
+
+- the schema Sonor has for the path, filtered by `includeTypes` / `excludeTypes`
+- the page's Signal-generated `managed_schema`
+- anything you pass in `additionalSchemas`
+- a `BreadcrumbList` built from the path, when there isn't one already and the project has a site URL (skipped on `/`)
+- a speakable `WebPage` or `Article` node, when `speakable`, `pageName` and `pageUrl` are all set
+
+| Prop | Default | Notes |
+|------|---------|-------|
+| `path` | | Required. |
+| `includeTypes` / `excludeTypes` | | Type allow and deny lists. `includeTypes` keeps Sonor schema rows by `schema_type`. `excludeTypes` drops a node of that `@type` wherever it sits in Sonor's schema: a whole row, an `@graph` member, or a nested value like `mainEntity`, and in `managed_schema` too. A row left empty is dropped. Your `additionalSchemas` are never filtered. |
+| `additionalSchemas` | `[]` | Extra nodes to merge in. |
+| `speakable` | | `true` for the default selectors (`h1`, `[data-speakable="true"]`, `.page-summary`, `.key-points`, `.aeo-block[data-speakable="true"]`), or `{ cssSelector }` / `{ xpath }`. |
+| `pageType` | `'WebPage'` | `'WebPage'` or `'Article'`, for the speakable node. |
+| `pageName`, `pageUrl` | | Required for the speakable node. |
+| `includeEntityGraph` | `true` | Meant to add nodes from Signal's entity graph. It adds nothing today; see [Entity graph](#entity-graph-and-ai-visibility). |
+
+It's wrapped in `Suspense`, so the fetch never holds up the rest of the page. The script streams in when it's ready.
+
+### `<LLMSchema path>`
+
+Renders the page's `managed_llm_schema` as a `WebPage` JSON-LD script marked `data-llm-optimized="true"`, linked to the site's `WebSite` node when the project has a site URL. It renders nothing when the page has no LLM schema.
+
+### Schema helpers
+
+- `createSchema(type, data)` returns `{ '@context': 'https://schema.org', '@type': type, ...data }`.
+- `createBreadcrumbSchema(baseUrl, path, labels?)` builds a `BreadcrumbList`. `labels` maps a path segment to its display name.
+- `createWebSiteOrganizationStub({ name, url, sameAs?, knowsAbout? })` returns a minimal `Organization` and `WebSite` pair with stable `@id`s. Only reach for it when Sonor isn't already emitting those nodes.
+
+Hand the result to `ManagedSchema` through `additionalSchemas`, so it's serialized and escaped in the same script as everything else.
+
+## FAQs: `<ManagedFAQ>`
+
+```tsx
+import { ManagedFAQ } from '@sonordev/site-kit/seo'
+
+<ManagedFAQ path="/services/plumbing" />
+```
+
+| Prop | Default | Notes |
+|------|---------|-------|
+| `path` | | Required. |
+| `showTitle` | `true` | Renders the FAQ's title as an `<h2>`. |
+| `includeSchema` | `true` | Emits `FAQPage` JSON-LD, but only when the FAQ is also set to include schema in Sonor. |
+| `renderItem` | | `(item, index) => ReactNode`, for your own markup. |
+| `className` | `'sk-faq'` | Wrapper class. |
+| `site` | | Sub-site host on a multi-site project. See [Multi-site projects](#multi-site-projects). |
+
+The default markup is native `<details>` / `<summary>` with its own small `<style>` block (`sk-faq-*` classes), so there's no CSS to import. Only visible items render, in their saved order. Answers are HTML, so render them as HTML in a custom item:
+
+```tsx
+<ManagedFAQ
+  path="/faq"
+  renderItem={(faq) => (
+    <details key={faq.id}>
+      <summary>{faq.question}</summary>
+      <div dangerouslySetInnerHTML={{ __html: faq.answer }} />
+    </details>
+  )}
+/>
+```
+
+Don't also hand-write `FAQPage` JSON-LD for a page that renders `ManagedFAQ`. You'd ship it twice.
+
+## Internal links: `<ManagedInternalLinks>`
+
+```tsx
+import { ManagedInternalLinks } from '@sonordev/site-kit/seo'
+
+<ManagedInternalLinks path="/article/my-post" position="related" limit={5} />
+```
+
+Renders the internal links Sonor has for `path` at that position, or nothing when there aren't any.
+
+| `position` | Markup |
+|------------|--------|
+| `'bottom'` (default) | "Related Articles" list |
+| `'sidebar'` | `<aside>` with a "Related Pages" list |
+| `'related'` | `<nav>` grid titled "You May Also Like", with each link's context |
+| `'inline'` | Bare links in a `<span>`, for dropping into copy |
+
+`limit` defaults to 5. `renderLink(link)` replaces the default `<a>`, and `className` replaces the default `sk-internal-links sk-internal-links--{position}`. `site` pins the sub-site host (see [Multi-site projects](#multi-site-projects)).
+
+## Content blocks: `<ManagedContent>`
+
+```tsx
+import { ManagedContent } from '@sonordev/site-kit/seo'
+
+<ManagedContent path="/services/plumbing" section="hero" fallback={<DefaultHero />} />
+```
+
+Renders the block Sonor has for that path and section, by its content type:
+
+- `html`: injected as-is
+- `markdown`: a basic conversion (headings, bold, italic, links, paragraphs). For anything richer, fetch the raw block with `getManagedContentData(path, section)` and use your own parser.
+- `json`: renders `title`, `subtitle`, `content` (as HTML) and `items`
+- `react`: `{ component, props }`, looked up by name in the `components` prop
+
+It renders `fallback` (or nothing) when there's no block. `injectEntityAnnotations` depends on the entity graph and changes nothing today. `site` pins the sub-site host, and `getManagedContentData(path, section, site?)` takes it too.
+
+## Multi-site projects
+
+One Sonor project can serve many domains (example.com plus its city microsites). Managed FAQs, internal links and content blocks can be project-wide (every host) or tagged with one host (that host only). `ManagedFAQ`, `ManagedInternalLinks` and `ManagedContent` send the site host with every read, so each microsite gets its own rows plus the project-wide ones, never a sibling's.
+
+The host resolves from `NEXT_PUBLIC_SITE_URL`, which every microsite already sets, so most sites change nothing. To pin one, pass `site`:
+
+```tsx
+<ManagedFAQ path="/contact" site="charlotte.example.com" />
+await getFAQData('/contact', 'charlotte.example.com')
+await getInternalLinks('/contact', { position: 'bottom', site: 'charlotte.example.com' })
+await getContentBlock('/contact', 'hero', 'charlotte.example.com')
+```
+
+When no host resolves, `site` is left off and the API answers for the project's primary domain. Single-site projects and older API servers ignore it.
+
+## Redirects, robots and sitemaps
+
+These have dedicated modules, and that's where to start:
+
+- **Redirects:** `createProxy()` from `@sonordev/site-kit/proxy` applies Sonor-managed redirects by default. See the [redirects README](../redirects/README.md) for the standalone helpers.
+- **Sitemap:** `createSitemap()` from `@sonordev/site-kit/sitemap` in `app/sitemap.ts`. See the [sitemap README](../sitemap/README.md).
+
+The SEO module keeps a few lower-level helpers:
+
+| Function | Returns |
+|----------|---------|
+| `getRedirect({ path })` | `{ destination, statusCode, isExternal }`, or `null`. Expired rules are skipped. |
+| `getRobotsDirective({ path })` | `{ index, follow, noarchive?, nosnippet?, ... }` parsed from the page's managed robots value. `{ index: true, follow: true }` when there isn't one. |
+| `isIndexable(projectId, path)` | `boolean`. This is a legacy signature and the first argument is ignored. `(await getRobotsDirective({ path })).index` says the same thing. |
+| `generateSitemap({ baseUrl, publishedOnly? })` | Sonor's page list as `{ path, url, lastmod, changefreq, priority }`. `publishedOnly` defaults to `true`. Those keys aren't Next's `MetadataRoute.Sitemap` shape (`lastModified`, `changeFrequency`), so map them before returning them from `app/sitemap.ts`. |
+
+### Registering pages with Sonor
+
+`createSitemap` already syncs your page list to Sonor during `next build`. A site without an `app/sitemap` route can use the postbuild CLI instead:
+
+```json
+{
+  "scripts": {
+    "postbuild": "sonor-register-sitemap --auto-discover"
+  }
+}
+```
+
+It skips itself when an `app/sitemap` route exists, and it only adds or updates pages unless you pass `--full-replace`.
+
+On a multi-site project, each page is tagged with the host it belongs to. The CLI takes it from `NEXT_PUBLIC_SITE_URL` (it loads `.env` and `.env.local`), or from `--site ohiopowerstudies.com`. It used to send no host at all, so a microsite's pages synced as unattributed.
+
+From code, `registerLocalSitemap({ entries?, autoDiscover?, mode?, site? })` on `@sonordev/site-kit/seo/server` does the same and is additive by default.
+
+`registerSitemap(entries, { mode?, site? })` is the raw call, and it **defaults to `'full-replace'`**, which prunes every page that isn't in `entries`. Pass `mode: 'additive'` unless `entries` really is the whole site. It sends the site host the same way.
+
+All of these and createSitemap's own sync build the request in one place (`seo/register-sitemap-request.ts`).
+
+## Data fetchers
+
+Every component above is built on these. They're server-only, take paths rather than project IDs, and are deduplicated per request with React `cache()`.
+
+| Function | Returns |
+|----------|---------|
+| `getSEOPageData(path)` | `{ page, project }`. `page` is the page's Sonor row (the `managed_*` fields) or `null`; `project` is `{ id, title, domain, logo_url, site_url }` or `null`. |
+| `getSchemaMarkups(path, { includeTypes?, excludeTypes? })` | Schema rows (`schema_type`, `schema_json`, ...). `excludeTypes` also prunes matching nodes inside each row. |
+| `getFAQData(path, site?)` | The FAQ (`title`, `description`, `items`, `include_schema`), or `null` |
+| `getInternalLinks(path, { position?, limit?, site? })` | Link rows |
+| `getContentBlock(path, section, site?)` | The content block, or `null` |
+| `getABTest(path, field)` | The running test for that field, or `null` |
+| `recordABImpression(testId, variant, sessionId?)` | `void` |
+| `getRedirectData(path)` | The raw redirect row, or `null` |
+| `getRobotsData(path)` | The page's managed robots string, or `null` |
+| `getSitemapEntries({ publishedOnly? })` | Raw sitemap rows |
+| `getManagedScripts(position, path?)` | Always `[]` (retired, see below) |
+
+`getSEOPageData` and `getSchemaMarkups` share one request per path, so using both in a render (metadata plus `ManagedSchema`) costs a single round trip.
+
+## Entity graph and AI visibility
+
+`getEntities`, `getPrimaryEntity`, `getEntityEnhancedSchema`, `getVisibilityScore` and `getVisibilitySummary` are exported, but called from a site they currently return empty results (`[]` or `null`): the Signal endpoints behind them don't accept a site key yet. That's also why `ManagedSchema`'s `includeEntityGraph` and `ManagedContent`'s `injectEntityAnnotations` have no effect. Don't build on them until that changes.
+
+## Caching
+
+- **Within a request:** React `cache()` collapses identical calls into one.
+- **Across requests:** Sonor API responses sit in Next's data cache for 24 hours (entity-graph calls, 5 minutes). Transient `429`, `502` and `503` responses are retried with backoff, inside a 30-second budget per call.
+
+So a change in the dashboard can take up to a day to reach the site. To push one sooner, revalidate the path from a route you control:
+
+```ts
+// app/api/revalidate/route.ts
+import { revalidatePath } from 'next/cache'
+
+export async function POST(request: Request) {
+  if (request.headers.get('x-revalidate-secret') !== process.env.REVALIDATION_SECRET) {
+    return new Response('Unauthorized', { status: 401 })
+  }
+  const { path } = await request.json()
+  revalidatePath(path)
+  return Response.json({ revalidated: true })
+}
+```
+
+## Retired and deprecated
+
+- **`ManagedScripts` / `ManagedNoScripts`** were retired in June 2026. They render nothing and make no request. Load third-party scripts with `next/script` in your own code.
+- **`LocationPageContent` / `getLocationSection`** were removed in 7.0. They were the one place that still sent a `projectId` in the request body instead of authenticating with the key, and no site used them.
+- **`projectId`** on any option or prop is ignored. The project comes from the key.
+
+## Upgrading older code
+
+- Drop `projectId` from every call and prop. The fetchers take just the path: `getSEOPageData('/about')`.
+- `SONOR_API_KEY` is the only variable. `UPTRADE_API_KEY` and `NEXT_PUBLIC_UPTRADE_*` aren't read, `uptrade_` keys aren't accepted, and `SONOR_PROJECT_ID` isn't needed. `npx sonor-setup codemod --only uptrade-to-sonor --write` moves a pre-rebrand site over.
+- Import from `@sonordev/site-kit/seo` or `@sonordev/site-kit/seo/server`. There's no `/seo/api` entry.
+
+## Troubleshooting
+
+**`SONOR_API_KEY environment variable is required`.** The key isn't in the server environment. Check `.env.local` locally and the host's environment settings in production, then redeploy.
+
+**A build error that mentions `server-only`.** A Client Component imports `@sonordev/site-kit/seo` or `/seo/server`. Move that code into a Server Component, or import `SitemapSync` from `/seo/client`.
+
+**The metadata is always the fallback.** The path isn't in Sonor yet, or its managed fields are empty. Make sure the page is registered (`createSitemap` or `sonor-register-sitemap`) and that `path` matches the path Sonor has.
+
+**The schema isn't in the page.** `ManagedSchema` has to render inside a Server Component. It streams in after the first bytes, so check the complete HTML (`curl` the page) rather than an early paint.
+
+**The brand is in the title twice.** See [Title templates](#getmanagedmetadataoptions).