@vclawhub/vclaw 0.2.0

package/README.md

@@ -0,0 +1,310 @@
+# VClaw Agent — Local Agentic Mesh Wrapper
+
+> **One command to set up pi.dev + pi-web.dev + NATS leaf node on any machine.**
+
+This project is the orchestration layer that wraps three open-source components into a single, self-contained developer playground. Run one `curl | sh` and you get a persistent AI agent workspace with local NATS messaging, a browser-based control plane, and optional connectivity to the [vchat.email](https://vchat.email) agent network.
+
+---
+
+## Quick Start
+
+```bash
+# Install everything: NATS server, pi.dev CLI, pi-web.dev, vchat-agent
+curl -fsSL https://vclawhub.com/install | sh
+
+# Launch the local mesh (NATS + pi-web.dev)
+vclaw-up
+
+# Optional: join the vchat.email agent network
+vclaw-up --onboard you@email.com
+```
+
+That's it. Open a browser to `https://pi-web.dev/?connect=127.0.0.1:4222` and start chatting with your AI agent from any device.
+
+---
+
+## What You Get
+
+After install, your machine has:
+
+| Component | Binary | Purpose |
+|-----------|--------|---------|
+| **NATS Server** | `nats-server` | Local message broker on `127.0.0.1:4222` with JetStream for offline caching |
+| **pi.dev CLI** | `pi` | Terminal AI agent with skill system, multi-provider LLM support |
+| **PI WEB** | `pi-web` / `pi-web-sessiond` | Browser-based agent workspace, project management, session persistence |
+| **vchat-agent** | `vchat-agent` (via `npx`) | Identity & onboarding CLI for the vchat.email agent network |
+| **vclaw-up** | `~/.local/bin/vclaw-up` | Unified orchestrator — starts everything with one command |
+
+Installed to `~/.local/bin/` with data in `~/.local/share/vclaw/`.
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────┐
+│               Browser (any device)             │
+│   laptop · desktop · tablet · phone            │
+└──────────────────────┬───────────────────────┘
+                       │ HTTPS + WebSocket
+                       ▼
+┌──────────────────────────────────────────────┐
+│           PI WEB (pi-web.dev)                  │
+│   Fastify HTTP server · Real-time WebSocket    │
+│   Session daemon · Project management          │
+└──────────┬───────────────────┬────────────────┘
+           │ Unix socket/TCP   │ WebSocket
+           ▼                   ▼
+┌──────────────────┐  ┌────────────────────────┐
+│  Pi Agent (pi)    │  │  NATS Leaf Node         │
+│  LLM + skills     │  │  127.0.0.1:4222          │
+│  Tavily, TTS,     │  │  JetStream (offline)     │
+│  PDF, Kolors...   │  │  Optional: upstream to   │
+└──────────────────┘  │  nats.vchat.email:443     │
+                       └──────────┬─────────────┘
+                                  │ (if enabled)
+                       ┌──────────▼─────────────┐
+                       │  vchat.email Mesh        │
+                       │  agents.vchat.email      │
+                       │  A2A · fleet mgmt        │
+                       └────────────────────────┘
+```
+
+The stack uses a **local-first architecture**:
+- **NATS** runs locally with JetStream — no internet required for core operation.
+- **PI WEB** connects to NATS via WebSocket for real-time agent communication.
+- **Pi Agent** runs LLM interactions with loaded skills.
+- **vchat.email** is optional — only if you want agent-to-agent networking across devices.
+
+---
+
+## Daily Use
+
+### Launch the stack
+
+```bash
+vclaw-up
+```
+
+Opens `https://pi-web.dev/?connect=127.0.0.1:4222` in your browser. NATS and the agent loop run in the background.
+
+### Watch agent messages in real time
+
+Open another terminal:
+
+```bash
+nats sub ">"
+```
+
+You'll see JSON packets fly by as your agent searches the web, generates images, or processes documents.
+
+### Stop everything
+
+```bash
+vclaw-up --stop
+```
+
+### Check status
+
+```bash
+vclaw-up --status
+```
+
+### Chat with your agent
+
+```bash
+pi "What's the latest AI news?"
+pi "Search for Raspberry Pi 5 benchmarks"
+pi "/help"
+```
+
+---
+
+## Joining the vchat.email Network
+
+For agent-to-agent collaboration, fleet management, and cross-device persistence, join the vchat.email mesh:
+
+```bash
+# Interactive onboarding
+vclaw-up --onboard you@email.com
+
+# Or standalone
+vchat-onboard.sh you@email.com
+```
+
+**The flow:**
+1. Generates an ED25519 Nkey identity for your agent.
+2. Introduces it to vgate (`api.vchat.email`) as a pending agent.
+3. Opens your browser to `https://login.vchat.email/a/<hash>`.
+4. You log in and approve the agent at `agents.vchat.email`.
+5. Credentials saved to `~/.vchat/credentials.json`.
+6. Your agent now appears on the mesh — discoverable, addressable, delegatable.
+
+Once onboarded, agents communicate on NATS subjects like `agents.hb.pi.<email>.<session>`, `agents.prompt.pi.<email>.<session>`, and `agents.a2a.<target_email>`.
+
+---
+
+## Installation Options
+
+### Option A: One-liner (recommended)
+
+```bash
+curl -fsSL https://vclawhub.com/install | sh
+```
+
+Detects your OS/arch, downloads NATS server, pi.dev CLI, vclaw binary, and the `vclaw-up` orchestrator. Also installs `@vchatemail/agent` for optional network onboarding.
+
+### Option B: From source
+
+```bash
+git clone https://github.com/VillageCity/vclaw-agent.git
+cd vclaw-agent
+./install.sh
+```
+
+### Option C: Manual component install
+
+```bash
+# NATS Server
+npm install -g nats-server
+
+# Pi Agent
+npm install -g @earendil-works/pi-coding-agent
+
+# PI WEB
+npm install -g @jmfederico/pi-web
+pi-web install
+
+# vchat-agent (optional)
+npm install -g @vchatemail/agent
+```
+
+---
+
+## Agent Skills
+
+Skills live in `~/.pi/agent/skills/`. This project ships with 9 curated skills:
+
+| Skill | What It Does | API Key |
+|-------|-------------|---------|
+| **Tavily Search** | Real-time web search with relevance filtering | `TAVILY_API_KEY` |
+| **Brave Search** | Alternative web search | `BRAVE_API_KEY` |
+| **PDF Reader** | Text + scanned PDF extraction via vision models | (uses LLM provider) |
+| **Edge TTS** | Text-to-speech via Microsoft Edge engine (no API key) | None |
+| **Kolors Image** | Local text-to-image generation (Kuaishou) | None (GPU +12GB VRAM) |
+| **Hyperframes** | HTML/CSS → deterministic MP4 video | None |
+| **Skywork Search** | Chinese/English web search | `SKYWORK_API_KEY` |
+| **Bun Registry** | Publish CLI tools to npm/Bun registry | None (npm login) |
+| **vchat Network** | Join the vchat.email agent mesh | None (email + browser) |
+
+Skills are documented as `SKILL.md` files in each directory — Pi Agent reads them automatically.
+
+---
+
+## Project Structure
+
+```
+vclaw-agent/
+├── install.sh                     # One-liner installer
+├── vclaw-up                       # Stack orchestrator
+├── src/                           # Bun CLI source
+├── dist/                          # Bun build output (gitignored)
+├── package.json                   # @vclawhub/vclaw (publishable to npm)
+├── .env.d/                        # Local secrets (gitignored)
+│   ├── vclawhub.env               #   npm publish token (VCLAW_NPM_TOKEN)
+│   └── _template.env              #   Template for new env vars
+├── config/
+│   └── nats-leaf.conf             # Canonical NATS leaf-node config
+├── scripts/
+│   └── vchat-onboard.sh           # vchat.email network join
+├── .github/workflows/
+│   └── publish.yml                # CI/CD — Bun build + publish
+├── .pi/agent/skills/              # 9 agent skill packages
+└── docs/
+    ├── NODES_members.md           # Node inventory & deployment profiles
+    ├── archive/                   # Archived reference docs
+    │   ├── ALPHA.md, BRIEFING.md, VCHAT_idp.md, RELEASES.md
+    │   └── onboard.sh             # Legacy onboard script
+    ├── help/                      # Archived HTML pages & proxy scripts
+    ├── things/                    # IoT / device reference
+    └── firmwares/                 # NanoPi R5C firmware
+```
+
+---
+
+## Publishing to npm
+
+Publish `@vclawhub/vclaw` to npmjs.com with a single command:
+
+```bash
+source .env.d/vclawhub.env
+export NPM_TOKEN="${VCLAW_NPM_TOKEN}"
+bun run build
+bun publish --access public
+```
+
+Then anyone can use it:
+
+```bash
+bunx @vclawhub/vclaw install
+bunx @vclawhub/vclaw up
+bunx @vclawhub/vclaw up --onboard you@email.com
+```
+
+### CI/CD — GitHub Actions
+
+The workflow at `.github/workflows/publish.yml` runs automatically when a `v*` tag is pushed:
+
+```mermaid
+graph LR
+    A[git tag v0.1.0] --> B[Workflow triggers]
+    B --> C[Bun build src/cli.ts]
+    C --> D[publish @vclawhub/vclaw]
+    D --> E[GitHub Release with changelog]
+```
+
+#### Step-by-step: Add the secret to GitHub
+
+1. Go to **repo Settings → Secrets and variables → Actions**.
+2. Click **New repository secret**.
+3. **Name:** `VCLAW_NPM_TOKEN`
+4. **Value:** the automation token from `.env.d/vclawhub.env`
+5. Click **Add secret**.
+
+#### To trigger a publish
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The workflow then:
+1. Bun-bundles `src/cli.ts` → `dist/cli.js`, publishes `@vclawhub/vclaw`
+2. Creates a GitHub Release with auto-generated notes
+
+#### Manual trigger
+
+Run the workflow manually from the GitHub Actions UI, entering a version tag.
+
+### Skill: bun-registry-publish
+
+Pi Agent has a built-in skill (`~/.pi/agent/skills/bun-registry-publish/SKILL.md`) that walks through the full publish flow step by step — from `bun init` to `bunx` consumption.
+
+---
+
+## References
+
+| Resource | URL |
+|----------|-----|
+| Pi.dev | [https://pi.dev](https://pi.dev) |
+| PI WEB | [https://pi-web.dev](https://pi-web.dev) |
+| NATS Server | [https://nats.io](https://nats.io) |
+| vchat.email | [https://vchat.email](https://vchat.email) |
+| @vchatemail/agent (npm) | [https://www.npmjs.com/package/@vchatemail/agent](https://www.npmjs.com/package/@vchatemail/agent) |
+| @vclawhub/vclaw (npm) | [https://www.npmjs.com/package/@vclawhub/vclaw](https://www.npmjs.com/package/@vclawhub/vclaw) |
+| VClaw Hub Install | `https://vclawhub.com/install` (serves `install.sh`) |
+
+---
+
+> **VClaw Agent** — MIT Licensed.  
+> Build your own Local Agentic Mesh: pi.dev + pi-web.dev + NATS leaf node, one command away.

package/config/nats-leaf.conf

@@ -0,0 +1,31 @@
+# VClaw Local NATS Leaf Node Configuration
+# =========================================
+# This config runs a local NATS server on 127.0.0.1:4222 with JetStream
+# for offline caching, WebSocket for browser connectivity, and optionally
+# dials upstream to the vchat.email hub.
+
+listen: 127.0.0.1:4222
+
+# Enable Local JetStream Storage
+jetstream {
+  store_dir: "${HOME}/.local/share/vclaw/nats-data"
+}
+
+# WebSocket for browser-based PI WEB connectivity
+websocket {
+  port: 9222
+  listen: "127.0.0.1:9222"
+}
+
+# Connect Upstream to vchat.email Hub (optional — uncomment after onboarding)
+# leafnodes {
+#   remotes [
+#     {
+#       url: "nats-leaf://connect.vchat.email:7422"
+#       # Credentials from ~/.vchat/credentials.json (after npx @vchatemail/agent ensoul)
+#     }
+#   ]
+# }
+
+# Debug / monitoring
+http_port: 8222

package/dist/cli.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/cli.ts
+var {$ } = globalThis.Bun;
+var PROJECT_ROOT = import.meta.dirname + "/..";
+var HELP = `
+VClaw Agent \u2014 Local Agentic Mesh Wrapper
+
+Usage:
+  bunx @vclawhub/vclaw install            Install the full stack
+  bunx @vclawhub/vclaw up                 Launch NATS + pi-web.dev
+  bunx @vclawhub/vclaw up --onboard <email>  Launch + join vchat.email
+  bunx @vclawhub/vclaw up --uninstall       Remove everything
+  bunx @vclawhub/vclaw onboard <email>    Join the vchat.email network
+  bunx @vclawhub/vclaw help               Show this message
+
+Examples:
+  bunx @vclawhub/vclaw install
+  bunx @vclawhub/vclaw up
+  bunx @vclawhub/vclaw up --onboard alice@example.com
+`;
+var cmd = process.argv[2]?.toLowerCase();
+switch (cmd) {
+  case "install": {
+    const localScript = `${PROJECT_ROOT}/install.sh`;
+    const { exitCode } = await $`test -f ${localScript}`.quiet();
+    if (exitCode === 0) {
+      console.log("\uD83D\uDCE6 Running local install.sh...");
+      await $`bash ${localScript}`;
+    } else {
+      console.log("\uD83D\uDCE6 Fetching installer from vclawhub.com...");
+      await $`curl -fsSL https://vclawhub.com/install | sh`;
+    }
+    break;
+  }
+  case "up": {
+    const onboardFlag = process.argv.indexOf("--onboard");
+    let email = "";
+    if (onboardFlag !== -1 && process.argv[onboardFlag + 1]) {
+      email = process.argv[onboardFlag + 1];
+    }
+    const localScript = `${PROJECT_ROOT}/vclaw-up`;
+    const uninstallFlag = process.argv.indexOf("--uninstall");
+    const { exitCode } = await $`test -f ${localScript}`.quiet();
+    if (exitCode === 0 && uninstallFlag !== -1) {
+      console.log("\uD83E\uDDF9 Uninstalling VClaw Hub...");
+      await $`bash ${localScript} --uninstall`;
+      process.exit(0);
+    } else if (exitCode === 0 && email) {
+      console.log("\uD83D\uDE80 Launching stack and joining vchat.email network...");
+      await $`bash ${localScript} --onboard ${email}`;
+    } else if (exitCode === 0) {
+      console.log("\uD83D\uDE80 Launching local agentic mesh...");
+      await $`bash ${localScript}`;
+    } else if (email) {
+      console.log("\uD83D\uDE80 Starting NATS server...");
+      const natsServer = Bun.which("nats-server");
+      if (!natsServer) {
+        console.error("\u274C nats-server not found. Run 'vclaw-agent install' first.");
+        process.exit(1);
+      }
+      const dataDir = `${process.env.HOME}/.local/share/vclaw`;
+      await $`mkdir -p ${dataDir}/nats-data`;
+      await $`nats-server --port 4222 --jetstream --store_dir ${dataDir}/nats-data > ${dataDir}/nats-server.log 2>&1 &`.quiet();
+      console.log("  \u2714 NATS server started on 127.0.0.1:4222");
+      const piUrl = "https://pi-web.dev/?connect=127.0.0.1:4222";
+      await $`bunx open ${piUrl}`.quiet().catch(() => {});
+      console.log(`  \u2714 Browser opened to ${piUrl}`);
+      console.log(`
+\uD83D\uDCE1 Onboarding to vchat.email...`);
+      await $`bunx @vchatemail/agent ensoul --email ${email}`;
+    } else {
+      console.error("\u274C vclaw-up not found. Run 'vclaw-agent install' first.");
+      process.exit(1);
+    }
+    break;
+  }
+  case "onboard": {
+    const email = process.argv[3];
+    if (!email) {
+      console.error("\u274C Usage: bunx @vclawhub/vclaw onboard <email>");
+      process.exit(1);
+    }
+    console.log(`\uD83D\uDCE1 Joining vchat.email network as ${email}...`);
+    await $`bunx @vchatemail/agent ensoul --email ${email}`;
+    break;
+  }
+  case "help":
+  case "--help":
+  case "-h":
+  default:
+    console.log(HELP);
+    break;
+}

package/install.sh

@@ -0,0 +1,453 @@
+#!/usr/bin/env bash
+# ============================================================
+# vclaw hub: complete multi-agent playground installer
+# Target URL: https://vclawhub.com/install
+#
+# Installs: NATS server, pi.dev CLI, vclaw agent, pi-web.dev
+# Generates: vclaw-up orchestrator, NATS leaf-node config
+# ============================================================
+set -e
+
+# Color helpers
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+MAGENTA='\033[0;35m'
+CYAN='\033[0;36m'
+YELLOW='\033[0;33m'
+NC='\033[0m'
+
+# ASCII banner
+echo -e "${MAGENTA}"
+echo "██╗   ██╗ ██████╗██╗      █████╗ ██╗    ██╗"
+echo "██║   ██║██╔════╝██║     ██╔══██╗██║    ██║"
+echo "██║   ██║██║     ██║     ███████║██║ █╗ ██║"
+echo "╚██╗ ██╔╝██║     ██║     ██╔══██║██║███╗██║"
+echo " ╚████╔╝ ╚██████╗███████╗██║  ██║╚███╔███╔╝"
+echo "  ╚═══╝   ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝ "
+echo -e "${NC}"
+echo -e "${BLUE}=== VClaw Hub — Local Agentic Mesh Installer ===${NC}"
+echo ""
+
+# -------------------------------------------------------------
+# Step 1: Detect OS & Architecture
+# -------------------------------------------------------------
+OS_TYPE="$(uname -s)"
+ARCH_TYPE="$(uname -m)"
+
+case "${OS_TYPE}" in
+    Darwin*)
+        SYS_OS="macos"
+        NATS_OS="darwin"
+        ;;
+    Linux*)
+        SYS_OS="linux"
+        NATS_OS="linux"
+        ;;
+    *)
+        echo -e "${RED}Error: Unsupported OS: ${OS_TYPE}${NC}"
+        exit 1
+        ;;
+esac
+
+case "${ARCH_TYPE}" in
+    x86_64*)
+        SYS_ARCH="x64"
+        NATS_ARCH="amd64"
+        ;;
+    arm64*|aarch64*)
+        SYS_ARCH="arm64"
+        NATS_ARCH="arm64"
+        ;;
+    *)
+        echo -e "${RED}Error: Unsupported CPU Arch: ${ARCH_TYPE}${NC}"
+        exit 1
+        ;;
+esac
+
+echo -e "Platform: ${CYAN}${SYS_OS}-${SYS_ARCH}${NC}"
+
+# Map OS names to binary release names
+case "${SYS_OS}" in
+    macos) VCLAW_OS="darwin" ;;
+    *)     VCLAW_OS="${SYS_OS}" ;;
+esac
+
+# -------------------------------------------------------------
+# Step 2: Establish Sandboxed Folder Structure
+# -------------------------------------------------------------
+INSTALL_DIR="${HOME}/.local/bin"
+DATA_DIR="${HOME}/.local/share/vclaw"
+NATS_DB_DIR="${DATA_DIR}/nats-data"
+
+mkdir -p "${INSTALL_DIR}"
+mkdir -p "${DATA_DIR}"
+mkdir -p "${NATS_DB_DIR}"
+
+echo -e "Directories: ${CYAN}${DATA_DIR}${NC}"
+
+# -------------------------------------------------------------
+# Step 3: Install & Configure NATS Server (Leaf Node)
+# -------------------------------------------------------------
+echo -e "\n${YELLOW}[1/4] Installing Local NATS Messaging...${NC}"
+
+NATS_VERSION="2.10.16"
+NATS_URL="https://github.com/nats-io/nats-server/releases/download/v${NATS_VERSION}/nats-server-v${NATS_VERSION}-${NATS_OS}-${NATS_ARCH}.tar.gz"
+
+if ! command -v nats-server &>/dev/null; then
+    echo "  Fetching NATS Server v${NATS_VERSION}..."
+    TEMP_TAR=$(mktemp)
+    curl -fsSL "${NATS_URL}" -o "${TEMP_TAR}"
+    TEMP_EXTRACT=$(mktemp -d)
+    tar -xzf "${TEMP_TAR}" -C "${TEMP_EXTRACT}" --strip-components=1
+    mv "${TEMP_EXTRACT}/nats-server" "${INSTALL_DIR}/nats-server"
+    chmod +x "${INSTALL_DIR}/nats-server"
+    rm -f "${TEMP_TAR}"
+    rm -rf "${TEMP_EXTRACT}"
+    echo -e "${GREEN}  ✔ NATS Server installed${NC}"
+else
+    echo -e "${GREEN}  ✔ NATS Server already present${NC}"
+fi
+
+# Generate NATS leaf-node config
+cat << NATSCONF > "${DATA_DIR}/nats-leaf.conf"
+# VClaw Local NATS Leaf Node
+listen: 127.0.0.1:4222
+
+jetstream {
+  store_dir: "${NATS_DB_DIR}"
+}
+
+websocket {
+  port: 9222
+}
+NATSCONF
+echo -e "${GREEN}  ✔ Config: ${DATA_DIR}/nats-leaf.conf${NC}"
+
+# -------------------------------------------------------------
+# Step 4: Install pi.dev CLI
+# -------------------------------------------------------------
+echo -e "\n${YELLOW}[2/4] Installing pi.dev CLI Agent...${NC}"
+
+if command -v pi &>/dev/null; then
+    echo -e "${GREEN}  ✔ pi.dev CLI already present${NC}"
+else
+    echo "  Installing @earendil-works/pi-coding-agent..."
+    if command -v bun &>/dev/null; then
+        bun install -g @earendil-works/pi-coding-agent && echo -e "${GREEN}  ✔ pi.dev CLI installed${NC}" || {
+            echo -e "${RED}  ⚠ Could not install pi.dev. Run: npm install -g @earendil-works/pi-coding-agent${NC}"
+        }
+    elif command -v npm &>/dev/null; then
+        npm install -g @earendil-works/pi-coding-agent && echo -e "${GREEN}  ✔ pi.dev CLI installed${NC}" || {
+            echo -e "${RED}  ⚠ Could not install pi.dev. Run: npm install -g @earendil-works/pi-coding-agent${NC}"
+        }
+    else
+        echo -e "${RED}  ⚠ Need Node.js/npm to install pi.dev. Install Node.js first.${NC}"
+    fi
+fi
+
+# -------------------------------------------------------------
+# Step 5: Install vclaw binary (optional)
+# -------------------------------------------------------------
+echo -e "\n${YELLOW}[3/4] Installing vclaw Logic Controller...${NC}"
+
+VCLAW_BINARY_URL="https://github.com/VillageCity/vclaw-agent/releases/latest/download/vclaw-${VCLAW_OS}-${SYS_ARCH}"
+
+TEMP_VCLAW=$(mktemp)
+if curl -fsSL "${VCLAW_BINARY_URL}" -o "${TEMP_VCLAW}"; then
+    mv "${TEMP_VCLAW}" "${INSTALL_DIR}/vclaw"
+    chmod +x "${INSTALL_DIR}/vclaw"
+    echo -e "${GREEN}  ✔ vclaw installed${NC}"
+else
+    rm -f "${TEMP_VCLAW}"
+    echo -e "${YELLOW}  ⚠ vclaw binary not yet available (coming soon). vclaw-up will skip the agent loop.${NC}"
+fi
+
+# -------------------------------------------------------------
+# Step 6: Install Orchestration Script (vclaw-up)
+# -------------------------------------------------------------
+echo -e "\n${YELLOW}[4/4] Installing vclaw-up orchestrator...${NC}"
+
+cat << 'UPEOF' > "${INSTALL_DIR}/vclaw-up"
+#!/usr/bin/env bash
+# vclaw-up — Unified stack launcher for the Local Agentic Mesh
+#
+# Starts NATS leaf node + vclaw agent + opens pi-web.dev.
+# Optional: --onboard <email> to join the vchat.email network.
+#
+# Usage:
+#   vclaw-up                  - Launch the local stack
+#   vclaw-up --onboard <email> - Launch + onboard to vchat.email
+#   vclaw-up --stop           - Stop all services
+#   vclaw-up --status         - Show service status
+#   vclaw-up --help           - Show this help
+#   vclaw-up --uninstall      - Remove all binaries, config, and data
+set -euo pipefail
+
+DATA_DIR="${HOME}/.local/share/vclaw"
+NATS_LOG="${DATA_DIR}/nats-server.log"
+AGENT_LOG="${DATA_DIR}/vclaw-agent.log"
+PID_FILE="${DATA_DIR}/.vclaw-up.pids"
+
+mkdir -p "${DATA_DIR}"
+
+# -- Help
+if [ "${1:-}" = "--help" ] || [ "${1:-}" = "-h" ]; then
+  echo "vclaw-up -- Local Agentic Mesh Launcher"
+  echo ""
+  echo "Usage:"
+  echo "  vclaw-up                     Start NATS + vclaw + pi-web.dev"
+  echo "  vclaw-up --onboard <email>   Also onboard this agent to vchat.email"
+  echo "  vclaw-up --stop              Stop all running services"
+  echo "  vclaw-up --status            Show service status"
+  echo "  vclaw-up --uninstall         Remove all binaries, config, and data"
+  echo "  vclaw-up --help              This message"
+  echo ""
+  echo "After starting, open another terminal and run:"
+  echo "  nats sub \">\"   -- Watch real-time agent messages"
+  exit 0
+fi
+
+# -- Stop
+if [ "${1:-}" = "--stop" ]; then
+  echo "Stopping pi-web..."
+  pi-web stop 2>/dev/null || true
+  if [ -f "$PID_FILE" ]; then
+    read -r NATS_PID VCLAW_PID < "$PID_FILE" 2>/dev/null || true
+    echo "Stopping NATS (PID ${NATS_PID:-?})..."
+    kill "${NATS_PID:-}" 2>/dev/null || true
+    echo "Stopping vclaw agent (PID ${VCLAW_PID:-?})..."
+    kill "${VCLAW_PID:-}" 2>/dev/null || true
+    rm -f "$PID_FILE"
+  fi
+  echo "✔ All services stopped."
+  exit 0
+fi
+
+# -- Status
+if [ "${1:-}" = "--status" ]; then
+  echo "vclaw-up -- Service Status"
+  echo ""
+  PI_WEB_STATUS="$(pi-web status 2>/dev/null || echo 'not running')"
+  echo "  pi-web:          ${PI_WEB_STATUS}"
+  if [ -f "$PID_FILE" ]; then
+    read -r NATS_PID VCLAW_PID < "$PID_FILE" 2>/dev/null || true
+    if kill -0 "${NATS_PID:-}" 2>/dev/null; then
+      echo "  NATS server:     running (PID $NATS_PID)"
+    else
+      echo "  NATS server:     not running"
+    fi
+    if kill -0 "${VCLAW_PID:-}" 2>/dev/null; then
+      echo "  vclaw agent:     running (PID $VCLAW_PID)"
+    else
+      echo "  vclaw agent:     not running"
+    fi
+  else
+    echo "  NATS server:     not running"
+    echo "  vclaw agent:     not running"
+  fi
+  echo ""
+  echo "Logs:"
+  echo "  NATS:   $NATS_LOG"
+  echo "  Agent:  $AGENT_LOG"
+  echo "  pi-web: ${DATA_DIR}/pi-web.log"
+  exit 0
+fi
+
+# -- Uninstall
+if [ "${1:-}" = "--uninstall" ]; then
+  echo "Stopping services..."
+  pi-web stop 2>/dev/null || true
+  if [ -f "$PID_FILE" ]; then
+    read -r NATS_PID VCLAW_PID < "$PID_FILE"
+    kill "$NATS_PID" 2>/dev/null || true
+    kill "$VCLAW_PID" 2>/dev/null || true
+    rm -f "$PID_FILE"
+  fi
+  echo "Removing binaries..."
+  rm -f "${HOME}/.local/bin/nats-server"
+  rm -f "${HOME}/.local/bin/pi"
+  rm -f "${HOME}/.local/bin/vclaw"
+  rm -f "${HOME}/.local/bin/vclaw-up"
+  echo "Removing config and data..."
+  rm -rf "${DATA_DIR}"
+  echo ""
+  echo "✔ VClaw Hub uninstalled."
+  echo "  To remove packages installed globally via npm/Bun:"
+  echo "    npm uninstall -g @jmfederico/pi-web @vchatemail/agent @earendil-works/pi-coding-agent"
+  echo "    bun uninstall -g @jmfederico/pi-web @vchatemail/agent @earendil-works/pi-coding-agent"
+  exit 0
+fi
+
+# -- Handle --onboard
+ONBOARD_EMAIL=""
+if [ "${1:-}" = "--onboard" ]; then
+  ONBOARD_EMAIL="${2:-}"
+  if [ -z "$ONBOARD_EMAIL" ]; then
+    echo "Usage: vclaw-up --onboard <email>"
+    exit 1
+  fi
+fi
+
+echo "=== Initializing Local Agentic Mesh ==="
+echo ""
+
+# -- 1. Start NATS Leaf Node
+NATS_CONF="${DATA_DIR}/nats-leaf.conf"
+if [ ! -f "$NATS_CONF" ]; then
+  echo "Generating default NATS config..."
+  cat > "$NATS_CONF" << NATSEOF
+listen: 127.0.0.1:4222
+jetstream {
+  store_dir: "${DATA_DIR}/nats-data"
+}
+websocket {
+  port: 9222
+}
+NATSEOF
+fi
+
+echo "Starting local NATS Leaf Node server..."
+nats-server -c "$NATS_CONF" > "$NATS_LOG" 2>&1 &
+NATS_PID=$!
+echo "  PID: $NATS_PID"
+sleep 1.5
+
+# -- 2. Start vclaw agent
+if command -v vclaw &>/dev/null; then
+  echo "Booting vclaw scheduler agent..."
+  vclaw run --daemon > "$AGENT_LOG" 2>&1 &
+  VCLAW_PID=$!
+  echo "  PID: $VCLAW_PID"
+else
+  echo "  vclaw binary not found -- skipping agent loop."
+  VCLAW_PID=""
+fi
+
+# -- 3. Start pi-web
+PI_WEB_PID=""
+if command -v pi-web &>/dev/null; then
+  echo "Starting pi-web workspace..."
+  pi-web start > "${DATA_DIR}/pi-web.log" 2>&1 &
+  PI_WEB_PID=$!
+  echo "  PID: $PI_WEB_PID"
+else
+  echo "  pi-web not found -- browser workspace unavailable."
+  echo "  Install: npm install -g @jmfederico/pi-web && pi-web install"
+fi
+
+# -- Save PIDs
+echo "$NATS_PID $VCLAW_PID" > "$PID_FILE"
+
+# -- 4. Open browser
+echo ""
+echo "Opening pi-web.dev workspace..."
+if [ -n "$PI_WEB_PID" ]; then
+  PI_WEB_URL="http://localhost:4321"
+else
+  PI_WEB_URL="https://pi-web.dev/?connect=ws://127.0.0.1:9222"
+fi
+if [[ "$OSTYPE" == "darwin"* ]]; then
+  open "$PI_WEB_URL" 2>/dev/null || true
+else
+  xdg-open "$PI_WEB_URL" &>/dev/null & true
+fi
+echo "  URL: $PI_WEB_URL"
+
+# -- 5. Optional onboard
+if [ -n "$ONBOARD_EMAIL" ]; then
+  echo ""
+  echo "=== Joining vchat.email Network ==="
+  echo "  Email: $ONBOARD_EMAIL"
+  if ! npx --yes @vchatemail/agent --version &>/dev/null 2>&1; then
+    echo "Installing @vchatemail/agent..."
+    npm install -g @vchatemail/agent 2>/dev/null || true
+  fi
+  npx @vchatemail/agent ensoul --email "$ONBOARD_EMAIL" || {
+    echo "  Onboarding skipped. Retry: vchat-onboard.sh $ONBOARD_EMAIL"
+  }
+fi
+
+# -- Summary
+echo ""
+echo "--------------------------------------------------------"
+echo "✔ Playground Active!"
+echo "  NATS Leaf Engine:   PID $NATS_PID"
+echo "  vclaw Agent Loop:   PID ${VCLAW_PID:-(not running)}"
+echo "  pi-web Workspace:   PID ${PI_WEB_PID:-(not running)}"
+echo ""
+echo "  Browse:             ${PI_WEB_URL}"
+echo ""
+echo "  Watch messages:     nats sub \">\""
+echo "  View logs:          tail -f ${NATS_LOG}"
+echo "  Stop everything:    vclaw-up --stop"
+echo "--------------------------------------------------------"
+
+if [ -n "$VCLAW_PID" ]; then
+  wait $NATS_PID $VCLAW_PID 2>/dev/null || true
+else
+  wait $NATS_PID 2>/dev/null || true
+fi
+UPEOF
+
+chmod +x "${INSTALL_DIR}/vclaw-up"
+echo -e "${GREEN}  ✔ Orchestrator: vclaw-up${NC}"
+
+# -------------------------------------------------------------
+# Step 7: Install pi-web (local PI WEB workspace)
+# -------------------------------------------------------------
+echo -e "\n${YELLOW}[extras] Installing pi-web.dev workspace...${NC}"
+if command -v pi-web &>/dev/null && pi-web version &>/dev/null; then
+    echo -e "${GREEN}  ✔ pi-web already installed${NC}"
+else
+    if command -v bun &>/dev/null; then
+        bun install -g @jmfederico/pi-web && echo -e "${GREEN}  ✔ pi-web installed${NC}" || {
+            echo -e "${YELLOW}  ⚠ Could not install pi-web via Bun. Trying npm...${NC}"
+            npm install -g @jmfederico/pi-web && echo -e "${GREEN}  ✔ pi-web installed${NC}" || {
+                echo -e "${RED}  ⚠ Could not install pi-web. Run: npm install -g @jmfederico/pi-web${NC}"
+            }
+        }
+    elif command -v npm &>/dev/null; then
+        npm install -g @jmfederico/pi-web && echo -e "${GREEN}  ✔ pi-web installed${NC}" || {
+            echo -e "${RED}  ⚠ Could not install pi-web. Run: npm install -g @jmfederico/pi-web${NC}"
+        }
+    else
+        echo -e "${RED}  ⚠ Need npm to install pi-web. Install Node.js first.${NC}"
+    fi
+fi
+
+# Install pi-web user service (launchd for macOS, systemd for Linux)
+if command -v pi-web &>/dev/null; then
+    pi-web install 2>/dev/null && echo -e "${GREEN}  ✔ pi-web service registered${NC}" || \
+        echo -e "${YELLOW}  ⚠ pi-web service registration skipped (user services may require manual setup)${NC}"
+fi
+
+# -------------------------------------------------------------
+# Step 8: Install vchat-agent network CLI
+# -------------------------------------------------------------
+# Step 8: Finalize PATH
+# -------------------------------------------------------------
+echo -e "\n${BLUE}=== Post-Installation ===${NC}"
+
+if [[ ":$PATH:" != *":${INSTALL_DIR}:"* ]]; then
+    if [ -n "$ZSH_VERSION" ]; then
+        PROFILE="${HOME}/.zshrc"
+    elif [ -n "$BASH_VERSION" ]; then
+        PROFILE="${HOME}/.bashrc"
+    else
+        PROFILE="${HOME}/.profile"
+    fi
+    echo "export PATH=\"\$PATH:${INSTALL_DIR}\"" >> "${PROFILE}"
+    echo -e "  Added ${INSTALL_DIR} to PATH in ${PROFILE}"
+fi
+
+echo ""
+echo -e "${GREEN}★ Setup complete! ★${NC}"
+echo ""
+echo "  Quick start:"
+echo "    ${CYAN}vclaw-up${NC}                  Launch local mesh"
+echo "    ${CYAN}vclaw-up --onboard you@email.com${NC}  Launch + join vchat.email network"
+echo "    ${CYAN}pi \"hello world\"${NC}          Chat with Pi Agent"
+echo ""
+echo "  Open a new terminal or: source ${PROFILE:-~/.profile}"
+echo ""

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@vclawhub/vclaw",
+  "version": "0.2.0",
+  "private": false,
+  "type": "module",
+  "description": "VClaw Hub — one-command setup for pi.dev + pi-web.dev + NATS leaf node + vchat.email network",
+  "keywords": [
+    "pi-agent",
+    "pi-web",
+    "coding-agent",
+    "ai-agent",
+    "vclaw",
+    "vchat",
+    "nats",
+    "bun"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VillageCity/vclaw-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/VillageCity/vclaw-agent/issues"
+  },
+  "homepage": "https://vclawhub.com",
+  "bin": {
+    "vclaw": "./dist/cli.js"
+  },
+  "files": [
+    "dist/cli.js",
+    "install.sh",
+    "vclaw-up",
+    "config/nats-leaf.conf",
+    "scripts/"
+  ],
+  "scripts": {
+    "build": "bun build ./src/cli.ts --target=bun --outdir=dist",
+    "compile:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 ./src/cli.ts --outfile=dist/vclaw-darwin-arm64",
+    "compile:darwin-x64": "bun build --compile --target=bun-darwin-x64 ./src/cli.ts --outfile=dist/vclaw-darwin-x64",
+    "compile:linux-x64": "bun build --compile --target=bun-linux-x64 ./src/cli.ts --outfile=dist/vclaw-linux-x64",
+    "compile:linux-arm64": "bun build --compile --target=bun-linux-arm64 ./src/cli.ts --outfile=dist/vclaw-linux-arm64",
+    "compile:all": "bun run compile:darwin-arm64 && bun run compile:darwin-x64 && bun run compile:linux-x64 && bun run compile:linux-arm64",
+    "dev": "bun --watch ./src/cli.ts",
+    "prepublishOnly": "bun run build",
+    "start": "bun run ./src/cli.ts"
+  },
+  "engines": {
+    "bun": ">=1.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/vchat-onboard.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# ============================================================
+# vchat-onboard.sh — Join the vchat.email agent network
+#
+# Wraps @vchatemail/agent CLI for human+agent signup/login.
+# Run this after vclaw-up to connect your agent to the mesh.
+# ============================================================
+set -euo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+YELLOW='\033[0;33m'
+NC='\033[0m'
+
+echo -e "${BLUE}=== vchat.email Agent Network Onboarding ===${NC}"
+echo ""
+echo -e "This will register your local vclaw agent on the ${CYAN}vchat.email${NC} mesh."
+echo -e "You'll need an email address and access to a browser to approve the agent."
+echo ""
+
+# ── Check for @vchatemail/agent ──────────────────────────────
+if ! npx --yes @vchatemail/agent --version &>/dev/null 2>&1; then
+  echo -e "${YELLOW}Installing @vchatemail/agent...${NC}"
+  bun install -g @vchatemail/agent 2>/dev/null || npm install -g @vchatemail/agent
+fi
+
+# ── Collect email ─────────────────────────────────────────────
+EMAIL="${1:-}"
+if [ -z "$EMAIL" ]; then
+  read -r -p "Enter your email (steward account): " EMAIL
+fi
+
+if [ -z "$EMAIL" ]; then
+  echo -e "${RED}Error: Email is required.${NC}"
+  echo "Usage: vchat-onboard.sh <email>"
+  exit 1
+fi
+
+# ── Check existing credentials ────────────────────────────────
+if npx @vchatemail/agent status 2>/dev/null | grep -q "Agent Identity"; then
+  echo -e "${YELLOW}⚠️  An agent is already onboarded on this machine.${NC}"
+  read -r -p "Overwrite existing credentials? (y/N): " CONFIRM
+  if [ "$CONFIRM" != "y" ] && [ "$CONFIRM" != "Y" ]; then
+    echo "Aborted."
+    exit 0
+  fi
+  FORCE="--force"
+else
+  FORCE=""
+fi
+
+# ── Generate agent name ──────────────────────────────────────
+HOSTNAME=$(hostname -s 2>/dev/null || echo "vclaw")
+AGENT_NAME="vclaw-${HOSTNAME}"
+
+echo ""
+echo -e "Agent name: ${CYAN}${AGENT_NAME}${NC}"
+echo -e "Steward:    ${CYAN}${EMAIL}${NC}"
+echo ""
+
+# ── Run ensoul (introduce → claim → token) ───────────────────
+echo -e "${BLUE}Starting onboarding flow...${NC}"
+echo ""
+echo -e "1. Generate Nkey identity"
+echo -e "2. Introduce agent to vgate (${CYAN}https://api.vchat.email${NC})"
+echo -e "3. Open browser for approval"
+echo -e "4. Wait for claim (up to 5 min)"
+echo -e "5. Store credentials to ${CYAN}~/.vchat/credentials.json${NC}"
+echo ""
+
+npx @vchatemail/agent ensoul \
+  --email "$EMAIL" \
+  --name "$AGENT_NAME" \
+  $FORCE
+
+# ── Done ──────────────────────────────────────────────────────
+echo ""
+echo -e "${GREEN}★ Agent onboarded to vchat.email!${NC}"
+echo ""
+echo -e "  Your agent is now visible at: ${CYAN}https://agents.vchat.email${NC}"
+echo -e "  Credentials: ${CYAN}~/.vchat/credentials.json${NC}"
+echo ""
+echo -e "Next: run ${CYAN}vclaw-up${NC} to start the local stack."
+echo "      Your agent will connect to the mesh via the local NATS leaf node."
+echo ""

package/vclaw-up

@@ -0,0 +1,236 @@
+#!/usr/bin/env bash
+# ============================================================
+# vclaw-up — Unified stack launcher for the Local Agentic Mesh
+#
+# Starts NATS leaf node + vclaw agent + pi-web workspace.
+# Optional: --onboard <email> to join the vchat.email network.
+#
+# Usage:
+#   vclaw-up                  — Launch the local stack
+#   vclaw-up --onboard <email> — Launch + onboard to vchat.email
+#   vclaw-up --stop           — Stop all services
+#   vclaw-up --status         — Show service status
+#   vclaw-up --help           — Show this help
+#   vclaw-up --uninstall      — Remove all binaries, config, data
+# ============================================================
+set -euo pipefail
+
+DATA_DIR="${HOME}/.local/share/vclaw"
+NATS_LOG="${DATA_DIR}/nats-server.log"
+AGENT_LOG="${DATA_DIR}/vclaw-agent.log"
+PID_FILE="${DATA_DIR}/.vclaw-up.pids"
+
+mkdir -p "${DATA_DIR}"
+
+# ── Help ──────────────────────────────────────────────────────
+if [ "${1:-}" = "--help" ] || [ "${1:-}" = "-h" ]; then
+  echo "vclaw-up — Local Agentic Mesh Launcher"
+  echo ""
+  echo "Usage:"
+  echo "  vclaw-up                     Start NATS + pi-web + vclaw"
+  echo "  vclaw-up --onboard <email>   Also onboard agent to vchat.email"
+  echo "  vclaw-up --stop              Stop all running services"
+  echo "  vclaw-up --status            Show service status"
+  echo "  vclaw-up --uninstall         Remove binaries, config, data"
+  echo "  vclaw-up --help              This message"
+  echo ""
+  echo "After starting, open another terminal and run:"
+  echo "  nats sub \">\"   — Watch real-time agent messages"
+  exit 0
+fi
+
+# ── Stop ──────────────────────────────────────────────────────
+if [ "${1:-}" = "--stop" ]; then
+  echo "Stopping pi-web..."
+  pi-web stop 2>/dev/null || true
+  if [ -f "$PID_FILE" ]; then
+    read -r NATS_PID VCLAW_PID < "$PID_FILE" 2>/dev/null || true
+    echo "Stopping NATS (PID ${NATS_PID:-?})..."
+    kill "${NATS_PID:-}" 2>/dev/null || true
+    echo "Stopping vclaw agent (PID ${VCLAW_PID:-?})..."
+    kill "${VCLAW_PID:-}" 2>/dev/null || true
+    rm -f "$PID_FILE"
+  fi
+  echo "✔ All services stopped."
+  exit 0
+fi
+
+# ── Status ────────────────────────────────────────────────────
+if [ "${1:-}" = "--status" ]; then
+  echo "vclaw-up — Service Status"
+  echo ""
+  PI_WEB_STATUS="$(pi-web status 2>/dev/null || echo 'not running')"
+  echo "  pi-web:          ${PI_WEB_STATUS}"
+  if [ -f "$PID_FILE" ]; then
+    read -r NATS_PID VCLAW_PID < "$PID_FILE" 2>/dev/null || true
+    if kill -0 "${NATS_PID:-}" 2>/dev/null; then
+      echo "  NATS server:     ✅ running (PID $NATS_PID)"
+    else
+      echo "  NATS server:     ❌ not running"
+    fi
+    if kill -0 "${VCLAW_PID:-}" 2>/dev/null; then
+      echo "  vclaw agent:     ✅ running (PID $VCLAW_PID)"
+    else
+      echo "  vclaw agent:     ❌ not running"
+    fi
+  else
+    echo "  NATS server:     ❌ not running"
+    echo "  vclaw agent:     ❌ not running"
+  fi
+  echo ""
+  echo "Logs:"
+  echo "  NATS:   $NATS_LOG"
+  echo "  Agent:  $AGENT_LOG"
+  echo "  pi-web: ${DATA_DIR}/pi-web.log"
+  exit 0
+fi
+
+# ── Uninstall ─────────────────────────────────────────────────
+if [ "${1:-}" = "--uninstall" ]; then
+  echo "Stopping services..."
+  pi-web stop 2>/dev/null || true
+  if [ -f "$PID_FILE" ]; then
+    read -r NATS_PID VCLAW_PID < "$PID_FILE"
+    kill "$NATS_PID" 2>/dev/null || true
+    kill "$VCLAW_PID" 2>/dev/null || true
+    rm -f "$PID_FILE"
+  fi
+  echo "Removing binaries..."
+  rm -f "${HOME}/.local/bin/nats-server"
+  rm -f "${HOME}/.local/bin/pi"
+  rm -f "${HOME}/.local/bin/vclaw"
+  rm -f "${HOME}/.local/bin/vclaw-up"
+  echo "Removing config and data..."
+  rm -rf "${DATA_DIR}"
+  echo ""
+  echo "✔ VClaw Hub uninstalled."
+  echo "  To remove globally installed npm/Bun packages:"
+  echo "    npm uninstall -g @jmfederico/pi-web @vchatemail/agent @earendil-works/pi-coding-agent"
+  echo "    bun uninstall -g @jmfederico/pi-web @vchatemail/agent @earendil-works/pi-coding-agent"
+  exit 0
+fi
+
+# ── Handle --onboard ──────────────────────────────────────────
+ONBOARD_EMAIL=""
+if [ "${1:-}" = "--onboard" ]; then
+  ONBOARD_EMAIL="${2:-}"
+  if [ -z "$ONBOARD_EMAIL" ]; then
+    echo "❌ Usage: vclaw-up --onboard <email>"
+    exit 1
+  fi
+fi
+
+echo "██╗   ██╗ ██████╗██╗      █████╗ ██╗    ██╗"
+echo "██║   ██║██╔════╝██║     ██╔══██╗██║    ██║"
+echo "██║   ██║██║     ██║     ███████║██║ █╗ ██║"
+echo "╚██╗ ██╔╝██║     ██║     ██╔══██║██║███╗██║"
+echo " ╚████╔╝ ╚██████╗███████╗██║  ██║╚███╔███╔╝"
+echo "  ╚═══╝   ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝ "
+echo ""
+echo "=== Initializing Local Agentic Mesh ==="
+echo ""
+
+# ── 1. Start NATS Leaf Node ───────────────────────────────────
+NATS_CONF="${DATA_DIR}/nats-leaf.conf"
+if [ ! -f "$NATS_CONF" ]; then
+  echo "Generating default NATS config..."
+  cat > "$NATS_CONF" << NATSEOF
+listen: 127.0.0.1:4222
+jetstream {
+  store_dir: "${DATA_DIR}/nats-data"
+}
+websocket {
+  port: 9222
+}
+NATSEOF
+fi
+
+echo "Starting local NATS Leaf Node server..."
+nats-server -c "$NATS_CONF" > "$NATS_LOG" 2>&1 &
+NATS_PID=$!
+echo "  PID: $NATS_PID"
+sleep 1.5
+
+# ── 2. Start vclaw agent ──────────────────────────────────────
+if command -v vclaw &>/dev/null; then
+  echo "Booting vclaw scheduler agent..."
+  vclaw run --daemon > "$AGENT_LOG" 2>&1 &
+  VCLAW_PID=$!
+  echo "  PID: $VCLAW_PID"
+else
+  echo "  vclaw binary not found — skipping agent loop."
+  VCLAW_PID=""
+fi
+
+# ── 3. Start pi-web ────────────────────────────────────────────
+PI_WEB_PID=""
+if command -v pi-web &>/dev/null; then
+  echo "Starting pi-web workspace..."
+  pi-web start > "${DATA_DIR}/pi-web.log" 2>&1 &
+  PI_WEB_PID=$!
+  echo "  PID: $PI_WEB_PID"
+else
+  echo "  pi-web not found — browser workspace unavailable."
+  echo "  Install: npm install -g @jmfederico/pi-web && pi-web install"
+fi
+
+# ── Save PIDs ──────────────────────────────────────────────────
+echo "$NATS_PID $VCLAW_PID" > "$PID_FILE"
+
+# ── 4. Open browser workspace ─────────────────────────────────
+echo ""
+echo "Opening pi-web workspace..."
+if [ -n "$PI_WEB_PID" ]; then
+  PI_WEB_URL="http://localhost:4321"
+else
+  PI_WEB_URL="https://pi-web.dev/?connect=ws://127.0.0.1:9222"
+fi
+if [[ "$OSTYPE" == "darwin"* ]]; then
+  open "$PI_WEB_URL" 2>/dev/null || true
+else
+  xdg-open "$PI_WEB_URL" &>/dev/null & true
+fi
+echo "  URL: $PI_WEB_URL"
+
+# ── 5. Optional: Onboard to vchat.email ────────────────────────
+if [ -n "$ONBOARD_EMAIL" ]; then
+  echo ""
+  echo "=== Joining vchat.email Network ==="
+  echo "  Email: $ONBOARD_EMAIL"
+  echo ""
+
+  if ! npx --yes @vchatemail/agent --version &>/dev/null 2>&1; then
+    echo "Installing @vchatemail/agent..."
+    npm install -g @vchatemail/agent 2>/dev/null || true
+  fi
+
+  npx @vchatemail/agent ensoul --email "$ONBOARD_EMAIL" || {
+    echo "⚠️  Onboarding skipped or failed. You can retry with:"
+    echo "   vchat-onboard.sh $ONBOARD_EMAIL"
+  }
+fi
+
+# ── Summary ────────────────────────────────────────────────────
+echo ""
+echo "--------------------------------------------------------"
+echo "✔ Playground Active!"
+echo "  NATS Leaf Engine:   PID $NATS_PID"
+echo "  vclaw Agent Loop:   PID ${VCLAW_PID:-(not running)}"
+echo "  pi-web Workspace:   PID ${PI_WEB_PID:-(not running)}"
+echo ""
+echo "  Browse:             ${PI_WEB_URL}"
+if [ -n "$ONBOARD_EMAIL" ]; then
+  echo "  vchat.email:       ✅ Onboarded as ${ONBOARD_EMAIL}"
+fi
+echo ""
+echo "  Watch messages:     nats sub \">\""
+echo "  View logs:          tail -f ${NATS_LOG}"
+echo "  Stop everything:    vclaw-up --stop"
+echo "--------------------------------------------------------"
+
+# Keep alive if run in foreground
+if [ -n "$VCLAW_PID" ]; then
+  wait $NATS_PID $VCLAW_PID 2>/dev/null || true
+else
+  wait $NATS_PID 2>/dev/null || true
+fi