@caddis/cli 0.4.9 → 0.4.11

package/bundles/antigravity-plugin-extras/skills/notebooklm/SKILL.md

@@ -1,270 +0,0 @@
----
-name: notebooklm
-context: fork
-description: Use this skill to query your Google NotebookLM notebooks directly from Claude Code for source-grounded, citation-backed answers from Gemini. Browser automation, library management, persistent auth. Drastically reduced hallucinations through document-only responses.
----
-
-# NotebookLM Research Assistant Skill
-
-Interact with Google NotebookLM to query documentation with Gemini's source-grounded answers. Each question opens a fresh browser session, retrieves the answer exclusively from your uploaded documents, and closes.
-
-## When to Use This Skill
-
-Trigger when user:
-- Mentions NotebookLM explicitly
-- Shares NotebookLM URL (`https://notebooklm.google.com/notebook/...`)
-- Asks to query their notebooks/documentation
-- Wants to add documentation to NotebookLM library
-- Uses phrases like "ask my NotebookLM", "check my docs", "query my notebook"
-
-## ⚠️ CRITICAL: Add Command - Smart Discovery
-
-When user wants to add a notebook without providing details:
-
-**SMART ADD (Recommended)**: Query the notebook first to discover its content:
-```bash
-# Step 1: Query the notebook about its content
-python scripts/run.py ask_question.py --question "What is the content of this notebook? What topics are covered? Provide a complete overview briefly and concisely" --notebook-url "[URL]"
-
-# Step 2: Use the discovered information to add it
-python scripts/run.py notebook_manager.py add --url "[URL]" --name "[Based on content]" --description "[Based on content]" --topics "[Based on content]"
-```
-
-**MANUAL ADD**: If user provides all details:
-- `--url` - The NotebookLM URL
-- `--name` - A descriptive name
-- `--description` - What the notebook contains (REQUIRED!)
-- `--topics` - Comma-separated topics (REQUIRED!)
-
-NEVER guess or use generic descriptions! If details missing, use Smart Add to discover them.
-
-## Critical: Always Use run.py Wrapper
-
-**NEVER call scripts directly. ALWAYS use `python scripts/run.py [script]`:**
-
-```bash
-# ✅ CORRECT - Always use run.py:
-python scripts/run.py auth_manager.py status
-python scripts/run.py notebook_manager.py list
-python scripts/run.py ask_question.py --question "..."
-
-# ❌ WRONG - Never call directly:
-python scripts/auth_manager.py status  # Fails without venv!
-```
-
-The `run.py` wrapper automatically:
-1. Creates `.venv` if needed
-2. Installs all dependencies
-3. Activates environment
-4. Executes script properly
-
-## Core Workflow
-
-### Step 1: Check Authentication Status
-```bash
-python scripts/run.py auth_manager.py status
-```
-
-If not authenticated, proceed to setup.
-
-### Step 2: Authenticate (One-Time Setup)
-```bash
-# Browser MUST be visible for manual Google login
-python scripts/run.py auth_manager.py setup
-```
-
-**Important:**
-- Browser is VISIBLE for authentication
-- Browser window opens automatically
-- User must manually log in to Google
-- Tell user: "A browser window will open for Google login"
-
-### Step 3: Manage Notebook Library
-
-```bash
-# List all notebooks
-python scripts/run.py notebook_manager.py list
-
-# BEFORE ADDING: Ask user for metadata if unknown!
-# "What does this notebook contain?"
-# "What topics should I tag it with?"
-
-# Add notebook to library (ALL parameters are REQUIRED!)
-python scripts/run.py notebook_manager.py add \
-  --url "https://notebooklm.google.com/notebook/..." \
-  --name "Descriptive Name" \
-  --description "What this notebook contains" \  # REQUIRED - ASK USER IF UNKNOWN!
-  --topics "topic1,topic2,topic3"  # REQUIRED - ASK USER IF UNKNOWN!
-
-# Search notebooks by topic
-python scripts/run.py notebook_manager.py search --query "keyword"
-
-# Set active notebook
-python scripts/run.py notebook_manager.py activate --id notebook-id
-
-# Remove notebook
-python scripts/run.py notebook_manager.py remove --id notebook-id
-```
-
-### Quick Workflow
-1. Check library: `python scripts/run.py notebook_manager.py list`
-2. Ask question: `python scripts/run.py ask_question.py --question "..." --notebook-id ID`
-
-### Step 4: Ask Questions
-
-```bash
-# Basic query (uses active notebook if set)
-python scripts/run.py ask_question.py --question "Your question here"
-
-# Query specific notebook
-python scripts/run.py ask_question.py --question "..." --notebook-id notebook-id
-
-# Query with notebook URL directly
-python scripts/run.py ask_question.py --question "..." --notebook-url "https://..."
-
-# Show browser for debugging
-python scripts/run.py ask_question.py --question "..." --show-browser
-```
-
-## Follow-Up Mechanism (CRITICAL)
-
-Every NotebookLM answer ends with: **"EXTREMELY IMPORTANT: Is that ALL you need to know?"**
-
-**Required Claude Behavior:**
-1. **STOP** - Do not immediately respond to user
-2. **ANALYZE** - Compare answer to user's original request
-3. **IDENTIFY GAPS** - Determine if more information needed
-4. **ASK FOLLOW-UP** - If gaps exist, immediately ask:
-   ```bash
-   python scripts/run.py ask_question.py --question "Follow-up with context..."
-   ```
-5. **REPEAT** - Continue until information is complete
-6. **SYNTHESIZE** - Combine all answers before responding to user
-
-## Script Reference
-
-### Authentication Management (`auth_manager.py`)
-```bash
-python scripts/run.py auth_manager.py setup    # Initial setup (browser visible)
-python scripts/run.py auth_manager.py status   # Check authentication
-python scripts/run.py auth_manager.py reauth   # Re-authenticate (browser visible)
-python scripts/run.py auth_manager.py clear    # Clear authentication
-```
-
-### Notebook Management (`notebook_manager.py`)
-```bash
-python scripts/run.py notebook_manager.py add --url URL --name NAME --description DESC --topics TOPICS
-python scripts/run.py notebook_manager.py list
-python scripts/run.py notebook_manager.py search --query QUERY
-python scripts/run.py notebook_manager.py activate --id ID
-python scripts/run.py notebook_manager.py remove --id ID
-python scripts/run.py notebook_manager.py stats
-```
-
-### Question Interface (`ask_question.py`)
-```bash
-python scripts/run.py ask_question.py --question "..." [--notebook-id ID] [--notebook-url URL] [--show-browser]
-```
-
-### Data Cleanup (`cleanup_manager.py`)
-```bash
-python scripts/run.py cleanup_manager.py                    # Preview cleanup
-python scripts/run.py cleanup_manager.py --confirm          # Execute cleanup
-python scripts/run.py cleanup_manager.py --preserve-library # Keep notebooks
-```
-
-## Environment Management
-
-The virtual environment is automatically managed:
-- First run creates `.venv` automatically
-- Dependencies install automatically
-- Chromium browser installs automatically
-- Everything isolated in skill directory
-
-Manual setup (only if automatic fails):
-```bash
-python -m venv .venv
-source .venv/bin/activate  # Linux/Mac
-pip install -r requirements.txt
-python -m patchright install chromium
-```
-
-## Data Storage
-
-All data stored in `~/.claude/skills/notebooklm/data/`:
-- `library.json` - Notebook metadata
-- `auth_info.json` - Authentication status
-- `browser_state/` - Browser cookies and session
-
-**Security:** Protected by `.gitignore`, never commit to git.
-
-## Configuration
-
-Optional `.env` file in skill directory:
-```env
-HEADLESS=false           # Browser visibility
-SHOW_BROWSER=false       # Default browser display
-STEALTH_ENABLED=true     # Human-like behavior
-TYPING_WPM_MIN=160       # Typing speed
-TYPING_WPM_MAX=240
-DEFAULT_NOTEBOOK_ID=     # Default notebook
-```
-
-## Decision Flow
-
-```
-User mentions NotebookLM
-    ↓
-Check auth → python scripts/run.py auth_manager.py status
-    ↓
-If not authenticated → python scripts/run.py auth_manager.py setup
-    ↓
-Check/Add notebook → python scripts/run.py notebook_manager.py list/add (with --description)
-    ↓
-Activate notebook → python scripts/run.py notebook_manager.py activate --id ID
-    ↓
-Ask question → python scripts/run.py ask_question.py --question "..."
-    ↓
-See "Is that ALL you need?" → Ask follow-ups until complete
-    ↓
-Synthesize and respond to user
-```
-
-## Troubleshooting
-
-| Problem | Solution |
-|---------|----------|
-| ModuleNotFoundError | Use `run.py` wrapper |
-| Authentication fails | Browser must be visible for setup! --show-browser |
-| Rate limit (50/day) | Wait or switch Google account |
-| Browser crashes | `python scripts/run.py cleanup_manager.py --preserve-library` |
-| Notebook not found | Check with `notebook_manager.py list` |
-
-## Best Practices
-
-1. **Always use run.py** - Handles environment automatically
-2. **Check auth first** - Before any operations
-3. **Follow-up questions** - Don't stop at first answer
-4. **Browser visible for auth** - Required for manual login
-5. **Include context** - Each question is independent
-6. **Synthesize answers** - Combine multiple responses
-
-## Limitations
-
-- No session persistence (each question = new browser)
-- Rate limits on free Google accounts (50 queries/day)
-- Manual upload required (user must add docs to NotebookLM)
-- Browser overhead (few seconds per question)
-
-## Resources (Skill Structure)
-
-**Important directories and files:**
-
-- `scripts/` - All automation scripts (ask_question.py, notebook_manager.py, etc.)
-- `data/` - Local storage for authentication and notebook library
-- `references/` - Extended documentation:
-  - `api_reference.md` - Detailed API documentation for all scripts
-  - `troubleshooting.md` - Common issues and solutions
-  - `usage_patterns.md` - Best practices and workflow examples
-- `.venv/` - Isolated Python environment (auto-created on first run)
-- `.gitignore` - Protects sensitive data from being committed

