@proveanything/smartlinks 2.0.57 → 2.0.60

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.57  |  Generated: 2026-10-13T11:42:19.247Z
+Version: 2.0.60  |  Generated: 2026-10-13T16:25:55.817Z
 
 This is a concise summary of all available API functions and types.
 
@@ -65,7 +65,7 @@ For detailed guides on specific features:
 - **[Analytics Metadata Conventions](analytics-metadata-conventions.md)** - Standard recommended keys and conventions for analytics metadata fields
 - **[Loyalty: Points, Members & Earning Rules](loyalty.md)** - Loyalty schemes, automatic point earning via interaction rules, member balances, transaction history, and manual adjustments
 - **[Integrations](integrations.md)** - Inbound/outbound integration flows + the sealed-secret store; triggers (manual/event/schedule), field mappings, and the Syndigo/Event Hub outbound path
-- **[Connectors](connectors.md)** - Connector apps: a manifest `connector` block + server functions (testConnection/describeTarget/sample/transform/send/fetch) that the integration engine and console call for one external provider
+- **[Connectors](connectors.md)** - Connector apps (adapters for one external provider): a manifest `connector` block + server functions (testConnection/describeTarget/sample/fetch/shape/serialize/send); core does the mapping
 - **[AI Tools & Skills](ai-tools-and-skills.md)** - The AI capability catalog: skills apps invoke by name (e.g. research.brand), the tools the AI reaches for (web fetch/screenshot/brand assets/image gen), the agent loop, and how apps discover them
 - **[Deep Link Discovery](deep-link-discovery.md)** - Registering and discovering navigable app states for portal menus and AI orchestration
 - **[AI Guide Template](ai-guide-template.md)** - A sample for an app on how to build an AI setup guide
@@ -2908,12 +2908,15 @@ interface AppConnectorDeclaration {
   testConnection?: string
   describeTarget?: string
   sample?: string
-  transform?: string
+  shape?: string
+  serialize?: string
   send?: string
   fetch?: string
   }
   panels?: ConnectorPanel[]
   aiGuide?: string
+  recordId?: string
+  limits?: { requestsPerSecond?: number }
 }
 ```
 
@@ -2963,18 +2966,34 @@ interface ConnectorRecords {
 }
 ```
 
-**ConnectorTransformInput** (interface)
+**ConnectorShapeInput** (interface)
 ```typescript
-interface ConnectorTransformInput {
+interface ConnectorShapeInput {
   installation: ConnectorInstallation
   records: Array<Record<string, unknown>>
-  mapping: FieldMapping[]
 }
 ```
 
-**ConnectorTransformResult** (interface)
+**ConnectorShapeResult** (interface)
 ```typescript
-interface ConnectorTransformResult {
+interface ConnectorShapeResult {
+  documents: Array<Record<string, unknown> | null>
+  skipped?: Array<{ index: number; reason: string }>
+}
+```
+
+**ConnectorSerializeInput** (interface)
+```typescript
+interface ConnectorSerializeInput {
+  installation: ConnectorInstallation
+  documents: Array<Record<string, unknown>>
+  eventType?: string
+}
+```
+
+**ConnectorSerializeResult** (interface)
+```typescript
+interface ConnectorSerializeResult {
   payloads: Array<unknown | null>
   skipped?: Array<{ index: number; reason: string }>
 }
@@ -2991,7 +3010,15 @@ interface ConnectorSendInput {
 **ConnectorSendResult** (interface)
 ```typescript
 interface ConnectorSendResult {
-  results: Array<{ index: number; ok: boolean; status?: number; error?: string; externalId?: string }>
+  results: Array<{
+  index: number
+  ok: boolean
+  status?: number
+  error?: string
+  externalId?: string
+  retryable?: boolean
+  retryAfterSeconds?: number
+  }>
 }
 ```
 
@@ -7091,6 +7118,32 @@ interface IntegrationFlow {
   lastPollAt?: string | null
   lastCursor?: string | null
   totalSynced?: number | null
+  circuitOpenedAt?: string | null
+  circuitProbeAt?: string | null
+  circuitReason?: string | null
+}
+```
+
+**FailedRecord** (interface)
+```typescript
+interface FailedRecord {
+  id: string
+  entityId?: string | null
+  externalId?: string
+  status: 'failed' | 'dead'
+  attempts: number
+  nextAttemptAt?: string | null
+  lastError?: string | null
+  updatedAt?: string
+}
+```
+
+**FailedRecordList** (interface)
+```typescript
+interface FailedRecordList {
+  direction: FlowDirection
+  items: FailedRecord[]
+  nextCursor: string | null
 }
 ```
 
@@ -7144,6 +7197,7 @@ interface RunFlowSummary {
   created?: number
   updated?: number
   skipped?: number
+  held?: number
   status: RunStatus
   runId?: string
 }
@@ -7374,7 +7428,7 @@ interface RecordTypesResponse {
 
 **UpdateFlowInput** = `Partial<Omit<CreateFlowInput, 'direction'>> & {`
 
-**ConnectorConsoleStep** = `'testConnection' | 'describeTarget' | 'sample' | 'transform'`
+**ConnectorConsoleStep** = `'testConnection' | 'describeTarget' | 'sample' | 'shape' | 'serialize'`
 
 **RunTrigger** = `'manual' | 'event' | 'schedule' | 'test'`
 
@@ -11687,6 +11741,17 @@ Is enhanced logging active for a connection? GET /integrations/logging/:connecti
 **setLogging**(collectionId: string, connectionId: string, input: SetLoggingInput = {}) → `Promise<`
 Enable enhanced logging. POST /integrations/logging/:connectionId (omit ttlMinutes = until cancelled)
 
+**listFailed**(collectionId: string,
+    flowId: string,
+    query: { status?: 'failed' | 'dead'; limit?: number; cursor?: string } = {}) → `Promise<FailedRecordList>`
+A flow's failed / dead records. GET /integrations/flows/:id/failed
+
+**retryFailed**(collectionId: string, flowId: string, ids?: string[]) → `Promise<`
+Retry failed / dead records now (all of them when `ids` is omitted). POST /integrations/flows/:id/failed/retry
+
+**resumeFlow**(collectionId: string, flowId: string) → `Promise<`
+Resume a flow that paused itself (circuit open): held records go out now. POST /integrations/flows/:id/resume
+
 **cancelLogging**(collectionId: string, connectionId: string) → `Promise<`
 Cancel enhanced logging now. DELETE /integrations/logging/:connectionId
 
@@ -11702,7 +11767,7 @@ Save a connector's non-secret Connect-form values and/or settings. PUT /integrat
     appId: string,
     step: ConnectorConsoleStep,
     input: Record<string, unknown> & { flowId?: string } = {}) → `Promise<T>`
-Run a connector step from the console: `testConnection` → ConnectorTestResult, `describeTarget` → ConnectorTargetSchema, `sample` → ConnectorRecords, `transform` (a dry run) → ConnectorTransformResult. The server adds the installation; pass `flowId` to layer that flow's settings. POST /integrations/connectors/:appId/steps/:step
+Run a connector step from the console: `testConnection` → ConnectorTestResult, `describeTarget` → ConnectorTargetSchema, `sample` → ConnectorRecords, and dry runs of `shape` ({ records }) → ConnectorShapeResult and `serialize` ({ documents }) → ConnectorSerializeResult. The server adds the installation; pass `flowId` to layer that flow's settings. POST /integrations/connectors/:appId/steps/:step
 
 ### interactions
 

package/docs/app-manifest.md

@@ -440,7 +440,7 @@ this is just the manifest shape.
 
 Marks the app as an integration **connector** for one external provider: the integrations console
 lists it and draws its connect form and settings, and the integration engine calls its server
