docs: add CI/DevOps documentation and verification checklist

.gitignore

@@ -13,10 +13,13 @@ Cargo.lock
 test_snapshots/
 
 # Environment
+# .env files are ignored at root and recursively in all subdirectories
+# to prevent accidental commits of configuration containing secrets
 .env
 .env.*
 **/.env
 **/.env.*
+# Exception: Always include .env.example files as templates
 !.env.example
 !**/.env.example
 

CONTRIBUTING.md

@@ -22,6 +22,45 @@ First off, thank you for considering contributing to Smasage! It's people like y
 4. Make sure your code lints.
 5. Issue a pull request!
 
+#### Pre-PR Verification Checklist
+
+Before submitting a pull request, verify the following:
+
+- [ ] **Code Quality**
+  - [ ] Code follows the project's style guidelines (see Style Guidelines below)
+  - [ ] No console.log, debug statements, or commented-out code remains
+  - [ ] Variable and function names are clear and descriptive
+
+- [ ] **Testing**
+  - [ ] New code includes tests where applicable
+  - [ ] All tests pass locally: `npm test` (frontend/agent) or `cargo test` (contracts)
+  - [ ] Tests cover the happy path and edge cases
+
+- [ ] **Build & Format**
+  - [ ] Frontend code passes linting: `npm run lint` (if configured)
+  - [ ] Rust code is formatted: `cargo fmt` and passes `cargo clippy`
+  - [ ] No build warnings or errors locally
+
+- [ ] **Dependencies**
+  - [ ] No unnecessary dependencies added
+  - [ ] lock files (package-lock.json, Cargo.lock) are committed
+  - [ ] Dependencies resolve without conflicts
+
+- [ ] **Environment & Security**
+  - [ ] No secrets (API keys, tokens) are hardcoded in code
+  - [ ] `.env` files are not committed; use `.env.example` for templates
+  - [ ] All environment variables used are documented in `.env.example`
+
+- [ ] **Documentation**
+  - [ ] README.md is updated if behavior or setup changes
+  - [ ] Code comments explain the "why" for non-obvious logic
+  - [ ] Commit messages follow the imperative mood ("Add feature", not "Added feature")
+
+- [ ] **Git Hygiene**
+  - [ ] Branch is up to date with `main`
+  - [ ] Commit history is clean (no accidental merge commits)
+  - [ ] PR description clearly explains what changed and why
+
 ## Development Setup
 
 ### Project Structure
@@ -30,6 +69,16 @@ First off, thank you for considering contributing to Smasage! It's people like y
 - `/agent`: Node.js backend using OpenClaw.
 - `/contracts`: Soroban smart contracts in Rust.
 
+### Environment Variables
+
+All environment variables are documented in [README.md](./README.md#environment-variables). Ensure you have a properly configured `.env` file before running any component locally.
+
+Key points:
+- Never commit `.env` files containing secrets to the repository.
+- `.env` files are gitignored recursively across the project (`**/.env` and `**/.env.*` patterns).
+- Use `.env.example` files as templates for required variables.
+- Each component (frontend, agent) can have local `.env.local` overrides for development.
+
 ### Branching Policy
 
 - `main`: Production-ready code.

README.md

@@ -44,7 +44,7 @@
    npm run dev
    ```
 
-3. **Setup the Agent**:
+3. **Setup the Agent** (in a separate terminal):
 
    ```bash
    cd agent
@@ -58,6 +58,81 @@
    cargo build --target wasm32-unknown-unknown
    ```
 
+### Running Frontend and Agent Concurrently
+
+The frontend (Next.js dev server) and agent (Node.js) can run simultaneously for local development:
+
+1. Open two terminals in the project root.
+2. In the first terminal, navigate to the frontend and start the dev server:
+   ```bash
+   cd frontend
+   npm run dev
+   ```
+   The frontend will be available at http://localhost:3000.
+
+3. In the second terminal, navigate to the agent and start it:
+   ```bash
+   cd agent
+   npm start
+   ```
+   The agent will be available at the configured NOTIFICATION_PORT (default: 3001).
+
+Both services will automatically reload on file changes during development.
+
+### Environment Variables
+
+Each component of Smasage uses environment variables configured via `.env` files. See below for the required and optional variables per component.
+
+#### Root Level (`.env`)
+
+Applied globally to both frontend and agent unless overridden locally.
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `GEMINI_API_KEY` | string | (required) | API key for Gemini AI service |
+| `NOTIFICATION_PORT` | number | 3001 | WebSocket server port for notifications |
+| `SOROBAN_RPC_URL` | string | https://soroban-test.stellar.org | Soroban RPC endpoint |
+| `SMASAGE_CONTRACT_ID` | string | (optional) | Smasage contract ID on Stellar |
+
+#### Frontend (`.env` or `.env.local` in `/frontend`)
+
+Frontend-specific variables (prefixed with `NEXT_PUBLIC_` to expose to the browser).
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `NEXT_PUBLIC_WS_URL` | string | ws://localhost:3001 | WebSocket URL for agent communication |
+| `NEXT_PUBLIC_ENABLE_NOTIFICATIONS` | boolean | true | Enable notification features |
+| `NEXT_PUBLIC_PROACTIVE_NUDGES` | boolean | true | Enable proactive financial nudges |
+
+#### Agent (`.env` or `.env.local` in `/agent`)
+
+Backend agent-specific configuration.
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `GEMINI_API_KEY` | string | (required) | API key for Gemini AI service |
+| `NOTIFICATION_PORT` | number | 3001 | Port for WebSocket notification server |
+| `SOROBAN_RPC_URL` | string | https://soroban-test.stellar.org | Soroban RPC endpoint |
+| `SMASAGE_CONTRACT_ID` | string | (optional) | Smasage contract ID on Stellar |
+
+#### Contracts (no runtime env vars)
+
+The Contracts component uses build-time configuration via `Cargo.toml`. No `.env` file is required for local development.
+
+#### Setup Instructions
+
+1. Copy `.env.example` to `.env` in the project root:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Update the following required variables in `.env`:
+   - `GEMINI_API_KEY`: Obtain from your Gemini API dashboard
+
+3. (Optional) If running frontend and agent separately, create `.env.local` files in each directory with component-specific overrides.
+
+4. Never commit `.env` files containing secrets. Use `.env.example` to document the expected variables.
+
 ## 🗺 Roadmap
 
 Our development is tracked via a detailed issue list. Key upcoming milestones include: