myorg-assistant/QUICKSTART.md

# MyOrg Assistant - Quick Start Guide

Get your personal assistant up and running in 15 minutes!

## What You're Building

A complete AI-powered personal assistant that:
- 🤖 Manages your GTD tasks via Discord or web interface
- 🌅 Sends morning briefings at 8 AM
- 🌆 Sends evening summaries at 8 PM  
- ⏰ Warns about deadlines automatically
- 🔄 Syncs everything via git
- 📊 Provides a beautiful web dashboard

## Prerequisites Checklist

Before starting, ensure you have:

- [ ] **Python 3.11+** installed
- [ ] **Git** installed
- [ ] **LiteLLM endpoint** running (with Claude API access)
- [ ] **Discord bot** created (5 min setup - see below)
- [ ] **myorg repository** (or use test data)
- [ ] **k3s cluster** (optional - for production deployment)

## Step 1: Get the Code (2 minutes)

```bash
git clone <your-repo-url>
cd myorg-assistant

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

## Step 2: Create Discord Bot (5 minutes)

1. Visit [Discord Developer Portal](https://discord.com/developers/applications)
2. Click "New Application" → Name it "MyOrg Assistant"
3. Go to "Bot" → Click "Add Bot"
4. Enable these intents:
   - ✅ Message Content Intent
   - ✅ Server Members Intent
5. Click "Reset Token" → **Copy this token!**
6. Go to "OAuth2" → "URL Generator"
   - Check: `bot`, `applications.commands`
   - Bot Permissions: `Send Messages`, `Read Messages`, `Read Message History`
7. Open the generated URL to invite bot to your server

## Step 3: Configure Environment (3 minutes)

```bash
cp .env.example .env
```

Edit `.env` and fill in:

```bash
# === REQUIRED ===

# Your LiteLLM endpoint
LITELLM_ENDPOINT=http://localhost:4000
LITELLM_API_KEY=sk-your-key

# Discord bot token (from Step 2)
DISCORD_BOT_TOKEN=YOUR.BOT.TOKEN.HERE
DISCORD_CHANNEL_ID=123456789  # Right-click channel → Copy ID

# Your myorg repository
MYORG_REPO_PATH=./tests/fixtures/test_myorg  # Use test data for now
GIT_REPO_URL=https://github.com/yourusername/myorg.git
GIT_USERNAME=yourusername
GIT_TOKEN=ghp_your_github_token

# === OPTIONAL ===

# Web interface password (leave empty for no password)
WEB_PASSWORD=mypassword

# Your timezone
TIMEZONE=Europe/Madrid
```

**Quick Tip**: Don't have a myorg repo? Use the test data included:
```bash
export MYORG_REPO_PATH=./tests/fixtures/test_myorg
```

## Step 4: Test Locally (2 minutes)

### Test CLI Mode

```bash
python -m src.main cli
```

Try these commands:
```
You: list files
You: show all tasks
You: add task: Test the system @computer-deep
You: exit
```

### Test Discord Bot

```bash
python -m src.main bot
```

In Discord:
```
@MyOrgBot help
@MyOrgBot add task: Test Discord integration
@MyOrgBot /tasks
```

### Test Web Interface

```bash
python -m src.main web
```

Visit: http://localhost:8000

## Step 5: Deploy to Kubernetes (3 minutes)

### Quick Deploy

```bash
cd k8s

# 1. Create secret with your credentials
cp secret.yaml.example secret.yaml
# Edit secret.yaml with your tokens

kubectl apply -f secret.yaml

# 2. Run deployment script
./deploy.sh
```

### Verify Deployment

```bash
# Check pod status
kubectl get pods -l app=myorg-assistant

# View logs
kubectl logs -f deployment/myorg-assistant

