@areca-cms/skills 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@areca-cms/skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.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",
+    "cms",
+    "agent-skills",
+    "skills",
+    "mcp",
+    "claude-code",
+    "codex",
+    "cursor"
+  ],
+  "homepage": "https://github.com/ekozf/areca-cms/tree/master/packages/skills#readme",
+  "bugs": {
+    "url": "https://github.com/ekozf/areca-cms/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ekozf/areca-cms.git",
+    "directory": "packages/skills"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "areca-skills": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.4",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.1"
+  },
+  "scripts": {
+    "clean": "node --eval \"for (const d of ['dist', 'skills']) require('node:fs').rmSync(d, { recursive: true, force: true })\"",
+    "build": "pnpm run clean && tsc && node --eval \"const fs = require('node:fs'); fs.chmodSync('dist/cli.js', 0o755); fs.cpSync('../../skills', 'skills', { recursive: true })\"",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }

package/skills/areca-mcp/SKILL.md

@@ -0,0 +1,72 @@
+---
+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.1.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).
+
+## Connect
+
+- **Connector URL:** `https://<cms-host>/api/mcp/<site-slug>`. The user copies it from the site's **Connect AI** page in the CMS. Don't guess it: if `ARECA_CMS_URL` and the `siteKey` in `areca.config.ts` exist, it is `${ARECA_CMS_URL}/api/mcp/${siteKey}`. Confirm that with the user.
+- **Transport:** Streamable HTTP (stateless, JSON responses). Suggested server name: `areca-<site-slug>`.
+- **Auth:** OAuth 2.1 in the browser. Add only the URL, and the client opens a sign-in and consent page on first use. No secret goes in config.
+- Claude Code: `claude mcp add --transport http areca-<slug> <url>`, then `/mcp` > Authenticate.
+- Other clients: see [references/connect.md](references/connect.md). It covers Cursor, VS Code/Copilot, Codex, OpenCode, Gemini, Windsurf, ChatGPT, the Claude app and more, plus personal keys (`areca_mcp_…`) for clients without OAuth.
+
+## 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.
+
+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.
+
+## Workflow and vocabulary
+
+```
+create_entry/update_entry -> draft
+mark_ready (owner)        -> ready     approved for the next release, NOT live yet
+go_live (go-live perm.)   -> live      builds and deploys every ready change
+schedule_entry            -> scheduled goes live at a set time (also publishes other ready changes)
+```
+
+- `status`: `draft` | `ready` | `scheduled` | `archived`. To answer "what is live" use the flags: `live` (on the production site now), `pendingRelease` (approved changes waiting for the next go live) and `editedSinceReady`.
+- Drafts are safe. Nothing changes the live site until an entry is marked ready **and** a go live happens.
+- Only call `mark_ready`, `go_live`, `schedule_entry`, `rollback`, `delete_*` or `archive_entry` when the user explicitly asks.
+- Writes return a `version`. Pass it as `expectedVersion` on the next `update_entry`. On a version conflict, call `get_entry`, reapply the change and retry.
+- 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
+
+| Role | Can |
+| --- | --- |
+| 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) |
+
+## Writing content
+
+- **Rich text = Markdown**, never HTML (HTML tags show up as literal text). Use `##`, `###` and `####` headings, lists, links, tables and `>` quotes. Images go in as `![alt](asset:<assetId>)`.
+- **Images:** call `upload_asset_from_url({ url, altText })` with a *direct* file link (JPEG, PNG, WebP, GIF or PDF, up to 20 MB), then use the returned `assetId` in image fields, `seo.ogImage` and Markdown. Always include alt text. If an upload fails, don't try other URLs. Ask the user for a working link, or continue without the image.
+- **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.
+
+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).
+
+## Errors
+
+Tool errors come back as normal results with `isError: true` and a message that tells you the next step. Follow it. Common ones:
+
+- `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.
+- `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/connect.md

