@sonordev/site-kit 7.0.1 → 7.1.0

package/src/admin-auth/README.md

@@ -0,0 +1,88 @@
+# `@sonordev/site-kit/admin-auth` — Sign in with Sonor
+
+Put a site's own admin area behind a Sonor login. Whoever can open the
+project in Sonor (its owners and members, the managing agency, platform
+admins) can sign in; nobody else can. There are no passwords on the site.
+
+## Wiring
+
+```ts
+// lib/sonor-sso.ts
+import { createSonorSso } from '@sonordev/site-kit/admin-auth'
+
+export const sso = createSonorSso({
+  paths: '/admin',            // or ['/bid', '/route'] for several areas
+  // loginPath: '/admin/login' (default: `${paths[0]}/login`)
+  // adminEmails: process.env.ADMIN_EMAILS,
+})
+```
+
+```ts
+// proxy.ts
+import { createProxy } from '@sonordev/site-kit/proxy'
+import { sso } from '@/lib/sonor-sso'
+
+export default createProxy({ before: sso.gate, redirects: true, securityHeaders: true })
+```
+
+```ts
+// app/api/auth/callback/route.ts
+import { sso } from '@/lib/sonor-sso'
+export const GET = sso.handleCallback
+```
+
+```ts
+// app/api/auth/logout/route.ts
+import { sso } from '@/lib/sonor-sso'
+export const GET = sso.handleLogout
+export const POST = sso.handleLogout
+```
+
+```tsx
+// app/admin/login/page.tsx (server component)
+import { SSO_ERROR_MESSAGES } from '@sonordev/site-kit/admin-auth'
+import { sso } from '@/lib/sonor-sso'
+
+export default async function Login({ searchParams }) {
+  const { error, return_to } = await searchParams
+  let href: string | null = null
+  try { href = await sso.getLoginUrl({ returnTo: return_to }) } catch {}
+  return (
+    <>
+      {error && <p>{SSO_ERROR_MESSAGES[error] ?? error}</p>}
+      {href ? <a href={href}>Sign in with Sonor</a> : <p>Sign-in is unavailable.</p>}
+    </>
+  )
+}
+```
+
+```ts
+// Every API route and server action that touches admin data
+const session = await sso.getSession()
+if (!session) return new Response('Unauthorized', { status: 401 })
+```
+
+Designer APIs or other JSON endpoints can be guarded in the middleware too:
+pass `apiPaths: ['/api/studio']` and include them in the matcher. They get a
+401 JSON response instead of a redirect.
+
+## Env
+
+| Var | |
+|---|---|
+| `SONOR_API_KEY` | Already on every site. Identifies the project and verifies tokens. |
+| `SONOR_SESSION_SECRET` | 32+ random chars (`openssl rand -hex 32`). Rotate to sign everyone out. |
+| `NEXT_PUBLIC_SITE_URL` | The site's public origin, for the callback URL. |
+
+The callback route has to be reachable at `callbackPath` (default
+`/api/auth/callback`) on `NEXT_PUBLIC_SITE_URL`.
+
+## Rules
+
+- **The gate doesn't cover `/api/*`.** The standard middleware matcher
+  excludes it. Check `getSession()` in every API route.
+- **Don't trust identity from headers, query strings or bodies.**
+  `getSession()` reads the httpOnly cookie and verifies its signature on
+  every call; that's the only source.
+- **Moving a site onto this module:** pass its existing `cookieName` and
+  `secretEnv` so current sessions stay valid.

package/src/analytics/README.md

