@areca-cms/skills 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to `@areca-cms/skills`.
 
+## 0.5.0 (2026-10-26)
+
+### Features
+
+- **sdk:** manifest pull asks only when something would be removed (a265c3e)
+- **skills:** add areca-quickstart skill and set_publishing_mode MCP tool (3c1bdbd)
+
+## 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/README.md

@@ -6,6 +6,7 @@ Agent skills that teach AI coding agents and chat apps how to work with Areca CM
 | --- | --- |
 | `areca-sdk` | Connecting a website with `@areca-cms/site-sdk`: tokens and env vars, `areca.config.ts`, the `areca` CLI, reading content, rich text, SEO, preview routes, Go-live builds |
 | `areca-mcp` | Connecting an AI to a site's MCP server and using it: OAuth and personal keys, roles, the draft/ready/live workflow, field formats, SEO, images, every tool |
+| `areca-quickstart` | Setting up Areca in a new website project: checks the project, interviews you about the content model, languages and build, wires the SDK, and makes a first release. Run it as `/areca-quickstart` |
 
 The skills are plain `SKILL.md` folders in the open [Agent Skills](https://agentskills.io) format. They have no scripts and no dependencies, so they work in any project.
 
@@ -45,7 +46,7 @@ MCP config is written to the project file for Claude Code (`.mcp.json`), Cursor,
 ## Other ways to install
 
 - **Claude Code plugin:** `/plugin marketplace add ekozf/areca-cms`, then `/plugin install areca@areca-cms`.
-- **skills CLI:** `npx skills add ekozf/areca-cms --skill areca-sdk --skill areca-mcp`.
+- **skills CLI:** `npx skills add ekozf/areca-cms --skill areca-sdk --skill areca-mcp --skill areca-quickstart`.
 - **Manually:** copy `skills/areca-*` from the repository into your agent's skills folder.
 
 ## Development

package/dist/cli.js

@@ -19,7 +19,7 @@ Commands:
 
 Options:
   -a, --agent <id>    Agent id, repeatable or comma separated (see list)
-  -s, --skill <name>  Only this skill (areca-sdk, areca-mcp); default all
+  -s, --skill <name>  Only this skill (areca-sdk, areca-mcp, areca-quickstart); default all
   -g, --global        Install into user-level folders instead of the project
       --mcp-url <url> Connector URL (<cms>/api/mcp/<site-slug>) to register
       --out <dir>     Zip folder for chat apps and export (default: areca-skills)
@@ -245,6 +245,8 @@ function hintFor(name) {
         return 'website code: setup, config, CLI, content, preview, deploy';
     if (name === 'areca-mcp')
         return 'AI content editing: connect, tools, workflow';
+    if (name === 'areca-quickstart')
+        return 'Set up Areca in a new site project (interview + wiring)';
     return '';
 }
 async function chooseMcpUrl(options, cwd, interactive, required = false) {

package/dist/skills.d.ts

@@ -5,10 +5,15 @@ export type Skill = {
     dir: string;
 };
 /**
- * Skills ship in the package's `skills/` folder (copied from the repo root at
- * build). From source inside the monorepo, fall back to the repo root copy.
+ * Where the bundled skills live. Inside the monorepo the root `skills/` folder is
+ * the source of truth, so it wins over the `skills/` copy that `build` makes inside
+ * the package (that copy can go stale). An npm install has no repo root, so the
+ * packaged copy is used.
+ *
+ * `moduleDir` is the folder of this module (`src/` from source, `dist/` when built).
+ * It is a parameter so tests can point it at a temp layout.
  */
-export declare function skillsRoot(): string;
+export declare function skillsRoot(moduleDir?: string): string;
 export declare function loadSkills(root?: string): Skill[];
 /** Top-level `key: value` pairs of a SKILL.md frontmatter block. */
 export declare function parseFrontmatter(source: string): Record<string, string>;

package/dist/skills.js

@@ -1,19 +1,26 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+const MARKER = 'areca-sdk/SKILL.md';
 /**
- * Skills ship in the package's `skills/` folder (copied from the repo root at
- * build). From source inside the monorepo, fall back to the repo root copy.
+ * Where the bundled skills live. Inside the monorepo the root `skills/` folder is
+ * the source of truth, so it wins over the `skills/` copy that `build` makes inside
+ * the package (that copy can go stale). An npm install has no repo root, so the
+ * packaged copy is used.
+ *
+ * `moduleDir` is the folder of this module (`src/` from source, `dist/` when built).
+ * It is a parameter so tests can point it at a temp layout.
  */
-export function skillsRoot() {
-    const candidates = [
-        fileURLToPath(new URL('../skills', import.meta.url)),
-        fileURLToPath(new URL('../../../skills', import.meta.url)),
-    ];
-    const found = candidates.find((dir) => existsSync(join(dir, 'areca-sdk', 'SKILL.md')));
-    if (!found)
-        throw new Error(`Bundled skills not found (looked in ${candidates.join(', ')})`);
-    return found;
+export function skillsRoot(moduleDir = dirname(fileURLToPath(import.meta.url))) {
+    const repoRoot = resolve(moduleDir, '../../..');
+    const repoSkills = join(repoRoot, 'skills');
+    const packaged = resolve(moduleDir, '../skills');
+    const inRepo = existsSync(join(repoRoot, 'pnpm-workspace.yaml')) && existsSync(join(repoSkills, MARKER));
+    if (inRepo)
+        return repoSkills;
+    if (existsSync(join(packaged, MARKER)))
+        return packaged;
+    throw new Error(`Bundled skills not found (looked in ${repoSkills}, ${packaged})`);
 }
 export function loadSkills(root = skillsRoot()) {
     return readdirSync(root, { withFileTypes: true })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@areca-cms/skills",
-  "version": "0.3.0",
+  "version": "0.5.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.5.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`), the site's publishing mode, whether a deployment target is configured (`deploymentConfigured`) and, on a multilingual site, its `languages`.
+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.
 
@@ -36,8 +36,9 @@ 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.
+- Publishing mode: `production` (go live deploys to the live site) or `demo` (go live builds a release that `areca pull` fetches; demo releases never reach visitors). Agency admins switch it with `set_publishing_mode`. A site that has ever gone live cannot switch to demo, and production needs a deployment target set in Settings › Deployment.
 - 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 +48,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`, `delete_global`, `set_site_languages` and `set_publishing_mode` (needs 2FA) |
 
 ## Writing content
 
@@ -56,9 +57,21 @@ 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:** check the first line of the site's `areca.config.ts`. If it is `// Generated by \`areca manifest pull\`.`, the schema is managed in the CMS: change it with `upsert_collection` or `upsert_global`, then run `areca manifest pull`. If the config is hand-written, the schema is in code: change `areca.config.ts` and push it with `areca manifest push`. Both ways replace the whole field list, so send every field.
 
-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).
+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). Multilingual details are in [references/languages.md](references/languages.md).
+
+## Multilingual sites
+
+Only when `get_site_info` returns `languages`. The main language is the fallback; each other language is written on its own.
+
+1. `get_site_info`: note `languages.main`, `languages.all` and each collection's `requiredLanguages`.
+2. `create_entry` or `update_entry` (or `update_global`) for the main language, with no `locale`.
+3. One `update_entry({ id, locale, fields, seo, slug, expectedVersion })` call per other language. Check `sharedFieldsUpdated` in each response: those fields changed in every language.
+4. `get_entry({ id })` and read `translations`. Fill any missing required fields until each language is `complete`.
+
+`mark_ready` refuses an entry until every required language is complete. Only mark ready when the user asks. Details, the `translatable` rules and the errors are in [references/languages.md](references/languages.md).
 
 ## Errors
 
@@ -67,6 +80,8 @@ Tool errors come back as normal results with `isError: true` and a message that
 - `Validation failed`: call `get_collection_schema`.
 - `changed since you last read it`: call `get_entry` and retry.
 - `Only site owners…` or `Going live…`: tell the user who can do it.
+- `is not one of this site's languages`: use a code from `get_site_info`. `This site has one language`: drop `locale`.
+- A refusal from `mark_ready` or `schedule_entry` that names languages: fill in those languages with `update_entry` and `locale`.
 - `Something went wrong on the Areca server (ref …)`: nothing is confirmed saved. Retry once, then report the ref.
 
 Over HTTP, `401` means sign in again or reconnect. `403 mfa_required` means the agency admin must turn on 2FA. `429` means wait for `Retry-After` (120 requests/min per credential).

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/languages.md

@@ -0,0 +1,86 @@
+# Multilingual sites
+
+A site can publish in several languages. A site with one language behaves as described in the rest of the skill, and none of the `locale`, `translations`, `missingLanguage` or `translatable` parameters appear. Use this file only when `get_site_info` returns `languages`.
+
+## Languages and the main language
+
+`get_site_info` returns `languages`:
+
+```json
+{ "main": "nl", "all": ["nl", "en"], "names": { "nl": "Dutch", "en": "English" } }
+```
+
+- `main` is the fallback. Visitors get it when a translation is missing, and it holds the shared base values.
+- `all` is the display order and always includes `main`.
+- Codes are BCP 47 (`nl`, `en`, `nl-BE`). Use the exact code from `all` in `locale`.
+
+`set_site_languages({ main, all })` changes them. Agency admins only.
+
+| Parameter | Behaviour |
+| --- | --- |
+| `main` | Required. Must be one of `all`. |
+| `all` | Required. Every language, in display order, including `main`. At least one, at most the site limit. |
+
+- Removing a language hides it: it stops shipping and leaves the editor, but its text stays in the entries and comes back if you add the language again.
+- A site cannot go back to having no languages. To go back to one language, set `all` to the single code (the rest are hidden as above).
+- Changing `main` deletes nothing. Entries and sections that are not complete in the new main language cannot be marked ready until they are. The result's `gaps` counts them, and the message says how many.
+
+## Writing one language per call
+
+`create_entry`, `update_entry`, `update_global` and `update_asset_alt` take `locale`. Leave it out for the main language.
+
+- `fields`, `seo` and `slug` apply to the language you name. A translation's `slug` is that language's own URL. Send `""` to fall back to the main slug.
+- Fields that are not translatable are shared. Changing one in any language changes it in every language, and the response lists them in `sharedFieldsUpdated`. Check that list before you assume a write stayed in one language.
+- By default `text`, `textarea`, `richtext` and `url` fields are per language. Other types (number, date, image, reference, select and so on) are shared. `get_collection_schema` shows `translatable` for each field, and `get_site_info` lists `translatableFields` per collection and section.
+
+`update_entry` only changes the keys you send. Pass `expectedVersion` from `get_entry` as usual.
+
+## Checking translations
+
+`get_entry` without `locale` returns the main language's values plus `translations`:
+
+```json
+"translations": {
+  "en": { "complete": false, "missing": ["fields.summary"] }
+}
+```
+
+- `complete` is true when every required field has a value in that language.
+- `missing` lists the required fields that are empty there.
+- With `locale`, `get_entry` returns that language's values (slug and seo included) instead, and no `translations`.
+
+`list_entries({ collection, missingLanguage: "en" })` returns only entries whose draft is not complete in that language.
+
+`get_global({ global, locale })` and `get_preview_url({ id, locale })` work the same way. A preview link with `locale` opens that language's page.
+
+## Required languages
+
+Each collection and section can require languages to be complete before it is marked ready. Set them with `requiredLanguages` (for example `["en"]`) on `upsert_collection` or `upsert_global`, or in `areca.config.ts`. `get_site_info` shows the current list per collection.
+
+`mark_ready` and `schedule_entry` refuse an entry until every required language is complete. The error names the languages and the fields that are missing. Fill them in with `update_entry` and `locale`, then mark ready again. Only when the user asks.
+
+## Per-language routes
+
+`upsert_collection` also takes `routes`, a route pattern per language, each with `$slug`. For example `{"nl": "/vacatures/$slug"}`. Languages that are not listed use `routePattern`. Patterns do not contain the language prefix, because the site adds it. Send `{}` to remove them all.
+
+`routes` and `requiredLanguages` are ignored on a site without languages. For a site that syncs its schema from code, put these in `areca.config.ts` and push with `areca manifest push` rather than calling `upsert_collection`.
+
+## Translating with AI
+
+There is no MCP tool for AI translation. The CMS editor's language bar offers "translate with AI", which fills empty fields from the main language. An agent that is asked to translate writes each language itself with `update_entry` and `locale`.
+
+## Multilingual workflow
+
+1. `get_site_info`: read `languages` (main and `all`), and each collection's `requiredLanguages` and `translatableFields`.
+2. `get_collection_schema({ collection })`: check which fields are `translatable`, and use the `translation` example if the response has one.
+3. `create_entry` or `update_entry` for the main language, with no `locale`.
+4. For each other language, one `update_entry({ id, locale, fields, seo, slug, expectedVersion })` call. Read `sharedFieldsUpdated` in each response.
+5. `get_entry({ id })` and check `translations`. Fill any missing required field, then repeat until every language is `complete`.
+6. Show the user the `previewUrl`, or call `get_preview_url({ id, locale })` to check one language. Mark ready only when the user asks.
+
+## Errors
+
+- `This site has one language, so locale does not apply. Leave it out.`: remove `locale` from the call.
+- `"xx" is not one of this site's languages (...)`: the error lists the codes the site has. Use one of them, or call `get_site_info`.
+- `Only agency admins can change the site languages.`: tell the user an agency admin must change them.
+- A mark-ready refusal for incomplete languages: fill in the named languages and fields, then retry.

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

@@ -6,19 +6,29 @@
 
 | Tool | Access | Inputs | Returns |
 | --- | --- | --- | --- |
-| `get_site_info` | all | none | `site` (name, slug, productionUrl, publishingMode), `you` (role, capabilities), `cannotDo[]`, `collections[]`, `guide`. **Call first.** |
-| `get_collection_schema` | all | `collection*` | Per-field key, type, required, format, options; example `fields` and `seo` payloads; SEO guide |
+| `get_site_info` | all | none | `site` (name, slug, productionUrl, publishingMode, deploymentConfigured), `you` (role, capabilities), `cannotDo[]`, `collections[]`, `globals[]` (site content: key, label, enabled, fieldCount, seo, previewPath), `guide`. On a site with languages also `languages` (`main`, `all`, `names`) and, per collection and section, `requiredLanguages`, `translatableFields` and `routes`. **Call first.** |
+| `get_collection_schema` | all | `collection*` | Per-field key, type, required, format, options (and `translatable` on sites with languages); example `fields` and `seo` payloads; SEO guide; `translation` example on sites with languages |
 
 ## Entries
 
 | Tool | Access | Inputs | Returns |
 | --- | --- | --- | --- |
-| `list_entries` | all | `collection*`, `status?` (draft, ready, scheduled, archived), `search?`, `limit?` (1-100, default 20), `offset?` | `items[]` (id, slug, status, live, pendingRelease, title, version), `total`, `nextOffset` |
-| `get_entry` | all | `id*`, `includePublished?` | `fields`, `seo`, `status`, `live`, `pendingRelease`, `editedSinceReady`, `version`. With `includePublished`, also `liveFields` and `approvedFields`. |
-| `create_entry` | all | `collection*`, `fields?`, `seo?` | New draft + `previewUrl` |
-| `update_entry` | all | `id*`, `fields?`, `seo?` (at least one), `expectedVersion?` | Updated draft + `previewUrl`. Keys you leave out keep their values. |
+| `list_entries` | all | `collection*`, `status?` (draft, ready, scheduled, archived), `search?`, `limit?` (1-100, default 20), `offset?`, `missingLanguage?` (languages sites: only entries whose draft is not complete in that language) | `items[]` (id, slug, status, live, pendingRelease, title, version), `total`, `nextOffset` |
+| `get_entry` | all | `id*`, `includePublished?`, `locale?` (languages sites) | `fields`, `seo`, `status`, `live`, `pendingRelease`, `editedSinceReady`, `version`. With `includePublished`, also `liveFields` and `approvedFields`. With `locale`, that language's values (slug and seo included) and `locale`. Without it on a languages site: the main language plus `translations` (`complete` and `missing` for each other language). |
+| `create_entry` | all | `collection*`, `fields?`, `seo?`, `slug?`, `locale?` (languages sites) | New draft + `previewUrl`. `fields`, `seo` and `slug` apply to `locale` (default main). |
+| `update_entry` | all | `id*`, `fields?`, `seo?`, `slug?` (at least one), `locale?` (languages sites), `expectedVersion?` | Updated draft + `previewUrl`. Keys you leave out keep their values. Languages sites: one language per call; `sharedFieldsUpdated` lists the non-translatable fields that changed in every language. |
 | `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. |
+| `get_preview_url` | all | `id*`, `locale?` (languages sites) | `{ 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`), `locale?` (languages sites) | `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), `locale?` (languages sites), `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
 
@@ -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 |
@@ -39,7 +51,7 @@
 | `list_assets` | all | `search?`, `limit?` (1-100), `offset?` | assetId, filename, mimeType, width, height, alt, url |
 | `get_asset` | all | `id*` | Asset + `usageCount` |
 | `upload_asset_from_url` | all | `url*` (direct http(s) file link), `altText?`, `filename?` | Asset with `assetId` + `howToUse` |
-| `update_asset_alt` | all | `id*`, `altText*` (`""` clears) | Asset |
+| `update_asset_alt` | all | `id*`, `altText*` (`""` clears), `locale?` (languages sites: alt text for that language) | Asset |
 | `delete_asset` | owner | `id*` | Refused while the asset is in use |
 
 ## Publishing
@@ -47,6 +59,7 @@
 | Tool | Access | Inputs | Returns |
 | --- | --- | --- | --- |
 | `get_release_status` | all | none | `publishingMode`, `live`, `demo`, `activeJob`, `pendingCount`, `pendingChanges[]` |
+| `set_publishing_mode` | agency | `mode*` (`demo` or `production`) | `publishingMode`, `deploymentConfigured`. `demo`: `go_live` builds a release that `areca pull` can fetch without a deployment; demo releases never reach visitors. `production`: `go_live` deploys to the live site and needs a deployment target (application ID and health check URL, set in Settings › Deployment). Refused with a conflict when switching to `demo` after the site has ever gone live, or to `production` without a deployment target. The same mode changes nothing and writes no audit entry. Each change is audited with the MCP caller. |
 | `list_publications` | all | `limit?` (1-50, default 10) | Publications, newest first |
 | `get_build_job` | all | `jobId*` | Status, attempts, timing, error |
 | `go_live` | go-live | `note?` | Queues a build that publishes **all** ready changes and returns `publicationId` and `jobId`. Poll `get_build_job`. |
@@ -57,8 +70,18 @@
 
 | Tool | Access | Inputs | Effect |
 | --- | --- | --- | --- |
-| `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. |
+| `upsert_collection` | agency | `key*`, `label*`, `routePattern*`, `fields*` (up to 100: `key*`, `label*`, `type*`, `required?`, `options?`, `collection?`, `description?`, `after?`, `translatable?` on languages sites), `enabled?`, `requiredLanguages?`, `routes?` (languages sites) | 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?`, `requiredLanguages?` (languages sites) | 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. |
+
+## Languages (agency)
+
+| Tool | Access | Inputs | Returns |
+| --- | --- | --- | --- |
+| `set_site_languages` | agency | `main*` (must be in `all`), `all*` (every language in display order, including `main`) | `languages` (main, all, names) and `gaps`: entries and sections not complete in the new main language. Removing a language hides it and keeps its text. Languages cannot be turned off once set. |
+
+On a site without languages none of the `locale`, `translations`, `missingLanguage`, `translatable` or `requiredLanguages` parameters appear, and their results are unchanged. See [languages.md](languages.md) for the workflow.
 
 ## Prompt