docs: Add Bird CLI implementation plan

12-task implementation plan for integrating Bird CLI as free X/Twitter search alternative. Includes detection, interactive install, search dispatch, and main flow integration. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-03 10:53:03 -08:00
parent 950810be92
commit 8ae00ea214
1 changed files with 929 additions and 0 deletions
@@ -0,0 +1,929 @@
 # Bird CLI Integration Implementation Plan
 > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
 **Goal:** Add Bird CLI as a free, zero-config alternative to xAI for X/Twitter searches with interactive installation.
 **Architecture:** New `bird_x.py` module handles Bird detection, installation prompts, and search. Modified `env.py` determines X source priority (Bird → xAI → WebSearch). Main script prompts for Bird install if not found.
 **Tech Stack:** Python 3, subprocess for Bird CLI calls, existing lib modules for normalization/scoring.
 ---
 ### Task 1: Create bird_x.py - Detection Functions
 **Files:**
 - Create: `scripts/lib/bird_x.py`
 **Step 1: Create the module with detection functions**
 ```python
 """Bird CLI client for X (Twitter) search."""
 import json
 import shutil
 import subprocess
 import sys
 from datetime import datetime
 from typing import Any, Dict, List, Optional, Tuple
 def _log(msg: str):
    """Log to stderr."""
    sys.stderr.write(f"[Bird] {msg}\n")
    sys.stderr.flush()
 def is_bird_installed() -> bool:
    """Check if Bird CLI is installed."""
    return shutil.which("bird") is not None
 def is_bird_authenticated() -> Optional[str]:
    """Check if Bird is authenticated by running 'bird whoami'.
    Returns:
        Username if authenticated, None otherwise.
    """
    if not is_bird_installed():
        return None
    try:
        result = subprocess.run(
            ["bird", "whoami"],
            capture_output=True,
            text=True,
            timeout=10,
        )
        if result.returncode == 0 and result.stdout.strip():
            # Output is typically the username
            return result.stdout.strip().split('\n')[0]
        return None
    except (subprocess.TimeoutExpired, FileNotFoundError, Exception):
        return None
 def check_npm_available() -> bool:
    """Check if npm is available for installation."""
    return shutil.which("npm") is not None
 ```
 **Step 2: Verify the module loads**
 Run: `cd /Users/mvanhorn/last30days-skill-private && python3 -c "from scripts.lib import bird_x; print('OK')"`
 Expected: `OK`
 **Step 3: Commit**
 ```bash
 git add scripts/lib/bird_x.py
 git commit -m "feat(bird): add detection functions for Bird CLI"
 ```
 ---
 ### Task 2: Add Bird Installation Functions
 **Files:**
 - Modify: `scripts/lib/bird_x.py`
 **Step 1: Add installation function**
 Add after `check_npm_available()`:
 ```python
 def install_bird() -> Tuple[bool, str]:
    """Install Bird CLI via npm.
    Returns:
        Tuple of (success, message).
    """
    if not check_npm_available():
        return False, "npm not found. Install Node.js first, or install Bird manually: https://github.com/steipete/bird"
    try:
        _log("Installing Bird CLI...")
        result = subprocess.run(
            ["npm", "install", "-g", "@steipete/bird"],
            capture_output=True,
            text=True,
            timeout=120,
        )
        if result.returncode == 0:
            return True, "Bird CLI installed successfully!"
        else:
            error = result.stderr.strip() or result.stdout.strip() or "Unknown error"
            return False, f"Installation failed: {error}"
    except subprocess.TimeoutExpired:
        return False, "Installation timed out"
    except Exception as e:
        return False, f"Installation error: {e}"
 def get_bird_status() -> Dict[str, Any]:
    """Get comprehensive Bird status.
    Returns:
        Dict with keys: installed, authenticated, username, can_install
    """
    installed = is_bird_installed()
    username = is_bird_authenticated() if installed else None
    return {
        "installed": installed,
        "authenticated": username is not None,
        "username": username,
        "can_install": check_npm_available(),
    }
 ```
 **Step 2: Verify functions work**
 Run: `cd /Users/mvanhorn/last30days-skill-private && python3 -c "from scripts.lib import bird_x; print(bird_x.get_bird_status())"`
 Expected: Dict with installed/authenticated status
 **Step 3: Commit**
 ```bash
 git add scripts/lib/bird_x.py
 git commit -m "feat(bird): add installation and status functions"
 ```
 ---
 ### Task 3: Add Bird Search Function
 **Files:**
 - Modify: `scripts/lib/bird_x.py`
 **Step 1: Add depth config and search function**
 Add after imports at top:
 ```python
 # Depth configurations: number of results to request
 DEPTH_CONFIG = {
    "quick": 12,
    "default": 30,
    "deep": 60,
 }
 ```
 Add after `get_bird_status()`:
 ```python
 def search_x(
    topic: str,
    from_date: str,
    to_date: str,
    depth: str = "default",
 ) -> Dict[str, Any]:
    """Search X using Bird CLI.
    Args:
        topic: Search topic
        from_date: Start date (YYYY-MM-DD)
        to_date: End date (YYYY-MM-DD)
        depth: Research depth - "quick", "default", or "deep"
    Returns:
        Raw Bird JSON response or error dict.
    """
    count = DEPTH_CONFIG.get(depth, DEPTH_CONFIG["default"])
    # Build command
    cmd = [
        "bird", "search",
        topic,
        "--since", from_date,
        "-n", str(count),
        "--json",
    ]
    # Adjust timeout based on depth
    timeout = 30 if depth == "quick" else 45 if depth == "default" else 60
    try:
        result = subprocess.run(
            cmd,
            capture_output=True,
            text=True,
            timeout=timeout,
        )
        if result.returncode != 0:
            error = result.stderr.strip() or "Bird search failed"
            return {"error": error, "items": []}
        # Parse JSON output
        output = result.stdout.strip()
        if not output:
            return {"items": []}
        return json.loads(output)
    except subprocess.TimeoutExpired:
        return {"error": "Search timed out", "items": []}
    except json.JSONDecodeError as e:
        return {"error": f"Invalid JSON response: {e}", "items": []}
    except Exception as e:
        return {"error": str(e), "items": []}
 ```
 **Step 2: Verify search function signature**
 Run: `cd /Users/mvanhorn/last30days-skill-private && python3 -c "from scripts.lib import bird_x; import inspect; print(inspect.signature(bird_x.search_x))"`
 Expected: `(topic: str, from_date: str, to_date: str, depth: str = 'default') -> Dict[str, Any]`
 **Step 3: Commit**
 ```bash
 git add scripts/lib/bird_x.py
 git commit -m "feat(bird): add search_x function"
 ```
 ---
 ### Task 4: Add Bird Response Parser
 **Files:**
 - Modify: `scripts/lib/bird_x.py`
 **Step 1: Add parse function**
 Add at end of file:
 ```python
 def parse_bird_response(response: Dict[str, Any]) -> List[Dict[str, Any]]:
    """Parse Bird response to match xai_x output format.
    Args:
        response: Raw Bird JSON response
    Returns:
        List of normalized item dicts matching xai_x.parse_x_response() format.
    """
    items = []
    # Check for errors
    if "error" in response and response["error"]:
        _log(f"Bird error: {response['error']}")
        return items
    # Bird returns a list of tweets directly or under a key
    raw_items = response if isinstance(response, list) else response.get("items", response.get("tweets", []))
    if not isinstance(raw_items, list):
        return items
    for i, tweet in enumerate(raw_items):
        if not isinstance(tweet, dict):
            continue
        # Extract URL - Bird uses permanent_url or we construct from id
        url = tweet.get("permanent_url") or tweet.get("url", "")
        if not url and tweet.get("id"):
            screen_name = tweet.get("user", {}).get("screen_name", "")
            if screen_name:
                url = f"https://x.com/{screen_name}/status/{tweet['id']}"
        if not url:
            continue
        # Parse date from created_at (e.g., "Wed Jan 15 14:30:00 +0000 2026")
        date = None
        created_at = tweet.get("created_at", "")
        if created_at:
            try:
                # Try ISO format first
                if "T" in created_at:
                    dt = datetime.fromisoformat(created_at.replace("Z", "+00:00"))
                else:
                    # Twitter format: "Wed Jan 15 14:30:00 +0000 2026"
                    dt = datetime.strptime(created_at, "%a %b %d %H:%M:%S %z %Y")
                date = dt.strftime("%Y-%m-%d")
            except (ValueError, TypeError):
                pass
        # Extract user info
        user = tweet.get("user", {})
        author_handle = user.get("screen_name", "") or tweet.get("author_handle", "")
        # Build engagement dict
        engagement = {
            "likes": tweet.get("like_count") or tweet.get("favorite_count"),
            "reposts": tweet.get("retweet_count"),
            "replies": tweet.get("reply_count"),
            "quotes": tweet.get("quote_count"),
        }
        # Convert to int where possible
        for key in engagement:
            if engagement[key] is not None:
                try:
                    engagement[key] = int(engagement[key])
                except (ValueError, TypeError):
                    engagement[key] = None
        # Build normalized item
        item = {
            "id": f"X{i+1}",
            "text": str(tweet.get("text", tweet.get("full_text", ""))).strip()[:500],
            "url": url,
            "author_handle": author_handle.lstrip("@"),
            "date": date,
            "engagement": engagement if any(v is not None for v in engagement.values()) else None,
            "why_relevant": "",  # Bird doesn't provide relevance explanations
            "relevance": 0.7,  # Default relevance, let score.py re-rank
        }
        items.append(item)
    return items
 ```
 **Step 2: Verify parser handles empty input**
 Run: `cd /Users/mvanhorn/last30days-skill-private && python3 -c "from scripts.lib import bird_x; print(bird_x.parse_bird_response({}))"`
 Expected: `[]`
 **Step 3: Commit**
 ```bash
 git add scripts/lib/bird_x.py
 git commit -m "feat(bird): add response parser matching xai_x format"
 ```
 ---
 ### Task 5: Add UI Functions for Bird Prompts
 **Files:**
 - Modify: `scripts/lib/ui.py`
 **Step 1: Add Bird-related messages and prompts**
 Add after `PROMO_SINGLE_KEY_PLAIN` dict (around line 128):
 ```python
 # Bird CLI prompts
 BIRD_INSTALL_PROMPT = f"""
 {Colors.CYAN}{Colors.BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━{Colors.RESET}
 {Colors.CYAN}🐦 FREE X/TWITTER SEARCH AVAILABLE{Colors.RESET}
 Bird CLI provides free X search using your browser session (no API key needed).
 """
 BIRD_INSTALL_PROMPT_PLAIN = """
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 🐦 FREE X/TWITTER SEARCH AVAILABLE
 Bird CLI provides free X search using your browser session (no API key needed).
 """
 BIRD_AUTH_HELP = f"""
 {Colors.YELLOW}Bird authentication failed.{Colors.RESET}
 To fix this:
 1. Log into X (twitter.com) in Safari, Chrome, or Firefox
 2. Run: {Colors.BOLD}bird check{Colors.RESET} to verify credentials
 3. Try again
 For manual setup, see: https://github.com/steipete/bird#authentication
 """
 BIRD_AUTH_HELP_PLAIN = """
 Bird authentication failed.
 To fix this:
 1. Log into X (twitter.com) in Safari, Chrome, or Firefox
 2. Run: bird check to verify credentials
 3. Try again
 For manual setup, see: https://github.com/steipete/bird#authentication
 """
 ```
 **Step 2: Add prompt functions to ProgressDisplay class**
 Add these methods to the `ProgressDisplay` class (after `show_promo` method, around line 310):
 ```python
    def prompt_bird_install(self) -> bool:
        """Prompt user to install Bird CLI.
        Returns:
            True if user wants to install, False otherwise.
        """
        if IS_TTY:
            sys.stderr.write(BIRD_INSTALL_PROMPT)
        else:
            sys.stderr.write(BIRD_INSTALL_PROMPT_PLAIN)
        sys.stderr.flush()
        try:
            response = input("Install Bird CLI now? (y/n): ").strip().lower()
            return response in ('y', 'yes')
        except (EOFError, KeyboardInterrupt):
            return False
    def show_bird_install_success(self, username: str):
        """Show Bird installation success message."""
        msg = f"{Colors.GREEN}✓ Bird installed and authenticated as @{username}{Colors.RESET}\n" if IS_TTY else f"✓ Bird installed and authenticated as @{username}\n"
        sys.stderr.write(msg)
        sys.stderr.flush()
    def show_bird_install_failed(self, error: str):
        """Show Bird installation failure message."""
        msg = f"{Colors.RED}✗ Bird installation failed: {error}{Colors.RESET}\n" if IS_TTY else f"✗ Bird installation failed: {error}\n"
        sys.stderr.write(msg)
        sys.stderr.flush()
    def show_bird_auth_help(self):
        """Show Bird authentication help."""
        if IS_TTY:
            sys.stderr.write(BIRD_AUTH_HELP)
        else:
            sys.stderr.write(BIRD_AUTH_HELP_PLAIN)
        sys.stderr.flush()
 ```
 **Step 3: Verify new methods exist**
 Run: `cd /Users/mvanhorn/last30days-skill-private && python3 -c "from scripts.lib.ui import ProgressDisplay; p = ProgressDisplay('test', show_banner=False); print(hasattr(p, 'prompt_bird_install'))"`
 Expected: `True`
 **Step 4: Commit**
 ```bash
 git add scripts/lib/ui.py
 git commit -m "feat(ui): add Bird CLI install prompts and auth help"
 ```
 ---
 ### Task 6: Update env.py with X Source Detection
 **Files:**
 - Modify: `scripts/lib/env.py`
 **Step 1: Add get_x_source function**
 Add at end of file:
 ```python
 def get_x_source(config: Dict[str, Any]) -> Optional[str]:
    """Determine the best available X/Twitter source.
    Priority: Bird (free) → xAI (paid API)
    Args:
        config: Configuration dict from get_config()
    Returns:
        'bird' if Bird is installed and authenticated,
        'xai' if XAI_API_KEY is configured,
        None if no X source available.
    """
    # Import here to avoid circular dependency
    from . import bird_x
    # Check Bird first (free option)
    if bird_x.is_bird_installed():
        username = bird_x.is_bird_authenticated()
        if username:
            return 'bird'
    # Fall back to xAI if key exists
    if config.get('XAI_API_KEY'):
        return 'xai'
    return None
 def get_x_source_status(config: Dict[str, Any]) -> Dict[str, Any]:
    """Get detailed X source status for UI decisions.
    Returns:
        Dict with keys: source, bird_installed, bird_authenticated,
        bird_username, xai_available, can_install_bird
    """
    from . import bird_x
    bird_status = bird_x.get_bird_status()
    xai_available = bool(config.get('XAI_API_KEY'))
    # Determine active source
    if bird_status["authenticated"]:
        source = 'bird'
    elif xai_available:
        source = 'xai'
    else:
        source = None
    return {
        "source": source,
        "bird_installed": bird_status["installed"],
        "bird_authenticated": bird_status["authenticated"],
        "bird_username": bird_status["username"],
        "xai_available": xai_available,
        "can_install_bird": bird_status["can_install"],
    }
 ```
 **Step 2: Verify function works**
 Run: `cd /Users/mvanhorn/last30days-skill-private && python3 -c "from scripts.lib import env; print(env.get_x_source_status(env.get_config()))"`
 Expected: Dict with source status
 **Step 3: Commit**
 ```bash
 git add scripts/lib/env.py
 git commit -m "feat(env): add X source detection with Bird priority"
 ```
 ---
 ### Task 7: Update __init__.py to Export bird_x
 **Files:**
 - Modify: `scripts/lib/__init__.py`
 **Step 1: Add bird_x to imports**
 Replace file contents with:
 ```python
 # last30days library modules
 from . import bird_x
 ```
 **Step 2: Verify import works**
 Run: `cd /Users/mvanhorn/last30days-skill-private && python3 -c "from scripts.lib import bird_x; print('OK')"`
 Expected: `OK`
 **Step 3: Commit**
 ```bash
 git add scripts/lib/__init__.py
 git commit -m "feat(lib): export bird_x module"
 ```
 ---
 ### Task 8: Integrate Bird into Main Script - Part 1 (Setup Phase)
 **Files:**
 - Modify: `scripts/last30days.py`
 **Step 1: Add bird_x import**
 Add `bird_x` to the imports from lib (around line 36):
 ```python
 from lib import (
    bird_x,
    dates,
    dedupe,
    env,
    http,
    models,
    normalize,
    openai_reddit,
    reddit_enrich,
    render,
    schema,
    score,
    ui,
    websearch,
    xai_x,
 )
 ```
 **Step 2: Add Bird setup function**
 Add after the imports, before `load_fixture`:
 ```python
 def setup_bird_if_needed(progress: ui.ProgressDisplay) -> Optional[str]:
    """Check Bird status and offer installation if needed.
    Returns:
        'bird' if Bird is ready to use,
        'declined' if user declined install,
        None if Bird not available and couldn't be installed.
    """
    status = bird_x.get_bird_status()
    # Already working
    if status["authenticated"]:
        return 'bird'
    # Installed but not authenticated
    if status["installed"]:
        progress.show_bird_auth_help()
        return None
    # Not installed - offer to install if npm available
    if status["can_install"]:
        if progress.prompt_bird_install():
            success, message = bird_x.install_bird()
            if success:
                # Check if auth works now
                username = bird_x.is_bird_authenticated()
                if username:
                    progress.show_bird_install_success(username)
                    return 'bird'
                else:
                    progress.show_bird_auth_help()
                    return None
            else:
                progress.show_bird_install_failed(message)
                return None
        else:
            return 'declined'
    return None
 ```
 **Step 3: Verify script still loads**
 Run: `cd /Users/mvanhorn/last30days-skill-private && python3 -c "import scripts.last30days; print('OK')"`
 Expected: `OK`
 **Step 4: Commit**
 ```bash
 git add scripts/last30days.py
 git commit -m "feat(main): add Bird setup function"
 ```
 ---
 ### Task 9: Integrate Bird into Main Script - Part 2 (Search Dispatch)
 **Files:**
 - Modify: `scripts/last30days.py`
 **Step 1: Modify _search_x function to support Bird**
 Replace the `_search_x` function (around line 119-159) with:
 ```python
 def _search_x(
    topic: str,
    config: dict,
    selected_models: dict,
    from_date: str,
    to_date: str,
    depth: str,
    mock: bool,
    x_source: str = "xai",
 ) -> tuple:
    """Search X via Bird CLI or xAI (runs in thread).
    Args:
        x_source: 'bird' or 'xai' - which backend to use
    Returns:
        Tuple of (x_items, raw_response, error)
    """
    raw_response = None
    x_error = None
    if mock:
        raw_response = load_fixture("xai_sample.json")
        x_items = xai_x.parse_x_response(raw_response or {})
        return x_items, raw_response, x_error
    # Use Bird if specified
    if x_source == "bird":
        try:
            raw_response = bird_x.search_x(
                topic,
                from_date,
                to_date,
                depth=depth,
            )
        except Exception as e:
            raw_response = {"error": str(e)}
            x_error = f"{type(e).__name__}: {e}"
        x_items = bird_x.parse_bird_response(raw_response or {})
        # Check for error in response
        if raw_response and raw_response.get("error") and not x_error:
            x_error = raw_response["error"]
        return x_items, raw_response, x_error
    # Use xAI (original behavior)
    try:
        raw_response = xai_x.search_x(
            config["XAI_API_KEY"],
            selected_models["xai"],
            topic,
            from_date,
            to_date,
            depth=depth,
        )
    except http.HTTPError as e:
        raw_response = {"error": str(e)}
        x_error = f"API error: {e}"
    except Exception as e:
        raw_response = {"error": str(e)}
        x_error = f"{type(e).__name__}: {e}"
    x_items = xai_x.parse_x_response(raw_response or {})
    return x_items, raw_response, x_error
 ```
 **Step 2: Update run_research to accept x_source parameter**
 Find the `run_research` function signature (around line 161) and add `x_source` parameter:
 ```python
 def run_research(
    topic: str,
    sources: str,
    config: dict,
    selected_models: dict,
    from_date: str,
    to_date: str,
    depth: str = "default",
    mock: bool = False,
    progress: ui.ProgressDisplay = None,
    x_source: str = "xai",
 ) -> tuple:
 ```
 Then update the `_search_x` call inside (around line 218-222) to pass `x_source`:
 ```python
            x_future = executor.submit(
                _search_x, topic, config, selected_models,
                from_date, to_date, depth, mock, x_source
            )
 ```
 **Step 3: Verify script syntax is valid**
 Run: `cd /Users/mvanhorn/last30days-skill-private && python3 -m py_compile scripts/last30days.py && echo "OK"`
 Expected: `OK`
 **Step 4: Commit**
 ```bash
 git add scripts/last30days.py
 git commit -m "feat(main): dispatch X search to Bird or xAI"
 ```
 ---
 ### Task 10: Integrate Bird into Main Script - Part 3 (Main Function)
 **Files:**
 - Modify: `scripts/last30days.py`
 **Step 1: Update main() to check Bird before research**
 In the `main()` function, after loading config and before checking available sources (around line 345-355), add Bird setup:
 Find this section:
 ```python
    # Load config
    config = env.get_config()
    # Check available sources
    available = env.get_available_sources(config)
 ```
 Replace with:
 ```python
    # Load config
    config = env.get_config()
    # Initialize progress display early for Bird prompts
    progress = ui.ProgressDisplay(args.topic, show_banner=True)
    # Check Bird availability and offer install if needed
    x_source_status = env.get_x_source_status(config)
    x_source = x_source_status["source"]
    # If no X source and Bird can be installed, offer it
    if x_source is None and x_source_status["can_install_bird"]:
        bird_result = setup_bird_if_needed(progress)
        if bird_result == 'bird':
            x_source = 'bird'
            # Refresh status
            x_source_status = env.get_x_source_status(config)
    # Check available sources (now accounting for Bird)
    available = env.get_available_sources(config)
    # Override available if Bird is ready
    if x_source == 'bird':
        if available == 'reddit':
            available = 'both'  # Now have both Reddit + X (via Bird)
        elif available == 'web':
            available = 'x'  # Now have X via Bird
 ```
 **Step 2: Remove duplicate progress initialization**
 Find and remove the later `progress = ui.ProgressDisplay(...)` line (around line 371) since we now create it earlier.
 **Step 3: Pass x_source to run_research**
 Find the `run_research` call (around line 413) and add `x_source` parameter:
 ```python
    reddit_items, x_items, web_needed, raw_openai, raw_xai, raw_reddit_enriched, reddit_error, x_error = run_research(
        args.topic,
        sources,
        config,
        selected_models,
        from_date,
        to_date,
        depth,
        args.mock,
        progress,
        x_source=x_source or "xai",
    )
 ```
 **Step 4: Verify script runs with --help**
 Run: `cd /Users/mvanhorn/last30days-skill-private && python3 scripts/last30days.py --help`
 Expected: Help text displays without errors
 **Step 5: Commit**
 ```bash
 git add scripts/last30days.py
 git commit -m "feat(main): integrate Bird setup into main flow"
 ```
 ---
 ### Task 11: Test End-to-End with Mock Mode
 **Files:**
 - None (testing only)
 **Step 1: Test mock mode still works**
 Run: `cd /Users/mvanhorn/last30days-skill-private && python3 scripts/last30days.py "Claude Code" --mock --emit=compact 2>&1 | head -20`
 Expected: Output showing research results without errors
 **Step 2: Test Bird detection (informational)**
 Run: `cd /Users/mvanhorn/last30days-skill-private && python3 -c "from scripts.lib import env; import json; print(json.dumps(env.get_x_source_status(env.get_config()), indent=2))"`
 Expected: JSON showing current Bird/xAI status
 **Step 3: Commit any fixes if needed, then final commit**
 ```bash
 git add -A
 git commit -m "feat(bird): complete Bird CLI integration
 - Add bird_x.py module for Bird CLI detection, install, and search
 - Add UI prompts for interactive Bird installation
 - Update env.py with X source priority (Bird > xAI)
 - Integrate Bird into main research flow
 - Bird uses browser cookies (free, no API key needed)"
 ```
 ---
 ### Task 12: Push to Private Repo
 **Files:**
 - None (git only)
 **Step 1: Push all changes**
 Run: `cd /Users/mvanhorn/last30days-skill-private && git push origin main`
 Expected: Changes pushed to private repo
 **Step 2: Verify commit history**
 Run: `cd /Users/mvanhorn/last30days-skill-private && git log --oneline -10`
 Expected: Shows Bird integration commits
 ---
 ## Summary
 After completing all tasks, the skill will:
 1. Check if Bird CLI is installed on startup
 2. If not installed but npm available, prompt user to install
 3. If installed, verify authentication via `bird whoami`
 4. If authenticated, use Bird for all X searches (free)
 5. If not, fall back to xAI (if key exists) or WebSearch
 6. Output format identical regardless of backend used