diff --git a/e2e/deployment-smoke.spec.ts b/e2e/deployment-smoke.spec.ts
index 0cefb05c3..46d0fa31c 100644
--- a/e2e/deployment-smoke.spec.ts
+++ b/e2e/deployment-smoke.spec.ts
@@ -3,10 +3,35 @@ import { test, expect } from '@playwright/test'
 /**
  * Deployment smoke tests — validates all services are reachable
  * through the nginx gateway on port 80.
+ *
+ * These tests require the full Docker stack to be running.
+ * They are skipped automatically when the gateway is unreachable
+ * (e.g. in CI without the stack, or in local dev without docker compose up).
+ *
+ * To run locally:
+ *   cd deployment && docker compose -f docker-compose.stack.yml up -d
+ *   PLAYWRIGHT_BASE_URL=http://localhost/workflowui/ npx playwright test deployment-smoke
  */
 
 const GATEWAY = 'http://localhost'
 
+let stackAvailable = false
+
+test.beforeAll(async ({ request }) => {
+  try {
+    const resp = await request.get(GATEWAY, { timeout: 5000 })
+    stackAvailable = resp.ok()
+  } catch {
+    stackAvailable = false
+  }
+})
+
+test.beforeEach(async ({}, testInfo) => {
+  if (!stackAvailable) {
+    testInfo.skip()
+  }
+})
+
 test.describe('Deployment Smoke Tests', () => {
   test.describe('Web Applications', () => {
     const apps = [