Skip to content

[P3] .env.example omits ~20 env vars the code reads #763

Description

@itsmiso-ai

Ask: Document every env var read by the code in .env.example so local setup stops requiring reverse-engineering.
Expected files: .env.example, README.md

Problem: .env.example documents a subset of the environment surface. Several env vars read by src/ are absent from .env.example entirely — not even as commented examples — and at least one (AGENTS) is documented nowhere in the repo. Local-dev and onboarding setups silently run without groomer/queue/webhook configuration they did not know existed. README covers some of these (LLM groomer table; webhook secret lives in docs/pr-review-fix-queue.md), but the .env.example contract itself is incomplete.

Evidence: (2026-08-12) comm of grep -rhoE 'process\.env\.[A-Z_]+' src/ vs all .env.example entries, including commented ones — missing:

  • AGENTS (read by src/app/api/issues/actions/agents/route.ts, documented nowhere)
  • DISPATCH_EXCLUDED_LABELS, DISPATCH_LANE_CONFIG_JSON
  • DISPATCH_GROOMER_COMMENT_COOLDOWN_HOURS, DISPATCH_GROOMER_DRY_RUN, DISPATCH_GROOMER_MAX_CONTEXT_BYTES, DISPATCH_GROOMER_MAX_CONTEXT_FILES, DISPATCH_GROOMER_MAX_FILE_BYTES, DISPATCH_GROOMER_MAX_SEARCHES, DISPATCH_GROOMER_MODEL, DISPATCH_GROOMER_REPO_CONTEXT_ENABLED, DISPATCH_GROOMER_TIMEOUT_MS, DISPATCH_GROOMER_TOKEN, DISPATCH_HOSTED_GROOMER_ENABLED
  • DISPATCH_QUEUE_AGING_DAYS_PER_TIER, DISPATCH_QUEUE_AGING_MAX_TIERS
  • DISPATCH_SYNC_LOCK_MAX_AGE_MS
  • MISSION_CONTROL_AGENT_TOKEN, MISSION_CONTROL_URL
  • PR_FOLLOWUP_BOT_IDENTITIES, PR_FOLLOWUP_BRANCH_OWNERS
  • WEBHOOK_GATEWAY_MODE, WEBHOOK_SECRET

Acceptance:

  • Every env var read by src/ appears in .env.example as a value or commented example, or is explicitly excluded in a comment explaining why
  • AGENTS gains a documented entry
  • README env tables and .env.example agree

Metadata

Metadata

Assignees

No one assigned

    Labels

    auditAudit, review, or investigation work.priority/p3Low priority.status/readyReady for Dispatch worker pickup.type/choreRoutine tasks and maintenance

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions