Improve .env loading and first-time setup docs

madebygps · madebygps · commit c385f0ff4e03 · 2025-10-13T20:06:58.000-04:00
- Search for .env in priority order (./.env, ~/.config/brain/.env, ~/.brain/.env), resolve symlinks and only load regular readable files; fall back to default dotenv behavior if none found.
- Clarify DIARY_PATH error with recommended locations and link to SETUP_CHECKLIST.md.
- Add comprehensive SETUP_CHECKLIST.md and update README Quick Start/Installation to show first-time setup steps (create ~/.config/brain/.env, fetch .env.example, usage notes and .env search priority).
diff --git a/README.md b/README.md
@@ -12,23 +12,16 @@ AI-powered personal knowledge system with daily planning, reflective journaling,
 Install directly from GitHub:
 
 ```bash
-# Using uv (recommended - fastest)
 uv tool install git+https://github.com/madebygps/second-brain.git
-
-# Or using pipx (isolated environment)
-pipx install git+https://github.com/madebygps/second-brain.git
-
-# Or using pip (system-wide)
-pip install git+https://github.com/madebygps/second-brain.git
 ```
 
 After installation, the `brain` command will be available globally:
 ```bash
 brain --help
-brain plan create today
-brain diary create today
 ```
 
+**Next:** Configure your `.env` file (see [Configuration](#configuration) below).
+
 ### For Development
 
 ```bash
@@ -74,13 +67,23 @@ uv run brain --help
 
 ## Quick Start
 
-After installing (see [Installation](#installation)):
+### First-Time Setup
+
+1. **Install** (see [Installation](#installation) above)
+
+2. **Configure** - Create `~/.config/brain/.env` with your settings:
 
 ```bash
-# Configure (first time only)
-cp .env.example .env
-# Edit .env with your paths and Azure credentials
+mkdir -p ~/.config/brain
+curl -o ~/.config/brain/.env https://raw.githubusercontent.com/madebygps/second-brain/main/.env.example
+nano ~/.config/brain/.env  # Edit with your paths and Azure credentials
+```
+
+See [SETUP_CHECKLIST.md](SETUP_CHECKLIST.md) for detailed setup instructions.
+
+3. **Use**:
 
+```bash
 # Morning: Create your planning entry (saves to PLANNER_PATH)
 brain plan create today
 
@@ -91,7 +94,9 @@ brain diary create today
 brain notes search "discipline"
 ```
 
-> **Note:** If developing locally, prefix commands with `uv run` (e.g., `uv run brain plan create today`)
+> **Note:** The `.env` file is automatically searched in `~/.config/brain/.env`, `~/.brain/.env`, or current directory.
+>
+> **For developers:** When running locally, prefix commands with `uv run` (e.g., `uv run brain plan create today`)
 
 ## Usage
 
@@ -128,12 +133,19 @@ brain --verbose <command>      # Show key operations
 brain --debug <command>        # Full diagnostics with LLM details
 ```
 
-> **Clean UX:** By default, logs are suppressed during operations to avoid interrupting spinners. Use `--verbose` or `--debug` for detailed information with beautiful Rich formatting.
+> **Logs:** By default, logs are suppressed during operations to avoid interrupting spinners. Use `--verbose` or `--debug` for detailed information with beautiful Rich formatting.
 
 > **Cost Tracking:** All Azure OpenAI usage is automatically tracked in a local SQLite database (`~/.brain/costs.db`). Data stays private and grows ~10-50 MB/year for typical use.
 
 ## Configuration
 
+The `brain` CLI automatically searches for `.env` in these locations (in priority order):
+1. Current directory (`./.env`)
+2. User config directory (`~/.config/brain/.env`) ⭐ **Recommended**
+3. Home directory (`~/.brain/.env`)
+
+Create `~/.config/brain/.env` with these settings:
+
 **Required Paths:**
 - `DIARY_PATH` - Path to Obsidian vault or markdown directory for reflection entries
 - `PLANNER_PATH` - Path to directory for daily plan files (separate from diary)
diff --git a/SETUP_CHECKLIST.md b/SETUP_CHECKLIST.md
@@ -0,0 +1,278 @@
+# Setup Checklist for second-brain
+
+Complete guide for first-time setup after installation.
+
+## Installation
+
+
+```bash
+uv tool install git+https://github.com/madebygps/second-brain.git
+```
+
+Verify installation:
+```bash
+brain --version
+# Output: Brain CLI v0.1.0
+```
+
+## Configuration
+
+### Step 1: Create Directories
+
+Create directories for your diary and planner:
+
+```bash
+# Create diary directory (for reflection entries)
+mkdir -p ~/Documents/second-brain/diary
+
+# Create planner directory (for daily plans)
+mkdir -p ~/Documents/second-brain/planner
+```
+
+> **Tip:** Best if used with Obsidian. Point `DIARY_PATH` to your vault directory.
+
+### Step 2: Create .env File
+
+The `brain` CLI automatically searches for `.env` in these locations (in order):
+
+1. **Current directory** (`./.env`)
+2. **User config directory** (`~/.config/brain/.env`) ⭐ **Recommended**
+3. **Home directory** (`~/.brain/.env`)
+
+**Recommended Setup (works from anywhere):**
+
+```bash
+# Create config directory
+mkdir -p ~/.config/brain
+
+# Download the example .env template
+curl -o ~/.config/brain/.env https://raw.githubusercontent.com/madebygps/second-brain/main/.env.example
+
+# Set secure permissions (readable by you only)
+chmod 600 ~/.config/brain/.env
+
+# Edit with your settings
+nano ~/.config/brain/.env  # or use your preferred editor
+```
+
+That's it! No need for shell aliases or cd-ing around. The `brain` command will automatically find your config.
+
+> **Security Note:** Your `.env` file contains API keys. The `chmod 600` command ensures only you can read it.
+
+
+The current directory's `.env` takes priority over the global config.
+
+### Step 3: Configure .env
+
+Edit your `.env` file with the following **required** variables:
+
+```bash
+# Required: Paths (created in Step 1)
+DIARY_PATH=/Users/yourname/Documents/second-brain/diary
+PLANNER_PATH=/Users/yourname/Documents/second-brain/planner
+
+# Required: Azure OpenAI (get from Azure Portal)
+AZURE_OPENAI_API_KEY=your-api-key-here
+AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
+AZURE_OPENAI_DEPLOYMENT=gpt-4o
+AZURE_OPENAI_API_VERSION=2024-02-15-preview
+
+# Required: Azure AI Search (for book notes search)
+AZURE_SEARCH_ENDPOINT=https://your-search-service.search.windows.net
+AZURE_SEARCH_API_KEY=your-search-api-key-here
+AZURE_SEARCH_INDEX_NAME=second-brain-notes
+```
+
+**Optional variables** (with defaults):
+
+```bash
+# Cost tracking database location
+BRAIN_COST_DB_PATH=~/.brain/costs.db
+
+# Logging
+BRAIN_LOG_LEVEL=INFO
+BRAIN_LOG_FILE=~/.brain/logs/brain.log
+```
+
+### Step 4: Get Azure Credentials
+
+#### Azure OpenAI (Required)
+
+1. Go to [Azure Portal](https://portal.azure.com)
+2. Navigate to your Azure OpenAI resource
+3. Go to **Keys and Endpoint**
+4. Copy:
+   - **KEY 1** → `AZURE_OPENAI_API_KEY`
+   - **Endpoint** → `AZURE_OPENAI_ENDPOINT`
+5. Go to **Model deployments**
+6. Copy your deployment name (e.g., "gpt-4o") → `AZURE_OPENAI_DEPLOYMENT`
+
+#### Azure AI Search (Required for notes search)
+
+1. Go to [Azure Portal](https://portal.azure.com)
+2. Navigate to your Azure AI Search resource
+3. Go to **Keys**
+4. Copy:
+   - **Primary admin key** → `AZURE_SEARCH_API_KEY`
+5. Copy the URL from Overview page → `AZURE_SEARCH_ENDPOINT`
+6. Go to **Indexes** and copy your index name → `AZURE_SEARCH_INDEX_NAME`
+
+### Step 5: Test Configuration
+
+Test that everything is configured correctly:
+
+```bash
+# Test diary commands (uses DIARY_PATH)
+brain diary list
+
+# Test plan commands (uses PLANNER_PATH)
+brain plan create today
+
+# Test notes search (uses Azure AI Search)
+brain notes status
+
+# Test cost tracking (uses BRAIN_COST_DB_PATH)
+brain cost summary
+```
+
+## Troubleshooting
+
+### "DIARY_PATH must be set in .env"
+
+The `brain` command cannot find your `.env` file. The error message will show where it's looking.
+
+Create `.env` in the recommended location:
+```bash
+mkdir -p ~/.config/brain
+nano ~/.config/brain/.env
+```
+
+### "DIARY_PATH does not exist: /path/to/dir"
+
+The directory doesn't exist. Create it:
+```bash
+mkdir -p /path/to/dir
+```
+
+### "Azure OpenAI credentials required"
+
+Your Azure OpenAI credentials are missing or incorrect. Double-check:
+1. `AZURE_OPENAI_API_KEY` is set correctly
+2. `AZURE_OPENAI_ENDPOINT` ends with a `/`
+3. `AZURE_OPENAI_DEPLOYMENT` matches your deployment name in Azure Portal
+
+### .env File Not Loading
+
+The `brain` CLI searches for `.env` in multiple locations automatically. If it's not loading:
+
+1. **Check file exists in a searched location:**
+   ```bash
+   ls -la ~/.config/brain/.env  # Recommended location
+   ls -la ~/.brain/.env         # Alternative location
+   ls -la .env                  # Current directory
+   ```
+
+2. **Check file permissions (should be 600):**
+   ```bash
+   ls -l ~/.config/brain/.env
+   # Should show: -rw------- (readable/writable by you only)
+
+   # Fix if needed:
+   chmod 600 ~/.config/brain/.env
+   ```
+
+3. **Verify file has correct format:**
+   ```bash
+   cat ~/.config/brain/.env | grep DIARY_PATH
+   # Should show: DIARY_PATH=/your/path
+   ```
+
+## Security Best Practices
+
+### Protect Your API Keys
+
+Your `.env` file contains sensitive Azure API keys. Follow these practices:
+
+1. **File Permissions:**
+   ```bash
+   chmod 600 ~/.config/brain/.env  # Only you can read/write
+   ```
+
+2. **Never Commit to Git:**
+   ```bash
+   # If you accidentally staged it:
+   git rm --cached .env
+   echo ".env" >> .gitignore
+   ```
+
+3. **Regular Key Rotation:**
+   - Rotate Azure API keys periodically (every 90 days)
+   - Update `.env` with new keys
+   - Revoke old keys in Azure Portal
+
+4. **Config Location Safety:**
+   - `~/.config/brain/.env` is in your home directory (safe)
+   - Current directory `.env` takes priority (be aware in shared directories)
+   - Only load from trusted locations (the tool only searches these 3 paths)
+
+### What the Tool Does
+
+The `brain` CLI is designed with security in mind:
+
+✅ Only searches 3 specific paths (no arbitrary file loading)
+✅ Validates files are regular files (not directories or special files)
+✅ Resolves symlinks to prevent path traversal
+✅ Only reads text configuration (no code execution)
+✅ Uses `python-dotenv` (standard, audited library)
+
+### Data Privacy
+
+All your data stays local:
+
+- **Diary/Plan entries:** Stored in paths you specify (`DIARY_PATH`, `PLANNER_PATH`)
+- **Cost tracking:** SQLite database in `~/.brain/costs.db` (your machine only)
+- **No telemetry:** Nothing is sent except Azure OpenAI API calls (for LLM features)
+- **No cloud sync:** You control where files are stored (use Obsidian Sync, etc. if desired)
+
+## Next Steps
+
+Once configured:
+
+1. **Morning routine:**
+   ```bash
+   brain plan create today
+   ```
+
+2. **Evening routine:**
+   ```bash
+   brain diary create today
+   # Write your reflection
+   brain diary link today  # Generate backlinks
+   ```
+
+3. **Weekly review:**
+   ```bash
+   brain diary report 7
+   brain diary patterns 7
+   ```
+
+4. **Search your notes:**
+   ```bash
+   brain notes search "topic"
+   ```
+
+5. **Track costs:**
+   ```bash
+   brain cost summary
+   brain cost trends 30
+   ```
+
+## Updating
+
+To update to the latest version:
+
+```bash
+uv tool install --force git+https://github.com/madebygps/second-brain.git
+```
+
+Your `.env` configuration file is not affected by updates.
diff --git a/brain_core/config.py b/brain_core/config.py
