Docs › Commands

Every sub-command,
named.

Reference for the Stardust sub-commands. Inputs, common flags, and the artifacts each one writes.

You don't need to memorize the syntax. Every command and flag can be triggered through plain conversational intent — Stardust reads your phrasing and routes it. The reference below is the canonical form, not a requirement.

  1. /stardust:uplift|shortcut
  2. /stardust:extract|01
  3. /stardust:direct|02
  4. /stardust:prototype|03
  5. /stardust:migrate|04
  6. /stardust:deploy|AEM
  7. /stardust:diff|AEM

The main flow is four commands in order — extract describes the current state, direct resolves a target, prototype renders proposed redesigns, migrate ships deployable HTML. Each writes its own artifacts under stardust/; the next reads them. You can run them in order, or jump in at any point. For a presales pitch deck, the uplift shortcut collapses extract → direct → three variants into one command. To ship to AEM Edge Delivery, deploy converts the approved page into authorable EDS blocks and diff verifies the built page against the source prototype.

stardust:uplift

One URL in. Three presales-quality redesign variants out. Collapses extract → direct → prototype × 3 into one opinionated command — every variability axis is picked from the captured brand surface rather than asked. Variant C is always cinematic.

Syntax

› /stardust:uplift <url> [flags]

Flags

  • <url> :: Required. The page to redesign. Defaults to the homepage when the URL has no path.
  • --page <slug> :: Override the slug if the URL points elsewhere or you want a different surface.
  • --cinematic-register <name> :: Override the auto-picked register for variant C. One of arrival, kinetic-display, live-systems, editorial, kinetic-grid. Records registerSource: "user-override" in C's provenance.
  • --two-variants :: 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.

Writes

  • stardust/uplift-improvements.md :: five specific captured-site weaknesses — load-bearing for variant A
  • stardust/uplift-questions.md :: "what if…" candidate walk with disqualifications
  • stardust/direction.md :: resolved direction + three variant declarations
  • stardust/prototypes/<slug>-{A,B,C}-proposed.html :: three rendered variants
  • stardust/prototypes/<slug>-C-cinematic.html :: cinematic variant C
  • DESIGN-{A,B,C}.{md,json} :: per-variant design specs at project root

Example

› /stardust:uplift https://example.com
› /stardust:uplift https://example.com/about --cinematic-register editorial
› /stardust:uplift https://example.com --two-variants # thin surface

The three-variant role contract is non-negotiable. A is "tomorrow's version of the site you have today." B is "what if we amplified <captured trait>?" C is "what if motion was part of the identity?" Uplift refuses to ship three weak variants — if the brand surface can't differentiate three, it drops to two automatically.

stardust:extract

Capture a brand surface — palette, typography, voice, motifs. Most often from a live URL (Stardust crawls it), but also from a prompt, a document, a Figma file, or any other source where brand traits can be read. Descriptive only; does not modify the source.

Syntax

› /stardust:extract [url] [flags]

Flags

  • [url] :: Optional. The most common source. If supplied, Stardust crawls the origin (a path narrows to a subtree). If omitted, supply another source via the chat — a prompt describing the brand, a document, a Figma URL, an image.
  • --cap <N> :: URL crawl only. Override the default 5-page cap. Stardust picks the home plus four IA pillars by default.
  • --all :: URL crawl only. Lift the cap entirely. Crawl every discovered page after junk filtering.
  • --pages <slug,…> :: URL crawl only. Restrict the crawl to specific paths. Bypasses the cap.
  • --refresh <slug> :: Re-extract one page that already exists in state.json.
  • --wait <mode> :: URL crawl only. Wait strategy per page: fast, medium (default), spec, or auto. Use spec for JavaScript-driven sites.

Writes

  • stardust/current/PRODUCT.md :: descriptive snapshot of the captured brand
  • stardust/current/DESIGN.md :: + DESIGN.json — captured visual surface
  • stardust/current/brand-review.html :: eyeball-check artifact
  • stardust/current/pages/<slug>.json :: per-page parsed structure + content (URL crawl)
  • stardust/current/_brand-extraction.json :: consolidated brand surface
  • stardust/state.json :: pages: extracted