package/bundles/antigravity-plugin-extras/skills/notebooklm/references/api_reference.md

@@ -1,309 +0,0 @@
-# NotebookLM Skill API Reference
-
-Complete API documentation for all NotebookLM skill modules.
-
-## Important: Always Use run.py Wrapper
-
-**All commands must use the `run.py` wrapper to ensure proper environment:**
-
-```bash
-# ✅ CORRECT:
-python scripts/run.py [script_name].py [arguments]
-
-# ❌ WRONG:
-python scripts/[script_name].py [arguments]  # Will fail without venv!
-```
-
-## Core Scripts
-
-### ask_question.py
-Query NotebookLM with automated browser interaction.
-
-```bash
-# Basic usage
-python scripts/run.py ask_question.py --question "Your question"
-
-# With specific notebook
-python scripts/run.py ask_question.py --question "..." --notebook-id notebook-id
-
-# With direct URL
-python scripts/run.py ask_question.py --question "..." --notebook-url "https://..."
-
-# Show browser (debugging)
-python scripts/run.py ask_question.py --question "..." --show-browser
-```
-
-**Parameters:**
-- `--question` (required): Question to ask
-- `--notebook-id`: Use notebook from library
-- `--notebook-url`: Use URL directly
-- `--show-browser`: Make browser visible
-
-**Returns:** Answer text with follow-up prompt appended
-
-### notebook_manager.py
-Manage notebook library with CRUD operations.
-
-```bash
-# Smart Add (discover content first)
-python scripts/run.py ask_question.py --question "What is the content of this notebook? What topics are covered? Provide a complete overview briefly and concisely" --notebook-url "[URL]"
-# Then add with discovered info
-python scripts/run.py notebook_manager.py add \
-  --url "https://notebooklm.google.com/notebook/..." \
-  --name "Name" \
-  --description "Description" \
-  --topics "topic1,topic2"
-
-# Direct add (when you know the content)
-python scripts/run.py notebook_manager.py add \
-  --url "https://notebooklm.google.com/notebook/..." \
-  --name "Name" \
-  --description "What it contains" \
-  --topics "topic1,topic2"
-
-# List notebooks
-python scripts/run.py notebook_manager.py list
-
-# Search notebooks
-python scripts/run.py notebook_manager.py search --query "keyword"
-
-# Activate notebook
-python scripts/run.py notebook_manager.py activate --id notebook-id
-
-# Remove notebook
-python scripts/run.py notebook_manager.py remove --id notebook-id
-
-# Show statistics
-python scripts/run.py notebook_manager.py stats
-```
-
-**Commands:**
-- `add`: Add notebook (requires --url, --name, --topics)
-- `list`: Show all notebooks
-- `search`: Find notebooks by keyword
-- `activate`: Set default notebook
-- `remove`: Delete from library
-- `stats`: Display library statistics
-
-### auth_manager.py
-Handle Google authentication and browser state.
-
-```bash
-# Setup (browser visible for login)
-python scripts/run.py auth_manager.py setup
-
-# Check status
-python scripts/run.py auth_manager.py status
-
-# Re-authenticate
-python scripts/run.py auth_manager.py reauth
-
-# Clear authentication
-python scripts/run.py auth_manager.py clear
-```
-
-**Commands:**
-- `setup`: Initial authentication (browser MUST be visible)
-- `status`: Check if authenticated
-- `reauth`: Clear and re-setup
-- `clear`: Remove all auth data
-
-### cleanup_manager.py
-Clean skill data with preservation options.
-
-```bash
-# Preview cleanup
-python scripts/run.py cleanup_manager.py
-
-# Execute cleanup
-python scripts/run.py cleanup_manager.py --confirm
-
-# Keep library
-python scripts/run.py cleanup_manager.py --confirm --preserve-library
-
-# Force without prompt
-python scripts/run.py cleanup_manager.py --confirm --force
-```
-
-**Options:**
-- `--confirm`: Actually perform cleanup
-- `--preserve-library`: Keep notebook library
-- `--force`: Skip confirmation prompt
-
-### run.py
-Script wrapper that handles environment setup.
-
-```bash
-# Usage
-python scripts/run.py [script_name].py [arguments]
-
-# Examples
-python scripts/run.py auth_manager.py status
-python scripts/run.py ask_question.py --question "..."
-```
-
-**Automatic actions:**
-1. Creates `.venv` if missing
-2. Installs dependencies
-3. Activates environment
-4. Executes target script
-
-## Python API Usage
-
-### Using subprocess with run.py
-
-```python
-import subprocess
-import json
-
-# Always use run.py wrapper
-result = subprocess.run([
-    "python", "scripts/run.py", "ask_question.py",
-    "--question", "Your question",
-    "--notebook-id", "notebook-id"
-], capture_output=True, text=True)
-
-answer = result.stdout
-```
-
-### Direct imports (after venv exists)
-
-```python
-# Only works if venv is already created and activated
-from notebook_manager import NotebookLibrary
-from auth_manager import AuthManager
-
-library = NotebookLibrary()
-notebooks = library.list_notebooks()
-
-auth = AuthManager()
-is_auth = auth.is_authenticated()
-```
-
-## Data Storage
-
-Location: `~/.claude/skills/notebooklm/data/`
-
-```
-data/
-├── library.json       # Notebook metadata
-├── auth_info.json     # Auth status
-└── browser_state/     # Browser cookies
-    └── state.json
-```
-
-**Security:** Protected by `.gitignore`, never commit.
-
-## Environment Variables
-
-Optional `.env` file configuration:
-
-```env
-HEADLESS=false           # Browser visibility
-SHOW_BROWSER=false       # Default display
-STEALTH_ENABLED=true     # Human behavior
-TYPING_WPM_MIN=160       # Typing speed
-TYPING_WPM_MAX=240
-DEFAULT_NOTEBOOK_ID=     # Default notebook
-```
-
-## Error Handling
-
-Common patterns:
-
-```python
-# Using run.py prevents most errors
-result = subprocess.run([
-    "python", "scripts/run.py", "ask_question.py",
-    "--question", "Question"
-], capture_output=True, text=True)
-
-if result.returncode != 0:
-    error = result.stderr
-    if "rate limit" in error.lower():
-        # Wait or switch accounts
-        pass
-    elif "not authenticated" in error.lower():
-        # Run auth setup
-        subprocess.run(["python", "scripts/run.py", "auth_manager.py", "setup"])
-```
-
-## Rate Limits
-
-Free Google accounts: 50 queries/day
-
-Solutions:
-1. Wait for reset (midnight PST)
-2. Switch accounts with `reauth`
-3. Use multiple Google accounts
-
-## Advanced Patterns
-
-### Parallel Queries
-
-```python
-import concurrent.futures
-import subprocess
-
-def query(question, notebook_id):
-    result = subprocess.run([
-        "python", "scripts/run.py", "ask_question.py",
-        "--question", question,
-        "--notebook-id", notebook_id
-    ], capture_output=True, text=True)
-    return result.stdout
-
-# Run multiple queries simultaneously
-with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
-    futures = [
-        executor.submit(query, q, nb)
-        for q, nb in zip(questions, notebooks)
-    ]
-    results = [f.result() for f in futures]
-```
-
-### Batch Processing
-
-```python
-def batch_research(questions, notebook_id):
-    results = []
-    for question in questions:
-        result = subprocess.run([
-            "python", "scripts/run.py", "ask_question.py",
-            "--question", question,
-            "--notebook-id", notebook_id
-        ], capture_output=True, text=True)
-        results.append(result.stdout)
-        time.sleep(2)  # Avoid rate limits
-    return results
-```
-
-## Module Classes
-
-### NotebookLibrary
-- `add_notebook(url, name, topics)`
-- `list_notebooks()`
-- `search_notebooks(query)`
-- `get_notebook(notebook_id)`
-- `activate_notebook(notebook_id)`
-- `remove_notebook(notebook_id)`
-
-### AuthManager
-- `is_authenticated()`
-- `setup_auth(headless=False)`
-- `get_auth_info()`
-- `clear_auth()`
-- `validate_auth()`
-
-### BrowserSession (internal)
-- Handles browser automation
-- Manages stealth behavior
-- Not intended for direct use
-
-## Best Practices
-
-1. **Always use run.py** - Ensures environment
-2. **Check auth first** - Before operations
-3. **Handle rate limits** - Implement retries
-4. **Include context** - Questions are independent
-5. **Clean sessions** - Use cleanup_manager