diff --git a/app/frontend/.env.example b/app/frontend/.env.example
new file mode 100644
index 0000000..9d6dd63
--- /dev/null
+++ b/app/frontend/.env.example
@@ -0,0 +1,36 @@
+# ChainForge frontend environment template
+# Copy this file to .env.local for local development.
+# Only NEXT_PUBLIC_* values are exposed to the browser. Do not add secrets here.
+
+# Backend API base URL used by frontend hooks and API clients.
+NEXT_PUBLIC_API_URL=http://localhost:4000
+
+# Stellar network label expected by the frontend and connected wallet.
+# Allowed values in validation: testnet, futurenet, mainnet, standalone.
+NEXT_PUBLIC_STELLAR_NETWORK=testnet
+
+# Optional compatibility alias for older code paths that read NEXT_PUBLIC_NETWORK.
+NEXT_PUBLIC_NETWORK=testnet
+
+# Public Stellar endpoints used by wallet and contract integrations.
+NEXT_PUBLIC_STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
+NEXT_PUBLIC_STELLAR_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
+
+# Deployed AidEscrow contract ID for the selected network.
+NEXT_PUBLIC_AID_ESCROW_CONTRACT_ID=
+
+# Optional environment name shown in UI indicators.
+NEXT_PUBLIC_ENV_NAME=local
+
+# Development-only mock API switch. Set false when testing against a real backend.
+NEXT_PUBLIC_USE_MOCKS=true
+
+# Optional role used by local empty states and demo flows.
+# Supported app roles include guest, donor, admin, operator, and recipient.
+NEXT_PUBLIC_USER_ROLE=guest
+
+# Optional local performance logging for dashboard fetches.
+NEXT_PUBLIC_DASHBOARD_PERF=0
+
+# Optional reviewer/demo checklist route.
+NEXT_PUBLIC_ENABLE_DEMO_CHECKLIST=false
diff --git a/app/frontend/.gitignore b/app/frontend/.gitignore
index 5ef6a52..7b8da95 100644
--- a/app/frontend/.gitignore
+++ b/app/frontend/.gitignore
@@ -32,6 +32,7 @@ yarn-error.log*
 
 # env files (can opt-in for committing if needed)
 .env*
+!.env.example
 
 # vercel
 .vercel