@@ -2,6 +2,9 @@
 
 This file provides context for AI coding agents working in this repository.
 
+Read [CONTRIBUTING.md](CONTRIBUTING.md) first: it carries the rules a contribution is judged against and the release procedure, and it applies to agents exactly as it does to people.
+This file covers the mechanics of the codebase and does not repeat them.
+
 ## Project Overview
 
 **spotify-web-api-java** is a Java wrapper library for the [Spotify Web API](https://developer.spotify.com/documentation/web-api/). It provides typed request builders and model objects for all Spotify API endpoints.
@@ -98,7 +101,8 @@ It checks that every `SpotifyApi` method has an example, that example file names
 
 ### Releasing
 
-The version lives in `pom.xml`, `README.md` and `examples/pom.xml`, and `ci/check-docs.py` fails if the examples fall behind the library.
+See the release workflow in [CONTRIBUTING.md](CONTRIBUTING.md#release-workflow-maintainers-only).
+Note that the version lives in three files, and `ci/check-docs.py` fails when they disagree.
 
 ### Renaming or removing public API
 
 
@@ -15,8 +15,9 @@ especially because currently only voluntary maintainers and contributors take ca
 At the same time it is strongly recommended to follow certain guidelines when making contributions to open source
 projects like this one. They ensure fast processing times and stable releases.
 
-It is mandatory to stay as close to the
-[Web API Endpoint Reference](https://developer.spotify.com/web-api/endpoint-reference/) as possible. Before changing
+It is mandatory to stay as close to Spotify's own API description as possible.
+A copy of it is vendored at `spec/openapi.yaml`, and that copy is what `ci/check-docs.py` checks a request's verb, path and deprecation against, so it is the first place to look rather than the
+[Web API Endpoint Reference](https://developer.spotify.com/documentation/web-api/reference/). Before changing
 anything in the code base, make sure to take one  - or more - looks into related files/classes and [the project's
 documentation](https://spotify-web-api-java.github.io/spotify-web-api-java/apidocs/). The whole code follows simple
 and consistent code conventions for naming rules and alike. Those should be easy to grasp by comparing to the online
@@ -37,10 +38,17 @@ A complete contribution includes the following features:
 Make sure that your contribution embeds well into the already existing code. For example, the unified folder/package
 structure must be used wherever possible.
 
+The library is an explicit Java module, so a class in a **new** package is unreachable for callers until that package is added to `exports` in `src/main/java/module-info.java`.
+The examples are compiled as a separate module against the built library, which is what turns a forgotten `exports` into a build failure here rather than in someone else's project.
+
 ### Documentation
-Document your source code! It's easy because one can most likely just stick to the online API reference. This is a
-requirement. Not because your contributed source code is unreadable. Instead, the aim is to keep the Javadoc complete
-and - accompanying this - to keep this project as accessible as possible to developers like yourself.
+Document what a reader of the published API reference needs: types, getters and the methods on `SpotifyApi`.
+Model builder setters and default constructors deliberately carry no prose, because restating the signature adds nothing that the matching getter does not already say, so Javadoc runs with `doclint` set to `all,-missing`.
+
+What is still enforced is that every reference resolves: a dead `{@link}` fails the build, and the Javadoc step runs in CI before a tag can publish anything.
+
+A new endpoint also needs an example under `examples/` and a link from the index in `README.md`, and a renamed or removed public name needs an entry in `MIGRATION.md`.
+`ci/check-docs.py` fails without them.
 
 ### Test Coverage
 Unit tests help to assure that functionality works. Due to that contribution approval requires them to be included for
@@ -49,40 +57,38 @@ none below. For arrays the length is to be checked.
 
 #### Fixtures
 A unit test builds upon JSON fixtures. For code changes, fixture files must only be updated when...
-- the online examples change
-- the online examples are outdated, compared against the reference description and/or the
-[Web API Object Model](https://developer.spotify.com/web-api/object-model/).
+- the responses Spotify actually returns change
+- a fixture is outdated, compared against the schema for that response in `spec/openapi.yaml`
 
 ## Contribution Flow
 1. Create a fork from this repository
 2. Create a branch in your fork in which you develop your contribution (one branch per feature/fix)
 3. Create meaningful and well-separated commits
 4. Make sure your contribution follows the contribution guidelines above
-5. Create a pull request from your feature branch to the correct branch of this project
+5. Create a pull request against the branch the change belongs on:
+   - `main` carries the current stable line, and is where fixes and dependency updates for the released version go
+   - `beta` accumulates the next pre-release, and is where anything that changes the public API belongs, breaking changes and new endpoints alike
+
+   Nothing reaches `main` from `beta` except through the release pull request, so a change that cannot ship in a patch release belongs on `beta` even when it looks small. Ask in the issue if you are unsure.
 
 ## Release Workflow (Maintainers Only)
 
 Follow these steps to publish a new release:
 
 ### 1. Update version numbers
 
-Update the version string in **three places**:
+The version lives in **three files**:
+
+- **`pom.xml`** — the `<version>` element near the top
+- **`README.md`** — two occurrences, the Maven `<version>` snippet and the Gradle `implementation` line
+- **`examples/pom.xml`** — the examples are a separate Maven project, so they carry their own copy
 
-- **`pom.xml`** — the `<version>` element near the top of the file:
-  ```xml
-  <version>X.Y.Z</version>
-  ```
-- **`README.md`** — two occurrences: the Maven `<version>` snippet and the Gradle `implementation` line:
-  ```xml
-  <version>X.Y.Z</version>
-  ```
-  ```groovy
-  implementation 'se.michaelthelin.spotify:spotify-web-api-java:X.Y.Z'
-  ```
+`ci/check-docs.py` fails the build when `examples/pom.xml` falls behind `pom.xml`, so a missed bump is caught rather than shipped.
 
 ### 2. Regenerate Javadoc
 
-The `apidocs/` directory at the project root is the published API documentation and must be regenerated on every release. The `release` Maven profile is configured to delete `apidocs/` and regenerate it.
+The `apidocs/` directory at the project root is the published API documentation and must be regenerated on every release.
+The `release` profile deletes and regenerates it, and because the library is an explicit module, Javadoc writes the pages under `apidocs/se.michaelthelin.spotify/`.
 
 Run:
 ```bash
@@ -96,23 +102,23 @@ This will:
 
 ### 3. Commit and tag
 
-Commit all changed files (version bumps + regenerated `apidocs/`):
+Pre-releases are cut from `beta` and tagged `X.Y.Z-RCN`; stable releases are cut from `main` and tagged `X.Y.Z`. CI reacts to both patterns and to nothing else.
+
+Commit the version bumps together with the regenerated documentation:
 ```bash
-git add pom.xml README.md apidocs/
+git add pom.xml README.md examples/pom.xml apidocs/
 git commit -m "X.Y.Z"
 ```
 
-Create a lightweight Git tag matching the version exactly (the CI tag pattern is `X.Y.Z` or `X.Y.Z-RCN`):
+Create a lightweight tag matching the version exactly, and push the commit before the tag so CI validates the code before it publishes anything:
 ```bash
 git tag X.Y.Z
-```
-
-Push the commit and tag:
-```bash
 git push origin <branch>
 git push origin X.Y.Z
 ```
 
+A pre-release line becomes stable by merging `beta` into `main` through the release pull request and tagging there. That merge is also what publishes the documentation, since GitHub Pages serves from `main`.
+
 ### 4. Automated release via CI
 
 Pushing a tag triggers the GitHub Actions CI workflow (`.github/workflows/ci.yml`), which automatically: