@areca-cms/skills 0.3.0 → 0.5.0

package/skills/areca-quickstart/references/interview.md

@@ -0,0 +1,169 @@
+# Interview
+
+Ask four batches, one at a time. Wait for the answer before you ask the next batch.
+
+Rules for every batch:
+
+- Number the questions. The user answers by number, for example "1 yes, 2 nl, 3 defaults".
+- Show the default in brackets for each question.
+- Say that the user can reply `defaults` to accept every default in the batch.
+- Skip a question when you already detected the answer. Show the detected value and ask "correct?" instead.
+- Keep each question to one line where you can.
+
+## Batch A: Project
+
+Send this when step 0 is done. Fill in the detected values.
+
+```text
+A. Project
+
+1. CMS URL? [detected: https://cms.example.com, or none. Local dev: http://localhost:3000]
+2. Site key (the CMS slug, lowercase, e.g. acme-site)? [detected: from areca.config.ts, or ask]
+3. Does this site exist in the CMS yet? [no]
+   If no, I will walk you through creating it. You will need the production URL field: use http://localhost:<dev port> for now.
+4. Framework: <detected>. Correct? [yes]
+5. Package manager: <detected>. Correct? [yes]
+6. Dev port: <detected, e.g. 3001>. [keep]
+7. Content folder for pulled content? [src/generated/content]
+8. Types file (areca.gen.ts)? [src/generated/content/areca.gen.ts]
+9. Commit the generated types file? [yes; the pulled JSON stays out of Git]
+10. Download images and files into the repo on pull? [yes]
+    10a. Folder for them? [public/areca]
+    10b. URL path the site serves that folder from? [only asked when the folder is not under public/]
+11. Schema source: connect the CMS over MCP (the schema is created in the CMS, then saved to areca.config.ts) or write areca.config.ts in code? [MCP, if you are an agency admin; otherwise code]
+
+Reply "defaults" to accept all of A.
+```
+
+Notes for the agent:
+
+- Q3: if the site does not exist, read the "Create the site" section of `connect.md` before you go on.
+- Q11: if MCP is not connected, ask only this: "Do you want to connect the CMS over MCP now?" If yes, go to step 1. If no, code.
+- If the CMS URL is `localhost`, say that a remote CMS needs its own site token.
+
+## Batch B: Content model
+
+Ask what the site needs. Then go through each item with its recipe in `recipes.md`.
+
+```text
+B. Content model
+
+1. What does the website need? Name the content in your own words.
+   Examples: blog posts, team members, vacancies, services, case studies, events, FAQ.
+2. Which company pages does the site need?
+   [company info, home page, about page, footer]
+3. Do you want any of these extras? [all yes]
+   a. Categories for blog posts (a collection)
+   b. Authors for blog posts (a collection, used as a reference)
+   c. Departments for vacancies (a collection, used as a reference)
+   d. Navigation links (a collection, see the note in recipes.md)
+   e. SEO on the home and about pages (on by default)
+4. Routes: each collection gets a route. These are the defaults from the recipe, for example /blog/$slug and /vacancies/$slug. Change them?
+5. Anything that does not fit the recipes? Describe the fields in your own words. I will map them to field types.
+6. Company details for the company info section: name, email, phone and address. [name: the client's name, the rest empty]
+   Give only what you know. I will leave the others empty. I will not guess a founding year, a phone number or an address.
+
+Reply "defaults" to accept the recipe fields and all the extras in B (the company details stay empty except the name).
+```
+
+For each item the user names:
+
+1. Find its recipe in `recipes.md`. If no recipe fits, build one from the field types in `areca-sdk`.
+2. Show the default fields in a short list. Ask: "Keep these, add, or remove?" Ask only one question per item.
+3. Note the translatable choice for each text field. Use the recipe defaults.
+
+Do not invent extra fields. Add what the user asked for and the recipe defaults.
+- A declined extra removes the fields that point to it. For example, no authors means no `author` field on posts. Show each removal in the plan.
+- Never invent a fact. A value the user did not give stays empty when the field is optional.
+
+## Batch C: Languages
+
+Skip this batch when the user said "single language" in batch B or when the project has no i18n. The default is one language.
+
+```text
+C. Languages
+
+1. One language or several? [one]
+2. If several: the main language (the fallback) and all languages in display order?
+   [main: <detected or en>, all: <main> only]
+3. Route for each collection in each extra language. Default: the same route in every language. The site adds the language prefix itself (for example /nl/blog/...). Ask per collection only when the user wants different words, for example /journal in English and /journaal in Dutch.
+4. Which languages must be complete before an item can be marked ready? [all extra languages, for every collection and section]
+5. Which fields are the same in every language (names, prices, contact details, URLs, emails)? [the recipe defaults]
+6. i18n approach:
+   - If the project already uses a library, use it. Only Paraglide is wired by the SDK. For another library, the content is read with an explicit locale.
+   - If the project has none: Paraglide is recommended. It needs a new package, and the recipe is in `frameworks.md` (TanStack Start is verified). Install it only if you say yes.
+     The lighter alternative is the explicit locale: no new package, and the locale is passed to each read.
+   [Paraglide]
+
+Reply "defaults" to accept all of C (one language, so C is skipped).
+```
+
+Notes for the agent:
+
+- Languages cannot be turned off once set in the CMS. Say so before Q2 is confirmed.
+- Do not install any i18n library without a yes to Q6.
+
+## Batch D: Build and preview
+
+```text
+D. Build and preview
+
+1. Pages for each collection:
+   a. Connect to existing pages. I change the data source only.
+   b. Build simple pages (list and detail) using the site's own components. No styling beyond what the site uses.
+   c. Skip for now.
+   [b when the project has no pages for the collection, otherwise a]
+2. Connect the home page and the about page to their sections? [yes, when the plan has them]
+3. Draft preview route (so editors can see drafts in the site)? [yes]
+   It needs the production URL in the CMS. A localhost URL is fine for development.
+4. Run a content pull before every build and before the dev server? [yes, prebuild only; predev only after the first release]
+5. Will you deploy with go-live builds (Dokploy) later? [no]
+   If yes, I add the health route now. Read the areca-sdk skill, references/production.md.
+6. First release mode: demo or production? [demo]
+   Demo does not deploy and never shows to visitors. Production needs a deployment target and a health check URL. Use demo for the first release.
+
+Reply "defaults" to accept all of D.
+```
+
+## Plan format
+
+After batch D, show the plan. Keep it short. Then ask: "Reply yes to confirm, or tell me what to change."
+
+```text
+Plan
+
+Project
+- Framework: TanStack Start, pnpm, dev port 3001
+- Site key: acme-site (exists in the CMS: yes)
+- CMS: https://cms.example.com (schema over MCP)
+
+Content folder
+- src/generated/content (types committed, media in public/areca, downloaded on pull)
+
+Collections
+- posts: /blog/$slug, 9 fields, author -> authors
+- authors: /team/$slug, 5 fields
+- ...
+
+Sections
+- companyInfo (no SEO), homePage (SEO, preview /), aboutPage (SEO, preview /about)
+
+Languages
+- none, or: en (main), nl. Routes: /blog/$slug and /nl/blog/$slug. Required: nl.
+
+i18n
+- none, or Paraglide (needs your yes to install)
+
+Pages
+- posts: list and detail, simple pages
+- home and about: connected to their sections
+
+Preview route: yes. Prebuild pull: yes.
+First release: demo mode.
+```
+
+Keep the plan to the facts. Mark every item the user has not confirmed.
+
+## Recording answers
+
+Keep the answers in your working notes for the rest of the run. Re-read them before step 3 and step 4. If the user changes an answer later, update the plan and show the changed lines only.

