diff --git a/README.md b/README.md
index 6de479b..9d86afc 100644
--- a/README.md
+++ b/README.md
@@ -82,6 +82,37 @@ npm run build
 npx playwright test
 ```
 
+## Sample Article E2E
+
+Run the live sample-article browser workflow:
+
+```bash
+npm run test:e2e:samples
+```
+
+The runner reads `.env.local`, starts an isolated local Next.js server, loads
+`samples/articles/*.json`, opens the web UI with Playwright, runs each sample
+through the one-click optimization flow, validates authenticated exports, and
+writes a report under:
+
+```text
+test-results/geo-sample-flow/<timestamp>/
+```
+
+Useful options:
+
+```bash
+npm run test:e2e:samples -- --limit 1
+npm run test:e2e:samples -- --sample title-quality
+npm run test:e2e:samples -- --headed
+npm run test:e2e:samples -- --reuse-server --base-url http://localhost:3000
+```
+
+This workflow uses the real configured LLM provider by default. It requires
+`API_ACCESS_KEY` and the provider API key in `.env.local` or the shell
+environment. Reports and exports are written to `test-results/`, which is
+ignored by Git.
+
 ## Cloudflare Workers Deployment
 
 Cloudflare deployment is manual. Pushing to Git does not deploy or hot-update