@@ -0,0 +1,264 @@
+# Analytics — `@sonordev/site-kit/analytics`
+
+Automatic page view tracking, custom events, conversions, scroll depth, heatmap clicks, and Core Web Vitals. All data flows through the Sonor API.
+
+## Usage
+
+`SiteKitLayout` mounts analytics for you. It renders `{children}` first and
+mounts `AnalyticsProvider` after them as a childless sibling, deferred until
+window load + idle (or the first interaction). Analytics never sits in the
+page's hydration path and can't push a route to client rendering. Configure it
+on the layout:
+
+```tsx
+// app/layout.tsx (server component)
+import { SiteKitLayout } from '@sonordev/site-kit/layout'
+import { ContactTracking } from '@sonordev/site-kit/analytics'
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <SiteKitLayout analytics={{ excludePaths: ['/admin'] }}>{children}</SiteKitLayout>
+        {/* Optional: tel:/mailto: clicks as conversions. Childless, renders null. */}
+        <ContactTracking />
+      </body>
+    </html>
+  )
+}
+```
+
+Don't wrap `{children}` in `AnalyticsProvider` yourself. It puts analytics in
+the hydration path (the page-view code ships in the page's initial scripts),
+and if it's lazy-loaded with `next/dynamic({ ssr: false })` the whole route
+de-opts to client rendering.
+
+### Without `SiteKitLayout`
+
+A layout that doesn't use core `SiteKitLayout` mounts analytics itself, and
+still as a deferred, childless island. Publish the credential server-side
+first with `SiteKitCredential` (see `@sonordev/site-kit/client`). Never pass
+`SONOR_API_KEY` to a client component.
+
+```tsx
+// app/analytics-shell.tsx
+'use client'
+import { AnalyticsProvider, ContactTracking } from '@sonordev/site-kit/analytics'
+
+export default function AnalyticsShell() {
+  return (
+    <AnalyticsProvider trackPageViews trackWebVitals>
+      <ContactTracking />
+    </AnalyticsProvider>
+  )
+}
+```
+
+```tsx
+// app/deferred-analytics.tsx
+'use client'
+import { lazy, Suspense } from 'react'
+import { useDeferredActivation } from '@sonordev/site-kit/client'
+
+const AnalyticsShell = lazy(() => import('./analytics-shell'))
+
+export function DeferredAnalytics() {
+  const ready = useDeferredActivation(true)
+  if (!ready) return null
+  return (
+    <Suspense fallback={null}>
+      <AnalyticsShell />
+    </Suspense>
+  )
+}
+```
+
+```tsx
+// app/layout.tsx (server component): {children} is a SIBLING of the island, never inside it
+import { resolveClientCredential } from '@sonordev/site-kit/server'
+import { SiteKitCredential } from '@sonordev/site-kit/client'
+import { DeferredAnalytics } from './deferred-analytics'
+
+export default async function RootLayout({ children }) {
+  const credential = await resolveClientCredential(process.env.SONOR_API_KEY ?? '', 'https://api.sonor.io')
+  return (
+    <html lang="en">
+      <body>
+        <SiteKitCredential apiKey={credential} />
+        {children}
+        <DeferredAnalytics />
+      </body>
+    </html>
+  )
+}
+```
+
+`AnalyticsProvider` already mounts `WebVitals` when `trackWebVitals` is on.
+Don't add a second `<WebVitals />`, or every metric reports twice.
+
+## Tracking custom events
+
+Under `SiteKitLayout` the provider is childless, so no page component sits
+inside it. Use the standalone functions. They need no provider and queue until
+the deferred provider mounts:
+
+```tsx
+'use client'
+import { trackEvent, trackConversion } from '@sonordev/site-kit/analytics'
+
+trackEvent({ name: 'button_click', category: 'engagement', properties: { buttonId: 'cta' } })
+trackConversion({ type: 'purchase', value: 99.99, currency: 'USD' })
+```
+
+## Hooks
+
+`useAnalytics()` and `useTrackEvent()` read the provider's context, so they
+only work in components rendered inside an `AnalyticsProvider` (children of
+your own analytics island, for example). Anywhere else they throw. Reach for
+the standalone functions above instead of wrapping `{children}` to make a hook
+work. `useAnalyticsOptional()` returns `null` instead of throwing.
+
+### useAnalytics()
+
+```tsx
+const { trackEvent, trackConversion, sessionId, visitorId } = useAnalytics()
+```
+
+### useTrackEvent()
+
+```tsx
+const { trackEvent, trackConversion } = useTrackEvent()
+```
+
+### useContactTracking()
+
+Auto-tracks `tel:` and `mailto:` link clicks as conversions. Works anywhere: it
+uses the standalone dispatch, not the provider's context.
+
+```tsx
+const { trackPhoneClick, trackEmailClick } = useContactTracking()
+```
+
+## Components
+
+| Component | Purpose |
+|-----------|---------|
+| `AnalyticsProvider` | The tracker. `SiteKitLayout` mounts it childless; never wrap `{children}` in it |
+| `WebVitals` | Auto-reports LCP, CLS, TTFB, INP, FCP. `AnalyticsProvider` mounts it when `trackWebVitals` is on |
+| `ContactTracking` | Auto-tracks phone/email link clicks. Childless, renders null |
+
+## AnalyticsProvider Props
+
+```ts
+interface AnalyticsConfig {
+  projectId?: string           // Auto-resolved from API key
+  trackPageViews?: boolean     // Default: true
+  trackWebVitals?: boolean     // Default: true
+  trackScrollDepth?: boolean   // Default: true
+  sessionTimeout?: number      // Minutes (default: 30)
+  excludePaths?: string[]      // Don't track these paths
+  allowInFrame?: boolean       // Default: false — see below
+  allowLocalhost?: boolean     // Default: false — local builds report nothing
+  debug?: boolean              // Log events to console
+}
+```
+
+## What Gets Tracked Automatically
+
+- **Page views** — on every route change (path, URL, title, referrer, UTM params, device/browser/OS)
+- **Web Vitals** — LCP, CLS, TTFB, INP, FCP with good/needs-improvement/poor ratings
+- **Contact clicks** — `tel:` and `mailto:` links tracked as conversions, once `<ContactTracking />` is mounted (it isn't by default)
+- **DOM metadata** — full snapshot per page view (meta tags, H1, word count, links, content, FAQs)
+
+## Embedded pages report nothing (`analytics.allowInFrame`)
+
+When this site is loaded inside a **cross-origin iframe**, nothing is sent —
+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 produces is phantom traffic in the analytics
+its owner reads.
+
+This is not hypothetical. Upforge case studies embed each client's whole
+production site in three eager iframes, and `securityHeaders`'
+`DEFAULT_FRAME_ANCESTORS` permits that. Before the guard landed, 23 client
+sites carried the signature in `analytics_page_views`: three views of `/`
+sharing one session and visitor id, 21-80ms apart, referrer
+`https://upforge.io/` — the desktop, tablet and mobile frames of one case
+study. The screenshot overlay in those frames hides the pixels, not the
+JavaScript.
+
+**Same-origin frames still report.** 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 only when the frame IS the product — a widget or partner-hosted
+page deliberately distributed as an embed:
+
+```tsx
+<SiteKitLayout analytics={{ allowInFrame: true }}>…</SiteKitLayout>
+```
+
+There is deliberately no env var or window global for this. A silent switch
+that turns cross-tenant tracking back on is the failure mode, not the feature.
+
+The decision lives in one place — `shared/reporting-gate.ts`, over the frame
+primitive in `shared/frame.ts`. Every send in the module routes through it, and
+`send-gate.test.ts` fails the build if a new one does not. `isCrossOriginFrame()`
+is exported from `@sonordev/site-kit/analytics` if a site needs the same answer
+for its own third-party pixels.
+
+## Local builds report nothing (`analytics.allowLocalhost`)
+
+The actual browser hostname controls this gate, even in a production build
+with `analytics.site` or `NEXT_PUBLIC_SITE_URL` set to a production domain.
+`localhost`, its subdomains, `127.0.0.1`, `[::1]`, and `0.0.0.0` report nothing
+by default: page views, events, conversions, sessions, vitals, scroll and
+heatmap data, fleet heartbeats, and client-side sitemap registrations all use
+`resolveAnalyticsTarget`. Engage doesn't mount its widgets or chat transport.
+Public hosts and same-origin frames on public hosts still report normally.
+
+For intentional local reporting:
+
+```tsx
+<SiteKitLayout analytics={{ allowLocalhost: true }}>…</SiteKitLayout>
+```
+
+The layout passes this option to AnalyticsProvider, WebVitals, FleetHeartbeat,
+SitemapSync and EngageWidget. Standalone components and `sendFleetHeartbeat`
+accept it too; standalone `trackEvent`/`trackConversion` use their mounted
+AnalyticsProvider's options. A local cross-origin frame needs **both** opt-ins.
+Neither option bypasses authentication. No environment variable or global
+silently enables local reporting.
+
+This is a browser gate: build-time `createSitemap` and Node fleet reporting
+still run. It doesn't disable forms, commerce, or Signal. When verifying those
+modules locally, point them at a test API as well.
+
+## Environment
+
+Uses `SONOR_API_KEY` (injected by `SiteKitLayout`) or `window.__SITE_KIT_API_KEY__`.
+
+## Multi-site projects (`analytics.site`)
+
+A single Sonor project can host many sub-sites (e.g. one project hosting
+example.com + 16 state microsites). Every analytics event is
+tagged with the sub-site host so the dashboard can roll up + filter per
+site without forcing each microsite into its own Sonor project.
+
+`SiteKitLayout` resolves the host in this precedence order:
+
+1. Explicit `analytics.site` config
+2. `NEXT_PUBLIC_SITE_URL` host
+3. `window.location.host`
+
+```tsx
+<SiteKitLayout
+  analytics={{ site: 'ohio.example.com' }}
+>
+  …
+</SiteKitLayout>
+```
+
+Most projects leave it implicit — `NEXT_PUBLIC_SITE_URL` is already set per
+microsite, so the dimension fills in automatically. The dashboard shows a
+"Site" picker + a "Sites" tab as soon as ≥2 distinct hosts are detected.

package/src/articles/README.md

@@ -0,0 +1,325 @@
+# Articles — `@sonordev/site-kit/articles`
+
+## Publication routes and artwork (5.4.0)
+
+Use one routing object for the stock components and their SEO helpers. Existing
+sites keep `/article/slug` unless they opt in. `basePath` remains supported as a
+metadata alias; `basePath` takes precedence when both are provided.
+
+```tsx
+import { Article, ArticleList } from '@sonordev/site-kit/articles/server-ui'
+import {
+  createPublicationRoutes, generateArticleMetadata, generateArticleSchema,
+  generateArticleSitemap, generateArticleStaticParams, generateRssFeed,
+  getArticle,
+} from '@sonordev/site-kit/articles/server'
+import type { PublicationRoutingOptions } from '@sonordev/site-kit/articles/server'
+
+const siteUrl = 'https://example.com'
+const routing = {
+  basePath: '/theforge',
+  includeCategoryInPath: true,
+  categoryPath: (slug: string) => `/theforge?category=${encodeURIComponent(slug)}`,
+} satisfies PublicationRoutingOptions
+
+// Cards, related stories and cluster links now use /theforge/category/slug.
+const article = <Article slug="build-first" routing={routing} />
+const archive = <ArticleList routing={routing} />
+
+// Use these helpers from their corresponding Next.js route exports.
+const metadata = await generateArticleMetadata('build-first', { siteUrl, ...routing })
+const post = await getArticle('build-first')
+const schema = post ? generateArticleSchema(post, { siteUrl, ...routing }) : null
+// In app/theforge/[category]/[slug]/page.tsx, wrap it to pass the routing:
+// export function generateStaticParams() { return generateArticleStaticParams(routing) }
+const params = await generateArticleStaticParams(routing) // { category, slug }[]
+const sitemap = await generateArticleSitemap(siteUrl, {
+  ...routing,
+  includeCategories: false, // category filters don't need separate sitemap entries
+  includeClusters: false, // enable when your site implements cluster routes
+})
+const rss = await generateRssFeed({ siteUrl, siteName: 'The Forge', ...routing })
+const href = createPublicationRoutes(routing).post({ slug: 'build-first', category: 'guides' })
+```
+
+`routing` also works on `PublicationLayout`, `PublicationSidebar`, `RelatedPosts`, `AuthorPage`,
+`ClusterLandingPage`, and `ClusterNavigation`. To support another article shape,
+provide `postPath: post => '/articles/' + encodeURIComponent(post.slug)`.
+Callbacks return local paths; generated metadata, feeds, and sitemaps separately
+honor a valid `canonical_url`. The same routes apply to Atom and generated
+breadcrumb/cluster schemas. Supplied `schema`/`schema_json` objects stay intact.
+
+For custom layouts, `resolveArticleArtwork(post, 'article')` prefers
+`editorial_image`, preserving an empty decorative `editorial_image_alt`.
+`resolveArticleArtwork(post, 'card')` keeps the complete `featured_image`. Older API
+responses fall back to the featured image for both. The stock UI keeps generated
+Sonor cards fully visible, while manually selected photos keep their existing
+layout. Social metadata and RSS enclosures use the featured share card.
+
+The stock article renders accessible table scroll regions automatically. Custom
+renderers can call `wrapArticleTables(html)` and include `articleTableCss` within their
+`.sk-article-content` scope. Both exports are available from `article/server` and
+`article/server-ui`. The wrapper preserves the original table and is safe to apply
+twice. It's a layout transform, not a sanitizer; keep your existing content trust
+policy. Scrollbars and keyboard focus use `--sk-*` tokens.
+
+## Import server components from `article/server-ui`
+
+`Article`, `ArticleList`, `PublicationLayout`, `PublicationSidebar` and `RelatedPosts` are async
+server components. The `@sonordev/site-kit/articles` barrel is stamped `'use client'`
+at build time, and an async component inside a client module is not something Next
+can render — the route returns a 500.
+
+```tsx
+import { Article, ArticleList } from '@sonordev/site-kit/articles/server-ui'  // ✅
+import { Article } from '@sonordev/site-kit/articles'                      // ❌ 500s
+```
+
+The barrel still re-exports them for backwards compatibility and they will move out
+in the next major. Reach for `@sonordev/site-kit/articles` only for genuine client
+components: `TableOfContents`, `ArticleFAQ`, `AuthorCard`, `ServiceCallout`,
+`NewsletterWidget`.
+
+`NewsletterWidget` needs either an `onSubmit` callback or a `formSlug`
+pointing at a managed Sonor form (newsletter routing) — with neither it
+renders nothing rather than a form that discards emails. `Article` mounts a
+childless `ArticleViewTracker` client island that counts real readers (one POST
+per post per session, deferred to idle); it needs `SiteKitLayout`'s globals
+and silently no-ops without them.
+
+Data helpers live in `@sonordev/site-kit/articles/server`, which is `server-only` — a
+client import there is a build error rather than a runtime one.
+
+Sonor-managed article with SSG, topic clusters, E-E-A-T author profiles, and full SEO integration. Create posts in the Sonor dashboard — they appear on your site automatically.
+
+## Quick Start
+
+### Articles Index
+
+```tsx
+// app/article/page.tsx
+import { ArticleList, PublicationLayout } from '@sonordev/site-kit/articles/server-ui'
+import { generatePublicationMetadata } from '@sonordev/site-kit/articles/server'
+
+export async function generateMetadata() {
+  return generatePublicationMetadata({ siteName: 'My Site', siteUrl: 'https://example.com' })
+}
+
+export default function PublicationPage() {
+  return (
+    <PublicationLayout hero={{ title: 'The Forge', subtitle: 'Latest articles' }}>
+      <ArticleList showCategoryFilter showPagination />
+    </PublicationLayout>
+  )
+}
+```
+
+### Single Post
+
+```tsx
+// app/article/[slug]/page.tsx
+import { Article } from '@sonordev/site-kit/articles/server-ui'
+import {
+  generateArticleStaticParams,
+  generateArticleMetadata,
+  requireArticle,
+} from '@sonordev/site-kit/articles/server'
+
+export const generateStaticParams = generateArticleStaticParams
+
+type Props = { params: Promise<{ slug: string }> }
+
+export async function generateMetadata({ params }: Props) {
+  const { slug } = await params
+  await requireArticle(slug) // 404 for an unknown slug, before anything streams
+  return generateArticleMetadata(slug, { siteName: 'My Site', siteUrl: 'https://example.com' })
+}
+
+export default async function Post({ params }: Props) {
+  const { slug } = await params
+  return <Article slug={slug} showRelated showToc showAuthor />
+}
+```
+
+**A missing post is a 404.** `requireArticle`, `generateArticleMetadata` and
+`Article` all call Next's `notFound()` when the post doesn't exist, so a
+mistyped or deleted post URL answers 404 with `noindex`. They used to render a
+"Post Not Found" page on a 200 with an indexable title, which is a soft 404.
+Calling `requireArticle` from `generateMetadata` is what guarantees the status:
+metadata resolves before the page streams. To render your own missing-post
+state instead, pass `notFound: false` to `generateArticleMetadata` (its
+placeholder is marked `noindex`) and `notFound={false}` to `Article`.
+
+**A post with its own social card.** If the post route has an
+`opengraph-image.tsx` beside the page (see `@sonordev/site-kit/og/route`), pass
+`images: false`:
+
+```ts
+return generateArticleMetadata(slug, { siteName: 'My Site', images: false })
+```
+
+Otherwise the featured image is declared as `openGraph.images`, and Next lets
+declared images beat the file convention: the card never ships. `images: false`
+leaves the keys out entirely (Next checks `hasOwnProperty('images')`, so even
+`images: undefined` would hide the card). `sonor-setup doctor` flags a post
+route that has a card but still declares the image.
+
+### Topic Cluster Landing
+
+```tsx
+// app/article/topics/[slug]/page.tsx
+// From `article/server-ui`, not `article` — it's an async server component that fetches
+// the cluster, so it must stay out of the client-side `article` barrel.
+import { ClusterLandingPage } from '@sonordev/site-kit/articles/server-ui'
+
+export default function ClusterPage({ params }: { params: { slug: string } }) {
+  return <ClusterLandingPage slug={params.slug} basePath="/article" />
+}
+```
+
+## Components
+
+| Component | Import | Purpose |
+|-----------|--------|---------|
+| `Article` | `article/server-ui` | Single post with content, TOC, author, related |
+| `ArticleList` | `article/server-ui` | Post grid with pagination and category filter |
+| `PublicationLayout` | `article/server-ui` | Full layout with optional sidebar |
+| `PublicationSidebar` | `article/server-ui` | Categories, recent posts, tags |
+| `RelatedPosts` | `article/server-ui` | Related articles widget |
+| `PublicationPage` | `article/server-ui` | Drop-in publication index page (layout + list) |
+| `ArticlePage` | `article/server-ui` | Drop-in single-post page |
+| `CategoryPage` | `article/server-ui` | Drop-in category archive page |
+| `ClusterLandingPage` | `article/server-ui` | Topic cluster overview with pillar + support articles |
+| `ClusterNavigation` | `article` | Breadcrumb-style cluster nav |
+| `AuthorCard` | `article` | Author profile with E-E-A-T fields |
+| `TableOfContents` | `article` | Auto-generated from H2-H4 headings |
+| `ArticleFAQ` | `article` | FAQ section with schema |
+| `ServiceCallout` | `article` | CTA callout for related services |
+| `NewsletterWidget` | `article` | Email capture; needs `onSubmit` or `formSlug` |
+
+## Server Functions (`article/server`)
+
+```ts
+// Data fetching
+getArticle(slug)                    // Single post with full data, or null
+requireArticle(slug)                // Same, but calls notFound() when there's no post
+getAllArticleSlugs()                     // All published slugs (for generateStaticParams)
+getArticleCategories()                  // Categories with post counts
+getTopicCluster(slug)                // Cluster with pillar + support articles
+getTopicClusters()                   // All clusters
+
+// Next.js integration
+generateArticleStaticParams(routing?)   // [{ slug }], or [{ category, slug }] with includeCategoryInPath
+generateCategoryStaticParams()       // Returns [{ category }]
+generateAuthorStaticParams()         // Returns [{ slug }]
+// With no routing options, all three can be exported directly as
+// `generateStaticParams`; the props Next passes are ignored.
+generateArticleMetadata(slug, opts) // Next.js Metadata object; notFound() for a missing post.
+                                     // opts.images: false when the route has its own opengraph-image card
+generatePublicationMetadata(opts)      // Index page metadata
+generateArticleCategoryMetadata(name, opts)
+
+// Schema & SEO
+generateArticleSchema(post, opts)   // JSON-LD Article with FAQ
+generateArticleListSchema()             // JSON-LD for publication index
+generateFaqSchema(items)             // FAQ Page schema
+generateArticleSitemap(siteUrl)         // Sitemap entries for article
+
+// Validation
+validateArticleSeo(post)            // Returns field-by-field SEO audit
+validateSeoTitle(title, keyphrase?)  // Title length + keyword checks
+validateMetaDescription(desc)        // Description length check
+```
+
+## Multi-site projects
+
+One Sonor project can serve many domains (example.com plus its city
+microsites), each with its own article. A post with no site is project-wide and
+shows on every host; a post tagged `charlotte.example.com` shows only there.
+
+Every article read sends the site host automatically, as `?site=` on GETs and a
+`site` field on the related-posts and view-count POSTs. The host resolves from
+`NEXT_PUBLIC_SITE_URL`, which every microsite already sets, so most sites
+change nothing. To pin a host explicitly, pass `site`:
+
+```tsx
+<ArticleList site="charlotte.example.com" />           // also Article, PublicationSidebar, PublicationLayout, RelatedPosts, ClusterLandingPage
+await getArticle(slug, { site: 'charlotte.example.com' })
+await getAllArticles({ site: 'charlotte.example.com' })
+```
+
+`getAllArticleSlugs()` and `getAllAuthorSlugs()` take no arguments, so they can
+still be exported as `generateStaticParams`. They always use
+`NEXT_PUBLIC_SITE_URL`. Single-site projects and older API servers ignore
+`site`.
+
+## Article Props
+
+```ts
+interface ArticleProps {
+  slug: string
+  showRelated?: boolean    // Related posts section
+  showToc?: boolean        // Table of contents
+  showAuthor?: boolean     // Author card
+  unstyled?: boolean       // Skip default styles
+  notFound?: boolean       // Default true: notFound() when the post is missing. false renders a message.
+  className?: string
+  children?: (props: { post, toc, related }) => ReactNode  // Render prop
+}
+```
+
+## ArticleList Props
+
+```ts
+interface ArticleListProps {
+  category?: string           // Filter by category slug
+  tag?: string                // Filter by tag
+  author?: string             // Filter by author
+  featured?: boolean          // Featured posts only
+  search?: string             // Search posts
+  page?: number               // Default: 1
+  perPage?: number            // Default: 12
+  orderBy?: 'published_at' | 'title' | 'view_count'
+  order?: 'asc' | 'desc'
+  showCategoryFilter?: boolean
+  showPagination?: boolean
+  unstyled?: boolean
+  className?: string
+  children?: (props: { posts, pagination, categories }) => ReactNode
+}
+```
+
+## Key Types
+
+```ts
+interface Article {
+  slug: string; title: string; excerpt?: string; content: string;
+  featured_image?: string; author?: ArticleAuthor; category?: ArticleCategory;
+  tags?: string[]; meta_title?: string; meta_description?: string;
+  faq_items?: { question: string; answer: string }[];
+  article_type?: 'pillar' | 'support' | 'comparison' | 'faq' | 'glossary' | 'checklist';
+  cluster_slug?: string; reading_time?: number; // the API column ('X min read')
+  published_at?: string; status: 'draft' | 'published' | 'scheduled' | 'archived';
+}
+
+interface ArticleAuthor {
+  name: string; slug: string; bio?: string; avatar_url?: string;
+  title?: string; credentials?: string[]; expertise_areas?: string[];
+  years_experience?: number; is_subject_matter_expert?: boolean;
+}
+
+interface TopicCluster {
+  cluster_name: string; cluster_slug: string; core_topic: string;
+  geo_target?: string; target_service_page?: string; article_count: number;
+  pillar: Article | null; supports: Article[];
+}
+```
+
+## Styling
+
+Components use `.sk-article-*` and `.sk-article-list-*` classes. Import default styles:
+
+```tsx
+```
+
+Or use `unstyled` prop + `children` render prop for complete control.