@areca-cms/skills 0.3.0 → 0.5.0

package/skills/areca-sdk/references/api.md

@@ -6,11 +6,14 @@ ESM only. Import paths and their exports:
 
 | Export | Signature | Notes |
 | --- | --- | --- |
-| `defineSiteContent` | `<T extends SiteContentConfig>(config: T) => T` | Identity helper for `areca.config.ts` default export |
-| `manifestFromConfig` | `(config: SiteContentConfig) => SiteManifest` | Validates identifiers and duplicates, returns `{ collections }` |
-| `createArecaClient` | `(options?: { cmsUrl?; siteToken?; schemaToken? }) => ArecaClient` | Falls back to `ARECA_CMS_URL`, `ARECA_SITE_TOKEN`, `ARECA_SCHEMA_TOKEN`; URL and site token required at creation |
-| `getPreviewEntry` | `({ token: string; client?: ArecaClient }) => Promise<PreviewResult>` | `PreviewResult` = `{ collection, slug, entry }`. Needs `ARECA_CMS_URL` and `ARECA_SITE_TOKEN` (or pass `client`). |
+| `defineSiteContent` | `<const T extends {...}, const G extends {...}>(config: { siteKey; collections: T; globals?: G; assets? }) => same object` | Identity helper for `areca.config.ts`. Checks at compile time: `options` only on `select`, `collection` required on `reference` and must be a collection key, `after` must name a date key, `route` contains `$slug`. Globals take the same fields, with no `slug`, and may set `group` |
+| `manifestFromConfig` | `(config: SiteContentConfig) => SiteManifest` | Validates identifiers, duplicates and reserved keys (`resolve`, `href`, `preview`, `globals`, `previewGlobals`, `in`, `languages`, `matchLocale`), returns `{ collections }` plus `globals` only when there are sections |
+| `createArecaClient` | `(options?: { cmsUrl?; siteToken?; schemaToken? }) => ArecaClient` | Falls back to `ARECA_CMS_URL`, `ARECA_SITE_TOKEN`, `ARECA_SCHEMA_TOKEN`. Only the URL is required at creation; each call resolves the one credential it sends and fails before any request if it is missing |
+| `FieldDropsRequiredError` | `class extends Error { drops: FieldDrop[] }` | Thrown by `syncManifest` when the CMS refuses removed fields that still hold content. Nothing was changed. Retry with `confirmDropFields` only after the user confirms |
+| `getPreviewEntry` | `({ token: string; client?: ArecaClient; locale?: string }) => Promise<PreviewResult>` | `PreviewResult` = `PreviewEntryResult` `{ kind: 'entry', collection, slug, entry }` or `PreviewGlobalResult` `{ kind: 'global', global, entry }`. Needs `ARECA_CMS_URL` only (or pass `client`): the signed token is the credential. `locale` previews in that language |
+| `toCamelKey` | `(raw: string) => string` | Converts a raw CMS key such as `blog-posts` or `company_info` to its code name (`blogPosts`, `companyInfo`) |
 | `previewHeaders` | `() => { 'X-Robots-Tag': 'noindex, nofollow'; 'Cache-Control': 'no-store' }` | Apply to preview responses |
+| `matchLocale` | `(input: string \| readonly string[] \| null \| undefined, languages: SiteLanguages \| null \| undefined) => string \| undefined` | Picks a site language from a tag, a list of tags or an `Accept-Language` header: exact match, then subtag, then `languages.main`. Returns `undefined` without languages |
 | `seoHead` | `(seo: SeoMeta \| null \| undefined, options?: SeoHeadOptions) => { title, meta, links, scripts }` | TanStack Router `head()` shape |
 | `seoHeadHtml` | `(seo, options?) => string` | Escaped `<head>` HTML |
 | `seoJsonLd` | `(seo) => string[]` | Escaped JSON-LD strings |
