@se-studio/contentful-cms 0.0.0-next16-20260822103555

package/docs/editor-tasks/media-pipeline-prepare.md

@@ -0,0 +1,175 @@
+# Capability: Media pipeline — prepare pack
+
+Normalize a **folder of designer masters** into short-lived **public HTTPS URLs** under cms-edit upload limits, then import into Contentful with reuse-first.
+
+**Never** expect the media pipeline service to write Contentful. Pipeline → ready URLs only. **cms-edit** owns assets/entries.
+
+## Intent phrases
+
+- process media folder
+- prepare Drive assets for CMS
+- media pipeline pack
+- normalize oversized images/videos
+- process case study assets
+- upload from media pipeline
+
+## Requires capabilities
+
+`assetSearch` and `assetUpload`
+
+## Prerequisites
+
+- Hosted cms-edit with media pipeline **configured on the host** (ops env):
+  - `MEDIA_PIPELINE_BASE_URL`
+  - `MEDIA_PIPELINE_SERVICE_KEY` (server-only — **never ask the agent/user for this**)
+  - `MEDIA_PIPELINE_TENANT` (e.g. `se`, not the cms-edit projectKey)
+- Drive folder shared **Viewer** with pipeline service account  
+  `media-pipeline-reader@se-media-pipeline.iam.gserviceaccount.com`  
+  (or “anyone with the link” if using API-key Drive mode on the pipeline).  
+  **If prepare/status reports `drive_inaccessible` or `drive_empty_or_unshared`:** fix the share first, then re-prepare **once**. Do not treat “no media files” as a wrong folder path until share is confirmed.
+- Profile default: `case-study-v1`
+
+## When to use
+
+| Situation | Action |
+|-----------|--------|
+| Drive/Figma package with large JPEGs/videos | **This task first**, then structure build |
+| Single small image already in library | `task-media-reuse-and-upload` only |
+| Masters already under limits and catalogued | Reuse search only |
+| Prior prepare already reached `succeeded` + catalog | **Reuse that jobId** — do not re-prepare the whole folder |
+
+## Steps (agent — single auth)
+
+### 1. Prepare
+
+Call MCP tool **`cms_edit_media`**:
+
+```json
+{
+  "action": "prepare",
+  "driveFolderUrl": "https://drive.google.com/drive/folders/…",
+  "profile": "case-study-v1",
+  "sourceNames": [
+    "BusinessCards copy.jpg",
+    "ArcticDB x3 Screens Tablet-1920.mp4",
+    "ADB_Macbook_HomeLoop.mp4"
+  ]
+}
+```
+
+| Param | On prepare |
+|-------|------------|
+| omit `sourceNames` | Encode **entire** folder (slow for large case-study packs) |
+| non-empty `sourceNames` | **Allowlist** — only exact Drive file names are downloaded/encoded |
+| `excludeSourceNames` | Skip these names (always) |
+
+CLI:
+
+```bash
+cms-edit media prepare --drive-folder "https://drive.google.com/drive/folders/…" \
+  --source-names "BusinessCards copy.jpg,ADB_Macbook_HomeLoop.mp4"
+```
+
+Expect `{ ok: true, jobId, status: "queued", pollHint }`.
+
+**Prefer prepare allowlist** whenever you only need og/hero/home (or a few masters). Names must match Drive display names exactly. Missing allowlist names appear as gaps (`not_found_in_folder`).
+
+If `{ ok: false, code: "pipeline_unconfigured" }` → host ops must set env vars. **Do not** ask the user for a pipeline API key.
+
+### 2. Wait / status
+
+```json
+{ "action": "wait", "jobId": "<jobId>" }
+```
+
+or
+
+```json
+{ "action": "status", "jobId": "<jobId>" }
+```
+
+**Pipeline lifecycle** (real pack states): `queued` → `running` → `succeeded` | `partial` | `failed`.
+
+| Status | Meaning | Agent action |
+|--------|---------|--------------|
+| `queued` / `running` | Pack is processing | Keep `wait` / `status` |
+| `succeeded` | All files ready | Proceed to catalog |
+| `partial` | Some ready; `gaps[]` lists failures | Catalog ready items; report gaps — **do not invent** assets for gaps |
+| `failed` | Nothing usable | Stop; report gaps |
+| `provisioning` | **Host soft state only** (not a pipeline phase): job is registered but pack status is not readable yet | Retry wait/status only while age is **under ~90s** |
+| `status_unavailable` (`ok: false`) | Soft grace exceeded; concurrent slot released | **Stop this jobId**. At most **one** new prepare. If the second also ends `status_unavailable`, **stop entirely** and report both jobIds (platform issue — the pack may still have completed on the pipeline). |
+
+**Rules:**
+
+- Do **not** invent assets for gaps.
+- Do **not** wait 5–10+ minutes on `provisioning`.
+- Do **not** thrash prepares (rate limit + concurrent max typically **2** per user).
+- On `429` / too many concurrent: call `status` once on any stuck old `jobId` (to free slots if past grace), then prepare again **once**.
+- Prefer **reusing** a job that already reached `succeeded` + catalog over preparing again for the same Drive folder.
+
+### 3. Catalog
+
+```json
+{ "action": "catalog", "jobId": "<jobId>" }
+```
+
+Each asset includes:
+
+| Field | Use |
+|-------|-----|
+| `readyUrl` | `asset upload --url` into Contentful |
+| `previewUrl` / `posterUrl` | Agent vision for **title / fileName / alt** (when present) |
+| `altDraft` / `titleDraft` | Filename seeds only — improve before save |
+
+### 4. Import into Contentful (reuse-first)
+
+After drafting titles/alts from **previewUrl** / **posterUrl**:
+
+**Prefer filtering** so unused files in a shared Drive folder are not uploaded:
+
+| Param | Use |
+|-------|-----|
+| `sourceNames` | Exact catalog `sourceName` allowlist (Drive file names) |
+| `excludeSourceNames` | Skip specific files |
+| `onlyWithOverrides` | Import only assets that have an `overrides` row (typical case-study path) |
+
+```json
+{
+  "action": "import",
+  "jobId": "<jobId>",
+  "withMedia": true,
+  "onlyWithOverrides": true,
+  "overrides": [
+    { "sourceName": "OM1_Hero.jpg", "title": "OM1 hero", "alt": "…", "fileName": "se-om1-hero-v3.jpg" }
+  ],
+  "dryRun": true
+}
+```
+
+1. Always **`dryRun: true` first** — check `existing: true/false` per asset (reuse is by **fileName**).
+2. When you need **new** assets instead of reusing prior runs, set `overrides[].fileName` to unique names.
+3. Then import without `dryRun`.
+
+CLI:  
+`cms-edit media import --job <id> [--dry-run] [--with-media] [--only-with-overrides] [--source-names a.jpg,b.jpg] [--exclude-source-names x.jpg] [--overrides-json '[…]']`
+
+Import:
+
+1. Filters catalog (allowlist / exclude / onlyWithOverrides)  
+2. Searches existing assets by fileName  
+3. Else uploads from `readyUrl` as the authenticated Contentful user  
+4. Returns `map`, `skipped[]`, and `counts` for page build  
+
+**Linking Media to components:** use singular Entry links with  
+`cms_edit ["set", "@cN", "visual", "<mediaId>", "--link"]`  
+— **never** `add … --target visual` (`add` only supports content **arrays**).
+
+Manual `asset upload --url` remains available for one-offs.
+
+### Hardening notes (for agents)
+
+- Jobs are **owned by the OAuth user** who prepared them — you cannot poll another user’s `jobId`.  
+- Rate limits apply (prepares/hour, concurrent jobs).  
+- Never document or request `MEDIA_PIPELINE_API_KEY` or Blob tokens in chat.
+- `provisioning` is **not** a real pipeline phase; do not treat it as “still encoding” for many minutes.
+- If the MCP client times out (~180s) on `set`/`rtf`/`import`, **read / catalog / diff before retrying** — the server may already have applied the change.

