create-workframe 0.1.1 → 0.1.2

package/README.md

@@ -3,7 +3,7 @@
 Published on npm as **create-workframe**.
 
 ```bash
-npx create-workframe@0.1.1 MyProject
+npx create-workframe@0.1.2 MyProject
 ```
 
 Scaffolds an isolated Workframe + Hermes project on Windows, macOS, and Linux.

package/SECURITY.md

@@ -25,9 +25,7 @@ We aim to acknowledge reports within a few business days.
 
 ## Scope notes
 
-- **Host Hermes** (`%LOCALAPPDATA%\hermes` on Windows) is personal runtime state and is
-  out of scope for Workframe product security reports unless the issue is in shared
-  Workframe source code that affects all installs.
+- Personal Hermes installs outside a Workframe compose stack are out of scope unless the issue is in shared Workframe source that affects all installs.
 - Production deployments should run with `WORKFRAME_MODE=team`, invite-only access, and
   without `DEV_LOCAL_UNSAFE`.
 - BYOK (bring-your-own-key) is the default credential mode; workspace company-pays is an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-workframe",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Scaffold a Workframe + Hermes workspace with guided onboarding",
   "type": "module",
   "bin": {

package/scripts/apply-update-hermes.sh

@@ -1,17 +1,17 @@
-#!/usr/bin/env bash
-# Safe Hermes update — pull gateway/dashboard images, recreate containers. Preserves runtime/Agents.
-set -euo pipefail
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-# shellcheck source=compose-docker-host.sh
-source "$SCRIPT_DIR/compose-docker-host.sh"
-
-echo "=== Hermes update (gateway + dashboard only) ==="
-workframe_compose_prepare
-echo "Compose dir: $compose_cd"
-echo "Preserves: Agents/, Files/, workframe-api data volumes"
-
-SERVICES=(gateway dashboard)
-workframe_compose pull "${SERVICES[@]}"
-workframe_compose up -d --force-recreate --no-deps "${SERVICES[@]}"
-
-echo "=== Hermes update complete ==="
+#!/usr/bin/env bash
+# Safe Hermes update — pull gateway/dashboard images, recreate containers. Preserves runtime/Agents.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=compose-docker-host.sh
+source "$SCRIPT_DIR/compose-docker-host.sh"
+
+echo "=== Hermes update (gateway + dashboard only) ==="
+workframe_compose_prepare
+echo "Compose dir: $compose_cd"
+echo "Preserves: Agents/, Files/, workframe-api data volumes"
+
+SERVICES=(gateway dashboard)
+workframe_compose pull "${SERVICES[@]}"
+workframe_compose up -d --force-recreate --no-deps "${SERVICES[@]}"
+
+echo "=== Hermes update complete ==="

package/scripts/apply-update-workframe.sh

@@ -1,77 +1,77 @@
-#!/usr/bin/env bash
-# Safe Workframe update — sync npm template (optional), rebuild API/supervisor/UI containers. Never wipes runtime/DB.
-set -euo pipefail
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-# shellcheck source=compose-docker-host.sh
-source "$SCRIPT_DIR/compose-docker-host.sh"
-
-workframe_compose_prepare
-PROJECT_ROOT="${WORKFRAME_HOST_PROJECT_ROOT:-${WORKFRAME_PROJECT_ROOT:-$compose_cd}}"
-
-echo "=== Workframe update (API + supervisor + UI) ==="
-echo "Project root: $PROJECT_ROOT"
-echo "Preserves: Agents/, Files/, .env, workframe-api/data, gateway/Hermes profiles"
-
-TARGET_VERSION="${WORKFRAME_UPDATE_VERSION:-}"
-NPM_PACKAGE="${WORKFRAME_NPM_PACKAGE:-create-workframe}"
-
-if [[ "${WORKFRAME_UPDATE_SKIP_NPM:-1}" == "1" ]] && [[ "${WORKFRAME_UPDATE_ALLOW_NPM:-}" != "1" ]]; then
-  echo "Skipping npm template sync (WORKFRAME_UPDATE_SKIP_NPM=1; set WORKFRAME_UPDATE_ALLOW_NPM=1 to fetch)"
-elif command -v npm >/dev/null 2>&1; then
-  if [[ "${WORKFRAME_UPDATE_ALLOW_NPM:-}" == "1" ]] && [[ -z "$TARGET_VERSION" ]]; then
-    echo "WORKFRAME_UPDATE_VERSION is required when WORKFRAME_UPDATE_ALLOW_NPM=1" >&2
-    exit 1
-  fi
-  TMP="$(mktemp -d)"
-  trap 'rm -rf "$TMP"' EXIT
-  echo "Fetching ${NPM_PACKAGE}@${TARGET_VERSION:-latest} from npm..."
-  (cd "$TMP" && npm pack "${NPM_PACKAGE}@${TARGET_VERSION:-latest}" --silent)
-  TARBALL="$(ls -1 "$TMP"/${NPM_PACKAGE}-*.tgz 2>/dev/null | head -n1 || true)"
-  if [[ -n "$TARBALL" ]]; then
-    EXPECTED="$(npm view "${NPM_PACKAGE}@${TARGET_VERSION:-latest}" dist.integrity --silent 2>/dev/null || true)"
-    if [[ -n "$EXPECTED" ]]; then
-      ACTUAL="sha512-$(sha512sum "$TARBALL" | awk '{print $1}' | xxd -r -p | base64 | tr -d '\n')"
-      if [[ "$ACTUAL" != "$EXPECTED" ]]; then
-        echo "integrity mismatch for ${NPM_PACKAGE}@${TARGET_VERSION:-latest}" >&2
-        exit 1
-      fi
-      echo "integrity ok: ${NPM_PACKAGE}@${TARGET_VERSION:-latest}"
-    fi
-    tar -xf "$TARBALL" -C "$TMP"
-    PKG="$TMP/package"
-    for dir in workframe-api workframe-supervisor; do
-      if [[ -d "$PKG/$dir" ]]; then
-        echo "Syncing $dir/"
-        mkdir -p "$PROJECT_ROOT/$dir"
-        cp -a "$PKG/$dir/." "$PROJECT_ROOT/$dir/"
-      fi
-    done
-    if [[ -d "$PKG/workframe-ui/public" ]]; then
-      echo "Syncing workframe-ui/public/"
-      mkdir -p "$PROJECT_ROOT/workframe-ui/public"
-      cp -a "$PKG/workframe-ui/public/." "$PROJECT_ROOT/workframe-ui/public/"
-    fi
-    for script in apply-update-hermes.sh apply-update-workframe.sh restart-gateway-hermes.sh compose-docker-host.sh update-hermes.sh; do
-      if [[ -f "$PKG/scripts/$script" ]]; then
-        cp -a "$PKG/scripts/$script" "$PROJECT_ROOT/scripts/workframe/$script"
-        chmod +x "$PROJECT_ROOT/scripts/workframe/$script" 2>/dev/null || true
-      fi
-    done
-  else
-    echo "npm pack produced no tarball — skipping template sync"
-  fi
-else
-  echo "Skipping npm template sync (npm missing or WORKFRAME_UPDATE_SKIP_NPM=1)"
-fi
-
-echo "Rebuilding workframe-api and workframe-supervisor..."
-workframe_compose build workframe-api workframe-supervisor
-workframe_compose up -d --build --no-deps workframe-api workframe-supervisor
-
-if workframe_compose config --services 2>/dev/null | grep -qx workframe-ui; then
-  workframe_compose up -d --no-deps workframe-ui || workframe_compose restart workframe-ui || true
-elif workframe_compose config --services 2>/dev/null | grep -qx workframe; then
-  workframe_compose up -d --no-deps workframe || workframe_compose restart workframe || true
-fi
-
-echo "=== Workframe update complete ==="
+#!/usr/bin/env bash
+# Safe Workframe update — sync npm template (optional), rebuild API/supervisor/UI containers. Never wipes runtime/DB.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=compose-docker-host.sh
+source "$SCRIPT_DIR/compose-docker-host.sh"
+
+workframe_compose_prepare
+PROJECT_ROOT="${WORKFRAME_HOST_PROJECT_ROOT:-${WORKFRAME_PROJECT_ROOT:-$compose_cd}}"
+
+echo "=== Workframe update (API + supervisor + UI) ==="
+echo "Project root: $PROJECT_ROOT"
+echo "Preserves: Agents/, Files/, .env, workframe-api/data, gateway/Hermes profiles"
+
+TARGET_VERSION="${WORKFRAME_UPDATE_VERSION:-}"
+NPM_PACKAGE="${WORKFRAME_NPM_PACKAGE:-create-workframe}"
+
+if [[ "${WORKFRAME_UPDATE_SKIP_NPM:-1}" == "1" ]] && [[ "${WORKFRAME_UPDATE_ALLOW_NPM:-}" != "1" ]]; then
+  echo "Skipping npm template sync (WORKFRAME_UPDATE_SKIP_NPM=1; set WORKFRAME_UPDATE_ALLOW_NPM=1 to fetch)"
+elif command -v npm >/dev/null 2>&1; then
+  if [[ "${WORKFRAME_UPDATE_ALLOW_NPM:-}" == "1" ]] && [[ -z "$TARGET_VERSION" ]]; then
+    echo "WORKFRAME_UPDATE_VERSION is required when WORKFRAME_UPDATE_ALLOW_NPM=1" >&2
+    exit 1
+  fi
+  TMP="$(mktemp -d)"
+  trap 'rm -rf "$TMP"' EXIT
+  echo "Fetching ${NPM_PACKAGE}@${TARGET_VERSION:-latest} from npm..."
+  (cd "$TMP" && npm pack "${NPM_PACKAGE}@${TARGET_VERSION:-latest}" --silent)
+  TARBALL="$(ls -1 "$TMP"/${NPM_PACKAGE}-*.tgz 2>/dev/null | head -n1 || true)"
+  if [[ -n "$TARBALL" ]]; then
+    EXPECTED="$(npm view "${NPM_PACKAGE}@${TARGET_VERSION:-latest}" dist.integrity --silent 2>/dev/null || true)"
+    if [[ -n "$EXPECTED" ]]; then
+      ACTUAL="sha512-$(sha512sum "$TARBALL" | awk '{print $1}' | xxd -r -p | base64 | tr -d '\n')"
+      if [[ "$ACTUAL" != "$EXPECTED" ]]; then
+        echo "integrity mismatch for ${NPM_PACKAGE}@${TARGET_VERSION:-latest}" >&2
+        exit 1
+      fi
+      echo "integrity ok: ${NPM_PACKAGE}@${TARGET_VERSION:-latest}"
+    fi
+    tar -xf "$TARBALL" -C "$TMP"
+    PKG="$TMP/package"
+    for dir in workframe-api workframe-supervisor; do
+      if [[ -d "$PKG/$dir" ]]; then
+        echo "Syncing $dir/"
+        mkdir -p "$PROJECT_ROOT/$dir"
+        cp -a "$PKG/$dir/." "$PROJECT_ROOT/$dir/"
+      fi
+    done
+    if [[ -d "$PKG/workframe-ui/public" ]]; then
+      echo "Syncing workframe-ui/public/"
+      mkdir -p "$PROJECT_ROOT/workframe-ui/public"
+      cp -a "$PKG/workframe-ui/public/." "$PROJECT_ROOT/workframe-ui/public/"
+    fi
+    for script in apply-update-hermes.sh apply-update-workframe.sh restart-gateway-hermes.sh compose-docker-host.sh update-hermes.sh; do
+      if [[ -f "$PKG/scripts/$script" ]]; then
+        cp -a "$PKG/scripts/$script" "$PROJECT_ROOT/scripts/workframe/$script"
+        chmod +x "$PROJECT_ROOT/scripts/workframe/$script" 2>/dev/null || true
+      fi
+    done
+  else
+    echo "npm pack produced no tarball — skipping template sync"
+  fi
+else
+  echo "Skipping npm template sync (npm missing or WORKFRAME_UPDATE_SKIP_NPM=1)"
+fi
+
+echo "Rebuilding workframe-api and workframe-supervisor..."
+workframe_compose build workframe-api workframe-supervisor
+workframe_compose up -d --build --no-deps workframe-api workframe-supervisor
+
+if workframe_compose config --services 2>/dev/null | grep -qx workframe-ui; then
+  workframe_compose up -d --no-deps workframe-ui || workframe_compose restart workframe-ui || true
+elif workframe_compose config --services 2>/dev/null | grep -qx workframe; then
+  workframe_compose up -d --no-deps workframe || workframe_compose restart workframe || true
+fi
+
+echo "=== Workframe update complete ==="

package/scripts/bootstrap-workspace-link.sh

@@ -1,8 +1,8 @@
-#!/bin/sh
-# Hermes sets HERMES_WRITE_SAFE_ROOT=/opt/data — user artifacts must resolve under it.
-# Bind host Files at /opt/data/workspace; keep /workspace as a symlink for agents and API.
-mkdir -p /opt/data/workspace
-if [ -L /workspace ] || [ ! -e /workspace ]; then
-  rm -rf /workspace 2>/dev/null || true
-  ln -sfn /opt/data/workspace /workspace
-fi
+#!/bin/sh
+# Hermes sets HERMES_WRITE_SAFE_ROOT=/opt/data — user artifacts must resolve under it.
+# Bind host Files at /opt/data/workspace; keep /workspace as a symlink for agents and API.
+mkdir -p /opt/data/workspace
+if [ -L /workspace ] || [ ! -e /workspace ]; then
+  rm -rf /workspace 2>/dev/null || true
+  ln -sfn /opt/data/workspace /workspace
+fi

package/scripts/compose-docker-host.sh

@@ -1,37 +1,37 @@
-#!/usr/bin/env bash
-# Shared docker compose invocation for in-container apply (docker.sock on host).
-set -euo pipefail
-
-workframe_compose_prepare() {
-  compose_cd=""
-  compose_files=()
-
-  # Host-bindings overlay: docker.sock apply from supervisor uses WORKFRAME_HOST_* paths.
-  if [[ -n "${WORKFRAME_HOST_COMPOSE_DIR:-}" && -n "${WORKFRAME_COMPOSE_DIR:-}" \
-        && -f "${WORKFRAME_COMPOSE_DIR}/docker-compose.yml" \
-        && -f "${WORKFRAME_COMPOSE_DIR}/docker-compose.host-bindings.yml" ]]; then
-    compose_cd="${WORKFRAME_COMPOSE_DIR}"
-    compose_files=(-f docker-compose.yml -f docker-compose.host-bindings.yml)
-    return 0
-  fi
-
-  # ponytail: docker Desktop resolves WORKFRAME_HOST_* via socket even when path is not visible in this container.
-  if [[ -n "${WORKFRAME_HOST_COMPOSE_DIR:-}" ]]; then
-    compose_cd="${WORKFRAME_HOST_COMPOSE_DIR}"
-    compose_files=(-f docker-compose.yml)
-    return 0
-  fi
-
-  compose_cd="${WORKFRAME_COMPOSE_DIR:-${WORKFRAME_PROJECT_ROOT:-.}}"
-  compose_files=(-f docker-compose.yml)
-}
-
-workframe_compose() {
-  workframe_compose_prepare
-  cd "$compose_cd"
-  if [[ ! -f docker-compose.yml ]]; then
-    echo "docker-compose.yml not found in $compose_cd" >&2
-    exit 1
-  fi
-  docker compose "${compose_files[@]}" "$@"
-}
+#!/usr/bin/env bash
+# Shared docker compose invocation for in-container apply (docker.sock on host).
+set -euo pipefail
+
+workframe_compose_prepare() {
+  compose_cd=""
+  compose_files=()
+
+  # Host-bindings overlay: docker.sock apply from supervisor uses WORKFRAME_HOST_* paths.
+  if [[ -n "${WORKFRAME_HOST_COMPOSE_DIR:-}" && -n "${WORKFRAME_COMPOSE_DIR:-}" \
+        && -f "${WORKFRAME_COMPOSE_DIR}/docker-compose.yml" \
+        && -f "${WORKFRAME_COMPOSE_DIR}/docker-compose.host-bindings.yml" ]]; then
+    compose_cd="${WORKFRAME_COMPOSE_DIR}"
+    compose_files=(-f docker-compose.yml -f docker-compose.host-bindings.yml)
+    return 0
+  fi
+
+  # ponytail: docker Desktop resolves WORKFRAME_HOST_* via socket even when path is not visible in this container.
+  if [[ -n "${WORKFRAME_HOST_COMPOSE_DIR:-}" ]]; then
+    compose_cd="${WORKFRAME_HOST_COMPOSE_DIR}"
+    compose_files=(-f docker-compose.yml)
+    return 0
+  fi
+
+  compose_cd="${WORKFRAME_COMPOSE_DIR:-${WORKFRAME_PROJECT_ROOT:-.}}"
+  compose_files=(-f docker-compose.yml)
+}
+
+workframe_compose() {
+  workframe_compose_prepare
+  cd "$compose_cd"
+  if [[ ! -f docker-compose.yml ]]; then
+    echo "docker-compose.yml not found in $compose_cd" >&2
+    exit 1
+  fi
+  docker compose "${compose_files[@]}" "$@"
+}

package/scripts/fix-zk-encryption-key.sh

@@ -1,35 +1,35 @@
-#!/usr/bin/env bash
-# Fix ZK_AUTH_ENCRYPTION_KEY when it was generated as hex instead of base64.
-set -euo pipefail
-ENV_FILE="${1:-/opt/workframe/MyBusiness/.env}"
-FORCE="${2:-}"
-python3 - "$ENV_FILE" "$FORCE" <<'PY'
-import base64, os, re, sys
-from pathlib import Path
-env, force = Path(sys.argv[1]), sys.argv[2] == "--force"
-text = env.read_text(encoding="utf-8")
-m = re.search(r"^ZK_AUTH_ENCRYPTION_KEY=(.*)$", text, re.M)
-if not m:
-    print("ZK_AUTH_ENCRYPTION_KEY missing"); sys.exit(1)
-val = m.group(1).strip()
-try:
-    ok = len(base64.b64decode(val)) == 32
-except Exception:
-    ok = False
-if ok:
-    print("ZK_AUTH_ENCRYPTION_KEY already valid"); sys.exit(0)
-
-zk_db = Path(os.environ.get("WORKFRAME_API_DATA_DIR", "/app/data")) / "zk_auth.db"
-if zk_db.is_file() and not force:
-    import sqlite3
-    n = sqlite3.connect(str(zk_db)).execute("SELECT COUNT(*) FROM identities").fetchone()[0]
-    if n > 0:
-        print(f"REFUSING: {n} encrypted identities present. Regenerating the KEK will lock "
-              f"out every existing user. Re-run with --force to proceed.", file=sys.stderr)
-        sys.exit(1)
-
-new_key = base64.b64encode(os.urandom(32)).decode()
-text = re.sub(r"^ZK_AUTH_ENCRYPTION_KEY=.*$", f"ZK_AUTH_ENCRYPTION_KEY={new_key}", text, flags=re.M)
-env.write_text(text, encoding="utf-8")
-print("ZK_AUTH_ENCRYPTION_KEY regenerated (was invalid base64)")
-PY
+#!/usr/bin/env bash
+# Fix ZK_AUTH_ENCRYPTION_KEY when it was generated as hex instead of base64.
+set -euo pipefail
+ENV_FILE="${1:-/opt/workframe/MyBusiness/.env}"
+FORCE="${2:-}"
+python3 - "$ENV_FILE" "$FORCE" <<'PY'
+import base64, os, re, sys
+from pathlib import Path
+env, force = Path(sys.argv[1]), sys.argv[2] == "--force"
+text = env.read_text(encoding="utf-8")
+m = re.search(r"^ZK_AUTH_ENCRYPTION_KEY=(.*)$", text, re.M)
+if not m:
+    print("ZK_AUTH_ENCRYPTION_KEY missing"); sys.exit(1)
+val = m.group(1).strip()
+try:
+    ok = len(base64.b64decode(val)) == 32
+except Exception:
+    ok = False
+if ok:
+    print("ZK_AUTH_ENCRYPTION_KEY already valid"); sys.exit(0)
+
+zk_db = Path(os.environ.get("WORKFRAME_API_DATA_DIR", "/app/data")) / "zk_auth.db"
+if zk_db.is_file() and not force:
+    import sqlite3
+    n = sqlite3.connect(str(zk_db)).execute("SELECT COUNT(*) FROM identities").fetchone()[0]
+    if n > 0:
+        print(f"REFUSING: {n} encrypted identities present. Regenerating the KEK will lock "
+              f"out every existing user. Re-run with --force to proceed.", file=sys.stderr)
+        sys.exit(1)
+
+new_key = base64.b64encode(os.urandom(32)).decode()
+text = re.sub(r"^ZK_AUTH_ENCRYPTION_KEY=.*$", f"ZK_AUTH_ENCRYPTION_KEY={new_key}", text, flags=re.M)
+env.write_text(text, encoding="utf-8")
+print("ZK_AUTH_ENCRYPTION_KEY regenerated (was invalid base64)")
+PY

package/scripts/restart-gateway-hermes.sh

@@ -1,12 +1,12 @@
-#!/usr/bin/env bash
-# Restart Hermes gateway container only — no image pull. Preserves runtime/Agents.
-set -euo pipefail
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-# shellcheck source=compose-docker-host.sh
-source "$SCRIPT_DIR/compose-docker-host.sh"
-
-echo "=== Hermes gateway restart ==="
-workframe_compose_prepare
-echo "Compose dir: $compose_cd"
-workframe_compose up -d --force-recreate --no-deps gateway
-echo "=== Gateway restart complete ==="
+#!/usr/bin/env bash
+# Restart Hermes gateway container only — no image pull. Preserves runtime/Agents.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=compose-docker-host.sh
+source "$SCRIPT_DIR/compose-docker-host.sh"
+
+echo "=== Hermes gateway restart ==="
+workframe_compose_prepare
+echo "Compose dir: $compose_cd"
+workframe_compose up -d --force-recreate --no-deps gateway
+echo "=== Gateway restart complete ==="

package/scripts/setup-stack-secrets.sh

@@ -1,50 +1,50 @@
-#!/usr/bin/env bash
-# Append production stack secrets to a Workframe .env (idempotent).
-# Usage: bash scripts/workframe/setup-stack-secrets.sh path/to/.env
-set -euo pipefail
-
-ENV_FILE="${1:-/workspace/.env}"
-
-append_if_missing() {
-  local key="$1"
-  local value="$2"
-  local comment="${3:-}"
-  if [[ -f "$ENV_FILE" ]] && grep -q "^${key}=" "$ENV_FILE"; then
-    echo "${key} already exists in ${ENV_FILE}"
-    return 0
-  fi
-  mkdir -p "$(dirname "$ENV_FILE")"
-  {
-    [[ -n "$comment" ]] && printf '\n# %s\n' "$comment"
-    printf '%s=%s\n' "$key" "$value"
-  } >>"$ENV_FILE"
-  echo "${key} generated and appended to ${ENV_FILE}"
-}
-
-rand_hex() {
-  openssl rand -hex 32 2>/dev/null || python3 - <<'PY'
-import secrets
-print(secrets.token_hex(32))
-PY
-}
-
-rand_b64() {
-  python3 - <<'PY'
-import base64, os
-print(base64.b64encode(os.urandom(32)).decode())
-PY
-}
-
-rand_proxy() {
-  python3 - <<'PY'
-import secrets
-print(secrets.token_urlsafe(32))
-PY
-}
-
-append_if_missing WORKFRAME_SUPERVISOR_TOKEN "${WORKFRAME_SUPERVISOR_TOKEN:-$(rand_hex)}" \
-  "Workframe supervisor token. Keep this secret."
-append_if_missing WORKFRAME_PROXY_TOKEN "${WORKFRAME_PROXY_TOKEN:-$(rand_proxy)}" \
-  "Internal LLM/action proxy secret — gateway + API must match."
-append_if_missing WORKFRAME_VAULT_KEK "${WORKFRAME_VAULT_KEK:-$(rand_b64)}" \
-  "Credential vault KEK (32-byte base64). Required for public_multi_user."
+#!/usr/bin/env bash
+# Append production stack secrets to a Workframe .env (idempotent).
+# Usage: bash scripts/workframe/setup-stack-secrets.sh path/to/.env
+set -euo pipefail
+
+ENV_FILE="${1:-/workspace/.env}"
+
+append_if_missing() {
+  local key="$1"
+  local value="$2"
+  local comment="${3:-}"
+  if [[ -f "$ENV_FILE" ]] && grep -q "^${key}=" "$ENV_FILE"; then
+    echo "${key} already exists in ${ENV_FILE}"
+    return 0
+  fi
+  mkdir -p "$(dirname "$ENV_FILE")"
+  {
+    [[ -n "$comment" ]] && printf '\n# %s\n' "$comment"
+    printf '%s=%s\n' "$key" "$value"
+  } >>"$ENV_FILE"
+  echo "${key} generated and appended to ${ENV_FILE}"
+}
+
+rand_hex() {
+  openssl rand -hex 32 2>/dev/null || python3 - <<'PY'
+import secrets
+print(secrets.token_hex(32))
+PY
+}
+
+rand_b64() {
+  python3 - <<'PY'
+import base64, os
+print(base64.b64encode(os.urandom(32)).decode())
+PY
+}
+
+rand_proxy() {
+  python3 - <<'PY'
+import secrets
+print(secrets.token_urlsafe(32))
+PY
+}
+
+append_if_missing WORKFRAME_SUPERVISOR_TOKEN "${WORKFRAME_SUPERVISOR_TOKEN:-$(rand_hex)}" \
+  "Workframe supervisor token. Keep this secret."
+append_if_missing WORKFRAME_PROXY_TOKEN "${WORKFRAME_PROXY_TOKEN:-$(rand_proxy)}" \
+  "Internal LLM/action proxy secret — gateway + API must match."
+append_if_missing WORKFRAME_VAULT_KEK "${WORKFRAME_VAULT_KEK:-$(rand_b64)}" \
+  "Credential vault KEK (32-byte base64). Required for public_multi_user."

package/scripts/sync-canonical-to-package.mjs

@@ -57,6 +57,17 @@ function removeIfExists(p) {
   if (fs.existsSync(p)) fs.rmSync(p, { recursive: true, force: true });
 }
 
+/** Alpine sh breaks on CRLF (then\r). Normalize at pack time — Windows checkout is CRLF. */
+function copyIntoPackage(src, dst) {
+  fs.mkdirSync(path.dirname(dst), { recursive: true });
+  if (dst.endsWith('.sh')) {
+    const text = fs.readFileSync(src, 'utf8').replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    fs.writeFileSync(dst, text, 'utf8');
+  } else {
+    fs.copyFileSync(src, dst);
+  }
+}
+
 console.log(`Sync canonical BFF: ${CANONICAL_API} -> ${PKG_API}`);
 copyTree(CANONICAL_API, PKG_API);
 
@@ -107,11 +118,17 @@ for (const name of applyScripts) {
   const src = path.join(REPO_ROOT, 'scripts/workframe', name);
   const dst = path.join(PKG_ROOT, 'scripts', name);
   if (!fs.existsSync(src)) throw new Error(`Missing apply script: ${src}`);
-  fs.mkdirSync(path.dirname(dst), { recursive: true });
-  fs.copyFileSync(src, dst);
+  copyIntoPackage(src, dst);
   console.log(`Synced ${name} -> package/scripts/`);
 }
 
+for (const sh of fs.readdirSync(path.join(PKG_ROOT, 'scripts')).filter((n) => n.endsWith('.sh'))) {
+  const p = path.join(PKG_ROOT, 'scripts', sh);
+  if (fs.readFileSync(p).includes(0x0d)) {
+    throw new Error(`CRLF remains in package script after sync: ${sh}`);
+  }
+}
+
 const publicDeploySrc = path.join(REPO_ROOT, 'infra/compose/workframe/PUBLIC_DEPLOY.md');
 const publicDeployDst = path.join(PKG_ROOT, 'docs/PUBLIC_DEPLOY.md');
 if (fs.existsSync(publicDeploySrc)) {

package/scripts/verify-public-deploy.sh

@@ -1,105 +1,105 @@
-#!/usr/bin/env bash
-# Fail-closed preflight for WORKFRAME_DEPLOYMENT_MODE=public_multi_user.
-# Usage: bash scripts/workframe/verify-public-deploy.sh [compose-dir]
-set -euo pipefail
-
-ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
-COMPOSE_DIR="${1:-$ROOT/infra/compose/workframe}"
-ENV_FILE="$COMPOSE_DIR/.env"
-COMPOSE_FILE="$COMPOSE_DIR/docker-compose.yml"
-
-fail() { echo "FAIL: $*" >&2; exit 1; }
-warn() { echo "WARN: $*" >&2; }
-ok() { echo "OK: $*"; }
-
-[[ -f "$ENV_FILE" ]] || fail "missing $ENV_FILE"
-[[ -f "$COMPOSE_FILE" ]] || fail "missing $COMPOSE_FILE"
-
-env_val() {
-  local key="$1"
-  grep -E "^${key}=" "$ENV_FILE" | tail -n1 | cut -d= -f2- | tr -d '\r' || true
-}
-
-MODE="$(env_val WORKFRAME_DEPLOYMENT_MODE)"
-MODE="${MODE:-trusted_team}"
-if [[ "$MODE" != "public_multi_user" ]]; then
-  ok "WORKFRAME_DEPLOYMENT_MODE=$MODE (skipping public checks; pass nothing to force public)"
-  exit 0
-fi
-
-ok "checking public_multi_user preflight"
-
-if [[ "$(env_val DEV_LOCAL_UNSAFE)" =~ ^(1|true|yes|on)$ ]]; then
-  fail "DEV_LOCAL_UNSAFE must be off for public_multi_user"
-fi
-if [[ "$(env_val SECURE_MODE)" != "true" ]]; then
-  fail "SECURE_MODE=true required"
-fi
-
-for key in WORKFRAME_SUPERVISOR_TOKEN WORKFRAME_API_TOKEN WORKFRAME_PROXY_TOKEN WORKFRAME_VAULT_KEK \
-  ZK_AUTH_HMAC_KEY ZK_AUTH_ENCRYPTION_KEY ZK_AUTH_SESSION_SECRET \
-  SMTP_HOST SMTP_USER SMTP_PASS EMAIL_FROM; do
-  [[ -n "$(env_val "$key")" ]] || fail "$key is empty"
-done
-
-APP_URL="$(env_val APP_BASE_URL)"
-[[ "$APP_URL" == https://* ]] || fail "APP_BASE_URL must be https:// (got ${APP_URL:-<empty>})"
-
-enc_key="$(env_val ZK_AUTH_ENCRYPTION_KEY)"
-if [[ -n "$enc_key" ]]; then
-  python3 - "$enc_key" <<'PY' || fail "ZK_AUTH_ENCRYPTION_KEY must be base64-encoded 32 bytes (not hex)"
-import base64, sys
-raw = base64.b64decode(sys.argv[1].strip())
-assert len(raw) == 32
-PY
-  ok "ZK_AUTH_ENCRYPTION_KEY format"
-fi
-
-if [[ "$(env_val WORKFRAME_E2E)" =~ ^(1|true|yes|on)$ ]] && [[ "$APP_URL" == https://* ]]; then
-  fail "WORKFRAME_E2E must be off for public HTTPS deploy"
-fi
-
-if grep -A40 '^  gateway:' "$COMPOSE_FILE" | grep -q 'env_file:'; then
-  fail "gateway must not use env_file in docker-compose.yml"
-fi
-if ! grep -q 'control-net' "$COMPOSE_FILE"; then
-  fail "control-net missing from docker-compose.yml"
-fi
-
-UI_PORT="$(env_val WORKFRAME_UI_PORT)"
-UI_PORT="${UI_PORT:-18644}"
-API_PORT="$(env_val WORKFRAME_API_PORT)"
-API_PORT="${API_PORT:-19120}"
-
-if command -v curl >/dev/null 2>&1; then
-  health="$(curl -fsS "http://127.0.0.1:${API_PORT}/api/health" 2>/dev/null || true)"
-  if [[ -z "$health" ]]; then
-    warn "API health unreachable on 127.0.0.1:${API_PORT} (stack down?)"
-  else
-    echo "$health" | grep -q 'public_multi_user' || fail "API health missing deployment_mode public_multi_user"
-    echo "$health" | grep -q '"mode": "secure"' || fail "API not in secure mode"
-    echo "$health" | grep -q '"proxy_token_configured": true' || fail "API proxy_token_configured is false"
-    echo "$health" | grep -q '"vault_envelope": true' || fail "API vault_envelope is false"
-    echo "$health" | grep -q '"docker_sock_on_api": false' || fail "API still has docker.sock mounted"
-    echo "$health" | grep -q 'install_window_open' || warn "API health missing install_window_open"
-    echo "$health" | grep -q 'workframe_e2e' || warn "API health missing workframe_e2e"
-    echo "$health" | grep -q 'dev_local_unsafe' || warn "API health missing dev_local_unsafe"
-    ok "API health"
-  fi
-  dash_code="$(curl -sS -o /dev/null -w '%{http_code}' "http://127.0.0.1:${UI_PORT}/hermes-dashboard/" || true)"
-  [[ "$dash_code" == "403" ]] || warn "hermes-dashboard without session returned $dash_code (expected 403)"
-else
-  warn "curl not found — skipping HTTP checks"
-fi
-
-if command -v docker >/dev/null 2>&1 && docker inspect workframe-gateway >/dev/null 2>&1; then
-  gw_env="$(docker inspect workframe-gateway --format '{{range .Config.Env}}{{println .}}{{end}}')"
-  for marker in WORKFRAME_SUPERVISOR_TOKEN ZK_AUTH_ SMTP_PASS; do
-    echo "$gw_env" | grep -q "$marker" && fail "gateway env contains $marker"
-  done
-  ok "gateway env allowlist"
-else
-  warn "workframe-gateway not running — skipping docker inspect"
-fi
-
-ok "public_multi_user preflight passed"
+#!/usr/bin/env bash
+# Fail-closed preflight for WORKFRAME_DEPLOYMENT_MODE=public_multi_user.
+# Usage: bash scripts/workframe/verify-public-deploy.sh [compose-dir]
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+COMPOSE_DIR="${1:-$ROOT/infra/compose/workframe}"
+ENV_FILE="$COMPOSE_DIR/.env"
+COMPOSE_FILE="$COMPOSE_DIR/docker-compose.yml"
+
+fail() { echo "FAIL: $*" >&2; exit 1; }
+warn() { echo "WARN: $*" >&2; }
+ok() { echo "OK: $*"; }
+
+[[ -f "$ENV_FILE" ]] || fail "missing $ENV_FILE"
+[[ -f "$COMPOSE_FILE" ]] || fail "missing $COMPOSE_FILE"
+
+env_val() {
+  local key="$1"
+  grep -E "^${key}=" "$ENV_FILE" | tail -n1 | cut -d= -f2- | tr -d '\r' || true
+}
+
+MODE="$(env_val WORKFRAME_DEPLOYMENT_MODE)"
+MODE="${MODE:-trusted_team}"
+if [[ "$MODE" != "public_multi_user" ]]; then
+  ok "WORKFRAME_DEPLOYMENT_MODE=$MODE (skipping public checks; pass nothing to force public)"
+  exit 0
+fi
+
+ok "checking public_multi_user preflight"
+
+if [[ "$(env_val DEV_LOCAL_UNSAFE)" =~ ^(1|true|yes|on)$ ]]; then
+  fail "DEV_LOCAL_UNSAFE must be off for public_multi_user"
+fi
+if [[ "$(env_val SECURE_MODE)" != "true" ]]; then
+  fail "SECURE_MODE=true required"
+fi
+
+for key in WORKFRAME_SUPERVISOR_TOKEN WORKFRAME_API_TOKEN WORKFRAME_PROXY_TOKEN WORKFRAME_VAULT_KEK \
+  ZK_AUTH_HMAC_KEY ZK_AUTH_ENCRYPTION_KEY ZK_AUTH_SESSION_SECRET \
+  SMTP_HOST SMTP_USER SMTP_PASS EMAIL_FROM; do
+  [[ -n "$(env_val "$key")" ]] || fail "$key is empty"
+done
+
+APP_URL="$(env_val APP_BASE_URL)"
+[[ "$APP_URL" == https://* ]] || fail "APP_BASE_URL must be https:// (got ${APP_URL:-<empty>})"
+
+enc_key="$(env_val ZK_AUTH_ENCRYPTION_KEY)"
+if [[ -n "$enc_key" ]]; then
+  python3 - "$enc_key" <<'PY' || fail "ZK_AUTH_ENCRYPTION_KEY must be base64-encoded 32 bytes (not hex)"
+import base64, sys
+raw = base64.b64decode(sys.argv[1].strip())
+assert len(raw) == 32
+PY
+  ok "ZK_AUTH_ENCRYPTION_KEY format"
+fi
+
+if [[ "$(env_val WORKFRAME_E2E)" =~ ^(1|true|yes|on)$ ]] && [[ "$APP_URL" == https://* ]]; then
+  fail "WORKFRAME_E2E must be off for public HTTPS deploy"
+fi
+
+if grep -A40 '^  gateway:' "$COMPOSE_FILE" | grep -q 'env_file:'; then
+  fail "gateway must not use env_file in docker-compose.yml"
+fi
+if ! grep -q 'control-net' "$COMPOSE_FILE"; then
+  fail "control-net missing from docker-compose.yml"
+fi
+
+UI_PORT="$(env_val WORKFRAME_UI_PORT)"
+UI_PORT="${UI_PORT:-18644}"
+API_PORT="$(env_val WORKFRAME_API_PORT)"
+API_PORT="${API_PORT:-19120}"
+
+if command -v curl >/dev/null 2>&1; then
+  health="$(curl -fsS "http://127.0.0.1:${API_PORT}/api/health" 2>/dev/null || true)"
+  if [[ -z "$health" ]]; then
+    warn "API health unreachable on 127.0.0.1:${API_PORT} (stack down?)"
+  else
+    echo "$health" | grep -q 'public_multi_user' || fail "API health missing deployment_mode public_multi_user"
+    echo "$health" | grep -q '"mode": "secure"' || fail "API not in secure mode"
+    echo "$health" | grep -q '"proxy_token_configured": true' || fail "API proxy_token_configured is false"
+    echo "$health" | grep -q '"vault_envelope": true' || fail "API vault_envelope is false"
+    echo "$health" | grep -q '"docker_sock_on_api": false' || fail "API still has docker.sock mounted"
+    echo "$health" | grep -q 'install_window_open' || warn "API health missing install_window_open"
+    echo "$health" | grep -q 'workframe_e2e' || warn "API health missing workframe_e2e"
+    echo "$health" | grep -q 'dev_local_unsafe' || warn "API health missing dev_local_unsafe"
+    ok "API health"
+  fi
+  dash_code="$(curl -sS -o /dev/null -w '%{http_code}' "http://127.0.0.1:${UI_PORT}/hermes-dashboard/" || true)"
+  [[ "$dash_code" == "403" ]] || warn "hermes-dashboard without session returned $dash_code (expected 403)"
+else
+  warn "curl not found — skipping HTTP checks"
+fi
+
+if command -v docker >/dev/null 2>&1 && docker inspect workframe-gateway >/dev/null 2>&1; then
+  gw_env="$(docker inspect workframe-gateway --format '{{range .Config.Env}}{{println .}}{{end}}')"
+  for marker in WORKFRAME_SUPERVISOR_TOKEN ZK_AUTH_ SMTP_PASS; do
+    echo "$gw_env" | grep -q "$marker" && fail "gateway env contains $marker"
+  done
+  ok "gateway env allowlist"
+else
+  warn "workframe-gateway not running — skipping docker inspect"
+fi
+
+ok "public_multi_user preflight passed"

package/workframe-api/README.md

@@ -1,28 +1,26 @@
 # Workframe API Service
 
-**Version:** `0.1.0` (`workframe-api-0.1.0`). See `docs/VERSION.md`.
+Python BFF for the Workframe UI. See [docs/VERSION.md](../../docs/VERSION.md) for release version.
 
-Active backend service for the transplanted Workframe vertical slice.
+Canonical implementation — not rewritten into a separate `apps/api` service.
 
-This is intentionally preserved as the current Python BFF instead of being rewritten into `apps/api`.
-
-## Local
+## Local (outside Docker)
 
 ```bash
 cd services/workframe-api
 python3 -m venv .venv
-. .venv/bin/activate
+. .venv/bin/activate   # Windows: .venv\Scripts\activate
 pip install -r requirements.txt
 HOST=0.0.0.0 PORT=8080 HERMES_DATA=/opt/data WORKSPACE=/workspace python3 server.py
 ```
 
-## Runtime state
+## Runtime state (not committed)
 
-Runtime files are intentionally not committed:
+- `data/*.db`, vault files under `WORKFRAME_API_DATA_DIR`
+- Hermes `Agents/` tree on mounted volume
 
-- `data/*.db`
-- `data/.auth_keys`
-- Hermes `Agents/`
-- workspace `Files/`
+## Docs
 
-For VPS deployment, mount clean persistent volumes into `/opt/data` and `/workspace`.
+- [Runtime operations](../../docs/public/runtime-operations.md)
+- [Security](../../docs/public/security.md)
+- [BFF route map](../../docs/public/bff-route-map.md)

package/workframe-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workframe/workframe-api",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": true,
   "type": "module",
   "scripts": {