diff --git a/README.md b/README.md
index 1f4918bb7..820fe37ff 100644
--- a/README.md
+++ b/README.md
@@ -79,7 +79,7 @@ b2 version                Print the version number of this tool.
 
 The environment variable `B2_ACCOUNT_INFO` specifies the SQLite
 file to use for caching authentication information.
-The default file to use is: `~/.b2_account_info`.
+Run `b2 account get` to see the file currently in use; its location depends on your profile and environment (see `b2 --help` for the resolution rules).
 
 To get more details on a specific command use `b2 <command> --help`.
 
@@ -165,3 +165,4 @@ Please refer to the [changelog](CHANGELOG.md).
 ## Developer Info
 
 Please see our [contributing guidelines](CONTRIBUTING.md).
+See [Authorization realm](doc/authorization_realm.md) for `B2_ENVIRONMENT` and related development flags.
diff --git a/changelog.d/1162.doc.md b/changelog.d/1162.doc.md
new file mode 100644
index 000000000..ae9c0c9b3
--- /dev/null
+++ b/changelog.d/1162.doc.md
@@ -0,0 +1 @@
+Document the ``B2_ENVIRONMENT`` authorization-realm environment variable.
diff --git a/doc/authorization_realm.md b/doc/authorization_realm.md
new file mode 100644
index 000000000..0616b7206
--- /dev/null
+++ b/doc/authorization_realm.md
@@ -0,0 +1,12 @@
+# Authorization realm (advanced / Backblaze development)
+
+By default, the B2 CLI talks to the production Backblaze B2 authorization realm. The controls
+below exist mainly for Backblaze development and testing.
+
+- `B2_ENVIRONMENT` selects the Backblaze authorization realm. Leave it unset for production, or
+  set it to a known realm name or a full B2 API endpoint URL.
+- The hidden flags `--environment <realm-or-url>`, `--dev`, and `--staging` provide equivalent
+  realm-selection controls for the same purpose.
+
+> **Note:** These controls select which Backblaze realm the CLI authenticates against. They are
+> not a way to namespace your own data or point the CLI at your own testing or staging server.