Contributing to notebooklm-py

Contributing to notebooklm-py

For Human Contributors

Getting Started

# Install in development mode
pip install -e ".[all]"
playwright install chromium

# Run tests
pytest

# Run linter
ruff check src/ tests/

# Run formatter
ruff format src/ tests/

Code Quality

This project uses **ruff** for linting and formatting:

# Check for lint issues
ruff check src/ tests/

# Auto-fix lint issues
ruff check --fix src/ tests/

# Check formatting
ruff format --check src/ tests/

# Apply formatting
ruff format src/ tests/

**Pre-commit hooks** (optional but recommended):

pip install pre-commit
pre-commit install

Pull Request Process

1. Create a feature branch from main
2. Make your changes with clear commit messages
3. Ensure tests pass: pytest
4. Ensure lint passes: ruff check src/ tests/
5. Ensure formatting: ruff format --check src/ tests/
6. Submit a PR with a description of changes

Pull Request Quality Expectations

• Reference an issue: PRs should link to an existing issue or clearly describe the problem being solved. If no issue exists, open one first for discussion.
• AI-assisted contributions: Welcome, but the submitter must review, understand, and test the code before submitting. PRs that appear to be unreviewed AI output will be closed.
• No duplicates: Check existing open PRs before submitting. Duplicate PRs for the same issue will be closed in favor of the first or best submission.
• Accurate severity: Claims of "critical" bugs must include evidence (stack trace, reproduction steps, affected users). Routine edge cases are not critical.
• Tested locally: All PRs must include evidence of local testing. The PR template includes a checklist for this.

---

Documentation Rules for AI Agents

**IMPORTANT:** All AI agents (Claude, Gemini, etc.) must follow these rules when working in this repository.

File Creation Rules

1. **No Root Rule** - Never create `.md` files in the repository root unless explicitly instructed by the user.

2. **Modify, Don't Fork** - Edit existing files; never create `FILE_v2.md`, `FILE_REFERENCE.md`, or `FILE_updated.md` duplicates.

3. **Scratchpad Protocol** - All analysis, investigation logs, and intermediate work go in `docs/scratch/` with date prefix: `YYYY-MM-DD-.md`

4. **Consolidation First** - Before creating new docs, search for existing related docs and update them instead.

Protected Sections

Some sections within files are critical and must not be modified without explicit user approval.

**Inline markers** (source of truth):

## Critical Section Title
Content that should not be changed by agents...

For code files:

# PROTECTED: Do not modify without approval
class RPCMethod(Enum):
    ...
# END PROTECTED

**Rule:** Never modify content between `PROTECTED` and `END PROTECTED` markers unless explicitly