@@ -18,32 +21,94 @@ ESM only. Import paths and their exports:
 | `richTextMarkdown` | `(value) => string` | `''` when empty |
 | `richTextHtml` | `(value) => string` | Static HTML; trusted CMS output only |
 
-`SeoHeadOptions` = `{ titleTemplate?: string /* contains %s */ | ((title: string) => string); siteName?: string }`.
+`SeoHeadOptions` = `{ titleTemplate?: string /* contains %s */ | ((title: string) => string); siteName?: string; locale?: string; alternates?: Partial<Record<string, string>>; main?: string }`. `locale` sets `og:locale`, `alternates` become `hreflang` links and `og:locale:alternate`, and `main` makes its alternate `x-default`.
 
 `ArecaClient` methods (plain `fetch`, no retries or caching):
 
 | Method | HTTP | Auth |
 | --- | --- | --- |
 | `fetchManifest(): Promise<SiteManifest>` | `GET /api/sites/manifest` | site token |
-| `syncManifest(config): Promise<{ ok: true }>` | `POST /api/sites/manifest` | schema token |
+| `syncManifest(config, opts?: { confirmDropFields?: string[] }): Promise<{ ok: true }>` | `POST /api/sites/manifest` | schema token. `confirmDropFields` lists confirmed removals as `<key>.<field>` |
 | `fetchSnapshot(opts?: { publicationId?: string }): Promise<Snapshot>` | `GET /api/sites/snapshot/current[?publicationId=]` | site token |
