@proveanything/smartlinks 2.0.37 → 2.0.39

package/dist/seo.js

@@ -0,0 +1,172 @@
+// =============================================================================
+// SEO + GEO helpers for apps served as websites (framework-agnostic).
+// =============================================================================
+// seo.head()       per-route <title>, description, Open Graph / Twitter tags, canonical, robots
+// seo.jsonLd()     place a structured-data block (replaces the previous one with the same id)
+// seo.schema.*     schema.org builders from platform data (Product, FAQPage, Organization, …)
+//
+// They write plain DOM, so whatever pre-renders the page (the platform's renderer, a crawler that runs
+// JavaScript) captures them. In SSR / no-document environments they're no-ops; the builders are pure.
+// =============================================================================
+const MARK = 'data-sl-seo';
+function doc() {
+    return typeof document !== 'undefined' && document && document.head ? document : null;
+}
+function setMeta(d, attr, key, content) {
+    let el = d.head.querySelector(`meta[${attr}="${key}"]`);
+    if (content === undefined || content === null || content === '') {
+        if (el && el.getAttribute(MARK) !== null)
+            el.remove();
+        return;
+    }
+    if (!el) {
+        el = d.createElement('meta');
+        el.setAttribute(attr, key);
+        el.setAttribute(MARK, '');
+        d.head.appendChild(el);
+    }
+    el.setAttribute('content', content);
+}
+/** Set this route's head tags. Call on every route change; unset fields are removed (if we added them). */
+export function head(h) {
+    const d = doc();
+    if (!d)
+        return;
+    if (h.title)
+        d.title = h.title;
+    setMeta(d, 'name', 'description', h.description);
+    setMeta(d, 'property', 'og:title', h.title);
+    setMeta(d, 'property', 'og:description', h.description);
+    setMeta(d, 'property', 'og:image', h.image);
+    setMeta(d, 'property', 'og:type', h.type || 'website');
+    setMeta(d, 'property', 'og:site_name', h.siteName);
+    setMeta(d, 'name', 'twitter:card', h.image ? 'summary_large_image' : 'summary');
+    setMeta(d, 'name', 'twitter:title', h.title);
+    setMeta(d, 'name', 'twitter:description', h.description);
+    setMeta(d, 'name', 'twitter:image', h.image);
+    setMeta(d, 'name', 'robots', h.noindex ? 'noindex, nofollow' : undefined);
+    let link = d.head.querySelector('link[rel="canonical"]');
+    if (h.canonical) {
+        if (!link) {
+            link = d.createElement('link');
+            link.setAttribute('rel', 'canonical');
+            link.setAttribute(MARK, '');
+            d.head.appendChild(link);
+        }
+        link.setAttribute('href', h.canonical);
+    }
+    else if (link && link.getAttribute(MARK) !== null) {
+        link.remove();
+    }
+}
+/**
+ * Place a JSON-LD structured-data block in <head>. `id` names the block, so calling again replaces it
+ * (e.g. per route); pass null to remove it. `<` is escaped so data can't close the script tag.
+ */
+export function jsonLd(id, data) {
+    const d = doc();
+    if (!d)
+        return;
+    const sel = `script[type="application/ld+json"][${MARK}="${id}"]`;
+    let el = d.head.querySelector(sel);
+    if (data === null) {
+        if (el)
+            el.remove();
+        return;
+    }
+    if (!el) {
+        el = d.createElement('script');
+        el.setAttribute('type', 'application/ld+json');
+        el.setAttribute(MARK, id);
+        d.head.appendChild(el);
+    }
+    el.textContent = JSON.stringify(data).replace(/</g, '\\u003c');
+}
+const CTX = 'https://schema.org';
+/** Drop undefined / null / empty values so the output stays valid and small. */
+function clean(o) {
+    for (const k of Object.keys(o)) {
+        const v = o[k];
+        if (v === undefined || v === null || v === '' || (Array.isArray(v) && v.length === 0))
+            delete o[k];
+    }
+    return o;
+}
+const imageOf = (x) => { var _a, _b, _c; return ((_a = x === null || x === void 0 ? void 0 : x.heroImage) === null || _a === void 0 ? void 0 : _a.url) || ((_b = x === null || x === void 0 ? void 0 : x.logoImage) === null || _b === void 0 ? void 0 : _b.url) || ((_c = x === null || x === void 0 ? void 0 : x.image) === null || _c === void 0 ? void 0 : _c.url) || (typeof (x === null || x === void 0 ? void 0 : x.image) === 'string' ? x.image : undefined); };
+export const schema = {
+    /** schema.org Product from a SmartLinks product. */
+    product(product, opts = {}) {
+        const images = [imageOf(product), ...(product.additionalImages || []).map((i) => i === null || i === void 0 ? void 0 : i.url)].filter(Boolean);
+        return clean({
+            '@context': CTX,
+            '@type': 'Product',
+            name: product.name,
+            description: product.description || undefined,
+            image: images.length > 1 ? images : images[0],
+            sku: product.sku || undefined,
+            gtin: product.gtin || product.ownGtin || undefined,
+            url: opts.url,
+            brand: opts.brand ? { '@type': 'Brand', name: opts.brand } : undefined,
+            offers: opts.offer ? clean({
+                '@type': 'Offer',
+                price: String(opts.offer.price),
+                priceCurrency: opts.offer.currency,
+                availability: opts.offer.availability ? `${CTX}/${opts.offer.availability}` : undefined,
+                url: opts.offer.url || opts.url,
+            }) : undefined,
+            aggregateRating: opts.rating ? { '@type': 'AggregateRating', ratingValue: opts.rating.value, reviewCount: opts.rating.count } : undefined,
+        });
+    },
+    /** schema.org FAQPage — answer-shaped content AI search can cite, and FAQ rich results. */
+    faqPage(items) {
+        return {
+            '@context': CTX,
+            '@type': 'FAQPage',
+            mainEntity: items.filter((i) => i && i.question && i.answer).map((i) => ({
+                '@type': 'Question',
+                name: i.question,
+                acceptedAnswer: { '@type': 'Answer', text: i.answer },
+            })),
+        };
+    },
+    /** schema.org Organization from a collection (the brand behind the site). */
+    organization(collection, opts = {}) {
+        return clean({
+            '@context': CTX,
+            '@type': 'Organization',
+            name: collection.title || collection.name,
+            description: collection.description || undefined,
+            logo: imageOf(collection),
+            url: opts.url || (collection.hubCustomDomain ? `https://${collection.hubCustomDomain}` : collection.siteHost ? `https://${collection.siteHost}` : undefined),
+            sameAs: opts.sameAs,
+        });
+    },
+    /** schema.org LocalBusiness — for a business with a place (shop, restaurant, studio). */
+    localBusiness(collection, opts = {}) {
+        const a = opts.address;
+        return clean(Object.assign(Object.assign({}, schema.organization(collection, { url: opts.url })), { '@type': opts.type || 'LocalBusiness', telephone: opts.telephone, address: a ? clean({ '@type': 'PostalAddress', streetAddress: a.street, addressLocality: a.locality, addressRegion: a.region, postalCode: a.postalCode, addressCountry: a.country }) : undefined, openingHours: opts.openingHours }));
+    },
+    /** schema.org BreadcrumbList from a trail of { name, url } (home first). */
+    breadcrumbs(trail) {
+        return {
+            '@context': CTX,
+            '@type': 'BreadcrumbList',
+            itemListElement: trail.map((t, i) => ({ '@type': 'ListItem', position: i + 1, name: t.name, item: t.url })),
+        };
+    },
+    /** schema.org Article (a blog post, news item, guide). Dates as ISO strings. */
+    article(a) {
+        return clean({
+            '@context': CTX,
+            '@type': 'Article',
+            headline: a.headline,
+            description: a.description,
+            image: a.image,
+            url: a.url,
+            datePublished: a.datePublished,
+            dateModified: a.dateModified || a.datePublished,
+            author: a.author ? { '@type': 'Person', name: a.author } : undefined,
+            publisher: a.publisher ? { '@type': 'Organization', name: a.publisher } : undefined,
+        });
+    },
+};

