docs: align v2 stack documentation (#6564)

apps/docs/docs/widgets/app/index.mdx

@@ -28,7 +28,8 @@ import piHoleApp from "./img/pi-hole-ping-icon.png";
 
 ### Interactions
 
-App tiles stay compact and open their configured destination directly. Right-click a tile to inspect its status or change its settings when the board and your preferences allow it.
+App tiles stay compact and open their configured destination directly. They do not use the shared widget context menu;
+configure the app and its status check from the tile's edit actions.
 
 ### Adding the widget
 

apps/docs/docs/widgets/assistant/index.mdx

@@ -7,6 +7,7 @@ hide_title: true
 import { AddingWidget } from "@site/src/components/widgets/adding";
 import { WidgetHeader } from "@site/src/components/widgets/header";
 import { assistantWidget } from ".";
+import assistantWidgetImage from "../../management/img/assistant-widget.png";
 
 <WidgetHeader widget={assistantWidget} categories={["Productivity"]} />
 
@@ -15,7 +16,18 @@ board. Messages, conversations, tool calls, approvals, files, mentions, model co
 usage details, and response actions remain synchronized with the app-wide assistant.
 
 The assistant must be enabled by an administrator in **Management → Assistant**. Signed-out users and users
-on an instance without an enabled model see an unavailable state instead of a broken composer.
+on an instance without an enabled model see an unavailable state instead of a broken composer. Signed-out users see
+**Sign in**; a configured provider without a saved model or with **Enable Assistant** off remains unavailable until
+the administrator saves a working connection, selects a model, and enables the assistant.
+
+<img
+  src={assistantWidgetImage}
+  alt="Assistant widget embedded on a dashboard with its conversation header, automatic approvals control, model selector, and composer"
+  style={{ maxWidth: "100%" }}
+/>
+
+The current preview capture labels the board-embedded surface: its header exposes conversation history, refresh,
+automatic approvals, and new-conversation controls, while the footer exposes the model, thinking mode, and composer.
 
 ### Adding the widget
 
@@ -42,10 +54,16 @@ keeps every assistant entry point synchronized without storing a user's private
 - Edit user messages and copy, regenerate, branch, quote, export, or rate responses.
 - Inspect syntax-highlighted Markdown, sources, generated files, tool results, streaming chain-of-thought,
   cumulative conversation usage, per-turn token and context use, timing, speed, provider routing, and cost.
-- Change the model and reasoning effort for the active conversation.
+- Change the model and reasoning effort for the active conversation. A model choice is saved per persisted thread,
+  does not change the administrator's default, and is restored when that thread is selected again; a new thread
+  starts from the configured default.
 - Refresh the current board from the conversation header. Approved mutations also refresh visible board data automatically.
 
 The expanded assistant and board widget use the same persisted thread runtime. A response continues in the
 background when the widget leaves the viewport or the expanded panel is minimized. Each visible surface keeps an
 independent draft, attachments, selection, and focus, so typing in a board widget cannot move or overwrite the
 floating panel composer.
+
+Automatic approvals are off by default, reset when switching conversations, and never select a neutral choice. A
+structured question shows **Other** only when the tool allows it (`allowOther` is not `false`); selecting **Other**
+opens a manual freeform response even when automatic approvals are enabled.

apps/docs/docs/widgets/beszel-system-grid/index.mdx

@@ -10,6 +10,7 @@ import { WidgetHeader } from "@site/src/components/widgets/header";
 import { AddingWidget } from "@site/src/components/widgets/adding";
 import { WidgetConfig } from "@site/src/components/widgets/configuration";
 import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 import { beszelSystemGridWidget } from ".";
 import { beszelIntegration } from "@site/docs/integrations/beszel";
 

apps/docs/docs/widgets/beszel-system-stats/index.mdx

@@ -17,7 +17,7 @@ import beszelSystemStats from "./img/beszel-system-stats.png";
 
 <WidgetHeader widget={beszelSystemStatsWidget} categories={["System Monitoring", "Charts"]} />
 
-This widget displays time-series charts for a selected Beszel system, including CPU, memory, disk, network, and Docker container metrics. The Disk Usage chart combines the root disk and every extra filesystem reported by Beszel. Hover over or focus the widget controls to switch between the realtime Live view and historical periods ranging from 1 hour to 30 days. Live view keeps a one-minute window and pauses while the browser tab is hidden. If the live stream drops, the widget now shows the connection failure state immediately and can switch back to historical data.
+This widget displays time-series charts for a selected Beszel system, including CPU, memory, disk, network, and Docker container metrics. The Disk Usage chart combines the root disk and every extra filesystem reported by Beszel. Use the widget controls to switch between the realtime Live view and historical periods ranging from 1 hour to 30 days. Live view keeps a one-minute window and pauses while the browser tab is hidden. If the live stream drops, the widget now shows the connection failure state immediately and can switch back to historical data.
 
 ### Screenshots
 

apps/docs/docs/widgets/beszel-system-table/index.mdx

@@ -10,6 +10,7 @@ import { WidgetHeader } from "@site/src/components/widgets/header";
 import { AddingWidget } from "@site/src/components/widgets/adding";
 import { WidgetConfig } from "@site/src/components/widgets/configuration";
 import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 import { beszelSystemTableWidget } from ".";
 import { beszelIntegration } from "@site/docs/integrations/beszel";
 

apps/docs/docs/widgets/calendar/index.mdx

@@ -31,16 +31,12 @@ the same data is requested through Homarr's MCP or Assistant tools.
 
 ### Screenshots
 
-import popover from "./img/popover.png";
-import withIntegrations from "./img/with-integrations.png";
-import withoutIntegrations from "./img/without-integrations.png";
+import currentView from "./img/current-view.png";
+import advancedView from "./img/advanced-view.png";
 
-<div className="flex gap-1">
-  <img src={withIntegrations} alt="calendar with-integrations big-size" width={256 + 4} height={256 + 4} />
-  <div className="flex flex-col gap-1">
-    <img src={popover} alt="calendar popover-details the-mandalorian" width={128 * 3} height={128} />
-    <img src={withoutIntegrations} alt="calendar without-integrations small-size" width={256} height={128} />
-  </div>
+<div className="flex flex-col gap-1">
+  <img src={currentView} alt="Calendar month view with marked events" width={513} height={303} />
+  <img src={advancedView} alt="Calendar advanced view with grouped events" width={800} height={484} />
 </div>
 
 ### Supported Integrations

apps/docs/docs/widgets/custom-api/index.mdx

@@ -32,7 +32,8 @@ Credentials remain on the server.
 
 :::note
 Custom API widgets must first be created in **Management → Custom Widgets** before they appear in the widget picker.
-Action buttons can only be executed by administrators.
+Action buttons require the request's minimum board permission, which is `modify` by default. Anonymous viewers cannot run
+mutations. DELETE additionally requires full permission and confirmation.
 :::
 
 ### Permissions and actions

apps/docs/docs/widgets/dns-hole-controls/index.mdx

@@ -22,7 +22,7 @@ import { technitiumDnsIntegration } from "@site/docs/integrations/technitium-dns
 
 When several DNS integrations are selected, Homarr keeps healthy controls available if one source fails and shows a warning identifying the unavailable integration.
 
-This widget lets permitted users enable, disable, or temporarily pause one or more DNS services. It shares the summary query and cache with DNS Hole Summary. Every selected source stays available in the normal scrollable view, while cards and controls adapt to the widget's width and height.
+This widget lets permitted users enable, disable, or temporarily pause one or more DNS services. It shares the summary query and cache with DNS Hole Summary. Every selected source stays available in the normal scrollable view, while cards and controls adapt to the widget's width and height. Bulk actions keep successful results visible and report the number of failures.
 
 ### Screenshots
 

apps/docs/docs/widgets/docker-containers/index.mdx

@@ -8,6 +8,7 @@ import { WidgetHeader } from "@site/src/components/widgets/header";
 import { AddingWidget } from "@site/src/components/widgets/adding";
 import { WidgetConfig } from "@site/src/components/widgets/configuration";
 import { WidgetIntegrations } from "@site/src/components/widgets/integrations";
+import { WidgetInteractionGuide } from "@site/src/components/widgets/interactions";
 import { IconAd } from "@tabler/icons-react";
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
@@ -49,6 +50,8 @@ Each container row has an action menu, accessible via the three-dot icon or by r
 - **Remove** - permanently remove the container after a second confirmation click
 - **Add to Homarr** - create a bookmark app from the container
 
+<WidgetInteractionGuide advancedView={false} />
+
 ### Adding the widget
 
 <AddingWidget />

apps/docs/docs/widgets/downloads/index.mdx

@@ -21,36 +21,79 @@ import { downloadsWidget } from ".";
 
 <WidgetHeader widget={downloadsWidget} categories={["Torrent client", "Usenet client", "Downloads"]} />
 
-This widget displays a list of torrents or usenet-articles that are currently being downloaded, along with their progress and other relevant information. It supports 7 download client integrations and provides a rich, responsive table interface.
+This widget displays torrent, Usenet, and miscellaneous download jobs, along with their progress and other relevant information. It supports 7 download client integrations and provides a rich, responsive table interface.
 
 ### Screenshots
 
 import downloadsCard from "./img/screenshot.png";
 import contextMenuImg from "./img/context-menu.png";
+import advancedViewImg from "./img/advanced-view.png";
+import filterPanelImg from "./img/filter-panel.png";
 
 <div>
   <img src={downloadsCard} alt="Downloads widget showing torrent and usenet items" width={128 * 4} />
 </div>
 
-#### Right-click context menu
+#### Download-row context menu
 
 <div>
-  <img src={contextMenuImg} alt="Downloads widget context menu with pause, delete, and copy actions" width={128 * 4} />
+  <img src={contextMenuImg} alt="Downloads row context menu with pause, delete, and copy actions" width={128 * 4} />
+</div>
+
+#### Advanced view
+
+<div>
+  <img
+    src={advancedViewImg}
+    alt="Downloads widget in advanced view with stats, sortable columns, and expanded details"
+    width={128 * 6}
+  />
+</div>
+
+#### Advanced filter panel
+
+<div>
+  <img src={filterPanelImg} alt="Downloads advanced view with the status filter panel open" width={128 * 6} />
 </div>
 
 ### Features
 
-- **Responsive table** — columns automatically adapt to widget width, hiding less important columns at smaller sizes
-- **Sortable columns** — click any column header to sort ascending/descending
+- **Responsive compact table** — in compact mode, selected columns adapt to both widget width and height; narrow or short tiles hide speed/state columns, and the shortest tiles also hide the ETA column
+- **Sortable columns** — click any sortable column header to sort the current view; the configured default controls the initial column and direction
 - **Column customization** — choose which columns to display, then hover a header to reveal its grab handle for reordering or drag its edge to resize it; layouts save automatically per widget
-- **Right-click context menu** — copy download names, or pause, resume, and delete when your account has Interact access and the client supports those actions
+- **Download-row context menu** — copy a download name or ID from any row; pause, resume, and delete actions appear when you have Interact access to that integration
 - **Row expansion** — click any row to see full details inline without opening a separate modal
 - **Hover tooltips** — hover a download name to see size, speeds, ETA, ratio, and category; open tooltips close when switching between compact and advanced mode
-- **Global stats bar** — toggle a summary bar showing queue progress, total size, speeds, ratio, and per-state counts
+- **Global stats bar** — show queue progress, downloaded/total size, transfer speeds, global torrent ratio, and per-state counts in compact mode; advanced view always includes it
 - **Client filtering** — filter downloads by integration or status using the footer filter panel
-- **Global controls** — pause/resume downloads from supported clients when your account has Interact access; read-only clients such as slskd do not expose these controls
+- **Global controls** — pause/resume actionable queues from the footer bar, limited to selected integrations where you have Interact access
 - **Status indicators** — color-coded badges show download state at a glance
-- **Speed overview** — total download and upload speeds displayed in the footer
+- **Speed overview** — total download and upload speeds for the selected clients are displayed in the footer
+
+:::note
+
+Compact layouts use both dimensions: below 500px wide, speed columns are hidden; below 300px wide, the ETA and state
+columns are hidden too. A tile shorter than 180px hides speed and state columns, and a tile shorter than 120px also
+hides ETA. The footer is hidden below 96px in compact mode. Advanced view bypasses these compact size reductions,
+keeps the selected column set, and always includes the stats bar and footer controls, with the filter panel available
+from the footer.
+
+The filter panel changes the visible rows. Its client/status filters also change the stats bar's progress, size, and
+state counts, while transfer-speed totals summarize the selected clients and the global torrent ratio summarizes the
+selected torrent clients. The configured category/label filter can optionally be applied to the global torrent ratio
+through **Use category filter for global torrent ratio**; footer client/status filters do not change that ratio.
+
+The per-item **Ratio** is sent bytes divided by the item's total size. **Global Ratio** is total uploaded bytes divided
+by total downloaded bytes.
+
+Mutation controls depend on the integration's Interact permission. Users without that permission can still view rows and
+use the row menu's copy actions. `slskd` is list-only: its pause, resume, and delete operations are no-ops, so those
+controls have no effect for that client even when Interact permission exposes them.
+
+The screenshot above is a Downloads row menu, separate from the shared widget context menu. When board right-click menus
+are enabled, the shared menu provides widget-level actions such as advanced view, widget options, refresh, and settings.
+
+:::
 
 ### Supported Integrations
 
@@ -82,20 +125,20 @@ import contextMenuImg from "./img/context-menu.png";
     },
     {
       integration: slskdIntegration,
-      note: "Soulseek client (read-only)",
+      note: "Soulseek client (list-only; mutation controls are no-ops)",
     },
   ]}
 />
 
 ### Interactions
 
