This directory holds the canonical decisions that shape the notebooklm-py codebase. Each record explains why a load-bearing pattern exists so that future contributors don't re-litigate (or silently re-introduce) the trade-off.
- Read the relevant ADR before changing the pattern it describes. If you disagree, write a new ADR that supersedes it — do not edit the original past correcting typos.
- Numbering is append-only. Retired ADR numbers are never re-used.
- Filenames follow
NNNN-short-title.md(lowercase, kebab-case). - Status values:
Proposed,Proposed — <short explanation>,Accepted,Accepted (retroactive),Accepted (#PR),Accepted (Sunset = <event>),Superseded — <short explanation>,Superseded by ADR-NNNN (#PR),Deprecated,Rejected. - Format: lightweight hybrid — six sections in this exact order: Title heading (
# ADR-NNNN: <Title>), Status, Context, Decision, Consequences, Alternatives considered. See 0000-template.md.
The pull-request template asks contributors to confirm that any change to the architectural shape of the codebase carries an ADR addition or update. "Architectural shape" means any of:
- New / removed / relocated modules in
src/notebooklm/_runtime/,src/notebooklm/_middleware/,src/notebooklm/auth.py,src/notebooklm/_auth/,src/notebooklm/cli/services/. - Changes to the contracts between layers (CLI ↔ Client ↔ Core ↔ RPC).
- New or retired test patterns (fixtures, monkeypatch policy, conformance tests).
- New cross-cutting policies (retry, idempotency, scrubbing, loop affinity).
Pure bug fixes, additive RPC method IDs, and CLI ergonomics changes do not require an ADR.
The ADR Index table utilizes five eras of Status notation to reflect the lifecycle of decisions:
Accepted/Accepted (retroactive)— The decision is currently active and adopted.Accepted (Tier X PR Y.Z)— Historical PR-naming convention from the early refactoring tiers (Tiers 11-12).Superseded — <note>/Superseded by ADR-NNNN (#PR)— Canonical supersession forms, either with a short inline explanation or a replacing ADR and PR.Accepted (#PR)/Accepted; <note>/Proposed — <note>— Short explanatory forms used when a status needs one compact qualifier.Superseded by <named-PR> (D1/D2 PR-X)— Pre-canonical historical supersession form, linking to specific branch-refactoring PRs.
| ADR | Title | Status |
|---|---|---|
| 0001 | Layered _core seams and the property-bridge policy |
Superseded — bridge policy retired in session-shrink arc |
| 0002 | Capability Protocol pattern (SessionCapabilities fat union) |
Superseded by arch-d2-cutover (#835) |
| 0003 | auth.py write-through facade (_AuthFacadeModule) |
Superseded — closed by ADR-0014 (session-decoupling Waves 3a + 4 T2.2 + 5) |
| 0004 | Loop-affinity contract for NotebookLMClient |
Accepted (retroactive) |
| 0005 | Mutating-RPC idempotency taxonomy | Accepted (retroactive) |
| 0006 | VCR cassette scrubber strategy | Accepted (retroactive) |
| 0007 | Test monkeypatch policy | Accepted |
| 0008 | cli/services/ extraction pattern |
Accepted (retroactive) |
| 0009 | Middleware chain for cross-cutting transport concerns | Accepted (Tier 12 PR 12.1); context refined by ADR-0013 (#866) |
| 0010 | Session/Kernel split | Superseded by ADR-0013 (#866) |
| 0011 | Schema validation policy (strict-decode default) | Accepted (Tier 13 PR 13.9a) |
| 0012 | Implementation surface convention (underscore-prefix policy) | Accepted (Tier 13 PR 13.9a) |
| 0013 | Composable Session Capabilities and Feature-Local Runtimes | Accepted |
| 0014 | Feature-local runtime adapters as Protocol satisfiers | Accepted (#1082) |
| 0015 | Typed JSON error envelope covers post-parse ClickException failures |
Accepted |
| 0016 | Auth identity and core logger compatibility | Accepted |
| 0017 | Public-facade / private-implementation re-export convention | Accepted (retroactive) |
| 0018 | Deprecation strategy (_deprecation.py) |
Accepted (retroactive) |
| 0019 | Error-and-return contract for the public API | Accepted; v0.8.0 implementation landed |
| 0020 | Sealed async result types for artifact generation | Proposed — design of record; recommends continued deferral (ADR-0019 Tier 3 / #1345) |
| 0021 | Transport-neutral application layer (_app/) |
Accepted |
| 0022 | Regenerable test baselines (derive / store / compare / regen) | Accepted |
| 0023 | Master-token headless auth (Option A) | Accepted |
| 0024 | MCP remote file transfer (signed-URL side-channel) | Proposed |
| 0025 | MCP tool granularity — mega-tools vs. discrete verbs | Accepted |
| 0026 | MCP Studio surface — notes + artifacts unified | Accepted |
| 0027 | In-app MCP-App upload widget (opt-in) | Accepted (experimental / opt-in) |
| 0028 | Renaming the package for Google's "Gemini Notebook" rebrand | Proposed — v3, single-release 0.9.0 flip |
| 0029 | Single canonical storage_state.json writer |
Accepted (rolling out) |
| 0030 | One recovery ladder (single-flight core + off-loop loaders) | Accepted (rolling out) |
| 0031 | Credential-tier domain model for _auth |
Proposed — Stage 0 landed; Stage 5 deferred by ADR-0033 |
| 0032 | Auth domain types (Cookie/CookieJar/MasterToken) + AuthTokens runway |
Accepted; implementation remains incremental |
| 0033 | _auth consolidation policy — sanctioned-merge ceilings + function-granular write boundary; amended by ADR-0034 |
Accepted (#2156) |
| 0034 | Auth storage object model and incremental extraction | Accepted |
| 0035 | Mobile backend as a resilience transport | Accepted |
| 0036 | Browser acquisition package and neutral login orchestration | Accepted |
| 0037 | Live usage and quota API | Accepted |
| 0038 | Local fault-injection services and concurrent resilience scenarios | Accepted |
| 0039 | Backend-specific credential surfaces | Accepted; C9b implementation remains release-gated |
ADR-0007 ships alongside its enforcement substrate: the concrete fixtures (tests/_fixtures/) and meta-lint (tests/_guardrails/test_no_forbidden_monkeypatches.py) are added in the same PR (arch-d1-fixtures-scaffolding) so the record is grounded in working code rather than an empty placeholder.
- Architecture — Canonical overview of the layered architecture.
- Release migration ledger — Shipped-warning evidence and earliest eligible transition releases.
docs/development.md— contributor-facing process notes (testing, releasing, environment setup).CLAUDE.md— onboarding map for AI assistants. Architectural rationale belongs here indocs/adr/, not inCLAUDE.md.