diff --git a/src/api/models.rs b/src/api/models.rs
index 4e16fc9..fb87ae7 100644
--- a/src/api/models.rs
+++ b/src/api/models.rs
@@ -1,4 +1,10 @@
 //! Model definitions and lookup.
+//!
+//! Maps our user-friendly model names to internal Antigravity identifiers.
+//! The `model_enum` values are protobuf enum numbers extracted from extension.js:
+//! placeholder models use 1000+N (e.g. M26→1026), while named models like
+//! `MODEL_CLAUDE_4_OPUS` have their own enum values (e.g. 290).
+//! See `docs/ls-binary-analysis.md` for the full enum mapping.
 
 /// Model definition: friendly name → (antigravity_id, protobuf_enum, label).
 pub(crate) struct ModelDef {
diff --git a/src/proto.rs b/src/proto.rs
index bb558c9..17d1293 100644
--- a/src/proto.rs
+++ b/src/proto.rs
@@ -3,6 +3,11 @@
 //! This is a minimal, hand-rolled encoder. We do NOT use prost or any codegen
 //! because we need precise control over field ordering and encoding to produce
 //! byte-identical output to the captured webview traffic.
+//!
+//! The LS communicates with Google via gRPC over H2, using proto messages from
+//! the `exa.*_pb` package family. Init metadata (field 34 of the init request)
+//! carries the `detect_and_use_proxy` enum, model selection, and version info.
+//! See `docs/ls-binary-analysis.md` for the full proto schema reverse engineering.
 
 use crate::constants::{client_version, CLIENT_NAME};
 
diff --git a/src/quota.rs b/src/quota.rs
index 650e293..dfc31a2 100644
--- a/src/quota.rs
+++ b/src/quota.rs
@@ -1,5 +1,15 @@
 //! Quota monitor — polls the local LS `GetUserStatus` to track
 //! prompt/flow credits and per-model rate limits without touching Google servers.
+//!
+//! The LS's `GetUserStatus` response contains `cascadeModelConfigData` with
+//! per-model `quotaInfo` (remaining fraction, reset time) and plan-level credit
+//! balances (prompt, flow, flex). This data originates from Google's
+//! `PredictionService/RetrieveUserQuota` / `v1internal:retrieveUserQuota` endpoint,
+//! but asking the LS is simpler since it caches this data locally.
+//!
+//! The credit system uses the `google/internal/cloud/code/v1internal/credits`
+//! proto package with `Credits_CreditType` enum. The `CASCADE_ENFORCE_QUOTA`
+//! config key controls whether quotas are actually enforced.
 
 use serde::Serialize;
 use std::sync::Arc;