package/dist/site.d.ts

@@ -0,0 +1,10 @@
+declare global {
+    var __SL_READY__: boolean | undefined;
+}
+/**
+ * Tell the platform this page has finished rendering its content (data loaded, head tags set). The
+ * platform's page renderer takes its snapshot for search engines and AI crawlers at this point;
+ * without it, it waits for the network to go idle (capped). Call once per page, after your data
+ * renders. Harmless anywhere else.
+ */
+export declare function ready(): void;

package/dist/site.js

@@ -0,0 +1,18 @@
+// =============================================================================
+// site — for apps served as websites.
+// =============================================================================
+/**
+ * Tell the platform this page has finished rendering its content (data loaded, head tags set). The
+ * platform's page renderer takes its snapshot for search engines and AI crawlers at this point;
+ * without it, it waits for the network to go idle (capped). Call once per page, after your data
+ * renders. Harmless anywhere else.
+ */
+export function ready() {
+    if (typeof globalThis === 'undefined')
+        return;
+    globalThis.__SL_READY__ = true;
+    const w = typeof window !== 'undefined' ? window : null;
+    if (w && typeof w.dispatchEvent === 'function' && typeof w.CustomEvent === 'function') {
+        w.dispatchEvent(new w.CustomEvent('smartlinks:ready'));
+    }
+}

