stardust:migrate
Apply the target spec authored by direct, the visual canon
written by prototype --prep, and the brand-module catalog
extracted during prepare-migration to every page in the
inventory. Produces a self-contained, deployable static HTML site
under stardust/migrated/. Per-page, incremental, idempotent.
migrate is the final stardust phase. Output is platform-
agnostic HTML — downstream conversion (AEM EDS, a CMS, a
framework) is the job of a separate plugin that consumes
migrated/ plus DESIGN.json plus the per-page _meta.json
sidecars.
Inputs
<slug> — optional positional. Migrate just this page. Without
it, migrate every page whose status is directed,
prototyped, or approved (and not stale).
--all — migrate every page including stale ones.
--force — re-migrate every page even when the idempotent
skip would skip them.
--require-approved — refuse to migrate any non-approved
page. Default behaviour migrates directed pages too (using
Path A′ or Path B per
reference/template-and-module-rendering.md); this flag flips
approval-gating on.
--strict-canon — refuse approvals that conflict with canon.
Default logs the deviation and continues. Useful for projects
where canon discipline matters more than per-template
flexibility.
--clean — delete assets previously bundled but no longer
referenced from stardust/migrated/assets/. Off by default
(migrate is additive). Implies --force: every page is
re-rendered so the run's bundledAssets Set is the complete
union of currently-referenced assets — otherwise --clean
would risk deleting assets still referenced by
idempotent-skipped pages. See
reference/asset-bundling.md § Stale asset cleanup.
--pin-timestamp <ISO8601> — pin the migrate-provenance
timestamp so re-runs without source changes produce byte-
identical HTML. Default re-uses the current wall clock, which
is fine for normal use; CI deployment fingerprinting may want
the pin.
The mobile-adapt audit, content-sourcing scan, and placeholder
refusal are all mandatory gates — there is no --skip-* or
--allow-* flag to bypass them. If a gate refuses a page, the
remediation is to fix the proposed file (re-prototype, edit
inline, or run an impeccable command) and re-invoke migrate.
Setup
Playwright re-probe (mandatory first step). --no-save playwright
installs from earlier phases are pruned by any later real npm i
(extract SKILL.md § Setup → --no-save installs are ephemeral). Before
any rendering step, probe
node -e "import('playwright').then(()=>process.exit(0))" from the
project root and re-install (npm i -D playwright --no-save --legacy-peer-deps) on failure.
Run the master skill's setup
(skills/stardust/SKILL.md § Setup).
Verify stardust/state.json exists with at least one
directed page.
Verify project-root DESIGN.md and DESIGN.json exist with
DESIGN.json.extensions.canon populated.
Verify stardust/canon/ exists with at least
header.html, footer.html, canon.css.
Canon auto-bootstrap (when steps 3–4 find no canon). The
documented prototype → migrate → deploy happy path does not
run prepare-migration, so a first migrate legitimately arrives
with no canon (observed on 4 of 6 e2e sites, where every run had
to derive canon by hand to proceed — this is the fix). When
canon is absent and at least one approved prototype exists,
do not stop: run the canon write-back inline from the first
approved prototype (the canon-author, default home) per
../prototype/reference/canon-extraction.md § Five-step
procedure — extract header.html / footer.html / canon.css
to stardust/canon/, pin tokens + compositional moves to
DESIGN.json.extensions.canon, and record
canon.source: "auto-bootstrap: <slug>". This is exactly what
prototype --prep does on first approval; migrate performs it
on demand so the core pipeline never dead-ends. Only stop and
recommend $stardust prepare-migration when canon is absent
and no approved prototype exists (there is nothing to derive
canon from). Under state.json.handsOff the bootstrap is
automatic and logged; interactively, surface it as a one-line
notice before proceeding.
Verify stardust/direction.md has an active (not pending)
direction.
Read state.json.pages[] and partition into:
- inScope: status
directed, prototyped, or
approved, stale: false (or --all / explicit
<slug>).
- skipped: everything else, with reason captured.
Validate provenance on every in-scope page. Call
validateProvenance(page) per
skills/stardust/reference/state-machine.md § Provenance
validation for every page in inScope. Abort with the
helper's error when any page lacks live-render evidence —
migrating a synthesized page record produces deployable HTML
that misrepresents the source site, the exact failure mode
that motivated the validator. Surface Provenance OK on N pages in the migrate-plan output before Phase 1.
Mobile-adapt audit on every Path A / Path A′ source. For
every page whose render branch consumes a proposed or
archetype HTML file (Path A, Path A′ per
reference/template-and-module-rendering.md § Render path
selection), run the audit per skills/prototype/SKILL.md
§ Mobile-adapt audit:
<meta name="viewport" content="width=device-width, ...">
present, width not pinned to a fixed pixel value.
- At least one
@media (max-width: ...) rule.
- At least one mobile-targeted breakpoint at ≤ 640px.
Refuse pages that fail — the audit is mandatory; there is no
skip flag. The user fixes the proposed file (re-prototype or
chat-driven impeccable command) and re-invokes migrate.
Record the audit result per page in the migrate report and
in the post-render _meta.json#audit.adapt sidecar. Path B
(unique-renders) skips the audit because adapt hasn't run
on those pages — a Path B page that needs mobile coverage
gets it via $impeccable adapt invoked separately by the
user. Surface this distinction in the report so it's not
read as a silent skip.
Procedure
Phase 1 — Plan
Print the plan and wait for confirmation when the scope is large:
migrate plan
============
In scope: 127 pages
Path A (approved) 6 pages: home, news/post-housing-summit, news, ...
Path A' (template-applied) 118 pages: 84 article, 5 listing, 11 program, 2 form, 16 static
Path B (unique) 3 pages: 404, search, faq
Skipped: 0 stale, 0 unscoped
DESIGN.md sha: 1a2b3c4
DESIGN.json sha: 5d6e7f8
Canon shas: header:7g8h9i footer:9i0j1k css:1k2l3m
Output: stardust/migrated/ + per-page _meta.json sidecars
Idempotent skip: enabled (run with --force to override)
Reply "go" to proceed.
For 1-3 pages or <slug> invocation, skip the confirmation.
Phase 2 — Per-page render
For each page in scope, follow
reference/migration-procedure.md and
reference/template-and-module-rendering.md:
- Idempotent skip check first (sha-compare across
designMd, designJson, sourceCurrent, sourceProposed,
canonShas, archetypeSource).
- Placeholder gate (Path A and Path A′ only — pages with a
proposed file or archetype). Refuse when
[data-placeholder]
elements or non-empty _provenance.unsourcedContent[] are
present — the user fills the missing content in the proposed
file before re-invoking migrate. No bypass flag.
- Render branch selection (LLM judgment per T&M §
Render path selection): A / A′ / B. Declare the page's
fidelityTier from the branch — A → archetype (craft-gated),
A′ → sibling (canon-fork, the cheap default for breadth),
B/bodyless → thin — per reference/fidelity-tiers.md. Record
fidelityTier, archetypeSource, and gatesPassed[] in
_meta.json so coverage shows what was craft-gated vs cloned.
- Render per the chosen branch's procedure in T&M.
- Canon application — chrome injection, canon.css
injection, deviation logging.
- Module rendering — render module instances via
stardust/canon/modules/<id>.html; bespoke slots logged
with data-bespoke.
- Apply content-preservation rules per
reference/content-preservation.md. Internal-link rewriting
always emits migrated-tree paths; missing slugs flagged
broken.
- Compose
<head> metadata per
reference/metadata-and-jsonld.md (five categories;
page-type-driven JSON-LD).
- Validate per T&M § Validation contracts. Strict contracts
refuse the page; soft contracts log and continue.
- Compute output path per migration-procedure.md
§ Output path mapping.
- Asset bundling. Scan the final HTML for asset references
(six detection shapes per
reference/asset-bundling.md § Detection), copy each unique
referenced subpath from stardust/current/assets/<subpath> to
stardust/migrated/assets/<subpath> (preserving subdir
structure), then rewrite every reference to the root-relative
form /assets/<subpath>. Cross-page dedup uses a
module-level Set seeded from
state.json.migrate.bundledAssets[]. Missing source assets
warn-and-skip per § Edge cases; the bundle stays internally
consistent.
- Media reconciliation. For every image not bundled to
same-origin (reused source-CDN URLs under Mode A image-reuse),
decide optimize/keep/rewrite/omit per
reference/media-reconciliation.md. Cross-origin <img> kept
as source URLs must skip createOptimizedPicture (it drops
the ?v= key and corrupts the rendition); broken URLs are
repaired (missing ?-delimiter, wrong host) or omitted, never
shipped as about:error. rollout re-runs the authoritative
network resolve at delivery (media-reconcile.mjs).
- Cinematic sibling (when
<slug>-cinematic.html exists).
Migrate consumes the STATIC prototype only — the cinematic layer
is never merged. Copy the motion assets (lenis.min.js,
lenis.min.css) from stardust/prototypes/ to
stardust/migrated/assets/motion/ (idempotent) for downstream
consumers (deploy/rollout decide whether to wire them), and
record cinematic-variant-not-consumed in the page's
_meta.json#migrationDecisions[].
- Write the migrated
index.html and the _meta.json
sidecar in the same directory. Provenance block as first
child of <head>. Record assetsBundled (count of unique
asset refs on this page) in _meta.json.
Phase 3 — Sitewide assets and bundle finalisation
Per-page asset bundling already happened in Phase 2 (every
referenced media subpath is on disk under
stardust/migrated/assets/). Phase 3 fills in the sitewide
assets that no individual page references explicitly:
Copy stardust/current/assets/logo.<ext> to
stardust/migrated/assets/logo.<ext> (only if missing or
stale). Record under state.json.migrate.bundledAssets[].
Verify favicon variants and font files were generated by
prepare-migration Phase 4. If absent, log a warning and
continue (the migrated site renders without them, just
missing some platform-specific affordances).
Add stardust/migrated/robots.txt and sitemap.xml
derived from the migrated page inventory per
reference/metadata-and-jsonld.md § Sitemap entry.
If --clean was passed, compute
stale = priorBundle.filter(p => !bundledAssets.has(p))
from state.json.migrate.bundledAssets[] and remove each
stale subpath from stardust/migrated/assets/. Record the
deletions under state.json.migrate.cleanedAssets[]. Per
reference/asset-bundling.md § Stale asset cleanup.
Verify portability. The bundle must work via file://,
at a webserver root, and at any subpath — "one shape, works
everywhere". Run every audit; any non-empty grep output or
non-zero fixture exit fails the run with the cited error
message:
# No source-tree escapes
find stardust/migrated/ -type f -name '*.html' -exec grep -l '\.\./current/' {} +
# Error: "asset still points outside the migrated tree; rewrite via the
# asset-bundling pass per reference/asset-bundling.md § Detection"
# No absolute internal references in attribute values (404 on file:// and subpath)
grep -rE '(href|src)="/[^/]' stardust/migrated/ --include='*.html'
# Error: "absolute href `/beers/` will 404 on file:// and on subpath hosts;
# rewrite via the page map per migration-procedure.md § Reference shape"
# No absolute internal references in url() (inline style, <style> blocks, CSS)
grep -rE 'url\(\s*["''']?\s*/[^/]' stardust/migrated/ --include='*.html' --include='*.css'
# Error: "absolute url(/...) reference will 404 on file:// and on subpath hosts;
# rewrite via the asset-bundling pass per asset-bundling.md § Rewrite"
# No directory-only nav (doesn't resolve on file://). Pattern accepts
# only relative or root-absolute hrefs (./, ../, /, or bare segment)
# so external URLs like https://google.com/ aren't false-flagged.
grep -rE 'href="(\.{0,2}/|[a-zA-Z0-9_-])[^:"#?]*/"' stardust/migrated/ --include='*.html'
# Error: "directory-only href `./beers/` won't resolve on file://;
# append the explicit index.html (or the source URL's .html leaf)
# per § Reference shape"
# pageMap consistency — every internal href appears as an outputPath
node skills/migrate/fixtures/pagemap-audit.mjs stardust/migrated/ stardust/state.json
# Error: "internal href has no pageMap entry; link rewriting bypassed the
# page map per § Page map (build once, use everywhere)"
# Headless file:// round-trip — the test that proves zip-and-deploy works
node skills/migrate/fixtures/file-protocol-audit.mjs stardust/migrated/
# Error: "<offending file> linked <ref> that 404s under file://; see the
# Playwright network log printed above"
The audits are mandatory — there is no skip flag. The contract
is "self-contained, zip-and-deploy" and these audits are the
verifiers that back the claim.
Asset migration is idempotent — files are content-hashed and
copied only when missing; per-page bundling deduplicates across
the run.
Phase 4 — State and report
Update state.json:
- For each successfully migrated page:
status advances to
migrated, append a history entry, clear any stale flag,
set migratedPath.
- For pages skipped via idempotent skip: leave state
unchanged.
- For pages that failed validation: leave state unchanged, log
the failure in
state.json.lastRun.failures[].
- Write the top-level
migrate block per
skills/stardust/reference/migrate-output-format.md
§ State.json contract: selfContained: true, outputDir,
totalAssetsBundled, bundledAssets[], per-page
assetsBundled counts, missingAssets[], cleanedAssets[].
This is the forward-compat signal downstream consumers test
for.
Print the run summary:
migrate complete
================
122 migrated home, about, news/post-housing-summit, ...
3 unchanged about, programs/shelter, news/post-old (idempotent skip)
2 failed contact (validation: required slot missing),
legal/privacy (validation: color-reservation violated)
0 stale skipped
Render branches:
Path A 6 approved-from-prototype
Path A' 116 template-applied (84 article, 5 listing, 11 program, 2 form, 14 static)
Path B 3 unique-render (404, search, faq)
Pages with non-trivial decisions: 12
about canon-deviation: footer carries financials disclaimer
donate template-adapted: amount-pills slot moved above headline
...
Broken internal links: 5
/events referenced by 2 pages; not in inventory
/press referenced by 1 page; not in inventory
...
Bespoke slots crossing promotion threshold: 1
hotline-211: "state" (3 instances) — consider `$stardust prepare-migration --refine-module`
Missing assets: 2
generated/orphan-1.jpg referenced by 1 page (home)
generated/orphan-2.jpg referenced by 2 pages (about, contact)
(Re-extract or accept the gap — bundle is deployable; refs 404 at view time.)
Output: stardust/migrated/ (122 pages, 47 bundled assets, 4.2 MB) — self-contained, zip-and-deploy
Next:
- Review: open stardust/migrated/index.html in a browser
- Audit: $impeccable critique stardust/migrated/
- Deploy: cd stardust/migrated && zip -r ../site.zip .
upload the zip to any static host that serves at the host root
- Refine: edit DESIGN.md or canon files, then re-run $stardust migrate
Outputs
| Path |
Purpose |
stardust/migrated/<source-url-path> |
Migrated page. Output path mirrors the source URL literally (see reference/migration-procedure.md § Output path mapping). The bundle is zip-and-deploy: drop on any static host at any path, or open index.html directly via file://. Every internal reference is relative to the page that emits it; nav targets carry an explicit index.html (or the source URL's literal filename) so file:// resolves without a server. |
| _meta.json sidecar |
Lives next to each migrated page. For <dir>/index.html the sidecar is <dir>/_meta.json; for <dir>/<name>.html the sidecar is <dir>/<name>._meta.json so multiple .html siblings don't collide. Per reference/migration-procedure.md § _meta.json sidecar. |
stardust/migrated/index.html |
The home page (special case). |
stardust/migrated/_meta.json |
Home sidecar. |
stardust/migrated/assets/logo.<ext> |
Brand logo (sitewide). |
stardust/migrated/assets/<subpath> |
Every asset referenced by any migrated page, bundled. Source subdir structure preserved verbatim. |
stardust/migrated/assets/favicon.<ext> + variants |
Favicon and apple-touch-icon, manifest icons. |
stardust/migrated/assets/fonts/... |
Downloaded font files (from canon @font-face URLs). |
stardust/migrated/robots.txt |
Minimal robots.txt. |
stardust/migrated/sitemap.xml |
Sitemap derived from migrated inventory + page types. |
stardust/state.json |
Updated with migrated status, history, and the migrate block (selfContained: true, asset counts). |
Idempotent and incremental
The whole pipeline is built around two properties:
- Idempotent. Re-running
$stardust migrate with no
changes produces zero file writes. Every page is sha-compared
across designMd, designJson, sourceCurrent, sourceProposed
(Path A), canonShas, archetypeSource (Path A′) — and skipped
if all match.
- Incremental. Migrate 5 pages today, 20 pages tomorrow,
fix one page's content next week — the migrated tree is
always the union of every successful migration to date.
These properties hold even when DESIGN.md, canon, or modules are
edited mid-run: the edit changes the relevant sha, so the next
migrate run re-renders every affected page (canon and DESIGN.md
edits typically affect every page).
Stale handling
When direction.md, canon, or the module catalog changes after
some pages have been migrated:
- Affected pages are flagged
stale: true per
skills/stardust/reference/state-machine.md § Stale flagging.
Stale-flagging is content-aware in all three trigger cases.
$stardust migrate (no flags) skips stale pages and reports
the count.
$stardust migrate --all re-migrates each stale page,
clearing the flag on success.
$stardust migrate <slug> always operates on the named page,
stale or not.
The user decides whether stale pages should be refreshed —
direction/canon/module changes don't invalidate prior migrated
work, they just mark it as out-of-step.
Failure modes
- No directed pages. Recommend
$stardust direct (or
$stardust extract if no extracted state).
- No DESIGN.md or DESIGN.json. Recommend
$stardust direct.
- No canon, but an approved prototype exists. Do NOT stop —
auto-bootstrap canon from the canon-author inline (Setup step 4).
- No canon and no approved prototype. Recommend
$stardust prepare-migration (or approve a prototype first).
- Pending direction. Refuse; user must resolve direction
first.
- Validation failure on a single page. Skip that page,
continue, log the failure under
state.json.lastRun.failures[]. Do not abort the whole run.
- Asset copy failure. Continue the run; record the missing
asset in the page's
migrationDecisions[] with
kind: "asset-missing". The migrated <img src> keeps the
original absolute URL as a fallback.
- Output path collision. Two slugs mapping to the same
output path. Refuse to write the second one and surface to
the user — manual slug rename needed.
- Placeholder content in proposed/archetype file. Refuse
to ship a page whose source contains
[data-placeholder]
elements. Surface the unsourced list and recommend sourcing
real content (re-prototype, or edit the proposed file
directly). There is no bypass flag — shipping placeholders to
a public site is the failure mode this gate exists to prevent.
- Color reservation violated. Refuse the page; surface to
user with the offending color and the reserved-for context.
- Brand-faithful inversion conflict. A hard rule declared
inverted in
extensions.divergence.brand_faithful_inversions[] is lifted
from validation per T&M § Brand-faithful inversion handling.
Emit a one-line note in the run summary acknowledging the
lift.
What migrate does NOT do
- Critique or audit the migrated output. Run
$impeccable critique stardust/migrated/ after migration if
you want a quality assessment.
- Deploy. Stardust does not push, upload, or modify origin.
- Generate AEM EDS, a CMS payload, or framework components. The
output is platform-agnostic static HTML; downstream conversion
is a separate plugin's job.
- Re-fetch the live site. Offline after extract Phase 1.
- Run any iteration loop. Iteration belongs to
prototype;
migrate consumes the result.
References
reference/migration-procedure.md — per-page render procedure,
output path mapping, validation, provenance shape, idempotent
skip, sidecar schema.
reference/template-and-module-rendering.md — three render
branches in detail, slot injection, deviation policy,
validation contracts.
reference/metadata-and-jsonld.md — head composition, JSON-LD
per page-type, canonical strategy.
reference/content-preservation.md — what's kept,
transformed, dropped; internal-link rewriting; asset path
rewriting; form handling.
reference/asset-bundling.md — detection / copy / rewrite
contract for the per-page asset-bundling phase.
skills/stardust/reference/migrate-output-format.md — the
self-contained-bundle contract downstream consumers can rely
on (asset reference shape, directory layout,
state.json.migrate block).
skills/stardust/reference/token-contract.md — :root block
refreshed from DESIGN.md on every render.
skills/stardust/reference/data-attributes.md — structural
attributes including data-template, data-module,
data-slot, data-canon, data-deviation, data-bespoke,
data-broken-link.
skills/stardust/reference/state-machine.md — page lifecycle,
page typing, stale-flagging cascade.
skills/stardust/reference/artifact-map.md — provenance shape
for migrated artifacts; canon files; sidecar shape.
skills/prototype/reference/canon-extraction.md — how canon
is built (input to migrate).
skills/prepare-migration/SKILL.md — the cascade that
produces every input migrate consumes.
1---2name: migrate3description: Apply DESIGN, canon, and modules to every page in the inventory, producing a deployable static HTML site. Use to migrate or render the whole captured site into the redesigned static tree ("migrate the pages", "render the migrated site", "apply the design to all pages", "build the deployable site", "convert the approved prototype into the full site") — the page-rendering step between prototype and deploy/rollout. Three render branches (approved page, template-applied sibling, unique render), with a declared fidelity tier per page. Per-page, incremental, idempotent, content-preserving by default.4license: Apache-2.05metadata:6 source: https://skillmd.com/skills/adobe/migrate7---89# stardust:migrate1011Apply the target spec authored by `direct`, the visual canon12written by `prototype --prep`, and the brand-module catalog13extracted during `prepare-migration` to every page in the14inventory. Produces a self-contained, deployable static HTML site15under `stardust/migrated/`. Per-page, incremental, idempotent.1617`migrate` is the final stardust phase. Output is platform-18agnostic HTML — downstream conversion (AEM EDS, a CMS, a19framework) is the job of a separate plugin that consumes20`migrated/` plus `DESIGN.json` plus the per-page `_meta.json`21sidecars.2223## Inputs2425- `<slug>` — optional positional. Migrate just this page. Without26 it, migrate every page whose status is `directed`,27 `prototyped`, or `approved` (and not `stale`).28- `--all` — migrate every page including stale ones.29- `--force` — re-migrate every page even when the idempotent30 skip would skip them.31- `--require-approved` — refuse to migrate any non-`approved`32 page. Default behaviour migrates `directed` pages too (using33 Path A′ or Path B per34 `reference/template-and-module-rendering.md`); this flag flips35 approval-gating on.36- `--strict-canon` — refuse approvals that conflict with canon.37 Default logs the deviation and continues. Useful for projects38 where canon discipline matters more than per-template39 flexibility.40- `--clean` — delete assets previously bundled but no longer41 referenced from `stardust/migrated/assets/`. Off by default42 (migrate is additive). **Implies `--force`**: every page is43 re-rendered so the run's `bundledAssets` Set is the complete44 union of currently-referenced assets — otherwise `--clean`45 would risk deleting assets still referenced by46 idempotent-skipped pages. See47 `reference/asset-bundling.md` § Stale asset cleanup.48- `--pin-timestamp <ISO8601>` — pin the migrate-provenance49 timestamp so re-runs without source changes produce byte-50 identical HTML. Default re-uses the current wall clock, which51 is fine for normal use; CI deployment fingerprinting may want52 the pin.5354The mobile-adapt audit, content-sourcing scan, and placeholder55refusal are all mandatory gates — there is no `--skip-*` or56`--allow-*` flag to bypass them. If a gate refuses a page, the57remediation is to fix the proposed file (re-prototype, edit58inline, or run an impeccable command) and re-invoke migrate.5960## Setup61620. **Playwright re-probe (mandatory first step).** `--no-save` playwright63 installs from earlier phases are pruned by any later real `npm i`64 (extract SKILL.md § Setup → `--no-save` installs are ephemeral). Before65 any rendering step, probe66 `node -e "import('playwright').then(()=>process.exit(0))"` from the67 project root and re-install (`npm i -D playwright --no-save68 --legacy-peer-deps`) on failure.691. Run the master skill's setup70 (`skills/stardust/SKILL.md` § Setup).712. Verify `stardust/state.json` exists with at least one72 `directed` page.733. Verify project-root `DESIGN.md` and `DESIGN.json` exist with74 `DESIGN.json.extensions.canon` populated.754. Verify `stardust/canon/` exists with at least76 `header.html`, `footer.html`, `canon.css`.7778 **Canon auto-bootstrap (when steps 3–4 find no canon).** The79 documented `prototype → migrate → deploy` happy path does not80 run `prepare-migration`, so a first migrate legitimately arrives81 with no canon (observed on 4 of 6 e2e sites, where every run had82 to derive canon by hand to proceed — this is the fix). When83 canon is absent **and** at least one `approved` prototype exists,84 do not stop: run the canon write-back inline from the first85 approved prototype (the canon-author, default `home`) per86 `../prototype/reference/canon-extraction.md` § Five-step87 procedure — extract `header.html` / `footer.html` / `canon.css`88 to `stardust/canon/`, pin tokens + compositional moves to89 `DESIGN.json.extensions.canon`, and record90 `canon.source: "auto-bootstrap: <slug>"`. This is exactly what91 `prototype --prep` does on first approval; migrate performs it92 on demand so the core pipeline never dead-ends. Only stop and93 recommend `$stardust prepare-migration` when canon is absent94 **and** no approved prototype exists (there is nothing to derive95 canon from). Under `state.json.handsOff` the bootstrap is96 automatic and logged; interactively, surface it as a one-line97 notice before proceeding.985. Verify `stardust/direction.md` has an active (not pending)99 direction.1006. Read `state.json.pages[]` and partition into:101 - **inScope**: status `directed`, `prototyped`, or102 `approved`, `stale: false` (or `--all` / explicit103 `<slug>`).104 - **skipped**: everything else, with reason captured.1057. **Validate provenance on every in-scope page.** Call106 `validateProvenance(page)` per107 `skills/stardust/reference/state-machine.md` § Provenance108 validation for every page in `inScope`. Abort with the109 helper's error when any page lacks live-render evidence —110 migrating a synthesized page record produces deployable HTML111 that misrepresents the source site, the exact failure mode112 that motivated the validator. Surface `Provenance OK on N113 pages` in the migrate-plan output before Phase 1.1148. **Mobile-adapt audit on every Path A / Path A′ source.** For115 every page whose render branch consumes a proposed or116 archetype HTML file (Path A, Path A′ per117 `reference/template-and-module-rendering.md` § Render path118 selection), run the audit per `skills/prototype/SKILL.md`119 § Mobile-adapt audit:120121 - `<meta name="viewport" content="width=device-width, ...">`122 present, width not pinned to a fixed pixel value.123 - At least one `@media (max-width: ...)` rule.124 - At least one mobile-targeted breakpoint at ≤ 640px.125126 Refuse pages that fail — the audit is mandatory; there is no127 skip flag. The user fixes the proposed file (re-prototype or128 chat-driven impeccable command) and re-invokes migrate.129 Record the audit result per page in the migrate report and130 in the post-render `_meta.json#audit.adapt` sidecar. Path B131 (unique-renders) skips the audit because adapt hasn't run132 on those pages — a Path B page that needs mobile coverage133 gets it via `$impeccable adapt` invoked separately by the134 user. Surface this distinction in the report so it's not135 read as a silent skip.136137## Procedure138139### Phase 1 — Plan140141Print the plan and wait for confirmation when the scope is large:142143```144migrate plan145============146147In scope: 127 pages148 Path A (approved) 6 pages: home, news/post-housing-summit, news, ...149 Path A' (template-applied) 118 pages: 84 article, 5 listing, 11 program, 2 form, 16 static150 Path B (unique) 3 pages: 404, search, faq151152Skipped: 0 stale, 0 unscoped153154DESIGN.md sha: 1a2b3c4155DESIGN.json sha: 5d6e7f8156Canon shas: header:7g8h9i footer:9i0j1k css:1k2l3m157158Output: stardust/migrated/ + per-page _meta.json sidecars159Idempotent skip: enabled (run with --force to override)160161Reply "go" to proceed.162```163164For 1-3 pages or `<slug>` invocation, skip the confirmation.165166### Phase 2 — Per-page render167168For each page in scope, follow169`reference/migration-procedure.md` and170`reference/template-and-module-rendering.md`:171172- **Idempotent skip check** first (sha-compare across173 `designMd`, `designJson`, `sourceCurrent`, `sourceProposed`,174 `canonShas`, `archetypeSource`).175- **Placeholder gate** (Path A and Path A′ only — pages with a176 proposed file or archetype). Refuse when `[data-placeholder]`177 elements or non-empty `_provenance.unsourcedContent[]` are178 present — the user fills the missing content in the proposed179 file before re-invoking migrate. No bypass flag.180- **Render branch selection** (LLM judgment per T&M §181 Render path selection): A / A′ / B. **Declare the page's182 `fidelityTier`** from the branch — A → `archetype` (craft-gated),183 A′ → `sibling` (canon-fork, the cheap default for breadth),184 B/bodyless → `thin` — per `reference/fidelity-tiers.md`. Record185 `fidelityTier`, `archetypeSource`, and `gatesPassed[]` in186 `_meta.json` so coverage shows what was craft-gated vs cloned.187- **Render** per the chosen branch's procedure in T&M.188- **Canon application** — chrome injection, canon.css189 injection, deviation logging.190- **Module rendering** — render module instances via191 `stardust/canon/modules/<id>.html`; bespoke slots logged192 with `data-bespoke`.193- **Apply content-preservation rules** per194 `reference/content-preservation.md`. Internal-link rewriting195 always emits migrated-tree paths; missing slugs flagged196 broken.197- **Compose `<head>` metadata** per198 `reference/metadata-and-jsonld.md` (five categories;199 page-type-driven JSON-LD).200- **Validate** per T&M § Validation contracts. Strict contracts201 refuse the page; soft contracts log and continue.202- **Compute output path** per migration-procedure.md203 § Output path mapping.204- **Asset bundling.** Scan the final HTML for asset references205 (six detection shapes per206 `reference/asset-bundling.md` § Detection), copy each unique207 referenced subpath from `stardust/current/assets/<subpath>` to208 `stardust/migrated/assets/<subpath>` (preserving subdir209 structure), then rewrite every reference to the root-relative210 form `/assets/<subpath>`. Cross-page dedup uses a211 module-level Set seeded from212 `state.json.migrate.bundledAssets[]`. Missing source assets213 warn-and-skip per § Edge cases; the bundle stays internally214 consistent.215- **Media reconciliation.** For every image **not** bundled to216 same-origin (reused source-CDN URLs under Mode A image-reuse),217 decide optimize/keep/rewrite/omit per218 `reference/media-reconciliation.md`. Cross-origin `<img>` kept219 as source URLs must **skip `createOptimizedPicture`** (it drops220 the `?v=` key and corrupts the rendition); broken URLs are221 repaired (missing `?`-delimiter, wrong host) or omitted, never222 shipped as `about:error`. `rollout` re-runs the authoritative223 network resolve at delivery (`media-reconcile.mjs`).224- **Cinematic sibling (when `<slug>-cinematic.html` exists).**225 Migrate consumes the STATIC prototype only — the cinematic layer226 is never merged. Copy the motion assets (`lenis.min.js`,227 `lenis.min.css`) from `stardust/prototypes/` to228 `stardust/migrated/assets/motion/` (idempotent) for downstream229 consumers (deploy/rollout decide whether to wire them), and230 record `cinematic-variant-not-consumed` in the page's231 `_meta.json#migrationDecisions[]`.232- **Write** the migrated `index.html` and the `_meta.json`233 sidecar in the same directory. Provenance block as first234 child of `<head>`. Record `assetsBundled` (count of unique235 asset refs on this page) in `_meta.json`.236237### Phase 3 — Sitewide assets and bundle finalisation238239Per-page asset bundling already happened in Phase 2 (every240referenced media subpath is on disk under241`stardust/migrated/assets/`). Phase 3 fills in the **sitewide242assets** that no individual page references explicitly:2432441. Copy `stardust/current/assets/logo.<ext>` to245 `stardust/migrated/assets/logo.<ext>` (only if missing or246 stale). Record under `state.json.migrate.bundledAssets[]`.2472. Verify favicon variants and font files were generated by248 `prepare-migration` Phase 4. If absent, log a warning and249 continue (the migrated site renders without them, just250 missing some platform-specific affordances).2513. Add `stardust/migrated/robots.txt` and `sitemap.xml`252 derived from the migrated page inventory per253 `reference/metadata-and-jsonld.md` § Sitemap entry.2544. If `--clean` was passed, compute255 `stale = priorBundle.filter(p => !bundledAssets.has(p))`256 from `state.json.migrate.bundledAssets[]` and remove each257 stale subpath from `stardust/migrated/assets/`. Record the258 deletions under `state.json.migrate.cleanedAssets[]`. Per259 `reference/asset-bundling.md` § Stale asset cleanup.2605. Verify **portability**. The bundle must work via `file://`,261 at a webserver root, and at any subpath — "one shape, works262 everywhere". Run every audit; any non-empty grep output or263 non-zero fixture exit fails the run with the cited error264 message:265266 ```bash267 # No source-tree escapes268 find stardust/migrated/ -type f -name '*.html' -exec grep -l '\.\./current/' {} +269 # Error: "asset still points outside the migrated tree; rewrite via the270 # asset-bundling pass per reference/asset-bundling.md § Detection"271272 # No absolute internal references in attribute values (404 on file:// and subpath)273 grep -rE '(href|src)="/[^/]' stardust/migrated/ --include='*.html'274 # Error: "absolute href `/beers/` will 404 on file:// and on subpath hosts;275 # rewrite via the page map per migration-procedure.md § Reference shape"276277 # No absolute internal references in url() (inline style, <style> blocks, CSS)278 grep -rE 'url\(\s*["''']?\s*/[^/]' stardust/migrated/ --include='*.html' --include='*.css'279 # Error: "absolute url(/...) reference will 404 on file:// and on subpath hosts;280 # rewrite via the asset-bundling pass per asset-bundling.md § Rewrite"281282 # No directory-only nav (doesn't resolve on file://). Pattern accepts283 # only relative or root-absolute hrefs (./, ../, /, or bare segment)284 # so external URLs like https://google.com/ aren't false-flagged.285 grep -rE 'href="(\.{0,2}/|[a-zA-Z0-9_-])[^:"#?]*/"' stardust/migrated/ --include='*.html'286 # Error: "directory-only href `./beers/` won't resolve on file://;287 # append the explicit index.html (or the source URL's .html leaf)288 # per § Reference shape"289290 # pageMap consistency — every internal href appears as an outputPath291 node skills/migrate/fixtures/pagemap-audit.mjs stardust/migrated/ stardust/state.json292 # Error: "internal href has no pageMap entry; link rewriting bypassed the293 # page map per § Page map (build once, use everywhere)"294295 # Headless file:// round-trip — the test that proves zip-and-deploy works296 node skills/migrate/fixtures/file-protocol-audit.mjs stardust/migrated/297 # Error: "<offending file> linked <ref> that 404s under file://; see the298 # Playwright network log printed above"299 ```300301 The audits are mandatory — there is no skip flag. The contract302 is "self-contained, zip-and-deploy" and these audits are the303 verifiers that back the claim.304305Asset migration is idempotent — files are content-hashed and306copied only when missing; per-page bundling deduplicates across307the run.308309### Phase 4 — State and report310311Update `state.json`:312313- For each successfully migrated page: `status` advances to314 `migrated`, append a history entry, clear any `stale` flag,315 set `migratedPath`.316- For pages skipped via idempotent skip: leave state317 unchanged.318- For pages that failed validation: leave state unchanged, log319 the failure in `state.json.lastRun.failures[]`.320- Write the top-level `migrate` block per321 `skills/stardust/reference/migrate-output-format.md`322 § State.json contract: `selfContained: true`, `outputDir`,323 `totalAssetsBundled`, `bundledAssets[]`, per-page324 `assetsBundled` counts, `missingAssets[]`, `cleanedAssets[]`.325 This is the forward-compat signal downstream consumers test326 for.327328Print the run summary:329330```331migrate complete332================333334 122 migrated home, about, news/post-housing-summit, ...335 3 unchanged about, programs/shelter, news/post-old (idempotent skip)336 2 failed contact (validation: required slot missing),337 legal/privacy (validation: color-reservation violated)338 0 stale skipped339340Render branches:341 Path A 6 approved-from-prototype342 Path A' 116 template-applied (84 article, 5 listing, 11 program, 2 form, 14 static)343 Path B 3 unique-render (404, search, faq)344345Pages with non-trivial decisions: 12346 about canon-deviation: footer carries financials disclaimer347 donate template-adapted: amount-pills slot moved above headline348 ...349350Broken internal links: 5351 /events referenced by 2 pages; not in inventory352 /press referenced by 1 page; not in inventory353 ...354355Bespoke slots crossing promotion threshold: 1356 hotline-211: "state" (3 instances) — consider `$stardust prepare-migration --refine-module`357358Missing assets: 2359 generated/orphan-1.jpg referenced by 1 page (home)360 generated/orphan-2.jpg referenced by 2 pages (about, contact)361 (Re-extract or accept the gap — bundle is deployable; refs 404 at view time.)362363Output: stardust/migrated/ (122 pages, 47 bundled assets, 4.2 MB) — self-contained, zip-and-deploy364365Next:366 - Review: open stardust/migrated/index.html in a browser367 - Audit: $impeccable critique stardust/migrated/368 - Deploy: cd stardust/migrated && zip -r ../site.zip .369 upload the zip to any static host that serves at the host root370 - Refine: edit DESIGN.md or canon files, then re-run $stardust migrate371```372373## Outputs374375| Path | Purpose |376|---------------------------------------------------|--------------------------------------------------------|377| `stardust/migrated/<source-url-path>` | Migrated page. Output path mirrors the source URL literally (see `reference/migration-procedure.md` § Output path mapping). The bundle is **zip-and-deploy**: drop on any static host at any path, or open `index.html` directly via `file://`. Every internal reference is relative to the page that emits it; nav targets carry an explicit `index.html` (or the source URL's literal filename) so file:// resolves without a server. |378| _meta.json sidecar | Lives next to each migrated page. For `<dir>/index.html` the sidecar is `<dir>/_meta.json`; for `<dir>/<name>.html` the sidecar is `<dir>/<name>._meta.json` so multiple `.html` siblings don't collide. Per `reference/migration-procedure.md` § `_meta.json` sidecar. |379| `stardust/migrated/index.html` | The home page (special case). |380| `stardust/migrated/_meta.json` | Home sidecar. |381| `stardust/migrated/assets/logo.<ext>` | Brand logo (sitewide). |382| `stardust/migrated/assets/<subpath>` | Every asset referenced by any migrated page, bundled. Source subdir structure preserved verbatim. |383| `stardust/migrated/assets/favicon.<ext>` + variants| Favicon and apple-touch-icon, manifest icons. |384| `stardust/migrated/assets/fonts/...` | Downloaded font files (from canon @font-face URLs). |385| `stardust/migrated/robots.txt` | Minimal robots.txt. |386| `stardust/migrated/sitemap.xml` | Sitemap derived from migrated inventory + page types. |387| `stardust/state.json` | Updated with `migrated` status, history, and the `migrate` block (`selfContained: true`, asset counts). |388389## Idempotent and incremental390391The whole pipeline is built around two properties:392393- **Idempotent.** Re-running `$stardust migrate` with no394 changes produces zero file writes. Every page is sha-compared395 across designMd, designJson, sourceCurrent, sourceProposed396 (Path A), canonShas, archetypeSource (Path A′) — and skipped397 if all match.398- **Incremental.** Migrate 5 pages today, 20 pages tomorrow,399 fix one page's content next week — the migrated tree is400 always the union of every successful migration to date.401402These properties hold even when DESIGN.md, canon, or modules are403edited mid-run: the edit changes the relevant sha, so the next404migrate run re-renders every affected page (canon and DESIGN.md405edits typically affect every page).406407## Stale handling408409When `direction.md`, canon, or the module catalog changes after410some pages have been migrated:411412- Affected pages are flagged `stale: true` per413 `skills/stardust/reference/state-machine.md` § Stale flagging.414 Stale-flagging is content-aware in all three trigger cases.415- `$stardust migrate` (no flags) skips stale pages and reports416 the count.417- `$stardust migrate --all` re-migrates each stale page,418 clearing the flag on success.419- `$stardust migrate <slug>` always operates on the named page,420 stale or not.421422The user decides whether stale pages should be refreshed —423direction/canon/module changes don't invalidate prior migrated424work, they just mark it as out-of-step.425426## Failure modes427428- **No directed pages.** Recommend `$stardust direct` (or429 `$stardust extract` if no extracted state).430- **No DESIGN.md or DESIGN.json.** Recommend `$stardust direct`.431- **No canon, but an approved prototype exists.** Do NOT stop —432 auto-bootstrap canon from the canon-author inline (Setup step 4).433- **No canon and no approved prototype.** Recommend434 `$stardust prepare-migration` (or approve a prototype first).435- **Pending direction.** Refuse; user must resolve direction436 first.437- **Validation failure on a single page.** Skip that page,438 continue, log the failure under439 `state.json.lastRun.failures[]`. Do not abort the whole run.440- **Asset copy failure.** Continue the run; record the missing441 asset in the page's `migrationDecisions[]` with442 `kind: "asset-missing"`. The migrated `<img src>` keeps the443 original absolute URL as a fallback.444- **Output path collision.** Two slugs mapping to the same445 output path. Refuse to write the second one and surface to446 the user — manual slug rename needed.447- **Placeholder content in proposed/archetype file.** Refuse448 to ship a page whose source contains `[data-placeholder]`449 elements. Surface the unsourced list and recommend sourcing450 real content (re-prototype, or edit the proposed file451 directly). There is no bypass flag — shipping placeholders to452 a public site is the failure mode this gate exists to prevent.453- **Color reservation violated.** Refuse the page; surface to454 user with the offending color and the reserved-for context.455- **Brand-faithful inversion conflict.** A hard rule declared456 inverted in457 `extensions.divergence.brand_faithful_inversions[]` is lifted458 from validation per T&M § Brand-faithful inversion handling.459 Emit a one-line note in the run summary acknowledging the460 lift.461462## What migrate does NOT do463464- Critique or audit the migrated output. Run465 `$impeccable critique stardust/migrated/` after migration if466 you want a quality assessment.467- Deploy. Stardust does not push, upload, or modify origin.468- Generate AEM EDS, a CMS payload, or framework components. The469 output is platform-agnostic static HTML; downstream conversion470 is a separate plugin's job.471- Re-fetch the live site. Offline after extract Phase 1.472- Run any iteration loop. Iteration belongs to `prototype`;473 migrate consumes the result.474475## References476477- `reference/migration-procedure.md` — per-page render procedure,478 output path mapping, validation, provenance shape, idempotent479 skip, sidecar schema.480- `reference/template-and-module-rendering.md` — three render481 branches in detail, slot injection, deviation policy,482 validation contracts.483- `reference/metadata-and-jsonld.md` — head composition, JSON-LD484 per page-type, canonical strategy.485- `reference/content-preservation.md` — what's kept,486 transformed, dropped; internal-link rewriting; asset path487 rewriting; form handling.488- `reference/asset-bundling.md` — detection / copy / rewrite489 contract for the per-page asset-bundling phase.490- `skills/stardust/reference/migrate-output-format.md` — the491 self-contained-bundle contract downstream consumers can rely492 on (asset reference shape, directory layout,493 `state.json.migrate` block).494- `skills/stardust/reference/token-contract.md` — `:root` block495 refreshed from DESIGN.md on every render.496- `skills/stardust/reference/data-attributes.md` — structural497 attributes including `data-template`, `data-module`,498 `data-slot`, `data-canon`, `data-deviation`, `data-bespoke`,499 `data-broken-link`.500- `skills/stardust/reference/state-machine.md` — page lifecycle,501 page typing, stale-flagging cascade.502- `skills/stardust/reference/artifact-map.md` — provenance shape503 for migrated artifacts; canon files; sidecar shape.504- `skills/prototype/reference/canon-extraction.md` — how canon505 is built (input to migrate).506- `skills/prepare-migration/SKILL.md` — the cascade that507 produces every input migrate consumes.