@areca-cms/skills 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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

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.4.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,7 +3,7 @@ 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.4.0"
+  version: "0.5.0"
 ---
 
 # Areca MCP
@@ -20,7 +20,7 @@ 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, the site content sections (`globals`) and the site's publishing mode.
+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,6 +36,7 @@ schedule_entry            -> scheduled goes live at a set time (also publishes o
 
 - `status`: `draft` | `ready` | `scheduled` | `archived`. To answer "what is live" use the flags: `live` (on the production site now), `pendingRelease` (approved changes waiting for the next go live) and `editedSinceReady`.
 - Drafts are safe. Nothing changes the live site until an entry is marked ready **and** a go live happens.
+- 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` 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.
@@ -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`, `delete_collection`, `upsert_global` and `delete_global` (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
 
@@ -57,9 +58,20 @@ schedule_entry            -> scheduled goes live at a set time (also publishes o
 - **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.
 - **Site content (globals):** single sections such as company info or the home page. Read one with `get_global({ global })` and change it with `update_global({ global, fields?, seo?, expectedVersion? })`. It is not a collection, so `create_entry` and `list_entries` do not apply. Its `id` (from `get_global`) works with `mark_ready`, `schedule_entry`, `cancel_schedule`, `list_revisions`, `restore_revision` and `get_preview_url`. Use `discard_global_draft` to go back to the ready values. `seo` is only accepted when the section has SEO on.
-- **Schema:** if the site project has `areca.config.ts`, change the schema there and push it with the SDK rather than calling `upsert_collection` or `upsert_global`. Both replace the whole field list.
+- **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
 
@@ -68,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/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,19 @@
 
 | Tool | Access | Inputs | Returns |
 | --- | --- | --- | --- |
-| `get_site_info` | all | none | `site` (name, slug, productionUrl, publishingMode), `you` (role, capabilities), `cannotDo[]`, `collections[]`, `globals[]` (site content: key, label, enabled, fieldCount, seo, previewPath), `guide`. **Call first.** |
-| `get_collection_schema` | all | `collection*` | Per-field key, type, required, format, options; example `fields` and `seo` payloads; SEO guide |
+| `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)
 
@@ -26,8 +26,8 @@ Single sections such as company info or the home page. Editors and owners see en
 
 | Tool | Access | Inputs | Returns |
 | --- | --- | --- | --- |
-| `get_global` | all | `global*` (key from `get_site_info`) | `id`, `key`, `label`, `status`, `live`, `pendingRelease`, `version`, `editedSinceReady`, `previewAvailable`, `values` (rich text as Markdown, images as `{assetId,url,alt}`, references as `{entryId}`), `seo` (only with SEO on), `fields` (format of each field), `example` |
-| `update_global` | all | `global*`, `fields?`, `seo?` (at least one; refused without SEO on the section), `expectedVersion?` | Updated draft + `previewUrl`. Keys you leave out keep their values. |
+| `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
@@ -51,7 +51,7 @@ Single sections such as company info or the home page. Editors and owners see en
 | `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
@@ -59,6 +59,7 @@ Single sections such as company info or the home page. Editors and owners see en
 | 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`. |
@@ -69,11 +70,19 @@ Single sections such as company info or the home page. Editors and owners see en
 
 | 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?` | Creates the site content section or **replaces** its fields, SEO setting, preview path and enabled flag. Keeps its content. |
+| `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
 
 `write_post({ collection*, topic* })` returns a step-by-step writing brief: schema, images, draft and SEO. It ends with "mark ready or go live only when asked".

package/skills/areca-quickstart/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: areca-quickstart
+description: Sets up Areca CMS in a new or existing website project for a web agency. Detects the framework, interviews the user, creates the content model over MCP or in code, wires the site and publishes a first release. Use when the user wants to set up, connect or integrate Areca CMS, run the quickstart, add Areca to a website, or add collections like blog or vacancies.
+license: MIT
+metadata:
+  version: "0.5.0"
+---
+
+# Areca quickstart
+
+This skill sets up Areca CMS in one website project. You detect what the project already has, ask the user a few questions, then do the work. The user is an agency. The website is for one client.
+
+The skill runs in two modes:
+
+- **New setup:** no Areca files exist yet. Go through steps 0 to 7.
+- **Re-run:** Areca is already set up. Go to [Re-run mode](#re-run-mode).
+
+Plain steps, in order:
+
+0. Detect the project.
+1. Check the MCP connection.
+2. Interview the user (four batches).
+3. Show the content model and wait for approval.
+4. Connect the project and create the schema.
+5. Wire the project (scripts, framework, languages, pages).
+6. Make the first release, pull the content and verify.
+7. Summarise and hand over.
+
+Keep the details in the reference files:
+
+- [references/interview.md](references/interview.md): the question batches and the plan format.
+- [references/recipes.md](references/recipes.md): collection and section recipes with fields.
+- [references/connect.md](references/connect.md): MCP connection, creating the site, tokens, demo mode.
+- [references/frameworks.md](references/frameworks.md): wiring code for TanStack Start, Next.js, Astro and plain Node.
+- [references/first-release.md](references/first-release.md): sample entries, release, pull, checks and troubleshooting.
+
+For API detail, read the `areca-sdk` skill (config, fields, CLI, content API) and the `areca-mcp` skill (tools, roles, workflow). Do not copy their detail into the project. Name the skill and use what it says. If those skills are not installed, read the docs in the `skills/` folder of https://github.com/ekozf/areca-cms instead.
+
+## Ground rules
+
+- Never delete a collection, field, section or language without explicit confirmation from the user.
+- Never run `areca init --force`. It replaces `areca.config.ts` with an empty config.
+- Never call `go_live` on your own. Ask first, every time. The same goes for `schedule_entry`, `rollback` and `set_publishing_mode`.
+- Never confirm a field drop with `--yes` or `--confirm-drop` on your own.
+- Never ask for a token or key in chat. Never print a token. See [Secrets](#secrets).
+- Never install a package you were not asked to install. This includes an i18n library. Ask first.
+- Confirm before you overwrite an existing file, or change an existing `package.json` script that is not ours.
+- Do not experiment on a live production site. For an existing live site, use hidden collections (`enabled: false`) or a separate site. Dev environments are planned but not available yet.
+- Respect the user's choices. If they say no to MCP, use code-first. If they say no to a route, skip it.
+- Show a plan before you write files, and wait for the user to approve the content model.
+
+## Step 0: Detect the project
+
+Read these. Do not change anything yet.
+
+1. `package.json`: framework and scripts.
+   - `@tanstack/react-start` means TanStack Start.
+   - `next` means Next.js.
+   - `astro` means Astro.
+   - `vite` alone, or no framework, means plain Vite or Node.
+   - Note the `dev` script and its port (for example `--port 3001`). If the script sets no port, use the framework's default and confirm it from the dev server output in step 6.
+   - Note `packageManager` if it is set.
+2. Lockfile, to find the package manager: `pnpm-lock.yaml` means pnpm, `package-lock.json` means npm, `yarn.lock` means yarn, `bun.lock` or `bun.lockb` means bun. If there is more than one, use the `packageManager` field. If there is still no answer, ask.
+3. Areca state: does `areca.config.ts` exist? Is `@areca-cms/site-sdk` in `dependencies`? Does `src/generated/content/areca.gen.ts` exist? If any is true, use [Re-run mode](#re-run-mode).
+4. i18n: look for `@inlang/paraglide-js` or `project.inlang/`, `next-intl`, `i18next` or `react-i18next`, `@lingui/*`, `vue-i18n`, or an `i18n` block in the framework config (for example `astro.config.mjs`). If none, the answer is "none".
+5. Routes and pages: `src/routes/` (TanStack), `app/` or `src/app/` or `pages/` (Next), `src/pages/` (Astro). Note any blog, team or job pages that already exist.
+6. Node version: run `node -v`. Areca needs 22.6 or newer. Use 24 LTS if possible. Loading a TypeScript config needs 22.18 or newer, or `tsx`.
+7. Env files: check whether `.env.local` exists and which keys it has. Never print values. For a token, print only its length:
+
+   ```bash
+   awk -F= '/^ARECA_(CMS_URL|SITE_TOKEN|SCHEMA_TOKEN)=/{print $1, "length", length($2)}' .env.local 2>/dev/null
+   ```
+
+8. Git: run `git status --short`. If the project is not a git repo, say so and offer `git init` before you write any file. If the tree has unrelated changes, tell the user before you start.
+
+No framework yet (no `package.json`, or no framework in it)? Say so. Offer to scaffold a TanStack Start app with `pnpm dlx @tanstack/cli@latest create` (not `create-tsrouter-app`). Then continue from step 0 in the new project. This skill does not cover the scaffold itself.
+
+Report what you found in a short list. Ask only about what you could not detect. Go to step 1.
+
+## Step 1: Check the MCP connection
+
+The Areca MCP server gives the agent its own tools. Look for a tool named `get_site_info` from an Areca server. The name may carry a prefix such as `mcp__areca-<slug>__get_site_info`.
+
+- **Connected:** call `get_site_info`. Read `you.role`, `cannotDo`, `site.publishingMode`, `collections`, `globals` and `languages`.
+  - Role **agency admin**: the schema can be created over MCP (MCP-first, the default).
+  - Any other role: the schema must be created in code (code-first). Say why. Owners and editors cannot change the schema over MCP.
+- **Not connected:** ask the user whether they want to connect. Explain what you need: the CMS URL and the site slug. The connector URL is `<cms-url>/api/mcp/<site-slug>`. Explain the sign-in (a browser opens on first use). Read [references/connect.md](references/connect.md) for the exact steps per app. Tell the user that the agent session may need a reload or restart after the connector is added.
+- **Declined, or not possible now:** code-first. Say so once and move on.
+
+If the site does not exist in the CMS yet, the user must create it in the CMS. Read the "Create the site" section in [references/connect.md](references/connect.md). Do not guess a site key or a token.
+
+## Step 2: Interview the user
+
+Read [references/interview.md](references/interview.md). It has four batches: A (project), B (content model), C (languages) and D (build and preview). Ask one batch at a time. Each batch has defaults and an "accept all defaults" reply.
+
+- Use the detected values as defaults. Do not ask again what you already know.
+- Record the answers. After batch D, show the plan in the format from `interview.md`. Ask the user to confirm it.
+
+## Step 3: Show the content model and wait for approval
+
+The approval in this step covers every MCP write and every file write that follows. Record it in your notes before you call any write tool, including `set_site_languages`. No recorded yes, no write.
+
+For each collection and section in the plan, build the schema from [references/recipes.md](references/recipes.md). Show one table per collection or section:
+
+| Key | Type | Required | Translatable | Notes |
+| --- | --- | --- | --- | --- |
+
+Also show the route for each collection (for example `/blog/$slug`) and the SEO setting for each section. When an extra was declined, show the fields that were removed because of it, in the table, for example a row "removed: author (authors declined)".
+
+Ask: "Shall I create this content model?" Wait for a yes. If the user changes something, update the plan and show the changed tables again. Do not create anything before approval.
+
+## Step 4: Connect the project and create the schema
+
+Record the Step 3 approval before any MCP write, including `set_site_languages`.
+
+### 4a. Install, init and tokens
+
+1. Install the SDK with the detected package manager: `pnpm add @areca-cms/site-sdk`, `npm install @areca-cms/site-sdk`, `yarn add @areca-cms/site-sdk` or `bun add @areca-cms/site-sdk`. Skip this if it is already there.
+2. Run `areca init` once. Use one of these two ways.
+   - **Preferred:** ask the user to run `<pm> exec areca init` in their own terminal. It asks for the CMS URL, the site token and the site key. The token prompt hides what is typed. Wait for the user to say it is done.
+   - **Alternative:** if the user is fine with it, the user first puts `ARECA_CMS_URL` and `ARECA_SITE_TOKEN` in `.env.local` (you do not paste the token). Then run the non-interactive form, with the URL and site key from the plan:
+
+     ```bash
+     <pm> exec areca init --yes --cms-url <url from the plan> --site-key <site key from the plan> --token "$(sed -n 's/^ARECA_SITE_TOKEN=//p' .env.local)"
+     ```
+
+     Do not echo the command with the token in it. The `--token` flag is visible to other users on the machine for a moment. Mention that.
+3. `init` writes `areca.config.ts` (if missing), `.env.example`, `.env.local`, `.gitignore` entries, `src/generated/content/manifest.json` and the scripts `sync-manifest` and `content:pull`. It also wraps `dev` in `areca run --` unless the script already loads env files. It does not install packages and does not add `areca.gen.ts`. Check the result with `git diff` and show the user a short list.
+   - `init` prints code-first next steps (`sync-manifest`, then publish). Ignore that text when you go MCP-first. The schema comes from MCP, and `sync-manifest` is not used.
+4. Schema token (code-first only): the user adds `ARECA_SCHEMA_TOKEN=` to `.env.local` themselves, from Settings › Developer › Schema-write token. MCP-first does not need it.
+5. Check the tokens with the length check from step 0. Do not print them. If a value is empty, say which key is empty and where to paste it. Continue only when the needed keys are set.
+6. `.env.local` is gitignored. Leave its file permissions as they are. Do not run `chmod` on your own. If the user asks for stricter permissions, `chmod 600 .env.local` is the usual choice.
+
+### 4b. Create the schema
+
+**MCP-first (default when the role is agency admin):**
+
+1. Call `get_site_info` again. Check that the site matches the site key in the plan.
+2. If the plan has languages, call `set_site_languages` with `main` and `all`. Tell the user that languages cannot be turned off once set. Ask first if that was not already clear in the plan.
+3. For each collection, call `get_collection_schema` for an existing one. Then call `upsert_collection` with `key`, `label`, `routePattern`, the full `fields` list, `requiredLanguages` and `routes` when needed. Fields replace the whole list, so always send every field. A `slug` field is added when missing, but include it anyway.
+4. For each section, call `upsert_global` with `key`, `label`, the full `fields` list, `seo` and `previewPath`.
+5. Call `get_site_info` again and compare with the plan. Report any difference.
+6. Pull the schema into the project: `<pm> exec areca manifest pull`. This writes `areca.config.ts` from the CMS, so the schema is in Git. A file it wrote before (it starts with the header `// Generated by \`areca manifest pull\`.`) asks only before a removal (a collection, section, field, language, or the main language). If it stops for a removal, show the user the diff and get a yes. Then follow [first-release.md](references/first-release.md) (section 7) before you add `--yes`. A file without the header that already has collections (for example from an older SDK) asks once. With the user's yes, run `<pm> exec areca manifest pull --yes` once.
+
+`manifest pull` rewrites the config file. Keep hand edits out of it. It keeps `siteKey`, `assets` and `i18n`.
+
+**Code-first (fallback):**
+
+1. Write `areca.config.ts` from the approved plan. Use `defineSiteContent` from `@areca-cms/site-sdk`. Use the field rules and the reserved names from the `areca-sdk` skill. Add `languages`, `i18n.paraglide` and `assets` only when the plan says so. Confirm before you overwrite a config that already has collections.
+2. Check that the user has `ARECA_SCHEMA_TOKEN` set (step 4a.5).
+3. Run `<pm> exec areca manifest push`. A push disables collections that are not in the config. If the CMS says a removed field still holds content, the push stops. Show the list to the user and ask. Do not add `--yes`.
+
+If an MCP-first or code-first step fails, read the error and the `areca-sdk` or `areca-mcp` skill. Tell the user what failed. Do not try a different path without asking.
+
+## Step 5: Wire the project
+
+Do these in order. Show the user each file you will change before you change it when the file already exists.
+
+1. **Scripts** in `package.json`. Keep the scripts `init` added. Add these, using the detected package manager:
+   - `content:sync`: `areca manifest pull && areca pull --out src/generated/content` (MCP-first). It asks only before a removal. A config from an older SDK (no header) asks once: see step 4b.6.
+   - `sync-manifest` (`areca manifest push`, needs `ARECA_SCHEMA_TOKEN`) is for code-first only. In MCP-first, leave it in place and tell the user it is not used.
+   - `prebuild`: `areca pull` (plus the Paraglide compile first when Paraglide is used). A build without content fails until the first release exists. That is expected.
+   - `predev` (optional): only after the first release. A failing `predev` stops the dev server.
+   - Do not change `dev` again. `init` already wraps it in `areca run --` when needed.
+2. **Languages** (only if the plan has them). Set `languages` in `areca.config.ts` through MCP or by code. Set up Paraglide only if the user agreed to it. Install it only after approval. For TanStack Start the Paraglide recipe in [references/frameworks.md](references/frameworks.md) was verified end to end; follow it. Other i18n libraries: pass the locale yourself with `content.in(locale)`.
+3. **Framework wiring**: read the section for the detected framework in [references/frameworks.md](references/frameworks.md). Add:
+   - a server-only content module (the code imports `content` from `areca.gen.ts`),
+   - list and detail pages for each collection in batch D,
+   - head tags from `seoHead` or `seoHeadHtml`,
+   - the home and about pages when they are in the plan,
+   - a preview route when the user asked for it,
+   - a health route only when the user plans go-live builds.
+4. **Existing pages**: when the user chose "connect into existing pages", change only the data source. Keep the markup and styles. Show the diff.
+5. **Build output**: keep `src/generated/content/*.json` out of Git. The `.gitignore` entries from `init` do that. Commit `areca.gen.ts` once it exists. Do not commit unless the user asks.
+
+Do not render CMS content in browser code. The SDK content object and tokens are server-only. Use the framework's server functions, server components or build-time code.
+
+## Step 6: First release, pull and verify
+
+Read [references/first-release.md](references/first-release.md). The short version:
+
+1. Check the publishing mode. Use demo mode for the first release. Production needs the user's explicit choice, and a site that already went live in production must not get sample content (see first-release.md, section 1).
+2. Create one sample entry per collection, in dependency order (authors before posts, for example). The title starts with `[Sample]`, or the main text field when there is no title. Fill the SEO fields. Fill the main language and each required language.
+3. Fill each required section with `update_global`. Use the real company details from the interview. For other copy, write short placeholder text and say so.
+4. Mark everything ready. Tell the user what you are doing.
+5. Ask: "Go live now in demo mode? This publishes N entries and M sections." Wait for a yes.
+6. Go live, then poll `get_build_job` until the job is done. If the agent has no go-live permission, ask the user to press Go live in the CMS and wait for them.
+7. Pull: `<pm> exec areca pull --out src/generated/content`. Use the direct command, not the `content:sync` script. The script also runs `manifest pull`, which stops without a terminal when that pull would remove something. Expect `Pulled publication …` and a `Types:` line.
+8. Verify: typecheck, build, start the dev server, and check that a sample page returns HTTP 200 and shows its title. Use the checks in the first-release reference.
+9. Ask the user whether to archive the sample entries or keep them as editor examples. Do not archive without a yes.
+
+If the user has no sample to show, or the build fails for a reason you cannot fix, stop and report the exact error.
+
+## Step 7: Finish
+
+Give the user a short summary with this shape. Keep it plain.
+
+```text
+Areca CMS is set up in <project path>.
+
+Created in the CMS:
+- Collections: <key> (<route>), ...
+- Sections: <key>, ...
+- Languages: <main> (main), <others> | none
+
+Files changed:
+- areca.config.ts, .env.local (tokens: not shown), .gitignore
+- src/generated/content/areca.gen.ts (commit this)
+- <pages and modules you wrote>
+
+Keep content up to date:
+- <pm> run content:sync    (MCP-first: pulls the schema and the published content)
+- <pm> run content:pull    (code-first: pulls published content only)
+- After you edit areca.config.ts by hand (code-first): <pm> run sync-manifest
+
+Add more later: run /areca-quickstart again. It skips what is done.
+Going live: see the areca-sdk skill, references/production.md (Dokploy builds and the health route).
+Docs: https://github.com/ekozf/areca-cms
+```
+
+Remove lines that do not apply. Mention any step you skipped and why.
+
+## Secrets
+
+- Never ask for a token, key or password in chat. If the user pastes one anyway, do not repeat it. Tell them to remove it from the chat and rotate it in the CMS.
+- Tokens live in `.env.local`. Only the user pastes them there, or runs `areca init` in their terminal.
+- Check that a value is set with the length check. Never print the value. Never write it into a file that Git tracks (`.env.example` has empty values only).
+- The site token and the schema token are server secrets. Never use a `VITE_`, `NEXT_PUBLIC_` or `PUBLIC_` prefix for them.
+- A personal MCP key (`areca_mcp_…`) follows the same rules. OAuth needs no key, so prefer it.
+
+## Re-run mode
+
+Use this when `areca.config.ts`, the SDK dependency or `areca.gen.ts` already exists.
+
+1. Do not install the SDK again. Do not run `areca init` again. Do not overwrite `.env.local`.
+2. Show the current state: collections and sections from `areca.config.ts`, or from `get_site_info` if MCP is connected. Note the languages and the publishing mode.
+3. Decide the schema source from the header of `areca.config.ts`:
+   - It has the header `// Generated by \`areca manifest pull\`.`: **MCP-first**. Change the schema with MCP (`upsert_collection`, `upsert_global`, `set_site_languages`) after the approval. Then run `<pm> run content:sync </dev/null`.
+   - Anything else: **code-first**. Edit `areca.config.ts` after the approval. Then run `<pm> run sync-manifest` (needs `ARECA_SCHEMA_TOKEN`), then `<pm> run content:pull`.
+   This is how to read the `areca-mcp` advice "if the site syncs its schema from code, prefer areca.config.ts": the header tells you which kind of site it is. Do not switch a site from one kind to the other without asking the user.
+4. Ask what the user wants to add or change. Typical requests: a new collection (for example vacancies), a new field, a new language, a new page.
+5. For new or changed parts, go through the same flow: the interview questions that apply, the approval gate (step 3), the schema (step 4b), the wiring (step 5), and a release (step 6). Skip the parts that are done.
+6. For removals, fields that hold content, or languages: explain what is lost. Get explicit confirmation before any change.
+7. For an existing live site, follow the note in the ground rules. Use hidden collections (`enabled: false`) or a separate site for experiments.
+8. Finish with the step 7 summary, only for the parts that changed.