@@ -0,0 +1,66 @@
+# Connecting clients to the Areca MCP server
+
+The examples use `NAME` = `areca-<site-slug>` and `URL` = `https://<cms-host>/api/mcp/<site-slug>`. Every client signs in with OAuth on first use: a browser opens, the user signs in to Areca, picks what the AI may do and approves. Only owners and agency admins see the "Allow going live" box, and it is off by default.
+
+## Coding agents (project config, URL only, safe to commit)
+
+| Client | File | Entry |
+| --- | --- | --- |
+| Claude Code | `.mcp.json` | `{"mcpServers":{"NAME":{"type":"http","url":"URL"}}}`. Or `claude mcp add --transport http NAME URL`, then `/mcp` > Authenticate. |
+| Cursor | `.cursor/mcp.json` | `{"mcpServers":{"NAME":{"url":"URL"}}}` |
+| VS Code / GitHub Copilot | `.vscode/mcp.json` | `{"servers":{"NAME":{"type":"http","url":"URL"}}}` |
+| Copilot CLI | `.mcp.json` | `{"mcpServers":{"NAME":{"type":"http","url":"URL"}}}` |
+| Codex (CLI/IDE/app) | `.codex/config.toml` (trusted projects) or `~/.codex/config.toml` | `[mcp_servers.NAME]` then `url = "URL"`. Then run `codex mcp login NAME`. |
+| OpenCode | `opencode.json` | `{"mcp":{"NAME":{"type":"remote","url":"URL","enabled":true}}}`. Then run `opencode mcp auth NAME`. |
+| Gemini CLI / Qwen Code | `.gemini/settings.json` / `.qwen/settings.json` | `{"mcpServers":{"NAME":{"httpUrl":"URL"}}}`. Then run `/mcp auth NAME`. |
+| Roo Code | `.roo/mcp.json` | `{"mcpServers":{"NAME":{"type":"streamable-http","url":"URL"}}}` |
+| Kiro | `.kiro/settings/mcp.json` | `{"mcpServers":{"NAME":{"url":"URL"}}}` |
+| Factory Droid | `.factory/mcp.json` | `{"mcpServers":{"NAME":{"type":"http","url":"URL"}}}` |
+| Junie | `.junie/mcp/mcp.json` | `{"mcpServers":{"NAME":{"url":"URL"}}}` |
+| Amp | `.amp/settings.json` | `{"amp.mcpServers":{"NAME":{"url":"URL"}}}` |
+| Continue | `.continue/mcpServers/NAME.yaml` | `name: NAME`, `version: 0.0.1`, `schema: v1`, `mcpServers: [{name: NAME, type: streamable-http, url: URL}]` |
+| Antigravity / Kilo Code / Trae / Warp / OpenHands | MCP settings UI | Add a remote (Streamable HTTP) server with the URL |
+
+These clients only have a user-level config. Merge the entry there:
+
+| Client | File | Entry |
+| --- | --- | --- |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `{"mcpServers":{"NAME":{"serverUrl":"URL"}}}` |
+| Cline | Cline > MCP Servers > Configure (`cline_mcp_settings.json`) | `{"mcpServers":{"NAME":{"type":"streamableHttp","url":"URL"}}}` |
+| Zed | `~/.config/zed/settings.json` | `{"context_servers":{"NAME":{"url":"URL"}}}` |
+| Augment | `~/.augment/settings.json` | `{"mcpServers":{"NAME":{"type":"http","url":"URL"}}}` |
+| Goose | `~/.config/goose/config.yaml` | `extensions: { NAME: { name: NAME, type: streamable_http, uri: URL, enabled: true } }` |
+
+When you edit an existing config file, merge into the existing object. Don't replace other servers.
+
+## Chat apps
+
+- **Claude (web, desktop, mobile):** Customize > Connectors > + Add > Add custom connector. Name it after the site, paste the URL, then Add > Connect. Sign in and approve.
+- **ChatGPT:** Settings > Apps (or Connectors) > Create. If Create isn't there, turn on Developer mode under Advanced first. Paste the URL as the MCP server URL, set Authentication to OAuth, then Create. Sign in and approve.
+- **Any other app:** paste the URL wherever it asks for an MCP server, remote connector or custom connector. If it needs JSON, use `{"mcpServers":{"NAME":{"url":"URL"}}}`.
+
+## Personal keys (scripts, CI, clients without OAuth)
+
+- The user creates one under Connect AI > Advanced: personal keys > Create AI key. It lasts 30 days, 90 (default), 1 year or never, with optional "Allow going live". It is shown once, and each user can have up to 20 per site.
+- Format: `areca_mcp_…`. Send it as the header `Authorization: Bearer <key>` to either the connector URL or `https://<cms-host>/api/mcp`, where the key decides the site.
+- Keep keys out of git. Reference an env var (e.g. `ARECA_MCP_KEY`) where the client supports it.
+  - Claude Code: `claude mcp add --transport http NAME URL --header "Authorization: Bearer $ARECA_MCP_KEY"`
+  - JSON clients: `"headers": {"Authorization": "Bearer ${ARECA_MCP_KEY}"}` (the interpolation syntax depends on the client)
+  - stdio-only clients: `npx -y mcp-remote URL --header "Authorization:${ARECA_AUTH}"` with env `ARECA_AUTH="Bearer <key>"`
+
+## OAuth details (for custom clients)
+
+- An unauthenticated request returns 401 with `WWW-Authenticate: Bearer resource_metadata="<cms>/.well-known/oauth-protected-resource/api/mcp/<slug>"`.
+- The authorization server metadata is at `<cms>/.well-known/oauth-authorization-server/api/auth`. Dynamic client registration uses `POST <cms>/api/auth/oauth2/register`. Requests need PKCE S256 and `resource=<connector URL>`, and the scope must include `mcp`; add `offline_access` for refresh tokens.
+- Access tokens (`areca_at_`) last 1 hour. Refresh tokens (`areca_rt_`) rotate on use and last 90 days from their last use. A connection idle for 90 days is revoked. The role is checked again on every request.
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| 401 "Sign in to connect" | Run the client's auth step (e.g. `/mcp`, `codex mcp login`) |
+| 401 "Key is for a different site" | Use the connector URL of the key's site, or create a key there |
+| 401 "This app is no longer connected" | Someone disconnected it in Connect AI. Reconnect. |
+| 403 `mfa_required` | The agency admin must enable 2FA in Account settings |
+| 404 "Site not found" | Wrong site slug in the URL |
+| Go-live tools missing | Reconnect with "Allow going live" ticked (owners only), or ask an owner to press Go live |

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

