diff --git a/apps/docs/src/pages/404.astro b/apps/docs/src/pages/404.astro
new file mode 100644
index 00000000..f827c3be
--- /dev/null
+++ b/apps/docs/src/pages/404.astro
@@ -0,0 +1,23 @@
+---
+import BaseLayout from "~/layouts/BaseLayout.astro";
+---
+
+<BaseLayout title="Page not found" description="The page you're looking for doesn't exist.">
+  <main
+    class="mx-auto flex min-h-screen max-w-3xl flex-col items-center justify-center gap-6 px-6 py-16 text-center"
+  >
+    <div>
+      <p class="text-sm font-medium text-secondary">404</p>
+      <h1 class="mt-2 text-3xl font-semibold text-primary">Page not found</h1>
+      <p class="mt-3 text-lg text-secondary">
+        The page you're looking for doesn't exist or has moved.
+      </p>
+    </div>
+    <a
+      href="/"
+      class="rounded-md bg-accent-primary px-4 py-2 text-sm font-medium text-on-color"
+    >
+      Back to home
+    </a>
+  </main>
+</BaseLayout>
diff --git a/apps/docs/wrangler.jsonc b/apps/docs/wrangler.jsonc
index 480a4c86..cc2b11bf 100644
--- a/apps/docs/wrangler.jsonc
+++ b/apps/docs/wrangler.jsonc
@@ -1,10 +1,33 @@
 {
   "$schema": "./node_modules/wrangler/config-schema.json",
-  "name": "docs",
-  // TODO: set account_id and a real routes/zone entry before deploying.
+  // The docs site is deployed as a static site on Cloudflare Workers (Static Assets).
+  // No Worker script is needed — `assets.directory` alone serves the built output.
+  // Deployment is driven by Cloudflare's Git integration (Workers Builds connected to the
+  // GitHub repo), which builds on push and reads this config; the account is the connected
+  // Cloudflare account, so no `account_id` belongs in this file.
+  // https://developers.cloudflare.com/workers/static-assets/
+  // https://developers.cloudflare.com/workers/ci-cd/builds/
+  // Worker name mirrors the `propel-storybook` sibling (packages/propel/wrangler.jsonc);
+  // Cloudflare Worker names are account-global, so keep the `propel-` prefix even though
+  // the workspace package is just `docs`.
+  "name": "propel-docs",
   "compatibility_date": "2026-07-15",
+  // Serve on the account's workers.dev subdomain and enable per-version preview URLs, so
+  // Workers Builds gives every non-production branch/PR build its own preview URL.
+  "workers_dev": true,
+  "preview_urls": true,
+  // TODO: once a production domain is assigned, add a custom-domain route here and set
+  // `site` in astro.config.mjs to match (so the sitemap emits absolute URLs). Mirror
+  // packages/propel/wrangler.jsonc's storybook route, e.g.:
+  //   "routes": [{ "pattern": "propel.plane.so", "custom_domain": true }]
+  // Keep `workers_dev`/`preview_urls` enabled even then: the PR preview URLs live on the
+  // workers.dev subdomain, so disabling them would break previews.
   "assets": {
     "directory": "./dist",
+    // Multi-page static site: serve the generated 404.html (built from src/pages/404.astro)
+    // for unmatched paths. Do NOT use "single-page-application" here — that returns
+    // index.html with a 200 for every bad path, which is wrong for a multi-page site.
+    "not_found_handling": "404-page",
   },
   "observability": {
     "enabled": true,