-| `fetchPreview(token: string): Promise<PreviewResult>` | `GET /api/sites/preview?token=` | signed preview token |
+| `fetchPreview(token: string, opts?: { locale?: string }): Promise<PreviewResult>` | `GET /api/sites/preview?token=[&locale=]` | signed preview token (no `Authorization` header) |
+
+Language types from the main entry: `SiteLanguages` (`{ main; all }`), `I18nConfig` (`{ paraglide? }`), `LocalizedValues` (`{ slug?; data; seo? }`, one language of an entry as published), `PreviewLocaleStatus` (`{ complete; missing }`), `PreviewSnapshotEntry` and `PreviewSnapshotGlobal` (the preview snapshot with `localeStatus`).
+
+Types from the main entry: `ArecaClient`, `ArecaClientOptions`, `FieldDrop` (`{ kind: 'collection' | 'global'; key; field; entries }`), `SiteContentConfig`, `AssetsConfig` (`{ download?, dir?, publicPath? }`), `CollectionConfig` (`{ route; label?; fields: Field[] }`), `Field` (a union discriminated on `type`: `reference` requires `collection`, `select` takes `options`, `date` and `datetime` take `after`), `FieldType`, `SiteManifest`, `Snapshot` (`{ publicationId, siteKey, createdAt, hash, collections, assets?, siteUrl?, schema? }`), `SnapshotAsset` (`{ id, storageKey, url, filename, mimeType, size }`), `SnapshotEntry` (the raw entry: `{ id, slug, publishedAt: string | null, data: Record<string, unknown>, seo? }`), `ImageValue`, `ReferenceValue<C = string>` (`{ collection: C; slug; id }`), `RichTextValue`, `SeoMeta`, `PreviewResult`, `PulledContentManifest`, `HeadMeta`, `HeadLink`, `HeadScript`, `SeoHeadOptions`, `SeoHeadResult`.
+
+Site content types: `GlobalConfig` (`{ label?, fields, seo?, previewPath? }`, `seo` defaults to `false`), `SnapshotGlobal` (`{ id, publishedAt, data, seo? }`), `PreviewEntryResult`, `PreviewGlobalResult`, and `SiteManifest` / `Snapshot`, which gain optional `globals` (and `globalSchema` on the snapshot).
+
+Typed content types (main entry, generated against `Register`):
+
+| Export | Meaning |
+| --- | --- |
+| `Register` | Interface that `areca.gen.ts` augments with `schema: typeof schema` |
+| `ContentSchema`, `ContentSchemaCollection`, `ContentSchemaField` | Shape of the generated schema (`key`, `label?`, `route`, `fields`; field `key`, `type`, `required`, `options?`, `collection?`) |
+| `RegisteredSchema` | The registered schema, or `ContentSchema` when nothing is registered |
+| `CollectionKey<S>` | camelCase collection keys |
+| `FieldKey<C, S>` | field keys of collection `C` |
+| `FieldValue<C, F, S>` | value type of one field, with null, missing and `''` where the CMS sends them |
+| `EntryData<C, S>` | `data` of collection `C` |
+| `Entry<C, S>` | `{ id, slug, publishedAt, collection: C, data, seo? }` |
+| `AnyEntry<S>` | union of the entries of every collection, discriminated on `collection` |
+| `Where<C, S>` | `where` option: field keys with equality or operator objects |
+| `OrderBy<C, S>` | `orderBy` option: sortable field keys with `'asc' \| 'desc'`, or an array |
+| `QueryOptions<C, S>` | `where`, `orderBy`, `limit`, `offset`, `with` |
+| `QueryResult<C, O, S>` | the entry type returned for query options `O`, with expanded references |
+| `RoutePath<R>` | a route with `$slug` replaced by `${string}` |
+| `Locale` | union of the site's language codes, from the generated `Register` (`string` without languages) |
+| `EntryLocale` | `{ locale; isFallback; locales; alternates }` added to each entry on a languages site |
+| `GlobalLocale` | `{ $locale; $isFallback }` added to each section value on a languages site |
+| `LocaleOptions` | per-call options: `{ locale?: Locale; fallback?: boolean }` (`fallback` defaults to `true`) |
+| `Href<C, S, L>` | the route type of collection `C`: the union of every language's route on a languages site, such as `` `/blog/${string}` ``. With language `L`, the route of that language, as `content.in(L)` gives |
+| `Content<S, G>` | the content object: one property per collection, plus `resolve`, `href`, `preview`, `globals` and `previewGlobals` |
+| `ContentGlobalSchema` | one site content section in the generated `globalSchema`: `key`, `label?`, `seo`, `previewPath?`, `fields` |
+| `GlobalSchema`, `RegisteredGlobalSchema` | the generated `globalSchema` (or the loose type when nothing is registered) |
+| `GlobalKey<G>` | camelCase section keys |
+| `GlobalData<K, G>` | the field values of section `K` |
+| `Global<K, G>` | one section: `GlobalData<K>`, plus `$seo: SeoMeta` when the section has `seo: true` |
+| `Globals<G>` | the object returned by `content.globals` and `previewGlobals`, one `Global` per section |
+| `GlobalsPreview<G>` | the result of `previewGlobals`: `{ globals, previewing, complete, issues }` |
+| `CollectionApi<C, S>` | `all`, `first`, `get`, `byId` and `href` of one collection |
+| `PreviewEntry<S>` | the union returned by `content.preview`, narrowed by `collection` and `complete`: `{ collection, slug, complete: true, entry: Entry, issues: [] }` or `{ collection, slug, complete: false, entry: DraftEntry, issues: string[] }` |
+| `DraftEntry<C, S>`, `DraftEntryData<C, S>` | the entry of an incomplete preview draft; every field has its optional type, whether or not it is required |
+
+## `@areca-cms/site-sdk/content` (Node only)
 
