fix(docker): strip hardcoded model/provider assumptions from fleet doc

Model choices and provider prereqs belong in onboarding/settings,
not static documentation.

apps/api/src/app.module.ts

@@ -39,7 +39,6 @@ import { JobStepsModule } from "./job-steps/job-steps.module";
 import { CoordinatorIntegrationModule } from "./coordinator-integration/coordinator-integration.module";
 import { FederationModule } from "./federation/federation.module";
 import { CredentialsModule } from "./credentials/credentials.module";
-import { CryptoModule } from "./crypto/crypto.module";
 import { MosaicTelemetryModule } from "./mosaic-telemetry";
 import { SpeechModule } from "./speech/speech.module";
 import { DashboardModule } from "./dashboard/dashboard.module";
@@ -112,7 +111,6 @@ import { RlsContextInterceptor } from "./common/interceptors/rls-context.interce
     CoordinatorIntegrationModule,
     FederationModule,
     CredentialsModule,
-    CryptoModule,
     MosaicTelemetryModule,
     SpeechModule,
     DashboardModule,

apps/api/src/crypto/crypto.module.ts

@@ -1,10 +0,0 @@
-import { Module } from "@nestjs/common";
-import { ConfigModule } from "@nestjs/config";
-import { CryptoService } from "./crypto.service";
-
-@Module({
-  imports: [ConfigModule],
-  providers: [CryptoService],
-  exports: [CryptoService],
-})
-export class CryptoModule {}

apps/api/src/crypto/crypto.service.spec.ts

@@ -1,71 +0,0 @@
-import { describe, it, expect, beforeEach } from "vitest";
-import { ConfigService } from "@nestjs/config";
-import { CryptoService } from "./crypto.service";
-
-function createConfigService(secret?: string): ConfigService {
-  return {
-    get: (key: string) => {
-      if (key === "MOSAIC_SECRET_KEY") {
-        return secret;
-      }
-      return undefined;
-    },
-  } as unknown as ConfigService;
-}
-
-describe("CryptoService", () => {
-  let service: CryptoService;
-
-  beforeEach(() => {
-    service = new CryptoService(createConfigService("this-is-a-test-secret-key-with-32+chars"));
-  });
-
-  it("encrypt -> decrypt roundtrip", () => {
-    const plaintext = "my-secret-api-key";
-
-    const encrypted = service.encrypt(plaintext);
-    const decrypted = service.decrypt(encrypted);
-
-    expect(encrypted.startsWith("enc:")).toBe(true);
-    expect(decrypted).toBe(plaintext);
-  });
-
-  it("decrypt rejects tampered ciphertext", () => {
-    const encrypted = service.encrypt("sensitive-token");
-    const payload = encrypted.slice(4);
-    const bytes = Buffer.from(payload, "base64");
-
-    bytes[bytes.length - 1] = bytes[bytes.length - 1]! ^ 0xff;
-
-    const tampered = `enc:${bytes.toString("base64")}`;
-
-    expect(() => service.decrypt(tampered)).toThrow();
-  });
-
-  it("decrypt rejects non-encrypted string", () => {
-    expect(() => service.decrypt("plain-text-value")).toThrow();
-  });
-
-  it("isEncrypted detects prefix correctly", () => {
-    expect(service.isEncrypted("enc:abc")).toBe(true);
-    expect(service.isEncrypted("ENC:abc")).toBe(false);
-    expect(service.isEncrypted("plain-text")).toBe(false);
-  });
-
-  it("generateToken returns 64-char hex string", () => {
-    const token = service.generateToken();
-
-    expect(token).toMatch(/^[0-9a-f]{64}$/);
-  });
-
-  it("different plaintexts produce different ciphertexts (random IV)", () => {
-    const encryptedA = service.encrypt("value-a");
-    const encryptedB = service.encrypt("value-b");
-
-    expect(encryptedA).not.toBe(encryptedB);
-  });
-
-  it("missing MOSAIC_SECRET_KEY throws on construction", () => {
-    expect(() => new CryptoService(createConfigService(undefined))).toThrow();
-  });
-});

apps/api/src/crypto/crypto.service.ts

@@ -1,82 +0,0 @@
-import { Injectable } from "@nestjs/common";
-import { ConfigService } from "@nestjs/config";
-import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from "crypto";
-
-const ALGORITHM = "aes-256-gcm";
-const ENCRYPTED_PREFIX = "enc:";
-const IV_LENGTH = 12;
-const AUTH_TAG_LENGTH = 16;
-const DERIVED_KEY_LENGTH = 32;
-const HKDF_SALT = "mosaic.crypto.v1";
-const HKDF_INFO = "mosaic-db-secret-encryption";
-
-@Injectable()
-export class CryptoService {
-  private readonly key: Buffer;
-
-  constructor(private readonly config: ConfigService) {
-    const secret = this.config.get<string>("MOSAIC_SECRET_KEY");
-
-    if (!secret) {
-      throw new Error("MOSAIC_SECRET_KEY environment variable is required");
-    }
-
-    if (secret.length < 32) {
-      throw new Error("MOSAIC_SECRET_KEY must be at least 32 characters");
-    }
-
-    this.key = Buffer.from(
-      hkdfSync(
-        "sha256",
-        Buffer.from(secret, "utf8"),
-        Buffer.from(HKDF_SALT, "utf8"),
-        Buffer.from(HKDF_INFO, "utf8"),
-        DERIVED_KEY_LENGTH
-      )
-    );
-  }
-
-  encrypt(plaintext: string): string {
-    const iv = randomBytes(IV_LENGTH);
-    const cipher = createCipheriv(ALGORITHM, this.key, iv);
-    const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
-    const authTag = cipher.getAuthTag();
-    const payload = Buffer.concat([iv, ciphertext, authTag]).toString("base64");
-
-    return `${ENCRYPTED_PREFIX}${payload}`;
-  }
-
-  decrypt(encrypted: string): string {
-    if (!this.isEncrypted(encrypted)) {
-      throw new Error("Value is not encrypted");
-    }
-
-    const payloadBase64 = encrypted.slice(ENCRYPTED_PREFIX.length);
-
-    try {
-      const payload = Buffer.from(payloadBase64, "base64");
-      if (payload.length < IV_LENGTH + AUTH_TAG_LENGTH) {
-        throw new Error("Encrypted payload is too short");
-      }
-
-      const iv = payload.subarray(0, IV_LENGTH);
-      const authTag = payload.subarray(payload.length - AUTH_TAG_LENGTH);
-      const ciphertext = payload.subarray(IV_LENGTH, payload.length - AUTH_TAG_LENGTH);
-
-      const decipher = createDecipheriv(ALGORITHM, this.key, iv);
-      decipher.setAuthTag(authTag);
-
-      return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
-    } catch {
-      throw new Error("Failed to decrypt value");
-    }
-  }
-
-  isEncrypted(value: string): boolean {
-    return value.startsWith(ENCRYPTED_PREFIX);
-  }
-
-  generateToken(): string {
-    return randomBytes(32).toString("hex");
-  }
-}

