feat: finalize dual-mode API key strategy (ENV-first + advanced server key store)

Author: rookiestar28

.github/workflows/phase2-release-gate.yml

@@ -38,6 +38,17 @@ on:
       - 'tests/e2e/**/*.js'
       - '.github/workflows/phase2-release-gate.yml'
   workflow_dispatch:
+    inputs:
+      run_integration_e2e:
+        description: 'Run optional telemetry integration E2E suite'
+        required: false
+        default: false
+        type: boolean
+      comfyui_url:
+        description: 'ComfyUI backend URL for optional integration suite'
+        required: false
+        default: 'http://127.0.0.1:8188'
+        type: string
 
 jobs:
   phase2-python-gate:
@@ -92,7 +103,7 @@ jobs:
           echo "- Outbound payload safety: PASS"
 
   phase2-e2e-gate:
-    name: Phase 2 E2E Regression Tests
+    name: Phase 2 E2E Regression Tests (Required)
     runs-on: ubuntu-latest
     timeout-minutes: 10
 
@@ -105,27 +116,16 @@ jobs:
         with:
           node-version: '18'
 
-      - name: Set up Python 3.10 (for HTTP server)
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.10'
-
       - name: Install npm dependencies
         run: npm ci
 
       - name: Install Playwright browsers
         run: npx playwright install chromium --with-deps
 
-      - name: Verify Python is available
-        run: |
-          python3 --version
-          which python3
-
       - name: Run E2E tests
         run: npm test
         env:
           CI: true
-          PW_PYTHON: python3
         timeout-minutes: 8
 
       - name: Upload test results
@@ -147,11 +147,66 @@ jobs:
       - name: Summary
         if: success()
         run: |
-          echo "✅ Phase 2 E2E Gate Passed"
+          echo "✅ Phase 2 Required E2E Gate Passed"
           echo "- Preact loader: PASS"
           echo "- Settings UI: PASS"
           echo "- Statistics UI: PASS"
           echo "- Sidebar UI: PASS"
+          echo "- Integration-tagged E2E: excluded by design"
+
+  phase2-e2e-integration-optional:
+    name: Phase 2 E2E Integration (Optional)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    if: |
+      (github.event_name == 'workflow_dispatch' && github.event.inputs.run_integration_e2e == 'true') ||
+      (vars.RUN_INTEGRATION_E2E == 'true')
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js 18
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Install npm dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install chromium --with-deps
+
+      - name: Run optional integration E2E tests
+        run: npm run test:integration
+        env:
+          CI: true
+          COMFYUI_URL: ${{ github.event.inputs.comfyui_url || vars.COMFYUI_URL || 'http://127.0.0.1:8188' }}
+        timeout-minutes: 8
+
+      - name: Upload integration report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report-integration
+          path: playwright-report/
+          retention-days: 7
+
+      - name: Upload integration screenshots
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-screenshots-integration
+          path: test-results/
+          retention-days: 7
+
+      - name: Summary
+        if: success()
+        run: |
+          echo "✅ Optional integration E2E suite completed"
+          echo "- Command: npm run test:integration"
+          echo "- Backend URL: ${{ github.event.inputs.comfyui_url || vars.COMFYUI_URL || 'http://127.0.0.1:8188' }}"
+          echo "- This job does not block release gate."
 
   phase2-gate-complete:
     name: Phase 2 Gate Complete
@@ -171,8 +226,11 @@ jobs:
             echo "  ✅ Dependency policy (2 tests)"
             echo "  ✅ Outbound payload safety (4 tests)"
             echo ""
-            echo "Frontend Regression:"
-            echo "  ✅ E2E tests (61 tests)"
+            echo "Frontend Regression (Required):"
+            echo "  ✅ E2E tests (npm test)"
+            echo ""
+            echo "Optional Integration:"
+            echo "  ℹ️ E2E integration suite is separate and non-blocking"
             echo ""
             echo "This change is safe to merge."
             exit 0

README.md

@@ -2,26 +2,27 @@
 
 [繁中](docs/readme/README.zh-TW.md) | [简中](docs/readme/README.zh-CN.md) | [日本語](docs/readme/README.ja.md) | [한국어](docs/readme/README.ko.md) | [Deutsch](docs/readme/README.de.md) | [Français](docs/readme/README.fr.md) | [Italiano](docs/readme/README.it.md) | [Español](docs/readme/README.es.md) | English |
 
+<div align="center">
+<img src="assets/icon.png" alt="ComfyUI Doctor">
+</div>
+
 A continuous, real-time runtime diagnostics suite for ComfyUI featuring **LLM-powered analysis**, **interactive debugging chat**, and **50+ fix patterns**. Automatically intercepts all terminal output from startup, captures complete Python tracebacks, and delivers prioritized fix suggestions with node-level context extraction. Now supports **JSON-based pattern management** with hot-reload and **full i18n support** for 9 languages (en, zh_TW, zh_CN, ja, de, fr, it, es, ko).
 
-## Table of Contents
+## Latest Updates (Feb 2026) - Click to expand
 