-Types: `ArecaClient`, `ArecaClientOptions`, `SiteContentConfig`, `CollectionConfig` (`{ route; label?; fields: Field[] }`), `Field` (`{ key; label; type: FieldType; required?; options?; collection?; description?; after? }`), `FieldType`, `SiteManifest`, `Snapshot` (`{ publicationId, siteKey, createdAt, hash, collections: Record<string, SnapshotEntry[]>, assets?: SnapshotAsset[], siteUrl? }`), `SnapshotAsset` (`{ id, storageKey, url, filename, mimeType, size }`), `AssetsConfig` (`{ download?, dir?, publicPath? }`), `SnapshotEntry` (`{ id, slug, publishedAt: string | null, data: Record<string, unknown>, seo?: SeoMeta }`), `ImageValue`, `ReferenceValue`, `RichTextValue`, `SeoMeta`, `PreviewResult`, `PulledContentManifest`, `HeadMeta`, `HeadLink`, `HeadScript`, `SeoHeadOptions`, `SeoHeadResult`.
+| Export | Signature | Notes |
+| --- | --- | --- |
+| `createContent` | `<const S extends ContentSchema, const G extends GlobalSchema>(options: { schema: S; globalSchema?: G; dir: string }) => Content<S, G>` | Builds the typed content object. `areca.gen.ts` calls it; use it only for another folder or schema. `dir` is resolved against `process.cwd()` on each call. Throws for a collection named `resolve`, `href`, `preview`, `globals` or `previewGlobals` |
+
+`content` (exported by `areca.gen.ts`) has one property per collection: `all(options?)`, `first(options?)`, `get(slug)`, `byId(id)`, `href(entryOrSlug)`. It also has `resolve(ref)` (returns `Entry | null`), `href(ref)` and `preview(token, { client? })` (returns `PreviewEntry<S>`; check `complete` before using `entry` as published content). Queries run in memory. `get` and `byId` return `undefined` for unknown values. A collection missing from the publication returns `[]`. `content.globals` is the object of enabled site content sections, keyed by camelCase key, and `content.previewGlobals(source, { client? })` returns it with one section replaced by its draft (see Site content below).
+
+## Site content (globals)
+
+| Export | Where | Notes |
+| --- | --- | --- |
+| `content.globals` | `areca.gen.ts` | `{ [camelKey]: Global }`. Read per call, from the current generation |
+| `content.previewGlobals` | `areca.gen.ts` | `(source: string \| PreviewResult \| null \| undefined, { client? }) => Promise<GlobalsPreview>`. A falsy source or an entry result returns the published values with `previewing: null`. A draft that fails validation keeps the published section, with `complete: false` and `issues` |
+| `readGlobalsFile` | `@areca-cms/site-sdk/pull` | `(outDir, manifest: PulledContentManifest) => Record<string, SnapshotGlobal>`. Reads `_globals.json` for the generation. Throws when the manifest lists globals but the file is missing |
+| `PulledContentManifest.globals` | `@areca-cms/site-sdk/pull` | Optional `string[]` of camel keys, absent when there are no sections |
+
+`$seo` is only present when the section has `seo: true`.
 
 ## `@areca-cms/site-sdk/pull` (Node only)
 
 | Export | Signature | Notes |
 | --- | --- | --- |
-| `pullContent` | `({ outDir: string; client?: ArecaClient; publicationId?: string; assets?: { dir: string; publicPath: string } }) => Promise<PullContentResult>` | With `assets`, downloads media into `dir` (absolute) and rewrites URLs to `publicPath`. Writes `outDir/.publications/publication-<random>/<collection>.json`, then atomically swaps `manifest.json`, which records the `publicationId`. Keeps the current and two previous generations. Defaults `publicationId` to `ARECA_SNAPSHOT_ID`. A failed pull keeps the previous generation. Result (`PullContentResult`) adds `localAssets?` and `warnings`. The `assets` option type is `ResolvedAssets`. |
-| `readContentManifest` | `(outDir: string) => PulledContentManifest` | `{ publicationId, hash, createdAt, collections counts, ... }` |
-| `readContent` | `<T = SnapshotEntry>(outDir: string, collectionKey: string, manifest?: PulledContentManifest) => T[]` | Throws `No content file for collection "x" ... Run \`areca pull\` first.` |
+| `pullContent` | `(options: PullContentOptions) => Promise<PullContentResult>` | Validates the publication against its schema, writes `outDir/.publications/publication-<random>/<camelCollection>.json`, switches `manifest.json`, then writes the types file. Keeps the current and two previous generations. Defaults `publicationId` to `ARECA_SNAPSHOT_ID`. A failed pull before the switch keeps the previous generation |
+| `readContentManifest` | `(outDir: string) => PulledContentManifest` | `{ publicationId, hash, createdAt, collections counts, generation?, assets? }` |
+| `readContent` | `<C extends CollectionKey>(outDir: string, collectionKey: C, manifest?: PulledContentManifest) => Entry<C>[]` | Typed by the collection key, no type parameter. Throws `No content file for collection "x" ... Run \`areca pull\` first.` |
+
+`PullContentOptions` = `{ outDir: string; client?: ArecaClient; publicationId?: string; assets?: ResolvedAssets; types?: string /* default <outDir>/areca.gen.ts */; contentDir?: string /* written into the module, default outDir */ }`.
 
