fix(docker): generic naming (mosaic-*), env-var-only config, no hardcoded values

- Renamed all jarvis-* to mosaic-* (generic for any deployment)
- Config files are .json.template with ${VAR} placeholders
- entrypoint.sh renders templates via envsubst at startup
- Ollama is optional: set OLLAMA_BASE_URL to auto-inject provider
- Model is configurable via OPENCLAW_MODEL env var
- No hardcoded IPs, keys, model names, or user preferences
- Updated README with full env var reference

docker/openclaw-instances/README.md

@@ -1,47 +1,97 @@
-# OpenClaw Agent Instance Setup
+# Mosaic Agent Fleet — Setup Guide
 
-Each service in the OpenClaw fleet reads:
+## Prerequisites
 
-- A per-agent environment file: `docker/openclaw-instances/<agent>.env`
-- A per-agent JSON5 config: `docker/openclaw-instances/<agent>.json`
+- Docker Swarm initialized on target host
+- Mosaic Stack running (Postgres, Valkey on `mosaic-stack_internal` network)
 
-## 1. Fill in API keys in `.env` files
+## 1. Configure Environment Variables
 
-Set `ZAI_API_KEY` in each instance env file:
-
-- `jarvis-main.env`
-- `jarvis-projects.env`
-- `jarvis-research.env`
-- `jarvis-operations.env`
-
-## 2. Generate unique gateway tokens per agent
-
-Generate one token per instance:
+Copy and fill in each agent's `.env` file:
 
 ```bash
-openssl rand -hex 32
+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
 ```
 
-Set a different `OPENCLAW_GATEWAY_TOKEN` in each `.env` file.
+### Optional: Local Ollama
 
-## 3. Deploy the Docker Swarm stack
-
-From repository root:
+If you have an Ollama instance, add to any agent's `.env`:
 
 ```bash
-docker stack deploy -c docker/openclaw-compose.yml jarvis
+OLLAMA_BASE_URL=http://your-ollama-host:11434
+OLLAMA_MODEL=cogito  # or any model you have pulled
 ```
 
-## 4. First-time auth (if needed)
+The entrypoint script will automatically inject the Ollama provider at startup.
 
-If an instance requires first-time login, exec into the running container and run:
+### Optional: Override Default Model
 
 ```bash
-openclaw auth
+OPENCLAW_MODEL=anthropic/claude-sonnet-4-6
 ```
 
-This uses OpenClaw's headless OAuth device-code flow.
+## 2. Populate Config Volumes
 
-## 5. Use Mosaic WebUI terminal for auth
+Each agent needs its `.json.template` file in its config volume:
 
-You can complete the device-code auth flow from the Mosaic WebUI terminal (xterm.js) attached to the service container.
+```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`)             |