-functions (`testConnection`, `describeTarget`, `sample`, `transform`, `send`, `fetch`). The full
+functions (`testConnection`, `describeTarget`, `sample`, `fetch`, `shape`, `serialize`, `send`). It adapts the provider's format; core does each customer's mapping. The full
 contract is in the **[Connectors guide](connectors.md)**.
 
 ---

package/docs/connectors.md

@@ -9,16 +9,22 @@ Three layers, each with one job:
 
 | Layer | Holds |
 |---|---|
-| **Engine** (the API) | [Integration flows](integrations.md), runs and their logs, triggers (events, schedule, Run now), the secret store, the deterministic field mapper, generic transports (HTTP, Event Hub). No provider code. |
+| **Engine** (the API) | [Integration flows](integrations.md), runs and their logs, triggers (events, schedule, Run now), the secret store, **the mapping** (each customer's field mappings and rules), generic transports (HTTP, Event Hub). No provider code. |
 | **Integrations console** (a core app) | The one admin screen: installed connectors, connect forms, settings, the mapper with AI assist, flows, runs. |
-| **Connector apps** | One per provider: its connect form, settings, target schema, transform, send/fetch, and any provider-specific panels. |
+| **Connector apps** | One per provider: an **adapter**. Talks to the provider and converts between its format and a clean, provider-neutral document. |
+
+**A connector adapts; core maps.** A connector never holds a customer's mapping. It turns the
+provider's records into provider-neutral documents (`shape`), or provider-ready payloads out of
+documents core has already mapped (`serialize`). Every customer's mapping, routing and rules live in
+core, so they work the same for every provider and can be replayed and traced. This is the line
+SnapLogic (endpoint Snaps vs the Mapper), MuleSoft and Airbyte all draw.
 
 A flow that only posts JSON to a webhook or an Event Hub needs no connector; it uses the engine's
 generic transports (see [integrations.md](integrations.md)).
 
 **No AI at run time.** The AI helps an admin *author* a mapping in the console (from the connector's
 target schema plus real sample records); a person approves it, and it is saved as data and runs
-deterministically. A connector's `transform` must be deterministic too.
+deterministically. A connector's `shape` and `serialize` must be deterministic too.
 
 ---
 
@@ -33,8 +39,10 @@ deterministically. A connector's `transform` must be deterministic too.
   "entities": ["product"],
   "connection": {
     "fields": [
-      { "name": "appId",     "label": "App ID",     "secret": "oneworldsync-app-id",     "required": true },
-      { "name": "secretKey", "label": "Secret key", "secret": "oneworldsync-secret-key", "required": true },
+      // Optional: SmartLinks' own credentials are the default; a customer may enter theirs.
+      { "name": "appId",     "label": "App ID",     "secret": "oneworldsync-app-id" },
+      { "name": "secretKey", "label": "Secret key", "secret": "oneworldsync-secret-key" },
+      { "name": "gln", "label": "GLN", "required": true },
       { "name": "environment", "label": "Environment", "type": "select",
         "options": [ { "value": "preprod", "label": "Pre-production" }, { "value": "production", "label": "Production" } ] }
     ]
@@ -44,12 +52,14 @@ deterministically. A connector's `transform` must be deterministic too.
     "properties": { "targetMarket": { "type": "string", "default": "GB" } }
   },
   "presets": [
-    { "id": "import-products", "title": "Import products", "direction": "inbound", "entity": "product" }
+    { "id": "import-products", "title": "Import products", "direction": "inbound", "entity": "product",
+      "flow": { "config": { "fieldMappings": [ /* a suggested mapping the customer can edit */ ] } } }
   ],
   "functions": {                      // names of this app's server functions
     "testConnection": "testConnection",
     "describeTarget": "describeTarget",
     "sample": "sample",
+    "shape": "shape",
     "fetch": "fetch"
   },
   "panels": [ { "id": "explorer", "title": "Explorer", "component": "Explorer" } ],
@@ -74,12 +84,14 @@ Types: `AppConnectorDeclaration` and friends in `@proveanything/smartlinks` (`sr
 | `title` | Provider display name; defaults to the app name. |
 | `directions` | `inbound` (provider → SmartLinks), `outbound` (SmartLinks → provider), or both. |
 | `entities` | SmartLinks entities it maps, e.g. `["product"]`. |
-| `connection.fields[]` | The console's **Connect** form. A field with `secret` is stored as this app's secret of that name (write-only; never returned to the browser). Other fields are saved in the installation's connection settings. |
+| `connection.fields[]` | The console's **Connect** form. A field with `secret` is stored as this app's secret of that name on the collection (write-only; never returned to the browser). Other fields are saved in the installation's connection settings. |
 | `settings` | JSON Schema for installation settings; the console renders it as a form. |
-| `presets[]` | Ready-made flows ("Products → provider") with flow defaults. |
+| `presets[]` | Ready-made flows ("Products → provider"). A preset's `flow.config.fieldMappings` is a **suggested** mapping: the connector's knowledge of the provider, which the customer accepts or edits in core. |
 | `functions` | Which of this app's server functions implement each step (below). Fill in only what applies. |
 | `panels[]` | Provider-specific screens the console mounts (an API explorer, a status page). |
 | `aiGuide` | A guide the mapping assistant reads: the provider's quirks, required fields, good defaults. |
+| `recordId` | Path of the provider's own id in a fetched record (e.g. `gtin`). Inbound records are landed and matched by it, so a re-import updates the same product instead of creating another. Default `id`; a flow can override it (`config.upsert.externalIdPath`). |
+| `limits` | `{ requestsPerSecond }` toward the provider, enforced across every SmartLinks worker. |
 
 ---
 
@@ -87,28 +99,40 @@ Types: `AppConnectorDeclaration` and friends in `@proveanything/smartlinks` (`sr
 
 Each step names one of the app's server functions. Declare them as **http POST, `visibility:
 "admin"`, `authority: "collection"`**: the engine calls them with no signed-in user (a product edit, a
-schedule), and the console calls the same functions while an admin configures the flow
-(`functions.callAdmin(collectionId, name, input, { appId })`). The input arrives as `event.body`;
-return the result as JSON. Capabilities still cap what each one can do: declare the provider's hosts
-(`network:<host>`) and the secrets it reads (`secrets:<name>`).
+schedule), and the console calls the same functions while an admin configures the flow. The input
+arrives as `event.body`; return the result as JSON. Capabilities still cap what each one can do:
+declare the provider's hosts (`network:<host>`) and the secrets it reads (`secrets:<name>`).
 
 | Step | Called by | Input (`event.body`) | Returns |
 |---|---|---|---|
 | `testConnection` | Connect form, **Test** | `{ installation }` | `ConnectorTestResult` `{ ok, message }` |
-| `describeTarget` | Mapper opens | `{ installation }` | `ConnectorTargetSchema` `{ fields: [{ path, label, type, required, enum }] }`: the provider's fields *for this customer* |
+| `describeTarget` | Mapper opens | `{ installation }` | `ConnectorTargetSchema` `{ fields: [{ path, label, type, required, enum }] }`: the provider's fields *for this customer*. Outbound mappings target these paths. |
 | `sample` | Mapper, AI assist, dry run | `{ installation, limit }` | `ConnectorRecords` `{ records }`: real provider records |
-| `transform` | Every run | `ConnectorTransformInput` `{ installation, records, mapping }` | `ConnectorTransformResult` `{ payloads, skipped }`: one payload per record, same order; `null` skips one |
-| `send` | Every outbound run | `ConnectorSendInput` `{ installation, payloads }` | `ConnectorSendResult` `{ results: [{ index, ok, status, error, externalId }] }` |
 | `fetch` | Every inbound run | `ConnectorFetchInput` `{ installation, cursor, limit }` | `ConnectorRecords` `{ records, nextCursor }`: one page per call |
+| `shape` | Every inbound run (and sample dry runs) | `ConnectorShapeInput` `{ installation, records }` | `ConnectorShapeResult` `{ documents, skipped }`: one provider-neutral document per record, same order; `null` skips one |
+| `serialize` | Every outbound run | `ConnectorSerializeInput` `{ installation, documents, eventType? }`: documents core mapped to `describeTarget` paths; a deletion arrives as `{ id, _deleted: true }` | `ConnectorSerializeResult` `{ payloads, skipped }`: one provider payload per document, same order; `null` skips one |
+| `send` | Every outbound run | `ConnectorSendInput` `{ installation, payloads }` | `ConnectorSendResult` `{ results: [{ index, ok, status, error, externalId }] }` |
 
-What happens when a step is left out:
-
-- **No `transform`:** the engine's own mapper runs the flow's `fieldMappings` (direct, static, Liquid
-  template).
-- **No `send`:** the flow's own transport: HTTP (`config.connection`), or Azure Event Hub with
+**How a run flows:**
+- **Inbound:** `fetch` (paged; every record is landed as received) → `shape` → core maps the documents
+  with the flow's mapping → upsert, matched by `recordId`. Unchanged records aren't processed again; a
+  changed flow configuration replays the landed records without fetching.
+- **Outbound:** gather the SmartLinks records → core maps them to the provider's fields → `serialize`
+  → `send` (or a generic transport). A record identical to its last successful delivery isn't sent again.
+- Large runs are processed in short slices that resume after an interruption; there's no record cap.
+
+**What happens when a step is left out:**
+- **No `shape`:** core maps the provider records as they come.
+- **No `serialize`:** the mapped documents are sent as they are.
+- **No `send`:** the flow's own transport is used: HTTP (`config.connection`), or Azure Event Hub with
   `config.transport: 'eventhub'` and `config.eventHub`.
 - **No `describeTarget`:** the mapper offers free-text target paths.
 
+**What `shape` should produce:** plain, predictable JSON a person can map without reading the
+provider's documentation. Flatten the provider's envelopes, name things plainly, keep codes alongside
+their meanings, and put repeated sections (ingredients, allergens, nutrients, images) in arrays. The
+same provider record always gives the same document.
+
 ### `installation`
 
 Every step receives the installation it serves:
@@ -124,13 +148,15 @@ interface ConnectorInstallation {
 ```
 
 Secrets are never in it. Read them in the function with `ctx.secrets.get('<name>')`, which needs the
-matching `secrets:<name>` capability.
+matching `secrets:<name>` capability. A secret the customer set on their collection wins; otherwise the
+connector's own app-level secret of that name (set in Forge) is used, so a connector can ship with
+SmartLinks' credentials as the default.
 
-### Example: `fetch`
+### Example: `fetch` and `shape`
 
 ```ts
 // src/functions/index.ts (the app's functions bundle)
-import type { ConnectorFetchInput, ConnectorRecords } from '@proveanything/smartlinks'
+import type { ConnectorFetchInput, ConnectorRecords, ConnectorShapeInput, ConnectorShapeResult } from '@proveanything/smartlinks'
 
 export async function fetch(ctx: any, event: any): Promise<ConnectorRecords> {
   const { installation, cursor, limit = 50 } = event.body as ConnectorFetchInput
@@ -140,6 +166,18 @@ export async function fetch(ctx: any, event: any): Promise<ConnectorRecords> {
   const page = await res.json()
   return { records: page.items, nextCursor: page.next ?? null }
 }
+
+export async function shape(_ctx: any, event: any): Promise<ConnectorShapeResult> {
+  const { records } = event.body as ConnectorShapeInput
+  return {
+    documents: records.map((r: any) => ({
+      gtin: r.item?.gtin,
+      name: r.item?.tradeItemDescription?.[0]?.value,
+      brand: r.item?.brandName,
+      ingredients: (r.item?.ingredients ?? []).map((i: any) => ({ name: i.name, percent: i.percentage })),
+    })),
+  }
+}
 ```
 
 ---
@@ -148,9 +186,9 @@ export async function fetch(ctx: any, event: any): Promise<ConnectorRecords> {
 
 | What | Where |
 |---|---|
-| Connect-form values (non-secret), installation settings | The connector app's config on the collection: `appConfiguration` for `appId`, under `connector.connection` and `connector.settings`. |
-| Credentials | The connector app's secrets, by the names its fields declare. |
-| One flow's use of the connector | The flow: `config.connector = { appId, preset?, settings? }` (per-flow settings override the installation's), plus `config.fieldMappings`. |
+| Connect-form values (non-secret), installation settings | The connector app's config on the collection, in its admin-only zone (`admin.connector.connection`, `admin.connector.settings`). |
+| Credentials | The connector app's secrets, by the names its fields declare (the customer's on their collection, else the connector's default). |
+| One flow's use of the connector | The flow: `config.connector = { appId, preset?, settings? }` (per-flow settings override the installation's), plus `config.fieldMappings`, which core runs. |
 
 ```ts
 await integrations.createFlow(collectionId, {
@@ -162,7 +200,8 @@ await integrations.createFlow(collectionId, {
   targetEntity: 'product',
   config: {
     connector: { appId: 'oneworldsync', preset: 'import-products' },
-    fieldMappings: [ { targetPath: 'name', sourcePath: 'item.tradeItemDescription', transformType: 'direct' } ],
+    // Maps the connector's shaped documents (not the raw provider records) onto the product.
+    fieldMappings: [ { targetPath: 'name', sourcePath: 'name', transformType: 'direct' } ],
   },
 })
 ```
@@ -181,7 +220,9 @@ await secrets.put(collectionId, 'provider-key', value, { appId })              /
 await integrations.saveConnectorInstallation(collectionId, appId, { connection: { environment: 'production' } })
 const test = await integrations.runConnectorStep(collectionId, appId, 'testConnection')
 const target = await integrations.runConnectorStep(collectionId, appId, 'describeTarget')
-const dryRun = await integrations.runConnectorStep(collectionId, appId, 'transform', { records, mapping })
+const { records } = await integrations.runConnectorStep(collectionId, appId, 'sample', { limit: 5 })
+const shaped = await integrations.runConnectorStep(collectionId, appId, 'shape', { records })      // dry run
+const wire = await integrations.runConnectorStep(collectionId, appId, 'serialize', { documents })  // dry run
 ```
 
 `send` and `fetch` only run inside a flow. A flow run's summary carries `sent` (outbound) or
@@ -192,8 +233,9 @@ const dryRun = await integrations.runConnectorStep(collectionId, appId, 'transfo
 ## Panels
 
 A connector can contribute screens to the integrations console (an API explorer, say). Each
-`panels[]` entry names a component exported from the app's widgets bundle; the console mounts it host-side and passes it the
-collection and the installation. Panels are admin-only and call the connector's own functions.
+`panels[]` entry names a component exported from the app's widgets bundle; the console mounts it
+host-side and passes it the collection and the installation. Panels are admin-only and call the
+connector's own functions.
 
 ---
 

package/docs/integrations.md

@@ -19,6 +19,14 @@ Provider-specific logic (a provider's payload format, its API, its connect form)
 **connector app**, not in the engine: see **[Connectors](connectors.md)**. A flow uses one with
 `config.connector = { appId }`.
 
+**Reliability.** A record that fails is retried on its own with exponential backoff (honouring the
+destination's `Retry-After`); a permanent failure (most 4xx) or one out of attempts is **dead** and
+waits in `integrations.listFailed` for `integrations.retryFailed`. A destination that keeps failing
+**pauses the flow automatically** (`flow.circuitOpenedAt`): edits are held, small probes check for
+recovery, and it resumes on its own (or with `integrations.resumeFlow`). Every product and record
+change is recorded durably before it's dispatched, so an edit can't be missed; scheduled sweeps are
+the reconciliation net.
+
 Credentials are **never** stored on the flow. The connection holds an opaque
 `credentialRef` into the **sealed-secret store** (`secrets` namespace); the value is sealed
 at rest and resolved server-side only, at execution.

package/docs/site-seo.md

@@ -1,68 +1,69 @@
-# Websites: search engines and AI crawlers (SEO + GEO)
-
-For apps served as websites (an app site at `<name>.smartlinks.host` or a custom domain). Hub sites
-get all of this from Hub.
-
-## What the platform does for you
-
-- **`/robots.txt`, `/sitemap.xml`, `/llms.txt`** are generated on the site's own address. Don't ship
-  `robots.txt` or `sitemap.xml`: one build serves many sites, and sitemap URLs must be absolute on
-  the site's host, which the build can't know.
-- **List every page** in `public/sitemap-paths.txt`, one `<path> [Title]` per line, in menu order
-  (`/ Home`, `/menu Menu`, `/book Book a table`). They go into the sitemap and `llms.txt` (titled)
-  on the right host, and Forge's preview uses the same list as its page menu. Keep it in step with
-  the router. Pre-rendered pages (`about/index.html`) are found automatically.
-- **Canonical address.** A site can answer on its automatic address, a chosen name and a custom
-  domain. Every page gets `Link: <https://{canonical}{path}>; rel="canonical"`, so search engines
-  consolidate on one: the custom domain, else the chosen name, else the automatic address. Don't set
-  your own canonical unless a page has a different canonical page.
-- **Previews stay out of search.** A sandbox collection's sites, and any test build (dev, alpha,
-  beta), are served with `X-Robots-Tag: noindex` and a `robots.txt` that disallows everything,
-  whatever the build ships.
-
-## What you do: `SL.seo` and `SL.site`
-
-```ts
-import * as SL from '@proveanything/smartlinks'
-
-// Per route, from its data — on every route change:
-SL.seo.head({
-  title: `${product.name} — ${brand}`,
-  description: product.description,       // ~150 characters, says what the page is
-  image: product.heroImage?.url,           // absolute; used for link previews
-  type: 'product',                         // 'website' | 'article' | 'product'
-})
-
-// Structured data (schema.org JSON-LD). The id names the block, so calling again replaces it:
-SL.seo.jsonLd('page', SL.seo.schema.product(product, { url: location.href, brand }))
-SL.seo.jsonLd('faq', SL.seo.schema.faqPage(faqs.map((f) => ({ question: f.q, answer: f.a }))))
-SL.seo.jsonLd('org', SL.seo.schema.organization(collection))
-
-// When the page's data has rendered:
-SL.site.ready()
-```
-
-| Builder | For |
-|---|---|
-| `schema.product(product, { url, brand, offer, rating })` | product pages (`offer` only when it's really sold) |
-| `schema.faqPage([{ question, answer }])` | FAQs: rich results, and the answer-shaped content AI search cites |
-| `schema.organization(collection)` | the brand behind the site (home page) |
-| `schema.localBusiness(collection, { type, address, telephone, openingHours })` | a business with a place (`type: 'Florist'`, `'Restaurant'`…) |
-| `schema.breadcrumbs([{ name, url }])` | nested pages |
-| `schema.article({ headline, datePublished, … })` | posts, guides, news |
-
-`seo.head` removes tags a previous route set and the next one doesn't. Both are no-ops without a
-`document` (SSR, tests).
-
-`site.ready()` tells the platform's page renderer the page is complete, so it can snapshot the
-content for crawlers that don't run JavaScript. Without it, the renderer waits for the network to go
-quiet.
-
-## Content that gets found
-
-- **Content in the page, not behind interaction.** FAQ answers in `<details>` are fine; answers
-  fetched only when a question is clicked aren't seen.
-- **One `<h1>` per page**, a logical heading order, `alt` text on content images.
-- **Answer-shaped writing.** A short summary near the top, question-style headings where they fit.
-  This is what AI assistants quote.
-- **Real links** (`<a href>`) between pages, never hash routes.
+# Websites: search engines and AI crawlers (SEO + GEO)
+
+For apps served as websites (an app site at `<name>.smartlinks.host` or a custom domain). Hub sites
+get all of this from Hub.
+
+## What the platform does for you
+
+- **Every page is server-rendered.** A website runs on the SmartLinks site runtime (see
+  [websites.md](websites.md)): the first response for any URL is the finished HTML, with its title,
+  description, link-preview image, structured data and real status codes (404s are 404s). Search
+  engines, AI crawlers and link previews read it without running JavaScript.
+- **`/robots.txt`, `/sitemap.xml`, `/llms.txt`** are generated on the site's own address. Don't ship
+  `robots.txt` or `sitemap.xml`: one build serves many sites, and sitemap URLs must be absolute on
+  the site's host, which the build can't know.
+- **List every page** in `public/sitemap-paths.txt`, one `<path> [Title]` per line, in menu order
+  (`/ Home`, `/menu Menu`, `/book Book a table`). They go into the sitemap and `llms.txt` (titled)
+  on the right host, and Forge's preview uses the same list as its page menu. Keep it in step with
+  the router.
+- **Canonical address.** A site can answer on its automatic address, a chosen name and a custom
+  domain. Every page gets `Link: <https://{canonical}{path}>; rel="canonical"`, so search engines
+  consolidate on one: the custom domain, else the chosen name, else the automatic address. Don't set
+  your own canonical unless a page has a different canonical page.
+- **Previews stay out of search.** A sandbox collection's sites, and any test build (dev, alpha,
+  beta), are served with `X-Robots-Tag: noindex` and a `robots.txt` that disallows everything,
+  whatever the build ships.
+
+## What you do: `SL.seo` and `SL.site`
+
+```ts
+import * as SL from '@proveanything/smartlinks'
+
+// Per route, from its data — on every route change:
+SL.seo.head({
+  title: `${product.name} — ${brand}`,
+  description: product.description,       // ~150 characters, says what the page is
+  image: product.heroImage?.url,           // absolute; used for link previews
+  type: 'product',                         // 'website' | 'article' | 'product'
+})
+
+// Structured data (schema.org JSON-LD). The id names the block, so calling again replaces it:
+SL.seo.jsonLd('page', SL.seo.schema.product(product, { url: location.href, brand }))
+SL.seo.jsonLd('faq', SL.seo.schema.faqPage(faqs.map((f) => ({ question: f.q, answer: f.a }))))
+SL.seo.jsonLd('org', SL.seo.schema.organization(collection))
+
+```
+
+| Builder | For |
+|---|---|
+| `schema.product(product, { url, brand, offer, rating })` | product pages (`offer` only when it's really sold) |
+| `schema.faqPage([{ question, answer }])` | FAQs: rich results, and the answer-shaped content AI search cites |
+| `schema.organization(collection)` | the brand behind the site (home page) |
+| `schema.localBusiness(collection, { type, address, telephone, openingHours })` | a business with a place (`type: 'Florist'`, `'Restaurant'`…) |
+| `schema.breadcrumbs([{ name, url }])` | nested pages |
+| `schema.article({ headline, datePublished, … })` | posts, guides, news |
+
+`seo.head` removes tags a previous route set and the next one doesn't. Both are no-ops without a
+`document`. In a server-rendered site, prefer the router's own head support (TanStack Start's route
+`head()`), so the tags are in the server's HTML; use `SL.seo.schema.*` to build the JSON-LD for it.
+
+`SL.site.ready()` is no longer needed: pages arrive finished from the server.
+
+## Content that gets found
+
+- **Content in the page, not behind interaction.** FAQ answers in `<details>` are fine; answers
+  fetched only when a question is clicked aren't seen.
+- **One `<h1>` per page**, a logical heading order, `alt` text on content images.
+- **Answer-shaped writing.** A short summary near the top, question-style headings where they fit.
+  This is what AI assistants quote.
+- **Real links** (`<a href>`) between pages, never hash routes.