feat: convert to UV shebang scripts with PEP 723 metadata

[ddlaws0n]

Summary

Converts the NotebookLM skill from manual .venv/requirements.txt management to modern uv shebang scripts with PEP 723 inline metadata.

Related Issue: Closes #8

Breaking Changes

This is a v2.0.0 breaking change:

Before:

python scripts/run.py ask_question.py --question "..."

After:

./scripts/ask_question.py --question "..."
# or
uv run scripts/ask_question.py --question "..."

Migration Required:

• Install UV: curl -LsSf https://astral.sh/uv/install.sh | sh
• See CHANGELOG.md for complete migration guide

Changes

Added

• UV shebang with PEP 723 inline metadata in all entry point scripts:
  • ask_question.py - patchright==1.55.2, python-dotenv==1.0.0
  • auth_manager.py - patchright==1.55.2, python-dotenv==1.0.0
  • notebook_manager.py - python-dotenv==1.0.0
  • cleanup_manager.py - no dependencies
• Automatic dependency installation on first run
• Dependency caching for instant subsequent runs
• Comprehensive migration guide in CHANGELOG.md

Removed

• scripts/run.py - No longer needed with UV shebang
• scripts/setup_environment.py - Replaced by UV automatic setup
• requirements.txt - Dependencies now inline in scripts

Changed

• Updated SKILL.md with new command patterns
• Updated README.md installation and quick start
• Updated api_reference.md with new examples
• All documentation now uses UV execution pattern
• Removed sys.path manipulation from scripts (UV handles imports)

Benefits

1. Simpler installation: No manual venv setup
2. Faster execution: UV caches dependencies (instant second run)
3. Self-documenting: Dependencies visible in each script
4. Modern standard: PEP 723 is official Python spec
5. Less code: Removed 300+ lines of wrapper infrastructure

Testing

✅ Tested on macOS Sonoma:

• Direct execution: ./scripts/*.py works
• Explicit uv: uv run scripts/*.py works
• Import resolution verified (no ModuleNotFoundError)
• Dependency caching working (instant second run, ~0.09s)
• Full authentication workflow tested
• NotebookLM query workflow tested
• Data directory preserved (library.json, auth_info.json)

⚠️ Windows/Linux testing needed:

Windows testers:

uv run scripts\auth_manager.py status
uv run scripts\notebook_manager.py list
uv run scripts\ask_question.py --question "test" --notebook-url "URL"

Linux testers:

./scripts/auth_manager.py status
./scripts/notebook_manager.py list
./scripts/ask_question.py --question "test" --notebook-url "URL"

Please verify:

• UV installs dependencies correctly
• Scripts execute without errors
• Imports resolve correctly
• Browser automation works
• Authentication flow works
• NotebookLM queries succeed

Migration Guide

See CHANGELOG.md for detailed migration instructions.

Quick migration:

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Update skill
cd ~/.claude/skills/notebooklm
git pull

# Clean old venv (optional)
rm -rf .venv

# Unix/Mac: Make executable
chmod +x scripts/*.py

# Done! Try it:
./scripts/auth_manager.py status

References

• UV Documentation
• PEP 723: Inline Script Metadata
• Discussion in Proposal: Modernize to UV shebang scripts (PEP 723) #8

Code Statistics

Before:

• 11 files
• 473 lines of infrastructure code (run.py, setup_environment.py, requirements.txt)

After:

• 8 files (-3 files)
• 290 lines total (+183 lines in documentation, -473 lines infrastructure)
• Net reduction: 183 lines of code

Commit: cbf346d