# 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.** If `url` is `null` (often CMA 404), read `unavailableReason` — **not a failed save**. Do not invent a Live Preview link. |
| **staging** | Preview (staging site) | Full-page check on staging. **`showsDrafts` is false** unless that deployment is `DRAFT_ONLY`. Do not use this as the only check for draft-only pages. |
| **siteLivePreview** | Preview redirect | `{devBaseUrl}/preview?id={entryId}` — **`showsDrafts: true`**. Use this for draft-only pages. |
| **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).
   - **siteLivePreview** (`/preview?id=`) — **draft-only pages**.
   - **Preview (staging site)** — full-screen check when `showsDrafts` is acceptable (published or `DRAFT_ONLY` host).
   - If Live Preview is unavailable, say so briefly using `unavailableReason`; do not treat 404 as a failed job.

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`