Docs›Commands

02 ·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.

On this page
  1. /stardust:upliftshortcut
  2. /stardust:extract01
  3. /stardust:direct02
  4. /stardust:prototype03
  5. /stardust:migrate04
  6. /stardust:distilloptional

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. The optional distill step turns user-provided design samples into a brief that direct reads as anchor references.

/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
Addendum

/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:distill — optional

Optional pre-extract step. Read a directory of user-provided design samples — static HTML mocks plus a manifest of live URLs — and produce a structured trait matrix + narrative brief that direct reads as anchor references. Use when the redesign direction has been pre-set by an art director and arrives as a folder of references.

Syntax

›/stardust:distill [samples-dir] [flags]

Flags

[samples-dir]
Optional positional. Defaults to samples/. Expects a directory containing static/<sample>/ subdirs and/or a live/urls.json manifest.
--from-static
Distill only static samples; skip live fetching.
--from-live
Distill only live samples; skip static parsing.
--cap <N>
Cap live URLs to fetch. Default 8 — enough to triangulate a visual language without burning budget on near-duplicates.
--refresh
Re-fetch and re-parse every sample even when cached snapshots exist.

Writes

  • samples/SAMPLES.md narrative vocabulary brief — direct reads this under Mode B
  • samples/trait-matrix.json per-sample + cross-sample design tokens
  • samples/live/snapshots/ cached DOM + screenshots from live URLs
  • stardust/state.json adds samples.distilledAt + inventory

Example

›/stardust:distill # defaults to ./samples/
›/stardust:distill samples/q2-refresh --cap 12