path: root/SETUP_GUIDE.md

# Setup Guide

## Step-by-Step API Key Setup

### 1. Todoist (Required)

1. Log in to [Todoist](https://todoist.com)
2. Click your profile icon → **Settings**
3. Go to **Integrations** tab
4. Scroll down to **Developer** section
5. Copy your **API token**
6. Add to `.env`: `TODOIST_API_KEY=your_token_here`

### 2. Trello (Required)

Trello requires **both** an API key and a token:

1. Go to https://trello.com/power-ups/admin
2. Click **"Create a Power-Up"** (or select an existing one)
   - Name: "Personal Dashboard" (or anything you prefer)
   - Workspace: Select your workspace
   - Click "Create"
3. In your Power-Up, go to the **"API Key"** tab
4. Click **"Generate a new API Key"**
5. **Copy the API Key** shown
   - ⚠️ **Important:** Copy the **API Key**, NOT the **Secret**
   - Add to `.env`: `TRELLO_API_KEY=abc123...`
6. In the description text below the API Key, look for instructions about "testing" or "for-yourself"
7. Click the **"Token"** link in those instructions (or "manually generate a Token")
8. Click **"Allow"** to authorize access to your account
9. **Copy the Token** shown on the next page
   - Add to `.env`: `TRELLO_TOKEN=xyz789...`

**Example `.env` for Trello:**
```bash
TRELLO_API_KEY=a1b2c3d4e5f6...          # API Key (not Secret!)
TRELLO_TOKEN=1234567890abcdef...        # Personal token for testing
```

**Common Confusion:**
- ❌ Don't use the "Secret" - that's for OAuth apps
- ✅ Use API Key + Token (from the testing/personal use instructions)

### 3. Obsidian (Optional)

If you use Obsidian for notes:

1. Find your Obsidian vault folder (usually in Documents/Obsidian)
2. Copy the **full path** to your vault
3. Add to `.env`: `OBSIDIAN_VAULT_PATH=/path/to/your/vault`

**Examples:**
- macOS: `/Users/yourname/Documents/Obsidian/MyVault`
- Linux: `/home/yourname/Documents/Obsidian/MyVault`
- Windows: `C:\Users\yourname\Documents\Obsidian\MyVault`

### 4. PlanToEat (Optional - Skip if no access)

**Note:** PlanToEat's API is not publicly documented or easily accessible.

If you don't have a PlanToEat API key, simply **leave it blank** in `.env`:
```bash
# PLANTOEAT_API_KEY=    # Leave commented out or empty
```

The dashboard will work fine without it - you just won't see meal planning data.

### 5. AI Agent Access (Optional)

For Claude.ai to access your dashboard:

1. Generate a secure API key:
   ```bash
   openssl rand -hex 32
   ```

2. Add to `.env`:
   ```bash
   AI_AGENT_API_KEY=a1b2c3d4e5f6...
   ```

3. Share the URL + token with Claude separately

## Complete .env Example

```bash
# Required
TODOIST_API_KEY=abc123def456...
TRELLO_API_KEY=a1b2c3d4e5f6...
TRELLO_TOKEN=1234567890abcdef...

# Optional
OBSIDIAN_VAULT_PATH=/Users/yourname/Documents/Obsidian/MyVault
# PLANTOEAT_API_KEY=    # Not publicly available
AI_AGENT_API_KEY=xyz789...

# Server settings (optional)
PORT=8080
CACHE_TTL_MINUTES=5
DEBUG=false
```

## Running the Dashboard

1. **Copy environment template:**
   ```bash
   cp .env.example .env
   ```

2. **Edit `.env`** with your API keys (see above)

3. **Run the application:**
   ```bash
   go run cmd/dashboard/main.go
   ```

4. **Access the dashboard:**
   - Web UI: http://localhost:8080
   - AI endpoint: http://localhost:8080/api/claude/snapshot

## Troubleshooting

### "TODOIST_API_KEY is required"
- Make sure you've added `TODOIST_API_KEY=...` to `.env`
- No spaces around the `=` sign
- No quotes needed

### "TRELLO_API_KEY is required"
- You need **both** `TRELLO_API_KEY` and `TRELLO_TOKEN`
- Get both from https://trello.com/power-ups/admin
- Create a Power-Up, go to "API Key" tab
- Copy the API Key (NOT the Secret!)
- Follow the "testing/for-yourself" instructions to generate a token

### "TRELLO_TOKEN is required"
- In Power-Up Admin Portal (https://trello.com/power-ups/admin)
- Go to your Power-Up's "API Key" tab
- Look for "testing/for-yourself" instructions in the description
- Click the "Token" link in those instructions (NOT the Secret!)
- Click "Allow" to authorize
- Copy the long token string

### No Trello boards showing
- Verify both API key and token are correct
- Check that you have boards in your Trello account
- Try the "Refresh" button on the dashboard

### No tasks showing
- Verify your Todoist API token is correct
- Check that you have tasks in Todoist
- Make sure tasks aren't all completed

### Obsidian notes not showing
- Verify the vault path is correct and exists
- Make sure the application has read permissions
- Check that you have `.md` files in the vault

### PlanToEat not working
- This is expected - PlanToEat's API is not publicly available
- Simply leave `PLANTOEAT_API_KEY` empty or commented out
- The dashboard will work without it

## Testing Your Setup

### Test Todoist
```bash
curl -H "Authorization: Bearer YOUR_TODOIST_KEY" \
     https://api.todoist.com/rest/v2/tasks
```

Should return your tasks in JSON format.

### Test Trello
```bash
curl "https://api.trello.com/1/members/me/boards?key=YOUR_API_KEY&token=YOUR_TOKEN"
```

Should return your boards in JSON format. If you get a 401 error, verify both your API key and token are correct.

### Test Dashboard
```bash
# Start the server
go run cmd/dashboard/main.go

# In another terminal, test the endpoint
curl http://localhost:8080/api/tasks
```

Should return your tasks from the dashboard.

## Next Steps

Once everything is set up:
1. Visit http://localhost:8080 to see your dashboard
2. Check that Trello boards appear at the top
3. Verify Todoist tasks are listed
4. Test the manual refresh button
5. If you set up AI access, test with Claude!

Need help? Check the logs in the terminal where you ran `go run cmd/dashboard/main.go`.