Example

› /stardust:extract https://example.com --cap 10 --wait spec
› /stardust:extract # with a Figma URL or document attached in chat

New site, no source to extract from? Stardust supports designing new sites too — provide a brief about the new brand and it will roll a fresh seed without an inherited surface. Redesigning an existing source is the main supported use case today; new-site design works but is less battle-tested.

stardust:direct

Resolve a redesign direction from a freeform phrase. Writes the target spec — what the site should become.

Syntax

› /stardust:direct "<phrase>" [flags]

Flags

  • "<phrase>" :: Optional positional. Your freeform redesign intent — "more editorial", "feel more premium on mobile", "keep typography and palette". If omitted, Stardust asks for one.
  • --re-direct :: Replace the current direction with a new one. Stale-flags any prototyped, approved, or migrated pages.
  • --rebrand :: Force rebrand mode — full divergence-seed roll, no brand-faithful inheritance. The default is brand-faithful when the captured surface has signal; this flag opts out.

Writes

  • PRODUCT.md :: at project root — target product spec
  • DESIGN.md + DESIGN.json :: at project root — target design system
  • stardust/direction.md :: resolved direction + full reasoning trace
  • stardust/state.json :: pages: extracted → directed

Example

› /stardust:direct "more editorial. lean into typography. keep the palette."

stardust:prototype

Generate a proposed redesign for one page or all directed pages. Writes a per-page composition brief, then renders the proposed HTML, then opens a before/after viewer.

Syntax

› /stardust:prototype [slug] [flags]

Flags

  • [slug] :: Optional positional. Prototype just this page. Without it, prototype every directed page that isn't stale.
  • --refresh-stale :: Re-prototype every page flagged stale by a direction change.
  • --all :: Prototype every directed page, including stale ones.
  • --no-iterate :: Render the proposed file and open the viewer, but skip the iteration loop. You iterate manually later.
  • --no-critique :: Skip the automatic post-render critique pass. Default behaviour gates prototyped status on P0/P1 findings.
  • --cinematic :: Layer a cinematic motion register on top of the static prototype. Register is read from DESIGN.json.extensions.motion.register (written by direct); falls back to the auto-selection heuristic if absent. Output is <slug>-cinematic.html, alongside the static <slug>-proposed.html — never replacing it.
  • --cinematic=<register> :: Same as --cinematic but forces a specific register: arrival, kinetic-display, live-systems, editorial, or kinetic-grid. Recorded as registerSource: "user-override" so reviewers can spot when direction's heuristic was bypassed.

Writes

  • stardust/prototypes/<slug>-shape.md :: per-page composition brief
  • stardust/prototypes/<slug>-proposed.html :: the proposed redesign
  • stardust/prototypes/<slug>-cinematic.html :: cinematic overlay (when --cinematic is set)
  • stardust/prototypes/<slug>.html :: before/after viewer
  • stardust/state.json :: page status: directed → prototyped

Example

› /stardust:prototype home
› /stardust:prototype home --cinematic
› /stardust:prototype home --cinematic=editorial
› /stardust:prototype # every directed page

stardust:migrate

Emit deployable static HTML from approved prototypes. The final step. Output is yours to publish anywhere.

Syntax

› /stardust:migrate [slug] [flags]

Flags

  • [slug] :: Optional positional. Migrate just this page. Without it, migrate every page whose status is directed, prototyped, or approved (and not stale).
  • --refresh-stale :: Re-migrate every page flagged stale. Default skips them.
  • --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 migrates directed pages too.
  • --strict-canon :: Refuse approvals that conflict with canon. Default logs the deviation and continues.

Writes

  • stardust/migrated/<slug>.html :: deployable static page
  • stardust/migrated/assets/ :: media + fonts + anything referenced
  • stardust/state.json :: page status: prototyped/approved → migrated

Example

› /stardust:migrate home
› /stardust:migrate # whole site

+stardust:prepare-migration

