docs: finish custom widget coverage

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

@@ -74,14 +74,16 @@ These interfaces do not return an archive URL or archive hash.
 4. Build one definition, using `templateLines` for multiline JSX tool input.
 5. Validate the definition without saving it and repair every reported issue.
 6. Create a preview session.
-7. Run `customWidget_previewQuery` for every query returned by the preview and inspect its actual status and data shape.
+7. Run `customWidget_previewQuery` for every query returned by the preview and inspect its actual status and data shape. Use
+   `{}` for load queries; manual queries require exactly the returned primitive `parameterNames`.
 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. Keep the
-    exact tested preview candidate locally.
-11. Create the widget from that final tested preview with `customWidget_createFromPreview`, including any source URLs and
-    credentials the user already supplied. The create call persists that tested preview and accepts its session ID plus an
-    optional target board.
+    exact tested preview candidate locally. Any definition, template, or source change requires a new validation and preview;
+    earlier query evidence belongs to the previous preview revision.
+11. Create the widget from that final tested preview with `customWidget_createFromPreview`. The preview session already carries
+    the source URLs and encrypted credentials supplied during preview; the create call accepts only its session ID plus an
+    optional target board and persists that tested preview.
 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

@@ -2,10 +2,13 @@
 
 import { CanonicalCustomWidgetExample } from "@site/src/components/custom-widget-code";
 import workbenchImage from "./img/workbench.png";
+import workbenchMobileImage from "./img/workbench-mobile.png";
+import workbenchValidationImage from "./img/workbench-validation.png";
 
