diff --git a/.env.local.example b/.env.local.example
index 8576336..ea51c32 100644
--- a/.env.local.example
+++ b/.env.local.example
@@ -1,9 +1,31 @@
-# Supabase Configuration
-# Get these values from your Supabase project settings
+# =============================================================================
+# Project Firefly — Environment Variables
+# =============================================================================
+# Copy this file to .env.local and fill in your values:
+#   cp .env.local.example .env.local
+#
+# See docs/ENVIRONMENTS.md for per-environment configuration details.
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Supabase
+# -----------------------------------------------------------------------------
+# Get these from your Supabase project: Settings → API
+#
+#   Development:  firefly-dev project
+#   Staging/QA:   firefly-staging project  (set in Vercel Preview env vars)
+#   Production:   firefly-prod project     (set in Vercel Production env vars)
+#
 NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
 NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
 
+# -----------------------------------------------------------------------------
 # Demo Mode
-# Set to 'true' to use hardcoded demo users (no auth required)
-# Set to 'false' to require real authentication
+# -----------------------------------------------------------------------------
+# Controls whether the app uses hardcoded demo users or real authentication.
+#
+#   Development:  true   (local dev uses demo IDs, no login required)
+#   Staging/QA:   true   (Vercel preview deployments run in demo mode)
+#   Production:   false  (real auth required, no demo IDs)
+#
 NEXT_PUBLIC_DEMO_MODE=true
diff --git a/docs/ENVIRONMENTS.md b/docs/ENVIRONMENTS.md
new file mode 100644
index 0000000..0a5164f
--- /dev/null
+++ b/docs/ENVIRONMENTS.md
@@ -0,0 +1,90 @@
+# Environment Configuration
+
+Project Firefly uses three environments, each with its own Supabase project and configuration.
+
+## Overview
+
+| Environment | Trigger | Supabase Project | Demo Mode | URL |
+|---|---|---|---|---|
+| **Development** | `npm run dev` | `firefly-dev` | `true` | `localhost:3000` |
+| **Staging / QA** | PR opened → Vercel preview | `firefly-staging` | `true` | `pr-123.vercel.app` |
+| **Production** | Merge to `main` → Vercel prod | `firefly-prod` | `false` | `firefly.app` |
+
+## Supabase Projects
+
+Create three separate Supabase projects. Each project is fully isolated with its own database, auth, and API keys.
+
+### Setup Steps (per project)
+
+1. Create a new project at [supabase.com/dashboard](https://supabase.com/dashboard)
+2. Run the migration: copy `supabase/migrations/001_initial_schema.sql` into the SQL Editor and execute
+3. Run the second migration: copy `supabase/migrations/002_vendor_accepted.sql` and execute
+4. **Dev and Staging only:** Run `supabase/seed.sql` to insert demo data (vendor, menu items, delivery person)
+5. Copy the project URL and anon key from **Settings → API**
+
+### What Each Project Contains
+
+| | firefly-dev | firefly-staging | firefly-prod |
+|---|---|---|---|
+| Schema (migrations) | Yes | Yes | Yes |
+| Seed data (demo vendor, menu) | Yes | Yes | **No** |
+| Demo user IDs in data | Yes | Yes | **No** |
+
+## Vercel Configuration
+
+Environment variables are set in the Vercel dashboard under **Settings → Environment Variables**.
+
+### Preview Deployments (Staging/QA)
+
+Every PR automatically gets a preview deployment. These use staging config:
+
+| Variable | Value |
+|---|---|
+| `NEXT_PUBLIC_SUPABASE_URL` | `https://firefly-staging-ref.supabase.co` |
+| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Staging anon key |
+| `NEXT_PUBLIC_DEMO_MODE` | `true` |
+
+Set these with the **Preview** environment checkbox in Vercel.
+
+### Production
+
+Merges to `main` auto-deploy to production:
+
+| Variable | Value |
+|---|---|
+| `NEXT_PUBLIC_SUPABASE_URL` | `https://firefly-prod-ref.supabase.co` |
+| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Prod anon key |
+| `NEXT_PUBLIC_DEMO_MODE` | `false` |
+
+Set these with the **Production** environment checkbox in Vercel.
+
+## Local Development
+
+1. Copy the example env file:
+   ```bash
+   cp .env.local.example .env.local
+   ```
+
+2. Fill in your **firefly-dev** Supabase credentials:
+   ```
+   NEXT_PUBLIC_SUPABASE_URL=https://your-dev-ref.supabase.co
+   NEXT_PUBLIC_SUPABASE_ANON_KEY=your-dev-anon-key
+   NEXT_PUBLIC_DEMO_MODE=true
+   ```
+
+3. Start the dev server:
+   ```bash
+   npm run dev
+   ```
+
+## Demo Mode Behavior
+
+When `NEXT_PUBLIC_DEMO_MODE=true`:
+- A yellow "DEMO MODE" banner appears at the top of every page
+- Hardcoded demo user IDs are used (no login required)
+- The landing page shows the role picker for testing all three roles
+
+When `NEXT_PUBLIC_DEMO_MODE=false`:
+- No demo banner
+- Real Supabase Auth is required (login/register flow)
+- API routes validate authentication tokens
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index 924c65e..361f10a 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -37,6 +37,11 @@ export default function RootLayout({
       <body
         className={`${geistSans.variable} ${geistMono.variable} antialiased`}
       >
+        {process.env.NEXT_PUBLIC_DEMO_MODE === 'true' && (
+          <div className="bg-amber-500 text-white text-center text-xs py-1">
+            DEMO MODE
+          </div>
+        )}
         <RoleProvider>
           <CartProvider>
             {children}