@latellu/atlas-agent-skills 0.3.0 → 0.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.3.0",
+  "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.0",
+  "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,15 +104,21 @@ 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. 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
+  current base state (status + seo) — the only "read" available on the management plane.
 
 ## Practical write checklist
 
@@ -120,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
 
@@ -108,3 +103,7 @@ matters double here because MCP swallows per-field validation errors.
   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.
+- **The server never checks that the live and mgmt keys belong to the same workspace.**
+  A mismatched pair is maximally confusing: schema and reads come from workspace A while
+  every write 404s ("content type not found") against workspace B. If reads succeed but
+  writes 404 on types you just listed, suspect mismatched keys before anything else.

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

@@ -67,7 +67,7 @@ All idOrSlug parameters accept either the entry ID or its slug.
 // (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.publish("landing");   // fails unless the page has ≥1 block — see authoring.md
 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");
@@ -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
 }
 ```