docs: clarify run profiles and env setup

README.md

@@ -39,6 +39,16 @@ A modern, secure web application for managing medication schedules and reminders
 - **Progress Tracking** over time
 - **Export Capabilities** for healthcare providers
 
+## 🧪 Run Profiles
+
+| Profile         | Purpose                                                | How to run                                                        | Configuration                                                                                                                                                                 |
+| --------------- | ------------------------------------------------------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Development** | Fast local iteration with hot reload and mock services | `bun run dev`                                                     | Copy `.env.example` to `.env.local` for local overrides. CouchDB can be mocked (`VITE_COUCHDB_URL=mock`) or pointed to a dev instance.                                        |
+| **Testing**     | Unit and integration validation in CI/stage            | `bun run test` · `bun run test:watch` · `bun run test:coverage`   | Tests run against the mock database strategy by default. No extra environment variables required.                                                                             |
+| **Production**  | Hardened build served via Docker/Reverse proxy         | `bun run build && bun run preview` or `docker compose up --build` | Populate `.env` with production credentials (CouchDB, Mailgun, OAuth). Review [`docs/setup/ENVIRONMENT_VARIABLES.md`](docs/setup/ENVIRONMENT_VARIABLES.md) for required keys. |
+
+> ℹ️ **Tip:** `.env.example` enumerates every variable consumed by the app. For local development prefer `.env.local` (ignored by Git) to avoid accidentally committing secrets.
+
 ### 🎨 **User Experience**
 
 - **Responsive Design** for mobile and desktop

docs/setup/ENVIRONMENT_VARIABLES.md

@@ -10,6 +10,16 @@ The rxminder application supports multiple ways to configure deployments using e
 2. **Dynamic Configuration**: Runtime environment variable injection
 3. **Hybrid Approach**: Combination of both methods
 
+### Run Profiles at a Glance
+
+| Profile     | Typical Usage                                                   | Key Files                                   |
+| ----------- | --------------------------------------------------------------- | ------------------------------------------- |
+| Development | Vite dev server with hot reload and optional mock CouchDB       | `.env.local`, `bun run dev`                 |
+| Testing     | Jest unit/integration suites against the mock database strategy | No additional env required (`bun run test`) |
+| Production  | Hardened build served by Docker/Kubernetes with real services   | `.env`, Docker/compose manifests            |
+
+See the [Run Profiles section](../../README.md#-run-profiles) in the project README for commands and best practices.
+
 ## Environment Variable Sources
 
 Variables are loaded in the following priority order (last wins):