create-workframe 0.1.0

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

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

package/scripts/lib/install-identity.mjs

@@ -0,0 +1,212 @@
+/**
+ * Per-install identity: slot-based localhost ports + stable install id for cookies.
+ *
+ * Slot N (1–99) → host ports N*10000 + tail:
+ *   gateway 8642, dashboard 9119, api 9120, ui 8644, supervisor 8090
+ *   slot 1 → 18642, 19119, 19120, 18644, 18090
+ *   slot 2 → 28642, 29119, 29120, 28644, 28090
+ *
+ * ponytail: cookies use WORKFRAME_INSTALL_ID (not display name); auth DB is per install so same email can sign into many.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+
+export const PORT_TAIL = Object.freeze({
+  gateway: 8642,
+  dashboard: 9119,
+  api: 9120,
+  ui: 8644,
+  supervisor: 8090,
+});
+
+export function portsForSlot(slot) {
+  const n = Number(slot);
+  if (!Number.isInteger(n) || n < 1 || n > 99) {
+    throw new Error(`WORKFRAME_SLOT must be 1–99, got ${slot}`);
+  }
+  const base = n * 10_000;
+  return {
+    slot: n,
+    gateway: base + PORT_TAIL.gateway,
+    dashboard: base + PORT_TAIL.dashboard,
+    api: base + PORT_TAIL.api,
+    ui: base + PORT_TAIL.ui,
+    supervisor: base + PORT_TAIL.supervisor,
+  };
+}
+
+export function generateSupervisorToken() {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+export function generateProxyToken() {
+  return crypto.randomBytes(32).toString('base64url');
+}
+
+export function generateApiToken() {
+  return crypto.randomBytes(32).toString('base64url');
+}
+
+export function generateDashboardAuthPassword() {
+  return crypto.randomBytes(18).toString('base64url');
+}
+
+export function generateDashboardAuthSecret() {
+  return crypto.randomBytes(24).toString('hex');
+}
+
+export function generateVaultKekB64() {
+  return crypto.randomBytes(32).toString('base64');
+}
+
+export function generateInstallId() {
+  return `wf_${crypto.randomBytes(6).toString('hex')}`;
+}
+
+export function sessionCookieNameFromEnv(env = process.env) {
+  const installId = String(env.WORKFRAME_INSTALL_ID || '').trim();
+  if (installId) {
+    const safe = installId.replace(/[^a-zA-Z0-9_-]+/g, '_').replace(/^_+|_+$/g, '');
+    if (safe) return `${safe}_session`;
+  }
+  const slug = String(env.WORKFRAME_PROJECT || 'workframe')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '') || 'workframe';
+  return `wf_${slug}_session`;
+}
+
+function portTaken(port, host = '127.0.0.1') {
+  return new Promise((resolve) => {
+    const socket = net.createConnection({ port, host });
+    const done = (taken) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(taken);
+    };
+    socket.setTimeout(400);
+    socket.once('connect', () => done(true));
+    socket.once('timeout', () => done(false));
+    socket.once('error', () => done(false));
+  });
+}
+
+async function slotPortsFree(slot, host = '127.0.0.1') {
+  const ports = portsForSlot(slot);
+  for (const key of ['gateway', 'dashboard', 'api', 'ui']) {
+    if (await portTaken(ports[key], host)) return false;
+  }
+  return true;
+}
+
+/**
+ * Pick the first free slot, or use preferredSlot when its ports are free.
+ */
+export async function allocateInstall({
+  projectName,
+  preferredSlot = null,
+  maxSlot = 9,
+  host = '127.0.0.1',
+  installId = null,
+} = {}) {
+  if (preferredSlot != null) {
+    const slot = Number(preferredSlot);
+    if (!await slotPortsFree(slot, host)) {
+      throw new Error(
+        `WORKFRAME_SLOT ${slot} ports are in use (${JSON.stringify(portsForSlot(slot))})`,
+      );
+    }
+    return {
+      installId: installId || generateInstallId(),
+      projectName,
+      slot,
+      ports: portsForSlot(slot),
+    };
+  }
+
+  for (let slot = 1; slot <= maxSlot; slot++) {
+    if (await slotPortsFree(slot, host)) {
+      return {
+        installId: installId || generateInstallId(),
+        projectName,
+        slot,
+        ports: portsForSlot(slot),
+      };
+    }
+  }
+  throw new Error(`No free Workframe install slot (1–${maxSlot}) on ${host}`);
+}
+
+export function envFileLines(install, { example = false, nativeProfile = '', deploy = 'docker', hermesHome = '' } = {}) {
+  const header = example
+    ? '# Copy to .env — one install = one slot + one WORKFRAME_INSTALL_ID.\n# Same email may be used across installs; each has its own auth DB.\n'
+    : '# Local Workframe install identity (.env is gitignored).\n';
+  const { ports, installId, slot } = install;
+  const deployLine = deploy === 'native' ? 'WORKFRAME_DEPLOY=native\n' : 'WORKFRAME_DEPLOY=docker\n';
+  const hermesLine = hermesHome ? `HERMES_DATA=${hermesHome.replace(/\\/g, '/')}\n` : '';
+  return `${header}${deployLine}${hermesLine}WORKFRAME_INSTALL_ID=${installId}
+WORKFRAME_SLOT=${slot}
+WORKFRAME_PROJECT=${install.projectName}
+WORKFRAME_GATEWAY_PORT=${ports.gateway}
+WORKFRAME_DASHBOARD_PORT=${ports.dashboard}
+WORKFRAME_UI_PORT=${ports.ui}
+WORKFRAME_UI_STATIC_DIR=./workframe-ui/public
+WORKFRAME_API_PORT=${ports.api}
+WORKFRAME_SUPERVISOR_PORT=${ports.supervisor}
+WORKFRAME_MISSION_PORT=${ports.api}
+WORKFRAME_NATIVE_PROFILE=${nativeProfile}
+SECURE_MODE=true
+DEV_LOCAL_UNSAFE=false
+WORKFRAME_DEPLOYMENT_MODE=trusted_team
+WORKFRAME_API_TOKEN=${example ? '' : generateApiToken()}
+WORKFRAME_SUPERVISOR_TOKEN=${example ? '' : generateSupervisorToken()}
+WORKFRAME_PROXY_TOKEN=${example ? '' : generateProxyToken()}
+HERMES_DASHBOARD_BASIC_AUTH_USERNAME=workframe
+HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=${example ? '' : generateDashboardAuthPassword()}
+HERMES_DASHBOARD_BASIC_AUTH_SECRET=${example ? '' : generateDashboardAuthSecret()}
+# Credential vault KEK (32-byte base64). Required when WORKFRAME_DEPLOYMENT_MODE=public_multi_user.
+# Generate: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+WORKFRAME_VAULT_KEK=${example ? '' : ''}
+APP_BASE_URL=http://127.0.0.1:${ports.ui}
+`;
+}
+
+/** Existing host Hermes install (never overwrites). Windows: %LOCALAPPDATA%\\hermes */
+export function detectHermesHome() {
+  const fromEnv = String(process.env.HERMES_HOME || '').trim();
+  if (fromEnv && fs.existsSync(path.join(fromEnv, 'config.yaml'))) return fromEnv;
+  const candidates = [];
+  if (process.platform === 'win32') {
+    const local = process.env.LOCALAPPDATA;
+    if (local) candidates.push(path.join(local, 'hermes'));
+  } else if (process.platform === 'darwin') {
+    candidates.push(path.join(os.homedir(), 'Library', 'Application Support', 'hermes'));
+  }
+  candidates.push(path.join(os.homedir(), '.hermes'));
+  for (const dir of candidates) {
+    if (fs.existsSync(path.join(dir, 'config.yaml'))) return dir;
+  }
+  return null;
+}
+
+export function resolveDeployMode(requested = 'auto') {
+  const mode = String(requested || 'auto').trim().toLowerCase();
+  if (mode === 'native' || mode === 'docker') return mode;
+  return detectHermesHome() ? 'native' : 'docker';
+}
+
+// ponytail: runnable self-check — node scripts/lib/install-identity.mjs
+import { pathToFileURL } from 'node:url';
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) {
+  const p1 = portsForSlot(1);
+  const p2 = portsForSlot(2);
+  console.assert(p1.ui === 18644 && p1.api === 19120 && p1.supervisor === 18090, 'slot 1 ports');
+  console.assert(p2.ui === 28644 && p2.gateway === 28642, 'slot 2 ports');
+  console.assert(sessionCookieNameFromEnv({ WORKFRAME_INSTALL_ID: 'wf_abc123' }) === 'wf_abc123_session');
+  allocateInstall({ projectName: 'Test', preferredSlot: 99 }).catch(() => {});
+  console.log('install-identity ok');
+}