package/docs/editor-tasks/media-reuse-and-upload.md

@@ -0,0 +1,122 @@
+# Capability: Media — reuse and upload
+
+## Intent phrases
+
+- upload image
+- find existing asset
+- add photo to page or article
+- update person headshot / portrait
+
+## Requires capabilities
+
+`assetSearch` and `assetUpload`
+
+## Prerequisites
+
+- **Always run `index sync` first** if the catalog may be stale
+- On **hosted MCP**, the server has **no filesystem** — use **staged upload** for all binary uploads (never `--base64` or a local file path in `args`)
+
+## Reuse-first workflow (default)
+
+1. `cms_edit ["index", "sync"]`
+2. **Search existing assets:**
+   - `cms_edit ["asset", "search", "--filename-match", "<partial-name>"]`
+   - `cms_edit ["list", "--type", "media", "--asset-filename-match", "<partial>"]`
+3. If match found — link by asset ID or filename in `set` / `create from-json` (`featuredImageAssetFilename`, `visualAssetFilename`, etc.)
+4. For **`visuals`** (Media entry **array** on page/article): prefer an **existing Media entry** — `cms_edit ["list", "--type", "media", "--asset-id", "<assetId>"]` — then `set @root visuals <mediaEntryId> --links`. Do **not** `create media` or use `asset upload --with-media` when a wrapper already exists.
+5. For **singular** component fields (e.g. `visual` on a component):  
+   `cms_edit ["set", "@cN", "visual", "<mediaEntryId>", "--link"]`  
+   **Never** `add media --parent @cN --target visual` — `add --target` only works for Entry-link **arrays** (`content`, `contents`, …). Bad `add --target` is rejected; it used to orphan Media drafts.
+6. `create media` only when no Media entry wraps that asset (RTF embeds, or first article in a new composite batch — then **reuse that media ID** on sibling entries)
+7. Bare Contentful entry IDs work with `set` (no `@` required) for mid-session Media field tweaks (width/autoplay/loop) after import — `set <mediaEntryId> width 75`.
+
+## Upload only when no match
+
+### Oversized masters / whole Drive folders
+
+If files are near or over **4 MB** (hosted staged) or **10 MB** (URL/local), or the user shared a **Drive folder of masters**, do **not** improvise compression in chat.
+
+1. Run **`task-media-pipeline-prepare`** (Drive folder → ready public URLs under limits)
+2. Return here and import with **`--url`** + reuse-first filename search
+
+### Hosted MCP (default)
+
+**Always use staged upload** for ad-hoc small binaries. Do not pass base64 in `cms_edit` args — hosted MCP rejects `asset upload --base64`.
+
+1. `cms_edit_request_staged_upload` with `fileName`, `mimeType`, optional `byteLength`, optional `title`
+2. Run the returned `curlCommand` in a shell (POST file to `uploadUrl`)
+3. `cms_edit` with the returned `consumeArgs` (e.g. `["asset","upload","--staged","<uploadId>",…]`)
+
+Rules:
+
+- Staged upload keeps binary **out of MCP args** — only a short `uploadId` is passed to Contentful
+- Hosted limit: **4 MB** per file; **1000 upload URLs per user per hour**; TTL **60 minutes**; single-use
+- **PNG** when the source has transparency (portraits on brand-colour cards); JPEG flattens alpha
+- Upload alone does **not** attach the asset — follow with **link + save** (below)
+- Use `--if-exists-by-filename` (with `--file-name`) to avoid duplicate assets when re-running
+
+After staged upload, create a Media wrapper **only when none exists** for that asset:
+
+```
+cms_edit ["list", "--type", "media", "--asset-id", "<newPortraitAssetId>"]
+cms_edit ["create", "media", "--asset-id", "<newPortraitAssetId>"]
+```
+
+**Media entry `name` (CMS list label):** defaults to the **linked asset title**. Only pass `--name` when you deliberately need a different label (e.g. two Media wrappers on one asset with distinct roles). Never use `visual-{assetId}` or `Wrapper for {assetId}` — those are migration leftovers.
+
+To rename an existing Media wrapper: `cms_edit ["batch", "set", "<media-entry-id>:name=<asset-title>"]` then `batch save`.
+
+Avoid `asset upload --with-media` when multiple entries will share the same image (e.g. news composites) — it creates duplicate Media entries. Upload the asset only, then one shared `create media`, then link the media ID on each entry.
+
+**Prefer `--url`** when the file is already on **public HTTPS** under size limits — especially **media-pipeline ready pack URLs**:
+
+```
+cms_edit ["asset", "upload", "--url", "https://<public-https-url>/file.png", "--mime", "image/png", "--file-name", "headshot-name-1200.png", "--title", "…", "--if-exists-by-filename"]
+```
+
+The URL must be fetchable by the hosted MCP server. Do not use local-only URLs.
+
+### Local CLI (only when user approves)
+
+Local `cms-edit` may use `--base64` or `--url` when the user explicitly approves local CLI (see repo `Agents.md`). Hosted agents must not use local CLI without permission.
+
+## Link uploaded asset to an entry
+
+Upload returns an **asset ID**. Attach it, then save:
+
+**Person portrait (`media` is an Asset link):**
+
+```
+cms_edit ["open", "--id", "<person-entry-id>"]
+cms_edit ["asset", "set", "@root", "media", "<new-asset-id>"]
+cms_edit ["diff"]
+cms_edit ["save"]
+```
+
+**Component `visual` (Media Entry link, singular):**
+
+```
+cms_edit ["set", "@cN", "visual", "<media-entry-id>", "--link"]
+```
+
+**Article featured image / asset fields:** `asset set <ref> <field> <asset-id>` (or `set … --asset`) when the field is an Asset link.
+
+Always `diff` → `save`. Verify with `preview urls` on the public path.
+
+## Confirmation gates
+
+1. Report search results before uploading
+2. Confirm upload filename/title with user if ambiguous
+3. After upload, confirm `asset info <id>` shows expected width/height/size before linking
+
+## Out of scope
+
+- Publish assets (draft upload; human publishes in Contentful UI if needed)
+- Deleting orphan assets from failed uploads (human cleanup in Contentful)
+
+## Related resources
+
+- `task-media-pipeline-prepare`
+
+- `cms-edit://customer/defaults` (featured image rules)
+- `cms-edit://customer/people` (person `media` field, when present)

