docs: align v2 stack documentation

apps/docs/docs/advanced/keyboard-shortcuts/index.mdx

@@ -6,14 +6,31 @@ tags:
 
 Homarr has the following keyboard shortcuts:
 
-| Shortcut                                        | Description                                |
-| ----------------------------------------------- | ------------------------------------------ |
-| `MOD` + `K`                                     | Opens the search bar                       |
-| `MOD` + `J`                                     | Toggles Dark Mode                          |
-| `MOD` + `E`                                     | Toggles Edit Mode                          |
-| Hold `Shift` for 500 ms over a supported widget | Opens its temporary advanced view          |
-| `Shift` + `Enter` on a supported widget         | Opens its advanced view until it is closed |
-| `Esc`                                           | Closes an open advanced view or board menu |
+| Shortcut                                        | Description                                                                                                                |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `MOD` + `K`                                     | Opens the search bar                                                                                                       |
+| `MOD` + `J`                                     | Toggles Dark Mode                                                                                                          |
+| `MOD` + `E`                                     | Toggles Edit Mode                                                                                                          |
+| Hold `Shift` for 500 ms over a supported widget | Opens its temporary advanced view                                                                                          |
+| `Shift` + `Enter` on a supported widget         | Opens its advanced view until it is closed                                                                                 |
+| `Esc`                                           | Stops keyboard tile editing, cancels an active pointer or touch move/resize, or closes an open advanced view or board menu |
+
+## Board editing
+
+`MOD` + `E` enters edit mode. Homarr keeps the current board visible while the editor prepares; movement and resizing become available when it is ready.
+
+When a tile is focused in edit mode:
+
+| Shortcut             | Description                                                          |
+| -------------------- | -------------------------------------------------------------------- |
+| `Enter` or `Space`   | Starts or stops keyboard editing                                     |
+| Arrow keys           | Moves the focused tile within its current canvas, rail, or Container |
+| `Shift` + Arrow keys | Resizes the focused tile                                             |
+| `Esc`                | Stops keyboard editing without undoing its changes                   |
+
+Keyboard moves and resizes apply immediately. To move an item between a canvas, rail, or Container, drag it there or use **Move / resize item** for precise numeric placement.
+
+On touch screens, press and hold a tile before moving it; a quick tap does not start a drag. Resize handles accept direct touch input. During a pointer or touch move or resize, `Esc` cancels the interaction and restores the layout from before it started.
 
 :::tip
 

apps/docs/docs/advanced/styling/index.mdx

@@ -85,8 +85,8 @@ To do this, enter the board settings:
 
 ![](./img/enter-board-settings.png)
 
-Scroll down a bit and click on custom CSS.
-Here you can enter your CSS code, which will be applied on the respective board page.
+Scroll to the **Custom CSS** section on the board settings page. It is part of the unified settings form; enter your CSS
+there and save the board settings to apply it to that board.
 
 ![](./img/custom-css-setting.png)
 

apps/docs/docs/getting-started/after-the-installation.mdx

