@@ -1,40 +1,63 @@
-# E2E test environment template — copy to .env.e2e and fill in the values.
+# E2E test environment template — copy to ../.env.e2e or cli/.env.e2e
+# depending on the test command working directory, then fill in values.
+#
 # .env.e2e is git-ignored; this file is safe to commit.
 #
+# ── Run mode ────────────────────────────────────────────────────────────────
+# Leave unset for real staging E2E. Set to "local" only for local-mode suites.
+# DIFY_E2E_MODE=local
+
 # ── Edition selector ────────────────────────────────────────────────────────
-# "ce" (default) = Community Edition   "ee" = Enterprise Edition
-# EE-only test cases ([EE] tag) are automatically skipped in CE mode.
-DIFY_E2E_EDITION=ce
+# ce = Community Edition (default)
+# ee = Enterprise Edition; requires workspaces named exactly auto_test0/auto_test1.
+DIFY_E2E_EDITION=ee
 
-# ── Required (both editions) ────────────────────────────────────────────────
+# ── Required for real staging E2E ───────────────────────────────────────────
+# DIFY_E2E_HOST is the OpenAPI / console base URL unless DIFY_E2E_CONSOLE_URL is set.
 DIFY_E2E_HOST=
 DIFY_E2E_EMAIL=
 DIFY_E2E_PASSWORD=
 
-# ── EE notes ────────────────────────────────────────────────────────────────
-# When DIFY_E2E_EDITION=ee the operator must pre-create two workspaces for the
-# test account BEFORE running the suite:
-#   primary   → workspace name: "auto_test0"
-#   secondary → workspace name: "auto_test1"
-# global-setup discovers them by exact name, imports DSL fixtures into both,
-# publishes apps, and sets access_mode → public automatically.
+# ── Enterprise workspace contract ───────────────────────────────────────────
+# For DIFY_E2E_EDITION=ee, the logged-in account must already have:
+#   auto_test0  → primary workspace; global-setup checks 8 fixture apps here.
+#   auto_test1  → secondary workspace; global-setup checks 1 fixture app here.
+#
+# If either workspace is missing, global-setup does not import DSL fixtures.
+# If a fixture app is missing, global-setup imports it from test/e2e/fixtures/apps.
+# If it already exists by exact app name, import is skipped.
+#
+# auto_test0 fixture apps:
+#   echo-chat.yml          → echo-bot
+#   echo-workflow.yml      → basic_auto_test
+#   file-upload.yml        → file_auto_test
+#   hitl-main.yml          → hitl_auto_test
+#   hitl-external.yml      → DIFY_E2E_HITL_EXTERNAL
+#   hitl-single-action.yml → DIFY_E2E_HITL_SINGLE_ACTION
+#   hitl-multi-node.yml    → DIFY_E2E_HITL_MULTI_NODE
+#   file-chat.yml          → DIFY_E2E_FILE_CHAT
+#
+# auto_test1 fixture app:
+#   ws2-workflow.yml       → auto_test_workspace2
 
-# ── Optional overrides ───────────────────────────────────────────────────────
-# Console URL when different from DIFY_E2E_HOST (e.g. EE console proxy)
+# ── Optional host override ──────────────────────────────────────────────────
+# Use only when console login/provisioning URL differs from DIFY_E2E_HOST.
 # DIFY_E2E_CONSOLE_URL=
 
-# Pre-minted primary token — skips device-flow mint in global-setup
+# ── Optional tokens ─────────────────────────────────────────────────────────
+# Primary internal bearer token (dfoa_). When unset, global-setup mints/caches one.
 # DIFY_E2E_TOKEN=
-
-# External SSO bearer token (dfoe_ prefix) — enables SSO test cases
+#
+# External SSO bearer token (dfoe_). Required only for SSO-specific cases.
 # DIFY_E2E_SSO_TOKEN=
 
-# Override workspace IDs (default: discovered by global-setup)
+# ── Optional manual fallbacks ────────────────────────────────────────────────
+# Normally leave these blank: global-setup discovers workspaces and fixture app IDs.
+# They are fallback values for debugging or when provisioning is intentionally skipped.
 # DIFY_E2E_WORKSPACE_ID=
-# DIFY_E2E_WORKSPACE_NAME=
+# DIFY_E2E_WORKSPACE_NAME=auto_test0
 # DIFY_E2E_WS2_ID=
-
-# Override app IDs (default: provisioned from fixture DSL files)
+#
 # DIFY_E2E_CHAT_APP_ID=
 # DIFY_E2E_WORKFLOW_APP_ID=
 # DIFY_E2E_FILE_APP_ID=
 
@@ -157,12 +157,36 @@ export async function setup(project: TestProject): Promise<void> {
   }
 
   // ── Discover workspaces ──────────────────────────────────────────────────