-- **Right-click** any download to copy its name; pause/resume and delete require Interact access and client support
+- **Right-click** any download to copy its name or ID; pause, resume, and delete are available only with Interact access
 - **Click** any row to expand it and see full download details inline
 - **Hover** a download name for a quick stats tooltip
-- **Stats toggle** — show or hide the global stats bar from the footer
-- **Pause / Resume** downloads from supported clients using the footer controls when you have Interact access; slskd remains read-only
-- **Filter** by integration or status using the filter button in the footer
-- **Sort** the current view by clicking column headers to switch direction
+- **Stats toggle** — show or hide the global stats bar in compact mode; advanced view always shows the stats bar
+- **Pause / Resume** actionable queues using the footer controls
+- **Filter** rows by integration or status using the filter button in the footer
+- **Sort** by clicking sortable column headers; the default sort is configured per widget, while header changes apply to the current view
 
 <WidgetInteractionGuide />
 

apps/docs/docs/widgets/downloads/index.ts

@@ -30,19 +30,20 @@ export const downloadsWidget: WidgetDefinition = {
       {
         name: "Columns to show",
         description:
-          "Select the columns you want to display in the widget. Columns automatically hide/show based on widget width.",
+          "Select the columns you want to display in the widget. Compact layouts automatically hide/show selected columns based on widget width and height; advanced view keeps the selected columns visible.",
         values: `List of columns: ${columnsList.join(", ")}`,
         defaultValue: ["name", "progress", "downSpeed", "time", "state"].join(", "),
       },
       {
         name: "Default sort column",
-        description: "The column used for initial sorting when the widget loads.",
+        description:
+          "The column used for initial sorting when the widget loads. Clicking a column header changes the current view only.",
         defaultValue: "progress",
         values: `List of columns: ${sortColumns.join(", ")}`,
       },
       {
         name: "Invert sorting",
-        description: "This will invert the default sorting order.",
+        description: "This sets the initial sorting direction.",
         values: { type: "boolean" },
         defaultValue: "no",
       },
@@ -66,8 +67,7 @@ export const downloadsWidget: WidgetDefinition = {
       },
       {
         name: "Hide completed torrent under this threshold (in kiB/s)",
-        description:
-          "This will hide completed torrent entries that have an upload speed below the specified threshold.",
+        description: "This will hide completed torrent entries whose upload speed is below the specified threshold.",
         values: "Any number above 0, 0 to disable",
         defaultValue: "0",
       },
@@ -85,15 +85,16 @@ export const downloadsWidget: WidgetDefinition = {
         defaultValue: "no",
       },
       {
-        name: "Use filter to calculate Ratio",
-        description: "This will use the category filter when calculating the global torrent ratio.",
+        name: "Use category filter for global torrent ratio",
+        description:
+          "When enabled, the configured category/label filter is applied to the global torrent ratio. Footer client/status filters do not change this ratio.",
         values: { type: "boolean" },
         defaultValue: "yes",
       },
       {
         name: "Limit items per integration",
         description: "This will limit the number of items shown per integration, not globally.",
-        values: "Any number above 1",
+        values: "Any whole number from 1 upward",
         defaultValue: "50",
       },
     ],

