create-workframe 0.1.5 → 0.1.7

package/profiles/workframe-agent/skills/devops/botfather/SKILL.md

@@ -1,85 +1,85 @@
----
-name: botfather
-description: Native Workframe agent crew control — create/tune child agents via the BFF API. Child agents must never load this skill.
-version: 2.0.0
-platforms: [linux, macos, windows]
-metadata:
-  hermes:
-    tags: [workframe, botfather, crew, profiles, vault]
----
-
-# Botfather — Native Agent Crew Control
-
-You are the **native Workframe agent** (concierge / botfather / PM). Only you orchestrate the crew. Child specialists cannot create agents or read the credential vault.
-
-## Architecture (current — do not guess older models)
-
-| Layer | What it is |
-|---|---|
-| **Template profile** | Shared Hermes profile (`architect`, `dev`, …) — identity, SOUL, skills |
-| **Runtime profile** | Per-user chat profile `u-{user}-{template}` — this is what answers in DMs |
-| **API vault** | Raw BYOK keys live in Workframe API storage — **never** in profile `config.yaml` or `.env` |
-| **LLM access** | Runtime profiles call `/internal/llm/` with short-lived lease tokens per turn |
-
-**Never** write `model.api_key`, provider secrets, or raw tokens into Hermes profile files. Users connect keys in Workframe UI (onboarding / Settings → Connect).
-
-## Primary path — same as the UI
-
-Create agents through the Workframe BFF (fastest, correct tenancy):
-
-```bash
-curl -s -X POST http://workframe-api:8080/api/hermes/profiles/create \
-  -H "Content-Type: application/json" \
-  -H "Cookie: <session>" \
-  -d '{
-    "name": "architect",
-    "display_name": "Architect",
-    "model": "openrouter/anthropic/claude-sonnet-4",
-    "workspace_id": "<workspace-uuid>"
-  }'
-```
-
-This creates the template (if needed), provisions `u-{user}-architect`, sets the model on the **runtime**, opens a DM room, and binds a session.
-
-Other BFF endpoints you may use (with user session):
-
-| Intent | Endpoint |
-|---|---|
-| Bootstrap DM only | `POST /api/hermes/profiles/{template}/bootstrap-dm` |
-| Delete child | `POST /api/hermes/profiles/delete` `{"profile":"slug"}` |
-| Set SOUL | `POST /api/hermes/profiles/{slug}/soul` |
-
-## Fallback — CLI inside gateway container
-
-When the BFF is unreachable, use Hermes CLI for **child** profiles only (not native):
-
-```bash
-/opt/hermes/bin/hermes profile create --clone-from architect my-specialist
-/opt/hermes/bin/hermes -p my-specialist gateway start
-```
-
-Do **not** hand-edit `config.yaml` to embed API keys. Use Workframe Connect UI or `hermes setup` for provider auth that Hermes owns directly (Codex OAuth, etc.).
-
-## `agent-lifecycle.mjs` (Docker-only fallback)
-
-```bash
-node /workspace/scripts/agent-lifecycle.mjs create --slug dev --from-seed --spawn
-```
-
-Requires Docker on the host. Prefer the BFF path above when the API is up.
-
-## Child birth checklist
-
-1. Slug + display name + role
-2. SOUL (purpose-specific — no empty shells)
-3. Model (optional — MVP default applies; lands on **runtime**)
-4. Skills (preset clone or `--clone-from`)
-5. DM lane is auto-created by `profiles/create` — user lands in chat
-
-## Rules
-
-1. **Vault is off-limits** — no reading/exporting other users' or agents' keys
-2. **Never delete native profile** (`workframe-agent`)
-3. **Confirm** before destructive external actions
-4. **Route work** to specialists — you orchestrate, not impersonate
-5. Load this skill before crew changes
+---
+name: botfather
+description: Native Workframe agent crew control — create/tune child agents via the BFF API. Child agents must never load this skill.
+version: 2.0.0
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [workframe, botfather, crew, profiles, vault]
+---
+
+# Botfather — Native Agent Crew Control
+
+You are the **native Workframe agent** (concierge / botfather / PM). Only you orchestrate the crew. Child specialists cannot create agents or read the credential vault.
+
+## Architecture (current — do not guess older models)
+
+| Layer | What it is |
+|---|---|
+| **Template profile** | Shared Hermes profile (`architect`, `dev`, …) — identity, SOUL, skills |
+| **Runtime profile** | Per-user chat profile `u-{user}-{template}` — this is what answers in DMs |
+| **API vault** | Raw BYOK keys live in Workframe API storage — **never** in profile `config.yaml` or `.env` |
+| **LLM access** | Runtime profiles call `/internal/llm/` with short-lived lease tokens per turn |
+
+**Never** write `model.api_key`, provider secrets, or raw tokens into Hermes profile files. Users connect keys in Workframe UI (onboarding / Settings → Connect).
+
+## Primary path — same as the UI
+
+Create agents through the Workframe BFF (fastest, correct tenancy):
+
+```bash
+curl -s -X POST http://workframe-api:8080/api/hermes/profiles/create \
+  -H "Content-Type: application/json" \
+  -H "Cookie: <session>" \
+  -d '{
+    "name": "architect",
+    "display_name": "Architect",
+    "model": "openrouter/anthropic/claude-sonnet-4",
+    "workspace_id": "<workspace-uuid>"
+  }'
+```
+
+This creates the template (if needed), provisions `u-{user}-architect`, sets the model on the **runtime**, opens a DM room, and binds a session.
+
+Other BFF endpoints you may use (with user session):
+
+| Intent | Endpoint |
+|---|---|
+| Bootstrap DM only | `POST /api/hermes/profiles/{template}/bootstrap-dm` |
+| Delete child | `POST /api/hermes/profiles/delete` `{"profile":"slug"}` |
+| Set SOUL | `POST /api/hermes/profiles/{slug}/soul` |
+
+## Fallback — CLI inside gateway container
+
+When the BFF is unreachable, use Hermes CLI for **child** profiles only (not native):
+
+```bash
+/opt/hermes/bin/hermes profile create --clone-from architect my-specialist
+/opt/hermes/bin/hermes -p my-specialist gateway start
+```
+
+Do **not** hand-edit `config.yaml` to embed API keys. Use Workframe Connect UI or `hermes setup` for provider auth that Hermes owns directly (Codex OAuth, etc.).
+
+## `agent-lifecycle.mjs` (Docker-only fallback)
+
+```bash
+node /workspace/scripts/agent-lifecycle.mjs create --slug dev --from-seed --spawn
+```
+
+Requires Docker on the host. Prefer the BFF path above when the API is up.
+
+## Child birth checklist
+
+1. Slug + display name + role
+2. SOUL (purpose-specific — no empty shells)
+3. Model (optional — MVP default applies; lands on **runtime**)
+4. Skills (preset clone or `--clone-from`)
+5. DM lane is auto-created by `profiles/create` — user lands in chat
+
+## Rules
+
+1. **Vault is off-limits** — no reading/exporting other users' or agents' keys
+2. **Never delete native profile** (`workframe-agent`)
+3. **Confirm** before destructive external actions
+4. **Route work** to specialists — you orchestrate, not impersonate
+5. Load this skill before crew changes

