.env.example

# Zero Develop — environment variable template.
#
# Copy to `.env` for local development. NEVER commit a real `.env`.
# Production secrets are referenced, never embedded (see ADR 0004).
#
# Layout:
#   1) CORE        — required everywhere
#   2) WORKERS     — background loop tuning
#   3) PROVIDERS   — model connectivity
#   4) EXECUTION   — task retry, decomposition, worktree sandbox
#   5) INTERFACES  — Telegram / Discord ingestion
#   6) PRODUCTION PRESET — the exact overrides to review before go-live

# =====================================================================
# 1) CORE
# =====================================================================

# Required: select runtime mode. One of: development, test, production.
ZERO_ENV=development

# Optional in development/test (auto-set if absent).
# In production this MUST be set explicitly.
# SQLite is the only implemented and tested backend this release;
# other schemes are refused at configuration load time.
# ZERO_DATABASE_URL=sqlite:///./zero_develop.db

# Override the state directory (secrets bootstrap key, plugins,
# sessions). Defaults to $HOME/.zero. On a server give Zero a dedicated
# OS user and a directory only that user can read:
#   install -d -o zero -m 0700 /var/lib/zero
# ZERO_HOME=/var/lib/zero

# Optional. One of DEBUG, INFO, WARNING, ERROR. Default INFO.
# PRODUCTION: WARNING keeps operator noise down while preserving
# failure forensics (failures still log at WARNING/ERROR).
# ZERO_LOG_LEVEL=INFO

# Required in production. Must be >= 32 bytes. Never logged. Generate:
#   python -c "import secrets; print(secrets.token_urlsafe(48))"
# ZERO_SECRET_KEY=

# Required in production (>= 32 bytes) unless an external first-user
# provisioning workflow exists and ZERO_ALLOW_MANUAL_PROVISIONING=1.
# ZERO_BOOTSTRAP_TOKEN=
# ZERO_ALLOW_MANUAL_PROVISIONING=0

# =====================================================================
# 2) MANAGED BACKGROUND WORKERS
# =====================================================================
# When enabled (default outside tests), the ASGI app hosts:
#   - a scheduler worker (claims approved handoffs, drains ready tasks,
#     advances integration reviews, enqueues result deliveries);
#   - a delivery worker (drains outbound result deliveries);
#   - a Telegram polling worker when a webhook secret is configured.
ZERO_WORKERS_ENABLED=1
ZERO_SCHEDULER_INTERVAL_SECONDS=5
ZERO_DELIVERY_INTERVAL_SECONDS=2

# Telegram long-poll interval. 1s is fine for development; the
# production preset below raises it to stay comfortably inside
# Bot API budget on busy teams.
# ZERO_POLLING_INTERVAL_SECONDS=1

# Optional combined test command run by the scheduler during
# integration review (split on whitespace).
# ZERO_COMBINED_TEST_COMMAND=pytest -q
# ZERO_COMBINED_TEST_TIMEOUT_SECONDS=300

# =====================================================================
# 3) PROVIDER ADAPTERS (optional)
# =====================================================================
# OpenAI-compatible chat completions endpoint.
# ZERO_OPENAI_API_KEY=
# ZERO_OPENAI_BASE_URL=https://api.openai.com/v1
# ZERO_OPENAI_MODEL=gpt-4o-mini
# PRODUCTION: raise above the 60s default when the model does long
# tool-call turns; decomposition probes measured ~10-25s per forced
# call against GLM-class models (retry/backoff adds more).
# ZERO_OPENAI_TIMEOUT_SECONDS=60

# Anthropic Messages API. When both providers are configured the
# scheduler/runtime fall back across them for retryable failures;
# tool_choice propagates through fallback attempts unchanged.
# ZERO_ANTHROPIC_API_KEY=
# ZERO_ANTHROPIC_BASE_URL=https://api.anthropic.com
# ZERO_ANTHROPIC_MODEL=claude-sonnet-4
# ZERO_ANTHROPIC_TIMEOUT_SECONDS=60

# PostgreSQL pool bounds (only consulted with a postgres:// URL and
# the [pg] extra installed). Min 2 / max 20 defaults suit small
# production teams; scale max with worker concurrency.
# ZERO_PG_POOL_MIN=2
# ZERO_PG_POOL_MAX=20

# =====================================================================
# 4) TASK EXECUTION POLICY
# =====================================================================
# Total dispatch attempts per provider request (in-process transient/
# rate-limit retries before provider fallback; 1 disables). Default 2.
# PRODUCTION: 3 absorbs single-shot 429 bursts seen live without
# delaying the durable retry ladder.
# ZERO_PROVIDER_MAX_ATTEMPTS=2

# Total attempts allowed per TASK (first run + automatic requeues);
# 0 disables automatic requeueing of failed tasks; maximum 16.
# GAP 12 backoff applies between attempts: base delay 60s doubling to
# a 3600s cap plus jitter, honoring provider Retry-After headers.
# PRODUCTION: 3 gives transient blips one cheap second chance without
# masking real failures for long.
# ZERO_TASK_MAX_ATTEMPTS=0

