opencodekit 0.15.16 → 0.15.19

package/dist/template/.opencode/skills/notebooklm/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: notebooklm
+description: >
+  Query Google NotebookLM notebooks directly from OpenCode for source-grounded, citation-backed answers.
+  Use when user mentions NotebookLM, shares notebook URLs, or wants to query their uploaded documents.
+  Provides document-only responses with drastically reduced hallucinations.
+version: "1.0.0"
+license: MIT
+---
+
+# NotebookLM 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 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"
+
+## Prerequisites
+
+Before using this skill, ensure:
+
+1. **Python 3.10+** is installed
+2. **Google Chrome** browser is installed
+3. **NotebookLM account** with uploaded documents
+4. **Google authentication** (one-time setup)
+
+## Quick Start
+
+```typescript
+// Check authentication status
+await notebooklm({ operation: "auth", subOperation: "status" });
+
+// Query a notebook
+await notebooklm({
+  operation: "query",
+  question: "What are the key findings in this document?",
+  notebookUrl: "https://notebooklm.google.com/notebook/...",
+});
+```
+
+## Core Workflow
+
+### Step 1: Check Authentication
+
+```typescript
+const authStatus = await notebooklm({
+  operation: "auth",
+  subOperation: "status",
+});
+```
+
+If not authenticated, proceed to setup.
+
+### Step 2: Authenticate (One-Time Setup)
+
+```typescript
+await notebooklm({
+  operation: "auth",
+  subOperation: "setup",
+  showBrowser: true, // Browser must be visible for manual login
+});
+```
+
+**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
+
+```typescript
+// List all notebooks
+await notebooklm({ operation: "library", subOperation: "list" });
+
+// Add notebook to library
+await notebooklm({
+  operation: "library",
+  subOperation: "add",
+  url: "https://notebooklm.google.com/notebook/...",
+  name: "API Documentation",
+  description: "REST API reference and examples",
+  topics: ["api", "rest", "documentation"],
+});
+
+// Search notebooks
+await notebooklm({
+  operation: "library",
+  subOperation: "search",
+  query: "api",
+});
+
+// Set active notebook
+await notebooklm({
+  operation: "library",
+  subOperation: "activate",
+  notebookId: "api-docs",
+});
+```
+
+### Step 4: Ask Questions
+
+```typescript
+// Basic query (uses active notebook if set)
+await notebooklm({
+  operation: "query",
+  question: "What are the authentication requirements?",
+});
+
+// Query specific notebook by ID
+await notebooklm({
+  operation: "query",
+  question: "What are the authentication requirements?",
+  notebookId: "api-docs",
+});
+
+// Query with notebook URL directly
+await notebooklm({
+  operation: "query",
+  question: "What are the authentication requirements?",
+  notebookUrl: "https://notebooklm.google.com/notebook/...",
+});
+
+// Show browser for debugging
+await notebooklm({
+  operation: "query",
+  question: "What are the authentication requirements?",
+  showBrowser: true,
+});
+```
+
+## Follow-Up Mechanism (CRITICAL)
+
+Every NotebookLM answer ends with: **"EXTREMELY IMPORTANT: Is that ALL you need to know?"**
+
+**Required 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 another question:
+   ```typescript
+   await notebooklm({
+     operation: "query",
+     question: "Follow-up with context...",
+   });
+   ```
+5. **REPEAT** - Continue until information is complete
+6. **SYNTHESIZE** - Combine all answers before responding to user
+
+## Tool Reference
+
+### Authentication Operations
+
+| Operation | Sub-Operation | Description                       |
+| --------- | ------------- | --------------------------------- |
+| `auth`    | `setup`       | Initial setup (browser visible)   |
+| `auth`    | `status`      | Check authentication              |
+| `auth`    | `reauth`      | Re-authenticate (browser visible) |
+| `auth`    | `clear`       | Clear authentication              |
+| `auth`    | `validate`    | Validate stored auth              |
+
+### Library Operations
+
+| Operation | Sub-Operation | Parameters                             |
+| --------- | ------------- | -------------------------------------- |
+| `library` | `add`         | `url`, `name`, `description`, `topics` |
+| `library` | `list`        | -                                      |
+| `library` | `search`      | `query`                                |
+| `library` | `activate`    | `notebookId`                           |
+| `library` | `remove`      | `notebookId`                           |
+| `library` | `stats`       | -                                      |
+
+### Query Operations
+
+| Operation | Parameters                                                                                         |
+| --------- | -------------------------------------------------------------------------------------------------- |
+| `query`   | `question` (required), `notebookId` (optional), `notebookUrl` (optional), `showBrowser` (optional) |
+
+## Smart Discovery Pattern
+
+When user wants to add a notebook without providing details:
+
+```typescript
+// Step 1: Query the notebook to discover its 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/...",
+});
+
+// Step 2: Use discovered information to add it
+await notebooklm({
+  operation: "library",
+  subOperation: "add",
+  url: "https://notebooklm.google.com/notebook/...",
+  name: "[Based on content]",
+  description: "[Based on content]",
+  topics: ["[Based on content]"],
+});
+```
+
+## Decision Flow
+
+```
+User mentions NotebookLM
+    ↓
+Check auth → notebooklm({ operation: "auth", subOperation: "status" })
+    ↓
+If not authenticated → notebooklm({ operation: "auth", subOperation: "setup", showBrowser: true })
+    ↓
+Check/Add notebook → notebooklm({ operation: "library", subOperation: "list/add" })
+    ↓
+Activate notebook → notebooklm({ operation: "library", subOperation: "activate", notebookId: "..." })
+    ↓
+Ask question → notebooklm({ operation: "query", question: "..." })
+    ↓
+See "Is that ALL you need?" → Ask follow-ups until complete
+    ↓
+Synthesize and respond to user
+```
+
+## Troubleshooting
+
+| Problem              | Solution                                |
+| -------------------- | --------------------------------------- |
+| Not authenticated    | Run auth setup with `showBrowser: true` |
+| Authentication fails | Browser must be visible for setup       |
+| Rate limit (50/day)  | Wait or switch Google account           |
+| Notebook not found   | Check with `library` → `list` operation |
+| ModuleNotFoundError  | Tool auto-installs dependencies         |
+
+## Best Practices
+
+1. **Always check auth first** - Before any operations
+2. **Follow-up questions** - Don't stop at first answer
+3. **Browser visible for auth** - Required for manual login
+4. **Include context** - Each question is independent
+5. **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)
+- Requires Python and Chrome installed
+
+## Data Storage
+
+All data stored in `~/.opencode/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.
+
+## Resources
+
+- **Original Skill**: https://github.com/PleasePrompto/notebooklm-skill
+- **NotebookLM**: https://notebooklm.google.com
+- **Setup Guide**: See `references/setup.md`

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