diff --git a/README.md b/README.md
index 278ccad7d4..37379588ad 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,44 @@ However, other projects are also encouraged to use Moby as an upstream, and to r
 The Moby project is not intended as a location for support or feature requests for Docker products, but as a place for contributors to work on open source code, fix bugs, and make the code more useful.
 The releases are supported by the maintainers, community and users, on a best efforts basis only. For customers who want enterprise or commercial support, [Docker Desktop](https://www.docker.com/products/docker-desktop/) and [Mirantis Container Runtime](https://www.mirantis.com/software/mirantis-container-runtime/) are the appropriate products for these use cases.
 
+## Go modules
+
+> [!IMPORTANT]
+> Starting with Docker v29 (released November 2025), the Go module `github.com/docker/docker` is **deprecated** and won't be updated.
+
+The supported public Go modules are:
+
+| Module | Description |
+|---|---|
+| [`github.com/moby/moby/client`](client/) | Go client for the Docker Engine API |
+| [`github.com/moby/moby/api`](api/) | API types shared between client and server |
+
+The root module `github.com/moby/moby/v2` is the codebase for building container engines based on Moby (such as Docker Engine).
+It produces binaries only - it is **not intended to be imported as a Go library** and has no API stability guarantees.
+
+### Release tags
+
+Docker Engine releases are tagged with a **`docker-`** prefix (e.g. `docker-v29.0.0` for Docker Engine 29.0.0).
+
+These tags are only used to build the Docker Engine binary from the root module - they must not be consumed via `go get`.
+
+The `client` and `api` modules are versioned independently with their own tags (e.g. `client/v1.x.x`, `api/v1.x.x`).
+
+### Migrating from `github.com/docker/docker`
+
+Replace the old import paths:
+
+```diff
+- import "github.com/docker/docker/client"
++ import "github.com/moby/moby/client"
+
+- import "github.com/docker/docker/api/types"
++ import "github.com/moby/moby/api/types"
+```
+
+Note that v29 includes many breaking API changes (option structs, renamed methods, moved types).
+See the [v29.0.0 release notes](https://github.com/moby/moby/releases/tag/docker-v29.0.0) for the full list of Go SDK changes.
+
 -----
 
 Legal