# Clawdbot System Reference

Complete reference for the Clawdbot automation system running on VPS `134.199.153.159`.

## Notion Databases

| Database | Purpose | MCP data_source_id |
|----------|---------|-------------------|
| **Command Center** | Central hub, dashboard | `019468b0-47e2-7f27-9d17-c38c4b28799c` |
| **Work Tracker** | Tasks, bugs, priorities | `6ede5973-7f70-4814-bdaa-711934c18194` |
| **System State** | Health status, metrics | `df695bc0-af61-4eba-86fc-cf7325d1ddfb` |
| **Deploy Log** | Deployment records | `01946886-c60e-7d5f-9558-c2ad6ac9aced` |
| **Lessons Learned** | Post-deploy learnings | `019465a8-9ca5-457e-80ff-273919caa477` |
| **AI Agents** | Agent status tracking | `01946633-34c3-7e98-a34e-db3105e44f48` |
| **Hot Leads** | High-score leads from Growth Engine | `2f863e0c-a7d5-81db-8677-ffc1dd4c0868` |

### URL vs MCP IDs
**Important:** Notion MCP uses `data_source_id`, not the URL `database_id`. To find the correct ID:
```
Use API-post-search with the database name to get the data_source_id
```

## Scripts Overview

### Core Operations
| Script | Purpose | Schedule |
|--------|---------|----------|
| `health-check.sh` | Basic health check | Every 5 min |
| `health-check-v2.sh` | Health check with auto-rollback | Every 5 min |
| `telegram-alert.sh` | Send alerts to Telegram | On-demand |
| `agent-status.sh` | Update AI Agent status in Notion | On-demand |
| `slack-to-notion.sh` | Monitor Slack, create tasks | Every 5 min |

### Briefs
| Script | Purpose | Schedule |
|--------|---------|----------|
| `morning-brief.sh` | Morning summary to Telegram | 6am Sydney |
| `evening-brief.sh` | Evening summary to Telegram | 6pm Sydney |

### Self-Improvement Loop
| Script | Purpose | Schedule |
|--------|---------|----------|
| `cc-read-lessons.sh` | Read lessons at CC session start | Session start |
| `cc-learn-stage.sh` | Stage a new lesson to Notion | After discoveries |
| `weekly-patterns.sh` | Analyze patterns, identify improvements | Monday 7am |

### Data Sync
| Script | Purpose | Schedule |
|--------|---------|----------|
| `hot-leads-sync.sh` | Sync hot leads (score 70+) to Notion | Hourly |

### Approval Workflow
| Script | Purpose | Schedule |
|--------|---------|----------|
| `check-approvals.sh` | Check for pending approvals in Notion | On-demand |
| `cc-startup.sh` | CC session initialization | Session start |

## Integration Points

### Growth Engine API
- **URL:** `https://rateright-growth-production.up.railway.app`
- **Internal Endpoints:** Use `X-Internal-Key` header (same as `INTERNAL_JOB_KEY`)
- **Hot Leads:** `GET /api/leads/internal/hot` - Returns leads with score >= 70

### Git Sync
VPS pulls from GitHub every 30 minutes:
```bash
# Cron: */30 * * * * cd /root/rateright-growth && git pull origin main
```
This syncs `docs/LESSONS.md` so Clawdbot and CC share knowledge.

### Slack Integration
- Monitor channels for commands and mentions
- Create Work Tracker items from Slack messages
- Send deployment notifications

### Telegram Integration
- Morning/evening briefs
- Alert notifications (errors, deploys, health issues)
- Format: Level prefix (INFO, WARN, ERROR, CRITICAL)

## Self-Improvement Protocol

Both CC (Claude Code) and Clawdbot share knowledge through:

1. **docs/LESSONS.md** - Git-synced every 30 min
2. **Lessons Learned Notion DB** - Direct API access

### After Every Fix/Discovery/Workaround:
```
Ask: "Is there a lesson here?"

If yes, do ALL THREE:
1. Fix the system (so it CAN'T happen again)
2. Add to docs/LESSONS.md
3. Run: ./cc-learn-stage.sh "Title" "What worked" "What failed" "What was slow"
```

### Pattern Categories:
- **DO MORE** - Things that worked well
- **AVOID** - Things that caused issues
- **IMPROVE** - Things that were slow or awkward

## Environment Variables

Required in `config.env`:
```bash
# Notion
NOTION_API_KEY=secret_xxx

# Telegram
TELEGRAM_BOT_TOKEN=xxx:yyy
TELEGRAM_CHAT_ID=123456

# Slack
SLACK_BOT_TOKEN=xoxb-xxx

# APIs
ANTHROPIC_API_KEY=sk-ant-xxx
GROWTH_ENGINE_API=https://rateright-growth-production.up.railway.app
INTERNAL_JOB_KEY=xxx  # For internal API calls

# Database IDs (URL format, for shell scripts)
WORK_TRACKER_DB=xxx
DEPLOY_LOG_DB=xxx
SYSTEM_STATE_DB=xxx
LESSONS_LEARNED_DB=xxx
AI_AGENTS_DB=xxx
HOT_LEADS_DB=xxx
```

## Logs

All logs at `/var/log/clawdbot/`:
- `health-check.log`
- `health-check-v2.log`
- `slack-sync.log`
- `morning-brief.log`
- `evening-brief.log`
- `hot-leads-sync.log`
- `weekly-patterns.log`

## Emergency Procedures

### Health Check Failure
`health-check-v2.sh` auto-rolls back if:
1. API returns 5xx errors
2. Database connection fails
3. Critical service unavailable

Manual rollback:
```bash
cd /root/rateright-growth
git revert HEAD~1
git push origin main
```

### Telegram Not Working
1. Check bot token: `curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe"`
2. Check chat ID matches
3. Verify VPS can reach api.telegram.org

### Notion Sync Failed
1. Check API key validity
2. Verify database IDs are correct (use API-post-search)
3. Check Notion API status: https://status.notion.so

## Timezone Reference

Sydney times (for cron):
| Sydney Time | UTC (AEDT) | UTC (AEST) |
|-------------|------------|------------|
| 6am | 7pm prev day | 8pm prev day |
| 6pm | 7am | 8am |
| 7am (weekly) | 8pm Sun | 9pm Sun |

## Related Files

- `AGENTS.md` - AI agent personalities and capabilities
- `SOUL.md` - Clawdbot's core identity and values
- `IDENTITY.md` - Team context and relationships
- `TOOLS.md` - Available tools and integrations
- `docs/LESSONS.md` - Shared lessons (git-synced)