Before migrate can run at scale, the project needs a typed-page catalog, a module catalog, canon, and downloaded assets. prepare-migration orchestrates that cascade. It runs extract --prep, direct --prep, prototype --prep, and an assets-prep phase in sequence, with confirmation gates between phases.

Syntax

› /stardust:prepare-migration [flags]

Flags

  • --from <phase> :: Resume the cascade from a specific phase. Values: extract, direct, prototype, assets. Default starts from the earliest incomplete phase.
  • --skip-confirm :: Skip the per-phase confirmation gates. Useful for re-runs where the catalog is already settled.
  • --canon-from <slug> :: Override the default canon-author (which is home). Forwarded to prototype --prep when that phase runs.

Writes

  • state.json.pages[].type :: page typing — set by extract --prep
  • DESIGN.json.extensions.modules[] :: module catalog — confirmed by direct --prep
  • DESIGN.json.extensions.colorReservations[] :: color reservations — by direct --prep
  • stardust/canon/ :: header, footer, css, modules — by prototype --prep
  • stardust/migrated/assets/favicon-* :: favicon variants — by assets prep
  • stardust/migrated/assets/fonts/ :: downloaded webfont files — by assets prep

Example

› /stardust:prepare-migration
› /stardust:prepare-migration --from prototype --canon-from about

Why the two-step boundary? The split between prepare-migration and migrate is intentional. It makes "I'm committing to migrate this site" a conscious gesture and keeps idempotency obvious — re-running prep resumes from the earliest incomplete phase without re-doing settled work.

stardust:deploy — ship to AEM

Convert an approved Stardust prototype into an AEM Edge Delivery experience and deploy it. Each prototype section becomes one independent EDS block — the section's CSS becomes that block's scoped stylesheet, and its text and images become authorable. Header and footer drop into static fragments; the page ships as a content fragment to AEM. Targets a project on the AuthorKit runtime; a vanilla aem-boilerplate is bootstrapped first.

Syntax

› /stardust:deploy [prototype]

Requires

  • An EDS project :: A project at the repo root with blocks/, styles/, scripts/, and head.html. A vanilla aem-boilerplate triggers a runtime bootstrap (the AuthorKit runtime is ported in) before conversion.
  • [prototype] :: The approved prototype to convert. Defaults to discovering prototypes under stardust/prototypes/ (or a samples/ folder); JSX prototypes are pre-rendered to static HTML first.

Writes

  • blocks/<block>/ :: one block (decorate JS + scoped CSS) per prototype section
  • styles/styles.css :: foundation tokens, global reset, self-hosted fonts
  • fragments/header.html + fragments/footer.html :: static chrome
  • the content page :: a body fragment, shipped to AEM via the source API

Example

› /stardust:deploy # convert + ship the approved prototype

stardust:diff — verify the build

Reconcile a built page against its source prototype with two complementary probes: a pixel/layout diff (stretched images, dropped wraps, blank renders, colour flips) and a structural content + typography diff (dropped or mis-slotted headings, eyebrows, CTAs; rendered-face font forks). Run both — either alone gives a false "looks fine". Stack-agnostic via profiles.

Syntax

› /stardust:diff <prototypeURL> <buildURL> [flags]

Flags

  • --profile <eds|generic> :: Remediation language + thresholds. eds (default) carries Edge Delivery / DA hints; generic is neutral for any prototype↔build comparison.
  • --width <px> :: Viewport width for both renders. Default 1280.
  • --main <selector> :: Content-root selector for the structural diff. Defaults to the profile's root.
  • --sections <a,b> :: Per-section screenshots for the pixel probe.
  • --json :: Dump both role-classified inventories as JSON.

Outputs

  • a structural report :: 🔴 missing / role-swapped content · 🟡 body drift · 🟠 font forks
  • a pixel/layout report :: geometry, image, and colour red flags
  • <out>/ screenshots :: per-section captures when --sections is set

Example

› /stardust:diff "$PROTO" "$BUILD" --profile eds
› /stardust:diff "$PROTO" "$BUILD" --profile generic # any stack