stardust:audit
One URL in. One scored, evidence-bound audit out.
audit looks at an existing website from three perspectives — design
(brand tensions + concrete improvement opportunities), SEO/technical,
and LLM/AI-search visibility — measures Core Web Vitals, and
synthesizes everything into a seven-dimension scorecard plus a
prioritized findings ledger that tells the owner what to improve to
generate a better business outcome. The report is also the natural
seed for a redesign: its findings feed stardust:uplift's
improvements list and stardust:direct's Phase 2.5, and it closes
with uplift-shaped redesign directions so "run stardust:uplift" is
the obvious next step.
Opinionated defaults
- Multi-page by default —
stardust:extract <url> --cap 8
(home + seven IA pillars) unless --single or --pages overrides.
- Non-interactive — the audit never asks questions. Every
assumption it makes instead is recorded in
audit.json#assumptions and stated in the report's executive
summary.
- Evidence-bound — every claim cites a measurement, a
T-*
tension id, a check result, or a screenshot observation. A claim
with no citation does not ship.
- No fabricated data — a measurement that could not be taken is
reported as
not measured (<reason>), never estimated silently.
An estimate, where reasoned, is labeled as one with its basis.
- Graceful degradation, not failure — optional capabilities
(refero, marketing-skills, modern-web-guidance, PageSpeed
Insights) are probed once and their absence is recorded, never
fatal. See § Degradation ladder.
Inputs
<url> — required. The site to audit. A path narrows the crawl to
that subtree (extract's semantics).
--pages <n> — optional. Override the default 8-page extraction
cap (passed through as --cap <n>).
--single — optional. One-page audit of the given URL only. The
cross-page checks (duplicate titles, sitemap coverage, CTA
fragmentation across pages) then run on a single page and say so.
--deploy — optional. After the report renders, publish
report.html as a single self-contained page via the DA transport
(../deploy/da-deploy-protocol.md: source PUT → preview → live)
and print the delivered URL. Transport only — the report never
goes through deploy's section→block conversion, which would
decompose the self-contained file.
--benchmark — optional. Force Phase 5 reference benchmarking:
probe the refero MCP even when the earlier capability probe was
slow or ambiguous. Without this flag Phase 5 fires only when the
probe succeeds quickly.
There are no other flags. Everything else is derived from the
captured surface or governed by the underlying skills' contracts.
Phase 0 — Setup
- Run the master skill's setup (
../stardust/SKILL.md § Setup) —
with one audit-specific carve-out: impeccable absence is a
degradation here, not the master setup's hard stop. When the
dep check fails, record impeccable: unavailable in
audit.json#degradations and continue — Phase 2 runs without the
critique/audit arms (VISION pass + accessibility fold-in still
fire) and Phase 6 skips the report render; the run ends at stop
condition (b) after audit.json is written.
- Extraction freshness check. If
stardust/current/ holds an
extraction of the same origin less than 7 days old —
origin from stardust/state.json (the site record extract
stamped), recency from the newest
pages/<slug>.json#_provenance.fetchedAt — reuse it
and record site.extraction.reused: true. Otherwise invoke
stardust:extract <url> --cap 8 (or --single / --pages <n>
per the inputs). Extract owns the crawl, the screenshots,
_brand-extraction.json, pages/<slug>.json, PRODUCT.md /
DESIGN.md, and brand-review.html with its Tensions section.
- Probe optional capabilities once, recording each outcome in
the degradation record (
audit.json#degradations):
marketing-skills plugin (seo-audit, ai-seo skills present?)
modern-web-guidance (npx -y modern-web-guidance@latest search "<query>" responds?)
- refero MCP (attempt
mcp__refero__refero_search_styles; treat a
tool-not-found or timeout as unavailable)
- PageSpeed Insights API (network-reachable without a key?)
- rollout project (
stardust/rollout/rollout.json present?)
If extract fails entirely (site unreachable, bot-management block
past the headed-Chrome fallback), stop and surface extract's error
verbatim — there is nothing to audit. This is the only hard stop
before synthesis; see § Stop conditions.
Procedure
Phase 1 — Brand surface & tension analysis
Read stardust/current/_brand-extraction.json and
stardust/current/brand-review.html § Tensions surfaced (rule
catalog in ../extract/reference/brand-review-template.md
§ Tensions). Every fired T-* tension is candidate evidence for a
finding — carry the ids forward, do not re-derive the detections.
Compute the four brand-expression measurements the report needs.
Each lands in audit.json#measurements with status + method per
reference/report-format.md:
brandColorShare — brand-color share of painted pixels on the
captured home screenshot. Preferred method: Playwright pixel
sampling (method: "pixel-sample") — load the screenshot, sample a
grid (e.g. every 8th pixel), classify each sample to the nearest
palette entry within a tolerance, and divide brand-hue samples by
painted (non-white/near-white) samples. When sampling is infeasible
in the session, a reasoned estimate from the captured surfaces is
allowed but must ship as method: "surface-estimate" with its
basis — never presented as measured.
ctaFragmentation — distinct CTA labels per equivalence bucket,
aggregated from pages/*.json#ctas[].label (the same buckets that
drive T-cta-vocab).
typeScale — distinct heading sizes and scale kind/ratio from
_brand-extraction.json#type.scaleAudit.
radiusSprawl — distinct border-radius values with occurrence
counts from _brand-extraction.json#motifs.borderRadius.
Phase 2 — Design & experience critique
Three passes over the captured home page (screenshot + live URL),
folded into one set of design findings:
- impeccable critique + audit. Invoke via the Skill tool using
the delegation mechanic in
../prototype/SKILL.md § Invoking
impeccable (Skill { skill: "impeccable:impeccable", args: "critique <target>" }, then "audit <target>" for the
accessibility / responsive / performance passes). Normalize its
findings into the audit's finding shape.
- VISION pass. Study the captured screenshots directly
(
stardust/current/assets/screenshots/<slug>.png) and name what a
design director would: dated patterns the field has moved past,
hierarchy failures, missed opportunities the captured surface
doesn't capitalize on. The claim discipline is absolute — every
observation cites a measurement, a tension id, or a screenshot
region ("home.png, hero: three equal-weight CTAs compete").
Adjectives without evidence do not become findings.
- Accessibility fold-in. Contrast computed (WCAG ratios for the
captured palette pairs in the roles they are actually used in),
alt coverage from
pages/*.json#media.images, landmark presence
and heading order from pages/*.json#landmarks, content-free link
labels (reuse T-link-content-free when fired).
Phase 3 — SEO & technical
When the marketing-skills plugin is installed, follow
marketing-skills:seo-audit's methodology and normalize its
issue/impact/evidence/fix items into findings. When absent, run the
checks directly — they are all curl/Playwright-derivable:
| area |
checks |
method |
| Crawlability |
robots.txt present and sane; sitemap declared and valid XML |
curl |
| Indexation |
canonical present and self-referential; meta robots not accidentally noindex; http→https single-hop redirect; redirect chains |
curl -I |
| Semantics |
main/nav/footer landmarks; single <h1>; heading hierarchy without skips |
pages/*.json + Playwright |
| Metadata |
title/description presence + quality per page; duplicates across pages; Open Graph completeness |
pages/*.json#metadata |
| Structured data |
JSON-LD presence, parse validity, entity types vs page type |
Playwright / curl |
Where a failure matches a rollout:baseline check id
(../rollout/reference/checks.md: single-h1, title-missing,
meta-description, canonical, sitemap, jsonld, img-alt,
landmark-main, duplicate-title), reuse that id as the
finding's evidence.ref (check:<id>) — findings recorded into a
rollout ledger under a known id get picked up by the AEM autofix
registry automatically.
Core Web Vitals. Measure LCP / CLS / TBT via Playwright
performance APIs (PerformanceObserver for
largest-contentful-paint and layout-shift, longtask entries for
TBT) on two viewports: mobile (375×667, CPU throttled where the
session supports it) and desktop (1440×900). When the PageSpeed
Insights API is network-reachable without a key, prefer it and record
method: "psi-api" (it adds field INP); otherwise record
method: "playwright-lab" and say in the measurement note that lab
TBT is a proxy for INP. Classify every metric against the Google
thresholds tabled in reference/scoring.md § performance.
Remediation guidance. When modern-web-guidance is installed,
run npx -y modern-web-guidance@latest search "<specific failure>"
for each distinct failure class and cite the returned guide ids in
the finding's guides[]. When absent, write the generic remediation
and leave guides: [].
Phase 4 — LLM visibility
When marketing-skills:ai-seo is installed, follow its methodology.
When absent, assess directly:
llms.txt — present at the origin root?
- Answerability — does each audited page answer the question a
user would ask of it ("what does this cost", "what is this") in
extractable, well-structured prose — and how early on the page?
- schema.org coverage — do the JSON-LD entities cover the
organization plus the page-type entities an answer engine needs
for entity understanding?
- Heading-as-question coverage — what share of
h2/h3 map to
askable questions or scannable topics rather than slogans?
- Content depth — extractable prose word counts on key pages;
specific, citable claims vs thin marketing copy.
- Key facts in crawlable text — are pricing, what-it-is, and
who-it's-for stated in crawlable text, or locked in images and
JS-rendered widgets?
Every Phase 4 finding names the concrete fix ("state the three price
points in the pricing table as text; they currently render only
inside the plan-card images"), not a category ("improve content").
Phase 5 — Reference benchmarking (optional)
Fires when the refero MCP tools are reachable — the Phase 0 probe
attempted mcp__refero__refero_search_styles; --benchmark forces a
re-probe. Skip gracefully when unavailable
(benchmarks: { status: "skipped", reason: … }).
When available: retrieve 2–3 same-vertical reference styles, compare
the audited site's brand expression (Phase 1 measurements) against
what best-in-class in the category does, and cite each reference —
title, URL, one line on what they do better — in the relevant design
findings and in audit.json#benchmarks.references.
Phase 6 — Synthesis & report
Scorecard. Score the seven dimensions per
reference/scoring.md — anchors first, evidence floor enforced,
not-measured dimensions nulled and renormalized. Compute the
weighted overall.
Findings. Consolidate Phases 1–5 into the prioritized ledger:
P1 (actively losing business or excluding users) / P2 (material
drag) / P3 (polish). Per finding: dimension, evidence
(measurement / tension / screenshot / check / benchmark citation),
businessImpact one-liner, concrete fix, guides[].
Uplift directions. Close with 2–3 redesign directions framed
exactly like uplift's variant role contract
(../uplift/SKILL.md § The three-variant role contract):
A faithful + fixes (names the findings it resolves), B one
captured-but-underused trait amplified, C cinematic (motion as
identity, register suggested per
../prototype/reference/motion-registers.md § Selection
heuristic). Drop B when the captured surface can't support a
differentiated middle — two strong directions beat three weak
ones.
Write stardust/audit/<domain-slug>/audit.json — schema,
slug convention, and measurement rules in
reference/report-format.md Part 1. Provenance _provenance
first key.
Render stardust/audit/<domain-slug>/report.html by
delegating to $impeccable craft with the brief in
reference/report-format.md Part 2 — the same Skill-tool
mechanic as prototype, and the same rule: never hand-template
the report. Run the post-render validation checklist; on
failure re-invoke craft with the specific violation. Open the
result with open stardust/audit/<domain-slug>/report.html.
Ledger recording (rollout projects only). When
stardust/rollout/rollout.json exists, record each finding into
the delivery ledger via
node skills/rollout/scripts/findings.mjs record with source
namespace audit: — --source audit:<dimension>, --layer from
the mapping below, severity carried through, --fixability
normalized per ../rollout/reference/audit-sources.md
§ Recording an external finding. Write each returned id into the
finding's ledgerId.
| audit dimension |
ledger layer |
brand-expression |
brand-tensions |
visual-hierarchy-craft |
design-ux |
conversion-focus |
content-conversion |
accessibility |
accessibility |
technical-seo |
seo (site-wide: cross-page) |
content-llm-visibility |
ai-search |
performance |
seo |
--deploy. When passed, publish report.html via the DA
transport per ../deploy/da-deploy-protocol.md — PUT the file as
a single source, POST preview, POST live, verify the delivered
URL returns 200 — and print the delivered URL. Transport only;
never run deploy's section→block conversion on the report.
Chat summary. Short — the work is on disk and openable:
audit complete — <url>
Site health: <overall>/100
<dimension>: <score> × 7 (not-measured dimensions listed with reasons)
Findings: <n> P1 · <n> P2 · <n> P3
Top lever: <the single highest-impact P1, one line>
Report: stardust/audit/<domain-slug>/report.html
Data: stardust/audit/<domain-slug>/audit.json
Next: run stardust:uplift <url> — the report's closing directions
are its variant briefs.
Degradation ladder
Probed once in Phase 0; every degradation is recorded in
audit.json#degradations and rendered in the report's methodology
appendix. None of these stops the audit.
| capability absent |
behavior |
| refero MCP |
skip Phase 5; benchmarks.status: "skipped" with reason |
| marketing-skills |
run the Phase 3 / Phase 4 checks directly (tabled above) |
| modern-web-guidance |
generic remediation text; guides: [] |
| PageSpeed Insights |
Playwright-only lab metrics; measurement note says lab TBT proxies INP |
| Playwright pixel sampling infeasible |
brandColorShare ships as method: "surface-estimate" with basis |
| rollout project |
no ledger recording; ledgerId: null on every finding |
Hard constraints
- No fabricated data. A measurement that could not be taken is
not measured (<reason>) in both artifacts. Estimates are labeled
with method + basis. This is the same discipline extract enforces
against synthesis (../extract/SKILL.md § Failure modes) —
fabricated audit numbers are worse than missing ones because they
are actionable-looking and wrong.
- Evidence discipline. Every finding cites observable evidence:
a measurement key, a
T-* tension id, a screenshot region, a
check id, or a benchmark URL. Uncited claims are cut in synthesis.
- Report is craft-rendered.
report.html is authored by
$impeccable craft against the brief in
reference/report-format.md, validated afterward — never
hand-templated, never hand-patched.
- Provenance is mandatory on both artifacts, per
../stardust/reference/artifact-map.md § Provenance shapes.
- Non-interactive. No questions in normal flow; assumptions are
stated in the report. The only stops are the two below.
- Audit does not fix. Fixes belong to
uplift (page redesign),
direct Phase 2.5 (improvements list), and rollout's optimize
loop (platform autofix). Audit names the fix; it never edits the
site.
Stop conditions
Stop and surface only if:
(a) Extract fails entirely — site unreachable, structure
unparseable, bot-management block past the headed-Chrome
fallback. Surface extract's error verbatim; nothing to audit.
(b) impeccable unavailable — Phase 2's critique/audit arms and
Phase 6's report render require it. Per the Phase 0 carve-out,
the run continues in degraded mode (VISION pass, SEO/technical,
LLM visibility, benchmarks all still fire) and writes
audit.json; then stop and tell the user the designed report
needs the impeccable plugin — deliver the data, not a
hand-templated substitute.
Everything else degrades per the ladder; the audit never stops for
confirmation in normal flow.
Outputs
stardust/
├── current/ ← from extract (reused when <7 days old)
│ ├── _brand-extraction.json
│ ├── brand-review.html ← Tensions section = Phase 1 input
│ ├── pages/<slug>.json
│ └── assets/screenshots/<slug>.png ← VISION-pass + report evidence figures
└── audit/
└── <domain-slug>/ ← hostname, www-stripped, dots → dashes
├── audit.json ← scorecard, measurements, findings[], provenance
└── report.html ← craft-rendered, self-contained
stardust/rollout/optimize/findings.json ← appended via findings.mjs (rollout projects only)
Audit writes no state.json entries — extraction state belongs to
extract; audit's own artifacts are self-describing via provenance.
Re-running audit against a fresh extraction overwrites
stardust/audit/<domain-slug>/; ledger recordings dedupe by the
ledger's own id hash.
Scope
- Audits and prescribes; never modifies the site or its redesign
artifacts.
- One origin per run. Auditing a competitor set is N runs.
- The natural continuations:
stardust:uplift <url> (the closing
directions are its variant briefs), stardust:direct (findings
feed the Phase 2.5 improvements list), rollout's optimize loop
(ledger findings with known check ids autofix on AEM).
References
reference/scoring.md — the seven dimensions, weights, observable
anchors at 40/70/90, scoring procedure.
reference/report-format.md — audit.json schema (Part 1) and
the report.html craft brief + post-render validation (Part 2).
../extract/SKILL.md — crawl, capture, brand-surface extraction;
§ Failure modes for the anti-synthesis discipline.
../extract/reference/brand-review-template.md § Tensions — the
T-* detector catalog Phase 1 carries forward.
../prototype/SKILL.md § Invoking impeccable — the Skill-tool
delegation mechanic reused for critique (Phase 2) and the report
render (Phase 6).
../rollout/reference/audit-sources.md — the findings-ledger
normalization rules (severity, fixability) Phase 6 applies.
../rollout/reference/checks.md — baseline check ids to reuse so
AEM autofix picks the findings up.
../rollout/scripts/findings.mjs — the ledger writer (record).
../uplift/SKILL.md § The three-variant role contract — the frame
for the closing uplift directions.
../prototype/reference/motion-registers.md § Selection heuristic
— register suggestion for direction C.
../direct/SKILL.md § Phase 2.5 — the improvements list audit
findings feed on a subsequent redesign.
../deploy/da-deploy-protocol.md — the DA transport behind
--deploy (source PUT → preview → live; no block conversion).
../stardust/SKILL.md § Setup — master-skill setup run in Phase 0.
../stardust/reference/artifact-map.md — provenance shapes.
1---2name: audit3description: Full three-perspective audit of an existing website from one URL — design (tensions + concrete improvement opportunities), SEO/technical, and LLM/AI-search visibility — plus Core Web Vitals, synthesized into a scored, evidence-bound report. Use when the user asks to "audit this site", "site audit", "design audit", "SEO audit", "why is my site underperforming", "LLM visibility", "how does my site look to AI", or invokes /stardust:audit <url>.4license: Apache-2.05metadata:6 source: https://skillmd.com/skills/adobe/audit7---89# stardust:audit1011One URL in. One scored, evidence-bound audit out.1213`audit` looks at an existing website from three perspectives — design14(brand tensions + concrete improvement opportunities), SEO/technical,15and LLM/AI-search visibility — measures Core Web Vitals, and16synthesizes everything into a seven-dimension scorecard plus a17prioritized findings ledger that tells the owner what to improve to18generate a better business outcome. The report is also the natural19seed for a redesign: its findings feed `stardust:uplift`'s20improvements list and `stardust:direct`'s Phase 2.5, and it closes21with uplift-shaped redesign directions so "run `stardust:uplift`" is22the obvious next step.2324## Opinionated defaults2526- **Multi-page by default** — `stardust:extract <url> --cap 8`27 (home + seven IA pillars) unless `--single` or `--pages` overrides.28- **Non-interactive** — the audit never asks questions. Every29 assumption it makes instead is recorded in30 `audit.json#assumptions` and stated in the report's executive31 summary.32- **Evidence-bound** — every claim cites a measurement, a `T-*`33 tension id, a check result, or a screenshot observation. A claim34 with no citation does not ship.35- **No fabricated data** — a measurement that could not be taken is36 reported as `not measured (<reason>)`, never estimated silently.37 An estimate, where reasoned, is labeled as one with its basis.38- **Graceful degradation, not failure** — optional capabilities39 (refero, marketing-skills, modern-web-guidance, PageSpeed40 Insights) are probed once and their absence is recorded, never41 fatal. See § Degradation ladder.4243## Inputs4445- `<url>` — required. The site to audit. A path narrows the crawl to46 that subtree (extract's semantics).47- `--pages <n>` — optional. Override the default 8-page extraction48 cap (passed through as `--cap <n>`).49- `--single` — optional. One-page audit of the given URL only. The50 cross-page checks (duplicate titles, sitemap coverage, CTA51 fragmentation across pages) then run on a single page and say so.52- `--deploy` — optional. After the report renders, publish53 `report.html` as a single self-contained page via the DA transport54 (`../deploy/da-deploy-protocol.md`: source PUT → preview → live)55 and print the delivered URL. Transport only — the report never56 goes through deploy's section→block conversion, which would57 decompose the self-contained file.58- `--benchmark` — optional. Force Phase 5 reference benchmarking:59 probe the refero MCP even when the earlier capability probe was60 slow or ambiguous. Without this flag Phase 5 fires only when the61 probe succeeds quickly.6263There are no other flags. Everything else is derived from the64captured surface or governed by the underlying skills' contracts.6566## Phase 0 — Setup67681. Run the master skill's setup (`../stardust/SKILL.md` § Setup) —69 with one audit-specific carve-out: **impeccable absence is a70 degradation here, not the master setup's hard stop.** When the71 dep check fails, record `impeccable: unavailable` in72 `audit.json#degradations` and continue — Phase 2 runs without the73 critique/audit arms (VISION pass + accessibility fold-in still74 fire) and Phase 6 skips the report render; the run ends at stop75 condition (b) *after* `audit.json` is written.762. **Extraction freshness check.** If `stardust/current/` holds an77 extraction of the **same origin** less than **7 days** old —78 origin from `stardust/state.json` (the site record extract79 stamped), recency from the newest80 `pages/<slug>.json#_provenance.fetchedAt` — reuse it81 and record `site.extraction.reused: true`. Otherwise invoke82 `stardust:extract <url> --cap 8` (or `--single` / `--pages <n>`83 per the inputs). Extract owns the crawl, the screenshots,84 `_brand-extraction.json`, `pages/<slug>.json`, `PRODUCT.md` /85 `DESIGN.md`, and `brand-review.html` with its Tensions section.863. **Probe optional capabilities once**, recording each outcome in87 the degradation record (`audit.json#degradations`):88 - `marketing-skills` plugin (`seo-audit`, `ai-seo` skills present?)89 - `modern-web-guidance` (`npx -y modern-web-guidance@latest search90 "<query>"` responds?)91 - refero MCP (attempt `mcp__refero__refero_search_styles`; treat a92 tool-not-found or timeout as unavailable)93 - PageSpeed Insights API (network-reachable without a key?)94 - rollout project (`stardust/rollout/rollout.json` present?)9596If extract fails entirely (site unreachable, bot-management block97past the headed-Chrome fallback), stop and surface extract's error98verbatim — there is nothing to audit. This is the only hard stop99before synthesis; see § Stop conditions.100101## Procedure102103### Phase 1 — Brand surface & tension analysis104105Read `stardust/current/_brand-extraction.json` and106`stardust/current/brand-review.html` § Tensions surfaced (rule107catalog in `../extract/reference/brand-review-template.md`108§ Tensions). Every fired `T-*` tension is candidate evidence for a109finding — carry the ids forward, do not re-derive the detections.110111Compute the four brand-expression measurements the report needs.112Each lands in `audit.json#measurements` with `status` + `method` per113`reference/report-format.md`:114115- **`brandColorShare`** — brand-color share of painted pixels on the116 captured home screenshot. Preferred method: Playwright pixel117 sampling (`method: "pixel-sample"`) — load the screenshot, sample a118 grid (e.g. every 8th pixel), classify each sample to the nearest119 palette entry within a tolerance, and divide brand-hue samples by120 painted (non-white/near-white) samples. When sampling is infeasible121 in the session, a reasoned estimate from the captured surfaces is122 allowed but must ship as `method: "surface-estimate"` with its123 basis — never presented as measured.124- **`ctaFragmentation`** — distinct CTA labels per equivalence bucket,125 aggregated from `pages/*.json#ctas[].label` (the same buckets that126 drive `T-cta-vocab`).127- **`typeScale`** — distinct heading sizes and scale kind/ratio from128 `_brand-extraction.json#type.scaleAudit`.129- **`radiusSprawl`** — distinct border-radius values with occurrence130 counts from `_brand-extraction.json#motifs.borderRadius`.131132### Phase 2 — Design & experience critique133134Three passes over the captured home page (screenshot + live URL),135folded into one set of design findings:1361371. **impeccable critique + audit.** Invoke via the Skill tool using138 the delegation mechanic in `../prototype/SKILL.md` § Invoking139 impeccable (`Skill { skill: "impeccable:impeccable", args:140 "critique <target>" }`, then `"audit <target>"` for the141 accessibility / responsive / performance passes). Normalize its142 findings into the audit's finding shape.1432. **VISION pass.** Study the captured screenshots directly144 (`stardust/current/assets/screenshots/<slug>.png`) and name what a145 design director would: dated patterns the field has moved past,146 hierarchy failures, missed opportunities the captured surface147 doesn't capitalize on. The claim discipline is absolute — every148 observation cites a measurement, a tension id, or a screenshot149 region ("`home.png`, hero: three equal-weight CTAs compete").150 Adjectives without evidence do not become findings.1513. **Accessibility fold-in.** Contrast computed (WCAG ratios for the152 captured palette pairs in the roles they are actually used in),153 alt coverage from `pages/*.json#media.images`, landmark presence154 and heading order from `pages/*.json#landmarks`, content-free link155 labels (reuse `T-link-content-free` when fired).156157### Phase 3 — SEO & technical158159When the `marketing-skills` plugin is installed, follow160`marketing-skills:seo-audit`'s methodology and normalize its161issue/impact/evidence/fix items into findings. When absent, run the162checks directly — they are all curl/Playwright-derivable:163164| area | checks | method |165|---|---|---|166| Crawlability | `robots.txt` present and sane; sitemap declared and valid XML | curl |167| Indexation | canonical present and self-referential; `meta robots` not accidentally `noindex`; http→https single-hop redirect; redirect chains | curl -I |168| Semantics | `main`/`nav`/`footer` landmarks; single `<h1>`; heading hierarchy without skips | pages/*.json + Playwright |169| Metadata | title/description presence + quality per page; duplicates across pages; Open Graph completeness | pages/*.json#metadata |170| Structured data | JSON-LD presence, parse validity, entity types vs page type | Playwright / curl |171172Where a failure matches a `rollout:baseline` check id173(`../rollout/reference/checks.md`: `single-h1`, `title-missing`,174`meta-description`, `canonical`, `sitemap`, `jsonld`, `img-alt`,175`landmark-main`, `duplicate-title`), **reuse that id** as the176finding's `evidence.ref` (`check:<id>`) — findings recorded into a177rollout ledger under a known id get picked up by the AEM autofix178registry automatically.179180**Core Web Vitals.** Measure LCP / CLS / TBT via Playwright181performance APIs (`PerformanceObserver` for182`largest-contentful-paint` and `layout-shift`, `longtask` entries for183TBT) on two viewports: mobile (375×667, CPU throttled where the184session supports it) and desktop (1440×900). When the PageSpeed185Insights API is network-reachable without a key, prefer it and record186`method: "psi-api"` (it adds field INP); otherwise record187`method: "playwright-lab"` and say in the measurement note that lab188TBT is a proxy for INP. Classify every metric against the Google189thresholds tabled in `reference/scoring.md` § performance.190191**Remediation guidance.** When `modern-web-guidance` is installed,192run `npx -y modern-web-guidance@latest search "<specific failure>"`193for each distinct failure class and cite the returned guide ids in194the finding's `guides[]`. When absent, write the generic remediation195and leave `guides: []`.196197### Phase 4 — LLM visibility198199When `marketing-skills:ai-seo` is installed, follow its methodology.200When absent, assess directly:201202- **`llms.txt`** — present at the origin root?203- **Answerability** — does each audited page answer the question a204 user would ask of it ("what does this cost", "what is this") in205 extractable, well-structured prose — and how early on the page?206- **schema.org coverage** — do the JSON-LD entities cover the207 organization plus the page-type entities an answer engine needs208 for entity understanding?209- **Heading-as-question coverage** — what share of `h2`/`h3` map to210 askable questions or scannable topics rather than slogans?211- **Content depth** — extractable prose word counts on key pages;212 specific, citable claims vs thin marketing copy.213- **Key facts in crawlable text** — are pricing, what-it-is, and214 who-it's-for stated in crawlable text, or locked in images and215 JS-rendered widgets?216217Every Phase 4 finding names the concrete fix ("state the three price218points in the pricing table as text; they currently render only219inside the plan-card images"), not a category ("improve content").220221### Phase 5 — Reference benchmarking (optional)222223Fires when the refero MCP tools are reachable — the Phase 0 probe224attempted `mcp__refero__refero_search_styles`; `--benchmark` forces a225re-probe. Skip gracefully when unavailable226(`benchmarks: { status: "skipped", reason: … }`).227228When available: retrieve 2–3 same-vertical reference styles, compare229the audited site's brand expression (Phase 1 measurements) against230what best-in-class in the category does, and cite each reference —231title, URL, one line on what they do better — in the relevant design232findings and in `audit.json#benchmarks.references`.233234### Phase 6 — Synthesis & report2352361. **Scorecard.** Score the seven dimensions per237 `reference/scoring.md` — anchors first, evidence floor enforced,238 not-measured dimensions nulled and renormalized. Compute the239 weighted overall.2402. **Findings.** Consolidate Phases 1–5 into the prioritized ledger:241 P1 (actively losing business or excluding users) / P2 (material242 drag) / P3 (polish). Per finding: `dimension`, `evidence`243 (measurement / tension / screenshot / check / benchmark citation),244 `businessImpact` one-liner, concrete `fix`, `guides[]`.2453. **Uplift directions.** Close with 2–3 redesign directions framed246 exactly like uplift's variant role contract247 (`../uplift/SKILL.md` § The three-variant role contract):248 **A** faithful + fixes (names the findings it resolves), **B** one249 captured-but-underused trait amplified, **C** cinematic (motion as250 identity, register suggested per251 `../prototype/reference/motion-registers.md` § Selection252 heuristic). Drop B when the captured surface can't support a253 differentiated middle — two strong directions beat three weak254 ones.2554. **Write `stardust/audit/<domain-slug>/audit.json`** — schema,256 slug convention, and measurement rules in257 `reference/report-format.md` Part 1. Provenance `_provenance`258 first key.2595. **Render `stardust/audit/<domain-slug>/report.html`** by260 delegating to `$impeccable craft` with the brief in261 `reference/report-format.md` Part 2 — the same Skill-tool262 mechanic as prototype, and the same rule: **never hand-template263 the report**. Run the post-render validation checklist; on264 failure re-invoke craft with the specific violation. Open the265 result with `open stardust/audit/<domain-slug>/report.html`.2666. **Ledger recording (rollout projects only).** When267 `stardust/rollout/rollout.json` exists, record each finding into268 the delivery ledger via269 `node skills/rollout/scripts/findings.mjs record` with source270 namespace `audit:` — `--source audit:<dimension>`, `--layer` from271 the mapping below, severity carried through, `--fixability`272 normalized per `../rollout/reference/audit-sources.md`273 § Recording an external finding. Write each returned id into the274 finding's `ledgerId`.275276 | audit dimension | ledger layer |277 |---|---|278 | `brand-expression` | `brand-tensions` |279 | `visual-hierarchy-craft` | `design-ux` |280 | `conversion-focus` | `content-conversion` |281 | `accessibility` | `accessibility` |282 | `technical-seo` | `seo` (site-wide: `cross-page`) |283 | `content-llm-visibility` | `ai-search` |284 | `performance` | `seo` |2852867. **`--deploy`.** When passed, publish `report.html` via the DA287 transport per `../deploy/da-deploy-protocol.md` — PUT the file as288 a single source, POST preview, POST live, verify the delivered289 URL returns 200 — and print the delivered URL. Transport only;290 never run deploy's section→block conversion on the report.2918. **Chat summary.** Short — the work is on disk and openable:292293 ```294 audit complete — <url>295296 Site health: <overall>/100297 <dimension>: <score> × 7 (not-measured dimensions listed with reasons)298299 Findings: <n> P1 · <n> P2 · <n> P3300 Top lever: <the single highest-impact P1, one line>301302 Report: stardust/audit/<domain-slug>/report.html303 Data: stardust/audit/<domain-slug>/audit.json304305 Next: run stardust:uplift <url> — the report's closing directions306 are its variant briefs.307 ```308309## Degradation ladder310311Probed once in Phase 0; every degradation is recorded in312`audit.json#degradations` and rendered in the report's methodology313appendix. None of these stops the audit.314315| capability absent | behavior |316|---|---|317| refero MCP | skip Phase 5; `benchmarks.status: "skipped"` with reason |318| marketing-skills | run the Phase 3 / Phase 4 checks directly (tabled above) |319| modern-web-guidance | generic remediation text; `guides: []` |320| PageSpeed Insights | Playwright-only lab metrics; measurement note says lab TBT proxies INP |321| Playwright pixel sampling infeasible | `brandColorShare` ships as `method: "surface-estimate"` with basis |322| rollout project | no ledger recording; `ledgerId: null` on every finding |323324## Hard constraints325326- **No fabricated data.** A measurement that could not be taken is327 `not measured (<reason>)` in both artifacts. Estimates are labeled328 with method + basis. This is the same discipline extract enforces329 against synthesis (`../extract/SKILL.md` § Failure modes) —330 fabricated audit numbers are worse than missing ones because they331 are actionable-looking and wrong.332- **Evidence discipline.** Every finding cites observable evidence:333 a measurement key, a `T-*` tension id, a screenshot region, a334 check id, or a benchmark URL. Uncited claims are cut in synthesis.335- **Report is craft-rendered.** `report.html` is authored by336 `$impeccable craft` against the brief in337 `reference/report-format.md`, validated afterward — never338 hand-templated, never hand-patched.339- **Provenance is mandatory** on both artifacts, per340 `../stardust/reference/artifact-map.md` § Provenance shapes.341- **Non-interactive.** No questions in normal flow; assumptions are342 stated in the report. The only stops are the two below.343- **Audit does not fix.** Fixes belong to `uplift` (page redesign),344 `direct` Phase 2.5 (improvements list), and rollout's optimize345 loop (platform autofix). Audit names the fix; it never edits the346 site.347348## Stop conditions349350Stop and surface only if:351352(a) **Extract fails entirely** — site unreachable, structure353 unparseable, bot-management block past the headed-Chrome354 fallback. Surface extract's error verbatim; nothing to audit.355(b) **impeccable unavailable** — Phase 2's critique/audit arms and356 Phase 6's report render require it. Per the Phase 0 carve-out,357 the run continues in degraded mode (VISION pass, SEO/technical,358 LLM visibility, benchmarks all still fire) and writes359 `audit.json`; then stop and tell the user the designed report360 needs the impeccable plugin — deliver the data, not a361 hand-templated substitute.362363Everything else degrades per the ladder; the audit never stops for364confirmation in normal flow.365366## Outputs367368```369stardust/370├── current/ ← from extract (reused when <7 days old)371│ ├── _brand-extraction.json372│ ├── brand-review.html ← Tensions section = Phase 1 input373│ ├── pages/<slug>.json374│ └── assets/screenshots/<slug>.png ← VISION-pass + report evidence figures375└── audit/376 └── <domain-slug>/ ← hostname, www-stripped, dots → dashes377 ├── audit.json ← scorecard, measurements, findings[], provenance378 └── report.html ← craft-rendered, self-contained379380stardust/rollout/optimize/findings.json ← appended via findings.mjs (rollout projects only)381```382383Audit writes no `state.json` entries — extraction state belongs to384`extract`; audit's own artifacts are self-describing via provenance.385Re-running audit against a fresh extraction overwrites386`stardust/audit/<domain-slug>/`; ledger recordings dedupe by the387ledger's own id hash.388389## Scope390391- Audits and prescribes; never modifies the site or its redesign392 artifacts.393- One origin per run. Auditing a competitor set is N runs.394- The natural continuations: `stardust:uplift <url>` (the closing395 directions are its variant briefs), `stardust:direct` (findings396 feed the Phase 2.5 improvements list), rollout's optimize loop397 (ledger findings with known check ids autofix on AEM).398399## References400401- `reference/scoring.md` — the seven dimensions, weights, observable402 anchors at 40/70/90, scoring procedure.403- `reference/report-format.md` — `audit.json` schema (Part 1) and404 the `report.html` craft brief + post-render validation (Part 2).405- `../extract/SKILL.md` — crawl, capture, brand-surface extraction;406 § Failure modes for the anti-synthesis discipline.407- `../extract/reference/brand-review-template.md` § Tensions — the408 `T-*` detector catalog Phase 1 carries forward.409- `../prototype/SKILL.md` § Invoking impeccable — the Skill-tool410 delegation mechanic reused for critique (Phase 2) and the report411 render (Phase 6).412- `../rollout/reference/audit-sources.md` — the findings-ledger413 normalization rules (severity, fixability) Phase 6 applies.414- `../rollout/reference/checks.md` — baseline check ids to reuse so415 AEM autofix picks the findings up.416- `../rollout/scripts/findings.mjs` — the ledger writer (`record`).417- `../uplift/SKILL.md` § The three-variant role contract — the frame418 for the closing uplift directions.419- `../prototype/reference/motion-registers.md` § Selection heuristic420 — register suggestion for direction C.421- `../direct/SKILL.md` § Phase 2.5 — the improvements list audit422 findings feed on a subsequent redesign.423- `../deploy/da-deploy-protocol.md` — the DA transport behind424 `--deploy` (source PUT → preview → live; no block conversion).425- `../stardust/SKILL.md` § Setup — master-skill setup run in Phase 0.426- `../stardust/reference/artifact-map.md` — provenance shapes.