diff --git a/API.md b/API.md
index 6122db2..c76bbfd 100644
--- a/API.md
+++ b/API.md
@@ -150,6 +150,8 @@ The processor architecture to target when building.
     - Please note: On M1 Macs, unless an arm64 version of brew is used to install nodejs, the version installed will be an `x64` version run through Rosetta, and will result in an `x64` app being generated. If this is not desired, either specify `-a arm64` to build for M1, or re-install node with an arm64 version of brew. See https://github.com/nativefier/nativefier/issues/1089
 - Can be overridden by specifying one of: `ia32`, `x64`, `armv7l`, `arm64`.
 
+Note: careful to not conflate _platform_ with _architecture_. If you want for example a Linux or Mac build, it's `--platform` you are looking for. See its documentation for details.
+
 #### [conceal]
 
 ```
@@ -215,7 +217,9 @@ Specifies if the destination directory should be not overwritten, defaults to fa
       (See https://nodejs.org/api/os.html#os_os_platform)
 - Can be overwritten by specifying either `linux`, `windows`, `osx` or `mas` for a Mac App Store specific build.
 
-The alternative values `win32` (for Windows) or `darwin`, `mac` (for macOS) can also be used.
+Note: careful to not conflate _platform_ with _architecture_. If you want for example a 32bit build or an ARM build, it's `--arch` you are looking for. See its documentation for details.
+
+For backwards compatibility, less-clear values `win32` (for Windows) and `darwin`, `mac` (for macOS) are supported.
 
 #### [portable]