apps/docs/docs/widgets/media-server/index.mdx

@@ -31,8 +31,12 @@ Sessions without user metadata remain visible and are labeled as an unknown user
 ### Screenshots
 
 import mediaTable from "./img/table.png";
+import mediaAdvancedView from "./img/advanced-view.png";
 
-<img src={mediaTable} alt="media-server-streams" width={128 * 3 * 1.5} height={128 * 1.5} />
+<div className="flex flex-col gap-1">
+  <img src={mediaTable} alt="Media server compact streams table" width={303} height={198} />
+  <img src={mediaAdvancedView} alt="Media server advanced view with stream summary" width={800} height={484} />
+</div>
 
 ### Supported Integrations
 

apps/docs/docs/widgets/weather/index.mdx

@@ -15,17 +15,20 @@ import { weatherWidget } from ".";
 
 The Weather Widget uses your location to display the current, highest and lowest temperature.
 In the compact view, select a condition icon or forecast day to open details with a mouse, keyboard or touch.
-The advanced view always combines current conditions with the full seven-day forecast, including humidity, wind,
-gusts, sunrise and sunset. Both views reuse the same cached Open Meteo response.
+The compact forecast shows up to the configured number of days. The advanced view combines current conditions with the
+available daily forecast, including humidity, wind, gusts, sunrise and sunset. Both views reuse the same cached Open
+Meteo response.
 
 ### Screenshots
 
 import forecastWeather from "./img/forecast.png";
 import currentWeather from "./img/current.png";
+import advancedWeather from "./img/advanced-view.png";
 
 <div className="flex flex-col gap-1">
-  <img src={forecastWeather} alt="weather forecast-5-days" width={128 * 4.5} />
-  <img src={currentWeather} alt="weather current" width={128 * 3} />
+  <img src={forecastWeather} alt="Weather compact forecast" width={238} height={112} />
+  <img src={currentWeather} alt="Weather compact current conditions" width={198} height={93} />
+  <img src={advancedWeather} alt="Weather advanced view with seven-day forecast details" width={800} height={484} />
 </div>
 
 <WidgetInteractionGuide />