adobe avatar

stardust

Redesign an existing website to make it better. Higher-level guided flow on top of impeccable.

version
0.39.4
GitHub stars
332

Install

/plugin install stardust@adobe-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add adobe/skills.

Contents

Discovered from source

Skills 16

stardust:audit

One URL in. One scored, evidence-bound audit out.

audit looks at an existing website from three perspectives — design (brand tensions + concrete improvement opportunities), SEO/technical, and LLM/AI-search visibility — measures Core Web Vitals, and synthesizes everything into a seven-dimension scorecard plus a prioritized findings ledger that tells the owner what to improve to generate a better business outcome. The report is also the natural seed for a redesign: its findings feed the stardust uplift skill's improvements list and the stardust direct skill's Phase 2.5, and it closes with uplift-shaped redesign directions so "run $stardust uplift" is the obvious next step.

Opinionated defaults

  • Multi-page by default — $stardust extract <url> --cap 8 (home + seven IA pillars) unless --single or --pages overrides.
  • Non-interactive — the audit never asks questions. Every assumption it makes instead is recorded in audit.json#assumptions and stated in the report's executive summary.
  • Evidence-bound — every claim cites a measurement, a T-* tension id, a check result, or a screenshot observation. A claim with no citation does not ship.
  • No fabricated data — a measurement that could not be taken is reported as not measured (<reason>), never estimated silently. An estimate, where reasoned, is labeled as one with its basis.
  • Graceful degradation, not failure — optional capabilities (refero, marketing-skills, modern-web-guidance, PageSpeed Insights) are probed once and their absence is recorded, never fatal. See § Degradation ladder.