@@ -130,7 +130,7 @@ It is important that you first migrate correctly using [the list of breaking cha
    Copy it and do not loose it!
 5. Go to your new >1.0.0 Homarr instance and start the onboarding. Choose `Import from Homarr before 1.0`
 6. Drag and drop your previously downloaded ZIP archive into the file upload: <br/><img src={manageImportOldHomarrDropzone} style={{ maxWidth: 500 }} />
-7. Next, choose the data that you want to import and how to import it. Since screen sizes were removed in 1.0, we create a new board for every screen size by default. We recommend you to only keep the best layout and adjust it later in 1.0.0 - but you can also import all of them and pick later.<br/><img src={manageImportOldHomarrChooseData} style={{ maxWidth: 500 }} />
+7. Next, choose the data that you want to import and how to import it. Old Homarr screen sizes are imported as responsive layouts on the same board: the narrowest becomes **Mobile**, the widest becomes **Base**, and layouts between them become custom layouts. Homarr normalizes duplicate breakpoints automatically, so you can review the imported board in Board Settings and adjust the layouts there.<br/><img src={manageImportOldHomarrChooseData} style={{ maxWidth: 500 }} />
 8. If you previously exported integrations or users, you will be asked to decrypt the data safely using your obtained encryption token. Paste into the modal and confirm your action.<br/><img src={manageImportDecryptionToken} style={{ maxWidth: 500 }} />
 9. Next, you can [follow the same setup as when starting from scratch](#starting-from-scratch). After you completed the onboarding, all of your data will be migrated and available.
 
@@ -151,6 +151,9 @@ Congratulations - you've just created your first board. You can see boards, that
 
 ![](./img/manage-view-board.png)
 
+New boards start with **Mobile** and **Base** responsive layouts automatically, so you can edit the board for phones and
+desktops without creating extra layouts first. Each layout keeps its own tile positions and sizes.
+
 ## Add your first app to Homarr
 
 To add links to your dashboard, you must first add them as an "app".
@@ -182,21 +185,23 @@ Here you have the following options in the header:
 - **Search**: Here you can search for data. You can search for integrations, boards, actions, sites and much more. Some actions may be context dependent (eg. will only show when certain widgets are on your page)
 - **Edit mode**: Clicking this button will toggle the edit mode. In this mode you can edit the contents of your board.
 - **Settings**: Clicking this button will redirect you to a settings page where you can adjust the board settings (page title, colors, ...).
+- **Board switcher**: Use this button to open another board that you can access.
 - **Profile**: This avatar will be visible on every page. Clicking it will show a menu with actions.
 
 When entering the edit mode, you'll get some additional buttons to work with:
 
 <img src={manageBoardHeaderEditMode} alt={"Screenshot of buttons in the edit mode"} width={200} />
 
-- **Add item**: Click this button to add new elements to your page.
-- **Exit edit mode**: Click this button to save your changes and exit edit mode.
+- **Add board content**: Click this button to create a new item, app, integration, or Container.
+- **Exit edit mode**: Click this button to save your changes and exit edit mode. If you leave with unsaved changes, Homarr asks whether to discard them.
 
 Outside edit mode, right-click a widget for its live status, refresh, settings, quick options, and supported actions.
 Hold `Shift` while hovering a widget that supports advanced view to expand it in place while the rest of the board
 stays visible but dimmed. Release `Shift` to close it. You can also focus that widget and press `Shift` + `Enter` to
 keep its advanced view open until you close it. Widgets without a distinct advanced experience adapt in place.
 
-To continue, click the option "New Item":
+To continue, click **New item** in the add-content menu. New content is placed at the first available position on the main
+canvas; it is not inserted at a clicked empty cell or directly into a rail or Container:
 
 <img src={manageBoardHeaderAddItem} alt={"Screenshot of the add item menu"} width={200} />
 
@@ -233,7 +238,8 @@ The tile snaps to the grid. Equally-sized tiles swap when one is dropped into th
 Every `1 × 1` tile has a logical content size of `200 × 200` pixels.
 Larger tiles use multiples of that fixed unit, with a consistent gap between cells.
 Homarr scales the complete board uniformly, like zooming a page.
-It stops shrinking at 75% and lets you scroll horizontally instead of making text and controls too small.
+The complete canvas always fits the available width without horizontal board scrolling. Below 100%, Homarr preserves the
+widget's readable typography and control density instead of shrinking each widget independently.
 It does not squeeze or reflow the content of individual widgets, so a widget keeps the same design and proportions across screen sizes.
 
 :::note
@@ -251,9 +257,11 @@ This helps you to explore the capabilities of Homarr before you build your board
 
 :::
 
-Keyboard users can focus a tile, press Enter or Space, then use arrow keys to move and Shift plus arrow keys to resize.
-Press Escape to stop.
-For precise numeric controls or touch input, choose **Move / resize item** from the tile's edit menu.
+Keyboard users can focus a tile, press Enter or Space, then use arrow keys to move and Shift plus arrow keys to resize
+within its current canvas, rail, or Container. Press Escape to stop keyboard editing. Touch dragging starts after a short
+hold of about `200 ms`; resize handles accept direct touch input. During a pointer or touch move or resize, press Escape
+to cancel and restore the previous layout. For cross-grid moves or precise numeric controls, choose **Move / resize item**
+from the tile's edit menu.
 The dialog can also move the tile to another section or fixed sidebar:
 
 ![](./img/manage-board-move-resize-item-menu.png)

apps/docs/docs/management/assistant.mdx

@@ -6,6 +6,8 @@ tags:
   - Security
 ---
 
+import assistantConfigImage from "./img/assistant-config.png";
+
 # Assistant
 
 Administrators can configure the instance-wide AI assistant from **Management → Assistant**.
@@ -59,6 +61,15 @@ The management page presents setup as three compact sections: provider and endpo
 model and availability. A status summary at the top shows whether the connection is ready, whether a key
 is protected, and which model is selected. Redundant active-state badges are omitted when the setup is ready.
 
+<img
+  src={assistantConfigImage}
+  alt="Assistant configuration page showing provider, credentials, model, and availability sections"
+  style={{ maxWidth: "100%" }}
+/>
+
+The screenshot shows the configuration surface with no provider key entered; the assistant remains disabled until a
+working provider, model, and enabled state are saved.
+
 1. Choose a provider preset or **Custom endpoint**, then confirm the API base URL. It usually ends in `/v1`.
 2. Add an API key if the service requires bearer authentication. Additional authentication or routing
    headers are available in the collapsed advanced section.
@@ -286,6 +297,9 @@ assistant did not change, and returns only values that differ from the current b
 copied or restored before continuing, and Homarr warns when it contains an imported stylesheet or remote
 resource URL. Continuing from the form opens the normal mutation approval before anything is saved.
 
+The board-settings tool covers General, Background, Appearance, Custom CSS, and app-status settings. It does not edit
+responsive layouts, board access control, or Danger zone actions.
+
 Ask for changes such as “make the cards denser on my Home board,” “add a mobile CSS rule without removing
 my existing styles,” or “change the board colors and disable app status checks.” The current user must have
 modify permission on the selected board. The empty conversation includes an **Improve a dashboard** starter,

apps/docs/docs/management/boards/index.mdx

@@ -14,12 +14,13 @@ import itemRadiusImage from "./img/item-radius.png";
 import layoutLargeImage from "./img/layout-large.png";
 import layoutMediumImage from "./img/layout-medium.png";
 import layoutSmallImage from "./img/layout-small.png";
+import layoutSettingsImage from "./img/layout-settings.png";
 
 Each dashboard is called a "board".
 You can create as many boards as you want.
 Boards can be restricted to user groups.
-A user may also have a "home board" which they will see at the root path (e.g. my-homarr.com or my-homarr.com/board).
-Other boards can be viewed by direct links (e.g. my-homarr.com/board/smart-home) or via the management pages.
+A user may also have a "home board" which they will see at the root path (e.g. my-homarr.com or my-homarr.com/boards).
+Other boards can be viewed by direct links (e.g. my-homarr.com/boards/smart-home) or via the management pages.
 
 Names of boards must be unique because this will be used in the URL to load the desired board.
 
@@ -92,9 +93,14 @@ Homarr will fall back to the Homarr logo if nothing is set.
 
 In this section you can configure the different responsive layouts. Homarr selects the layout with the highest breakpoint that is not wider than the current screen, then scales its complete fixed-size canvas uniformly.
 
-![](./img/layout-settings.png)
+<img
+  src={layoutSettingsImage}
+  alt="Board settings showing protected Mobile and Base responsive layouts with rail controls"
+  style={{ maxWidth: "100%" }}
+/>
 
-Every board has two protected layouts:
+Every board has two protected layouts. Creating a board adds **Mobile** at `0px` with three columns and **Base** at
+`768px` with the column count you choose. Both layouts can be edited, but neither can be removed.
 
 Every `1 × 1` tile has a `200 × 200` logical-pixel content area.
 The `24` logical-pixel gap between tiles is separate from that size.
@@ -107,9 +113,16 @@ The complete canvas always fits the available width and never adds horizontal bo
 - **Mobile** starts at `0px` and uses three columns on new boards.
 - **Base** is the widest layout and starts at `768px` on new boards.
 
-Mobile and Base can be renamed and their column counts and rails can be changed, but they cannot be removed. You can add removable custom layouts between their breakpoints.
+Mobile and Base can be renamed and their column counts and rails can be changed. You can add removable custom layouts
+between their breakpoints.
 
-Each layout stores independent positions and sizes. Moving or resizing a widget while editing Mobile does not move it in Base or any custom layout. New custom layouts are generated from Base and scaled to their selected column count.
+Each layout stores independent positions and sizes. Moving or resizing a widget while editing Mobile does not move it in
+Base or any custom layout. New custom layouts start from Base's current column count and rail widths; Homarr chooses a
+free breakpoint between Mobile and Base, and you can then change the breakpoint, columns, and rails.
+
+Older or incomplete boards are repaired automatically. Homarr restores missing Mobile/Base layouts, promotes the narrowest
+and widest existing layouts to those protected roles, keeps intermediate layouts custom, and normalizes duplicate or
+out-of-order breakpoints without discarding saved positions.
 
 Use **Reset from Base** on Mobile or a custom layout to replace all of its positions and sizes with a newly generated version of Base. The layout's name, breakpoint, and column count are kept.
 
@@ -152,17 +165,27 @@ After the board is interactive, Homarr prepares the editor in the background for
 Entering edit mode keeps the static board visible until that preparation finishes, then enables collision-aware movement and resizing without changing the board geometry.
 Widget content is inert in edit mode, so dragging anywhere on the content moves the tile instead of activating the widget; its settings button remains visible in the compact header above the tile.
 Dropping a tile into another tile's exact slot swaps their positions when both resulting placements fit without overlapping other content.
-For other collisions, or when a tile grows into occupied space, nearby tiles are compacted out of the way.
+For other collisions, or when a tile grows into occupied space, nearby tiles are compacted out of the way. A compatible
+single-item collision can swap when both placements fit; other collision chains reflow around the move.
 The visible corner controls provide a 44-pixel resize target, and edge controls appear on hover for horizontal or vertical resizing.
 Resize handles stop at the tile's minimum allowed size while the pointer is still moving.
-Exit edit mode to save the resulting positions.
+Use the pencil button in the board header to enter edit mode; click it again to save. If you leave the page with unsaved
+changes, Homarr asks whether to discard them. If the editor cannot load, the board remains in view mode.
+
+While edit mode is active, **Add board content** creates a new item, app, integration, or Container on the main canvas.
+New content uses the first available position; clicking an empty cell does not place it there, and items cannot be added
+directly into a rail or Container from this menu.
 
 Pointer users can drag anywhere on a widget tile. Containers use the grab button at their top-left corner.
-Resize tiles from any edge or corner handle.
-On a touch screen, press and hold the tile before moving it; resize handles support direct touch input.
+Widgets can be resized from any edge or corner handle. Activate a Container's chrome with its top-left grip before using
+its resize handles.
+On a touch screen, press and hold a tile for about `200 ms` before moving it; a quick tap does not start a drag. Resize
+handles support direct touch input.
 Keyboard users can focus a tile, press Enter or Space to start editing, use the arrow keys to move it, and use Shift plus the arrow keys to resize it.
 Press Enter, Space, or Escape to stop keyboard editing.
-Keyboard moves and resizes apply immediately; Escape stops keyboard editing without undoing those changes.
+Keyboard moves and resizes apply immediately within the current canvas, rail, or Container; they cannot move an item
+between grids. Use pointer drag or **Move / resize item** for that.
+Escape stops keyboard editing without undoing those changes.
 During a pointer or touch interaction, Escape cancels the move or resize and restores the layout from before that interaction.
 The **Move / resize item** action in the edit menu remains available for precise numeric input.
 
@@ -247,9 +270,10 @@ Change the radius of your items and Containers.
 This is the field where you can enter custom CSS.
 The styling will only be applied on the respective board page.
 
-When Homarr Assistant is enabled, users with modify permission can also ask it to edit the board's Custom
-CSS and other visual or behavior settings. The assistant reads the current stylesheet first and presents an
-editable review form before requesting approval to save the change.
+When Homarr Assistant is enabled, users with modify permission can also ask it to edit the board's General, Background,
+Appearance, Custom CSS, and app-status settings. The assistant reads the current stylesheet first and presents an
+editable review form before requesting approval to save the change. It does not edit responsive layouts, access control,
+or Danger zone actions.
 
 [See this guide on how to work with custom CSS](/docs/advanced/styling/).
 
@@ -266,12 +290,12 @@ Widgets expose their routine controls without requiring edit mode:
 - Hold `Shift` while hovering a widget that supports advanced view to expand it in place while the other widgets
   remain visible but dimmed. Release `Shift` to close it. Focus that widget and press `Shift` + `Enter` to keep the view
   open until you close it. On touch devices, open it from the widget menu. Other widgets adapt in place instead.
-- Right-click a widget to inspect its live query status, refresh its data, change quick options, open settings, or run
-  supported actions. Available controls follow your board and integration permissions.
-- If you can modify the board, right-click or touch and hold an empty grid cell to add an item there. Focus a board
-  section and press `Shift` + `F10` for the keyboard equivalent.
+- When signed in, outside edit mode, and with **Enable right click on widgets** enabled, right-click a widget to inspect
+  its live query status, refresh its data, change quick options, open settings, or run supported actions. App tiles do
+  not use this widget menu, and available controls follow your board and integration permissions.
 
-Widget and empty-space context menus follow the **Enable right click on widgets** preference in your user settings.
+The widget context menu follows the **Enable right click on widgets** preference in your user settings. On touch devices,
+use the widget menu where your browser exposes it.
 
 ### Access control
 
@@ -388,5 +412,7 @@ For the global home board you can only select boards that are public.
 
 ### Mobile home board
 
-Same as the home board, you can also set a mobile home board.
-It will be used for devices that are detected as mobile devices. (Using User-Agent header)
+Same as the home board, you can also set a mobile home board. It is used for devices detected as mobile devices from the
+User-Agent header. For the server-wide fallback, configure **Global mobile board** under `Management` > `Settings` >
+`Boards`; the selected board must be public. See the [global board defaults](/docs/management/settings#boards) for the
+desktop and mobile fallback rules.

apps/docs/docs/management/custom-widgets/agent-authoring.mdx

@@ -67,8 +67,9 @@ These interfaces do not return an archive URL or archive hash.
 
 1. Load `customWidget_getSkill`, then get the prompt and live schema.
 2. Call `customWidget_getComponentCatalog`, followed by `customWidget_getComponent` for only the relevant installed
-   components and `customWidget_getExample` when one catalog example matches the interaction pattern. If shared props
-   are needed, collect their catalog names and call `customWidget_getSharedProps` once for that set.
+   components and `customWidget_getExample` when one catalog example matches the interaction pattern. Fetch at most
+   eight component documents before the first validation (or four after a complete example already matches). If shared
+   props are needed, collect their catalog names and call `customWidget_getSharedProps` once for that set.
 3. Read the external API documentation.
 4. Build one definition, using `templateLines` for multiline JSX tool input.
 5. Validate the definition without saving it and repair every reported issue.
@@ -76,8 +77,9 @@ These interfaces do not return an archive URL or archive hash.
 7. Run `customWidget_previewQuery` for every query returned by the preview and inspect its actual status and data shape.
 8. Test relevant actions in simulation mode.
 9. Open the returned preview path with browser tools.
-10. Inspect the redacted journal and revise the local candidate until validation, data, and rendering all work.
-11. Create the widget, including any source URLs and credentials the user already supplied.
+10. Inspect the redacted journal and revise the local candidate until validation, data, and rendering all work. Keep the
+    exact tested preview candidate locally.
+11. Create the widget from that final tested preview, including any source URLs and credentials the user already supplied.
 12. Open its returned management path, and use a structured question when the user must choose whether to place it on a board.
 13. Otherwise, ask the user to configure the saved definition with the ten-minute Homarr source-setup URL.
 14. Create a final preview with the saved definition ID so Homarr loads its stored credentials, then test it again.

apps/docs/docs/management/custom-widgets/authoring.mdx

@@ -1,8 +1,19 @@
 # Create a Custom Widget
 
 import { CanonicalCustomWidgetExample } from "@site/src/components/custom-widget-code";
+import workbenchImage from "./img/workbench.png";
 
 The workbench is visual-first: configure the default API connection, add request cards, add option rows, then write JSX. Additional sources and raw manifest JSON remain under Advanced. Code and preview sit side by side on desktop and use tabs on mobile.
+For multiline JSX, prefer `templateLines` in agent or MCP input and keep the final tested preview as the source of truth before saving.
+
+<img
+  src={workbenchImage}
+  alt="Custom Widget workbench with configuration sections and a live preview"
+  style={{ maxWidth: "100%" }}
+/>
+
+The workbench keeps the configuration and preview together so you can inspect validation diagnostics, the redacted request
+journal, fixture data, and preview size before saving.
 
 ## Manual workflow
 

apps/docs/docs/management/custom-widgets/custom-jsx.mdx

@@ -7,6 +7,9 @@ Templates are JSX expressions interpreted inside a widget-local safety and rende
 - `options.name` — saved widget configuration
 - `inputs.name` — temporary values from declarative `bind`
 
+The v2 manifest supports up to eight sources and 64 requests. Source IDs are case-insensitively unique, and
+the template and secret values have bounded sizes. Validation reports the exact field when a limit is exceeded.
+
 Use normal Mantine layouts, typography, feedback, dates, and charts. Official compound names such as `Card.Section`, `Tabs.List`, and `Radio.Group` are supported. Ordinary safe props pass through; a dangerous capability produces an explicit error.
 
 ## Temporary inputs
@@ -15,7 +18,7 @@ Use normal Mantine layouts, typography, feedback, dates, and charts. Official co
 <Stack>
   <TextInput bind="search" defaultValue="" label="Search" />
   <SubFetch requestId="search" params={{ query: inputs.search }}>
-    {(results) => (
+    {(results, meta) => (
       <Stack>
         {(results ?? []).map((item) => (
           <Text key={item.id}>{item.name}</Text>
@@ -37,7 +40,11 @@ Bounded regex literals are supported for string matching, splitting, search, and
 ## Runtime components
 
 - `SubFetch` runs a manual query with its `params`. Set `triggerContent` to a card or image to make that content the accessible click and keyboard trigger instead of showing the default load button.
-- `ActionButton` and `ToggleSwitch` run actions.
+- `SubFetch` with `trigger="manual"` keeps its result local to that instance; it does not populate the shared
+  `data.requestId` or `status.requestId` roots. The child callback receives `(result, meta)`, while loading, errors, and
+  retry are handled by `SubFetch`. Provide both `triggerContent` and `triggerAriaLabel` when custom content launches it.
+- `ActionButton` and `ToggleSwitch` run actions only when the widget is mounted outside edit mode. A toggle needs both
+  enabled and disabled request parameters and rolls back its visual state if the action fails.
 - `RefreshButton` renders a compact, accessible icon control that refreshes load queries for authenticated viewers. It
   is disabled for anonymous public-board viewers because refreshing invalidates shared server cache state.
 - `Icon`/`TablerIcon` resolves installed safe icons.

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

@@ -63,8 +63,7 @@ only lists Custom Widget MCP tools, prompts, and resources when its owner is an
 
 Adding or configuring a Custom Widget placement requires both administrator access and permission to modify that
 board. A non-administrator with board-modify access can move, resize, change presentation settings, or remove an
-existing placement, but cannot add one, change its definition, refresh interval, or Custom Widget options. Duplicating
-a board that contains Custom Widgets also requires an administrator.
+existing placement, but cannot add one, change its definition, refresh interval, or Custom Widget options.
 
 Once an administrator has placed a widget, ordinary board permissions apply to rendering and requests. Authorized
 non-administrators can use it on private boards, and queries can render for anonymous viewers on public boards.
@@ -99,10 +98,8 @@ logs, or exports.
 For administrators adding widgets while editing a board, the Custom Widgets section includes **Import from
 Workshop**. Non-administrators do not see the Custom Widget picker or Workshop actions. Selecting **Install widget**
 opens a two-step modal flow: first review the Workshop entry and its complete source in the read-only editor, then
-confirm API sources and credentials. The steps keep the same dimensions and the previous step remains available when
-you go back. After import, the new definition appears in the picker. Its tile
-waits for the board to be saved before server requests run and loads automatically after a successful save; no page
-reload is required.
+confirm API sources and credentials. After import, the new definition appears in the picker. Its tile waits for the board
+to be saved before server requests run.
 
 ## Import and Workshop
 

apps/docs/docs/management/mcp.mdx

@@ -23,9 +23,9 @@ approval before running mutating procedures.
 
 ## Getting Started
 
-The MCP endpoint lives under the **API** page at `Management` → `Tools` → `API` → **MCP** tab.
+The MCP endpoint lives under the **API** page at `Management` → `Tools` → `API` → **AI / MCP** tab.
 
-![MCP Instructions Page](./api/img/mcp-instructions.png)
+![AI / MCP tab showing the endpoint, API-key warning, and client configuration](./api/img/mcp-instructions.png)
 
 ### 1. Create an API Key
 

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/beszel-alerts/index.mdx

@@ -34,7 +34,7 @@ This widget displays your Beszel alert configurations separated by status (trigg
   ]}
 />
 
-<WidgetInteractionGuide />
+<WidgetInteractionGuide advancedView={false} />
 
 ### Adding the widget
 

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

@@ -27,6 +27,7 @@ This widget displays a list of torrents or usenet-articles that are currently be
 
 import downloadsCard from "./img/screenshot.png";
 import contextMenuImg from "./img/context-menu.png";
+import advancedViewImg from "./img/advanced-view.png";
 
 <div>
   <img src={downloadsCard} alt="Downloads widget showing torrent and usenet items" width={128 * 4} />
@@ -38,12 +39,22 @@ import contextMenuImg from "./img/context-menu.png";
   <img src={contextMenuImg} alt="Downloads widget 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>
+
 ### 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
 - **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** — pause, resume, delete downloads, or copy download names directly from the context menu
+- **Right-click context menu** — pause, resume, delete downloads, or copy download names directly from the context menu when the selected integration grants interact access
 - **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
@@ -52,6 +63,16 @@ import contextMenuImg from "./img/context-menu.png";
 - **Status indicators** — color-coded badges show download state at a glance
 - **Speed overview** — total download and upload speeds displayed in the footer
 
+:::note
+
+Compact layouts hide secondary columns as width decreases and can hide the footer on very short tiles. Downloads supports
+Advanced view, which restores the denser table, stats, filters, and footer controls in a focused panel.
+
+Pause, resume, delete, and global controls depend on integration permissions. `slskd` is read-only, so its rows expose
+copy and inspection actions instead of mutations.
+
+:::
+
 ### Supported Integrations
 
 <WidgetIntegrations
@@ -89,7 +110,7 @@ import contextMenuImg from "./img/context-menu.png";
 
 ### Interactions
 
-- **Right-click** any download to open a context menu with pause/resume, delete, and copy actions
+- **Right-click** any download to open a context menu with the actions allowed by that integration
 - **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

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

@@ -66,8 +66,7 @@ export const downloadsWidget: WidgetDefinition = {
       },
       {
         name: "Hide completed torrent under this threshold (in kiB/s)",
-        description:
-          "This will hide completed torrent entries that have a download 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",
       },

apps/docs/src/components/widgets/interactions.tsx

@@ -1,10 +1,10 @@
-import { IconArrowsMaximize, IconLayoutGrid, IconMouse2, IconPlus } from "@tabler/icons-react";
+import { IconArrowsMaximize, IconLayoutGrid, IconMouse2 } from "@tabler/icons-react";
 
 const advancedInteraction = {
   icon: IconArrowsMaximize,
   title: "Advanced view",
   description:
-    "Hold Shift while hovering for an in-place preview, press Shift + Enter, or choose Open advanced view from the widget menu.",
+    "On supported widgets, hold Shift while hovering for about 500 ms, press Shift + Enter, or choose Open advanced view from the widget menu. It is unavailable in edit mode.",
 } as const;
 
 const standardInteractions = [
@@ -12,13 +12,7 @@ const standardInteractions = [
     icon: IconMouse2,
     title: "Widget actions",
     description:
-      "Right-click for live query status, refresh, settings, quick options, and actions supported by the widget.",
-  },
-  {
-    icon: IconPlus,
-    title: "Place it precisely",
-    description:
-      "With board changes allowed, right-click or touch and hold empty grid space to add there. Keyboard users can press Shift + F10.",
+      "When signed in, outside edit mode, and with Enable right click on widgets enabled, right-click for live query status, refresh, settings, quick options, and supported actions. App tiles are excluded.",
   },
   {
     icon: IconLayoutGrid,
@@ -35,9 +29,9 @@ export const WidgetInteractionGuide = ({ advancedView = true }: { advancedView?:
     <details className="group my-6 overflow-hidden rounded-xl border border-solid border-[#e5e7eb] bg-slate-50/70 dark:border-[#333] dark:bg-gray-900/40">
       <summary className="flex cursor-pointer list-none items-center justify-between gap-3 px-4 py-3 font-semibold marker:hidden">
         <span>Power-user controls</span>
-        <span className="text-xs font-normal text-[#696969] group-open:hidden dark:text-[#999]">Show shortcuts</span>
+        <span className="text-xs font-normal text-[#696969] group-open:hidden dark:text-[#999]">Show controls</span>
         <span className="hidden text-xs font-normal text-[#696969] group-open:inline dark:text-[#999]">
-          Hide shortcuts
+          Hide controls
         </span>
       </summary>
       <div
@@ -53,8 +47,9 @@ export const WidgetInteractionGuide = ({ advancedView = true }: { advancedView?:
       </div>
       {advancedView && (
         <p className="m-0 px-4 pb-4 text-xs text-[#696969] dark:text-[#999]">
-          Advanced view reuses the widget&apos;s live data and cache. The rest of the board stays visible but dimmed. On
-          touch devices, use the widget menu; compact-only widgets adapt in place instead.
+          Advanced view reuses the widget&apos;s live data and cache. Preview dims the rest of the board; the manual
+          view traps focus and locks background scrolling. On touch devices, use the widget menu where your browser
+          exposes it; compact-only widgets adapt in place instead.
         </p>
       )}
     </details>