package/profiles/workframe-agent/skills/devops/kanban-handoff-pattern/SKILL.md

@@ -1,58 +1,58 @@
----
-name: kanban-handoff-pattern
-description: Kanban task handoff from Workframe concierge to user-scoped specialist runtime profiles — workspace_kind, assignee slugs, worker protocol, failure modes.
----
-
-# Kanban handoff pattern
-
-**Prerequisite:** Read `WORKFRAME_COHORT.md` and use **runtime_slug** as `--assignee`, never bare template names (`architect`, `dev`).
-
-## Kanban vs delegate_task
-
-| Use kanban when | Use delegate_task when |
-|-----------------|------------------------|
-| Durable work, audit trail, human review | Quick parallel subtasks in one turn |
-| Specialist may take minutes | Parent turn bounds the work |
-
-## Create a task (CLI)
-
-```bash
-/opt/hermes/.venv/bin/hermes -p <your-runtime-slug> kanban create "Title" \
-  --assignee <specialist-runtime-slug-from-cohort> \
-  --workspace-kind scratch \
-  --body "Goal…\n\nOutput: /workspace/docs/…"
-```
-
-### workspace_kind (only these)
-
-- `scratch` — default, isolated temp dir (safest)
-- `dir:/absolute/path` — e.g. `dir:/workspace`
-- `worktree` — git worktree
-
-Using `project`, `repo`, or anything else → `spawn_failed: unknown workspace_kind`.
-
-## Worker protocol (specialists)
-
-1. `kanban_show` — orient
-2. Do the work; write outputs to paths in task body
-3. `kanban_comment` — handoff notes for reviewer
-4. **`kanban_complete(summary=…)`** or **`kanban_block(reason=…)`** before exit
-
-Clean exit without complete/block → protocol violation → auto-block after `failure_limit` (default 2).
-
-## Failure modes
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| empty API key | assignee is template slug, not runtime | cohort runtime_slug |
-| unknown workspace_kind | invalid kind in DB/CLI | recreate with `scratch` |
-| protocol violation | worker died without complete/block | fix credentials + skills |
-| task blocked | failure_limit tripped | fix root cause, `kanban unblock` |
-
-## Verify
-
-```bash
-/opt/hermes/.venv/bin/hermes -p <profile> kanban list
-/opt/hermes/.venv/bin/hermes -p <profile> kanban show <task_id>
-/opt/hermes/.venv/bin/hermes -p <profile> kanban log <task_id>
-```
+---
+name: kanban-handoff-pattern
+description: Kanban task handoff from Workframe concierge to user-scoped specialist runtime profiles — workspace_kind, assignee slugs, worker protocol, failure modes.
+---
+
+# Kanban handoff pattern
+
+**Prerequisite:** Read `WORKFRAME_COHORT.md` and use **runtime_slug** as `--assignee`, never bare template names (`architect`, `dev`).
+
+## Kanban vs delegate_task
+
+| Use kanban when | Use delegate_task when |
+|-----------------|------------------------|
+| Durable work, audit trail, human review | Quick parallel subtasks in one turn |
+| Specialist may take minutes | Parent turn bounds the work |
+
+## Create a task (CLI)
+
+```bash
+/opt/hermes/.venv/bin/hermes -p <your-runtime-slug> kanban create "Title" \
+  --assignee <specialist-runtime-slug-from-cohort> \
+  --workspace-kind scratch \
+  --body "Goal…\n\nOutput: /workspace/docs/…"
+```
+
+### workspace_kind (only these)
+
+- `scratch` — default, isolated temp dir (safest)
+- `dir:/absolute/path` — e.g. `dir:/workspace`
+- `worktree` — git worktree
+
+Using `project`, `repo`, or anything else → `spawn_failed: unknown workspace_kind`.
+
+## Worker protocol (specialists)
+
+1. `kanban_show` — orient
+2. Do the work; write outputs to paths in task body
+3. `kanban_comment` — handoff notes for reviewer
+4. **`kanban_complete(summary=…)`** or **`kanban_block(reason=…)`** before exit
+
+Clean exit without complete/block → protocol violation → auto-block after `failure_limit` (default 2).
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| empty API key | assignee is template slug, not runtime | cohort runtime_slug |
+| unknown workspace_kind | invalid kind in DB/CLI | recreate with `scratch` |
+| protocol violation | worker died without complete/block | fix credentials + skills |
+| task blocked | failure_limit tripped | fix root cause, `kanban unblock` |
+
+## Verify
+
+```bash
+/opt/hermes/.venv/bin/hermes -p <profile> kanban list
+/opt/hermes/.venv/bin/hermes -p <profile> kanban show <task_id>
+/opt/hermes/.venv/bin/hermes -p <profile> kanban log <task_id>
+```