package/dist/types/appManifest.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="node" />
 /// <reference types="node" />
+import type { AppDataDeclaration, AppHeadlessDeclaration } from './headless.js';
 /**
  * A bundle (widget or container) as returned by the collection widgets endpoint.
  *
@@ -662,6 +663,16 @@ export interface AppManifest {
      * @see AppManifestFunctions
      */
     functions?: AppManifestFunctions;
+    /**
+     * The app's public data model: its data types, how each is stored, fields, examples and read
+     * recipes. Required for `headless`. @see AppDataDeclaration · docs/headless-providers.md
+     */
+    data?: AppDataDeclaration;
+    /**
+     * Opt-in: other sites and apps may install this app and use its content (a headless content
+     * provider). Validated by `smartlinks-headless`. @see AppHeadlessDeclaration
+     */
+    headless?: AppHeadlessDeclaration;
     [key: string]: any;
 }
 /**

package/dist/types/appManifest.js

@@ -1,2 +1 @@
-// src/types/appManifest.ts
 export {};

package/dist/types/headless.d.ts

@@ -0,0 +1,96 @@
+/** Field value types. Keep this set small: generated editors, typed reads and sites rely on it. */
+export type AppDataFieldType = 'string' | 'text' | 'richtext' | 'markdown' | 'number' | 'boolean' | 'date' | 'datetime' | 'enum' | 'url' | 'image' | 'file' | 'ref' | 'string[]' | 'ref[]' | 'json';
+export interface AppDataField {
+    type: AppDataFieldType;
+    label?: string;
+    description?: string;
+    required?: boolean;
+    /** Translated per language (string / text / richtext / markdown only). */
+    localized?: boolean;
+    /**
+     * The JSONB zone it lives in (app objects): `data` (default), `owner`, or `admin`. Only `data`
+     * can be public; `admin` is never readable on public endpoints.
+     */
+    zone?: 'data' | 'owner' | 'admin';
+    /** Readable by anonymous visitors (when the item's visibility is public). */
+    public?: boolean;
+    /** For `ref` / `ref[]`: the declared type id, or 'product' | 'contact' | 'proof'. */
+    to?: string;
+    /** For `enum`: the allowed values. */
+    options?: string[];
+}
+/** How a type's items are stored. */
+export type AppDataStorage = 
+/** App records (`SL.app.records`), filtered by recordType. The usual home for content. */
+{
+    kind: 'record';
+    recordType: string;
+}
+/** App cases (`SL.app.cases`) — requests that get resolved. */
+ | {
+    kind: 'case';
+    category?: string;
+}
+/** App threads (`SL.app.threads`) — discussions, Q&A, reviews. */
+ | {
+    kind: 'thread';
+    slug?: string;
+}
+/** App configuration (`SL.appConfiguration.getConfig` / data items) — settings, small lists. */
+ | {
+    kind: 'config';
+    key?: string;
+};
+export interface AppDataType {
+    /** What one item is, in a sentence. */
+    description: string;
+    storage: AppDataStorage;
+    /** The visibility items normally have (app objects): public, owner or admin. Default public. */
+    visibility?: 'public' | 'owner' | 'admin';
+    /** What an item can be attached to (app objects' anchor columns). */
+    anchors?: Array<'product' | 'variant' | 'batch' | 'proof' | 'contact'>;
+    fields: Record<string, AppDataField>;
+    /** How a site normally lists them. */
+    listing?: {
+        sort?: string[];
+        filters?: string[];
+    };
+    /** Real-shaped sample items (the `data` zone's JSON). At least one for a headless type. */
+    examples?: Array<Record<string, unknown>>;
+    /** SDK recipes a site uses. If omitted, the checker prints the standard ones for the storage. */
+    read?: {
+        list?: string;
+        get?: string;
+        notes?: string;
+    };
+    /** The app version that introduced this type. */
+    since?: string;
+}
+export interface AppDataDeclaration {
+    /** Semver of the data contract itself (not the app's version). Major = breaking. */
+    schemaVersion: string;
+    types: Record<string, AppDataType>;
+}
+/** What kind of content a provider supplies — how site builders find it. */
+export type HeadlessCategory = 'faq' | 'media' | 'pages' | 'articles' | 'catalog' | 'events' | 'locations' | 'people' | 'reviews' | 'documents' | 'forms' | 'other';
+export declare const HEADLESS_CATEGORIES: readonly HeadlessCategory[];
+/** SEO structured-data helpers a site should use with this content (`SL.seo.schema.*`). */
+export type HeadlessSeoHelper = 'faqPage' | 'product' | 'article' | 'breadcrumbs' | 'organization' | 'localBusiness';
+export interface AppHeadlessDeclaration {
+    /** What content this app holds, and when a site should use it rather than build its own. */
+    purpose: string;
+    categories: HeadlessCategory[];
+    /** The `data` types a site renders (the rest are supporting types, e.g. categories). */
+    primaryTypes: string[];
+    /** Where the business edits the content — the app's admin inside SmartLinks. Sites never build an editor for it. */
+    editedIn: {
+        label: string;
+        adminPath?: string;
+        notes?: string;
+    };
+    /** How a site should present it. */
+    render?: {
+        guidance?: string;
+        seo?: HeadlessSeoHelper[];
+    };
+}

