Add deployment plan docs

docs/superpowers/plans/2026-04-17-hf-space-hermes-web-ui.md

@@ -0,0 +1,170 @@
+# HF Space Hermes Web UI Replacement Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the built-in Hermes dashboard startup path in the Hugging Face Docker Space image with `hermes-web-ui`, without changing Hermes core application code.
+
+**Architecture:** Keep the existing Hermes container and runtime bootstrap. Install the external UI during image build, enable the Hermes API server through the gateway, then run the new UI as the foreground Space process on port `7860`.
+
+**Tech Stack:** Docker, bash entrypoint, npm global package install, Hermes gateway/API server
+
+---
+
+### Task 1: Document the Docker-only integration boundary
+
+**Files:**
+- Create: `E:\Codeing\hermes-agent-2026.4.13\docs\superpowers\specs\2026-04-17-hf-space-hermes-web-ui-design.md`
+- Create: `E:\Codeing\hermes-agent-2026.4.13\docs\superpowers\plans\2026-04-17-hf-space-hermes-web-ui.md`
+
+- [ ] **Step 1: Confirm the integration boundary**
+
+State that only Docker/runtime files will change:
+
+```text
+Dockerfile
+docker/entrypoint.sh
+```
+
+- [ ] **Step 2: Record the runtime contract**
+
+Document that the new UI will consume:
+
+```text
+UPSTREAM=http://127.0.0.1:8642
+PORT=7860
+HERMES_HOME=/opt/data or runtime override
+HERMES_BIN=/opt/hermes/.venv/bin/hermes
+```
+
+- [ ] **Step 3: Record the Hermes side requirement**
+
+Document that the Space startup must export:
+
+```text
+API_SERVER_ENABLED=true
+API_SERVER_HOST=127.0.0.1
+API_SERVER_PORT=8642
+```
+
+### Task 2: Install hermes-web-ui during image build
+
+**Files:**
+- Modify: `E:\Codeing\hermes-agent-2026.4.13\Dockerfile`
+
+- [ ] **Step 1: Add the package install in the Docker image**
+
+Insert a pinned global install in the existing Node/npm layer:
+
+```dockerfile
+RUN npm install --prefer-offline --no-audit && \
+    npm install -g --no-audit hermes-web-ui@0.3.2 && \
+    npx playwright install --with-deps chromium --only-shell && \
+    cd /opt/hermes/scripts/whatsapp-bridge && \
+    npm install --prefer-offline --no-audit && \
+    npm cache clean --force
+```
+
+- [ ] **Step 2: Keep all existing Hermes build behavior intact**
+
+Do not remove:
+
+```dockerfile
+npx playwright install --with-deps chromium --only-shell
+uv venv
+uv pip install --no-cache-dir -e ".[all]"
+```
+
+- [ ] **Step 3: Verify the Dockerfile still has a single image entrypoint**
+
+Ensure this remains unchanged:
+
+```dockerfile
+ENTRYPOINT [ "/opt/hermes/docker/entrypoint.sh" ]
+```
+
+### Task 3: Replace official dashboard startup in Space mode
+
+**Files:**
+- Modify: `E:\Codeing\hermes-agent-2026.4.13\docker\entrypoint.sh`
+
+- [ ] **Step 1: Write the Space-mode environment exports**
+
+Add these inside the existing `SPACE_ID` / `SPACE_HOST` block before launching processes:
+
+```bash
+    export API_SERVER_ENABLED="${API_SERVER_ENABLED:-true}"
+    export API_SERVER_HOST="${API_SERVER_HOST:-127.0.0.1}"
+    export API_SERVER_PORT="${API_SERVER_PORT:-8642}"
+```
+
+- [ ] **Step 2: Replace the dashboard command wiring**
+
+Change the command variables to:
+
+```bash
+    HERMES_BIN="$INSTALL_DIR/.venv/bin/hermes"
+    GATEWAY_CMD="$HERMES_BIN gateway run"
+    WEB_UI_CMD="hermes-web-ui start --host 0.0.0.0 --port 7860"
+
+    export PORT="${PORT:-7860}"
+    export UPSTREAM="${UPSTREAM:-http://127.0.0.1:${API_SERVER_PORT}}"
+    export HERMES_BIN
+```
+
+- [ ] **Step 3: Preserve background gateway + foreground UI process behavior**
+
+Run:
+
+```bash
+    $SHELL_EXEC -lc "$GATEWAY_CMD" &
+    exec $SHELL_EXEC -lc "$WEB_UI_CMD"
+```
+
+- [ ] **Step 4: Remove the official dashboard launch only**
+
+Delete the old dashboard command assignment:
+
+```bash
+    DASHBOARD_CMD="$HERMES_BIN dashboard --host 0.0.0.0 --port 7860 --no-open"
+```
+
+and its exec call, while leaving the rest of the bootstrap logic untouched.
+
+### Task 4: Verify the integration wiring
+
+**Files:**
+- Verify: `E:\Codeing\hermes-agent-2026.4.13\Dockerfile`
+- Verify: `E:\Codeing\hermes-agent-2026.4.13\docker\entrypoint.sh`
+
+- [ ] **Step 1: Run shell syntax validation**
+
+Run:
+
+```bash
+bash -n docker/entrypoint.sh
+```
+
+Expected: exit code `0` and no output
+
+- [ ] **Step 2: Inspect the startup wiring**
+
+Run:
+
+```bash
+Select-String -Path Dockerfile,docker/entrypoint.sh -Pattern "hermes-web-ui|API_SERVER_ENABLED|UPSTREAM|dashboard --host|gateway run"
+```
+
+Expected:
+- `hermes-web-ui` appears in both build/runtime wiring
+- `API_SERVER_ENABLED` appears in `docker/entrypoint.sh`
+- the old `dashboard --host` launch no longer appears in the active Space startup path
+
+- [ ] **Step 3: Report deployment follow-up**
+
+State clearly that after local file changes, the Hugging Face Space still needs:
+
+```text
+1. upload or commit the modified files
+2. rebuild the Docker Space
+3. inspect startup logs to confirm gateway + hermes-web-ui both start
+```