From 2ffffd5453449aaa31c0d330ff7e568711fdca0d Mon Sep 17 00:00:00 2001
From: Arran Ireland <a.ireland.git@proton.me>
Date: Sun, 23 Aug 2026 09:02:56 +0100
Subject: [PATCH 1/3] chore: update readme

---
 README.md | 53 ++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 44 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index a251be7..30a6198 100644
--- a/README.md
+++ b/README.md
@@ -1,31 +1,66 @@
 # lichess-api
 
 [![Crates.io][crates-badge]][crates-url]
+[![Docs.rs][docs-badge]][docs-url]
 [![Dependencies][deps-badge]][deps-url]
 [![Apache 2.0 licensed][apache-badge]][apache-url]
 
 [crates-badge]: https://img.shields.io/crates/v/lichess-api.svg
 [crates-url]: https://crates.io/crates/lichess-api
+[docs-badge]: https://docs.rs/lichess-api/badge.svg
+[docs-url]: https://docs.rs/lichess-api
 [deps-badge]: https://deps.rs/repo/github/ion232/lichess-api/status.svg
 [deps-url]: https://deps.rs/repo/github/ion232/lichess-api
 [apache-badge]: https://img.shields.io/badge/license-Apache%202.0-blue.svg
 [apache-url]: LICENSE
 
