@se-studio/skills 1.0.1

package/skills/contentful-cms-update-cms-guidelines/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: update-cms-guidelines
+description: Primary CMS guideline orchestration. Use `fresh` only after a full clean slate and complete pipeline (showcase → screenshots → new component prose via Phase B/C/D — never git-restore fragments). Use `sync` for incremental changes but always delete stale types. If the user is vague, ask whether they want a full clean regeneration or incremental sync before acting.
+license: Private
+metadata:
+  author: se-core-product
+  version: "1.1.0"
+---
+
+# Update CMS Guidelines
+
+This is the **primary entry point** for all CMS guideline work. It wraps the lower-level skills
+into three clear modes so you always know which path to take.
+
+## Terms: full regeneration vs incremental
+
+| Term | Meaning |
+|---|---|
+| **Full regeneration** (brand-new run) | **Clean slate** of generated artifacts, then rerun the **entire** pipeline: showcase data → mocks → field list → **all** screenshots (components **and** collections) → **new** component guideline markdown (Phase B + C + D for **every** type — no restoring old `.md` from git) → collection/external CLI step → merge → commit. Collections are CLI-regenerated; externals may need hand-filled sections after stub creation. |
+| **Incremental** (`sync` + targeted work) | Discovery/registrations are the source of truth. **Remove every stale artifact** for types no longer registered (fragments, PNGs, `screenshots/index.json` rows, `accepted-variants` JSON where your app tracks them). Then add or refresh only **new** or **changed** types (screenshots + `generate-cms-guidelines` single / generate-all partial). Always merge at the end if fragments changed. |
+
+**Not** a full regeneration: restoring `docs/cms-guidelines/components/*.md` (or externals) from `git checkout`, merge-only, or screenshots-only while leaving years-old prose in place.
+
+## When the user is vague
+
+Phrases like “regenerate guidelines”, “refresh CMS docs”, “update showcase/guidelines”, or “redo screenshots” are **ambiguous**.
+
+**Before doing substantial work, ask briefly:**
+
+1. Do you want a **full clean regeneration** (delete existing fragments and screenshots, rewrite every component guideline from scratch, full screenshot pass)?  
+2. Or an **incremental** update (sync with registrations — **including removing** dropped types — plus only new/changed types)?  
+3. Or something narrower (e.g. **merge-only**, **one component**, **collections CLI only**)?
+
+If they insist on “everything” / “from scratch” / “totally regenerate” / “wipe and rebuild”, treat that as **full regeneration** and follow **`fresh`** including the **clean slate** steps below — do **not** shortcut with git-restored fragments.
+
+## When to use which mode
+
+| Situation | Mode |
+|---|---|
+| New app — no guidelines exist yet | `fresh` |
+| User wants **total** / **full** / **clean-slate** regeneration | `fresh` (must include **clean slate** + full **generate-all-guidelines** Phase 3 for all components) |
+| Types added or removed in `registrations.ts` (incremental) | `sync` — **always** remove stale files and index entries, then add/refresh new types |
+| Fragment files edited manually, combined doc needs rebuild | `merge-only` |
+| Major refactor but user confirms they **do not** need new prose | Rare — confirm explicitly; otherwise use `fresh` |
+
+---
+
+## Inputs
+
+| Input | Example |
+|---|---|
+| App directory (repo-relative or absolute) | `apps/example-se2026` |
+| Port | `3012` |
+| Discovery URL | `http://localhost:3012/api/cms/discovery/` |
+| Mode | `fresh` \| `sync` \| `merge-only` |
+
+**App ports:**
+
+| App | Port |
+|---|---|
+| example-brightline | 3010 |
+| example-se2026 | 3012 |
+| example-om1 | 3013 |
+| example-empty | 3014 |
+| example-brightlifekids | 3015 |
+
+---
+
+## Mode: fresh
+
+Full pipeline from a **clean slate** (or a brand-new app). Expect roughly **30–90+ minutes** for a typical site (component count × LLM time for Phase B/C/D).
+
+### Step 0 — Clean slate (mandatory for true full regeneration)
+
+If any guideline or screenshot files already exist, **delete generated guideline outputs** before re-running the pipeline. Otherwise you risk mixed old/new content or skipping work.
+
+**Do:**
+
+1. Remove per-type fragments:  
+   `docs/cms-guidelines/components/*.md`, `docs/cms-guidelines/collections/*.md`, `docs/cms-guidelines/externals/*.md`  
+   **Keep** editorial/meta files if present (e.g. `README.md`, `CHECKLIST.md`, `LAYOUT.md`, `GENERATE_NEXT_*.md`).
+2. Remove merged bundle: `docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md`.
+3. Remove screenshots: all `docs/cms-guidelines/screenshots/components/*.png`, `.../collections/*.png`, `.../externals/*.png` (if used), then reset `docs/cms-guidelines/screenshots/index.json` to `[]` **or** delete it so captures recreate it.
+4. Clear showcase pipeline inputs as needed: remove `src/generated/showcase-examples.json`, `src/generated/showcase-mocks-draft.json`, and the tree `src/generated/cms-discovery/accepted-variants/` (or empty `components/` / `collections/` / `externals/` subdirs). Stub `src/generated/showcase-mocks.json` per **curate-showcase-mocks** if the import must compile.
+5. Remove any **duplicate** variant path some apps still have (e.g. `generated/cms-discovery/accepted-variants/` at repo root of the app) if it is not the canonical `src/generated/...` tree.
+6. Optionally reset `generated/cms-discovery/colour-hints.json` if you want colour hints re-derived during Phase C.
+
+**Do not** (for a claimed full regeneration):
+
+- Restore `docs/cms-guidelines/components/*.md` or `externals/*.md` from git instead of running **generate-all-guidelines Phase 3** (Phase B + C + D per component).
+- Skip collection screenshot capture when collections are registered — Phase 1 must cover **both** components and collections for a complete visual record.
+
+After this, run Steps 1–4 in order (prerequisites → showcase mocks → field list → generate-all-guidelines).
+
+### Step 1 — Prerequisites
+
+Check all of these before starting:
+
+```bash
+# 1. Dev server is running
+curl -sL http://localhost:<PORT>/api/cms/discovery/ | head -c 100
+# Should return: {"components":[
+
+# 2. agent-browser is installed
+agent-browser --version
+# If missing: npm install -g agent-browser && agent-browser install
+
+# 3. Env vars present in <appDir>/.env.local
+grep -E "CONTENTFUL_SPACE_ID|CONTENTFUL_ACCESS_TOKEN|OPENAI_API_KEY|ANTHROPIC_API_KEY" <appDir>/.env.local
+```
+
+### Step 2 — Curate showcase mocks
+
+Read and follow the **curate-showcase-mocks** skill:
+`.agents/skills/se-marketing-sites-curate-showcase-mocks/SKILL.md`
+
+This produces `src/generated/showcase-mocks.json` (committed) and
+`src/generated/cms-discovery/accepted-variants/{components|collections|externals}/<slug>.json` (often gitignored — **some apps commit them**; follow the app’s `.gitignore`).
+
+When complete, confirm:
+- `src/generated/showcase-mocks.json` has non-empty `components` and `collections` keys
+- `src/generated/cms-discovery/accepted-variants/` has `components/` and `collections/` subdirs with JSON files
+
+Backfill any registered types missing from the LLM draft using `showcase-examples.json` (see curate skill), and add minimal `accepted-variants` JSON for types with no variant file so screenshot capture can run.
+
+### Step 3 — Generate HTML Component Style Guide
+
+Generate the design system reference used when authoring `HtmlComponent` entries:
+
+```bash
+# From the app directory:
+pnpm run cms-generate-html-style-guide
+# or from repo root:
+pnpm --filter <appName> exec cms-generate-html-style-guide --app-dir .
+```
+
+Reads `tailwind.config.json` and `src/app/globals.css`; writes `docs/cms-guidelines/html-component-style-guide.md`. No dev server required. Safe to skip if the design system has not changed since the last run.
+
+### Step 4 — Generate field list
+
+```bash
+# From the app directory:
+pnpm run cms-discovery:field-list
+# or from repo root:
+pnpm --filter <appName> exec cms-generate-field-list --app-dir .
+```
+
+Produces `generated/cms-discovery/field-list.json` (discovery API reads from this path). Some apps use `src/generated/` for showcase artifacts; see app docs.
+
+### Step 5 — Run generate-all-guidelines
+
+Read and follow the **generate-all-guidelines** skill:
+`.agents/skills/contentful-cms-generate-all-guidelines/SKILL.md`
+
+Skip its prerequisite check (you already verified everything through Step 4).
+Run Phases 0–5 from that skill with **full regeneration rules**:
+
+- **Phase 0** — Discover types; **do not** skip components that already had old fragments (there should be none after clean slate).
+- **Phase 1** — Bulk screenshot capture for **all components**, then **all collections** (and externals if your app captures them).
+- **Phase 2** — Collections + externals (`cms-generate-collection-guidelines`)
+- **Phase 3** — Component guidelines (**every** type: Phase B + C + D; **overwrite** `components/<slug>.md`)
+- **Phase 4** — Merge (`cms-merge-guidelines`)
+- **Phase 5** — Commit
+
+### After Phase 2 (externals)
+
+If any `docs/cms-guidelines/externals/<slug>.md` stubs were created, fill in their
+`## Fields & Schema` and `## Usage` sections before committing. See the
+**generate-cms-guidelines** skill (`Step 2b`) for guidance on what to put in these sections.
+
+---
+
+## Mode: sync
+
+Use when types have been added or removed in `registrations.ts` (or from the Contentful space).
+This mode diffs the current registered types against existing guideline files and handles both
+stale files and new types.
+
+**Incremental is not “append only”.** If a type left registrations or discovery, you **must** remove its artifacts (markdown, PNGs, index rows, optional `accepted-variants` files). Otherwise the repo and `COMPONENT_GUIDELINES_FOR_LLM.md` will lie.
+
+### Phase 0 — Diff
+
+Fetch the discovery endpoint and compute the current set of registered type slugs:
+
+```bash
+curl -sL http://localhost:<PORT>/api/cms/discovery/ > /tmp/discovery.json
+```
+
+Slug formula: `name.toLowerCase().replace(/\s+/g, '-').replace(/[()]/g, '')`
+
+Examples: `"Article Browser Sticky"` → `article-browser-sticky`, `"Two Column (Rich Text)"` → `two-column-rich-text`
+
+Build three diff lists by comparing discovery slugs against existing files:
+
+```bash
+# List existing guideline file slugs (strip .md extension)
+ls <appDir>/docs/cms-guidelines/components/  # → component file slugs
+ls <appDir>/docs/cms-guidelines/collections/ # → collection file slugs
+ls <appDir>/docs/cms-guidelines/externals/   # → external file slugs
+```
+
+From the diff, identify:
+
+| Status | Meaning | Action |
+|---|---|---|
+| **STALE** | File exists, type not in discovery | Remove files |
+| **NEW** | Type in discovery, no file exists | Generate guidelines |
+| **UNCHANGED** | Both exist | Skip |
+
+Report the full diff to the user before taking any action.
+
+### Phase 1 — Remove stale files
+
+For each **stale component** slug (`<slug>`):
+
+```bash
+# 1. Delete the guideline fragment
+rm <appDir>/docs/cms-guidelines/components/<slug>.md
+
+# 2. Delete all screenshot variants (screenshots live under components/ or collections/ subdirs)
+rm -f <appDir>/docs/cms-guidelines/screenshots/components/<slug>-*.png
+rm -f <appDir>/docs/cms-guidelines/screenshots/collections/<slug>-*.png
+
+# 3. Remove screenshot index entries for this type (index.json has typeName and file e.g. "components/<slug>-default.png")
+# Read screenshots/index.json, filter out entries where typeName matches or file starts with "components/<slug>-" or "collections/<slug>-", rewrite
+node -e "
+  const fs = require('node:fs');
+  const p = '<appDir>/docs/cms-guidelines/screenshots/index.json';
+  const idx = JSON.parse(fs.readFileSync(p, 'utf8'));
+  const filtered = idx.filter(e => !e.file.startsWith('components/<slug>-') && !e.file.startsWith('collections/<slug>-'));
+  fs.writeFileSync(p, JSON.stringify(filtered, null, 2));
+  console.log('Removed', idx.length - filtered.length, 'entries for <slug>');
+"
+
+# 4. Remove accepted-variants file if present (check both components/ and collections/)
+rm -f <appDir>/src/generated/cms-discovery/accepted-variants/components/<slug>.json
+rm -f <appDir>/src/generated/cms-discovery/accepted-variants/collections/<slug>.json
+```
+
+For each **stale collection** slug (`<slug>`):
+
+```bash
+# 1. Fragment
+rm <appDir>/docs/cms-guidelines/collections/<slug>.md
+
+# 2. Screenshots for that collection
+rm -f <appDir>/docs/cms-guidelines/screenshots/collections/<slug>-*.png
+
+# 3. Remove index entries (same pattern as components — filter by file prefix)
+# e.g. drop rows where e.file.startsWith('collections/<slug>-')
+```
+
+Use the same **index.json** filtering approach as for stale components (adjust the `startsWith` prefix to `collections/<slug>-`).
+
+For each **stale external** slug:
+
+> **Caution:** External guideline files contain hand-authored schema documentation. Confirm
+> with the user before deleting. If confirmed:
+
+```bash
+rm <appDir>/docs/cms-guidelines/externals/<slug>.md
+```
+
+### Phase 2 — Add new types
+
+**New components** (one or more):
+
+Run the [generate-all-guidelines](../generate-all-guidelines/SKILL.md) skill's Phase 1 (screenshots)
+and Phase 3 (component subagents) for **only the new types**, then skip to Phase 4 (merge).
+
+If the new component does not yet have an `accepted-variants/components/<slug>.json` file (or `collections/<slug>.json` for a collection), run:
+
+```bash
+pnpm --filter <appName> generate-showcase-mocks -- --types "<Type Name 1>,<Type Name 2>"
+```
+
+This regenerates the variant file for just those types. Then capture screenshots and run the
+Phase 3 subagent prompt as described in generate-all-guidelines.
+
+**New collections or externals:**
+
+Re-running the generator is safe — it always overwrites collections and only creates externals
+if the file does not already exist:
+
+```bash
+cms-generate-collection-guidelines \
+  --discovery-url http://localhost:<PORT>/api/cms/discovery/ \
+  --app-dir <appDir>
+```
+
+If a new external stub was created, fill in its `## Fields & Schema` and `## Usage` sections
+before committing (see Mode: fresh → After Phase 2).
+
+### Phase 3 — Merge and commit
+
+```bash
+# Rebuild the combined document
+cms-merge-guidelines --app-dir <appDir>
+# or: pnpm --filter <appName> run cms-guidelines:merge
+
+# Commit everything
+git add <appDir>/docs/cms-guidelines/ <appDir>/src/generated/cms-discovery/
+git commit -m "chore(<appName>): sync CMS guidelines with registrations"
+```
+
+---
+
+## Mode: merge-only
+
+Rebuilds `docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md` from all existing fragment files.
+Use after manual edits to fragment files, or after any of the other modes if the combined doc
+looks stale.
+
+```bash
+cms-merge-guidelines --app-dir <appDir>
+# or from the app directory:
+pnpm run cms-guidelines:merge
+```
+
+---
+
+## Output files (reference)
+
+All under `<appDir>`:
+
+| File | Description | Committed |
+|---|---|---|
+| `docs/cms-guidelines/components/<slug>.md` | Per-component fragment | Yes |
+| `docs/cms-guidelines/collections/<slug>.md` | Per-collection fragment | Yes |
+| `docs/cms-guidelines/externals/<slug>.md` | Per-external fragment | Yes |
+| `docs/cms-guidelines/screenshots/index.json` | Screenshot index | Yes |
+| `docs/cms-guidelines/screenshots/{components\|collections\|externals}/*.png` | Screenshot images | Yes |
+| `docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md` | Merged document (AI-readable) | Yes |
+| `generated/cms-discovery/field-list.json` | Field metadata (discovery API) | Yes |
+| `src/generated/showcase-mocks.json` | Curated showcase mocks | Yes |
+| `src/generated/cms-discovery/accepted-variants/{components\|collections\|externals}/<slug>.json` | Variant files (per type) | Usually no (app-dependent) |
+| `src/generated/showcase-examples.json` | Raw Contentful data dump | No |
+
+---
+
+## Sub-skills reference
+
+| Purpose | Skill |
+|---|---|
+| Curate showcase mocks (Step 2 of `fresh`) | `.agents/skills/se-marketing-sites-curate-showcase-mocks/SKILL.md` |
+| Full-site bulk generation (Step 4 of `fresh`: Phases 0–5) | `.agents/skills/contentful-cms-generate-all-guidelines/SKILL.md` |
+| Single-type regeneration (after code change) | `.agents/skills/contentful-cms-generate-cms-guidelines/SKILL.md` (mode: single) |
+| Per-component pipeline detail | `packages/skills/skills/contentful-cms-cms-guidelines/generate-component-guidelines.md` |

package/skills/performance-audit/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: performance-audit
+description: >
+  Measure and improve Next.js app performance: bundle analysis, Lighthouse,
+  and real-user monitoring. Generic — works with any Next.js deployment on Vercel.
+metadata:
+  author: se-core-product
+  version: "1.0.0"
+  priority: 5
+  promptSignals:
+    phrases:
+      - performance
+      - lighthouse
+      - bundle size
+      - bundle analysis
+      - LCP
+      - core web vitals
+      - CWV
+      - speed insights
+      - page speed
+      - slow pages
+      - optimize performance
+      - analyse bundle
+      - analyze bundle
+      - web vitals
+retrieval:
+  aliases:
+    - perf
+    - web vitals
+    - bundle
+    - lighthouse audit
+    - performance measurement
+  intents:
+    - measure page performance
+    - analyze bundle sizes
+    - improve Lighthouse scores
+    - set up performance tooling
+    - investigate slow LCP
+    - add speed insights
+    - run bundle analyzer
+  entities:
+    - LCP
+    - CLS
+    - TBT
+    - TTFB
+    - FCP
+    - bundle analyzer
+    - Lighthouse
+    - Speed Insights
+    - Core Web Vitals
+---
+
+# Next.js Performance Audit
+
+## Overview — Three-layer measurement strategy
+
+Always use all three layers. Bundle size ≠ Lighthouse score ≠ real-user experience.
+
+| Layer | Tool | What it measures | When to use |
+|---|---|---|---|
+| Bundle | `@next/bundle-analyzer` | JS/CSS weight by package, lazy vs eager chunks | Before/after any dependency or code change |
+| Lab | Lighthouse | CWV scores in controlled conditions | Before deploying an optimisation |
+| Field | Vercel Speed Insights | Real-user CWV on production | Ongoing monitoring post-deploy |
+
+---
+
+## Phase 1 — Bundle Analysis
+
+### Setup (if not already present)
+
+```bash
+pnpm add -D @next/bundle-analyzer
+```
+
+In `next.config.ts`, wrap the export:
+```ts
+import bundleAnalyzer from '@next/bundle-analyzer';
+const withBundleAnalyzer = bundleAnalyzer({ enabled: process.env.ANALYZE === 'true' });
+export default withBundleAnalyzer(nextConfig);
+```
+
+Add script to `package.json`:
+```json
+"analyze": "ANALYZE=true next build"
+```
+
+### Run
+
+```bash
+pnpm analyze
+```
+
+Opens `client.html`, `nodejs.html`, `edge.html` in `.next/analyze/`. The treemap shows every package in every chunk with parsed and gzip sizes.
+
+### What to look for
+
+**Good:**
+- Heavy libraries (video players, animation libraries, charting) appear as separate lazy chunks — they're only loaded when needed.
+
+**Investigate:**
+- Any package >30 KB gzip in the first-load chunks that isn't React or Next.js internals.
+- Libraries that should be server-only (e.g. CMS SDKs, data parsers) appearing in client bundles.
+- The same library duplicated across multiple chunks at different versions.
+
+**Node.js SSR bundle (`nodejs.html`):**
+Large client-only packages here inflate server cold-start time. Check for missing `'use client'` boundaries.
+
+---
+
+## Phase 2 — Lighthouse
+
+### Prerequisites
+
+| Node version | Lighthouse version |
+|---|---|
+| 20.18.x | `lighthouse@12` (`npm i -g lighthouse@12`) |
+| 20.19+ or 22+ | `lighthouse@13` |
+
+Chrome path:
+- Linux / WSL: `/usr/bin/google-chrome`
+- macOS: Lighthouse finds it automatically
+
+### Run against key page types
+
+Substitute `<SITE_URL>` with the production (or preview) domain.
+
+```bash
+mkdir -p .lighthouse
+
+# Homepage
+npx lighthouse@12 <SITE_URL>/ \
+  --chrome-path /usr/bin/google-chrome \
+  --chrome-flags="--headless=new --no-sandbox --disable-gpu --disable-dev-shm-usage" \
+  --only-categories=performance,accessibility,best-practices,seo \
+  --output json --output-path .lighthouse/home.json --quiet
+
+# A list or index page
+npx lighthouse@12 <SITE_URL>/blog/ \
+  --chrome-path /usr/bin/google-chrome \
+  --chrome-flags="--headless=new --no-sandbox --disable-gpu --disable-dev-shm-usage" \
+  --only-categories=performance,accessibility,best-practices,seo \
+  --output json --output-path .lighthouse/list.json --quiet
+
+# A detail page (pick a URL from the sitemap)
+npx lighthouse@12 <DETAIL_URL> \
+  --chrome-path /usr/bin/google-chrome \
+  --chrome-flags="--headless=new --no-sandbox --disable-gpu --disable-dev-shm-usage" \
+  --only-categories=performance,accessibility,best-practices,seo \
+  --output json --output-path .lighthouse/detail.json --quiet
+```
+
+To find page URLs: `curl -s <SITE_URL>/sitemap.xml | grep -oP 'https://[^<]+'`
+
+### Extract scores from JSON
+
+```bash
+node -e "
+const pages = ['home','list','detail'];
+pages.forEach(p => {
+  try {
+    const d = JSON.parse(require('fs').readFileSync('.lighthouse/' + p + '.json', 'utf8'));
+    const c = d.categories;
+    const a = d.audits;
+    console.log(p.padEnd(10),
+      'Perf:', Math.round(c.performance.score * 100),
+      '| LCP:', (a['largest-contentful-paint'].numericValue / 1000).toFixed(2) + 's',
+      '| CLS:', a['cumulative-layout-shift'].numericValue.toFixed(3),
+      '| TBT:', Math.round(a['total-blocking-time'].numericValue) + 'ms',
+      '| TTFB:', Math.round(a['server-response-time'].numericValue) + 'ms'
+    );
+  } catch(e) { console.log(p + ': not found'); }
+});
+"
+```
+
+### Targets
+
+| Metric | Target | Fail threshold |
+|---|---|---|
+| LCP | < 2.5s | > 4s |
+| CLS | < 0.1 | > 0.25 |
+| TBT | < 200ms | > 600ms |
+| TTFB | < 600ms | > 1800ms |
+| FCP | < 1.8s | > 3s |
+
+### Key diagnostic signal
+
+If a simple page (e.g. About) scores 90+ but heavier pages score < 80, the delta is almost always media loading or third-party scripts present only on those pages.
+
+If all pages score similarly low, the issue is in the shared layout — fonts, analytics scripts, or global CSS.
+
+### Extracting opportunities
+
+```bash
+node -e "
+const d = JSON.parse(require('fs').readFileSync('.lighthouse/home.json', 'utf8'));
+const a = d.audits;
+
+console.log('=== LARGEST PAYLOADS ===');
+(a['total-byte-weight']?.details?.items || []).slice(0, 8).forEach(i =>
+  console.log('  ' + ((i.totalBytes||0)/1024).toFixed(0).padStart(6) + 'KB | ' + (i.url||'').substring(0,90))
+);
+
+console.log('\n=== UNUSED JS ===');
+(a['unused-javascript']?.details?.items || []).slice(0, 6).forEach(i =>
+  console.log('  ' + ((i.wastedBytes||0)/1024).toFixed(0).padStart(6) + 'KB | ' + (i.url||'').substring(0,90))
+);
+
+console.log('\n=== RENDER BLOCKING ===');
+(a['render-blocking-resources']?.details?.items || []).forEach(i =>
+  console.log('  ' + Math.round(i.wastedMs||0) + 'ms | ' + (i.url||'').substring(0,90))
+);
+"
+```
+
+---
+
+## Phase 3 — Real-User Monitoring (Speed Insights)
+
+### Setup
+
+```bash
+pnpm add @vercel/speed-insights
+```
+
+Add to the **root layout** (`src/app/layout.tsx`) — must be root, not a route group layout:
+```tsx
+import { SpeedInsights } from '@vercel/speed-insights/next';
+
+// Inside <body>:
+<SpeedInsights />
+```
+
+Deploy to production. View in **Vercel dashboard → Speed Insights**.
+
+Data appears within minutes of the first production visit. Field data reflects real network conditions and will differ from Lighthouse's simulated throttling.
+
+---
+
+## Common Fixes
+
+### Fix 1: Heavy libraries loading on every page
+
+**Symptom**: Lighthouse flags large unused JS. Bundle analyzer shows a library in first-load chunks but it's only used on specific pages/routes.
+
+**Fix** — Use dynamic import with `next/dynamic` or native `import()` inside `useEffect`:
+```tsx
+// next/dynamic (renders a component lazily)
+import dynamic from 'next/dynamic';
+const HeavyComponent = dynamic(() => import('./HeavyComponent'), { ssr: false });
+
+// Conditional import in useEffect (for web components / side-effect-only libraries)
+useEffect(() => {
+  if (document.querySelector('my-web-component')) {
+    import('my-web-component-library');
+  }
+}, []);
+```
+
+---
+
+### Fix 2: Render-blocking third-party scripts
+
+**Symptom**: GTM, consent scripts, or analytics tags appear in the Lighthouse render-blocking or TBT audits.
+
+**Fix** — Use Next.js `<Script>` with appropriate strategy. Requires `'use client'`:
+```tsx
+'use client';
+import Script from 'next/script';
+
+// Load after page becomes interactive (GTM, analytics)
+<Script src="https://www.googletagmanager.com/gtm.js?id=..." strategy="afterInteractive" />
+
+// Load during browser idle time (consent banners, low-priority widgets)
+<Script src="https://cdn.example.com/widget.js" strategy="lazyOnload" />
+```
+
+---
+
+### Fix 3: Legacy JS polyfills inflating bundle
+
+**Symptom**: Lighthouse legacy-JavaScript audit flags `Array.prototype.at`, `.flat`, `.flatMap` being polyfilled.
+
+**Fix** — Create `.browserslistrc` at the project root:
+```
+last 2 Chrome versions
+last 2 Firefox versions
+last 2 Safari versions
+last 2 Edge versions
+not dead
+```
+
+Verify audience browser share before applying — check analytics for any legacy traffic.
+
+---
+
+### Fix 4: Visuals without dimensions causing CLS
+
+**Symptom**: CLS > 0.1. Lighthouse "Avoid large layout shifts" audit lists image or media elements.
+
+**Fix** — Always set explicit `width` and `height` on `<img>` and `<video>` elements, or use `aspect-ratio` CSS on their container so the browser can reserve space before the asset loads:
+```tsx
+<div style={{ aspectRatio: '16 / 9' }}>
+  <video ... />
+</div>
+```
+
+---
+
+## Tracking baselines
+
+Save Lighthouse JSON to `.lighthouse/<page>.json`. After each round of fixes, save to `.lighthouse/<page>-v2.json`, `v3.json`, etc.
+
+Compare LCP across versions:
+```bash
+node -e "
+const v1 = JSON.parse(require('fs').readFileSync('.lighthouse/home.json','utf8'));
+const v2 = JSON.parse(require('fs').readFileSync('.lighthouse/home-v2.json','utf8'));
+const lcp = a => (a.audits['largest-contentful-paint'].numericValue/1000).toFixed(2)+'s';
+const perf = a => Math.round(a.categories.performance.score * 100);
+console.log('Home LCP: v1=' + lcp(v1) + ' → v2=' + lcp(v2));
+console.log('Home Perf: v1=' + perf(v1) + ' → v2=' + perf(v2));
+"
+```
+
+Commit `.lighthouse/` to git for team-visible historical baselines.
+
+---
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|---|---|---|
+| `Unable to connect to Chrome` | Lighthouse can't find Chrome binary | Add `--chrome-path /usr/bin/google-chrome` |
+| Lighthouse fails on Node 20.18.x | Requires lighthouse@12 | Use `npm i -g lighthouse@12` |
+| `ANALYZE=true next build` fails | `next.config.ts` export not wrapped | Ensure `export default withBundleAnalyzer(nextConfig)` |
+| Speed Insights shows no data | Wrong layout, or not deployed to production | Must be in root `src/app/layout.tsx`; requires production traffic |
+| Lighthouse score varies between runs | CPU/network simulation variability | Run 3× and average; use `--throttling-method=provided` for stable local results |
+
+---
+
+## See also
+
+- **SE Studio stack**: if the project uses `@se-studio/core-ui`, Contentful CMS, or ImageKit, see the SE-Studio-specific performance-audit skill for additional fixes (lazy video/animation loading, variable font subsetting, lottie-player optimisation).