package/dist/types/headless.js

@@ -0,0 +1,16 @@
+// =============================================================================
+// Headless providers — an app's declared public data model, and its promise that other sites and
+// apps can install it and use its content (FAQ, media, content pages, articles…).
+//
+// Two manifest blocks:
+//   data      the app's data types: how each is stored, its fields (JSON types, zone, public or not),
+//             examples, and how to read it. Useful on its own (typed reads, generated editors).
+//   headless  the opt-in: purpose, categories, which types a site renders, where the owner edits the
+//             content, rendering + SEO guidance. Requires a complete `data` block.
+//
+// Validate with `smartlinks-headless` (scripts/headless-check.mjs) or validateHeadless() (SDK).
+// Docs: docs/headless-providers.md.
+// =============================================================================
+export const HEADLESS_CATEGORIES = [
+    'faq', 'media', 'pages', 'articles', 'catalog', 'events', 'locations', 'people', 'reviews', 'documents', 'forms', 'other',
+];

package/dist/types/index.d.ts

@@ -42,3 +42,4 @@ export * from "./integrations.js";
 export * from "./research.js";
 export * from "./config.js";
 export * from "./widgets.js";
+export * from "./headless.js";

package/dist/types/index.js

@@ -44,3 +44,4 @@ export * from "./integrations.js";
 export * from "./research.js";
 export * from "./config.js";
 export * from "./widgets.js";
+export * from "./headless.js";

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.37  |  Generated: 2026-10-04T09:59:59.885Z
+Version: 2.0.39  |  Generated: 2026-10-05T14:14:46.558Z
 
 This is a concise summary of all available API functions and types.
 
@@ -26,6 +26,12 @@ For detailed guides on specific features:
 - **[iframe Responder](iframe-responder.md)** - iframe integration and cross-origin communication (incl. hand-rolled streaming protocol)
 - **[Utilities](utils.md)** - Helper functions for building portal paths, URLs, and common tasks
 - **[UI Utils](ui-utils.md)** - Reusable, themeable admin UI React component library for microapps