-A Rust API client library for [the current lichess.org API](https://lichess.org/api).
-All endpoints are supported.
+An asynchronous client library for [the current lichess.org API](https://lichess.org/api) with all endpoints supported.
 
-## Features
+## Quick start
 
-| Feature | Default | Description |
-|---------|:-------:|-------------|
-| `oauth` |   yes   | OAuth2 authorization code flow with PKCE, for acting on behalf of other users. Pulls in `rand` and `sha2`. |
-
-Most clients authenticate with a [personal API token](https://lichess.org/account/oauth/token) and don't need the OAuth flow. If you only ever act as yourself, you can drop the dependencies:
+Add the dependencies:
 
 ```toml
-lichess-api = { version = "0.7", default-features = false }
+[dependencies]
+lichess-api = "0.7"
+tokio = { version = "1", features = ["full"] }
+```
+
+Example request:
+
+```rust,no_run
+use lichess_api::client::LichessApi;
+
+#[tokio::main]
+async fn main() -> lichess_api::error::Result<()> {
+    let client = reqwest::Client::new();
+    let token = std::env::var("LICHESS_TOKEN").ok();
+    let api = LichessApi::new(client, token);
+
+    let profile = api.get_profile().await?;
+    println!("username: {}", profile.user.username);
+
+    Ok(())
+}
 ```
 
+## Authentication
+
+Most endpoints require a bearer token but some don't. E.g. the daily puzzle, etc.
+
+- **Acting as yourself**: generate a [personal API
+  token](https://lichess.org/account/oauth/token) and pass it to
+  `LichessApi::new` as above.
+- **Acting on behalf of another user**: Ensure the oauth feature is enabled and use the OAuth2 authorization code flow
+  with PKCE, via [`AuthorizationUrl`](https://docs.rs/lichess-api/latest/lichess_api/model/oauth/authorize/struct.AuthorizationUrl.html) and
+  [`PendingAuthorization`](https://docs.rs/lichess-api/latest/lichess_api/model/oauth/struct.PendingAuthorization.html).
+
+## Features
+
+| Feature | Default | Description |
+|---------|:-------:|-------------|
+| `oauth` |   yes   | OAuth2 authorization code flow with PKCE, for acting on behalf of other users. |
+
 ## Contributing
 
 If you have any ideas, bug reports, feature requests, or fixes, please make an issue or submit a pull request.

From 044d19cf73f1739aad6eb124f403393e96dfa0d4 Mon Sep 17 00:00:00 2001
From: Arran Ireland <a.ireland.git@proton.me>
Date: Sun, 23 Aug 2026 09:03:50 +0100
Subject: [PATCH 2/3] docs: add top level crate docs

---
 lib/src/lib.rs | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/lib/src/lib.rs b/lib/src/lib.rs
index 88f9572..052ce96 100644
--- a/lib/src/lib.rs
+++ b/lib/src/lib.rs
@@ -1,3 +1,53 @@
+//! A Rust client for [the Lichess API](https://lichess.org/api).
+//!
+//! [`client::LichessApi`] wraps an HTTP client (currently only `reqwest::Client`
+//! is supported) with an optional bearer token. Every operation is a method on
+//! `LichessApi<reqwest::Client>`, grouped into one [`api`] module per Lichess API
+//! category (`api::account`, `api::games`, `api::tv`, ...). The request/response
+//! types for a given operation live in the matching [`model`] module
+//! (`model::account`, `model::games`, ...).
+//!
+//! # Authentication
+//!
+//! Most endpoints take a bearer token. For your own account, generate a
+//! [personal API token](https://lichess.org/account/oauth/token) and pass it to
+//! [`client::LichessApi::new`]:
+//!
+//! ```no_run
+//! use lichess_api::client::LichessApi;
+//!
+//! # async fn run() -> lichess_api::error::Result<()> {
+//! let http_client = reqwest::Client::new();
+//! let token = std::env::var("LICHESS_TOKEN").ok();
+//! let api = LichessApi::new(http_client, token);
+//!
+//! let profile = api.get_profile().await?;
+//! println!("logged in as {}", profile.user.username);
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! Public endpoints that don't require a token accept `LichessApi::new(client, None)`.
+//!
+//! To act on behalf of *other* users, use the OAuth2 authorization code flow
+//! with PKCE instead of a personal token — see
+//! [`model::oauth::authorize::AuthorizationUrl`] and
+//! [`model::oauth::PendingAuthorization`] for a full walkthrough, gated behind
+//! the default-on `oauth` feature.
+//!
+//! # Streamed endpoints
+//!
+//! Endpoints that stream newline-delimited JSON (board game state, TV feeds,
+//! broadcast rounds, ...) return a `Stream` of results instead of a single
+//! value, so results arrive as they're produced rather than after the whole
+//! response body has been read.
+//!
+//! # Errors
+//!
+//! Every operation returns [`error::Result`]; see [`error::Error`] for the
+//! failure cases (transport errors, non-2xx responses, deserialization
+//! failures, and OAuth-specific errors).
+
 pub mod api;
 pub mod client;
 pub mod error;

From c0fe82df0aab77961adc82474a0a1b8fb53c31a2 Mon Sep 17 00:00:00 2001
From: Arran Ireland <a.ireland.git@proton.me>
Date: Sun, 23 Aug 2026 09:11:23 +0100
Subject: [PATCH 3/3] docs: add module level docs

---
 lib/src/api/account.rs           |  9 +++++++++
 lib/src/api/analysis.rs          | 10 ++++++++++
 lib/src/api/arena_tournaments.rs | 16 ++++++++++++++++
 lib/src/api/board.rs             | 13 +++++++++++++
 lib/src/api/bot.rs               | 14 ++++++++++++++
 lib/src/api/broadcasts.rs        | 20 ++++++++++++++++++++
 lib/src/api/bulk_pairings.rs     | 12 ++++++++++++
 lib/src/api/challenges.rs        | 11 +++++++++++
 lib/src/api/external_engine.rs   | 18 ++++++++++++++++++
 lib/src/api/fide.rs              |  8 ++++++++
 lib/src/api/games.rs             | 14 ++++++++++++++
 lib/src/api/messaging.rs         |  5 +++++
 lib/src/api/oauth.rs             |  9 +++++++++
 lib/src/api/openings.rs          |  9 +++++++++
 lib/src/api/puzzles.rs           | 14 ++++++++++++++
 lib/src/api/relations.rs         |  7 +++++++
 lib/src/api/simuls.rs            |  8 ++++++++
 lib/src/api/studies.rs           | 16 ++++++++++++++++
 lib/src/api/swiss_tournaments.rs | 10 ++++++++++
 lib/src/api/tablebase.rs         | 10 ++++++++++
 lib/src/api/teams.rs             | 10 ++++++++++
 lib/src/api/tv.rs                | 12 ++++++++++++
 lib/src/api/users.rs             | 16 ++++++++++++++++
 23 files changed, 271 insertions(+)

diff --git a/lib/src/api/account.rs b/lib/src/api/account.rs
index 17b1356..5393f70 100644
--- a/lib/src/api/account.rs
+++ b/lib/src/api/account.rs
@@ -1,3 +1,12 @@
+//! Read and manage the logged in user's own account: public profile, email
+//! address, kid mode, preferences, and activity timeline.
+//!
+//! Every method here requires a bearer token for the account being queried —
+//! there is no anonymous access. [`LichessApi::get_email_address`] and
+//! [`LichessApi::get_kid_mode_status`]/[`LichessApi::set_kid_mode_status`]
+//! additionally require the `email:read` and `preference:read` (or
+//! `preference:write`) scopes respectively, not just any token.
+
 use crate::client::LichessApi;
 use crate::error::Result;
 use crate::model::account::*;
diff --git a/lib/src/api/analysis.rs b/lib/src/api/analysis.rs
index a3453b6..4a9fe2a 100644
--- a/lib/src/api/analysis.rs
+++ b/lib/src/api/analysis.rs
@@ -1,3 +1,13 @@
+//! Position analysis.
+//!
+//! Lichess maintains a database of cloud engine evaluations for positions it
+//! has already analyzed (mostly openings, around 320 million positions).
+//! [`LichessApi::get_cloud_evaluation`] looks one up by FEN and returns its
+//! principal variations if present, or an error if the position hasn't been
+//! evaluated. This endpoint is public and needs no bearer token; it's meant
+//! for occasional lookups, not bulk fetching — for that, use the exported
+//! evaluation database from lichess.org directly.
+
 use crate::client::LichessApi;
 use crate::error::Result;
 use crate::model::analysis::*;
diff --git a/lib/src/api/arena_tournaments.rs b/lib/src/api/arena_tournaments.rs
index 2fefeb8..9591efd 100644
--- a/lib/src/api/arena_tournaments.rs
+++ b/lib/src/api/arena_tournaments.rs
@@ -1,3 +1,19 @@
+//! Arena tournaments: Lichess's continuous-pairing tournament format, where
+//! players score points per game and climb a live leaderboard for the
+//! duration of the event.
+//!
+//! Covers listing current tournaments, creating and updating them, joining,
+//! withdrawing/pausing, terminating, managing team battles, and reading back
+//! standings, results, team standings, and games. Creating or modifying a
+//! tournament ([`create_arena_tournament`](LichessApi::create_arena_tournament),
+//! [`update_arena_tournament`](LichessApi::update_arena_tournament),
+//! [`join_arena_tournament`](LichessApi::join_arena_tournament),
+//! [`withdraw_from_arena_tournament`](LichessApi::withdraw_from_arena_tournament),
+//! [`terminate_arena_tournament`](LichessApi::terminate_arena_tournament), and
+//! [`update_arena_team_battle`](LichessApi::update_arena_team_battle)) requires
+//! a bearer token with the `tournament:write` scope; reading tournament info,
+//! results, team standings, and games is public and needs no token.
+
 use futures::stream::StreamExt;
 
 use crate::client::LichessApi;
diff --git a/lib/src/api/board.rs b/lib/src/api/board.rs
index cccc128..39a65e8 100644
--- a/lib/src/api/board.rs
+++ b/lib/src/api/board.rs
@@ -1,3 +1,16 @@
+//! The Board API: play games as if from a physical board or other external
+//! device, rather than the normal Lichess UI.
+//!
+//! Covers making moves, offering or claiming draws, resigning, berserking,
+//! seeking a game, and chatting, plus the event and game-state streams needed
+//! to drive a game in real time. All methods here require a bearer token with
+//! the `board:play` scope.
+//!
+//! [`LichessApi::board_stream_incoming_events`] and
+//! [`LichessApi::board_stream_board_state`] return streams of events rather
+//! than a single response: keep the connection open and read from the stream
+//! as moves and other updates happen, rather than polling.
+
 use futures::stream::StreamExt;
 
 use crate::client::LichessApi;
diff --git a/lib/src/api/bot.rs b/lib/src/api/bot.rs
index 6b05275..d718fc7 100644
--- a/lib/src/api/bot.rs
+++ b/lib/src/api/bot.rs
@@ -1,3 +1,17 @@
+//! Play games as a Lichess [Bot account](https://lichess.org/api#tag/Bot).
+//!
+//! A regular player account must first be upgraded to a Bot account with
+//! [`bot_upgrade_account`](crate::client::LichessApi::bot_upgrade_account) —
+//! irreversible, and only possible before the account has played any game.
+//! Once upgraded, a bot streams incoming challenges and game state and reacts
+//! to them (moves, resignations, draw/takeback offers, chat) rather than
+//! using the normal web UI; see the [board](crate::api::board) module for the
+//! equivalent flow for human-driven clients.
+//!
+//! All methods here require a bearer token with the `bot:play` scope, except
+//! [`bot_get_online`](crate::client::LichessApi::bot_get_online), which is
+//! public.
+
 use futures::stream::StreamExt;
 
 use crate::client::LichessApi;
diff --git a/lib/src/api/broadcasts.rs b/lib/src/api/broadcasts.rs
index 3ca2109..982304d 100644
--- a/lib/src/api/broadcasts.rs
+++ b/lib/src/api/broadcasts.rs
@@ -1,3 +1,23 @@
+//! Broadcasts: Lichess's live relays of over-the-board tournaments, made up
+//! of one tournament containing one or more rounds, each fed by an external
+//! PGN source.
+//!
+//! Reading broadcasts (getting a tournament, round, player, team standings,
+//! listing/searching/browsing top and official broadcasts, and exporting PGN)
+//! is public and needs no token. Creating or managing your own broadcasts —
+//! [`create_broadcast_tournament`](LichessApi::create_broadcast_tournament),
+//! [`update_broadcast_tournament`](LichessApi::update_broadcast_tournament),
+//! [`create_broadcast_round`](LichessApi::create_broadcast_round),
+//! [`update_broadcast_round`](LichessApi::update_broadcast_round),
+//! [`push_broadcast_round_pgn`](LichessApi::push_broadcast_round_pgn), and
+//! [`reset_broadcast_round`](LichessApi::reset_broadcast_round) — requires a
+//! bearer token with the `study:write` scope.
+//!
+//! The `stream_*_pgn` methods keep the connection open and yield PGN as
+//! games progress, so they return a `Stream` rather than a single value;
+//! `export_*_pgn` methods stream the same way but close once the current
+//! games have been sent.
+
 use futures::stream::StreamExt;
 
 use crate::client::LichessApi;
diff --git a/lib/src/api/bulk_pairings.rs b/lib/src/api/bulk_pairings.rs
index cee3d41..16f45fb 100644
--- a/lib/src/api/bulk_pairings.rs
+++ b/lib/src/api/bulk_pairings.rs
@@ -1,3 +1,15 @@
+//! Bulk pairings let a broadcaster or tournament organizer schedule many
+//! games between paired players at once, up to a week in advance, rather than
+//! creating challenges one by one.
+//!
+//! Creating a pairing ([`LichessApi::create_bulk_pairing`]) requires an OAuth
+//! token with the `challenge:bulk` scope for the caller, plus a
+//! `challenge:write` token for each player being paired. Once created, a
+//! pairing can be looked up, canceled before it fires, or have its clocks
+//! started immediately instead of waiting for the scheduled time.
+//!
+//! [`LichessApi::create_bulk_pairing`]: crate::client::LichessApi::create_bulk_pairing
+
 use futures::stream::StreamExt;
 
 use crate::client::LichessApi;
diff --git a/lib/src/api/challenges.rs b/lib/src/api/challenges.rs
index 7465cd3..715a924 100644
--- a/lib/src/api/challenges.rs
+++ b/lib/src/api/challenges.rs
@@ -1,3 +1,14 @@
+//! Challenge other players, bots, or the Lichess AI to a game.
+//!
+//! Covers listing your incoming and outgoing challenges, creating, accepting,
+//! declining, and canceling a challenge, creating an open challenge anyone can
+//! join, and starting a game against the Lichess AI. Most operations require a
+//! bearer token with a `challenge:*` scope; open challenges and public reads
+//! are the exceptions. [`LichessApi::admin_challenge_tokens`] is restricted to
+//! Lichess administrators.
+//!
+//! Request/response types live in [`crate::model::challenges`].
+
 use crate::client::LichessApi;
 use crate::error::Result;
 use crate::model::challenges::*;
diff --git a/lib/src/api/external_engine.rs b/lib/src/api/external_engine.rs
index cd0677a..86dd168 100644
--- a/lib/src/api/external_engine.rs
+++ b/lib/src/api/external_engine.rs
@@ -1,3 +1,21 @@
+//! Register and use an external engine: a chess engine running on the user's
+//! own machine, made available for cloud analysis (e.g. from the Lichess
+//! analysis board) via a provider/secret handshake.
+//!
+//! Listing, creating, fetching, updating, and deleting engine registrations
+//! ([`list_external_engines`](LichessApi::list_external_engines),
+//! [`create_external_engine`](LichessApi::create_external_engine),
+//! [`get_external_engine`](LichessApi::get_external_engine),
+//! [`update_external_engine`](LichessApi::update_external_engine),
+//! [`delete_external_engine`](LichessApi::delete_external_engine)) require a
+//! bearer token with the `engine:read` or `engine:write` scope and talk to
+//! the regular Lichess host. Requesting and providing analysis
+//! ([`analyse_with_external_engine`](LichessApi::analyse_with_external_engine),
+//! [`acquire_analysis_request`](LichessApi::acquire_analysis_request),
+//! [`submit_analysis`](LichessApi::submit_analysis)) instead use the engine's
+//! own client/provider secrets for auth and are served from a separate host,
+//! [`Domain::Engine`](crate::model::Domain::Engine).
+
 use futures::stream::StreamExt;
 
 use crate::client::LichessApi;
diff --git a/lib/src/api/fide.rs b/lib/src/api/fide.rs
index 80d246c..0b4e381 100644
--- a/lib/src/api/fide.rs
+++ b/lib/src/api/fide.rs
@@ -1,3 +1,11 @@
+//! Look up FIDE-rated players and their rating history.
+//!
+//! Search by name with [`LichessApi::search_fide_player`], fetch a single
+//! [`Player`] by FIDE ID with [`LichessApi::get_fide_player`], and get their
+//! historical standard, rapid, and blitz ratings with
+//! [`LichessApi::get_fide_player_ratings`]. This data is public and does not
+//! require a token.
+
 use crate::client::LichessApi;
 use crate::error::Result;
 use crate::model::fide::*;
diff --git a/lib/src/api/games.rs b/lib/src/api/games.rs
index 9c24c14..a64f7cf 100644
--- a/lib/src/api/games.rs
+++ b/lib/src/api/games.rs
@@ -1,3 +1,17 @@
+//! Fetching, exporting, streaming, and importing games.
+//!
+//! Games can be exported as [`GameJson`] (single game or user history) or as
+//! raw PGN text, and requests for many games at once return a stream of
+//! results rather than a single value, since the response can be very large.
+//! [`stream_games_of_users`](LichessApi::stream_games_of_users) and
+//! [`stream_games_by_ids`](LichessApi::stream_games_by_ids) instead stream
+//! [`GameStream`] events for games as they start and finish, in real time.
+//!
+//! Most exports work without a token, but return more detail when
+//! authenticated, and downloading your own games is rate limited more
+//! generously than anonymous or third-party requests. Importing a game and
+//! bookmarking a game both require an authenticated user.
+
 use futures::stream::StreamExt;
 
 use crate::client::LichessApi;
diff --git a/lib/src/api/messaging.rs b/lib/src/api/messaging.rs
index ce31974..9857bec 100644
--- a/lib/src/api/messaging.rs
+++ b/lib/src/api/messaging.rs
@@ -1,3 +1,8 @@
+//! Sending private messages to other Lichess players.
+//!
+//! [`LichessApi::send_message`] posts a message to a user's inbox, on behalf
+//! of the authenticated account. It requires the `msg:write` OAuth scope.
+
 use crate::client::LichessApi;
 use crate::error::Result;
 use crate::model::messaging::*;
diff --git a/lib/src/api/oauth.rs b/lib/src/api/oauth.rs
index 9c5a5e6..d1487af 100644
--- a/lib/src/api/oauth.rs
+++ b/lib/src/api/oauth.rs
@@ -1,3 +1,12 @@
+//! Inspect and revoke OAuth2 tokens, and exchange an authorization code for
+//! an access token.
+//!
+//! This module covers the token-facing half of the OAuth2 PKCE flow. For
+//! generating the authorization URL and completing the flow end to end, see
+//! [`crate::model::oauth::authorize::AuthorizationUrl`] and
+//! [`crate::model::oauth::PendingAuthorization`], which both carry a full
+//! walkthrough.
+
 use crate::client::LichessApi;
 use crate::error::Result;
 use crate::model::oauth::*;
diff --git a/lib/src/api/openings.rs b/lib/src/api/openings.rs
index cf5395f..6f46d58 100644
--- a/lib/src/api/openings.rs
+++ b/lib/src/api/openings.rs
@@ -1,3 +1,12 @@
+//! Query move statistics for a position from the Opening Explorer: aggregated
+//! master games ([`openings_masters`](LichessApi::openings_masters)), rated
+//! Lichess games ([`openings_lichess`](LichessApi::openings_lichess)), or a
+//! specific player's games ([`openings_player`](LichessApi::openings_player)),
+//! plus fetching a masters game's PGN by ID
+//! ([`openings_otb`](LichessApi::openings_otb)). All of these are public and
+//! need no token, and are served from a separate host,
+//! [`Domain::Explorer`](crate::model::Domain::Explorer).
+
 use futures::stream::StreamExt;
 
 use crate::client::LichessApi;
diff --git a/lib/src/api/puzzles.rs b/lib/src/api/puzzles.rs
index 450b706..26d6d2f 100644
--- a/lib/src/api/puzzles.rs
+++ b/lib/src/api/puzzles.rs
@@ -1,3 +1,17 @@
+//! Fetching puzzles, tracking puzzle progress, and puzzle racing.
+//!
+//! Covers the daily puzzle, fetching a puzzle by ID or a random next puzzle,
+//! batches of puzzles for offline play, puzzle activity and the puzzle
+//! dashboard, puzzles to replay for a theme, and the Puzzle Storm dashboard.
+//! Also covers creating and joining a puzzle race and fetching its results.
+//!
+//! The daily puzzle, puzzle-by-ID, and Storm dashboard lookups are public.
+//! Everything else needs a bearer token: reading activity, the dashboard,
+//! replays, and fetching puzzles requires a `puzzle:read` scope, solving a
+//! batch requires `puzzle:write`, and creating a race requires `racer:write`.
+//!
+//! Request/response types live in [`crate::model::puzzles`].
+
 use futures::stream::StreamExt;
 
 use crate::client::LichessApi;
diff --git a/lib/src/api/relations.rs b/lib/src/api/relations.rs
index ee9257c..ce5f159 100644
--- a/lib/src/api/relations.rs
+++ b/lib/src/api/relations.rs
@@ -1,3 +1,10 @@
+//! Follow, unfollow, and block other Lichess players.
+//!
+//! [`LichessApi::get_following`] streams the users the authenticated account
+//! follows; the request/response types live in [`crate::model::relations`].
+//! All operations here act on behalf of the authenticated user and require
+//! the `follow:read` or `follow:write` OAuth scope, as appropriate.
+
 use futures::stream::StreamExt;
 
 use crate::client::LichessApi;
diff --git a/lib/src/api/simuls.rs b/lib/src/api/simuls.rs
index acde059..0dd81e9 100644
--- a/lib/src/api/simuls.rs
+++ b/lib/src/api/simuls.rs
@@ -1,3 +1,11 @@
+//! Simultaneous exhibitions: one host playing many opponents at once.
+//!
+//! Lists recently created, started, and finished simuls, matching what's shown
+//! on <https://lichess.org/simul>. The created/finished lists are not
+//! exhaustive — only simuls with a strong enough host are included. This
+//! endpoint is public, but when called with a bearer token the pending list is
+//! populated with the caller's own created-but-unstarted simuls.
+
 use crate::client::LichessApi;
 use crate::error::Result;
 use crate::model::simuls::*;
diff --git a/lib/src/api/studies.rs b/lib/src/api/studies.rs
index 117359b..57306cc 100644
--- a/lib/src/api/studies.rs
+++ b/lib/src/api/studies.rs
@@ -1,3 +1,19 @@
+//! Create, import into, and export [studies](https://lichess.org/study) and
+//! their chapters.
+//!
+//! Studies can be exported as PGN, either a single chapter, a whole study, or
+//! every study belonging to a user; [`update_study_chapter_moves`] and
+//! [`update_study_chapter_tags`] edit an existing chapter's move tree and PGN
+//! tags in place. See [`model::studies`] for the request/response types.
+//!
+//! Reading a study you don't own only returns it if it's public. Pass a
+//! bearer token to also see your own private and unlisted studies; writes
+//! (creating, importing, deleting, or editing a chapter) always require one.
+//!
+//! [`update_study_chapter_moves`]: LichessApi::update_study_chapter_moves
+//! [`update_study_chapter_tags`]: LichessApi::update_study_chapter_tags
+//! [`model::studies`]: crate::model::studies
+
 use futures::stream::StreamExt;
 
 use crate::client::LichessApi;
diff --git a/lib/src/api/swiss_tournaments.rs b/lib/src/api/swiss_tournaments.rs
index d129fff..65c5f78 100644
--- a/lib/src/api/swiss_tournaments.rs
+++ b/lib/src/api/swiss_tournaments.rs
@@ -1,3 +1,13 @@
+//! Swiss-system tournaments.
+//!
+//! Unlike arena tournaments, Swiss tournaments are always organized by a team
+//! ([`LichessApi::create_swiss_tournament`] takes a `team_id`), run over a
+//! fixed number of rounds, and pair players based on score each round rather
+//! than continuously. Most write operations (creating, updating, joining,
+//! scheduling the next round, terminating, withdrawing) require the
+//! `tournament:write` scope; reading tournament info, results, games, and the
+//! TRF export are public.
+
 use futures::stream::StreamExt;
 
 use crate::client::LichessApi;
diff --git a/lib/src/api/tablebase.rs b/lib/src/api/tablebase.rs
index 9fe3630..9837df9 100644
--- a/lib/src/api/tablebase.rs
+++ b/lib/src/api/tablebase.rs
@@ -1,3 +1,13 @@
+//! Look up Syzygy endgame tablebase results for positions with few pieces
+//! remaining, one method per variant: standard chess
+//! ([`lookup_standard`](LichessApi::lookup_standard)), antichess
+//! ([`lookup_antichess`](LichessApi::lookup_antichess)), and atomic chess
+//! ([`lookup_atomic`](LichessApi::lookup_atomic)). Each returns the win/loss/draw
+//! category and, where known, distance-to-zero and distance-to-mate for the
+//! position and for every legal move. These endpoints are public and need no
+//! token, and are served from a separate host,
+//! [`Domain::Tablebase`](crate::model::Domain::Tablebase).
+
 use crate::client::LichessApi;
 use crate::error::Result;
 use crate::model::tablebase::*;
diff --git a/lib/src/api/teams.rs b/lib/src/api/teams.rs
index 7ca4734..9077444 100644
--- a/lib/src/api/teams.rs
+++ b/lib/src/api/teams.rs
@@ -1,3 +1,13 @@
+//! Team info, membership, and team-only tournament listings.
+//!
+//! Lookups such as [`LichessApi::get_team`], [`LichessApi::search_teams`],
+//! [`LichessApi::get_team_members`], and the team's arena/swiss tournament
+//! listings are public. Joining and quitting a team need a token with
+//! `team:write`; reading your team updates needs `team:read`. Everything
+//! else here — viewing join requests, accepting or declining them, kicking a
+//! member, and sending a team update — acts on a team you lead and needs a
+//! token with `team:lead`.
+
 use futures::stream::StreamExt;
 
 use crate::client::LichessApi;
diff --git a/lib/src/api/tv.rs b/lib/src/api/tv.rs
index 2076487..d78b609 100644
--- a/lib/src/api/tv.rs
+++ b/lib/src/api/tv.rs
@@ -1,3 +1,15 @@
+//! Lichess TV: the best ongoing games, overall and per channel (speed
+//! variants like bullet or blitz, plus computer and bot games).
+//!
+//! [`LichessApi::tv_channels`] gives current champions for every channel in
+//! one call, and [`LichessApi::tv_channel_games`] lists ongoing games for a
+//! single channel. [`LichessApi::tv_stream_current`] and
+//! [`LichessApi::tv_stream_channel_current`] instead follow the featured game
+//! (overall, or for one channel) as it changes, streaming positions and moves
+//! rather than returning a single value.
+//!
+//! All of these endpoints are public and need no bearer token.
+
 use futures::stream::StreamExt;
 
 use crate::client::LichessApi;
diff --git a/lib/src/api/users.rs b/lib/src/api/users.rs
index de96673..1630d63 100644
--- a/lib/src/api/users.rs
+++ b/lib/src/api/users.rs
@@ -1,3 +1,19 @@
+//! Public user profiles, ratings, and activity.
+//!
+//! Covers looking up one or many users ([`LichessApi::get_public_user_data`],
+//! [`LichessApi::get_users_by_id`], [`LichessApi::autocomplete_users`]),
+//! ratings and leaderboards ([`LichessApi::get_one_leaderboard`],
+//! [`LichessApi::get_all_top_10`], [`LichessApi::get_rating_history`],
+//! [`LichessApi::get_user_performance_statistics`],
+//! [`LichessApi::get_crosstable`]), online/playing/streaming status
+//! ([`LichessApi::get_status_of_users`], [`LichessApi::get_live_streamers`]),
+//! and a user's activity feed ([`LichessApi::get_user_activity`]).
+//!
+//! Most of these endpoints are public and work without a token. The private
+//! note endpoints ([`LichessApi::add_note_to_user`],
+//! [`LichessApi::get_user_notes`]) are the exception — they read and write
+//! notes that only your own account can see, so they require a token.
+
 use crate::client::LichessApi;
 use crate::error::Result;
 use crate::model::users::*;