@latellu/atlas-agent-skills 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "latellu",
+  "description": "Official Latellu plugins for Claude Code, including the Atlas CMS plugin (MCP server + agent skill).",
+  "owner": {
+    "name": "Latellu",
+    "url": "https://github.com/tenriajeng"
+  },
+  "plugins": [
+    {
+      "name": "atlas",
+      "source": {
+        "source": "npm",
+        "package": "@latellu/atlas-agent-skills"
+      },
+      "description": "Atlas CMS for Claude Code: the atlas-cms skill (SDK, CLI and MCP usage guidance) plus the bundled Atlas MCP server for reading and writing content from AI agents."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "atlas",
+  "version": "0.1.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",
+    "url": "https://github.com/tenriajeng"
+  },
+  "homepage": "https://docs.atlas.latellu.com/docs/claude-code",
+  "repository": "https://github.com/tenriajeng/atlas-agent-skills",
+  "license": "MIT",
+  "keywords": ["atlas", "cms", "headless-cms", "mcp", "sdk"]
+}

package/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "atlas": {
+      "command": "npx",
+      "args": ["-y", "@latellu/atlas-mcp"],
+      "env": {
+        "ATLAS_LIVE_API_KEY": "${ATLAS_LIVE_API_KEY}",
+        "ATLAS_MGMT_API_KEY": "${ATLAS_MGMT_API_KEY}",
+        "ATLAS_API_URL": "${ATLAS_API_URL:-https://api.atlas.latellu.com}",
+        "MCP_ALLOWED_UPLOAD_PATHS": "${MCP_ALLOWED_UPLOAD_PATHS:-}"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Latellu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# Atlas Agent Skills
+
+Agent skill + MCP configuration for **[Atlas CMS](https://docs.atlas.latellu.com)** — teaches AI coding agents when and how to use the Atlas MCP tools, the [`@latellu/atlas-sdk`](https://www.npmjs.com/package/@latellu/atlas-sdk) delivery/management clients, and the [`@latellu/atlas-cli`](https://www.npmjs.com/package/@latellu/atlas-cli) type generator.
+
+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.
+
+## Claude Code
+
+```bash
+claude plugin marketplace add tenriajeng/atlas-agent-skills
+claude plugin install atlas@latellu
+```
+
+Then set your credentials 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/claude-code](https://docs.atlas.latellu.com/docs/claude-code).
+
+## Other agents (Cursor, Codex, opencode, Gemini CLI, ...)
+
+```bash
+npm install -D @latellu/atlas-agent-skills
+```
+
+Then point your agent at the skill (via `AGENTS.md`, Cursor rules, etc.) and register the MCP server — see [`adapters/other-agents.md`](adapters/other-agents.md).
+
+## What's inside
+
+| 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 |
+| `.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 |
+
+## Releasing
+
+Bump `version` in `package.json` (and `.claude-plugin/plugin.json`), tag `vX.Y.Z`, push the tag — CI publishes to npm. The Claude Code marketplace resolves the plugin from npm, so users pick up the new version on `claude plugin marketplace update latellu`.
+
+## License
+
+[MIT](LICENSE)

package/adapters/other-agents.md

@@ -0,0 +1,66 @@
+# Using the Atlas skill outside Claude Code
+
+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.
+
+```bash
+npm install -D @latellu/atlas-agent-skills
+```
+
+## AGENTS.md-based agents (Codex, opencode, Gemini CLI, Jules, Amp, ...)
+
+Add to your project's `AGENTS.md`:
+
+```markdown
+## Atlas CMS
+
+When a task involves Atlas CMS (entries, pages, media, @latellu/atlas-sdk,
+@latellu/atlas-cli, atlas_live_/atlas_mgmt_ keys, or api.atlas.latellu.com), first read
+node_modules/@latellu/atlas-agent-skills/skills/atlas-cms/SKILL.md and follow its
+routing table — it links to detailed references per surface (MCP, SDK read, SDK write,
+CLI type generation). Do not guess Atlas API shapes from memory.
+```
+
+## Cursor
+
+Create `.cursor/rules/atlas-cms.mdc`:
+
+```markdown
+---
+description: Atlas CMS integration guidance (SDK, CLI, MCP)
+alwaysApply: false
+---
+
+When working with Atlas CMS, read
+node_modules/@latellu/atlas-agent-skills/skills/atlas-cms/SKILL.md and the reference
+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:
+
+```json
+{
+  "mcpServers": {
+    "atlas": {
+      "command": "npx",
+      "args": ["-y", "@latellu/atlas-mcp"],
+      "env": {
+        "ATLAS_LIVE_API_KEY": "atlas_live_xxx...",
+        "ATLAS_MGMT_API_KEY": "atlas_mgmt_xxx..."
+      }
+    }
+  }
+}
+```
+
+- Cursor: `~/.cursor/mcp.json` or `.cursor/mcp.json`
+- Codex CLI: `~/.codex/config.toml` (`[mcp_servers.atlas]`)
+- opencode: `opencode.json` (`"mcp"` section)
+- Others: consult your agent's MCP docs; the command/env above are the same everywhere.
+
+See [docs.atlas.latellu.com/docs/mcp](https://docs.atlas.latellu.com/docs/mcp) for the
+tool catalog and key setup.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@latellu/atlas-agent-skills",
+  "version": "0.1.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)",
+  "homepage": "https://docs.atlas.latellu.com/docs/claude-code",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tenriajeng/atlas-agent-skills.git"
+  },
+  "keywords": ["atlas", "cms", "headless-cms", "mcp", "agent", "skill", "claude-code"],
+  "files": [
+    ".claude-plugin",
+    ".mcp.json",
+    "skills",
+    "adapters",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/atlas-cms/SKILL.md

@@ -0,0 +1,55 @@
+---
+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.
+---
+
+# Atlas CMS
+
+A router, not a knowledge dump. Read the shared concepts below (always), then load
+**only** the reference file for the surface you are actually using.
+
+## Shared concepts
+
+**Content model.** A *workspace* contains *content types* (schemas). A content type has
+*entries* (structured records with a `slug`, a `status`, and a `data` field map). A
+workspace also has *pages*: a page has SEO metadata and an ordered tree of *blocks*
+(`{ id, type, position, data }`). Localized content is delivered as base-locale data plus
+a `translations` array; readers merge a requested locale field-by-field with fallback to
+the base locale.
+
+**Two API key classes**, both sent as the `X-API-Key` header (never `Authorization`):
+
+| Key prefix | Plane | Base path | Can do |
+|---|---|---|---|
+| `atlas_live_*` | Delivery (read) | `/api/v1/public` | Read published entries, pages, media, schema |
+| `atlas_mgmt_*` | Management (write) | `/api/v1/manage` | Create/update/publish/delete content, upload media |
+
+- Keys are minted in the dashboard: `cms.atlas.latellu.com/dashboard/api-keys`.
+- Default base URL: `https://api.atlas.latellu.com` (override only for self-hosted).
+- **Workspace scoping is implicit in the key.** There is no workspace parameter anywhere;
+  a key reaches exactly one workspace.
+- Management keys act as a service actor bound to the RBAC permissions of the person who
+  created them, further limited by scopes: `content:write`, `content:publish`,
+  `media:write`. A missing scope returns 403 on that specific operation.
+- Production `atlas_live_*` keys only ever see **published** content. Draft content is
+  not reachable through them, regardless of query parameters.
+
+**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).
+
+## Which surface do I use?
+
+| You are... | Use | Read |
+|---|---|---|
+| Building a frontend that renders Atlas content | SDK delivery client | [references/sdk-delivery.md](references/sdk-delivery.md) |
+| 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) |
+
+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.
+
+## Extending
+
+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/cli-typegen.md

@@ -0,0 +1,51 @@
+# CLI type generation
+
+Generates TypeScript interfaces for a workspace from `/api/v1/public/schema`.
+
+```bash
+npx @latellu/atlas-cli generate --api-key=atlas_live_xxx --output=./lib/atlas.types.ts
+# or, installed globally, the binary is named atlas-cms (not atlas-cli):
+atlas-cms generate --api-key=atlas_live_xxx
+```
+
+| Flag | Env fallback | Default |
+|---|---|---|
+| `--api-key` | `ATLAS_API_KEY` | (required) |
+| `--url` | `ATLAS_API_URL` | `https://api.atlas.latellu.com` |
+| `--output` | `ATLAS_OUTPUT` | `./src/atlas.types.ts` |
+
+Flags win over env vars. If `--output` doesn't end in `.ts` it is treated as a directory
+and `atlas.types.ts` is appended. The workspace is derived server-side from the key.
+
+## Output anatomy
+
+- One `export interface <PascalCaseSlug>` per content type, plus
+  `export type Locale = "en" | "ja" | ...` from the workspace locales.
+- A registry mapping slugs to interfaces — feed it to the SDK for full typing:
+
+```ts
+import { createClient } from "@latellu/atlas-sdk";
+import type { AtlasContentTypes } from "./atlas.types";
+
+const atlas = createClient<AtlasContentTypes>({ url, apiKey });
+const article = await atlas.entries("news-article").get("hello"); // data is typed
+```
+
+## Type semantics (what the generated types do and don't promise)
+
+- `select` fields with options → string-literal unions (`"News" | "Event"`).
+- `number` → `number`, `boolean` → `boolean`; `text`/`textarea`/`richtext`/`date` → `string`.
+- **`image`, `relation`, `content_type_reference` → plain `string`** — the raw media ID or
+  entry slug, never a resolved object. Resolve manually via `atlas.media.get(id)` /
+  `atlas.entries(type).get(slug)`.
+- **Localizable fields are only marked with a `// localizable` comment**; the value is
+  typed as the base-locale scalar (no per-locale map in this release).
+- Optional (`?`) mirrors non-required fields; non-identifier field names are quoted.
+- A content type with zero fields renders as `{ [key: string]: unknown }`; unknown field
+  types degrade to `unknown` instead of failing codegen.
+
+## Rules
+
+- The file is generated (`// Generated by @latellu/atlas-cli — DO NOT EDIT BY HAND.`) —
+  never hand-edit; **regenerate after every schema change** in the dashboard.
+- A 401 means the API key is wrong or revoked (the error says so); check `--api-key`.

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

@@ -0,0 +1,63 @@
+# Atlas MCP tools
+
+The plugin bundles the `@latellu/atlas-mcp` server (stdio). Read tools need
+`ATLAS_LIVE_API_KEY`; write tools need `ATLAS_MGMT_API_KEY`. With only one key set, the
+other half of the tools fails client-side naming the missing variable. If neither is set
+the server exits at startup. `ATLAS_API_URL` overrides the base URL for self-hosted.
+
+## Tool catalog
+
+**Schema & discovery** (live key)
+- `get_workspace_schema` — workspace meta (slug, locales, default locale) + all content types.
+- `list_content_types` / `get_content_type(content_type)` — convenience views over the schema.
+
+**Entries** (read: live key; write: mgmt key)
+- `list_entries(content_type, page?, limit?, status?)`
+- `get_entry(content_type, slug)`
+- `create_entry(content_type, data, slug?)` — creates a **draft**; slug auto-generated if omitted.
+- `update_entry(content_type, slug, data)`
+- `publish_entry` / `unpublish_entry` / `archive_entry` / `duplicate_entry` / `delete_entry` — all `(content_type, slug)`.
+
+**Pages** (read: live; write: mgmt)
+- `list_pages(page?, limit?)` / `get_page(slug)`
+- `create_page(title, slug?, blocks?, seo?)` — creates a draft. `seo` accepts `title`/`description` only.
+- `update_page(slug, title?, blocks?, seo?)` / `publish_page(slug)` / `delete_page(slug)`
+
+**Media**
+- `get_media(id)` (live key)
+- `upload_media(file_path, folder?, alt_text?)` (mgmt key) — reads a local file and uploads it.
+
+## Recommended workflow for writes
+
+1. Call `get_content_type` (or `get_workspace_schema`) first to learn the exact field
+   names and types. `data` is an unvalidated map — the backend rejects bad shapes with a
+   400, and per-field validation detail is **not** surfaced through MCP (you only see
+   `Atlas API error: 400 - validation failed`).
+2. `create_entry` / `update_entry` with a `data` object matching the schema.
+3. `publish_entry` when ready (requires the `content:publish` scope on the key).
+
+## Gotchas
+
+- **`update_entry` is a full replace** of `data`, not a patch. Read the entry first,
+  merge your change, then send the complete object (read-modify-write).
+- **Page lifecycle is asymmetric**: there is no `unpublish_page`, `archive_page`, or
+  `duplicate_page` tool. There are also no bulk, schedule, or block-reorder tools, and no
+  `delete_media`/`update_media`. For those, use the dashboard or the SDK management
+  client (see `sdk-management.md`).
+- **`get_page` returns each block's `data` as a JSON-encoded string**, not an object.
+  Parse it before reading fields — otherwise blocks look empty.
+- **`get_entry` resolves by slug alone**; its `content_type` argument is accepted but not
+  sent to the backend. Don't rely on it to disambiguate slugs shared across types.
+- **Drafts are invisible to live keys.** `list_entries(status="draft")` with a production
+  key returns nothing — that is key scoping, not an empty workspace.
+- **Uploads are validated server-side only**: max 10 MB; MIME must be `image/*`,
+  `video/*`, or `application/pdf`. MIME is inferred from the file extension; unknown
+  extensions become `application/octet-stream` and are always rejected (e.g. `.svg`,
+  `.heic`). Check size and extension before calling `upload_media`. If
+  `MCP_ALLOWED_UPLOAD_PATHS` is set, `file_path` must live under one of those directories.
+- **No client-side retry on 429.** On `Atlas API error: 429 - ...`, back off
+  (exponentially) and retry yourself.
+- **`delete_entry` / `delete_page` return plain text** ("Entry 'x' deleted successfully"),
+  unlike every other tool, which returns JSON.
+- Every write automatically sends a fresh `Idempotency-Key` header per call; identical
+  retries you issue as *new tool calls* are new operations, not deduplicated.

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

@@ -0,0 +1,82 @@
+# SDK delivery client (read)
+
+```bash
+npm install @latellu/atlas-sdk        # Node 18+ (uses global fetch)
+```
+
+## Canonical setup (Next.js thin adapter)
+
+Keep one server-only adapter, e.g. `lib/atlas.ts`:
+
+```ts
+import "server-only";
+import { createClient } from "@latellu/atlas-sdk";
+import type { AtlasContentTypes } from "./atlas.types"; // generated — see cli-typegen.md
+
+// The SDK sets NO cache directive. In Next.js you must decide caching yourself
+// via a custom fetchImpl, or Next's defaults for un-annotated fetch apply.
+const noStoreFetch: typeof fetch = (input, init) =>
+  fetch(input, { ...init, cache: "no-store" }); // or next: { revalidate: 60 }
+
+export const atlas = createClient<AtlasContentTypes>({
+  url: process.env.ATLAS_BASE_URL ?? "",     // https://api.atlas.latellu.com
+  apiKey: process.env.ATLAS_API_KEY ?? "",   // atlas_live_...
+  fetchImpl: noStoreFetch,
+});
+```
+
+With `no-store`, pair route files with `export const dynamic = "force-dynamic"` so
+dashboard edits appear immediately. The SDK reads no env vars itself — `url`/`apiKey`
+must be passed explicitly. `createClient` throws synchronously if either is missing.
+
+## Surface
+
+```ts
+const { items, total, page, pageSize } =
+  await atlas.entries("news-article").list({ locale: "en", page: 1, limit: 20, sort: "created_at:desc" });
+
+const entry = await atlas.entries("news-article").get("hello-world", { locale: "en" }); // null on 404
+// entry: { id, slug, status, published_at, data }  — data is already parsed to an object
+
+const pages = await atlas.pages.list({ locale: "en", page: 1, limit: 20 }); // summaries, no blocks
+const pageDetail = await atlas.pages.get("home", { locale: "en" });         // null on 404
+// pageDetail: { id, slug, status, seo, blocks: [{ id, type, position, data }] }
+
+const asset = await atlas.media.get(mediaId);      // null on 404
+const raw = await atlas.raw.get<T>("/some/path");  // escape hatch for unwrapped /api/v1/public paths
+```
+
+Semantics the SDK handles for you (don't re-implement):
+- `entry.data`, page `seo`, and block `data` arrive from the API as JSON strings — the
+  SDK parses them.
+- Locale merge is field-by-field: translated fields overlay base data; untranslated
+  fields fall back to the base locale.
+- Page blocks are always returned sorted by `position`, regardless of API order.
+
+Errors: non-404 failures throw `AtlasError` (`{ status?, code?, message }`). `get()`
+methods return `null` only for 404.
+
+## Rendering blocks
+
+Dispatch on `block.type` with an explicit fallback so new block types added in the
+dashboard never crash the site:
+
+```tsx
+export function BlockRenderer({ blocks }: { blocks: AtlasBlock[] }) {
+  return blocks.map((block) => {
+    switch (block.type) {
+      case "hero":   return <HeroBlock key={block.id} data={block.data} />;
+      case "faq":    return <FaqBlock key={block.id} data={block.data} />;
+      default:       return null; // or an <UnknownBlock /> placeholder
+    }
+  });
+}
+```
+
+## Limits
+
+- Draft preview is not yet supported by the SDK — delivery keys see published content only.
+- There is no `search` or `schema` namespace on the client; schema introspection is the
+  CLI's job (`cli-typegen.md`).
+- `image` / `relation` / `content_type_reference` field values are raw string IDs/slugs —
+  resolve with `atlas.media.get(id)` or `atlas.entries(type).get(slug)`.

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

@@ -0,0 +1,60 @@
+# SDK management client (write)
+
+Server-side only. Never import this module or expose an `atlas_mgmt_*` key in
+browser-bundled code.
+
+```ts
+import { createManagementClient, AtlasError } 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_
+});
+```
+
+`createManagementClient` throws `ManagementConfigError` **synchronously** if the token
+doesn't start with `atlas_mgmt_` (e.g. you passed a live key) — wrap construction in
+try/catch, not just the calls. Requests go to `/api/v1/manage` with `X-API-Key`.
+
+## Surface
+
+```ts
+const w = client.entries("news-article");
+await w.create({ slug: "hello", data: { title: "Hello" } });
+await w.update("hello", { data: { title: "Hello v2" } });
+await w.publish("hello");            // needs content:publish scope
+await w.unpublish("hello");
+await w.archive("hello");
+await w.schedule("hello", "2026-08-01T09:00:00Z");
+await w.duplicate("hello");
+await w.delete("hello");
+await w.bulk([{ op: "publish", id: "..." }, ...]);
+
+await client.pages.create({ slug: "landing", /* ... */ });
+await client.pages.update("landing", { /* ... */ });
+await client.pages.publish("landing");     // also: unpublish, archive, schedule, delete
+await client.pages.blocksReorder("landing", ["block-id-1", "block-id-2"]);
+
+const asset = await client.media.upload(fileBlob, { alt: "Team photo" }); // multipart
+await client.media.delete(asset.id);
+```
+
+Every write accepts an optional trailing `{ idempotencyKey: "..." }` — pass a stable key
+when a retry must not double-create/double-publish.
+
+## Built-ins
+
+- **429s are retried automatically** (exponential backoff from 200 ms, up to 3 retries).
+  Not configurable.
+- **Validation errors carry per-field detail** (unlike MCP): `AtlasError.errors` is
+  `{ field, message }[]` on 400s — surface it to users instead of the generic message.
+- Scopes: `content:write` covers create/update/delete/duplicate; `content:publish` covers
+  publish/unpublish/archive/schedule; `media:write` covers uploads. Missing scope → 403.
+
+## Effect-native variant
+
+`@latellu/atlas-sdk/management/effect` exports `makeManagementClient` with the same shape
+where every method returns `Effect.Effect<T, AtlasError>`. The plain Promise client above
+never bundles `effect`. If you run Effects yourself, note `Effect.runPromise` rejects
+with a `FiberFailure` wrapper — recover the original `AtlasError` via
+`Runtime.isFiberFailure` + `Cause.squash` (the Promise surface already does this for you).