# LLM-driven task decomposition (GAP 10): splits approved plan
# revisions into dependency graphs instead of one implementation task.
# Off by default. The decomposer forces a native tool call
# (emit_task_graph via tool_choice), retries once with stricter
# phrasing, deterministically repairs near-miss dependency keys, and
# falls back to the legacy free-text contract when a model or gateway
# cannot do native tools at all. Failure degrades to single-task
# execution, never blocks an approved plan.
# ZERO_DECOMPOSITION_ENABLED=0

# GAP 8b/G2 Hermes-parity per-call tool approval gate. ``off`` (default)
# keeps plan-level-only authorization; ``manual`` consults the durable
# gate before every declared tool call inside task executions:
#   - hardline floor denies catastrophic arguments even under explicit allows;
#   - deny rules outrank standing allows (deny + grain=always is TOOL-WIDE);
#   - pending requests surface at /projects/{id}/tool-approvals and are
#     resolved via .../{request_id}/resolve by actors holding tool.manage.
# Resolve REST requires ZERO_TOOL_APPROVAL_MODE=manual to return 200.
# ZERO_TOOL_APPROVAL_MODE=off

# GAP 8b/G3: how many independent executions one scheduler tick drains
# concurrently (1 = historical serial ticks; hard cap 8). Within a single
# execution the dependency chain stays strictly serial, so lease fencing
# and DAG order semantics are untouched.
# ZERO_TICK_PARALLEL_EXECUTIONS=1

# Optional JSONL evidence ledger for decomposition recovery analytics
# (S7): every decompose() outcome appends one line — attempts used,
# rescued near-miss dependency repairs with similarity scores,
# escalations, legacy degradations and single-task fallbacks — keyed by
# provider/model. Aggregates (typo_rate_per_graph et al.) power ops
# dashboards; keep the file on a writable path with rotation at the
# log-shipper layer.
# PRODUCTION: set it whenever ZERO_DECOMPOSITION_ENABLED=1; without a
# ledger, per-model output discipline is invisible until graphs fail.
# ZERO_DECOMPOSITION_ANALYTICS_PATH=

# Worktree command execution. `disabled` (default) refuses command
# runs; development may use host_bounded; production additionally
# requires ZERO_SANDBOX_EXECUTOR=docker|firejail (see GET
# /capabilities for the live report).
# ZERO_WORKTREE_ISOLATION_MODE=disabled
# ZERO_SANDBOX_EXECUTOR=none
# ZERO_SANDBOX_IMAGE=python:3.12-slim
# ZERO_WORKTREE_ROOT=
# ZERO_WORKTREE_ALLOWED_COMMANDS=

# MCP client configuration file (optional [mcp] extra).
# ZERO_MCP_SERVERS=

# =====================================================================
# 5) MESSAGING INTERFACES (optional)
# =====================================================================
# ZERO_TELEGRAM_MODE=bot_api|user_session   # session mode needs [session]
# ZERO_TELEGRAM_WEBHOOK_SECRET=
# ZERO_DISCORD_APPLICATION_PUBLIC_KEY=

# =====================================================================
# 6) PRODUCTION PRESET — diff against your .env before go-live
# =====================================================================
# ZERO_ENV=production
# ZERO_DATABASE_URL=<explicit URL — required>
# ZERO_SECRET_KEY=<64+ hex/urlsafe chars>
# ZERO_BOOTSTRAP_TOKEN=<rotate after first login>
# ZERO_HOME=/var/lib/zero            # owned root:root? no — dedicated uid, 0700
# ZERO_LOG_LEVEL=WARNING
# ZERO_SCHEDULER_INTERVAL_SECONDS=5
# ZERO_DELIVERY_INTERVAL_SECONDS=2
# ZERO_POLLING_INTERVAL_SECONDS=3
# ZERO_PROVIDER_MAX_ATTEMPTS=3
# ZERO_TASK_MAX_ATTEMPTS=3
# ZERO_TICK_PARALLEL_EXECUTIONS=4   # drain independent graphs concurrently
# ZERO_OPENAI_TIMEOUT_SECONDS=180    # / ZERO_ANTHROPIC_TIMEOUT_SECONDS=180
# ZERO_DECOMPOSITION_ENABLED=1       # validated live; degrades to single-task on failure
# ZERO_DECOMPOSITION_ANALYTICS_PATH=/var/lib/zero/log/decomposition_analytics.jsonl
# ZERO_TOOL_APPROVAL_MODE=manual    # enterprise posture: per-call human gate
#
# Ingestion duty cycle: prefer ONE delivery path per project interface.
# Webhook ingestion (ZERO_TELEGRAM_WEBHOOK_SECRET + public TLS) beats
# polling for latency and Bot API budget; keep
# ZERO_POLLING_INTERVAL_SECONDS raised (3s+) whenever polling carries
# production traffic instead.