@areca-cms/skills 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to `@areca-cms/skills`.
 
+## 0.4.0 (2026-10-14)
+
+### Features
+
+- add site content (globals) sections (b1c0aaf)
+- implement full end-to-end types (86c76bb)
+
+### Bug fixes
+
+- address review feedback on site content globals (46791c2)
+
 ## 0.3.0 (2026-10-11)
 
 No user-facing changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@areca-cms/skills",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Agent skills for Areca CMS: the site SDK and the MCP server. Installs into Claude Code, Codex, Cursor, Copilot, OpenCode, Gemini CLI and 20+ other agents.",
   "keywords": [
     "areca",

package/skills/areca-mcp/SKILL.md

@@ -3,12 +3,12 @@ name: areca-mcp
 description: Connects an AI client to an Areca CMS site through its MCP server and uses its tools to write, edit, review and publish content. Covers the per-site connector URL, OAuth sign-in or personal keys, roles and go-live permission, the draft/ready/live workflow, field and Markdown formats, SEO, images, and every tool. Use when the user wants to connect Areca to an AI app or coding agent, or to create, update, approve, schedule or publish Areca CMS entries, upload images, or check what is live.
 license: MIT
 metadata:
-  version: "0.3.0"
+  version: "0.4.0"
 ---
 
 # Areca MCP
 
-Every Areca site has its own remote MCP server. Through it an AI can read and write that site's content: entries, the media Library, releases and, for agency admins, content types. It edits CMS content and is separate from the `@areca-cms/site-sdk` website code (see the `areca-sdk` skill).
+Every Areca site has its own remote MCP server. Through it an AI can read and write that site's content: entries, site content (single sections such as company info), the media Library, releases and, for agency admins, content types and site content structure. It edits CMS content and is separate from the `@areca-cms/site-sdk` website code (see the `areca-sdk` skill).
 
 ## Connect
 
@@ -20,8 +20,8 @@ Every Areca site has its own remote MCP server. Through it an AI can read and wr
 
 ## First calls (always)
 
-1. `get_site_info`: returns your role, what you **cannot** do, the collections and the site's publishing mode.
-2. `get_collection_schema({ collection })`: returns exact field formats, an example payload and SEO guidance. Call it before every first write to a collection.
+1. `get_site_info`: returns your role, what you **cannot** do, the collections, the site content sections (`globals`) and the site's publishing mode.
+2. `get_collection_schema({ collection })`: returns exact field formats, an example payload and SEO guidance. Call it before every first write to a collection. For a site content section, `get_global({ global })` gives the same information.
 
 Tools your role can't use are not listed at all. If the user asks for one of those actions, explain who can do it and don't look for workarounds.
 
@@ -37,7 +37,7 @@ schedule_entry            -> scheduled goes live at a set time (also publishes o
 - `status`: `draft` | `ready` | `scheduled` | `archived`. To answer "what is live" use the flags: `live` (on the production site now), `pendingRelease` (approved changes waiting for the next go live) and `editedSinceReady`.
 - Drafts are safe. Nothing changes the live site until an entry is marked ready **and** a go live happens.
 - Only call `mark_ready`, `go_live`, `schedule_entry`, `rollback`, `delete_*` or `archive_entry` when the user explicitly asks.
-- Writes return a `version`. Pass it as `expectedVersion` on the next `update_entry`. On a version conflict, call `get_entry`, reapply the change and retry.
+- Writes return a `version`. Pass it as `expectedVersion` on the next `update_entry` or `update_global`. On a version conflict, call `get_entry` (or `get_global`), reapply the change and retry.
 - Show the user the `previewUrl` that create and update return (it's signed and valid for about 1 hour). If the site has no production URL, preview isn't available.
 
 ## Roles
@@ -47,7 +47,7 @@ schedule_entry            -> scheduled goes live at a set time (also publishes o
 | editor | read everything, create and edit drafts, upload images, edit alt text, preview |
 | owner | everything an editor can, plus `mark_ready`, `unpublish_entry`, `archive_entry`, `cancel_schedule`, `delete_entry`, `restore_revision`, `delete_asset` |
 | + go-live permission | `go_live`, `schedule_entry`, `rollback`, `cancel_build`. Granted per connection or key with "Allow going live" (owners and agency admins only). |
-| agency admin | everything above, plus `upsert_collection` and `delete_collection` (needs 2FA) |
+| agency admin | everything above, plus `upsert_collection`, `delete_collection`, `upsert_global` and `delete_global` (needs 2FA) |
 
 ## Writing content
 
@@ -56,7 +56,8 @@ schedule_entry            -> scheduled goes live at a set time (also publishes o
 - **Field values:** `image` and `reference` take ids, `date` is `YYYY-MM-DD`, `datetime` is ISO 8601 with an offset, `select` must match an option exactly, and `slug` is lowercase with dashes and unique. Date fields are content only and never schedule an entry.
 - **Clearing:** use `""` for a field or SEO text, `[]` for SEO lists and `false` for `noindex`/`nofollow`. Avoid `null` (`seo` rejects it). A key you leave out keeps its value.
 - **SEO on every new entry:** `seo.title` (50-60 chars), `seo.description` (140-160), `focusKeyphrase`, `summary` (2-3 sentences) and 3-5 `keyTakeaways`. Add `faq` only when the body really answers those questions.
-- **Schema:** if the site project has `areca.config.ts`, change the schema there and push it with the SDK rather than calling `upsert_collection`. `upsert_collection` replaces the whole field list.
+- **Site content (globals):** single sections such as company info or the home page. Read one with `get_global({ global })` and change it with `update_global({ global, fields?, seo?, expectedVersion? })`. It is not a collection, so `create_entry` and `list_entries` do not apply. Its `id` (from `get_global`) works with `mark_ready`, `schedule_entry`, `cancel_schedule`, `list_revisions`, `restore_revision` and `get_preview_url`. Use `discard_global_draft` to go back to the ready values. `seo` is only accepted when the section has SEO on.
+- **Schema:** if the site project has `areca.config.ts`, change the schema there and push it with the SDK rather than calling `upsert_collection` or `upsert_global`. Both replace the whole field list.
 
 Full formats, the SEO object, limits and errors are in [references/content.md](references/content.md). Every tool with its inputs is in [references/tools.md](references/tools.md).
 

package/skills/areca-mcp/references/content.md

@@ -19,6 +19,10 @@ Unknown field keys are refused, and the error lists the valid ones. Entry data i
 
 **Clearing on update:** use `""` for fields and SEO text, `false` for `noindex`/`nofollow`, `[]` for `keyTakeaways`/`faq`/`about`, and an empty `name` for `author`. Don't use `null`: fields accept it, but `seo` rejects it. A key you leave out keeps its value.
 
+## Site content (globals)
+
+A section has the same field types as a collection, except `slug`. Its fields can set `group`, a heading shown above the field in the CMS editor (not in the data). Collection fields cannot set `group`. A section stores one set of values, so there is no create and no list: read it with `get_global` and change it with `update_global`. `seo` is only accepted on a section that has SEO turned on; `get_global` shows whether it does. `get_global` returns `previewAvailable: true` only when the section has a `previewPath` and the site has a production URL.
+
 ## Rich text Markdown
 
 - Use `##` for sections and `###` or `####` for subsections. Other heading levels are clamped.
@@ -63,7 +67,10 @@ Unknown SEO keys are refused. There is no SEO-generation tool, so you write thes
 | `Could not import the file:` | Ask the user for a direct, public file link |
 | `Only site owners…` / `Going live…` / `Only agency admins…` | Tell the user who can do it, e.g. an owner presses Go live in the CMS |
 | `No entry with id…` (or asset/job/publication) | Use the list tools to find valid ids |
-| `No collection "…" on this site` | Use one of the listed keys (see `get_site_info`) |
+| `No collection "…" on this site` | Use one of the listed keys (see `get_site_info`). Site content keys are not collections: use `get_global`. |
+| `No site content "…" on this site` | Use one of the `globals` keys from `get_site_info`. Disabled sections are not listed to editors and owners. |
+| `… has no SEO` | The section has SEO off, so drop `seo`. Ask an agency admin to turn SEO on if it is needed. |
+| `… has no preview page` | Preview needs a `previewPath` on the section. An agency admin sets it. |
 | `Something went wrong on the Areca server (ref …)` | Nothing is confirmed saved. Retry once, then report the ref. |
 
 HTTP: `401` = token or key invalid, expired, revoked or for another site, so reconnect. `403 mfa_required` = the agency admin must enable 2FA. `429` = wait `Retry-After` seconds (120/min per credential, plus 600/min per client IP when the CMS trusts its proxy).

package/skills/areca-mcp/references/tools.md

@@ -6,7 +6,7 @@
 
 | Tool | Access | Inputs | Returns |
 | --- | --- | --- | --- |
-| `get_site_info` | all | none | `site` (name, slug, productionUrl, publishingMode), `you` (role, capabilities), `cannotDo[]`, `collections[]`, `guide`. **Call first.** |
+| `get_site_info` | all | none | `site` (name, slug, productionUrl, publishingMode), `you` (role, capabilities), `cannotDo[]`, `collections[]`, `globals[]` (site content: key, label, enabled, fieldCount, seo, previewPath), `guide`. **Call first.** |
 | `get_collection_schema` | all | `collection*` | Per-field key, type, required, format, options; example `fields` and `seo` payloads; SEO guide |
 
 ## Entries
@@ -20,6 +20,16 @@
 | `list_revisions` | all | `id*` | Revision id, note, createdAt, createdBy |
 | `get_preview_url` | all | `id*` | `{ url }`, signed, about 1 hour. Fails without a site production URL. |
 
+## Site content (globals)
+
+Single sections such as company info or the home page. Editors and owners see enabled sections only; agency admins see all of them. The `id` returned here is the entry id for the workflow tools below.
+
+| Tool | Access | Inputs | Returns |
+| --- | --- | --- | --- |
+| `get_global` | all | `global*` (key from `get_site_info`) | `id`, `key`, `label`, `status`, `live`, `pendingRelease`, `version`, `editedSinceReady`, `previewAvailable`, `values` (rich text as Markdown, images as `{assetId,url,alt}`, references as `{entryId}`), `seo` (only with SEO on), `fields` (format of each field), `example` |
+| `update_global` | all | `global*`, `fields?`, `seo?` (at least one; refused without SEO on the section), `expectedVersion?` | Updated draft + `previewUrl`. Keys you leave out keep their values. |
+| `discard_global_draft` | all | `global*` | Draft reset to the ready values, kept in history. Refused when the section was never ready. |
+
 ## Workflow
 
 | Tool | Access | Inputs | Effect |
@@ -32,6 +42,8 @@
 | `restore_revision` | owner | `id*`, `revisionId*`, `expectedVersion?` | Copies a revision into the draft and returns `skippedFields`. Doesn't mark it ready. |
 | `schedule_entry` | go-live | `id*`, `publishAt*` (future ISO 8601 with offset), `timezone*` (IANA, e.g. `Europe/Amsterdam`) | Goes live at that time, together with the site's other ready changes |
 
+`mark_ready`, `schedule_entry`, `cancel_schedule`, `list_revisions`, `restore_revision` and `get_preview_url` also take a site content section's `id`. `unpublish_entry`, `archive_entry` and `delete_entry` refuse it: change the section instead.
+
 ## Library (assets)
 
 | Tool | Access | Inputs | Returns |
@@ -59,6 +71,8 @@
 | --- | --- | --- | --- |
 | `upsert_collection` | agency | `key*`, `label*`, `routePattern*`, `fields*` (up to 100: `key*`, `label*`, `type*`, `required?`, `options?`, `collection?`, `description?`, `after?`), `enabled?` | Creates the collection or **replaces** its field list. Prefer `areca.config.ts` + `areca manifest push` when the site syncs its schema from code. |
 | `delete_collection` | agency | `key*` | Deletes the collection and its entries. Destructive. |
+| `upsert_global` | agency | `key*`, `label*`, `fields*` (as `upsert_collection`, plus `group?` heading; no `slug` type), `seo?`, `previewPath?` (e.g. `/about`, `""` removes it), `enabled?` | Creates the site content section or **replaces** its fields, SEO setting, preview path and enabled flag. Keeps its content. |
+| `delete_global` | agency | `key*` | Deletes the section. Its content is kept in the deleted-content archive. Destructive. |
 
 ## Prompt
 

package/skills/areca-sdk/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: areca-sdk
-description: Connects a website project to Areca CMS with the @areca-cms/site-sdk package. Covers setup, tokens and env vars, areca.config.ts collections and field types, the areca CLI (init, manifest push/pull, pull, run), reading pulled content, rich text, SEO head tags, draft preview routes and Go-live builds. Use when a project imports @areca-cms/site-sdk, has an areca.config.ts, mentions ARECA_* env vars, or the user wants to add, render or deploy Areca CMS content.
+description: Connects a website project to Areca CMS with the @areca-cms/site-sdk package. Covers setup, tokens and env vars, areca.config.ts collections, site content globals and field types, the areca CLI (init, manifest push/pull, pull, run), typed content from the generated areca.gen.ts (import { content }), rich text, SEO head tags, draft preview routes and Go-live builds. Use when a project imports @areca-cms/site-sdk, has an areca.config.ts or areca.gen.ts, mentions ARECA_* env vars, or the user wants to add, render or deploy Areca CMS content.
 license: MIT
 metadata:
-  version: "0.3.0"
+  version: "0.4.0"
 ---
 
 # Areca site SDK
@@ -14,13 +14,13 @@ Requirements: Node >= 22.6 (24 LTS recommended), ESM only. It works with any fra
 
 ## Mental model
 
-1. `areca.config.ts` declares **collections** (content types) and their **fields**.
+1. `areca.config.ts` declares **collections** (content types), **globals** (single site content sections) and their **fields**.
 2. `areca manifest push` sends that schema to the CMS (needs the schema token).
-3. Editors create entries in the CMS and **Go live**, which creates an immutable **publication** (snapshot).
-4. `areca pull` downloads the publication into `src/generated/content/`.
-5. Server code reads it with `readContent()` from `@areca-cms/site-sdk/pull`.
+3. Editors create entries in the CMS and **Go live**, which creates an immutable **publication** (snapshot) with the schema embedded.
+4. `areca pull` downloads the publication into `src/generated/content/` and writes `src/generated/content/areca.gen.ts`.
+5. Server code reads it through the typed `content` object from `areca.gen.ts`: `import { content } from "../generated/content/areca.gen"`.
 
-There are no singletons, blocks, locales, typegen, webhooks or runtime query API. A "page" is an entry in a collection. Filter, sort and paginate the returned arrays in your own code.
+Typing is generated, not hand-written: after a pull, every collection, field, value, select option, reference and route is typed and autocompletes. Commit `areca.gen.ts`; never commit the pulled JSON. Single sections of values, such as company details or the home page, are site content (`globals`). There are no blocks, locales, webhooks or HTTP query API. A "page" is an entry in a collection, or a site content section. Queries run in memory on the pulled files, with `where`, `orderBy`, `limit`, `offset` and `with`.
 
 ## Setup
 
@@ -31,7 +31,7 @@ pnpm exec areca init                  # interactive; writes config, env files, s
 pnpm exec areca init --cms-url https://cms.example.com --token "$ARECA_SITE_TOKEN" --site-key acme-site --yes
 ```
 
-`init` writes `areca.config.ts` (including an `assets` block), `.env.example`, `.env.local` (`ARECA_CMS_URL`, `ARECA_SITE_TOKEN`), `.gitignore` entries (content and media folders), `src/generated/content/manifest.json`, and the package scripts `sync-manifest` and `content:pull`. It also wraps `dev` in `areca run --`. Use `--force` to overwrite an existing config. `--out` and `--config` change the paths. Media flags: `--assets-dir <dir>` (default `public/areca`), `--assets-public-path <path>` (only for folders outside `public/`), `--no-assets`. On an existing config, init inserts an `assets` block if there is none.
+`init` writes `areca.config.ts` (including an `assets` block), `.env.example`, `.env.local` (`ARECA_CMS_URL`, `ARECA_SITE_TOKEN`), `.gitignore` entries (the pulled content folder as `<out>/*` with `!<out>/areca.gen.ts` so the types stay tracked, and the media folder), `src/generated/content/manifest.json`, and the package scripts `sync-manifest` and `content:pull`. It also wraps `dev` in `areca run --`. Use `--force` to overwrite an existing config. `--out` and `--config` change the paths. Media flags: `--assets-dir <dir>` (default `public/areca`), `--assets-public-path <path>` (only for folders outside `public/`), `--no-assets`. On an existing config, init inserts an `assets` block if there is none.
 
 | Env var | Needed for | Where the user gets it |
 | --- | --- | --- |
@@ -40,10 +40,11 @@ pnpm exec areca init --cms-url https://cms.example.com --token "$ARECA_SITE_TOKE
 | `ARECA_SCHEMA_TOKEN` | `manifest push` only | Settings > Developer > Rotate schema token. Keep it in the authoring env only, never in builds. |
 | `ARECA_SITE_KEY` | `manifest pull` without a config | The site key shown in Settings |
 | `ARECA_SNAPSHOT_ID` | pinned pulls during Go-live builds | Set by the CMS deploy; empty or `0` means current live |
+| `ARECA_CONTENT_DIR` | the generated `content` object at run time | Optional. The content folder, when it is not the folder that was pulled into |
 
 The CLI loads `.env.local` and then `.env`, and existing process env wins. Library imports do **not** load env files.
 
-**Security:** both tokens are server secrets. Never put them in browser code or behind a `VITE_`, `NEXT_PUBLIC_` or `PUBLIC_` prefix, and never commit them. Only import `readContent` and the client in server or build code.
+**Security:** both tokens are server secrets. Never put them in browser code or behind a `VITE_`, `NEXT_PUBLIC_` or `PUBLIC_` prefix, and never commit them. Only import the content object, `readContent` and the client in server or build code.
 
 ## Declare content
 
@@ -68,15 +69,42 @@ export default defineSiteContent({
         { key: "endsAt", label: "Ends", type: "datetime", after: "startsAt" },
       ],
     },
+    authors: {
+      route: "/authors/$slug",
+      fields: [{ key: "name", label: "Name", type: "text", required: true }],
+    },
   },
 });
 ```
 
-- Field types: `text`, `textarea`, `richtext`, `image`, `date`, `datetime`, `select` (`options`), `reference` (`collection`), `slug`, `boolean`, `number`, `url`. Optional per field: `required`, `description`, `after` (date or datetime key this must be on or after).
+- Field types: `text`, `textarea`, `richtext`, `image`, `date`, `datetime`, `select` (`options`), `reference` (`collection`, required), `slug`, `boolean`, `number`, `url`. Optional per field: `required`, `description`, `after` (only on `date` or `datetime`, naming another date key in the same collection).
+- `defineSiteContent` checks these at compile time: `options` only on `select`, `collection` required on `reference` and must be a collection key of the same config, `after` must name a date key, and `route` must contain `$slug`.
 - Keys match `^[A-Za-z][A-Za-z0-9_-]{0,63}$`. Collection keys must be unique case-insensitively. Reserved: `manifest`, `constructor`, `prototype`, `__proto__`, and Windows device names (`con`, `prn`, `aux`, `nul`, `com1`, `lpt1`, ...).
+- Collection keys cannot be `resolve`, `href`, `preview`, `globals` or `previewGlobals` (any case, and `preview-globals` too), because the content object uses those names. Field keys may use them.
+- In code, keys are camelCase: `blog-posts` is `content.blogPosts`, `cover_image` is `entry.data.coverImage`. The pull fails when two keys collide after this conversion (`blog-posts` and `blog_posts`).
 - A push is the **full** manifest. Collections left out are disabled (their entries are kept). The CMS adds a required `slug` field if one is missing. Limits: 100 collections, 100 fields each, 256 KiB.
 - `areca manifest pull --config areca.config.ts [--yes]` regenerates the config from the CMS. It replaces the whole file and keeps `siteKey` and `assets`. Without a TTY it needs `--yes` if the config already has collections.
 
+### Site content (globals)
+
+```ts
+globals: {
+  companyInfo: {
+    label: "Company info",
+    fields: [
+      { key: "name", label: "Name", type: "text", required: true },
+      { key: "email", label: "Email", type: "text", group: "Contact" },
+    ],
+  },
+  homePage: { label: "Home page", seo: true, previewPath: "/", fields: [/* ... */] },
+},
+```
+
+- A global is one set of fields with no slug and no route. Its key follows the same identifier rules as a collection key and may not be `globals`, `previewGlobals`, `resolve`, `href` or `preview`.
+- `seo: true` adds a `$seo` value. `previewPath` is the page that shows the draft. Both are optional.
+- `group` is an editor heading only. The SDK value stays flat, and collection fields may not set `group`.
+- Sections may reference collections, not the other way round. A push is a full sync: a section left out is disabled and its content is kept.
+
 ### Media (`assets`)
 
 ```ts
@@ -92,31 +120,42 @@ areca init [--cms-url <url>] [--token <t>] [--site-key <key>] [--out <dir>] [--c
            [--assets-dir <dir>] [--assets-public-path <path>] [--no-assets] [--yes] [--force]
 areca manifest push [config]             # needs ARECA_SCHEMA_TOKEN (+ URL and site token)
 areca manifest pull [--config <path>] [--yes]
-areca pull [--out <dir>] [--publication <id>] [--config <path>]   # default out: src/generated/content; media: public/areca
+areca pull [--out <dir>] [--publication <id>] [--config <path>] [--types <path>]   # default out: src/generated/content; types: <out>/areca.gen.ts; media: public/areca
 areca run -- <command>                   # run a command with .env.local/.env loaded
 ```
 
-`areca sync-manifest` is a deprecated alias for `manifest push`. Run the CLI as `pnpm exec areca`, `npx areca` or `yarn areca`. A pull fails until something has gone live in the CMS. To pull before every build, add `"prebuild": "areca pull"`.
+`areca sync-manifest` is a deprecated alias for `manifest push`. Run the CLI as `pnpm exec areca`, `npx areca` or `yarn areca`. A pull fails until something has gone live in the CMS. To pull before every build, add `"prebuild": "areca pull"`. A pull prints a `Types:` line with the file it wrote, and it fails before writing anything when an entry does not match its schema or two keys collide in camelCase.
 
-## Read content (server or build only)
+## Read typed content (server or build only)
 
 ```ts
-import { readContent, readContentManifest } from "@areca-cms/site-sdk/pull";
-import type { ImageValue, ReferenceValue, RichTextValue, SnapshotEntry } from "@areca-cms/site-sdk";
+// src/lib/content.ts: server only
+import { content } from "../generated/content/areca.gen";
 
-type Article = SnapshotEntry & {
-  data: { title: string; body: RichTextValue; cover: ImageValue | null; author: ReferenceValue | null };
-};
+export function getNewsArticles() {
+  return content.articles.all({ where: { category: "news" }, orderBy: { startsAt: "desc" }, limit: 10 });
+}
 
-const dir = "src/generated/content";
-const manifest = readContentManifest(dir); // capture once for consistent multi-collection reads
-const articles = readContent<Article>(dir, "articles", manifest);
-const post = articles.find((a) => a.slug === slug);
+export function findArticle(slug: string) {
+  return content.articles.get(slug); // Entry | undefined
+}
+
+// in a server function:
+const author = content.resolve(article.data.author); // Entry<"authors"> | null
 ```
 
-- Entry: `{ id, slug, publishedAt, data, seo? }`. The field values live in `data`. You write the types yourself because there is no codegen.
-- `ImageValue` = `{ url, width|null, height|null, alt, mimeType }`, where `url` is the local path after `areca pull` (e.g. `/areca/hero-3f2a91c0.jpg`), or an absolute CMS URL with `assets.download: false`. Serve the media folder with the site (it is part of `public/` by default). `ReferenceValue` = `{ collection, slug, id }`. Optional and image fields can be `null` or missing, so check them.
-- `readContent` reads files at runtime, so ship `src/generated/content/` (including `.publications/`) with the server build or container. For TanStack Start, call it inside a `createServerFn` handler, never in route or component code.
+- Each collection has `all(options?)`, `first(options?)`, `get(slug)`, `byId(id)` and `href(entryOrSlug)`. `get` and `byId` return `undefined` for an unknown value.
+- `where`: a direct value means equality. Operators depend on the field type: text fields take `eq`, `ne`, `in`, `notIn`, `contains`; `select` takes `eq`, `ne`, `in`, `notIn`; `date`, `datetime` and `number` take `eq`, `ne`, `gt`, `gte`, `lt`, `lte`; `boolean` takes `eq`, `ne`; optional fields of any type take `isNull`. Several keys are AND-ed. Null, `''` and a missing key count as empty.
+- `orderBy` takes an object such as `{ startsAt: "desc" }`, or an array for tie-breakers. Empty values sort last. Images, rich text and references are not sortable.
+- `with: { author: true }` expands reference fields one level. `content.resolve(ref)` returns the target entry or `null`. `content.href(ref)` and `content.blogPosts.href(entry)` build routes, typed as template literals.
+- `content.preview(token)` fetches a draft for a preview route. Check `result.complete` first: when true, `entry` is an `Entry`; when false, `entry` is a `DraftEntry` (every field optional) and `issues` lists the problems as `<field>: <problem>`.
+- Entry: `{ id, slug, publishedAt, collection, data, seo? }`. Field values live in `data`, keyed by camelCase field name. No hand-written types are needed. Types are per collection, with `Entry<"articles">` for one collection.
+- Optional fields can be `null`, missing or `''`, and the types show each case. Required fields are never empty.
+- `ImageValue` = `{ url, width|null, height|null, alt, mimeType }`, where `url` is the local path after `areca pull` (e.g. `/areca/hero-3f2a91c0.jpg`), or an absolute CMS URL with `assets.download: false`. Serve the media folder with the site (it is part of `public/` by default). `ReferenceValue<C>` = `{ collection, slug, id }`.
+- The content object reads files at runtime, so ship `src/generated/content/` (including `.publications/`) with the server build or container. For TanStack Start, call it inside a `createServerFn` handler, never in route or component code.
+- Low-level: `readContent(dir, "blogPosts")` from `@areca-cms/site-sdk/pull` returns the typed entries of one collection and takes no type parameter. Use `readContentManifest(dir)` once when reading several collections from one publication.
+- `content.globals.<camelKey>` returns a section as a flat object of its field values, plus `$seo` when SEO is on. Types: `CompanyInfoGlobal` (exported from `areca.gen.ts`), and `Global<K>`, `Globals`, `GlobalKey`, `GlobalData` and `GlobalSchema` from the package root. Without a registered schema, the value is typed as a loose record.
+- `content.previewGlobals(token)` returns `{ globals, previewing, complete, issues }`. `previewing` is the camel key of the section the token targets (or `null`). A valid draft is in `globals`; an incomplete one keeps the published section, with `complete: false` and `issues` listing the problems. It also accepts a `PreviewResult` or `null`.
 
 ## Rich text
 
@@ -136,11 +175,13 @@ import { richTextDocument } from "@areca-cms/site-sdk";
 - Astro or plain SSR: `seoHeadHtml(entry.seo, options)` from `@areca-cms/site-sdk/seo` returns an escaped HTML string. `seoJsonLd(seo)` returns safe JSON-LD strings.
 - `seo` is optional. When `seo.summary`, `keyTakeaways` or `faq` exist, render them visibly on the page so the content matches the JSON-LD.
 
+- Site content sections with `seo: true` have `$seo` on the section value, in the same shape as an entry's `seo`: `seoHead(content.globals.homePage.$seo)`.
+
 ## Preview, Go live and the client
 
 Read [references/production.md](references/production.md) when the user needs any of these:
 
-- A draft preview route: `getPreviewEntry` and `previewHeaders` at `/__preview/<collection>/<slug>?token=`.
+- A draft preview route: `getPreviewEntry` and `previewHeaders` at `/__preview/<collection>/<slug>?token=`, or `content.preview(token)` for a typed result. A site content section previews on its `previewPath` with `?arecaPreview=<token>`, and `content.previewGlobals(token)` returns the page's values, with the draft in place when it is complete and `previewing` is the page's section.
 - The production health route that Go live waits for.
 - Docker or CI builds with `ARECA_SNAPSHOT_ID`.
 - The CMS settings needed: production URL, deployment target, publishing mode.
@@ -150,8 +191,9 @@ Read [references/api.md](references/api.md) for every export, type and signature
 
 ## Rules
 
-- Change the schema in `areca.config.ts` and then `manifest push`. Don't hand-edit generated content.
-- Never import `@areca-cms/site-sdk/pull` or a client with tokens into browser bundles.
+- Change the schema in `areca.config.ts` and then `manifest push`, then go live and pull. Don't hand-edit generated content or `areca.gen.ts`; a pull rewrites both.
+- Commit `areca.gen.ts`. Keep the pulled JSON out of Git.
+- Never import the content object, `@areca-cms/site-sdk/pull` or a client with tokens into browser bundles.
 - Exclude `/__preview/*` from prerendering and caching.
 - The SDK doesn't create CMS sites or tokens. An agency admin creates the site in the CMS. Ask the user for the URL, site key and tokens instead of guessing them.
 - To edit content (not code) through an AI, use the Areca MCP server (see the `areca-mcp` skill).

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

@@ -6,10 +6,11 @@ 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 }` |
+| `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`), 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`; 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`). |
+| `getPreviewEntry` | `({ token: string; client?: ArecaClient }) => Promise<PreviewResult>` | `PreviewResult` = `PreviewEntryResult` `{ kind: 'entry', collection, slug, entry }` or `PreviewGlobalResult` `{ kind: 'global', global, entry }`. Needs `ARECA_CMS_URL` and `ARECA_SITE_TOKEN` (or pass `client`). |
+| `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 |
 | `seoHead` | `(seo: SeoMeta \| null \| undefined, options?: SeoHeadOptions) => { title, meta, links, scripts }` | TanStack Router `head()` shape |
 | `seoHeadHtml` | `(seo, options?) => string` | Escaped `<head>` HTML |
@@ -29,17 +30,73 @@ ESM only. Import paths and their exports:
 | `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 |
 
-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`.
+Types from the main entry: `ArecaClient`, `ArecaClientOptions`, `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}` |
+| `Href<C, S>` | the route type of collection `C`, such as `` `/blog/${string}` `` |
+| `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)
+
+| 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
 
@@ -64,5 +121,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/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)
@@ -85,5 +88,9 @@ await pullContent({ outDir: "src/generated/content", client });
 | `400` / `413` on push | Invalid schema, or the manifest is over 256 KiB |
 | `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` |