docker/OPENCLAW-FLEET.md

@@ -0,0 +1,49 @@
+# Mosaic Agent Fleet
+
+Multi-agent deployment for Mosaic Stack using OpenClaw containers on Docker Swarm.
+
+## Architecture
+
+Each agent runs as an isolated OpenClaw Gateway instance with its own:
+
+- **Workspace** — persistent volume for agent files and memory
+- **State** — persistent volume for auth tokens and sessions
+- **Config** — template rendered at startup from environment variables
+
+Agents communicate with the Mosaic API via the OpenAI-compatible
+`/v1/chat/completions` endpoint. The Mosaic WebUI routes chat requests
+to agents through the `OpenClawGatewayModule`.
+
+## Default Agent Roles
+
+| Agent             | Role         | Description                                 |
+| ----------------- | ------------ | ------------------------------------------- |
+| mosaic-main       | Orchestrator | User-facing gateway, routes to other agents |
+| mosaic-projects   | Developer    | Implementation, coding, PRs                 |
+| mosaic-research   | Research     | Web search, analysis, discovery             |
+| mosaic-operations | Operations   | Monitoring, health checks, alerts           |
+
+> **Models and providers are configured per-deployment** via environment
+> variables and the Mosaic Settings UI — not hardcoded in these files.
+> See the [Setup Guide](openclaw-instances/README.md) for env var reference.
+
+## Prerequisites
+
+- Docker Swarm initialized on target host
+- Mosaic Stack running (`mosaic-stack_internal` network available)
+- At least one LLM provider API key (Z.ai, OpenAI, Anthropic, etc.)
+
+## Quick Start
+
+1. **Configure** — Fill in `docker/openclaw-instances/*.env` files
+2. **Deploy** — `docker stack deploy -c docker/openclaw-compose.yml mosaic-agents`
+3. **Auth** — If needed, run `openclaw auth` inside a container (or via Mosaic terminal)
+4. **Verify** — `docker stack services mosaic-agents`
+
+See [openclaw-instances/README.md](openclaw-instances/README.md) for detailed setup.
+
+## Future: Onboarding Wizard
+
+Model assignments, provider configuration, and agent customization will be
+managed through the Mosaic WebUI onboarding wizard and Settings pages (MS22-P4).
+Until then, use environment variables per the README.

docker/openclaw-compose.yml

