diff --git a/apps/web/.env.example b/apps/web/.env.example
index 4bbce95..f1c57e5 100644
--- a/apps/web/.env.example
+++ b/apps/web/.env.example
@@ -2,6 +2,10 @@
 # SolarProof — environment variables
 # Copy this file to .env.local and fill in your values.
 # See docs/ONBOARDING.md for a step-by-step setup guide.
+#
+# Legend:
+#   [REQUIRED] — the app will not start or will error without this value.
+#   [OPTIONAL] — the feature degrades gracefully if this is not set.
 # ─────────────────────────────────────────────────────────────────────────────
 
 # ── Supabase ──────────────────────────────────────────────────────────────────
@@ -12,6 +16,7 @@
 NEXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
 
 # [REQUIRED] Public anon key — safe to expose in the browser.
+# Used by the client-side Supabase SDK for unauthenticated reads.
 # Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
 NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here
 
@@ -26,40 +31,56 @@ SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here
 # Use "testnet" for development and staging; "mainnet" for production.
 NEXT_PUBLIC_STELLAR_NETWORK=testnet
 
-# [REQUIRED] Contract IDs — set these after running the deploy-contracts workflow
-# or following the manual steps in docs/DEPLOYMENT.md.
-# Each value is a 56-character Stellar contract address (C...).
+# [REQUIRED] Contract ID for the energy_token Soroban contract.
+# Minted 1:1 with verified kWh readings. Set after running the deploy-contracts
+# workflow or following the manual steps in docs/DEPLOYMENT.md.
+# Format: 56-character Stellar contract address starting with "C".
 # Example: CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM
 NEXT_PUBLIC_ENERGY_TOKEN_ID=
+
+# [REQUIRED] Contract ID for the audit_registry Soroban contract.
+# Stores immutable on-chain anchors of Ed25519-signed meter reading hashes.
+# Example: CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM
 NEXT_PUBLIC_AUDIT_REGISTRY_ID=
+
+# [REQUIRED] Contract ID for the community_governance Soroban contract.
+# Manages cooperative proposals and voting.
+# Example: CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM
 NEXT_PUBLIC_COMMUNITY_GOVERNANCE_ID=
 
 # [REQUIRED] Stellar secret key for the minter account (server-side only).
-# This account mints energy_token certificates after a valid meter reading.
+# This account calls energy_token.mint() after a valid meter reading is verified.
 # Generate with: stellar keys generate minter --network testnet
 # Never commit a real secret key. Use GitHub Actions secrets in CI/CD.
 # Example: SAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
 MINTER_SECRET_KEY=
 
-# ── Redis (optional) ──────────────────────────────────────────────────────────
+# ── Redis ─────────────────────────────────────────────────────────────────────
 # Upstash Redis is used as a caching layer for certificate verification queries.
-# If these are not set, caching is disabled and every /api/verify call hits Supabase.
+# If these are not set, caching is disabled and every /api/verify call hits Supabase directly.
 
 # [OPTIONAL] REST URL for your Upstash Redis database.
+# Create a database at https://console.upstash.com and copy the REST URL.
 # Example: https://us1-example-12345.upstash.io
 UPSTASH_REDIS_REST_URL=https://your-redis.upstash.io
 
 # [OPTIONAL] REST token for your Upstash Redis database.
+# Found in the Upstash console under your database → REST API → Token.
 # Example: AXxxASQgODk...
 UPSTASH_REDIS_REST_TOKEN=your-token
 
-# Logtail / Better Stack — structured log aggregation (production)
-# Create a source at https://logs.betterstack.com and paste the token here.
+# ── Logging ───────────────────────────────────────────────────────────────────
+
+# [OPTIONAL] Logtail / Better Stack source token for structured log aggregation.
+# Create a source at https://logs.betterstack.com and paste the ingest token here.
+# If not set, logs are written to stdout only (suitable for local development).
 # Retention: 30 days. Alerts configured in the Better Stack dashboard.
 LOGTAIL_SOURCE_TOKEN=
 
 # ── CORS ──────────────────────────────────────────────────────────────────────
-# Comma-separated list of origins allowed to call the API from a browser.
-# In development, http://localhost:3000 is always permitted.
+
+# [OPTIONAL] Comma-separated list of origins allowed to call the API from a browser.
+# In development, http://localhost:3000 is always permitted regardless of this value.
+# If not set, only same-origin requests are allowed in production.
 # Example: https://solarproof.vercel.app,https://staging.solarproof.vercel.app
 CORS_ALLOWED_ORIGINS=https://solarproof.vercel.app