package/skills/areca-quickstart/references/recipes.md

@@ -0,0 +1,243 @@
+# Recipes
+
+Starting points for collections and sections. Use them in batch B and in the approval table (step 3). Adapt the fields to the client. Keep the list short.
+
+Field rules that apply to every recipe (see the `areca-sdk` skill for the full list):
+
+- Keys (collections, sections and fields) start with a letter. They use letters, digits, `_` or `-`, and are 64 characters at most.
+- Collection and section keys cannot be `resolve`, `href`, `preview`, `globals`, `previewGlobals`, `in`, `languages` or `matchLocale`, in any case. Field keys may use them. Also avoid `manifest`, `constructor`, `prototype` and the Windows device names (`con`, `aux`, `nul`, `com1` and so on).
+- Every collection needs a `route` with `$slug`. Even a collection with no page (for example testimonials) needs one.
+- Every collection gets a `slug` field. Add it in the config, as the examples do.
+- Text, textarea, richtext and url are translatable by default on a multilingual site. Names, prices, contact details and shop or apply links are usually not. Mark them `translatable: false`.
+- The SDK has no list field. Use one of these instead: a collection with a number field for order, a reference, or several plain fields.
+- `group` works only on sections (globals), not on collection fields.
+- A `date` or `datetime` field is content only. It does not schedule an entry.
+- When the user declines an extra (for example authors or departments), remove every field that points to it (`posts.author`, `vacancies.department`, `posts.category`, `homePage.featuredPost`). Show each removal in the approval table, for example "removed: author (authors declined)".
+- Never invent facts for a field (a founding year, a phone number, an address, a salary). If the interview did not give the value, leave an optional field empty. Use placeholder text only for copy, and say so.
+
+Field lines below use: `key` (type, required, notes). `slug` is always `slug` (type slug, required).
+
+## Collections
+
+### Blog posts
+
+Collection `posts`. Route `/blog/$slug`. Label "Blog posts" (or the client's word, such as "News" or "Journal").
+
+- `slug` (slug, required)
+- `title` (text, required)
+- `excerpt` (textarea), short summary for lists and SEO
+- `body` (richtext, required)
+- `coverImage` (image)
+- `category` (select: `news`, `guides`, `updates`). Use a reference to categories instead if categories need their own page.
+- `tags` (text). Comma-separated, with a description that says so. There is no list type.
+- `author` (reference to `authors`)
+- `publishedAt` (datetime). Content only, does not schedule.
+
+Suggested extras: categories, authors, a home page section that features the latest post.
+
+### Categories
+
+Collection `categories`. Route `/blog/category/$slug`.
+
+- `slug` (slug, required)
+- `name` (text, required)
+- `description` (textarea)
+
+### Authors (team members)
+
+Collection `authors`. Route `/team/$slug`. Label "Team".
+
+- `slug` (slug, required)
+- `name` (text, required, `translatable: false`)
+- `role` (text)
+- `bio` (textarea)
+- `portrait` (image)
+
+Used by posts (author reference) and projects.
+
+### Vacancies (job openings)
+
+Collection `vacancies`. Route `/vacancies/$slug`. Label "Vacancies".
+
+- `slug` (slug, required)
+- `title` (text, required)
+- `summary` (textarea, required). Shown on the list page and in SEO.
+- `description` (richtext, required). Role, tasks, requirements.
+- `department` (reference to `departments`)
+- `location` (text). For example "Amsterdam (hybrid)".
+- `employmentType` (select: `full-time`, `part-time`, `contract`, `internship`, `freelance`). Shared across languages.
+- `hoursPerWeek` (number)
+- `salaryRange` (text, `translatable: false`). For example "3,000 to 3,800 EUR per month". Keep it as text, the SDK has no currency type.
+- `remote` (boolean). Open to remote work.
+- `startDate` (date)
+- `closingDate` (date). When it closes, the page can say "closed".
+- `applyUrl` (url, `translatable: false`). Link to the applicant tracking system.
+- `applyEmail` (text, `translatable: false`)
+
+Suggested extras: departments, and a `/vacancies` list page on the site. Entries already have SEO in the CMS, so there is no SEO flag to set here.
+
+### Departments
+
+Collection `departments`. Route `/departments/$slug`.
+
+- `slug` (slug, required)
+- `name` (text, required)
+- `summary` (textarea)
+- `body` (richtext)
+- `contactEmail` (text, `translatable: false`)
+
+### Services
+
+Collection `services`. Route `/services/$slug`.
+
+- `slug` (slug, required)
+- `title` (text, required)
+- `summary` (textarea)
+- `body` (richtext)
+- `icon` (image)
+- `order` (number). Lower numbers show first. Use `orderBy` in the code.
+
+### Projects and case studies
+
+Collection `projects`. Route `/work/$slug`. Label "Projects" or "Work".
+
+- `slug` (slug, required)
+- `title` (text, required)
+- `client` (text). The client name in the project. Use `translatable: false` if it is a name.
+- `summary` (textarea)
+- `coverImage` (image)
+- `body` (richtext)
+- `completedOn` (date)
+- `services` (reference to `services`)
+
+### Testimonials
+
+Collection `testimonials`. Route `/testimonials/$slug`. Even when the site shows them on one page, the route is still required.
+
+- `slug` (slug, required)
+- `quote` (textarea, required)
+- `name` (text, required, `translatable: false`)
+- `role` (text)
+- `company` (text, `translatable: false`)
+- `photo` (image)
+- `order` (number)
+
+### FAQ
+
+Collection `faqs`. Route `/faq/$slug`.
+
+- `slug` (slug, required)
+- `question` (text, required)
+- `answer` (richtext, required)
+- `order` (number)
+
+### Events
+
+Collection `events`. Route `/events/$slug`.
+
+- `slug` (slug, required)
+- `title` (text, required)
+- `summary` (textarea)
+- `body` (richtext)
+- `coverImage` (image)
+- `startsAt` (datetime, required)
+- `endsAt` (datetime, `after: "startsAt"`)
+- `location` (text)
+- `registrationUrl` (url, `translatable: false`)
+
+### Navigation links (optional)
+
+Collection `navigationLinks`. Route `/navigation/$slug`. The site never renders this as a page. It only reads the links.
+
+- `slug` (slug, required)
+- `label` (text, required)
+- `url` (url, `translatable: false`)
+- `order` (number)
+
+Mention the trade-off to the user. A menu that rarely changes is simpler in code. Use this collection when editors must change the menu themselves.
+
+## Sections (site content)
+
+Sections are single sets of values. They have no slug and no route. Set `seo: true` only on pages that have their own SEO (home, about). Set `previewPath` to the page that shows the section, so editors can preview drafts there.
+
+### Company info
+
+Section `companyInfo`. Label "Company info". No SEO.
+
+Ask the user for the company details in batch B: name, email, phone and address. Use only what they give. Leave the others empty. Do not guess a founding year, a phone number or an address.
+
+- `name` (text, required, `translatable: false`)
+- `tagline` (textarea). The site's default description in the root head.
+- `email` (text, `translatable: false`, `group: "Contact"`)
+- `phone` (text, `translatable: false`, `group: "Contact"`)
+- `address` (textarea, `group: "Contact"`)
+- `mapUrl` (url, `translatable: false`, `group: "Contact"`)
+- `instagramUrl` (url, `translatable: false`, `group: "Social"`)
+- `linkedinUrl` (url, `translatable: false`, `group: "Social"`)
+- `foundedYear` (number)
+
+### Home page
+
+Section `homePage`. Label "Home page". `seo: true`. `previewPath: "/"`.
+
+- `heroEyebrow` (text)
+- `heroTitle` (text, required)
+- `heroIntro` (textarea, required)
+- `heroImage` (image)
+- `ctaLabel` (text)
+- `ctaUrl` (url, `translatable: false`)
+- `featuredPost` (reference to `posts`), when the plan has posts
+
+### About page
+
+Section `aboutPage`. Label "About page". `seo: true`. `previewPath: "/about"`.
+
+- `heading` (text, required)
+- `body` (richtext, required)
+- `image` (image)
+
+### Footer
+
+Section `footer`. Label "Footer". No SEO. Keep it small.
+
+- `footerNote` (textarea). Short line under the links.
+- `copyrightName` (text). Shown after the year.
+- `legalNotice` (richtext). Terms or imprint text.
+
+Use `companyInfo` for the address and contact fields. Do not repeat them.
+
+## SEO defaults
+
+- Every entry has SEO in the CMS. Editors fill it in, and the SDK gives `entry.seo`. Use `seoHead` or `seoHeadHtml` in every entry page.
+- Sections get SEO only with `seo: true`. Use it for home and about. Read the value from `content.globals.<key>.$seo`.
+- The site name and the default description come from `companyInfo`. Use them in the root layout.
+- Do not add SEO fields as collection fields. Use the CMS SEO panel.
+
+## Routes and languages
+
+A collection has one `route` in the main language, for example `/blog/$slug`. A language that uses other words gets its own pattern in `routes`, for example `routes: { nl: '/vacatures/$slug' }`. Read from the SDK source (`packages/site-sdk/src/content.ts`):
+
+- The SDK uses `route` and each `routes[locale]` value exactly as written. It never adds a language prefix. Write `/vacatures/$slug`, not `/nl/vacatures/$slug`. A prefix in `routes` is doubled once the site adds `/nl`.
+- `content.posts.href(slug)` returns the route of the language in use, with `$slug` replaced. Example: `content.posts.href('my-post')` gives `/blog/my-post`. `content.in('nl').vacancies.href('dev')` gives `/vacatures/dev`. A string slug uses the language from `in(locale)` if set, else the locale function (Paraglide's `getLocale` when it is wired), else the main language. `href(entry)` uses the entry's own language.
+- `entry.alternates` maps each complete language tag to its route, again with no prefix: `{ en: '/vacancies/dev', nl: '/vacatures/dev' }`.
+- The site adds the prefix. The main language has none. Every other language is `/<tag>` followed by the route, so the Dutch vacancy is `/nl/vacatures/dev`. With Paraglide, the router rewrite does this (see [frameworks.md](frameworks.md)). Without Paraglide, add the prefix in code.
+
+**The rule:** `href()` and `alternates` never include the language prefix. Add `/<tag>` yourself for every language except the main one.
+
+## Route suggestions
+
+| Collection | Route | Page type |
+| --- | --- | --- |
+| posts | `/blog/$slug` | list at `/blog`, detail |
+| categories | `/blog/category/$slug` | list of posts, filtered |
+| authors | `/team/$slug` | list at `/team`, detail |
+| vacancies | `/vacancies/$slug` | list at `/vacancies`, detail |
+| departments | `/departments/$slug` | detail, linked from vacancies |
+| services | `/services/$slug` | list at `/services`, detail |
+| projects | `/work/$slug` | list at `/work`, detail |
+| testimonials | `/testimonials/$slug` | route kept, shown on home |
+| faqs | `/faq/$slug` | list at `/faq` |
+| events | `/events/$slug` | list at `/events`, detail |
+| navigationLinks | `/navigation/$slug` | none (read only) |
+
+Sections have no route. Their pages are `/` (home), `/about`, and the footer appears on every page.

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, multilingual sites (languages, locales, hreflang), 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.5.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**.
-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`.
+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). It is refused while a removed field still holds content, until the removal is confirmed.
+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, 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,19 +31,20 @@ 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 |
 | --- | --- | --- |
 | `ARECA_CMS_URL` | everything | The CMS base URL, e.g. `https://cms.example.com` |
-| `ARECA_SITE_TOKEN` | pull, client, preview | CMS: site Settings > Developer > build token (shown once; rotate to get a new one) |
+| `ARECA_SITE_TOKEN` | reads (pull, `manifest pull`, the client's snapshot calls) | CMS: site Settings > Developer > build token (shown once; rotate to get a new one) |
 | `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.
+The CLI loads `.env.local` and then `.env`, and existing process env wins. Library imports do **not** load env files. Each call reads only the credential it sends: a schema push needs the schema token but not the site token, and a preview needs neither (its token is signed).
 
-**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,14 +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.
+- `areca manifest pull --config areca.config.ts [--yes]` regenerates the config from the CMS. It replaces the whole file and keeps `siteKey` and `assets`. It prints the changes first. It asks (`--yes` without a TTY) only when something would be removed: a collection, a site content section, a field, a language, or the main language. Additions and changes are written without a question. A file that already matches writes nothing. A hand-written config that defines collections still asks before it is replaced.
+- **Removing a field that still holds content** deletes that content. `manifest push` lists the affected fields (`key.field`, with the entry count) and pushes nothing until they are confirmed: `--confirm-drop <key.field>` per field (repeatable), or `--yes` for all. In code, `syncManifest(config, { confirmDropFields: ["articles.subtitle"] })` does the same. An unconfirmed push throws `FieldDropsRequiredError` (exported; `.drops` holds the `FieldDrop` list, each `{ kind, key, field, entries }`). **Ask the user before confirming a drop**; never add `--yes` or `--confirm-drop` on your own.
+
+### 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`)
 
@@ -90,33 +119,48 @@ assets: { download: true, dir: "public/areca" /*, publicPath: "/areca" */ }, //
 ```text
 areca init [--cms-url <url>] [--token <t>] [--site-key <key>] [--out <dir>] [--config <path>]
            [--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 push [config] [--confirm-drop <key.field>]... [--yes]   # needs ARECA_SCHEMA_TOKEN and ARECA_CMS_URL
 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";
+
+export function getNewsArticles() {
+  return content.articles.all({ where: { category: "news" }, orderBy: { startsAt: "desc" }, limit: 10 });
+}
 
-type Article = SnapshotEntry & {
-  data: { title: string; body: RichTextValue; cover: ImageValue | null; author: ReferenceValue | null };
-};
+export function findArticle(slug: string) {
+  return content.articles.get(slug); // Entry | undefined
+}
 
-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);
+// 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`.
+
+## Languages
+
+Only when the CMS site has content languages. Set `languages`, `routes`, `requiredLanguages` and `translatable` in `areca.config.ts`. Reads pick a language with `content.in(locale)`, a per-call `{ locale, fallback }` or the `createContent({ locale })` resolver, and fall back to the main language. Entries carry `locale`, `isFallback`, `locales` and `alternates`; globals carry `$locale` and `$isFallback`. `seoHead` takes `locale` and `alternates` for hreflang, and `content.matchLocale` picks a visitor's language. `Href` is the union of every language's route; `content.in(locale)` narrows `href()` to that language's route. A pulled media URL is rewritten in every language view, so each language gets local files. Read [references/languages.md](references/languages.md) for the Paraglide setup, the other i18n libraries, preview with `locale`, and every export.
 
 ## Rich text
 
@@ -136,22 +180,25 @@ 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.
 - Direct use of `createArecaClient` and error messages.
 
-Read [references/api.md](references/api.md) for every export, type and signature.
+Read [references/api.md](references/api.md) for every export, type and signature, and [references/languages.md](references/languages.md) for languages.
 
 ## 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. Confirm a field removal or a language removal with the user first: both can delete content or stop a language being served. 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).