From ace4ab0acba38f730aef52094380fface5703bda Mon Sep 17 00:00:00 2001
From: "devin-ai-integration[bot]"
 <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Thu, 30 Apr 2026 16:00:49 +0000
Subject: [PATCH] Update lighthouse testing skill with API Worker testing
 guidance

Co-authored-by: Anthony Jones <anthony@designedbyanthony.com>
---
 .agents/skills/testing-lighthouse/SKILL.md | 44 ++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/.agents/skills/testing-lighthouse/SKILL.md b/.agents/skills/testing-lighthouse/SKILL.md
index 529f7169..2c7c99dd 100644
--- a/.agents/skills/testing-lighthouse/SKILL.md
+++ b/.agents/skills/testing-lighthouse/SKILL.md
@@ -9,6 +9,49 @@ The Lighthouse Scanner lives at `/lighthouse` in the Next.js app (`apps/web`). I
 - **Cloudflare Pages preview**: Every PR gets a preview deploy. Check the PR comments from `cloudflare-workers-and-pages[bot]` for the preview URL (format: `https://<hash>.dba-92r.pages.dev`).
 - **Production**: `https://designedbyanthony.com/lighthouse`
 
+## Important: Pages vs Worker Deployment
+
+This repo has **two separate deploy targets**:
+- **Cloudflare Pages** (`apps/web`) — deploys automatically via PR/merge CI
+- **Cloudflare Worker** (`apps/api`) — deploys separately via `wrangler deploy` from `apps/api/`
+
+Cloudflare Pages preview URLs only include frontend changes. **API Worker changes (routes in `apps/api/src/routes/`) are NOT included in Pages previews.** To test API changes, use local `wrangler dev` (see below) or wait for a separate Worker deployment.
+
+## Testing API Routes Locally
+
+To test API Worker routes (e.g., `/api/report/:id/pdf`, `/api/audit`, `/api/audit/email-summary`):
+
+1. **Start the API locally:**
+   ```bash
+   cd apps/api && npx wrangler dev --local
+   ```
+   This starts the Worker on `http://localhost:8788` with local KV.
+
+2. **Seed test data into local KV** (needed for endpoints that read from the report store):
+   ```bash
+   cd apps/api && npx wrangler kv key put "DBA-TEST1234" \
+     --binding AUDIT_REPORTS_KV --local \
+     "$(cat /path/to/test-report.json)"
+   ```
+   The test report JSON must match the full stored payload structure from `audit.ts` — including nested `sitewide.robotsTxt.exists`, `sitewide.sitemap.exists`, `backlinks.found`, `places.found`, `indexCoverage.found` fields. Empty objects (`{}`) for these fields will cause `buildAuditPdf` to crash with "Cannot read properties of undefined".
+
+3. **Verify with curl:**
+   ```bash
+   # Health check
+   curl -s http://localhost:8788/health
+
+   # Test PDF headers
+   curl -sD - http://localhost:8788/api/report/DBA-TEST1234/pdf -o /tmp/test.pdf
+
+   # Test CORS preflight
+   curl -sD - -X OPTIONS http://localhost:8788/api/audit/email-summary \
+     -H "Origin: https://designedbyanthony.com" -o /dev/null
+   ```
+
+## Elysia Response Pattern
+
+When testing Elysia routes that return raw `Response` objects: in Elysia, `set.headers` is ignored when returning a raw `Response`. Headers must be passed via the `Response` constructor. If you see missing headers on a raw Response return, check for this pattern mismatch. Routes that return plain objects (JSON) can use `set.headers` normally.
+
 ## Key Visual Elements to Verify
 
 When testing Lighthouse UI changes, compare against the main site homepage (`/`) for consistency:
@@ -33,6 +76,7 @@ When testing Lighthouse UI changes, compare against the main site homepage (`/`)
 - **CSS class name mismatches**: When refactoring CSS class names, always check that components still reference the correct names. Use `grep -oP 'className="[^"]*lh-[^"]*"' <component>.tsx | grep -oP 'lh-[a-z0-9_-]+'` to extract class names from components and verify they exist in the CSS file.
 - **Local dev 500 errors**: The homepage might 500 locally due to missing env vars, but `/lighthouse` usually works. Use the Cloudflare Pages preview URL as a reliable alternative.
 - **Bronze is intentional in some places**: The submit button CTA and decorative accent rules intentionally keep bronze — don't flag these as bugs.
+- **Empty nested objects in test data**: When seeding test reports for PDF generation, ensure all nested objects (`sitewide`, `backlinks`, `places`, `indexCoverage`) have their full expected structure. `buildAuditPdf` accesses nested properties like `sitewide.robotsTxt.exists` and will crash on empty objects.
 
 ## Devin Secrets Needed