@@ -0,0 +1,69 @@
+# Field formats, SEO, limits and errors
+
+## Field values (write → read)
+
+| Type | Write | Read back |
+| --- | --- | --- |
+| `text` | Plain text, up to 1,000 chars | same |
+| `textarea` | Plain text with line breaks, up to 50,000 chars, no Markdown | same |
+| `richtext` | Markdown string (see below): at most 200,000 text chars, 20,000 nodes, depth 32 | Markdown |
+| `image` | asset id from `list_assets` / `upload_asset_from_url` | `{ assetId, url, alt }` or `null` |
+| `reference` | entry id from `list_entries` of the referenced collection | `{ entryId }` or `null` |
+| `date` | `YYYY-MM-DD` | same |
+| `datetime` | ISO 8601 with offset, e.g. `2026-10-10T09:00:00+02:00` | same |
+| `select` | one listed option, spelled exactly | same |
+| `slug` | `a-z`, `0-9` and `-`, unique in the collection, up to 200 chars | same |
+| `boolean` / `number` / `url` | `true`/`false` / JSON number / absolute http(s) URL | same |
+
+Unknown field keys are refused, and the error lists the valid ones. Entry data is limited to 1 MB.
+
+**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.
+
+## Rich text Markdown
+
+- Use `##` for sections and `###` or `####` for subsections. Other heading levels are clamped.
+- Separate paragraphs with a blank line. `**bold**`, `*italic*`, `[link](https://…)`, lists, `>` quotes and tables all work.
+- Images: `![alt text](asset:<assetId>)`. The asset must be in this client's Library. Read-back keeps the `asset:` form, so the text can be sent again as is.
+- Never send HTML: it is not rendered, and the tags end up as visible text. A full https image URL works for images, but uploaded assets are better.
+
+## SEO object (`seo` on create/update)
+
+| Key | Limit | Guidance |
+| --- | --- | --- |
+| `title` | 300 | aim for 50-60 chars |
+| `description` | 1,000 | aim for 140-160 chars |
+| `focusKeyphrase` | 200 | the search phrase the entry targets |
+| `summary` | 2,000 | 2-3 sentences that answer the main question |
+| `keyTakeaways` | 12 × 500 | 3-5 self-contained points |
+| `faq` | 20 × `{question (500), answer (3,000)}` | only questions the body really answers |
+| `ogImage` | asset id | share image, ideally 1200×630 |
+| `ogTitle`, `ogDescription` | 300 / 1,000 | fall back to title and description |
+| `canonicalUrl` | URL | only when the page duplicates another URL |
+| `noindex`, `nofollow` | boolean | |
+| `twitterCard` | `summary_large_image` or `summary` | |
+| `schemaType` | `Article`, `BlogPosting`, `NewsArticle` or `WebPage` | |
+| `about` | 12 × `{name, sameAs?}` | entities the entry is about |
+| `author` | `{name, url?, bio?}` | |
+| `jsonLd` | 20,000 chars of JSON | usually leave unset, because the CMS builds the main node |
+
+Unknown SEO keys are refused. There is no SEO-generation tool, so you write these values yourself.
+
+## Uploads
+
+`upload_asset_from_url` accepts JPEG, PNG, WebP, GIF and PDF (detected from the bytes) up to 20 MB. URLs must be public `http`/`https` on ports 80, 443, 8080 or 8443, with no credentials. Private and loopback addresses are refused, and there is a 15 s timeout with at most 3 redirects. Use a direct file link, not an HTML page.
+
+## Errors
+
+| Message starts with | Do |
+| --- | --- |
+| `Validation failed.` | Call `get_collection_schema`, fix the listed fields, retry |
+| `This entry changed since you last read it` | Call `get_entry`, reapply the change, retry with the new `version` |
+| slug message | Pick another unique slug |
+| `This asset is still used by N item(s)` | Remove it from those items first |
+| `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`) |
+| `Something went wrong on the Areca server (ref …)` | Nothing is confirmed saved. Retry once, then report the ref. |
+
+HTTP: `401` = token or key invalid, expired, revoked or for another site, so reconnect. `403 mfa_required` = the agency admin must enable 2FA. `429` = wait `Retry-After` seconds (120/min per credential, plus 600/min per client IP when the CMS trusts its proxy).

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

