Improve bazel RBE documentation

tools/remote_build/README.md

@@ -17,30 +17,55 @@ and tests run by Kokoro CI.
 
 ## Running remote build manually from dev workstation
 
-Run from repository root (opt, dbg):
+IMPORTANT: The OS from which you run the bazel command needs to always match your desired build & execution platform. If you want to run tests on linux, you need to run bazel from a linux machine, to execute tests on windows you need to be on windows etc. If you don't follow this guideline, the build might still appear like it's working, but you'll get nonsensical results (e.g. will be test configured as if on mac, but actually running on linux).
+
+### Linux
+
+For `opt` or `dbg` run this command:
 ```
 # manual run of bazel tests remotely on Foundry
 bazel --bazelrc=tools/remote_build/manual.bazelrc test --config=opt //test/...
 ```
 
-Sanitizer runs (asan, msan, tsan, ubsan):
+This also works for sanitizer runs (`asan`, `msan`, `tsan`, `ubsan`):
 ```
 # manual run of bazel tests remotely on Foundry with given sanitizer
 bazel --bazelrc=tools/remote_build/manual.bazelrc test --config=asan //test/...
 ```
 
-Run on Windows MSVC:
+### Windows
+
 ```
 # manual run of bazel tests remotely on RBE Windows (must be run from Windows machine)
 bazel --bazelrc=tools/remote_build/windows.bazelrc test --config=windows_opt //test/...
 ```
 
-Run on MacOS (experimental for now):
+NOTE: Unlike on Linux and Mac, the bazel version won't get autoselected for you,
+so check that you're using the [right bazel version](https://github.com/grpc/grpc/blob/master/tools/bazel).
+
+### MacOS
+
+There is no such thing as Mac RBE cluster, so a real remote build on Macs is currently impossible.
+The following setup will build and run test on you local mac machine, but will give
+you the RBE-like look & feel (e.g. a results link will be generated and some extra configuration will
+be used).
+
 ```
 # manual run of bazel tests on Mac (must be run from Mac machine)
 # NOTE: it's not really a "remote execution", but uploads results to ResultStore
 bazel --bazelrc=tools/remote_build/mac.bazelrc test --config=opt //test/...
 ```
 
+NOTE: Because this is essentially a local run, you'll need to run start port server first (`tools/run_tests/start_port_server.py`)
+
+## Running local builds with bazel
+
+On all platforms, you can generally still use bazel builds & tests locally without any extra settings, but you might need to 
+start port server first (`tools/run_tests/start_port_server.py`) to be able to run the tests locally.
+
+E.g.: `bazel test --config=opt //test/...`
+
+## Bazel command line options
+
 Available command line options can be found in
 [Bazel command line reference](https://docs.bazel.build/versions/master/command-line-reference.html)