package/docs/editor-tasks/media-review.md

@@ -0,0 +1,139 @@
+# Capability: Media — quality review
+
+## Intent phrases
+
+- audit CMS images
+- media review
+- find oversized images
+- missing alt text across the space
+- unused assets
+- review videos and animations
+
+## Requires capabilities
+
+`assetSearch` (index sync + asset review)
+
+## Prerequisites
+
+1. Read `cms-edit://customer/overview` — note **production site URL** (if set) for prod link columns
+2. Read `cms-edit://customer/capabilities` — `projectKey`, space ID
+3. **`index sync`** if the catalog may be stale
+4. **Local CLI / Cursor:** `CONTENTFUL_PREVIEW_ACCESS_TOKEN` and `CMS_EDIT_TOKEN` (usage resolution needs CMA)
+5. **Hosted MCP:** do not pass `--space`; never combine `--include-passing`, `--include-usage`, and `--usage-limit 0` (timeouts)
+
+## What gets checked
+
+| Check | Issue code | Severity |
+|-------|------------|----------|
+| Descriptive filename | `bad_filename` | fail |
+| Alt text present | `missing_alt` | fail |
+| Alt text quality | `weak_alt` | fail |
+| Width ≤ max (not SVG/Lottie) | `oversized_width` | fail |
+| File size limits | `oversized_file` | fail / warn |
+| Animated GIF | `animated_gif` | fail |
+| No media wrapper in index | `no_media_wrapper` | warn |
+
+Default thresholds: max width **2000px**, images **800 KB**, video **8 MB**, Lottie **400 KB**. Override with CLI flags (see `cms-edit help asset-review`).
+
+## Phase 1 — Sync index
+
+**Hosted MCP:**
+
+```
+cms_edit ["index", "sync"]
+```
+
+**Local CLI:**
+
+```bash
+cms-edit index sync
+# multi-space: cms-edit index sync --space <projectKey>
+```
+
+Default: **Preview API** (drafts). Use `--published` on sync and review for delivery-only content.
+
+## Phase 2 — Quality audit (failures)
+
+**Hosted MCP:**
+
+```
+cms_edit ["--json", "asset", "review"]
+```
+
+**Local CLI:**
+
+```bash
+cms-edit --json-output asset review > docs/media-review-failures.json
+```
+
+Exit code **1** when any asset fails (expected for remediation workflows).
+
+## Phase 3 — Usage and likely-unused (optional, slower)
+
+Resolves slug-bearing CMS ancestors (page, article, tag, person, etc.) per asset.
+
+**Hosted MCP** (capped — default 50 assets):
+
+```
+cms_edit ["--json", "asset", "review", "--include-usage", "--usage-limit", "50"]
+```
+
+For a larger sample on hosted, raise the limit in steps (e.g. `100`) — do not use `0` on hosted MCP.
+
+**Local CLI** (full inventory):
+
+```bash
+cms-edit --json-output asset review \
+  --include-passing --include-usage --usage-limit 0 \
+  > docs/media-review-full.json
+```
+
+JSON fields when usage runs: `usages[]` per asset (`slug`, `label`, `contentType`), plus `usageLimit`, `usageResolvedCount`, `usageTruncated`.
+
+**Likely unused:** `usages` empty **and** `no_media_wrapper` warning — verify manually (rich-text embeds may not create a media wrapper).
+
+## Phase 4 — Production URLs (spreadsheet)
+
+Read production base URL from `cms-edit://customer/overview` or `capabilities.json` → `website.productionSiteUrl`.
+
+If missing, check the app `.env.example` for `SITEMAP_PROD_URL` or `PRODUCTION_SITE_URL`, or ask the user once.
+
+For each `usages[].slug`, prod URL = `{productionSiteUrl}{slug}` (slug usually starts with `/`).
+
+## Phase 5 — Deliverables
+
+Use skill **`contentful-cms-media-review`** for:
+
+- Excel workbook (`Issues` + `Summary` sheets) from failures JSON
+- Executive summary (counts, top issue types, quick wins)
+- Optional image guide extension (full inventory + `docs/descriptions/{assetId}.json` cache)
+
+Default output path: `docs/media-review-<projectKey>-<date>.xlsx`.
+
+## Phase 6 — Fixes (optional, user-approved)
+
+Alt text only — asset-level, draft:
+
+```
+cms_edit ["asset", "set-description", "<asset-id>", "Descriptive alt text"]
+```
+
+Do **not** publish assets. For per-page context fixes, use skill `contentful-cms-alt-text-audit`.
+
+## Confirmation gates
+
+1. **Propose** scope (failures only vs full inventory + usage) — user approves
+2. **Read-only** by default — no `asset set-description` without explicit approval
+3. **Summarize** findings before any fix pass
+
+## Out of scope
+
+- Publish assets or entries
+- Definitive “live on production” verification (optional dev crawl of `ctfassets.net/{assetId}` — not automated here)
+- Bulk asset re-upload or dimension resizing in Contentful
+
+## Related resources
+
+- `cms-edit://customer/task-media-reuse-and-upload` — search/reuse before upload
+- `cms-edit help asset-review` — CLI flags and thresholds
+- Skill `contentful-cms-media-review` — spreadsheet schema and image-guide extension