@@ -0,0 +1,150 @@
+# Mosaic Agent Fleet — OpenClaw Docker Swarm Stack
+# Deploy: docker stack deploy -c docker/openclaw-compose.yml mosaic-agents
+# All config via env vars — see openclaw-instances/*.env
+
+services:
+  mosaic-main:
+    image: alpine/openclaw:latest
+    command: ["/config/entrypoint.sh"]
+    env_file:
+      - ./openclaw-instances/mosaic-main.env
+    environment:
+      OPENCLAW_CONFIG_PATH: /tmp/openclaw.json
+    volumes:
+      - mosaic-main-config:/config:ro
+      - mosaic-main-state:/home/node/.openclaw
+    networks:
+      - mosaic-stack_internal
+    healthcheck:
+      test: ["CMD", "openclaw", "gateway", "health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 20s
+    deploy:
+      replicas: 1
+      restart_policy:
+        condition: on-failure
+        delay: 5s
+        max_attempts: 3
+      resources:
+        limits:
+          memory: 2G
+        reservations:
+          memory: 512M
+      labels:
+        - com.mosaic.agent=mosaic-main
+        - com.mosaic.role=orchestrator
+
+  mosaic-projects:
+    image: alpine/openclaw:latest
+    command: ["/config/entrypoint.sh"]
+    env_file:
+      - ./openclaw-instances/mosaic-projects.env
+    environment:
+      OPENCLAW_CONFIG_PATH: /tmp/openclaw.json
+    volumes:
+      - mosaic-projects-config:/config:ro
+      - mosaic-projects-state:/home/node/.openclaw
+    networks:
+      - mosaic-stack_internal
+    healthcheck:
+      test: ["CMD", "openclaw", "gateway", "health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 20s
+    deploy:
+      replicas: 1
+      restart_policy:
+        condition: on-failure
+        delay: 10s
+        max_attempts: 3
+      resources:
+        limits:
+          memory: 4G
+        reservations:
+          memory: 1G
+      labels:
+        - com.mosaic.agent=mosaic-projects
+        - com.mosaic.role=developer
+
+  mosaic-research:
+    image: alpine/openclaw:latest
+    command: ["/config/entrypoint.sh"]
+    env_file:
+      - ./openclaw-instances/mosaic-research.env
+    environment:
+      OPENCLAW_CONFIG_PATH: /tmp/openclaw.json
+    volumes:
+      - mosaic-research-config:/config:ro
+      - mosaic-research-state:/home/node/.openclaw
+    networks:
+      - mosaic-stack_internal
+    healthcheck:
+      test: ["CMD", "openclaw", "gateway", "health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 20s
+    deploy:
+      replicas: 1
+      restart_policy:
+        condition: on-failure
+        delay: 10s
+        max_attempts: 3
+      resources:
+        limits:
+          memory: 1G
+        reservations:
+          memory: 256M
+      labels:
+        - com.mosaic.agent=mosaic-research
+        - com.mosaic.role=research
+
+  mosaic-operations:
+    image: alpine/openclaw:latest
+    command: ["/config/entrypoint.sh"]
+    env_file:
+      - ./openclaw-instances/mosaic-operations.env
+    environment:
+      OPENCLAW_CONFIG_PATH: /tmp/openclaw.json
+    volumes:
+      - mosaic-operations-config:/config:ro
+      - mosaic-operations-state:/home/node/.openclaw
+    networks:
+      - mosaic-stack_internal
+    healthcheck:
+      test: ["CMD", "openclaw", "gateway", "health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 20s
+    deploy:
+      replicas: 1
+      restart_policy:
+        condition: on-failure
+        delay: 10s
+        max_attempts: 3
+      resources:
+        limits:
+          memory: 1G
+        reservations:
+          memory: 256M
+      labels:
+        - com.mosaic.agent=mosaic-operations
+        - com.mosaic.role=operations
+
+networks:
+  mosaic-stack_internal:
+    external: true
+
+volumes:
+  mosaic-main-config:
+  mosaic-main-state:
+  mosaic-projects-config:
+  mosaic-projects-state:
+  mosaic-research-config:
+  mosaic-research-state:
+  mosaic-operations-config:
+  mosaic-operations-state:

docker/openclaw-instances/README.md

@@ -0,0 +1,97 @@
+# Mosaic Agent Fleet — Setup Guide
+
+## Prerequisites
+
+- Docker Swarm initialized on target host
+- Mosaic Stack running (Postgres, Valkey on `mosaic-stack_internal` network)
+
+## 1. Configure Environment Variables
+
+Copy and fill in each agent's `.env` file:
+
+```bash
+cd docker/openclaw-instances
+
+# Required for each agent:
+# ZAI_API_KEY         — Your Z.ai API key (or other LLM provider key)
+# OPENCLAW_GATEWAY_TOKEN — Unique bearer token per agent
+
+# Generate unique tokens:
+for agent in main projects research operations; do
+  echo "OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)"
+done
+```
+
+### Optional: Local Ollama
+
+If you have an Ollama instance, add to any agent's `.env`:
+
+```bash
+OLLAMA_BASE_URL=http://your-ollama-host:11434
+OLLAMA_MODEL=cogito  # or any model you have pulled
+```
+
+The entrypoint script will automatically inject the Ollama provider at startup.
+
+### Optional: Override Default Model
+
+```bash
+OPENCLAW_MODEL=anthropic/claude-sonnet-4-6
+```
+
+## 2. Populate Config Volumes
+
+Each agent needs its `.json.template` file in its config volume:
+
+```bash
+# Create config directories and copy templates
+for agent in main projects research operations; do
+  mkdir -p /var/lib/docker/volumes/mosaic-agents_mosaic-${agent}-config/_data/
+  cp openclaw-instances/mosaic-${agent}.json.template \
+     /var/lib/docker/volumes/mosaic-agents_mosaic-${agent}-config/_data/openclaw.json.template
+  cp openclaw-instances/entrypoint.sh \
+     /var/lib/docker/volumes/mosaic-agents_mosaic-${agent}-config/_data/entrypoint.sh
+done
+```
+
+## 3. Deploy
+
+```bash
+docker stack deploy -c docker/openclaw-compose.yml mosaic-agents
+docker stack services mosaic-agents
+```
+
+## 4. First-Time Auth (if needed)
+
+For providers requiring OAuth (e.g., Anthropic):
+
+```bash
+docker exec -it $(docker ps -q -f name=mosaic-main) openclaw auth
+```
+
+Follow the device-code flow in your browser. Tokens persist in the state volume.
+
+You can also use the Mosaic WebUI terminal (xterm.js) for this.
+
+## 5. Verify
+
+```bash
+# Check health
+curl http://localhost:18789/health
+
+# Test chat completions endpoint
+curl http://localhost:18789/v1/chat/completions \
+  -H "Authorization: Bearer YOUR_GATEWAY_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"openclaw:main","messages":[{"role":"user","content":"hello"}]}'
+```
+
+## Environment Variable Reference
+
+| Variable                 | Required | Description                                       |
+| ------------------------ | -------- | ------------------------------------------------- |
+| `ZAI_API_KEY`            | Yes\*    | Z.ai API key (\*or other provider key)            |
+| `OPENCLAW_GATEWAY_TOKEN` | Yes      | Bearer token for this agent (unique per instance) |
+| `OPENCLAW_MODEL`         | No       | Override default model (default: `zai/glm-5`)     |
+| `OLLAMA_BASE_URL`        | No       | Ollama endpoint (e.g., `http://10.1.1.42:11434`)  |
+| `OLLAMA_MODEL`           | No       | Ollama model name (default: `cogito`)             |

docker/openclaw-instances/entrypoint.sh

@@ -0,0 +1,53 @@
+#!/bin/sh
+# Mosaic Agent Fleet — OpenClaw container entrypoint
+# Renders config template from env vars, optionally adds Ollama provider, starts gateway
+set -e
+
+TEMPLATE="/config/openclaw.json.template"
+CONFIG="/tmp/openclaw.json"
+
+if [ ! -f "$TEMPLATE" ]; then
+  echo "ERROR: Config template not found at $TEMPLATE"
+  echo "Mount your config volume at /config with a .json.template file"
+  exit 1
+fi
+
+# Validate required env vars
+: "${OPENCLAW_GATEWAY_TOKEN:?OPENCLAW_GATEWAY_TOKEN is required (generate: openssl rand -hex 32)}"
+
+# Render template with env var substitution
+envsubst < "$TEMPLATE" > "$CONFIG"
+
+# If OLLAMA_BASE_URL is set, inject Ollama provider into config
+if [ -n "$OLLAMA_BASE_URL" ]; then
+  # Use python3 if available, fall back to node
+  if command -v python3 >/dev/null 2>&1; then
+    python3 -c "
+import json, sys
+with open('$CONFIG') as f: cfg = json.load(f)
+cfg.setdefault('models', {})['mode'] = 'merge'
+cfg['models'].setdefault('providers', {})['ollama'] = {
+  'baseUrl': '$OLLAMA_BASE_URL/v1',
+  'api': 'openai-completions',
+  'models': [{'id': '${OLLAMA_MODEL:-cogito}', 'name': '${OLLAMA_MODEL:-cogito} (Local)', 'reasoning': False, 'input': ['text'], 'cost': {'input':0,'output':0,'cacheRead':0,'cacheWrite':0}, 'contextWindow': 128000, 'maxTokens': 8192}]
+}
+with open('$CONFIG','w') as f: json.dump(cfg, f, indent=2)
+"
+    echo "Ollama provider added: $OLLAMA_BASE_URL (model: ${OLLAMA_MODEL:-cogito})"
+  elif command -v node >/dev/null 2>&1; then
+    node -e "
+const fs = require('fs');
+const cfg = JSON.parse(fs.readFileSync('$CONFIG','utf8'));
+cfg.models = cfg.models || {}; cfg.models.mode = 'merge';
+cfg.models.providers = cfg.models.providers || {};
+cfg.models.providers.ollama = {baseUrl:'$OLLAMA_BASE_URL/v1',api:'openai-completions',models:[{id:'${OLLAMA_MODEL:-cogito}',name:'${OLLAMA_MODEL:-cogito} (Local)',reasoning:false,input:['text'],cost:{input:0,output:0,cacheRead:0,cacheWrite:0},contextWindow:128000,maxTokens:8192}]};
+fs.writeFileSync('$CONFIG', JSON.stringify(cfg, null, 2));
+"
+    echo "Ollama provider added: $OLLAMA_BASE_URL (model: ${OLLAMA_MODEL:-cogito})"
+  else
+    echo "WARNING: OLLAMA_BASE_URL set but no python3/node available to inject provider"
+  fi
+fi
+
+export OPENCLAW_CONFIG_PATH="$CONFIG"
+exec openclaw gateway run --bind lan --auth token "$@"

docker/openclaw-instances/mosaic-main.env

@@ -0,0 +1,14 @@
+# Mosaic Agent: main
+# Fill in all values before deploying.
+
+# Required: LLM provider API key (Z.ai, OpenAI, etc.)
+ZAI_API_KEY=
+
+# Required: unique bearer token for this agent instance (generate: openssl rand -hex 32)
+OPENCLAW_GATEWAY_TOKEN=
+
+# Optional: override default model (default: zai/glm-5)
+# OPENCLAW_MODEL=zai/glm-5
+
+# Optional: Ollama endpoint for local inference (uncomment to enable)
+# OLLAMA_BASE_URL=

docker/openclaw-instances/mosaic-main.json.template

@@ -0,0 +1,19 @@
+{
+  "gateway": {
+    "mode": "local",
+    "port": 18789,
+    "bind": "lan",
+    "auth": { "mode": "token" },
+    "http": {
+      "endpoints": {
+        "chatCompletions": { "enabled": true }
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "workspace": "/home/node/workspace",
+      "model": { "primary": "${OPENCLAW_MODEL:-zai/glm-5}" }
+    }
+  }
+}

docker/openclaw-instances/mosaic-operations.env

@@ -0,0 +1,14 @@
+# Mosaic Agent: operations
+# Fill in all values before deploying.
+
+# Required: LLM provider API key (Z.ai, OpenAI, etc.)
+ZAI_API_KEY=
+
+# Required: unique bearer token for this agent instance (generate: openssl rand -hex 32)
+OPENCLAW_GATEWAY_TOKEN=
+
+# Optional: override default model (default: zai/glm-5)
+# OPENCLAW_MODEL=zai/glm-5
+
+# Optional: Ollama endpoint for local inference (uncomment to enable)
+# OLLAMA_BASE_URL=

docker/openclaw-instances/mosaic-operations.json.template

@@ -0,0 +1,19 @@
+{
+  "gateway": {
+    "mode": "local",
+    "port": 18789,
+    "bind": "lan",
+    "auth": { "mode": "token" },
+    "http": {
+      "endpoints": {
+        "chatCompletions": { "enabled": true }
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "workspace": "/home/node/workspace",
+      "model": { "primary": "${OPENCLAW_MODEL:-zai/glm-5}" }
+    }
+  }
+}

docker/openclaw-instances/mosaic-projects.env

@@ -0,0 +1,14 @@
+# Mosaic Agent: projects
+# Fill in all values before deploying.
+
+# Required: LLM provider API key (Z.ai, OpenAI, etc.)
+ZAI_API_KEY=
+
+# Required: unique bearer token for this agent instance (generate: openssl rand -hex 32)
+OPENCLAW_GATEWAY_TOKEN=
+
+# Optional: override default model (default: zai/glm-5)
+# OPENCLAW_MODEL=zai/glm-5
+
+# Optional: Ollama endpoint for local inference (uncomment to enable)
+# OLLAMA_BASE_URL=

docker/openclaw-instances/mosaic-projects.json.template

@@ -0,0 +1,19 @@
+{
+  "gateway": {
+    "mode": "local",
+    "port": 18789,
+    "bind": "lan",
+    "auth": { "mode": "token" },
+    "http": {
+      "endpoints": {
+        "chatCompletions": { "enabled": true }
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "workspace": "/home/node/workspace",
+      "model": { "primary": "${OPENCLAW_MODEL:-zai/glm-5}" }
+    }
+  }
+}

docker/openclaw-instances/mosaic-research.env

@@ -0,0 +1,14 @@
+# Mosaic Agent: research
+# Fill in all values before deploying.
+
+# Required: LLM provider API key (Z.ai, OpenAI, etc.)
+ZAI_API_KEY=
+
+# Required: unique bearer token for this agent instance (generate: openssl rand -hex 32)
+OPENCLAW_GATEWAY_TOKEN=
+
+# Optional: override default model (default: zai/glm-5)
+# OPENCLAW_MODEL=zai/glm-5
+
+# Optional: Ollama endpoint for local inference (uncomment to enable)
+# OLLAMA_BASE_URL=

docker/openclaw-instances/mosaic-research.json.template

@@ -0,0 +1,19 @@
+{
+  "gateway": {
+    "mode": "local",
+    "port": 18789,
+    "bind": "lan",
+    "auth": { "mode": "token" },
+    "http": {
+      "endpoints": {
+        "chatCompletions": { "enabled": true }
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "workspace": "/home/node/workspace",
+      "model": { "primary": "${OPENCLAW_MODEL:-zai/glm-5}" }
+    }
+  }
+}

docs/TASKS.md

@@ -25,12 +25,12 @@
 | MS21-MIG-003   | not-started | phase-3   | Run migration on production database                                              | #568     | api   | —                              | MS21-MIG-001,MS21-TEST-003                                  | MS21-VER-001               | —               | —          | —            | 5K       | —    | Needs deploy coordination; not automatable                                                                            |
 | MS21-MIG-004   | done        | phase-3   | Import API endpoints (6/6 tests)                                                  | #568     | api   | feat/ms21-import-api           | MS21-DB-001                                                 | —                          | codex           | 2026-02-28 | 2026-02-28   | 20K      | 24K  | PR #567 merged, CI green. Review: 0 blockers, 4 should-fix, 1 medium sec (no audit log).                              |
 | MS21-UI-001    | done        | phase-4   | Settings/users page                                                               | #569     | web   | feat/ms21-ui-users             | MS21-API-001,MS21-API-002                                   | —                          | codex           | 2026-02-28 | 2026-02-28   | 20K      | ~30K | PR #573 merged. Review: 0 blockers, 4 should-fix → MS21-UI-001-QA                                                     |
-| MS21-UI-001-QA | done        | phase-4   | QA: fix 4 review findings (pagination, error state, self-deactivate guard, tests) | #569     | web   | fix/ms21-ui-001-qa             | MS21-UI-001                                                 | —                          | —               | —          | —            | 15K      | —    | 0 blockers; merged per framework. Should-fix: pagination cap, error/empty collision, self-deactivate guard, no tests. |
+| MS21-UI-001-QA | in-progress | phase-4   | QA: fix 4 review findings (pagination, error state, self-deactivate guard, tests) | #569     | web   | fix/ms21-ui-001-qa             | MS21-UI-001                                                 | —                          | —               | —          | —            | 15K      | —    | 0 blockers; merged per framework. Should-fix: pagination cap, error/empty collision, self-deactivate guard, no tests. |
 | MS21-UI-002    | done        | phase-4   | User detail/edit and invite dialogs                                               | #569     | web   | feat/ms21-ui-users             | MS21-UI-001                                                 | —                          | —               | —          | —            | 15K      | —    |                                                                                                                       |
 | MS21-UI-003    | done        | phase-4   | Settings/workspaces page (wire to real API)                                       | #569     | web   | feat/ms21-ui-workspaces        | MS21-API-003                                                | —                          | codex           | 2026-02-28 | 2026-02-28   | 15K      | ~25K | PR #574 merged. Review: 0 critical, 1 low (raw errors in UI)                                                          |
 | MS21-UI-004    | done        | phase-4   | Workspace member management UI                                                    | #569     | web   | feat/ms21-ui-workspaces        | MS21-UI-003,MS21-API-003                                    | —                          | —               | —          | —            | 15K      | —    | Components exist                                                                                                      |
 | MS21-UI-005    | done        | phase-4   | Settings/teams page                                                               | #569     | web   | feat/ms21-ui-teams             | MS21-API-004                                                | —                          | —               | —          | —            | 15K      | —    |                                                                                                                       |
-| MS21-TEST-004  | done        | phase-4   | Frontend component tests                                                          | #569     | web   | test/ms21-ui                   | MS21-UI-001,MS21-UI-002,MS21-UI-003,MS21-UI-004,MS21-UI-005 | —                          | —               | —          | —            | 20K      | —    |                                                                                                                       |
+| MS21-TEST-004  | in-progress | phase-4   | Frontend component tests                                                          | #569     | web   | test/ms21-ui                   | MS21-UI-001,MS21-UI-002,MS21-UI-003,MS21-UI-004,MS21-UI-005 | —                          | —               | —          | —            | 20K      | —    |                                                                                                                       |
 | MS21-RBAC-001  | done        | phase-5   | Sidebar navigation role gating                                                    | #570     | web   | feat/ms21-rbac                 | MS21-UI-001                                                 | —                          | —               | —          | —            | 10K      | —    |                                                                                                                       |
 | MS21-RBAC-002  | done        | phase-5   | Settings page access restriction                                                  | #570     | web   | feat/ms21-rbac                 | MS21-RBAC-001                                               | —                          | —               | —          | —            | 8K       | —    |                                                                                                                       |
 | MS21-RBAC-003  | done        | phase-5   | Action button permission gating                                                   | #570     | web   | feat/ms21-rbac                 | MS21-RBAC-001                                               | —                          | —               | —          | —            | 8K       | —    |                                                                                                                       |

docs/design/MS22-DB-CENTRIC-ARCHITECTURE.md

@@ -1,413 +0,0 @@
-# MS22 Phase 1: DB-Centric Multi-User Agent Architecture
-
-## Design Principles
-
-1. **2 env vars to bootstrap** — `DATABASE_URL` + `MOSAIC_SECRET_KEY`
-2. **DB-centric config** — All runtime config in Postgres, managed via WebUI
-3. **Mosaic is the gatekeeper** — Users authenticate to Mosaic, never to OpenClaw directly
-4. **Per-user agent isolation** — Each user gets their own OpenClaw container(s) with their own credentials
-5. **Onboarding-first** — Breakglass user + wizard on first boot
-6. **Generic product** — No hardcoded names, models, providers, or endpoints
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────┐
-│                    MOSAIC WEBUI                      │
-│  (Auth: breakglass local + OIDC via settings)       │
-└──────────────────────┬──────────────────────────────┘
-                       │
-                       ▼
-┌─────────────────────────────────────────────────────┐
-│                    MOSAIC API                        │
-│                                                     │
-│  ┌──────────────┐  ┌────────────────┐  ┌─────────┐ │
-│  │ Onboarding   │  │ Container      │  │ Config  │ │
-│  │ Wizard       │  │ Lifecycle Mgr  │  │ Store   │ │
-│  └──────────────┘  └───────┬────────┘  └─────────┘ │
-│                            │                        │
-└────────────────────────────┼────────────────────────┘
-                             │ Docker API
-          ┌──────────────────┼──────────────────┐
-          │                  │                  │
-          ▼                  ▼                  ▼
-   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
-   │  OpenClaw   │   │  OpenClaw   │   │  OpenClaw   │
-   │  User A     │   │  User B     │   │  System     │
-   │             │   │             │   │  (admin)    │
-   │ Claude Max  │   │ Z.ai key   │   │ Shared key  │
-   │ own memory  │   │ own memory  │   │ monitoring  │
-   └─────────────┘   └─────────────┘   └─────────────┘
-    Scale to zero      Scale to zero     Always on
-    after idle         after idle
-```
-
-## Container Lifecycle
-
-### User containers (on-demand)
-
-1. User logs in → Mosaic checks `UserContainer` table
-2. No running container → Mosaic calls Docker API to create one
-3. Injects user's encrypted API keys via config endpoint
-4. Routes chat requests to user's container
-5. Idle timeout (configurable, default 30min) → scale to zero
-6. State volume persists (sessions, memory, auth tokens)
-7. Next request → container restarts, picks up state from volume
-
-### System containers (always-on, optional)
-
-- Admin-provisioned for system tasks (monitoring, scheduled jobs)
-- Use admin-configured shared API keys
-- Not tied to any user
-
-## Auth Layers
-
-| Flow                            | Method                                                                 |
-| ------------------------------- | ---------------------------------------------------------------------- |
-| User → Mosaic WebUI             | Breakglass (local) or OIDC (configured in settings)                    |
-| Mosaic API → OpenClaw container | Bearer token (auto-generated per container, stored encrypted in DB)    |
-| OpenClaw → LLM providers        | User's own API keys (delivered via config endpoint, decrypted from DB) |
-| Admin → System settings         | RBAC (admin role required)                                             |
-| Internal config endpoint        | Bearer token (container authenticates to fetch its config)             |
-
-## Database Schema
-
-### System Tables
-
-```prisma
-model SystemConfig {
-  id        String   @id @default(cuid())
-  key       String   @unique  // "oidc.issuerUrl", "oidc.clientId", "onboarding.completed"
-  value     String             // plaintext or encrypted (prefix: "enc:")
-  encrypted Boolean  @default(false)
-  updatedAt DateTime @updatedAt
-}
-
-model BreakglassUser {
-  id           String   @id @default(cuid())
-  username     String   @unique
-  passwordHash String   // bcrypt
-  isActive     Boolean  @default(true)
-  createdAt    DateTime @default(now())
-  updatedAt    DateTime @updatedAt
-}
-```
-
-### Provider Tables (per-user)
-
-```prisma
-model LlmProvider {
-  id          String   @id @default(cuid())
-  userId      String             // owner — each user manages their own providers
-  name        String             // "my-zai", "work-openai", "local-ollama"
-  displayName String             // "Z.ai", "OpenAI (Work)", "Local Ollama"
-  type        String             // "zai" | "openai" | "anthropic" | "ollama" | "custom"
-  baseUrl     String?            // null for built-in, URL for custom/ollama
-  apiKey      String?            // encrypted
-  apiType     String   @default("openai-completions")
-  models      Json     @default("[]")  // [{id, name, contextWindow, maxTokens}]
-  isActive    Boolean  @default(true)
-  createdAt   DateTime @default(now())
-  updatedAt   DateTime @updatedAt
-
-  @@unique([userId, name])
-}
-```
-
-### Container Tables
-
-```prisma
-model UserContainer {
-  id              String    @id @default(cuid())
-  userId          String    @unique
-  containerId     String?   // Docker container ID (null = not running)
-  containerName   String    // "mosaic-user-{userId}"
-  gatewayPort     Int?      // assigned port (null = not running)
-  gatewayToken    String    // encrypted — auto-generated
-  status          String    @default("stopped")  // "running" | "stopped" | "starting" | "error"
-  lastActiveAt    DateTime?
-  idleTimeoutMin  Int       @default(30)
-  config          Json      @default("{}")  // cached openclaw.json for this user
-  createdAt       DateTime  @default(now())
-  updatedAt       DateTime  @updatedAt
-}
-
-model SystemContainer {
-  id              String   @id @default(cuid())
-  name            String   @unique  // "mosaic-system-ops", "mosaic-system-monitor"
-  role            String   // "operations" | "monitor" | "scheduler"
-  containerId     String?
-  gatewayPort     Int?
-  gatewayToken    String   // encrypted
-  status          String   @default("stopped")
-  providerId      String?  // references admin-level LlmProvider
-  primaryModel    String   // "zai/glm-5", etc.
-  isActive        Boolean  @default(true)
-  createdAt       DateTime @default(now())
-  updatedAt       DateTime @updatedAt
-}
-```
-
-### User Agent Preferences
-
-```prisma
-model UserAgentConfig {
-  id             String  @id @default(cuid())
-  userId         String  @unique
-  primaryModel   String?           // user's preferred model
-  fallbackModels Json    @default("[]")
-  personality    String?           // custom SOUL.md content
-  providerId     String?           // default provider for this user
-  createdAt      DateTime @default(now())
-  updatedAt      DateTime @updatedAt
-}
-```
-
-## Internal Config Endpoint
-
-`GET /api/internal/agent-config/:containerType/:id`
-
-- Auth: Bearer token (container's own gateway token)
-- Returns: Complete `openclaw.json` generated from DB
-- For user containers: includes user's providers, model prefs, personality
-- For system containers: includes admin provider config
-
-Response assembles openclaw.json dynamically:
-
-```json
-{
-  "gateway": { "mode": "local", "port": 18789, "bind": "lan", "auth": { "mode": "token" } ... },
-  "agents": { "defaults": { "model": { "primary": "<from UserAgentConfig>" } } },
-  "models": { "providers": { "<from LlmProvider rows>": { ... } } }
-}
-```
-
-## Container Lifecycle Manager
-
-NestJS service that manages Docker containers:
-
-```typescript
-class ContainerLifecycleService {
-  // Create and start a user's OpenClaw container
-  async ensureRunning(userId: string): Promise<{ url: string; token: string }>;
-
-  // Stop idle containers (called by cron/scheduler)
-  async reapIdle(): Promise<number>;
-
-  // Stop a specific user's container
-  async stop(userId: string): Promise<void>;
-
-  // Health check all running containers
-  async healthCheckAll(): Promise<HealthStatus[]>;
-
-  // Restart container with updated config
-  async restart(userId: string): Promise<void>;
-}
-```
-
-Uses Docker Engine API (`/var/run/docker.sock` or TCP) via `dockerode` npm package.
-
-## Onboarding Wizard
-
-### First-Boot Detection
-
-- API checks: `SystemConfig.get("onboarding.completed")` → null = first boot
-- WebUI redirects to `/onboarding` if not completed
-
-### Steps
-
-**Step 1: Create Breakglass Admin**
-
-- Username + password → bcrypt → `BreakglassUser` table
-- This user always works, even if OIDC is misconfigured
-
-**Step 2: Configure Authentication (optional)**
-
-- OIDC: provider URL, client ID, client secret → encrypted in `SystemConfig`
-- Skip = breakglass-only auth (can add OIDC later in settings)
-
-**Step 3: Add Your First LLM Provider**
-
-- Pick type → enter API key/endpoint → test connection → save to `LlmProvider`
-- This becomes the admin's default provider
-
-**Step 4: System Agents (optional)**
-
-- Configure always-on system agents for monitoring/ops
-- Or skip — users can just use their own personal agents
-
-**Step 5: Complete**
-
-- Sets `SystemConfig("onboarding.completed") = true`
-- Redirects to dashboard
-
-### Post-Onboarding: User Self-Service
-
-- Each user adds their own LLM providers in profile settings
-- Each user configures their preferred model, personality
-- First chat request triggers container creation
-
-## Docker Compose (final)
-
-```yaml
-services:
-  mosaic-api:
-    image: mosaic/api:latest
-    environment:
-      DATABASE_URL: ${DATABASE_URL}
-      MOSAIC_SECRET_KEY: ${MOSAIC_SECRET_KEY}
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock # Docker API access
-    networks:
-      - internal
-
-  mosaic-web:
-    image: mosaic/web:latest
-    environment:
-      NEXT_PUBLIC_API_URL: http://mosaic-api:4000
-    networks:
-      - internal
-
-  postgres:
-    image: postgres:17
-    environment:
-      POSTGRES_DB: mosaic
-      POSTGRES_USER: mosaic
-      POSTGRES_PASSWORD: ${DATABASE_PASSWORD}
-    volumes:
-      - postgres-data:/var/lib/postgresql/data
-    networks:
-      - internal
-
-  # System agent (optional, admin-provisioned)
-  # mosaic-system:
-  #   image: alpine/openclaw:latest
-  #   ... (managed by ContainerLifecycleService)
-
-  # User containers are NOT in this file —
-  # they are dynamically created by ContainerLifecycleService
-  # via the Docker API at runtime.
-
-networks:
-  internal:
-    driver: overlay
-
-volumes:
-  postgres-data:
-```
-
-Note: User OpenClaw containers are **not** defined in docker-compose. They are
-created dynamically by the `ContainerLifecycleService` when users start chatting.
-
-## Entrypoint (for dynamically created containers)
-
-```sh
-#!/bin/sh
-set -e
-: "${MOSAIC_API_URL:?required}"
-: "${AGENT_TOKEN:?required}"
-: "${AGENT_ID:?required}"
-
-# Fetch config from Mosaic API
-curl -sf "${MOSAIC_API_URL}/api/internal/agent-config/${AGENT_ID}" \
-  -H "Authorization: Bearer ${AGENT_TOKEN}" \
-  -o /tmp/openclaw.json
-
-export OPENCLAW_CONFIG_PATH=/tmp/openclaw.json
-exec openclaw gateway run --bind lan --auth token
-```
-
-Container env vars (injected by ContainerLifecycleService):
-
-- `MOSAIC_API_URL` — internal API URL
-- `AGENT_TOKEN` — this container's bearer token (from DB)
-- `AGENT_ID` — container ID for config lookup
-
-## Config Update Strategy
-
-When a user changes settings (model, provider, personality):
-
-1. Mosaic API updates DB
-2. API calls `ContainerLifecycleService.restart(userId)`
-3. Container restarts, fetches fresh config from API
-4. OpenClaw gateway starts with new config
-5. State volume preserves sessions/memory across restarts
-
-## Task Breakdown
-
-| Task     | Phase          | Scope                                                                                                                 | Dependencies |
-| -------- | -------------- | --------------------------------------------------------------------------------------------------------------------- | ------------ |
-| MS22-P1a | Schema         | Prisma models: SystemConfig, BreakglassUser, LlmProvider, UserContainer, SystemContainer, UserAgentConfig. Migration. | —            |
-| MS22-P1b | Crypto         | Encryption service for API keys/tokens (AES-256-GCM using MOSAIC_SECRET_KEY)                                          | P1a          |
-| MS22-P1c | Config API     | Internal config endpoint: assembles openclaw.json from DB                                                             | P1a, P1b     |
-| MS22-P1d | Container Mgr  | ContainerLifecycleService: Docker API integration (dockerode), start/stop/health/reap                                 | P1a          |
-| MS22-P1e | Onboarding API | Onboarding endpoints: breakglass, OIDC, provider, complete                                                            | P1a, P1b     |
-| MS22-P1f | Onboarding UI  | Multi-step wizard in WebUI                                                                                            | P1e          |
-| MS22-P1g | Settings API   | CRUD: providers, agent config, OIDC, breakglass                                                                       | P1a, P1b     |
-| MS22-P1h | Settings UI    | Settings pages: Providers, Agent Config, Auth                                                                         | P1g          |
-| MS22-P1i | Chat Proxy     | Route WebUI chat → user's OpenClaw container (SSE)                                                                    | P1c, P1d     |
-| MS22-P1j | Docker         | Entrypoint script, health checks, compose for core services                                                           | P1c          |
-| MS22-P1k | Idle Reaper    | Cron service to stop idle user containers                                                                             | P1d          |
-
-## Open Questions (Resolved)
-
-1. ~~Config updates → restart?~~ **Yes.** Mosaic restarts the container, fresh config on boot.
-2. ~~CLI alternative for breakglass?~~ **Yes.** Both WebUI wizard and CLI (`mosaic admin create-breakglass`).
-3. ~~Config cache TTL?~~ **Yes.** Config fetched once at startup, changes trigger restart.
-
-## Security Isolation Model
-
-### Core Principle: ZERO cross-user access
-
-Every user is fully sandboxed. No exceptions.
-
-### Container Isolation
-
-- Each user gets their **own** OpenClaw container (separate process, PID namespace)
-- Each container has its **own** Docker volume (sessions, memory, workspace)
-- Containers run on an **internal-only** Docker network — no external exposure
-- Users NEVER talk to OpenClaw directly — Mosaic proxies all requests
-- Container gateway tokens are unique per-user and single-purpose
-
-### Data Isolation (enforced at API + DB level)
-
-| Data             | Isolation                 | Enforcement                                                                       |
-| ---------------- | ------------------------- | --------------------------------------------------------------------------------- |
-| LLM API keys     | Per-user, encrypted       | `LlmProvider.userId` — all queries scoped by authenticated user                   |
-| Chat history     | Per-user container volume | Separate Docker volume per user, not shared                                       |
-| Agent memory     | Per-user container volume | Separate Docker volume per user                                                   |
-| Agent config     | Per-user                  | `UserAgentConfig.userId` — scoped queries                                         |
-| Container access | Per-user                  | `UserContainer.userId` — Mosaic validates user owns the container before proxying |
-
-### API Enforcement
-
-- **All user-facing endpoints** include `WHERE userId = authenticatedUser.id`
-- **No admin endpoint** exposes another user's API keys (even to admins)
-- **Chat proxy** validates: authenticated user → owns target container → forwards request
-- **Config endpoint** validates: container token matches the container requesting config
-- **Provider CRUD** is fully user-scoped — User A cannot list, read, or modify User B's providers
-
-### What admins CAN see
-
-- Container status (running/stopped) — not contents
-- User list and roles
-- System-level config (OIDC, system agents)
-- Aggregate usage metrics (not individual conversations)
-
-### What admins CANNOT see
-
-- Other users' API keys (encrypted, no decrypt endpoint)
-- Other users' chat history (in container volumes, not in Mosaic DB)
-- Other users' agent memory/workspace contents
-
-### Future: Team Workspaces (NOT in scope)
-
-Team/shared workspaces are a potential future feature where users opt-in to
-shared agent contexts. This requires explicit consent, shared-key management,
-and a different isolation model. **Not designed here. Not built now.**
-
-### Attack Surface Notes
-
-- Docker socket access (`/var/run/docker.sock`) is required by Mosaic API for container management. This is a privileged operation — the Mosaic API container must be trusted.
-- `MOSAIC_SECRET_KEY` is the root of trust for encryption. Rotation requires re-encrypting all secrets in DB.
-- Container-to-container communication is blocked by default (no shared network between user containers unless explicitly configured).