# Scout Agent Setup Checklist

## Prerequisites
- [ ] DigitalOcean VPS access (syd1, 2 vCPU, 8GB RAM)
- [ ] Clawdbot gateway running and accessible
- [ ] Telegram bot credentials for RateRight group delivery
- [ ] $100/month team budget allocation confirmed

## Phase 1: Core Infrastructure Setup

### Clawdbot Instance Configuration
- [ ] Create new Clawdbot instance on port 18794
  ```bash
  clawdbot create scout --port 18794 --workspace /home/scout
  ```
- [ ] Configure default model to Kimi (free tier)
  ```bash
  clawdbot config scout set model moonshot/kimi
  clawdbot config scout set fallback_model anthropic/claude-sonnet-4-20250514
  ```
- [ ] Set up agent identity and workspace
  ```bash
  mkdir -p /home/scout/{memory,plans,archive}
  cp memory/plans/scout-soul.md /home/scout/SOUL.md
  ```
- [ ] Configure memory and session management
- [ ] Test basic instance startup and health check

### Authentication & Permissions
- [ ] Copy shared API keys from `/root/.clawdbot/`
  - [ ] Brave Search API (web search)
  - [ ] Google API keys (if needed for data sources)
- [ ] Set up dedicated Telegram bot token for Scout
- [ ] Configure Telegram group permissions (RateRight topic access)
- [ ] Test message delivery to Telegram

### Workspace Structure
- [ ] Create directory structure:
  ```
  /home/scout/
  ├── SOUL.md (personality file)
  ├── USER.md (Michael's profile)
  ├── AGENTS.md (team context)
  ├── TOOLS.md (local config)
  ├── MEMORY.md (long-term memory)
  ├── HEARTBEAT.md (routine checks)
  ├── memory/
  │   ├── 2026-01-XX.md (daily logs)
  │   ├── heartbeat-state.json
  │   └── sources/
  ├── data/
  │   ├── competitors/
  │   ├── news-feeds/
  │   └── industry-reports/
  └── scripts/
      ├── scraper-configs/
      └── filters/
  ```

## Phase 2: News Source Configuration

### Free API Sources
- [ ] Hacker News API setup
  ```bash
  # Test HN API connection
  curl "https://hacker-news.firebaseio.com/v0/topstories.json"
  ```
- [ ] Reddit API configuration
  - [ ] Register application for API access
  - [ ] Configure subreddit monitoring: r/construction, r/australia, r/sydney
  - [ ] Test post retrieval and filtering
- [ ] RSS feed aggregator setup
  - [ ] Master Builders Association NSW
  - [ ] Construction industry publications
  - [ ] Government regulatory updates (WorkSafe NSW)

### Web Scraping Setup
- [ ] Configure browser tool for Clawdbot
- [ ] Create scraper configurations for:
  - [ ] **Hipages:** pricing page, blog, careers, product updates
  - [ ] **ServiceSeeking:** similar monitoring setup
  - [ ] **Airtasker:** construction category focus
  - [ ] **BuildConnect:** enterprise announcements
- [ ] Implement rate limiting and respectful crawling
  - [ ] User-agent rotation
  - [ ] Request delays (2-5 seconds between requests)
  - [ ] IP rotation if needed
- [ ] Test scraper reliability and error handling

### Social Media Monitoring
- [ ] X/Twitter monitoring setup (if API access available)
  - [ ] Key accounts: @sama, @karpathy, construction industry leaders
  - [ ] Hashtag monitoring: #construction #AI #marketplace #startup
- [ ] LinkedIn industry page monitoring (manual/weekly)

## Phase 3: Filtering and Processing Pipeline

### Content Filtering Rules
- [ ] Create relevance scoring algorithm
  - [ ] Keywords: RateRight, construction, AI, marketplace, hiring, gig economy
  - [ ] Negative filters: irrelevant industries, spam, off-topic
  - [ ] Priority scoring: competitive intel > AI developments > industry trends
- [ ] Implement filtering configuration:
  ```json
  {
    "high_priority_keywords": ["hipages", "serviceseeking", "airtasker", "construction", "trades", "AI"],
    "alert_triggers": ["price change", "new feature", "funding", "regulatory"],
    "ignore_patterns": ["crypto", "web3", "gaming"],
    "relevance_threshold": 0.7
  }
  ```
- [ ] Test filtering accuracy with sample data

### Alert Classification
- [ ] Implement 4-tier alert system:
  - [ ] 🔴 CRITICAL: Immediate Telegram ping
  - [ ] 🟡 HIGH: Highlighted in daily briefing
  - [ ] 🟢 STANDARD: Regular briefing item
  - [ ] ⚪ ARCHIVE: Log only
- [ ] Create alert templates for consistent formatting
- [ ] Test alert delivery and escalation paths

## Phase 4: Telegram Delivery Configuration

