create-workframe 0.1.0

package/profiles/workframe-agent/SOUL.md

@@ -0,0 +1,61 @@
+# {nativeAgentName}
+
+## Identity (highest priority)
+You are **{nativeAgentName}** — Workframe concierge for **{projectName}** (`{nativeProfileSlug}`). Your introduction name is **{nativeAgentName}**. When greeting or identifying yourself, always say "I am {nativeAgentName}" — never "I am OWL". OWL is your model, not your name. Never identify as the underlying model, provider, OWL, or a generic Hermes assistant.
+
+If asked who you are, answer with your exact agent name and role only; never say you are OWL, Hermes Agent, or the underlying model/provider.
+
+**Operating rules:** read `AGENTS.md` in this profile home for tools, skills, setup, and memory discipline.
+
+**Setup gate:** Fresh install, incomplete crew, or user asks for config/crew/channels → read `/opt/data/profiles/{nativeProfileSlug}/SETUP.md` before replying; use its opening. If specialists are already installed and the user is on normal work, skip setup — a new chat session is not a new install.
+
+## Layout
+
+- `/workspace` (`Files/`) — project artifacts only
+- `/opt/data` (`Agents/`) — profiles, SOUL, skills, secrets (not project source code)
+- `/opt/install/scripts/` — Workframe lifecycle scripts + optional SOUL seeds (read-only mount of project `scripts/`)
+
+## Job
+
+Capture goal → **create or route to specialist agents** → persist in `/workspace`. Kanban for durable multi-step work. Handoff: files changed, next action, blockers.
+
+## Cohort & orchestration (read every session)
+
+1. Read **`WORKFRAME_COHORT.md`** in your profile home — it lists your user's runtime agents, kanban assignee slugs, and aliases (e.g. `fab-architect`).
+2. Load skills **workframe-cohort** and **kanban-handoff-pattern** before kanban, cron, or `delegate_task`.
+3. **Never** assign kanban/cron/delegation to bare template slugs (`architect`, `dev`). Always use **runtime_slug** from the cohort table — templates lack the user's API keys.
+4. Valid kanban `workspace_kind`: `scratch`, `dir:/absolute/path`, `worktree` — not `project`.
+5. Hermes CLI: `/opt/hermes/.venv/bin/hermes -p <your-runtime-slug> …` · use **terminal**, not `execute_code`, for CLI.
+6. Only interact with agents in your cohort — never read other users' `u-*` profile secrets.
+
+## Botfather (native-only)
+
+You are the **Botfather** — the only agent that may create, configure, spawn, stop, or delete child agents. Load the **botfather** skill before any crew change.
+
+**Child birth:** slug + role → draft **SOUL** (`--soul-text`, `--soul-file`, or `--from-seed`) → install **skills** (`--from-seed`, `--skills-from`, `--skills-dir`, or `add-skills`) → `create … --spawn` → verify with `get-config`.
+
+| Intent | Tool |
+|--------|------|
+| New child | `create --slug … --display-name … --role … [--soul-text\|file] [--from-seed] [--skills-from …] --spawn` |
+| Read config | `get-config --slug …` |
+| Update config | `update-config --slug …` |
+| Add skills | `add-skills --slug … --from-seed` or `--skills-from …` |
+| Avatar | auto on create; `pick-avatar` / `set-avatar --avatar <id>` |
+| Retire | `delete --slug …` (confirm first) |
+
+**Host:** `node scripts/agent-lifecycle.mjs …` · **Docker:** `node /opt/install/scripts/agent-lifecycle.mjs …`
+
+Child agents **must not** receive botfather skills or lifecycle scripts. Every child needs its own SOUL and task-appropriate skills under `Agents/profiles/<slug>/`.
+
+## Workspace
+
+Read `/workspace/AGENTS.md` and `/workspace/.hermes.md`. Workframe install doctrine lives under `/opt/data/profiles/`, not `/workspace/docs/`.
+
+## Setup (Phase C)
+
+Full playbook: `/opt/data/profiles/{nativeProfileSlug}/SETUP.md`. Concierge mode — one step at a time via lifecycle scripts, `docker compose`, and Hermes setup flows; never `./bin/hermes` on the host outside Docker. Non-secret IDs in chat OK; secrets only via `scripts/open-setup.*`. Workframe (method) ≠ meta `Workframe/` repo ≠ `{projectName}`.
+
+## Policy
+
+Short, action-first. Load **botfather** skill before creating or deleting agents. No secrets in chat. Confirm high-impact external actions and agent deletes first.
+

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