package/docs/editor-tasks/navigation.md

@@ -0,0 +1,39 @@
+# Capability: Navigation
+
+## Intent phrases
+
+- update menu
+- change navigation links
+- edit footer
+
+## Requires capabilities
+
+`navigation`
+
+## Prerequisites
+
+- Read `cms-edit://customer/routing` for URL shapes
+- `cms_edit ["index", "sync"]` for navigation entry lookup
+
+## Steps
+
+1. `cms_edit ["list", "--type", "navigation"]` — find nav entry
+2. `cms_edit ["nav", "open", "--id", "<navigationId>"]` or by slug
+3. `snapshot` — inspect nav items
+4. Add/clone/link items per navigation commands
+5. `diff` → `save`
+
+See `contentful-cms-navigation` skill for full command reference in dev environments.
+
+## Confirmation gates
+
+1. Confirm which menu (header/footer) and link changes
+2. `diff` before `save`
+
+## Out of scope
+
+- Publish
+
+## Related resources
+
+- `cms-edit://customer/routing`

package/docs/editor-tasks/preview-verify.md

@@ -0,0 +1,93 @@
+# Capability: Preview verification
+
+## Intent phrases
+
+- preview changes
+- check staging
+- verify page looks right
+- open in browser
+
+## Requires capabilities
+
+Always available.
+
+## Prerequisites
+
+- Draft saved (`save` creates drafts)
+- Staging URL from `cms-edit://customer/overview` or `capabilities.json` → `website.devBaseUrl`
+- Entry ID from session (after `open` / `save`) or `--entry-id`
+
+## Preview targets
+
+After saving a draft, agents should return **all applicable URLs** and explain which to use when.
+
+| Target | Label | When to use |
+|--------|-------|-------------|
+| **contentfulLivePreview** | Live preview (publish here) | **Primary for editors when `url` is present.** Opens `app.contentful.com/.../entries/.../preview/...` — in-app preview with inspector. User clicks the green **Publish** button at the top to go live. If `url` is `null`, read `unavailableReason` / `notes` — do not invent a Live Preview link; use **staging** + **contentfulEntry** instead. |
+| **staging** | Preview (staging site) | Full-page check on staging, e.g. `{devBaseUrl}/resources/news/{tag}/{slug}/` (includes Vercel bypass params when configured). Always valid for draft visibility when staging is configured. |
+| **siteLivePreview** | Preview redirect | `{devBaseUrl}/preview?id={entryId}` — entry-aware redirect to the staging path. |
+| **production** | Production site | Published content only — compare after publish. |
+| **contentfulEntry** | Contentful entry editor | Classic entry form. Prefer **Live preview** when available; otherwise this is the publish path. |
+
+## Steps
+
+1. After `save`, list all preview URLs:
+   ```
+   cms_edit ["preview", "urls", "<slug>"]
+   ```
+   Or with explicit entry ID:
+   ```
+   cms_edit ["preview", "urls", "<slug>", "--entry-id", "<entry-id>"]
+   ```
+   Use `--json` for machine-readable output.
+
+2. **Hand off to the editor:**
+   - **Live preview** — when `url` is non-null: reviewing the draft and publishing (green Publish button in Contentful).
+   - **Preview (staging site)** — full-screen check on the staging deployment (always offer when available).
+   - If Live Preview is unavailable, say so briefly using `unavailableReason` and point at staging + classic entry editor.
+
+3. Summarize what to check before publish handoff — use the checklist below (add multi-block items when relevant).
+
+### What to check (all drafts)
+
+- [ ] Headings: page H1 from hero/template only; no invented body section titles
+- [ ] CTAs / links resolve
+- [ ] Images and featured/OG media present and roughly correct crop
+- [ ] Template blocks not duplicated in `content`
+
+### Multi-block / package builds (extra)
+
+When the draft was built from a soft-proof or multi-block plan:
+
+- [ ] **Sequence** matches the agreed soft-proof (no silent reordering)
+- [ ] **Placeholders** for GO-WITH-GAPS slots still present and labeled (not dropped)
+- [ ] **No invented pairs** — side-by-side collections only where the source was a true pair
+- [ ] **Copy** is the source text structured into blocks — not rewritten
+- [ ] Media behaviour per site playbook (e.g. decorative video autoplay/loop, width %)
+- [ ] Adjacent body-only sections may look airy on some sites (known section spacing) — flag, don’t invent empty paragraphs to “fix”
+
+### Legacy single URL
+
+```
+cms_edit ["preview", "url", "--page-slug", "<slug>"]
+```
+
+Returns the staging preview path only.
+
+## Confirmation gates
+
+1. Confirm draft saved before preview
+2. Summarize what to check (headings, CTAs, images; multi-block soft-proof items when relevant)
+3. Tell user production URL will not show draft content until published
+
+## Out of scope
+
+- Publish (human uses Live preview → Publish button)
+- Rewriting copy during QA
+
+## Related resources
+
+- `cms-edit://customer/overview`
+- `cms-edit://customer/task-publish-handoff`
+- `cms-edit://customer/task-source-readiness-review`
+- `cms-edit://customer/production-site`

