diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..ff1e2fb
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,77 @@
+# ---------------------------------------------------------------------------
+# .env.example — committable template for the tmux-agent-orchestrate-* skills
+#
+# This file is tracked in git and contains NO secrets. To get a working local
+# config, copy it to `.env` (which is git-ignored) and edit as needed:
+#
+#     scripts/generate-env.sh        # creates .env from this template if absent
+#     # or manually:  cp .env.example .env
+#
+# Every variable below is OPTIONAL. The skills already resolve sane defaults
+# (shown after each `#default:` line), so an unset/commented variable just keeps
+# the built-in behaviour. Uncomment + edit only the ones you want to override.
+#
+# SECURITY: never put real secrets in this template. Secret-bearing vars use a
+# `replace_me` placeholder — fill them in only in your local `.env`.
+# ---------------------------------------------------------------------------
+
+# ===========================================================================
+# Workspace / runtime paths
+# ===========================================================================
+
+# Single source of truth for the agent session registry YAML.
+#default: <workspace>/.hermes/agent-sessions.yaml
+# AGENT_SESSIONS_YAML=/path/to/workspace/.hermes/agent-sessions.yaml
+
+# Where the monitor (reconcile.sh) keeps its drift-state cache.
+#default: <workspace>/.cache/tmux-agent-orchestrate-monitor
+# AGENT_SESSIONS_STATE_DIR=/path/to/workspace/.cache/tmux-agent-orchestrate-monitor
+
+# Root directory that holds Claude Code per-project conversation logs (*.jsonl).
+#default: $HOME/.claude/projects
+# CLAUDE_PROJECT_DIR=$HOME/.claude/projects
+
+# Directory scanned for per-session launcher wrappers (~/.local/bin/<session>).
+#default: $HOME/.local/bin
+# LOCAL_BIN=$HOME/.local/bin
+
+# tmux server socket name (`tmux -L <name>`). "default" = the normal tmux server
+# (no -L). Set this to opt into an isolated server for all skill tmux calls.
+#default: default
+# TMUX_SERVER_NAME=default
+
+# ===========================================================================
+# delegate-job / MQTT broker
+# ===========================================================================
+
+# MQTT broker host the delegate-job publisher/subscriber connects to.
+#default: broker.hivemq.com
+# MQTT_BROKER=broker.hivemq.com
+
+# Broker auth username. Leave unset for anonymous brokers.
+#default: (unset → anonymous)
+# MQTT_USERNAME=replace_me
+
+# Broker auth password. SECRET — fill in only in your local .env, never commit.
+#default: (unset → anonymous)
+# MQTT_PASSWORD=replace_me
+
+# Prefix for generated MQTT client ids (publisher/subscriber/monitor).
+#default: hermes
+# MQTT_CLIENT_ID_PREFIX=hermes
+
+# Path to a CA bundle for TLS broker verification (set MQTT_TLS=1 to use TLS).
+#default: (unset → no custom CA)
+# MQTT_CA_CERTS=/path/to/ca.crt
+
+# Client certificate for mutual-TLS brokers.
+#default: (unset → no client cert)
+# MQTT_CERTFILE=/path/to/client.crt
+
+# Client private key for mutual-TLS brokers. SECRET — keep the key file private.
+#default: (unset → no client key)
+# MQTT_KEYFILE=/path/to/client.key
+
+# Directory for delegate-job audit logs (sits beside .hermes/jobs/).
+#default: <cwd>/.hermes/delegate_job_logs
+# DELEGATE_JOB_LOGS_DIR=/path/to/workspace/.hermes/delegate_job_logs
diff --git a/scripts/generate-env.sh b/scripts/generate-env.sh
new file mode 100755
index 0000000..af3221c
--- /dev/null
+++ b/scripts/generate-env.sh
@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# generate-env.sh — create a local .env from the committed .env.example template.
+#
+# Behaviour:
+#   - .env absent          → copy .env.example to .env, print the path.
+#   - .env present         → no-op (leaves your edits intact), exit 0.
+#   - .env present --force  → overwrite .env from .env.example (backs up to .env.bak).
+#
+# Paths are resolved relative to this script (repo root = parent of scripts/),
+# so it works regardless of the caller's cwd.
+#
+# Usage: scripts/generate-env.sh [--force] [-h|--help]
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SRC="$REPO_ROOT/.env.example"
+DST="$REPO_ROOT/.env"
+
+FORCE=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --force) FORCE=1; shift ;;
+    -h|--help)
+      echo "Usage: $0 [--force]"
+      echo "  Create .env from .env.example. --force overwrites an existing .env."
+      exit 0 ;;
+    *) echo "ERROR: unknown arg: $1" >&2; echo "Usage: $0 [--force]" >&2; exit 2 ;;
+  esac
+done
+
+[ -f "$SRC" ] || { echo "ERROR: template not found: $SRC" >&2; exit 1; }
+
+if [ -f "$DST" ] && [ "$FORCE" != "1" ]; then
+  echo "no-op: $DST already exists (use --force to overwrite)"
+  exit 0
+fi
+
+if [ -f "$DST" ] && [ "$FORCE" = "1" ]; then
+  cp -p "$DST" "$DST.bak"
+  echo "backed up existing .env -> $DST.bak"
+fi
+
+cp "$SRC" "$DST"
+echo "created: $DST"
+echo "Next: edit $DST and fill in any secrets (look for 'replace_me')."