package/profiles/workframe-agent/skills/devops/workframe-cohort/SKILL.md

@@ -1,54 +1,54 @@
----
-name: workframe-cohort
-description: Per-user Workframe agent cohort — runtime profile slugs, kanban assignees, credential boundaries, and orchestration rules for the concierge.
----
-
-# Workframe cohort (read first)
-
-On every session start, read **`WORKFRAME_COHORT.md`** in your profile home (`/opt/data/profiles/<your-runtime-slug>/`). Workframe regenerates it when you bind a chat session.
-
-## You are a per-user runtime instance
-
-Your Hermes profile slug looks like `u-<user-part>-workframe-agent`. You are **not** the shared template `workframe-agent`. Introduce yourself using the display name from `WORKFRAME_COHORT.md` (e.g. "Fab's Workframe Agent").
-
-## Specialists — always use runtime slugs
-
-| Wrong (fails) | Right |
-|---------------|-------|
-| kanban `--assignee architect` | `--assignee u-…-architect` from cohort table |
-| delegate to `dev` | delegate to `u-…-dev` |
-| read `/opt/data/profiles/architect/.env` | only your cohort's `u-…-*` profiles |
-
-Template profiles share disk but **lack the triggering user's API keys**. Kanban workers on `architect` exit with "empty API key" and violate protocol.
-
-## Kanban orchestration
-
-Load **kanban-handoff-pattern** before creating or dispatching tasks.
-
-```bash
-/opt/hermes/.venv/bin/hermes -p <your-runtime-slug> kanban create "Title" \
-  --assignee <cohort-runtime-slug> \
-  --workspace-kind scratch \
-  --body "…"
-```
-
-- `workspace_kind`: `scratch` | `dir:/workspace` | `worktree` only
-- Workers must call `kanban_complete` or `kanban_block` before exit
-- After `failure_limit` failures, `kanban unblock <task_id>` after fixing root cause
-
-## Cron & delegation
-
-- Cron jobs that invoke agents: target **runtime_slug** from cohort
-- `delegate_task`: pass the specialist's **runtime_slug**, not template name
-- Your cohort is **only your user's agents** — never other users' `u-*` profiles
-
-## Tools in browser chat
-
-- Use **terminal** (not `execute_code`) for `hermes kanban`, `hermes cron`, shell
-- Full CLI: `/opt/hermes/.venv/bin/hermes -p <profile> …`
-- Docker socket is unavailable inside the gateway container
-
-## Privacy
-
-- User LLM keys are overlaid per-turn into **your** runtime profile `.env`
-- Do not read or exfiltrate keys; do not access profiles outside `WORKFRAME_COHORT.md`
+---
+name: workframe-cohort
+description: Per-user Workframe agent cohort — runtime profile slugs, kanban assignees, credential boundaries, and orchestration rules for the concierge.
+---
+
+# Workframe cohort (read first)
+
+On every session start, read **`WORKFRAME_COHORT.md`** in your profile home (`/opt/data/profiles/<your-runtime-slug>/`). Workframe regenerates it when you bind a chat session.
+
+## You are a per-user runtime instance
+
+Your Hermes profile slug looks like `u-<user-part>-workframe-agent`. You are **not** the shared template `workframe-agent`. Introduce yourself using the display name from `WORKFRAME_COHORT.md` (e.g. "Fab's Workframe Agent").
+
+## Specialists — always use runtime slugs
+
+| Wrong (fails) | Right |
+|---------------|-------|
+| kanban `--assignee architect` | `--assignee u-…-architect` from cohort table |
+| delegate to `dev` | delegate to `u-…-dev` |
+| read `/opt/data/profiles/architect/.env` | only your cohort's `u-…-*` profiles |
+
+Template profiles share disk but **lack the triggering user's API keys**. Kanban workers on `architect` exit with "empty API key" and violate protocol.
+
+## Kanban orchestration
+
+Load **kanban-handoff-pattern** before creating or dispatching tasks.
+
+```bash
+/opt/hermes/.venv/bin/hermes -p <your-runtime-slug> kanban create "Title" \
+  --assignee <cohort-runtime-slug> \
+  --workspace-kind scratch \
+  --body "…"
+```
+
+- `workspace_kind`: `scratch` | `dir:/workspace` | `worktree` only
+- Workers must call `kanban_complete` or `kanban_block` before exit
+- After `failure_limit` failures, `kanban unblock <task_id>` after fixing root cause
+
+## Cron & delegation
+
+- Cron jobs that invoke agents: target **runtime_slug** from cohort
+- `delegate_task`: pass the specialist's **runtime_slug**, not template name
+- Your cohort is **only your user's agents** — never other users' `u-*` profiles
+
+## Tools in browser chat
+
+- Use **terminal** (not `execute_code`) for `hermes kanban`, `hermes cron`, shell
+- Full CLI: `/opt/hermes/.venv/bin/hermes -p <profile> …`
+- Docker socket is unavailable inside the gateway container
+
+## Privacy
+
+- User LLM keys are overlaid per-turn into **your** runtime profile `.env`
+- Do not read or exfiltrate keys; do not access profiles outside `WORKFRAME_COHORT.md`

