docs: refresh AGENTS.md, HANDOFF.md, and README with recent work

- Create AGENTS.md: comprehensive agent guide covering architecture,
  data flow, error bar convention (90% intervals), D3 usage patterns,
  null safety pitfalls, deployment checklist, and related repos
- Update HANDOFF.md: mark CORS as resolved, document chart improvements
  (Chart 5 ridgeline rewrite with synthetic draws + smooth rendering)
- Refresh README.md: accurate tech stack (D3 v7), updated file structure
  with new chart files, corrected API endpoint table

HANDOFF.md

@@ -1,25 +1,40 @@
 # Handoff: Fix CORS for CRDC Arrests API Demo App
 
 ## Current Status
-The demo app at `https://pages.civilytics.org/crdc-demo/` loads HTML correctly but shows a blank white screen because browser-based fetch requests to the CRDC API are blocked by CORS (the API doesn't send `Access-Control-Allow-Origin` headers).
+**RESOLVED**: The demo app at `https://pages.civilytics.org/crdc-demo/` is fully functional. All charts render correctly and there are no blocking errors in the console.
 
-## What's Done
-1. ✅ **App code**: React + Vite app fully built with 6 charts, Civilytics visual identity, loading animation, district search — all committed and building cleanly
-2. ✅ **Git Pages deployment**: Gitea Actions workflow (`.gitea/workflows/pages.yml`) successfully builds `dist/` and deploys to a `pages` branch on `Civilytics/crdc-demo` repo at gitea.civilytics.org
-3. ✅ **CORS proxy code added**: 
-   - Updated `src/hooks/useApi.js`, `LoadingAnimation.jsx`, `ChartPanel.jsx` with `VITE_PROXY_URL` support (routes through a query-param-based proxy)
-   - Added `proxy.php` — simple PHP CORS proxy for git-pages hosts that support PHP
-   - Updated Dockerfile nginx.conf to include `/api/v1/` reverse proxy with CORS headers
+The original CORS issue was resolved by deploying updated `plumber.R` with CORS headers to the running API server (`crdc-api.civilytics.org`).
+
+## Historical Context (resolved)
+
+### Original Problem
+The demo app loaded HTML correctly but showed a blank white screen because browser-based fetch requests to the CRDC API were blocked by CORS (the API didn't send `Access-Control-Allow-Origin` headers).
+
+### Resolution
+The CORS issue was fixed at the API source:
+- Updated `crdc-arrests/api/plumber.R` with CORS headers (`Access-Control-Allow-Origin: *`) in the existing `cacheHeaders` filter and OPTIONS preflight handling.
+- Deployed to the running API server so it took effect at https://crdc-api.civilytics.org/.
+
+The app now calls the public read-only API directly from the browser without requiring a proxy.
+
+## Current Work (completed)
+
+Since resolving CORS, additional improvements were made:
+### What's Done
+1. ✅ **CORS resolved**: API server (`crdc-api.civilytics.org`) now sends `Access-Control-Allow-Origin: *` headers — deployed via updated `plumber.R`
+2. ✅ **App code**: React + Vite app fully built with 6 charts, Civilytics visual identity (wordmark from civilyticsR package), loading animation, district search
+3. ✅ **Git Pages deployment**: Gitea Actions workflow (`.gitea/workflows/pages.yml`) successfully builds `dist/` and deploys to a `pages` branch on `Civilytics/crdc-demo` repo at gitea.civilytics.org
+4. ✅ **Chart 5 rewrite**: Replaced interval-proxy ridgeline with proper D3 density ridges (`RateDensityRidgeline.jsx`) using synthetic draws from normal approximation of posterior intervals, smooth `curveBasis` rendering, and diamond markers for observed rates
+5. ✅ **Chart 4 enhancement**: Added D3-based quadrant visualization in `ModelDrawsComparison.jsx` showing error bars with proper null safety
+
+### Remaining Proxy Code (optional)
+The CORS proxy fallback code (`proxy.php`, nginx reverse proxy config, `VITE_PROXY_URL` support) was added but is **not needed** since the API now sends CORS headers. It remains as a safety net for environments where the API can't be modified.
 
 ## What Needs to Be Done Next
 
-### Option A: Fix at the API source (recommended, cleanest)
-The CRDC API is a Plumber/R service deployed behind Cloudflare. The code change has already been made in `crdc-arrests/api/plumber.R` — added CORS headers (`Access-Control-Allow-Origin: *`) to the existing `cacheHeaders` filter and OPTIONS preflight handling.
-
-**Action needed**: Deploy this updated plumber.R to the running API server so it takes effect at https://crdc-api.civilytics.org/. The change is in `/home/jared/Nextcloud/Civilytics/Code/Civilytics/crdc-arrests/api/plumber.R` (lines 56-78).
-
-### Option B: Fix on the git-pages server
-If you can't restart the API, configure the nginx serving `pages.civilytics.org` to add CORS headers when proxying requests to `crdc-api.civilytics.org`. Or deploy `proxy.php` and set `VITE_PROXY_URL=/crdc-demo/proxy.php` at build time.
+### Future Enhancements
+- **Raw posterior draws**: The `/api/v1/draws?...` endpoint returns Parquet shard URLs for bulk processing, not browser-friendly draw data. If actual posterior distributions are needed in Chart 5 (instead of synthetic normal approximation), a new API endpoint would be required.
+- **Automated testing**: No test suite exists; consider adding basic tests for chart rendering and API error handling.
 
 ## Key Files
 - **API fix**: `/home/jared/Nextcloud/Civilytics/Code/Civilytics/crdc-arrests/api/plumber.R` (CORS headers added to cacheHeaders filter)