@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/enhance-web-redesign/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: enhance-web-redesign
+description: >
+  Upgrade an existing site/app to premium quality. Use when "redesign
+  this app" or "upgrade UI to premium". One-page polish → enhance-web-ui.
+  Plan-only slop audit → plan-antislop. New UI from scratch →
+  design-frontend.
+license: MIT
+---
+
+> Surface router: `/uiux`. You are here: `enhance-web-redesign`. Native iOS/Android (SwiftUI / Compose, no web layer) is out of scope — use Apple HIG / Material directly.
+
+# Redesign Skill
+
+**Degree of freedom: MIXED.** Taste and audit judgment `[HIGH freedom]`; keep-the-stack, no-break-functionality `[LOW freedom — run exactly]`.
+
+## How to reason
+
+1. **Scan** — framework, styling, current patterns
+2. **Triage** — AI-tells first (3+ = slop; kill those)
+3. **Fix** — existing stack, Fix Priority order; no rewrite
+4. **Preserve** — flows still work; deps exist before import
+
+## Worked example
+
+> **Scan:** Vite + Tailwind v4; Inter everywhere; three equal feature cards; no hover.
+> **Triage:** Inter, purple hero gradient, three cards, "Welcome to…" — four tells.
+> **Fix:** Geist; one accent; asymmetric feature row; hover/active; keep routes.
+> **Preserve:** `npm run build` green; no new framework.
+
+## Self-critique before reporting
+
+- **Same stack** — no framework or styling-library migration
+- **Tells killed** — Phase 0 fingerprints actually gone, not restyled in place
+- **States exist** — hover/focus/loading/empty/error present
+- **Right owner** — one-page polish → `enhance-web-ui`; plan-only slop → `plan-antislop`; greenfield → `design-frontend`
+
+## How This Works
+
+When applied to an existing project, follow this sequence:
+
+1. **Scan** — Read the codebase. Identify the framework, styling method (Tailwind, vanilla CSS, styled-components, etc.), and current design patterns.
+2. **Diagnose** — Run through the audit below. List every generic pattern, weak point, and missing state you find.
+3. **Fix** — Apply targeted upgrades working with the existing stack. Do not rewrite from scratch. Improve what's there.
+
+## Phase 0: 60-Second AI-Tell Triage  [HIGH freedom]
+
+Before the full audit, scan for the highest-signal "AI-generated look" fingerprints. If you spot 3+, the page reads as slop and these are the fastest wins. (Distilled from anti-slop research — see [anti-slop-ui](https://github.com/awaken7050dev/anti-slop-ui) and [taste-skill](https://github.com/Leonxlnx/taste-skill).)
+
+- [ ] **Inter / Roboto** as the only typeface
+- [ ] **Purple→blue gradient** on hero, buttons, or icons
+- [ ] **Three equal feature cards** in a row
+- [ ] **Pill-shaped everything** (uniform `rounded-full` badges + buttons)
+- [ ] **"Welcome to [Product]" / "improve your…"** hero copy
+- [ ] **Em dashes** sprinkled through every sentence of body copy
+- [ ] **Lucide/Feather icons** with a rocket = "launch", shield = "security"
+- [ ] **Centered-everything** symmetrical layout with no asymmetry or overlap
+- [ ] **Generic `shadow-lg`** pure-black shadows on white cards
+- [ ] **No hover / active / focus states** on interactive elements
+- [ ] **Cream / off-white page background** as the default canvas
+- [ ] **Italic accent word** in every headline
+- [ ] **"01 / 02 / 03" numbered or monospace eyebrow labels** above every section
+
+Kill these first, then run the full audit.
+
+## Design Audit  [HIGH freedom]
+
+### Typography
+
+Check for these problems and fix them:
+
+- **Browser default fonts or Inter everywhere.** Replace with a font that has character. Good options: `Geist`, `Outfit`, `Cabinet Grotesk`, `Satoshi`. For editorial/creative projects, pair a serif header with a sans-serif body.
+- **Headlines lack presence.** Increase size for display text, tighten letter-spacing, reduce line-height. Headlines should feel heavy and intentional.
+- **Body text too wide.** Limit paragraph width to roughly 65 characters. Increase line-height for readability.
+- **Only Regular (400) and Bold (700) weights used.** Introduce Medium (500) and SemiBold (600) for more subtle hierarchy.
+- **Numbers in proportional font.** Use a monospace font or enable tabular figures (`font-variant-numeric: tabular-nums`) for data-heavy interfaces.
+- **Missing letter-spacing adjustments.** Use negative tracking for large headers, positive tracking for small caps or labels.
+- **All-caps subheaders everywhere.** Try lowercase italics, sentence case, or small-caps instead.
+- **Orphaned words.** Single words sitting alone on the last line. Fix with `text-wrap: balance` or `text-wrap: pretty`.
+
+### Color and Surfaces
+
+- **Pure `#000000` background.** Replace with off-black, dark charcoal, or tinted dark (`#0a0a0a`, `#121212`, or a dark navy).
+- **Oversaturated accent colors.** Keep saturation below 80%. Desaturate accents so they blend with neutrals instead of screaming.
+- **More than one accent color.** Pick one. Remove the rest. Consistency beats variety.
+- **Mixing warm and cool grays.** Stick to one gray family. Tint all grays with a consistent hue (warm or cool, not both).
+- **Purple/blue "AI gradient" aesthetic.** This is the most common AI design fingerprint. Replace with neutral bases and a single, considered accent.
+- **Generic `box-shadow`.** Tint shadows to match the background hue. Use colored shadows (e.g., dark blue shadow on a blue background) instead of pure black at low opacity.
+- **Flat design with zero texture.** Add subtle noise, grain, or micro-patterns to backgrounds. Pure flat vectors feel sterile.
+- **Perfectly even gradients.** Break the uniformity with radial gradients, noise overlays, or mesh gradients instead of standard linear 45-degree fades.
+- **Inconsistent lighting direction.** Audit all shadows to ensure they suggest a single, consistent light source.
+- **Random dark sections in a light mode page (or vice versa).** A single dark-background section breaking an otherwise light page looks like a copy-paste accident. Either commit to a full dark mode or keep a consistent background tone throughout. If contrast is needed, use a slightly darker shade of the same palette — not a sudden jump to `#111` in the middle of a cream page.
+- **Empty, flat sections with no visual depth.** Sections that are just text on a plain background feel unfinished. Add high-quality background imagery (blurred, overlaid, or masked), subtle patterns, or ambient gradients. Use reliable placeholder sources like `https://picsum.photos/seed/{name}/1920/1080` when real assets are not available. Experiment with background images behind hero sections, feature blocks, or CTAs — even a subtle full-width photo at low opacity adds presence.
+
+### Layout
+
+- **Everything centered and symmetrical.** Break symmetry with offset margins, mixed aspect ratios, or left-aligned headers over centered content.
+- **Three equal card columns as feature row.** This is the most generic AI layout. Replace with a 2-column zig-zag, asymmetric grid, horizontal scroll, or masonry layout.
+- **Using `height: 100vh` for full-screen sections.** Replace with `min-height: 100dvh` to prevent layout jumping on mobile browsers (iOS Safari viewport bug).
+- **Complex flexbox percentage math.** Replace with CSS Grid for reliable multi-column structures.
+- **No max-width container.** Add a container constraint (around 1200-1440px) with auto margins so content doesn't stretch edge-to-edge on wide screens.
+- **Cards of equal height forced by flexbox.** Allow variable heights or use masonry when content varies in length.
+- **Uniform border-radius on everything.** Vary the radius: tighter on inner elements, softer on containers.
+- **No overlap or depth.** Elements sit flat next to each other. Use negative margins to create layering and visual depth.
+- **Symmetrical vertical padding.** Top and bottom padding are always identical. Adjust optically — bottom padding often needs to be slightly larger.
+- **Dashboard always has a left sidebar.** Try top navigation, a floating command menu, or a collapsible panel instead.
+- **Missing whitespace.** Double the spacing. Let the design breathe. Dense layouts work for data dashboards, not for marketing pages.
+- **Buttons not bottom-aligned in card groups.** When cards have different content lengths, CTAs end up at random heights. Pin buttons to the bottom of each card so they form a clean horizontal line regardless of content above.
+- **Feature lists starting at different vertical positions.** In pricing tables or comparison cards, the list of features should start at the same Y position across all columns. Use consistent spacing above the list or fixed-height title/price blocks.
+- **Inconsistent vertical rhythm in side-by-side elements.** When placing cards, columns, or panels next to each other, align shared elements (titles, descriptions, prices, buttons) across all items. Misaligned baselines make the layout look broken.
+- **Mathematical alignment that looks optically wrong.** Centering by the math doesn't always look centered to the eye. Icons next to text, play buttons in circles, or text in buttons often need 1-2px optical adjustments to feel right.
+
+### Interactivity and States
+
+- **No hover states on buttons.** Add background shift, slight scale, or translate on hover.
+- **No active/pressed feedback.** Add a subtle `scale(0.98)` or `translateY(1px)` on press to simulate a physical click.
+- **Instant transitions with zero duration.** Add smooth transitions (200-300ms) to all interactive elements.
+- **Missing focus ring.** Ensure visible focus indicators for keyboard navigation. This is an accessibility requirement, not optional.
+- **No loading states.** Replace generic circular spinners with skeleton loaders that match the layout shape.
+- **No empty states.** An empty dashboard showing nothing is a missed opportunity. Design a composed "getting started" view.
+- **No error states.** Add clear, inline error messages for forms. Do not use `window.alert()`.
+- **Dead links.** Buttons that link to `#`. Either link to real destinations or visually disable them.
+- **No indication of current page in navigation.** Style the active nav link differently so users know where they are.
+- **Scroll jumping.** Anchor clicks jump instantly. Add `scroll-behavior: smooth`.
+- **Animations using `top`, `left`, `width`, `height`.** Switch to `transform` and `opacity` for GPU-accelerated, smooth animation.
+
+### Content
+
+- **Generic names like "John Doe" or "Jane Smith".** Use diverse, realistic-sounding names.
+- **Fake round numbers like `99.99%`, `50%`, `$100.00`.** Use real figures where the repo or brief has them; otherwise label sample values as mock (`<!-- mock -->`) rather than inventing precise-looking ones (same rule as `enhance-web-landing` 4.9).
+- **Placeholder company names like "Acme Corp", "Nexus", "SmartFlow".** Invent contextual, believable brand names.
+- **AI copywriting clichés.** "Unleash", "Next-Gen", "Game-changer", "Tapestry", "In the world of…", "Welcome to [Product]" read as generated. Write plain, specific copy that names what the product does.
+- **Exclamation marks in success messages.** Remove them. Be confident, not loud.
+- **"Oops!" error messages.** Be direct: "Connection failed. Please try again."
+- **Passive voice.** Use active voice: "We couldn't save your changes" instead of "Mistakes were made."
+- **All blog post dates identical.** Randomize dates to appear real.
+- **Same avatar image for multiple users.** Use unique assets for every distinct person.
+- **Lorem Ipsum.** Never use placeholder latin text. Write real draft copy.
+- **Title Case On Every Header.** Use sentence case instead.
+
+### Component Patterns
+
+- **Generic card look (border + shadow + white background).** Remove the border, or use only background color, or use only spacing. Cards should exist only when elevation communicates hierarchy.
+- **Always one filled button + one ghost button.** Add text links or tertiary styles to reduce visual noise.
+- **Pill-shaped "New" and "Beta" badges.** Try square badges, flags, or plain text labels.
+- **Accordion FAQ sections.** Use a side-by-side list, searchable help, or inline progressive disclosure.
+- **3-card carousel testimonials with dots.** Replace with a masonry wall, embedded social posts, or a single rotating quote.
+- **Pricing table with 3 towers.** Highlight the recommended tier with color and emphasis, not just extra height.
+- **Modals for everything.** Use inline editing, slide-over panels, or expandable sections instead of popups for simple actions.
+- **Avatar circles exclusively.** Try squircles or rounded squares for a less generic look.
+- **Light/dark toggle always a sun/moon switch.** Use a dropdown, system preference detection, or integrate it into settings.
+- **Footer link farm with 4 columns.** Simplify. Focus on main navigational paths and legally required links.
+
+### Iconography
+
+- **Lucide or Feather icons exclusively.** These are the "default" AI icon choice. Use Phosphor, Heroicons, or a custom set for differentiation.
+- **Rocketship for "Launch", shield for "Security".** Replace cliche metaphors with less obvious icons (bolt, fingerprint, spark, vault).
+- **Inconsistent stroke widths across icons.** Audit all icons and standardize to one stroke weight.
+- **Missing favicon.** Always include a branded favicon.
+- **Stock "diverse team" photos.** Use real team photos, candid shots, or a consistent illustration style instead of uncanny stock imagery.
+
+### Code Quality
+
+- **Div soup.** Use semantic HTML: `<nav>`, `<main>`, `<article>`, `<aside>`, `<section>`.
+- **Inline styles mixed with CSS classes.** Move all styling to the project's styling system.
+- **Hardcoded pixel widths.** Use relative units (`%`, `rem`, `em`, `max-width`) for flexible layouts.
+- **Missing alt text on images.** Describe image content for screen readers. Never leave `alt=""` or `alt="image"` on meaningful images.
+- **Arbitrary z-index values like `9999`.** Establish a clean z-index scale in the theme/variables.
+- **Commented-out dead code.** Remove all debug artifacts before shipping.
+- **Import hallucinations.** Check that every import actually exists in `package.json` or the project dependencies.
+- **Missing meta tags.** Add proper `<title>`, `description`, `og:image`, and social sharing meta tags.
+
+### Strategic Omissions (What AI Typically Forgets)
+
+- **No legal links.** Add privacy policy and terms of service links in the footer.
+- **No "back" navigation.** Dead ends in user flows. Every page needs a way back.
+- **No custom 404 page.** Design a helpful, branded "page not found" experience.
+- **No form validation.** Add client-side validation for emails, required fields, and format checks.
+- **No "skip to content" link.** Essential for keyboard users. Add a hidden skip-link.
+- **No cookie consent.** If required by jurisdiction, add a compliant consent banner.
+
+## Upgrade Techniques  [HIGH freedom]
+
+When upgrading a project, pull from these high-impact techniques to replace generic patterns:
+
+### Typography Upgrades
+- **Variable font animation.** Interpolate weight or width on scroll or hover for text that feels alive.
+- **Outlined-to-fill transitions.** Text starts as a stroke outline and fills with color on scroll entry or interaction.
+- **Text mask reveals.** Large typography acting as a window to video or animated imagery behind it.
+
+### Layout Upgrades
+- **Broken grid / asymmetry.** Elements that deliberately ignore column structure — overlapping, bleeding off-screen, or offset with calculated randomness.
+- **Whitespace maximization.** Aggressive use of negative space to force focus on a single element.
+- **Parallax card stacks.** Sections that stick and physically stack over each other during scroll.
+- **Split-screen scroll.** Two halves of the screen sliding in opposite directions.
+
+### Motion Upgrades
+- **Smooth scroll with inertia.** Decouple scrolling from browser defaults for a heavier, cinematic feel.
+- **Staggered entry.** Elements cascade in with slight delays, combining Y-axis translation with opacity fade. Never mount everything at once.
+- **Spring physics.** Replace linear easing with spring-based motion for a natural, weighty feel on all interactive elements.
+- **Scroll-driven reveals.** Content entering through expanding masks, wipes, or draw-on SVG paths tied to scroll progress.
+
+### Surface Upgrades
+- **True glassmorphism.** Go beyond `backdrop-filter: blur`. Add a 1px inner border and a subtle inner shadow to simulate edge refraction.
+- **Spotlight borders.** Card borders that illuminate dynamically under the cursor.
+- **Grain and noise overlays.** A fixed, pointer-events-none overlay with subtle noise to break digital flatness.
+- **Colored, tinted shadows.** Shadows that carry the hue of the background rather than using generic black.
+
+## Fix Priority  [HIGH freedom]
+
+Apply changes in this order for maximum visual impact with minimum risk:
+
+1. **Font swap** — biggest instant improvement, lowest risk
+2. **Color palette cleanup** — remove clashing or oversaturated colors
+3. **Hover and active states** — makes the interface feel alive
+4. **Layout and spacing** — proper grid, max-width, consistent padding
+5. **Replace generic components** — swap cliche patterns for modern alternatives
+6. **Add loading, empty, and error states** — makes it feel finished
+7. **Polish typography scale and spacing** — the premium final touch
+
+## Rules  [LOW freedom — run exactly]
+
+- Work with the existing tech stack. Do not migrate frameworks or styling libraries.
+- Do not break existing functionality: keep routes, handlers, and states; run the repo's build and checks before reporting.
+- Before importing any new library, check the project's dependency file first.
+- If the project uses Tailwind, check the version (v3 vs v4) before modifying config.
+- If the project has no framework, use vanilla CSS.
+- Keep changes reviewable and focused. Small, targeted improvements over big rewrites.

package/skills/enhance-web-seo/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: enhance-web-seo
+description: >
+  Audit and fix SEO for a web app. Use when "improve SEO", "SEO audit", "add
+  meta tags", "add structured data", "sitemap", "canonical URLs", "Open
+  Graph", "Google indexing", "rich results", or "why is my site not ranking".
+license: MIT
+---
+
+# enhance-web-seo — SEO Audit & Implementation
+
+**Degree of freedom: MIXED.** Title/snippet judgment `[HIGH freedom]`; live probes, robots/sitemap, and re-measure `[LOW freedom — run exactly]`.
+
+**Google does not rank pages it cannot read, understand, or trust.** This skill
+finds every gap between your app and how search engines see it, then fixes them
+in order of impact.
+
+Before browser work, read `protocol-browser-anti-stall` and apply it.
+
+## How to reason
+
+1. **Detect** — metadata API, robots, sitemap, generator
+2. **Measure** — live title, OG, JSON-LD, headings, LCP/CLS
+3. **Fix** — impact order: title → OG → robots/sitemap → JSON-LD → CWV
+4. **Re-measure** — same probes on each changed route
+
+## Worked example
+
+> **Detect:** Next.js App Router; root `metadata` only; no `sitemap.ts`; `/robots.txt` 404.
+> **Measure:** product pages inherit the home title; no canonical; no JSON-LD; LCP 3.1s.
+> **Fix:** `generateMetadata` per product; `app/sitemap.ts` + robots; Product JSON-LD; image dimensions.
+> **Re-measure:** unique titles; OG image resolves; sitemap lists products; LCP < 2.5s.
+
+## Self-critique before reporting
+
+- **Live, not source-only** — titles/OG/JSON-LD read from the rendered head
+- **Unique per page** — no inherited home title on inner routes
+- **Indexable** — robots/sitemap exist; no accidental `Disallow: /` or noindex
+- **Right owner** — JS/LCP budget → `audit-bundle-size`; AEO citations → `plan-aeo-readiness`
+
+---
+
+## Phase 0: Detect the stack  [HIGH freedom]
+
+```
+package.json        → Next.js Metadata API, remix-utils/seo, @vueuse/head, etc.
+src/app/layout.tsx  → existing metadata export (Next.js App Router)
+src/app/head.tsx    → legacy Head component
+public/robots.txt   → existing robots config
+public/sitemap.xml  → existing sitemap
+```
+
+Also check if a sitemap generator is configured (`next-sitemap`, `astro-sitemap`,
+SvelteKit's `@sveltejs/adapter-static` sitemap, etc.).
+
+---
+
+## Phase 1: Live page audit (Playwright)  [LOW freedom — run exactly]
+
+For every public-facing route, run the following:
+
+### 1a. Navigate and capture head
+
+```javascript
+// eval after goto
+const seo = await page.evaluate(() => ({
+  title: document.title,
+  description: document.querySelector('meta[name="description"]')?.content,
+  canonical: document.querySelector('link[rel="canonical"]')?.href,
+  og_title: document.querySelector('meta[property="og:title"]')?.content,
+  og_description: document.querySelector('meta[property="og:description"]')?.content,
+  og_image: document.querySelector('meta[property="og:image"]')?.content,
+  og_url: document.querySelector('meta[property="og:url"]')?.content,
+  twitter_card: document.querySelector('meta[name="twitter:card"]')?.content,
+  robots: document.querySelector('meta[name="robots"]')?.content,
+  jsonld: [...document.querySelectorAll('script[type="application/ld+json"]')]
+            .map(s => s.textContent),
+}));
+```
+
+### 1b. Heading hierarchy
+
+```javascript
+const headings = await page.evaluate(() =>
+  [...document.querySelectorAll('h1,h2,h3,h4,h5,h6')]
+    .map(h => ({ tag: h.tagName, text: h.textContent.trim().slice(0, 60) }))
+);
+```
+
+Rules: exactly one `<h1>` per page; `<h2>` never skips to `<h4>` without `<h3>`.
+
+### 1c. Image alt text
+
+```javascript
+const images = await page.evaluate(() =>
+  [...document.querySelectorAll('img')]
+    .filter(img => !img.alt || img.alt.trim() === '')
+    .map(img => img.src.slice(-60))
+);
+```
+
+### 1d. Core Web Vitals
+
+CWV (LCP, INP, CLS) is a ranking input. Measure field p75 via
+CrUX/PSI. Do **not** fix CWV here — hand off:
+- LCP / INP / CLS root cause → `audit-performance` §Loading Priority & Speculation
+- JS weight → `audit-bundle-size`
+- Instant navigations → `enhance-web-instant-nav`
+Record before/after p75 in this skill's re-measure step.
+
+---
+
+## Phase 2: Technical SEO checks  [HIGH freedom]
+
+### 2a. robots.txt
+
+`goto` to `/robots.txt`. Check:
+- File exists and returns 200 (not 404)
+- No `Disallow: /` unless intentional (private app)
+- Sitemap URL referenced: `Sitemap: https://yourdomain.com/sitemap.xml`
+- No important pages accidentally blocked
+
+### 2b. Sitemap
+
+Navigate to `/sitemap.xml` or `/sitemap-index.xml`. Check:
+- Exists and is valid XML
+- Contains all important public routes (not just `/`)
+- `<lastmod>` dates are current, not hardcoded to a past date
+- No 404 or noindex pages included
+
+### 2c. Structured data (JSON-LD)
+
+Validate each JSON-LD block found in Phase 1a:
+- `@context: "https://schema.org"` present
+- `@type` matches the page content (Article, Product, Organization, WebSite, BreadcrumbList, FAQPage, etc.)
+- Required fields for the type are present (check `references/structured-data-types.md`)
+- No syntax errors in the JSON
+
+### 2d. Canonical URLs
+
+- Every page has a `<link rel="canonical">` pointing to its definitive URL
+- No page canonicalises to a 404 or redirect
+- Pagination: page 2+ should have canonical pointing to itself (not page 1)
+- Duplicate content (www vs non-www, http vs https): one canonical, one redirect
+
+---
+
+## Phase 3: Research current best practices  [HIGH freedom]
+
+Follow `/research`: Context7 for the framework's metadata, sitemap, and robots API; Firecrawl for current Google guidance on CWV, structured data, and rich results, dated to now. Anchor to the framework version actually installed.
+
+---
+
+## Phase 4: Fix — ordered by impact  [HIGH freedom]
+
+### Priority 1 — Page title and meta description (every page)
+
+Every public page needs a unique, descriptive title (50–60 chars) and
+meta description (150–160 chars).
+
+**Next.js App Router:**
+```typescript
+// app/page.tsx
+export const metadata: Metadata = {
+  title: 'Specific Page Title — Brand Name',
+  description: 'One or two sentences that describe this page for someone scanning search results.',
+};
+```
+
+**Next.js dynamic routes:**
+```typescript
+export async function generateMetadata({ params }): Promise<Metadata> {
+  const item = await fetchItem(params.id);
+  return {
+    title: `${item.name} — Brand Name`,
+    description: item.summary,
+    openGraph: { title: item.name, description: item.summary, images: [item.coverImage] },
+  };
+}
+```
+
+### Priority 2 — Open Graph and Twitter Card
+
+Required for social sharing previews. Every page needs at minimum:
+```typescript
+openGraph: {
+  title: 'Page Title',
+  description: 'Page description',
+  url: 'https://yourdomain.com/page',
+  siteName: 'Brand Name',
+  images: [{ url: '/og-image.png', width: 1200, height: 630 }],
+  type: 'website', // or 'article' for blog posts
+},
+twitter: {
+  card: 'summary_large_image',
+  title: 'Page Title',
+  description: 'Page description',
+  images: ['/og-image.png'],
+},
+```
+
+### Priority 3 — robots.txt and sitemap
+
+**robots.txt** (static file at `public/robots.txt`):
+```
+User-agent: *
+Allow: /
+
+Sitemap: https://yourdomain.com/sitemap.xml
+```
+
+**Sitemap** — use the framework's built-in generator where available:
+- Next.js App Router: `app/sitemap.ts` returning `MetadataRoute.Sitemap`
+- SvelteKit: `+server.ts` returning XML response
+- Remix: `sitemap[.]xml.ts` resource route
+
+### Priority 4 — Structured data (JSON-LD)
+
+Add to the relevant page layout:
+```typescript
+// For a website home page
+const jsonLd = {
+  '@context': 'https://schema.org',
+  '@type': 'WebSite',
+  name: 'Brand Name',
+  url: 'https://yourdomain.com',
+  potentialAction: {
+    '@type': 'SearchAction',
+    target: 'https://yourdomain.com/search?q={search_term_string}',
+    'query-input': 'required name=search_term_string',
+  },
+};
+// Inject via: <script type="application/ld+json">{JSON.stringify(jsonLd)}</script>
+```
+
+### Priority 5 — Core Web Vitals fixes
+
+See `audit-bundle-size` for JS bundle → LCP fixes.
+For CLS: ensure images have explicit `width`/`height`, fonts use `font-display: swap`,
+ads/embeds have reserved space.
+
+---
+
+## Phase 5: Verify with Playwright  [LOW freedom — do not skip]
+
+After fixes, re-run Phase 1 checks on each modified page. Confirm:
+- `document.title` and meta description match the intent
+- OG tags present and well-formed
+- JSON-LD valid (no JSON.parse errors)
+- LCP improved or within threshold
+- No new console errors introduced
+
+---
+
+## SEO audit checklist
+
+```
+Per page:
+- [ ] Unique descriptive title (50–60 chars)
+- [ ] Meta description (150–160 chars), not cut off
+- [ ] Exactly one <h1>
+- [ ] Heading hierarchy correct (no skipped levels)
+- [ ] All images have alt text
+- [ ] Canonical URL present and correct
+- [ ] OG title, description, image
+- [ ] Twitter card meta
+- [ ] JSON-LD structured data where relevant
+
+Site-wide:
+- [ ] robots.txt exists and correct
+- [ ] Sitemap exists and up to date
+- [ ] No important pages noindexed accidentally
+- [ ] HTTPS enforced, no mixed content
+- [ ] LCP < 2.5 s
+- [ ] CLS < 0.1
+```