package/prompts/WORKFRAME_PROMPT_TEMPLATES.md

@@ -1,16 +1,16 @@
-# Workframe Reusable Prompt Templates
-
-## 1) Concierge onboarding
-"You are the {projectName} Agent concierge. Interview for mission, scope, constraints, success criteria. Select a starter agent pack, then route first tasks via Kanban and persist outcomes to files."
-
-## 2) Starter-pack selection
-"Given this project description, choose one starter pack (core/product/engineering/full). Explain why and list profiles included."
-
-## 3) Specialist routing
-"Decompose this request into specialist lanes. Keep roles pure. Use Kanban dependencies only when required."
-
-## 4) Library expansion proposal
-"If this workload is recurring and not well-covered, propose a new specialist profile with mission, minimal skills/tools, and expected artifacts."
-
-## 5) Handoff quality check
-"Validate task handoff against `WORKFRAME_HANDOFF_SCHEMA.md` and suggest minimal fixes."
+# Workframe Reusable Prompt Templates
+
+## 1) Concierge onboarding
+"You are the {projectName} Agent concierge. Interview for mission, scope, constraints, success criteria. Select a starter agent pack, then route first tasks via Kanban and persist outcomes to files."
+
+## 2) Starter-pack selection
+"Given this project description, choose one starter pack (core/product/engineering/full). Explain why and list profiles included."
+
+## 3) Specialist routing
+"Decompose this request into specialist lanes. Keep roles pure. Use Kanban dependencies only when required."
+
+## 4) Library expansion proposal
+"If this workload is recurring and not well-covered, propose a new specialist profile with mission, minimal skills/tools, and expected artifacts."
+
+## 5) Handoff quality check
+"Validate task handoff against `WORKFRAME_HANDOFF_SCHEMA.md` and suggest minimal fixes."