+- **[Headless Providers](headless-providers.md)** - Declaring an app's content for other sites: the manifest `data` + `headless` blocks (types, storage, public fields, examples, read recipes, categories), `SL.headless.validate`, `smartlinks-headless`, and the procedure for adding a headless mode
+- **[Websites: SEO + GEO](site-seo.md)** - For apps served as websites: platform-generated robots/sitemap/llms.txt, canonical addresses, `SL.seo.head` / `SL.seo.jsonLd` / `SL.seo.schema.*`, `SL.site.ready()`, routes in `sitemap-paths.txt`
+- **[Agent Tools](agent-tools.md)** - Exposing app functions as AI agent tools
+- **[Host Dependency Contract](host-dependency-contract.md)** - The shared dependencies (React, the SDK…) the host provides, and what an app must externalise
+- **[Theme Tokens](theme-tokens.md)** - The `--sl-*` semantic token contract hosts set and apps bind to (`theme.css`)
+- **[CSS Baseline](css-baseline.md)** - The frozen `sl-*` structural helper classes hosts guarantee
 - **[Caching](caching.md)** - Multi-tier caching strategy (in-memory, SessionStorage, IndexedDB) used by the SDK
 - **[Native Facade](native-facade.md)** - Contract layer for accessing device capabilities (share, NFC, haptics) across host shells
 - **[i18n](i18n.md)** - Internationalization and localization
@@ -2748,6 +2754,8 @@ interface AppManifest {
   publicViews?: PublicView[];
   executor?: AppManifestExecutor;
   functions?: AppManifestFunctions;
+  data?: AppDataDeclaration;
+  headless?: AppHeadlessDeclaration;
   [key: string]: any;
 }
 ```
@@ -6459,6 +6467,65 @@ interface FacetValueGetParams {
 
 **FacetValueDefinition** = `FacetValue`
 
+### headless
+
+**AppDataField** (interface)
+```typescript
+interface AppDataField {
+  type: AppDataFieldType;
+  label?: string;
+  description?: string;
+  required?: boolean;
+  localized?: boolean;
+  zone?: 'data' | 'owner' | 'admin';
+  public?: boolean;
+  to?: string;
+  options?: string[];
+}
+```
+
+**AppDataType** (interface)
+```typescript
+interface AppDataType {
+  description: string;
+  storage: AppDataStorage;
+  visibility?: 'public' | 'owner' | 'admin';
+  anchors?: Array<'product' | 'variant' | 'batch' | 'proof' | 'contact'>;
+  fields: Record<string, AppDataField>;
+  listing?: { sort?: string[]; filters?: string[] };
+  examples?: Array<Record<string, unknown>>;
+  read?: { list?: string; get?: string; notes?: string };
+  since?: string;
+}
+```
+
+**AppDataDeclaration** (interface)
+```typescript
+interface AppDataDeclaration {
+  schemaVersion: string;
+  types: Record<string, AppDataType>;
+}
+```
+
+**AppHeadlessDeclaration** (interface)
+```typescript
+interface AppHeadlessDeclaration {
+  purpose: string;
+  categories: HeadlessCategory[];
+  primaryTypes: string[];
+  editedIn: { label: string; adminPath?: string; notes?: string };
+  render?: { guidance?: string; seo?: HeadlessSeoHelper[] };
+}
+```
+
+**AppDataFieldType** = ``
+
+**AppDataStorage** = ``
+
+**HeadlessCategory** = ``
+
+**HeadlessSeoHelper** = `'faqPage' | 'product' | 'article' | 'breadcrumbs' | 'organization' | 'localBusiness'`
+
 ### iframeResponder
 
 **CachedData** (interface)
@@ -11131,22 +11198,22 @@ The release channel a call targets, or undefined for "the collection's installed
 **functionPath**(surface: 'public' | 'admin', collectionId: string, name: string, opts: FunctionCallOptions = {}) → `string`
 The API path a function call goes to (exported for hosts/tests that need the exact URL).
 
-**siteUrl**(collection: { siteHost?: string | null } | string,
-    name: string,
+**siteUrl**(collection: { siteHost?: string | null } | string,
+    name: string,
     opts: FunctionSiteUrlOptions & { appId?: string } = {}) → `string`
 The PUBLIC address of an app function on the collection's own site — what you give a third party as a webhook URL, or call from the collection's public pages: `https://<siteHost>/_fn/<appId>[/<channel>]/<name>[/<path>]`. Every HTTP method the function declares works there, with the raw body for signature checks. Pass the collection (or its siteHost). This address is for public/integration calls; signed-in calls from your app keep using {@link call} / {@link callAdmin}, so the user's SmartLinks session never goes to a tenant hostname. const col = await SL.collection.get(collectionId) const hookUrl = SL.functions.siteUrl(col, 'stripeWebhook', { appId: 'my-shop' }) // → https://acme.smartlinks.host/_fn/my-shop/stripeWebhook
 
