diff --git a/README.md b/README.md
index 0608ba3..2c4d4da 100644
--- a/README.md
+++ b/README.md
@@ -68,27 +68,30 @@ Required test coverage of 75.0% reached. Total coverage: 98.64%
 
 ### CI on a sample PR
 
-Eight backend + two frontend + four security jobs all green on every PR:
+Ten jobs across `ci.yml` (eight backend + two frontend) — all green:
 
 ![CI status](docs/images/ci-green.png)
 
-> **Capture:** open <https://github.com/constk/harness-python-react/actions/workflows/ci.yml>, click any green run on `develop`, screenshot the job-list panel. Save as `docs/images/ci-green.png`.
+The four security-workflow jobs (gitleaks, pip-audit, npm audit, trivy) gate every PR alongside this set; see the [Security workflow runs](https://github.com/constk/harness-python-react/actions/workflows/security.yml).
 
-### Hello page (`docker compose up`)
+### Hello page (`npm run dev` / `docker compose up`)
 
-The scaffold's React page hits `/api/v1/health` on load and renders the version + status badge:
+The scaffold's React page hits `/api/v1/health` on load and renders the version + status badge. The Vite dev server proxies `/api/*` to the FastAPI backend (target overridable via `VITE_API_PROXY_TARGET`):
 
 ![Hello page](docs/images/hello-page.png)
 
-> **Capture:** `docker compose up`, open <http://localhost:5173>, screenshot.
+<!--
+TODO (#28): one capture left — Jaeger trace.
 
-### Jaeger trace for `/api/v1/health`
+  docs/images/jaeger-trace.png
+    With the full stack running (`docker compose up`), hit /api/v1/health
+    once, then open http://localhost:16686, select service
+    `harness-python-react`, click the most recent trace, screenshot the
+    span timeline.
 
-OTel auto-instrumentation produces one span per request, exported via OTLP gRPC to the local Jaeger:
-
-![Jaeger trace](docs/images/jaeger-trace.png)
-
-> **Capture:** with the stack running, hit `/api/v1/health` once, then open <http://localhost:16686>, select service `harness-python-react`, click the most recent trace, screenshot the span timeline.
+When the PNG lands in docs/images/, replace this comment with a section
+analogous to "Hello page" above.
+-->
 
 ## Why a harness
 
diff --git a/docker-compose.yml b/docker-compose.yml
index 67c6ae8..55fb5ce 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -30,6 +30,11 @@ services:
       - "5173:5173"
     depends_on:
       - app
+    environment:
+      # Vite dev-server proxy target. Inside the compose network, the
+      # backend service is reachable at http://app:8000. The browser
+      # still hits http://localhost:5173/api/v1/* and Vite proxies it.
+      - VITE_API_PROXY_TARGET=http://app:8000
     # Bind-mount the source so Vite HMR sees host edits. node_modules stays
     # inside the container so platform-native deps aren't shadowed.
     volumes:
diff --git a/docs/images/ci-green.png b/docs/images/ci-green.png
new file mode 100644
index 0000000..83c4f3a
Binary files /dev/null and b/docs/images/ci-green.png differ
diff --git a/docs/images/hello-page.png b/docs/images/hello-page.png
new file mode 100644
index 0000000..61b485b
Binary files /dev/null and b/docs/images/hello-page.png differ
diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts
index 8b0f57b..8ca63ba 100644
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -1,7 +1,26 @@
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 
+// `/api/*` calls from the React app are proxied to the FastAPI backend so
+// the dev experience matches a same-origin production deployment. Without
+// this Vite serves `index.html` for `/api/*`, which the browser then tries
+// to JSON.parse — producing "Unexpected token '<'".
+//
+// Override the target via env when needed:
+//   - Local (no Docker): defaults to http://localhost:8000.
+//   - docker-compose:    set VITE_API_PROXY_TARGET=http://app:8000 (inside
+//                        the compose network the backend hostname is `app`).
+const API_PROXY_TARGET = process.env.VITE_API_PROXY_TARGET ?? 'http://localhost:8000'
+
 // https://vite.dev/config/
 export default defineConfig({
   plugins: [react()],
+  server: {
+    proxy: {
+      '/api': {
+        target: API_PROXY_TARGET,
+        changeOrigin: true,
+      },
+    },
+  },
 })