package/docs/editor-tasks/publish-handoff.md

@@ -0,0 +1,41 @@
+# Capability: Publish handoff
+
+## Intent phrases
+
+- publish changes
+- go live
+- make changes live
+
+## Requires capabilities
+
+Always available.
+
+## What cms-edit does
+
+- Creates and updates **drafts only**
+- **Cannot** publish, unpublish, archive, or delete published entries
+
+## Handoff steps
+
+1. Ensure all edits are saved (`diff` was reviewed)
+2. Run `cms_edit ["preview", "urls", "<slug>"]` (or use session entry id after save)
+3. Give the user **both** links:
+   - **Live preview (publish here)** — `app.contentful.com/.../entries/.../preview/...` — open this to review and click the green **Publish** button at the top
+   - **Preview (staging site)** — full staging URL for a full-page check (optional)
+4. Tell the user which entry was changed (title, slug, CMS label)
+5. Remind them: production URL updates 1–3 minutes after publish
+
+## Confirmation gates
+
+1. Never claim changes are live until a human publishes
+2. Always include the **Live preview** link when `contentfulLivePreview` is available
+3. List draft entries awaiting publish
+
+## Out of scope
+
+- Automated publish (intentionally unsupported)
+
+## Related resources
+
+- `cms-edit://customer/task-preview-verify`
+- `cms-edit://customer/overview`

