@latellu/atlas-agent-skills 0.5.3 → 0.6.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.5.3",
+  "version": "0.6.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",
@@ -9,5 +9,11 @@
   "homepage": "https://docs.atlas.latellu.com/docs/agent-skill",
   "repository": "https://github.com/tenriajeng/atlas-agent-skills",
   "license": "MIT",
-  "keywords": ["atlas", "cms", "headless-cms", "mcp", "sdk"]
+  "keywords": [
+    "atlas",
+    "cms",
+    "headless-cms",
+    "mcp",
+    "sdk"
+  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@latellu/atlas-agent-skills",
-  "version": "0.5.3",
+  "version": "0.6.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)",
@@ -9,7 +9,15 @@
     "type": "git",
     "url": "git+https://github.com/tenriajeng/atlas-agent-skills.git"
   },
-  "keywords": ["atlas", "cms", "headless-cms", "mcp", "agent", "skill", "claude-code"],
+  "keywords": [
+    "atlas",
+    "cms",
+    "headless-cms",
+    "mcp",
+    "agent",
+    "skill",
+    "claude-code"
+  ],
   "files": [
     ".claude-plugin",
     ".mcp.json",

package/skills/atlas-cms/SKILL.md

@@ -43,8 +43,10 @@ Two key classes, both sent as the `X-API-Key` header (never `Authorization: Bear
   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.
+  `content:publish` (publish/unpublish/archive/schedule), `media:write` (uploads),
+  `schema:write` (content-type/field authoring). A missing scope → 403 on that operation
+  only. Scopes don't imply one another, and keys minted before a scope existed don't
+  gain it — if schema tools 403, the key needs `schema:write` added in the dashboard.
 
 **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).
@@ -92,13 +94,23 @@ means a few manual edits typed out in conversation, not a bulk script.
 
 ## 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.
+- **Schema authoring stops at the shape of stored data.** With a `schema:write` key you
+  CAN create content types, add fields, edit a field's label/filterable/sortable, reorder
+  fields, and delete a content type that still has zero entries. You CANNOT rename a
+  field, change its `field_type`, toggle `localizable`/`is_unique`/`required`, edit
+  `validation`, delete a field, or toggle `is_block` — those rewrite or invalidate data
+  already in entries and are dashboard-only. Don't hunt for a workaround (deleting and
+  re-adding a field is NOT one — it drops the data): call `plan_field_change`, then give
+  the user its numbers and dashboard link. Available in MCP only; the SDK has no
+  schema methods.
 - **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.
+- **The management plane has no entry/page/media reads.** Its only GETs are the
+  content-type/field ones (`/manage/content-types...`, which exist because the public
+  schema omits field ids). Reading content still needs a live key, so a
+  write-then-verify flow needs both keys.
+- **A live key never sees drafts** and there is no `status` parameter to change that —
+  visibility follows the key's environment (`production` vs `preview`).
 
 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

@@ -109,7 +109,9 @@ The real write shape (`POST/PUT /pages`) differs from what the reading API shows
   `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.)
+  `id`/`is_block` from the schema — there, block-type UUIDs are dashboard-only.) A new
+  block type can be created with MCP `create_content_type` (`is_block: true`) given a
+  `schema:write` key; only flipping `is_block` on an *existing* type is 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.

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

@@ -1,8 +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.2.0** (the bundled `.mcp.json` uses
-`npx -y`, so it always runs the latest). Older servers lack `translations`,
+This file describes `@latellu/atlas-mcp` **≥ 1.5.0** (the bundled `.mcp.json` uses
+`npx -y`, so it always runs the latest). Servers below 1.5.0 lack the schema-authoring
+tools and the `locale` parameter on reads; below 1.2.0 they also lack `translations`,
 `seo_translations`, per-field error detail, the schema `id`/`is_block` fields, page/entry lifecycle tools (unpublish/archive/duplicate/schedule), bulk operations, reorder tools, media alt-text editing, list meta+cursor pagination, automatic 429 retry, and pre-parsed block data in get_page.
 
 **Environment** — read tools need `ATLAS_LIVE_API_KEY`, write tools need
