@latellu/atlas-agent-skills 0.2.0 → 0.3.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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,7 +33,7 @@ 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 |

package/package.json

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

@@ -75,6 +75,7 @@ is `-1` in cursor mode).
 | 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.
@@ -82,8 +83,18 @@ 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, per-field validation
-errors).
+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,133 @@
+# 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.
+- **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).
+- **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
+
+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/mcp.md

@@ -74,6 +74,10 @@ 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.
@@ -81,6 +85,14 @@ dashboard or the management SDK (`sdk-management.md`) rather than improvising:
   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`.
+
+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
 
@@ -96,3 +108,7 @@ dashboard or the management SDK (`sdk-management.md`) rather than improvising:
   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-delivery.md

@@ -155,17 +155,26 @@ export function BlockRenderer({ blocks }: { blocks: AtlasBlock[] }) {
 
 ## Resolving reference fields
 
-`image` / `relation` / `content_type_reference` field values are raw string IDs/slugs.
-Resolve them explicitly — and in parallel when rendering lists:
+`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, author] = await Promise.all([
-  atlas.media.get(article.data.cover_image),        // image field → media ID
-  atlas.entries("author").get(article.data.author), // relation field → entry 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
 
 - Delivery keys see **published content only**; draft preview is not yet supported by

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

@@ -32,10 +32,19 @@ const w = client.entries("news-article");
 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
@@ -53,9 +62,12 @@ All idOrSlug parameters accept either the entry ID or its slug.
 ## Pages
 
 ```ts
-await client.pages.create({ slug: "landing", title: "Landing", blocks: [...], seo: {...} });
-await client.pages.update("landing", { title: "Landing v2" });
-await client.pages.publish("landing");
+// 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");   // 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");