← All playbooks · Raw API

task-media-review

# 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