Document Matrix authentication modes

Add a dedicated configuration/authentication doc covering password and access-token setup,
including environment-variable mappings and token-generation example.

Link to it from configuration docs and align the sample config wording with Matrix Authentication Service/OIDC terminology.

docs/configuration/README.md

@@ -22,6 +22,8 @@ You can see the list of supported environment variables in the [🦀 src/entity/
 > [!WARNING]
 > The static configuration contains an `initial_global_config` key, which is used to populate the bot's global configuration (stored as [dynamic configuration](#dynamic-configuration)) the first time the bot starts. Modifying this subsequently will not have any effect. After initial global configuration creation, it's expected to be managed dynamically via chat commands.
 
+For Matrix-account authentication setup, see [🔐 Authentication](./authentication.md).
+
 
 ### Dynamic configuration
 

docs/configuration/authentication.md

@@ -0,0 +1,23 @@
+## 🔐 Authentication
+
+baibot supports 2 authentication modes for the Matrix account (`user.*` keys in config).
+
+Set **exactly one** mode. If both are set (or neither is set), startup validation fails.
+
+### Password authentication
+
+- Config key: `user.password`
+- Environment variable: `BAIBOT_USER_PASSWORD`
+
+### Access token authentication
+
+- Config keys: `user.access_token` + `user.device_id`
+- Environment variables: `BAIBOT_USER_ACCESS_TOKEN` + `BAIBOT_USER_DEVICE_ID`
+
+Access-token authentication is useful for OIDC-enabled homeservers (e.g. those using [Matrix Authentication Service](https://github.com/element-hq/matrix-authentication-service)).
+
+Example token-generation command:
+
+```sh
+mas-cli manage issue-compatibility-token <username> [device_id]
+```

etc/app/config.yml.dist

@@ -11,7 +11,7 @@ user:
   # Password-based login (traditional homeservers):
   password: baibot
 
-  # Access token login (for MAS/OIDC-enabled homeservers):
+  # Access token login (for Matrix Authentication Service/OIDC-enabled homeservers):
   # Generate a token via: mas-cli manage issue-compatibility-token <username> [device_id]
   # access_token: null
   # device_id: null