docs(dashboards): update to describe current behaviour of system

en/building-sites/client-proofing/dashboards/creating-a-widget.md

@@ -41,6 +41,12 @@ From here, click the "Place Widget" button above the Widgets grid on this page.
 
 Save your Dashboard.
 
+> **Note:** Adding a widget through the Dashboards manager page (as described above) places it on the dashboard **template**. If the dashboard is [customizable](building-sites/client-proofing/dashboards "Dashboards"), the widget will automatically appear for all existing users of that dashboard, as well as any new users.
+>
+> Adding a widget directly on the dashboard page (via the dashboard view itself) only adds it for the currently logged-in user. Other users will not see it unless it is also added to the template.
+>
+> On large sites with many users, adding a widget to the template will create a placement record for each user who already has a personal copy of that dashboard. Keep this in mind if performance is a concern.
+
 ### Viewing the Widget
 
 Now, if you click the "Dashboard" top menu item on the page, you can see your new dashboard widget in place!

en/building-sites/client-proofing/dashboards/index.md

@@ -4,8 +4,6 @@ _old_id: "90"
 _old_uri: "2.x/administering-your-site/dashboards"
 ---
 
-Dashboards are only available in MODX 2.2 or later.
-
 ## What are Dashboards?
 
 A Dashboard in MODX is the page that shows on initial loading of the MODX manager, or when clicking the "Dashboard" link in the top-left of the screen. Dashboards can contain an unlimited number of "widgets", which are boxes that show various content on the Dashboard. Widgets can be arranged in any order, and can be either a file, a MODX Snippet, or straight HTML.
@@ -14,6 +12,23 @@ Each User Group in MODX is assigned a Dashboard by default. This means that you
 
 If a User is part of two different groups, it will use the Dashboard of its Primary Group, which can be set in the User editing screen.
 
+## Customizable Dashboards
+
+Dashboards have a **Customizable** setting. When this is checked (the default), MODX clones the dashboard's widget layout for each user the first time they load the dashboard. This gives each user their own personal copy of the dashboard, which they can then rearrange, add widgets to, or remove widgets from without affecting other users.
+
+When **Customizable** is unchecked, all users share the same dashboard layout and cannot make personal changes to it.
+
+### How Template Changes Propagate
+
+The widget layout configured through the Dashboards manager page (Dashboard -> Dashboards -> Update Dashboard) serves as the **template** for a customizable dashboard. When you add or remove widgets from the template, those changes propagate to all existing users of that dashboard:
+
+- **Widgets added** to the template will automatically appear for all users who already have a personal copy of the dashboard.
+- **Widgets removed** from the template will be removed from all users' personal dashboards.
+
+Other personal customizations, such as widget order, are not affected by template changes.
+
+Changes made directly on a user's dashboard page (for example, removing a widget with the close button or adding a widget via the dashboard itself) only affect that individual user and do not change the template.
+
 ## Using Dashboards
 
 - [Managing Your Dashboard](building-sites/client-proofing/dashboards/managing "Managing Your Dashboard")

en/building-sites/client-proofing/dashboards/managing.md

@@ -14,6 +14,17 @@ You will see a name and description field, and below, a grid of Widgets assigned
 
 ![](dashboard-edit.png)
 
+## Template vs Personal Changes
+
+Changes made on this page update the dashboard **template**. For [customizable dashboards](building-sites/client-proofing/dashboards "Dashboards"), template changes are propagated to all users who have a personal copy of that dashboard:
+
+- When you **add a widget** here, it will appear on the dashboard for all existing users of that dashboard.
+- When you **remove a widget** here, it will be removed from all users' personal dashboards.
+
+This is different from changes made directly on the dashboard page itself (for example, using the close button on a widget or adding a widget from the dashboard view). Those changes only affect the currently logged-in user.
+
+If you want to enforce a widget change across all users, make it from this management page. If you only want to adjust your own dashboard, make the change directly on the dashboard page instead.
+
 ## See Also
 
 1. [Managing Your Dashboard](building-sites/client-proofing/dashboards/managing)

en/building-sites/client-proofing/dashboards/usergroups.md

@@ -4,14 +4,20 @@ _old_id: "25"
 _old_uri: "2.x/administering-your-site/dashboards/assigning-a-dashboard-to-a-user-group"
 ---
 
-This article describes how to edit a Dashboard, including on how to assign and arrange Widgets for that Dashboard.
+This article describes how to assign a Dashboard to a User Group.
 
 First off, find the User Group that you would like to assign the Dashboard to, and edit it. You can do so by "Menu" -> "Access Controls", then right-clicking on the group in the User Groups tree, and clicking "Update User Group".
 
 From there, you can simply click on the "Dashboard" dropdown, and select the Dashboard you want to assign to this User Group. All users in this group that have this group as their Primary Group will load that Dashboard instead of the Default now.
 
 ![](dashboard-assign.png)
 
+## Customizable Dashboards and User Groups
+
+If the assigned dashboard has the **Customizable** setting checked, MODX creates a personal copy of the dashboard's widget layout for each user the first time they log in. Users can then rearrange, add, or remove widgets on their own copy without affecting other group members.
+
+When an administrator later updates the dashboard template (by adding or removing widgets through the Dashboards manager page), those changes are applied to all existing users' personal dashboards. See [Managing Your Dashboard](building-sites/client-proofing/dashboards/managing "Managing Your Dashboard") for more on how template changes propagate.
+
 ## See Also
 
 1. [Managing Your Dashboard](building-sites/client-proofing/dashboards/managing)