@proveanything/smartlinks 2.0.57 → 2.0.58

package/dist/api/integrations.d.ts

@@ -70,7 +70,8 @@ export declare namespace integrations {
     }>;
     /**
      * Run a connector step from the console: `testConnection` → ConnectorTestResult, `describeTarget` →
-     * ConnectorTargetSchema, `sample` → ConnectorRecords, `transform` (a dry run) → ConnectorTransformResult.
+     * 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
      */

package/dist/api/integrations.js

@@ -152,7 +152,8 @@ export var integrations;
     integrations.saveConnectorInstallation = saveConnectorInstallation;
     /**
      * Run a connector step from the console: `testConnection` → ConnectorTestResult, `describeTarget` →
-     * ConnectorTargetSchema, `sample` → ConnectorRecords, `transform` (a dry run) → ConnectorTransformResult.
+     * 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
      */

package/dist/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.58  |  Generated: 2026-10-13T14:08:01.791Z
 
 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,7 +2908,8 @@ interface AppConnectorDeclaration {
   testConnection?: string
   describeTarget?: string
   sample?: string
-  transform?: string
+  shape?: string
+  serialize?: string
   send?: string
   fetch?: string
   }
@@ -2963,18 +2964,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 }>
 }
@@ -7374,7 +7391,7 @@ interface RecordTypesResponse {
 
 **UpdateFlowInput** = `Partial<Omit<CreateFlowInput, 'direction'>> & {`
 
-**ConnectorConsoleStep** = `'testConnection' | 'describeTarget' | 'sample' | 'transform'`
+**ConnectorConsoleStep** = `'testConnection' | 'describeTarget' | 'sample' | 'shape' | 'serialize'`
 
 **RunTrigger** = `'manual' | 'event' | 'schedule' | 'test'`
 
@@ -11702,7 +11719,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/dist/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/dist/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,9 +84,9 @@ 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. |
@@ -87,28 +97,37 @@ 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:
+**How a run flows:**
+- **Inbound:** `fetch` (paged) → `shape` → core maps the documents with the flow's mapping → upsert.
+- **Outbound:** gather the SmartLinks records → core maps them to the provider's fields → `serialize`
+  → `send` (or a generic transport).
 
-- **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
+**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 +143,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 +161,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 +181,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 +195,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 +215,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 +228,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/dist/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.

package/dist/docs/websites.md

@@ -0,0 +1,91 @@
+# Websites: server-rendered on the SmartLinks site runtime
+
+A website built on SmartLinks is an app whose public side is a **server-rendered site** at its own
+address: an automatic `*.smartlinks.host` name, a chosen name, or the business's own domain. Every
+page arrives as finished HTML, so search engines, AI crawlers and link previews see the real
+content, and visitors see it before any JavaScript runs.
+
+## How a request is served
+
+```
+visitor / crawler / agent
+  └─► SmartLinks site router (edge)
+        ├─ /robots.txt, /sitemap.xml, /llms.txt     made by the platform (site-seo.md)
+        ├─ a file in your build (has an extension)   served from the build, cached at the edge
+        └─ anything else                             your site's server renders it
+              • runs in an isolated worker, close to the SmartLinks API
+              • may call the SmartLinks API and the hosts you declare, nothing else
+              • request header x-sl-site says which site it is (SL.site.fromRequest)
+```
+
+The router also adds the canonical or noindex header, the security headers, and
+`window.__SMARTLINKS_SITE__` to every HTML page (read in the browser with `SL.site.current()` or
+`SL.readContext()`).
+
+## The build
+
+The website template (TanStack Start) produces this; you don't write it by hand.
+
+```
+dist/
+├── index.html? / assets/…       the client build (hashed files: cached for a year)
+├── sitemap-paths.txt            your pages, "<path> [Title]" per line (site-seo.md)
+├── _server/                     the server bundle: one ES module entry + its chunks
+│   └── index.mjs                exports default { fetch(request, env, ctx) }  (WinterTC)
+└── app.manifest.json
+```
+
+Manifest:
+
+```jsonc
+"site": {
+  "server": {
+    "main": "_server/index.mjs",            // the server entry, inside the build
+    "compatibilityFlags": ["nodejs_compat"] // allowed: nodejs_compat, nodejs_compat_v2, nodejs_als
+  },
+  "network": ["api.example-weather.com"]    // other hosts the server may call (optional)
+}
+```
+
+On publish, the server folder becomes the site's server for that channel. Promote copies the same
+bytes. `_server/` is never served to visitors.
+
+## The server's rules
+
+- **Which site:** `const site = SL.site.fromRequest(request)` gives `{ host, collectionId, appId,
+  channel, canonicalHost }`. One build serves every site it's installed on, so always take the
+  collection from here, never from a constant.
+- **Data:** call the SmartLinks API with the SDK as you would in the browser. The server reads what
+  an anonymous visitor could read on that site, and only that collection. It holds no keys and no
+  signed-in user.
+- **Writes** (contact forms, entries, sign-ups) go to your app's **server functions**
+  (server-functions.md), called from the browser as today. Their capabilities, secrets and limits
+  apply.
+- **Other hosts:** only those in `site.network`. Anything else is refused (`403 Blocked`).
+- **Limits per request:** a CPU-time budget and a cap on outgoing calls. A page that needs more is
+  doing work that belongs in a server function or a scheduled job.
+- **No secrets** in the server bundle and no Node built-ins beyond `nodejs_compat`.
+
+## Caching
+
+The router keeps a rendered page at the edge when your response says it may:
+
+| Your response | At the edge |
+|---|---|
+| `Cache-Control: public, s-maxage=300` (the template's default for pages) | kept up to 5 minutes |
+| `private`, `no-store`, `no-cache`, or a `Set-Cookie` | never kept |
+| no `Cache-Control` | never kept |
+
+Cached pages are keyed by the release and the collection's **content generation**: when products,
+public app records, app settings or the collection change, the generation moves and every page of
+the collection's sites re-renders on its next visit (within about 30 seconds). Publishing a release
+does the same. Tracking parameters (`utm_*`, `gclid`, `fbclid`…) don't create separate entries.
+
+Keep pages the same for every visitor. Anything personal (a signed-in owner's products, a basket)
+renders in the browser after load.
+
+## Locally
+
+`npm run dev` runs the site with your dev collection (`.env`: `VITE_SL_COLLECTION_ID`), because
+there's no router to say which site it is: `SL.site.fromRequest()` is null, so fall back to it.
+Forge's preview runs the same server code the site runtime does.

package/dist/openapi.yaml

@@ -19766,7 +19766,9 @@ components:
           type: string
         sample:
           type: string
-        transform:
+        shape:
+          type: string
+        serialize:
           type: string
         send:
           type: string
@@ -19860,7 +19862,7 @@ components:
           type: string
       required:
         - records
-    ConnectorTransformInput:
+    ConnectorShapeInput:
       type: object
       properties:
         installation:
@@ -19870,15 +19872,40 @@ components:
           items:
             type: object
             additionalProperties: true
-        mapping:
+      required:
+        - installation
+        - records
+    ConnectorShapeResult:
+      type: object
+      properties:
+        documents:
           type: array
           items:
-            $ref: "#/components/schemas/FieldMapping"
+            type: object
+            additionalProperties: true
+        skipped:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+      required:
+        - documents
+    ConnectorSerializeInput:
+      type: object
+      properties:
+        installation:
+          $ref: "#/components/schemas/ConnectorInstallation"
+        documents:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        eventType:
+          type: string
       required:
         - installation
-        - records
-        - mapping
-    ConnectorTransformResult:
+        - documents
+    ConnectorSerializeResult:
       type: object
       properties:
         payloads:
@@ -26734,7 +26761,8 @@ components:
         - testConnection
         - describeTarget
         - sample
-        - transform
+        - shape
+        - serialize
     RunTrigger:
       type: string
       enum: