## Context

Chrome Lighthouse runs against `https://santhoshj.com/` (desktop + mobile) report several audits that prevent a 100 score.

Inputs:
- Desktop report: `C:\Users\simpl\Downloads\santhoshj.com-20260210T182644.json`
- Mobile report: `C:\Users\simpl\Downloads\santhoshj.com-20260210T182538.json`

Key failing audits (non-exhaustive):
- Accessibility: `color-contrast`
- SEO: `robots-txt`, `crawlable-anchors`
- Best Practices: `inspector-issues` (Content Security Policy)
- Performance: `render-blocking-insight`, `image-delivery-insight`, `unminified-css`, `unused-css-rules`, `unused-javascript`, `cache-insight` (plus mobile LCP/TTI pressure)

Constraints:
- Site is a static Astro build served behind Docker Compose + reverse proxy.
- Some assets are third-party (YouTube thumbnails, CloudFront podcast images, Umami script). These can influence some performance/cache audits and must be handled carefully (reduce impact where possible, but avoid breaking content).
- Service worker script MUST remain at stable URL `/sw.js` and should not be versioned via query string.

## Goals / Non-Goals

**Goals:**
- Achieve a 100 Lighthouse rating on the homepage in all categories (Performance, Accessibility, Best Practices, SEO) using the audits provided.
- Make contrast compliant (WCAG AA) for secondary text and pill/chip labels.
- Ensure SEO hygiene:
  - `robots.txt` includes a valid (absolute) sitemap URL
  - interactive elements do not render anchor tags without `href`.
- Remove DevTools Issues panel findings related to CSP by implementing an explicit CSP baseline that matches site needs.
- Reduce render-blocking requests and improve asset delivery so mobile LCP/TTI is consistently fast.

**Non-Goals:**
- Redesigning the site's visual identity or typography scale.
- Removing all third-party content sources (YouTube thumbnails, podcast cover images) or analytics.
- Building a full PWA manifest/offline-first experience (out of scope).

## Decisions

1. **Contrast remediation via token-level CSS adjustments**
Rationale: Lighthouse flags specific selectors in card footers and pills. Fixing contrast at the token level (e.g., `--muted`, pill bg/fg) avoids per-component overrides and reduces regressions.
Alternatives:
- Component-local overrides (harder to maintain, easy to miss).

2. **Robots sitemap MUST be absolute**
Rationale: Lighthouse treats `Sitemap: /sitemap-index.xml` as invalid. Robots will be updated to point at the full absolute URL.
Alternatives:
- Switch to `sitemap.xml` only (not desired; site already emits sitemap-index).

3. **No anchor elements without href in rendered HTML**
Rationale: Lighthouse flags the media modal anchors because they exist at load time without `href` (populated later by JS). Fix by using buttons for non-navigational actions, and ensuring any `<a>` is rendered with a valid `href` in initial HTML (or not rendered until it has one).
Alternatives:
- Keep anchors and set `href="#"` (still crawlable but semantically wrong, and can degrade UX).

4. **CSP baseline implemented at the edge (reverse proxy), compatible with site JS**
Rationale: DevTools Issues panel reports CSP issues. Implement a CSP that matches current needs (site inline scripts, Umami, fonts, images, frames) and remove/avoid inline scripts where possible to keep CSP strict.
Alternatives:
- Avoid CSP entirely (does not resolve audit and leaves security posture ambiguous).

5. **Font delivery: prefer self-hosting to remove render-blocking third-party CSS**
Rationale: Lighthouse render-blocking points to Google Fonts stylesheet. Self-hosting WOFF2 and using `@font-face` reduces blocking and improves reliability.
Alternatives:
- Keep Google Fonts and rely on preload hints (still incurs third-party CSS request; harder to reach 100).

6. **CSS delivery: move global CSS into the build pipeline (minified output)**
Rationale: Lighthouse flags unminified/unused CSS. Keeping `global.css` as a raw file in `public/` makes it harder to guarantee minification/unused pruning. Prefer having Astro/Vite handle minification and (where possible) pruning.
Alternatives:
- Add a bespoke minify step for `public/styles/global.css` (works, but adds build complexity and can drift).

7. **Caching headers: stable URLs get revalidated; fingerprinted assets get long-lived caching**
Rationale: Lighthouse cache-lifetime audit penalizes short cache lifetimes on first-party CSS/JS. For assets that are not fingerprinted (e.g., `/sw.js`, possibly `/styles/global.css`), use `no-cache` or revalidation to avoid staleness. For fingerprinted build outputs, use long-lived caching.
Alternatives:
- Querystring versioning on SW (known pitfall; can break update chain).

## Risks / Trade-offs

- **[CSP breaks site behavior]** → Start with Report-Only CSP, verify in production, then enforce. Prefer eliminating inline scripts to avoid `unsafe-inline`.
- **[Self-hosting fonts changes appearance slightly]** → Keep the same Manrope font files and weights, verify typography visually.
- **[Optimizing images reduces perceived sharpness]** → Use responsive images and appropriate sizes; keep high-DPR support via srcset.
- **[Third-party cache lifetimes cannot be controlled]** → Focus on first-party cache headers and reduce critical path reliance on third-party where possible.

## Migration Plan

1. Reproduce Lighthouse findings from a clean Chrome profile (no extensions) for both mobile/desktop.
2. Apply fixes in small slices (contrast, robots/anchors, CSP, fonts, CSS pipeline/minify, image delivery).
3. Deploy behind the reverse proxy with Report-Only CSP first.
4. Re-run Lighthouse on production URL until 100 is reached and stable.
5. Enable enforced CSP after confirming no violations.

## Open Questions

- What exact CSP issue is being reported in the DevTools Issues panel (violation message)? Lighthouse only surfaces the issue type without sub-items.
- Do we want to keep Google Fonts or commit to self-hosting fonts for maximum Lighthouse consistency?
- For cache-lifetime scoring: do we want to introduce fingerprinted CSS output (preferred) or add explicit versioning for `/styles/global.css`?