@latellu/atlas-agent-skills 0.5.2 → 0.5.3

package/.claude-plugin/plugin.json

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

@@ -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.5.3",
   "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

@@ -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
@@ -84,6 +84,11 @@ 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)
 

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

@@ -5,18 +5,66 @@
 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.
@@ -35,15 +83,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