Add comprehensive API Rate Limits & Throttling documentation

Added comprehensive API rate limiting documentation covering all major integration points:

**LinkedIn API:**
- Connection/messaging limits (100-200/week, 150 messages/day)
- API request limits by scale (7,500-30,000 requests/day)
- Exponential backoff implementation (15-30 min delays)

**Email APIs (SendGrid, Mailgun):**
- Request rate limits (300-600 requests/minute)
- Daily email quotas by plan tier
- Automatic throttling behavior

**Phone/SMS (Twilio):**
- 1 CPS limit per account/phone number
- Conversation limits (30 messages/30 seconds)
- Error codes and handling

**Data Enrichment (ZoomInfo, Clearbit, Hunter.io, Apollo.io):**
- Per-second and per-minute limits
- Daily quotas by plan
- Batch enrichment constraints
- Credit-based pricing models

**CRM (Salesforce):**
- 100,000+ daily requests (Enterprise)
- Concurrent request limits (25 max)
- Bulk API batch limits (15,000/day)
- Rolling 24-hour windows

**Platform Implementation:**
- Rate limit detection and monitoring
- Circuit breaker patterns
- Queue management
- Live Diagnostics panel integration
- Configuration file references

**Additional Resources:**
- Links to official API documentation for each service
- Best practices and recommended actions
- Monitoring and alerting guidelines

This documentation addresses the rate limit warning observed in Live Diagnostics and provides operational guidance for managing API quotas across all integrated services.

README.md

@@ -49,3 +49,165 @@ Example construction is provided in app.py showing default data structures and r
 ---
 (legacy platform and API docs retained below)
 
