velaclaw-dev 0.2.0

package/.gitignore

@@ -0,0 +1,14 @@
+node_modules/
+dist/
+*.log
+state/*.json
+!state/.gitkeep
+
+members/*/runtime/secrets/*
+!members/*/runtime/secrets/.gitkeep
+
+members/*/runtime/workspace/*
+!members/*/runtime/workspace/.gitkeep
+
+members/*/runtime/config/team-policy.json
+members/*/runtime/config/team-usage.json

package/ARCHITECTURE.md

@@ -0,0 +1,143 @@
+# Velaclaw Architecture v1
+
+This directory defines a practical first-stage architecture for a team-oriented OpenClaw deployment using:
+
+- one primary host instance as the control plane
+- multiple secondary Docker instances as member runtimes
+- shared team assets separated from member-private assets
+- minimal direct sharing of writable state
+
+## Goals
+
+- keep the primary user instance in control
+- isolate each member runtime from the primary workspace
+- support both team-shared and member-private assets
+- avoid direct access from child containers to host Docker or host secrets
+- keep the design simple enough to run today on a single machine
+
+## High-level model
+
+### Control plane (host primary instance)
+Responsible for:
+- team policies
+- team shared memory
+- team shared skills
+- team shared tool definitions
+- approvals and audit decisions
+- future asset API / synchronization
+
+### Member runtime (one Docker container per member)
+Responsible for:
+- member-private memory
+- member-private skills
+- member-private workspace
+- member-private credentials/bindings
+- low-risk task execution
+
+## Storage split
+
+### Host control-plane assets
+- `team-assets/`
+  - shared-memory/
+  - shared-skills/
+  - shared-tools/
+  - shared-workflows/
+  - shared-docs/
+  - policies/
+- `teams/<team-slug>/assets/`
+  - drafts/
+  - collab/
+  - approvals/
+  - published/
+    - releases/
+  - current/
+
+### Per-member assets
+- `members/<member-id>/`
+  - private-memory/
+  - private-skills/
+  - private-tools/
+  - private-docs/
+  - runtime/
+    - config/
+    - workspace/
+    - secrets/
+    - logs/
+
+## Security rules
+
+1. Never mount host Docker socket into member containers.
+2. Never mount the primary workspace into member containers.
+3. Never store team secrets inside member runtime directories unless explicitly intended as team-level shared bindings.
+4. Member containers only get:
+   - their own config
+   - their own workspace
+   - their own secrets
+   - team-scoped read-only shared snapshots
+5. Prefer API-mediated or snapshot-based access to team assets instead of writable shared mounts.
+6. Treat `current/` as a published snapshot, not as a collaboration directory.
+
+## Shared vs private assets
+
+### Shared assets
+Examples:
+- common skills
+- playbooks / SOPs
+- non-sensitive team docs
+- common tool definitions
+- common market analysis templates
+
+## Governed publication flow
+
+Team members do not write directly into the live shared snapshot.
+
+Recommended lifecycle:
+
+1. member creates a draft or collab asset
+2. control plane checks the member's publication permission
+3. if required, the asset enters the approval queue
+4. manager/owner approves or rejects
+5. approved assets publish into the release set
+6. `current/` is updated for member runtimes
+
+## Role policy examples
+
+- `viewer`
+  - cannot propose shared assets
+- `member` / `contributor`
+  - can propose
+  - requires approval before publish
+- `publisher`
+  - can propose
+  - can publish without review
+- `manager` / `owner`
+  - can approve
+  - can promote collab assets into the published layer
+
+### Private assets
+Examples:
+- personal memory
+- private credentials
+- private Gmail or calendar bindings
+- private preferences
+- personal notes and drafts
+
+## Access model
+
+### Primary host instance can:
+- read and manage team assets
+- provision member runtimes
+- publish approved shared assets
+- eventually proxy high-risk actions
+
+### Member runtime can:
+- read its own private assets
+- read allowed team assets through controlled means
+- not directly modify host team assets unless explicitly synchronized/approved
+
+## Recommended next steps
+
+1. Treat this directory as the canonical Velaclaw control root.
+2. Create one member runtime from the provided Docker template.
+3. Keep shared assets read-only to member containers.
+4. Introduce an asset API later if two-way sync is needed.

