diff --git a/templates/onchainkit-nextjs/.template.env b/templates/onchainkit-nextjs/.template.env
index 56c8b23ebb..fb33b3210d 100644
--- a/templates/onchainkit-nextjs/.template.env
+++ b/templates/onchainkit-nextjs/.template.env
@@ -1,2 +1,36 @@
+# ==============================================================================
+# OnchainKit Next.js template — environment configuration
+# ==============================================================================
+# Copy this file to `.env.local` before running the app:
+#   cp .template.env .env.local
+#
+# Never commit `.env.local` to version control.
+# ==============================================================================
+
+# -----------------------------------------------------------------------------
+# Project
+# -----------------------------------------------------------------------------
+# Display name used in the app layout metadata.
 NEXT_PUBLIC_PROJECT_NAME="template-next-basic"
+
+# -----------------------------------------------------------------------------
+# OnchainKit
+# -----------------------------------------------------------------------------
+# API key from https://portal.cdp.coinbase.com/ (OnchainKit / Developer Platform).
 NEXT_PUBLIC_ONCHAINKIT_API_KEY=""
+
+# -----------------------------------------------------------------------------
+# Base Sepolia (local development)
+# -----------------------------------------------------------------------------
+# The starter template defaults to Base mainnet in `app/rootProvider.tsx`.
+# For Base Sepolia testnet development, switch `chain` to `baseSepolia` from
+# `wagmi/chains` and use a Sepolia RPC endpoint, for example:
+#
+#   NEXT_PUBLIC_RPC_URL=https://sepolia.base.org
+#
+# Public Base Sepolia RPC: https://sepolia.base.org
+# Public Base mainnet RPC: https://mainnet.base.org
+#
+# Third-party providers (Alchemy, Infura, QuickNode) are recommended for
+# production workloads that need higher rate limits.
+NEXT_PUBLIC_RPC_URL=https://sepolia.base.org