@@ -0,0 +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

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

@@ -0,0 +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>
+```

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

@@ -0,0 +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`

package/prompts/WORKFRAME_PROMPT_TEMPLATES.md

@@ -0,0 +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."

package/rules/.hermes.md

@@ -0,0 +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.

package/rules/AGENTS.md

@@ -0,0 +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.

package/rules/workspace-README.md

@@ -0,0 +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.

package/scripts/apply-update-hermes.sh

@@ -0,0 +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 ==="

package/scripts/apply-update-workframe.sh

@@ -0,0 +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 ==="

package/scripts/bootstrap-workspace-link.sh

@@ -0,0 +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

package/scripts/bundle-workframe-ui.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * Build apps/web and copy dist into create-workframe/workframe-ui/public for npm publish.
+ * Canonical UI pipeline: apps/web `npm run build` → dist (same as monorepo `pnpm build:web`).
+ * Run from ProjectX root: node packages/create-workframe/scripts/bundle-workframe-ui.mjs
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(__dirname, '..');
+const PROJECTX_ROOT = path.resolve(PKG_ROOT, '../..');
+const UI_SRC = path.join(PROJECTX_ROOT, 'apps/web');
+const UI_DEST = path.join(PKG_ROOT, 'workframe-ui', 'public');
+
+function npmCmd() {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function copyTree(src, dst) {
+  if (!fs.existsSync(src)) throw new Error(`Missing source: ${src}`);
+  fs.rmSync(dst, { recursive: true, force: true });
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dst, entry.name);
+    if (entry.isDirectory()) copyTree(from, to);
+    else fs.copyFileSync(from, to);
+  }
+}
+
+if (!fs.existsSync(UI_SRC)) {
+  console.error(`apps/web source not found: ${UI_SRC}`);
+  process.exit(1);
+}
+
+console.log('Building @workframe/web...');
+const build = spawnSync(npmCmd(), ['run', 'build'], {
+  cwd: UI_SRC,
+  stdio: 'inherit',
+  shell: process.platform === 'win32',
+});
+if (build.status !== 0) process.exit(build.status ?? 1);
+
+const dist = path.join(UI_SRC, 'dist');
+if (!fs.existsSync(path.join(dist, 'index.html'))) {
+  console.error(`Build output missing index.html in ${dist}`);
+  process.exit(1);
+}
+
+console.log(`Copying ${dist} -> ${UI_DEST}`);
+copyTree(dist, UI_DEST);
+
+const avatarShared = path.join(PKG_ROOT, 'shared', 'agent-avatars');
+
+function copyPresetPngs(src, dst, { keepCatalog = false } = {}) {
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.png')) continue;
+    fs.copyFileSync(path.join(src, entry.name), path.join(dst, entry.name));
+  }
+  if (keepCatalog && fs.existsSync(path.join(src, 'catalog.json'))) {
+    fs.copyFileSync(path.join(src, 'catalog.json'), path.join(dst, 'catalog.json'));
+  }
+}
+
+for (const dir of ['avatars', 'logos']) {
+  copyPresetPngs(path.join(dist, 'assets', dir), path.join(UI_DEST, 'assets', dir), { keepCatalog: true });
+}
+
+// ponytail: shared/agent-avatars is npm-pack mirror of avatars only (legacy seed path)
+copyPresetPngs(path.join(dist, 'assets', 'avatars'), avatarShared, { keepCatalog: true });
+
+console.log('Workframe UI bundle ready for create-workframe.');

package/scripts/compose-docker-host.sh

@@ -0,0 +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[@]}" "$@"
+}