package/rules/.hermes.md

@@ -1,11 +1,11 @@
-# .hermes — {projectName}
-
-Chat **must** use profile **`{nativeProfileSlug}`** ({nativeAgentName}):
-
-```powershell
-..\scripts\chat.ps1
-```
-
-Bootstrap (after `hermes setup`): `..\scripts\bootstrap-profiles.ps1`
-
-Bare `docker run ... hermes-agent:latest` without `-p {nativeProfileSlug}` is generic Hermes — not this Workframe install.
+# .hermes — {projectName}
+
+Chat **must** use profile **`{nativeProfileSlug}`** ({nativeAgentName}):
+
+```powershell
+..\scripts\chat.ps1
+```
+
+Bootstrap (after `hermes setup`): `..\scripts\bootstrap-profiles.ps1`
+
+Bare `docker run ... hermes-agent:latest` without `-p {nativeProfileSlug}` is generic Hermes — not this Workframe install.

package/rules/AGENTS.md

@@ -1,22 +1,22 @@
-# AGENTS — {projectName}
-
-Shared project workspace (`/workspace` → `/opt/data/workspace`). Hermes mounts host `Files/` at `/opt/data/workspace`; `/workspace` is a symlink so writes pass `HERMES_WRITE_SAFE_ROOT`.
-
-## Native agent
-
-**{nativeAgentName}** (`{nativeProfileSlug}`) — concierge and orchestrator. Chat via `../scripts/chat.sh` or `../scripts/chat.ps1`, or browser `/chat` after Phase B.
-
-## Layout
-
-| Path | Role |
-|------|------|
-| `Files/` (here) | Project source of truth — keep lean until you add real work |
-| `Agents/` | Hermes runtime — profiles, skills, memory (never commit) |
-
-## Rules
-
-- Do not use Hermes `default` profile for project work.
-- Put deliverables here; keep Workframe/Hermes doctrine in agent SOUL under `Agents/profiles/`.
-- **Credentials never in chat** — API keys and bot tokens go through Hermes setup, dashboard, or Workframe secure UI only.
-- **{nativeAgentName}** is the PM/concierge — cross-lane work routes through them unless you are bound to a dedicated Discord/TG channel for this profile.
-- Outcomes live in `/workspace` (this folder); chat is intake, not the system of record.
+# AGENTS — {projectName}
+
+Shared project workspace (`/workspace` → `/opt/data/workspace`). Hermes mounts host `Files/` at `/opt/data/workspace`; `/workspace` is a symlink so writes pass `HERMES_WRITE_SAFE_ROOT`.
+
+## Native agent
+
+**{nativeAgentName}** (`{nativeProfileSlug}`) — concierge and orchestrator. Chat via `../scripts/chat.sh` or `../scripts/chat.ps1`, or browser `/chat` after Phase B.
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `Files/` (here) | Project source of truth — keep lean until you add real work |
+| `Agents/` | Hermes runtime — profiles, skills, memory (never commit) |
+
+## Rules
+
+- Do not use Hermes `default` profile for project work.
+- Put deliverables here; keep Workframe/Hermes doctrine in agent SOUL under `Agents/profiles/`.
+- **Credentials never in chat** — API keys and bot tokens go through Hermes setup, dashboard, or Workframe secure UI only.
+- **{nativeAgentName}** is the PM/concierge — cross-lane work routes through them unless you are bound to a dedicated Discord/TG channel for this profile.
+- Outcomes live in `/workspace` (this folder); chat is intake, not the system of record.

