@areca-cms/skills 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to `@areca-cms/skills`.
 
+## 0.2.0 (2026-10-11)
+
+### Features
+
+- copy media into client sites on areca pull (da09a0c)
+
 ## 0.1.1 (2026-10-10)
 
 No user-facing changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@areca-cms/skills",
-  "version": "0.1.1",
+  "version": "0.2.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.1.1"
+  version: "0.2.0"
 ---
 
 # Areca MCP

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

@@ -24,7 +24,7 @@ Unknown field keys are refused, and the error lists the valid ones. Entry data i
 - 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.
+- Never send HTML: it is not rendered, and the tags end up as visible text. A full https image URL is copied into the Library on save; if the copy fails it stays external and the result lists it in `warnings`. Uploaded assets are still better, because you set their alt text.
 
 ## SEO object (`seo` on create/update)
 

package/skills/areca-sdk/SKILL.md

@@ -3,7 +3,7 @@ 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.1"
+  version: "0.2.0"
 ---
 
 # Areca site SDK
@@ -31,7 +31,7 @@ pnpm exec areca init                  # interactive; writes config, env files, s
 pnpm exec areca init --cms-url https://cms.example.com --token "$ARECA_SITE_TOKEN" --site-key acme-site --yes
 ```
 
-`init` writes `areca.config.ts`, `.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.
+`init` writes `areca.config.ts` (including an `assets` block), `.env.example`, `.env.local` (`ARECA_CMS_URL`, `ARECA_SITE_TOKEN`), `.gitignore` entries (content and media folders), `src/generated/content/manifest.json`, and the package scripts `sync-manifest` and `content:pull`. It also wraps `dev` in `areca run --`. Use `--force` to overwrite an existing config. `--out` and `--config` change the paths. Media flags: `--assets-dir <dir>` (default `public/areca`), `--assets-public-path <path>` (only for folders outside `public/`), `--no-assets`. On an existing config, init inserts an `assets` block if there is none.
 
 | Env var | Needed for | Where the user gets it |
 | --- | --- | --- |
@@ -75,15 +75,24 @@ export default defineSiteContent({
 - 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.
+- `areca manifest pull --config areca.config.ts [--yes]` regenerates the config from the CMS. It replaces the whole file and keeps `siteKey` and `assets`. Without a TTY it needs `--yes` if the config already has collections.
+
+### Media (`assets`)
+
+```ts
+assets: { download: true, dir: "public/areca" /*, publicPath: "/areca" */ }, // top level of defineSiteContent
+```
+
+`areca pull` copies every file the content uses (image fields, SEO images, rich-text images and file links) into `dir` and rewrites URLs to `<publicPath>/<name>-<id>.<ext>`, so the deployed site never calls the CMS. `publicPath` is derived for folders under `public/`; set it for others (e.g. SvelteKit `static/`). SEO image URLs become absolute with the site's production URL. `download: false` keeps CMS URLs. The setting is local only; `manifest push` does not send it. A failed download fails the pull without changing the current content.
 
 ## CLI
 
 ```text
-areca init [--cms-url <url>] [--token <t>] [--site-key <key>] [--out <dir>] [--config <path>] [--yes] [--force]
+areca init [--cms-url <url>] [--token <t>] [--site-key <key>] [--out <dir>] [--config <path>]
+           [--assets-dir <dir>] [--assets-public-path <path>] [--no-assets] [--yes] [--force]
 areca manifest push [config]             # needs ARECA_SCHEMA_TOKEN (+ URL and site token)
 areca manifest pull [--config <path>] [--yes]
-areca pull [--out <dir>] [--publication <id>]   # default out: src/generated/content
+areca pull [--out <dir>] [--publication <id>] [--config <path>]   # default out: src/generated/content; media: public/areca
 areca run -- <command>                   # run a command with .env.local/.env loaded
 ```
 
@@ -106,7 +115,7 @@ 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.
+- `ImageValue` = `{ url, width|null, height|null, alt, mimeType }`, where `url` is the local path after `areca pull` (e.g. `/areca/hero-3f2a91c0.jpg`), or an absolute CMS URL with `assets.download: false`. Serve the media folder with the site (it is part of `public/` by default). `ReferenceValue` = `{ collection, slug, id }`. Optional and image fields can be `null` or missing, so check them.
 - `readContent` reads files at runtime, so ship `src/generated/content/` (including `.publications/`) with the server build or container. For TanStack Start, call it inside a `createServerFn` handler, never in route or component code.
 
 ## Rich text

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

@@ -29,13 +29,13 @@ ESM only. Import paths and their exports:
 | `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`.
+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[]>, assets?: SnapshotAsset[], siteUrl? }`), `SnapshotAsset` (`{ id, storageKey, url, filename, mimeType, size }`), `AssetsConfig` (`{ download?, dir?, publicPath? }`), `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. |
+| `pullContent` | `({ outDir: string; client?: ArecaClient; publicationId?: string; assets?: { dir: string; publicPath: string } }) => Promise<PullContentResult>` | With `assets`, downloads media into `dir` (absolute) and rewrites URLs to `publicPath`. Writes `outDir/.publications/publication-<random>/<collection>.json`, then atomically swaps `manifest.json`, which records the `publicationId`. Keeps the current and two previous generations. Defaults `publicationId` to `ARECA_SNAPSHOT_ID`. A failed pull keeps the previous generation. Result (`PullContentResult`) adds `localAssets?` and `warnings`. The `assets` option type is `ResolvedAssets`. |
 | `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.` |
 

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

@@ -54,6 +54,7 @@ Set the CMS health check URL to this route, e.g. `https://www.example.com/api/he
 - 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.
+- Media lands in `public/areca` before the build, so the framework bundles it with other static files. With a custom `assets.dir`, make sure the build or image includes it.
 
 ```dockerfile
 ARG ARECA_CMS_URL