-Type: `PullContentOptions`.
+`ResolvedAssets` = `{ dir: string /* absolute */; publicPath: string }`.
+
+`PullContentResult` = the snapshot as the CMS sent it, plus `schema`, `localAssets?` (`{ dir, total, downloaded }`), `warnings: string[]` and `typesPath`.
 
 ## Other subpaths
 
-- `@areca-cms/site-sdk/seo`: `seoHead`, `seoHeadHtml`, `seoJsonLd` and their types.
+- `@areca-cms/site-sdk/seo`: `seoHead`, `seoHeadHtml`, `seoJsonLd`, `ogLocale(tag)` (`nl-BE` gives `nl_BE` for `og:locale`) and their types.
 - `@areca-cms/site-sdk/rich-text`: `richTextDocument`, `richTextMarkdown`, `richTextHtml`.
 - `@areca-cms/site-sdk/rich-text-react`: `richTextComponents(components?: MarkdownComponents) => MarkdownComponents`. Wraps `img` so editor sizes are kept. Needs `react` (optional peer) and `@tanstack/markdown@1.0.0`.
 
@@ -64,5 +129,3 @@ Type: `PullContentOptions`.
 ```
 
 `seo` is missing on snapshots from older CMS versions. `seoHead` and `seoHeadHtml` then return empty head data.
-
-`PulledContentManifest` = `{ publicationId, hash, createdAt, collections: Record<string, number>, generation? }`.

package/skills/areca-sdk/references/languages.md

@@ -0,0 +1,177 @@
+# Multilingual sites (SDK)
+
+Read this when the CMS site has content languages. `get_site_info` in the MCP server, or `content.languages` in the SDK, tells you: `content.languages` is `null` on a single-language site, and then the `locale` options, `entry.locale` and the `Locale` type do not apply.
+
+## Configure the languages
+
+```ts
+// areca.config.ts
+import { defineSiteContent } from "@areca-cms/site-sdk";
+
+export default defineSiteContent({
+  siteKey: "acme",
+  languages: { main: "en", all: ["en", "nl"] },
+  i18n: { paraglide: "./src/paraglide/runtime.js" },
+  collections: {
+    articles: {
+      route: "/journal/$slug",
+      routes: { nl: "/journaal/$slug" },
+      fields: [
+        { key: "title", label: "Title", type: "text", required: true },
+        { key: "slug", label: "Slug", type: "slug", required: true },
+        { key: "price", label: "Price", type: "number", translatable: false },
+      ],
+    },
+  },
+  globals: {
+    homePage: { label: "Home page", requiredLanguages: ["nl"], fields: [/* ... */] },
+  },
+});
+```
+
+- `languages.main` is the fallback and the language of shared values. `languages.all` is the switcher order and includes `main`. Validation fails on duplicates, a `main` that is not in `all`, or an empty `all`.
+- `routes` maps a language to its route pattern. Keys must be in `languages.all`, and each pattern must contain `$slug`. Languages not listed use `route`. The pattern has no language prefix; the site adds it.
+- `requiredLanguages` on a collection or global lists the languages (other than main) that must be complete before an entry is marked ready. Every key must be in `languages.all`.
+- `translatable` on a field overrides the default. Text, textarea, richtext and url are per language by default; every other type is shared across languages.
+- `i18n.paraglide` is the Paraglide runtime path. When it is set, `areca pull` wires its `getLocale` into the generated content object.
+- `languages` and the per-language settings are sent with the schema by `manifest push`. `i18n` and `assets` stay local.
+- `manifest pull` lists language changes before it writes. Removing a language, or changing `main`, needs confirmation (`--yes` without a TTY). Adding one only appears in the diff. Ask the user before confirming: a removed language stops being served.
+- `areca pull` warns when `project.inlang/settings.json` disagrees with `languages`.
+
+The generated `areca.gen.ts` exports `languages` (`{ main, all }`) and the `Locale` union, which is registered for the typed API. Commit it like any other generated file.
+
+## Quick start with Paraglide
+
+1. `pnpm add @inlang/paraglide-js`, with `project.inlang/settings.json` listing the same `locales` as `languages.all`.
+2. Add the Vite plugin with `strategy: ['url', 'baseLocale']`, so the locale comes from the URL prefix only.
+3. Compile before anything imports the generated content: `paraglide-js compile --project ./project.inlang --outdir ./src/paraglide`. Then run `areca pull`.
+4. Wrap the server entry in `paraglideMiddleware`, so server rendering and prerendering see the URL's language.
+5. Localize the router's URLs with `deLocalizeUrl` and `localizeUrl` in `createRouter({ rewrite })`. Routes are written once in the main language.
+6. `content.articles.all()` now returns the language of the current URL. Use `getLocale()` for `Intl` formatting.
+
+Prerender every language's tree. Each entry's `alternates` gives its path in each language.
+
+## Other i18n libraries
+
+`areca pull` wires only Paraglide. For anything else, build your own content object from the generated schema and pass a resolver:
+
+```ts
+// src/content.ts
+import { createContent } from "@areca-cms/site-sdk/content";
+import { schema, globalSchema } from "./generated/content/areca.gen.ts";
+import i18next from "i18next";
+
+export const content = createContent({
+  schema,
+  globalSchema,
+  dir: "src/generated/content",
+  locale: () => i18next.resolvedLanguage, // called on every read; undefined = main language
+});
+```
+
+`createContent({ locale })` takes a string or a function. A function is called on each read, so it follows the library's current language. Use `i18n.global.locale.value` for vue-i18n, or `i18n.locale` from `@lingui/core` for Lingui.
+
+On a server with a per-request language (for example next-intl), do not rely on a global resolver. Pass the request's language per call: `content.in(locale).articles.all()` or `content.articles.all({ locale })`.
+
+## How the language is chosen
+
+For each read, the first of these that is set wins:
+
+1. the `locale` in the call: `all({ locale })`, `get(slug, { locale })`, `byId(id, { locale })`;
+2. the scope from `content.in(locale)`;
+3. the resolver from `createContent({ locale })`;
+4. the main language.
+
+`content.in(locale)` returns a new content object that reads in that language. A per-call `locale` still overrides the scope.
+
+Types follow the same scope. `Href` (and `href()` on a collection or `content.href(ref)`) is the union of every language's route, such as `` `/journal/${string}` | `/journaal/${string}` ``. `content.in("nl").articles.href(entry)` narrows it to the Dutch route `` `/journaal/${string}` ``.
+
+Media URLs are rewritten for every language view, so the main language and the other languages all serve the local files from `areca pull`, not CMS URLs.
+
+## Reading in a language
+
+Every entry carries:
+
+| Field | Meaning |
+| --- | --- |
+| `entry.locale` | The language of `data`, `slug` and `seo`. |
+| `entry.isFallback` | `true` when it is served in a language other than the one asked for. |
+| `entry.locales` | The languages with a complete translation of this entry. |
+| `entry.alternates` | The entry's URL in each of `locales`, from its per-language slug and route, for example `{ en: "/journal/backend", nl: "/journaal/backend" }`. |
+
+`content.languages` is `{ main, all }` or `null`. Section values (`content.globals`) carry `$locale` and `$isFallback` instead, and their other values stay flat.
+
+```ts
+const dutch = content.in("nl");
+const posts = dutch.articles.all({ orderBy: { title: "asc" } });
+
+// Only entries that really exist in Dutch
+const onlyDutch = content.articles.all({ locale: "nl", fallback: false });
+
+const post = content.articles.get("backend-ontwikkelaar", { locale: "nl" });
+if (post?.isFallback) {
+  // show the main-language text with a note, or link to the English page
+}
+```
+
+- `fallback` defaults to `true`. With `false`, `all` leaves out entries with no complete translation in the requested language, and `get` returns `undefined` for them.
+- `where` and `orderBy` run on the language's own values, so a Dutch title sorts by the Dutch title.
+- For a requested language, the entry is served from the first complete language of this chain: the exact tag (case-insensitive), its language subtag (`nl-BE` gives `nl`), the main language, then the first complete language in site order.
+
+Use `LocaleOptions` (`{ locale?: Locale; fallback?: boolean }`) to type your own wrappers around these calls.
+
+## Match the visitor's language
+
+```ts
+content.matchLocale("nl-BE");                                 // "nl"
+content.matchLocale("de;q=0.9, en-GB;q=0.8");                 // "en"
+content.matchLocale(request.headers.get("accept-language"));  // main language when nothing matches
+```
+
+`content.matchLocale(input)` tries each tag in preference order, first as an exact match and then by its subtag. `Accept-Language` headers are sorted by quality. It returns the main language when nothing matches, and `undefined` on a single-language site. The pure function `matchLocale(input, languages)` from `@areca-cms/site-sdk` takes the languages explicitly, which is useful in a redirect or in a resolver.
+
+## Alternate links and hreflang
+
+Pass the entry's alternates and language to `seoHead` (or `seoHeadHtml`):
+
+```ts
+import { seoHead } from "@areca-cms/site-sdk";
+
+export const head = ({ entry }) =>
+  seoHead(entry.seo, {
+    locale: entry.locale,
+    alternates: entry.alternates,
+    main: content.languages?.main,
+  });
+```
+
+- `locale` sets `og:locale`, using `ogLocale(tag)` from `@areca-cms/site-sdk/seo`: `nl` stays `nl`, `nl-BE` becomes `nl_BE`.
+- Each alternate becomes a `hreflang` link and an `og:locale:alternate`. The page's own locale is included as a link but not as an `og:locale:alternate`.
+- `main` makes the main language's alternate also the `x-default` link.
+- Relative alternate paths are made absolute from the site origin when the entry has a canonical URL.
+- For pages that aren't entries, build the same alternates from the path in each language.
+- Set the document's `lang` attribute to the page's language.
+
+## Preview in a language
+
+The CMS opens preview links with `&locale=<code>`. Pass it through:
+
+```ts
+const result = await content.preview(token, { locale: url.searchParams.get("locale") ?? undefined });
+// or without the content object:
+const raw = await getPreviewEntry({ token, locale: "nl" });
+```
+
+- `content.previewGlobals(source, { locale })` takes the same option for sections.
+- `client.fetchPreview(token, { locale })` sends the same query parameter.
+- A preview draft carries `localeStatus`: a map from each site language to `PreviewLocaleStatus` (`{ complete, missing }`, where `missing` lists the labels of the missing required fields). `PreviewSnapshotEntry` and `PreviewSnapshotGlobal` are the preview types that include it. Use it to show an incomplete draft in the language it was written in.
+- Preview responses are draft content. Send `previewHeaders()` (`X-Robots-Tag: noindex, nofollow`, `Cache-Control: no-store`) and keep them out of caches and search.
+
+## Checklist
+
+- `languages` in `areca.config.ts` matches the CMS site and `project.inlang/settings.json`.
+- `routes` for each language use the same segments as the router's localized URLs.
+- Shared values (prices, contact details, product names) are `translatable: false`.
+- Pages prerender in every language and link to their alternates.
+- Untranslated entries either fall back with a note or are left out with `fallback: false`.
+- Preview routes read `locale` from the query string and send `previewHeaders()`.

package/skills/areca-sdk/references/production.md

@@ -17,6 +17,7 @@ import { getPreviewEntry, previewHeaders } from "@areca-cms/site-sdk";
 try {
   const { collection, slug, entry } = await getPreviewEntry({ token });
   // render `entry` (same shape as SnapshotEntry) with the normal template
+  // (with the generated content object, `content.preview(token)` returns the typed entry)
   // and set every header from previewHeaders() plus <meta name="robots" content="noindex">
 } catch (error) {
   // Plain Error, no status field. The message holds the status:
@@ -25,6 +26,8 @@ try {
 }
 ```
 
+A site content section preview is different. The CMS opens the section's `previewPath` on the site (for example `/about`) with `?arecaPreview=<token>`, not `/__preview`. `getPreviewEntry` returns `{ kind: "global", global, entry }` for that token. Read the token on the page, then call `content.previewGlobals(token)` (or pass the `PreviewGlobalResult`). It returns `{ globals, previewing, complete, issues }`: `globals` has the section replaced by its draft when the draft is complete, and the published section otherwise. Use the draft only when `previewing` is this page's section, and show a note when `complete` is `false`. An expired or mistyped token makes the fetch throw, so catch it and serve the published values. Set `previewHeaders()` on the response as for entries.
+
 `getPreviewEntry` needs `ARECA_CMS_URL` and `ARECA_SITE_TOKEN` at runtime. Exclude `/__preview` from prerendering and CDN caching. In TanStack Start, wrap the fetch in a `createServerFn` handler.
 
 ## Health route (Production mode)
@@ -83,7 +86,12 @@ await pullContent({ outDir: "src/generated/content", client });
 | `404` / no publication on pull | Nothing is live yet. Go live in the CMS, then pull again. |
 | `429` | 300 requests/min per token. Wait for `Retry-After`. |
 | `400` / `413` on push | Invalid schema, or the manifest is over 256 KiB |