-The workbench exposes General, API sources, Requests, Options, JSX, and Preview sections. Advanced JSON is available in the
-manifest and request/option editors. Code and preview sit side by side on desktop; mobile switches between Configure and
-Preview.
+The workbench exposes **General**, **API sources**, **Requests**, **Options**, **JSX**, and **Preview** sections. Advanced JSON is
+available in the manifest and request/option editors. Code and preview sit side by side on desktop; on smaller screens the
+**Configure**/**Preview** switch shows one pane at a time and the section navigation scrolls horizontally. Preview sizes display
+as **S/M/L** (Compact/Standard/Wide), and fixtures are **Live**, **Loading**, **Empty**, or **Error**.
 For multiline JSX, prefer `templateLines` in agent or MCP input and keep the final tested preview as the source of truth before saving.
 
 <img
@@ -14,8 +17,21 @@ For multiline JSX, prefer `templateLines` in agent or MCP input and keep the fin
   style={{ maxWidth: "100%" }}
 />
 
+<img
+  src={workbenchMobileImage}
+  alt="Mobile Custom Widget workbench with Configure and Preview switch and horizontally scrollable section navigation"
+  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.
+journal, fixture data, and preview size before saving. Invalid fields stay marked in the form while the preview explains why it
+needs attention.
+
+<img
+  src={workbenchValidationImage}
+  alt="Custom Widget workbench showing a Base URL validation error with Test, preview, and Create actions disabled"
+  style={{ maxWidth: "100%" }}
+/>
 
 ## Manual workflow
 
@@ -46,7 +62,8 @@ The model must return one fenced `json` block containing the complete widget, in
 field. Copy that single block and select **Paste**. Homarr fills the visual builders and the JSX editor
 without any placeholder replacement or second paste.
 
-Homarr shows all actionable schema or JSX errors inline. Enter credentials separately. The prompt deliberately
+Homarr shows all actionable schema or JSX errors inline. Enter credentials separately. The copied prompt does not include the
+latest preview response; use **Preview** > **Data** to inspect it and mention important response fields in your request. The prompt deliberately
 recommends a focused Mantine component set, visual hierarchy, responsive layout, theme compatibility, and loading,
 empty, failure, and success states.
 

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

@@ -12,6 +12,13 @@ case-insensitively unique. Each request allows up to 32 static headers and 32 in
 up to 24 secrets, each up to 8,192 characters, and templates are limited to 50,000 characters. Validation reports the
 exact field when a limit is exceeded.
 
+Authoring input accepts either `template` or `templateLines`, not both. `templateLines` accepts 1–2,000 lines, each up to
+10,000 characters; after joining lines with newlines, the complete template must still fit the 50,000-character limit.
+
+The safe interpreter also bounds JSX evaluation: AST depth 64, 25,000 operations, 4,000 collection items, 10,000 rendered
+nodes, and 200,000 characters in one string or rendered value. API responses are bounded separately before they reach the
+template.
+
 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.
 Unsafe URLs, callback props, and unapproved style properties are stripped. Response data is deep-sanitized and budgeted
 before it reaches `data`, so treat it as untrusted input even when the source is private.
@@ -45,15 +52,17 @@ than one variable quantifier are rejected.
 
 ## 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.
+- `SubFetch` runs a named query. Automatic queries run when the widget loads; set `trigger="manual"` to defer one and pass
+  primitive `params` for its invocation references. With `triggerContent`, any content node (commonly a card or image) becomes
+  the accessible click and keyboard trigger instead of showing the default load button.
 - `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 invalidates the client's load-query cache; it does not
-  execute a request itself. It is disabled when the widget has no active item or preview session, or while the board is in
-  edit mode.
+- `RefreshButton` renders a compact, accessible icon control that invalidates the client's load-query cache so active load
+  queries can refetch; it does not execute a request itself. It is disabled when the widget has no active item or preview
+  session, or while the board is in edit mode.
 - `Icon`/`TablerIcon` resolves installed safe icons.
 
 Always include responsive loading, empty, error, and success states. Runtime failures remain inside the widget tile.

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

@@ -47,7 +47,9 @@ when [Homarr Assistant](../assistant) is enabled, send the request directly from
 widget schema and current non-secret configuration, but not the latest preview response. It proposes the matching create or
 update tool for your approval.
 
-Run **Test** first when possible so the prompt includes the endpoint's real response shape. Saved secrets are never added to the prompt. **Copy to clipboard** remains available when the Assistant is disabled or when you prefer another AI service.
+Use the preview's **Data** tab to inspect the endpoint's real response shape and mention important fields in your request; the
+copied prompt does not automatically include the latest preview response. Saved secrets are never added to the prompt. **Copy to
+clipboard** remains available when the Assistant is disabled or when you prefer another AI service.
 
 <CustomWidgetCodeExample
   id="complete-widget-manifest"

apps/docs/docs/management/custom-widgets/requests-and-security.mdx

@@ -4,6 +4,8 @@ Most widgets use a single source named `default`; the manifest must contain it.
 that combine APIs. Source IDs are case-insensitively unique. Base URLs must use HTTP(S), contain no embedded credentials,
 query string, or fragment, and sources can be `public`, `private`, or `loopback`. Authentication is `none`, `bearer`,
 `basic`, an API-key header, or an API-key query parameter. Credentials belong to the widget but remain outside its manifest.
+Source origins are fixed by the definition and source-setup flow; widget options and invocation parameters cannot redirect a
+request to a different origin.
 
 ## Named requests
 
@@ -46,6 +48,13 @@ also use structured `json` and `multiSelect` option values, for example `{ "enti
 
 Every request uses Homarr's existing server executor: same-origin source enforcement, network scope, DNS and redirect validation, SSRF protection, board permissions, rate and request limits, body and response limits, timeouts, and encrypted credential injection. Static headers cannot override credentials, cookies, routing, proxy, forwarding, or hop-by-hop headers.
 
+The executor caps request bodies at 10 KiB and response bodies at 1 MiB. Parsed JSON is limited to depth 32 and 50,000 nodes;
+each network hop has a ten-second timeout, queries follow at most three same-origin redirects, actions do not follow redirects,
+and the total request deadline is 45 seconds.
+
+The limiter allows four concurrent requests per user/item and eight per definition. Per minute, a user/item can make up to 60
+queries, 10 actions, or 3 DELETE actions; a definition can receive up to 240, 40, or 12 of those request categories.
+
 Queries default to view permission and actions to modify. DELETE always requires full permission and confirmation. Actions are never cached, retried, or run on load.
 
 Management and runtime are intentionally separate. A Homarr administrator with board-modify permission places and

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

@@ -41,7 +41,8 @@ The workbench marks the invalid field while you type. An invalid URL does not re
 
 An invalid definition disables widget preview and Save/Create. The Data, Options, Actions, and Diagnostics tabs remain available so you can correct it.
 
-The Diagnostics tab shows the current schema errors.
+The Diagnostics tab shows current schema and JSX errors, accessibility checks, and (after a preview) the redacted request
+journal. It does not expose credentials or raw secret values.
 
 ## Workshop unavailable