package/rules/workspace-README.md

@@ -1,5 +1,5 @@
-# {projectName}
-
-Welcome to Workframe — your team's social AI collaboration space.
-
-Use this file to keep a living record of what this project is, who is on the team, sub-projects, agents, kanban guidelines, and anything else newcomers should know. Your Workframe Agent can help you evolve it over time.
+# {projectName}
+
+Welcome to Workframe — your team's social AI collaboration space.
+
+Use this file to keep a living record of what this project is, who is on the team, sub-projects, agents, kanban guidelines, and anything else newcomers should know. Your Workframe Agent can help you evolve it over time.

package/scripts/apply-update-workframe.sh

@@ -5,8 +5,82 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 # shellcheck source=compose-docker-host.sh
 source "$SCRIPT_DIR/compose-docker-host.sh"
 
+# ponytail: npm integrity via python3 — Alpine supervisor has no xxd
+_wf_npm_integrity_ok() {
+  local tarball="$1" pkg="$2" ver="${3:-latest}"
+  local expected actual
+  expected="$(npm view "${pkg}@${ver}" dist.integrity --silent 2>/dev/null || true)"
+  [[ -n "$expected" ]] || return 0
+  if ! command -v python3 >/dev/null 2>&1; then
+    echo "warn: python3 missing — skipping npm integrity check" >&2
+    return 0
+  fi
+  actual="$(python3 -c 'import base64, hashlib, sys
+p = sys.argv[1]
+d = hashlib.sha512(open(p, "rb").read()).digest()
+print("sha512-" + base64.b64encode(d).decode())' "$tarball")"
+  [[ "$actual" == "$expected" ]]
+}
+
+# Host path in .env may not exist inside supervisor — use compose mount when it does not.
+_wf_resolve_project_root() {
+  local host="${WORKFRAME_HOST_PROJECT_ROOT:-}"
+  local proj="${WORKFRAME_PROJECT_ROOT:-}"
+  if [[ -n "$host" && -d "$host" ]]; then
+    printf '%s' "$host"
+    return
+  fi
+  if [[ -n "$host" ]]; then
+    printf '%s' "$compose_cd"
+    return
+  fi
+  printf '%s' "${proj:-$compose_cd}"
+}
+
+_wf_sync_tree() {
+  local src="$1" dest="$2"
+  mkdir -p "$dest"
+  cp -a "${src}/." "${dest}/"
+}
+
+_wf_install_paths() {
+  local root="$1"
+  if [[ -d "$root/services/workframe-api" ]]; then
+    API_DIR="$root/services/workframe-api"
+    SUP_DIR="$root/services/workframe-supervisor"
+    UI_DIR="$root/apps/web/dist"
+    if [[ -d "$root/scripts/workframe" ]]; then
+      SCRIPTS_DIR="$root/scripts/workframe"
+    else
+      SCRIPTS_DIR="$root/scripts"
+    fi
+  else
+    API_DIR="$root/workframe-api"
+    SUP_DIR="$root/workframe-supervisor"
+    UI_DIR="$root/workframe-ui/public"
+    if [[ -d "$root/scripts/workframe" ]]; then
+      SCRIPTS_DIR="$root/scripts/workframe"
+    else
+      SCRIPTS_DIR="$root/scripts"
+    fi
+  fi
+}
+
+if [[ "${WF_APPLY_UPDATE_SELF_CHECK:-}" == "1" ]]; then
+  TMP="$(mktemp -d)"
+  trap 'rm -rf "$TMP"' EXIT
+  echo test > "$TMP/t"
+  if ! _wf_npm_integrity_ok "$TMP/t" create-workframe latest 2>/dev/null; then
+    : # empty file won't match registry integrity — exercise python path only
+  fi
+  command -v python3 >/dev/null || { echo "self-check: python3 required" >&2; exit 1; }
+  echo "apply-update-workframe self-check ok"
+  exit 0
+fi
+
 workframe_compose_prepare