package/README.dev.md

@@ -0,0 +1,208 @@
+<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 Dev</h1>
+
+<p align="center">
+  <strong>The private development repository for Velaclaw.</strong><br/>
+  <sub>Assets, runtimes, onboarding, and team operations — in progress.</sub>
+</p>
+
+<p align="center">
+  <a href="#-getting-started">Getting Started</a> ·
+  <a href="./TESTING.md">Tester Install</a> ·
+  <a href="./RELEASING.md">Release Flow</a> ·
+  <a href="#-core-capabilities">Core Capabilities</a> ·
+  <a href="#-project-structure">Project Structure</a> ·
+  <a href="#-roadmap">Roadmap</a>
+</p>
+
+<p align="center">
+  <img alt="Status" src="https://img.shields.io/badge/status-active--development-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="Repository" src="https://img.shields.io/badge/repo-private-lightgrey" />
+</p>
+
+---
+
+Velaclaw Dev is where the working system takes shape.
+This repository is focused on implementation: team assets, member runtimes, onboarding flow, runtime isolation, and the operator experience around them.
+
+---
+
+## 🧩 Core Capabilities
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+### 🎛️ Shared System for Team AI
+
+Velaclaw organizes AI work around **team assets** and **member assets** instead of leaving everything scattered across chats and one-off tools.
+
+</td>
+<td width="50%" valign="top">
+
+### 📦 Isolated Member Runtimes
+
+Each member runs inside an isolated Docker runtime with its own private assets, runtime config, and secrets.
+
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+
+### 🔐 Asset Boundaries
+
+Memory, skills, tools, workflows, documents, and bindings are treated as **assets**. Team assets and member assets are kept separate by design.
+
+</td>
+<td width="50%" valign="top">
+
+### ✅ Approval-Aware Operations
+
+High-risk actions go through the control plane first, so collaboration does not require giving up review or boundaries.
+
+</td>
+</tr>
+</table>
+
+---
+
+## 🏗️ 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  │
+         └──────────┘└──────────┘└──────────┘
+```
+
+> **🛡️ Security boundary**
+> Member containers never mount the host Docker socket, never touch the primary workspace, and never access team secrets directly. Team assets are distributed via read-only snapshots.
+
+---
+
+## 🚀 Getting Started
+
+```bash
+# 1. Clone the repo
+git clone https://github.com/Zavianx/velaclaw-dev.git
+cd velaclaw-dev
+
+# 2. Review the architecture
+cat ARCHITECTURE.md
+
+# 3. Review provisioning flow
+cat provision-member.md
+```
+
+### Run the local prototype
+
+```bash
+npm install -g velaclaw-dev
+velaclaw init velaclaw-test
+cd velaclaw-test
+velaclaw start
+```
+
+By default the local service starts on:
+
+```bash
+http://127.0.0.1:4318
+```
+
+### Formal Tester Flow
+
+If you are preparing a build for other people to test, do not send them this README alone.
+Use these two documents:
+
+- [TESTING.md](/home/ubuntu/.openclaw/workspace/velaclaw/TESTING.md)
+- [RELEASING.md](/home/ubuntu/.openclaw/workspace/velaclaw/RELEASING.md)
+
+They cover:
+
+- host prerequisites
+- LiteLLM env setup
+- local startup order
+- smoke verification
+- current supported test scope
+
+The intended tester install path is now:
+
+```bash
+npm install -g velaclaw-dev
+velaclaw init velaclaw-test
+cd velaclaw-test
+velaclaw start
+```
+
+---
+
+## 📁 Project Structure
+
+```text
+velaclaw-dev/
+├── ARCHITECTURE.md          # Control plane + member runtime design
+├── provision-member.md      # Member runtime provisioning guide
+├── team-assets/             # 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
+├── shared-snapshots/        # Read-only asset snapshots for controlled distribution
+├── src/                     # Local control-plane prototype
+├── state/                   # Team state and invitations
+└── pic/                     # Repo imagery
+```
+
+---
+
+## 🗺️ Roadmap
+
+**Shipped**
+- [x] Control plane + member runtime architecture
+- [x] Team / member asset separation
+- [x] Member runtime provisioning flow
+- [x] Read-only snapshot distribution
+- [x] Local control-plane MVP
+
+**Next**
+- [ ] Asset sync API
+- [ ] Approval workflow engine
+- [ ] Runtime health and lifecycle views
+- [ ] Invitee-facing onboarding flow
+- [ ] Operator dashboard
+
+---
+
+## Notes
+
+This repository is intentionally more implementation-focused than the public repository.
+Use the public repo for product-facing messaging, and this repo for the evolving system itself.
+
+---
+
+<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/README.local-before-remote-sync.md

@@ -0,0 +1,224 @@
+# Velaclaw
+
+**Velaclaw** is a control-plane-first multi-team AI product concept built on top of [OpenClaw](https://github.com/openclaw/openclaw).
+
+Core idea:
+- shared team intelligence
+- private Docker-isolated member runtimes
+- Docker-isolated member execution
+- team assets and member assets split by default
+- approval-oriented handling for high-risk actions
+- manager-owned quota policy per member
+
+## Current structure
+
+- `ARCHITECTURE.md` — control-plane + member-runtime design
+- `team-assets/` — shared team assets and policies
+- `members/` — per-member runtime templates
+- `shared-snapshots/` — read-only team asset snapshots for controlled distribution
+- `provision-member.md` — how to create a new member runtime
+- `src/` — runnable local control-plane MVP
+
+## MVP prototype
+
+The repository now includes a runnable local Node/TypeScript prototype that reads the repository layout and exposes it as a control-plane API.
+
+### Endpoints
+
+- `GET /health`
+- `GET /team`
+- `GET /team/:slug`
+- `GET /invite/:code`
+- `GET /api/team`
+- `GET /api/teams`
+- `GET /api/teams/:slug`
+- `GET /api/team/assets`
+- `GET /api/members`
+- `GET /api/teams/:slug/members`
+- `GET /api/members/:id/assets`
+- `GET /api/teams/:slug/members/:id/assets`
+- `GET /api/members/:id/runtime`
+- `GET /api/teams/:slug/members/:id/runtime`
+- `POST /api/members/provision`
+- `POST /api/teams`
+- `POST /api/teams/:slug/profile`
+- `POST /api/teams/:slug/invitations`
+- `POST /api/teams/:slug/members/provision`
+- `POST /api/teams/:slug/members/:id/quota`
+- `POST /api/teams/:slug/members/:id/secrets/telegram`
+- `POST /api/teams/:slug/members/:id/onboard/start`
+- `POST /api/teams/:slug/members/:id/runtime/:action`
+- `POST /api/members/:id/secrets/telegram`
+- `POST /api/members/:id/onboard/start`
+- `POST /api/members/:id/runtime/:action`
+- `POST /api/team/profile`
+- `POST /api/team/invitations`
+- `POST /api/team/members/:id/quota`
+- `POST /api/team/invitations/:id/revoke`
+- `POST /api/team/invitations/:code/accept`
+
+### What it does today
+
+- lists team-shared asset buckets under `team-assets/`
+- lists read-only snapshot buckets under `shared-snapshots/`
+- lists member runtime folders under `members/`
+- reports whether a member has runtime/config/compose files
+- exposes a lightweight landing page at `/`
+- exposes a real team workspace at `/team`
+- exposes a multi-team index at `/team` and per-team workspaces at `/team/:slug`
+- provisions a new member runtime from `members/member-template/`
+- auto-assigns the next free local port starting from `18800`
+- generates a gateway token when one is not supplied
+- stores team profile and invitation state in `state/team.json`
+- turns a shareable invite link into a provisioned member skeleton
+- writes a manager-owned runtime policy file for each accepted member
+- lets the team manager update member quotas from `/team`
+- syncs allowed models and max thinking into the member runtime config
+- ships a member-side quota guard plugin that hard-blocks paused members and message quota overruns
+- surfaces Docker runtime status, launch commands, and start/stop/restart actions for each member
+- lets the manager save a member Telegram bot token from the control plane
+- moves a member runtime from `needs-secrets` to `ready` once policy + token are both present
+- exposes a bot-side command surface through the main OpenClaw bot plugin
+- supports multiple teams, each with its own invites, quota policy, and member runtime tree
+
+## Getting started
+
+### Run locally
+
+```bash
+npm install
+npm run dev
+```
+
+By default the local service starts on:
+
+```bash
+http://127.0.0.1:4318
+```
+
+### First steps
+
+```bash
+# 1. Clone the repo
+git clone https://github.com/Zavianx/velaclaw-dev.git
+cd velaclaw-dev
+
+# 2. Start the local control plane
+npm install
+npm run dev
+
+# 3. Open the team workspace
+open http://127.0.0.1:4318/team
+```
+
+If `open` is unavailable on your machine, just visit the URL in your browser.
+
+### Production-style run
+
+```bash
+npm run build
+npm start
+```
+
+### Provision a member
+
+```bash
+curl -X POST http://127.0.0.1:4318/api/members/provision \
+  -H 'content-type: application/json' \
+  -d '{
+    "memberId": "zane",
+    "telegramUserId": "8555695623",
+    "identityName": "小虾-zane"
+  }'
+```
+
+Response highlights:
+
+- generated member paths
+- selected local port
+- generated gateway token
+- pending placeholders still requiring operator input
+
+### Team and invitation flow
+
+Open:
+
+```bash
+http://127.0.0.1:4318/team
+```
+
+From `/team` you can:
+
+- list existing teams
+- create a new team
+- enter `/team/:slug` for a specific team
+
+Inside a specific team page you can:
+
+- set your team name and description
+- set the visible team manager label
+- create invite links
+- open `/invite/<code>` pages
+- accept an invite and provision a new member skeleton
+- pause or tighten a member quota without touching the member's private workspace
+- inspect runtime readiness and use start/stop/restart controls
+- paste a member Telegram bot token and finish onboarding from `/team`
+
+### Bot command surface
+
+The main OpenClaw bot now loads a local plugin that intercepts team commands:
+
+- `/team`
+- `/team <slug>`
+- `/create team <slug> <name>`
+- `/members`
+- `/invite <member_id> <label>`
+- `/create invite <member_id> <label>`
+- `/join <invite_code> [identity_name]`
+- `/runtime <member_id>`
+
+This means the operator can manage Velaclaw from the bot chat instead of only through the web page.
+
+Current shape:
+
+- `/team` lists teams and tells you what is currently selected
+- `/team <slug>` switches into a specific team context
+- `/create team <slug> <name>` creates a new team from chat
+- `/invite` creates an invitation code
+- `/join` accepts the invitation using the sender's Telegram user id
+- `/runtime` shows the target member runtime state and launch commands
+
+## Current enforcement model
+
+- each accepted member gets a Docker-isolated runtime skeleton
+- the team manager owns quota policy in the control plane
+- accepted members receive `runtime/config/team-policy.json`
+- the member runtime loads `member-quota-guard`, which currently enforces:
+  - paused / active runtime state
+  - daily message quota
+  - monthly message quota
+- allowed models and max thinking are synchronized into the generated member `openclaw.json`
+- `/team` now shows Docker reachability, expected container name, published port, and launch commands for each member
+- member Telegram bot tokens are written to the member runtime secrets directory with `0600` permissions
+
+Current gap:
+
+- `maxSubagents` is stored in policy, but the current member template still keeps subagents disabled by default
+- runtime actions use host Docker via `sudo -n docker`, so production hardening still needs a more explicit execution boundary
+
+## Positioning
+
+Velaclaw is not just a chat UI or a generic team agent hub.
+It is intended to become a:
+
+- team AI control plane
+- shared/private asset governance layer
+- isolated runtime management model for OpenClaw-based teams
+
+## Next likely steps
+
+- add snapshot publish/sync actions
+- add policy-aware approval flow
+- add stronger runtime health/detail views
+- add a full invitee-facing onboarding page instead of operator-only setup on `/team`
+- add a real operator dashboard