package/scripts/lib/workframe-registry.mjs

@@ -0,0 +1,290 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+export function workframeDir(root) {
+  return path.join(root, 'Agents', 'workframe');
+}
+
+export function agentsRegistryPath(root) {
+  return path.join(workframeDir(root), 'agents.json');
+}
+
+export function avatarRegistryPath(root) {
+  return path.join(workframeDir(root), 'avatar-registry.json');
+}
+
+export function ensureWorkframeDir(root) {
+  fs.mkdirSync(workframeDir(root), { recursive: true });
+}
+
+export function loadAgentsRegistry(root) {
+  const file = agentsRegistryPath(root);
+  if (!fs.existsSync(file)) {
+    return { version: 1, owner_profile: '', agents: {} };
+  }
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+export function saveAgentsRegistry(root, data) {
+  ensureWorkframeDir(root);
+  fs.writeFileSync(agentsRegistryPath(root), `${JSON.stringify(data, null, 2)}\n`);
+}
+
+export function loadAvatarRegistry(root) {
+  const file = avatarRegistryPath(root);
+  if (!fs.existsSync(file)) {
+    return { version: 1, weights: {}, assignments: {} };
+  }
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+export function saveAvatarRegistry(root, data) {
+  ensureWorkframeDir(root);
+  fs.writeFileSync(avatarRegistryPath(root), `${JSON.stringify(data, null, 2)}\n`);
+}
+
+export function avatarCatalogPaths(root) {
+  return [
+    path.join(root, 'Files', 'packages', 'workframe-ui', 'public', 'assets', 'avatars', 'catalog.json'),
+    path.join(root, 'Files', 'packages', 'create-workframe', 'shared', 'agent-avatars', 'catalog.json'),
+    path.join(root, 'workframe-ui', 'public', 'assets', 'avatars', 'catalog.json'),
+    path.join(root, 'packages', 'workframe-ui', 'public', 'assets', 'avatars', 'catalog.json'),
+    path.join(root, 'packages', 'create-workframe', 'shared', 'agent-avatars', 'catalog.json'),
+    path.join(root, 'scripts', 'seed', 'assets', 'avatars', 'catalog.json'),
+    path.join(root, 'workframe-ui', 'public', 'assets', 'agents', 'catalog.json'),
+    path.join(root, 'packages', 'create-workframe', 'shared', 'agent-avatars', 'catalog.json'),
+  ];
+}
+
+export function loadAvatarCatalog(root) {
+  for (const candidate of avatarCatalogPaths(root)) {
+    if (fs.existsSync(candidate)) {
+      const data = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+      const base = String(data.public_base || '/assets/avatars').replace(/\/$/, '');
+      const avatars = (data.avatars || []).map((row) => ({
+        id: String(row.id),
+        file: String(row.file || `${row.id}.png`),
+        label: String(row.label || row.id),
+        url: `${base}/${row.file || `${row.id}.png`}`,
+      }));
+      if (avatars.length) return { base, avatars };
+    }
+  }
+  throw new Error('Avatar catalog not found (expected workframe-ui/public/assets/avatars/catalog.json)');
+}
+
+export function avatarUrlForId(catalog, avatarId) {
+  const row = catalog.avatars.find((a) => a.id === avatarId);
+  return row?.url ?? `${catalog.base}/${avatarId}.png`;
+}
+
+/** Weighted pick: prefer unassigned avatars, then lowest weight; random tie-break. */
+export function pickAvatarId(root, { avoidReuse = true } = {}) {
+  const catalog = loadAvatarCatalog(root);
+  const avatarRegistry = loadAvatarRegistry(root);
+  const agentsRegistry = loadAgentsRegistry(root);
+  const assigned = new Set(Object.values(avatarRegistry.assignments || {}));
+  for (const row of Object.values(agentsRegistry.agents || {})) {
+    if (row.avatar_id) assigned.add(row.avatar_id);
+  }
+
+  let pool = catalog.avatars;
+  if (avoidReuse) {
+    const unused = pool.filter((a) => !assigned.has(a.id));
+    if (unused.length) pool = unused;
+  }
+
+  const weights = avatarRegistry.weights || {};
+  let minWeight = Infinity;
+  for (const avatar of pool) {
+    const w = weights[avatar.id] ?? 0;
+    if (w < minWeight) minWeight = w;
+  }
+  const candidates = pool.filter((a) => (weights[a.id] ?? 0) <= minWeight);
+  const pick = candidates[Math.floor(Math.random() * candidates.length)];
+  return pick.id;
+}
+
+export function assignAvatar(root, profile, avatarId) {
+  const catalog = loadAvatarCatalog(root);
+  if (!catalog.avatars.some((a) => a.id === avatarId)) {
+    throw new Error(`Unknown avatar id: ${avatarId}`);
+  }
+  const avatarRegistry = loadAvatarRegistry(root);
+  avatarRegistry.assignments = avatarRegistry.assignments || {};
+  avatarRegistry.weights = avatarRegistry.weights || {};
+  avatarRegistry.assignments[profile] = avatarId;
+  avatarRegistry.weights[avatarId] = (avatarRegistry.weights[avatarId] ?? 0) + 1;
+  saveAvatarRegistry(root, avatarRegistry);
+  return avatarUrlForId(catalog, avatarId);
+}
+
+export function releaseAvatar(root, profile) {
+  const avatarRegistry = loadAvatarRegistry(root);
+  if (avatarRegistry.assignments?.[profile]) {
+    delete avatarRegistry.assignments[profile];
+    saveAvatarRegistry(root, avatarRegistry);
+  }
+}
+
+export function upsertAgentRecord(root, profile, patch, ownerProfile) {
+  const registry = loadAgentsRegistry(root);
+  registry.owner_profile = registry.owner_profile || ownerProfile;
+  registry.agents = registry.agents || {};
+  const prev = registry.agents[profile] || {};
+  const now = new Date().toISOString();
+  registry.agents[profile] = {
+    ...prev,
+    ...patch,
+    profile,
+    owner: ownerProfile,
+    updated_at: now,
+    created_at: prev.created_at || now,
+  };
+  saveAgentsRegistry(root, registry);
+  return registry.agents[profile];
+}
+
+export function removeAgentRecord(root, profile) {
+  const registry = loadAgentsRegistry(root);
+  if (registry.agents?.[profile]) {
+    delete registry.agents[profile];
+    saveAgentsRegistry(root, registry);
+  }
+  releaseAvatar(root, profile);
+}
+
+export function getAgentRecord(root, profile) {
+  const registry = loadAgentsRegistry(root);
+  return registry.agents?.[profile] ?? null;
+}
+
+export function readModelFromConfig(root, profile) {
+  const cfgPath = path.join(root, 'Agents', 'profiles', profile, 'config.yaml');
+  if (!fs.existsSync(cfgPath)) return null;
+  const text = fs.readFileSync(cfgPath, 'utf8');
+  const match = text.match(/^model:\s*\n(?:\s+.+\n)*?\s+default:\s*(.+)$/m);
+  return match ? match[1].trim() : null;
+}
+
+const FORBIDDEN_CHILD_SKILLS = new Set(['botfather', 'crew-manager']);
+
+export function profileSkillsSeedDir(root, sourceSlug) {
+  return path.join(root, 'scripts', 'seed', 'profiles', sourceSlug, 'skills');
+}
+
+export function profileSkillsDir(root, profile) {
+  return path.join(root, 'Agents', 'profiles', profile, 'skills');
+}
+
+function copyDirRecursive(src, dest) {
+  if (!fs.existsSync(src)) return false;
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDirRecursive(from, to);
+    else fs.copyFileSync(from, to);
+  }
+  return true;
+}
+
+function skillNameFromPath(skillsRoot, skillFile) {
+  const rel = path.relative(skillsRoot, skillFile).replace(/\\/g, '/');
+  const parts = rel.split('/');
+  if (parts.length >= 2 && parts[parts.length - 1] === 'SKILL.md') {
+    return parts[parts.length - 2];
+  }
+  return path.basename(path.dirname(skillFile));
+}
+
+export function listInstalledSkillIds(root, profile) {
+  const skillsRoot = profileSkillsDir(root, profile);
+  if (!fs.existsSync(skillsRoot)) return [];
+  const ids = new Set();
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name === 'SKILL.md') ids.add(skillNameFromPath(skillsRoot, full));
+    }
+  };
+  walk(skillsRoot);
+  return [...ids].sort();
+}
+
+/** Copy skills from seed (or another seed slug). Never installs botfather on children. */
+export function installProfileSkills(root, targetProfile, { sourceSlug, skillsDir } = {}) {
+  const dest = profileSkillsDir(root, targetProfile);
+  let src = skillsDir ? (path.isAbsolute(skillsDir) ? skillsDir : path.join(root, skillsDir)) : null;
+  if (!src) {
+    const seedSlug = sourceSlug || targetProfile;
+    src = profileSkillsSeedDir(root, seedSlug);
+  }
+  if (!fs.existsSync(src)) {
+    return { installed: [], skipped: [], source: src };
+  }
+
+  const staging = path.join(dest, '.staging');
+  fs.rmSync(staging, { recursive: true, force: true });
+  copyDirRecursive(src, staging);
+
+  const installed = [];
+  const skipped = [];
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name === 'SKILL.md') {
+        const id = skillNameFromPath(staging, full);
+        if (FORBIDDEN_CHILD_SKILLS.has(id)) {
+          skipped.push(id);
+          fs.rmSync(path.dirname(full), { recursive: true, force: true });
+        } else {
+          installed.push(id);
+        }
+      }
+    }
+  };
+  walk(staging);
+
+  if (installed.length || skipped.length) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(staging, { withFileTypes: true })) {
+      const from = path.join(staging, entry.name);
+      const to = path.join(dest, entry.name);
+      if (entry.isDirectory()) copyDirRecursive(from, to);
+      else if (fs.existsSync(from)) fs.copyFileSync(from, to);
+    }
+  }
+  fs.rmSync(staging, { recursive: true, force: true });
+  return { installed: [...new Set(installed)].sort(), skipped: [...new Set(skipped)].sort(), source: src };
+}
+
+/** Remove botfather/crew-manager from a child profile after Hermes --clone. */
+export function stripForbiddenChildSkills(root, profile) {
+  const skillsRoot = profileSkillsDir(root, profile);
+  if (!fs.existsSync(skillsRoot)) return { removed: [] };
+  const removed = [];
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'botfather' || entry.name === 'crew-manager') {
+          fs.rmSync(full, { recursive: true, force: true });
+          removed.push(entry.name);
+        } else walk(full);
+      } else if (entry.name === 'SKILL.md') {
+        const id = skillNameFromPath(skillsRoot, full);
+        if (FORBIDDEN_CHILD_SKILLS.has(id)) {
+          fs.rmSync(path.dirname(full), { recursive: true, force: true });
+          removed.push(id);
+        }
+      }
+    }
+  };
+  walk(skillsRoot);
+  return { removed: [...new Set(removed)].sort() };
+}