-- [Latest Updates](#latest-updates-jan-2026---click-to-expand)
-- [Features](#features)
-- [Installation](#installation)
-- [Usage](#usage)
-- [Frontend UI](#frontend-ui)
-- [Settings](#settings)
-- [API Endpoints](#api-endpoints)
-- [Supported Error Patterns](#supported-error-patterns)
-- [Phase 2 Release Gate](#phase-2-release-gate)
-- [CSP Compatibility](#csp-compatibility)
-- [Contributing](#contributing)
+<details>
+<summary><strong>(v1.6.3): Dual-Mode API Key Strategy (ENV-first + Advanced Server Key Store)</strong></summary>
 
-## Latest Updates (Jan 2026) - Click to expand
+- API keys are no longer persisted in frontend settings; the API key input is session-only by default.
+- Added a default-collapsed **🔐 Advanced Key Store (Server-side)** section for explicit save/delete actions.
+- Backend key resolution order is now: request key → provider ENV → generic ENV → optional server store.
+- Existing users with legacy frontend-stored keys are auto-migrated once to runtime memory, then the persisted key is cleared.
+- UI now includes inline risk guidance (`?`) warning that server store uses plaintext `secrets.json`; ENV keys remain the recommended path.
+
+</details>
 
 <details>
-<summary><strong>New: F14 Proactive Diagnostics (Health Check + Intent Signature)</strong></summary>
+<summary><strong>Proactive Diagnostics (Health Check + Intent Signature)</strong></summary>
 
 - Added a **Diagnostics** section to the **Statistics** tab for proactive workflow troubleshooting (no LLM required).
 - **Health checks**: workflow lint + environment/deps + privacy/safety checks, with actionable issues.
@@ -321,6 +322,19 @@ ComfyUI Settings panel now only shows the Enable/Disable toggle - all other sett
 
 </details>
 
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Frontend UI](#frontend-ui)
+- [Settings](#settings)
+- [API Endpoints](#api-endpoints)
+- [Supported Error Patterns](#supported-error-patterns)
+- [Phase 2 Release Gate](#phase-2-release-gate)
+- [CSP Compatibility](#csp-compatibility)
+- [Contributing](#contributing)
+
 ## Features
 
 - **Automatic Error Monitoring**: Captures all terminal output and detects Python tracebacks in real-time
@@ -539,13 +553,13 @@ ComfyUI-Doctor integrates with popular LLM services to provide intelligent, cont
 
 ### Configuration
 
-![Settings Panel](./assets/settings.png)
+<img src="assets/settings.png" alt="side bar - settings">
 
 Configure AI analysis in the **Doctor Sidebar** → **Settings** panel:
 
 1. **AI Provider**: Select from the dropdown menu. The Base URL will auto-fill.
 2. **AI Base URL**: The API endpoint (auto-populated, but customizable)
-3. **AI API Key**: Your API key (leave empty for local LLMs like Ollama/LMStudio)
+3. **AI API Key**: Session-only key input for cloud providers (leave empty for local LLMs like Ollama/LMStudio)
 4. **AI Model Name**:
    - Select a model from the dropdown list (automatically populated from your provider's API)
    - Click the 🔄 refresh button to reload available models
@@ -559,7 +573,7 @@ Configure AI analysis in the **Doctor Sidebar** → **Settings** panel:
 3. Wait for the LLM to analyze the error (typically 3-10 seconds).
 4. Review the AI-generated debugging suggestions.
 
-**Security Note**: Your API key is transmitted securely from frontend to backend for the analysis request only. It is never logged or stored persistently.
+**Security Note**: API keys are **session-only** in the browser (cleared on reload). The backend resolves keys via this priority chain: request key → `DOCTOR_{PROVIDER}_API_KEY` → `DOCTOR_LLM_API_KEY` → optional server-side store (`secrets.json`). Keys are never logged and the server store is admin-gated. `secrets.json` is plaintext on disk (OS-permission protected), so for maximum security use environment variables.
 
 ### Privacy Mode (PII Sanitization)
 
@@ -702,7 +716,18 @@ You can customize ComfyUI-Doctor behavior via the **Doctor sidebar → Settings*
 
 **Function**: Your API key for authentication with cloud LLM services.
 **Usage**: Required for cloud providers (OpenAI, DeepSeek, etc.). Leave empty for local LLMs (Ollama, LMStudio).
-**Security**: The key is only transmitted during analysis requests and is never logged or persisted.
+**Default Behavior**: Session-only in frontend (cleared on reload); not persisted in ComfyUI settings.
+**Runtime Resolution Priority**: Request key → provider-specific ENV → generic ENV → optional server-side key store.
+**Security Warning**: The server-side key store writes plaintext `secrets.json` to disk. Use ENV for production or multi-user environments.
+
+**Advanced Key Store Setup (optional)**:
+
+<img src="assets/key_store.png" alt="side bar - Advanced Key Store">
+
+1. Expand **🔐 Advanced Key Store (Server-side)** in Settings (collapsed by default).
+2. Select provider, paste API key, and provide admin token if configured.
+3. Click **💾 Save to Server** to persist, or **🗑️ Delete** to remove.
+4. Confirm provider status badge (`ENV`, `Server`, `None`) to verify effective source.
 
 ### 9. AI Model Name