@@ -23,14 +24,27 @@ errors).
 |---|---|---|
 | `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 |
+| `get_content_type` | `content_type` | one content type with its full field list; error text if the slug doesn't exist. **No field ids** — use `list_fields` for those |
+| `list_fields` | `content_type` | field definitions **with `id`** (mgmt key). The ids are what `update_field` and `reorder_fields` address |
+
+### Schema authoring — mgmt key with `schema:write`
+
+| Tool | Params | Notes |
+|---|---|---|
+| `create_content_type` | `name`, `slug?`, `is_block?`, `orderable?` | slug auto-generated from name when omitted; `is_block: true` makes it usable as a page block |
+| `update_content_type` | `content_type`, `name?`, `description?`, `icon?`, `display_field?`, `orderable?` | metadata only; slug is immutable and `is_block` is not accepted |
+| `delete_content_type` | `content_type` | **409 while any entry exists** — so it only undoes an empty type you just created |
+| `add_field` | `content_type`, `name`, `label`, `field_type`, `required?`, `is_unique?`, `localizable?`, `filterable?`, `sortable?`, `options?`, `validation?` | `options` is a plain array (encoded for you). Pick `field_type` carefully — it cannot be changed later via API |
+| `update_field` | `content_type`, `field_name` \| `field_id`, `label?`, `filterable?`, `sortable?` | presentation only; `field_name` is resolved to an id for you |
+| `reorder_fields` | `content_type`, `order` | complete ordered list of field **ids** (from `list_fields`), not a patch |
+| `plan_field_change` | `content_type`, `field_name` \| `field_id` | read-only impact report + `dashboard_url`; use for any change the API refuses |
 
 ### Entries — read: live key · write: mgmt key
 
 | Tool | Params | Notes |
 |---|---|---|
-| `list_entries` | `content_type`, `page?`=1, `limit?`=20, `status?`, `cursor?` | `status` is enum (draft \| published \| archived \| scheduled); live key **cannot** reveal drafts. Returns `{ data, meta }` where `meta` has `total_data`, `total_pages` (offset mode) or `next_cursor` (cursor mode). Use `cursor: meta.next_cursor` to page past the 1000-page limit. |
-| `get_entry` | `content_type`, `slug` | resolves by `slug` alone — `content_type` is accepted but errors clearly if the slug belongs to a different content type |
+| `list_entries` | `content_type`, `page?`=1, `limit?`=20, `cursor?`, `fields?`, `locale?`, `sort?`, `search?` | **No `status` param** — visibility follows the key's environment (`production` = published only, `preview` = also draft/scheduled). Returns `{ data, meta }` where `meta` has `total_data`, `total_pages` (offset mode) or `next_cursor` (cursor mode). Use `cursor: meta.next_cursor` to page past the 1000-page limit. |
+| `get_entry` | `content_type`, `slug`, `fields?`, `locale?` | resolves by `slug` alone — `content_type` is accepted but errors clearly if the slug belongs to a different content type |
 | `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 |
@@ -90,17 +104,32 @@ The MCP manage plane is now fully covered. These gaps remain:
   must read-modify-write yourself: `get_entry` → merge your changes → `update_entry`.
   (The management SDK's `update` is a full replace too — this is API semantics, not an
   MCP quirk.)
-- **Schema is dashboard-only.** Creating content types, fields, or block types is not
-  exposed via MCP, SDK, or API. "Create a content type" = ask the user to do it in the
-  dashboard, then continue.
+- **Schema changes that touch stored data are dashboard-only.** Creating types and fields
+  IS available (see "Schema authoring" above, needs `schema:write`). What is not: renaming
+  a field, changing its `field_type`, toggling `localizable`/`is_unique`/`required`,
+  editing `validation`, deleting a field, deleting a type that has entries, toggling
+  `is_block`. For those, call `plan_field_change` and hand the user its affected-entry
+  counts plus `dashboard_url`. **Delete-and-re-add is not a workaround** — it discards the
+  data the rename was meant to preserve.
+- **Schema authoring is MCP-only.** `@latellu/atlas-sdk`'s management client has no
+  content-type methods; don't look for them there.
 
 Before composing any `data` payload, read `authoring.md` — it defines the exact value
 format per field type (richtext = Tiptap HTML, relation/image = UUIDs, etc.).
 
 ## Gotchas
 
-- **Drafts are invisible to live keys** — `list_entries(status="draft")` returning
-  empty means key scoping, not an empty workspace.
+- **Drafts are invisible to live keys** — an empty `list_entries` means key scoping, not
+  an empty workspace. There is no `status` parameter to override it; you need a `preview`
+  environment key.
+- **Reads are base-locale unless you pass `locale`** — write a translation, then
+  `get_entry` without `locale`, and it looks like the write silently failed. Pass the
+  locale to verify your own writes.
+- **Field ids are not in the schema** — `get_workspace_schema` / `get_content_type` omit
+  them by design. `update_field` accepts `field_name` so you rarely need them, but
+  `reorder_fields` needs real ids from `list_fields`.
+- **A freshly created content type appears immediately**, but only because schema writes
+  bust the delivery response cache server-side; don't add sleeps or retries around it.
 - **`get_entry` looks up by slug alone** (slug-global, `content_type` is not sent to the
   API) — but if the entry found belongs to a different content type than you requested,
   the tool returns a clear mismatch error instead of the wrong entry.

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

@@ -68,7 +68,10 @@ Construction rules:
 - 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
+  Missing scope = 403 on that call only.
+- **No schema methods.** Content-type and field authoring (the `schema:write` scope) is
+  exposed through the MCP server only — this SDK has no equivalent. Reach for MCP, or call
+  `/api/v1/manage/content-types` directly, when you need to build schema from code. 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.