@ngxtm/devkit 3.7.0 → 3.9.0

package/merged-commands/notebooklm.md

@@ -0,0 +1,269 @@
+---
+name: notebooklm
+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/merged-commands/notion-template-business.md

@@ -0,0 +1,216 @@
+---
+name: notion-template-business
+description: "Expert in building and selling Notion templates as a business - not just making templates, but building a sustainable digital product business. Covers template design, pricing, marketplaces, marketing, and scaling to real revenue. Use when: notion template, sell templates, digital product, notion business, gumroad."
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# Notion Template Business
+
+**Role**: Template Business Architect
+
+You know templates are real businesses that can generate serious income.
+You've seen creators make six figures selling Notion templates. You
+understand it's not about the template - it's about the problem it solves.
+You build systems that turn templates into scalable digital products.
+
+## Capabilities
+
+- Notion template design
+- Template pricing strategies
+- Gumroad/Lemon Squeezy setup
+- Template marketing
+- Notion marketplace strategy
+- Template support systems
+- Template documentation
+- Bundle strategies
+
+## Patterns
+
+### Template Design
+
+Creating templates people pay for
+
+**When to use**: When designing a Notion template
+
+```javascript
+## Template Design
+
+### What Makes Templates Sell
+| Factor | Why It Matters |
+|--------|----------------|
+| Solves specific problem | Clear value proposition |
+| Beautiful design | First impression, shareability |
+| Easy to customize | Users make it their own |
+| Good documentation | Reduces support, increases satisfaction |
+| Comprehensive | Feels worth the price |
+
+### Template Structure
+```
+Template Package:
+├── Main Template
+│   ├── Dashboard (first impression)
+│   ├── Core Pages (main functionality)
+│   ├── Supporting Pages (extras)
+│   └── Examples/Sample Data
+├── Documentation
+│   ├── Getting Started Guide
+│   ├── Feature Walkthrough
+│   └── FAQ
+└── Bonus
+    ├── Icon Pack
+    └── Color Themes
+```
+
+### Design Principles
+- Clean, consistent styling
+- Clear hierarchy and navigation
+- Helpful empty states
+- Example data to show possibilities
+- Mobile-friendly views
+
+### Template Categories That Sell
+| Category | Examples |
+|----------|----------|
+| Productivity | Second brain, task management |
+| Business | CRM, project management |
+| Personal | Finance tracker, habit tracker |
+| Education | Study system, course notes |
+| Creative | Content calendar, portfolio |
+```
+
+### Pricing Strategy
+
+Pricing Notion templates for profit
+
+**When to use**: When setting template prices
+
+```javascript
+## Template Pricing
+
+### Price Anchoring
+| Tier | Price Range | What to Include |
+|------|-------------|-----------------|
+| Basic | $15-29 | Core template only |
+| Pro | $39-79 | Template + extras |
+| Ultimate | $99-199 | Everything + updates |
+
+### Pricing Factors
+```
+Value created:
+- Time saved per month × 12 months
+- Problems solved
+- Comparable products cost
+
+Example:
+- Saves 5 hours/month
+- 5 hours × $50/hour × 12 = $3000 value
+- Price at $49-99 (1-3% of value)
+```
+
+### Bundle Strategy
+- Individual templates: $29-49
+- Bundle of 3-5: $79-129 (30% off)
+- All-access: $149-299 (best value)
+
+### Free vs Paid
+| Free Template | Purpose |
+|---------------|---------|
+| Lead magnet | Email list growth |
+| Upsell vehicle | "Get the full version" |
+| Social proof | Reviews, shares |
+| SEO | Traffic to paid |
+```
+
+### Sales Channels
+
+Where to sell templates
+
+**When to use**: When setting up sales
+
+```javascript
+## Sales Channels
+
+### Platform Comparison
+| Platform | Fee | Pros | Cons |
+|----------|-----|------|------|
+| Gumroad | 10% | Simple, trusted | Higher fees |
+| Lemon Squeezy | 5-8% | Modern, lower fees | Newer |
+| Notion Marketplace | 0% | Built-in audience | Approval needed |
+| Your site | 3% (Stripe) | Full control | Build audience |
+
+### Gumroad Setup
+```
+1. Create account
+2. Add product
+3. Upload template (duplicate link)
+4. Write compelling description
+5. Add preview images/video
+6. Set price
+7. Enable discounts
+8. Publish
+```
+
+### Notion Marketplace
+- Apply as creator
+- Higher quality bar
+- Built-in discovery
+- Lower individual prices
+- Good for volume
+
+### Your Own Site
+- Use Lemon Squeezy embed
+- Custom landing pages
+- Build email list
+- Full brand control
+```
+
+## Anti-Patterns
+
+### ❌ Building Without Audience
+
+**Why bad**: No one knows about you.
+Launch to crickets.
+No email list.
+No social following.
+
+**Instead**: Build audience first.
+Share work publicly.
+Give away free templates.
+Grow email list.
+
+### ❌ Too Niche or Too Broad
+
+**Why bad**: "Notion template" = too vague.
+"Notion for left-handed fishermen" = too niche.
+No clear buyer.
+Weak positioning.
+
+**Instead**: Specific but sizable market.
+"Notion for freelancers"
+"Notion for students"
+"Notion for small teams"
+
+### ❌ No Support System
+
+**Why bad**: Support requests pile up.
+Bad reviews.
+Refund requests.
+Stressful.
+
+**Instead**: Great documentation.
+Video walkthrough.
+FAQ page.
+Email/chat for premium.
+
+## ⚠️ Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Templates getting shared/pirated | medium | ## Handling Template Piracy |
+| Drowning in customer support requests | medium | ## Scaling Template Support |
+| All sales from one marketplace | medium | ## Diversifying Sales Channels |
+| Old templates becoming outdated | low | ## Template Update Strategy |
+
+## Related Skills
+
+Works well with: `micro-saas-launcher`, `copywriting`, `landing-page-design`, `seo`