velaclaw-dev 0.2.0

package/README.md

@@ -0,0 +1,211 @@
+<p align="center">
+  <img src="pic/banner.jpg" alt="Velaclaw — The control plane for team AI" width="100%" />
+</p>
+
+<h1 align="center">Velaclaw</h1>
+
+<p align="center">
+  <strong>The control plane for team AI.</strong><br/>
+  <sub>Shared intelligence. Isolated runtimes. Governed by design.</sub>
+</p>
+
+<p align="center">
+  <a href="#-quick-start">Quick Start</a> ·
+  <a href="#-core-capabilities">Core Capabilities</a> ·
+  <a href="#-architecture">Architecture</a> ·
+  <a href="#-roadmap">Roadmap</a>
+</p>
+
+<p align="center">
+  <img alt="Status" src="https://img.shields.io/badge/status-early--access-orange" />
+  <img alt="Runtime" src="https://img.shields.io/badge/runtime-Docker-blue" />
+  <img alt="Built on" src="https://img.shields.io/badge/built%20on-OpenClaw-black" />
+  <img alt="License" src="https://img.shields.io/badge/license-MIT-green" />
+</p>
+
+---
+
+> Your team is already using AI.
+> The question isn't whether — it's **who's in control.**
+
+Velaclaw is the answer: **one control plane** governing every AI runtime on your team.
+Team assets stay with the team. Member assets stay with the member. High-risk actions go through approval.
+**Runs on a single machine. Today.**
+
+---
+
+## 🧩 Core Capabilities
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+### 🎛️ Control-Plane First
+
+The host is the coordination layer. Team policies, shared assets, and approval decisions live in **one place** instead of being scattered across individual chat windows.
+
+</td>
+<td width="50%" valign="top">
+
+### 📦 Isolated Member Runtimes
+
+One Docker container per member. No host workspace mounts. No Docker socket exposure. **One member crashes — nothing else burns.**
+
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+
+### 🔐 Shared vs Private, by Default
+
+Velaclaw treats memory, skills, tools, workflows, documents, and bindings as **assets**.
+Some assets belong to the team. Others belong to the member. Team assets can be distributed as read-only snapshots, while member assets stay private by default.
+
+Shared assets now follow a governed publication flow:
+- members can submit into `drafts/` or `collab/`
+- untrusted roles require approval before publish
+- trusted publishers can publish without review
+- managers can approve, reject, or promote into the live snapshot
+
+</td>
+<td width="50%" valign="top">
+
+### ✅ Approval for High-Risk Actions
+
+Write operations, credential access, and cross-member actions do not execute directly. They go through the control plane first. **Approval is part of the system, not an afterthought.**
+
+</td>
+</tr>
+</table>
+
+---
+
+## 🏗️ Architecture
+
+```
+    ┌─────────────────────────────────────────────────┐
+    │              Control Plane (Host)                │
+    │                                                  │
+    │   policies  ·  shared-assets  ·  approvals       │
+    │   asset-distribution  ·  audit                   │
+    └──────────┬──────────┬──────────┬─────────────────┘
+               │          │          │
+         ┌─────▼────┐┌────▼─────┐┌──▼───────┐
+         │ Member A ││ Member B ││ Member C │
+         │ (Docker) ││ (Docker) ││ (Docker) │
+         │          ││          ││          │
+         │ private  ││ private  ││ private  │
+         │ assets   ││ assets   ││ assets   │
+         │ runtime  ││ runtime  ││ runtime  │
+         │ secrets  ││ secrets  ││ secrets  │
+         └──────────┘└──────────┘└──────────┘
+```
+
+> **🛡️ Security boundary**
+> Member containers never mount the host Docker socket, never touch the primary workspace, never access team secrets directly. Team assets are distributed via **read-only snapshots** — no writable shared mounts.
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# 1. Clone the repo
+git clone https://github.com/Zavianx/velaclaw-dev.git
+cd velaclaw-dev
+
+# 2. Read the architecture
+cat ARCHITECTURE.md
+
+# 3. Provision your first member runtime
+cat provision-member.md
+```
+
+---
+
+## 📁 Project Structure
+
+```text
+velaclaw-dev/
+├── ARCHITECTURE.md          # Control plane + member runtime design
+├── provision-member.md      # Member runtime provisioning guide
+├── team-assets/             # System/global shared team asset sources
+│   ├── policies/            # Team policies
+│   ├── shared-memory/       # Shared memory assets
+│   ├── shared-skills/       # Shared skill assets
+│   ├── shared-tools/        # Shared tool assets
+│   ├── shared-workflows/    # Shared workflow assets
+│   └── shared-docs/         # Shared document assets
+├── members/                 # Per-member runtime templates and private assets
+├── teams/                   # Team-scoped governed asset workspaces
+│   └── <slug>/
+│       └── assets/
+│           ├── drafts/
+│           ├── collab/
+│           ├── approvals/
+│           ├── published/
+│           │   └── releases/
+│           └── current/
+```
+
+---
+
+## 🗺️ Roadmap
+
+**Shipped**
+- [x] Control plane + member runtime architecture
+- [x] Team / member asset directory separation
+- [x] Member runtime provisioning flow
+- [x] Read-only snapshot distribution
+- [x] Team-scoped governed asset directories
+- [x] Member proposal -> approval -> publish workflow
+- [x] Direct publish for trusted roles
+- [x] Manager promote / approve / reject controls
+
+**Next**
+- [ ] Asset sync API
+- [ ] Rich approval workflow UI
+- [ ] Web Dashboard
+- [ ] Multi-machine deployment
+
+---
+
+## 💡 Why Velaclaw?
+
+<table>
+<thead>
+<tr>
+<th width="50%">Today</th>
+<th width="50%">With Velaclaw</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Everyone runs their own AI — no one knows who did what</td>
+<td><strong>One shared system</strong> for the team to work from</td>
+</tr>
+<tr>
+<td>Team knowledge and workflows are scattered across chat windows</td>
+<td><strong>Shared assets</strong> the team can keep building on together</td>
+</tr>
+<tr>
+<td>AI can touch code, credentials, and files directly</td>
+<td><strong>Isolated runtimes + approval gates</strong> around high-risk actions</td>
+</tr>
+<tr>
+<td>Structure gets added later, if at all</td>
+<td><strong>Assets and boundaries are built in from the start</strong></td>
+</tr>
+</tbody>
+</table>
+
+---
+
+<p align="center">
+  <strong>Built on <a href="https://github.com/openclaw/openclaw">OpenClaw</a></strong>
+</p>
+<p align="center">
+  <em>A better way for teams to work with AI.</em>
+</p>
+<p align="center">
+  <sub>Made for teams that take AI seriously.</sub>
+</p>

package/README.public.md

@@ -0,0 +1,115 @@
+<p align="center">
+  <img src="pic/banner.jpg" alt="Velaclaw — A better way for teams to work with AI" width="100%" />
+</p>
+
+<h1 align="center">Velaclaw</h1>
+
+<p align="center">
+  <strong>A better way for teams to work with AI.</strong><br/>
+  <sub>Shared where it should be. Private where it must be.</sub>
+</p>
+
+<p align="center">
+  <img alt="Status" src="https://img.shields.io/badge/status-early--access-orange" />
+  <img alt="Runtime" src="https://img.shields.io/badge/runtime-Docker-blue" />
+  <img alt="Built on" src="https://img.shields.io/badge/built%20on-OpenClaw-black" />
+</p>
+
+---
+
+> Teams are already using AI.
+> Velaclaw gives them a better way to work together.
+
+Velaclaw is a system for teams that want to work with AI together without turning everything into one shared trust boundary.
+It brings collaboration, structure, and clear asset boundaries into the same place.
+
+---
+
+## What Velaclaw is
+
+Velaclaw is built around three ideas:
+
+- **shared assets** the team can build on together
+- **private member runtimes** for work that should stay isolated
+- **approvals and boundaries** for actions that carry real risk
+
+In Velaclaw, memory, skills, tools, workflows, documents, and bindings are all treated as **assets**.
+Some belong to the team. Others belong to the member.
+
+---
+
+## Why it exists
+
+Most teams already use AI across chat windows, scripts, agents, and tools.
+What they usually do not have is a good shared system around it.
+
+Velaclaw is meant to change that.
+
+It helps teams:
+
+- build on shared assets over time
+- keep member-specific work private where it should be
+- introduce structure without turning collaboration into chaos
+- put approvals around high-risk actions
+
+---
+
+## Core capabilities
+
+- **Shared assets** for team memory, skills, tools, workflows, and docs
+- **Private runtimes** for member-specific execution
+- **Read-only asset distribution** for controlled sharing
+- **Approval-aware operations** for higher-risk actions
+- **Docker-based isolation** for practical deployment today
+
+---
+
+## Architecture
+
+```text
+    ┌─────────────────────────────────────────────────┐
+    │              Control Plane (Host)                │
+    │                                                  │
+    │   policies  ·  shared-assets  ·  approvals       │
+    │   asset-distribution  ·  audit                   │
+    └──────────┬──────────┬──────────┬─────────────────┘
+               │          │          │
+         ┌─────▼────┐┌────▼─────┐┌──▼───────┐
+         │ Member A ││ Member B ││ Member C │
+         │ (Docker) ││ (Docker) ││ (Docker) │
+         │          ││          ││          │
+         │ private  ││ private  ││ private  │
+         │ assets   ││ assets   ││ assets   │
+         │ runtime  ││ runtime  ││ runtime  │
+         │ secrets  ││ secrets  ││ secrets  │
+         └──────────┘└──────────┘└──────────┘
+```
+
+---
+
+## Current focus
+
+Velaclaw is still early.
+Current work is focused on:
+
+- control-plane foundations
+- asset modeling
+- isolated member runtimes
+- provisioning flow
+- approval-aware operations
+
+---
+
+## Status
+
+Velaclaw is in active development.
+The public repository is intended to communicate the product direction, architecture, and design principles as the system takes shape.
+
+---
+
+<p align="center">
+  <strong>Built on <a href="https://github.com/openclaw/openclaw">OpenClaw</a></strong>
+</p>
+<p align="center">
+  <em>A better way for teams to work with AI.</em>
+</p>

package/RELEASING.md

@@ -0,0 +1,162 @@
+# Velaclaw Dev Release Flow
+
+This is the formal dev-side flow for preparing a testable build for other people.
+
+## 1. Update The Working Tree
+
+Before cutting a tester build:
+
+```bash
+git status --short
+npm run build
+```
+
+Do not publish a tester build from a broken tree.
+
+## 2. Bring Up Local Dependencies
+
+LiteLLM:
+
+```bash
+docker compose -f services/litellm/docker-compose.yml up -d
+```
+
+Velaclaw:
+
+```bash
+npm run start
+```
+
+## 3. Run The Minimum Release Checks
+
+Required:
+
+```bash
+npm run release:check
+```
+
+Recommended before a real tester cut:
+
+```bash
+npm run smoke:skills
+npm run smoke:assets
+```
+
+Optional for larger drops:
+
+```bash
+npm run load:test-team
+```
+
+## 4. Check The Outputs
+
+You should have:
+
+- a healthy control plane on `127.0.0.1:4318`
+- a healthy LiteLLM stack on `127.0.0.1:4000`
+- fresh smoke artifacts in `artifacts/`
+
+At minimum, inspect:
+
+- latest `shared-skill-combo-test-*.json`
+- latest `shared-asset-stack-test-*.json`
+
+## 5. Sanity Check The Main Team
+
+Before handing the build to testers, confirm your real bots were not broken by the release candidate:
+
+- `testjjabot`
+- `Erwinyu_bot`
+- `Xiaoananabot`
+
+Expected state:
+
+- runtime container exists
+- runtime health is `healthy`
+- `/team` still loads
+
+## 6. Publish To npm
+
+Public npm:
+
+```bash
+npm login
+npm run publish:npm
+```
+
+GitHub Actions:
+
+- workflow: `.github/workflows/publish-npm.yml`
+- required secret: `NPM_TOKEN`
+
+## 7. Publish To A Private Registry
+
+Local shell path:
+
+```bash
+npm config set registry <private-registry-url>
+npm config set //<private-registry-host>/:_authToken <token>
+npm run publish:private
+```
+
+GitHub Actions path:
+
+- workflow: `.github/workflows/publish-private-registry.yml`
+- required secret: `PRIVATE_NPM_TOKEN`
+- workflow input: `registry_url`
+
+## 8. Publish The Tester Instructions
+
+Always ship the published package together with:
+
+- [TESTING.md](/home/ubuntu/.openclaw/workspace/velaclaw/TESTING.md)
+- [services/litellm/litellm.env.example](/home/ubuntu/.openclaw/workspace/velaclaw/services/litellm/litellm.env.example)
+
+And for the npm path, tell testers to start with:
+
+```bash
+npm install -g velaclaw-dev
+velaclaw init velaclaw-test
+cd velaclaw-test
+```
+
+Do not assume the tester knows:
+
+- where LiteLLM secrets live
+- startup order
+- which smoke scripts matter
+- what is intentionally unsupported
+
+## 9. Suggested Release Note Format
+
+Use a short note like this:
+
+```text
+Velaclaw Dev Tester Build
+
+Included:
+- control plane
+- team/member onboarding
+- shared skills
+- shared memory
+- shared workflows
+
+Not included:
+- MCP/server assets
+- multi-host deployment
+
+Start here:
+- npm install -g velaclaw-dev
+- velaclaw init velaclaw-test
+- TESTING.md
+```
+
+## 10. Exit Criteria
+
+A tester build is ready only if all of these are true:
+
+- `npm run release:check` passes
+- `npm run smoke:skills` passes
+- `npm run smoke:assets` passes
+- latest artifacts exist in `artifacts/`
+- the main team’s member runtimes still come back `healthy`

package/TESTING.md

@@ -0,0 +1,195 @@
+# Velaclaw Tester Install Guide
+
+This guide is the formal path for bringing up a local Velaclaw test environment for external testers.
+
+It assumes:
+
+- one Linux host
+- Docker Engine + Compose v2
+- Node.js 22+
+- a reachable upstream OpenAI-compatible endpoint for LiteLLM
+
+The current supported test scope is:
+
+- control plane at `http://127.0.0.1:4318`
+- LiteLLM on `http://127.0.0.1:4000`
+- team creation
+- invite acceptance
+- member runtime provisioning
+- Telegram/Discord member setup
+- shared `skills`, `memory`, and `workflows`
+
+Not part of the formal tester flow:
+
+- MCP/server assets
+- multi-host deployment
+- production HA setup
+
+## 1. Install The CLI
+
+Preferred path:
+
+```bash
+npm install -g velaclaw-dev
+```
+
+Then initialize a local workspace:
+
+```bash
+velaclaw init velaclaw-test
+cd velaclaw-test
+```
+
+If you are testing from a local checkout instead of npm:
+
+```bash
+git clone <your-private-dev-repo-url> velaclaw-dev
+cd velaclaw-dev
+npm install
+npm run build
+```
+
+## 2. Prerequisites
+
+Install:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y git curl jq docker-compose-v2 docker-buildx
+```
+
+Verify:
+
+```bash
+docker compose version
+docker buildx version
+node --version
+npm --version
+```
+
+## 3. Configure LiteLLM
+
+Create the local config directory:
+
+```bash
+mkdir -p ~/.config/velaclaw
+cp services/litellm/litellm.env.example ~/.config/velaclaw/litellm.env
+```
+
+Edit `~/.config/velaclaw/litellm.env` and set:
+
+- `POSTGRES_PASSWORD`
+- `DATABASE_URL`
+- `OPENAI_API_KEY`
+- `LITELLM_MASTER_KEY`
+
+Expected format:
+
+```dotenv
+POSTGRES_PASSWORD=change-me
+DATABASE_URL=postgresql://litellm:change-me@postgres:5432/litellm
+OPENAI_API_KEY=replace-with-your-upstream-key
+LITELLM_MASTER_KEY=replace-with-a-long-random-secret
+```
+
+Start LiteLLM:
+
+```bash
+docker compose -f services/litellm/docker-compose.yml up -d
+docker ps --format 'table {{.Names}}\t{{.Status}}' | grep velaclaw-litellm
+```
+
+## 4. Start Velaclaw
+
+Run the control plane:
+
+```bash
+velaclaw start
+```
+
+Default port:
+
+```text
+http://127.0.0.1:4318
+```
+
+If you want a different port:
+
+```bash
+velaclaw start --port 4318
+```
+
+## 5. Verify The Stack
+
+Basic verification:
+
+```bash
+velaclaw verify
+```
+
+Manual checks:
+
+```bash
+curl -fsS http://127.0.0.1:4318/health
+curl -fsS http://127.0.0.1:4318/api/teams
+open http://127.0.0.1:4318/team
+```
+
+## 6. Tester Workflow
+
+Recommended manual test path:
+
+1. Open `/team`
+2. Create a test team
+3. Create an invite for a test email
+4. Open `/invite/<code>`
+5. Accept the invite
+6. Configure a Telegram or Discord bot on the member page
+7. Start the member runtime
+8. Send the bot a message
+9. Verify the member responds
+
+## 7. Automated Smoke Tests
+
+Shared skills:
+
+```bash
+velaclaw smoke skills
+```
+
+Shared skills + memory + workflow:
+
+```bash
+velaclaw smoke assets
+```
+
+Large team control-plane load test:
+
+```bash
+velaclaw smoke load-test
+```
+
+Artifacts are written to:
+
+```text
+artifacts/
+```
+
+## 8. Current Known Limits
+
+- Default stable model path is `gpt-4.1-mini`
+- GPT-5 family support is not the default test path
+- MCP/server assets are intentionally out of scope
+- This guide is for a single-host setup, not a production cluster
+
+## 9. What Testers Should Report
+
+Ask testers to include:
+
+- host OS and Docker version
+- whether LiteLLM started cleanly
+- whether `/health` and `/api/teams` worked
+- whether invite acceptance succeeded
+- whether member runtime reached `healthy`
+- whether Telegram/Discord messages were answered
+- the exact artifact file if a smoke script was run