-**call**(collectionId: string,
-    name: string,
-    body: Record<string, any> = {},
+**call**(collectionId: string,
+    name: string,
+    body: Record<string, any> = {},
     opts: FunctionCallOptions = {}) → `Promise<T>`
-Call a PUBLIC app server function inline (surface `'public'`). App-scoped: `POST /public/collection/:c/app/:appId/functions/:name`. // App calling its own function (appId from initializeApi({ appId })): const { value } = await SL.functions.call<{ value: number }>(collectionId, 'pressCounter') // Or address another app explicitly: await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'my-counter-app' })
+Call a PUBLIC app server function inline (surface `'public'`). App-scoped: `POST /fn/public/collection/:c/app/:appId/functions/:name`. // App calling its own function (appId from initializeApi({ appId })): const { value } = await SL.functions.call<{ value: number }>(collectionId, 'pressCounter') // Or address another app explicitly: await SL.functions.call(collectionId, 'pressCounter', {}, { appId: 'my-counter-app' })
 
-**callAdmin**(collectionId: string,
-    name: string,
-    body: Record<string, any> = {},
+**callAdmin**(collectionId: string,
+    name: string,
+    body: Record<string, any> = {},
     opts: FunctionCallOptions = {}) → `Promise<T>`
-Call an ADMIN app server function (surface `'admin'`; requires an admin session). App-scoped: `POST /admin/collection/:c/app/:appId/functions/:name`.
+Call an ADMIN app server function (surface `'admin'`; requires an admin session). App-scoped: `POST /fn/admin/collection/:c/app/:appId/functions/:name`.
 
 **list**(collectionId: string, opts: FunctionCallOptions = {}) → `Promise<FunctionListResponse>`
 List the public functions available for a collection (discovery). Scoped to one app when an appId is given (or set as the SDK app context): `GET /public/collection/:c[/app/:appId]/functions`.

package/docs/headless-providers.md

@@ -0,0 +1,112 @@
+# Headless providers: declaring an app's content for other sites
+
+A **headless provider** is an app whose content other sites and apps may use: an FAQ app, a media gallery, content pages, a blog. The site renders the content its own way. The business keeps editing it in the provider's own admin, inside SmartLinks. A site never builds an editor for provider content.
+
+To become a provider, an app declares two blocks in `app.manifest.json`:
+- **`data`**: its data types, meaning how each is stored, its fields, examples and read recipes;
+- **`headless`**: the opt-in, meaning its purpose, categories, which types a site renders, where the owner edits it, and rendering guidance.
+
+Site builders (the Forge agent included) read these declarations to decide "install the FAQ app and use its content" instead of inventing their own.
+
+## The `data` block
+
+```jsonc
+"data": {
+  "schemaVersion": "1.0.0",                 // semver of THIS contract; a major = a breaking change
+  "types": {
+    "<app>.<thing>": {                      // lowercase, dot-separated, e.g. "faq.item"
+      "description": "What one item is, in a sentence.",
+      "storage": { "kind": "record", "recordType": "<the recordType the app writes>" },
+      "visibility": "public",               // the visibility items normally have: public | owner | admin
+      "anchors": ["product"],               // optional: what items can be attached to
+      "fields": {
+        "<key>": {
+          "type": "string",                 // see field types
+          "label": "Question",
+          "required": true,
+          "localized": true,                // translated per language (text types only)
+          "public": true,                   // readable by anonymous visitors
+          "zone": "data"                    // data (default) | owner | admin
+        }
+      },
+      "listing": { "sort": ["order"], "filters": ["category"] },
+      "examples": [ { "<key>": "realistic value" } ],
+      "read": {                             // optional: defaults to the standard calls for the storage
+        "list": "SL.app.records.list(collectionId, appId, { recordType: '...', limit: 50 })",
+        "get":  "SL.app.records.get(collectionId, appId, recordId)",
+        "notes": "anything a site must know, e.g. 'sort by order, then title'"
+      }
+    }
+  }
+}
+```
+
+**Storage kinds:**
+
+| `storage.kind` | The app keeps items in | Read with |
+|---|---|---|
+| `record` (+ `recordType`) | App records: the usual home for content | `SL.app.records.list / get`, filtered by `recordType` |
+| `case` | App cases: requests that get resolved | `SL.app.cases.list / get` |
+| `thread` | App threads: discussions, Q&A, reviews | `SL.app.threads.list / get` |
+| `config` (+ optional `key`) | App configuration: settings, small fixed lists | `SL.appConfiguration.getConfig({ collectionId, appId })` |
+
+**What the read calls return.** This is fixed by the storage kind, so a provider never needs to describe it, and site builders get it from the checker and `forge-cms describe`:
+
+- **`record`, `case`, `thread`:** `list` returns `{ data: Item[], pagination: { total, limit, offset, hasMore } }`.
+  - The items are in **`response.data`**, never `response.items` or `response.records`.
+  - Each item's declared fields are in **`item.data`** (e.g. `record.data.question`). `id`, `status`, `productId` and the dates are top-level.
+  - Page with `offset` / `limit` while `pagination.hasMore`. `get` returns one item.
+- **`config`:** the configuration object. Items are in `config.<key>` when the type names a `key`.
+
+Products, contacts and proofs are platform data. Reference them with `ref` fields (`"to": "product"`); never redeclare them.
+
+**Field types:** `string`, `text`, `richtext` (HTML), `markdown`, `number`, `boolean`, `date` (YYYY-MM-DD), `datetime`, `enum` (+ `options`), `url`, `image` and `file` (a URL or `{ url, ... }`), `ref` and `ref[]` (+ `to`: a declared type id, or `product` / `contact` / `proof`), `string[]`, `json` (avoid where a typed field fits).
+
+**Zones and what's public.** App records, cases and threads have three JSONB zones: `data`, `owner` and `admin`. Only `data` can be public, and only when the item's visibility is `public`. Mark each field a visitor may read with `"public": true`. Internal fields (notes, moderation flags) are `zone: "admin"` and never public.
+
+**Examples** are the item's `data` JSON exactly as the app writes it, with realistic content, not lorem ipsum.
+
+## The `headless` block
+
+```jsonc
+"headless": {
+  "purpose": "What content this holds and when a site should use it instead of building its own.",
+  "categories": ["faq"],                    // faq | media | pages | articles | catalog | events | locations
+                                            // | people | reviews | documents | forms | other
+  "primaryTypes": ["faq.item"],             // the types a site renders; others are supporting (e.g. categories)
+  "editedIn": { "label": "FAQ → Questions", "adminPath": "#/questions" },
+  "render": {
+    "guidance": "Group by category; questions expand to show answers.",
+    "seo": ["faqPage"]                      // SL.seo.schema helpers a site should use
+  }
+}
+```
+
+A primary type must be readable by visitors: public visibility, at least one public field, and at least one example.
+
+## Checking a declaration
+
+- **In Forge:** `forge-headless check` validates it against the app's real public data on its test collection. `forge-headless register` validates it and records it in Forge, which makes the app a provider that site builds can find.
+- **Anywhere else:**
+  - `npx smartlinks-headless [appDir] [--collection <id> --app <appId>]`;
+  - or `SL.headless.validate(manifest, { samples })` in code.
+
+Errors block. Warnings are worth fixing, and the most useful one is *real data has "x" but it isn't declared*.
+
+## Adding a headless mode to an existing app (procedure)
+
+1. **Find what the app stores.** Search the source for its writes and reads:
+   - `SL.app.records.create / upsert / bulkUpsert` (note each `recordType`);
+   - `SL.app.cases`, `SL.app.threads`;
+   - `appConfiguration.setConfig` / data items.
+
+   Each distinct `recordType` (or config key) the business edits is a candidate type.
+2. **Find the fields.** Read the admin forms and the TypeScript types for what each item holds. Note which zone each field is written to.
+3. **Decide what's public.** Content a visitor sees is public. Notes, flags and anything personal are not, and move to `zone: "admin"` if the app keeps them in `data`.
+4. **Write the `data` block:** a type per content thing, its storage, fields, listing, and one or two realistic examples taken from the app's real data.
+5. **Write the `headless` block:** purpose, categories, primary types, where it's edited (the admin screen's name and route), and render and SEO guidance.
+6. **Check against real data** (`forge-headless check`). Declare any real fields you missed, or confirm they're internal.
+7. **Register** (`forge-headless register`) once it's valid.
+8. **Keep the data contract stable.** Adding fields or types is a minor bump of `schemaVersion`; renaming or removing them is a major one.
+
+Don't change how the app stores data just to declare it. The declaration describes what already exists. If something must change (say, an internal field sitting in the public `data` zone), make that a separate, deliberate change.