+| `Removing <key.field> deletes content` / `FieldDropsRequiredError` | Nothing was pushed. Ask the user before confirming, then re-run with `--confirm-drop <key.field>` (or `--yes`), or pass `confirmDropFields` to `syncManifest`. |
 | `No content file for collection` | Run `areca pull`, then check the collection key |
 | `Unsafe collection or field identifier` | Rename the key to match `^[A-Za-z][A-Za-z0-9_-]{0,63}$` |
+| `Collection key "<key>" is reserved` / `resolve`, `href`, `preview`, `globals`, `previewGlobals` | Collections cannot use these names, because the content object uses them. Rename the collection. Field keys may keep them. |
+| `Collection keys ... both map to` / `Field keys ... both map to` | Two keys have the same camelCase name, such as `blog-posts` and `blog_posts`. Rename one. |
+| `Publication does not match its schema` | An entry breaks its schema. Each line names the entry, field and problem. Fix the entry or the schema, publish, and pull again. Nothing is written. |
+| `Warning: Publication <id> has no embedded schema` | An older publication. Types use the current schema. Go live again to embed it. |
 | `Expected publication X, received Y` | Pinned pull mismatch. Check `ARECA_SNAPSHOT_ID`. |
 | TS config import fails | Use Node 24, or run through `tsx` |