@latellu/atlas-agent-skills 0.3.1 → 0.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.3.1",
+  "version": "0.4.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@latellu/atlas-agent-skills",
-  "version": "0.3.1",
+  "version": "0.4.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

@@ -83,8 +83,7 @@ types, then build the page"), route each sub-task to its own single reference.
 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).
+lacks (bulk, scheduling, page unpublish/archive, block reorder, media alt-text edits).
 
 ## Hard capability boundaries (don't go looking for these)
 

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

@@ -71,9 +71,9 @@ Rules that will bite you if unknown:
   });
   ```
 
-- **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.
+- **Via MCP (≥ 1.1.0)**: pass the same `translations` map as a tool argument on
+  `create_entry`/`update_entry`. Older MCP servers silently drop it — if a
+  translation write appears to succeed but nothing changes, check the server version.
 
 ## Writing pages and blocks
 
@@ -104,19 +104,17 @@ The real write shape (`POST/PUT /pages`) differs from what the reading API shows
 
 - `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.
+- **Finding `block_type_id`: read the workspace schema.** Block types are content
+  types with `is_block: true`; `GET /api/v1/public/schema` (or the MCP
+  `get_workspace_schema` tool) returns each content type's `id`, `is_block`, and field
+  list. Use the `id` of an `is_block: true` type as `block_type_id`, and compose the
+  block's `data` against its fields exactly like an entry. (Older backends omit
+  `id`/`is_block` from the schema — there, block-type UUIDs are dashboard-only.)
+- MCP `create_page`/`update_page` caveats (≥ 1.1.0): `title` is an alias mapped to
+  `seo.title` (on update, `seo` is replaced wholesale — title alone drops the other seo
+  fields), and `seo_translations`/per-block `translations` are regular arguments.
 - **A page without blocks cannot be published** — publish returns an error requiring at
-  least one block. Combined with `block_type_id` being undiscoverable, an API-only
-  workflow can create and edit pages but **never publish a new one**; publishing needs
-  someone to add a block in the dashboard first (or block-type UUIDs supplied to you).
+  least one block. Compose at least one block (see above) before `publish_page`.
 - **The write plane has no reads**, and write responses don't echo `seo_translations` —
   you cannot fully verify a translation write without a live key for the same workspace.
   Trick: `PUT /pages/:slug` with body `{}` is a safe no-op that returns the page's
@@ -128,6 +126,7 @@ The real write shape (`POST/PUT /pages`) differs from what the reading API shows
 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`.
+5. On `VALIDATION_ERROR`: the error text carries per-field detail (MCP ≥ 1.1.0 and the
+   SDK both surface it) — fix the named field. 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/mcp.md

@@ -1,6 +1,9 @@
 # Atlas MCP tools
 
 The `@latellu/atlas-mcp` server (stdio) exposes Atlas content operations as agent tools.
+This file describes `@latellu/atlas-mcp` **≥ 1.1.0** (the bundled `.mcp.json` uses
+`npx -y`, so it always runs the latest). Older servers lack `translations`,
+`seo_translations`, per-field error detail, and the schema `id`/`is_block` fields.
 
 **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
@@ -18,7 +21,7 @@ errors).
 
 | Tool | Params | Returns |
 |---|---|---|
-| `get_workspace_schema` | — | `{ workspace: { slug, name, locales, default_locale }, content_types: [...] }` |
+| `get_workspace_schema` | — | `{ workspace: { slug, name, locales, default_locale }, content_types: [...] }` — each content type carries `id` and `is_block`; types with `is_block: true` are the valid `block_type_id` values for page blocks |
 | `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 |
 
@@ -28,8 +31,8 @@ errors).
 |---|---|---|
 | `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 |
+| `create_entry` | `content_type`, `data`, `slug?`, `translations?` | creates a **draft**; slug auto-generated when omitted; `translations` = `{locale: {data: {...}}}` (required+localizable fields go HERE) |
+| `update_entry` | `content_type`, `slug`, `data`, `translations?` | **full replace** of `data` (and per-locale `translations`), 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 |
@@ -40,9 +43,9 @@ errors).
 |---|---|---|
 | `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 |
+| `create_page` | `slug`, `title?`, `blocks?`, `seo?`, `seo_translations?` | draft; `title` is an alias for `seo.title`; `seo` accepts `title`/`description`/`keywords`/`og_image`/`canonical`; blocks = `[{block_type_id, parent_id?, position, data, translations?}]` |
+| `update_page` | `slug`, `title?`, `blocks?`, `seo?`, `seo_translations?` | passing `blocks` replaces the whole list; `seo` replaces wholesale (title alone drops other seo fields) |
+| `publish_page` | `slug` | the ONLY page lifecycle tool — see gaps below; fails on blockless pages |
 | `delete_page` | `slug` | plain-text result |
 
 ### Media
@@ -51,14 +54,16 @@ errors).
 |---|---|---|
 | `get_media` | `id` | live key |
 | `upload_media` | `file_path` (absolute), `folder?`="/", `alt_text?` | mgmt key; reads the local file, multipart upload |
+| `delete_media` | `id` | mgmt key; plain-text result |
 
 ## Recommended write workflow
 
 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.
+   rejects wrong shapes with 400. Error results include per-field detail
+   (`title: title is required`) and a `traceId` — read them instead of guessing.
+   Knowing the exact field names/types up front is still 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
@@ -74,25 +79,15 @@ errors).
 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:
 
-- **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.
+- **No `update_media`** (alt-text edits) — media is upload/read/delete 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`.
 
 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.
+format per field type (richtext = Tiptap HTML, relation/image = UUIDs, etc.).
 
 ## Gotchas
 

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

@@ -113,8 +113,8 @@ try {
   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
+    e.errors;  // [{ field: "title", message: "must be a string" }, ...]  ← per-field detail
+  }            //    (structured here; MCP ≥ 1.1.0 appends it to the error text) — surface it to users
 }
 ```