docs: align v2 stack documentation (#6564)

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

@@ -67,17 +67,23 @@ 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.
 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.
-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. 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

@@ -1,8 +1,37 @@
 # Create a Custom Widget
 
 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 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.
+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
+  src={workbenchImage}
+  alt="Custom Widget workbench with configuration sections and a live preview"
+  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. 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
 
@@ -21,7 +50,9 @@ The workbench is visual-first: configure the default API connection, add request
 
 <CanonicalCustomWidgetExample id="widget-options" label="Widget options" example="options" height="360px" />
 
-Every option has a default. Supported controls include text, textarea, number, switch, select, multi-select, slider, date, time, color, icon, URL, duration, time zone, and JSON. Dynamic choices use `choicesFrom` with a query ID and value/label paths.
+Every option has a default. Supported controls include text, textarea, number, switch, select, multi-select, slider, date, time, color, icon, URL, duration, time zone, and JSON. Dynamic choices use `choicesFrom: { request, itemsPath?, valuePath, labelPath }`; the request must be a load query without invocation parameters, and you cannot provide both static `choices` and `choicesFrom`.
+
+Preview actions are simulated by default and recorded in the journal without contacting the service. Enable **Run actions against the configured API** only when you intend a real mutation; live actions still require configured confirmation.
 
 ## ChatGPT or Claude
 
@@ -31,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

@@ -7,7 +7,21 @@ 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 requires a `default` source and supports up to eight sources, 64 requests, and 64 options. Source IDs are
+case-insensitively unique. Each request allows up to 32 static headers and 32 invalidation targets; a widget can contain
+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.
 
 ## Temporary inputs
 
@@ -15,7 +29,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>
@@ -32,14 +46,23 @@ Bound values live only in React memory while the widget is mounted. They are not
 
 Use expressions, conditionals, optional chaining, arrays, objects, template strings, safe standard helpers, and expression callbacks for `map`, `filter`, `sort`, and trusted runtime slots. Callback blocks, authored `const`, IIFEs, authored recursion, arbitrary functions, imports, hooks, refs, raw events, browser requests, `eval`, and bigint are blocked.
 
-Bounded regex literals are supported for string matching, splitting, search, and replacement. Patterns with lookbehind, backreferences, nested quantifiers, excessive length, or unsupported flags are rejected.
+Bounded regex literals are supported for string matching, splitting, search, and replacement. Regex literals are limited to
+128 characters and flags `gimsu`; lookarounds, backreferences, repeated alternatives/groups, unsupported flags, and more
+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.
-- `ActionButton` and `ToggleSwitch` run actions.
-- `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.
+- `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&apos;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

@@ -42,9 +42,14 @@ interface HomarrCustomWidgetV2 {
 
 ### Design with AI
 
-The **Design with AI** action is available while creating or editing a custom widget. Describe what the widget should show and, when [Homarr Assistant](../assistant) is enabled, send the request directly from the form. The assistant receives the widget schema, current non-secret configuration, and latest test response, then proposes the matching create or update tool for your approval.
+The **Design with AI** action is available while creating or editing a custom widget. Describe what the widget should show and,
+when [Homarr Assistant](../assistant) is enabled, send the request directly from the form. The generated prompt includes the
+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"
@@ -62,9 +67,9 @@ preview, publish, install, configure, or write secrets, including through HTTP a
 only lists Custom Widget MCP tools, prompts, and resources when its owner is an administrator.
 
 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.
+board. Duplicating a board that contains Custom Widgets also requires an administrator. 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.
 
 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 +104,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
 
@@ -131,6 +134,7 @@ replace the v1 backup.
 
 ## Bundled examples
 
-Homarr seeds five disabled examples without credentials and never overwrites an edited seed. They use the same public contract. The Tautulli example is the highest-scoring widget preserved from Homarr's AI authoring evaluation:
+Homarr seeds five disabled examples without credentials and never overwrites an edited seed. They use the same public
+contract. Tautulli Activity is one of the bundled examples preserved from Homarr's AI authoring evaluation:
 
 <BundledCustomWidgetGallery />

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

@@ -1,6 +1,11 @@
 # Configure requests and security
 
-Most widgets use a single source named `default`. Extra keyed sources are available under Advanced for widgets that combine APIs. 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.
+Most widgets use a single source named `default`; the manifest must contain it. Extra keyed sources are available for widgets
+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
 
@@ -35,19 +40,28 @@ Bind values directly where they are used:
 
 `{option:name}` and `$option` read saved widget options. `{param:name}` and `$param` read invocation-time `params`. Load queries cannot use invocation parameters. Homarr infers the exact parameter names and primitive values from these references, rejecting missing or extra invocation params at the request boundary.
 
-Paths and query-string values must resolve to text, numbers, or booleans. JSON bodies can also use structured `json` and `multiSelect` option values, for example `{ "entity_ids": { "$option": "entities" } }`.
+Path placeholders and query values must resolve to text, numbers, or booleans. `$option` and `$param` references may appear
+recursively in JSON bodies; invocation parameters remain primitive, and load queries cannot use `$param`. JSON bodies can
+also use structured `json` and `multiSelect` option values, for example `{ "entity_ids": { "$option": "entities" } }`.
 
 ## Protection
 
 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
 configures the widget. After placement, query and action authorization follows the request's board permission. Public
 boards may execute queries for anonymous viewers, but mutations stay authenticated. This includes shared-cache
-invalidation: `RefreshButton` is disabled for anonymous viewers, while ordinary scheduled query rendering remains
-available.
+invalidation: `RefreshButton` is disabled only without an active item or preview session, or in edit mode, while ordinary
+scheduled query rendering remains available to anonymous viewers.
 
 Responses use bounded, versioned shared-Redis cache keys. Action invalidation advances the shared version so every
 Homarr replica stops serving the previous response without scanning or deleting a key prefix.

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