@areca-cms/skills 0.4.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, 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.
+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.4.0"
+  version: "0.5.0"
 ---
 
 # Areca site SDK
@@ -15,12 +15,12 @@ Requirements: Node >= 22.6 (24 LTS recommended), ESM only. It works with any fra
 ## Mental model
 
 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).
+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"`.
 
-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`.
+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
 
@@ -36,13 +36,13 @@ pnpm exec areca init --cms-url https://cms.example.com --token "$ARECA_SITE_TOKE
 | 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 the content object, `readContent` and the client in server or build code.
 
@@ -83,7 +83,8 @@ export default defineSiteContent({
 - 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)
 
@@ -118,7 +119,7 @@ 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>] [--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
@@ -157,6 +158,10 @@ const author = content.resolve(article.data.author); // Entry<"authors"> | null
 - `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
 
 ```tsx
@@ -187,11 +192,11 @@ Read [references/production.md](references/production.md) when the user needs an
 - 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`, then go live and pull. Don't hand-edit generated content or `areca.gen.ts`; a pull rewrites both.
+- 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.

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

@@ -7,11 +7,13 @@ ESM only. Import paths and their exports:
 | Export | Signature | Notes |
 | --- | --- | --- |
 | `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` = `PreviewEntryResult` `{ kind: 'entry', collection, slug, entry }` or `PreviewGlobalResult` `{ kind: 'global', global, entry }`. Needs `ARECA_CMS_URL` and `ARECA_SITE_TOKEN` (or pass `client`). |
+| `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 |
@@ -19,18 +21,20 @@ 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) |
 
-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`.
+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).
 
@@ -52,7 +56,11 @@ Typed content types (main entry, generated against `Register`):
 | `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}` `` |
+| `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) |
@@ -100,7 +108,7 @@ Typed content types (main entry, generated against `Register`):
 
 ## 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`.