@latellu/atlas-agent-skills 0.1.0 → 0.3.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Work with Atlas CMS from Claude Code: bundles the Atlas MCP server (read/write content via tools) and the atlas-cms skill that teaches agents when and how to use the MCP tools, the @latellu/atlas-sdk delivery/management clients, and the @latellu/atlas-cli type generator.",
   "author": {
     "name": "Latellu",

package/README.md

@@ -33,14 +33,18 @@ Then point your agent at the skill (via `AGENTS.md`, Cursor rules, etc.) and reg
 | Path | Purpose |
 | --- | --- |
 | `skills/atlas-cms/SKILL.md` | Router: shared Atlas concepts + decision table (MCP vs SDK vs CLI) |
-| `skills/atlas-cms/references/` | Per-surface guides: MCP tools, SDK delivery, SDK management, CLI typegen |
+| `skills/atlas-cms/references/` | Per-surface guides: MCP tools, SDK delivery, SDK management, CLI typegen, content authoring (field formats, translations, blocks) |
 | `.mcp.json` | Atlas MCP server config (used by the Claude Code plugin) |
 | `.claude-plugin/` | Claude Code plugin + marketplace manifests |
 | `adapters/other-agents.md` | Setup for non-Claude agents |
 
-## Releasing
+## Releasing (manual)
 
-Bump `version` in `package.json` (and `.claude-plugin/plugin.json`), tag `vX.Y.Z`, push the tag — CI publishes to npm. The Claude Code marketplace resolves the plugin from npm, so users pick up the new version on `claude plugin marketplace update latellu`.
+1. Bump `version` in `package.json` **and** `.claude-plugin/plugin.json` (keep them equal)
+2. `npm publish` (from an authenticated machine)
+3. `git tag vX.Y.Z && git push && git push --tags`
+
+The Claude Code marketplace resolves the plugin from npm, so users pick up the new version on `claude plugin marketplace update latellu`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@latellu/atlas-agent-skills",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Agent skill + MCP configuration for Atlas CMS. Works as a Claude Code plugin and as plain markdown guidance for any AI coding agent (Cursor, Codex, opencode, Gemini CLI, ...).",
   "license": "MIT",
   "author": "Latellu (https://github.com/tenriajeng)",

package/skills/atlas-cms/SKILL.md

@@ -8,35 +8,65 @@ description: Use when integrating with or operating Atlas CMS - fetching entries
 A router, not a knowledge dump. Read the shared concepts below (always), then load
 **only** the reference file for the surface you are actually using.
 
-## Shared concepts
+## Content model
 
-**Content model.** A *workspace* contains *content types* (schemas). A content type has
-*entries* (structured records with a `slug`, a `status`, and a `data` field map). A
-workspace also has *pages*: a page has SEO metadata and an ordered tree of *blocks*
-(`{ id, type, position, data }`). Localized content is delivered as base-locale data plus
-a `translations` array; readers merge a requested locale field-by-field with fallback to
-the base locale.
+A **workspace** is the tenant — it owns everything below and is reached by exactly one
+API key (there is no workspace parameter on any endpoint or tool; scoping is implicit in
+the key).
 
-**Two API key classes**, both sent as the `X-API-Key` header (never `Authorization`):
+- **Content type** — a schema (e.g. "Article") defining fields. Field types: `text`,
+  `textarea`, `richtext`, `number`, `boolean`, `date`, `select` (with options),
+  `image`, `relation`, `content_type_reference`.
+- **Entry** — a record of a content type: `{ id, slug, status, published_at, data }`
+  where `data` is the field map. Lifecycle: `draft → published → archived`, plus
+  `scheduled` (publish at a future time).
+- **Page** — like an entry but composed of ordered **blocks**
+  (`{ id, type, position, data }`) and carrying its own SEO object
+  (`title, description, keywords, og_image, canonical`).
+- **Locale** — content is stored as base-locale data plus a `translations` array.
+  Readers merge the requested locale **field-by-field**; untranslated fields fall back
+  to the base locale. `image`/`relation` values are IDs/slugs, never resolved objects.
+
+## Authentication
+
+Two key classes, both sent as the `X-API-Key` header (never `Authorization: Bearer`):
 
 | Key prefix | Plane | Base path | Can do |
 |---|---|---|---|
-| `atlas_live_*` | Delivery (read) | `/api/v1/public` | Read published entries, pages, media, schema |
+| `atlas_live_*` | Delivery (read) | `/api/v1/public` | Read **published** entries, pages, media, schema |
 | `atlas_mgmt_*` | Management (write) | `/api/v1/manage` | Create/update/publish/delete content, upload media |
 
-- Keys are minted in the dashboard: `cms.atlas.latellu.com/dashboard/api-keys`.
+- Keys are minted at `cms.atlas.latellu.com/dashboard/api-keys` (Developer → API Keys).
 - Default base URL: `https://api.atlas.latellu.com` (override only for self-hosted).
-- **Workspace scoping is implicit in the key.** There is no workspace parameter anywhere;
-  a key reaches exactly one workspace.
-- Management keys act as a service actor bound to the RBAC permissions of the person who
-  created them, further limited by scopes: `content:write`, `content:publish`,
-  `media:write`. A missing scope returns 403 on that specific operation.
-- Production `atlas_live_*` keys only ever see **published** content. Draft content is
-  not reachable through them, regardless of query parameters.
+- The planes are strict: a live key gets 401 on `/manage/*`, a mgmt key gets 401 on
+  `/public/*`. A live key sees **only published content** — no query parameter reveals
+  drafts.
+- Management keys act as a service actor bound to the RBAC permissions of whoever
+  created them, further limited by scopes: `content:write` (create/update/delete),
+  `content:publish` (publish/unpublish/archive/schedule), `media:write` (uploads).
+  A missing scope → 403 on that operation only.
 
 **Safety rule:** never ship an `atlas_mgmt_*` key or the management client in
 browser-delivered code. Management usage is server-side only (API routes, scripts, CI).
 
+## Wire format (applies to every surface)
+
+Every REST response is an envelope: `{ success, message, data?, meta?, code?, errors? }`.
+The SDK and MCP unwrap it, but two payload quirks leak through in places: `entry.data`,
+page `seo`, and block `data` are stored/transported as **JSON strings** (the SDK parses
+them for you; MCP `get_page` does not), and list `meta` uses
+`{ total_data, current_page, page_size, total_pages, next_cursor }`.
+
+Error codes you will actually see: `UNAUTHORIZED` (401 — missing/empty/wrong-class key),
+`FORBIDDEN` (403 — missing scope or RBAC), `NOT_FOUND` (404 — also returned for
+other-workspace resources), `VALIDATION_ERROR` (400 — with field detail),
+`PAGE_TOO_DEEP` (400 — offset pagination past page 1000), and 429 rate limiting
+(back off exponentially; only the SDK management client retries for you).
+
+Pagination limits: `limit` max 100, `page` max 1000; past that, switch to cursor
+pagination (`meta.next_cursor`, opaque — never construct cursors yourself; `total_data`
+is `-1` in cursor mode).
+
 ## Which surface do I use?
 
 | You are... | Use | Read |
@@ -45,11 +75,26 @@ browser-delivered code. Management usage is server-side only (API routes, script
 | Wanting typed content interfaces for the SDK | CLI type generator | [references/cli-typegen.md](references/cli-typegen.md) |
 | Writing content from your own code (scripts, migrations, backends) | SDK management client | [references/sdk-management.md](references/sdk-management.md) |
 | Operating content via MCP tools in this session (`list_entries`, `create_entry`, ...) | Atlas MCP server | [references/mcp.md](references/mcp.md) |
+| Composing any `data` payload — field value formats, translations, page blocks | Authoring guide | [references/authoring.md](references/authoring.md) |
 
 Do **not** read references you don't need. If a task spans surfaces (e.g. "generate
 types, then build the page"), route each sub-task to its own single reference.
 
-## Extending
+Choosing between MCP and the management SDK for writes: MCP is for operating content
+interactively in an agent session (one-off edits, content entry, audits); the SDK is for
+code that outlives the session (migrations, sync jobs, backends) and for anything MCP
+lacks (bulk, scheduling, page unpublish/archive, media delete, **writing translations**,
+per-field validation errors).
+
+## Hard capability boundaries (don't go looking for these)
+
+- **Schema is dashboard-only.** No API, SDK, CLI, or MCP surface creates content types,
+  fields, or block types. "Create a content type" = ask the user to do it in the
+  dashboard, then continue.
+- **No field-value queries.** The public list endpoints filter by `type`/`locale` only —
+  "all articles where category = X" means paging through and filtering client-side.
+- **The management plane is write-only** (no GET endpoints). Reading always needs a
+  live key; a write-then-verify flow therefore needs both keys.
 
 Deep API detail lives at https://docs.atlas.latellu.com — link there rather than
 duplicating endpoint documentation into this skill.

package/skills/atlas-cms/references/authoring.md

@@ -0,0 +1,125 @@
+# Authoring valid content (field formats, translations, page blocks)
+
+What actually gets validated on write, what each field type's value must look like, and
+how to write localized content. Applies to both the management SDK and the MCP write
+tools — read this before composing any `data` payload.
+
+## What the API validates (and what it silently accepts)
+
+On entry create/update the backend enforces exactly four rules:
+
+1. `required` — the field must be present and non-empty. For **richtext**, the Tiptap
+   empty states `""`, `"<p></p>"`, `"<p><br></p>"` count as empty.
+2. `unique` — value must not collide with another entry of the workspace.
+3. `relation` fields — value must be a valid **entry UUID** (or array of UUIDs) that
+   exists in the workspace. Slugs are rejected.
+4. `image` fields — value must be a valid **media UUID** (or array) that exists in the
+   workspace. Upload first (`media.upload` / `upload_media`), then reference the
+   returned `id`.
+
+**Everything else is stored as-is.** A number in a text field, a garbage date, a select
+value outside the options — none of it is rejected. Validation failures you don't get
+from the API become rendering bugs in the dashboard/frontend, so discipline comes from
+you: fetch the schema first and match each field's type exactly.
+
+## Value format per field type
+
+| Field type | Write this | Notes |
+|---|---|---|
+| `text`, `textarea` | plain string | |
+| `richtext` | **Tiptap HTML string**, e.g. `"<p>Hello <strong>world</strong></p>"` | not markdown, not JSON; the dashboard editor is Tiptap |
+| `number` / `boolean` | JSON number / boolean | not validated — don't send strings |
+| `date` | ISO 8601 string, `"2026-08-01"` (or full timestamp) | not format-validated; ISO keeps the dashboard picker working |
+| `select` | one of the schema's `options`, exact string | not validated — off-list values break the generated literal-union types |
+| `image` | media UUID string, or array of them | validated against workspace media |
+| `relation`, `content_type_reference` | entry UUID string, or array | validated against workspace entries; **UUID, not slug** |
+
+Reading back: the value is whatever was stored. Content created through this API holds
+UUIDs for image/relation; older or imported datasets may hold URLs/slugs — when
+rendering, branch on the shape (e.g. `value.startsWith("http")` → use directly,
+otherwise resolve via `media.get(id)`).
+
+## Writing translations (localized entries)
+
+Entry create/update accept a `translations` map alongside `data`:
+
+```jsonc
+{
+  "slug": "hello",
+  "data":         { "title": "Hello",  "views": 10 },   // base locale
+  "translations": {
+    "de": { "data": { "title": "Hallo" } },              // only localizable fields
+    "ja": { "data": { "title": "こんにちは" } }
+  }
+}
+```
+
+Rules that will bite you if unknown:
+
+- **A `required` + `localizable` field is validated against `translations`, not
+  `data`** — it must have a non-empty value in at least one translation locale, or the
+  write fails with "required localizable field ... is missing".
+- Translation `data` should contain **only localizable fields**; non-localizable values
+  live in base `data` and fall back automatically on read.
+- **Via the management SDK**: pass `translations` as an extra key on
+  `CreateEntryInput`/`UpdateEntryInput` (the input types accept extra keys):
+
+  ```ts
+  await client.entries("article").update("hello", {
+    data: fullBaseData,                                   // full replace — include everything
+    translations: { de: { data: { title: "Hallo" } } },   // also a full replace per locale
+  });
+  ```
+
+- **Via MCP: not possible.** The `create_entry`/`update_entry` tools forward only
+  `slug` and `data` — a `translations` key is dropped. Translating content needs the
+  SDK or the dashboard; say so instead of trying.
+
+## Writing pages and blocks
+
+The real write shape (`POST/PUT /pages`) differs from what the reading API shows:
+
+```jsonc
+{
+  "slug": "landing",                       // required on create; there is NO "title" field —
+  "seo": {                                 //   the page's title lives in seo.title
+    "title": "Landing",
+    "description": "...",
+    "keywords": ["a", "b"],                // array of strings
+    "og_image": "https://...",
+    "canonical": "https://..."
+  },
+  "seo_translations": { "de": { "title": "Landung", ... } },
+  "blocks": [
+    {
+      "block_type_id": "<UUID>",           // required per block — see warning below
+      "parent_id": null,                    // block UUID for nesting, or null
+      "position": 0,
+      "data": { "...": "block fields" },
+      "translations": { "de": { "data": { "...": "..." } } }
+    }
+  ]
+}
+```
+
+- `update` with `blocks` replaces the block list; reordering alone has a dedicated
+  endpoint (`blocksReorder(slug, ids)` in the SDK).
+- **`block_type_id` is effectively dashboard-only knowledge.** The public read API
+  returns each block's type *name* and its instance id — not its `block_type_id` — and
+  the management plane has no read endpoints at all. To compose new blocks
+  programmatically you must be given the block-type UUIDs (from the dashboard). If you
+  don't have them, structure the content as **entries** instead (fully writable blind)
+  and keep pages for dashboard-managed layout.
+- MCP `create_page`/`update_page` extra caveats: the `title` argument is ignored by the
+  backend (set `seo.title`), `seo` there accepts only `title`/`description`, and block
+  `translations`/`seo_translations` aren't expressible.
+
+## Practical write checklist
+
+1. `get_content_type` / schema → exact field names, types, required, localizable, select options.
+2. Uploads first → collect media UUIDs.
+3. Compose `data` per the table above; localizable required fields go in `translations`.
+4. Create (draft) → read back → verify → publish.
+5. On `VALIDATION_ERROR` via MCP (no field detail): re-check step 1-3 against this file
+   before retrying — the usual culprits are slug-instead-of-UUID in relation/image,
+   markdown in richtext, and required-localizable fields sitting in `data`.

package/skills/atlas-cms/references/cli-typegen.md

@@ -1,51 +1,93 @@
 # CLI type generation
 
-Generates TypeScript interfaces for a workspace from `/api/v1/public/schema`.
+`@latellu/atlas-cli` generates TypeScript interfaces for a workspace by fetching
+`GET /api/v1/public/schema` (workspace derived server-side from the key). One command:
 
 ```bash
 npx @latellu/atlas-cli generate --api-key=atlas_live_xxx --output=./lib/atlas.types.ts
-# or, installed globally, the binary is named atlas-cms (not atlas-cli):
+# installed globally the binary is named `atlas-cms` (not atlas-cli):
 atlas-cms generate --api-key=atlas_live_xxx
 ```
 
 | Flag | Env fallback | Default |
 |---|---|---|
-| `--api-key` | `ATLAS_API_KEY` | (required) |
+| `--api-key` | `ATLAS_API_KEY` | (required — errors if absent from both) |
 | `--url` | `ATLAS_API_URL` | `https://api.atlas.latellu.com` |
 | `--output` | `ATLAS_OUTPUT` | `./src/atlas.types.ts` |
 
-Flags win over env vars. If `--output` doesn't end in `.ts` it is treated as a directory
-and `atlas.types.ts` is appended. The workspace is derived server-side from the key.
+Flags win over env vars. Both `--key=value` and `--key value` forms work. If `--output`
+doesn't end in `.ts` it is treated as a directory and `atlas.types.ts` is appended.
+Parent directories are created automatically. Output is deterministic for a given
+schema, so committing the file produces clean diffs on schema changes.
 
 ## Output anatomy
 
-- One `export interface <PascalCaseSlug>` per content type, plus
-  `export type Locale = "en" | "ja" | ...` from the workspace locales.
-- A registry mapping slugs to interfaces — feed it to the SDK for full typing:
+```ts
+// Generated by @latellu/atlas-cli — DO NOT EDIT BY HAND.
+// Workspace: acme-digital
+// Source: https://api.atlas.latellu.com/api/v1/public/schema
+
+export type Locale = "en" | "de" | "ja";      // from workspace locales ("string" if none)
+
+/** News Article (content type: "news-article") */
+export interface NewsArticle {
+  title: string;                               // localizable
+  category: "News" | "Event";                  // select field → literal union
+  views?: number;                              // non-required → optional
+  cover_image: string;                         // image field → media ID (unresolved)
+  "og:title"?: string;                         // non-identifier names are quoted
+}
+
+export interface AtlasContentTypes {
+  "news-article": NewsArticle;
+  // ... one key per content-type slug
+}
+```
+
+Consume it as the SDK generic — this is the whole point:
 
 ```ts
 import { createClient } from "@latellu/atlas-sdk";
 import type { AtlasContentTypes } from "./atlas.types";
 
 const atlas = createClient<AtlasContentTypes>({ url, apiKey });
-const article = await atlas.entries("news-article").get("hello"); // data is typed
+const article = await atlas.entries("news-article").get("hello");
+article?.data.category; // "News" | "Event" — fully typed
 ```
 
-## Type semantics (what the generated types do and don't promise)
+## Field-type mapping (what the types do and don't promise)
+
+| Atlas field type | Generated TS | Caveat |
+|---|---|---|
+| `text`, `textarea`, `richtext`, `date` | `string` | richtext is the raw stored string |
+| `number` / `boolean` | `number` / `boolean` | |
+| `select` (with options) | `"A" \| "B"` literal union | no options → `string` |
+| `image` | `string` | **media ID** — resolve via `atlas.media.get(id)` |
+| `relation`, `content_type_reference` | `string` | **entry slug/ID** — resolve via `atlas.entries(type).get(slug)` |
+| localizable anything | base type + `// localizable` comment | value is base-locale only; no per-locale map in this release |
+| unknown/new field type | `unknown` | codegen never fails on new backend field types |
+| content type with zero fields | `{ [key: string]: unknown }` | index-signature escape hatch |
+| non-required field | `name?:` | |
+
+## Workflow
+
+- Add a script so regeneration is one command, and **regenerate after every schema
+  change** in the dashboard (the file is generated — never hand-edit):
+
+  ```json
+  { "scripts": { "atlas:types": "atlas-cli generate --output=./lib/atlas.types.ts" } }
+  ```
 
-- `select` fields with options → string-literal unions (`"News" | "Event"`).
-- `number` → `number`, `boolean` → `boolean`; `text`/`textarea`/`richtext`/`date` → `string`.
-- **`image`, `relation`, `content_type_reference` → plain `string`** — the raw media ID or
-  entry slug, never a resolved object. Resolve manually via `atlas.media.get(id)` /
-  `atlas.entries(type).get(slug)`.
-- **Localizable fields are only marked with a `// localizable` comment**; the value is
-  typed as the base-locale scalar (no per-locale map in this release).
-- Optional (`?`) mirrors non-required fields; non-identifier field names are quoted.
-- A content type with zero fields renders as `{ [key: string]: unknown }`; unknown field
-  types degrade to `unknown` instead of failing codegen.
+  with `ATLAS_API_KEY` in the environment (e.g. `.env.local`, not committed).
+- Stale types don't fail at runtime — the SDK sends whatever the API returns — they
+  fail at compile time or silently type new fields as missing. Treat type/`data`
+  mismatches as a "regenerate first" signal before debugging anything else.
 
-## Rules
+## Troubleshooting
 
-- The file is generated (`// Generated by @latellu/atlas-cli — DO NOT EDIT BY HAND.`) —
-  never hand-edit; **regenerate after every schema change** in the dashboard.
-- A 401 means the API key is wrong or revoked (the error says so); check `--api-key`.
+| Symptom | Cause |
+|---|---|
+| `401 ... (check your --api-key)` | wrong/revoked key, or a `atlas_mgmt_` key (schema needs a live key) |
+| interface is `{ [key: string]: unknown }` | that content type has no fields defined yet |
+| field typed `unknown` | backend field type newer than the installed CLI — upgrade `@latellu/atlas-cli` |
+| exit code 1 with usage text | ran without a subcommand — the only command is `generate` |

package/skills/atlas-cms/references/mcp.md

@@ -1,63 +1,110 @@
 # Atlas MCP tools
 
-The plugin bundles the `@latellu/atlas-mcp` server (stdio). Read tools need
-`ATLAS_LIVE_API_KEY`; write tools need `ATLAS_MGMT_API_KEY`. With only one key set, the
-other half of the tools fails client-side naming the missing variable. If neither is set
-the server exits at startup. `ATLAS_API_URL` overrides the base URL for self-hosted.
+The `@latellu/atlas-mcp` server (stdio) exposes Atlas content operations as agent tools.
+
+**Environment** — read tools need `ATLAS_LIVE_API_KEY`, write tools need
+`ATLAS_MGMT_API_KEY`; with only one set, the other half of the tools fails client-side
+naming the missing variable, and with neither set the server exits at startup.
+`ATLAS_API_URL` overrides the base URL (self-hosted). `MCP_ALLOWED_UPLOAD_PATHS`
+(comma-separated absolute dirs) restricts where `upload_media` may read files from.
+
+Tool results are the API's `data` payload as pretty-printed JSON text; failures come
+back as `Error: Atlas API error: <status> - <message>` tool results (not protocol
+errors).
 
 ## Tool catalog
 
-**Schema & discovery** (live key)
-- `get_workspace_schema` — workspace meta (slug, locales, default locale) + all content types.
-- `list_content_types` / `get_content_type(content_type)` — convenience views over the schema.
+### Schema & discovery — live key
+
+| Tool | Params | Returns |
+|---|---|---|
+| `get_workspace_schema` | — | `{ workspace: { slug, name, locales, default_locale }, content_types: [...] }` |
+| `list_content_types` | — | `content_types` array (client-side view of the schema) |
+| `get_content_type` | `content_type` | one content type with its full field list; error text if the slug doesn't exist |
+
+### Entries — read: live key · write: mgmt key
+
+| Tool | Params | Notes |
+|---|---|---|
+| `list_entries` | `content_type`, `page?`=1, `limit?`=20, `status?` | `status` is free text and **cannot** reveal drafts to a live key |
+| `get_entry` | `content_type`, `slug` | resolves by `slug` alone — `content_type` is accepted but not sent |
+| `create_entry` | `content_type`, `data`, `slug?` | creates a **draft**; slug auto-generated when omitted |
+| `update_entry` | `content_type`, `slug`, `data` | **full replace** of `data`, not a patch |
+| `publish_entry` / `unpublish_entry` / `archive_entry` | `content_type`, `slug` | need the `content:publish` scope |
+| `duplicate_entry` | `content_type`, `slug` | copies to a new draft |
+| `delete_entry` | `content_type`, `slug` | returns plain text, not JSON |
+
+### Pages — read: live key · write: mgmt key
+
+| Tool | Params | Notes |
+|---|---|---|
+| `list_pages` | `page?`=1, `limit?`=20 | summaries, no blocks |
+| `get_page` | `slug` | block tree — each block's `data` is a **JSON string**, parse it |
+| `create_page` | `title`, `slug?`, `blocks?`, `seo?` | draft; `seo` accepts only `title`/`description` here |
+| `update_page` | `slug`, `title?`, `blocks?`, `seo?` | |
+| `publish_page` | `slug` | the ONLY page lifecycle tool — see gaps below |
+| `delete_page` | `slug` | plain-text result |
+
+### Media
+
+| Tool | Params | Notes |
+|---|---|---|
+| `get_media` | `id` | live key |
+| `upload_media` | `file_path` (absolute), `folder?`="/", `alt_text?` | mgmt key; reads the local file, multipart upload |
+
+## Recommended write workflow
 
-**Entries** (read: live key; write: mgmt key)
-- `list_entries(content_type, page?, limit?, status?)`
-- `get_entry(content_type, slug)`
-- `create_entry(content_type, data, slug?)` — creates a **draft**; slug auto-generated if omitted.
-- `update_entry(content_type, slug, data)`
-- `publish_entry` / `unpublish_entry` / `archive_entry` / `duplicate_entry` / `delete_entry` — all `(content_type, slug)`.
+1. **Schema first.** Call `get_content_type` (or `get_workspace_schema`) before any
+   `create_entry`/`update_entry`. The `data` argument is an unvalidated map; the backend
+   rejects wrong shapes with 400, and **per-field validation detail is lost through
+   MCP** — you only see `Atlas API error: 400 - validation failed`. Knowing the exact
+   field names/types up front is the difference between one call and five.
+2. **Read-modify-write for updates.** `update_entry` replaces `data` wholesale:
+   `get_entry` → merge your change into the full object → `update_entry` with everything.
+3. **Create → verify → publish.** `create_entry` makes a draft; `publish_entry` needs
+   the `content:publish` scope (403 without it, with a clear message).
+4. **Before `upload_media`**: check the file is ≤ 10 MB and has a known extension.
+   Validation is entirely server-side; MIME is inferred from the extension and unknown
+   extensions upload as `application/octet-stream`, which the backend always rejects
+   (so `.svg`, `.heic` fail). Allowed: `image/*`, `video/*`, `application/pdf` (i.e.
+   `.jpg .jpeg .png .gif .webp .mp4 .webm .mov .pdf`).
 
-**Pages** (read: live; write: mgmt)
-- `list_pages(page?, limit?)` / `get_page(slug)`
-- `create_page(title, slug?, blocks?, seo?)` — creates a draft. `seo` accepts `title`/`description` only.
-- `update_page(slug, title?, blocks?, seo?)` / `publish_page(slug)` / `delete_page(slug)`
+## Capability gaps — route elsewhere instead of retrying
 
-**Media**
-- `get_media(id)` (live key)
-- `upload_media(file_path, folder?, alt_text?)` (mgmt key) — reads a local file and uploads it.
+These exist in the backend/SDK but have **no MCP tool**; say so and point to the
+dashboard or the management SDK (`sdk-management.md`) rather than improvising:
 
-## Recommended workflow for writes
+- **Translations cannot be written.** `create_entry`/`update_entry` forward only
+  `slug`/`data` — a `translations` key is dropped. "Translate this entry" is an SDK or
+  dashboard job (see `authoring.md`), and note that a required+localizable field can
+  make MCP creates fail outright (its value must be in `translations`).
+- Page lifecycle beyond publish: **no `unpublish_page`, `archive_page`,
+  `duplicate_page`**.
+- **No** bulk operations, entry/page **scheduling**, or block **reorder** tools.
+- **No `delete_media` / `update_media`** (alt-text edits) — media is upload-and-read
+  only through MCP.
+- Pagination is offset-only (`page`/`limit`); there is no cursor option, so listings
+  past page 1000 (`PAGE_TOO_DEEP`) are unreachable via MCP.
+- Composing page **blocks** needs `block_type_id` UUIDs that no read surface exposes
+  (dashboard-only knowledge) — prefer entries for agent-authored content. Also:
+  `create_page`'s `title` argument is ignored by the backend (the title is `seo.title`),
+  and its `seo` accepts only `title`/`description`.
 
-1. Call `get_content_type` (or `get_workspace_schema`) first to learn the exact field
-   names and types. `data` is an unvalidated map — the backend rejects bad shapes with a
-   400, and per-field validation detail is **not** surfaced through MCP (you only see
-   `Atlas API error: 400 - validation failed`).
-2. `create_entry` / `update_entry` with a `data` object matching the schema.
-3. `publish_entry` when ready (requires the `content:publish` scope on the key).
+Before composing any `data` payload, read `authoring.md` — it defines the exact value
+format per field type (richtext = Tiptap HTML, relation/image = UUIDs, etc.), which
+matters double here because MCP swallows per-field validation errors.
 
 ## Gotchas
 
-- **`update_entry` is a full replace** of `data`, not a patch. Read the entry first,
-  merge your change, then send the complete object (read-modify-write).
-- **Page lifecycle is asymmetric**: there is no `unpublish_page`, `archive_page`, or
-  `duplicate_page` tool. There are also no bulk, schedule, or block-reorder tools, and no
-  `delete_media`/`update_media`. For those, use the dashboard or the SDK management
-  client (see `sdk-management.md`).
-- **`get_page` returns each block's `data` as a JSON-encoded string**, not an object.
-  Parse it before reading fields — otherwise blocks look empty.
-- **`get_entry` resolves by slug alone**; its `content_type` argument is accepted but not
-  sent to the backend. Don't rely on it to disambiguate slugs shared across types.
-- **Drafts are invisible to live keys.** `list_entries(status="draft")` with a production
-  key returns nothing — that is key scoping, not an empty workspace.
-- **Uploads are validated server-side only**: max 10 MB; MIME must be `image/*`,
-  `video/*`, or `application/pdf`. MIME is inferred from the file extension; unknown
-  extensions become `application/octet-stream` and are always rejected (e.g. `.svg`,
-  `.heic`). Check size and extension before calling `upload_media`. If
-  `MCP_ALLOWED_UPLOAD_PATHS` is set, `file_path` must live under one of those directories.
-- **No client-side retry on 429.** On `Atlas API error: 429 - ...`, back off
-  (exponentially) and retry yourself.
-- **`delete_entry` / `delete_page` return plain text** ("Entry 'x' deleted successfully"),
-  unlike every other tool, which returns JSON.
-- Every write automatically sends a fresh `Idempotency-Key` header per call; identical
-  retries you issue as *new tool calls* are new operations, not deduplicated.
+- **Drafts are invisible to live keys** — `list_entries(status="draft")` returning
+  empty means key scoping, not an empty workspace.
+- **`get_page` block `data` needs `JSON.parse`** per block, or blocks look empty.
+- **`get_entry` ignores `content_type`** — slugs shared across types resolve to
+  whatever the backend finds by slug.
+- **No client-side 429 retry** — on `Atlas API error: 429`, back off exponentially and
+  retry the tool call yourself.
+- Every write sends a fresh auto-generated `Idempotency-Key` per call, so re-issuing a
+  failed create as a *new tool call* is a new operation — check whether the first call
+  actually landed (e.g. `get_entry`) before retrying creates.
+- One MCP server = one workspace (the key's). Multi-workspace work needs one server
+  registration per workspace.

package/skills/atlas-cms/references/sdk-delivery.md

@@ -1,82 +1,185 @@
 # SDK delivery client (read)
 
+`@latellu/atlas-sdk` — typed, zero-dependency read client for `/api/v1/public`.
+Node 18+ (uses global `fetch`). ESM only.
+
 ```bash
-npm install @latellu/atlas-sdk        # Node 18+ (uses global fetch)
+npm install @latellu/atlas-sdk
+```
+
+## Client setup
+
+```ts
+import { createClient } from "@latellu/atlas-sdk";
+
+const atlas = createClient<AtlasContentTypes>({
+  url: "https://api.atlas.latellu.com", // required — SDK reads NO env vars itself
+  apiKey: "atlas_live_...",             // required — delivery key
+  fetchImpl: customFetch,               // optional — see "Caching" below
+});
 ```
 
-## Canonical setup (Next.js thin adapter)
+- `createClient` **throws synchronously** (`AtlasError`) if `url` or `apiKey` is missing.
+- The generic `<AtlasContentTypes>` comes from CLI codegen (`cli-typegen.md`); without
+  it, `entry.data` is `Record<string, unknown>`.
+- All requests go to `${url}/api/v1/public/*` with header `X-API-Key`.
 
-Keep one server-only adapter, e.g. `lib/atlas.ts`:
+### Canonical Next.js thin adapter
+
+Keep one server-only adapter (pattern used by all official Atlas examples), e.g.
+`lib/atlas.ts`:
 
 ```ts
 import "server-only";
 import { createClient } from "@latellu/atlas-sdk";
-import type { AtlasContentTypes } from "./atlas.types"; // generated — see cli-typegen.md
+import type { AtlasContentTypes } from "./atlas.types";
 
-// The SDK sets NO cache directive. In Next.js you must decide caching yourself
-// via a custom fetchImpl, or Next's defaults for un-annotated fetch apply.
 const noStoreFetch: typeof fetch = (input, init) =>
-  fetch(input, { ...init, cache: "no-store" }); // or next: { revalidate: 60 }
+  fetch(input, { ...init, cache: "no-store" });
 
 export const atlas = createClient<AtlasContentTypes>({
-  url: process.env.ATLAS_BASE_URL ?? "",     // https://api.atlas.latellu.com
-  apiKey: process.env.ATLAS_API_KEY ?? "",   // atlas_live_...
+  url: process.env.ATLAS_BASE_URL ?? "",
+  apiKey: process.env.ATLAS_API_KEY ?? "",
   fetchImpl: noStoreFetch,
 });
 ```
 
-With `no-store`, pair route files with `export const dynamic = "force-dynamic"` so
-dashboard edits appear immediately. The SDK reads no env vars itself — `url`/`apiKey`
-must be passed explicitly. `createClient` throws synchronously if either is missing.
+### Caching — the SDK deliberately has no knob
+
+The SDK issues plain `fetch(url, { headers })` with **no cache directive**. In Next.js
+App Router this means caching behavior is whatever Next's defaults do for un-annotated
+fetch (varies by version/runtime). Decide explicitly via `fetchImpl`:
 
-## Surface
+| Goal | fetchImpl |
+|---|---|
+| Dashboard edits appear immediately (no SSG) | `cache: "no-store"` + `export const dynamic = "force-dynamic"` in routes |
+| ISR-style freshness | `next: { revalidate: 60 }` |
+| Astro/SSR outside Next | default fetch is fine (no framework cache layer) |
+
+## Full surface
 
 ```ts
-const { items, total, page, pageSize } =
-  await atlas.entries("news-article").list({ locale: "en", page: 1, limit: 20, sort: "created_at:desc" });
+interface AtlasClient<TSchema> {
+  entries<K extends keyof TSchema>(type: K): EntriesResource<TSchema[K]>;
+  pages: PagesResource;
+  media: MediaResource;
+  raw: Requester;  // low-level escape hatch
+}
+```
 
-const entry = await atlas.entries("news-article").get("hello-world", { locale: "en" }); // null on 404
-// entry: { id, slug, status, published_at, data }  — data is already parsed to an object
+### Entries
 
-const pages = await atlas.pages.list({ locale: "en", page: 1, limit: 20 }); // summaries, no blocks
-const pageDetail = await atlas.pages.get("home", { locale: "en" });         // null on 404
-// pageDetail: { id, slug, status, seo, blocks: [{ id, type, position, data }] }
+```ts
+const res = await atlas.entries("news-article").list({
+  locale: "en",              // optional
+  page: 1, limit: 20,        // offset pagination (limit max 100, page max 1000)
+  sort: "created_at:desc",   // "<field>:<asc|desc>", e.g. "published_at:desc"
+});
+// res: ListResult<AtlasEntry<T>> = { items, total, page, pageSize }
 
-const asset = await atlas.media.get(mediaId);      // null on 404
-const raw = await atlas.raw.get<T>("/some/path");  // escape hatch for unwrapped /api/v1/public paths
+const entry = await atlas.entries("news-article").get("hello-world", { locale: "en" });
+// AtlasEntry<T> = { id, slug, status, published_at: string | null, data: T }
+// null on 404; throws AtlasError on anything else
 ```
 
-Semantics the SDK handles for you (don't re-implement):
-- `entry.data`, page `seo`, and block `data` arrive from the API as JSON strings — the
-  SDK parses them.
-- Locale merge is field-by-field: translated fields overlay base data; untranslated
-  fields fall back to the base locale.
-- Page blocks are always returned sorted by `position`, regardless of API order.
+What the SDK does for you here (do not re-implement):
+- `data` arrives from the API as a **JSON string**; the SDK parses it to an object
+  (empty string → `{}`).
+- With `locale`, `get()` merges the matching `translations[].data` over the base `data`
+  field-by-field (`{ ...base, ...translation }`) — untranslated fields keep base values.
+
+### Pages
+
+```ts
+const list = await atlas.pages.list({ locale: "en", page: 1, limit: 20 });
+// items: AtlasPageSummary[] — lightweight rows { id, slug, status, ... }, NO blocks
+
+const page = await atlas.pages.get("home", { locale: "en" }); // null on 404
+// AtlasPage = { id, slug, status, seo: AtlasPageSEO, blocks: AtlasBlock[] }
+// AtlasPageSEO = { title?, description?, keywords?, og_image?, canonical?, ... }
+// AtlasBlock  = { id, type, position, data: Record<string, unknown> }
+```
 
-Errors: non-404 failures throw `AtlasError` (`{ status?, code?, message }`). `get()`
-methods return `null` only for 404.
+`pages.get` semantics: SEO is overlaid with `seo_translations` for the locale
+(field-level fallback); each block's `data` is overlaid with its matching
+`block_translations` row; **blocks are always returned sorted by `position`** regardless
+of API order; `seo`/block `data` JSON strings are parsed defensively (malformed JSON
+silently becomes `{}` — a corrupt block fails silent, not loud).
+
+### Media & raw
+
+```ts
+const asset = await atlas.media.get(id);   // MediaAsset = { id, ...unknown } | null on 404
+
+const { data, meta } = await atlas.raw.get<T>("/entries", { type: "article", cursor });
+// any /api/v1/public path; use for things the SDK doesn't wrap — e.g. CURSOR pagination
+// (entries.list only exposes page/limit; past page 1000 the API returns PAGE_TOO_DEEP,
+//  so deep datasets must iterate meta.next_cursor via raw.get)
+```
+
+## Error handling
+
+```ts
+import { AtlasError } from "@latellu/atlas-sdk";
+
+try {
+  const items = await atlas.entries("article").list();
+} catch (e) {
+  if (e instanceof AtlasError) {
+    e.status; // HTTP status (undefined for network errors)
+    e.code;   // "UNAUTHORIZED" | "FORBIDDEN" | "PAGE_TOO_DEEP" | ...
+  }
+}
+```
+
+Only `get()` methods special-case 404 → `null`. `list()` never returns null. Network
+failures are wrapped in `AtlasError` with the URL in the message.
 
 ## Rendering blocks
 
-Dispatch on `block.type` with an explicit fallback so new block types added in the
-dashboard never crash the site:
+Dispatch on `block.type` with an explicit fallback so block types added later in the
+dashboard never crash the site — adding a section type then only requires registering a
+component here:
 
 ```tsx
 export function BlockRenderer({ blocks }: { blocks: AtlasBlock[] }) {
   return blocks.map((block) => {
     switch (block.type) {
-      case "hero":   return <HeroBlock key={block.id} data={block.data} />;
-      case "faq":    return <FaqBlock key={block.id} data={block.data} />;
-      default:       return null; // or an <UnknownBlock /> placeholder
+      case "hero": return <HeroBlock key={block.id} data={block.data} />;
+      case "faq":  return <FaqBlock key={block.id} data={block.data} />;
+      default:     return <UnknownBlock key={block.id} type={block.type} />; // never throw
     }
   });
 }
 ```
 
-## Limits
+## Resolving reference fields
+
+`image` / `relation` / `content_type_reference` values are raw strings, never resolved
+objects. Content written through the API holds **UUIDs** (that's what the backend
+validates); imported/seeded datasets may hold URLs instead — branch on the shape:
+
+```ts
+const article = await atlas.entries("article").get(slug);
+
+const cover = article.data.cover_image.startsWith("http")
+  ? article.data.cover_image                       // legacy/imported: direct URL
+  : await atlas.media.get(article.data.cover_image); // API-written: media UUID
+
+// relation fields hold entry UUIDs; the public API fetches entries by SLUG only,
+// so resolve relations by listing the target type and matching on id:
+const authors = await atlas.entries("author").list({ limit: 100 });
+const author = authors.items.find((a) => a.id === article.data.author);
+```
+
+Also note: list endpoints have **no field-value filters** (only type/locale/page/sort) —
+"entries where category = X" means paging + filtering client-side.
+
+## Limits to remember
 
-- Draft preview is not yet supported by the SDK — delivery keys see published content only.
-- There is no `search` or `schema` namespace on the client; schema introspection is the
-  CLI's job (`cli-typegen.md`).
-- `image` / `relation` / `content_type_reference` field values are raw string IDs/slugs —
-  resolve with `atlas.media.get(id)` or `atlas.entries(type).get(slug)`.
+- Delivery keys see **published content only**; draft preview is not yet supported by
+  the SDK (preview-token endpoint pending).
+- No `search` or `schema` namespace on the client — schema introspection belongs to the
+  CLI (`cli-typegen.md`); anything else goes through `raw.get`.
+- API keys are rate limited; a 429 here is **not** retried automatically (only the
+  management client retries) — back off exponentially and retry yourself.

package/skills/atlas-cms/references/sdk-management.md

@@ -1,6 +1,7 @@
 # SDK management client (write)
 
-Server-side only. Never import this module or expose an `atlas_mgmt_*` key in
+`@latellu/atlas-sdk/management` — Promise-based write client for `/api/v1/manage`.
+**Server-side only.** Never import this module or expose an `atlas_mgmt_*` key in
 browser-bundled code.
 
 ```ts
@@ -12,49 +13,136 @@ const client = createManagementClient<AtlasContentTypes>({
 });
 ```
 
-`createManagementClient` throws `ManagementConfigError` **synchronously** if the token
-doesn't start with `atlas_mgmt_` (e.g. you passed a live key) — wrap construction in
-try/catch, not just the calls. Requests go to `/api/v1/manage` with `X-API-Key`.
+Construction rules:
+- The token prefix is validated **synchronously**: a non-`atlas_mgmt_` token (e.g. a
+  live key) throws `ManagementConfigError` immediately — wrap
+  `createManagementClient(...)` in try/catch, not just the awaited calls.
+- Requests carry `X-API-Key` and go to `${url}/api/v1/manage/*`.
+- The key's scopes gate operations: `content:write` → create/update/delete/duplicate,
+  `content:publish` → publish/unpublish/archive/schedule, `media:write` → uploads.
+  Missing scope = 403 on that call only. Every write is audit-attributed to the key's
+  creator and bounded by their RBAC — a key can never do more than its creator could in
+  the dashboard.
 
-## Surface
+## Entries
 
 ```ts
 const w = client.entries("news-article");
-await w.create({ slug: "hello", data: { title: "Hello" } });
-await w.update("hello", { data: { title: "Hello v2" } });
-await w.publish("hello");            // needs content:publish scope
-await w.unpublish("hello");
-await w.archive("hello");
-await w.schedule("hello", "2026-08-01T09:00:00Z");
-await w.duplicate("hello");
-await w.delete("hello");
-await w.bulk([{ op: "publish", id: "..." }, ...]);
-
-await client.pages.create({ slug: "landing", /* ... */ });
-await client.pages.update("landing", { /* ... */ });
-await client.pages.publish("landing");     // also: unpublish, archive, schedule, delete
-await client.pages.blocksReorder("landing", ["block-id-1", "block-id-2"]);
-
-const asset = await client.media.upload(fileBlob, { alt: "Team photo" }); // multipart
+
+await w.create({ slug: "hello", data: { title: "Hello", body: "..." } });
+// CreateEntryInput = { slug, data, ... }  → creates a DRAFT
+// POST /content-types/:type/entries
+// Field value formats (richtext = Tiptap HTML, relation/image = UUIDs, ...):
+//   see authoring.md before composing `data`.
+
+await w.update("hello", { data: { title: "Hello v2", body: "..." } });
+// UpdateEntryInput = { slug?, data?, ... } — send the FULL data object you want stored
+
+// Localized content: pass a `translations` map as an extra key (accepted by the API
+// on both create and update; required+localizable fields MUST live here, not in data):
+await w.update("hello", {
+  data: fullBaseData,
+  translations: { de: { data: { title: "Hallo" } }, ja: { data: { title: "こんにちは" } } },
+});
+
+await w.publish("hello");                            // PATCH .../publish
+await w.unpublish("hello");                          // PATCH .../unpublish
+await w.archive("hello");                            // PATCH .../archive
+await w.schedule("hello", "2026-08-01T09:00:00Z");   // PATCH .../schedule { publish_at } — ISO 8601 UTC
+await w.duplicate("hello");                          // POST .../duplicate → new draft copy
+await w.delete("hello");                             // DELETE
+await w.bulk([                                       // POST .../bulk { operations }
+  { op: "publish", id: "…" },
+  { op: "archive", id: "…" },
+]);
+```
+
+All idOrSlug parameters accept either the entry ID or its slug.
+
+## Pages
+
+```ts
+// NOTE: pages have NO top-level title — the title lives in seo.title.
+// Block objects need a block_type_id UUID; see authoring.md for the full write shape
+// (seo_translations, block translations, nesting) and the block_type_id caveat.
+await client.pages.create({ slug: "landing", seo: { title: "Landing" }, blocks: [...] });
+await client.pages.update("landing", { seo: { title: "Landing v2" } });
+await client.pages.publish("landing");
+await client.pages.unpublish("landing");   // pages have the FULL lifecycle here
+await client.pages.archive("landing");     //   (unlike the MCP tools)
+await client.pages.schedule("landing", "2026-08-01T09:00:00Z");
+await client.pages.delete("landing");
+await client.pages.blocksReorder("landing", ["block-id-2", "block-id-1", "block-id-3"]);
+// PATCH /pages/:slug/blocks/reorder { block_ids } — pass the COMPLETE ordered id list
+```
+
+## Media
+
+```ts
+import { readFile } from "node:fs/promises";
+
+const blob = new Blob([await readFile("./team.jpg")], { type: "image/jpeg" });
+const asset = await client.media.upload(blob, { alt: "Team photo" });
+// multipart POST /media/upload; returns UploadedMediaAsset = { id, ... }
+
 await client.media.delete(asset.id);
 ```
 
-Every write accepts an optional trailing `{ idempotencyKey: "..." }` — pass a stable key
-when a retry must not double-create/double-publish.
+Server-side upload validation: max 10 MB; MIME must be `image/*`, `video/*`, or
+`application/pdf` — set the Blob `type` explicitly, an untyped Blob is rejected.
+
+## Idempotency & retries (built in)
+
+- Every write accepts an optional trailing options argument
+  `{ idempotencyKey: "stable-string" }` → sent as the `Idempotency-Key` header. Pass a
+  **stable** key when your own retry logic must not double-create or double-publish:
 
-## Built-ins
+  ```ts
+  await w.create(input, { idempotencyKey: `import-article-${sourceId}` });
+  ```
 
-- **429s are retried automatically** (exponential backoff from 200 ms, up to 3 retries).
-  Not configurable.
-- **Validation errors carry per-field detail** (unlike MCP): `AtlasError.errors` is
-  `{ field, message }[]` on 400s — surface it to users instead of the generic message.
-- Scopes: `content:write` covers create/update/delete/duplicate; `content:publish` covers
-  publish/unpublish/archive/schedule; `media:write` covers uploads. Missing scope → 403.
+- **429 responses are retried automatically**: exponential backoff from 200 ms, up to 3
+  retries. Hardcoded — not configurable, and only for 429 (400/403/500 are not retried).
+
+## Error handling
+
+```ts
+try {
+  await w.create({ slug: "x", data: { title: 42 } });
+} catch (e) {
+  if (e instanceof AtlasError) {
+    e.status;  // 400
+    e.code;    // "VALIDATION_ERROR"
+    e.errors;  // [{ field: "title", message: "must be a string" }, ...]  ← per-field detail,
+  }            //    management client only (MCP loses this) — surface it to users
+}
+```
+
+`ManagementConfigError` (bad config, thrown synchronously) is a different class from
+`AtlasError` (failed requests, rejected promises) — handle both.
+
+## Worked example: idempotent import script
+
+```ts
+for (const row of sourceRows) {
+  const slug = slugify(row.title);
+  const existing = await readClient.entries("article").get(slug); // delivery client
+  const w = client.entries("article");
+  if (existing) {
+    await w.update(slug, { data: mapRow(row) });
+  } else {
+    await w.create({ slug, data: mapRow(row) }, { idempotencyKey: `import-${row.id}` });
+  }
+  await w.publish(slug);
+}
+```
 
 ## Effect-native variant
 
-`@latellu/atlas-sdk/management/effect` exports `makeManagementClient` with the same shape
-where every method returns `Effect.Effect<T, AtlasError>`. The plain Promise client above
-never bundles `effect`. If you run Effects yourself, note `Effect.runPromise` rejects
-with a `FiberFailure` wrapper — recover the original `AtlasError` via
-`Runtime.isFiberFailure` + `Cause.squash` (the Promise surface already does this for you).
+`@latellu/atlas-sdk/management/effect` exports `makeManagementClient` — identical
+surface where every method returns `Effect.Effect<T, AtlasError>`; run with
+`Effect.runPromise`. The plain entrypoints never bundle `effect` as a dependency; only
+this subpath does. Gotcha if you compose Effects yourself: `Effect.runPromise` rejects
+with a `FiberFailure` wrapper, not the raw error — recover the original `AtlasError` via
+`Runtime.isFiberFailure` + `Cause.squash` (the Promise surface already does this
+internally).