diff --git a/packages/bruno-cli/docker/README.md b/packages/bruno-cli/docker/README.md
index b9194b3d3..1c2081951 100644
--- a/packages/bruno-cli/docker/README.md
+++ b/packages/bruno-cli/docker/README.md
@@ -2,22 +2,6 @@
 
 Official Docker images for [Bruno CLI](https://www.usebruno.com), enabling container-native API collection runs in CI/CD pipelines and local environments without requiring Node.js or npm on the host. See the [Bruno CLI docs](https://docs.usebruno.com/bru-cli/overview) for CLI usage.
 
-## Folder structure
-
-```text
-docker/
-  ├── README.md           ← you are here
-  └── images/
-      ├── alpine/
-      │   ├── Dockerfile  ← Alpine Linux variant (smallest, ~141MB)
-      │   └── README.md
-      └── debian/
-          ├── Dockerfile  ← Debian slim variant (~162MB, glibc support)
-          └── README.md
-```
-
----
-
 ## Registries
 
 ```bash
@@ -31,8 +15,8 @@ docker pull ghcr.io/usebruno/cli:latest
 
 | Variant | Base image | Details |
 |---------|-----------|---------|
-| **Alpine** (default) | `node:22-alpine` | [→ Alpine README](./images/alpine/README.md) |
-| **Debian** | `node:22-slim` | [→ Debian README](./images/debian/README.md) |
+| **Alpine** (default) | `node:22-alpine` | [→ Alpine README](https://github.com/usebruno/bruno/blob/main/packages/bruno-cli/docker/images/alpine/README.md) |
+| **Debian** | `node:22-slim` | [→ Debian README](https://github.com/usebruno/bruno/blob/main/packages/bruno-cli/docker/images/debian/README.md) |
 
 ### Quick choice
 
@@ -94,7 +78,7 @@ docker pull usebruno/cli:3.3.0-debian
 
 ---
 
-### Step 2 — Check it works
+#### Check it works
 
 ```bash
 docker run --rm usebruno/cli --version
@@ -102,13 +86,12 @@ docker run --rm usebruno/cli --version
 
 ---
 
-### Step 3 — Run your collection
+### Step 2 — Run your collection
 
 > These examples assume you are running `docker` from your Bruno collection directory. Mount that directory to `/bruno` and pass `bru` arguments directly after the image name. If your collection lives elsewhere on disk, see the path-based examples further down.
-> **Cross-platform note:** the examples below use `$(pwd)` which works in Bash / Zsh / Git Bash / WSL.
-> On Windows native shells, substitute `$(pwd)` with:
-> - PowerShell: `${PWD}`
-> - CMD: `%cd%`
+
+> **Cross-platform note:** the examples below use `$(pwd)` which works in Bash / Zsh / Git Bash / WSL. On Windows native shells, substitute `$(pwd)` with `${PWD}` (PowerShell) or `%cd%` (CMD).
+
 > **Adding `bru` options:** The examples below show docker-specific flags. For all `bru run` options — recurse (`-r`), environments, variables, reporters, bail, and more — see the [Bruno CLI docs](https://docs.usebruno.com/bru-cli/overview).
 
 ```bash
@@ -144,72 +127,13 @@ docker run -v /path/to/your/collection:/bruno usebruno/cli run ./auth/login.bru
 ```
 
 > **Note on `--rm`:** Examples below include `--rm`. Docker keeps stopped containers around after they exit, which lets you `docker logs` or `docker inspect` them later for debugging. If you'd rather have Docker auto-delete the container as soon as `bru` finishes — useful for CI runs or to avoid `docker ps -a` filling up with stale entries — append `--rm` to any `docker run` (or `docker compose run`) command:
->
-> ```bash
-> docker run --rm -v $(pwd):/bruno usebruno/cli run
-> ```
->
+
+```bash
+docker run --rm -v $(pwd):/bruno usebruno/cli run
+```
+
 > It's purely a cleanup convenience; it doesn't affect the image, mounts, stdout output, or exit code.
 
----
-
-### Step 4 — Choose your environment
-
-```bash
-docker run -v $(pwd):/bruno usebruno/cli run --env local
-docker run -v $(pwd):/bruno usebruno/cli run --env staging
-docker run -v $(pwd):/bruno usebruno/cli run --env production
-```
-
----
-
-### Step 5 — Pin the right version
-
-```bash
-# exact version — safest for production, no surprise updates
-docker run -v $(pwd):/bruno usebruno/cli:3.3.0 run
-
-# major.minor — gets patch fixes automatically
-docker run -v $(pwd):/bruno usebruno/cli:3.3 run
-
-# latest — always newest, not recommended for production CI
-docker run -v $(pwd):/bruno usebruno/cli:latest run
-```
-
----
-
-### Step 6 — Choose alpine or debian
-
-```bash
-# alpine (default) — use this for most cases
-docker run -v $(pwd):/bruno usebruno/cli:3.3.0 run
-
-# alpine — explicitly use the alpine-based image variant
-docker run -v $(pwd):/bruno usebruno/cli:3.3.0-alpine run
-
-# debian — use if you hit SSL, glibc, or native module issues
-docker run -v $(pwd):/bruno usebruno/cli:3.3.0-debian run
-```
-
----
-
-## Usage by variant
-
-### Alpine variant
-
-See [Alpine README](./images/alpine/README.md) for:
-- Building the Alpine image
-- When to use Alpine
-- Variant-specific options
-
-### Debian variant
-
-See [Debian README](./images/debian/README.md) for:
-- Building the Debian image
-- When to use Debian
-- Compatibility notes
-
----
 
 ## CI/CD integration
 
@@ -284,7 +208,7 @@ The `/path/to/reports:/reports` mount catches the JSON, JUnit XML, and HTML repo
 
 ### Try it from this repo
 
-A ready-to-run `docker-compose.yml` lives in this repo at [`packages/bruno-tests/docker-compose.yml`](../../bruno-tests/docker-compose.yml). It mounts the sibling `collection/` directory into the container, runs the `echo` folder against the `Prod` environment, and writes JSON, JUnit XML, and HTML reports into `packages/bruno-tests/reports/`:
+A ready-to-run `docker-compose.yml` lives in this repo at [`packages/bruno-tests/docker-compose.yml`](https://github.com/usebruno/bruno/blob/main/packages/bruno-tests/docker-compose.yml). It mounts the sibling `collection/` directory into the container, runs the `echo` folder against the `Prod` environment, and writes JSON, JUnit XML, and HTML reports into `packages/bruno-tests/reports/`:
 
 ```bash
 cd packages/bruno-tests