diff --git a/apps/docs/environments.mdx b/apps/docs/environments.mdx
index 184c5de22..e6272e8c5 100644
--- a/apps/docs/environments.mdx
+++ b/apps/docs/environments.mdx
@@ -41,7 +41,8 @@ An environment can combine repositories from different source-control
 providers, such as GitHub and GitLab. Each provider must have working
 credentials in the deployment or the task cannot prepare the complete
 workspace. Repositories connected through GitHub must also belong to the same
-GitHub App installation.
+GitHub App installation. Repository full names must be unique within the
+environment, including across source-control connections.
 
 The setup task is meant to produce a working environment Roomote can reuse. If
 it cannot finish, adjust the input and try again from
diff --git a/apps/docs/personal-settings.mdx b/apps/docs/personal-settings.mdx
index 66195d33d..8af762abb 100644
--- a/apps/docs/personal-settings.mdx
+++ b/apps/docs/personal-settings.mdx
@@ -61,6 +61,8 @@ they need to use it.
 Personal Settings also include app preferences such as:
 
 - **Color Theme** for light, dark, or system-defined appearance
+- **Mind Reader Mode** to expand LLM thoughts by default in task conversations;
+  you can still collapse or expand individual thought messages
 - **Narration Mode** for a more streamlined task conversation view
 
 Most teammates only need profile, linked accounts, and theme settings.
diff --git a/apps/docs/self-hosting.mdx b/apps/docs/self-hosting.mdx
index ccea1110b..0acd956fe 100644
--- a/apps/docs/self-hosting.mdx
+++ b/apps/docs/self-hosting.mdx
@@ -135,6 +135,12 @@ empty PostgreSQL/MinIO/Redis volumes, and starts the recorded Roomote release.
   retained tag, and restoring the pre-upgrade bundle is the last-resort path
   that also rewinds data.
 
+Use `roomote upgrade` instead of updating application image references alone.
+The command refreshes the release's Compose and Caddy configuration together;
+mixing newer application images with an older Caddyfile can leave routes used
+by the new controller unavailable until the deployment configuration is also
+updated.
+
 The supported rollback target is the release immediately before the current
 one. Check the running application version and applied schema migration at any
 time under **Settings → Deployment → Diagnostics**; both are also recorded in
diff --git a/apps/docs/users.mdx b/apps/docs/users.mdx
index 64d4323e9..0a91fa485 100644
--- a/apps/docs/users.mdx
+++ b/apps/docs/users.mdx
@@ -79,12 +79,14 @@ expiry date. Purchased keys are issued annually and can be refreshed from the
 Roomote Cloud portal while the subscription is active. Replace the key in
 Settings or `R_LICENSE_KEY` after refreshing it.
 
-Keys are signature-verified locally, then activated with Roomote Cloud for the
-deployment's stable installation ID. A paid seat limit remains active while
-the Cloud activation lease is current (up to 72 hours); without it, the
-deployment uses the free-seat limit. Roomote Cloud records the current user
-count and short-lived peaks for subscription billing, independently of
-anonymous analytics. License usage is not sent to the Ping analytics service.
+Keys are signature-verified locally. On self-hosted deployments, they are then
+activated with Roomote Cloud for the deployment's stable installation ID. A
+paid seat limit remains active while the Cloud activation lease is current (up
+to 72 hours); without it, the deployment uses the free-seat limit. Roomote
+Cloud deployments use their provisioned valid license directly. Roomote Cloud
+records the current user count and short-lived peaks for subscription billing,
+independently of anonymous analytics. License usage is not sent to the Ping
+analytics service.
 
 Each license may be active on one deployment at a time. If you move a
 deployment, contact Roomote support to reset the existing activation before