website-build-skill 0.1.0

package/skills/website-build-skill/playbooks/accessibility.md

@@ -0,0 +1,91 @@
+# Test whether people can complete the task
+
+Date rule: [establish ASK DATE and revalidate claims](research-and-memory.md#ask-date-rule).
+Source status: external facts and example commands are UNVERIFIED until checked for the chosen version and engagement.
+Record opened URLs, source dates or unknown, actual access dates, and supporting evidence.
+
+Question: can the site's primary journey work across input and perception needs?
+
+## Establish the target
+
+Start with the method's WCAG 2.2 AA baseline and verify the current W3C release,
+applicable target level, and relevant criteria as of ASK DATE before relying on it.
+Record a newer applicable release or erratum without silently changing an approved target.
+Name each critical journey and its routes, controls, errors, and completion state.
+Require manual evidence for every critical journey as well as automated checks.
+
+## Use meaningful structure
+
+Choose headings for hierarchy, landmarks for page regions, links for navigation,
+and buttons for actions. Give controls names that make sense out of context.
+Use native controls when they meet the need and test any custom control fully.
+Expose expanded/selected/invalid state and relationships accurately.
+Do not use an icon, color, or positional instruction as the only meaning.
+
+## Exercise keyboard and focus
+
+Navigate from entry through completion using keyboard only.
+Test menus, dialogs, validation errors, dismissal, retry, and success.
+Record visible focus, logical order, no trap, and restoration after closing overlays.
+Confirm focused content is visible and not hidden behind sticky UI.
+Test the escape path and focus destination when asynchronous content replaces a control.
+
+## Compute contrast
+
+Use a calculator or runner with actual foreground and background inputs.
+For translucent layers, gradients, or images, compute the rendered composition and
+inspect the relevant worst-case locations and control states.
+Record font size/weight, criterion, threshold, unrounded ratio, method, and result.
+The baseline text thresholds are 4.5:1 for normal text and 3:1 for qualifying large text;
+verify the authoritative criteria and qualification rules before applying them.
+Evaluate meaningful control boundaries and focus under their applicable criteria.
+A color pair with no computed ratio is UNVERIFIED and cannot pass.
+Never round a failure upward or silently change an approved brand role to claim success.
+
+## Test communication and recovery
+
+Associate labels and descriptions with inputs; preserve useful entered data on errors.
+Explain each error, its location, and a practical way to recover.
+Test status announcements with a named screen reader/browser combination.
+Inspect image alternatives for their actual purpose, with empty alternatives for decoration.
+Provide required media alternatives and usable controls.
+Automated semantics checks supplement actual assistive-technology journeys.
+
+## Check reflow and motion
+
+The method proposes widths of 320, 390, 768, and 1280 CSS pixels for layout checks.
+Test text zoom at 200% and reflow separately against the applicable criteria.
+Record unintended horizontal scrolling, clipped controls, or hidden content.
+Check target size and spacing against the verified criterion, not a remembered number.
+Honor reduced motion and provide pause controls where required.
+Do not make information available only through animation, hover, or precise pointing.
+Inspect flashing hazards and preserve useful content without JavaScript.
+
+## Work a small example
+
+A dialog opens from an inquiry button, traps no user, names its purpose, and can close.
+A missing required field exposes a linked error and preserves the other entries.
+After closing, focus returns to the inquiry trigger.
+Capture each transition and its result, not only the default dialog screenshot.
+
+## Verify and remediate
+
+Write site-work/qa/accessibility.md and site-work/qa/contrast.md.
+For each result record route/state, candidate, tool/environment, criterion, inputs,
+observed behavior, evidence, impact, owner, and retest result.
+Apply checklists/accessibility.md AX01 through AX08.
+Re-run failed journeys after fixes; keep meaningful regressions for repeatable failures.
+Do not call an automated scanner a conformance certificate.
+Unavailable checks remain UNVERIFIED with a precise test and capable runner handoff.
+
+## Failure modes and source starting points
+
+- Visual guess: a brand-colored button is called accessible without calculation.
+- Mouse-only evidence: keyboard and error recovery remain untested.
+- Scanner certificate: no violations is mistaken for complete conformance.
+- Incomplete composition: opacity or image background is omitted from ratio inputs.
+
+Open https://www.w3.org/TR/WCAG22/ and current W3C release information.
+Open https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html
+for text contrast, with separate relevant criteria for controls and focus.
+Record actual source access before adopting the baseline in a project.

package/skills/website-build-skill/playbooks/choose-stack.md

@@ -0,0 +1,69 @@
+# Choose the smallest stack
+
+Date rule: [establish ASK DATE and revalidate claims](research-and-memory.md#ask-date-rule).
+Source status: external facts and example commands are UNVERIFIED until checked for the chosen version and engagement.
+Record opened URLs, source dates or unknown, actual access dates, and supporting evidence.
+
+Question: what is the least machinery that meets the approved brief?
+
+## Establish requirements
+
+Require accepted research, a confirmed brief, and a named mockup selection.
+List routes, content editor, publishing frequency, repeated structures, state,
+authentication, secrets, integration needs, localization, and maintenance owner.
+Separate request-time requirements from operations that can happen during a build.
+A framework preference is a preference, not proof of a runtime requirement.
+
+## Follow the decision tree
+
+```text
+Server secrets, authenticated state, or request-time behavior?
+  Compare a small separate endpoint with an application framework.
+  Select a framework only if the remaining application requirements earn it.
+Otherwise, repeated pages with shared structure or derived metadata?
+  Yes: scripted static builder with validated records and shared templates.
+  No: static HTML, CSS, and only the JavaScript the approved experience uses.
+Before adding another layer, name the requirement still unmet.
+```
+
+- Static HTML: load references/stacks/static-html.md for files, preview, and checks.
+- Scripted static: load references/stacks/scripted-static.md for data-derived routes.
+- Framework: load references/stacks/framework.md for server/client and runtime boundaries.
+
+## Compare costs and exits
+
+For each candidate, name its dependency, supported version, build/runtime needs,
+host constraints, upgrade path, editor workflow, and removal path.
+Evaluate APIs against official documentation opened in this engagement.
+Payments may use a hosted checkout. MDX may compile to static pages.
+Neither capability universally requires a particular framework.
+Do not add a CMS, analytics service, or paid dependency without an approved need.
+
+## Work a small example
+
+An invented workshop has a home page, visit page, and quarterly article series.
+Repeated articles share title, summary, image, and canonical metadata.
+A scripted static builder can derive articles and discovery files from one record.
+A private member area would add a server-state requirement that needs a new comparison.
+Do not silently extend the original stack decision to cover the member area.
+
+## Record and verify
+
+Write site-work/stack.md with requirements, rejected alternatives and reasons,
+selected recipe, dependencies, host, source claim IDs, and exact editing/build commands.
+Have another author add a representative next item from those instructions.
+Verify the new route, navigation, canonical, sitemap, and discovery entry together.
+Apply checklists/build.md B01 and B03 before accepting the decision.
+
+## Failure modes
+
+- Familiarity: choosing a framework before reading requirements or selecting a mockup.
+- Hidden server: static output depends on an undocumented secret-bearing process.
+- Editorial duplication: each new record needs manual changes in multiple metadata lists.
+- Unsupported API: copying a remembered version without a current source check.
+
+## Source starting points
+
+Open the selected framework and host's official versioned documentation.
+Inspect real source files at a recorded repository revision and check its license.
+The three local stack references are recipes to validate, not platform support claims.

package/skills/website-build-skill/playbooks/data-and-templates.md

@@ -0,0 +1,89 @@
+# Make repeated pages data changes
+
+Date rule: [establish ASK DATE and revalidate claims](research-and-memory.md#ask-date-rule).
+Source status: external facts and example commands are UNVERIFIED until checked for the chosen version and engagement.
+Record opened URLs, source dates or unknown, actual access dates, and supporting evidence.
+
+Question: how can another author add the tenth item without copying a page?
+
+## Separate responsibilities
+
+- Data: authored content and stable identities, owned independently of layout.
+- Validation: required fields, types, uniqueness, URLs, dates, and relationships.
+- Rendering: shared templates and context-specific serialization.
+- Output: generated pages and discovery artifacts, never edited as source.
+- Deployment: an allowlist of checked output, with private work files excluded.
+
+## Define the record contract
+
+Name an immutable record ID and a unique normalized route slug.
+Require title, useful body, and publication state inputs needed for that content type.
+Mark optional provider IDs and assets explicitly optional.
+Define the accepted identifier grammar from the provider's current official source.
+Trim before validating. Whitespace-only identifiers are absent, not valid values.
+Reject malformed required fields with record ID and field name before rendering.
+Omit missing optional controls and list omissions in the build report.
+
+## Compute state once
+
+Define publicationState(record, clock, timezonePolicy) as a pure decision.
+Use its result for page headings, badges, buttons, indexes, feeds, and discovery output.
+Use an explicit clock and timezone policy; do not infer dates from the build machine.
+Test immediately before, at, and after each release boundary.
+A static page changes state only after rebuilding. Name the rebuild trigger or human owner.
+
+## Keep helpers narrow
+
+| Helper | Contract | Adverse input |
+| --- | --- | --- |
+| esc | Escape text or quoted attribute metacharacters after string normalization. | Quotes, ampersands, angle brackets. |
+| jsonLd | Serialize valid JSON and escape literal less-than characters for a script element. | Script-terminator text followed by markup. |
+| safeUrl | Parse, normalize, and allow only schemes/origins appropriate to the URL role. | A script URL, control characters, or an unexpected origin. |
+| publicationState | Return one state and its allowed actions using the explicit clock. | A release boundary with an absent provider ID. |
+
+Use structural DOM/template APIs when available; do not concatenate untrusted attributes.
+Escaping is not URL validation, and safe JSON is not HTML sanitization.
+For rich HTML, use a reviewed sanitizer with a narrow allowlist or render text instead.
+
+## Work a small example
+
+```text
+record: workshop-introduction
+slug: workshop-introduction
+state: published
+provider_id: empty
+expected page: visible article, no provider link, no player, omission in build report
+expected discovery: the article route only if it satisfies the public-content rules
+```
+
+Validate the ID before constructing a URL, not after interpolating it into a suffix.
+Never render an empty href, a fragment stand-in, or an empty provider URL as recovery.
+A valid optional ID enables its control only when the shared state permits it.
+
+## Derive related outputs
+
+Generate route HTML, titles, descriptions, canonical URLs, social metadata,
+structured data, sitemap, and llms.txt from the same validated records.
+Sort deterministically. Use content or transformation identities for generated asset names.
+Exclude drafts and private records consistently from navigation and discovery.
+Keep Optimizer's authored inputs immutable when Builder integrates a revision.
+
+## Verify the generated artifact
+
+Run checklists/build.md B02 through B07 on rendered HTML.
+Exercise quotes, ampersands, angle brackets, script terminators, rejected schemes,
+empty and whitespace IDs, duplicate slugs, long copy, missing assets, and boundary dates.
+Prove hostile text stays text, valid JSON parses, and unsafe actions are absent.
+Add one representative record and inspect every derived surface.
+Rebuild unchanged inputs twice and investigate output differences.
+
+## Failure modes and sources
+
+- Late validation: malformed data reaches templates before a meaningful error.
+- Split state: badges and buttons each implement a separate date condition.
+- Safe-looking source: only the template is checked while generated HTML is broken.
+- Quiet omission: optional data disappears without an author-visible report.
+
+Open the chosen template engine's escaping documentation, the URL API documentation,
+and https://html.spec.whatwg.org/multipage/scripting.html for script parsing context.
+Record source-opening evidence before relying on an implementation detail.

package/skills/website-build-skill/playbooks/deploy-and-operate.md

@@ -0,0 +1,87 @@
+# Promote an exact, operable release
+
+Date rule: [establish ASK DATE and revalidate claims](research-and-memory.md#ask-date-rule).
+Source status: external facts and example commands are UNVERIFIED until checked for the chosen version and engagement.
+Record opened URLs, source dates or unknown, actual access dates, and supporting evidence.
+
+Question: can a cold reader release, verify, and recover this site from one document?
+
+## Establish release authority and identity
+
+Require the brief, user selection, current research, QA receipts, independent review,
+and ROUND 1 dispositions with regressions on the final candidate.
+Name target account, project, domain, operator, and authorized action.
+Existing explicit authorization is sufficient within its scope.
+If authority is missing, finish the reviewable candidate before asking at that boundary.
+Do not infer permission to buy services, create accounts, change unrelated DNS, or rotate keys.
+
+Record source revision, build environment, immutable artifact digest, and preview identity.
+If review fixes changed the candidate, retain the reviewed predecessor, explained diff,
+post-fix harness, and final digest. Unexplained changes invalidate affected evidence.
+Identify a known-working rollback artifact and its documented restoration command.
+An initial release needs an explicit safe recovery plan when no predecessor exists.
+
+## Prepare and promote
+
+Build cleanly using the documented command and locked dependencies where applicable.
+Inspect the actual upload allowlist for research, private assets, credentials, and unrelated files.
+Test the preview's routes and production configuration before promotion.
+Promote the checked bytes rather than rebuilding from a moving source revision.
+Record the command/action, actual response, deployment identifier, timestamp, and public URLs.
+A successful command is evidence of a deploy operation, not a working public journey.
+
+## Verify the live release
+
+Check HTTPS, canonical hosts, redirects, intended routes, error paths, and assets.
+Complete the primary journey, including validation, submission, and recovery.
+Inspect actual CSP and other headers on all response classes.
+Check canonical metadata, social images, sitemap, llms.txt, and intentional exclusions.
+Inspect mobile and desktop behavior with production CSP enforced.
+Separate social-bot origin responses from third-party preview-cache results.
+Verify analytics at the intended property; loading a script does not prove receipt.
+Record absent field observations as UNVERIFIED with a follow-up owner.
+
+If a critical check fails, use the authorized recovery plan and verify the restored journey.
+Record both the failure and recovery evidence; do not hide rollback under a release PASS.
+Apply checklists/ship.md SH01 through SH10, including distinct pre-promotion and live phases.
+
+## Write one complete operations document
+
+Builder writes SITE_OPERATIONS.md in the authorized implementation root.
+Use templates/site-operations.md and replace blank contract fields with actual evidence.
+Keep these sections in order:
+
+1. What and why: purpose, audience, primary action, and deployed identity.
+2. Trigger: manual or scheduled content, build, and release events with owners.
+3. Invocation chain: editing through validation, build, preview, promotion, and verification.
+4. Dependencies: versions, host, integrations, credentials by mechanism only.
+5. Reads: content, assets, tokens, environment names, and approved external resources.
+6. Writes: generated output, deployed targets, logs, and runtime side effects.
+7. The closed loop: watcher, expected signal, cadence, recipient, and response.
+8. Failure modes: symptoms, diagnosis, recovery, and escalation owner.
+9. Run-and-verify by hand: exact working commands, success evidence, and rollback.
+10. Source of truth: source, deployed artifact, research/approval revisions, and maintenance owner.
+
+Name what watches the site, including nothing. Silence is not a monitoring plan.
+Include enough content-editing and recovery detail to avoid requiring a second document.
+Every untested command or procedure says UNVERIFIED and names the settling test.
+Never write secret values, authenticated URLs, or personal credentials into the document.
+
+## Maintain the result
+
+Record who adds content, approves brand changes, updates dependencies, and checks measurements.
+Scheduled publication requires an actual trigger; date-dependent templates do not self-run.
+Revalidate expired host, license, security, and search facts before later releases.
+Re-run checks affected by changed content, resources, forms, or dependencies.
+Keep rollback identities and retention limitations explicit.
+
+## Failure modes and sources
+
+- Artifact drift: deploying unreviewed files after a green harness.
+- False live proof: command success replaces browser and response evidence.
+- Missing loop: nobody receives an alert or knows how to run a manual check.
+- Untested recovery: a rollback command is documented as verified without a run.
+
+Open the selected host's current deployment, promotion, and recovery documentation.
+Record version, plan restrictions, actual access evidence, and authorized runtime receipts.
+No host procedure is assumed to work because this package describes it.

package/skills/website-build-skill/playbooks/embed-facades.md

@@ -0,0 +1,59 @@
+# Load providers after deliberate activation
+
+Date rule: [establish ASK DATE and revalidate claims](research-and-memory.md#ask-date-rule).
+Source status: external facts and example commands are UNVERIFIED until checked for the chosen version and engagement.
+Record opened URLs, source dates or unknown, actual access dates, and supporting evidence.
+
+Question: how can a visitor choose a player without paying its cost on arrival?
+
+## Validate the control
+
+Require a valid provider ID and an allowed destination before rendering a facade.
+Use the selected provider's current identifier and URL requirements.
+An absent or whitespace-only ID omits the entire control and records the omission.
+Do not replace it with a dead iframe, empty suffix, or empty link.
+
+## Render a local first state
+
+Show a local authorized poster, a useful description, and a real button.
+Reserve player space using actual aspect ratio to prevent layout shifts.
+Give the button an accessible action name, not only a play-shaped icon.
+Keep a safe outbound link available when loading or embedding fails.
+Do not fetch provider posters, preconnect, or inject provider SDKs before activation.
+
+## Implement a bounded state transition
+
+```text
+idle -> deliberate button activation -> loading -> ready
+loading -> error -> retry or safe outbound fallback
+ready + repeated activation -> no second iframe
+invalid identifier -> no facade and no outbound provider control
+```
+
+Create the iframe only on intentional keyboard or pointer activation.
+Set its title, reviewed source, and minimum necessary permissions.
+Select sandbox behavior from the provider's actual requirements and test it.
+Keep focus predictable while replacing content and announce loading/error states.
+Do not remove the focused button without a deliberate focus destination.
+Provide a no-JavaScript path to the approved outbound destination.
+
+## Verify the network boundary
+
+Start a clean browser session without cached provider resources.
+Inspect requests before activation: no iframe, poster, script, or provider connection.
+Activate by keyboard and pointer in separate checks.
+Inspect requests, layout stability, focus, error recovery, and repeated activation.
+Test with production CSP and network failure, including blocked third-party cookies.
+Record exact route, candidate, environment, request log, and results.
+Apply checklists/build.md B04 and checklists/performance-seo.md PS03.
+
+## Failure modes and sources
+
+- Cosmetic facade: a hidden iframe already fetched the provider.
+- Remote poster: the first state still contacts the provider.
+- Lost focus: swapping markup strands a keyboard user.
+- Overbroad policy: frame permissions allow unrelated origins or capabilities.
+
+Open the chosen provider's official embedding documentation and current browser
+iframe documentation. Retain the source ledger and network inspection evidence.
+Click-to-play is a performance/privacy boundary, not proof of consent compliance.

package/skills/website-build-skill/playbooks/image-pipeline.md

@@ -0,0 +1,73 @@
+# Deliver images for their actual slots
+
+Date rule: [establish ASK DATE and revalidate claims](research-and-memory.md#ask-date-rule).
+Source status: external facts and example commands are UNVERIFIED until checked for the chosen version and engagement.
+Record opened URLs, source dates or unknown, actual access dates, and supporting evidence.
+
+Question: how do images remain useful and sharp within the route's loading budget?
+
+## Inventory before transforming
+
+Record source identity, rights evidence, intrinsic dimensions, image role, focal point,
+crop intent, background/transparency, decorative status, and alt-text intent.
+Preserve authorized originals and required notices under Graphics ownership.
+Strip unnecessary sensitive metadata from public exports without altering the original.
+Unknown rights block release of that asset.
+
+## Choose transformations
+
+Measure layout slots at representative widths and display densities.
+Generate AVIF and WebP candidates using the selected supported sharp version.
+Retain a browser-usable original-format fallback for the same composition.
+Do not ship an unsuitable source format as the fallback solely because it is original.
+Record a conversion when the master is a design file rather than a web image.
+Compare compression by inspecting edges, small text, gradients, and the intended crop.
+Quality and width settings are choices to measure, never universal defaults.
+
+## Define a deterministic pipeline
+
+```text
+input: original bytes + crop + widths + quality settings + encoder version
+process: validate -> orient -> crop -> resize -> encode -> inspect
+output: content-keyed variants + actual dimensions + byte sizes + manifest
+invalidate: any input bytes, settings, crop, or encoder version changes
+```
+
+Use a documented TypeScript build script with sharp as a declared build dependency.
+Read current API documentation before implementing format options.
+Reject enlargements that cannot meet the approved visual requirement.
+Rebuild from source rather than recompressing already compressed derivatives.
+
+## Connect markup to layout
+
+Use picture sources for AVIF and WebP with an img fallback.
+Set srcset widths from actual exports and sizes from the rendered CSS slots.
+Set width and height from the real file and reserve the matching aspect ratio.
+Do not claim dimensions from a requested export setting without inspecting the result.
+Give meaningful images task-relevant alternatives; use empty alternatives for decoration.
+
+## Protect the first screen
+
+Identify the likely LCP image from the real route and a measurement trace.
+Make the important image discoverable in initial HTML and avoid lazy loading it.
+Lazy load appropriate below-fold images and test behavior with JavaScript unavailable.
+Avoid preloading every image; verify that a critical preload matches the selected resource.
+
+## Verify and hand off
+
+Inspect desktop/mobile crops and representative density combinations in a browser.
+Record the selected resource, actual dimensions, byte size, request timing, and visual result.
+Compare the route budget before and after the pipeline change.
+Measure each social card independently and pass its actual dimensions to Optimizer.
+Graphics hands an immutable export revision and rights ledger to Builder.
+Apply checklists/brand-and-mockups.md BM07 and checklists/performance-seo.md PS03.
+
+## Failure modes and sources
+
+- Mismatched sizes: the browser fetches a large variant for a narrow slot.
+- Crop loss: the focal subject disappears on mobile.
+- False dimensions: one social-card size is copied across unequal files.
+- Nondeterminism: unchanged originals churn names and invalidate caches.
+
+Open https://sharp.pixelplumbing.com/ and the selected browser image guidance.
+Record the exact API version, actual source access, and inspected export results.

package/skills/website-build-skill/playbooks/performance-budgets.md

@@ -0,0 +1,76 @@
+# Measure the experience against explicit budgets
+
+Date rule: [establish ASK DATE and revalidate claims](research-and-memory.md#ask-date-rule).
+Source status: external facts and example commands are UNVERIFIED until checked for the chosen version and engagement.
+Record opened URLs, source dates or unknown, actual access dates, and supporting evidence.
+
+Question: is the site fast enough for its visitors' routes, devices, and primary tasks?
+
+## Set route budgets before implementation
+
+Select representative routes: the main entry, a repeated content page, and the heaviest journey.
+Record viewport, device/CPU/network profile, cache state, tool version, and route state.
+Choose transfer, script, image, and third-party budgets from actual content and audience needs.
+Name the owner, rationale, method, and exception process for each budget.
+Do not invent a universal byte allowance or silently enlarge a missed target.
+
+## Separate proposed targets from evidence
+
+The method proposes a Lighthouse mobile performance median of at least 90 per route.
+The field baseline to revalidate is p75 LCP at most 2.5 seconds, INP at most 200 ms,
+and CLS at most 0.1, assessed separately by device class and reporting window.
+These numeric baselines are UNVERIFIED for the current engagement until the authoritative
+source is opened and its source date, access date, release, and applicability are recorded.
+Do not cite this playbook as proof of current external thresholds.
+
+Lab scores diagnose a controlled run. They do not establish real-user p75 or interaction quality.
+A new site can lack sufficient field observations; record UNVERIFIED, the follow-up owner,
+when to check again, and the intended data source. Do not invent a field PASS.
+
+## Run a repeatable lab series
+
+1. Build the identified candidate and serve its production output.
+2. Fix the environment, route state, and cold-cache conditions for the series.
+3. Run three comparable mobile Lighthouse measurements for each representative route.
+4. Retain every raw report, run timestamp, environment, and command.
+5. Use a calculator or runner to compute the median; retain its inputs and result.
+6. Compare the result to the recorded budget and investigate the causes of misses.
+
+Discard a run only for an evidenced invalid measurement, preserve it with the reason,
+and rerun under the same conditions. Never select only the best report.
+Budget exceptions need a named decision, remaining impact, and evidence, not a disguised PASS.
+
+## Diagnose and improve
+
+Use the trace to identify hero discovery delays, blocking resources, image overfetch,
+font swaps, third-party work, and unnecessary JavaScript.
+Test a bounded change and compare the same route under the same conditions.
+Use image-pipeline.md, self-hosted-fonts.md, and embed-facades.md for focused corrections.
+Keep animation optional, honor reduced motion, and suspend decorative work in hidden tabs.
+Check useful initial content and the primary navigation with JavaScript disabled.
+
+## Work a small example
+
+A route loads its local poster immediately but delays the third-party player until activation.
+Compare cold traces before and after the facade change.
+Inspect the pre-click request log and test keyboard activation before accepting the gain.
+A smaller transfer with a broken player fails the journey gate.
+
+## Save the evidence
+
+Write site-work/qa/build/performance.md with artifact identity, route budget table,
+raw report paths, computed medians, field-data status, failures, and follow-up owners.
+Apply checklists/performance-seo.md PS01 through PS04.
+Unknown tool access leaves measurement UNVERIFIED with commands for a capable runner.
+
+## Failure modes and source starting points
+
+- Lab/field substitution: a single score is called real-user performance.
+- Cherry picking: the best of several runs replaces the recorded series.
+- Budget drift: limits change after a failure without a reviewable decision.
+- Optimized screenshot: interactivity, reduced motion, and hidden-tab work go unchecked.
+
+Open https://web.dev/articles/defining-core-web-vitals-thresholds for field definitions.
+Open https://developer.chrome.com/docs/lighthouse/performance/performance-scoring
+for the chosen Lighthouse version and score interpretation.
+Keep source-opening receipts separate from site measurement reports.