docs: reflect real posterior-draw architecture in AGENTS/README/HANDOFF

- AGENTS.md: Replace §4 (API Endpoint Availability) with updated text; insert
  new §5 (Real posterior draws via duckdb-wasm) documenting the shift from
  synthetic normal-approximation draws to client-side fetches via duckdb-wasm
  against the public Hugging Face parquet dataset. Include actual payload size
  (~39MB uncompressed / ~8.86MB gzipped). Renumber subsequent items.
- README.md: Update Chart 5 description in "What It Does" to reflect real draws
  + fallback behavior. Update API table to clarify that /api/v1/draws is not
  called from app but informs the Hugging Face URL the app fetches directly.
- HANDOFF.md: Mark "Raw posterior draws" as done (2026-08-11) with reference
  to the design spec.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

AGENTS.md

@@ -83,11 +83,26 @@ Charts use fixed dimensions with responsive containers (`overflowX: 'auto'` for
 
 Not all endpoints are available to browser-based clients:
 - `/api/v1/estimates/{leaid}` — ✅ Returns estimates summary (median, lower, upper bounds)
-- `/api/v1/draws?...` — ❌ Returns Parquet shard URL only; meant for bulk processing via DuckDB, **not** usable from the browser
+- `/api/v1/draws?...` — Returns a Parquet shard URL + DuckDB SQL, not draw data itself. The app **does** use the real draws in the shard it points to — see below.
 
-If you need raw posterior draws in the browser app, a new API endpoint would be required. Currently, Chart 5 generates synthetic draws using normal approximation (`d3.randomNormal`) based on the interval bounds.
+### 5. Real posterior draws via duckdb-wasm
 
-### 5. CORS Configuration
+Charts 2 (`RateByGroupBar`) and 3 (`RateDensityRidgeline`) fetch the actual
+500-draw-per-group posterior from the public Hugging Face parquet dataset
+(`civilytics/crdc-school-arrest-rates`), queried client-side with
+`@duckdb/duckdb-wasm` (`src/utils/duckdbClient.js` +
+`src/hooks/useDrawDistribution.js`). No server-side draws endpoint is
+involved. If that fetch fails (network, unsupported browser, HF outage),
+both charts fall back to the `distributionApprox.js` analytic approximation
+and show the "estimated shape" note — **do not delete `distributionApprox.js`
+or `ApproxNote.jsx`**, they're the fallback path, not dead code.
+
+See `docs/superpowers/specs/2026-08-11-empirical-draws-wasm-design.md` for
+the full design.
+
+The duckdb-wasm engine itself is ~39MB uncompressed / ~8.86MB gzipped (confirmed against the shipped `@duckdb/duckdb-wasm` package, not the design spec's original ~3-5MB estimate, which was wrong). It's loaded via dynamic `import()` only once a district is selected — never on initial page load — and cached by the browser thereafter, but it's a real one-time cost worth knowing about before touching this code path.
+
+### 6. CORS Configuration
 
 The CRDC API does not send CORS headers. When deployed to git-pages (static hosting), requests are blocked by same-origin policy unless a proxy is configured:
 - The app auto-detects proxy availability via `VITE_PROXY_URL` environment variable