+---
+
+## API Rate Limits & Throttling
+
+### Overview
+
+This platform integrates with multiple external APIs for B2B outreach automation. Each service enforces rate limits to prevent abuse and ensure service stability. Understanding these limits is critical for:
+- **Preventing service disruptions** (429 errors, temporary blocks)
+- **Optimizing batch operations** (cadence scheduling, bulk enrichment)
+- **Compliance monitoring** (audit trail accuracy)
+- **Cost management** (avoiding overage charges)
+
+**Rate Limit Reset Timing:** Most APIs reset limits at **midnight UTC** daily, with some using rolling windows.
+
+---
+
+### LinkedIn API Rate Limits
+
+**Connection & Messaging Limits:**
+- **Connection Requests:** 100-200 per week (varies by account reputation)
+  - New accounts: ~50-75/week
+  - Established accounts: ~100/week  
+  - Trusted accounts (high SSI): up to 200/week
+- **Messages:** 150 per day (premium accounts)
+- **Profile Views:** 80/day (standard), up to 1,000/day (premium)
+
+**API Request Limits (Scale-Dependent):**
+- **1,000-5,000 members:** 7,500 requests/day, 1,500 requests/hour
+- **5,001-10,000 members:** 15,000 requests/day, 15,000 requests/hour
+- **10,001-20,000 members:** 30,000 requests/day, 30,000 requests/hour
+- **Rate limit errors:** HTTP 429 "Too Many Requests"
+- **Alert threshold:** Email notification at 75% of quota
+
+**Best Practices:**
+- Implement **exponential backoff** (15-30 minute delays) when hitting limits
+- Monitor `X-RateLimit-Remaining` response headers
+- Limits reset at midnight UTC daily
+
+---
+
+### Email API Rate Limits
+
+#### SendGrid
+- **API Rate Limit:** 600 requests/minute (varies by endpoint)
+- **Free Plan:** 100 emails/day
+- **Paid Plans:** Up to 1,500 emails/day, max 400 emails/hour
+- **Enterprise:** 1.5M emails/month with dedicated IP
+
+#### Mailgun
+- **API Rate Limit:** 300 requests/minute
+- **Free Plan:** 5,000 emails/month, 300 emails/day
+- **Paid Plans:** 50,000-100,000 emails/month (Foundation/Growth/Scale)
+- **Throttling:** Automatic rate limiting based on sender behavior
+
+---
+
+### Phone/SMS API Rate Limits (Twilio)
+
+- **Outbound Calls:** 1 call per second (CPS) per account
+- **SMS Messages:** 1 message per second per phone number
+- **Conversation Limit:** 30 outbound replies between two numbers in 30 seconds
+- **Error Code:** 14107 when SMS rate limit exceeded
+- **Webhook Limits:** Service-specific (see Twilio Verify documentation)
+
+**Important:** The 500th user in a batch will receive their call/SMS after ~500 seconds due to 1 CPS limit.
+
+---
+
+### Data Enrichment API Rate Limits
+
+#### ZoomInfo
+- **Standard APIs:** 25 requests/second (1,500 requests/minute)
+- **Scaling APIs:** 33 requests/second
+- **Daily Limits:**
+  - Pro Plan: ~1,000 API calls/day
+  - Enterprise Plan: up to 10,000 API calls/day
+- **Batch Enrichment:** 100,000 records max per batch
+- **Pricing:** Credit-based system (~$15,000/year for 5,000 credits)
+
+#### Clearbit (Breeze Intelligence)
+- **Rate Limits:** Not publicly specified (HubSpot integration)
+- **Batch Enrichment:** Limited to 100,000 records at once
+- **Pricing:** Credit-based, starts at $45-50/month (100 credits)
+- **Real-time Updates:** API-first approach for live data
+
+#### Hunter.io
+- **Domain Search & Email Finder:** 15 requests/second, 500 requests/minute
+- **Email Verifier:** 10 requests/second, 300 requests/minute
+- **Error Response:** HTTP 403 when limit exceeded
+- **Plans:**
+  - Free: Limited credits
+  - Growth: 10,000 credits/month
+  - Scale: 25,000 credits/month
+
+#### Apollo.io
+- **Free Plan:** 50 API calls/minute, 600 calls/day
+- **Paid Plans:** 200 API calls/minute, 2,000 calls/day
+- **Bulk Enrichment:** 1/10 of standard rate limit (but 10 inputs per call)
+- **Error:** HTTP 429 after exceeding limit
+
+---
+
+### CRM API Rate Limits (Salesforce)
+
+- **Daily Request Limit:** 100,000 base requests/24 hours (Enterprise Edition)
+  - Plus 1,000 additional requests per user license
+  - Example: 50 users = 150,000 daily requests
+- **Concurrent Requests:** Max 25 long-running requests (20+ seconds)
+  - Developer orgs: 5 concurrent requests
+- **API Timeout:** Hard 10-minute maximum per call
+- **Bulk API:** 15,000 batches/day, 10,000 records per batch
+- **Report API:** 1,200 async requests/hour
+- **Measurement Window:** Rolling 24-hour window (not calendar days)
+
+---
+
+### Platform Implementation
+
+**Our Rate Limit Handling Strategy:**
+
+1. **Detection:** Monitor response headers (`X-RateLimit-*`, HTTP 429 status)
+2. **Exponential Backoff:** 15-minute initial delay, doubling on repeated failures
+3. **Circuit Breaker:** Temporary pause (15-30 min) when threshold reached
+4. **Queue Management:** Batch operations respect per-service limits
+5. **Alerting:** Live Diagnostics panel logs rate limit events
+
+**Configuration Files:**
+- Rate limit configs: `/docs/configs/rate_limits.json`
+- Throttling logic: See `cadence_agent.py` backoff implementation
+- Monitoring: Live Diagnostics Panel tracks limit-related warnings
+
+**Example from Live Diagnostics:**
+```
+[2025-11-06T06:33:00Z] warning: Rate limit reached for LinkedIn API; 
+implementing exponential backoff for 15 minutes
+```
+
+---
+
+### Monitoring & Alerts
+
+**Dashboard Integration:**
+- **Live Diagnostics Panel:** Real-time rate limit warnings
+- **Audit Trail Export:** Historical rate limit incidents (CSV export)
+- **Compliance Tracking:** Flags batches affected by rate limiting
+
+**Recommended Actions:**
+- Review Live Diagnostics panel regularly for rate limit patterns
+- Adjust batch sizes and cadence timing based on observed limits
+- Consider upgrading API plans if consistently hitting free tier limits
+- Implement staggered scheduling to distribute load throughout the day
+
+---
+
+### Additional Resources
+
+- LinkedIn API Documentation: [Microsoft Learn - Rate Limits](https://learn.microsoft.com/en-us/linkedin/shared/api-guide/concepts/rate-limits)
+- Twilio Rate Limits: [Understanding Twilio Rate Limits](https://help.twilio.com/articles/115002943027)
+- Salesforce API Limits: [API Request Limits and Allocations](https://developer.salesforce.com/docs/atlas.en-us.salesforce_app_limits_cheatsheet.meta)
+- Hunter.io API: [Rate Limits Documentation](https://help.hunter.io/en/articles/1970956-hunter-api)
+- Apollo.io API: [View API Usage Stats](https://docs.apollo.io/reference/view-api-usage-stats)
+