opencodekit 0.15.18 → 0.15.20

package/dist/template/.opencode/skills/notebooklm/references/setup.md

@@ -0,0 +1,353 @@
+# NotebookLM Skill Setup Guide
+
+Complete setup instructions for the NotebookLM skill integration.
+
+## Prerequisites
+
+### 1. Python 3.10+
+
+Check if Python is installed:
+
+```bash
+python --version
+# or
+python3 --version
+```
+
+**Install if missing:**
+
+**macOS (using Homebrew):**
+
+```bash
+brew install python@3.11
+```
+
+**Ubuntu/Debian:**
+
+```bash
+sudo apt update
+sudo apt install python3 python3-pip python3-venv
+```
+
+**Windows:**
+Download from [python.org](https://python.org) and install with "Add to PATH" checked.
+
+### 2. Google Chrome
+
+Check if Chrome is installed:
+
+**macOS:**
+
+```bash
+ls /Applications/Google\ Chrome.app
+```
+
+**Linux:**
+
+```bash
+which google-chrome
+```
+
+**Windows:**
+Check Start Menu for Google Chrome.
+
+**Install if missing:**
+Download from [google.com/chrome](https://google.com/chrome)
+
+### 3. NotebookLM Account
+
+1. Visit [notebooklm.google.com](https://notebooklm.google.com)
+2. Sign in with Google account
+3. Upload documents to create notebooks
+
+## First-Time Setup
+
+### Step 1: Verify Tool Installation
+
+The tool auto-installs the Python skill on first use. Verify it's working:
+
+```typescript
+const setup = await notebooklm({ operation: "setup" });
+console.log(setup.output);
+```
+
+Expected output:
+
+```
+📦 NotebookLM skill not found. Installing...
+   Cloning from https://github.com/PleasePrompto/notebooklm-skill...
+   ✓ Skill installed successfully
+   📍 Location: ~/.opencode/skills/notebooklm
+```
+
+### Step 2: Authenticate with Google
+
+**CRITICAL:** Browser must be visible for manual login.
+
+```typescript
+await notebooklm({
+  operation: "auth",
+  subOperation: "setup",
+  showBrowser: true,
+});
+```
+
+**What happens:**
+
+1. Browser window opens automatically
+2. Navigate to notebooklm.google.com
+3. **You must manually log in** to your Google account
+4. Authentication state is saved for future use
+
+**Authentication lasts:** ~7 days (then requires re-auth)
+
+### Step 3: Verify Authentication
+
+```typescript
+const status = await notebooklm({
+  operation: "auth",
+  subOperation: "status",
+});
+
+console.log(status.output);
+```
+
+Expected output:
+
+```
+🔐 Authentication Status:
+  Authenticated: Yes
+  State age: 0.5 hours
+  Last auth: 2025-01-30 14:32:15
+```
+
+## Adding Notebooks
+
+### Method 1: Smart Discovery (Recommended)
+
+If you don't know the notebook content:
+
+```typescript
+// Step 1: Query to discover content
+const discovery = await notebooklm({
+  operation: "query",
+  question:
+    "What is the content of this notebook? What topics are covered? Provide a complete overview briefly and concisely",
+  notebookUrl: "https://notebooklm.google.com/notebook/abc123...",
+});
+
+// Step 2: Add with discovered info
+await notebooklm({
+  operation: "library",
+  subOperation: "add",
+  url: "https://notebooklm.google.com/notebook/abc123...",
+  name: "API Documentation",
+  description: "REST API reference with authentication examples",
+  topics: ["api", "rest", "authentication"],
+});
+```
+
+### Method 2: Manual Entry
+
+If you already know the details:
+
+```typescript
+await notebooklm({
+  operation: "library",
+  subOperation: "add",
+  url: "https://notebooklm.google.com/notebook/abc123...",
+  name: "Project Documentation",
+  description: "Architecture and design decisions",
+  topics: ["architecture", "design", "documentation"],
+});
+```
+
+## Usage Examples
+
+### Query Active Notebook
+
+```typescript
+// Set active notebook first
+await notebooklm({
+  operation: "library",
+  subOperation: "activate",
+  notebookId: "api-docs",
+});
+
+// Query without specifying notebook
+const answer = await notebooklm({
+  operation: "query",
+  question: "What are the rate limits?",
+});
+
+console.log(answer.output);
+```
+
+### Query Specific Notebook
+
+```typescript
+const answer = await notebooklm({
+  operation: "query",
+  question: "What are the rate limits?",
+  notebookId: "api-docs",
+});
+```
+
+### Query by URL
+
+```typescript
+const answer = await notebooklm({
+  operation: "query",
+  question: "What are the rate limits?",
+  notebookUrl: "https://notebooklm.google.com/notebook/abc123...",
+});
+```
+
+### List All Notebooks
+
+```typescript
+const library = await notebooklm({
+  operation: "library",
+  subOperation: "list",
+});
+
+console.log(library.output);
+```
+
+### Search Notebooks
+
+```typescript
+const results = await notebooklm({
+  operation: "library",
+  subOperation: "search",
+  query: "authentication",
+});
+
+console.log(results.output);
+```
+
+## Troubleshooting
+
+### "Not authenticated" Error
+
+**Cause:** Authentication expired or never completed.
+
+**Fix:**
+
+```typescript
+await notebooklm({
+  operation: "auth",
+  subOperation: "setup",
+  showBrowser: true,
+});
+```
+
+### "ModuleNotFoundError" Error
+
+**Cause:** Python dependencies not installed.
+
+**Fix:** The tool auto-installs on first use. If it fails:
+
+```bash
+cd ~/.opencode/skills/notebooklm
+python -m venv .venv
+source .venv/bin/activate  # Linux/Mac
+# or .venv\Scripts\activate  # Windows
+pip install -r requirements.txt
+python -m patchright install chromium
+```
+
+### "Notebook not found" Error
+
+**Cause:** Notebook ID doesn't exist in library.
+
+**Fix:**
+
+```typescript
+// List available notebooks
+await notebooklm({ operation: "library", subOperation: "list" });
+
+// Or add the notebook first
+await notebooklm({
+  operation: "library",
+  subOperation: "add",
+  url: "...",
+  name: "...",
+  description: "...",
+  topics: ["..."],
+});
+```
+
+### Rate Limit (50 queries/day)
+
+**Cause:** Free Google account limit reached.
+
+**Fix:**
+
+- Wait 24 hours
+- Use a different Google account
+- Upgrade to Google One AI Premium (if available)
+
+### Browser Not Opening
+
+**Cause:** Chrome not found or headless mode enabled.
+
+**Fix:**
+
+```typescript
+// Always use showBrowser: true for auth
+await notebooklm({
+  operation: "auth",
+  subOperation: "setup",
+  showBrowser: true, // Required!
+});
+```
+
+## Data Locations
+
+All data stored in `~/.opencode/skills/notebooklm/`:
+
+```
+~/.opencode/skills/notebooklm/
+├── data/
+│   ├── library.json          # Your notebook library
+│   ├── auth_info.json        # Authentication metadata
+│   └── browser_state/        # Browser cookies/session
+│       ├── state.json
+│       └── browser_profile/
+├── scripts/                  # Python automation scripts
+│   ├── run.py               # Virtual environment wrapper
+│   ├── ask_question.py      # Query interface
+│   ├── notebook_manager.py  # Library management
+│   ├── auth_manager.py      # Authentication
+│   ├── browser_utils.py     # Browser utilities
+│   └── config.py            # Configuration
+├── .venv/                    # Python virtual environment
+├── requirements.txt          # Python dependencies
+└── .gitignore               # Protects sensitive data
+```
+
+**Security Note:** The `data/` directory contains authentication cookies. Never commit this to git.
+
+## Updating the Skill
+
+To update to the latest version:
+
+```bash
+cd ~/.opencode/skills/notebooklm
+git pull origin master
+```
+
+## Uninstalling
+
+To completely remove the skill:
+
+```bash
+rm -rf ~/.opencode/skills/notebooklm
+```
+
+## Getting Help
+
+- **Original Repository:** https://github.com/PleasePrompto/notebooklm-skill
+- **NotebookLM Help:** https://support.google.com/notebooklm
+- **OpenCodeKit Issues:** File an issue in the opencodekit-template repository