/rollout

name: rollout
description: Deploy a WHOLE redesigned site to AEM Edge Delivery Services — the full-site, bulk sibling of `deploy` (which ships one page). Use to roll out, bulk-deploy, or publish an entire migrated stardust site at once ("deploy all pages", "full site deployment", "deploy the whole/entire website to AEM"), not just a single page. Inventories the migrated tree (stardust/migrated/ + _meta.json) into a delivery ledger, dedups blocks, drives `deploy` per page, verifies, and tracks what's done and what's left. Supports archetypes-only mode — when only the template archetype pages are migrated, it deploys all block code immediately and registers the rest as content-pending.
license: Apache-2.0

stardust:rollout — whole site → AEM (Edge Delivery Services)

`deploy` converts **one** page to AEM. `rollout` delivers the **whole site**: it inventories the agnostic output of `migrate`, then drives `deploy` across every page, tracking delivery coverage so you always know what's done and what's left.

`rollout` is **delivery-only** — it does not redesign. The page-by-page redesign (`extract → direct → prototype → migrate`) and `deploy` itself are **unchanged**; `rollout` is the across-pages layer on top. Design rationale, coverage model, and phasing are in [`notes/rollout/PLAN.md`](../../notes/rollout/PLAN.md). The flow runs **A→I** below.

When to use

**Full mode** — the user has a fully migrated site at `stardust/migrated/` (per-page HTML + `_meta.json` from `stardust migrate`), an EDS/AEM project + DA destination (the same target `deploy` needs), and wants the **entire** site delivered, incrementally and resumably.

**Archetypes-only mode** — the user has one migrated archetype per template plus a full page inventory in `stardust/state.json` (with `type` per page), and wants to ship all block code immediately without waiting for every page to be migrated. Sibling pages register as `content-pending` and get their content later via a separate track.

If there is no `stardust/migrated/` tree at all, recommend `stardust migrate` on at least the archetype pages first. For a single page, use `stardust deploy` directly.

Setup

1. Run the master skill's setup (`skills/stardust/SKILL.md` § Setup). 2. Verify `stardust/migrated/` exists with at least one `*.html` page (full mode: all pages; archetypes-only: the archetypes + a `state.json` with `type` populated). If not, recommend `stardust migrate` on the archetypes and stop. 3. Verify the EDS/AEM target is ready exactly as `deploy` requires (project scaffolding, `DA_TOKEN`, code branch pushable). `rollout` adds no new transport. 4. If `state.json.handsOff` is true (`skills/stardust/SKILL.md` § Hands-off mode), run full-auto: no per-phase pauses. Every gate and verify step below runs unchanged — hands-off removes waiting, not validation.

Procedure

Phase A — Inventory (build the coverage)

node skills/rollout/scripts/inventory.mjs --site-url <source-url>
# defaults: --migrated stardust/migrated  --out stardust/rollout
# archetypes-only mode: add the full page roster from state.json
node skills/rollout/scripts/inventory.mjs --site-url <source-url> --state stardust/state.json

Writes `coverage/pages.json` (one row per page: slug, delivered `path`, `templateId`, `blocks`, `sourceHash`, `delivery` status), `coverage/templates.json` (pages grouped by template), and `rollout.json` (target + DA config + `lastRun`).

**Archetypes-only mode** (`--state`): pages with a `_meta.json` are seeded as in full mode; pages present only in `state.json` are seeded with `templateId` from `type`, `blocks` from the archetype sidecar, and `delivery.status: content-pending`.

Inventory is **idempotent and incremental**: delivery status is preserved; a page whose migrated HTML changed after delivery is re-flagged `stale`. Fill in the DA coordinates in `rollout.json` (`site.da.org`, `site.site`, `site.da.ref`, `site.liveHost`) if not inferred.

Phase B — Block dedup plan (FIRST-CLASS, before any conversion)

node skills/rollout/scripts/blocks.mjs   # → coverage/blocks.json (the dedup unit)
node skills/rollout/scripts/plan.mjs     # → plan.json + a readable conversion plan

• `blocks.mjs` collapses every block instance (per-page `modules` + chrome) into

the **distinct** set, assigns each a canonical `edsBlockName` (kebab, reserved-class-guarded per deploy #15), and records `usedByPages` / `instanceCount`. Chrome (`header`/`nav`/`footer`) is `kind: chrome` → site-wide authored documents (`/nav`, `/footer`) fed to the header/footer blocks. In archetypes-only mode the archetype sidecars fully determine the block set; `content-pending` pages add none.

• `plan.mjs` orders pages **representative-first per template** and gives each

distinct block a **single conversion point**: the first page that uses it CONVERTS it, every later page REUSES it by name. The per-page `convert`/`reuse` lists are exactly `deploy`'s Step-7 brief input, so each block converts once **without changing deploy**. `content-pending` pages are always `convert: []`.

> Extending an already-delivered site? A "new template" is almost always a new > COMPOSITION of the existing block library, not new block code — audit `blocks/` > first. See `reference/operational-learnings.md`.

Phase B2 — Metadata contract for dynamic listings (PRE-IMPORT GATE)

**Do this before Phase C — the import is blocked on it.** What a dynamic listing block can show is bounded by what each page emits, and retrofitting metadata across thousands of already-published pages is a second migration. Before importing, produce `dynamic-blocks-map.md` (which blocks are dynamic vs static, the index each reads, the fields its cards need) and a **metadata contract** (the `<meta name="…">` each content TYPE must carry). Then have Phase C's `deploy` brief emit the contract per page, and author `helix-query.yaml` from the same contract. When `stardust:prepare-m