package/docs/editor-tasks/seo-descriptions.md

@@ -0,0 +1,48 @@
+# Capability: SEO meta descriptions
+
+## Intent phrases
+
+- update meta descriptions
+- improve SEO for Google
+- change page descriptions for search
+
+## Requires capabilities
+
+`pages` or `articles`
+
+## Prerequisites
+
+- Field name is **`description`** (meta description) on pages and articles
+- `cms_edit ["list", "--type", "page"]` for page inventory
+
+## Steps
+
+**Per entry (hosted editors):**
+
+1. `cms_edit ["open", "--page-slug", "<slug>"]`
+2. `cms_edit ["set", "@p0", "description", "<new meta description>"]`
+3. `cms_edit ["diff"]` → `cms_edit ["save"]`
+
+**Many entries with known IDs:**
+
+```
+cms_edit ["batch", "set", "<pageId>:description=…", …]
+cms_edit ["batch", "save"]
+```
+
+**Dev agents only** — if `capabilities.devTools.cmsSeoAudit` is true, developers may run the site's `cms:seo-audit` CSV workflow locally. Hosted editors should use per-entry updates above.
+
+## Confirmation gates
+
+1. Propose new descriptions (or selection of pages) — user approves
+2. `diff` before `save`
+
+## Out of scope
+
+- Publish
+- Keyword research (descriptions are editorial)
+
+## Related resources
+
+- `cms-edit://customer/routing`
+- `cms-edit://customer/brand` (if present)