Runtime: add Gemini + Groq workers; document Phase C heterogeneous topologies

Gemini via the built-in `gemini` API family (gemini-2.5-flash default,
gemini-3-pro-preview flagship) and Groq via `groq` — both wired as topology
worker aliases (worker_gemini, worker_groq), no image rebuild. Documents the
Phase C recipe: map semantic roles to per-model aliases via the server
ZEROCLAW_AGENT_MAP, then POST /api/topologies/run.

Five subscription/API backends now selectable per role: Claude, Kimi, GLM,
Gemini, Groq. Proven live on gw-04 — a 3-stage pipeline ran researcher=GLM-4.7
-> analyst=Kimi-K2 -> writer=Gemini-2.5-flash end-to-end (RunRecord persisted).
Quota-care notes added (5h/weekly caps, low concurrency -> prefer sequential
pipelines, short prompts).

Co-Authored-By: Claude Opus 4.8 <[email protected]>

deploy/clawmates-runtime/agent.config.example.toml

@@ -76,6 +76,36 @@ mcp_config = "/zeroclaw-data/clawmates-mcp.json"
 # [agents.worker_glm]
 # model_provider = "claude_cli.glm"
 # risk_profile = "toolfree"
+#
+# Gemini (Google) — built-in `gemini` API family (no image rebuild). Key via env
+# ZEROCLAW_providers__models__gemini__default__api_key=<GEMINI_API_KEY>; model in
+# config. gemini-2.5-flash = stable + high free-tier RPM (throttle-friendly);
+# gemini-3-pro-preview is the flagship.
+# [providers.models.gemini.default]
+# model = "gemini-2.5-flash"
+# [agents.worker_gemini]
+# model_provider = "gemini.default"
+# risk_profile = "toolfree"
+#
+# Groq — built-in `groq` family (key via ZEROCLAW_providers__models__groq__default__api_key).
+# Fast, but LOW free-tier TPM: each turn carries a ~9.5k-tok system prompt, so 2
+# turns/min can exceed 12k TPM → 429. Keep Groq to light/sequential roles.
+# [providers.models.groq.default]
+# # model via ZEROCLAW_providers__models__groq__default__model=llama-3.3-70b-versatile
+# [agents.worker_groq]
+# model_provider = "groq.default"
+# risk_profile = "toolfree"
+
+# --- Phase C: heterogeneous cross-model topologies ---
+# The orchestrator maps a topology node's `role` → an agent alias via the SERVER
+# env ZEROCLAW_AGENT_MAP="role=alias,role=alias" (+ ZEROCLAW_DEFAULT_AGENT for
+# unmapped roles). Point each semantic role at a different model to run ONE
+# topology across vendors, e.g.:
+#   ZEROCLAW_AGENT_MAP="coordinator=coordinator,researcher=worker_glm,analyst=worker_kimi,writer=worker_gemini,actor=worker_groq"
+# Then POST /api/topologies/run {task, graph} with those role names. QUOTA CARE:
+# GLM/Kimi plans have 5h/weekly caps + low concurrency (GLM Lite ~1 project at a
+# time) — prefer pipeline (sequential) over swarm/mesh, keep tasks short, and ask
+# the model for brief replies to cap output tokens.
 
 # Tool-free profile — agents can only reason + call the MCP door (tools inject
 # AFTER this allowlist filter). `level = "full"` removes ZeroClaw's OWN approval