task-publish-handoff

# Capability: Publish

## Intent phrases

- publish changes
- unpublish
- archive
- revalidate this page
- go live

## Requires capabilities

The signed-in Contentful user must have the matching role permission. AI Editor cannot publish.

## What cms-edit does

`save` creates drafts. Publishing is a separate command.

1. `publish plan` (or `unpublish plan`, `archive plan`, `revalidate plan`) is read-only. It returns a plan id.
2. If someone else also changed an entry in that plan, stop and ask: publish **all** of those entries, or **mine** only. One entry cannot be split by field. Record the answer with `publish choose --plan <id> --scope all|mine`.
3. Apply only after the user says yes: `publish apply --plan <id>`. Do not apply on your own. The same yes is required for unpublish, archive, and revalidate.

## What gets published

- A page publishes its draft and changed assets and components first, then the page. That page publish is what refreshes the live site.
- The walk does not enter another page, article, or person, and it does not enter a shared template.
- `schema`, `template`, `navigation`, and the other webhook types can be the target (`--content-type schema`, `--id`, or `--from-session`). Publishing them refreshes caches through their own webhook. Do not republish every page that uses them.
- A schema linked only from an unpublished page is named in the plan. Publishing the schema does not add that link to the live page.
- A component publishes its own changes, then the pages that use it. The parent walk climbs through components and collections and stops at the first root. A template on that path is republished itself, because its webhook refreshes the pages that use it. The walk does not continue into those pages.
- `location` is a root only when the site's `project.json` lists it under `publish.extraRootContentTypes` and the editor pack has been regenerated.
- Unpublish and archive affect the named entries only, not their children. A published entry is unpublished before it is archived.
- `redirect` is refused. Redirects go live on deploy.

## Revalidate

`revalidate plan` refreshes production cache for the named pages and does not publish. The host needs `REVALIDATION_SECRET` and `PRODUCTION_SITE_URL`. If those are missing, publishing the page still refreshes the site through the Contentful webhook.

## Confirmation gates

1. Do not apply a plan unless the user has said yes for that plan id.
2. Do not claim the site is updated until apply succeeds.
3. There is no scheduled publish.