diff --git a/apps/www/wrangler.jsonc b/apps/www/wrangler.jsonc
index 4add233..75a00ce 100644
--- a/apps/www/wrangler.jsonc
+++ b/apps/www/wrangler.jsonc
@@ -8,9 +8,21 @@
 	// React SPA client build (Vite emits it to dist/www/client). Static assets are
 	// served directly; any non-asset request falls through to the Worker, which
 	// serves API routes and returns index.html for client-side routes (SPA).
+	//
+	// `run_worker_first` (an ARRAY) is an EXCLUSIVE allowlist: it replaces the default
+	// routing entirely, so the Worker runs ONLY for the listed patterns and every other
+	// path is served assets-first (with the SPA fallback → index.html). It must therefore
+	// list EVERY route the Worker handles, not just the new ones — otherwise `/api/*`
+	// falls through to index.html and the whole BFF breaks. Why it's needed at all: with
+	// SPA `not_found_handling`, a top-level *navigation* to a non-asset path (browsers
+	// send `Sec-Fetch-Mode: navigate`) is served index.html WITHOUT invoking the Worker,
+	// so a browser hitting `/docs` got the homepage. Keep this in sync with the Worker's
+	// routes (all under `/api/*` and `/docs*`). `/docs/scalar.standalone.js` is
+	// deliberately excluded so it's served directly as the static asset it is.
 	"assets": {
 		"binding": "ASSETS",
-		"not_found_handling": "single-page-application"
+		"not_found_handling": "single-page-application",
+		"run_worker_first": ["/api/*", "/docs", "/docs/openapi/*"]
 	},
 	"upload_source_maps": true,
 	"observability": {