Add project overview, integrations, and dev commands to CLAUDE.md

.claude/CLAUDE.md

@@ -1,5 +1,61 @@
 # michaeluloth.com - Claude Code Rules
 
+## What this project is
+
+A personal blog and portfolio site built with Next.js, deployed to Cloudflare Pages (not Vercel). Content is authored in Notion and pulled at build time via the Notion API. The architecture treats the data pipeline like a production system: Zod validates every external API response at the boundary, errors are values (Rust-style `Result<T, E>`), and all external calls use exponential backoff retry.
+
+## External integrations
+
+| Integration | Role                                                        |
+| ----------- | ----------------------------------------------------------- |
+| Notion      | CMS — albums, books, podcasts, writing                      |
+| Cloudinary  | Image CDN — responsive srcsets, format/quality optimization |
+| TMDB        | Film metadata (movie and TV list data)                      |
+| iTunes      | Podcast metadata                                            |
+
+## Local development
+
+```bash
+npm run dev   # starts dev server at http://localhost:3000
+```
+
+On first run, each page fetch hits the real external APIs and caches the results under `.local-cache/` by namespace. Subsequent requests are served from that persistent on-disk cache until `.local-cache/` is manually cleared. The directory is created automatically on first write — no manual setup needed.
+
+Required env vars (copy `.env.example` to `.env.local` and fill in):
+
+- `NOTION_ACCESS_TOKEN`, `NOTION_DATA_SOURCE_ID_*` (albums, books, podcasts, writing)
+- `CLOUDINARY_CLOUD_NAME`, `CLOUDINARY_API_KEY`, `CLOUDINARY_API_SECRET`
+- `TMDB_READ_ACCESS_TOKEN`, `TMDB_MOVIE_LIST_ID`, `TMDB_TV_LIST_ID`
+- `PUSHOVER_API_TOKEN`, `PUSHOVER_USER_KEY`
+
+CI/deploy only (not needed for local dev):
+
+- `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_API_TOKEN`
+
+## Check commands
+
+```bash
+npm run lint        # ESLint
+npm run typecheck   # TypeScript
+npm run test:ci     # Vitest (all tests, no watch)
+```
+
+Run these before committing. To run a single test file: `npm run test:ci -- path/to/file.test.ts`.
+
+## Post-build metadata validation
+
+```bash
+npm run build && npm run test:metadata
+```
+
+`test:metadata` reads the static HTML from the `out/` build directory and validates OpenGraph tags, image dimensions, alt text, and SEO fields. It must run **after** `npm run build` — running it against a stale or missing build will produce false results.
+
+## Deployment
+
+The site deploys to **Cloudflare Pages** via GitHub Actions. Do not add Vercel config or assume Vercel-specific behaviour (e.g. `vercel.json`, edge runtime defaults).
+
+---
+
 ## TypeScript Type Safety
 
 ### Never use `any`

.github/workflows/ci.yml

@@ -33,7 +33,7 @@ jobs:
           node-version-file: '.nvmrc'
           cache: 'npm'
       - run: npm ci
-      - run: npx prettier --check .
+      - run: npm run format:check
 
   lint:
     name: Linting

.prettierignore

@@ -1,2 +1,5 @@
 # Ignore Claude Code Review workflow to prevent breaking security validation
 .github/workflows/claude-code-review.yml
+
+# Generated by npm; npm 11 modifies this during `npm ci` before the format check runs
+package-lock.json

package.json

@@ -15,6 +15,7 @@
     "deploy:production": "bash io/cloudflare/deploy-production-check.sh && npm run build && npx wrangler pages deploy out --project-name=michaeluloth --branch=main",
     "dev": "next dev",
     "format": "prettier --write .",
+    "format:check": "prettier --check .",
     "generate:og-image": "tsx seo/generate-og-image.tsx",
     "lighthouse": "lhci autorun || (tsx ci/lighthouse/parse-errors.ts && exit 1)",
     "prelighthouse": "tsx ci/lighthouse/generate-urls.ts",
@@ -56,7 +57,7 @@
     "eslint-config-next": "16.0.1",
     "eslint-config-prettier": "^10.1.8",
     "happy-dom": "^20.0.11",
-    "prettier": "^3.6.2",
+    "prettier": "^3.8.3",
     "satori": "^0.18.3",
     "sharp": "^0.34.5",
     "shiki": "^3.15.0",