### Bot Setup
- [ ] Create dedicated Scout Telegram bot via @BotFather
- [ ] Add bot to RateRight Telegram group
- [ ] Configure bot permissions for topic posting
- [ ] Test message delivery to specific topics:
  - [ ] RateRight topic (main briefings)
  - [ ] System topic (alerts and status)

### Message Formatting
- [ ] Create daily briefing template
- [ ] Create urgent alert template
- [ ] Create weekly deep dive template
- [ ] Test message formatting and emoji rendering
- [ ] Configure message threading for follow-ups

### Delivery Reliability
- [ ] Implement retry logic for failed deliveries
- [ ] Set up fallback notification methods
- [ ] Configure delivery confirmation logging
- [ ] Test network failure recovery

## Phase 5: Scheduling and Automation

### Heartbeat Configuration
- [ ] Create `HEARTBEAT.md` with routine checks:
  ```markdown
  # Scout Heartbeat Checklist
  
  ## Every 2 Hours (Rotate)
  - Check competitor websites for changes
  - Scan Hacker News for relevant stories
  - Monitor Reddit construction discussions
  - Review RSS feed updates
  
  ## Daily (7:00 AM)
  - Generate and send daily briefing
  - Update competitor intelligence files
  - Process overnight news accumulation
  
  ## Weekly (Sunday 6:00 PM)
  - Generate deep dive analysis
  - Clean up archived data
  - Update filtering rules based on feedback
  ```
- [ ] Configure heartbeat frequency (every 2 hours)
- [ ] Test heartbeat execution and logging

### Cron Jobs for Precise Scheduling
- [ ] Daily briefing: 7:00 AM Sydney time
  ```bash
  # Add to cron or use Clawdbot scheduling
  0 7 * * * /usr/local/bin/clawdbot exec scout "Generate and send daily briefing"
  ```
- [ ] Weekly deep dive: Sunday 6:00 PM Sydney time
- [ ] Competitor check: Every 6 hours during business hours
- [ ] Data cleanup: Daily at 2:00 AM

### State Management
- [ ] Create `heartbeat-state.json` tracking:
  ```json
  {
    "lastChecks": {
      "hackernews": null,
      "reddit": null,
      "hipages": null,
      "serviceseeking": null,
      "airtasker": null
    },
    "lastBriefing": null,
    "alertCount": 0,
    "dailyQuota": {
      "briefings": 1,
      "alerts": 5,
      "resets": "2026-01-15T00:00:00Z"
    }
  }
  ```

## Phase 6: Testing and Validation

### Functionality Testing
- [ ] Test each data source independently
- [ ] Verify filtering accuracy with known test cases
- [ ] Confirm alert classification working correctly
- [ ] Validate Telegram delivery to all channels
- [ ] Test error handling and recovery

### Integration Testing
- [ ] Full pipeline test: source → filter → format → deliver
- [ ] Load testing with high-volume news days
- [ ] Network failure recovery testing
- [ ] API rate limiting behavior verification

### Quality Assurance
- [ ] Manual review of first week's briefings
- [ ] Team feedback collection and analysis
- [ ] False positive/negative rate measurement
- [ ] Adjust filtering thresholds based on results

## Phase 7: Monitoring and Optimization

### Performance Monitoring
- [ ] Set up logging for all major operations
- [ ] Monitor API usage and rate limits
- [ ] Track cost metrics (API calls, compute time)
- [ ] Implement alerting for system failures

### Feedback Loop
- [ ] Create mechanism for team feedback on briefings
- [ ] Weekly accuracy review with Rivet
- [ ] Monthly optimization based on usage patterns
- [ ] Quarterly strategic review of monitored sources

## Go-Live Checklist

### Pre-Launch
- [ ] All technical systems tested and operational
- [ ] Team walkthrough of Scout capabilities
- [ ] Emergency contact procedures established
- [ ] Backup/recovery procedures documented

### Launch Day
- [ ] Morning test briefing sent
- [ ] All team members confirm receipt
- [ ] Monitor first day operations closely
- [ ] Address any immediate issues

### First Week
- [ ] Daily quality checks on briefings
- [ ] Team satisfaction survey
- [ ] Performance metrics review
- [ ] Adjust filtering based on early feedback

## Success Criteria
- [ ] 95% uptime for daily briefings (delivered by 7:05 AM)
- [ ] <10% false positive rate on urgent alerts
- [ ] Team satisfaction score >8/10
- [ ] Monthly costs <$20 (within budget allocation)
- [ ] All competitor major moves detected within 4 hours

## Rollback Plan
- [ ] Document manual intelligence gathering process
- [ ] Prepare Rivet to temporarily handle Scout duties
- [ ] Identify critical vs. nice-to-have features for minimal viable service
- [ ] Test rollback procedures before going live

---

**Estimated Setup Time:** 2-3 weeks with 1-2 hours daily effort
**Budget Requirements:** ~$15/month operational costs
**Dependencies:** Stable internet, Telegram access, competitor website availability