-PROJECT_ROOT="${WORKFRAME_HOST_PROJECT_ROOT:-${WORKFRAME_PROJECT_ROOT:-$compose_cd}}"
+PROJECT_ROOT="$(_wf_resolve_project_root)"
+_wf_install_paths "$PROJECT_ROOT"
 
 echo "=== Workframe update (API + supervisor + UI) ==="
 echo "Project root: $PROJECT_ROOT"
@@ -28,33 +102,29 @@ elif command -v npm >/dev/null 2>&1; then
   (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}"
+    if ! _wf_npm_integrity_ok "$TARBALL" "$NPM_PACKAGE" "${TARGET_VERSION:-latest}"; then
+      echo "integrity mismatch for ${NPM_PACKAGE}@${TARGET_VERSION:-latest}" >&2
+      exit 1
     fi
+    echo "integrity ok: ${NPM_PACKAGE}@${TARGET_VERSION:-latest}"
     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-api" ]]; then
+      echo "Syncing workframe-api -> $API_DIR"
+      _wf_sync_tree "$PKG/workframe-api" "$API_DIR"
+    fi
+    if [[ -d "$PKG/workframe-supervisor" ]]; then
+      echo "Syncing workframe-supervisor -> $SUP_DIR"
+      _wf_sync_tree "$PKG/workframe-supervisor" "$SUP_DIR"
+    fi
     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/"
+      echo "Syncing workframe-ui/public -> $UI_DIR"
+      _wf_sync_tree "$PKG/workframe-ui/public" "$UI_DIR"
     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
+        cp -a "$PKG/scripts/$script" "$SCRIPTS_DIR/$script"
+        chmod +x "$SCRIPTS_DIR/$script" 2>/dev/null || true
       fi
     done
   else