package/scripts/new-project.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * Canonical dev/test bootstrap: bundle UI (meta layout only) → scaffold → auto-launch Phase B.
+ *
+ * Meta repo:
+ *   node packages/create-workframe/scripts/new-project.mjs BrandAuthority --out D:/Workframe --force
+ *
+ * Published npm (UI already bundled in package):
+ *   npx create-workframe BrandAuthority --out D:/Workframe --force
+ */
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
+
+const PKG_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const CLI = path.join(PKG_ROOT, 'bin', 'create-workframe.js');
+const BUNDLE = path.join(PKG_ROOT, 'scripts', 'bundle-workframe-ui.mjs');
+const UI_SOURCE = path.join(PKG_ROOT, '..', 'workframe-ui', 'package.json');
+
+function usage() {
+  console.log(`new-project — scaffold + Phase B installer (Workframe UI bundled when developing from meta)
+
+Usage:
+  node scripts/new-project.mjs <ProjectName> [--out DIR] [--force] [--no-launch] [--no-bundle]
+
+Examples:
+  node scripts/new-project.mjs BrandAuthority --out D:/Workframe --force
+  node scripts/new-project.mjs Demo --out /tmp/projects
+
+Notes:
+  - Auto-bundles Workframe UI when run from the meta repo (workframe-ui source present).
+  - Skips bundle when installed from npm (pre-bundled UI in the package).
+  - Phase B installer opens in a new terminal; complete Hermes setup there.
+  - Equivalent published command: npx create-workframe <ProjectName> --out <DIR> --force
+`);
+}
+
+const argv = process.argv.slice(2);
+if (!argv.length || argv.includes('-h') || argv.includes('--help')) {
+  usage();
+  process.exit(argv.length ? 0 : 1);
+}
+
+const noBundle = argv.includes('--no-bundle');
+const noLaunch = argv.includes('--no-launch');
+const forwarded = argv.filter((a) => a !== '--no-bundle');
+
+const isMetaDevLayout = fs.existsSync(UI_SOURCE);
+if (isMetaDevLayout && !noBundle) {
+  console.log('Bundling Workframe UI into create-workframe…');
+  const bundle = spawnSync(process.execPath, [BUNDLE], {
+    stdio: 'inherit',
+    cwd: path.dirname(BUNDLE),
+  });
+  if (bundle.status !== 0) process.exit(bundle.status ?? 1);
+} else if (!isMetaDevLayout && !noBundle) {
+  console.log('Using pre-bundled Workframe UI from create-workframe package.');
+}
+
+const scaffold = spawnSync(process.execPath, [CLI, ...forwarded], { stdio: 'inherit' });
+if (scaffold.status !== 0) process.exit(scaffold.status ?? 1);
+
+if (!noLaunch) {
+  console.log('');
+  console.log('Next: complete Hermes setup in the Phase B installer window.');
+  console.log('Re-open installer manually: .\\scripts\\start-install.ps1 or ./scripts/start-install.sh');
+}

package/scripts/restart-gateway-hermes.sh

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