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 to do
useful work. Lift the cap with --cap 25 (the previous default)
or higher 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
explicitly includes the consent surface, or when the
dismissal's side-effects (script activation that wouldn't
otherwise run) need to be avoided. Default behaviour is to
dismiss; the contract preserves screenshots, voice
aggregation, and per-section style from being polluted by
the banner.
--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:
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 do import { chromium } from 'playwright',
and ESM module resolution does not honour a global install or
NODE_PATH. On a vanilla aem-boilerplate target (no
node_modules) that import throws ERR_MODULE_NOT_FOUND even
though npx playwright --version succeeds. So 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 --no-save --legacy-peer-deps (or
use the Playwright MCP server) before crawling. The
--legacy-peer-deps flag is required on aem-boilerplate targets
— its pinned eslint@8 conflicts with @babel/eslint-parser@8's
peer range and a plain npm i exits ERESOLVE before playwright
is even considered (six-site e2e finding). Don't trust the CLI
probe alone.
--no-save installs are ephemeral (stardust-style e2e
finding). Any later real npm i (e.g. deploy's bootstrap
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 — so running crawl.mjs from the plugin path
throws ERR_MODULE_NOT_FOUND even when the project has playwright
installed. Copy the script byte-identical into the project
(stardust/scripts/crawl.mjs) and run the copy; it resolves
against the project's node_modules.
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
(node skills/extract/scripts/crawl.mjs --url <origin> [--pages …] [--max N] [--concurrency N]) over hand-rolling a Playwright
script per run; extend
its in-page capture() to cover any recipe field it doesn't yet
emit.
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.
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.
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
headless: false, channel: 'chrome' per
reference/playwright-recipe.md § Bot-management fallback 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:
Fetch <origin>/sitemap.xml, then <origin>/sitemap_index.xml,
then check robots.txt for Sitemap: directives.
If no sitemap is reachable, run a same-origin BFS crawl from
<url>, depth-limited to 3, link-extracting from rendered HTML.
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).
De-duplicate trailing-slash variations.
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.
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. The default cap is small enough that the common
case is "extract 5 pages and move on"; pausing for a yes/no
reply on every run is friction without value. 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: page-type checklist first, then score-based
ranking (home + IA-pillar keywords + sitemap priority − archive /
version markers). See reference/ia-extraction.md § Page
selection and § Priority for the cap. The English-only keyword
list is a known limitation for localized sites.
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: the page queue is drained by --concurrency
parallel browser contexts (default 4, sane range 4–8), each applying
the full recipe independently; media resolves / HEAD checks are
batched with Promise.all. See § 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 enterprise CMSes,
where 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 from extract — and so
enterprise-CDN images that 404 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)
Save to stardust/current/pages/<slug>.json with _provenance as the
first key. 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 lovesac 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?
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. 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>.
- 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). Without this elevation, downstream
prototype reasons over a 16-image list and frequently picks
the og:image instead of the live hero.
- 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 it
is lost in the raw media list and 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:
- For PRODUCT.md, follow the section structure in impeccable's
reference/teach.md. Populate Register from the brand surface
(sites that read as marketing/landing → brand; tools/dashboards →
product; ambiguous → brand with a note). Populate Users,
Product Purpose, Brand Personality, Anti-references, and
Design 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.
Stardust does not invoke $impeccable 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 in the JSON (a wrong dominant radius, a missing system
component, a single-page palette bias) are obvious to the eye in five
seconds and invisible in JSON until someone notices. Putting the
review at the end of extract catches misreads while they are still
cheap to fix — re-extract is fast; re-direct + re-prototype is not.
The template is mandatory. In particular:
- 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.
- Render in the brand's own captured colors and fonts, not a
stardust shell.
- Embed all CSS; do not load external JavaScript or fonts unless
the live site already does.
- 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:
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
Print a one-screen summary:
Extracted https://example.com (5/38 pages, sitemap.xml)
stardust/current/
PRODUCT.md (register: brand, inferred from landing)
DESIGN.md (5 colors, 2 type families, 3 motifs)
brand-review.html (4 tensions surfaced)
pages/ (5 files)
assets/logo.svg (extracted from inline SVG)
_brand-extraction.json
_crawl-log.json
Per-page evidence:
slug live waitMode waitMs status media(img/bg)
/ yes medium 2380 200 38/6
/about yes medium 2110 200 12/2
/pricing yes medium 1940 200 9/0 ⚠ low-media
/products yes medium 2640 200 21/4
/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. The brand
surface and brand-review use cross-page aggregation, so 5 pages
covering distinct templates is usually sufficient. To extract
more, re-run with --cap <N> (e.g. --cap 25) or list specific
slugs with --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 — this should never
happen given the write-time guard, but the visible column is
the defense-in-depth signal that catches the failure mode
when it does (the 2026-04-30 lovesac synthesis bug went four
phases deep before being caught because no report column
surfaced the missing provenance). 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 — getComputedStyle(el).backgroundImage read
before the element was styled, a ::before/::after host missed,
or product imagery gated behind interaction the reveal pass did not
trigger. The recipe already specs the full background walk
(playwright-recipe.md § Capture list 11, hardened after the
2026-05-04 ups.com dropped-hero failure), but a thorough spec that
silently produces nothing still ships an image-less capture: the
2026-06-26 knack.com run returned cssBackgrounds: [] on every
page and lost all product screenshots, hero art, and customer
logos, and nothing surfaced it because no column reported media
coverage. 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. Both are
opt-in; without them this section is inert.
--brand-source <url> (repeatable) — sibling enrichment
An additional same-brand origin whose brand surface enriches the
primary extraction. Per source: shallow capture only — home page plus
up to 2 nav-linked pages, full recipe per page (Phase 2 rules apply,
provenance contract included). Captured records land under
stardust/current/brand-sources/<host>/ (own pages/ +
assets/screenshots/, same page-JSON shape); they are evidence,
not inventory — they never enter state.json.pages[].
Their palette / type / motif / voice / photography evidence
aggregates into _brand-extraction.json with per-origin
provenance (origins[] per reference/brand-surface.md § Origins).
Two rules govern the merge:
- Conflicts resolve toward the primary. Where primary and
brand-source evidence disagree for the same slot (a palette role,
the heading family, the signature radius), the primary origin's
value wins; the losing value is noted in
_provenance.notes.
- Brand-source evidence widens the surface. A motif or
photography treatment the primary site underuses enters as an
additional entry, attributed in
origins[].contributedSignals[]
— so downstream direct / uplift can amplify a trait captured
on a sibling property as captured evidence with an origin
citation, never as invention.
Brand-source pages join palette/type/motif/voice aggregation but are
excluded from § System components, voiceTable, and cross-promo
detection — those describe the primary site's IA.
--design-source <url> — design donor
Formalizes the proven canon.com pattern: a golden design source is
extracted separately and its design system becomes the fixed
target, while the primary origin supplies content.
- Capture the donor to
stardust/canon-source/ — same page-JSON and
brand-extraction shapes as stardust/current/, rooted there (own
pages/, assets/, _brand-extraction.json, _crawl-log.json).
The default cap (5) applies unless the user widens it.
- Derive
stardust/canon-source/DESIGN.md + DESIGN.json from the
donor's brand surface — descriptive, same authoring rules as
Phase 4.
- Stamp
state.json.designSource = { "url", "capturedAt", "path": "stardust/canon-source/" }.
stardust:direct reads this stamp and pins the donor system as the
target: Mode A's brand-faithful pins transfer to the donor
surface while content stays with the primary origin — see
skills/direct/SKILL.md § Mode A. The donor records
role: "design-source" in its own
canon-source/_brand-extraction.json#origins[]; 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
| Path |
Purpose |
stardust/current/PRODUCT.md |
Descriptive strategy of the existing site (impeccable format) |
stardust/current/DESIGN.md |
Descriptive visual system (Stitch format) |
stardust/current/DESIGN.json |
Sidecar with extensions for motifs, voice, components |
stardust/current/brand-review.html |
Self-contained visual review of the extraction (first eyeball-able artifact) |
stardust/current/pages/<slug>.json |
Per-page parsed structure + content |
stardust/current/assets/logo.<ext> |
Extracted logo |
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.json |
Consolidated brand surface (palette, type, motifs, voice, system components) |
stardust/current/_crawl-log.json |
Discovery + crawl audit trail (incl. visionCheck[], siblingCandidates[]) |
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.json |
Updated 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).
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.
Switch to headless: false, channel: 'chrome' per
reference/playwright-recipe.md § Bot-management fallback. Do
not retry headless: it will fail identically. The headed
fallback works against most enterprise / commerce origins;
playwright-extra + stealth plugin is a non-standard escape
hatch for the residual cases. The headed window pops visibly,
which is acceptable for interactive runs and unacceptable for
unattended pipelines — surface this to the user when first
triggered.
- 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. This was the 2026-04-30 lovesac.com
failure — 20 of 25 pages synthesized this way and the cascade
ran four phases on the synthesized data before the gap was
caught by a meta-question. The synthesis shortcut produces
output indistinguishable from a successful run and propagates
fabricated content through every downstream phase.
Prep mode (--prep)
When invoked with --prep, extract runs an extended pass that
prepares the inventory for migration. Discovery-mode runs (without
--prep) are unchanged: small cap, no typing, no module detection,
presales-friendly. --prep is the gesture that says "the user is
committing to migrate; build the data structure migrate consumes."
--prep adds five things on top of the standard procedure:
1. Lift the cap
--prep implies --all. Migration coverage requires the full
inventory — the small discovery cap (5 pages) is insufficient. The
cap-respecting selection logic from reference/ia-extraction.md
§ Page selection still applies for ordering and junk-filtering;
it just doesn't truncate.
Sub-agent prompt requirements (when delegating)
When --prep is heavy enough that the agent delegates extraction
to a sub-agent (a presales-shaped pattern when the inventory is
large), the sub-agent prompt must:
- Forbid synthesis by name. The literal sentence
*"do not synthesize a page record from
_brand-extraction.json
- URL patterns + captured photos; every page must be a live
Playwright render"* must appear in the prompt. The earlier
wording "must actually invoke Playwright per page" was
satisfiable in spirit by synthesis-with-photo-reuse and
produced the lovesac failure. Naming the shortcut explicitly
closes that loophole.
- Require a per-page evidence table in the return. Columns:
slug | waitMode | waitMs | fetchedAt | httpStatus. The
parent agent reads this table on completion and aborts if
any row is missing or shows waitMs: 0.
- Require the wait-summary line in the return, formatted
identically to Phase 6's wait summary, so the parent can
surface it in the user-facing report without reformatting.
These three are mandatory; missing any of them in the sub-agent
prompt is itself a recipe violation. The cascade-level guard in
prepare-migration validates the resulting per-page JSONs via
validateProvenance() regardless — but a well-formed sub-agent
return makes the failure cheaper to diagnose.
2. Page typing
For each extracted page, infer the type field from URL pattern
and content shape (LLM judgment). Catalog from
skills/stardust/reference/state-machine.md § Page types:
landing | article | listing | program | form | static | unique.
Write the inferred type to state.json.pages[].type. The user
confirms or refines during direct --prep. Discovery-mode runs
leave type as null.
3. Module candidate detection
After Phase 3 (brand-surface extraction), scan extracted pages for
recurring structural patterns. A pattern that appears in N
…(truncated)
1---2name: extract3description: Crawl an existing website (capped, multi-page) and seed stardust/current/ with PRODUCT.md, DESIGN.md, DESIGN.json, a per-page inventory, and the consolidated brand surface — the captured design system, palette, typography, motifs, and voice of the live site. Use when the user wants to analyze an existing site's design, extract or reverse-engineer its design system or brand, capture design tokens from a live site, import a website as the starting point for a redesign, capture the current state before a migration, or invokes /stardust:extract. Trigger phrases include "analyze this site", "extract the design tokens", "capture the brand", "crawl the site", "reverse engineer the design". Not for scraping page data or content for its own sake (it captures design evidence, not datasets), and not for the redesign itself — extraction is descriptive; direction and prototyping happen downstream.4license: Apache-2.05metadata:6 source: https://skillmd.com/skills/adobe/extract7---89# stardust:extract1011Crawl an existing website, parse each page, extract the brand surface,12and produce a stardust-formatted snapshot of the current state under13`stardust/current/`. The output describes what the site **is**; later14sub-commands consume it to decide what it **should be**.1516This skill is **descriptive**: it does not invent direction, it does not17critique, and it does not modify the live site. It writes only under18`stardust/current/` and updates `stardust/state.json`.1920## Inputs2122- `<url>` — required. The origin to crawl. Examples: `https://example.com`,23 `https://example.com/shop`. A path narrows the same-origin crawl to24 that subtree.25- `--cap <N>` — optional. Override the default 5-page cap. The cap26 is intentionally small — a 5-page sample (home + four IA27 pillars/templates) is enough for cross-page brand aggregation,28 system-component detection, and the brand-review HTML to do29 useful work. Lift the cap with `--cap 25` (the previous default)30 or higher when a deeper crawl is genuinely needed.31- `--all` — optional. Lift the cap entirely; extract every32 discovered page after junk filtering. Equivalent to `--cap 0`.33 Use when the user spontaneously asks for a full crawl.34- `--pages <slug,slug,...>` — optional. Restrict the crawl to specific35 paths (slugs derived per `reference/ia-extraction.md`). Bypasses36 the cap.37- `--refresh <slug>` — optional. Re-extract one page that already exists38 in `state.json`.39- `--single` — optional. Equivalent to `--cap 1`. Useful for testing.40- `--wait <fast|medium|spec|auto>` — optional. Wait strategy per page.41 Default `medium`. See `reference/playwright-recipe.md` § Wait modes.42- `--no-junk-filter` — optional. Disable the default junk-page filter43 in discovery (see `reference/ia-extraction.md` § Filtering).44- `--no-consent-dismiss` — optional. Skip the pre-flight consent /45 cookie banner dismissal (see `reference/playwright-recipe.md`46 § Pre-flight: consent dismissal). Use when the redesign scope47 explicitly includes the consent surface, or when the48 dismissal's side-effects (script activation that wouldn't49 otherwise run) need to be avoided. Default behaviour is to50 dismiss; the contract preserves screenshots, voice51 aggregation, and per-section style from being polluted by52 the banner.53- `--concurrency <n>` — optional. Parallel browser contexts for the54 per-page capture loop. Default 4; sane range 4–8. See55 § Concurrency.56- `--brand-source <url>` — optional, repeatable. An additional57 **same-brand** origin whose brand surface enriches the primary58 extraction (shallow capture: home + up to 2 nav-linked pages).59 See § Cross-site brand sources.60- `--design-source <url>` — optional. Design-donor origin: its61 design system is captured to `stardust/canon-source/` and becomes62 the fixed redesign target while the primary origin supplies63 content. See § Cross-site brand sources.64- `--prep` — optional. Run in **migrate-prep mode**: lift the cap,65 type each page, detect module candidates, capture typed content66 slots, emit the prep summary. See § Prep mode below. Typically67 invoked via the `prepare-migration` orchestrator skill rather68 than directly.6970## Setup7172Run the master skill's setup procedure first73(`skills/stardust/SKILL.md` § Setup): impeccable dep check, context74loader, state read.7576Additional checks for this sub-command:77781. **Playwright availability.** The extraction step needs a real79 browser. Detect Playwright in this order: a Playwright MCP server,80 then a project-importable `playwright` module. **The `npx81 playwright` probe is NOT sufficient** — it confirms the CLI82 (which resolves a global install) but the recipe and83 `scripts/crawl.mjs` do `import { chromium } from 'playwright'`,84 and ESM module resolution does **not** honour a global install or85 `NODE_PATH`. On a vanilla `aem-boilerplate` target (no86 `node_modules`) that import throws `ERR_MODULE_NOT_FOUND` even87 though `npx playwright --version` succeeds. So verify the module is88 import-resolvable from the project root (probe:89 `node -e "import('playwright').then(()=>process.exit(0))"`); if it90 isn't, run `npm i -D playwright --no-save --legacy-peer-deps` (or91 use the Playwright MCP server) before crawling. The92 `--legacy-peer-deps` flag is required on `aem-boilerplate` targets93 — its pinned `eslint@8` conflicts with `@babel/eslint-parser@8`'s94 peer range and a plain `npm i` exits `ERESOLVE` before playwright95 is even considered (six-site e2e finding). Don't trust the CLI96 probe alone.9798 **`--no-save` installs are ephemeral (stardust-style e2e99 finding).** Any later real `npm i` (e.g. deploy's bootstrap100 adding a devDependency) prunes non-manifest packages, silently101 removing playwright mid-pipeline. Every downstream skill that102 renders (prototype, migrate, deploy, diff) must re-run the103 import-resolvability probe — and re-install on failure — at the104 start of its own run, not assume extract's install survived.105106 **Script location matters.** ESM resolves `import 'playwright'`107 from the *script's* directory, and the plugin tree ships no108 `node_modules` — so running `crawl.mjs` from the plugin path109 throws `ERR_MODULE_NOT_FOUND` even when the project has playwright110 installed. Copy the script byte-identical into the project111 (`stardust/scripts/crawl.mjs`) and run the copy; it resolves112 against the project's `node_modules`.113114 **Bundled crawler.** `skills/extract/scripts/crawl.mjs` is a115 runnable reference implementation of this whole sub-command —116 browser config + bot-management fallback, consent dismissal, wait117 + scroll, the capture list, per-page full-page screenshots118 (`assets/screenshots/<slug>.png`, consumed by the Phase 2.5119 vision gate), response validation, and the §120 Capture-hygiene hardening (visibility filter, interstitial drop,121 SPA-shell flag, modal `textContent` capture, tracking-pixel122 discounting, cross-page duplicate detection). Prefer invoking it123 (`node skills/extract/scripts/crawl.mjs --url <origin> [--pages …]124 [--max N] [--concurrency N]`) over hand-rolling a Playwright125 script per run; extend126 its in-page `capture()` to cover any recipe field it doesn't yet127 emit.1282. **Origin collision.** If `stardust/state.json` already records129 `site.originUrl` and the new `<url>` is a different origin, stop and130 ask before clobbering. Stardust does not silently mix two sites in131 one project.1323. **Browser contexts.** Open a fresh `BrowserContext` per capture133 worker (§ Concurrency; default 4). Run the **consent dismissal134 pre-flight** per `reference/playwright-recipe.md` § Pre-flight:135 consent dismissal *unless* `--no-consent-dismiss` is set.136 Cookies persist within a context but **not across contexts** —137 re-establish consent state per context (re-run the dismissal on138 the worker's first page, or clone the probe context's139 `storageState`). Record the resolved method in140 `_crawl-log.json#consent.method`.1414. **Bot-management probe.** When the first navigation in the run142 returns `ERR_HTTP2_PROTOCOL_ERROR` or `ERR_QUIC_PROTOCOL_ERROR`,143 or hangs through the entire hard-cap on what should be a fast144 origin, **do not retry headless**. Switch to145 `headless: false, channel: 'chrome'` per146 `reference/playwright-recipe.md` § Bot-management fallback and147 record the switch in `_crawl-log.json#discovery.fetchTechnique`148 so re-runs start in headed mode without rediscovering the149 issue.150151## Procedure152153### Phase 1 — Discovery154155Discover the page inventory before crawling. Procedure in156`reference/ia-extraction.md`. In summary:1571581. Fetch `<origin>/sitemap.xml`, then `<origin>/sitemap_index.xml`,159 then check `robots.txt` for `Sitemap:` directives.1602. If no sitemap is reachable, run a same-origin BFS crawl from161 `<url>`, depth-limited to 3, link-extracting from rendered HTML.1623. Filter the discovered URL list: same origin only, exclude163 `mailto:`, `tel:`, anchor-only links, query-only variations,164 common asset paths (`.css`, `.js`, `.pdf`, image extensions).1654. De-duplicate trailing-slash variations.1665. Apply the junk-page filter (`reference/ia-extraction.md` §167 Junk-page filter) unless `--no-junk-filter` is set. Surface the168 filtered list to the user as overridable.1696. Apply the cap (default 5, or `--cap`, or `--all` for no cap)170 and **proceed silently**. Print an informational summary of171 what was kept and what was cut — but do **not** gate on user172 confirmation. The default cap is small enough that the common173 case is "extract 5 pages and move on"; pausing for a yes/no174 reply on every run is friction without value. Users who want175 different scope set it spontaneously at command time:176177 ```178 $stardust extract https://example.com # default 5 pages179 $stardust extract https://example.com --cap 25 # bump to 25180 $stardust extract https://example.com --all # lift the cap181 $stardust extract https://example.com --pages home,about,pricing182 $stardust extract https://example.com --single # just the entry URL183 ```184185 The agent reads spontaneous scope intent from the user's prompt186 (e.g. "extract all pages", "look at just the home and pricing",187 "do a full crawl") and applies the equivalent flag. No188 re-confirmation needed once intent is clear.189190 Informational output (not a prompt — proceed immediately):191192 ```193 Discovered 38 pages on https://example.com (sitemap.xml).194 Filtered as likely junk (5): /test/, /sample-page/, /holiday1/, ...195 Selecting 5 highest-priority pages:196 - / (home)197 - /about198 - /pricing199 - /products200 - /contact201202 Cut (28 pages, --all to lift): /blog/post-1, /blog/post-2, ...203204 Extracting...205 ```206207 Selection heuristic: page-type checklist first, then score-based208 ranking (home + IA-pillar keywords + sitemap priority − archive /209 version markers). See `reference/ia-extraction.md` § Page210 selection and § Priority for the cap. The English-only keyword211 list is a known limitation for localized sites.2122137. Write the discovered list to `stardust/current/_crawl-log.json`214 (created if absent) with `_provenance` and the full discovery215 reasoning, including `filteredAsJunk[]` and `userChoice`. This is216 an audit trail, not a state file.217218### Phase 2 — Per-page extraction219220For each page in the cap-respecting list, render with Playwright221following `reference/playwright-recipe.md`. Captures run222**concurrently**: the page queue is drained by `--concurrency`223parallel browser contexts (default 4, sane range 4–8), each applying224the full recipe independently; media `resolves` / HEAD checks are225batched with `Promise.all`. See § Concurrency. The recipe is226mandatory per page — in particular, do not skip the wait, scroll, or227capture-list steps:228229- Viewport 1440 × 900 @ 2× DPR230- Wait per the configured wait mode (default `medium`; see § Wait231 modes in `reference/playwright-recipe.md`)232- Disable animations via `prefers-reduced-motion: reduce`233- After the wait resolves, scroll to bottom in 4 viewport-height234 steps with 300 ms pauses, then return to top — this is required235 to trigger lazy-load and IntersectionObserver-driven content236- Record `waitMs` and `waitMode` in the per-page `_provenance`237238Capture per page (full schema in `reference/current-state-schema.md`):239240- Page metadata (title, meta description, OG tags, theme-color)241- Semantic structure: heading outline, landmark roles, sections242- **Hero headline + lede (resolved)** — `heroHeadline` / `heroLede`243 picked by font-size × hero-region with a junk/hidden-state filter and244 a clean meta-description fallback (per `reference/playwright-recipe.md`245 § Capture list 5-bis). Required for JS-rendered enterprise CMSes,246 where document-order headings surface modal / promo / count junk247 instead of the real tagline.248- Content: visible text per section (full innerText, **no249 truncation** per `reference/playwright-recipe.md` § Capture250 list 7), structured paragraphs (`body[]`), lists, FAQ Q/A251 pairs, and review/testimonial quotes per252 § Capture list 7-bis. Without these structured fields,253 every body region under a heading falls back to placeholder254 signature at migrate time.255- CTA labels and href targets, link inventory (internal vs external)256- Per-section computed style summary: dominant colors, font families257 in use, spacing rhythm, border-radius, shadows258- Media inventory: img with `currentSrc`/`srcset` captured **with259 query strings intact** plus a `resolves` flag (HEAD/GET with browser260 UA + Referer), intrinsic dimensions, inline SVG count, video/iframe261 presence, `cssBackgrounds[]` (including pseudo-element `::before`/262 `::after` walks per § Capture list 11) so `background-image`263 heroes and motifs do not silently disappear from extract — and so264 enterprise-CDN images that 404 are flagged before migrate ships265 `about:error`.266- Font files captured via network-intercept (per § Capture list267 16): every `woff2`/`woff`/`ttf`/`otf` response saved under268 `assets/fonts/` and recorded in `_brand-extraction.json#type.files[]`269 with licensing flag.270- Icon-font detection (per § Capture list 17): when the page271 uses `[class^="icon-"]` with non-default `::before`272 font-family + codepoint, capture the family, save the file,273 and record the `iconClass → codepoint` table in274 `_brand-extraction.json#iconFont`.275- Interactive elements: forms (with field types), buttons, modals276 detected by ARIA roles277- Full-page screenshot to `assets/screenshots/<slug>.png` —278 script-captured by the bundled crawler after the wait/scroll279 settle (viewport-only fallback on extremely tall pages; mode in280 `_signals.screenshotMode`, relative path in the page JSON281 `screenshot` field)282283Save to `stardust/current/pages/<slug>.json` with `_provenance` as the284first key. Save referenced media to `stardust/current/assets/media/`285preserving basename plus a short content hash.286287**Live-render evidence (synthesis is forbidden).** Refuse to mark288a page `extracted` in `state.json` unless its `_provenance`289contains `renderedBy: "playwright"`, an ISO-8601 `fetchedAt`, a290positive integer `waitMs`, a `waitMode` from the recipe, and a291final `httpStatus` in the 2xx/3xx range. These five fields are292the contract enforced by `reference/current-state-schema.md`293§ Live-render evidence and read back by every downstream phase294via `validateProvenance()` per295`skills/stardust/reference/state-machine.md` § Provenance296validation. Synthesizing a page record from297`_brand-extraction.json` plus URL patterns plus captured photos298— the 2026-04-30 lovesac shortcut — is the failure mode this299guard exists to prevent. When the agent (or a delegated sub-300agent) cannot satisfy the contract for a page, treat the page301as a Phase 2 failure: record under `_crawl-log.json#crawl.failures[]`302with `errorClass: "ProvenanceMissing"` and continue.303304Mark the page `extracted` in `state.json` immediately after each305successful page write. If a page fails, record the error in306`_crawl-log.json` and continue — extraction is best-effort per page.307308### Phase 2.5 — Vision verification309310Before anything downstream is authored, **look** at each captured311page's screenshot (`assets/screenshots/<slug>.png`) — the multimodal312model reads the image — and verify it against the extracted record:313314- Does the recorded hero (headline + asset) match what the pixels show?315- Is the extracted palette plausible against the pixels?316- Does a `cssBackgrounds: []` record look believable, or is imagery317 visibly present — a silent capture failure?318- Is the logo captured?319- Is the page actually rendered — not a consent wall, bot-block320 page, or blank SPA shell?321322On mismatch, re-run that page's capture with the escalation ladder323before proceeding: bump the wait mode one step324(`reference/playwright-recipe.md` § Wait modes), then headed Chrome325(§ Bot-management fallback), then a fresh browser context. Record326the outcome per page in `_crawl-log.json#visionCheck[]`:327328```json329{ "slug": "pricing", "verdict": "recaptured", "notes": "record said zero CSS backgrounds; screenshot shows a full-bleed photo hero" }330```331332`verdict` is `"ok" | "recaptured" | "suspect"` — `suspect` means the333mismatch survived the ladder; downstream phases treat that record as334unreliable. Vision is the **authoritative** capture check; the335heuristic defenses (low-media flag, `spaShellSuspect`, duplicate336hash) remain as cheap early signals but no longer gate alone.337338### Phase 3 — Brand-surface extraction339340Run after the capture phases (2–2.5). Aggregation **may proceed341incrementally** as concurrent page captures complete (§ Concurrency),342but the written file must reflect every extracted page — including343brand-source pages per § Cross-site brand sources.344Produces `stardust/current/_brand-extraction.json`345per `reference/brand-surface.md`. Some fields are home-only (logo,346voice samples, register heuristic); the visual tokens that drive347DESIGN.md (palette, radius, shadow, type) are aggregated across **all348extracted pages** to avoid the home-page bias documented in349`brand-surface.md` § Aggregation scope. Captures:350351- **Logo** by the v1 priority chain: inline SVG → `<img>` with352 logo-ish class/id → `apple-touch-icon` → `og:image` → favicon →353 synthesized placeholder. Save to `stardust/current/assets/logo.<ext>`.354- **Favicon** — ALWAYS captured as its own asset (independent of the355 logo chain) to `stardust/current/assets/favicon.<ext>`, per356 `reference/playwright-recipe.md` § Favicon capture. Downstream,357 `prototype` embeds it in the proposed page head and `deploy` ships358 it to the Edge Delivery site.359- **Palette** — aggregate computed colors across **all extracted360 pages** (background, text, accents, borders, hovers). Frequency-sort,361 cluster near-duplicates, emit a role-named list (background, surface,362 text, primary, secondary, accent).363- **Type** — font families in use with their weights, sizes, and364 computed line-heights. Identify the heading family vs body family.365 Run the modular-scale audit (`brand-surface.md` § Modular-scale366 audit) and emit `scaleAudit.kind = "modular" | "ad-hoc"`.367- **Motifs** — signature border-radius (cross-page mode of non-zero368 values, weighted by element count), shadow stack (top 3 distinct,369 cross-page), gradient inventory, common patterns (chip, badge,370 card, hero-with-image). When the home-only mode disagrees with the371 cross-page mode, surface the divergence in `_provenance.notes`.372- **Voice samples** — first paragraph of body copy, the hero headline,373 3 representative CTA labels, a representative link list. Used by374 `direct` later but extracted now so the network round-trip is over.375- **Hero image** — elevate the home page's primary visual376 asset to `voice.heroImage` (per `reference/brand-surface.md`377 § heroImage resolution). Without this elevation, downstream378 prototype reasons over a 16-image list and frequently picks379 the `og:image` instead of the live hero.380- **Hero medium (signature)** — when the hero/first viewport carries a381 *moving* asset (background `<video>` / HLS / canvas / WebGL /382 Lottie / animated SVG / scroll-driven motion), elevate it to383 `voice.heroMedium` (per `reference/brand-surface.md` § heroMedium384 resolution). This is the page's **signature**; without elevation it385 is lost in the raw media list and downstream prototype flattens it386 to a static hero. A non-null `heroMedium` triggers signature387 preservation (`skills/stardust/reference/intent-dimensions.md`388 § 8b) at prototype time.389- **Icon font** — when detected per `reference/playwright-recipe.md`390 § Capture list 17, populate `_brand-extraction.json#iconFont`391 with family, file path, and the `iconClass → codepoint`392 table so prototypes can render the brand's actual icons.393- **System components** — cross-page repeated DOM blocks (site394 header, site footer, cross-promo strips, persistent CTAs,395 breadcrumbs). Detected by heading-sequence + CTA-label fingerprint396 per `reference/brand-surface.md` § System components. Required —397 these are usually the most load-bearing surfaces and must not398 silently disappear from the redesign target.399- **Origins** — one entry per contributing origin in400 `_brand-extraction.json#origins[]` per `reference/brand-surface.md`401 § Origins. Single-origin runs emit a one-entry array; brand-source402 runs attribute widened evidence per origin.403404Do not invent values. Every captured value cites a source selector or405URL in `_brand-extraction.json` for traceability.406407### Phase 4 — Seed `stardust/current/PRODUCT.md` and `DESIGN.md`408409The current-state PRODUCT.md and DESIGN.md are **descriptive, not410authored** — there is no interview to run because the user is not411defining intent here, the agent is describing the existing site. Write412them directly using impeccable's format specs:413414- For PRODUCT.md, follow the section structure in impeccable's415 `reference/teach.md`. Populate `Register` from the brand surface416 (sites that read as marketing/landing → `brand`; tools/dashboards →417 `product`; ambiguous → `brand` with a note). Populate `Users`,418 `Product Purpose`, `Brand Personality`, `Anti-references`, and419 `Design Principles` from the captured copy and the brand surface.420 Where the agent must infer, mark the section with `_provenance:421 inferred` and a one-line basis sentence.422- For DESIGN.md and DESIGN.json, follow the format spec in423 impeccable's `reference/document.md`. Populate frontmatter424 (`colors`, `typography`, `rounded`, `spacing`, `components`) from425 the captured tokens. The `extensions` block of DESIGN.json carries426 v1's `componentStyle`, `motifs`, and `voice` arrays so nothing is427 lost.428429Stardust does **not** invoke `$impeccable teach` or `$impeccable430document` for the current-state files: those commands write to project431root (the *target*) and run an interview. Stardust authors the432descriptive snapshot directly. The format spec from impeccable is the433contract; the runtime command is not.434435The target-state PRODUCT.md and DESIGN.md at the project root are436written by `$stardust direct` in Phase 2 of the pipeline, not here.437438### Phase 5 — Render `stardust/current/brand-review.html`439440After Phase 4 writes the descriptive PRODUCT.md and DESIGN.md, emit441the current-state brand review per442`reference/brand-review-template.md`.443444The brand-review HTML is the **first surface a human can eyeball** to445verify the extraction before committing to a redesign direction.446Misreads in the JSON (a wrong dominant radius, a missing system447component, a single-page palette bias) are obvious to the eye in five448seconds and invisible in JSON until someone notices. Putting the449review at the end of `extract` catches misreads while they are still450cheap to fix — re-extract is fast; re-direct + re-prototype is not.451452The template is mandatory. In particular:4534541. Run the **Tensions detectors** listed in455 `reference/brand-review-template.md` § Detectors. Each rule is456 mechanical; emit a tension card whenever the trigger condition457 matches. The review may ship with zero tensions if the data is458 too thin to evaluate, but the detectors must always be run.4592. Render in the brand's **own captured colors and fonts**, not a460 stardust shell.4613. Embed all CSS; do not load external JavaScript or fonts unless462 the live site already does.4634. Cite the source artifact for every section (e.g.464 `_brand-extraction.json § type` under Typography).465466If the data for a section is missing, **omit the section** — do not467fabricate placeholders. The coverage callout at the top reflects what468is missing.469470### Phase 6 — Update state and report471472After all Phase 2-5 writes succeed:4734741. Update `stardust/state.json` (schema in475 `skills/stardust/reference/state-machine.md`):476 - `site.originUrl`, `site.extractedAt`, `site.pageCap`,477 `site.totalDiscovered`, `site.crawled`478 - `pages[]` — one entry per crawled page with `status: "extracted"`,479 filled `currentStatePath`, empty `prototypePath` and `migratedPath`480 - `designSource` — only when `--design-source` was used:481 `{ url, capturedAt, path }` per § Cross-site brand sources4822. Print a one-screen summary:483 ```484 Extracted https://example.com (5/38 pages, sitemap.xml)485486 stardust/current/487 PRODUCT.md (register: brand, inferred from landing)488 DESIGN.md (5 colors, 2 type families, 3 motifs)489 brand-review.html (4 tensions surfaced)490 pages/ (5 files)491 assets/logo.svg (extracted from inline SVG)492 _brand-extraction.json493 _crawl-log.json494495 Per-page evidence:496 slug live waitMode waitMs status media(img/bg)497 / yes medium 2380 200 38/6498 /about yes medium 2110 200 12/2499 /pricing yes medium 1940 200 9/0 ⚠ low-media500 /products yes medium 2640 200 21/4501 /contact yes domcontentloaded(fb) 8000 200 3/0502503 Wait summary: 4 resolved at medium (avg 2.4s), 1 fallback (timed out at 8s)504 → /contact may be under-captured; consider --refresh505 Media summary: 1 page flagged low-media (/pricing) — see media-coverage check506 Vision check: 4 ok, 1 recaptured (/pricing) — _crawl-log.json#visionCheck507508 Open stardust/current/brand-review.html to verify the extraction509 before running $stardust direct.510511 Coverage note: extracted 5 of 38 discovered pages. The brand512 surface and brand-review use cross-page aggregation, so 5 pages513 covering distinct templates is usually sufficient. To extract514 more, re-run with --cap <N> (e.g. --cap 25) or list specific515 slugs with --pages.516517 Next: $stardust direct (resolve a redesign direction)518 ```519520 The **per-page evidence table** is mandatory. The `live` column521 is `yes` when `_provenance.renderedBy === "playwright"` AND522 `waitMs > 0`, else `no`. A `no` row means the page record was523 not produced by a live Playwright render — this should never524 happen given the write-time guard, but the visible column is525 the defense-in-depth signal that catches the failure mode526 when it does (the 2026-04-30 lovesac synthesis bug went four527 phases deep before being caught because no report column528 surfaced the missing provenance). A maintainer scanning the529 summary should see `yes` on every row.530531 Compute the wait summary by grouping each page's `_provenance.waitMode`532 and averaging `waitMs`. List slugs whose `waitMode` ends in533 `(fallback)` (rendered as `(fb)` in the table for width) as534 candidates for `--refresh`.535536 The **`media(img/bg)` column** is the analogous defense-in-depth537 signal for imagery. It prints `<count of media.imgs> / <count of538 media.cssBackgrounds>`. Flag a row `⚠ low-media` when the page539 reads as brand/marketing (register `brand`, or a landing/solution/540 product template) yet has `cssBackgrounds: []` **and** few large541 rasters (no `media.imgs` entry with intrinsic width ≥ 600). That542 combination is the signature of a silently-failed background /543 lazy-media walk — `getComputedStyle(el).backgroundImage` read544 before the element was styled, a `::before`/`::after` host missed,545 or product imagery gated behind interaction the reveal pass did not546 trigger. The recipe already specs the full background walk547 (`playwright-recipe.md` § Capture list 11, hardened after the548 2026-05-04 ups.com dropped-hero failure), but a thorough spec that549 silently produces nothing still ships an image-less capture: the550 2026-06-26 knack.com run returned `cssBackgrounds: []` on every551 page and lost all product screenshots, hero art, and customer552 logos, and nothing surfaced it because no column reported media553 coverage. A flagged row is the cue to re-run that page with554 `--refresh` (and, if it persists, to fall back to headed Chrome per555 § Bot-management fallback). A maintainer scanning the summary should556 treat a `brand`-register site with all-zero `bg` counts as suspect,557 not as "this site uses no background images."558559## Cross-site brand sources560561Two flags widen extraction beyond the primary origin. Both are562opt-in; without them this section is inert.563564### `--brand-source <url>` (repeatable) — sibling enrichment565566An additional **same-brand** origin whose brand surface enriches the567primary extraction. Per source: shallow capture only — home page plus568up to 2 nav-linked pages, full recipe per page (Phase 2 rules apply,569provenance contract included). Captured records land under570`stardust/current/brand-sources/<host>/` (own `pages/` +571`assets/screenshots/`, same page-JSON shape); they are **evidence,572not inventory** — they never enter `state.json.pages[]`.573574Their palette / type / motif / voice / photography evidence575**aggregates** into `_brand-extraction.json` with per-origin576provenance (`origins[]` per `reference/brand-surface.md` § Origins).577Two rules govern the merge:578579- **Conflicts resolve toward the primary.** Where primary and580 brand-source evidence disagree for the same slot (a palette role,581 the heading family, the signature radius), the primary origin's582 value wins; the losing value is noted in `_provenance.notes`.583- **Brand-source evidence widens the surface.** A motif or584 photography treatment the primary site underuses enters as an585 *additional* entry, attributed in `origins[].contributedSignals[]`586 — so downstream `direct` / `uplift` can amplify a trait captured587 on a sibling property as **captured** evidence with an origin588 citation, never as invention.589590Brand-source pages join palette/type/motif/voice aggregation but are591**excluded** from § System components, `voiceTable`, and cross-promo592detection — those describe the primary site's IA.593594### `--design-source <url>` — design donor595596Formalizes the proven canon.com pattern: a golden design source is597extracted separately and its design system becomes the fixed598**target**, while the primary origin supplies content.599600- Capture the donor to `stardust/canon-source/` — same page-JSON and601 brand-extraction shapes as `stardust/current/`, rooted there (own602 `pages/`, `assets/`, `_brand-extraction.json`, `_crawl-log.json`).603 The default cap (5) applies unless the user widens it.604- Derive `stardust/canon-source/DESIGN.md` + `DESIGN.json` from the605 donor's brand surface — **descriptive**, same authoring rules as606 Phase 4.607- Stamp `state.json.designSource = { "url", "capturedAt", "path":608 "stardust/canon-source/" }`.609610`stardust:direct` reads this stamp and pins the donor system as the611target: Mode A's brand-faithful pins transfer to the **donor**612surface while content stays with the primary origin — see613`skills/direct/SKILL.md` § Mode A. The donor records614`role: "design-source"` in its own615`canon-source/_brand-extraction.json#origins[]`; donor evidence never616aggregates into the primary `_brand-extraction.json`.617618## Sibling-site discovery619620After the primary crawl (Phases 2–2.5), harvest candidate same-brand621origins from evidence **already captured** — no extra navigation:622623- footer / nav links out to other properties624- "our brands" / "our companies" pages625- `hreflang` alternates on other domains626- subdomain families (`shop.`, `careers.`, country subdomains)627- `og:site_name` matches across captured pages628629List candidates with confidence + the evidence line in the crawl630report and in `_crawl-log.json#siblingCandidates[]`:631632```json633{ "origin": "https://example.co.uk", "confidence": "high", "evidence": "hreflang alternate on 4/5 pages", "decision": "included" }634```635636- **Interactive:** propose — *"found 3 candidate sibling properties —637 include as `--brand-source`?"* — and proceed on the answer.638- **Hands-off** (`state.json.handsOff` is true): auto-include up to639 **2 high-confidence** candidates as brand-sources; record the640 decision in `siblingCandidates[].decision`.641642Discovery is capped and cheap: harvesting reads captured evidence643only, and each included sibling gets the shallow brand-source644capture (≤ 3 pages). It must never balloon the crawl.645646## Outputs647648| Path | Purpose |649|---------------------------------------------|-----------------------------------------------------|650| `stardust/current/PRODUCT.md` | Descriptive strategy of the existing site (impeccable format) |651| `stardust/current/DESIGN.md` | Descriptive visual system (Stitch format) |652| `stardust/current/DESIGN.json` | Sidecar with extensions for motifs, voice, components |653| `stardust/current/brand-review.html` | Self-contained visual review of the extraction (first eyeball-able artifact) |654| `stardust/current/pages/<slug>.json` | Per-page parsed structure + content |655| `stardust/current/assets/logo.<ext>` | Extracted logo |656| `stardust/current/assets/favicon.<ext>` | Site favicon (first-class asset; prototype head + deploy consume it) |657| `stardust/current/assets/media/` | Extracted media referenced by pages |658| `stardust/current/assets/screenshots/` | Per-page full-page screenshots, script-captured by `crawl.mjs` (Phase 2.5 vision gate + brand-review) |659| `stardust/current/_brand-extraction.json` | Consolidated brand surface (palette, type, motifs, voice, system components) |660| `stardust/current/_crawl-log.json` | Discovery + crawl audit trail (incl. `visionCheck[]`, `siblingCandidates[]`) |661| `stardust/current/brand-sources/<host>/` | Shallow same-brand captures (only with `--brand-source`) |662| `stardust/canon-source/` | Design-donor capture + descriptive DESIGN.md/json (only with `--design-source`) |663| `stardust/state.json` | Updated with site + per-page status (+ `designSource` stamp) |664665## Concurrency666667Page captures run **concurrently**: the Phase 2 queue is drained by6684–8 parallel browser contexts (`--concurrency`, default 4). Each669worker owns its `BrowserContext`; consent state is re-established per670context (Setup step 3). Media `resolves` / HEAD checks are batched671with `Promise.all`. Brand-surface aggregation (Phase 3) may proceed672incrementally as pages complete, so long as the written673`_brand-extraction.json` reflects every extracted page. The bundled674crawler implements the pool (`crawl.mjs --concurrency <n>`).675676Across processes, per `state-machine.md`: stardust does not lock. Two677concurrent extracts on the same project are last-write-wins. Document678this in the user report; do not engineer around it.679680## Failure modes681682- **Network failure mid-crawl.** Continue, record in `_crawl-log.json`,683 end with a partial state. State.json reflects only successfully684 extracted pages. User can re-run; already-extracted pages are685 skipped unless `--refresh <slug>`.686- **HTTP 4xx/5xx, non-HTML content, soft-404s.** Validated explicitly687 per `reference/playwright-recipe.md` § Response validation. Each688 produces a distinct error class (`HTTPError`, `ContentTypeError`,689 `EmptyPageError`) recorded in `_crawl-log.json#crawl.failures[]`.690 Failed pages do **not** appear in `state.json` as `extracted` —691 they appear only in the failure log. Without this validation a 5xx692 page silently lands as an empty success and propagates wrong data693 to `direct` and `prototype`.694- **Login wall.** Do not attempt to authenticate. If the home page695 redirects to a login screen, capture that one page, mark the rest as696 unreachable, and ask the user how to proceed (provide cookies via697 Playwright config, change the entry URL, or scope to public pages).698- **Bot-management block (Akamai / Cloudflare / F5 / Imperva).**699 When the first navigation returns `ERR_HTTP2_PROTOCOL_ERROR`,700 `ERR_QUIC_PROTOCOL_ERROR`, or hangs through the hard-cap on a701 TLS/H2 fingerprint check, the issue is JA3/H2 fingerprinting on702 bundled-chromium-default headless mode — not auth, not network.703 Switch to `headless: false, channel: 'chrome'` per704 `reference/playwright-recipe.md` § Bot-management fallback. Do705 **not** retry headless: it will fail identically. The headed706 fallback works against most enterprise / commerce origins;707 `playwright-extra` + stealth plugin is a non-standard escape708 hatch for the residual cases. The headed window pops visibly,709 which is acceptable for interactive runs and unacceptable for710 unattended pipelines — surface this to the user when first711 triggered.712- **JavaScript-only content.** Playwright already handles this. If713 the configured wait condition never fires within the mode's hard714 cap (`reference/playwright-recipe.md` § Wait modes), fall back to715 `domcontentloaded` and capture what is rendered. Record the716 fallback in the per-page `_provenance.waitMode` and surface in the717 wait-summary line of the final report.718- **Synthesis attempt (forbidden).** When the agent (or a delegated719 sub-agent) cannot run a real Playwright render for a page —720 whether due to time pressure, token budget, or a tool/network721 failure — the only correct outcome is to record the page as a722 Phase 2 failure (`errorClass: "ProvenanceMissing"` in723 `_crawl-log.json#crawl.failures[]`) and continue. **Synthesizing724 a page record from `_brand-extraction.json` plus URL patterns725 plus captured photos at "semantically matching" template726 positions is forbidden.** This was the 2026-04-30 lovesac.com727 failure — 20 of 25 pages synthesized this way and the cascade728 ran four phases on the synthesized data before the gap was729 caught by a meta-question. The synthesis shortcut produces730 output indistinguishable from a successful run and propagates731 fabricated content through every downstream phase.732733## Prep mode (--prep)734735When invoked with `--prep`, extract runs an extended pass that736prepares the inventory for migration. Discovery-mode runs (without737`--prep`) are unchanged: small cap, no typing, no module detection,738presales-friendly. `--prep` is the gesture that says "the user is739committing to migrate; build the data structure migrate consumes."740741`--prep` adds five things on top of the standard procedure:742743### 1. Lift the cap744745`--prep` implies `--all`. Migration coverage requires the full746inventory — the small discovery cap (5 pages) is insufficient. The747cap-respecting selection logic from `reference/ia-extraction.md`748§ Page selection still applies for ordering and junk-filtering;749it just doesn't truncate.750751#### Sub-agent prompt requirements (when delegating)752753When `--prep` is heavy enough that the agent delegates extraction754to a sub-agent (a presales-shaped pattern when the inventory is755large), the sub-agent prompt **must**:7567571. **Forbid synthesis by name.** The literal sentence758 *"do not synthesize a page record from `_brand-extraction.json`759 + URL patterns + captured photos; every page must be a live760 Playwright render"* must appear in the prompt. The earlier761 wording *"must actually invoke Playwright per page"* was762 satisfiable in spirit by synthesis-with-photo-reuse and763 produced the lovesac failure. Naming the shortcut explicitly764 closes that loophole.7652. **Require a per-page evidence table in the return.** Columns:766 `slug | waitMode | waitMs | fetchedAt | httpStatus`. The767 parent agent reads this table on completion and aborts if768 any row is missing or shows `waitMs: 0`.7693. **Require the wait-summary line in the return**, formatted770 identically to Phase 6's wait summary, so the parent can771 surface it in the user-facing report without reformatting.772773These three are mandatory; missing any of them in the sub-agent774prompt is itself a recipe violation. The cascade-level guard in775`prepare-migration` validates the resulting per-page JSONs via776`validateProvenance()` regardless — but a well-formed sub-agent777return makes the failure cheaper to diagnose.778779### 2. Page typing780781For each extracted page, infer the `type` field from URL pattern782and content shape (LLM judgment). Catalog from783`skills/stardust/reference/state-machine.md` § Page types:784`landing | article | listing | program | form | static | unique`.785786Write the inferred type to `state.json.pages[].type`. The user787confirms or refines during `direct --prep`. Discovery-mode runs788leave `type` as `null`.789790### 3. Module candidate detection791792After Phase 3 (brand-surface extraction), scan extracted pages for793**recurring structural patterns**. A pattern that appears in N+794pages with similar shape (same sequence of elements, same795`data-section` / `data-purpose`, similar text shape) is surfaced796as a module candidate.797798#### Signal-source priority799800Detection consumes per-page captured fields in this priority801order. Each higher signal is **weighted more heavily** in the802match-score; lower signals are tie-breakers and corroboration,803not primary evidence. The priority exists because higher-up804fields are explicitly extracted and structured (no parsing805ambiguity), while the bottom of the list (`landmarks[].innerText`806substring search) is fragile against capture variations and was807the source of the 2026-04-29 sliccy.com under-detection (0808hits for `pre-footer-shell`, 1 of 2 hits for `install-tile` —809both modules genuinely present on every page, both invisible810because the substrings being searched lived past the truncation811boundary that has since been removed).8128131. **`pages/<slug>.json#headings[]`** — cross-page repeats of814 the same heading text in the same level. Highest signal:815 structured, explicit, captured in full regardless of body816 length.8172. **`pages/<slug>.json#ctas[]` labels** — cross-page repeats818 of the same CTA label appearing on similar surfaces.8193. **`pages/<slug>.json#media.cssBackgrounds[]` URLs** — same820 asset URL on multiple pages is a strong system-component821 signal (already specced as a system-component candidate in822 `reference/brand-surface.md` § Cross-page CSS-background823 reuse; module detection consumes the same signal at finer824 granularity).8254. **`pages/<slug>.json#forms[]` actions** — cross-page repeats826 of the same form `action` URL. Newsletter / contact / search827 forms are the typical hits.8285. **`pages/<slug>.json#components.componentsByLandmark`** when829 present (per future `current-state-schema.md` extension):830 per-landmark counts of cards / grids / etc.8316. **Substring search in `landmarks[].innerText`** — lowest832 signal. Use only as corroboration once a candidate has833 already passed the higher-signal checks; never as the834 primary detector.835836A candidate that fires on signals 1 + 2 above the threshold is837high-confidence; a candidate that fires only on 6 should be838treated as speculative and surfaced as such for the user to839confirm in `direct --prep`.840841Candidate output is a draft entry under842`DESIGN.json.extensions.modules[]`:843844```json845{846 "id": "candidate-<short-hash>",847 "slots": [848 { "name": "<inferred>", "type": "text|link|image|...", "required": false }849 ],850 "instances": [851 { "slug": "home", "selector": "..." },852 { "slug": "donate", "selector": "..." }853 ],854 "status": "candidate"855}856```857858The `status: "candidate"` flag distinguishes draft entries from859confirmed modules. `direct --prep` is where the user names them860and promotes (or prunes).861862### 4. Typed content slots863864Per-page JSON (`current/pages/<slug>.json`) gains a `slots`865section that identifies content slots per page-type:866867- `article` pages: `headline`, `deck`, `byline`, `meta`,868 `lead-image`, `body`, `pullquotes[]`, `related[]`869- `listing` pages: `index-headline`, `filter-controls`,870 `card-grid` with typed sub-slots per card871- `program` pages: `program-headline`, `summary`,872 `feature-grid`, `cta-band`873- `landing`, `form`, `static` — typed slots inferred per874 content shape875876Schema additions live in `reference/current-state-schema.md`877§ Typed slots (extend that doc separately).878879### 5. Prep summary880881Replace Phase 6's standard report with the prep summary format:882883```884extract --prep complete885=======================886887Inventory: 127 pages crawled (5 prior, 122 new)888Provenance: 127/127 live (every page has Playwright evidence)889Page types: landing 1 · article 84 · listing 6 · program 12 · form 3 · static 18 · unique 3890 (LLM-inferred; refine in direct --prep)891892Module candidates: 8893 hotline-211 5 instances (home, get-help, donate, news, programs)894 donate-band 12 instances (home, donate, news, all article footers)895 story-card 7 instances (home, news, programs)896 ...897898Typed slots: filled per page-type (see current/pages/<slug>.json § slots)899900Next: $stardust direct --prep (confirm types, name modules)901```902903The `Provenance: <live>/<total> live` line is mandatory in904prep-mode output. When the ratio is anything other than905`<total>/<total>` the prep run has failed the synthesis guard;906list the affected slugs as a sub-bullet and treat the prep run907as incomplete (the cascade-level guard in908`prepare-migration` SKILL.md surfaces the same check between909phases).910911Default mode (no `--prep`) is unchanged. The flag is intended for912the `prepare-migration` orchestrator, though direct invocation is913supported.914915## References916917- `reference/playwright-recipe.md` — viewport, capture list, logo locator chain.918- `reference/ia-extraction.md` — sitemap + BFS crawl + cap procedure.919- `reference/current-state-schema.md` — per-page JSON schema.920- `reference/brand-surface.md` — consolidated brand-surface schema.921- `reference/brand-review-template.md` — current-state brand-review HTML contract + Tensions detectors.922- `skills/stardust/reference/state-machine.md` — state.json contract.923- `skills/stardust/reference/artifact-map.md` — provenance shape.