diff --git a/.env.development b/.env.development
index 646bc60..e2a6493 100644
--- a/.env.development
+++ b/.env.development
@@ -1,29 +1,109 @@
+```env
+# ============================================================
+# Application Configuration
+# ============================================================
+
+# Runtime environment.
+# "development" enables development-specific behavior and settings.
 NODE_ENV=development
+
+# Port on which the backend API runs.
 PORT=3000
 
+
+# ============================================================
+# CORS Configuration
+# ============================================================
+
+# Comma-separated list of frontend origins allowed to access
+# the backend API during local development.
 CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001,http://localhost:5173
 
+# Maximum amount of time, in seconds, that browsers can cache
+# CORS preflight responses.
+CORS_MAX_AGE=3600
+
+# Allow credentials such as cookies and authorization headers
+# in cross-origin requests.
+CORS_ALLOW_CREDENTIALS=true
+
+
+# ============================================================
+# Database Configuration
+# ============================================================
+
+# PostgreSQL connection string for the development database.
 DATABASE_URL=postgresql://dev_user:dev_password@localhost:5432/neuro_backend_dev
+
+# PostgreSQL database host.
 DB_HOST=localhost
+
+# PostgreSQL database port.
 DB_PORT=5432
+
+# PostgreSQL database username.
 DB_USER=dev_user
+
+# PostgreSQL database password.
+# Use a local development password only.
 DB_PASSWORD=dev_password
+
+# Name of the development PostgreSQL database.
 DB_NAME=neuro_backend_dev
-# # AI
-# ANTHROPIC_API_KEY=get_from_console.anthropic.com
-# BRIAN_API_KEY=get_from_brianknows.org
+
+
+# ============================================================
+# Authentication / JWT Configuration
+# ============================================================
+
+# Secret used to sign and verify JWT access tokens.
+# Use a strong secret even in development.
 JWT_SECRET=dev-jwt-secret-key
+
+# Lifetime of JWT access tokens.
 JWT_EXPIRY=24h
+
+# Separate secret used to sign and verify refresh tokens.
 REFRESH_TOKEN_SECRET=dev-refresh-secret
 
+
+# ============================================================
+# AI / External API Configuration
+# ============================================================
+
+# Anthropic API key used by the application for AI functionality.
+# Replace the development placeholder with a valid API key when needed.
 ANTHROPIC_API_KEY=sk-dev-anthropic-key
+
+# OpenAI API key used by the application for OpenAI functionality.
+# Replace the development placeholder with a valid API key when needed.
 OPENAI_API_KEY=sk-dev-openai-key
 
+# Brian API key for Brian-related integrations.
+# Add a valid development key if the integration is enabled.
+# BRIAN_API_KEY=get_from_brianknows.org
+
+
+# ============================================================
+# Logging Configuration
+# ============================================================
+
+# Log level for development.
+# "debug" provides detailed information useful during development.
 LOG_LEVEL=debug
+
+# Output logs as structured JSON.
 LOG_FORMAT=json
 
+
+# ============================================================
+# HTTP / Server Configuration
+# ============================================================
+
+# Maximum amount of time the server waits for an HTTP request
+# before timing out, in milliseconds.
 SERVER_TIMEOUT=30000
-MAX_REQUEST_SIZE=10mb
 
-CORS_MAX_AGE=3600
-CORS_ALLOW_CREDENTIALS=true
+# Maximum size allowed for incoming HTTP request bodies.
+MAX_REQUEST_SIZE=10mb
+```
diff --git a/.env.example b/.env.example
index e79531f..b3a7329 100644
--- a/.env.example
+++ b/.env.example
@@ -1,81 +1,245 @@
+```env
+# ============================================================
 # Application Environment
+# ============================================================
+
+# Runtime environment for the backend application.
+# "development" enables development-specific behavior.
 NODE_ENV=development
+
+# Port on which the backend API will run.
 PORT=3000
 
-# Stellar
+
+# ============================================================
+# Stellar / Blockchain Configuration
+# ============================================================
+
+# Stellar network used by the application.
+# Options typically include testnet or mainnet.
 STELLAR_NETWORK=testnet
-# STELLAR_RPC_URL is optional — derived from STELLAR_NETWORK by default.
-# Set this only if you need a custom RPC endpoint (e.g., self-hosted or devnet).
+
+# Optional custom Stellar RPC endpoint.
+# By default, the application derives the RPC URL from STELLAR_NETWORK.
+# Set this only when using a custom RPC endpoint, self-hosted node,
+# or another development network.
 # STELLAR_RPC_URL=https://soroban-testnet.stellar.org
+
+# Stellar secret key for the application's agent wallet.
+# Replace this placeholder with a valid development/testnet secret key.
 STELLAR_AGENT_SECRET_KEY=your_agent_stellar_secret_key_here
+
+# Contract ID of the deployed Vault contract.
+# Replace this placeholder with the appropriate testnet contract ID.
 VAULT_CONTRACT_ID=your_deployed_contract_id_here
+
+# Stellar testnet USDC token contract/address.
+# Replace this placeholder with the correct testnet USDC contract address.
 USDC_TOKEN_ADDRESS=testnet_usdc_contract_address_here
 
-# AI
-ANTHROPIC_API_KEY=get_from_console.anthropic.com
+
+# ============================================================
+# AI / External API Configuration
+# ============================================================
+
+# Anthropic API key used for AI functionality.
+# Obtain a development API key from the Anthropic console.
+ANTHROPIC_API_KEY=your-anthropic-key-here
+
+# Brian API key used for Brian-related integrations.
+# Obtain a key from the Brian platform if this integration is enabled.
 BRIAN_API_KEY=get_from_brianknows.org
-# # AI
-# ANTHROPIC_API_KEY=get_from_console.anthropic.com
-# BRIAN_API_KEY=get_from_brianknows.org
-# Database
-DATABASE_URL=postgresql://postgres:password@localhost:5432/neurowealth
-
-# Wallet encryption
-# Generate with: openssl rand -hex 32
-WALLET_ENCRYPTION_KEY=generate_with_openssl_rand_hex_32
-# CORS Configuration - Production Security
-CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001
 
+# OpenAI API key used for OpenAI-related functionality.
+OPENAI_API_KEY=your-openai-key-here
+
+
+# ============================================================
 # Database Configuration
+# ============================================================
+
+# PostgreSQL connection URL for local development.
+# Keep this consistent with the individual DB_* variables below.
 DATABASE_URL=postgresql://user:password@localhost:5432/neuro_backend
+
+# PostgreSQL database host.
 DB_HOST=localhost
+
+# PostgreSQL database port.
 DB_PORT=5432
+
+# PostgreSQL database username.
 DB_USER=postgres
+
+# PostgreSQL database password.
+# Use a secure local development password where appropriate.
 DB_PASSWORD=password
+
+# Name of the local development database.
 DB_NAME=neuro_backend
 
-# Authentication
+
+# ============================================================
+# Wallet Encryption
+# ============================================================
+
+# Encryption key used to protect encrypted wallet/private-key data.
+# IMPORTANT: Generate a strong random value for development.
+#
+# Generate a 32-byte hexadecimal key with:
+# openssl rand -hex 32
+WALLET_ENCRYPTION_KEY=generate_with_openssl_rand_hex_32
+
+
+# ============================================================
+# Authentication / JWT Configuration
+# ============================================================
+
+# Secret used to sign and verify JWT access tokens.
+# Use a strong random value even during development.
 JWT_SECRET=your-secret-key-here
+
+# Lifetime of an access token.
 JWT_EXPIRY=24h
+
+# Separate secret used to sign and verify refresh tokens.
 REFRESH_TOKEN_SECRET=refresh-secret-key
 
-# API Keys
-ANTHROPIC_API_KEY=your-anthropic-key-here
-OPENAI_API_KEY=your-openai-key-here
 
-# Logging
+# ============================================================
+# Logging Configuration
+# ============================================================
+
+# Minimum log level emitted by the application.
+# Common values include debug, info, warn, and error.
 LOG_LEVEL=info
+
+# Log output format.
+# JSON is useful when logs are consumed by structured logging tools.
 LOG_FORMAT=json
 
-# Server
+
+# ============================================================
+# HTTP / Server Configuration
+# ============================================================
+
+# Maximum amount of time the server waits for an HTTP request
+# before timing out, in milliseconds.
 SERVER_TIMEOUT=30000
+
+# Maximum size of incoming HTTP request bodies.
 MAX_REQUEST_SIZE=10mb
 
-# CORS Specific
+
+# ============================================================
+# CORS Configuration
+# ============================================================
+
+# Comma-separated list of frontend origins allowed to make
+# cross-origin requests to the backend.
+#
+# Local development frontends:
+# - http://localhost:3000
+# - http://localhost:3001
+CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001
+
+# Maximum time, in seconds, that browsers may cache CORS
+# preflight responses.
 CORS_MAX_AGE=3600
+
+# Allow cookies and other credentials to be included in
+# cross-origin requests.
 CORS_ALLOW_CREDENTIALS=true
 
-# ── Real-time WebSocket streaming (#316) ─────────────────────────────────────
-# See docs/WEBSOCKET_STREAMING.md. All optional — the defaults shown are what
-# the code uses when the variable is unset.
+
+# ============================================================
+# Real-time WebSocket Streaming (#316)
+# ============================================================
+#
+# See docs/WEBSOCKET_STREAMING.md for the complete WebSocket
+# streaming configuration and implementation details.
+#
+# All WebSocket settings below are optional.
+# If a variable is not provided, the application uses its
+# corresponding default value.
+
+# WebSocket endpoint path.
 WS_PATH=/api/v1/ws
+
+# Interval between WebSocket heartbeat/ping checks, in milliseconds.
 WS_HEARTBEAT_INTERVAL_MS=30000
+
+# Maximum amount of time an idle WebSocket connection can remain
+# inactive before it is closed, in milliseconds.
 WS_IDLE_TIMEOUT_MS=90000
+
+# Maximum number of events that can be buffered for a connection.
 WS_MAX_BUFFERED_EVENTS=256
+
+# Maximum total size of buffered events, in bytes.
 WS_MAX_BUFFERED_BYTES=1048576
+
+# Maximum number of simultaneous WebSocket connections allowed
+# for a single user.
 WS_MAX_CONNECTIONS_PER_USER=5
+
+# Maximum number of handshake attempts allowed within the
+# configured handshake window.
 WS_HANDSHAKE_MAX=30
+
+# Time window used for limiting WebSocket handshake attempts,
+# in milliseconds.
 WS_HANDSHAKE_WINDOW_MS=60000
+
+# Maximum number of messages a client may send within the
+# configured message rate-limit window.
 WS_MESSAGE_MAX=50
+
+# Message rate-limit window, in milliseconds.
 WS_MESSAGE_WINDOW_MS=10000
+
+# Maximum size of an individual WebSocket message, in bytes.
 WS_MAX_MESSAGE_BYTES=4096
+
+# Maximum number of events that can be replayed when a client
+# reconnects and requests missed events.
 WS_REPLAY_MAX_EVENTS=1000
+
+# Interval at which the server re-checks the user's session,
+# in milliseconds.
 WS_SESSION_RECHECK_MS=60000
+
+# Time window used to coalesce multiple events into a single
+# delivery, in milliseconds.
 WS_COALESCE_WINDOW_MS=250
+
+# Delay before retrying a WebSocket drain operation,
+# in milliseconds.
 WS_DRAIN_RETRY_AFTER_MS=2000
-# Cross-pod fan-out channel. Requires REDIS_URL; without it delivery is
-# pod-local and clients close the gap with `resume afterSeq`.
+
+
+# ============================================================
+# Redis / Cross-Pod Event Fan-out
+# ============================================================
+
+# Redis pub/sub channel used to distribute user events across
+# multiple application pods/instances.
+#
+# Requires REDIS_URL to be configured.
+# Without Redis, event delivery remains pod-local and clients
+# can recover missed events using `resume afterSeq`.
 WS_EVENT_CHANNEL=neurowealth:user-events
-# Durable stream retention — bounded by age AND by rows per user.
+
+
+# ============================================================
+# Durable User Event Stream Retention
+# ============================================================
+
+# Maximum age of persisted user events.
+# Events older than this value can be removed during retention cleanup.
 RETENTION_USER_EVENTS_DAYS=7
+
+# Maximum number of persisted events retained per user.
+# Retention is bounded by both age and this per-user row limit.
 USER_EVENT_STREAM_MAX_PER_USER=5000
+```
diff --git a/.env.production b/.env.production
index c030f89..2d92217 100644
--- a/.env.production
+++ b/.env.production
@@ -1,30 +1,123 @@
+```env
+# ============================================================
+# Application Configuration
+# ============================================================
+
+# Application environment.
+# Enables production-specific behavior and optimizations.
 NODE_ENV=production
+
+# Port on which the backend API listens.
 PORT=3000
 
+
+# ============================================================
+# CORS Configuration
+# ============================================================
+
+# Comma-separated list of frontend origins allowed to access
+# the backend API from a browser.
 CORS_ALLOWED_ORIGINS=https://app.neurowealth.io,https://admin.neurowealth.io
 
+# Maximum amount of time (in seconds) that browsers may cache
+# CORS preflight responses.
+CORS_MAX_AGE=7200
+
+# Allows the browser to include credentials such as cookies
+# and authorization headers in cross-origin requests.
+CORS_ALLOW_CREDENTIALS=true
+
+
+# ============================================================
+# Database Configuration
+# ============================================================
+
+# PostgreSQL connection URL for the production database.
+# IMPORTANT: Replace this with the actual production database
+# credentials and keep the value secret.
 DATABASE_URL=postgresql://prod_user:prod_password@prod-db.example.com:5432/neuro_backend_prod
+
+# Production PostgreSQL database host.
 DB_HOST=prod-db.example.com
+
+# PostgreSQL database port.
 DB_PORT=5432
+
+# PostgreSQL database username.
 DB_USER=prod_user
+
+# PostgreSQL database password.
+# IMPORTANT: This is a production secret and should not be
+# committed to source control.
 DB_PASSWORD=prod_password
+
+# Name of the production PostgreSQL database.
 DB_NAME=neuro_backend_prod
 
+
+# ============================================================
+# JWT / Authentication Configuration
+# ============================================================
+
+# Secret used to sign and verify access JWTs.
+# IMPORTANT: Use a strong, randomly generated secret in production.
+# Never commit the real value to source control.
 JWT_SECRET=your-production-jwt-secret-key
+
+# Lifetime of an access JWT.
 JWT_EXPIRY=24h
+
+# Secret used to sign and verify refresh tokens.
+# IMPORTANT: Use a separate strong secret from JWT_SECRET.
 REFRESH_TOKEN_SECRET=your-production-refresh-secret
 
-# # AI
+
+# ============================================================
+# AI / External API Configuration
+# ============================================================
+
+# Anthropic API key used by the backend for AI functionality.
+# IMPORTANT: Store the real production key securely.
 # ANTHROPIC_API_KEY=get_from_console.anthropic.com
+
+# Brian API key for blockchain/AI-related integrations.
+# Obtain the key from the Brian platform when required.
 # BRIAN_API_KEY=get_from_brianknows.org
+
+# Production Anthropic API key.
+# IMPORTANT: Replace the placeholder with the real secret
+# and never commit it to source control.
 ANTHROPIC_API_KEY=sk-your-prod-anthropic-key
+
+# Production OpenAI API key.
+# IMPORTANT: Replace the placeholder with the real secret
+# and never commit it to source control.
 OPENAI_API_KEY=sk-your-prod-openai-key
 
+
+# ============================================================
+# Logging Configuration
+# ============================================================
+
+# Logging level for the production environment.
+# "warn" reduces noisy informational logs while retaining
+# warnings and errors.
 LOG_LEVEL=warn
+
+# Log output format.
+# JSON is suitable for production log aggregation and
+# monitoring systems.
 LOG_FORMAT=json
 
+
+# ============================================================
+# HTTP / Server Configuration
+# ============================================================
+
+# Maximum amount of time the server will wait for an HTTP
+# request before timing out, in milliseconds.
 SERVER_TIMEOUT=30000
-MAX_REQUEST_SIZE=10mb
 
-CORS_MAX_AGE=7200
-CORS_ALLOW_CREDENTIALS=true
+# Maximum size allowed for incoming HTTP request bodies.
+MAX_REQUEST_SIZE=10mb
+```
diff --git a/.env.test b/.env.test
index 89edbab..d746448 100644
--- a/.env.test
+++ b/.env.test
@@ -1,28 +1,107 @@
-# Test environment for CI contract smoke tests (.github/workflows/api-contract.yml).
-# Non-secret stubs only — must satisfy src/config/env.ts format validation.
+```env
+# ============================================================
+# CI / Application Configuration
+# Used by the API contract smoke tests in:
+# .github/workflows/api-contract.yml
+# ============================================================
+
+# Application environment.
+# "test" enables test-specific application behavior.
 NODE_ENV=test
+
+# Port used by the API during CI smoke tests.
 PORT=3000
 
+
+# ============================================================
+# Database Configuration
+# ============================================================
+
+# Non-secret PostgreSQL connection string used by CI.
+# This is a local/test stub and is not intended for production.
 DATABASE_URL=postgresql://user:pass@localhost:5432/db
 
+
+# ============================================================
+# Stellar / Blockchain Configuration
+# ============================================================
+
+# Stellar network used during CI tests.
 STELLAR_NETWORK=testnet
+
+# Stub Stellar RPC endpoint.
+# No real production endpoint or credential is required for smoke tests.
 STELLAR_RPC_URL=https://rpc.example.com
+
+# Non-secret placeholder for the Stellar agent secret key.
+# Used only to satisfy environment validation during CI.
 STELLAR_AGENT_SECRET_KEY=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+
+# Placeholder Vault contract ID used by CI.
 VAULT_CONTRACT_ID=CDUMMYVAULTCONTRACTID
+
+# Placeholder USDC token contract/address used by CI.
 USDC_TOKEN_ADDRESS=CDUMMYUSDC
 
+
+# ============================================================
+# AI / Anthropic Configuration
+# ============================================================
+
+# Non-secret placeholder API key.
+# Used only to satisfy environment validation during CI.
 ANTHROPIC_API_KEY=sk-ant-smoke-key
 
+
+# ============================================================
+# Encryption / Security Configuration
+# ============================================================
+
+# Test-only encryption key.
+# This value is a non-production stub used to satisfy validation.
 WALLET_ENCRYPTION_KEY=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
 
+
+# ============================================================
+# JWT Configuration
+# ============================================================
+
+# Seed used to generate/sign JWT-related values in the test environment.
 JWT_SEED=smoke-jwt-seed-0123456789abcdef0123456789
+
+# JWT session lifetime in hours.
 JWT_SESSION_TTL_HOURS=24
+
+# JWT nonce lifetime in milliseconds.
 JWT_NONCE_TTL_MS=300000
+
+# Interval for cleaning up expired JWT/nonces in milliseconds.
 JWT_CLEANUP_INTERVAL_MS=86400000
 
+
+# ============================================================
+# External Services / Internal Authentication
+# ============================================================
+
+# Placeholder Twilio authentication token.
+# Used only to satisfy environment validation in CI.
 TWILIO_AUTH_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+
+# Placeholder token used for internal service-to-service authentication.
 INTERNAL_SERVICE_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
+
+# ============================================================
+# Network / HTTP Configuration
+# ============================================================
+
+# IP addresses allowed to access trusted/internal endpoints.
 TRUSTED_IPS=127.0.0.1
+
+# Allowed CORS origins.
+# "*" allows all origins in the CI test environment.
 CORS_ORIGINS=*
+
+# Maximum HTTP client request timeout in milliseconds.
 HTTP_CLIENT_TIMEOUT_MS=1000
+```