@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/skill-deep-dives/bird.md

@@ -0,0 +1,357 @@
+# Skill Deep-Dive: bird
+
+**Skill**: `bird`
+**Category**: Free Skill (Cookie-Based)
+**Setup Difficulty**: 🟢 Easy
+**Time Estimate**: ~2 minutes
+**Platform**: Cross-platform (macOS, Windows, Linux)
+
+---
+
+## What It Enables
+
+| Capability | Description | Example |
+|------------|-------------|---------|
+| Read X/Twitter feed | View your timeline without opening browser | `bird timeline` |
+| Read tweets | View specific tweets and threads | `bird read <url>` |
+| Search X | Search tweets by keyword | `bird search "AI agents"` |
+| View threads | See full conversation threads | `bird thread <url>` |
+| Post tweets | Tweet from CLI | `bird tweet "Hello world"` |
+| Reply to tweets | Reply to conversations | `bird reply <url> "Great point!"` |
+| User info | View profile information | `bird whoami` |
+| Bookmarks | Access your bookmarks | Cookie-based |
+
+---
+
+## Dependencies
+
+### Hard Dependencies (Required)
+- [ ] `brew` or equivalent package manager — For installing bird
+- [ ] X/Twitter account — Free account works
+- [ ] Chrome or Firefox — For cookie extraction
+
+### Soft Dependencies (Recommended)
+- [ ] `SWEETISTICS_API_KEY` — Optional alternative to cookies
+
+### This Skill Enables
+- [ ] `comms` — Can provide X/Twitter data to unified layer
+- [ ] Social media intelligence — Track conversations, mentions
+
+---
+
+## Installation
+
+### Prerequisites Check
+
+```bash
+# Check for brew (macOS)
+which brew && echo "✅ Homebrew available"
+
+# Check if Chrome is installed (for cookie auth)
+ls -la /Applications/Google\ Chrome.app && echo "✅ Chrome found"
+# OR Firefox
+ls -la /Applications/Firefox.app && echo "✅ Firefox found"
+```
+
+### Installation Steps
+
+```bash
+# Install via Homebrew
+brew install steipete/tap/bird
+
+# Verify installation
+bird --version
+```
+
+### Verification
+
+```bash
+# Check bird is accessible
+bird --version
+```
+
+---
+
+## Configuration
+
+### Authentication: Option 1 - Cookie-Based (FREE, Recommended)
+
+This method uses your existing Chrome/Firefox cookies - no API key needed!
+
+```bash
+# Check if bird can access cookies
+bird check
+
+# Expected output: Shows which auth sources are available
+# - Chrome cookies: ✅ (if logged into X in Chrome)
+# - Firefox cookies: ✅ (if logged into X in Firefox)
+# - Sweetistics: ❌ (if not configured)
+
+# Test authentication
+bird whoami
+# Should show your X username
+
+# Read a tweet
+bird read https://x.com/username/status/1234567890
+```
+
+**That's it!** If you're logged into X in Chrome or Firefox, bird works immediately.
+
+### Authentication: Option 2 - Sweetistics API (Paid)
+
+If cookie access doesn't work or you prefer API-based access:
+
+```bash
+# Get Sweetistics API key from sweetistics.com
+# Then set environment variable
+export SWEETISTICS_API_KEY="your-api-key"
+
+# Or add to shell profile
+echo 'export SWEETISTICS_API_KEY="your-api-key"' >> ~/.zshrc
+source ~/.zshrc
+
+# Test
+bird --engine sweetistics whoami
+```
+
+### Test Basic Commands
+
+```bash
+# View your info
+bird whoami
+
+# Read a tweet (try a popular one)
+bird read https://x.com/elonmusk/status/...
+
+# Search tweets
+bird search "AI agents" -n 5
+
+# View your timeline
+bird timeline -n 10
+```
+
+---
+
+## User Actions Required
+
+1. **Be logged into X in Chrome/Firefox**: Open browser, go to x.com, sign in
+2. **(Optional) Get Sweetistics API key**: Visit sweetistics.com if cookie method doesn't work
+
+---
+
+## Common Failure Points
+
+### Failure: "No authentication sources available"
+
+**Symptom**: `bird check` shows all auth sources as ❌
+
+**Cause**: Not logged into X in Chrome/Firefox, and no Sweetistics key set
+
+**Recovery**:
+```bash
+# Option 1: Login to X in browser
+# 1. Open Chrome or Firefox
+# 2. Go to x.com
+# 3. Sign in
+# 4. Try again: bird check
+
+# Option 2: Use Sweetistics
+export SWEETISTICS_API_KEY="your-key"
+bird --engine sweetistics check
+```
+
+**Prevention**: Stay logged into X in your default browser
+
+---
+
+### Failure: "Cookie expired"
+
+**Symptom**: `bird` commands fail with authentication errors
+
+**Cause**: X session cookie expired in browser
+
+**Recovery**:
+```bash
+# Re-login to X in browser
+# 1. Open Chrome/Firefox
+# 2. Go to x.com
+# 3. Logout and login again
+# 4. Try again: bird whoami
+```
+
+**Prevention**: Periodically refresh X session in browser
+
+---
+
+### Failure: Rate limiting
+
+**Symptom**: Commands fail with "rate limit exceeded"
+
+**Cause**: Too many requests in short time (X rate limits)
+
+**Recovery**:
+```bash
+# Wait 15 minutes
+# Or use --delay flag for spacing requests
+bird search "query" --delay 2000  # 2 second delay between requests
+```
+
+**Prevention**: Add delays between bulk operations
+
+---
+
+## Automation Opportunities
+
+| Step | Automatable? | Tool | Notes |
+|------|--------------|------|-------|
+| Install bird | ✅ Yes | bash | `brew install steipete/tap/bird` |
+| Cookie auth | ✅ Yes | bash | Auto-detects if logged in |
+| Read tweets | ✅ Yes | bash | `bird read <url>` |
+| Search | ✅ Yes | bash | `bird search <query>` |
+| Post tweets | ✅ Yes | bash | `bird tweet <text>` (confirm first!) |
+| Monitor mentions | ✅ Yes | cron | Schedule `bird search "@yourusername"` |
+
+### Automation Script
+
+```bash
+#!/bin/bash
+# Monitor mentions and keywords
+
+KEYWORDS="nexus AI agents"
+
+echo "Checking X for mentions of: $KEYWORDS"
+
+bird search "$KEYWORDS" -n 10 --json | \
+  jq -r '.[] | "[@\(.author.username)] \(.text)"'
+```
+
+---
+
+## Wow Moments
+
+| Moment | What Happens | When to Demo |
+|--------|--------------|--------------|
+| Zero setup | Works immediately if logged into X | Right after install |
+| Read feed | Show timeline without opening browser | Morning briefing |
+| Search tweets | Find recent conversations on topic | Research use case |
+| Thread view | Show full conversation tree | Understanding discourse |
+| Post from CLI | Tweet without opening browser | Quick announcements |
+
+### Demo Script
+
+```
+Agent: "Bird is one of the easiest skills to setup - it uses your existing Chrome login. Watch:"
+
+bird check
+
+Agent: "See? Already authenticated! Let me search for recent AI discussions:"
+
+bird search "AI agents" -n 5
+
+Agent: "I can read specific tweets and show you full threads:"
+
+bird read <popular-tweet-url>
+bird thread <popular-tweet-url>
+
+Agent: "And if you want, I can post tweets on your behalf (with your permission):"
+
+[User: "Tweet 'Hello from bird CLI!'"]
+
+bird tweet "Hello from bird CLI!"
+
+Agent: "✅ Posted! This means I can monitor X, search for mentions, and even respond - all without opening a browser."
+```
+
+---
+
+## Integration with Other Skills
+
+| Skill | Integration | Notes |
+|-------|-------------|-------|
+| **comms** | Provides X/Twitter data | Optional data source |
+| **cron** | Schedule searches/monitoring | Track keywords automatically |
+| **qmd** | Index tweets | Semantic search across saved tweets |
+
+---
+
+## Testing Checklist
+
+- [ ] Fresh install: `brew install steipete/tap/bird`
+- [ ] Version check: `bird --version`
+- [ ] Auth check: `bird check` (shows cookie auth available)
+- [ ] Whoami works: `bird whoami`
+- [ ] Read tweet: `bird read <tweet-url>`
+- [ ] Search works: `bird search "test query" -n 5`
+- [ ] Thread view: `bird thread <tweet-url>`
+- [ ] Timeline: `bird timeline -n 10`
+- [ ] Post tweet (optional): `bird tweet "Test from bird"`
+
+---
+
+## Notes for Onboarding Agent
+
+- **Easiest skill**: Setup is literally just `brew install` if user is logged into X
+- **FREE**: No API key needed (unless using Sweetistics)
+- **Wow factor**: Works immediately - great for onboarding demos
+- **When NOT to recommend**: User doesn't use X/Twitter
+- **Value proposition**: "Read and post to X from terminal, no API key needed"
+- **Time estimate**: 2 minutes (install + verify)
+- **Perfect for beginners**: No manual steps, no permissions, no config files
+
+---
+
+## Common Commands Reference
+
+```bash
+# Reading
+bird whoami                             # Your profile
+bird read <tweet-url>                   # Read specific tweet
+bird thread <tweet-url>                 # View full thread
+bird timeline -n 20                     # Your timeline (20 tweets)
+bird search "query" -n 10               # Search tweets
+
+# Posting (ALWAYS confirm with user first!)
+bird tweet "text"                       # Post tweet
+bird reply <tweet-url> "text"           # Reply to tweet
+
+# Authentication
+bird check                              # Check auth sources
+bird --engine sweetistics <command>     # Use Sweetistics API
+
+# Output formats
+bird search "query" --json              # JSON output
+bird timeline -n 5 | jq                 # Pretty JSON with jq
+```
+
+---
+
+## Cookie vs Sweetistics
+
+| Feature | Cookie-Based | Sweetistics API |
+|---------|--------------|-----------------|
+| **Cost** | FREE | Paid subscription |
+| **Setup** | Automatic | Requires API key |
+| **Reliability** | Depends on browser session | More stable |
+| **Rate limits** | X's normal limits | May have different limits |
+| **When to use** | Default for personal use | Production/automation |
+
+---
+
+## Security Considerations
+
+- **Cookie access**: bird reads browser cookies (doesn't store passwords)
+- **Temporary**: If cookies expire, just login again
+- **Revocable**: Logout from X in browser to revoke access
+- **No persistence**: bird doesn't store credentials, re-reads cookies each time
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-01-12 | Initial deep-dive created |
+
+---
+
+*Template version: 1.0*