-  const { primaryWsId, primaryWsName, secondaryWsId } = await discoverWorkspaces(
+  const workspaces = await discoverWorkspaces(
     consoleBase,
     cookieString,
     csrfToken,
     E.edition,
   )
+  if (!workspaces) {
+    project.provide('e2eCapabilities', {
+      tokenValid: true,
+      tokenId: match?.id,
+      edition: E.edition,
+      token: primaryToken,
+      logoutToken: '',
+      devicesToken: '',
+      workspaceId: '',
+      workspaceName: '',
+      ws2Id: '',
+      chatAppId: '',
+      workflowAppId: '',
+      fileAppId: '',
+      fileChatAppId: '',
+      hitlAppId: '',
+      hitlExternalAppId: '',
+      hitlSingleActionAppId: '',
+      hitlMultiNodeAppId: '',
+      ws2AppId: '',
+    } satisfies E2ECapabilities)
+    return
+  }
+  const { primaryWsId, primaryWsName, secondaryWsId } = workspaces
 
   // ── Mint per-suite dedicated tokens ──────────────────────────────────────
   let logoutToken = ''
@@ -325,7 +349,7 @@ async function discoverWorkspaces(
   cookieString: string,
   csrfToken: string,
   edition: 'ce' | 'ee',
-): Promise<{ primaryWsId: string, primaryWsName: string, secondaryWsId: string }> {
+): Promise<{ primaryWsId: string, primaryWsName: string, secondaryWsId: string } | null> {
   const wsRes = await fetch(`${consoleBase}/console/api/workspaces`, {
     headers: { 'Cookie': cookieString, 'X-CSRF-Token': csrfToken },
     signal: AbortSignal.timeout(10_000),
@@ -343,26 +367,21 @@ async function discoverWorkspaces(
     const ws0 = all.find(w => w.name === 'auto_test0')
     const ws1 = all.find(w => w.name === 'auto_test1')
 
-    if (!ws0) {
-      throw new Error(
-        '[E2E EE] Workspace "auto_test0" not found. '
-        + 'Please pre-create it for the test account before running E2E tests.',
-      )
-    }
-
-    if (!ws1) {
+    if (!ws0 || !ws1) {
+      const existing = all.map(w => w.name).join(', ') || '(none)'
       console.warn(
-        '[E2E EE] Workspace "auto_test1" not found — secondary workspace will reuse primary. '
-        + 'Cross-workspace [EE] tests may not work correctly.',
+        `[E2E EE] Required workspaces not found; expected auto_test0 and auto_test1, got: ${existing}. `
+        + 'Skip fixture app provisioning.',
       )
+      return null
     }
 
     const primaryWsId = ws0.id
     const primaryWsName = ws0.name
-    const secondaryWsId = ws1?.id ?? ws0.id
+    const secondaryWsId = ws1.id
 
     console.warn(`[E2E EE] primary   workspace: ${primaryWsName} (${primaryWsId})`)
-    console.warn(`[E2E EE] secondary workspace: ${ws1?.name ?? 'reuses primary'} (${secondaryWsId})`)
+    console.warn(`[E2E EE] secondary workspace: ${ws1.name} (${secondaryWsId})`)
 
     return { primaryWsId, primaryWsName, secondaryWsId }
   }
@@ -460,7 +479,7 @@ async function provisionApps(
     const url = `${consoleBase}/console/api/apps?name=${encodeURIComponent(name)}&limit=50&page=1`
     const r = await fetch(url, { headers: mkHeaders(), signal: AbortSignal.timeout(10_000) })
     if (!r.ok)
-      return null
+      throw new Error(`list apps by name "${name}" failed: HTTP ${r.status}`)
     const d = await r.json() as { data?: Array<{ id: string, name: string }> }
     return d.data?.find(a => a.name === name)?.id ?? null
   }
@@ -540,14 +559,14 @@ async function provisionApps(
       }
 
       const dsl = await readFile(join(fixturesDir, dslFile), 'utf8')
-      const appName = (dsl.match(/^[ \t]+name:[ \t]*(\\S[^\\n]*)$/m) ?? [])[1]
+      const appName = (dsl.match(/^[ \t]+name:[ \t]*(\S[^\n]*)$/m) ?? [])[1]
         ?.trim()
         .replace(/^['"]|['"]$/g, '') ?? dslFile
       const appMode = (dsl.match(/^\s+mode:\s*(\S+)/m) ?? [])[1] ?? ''
 
       let appId = await findAppByName(appName)
       if (appId) {
-        console.warn(`[E2E provision] ${dslFile}: exists id=${appId}`)
+        console.warn(`[E2E provision] ${dslFile}: exists in workspace id=${appId}; skip import`)
       }
       else {
         appId = await importFromDsl(dsl)
 
@@ -218,7 +218,7 @@ describe('E2E / error message standards (spec 5.3)', () => {
     // not exist, the error message must display the path without garbling.
     const fileDir = await mkdtemp(join(tmpdir(), 'difyctl-e2e-cjk-'))
     try {
-      const cjkPath = join(fileDir, 'cjk-test-\u6587\u6863.txt') // "文档"
+      const cjkPath = join(fileDir, 'cjk-test-\u6587\u6863.txt') // "document" in Chinese — tests CJK path handling
       // Do not create the file — we want the "not found" error
       const result = await fx.r([
         'run',