Inputs

  • <url> — required. The site to audit. A path narrows the crawl to that subtree (extract's semantics).
  • --pages <n> — optional. Override the default 8-page extraction cap (passed through as --cap <n>).
  • --single — optional. One-page audit of the given URL only. The cross-page checks (duplicate titles, sitemap coverage, CTA fragmentation across pages) then run on a single page and say so.
  • --deploy — optional. After the report renders, publish report.html as a single self-contained page via the DA transport (../deploy/da-deploy-protocol.md: source PUT → preview → live) and print the delivered URL. Transport only — the report never goes through deploy's section→block conversion, which would decompose the self-contained file.
  • --benchmark — optional. Force Phase 5 reference benchmarking: probe the refero MCP even when the earlier capability probe was slow or ambiguous. Without this flag Phase 5 fires only when the probe succeeds quickly.

There are no other flags. Everything else is derived from the captured surface or governed by the underlying skills' contracts.

Phase 0 — Setup

  1. Run the master skill's setup (../stardust/SKILL.md § Setup) — with one audit-specific carve-out: impeccable absence is a degradation here, not the master setup's hard stop. When the dep check fails, record impeccable: unavailable in audit.json#degradations and continue — Phase 2 runs without the critique/audit arms (VISION pass + accessibility fold-in still fire) and Phase 6 skips the report render; the run ends at stop condition (b) after audit.json is written.
  2. Extraction freshness check. If stardust/current/ holds an extraction of the same origin less than 7 days old — origin from stardust/state.json (the site record extract stamped), recency from the newest pages/<slug>.json#_provenance.fetchedAt — reuse it and record site.extraction.reused: true. Otherwise invoke $stardust extract <url> --cap 8 (or --single / --pages <n> per the inputs). Extract owns the crawl, the screenshots, _brand-extraction.json, pages/<slug>.json, PRODUCT.md / DESIGN.md, and brand-review.html with its Tensions section.
  3. Probe optional capabilities once, recording each outcome in the degradation record (audit.json#degradations):
    • marketing-skills plugin (seo-audit, ai-seo skills present?)
    • modern-web-guidance (npx -y modern-web-guidance@latest search "<query>" responds?)
    • refero MCP (attempt mcp__refero__refero_search_styles; treat a tool-not-found or timeout as unavailable)
    • PageSpeed Insights API (network-reachable without a key?)
    • rollout project (stardust/rollout/rollout.json present?)

If extract fails entirely (site unreachable, bot-management block past the headed-Chrome fallback), stop and surface extract's error verbatim — there is nothing to audit. This is the only hard stop before synthesis; see § Stop conditions.

Procedure

Phase 1 — Brand surface & tension analysis

Read stardust/current/_brand-extraction.json and stardust/current/brand-review.html § Tensions surfaced (rule catalog in ../extract/reference/brand-review-template.md § Tensions). Every fired T-* tension is candidate evidence for a finding — carry the ids forward, do not re-derive the detections.

Compute the four brand-expression measurements the report needs. Each lands in audit.json#measurements with status + method per reference/report-format.md:

  • brandColorShare — brand-color share of painted pixels on the captured home screenshot. Preferred method: Playwright pixel sampling (method: "pixel-sample") — load the screenshot, sample a grid (e.g. every 8th pixel), classify each sample to the nearest palette entry within a tolerance, and divide brand-hue samples by painted (non-white/near-white) samples. When sampling is infeasible in the session, a reasoned estimate from the captured surfaces is allowed but must ship as method: "surface-estimate" with its basis — never presented as measured.
  • ctaFragmentation — distinct CTA labels per equivalence bucket, aggregated from pages/*.json#ctas[].label (the same buckets that drive T-cta-vocab).
  • typeScale — distinct heading sizes and scale kind/ratio from _brand-extraction.json#type.scaleAudit.
  • radiusSprawl — distinct border-radius values with occurrence counts from _brand-extraction.json#motifs.borderRadius.

Phase 2 — Design & experience critique

Three passes over the captured home page (screenshot + live URL), folded into one set of design findings:

  1. impeccable critique + audit. Invoke impeccable through the harness's skill-invocation tool using the delegation mechanic in ../prototype/SKILL.md § Invoking impeccable (Claude Code form: Skill { skill: "impeccable:impeccable", args: "critique <target>" }, then "audit <target>" for the accessibility / responsive / performance passes). Normalize its findings into the audit's finding shape.
  2. VISION pass. Study the captured screenshots directly (stardust/current/assets/screenshots/<slug>.png) and name what a design director would: dated patterns the field has moved past, hierarchy failures, missed opportunities the captured surface doesn't capitalize on. The claim discipline is absolute — every observation cites a measurement, a tension id, or a screenshot region ("home.png, hero: three equal-weight CTAs compete"). Adjectives without evidence do not become findings.
  3. Accessibility fold-in. Contrast computed (WCAG ratios for the captured palette pairs in the roles they are actually used in), alt coverage from pages/*.json#media.images, landmark presence and heading order from pages/*.json#landmarks, content-free link labels (reuse T-link-content-free when fired).

Phase 3 — SEO & technical

When the marketing-skills plugin is installed, follow marketing-skills:seo-audit's methodology and normalize its issue/impact/evidence/fix items into findings. When absent, run the checks directly — they are all curl/Playwright-derivable:

areachecksmethod
Crawlabilityrobots.txt present and sane; sitemap declared and valid XMLcurl
Indexationcanonical present and self-referential; meta robots not accidentally noindex; http→https single-hop redirect; redirect chainscurl -I
Semanticsmain/nav/footer landmarks; single <h1>; heading hierarchy without skipspages/*.json + Playwright
Metadatatitle/description presence + quality per page; duplicates across pages; Open Graph completenesspages/*.json#metadata
Structured dataJSON-LD presence, parse validity, entity types vs page typePlaywright / curl

Where a failure matches a rollout:baseline check id (../rollout/reference/checks.md: single-h1, title-missing, meta-description, canonical, sitemap, jsonld, img-alt, landmark-main, duplicate-title), reuse that id as the finding's evidence.ref (check:<id>) — findings recorded into a rollout ledger under a known id get picked up by the AEM autofix registry automatically.

Core Web Vitals. Measure LCP / CLS / TBT via Playwright performance APIs (PerformanceObserver for largest-contentful-paint and layout-shift, longtask entries for TBT) on two viewports: mobile (375×667, CPU throttled where the session supports it) and desktop (1440×900). When the PageSpeed Insights API is network-reachable without a key, prefer it and record method: "psi-api" (it adds field INP); otherwise record method: "playwright-lab" and say in the measurement note that lab TBT is a proxy for INP. Classify every metric against the Google thresholds tabled in reference/scoring.md § performance.

Remediation guidance. When modern-web-guidance is installed, run npx -y modern-web-guidance@latest search "<specific failure>" for each distinct failure class and cite the returned guide ids in the finding's guides[]. When absent, write the generic remediation and leave guides: [].

Phase 4 — LLM visibility

When marketing-skills:ai-seo is installed, follow its methodology. When absent, assess directly:

  • llms.txt — present at the origin root?
  • Answerability — does each audited page answer the question a user would ask of it ("what does this cost", "what is this") in extractable, well-structured prose — and how early on the page?
  • schema.org coverage — do the JSON-LD entities cover the organization plus the page-type entities an answer engine needs for entity understanding?
  • Heading-as-question coverage — what share of h2/h3 map to askable questions or scannable topics rather than slogans?
  • Content depth — extractable prose word counts on key pages; specific, citable claims vs thin marketing copy.
  • Key facts in crawlable text — are pricing, what-it-is, and who-it's-for stated in crawlable text, or locked in images and JS-rendered widgets?
  • Citation readability, measured — run skills/deploy/scripts/ai-readability.mjs --origin <site> <sampled paths> and report the strict score per page with the top blocks adding rendered-only words; it is the exact formula of Adobe's AI Content Visibility Checker (deploy/reference/ai-readability.md).

Every Phase 4 finding names the concrete fix ("state the three price points in the pricing table as text; they currently render only inside the plan-card images"), not a category ("improve content").

Phase 5 — Reference benchmarking (optional)

Fires when the refero MCP tools are reachable — the Phase 0 probe attempted mcp__refero__refero_search_styles; --benchmark forces a re-probe. Skip gracefully when unavailable (benchmarks: { status: "skipped", reason: … }).

When available: retrieve 2–3 same-vertical reference styles, compare the audited site's brand expression (Phase 1 measurements) against what best-in-class in the category does, and cite each reference — title, URL, one line on what they do better — in the relevant design findings and in audit.json#benchmarks.references.

Phase 6 — Synthesis & report

  1. Scorecard. Score the seven dimensions per reference/scoring.md — anchors first, evidence floor enforced, not-measured dimensions nulled and renormalized. Compute the weighted overall.

  2. Findings. Consolidate Phases 1–5 into the prioritized ledger: P1 (actively losing business or excluding users) / P2 (material drag) / P3 (polish). Per finding: dimension, evidence (measurement / tension / screenshot / check / benchmark citation), businessImpact one-liner, concrete fix, guides[].

  3. Uplift directions. Close with 2–3 redesign directions framed exactly like uplift's variant role contract (../uplift/SKILL.md § The three-variant role contract): A faithful + fixes (names the findings it resolves), B one captured-but-underused trait amplified, C cinematic (motion as identity, register suggested per ../prototype/reference/motion-registers.md § Selection heuristic). Drop B when the captured surface can't support a differentiated middle — two strong directions beat three weak ones.

  4. Write stardust/audit/<domain-slug>/audit.json — schema, slug convention, and measurement rules in reference/report-format.md Part 1. Provenance _provenance first key.

  5. Render stardust/audit/<domain-slug>/report.html by delegating to $impeccable craft with the brief in reference/report-format.md Part 2 — the same skill-invocation mechanic as prototype, and the same rule: never hand-template the report. Run the post-render validation checklist; on failure re-invoke craft with the specific violation. Open the result with open stardust/audit/<domain-slug>/report.html.

  6. Ledger recording (rollout projects only). When stardust/rollout/rollout.json exists, record each finding into the delivery ledger via node skills/rollout/scripts/findings.mjs record with source namespace audit: — --source audit:<dimension>, --layer from the mapping below, severity carried through, --fixability normalized per ../rollout/reference/audit-sources.md § Recording an external finding. Write each returned id into the finding's ledgerId.

    audit dimensionledger layer
    brand-expressionbrand-tensions
    visual-hierarchy-craftdesign-ux
    conversion-focuscontent-conversion
    accessibilityaccessibility
    technical-seoseo (site-wide: cross-page)
    content-llm-visibilityai-search
    performanceseo
  7. --deploy. When passed, publish report.html via the DA transport per ../deploy/da-deploy-protocol.md — PUT the file as a single source, POST preview, POST live, verify the delivered URL returns 200 — and print the delivered URL. Transport only; never run deploy's section→block conversion on the report.

  8. Chat summary. Short — the work is on disk and openable:

    audit complete — <url>
    
    Site health: <overall>/100
      <dimension>: <score>   × 7 (not-measured dimensions listed with reasons)
    
    Findings: <n> P1 · <n> P2 · <n> P3
    Top lever: <the single highest-impact P1, one line>
    
    Report: stardust/audit/<domain-slug>/report.html
    Data:   stardust/audit/<domain-slug>/audit.json
    
    Next: run `$stardust uplift <url>` — the report's closing directions
    are its variant briefs.
    

Degradation ladder

Probed once in Phase 0; every degradation is recorded in audit.json#degradations and rendered in the report's methodology appendix. None of these stops the audit.

capability absentbehavior
refero MCPskip Phase 5; benchmarks.status: "skipped" with reason
marketing-skillsrun the Phase 3 / Phase 4 checks directly (tabled above)
modern-web-guidancegeneric remediation text; guides: []
PageSpeed InsightsPlaywright-only lab metrics; measurement note says lab TBT proxies INP
Playwright pixel sampling infeasiblebrandColorShare ships as method: "surface-estimate" with basis
rollout projectno ledger recording; ledgerId: null on every finding

Hard constraints

  • No fabricated data. A measurement that could not be taken is not measured (<reason>) in both artifacts. Estimates are labeled with method + basis. This is the same discipline extract enforces against synthesis (../extract/SKILL.md § Failure modes) — fabricated audit numbers are worse than missing ones because they are actionable-looking and wrong.
  • Evidence discipline. Every finding cites observable evidence: a measurement key, a T-* tension id, a screenshot region, a check id, or a benchmark URL. Uncited claims are cut in synthesis.
  • Report is craft-rendered. report.html is authored by $impeccable craft against the brief in reference/report-format.md, validated afterward — never hand-templated, never hand-patched.
  • Provenance is mandatory on both artifacts, per ../stardust/reference/artifact-map.md § Provenance shapes.
  • Non-interactive. No questions in normal flow; assumptions are stated in the report. The only stops are the two below.
  • Audit does not fix. Fixes belong to uplift (page redesign), direct Phase 2.5 (improvements list), and rollout's optimize loop (platform autofix). Audit names the fix; it never edits the site.

Stop conditions

Stop and surface only if:

(a) Extract fails entirely — site unreachable, structure unparseable, bot-management block past the headed-Chrome fallback. Surface extract's error verbatim; nothing to audit. (b) impeccable unavailable — Phase 2's critique/audit arms and Phase 6's report render require it. Per the Phase 0 carve-out, the run continues in degraded mode (VISION pass, SEO/technical, LLM visibility, benchmarks all still fire) and writes audit.json; then stop and tell the user the designed report needs the impeccable plugin — deliver the data, not a hand-templated substitute.

Everything else degrades per the ladder; the audit never stops for confirmation in normal flow.

Outputs

stardust/
├── current/                             ← from extract (reused when <7 days old)
│   ├── _brand-extraction.json
│   ├── brand-review.html                ← Tensions section = Phase 1 input
│   ├── pages/<slug>.json
│   └── assets/screenshots/<slug>.png    ← VISION-pass + report evidence figures
└── audit/
    └── <domain-slug>/                   ← hostname, www-stripped, dots → dashes
        ├── audit.json                   ← scorecard, measurements, findings[], provenance
        └── report.html                  ← craft-rendered, self-contained

stardust/rollout/optimize/findings.json  ← appended via findings.mjs (rollout projects only)

Audit writes no state.json entries — extraction state belongs to extract; audit's own artifacts are self-describing via provenance. Re-running audit against a fresh extraction overwrites stardust/audit/<domain-slug>/; ledger recordings dedupe by the ledger's own id hash.

Scope

  • Audits and prescribes; never modifies the site or its redesign artifacts.
  • One origin per run. Auditing a competitor set is N runs.
  • The natural continuations: $stardust uplift <url> (the closing directions are its variant briefs), the stardust direct skill (findings feed the Phase 2.5 improvements list), rollout's optimize loop (ledger findings with known check ids autofix on AEM).

References

  • reference/scoring.md — the seven dimensions, weights, observable anchors at 40/70/90, scoring procedure.
  • reference/report-format.md — audit.json schema (Part 1) and the report.html craft brief + post-render validation (Part 2).
  • ../extract/SKILL.md — crawl, capture, brand-surface extraction; § Failure modes for the anti-synthesis discipline.
  • ../extract/reference/brand-review-template.md § Tensions — the T-* detector catalog Phase 1 carries forward.
  • ../prototype/SKILL.md § Invoking impeccable — the skill-invocation delegation mechanic reused for critique (Phase 2) and the report render (Phase 6).
  • ../rollout/reference/audit-sources.md — the findings-ledger normalization rules (severity, fixability) Phase 6 applies.
  • ../rollout/reference/checks.md — baseline check ids to reuse so AEM autofix picks the findings up.
  • ../rollout/scripts/findings.mjs — the ledger writer (record).
  • ../uplift/SKILL.md § The three-variant role contract — the frame for the closing uplift directions.
  • ../prototype/reference/motion-registers.md § Selection heuristic — register suggestion for direction C.
  • ../direct/SKILL.md § Phase 2.5 — the improvements list audit findings feed on a subsequent redesign.
  • ../deploy/da-deploy-protocol.md — the DA transport behind --deploy (source PUT → preview → live; no block conversion).
  • ../stardust/SKILL.md § Setup — master-skill setup run in Phase 0.
  • ../stardust/reference/artifact-map.md — provenance shapes.

stardust:deploy — prototypes → EDS/AEM

This file is the outline. The text of each section below is in skills/deploy/reference/, in the file the section names. Read that file in full when you reach the section; never work from a heading alone. A numbered rule that another file cites as #N is in one of those files: search skills/deploy/ for #N.

When to use

The user has:

  1. Per-page styled HTML prototypes — one file per page, each carrying its own CSS. Accept any of these shapes:
    • Single-file with inline <style> and :root tokens + semantic <section class="…"> (e.g. stardust output, or claude-design "Stardust"/Mobirise/Relume-style pages). Easiest — convert directly.
    • External per-page .css (the <style> lives in a sibling stylesheet). Read the linked CSS the same way you'd read an inline <style>.
    • <x-dc> document-content with everything inline-styled (per-element style="…"). Harder — you must lift inline styles into a scoped block stylesheet.
    • React/JSX prototypes (an HTML shell that mounts .jsx components at runtime). Pre-render to static HTML first (run it, or screenshot + read the JSX to reconstruct the DOM); you cannot decorate a shell that has no server-rendered <main>. The prototypes typically live under stardust/prototypes/** or a samples/<Name>/ folder — don't hard-code the path; discover them.
  2. An EDS project at the repo root — vanilla aem-boilerplate (github.com/adobe/aem-boilerplate): scripts/aem.js + scripts/scripts.js, blocks/ with header/footer/fragment, styles/styles.css + styles/fonts.css, head.html. This is the ONLY runtime this skill targets — no runtime files are ever ported, vendored, or edited.
  3. A goal to convert: prototypes → authorable EDS blocks + EDS content pages under content/**.

If the user has prototypes but no EDS scaffolding, stop and ask whether to scaffold from adobe/aem-boilerplate (use the template as-is; the conversion never modifies scripts/aem.js). If they have EDS but no prototypes, this skill doesn't apply.

Flow guard (stardust projects). When stardust/state.json exists but has no flow and the ask is a migration (a URL plus "migrate" / "to EDS" / "re-platform"), stop before Step 1: print the master skill's two-flow table (skills/stardust/SKILL.md § Two migration flows) and hand back to its routing, which stamps flow (skills/stardust/reference/state-machine.md § Flow keys). Hand-authored prototypes with no state.json are unaffected — that is this skill's standalone use.

Target runtime — vanilla aem-boilerplate (what the generated code can rely on)

Read skills/deploy/reference/target-runtime.md in full before you act on this section.

Playwright re-probe (run before anything that renders)

Read skills/deploy/reference/target-runtime.md in full before you act on this section.

Runtime-detection probe (run before Step 1 — write stardust/runtime-contract.json)

Read skills/deploy/reference/target-runtime.md in full before you act on this section.

Deploy (DA Source API, from a local agent)

Read skills/deploy/reference/da-source-api.md in full before you act on this section.

The one rule that drives everything else

One distinct visual PATTERN = one EDS block — and a section with NO pattern is NOT a block at all. The content structure that lands in DA must follow David's Model (davids-model.md, bundled with this skill — the 15 rules mapped to this skill's contracts; cited as D#N throughout). Its first rule shapes everything here:

  • D1 — blocks aren't ideal for authoring. A block is a table an author must maintain. A section whose content is plain prose — heading, paragraphs, an image, CTAs, with no repeating units and no bespoke interactive structure — is authored as DEFAULT CONTENT in its own section, never wrapped in a block. Its skin rides a minimal section-metadata style value (see Step 3); the section's semantics stay native <h2>/<p>/<picture>/<a>. Never create a text/heading/image block around bare default content — that is the D1 anti-pattern verbatim.
  • Blocks are for structure default content can't express: repeating units (cards, FAQ, logos, team), genuinely bespoke compositions (a countdown, a stat band, a cinematic hero), and interactive components. For those, one distinct prototype pattern = one block. Don't abstract speculatively, and don't extract "patterns" across prototypes unless sections are genuinely the same pattern — each pattern's bespoke CSS can't be wrongly shared; violating this casually cost full resets (see ANTI-PATTERNS).

The one deliberate exception — collapse SAME-PATTERN sections into one block + VARIANT classes. When two or more sections are the same content pattern (card grids, prose/CTA bands, quotes, accordions) differing only in skin, emit ONE canonical block (cards, text, quote, accordion) and put each section's look behind a variant class (class="cards brands"), brand styling in the variant CSS. The block JS stays generic (classify cells by content); only the CSS differs per variant. This is the David's-Model library win (D9: small, reusable, variant-driven — not 20 bespoke names) and is proven to preserve fidelity. Keep genuinely-unique sections (a hero, a countdown) bespoke. Budget for it: variant CSS is careful work and some grids are count-specific.

The prototype is the visual spec. The block exists to AUTHOR its content — see The ENCODE contract below for what well-authored content looks like, and ANTI-PATTERNS for how a block must defensively PARSE it.

Output you will produce

For a typical 5–10 page site:

  • One block per distinct prototype PATTERN (D1/D9). A 5-page site with 6 sections each → typically ~8–14 blocks: prose bands land as default content, same-pattern sections share one block + variants, and only genuinely bespoke sections get their own block.
  • One EDS content page per prototype page. Same number of pages.
  • Nav + footer documents at content/nav.html and content/footer.html — authored content, deployed and published like any page, fetched by the stock header/footer blocks (D12: chrome is the canonical fragment use case).
  • Per-site blocks/header + blocks/footer CSS/JS reproducing the prototype's chrome (see Step 6).
  • Updated styles/styles.css with brand tokens lifted from the prototype's :root, a reset, the EDS section scaffold, a global button system (see "Lean on EDS button conventions" below), and the styles for the few section-metadata style values default-content sections use. Nothing more.
  • No shared utility modules. No wave systems. No motion library. The prototype already encodes these per-section; keep them inside the owning block. Section-metadata style values stay a SMALL closed set (dark, tinted, …) used only by default-content sections — blocks keep painting their own sections.

The ENCODE contract — what well-authored content looks like

Read skills/deploy/reference/encode-contract.md in full before you act on this section. It covers: Section heads: default content the block reabsorbs; Images: editorial → authored content, decorative → CSS only.

Steps

1. Audit (light)

Read skills/deploy/reference/step-1-audit.md in full before you act on this section.

2. Decide names + reuse — LOCK BEFORE WRITING ANY CODE

Read skills/deploy/reference/step-2-names-and-schema.md in full before you act on this section.

2b. Section schema + decode tier — close the round-trip BEFORE writing code (#93, #95)

Read skills/deploy/reference/step-2-names-and-schema.md in full before you act on this section.

3. Foundation

Read skills/deploy/reference/step-3-foundation.md in full before you act on this section.

4. Self-host fonts and minimize CLS — never put font loads in head.html

Read skills/deploy/reference/step-4-fonts.md in full before you act on this section.

5. Lean on EDS button conventions — DO NOT manufacture button anchors in block JS

Read skills/deploy/reference/step-5-buttons.md in full before you act on this section.

6. Chrome — authored /nav + /footer documents, template-slotted header/footer blocks

Read skills/deploy/reference/step-6-chrome.md in full before you act on this section.

7. Blocks (parallel agents)

Read skills/deploy/reference/step-7-blocks.md in full before you act on this section.

8. Block JS scaffold

Read skills/deploy/reference/step-8-block-js.md in full before you act on this section. It covers: Experience Workspace editability contract.

9. Content page scaffold

Read skills/deploy/reference/step-9-content-page.md in full before you act on this section.

Local QA before deploy (no DA)

Read skills/deploy/reference/local-qa.md in full before you act on this section.

Step 10 — Reconcile on the DEPLOYED URL (content-diff ADVISORY + eyeball + CLS)

Read skills/deploy/reference/step-10-reconcile.md in full before you act on this section.

Anti-patterns (lessons paid for the hard way)

Read skills/deploy/reference/anti-patterns.md in full before you act on this section.

Checklist (per page)

Read skills/deploy/reference/checklist.md in full before you act on this section.

When you finish

First page of a site, or a new block or variant: publish the DA library (../rollout/SKILL.md § Phase D, #160). Update stardust/eds-conversion-log.md (or create one) with: final block inventory, decisions locked, anti-patterns avoided this run, anything site-specific the next person should know. The log is the running history of "why does this look the way it does."

References

  • davids-model.md — David's Model (aem.live) distilled: the 15 rules (D#N), each mapped to the contract or gate in this skill that enforces it, plus the component-model shape compatibility notes.
  • da-deploy-protocol.md — the curl-based DA Source API deploy contract (auth, source PUT, preview/publish, asset-before-preview ordering).
  • (#NN) citations in this document and in the deploy/diff scripts point to the deploy improvement ledger (findings #1–#80), removed from the tree; read it with git show 940b8795:plugins/stardust/notes/deploy-improvements-archive.md. New findings go to skills/stardust/reference/learnings.md.
  • scripts/ew-editability-probe.mjs — the Experience Workspace editability gate (Step 8 § contract): instrument → decorate → count survivors; --simulate-editor edit-mode drift; URL and --content harness modes; reads @ew-exempt JSDoc tags.
  • Experience Workspace sources the contract was verified against (read them when the mechanism seems to have changed): da.live blocks/canvas/editor-utils/editor-utils.js (getInstrumentedHTML — what is stamped), blocks/canvas/ew-editor-wysiwyg/ew-editor-wysiwyg.js, blocks/shared/prose2aem.js (cells keep their <p>); da-nx nx/public/plugins/quick-edit/quick-edit.js (setBody → loadPage → restoreBlockIndices), src/prose.js (createEditor swap shape), src/images.js, src/dom-index.js, src/selection.js (cursor math on textContent length).

stardust:diff — prototype ↔ build reconcile

Two probes that compare a source prototype against a built page. They catch disjoint failure classes — run BOTH; either alone gives a false "looks fine".

Both are framework-agnostic Playwright probes that compare two rendered URLs by computed style + DOM (not pixels). All stack-specific language lives in a profile (--profile eds|generic); the comparison logic is generic.

When to use

  • After converting a prototype to EDS (the stardust deploy skill's Step 10) — use --profile eds.
  • Any "does the build match the design?" check between two rendered URLs (a Figma export vs a React build, a legacy page vs a rebuild) — use --profile generic.
  • Inside a conversion/QA workflow as the validation gate (see Workflow use).

Not for: a single static file with no JS decoration (use the build/harness URL so components are decorated — a raw .plain.html has no roles to classify).

The two probes

ProbeScriptSeesBlind to
Pixel / layoutskills/diff/scripts/visual-diff.mjsstretched images (vs the source), dropped max-width wraps, blank renders, surface/ground colour flips, heading size/face deltas, image-count gaps"right text, wrong slot"; a dropped CTA (full pixels, plausible colours → no flag)
Structural content + typeskills/diff/scripts/content-diff.mjsMISSING / ROLE-SWAPPED headings·eyebrows·CTAs, invented/dropped body copy, rendered-FACE font forks (width probe); dropped placeholder/aria-label/title values, missing/wrong/moved icons — on the main root AND the header/footer chrome roots by defaultgeometry / layout regressions

content-diff extracts an ordered, role-classified inventory (heading / eyebrow / cta+href / body) from each root — the --main root(s) plus, by default, the header and footer chrome roots — classifying by computed style + tag so the prototype's DOM and the built DOM compare symmetrically, then diffs them root by root; a second inventory per root carries the placeholder / aria-label / title values and the icons.

Run it

# Prereq 0: playwright importable from the project root (node -e "import('playwright')"), else
# npm i -D playwright pixelmatch pngjs cheerio --legacy-peer-deps
# (never --no-save; extract SKILL.md § Setup). Run the copied scripts from the project
# root: ESM resolves from the script.
# Copy the WHOLE skills/diff/scripts/ dir: content-diff imports its local diff-profiles.mjs
# AND content-inventory.mjs (deploy keeps its own synced copies for #93/#94), plus the
# master's scripts/ (browser.mjs, the one entry to the browser) in stardust/scripts/stardust/.
# Prereq: a RENDERABLE source. Static → serve from its own dir (python3 -m http.server).
# The build URL must be the DECORATED page (live/preview or a local harness), not raw markup.
# ONE server, ONE port — probe before starting one (curl is always present, lsof is not):
curl -sI localhost:8791/ | head -1                   # 200/404 = something serves the port; no line = free
curl -sI localhost:8791/<prototype>.html | head -1   # 200 = it serves YOUR dir: reuse it
command -v lsof >/dev/null && lsof -nP -iTCP:8791 -sTCP:LISTEN   # optional: names the pid
# Nothing answered → start yours. A foreign server: never kill it; use a per-project port
# (the traps: ../deploy/SKILL.md § Step 10).
PROTO="http://localhost:8791/<prototype>.html"
BUILD="https://<branch>--<repo>--<owner>.aem.page/<path>"   # or http://localhost:3000/<harness>

# 1. PIXEL/layout
node skills/diff/scripts/visual-diff.mjs   "$PROTO" "$BUILD" --profile eds --sections ".hero"

# 2. STRUCTURAL content + type
node skills/diff/scripts/content-diff.mjs  "$PROTO" "$BUILD" --profile eds   # --json dumps both inventories

Flags (both tools): --profile eds|generic (default eds), --width <px> (default 1280), --main <selector[,selector…]> (content root; content-diff defaults from the profile and takes a comma-separated list — every root is inventoried and diffed on its own and each finding line carries its root as [root]; visual-diff takes one selector, default main), content-diff only: --chrome / --no-chrome (default on — the header and footer roots, resolved as the first <header>/[role=banner] and <footer>/[role=contentinfo] outside the main root(s), are compared beside it; a side lacking one is measured as empty there and the root line says so), plus the live-target set (shared engine: skills/stardust/scripts/live-session.mjs — real Chrome presents its user agent without the headless token and matching client hints; automation-signal handling stays on unless STARDUST_STEALTH=0; every context sends standard Chrome request headers, and live navigations to one host are paced STARDUST_LIVE_PACE_MS apart (default 1000), capped by STARDUST_LIVE_MAX_PARALLEL (default 2) and STARDUST_LIVE_MAX_WAIT_MS (default 300000; 0 disables):

  • --ua <string> — user agent override (default: the browser's own with HeadlessChrome replaced by Chrome).

  • --wait-until <state> — goto wait override. Default rule (one shared defaultWaitUntil in skills/stardust/scripts/live-session.mjs), decided per URL side, three tiers:

    • localhost/127.0.0.1 → networkidle (local prototypes / harnesses, unchanged);
    • EDS build/preview origins — hostnames ending in .aem.page, .aem.live, .hlx.page, .hlx.live → networkidle (they decorate asynchronously and reliably reach networkidle; measuring at domcontentloaded reads the pre-decoration DOM — flaky false reds / FONT FORK on deploy Step 10);
    • all other live http(s) → domcontentloaded (live sites with analytics beacons never reach networkidle).

    --wait-until overrides all three tiers.

  • --dismiss [sel,...] — dismiss overlays on both sides: cookie consent (clicked, not removed) AND timed marketing/newsletter modals, plus optional extra site-specific selectors; the mouse is parked afterwards.

  • --headed — escalation for bot-managed sites: the same real Chrome plus the challenge-solve window and existing launch flags, window-free; STARDUST_STEALTH=0 disables the flags and context spoof, while STARDUST_HEADED_WINDOW=1 opens a window.

  • --locale <tag> — pin Accept-Language + context locale (geo-redirecting sites capture a different locale per run otherwise).

visual-diff also: --out <dir>, --sections a,b (per-section screenshots).

A bot-management challenge/blocked interstitial on either navigation fails LOUD with exit 3 — it is never measured as the source. Escalate with --headed; if that is still blocked, the site needs crawl.mjs-class capture and the check cannot run unattended.

A plain (non-challenge) HTTP error on either side — e.g. a 404 build side, normal on aem.page before preview propagation — is NOT fatal: the probe logs a loud warning, measures the error page, and the flags (BLANK RENDER / content asymmetry) carry the signal with exit 0. That is the probes' advisory contract: 0 = ran (flags advisory), 1 = probe error, 3 = bot challenge.

The published-origin probes (#125)

content-diff reconciles a prototype with its build; against a LIVE commerce origin its per-node findings were false, and the pixel gate passed a page whose every card was clipped (../replica/reference/source-fidelity-gate.md § The all-pages published-origin gate). Three probes ask the checkable questions; all load both sides in the same window-free real-Chrome tier and settle them the same way (scripts/measure-live.mjs).

ORIGIN="https://www.example.com/<path>"; SERVED="https://main--repo--owner.aem.live/<path>"
node stardust/scripts/diff/clip-probe.mjs "$SERVED" [--json clip.json]                       # D1: exit 2 on cut / hidden text or controls
node stardust/scripts/diff/content-presence.mjs "$ORIGIN" "$SERVED" [--variable "<selO>=<selE>"]  # D2: exit 2 on MISSING/HIDDEN link or heading
node stardust/scripts/diff/unit-geometry.mjs "$ORIGIN" "$SERVED" --unit "<selO>=<selE>" --n 2      # D3: exit 2 on an element off / hidden / missing

Reading: a 🔴 clip group names the clipper (a fixed-height box with overflow: hidden) — fix that block's CSS, never the content. HIDDEN LINK = in the DOM but clipped (CSS); MISSING LINK = not served (encoder); CONTROL STATE = same control, another value; COUNT … = session-variable region, confirm by eye. The origin side fails loud on HTTP ≥ 400 (exit 4) and a bot challenge (exit 3). Traps: an infinite-scroll origin keeps loading under the settle — mark the region --variable; a live origin without <main> compares whole page against whole page (the scope line says so), header / footer left to the chrome crop gate unless --chrome; the count-phrase and "read more" heuristics are English word lists (--count-words, --more-words).

The header contract (#132)

Every probe above sees the header at rest (pointer parked, motion frozen), so it passes with every menu wrong; runs shipped boilerplate click dropdowns for hover mega menus, search and cart as plain links, a static list for a drill-down drawer. The header's behaviour is recorded from the source once and the build compared with it:

node stardust/scripts/diff/chrome-explore.mjs "$ORIGIN" stardust/chrome/header-contract.json   # 1440 + 390
node stardust/scripts/diff/chrome-explore.mjs "$SERVED" stardust/chrome/header-build.json --max-requests 0 --pace-ms 0 --reload-pause-ms 0   # our host: source-edge protections do not apply
node stardust/scripts/diff/chrome-compare.mjs stardust/chrome/header-contract.json stardust/chrome/header-build.json \
  --profile replica --json stardust/chrome/header-parity.json    # functional under redesign and reskin

The explorer hovers (desktop), clicks and keys every header control and records each opened state (links, headings, crop, aria-expanded, focus, scroll lock, motion, close paths), nested levels within --max-states 400 --max-depth 4, search typeahead and submit, and the header scrolled; its summary line sizes the work. The comparer exits 2 on a missing control or state (hover rebuilt as click included), panel links, keyboard, close paths or scroll lock; replica adds open-state crops (2 %), motion (max(80 ms, 25 %)) and scroll states. Only the site owner clears a finding: stardust/chrome/header-decisions.json ({ decisions: [{ finding, decision, reason, by, at }] }), never signed by an agent. It runs at extract --prep (the contract), on the foundation shell and in deploy Step 10, on the live host before handover (done-check header_parity), and in qa. Crops stay in stardust/.work/chrome/.

Reading content-diff

  • 🔴 MISSING CTA / HEADING / EYEBROW — real dropped content. FIX. A missing eyebrow is most often a segmentation drop where the eyebrow precedes its heading; a missing CTA means the component never rendered the link. These are exactly what the pixel probe cannot see.
  • 🔴 ROLE SWAP — same text under a different role (body painted as eyebrow, eyebrow folded into a teaser). FIX the component's node segmentation. With the same look, body/eyebrow → heading is an accepted ROLE UPGRADE (root line and --json accepted, not a finding), heading → body/eyebrow 🟡 ROLE DOWNGRADE. Lost visually hidden (sr-only) text is 🟡 MISSING SR-ONLY TEXT; a lost sr-only link stays 🔴 MISSING CTA.
  • 🔴 MISSING PLACEHOLDER, MISSING ICON, ICON DIFF on an interactive element (an input, a button, a link or inside one) — a dropped localized search placeholder, a share link without its icon, a wrong flag in a locale link, an empty icon box. FIX. Outside interactive elements the same findings are 🟡. A lost aria-label is a nothing-lost 🟡 anywhere (fails the gate).
  • Icons pair by identity or by the same pixels: a re-hosted file (SAME IMAGE) or an svg drawn as <img> (SAME ICON) is accepted. A laid-out 0×0 icon is not one.
  • 🟡 MISSING TITLE — always 🟡: a title tooltip is not read by most assistive tech and is commonly dropped by design. 🟡 ICON MOVED — the same icon at another anchor, paired after the anchor passes (typically a text-less <button> host that anchors as button#n): CONFIRM its placement. 🟡 ICON KIND (pixels not compared, e.g. a hidden icon) and every EXTRA.
  • Every finding line names its root — 🔴 MISSING PLACEHOLDER [header]: … — and the report prints one block per root (root "main", root "header", …; a root a side lacks is measured as empty there and the line says which side).
  • 🟡 MISSING BODY / EXTRA — body prose dropped, or build copy with no source. Usually a placeholder→real-copy rewrite. CONFIRM intended; don't blindly "fix".
  • 🟠 FONT FORK — matched lines whose rendered FACE differs (width probe, never document.fonts.check). source X→sys means the prototype named font X but never loaded it and fell back to system — the build self-hosting the intended fallback is then CORRECT, not a bug. All forked lines are grouped into one advisory.
  • Known limitation — node-granularity JOIN/SPLIT reads as 🔴 (#87). When the source renders one text run as N sibling nodes and the build renders the same text as ONE node (or vice versa — e.g. three fact chips vs one combined chip span), the diff currently reports MISSING + ROLE SWAP + EXTRA for what is a non-defect. Until concat-matching lands (a source node that is a substring of a same-region build node → 🟡 JOIN/SPLIT advisory), verify a 🔴 whose texts concatenate into an EXTRA finding's text before treating it as dropped content — confirmed-justified is a pass.

Pass bar: visual red flags none/justified AND content-diff 0 🔴 and 0 nothing-lost 🟡 (../replica/reference/source-fidelity-gate.md § Pass bar item 1). Re-run BOTH after each fix.

Profiles

skills/diff/scripts/diff-profiles.mjs holds them. A profile supplies the source/target labels, per-flag remediation hints, the font-delta threshold, the default content-root selector, and the eyebrow classifier thresholds. The engines carry no stack strings.

  • eds (default) — Edge Delivery / DA remediation language + the stardust deploy skill's finding numbers.
  • generic — neutral source/build language for any stack.

Add a profile by copying generic in diff-profiles.mjs and editing hints.

Shared engine + the in-loop sibling

The structural probe's classifier + differ live in skills/diff/scripts/content-inventory.mjs (deploy imports its synced copy). They measure with the same instrument as two gates of the stardust deploy skill: section-schema.mjs (the pre-code ENCODE/DECODE contract, deploy #93) and block-roundtrip.mjs (the in-loop per-block gate, deploy #94 — the same inventory diff, run per block at authoring time against a local decorate() harness, no DA needed, exit-code gated). Run the in-loop gate while converting; run THIS skill's two probes as the final post-deploy proof. A defect first found here that the in-loop gate passed = the delivery pipeline reshaped the content in transport — fix the block's flattened-shape fallback, not the authoring.

Workflow use

Call both scripts in a validation phase and gate on the output, as deploy's Validate phase does on a served, decorated build (local harness or branch preview): fix visual-diff's STRETCHED/FLUSH-LEFT/SURFACE-GROUND/GAP/ HEADING FACE flags (unless justified — a font substitution is one HEADING FACE ×N line) and every content-diff 🔴, confirm 🟡/🟠, loop until both are clean.

stardust:direct

Resolve the user's freeform redesign intent into a complete target specification: project-root PRODUCT.md and DESIGN.md (impeccable format), a DESIGN.json sidecar with the divergence audit trail, and a stardust/direction.md with the full reasoning trace.

direct produces the spec against which prototype and migrate operate. It never writes prototypes or migrates pages — those are downstream sub-commands.

Inputs

  • <phrase> — optional positional. The user's freeform intent ("make it better", "more Linear less Salesforce", "feel more premium on a small screen"). If omitted, ask the user for one.
  • --re-direct — optional. Replace the current direction with a new one. Triggers stale-flagging on prototyped / approved / migrated pages per skills/stardust/reference/state-machine.md. Default behaviour without the flag is additive: if a direction already exists, the agent asks before replacing.
  • --rebrand — optional. Force rebrand mode (full divergence-seed roll, no Mode A inheritance). Without it the default is brand-faithful whenever the captured signal is signal-strong (§ Mode-detection precedence).
  • --prep — optional. Run in migrate-prep mode: confirm the type catalog, finalize the module catalog, capture color reservations and brand-level metadata defaults, re-evaluate direction against the wider crawl. See § Prep mode below. Typically invoked via the prepare-migration orchestrator.
  • --add-variant <name> — optional. Add a new variant against the existing direction without re-running intent reasoning or mode detection. Writes DESIGN-<name>.{md,json} at the project root and appends a per-variant section to stardust/direction.md; existing prototypes are not stale-flagged. See § Add-variant mode below.

Setup

  1. Run the master skill's setup (skills/stardust/SKILL.md § Setup) — hard impeccable dep check, context loader, state read.
  2. Verify stardust/state.json exists and contains at least one extracted page. If not, stop and recommend $stardust extract <url> first.
  3. Read stardust/current/_brand-extraction.json. If absent, stop — extract did not complete brand-surface extraction; re-run extract. 3b. Cross-site brand inputs (when present). state.json.designSource (design-donor mode: Mode A pins bind to the donor's derived system) and _brand-extraction.json.origins[] (sibling-property evidence: widens what can be amplified, not what is pinned). Read reference/cross-site-brand-inputs.md for the pin and evidence rules; surface the active mode in the plan.
  4. Read stardust/direction.md if present. If a prior direction exists and --re-direct was not passed, ask whether the user wants to refine the existing direction or replace it.
  5. Validate provenance (prep mode only). When --prep is active, run the provenance validation per reference/prep-mode.md before typing or module detection.
  6. Classify the captured brand signal. Read _brand-extraction.json and stamp one of:
    • signal-strong — palette has ≥ 3 distinct colors (after near-duplicate clustering and excluding pure black/white if they are the only entries) AND at least one captured type family is named in type.headingFamily.name or type.bodyFamily.name. This is the common case for any extracted commercial site.
    • signal-thin — palette has 2 colors OR no captured type family OR type.scaleAudit.kind === "ad-hoc" with fewer than 3 distinct heading sizes. The brand exists but cannot fully anchor a refresh.
    • signal-absent — palette has 1 color or 0, or _brand-extraction.json._provenance.notes flags the extraction as failed / login-walled / iframe-dominated. The classification feeds the Mode-detection precedence in Phase 2. Surface the classification in the plan when it would change the default mode.

Procedure

Phase 1 — Reasoning

Run the full intent-reasoning procedure from skills/stardust/reference/intent-reasoning.md. Steps 1-6: restate the phrase in dimensional vocabulary, identify movement, identify gaps, ask at most two clarifying questions, map to an impeccable command sequence, show the plan to the user.

Worked examples in skills/stardust/reference/intent-examples.md calibrate the style. Hard ceiling on questions: two per turn, no exceptions.

Zero movement is not a direction — hand off to replica. Before restating, check whether the phrase pins every axis unchanged: "exact replica", "same design", "pixel-perfect", "faithful", "keep the current design", "1:1", "re-platform only", "preserve verbatim", or ia-fidelity: verbatim with palette, type and density all pinned. That is a same-design migration and direct has nothing to decide: write a one-paragraph note to stardust/direction.md ("zero-movement phrase — same-design migration; the direction is the mechanical promotion in replica Phase 2"), stamp state.json.flow: "replica" if unset (../stardust/reference/state-machine.md § Flow keys), and stop with "run $stardust replica <url>". Never continue into a redesign direction, a --prep module catalog or a plan on such a phrase — under hands-off included: "ask nothing" below never means "proceed on a replica phrase". (Recorded: direct invoked with "exact replica — preserve verbatim" kept going; 2,207 pages were published at 24–28 % pixel diff, four to five times the replica pass bar.)

Hands-off mode (per skills/stardust/SKILL.md § Hands-off mode, state.json.handsOff: true): ask nothing and wait for nothing — after the zero-movement check above, which hands-off does not skip. Derive every answer the questions would have collected from the captured evidence — density and ia-fidelity from their documented defaults and trigger conditions, audience and register from the captured surface — and record each as a named assumption in direction.md § Movements (e.g. density: balanced (hands-off default — multi-audience floor fired)). The plan is still written; execution proceeds without the confirmation gate. Question budgets and gates below that say "ask the user" resolve the same way: derive, stamp the assumption, proceed.

Density tuning (one-shot, only when unmoved)

When the user's phrase does not move the density axis (per reference/intent-dimensions.md § 4), and the resolved register is brand, ask one short follow-up — count it within the two-question ceiling:

Density tuning — (a) airy (NYT-Opinion-tier breathing, ~96px section padding), (b) balanced (calm but compact, ~64–72px), (c) packed (data-dense, ~40–48px). Default for brand-register sites with multi-audience IA is (b) balanced; pick (a) only when the page is editorial-led with deep per-section density.

If the user answers, stamp the chosen tier in direction.md § Movements as density: <tier>. If unanswered, default to balanced (not airy) for brand register and stamp density: balanced (default).

Skip this question entirely when:

  • The user's phrase already moved density (any of "make it denser", "more breathing room", "compact", "tight", "spacious" count as movement).
  • The register is product (default packed per § 4).
  • The register is ambiguous and resolving it earlier in the reasoning is the higher-value question — defer density to the next turn rather than burning a question slot.

Phase 4 reads the stamped tier to set spacing.sectionPadding; it never re-asks.

IA-fidelity tuning (one-shot, only when unmoved)

When the user's phrase does not auto-pin ia-fidelity (per reference/intent-dimensions.md § 9 — i.e. none of "verbatim", "same IA", "keep the structure", "swap the surface", "don't rethink the IA" and none of "reimagine", "rethink", "deeper redesign", "what if" appear), ask one short follow-up — count it within the two-question ceiling:

IA fidelity — (a) verbatim (same section sequence, same content beats; variants explore surface only: color, type, density, motion), or (b) reimagined (variants may demote / promote / drop sections, move IA priorities, take "what if" positions on the spine of the page). Default (b) for the typical refresh; pick (a) when the customer asked to keep their site structurally identical and only swap the surface.

If the user answers, stamp the chosen tier in direction.md § Movements as ia-fidelity: <tier>. If unanswered, default to reimagined and stamp ia-fidelity: reimagined (default).

Skip this question entirely when:

  • The user's phrase already auto-pinned the axis (any trigger phrase in § 9 — "same IA, swap the surface" → verbatim; "what if we rethought the home page" → reimagined).
  • An existing direction.md is being refined (the active tier holds unless the user explicitly re-pins).

Phase 4 stamps the tier into iaPriorities[].mutability; downstream prototype reads it.

Pair this question with the density-tuning question when both are unmoved — "two things to pin before we resolve: (1) density …, (2) IA fidelity …" — to stay within the two-question ceiling. If resolving register (brand vs product) is also outstanding, prioritise register first; defer one of density / ia-fidelity to the next turn.

Wait for the user's confirmation ("go", or a correction to the plan) before moving on.

Phase 2 — Resolve the divergence inputs

Once the plan is confirmed, resolve the divergence-toolkit inputs from skills/stardust/reference/divergence-toolkit.md. Before rolling the seed, run the mode-detection precedence below to decide whether the seed needs rolling at all.

Mode-detection precedence (run first)

The default mode for direct is determined by whether an extracted brand surface exists with usable signal — not by the user's freeform phrase alone. Ambiguous refresh phrases ("make it modern", "stunning new version", "design fatigue cure") are migration-shaped asks, not rebrand triggers. The precedence is asymmetric on purpose: the safer mode (Mode A — brand-faithful) catches ambiguous phrases; the riskier rebrand mode requires the user to name it.

  1. Site migration / refresh — DEFAULT. When the captured brand signal stamped in § Setup step 6 is signal-strong, Mode A is active by default. The user's phrase moves expressive, distinctiveness, tone, and density axes inside Mode A — but palette and type are pinned to the captured surface, and the image-reuse contract (below) holds. Signature preservation also holds: a captured signature hero medium (background video / canvas / Lottie / scroll-motion, elevated as _brand-extraction.json#voice.heroMedium) or a site-wide motif is reproduced, not flattened — per skills/stardust/reference/ intent-dimensions.md § 8b, and exempt from the surprise budget. Surface in the plan: "Brand-faithful mode active — palette and type pinned to the captured brand surface. Pass --rebrand to override."

  2. Rebrand — explicit opt-in. Mode A is overridden when any of the following triggers fire:

    • The user's phrase contains an explicit rebrand signal: any of rebrand, new brand, clean slate, start over, from scratch, replace the brand, not brand-faithful, editorial reimagination, completely new, redo the brand.
    • The --rebrand flag is passed.
    • Captured signal is signal-absent (no usable inheritance). Surface this case as an automatic switch with reason; the user can correct.

    In rebrand mode, run the standard divergence-seed roll per "Default mode (no constraints)" below. Surface in the plan: "Rebrand mode active — full divergence-seed roll. Mode A bypassed because ."

  3. Brand-faithful + targeted exploration. When the user requests N variants (e.g. "3 variants", "4 directions") and Mode A is active, the variant role contract in reference/multi-variant.md applies (trigger: § Phase 2.6). Variant A is locked to strict Mode A (palette and type pinned, IA preserved, every improvements-list item applied). Variants B+ may amplify one captured trait (a motif, a photo treatment, an IA priority the current site underplays) but cannot:

    • introduce a font outside the captured surface,
    • introduce a color outside the captured palette,
    • shift the register from PRODUCT.md.
  4. Signal-thin fallback. When captured signal is signal-thin, Mode A activates but warns: "Captured brand surface is thin — {reason}. Variants will inherit what is available; some dimensions will need to be filled by the divergence toolkit." The user may either re-run extract with a wider crawl (--cap 25) or proceed with reduced fidelity.

After mode-detection completes, run the existing mode definitions below (Mode A procedure, Mode B anchor-reference precedence, Mode C ground-family override) as applicable.

Mode A — Brand-faithful mode

Triggered automatically when the captured brand signal is signal-strong and no rebrand-mode override fired (see § Mode-detection precedence above), OR when the user pinned both type and palette (via explicit phrase: "keep typography and palette", "preserve the existing brand", "brand-faithful redesign"; or via constraints listing both as anchors).

In this mode, direct does not roll the type or palette dimensions of the seed — they are already locked.

The mode procedure:

  1. Record font_deck.name = "brand-inherited" and font_deck.picked_by = "user-constraint". Do not invoke reference/palette-picker.md.

  2. Record palette.source = "inherited from _brand-extraction.json" and palette.picked_by = "user-constraint". Apply role-renaming per toolkit § 4 if the inherited names violate the brand-native rule (this is still useful — role renaming is presentational, not a divergence choice).

  3. Still roll the seed for the non-locked dimensions (decade, register, ground-family-as-applicable per Mode C below). These dimensions still drive divergence — the visual register and the era can shift even when type and palette are pinned.

  4. Auto-emit the brand_faithful_inversions[] block in extensions.divergence per reference/direction-format.md § Brand-faithful inversions. The list is mostly mechanical (see § Brand-faithful inversions in direction-format.md for the canonical patterns).

  5. Surface in the user report which dimensions had teeth and which were inert:

    Divergence (brand-faithful mode):
      decade           ✓ rolled    → 2025-now
      craft            ✓ rolled    → Riso print
      register         ✓ rolled    → Memoir-adjacent
      ground-family    inherited   → stark-white (brand-native)
      font deck        inherited   → existing site stack
      palette          inherited   → existing 5-color set
    
  6. Image-reuse contract. Captured images are reused via their public URLs (or the local copies in stardust/current/assets/media/ written by extract Phase 2) at the same semantic position as on the source site. Hero stays hero. Story-tile portrait stays story-tile portrait. Program-card image stays program-card image. Background-motif image stays background motif.

    This is part of brand-faithful inheritance: swapping a captured portrait for a placeholder, or demoting the hero photo to a thumbnail, erases the brand's most load-bearing trust signal.

    The only legitimate ways to deviate from semantic position-preservation under Mode A:

    • The captured image is broken (404, blocked by referrer-policy, CORS-walled, or recorded with localPath: null and a downloadError).
    • The brand-review surfaced the image as a tension (e.g. T-stock-photography when added — flagging the captured image as obviously templated stock that the brand team would replace anyway).
    • The improvements list (Phase 2.5) explicitly notes a crop or positioning fix for that image — in which case the same image is reused at the corrected crop or position.

    Synthesised placeholders are forbidden under Mode A. When a captured image cannot be reused, the prototype shape brief declares the gap explicitly and the rendered prototype shows a placeholder-with-signature element so reviewers see the gap rather than a fabricated photo.

The user can correct the mode at the plan-confirmation gate (e.g. "actually let me move the palette" or "actually rebrand it") before it locks.

Mode A+ — Brand-adjacent refinement (bounded, evidence-gated)

The middle tier between Mode A's hard pins and --rebrand: when the improvements list (Phase 2.5) names a captured type or color weakness with evidence, bounded same-classification upgrades are permitted — each audited in extensions.divergence. brand_adjacent_refinements[], never active by default. Read reference/mode-a-plus.md before applying any refinement.

Mode B — Anchor-reference precedence

When the user provides anchor references (Q1/Q2 answers like "Pentagram nonprofits, This American Life, NYT Opinion longform"), those references already imply seed dimensions (Pentagram → decade 2025-now editorial; This American Life → register Memoir-adjacent). Do not roll dimensions the references already imply.

Agent-sourced anchors (default when the user provides none). Mode B no longer waits for the user to name references: run the reference-research procedure (skills/stardust/reference/reference-research.md) to source 3–5 real-world anchors matched to the brand's category, register, and the resolved direction movement. Researched anchors carry the same implied-dimension weight as user-provided ones and are recorded as picked_by: "reasoned: <anchor>" with the full citation in extensions.divergence.references_used[]. User-provided references always outrank researched ones on conflict. When research is unavailable (ladder exhausted per reference-research.md § 1), Mode B degrades to the deterministic roll for the un-implied dimensions.

Precedence rule:

  1. If anchor references are present, extract their implied dimensions:
    • Decade from era of the references (Pentagram → 2025-now; vintage Penguin → 1960s).
    • Craft from medium of the references (TAL → audio editorial ≠ a craft per se, but Bandcamp → web-print hybrid; Riso-print anthology → Riso).
    • Register from cultural reference set (Memoir, Tabloid, Catalogue, etc.).
    • Ground-family from typical ground of those references (NYT Opinion → cream/parchment; Pentagram nonprofit → stark-white or monochrome-tint).
  2. Mark each implied dimension as picked_by = "anchor-reference: <ref-name>".
  3. Roll the seed only for un-implied dimensions.
  4. Record the anchor → dimension mapping in extensions.divergence.seed.anchors[].

Mode B can compose with Mode A: anchor-references narrow the seed, brand-faithful constraints lock type/palette, the remaining roll is whatever the anchors didn't already imply.

Mode C — Brand-faithful ground-family override

When Mode A is active and the seed's ground_family roll disagrees with the brand's existing ground (e.g. seed rolled monochrome-tint but the brand's captured background is #ffffff stark-white), the brand's ground wins. The seed roll is not discarded — it informs the alt-section surface instead (per divergence-toolkit.md § 4 Color roles). Record the override in extensions.divergence.seed.ground_family.override with one of three reasons:

  • brand-faithful — Mode A active and brand has a fixed ground.
  • print-paper — manual override for print/paper categories (existing toolkit rule).
  • direction-driven — seed wins (default; no override).

The three reasons are mutually exclusive; surface the chosen one in the user report.

Default mode (no constraints)

When neither Mode A nor Mode B applies (rebrand or thin-signal runs with no user anchors), the procedure is research-first, roll as fallback:

  • Reference research first. Run skills/stardust/reference/reference-research.md to source anchors for the brand's category and the resolved direction, and derive the dimensions they imply (picked_by: "reasoned: <basis>"). This is Mode B's machinery applied to agent-sourced anchors — see § Mode B above.
  • Seed as fallback + tiebreaker. Roll the 4-dimension seed (decade × craft × register × ground-family) per § 2 of the toolkit only for dimensions research left un-implied, or entirely when research is unavailable. The roll also remains available as a deliberate convergence-breaker when the self-audit catches the model reproducing its defaults despite research. Record picked_by per dimension.
  • Font deck. Pick from the 10 named decks per § 3, letting the researched anchors inform the pick the same way a seed implication would (e.g. an editorial-serif anchor set → serif-luxury). When neither research nor seed implies a deck, pick deterministically from the hash.
  • Palette. If the resolved direction moves the color-energy axis or names the existing palette as part of the problem: derive a full role-ramped palette (text, grounds, borders, accents, states) from the primary researched anchor or a library candidate — the library (skills/direct/reference/palette-picker.md) is an anchor bank, not a closed menu; the model designs the ramp and validates every text-on-ground pair for WCAG AA before it lands in tokens (deterministic where it matters — math — not where it hurts — taste). Record the derivation basis in extensions.divergence.palette_source. Otherwise inherit the existing palette from stardust/current/_brand-extraction.json, applying role-renaming per toolkit § 4 if the inherited names violate the brand-native rule.
Always run
  • Anti-toolbox audit. Regardless of mode, run the self-audit (toolkit § 1 Enforcement + Self-audit) on the resolved direction. Each anti-toolbox hit needs a brand-specific justification or it is removed.

Record every resolution in DESIGN.json.extensions.divergence per the v2 storage shape at the bottom of divergence-toolkit.md.

Phase 2.5 — Improvements list (Mode A only)

Before any variant is rendered downstream, write stardust/prototypes/<slug>-improvements.md listing 3–5 specific weaknesses observed in the captured site. It is the brief variant A renders against: not prescriptive (no visual targets), but descriptive of the gap between the existing site and a competent 2026 execution of the same brand. Variants B+ honor the list as a floor (they may go further but not contradict it).

Skip this phase when the resolved mode is rebrand — the improvements list assumes brand-faithful inheritance, and a rebrand replaces the site rather than fixing it.

Audit reuse. When stardust/audit/<domain-slug>/audit.json exists for this origin (written by the stardust audit skill), consume its design findings as candidate improvements instead of re-deriving from scratch — carry the finding IDs into each item's evidence citation. The specificity bar below still applies to every carried item.

What goes in the list

The list draws from five categories. Items should be specific enough that a downstream prototype shape brief can cite them by number.

  1. Dated patterns the design world has moved past — name the pattern and its era, not a feeling.
  2. Cluttered IA — unclear hierarchy, weak or redundant CTAs, fragmented conversion funnels.
  3. Contrast failures, accessibility gaps, density issues — pull from brand-review.html Tensions when present (T-color-imbalance, T-img-alt-empty, etc.).
  4. Cliché conventions the brand could move past while staying recognisably itself.
  5. Missed opportunities the existing site doesn't capitalise on.

Worked examples per category: reference/improvements-list.md.

Specificity bar

A weakness is specific enough when it cites:

  • a measurable observation (size, ratio, contrast value, count, or named tension ID) drawn from the per-page JSON, the brand-review, or the brand-extraction;
  • the design pattern at fault (named, e.g. "centered hero + dual CTA");
  • one concrete fix the variant A brief will apply.

"The hero needs work" fails all three. "Hero photo is cropped to 280×180 in a 1440-wide viewport when the captured source supports 16:9 full-bleed at 1440×810; variant A fix: render at full-bleed and move the headline to a left-anchored two-column overlay" passes all three.

Format

Markdown, with a _provenance frontmatter block per the artifact-map convention. Each item is a numbered list entry with a category tag, a weakness statement, and a one-line fix. Full worked example in reference/improvements-list.md § Format example.

Stopping condition

If after reading the brand-review, the per-page JSON, and the brand-extraction the agent cannot name 3 specific weaknesses that meet the specificity bar, stop. Variant A has no brief; the "better" claim fails. See § Failure modes (d).

The agent should not rationalise — "the hero is dated" is not an item, "the typography could be more modern" is not an item. Genuine empty-list cases occur when the captured site is already at a high execution level on observable dimensions. In that case the honest answer is to surface the empty list and propose reduced scope (density-and-contrast adjustments only, or pivot to a single exploratory variant rather than three).

Phase 2.6 — Multi-variant fork (when N > 1)

When the user requests N variants (phrase contains "3 variants", "4 directions", or equivalent), variant slots are role-differentiated, not seed-differentiated. Branch on the ia-fidelity tier stamped in Phase 1: surface-tuning forks A1/A2/A3 under verbatim; role-differentiated A + B + C (faithful

  • improvements / one captured trait amplified / a different captured trait amplified) under reimagined. Read reference/multi-variant.md and follow its variant role contract, differentiation contract (each variant pair differs by ≥ 2 substantive changes), surface-fork rules, and render-refusal conditions before resolving any variant.

Phase 3 — Author target PRODUCT.md

Write PRODUCT.md at the project root using impeccable's reference/init.md § Write PRODUCT.md as the format spec (not as a runtime command to invoke; init, formerly teach, runs an interview). Direct authoring is intentional: by the time direct runs, every answer impeccable's interview would surface has already been resolved through stardust's intent-reasoning + divergence resolution above.

File order: stardust's <!-- stardust:provenance … --> block first (per ../stardust/reference/artifact-map.md § Provenance, as for every stardust-written artifact), then # Product, then the <!-- impeccable:product-schema 1 --> comment verbatim so impeccable reads the file as a current product record rather than a legacy one. Omit a section rather than filling it with generic prose. Sections to populate:

  • Platform — the bare value web.
  • Users — from the resolved audience tuple plus tone signals from the extracted brand surface.
  • Product Purpose — from the user's phrase + extracted hero copy
    • resolved tone, written as a one-line value statement followed by one-line scope.
  • Positioning — the claim the site makes that a neighbour could not truthfully copy, from the extracted hero and proof copy. Mark inferred when the copy does not state it.
  • Capabilities and Constraints — the resolved constraint set (a11y-first, RTL-required, platform or content constraints) and any product fact the user pinned.
  • Brand Commitments — the binding identity decisions: the resolved register axis, the brand personality derived from the resolved expressive axis + tone + reference set (weight axes the user explicitly moved over inherited values), and the anti-references — the user's stated anti-refs plus any anti-toolbox guardrails relevant to the resolved direction (e.g. "modernise" triggers the Generic-2026-SaaS silhouette guardrail; list it explicitly so prototype and polish enforce it).
  • Evidence on Hand — the captured copy, imagery and proof under stardust/current/ with paths, and the absences future work must not fabricate (no testimonials captured, no pricing, …).
  • Product Principles — 3-5 durable strategic principles, each mapping to a specific axis movement. Format: one verb-led principle, one-line elaboration. No visual recipes; those belong in DESIGN.md.
  • Accessibility & Inclusion — populated when the constraint set includes a11y-first, RTL-required, or similar. Otherwise omit and inherit impeccable's defaults.

Where a section cannot be populated with confidence from inputs, mark it <!-- _provenance: inferred --> with a one-line basis sentence. Never invent strategy.

Phase 4 — Author target DESIGN.md and DESIGN.json (site-level only)

Write DESIGN.md at the project root using impeccable's reference/document.md as the format spec — Stitch YAML frontmatter plus the 6 canonical sections in fixed order.

Site-level only. direct authors the design system, not page-level deployments. Page-specific composition decisions live in stardust/prototypes/<slug>-shape.md written by prototype Phase 1 — see skills/prototype/reference/page-shape-brief.md.

The boundary is abstract role vs literal deployment:

In DESIGN.md / DESIGN.json (site system)In <slug>-shape.md (page deployment)
Token vocabulary (colors, typography, spacing, radii)Per-page section list and order
Voice rules ("Mixed-Case-Headlines"), anti-refsLiteral copy per section (sourced from current/pages/.json)
Anti-toolbox audit, divergence tracePage-specific layout decisions ("hero is 5/3 split on home")
Abstract component vocabulary: button-primary, button-secondary, card, input, badge, link (default treatment, density, sizing — NO page-specific dimensions or content)Section-level component dimensions (the211Panel at 320×260 with dock points per viewport)
Named system-component roles (a header exists, a footer exists, a cta-band pattern exists)System-component deployment (literal tile labels in fixed order, link targets, copy variants)
Default visual treatment for each abstract componentPer-page composition (statRow with literal "100 YEARS · 18,400 PEOPLE HOUSED · …")
Voice samples (do/don't, tone exemplars)Per-page interaction model and key states

Concrete examples of items that must not appear in DESIGN.md / DESIGN.json:

  • Literal tile labels for any system-component pattern.
  • Section-level pixel dimensions, dock points, breakpoint-specific widths.
  • Stat numbers, addresses, quotes, named-person references.
  • "On home, the hero is X" — that's a home-page deployment.
  • Per-page copy variants ("on the donate page the CTA reads Y").

If a redesign demands a section-level dimension or a literal label that feels site-wide ("every page has a 211 panel docked at the bottom-right"), encode it as an abstract role in DESIGN.json (e.g. extensions.systemComponentRoles.persistent-help with purpose / position-class but no literal copy or dimensions) and let each page's shape brief specify the deployment.

Token sources:

  • colors — from the picked palette (palette-picker.md output) or the inherited palette with role-renaming. Role names must satisfy toolkit § 4 (brand-native, no Primary / Secondary / Alarm etc. as sole role names).

  • typography — from the chosen font deck. Sizes scaled by the resolved expressive axis (drenched → ratio ≥ 1.333; committed → ratio 1.25; restrained → ratio 1.125-1.2). Heading vs body assignments inherit from the deck.

  • rounded — derived from extracted brand-surface borderRadius.primary mode, unless the direction moves distinctiveness toward singular (in which case re-derive from the font deck's tonal cousins).

  • spacing — 4pt base scale; sectionPadding propagated from the density tier stamped in Phase 1 (reference/intent-dimensions.md § 4):

    • airy → sectionPadding.desktop: 96px, tablet: 72px, mobile: 48px
    • balanced → sectionPadding.desktop: 64px, tablet: 48px, mobile: 32px ← brand-register default
    • packed → sectionPadding.desktop: 48px, tablet: 36px, mobile: 24px ← product-register default

    The agent does not re-ask the density question here — the tier was resolved in Phase 1 (asked once when the phrase didn't move the axis, defaulted to balanced for brand register if unanswered). Pick the value deterministically from the stamp.

    Hard floor enforcement. When the captured page inventory shows

    5 sections OR >2 audience tracks (per reference/intent-dimensions.md § 4 → "Hard floor for brand-register multi-audience sites"), the resolved sectionPadding.desktop is bounded at ≤ 64px and ≥ 40px on every variant including the highest-divergence one. If Phase 1 stamped airy despite the trigger conditions firing, surface the conflict before writing tokens — "density tier airy was selected but the captured inventory triggers the multi-audience hard floor; pick (a) override floor (density: airy (user-pinned) in direction.md) or (b) accept the floor (sectionPadding capped at 64px)." Default to (b) when the user does not respond.

  • components — 4-6 canonical components (button-primary, button-secondary, card, input, badge, link) populated from extracted brand-surface componentStyle, with values adjusted for direction movements.

Write DESIGN.json (schemaVersion 2) with:

  • extensions.colorMeta, typographyMeta, shadows, motion, breakpoints — filled from the same sources as DESIGN.md. The motion block carries the register selection (when cinematic motion may be applied at prototype time):

    "motion": {
      "register": "arrival | kinetic-display | live-systems | editorial | kinetic-grid",
      "registerRationale": "<one-line citation back to PRODUCT.md Brand Personality trait that selected this register>",
      "easings":   { "entrance": "...", "transition": "...", "expo": "..." },
      "durations": { "enter": <ms>, "stagger": <ms> },
      "parallax":  { "translate": <vh>, "fade": <0-1>, "rangeStart": <%>, "range": <%> }
    }
    

    Picked per the register selection heuristic in skills/prototype/reference/motion-registers.md § Selection heuristic, reading the resolved PRODUCT.md § Brand Personality:

    Personality traits (any match)Register
    civic-formal + (institutional OR place-led)arrival
    signage-led OR wayfinding-first OR display-typography-signaturekinetic-display
    operationally-transparent OR data-led OR dashboard-registerlive-systems
    editorial OR slow-paced OR publication-registereditorial
    product OR SaaS OR transactional OR modular-cataloguekinetic-grid
    (ambiguous / no clear match)arrival

    Token defaults per register are sourced from skills/prototype/reference/motion-registers.md § The five registers; direct copies them verbatim into the motion block unless the user has provided overrides during intent reasoning. The registerRationale field records the one-line justification so reviewers can audit the choice. direct does not apply the motion — that happens at prototype time under --cinematic. direct only selects the register. Pages whose redesign does not need motion can leave register absent; cinematic prototype will then either ask or pick from the heuristic at render time.

    Per-variant placement (when N > 1 variants). The motion block goes into the variant-specific DESIGN-<id>.json files, not site-level DESIGN.json — variants without a register render static. See reference/multi-variant.md § Per-variant motion placement.

    When the user's intent phrase contains explicit motion direction ("make it cinematic", "feel alive", "move like signage"), direct picks the register and notes the source in registerRationale as "user-phrase: <verbatim>".

  • extensions.divergence — full audit trail per the v2 storage shape in divergence-toolkit.md. Includes the brand-faithful inversion log (per reference/direction-format.md § Divergence inputs) capturing pure-color or hex-format retentions.

  • extensions.componentStyle — the abstract v1 fields (buttons, cards, inputs, dualCTAPattern). Default treatment per component, no per-page dimensions or literal copy.

  • extensions.systemComponentRoles — the abstract roles for named cross-page patterns (e.g. persistent-help, cta-band, header, footer). Each role carries purpose, position class, and any site-wide constraint — not literal copy, dimensions, or per-viewport dock points (those are page-deployment, in <slug>-shape.md).

  • extensions.voice — sampled DOs and DON'Ts derived from _brand-extraction.json voice samples + the resolved tone.

  • narrative.northStar, overview, keyCharacteristics, rules, dos, donts — derived from the resolved direction. Toolkit § 7 Optional House Standards land here in narrative.rules[].

Every component HTML/CSS snippet in components[] must be self-contained, use ds- class prefixes, and respect impeccable's hard rules (OKLCH only, no pure black/white, no glassmorphism, no side stripes, no gradient text, ≥ 1.25 type ratio for brand register).

IA-priority preservation audit (Mode A)

After tokens are drafted but before they land in the variant DESIGN files, run the IA-priority preservation audit per reference/intent-dimensions.md § 8. For each captured signal that fires a trigger condition (commercial conversion, search-led IA, donation funnel, crisis affordance, audience routing), record an extensions.iaPriorities[] entry in DESIGN.json:

[
  {
    "signal": "crisis-affordance",
    "evidence": "pages/home.json#landmarks[hero] contains heading 'Looking for immediate shelter?' + phone 801-990-9999",
    "preserveAs": "first-viewport",
    "scope": "site-wide",
    "mutability": "movable"
  }
]

Each entry is a constraint that downstream prototype and migrate must honor — a variant whose home shape brief omits the crisis affordance from the first viewport fails the audit and is rejected. The audit is the structural enforcement of § 8; without it, IA- priority preservation is a guideline rather than a contract.

The mutability field reflects the ia-fidelity stamp from Phase 1 (per reference/intent-dimensions.md § 9): locked under verbatim (variants may not move the priority at all — A1/A2/A3 are surface forks), movable under reimagined (variants may demote / promote / re-shape the priority's deployment, but the § 8 floor still fires). The field is stamped once at Phase 4 and is the source of truth prototype reads.

Multi-variant DESIGN files (when N > 1)

When Phase 2.6 is active, Phase 4 writes PRODUCT.md (shared) plus per-variant DESIGN-{A,B,C,…}.{md,json} instead of a single pair; every variant inherits the shared extensions.iaPriorities[] audit. Under rebrand mode PRODUCT.md may also vary per variant. See reference/multi-variant.md § Multi-variant DESIGN files.

Phase 5 — Write direction.md and update state

Write stardust/direction.md per skills/direct/reference/direction-format.md. The full reasoning trace: phrase, restatement, movements, gaps, questions and answers, resolved axes, divergence inputs, command sequence proposed, user confirmation, every assumption that defaulted in. Re-directs append to the file as a new section; prior direction stays as history.

Update stardust/state.json:

  • direction.resolvedAt = now
  • direction.phrase = the user's verbatim phrase
  • direction.directionFile = "stardust/direction.md"
  • For each page in scope: status extracted → directed
  • On --re-direct, for each page already in prototyped / approved / migrated: set stale: true and staleReason: "direction changed at <ts>". Do not change the status itself; the on-disk artifact is still valid, just out of step.

Print a one-screen summary report and recommend the next step:

direction resolved
==================

Phrase:    "make it more expressive for a young audience"
Audience:  Gen Z college / first-job (resolved via Q1)
Register:  brand (inherited from current/PRODUCT.md)

Movements:
  expressive axis    restrained -> committed
  distinctiveness    familiar  -> distinctive
  tone               serious   -> playful
  density            (unchanged)
  audience           (resolved: Gen Z college / first-job)

Divergence:
  seed         1970s x Riso print x zine x monochrome-tint
  font deck    zine-maximalist
  palette      "Brutalist Dawn" (picked from library)

Wrote:
  PRODUCT.md, DESIGN.md, DESIGN.json
  stardust/direction.md

State:
  25 pages: extracted -> directed
  0 stale prototypes (none exist yet)

Next: $stardust prototype  (defaults to home page)

Outputs

PathPurpose
PRODUCT.mdTarget strategy (impeccable format). Shared across variants when N > 1 under Mode A.
DESIGN.mdTarget visual system (Stitch frontmatter + 6 sections). Single-variant runs only.
DESIGN.jsonSidecar with extensions (divergence, componentStyle, voice, iaPriorities) and narrative. Single-variant runs only.
DESIGN-{A,B,C,…}.mdPer-variant DESIGN files when the user requested N > 1 variants (Phase 2.6 active).
DESIGN-{A,B,C,…}.jsonPer-variant DESIGN sidecars matching the .md files.
stardust/prototypes/<slug>-improvements.mdImprovements list (Mode A only, written in Phase 2.5). The load-bearing artifact for variant A.
stardust/direction.mdResolved direction + full reasoning trace + per-variant resolutions when N > 1.
stardust/state.jsonUpdated with direction + per-page status changes + direction.variantMode + direction.variants[] when N > 1.

Failure modes

  • No extracted state. Abort and recommend $stardust extract.
  • Phrase too vague even after two questions. Persist the partial reasoning to stardust/direction.md under a # Pending section, ask the user to refine further, do not write PRODUCT.md / DESIGN.md / DESIGN.json from incomplete reasoning.
  • Re-direct with prior approved or migrated pages. Always confirm before stale-flagging. The flag is visible to the user and reversible (clearing happens automatically on successful re-run of prototype or migrate), but a re-direct invalidates work the user may have signed off on.
  • Anti-toolbox audit removes too many moves. If the resolved direction collapses to defaults after the audit strips unjustifiable hits, surface this to the user and re-prompt for reference anchors before writing tokens.
  • (b) Insufficient brand signal for N variants. Fewer than 3 distinct amplifiable traits in the captured surface (or signal-thin) → refuse N ≥ 3 under Mode A and propose 1–2 variants instead; full contract in reference/multi-variant.md § Failure mode.
  • (c) Hard rule conflict. When Mode A is active and the user's phrase requires violating a Mode A pin (e.g., the user asks for "a completely different palette" while migration mode is active and --rebrand was not passed), stop. Name the conflict explicitly: "You asked to keep the brand and to change the palette — those are not compatible. Did you mean (a) keep the current palette and only refresh execution, (b) rebrand (--rebrand) and roll a new palette, or (c) Mode A with a targeted palette move (single role recolored, rest pinned)?" Wait for explicit answer.
  • (d) Empty improvements list. When Phase 2.5 produces fewer than 3 weaknesses meeting the specificity bar, stop before rendering any variant. Variant A's brief depends on the list; without it, the "better" claim fails. Surface honestly: "the captured site is already at a competent execution level on observable dimensions — variant A would reduce to spacing and contrast adjustments only." Ask the user whether to (a) proceed with reduced scope (density + contrast only), (b) extract additional pages (extract --cap 25 or higher) to surface more weaknesses, or (c) pivot to rebrand mode (--rebrand) where the brand-fidelity floor doesn't apply.

Prep mode (--prep)

When invoked with --prep, direct runs an extended pass that finalizes the inventory data structures migrate consumes: type catalog confirmation, module catalog finalization, color reservations, a wider direction re-evaluation, and site-level metadata defaults. Read reference/prep-mode.md and follow it on top of the standard procedure. Discovery-mode runs are unchanged.

Add-variant mode (--add-variant)

When the user has already approved (or rendered) variant A and asks for B / C / etc. as alternatives, --re-direct is too heavy — the user is extending the existing direction, not changing it. --add-variant <name> skips Phases 1–2 (mode, seed, palette, and ground family are inherited from the active direction), resolves the new variant's role per the variant role contract, and writes DESIGN-<name>.{md,json} plus a ## Variant <name> section in direction.md, without stale-flagging any page. Read reference/add-variant.md and follow its procedure, parentage and per-field inheritance rules, and failure modes before writing anything.

References

  • skills/stardust/reference/intent-dimensions.md — the 8 axes (the 7 axes plus § 8 IA-priority preservation, the Mode A constraint that fires on captured commercial-conversion / crisis / audience-routing signals).
  • skills/stardust/reference/intent-reasoning.md — the procedure.
  • skills/stardust/reference/intent-examples.md — worked examples.
  • skills/stardust/reference/impeccable-command-map.md — when to reach for each impeccable command (used when building the plan).
  • skills/stardust/reference/reference-research.md — the research-first anchor procedure (refero MCP → WebSearch → seed fallback) consumed by Mode B and Default mode; evidence shape and budgets.
  • skills/stardust/reference/divergence-toolkit.md — anti-mediocrity inputs and the v2 storage shape for the audit trail. Contains the anti-toolbox additions for multi-variant moves (C-cliff overshoot, Anonymous middle variant, Variant homogeneity) and universal hardening (Fabricated content, Hero text on photographic background without contrast scrim, Editorial-register vocabulary applied to non-editorial brands).
  • skills/stardust/reference/artifact-map.md — provenance shape.
  • reference/direction-format.md — schema for stardust/direction.md.
  • reference/palette-picker.md — palette resolution procedure.
  • reference/prep-mode.md — the --prep extended pass (provenance validation, type/module catalogs, color reservations, metadata).
  • reference/add-variant.md — the --add-variant flow (procedure, variant parentage, per-field inheritance, failure modes).
  • reference/multi-variant.md — the N > 1 fork: variant role contract, differentiation contract, surface forks, C-cliff.
  • reference/improvements-list.md — worked examples for the Phase 2.5 improvements list (categories + format).
  • reference/mode-a-plus.md — bounded brand-adjacent refinements.
  • reference/cross-site-brand-inputs.md — design-donor and sibling-origin evidence rules.

stardust:dynamics — the dynamic surface of a migration

Static migration treats a page as content and layout. This skill treats it as behaviour: everything the source renders from JavaScript, a service or a data source, and everything the target host cannot serve the same way. Three real migrations found the same thing: the dynamic surface is invisible to a block-scoped, pixel-verified pipeline — and invisible in a way every gate certifies as correct. Modals rendered as links, video pills as CTAs without targets, a search box as a 404, forms that rendered and could not submit. This skill makes that surface visible and forces a decision per row before import, then proves the behaviour after delivery. It never blocks the static path; every page must still work as a static page.

When it runs — migration-bound, default-on there, never elsewhere

entry pointwhat runs here
prepare-migration Phase 4.5 · replica Phase 2Phases 1–3 (detect on archetypes, classify, triage) — the pre-import gate
migrate Phase 1safety net: no inventory → run Phases 1–3 now (hand-run extract → direct → prototype → migrate never passed a gate)
deployreads the inventory as brief input (fallback rows, #modal markers, endpoint config; never flatten client-only / modal-bearing sections)
rollout B2 · D2B2 verifies the inventory against fresh evidence; D2 = Phase 4 for the self set + one owner batch
qa dynamics check · rollout reportPhase 5 replay of parity.json
standalone $stardust dynamics <origin>all phases on a site that was already migrated without them

uplift, audit and a bare extract never trigger it: dynamics is a migration concern (EDS today, other platforms later), not a redesign one.

Phase 1 — Detect

node skills/dynamics/scripts/dynamics-detect.mjs --from-state stardust/state.json --out stardust/current [--reach stardust/current] (or --urls one per archetype + the home page). Depth on archetypes, reach from the crawl's extract --dynamics per-page signals. Output stardust/current/_dynamics.json + dynamic-features.generated.md. Evidence only. reference/classes-and-signals.md. For every search form found, run one probe term on the SOURCE and record what it shows — the visible result count, the top titles (≤ 3), one known hit — as expectCount / expectTitles / expectIncludes on the feature's search-query check (Phase 5; a spec's knowledge/search-probes.json already holds them); without them the rebuilt search can only be checked for presence.

Phase 2 — Classify

Every finding gets a class from L S F M V T A R X I18N CR D; known vendors resolve to a role through scripts/vendors.json; unknown third-party hosts stay visible as "inspect". When a target host exists, dynamics-plan.mjs --target-origin <host> probes every recorded first-party API path there and marks dead ones host-bound — the signal a pixel gate reports as "band shorter".

Phase 3 — Triage (the gate output)

node skills/dynamics/scripts/dynamics-plan.mjs [--target-origin …] [--migrated stardust/migrated] [--knowledge] [--chrome] --out stardust/dynamics drafts one row per finding with the four axes pre-filled — class · disposition · reproducibility · status — plus pattern, phase, the owner decision and target, the delivery form (widget where no authored rows remain — reference/triage.md § Target); --knowledge adds a spec's curated features, decisions from its open questions; --chrome a row per header-contract family (cart and account decide their backend, the UI ships). Curate it into stardust/dynamic-features.md (§ Listings contract + § Features + § Decision batch + § Register) and stardust/dynamic-features-plan.md. reference/triage.md is the contract. Rules that decide the shape of the phase:

  • Reconcile against the migrated output before scheduling anything.
  • Only reproducibility self ships autonomously; everything else is one decision batch.
  • Never fabricate copy for a blank client-rendered capture; never auto-wire a regulated-pii form; a search box implies a results page; decided-out is explicit and owner-stated — a hands-off assumption never writes it.
  • Gate: a row without a disposition fails prepare-migration 4.5 / replica Phase 2 / rollout B2. The static migration continues regardless.
  • Martech only on request: when the owner asks to keep tags or consent, add --martech (reference/martech.md); everything is scaffolded off.

Phase 4 — Implement (per plan phase)

From reference/patterns.md (catalogue + contracts + embedded example mechanisms), reference/listings.md, reference/off-origin-data.md, reference/forms.md, reference/locale-trees.md. Principles that held on three sites: static first, then wire · authoring contract before code · no owner input, no waiting (ship the interim tier, name the decision) · existing library first (feed it, do not fork it) · decided-out is explicit. Each phase ends with the flow verified on the published origin at 1440 and 360, a parity row, a journal entry and a commit. Tooling: snapshot-api.mjs, snapshot-forms.mjs, sync-sheets.mjs. A flow script you write follows the recipe in ../stardust/SKILL.md § Setup, step 7. The query index comes from helix-query.yaml in the code branch — commit, push, publish live, poll — never from a configuration-service write; the sheet-backed interim index only when the branch is not writable (reference/listings.md § Getting an index at all). Search follows reference/patterns.md § search-index-backed. Listings and data-fed bands are document-first: the document carries the item text as authored rows, the block reads the index or snapshot only for non-text fields and top-up (reference/listings.md § Block contract; why: deploy/reference/ai-readability.md).

Phase 5 — Verify: dynamic parity

Write stardust/dynamics/parity.json (reference/parity-report.md) with replayable checks from the closed set; node skills/dynamics/scripts/dynamics-check.mjs --origin <published origin> [--auth-header … | --token-env SITE_TOKEN] writes stardust/qa/dynamics-report.md. Flows, not presence. A search-query check compares the result COUNT and the top titles with the source's recorded values — a count mismatch fails. The site secret rides an origin-scoped route filter only; third-party request statuses are recorded next to every assertion.

Hands-off resolutions

gateresolution
owner decision (backend, tags on the new host, datasource ownership, locale scope)ship the interim tier, record the decision by name in the plan and parity report, continue — never as decided-out, which takes an owner's statement or a hard blocker
unknown third-party hostclassify from the XHR body; else T "inspect" — never drop silently
blank client-rendered capturehard content gap → human-capture batch; never migrate blank
regulated-pii formUI rebuilt, submission blocked, mandatory decision
hand-off target unreachable from the test networkenvironment-limit row with the egress region; not a defect
content source cannot receive submissionslocal capture with an explicit "no backend connected" message; decision named

Hard blockers (event: "blocked")

Source unreachable from the probe network; target config not writable when endpoint indirection is required; an interim tier that would capture regulated data (record as decided-out instead).

Artifacts

stardust/current/_dynamics.json, dynamic-features.generated.md · stardust/dynamics/dynamic-features.generated-plan.{md,json} · stardust/dynamic-features.md, stardust/dynamic-features-plan.md (curated) · helix-query.yaml (listings + search, committed in the code branch) · data/<feature>/*.json + _provenance.json (snapshots, code bus) · scripts/site-config.js (owner-facing integrations, disabled) · stardust/martech-contract.json, martech-handoff.md, scripts/martech.js (opt-in) · stardust/dynamics/parity.json · stardust/qa/dynamics-report.{md,json} · register rows · journal + status lines.

References

  • reference/classes-and-signals.md — the class axis, detector procedure, vendor table policy, origin-bound probe.
  • reference/triage.md — the four axes, rules, the inventory file format.
  • reference/patterns.md — catalogue: contracts + verification per pattern, example mechanisms.
  • reference/listings.md — metadata contract + query-index mechanics (formerly rollout's dynamic-listings).
  • reference/off-origin-data.md — feeding an existing library off-origin; sheet-backed data; chrome URL space.
  • reference/forms.md — controls not form tags; intake by content source; regulated data.
  • reference/parity-report.md — schema, check types, rules.
  • reference/locale-trees.md — I18N as a tree.
  • reference/martech.md — opt-in martech contract, owner enablement, runtime, verification.
  • scripts/ — dynamics-detect.mjs, dynamics-plan.mjs, dynamics-check.mjs, snapshot-api.mjs, snapshot-forms.mjs, sync-sheets.mjs, vendors.json, lib.mjs, martech.mjs.

stardust:extract

Crawl an existing website, parse each page, extract the brand surface, and produce a stardust-formatted snapshot of the current state under stardust/current/. The output describes what the site is; later sub-commands consume it to decide what it should be.

This skill is descriptive: it does not invent direction, it does not critique, and it does not modify the live site. It writes only under stardust/current/ and updates stardust/state.json.

Inputs

  • <url> — required. The origin to crawl. Examples: https://example.com, https://example.com/shop. A path narrows the same-origin crawl to that subtree.
  • --cap <N> — optional. Override the default 5-page cap. The cap is intentionally small — a 5-page sample (home + four IA pillars/templates) is enough for cross-page brand aggregation, system-component detection, and the brand-review HTML; lift it (e.g. --cap 25) when a deeper crawl is genuinely needed.
  • --all — optional. Lift the cap entirely; extract every discovered page after junk filtering. Equivalent to --cap 0. Use when the user spontaneously asks for a full crawl.
  • --pages <slug,slug,...> — optional. Restrict the crawl to specific paths (slugs derived per reference/ia-extraction.md). Bypasses the cap.
  • --refresh <slug> — optional. Re-extract one page that already exists in state.json.
  • --single — optional. Equivalent to --cap 1. Useful for testing.
  • --wait <fast|medium|spec|auto> — optional. Wait strategy per page. Default medium. See reference/playwright-recipe.md § Wait modes.
  • --no-junk-filter — optional. Disable the default junk-page filter in discovery (see reference/ia-extraction.md § Filtering).
  • --no-consent-dismiss — optional. Skip the pre-flight consent / cookie banner dismissal (see reference/playwright-recipe.md § Pre-flight: consent dismissal). Use when the redesign scope includes the consent surface or the dismissal's side-effects (script activation that wouldn't otherwise run) must be avoided. Default is to dismiss, keeping screenshots, voice aggregation, and per-section style unpolluted by the banner.
  • --dynamics — optional, migration-bound. Record per-page reach signals of the dynamic surface (data endpoints, forms, modal triggers, player ids) in each page JSON dynamic section and roll them up in _crawl-log.json#dynamicSurface. Set by prepare-migration, replica and migrate's safety net; never by a bare extract, uplift or audit — dynamics is a migration concern. Depth and classification belong to the stardust dynamics skill.
  • --concurrency <n> — optional. Parallel browser contexts for the per-page capture loop. Default 4; sane range 4–8. See § Concurrency.
  • --brand-source <url> — optional, repeatable. An additional same-brand origin whose brand surface enriches the primary extraction (shallow capture: home + up to 2 nav-linked pages). See § Cross-site brand sources.
  • --design-source <url> — optional. Design-donor origin: its design system is captured to stardust/canon-source/ and becomes the fixed redesign target while the primary origin supplies content. See § Cross-site brand sources.
  • --prep — optional. Run in migrate-prep mode: lift the cap, type each page, detect module candidates, capture typed content slots, emit the prep summary. See § Prep mode below. Typically invoked via the prepare-migration orchestrator skill rather than directly.

Setup

Run the master skill's setup procedure first (skills/stardust/SKILL.md § Setup): impeccable dep check, context loader, state read.

Additional checks for this sub-command:

  1. Playwright availability. The extraction step needs a real browser. Detect Playwright in this order: a Playwright MCP server, then a project-importable playwright module. The npx playwright probe is NOT sufficient — it confirms the CLI (which resolves a global install) but the recipe and scripts/crawl.mjs load playwright through browser.mjs, and ESM module resolution does not honour a global install or NODE_PATH — the import throws ERR_MODULE_NOT_FOUND even where npx playwright --version succeeds. Verify the module is import-resolvable from the project root (probe: node -e "import('playwright').then(()=>process.exit(0))"); if it isn't, run npm i -D playwright pixelmatch pngjs cheerio --legacy-peer-deps (devDependencies, never --no-save — #125) or use the Playwright MCP server, before crawling. The --legacy-peer-deps flag is required on aem-boilerplate targets (their pinned eslint@8 makes a plain npm i exit ERESOLVE before playwright is even considered). Don't trust the CLI probe alone.

    --no-save installs are ephemeral. Any later real npm i (e.g. a setup step adding a devDependency) prunes non-manifest packages, silently removing playwright mid-pipeline. Every downstream skill that renders (prototype, migrate, deploy, diff) must re-run the import-resolvability probe — and re-install on failure — at the start of its own run, not assume extract's install survived.

    Script location matters. ESM resolves import 'playwright' from the script's directory and the plugin tree ships no node_modules: copy every script byte-identical into the project (stardust/scripts/…), the master skill's too (../stardust/SKILL.md § Setup, step 7), and run the copy.

    Bundled crawler. skills/extract/scripts/crawl.mjs is a runnable reference implementation of this whole sub-command — browser config + bot-management fallback, consent dismissal, wait

    • scroll, the capture list, per-page full-page screenshots (assets/screenshots/<slug>.png, consumed by the Phase 2.5 vision gate), response validation, and the § Capture-hygiene hardening (visibility filter, interstitial drop, SPA-shell flag, modal textContent capture, tracking-pixel discounting, cross-page duplicate detection). Prefer invoking it over hand-rolling a Playwright script per run; extend its in-page capture() to cover any recipe field it doesn't yet emit.
  2. Origin collision. If stardust/state.json already records site.originUrl and the new <url> is a different origin, stop and ask before clobbering. Stardust does not silently mix two sites in one project. Flow guard (migration asks only). If the ask carries migration intent ("migrate", "to EDS", "re-platform", "1:1", "replica") and stardust/state.json exists — or is about to be created — without flow, hand back to the master skill § Two migration flows before crawling: the flow is chosen and stamped there, and a keep-design ask enters through replica (which invokes this skill with --prep itself). A bare extract <url> for a redesign, audit or uplift is unaffected. (Recorded: extract on a raw URL as the entry of a same-design migration; the agent then built its own importer beside replica.)

  3. Browser contexts. Open a fresh BrowserContext per capture worker (§ Concurrency; default 4). Run the consent dismissal pre-flight per reference/playwright-recipe.md § Pre-flight: consent dismissal unless --no-consent-dismiss is set. Cookies persist within a context but not across contexts — re-establish consent state per context (re-run the dismissal on the worker's first page, or clone the probe context's storageState). Record the resolved method in _crawl-log.json#consent.method.

  4. Bot-management probe. When the first navigation in the run returns ERR_HTTP2_PROTOCOL_ERROR or ERR_QUIC_PROTOCOL_ERROR, or hangs through the entire hard-cap on what should be a fast origin, do not retry headless — switch to headed Chrome per § Failure modes → Bot-management block and record the switch in _crawl-log.json#discovery.fetchTechnique so re-runs start in headed mode without rediscovering the issue.

Procedure

Phase 1 — Discovery

Discover the page inventory before crawling. Procedure in reference/ia-extraction.md. In summary:

  1. Fetch <origin>/sitemap.xml, then <origin>/sitemap_index.xml, then check robots.txt for Sitemap: directives.

  2. If no sitemap is reachable, run a same-origin BFS crawl from <url>, depth-limited to 3, link-extracting from rendered HTML.

  3. Filter the discovered URL list: same origin only, exclude mailto:, tel:, anchor-only links, query-only variations, common asset paths (.css, .js, .pdf, image extensions).

  4. De-duplicate trailing-slash variations.

  5. Apply the junk-page filter (reference/ia-extraction.md § Junk-page filter) unless --no-junk-filter is set. Surface the filtered list to the user as overridable.

  6. Apply the cap (default 5, or --cap, or --all for no cap) and proceed silently. Print an informational summary of what was kept and what was cut — but do not gate on user confirmation. Users who want different scope set it spontaneously at command time:

    $stardust extract https://example.com              # default 5 pages
    $stardust extract https://example.com --cap 25     # bump to 25
    $stardust extract https://example.com --all        # lift the cap
    $stardust extract https://example.com --pages home,about,pricing
    $stardust extract https://example.com --single     # just the entry URL
    

    The agent reads spontaneous scope intent from the user's prompt (e.g. "extract all pages", "look at just the home and pricing", "do a full crawl") and applies the equivalent flag. No re-confirmation needed once intent is clear.

    Informational output (not a prompt — proceed immediately):

    Discovered 38 pages on https://example.com (sitemap.xml).
    Filtered as likely junk (5): /test/, /sample-page/, /holiday1/, ...
    Selecting 5 highest-priority pages:
      - / (home)
      - /about
      - /pricing
      - /products
      - /contact
    
    Cut (28 pages, --all to lift): /blog/post-1, /blog/post-2, ...
    
    Extracting...
    

    Selection heuristic: when the user names N, link-first order (the entered page, then its links). Otherwise page-type checklist first, then score-based ranking. See reference/ia-extraction.md § Page selection and § Priority for the cap.

  7. Write the discovered list to stardust/current/_crawl-log.json (created if absent) with _provenance and the full discovery reasoning, including filteredAsJunk[] and userChoice. This is an audit trail, not a state file.

Phase 2 — Per-page extraction

For each page in the cap-respecting list, render with Playwright following reference/playwright-recipe.md. Captures run concurrently per § Concurrency. The recipe is mandatory per page — in particular, do not skip the wait, scroll, or capture-list steps:

  • Viewport 1440 × 900 @ 2× DPR
  • Wait per the configured wait mode (default medium; see § Wait modes in reference/playwright-recipe.md)
  • Disable animations via prefers-reduced-motion: reduce
  • After the wait resolves, scroll to bottom in 4 viewport-height steps with 300 ms pauses, then return to top — this is required to trigger lazy-load and IntersectionObserver-driven content
  • Record waitMs and waitMode in the per-page _provenance

Capture per page (full schema in reference/current-state-schema.md):

  • Page metadata (title, meta description, OG tags, theme-color)

  • Semantic structure: heading outline, landmark roles, sections

  • Hero headline + lede (resolved) — heroHeadline / heroLede picked by font-size × hero-region with a junk/hidden-state filter and a clean meta-description fallback (per reference/playwright-recipe.md § Capture list 5-bis). Required for JS-rendered sites whose document-order headings surface modal / promo / count junk instead of the real tagline.

  • Content: visible text per section (full innerText, no truncation per reference/playwright-recipe.md § Capture list 7), structured paragraphs (body[]), lists, FAQ Q/A pairs, and review/testimonial quotes per § Capture list 7-bis. Without these structured fields, every body region under a heading falls back to placeholder signature at migrate time.

  • CTA labels and href targets, link inventory (internal vs external)

  • Per-section computed style summary: dominant colors, font families in use, spacing rhythm, border-radius, shadows

  • Media inventory: img with currentSrc/srcset captured with query strings intact plus a resolves flag (HEAD/GET with browser UA + Referer), intrinsic dimensions, inline SVG count, video/iframe presence, cssBackgrounds[] (including pseudo-element ::before/ ::after walks per § Capture list 11) so background-image heroes and motifs do not silently disappear and 404ing CDN images are flagged before migrate ships about:error.

  • Font files captured via network-intercept (per § Capture list 16): every woff2/woff/ttf/otf response saved under assets/fonts/ and recorded in _brand-extraction.json#type.files[] with licensing flag.

  • Icon-font detection (per § Capture list 17): when the page uses [class^="icon-"] with non-default ::before font-family + codepoint, capture the family, save the file, and record the iconClass → codepoint table in _brand-extraction.json#iconFont.

  • Interactive elements: forms (with field types), buttons, modals detected by ARIA roles

  • Full-page screenshot to assets/screenshots/<slug>.png — script-captured by the bundled crawler after the wait/scroll settle (viewport-only fallback on extremely tall pages; mode in _signals.screenshotMode, relative path in the page JSON screenshot field)

  • Dynamic surface (only with --dynamics) — per-page reach signals: endpoints, third-party script hosts, forms, modal triggers, player ids, hydration hints, in the page JSON dynamic section and _crawl-log.json#dynamicSurface (schema in reference/current-state-schema.md § Dynamic). Evidence only; the stardust dynamics sub-skill probes archetypes in depth and decides.

Save to stardust/current/pages/<slug>.json with _provenance as the first key. The bundled crawler also saves the settled rendered DOM verbatim as stardust/current/pages/<slug>.html (page.content() after the wait/scroll settle; path in the record's renderedHtml field). Capture once, parse offline: every downstream importer or sibling generator iterates its extraction against this artifact — free, reproducible, and provenance — instead of re-running live probes per selector guess (recorded: 4+ live round-trips per page family before the switch). Live probes stay for what the static DOM cannot answer: geometry and computed styles. Save referenced media to stardust/current/assets/media/ preserving basename plus a short content hash.

Live-render evidence (synthesis is forbidden). Refuse to mark a page extracted in state.json unless its _provenance contains renderedBy: "playwright", an ISO-8601 fetchedAt, a positive integer waitMs, a waitMode from the recipe, and a final httpStatus in the 2xx/3xx range. These five fields are the contract enforced by reference/current-state-schema.md § Live-render evidence and read back by every downstream phase via validateProvenance() per skills/stardust/reference/state-machine.md § Provenance validation. Synthesizing a page record from _brand-extraction.json plus URL patterns plus captured photos — the 2026-04-30 e-commerce shortcut — is the failure mode this guard exists to prevent. When the agent (or a delegated sub- agent) cannot satisfy the contract for a page, treat the page as a Phase 2 failure: record under _crawl-log.json#crawl.failures[] with errorClass: "ProvenanceMissing" and continue.

Mark the page extracted in state.json immediately after each successful page write. If a page fails, record the error in _crawl-log.json and continue — extraction is best-effort per page.

Phase 2.5 — Vision verification

Before anything downstream is authored, look at each captured page's screenshot (assets/screenshots/<slug>.png) — the multimodal model reads the image — and verify it against the extracted record:

  • Does the recorded hero (headline + asset) match what the pixels show?
  • Is the extracted palette plausible against the pixels?
  • Does a cssBackgrounds: [] record look believable, or is imagery visibly present — a silent capture failure?
  • Is the logo captured?
  • Is the page actually rendered — not a consent wall, bot-block page, or blank SPA shell?

Read the whole page through its thumbnail — node stardust/scripts/thumb.mjs stardust/current/assets/screenshots/<slug>.png --width 480 (skills/extract/scripts/thumb.mjs, copied beside crawl.mjs; a box-filter downscale, so 1-px rules and hairline borders survive; its --max-bytes cap, 150 KB by default, re-encodes a heavy page narrower first and crops only as a last resort, never below 60 % of the page) — never the full-resolution screenshot, and read any detail as a crop of the full capture. The check is of the WHOLE page: read the script's stdout line before the image, and when it prints a share below 100 (cropped at <n>px of <H> = <share>%) run the same command with --offset <n> and read <slug>-thumb-<n>.png too, repeating while its rows <n>-<end>px line ends short of <H>. A recorded hands-off run's thumbnails kept a median 28 % of each page and the check read them as the page. A thumbnail enters the context only after thumb.mjs has written it (≤ 150 KB, or the floor thumbnail it named on stderr, exit 1) — or the vision check runs in a subagent that reads the thumbnails and returns one line per page (<slug>: ok | recaptured | suspect — <note>); a recorded hands-off run read eight *-thumb.png files of 268–608 KB each into one context — 3.2 MB of pixels for eight verdicts.

On mismatch, re-run that page's capture with the escalation ladder before proceeding: bump the wait mode one step (reference/playwright-recipe.md § Wait modes), then headed Chrome (§ Bot-management fallback), then a fresh browser context. Record the outcome per page in _crawl-log.json#visionCheck[]:

{ "slug": "pricing", "verdict": "recaptured", "notes": "record said zero CSS backgrounds; screenshot shows a full-bleed photo hero" }

verdict is "ok" | "recaptured" | "suspect" — suspect means the mismatch survived the ladder; downstream phases treat that record as unreliable. Vision is the authoritative capture check; the heuristic defenses (low-media flag, spaShellSuspect, duplicate hash) remain as cheap early signals but no longer gate alone.

Phase 3 — Brand-surface extraction

Run after the capture phases (2–2.5). Aggregation may proceed incrementally as concurrent page captures complete (§ Concurrency), but the written file must reflect every extracted page — including brand-source pages per § Cross-site brand sources. Produces stardust/current/_brand-extraction.json per reference/brand-surface.md. Some fields are home-only (logo, voice samples, register heuristic); the visual tokens that drive DESIGN.md (palette, radius, shadow, type) are aggregated across all extracted pages to avoid the home-page bias documented in brand-surface.md § Aggregation scope.

Computed-style census — run the shipped instrument; author no probe. node <plugin>/skills/extract/scripts/style-census.mjs (copied into the project like crawl.mjs, § Setup) measures every captured page at 1440 and writes stardust/current/_computed-styles.json; add --width 360 when the breakpoints include it. One more live pass over every page — run it ONCE, after the crawl, in the background; it opens the live side through the shared browser.mjs like every other live instrument. Read the palette, type, motif and hover values from the file's aggregate and cite each from its sources[] (url, selector, prop); the per-page detail sits under pages[url][width].

Content-cap model — run the shipped probe; author no lift (#124). node stardust/scripts/replica/cap-probe.mjs <archetype-url>… --write-design stardust/current/DESIGN.json (replica's script; it needs the master skill's scripts copied too) renders each archetype at 1440 and at a DERIVED wide width — max(2560, largest cap × 1.25); a probe AT a cap's width cannot see it — and records every box that stops growing (kind shell / content / module, px, authored via, tier) into extensions.breakpoints: containerMaxWidth (the --max-width source; null when fluid), probeWidth, caps[], modules[]. One navigation per archetype after the census (never beside it), once DESIGN.json is authored (it merges). A cap on the shell or on every archetype is design intent whatever its value; capRegister lists single-module or archetype-divergent caps for the inconsistency register. The cap model never records layout breakpoints: a redesign target keeps its own two; replica keeps the source's, or maps them to --target-breakpoints. Captures:

  • Logo by the v1 priority chain: inline SVG → <img> with logo-ish class/id → apple-touch-icon → og:image → favicon → synthesized placeholder. Save to stardust/current/assets/logo.<ext>.
  • Favicon — ALWAYS captured as its own asset (independent of the logo chain) to stardust/current/assets/favicon.<ext>, per reference/playwright-recipe.md § Favicon capture. Downstream, prototype embeds it in the proposed page head and deploy ships it to the Edge Delivery site.
  • Palette — aggregate computed colors across all extracted pages (background, text, accents, borders, hovers). Frequency-sort, cluster near-duplicates, emit a role-named list (background, surface, text, primary, secondary, accent).
  • Type — font families in use with their weights, sizes, and computed line-heights. Identify the heading family vs body family. Run the modular-scale audit (brand-surface.md § Modular-scale audit) and emit scaleAudit.kind = "modular" | "ad-hoc".
  • Motifs — signature border-radius (cross-page mode of non-zero values, weighted by element count), shadow stack (top 3 distinct, cross-page), gradient inventory, common patterns (chip, badge, card, hero-with-image). When the home-only mode disagrees with the cross-page mode, surface the divergence in _provenance.notes.
  • Voice samples — first paragraph of body copy, the hero headline, 3 representative CTA labels, a representative link list. Used by direct later but extracted now so the network round-trip is over.
  • Hero image — elevate the home page's primary visual asset to voice.heroImage (per reference/brand-surface.md § heroImage resolution), so downstream prototype picks the live hero rather than the og:image from the raw media list.
  • Hero medium (signature) — when the hero/first viewport carries a moving asset (background <video> / HLS / canvas / WebGL / Lottie / animated SVG / scroll-driven motion), elevate it to voice.heroMedium (per reference/brand-surface.md § heroMedium resolution). This is the page's signature; without elevation downstream prototype flattens it to a static hero. A non-null heroMedium triggers signature preservation (skills/stardust/reference/intent-dimensions.md § 8b) at prototype time.
  • Icon font — when detected per reference/playwright-recipe.md § Capture list 17, populate _brand-extraction.json#iconFont with family, file path, and the iconClass → codepoint table so prototypes can render the brand's actual icons.
  • System components — cross-page repeated DOM blocks (site header, site footer, cross-promo strips, persistent CTAs, breadcrumbs). Detected by heading-sequence + CTA-label fingerprint per reference/brand-surface.md § System components. Required — these are usually the most load-bearing surfaces and must not silently disappear from the redesign target.
  • Origins — one entry per contributing origin in _brand-extraction.json#origins[] per reference/brand-surface.md § Origins. Single-origin runs emit a one-entry array; brand-source runs attribute widened evidence per origin.

Do not invent values. Every captured value cites a source selector or URL in _brand-extraction.json for traceability.

Phase 4 — Seed stardust/current/PRODUCT.md and DESIGN.md

The current-state PRODUCT.md and DESIGN.md are descriptive, not authored — there is no interview to run because the user is not defining intent here, the agent is describing the existing site. Write them directly using impeccable's format specs (impeccable's skill directory is what node <plugin>/skills/stardust/scripts/impeccable-version-check.mjs --where prints; read each spec by section, not whole):

  • For PRODUCT.md, follow the section structure in impeccable's reference/init.md § Write PRODUCT.md. File order: stardust's <!-- stardust:provenance … --> block first (per ../stardust/reference/artifact-map.md § Provenance, as for every file this skill writes), then # Product, then the <!-- impeccable:product-schema 1 --> comment verbatim, then Platform (web), Users, Product Purpose, Positioning, Capabilities and Constraints, Brand Commitments, Evidence on Hand, Product Principles, Accessibility & Inclusion; omit a section rather than pad it. Under Brand Commitments record the register guess from the brand surface (sites that read as marketing/landing → brand; tools/dashboards → product; ambiguous → brand with a note), the observed brand personality and the observed anti-references. Evidence on Hand lists what was captured under stardust/current/ with paths. Populate Users, Product Purpose, Positioning and Product Principles from the captured copy and the brand surface. Where the agent must infer, mark the section with _provenance: inferred and a one-line basis sentence.
  • For DESIGN.md and DESIGN.json, follow the format spec in impeccable's reference/document.md. Populate frontmatter (colors, typography, rounded, spacing, components) from the captured tokens. The extensions block of DESIGN.json carries v1's componentStyle, motifs, and voice arrays so nothing is lost, and breakpoints — the cap-probe sizing model — verbatim.

Stardust does not invoke $impeccable init (formerly teach) or $impeccable document for the current-state files: those commands write to project root (the target) and run an interview. Stardust authors the descriptive snapshot directly. The format spec from impeccable is the contract; the runtime command is not.

The target-state PRODUCT.md and DESIGN.md at the project root are written by $stardust direct in Phase 2 of the pipeline, not here.

Phase 5 — Render stardust/current/brand-review.html

After Phase 4 writes the descriptive PRODUCT.md and DESIGN.md, emit the current-state brand review per reference/brand-review-template.md.

The brand-review HTML is the first surface a human can eyeball to verify the extraction before committing to a redesign direction — misreads that are invisible in JSON (a wrong dominant radius, a missing system component, a single-page palette bias) are obvious to the eye while they are still cheap to fix (re-extract is fast; re-direct + re-prototype is not).

The template is mandatory. In particular:

  1. Run the Tensions detectors listed in reference/brand-review-template.md § Detectors. Each rule is mechanical; emit a tension card whenever the trigger condition matches. The review may ship with zero tensions if the data is too thin to evaluate, but the detectors must always be run.
  2. Render in the brand's own captured colors and fonts, not a stardust shell.
  3. Embed all CSS; do not load external JavaScript or fonts unless the live site already does.
  4. Cite the source artifact for every section (e.g. _brand-extraction.json § type under Typography).

If the data for a section is missing, omit the section — do not fabricate placeholders. The coverage callout at the top reflects what is missing.

Phase 6 — Update state and report

After all Phase 2-5 writes succeed:

  1. Update stardust/state.json (schema in skills/stardust/reference/state-machine.md):

    • site.originUrl, site.extractedAt, site.pageCap, site.totalDiscovered, site.crawled
    • pages[] — one entry per crawled page with status: "extracted", filled currentStatePath, empty prototypePath and migratedPath
    • designSource — only when --design-source was used: { url, capturedAt, path } per § Cross-site brand sources
  2. Print a one-screen summary:

    Extracted https://example.com (5/38 pages, sitemap.xml)
    
    stardust/current/
      PRODUCT.md, DESIGN.md, DESIGN.json, brand-review.html,
      pages/ (5), assets/logo.svg, _brand-extraction.json, _crawl-log.json
    
    Per-page evidence:
      slug         live  waitMode               waitMs   status  media(img/bg)
      /            yes   medium                 2380     200     38/6
      /pricing     yes   medium                 1940     200     9/0   ⚠ low-media
      /contact     yes   domcontentloaded(fb)   8000     200     3/0
      ...
    
    Wait summary: 4 resolved at medium (avg 2.4s), 1 fallback (timed out at 8s)
      → /contact may be under-captured; consider --refresh
    Media summary: 1 page flagged low-media (/pricing) — see media-coverage check
    Vision check: 4 ok, 1 recaptured (/pricing) — _crawl-log.json#visionCheck
    
    Open stardust/current/brand-review.html to verify the extraction
    before running $stardust direct.
    
    Coverage note: extracted 5 of 38 discovered pages; 5 pages
    covering distinct templates is usually sufficient for the
    cross-page brand surface. Widen with --cap <N> or --pages.
    
    Next: $stardust direct  (resolve a redesign direction)
    

    The per-page evidence table is mandatory. The live column is yes when _provenance.renderedBy === "playwright" AND waitMs > 0, else no. A no row means the page record was not produced by a live Playwright render — the visible column is the defense-in-depth signal for the failure mode the write-time guard exists to prevent (2026-04-30 e-commerce run). A maintainer scanning the summary should see yes on every row.

    Compute the wait summary by grouping each page's _provenance.waitMode and averaging waitMs. List slugs whose waitMode ends in (fallback) (rendered as (fb) in the table for width) as candidates for --refresh.

    The media(img/bg) column is the analogous defense-in-depth signal for imagery. It prints <count of media.imgs> / <count of media.cssBackgrounds>. Flag a row ⚠ low-media when the page reads as brand/marketing (register brand, or a landing/solution/ product template) yet has cssBackgrounds: [] and few large rasters (no media.imgs entry with intrinsic width ≥ 600). That combination is the signature of a silently-failed background / lazy-media walk — a capture pass that specs the full background walk (playwright-recipe.md § Capture list 11) yet silently produces nothing still ships an image-less capture (2026-06-26 a SaaS site: cssBackgrounds: [] on every page, all product imagery lost). A flagged row is the cue to re-run that page with --refresh (and, if it persists, to fall back to headed Chrome per § Bot-management fallback). A maintainer scanning the summary should treat a brand-register site with all-zero bg counts as suspect, not as "this site uses no background images."

Cross-site brand sources

Two flags widen extraction beyond the primary origin — read reference/cross-site-sources.md in full whenever either flag is present. Both are opt-in; without them this section is inert.

Core contract (merge rules and capture shapes in the reference):

  • --brand-source <url> (repeatable) — a same-brand sibling gets a shallow capture (home + ≤2 nav-linked pages, full recipe + provenance) under stardust/current/brand-sources/<host>/. Evidence, not inventory: never enters state.json.pages[]. Its palette/type/motif/voice evidence aggregates into _brand-extraction.json with per-origin attribution (origins[]); conflicts resolve toward the primary; widened traits are attributed, never invented. Excluded from system components, voiceTable, and cross-promo detection.
  • --design-source <url> — a design donor is captured to stardust/canon-source/ (same shapes as current/, default cap), its descriptive DESIGN.md/json derived per Phase 4 rules, and state.json.designSource = { url, capturedAt, path: "stardust/canon-source/" } stamped. direct pins the donor system as the target (its § Mode A); donor evidence never aggregates into the primary _brand-extraction.json.

Sibling-site discovery

After the primary crawl (Phases 2–2.5), harvest candidate same-brand origins from evidence already captured — no extra navigation:

  • footer / nav links out to other properties
  • "our brands" / "our companies" pages
  • hreflang alternates on other domains
  • subdomain families (shop., careers., country subdomains)
  • og:site_name matches across captured pages

List candidates with confidence + the evidence line in the crawl report and in _crawl-log.json#siblingCandidates[]:

{ "origin": "https://example.co.uk", "confidence": "high", "evidence": "hreflang alternate on 4/5 pages", "decision": "included" }
  • Interactive: propose — "found 3 candidate sibling properties — include as --brand-source?" — and proceed on the answer.
  • Hands-off (state.json.handsOff is true): auto-include up to 2 high-confidence candidates as brand-sources; record the decision in siblingCandidates[].decision.

Discovery is capped and cheap: harvesting reads captured evidence only, and each included sibling gets the shallow brand-source capture (≤ 3 pages). It must never balloon the crawl.

Outputs

PathPurpose
stardust/current/PRODUCT.mdDescriptive strategy of the existing site (impeccable format)
stardust/current/DESIGN.mdDescriptive visual system (Stitch format)
stardust/current/DESIGN.jsonSidecar with extensions for motifs, voice, components
stardust/current/brand-review.htmlSelf-contained visual review of the extraction (first eyeball-able artifact)
stardust/current/pages/<slug>.jsonPer-page parsed structure + content
stardust/current/pages/<slug>.htmlSettled rendered DOM (crawler sidecar; parse offline, never re-scrape)
stardust/current/assets/logo.<ext>Extracted logo
stardust/current/assets/favicon.<ext>Site favicon (first-class asset; prototype head + deploy consume it)
stardust/current/assets/media/Extracted media referenced by pages
stardust/current/assets/screenshots/Per-page full-page screenshots, script-captured by crawl.mjs (Phase 2.5 vision gate + brand-review)
stardust/current/_brand-extraction.jsonConsolidated brand surface (palette, type, motifs, voice, system components)
stardust/current/_crawl-log.jsonDiscovery + crawl audit trail (incl. visionCheck[], siblingCandidates[]; dynamicSurface reach roll-up only with --dynamics)
stardust/current/brand-sources/<host>/Shallow same-brand captures (only with --brand-source)
stardust/canon-source/Design-donor capture + descriptive DESIGN.md/json (only with --design-source)
stardust/state.jsonUpdated with site + per-page status (+ designSource stamp)

Concurrency

Page captures run concurrently: the Phase 2 queue is drained by 4–8 parallel browser contexts (--concurrency, default 4). Each worker owns its BrowserContext; consent state is re-established per context (Setup step 3). Media resolves / HEAD checks are batched with Promise.all. Brand-surface aggregation (Phase 3) may proceed incrementally as pages complete, so long as the written _brand-extraction.json reflects every extracted page. The bundled crawler implements the pool (crawl.mjs --concurrency <n>).

Across processes, per state-machine.md: stardust does not lock. Two concurrent extracts on the same project are last-write-wins. Document this in the user report; do not engineer around it.

Failure modes

  • Network failure mid-crawl. Continue, record in _crawl-log.json, end with a partial state. State.json reflects only successfully extracted pages. User can re-run; already-extracted pages are skipped unless --refresh <slug>.
  • HTTP 4xx/5xx, non-HTML content, soft-404s. Validated explicitly per reference/playwright-recipe.md § Response validation. Each produces a distinct error class (HTTPError, ContentTypeError, EmptyPageError) recorded in _crawl-log.json#crawl.failures[]. Failed pages do not appear in state.json as extracted — they appear only in the failure log. Without this validation a 5xx page silently lands as an empty success and propagates wrong data to direct and prototype.
  • Login wall. Do not attempt to authenticate. If the home page redirects to a login screen, capture that one page, mark the rest as unreachable, and ask the user how to proceed (provide cookies via Playwright config, change the entry URL, or scope to public pages).
  • Bot-management block (Akamai / Cloudflare / F5 / Imperva / CloudFront). When the first navigation returns ERR_HTTP2_PROTOCOL_ERROR, ERR_QUIC_PROTOCOL_ERROR, or hangs through the hard-cap on a TLS/H2 fingerprint check, the issue is JA3/H2 fingerprinting on bundled-chromium-default headless mode — not auth, not network. crawl.mjs runs the fallback itself, window-free: real Chrome headless (channel: 'chrome', its own identity, no launch flags) first, bundled Chromium only when Chrome is missing, one real-Chrome relaunch with the challenge-solve window on an entry-page block, and a wall — an edge 403 or a 200 verification interstitial — is named within seconds in _crawl-log.json (discovery.botBlock, per-page BotChallenge failures), never captured as content (node crawl.mjs --help; a hand-rolled recipe follows reference/playwright-recipe.md § Bot-management fallback). Note for asset harvest: a page-level bot wall usually does NOT gate assets — media/CSS/font URLs commonly return 200 to a plain browser-UA curl even while every page navigation is challenged (Cloudflare challenge, field-confirmed). Probe one asset with curl BEFORE reaching for in-page-fetch machinery; the in-page harvest is the fallback, not the default.
  • JavaScript-only content. Playwright already handles this. If the configured wait condition never fires within the mode's hard cap (reference/playwright-recipe.md § Wait modes), fall back to domcontentloaded and capture what is rendered. Record the fallback in the per-page _provenance.waitMode and surface in the wait-summary line of the final report.
  • Synthesis attempt (forbidden). When the agent (or a delegated sub-agent) cannot run a real Playwright render for a page — whether due to time pressure, token budget, or a tool/network failure — the only correct outcome is to record the page as a Phase 2 failure (errorClass: "ProvenanceMissing" in _crawl-log.json#crawl.failures[]) and continue. Synthesizing a page record from _brand-extraction.json plus URL patterns plus captured photos at "semantically matching" template positions is forbidden. The shortcut produces output indistinguishable from a successful run and propagates fabricated content through every downstream phase (2026-04-30 e-commerce run: 20 of 25 pages synthesized, caught four phases later).

Prep mode (--prep)

When invoked with --prep, extract runs an extended pass that prepares the inventory for migration — read reference/prep-mode.md in full before running any --prep extraction. Discovery-mode runs (without --prep) are unchanged: small cap, no typing, no module detection. The flag is intended for the prepare-migration orchestrator, though direct invocation is supported.

Core contract (procedure, formats, and detection rules in the reference):

  • --prep implies --all unless the user named N (then --cap N, reference/prep-mode.md § 1) — migration coverage requires the full junk-filtered inventory, not the discovery cap.
  • Page types (landing | article | listing | program | form | static | unique) are LLM-inferred into state.json.pages[].type (discovery-mode runs leave type null); the user confirms in direct --prep.
  • Module candidates (cross-page structural repeats, detected by the signal-source priority in the reference) are drafted under DESIGN.json.extensions.modules[] with status: "candidate"; per-page JSON gains a typed slots section per page-type.
  • Locale-root capture gaps are settled before Phase 2 of any flow. After the crawl, crawl.mjs takes every captured locale root (a one- or two-segment path of locale codes — /en, /fr-ca, /ca/en), lists the same-origin targets linked from that page under its own path, and marks the ones missing from the capture: _crawl-log.json#captureGaps (roots[] with root, slug, linked, uncaptured[], plus detail, a ready ledger string) and one [crawl] capture gaps: stderr line. Copy roots[] to state.json.site.captureGaps (the site block is extract's; an uncaptured target never becomes a pages[] row) and carry detail verbatim in the ledger end line that closes the extraction — ledger.mjs extract prep end --detail "… uncaptured first-level targets: ca/en 15, fr/fr 0" (replica's extract end repeats it) — so the owner decides on the gap now (widen with --pages, or record it as scope debt), not in the rollout link audit: two recorded hands-off runs captured /ca/en as a locale root while 15 /ca/en/* pages existed on the source, and found out six hours later, when 15 links answered 404 and the gap exceeded the 12-page deliver threshold.
  • The header contract is recorded here (../diff/SKILL.md § The header contract); its summary line in the prep summary sizes the header.
  • The prep summary replaces the Phase 6 report; its Provenance: <live>/<total> live line is mandatory, and any ratio short of <total>/<total> means the run failed the synthesis guard and is incomplete.
  • When delegating extraction to a sub-agent, the sub-agent prompt must forbid synthesis by name and require the per-page evidence table and wait-summary line in its return (reference/prep-mode.md § Sub-agent prompt requirements); missing any of the three is a recipe violation.

References

  • reference/playwright-recipe.md — viewport, capture list, logo locator chain.
  • reference/ia-extraction.md — sitemap + BFS crawl + cap procedure.
  • reference/current-state-schema.md — per-page JSON schema.
  • reference/brand-surface.md — consolidated brand-surface schema.
  • reference/brand-review-template.md — current-state brand-review HTML contract + Tensions detectors.
  • reference/prep-mode.md — full --prep procedure (typing, module candidates, typed slots, prep summary, sub-agent requirements).
  • reference/cross-site-sources.md — full --brand-source / --design-source procedure (shallow capture, merge rules, canon-source donor).
  • skills/stardust/reference/state-machine.md — state.json contract.
  • skills/stardust/reference/artifact-map.md — provenance shape.

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.

The procedure below is an outline. The text of each phase is in skills/migrate/reference/, in the file the phase names. Read that file in full when you reach the phase; never work from a heading alone.

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

  1. 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.

  2. Run the master skill's setup (skills/stardust/SKILL.md § Setup). Flow guard. If stardust/state.json exists without flow and the ask is a migration (a URL plus "migrate" / "to EDS" / "re-platform"), do not run: print the two-flow table from the master skill § Two migration flows and hand back to its routing — the flow is chosen and stamped there before any sub-skill runs (skills/stardust/reference/state-machine.md § Flow keys): replica unless the ask names a redesign. (Recorded: migrate <url> as the first command of two same-design migrations led to a hand-built compiler tuned by eye instead of the replica gate.)

  3. Verify stardust/state.json exists with at least one directed page.

  4. Verify project-root DESIGN.md and DESIGN.json exist with DESIGN.json.extensions.canon populated.

  5. 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.

  6. Verify stardust/direction.md has an active (not pending) direction.

  7. 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.
  8. 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.

  9. 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 (viewport meta, mobile-first queries, the 360px render checks).

    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

Read skills/migrate/reference/phase-1-plan.md in full before you act on this section.

Phase 2 — Per-page render

Read skills/migrate/reference/phase-2-per-page-render.md in full before you act on this section.

Phase 3 — Sitewide assets and bundle finalisation

Read skills/migrate/reference/phase-3-sitewide-assets.md in full before you act on this section.

Phase 4 — State and report

Read skills/migrate/reference/phase-4-state-and-report.md in full before you act on this section.

Outputs

PathPurpose
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 sidecarLives 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.htmlThe home page (special case).
stardust/migrated/_meta.jsonHome 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> + variantsFavicon and apple-touch-icon, manifest icons.
stardust/migrated/assets/fonts/...Downloaded font files (from canon @font-face URLs).
stardust/migrated/robots.txtMinimal robots.txt.
stardust/migrated/sitemap.xmlSitemap derived from migrated inventory + page types.
stardust/state.jsonUpdated with migrated status, history, and the migrate block (selfContained: true, asset counts).

The driver (node stardust/scripts/migrate/migrate.mjs render …) writes the per-page rows above (index.html / <name>.html, _meta.json, bundled assets/**) and the migrate block of state.json (pageMap[], bundledAssets[], pages[], missingAssets[], lastRun); status changes, robots.txt and sitemap.xml stay with Phases 3–4.

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 (Phase 2 placeholder gate); surface the unsourced list and recommend sourcing real content (re-prototype, or edit the proposed file directly).
  • 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.

stardust:prepare-migration

Orchestrate the migrate-prep cascade. When the user commits to migrating an existing site, this skill runs the upstream phases (extract, direct, prototype) in their --prep modes, sequenced with confirmation gates so the user can confirm or refine the inferred catalog at each step.

prepare-migration is a thin orchestrator — it does not duplicate logic from the underlying skills; it invokes them and brokers the per-phase summaries. The substantive work lives in:

  • skills/extract/SKILL.md § Prep mode
  • skills/direct/SKILL.md § Prep mode
  • skills/prototype/SKILL.md § Prep mode + reference/canon-extraction.md

When prep is complete, the user runs $stardust migrate separately. The two-step boundary (prepare-migration then migrate) is intentional: it makes "I'm committing to migrate this site" a conscious gesture and keeps idempotency obvious.

Inputs

  • --from <phase> — optional. Resume the cascade from a specific phase. Values: extract | direct | prototype | assets | dynamics. Default starts from the earliest incomplete phase.
  • --skip-confirm — optional. Skip the per-phase confirmation gates. Useful for re-runs where the catalog is already settled. Default is to gate at every phase boundary. Hands-off mode (skills/stardust/SKILL.md § Hands-off mode, i.e. state.json.handsOff: true) implies --skip-confirm.
  • --canon-from <slug> — optional. Forward to prototype --prep --canon-from <slug> when that phase runs. Override the default canon-author (which is home).
  • --refine-module <module-id> — optional. Re-enter Phase 2's module-catalog step for one module — the target of migrate's "bespoke slot crossing promotion threshold" hint. Promotes the recurring bespoke slot into that module's slot schema (DESIGN.json.extensions.modules[]), surfaces the change for confirmation, then stops; it does not re-run the full cascade. Affected pages are stale-flagged content-aware per skills/stardust/reference/state-machine.md.

Setup

  1. Run the master skill's setup (skills/stardust/SKILL.md § Setup) — impeccable dep check, context loader, state read. Flow guard. This is the redesign flow's orchestrator. If state.json.flow is replica, refuse: print "never run prepare-migration before or after replica" and the switch command ($stardust prepare-migration --switch-flow, which marks the replica artefacts stale — master skill § Two migration flows). If flow is absent, resolve it first: only an explicit redesign phrase ("redesign", "modernise", "refresh", "new look") selects this skill — stamp flow: "redesign" (skills/stardust/reference/state-machine.md § Flow keys). Any other migration ask, keep-design phrase or plain "migrate", means this skill does not apply — say so and hand to replica.

  2. Verify stardust/state.json exists with at least one extracted page. If not, recommend $stardust extract <url> and stop.

  3. Verify stardust/direction.md exists with an active direction. If not, recommend $stardust direct and stop.

  4. Determine which phases are already complete by inspecting project state:

    • extract: every page has a non-null type in state.json and current/pages/<slug>.json carries a slots block.
    • direct: DESIGN.json.extensions.modules[] entries all have status: confirmed; colorReservations and metadata blocks present.
    • prototype: every page-type has at least one approved archetype; stardust/canon/ populated; DESIGN.json.extensions.canon populated.
    • assets: favicon variants in stardust/migrated/assets/; fonts downloaded.
    • dynamics: stardust/dynamic-features.md present with every row carrying a disposition; helix-query.yaml present when any listing is index-backed (Phase 4.5 records "none" otherwise).

    Resume from the earliest incomplete phase unless --from overrides.

Procedure

The cascade runs five phases sequentially. Each phase invokes its underlying skill via the harness's skill-invocation tool (see the master skill § Routing for how sub-skills are addressed), surfaces the phase's prep summary, then waits for user confirmation (unless --skip-confirm or hands-off mode) before advancing.

Phase 1 — extract --prep

Invoke the stardust extract skill with the argument --prep. Claude Code form: Skill { skill: "stardust:extract", args: "--prep" }.

The underlying skill runs the standard extract procedure with the five --prep overlays (lift cap, page typing, module candidates, typed slots, prep summary).

On completion, surface the summary verbatim, name the flow, and gate — the first interactive gate of the cascade carries the keep-vs-redesign choice (one recorded migration ran this cascade for 3.5 hours before the user asked for the keep-design flow, and the work was discarded):

Flow: redesign — the design changes while migrating. Say `switch to replica` now if it is to be kept.
Confirm and continue? (yes / refine "<phrase>" / switch to replica)

User options:

  • yes — advance to Phase 2.
  • switch to replica — the design is to be kept: stop this cascade and run $stardust replica <url> --switch-flow (master skill § Two migration flows). The extract just produced is reused by replica Phase 1; nothing else from this flow is.
  • refine "<phrase>" — re-invoke extract --prep with the refinement (e.g., "type news/* slugs as listing not article", "exclude /search and /404 from inventory"). Re-surface summary; loop.
Provenance guard (between Phase 1 and Phase 2)

Before invoking direct --prep, validate every page in the inventory via validateProvenance(page) per skills/stardust/reference/state-machine.md § Provenance validation. Abort the cascade with the helper's error if any page lacks live-render evidence. This is the cascade-level defense against the failure mode where extract --prep (or its delegated sub-agent) silently synthesized one or more page records — extract's own write-time refusal is the primary guard, but the cascade adds a second check between phases so the synthesis bug recurring under a different rationale cannot quietly contaminate the rest of the run.

The same guard runs implicitly inside Phase 2, 3, and 4 (each underlying skill's setup calls validateProvenance() per its own SKILL.md) — but surfacing it here as an explicit cascade step makes the abort happen before the user sees the Phase 2 prep summary, which would otherwise look like a successful run.

Surface in the cascade output:

Provenance OK on 127 pages.

When the check fails:

Provenance check failed on 20 of 127 pages — see error above.
Cascade aborted between Phase 1 and Phase 2.
   → Re-run extract for the affected slugs:
       $stardust extract --refresh <slug-1>
       $stardust extract --refresh <slug-2>
       ...

Phase 2 — direct --prep

Invoke the stardust direct skill with the argument --prep. Claude Code form: Skill { skill: "stardust:direct", args: "--prep" }.

The underlying skill runs five --prep overlays (type catalog confirmation, module catalog finalization, color reservations, direction re-evaluation, brand metadata defaults).

Surface the summary and gate. User options match Phase 1 (yes / refine "<phrase>").

Phase 3 — prototype --prep

Invoke the stardust prototype skill with the argument --prep, plus --canon-from <slug> when a canon slug is already known. Claude Code form: Skill { skill: "stardust:prototype", args: "--prep --canon-from <slug>" }.

The underlying skill fills page-type gaps (one approved archetype per type) and writes canon back per skills/prototype/reference/canon-extraction.md. First approval establishes canon; subsequent approvals extend it (with conflicts logged as deviations by default).

This phase typically takes the longest — each archetype goes through the full prototype loop (shape brief, craft, open in browser, iterate, approve). Stream progress to the user as each archetype lands.

Surface the summary and gate.

Phase 4 — assets prep

Generate or download asset variants needed for the migrated site. This phase has no underlying SKILL — it runs as a small image- processing + download routine.

  1. Favicon variants. From the canonical favicon at stardust/current/assets/favicon.<ext>, generate:

    • stardust/migrated/assets/favicon-512.png
    • stardust/migrated/assets/apple-touch-icon.png (180×180)
    • stardust/migrated/assets/icon-192.png, icon-512.png (manifest sizes)
  2. Font downloads. Scan stardust/canon/canon.css (and stardust/canon/header.html / footer.html) for @font-face rules with external URLs. For each:

    • Download the file to stardust/migrated/assets/fonts/<basename-with-hash>.<ext>.
    • Rewrite the @font-face url(...) reference in canon files to the local path.
    • Skip if already downloaded (sha-compared).
    • Log a warning if download fails (font keeps external URL; migrate logs a metadata-override warning per page).
  3. Brand-asset audit. Verify the logo, favicon, and any media files referenced by canon module renderings are present in stardust/current/assets/. Surface missing assets to the user.

Surface summary and gate:

assets prep complete
====================

Favicon variants:    favicon-512.png, apple-touch-icon.png, icon-192.png, icon-512.png
Font downloads:      4 files (HarmoniaSans 4 weights)
Brand assets:        all present

Phase 4.5 — Dynamic surface (pre-import gate: dynamics Phases 1–3)

Runs after assets prep and before any bulk import. Migration-bound: this is the step that keeps a dynamic site from being imported as a static one. Delegate to skills/dynamics/SKILL.md:

  1. Detect — re-run extract --dynamics if Phase 1 ran without it (reach), then dynamics-detect.mjs --from-state stardust/state.json --reach stardust/current (depth on archetypes).
  2. Classify + triage — dynamics-plan.mjs [--target-origin <host>] drafts the four axes per row; curate into stardust/dynamic-features.md (§ Listings contract with helix-query.yaml, § Features, § Decision batch, § Register) and stardust/dynamic-features-plan.md.
  3. Gate — passes when every row has a disposition. "none" in both sections is a valid pass. The gate never blocks the static path; it blocks silent regressions.

Summary line: dynamic surface: N findings · self K · owner batch M · host-bound H · listings L dynamic / S static. Contract: skills/dynamics/reference/triage.md.

Final report

prepare-migration complete
==========================

Phase 1 (extract --prep):      127 pages, 7 types, 8 module candidates
Phase 2 (direct --prep):       types & modules confirmed; metadata set
Phase 3 (prototype --prep):    6 archetypes approved; canon written
Phase 4 (assets prep):         favicon variants + fonts + brand assets ready
Phase 4.5 (dynamic surface):   14 findings · self 6 · owner batch 7 · host-bound 1 · listings 3 index-backed / 1 static

Next: $stardust migrate

Outputs

prepare-migration writes nothing directly — every artifact is written by the underlying skill or by the Phase 4 / 4.5 routines. After the cascade runs, the project state has:

ArtifactPhase that wrote it
state.json.pages[].typeextract --prep
current/pages/<slug>.json § slotsextract --prep
DESIGN.json.extensions.modules[] (status: confirmed)extract --prep + direct --prep
DESIGN.json.extensions.colorReservations[]direct --prep
DESIGN.json.extensions.metadatadirect --prep
stardust/canon/ (header, footer, css, modules/)prototype --prep
DESIGN.json.extensions.canonprototype --prep
stardust/migrated/assets/favicon-*assets prep
stardust/migrated/assets/fonts/assets prep
stardust/dynamic-features.md + -plan.md (inventory, four axes, decision batch)dynamics gate (Phase 4.5)
helix-query.yaml (scoped indexes, EDS project root)dynamics gate (Phase 4.5)
stardust/state.json (per-page status updates)each underlying phase

Failure modes

  • No state.json or no extracted pages. Recommend $stardust extract <url> and stop.
  • No active direction. Recommend $stardust direct and stop.
  • User refuses a phase. Stop the cascade cleanly. State is left in a consistent intermediate (the underlying skill's writes have landed); the user can resume with $stardust prepare-migration --from <phase>.
  • Underlying skill fails. Surface the failure verbatim; do not advance. User fixes and re-runs.
  • Phase 3 canon conflict during a non-canon-author approval. Conflicts log as deviations by default per reference/canon-extraction.md. If the user wants to override per-conflict (promote to canon / reject and re-iterate / log as deviation), surface during the phase's confirmation gate rather than at runtime. A future --strict-canon flag could refuse approvals that conflict; not in v0.2.
  • Phase 4 asset download failure. Continue the run; log the failure in the assets-prep summary. Migrate later surfaces a warning per affected page.

Concurrency

Per skills/stardust/reference/state-machine.md § Concurrency: state.json writes merge by slug, so the cascade's per-page writes coexist with other parallel lanes. But two concurrent prepare-migration runs on the same project race on the same top-level artifacts (canon, module catalog) — that remains last-write-wins with a warning, and is likely to corrupt canon. Don't run two cascades at once; do not engineer a lock around it.

Idempotency

Re-running prepare-migration after partial completion resumes from the earliest incomplete phase (or the explicit --from phase). Each underlying skill is itself idempotent — already- typed pages are not re-typed, already-confirmed modules are not re-proposed, already-approved archetypes are not re-prototyped, already-generated favicon variants are not re-generated, and an existing dynamic-features.md is refined rather than rewritten.

Re-running after full completion is a no-op unless inputs changed (extract found new pages, direction was edited, the canon-author prototype was re-iterated, etc.).

References

  • skills/extract/SKILL.md § Prep mode
  • skills/direct/SKILL.md § Prep mode
  • skills/prototype/SKILL.md § Prep mode
  • skills/prototype/reference/canon-extraction.md — the five-step extraction procedure prototype --prep performs on approval
  • skills/dynamics/SKILL.md + reference/triage.md, reference/listings.md — Phase 4.5 is its Phases 1–3
  • skills/migrate/SKILL.md — the consumer of every data structure this cascade prepares
  • skills/stardust/reference/state-machine.md — page typing, stale-flagging cascade
  • skills/stardust/reference/artifact-map.md — file structure, DESIGN.json.extensions shape

stardust:prototype

For each directed page, render a proposed redesign as a self-contained static HTML file at stardust/prototypes/<slug>-proposed.html. Open the file in the browser; iterate via chat-driven impeccable commands ("make the hero bolder", "tighten the cup-note grid"). Mark approved once the user signs off in the conversation.

prototype is not a renderer of its own design — it composes the target spec written by direct (PRODUCT.md, DESIGN.md, DESIGN.json, stardust/direction.md) onto the page content captured by extract (stardust/current/pages/<slug>.json). Visual creativity is delegated to $impeccable craft and the iteration commands (bolder, quieter, distill, polish, colorize, typeset, layout, adapt, animate, delight, overdrive, impeccable).

This file is the outline of the procedure. The text of each phase is in skills/prototype/reference/, in the file the phase names. Read that file in full when you reach the phase; never work from a heading alone.

Inputs

  • <slug> — optional positional. Prototype just this page. Without it, prototype every directed page that is not stale.
  • --all — prototype every directed page including stale ones.
  • --prep — optional. Run in migrate-prep mode: fill page-type gaps (prototype one representative archetype per type) and, on approval, write canon back to stardust/canon/ and DESIGN.json.extensions.canon. See § Prep mode below and reference/canon-extraction.md. Typically invoked via the prepare-migration orchestrator.
  • --canon-from <slug> — optional. Override the default canon- author (which is the first approved prototype, typically home). Used when a different page should establish the design canon.
  • --publish-sample <slug> — submit the named slug to the stardust showcase. Triggers the publish-sample sub-flow documented in reference/publish-sample.md: eligibility checks, file staging, PR creation against the upstream stardust repo. Requires gh installed and authenticated. The showcase is a visual demonstration, not a deployable site — placeholder content is allowed and recorded in the PR body's § Unsourced content section. Design-quality gates stay strict: refuses on unjustified anti-toolbox hits, :root token contract failure, data-attributes contract failure, or impeccable hard-rule violations. P0/P1 critique findings warn but don't refuse. The showcase publishes via GitHub Pages on merge.
  • --cinematic — optional. Layer a cinematic motion register on top of the static prototype. The register is read from DESIGN.json.extensions.motion.register (written by direct); if absent, the prototype phase picks one using the same heuristic per reference/motion-registers.md § Selection heuristic. Output filename is <slug>-cinematic.html (alongside the static <slug>-proposed.html, never replacing it). Triggers the cinematic gates in motion validation (reference/motion-validation.md § Pass 6).
  • --cinematic=<register> — optional. Same as --cinematic but forces a specific register (arrival, kinetic-display, live-systems, editorial, kinetic-grid). The override is recorded in _provenance.motion.registerSource = "user-override" so reviewers can spot when direction's heuristic was bypassed.

No opt-outs

prototype does not carry --no-* or --skip-* flags. The quality gates (critique, audit, mobile-adapt audit, anti-toolbox audit, content-sourcing scan) are the product — they're not optional. If a gate refuses a file, the remediation is to fix the file or override the gate by editing the file directly, not to pass a flag that silently lowers the bar. Manual chat overrides ("ship as-is", "accept the P1 findings") are still available; the agent records the override verbatim in _provenance so downstream consumers see the explicit acknowledgement.

Setup

  1. 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.
  2. Run the master skill's setup (skills/stardust/SKILL.md § Setup).
  3. Verify stardust/state.json exists and contains at least one directed page. If not, recommend $stardust direct and stop.
  4. Verify the project-root DESIGN.md and DESIGN.json exist. If not, the direction was not fully authored — recommend $stardust direct and stop.
  5. Verify stardust/direction.md has an active (not pending) direction. Pending directions block prototype.
  6. Validate provenance on every page in scope. Call validateProvenance(page) per skills/stardust/reference/state-machine.md § Provenance validation for every page that this run will render (the single <slug> argument when present, otherwise every non-stale directed/prototyped/approved page). Abort with the helper's error when any page lacks live-render evidence — re-running prototype against a synthesized page record silently propagates the synthesis into the rendered prototype. Surface Provenance OK on N pages once the check passes.
  7. Read stardust/current/DESIGN.md (the descriptive snapshot of the existing site, used as a fallback reference during render when the proposed file needs to mirror an aspect of the captured surface).

Delegation mechanic

Read skills/prototype/reference/delegation-mechanic.md in full before you act on this section. It covers: Invoking impeccable.

Procedure

Phase 1 — Plan the prototype (page-shape brief)

Read skills/prototype/reference/phase-1-plan.md in full before you act on this section. It covers: Brief-time disciplines.

Phase 2 — Render the proposed page

Read skills/prototype/reference/phase-2-render.md in full before you act on this section. It covers: Craft-time disciplines.

Phase 2.4 — Motion application (when --cinematic)

Read skills/prototype/reference/phase-2-4-motion-application.md in full before you act on this section. It covers: Output paths; When to use the static-only path.

Phases 2.5 – 2.8 — Quality gates: Critique → Audit → Adapt → Motion (Discipline 9)

Read skills/prototype/reference/phase-2-5-to-2-8-quality-gates.md in full before you act on this section.

Phase 2.5 — Critique

Read skills/prototype/reference/phase-2-5-to-2-8-quality-gates.md in full before you act on this section.

Phase 2.6 — Audit (detector specifics)

Read skills/prototype/reference/phase-2-5-to-2-8-quality-gates.md in full before you act on this section.

Phase 2.7 — Adapt (mandatory pre-approval)

Read skills/prototype/reference/phase-2-5-to-2-8-quality-gates.md in full before you act on this section. It covers: Adapt procedure; Mobile-adapt audit; Mobile nav collapse.

Phase 2.8 — Motion validation (mandatory when motion declared)

Read skills/prototype/reference/phase-2-5-to-2-8-quality-gates.md in full before you act on this section. It covers: Variant-convergence detector.

Phase 4 — Open and iterate

Read skills/prototype/reference/phase-4-and-5-iterate-and-approve.md in full before you act on this section. It covers: Iteration paths.

Phase 5 — Approval (+ fold-back, Part III)

Read skills/prototype/reference/phase-4-and-5-iterate-and-approve.md in full before you act on this section.

Phase 5.5 — Adapt for mobile (retired; see Phase 2.7)

Adapt and the mobile-adapt audit moved to Phase 2.7 as part of the Discipline 9 critique → audit → adapt cycle, gating prototyped instead of approval. A 2026-05-03 e-commerce showcase failure mode (stakeholders eyeballing variants on a phone getting the unadjusted desktop layout) is unchanged — the gate just fires earlier in the lifecycle, so a non-adapted prototype never lands as prototyped in the first place.

The implementation (impeccable adapt invocation, mobile-adapt audit, mobile-nav-collapse stock pattern) lives in § Phase 2.7 above. This section is retained as an anchor for any external cross-reference that still names Phase 5.5.

Stale handling

When direction.md changes, the prototype's againstDirection provenance becomes outdated and state.json flags the page stale: true. Default behaviour:

  • $stardust prototype (no slug) skips stale pages and reports the count: 2 stale pages (home, about) — re-run with --all.
  • $stardust prototype home operates on home even if stale.
  • $stardust prototype --all re-prototypes every directed page including stale ones.

When a stale page is successfully re-prototyped, clear its stale flag and update againstDirection to the new active direction.

Outputs

PathPurpose
stardust/prototypes/<slug>-shape.mdPer-page compositional brief (Phase 1 output, craft input).
stardust/prototypes/<slug>-proposed.htmlProposed redesign (chat-driven iteration target, migration source, user-facing review surface).
stardust/state.jsonUpdated with page status and approval history.
DESIGN.jsonUpdated with extensions.divergence.anti_toolbox_hits and any audit amendments from this prototype's render.

Failure modes

  • No directed pages. Recommend $stardust direct and stop.
  • Pending direction. Refuse to run; the user must resolve the direction first.
  • Validation failure (:root block missing, data attributes missing, unjustified anti-toolbox hit, impeccable rule violation). Do not write the file. Surface the specific failure and a suggested fix.
  • Impeccable not available. Refuse to run — impeccable is a hard requirement (Delegation mechanic). Recommend the user install the impeccable plugin and re-invoke.

Concurrency

Per state-machine.md: stardust does not lock. Two concurrent prototype runs on different slugs are safe. Two on the same slug are last-write-wins; warn the user if they explicitly try.

Prep mode (--prep)

Read skills/prototype/reference/prep-mode.md in full before you act on this section. It covers: 1. Fill page-type gaps; 2. Canon write-back on first approval; 3. Canon write-back on subsequent approvals; Prep summary.

References

  • reference/page-shape-brief.md — per-page compositional brief format (Phase 1 output, craft input). Page-level deployment decisions live here; site-level system decisions live in DESIGN.md.
  • reference/canon-extraction.md — the five-step canon-extraction procedure performed on prototype approval in --prep mode.
  • reference/proposed-file-shell.md — proposed-file schema and required structure (:root token block, data attributes, provenance, content sourcing hierarchy, mobile-adapt audit).
  • reference/publish-sample.md — --publish-sample sub-flow: eligibility checks, file staging, PR creation against the upstream stardust showcase. Lands the prototype as a public sample at https://{owner}.github.io/stardust-2/.
  • reference/mobile-nav-collapse.md — stock CSS-only hamburger pattern Phase 2.7 auto-applies when the Mobile-adapt audit refuses on horizontal-overflow-at-360px or nav-readability-floor. Carries the copy-pasteable HTML+CSS+JS, the audit smoke-test command, and the alternative-pattern vocabulary.
  • reference/motion-validation.md — Phase 2.8 procedure: scroll-position probe, finding classification, motion-bug checks (clipped-container reveal timing, animation-range vs reading position, anim-enter trigger reachability, reduced-motion override completeness, no-JS state, multi- viewport scroll-driven check). Reusable Playwright probe patterns documented inline.
  • reference/motion-registers.md — five brand-faithful motion registers (arrival, kinetic-display, live-systems, editorial, kinetic-grid), the selection heuristic that maps PRODUCT.md Brand Personality traits to a register, and the § Extension rule for bespoke registers derived from the site's own captured motion. Consumed by Phase 2.4 (motion application).
  • reference/motion-stack.md — technology choice for cinematic prototypes: Lenis + CSS keyframes + rAF + IntersectionObserver. Why not GSAP. Bundle policy + Lenis pinning procedure.
  • reference/motion-attributes.md — data-* vocabulary the cinematic runtime consumes ([data-anim], [data-tile-anim], [data-countup], [data-flip], [data-fill], [data-split], [data-parallax]). Annotated per the active register.
  • reference/motion-runtime.md — the canonical inline runtime script that powers every cinematic prototype. Single source of truth; embedded verbatim during Phase 2.4.
  • reference/fidelity-refined-pass.md — concrete CSS recipes for the --fidelity=refined craft micro-pass (Discipline 8).
  • reference/anti-template-bank.md — worked examples of the non-template moves Discipline 3 draws from (typographic substitution / substrate-promotion / inversion / document-shape / scale-displacement), plus the § Extension rule for evidence-shaped new moves.
  • skills/stardust/reference/reference-research.md — sourcing real-world design references (refero MCP with WebSearch fallback, graceful skip when unavailable); consumed by Discipline 2's reference-grounded alternatives.
  • reference/approval-fold-back.md — Phase 5 fold-back procedure (Part III of the merged spec): diff algorithm, surfacing UX, write logic, stale flagging, --auto-fold / --no-fold flags, verbatim no-op gating.
  • fixtures/composition-delta-good.md — example shape brief with a strong structural compositionDelta (passes Discipline 10).
  • fixtures/composition-delta-trivial.md — example shape brief with token-only deltas (fails Discipline 10).
  • ../stardust/reference/token-contract.md — :root token block (cross-cutting, used by prototype + migrate).
  • ../stardust/reference/data-attributes.md — structural data attribute vocabulary (cross-cutting, used by prototype + migrate).
  • ../stardust/reference/divergence-toolkit.md — anti-mediocrity rules consumed during render and iteration.
  • ../stardust/reference/intent-dimensions.md — the 7-axis vocabulary used to read a chat-driven refinement phrase (iteration path 2).
  • ../stardust/reference/impeccable-command-map.md — when to reach for each impeccable command. Consulted during chat-driven iteration (path 2) to pick the command for a refinement phrase.
  • ../stardust/reference/state-machine.md — page lifecycle and stale rules.
  • ../stardust/reference/artifact-map.md — provenance shape.
  • impeccable's reference/craft.md and reference/live.md — the underlying impeccable commands stardust delegates to.

stardust:qa — read-only site QA sweep

One live URL in. One evidence-bound findings report out. This skill never edits anything — not site content, not DA documents, not repo code. Its only writes are report artifacts under stardust/qa/. If the user wants findings fixed, that is a separate, explicit follow-up outside this skill.

qa is the post-deploy counterpart of rollout's delivery verification: where rollout asks "did every page ship?", qa asks "is everything that shipped actually correct?" — at all three layers a deploy can silently break:

  1. delivery — what the pipeline serves (.plain.html, full HTML, sheets, sitemap)
  2. rendered — what a browser shows after block decoration (and what it does: an autoplay video that only shows its poster is a rendered defect)
  3. regression — what changed since the last approved state (visual baselines)

A green upper layer never implies the lower one: a publish 200 ≠ delivered, delivered HTML ≠ rendered correctly.

Setup

  1. Run the master skill's setup (skills/stardust/SKILL.md § Setup) if not already done this session. qa works standalone too — it only needs a live base URL.
  2. Resolve the base URL (the *.aem.live host or production domain). If the user didn't give one, look in stardust/rollout/rollout.json (site.liveHost) or ask.
  3. Resolve the inventory source — what pages the sweep covers, merged from any of: stardust/template-map.json (also supplies template assignments for conformance; scripts/from-knowledge.mjs writes it from a spec, plus allowlist entries for 404s the source already had), a paths file, and the live sitemap.xml (always fetched; parity mismatches become findings, so a wrong sitemap can't silently shrink coverage).
  4. Optional inputs that unlock deeper checks:
    • --scrape stardust/scrape — verbatim fidelity vs the extraction capture
    • --expected-blocks <json> — explicit per-template block expectations
    • --parity <json> — dynamic parity file to replay (default stardust/dynamics/parity.json; the dynamics check reports parity-missing when absent)
    • --auth-header "token …" / --token-env SITE_TOKEN — protected origins; the secret is sent to the base origin only (otherwise derived by fleet consensus)
    • --blocks-dir <dir> — the site's blocks/ checkout, so the editability check can honour @ew-exempt JSDoc tags (otherwise pass --ew-exempt a,b for index-driven blocks)
  5. Browser checks need playwright resolvable from the project (node_modules/playwright). If missing, run the delivery-layer checks only (--checks routing,content,templates,metadata,links) and tell the user what was skipped.
  6. Append a phase-transition line to stardust/status.jsonl per reference/run-status.md (master skill) at sweep start/end.

Procedure

Phase 1 — deterministic sweep

node <plugin>/skills/qa/scripts/qa.mjs \
  --base https://main--<site>--<org>.aem.live \
  --template-map stardust/template-map.json \
  --scrape stardust/scrape

Writes stardust/qa/inventory.json, report.json, report.html, screenshots under stardust/qa/shots/, and (first run) visual baselines under stardust/qa/baselines/. Exit 0 = no active errors, 1 = active errors, 2 = infra failure. reference/checks.md documents every check, its finding ids, and severity rationale. Useful variants: --checks <subset>, --max-pages <n> (smoke run), --fail-on warn (strict gate). The ai-readability check reproduces Adobe's AI Content Visibility Checker per page (served words ÷ rendered words) and attributes the gap per block (deploy/reference/ai-readability.md).

The editability check is the post-deploy Experience Workspace editability gate (deploy SKILL.md § 8, EW1–EW10): per page it re-creates the da.live canvas's instrumentation on the served document, lets the live page decorate, and counts which authored texts still carry their editor index. editability/dead-text (error) = a block rebuilt authored text and the author cannot click it in the canvas; editability/duplicated-index (warn) = a presentational clone kept the index. Dead texts inside blocks declared @ew-exempt (or listed in --ew-exempt) are info, not errors.

First run on a site: expect a wave of visual/baseline-created info findings — that is the baseline being established, not a defect. Baselines are screenshots and therefore local (stardust/.gitignore excludes qa/baselines/ and qa/shots/, master skill § Artifacts): later runs on the same machine diff against them; a fresh clone re-establishes them on its first sweep. qa/allowlist.json is the tracked record of judgement.

Phase 2 — triage the ambiguous flags (LLM judgment, still read-only)

The deterministic sweep marks two finding classes as needs triage; read report.json and judge only those:

  • content/verbatim-below-threshold — inspect evidence.missingNodes against the live page and the scrape capture: is copy actually lost/corrupted (defect) or acceptably transformed (candidate for the allowlist)?
  • visual/visual-diff — open evidence.baseline and evidence.current side by side (they are PNGs; view them): real layout/style regression, or benign dynamism (carousel frame, loaded font, live embed)? Use the bands evidence to locate the changed region.

Record each verdict by annotating the finding in your summary to the user (defect vs non-defect + why). Do not edit report.json scores and do not fix anything.

Phase 3 — report to the user

Summarize: totals by severity, the confirmed defects first (with page paths and one-line evidence), then triaged-away flags with their rationale, then notable warns. Point at stardust/qa/report.html. Recommend — but do not apply — fixes.

Allowlist workflow (documented non-defects)

stardust/qa/allowlist.json (schema in schemas/qa-allowlist.schema.json) keeps known non-defects from drowning every future run — e.g. a source page that itself ships placeholder copy, or a form endpoint deliberately awaiting a client credential. Entries match on check/id/path/messagePattern and must carry a reason. Allowlisted findings stay in the report, greyed out, so the evidence is never deleted.

Only add an entry when the user confirms the flag is a non-defect (or it is already documented as one in the project's records). Never allowlist to make a run green.

Read-only contract

  • Writes only under stardust/qa/ (plus the status.jsonl ledger line).
  • Never invokes deploy/publish APIs, never PUTs to DA, never edits blocks, styles, or content — even for "trivial" fixes the sweep itself surfaced.
  • Reports failure honestly: a crashed check appears in the report as <check>/check-crashed (error), never silently dropped.

Scheduling / CI

The runner is plain node with no plugin-runtime dependency, so the same command works from a GitHub Action or cron for drift monitoring; --fail-on sets the gate. In CI without playwright, pin --checks to the delivery-layer subset.

stardust:replica — same-design migration

Same pages, same content, same design — new platform. The target spec IS the captured current state, the only permitted deltas are the entries of an explicit inconsistency register, and every archetype passes a measured source-fidelity gate against the live site before anything ships.

  1. No creative decisions. The direction step is mechanical promotion of the captured spec: the stardust direct skill is never invoked and impeccable craft is never delegated to (its redesign gates do not apply — a "tastefully improved" section is a failing section).
  2. Recreation, not copying. Archetypes are clean semantic HTML/CSS authored from captured content and from values MEASURED on the source — never DOM copies, never ported page-level stylesheets. Fidelity is proven by instruments, not asserted.

Inputs

  • <URL> — required. The site to migrate.
  • --breakpoints <list> — optional. Gate widths, default 1440,360; each gets its own gate pass (mobile is not free — gate doc § Per-breakpoint).
  • --target-breakpoints <list> — optional. Mobile-first min-width steps (e.g. 600,900,1200) the delivered site switches layout at instead of the source's. Absent = source breakpoints kept, every target step below skipped. Persisted in DESIGN.json extensions.breakpoints.target.
  • --register <file> — optional. Inconsistency items to seed the register (Phase 2). Without it and without an audit the register is empty.
  • --first-page <url|home> — optional; hands-off home. The page a full-site run delivers first (reference/first-page-first.md).

Setup

  1. Run the master skill's setup (../stardust/SKILL.md § Setup). Flow guard: if state.json.flow is redesign, refuse — print the never-mix line and the switch command ($stardust replica --switch-flow; master skill § Two migration flows). If flow is absent, stamp flow: "replica", flowSource: "user-phrase".
  2. Probe the gate's deps from the project root — node -e "import('pixelmatch').then(()=>process.exit(0))" (and playwright, pngjs, cheerio) — and only on failure install them AS devDependencies, never --no-save (npm i -D playwright pixelmatch pngjs cheerio --legacy-peer-deps): ESM resolves from the project root, and the delivered repo carries what is installed.
  3. Copy scripts into the project and run them from there: this skill's scripts/ to stardust/scripts/replica/, ../stardust/scripts/ to stardust/scripts/stardust/, ../migrate/scripts/ to stardust/scripts/migrate/ and ../diff/scripts/ to stardust/scripts/diff/ (siblings — the gates import across them). Never into the project-root scripts/: that is the EDS boilerplate's.

The context is the budget — read reference/reading-discipline.md once at Setup. Reference docs by section (section.mjs <doc> --list, then one heading per call); captures through css-rules.mjs, json-query.mjs and html-slice.mjs; instrument output through run-bg.mjs wait and log --grep, never cat; script flags from ../stardust/reference/scripts-index.md, then --help, never the source.

Procedure

Five phases. 1 and 5 delegate to existing skills unchanged; 2–4 are replica's. A full-site run opens first page first (reference/first-page-first.md). Every phase opens with node stardust/scripts/stardust/ledger.mjs replica <phase> start as its FIRST command and closes with the end line plus its section in stardust/journal.md (../stardust/reference/run-status.md).

Phase 1 — EXTRACT (delegate to $stardust extract --prep --dynamics)

Invoke $stardust extract <URL> --prep --dynamics, unchanged. Replica consumes the full migration inventory: stardust/current/pages/<slug>.json (the verbatim source of every string), the per-page screenshots, the captured fonts and media, the descriptive PRODUCT.md / DESIGN.md / DESIGN.json, state.json.pages[].type (each type becomes one archetype) and DESIGN.json.extensions.modules[] (block candidates).

Surface extract's summary with the flow line first — "Flow: replica — the design is kept. Say switch to redesign now if it is to change." (switch to redesign runs $stardust prepare-migration --switch-flow; the extract is reused, nothing else is.)

Bounded entry (one page, or a pilot): $stardust extract <URL> --single --dynamics (or --pages <slug,...> --dynamics) is a first-class way in. It provides what recreation needs per page; it skips page typing and module detection, needed only when Phase 5 fans out, and the descriptive synthesis (Phase 2 takes the bounded promotion branch).

If extract fell back to headed Chrome, the gate captures need --headed too.

Phase 2 — PRESERVE DIRECTION (mechanical — never invoke the stardust direct skill)

Full contract: reference/preserve-direction.md.

  1. Promote stardust/current/PRODUCT.md, DESIGN.md, DESIGN.json verbatim to the project root as the target spec — no divergence roll, no re-direction. Bounded entry: those files do not exist; take the bounded promotion branch (§ 1a, provenance bounded-single). Never mix the two.
  2. Write stardust/direction.md: what was promoted, from where, the provenance and the register pointer — what tells downstream skills the direction step happened.
  3. Build the inconsistency register at stardust/replica/inconsistency-register.md — the ONLY permitted design deltas. Sources: audit design findings (only when the user wants improvement candidates) and --register items; every entry carries captured evidence, the minimal change and a status. An empty register is a pure replica, a valid and common outcome.
  4. Target breakpoints (only with --target-breakpoints), before any CSS exists (§ 4): persist the list, map each source breakpoint to a step in stardust/replica/breakpoint-map.md, seed the ONE register entry.
  5. Dynamic surface (the stardust dynamics skill, Phases 1–3): run the detector on the archetypes, draft the triage, curate stardust/dynamic-features.md and its plan — every row gets a disposition (skills/dynamics/reference/triage.md). This is what surfaces the modals, forms, search and host-bound APIs a pixel gate certifies as correct.

Anything not in the register is out of scope for change: a recreation choice that "improves" something unregistered is a fidelity bug.

Phase 3 — RECREATE (one archetype per page type)

Full method: reference/recreation-procedure.md (§ Authoring order). For each page type (archetype: the type's rep_url in a spec's archetypes.json) author stardust/prototypes/<slug>-proposed.html (+ its CSS):

  1. Measure the source first, at every gate width, before any CSS: node stardust/scripts/replica/source-spec.mjs capture <live-url> --slug <slug> --widths 1440,360 writes a spec per width and the header and footer inventory. Author from them.
  2. Content verbatim from current/pages/<slug>.json — headings, body, CTAs and hrefs, alt text, metadata (../migrate/reference/content-preservation.md): no rewording.
  3. The source's CSS for what the spec cannot name (states, media-query structure, tokens), read through css-rules.mjs. The container model is measured (DESIGN.json extensions.breakpoints; a bounded entry runs cap-probe.mjs <live-url> --write-design stardust/current/DESIGN.json first). Any other live-vs-prototype box check goes through measure.mjs --against, never an authored probe.
  4. source-spec.mjs compare <spec> <prototype-url> exits 0 at every width BEFORE the first gate round.

Fonts (§ Fonts policy): the captured faces are self-hosted as-is, proprietary ones with deploy's licensing alert and one register entry; a substitute renders only a face with no captured file, declared in stardust/replica/font-subst.txt.

With a target set, every @media rule and JS width threshold is authored on the target steps from the first line per breakpoint-map.md; breakpoint-lint.mjs exits 0 on a prototype before its gate.

Every archetype gets its own standalone prototype — cumulative, never skipped. Never go straight to platform authoring for a new archetype: direct-authored pages plateaued at 8–16 % in the field, prototyped ones at 3.5–5.6 %. Each new prototype imports the shared layers already gated and iterates only on its new modules (§ Cumulative archetype prototypes).

CSS-portation is the per-section fallback only (§ CSS-portation fallback): paint effects not recoverable from computed styles, JS-hydrated widgets, video or animated heroes — the minimal source rules, scoped, never page-level.

Phase 4 — SOURCE-FIDELITY GATE (measured, per breakpoint)

Full contract: reference/source-fidelity-gate.md ("gate doc"). Per archetype, per breakpoint, live URL against the served prototype:

PROTO="http://localhost:8791/<slug>-proposed.html"   # ONE server, ONE port; one that answers but is not yours is never killed — take another port
LIVE="https://<site>/<path>"
G=stardust/replica/gates/<slug>-1440
# A round = gate.sh through run-bg, never a hand-written wrapper. The FIRST round of a
# breakpoint and the CONFIRMATION round after the last fix run --full; the others are pixel rounds.
node stardust/scripts/replica/run-bg.mjs start --name <slug>-1440-iter1 -- \
  stardust/scripts/replica/gate.sh <slug> "$LIVE" "$PROTO" 1440 iter1 --full --main "<content-root>"
node stardust/scripts/replica/run-bg.mjs start --name <slug>-360-iter1 -- \
  stardust/scripts/replica/gate.sh <slug> "$LIVE" "$PROTO" 360 iter1 --full --main "<content-root>"
node stardust/scripts/replica/run-bg.mjs wait   # verdict lines; exit 75 = still going → wait again as the NEXT step
# header and footer: style parity BEFORE any pixel round on them (exit 0 = quiet)
node stardust/scripts/replica/chrome-parity.mjs "$LIVE" "$PROTO" --width 1440 --live-cache $G/chrome-live.json
# content-cap row: once per archetype after the 1440 pass, at DESIGN.json's derived probeWidth
node stardust/scripts/replica/cap-probe.mjs "$LIVE" --against "$PROTO" --design DESIGN.json --slug <slug> --main "<content-root>"
# when the archetypes pass: the prototype table, one run per width — a prototype without a row is ungated
node stardust/scripts/replica/gate-all.mjs --stage prototype --proto-base "$PROTO_BASE" --width 1440

gate.sh --help lists the flags and exit codes. Its verdict lines are the pass bar (gate doc § Pass bar): content-diff 0 🔴 and 0 nothing-lost 🟡; visual-diff flags none or justified; pixel aligned ≤ 10 % with the offsets within their bound; |Δh| ≤ 8 px; Clipped: 0; declared repeated units within 4 px; no horizontal overflow; cap-probe: PASS. Exit 124 (deadline), 5 (unstable reference) and 3 (blocked — escalate --headed) are never a verdict: fix the capture and re-run.

  • Reading a failing round (gate doc § Reading the band breakdown): the offset steps are the fix list — fix every one in ONE round; bands are read after alignment. Every fix comes off an instrument line, never the eye.
  • Round cap (gate doc § Iteration discipline): three counted rounds per page, width and stage. gate.sh exits 6 at the cap until rounds.mjs decide records the decision; residuals are logged, never iterated past it.
  • No step waits longer than the context cache lives: a long instrument goes through run-bg.mjs (start, then wait in ≤ 100-second slices) — never in the foreground, never two as parallel tool calls, never behind a sleep.
  • Capture traps are the scripts' flags, the same on both sides (--consent, --dismiss, --headed, --locale, --main — --main body is never valid); a project copy with hand-edits is a defect. The list: gate doc § Hardening rules.
  • With a target set (#131) the gate widths add each target step; inside a shifted band a pixel failure is tier-shift (logged against the register entry) or a defect — gate doc § Target breakpoints.

Interaction parity is a REQUIRED gate output per archetype, after the static gate passes (reference/recreation-procedure.md § Interaction parity): motion is OBSERVED with motion-observe.mjs, never inferred from classes or CSS; only what fired is implemented; the prototype is observed the same way and compared with motion-compare.mjs. Record motion: {observed, implemented, dead[]} in progress.json, then re-run the pixel round — the number returns to the gated value.

When all breakpoints pass, present the archetype and its gate metrics for approval (hands-off records approvedBy: "hands-off"). Bookkeeping is one command each, never a hand-built JSON line: node stardust/scripts/stardust/state.mjs advance <slug> --to approved --by hands-off --prototype stardust/prototypes/<slug>-proposed.html and node stardust/scripts/stardust/ledger.mjs replica source-fidelity-gate end --detail "<per-breakpoint numbers>". Resuming a run starts with ledger.mjs tail and state.mjs summary --slugs, not cat.

Phase 5 — HANDOFF (delegate — migrate → deploy → rollout, unchanged)

Read the contract card first: reference/handoff-contract.md — the migrate, deploy and rollout rules this phase needs, the rollout ledger phase strings, one usage line per script. Read it by section (section.mjs <doc> --list, then the section a step needs), never whole, and never the sibling SKILL.md files whole.

  • Pages beyond the archetypes go through migrate at sibling tier (../migrate/reference/fidelity-tiers.md), only AFTER their archetype is live and gated at the published origin (contract § 3 row C). Siblings inherit the archetype's encoder, never a new one; template constancy is measured first (sibling-variance.mjs), content fidelity per page at import.
  • Delivery via deploy per page: template-slotted for fixed compositions, reconstructive for repeat groups; blocks obey the editability contract and pass block-roundtrip --ew.
  • Site-wide rollout via rollout, unchanged. C-deliver runs in recorded units (contract § 3 row C, Fan-out discipline): the foundation first, gated on the published origin with the header contract, then frozen (no frozen file is edited mid-wave); each archetype deployed and gated on its preview URL BEFORE its siblings render; one subagent per template cluster; C-final.
  • Target breakpoints: C0 authors on the target steps and wires breakpoint-lint.mjs into npm run lint.
  • The final gate runs against the PUBLISHED origin, not the harness (gate doc § The published-origin gate): gate.sh <slug> "$LIVE" "<preview-url>" <width> pub1 --full --marker "<brand or domain string>" through run-bg.mjs, in the page's ordinary gate dir. Nothing pixel-shaped runs on the local harness.
  • The delivery gate is the ALL-PAGES run (gate doc § The all-pages published-origin gate): node stardust/scripts/replica/gate-all.mjs [--only <slug,…>] [--skip-existing] [--eds-host <host>] — pixel, height, clipped text and missing or hidden content; a page without a row is ungated. C-final ends with update-coverage.mjs --gate.

What replica never does

  • No redesign. No new palette, type, spacing, composition, motion.
  • No content rewriting. Captured strings are verbatim; placeholders and hydration states are replicated as captured, not "fixed".
  • No invented improvements. A change without a register entry is a defect, however tasteful.
  • No DOM copying. Never paste the live DOM or port page-level CSS as the prototype: clean re-authoring is the point.

Outputs

stardust/
├── state.json, direction.md, journal.md   ← core state, the preserve-mode record, the run journal
├── current/                               ← from extract
├── prototypes/<slug>-proposed.html        ← gated archetypes, one per page type
├── replica/
│   ├── inconsistency-register.md          ← the ONLY permitted design deltas
│   ├── breakpoint-map.md                  ← only with --target-breakpoints
│   ├── spec/<slug>-<width>.json           ← the measured source (Phase 3)
│   ├── progress.json                      ← per page type: rounds, gate results, residuals, motion
│   ├── motion/<slug>.json                 ← motion-observe evidence
│   └── gates/                             ← <slug>-<width>/ per round; prototypes-<width>/ and all-<width>/ tables
├── migrated/                              ← from migrate (Phase 5)
└── rollout/                               ← from rollout: progress.json (C-deliver units), foundation-freeze.json, foundation-requests.md
PRODUCT.md / DESIGN.md / DESIGN.json       ← promoted from current/ (Phase 2)

References

  • reference/preserve-direction.md — promotion contract, register schema.
  • reference/recreation-procedure.md — authoring order, CSS lifting, fonts policy, fixed and sticky chrome, interaction parity, the fallback.
  • reference/source-fidelity-gate.md — the gate: procedure, pass bar, reading a round, iteration discipline, hardening, the published-origin and all-pages gates, residual logging.
  • reference/handoff-contract.md — Phase 5 contract card.
  • reference/reading-discipline.md, reference/first-page-first.md.
  • ../diff/SKILL.md — the probes replica reuses, the header contract.
  • ../migrate/reference/fidelity-tiers.md — the archetype / sibling model.

stardust:reskin — same content, donor design

The user has a site (the content source) and a design that already exists somewhere else (the donor: another live site, or a directory of static HTML prototypes; Figma is future scope). Reskin rebuilds the content site's pages so that every visible byte of content survives — text, ordered images, CTAs, SEO metadata — while the surface comes entirely from the donor's tokens and module vocabulary.

The two halves have different contracts:

  • Content is non-negotiable. The gate is byte equality of whitespace-normalized visible text, the ordered visible-image set, and full metadata carry-over. Not "close" — equal, after an explicitly declared, executable normalization ledger.
  • Design is flexible. Content is re-laid-out onto donor modules; a carousel may become a static card grid, a sidebar may become a band. Structure (element counts, tag sequences) is informational, never gating — a reskin re-structures markup by design.

The decisive rule, validated in the UC2-E1 experiment (a healthcare site × a fintech donor: 2281/2281 text bytes, 7/7 images, 47/47 slots, 13/13 metadata, 17/17 donor-token probe): the page is generated programmatically from the captured content model — content strings are never retyped. Byte fidelity then holds by construction and the content gate becomes a regression check instead of a debugging tool.

Inputs

  • <content-url> — required. The site whose content is preserved.
  • Donor, exactly one of:
    • --donor <url> — a live site whose design system is adopted.
    • --donor-dir <path> — a directory of local static HTML prototypes (claude-design / Mobirise / Relume / Lovable / v0 / hand-coded). Served on localhost and captured through the same path — recipe in reference/donor-sources.md § Local prototypes.
    • --donor-figma <url> — not yet implemented. The contract is defined (reference/donor-sources.md § Figma) but the adapter is future scope. Tell the user exactly this: "Figma donors are not implemented yet. Export the frames as static HTML prototypes (or point me at a live staging URL of the design) and re-run with --donor-dir / --donor. The Figma adapter — variables→palette, text styles→type, frame screenshots→vision references, provenance class figma-mcp — is specced in skills/reskin/reference/donor-sources.md and will land in a later release." Do not improvise a partial Figma capture.
  • --pages <slug,slug,...> — optional. Restrict the content capture to specific pages. Default: the archetype set (one page per page family; a spec's archetypes.json names them; scale to siblings happens in Phase 6 via migrate).
  • --scope <selectors> — optional. Pre-declare the content-root scope for a single-page run (comma-separated, ! suffix keeps a scope whole; see reference/content-model.md § Scope declaration). Without it, run the scope-discovery procedure per page.

Setup

  1. Run the master skill's setup (../stardust/SKILL.md § Setup): impeccable dep check, context loader, state read. Flow. Stamp state.json.flow: "reskin" if unset (../stardust/reference/state-machine.md § Flow keys); if another flow is set, print it and the switch command ($stardust reskin --switch-flow) instead of running.
  2. Playwright import-resolvability probe — same contract as ../extract/SKILL.md § Setup: node -e "import('playwright').then(()=>process.exit(0))" from the project root; on failure npm i -D playwright --no-save --legacy-peer-deps. Re-run the probe at the start of every phase that renders — a --no-save install is pruned by any later real npm i.
  3. Copy the scripts into the project. ESM resolves import('playwright') from the script's directory and the plugin tree ships no node_modules. Copy skills/reskin/scripts/* (all five files — capture-content.mjs and dom-equality.mjs import source-normalize.mjs as a sibling) byte-identical to stardust/scripts/reskin/, and the master skill's scripts (../stardust/SKILL.md § Setup, step 7): every reskin gate script resolves browser.mjs there at startup and exits 2 without it, even for --help. Run the copies.
  4. Origin collision — if stardust/state.json records a different site.originUrl, stop and ask before mixing sites, per ../extract/SKILL.md § Setup.

Procedure

Phase 1 — INGEST DONOR

The donor's design system is captured separately from the content site, into stardust/canon-source/. Full recipes per donor type in reference/donor-sources.md; summary:

  • Live URL (--donor <url>): invoke $stardust extract <content-url> --design-source <donor-url> — the existing skill, unchanged. It lands in stardust/canon-source/: the donor's pages/, assets/ (screenshots included), _brand-extraction.json, _crawl-log.json, and a descriptive DESIGN.md + DESIGN.json, and stamps state.json.designSource = { url, capturedAt, path } — see ../extract/SKILL.md § Cross-site brand sources.
  • Local prototype dir (--donor-dir <path>): serve the directory on localhost (python3 -m http.server <port> --directory <path>) and run the same --design-source capture path against the localhost origin. Record the real provenance (localhost serve of <path>) in canon-source/_crawl-log.json. Recipe details — page listing, index-less directories, port hygiene — in reference/donor-sources.md § Local prototypes.
  • Figma (--donor-figma): FUTURE. Surface the exact message from § Inputs and stop.

Then author two reskin-owned donor artifacts (contracts in reference/donor-sources.md):

  • stardust/reskin/donor-tokens.json — the curated, probe-able token sheet: palette roles, type ramp, layout metrics, button specs, radii, shadows, motifs — every value a computed-style string the Phase 5 probe can assert verbatim. Curated from canon-source/DESIGN.json + _brand-extraction.json + the raw computed styles; cites the donor page each value came from. On a bounded donor capture (a single donor page, no full --design-source run) there is no DESIGN.json, _brand-extraction.json, or designSource stamp to curate from — the token sheet is authored entirely from raw computed-style sampling of the donor page, a first-class parallel path (reference/donor-sources.md § Two first-class token-sourcing paths).
  • stardust/reskin/donor-modules.md — the enumerated module vocabulary (M1..Mn): one row per donor module with where-seen screenshot evidence and an anatomy description. This is the closed set the Phase 3 mapping brief maps onto.

The pin-one-reference-page rule (hard). Real donors run multiple design systems concurrently — the experiment's donor served radius-4px / 1266px on its homepage and pill-radius / 1080px on older product pages. Consolidating across them produces a chimera no live page ever shipped, and the token probe then asserts against nothing. When donor pages disagree on a token, pin ONE donor reference page per module family, record it in donor-tokens.json (curatedFrom + a note naming the reference page), and demote the other pages to corroboration.

Phase 2 — CONTENT-MODEL CAPTURE

The new capability: a byte-oriented capture of each content page — distinct from extract's design-oriented capture. Run the ported capture script per page:

node stardust/scripts/reskin/capture-content.mjs \
  --url <page-url> \
  --scope '<sel1,sel2!,...>' \
  --normalize stardust/reskin/normalize/<slug>.mjs \
  --out stardust/reskin/content-model/<slug>/

It writes stardust/reskin/content-model/<slug>/content-model.json (full contract in reference/content-model.md): per section-slot — headings with levels, eyebrows and other leftovers, body paragraphs, list items, CTAs with absolute hrefs, ordered visible images (currentSrc + alt), plus the ordered stream (ordered) — the same content as kind-tagged nodes in document order with nesting and separator flags, the render surface Phase 4 consumes; page-level — full SEO metadata (title, description, canonical, OG, Twitter, JSON-LD, lang, favicon), the whitespace-normalized visible text of the scope (the content-gate reference string), and a full-page screenshot.

Two declarations are mandatory per page, because they are the experiment's top two failure modes:

  1. CONTENT-ROOT SCOPE declaration. Naive scoping silently dropped 30% of the experiment page's content — the hero and a banner carousel lived inside <header>, outside the obvious #content root, and byte equality would have "passed" against the incomplete reference. Never trust main or #content blind. Run the scope-discovery procedure (reference/content-model.md § Scope discovery): compare the captured scope text against the whole-body text and the page screenshot, verify the h1 is inside the scope, widen with comma-separated multi-scope selectors until everything visible in the screenshot that isn't declared chrome is in the model. Chrome exclusions (nav, footer) are declared deltas (D1-style), not silent omissions. The capture script prints a coverage line (bodyTextLen / scopeTextLen / h1InScope) to make the check mechanical.
  2. EXECUTABLE NORMALIZATION LEDGER. Cookie-consent chrome removal, carousel de-duplication (hidden slides are absent from innerText; clone slides duplicate it — rotating carousels break byte determinism), and any page-specific cleanup live in a per-page ledger module stardust/reskin/normalize/<slug>.mjs that extends the shared default (scripts/source-normalize.mjs). The same ledger file is passed verbatim to the capture and to every gate (--normalize), so the gate measures exactly the normalization the capture declared. The ledger is code, not prose. Format in reference/content-model.md § Normalization ledger.

Phase 3 — MAPPING BRIEF

Author stardust/reskin/mapping.md — the cross-origin mapping brief. Full contract and entry schema in reference/mapping-brief.md. Per every content slot in the content model:

  • assigned donor module id (from donor-modules.md's closed vocabulary) + a one-line rationale grounded in slot anatomy vs module anatomy;
  • status ∈ {mapped, new-module, chrome, carried-invisible} — the last for sr-only/visually-hidden content inside the byte scope (carried verbatim into an equivalent hidden element, no donor module; reference/mapping-brief.md § Status semantics).

Gates before any rendering:

  • ≥ 80% of content slots mapped onto named donor modules. Below that, the donor vocabulary doesn't cover this content — stop and surface (see § Stop conditions).
  • Every new-module entry is explicitly composed from donor tokens (name the tokens it borrows: input spec + primary button spec, etc.) and listed in the brief's stats block. New modules are never silently improvised mid-render.
  • Chrome swaps documented — nav/footer replaced by donor chrome carrying the source's links is a declared delta, excluded from the content-gate scope.
  • Casing / text-transform policy declared. The donor may render eyebrows uppercase (or the source may — Chrome's innerText reflects text-transform, so captured text is rendered-case). The underlying text stays byte-faithful; casing is applied via CSS text-transform only, never by editing the string. Policy details in reference/mapping-brief.md § Casing policy.

Composite source sections (one wrapper div holding two logical regions) are split into atomic slots in the brief — section ≠ slot.

Phase 4 — PROGRAMMATIC RENDER

The decisive validated rule: the page is GENERATED from content-model.json — never retyped by hand. Write a renderer script per archetype (stardust/reskin/renderers/<archetype>.mjs, modeled on the experiment's render-reskin.mjs) that:

  • reads the page's content-model.json and interpolates every visible string, href, and image URL from the model (HTML-escaped) — if a string appears in the output HTML but not in the model, the renderer is wrong;
  • takes each slot's structure from the ordered stream (sections[].ordered, reference/content-model.md § The ordered stream): kind-tagged nodes in document order, nesting preserved (a CTA wrapping its heading and vice versa), sep flags marking zero-separator inline joins. The stream is innerText-consistent by construction (its text nodes are sliced from the parent's rendered innerText — the byte-gate basis), so emitting it verbatim is safe. Emit nodes in stream order; emit sep: "" neighbours with no whitespace between them (inline); never reorder, and never reconstruct order or separators from visibleText — the first field run did exactly that (per-type arrays matched greedily against visibleText as an oracle) and burned three debug rounds on duplicate identical strings, both directions of CTA/container nesting, and zero-separator inline li runs, all of which the stream now captures structurally;
  • renders formControl nodes as equivalent controls, not text: a <select> carrying the captured option texts verbatim, in order; inputs/textareas carrying value/placeholder — restyled with donor tokens (the new-module composition rules apply), never flattened to prose and never dropped. A select's option text is part of the source's innerText, so dropping the control fails the byte gate with nothing structured to render from (reference/content-model.md § Slot taxonomy, formControls);
  • carries the metadata block verbatim into <head> (title, description, canonical, OG, Twitter, JSON-LD — including source garbage like broken JSON-LD URLs: fidelity over repair; flag such items for the human in the run report, never silently fix or silently keep);
  • takes its surface exclusively from donor-tokens.json (emitted as CSS custom properties) + the donor module patterns assigned in mapping.md. Use the rendered-page conventions the Phase 5 probe asserts against: content in <main>, .container for the measure, .btn for the donor primary button (reference/gates.md § Rendered-page conventions);
  • writes stardust/reskin/pages/<slug>.html, self-contained.

Renderers may parse a single node's text apart (split a list-item row into kicker/date/title) but must fail loudly (throw) when a parse doesn't reproduce the node's text — a silent partial parse is a silent content drop. A slot whose orderedVerified is false is inspected before rendering, never trusted blind; when inspection shows stream text genuinely absent from the slot's visibleText, the sanctioned fallback is to drop that text before rendering and record the drop in the model's provenance — filtering ghosts against visibleText is the documented resolution, distinct from the forbidden order-reconstruction move (reference/content-model.md § When orderedVerified is false).

Phase 5 — GATES

Three gate families per page; commands, pass bars, tolerances, and failure modes in reference/gates.md. Serve or file://-address the rendered page and run:

(a) CONTENT GATE — all three must pass:

node stardust/scripts/reskin/dom-equality.mjs \
  --source <page-url> --source-scope '<declared scope>' \
  --normalize stardust/reskin/normalize/<slug>.mjs \
  --rendered stardust/reskin/pages/<slug>.html --rendered-scope main \
  --report stardust/reskin/reports/<slug>-content-gate.md
node stardust/scripts/reskin/slot-coverage.mjs \
  --model stardust/reskin/content-model/<slug>/content-model.json \
  --rendered stardust/reskin/pages/<slug>.html \
  --report stardust/reskin/reports/<slug>-slot-coverage.md

dom-equality.mjs (vendored + adapted from github.com/aemcoder/skills, Apache-2.0) gates on whitespace-normalized visible-text byte equality and the ordered, URL-normalized visible-image set; element count and tag sequence are reported but informational. slot-coverage.mjs additionally proves every model slot present (slot text substring, every CTA as a (text, absolute-href) pair, every image) and asserts metadata carry-over field by field.

(b) DESIGN-ADOPTION GATE:

node stardust/scripts/reskin/donor-probe.mjs \
  --tokens stardust/reskin/donor-tokens.json \
  --rendered stardust/reskin/pages/<slug>.html \
  --report stardust/reskin/reports/<slug>-donor-probe.md

Computed-style assertions of donor token values on the rendered page — bg/fg, font-family token string, display weight, button spec, container width, band palette, section rhythm. Tolerances (exact for colors/radius/family; ±2px button padding; ±20px container; ±16px section rhythm) documented in reference/gates.md § Tolerances. Then the side-by-side judgment: open the rendered page next to the donor reference-page screenshots (canon-source/assets/screenshots/) and judge adoption with your eyes — the probe proves tokens, the eyeball proves the page reads as the donor. Record the verdict.

(c) Sanity — no horizontal overflow at 1440 and 360 (donor-probe runs this automatically; --widths to override).

One fix iteration per gate family — one for the content gate, one for design-adoption/sanity. On a failure in a family, fix once, re-run all gates (a fix for one gate can break another). Residual failures after a family's iteration is spent are logged in stardust/reskin/ledger.json under the page's residuals[] — never silently absorbed, never looped on indefinitely. (Both field runs support the budget: the validation experiment spent one iteration on 360px chrome; the smoke run spent exactly one per family — a content-side separator emission fix and a sanity-side 360px chrome fix. A single shared iteration would have forced a false residual; per-family keeps the loop bounded without absorbing real failures.)

Phase 6 — HANDOFF

Reskin owns the archetype pages; scale and shipping are the existing pipeline, unchanged:

  • Scale via the stardust migrate skill (../migrate/SKILL.md) with the donor-pinned target (the state.json.designSource stamp Phase 1 wrote is exactly what direct/migrate read for donor pinning; a bounded donor capture wrote no stamp — record the donor origin in the handoff instead, reference/donor-sources.md § Two first-class token-sourcing paths). Same-type sibling pages render at the sibling tier against the gated archetype. Content rules are the ones reskin already enforces — ../migrate/reference/content-preservation.md is inherited wholesale.
  • Ship via the stardust deploy and rollout skills, unchanged. Blocks written for donor modules obey the Experience Workspace editability contract (deploy SKILL.md § 8, EW1–EW10) and pass the EW gate (block-roundtrip --ew) before they are done.

Reskin writes its own state under stardust/reskin/ — ledger.json holds per-page status (captured → mapped → rendered → gated), gate results, and residuals. It makes no changes to the core state machine (../stardust/reference/state-machine.md); the only state.json touch is the designSource stamp that extract itself writes in Phase 1.

What reskin never does

  • No content rewriting or summarizing. Not headlines, not body, not CTA labels, not casing-by-editing. Faithful ≠ clean: source garbage is carried verbatim and flagged, not fixed.
  • No invented sections. Every rendered slot traces to a content-model slot; every module traces to donor-modules.md or an explicit new-module entry in mapping.md.
  • No donor-token drift. No colors, fonts, radii, or spacing outside donor-tokens.json. Licensed donor fonts are adopted as the family token string with local fallback, never rebundled.
  • No silent slot drops. Anything excluded from the gate scope is a declared chrome delta or a ledger normalization — declared in mapping.md, executable in the normalize module.

Stop conditions

  • Donor capture fails (bot-block past the headed fallback, prototypes dir unservable) — surface extract's error verbatim.
  • Mapping ratio < 80% — the donor vocabulary can't carry this content. Ask: widen the donor capture (more donor pages → more modules) or accept a larger explicit new-module list.
  • Scope undecidable — the content page's visible content cannot be covered by any selector set (heavy shadow-DOM, iframe-embedded content). Surface with the screenshot evidence.
  • Figma donor requested — future scope; exact message in § Inputs.

Outputs

PathPurpose
stardust/canon-source/Donor capture + descriptive DESIGN.md/json (extract --design-source, unchanged)
stardust/reskin/donor-tokens.jsonCurated probe-able token sheet, pinned to one reference page
stardust/reskin/donor-modules.mdEnumerated donor module vocabulary (M1..Mn) with screenshot evidence
stardust/reskin/content-model/<slug>/content-model.jsonByte-oriented per-page content model (+ source screenshot)
stardust/reskin/normalize/<slug>.mjsPer-page executable normalization ledger (shared capture ↔ gates)
stardust/reskin/mapping.mdThe mapping brief: every slot → donor module, status, rationale
stardust/reskin/renderers/<archetype>.mjsProgrammatic renderers (model in, HTML out)
stardust/reskin/pages/<slug>.htmlRendered reskin pages
stardust/reskin/reports/Per-page gate reports + screenshots
stardust/reskin/ledger.jsonPer-page status, gate results, residuals
stardust/scripts/reskin/Project-local copies of the five skill scripts

References

  • reference/donor-sources.md — the three donor types and their capture recipes; pin-one-reference-page; donor-tokens.json and donor-modules.md contracts; the Figma future contract.
  • reference/content-model.md — the capture contract: slot taxonomy, the ordered stream (the render surface), scope-discovery procedure, normalization ledger format, provenance.
  • reference/mapping-brief.md — entry schema, the ≥80% gate, new-module composition rules, casing policy.
  • reference/gates.md — both gates' commands, pass bars, tolerances, failure modes, residual logging.
  • ../extract/SKILL.md § Cross-site brand sources — the --design-source donor-capture path Phase 1 delegates to.
  • ../migrate/reference/content-preservation.md — the content rules reskin inherits (and tightens to byte level).
  • ../diff/SKILL.md — the pixel + structural probes; reuse them as a supplementary build-side check after Phase 6 deploy, --profile eds.

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. 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). Flow guard: stardust/state.json without flow on a migration ask → do not roll out; print the master's two-flow table and hand back to its routing (skills/stardust/reference/state-machine.md § Flow keys).
  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. Gated-archetype precondition (flow: replica). Read stardust/replica/progress.json: a page type may ship only when its archetype has a gate result at every configured breakpoint that is pass: true, or over the bar with every residual carrying a cause (skills/replica/reference/source-fidelity-gate.md § Residual logging format — a documented residual is a pass with an asterisk). A page type whose archetype was never gated, or is over the bar with no residual entries, is blocked: list it with its archetype slug and the command to gate it ($stardust replica <archetype>), and neither fan out its siblings nor POST /live/ any of them. Accepting logged residuals under hands-off is not a bypass for an ungated archetype. Thresholds are the gate's, unchanged. (Recorded: 2,207 pages published at 24–28 % diff from an archetype that never passed; a 3,366-page re-import after a random review found what a gate would have.)
  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 (never a pinned row: replica's first page first). 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, widgets + chrome) into the distinct set, assigns each a canonical edsBlockName (kebab, reserved-class guarded) and records usedByPages / instanceCount. Chrome (header/nav/footer) is kind: chrome → site-wide authored documents (/nav, /footer). A widget (kind: widget, from the sidecar's widgets[] {id, href}) needs no document rows: its code ships at widgets/<path>/<name>.html and the page carries one /widgets/…html link (#133). In archetypes-only mode the archetype sidecars determine the block set; content-pending pages add none. A module that maps to EDS default content (title, text, image, button, separator) needs no block: record it update-coverage.mjs --block <id> --status converted --eds-name default-content; such a row is never counted pending, whatever its status.
  • 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 deploy's Step-7 brief input. content-pending pages are always convert: [].

Extending a delivered site: audit blocks/ and widgets/ first — a "new template" is usually a new composition of them (reference/operational-learnings.md).

Phase B2 — Dynamic surface (PRE-IMPORT GATE — verify the inventory)

Before Phase C. stardust/dynamic-features.md (from prepare-migration 4.5 or replica Phase 2) must exist with a disposition on every row; verify it against fresh evidence here — dynamics-detect.mjs --from-state … --reach stardust/current and dynamics-plan.mjs --target-origin <live host> --migrated stardust/migrated (host-bound APIs, rows the capture already delivered). New evidence → new rows. The listings contract (per-type <meta> fields + helix-query.yaml) is emitted by Phase C's deploy brief per page: retrofitting metadata across published pages is a second migration. Missing inventory → run the stardust dynamics skill Phases 1–3 now. Contract: skills/dynamics/reference/triage.md, reference/listings.md.

Phase C — Deliver the site (drive deploy per page, per the plan)

Blocked on Phase B2 — author each page's metadata contract into its metadata block during delivery, so the indexes are rich at import time.

Walk plan.json.steps in order (representative pages first). For each page:

  1. Convert + push the migrated HTML (source.migratedHtml) to AEM via the deploy methodology. Pass the plan step into deploy's brief: create only the blocks in convert; for each block in reuse, REUSE the existing block by its edsBlockName (do not recreate). The brief MUST carry the Experience Workspace editability contract (deploy SKILL.md § 8, EW1–EW10): every converted block moves authored elements into wrappers (never rebuilds from text) and passes the EW gate (block-roundtrip --ew) before it counts as delivered — a brief without it skipped the contract on 27/27 blocks of a real site. The brief also carries the archetype's captureState[].restoreAtDelivery list (replica progress.json): a freeze the gate needed (video at frame 0, carousel on slide 1) is a behaviour to deliver, never the spec (../replica/reference/recreation-procedure.md § Carousels).

    Deploy first, judge on the preview origin. The local harness (build-harness.mjs → qa-gate.mjs, block-roundtrip.mjs --ew) serves the structural asserts only; every pixel or visual judgment — replica's source-fidelity gate, the header/footer crop-compare bands, the deployed eyeball — runs against the page's preview URL after PUT → preview, never against the harness before the first PUT (deploy SKILL.md § Local QA before deploy, § Step 10). A recorded delivery session iterated CSS against a local harness pixel diff for its whole budget and delivered no page.

    Chrome and fragment documents carry Robots | noindex. content/nav.html, content/footer.html, every per-locale nav-* / footer-* document and any locale shell that is not a page get one more metadata block row at write time — <div><div>Robots</div><div>noindex</div></div> (renders <meta name="robots" content="noindex">). Without it the platform's index of published documents, and the /sitemap.xml it serves, list them as pages: a recorded hands-off run served 58 sitemap urls for a 36-page site (every page plus 22 chrome documents). Phase D verifies the served sitemap.

    content-pending pages (archetypes-only): no migrated HTML — skip the document push entirely (no shell/placeholder), record content-pending, surface as "awaiting content track." Their block code is already deployed via the archetype.

  2. Static contract lint (pre-PUT, deterministic). Before the push, run the delivery-contract linter — it catches the cheap, deterministic failures (wrapper, one-CTA-per-<p>, trailing-slash, path-safety, /img/ src, about:error) offline so a broken page never reaches preview. Mechanics in reference/delivery-lint.md. A P0/P1 blocks the PUT.

    node skills/rollout/scripts/delivery-lint.mjs --file <html> --path </da/path>
    node skills/rollout/scripts/media-reconcile.mjs --file <html> --deploy-host <branch>--<repo>--<owner>.aem.live [--media-ledger <file>] [--apply]
    

    media-reconcile resolves every non-hosted image on the network and decides optimize/keep/rewrite/omit (skills/migrate/reference/media-reconciliation.md) — the authoritative form of the image-fidelity gate below. A content-host URL (content.da.live) is the hosted decision instead: checked offline against the media ledger (--media-ledger <file>, auto-detected), never fetched anonymously (401 by design); missing from the ledger fails the gate.

  3. Run the delivery gates before flipping a page to deployed. Each is a one-line rule here; mechanics + helpers in reference/delivery-gates.md:

    • Source-fidelity — don't add sections the source lacks; never fabricate facts. node skills/rollout/scripts/section-fidelity.mjs --file <html> --source <url> (a static outline check on the authored file — not replica's pixel source-fidelity gate, which runs on the published origin after deployed)
    • Image-fidelity — every authored <img> src must return 200 or be omitted; never ship <img src="about:error">. Run media-reconcile.mjs (step 2).
    • Path-safety — reference/delivery-gates.md § Gate 3; record original→normalized in stardust/redirects.tsv. (delivery-lint flags violations.)
    • Source-content hygiene — skip dead source URLs; author bodyless/PDF-only sources thin and faithful (tier thin, skills/migrate/reference/fidelity-tiers.md), don't pad with invented prose.
    • Fidelity tier declared — record each page's fidelityTier (archetype/sibling/thin) so coverage shows what was craft-gated vs cloned (skills/migrate/reference/fidelity-tiers.md).
  4. Record outcomes with the state-writer (never hand-edit the ledger):

    node skills/rollout/scripts/update-coverage.mjs <slug> --status converting
    node skills/rollout/scripts/update-coverage.mjs --block <id> --status converted --eds-name <name>
    node skills/rollout/scripts/update-coverage.mjs --block <id> --status converted --eds-name default-content   # maps to default content, no block
    node skills/rollout/scripts/update-coverage.mjs <slug> --status deployed --url <branch-preview-url>
    node skills/rollout/scripts/update-coverage.mjs <slug> --status content-pending   # no document push
    

    Publish in the loop (PUT → preview → live), don't stop at preview — any query-index (Phase D2) builds from the live tree, so a preview-only delivery leaves indexes empty. On failure: --status failed --error "<reason>" and continue (one page's failure never aborts the rollout).

Foundation-first gate (hard block, once per rollout). When the FIRST archetype page flips to deployed, stop and prove the foundation before authoring any second page: run the stardust diff skill (both probes) against its prototype, plus computed-style invariants in a headless render — grid containers compute display: grid (not stacked single-column), sections are full-bleed where the design says so, and the CTA/button classes are actually styled (per stardust/runtime-contract.json, skills/deploy/SKILL.md § Runtime-detection probe). deployed means after PUT + preview: the gate's probes run against the page's preview URL, never a local harness — a pre-deploy harness pixel diff is NOT this gate. A wrong runtime assumption (block wrapper class, button classes) is silent and sitewide — typography still looks fine while every grid stacks. This one gate is the difference between fixing one page and rebuilding every template. The same gate runs qa.mjs --checks metadata against the origin: favicon-default means the site's icon never shipped (deploy Step 3 § Favicon) — recorded first passes served the boilerplate icon while /favicon.ico answered 200. Archetype first, per template (#126): the template's archetype is deployed and passes its full gate row on the preview URL (gate-all.mjs --only, cap 3 fix rounds) before any of its siblings is rendered or converted — the recorded unit C-archetype (handoff contract § 3, row C).

Execution model: waves. Deliver in waves of parallel author-only agents — each agent curls its source pages and writes files only, never deploys or edits blocks — template clusters concurrently (non-overlapping pages), representative-first so blocks exist to be reused; then a central deploy per page; then background batches with a per-page OK/FAIL ledger, re-driving FAILs only. For clusters of 6–20+ siblings, the full flow is reference/delivery-gates.md § Batched delivery (it also names the one variant where cluster agents deploy themselves — replica's Phase 5 fan-out, per-cluster deploy ledgers, lock-safe shared ledgers). The central deploy step should run the bundled, resumable driver rather than a serial loop: node skills/deploy/scripts/deploy-batch.mjs --org <org> --repo <repo> --branch <branch> --content <dir> (concurrency pool, persistent ledger that skips already-live pages, retry/backoff, append-only log, delivered-.plain.html check). The driver and every batch run in the background; its log and ledger are the progress file. Check them at most every 4 minutes and never with a fixed sleep of 5 minutes or more (the prompt-cache window) — the master skill's wait discipline; recorded batch waits of 9–10 minutes re-wrote a ~650k prefix each time. After a transient blip, re-run the same command — it re-drives only the FAILs. Then reconcile the ledger into coverage with update-coverage.mjs. Foundation first: lint AND commit styles.css, header/footer CSS and the contract file BEFORE the first agent spawns; no token or custom-property rename after fan-out (a recorded rename under three running agents cost seven coordination messages). Disjoint clusters spawn concurrently — a wave waits only on a real dependency (a recorded second wave idled 14 min behind an unrelated first). Every tool call stays under 4 minutes, the main agent's included (the prompt cache holds 5; calls of 5.2 and 6.6 min re-wrote the whole context, and so did one 338 s foreground turn on the main agent that ran a pixel loop beside a deploy-batch start + wait): a long instrument (gate rounds, pixel loops, Playwright captures, deploy batches) goes through run-bg.mjs start, and wait is the NEXT tool call — it returns within its --max (100 s by default); never two long instruments as parallel tool calls in one turn, never two waits in one command.

Phase D — Site assembly (whole-site artifacts)

node skills/rollout/scripts/assemble.mjs   # → rollout/site/{sitemap.xml,robots.txt,manifest.json} — the EXPECTED set
node skills/rollout/scripts/assemble.mjs --verify-origin https://<branch>--<repo>--<owner>.aem.live   # vs the SERVED /sitemap.xml; exit 1 on a mismatch

Generates site-wide artifacts: sitemap.xml + robots.txt from delivered paths, and a fragments manifest mapping chrome blocks to the authored chrome documents (content/nav.html, content/footer.html) with their canon/*.html source (deploy authors + deploys the documents through the normal content chain — they MUST be published or the chrome 404s sitewide).

The assembled sitemap is never the served one. stardust/rollout/ is in .hlxignore, so site/sitemap.xml is a local artifact — the EXPECTED url set. The platform serves its own /sitemap.xml, built from its index of every published document, chrome documents included unless each carries Robots | noindex (Phase C). A recorded hands-off run read the local file, reported "sitemap 36 urls" and shipped a served sitemap of 58 (36 pages + 22 nav / footer documents). Two remedies, the first required:

  • Authoring: every chrome/fragment document — /nav, /footer, per-locale nav-* / footer-*, locale shells that are not pages — carries the metadata row Robots | noindex; a document already published without it is re-authored and re-published (preview → live) before the check below.
  • Configuration (alternative, additive): when the code branch is writable, a helix-sitemap.yaml at the project root (sitemaps.default.include: ['/**'], exclude: ['/nav', '/footer', '/**/nav*', '/**/footer*', '/fragments/**'], properties.lastmod: lastModified) keeps chrome out of the served sitemap even when a document lacks the row; the same exclude globs go into helix-query.yaml (Phase D2) so the index never carries them either.

Verify the SERVED sitemap, never the local file. assemble.mjs --verify-origin <live-origin> compares the served <loc> paths with the coverage rows and exits 1 on any difference. An extra path is a chrome document without noindex or a page built outside the migrated tree with no coverage row (update-coverage.mjs --new, Phase D2); a missing path is a page not published live. Re-run after the fix until it exits 0. The D-site ledger end line names the SERVED count, never the assembled one — e.g. --detail "sitemap served 36 = assembled 36; redirects wired; / 200".

DA library (#160). Without a library tab in its site config, a migrated site shows authors an inherited or empty block library, never the blocks it shipped. Run node skills/rollout/scripts/da-library.mjs (one document per block variant and per template, the sheets, and only the Blocks / Templates config rows) whenever a block, variant or template ships — in archetypes-only mode once the archetypes are delivered.

D-site checklist (all before the D-site end line): assemble.mjs --verify-origin exits 0 · every chrome document carries Robots | noindex and is published · the redirects sheet is published (below) · da-library.mjs exits 0 · curl -sIL <origin>/ ends in 200.

Redirects: if Phase C's path-safety gate emitted stardust/redirects.tsv, wire it into the EDS redirects mechanism here so original inbound URLs don't 404 — the redirects sheet at the content root (on a DA-backed site /redirects.json, columns Source / Destination; PUT through the admin API, then preview + publish it like a page). The root MUST answer: when the source root serves a page, deliver it as the root index document (the pipeline serves / from it — /index ≡ /; never also a / Source row, which would shadow it); only when the source root itself redirects (curl -sI <source-url>, follow the Location chain) does the sheet carry / and /index.html → the landing page. Then verify curl -sIL https://<branch>--<repo>--<owner>.aem.page/ ends in 200: a 404 on / fails the whole delivery after every phase has passed (recorded — a sheet with a row for every .html path and none for /).

Phase D2 — Dynamic features (dynamics Phases 4–5)

Implement the plan's reproducibility-self rows from the pattern catalogue (skills/dynamics/reference/patterns.md — index-backed listings and search, modal loader, media as URL, client-compute blocks, owner-facing tag config disabled, off-origin data tiers, sheet sync); emit every other row as one owner decision batch and ship its interim tier. Query indexes build from the published tree — publish per page in Phase C, then poll total. Each feature ends with a parity row in stardust/dynamics/parity.json carrying a replayable check; dynamics-check.mjs --origin <live host> runs before Phase H and the report carries its table. Failed replays are dynamic-gap / api-dependency learnings, never silent passes. Index-backed listings ship document-first (authored rows, index for non-text and top-up — dynamics/reference/listings.md); the deploy AI-readability gate runs on every listing page.

A missing query index is a code-branch gap, not a configuration-service problem. /query-index.json answering 404 means the project ships no helix-query.yaml. Author it at the code branch root (a spec's knowledge/helix-query.yaml is the draft), publish the pages LIVE and poll: skills/dynamics/reference/listings.md § Getting an index at all. A 403 from the configuration service is expected; only an unwritable code branch ships the sheet-backed interim index (recorded interim, decision named).

Search parity is count + titles, not presence. The results block ranks title matches first and consults description, then body text, only while fewer than N title hits exist (N = the source's visible count for the probe term), dedupes by title + description and caps the typeahead at N — N, the top titles and one known hit are read from the SOURCE during detect and recorded on the search-query check (expectCount, expectTitles, expectIncludes); dynamics-check.mjs fails the check on a count mismatch (skills/dynamics/reference/patterns.md § search-index-backed).

Pages built here enter coverage. A results page (or any page without a capture) has no inventory row, so it stays outside verify.mjs --all, optimize.mjs and the assembled sitemap unless registered:

node skills/rollout/scripts/update-coverage.mjs --new search --path /search --template search --origin dynamics --title "Search"

then record its status like any page. inventory.mjs keeps such rows on a re-run (the origin marker in source.migratedHtml identifies them; status untouched), so the line runs once.

Phase D3 — Multilingual (per-language trees) — optional

When the source has language trees (/fr/…, /en/…), add them as parallel content trees that REUSE the same block library — only authored content and a little wiring change (language-routed chrome documents, per-language indexes, per-language path-safety). See reference/multilingual.md.

Phase E — Full-site verify

node skills/rollout/scripts/verify.mjs            # uses rollout.json site.liveHost
# or: --base <url>   (explicit host)   |   --root <dir>   (offline, against a local export)

For every delivered page, verify confirms HTTP 200, no about:error (deploy #75), and that every internal href="/…" resolves to a known delivered path — then flips each page to verified or failed. Exits non-zero if any page failed.

Headless render check (per template). A 200 .plain.html can still render blank — decoration failures (missing script, wrong block wrapper class, 404 chrome) are invisible to a text check. On the FIRST delivered page of each template (home included), load the live URL in a headless browser and assert decoration ran: the runtime's body.appear class is set (per stardust/runtime-contract.json), main .section count > 0, zero pageerror events, zero broken images, and every restoreAtDelivery entry of the template's archetype holds: an autoplay <video> at least a quarter visible is playing (!paused, currentTime advancing — not merely present), a rotating carousel advances without interaction.

Published-origin gate over the roster (#125). verify proves the pages render; the DELIVERY verdict is replica's gate-all.mjs (pixel + height + clip + content per deployed page, ../replica/reference/source-fidelity-gate.md § The all-pages published-origin gate). update-coverage.mjs --gate stardust/replica/gates/all-<w>/summary.json writes each row into delivery.gate and flips a failing page to failed; verify never marks it verified while the gate fails — completion derives from one place, never from the pixel number alone. In C-deliver the roster run is the recorded unit gate-all (handoff contract § 3, row C).

Phase E2 — Link-audit completeness

verify.mjs checks the links on delivered pages; this phase closes the set of link targets a roster-driven batch misses (reference/operational-learnings.md § Two verify checks):

  • Nav/footer/landing targets are NOT archetype siblings. Enumerate every href in the /nav + /footer documents plus each section's index/landing page and confirm each is deployed + published + verified — and that the chrome documents THEMSELVES are published — otherwise they get committed but never published, their links 404, and the dashboard still reads 100%.
  • Localize source-site bounce links with the deploy stage, not by hand: node skills/deploy/scripts/localize-links.mjs --source-host <live-host> --content content --redirects stardust/redirects.tsv rewrites every source-host href whose path exists in the content tree (header/footer/home included) to the canonical root-relative form and lists the ones it kept absolute (no local page — a bounce beats a 404). Re-run over the WHOLE tree after every wave: earlier waves' pages gain newly valid targets only when a later wave ships them. --check is the gate (exit 2 = localizable links remain).
  • Link every internal page at its served URL (deploy/scripts/eds-path.mjs): no .html, a slash only on a folder index (/x/). .html and a leaf's slash 404 while .plain.html passes. Repoint .html links with no local page at the working source URL.
  • The audit GETs each href against the LIVE tree: the ledger alone misses slash and case defects.
  • Targets missing from the capture. Two cases, both recorded in direction.md as a named decision with the list: a target the direction's caps meant to include is a CAPTURE GAP — crawl it first (capture → migrate → gate, never authored from a live read) and deliver when the gap is ≤ 12 pages, else repoint to the source site and list it as scope debt; a target outside the declared caps is SCOPE EXTENSION — repoint regardless of count. External targets: repoint to the source site; other-locale targets: repoint ONLY when that locale root was never captured. Any captured page — a stardust/state.json row, including duplicateOf shells and locale roots — is in scope and is delivered, never repointed (the ≤ 12 rule is for UNcaptured pages; a recorded run dropped ten captured locale roots by citing it). Never leave a 404 (a recorded audit found 10 uncaptured in-scope pages — delivering them was the right call).

Phase F — Optimize: multi-source audit + gate (delivery quality)

The in-flow quality gate. optimize aggregates findings from existing audit skills into one ledger (optimize/findings.json + optimize/scorecard.json), tags each by fixability, and gates the rollout. Sources (full mapping in reference/audit-sources.md):

  1. rollout:baseline — built-in deterministic detectors:
    node skills/rollout/scripts/optimize.mjs        # uses rollout.json site.liveHost
    # or: --base <url> | --root <dir> | --slug <s> | --all
    
  2. impeccable:critique + impeccable:audit — design quality + a11y/perf.
  3. The marketing SEO skills — seo-audit, schema, ai-seo, site-architecture.
  4. stardust:tensions — mechanical design tensions from stardust/current/brand-review.html.

Source parity. When the extract capture exists (stardust/current/pages/<slug>.json and its rendered sidecar; --current <dir> to point elsewhere), baseline findings the SOURCE shares — the same <title>, no description on the source either, no JSON-LD on the source either, the same title shared by the same pages — are tagged fixability: out-of-scope with the evidence prefix source parity: and listed in their own report section: informational, excluded from the health score and the open P1/P2/P3 counts, never gated, never auto-fixed. A recorded hands-off run accepted 63 such findings by hand. Everything else routes as before (reference/checks.md § Source parity).

Normalize each source's findings into the ledger with the writer:

node skills/rollout/scripts/findings.mjs record \
  --source marketing:seo-audit --layer seo --check thin-content \
  --severity P2 --fixability platform-migration \
  --scope-ids blog/post --evidence "…" --recommend "…"
node skills/rollout/scripts/findings.mjs resolve <id> --status accepted --note "…"

All sources share one id space, dedup, scorecard, and the detect → fix → verify loop: re-running a source resolves its own gone findings; a regressed fixed finding re-opens; human accepted/wontfix are preserved. Fixability routing: platform-migration → autofix / re-deploy; design-pass → upstream (surface only); out-of-scope → informational. The gate exits non-zero if any open P1 is in scope — a page is delivery-clean only when verify passes and the ledger has no open P1.

At ~1k-page scale: a head.html-level fix needs a site-wide republish to land and flip its per-page findings; the optimize gate only audits pages in coverage/pages.json; and faithfully migrated parallel source trees produce legitimate duplicate-title findings (a canonical decision, not a bug). See reference/operational-learnings.md.

The judgment layers (brand-tensions, design-ux, content-conversion) are scored null until populated by the impeccable/tensions sources — the scorecard shows not-assessed rather than faking a score.

Phase G — AEM autofix (close the loop)

node skills/rollout/scripts/autofix-aem.mjs --project <eds-root>   # [--dry-run] [--slug s] [--check c]

The platform autofix engine (AEM-EDS, v1 — aggressive). For every open finding whose check has a registered EDS fixer, it edits the EDS project files, logs the change on finding.autofix, and stages the finding in-progress:

  • deterministic — eds-fix-h1 (exactly one <h1>), sitemap (re-assemble).
  • content-draft (logged for review) — eds-metadata-title / eds-metadata-description, eds-alt-draft, eds-disambiguate-title.
  • manual (prepares guidance/payload) — eds-jsonld (use marketing:schema), eds-canonical, eds-landmark-main.

Use --dry-run first. After applying, re-deploy the edited pages, then re-run verify + optimize — staged findings flip to fixed. design-pass findings are surfaced, not auto-fixed.

Phase H — Report

Include the dynamic parity table (stardust/qa/dynamics-report.md, from Phase D2) next to the delivery ledger: per feature its class, reach, status, owner decision and the replayed check — so the report is honest about what the site does, not only what it shows.

Read rollout.json.lastRun + optimize/scorecard.json (or re-run inventory.mjs):

rollout — <site> → aem-eds
==================================================
Pages       <N> total · <v> verified · <d> deployed · <p> pending · <cp> content-pending · <s> stale
Templates   <T> (per-template delivered/total)
Blocks      <B> total · <c> converted · <p> pending
Quality     health <H>/100 · open P1 <n> / P2 <n> / P3 <n>
Pixel table prototypes <p>/<P> PASS · deployed <d>/<D> PASS (pixel-only <x>/<D>) — gates/{prototypes,all}-1440/summary.md
To deliver  <list of remaining slugs>
Content     <cp> pages awaiting content track (block code deployed, document not yet pushed)

Surface pending/stale/failed as the explicit "what's missing" list. The pixel-table line comes from the two summary.json totals (pass, pixelOnlyPass, pages); a deployed page missing from all-1440/summary.json is ungated and belongs in that list (#125). content-pending pages are listed separately — not failures; their block code is live and they advance to pending automatically when migrate emits their HTML and inventory is re-run.

Also write/refresh stardust/learnings.md per skills/stardust/reference/learnings.md: one entry per failure class this run surfaced (evidence, proposed skill + section to change, status: pending). plugin maintainers harvest pending entries into skill diffs — this is how a run's hard-won fixes stop being re-learned.

Phase I — Dashboard

node skills/rollout/scripts/dashboard.mjs    # → dashboard/index.html + data.json

A self-contained, no-external-JS dashboard rendered in the project's design identity (brand tokens read from a migrated page's :root). Centerpiece: a page tree of every identified page, nested by URL path, each node colour-coded by the most-advanced lifecycle stage it reached:

identified → prototyped → deployed → optimised

The stage spans state.json (rostered/extracted/directed → identified, prototyped/approved/migrated → prototyped), rollout coverage (deployed/verified → deployed), and optimize (optimised = verified and no open findings). A content-pending sibling stays at identified (it's in the ledger so delivery can be tracked, but has no designed document yet). Legend counts are cumulative. Template archetypes are badged T; a page with open findings shows a red count. Also a templates table + the quality scorecard. dashboard/data.json is the inspectable snapshot — regenerate at every iteration boundary. (state.json is read-only and optional.)

Done is one verdict: the rollout is complete when node skills/rollout/scripts/done-check.mjs exits 0; otherwise it prints one gap per line.

Inputs

InputSourceUsed for
stardust/migrated/*.htmlmigratethe pages to deliver (read-only)
stardust/migrated/**/_meta.jsonmigratetemplateId (template; an archetype with template: null groups under its own slug; else type), blocks (modules — the inventory report counts sidecars with an empty list: fill them before Phase B), widgets (widgets[] {id, href}), title
stardust/state.jsonstardust core(archetypes-only mode) full page roster + type for pages not yet migrated
stardust/rollout/rollout.jsonrollout / userDA target coordinates

Outputs

PathPurpose
stardust/rollout/coverage/pages.jsonper-page delivery ledger (schema: schemas/rollout-pages.schema.json)
stardust/rollout/coverage/templates.jsontemplate grouping + roll-ups (schema: schemas/rollout-templates.schema.json)
stardust/rollout/coverage/blocks.jsonthe block dedup ledger + EDS mapping (schema: schemas/rollout-blocks.schema.json)
stardust/rollout/plan.jsondedup-driven delivery order + per-page convert/reuse briefs
stardust/rollout/optimize/findings.jsonmulti-source quality findings ledger (schema: schemas/rollout-findings.schema.json)
stardust/rollout/optimize/scorecard.jsonquality scorecard + history (schema: schemas/rollout-scorecard.schema.json)
stardust/rollout/rollout.jsonconfig + lastRun summary (schema: schemas/rollout-config.schema.json)
stardust/rollout/site/{sitemap.xml,robots.txt,manifest.json}site-level assembly artifacts
stardust/rollout/dashboard/{index.html,data.json}self-contained progress dashboard + snapshot
edits to the EDS project (content/**, styles/)applied by autofix-aem (the only files rollout writes outside stardust/rollout/)
the delivered EDS siteproduced by deploy per page (blocks/, widgets/, content/, fragments — owned by deploy)

rollout writes under stardust/rollout/ and — only via autofix-aem — to the EDS project it delivers to. It never modifies the agnostic core, state.json, or migrated/ — those are read-only inputs.

Dependencies (audit sources — referenced, not vendored)

optimize orchestrates existing audit skills by invocation; they must be installed:

  • impeccable (critique, audit) — already a stardust dependency.
  • marketing skills — seo-audit, schema, ai-seo, site-architecture. Optional; surface a note if absent.
  • stardust tensions — emitted in-repo by extract (brand-review.html).

Normalize each one's output into the ledger via findings.mjs record. See reference/audit-sources.md.

What rollout does NOT do

  • No upstream redesign. design-pass findings are surfaced, not fixed here. autofix only touches platform-fixable findings in the EDS project.
  • No new transport. Delivery is deploy's DA Source API path, unchanged.
  • No redesign of the agnostic core. extract/direct/prototype/migrate and deploy are untouched.
  • No full pre-migration requirement. Archetypes-only mode is first-class: block code is deployed from the archetypes; remaining pages advance from content-pending to deployed as migrate emits their HTML — no rollout restart.

Scripts

  • scripts/inventory.mjs — migrated tree → page + template coverage (idempotent, stale-aware). --state <path> enables archetypes-only mode.
  • scripts/blocks.mjs — distinct-block dedup ledger (blocks.json).
  • scripts/plan.mjs — dedup-driven delivery order + per-page convert/reuse briefs.
  • scripts/update-coverage.mjs — deterministic delivery state-writer for pages and blocks; re-derives all roll-ups. --new <slug> --path --template --origin registers a page built outside the migrated tree (D2) so it enters coverage.
  • scripts/section-fidelity.mjs — source-fidelity gate scaffold (authored sections vs source heading outline; informs the gate, never auto-decides).
  • scripts/assemble.mjs — site-level sitemap / robots / fragments manifest (the EXPECTED set); --verify-origin <live-origin> compares the SERVED /sitemap.xml with it and exits 1 on a mismatch.
  • scripts/verify.mjs — full-site structural verification (HTTP or offline --root).
  • scripts/optimize.mjs — rollout:baseline detectors + the multi-source gate; exits non-zero on open P1. Findings mirroring the source capture are tagged source parity: — informational, not scored, not gated.
  • scripts/findings.mjs — record/resolve findings from the external audit sources.
  • scripts/autofix-aem.mjs — the AEM autofix engine (edits the EDS project).
  • scripts/dashboard.mjs — design-identity dashboard + data.json snapshot.
  • scripts/done-check.mjs — the completion verdict (Phase I); exit 0 = complete.
  • scripts/lib.mjs — shared IO + roll-up + page-loading + autofix-registry helpers.

References

  • notes/rollout/PLAN.md — design, coverage model, phasing, open questions.
  • reference/delivery-gates.md — Phase C gates + batched-delivery-at-scale flow.
  • skills/dynamics/SKILL.md + its reference/ — the dynamic surface: classes, triage axes, listings contract + query-index mechanics, pattern catalogue, parity report (B2/D2).
  • reference/multilingual.md — per-language trees (D3).
  • reference/operational-learnings.md — scaled-rollout gotchas (extend, republish, verify).
  • reference/audit-sources.md — the audit-source → layer → fixability → autofix map.
  • reference/checks.md — the rollout:baseline check catalog.
  • skills/stardust/reference/learnings.md — the per-run learnings ledger the report phase writes.
  • skills/migrate/reference/fidelity-tiers.md — the archetype/sibling/thin tier contract Phase C records.
  • skills/migrate/reference/media-reconciliation.md — the image-fidelity resolver's decision table.
  • skills/deploy/SKILL.md — the single-page conversion methodology rollout drives.
  • skills/deploy/da-deploy-protocol.md — the DA Source API transport.
  • skills/migrate/SKILL.md — produces the migrated/ + _meta.json inputs.
  • schemas/*.schema.json — the coverage + config contracts.

stardust:spec — the migration spec, before the migration

The spec answers the people planning a migration (what to build, reuse, fix or decide) and the agent that runs it (archetypes, block backlog, contracts, redirects, a default for every decision). The agent builds it stage by stage.

Principles

  • Evidence, then judgement. Stages S1–S6 and S8 measure the live site; S7 and S9 are judgement (mapping, reuse, features, questions) recorded in judgement/ with a rationale per decision.
  • Blind judgement. Judge from the source site only (reference/judgement.md); state the provenance in implementation.json#provenance.
  • Variants, not templates. CMS templates are loose; plan, capture and QA by layout variant (S8).
  • Every open question ships a default. A hands-off migration applies it; a recorded answer replaces it.
  • Computed, never typed. Every figure in findings, feature reach and question impact is a rule (reference/knowledge.md § Rules) the knowledge stage evaluates.

Setup

stardust/spec/spec.config.json (reference/config.md): origin, scopePath, template rule, parser profile (aem-classic, aem-core, or generic for any other site) + main selector, optional maxPages, rum, referenceBlocks. Copy the stardust, spec, diff, dynamics and deploy scripts to stardust/scripts/<skill>/ (the stages import them).

Stages

#StageCommand (from the project root)Output
S1Inventoryspec-inventory.mjs<work>/inventory/
S2Fetchspec-fetch.mjs<work>/fetch/
S3Parsespec-parse.mjs<work>/parse/
S4Linksspec-links.mjs, then spec-fetch.mjs --urls <work>/links/pages.txt --out <work>/links/pages.jsonl and spec-parse.mjs --fetch <work>/links/pages.jsonl --out <work>/links<work>/links/
S5Real-user data (optional)spec-rum.mjs (key from $RUM_DOMAIN_KEY)<work>/rum/rum.json
S6First capturespec-pick.mjs --components-only, spec-capture.mjs<work>/media/
S7Judgement: mappingspec-profile.mjs, spec-sheet.mjs <component>, write judgement/mapping.json, spec-map.mjs<work>/map/page-blocks.jsonl
S8Variants + visualsspec-variants.mjs, spec-pick.mjs, spec-capture.mjs<work>/map/variants.json, <work>/media/
S9Implementationdynamics-detect.mjs --urls <reps> --out <work>/dynamics, spec-martech.mjs, chrome-explore.mjs <home> <work>/chrome/header.json; write judgement/catalog.json, implementation.json, findings.json, search-probes.json<work>/, judgement/
S10Knowledgespec-knowledge.mjsknowledge/

Each stage logs start and end to stardust/status.jsonl (ledger.mjs spec s1-inventory start). <work> is stardust/.work/spec/, never committed. Large sites: S2 runs at 4 parallel requests and is resumable — start it, then write config and judgement scaffolding while it runs. One browser job at a time (S6/S8/S9), two tabs.

Judgement (S7, S9)

Start from templates/. mapping.json and catalog.json: reference/judgement.md. implementation.json: reference/implementation.md. findings.json: 6–10 plain-text { title, text, chapter, rank } headlines. Recorded answers go in judgement/answers.json.

Outputs

judgement/ and knowledge/ in stardust/spec/, committed; reference/knowledge.md is the contract. Raw material, captures and crops stay in <work>.

Gates

  • S7 passes when spec-map.mjs reports no unmapped component and every block in the page blocks is in catalog.json (spec-knowledge.mjs warns otherwise).
  • S10 passes when spec-knowledge.mjs exits 0 (every rule computed) and every open question has a default.
  • A blocked origin (S1 or S2 exit 3: bot challenges or refusals on 10% or more) stops the build: ask the user to allow-list the crawler, or to choose --headed (the plugin's real-Chrome challenge-solve tier of browser.mjs, as replica uses) or --archive <date> (Internet Archive captures, which the provenance and a finding must disclose). Never choose for them, and never work around a block another way.
  • Before sharing: no customer secret, internal evaluation or other migration's name in the project or the output.

References

  • reference/config.md — spec.config.json, template rules, parser profiles.
  • reference/judgement.md — the blind rule, mapping rules, contact sheets, block families, reuse verdicts.
  • reference/implementation.md — features, martech, data layer, metadata, indexes, locales, open questions.
  • reference/knowledge.md — the output contract: files, fields, the rule format.
  • reference/evaluation.md — scoring a spec against a delivered migration; blind re-judgement.

stardust

You are operating the stardust skill: a guided redesign of an existing website. The user's job is to say what they want; your job is to reason about what that means, propose a plan, and execute it through a small set of sub-commands that delegate the actual design work to impeccable.

Setup (run before anything else)

  1. Verify impeccable is installed. Stardust has a hard dependency on impeccable and ships no fallbacks. Look for the impeccable skill wherever the harness installs skills or plugins: the skill list the harness exposes to you, project skill directories (.claude/skills/, .agents/skills/, .cursor/skills/, .github/skills/), or the harness's plugin cache (Claude Code: ~/.claude/plugins/cache/; GitHub Copilot: ~/.copilot/installed-plugins/*/impeccable/skills/impeccable). If it is not installed, stop and tell the user:

    Stardust requires impeccable. Install it from https://github.com/pbakaus/impeccable and re-run the command.

    Version hint (advisory, never blocking). Stardust deliberately pins NO impeccable version — the design craft should always be the current one — and harnesses do not announce third-party plugin updates by default (Claude Code's marketplace auto-update is off for third-party marketplaces such as impeccable's; Copilot has no update notice). So, once per session, run node <plugin>/skills/stardust/scripts/impeccable-version-check.mjs (add --local <impeccable-dir> when impeccable lives in a harness skills directory rather than the plugin registry) and surface its one output line to the user verbatim when it reports a newer version; it prints the update command for the harness it found impeccable in. Any other outcome (current, unknown, offline) is noise — do not mention it, and never stop or degrade a run over it. The same script with --where prints impeccable's skill directory (the one holding its SKILL.md and reference/); note it once — the phases that read impeccable's format specs (reference/init.md, reference/document.md) read them from there by section, never after a filesystem search.

  2. Check the target-state files. PRODUCT.md and DESIGN.md at the project root are the target state for stardust; check whether they exist (a directory listing is enough). Do not run impeccable's context loader (scripts/impeccable context) here: it emits directives for impeccable's own flow (init, new-work, detector, update checks) that do not apply to stardust's setup, and impeccable runs it itself whenever stardust invokes an impeccable command. Skip if already known from this session's history.

  3. Read stardust's state. Read stardust/state.json if present (reference/state-machine.md defines the schema). Note which pages are extracted, directed, prototyped, approved, or migrated.

  4. Read impeccable's command registry. Parse <harness>/skills/impeccable/scripts/command-metadata.json. This is the single source of truth for the 24 impeccable commands; never hardcode them in your reasoning.

  5. Status ledger. Every stardust skill appends a phase-transition line to stardust/status.jsonl at each phase start/end, per reference/run-status.md — written with skills/stardust/scripts/ledger.mjs <skill> <phase> <start|end|blocked> [--detail …] (--strict refuses unknown phases), never with hand-built printf. Page status moves with skills/stardust/scripts/state.mjs advance <slug…> --to <status>; a resuming agent reads ledger.mjs tail and state.mjs summary. For progress, recommend node stardust/scripts/stardust/ledger.mjs tail [-n 10] or last [<skill>]; ledger has no summary command. Report recorded status, not process liveness.

  6. Project hygiene (idempotent). Write stardust/.gitignore from reference/stardust.gitignore if absent; never edit a project's copy. In a git repo: root .gitignore covers .env / .env.* (managed # >>> stardust block), .hlxignore if present lists stardust/, and git check-ignore -q stardust/state.json must fail — if it passes, stop and name the rule. Offer, never write, LFS above 50 MB of tracked binaries under stardust/. Details in reference/artifact-map.md § Versioning.

  7. Copy this skill's whole scripts/ dir to stardust/scripts/stardust/ before any other skill's script runs. Its browser.mjs is the one entry to the browser for every script. A script you write opens every page this way (#159): newLiveContext and gotoLive, never chromium.launch() or page.goto:

    import { pathToFileURL } from 'node:url';
    const { openBrowser, newLiveContext, gotoLive } = await import(pathToFileURL('stardust/scripts/stardust/browser.mjs').href);
    const browser = await openBrowser({ mode: 'chrome' });
    const context = await newLiveContext(browser, { viewport: { width: 1440, height: 900 }, stateUrl: url });
    const page = await context.newPage();
    await gotoLive(page, url); // paced on a live site. A bot wall throws.
    

Routing

Once setup is done, route on the user's input:

  • No argument. Render the state report described in reference/state-machine.md: project state, per-page status table, recommended next command, with reasoning. Do not write anything. The same applies to any resume: a new session on a project that has stardust/state.json, "continue", "where are we", or a resume driven by a memory file. Start with the state report (it names the flow and the last gate numbers), then enter the next phase through its skill — the procedure drives, not memory. (Recorded: a 144-hour resume session invoked no stardust skill at all, re-read the procedure through grep, and followed whatever the previous context remembered.)

  • First word names a sub-skill. Delegate to the matching sub-skill and pass remaining args through. Sub-skills are named by their bare skill name below; how to address one depends on the harness. Claude Code namespaces plugin skills as stardust:<name> (Skill tool); GitHub Copilot and other harnesses that flatten plugin skills expose the bare <name>. If the harness has no skill-invocation tool, read the sub-skill's SKILL.md and follow it inline. Never confuse the stardust extract and audit skills with impeccable's extract and audit commands, which are always written $impeccable <command>. The master skill routes all sibling sub-skills:

    keywordowns
    extractcrawl + capture the current site
    directresolve the visual direction
    prototypeper-page redesign prototypes
    migratefull-site platform-agnostic static HTML
    prepare-migrationthe migrate-prep cascade (prep phases, assets, dynamics gate) — redesign flow only
    replicasame-design migration (re-platform, keep the current design) — runs its own preserve-mode prep, then hands off to migrate/deploy/rollout
    reskinbyte-faithful content re-laid onto a separately defined donor design system
    deployone page → EDS blocks + DA delivery
    rolloutwhole migrated site → EDS, with coverage + delivery gates
    dynamicsthe dynamic surface of a migration — detect, classify, triage, implement, verify (APIs, search, forms, modals, media, tags, client-rendered, sheet data); migration-bound, invoked by prepare-migration / replica / migrate / rollout or standalone on an already-migrated site
    diffprototype ↔ build fidelity probes (pixel + structural)
    auditthree-perspective site audit — design tensions, SEO/technical, LLM visibility — scored report + findings ledger
    qaread-only post-deploy QA sweep of the live site — routing, fidelity, template conformance, rendering, visual regression, SEO, links, a11y, perf — findings report only, never fixes
    upliftone-shot presales orchestrator (3 variants)
    specpre-migration spec of a site — pages, blocks with reuse verdicts, dynamic features, martech, open decisions — as committed knowledge files
    • prototype accepts --cinematic (or --cinematic=<register>) to layer a brand-faithful motion register on top of the static prototype (per skills/prototype/reference/motion-registers.md).
    • uplift is the one-shot presales orchestrator: takes a URL and produces three differentiated variants (one fully cinematic) without further user coordination. Use when the user wants to skip the extract/direct/prototype chain (per skills/uplift/SKILL.md).
  • Migration to EDS — pick ONE of two flows, never mix them. See § Two migration flows below before answering any "how do I migrate X" question; the routing answer differs by whether the design is kept.

  • First word is anything else (a freeform phrase). Treat it as a redesign intent. Load reference/intent-reasoning.md and follow the procedure step by step. Do not execute any impeccable or stardust command before showing the resolved plan to the user (under hands-off mode, the plan is recorded in stardust/direction.md instead of awaiting confirmation — see § Hands-off mode).

Two migration flows — pick one, never mix

When the user wants to migrate a site to AEM Edge Delivery (or any clean front end), the ask decides whether the design is kept or changed: a migration keeps its design unless the ask says to redesign it. That selects the flow; the downstream chain is shared.

  • Scoping, before either flow: "scope / estimate / plan / spec the migration of X", "which pages use block X", a redirect or 404 inventory → spec. Flow-neutral: it never stamps flow.
  • Redesign while migrating: extract → direct → prototype, or in one orchestrated step prepare-migration (the prep cascade with confirmation gates) → migrate → deploy (one-page pilot) / rollout (whole site).
  • Keep the current design (re-platform): replica → migrate → deploy / rollout. replica subsumes the prep cascade in preserve mode — extract --prep is its Phase 1, a mechanical direction-preservation step replaces direct --prep, and gated archetype recreation (measured source-fidelity gate per breakpoint) replaces prototype --prep. Never run prepare-migration before or after replica; there is no separate prep step in this flow.
  • New design from a donor, same content: reskin — content is byte-gated, design comes from another live site or local prototypes.
  • Both migration flows carry the dynamic surface by default. The pre-import gate (prepare-migration 4.5 / replica Phase 2, with migrate as the safety net) runs the stardust dynamics skill Phases 1–3 so every API, search box, form, modal, player, tag and client-rendered surface gets a disposition before import; rollout D2 implements the reproducible rows and qa replays parity. Never for redesign-only work (uplift, a bare extract): dynamics is a migration concern.

Choosing, and recording the choice. Read the ask before any sub-skill loads:

  • Keep-design phrases select replica without a question: "exact replica", "1:1", "pixel-perfect", "faithful", "same design", "keep the current design", "as is", "re-platform only", "migrate keeping the design", or a direction phrase that pins every axis unchanged (ia-fidelity: verbatim with palette, type and density all pinned).
  • Redesign phrases select the redesign flow: "redesign", "modernise", "refresh", "new look", "rethink", "reimagine" — any phrase that moves a design axis. Only an explicit phrase does; nothing is inferred.
  • Anything else ("migrate X to EDS") is a faithful migration: replica, flowSource: "default", no question, interactive and hands-off alike. The first response carries replica's flow line ("Flow: replica — the design is kept. Say switch to redesign now if it is to change."), so the one decision stays visible. With 1,000+ sitemap URLs and no spec, it adds "Large site: say spec first to scope it." Offered only, never in hands-off mode.

Stamp the choice in state.json as flow / flowChosenAt / flowSource (reference/state-machine.md § Flow keys) before delegating. The sub-skills enforce it: migrate, deploy, rollout and a migration-intent extract refuse to start a migration on a project with state.json and no flow; prepare-migration refuses under flow: replica and replica under flow: redesign. Switching is explicit — $stardust replica --switch-flow / $stardust prepare-migration --switch-flow — and marks the old flow's prototyped or migrated pages stale (§ Per-page state).

Planning aids belong to one flow. Redesign: the prepare-migration plan and its phase gates, the canon, module catalogs, template plans of the "learn the template, then compile" kind. Keep-design: replica's inconsistency register and progress.json, the archetype gate ledgers, rollout waves. A redesign procedure or plan template inside a replica run — or the reverse — is a routing defect: refuse it, or flag it in direction.md and hand back to this section. (Recorded: a same-design migration adopted a redesign-only "train the template, then compile" plan and spent an hour, 45 turns and 36 M tokens before reverting it; another loaded prepare-migration for a keep-design ask on a plugin that already described the two flows — description without a guard did not hold.)

State the chosen flow explicitly in the first response to a migration question, including the fact that replica needs no prepare-migration step, so the user never has to ask which prep applies.

Hands-off mode

Activated by --hands-off on any stardust invocation, or by an explicit user phrase ("fully hands-off", "no approval gates", "run autonomously"). On activation, stamp state.json.handsOff: true (schema note in reference/state-machine.md § Hands-off keys) and append an activation line to stardust/direction.md. The mode removes waiting, not validation: every quality gate in the pipeline still runs at full strength; what changes is who resolves the interactive pauses.

Under hands-off, every interactive gate across the pipeline auto-resolves:

gatehands-off resolution
direct clarifying questionsderive the answers from the captured evidence (stardust/current/), and state each as a named assumption in direction.md
prototype brief-confirmation waitsskip; proceed on the authored brief
prototype approvalgranted by the agent's own judgment only after all quality gates pass (craft bar, validation loop, motion gates); recorded as approvedBy: "hands-off" on the page's approved history entry in state.json
prepare-migration phase gatesbehave as --skip-confirm
rolloutruns full-auto end-to-end
dynamics owner decisions (backend, tags on the new host, datasource ownership, locale scope)ship the interim tier, record each decision by name in dynamic-features.md and the parity report, continue; regulated-pii forms stay blocked; a named assumption never sets decided-out

Defaults under hands-off (override only when the invocation says otherwise):

  • One canonical direction. No variant fan-out — commit to a single direction and record the rationale in direction.md.
  • Volume caps as reasoned proposals, said out loud. Default 100 pages overall, 20 per template; "all pages" (or --all-pages) in the invocation lifts them; a user-named N replaces both and orders link-first (../extract/reference/ia-extraction.md § Priority for the cap). Otherwise roster priority: (1) every page linked from the header and footer, (2) section landing/overview pages, (3) a representative spread of detail pages across all templates. The setup status line names the roster against the site (roster 94 of 2,532 discovered — cap 100/20); a capped roster is never called the full site. Record the caps in direction.md.
  • First page first. A full-site replica run delivers one page (home, or the one named) first: ../replica/reference/first-page-first.md.
  • Captured pages stay in the roster. Locale is never a reason to drop a captured page: every state.json row is delivered — duplicate-content locale shells ride the sibling tier of their twin; D3-multilingual is for language trees that were never captured.
  • Delegate by file pointer, read by section. A brief to a delegated agent names the files and sections it needs (state.json, the page's schema, the phase's SKILL.md sections); it never inlines reference docs. Reference documents are read by heading and line range, not end to end (replica ships skills/replica/scripts/section.mjs for exactly this: --list for a document's outline, then one heading; it works on any Markdown file — a whole reference doc is 30–40k characters, the section a step needs is 2–4k, and one recorded session paid for three whole docs twice when their cat output overflowed and was re-read in full). Instruments that can stall run under their shipped deadline (replica gate.sh, pixel-compare --timeout) — never under an agent-authored sleep N; kill loop — and long steps write a progress file the coordinator polls instead of blocking on the agent. (Field evidence, 2026-09: in one recorded run the two conversion agents the harness watchdog killed carried the fattest briefs and whole-document reads, and a lean re-dispatch finished the same pages; that conversion lost 89 minutes to a blind wait and 30 to fixed sleeps.)
  • Wait discipline: never park the conversation past the prompt-cache window. Anything expected to run longer than about 2 minutes — a gate round over several pages, a crawl, a batch push, a capture set, a delegated agent — runs in the background and writes a progress or summary file; the coordinator never runs it in the foreground and never covers it with one long sleep. While it runs, do independent work; when there is none, check back with one short read of the progress file at most every 4 minutes — never a fixed sleep of 5 minutes or more, and never a blocking "wait for the agent's output" call with a long timeout. The number is not taste: the prompt cache expires after 5 idle minutes, and at the 500–900k-token contexts a migration reaches, every expiry re-writes the whole prefix at write price (12× a cached read). Field data, 48 sessions: a foreground wait of ≤ 4 minutes missed the cache in ~10 % of cases, ≥ 5 minutes in 85–87 %; 572 such agent-side waits re-wrote 325 M tokens — 46 % of everything those sessions wrote to the cache. Ending the turn to wait for a completion notification helps the user, not the cache: a notification that arrives after 5 minutes misses too (137 recorded), so prefer short checks for waits under ~45 minutes and end the turn only when the wait is longer or the user should decide. (Claude Code: run_in_background: true on the shell call, the harness posts a task notification when it exits; promptCacheTtl: "1h" in settings.json stretches the window to an hour at 1.6× write price — an owner setting, worth it for any multi-hour session.) The harness-neutral form of the same rule is replica's run-bg.mjs: start detaches the instrument, wait returns within --max (default 100 s, ceiling 110 s — inside the shell tool's ~2-minute default timeout, which applies only to a call that declares none) with verdict lines only, exit 75 = still going, wait again as the NEXT call — never in a shell loop, never after a sleep. The rule binds the main agent as it binds subagents: one long instrument in the foreground, or two long instruments as parallel tool calls in one turn, is the same blocked step (recorded: a 338 s main-agent turn cost one full cache re-write).
  • One shell, one working directory. The harness's shell keeps its working directory from one tool call to the next: a cd inside a command moves every later command with it, and a path written from the project root then fails from wherever the previous call ended. Write paths from the project root (or absolute), and confine any cd to a subshell — (cd stardust/current && …). (Field evidence, 2026-09: one cd into the capture directory failed the next three reads and cost a re-run turn.)
  • Author large files in parts. Write the skeleton, then append in edits of roughly 150 lines or less, so no single turn generates for longer than the prompt cache lives (about five minutes); a turn that outruns it leaves the next request with a cold cache and re-writes the whole context. (Field evidence, 2026-09: in one recorded run two such turns — the brand documents written in one go at the end of extract, and a first prototype's whole HTML and CSS in one write — each cost a full re-write of a ~200k-token context; an earlier run re-wrote 513k and 694k the same way. No compaction was involved; the sessions simply outran the cache lifetime inside one generation.)
  • Commit at the end of each phase when the project is a git repo. Before the FIRST such commit, re-run Setup step 6 — the first commit lands at the end of the audit phase, long before deploy's SKILL.md is read, and a tracked .env poisons every later push (GH013 + history rewrite at deploy time).

Hard blockers remain stops. An unreachable source site, an expired DA_TOKEN that cannot be recovered, or a signal-absent brand surface (extract captured no usable brand signal even after a re-run) are not judgment calls — state the blocker precisely, append event: "blocked" to stardust/status.jsonl, and halt. Never guess around a hard blocker.

Quality gates NEVER weaken under hands-off. Provenance validation, the validation loop, fidelity gates, delivery gates, and rollout's optimize gate all run unchanged. Hands-off changes who answers, not what must pass.

The "open and reasoned" principle

Stardust does not ship a closed intent → commands lookup. Every freeform phrase is reasoned about in public. You must:

  1. Restate the phrase in stardust's dimensional vocabulary (reference/intent-dimensions.md).
  2. Identify which axes the phrase moves and in which direction.
  3. Identify what is underspecified and ask the user at most two clarifying questions.
  4. Map the resolved direction to a sequence of impeccable commands, citing each command's reference in reference/impeccable-command-map.md.
  5. Show the proposed plan to the user before executing.
  6. After execution, record the resolved direction, axes, commands, and reasoning in stardust/direction.md with a stardust provenance block.

Worked examples of this procedure live in reference/intent-examples.md.

Per-page state and "stale on direction change"

Pages have lifecycle states (extracted | directed | prototyped | approved | migrated). When the user's direction changes after some pages have already been prototyped or migrated, mark those pages stale; do not auto-re-run. The user opts in to re-prototyping or re-migrating explicitly. Details in reference/state-machine.md.

Artifacts you read and write

Stardust state lives under stardust/. Impeccable's PRODUCT.md / DESIGN.md / DESIGN.json live at the project root and represent the target state. The current (extracted) state lives under stardust/current/. Full layout in reference/artifact-map.md.

Write boundary. Stardust writes to stardust/, the impeccable target files at the project root, and the EDS project (only via deploy, rollout, dynamics). Run-only files — logs, harness page, pre-renders, script copies, drafts — go under stardust/.work/<skill>/; the root scripts/ and qa/ are not stardust's. Anything written elsewhere is a bug in that skill.

Versioning. Everything under stardust/ is committed except what reference/stardust.gitignore lists: screenshots, gate images, two heavy folders (migrated/assets/, rollout/qa/), .work/, run residue, session state. Per-directory table and what a clone can and cannot do: reference/artifact-map.md § Versioning.

Provenance

Every artifact stardust writes carries a provenance block as the first line or first key, declaring: which sub-command wrote it, against which user input, what was synthesized vs. authored, and what other artifacts were read. Format conventions in reference/artifact-map.md.

Journal rule

A multi-session stardust project benefits from a chronological journal that records the prompt history, decisions, and open questions across turns — separate from the state machine and from per-artifact provenance. State.json records what is, provenance records why an artifact says what it says, but neither captures the narrative arc of how the project got here. The journal does.

Maintain stardust/journal.md per the format in reference/journal-format.md. On every prompt execution that resulted in a non-trivial write (any direct, prototype, migrate, or substantial iteration), append an entry before ending the turn.

Named deviations. Any agent-authored crawler, compiler, importer, wave driver or gate that replaces a skill phase is recorded in stardust/direction.md as a named deviation — what it replaces, why the shipped instrument did not serve, where the replacement lives — and noted in the journal entry. An unrecorded parallel pipeline is a defect, not initiative: three recorded migrations rebuilt the import pipeline by hand (one a 60 KB importer) beside skills that shipped it, and their fidelity numbers were never comparable to the gate's.

The journal is append-only. If a prior entry turns out wrong, write a new entry that corrects it; do not edit history. This preserves the reasoning trace and lets reviewers see how decisions evolved.

The journal is project-scoped and human-facing — it lives at the same level as the impeccable PRODUCT.md, not under stardust/current/ or stardust/canon/. Treat it as the shared narrative layer over stardust's state machine.

When the user invokes stardust at the start of a new session, the journal is read first (along with state.json) — its last 3-5 entries carry the "where did we leave off" context that the state machine doesn't.

Validation rule

Every artifact stardust writes that a human will eyeball — proposed HTML, brand-review.html, the migrated site — runs through a recursive validate- and-fix loop before being marked done. The principle: type checks and test suites verify code correctness; only browser rendering verifies feature correctness.

For HTML the user will see (prototypes, migrated pages, the brand-review HTML):

  1. Render in Playwright (file:// for static, or local dev server), through browser.mjs (§ Setup, step 7).
  2. Capture at three viewports — desktop 1440×900, tablet 768×1024, mobile 390×844:
    • Full-page screenshot.
    • Browser console messages (errors + warnings).
    • Network failures (4xx / 5xx / aborted requests, missing assets).
    • Uncaught JS exceptions + unhandled promise rejections.
    • Layout sanity: no horizontal overflow; key landmarks present and non-empty.
    • a11y quick-pass: alt text, input labels, heading order, contrast on text-over-image.
    • Interaction smoke: hover an interactive card, scroll-trigger fires, nav opens/closes, primary CTA reachable by keyboard.
  3. If any issue is found, fix it and re-run the loop. Iterate recursively until either (a) no issues remain or (b) the fix needs user input — in which case surface the question and stop. Do not report a task complete with known issues outstanding.
  4. Save the final clean-pass screenshots to stardust/validation/<artifact>/<viewport>.png so reviewers can compare without re-running.

Per-sub-skill validation specifics live in each skill's reference docs — notably extract/reference/playwright-recipe.md (the canonical recipe), prototype/reference/motion-validation.md (motion-specific gates), and prototype/SKILL.md Phases 2.5–2.8 (the critique / audit / adapt / motion gate cascade).

What stardust never does

  • Invent design opinions that contradict impeccable's hard rules. Defer to impeccable.
  • Execute a redesign plan without showing it first (hands-off mode records the plan in stardust/direction.md instead of waiting — § Hands-off mode).
  • Force a re-run on stale pages without explicit user opt-in.
  • Crawl an existing site beyond the user's confirmed page cap (an explicit --pages list is itself the confirmed scope — listed pages are never dropped; the crawler warns rather than truncates when the list exceeds --max).
  • Emit platform-specific output from migrate. migrate emits platform-agnostic static HTML; the EDS conversion and delivery are owned by the stardust deploy (one page) and rollout (whole site) skills sub-skills, routed above.

References

  • reference/intent-dimensions.md — the axes redesigns move along.
  • reference/intent-reasoning.md — the procedure for handling a freeform phrase.
  • reference/intent-examples.md — worked examples (8-12) of the reasoning style.
  • reference/impeccable-command-map.md — when to reach for each of the 24 impeccable commands.
  • reference/state-machine.md — page lifecycle, stale rules, state report format.
  • reference/artifact-map.md — every file stardust reads or writes, with ownership, provenance shape and (§ Versioning) what is tracked.
  • reference/stardust.gitignore — installed as stardust/.gitignore by Setup step 6.
  • reference/divergence-toolkit.md — anti-mediocrity device. Default-moves list, deterministic seed, font decks, role-naming rule. Consumed by direct (when authoring target tokens) and prototype (when generating variants).
  • reference/token-contract.md — :root CSS custom-property contract every prototype and migrated page must expose. The token interface between stardust and any downstream consumer.
  • reference/data-attributes.md — structural data-* vocabulary applied to sections in every prototype and migrated page. The structural lingua franca between stardust sub-commands and downstream tools.
  • reference/journal-format.md — stardust/journal.md entry format. Append-only chronological log; the shared narrative layer over the state machine.
  • reference/run-status.md — the stardust/status.jsonl phase-transition contract every skill appends to. The deterministic progress surface for any harness.
  • reference/learnings.md — the per-run learnings ledger contract (stardust/learnings.md). rollout's report phase writes it; plugin maintainers harvest pending entries into skill diffs.

Cinematic-feature references (cross-cutting)

Owned by prototype/ because the cinematic feature is scoped to prototype rendering, but cited by direct (when selecting a register), uplift (when picking C's register), and migrate (when copying motion assets through):

  • ../prototype/reference/motion-registers.md — five brand-faithful motion personalities (arrival, kinetic-display, live-systems, editorial, kinetic-grid) and the selection heuristic that maps PRODUCT.md Brand Personality traits to a register.
  • ../prototype/reference/motion-stack.md — technology choice: Lenis + CSS keyframes + rAF + IntersectionObserver. Why not GSAP. Bundle policy.
  • ../prototype/reference/motion-attributes.md — data-* vocabulary the runtime consumes ([data-anim], [data-tile-anim], [data-countup], [data-flip], [data-fill], [data-split], [data-parallax]).
  • ../prototype/reference/motion-runtime.md — the canonical inline runtime script that powers every cinematic prototype.
  • ../prototype/reference/motion-validation.md § Pass 6 — cinematic-mode validation gates (Lenis boot, reduced-motion fallback, scroll-jack, three-position screenshots, register-match, motion C-cliff detector).

Uplift-feature references

Owned by uplift/. Cited by master routing when delegating $stardust uplift <URL>:

  • ../uplift/SKILL.md — one-shot presales orchestrator: extract → tension/trait identification → 3-variant direction → prototype × 3 → open + summarize.
  • ../uplift/reference/what-if-candidates.md — catalog of 8 worked captured-trait amplification candidates that B and C select from in Phase 2b — plus its § Extension rule admitting evidence-shaped derived candidates.

stardust:uplift

One entry point. One URL. Three presales-quality redesign variants.

uplift collapses the extract → direct → prototype × 3 chain into a single opinionated command that picks every variability axis from the captured brand surface rather than asking the user. The output is the same as the long-form chain (state.json, brand-review.html, three proposed files, motion validation) — the user just doesn't have to coordinate it.

Opinionated defaults

  • Single-page extract — the homepage by default (the brand owner's first surface) unless --page <slug> overrides.
  • Brand-faithful Mode A — palette + typography pinned. No invented colors, no fonts outside the captured surface.
  • Three variants, fixed role contract — A is the green-light, B is the design-team motivator, C is the visionary cinematic pitch.
  • Cinematic register auto-picked — C's motion register is selected from the captured PRODUCT.md Brand Personality per ../prototype/reference/motion-registers.md § Selection heuristic.
  • "What if..." candidates are evidence-shaped — B and C each pick one captured-but-underused trait, from the eight worked candidates in reference/what-if-candidates.md or a derived candidate per its § Extension rule. Different traits per variant.
  • Validation cascade runs — every gate in prototype/SKILL.md Phases 2.5–2.8 fires, including cinematic Pass 6 for variant C.

Inputs

  • <URL> — required. The page to redesign. Defaults to homepage when the URL has no path (https://example.com/ → home).
  • --page <slug> — optional. Override the slug if the URL points elsewhere or the user wants a different surface.
  • --cinematic-register <name> — optional. Override the auto-picked register for variant C. One of arrival, kinetic-display, live-systems, editorial, kinetic-grid. Recorded as registerSource: "user-override" in C's provenance.
  • --two-variants — optional. Render only A and C (skip B). Useful when the brand surface is thin and a forced three-way differentiation would produce a weak middle (per the stop condition below).
  • --re-extract — optional. Force a fresh crawl even when a prior extraction of the same URL is < 7 days old (see § Setup, reuse-if-fresh).

There are no other flags. Everything else is derived from the captured brand surface or governed by the underlying skills' contracts.

Setup

  1. Run the master skill's setup (../stardust/SKILL.md § Setup): impeccable dep check, context loader, state read.
  2. Verify Playwright is available (extract will fail without it — surface the same install message extract would).
  3. Read stardust/state.json if present. Reuse-if-fresh: when a prior extraction of the same URL is < 7 days old, skip Phase 1 and render against the existing capture, with a one-line notice ("reusing extraction from — pass --re-extract for a fresh crawl"). --re-extract forces a fresh crawl regardless of age; extractions ≥ 7 days old re-extract without asking.

Procedure

Six phases plus a reference-grounding interphase. Phases 1, 4, 5 delegate to existing skills; phases 2, 2.5, 3, 6 are owned by uplift.

Phase 1 — Extract (delegate to the stardust extract skill)

Invoke $stardust extract <URL> --single (single-page mode). Extract owns:

  • Live Playwright render with the standard wait recipe.
  • stardust/current/_brand-extraction.json (palette + type + motifs
    • voice + system components + photography).
  • stardust/current/pages/home.json (full per-page capture).
  • stardust/current/brand-review.html with the tensions detectors applied — this is the load-bearing input for Phase 2.
  • stardust/current/PRODUCT.md and DESIGN.md (descriptive — the current state, not the target).

uplift does not crawl beyond one page. The brand surface from a single homepage is sufficient for three variants; multi-page extract is what the stardust extract skill (without --single) is for.

Phase 2 — Tension and trait identification (owned by uplift)

Read stardust/current/brand-review.html § Tensions surfaced and _brand-extraction.json. Produce two artifacts:

2a — stardust/uplift-improvements.md

At least 3 specific weaknesses observed in the captured site — as many as the evidence supports, no fixed count. Same load-bearing contract as the existing presales workflow: without specifics, "make it better" has no claim. Category tags (MAY repeat across items when the evidence supports it):

  • [dated-pattern] — patterns the design world has moved past (be specific: "centered hero with stock photo + double CTA in primary blue reads as the SaaS template circa 2019")
  • [ia-clutter] — cluttered IA / unclear hierarchy / weak CTAs / redundant sections
  • [contrast-or-density] — contrast failures, accessibility gaps, density issues
  • [cliché] — conventions the brand could move past while staying recognisably itself
  • [missed-opportunity] — the captured surface doesn't capitalise on its own strengths ("captured photography is excellent but the layout crops it to thumbnail-size")

Specificity bar — every item. Each item cites a measurement, tension ID, or screenshot observation from the capture, names the pattern at fault, and proposes one concrete fix. An item that fails the bar is cut, not padded.

Audit consumption. When stardust/audit/<domain-slug>/audit.json exists for this origin (written by the stardust audit skill), consume its design findings as candidate improvements instead of re-deriving them from scratch — cite the finding IDs in the item's evidence and add the audit file to readArtifacts.

Refuse to proceed if fewer than 3 specific weaknesses can be named (see § Stop conditions).

Format (mirrors the provenance shape used by the rest of stardust):

---
_provenance:
  writtenBy: stardust:uplift
  writtenAt: <ISO-8601>
  againstInput: <URL>
  readArtifacts:
    - stardust/current/_brand-extraction.json
    - stardust/current/pages/<slug>.json
    - stardust/current/brand-review.html
---

# Improvements — <URL>

1. **[<category-tag>]** <one-line headline> — <measurement /
   tension ID / screenshot observation> · <pattern at fault> ·
   fix: <one concrete fix>.
2. **[<category-tag>]** … (≥ 3 items; tags may repeat)

The bracketed tag preceding each weakness is a category from the list above. The headline is the one-sentence summary the agent will restate when variant A's shape brief applies the fix.

2b — stardust/uplift-questions.md

Six to eight "what if we leaned into…" candidates derived from the captured brand surface. Each candidate cites the captured evidence that makes it concrete. Candidates are drawn from the catalog in reference/what-if-candidates.md — eight worked examples that are the floor, not a ceiling:

  1. Display-typography amplification
  2. Photography re-foregrounding
  3. Live-data promotion
  4. Signature-gesture extension
  5. Voice-register pivot
  6. Color-ladder re-weighting
  7. Audience-routing reframe
  8. Motif vocabulary swap

An out-of-catalog derived candidate is admissible when it carries the same evidence shape as the catalog entries: ≥ 2 captured citations + an explicit disqualification test + the variant role it serves (per reference/what-if-candidates.md § Extension rule). Record each candidate's source — catalog | derived — in the candidate list.

For each candidate the agent generates: a one-line "what if…" phrasing, the captured evidence that makes the candidate concrete, the variant role it best serves (B's composition bet vs C's cinematic bet), and whether the candidate is disqualified for this brand (e.g. "Photography re-foregrounding disqualified — the captured photography is generic stock; amplifying it would expose the weakness").

The disqualification step is what keeps the agent from reflexively picking the same candidate for every brand.

Phase 2.5 — Reference grounding (owned by uplift)

When reference research is available (per skills/stardust/reference/reference-research.md — when to fire, the 3–5 reference budget, the evidence shape, and provenance recording are all defined there), ground the Phase 2 claims in real-world references before Phase 3 picks directions:

(a) Ground each [dated-pattern] claim in uplift-improvements.md with a named contemporary counter-example — a real site / screen citation showing what the pattern's world moved to. (b) Anchor variant B's composition bet with a named real-world compositional anchor — a real screen whose composition the bet resembles. (c) Verify C's register pick against how motion is actually used in the vertical — does the register match observed contemporary practice for this kind of brand?

Record the references per reference-research.md's provenance contract (_provenance.referencesUsed[] on the artifact each grounding serves). When reference research is unavailable, skip with a one-line note in that provenance and proceed — the phase degrades gracefully.

This phase never replaces captured-evidence discipline: references justify the MOVE, captured evidence justifies the TRAIT. A candidate without captured citations is inadmissible no matter how well-referenced its move is.

Phase 3 — Pick three variant directions (owned by uplift)

Default: three variants (A + B + C). When --two-variants is active, skip § 3c (B's candidate selection) and the direction.md authored in § 3d declares only A + C. Phase 4 then writes only DESIGN-A and DESIGN-C files at the project root, and Phase 5 renders accordingly. All downstream contracts (variant differentiation, motion validation on C, summary in Phase 6) operate over the reduced variant set without modification.

3a — Pick the cinematic register for variant C

Read PRODUCT.md Brand Personality (from stardust/current/PRODUCT.md) and apply the heuristic in ../prototype/reference/motion-registers.md § Selection heuristic. Record the picked register + the one-line rationale.

3b — Pick C's "what if" candidate

The candidate must be the one the picked register naturally amplifies through motion. The per-candidate Natural register for C fields in reference/what-if-candidates.md are the single source of truth for the register→candidate mapping — read the mapping there (a derived candidate admitted per its § Extension rule must declare the same field). This file does not duplicate the table.

Fallback when C's natural candidates are all disqualified: re-pick the second-choice register — the next-best match from ../prototype/reference/motion-registers.md § Selection heuristic — and take its natural candidate. If the second-choice register's natural candidates are also all disqualified, fall through to --two-variants via stop condition (d): drop B and let C take the strongest remaining non-disqualified candidate.

3c — Pick B's "what if" candidate

Pick from the remaining (non-disqualified, non-C) candidates in uplift-questions.md. Prefer:

  1. A candidate that addresses a tension surfaced in brand-review.html § Tensions.
  2. A candidate whose visual move is composition / IA / voice rather than motion (so B and C are differentiated by axis, not just intensity).
3d — Author stardust/direction.md

Write the resolved direction with three variant declarations:

## Variant A — Faithful + improvements

Role: risk-averse green-light. "Yes, that's us, with the obvious
fixes."
Composition: same as captured.
Motion: static (no cinematic layer).
Improvements applied: <list from uplift-improvements.md>.

## Variant B — What if we amplified <captured trait>?

Role: design-team motivator. The brand's underused capability
foregrounded.
What if: "<one-line "what if…" framing>"
Captured trait amplified: <trait from uplift-questions.md>
Evidence: <captured citation>
Composition: <specific layout strategy that amplifies the trait>
Motion: static (no cinematic layer).

## Variant C — What if motion was part of the identity?

Role: visionary pitch. The brand's third dimension — kinetic.
What if: "<one-line "what if…" framing tied to the register>"
Cinematic register: <register> (auto-picked from PRODUCT.md
Brand Personality)
Captured trait amplified: <trait — the one register naturally
amplifies>
Evidence: <captured citation>
Composition: identical IA to A; the bet is motion, not layout.
Motion: cinematic, register <register>.

Phase 4 — Direct (delegate to the stardust direct skill)

Invoke the stardust direct skill with the resolved direction. Pass the three-variant declaration as the input phrase ("uplift presales redesign — three variants per stardust/direction.md"). Direct owns:

  • Mode A authoring of PRODUCT.md, DESIGN.md, DESIGN.json (root).
  • Per-variant DESIGN-A / DESIGN-B / DESIGN-C files.
  • The motion register block in DESIGN-C.json (read from the direction.md declaration).
  • IA-priority preservation audit.
  • Density floor enforcement.
  • Anti-toolbox audit.
  • Variant differentiation contract.

uplift does not duplicate any of those checks; it relies on direct's existing validators to refuse if the variants violate the brand-faithful contract.

Phase 5 — Prototype × 3 (delegate to the stardust prototype skill)

Render A first, then B and C:

  1. Render A — invoke $stardust prototype <slug> scoped to variant A. A establishes and freezes the canon (tokens, chrome, module renderings) that B and C inherit; rendering it first removes the ordering race.
  2. Render B, then C (default: sequential; parallel only where the harness offers a subagent primitive, such as Claude Code's Agent tool or Copilot CLI's task tool). B and C prototype the same slug, and same-slug concurrent runs are last-write- wins on state.json per ../stardust/reference/state-machine.md § Concurrency — so in-place parallel rendering is unsafe. Parallel is permitted only via isolated workspace copies: each subagent gets a copy of the project (git worktree or directory copy) containing only its own DESIGN-<id>.json at the root (siblings stashed), so prototype's file-presence detection renders exactly that variant. The subagent returns its <slug>-<id>-shape.md, <slug>-<id>-proposed.html (and C's -cinematic.html) plus provenance; the parent copies the artifacts back and performs the single state.json update for both variants.
  3. Open each prototype as it completes (via the open mechanics in Phase 6 step 1) rather than waiting for all three.

Prototype detects the variant set from the per-variant DESIGN-A, DESIGN-B, DESIGN-C files that direct wrote in Phase 4 — authoring <slug>-A-shape.md / -B-shape.md / -C-shape.md and emitting <slug>-A-proposed.html / <slug>-B-proposed.html / <slug>-C-proposed.html per the variant-convergence detector contract (../prototype/SKILL.md § Phase 2.5 / Discipline 10).

Cinematic motion fires per-variant from the per-variant DESIGN file, not from a CLI flag. Never pass --cinematic to prototype from uplift. Because Phase 4 wrote extensions.motion.register into DESIGN-C.json only (A and B omit it), prototype's Phase 2.4 (motion application) fires only for variant C. Variant C emits both <slug>-C-proposed.html (the static reference) and <slug>-C-cinematic.html (the register-applied surface). Variants A and B render static, never acquiring the motion runtime.

Prototype owns:

  • Page-shape brief authoring per Phase 1 of prototype.
  • Render via $impeccable craft delegation, per variant.
  • Phase 2.4 motion application for variants whose DESIGN-<id>.json declares an extensions.motion.register.
  • Phases 2.5–2.8 quality gates (critique, audit, adapt, motion) per variant.
  • Variant C's cinematic-mode gates (Pass 6) per ../prototype/reference/motion-validation.md.
  • Variant-convergence detector (≥ 2 structural changes per pair) per Discipline 10.

Multi-variant rendering is driven by the presence of multiple DESIGN-<id>.json files at the project root, not by a CLI selector — prototype has no --variant <id> input. That is exactly why the parallel path in step 2 requires isolated workspace copies with a single pinned DESIGN-<id>.json each: file presence is the only variant selector prototype has. The A-first ordering above is what keeps canon consistent across the B and C runs in either path.

Phase 6 — Open and summarize (owned by uplift)

After all three prototypes mark prototyped in state.json:

  1. Confirm all three are open in the browser — each variant was opened as it completed (Phase 5 step 3); open any that weren't, using the open shell command (not playwright-cli open) so VFS paths are served via the preview service worker:

    open stardust/prototypes/<slug>-A-proposed.html
    open stardust/prototypes/<slug>-B-proposed.html
    open stardust/prototypes/<slug>-C-cinematic.html
    

    playwright-cli open bypasses the preview service worker and produces a FILE NOT FOUND error for VFS paths. Always use open <vfs-path> for local prototype files.

  2. Print the three-pitch summary in the chat:

    uplift complete — three variants for <URL>
    
    A · Tomorrow's version of the site you have today.
       Improvements applied: <count>.
       File: stardust/prototypes/<slug>-A-proposed.html
       Pitch: "yes, that's us, fixed."
    
    B · What if we amplified <captured trait>?
       Trait: <name>.
       Composition bet: <one-line summary>.
       File: stardust/prototypes/<slug>-B-proposed.html
       Pitch: "the brand's underused capability, foregrounded."
    
    C · What if motion was part of the identity?
       Cinematic register: <register>.
       Motion bet: <one-line summary>.
       File: stardust/prototypes/<slug>-C-cinematic.html
       Pitch: "the brand's third dimension."
    
    Differentiation: A vs B ≥ 2 changes (✓), A vs C ≥ 2 changes (✓),
    B vs C ≥ 2 changes (✓).
    
    Validation: all three pass critique + audit + adapt; C additionally
    passes motion validation Pass 6.
    
    Next: iterate any variant via chat ("make B's hero quieter") or
    approve via the standard prototype approval flow (records the
    approval in state.json).
    

The summary is the user's only direct touchpoint with the three variants. Keep it short — the work is on disk and openable.

The three-variant role contract (hard)

VariantPitchCompositionMotionStakeholder
A"Tomorrow's version."Same IA + improvements appliedStaticRisk-averse green-light buyer
B"What if we amplified <captured trait>?"One captured-but-underused trait foregrounded in IA / composition / voiceStaticDesign team that wants brand exploration
C"What if motion was part of the identity?"Same IA as AFully cinematic, register from brand surfaceVisionary buyer + design lead

This contract is non-negotiable. The "C is cinematic" rule is how uplift reliably ships a third proposition that's defensibly different from A and B (rather than the C-cliff failure mode of "everything from B but bigger").

If the captured brand surface can't support three differentiated variants (e.g. the palette has only one color, the captured page has only two sections, the brand register doesn't map cleanly to any motion register), reduce to two variants (A + C) via --two-variants rather than ship three weak ones.

Hard constraints

Inherited from the underlying skills — uplift does not re-state them but relies on them being enforced:

  • Mode A pinning — palette + typography from captured brand surface. Enforced by direct/SKILL.md § Mode A.
  • IA priority preservation — configurator stays above the fold, crisis affordances stay first-viewport, etc. Enforced by direct/SKILL.md § IA-priority preservation audit.
  • Density floor — brand-register pages with > 5 sections cap sectionPadding.desktop at ≤ 64px. Enforced by direct/SKILL.md § Hard floor enforcement.
  • Variant differentiation — each variant differs from the others by ≥ 2 changes. Enforced by direct/SKILL.md § Variant differentiation contract.
  • Captured images reused in semantic positions — hero stays hero, story image stays story image. Enforced by prototype/reference/proposed-file-shell.md § Content sourcing hierarchy.
  • No fabricated content — stats, addresses, quotes, named persons rendered as [data-placeholder] not invented. Enforced by prototype/SKILL.md Phase 2 § Content sourcing scan.
  • Site favicon in every variant's head — when stardust/current/assets/favicon.<ext> exists, each variant page inlines it as a data: URI <link rel="icon">. Enforced by prototype/reference/proposed-file-shell.md § Hard requirements #8.
  • C-cliff refusal for variant C — variant C bets on motion, not on "everything from B but more." Enforced by prototype/reference/motion-validation.md § Pass 6f motion C-cliff detector.
  • Reduced-motion fallback for variant C — every motion element is neutralized under prefers-reduced-motion: reduce. Enforced by prototype/reference/motion-validation.md § Pass 6b.

When any of these gates refuses, uplift surfaces the refusal verbatim from the underlying skill — the user sees the specific violation, not a generic "uplift failed" message.

Stop conditions

Stop and ask only if:

(a) Extract fails — site unreachable, structure unparseable, bot-management blocks past the headed-Chrome fallback. (b) Brand surface insufficient — palette has fewer than 2 distinct colors after clustering; OR the captured page has fewer than 3 sections; OR the captured PRODUCT.md Brand Personality maps to none of the five motion registers. Surface honestly: "the captured brand surface is too thin for three differentiated variants — render one strong variant instead?" (c) Improvements list empty — Phase 2a cannot name 3 specific weaknesses. Without specifics, variant A has no brief and "uplift" has no claim. Surface honestly. (d) Two candidates equally weak — if B's "what if…" candidate and C's cinematic candidate would amplify the same captured trait, the variants would not differentiate. Switch to --two-variants (A + C only). (e) Hard rule conflict — captured palette has a single color, captured typography has no display register, captured site has no system components. Brand-faithful constraint impossible without invention. Surface and ask.

The skill does not stop for confirmation in normal flow. The "PROCEED. Run all phases without stopping" property of the original presales prompt is preserved.

Outputs

stardust/
├── state.json                              ← extracted + 3× prototyped
├── direction.md                            ← resolved direction + 3 variant declarations
├── uplift-improvements.md                  ← load-bearing weakness list (≥ 3 items)
├── uplift-questions.md                     ← 6–8 "what if…" candidate list with disqualifications
├── current/                                ← from extract
│   ├── PRODUCT.md
│   ├── DESIGN.md
│   ├── DESIGN.json
│   ├── brand-review.html
│   ├── _brand-extraction.json
│   ├── _crawl-log.json
│   ├── pages/<slug>.json
│   └── assets/
└── prototypes/
    ├── <slug>-A-shape.md
    ├── <slug>-A-proposed.html              ← faithful + improvements
    ├── <slug>-B-shape.md
    ├── <slug>-B-proposed.html              ← "what if amplifying <trait>"
    ├── <slug>-C-shape.md
    ├── <slug>-C-proposed.html              ← static fallback for C
    ├── <slug>-C-cinematic.html             ← cinematic variant C
    ├── lenis.min.js                        ← copied from skill assets
    └── lenis.min.css

PRODUCT.md                                  ← shared (Mode A)
DESIGN.md / DESIGN.json                     ← shared
DESIGN-A.md / DESIGN-A.json
DESIGN-B.md / DESIGN-B.json
DESIGN-C.md / DESIGN-C.json                 ← carries motion.register

Scope

  • One page per run. Multi-page redesigns use the standard extract → direct → prototype chain.
  • Three review surfaces, not a deployable bundle. After the brand owner picks a variant, iterate via chat-driven impeccable commands and approve via the standard prototype approval flow. Migration is the stardust migrate skill.

References

  • reference/what-if-candidates.md — the eight worked captured-trait amplification candidates that B and C pick from, plus the § Extension rule for evidence-shaped derived candidates.
  • skills/stardust/reference/reference-research.md — procedure for sourcing real-world design references (Phase 2.5): when to fire, the 3–5 reference budget, the evidence shape, provenance recording.
  • ../prototype/reference/motion-registers.md — register catalog and selection heuristic used in Phase 3a.
  • ../prototype/reference/motion-validation.md § Pass 6 — cinematic-mode validation gates that fire for variant C.
  • ../prototype/SKILL.md — multi-variant rendering and motion driven by the per-variant DESIGN-<id>.json files direct wrote in Phase 4, not by a CLI selector or flag (uplift never passes --cinematic).
  • ../direct/SKILL.md § Phase 2.6 — multi-variant fork; uplift passes the three-variant declaration through.
  • ../stardust/reference/data-attributes.md — structural section attributes applied by prototype to all three variants.
  • ../prototype/reference/proposed-file-shell.md — content sourcing hierarchy and placeholder convention.

Sponsors

Details

Marketplace
adobe/skills
Source
plugins/stardust
Author
Adobe
Category
Design
License
Apache-2.0
Keywords
design, redesign, frontend, skills, impeccable

More from adobe/skills

All 19