@latellu/atlas-agent-skills 0.5.2 → 0.6.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.5.2",
+  "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/README.md

@@ -4,6 +4,8 @@ Agent skill + MCP configuration for **[Atlas CMS](https://docs.atlas.latellu.com
 
 The skill itself is plain markdown ([`skills/atlas-cms/SKILL.md`](skills/atlas-cms/SKILL.md) plus per-surface references), so it works with **any** AI coding agent. This repo also packages it as a Claude Code plugin with the Atlas MCP server pre-wired.
 
+**New to MCP?** MCP (Model Context Protocol) is just the plug-in standard that lets your AI agent call a tool directly — installing "the Atlas MCP server" gives your agent tools like "list entries" or "publish page" it can call on its own, instead of you copy-pasting API calls for it.
+
 ## Claude Code
 
 ```bash
@@ -11,14 +13,29 @@ claude plugin marketplace add tenriajeng/atlas-agent-skills
 claude plugin install atlas@latellu
 ```
 
-Then set your credentials in the shell where you run `claude`:
+### Get your API keys
+
+Atlas uses two separate keys so a read-only integration can never accidentally write:
+
+- **`atlas_live_...`** — read-only. Fetches published content (blog posts, pages, media). Use this if your agent only needs to *display* content.
+- **`atlas_mgmt_...`** — read/write. Lets your agent create, edit, and publish content. Only create this if you want your agent to make changes for you.
+
+To create them: go to [cms.atlas.latellu.com/dashboard/api-keys](https://cms.atlas.latellu.com/dashboard/api-keys), log in to (or create) your workspace, click **New API key**, pick the key type above, and copy the value shown — it's only shown once.
+
+Then set them in the shell where you run `claude`:
 
 ```bash
 export ATLAS_LIVE_API_KEY="atlas_live_xxx..."   # read tools
 export ATLAS_MGMT_API_KEY="atlas_mgmt_xxx..."   # write tools
 ```
 
-Create keys at [cms.atlas.latellu.com/dashboard/api-keys](https://cms.atlas.latellu.com/dashboard/api-keys). Full guide: [docs.atlas.latellu.com/docs/agent-skill](https://docs.atlas.latellu.com/docs/agent-skill).
+Add these two `export` lines to your shell profile (`~/.zshrc` or `~/.bashrc`) if you want them available in every new terminal, not just the current session.
+
+### Verify it worked
+
+Start `claude` in your project and ask it something like *"list the content types in my Atlas workspace"*. If it calls an Atlas tool and returns a real answer, setup is complete. If it says it has no Atlas tools available, double check the plugin installed (`claude plugin install atlas@latellu` again) and that both env vars are set in that same shell (`echo $ATLAS_LIVE_API_KEY`).
+
+Full guide: [docs.atlas.latellu.com/docs/agent-skill](https://docs.atlas.latellu.com/docs/agent-skill).
 
 ## Other agents (Cursor, Codex, opencode, Gemini CLI, ...)
 

package/adapters/other-agents.md

@@ -1,5 +1,9 @@
 # Using the Atlas skill outside Claude Code
 
+> New to Atlas or MCP? Read the [README](../README.md) first — it explains what MCP is
+> and the difference between `atlas_live_` (read-only) and `atlas_mgmt_` (read/write)
+> keys before you get here.
+
 The skill is plain markdown (`skills/atlas-cms/SKILL.md` + `references/`), so any AI
 coding agent can consume it. Install the package into your project, then point your
 agent at it.
@@ -39,8 +43,10 @@ file it routes you to.
 
 ## MCP server (any MCP-capable agent)
 
-The Atlas MCP server is a separate npm package (`@latellu/atlas-mcp`, stdio). Register it
-with your agent's MCP configuration:
+"Registering an MCP server" means telling your agent to launch this process and use the
+tools it exposes (list entries, publish page, etc.) — it's the same two API keys as
+above, just read by a different process. The Atlas MCP server is a separate npm package
+(`@latellu/atlas-mcp`, stdio). Register it with your agent's MCP configuration:
 
 ```json
 {

package/package.json

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

@@ -1,6 +1,6 @@
 ---
 name: atlas-cms
-description: Use when integrating with or operating Atlas CMS - fetching entries, pages, blocks or media into a frontend, generating TypeScript types from a workspace schema, writing/publishing/scheduling content programmatically, uploading media, or operating content through the Atlas MCP tools (list_entries, create_entry, publish_page, etc.). Trigger on mentions of Atlas CMS, @latellu/atlas-sdk, @latellu/atlas-cli, atlas_live_/atlas_mgmt_ API keys, or api.atlas.latellu.com.
+description: Use for any task that touches Atlas CMS, however casually phrased - fetching entries, pages, blocks or media into a frontend, generating/gen-ing TypeScript types from a workspace schema, writing/publishing/scheduling/pushing content programmatically, uploading media, or operating content through the Atlas MCP tools (list_entries, create_entry, publish_page, etc.). Always trigger on any mention of Atlas CMS, @latellu/atlas-sdk, @latellu/atlas-cli, atlas_live_/atlas_mgmt_ API keys, or api.atlas.latellu.com - including quick/informal asks like "gen the types for our repo" or "push some content into atlas real quick" - rather than answering from general knowledge, which risks hallucinating wrong package names or endpoints.
 ---
 
 # Atlas CMS
@@ -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).
@@ -84,16 +86,31 @@ 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 structured per-field error objects.
+This is about scale and recoverability, not run count: if the task touches more than a
+handful of entries, needs to survive partial failure and be safely re-run, or needs
+structured per-field error handling, that's the SDK management client — even if you'll
+only run it once. A 200-entry backfill script is an SDK job; MCP's "one-off" framing
+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

@@ -5,22 +5,73 @@
 browser-bundled code.
 
 ```ts
-import { createManagementClient, AtlasError } from "@latellu/atlas-sdk/management";
+import { createManagementClient, AtlasError, ManagementConfigError } from "@latellu/atlas-sdk/management";
 
-const client = createManagementClient<AtlasContentTypes>({
-  url: process.env.ATLAS_BASE_URL ?? "",    // https://api.atlas.latellu.com
-  token: process.env.ATLAS_MGMT_KEY ?? "",  // MUST start with atlas_mgmt_
+// ✅ CORRECT: Wrap construction in try/catch for config errors
+let client: ManagementClient<AtlasContentTypes> | null = null;
+
+try {
+  client = createManagementClient<AtlasContentTypes>({
+    url: process.env.ATLAS_BASE_URL ?? "https://api.atlas.latellu.com",
+    token: process.env.ATLAS_MGMT_KEY ?? "",  // MUST start with atlas_mgmt_
+  });
+} catch (e) {
+  if (e instanceof ManagementConfigError) {
+    // Configuration error — fail fast at startup
+    console.error("Failed to initialize Atlas:", e.message);
+    process.exit(1);
+  }
+  throw e;
+}
+
+if (!client) {
+  throw new Error("Atlas client not initialized");
+}
+
+// Now client is safely initialized and ready to use
+```
+
+**Common error scenario:**
+If someone accidentally uses an `atlas_live_` delivery key instead of `atlas_mgmt_`, they'll see:
+```
+ManagementConfigError: management client received an atlas_live_ delivery key, which is read-only. 
+You need an atlas_mgmt_ management key for writes. 
+Create one at cms.atlas.latellu.com/dashboard/api-keys
+```
+
+**Validate config without creating the client:**
+```ts
+import { validateManagementConfig } from "@latellu/atlas-sdk/management";
+
+const validation = validateManagementConfig({
+  url: process.env.ATLAS_BASE_URL ?? "",
+  token: process.env.ATLAS_MGMT_KEY ?? "",
 });
+
+if (!validation.valid) {
+  console.error("Invalid Atlas config:", validation.error);
+  if (validation.keyType === 'atlas_live_') {
+    console.error("→ Use an atlas_mgmt_ key (management key) instead");
+  }
+  process.exit(1);
+}
 ```
 
 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.
+- The token prefix is validated **synchronously at creation time**, not during API calls.
+  A non-`atlas_mgmt_` token (e.g., `atlas_live_` or malformed) throws `ManagementConfigError`
+  immediately with a descriptive message identifying what went wrong.
+- **Critical:** Wrap `createManagementClient(...)` in a try/catch block, **not just the
+  awaited calls**. Config errors are synchronous exceptions; request errors are rejected promises.
+- If you accidentally use an `atlas_live_` delivery key, the error message will explicitly
+  state that read keys cannot be used for management operations.
 - 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.
 
@@ -35,15 +86,20 @@ await w.create({ slug: "hello", data: { title: "Hello", body: "..." } });
 // 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):
+// update() is a FULL REPLACE of `data` (and of each locale in `translations`) — it does
+// NOT merge. To change only one field, you MUST read the current entry first and spread
+// its existing data/translations, or you will silently drop every other field:
+const readClient = createDeliveryClient<AtlasContentTypes>({ url, token: deliveryKey });
+const current = await readClient.entries("news-article").get("hello");
 await w.update("hello", {
-  data: fullBaseData,
-  translations: { de: { data: { title: "Hallo" } }, ja: { data: { title: "こんにちは" } } },
+  data: { ...current.data, category: "updated-category" },
+  translations: {
+    ...current.translations,
+    de: { data: { ...current.translations?.de?.data, title: "Hallo Welt" } },
+  },
 });
+// UpdateEntryInput = { slug?, data?, translations?, ... } — required+localizable fields
+// MUST live under translations[locale].data, not in the base `data` object.
 
 await w.publish("hello");                            // PATCH .../publish
 await w.unpublish("hello");                          // PATCH .../unpublish