sync: update from private repo (a67c053)

.env.example

@@ -1,6 +1,58 @@
-# Docker Compose reaches an LLM running on the host through this address.
+# ---------------------------------------------------------------------------
+# MAESTRO environment overrides
+#
+#   cp .env.example .env
+#
+# Loaded by:
+#   - Docker Compose       (docker-compose.yml: env_file: .env)
+#   - scripts/server.sh    (bare-metal: each KEY=value is exported before launch)
+#
+# Precedence: explicit shell env  >  .env  >  config.yaml  >  built-in defaults.
+# Every key is OPTIONAL. The uncommented defaults below target the Docker path;
+# bare-metal installs usually generate config.yaml with `npm run setup` and only
+# need this file for the LLM endpoint and HOST.
+#
+# NOTE: under Docker Compose, PORT / DB_PATH / WORKTREE_DIR are also pinned in
+# docker-compose.yml's `environment:` block, which overrides this file. Editing
+# them here only takes effect on a bare-metal (scripts/server.sh) launch.
+# ---------------------------------------------------------------------------
+
+# --- LLM connection --------------------------------------------------------
+# OpenAI-compatible endpoint. From inside a Docker container, host.docker.internal
+# reaches an LLM (Ollama / vLLM, ...) running on the host.
 OLLAMA_BASE_URL=http://host.docker.internal:11434/v1
 OLLAMA_MODEL=qwen3:32b
 
-# Required only when enabling MCP or SSH.
+# --- Network bind ----------------------------------------------------------
+# Address the HTTP(S) server binds to. Default: 127.0.0.1 (loopback only).
+# The agent API includes a Bash tool, so an auth-less instance reachable on the
+# LAN is effectively unauthenticated remote code execution.
+#
+# To reach MAESTRO from another machine on a BARE-METAL install, set HOST
+# explicitly (e.g. 0.0.0.0) -- and enable auth in config.yaml first.
+# (The Docker image already sets HOST=0.0.0.0 inside the container; external
+#  access is gated by the 127.0.0.1:9876 port mapping in docker-compose.yml.)
+# HOST=0.0.0.0
+
+# HTTP(S) listen port (default 9876).
+# PORT=9876
+
+# --- Storage paths ---------------------------------------------------------
+# SQLite database file (default ./data/maestro.db).
+# DB_PATH=./data/maestro.db
+
+# Agent workspace base directory (default ./data/workspaces; mirrors
+# storage.worktree_dir in config.yaml).
+# WORKTREE_DIR=./data/workspaces
+
+# --- Runtime ---------------------------------------------------------------
+# Max concurrent jobs across all workers (overrides `concurrency` in config.yaml).
+# CONCURRENCY=4
+
+# Log verbosity: debug | info | warn | error (default info).
+# LOG_LEVEL=info
+
+# --- Secrets ---------------------------------------------------------------
+# Required ONLY when using MCP servers or the SSH tool. 64 hex characters.
+# Generate one with:  openssl rand -hex 32
 # MCP_ENCRYPTION_KEY=replace-with-64-hex-characters