# Check scheduled jobs
kubectl get cronjobs
```

You should see:
- Main pod running (Discord bot + web server)
- 5 CronJobs configured
- Web service exposed on port 8000

## What Happens Next?

Once deployed, your assistant will:

**Immediately:**
- ✅ Respond to Discord messages
- ✅ Serve web interface at port 8000
- ✅ Sync git every 15 minutes

**At 8:00 AM (your timezone):**
- 🌅 Send morning briefing to Discord

**Every Hour:**
- ⏰ Check deadlines and send warnings if needed

**At 8:00 PM:**
- 🌆 Send evening summary to Discord

**Every Monday at 9 AM:**
- ⏸️  Send waiting list follow-up

## Usage Examples

### Discord

**Add Tasks:**
```
@MyOrgBot Add task: Buy groceries tomorrow @recados
@MyOrgBot Recordatori: Review PR +work due:2026-02-05
```

**Check Tasks:**
```
@MyOrgBot What should I work on? I have 2 hours @computer-deep
@MyOrgBot /tasks priority:A
@MyOrgBot Show tasks for project myorg-assistant
```

**Get Information:**
```
@MyOrgBot /today
@MyOrgBot /briefing
@MyOrgBot What's my calendar like this week?
```

### Web Interface

Navigate to:
- **Dashboard** (`/`) - Today's overview
- **Chat** (`/chat`) - Talk to assistant
- **Tasks** (`/tasks`) - Manage todos
- **Calendar** (`/calendar`) - View events
- **Projects** (`/projects`) - Track projects

## Troubleshooting

### Bot Not Responding?

```bash
# Check logs
kubectl logs -f deployment/myorg-assistant

# Common fixes:
# 1. Verify Discord token in secret
# 2. Check bot has permissions in server
# 3. Ensure Message Content Intent is enabled
```

### LiteLLM Connection Error?

```bash
# Test endpoint
curl http://your-litellm-endpoint:4000/health

# Verify these in .env:
LITELLM_ENDPOINT=http://... (correct URL?)
LITELLM_API_KEY=... (valid key?)
```

### Git Sync Failing?

```bash
# Check git job logs
kubectl logs job/myorg-git-sync-xxxxx

# Common fixes:
# 1. Verify git token has repo permissions
# 2. Check repository URL is correct
# 3. Ensure branch name matches (default: main)
```

### Web Interface 401 Unauthorized?

If you set `WEB_PASSWORD`, use HTTP Basic Auth:
- Username: (any value)
- Password: your WEB_PASSWORD value

Or remove the password from .env to disable auth.

## Next Steps

### For Production Use

1. **Set up your real myorg repository:**
   ```bash
   # Update .env with your repo
   MYORG_REPO_PATH=/path/to/your/myorg
   GIT_REPO_URL=https://github.com/you/myorg.git
   ```

2. **Configure external access:**
   ```bash
   # Edit k8s/ingress.yaml with your domain
   kubectl apply -f k8s/ingress.yaml
   ```

3. **Adjust timezone:**
   ```bash
   # In .env or k8s/configmap.yaml
   TIMEZONE=Your/Timezone
   ```

4. **Customize briefing times:**
   Edit the schedule in:
   - `k8s/cronjobs/morning-briefing.yaml` (default: 8 AM)
   - `k8s/cronjobs/evening-summary.yaml` (default: 8 PM)

### Explore Features

- Read [README.md](README.md) for full documentation
- Check [DEPLOYMENT.md](DEPLOYMENT.md) for advanced deployment
- See [project-plan.md](project-plan.md) for architecture details

## Getting Help

**Logs are your friend:**
```bash
# Main app logs
kubectl logs -f deployment/myorg-assistant

# Specific job logs
kubectl get jobs
kubectl logs job/myorg-morning-briefing-xxxxx
```

**Common Commands:**
```bash
# Restart deployment
kubectl rollout restart deployment/myorg-assistant

# Check all resources
kubectl get all -l app=myorg-assistant

# Delete everything (careful!)
kubectl delete -f k8s/
```

## Success! 🎉

You now have:
- ✅ AI assistant managing your GTD system
- ✅ Discord bot for mobile/quick access
- ✅ Web dashboard for detailed management
- ✅ Automated daily briefings
- ✅ Deadline warnings
- ✅ Automatic git synchronization

**Your morning tomorrow will look like this:**

```
🌅 Good Morning! - Saturday, February 01, 2026

📅 Today's Schedule:
  • 09:00 Morning coffee @personal
  • 14:00 Work on myorg assistant +myorg-assistant

✅ Priority Tasks:
  • (A) Complete Phase 4 +myorg-assistant @computer-deep
  • (B) Review documentation +myorg-assistant

Have a productive day! 🚀
```

Welcome to your new AI-powered productivity system! 🤖✨