@@ -0,0 +1,65 @@
+# Areca MCP tools
+
+`*` means required. Access: **all** = every role, **owner** = owners and agency admins, **go-live** = also needs "Allow going live" on the connection or key, **agency** = agency admins only. Tools a caller cannot use are not listed by the server.
+
+## Site and schema
+
+| 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 |
+
+## 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_revisions` | all | `id*` | Revision id, note, createdAt, createdBy |
+| `get_preview_url` | all | `id*` | `{ url }`, signed, about 1 hour. Fails without a site production URL. |
+
+## Workflow
+
+| Tool | Access | Inputs | Effect |
+| --- | --- | --- | --- |
+| `mark_ready` | owner | `id*` | Approves the current draft for the next release. Not live yet. |
+| `unpublish_entry` | owner | `id*` | Takes it out of the release and back to draft. Removed from the live site at the next go live. |
+| `archive_entry` | owner | `id*` | Archives it. Removed from the live site at the next go live. |
+| `cancel_schedule` | owner | `id*` | Clears the scheduled time |
+| `delete_entry` | owner | `id*` | Deletes permanently. Destructive. |
+| `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 |
+
+## Library (assets)
+
+| Tool | Access | Inputs | Returns |
+| --- | --- | --- | --- |
+| `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 |
+| `delete_asset` | owner | `id*` | Refused while the asset is in use |
+
+## Publishing
+
+| Tool | Access | Inputs | Returns |
+| --- | --- | --- | --- |
+| `get_release_status` | all | none | `publishingMode`, `live`, `demo`, `activeJob`, `pendingCount`, `pendingChanges[]` |
+| `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`. |
+| `rollback` | go-live | `publicationId*` | Queues a rollback to an earlier publication |
+| `cancel_build` | go-live | `jobId*` | Cancels a queued build |
+
+## Content types (agency)
+
+| 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. |
+| `delete_collection` | agency | `key*` | Deletes the collection and its entries. Destructive. |
+
+## 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-sdk/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: areca-sdk
+description: Connects a website project to Areca CMS with the @areca-cms/site-sdk package. Covers setup, tokens and env vars, areca.config.ts collections and field types, the areca CLI (init, manifest push/pull, pull, run), reading pulled content, rich text, SEO head tags, draft preview routes and Go-live builds. Use when a project imports @areca-cms/site-sdk, has an areca.config.ts, mentions ARECA_* env vars, or the user wants to add, render or deploy Areca CMS content.
+license: MIT
+metadata:
+  version: "0.1.0"
+---
+
+# Areca site SDK
+
+`@areca-cms/site-sdk` connects a Node.js website to one site in an Areca CMS. The schema is declared in code and pushed to the CMS. Editors write and publish there, and the website pulls the published snapshot as JSON at build time. Visitor requests never call the CMS.
+
+Requirements: Node >= 22.6 (24 LTS recommended), ESM only. It works with any framework because the core has no React dependency.
+
+## Mental model
+
+1. `areca.config.ts` declares **collections** (content types) and their **fields**.
+2. `areca manifest push` sends that schema to the CMS (needs the schema token).
+3. Editors create entries in the CMS and **Go live**, which creates an immutable **publication** (snapshot).
+4. `areca pull` downloads the publication into `src/generated/content/`.
+5. Server code reads it with `readContent()` from `@areca-cms/site-sdk/pull`.
+
+There are no singletons, blocks, locales, typegen, webhooks or runtime query API. A "page" is an entry in a collection. Filter, sort and paginate the returned arrays in your own code.
+
+## Setup
+
+```bash
+pnpm add @areca-cms/site-sdk          # or npm install / yarn add
+pnpm exec areca init                  # interactive; writes config, env files, scripts
+# non-interactive:
+pnpm exec areca init --cms-url https://cms.example.com --token "$ARECA_SITE_TOKEN" --site-key acme-site --yes
+```
+
+`init` writes `areca.config.ts`, `.env.example`, `.env.local` (`ARECA_CMS_URL`, `ARECA_SITE_TOKEN`), `.gitignore` entries, `src/generated/content/manifest.json`, and the package scripts `sync-manifest` and `content:pull`. It also wraps `dev` in `areca run --`. Use `--force` to overwrite an existing config. `--out` and `--config` change the paths.
+
+| 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_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 |
+
+The CLI loads `.env.local` and then `.env`, and existing process env wins. Library imports do **not** load env files.
+
+**Security:** both tokens are server secrets. Never put them in browser code or behind a `VITE_`, `NEXT_PUBLIC_` or `PUBLIC_` prefix, and never commit them. Only import `readContent` and the client in server or build code.
+
+## Declare content
+
+```ts
+// areca.config.ts
+import { defineSiteContent } from "@areca-cms/site-sdk";
+
+export default defineSiteContent({
+  siteKey: "acme-site", // must match the CMS site key
+  collections: {
+    articles: {
+      route: "/blog/$slug", // documentation only; build the route yourself
+      label: "Articles",
+      fields: [
+        { key: "title", label: "Title", type: "text", required: true },
+        { key: "slug", label: "Slug", type: "slug", required: true },
+        { key: "body", label: "Body", type: "richtext" },
+        { key: "cover", label: "Cover", type: "image" },
+        { key: "category", label: "Category", type: "select", options: ["news", "guides"] },
+        { key: "author", label: "Author", type: "reference", collection: "authors" },
+        { key: "startsAt", label: "Starts", type: "datetime" },
+        { key: "endsAt", label: "Ends", type: "datetime", after: "startsAt" },
+      ],
+    },
+  },
+});
+```
+
+- Field types: `text`, `textarea`, `richtext`, `image`, `date`, `datetime`, `select` (`options`), `reference` (`collection`), `slug`, `boolean`, `number`, `url`. Optional per field: `required`, `description`, `after` (date or datetime key this must be on or after).
+- Keys match `^[A-Za-z][A-Za-z0-9_-]{0,63}$`. Collection keys must be unique case-insensitively. Reserved: `manifest`, `constructor`, `prototype`, `__proto__`, and Windows device names (`con`, `prn`, `aux`, `nul`, `com1`, `lpt1`, ...).
+- 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`. Without a TTY it needs `--yes` if the config already has collections.
+
+## CLI
+
+```text
+areca init [--cms-url <url>] [--token <t>] [--site-key <key>] [--out <dir>] [--config <path>] [--yes] [--force]
+areca manifest push [config]             # needs ARECA_SCHEMA_TOKEN (+ URL and site token)
+areca manifest pull [--config <path>] [--yes]
+areca pull [--out <dir>] [--publication <id>]   # default out: src/generated/content
+areca run -- <command>                   # run a command with .env.local/.env loaded
+```
+
+`areca sync-manifest` is a deprecated alias for `manifest push`. Run the CLI as `pnpm exec areca`, `npx areca` or `yarn areca`. A pull fails until something has gone live in the CMS. To pull before every build, add `"prebuild": "areca pull"`.
+
+## Read content (server or build only)
+
+```ts
+import { readContent, readContentManifest } from "@areca-cms/site-sdk/pull";
+import type { ImageValue, ReferenceValue, RichTextValue, SnapshotEntry } from "@areca-cms/site-sdk";
+
+type Article = SnapshotEntry & {
+  data: { title: string; body: RichTextValue; cover: ImageValue | null; author: ReferenceValue | null };
+};
+
+const dir = "src/generated/content";
+const manifest = readContentManifest(dir); // capture once for consistent multi-collection reads
+const articles = readContent<Article>(dir, "articles", manifest);
+const post = articles.find((a) => a.slug === slug);
+```
+
+- Entry: `{ id, slug, publishedAt, data, seo? }`. The field values live in `data`. You write the types yourself because there is no codegen.
+- `ImageValue` = `{ url, width|null, height|null, alt, mimeType }`, where `url` is absolute on the CMS origin. `ReferenceValue` = `{ collection, slug, id }`. Optional and image fields can be `null` or missing, so check them.
+- `readContent` reads files at runtime, so ship `src/generated/content/` (including `.publications/`) with the server build or container. For TanStack Start, call it inside a `createServerFn` handler, never in route or component code.
+
+## Rich text
+
+```tsx
+import { Markdown } from "@tanstack/markdown/react"; // pnpm add @tanstack/markdown@1.0.0 (match the SDK)
+import { richTextComponents } from "@areca-cms/site-sdk/rich-text-react";
+import { richTextDocument } from "@areca-cms/site-sdk";
+
+<Markdown components={richTextComponents()}>{richTextDocument(article.data.body)}</Markdown>
+```
+
+`RichTextValue` = `{ document, markdown, html, json }`. Outside React, use `richTextHtml(value)`, which is trusted CMS HTML, or `richTextMarkdown(value)`. Keep `img { max-width: 100% }` and don't force `width: 100%`, because editors set image sizes.
+
+## SEO
+
+- TanStack Router: `head: ({ loaderData }) => seoHead(loaderData?.post.seo, { titleTemplate: "%s · Acme", siteName: "Acme" })`.
+- Astro or plain SSR: `seoHeadHtml(entry.seo, options)` from `@areca-cms/site-sdk/seo` returns an escaped HTML string. `seoJsonLd(seo)` returns safe JSON-LD strings.
+- `seo` is optional. When `seo.summary`, `keyTakeaways` or `faq` exist, render them visibly on the page so the content matches the JSON-LD.
+
+## Preview, Go live and the client
+
+Read [references/production.md](references/production.md) when the user needs any of these:
+
+- A draft preview route: `getPreviewEntry` and `previewHeaders` at `/__preview/<collection>/<slug>?token=`.
+- The production health route that Go live waits for.
+- Docker or CI builds with `ARECA_SNAPSHOT_ID`.
+- The CMS settings needed: production URL, deployment target, publishing mode.
+- Direct use of `createArecaClient` and error messages.
+
+Read [references/api.md](references/api.md) for every export, type and signature.
+
+## Rules
+
+- Change the schema in `areca.config.ts` and then `manifest push`. Don't hand-edit generated content.
+- Never import `@areca-cms/site-sdk/pull` or a client with tokens into browser bundles.
+- Exclude `/__preview/*` from prerendering and caching.
+- The SDK doesn't create CMS sites or tokens. An agency admin creates the site in the CMS. Ask the user for the URL, site key and tokens instead of guessing them.
+- To edit content (not code) through an AI, use the Areca MCP server (see the `areca-mcp` skill).

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

@@ -0,0 +1,68 @@
+# @areca-cms/site-sdk API reference
+
+ESM only. Import paths and their exports:
+
+## `@areca-cms/site-sdk`
+
+| Export | Signature | Notes |
+| --- | --- | --- |
+| `defineSiteContent` | `<T extends SiteContentConfig>(config: T) => T` | Identity helper for `areca.config.ts` default export |
+| `manifestFromConfig` | `(config: SiteContentConfig) => SiteManifest` | Validates identifiers and duplicates, returns `{ collections }` |
+| `createArecaClient` | `(options?: { cmsUrl?; siteToken?; schemaToken? }) => ArecaClient` | Falls back to `ARECA_CMS_URL`, `ARECA_SITE_TOKEN`, `ARECA_SCHEMA_TOKEN`; URL and site token required at creation |
+| `getPreviewEntry` | `({ token: string; client?: ArecaClient }) => Promise<PreviewResult>` | `PreviewResult` = `{ collection, slug, entry }`. Needs `ARECA_CMS_URL` and `ARECA_SITE_TOKEN` (or pass `client`). |
+| `previewHeaders` | `() => { 'X-Robots-Tag': 'noindex, nofollow'; 'Cache-Control': 'no-store' }` | Apply to preview responses |
+| `seoHead` | `(seo: SeoMeta \| null \| undefined, options?: SeoHeadOptions) => { title, meta, links, scripts }` | TanStack Router `head()` shape |
+| `seoHeadHtml` | `(seo, options?) => string` | Escaped `<head>` HTML |
+| `seoJsonLd` | `(seo) => string[]` | Escaped JSON-LD strings |
+| `richTextDocument` | `(value: RichTextValue \| null \| undefined) => MarkdownDocument` | Parses `markdown` for old snapshots; empty root for null |
+| `richTextMarkdown` | `(value) => string` | `''` when empty |
+| `richTextHtml` | `(value) => string` | Static HTML; trusted CMS output only |
+
+`SeoHeadOptions` = `{ titleTemplate?: string /* contains %s */ | ((title: string) => string); siteName?: string }`.
+
+`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 |
+| `fetchSnapshot(opts?: { publicationId?: string }): Promise<Snapshot>` | `GET /api/sites/snapshot/current[?publicationId=]` | site token |
+| `fetchPreview(token: string): Promise<PreviewResult>` | `GET /api/sites/preview?token=` | signed preview token |
+
+Types: `ArecaClient`, `ArecaClientOptions`, `SiteContentConfig`, `CollectionConfig` (`{ route; label?; fields: Field[] }`), `Field` (`{ key; label; type: FieldType; required?; options?; collection?; description?; after? }`), `FieldType`, `SiteManifest`, `Snapshot` (`{ publicationId, siteKey, createdAt, hash, collections: Record<string, SnapshotEntry[]> }`), `SnapshotEntry` (`{ id, slug, publishedAt: string | null, data: Record<string, unknown>, seo?: SeoMeta }`), `ImageValue`, `ReferenceValue`, `RichTextValue`, `SeoMeta`, `PreviewResult`, `PulledContentManifest`, `HeadMeta`, `HeadLink`, `HeadScript`, `SeoHeadOptions`, `SeoHeadResult`.
+
+## `@areca-cms/site-sdk/pull` (Node only)
+
+| Export | Signature | Notes |
+| --- | --- | --- |
+| `pullContent` | `({ outDir: string; client?: ArecaClient; publicationId?: string }) => Promise<Snapshot>` | Writes `outDir/.publications/publication-<random>/<collection>.json`, then atomically swaps `manifest.json`, which records the `publicationId`. Defaults `publicationId` to `ARECA_SNAPSHOT_ID`. A failed pull keeps the previous generation. |
+| `readContentManifest` | `(outDir: string) => PulledContentManifest` | `{ publicationId, hash, createdAt, collections counts, ... }` |
+| `readContent` | `<T = SnapshotEntry>(outDir: string, collectionKey: string, manifest?: PulledContentManifest) => T[]` | Throws `No content file for collection "x" ... Run \`areca pull\` first.` |
+
+Type: `PullContentOptions`.
+
+## Other subpaths
+
+- `@areca-cms/site-sdk/seo`: `seoHead`, `seoHeadHtml`, `seoJsonLd` 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`.
+
+## SeoMeta (snapshot `entry.seo`, already resolved with fallbacks)
+
+```ts
+{
+  title: string; description: string | null; canonicalUrl: string | null;
+  robots: { index: boolean; follow: boolean; content: string };
+  focusKeyphrase: string | null;
+  openGraph: { type: 'article' | 'website'; title; description; url; siteName; image: ImageValue | null; publishedTime; modifiedTime };
+  twitter: { card: 'summary' | 'summary_large_image'; title; description; image: ImageValue | null };
+  author: { name; url; bio } | null;
+  summary: string | null; keyTakeaways: string[];
+  faq: { question; answer }[]; about: { name; sameAs }[];
+  jsonLd: Record<string, unknown>[]; // ready-to-embed objects
+}
+```
+
+`seo` is missing on snapshots from older CMS versions. `seoHead` and `seoHeadHtml` then return empty head data.
+
+`PulledContentManifest` = `{ publicationId, hash, createdAt, collections: Record<string, number>, generation? }`.

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

@@ -0,0 +1,88 @@
+# Preview, Go-live builds and errors
+
+## CMS settings the site needs (asked of an owner or agency admin)
+
+- **Production URL** (site settings). This enables preview links: the CMS opens `<productionUrl>/__preview/<collection>/<slug>?token=<signed>`.
+- **Publishing mode**: `Demo` skips deploy and health checks, which is good for trying things out. `Production` needs a deployment target (Dokploy) and a **health check URL**.
+- **Site key and tokens**: Settings > Developer. Rotating a token invalidates the old one immediately.
+
+## Draft preview route
+
+Server-side only. The preview token is signed, valid for about 1 hour, and separate from the site token. Never log, cache or store it.
+
+```ts
+import { getPreviewEntry, previewHeaders } from "@areca-cms/site-sdk";
+
+// route: /__preview/$collection/$slug  (read ?token= from the URL)
+try {
+  const { collection, slug, entry } = await getPreviewEntry({ token });
+  // render `entry` (same shape as SnapshotEntry) with the normal template
+  // and set every header from previewHeaders() plus <meta name="robots" content="noindex">
+} catch (error) {
+  // Plain Error, no status field. The message holds the status:
+  // "Failed to fetch preview (401): …" => link expired or invalid, ask for a new one
+  // "(404)" => the entry no longer exists
+}
+```
+
+`getPreviewEntry` needs `ARECA_CMS_URL` and `ARECA_SITE_TOKEN` at runtime. Exclude `/__preview` from prerendering and CDN caching. In TanStack Start, wrap the fetch in a `createServerFn` handler.
+
+## Health route (Production mode)
+
+Go live waits until the deployed site reports the publication it was built from:
+
+```ts
+// GET /api/health -> { ok: true, publicationId } or 503
+import { readContentManifest } from "@areca-cms/site-sdk/pull";
+
+export function health() {
+  try {
+    const { publicationId } = readContentManifest("src/generated/content");
+    if (!publicationId) throw new Error("missing");
+    return Response.json({ ok: true, publicationId });
+  } catch {
+    return Response.json({ ok: false }, { status: 503 });
+  }
+}
+```
+
+Set the CMS health check URL to this route, e.g. `https://www.example.com/api/health`.
+
+## Builds (Docker / CI)
+
+- Pull **before** the build: `"prebuild": "areca pull"` or an explicit step.
+- The CMS deploy passes the build arg `ARECA_SNAPSHOT_ID`, and `areca pull` fetches exactly that publication. Declare the arg right before the pull step so the cache is busted for each release.
+- Pass `ARECA_SITE_TOKEN` as a build secret, not as an ARG or ENV in the image.
+- Copy `src/generated` into the runtime image when the server reads content at runtime.
+
+```dockerfile
+ARG ARECA_CMS_URL
+ARG ARECA_SNAPSHOT_ID
+RUN --mount=type=secret,id=ARECA_SITE_TOKEN,required=true \
+    ARECA_SITE_TOKEN="$(cat /run/secrets/ARECA_SITE_TOKEN)" pnpm build   # build runs areca pull via prebuild
+# runtime stage:
+COPY --from=build /app/src/generated ./src/generated
+```
+
+## Client and errors
+
+```ts
+import { createArecaClient } from "@areca-cms/site-sdk";
+import { pullContent } from "@areca-cms/site-sdk/pull";
+
+const client = createArecaClient({ cmsUrl, siteToken }); // or env vars
+await pullContent({ outDir: "src/generated/content", client });
+```
+
+| Error | Fix |
+| --- | --- |
+| `Missing ARECA_CMS_URL` / `ARECA_SITE_TOKEN` | Set them in env or `.env.local` (CLI) |
+| Missing `ARECA_SCHEMA_TOKEN` on push | Add it to the authoring env only |
+| `401` | Wrong or rotated token, or the wrong token type (schema vs site) |
+| `404` / no publication on pull | Nothing is live yet. Go live in the CMS, then pull again. |
+| `429` | 300 requests/min per token. Wait for `Retry-After`. |
+| `400` / `413` on push | Invalid schema, or the manifest is over 256 KiB |
+| `No content file for collection` | Run `areca pull`, then check the collection key |
+| `Unsafe collection or field identifier` | Rename the key to match `^[A-Za-z][A-Za-z0-9_-]{0,63}$` |
+| `Expected publication X, received Y` | Pinned pull mismatch. Check `ARECA_SNAPSHOT_ID`. |
+| TS config import fails | Use Node 24, or run through `tsx` |