fix(ci): use pinned pnpm for releases

feat: announce Homarr v2 beta (#6793 )
* feat: announce Homarr v2 beta * chore: refine v2 beta announcement * feat: expand v2 beta guidance * chore: refine v2 beta resources * chore: simplify v2 beta modal * chore: improve v2 beta feedback links * fix: keep v2 modal above header * chore: sharpen v2 beta message * fix: clear header for v2 modal
2026-09-06 21:02:59 +02:00 · 2026-09-06 20:36:04 +02:00 · 2026-09-06 01:52:04 +00:00 · 2026-09-04 15:58:09 +00:00 · 2026-09-03 02:05:21 +00:00 · 2026-09-01 02:36:36 +00:00
151 changed files with 31319 additions and 26941 deletions
@@ -1,6 +1,6 @@
 ---
-description: Comprehensive Homarr codebase architecture and conventions reference
-alwaysApply: true
+name: codebase-context
+description: Comprehensive Homarr codebase architecture and conventions reference. Use when orienting in the monorepo, understanding package dependency layers, the three runtime services and ports, tRPC router structure, multi-database support, widget/integration/cron system architecture, routing, auth providers, env vars, or key patterns before writing code.
 ---

 # Homarr Codebase Context
@@ -27,7 +27,7 @@ Homarr is an open-source, self-hosted dashboard for managing homelab services. I

 ## Repository Structure

-```
+```text
 homarr/
 ├── apps/
 │   ├── nextjs/          # Main Next.js application (port 3000)
@@ -66,8 +66,6 @@ homarr/
 │   ├── analytics/       # Server-side analytics (Umami)
 │   ├── server-settings/ # Server setting keys/types
 │   ├── settings/        # User-facing settings UI context
-│   ├── old-import/      # Legacy Homarr import
-│   ├── old-schema/      # Legacy Homarr zod schemas
 │   └── cli/             # Node CLI for ops (brocli)
 ├── tooling/
 │   ├── typescript/      # Base tsconfig
@@ -79,11 +77,11 @@ homarr/

 ## Three Runtime Services

-| Service | Port | Role |
-|---------|------|------|
-| Next.js | 3000 | Main web app (SSR + API routes) |
-| WebSocket | 3001 | tRPC subscriptions via `ws` |
-| Tasks | 3002 | Cron job runner + management API via Fastify |
+| Service   | Port | Role                                         |
+| --------- | ---- | -------------------------------------------- |
+| Next.js   | 3000 | Main web app (SSR + API routes)              |
+| WebSocket | 3001 | tRPC subscriptions via `ws`                  |
+| Tasks     | 3002 | Cron job runner + management API via Fastify |

 In Docker, nginx listens on **7575** and proxies to all three. The tasks service authenticates via `CRON_JOB_API_KEY` header.

@@ -112,6 +110,7 @@ In Docker, nginx listens on **7575** and proxies to all three. The tasks service
 ### Multi-Database Support

 Drizzle schemas exist in three parallel implementations:
+
 - `packages/db/schema/sqlite.ts`
 - `packages/db/schema/mysql.ts`
 - `packages/db/schema/postgresql.ts`
@@ -121,6 +120,7 @@ Selected at runtime via `DB_DRIVER` env (`better-sqlite3` | `mysql2` | `node-pos
 ### Widget System

 Widgets are registered in `packages/widgets/src/index.tsx` as `widgetImports` (must satisfy `Record<WidgetKind, ...>`). Each widget:
+
 - Has a `definition` created via `createWidgetDefinition(kind, { icon, createOptions, supportedIntegrations? })`
 - Uses `optionsBuilder.from(factory => ({ ... }))` for typed options
 - Loads dynamically via `next/dynamic`
@@ -133,6 +133,7 @@ Integrations are defined in `packages/definitions/src/integration.ts` (`integrat
 ### Cron Job System

 Jobs defined in `packages/cron-jobs/src/jobs/`. Each job:
+
 - Uses `createCronJob` with a cron expression
 - Publishes results to Redis channels
 - Widget subscriptions consume those channels via tRPC subscriptions
@@ -160,6 +161,7 @@ Configured via `AUTH_PROVIDERS` env. Supports: `credentials` (local), `ldap`, `o
 ## Environment Variables

 Key env vars (from `.env.example`):
+
 - `DB_DRIVER`: `better-sqlite3` | `mysql2` | `node-postgres`
 - `DB_URL`: Database connection string
 - `AUTH_SECRET`: NextAuth secret
@@ -191,16 +193,3 @@ Key env vars (from `.env.example`):
 - Drag-and-drop via `@dnd-kit/*`
 - `typescript.ignoreBuildErrors: true` in next.config (types checked separately via `typecheck`)
 - `serverExternalPackages`: `dockerode`, `isomorphic-dompurify`, `jsdom`
-
-## Documentation (`apps/docs`)
-
-Docusaurus 3 site at `apps/docs/`, package name `@homarr/docs`.
-
- Run with `pnpm dev:docs` from root
- Build with `pnpm turbo build --filter=@homarr/docs`
- Uses Tailwind CSS 3 for custom pages (not Mantine)
- Imports `@homarr/definitions` for type-safe integration/widget metadata
- When adding or modifying widgets, integrations, cron jobs, API routes, env vars, or user-facing features, you MUST also update corresponding docs in `apps/docs/docs/`
- Integration docs: `apps/docs/docs/integrations/<slug>/index.mdx` + `index.ts`
- Widget docs: `apps/docs/docs/widgets/<slug>/index.mdx` + `index.ts`
- Strict link checking: broken links/anchors cause build failure
@@ -1,3 +1,8 @@
+---
+name: datatable-migration
+description: Playbook for migrating tables from mantine-react-table (MRT) to mantine-datatable. Use when converting any table component from mantine-react-table to mantine-datatable, working on DataTable column/sort/expansion/context-menu code, or implementing responsive column visibility, column persistence, or transparent tables in widgets.
+---
+
 # Migrating Tables from mantine-react-table to mantine-datatable

 This document captures every pattern, fix, and decision from the downloads widget rework (PR #6430). Use it as a playbook when porting other tables.
@@ -7,10 +12,12 @@ This document captures every pattern, fix, and decision from the downloads widge
 Current `mantine-react-table` consumers that could be migrated:

 **Widgets (in `packages/widgets/`):**
+
 - `docker/component.tsx` — Docker container table
 - `media-server/component.tsx` — Media server sessions

 **Admin pages (in `apps/nextjs/src/app/[locale]/manage/`):**
+
 - `tools/docker/docker-table.tsx`
 - `tools/tasks/_components/tasks-table.tsx`
 - `tools/api/components/api-keys.tsx`
@@ -19,12 +26,12 @@ Current `mantine-react-table` consumers that could be migrated:
 - `tools/kubernetes/` — 8 Kubernetes resource tables

 **Modals:**
+
 - `packages/modals-collection/src/search-engines/request-media-modal.tsx`

 **Shared hook to remove once all migrated:**
- `packages/ui/src/hooks/use-translated-mantine-react-table.ts`

---
+- `packages/ui/src/hooks/use-translated-mantine-react-table.ts`

 ## 1. Core Migration: mantine-react-table → mantine-datatable

@@ -67,6 +74,7 @@ const columns: DataTableColumn<MyRow>[] = [
 ```

 Key differences:
+
 - `accessorKey` → `accessor`
 - `header` → `title`
 - `size` → `width`
@@ -118,8 +126,6 @@ const sortedData = useMemo(() => {
 <DataTable records={sortedData} sortStatus={sortStatus} onSortStatusChange={setSortStatus} />
 ```

---
-
 ## 2. Making Tables Transparent (Widget Context)

 Widgets sit inside board cards that have user-controlled opacity. The table must be fully transparent so the card background shows through. mantine-datatable defaults to `var(--mantine-color-body)` which is opaque.
@@ -144,13 +150,21 @@ Create a CSS file alongside the component:

 /* Hover: translucent instead of opaque */
 .my-table .mantine-datatable-table tbody tr:hover {
-  background-color: color-mix(in srgb, var(--mantine-color-default-hover) 40%, transparent) !important;
+  background-color: color-mix(
+    in srgb,
+    var(--mantine-color-default-hover) 40%,
+    transparent
+  ) !important;
 }

 /* Headers: frosted glass effect */
 .my-table th {
  white-space: nowrap;
-  background-color: color-mix(in srgb, var(--mantine-color-body) 60%, transparent) !important;
+  background-color: color-mix(
+    in srgb,
+    var(--mantine-color-body) 60%,
+    transparent
+  ) !important;
  backdrop-filter: blur(8px);
 }

@@ -172,14 +186,16 @@ Create a CSS file alongside the component:

 /* Row expansion area */
 .my-table .mantine-datatable-row-expansion-cell {
-  background-color: color-mix(in srgb, var(--mantine-color-body) 40%, transparent) !important;
+  background-color: color-mix(
+    in srgb,
+    var(--mantine-color-body) 40%,
+    transparent
+  ) !important;
 }
 ```

 Import it: `import "./styles.css";` and apply via `className="my-table"`.

---
-
 ## 3. Responsive Column Visibility

 Use a lookup table of width breakpoints instead of media queries. The widget receives `width` as a prop.
@@ -195,11 +211,38 @@ interface SizeConfig {
 }

 const SIZE_BREAKPOINTS: { maxWidth: number; config: SizeConfig }[] = [
-  { maxWidth: 300, config: { fontSize: "xs", iconSize: 12, cellPadding: 2, showSpeedColumns: false, showTimeColumn: false, showStateColumn: false } },
-  { maxWidth: 500, config: { fontSize: "xs", iconSize: 14, cellPadding: 4, showSpeedColumns: false, showTimeColumn: true, showStateColumn: false } },
+  {
+    maxWidth: 300,
+    config: {
+      fontSize: "xs",
+      iconSize: 12,
+      cellPadding: 2,
+      showSpeedColumns: false,
+      showTimeColumn: false,
+      showStateColumn: false,
+    },
+  },
+  {
+    maxWidth: 500,
+    config: {
+      fontSize: "xs",
+      iconSize: 14,
+      cellPadding: 4,
+      showSpeedColumns: false,
+      showTimeColumn: true,
+      showStateColumn: false,
+    },
+  },
 ];

-const DEFAULT_SIZE_CONFIG: SizeConfig = { fontSize: "sm", iconSize: 14, cellPadding: 4, showSpeedColumns: true, showTimeColumn: true, showStateColumn: true };
+const DEFAULT_SIZE_CONFIG: SizeConfig = {
+  fontSize: "sm",
+  iconSize: 14,
+  cellPadding: 4,
+  showSpeedColumns: true,
+  showTimeColumn: true,
+  showStateColumn: true,
+};

 function getSizeConfig(width: number): SizeConfig {
  for (const { maxWidth, config } of SIZE_BREAKPOINTS) {
@@ -215,7 +258,9 @@ const size = useMemo(() => getSizeConfig(width), [width]);
 Then use a visibility check lookup table for columns:

 ```typescript
-const columnVisibilityChecks: Partial<Record<string, (ctx: ColumnContext) => boolean>> = {
+const columnVisibilityChecks: Partial<
+  Record<string, (ctx: ColumnContext) => boolean>
+> = {
  upSpeed: (ctx) => ctx.hasTorrents && ctx.size.showSpeedColumns,
  downSpeed: (ctx) => ctx.size.showSpeedColumns,
  time: (ctx) => ctx.size.showTimeColumn,
@@ -230,8 +275,6 @@ function shouldIncludeColumn(accessor: string, ctx: ColumnContext): boolean {
 }
 ```

---
-
 ## 4. Column Persistence (Drag/Resize → Server)

 `useDataTableColumns` stores column order and widths in localStorage by default. For widgets, this must persist server-side so it works across devices.
@@ -263,15 +306,6 @@ Even hidden options need translation keys or the translation test fails:
 "widget.mywidget.option.columnWidths.label": "Column widths"
 ```

-### Old-import mappings
-
-Add to `packages/old-import/src/widgets/options.ts`:
-
-```typescript
-columnOrder: () => undefined,
-columnWidths: () => undefined,
-```
-
 ### Dynamic storeKey

 Use a key that includes `itemId` and sorted column names. This prevents cross-widget localStorage bleeding:
@@ -285,8 +319,13 @@ const storeKey = `mytable-${itemId ?? "preview"}-${[...options.columns].toSorted
 On mount, seed `useDataTableColumns` with server-persisted values. Use a `hydrated` ref to prevent the persist effect from immediately writing defaults back:

 ```typescript
-const { effectiveColumns, columnsOrder, columnsWidth, setColumnsOrder, setMultipleColumnWidths } =
-  useDataTableColumns<MyRow>({ key: storeKey, columns });
+const {
+  effectiveColumns,
+  columnsOrder,
+  columnsWidth,
+  setColumnsOrder,
+  setMultipleColumnWidths,
+} = useDataTableColumns<MyRow>({ key: storeKey, columns });

 const lastStoreKey = useRef(storeKey);
 const hydrated = useRef(false);
@@ -300,11 +339,22 @@ useEffect(() => {
  if (savedOrder.length > 0) setColumnsOrder(savedOrder);
  if (Object.keys(savedWidths).length > 0) {
    setMultipleColumnWidths(
-      Object.entries(savedWidths).map(([accessor, w]) => ({ accessor, width: w })),
+      Object.entries(savedWidths).map(([accessor, w]) => ({
+        accessor,
+        width: w,
+      })),
    );
  }
-  requestAnimationFrame(() => { hydrated.current = true; });
-}, [storeKey, savedOrder, savedWidths, setColumnsOrder, setMultipleColumnWidths]);
+  requestAnimationFrame(() => {
+    hydrated.current = true;
+  });
+}, [
+  storeKey,
+  savedOrder,
+  savedWidths,
+  setColumnsOrder,
+  setMultipleColumnWidths,
+]);
 ```

 ### Persist localStorage → server
@@ -317,22 +367,26 @@ const prevWidths = useRef(columnsWidth);

 useEffect(() => {
  if (!hydrated.current) return;
-  const orderChanged = JSON.stringify(columnsOrder) !== JSON.stringify(prevOrder.current);
-  const widthsChanged = JSON.stringify(columnsWidth) !== JSON.stringify(prevWidths.current);
+  const orderChanged =
+    JSON.stringify(columnsOrder) !== JSON.stringify(prevOrder.current);
+  const widthsChanged =
+    JSON.stringify(columnsWidth) !== JSON.stringify(prevWidths.current);
  prevOrder.current = columnsOrder;
  prevWidths.current = columnsWidth;

  if (!orderChanged && !widthsChanged) return;

-  if (orderChanged) persistOption({ columnOrder: JSON.stringify(columnsOrder) });
+  if (orderChanged)
+    persistOption({ columnOrder: JSON.stringify(columnsOrder) });
  if (widthsChanged) {
    const widthMap: Record<string, number> = {};
    for (const entry of columnsWidth) {
      const key = Object.keys(entry)[0];
      if (!key) continue;
-      const w = entry[key as keyof typeof entry];
-      if (typeof w === "number") widthMap[key] = w;
-      else if (typeof w === "string" && w.endsWith("px")) widthMap[key] = parseInt(w, 10);
+      const v = entry[key as keyof typeof entry];
+      if (typeof v === "number") widthMap[key] = v;
+      else if (typeof v === "string" && v.endsWith("px"))
+        widthMap[key] = parseInt(v, 10);
    }
    persistOption({ columnWidths: JSON.stringify(widthMap) });
  }
@@ -341,8 +395,6 @@ useEffect(() => {

 The `persistOption` helper calls both `setOptions` (local state) and `saveItemOptions` (server mutation).

---
-
 ## 5. Context Menu (Right-Click)

 Do NOT install `mantine-contextmenu`. Use Mantine's `Menu` + `Portal` directly:
@@ -374,15 +426,41 @@ const handleContextMenu = useCallback(
 The menu component uses `Portal` for correct z-index:

 ```tsx
-function RowContextMenu({ state, onClose }: { state: ContextMenuState; onClose: () => void }) {
+function RowContextMenu({
+  state,
+  onClose,
+}: {
+  state: ContextMenuState;
+  onClose: () => void;
+}) {
  return (
    <Portal>
-      <Menu opened onClose={onClose} closeOnItemClick={false} position="right-start" offset={0}>
+      <Menu
+        opened
+        onClose={onClose}
+        closeOnItemClick={false}
+        position="right-start"
+        offset={0}
+      >
        <Menu.Target>
-          <Box style={{ position: "fixed", left: state.x, top: state.y, width: 0, height: 0 }} />
+          <Box
+            style={{
+              position: "fixed",
+              left: state.x,
+              top: state.y,
+              width: 0,
+              height: 0,
+            }}
+          />
        </Menu.Target>
        <Menu.Dropdown>
-          <Menu.Item onClick={() => { /* action */ onClose(); }}>Action</Menu.Item>
+          <Menu.Item
+            onClick={() => {
+              /* action */ onClose();
+            }}
+          >
+            Action
+          </Menu.Item>
        </Menu.Dropdown>
      </Menu>
    </Portal>
@@ -392,8 +470,6 @@ function RowContextMenu({ state, onClose }: { state: ContextMenuState; onClose:

 **Key fix:** Use `closeOnItemClick={false}` if any menu item needs a two-step confirmation (like delete → confirm). Close the menu on scroll: `onScroll={() => { if (contextMenu) closeContextMenu(); }}`.

---
-
 ## 6. Row Expansion

 ```typescript
@@ -413,8 +489,6 @@ function RowContextMenu({ state, onClose }: { state: ContextMenuState; onClose:

 **Critical:** Do NOT set `onRowClick` when using `rowExpansion` with `trigger: "click"`. They conflict and the expansion won't work.

---
-
 ## 7. Common Pitfalls & Fixes

 ### Status indicator dots
@@ -475,8 +549,11 @@ Always wrap in try/catch:
 ```typescript
 function parseJsonOption<T>(value: string | undefined, fallback: T): T {
  if (!value) return fallback;
-  try { return JSON.parse(value) as T; }
-  catch { return fallback; }
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return fallback;
+  }
 }
 ```

@@ -494,20 +571,19 @@ If the widget has configurable default sort, sync it:

 ```typescript
 useEffect(() => {
-  setSortStatus({ columnAccessor: options.defaultSort, direction: defaultSortDirection });
+  setSortStatus({
+    columnAccessor: options.defaultSort,
+    direction: defaultSortDirection,
+  });
 }, [options.defaultSort, defaultSortDirection]);
 ```

---
-
 ## 8. Accessibility

 - All `ActionIcon` components need `aria-label`
 - Filter toggles (client badges, status badges) need `aria-pressed={isActive}`
 - `textSelectionDisabled` on DataTable prevents accidental text selection during drag/resize

---
-
 ## 9. Error Handling

 - Every mutation needs an `onError` callback with `showErrorNotification`
@@ -518,12 +594,14 @@ useEffect(() => {
 ```typescript
 const mutationOptions = {
  onSettled: () => void utils.myQuery.invalidate(),
-  onError: () => showErrorNotification({ title: t("errors.actionFailed"), message: t("errors.actionFailedMessage") }),
+  onError: () =>
+    showErrorNotification({
+      title: t("errors.actionFailed"),
+      message: t("errors.actionFailedMessage"),
+    }),
 };
 ```

---
-
 ## 10. i18n

 - No hardcoded strings. Every user-visible string goes through `useScopedI18n`
@@ -534,8 +612,6 @@ const mutationOptions = {
 - Errors: `t("errors.{errorKey}")`
 - Hidden options still need `.label` translation keys

---
-
 ## 11. Edit Mode

 Disable pointer events on the table during edit mode to prevent conflicts with the board's drag-and-drop:
@@ -550,8 +626,6 @@ if (isEditMode) rowContextMenuHandler = undefined;
 <DataTable style={{ pointerEvents: tablePointerEvents }} />
 ```

---
-
 ## 12. DataTable Props Reference (Commonly Used)

 ```typescript
@@ -590,8 +664,6 @@ if (isEditMode) rowContextMenuHandler = undefined;
 />
 ```

---
-
 ## 13. Layout Stability

 - Don't use `table-layout: fixed` — it fights mantine-datatable's resize logic
@@ -600,8 +672,6 @@ if (isEditMode) rowContextMenuHandler = undefined;
 - Names should truncate at the cell boundary, not a character count, so the layout is stable regardless of content length
 - `flexShrink: 0` on badges/icons prevents them from being squeezed by long names

---
-
 ## 14. Checklist for Each Migration

 1. Replace imports (`mantine-react-table` → `mantine-datatable`)
@@ -610,13 +680,12 @@ if (isEditMode) rowContextMenuHandler = undefined;
 4. Add CSS file for transparent backgrounds (if widget context)
 5. Add responsive column visibility (if widget context)
 6. Add hidden options + hydration logic (if column persistence needed)
-7. Add old-import mappings for new options
-8. Add translation keys (including hidden option labels)
-9. Add context menu if row actions exist
-10. Add row expansion if detail view exists
-11. Add error handling on all mutations
-12. Add accessibility attributes
-13. Test at multiple widget widths
-14. Update docs in `apps/docs/docs/widgets/` if applicable
-15. Run `pnpm turbo typecheck` — catches old-import mismatches
-16. Run translation spec — catches missing keys
+7. Add translation keys (including hidden option labels)
+8. Add context menu if row actions exist
+9. Add row expansion if detail view exists
+10. Add error handling on all mutations
+11. Add accessibility attributes
+12. Test at multiple widget widths
+13. Update docs in `apps/docs/docs/widgets/` if applicable
+14. Run `pnpm turbo typecheck`
+15. Run translation spec — catches missing keys
@@ -0,0 +1,44 @@
+---
+name: documentation-sync
+description: Keep Homarr documentation in sync with code changes. Use when modifying code that affects user-facing behavior, or when adding/modifying widgets, integrations, cron jobs, API routes, env vars, permissions, auth providers, or UI in apps/docs. Covers the docs/ mapping table, integration doc pattern, and widget doc pattern.
+---
+
+# Documentation Sync
+
+When modifying code that affects user-facing behavior, you MUST also update the documentation in `apps/docs/`.
+
+## What triggers a doc update
+
+| Code change            | Doc location                                                |
+| ---------------------- | ----------------------------------------------------------- |
+| New integration        | `apps/docs/docs/integrations/<slug>/index.mdx` + `index.ts` |
+| New widget             | `apps/docs/docs/widgets/<slug>/index.mdx` + `index.ts`      |
+| Changed API surface    | `apps/docs/docs/management/api.mdx`                         |
+| New/changed env vars   | `apps/docs/docs/advanced/`                                  |
+| New CLI commands       | `apps/docs/docs/advanced/command-line/`                     |
+| Changed auth providers | `apps/docs/docs/advanced/` SSO pages                        |
+| UI/UX changes          | Relevant getting-started or management pages                |
+| New cron job           | `apps/docs/docs/management/tasks.mdx`                       |
+| Changed permissions    | `apps/docs/docs/management/users.mdx`                       |
+
+## Integration doc pattern
+
+Each integration has a folder under `apps/docs/docs/integrations/<slug>/`:
+
+- `index.ts` — exports a typed `IntegrationDefinition` with name, description, iconUrl, path
+- `index.mdx` — uses shared components: `IntegrationHeader`, `IntegrationCapabilites`, `IntegrationSecrets`
+- Import metadata from `@homarr/definitions` where possible
+
+## Widget doc pattern
+
+Each widget has a folder under `apps/docs/docs/widgets/<slug>/`:
+
+- `index.ts` — exports a typed `WidgetDefinition` with icon, name, description, path, configuration
+- `index.mdx` — uses shared components: `WidgetHeader`, `WidgetConfig`, `WidgetAdding`
+
+## Development
+
+- Run docs locally: `pnpm dev:docs` from root
+- Build docs: `pnpm turbo build --filter=@homarr/docs`
+- The docs app can import from `@homarr/definitions` for type-safe integration/widget metadata
+- Docusaurus strict mode throws on broken links — fix any broken references before committing
@@ -1,13 +1,14 @@
 ---
-description: How to expose tRPC procedures as MCP tools for AI clients
-globs: packages/api/src/router/**/*.ts
-alwaysApply: false
+name: mcp-integration
+description: Expose tRPC procedures as MCP tools for AI clients. Use when modifying procedures in packages/api/src/router, adding a new tRPC procedure or router, or deciding what to expose via Homarr's MCP interface. Covers .meta({ mcp }), router registration in packages/api/src/mcp.ts, input schema rules, and what to expose vs skip.
 ---

-# MCP Integration Guide
+# MCP Integration

 Every new tRPC procedure that provides useful functionality should be exposed as an MCP tool so AI assistants (Claude, Cursor, etc.) can use it. This is a first-class feature of Homarr.

+Exposing a procedure makes it callable by any AI client with an API key. Before adding `.meta({ mcp })`, review what the tool exposes: authorization requirements, sensitive data, tenant isolation, auditability, and whether the action is destructive. Prefer exposing read-only queries over mutations unless the mutation is safe and permission-scoped. When in doubt, ask for a security review before shipping a new MCP tool.
+
 ## Adding MCP to a procedure

 Add `.meta({ mcp: { enabled: true, description: "..." } })` to the procedure chain:
@@ -16,7 +17,7 @@ Add `.meta({ mcp: { enabled: true, description: "..." } })` to the procedure cha
 // Read-only tool (query)
 myProcedure: protectedProcedure
  .meta({ mcp: { enabled: true, description: "Get all items with their status and metadata" } })
-  .input(z.object({ limit: z.number().default(50) }))
+  .input(z.object({ limit: z.number().default(10) }))
  .query(async ({ ctx, input }) => { ... })

 // Write tool (mutation)
@@ -38,23 +39,27 @@ The `.meta()` call must come **before** `.input()` and `.query()`/`.mutation()`
 The description is the **only thing** an AI sees to decide when and how to use the tool. Write it like you're explaining to a colleague who has never used Homarr.

 **Must include:**
+
 - What the tool returns or does
 - Which integrations/services it works with (if applicable)
 - How to get required IDs (e.g., "Use integration_all to get the integrationId")
 - Permission requirements (if non-obvious)

 **Good:**
-```
+
+```text
 "Get calendar events for upcoming and recent media releases. Fetches from all connected Sonarr (TV), Radarr (movies), Lidarr (music), and Readarr (books) integrations. Requires integrationIds from integration_all"
 ```

 **Bad:**
-```
+
+```text
 "Get calendar events"
 ```

 **For tools that return permission fields**, explain what they mean:
-```
+
+```text
 "List all integrations. Returns permissions.hasUseAccess (read) and permissions.hasInteractAccess (actions) — false means the API key lacks that permission, not an error"
 ```

@@ -77,11 +82,13 @@ export const mcpRouter = createTRPCRouter({
 ## What to expose vs. what to skip

 **Expose:**
+
 - Data queries (list, search, get by ID)
 - Actions users would ask an AI to do (toggle, create, delete, approve)
 - Status checks (health, stats, summaries)

 **Skip:**
+
 - Subscriptions (WebSocket-only, not supported by MCP)
 - Internal procedures (session management, onboarding steps)
 - File upload/download procedures
@@ -0,0 +1 @@
+../.agents/skills
@@ -1,50 +0,0 @@
---
-description: Keep documentation in sync with code changes
-globs:
-  - packages/definitions/src/**
-  - packages/widgets/src/**
-  - packages/integrations/src/**
-  - packages/api/src/**
-  - apps/nextjs/src/**
-  - apps/docs/**
---
-
-# Documentation Sync Rule
-
-When modifying code that affects user-facing behavior, you MUST also update the documentation in `apps/docs/`.
-
-## What triggers a doc update
-
-| Code change | Doc location |
-|---|---|
-| New integration | `apps/docs/docs/integrations/<slug>/index.mdx` + `index.ts` |
-| New widget | `apps/docs/docs/widgets/<slug>/index.mdx` + `index.ts` |
-| Changed API surface | `apps/docs/docs/management/api.mdx` |
-| New/changed env vars | `apps/docs/docs/advanced/` |
-| New CLI commands | `apps/docs/docs/advanced/command-line/` |
-| Changed auth providers | `apps/docs/docs/advanced/` SSO pages |
-| UI/UX changes | Relevant getting-started or management pages |
-| New cron job | `apps/docs/docs/management/tasks.mdx` |
-| Changed permissions | `apps/docs/docs/management/users.mdx` |
-
-## Integration doc pattern
-
-Each integration has a folder under `apps/docs/docs/integrations/<slug>/`:
-
- `index.ts` — exports a typed `IntegrationDefinition` with name, description, iconUrl, path
- `index.mdx` — uses shared components: `IntegrationHeader`, `IntegrationCapabilites`, `IntegrationSecrets`
- Import metadata from `@homarr/definitions` where possible
-
-## Widget doc pattern
-
-Each widget has a folder under `apps/docs/docs/widgets/<slug>/`:
-
- `index.ts` — exports a typed `WidgetDefinition` with icon, name, description, path, configuration
- `index.mdx` — uses shared components: `WidgetHeader`, `WidgetConfig`, `WidgetAdding`
-
-## Development
-
- Run docs locally: `pnpm dev:docs` from root
- Build docs: `pnpm turbo build --filter=@homarr/docs`
- The docs app can import from `@homarr/definitions` for type-safe integration/widget metadata
- Docusaurus strict mode throws on broken links — fix any broken references before committing
@@ -33,6 +33,10 @@ body:
      options:
        # The below comment is used to insert a new version with on-release.yml
        #NEXT_VERSION#
+        - 1.76.2
+        - 1.76.1
+        - 1.76.0
+        - 1.75.0
        - 1.74.0
        - 1.73.0
        - 1.72.0
@@ -0,0 +1,131 @@
+name: Homarr v2 beta feedback
+description: Report a specific bug, unexpected behavior, or improvement for the Homarr v2 beta
+title: "feedback(v2): "
+labels: ["needs triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for testing Homarr v2. It will become the default when it is ready, and every detailed report helps us get there.
+
+        We cannot guess what you wanted from “this looks wrong.” Tell us exactly which feature is affected, what happened, why it is wrong for your use case, and what you expected instead. Add screenshots or a short recording whenever possible.
+
+        **Not useful:** “The board looks wrong.”
+
+        **Useful:** “The container changes from four columns to three after I move a widget at 1440 × 900 and 100% browser zoom. I expected it to keep four columns.”
+
+  - type: dropdown
+    id: feedback-type
+    attributes:
+      label: Feedback type
+      options:
+        - Bug
+        - Upgrade or migration
+        - Usability or design
+        - Performance
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Homarr v2 version or image tag
+      description: Copy the version from the About page or provide the exact Docker image tag you tested.
+      placeholder: ghcr.io/homarr-labs/homarr-test:v2
+    validations:
+      required: true
+
+  - type: input
+    id: affected-area
+    attributes:
+      label: Affected page, feature, or widget
+      description: Name the exact page, widget, integration, container, sidebar, or action involved.
+      placeholder: "Board editor: moving a widget into a container"
+    validations:
+      required: true
+
+  - type: textarea
+    id: behavior
+    attributes:
+      label: What happened, why is it wrong, and what should happen instead?
+      description: Describe the actual result, why it does not work for you, and the exact result you expected.
+      placeholder: |
+        What happened:
+        Why this is wrong for my use case:
+        What I expected instead:
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Exact steps to reproduce
+      description: Start from the page you opened and list every click, keypress, drag, setting, and value needed to reproduce it.
+      placeholder: |
+        1. Open...
+        2. Set...
+        3. Drag or click...
+        4. Observe...
+    validations:
+      required: true
+
+  - type: textarea
+    id: visual-evidence
+    attributes:
+      label: Screenshots or screen recordings
+      description: Drag screenshots or a recording into this field. Include the full page for context and a close-up of the problem. Blur secrets and personal data. If you cannot add visuals, explain why.
+      placeholder: Drag screenshots or a recording here, or explain why none are available.
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Device and Homarr environment
+      description: Provide every detail that could affect the result.
+      placeholder: |
+        Device type and model:
+        Operating system and version:
+        Browser and version:
+        Installation method (Docker, Unraid, Kubernetes, other):
+        Database (SQLite, MySQL, PostgreSQL):
+        Reverse proxy and version, if used:
+    validations:
+      required: true
+
+  - type: textarea
+    id: board-context
+    attributes:
+      label: Board and display context
+      description: Include the layout details even when you are not sure they matter.
+      placeholder: |
+        Display resolution:
+        Browser zoom:
+        Desktop or mobile layout:
+        Board column count:
+        Approximate number of items:
+        Container or sidebar nesting:
+        Relevant board or widget settings:
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional-information
+    attributes:
+      label: Logs and additional information
+      description: Add relevant browser console errors, Homarr logs, integration details, or anything else that may help. Remove secrets and personal information first.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I added screenshots or a recording where possible, or explained why I could not.
+          required: true
+        - label: I described both what happened and the exact result I expected.
+          required: true
+        - label: I searched the existing issues for the same feedback.
+          required: true
+        - label: I removed passwords, API keys, tokens, and other private information.
+          required: true
@@ -68,8 +68,6 @@ jobs:
        with:
          node-version: 24.18.0
          package-manager-cache: false
-      - run: npm i -g pnpm
-        if: env.SKIP_RELEASE == 'false'
      - name: Install dependencies
        if: env.SKIP_RELEASE == 'false'
        run: |
@@ -71,7 +71,8 @@ apps/nextjs/public/images/background.png

 # personal agent config
 .opencode
-.agents/
+.agents/*
+!.agents/skills/
 skills-lock.json

 # docusaurus
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "mantine": {
+      "command": "npx",
+      "args": ["-y", "@mantine/mcp-server"]
+    }
+  }
+}
@@ -84,6 +84,16 @@ When modifying user-facing code, you MUST also update the corresponding document
 - Lint: oxlint (not ESLint)
 - Format: oxfmt (not Prettier)
 - UI: Mantine (not Tailwind) — Tailwind is only used in docs app
+- Mantine: use the `mantine` MCP server (configured in `.mcp.json`; tools `get_item_doc` / `get_item_props` / `search_docs`) for current v9 APIs before writing component code. Prefer built-in primitives (`Combobox`/`useCombobox` for selects, the polymorphic `component` prop, `@mantine/hooks`) over hand-rolled equivalents. Check `packages/ui/` for existing conventions first.
+
+## MCP servers
+
+`.mcp.json` at the repo root declares project-scoped MCP servers (the standard Claude Code layout; other tools can import the same `mcpServers` block). See the `mantine` entry there for the Mantine v9 server, and the upstream docs at https://mantine.dev/guides/llms/ for per-tool setup (OpenCode: `.opencode/opencode.json`, Codex: `.codex/config.toml`). Only keyless server definitions belong in `.mcp.json`; anything needing secrets stays in local dotfiles.
+
+## Agent Skills
+
+Portable agent skills live in `.agents/skills/` (the Agent Skills open standard). Cursor, Codex, and OpenCode read `.agents/skills/` natively. Claude Code does not scan it, so `.claude/skills/` is a symlink back to `.agents/skills/`. Install skills at `.agents/skills/<name>/SKILL.md` — that single copy is used everywhere. See `.agents/skills/` for available skills (documentation-sync, mcp-integration, codebase-context, datatable-migration).
+
 - Icons: @tabler/icons-react
 - Docs app can import from `@homarr/definitions` for shared types
 - Run `pnpm dev:cli -- dev` to browse local `homarr:*` images and remote PR images.
@@ -1,3 +1,11 @@
+## [1.76.2](https://github.com/homarr-labs/homarr/compare/v1.76.1...v1.76.2) (2026-08-27)
+
+## [1.76.1](https://github.com/homarr-labs/homarr/compare/v1.76.0...v1.76.1) (2026-08-26)
+
+## [1.76.0](https://github.com/homarr-labs/homarr/compare/v1.75.0...v1.76.0) (2026-08-21)
+
+## [1.75.0](https://github.com/homarr-labs/homarr/compare/v1.74.0...v1.75.0) (2026-08-14)
+
 ## [1.74.0](https://github.com/homarr-labs/homarr/compare/v1.73.0...v1.74.0) (2026-08-07)

 ## [1.73.0](https://github.com/homarr-labs/homarr/compare/v1.72.0...v1.73.0) (2026-07-31)
@@ -206,6 +206,14 @@ packages/integrations/src/unraid @manuel-rw
 apps/docs/docs/integrations/uptime-kuma @ajnart
 packages/integrations/src/uptime-kuma @ajnart

+# What's Up Docker (WUD) - introduced in https://github.com/homarr-labs/homarr/pull/6523 by @tiimonn
+apps/docs/docs/integrations/whats-up-docker @tiimonn
+apps/docs/docs/widgets/whats-up-docker @tiimonn
+packages/api/src/router/widgets/wud.ts @tiimonn
+packages/integrations/src/wud @tiimonn
+packages/request-handler/src/wud.ts @tiimonn
+packages/widgets/src/wud @tiimonn
+
 # Traefik - by @Nerdy-Technician
 apps/docs/docs/integrations/traefik @Nerdy-Technician
 apps/docs/docs/widgets/traefik @Nerdy-Technician
@@ -55,8 +55,8 @@ pnpm typecheck
 docs/
 ├── getting-started/    # Installation guides, glossary, prerequisites
 ├── management/         # Boards, apps, users, integrations, settings, tasks, API
-├── integrations/       # 55 integration guides (one folder each)
-├── widgets/            # 42 widget guides (one folder each)
+├── integrations/       # 56 integration guides (one folder each)
+├── widgets/            # 43 widget guides (one folder each)
 ├── advanced/           # SSO, env vars, proxy, styling, CLI, development
 └── community/          # FAQ, donate, license, translations, get-in-touch
 ```
@@ -9,17 +9,19 @@ tags:
 ---

 ## Icon picker
+
 Icons in Homarr are automatically requested from multiple sources:
-  - [Dashboard Icons](https://dashboardicons.com/) - Our recommended source with over 1888+ curated, high-quality icons
-  - [selfh.st icons](https://github.com/selfhst/icons)
-  - [Simple icons](https://github.com/simple-icons/simple-icons)
-  - [Tabler icons](https://tabler-icons.io/)
-  - [Papirus icons](https://github.com/PapirusDevelopmentTeam/papirus-icon-theme)
-  - [Homelab Svg assets](https://github.com/loganmarchione/homelab-svg-assets)
-  - **Local icons**: automatically fetched from the [medias feature](/docs/management/media/)
+
+- [Dashboard Icons](https://dashboardicons.com/) - Our recommended source with more than 1,888 curated, high-quality icons
+- [selfh.st icons](https://github.com/selfhst/icons)
+- [Simple icons](https://github.com/simple-icons/simple-icons)
+- [Tabler icons](https://tabler-icons.io/)
+- [Papirus icons](https://github.com/PapirusDevelopmentTeam/papirus-icon-theme)
+- [Homelab Svg assets](https://github.com/loganmarchione/homelab-svg-assets)
+- **Local icons**: automatically fetched from the [medias feature](/docs/management/media/)

 Using these icon sources, Homarr provides a total collection of over 11,000 icons at your fingertips.
-The icon picker is a fast searcher that helps you to find your desired icon simply by entering a search term.
+The image picker searches this collection after a short typing delay. When a name is available, such as an app or search engine name, the picker uses it as the initial search. Results show your locally uploaded images first, followed by SVG icons and then other image formats.

 ### Finding Missing Icons

@@ -29,6 +31,13 @@ If you can't find the icon you're looking for in Homarr's built-in picker, we st

 Icons that are high quality and printable ([SVG](https://wikipedia.org/wiki/Scalable_Vector_Graphics)) are marked with a red badge "SVG" at the top right.

+You can clear the selected image with the clear button or the usual keyboard shortcut for deleting a line (Command+Backspace on macOS or Control+Backspace on other platforms). Clearing the field does not restore the previous image.
+
 ### Using external icons
+
 If you don't find the icon you're looking for on Dashboard Icons or wish to use a different source, you can simply enter a URL that points to an icon.
-Direct HTTP(S) image URLs are used as entered instead of being searched in the built-in repositories. It is important that the URL directly points to the file without any advertisements or elements around it.
+Direct HTTP(S) image URLs are used as entered instead of being searched in the built-in repositories. The picker previews the image and shows whether it loaded successfully. It is important that the URL directly points to the file without any advertisements or elements around it.
+
+### Uploading a local image
+
+Users with media upload permission can select **Upload image** next to the field. After the upload finishes, the new local image is selected immediately and is available at the top of future searches.
@@ -11,6 +11,12 @@ tags:
 import Link from '@docusaurus/Link';
 import { IconArrowRight } from '@tabler/icons-react';

+:::info Homarr v2 beta is available
+
+We've been working on Homarr's v2 update for a while now. There is no fixed release date yet, it will be ready when it's ready. We **need your help** and feedback to help us become confident enough to release it for everyone. Read [what is new](https://v2.preview.homarr.dev/blog/2026/09/03/homarr-2.0), browse the [v2 documentation](https://v2.preview.homarr.dev/docs/getting-started/) and [Workshop](https://v2.preview.homarr.dev/workshop), or try the [hosted preview](https://app-v2.preview.homarr.dev). If anything breaks or does not feel right, [tell us on Discord](https://discord.com/invite/aCsmEV5RgA) in the dedicated v2 channel for the fastest response, or [open a dedicated GitHub issue](https://github.com/homarr-labs/homarr/issues/new?template=v2_beta_feedback.yml). SQLite administrators can download a full backup directly from the beta announcement before changing images.
+
+:::
+
 Before you try to install Homarr, please review if your device meets the requirements.
 Installing on an unsupported device may lead to unstable behaviour and no support will be provided.

@@ -2,9 +2,9 @@

 <img src="https://raw.githubusercontent.com/homarr-labs/charts/refs/heads/main/charts/homarr/icon.svg" align="right" width="92" alt="homarr logo">

-![Version: 8.26.0](https://img.shields.io/badge/Version-8.26.0-informational?style=flat)
+![Version: 8.28.1](https://img.shields.io/badge/Version-8.28.1-informational?style=flat)
 ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat)
-![AppVersion: v1.74.0](https://img.shields.io/badge/AppVersion-v1.74.0-informational?style=flat)
+![AppVersion: v1.76.1](https://img.shields.io/badge/AppVersion-v1.76.1-informational?style=flat)

 A Helm chart to deploy homarr for Kubernetes

@@ -429,7 +429,7 @@ All available values are listed on the [artifacthub](https://artifacthub.io/pack
 | httproute.rules[0].matches[0].path.value | string | `"/"` | Path value to match |
 | image.pullPolicy | string | `"IfNotPresent"` | Image pull policy |
 | image.repository | string | `"ghcr.io/homarr-labs/homarr"` | Image repository |
-| image.tag | string | `"v1.74.0"` | Overrides the image tag whose default is the chart appVersion |
+| image.tag | string | `"v1.76.1"` | Overrides the image tag whose default is the chart appVersion |
 | imagePullSecrets | list | `[]` | Secrets for Docker registry |
 | ingress.annotations | object | `{}` | Ingress annotations |
 | ingress.enabled | bool | `false` | Enable ingress |
@@ -27,6 +27,8 @@ import Alert from '@theme/Admonition';
      ]}
 />

+The storage values shown by these widgets come from each pool's root ZFS dataset, so they already account for RAIDZ parity overhead and dataset limits and match what `zfs list` and the TrueNAS web interface report. When a pool cannot report its dataset space, Homarr falls back to the pool's physical values, which read higher on RAIDZ.
+
 ### Adding the integration
 <AddingIntegration />

@@ -0,0 +1,48 @@
+---
+title: "What's Up Docker"
+description: "What's Up Docker (WUD) watches your Docker containers and reports which ones have newer image versions available."
+hide_title: true
+---
+
+import { IntegrationHeader } from "@site/src/components/integrations/header";
+import { IntegrationCapabilites } from "@site/src/components/integrations/widgets";
+import { AddingIntegration } from "@site/src/components/integrations/adding";
+import { IntegrationSecrets } from "@site/src/components/integrations/secrets";
+import { wudIntegration } from ".";
+import { wudWidget } from "@site/docs/widgets/whats-up-docker";
+
+<IntegrationHeader integration={wudIntegration} categories={["Health Monitoring"]} />
+
+The What's Up Docker integration lets Homarr connect to your [WUD](https://github.com/getwud/wud) instance so you can see how many of your watched containers have image updates available directly from your dashboard.
+
+### Widgets & Capabilities
+
+<IntegrationCapabilites items={[{ widget: wudWidget }]} />
+
+### Adding the integration
+
+<AddingIntegration />
+
+:::info URL configuration
+Use the root URL of your WUD instance, for example `https://wud.example.com`. Homarr calls the `/api/app` and `/api/containers` endpoints under that URL automatically.
+:::
+
+### Secrets
+
+WUD does not require authentication by default. If your instance is protected with [Basic Authentication](https://github.com/getwud/wud/blob/main/docs/configuration/authentications/basic/README.md), you can provide a username and password.
+
+<IntegrationSecrets
+  secrets={[
+    {
+      credentials: [],
+      steps: [],
+    },
+    {
+      credentials: ["username", "password"],
+      steps: [
+        "Open your WUD instance's configuration and configure a WUD_AUTH_BASIC_* user as described in the WUD documentation",
+        "Enter that username and password in Homarr — Basic authentication is handled automatically",
+      ],
+    },
+  ]}
+/>
@@ -0,0 +1,9 @@
+import { IntegrationDefinition } from "@site/src/types";
+
+export const wudIntegration: IntegrationDefinition = {
+  name: "What's Up Docker",
+  description:
+    "What's Up Docker (WUD) watches your Docker containers and reports which ones have newer image versions available.",
+  iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/whats-up-docker.svg",
+  path: "../../integrations/whats-up-docker",
+};
@@ -28,7 +28,7 @@ The name must be at least one character long and can be chosen freely.
 ### Icon URL

 This is the URL to the icon that will be displayed on the app widget.
-You can paste a direct HTTP(S) URL to an image, search the included icon repositories by name, or upload a local file through the upload button. Direct image URLs are used as entered and are not searched in the icon repositories.
+You can paste a direct HTTP(S) URL to an image, search the included icon repositories by name, or upload a local file through the upload button. The app name is pre-filled as the initial library search when no image is selected. Local images appear first, followed by SVG icons and other formats. Direct image URLs are previewed, used as entered, and are not searched in the icon repositories.

 ![Icon URL](./img/app-icon-url.png)

@@ -52,14 +52,21 @@ The certificates are stored in the `/appdata/trusted-certificates` directory whi
 This means you can automate the update of the certificates by simply replacing or adding a new file in the directory.

 ## Obtaining certificates
-
 Every integration has its own way of obtaining certificates.
 Generally it is recommended to search for the documentation of the integration you are using.
 Most of the time you can find the certificate in the file system of the integration.
+The certificate file needs to be uploaded to Homarr. To first get the file on your computer you can either:
+- use `scp user@host:/path/to/file ./certificate.pem`
+- use `cat /path/to/file` to print the certificate. Then recreate the file on your machine.
+
 Below you can find instructions for some of the integrations.

 ### Pi-hole (v6)
-
 Since version 6 of Pi-hole, the web interface can be accessed through HTTPS.
-The certificate can be found in the path `/etc/pihole/tls_ca.crt`. To add the certificate, this file needs to be copied and uploaded to Homarr.
-You can find more details regarding SSL / TLS for Pi-hole [here](https://docs.pi-hole.net/api/tls/).
+The certificate can be found in the path `/etc/pihole/tls_ca.crt`.
+You can find more details regarding SSL / TLS for Pi-hole [here](https://docs.pi-hole.net/api/tls/).
+
+### Proxmox
+By default, Proxmox VE uses a node certificate signed by the cluster. You only need to configure Homarr with the certificate of a single node.
+The certificate can be found in any node on the path `/etc/pve/pve-root-ca.pem`.
+You can learn more about certificate management in Proxmox [here](https://pve.proxmox.com/wiki/Certificate_Management).
@@ -1,30 +1,27 @@
 ---
-title: 'App'
-description: 'Embeds an app into the board.'
+title: "App"
+description: "Embeds an app into the board."
 hide_title: true
 ---

-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { appWidget } from '.';
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { appWidget } from ".";

-
-<WidgetHeader
-  widget={appWidget}
-  categories={['Links', 'Apps']}
-/>
+<WidgetHeader widget={appWidget} categories={["Links", "Apps"]} />

 The app widget allows you to add a link to an application or a website that you want to access quickly from your Homarr board.
 It also supports a status check to indicate whether Homarr can reach the application or website.
+In view mode, right-clicking uses the browser's link menu. Homarr's widget menu remains available in edit mode.

 ### Screenshots

-import githubApp from './img/github.png';
-import jellyseerrApp from './img/jellyseerr-description-tooltip.png';
-import piHoleApp from './img/pi-hole-ping-icon.png';
+import githubApp from "./img/github.png";
+import jellyseerrApp from "./img/jellyseerr-description-tooltip.png";
+import piHoleApp from "./img/pi-hole-ping-icon.png";

-<div className='flex gap-1'>
+<div className="flex gap-1">
  <img src={githubApp} alt="app github with-status-check" width={128 * 1.5} height={128 * 1.5} />
  <img src={piHoleApp} alt="app pi-hole with-status-check status-check-icon" width={128 * 1.5} height={128 * 1.5} />
  <img src={jellyseerrApp} alt="app jellyseerr with-description-tooltip" height={128 * 1.5} />
@@ -34,4 +31,5 @@ import piHoleApp from './img/pi-hole-ping-icon.png';
 <AddingWidget />

 ### Configuration
+
 <WidgetConfig configuration={appWidget.configuration} />
@@ -1,29 +1,26 @@
 ---
-title: 'Bookmarks'
-description: 'Displays multiple app links'
+title: "Bookmarks"
+description: "Displays multiple app links"
 hide_title: true
 ---

-import { AddingWidget } from '@site/src/components/widgets/adding';
-import { WidgetConfig } from '@site/src/components/widgets/configuration';
-import { WidgetHeader } from '@site/src/components/widgets/header';
-import { bookmarksWidget } from '.';
+import { AddingWidget } from "@site/src/components/widgets/adding";
+import { WidgetConfig } from "@site/src/components/widgets/configuration";
+import { WidgetHeader } from "@site/src/components/widgets/header";
+import { bookmarksWidget } from ".";

-
-<WidgetHeader
-  widget={bookmarksWidget}
-  categories={['Links', 'Apps']}
-/>
+<WidgetHeader widget={bookmarksWidget} categories={["Links", "Apps"]} />

 The bookmarks widget allows you to display multiple app links in a single widget.
 You can add links to your favorite applications, websites, or any other resources you want quick access to.
+In view mode, right-clicking uses the browser's link menu. Homarr's widget menu remains available in edit mode.

 ### Screenshots

-import gridIconsOnly from './img/grid-icons-only.png';
-import gridWithTitle from './img/grid-with-title.png';
-import verticalListAll from './img/vertical-list-all.png';
-import vericalListSimple from './img/vertical-list-simple.png';
+import gridIconsOnly from "./img/grid-icons-only.png";
+import gridWithTitle from "./img/grid-with-title.png";
+import verticalListAll from "./img/vertical-list-all.png";
+import vericalListSimple from "./img/vertical-list-simple.png";

 <div className='flex gap-1'>
    <div className='flex flex-col gap-1'>
@@ -33,12 +30,13 @@ import vericalListSimple from './img/vertical-list-simple.png';

    <img src={gridWithTitle} alt="bookmarks grid with-title" width={256 + 4} height={256 + 4} />
    <img src={verticalListAll} alt="bookmarks vertical-list all-elements" width={128} height={256 + 4} />
-</div>

+</div>

 ### Adding the widget

 <AddingWidget />

 ### Configuration
+
 <WidgetConfig configuration={bookmarksWidget.configuration} />
@@ -43,6 +43,7 @@ import temperature from './img/temperature.png';
 ### Interactions

 - Toggle entity state by clicking on the entity (only when clickable enabled).
+- After a successful toggle, the displayed state refreshes immediately.

 ### Adding the widget

@@ -64,4 +65,4 @@ import retrieveEntityId from './img/retrieve-entity-id.png';

 <div>
  <img src={retrieveEntityId} alt="homeassistant retrieve-entity-id" width={256 * 2} />
-</div>
+</div>
@@ -47,4 +47,7 @@ import withDisplayname from './img/with-displayname.png';
 <AddingWidget />

 ### Configuration
+
+Use the Home Assistant entity ID (for example, `automation.turn_on_lights`) in the **Automation ID** field, not the automation's internal ID.
+
 <WidgetConfig configuration={smartHomeExecuteAutomationWidget.configuration} />
@@ -0,0 +1,35 @@
+---
+title: "What's Up Docker"
+description: "Displays how many watched containers have image updates available."
+hide_title: true
+---
+
+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 { wudWidget } from ".";
+import { wudIntegration } from "@site/docs/integrations/whats-up-docker";
+
+<WidgetHeader widget={wudWidget} categories={["Health Monitoring"]} />
+
+This widget shows two stats from your WUD instance: the total number of monitored containers, and how many of them currently have an image update available. Optionally, it can also list each outdated container with its current and new version, linking to the release notes when WUD provides one.
+
+### Supported Integrations
+
+<WidgetIntegrations
+  items={[
+    {
+      integration: wudIntegration,
+      note: "Displays monitored container and available-update counts",
+    },
+  ]}
+/>
+
+### Adding the widget
+
+<AddingWidget />
+
+### Configuration
+
+<WidgetConfig configuration={wudWidget.configuration} />
@@ -0,0 +1,37 @@
+import { WidgetDefinition } from "@site/src/types";
+import { IconBrandDocker } from "@tabler/icons-react";
+
+export const wudWidget: WidgetDefinition = {
+  icon: IconBrandDocker,
+  name: "What's Up Docker",
+  description: "Displays how many watched containers have image updates available.",
+  path: "../../widgets/whats-up-docker",
+  configuration: {
+    items: [
+      {
+        name: "Show title",
+        description: "Displays the icon and \"What's Up Docker\" label above the stats",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+      {
+        name: "Show update ring",
+        description: "Displays a ring showing the percentage of monitored containers with a pending update",
+        values: { type: "boolean" },
+        defaultValue: "yes",
+      },
+      {
+        name: "Layout",
+        description: "Arrange the two stats side by side (Horizontal) or stacked (Vertical)",
+        values: { type: "select", options: ["Horizontal", "Vertical"] },
+        defaultValue: "Horizontal",
+      },
+      {
+        name: "Show container update list",
+        description: "Lists each monitored container that has an image update available, linking to its release notes when known",
+        values: { type: "boolean" },
+        defaultValue: "no",
+      },
+    ],
+  },
+};
@@ -1,17 +1,21 @@
+import { createHash } from "node:crypto";
+
 import type { JSX, PropsWithChildren } from "react";
 import { notFound, redirect } from "next/navigation";
-import { AppShellMain } from "@mantine/core";
+import { cookies } from "next/headers";
 import { TRPCError } from "@trpc/server";

 import { getRscUserSettingsAsync } from "@homarr/api/user-server";
 import { auth } from "@homarr/auth/next";
 import { BoardProvider } from "@homarr/boards/context";
 import { EditModeProvider } from "@homarr/boards/edit-mode";
+import { dbEnv } from "@homarr/core/infrastructure/db/env";
 import { createLogger } from "@homarr/core/infrastructure/logs";
+import { v2BetaAnnouncementCookieKey } from "@homarr/definitions";

-import { MainHeader } from "~/components/layout/header";
+import { MainHeaderContent } from "~/components/layout/header";
 import { BoardLogoWithTitle } from "~/components/layout/logo/board-logo";
-import { ClientShell } from "~/components/layout/shell";
+import { V2BetaDashboardShell } from "~/components/layout/v2-beta-announcement/v2-beta-dashboard-shell";
 import { BoardTourGate } from "~/components/onboarding/board-tour-gate";
 import { env } from "~/env";
 import { getCurrentColorSchemeAsync } from "~/theme/color-scheme";
@@ -42,6 +46,7 @@ export const createBoardLayout = <TParams extends Params>({
  }>) => {
    const resolvedParams = await params;
    const sessionPromise = auth();
+    const cookiesPromise = cookies();
    const initialBoardPromise = getInitialBoard(resolvedParams).then(
      (board) => ({ status: "fulfilled", board }) as const,
      (error: unknown) => ({ status: "rejected", error }) as const,
@@ -58,11 +63,12 @@ export const createBoardLayout = <TParams extends Params>({
        return false;
      }
    });
-    const [session, initialBoardResult, colorScheme, shouldRunBoardTour] = await Promise.all([
+    const [session, initialBoardResult, colorScheme, shouldRunBoardTour, cookieStore] = await Promise.all([
      sessionPromise,
      initialBoardPromise,
      colorSchemePromise,
      shouldRunBoardTourPromise,
+      cookiesPromise,
    ]);
    if (initialBoardResult.status === "rejected") {
      const { error } = initialBoardResult;
@@ -83,6 +89,11 @@ export const createBoardLayout = <TParams extends Params>({
      throw error;
    }
    const initialBoard = initialBoardResult.board;
+    const viewerIdentity = session?.user.id ?? "anonymous";
+    const viewerHash = createHash("sha256").update(viewerIdentity).digest("hex").slice(0, 16);
+    const dismissalCookieName = `${v2BetaAnnouncementCookieKey}.${viewerHash}`;
+    const isAnnouncementDismissed = cookieStore.get(dismissalCookieName)?.value === "dismissed";
+    const canExportBackup = dbEnv.DRIVER === "better-sqlite3" && Boolean(session?.user.permissions.includes("admin"));

    return (
      <BoardProvider initialBoard={initialBoard}>
@@ -91,14 +102,20 @@ export const createBoardLayout = <TParams extends Params>({
            <BoardMantineProvider defaultColorScheme={colorScheme}>
              <CustomCss />
              <BoardTourGate enabled={shouldRunBoardTour}>
-                <ClientShell hasNavigation={false}>
-                  <MainHeader
-                    logo={<BoardLogoWithTitle size="md" hideTitleOnMobile />}
-                    actions={headerActions}
-                    hasNavigation={false}
-                  />
-                  <AppShellMain>{children}</AppShellMain>
-                </ClientShell>
+                <V2BetaDashboardShell
+                  canExportBackup={canExportBackup}
+                  dismissalCookieName={dismissalCookieName}
+                  initiallyDismissed={isAnnouncementDismissed}
+                  header={
+                    <MainHeaderContent
+                      logo={<BoardLogoWithTitle size="md" hideTitleOnMobile />}
+                      actions={headerActions}
+                      hasNavigation={false}
+                    />
+                  }
+                >
+                  {children}
+                </V2BetaDashboardShell>
              </BoardTourGate>
            </BoardMantineProvider>
          </EditModeProvider>
@@ -697,7 +697,11 @@ export function CustomWidgetForm({ mode, initialValues, definitionId }: CustomWi
            <Stack gap="sm">
              <TextInput label={t("field.name")} required {...form.getInputProps("name")} />
              <Textarea label={t("field.description")} {...form.getInputProps("description")} />
-              <IconPicker withAsterisk={false} {...form.getInputProps("iconUrl")} />
+              <IconPicker
+                withAsterisk={false}
+                suggestedSearch={mode === "create" ? form.values.name : undefined}
+                {...form.getInputProps("iconUrl")}
+              />
            </Stack>
          </Fieldset>

@@ -57,7 +57,10 @@ export const SearchEngineForm = (props: SearchEngineFormProps) => {
            />
          </Grid.Col>
        </Grid>
-        <IconPicker {...form.getInputProps("iconUrl")} />
+        <IconPicker
+          {...form.getInputProps("iconUrl")}
+          suggestedSearch={initialValues === undefined ? form.values.name : undefined}
+        />

        <Fieldset legend={t("search.engine.page.edit.configControl")}>
          <SegmentedControl
@@ -1,49 +1,14 @@
 "use client";

-import { useState } from "react";
-import { Alert, Button, Card, Group, Stack, Text, Title } from "@mantine/core";
-import { IconAlertTriangle, IconDatabaseExport, IconDownload } from "@tabler/icons-react";
+import { Card, Group, Stack, Text, Title } from "@mantine/core";
+import { IconDatabaseExport } from "@tabler/icons-react";

 import { useScopedI18n } from "@homarr/translation/client";

-import { DangerousActionConfirmation } from "~/components/backup/dangerous-action-confirmation";
+import { BackupExportButton } from "~/components/backup";

 export const BackupExportCard = () => {
  const t = useScopedI18n("management.page.tool.backup.export");
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const [showConfirm, setShowConfirm] = useState(false);
-
-  const handleExport = async () => {
-    setLoading(true);
-    setError(null);
-    try {
-      const response = await fetch("/api/backup/export");
-      if (!response.ok) {
-        const errorMessage = await response.json().then(
-          (data) => data.error,
-          () => `Server returned ${response.status}`,
-        );
-        throw new Error(errorMessage ?? t("error"));
-      }
-
-      const blob = await response.blob();
-      const url = URL.createObjectURL(blob);
-      const filename =
-        response.headers.get("Content-Disposition")?.match(/filename="(.+)"/)?.[1] ?? "homarr-backup.zip";
-
-      const a = document.createElement("a");
-      a.href = url;
-      a.download = filename;
-      a.click();
-      URL.revokeObjectURL(url);
-      setShowConfirm(false);
-    } catch (err) {
-      setError(err instanceof Error ? err.message : t("error"));
-    } finally {
-      setLoading(false);
-    }
-  };

  return (
    <Card withBorder>
@@ -55,33 +20,7 @@ export const BackupExportCard = () => {
        <Text size="sm" c="dimmed">
          {t("description")}
        </Text>
-        {error && (
-          <Alert color="red" icon={<IconAlertTriangle size={16} />}>
-            {error}
-          </Alert>
-        )}
-
-        {showConfirm ? (
-          <DangerousActionConfirmation
-            title={t("confirm.title")}
-            warningTitle={t("confirm.warningTitle")}
-            warningBody={t("confirm.warningBody")}
-            typePrompt={t("confirm.typePrompt", { phrase: "I understand" })}
-            submitLabel={t("confirm.submit")}
-            submitIcon={<IconDownload size={16} />}
-            cancelLabel={t("confirm.cancel")}
-            onConfirm={handleExport}
-            onCancel={() => setShowConfirm(false)}
-            disabled={loading}
-            color="orange"
-          />
-        ) : (
-          <Group>
-            <Button leftSection={<IconDownload size={16} />} loading={loading} onClick={() => setShowConfirm(true)}>
-              {t("button")}
-            </Button>
-          </Group>
-        )}
+        <BackupExportButton />
      </Stack>
    </Card>
  );
@@ -14,6 +14,7 @@ import { db } from "@homarr/db";

 import { getPackageVersion } from "~/versions/package-reader";
 import { extractMcpTools } from "../_extract-tools";
+import { serializeMcpToolResult } from "../_serialize-result";

 const logger = createLogger({ module: "mcpRoute" });

@@ -203,7 +204,7 @@ const mcpHandler = createMcpHandler(
        const input = args && Object.keys(args).length > 0 ? args : undefined;
        const result = await procedure(input);
        return {
-          content: [{ type: "text" as const, text: JSON.stringify(result) }],
+          content: [{ type: "text" as const, text: serializeMcpToolResult(result) }],
        };
      } catch (error) {
        const message = sanitizeErrorMessage(error);
@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+
+import { serializeMcpToolResult } from "./_serialize-result";
+
+describe("serializeMcpToolResult", () => {
+  it("serializes objects as JSON strings", () => {
+    expect(serializeMcpToolResult({ boardId: "1" })).toBe('{"boardId":"1"}');
+  });
+
+  it("serializes primitive values", () => {
+    expect(serializeMcpToolResult("hello")).toBe('"hello"');
+    expect(serializeMcpToolResult(42)).toBe("42");
+    expect(serializeMcpToolResult(true)).toBe("true");
+  });
+
+  it("serializes null as the string null", () => {
+    expect(serializeMcpToolResult(null)).toBe("null");
+  });
+
+  it("serializes void results as the string null so MCP content text is always a string", () => {
+    expect(serializeMcpToolResult(undefined)).toBe("null");
+  });
+});
@@ -0,0 +1,3 @@
+export function serializeMcpToolResult(result: unknown): string {
+  return JSON.stringify(result) ?? "null";
+}
@@ -0,0 +1,79 @@
+"use client";
+
+import { useState } from "react";
+import { Alert, Button, Group, Stack } from "@mantine/core";
+import { IconAlertTriangle, IconDownload } from "@tabler/icons-react";
+
+import { useScopedI18n } from "@homarr/translation/client";
+
+import { DangerousActionConfirmation } from "./dangerous-action-confirmation";
+
+export const BackupExportButton = () => {
+  const t = useScopedI18n("management.page.tool.backup.export");
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [showConfirm, setShowConfirm] = useState(false);
+
+  const handleExport = async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const response = await fetch("/api/backup/export");
+      if (!response.ok) {
+        const errorMessage = await response.json().then(
+          (data) => data.error,
+          () => `Server returned ${response.status}`,
+        );
+        throw new Error(errorMessage ?? t("error"));
+      }
+
+      const blob = await response.blob();
+      const url = URL.createObjectURL(blob);
+      const filename =
+        response.headers.get("Content-Disposition")?.match(/filename="(.+)"/)?.[1] ?? "homarr-backup.zip";
+
+      const anchor = document.createElement("a");
+      anchor.href = url;
+      anchor.download = filename;
+      anchor.click();
+      URL.revokeObjectURL(url);
+      setShowConfirm(false);
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : t("error"));
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <Stack gap="sm">
+      {error && (
+        <Alert color="red" icon={<IconAlertTriangle size={16} />}>
+          {error}
+        </Alert>
+      )}
+
+      {showConfirm ? (
+        <DangerousActionConfirmation
+          title={t("confirm.title")}
+          warningTitle={t("confirm.warningTitle")}
+          warningBody={t("confirm.warningBody")}
+          typePrompt={t("confirm.typePrompt", { phrase: "I understand" })}
+          submitLabel={t("confirm.submit")}
+          submitIcon={<IconDownload size={16} />}
+          cancelLabel={t("confirm.cancel")}
+          onConfirm={handleExport}
+          onCancel={() => setShowConfirm(false)}
+          disabled={loading}
+          color="orange"
+        />
+      ) : (
+        <Group>
+          <Button leftSection={<IconDownload size={16} />} loading={loading} onClick={() => setShowConfirm(true)}>
+            {t("button")}
+          </Button>
+        </Group>
+      )}
+    </Stack>
+  );
+};
@@ -1,3 +1,4 @@
+export { BackupExportButton } from "./backup-export-button";
 export { DatabaseRestoreFlow } from "./database-restore-flow";
 export { DangerousActionConfirmation } from "./dangerous-action-confirmation";
 export type { BackupAnalysis, RestoreStep } from "./types";
@@ -44,9 +44,13 @@ interface WidgetContextMenuProps {

 export const WidgetContextMenu = ({ item, definition, widgetStateRef, children }: WidgetContextMenuProps) => {
  const { data: session } = useSession();
+  const [isEditMode] = useEditMode();
  const settings = useSettings();

  if (!session || !settings.enableRightClickOnWidgets) return <>{children}</>;
+  const isLinkWidget = item.kind === "app" || item.kind === "bookmarks";
+  // Keep the Homarr menu in edit mode so these widgets can still be edited or removed.
+  if (isLinkWidget && !isEditMode) return <>{children}</>;

  return (
    <WidgetContextMenuInner item={item} definition={definition} widgetStateRef={widgetStateRef} settings={settings}>
@@ -301,6 +301,8 @@ interface UseCssVariableConfiguration {
  isDynamic: boolean;
 }

+const minimumResizeWidthDelta = 20;
+
 /**
 * This hook is used to configure the css variables for the gridstack
 * Those css variables are used to define the size of the gridstack items
@@ -319,9 +321,30 @@ const useCssVariableConfiguration = ({
  columnCount,
  isDynamic,
 }: UseCssVariableConfiguration) => {
+  const prevSizeRef = useRef<{ width: number; height: number } | null>(null);
+
  const onResize = useCallback(() => {
    if (!wrapperRef.current) return;
    if (!gridRef.current) return;
+
+    const currentWidth = wrapperRef.current.clientWidth;
+    const currentHeight = wrapperRef.current.clientHeight;
+    const prevSize = prevSizeRef.current;
+
+    // Only skip recalculation when the width change is insignificant
+    // and, for dynamic sections, the height is unchanged. This prevents infinite
+    // feedback loops when the vertical scrollbar appears/disappears, causing
+    // clientWidth to oscillate by ~15px, while still reacting to height changes.
+    if (
+      prevSize !== null &&
+      Math.abs(currentWidth - prevSize.width) < minimumResizeWidthDelta &&
+      (!isDynamic || currentHeight === prevSize.height)
+    ) {
+      return;
+    }
+
+    prevSizeRef.current = { width: currentWidth, height: currentHeight };
+
    handleResizeChange(
      wrapperRef.current,
      gridRef.current,
@@ -19,25 +19,31 @@ interface Props {
 export const MainHeader = ({ logo, actions, hasNavigation = true }: Props) => {
  return (
    <AppShellHeader maw="100vw" zIndex={201} style={{ overflowX: "hidden" }}>
-      <Group h="100%" gap="xl" px="md" justify="apart" wrap="nowrap">
-        <Group h="100%" align="center" style={{ flex: 1 }} wrap="nowrap">
-          {hasNavigation && <ClientBurger />}
-          <UnstyledButton component={Link} href="/">
-            {logo ?? <HomarrLogoWithTitle size="md" />}
-          </UnstyledButton>
-        </Group>
-        <TourTarget id="board-search">
-          <DesktopSearchInput />
-        </TourTarget>
-        <Group h="100%" align="center" justify="end" style={{ flex: 1 }} wrap="nowrap">
-          {actions}
-          <MobileSearchButton />
-          <TourTarget id="board-user-menu">
-            <UserButton />
-          </TourTarget>
-        </Group>
-      </Group>
-      <LazySpotlight />
+      <MainHeaderContent logo={logo} actions={actions} hasNavigation={hasNavigation} />
    </AppShellHeader>
  );
 };
+
+export const MainHeaderContent = ({ logo, actions, hasNavigation = true }: Props) => (
+  <>
+    <Group h={60} gap="xl" px="md" justify="apart" wrap="nowrap">
+      <Group h="100%" align="center" style={{ flex: 1 }} wrap="nowrap">
+        {hasNavigation && <ClientBurger />}
+        <UnstyledButton component={Link} href="/">
+          {logo ?? <HomarrLogoWithTitle size="md" />}
+        </UnstyledButton>
+      </Group>
+      <TourTarget id="board-search">
+        <DesktopSearchInput />
+      </TourTarget>
+      <Group h="100%" align="center" justify="end" style={{ flex: 1 }} wrap="nowrap">
+        {actions}
+        <MobileSearchButton />
+        <TourTarget id="board-user-menu">
+          <UserButton />
+        </TourTarget>
+      </Group>
+    </Group>
+    <LazySpotlight />
+  </>
+);
@@ -1,38 +1,17 @@
 "use client";

-import type { ComponentProps, ReactNode } from "react";
-import { Suspense, use, useEffect, useState } from "react";
-import { Box, Loader, UnstyledButton, useMantineColorScheme } from "@mantine/core";
+import type { ReactNode } from "react";
+import { useEffect, useState } from "react";
+import { UnstyledButton, useMantineColorScheme } from "@mantine/core";
 import { useHotkeys } from "@mantine/hooks";
-import { ErrorBoundary } from "react-error-boundary";

 import { clientApi } from "@homarr/api/client";
 import { useSession } from "@homarr/auth/client";
 import { hotkeys } from "@homarr/definitions";

+import { UserAvatarMenu } from "~/components/user-avatar-menu";
 import { UpdateIndicator } from "./update";

-type UserAvatarMenuModule = typeof import("~/components/user-avatar-menu");
-type UserAvatarMenuProps = ComponentProps<UserAvatarMenuModule["UserAvatarMenu"]>;
-
-let userAvatarMenuPromise: Promise<UserAvatarMenuModule> | undefined;
-const loadUserAvatarMenu = () => {
-  if (userAvatarMenuPromise) return userAvatarMenuPromise;
-
-  const promise = import("~/components/user-avatar-menu");
-  userAvatarMenuPromise = promise;
-  void promise.catch(() => {
-    if (userAvatarMenuPromise === promise) userAvatarMenuPromise = undefined;
-  });
-  return promise;
-};
-const preloadUserAvatarMenu = () => void loadUserAvatarMenu().catch(() => undefined);
-
-const LazyUserAvatarMenu = (props: UserAvatarMenuProps) => {
-  const { UserAvatarMenu } = use(loadUserAvatarMenu());
-  return <UserAvatarMenu {...props} />;
-};
-
 interface UserButtonClientProps {
  avatar: ReactNode;
  isAdmin: boolean;
@@ -41,8 +20,6 @@ interface UserButtonClientProps {

 export const UserButtonClient = ({ avatar, isAdmin, isDockerEnabled }: UserButtonClientProps) => {
  const [canCheckForUpdates, setCanCheckForUpdates] = useState(false);
-  const [isMenuMounted, setIsMenuMounted] = useState(false);
-  const [isMenuOpen, setIsMenuOpen] = useState(false);
  const session = useSession();
  const { toggleColorScheme } = useMantineColorScheme();
  useHotkeys([[hotkeys.toggleColorScheme, toggleColorScheme]]);
@@ -66,60 +43,14 @@ export const UserButtonClient = ({ avatar, isAdmin, isDockerEnabled }: UserButto
    staleTime: 60 * 60 * 1_000,
  });
  const visibleUpdates = isCurrentSessionAdmin ? availableUpdates : undefined;
-  const openMenu = () => {
-    setIsMenuMounted(true);
-    setIsMenuOpen(true);
-  };
-  const renderButton = (onClick: () => void, isLoading = false) => (
-    <UnstyledButton
-      onClick={onClick}
-      onFocus={preloadUserAvatarMenu}
-      onMouseEnter={preloadUserAvatarMenu}
-      onPointerDown={preloadUserAvatarMenu}
-      aria-busy={isLoading || undefined}
-      disabled={isLoading}
-    >
-      <UpdateIndicator availableUpdates={visibleUpdates} disabled={!isCurrentSessionAdmin}>
-        <Box pos="relative" style={{ display: "inline-flex" }}>
-          <Box opacity={isLoading ? 0.35 : 1}>{avatar}</Box>
-          {isLoading && (
-            <Loader
-              aria-label="Loading user menu"
-              size={18}
-              pos="absolute"
-              top="50%"
-              left="50%"
-              style={{ transform: "translate(-50%, -50%)" }}
-            />
-          )}
-        </Box>
-      </UpdateIndicator>
-    </UnstyledButton>
-  );
-  const button = renderButton(openMenu);
-  const loadingButton = renderButton(() => undefined, true);
-
-  if (!isMenuMounted) return button;

  return (
-    <ErrorBoundary
-      fallbackRender={({ resetErrorBoundary }) =>
-        renderButton(() => {
-          resetErrorBoundary();
-          openMenu();
-        })
-      }
-    >
-      <Suspense fallback={loadingButton}>
-        <LazyUserAvatarMenu
-          availableUpdates={visibleUpdates}
-          isDockerEnabled={isDockerEnabled}
-          opened={isMenuOpen}
-          onOpenChange={setIsMenuOpen}
-        >
-          {button}
-        </LazyUserAvatarMenu>
-      </Suspense>
-    </ErrorBoundary>
+    <UserAvatarMenu availableUpdates={visibleUpdates} isDockerEnabled={isDockerEnabled}>
+      <UnstyledButton>
+        <UpdateIndicator availableUpdates={visibleUpdates} disabled={!isCurrentSessionAdmin}>
+          {avatar}
+        </UpdateIndicator>
+      </UnstyledButton>
+    </UserAvatarMenu>
  );
 };
@@ -10,11 +10,13 @@ import { navigationCollapsedAtom } from "./header/burger";
 interface ClientShellProps {
  hasHeader?: boolean;
  hasNavigation?: boolean;
+  headerHeight?: number;
 }

 export const ClientShell = ({
  hasHeader = true,
  hasNavigation = true,
+  headerHeight = 60,
  children,
 }: PropsWithChildren<ClientShellProps>) => {
  const collapsed = useAtomValue(navigationCollapsedAtom);
@@ -23,7 +25,7 @@ export const ClientShell = ({
  return (
    <AppShell
      {...backgroundProps}
-      header={hasHeader ? { height: 60 } : undefined}
+      header={hasHeader ? { height: headerHeight } : undefined}
      navbar={
        hasNavigation
          ? {
@@ -0,0 +1,7 @@
+export const v2BetaBlogUrl = "https://v2.preview.homarr.dev/blog/2026/09/03/homarr-2.0";
+export const v2BetaDocsUrl = "https://v2.preview.homarr.dev/docs/getting-started/";
+export const v2BetaPreviewUrl = "https://app-v2.preview.homarr.dev";
+export const v2BetaWorkshopUrl = "https://v2.preview.homarr.dev/workshop";
+export const v2BetaFeedbackUrl = "https://github.com/homarr-labs/homarr/issues/new?template=v2_beta_feedback.yml";
+export const v2BetaDiscussionUrl = "https://github.com/homarr-labs/homarr/issues/6600";
+export const discordInviteUrl = "https://discord.com/invite/aCsmEV5RgA";
@@ -0,0 +1,94 @@
+.banner {
+  position: relative;
+  isolation: isolate;
+  height: 52px;
+  overflow: hidden;
+  color: var(--mantine-color-white);
+  background: var(--mantine-color-red-9);
+  border-bottom: 1px solid rgb(255 255 255 / 18%);
+}
+
+.banner::after {
+  position: absolute;
+  z-index: -1;
+  right: -0.35rem;
+  bottom: -1.75rem;
+  color: rgb(255 255 255 / 9%);
+  font-size: 5.5rem;
+  font-weight: 900;
+  line-height: 1;
+  content: "v2";
+}
+
+.copy {
+  min-width: 0;
+}
+
+.subtitle {
+  opacity: 0.86;
+}
+
+.modalHero {
+  position: relative;
+  isolation: isolate;
+  overflow: hidden;
+  color: var(--mantine-color-white);
+  background: var(--mantine-color-red-9);
+}
+
+.modalHero::after {
+  position: absolute;
+  z-index: -1;
+  right: -0.75rem;
+  bottom: -1.5rem;
+  color: rgb(255 255 255 / 8%);
+  font-size: 12rem;
+  font-weight: 900;
+  line-height: 1;
+  content: "v2";
+}
+
+.featureCard {
+  height: 100%;
+  background: light-dark(var(--mantine-color-white), var(--mantine-color-dark-7));
+}
+
+.diffViewer {
+  overflow: hidden;
+}
+
+.diffHeader {
+  background: light-dark(var(--mantine-color-gray-1), var(--mantine-color-dark-7));
+  border-bottom: 1px solid var(--mantine-color-default-border);
+}
+
+.diffCode {
+  margin: 0;
+  padding-block: var(--mantine-spacing-sm);
+  overflow-x: auto;
+  color: light-dark(var(--mantine-color-dark-8), var(--mantine-color-gray-2));
+  background: light-dark(var(--mantine-color-gray-0), var(--mantine-color-dark-9));
+  font-family: var(--mantine-font-family-monospace);
+  font-size: var(--mantine-font-size-sm);
+  line-height: 1.6;
+}
+
+.diffLine_context,
+.diffLine_added,
+.diffLine_removed {
+  display: block;
+  width: max-content;
+  min-width: 100%;
+  padding-inline: var(--mantine-spacing-md);
+  white-space: pre;
+}
+
+.diffLine_added {
+  color: light-dark(var(--mantine-color-green-9), var(--mantine-color-green-3));
+  background: light-dark(var(--mantine-color-green-0), rgb(47 158 68 / 15%));
+}
+
+.diffLine_removed {
+  color: light-dark(var(--mantine-color-red-9), var(--mantine-color-red-3));
+  background: light-dark(var(--mantine-color-red-0), rgb(250 82 82 / 15%));
+}
@@ -0,0 +1,377 @@
+"use client";
+
+import type { ReactNode } from "react";
+import {
+  ActionIcon,
+  Accordion,
+  Alert,
+  Anchor,
+  Box,
+  Button,
+  getDefaultZIndex,
+  Group,
+  Paper,
+  SimpleGrid,
+  Stack,
+  Text,
+  ThemeIcon,
+  Title,
+} from "@mantine/core";
+import {
+  IconArrowsMove,
+  IconBook2,
+  IconBrandCss3,
+  IconBrandDiscord,
+  IconBrandGithub,
+  IconDatabaseExport,
+  IconExternalLink,
+  IconHeartHandshake,
+  IconRobot,
+  IconRocket,
+  IconTerminal2,
+  IconWand,
+  IconX,
+} from "@tabler/icons-react";
+
+import { setClientCookie } from "@homarr/common";
+import { createModal, useModalAction } from "@homarr/modals";
+
+import { BackupExportButton } from "~/components/backup";
+import {
+  discordInviteUrl,
+  v2BetaBlogUrl,
+  v2BetaDiscussionUrl,
+  v2BetaDocsUrl,
+  v2BetaFeedbackUrl,
+  v2BetaPreviewUrl,
+  v2BetaWorkshopUrl,
+} from "./constants";
+import classes from "./v2-beta-announcement.module.css";
+
+const diffLineClassNames = {
+  added: classes.diffLine_added,
+  context: classes.diffLine_context,
+  removed: classes.diffLine_removed,
+} as const;
+
+const composeDiffLines = [
+  { kind: "context", value: " services:" },
+  { kind: "context", value: "   homarr:" },
+  { kind: "added", value: "+    image: ghcr.io/homarr-labs/homarr-test:v2" },
+  { kind: "removed", value: "-    image: ghcr.io/homarr-labs/homarr:latest" },
+  { kind: "context", value: "     ports:" },
+  { kind: "context", value: '       - "7575:7575"' },
+  { kind: "context", value: "     volumes:" },
+  { kind: "context", value: "       - homarr-v2:/appdata" },
+  { kind: "context", value: "     environment:" },
+  { kind: "context", value: "       SECRET_ENCRYPTION_KEY: <SECRET_KEY>" },
+  { kind: "added", value: "+      WORKSHOP_API_URL: https://v2.preview.homarr.dev/ # Only during the beta" },
+  { kind: "context", value: "" },
+  { kind: "context", value: " volumes:" },
+  { kind: "context", value: "   homarr-v2:" },
+] as const;
+
+interface V2BetaAnnouncementProps {
+  canExportBackup: boolean;
+  dismissalCookieName: string;
+  onDismiss: () => void;
+}
+
+export const V2BetaAnnouncement = ({ canExportBackup, dismissalCookieName, onDismiss }: V2BetaAnnouncementProps) => {
+  const { openModal } = useModalAction(V2BetaAnnouncementModal);
+
+  const dismiss = () => {
+    setClientCookie(dismissalCookieName, "dismissed", {
+      maxAge: 60 * 60 * 24 * 7,
+      path: "/",
+      sameSite: "lax",
+      secure: window.location.protocol === "https:",
+    });
+    onDismiss();
+  };
+
+  return (
+    <Box component="aside" className={classes.banner} aria-label="Homarr v2 beta announcement">
+      <Group h="100%" justify="space-between" gap="sm" wrap="nowrap" px="md">
+        <Box className={classes.copy}>
+          <Text fw={750} size="sm" truncate>
+            We&apos;ve been cooking, Homarr v2 beta is here
+          </Text>
+          <Text className={classes.subtitle} visibleFrom="sm" size="xs" truncate>
+            Custom Widgets &amp; CSS workshop, new drag-and-drop, new container system, side-bars are back, new widgets
+            and so much more, come check it out and help us make v2 ready for everyone
+          </Text>
+        </Box>
+
+        <Group gap={6} wrap="nowrap">
+          <Button variant="white" color="red" size="compact-sm" onClick={() => openModal({ canExportBackup })}>
+            Explore v2
+          </Button>
+          <ActionIcon variant="subtle" color="white" onClick={dismiss} aria-label="Dismiss the v2 beta announcement">
+            <IconX size={18} />
+          </ActionIcon>
+        </Group>
+      </Group>
+    </Box>
+  );
+};
+
+interface V2BetaAnnouncementModalProps {
+  canExportBackup: boolean;
+}
+
+const V2BetaAnnouncementModal = createModal<V2BetaAnnouncementModalProps>(({ innerProps }) => {
+  return (
+    <Stack gap="lg">
+      <Paper className={classes.modalHero} p={{ base: "lg", sm: "xl" }} radius="md">
+        <Stack gap="sm" maw={760}>
+          <Title order={2}>Help us get Homarr v2 ready</Title>
+          <Text>
+            We&apos;ve been working on Homarr&apos;s v2 update for a while now. There is no fixed release date yet, it
+            will be ready when it&apos;s ready. We{" "}
+            <Text span inherit fw={700}>
+              need your help
+            </Text>{" "}
+            and feedback to help us become confident enough to release it for everyone.
+          </Text>
+        </Stack>
+      </Paper>
+
+      <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="md">
+        <FeatureCard icon={<IconBrandCss3 size={21} />} title="Workshop">
+          Share and discover Custom Widgets and CSS made by the Homarr community.
+        </FeatureCard>
+        <FeatureCard icon={<IconArrowsMove size={21} />} title="Complete drag-and-drop rewrite">
+          Move, resize, multi-select, and arrange your dashboard with a board editor rebuilt from the ground up.
+        </FeatureCard>
+        <FeatureCard icon={<IconWand size={21} />} title="Custom Widgets v2">
+          We think you can make almost any widget with live previews, API requests, options, actions, and validation.
+        </FeatureCard>
+        <FeatureCard icon={<IconRobot size={21} />} title="Assistant">
+          Assistant can directly make a Custom Widget for you. Try giving it the API docs for your latest selfhosted
+          tool and asking it to build a custom widget for it.
+        </FeatureCard>
+      </SimpleGrid>
+
+      <Accordion variant="separated" radius="md">
+        <Accordion.Item value="installation">
+          <Accordion.Control
+            icon={
+              <ThemeIcon variant="light" color="red" radius="md" size="lg">
+                <IconTerminal2 size={20} />
+              </ThemeIcon>
+            }
+            aria-label="Test Homarr v2 on your server"
+          >
+            <Box>
+              <Text fw={750}>Test Homarr v2 on your server</Text>
+              <Text c="dimmed" size="xs">
+                Back up this instance, then update your Docker Compose file.
+              </Text>
+            </Box>
+          </Accordion.Control>
+          <Accordion.Panel>
+            <V2BetaInstallInstructions canExportBackup={innerProps.canExportBackup} />
+          </Accordion.Panel>
+        </Accordion.Item>
+      </Accordion>
+
+      <Alert variant="light" color="red" icon={<IconHeartHandshake size={22} />} title="Your testing is essential">
+        <Text size="sm">
+          Everyone uses Homarr in a different way. If anything breaks or does not feel right, the easiest way to get it
+          fixed as soon as possible is to{" "}
+          <Anchor
+            href={discordInviteUrl}
+            target="_blank"
+            rel="noopener noreferrer"
+            c="inherit"
+            fz="sm"
+            fw={700}
+            underline="always"
+          >
+            tell us about it on Discord
+          </Anchor>{" "}
+          in our dedicated v2 channel. You can also{" "}
+          <Anchor
+            href={v2BetaFeedbackUrl}
+            target="_blank"
+            rel="noopener noreferrer"
+            c="inherit"
+            fz="sm"
+            fw={700}
+            underline="always"
+          >
+            open a dedicated GitHub issue
+          </Anchor>
+          {"."} Every report matters.
+        </Text>
+      </Alert>
+
+      <SimpleGrid cols={{ base: 1, sm: 3 }} spacing="sm">
+        <Button
+          component="a"
+          href={v2BetaPreviewUrl}
+          target="_blank"
+          rel="noopener noreferrer"
+          size="md"
+          leftSection={<IconRocket size={18} />}
+        >
+          Try the hosted preview
+        </Button>
+        <Button
+          component="a"
+          href={v2BetaWorkshopUrl}
+          target="_blank"
+          rel="noopener noreferrer"
+          variant="light"
+          size="md"
+          leftSection={<IconBrandCss3 size={18} />}
+        >
+          Open Workshop
+        </Button>
+        <Button
+          component="a"
+          href={v2BetaDocsUrl}
+          target="_blank"
+          rel="noopener noreferrer"
+          variant="default"
+          size="md"
+          leftSection={<IconBook2 size={18} />}
+        >
+          Read the v2 docs
+        </Button>
+        <Button
+          component="a"
+          href={v2BetaBlogUrl}
+          target="_blank"
+          rel="noopener noreferrer"
+          variant="default"
+          size="md"
+          rightSection={<IconExternalLink size={16} />}
+        >
+          See everything new
+        </Button>
+        <Button
+          component="a"
+          href={discordInviteUrl}
+          target="_blank"
+          rel="noopener noreferrer"
+          variant="default"
+          size="md"
+          leftSection={<IconBrandDiscord size={18} />}
+        >
+          Join us on Discord
+        </Button>
+        <Button
+          component="a"
+          href={v2BetaDiscussionUrl}
+          target="_blank"
+          rel="noopener noreferrer"
+          variant="default"
+          size="md"
+          rightSection={<IconExternalLink size={15} />}
+        >
+          Follow v2 development
+        </Button>
+      </SimpleGrid>
+
+      <Button
+        component="a"
+        href={v2BetaFeedbackUrl}
+        target="_blank"
+        rel="noopener noreferrer"
+        variant="light"
+        color="red"
+        size="md"
+        leftSection={<IconBrandGithub size={18} />}
+      >
+        Report anything that breaks or feels wrong
+      </Button>
+    </Stack>
+  );
+}).withOptions({
+  defaultTitle: "Homarr v2 beta",
+  size: 1000,
+  yOffset: 128,
+  zIndex: getDefaultZIndex("modal") + 2,
+});
+
+interface V2BetaInstallInstructionsProps {
+  canExportBackup: boolean;
+}
+
+const V2BetaInstallInstructions = ({ canExportBackup }: V2BetaInstallInstructionsProps) => (
+  <Stack gap="lg">
+    {canExportBackup ? (
+      <Paper withBorder p="md" radius="md">
+        <Stack gap="sm">
+          <Group gap="sm">
+            <IconDatabaseExport size={22} />
+            <Title order={4}>Back up this Homarr instance</Title>
+          </Group>
+          <Text c="dimmed" size="sm">
+            Download a full backup before testing v2. The archive contains sensitive data, so keep it somewhere safe.
+          </Text>
+          <BackupExportButton />
+        </Stack>
+      </Paper>
+    ) : (
+      <Alert color="blue" title="Back up your database before continuing">
+        Direct backup downloads are available here to Homarr administrators using SQLite. If you use MySQL or
+        PostgreSQL, back up the database with its own tools before testing v2.
+      </Alert>
+    )}
+
+    <Stack gap="xs">
+      <Title order={3}>Update your Docker Compose file</Title>
+      <Text c="dimmed" size="sm">
+        Replace the current image and add the beta-only Workshop URL. Use the example below as a starting point.
+      </Text>
+    </Stack>
+
+    <Paper withBorder radius="md" className={classes.diffViewer}>
+      <Group gap="xs" px="md" py="sm" className={classes.diffHeader}>
+        <IconTerminal2 size={17} />
+        <Text fw={700} size="sm">
+          docker-compose.yml
+        </Text>
+      </Group>
+      <Box component="pre" className={classes.diffCode} aria-label="Docker Compose changes for Homarr v2 beta">
+        {composeDiffLines.map((line, index) => (
+          <Box component="span" className={diffLineClassNames[line.kind]} key={`${line.kind}-${index}`}>
+            {line.value || " "}
+          </Box>
+        ))}
+      </Box>
+    </Paper>
+
+    <Text c="dimmed" size="xs">
+      Replace <code>&lt;SECRET_KEY&gt;</code> with your existing encryption key. The Workshop URL is only required while
+      the beta uses the preview Workshop.
+    </Text>
+  </Stack>
+);
+
+interface FeatureCardProps {
+  icon: ReactNode;
+  title: string;
+  children: ReactNode;
+}
+
+const FeatureCard = ({ icon, title, children }: FeatureCardProps) => (
+  <Paper className={classes.featureCard} withBorder p="md" radius="md">
+    <Group gap="sm" align="flex-start" wrap="nowrap">
+      <ThemeIcon variant="light" color="red" radius="md" size="lg">
+        {icon}
+      </ThemeIcon>
+      <Box>
+        <Text fw={750} size="sm">
+          {title}
+        </Text>
+        <Text c="dimmed" size="sm">
+          {children}
+        </Text>
+      </Box>
+    </Group>
+  </Paper>
+);
@@ -0,0 +1,42 @@
+"use client";
+
+import type { PropsWithChildren, ReactNode } from "react";
+import { useState } from "react";
+import { AppShellHeader, AppShellMain } from "@mantine/core";
+
+import { ClientShell } from "../shell";
+import { V2BetaAnnouncement } from "./v2-beta-announcement";
+
+interface V2BetaDashboardShellProps {
+  canExportBackup: boolean;
+  dismissalCookieName: string;
+  initiallyDismissed: boolean;
+  header: ReactNode;
+}
+
+export const V2BetaDashboardShell = ({
+  canExportBackup,
+  dismissalCookieName,
+  initiallyDismissed,
+  header,
+  children,
+}: PropsWithChildren<V2BetaDashboardShellProps>) => {
+  const [isAnnouncementVisible, setIsAnnouncementVisible] = useState(!initiallyDismissed);
+  const headerHeight = isAnnouncementVisible ? 112 : 60;
+
+  return (
+    <ClientShell hasNavigation={false} headerHeight={headerHeight}>
+      <AppShellHeader maw="100vw" zIndex={201} style={{ overflowX: "hidden" }}>
+        {isAnnouncementVisible && (
+          <V2BetaAnnouncement
+            canExportBackup={canExportBackup}
+            dismissalCookieName={dismissalCookieName}
+            onDismiss={() => setIsAnnouncementVisible(false)}
+          />
+        )}
+        {header}
+      </AppShellHeader>
+      <AppShellMain>{children}</AppShellMain>
+    </ClientShell>
+  );
+};
@@ -21,17 +21,9 @@ interface UserAvatarMenuProps {
  children: ReactNode;
  availableUpdates?: RouterOutputs["updateChecker"]["getAvailableUpdates"];
  isDockerEnabled?: boolean;
-  opened: boolean;
-  onOpenChange: (opened: boolean) => void;
 }

-export const UserAvatarMenu = ({
-  children,
-  availableUpdates,
-  isDockerEnabled,
-  opened,
-  onOpenChange,
-}: UserAvatarMenuProps) => {
+export const UserAvatarMenu = ({ children, availableUpdates, isDockerEnabled }: UserAvatarMenuProps) => {
  const t = useScopedI18n("common.userAvatar.menu");
  const session = useSession();

@@ -48,7 +40,7 @@ export const UserAvatarMenu = ({

  return (
    // We use keepMounted so we can add event listeners to prevent navigating away without saving the board
-    <Menu width={300} withinPortal keepMounted opened={opened} onChange={onOpenChange}>
+    <Menu width={300} withinPortal keepMounted>
      <Menu.Dropdown>
        <AvailableUpdatesMenuItem availableUpdates={availableUpdates} />
        <Menu.Item component={Link} href="/boards" leftSection={<IconHome size="1rem" />}>
@@ -429,6 +429,13 @@
  <br/>  
  <p align="center">Uptime<br/>Kuma</p>
 </a>
+</td>
+<td align="center">
+<a href="https://homarr.dev/docs/integrations/whats-up-docker" target="_blank" rel="noreferrer noopener">
+  <img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/whats-up-docker.svg" alt="What's Up Docker" width="90" height="90" />
+  <br/>  
+  <p align="center">What's<br/>Up<br/>Docker</p>
+</a>
 </td></tr>
 </tbody>
 </table>
@@ -45,7 +45,10 @@ describe("Custom JSX custom widgets", () => {
      await page.goto(`${baseUrl}/auth/login`);
      await page.getByLabel("Username").fill(adminCredentials.username);
      await page.locator("#password").fill(adminCredentials.password);
-      const loginNavigation = page.waitForURL(baseUrl, { timeout: 15_000, waitUntil: "commit" });
+      const loginNavigation = page.waitForURL((url) => url.origin === baseUrl && url.pathname !== "/auth/login", {
+        timeout: 60_000,
+        waitUntil: "commit",
+      });
      await page.locator("css=button[type='submit']").click();
      await loginNavigation;

@@ -7,42 +7,6 @@ import { createHomarrContainer } from "./shared/create-homarr-container";
 import { createSqliteDbFileAsync } from "./shared/e2e-db";

 describe("Onboarding", () => {
-  test("Credentials onboarding should be successful", async () => {
-    // Arrange
-    const { db, localMountPath } = await createSqliteDbFileAsync();
-    const homarrContainer = await createHomarrContainer({
-      mounts: {
-        "/appdata": localMountPath,
-      },
-    }).start();
-
-    const browser = await chromium.launch();
-    const context = await browser.newContext();
-    const page = await context.newPage();
-    const actions = new OnboardingActions(page, db);
-    const assertions = new OnboardingAssertions(page, db);
-
-    try {
-      // Act
-      await page.goto(`http://${homarrContainer.getHost()}:${homarrContainer.getMappedPort(7575)}`);
-      await actions.startOnboardingAsync("scratch");
-      await actions.processUserStepAsync({
-        username: "admin",
-        password: "Comp(exP4sswOrd",
-        confirmPassword: "Comp(exP4sswOrd",
-      });
-      await actions.processSettingsStepAsync();
-      await actions.processIntegrationsStepAsync();
-
-      // Assert
-      await assertions.assertFinishStepVisibleAsync();
-      await assertions.assertUserAndAdminGroupInsertedAsync("admin");
-      await assertions.assertDbOnboardingStepAsync("finish");
-    } finally {
-      await Promise.all([browser.close(), homarrContainer.stop()]);
-    }
-  }, 60_000);
-
  test("External provider onboarding setup should be successful", async () => {
    // Arrange
    const { db, localMountPath } = await createSqliteDbFileAsync();
@@ -9,7 +9,7 @@ http {

        # Route websockets traffic to port 3001
        location /websockets {
-            proxy_pass http://${HOSTNAME}:3001;
+            proxy_pass http://127.0.0.1:3001;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "Upgrade";
@@ -18,7 +18,7 @@ http {

        # Route all other traffic to port 3000
        location / {
-            proxy_pass http://${HOSTNAME}:3000;
+            proxy_pass http://127.0.0.1:3000;
            proxy_set_header Host $http_host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
@@ -1,6 +1,6 @@
 {
  "name": "homarr",
-  "version": "1.74.0",
+  "version": "1.76.2",
  "private": true,
  "scripts": {
    "build": "cross-env CI=true turbo build",
@@ -1,4 +1,4 @@
-import { and, like } from "@homarr/db";
+import { getImageMatchRank, normalizeImageName } from "@homarr/common";
 import { icons } from "@homarr/db/schema";
 import { iconsFindSchema } from "@homarr/validation/icons";

@@ -15,38 +15,41 @@ export const iconsRouter = createTRPCRouter({
    })
    .input(iconsFindSchema)
    .query(async ({ ctx, input }) => {
-      const term = input.searchText?.toLowerCase().trim() ?? "";
-      const keywords = (input.searchText ?? "").split(" ").filter((keyword) => keyword.length > 0);
-
-      let whereCondition = undefined;
-      if (term.length > 0) {
-        whereCondition = and(...keywords.map((keyword) => like(icons.name, `%${keyword}%`)));
-      }
+      const term = normalizeImageName(input.searchText ?? "");
+      const repositories = await ctx.db.query.iconRepositories.findMany({
+        orderBy: (table, { asc, sql }) => [sql`CASE WHEN ${table.slug} = 'local' THEN 0 ELSE 1 END`, asc(table.slug)],
+        with: {
+          icons: {
+            columns: { id: true, name: true, url: true },
+            orderBy: (table, { asc, sql }) => [
+              sql`CASE WHEN ${table.name} LIKE '%.svg' THEN 0 ELSE 1 END`,
+              asc(table.name),
+            ],
+            limit: term.length === 0 ? input.limitPerGroup : undefined,
+          },
+        },
+      });

      return {
-        icons: await ctx.db.query.iconRepositories.findMany({
-          with: {
-            icons: {
-              columns: { id: true, name: true, url: true },
-              where: whereCondition,
-              orderBy: (table, { asc, sql }) => {
-                const svgFirst = sql`CASE WHEN ${table.name} LIKE '%.svg' THEN 0 ELSE 1 END`;
-                const nameAsc = asc(table.name);
-                if (term.length === 0) {
-                  return [svgFirst, nameAsc];
-                }
-                const tier = sql`CASE
-                  WHEN LOWER(${table.name}) = ${term} THEN 0
-                  WHEN LOWER(${table.name}) LIKE ${term + "%"} THEN 1
-                  WHEN LOWER(${table.name}) LIKE ${`%${term}%`} THEN 2
-                  ELSE 3
-                END`;
-                return [tier, svgFirst, nameAsc];
-              },
-              limit: input.limitPerGroup,
-            },
-          },
-        }),
+        icons:
+          term.length === 0
+            ? repositories
+            : repositories.map((repository) => ({
+                ...repository,
+                icons: repository.icons
+                  .flatMap((icon) => {
+                    const rank = getImageMatchRank(term, icon.name || icon.url);
+                    return rank === null ? [] : [{ icon, rank }];
+                  })
+                  .toSorted((a, b) =>
+                    a.rank !== b.rank
+                      ? a.rank - b.rank
+                      : Number(b.icon.name.toLowerCase().endsWith(".svg")) -
+                          Number(a.icon.name.toLowerCase().endsWith(".svg")) || a.icon.name.localeCompare(b.icon.name),
+                  )
+                  .slice(0, input.limitPerGroup)
+                  .map(({ icon }) => icon),
+              })),
        countIcons: await ctx.db.$count(icons),
      };
    }),
@@ -0,0 +1,44 @@
+import { describe, expect, test } from "vitest";
+
+import { iconRepositories, icons } from "@homarr/db/schema";
+import { createDb } from "@homarr/db/test";
+
+import { iconsRouter } from "../icons";
+
+describe("findIcons", () => {
+  test.each(["homeassistant", "home_assistant", "home assistant.png"])(
+    "matches normalized search %s before applying the group limit",
+    async (searchText) => {
+      const db = createDb();
+      const caller = iconsRouter.createCaller({ db, deviceType: undefined, session: null });
+
+      await db.insert(iconRepositories).values({ id: "repository", slug: "dashboard-icons" });
+      await db.insert(icons).values([
+        {
+          id: "irrelevant",
+          name: "000-unrelated.svg",
+          url: "https://example.com/000-unrelated.svg",
+          checksum: "irrelevant",
+          iconRepositoryId: "repository",
+        },
+        {
+          id: "home-assistant",
+          name: "home-assistant.svg",
+          url: "https://example.com/home-assistant.svg",
+          checksum: "home-assistant",
+          iconRepositoryId: "repository",
+        },
+      ]);
+
+      const result = await caller.findIcons({ searchText, limitPerGroup: 1 });
+
+      expect(result.icons[0]?.icons).toEqual([
+        {
+          id: "home-assistant",
+          name: "home-assistant.svg",
+          url: "https://example.com/home-assistant.svg",
+        },
+      ]);
+    },
+  );
+});
@@ -44,4 +44,5 @@ export const widgetRouter = createTRPCRouter({
  traefik: lazy(() => import("./traefik").then((mod) => mod.traefikRouter)),
  customApi: lazy(() => import("./custom-api").then((mod) => mod.customApiRouter)),
  secrets: lazy(() => import("./widget-secrets").then((mod) => mod.widgetSecretsRouter)),
+  wud: lazy(() => import("./wud").then((mod) => mod.wudRouter)),
 });
@@ -1,3 +1,4 @@
+import { TRPCError } from "@trpc/server";
 import { z } from "zod/v4";

 import { getIntegrationKindsByCategory } from "@homarr/definitions";
@@ -41,6 +42,13 @@ export const smartHomeRouter = createTRPCRouter({
      const client = await createIntegrationAsync(integration);
      const success = await client.triggerToggleAsync(input.entityId);

+      if (!success) {
+        throw new TRPCError({
+          code: "INTERNAL_SERVER_ERROR",
+          message: "Home Assistant failed to toggle the entity",
+        });
+      }
+
      return success;
    }),
  executeAutomation: protectedProcedure
@@ -55,6 +63,13 @@ export const smartHomeRouter = createTRPCRouter({
    .input(z.object({ automationId: z.string() }))
    .mutation(async ({ ctx: { integration }, input }) => {
      const client = await createIntegrationAsync(integration);
-      await client.triggerAutomationAsync(input.automationId);
+      const success = await client.triggerAutomationAsync(input.automationId);
+
+      if (!success) {
+        throw new TRPCError({
+          code: "INTERNAL_SERVER_ERROR",
+          message: "Home Assistant failed to trigger the automation",
+        });
+      }
    }),
 });
@@ -0,0 +1,25 @@
+import { wudStatsRequestHandler } from "@homarr/request-handler/wud";
+
+import { createOneIntegrationMiddleware } from "../../middlewares/integration";
+import { createTRPCRouter, publicProcedure } from "../../trpc";
+
+export const wudRouter = createTRPCRouter({
+  getStats: publicProcedure
+    .meta({
+      mcp: {
+        enabled: true,
+        description:
+          "Returns monitored-container counts and available updates from a What's Up Docker integration. REQUIRED: integrationId from integration_all. The caller needs query permission for that integration.",
+      },
+    })
+    .concat(createOneIntegrationMiddleware("query", "wud"))
+    .query(async ({ ctx }) => {
+      const handler = wudStatsRequestHandler.handler(ctx.integration, {});
+      const { data, timestamp } = await handler.getDataAsync();
+
+      return {
+        stats: data,
+        updatedAt: timestamp,
+      };
+    }),
+});
@@ -43,7 +43,7 @@ async function importCookiesAsync() {

 function getBaseUrl() {
  if (typeof window !== "undefined") return window.location.origin;
-  return `http://${process.env.HOSTNAME ?? "localhost"}:3000`;
+  return "http://127.0.0.1:3000";
 }

 export const trpcPath = "/api/trpc";
@@ -28,3 +28,34 @@ export const bestMatch = <TItem extends Record<string, unknown>>(
    return best;
  }, null);
 };
+
+export const normalizeImageName = (value: string) => {
+  const fileName = value.split(/[?#]/, 1)[0]?.split("/").pop() ?? value;
+  const withoutExtension = fileName.replace(/\.(?:avif|gif|jpe?g|png|svg|webp)$/i, "");
+
+  return withoutExtension
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/&/g, " and ")
+    .replace(/[^\p{L}\p{M}\p{N}]+/gu, " ")
+    .trim()
+    .toLowerCase();
+};
+
+export const getImageMatchRank = (normalizedSearch: string, candidateValue: string): number | null => {
+  const candidate = normalizeImageName(candidateValue);
+  if (!candidate) return null;
+
+  const compactSearch = normalizedSearch.replaceAll(" ", "");
+  const compactCandidate = candidate.replaceAll(" ", "");
+  if (candidate === normalizedSearch) return 0;
+  if (compactCandidate === compactSearch) return 1;
+  if (candidate.startsWith(`${normalizedSearch} `)) return 2;
+
+  const searchTokens = normalizedSearch.split(" ");
+  const candidateTokens = candidate.split(" ");
+  if (searchTokens.every((term) => candidateTokens.some((token) => token === term))) return 3;
+  if (searchTokens.every((term) => candidateTokens.some((token) => token.startsWith(term)))) return 4;
+  if (candidate.includes(normalizedSearch)) return 5;
+  return null;
+};
@@ -1,6 +1,6 @@
 import { describe, expect, test } from "vitest";

-import { bestMatch, capitalize } from "../string";
+import { bestMatch, capitalize, getImageMatchRank, normalizeImageName } from "../string";

 const capitalizeTestCases = [
  ["hello", "Hello"],
@@ -54,3 +54,27 @@ describe("bestMatch should find the best match in an array of options", () => {
    expect(result).toBeNull();
  });
 });
+
+describe("image name matching", () => {
+  test.each([
+    ["home-assistant.svg", "home assistant"],
+    ["https://example.com/Home_Assistant.PNG?v=1", "home assistant"],
+    ["jelly.fin.webp", "jelly fin"],
+    ["Caf\u00e9.svg", "cafe"],
+    ["\u6771\u4eac.svg", "\u6771\u4eac"],
+    ["\u0939\u093f\u0928\u094d\u0926\u0940.svg", "\u0939\u093f\u0928\u094d\u0926\u0940"],
+  ])("normalizes %s", (value, expected) => {
+    expect(normalizeImageName(value)).toBe(expected);
+  });
+
+  test.each([
+    ["homeassistant", "home-assistant.svg", 1],
+    ["home assistant", "home_assistant.png", 0],
+    ["home assistant", "Home Assistant.webp", 0],
+    ["\u6771\u4eac", "\u6771\u4eac.svg", 0],
+    ["\u0939\u093f\u0928\u094d\u0926\u0940", "\u0939\u093f\u0928\u094d\u0926\u0940.png", 0],
+    ["home assistant", "unrelated.svg", null],
+  ])("ranks %s against %s", (search, candidate, expected) => {
+    expect(getImageMatchRank(normalizeImageName(search), candidate)).toBe(expected);
+  });
+});
@@ -13,7 +13,6 @@ import { UndiciHttpAgent } from "@homarr/core/infrastructure/http";

 import type { TrustedCertificateHostname } from "../certificates/hostnames";
 import { withTimeoutAsync } from "./timeout";
-
 export const createCustomCheckServerIdentity = (
  trustedHostnames: TrustedCertificateHostname[],
 ): typeof checkServerIdentity => {
@@ -1,2 +1,3 @@
 export const colorSchemeCookieKey = "homarr.color-scheme";
 export const localeCookieKey = "homarr.locale";
+export const v2BetaAnnouncementCookieKey = "homarr.v2-beta-announcement";
@@ -210,6 +210,7 @@ export type HomarrDocumentationPath =
  | "/docs/integrations/unifi-controller"
  | "/docs/integrations/unraid"
  | "/docs/integrations/uptime-kuma"
+  | "/docs/integrations/whats-up-docker"
  | "/docs/management/api"
  | "/docs/management/apps"
  | "/docs/management/backup"
@@ -276,6 +277,7 @@ export type HomarrDocumentationPath =
  | "/docs/widgets/video"
  | "/docs/widgets/vpn"
  | "/docs/widgets/weather"
+  | "/docs/widgets/whats-up-docker"
  | ""
  | "/sitemap.xml"
  | "/docs/integrations/sabnzbd"
@@ -330,6 +332,7 @@ export type HomarrDocumentationPath =
  | "/docs/integrations/peanut"
  | "/docs/integrations/beszel"
  | "/docs/integrations/traefik"
+  | "/docs/integrations/whats-up-docker"
  | "/docs/widgets/clock"
  | "/docs/widgets/weather"
  | "/docs/widgets/app"
@@ -382,4 +385,5 @@ export type HomarrDocumentationPath =
  | "/docs/widgets/beszel-alerts"
  | "/docs/widgets/beszel-system-stats"
  | "/docs/widgets/traefik"
-  | "/docs/widgets/custom-api";
+  | "/docs/widgets/custom-api"
+  | "/docs/widgets/whats-up-docker";
@@ -54,5 +54,6 @@ export const integrationDocSlugs: Record<IntegrationKind, string | null> = {
  beszel: "beszel",
  traefik: "traefik",
  archiveTeamWarrior: null,
+  wud: "whats-up-docker",
  mock: null,
 };
@@ -55,4 +55,5 @@ export const widgetDocSlugs: Record<WidgetKind, string | null> = {
  beszelSystemStats: "beszel-system-stats",
  traefik: "traefik",
  customApi: "custom-api",
+  wud: "whats-up-docker",
 };
@@ -468,6 +468,14 @@ export const integrationDefs = {
    category: ["archiving"],
    documentationUrl: null,
  },
+  wud: {
+    name: "What's Up Docker",
+    secretKinds: [[], ["username", "password"]],
+    iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/whats-up-docker.svg",
+    category: ["healthMonitoring"],
+    documentationUrl: createDocumentationLink("/docs/integrations/whats-up-docker"),
+    defaultPort: 3000,
+  },
  // This integration only returns mock data, it is used during development (but can also be used in production by directly going to the create page)
  mock: {
    name: "Mock",
@@ -24,7 +24,9 @@ export const widgetIntegrationSupport: Partial<Record<WidgetKind, readonly Integ
  networkControllerSummary: getIntegrationKindsByCategory("networkController"),
  networkControllerStatus: getIntegrationKindsByCategory("networkController"),
  indexerManager: getIntegrationKindsByCategory("indexerManager"),
-  healthMonitoring: getIntegrationKindsByCategory("healthMonitoring").filter((kind) => kind !== "patchmon"),
+  healthMonitoring: getIntegrationKindsByCategory("healthMonitoring").filter(
+    (kind) => kind !== "patchmon" && kind !== "wud",
+  ),
  firewall: getIntegrationKindsByCategory("firewall"),
  notifications: getIntegrationKindsByCategory("notifications"),
  mediaReleases: ["mock", "emby", "jellyfin", "plex"],
@@ -50,6 +52,7 @@ export const widgetIntegrationSupport: Partial<Record<WidgetKind, readonly Integ
  archiveTeamWarrior: ["archiveTeamWarrior"],
  anchorNote: ["anchor"],
  traefik: ["traefik"],
+  wud: ["wud"],
 };

 export const getWidgetKindsForIntegration = (integrationKind: IntegrationKind): WidgetKind[] => {
@@ -53,6 +53,7 @@ export const widgetKinds = [
  "beszelSystemStats",
  "traefik",
  "customApi",
+  "wud",
 ] as const;
 export type WidgetKind = (typeof widgetKinds)[number];

@@ -1,3 +1,89 @@
-[data-combobox-selected="true"] .iconCard {
-  border-color: var(--mantine-primary-color-6);
+.dropdown {
+  min-width: min(32rem, calc(100vw - 2rem));
+}
+
+.options {
+  max-height: min(28rem, 60vh);
+  overflow-y: auto;
+  overscroll-behavior: contain;
+}
+
+.iconGrid {
+  grid-template-columns: repeat(auto-fill, minmax(3.25rem, 1fr));
+}
+
+.iconOption {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 0;
+  height: 3.25rem;
+  padding: var(--mantine-spacing-xs);
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: var(--mantine-radius-md);
+  background: var(--mantine-color-body);
+  transition:
+    border-color 160ms ease,
+    background-color 160ms ease,
+    transform 160ms ease;
+}
+
+.iconOption:hover,
+.iconOption[data-combobox-selected="true"] {
+  border-color: var(--mantine-primary-color-6);
+  background: var(--mantine-primary-color-light);
+}
+
+.iconOption:active {
+  transform: scale(0.96);
+}
+
+.formatBadge,
+.sectionBadge {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--mantine-radius-xs);
+  background: var(--mantine-color-red-9);
+  color: var(--mantine-color-white);
+  font-size: 0.625rem;
+  font-weight: 700;
+  line-height: 1;
+}
+
+.formatBadge {
+  position: absolute;
+  top: 0.2rem;
+  right: 0.2rem;
+  padding: 0.15rem 0.2rem;
+}
+
+.sectionBadge {
+  padding: 0.2rem 0.3rem;
+}
+
+.urlPreview {
+  background: var(--mantine-color-default-hover);
+}
+
+.previewFrame {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 3rem;
+  height: 3rem;
+  flex: 0 0 3rem;
+}
+
+.previewLoader {
+  position: absolute;
+  z-index: 1;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .iconOption {
+    transition: none;
+  }
 }
@@ -4,31 +4,84 @@ import { afterEach, beforeAll, beforeEach, describe, expect, test, vi } from "vi
 import { MantineProvider } from "@mantine/core";

 import type { Root } from "react-dom/client";
+import type { IconGroup } from "./icon-picker.utils";

-const { findIconsQuery } = vi.hoisted(() => ({
-  findIconsQuery: vi.fn((_query: { searchText: string }) => ({
-    data: { icons: [], countIcons: 0 },
-    isLoading: false,
-    isError: false,
-    refetch: vi.fn(),
-  })),
+const { findIconsQuery, refetch, uploadSelection, sessionPermissions } = vi.hoisted(() => ({
+  findIconsQuery: vi.fn(),
+  refetch: vi.fn(),
+  uploadSelection: vi.fn(),
+  sessionPermissions: { current: [] as string[] },
 }));

+interface QueryData {
+  icons: IconGroup[];
+  countIcons: number;
+}
+
+const emptyResult: QueryData = { icons: [], countIcons: 11_000 };
+let queryResult: {
+  data?: QueryData;
+  isLoading: boolean;
+  isFetching: boolean;
+  isError: boolean;
+};
+
 vi.mock("@homarr/api/client", () => ({
-  clientApi: { icon: { findIcons: { useQuery: findIconsQuery } } },
+  clientApi: {
+    icon: {
+      findIcons: {
+        useQuery: (input: { searchText: string; limitPerGroup: number }, options: { enabled: boolean }) => {
+          findIconsQuery(input, options);
+          return { ...queryResult, refetch };
+        },
+      },
+    },
+  },
 }));
 vi.mock("@homarr/auth/client", () => ({
-  useSession: () => ({ data: { user: { permissions: [] } } }),
+  useSession: () => ({ data: { user: { permissions: sessionPermissions.current } } }),
 }));
 vi.mock("@homarr/translation", () => ({ supportedLanguages: [] }));
 vi.mock("@homarr/translation/client", () => ({
-  useScopedI18n: () => (key: string) => key,
+  useScopedI18n: () => (key: string, params?: Record<string, string>) =>
+    params ? `${key}:${Object.values(params).join(",")}` : key,
+}));
+vi.mock("../upload-media/upload-media", () => ({
+  UploadMedia: ({
+    children,
+    onSuccess,
+  }: {
+    children: (props: object) => unknown;
+    onSuccess: (medias: unknown) => void;
+  }) =>
+    children({
+      loading: false,
+      onClick: () => {
+        uploadSelection();
+        onSuccess([{ id: "uploaded", url: "/api/user-medias/uploaded" }]);
+      },
+    }),
 }));
-vi.mock("../upload-media/upload-media", () => ({ UploadMedia: () => null }));

 import { IconPicker } from "./icon-picker";

-const directIconUrl = "https://cdn.example.com/shopify.svg";
+const directImageUrl = "https://cdn.example.com/shopify.svg";
+
+const iconGroups = [
+  {
+    id: "remote",
+    slug: "dashboard-icons",
+    icons: [
+      { id: "png", name: "shopify.png", url: "https://cdn.example.com/shopify.png" },
+      { id: "svg", name: "shopify.svg", url: "https://cdn.example.com/shopify.svg" },
+    ],
+  },
+  {
+    id: "local",
+    slug: "local",
+    icons: [{ id: "local-icon", name: "my-shop.png", url: "/api/user-medias/local-icon" }],
+  },
+];

 const setInputValue = (input: HTMLInputElement, value: string) => {
  const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
@@ -37,6 +90,18 @@ const setInputValue = (input: HTMLInputElement, value: string) => {
  input.dispatchEvent(new Event("input", { bubbles: true }));
 };

+const pressKey = (input: HTMLInputElement, key: string, init?: KeyboardEventInit) => {
+  input.dispatchEvent(new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true, ...init }));
+};
+
+const focusInput = async (input: HTMLInputElement) => {
+  await act(async () => input.focus());
+};
+
+const advanceDebounce = async () => {
+  await act(async () => vi.advanceTimersByTimeAsync(300));
+};
+
 describe("IconPicker", () => {
  let container: HTMLDivElement;
  let root: Root;
@@ -45,9 +110,9 @@ describe("IconPicker", () => {
    Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", { value: true, writable: true });
    Object.defineProperty(window, "matchMedia", {
      writable: true,
-      value: (query: string) => ({
+      value: (media: string) => ({
        matches: false,
-        media: query,
+        media,
        onchange: null,
        addListener: () => undefined,
        removeListener: () => undefined,
@@ -56,54 +121,186 @@ describe("IconPicker", () => {
        dispatchEvent: () => false,
      }),
    });
+    Object.defineProperty(HTMLElement.prototype, "scrollIntoView", { value: () => undefined, writable: true });
  });

  beforeEach(() => {
+    vi.useFakeTimers();
    findIconsQuery.mockClear();
+    refetch.mockClear();
+    uploadSelection.mockClear();
+    sessionPermissions.current = [];
+    queryResult = { data: emptyResult, isLoading: false, isFetching: false, isError: false };
  });

  afterEach(() => {
-    root.unmount();
+    act(() => root.unmount());
    container.remove();
+    document.querySelectorAll("[data-combobox-dropdown]").forEach((element) => element.remove());
+    vi.useRealTimers();
  });

-  const renderPicker = async (onChange: (value: string) => void) => {
+  const renderPicker = async (
+    onChange: (value: string) => void,
+    props: Partial<React.ComponentProps<typeof IconPicker>> = {},
+  ) => {
    container = document.createElement("div");
    document.body.appendChild(container);
    root = createRoot(container);
    await act(async () => {
-      root.render(createElement(MantineProvider, null, createElement(IconPicker, { value: "", onChange })));
+      root.render(createElement(MantineProvider, null, createElement(IconPicker, { value: "", onChange, ...props })));
    });
    const input = container.querySelector("input");
    if (!input) throw new Error("Icon picker input was not rendered");
    return input;
  };

-  test("keeps a direct URL visible without searching the icon repositories", async () => {
+  test("clears an existing value without restoring it", async () => {
    const onChange = vi.fn();
-    const input = await renderPicker(onChange);
+    const input = await renderPicker(onChange, { value: directImageUrl });

-    await act(async () => {
-      setInputValue(input, directIconUrl);
-      await new Promise((resolve) => setTimeout(resolve, 150));
-    });
+    await act(async () => setInputValue(input, ""));

-    expect(onChange).toHaveBeenCalledWith(directIconUrl);
-    expect(input.value).toBe(directIconUrl);
-    expect(findIconsQuery.mock.calls.some(([query]) => query.searchText === directIconUrl)).toBe(false);
+    expect(onChange).toHaveBeenCalledWith("");
+    expect(input.value).toBe("");
  });

-  test("keeps icon names in repository search mode", async () => {
-    const onChange = vi.fn();
-    const input = await renderPicker(onChange);
+  test.each([{ metaKey: true }, { ctrlKey: true }])(
+    "clears the entire value with a line-delete shortcut",
+    async (modifier) => {
+      const onChange = vi.fn();
+      const input = await renderPicker(onChange, { value: directImageUrl });

-    await act(async () => {
-      setInputValue(input, "shopify");
-      await new Promise((resolve) => setTimeout(resolve, 150));
-    });
+      await act(async () => pressKey(input, "Backspace", modifier));

-    expect(onChange).not.toHaveBeenCalled();
-    expect(input.value).toBe("shopify");
+      expect(onChange).toHaveBeenCalledWith("");
+      expect(input.value).toBe("");
+    },
+  );
+
+  test("debounces repository searches", async () => {
+    const input = await renderPicker(vi.fn());
+    findIconsQuery.mockClear();
+
+    await act(async () => setInputValue(input, "shopify"));
+    expect(findIconsQuery.mock.calls.some(([query]) => query.searchText === "shopify")).toBe(false);
+
+    await advanceDebounce();
    expect(findIconsQuery.mock.calls.some(([query]) => query.searchText === "shopify")).toBe(true);
  });
+
+  test("pre-searches the suggested app name when opened", async () => {
+    const input = await renderPicker(vi.fn(), { suggestedSearch: "Jellyfin" });
+
+    await focusInput(input);
+    expect(input.value).toBe("Jellyfin");
+    await advanceDebounce();
+
+    expect(findIconsQuery.mock.calls.some(([query]) => query.searchText === "Jellyfin")).toBe(true);
+  });
+
+  test("shows local images before SVG and raster library images", async () => {
+    queryResult = { data: { icons: iconGroups, countIcons: 3 }, isLoading: false, isFetching: false, isError: false };
+    const input = await renderPicker(vi.fn());
+
+    await focusInput(input);
+    const content = document.body.textContent ?? "";
+
+    expect(document.body.querySelector('[role="listbox"]')?.getAttribute("aria-label")).toBe("iconPicker.results");
+    expect(content.indexOf("iconPicker.localImages")).toBeLessThan(content.indexOf("iconPicker.svgIcons"));
+    expect(content.indexOf("iconPicker.svgIcons")).toBeLessThan(content.indexOf("iconPicker.otherImages"));
+  });
+
+  test("selects a library image with a pointer", async () => {
+    queryResult = { data: { icons: iconGroups, countIcons: 3 }, isLoading: false, isFetching: false, isError: false };
+    const onChange = vi.fn();
+    const input = await renderPicker(onChange);
+    await focusInput(input);
+
+    const option = document.body.querySelector<HTMLElement>(
+      '[data-combobox-option][value="/api/user-medias/local-icon"]',
+    );
+    if (!option) throw new Error("Local image option was not rendered");
+    await act(async () => option.click());
+
+    expect(onChange).toHaveBeenCalledWith("/api/user-medias/local-icon");
+    expect(input.value).toBe("/api/user-medias/local-icon");
+  });
+
+  test("selects a library image with the keyboard", async () => {
+    queryResult = { data: { icons: iconGroups, countIcons: 3 }, isLoading: false, isFetching: false, isError: false };
+    const onChange = vi.fn();
+    const input = await renderPicker(onChange);
+    await focusInput(input);
+
+    await act(async () => pressKey(input, "ArrowDown"));
+    await act(async () => pressKey(input, "Enter"));
+
+    expect(onChange).toHaveBeenCalledWith("/api/user-medias/local-icon");
+  });
+
+  test("keeps a direct URL visible and reports a successful preview", async () => {
+    const onChange = vi.fn();
+    const input = await renderPicker(onChange);
+
+    await act(async () => setInputValue(input, directImageUrl));
+
+    expect(onChange).toHaveBeenCalledWith(directImageUrl);
+    expect(input.value).toBe(directImageUrl);
+    expect(findIconsQuery.mock.calls.at(-1)?.[1]).toMatchObject({ enabled: false });
+    expect(document.body.textContent).toContain("iconPicker.urlLoading");
+
+    const preview = document.body.querySelector('[data-testid="direct-url-preview"]');
+    if (!preview) throw new Error("Direct URL preview was not rendered");
+    await act(async () => preview.dispatchEvent(new Event("load")));
+    expect(document.body.textContent).toContain("iconPicker.urlReady");
+  });
+
+  test("keeps a failed direct URL editable and shows an error", async () => {
+    const input = await renderPicker(vi.fn());
+    await act(async () => setInputValue(input, "https://invalid.example/image.png"));
+
+    const preview = document.body.querySelector('[data-testid="direct-url-preview"]');
+    if (!preview) throw new Error("Direct URL preview was not rendered");
+    await act(async () => preview.dispatchEvent(new Event("error")));
+
+    expect(input.value).toBe("https://invalid.example/image.png");
+    expect(document.body.textContent).toContain("iconPicker.urlError");
+  });
+
+  test("restores the committed value when an unfinished search is cancelled", async () => {
+    const input = await renderPicker(vi.fn(), { value: directImageUrl });
+
+    await act(async () => setInputValue(input, "unfinished search"));
+    await act(async () => pressKey(input, "Escape"));
+
+    expect(input.value).toBe(directImageUrl);
+  });
+
+  test("offers retry when the repository search fails", async () => {
+    queryResult = { data: undefined, isLoading: false, isFetching: false, isError: true };
+    const input = await renderPicker(vi.fn());
+    await focusInput(input);
+
+    const retry = Array.from(document.body.querySelectorAll("button")).find(
+      (button) => button.textContent === "action.tryAgain",
+    );
+    if (!retry) throw new Error("Retry button was not rendered");
+    await act(async () => retry.click());
+
+    expect(refetch).toHaveBeenCalledOnce();
+  });
+
+  test("selects an uploaded local image when the user has permission", async () => {
+    sessionPermissions.current = ["media-upload"];
+    const onChange = vi.fn();
+    await renderPicker(onChange);
+
+    const upload = container.querySelector<HTMLButtonElement>('[aria-label="iconPicker.uploadImage"]');
+    if (!upload) throw new Error("Upload button was not rendered");
+    await act(async () => upload.click());
+
+    expect(uploadSelection).toHaveBeenCalledOnce();
+    expect(onChange).toHaveBeenCalledWith("/api/user-medias/uploaded");
+  });
 });
@@ -1,27 +1,36 @@
 "use client";

-import type { FocusEventHandler } from "react";
-import { startTransition, useEffect, useState } from "react";
+import type { FocusEventHandler, KeyboardEventHandler } from "react";
+import { startTransition, useEffect, useMemo, useState } from "react";
 import {
  ActionIcon,
  Box,
  Button,
-  Card,
+  CloseButton,
  Combobox,
-  Flex,
  Group,
  Image,
-  Indicator,
  InputBase,
+  Loader,
  Paper,
+  SimpleGrid,
  Skeleton,
  Stack,
  Text,
-  UnstyledButton,
+  ThemeIcon,
+  Tooltip,
  useCombobox,
 } from "@mantine/core";
 import { useDebouncedValue, useUncontrolled } from "@mantine/hooks";
-import { IconMoodEmpty, IconSearchOff, IconUpload } from "@tabler/icons-react";
+import {
+  IconCheck,
+  IconCloud,
+  IconMoodEmpty,
+  IconPhoto,
+  IconPhotoOff,
+  IconSearchOff,
+  IconUpload,
+} from "@tabler/icons-react";

 import { clientApi } from "@homarr/api/client";
 import { useSession } from "@homarr/auth/client";
@@ -29,6 +38,7 @@ import { supportedLanguages } from "@homarr/translation";
 import { useScopedI18n } from "@homarr/translation/client";

 import { UploadMedia } from "../upload-media/upload-media";
+import { arrangeIconPickerSections, isDirectImageUrl, isImageSource, isSvgImage } from "./icon-picker.utils";
 import classes from "./icon-picker.module.css";

 interface IconPickerProps {
@@ -39,9 +49,12 @@ interface IconPickerProps {
  onBlur?: FocusEventHandler;
  label?: string;
  placeholder?: string;
+  suggestedSearch?: string | null;
  withAsterisk?: boolean;
 }

+type PreviewState = "idle" | "loading" | "ready" | "error";
+
 export const IconPicker = ({
  value: propsValue,
  onChange,
@@ -51,188 +64,403 @@ export const IconPicker = ({
  withAsterisk = true,
  label,
  placeholder,
+  suggestedSearch,
 }: IconPickerProps) => {
-  const [value, setValue] = useUncontrolled({ value: propsValue, onChange });
-  const [query, setQuery] = useState("");
-
-  useEffect(() => {
-    setQuery("");
-  }, [value]);
-
+  const [value, setValue] = useUncontrolled({ value: propsValue, onChange, defaultValue: "" });
+  const [draft, setDraft] = useState(propsValue ?? "");
+  const [hasEdited, setHasEdited] = useState(false);
+  const [keyboardIndex, setKeyboardIndex] = useState(-1);
+  const [previewState, setPreviewState] = useState<PreviewState>("idle");
  const { data: session } = useSession();
  const tCommon = useScopedI18n("common");
-  const [debouncedQuery] = useDebouncedValue(query, 100);
+  const [debouncedDraft] = useDebouncedValue(draft, 250);

-  const searchText = !isDirectIconUrl(debouncedQuery) && debouncedQuery !== (value ?? "") ? debouncedQuery : "";
+  const directUrl = isDirectImageUrl(draft) ? draft.trim() : null;
+  const isCommittedValueDraft = debouncedDraft === (value ?? "");
+  const searchText = directUrl !== null || isCommittedValueDraft ? "" : debouncedDraft.trim();
+  const canUpload = session?.user.permissions.includes("media-upload") ?? false;

-  const { data, isLoading, isError, refetch } = clientApi.icon.findIcons.useQuery(
-    { searchText },
-    { placeholderData: (prev) => prev },
+  const query = clientApi.icon.findIcons.useQuery(
+    { searchText, limitPerGroup: 24 },
+    { enabled: directUrl === null, placeholderData: (previous) => previous },
  );

  const combobox = useCombobox({
    onDropdownClose: () => combobox.resetSelectedOption(),
+    onDropdownOpen: () => combobox.updateSelectedOptionIndex("active"),
  });

-  const totalOptions = data?.icons.reduce((acc, group) => acc + group.icons.length, 0) ?? 0;
-  const groups = data?.icons.map((group) => {
-    const options = group.icons.map((item) => (
-      <Combobox.Option
-        key={item.id}
-        value={item.url}
-        p={0}
-        h="calc(2*var(--mantine-spacing-sm)+25px)"
-        w="calc(2*var(--mantine-spacing-sm)+25px)"
-      >
-        <UnstyledButton
-          onClick={() => {
-            startTransition(() => {
-              setValue(item.url);
-              setQuery("");
-              combobox.closeDropdown();
-            });
-          }}
-        >
-          <Indicator label="SVG" disabled={!item.url.endsWith(".svg")} size={16}>
-            <Card p="sm" pos="relative" style={{ overflow: "visible", cursor: "pointer" }} className={classes.iconCard}>
-              <Box w={25} h={25}>
-                <Image src={item.url} w={25} h={25} />
-              </Box>
-            </Card>
-          </Indicator>
-        </UnstyledButton>
-      </Combobox.Option>
-    ));
+  useEffect(() => {
+    setDraft(value ?? "");
+    setHasEdited(false);
+  }, [value]);

-    return (
-      <Paper p="xs" key={group.slug} pt={2}>
-        <Text mb={8} size="sm" fw="bold">
-          {group.slug}
-        </Text>
-        <Flex gap={8} wrap={"wrap"}>
-          {options}
-        </Flex>
-      </Paper>
-    );
-  });
+  useEffect(() => {
+    setPreviewState(directUrl ? "loading" : "idle");
+  }, [directUrl]);

-  const inputValue = query || value || "";
-  const leftSection = shouldShowPreview(value) && <img src={value} alt="" style={{ width: 20, height: 20 }} />;
-  const placeholderText =
-    placeholder ||
-    (data && tCommon("iconPicker.header", { countIcons: String(data.countIcons) })) ||
-    tCommon("iconPicker.headerLoading");
+  const sections = useMemo(
+    () => arrangeIconPickerSections(query.data?.icons ?? [], searchText),
+    [query.data?.icons, searchText],
+  );
+  const orderedOptions = useMemo(
+    () => [...sections.local, ...sections.svg, ...sections.other],
+    [sections.local, sections.svg, sections.other],
+  );
+  const totalOptions = sections.local.length + sections.svg.length + sections.other.length;

-  const renderDropdown = () => {
-    if (isError) {
+  const commitValue = (nextValue: string) => {
+    startTransition(() => {
+      setValue(nextValue);
+      setDraft(nextValue);
+      setHasEdited(false);
+      setKeyboardIndex(-1);
+    });
+  };
+
+  const clearValue = () => {
+    commitValue("");
+    combobox.openDropdown("keyboard");
+  };
+
+  const openWithSuggestedSearch = () => {
+    if (!draft && !value && !hasEdited && suggestedSearch?.trim()) {
+      setDraft(suggestedSearch.trim());
+    }
+    combobox.openDropdown();
+  };
+
+  const handleKeyDown: KeyboardEventHandler<HTMLInputElement> = (event) => {
+    if ((event.metaKey || event.ctrlKey) && event.key === "Backspace") {
+      event.preventDefault();
+      clearValue();
+      return;
+    }
+
+    if (event.key === "Escape") {
+      setDraft(value ?? "");
+      setHasEdited(false);
+      combobox.closeDropdown("keyboard");
+      return;
+    }
+
+    if (!directUrl && orderedOptions.length > 0 && (event.key === "ArrowDown" || event.key === "ArrowUp")) {
+      event.preventDefault();
+      combobox.openDropdown("keyboard");
+      setKeyboardIndex((current) => {
+        const next =
+          event.key === "ArrowDown"
+            ? current >= orderedOptions.length - 1
+              ? 0
+              : current + 1
+            : current <= 0
+              ? orderedOptions.length - 1
+              : current - 1;
+        combobox.selectOption(next);
+        return next;
+      });
+      return;
+    }
+
+    if (event.key === "Enter") {
+      if (keyboardIndex >= 0 && orderedOptions[keyboardIndex]) {
+        event.preventDefault();
+        commitValue(orderedOptions[keyboardIndex].url);
+        combobox.closeDropdown("keyboard");
+      } else if (isImageSource(draft)) {
+        event.preventDefault();
+        commitValue(draft.trim());
+        combobox.closeDropdown("keyboard");
+      }
+    }
+  };
+
+  const renderIconOptions = (icons: typeof sections.local, offset: number) => (
+    <SimpleGrid className={classes.iconGrid} spacing={6} verticalSpacing={6}>
+      {icons.map((icon, index) => (
+        <Tooltip key={icon.id} label={`${icon.name} · ${icon.repositorySlug}`} openDelay={500}>
+          <Combobox.Option
+            value={icon.url}
+            aria-label={icon.name}
+            active={icon.url === value || keyboardIndex === offset + index}
+            className={classes.iconOption}
+          >
+            <Image src={icon.url} alt="" w={30} h={30} fit="contain" fallbackSrc="/logo/logo.png" />
+            {isSvgImage(icon.url) && <span className={classes.formatBadge}>SVG</span>}
+          </Combobox.Option>
+        </Tooltip>
+      ))}
+    </SimpleGrid>
+  );
+
+  const renderSearchResults = () => {
+    if (query.isError) {
      return (
-        <Stack align="center" gap="xs" p="md">
-          <IconSearchOff size={32} stroke={1.5} />
-          <Text size="sm">{tCommon("iconPicker.error")}</Text>
-          <Button size="xs" variant="default" onClick={() => refetch()}>
-            {tCommon("action.tryAgain")}
-          </Button>
-        </Stack>
+        <PickerMessage
+          icon={<IconSearchOff size={22} />}
+          title={tCommon("iconPicker.error")}
+          action={
+            <Button size="xs" variant="default" onClick={() => query.refetch()}>
+              {tCommon("action.tryAgain")}
+            </Button>
+          }
+        />
      );
    }
-    if (isLoading) {
-      return Array(15)
-        .fill(0)
-        .map((_, index) => (
-          <Combobox.Option value={`skeleton-${index}`} key={index} disabled>
-            <Skeleton height={25} visible />
-          </Combobox.Option>
-        ));
+
+    if (query.isLoading) {
+      return (
+        <SimpleGrid className={classes.iconGrid} spacing={6} verticalSpacing={6} p="xs">
+          {Array.from({ length: 12 }, (_, index) => (
+            <Skeleton key={index} height={52} radius="md" />
+          ))}
+        </SimpleGrid>
+      );
    }
-    if (totalOptions > 0) {
-      return <Stack gap={4}>{groups}</Stack>;
+
+    if (totalOptions === 0) {
+      return (
+        <PickerMessage
+          icon={<IconMoodEmpty size={22} />}
+          title={tCommon("iconPicker.noResults", { search: debouncedDraft.trim() })}
+        />
+      );
    }
+
    return (
-      <Stack align="center" gap="xs" p="md">
-        <IconMoodEmpty size={32} stroke={1.5} />
-        <Text size="sm">{tCommon("iconPicker.noResults", { search: debouncedQuery })}</Text>
+      <Stack gap="sm" p="xs">
+        {sections.local.length > 0 && (
+          <PickerSection icon={<IconPhoto size={15} />} label={tCommon("iconPicker.localImages")}>
+            {renderIconOptions(sections.local, 0)}
+          </PickerSection>
+        )}
+        {sections.svg.length > 0 && (
+          <PickerSection label={tCommon("iconPicker.svgIcons")} badge="SVG">
+            {renderIconOptions(sections.svg, sections.local.length)}
+          </PickerSection>
+        )}
+        {sections.other.length > 0 && (
+          <PickerSection icon={<IconCloud size={15} />} label={tCommon("iconPicker.otherImages")}>
+            {renderIconOptions(sections.other, sections.local.length + sections.svg.length)}
+          </PickerSection>
+        )}
      </Stack>
    );
  };

+  const leftSection = (() => {
+    if (directUrl && previewState === "loading") return <Loader size={15} />;
+    if (directUrl && previewState === "error") return <IconPhotoOff size={17} color="var(--mantine-color-red-6)" />;
+    if (shouldShowPreview(value)) {
+      return (
+        <Image
+          src={value}
+          alt=""
+          w={22}
+          h={22}
+          fit="contain"
+          onLoad={() => directUrl && setPreviewState("ready")}
+          onError={() => directUrl && setPreviewState("error")}
+        />
+      );
+    }
+    return <IconPhoto size={17} stroke={1.5} />;
+  })();
+
+  const placeholderText =
+    placeholder ??
+    (query.data
+      ? tCommon("iconPicker.header", { countIcons: String(query.data.countIcons) })
+      : tCommon("iconPicker.headerLoading"));
+
  return (
-    <Combobox store={combobox} withinPortal>
-      <Combobox.Target>
-        <Group wrap="nowrap" gap="xs" w="100%" align="start">
-          <InputBase
-            flex={1}
-            rightSection={<Combobox.Chevron />}
-            leftSection={leftSection}
-            value={inputValue}
-            onChange={(event) => {
-              const nextValue = event.currentTarget.value;
-              const trimmedValue = nextValue.trim();
-              setQuery(nextValue);
-              if (isDirectIconUrl(trimmedValue)) {
-                setValue(trimmedValue);
-                combobox.closeDropdown();
-              } else {
-                combobox.openDropdown();
-              }
-            }}
-            onClick={() => combobox.openDropdown()}
-            onFocus={(event) => {
-              onFocus?.(event);
-              combobox.openDropdown();
-            }}
-            onBlur={(event) => {
-              onBlur?.(event);
-              combobox.closeDropdown();
-              setQuery("");
-            }}
-            rightSectionPointerEvents="none"
-            withAsterisk={withAsterisk}
-            error={error}
-            label={label ?? tCommon("iconPicker.label")}
-            placeholder={placeholderText}
-          />
-          {session?.user.permissions.includes("media-upload") && (
-            <UploadMedia
-              onSuccess={(medias) => {
-                const first = medias.at(0);
-                if (!first) return;
-                startTransition(() => {
-                  setValue(first.url);
-                });
-              }}
-            >
-              {({ onClick, loading }) => (
-                <ActionIcon onClick={onClick} loading={loading} mt={24} size={36} variant="default">
-                  <IconUpload size={16} stroke={1.5} />
-                </ActionIcon>
+    <Combobox
+      store={combobox}
+      withinPortal
+      resetSelectionOnOptionHover
+      onOptionSubmit={(url) => {
+        commitValue(url);
+        combobox.closeDropdown();
+      }}
+    >
+      <Combobox.Target withExpandedAttribute>
+        <InputBase
+          flex={1}
+          leftSection={leftSection}
+          rightSection={
+            <Group gap={2} wrap="nowrap">
+              {canUpload && (
+                <UploadMedia
+                  onSuccess={(medias) => {
+                    const first = medias.at(0);
+                    if (!first) return;
+                    commitValue(first.url);
+                    combobox.closeDropdown();
+                  }}
+                >
+                  {({ onClick, loading }) => (
+                    <Tooltip label={tCommon("iconPicker.uploadImage")}>
+                      <ActionIcon
+                        onClick={(event) => {
+                          event.stopPropagation();
+                          onClick();
+                        }}
+                        loading={loading}
+                        size="sm"
+                        variant="subtle"
+                        aria-label={tCommon("iconPicker.uploadImage")}
+                      >
+                        <IconUpload size={16} stroke={1.5} />
+                      </ActionIcon>
+                    </Tooltip>
+                  )}
+                </UploadMedia>
              )}
-            </UploadMedia>
-          )}
-        </Group>
+              {(draft || value) && (
+                <CloseButton
+                  size="sm"
+                  aria-label={tCommon("iconPicker.clear")}
+                  onMouseDown={(event) => event.preventDefault()}
+                  onClick={clearValue}
+                />
+              )}
+              {query.isFetching && !directUrl ? <Loader size={14} /> : <Combobox.Chevron />}
+            </Group>
+          }
+          rightSectionWidth={canUpload ? 86 : 56}
+          rightSectionPointerEvents="all"
+          value={draft}
+          onChange={(event) => {
+            const nextValue = event.currentTarget.value;
+            setDraft(nextValue);
+            setHasEdited(true);
+            setKeyboardIndex(-1);
+            combobox.openDropdown("keyboard");
+            combobox.updateSelectedOptionIndex();
+
+            if (!nextValue) {
+              setValue("");
+            } else if (isImageSource(nextValue)) {
+              setValue(nextValue.trim());
+            }
+          }}
+          onKeyDown={handleKeyDown}
+          onClick={openWithSuggestedSearch}
+          onFocus={(event) => {
+            onFocus?.(event);
+            openWithSuggestedSearch();
+          }}
+          onBlur={(event) => {
+            onBlur?.(event);
+            combobox.closeDropdown();
+            setDraft(value ?? "");
+            setHasEdited(false);
+          }}
+          withAsterisk={withAsterisk}
+          error={error}
+          label={label ?? tCommon("iconPicker.label")}
+          description={tCommon("iconPicker.description")}
+          styles={{
+            description: { color: "var(--mantine-color-text)" },
+            input: { color: "var(--mantine-color-text)" },
+            error: { color: "light-dark(var(--mantine-color-red-9), var(--mantine-color-red-2))" },
+          }}
+          placeholder={placeholderText}
+          autoComplete="off"
+          spellCheck={false}
+        />
      </Combobox.Target>

-      <Combobox.Dropdown>
-        <Combobox.Options mah={350} style={{ overflowY: "auto" }}>
-          {renderDropdown()}
+      <Combobox.Dropdown className={classes.dropdown}>
+        <Combobox.Options className={classes.options} aria-label={tCommon("iconPicker.results")}>
+          {directUrl ? (
+            <Paper p="sm" m="xs" className={classes.urlPreview}>
+              <Group wrap="nowrap" align="center">
+                <Box className={classes.previewFrame}>
+                  {previewState === "loading" && <Loader size={18} className={classes.previewLoader} />}
+                  {previewState === "error" ? (
+                    <ThemeIcon variant="light" color="red" size={40}>
+                      <IconPhotoOff size={21} />
+                    </ThemeIcon>
+                  ) : (
+                    <Image
+                      src={directUrl}
+                      alt=""
+                      w={40}
+                      h={40}
+                      fit="contain"
+                      data-testid="direct-url-preview"
+                      onLoad={() => setPreviewState("ready")}
+                      onError={() => setPreviewState("error")}
+                    />
+                  )}
+                </Box>
+                <Box flex={1} miw={0}>
+                  <Text size="sm" fw={600}>
+                    {previewState === "error"
+                      ? tCommon("iconPicker.urlError")
+                      : previewState === "ready"
+                        ? tCommon("iconPicker.urlReady")
+                        : tCommon("iconPicker.urlLoading")}
+                  </Text>
+                  <Text size="xs" truncate>
+                    {directUrl}
+                  </Text>
+                </Box>
+                {previewState === "ready" && (
+                  <ThemeIcon variant="light" color="green" size="sm" aria-hidden>
+                    <IconCheck size={14} />
+                  </ThemeIcon>
+                )}
+              </Group>
+            </Paper>
+          ) : (
+            renderSearchResults()
+          )}
        </Combobox.Options>
      </Combobox.Dropdown>
    </Combobox>
  );
 };

-// This regex is used to prevent loading a preview like en or /en which would trigger a language change
-// See https://github.com/homarr-labs/homarr/issues/3070
+interface PickerSectionProps {
+  label: string;
+  icon?: React.ReactNode;
+  badge?: string;
+  children: React.ReactNode;
+}
+
+const PickerSection = ({ label, icon, badge, children }: PickerSectionProps) => (
+  <Stack gap={6}>
+    <Group gap={6} px={2}>
+      {icon}
+      <Text size="xs" fw={600}>
+        {label}
+      </Text>
+      {badge && <span className={classes.sectionBadge}>{badge}</span>}
+    </Group>
+    {children}
+  </Stack>
+);
+
+interface PickerMessageProps {
+  icon: React.ReactNode;
+  title: string;
+  action?: React.ReactNode;
+}
+
+const PickerMessage = ({ icon, title, action }: PickerMessageProps) => (
+  <Stack align="center" gap="xs" p="lg" ta="center">
+    <ThemeIcon variant="light" color="gray" size="lg">
+      {icon}
+    </ThemeIcon>
+    <Text size="sm">{title}</Text>
+    {action}
+  </Stack>
+);
+
 const localizationPathRegex = new RegExp(`^/?(${supportedLanguages.join("|")})(/.*)?$`, "i");
 const shouldShowPreview = (value: string | null | undefined): value is string => {
  if (!value) return false;
  return !localizationPathRegex.test(value);
 };
-
-const isDirectIconUrl = (value: string) => {
-  try {
-    const url = new URL(value.trim());
-    return (url.protocol === "http:" || url.protocol === "https:") && Boolean(url.hostname);
-  } catch {
-    return false;
-  }
-};
@@ -0,0 +1,50 @@
+import { describe, expect, test } from "vitest";
+
+import type { IconGroup } from "./icon-picker.utils";
+import { arrangeIconPickerSections, isDirectImageUrl, isImageSource, isSvgImage } from "./icon-picker.utils";
+
+const groups = [
+  {
+    id: "remote",
+    slug: "dashboard-icons",
+    icons: [
+      { id: "long", name: "home-assistant-alt.svg", url: "https://cdn.example.com/home-assistant-alt.svg" },
+      { id: "raster", name: "Home Assistant.png", url: "https://cdn.example.com/home-assistant.png" },
+      { id: "svg", name: "home-assistant.svg", url: "https://cdn.example.com/home-assistant.svg?v=1" },
+    ],
+  },
+  {
+    id: "local",
+    slug: "local",
+    icons: [{ id: "local", name: "Home Assistant.png", url: "/api/user-medias/home-assistant" }],
+  },
+] as IconGroup[];
+
+describe("icon picker utilities", () => {
+  test("arranges local images before remote SVG and raster images", () => {
+    const result = arrangeIconPickerSections(groups, "home assistant");
+
+    expect(result.local.map((icon) => icon.id)).toEqual(["local"]);
+    expect(result.svg.map((icon) => icon.id)).toEqual(["svg", "long"]);
+    expect(result.other.map((icon) => icon.id)).toEqual(["raster"]);
+  });
+
+  test.each([
+    ["https://example.com/icon.png", true],
+    ["http://localhost:3000/icon", true],
+    ["ftp://example.com/icon.png", false],
+    ["javascript:alert(1)", false],
+    ["example.com/icon.png", false],
+  ])("validates direct image URLs", (value, expected) => {
+    expect(isDirectImageUrl(value)).toBe(expected);
+  });
+
+  test("accepts internal image paths without treating search text as a source", () => {
+    expect(isImageSource("/api/user-medias/123")).toBe(true);
+    expect(isImageSource("shopify")).toBe(false);
+  });
+
+  test("recognizes SVG URLs with query strings case-insensitively", () => {
+    expect(isSvgImage("https://example.com/ICON.SVG?raw=1")).toBe(true);
+  });
+});
@@ -0,0 +1,67 @@
+import type { inferRouterOutputs } from "@trpc/server";
+
+import type { AppRouter } from "@homarr/api";
+import { getImageMatchRank, normalizeImageName } from "@homarr/common";
+
+type RouterOutput = inferRouterOutputs<AppRouter>;
+export type IconGroup = RouterOutput["icon"]["findIcons"]["icons"][number];
+export type PickerIcon = IconGroup["icons"][number] & { repositorySlug: string };
+
+export interface IconPickerSections {
+  local: PickerIcon[];
+  svg: PickerIcon[];
+  other: PickerIcon[];
+}
+
+export const arrangeIconPickerSections = (iconGroups: IconGroup[], searchTerm = ""): IconPickerSections => {
+  const sections: IconPickerSections = { local: [], svg: [], other: [] };
+
+  for (const group of iconGroups) {
+    for (const icon of group.icons) {
+      const pickerIcon = { ...icon, repositorySlug: group.slug };
+      if (group.slug === "local") {
+        sections.local.push(pickerIcon);
+      } else if (isSvgImage(icon.url)) {
+        sections.svg.push(pickerIcon);
+      } else {
+        sections.other.push(pickerIcon);
+      }
+    }
+  }
+
+  const normalizedSearch = normalizeImageName(searchTerm);
+  if (normalizedSearch) {
+    const compareMatches = (a: PickerIcon, b: PickerIcon) => {
+      const aRank = getImageMatchRank(normalizedSearch, a.name || a.url) ?? Number.MAX_SAFE_INTEGER;
+      const bRank = getImageMatchRank(normalizedSearch, b.name || b.url) ?? Number.MAX_SAFE_INTEGER;
+      return aRank - bRank || a.name.localeCompare(b.name);
+    };
+    return {
+      local: sections.local.toSorted(compareMatches),
+      svg: sections.svg.toSorted(compareMatches),
+      other: sections.other.toSorted(compareMatches),
+    };
+  }
+
+  return sections;
+};
+
+export const isDirectImageUrl = (value: string) => {
+  try {
+    const url = new URL(value.trim());
+    return (url.protocol === "http:" || url.protocol === "https:") && Boolean(url.hostname);
+  } catch {
+    return false;
+  }
+};
+
+export const isImageSource = (value: string) => isDirectImageUrl(value) || value.trim().startsWith("/");
+
+export const isSvgImage = (value: string) => {
+  try {
+    const url = new URL(value, "http://homarr.local");
+    return url.pathname.toLowerCase().endsWith(".svg");
+  } catch {
+    return value.toLowerCase().split(/[?#]/, 1)[0]?.endsWith(".svg") ?? false;
+  }
+};
@@ -2,7 +2,6 @@ export * from "./new-app/_app-new-form";
 export * from "./new-app/_form";

 export * from "./icon-picker/icon-picker";
-export * from "./new-app/icon-matcher";

 export * from "./upload-media/upload-media";

@@ -3,17 +3,15 @@
 import type { ChangeEventHandler } from "react";
 import { useEffect, useImperativeHandle, useRef } from "react";
 import { Button, Checkbox, Collapse, Group, Stack, Textarea, TextInput } from "@mantine/core";
-import { useDebouncedValue, useDisclosure } from "@mantine/hooks";
+import { useDisclosure } from "@mantine/hooks";
 import type { z } from "zod/v4";

-import { clientApi } from "@homarr/api/client";
 import { useZodForm } from "@homarr/form";
 import { useI18n } from "@homarr/translation/client";
 import { Link } from "@homarr/ui";
 import { appManageSchema } from "@homarr/validation/app";

 import { IconPicker } from "../icon-picker/icon-picker";
-import { findBestIconMatch } from "./icon-matcher";

 type FormType = z.infer<typeof appManageSchema>;

@@ -81,9 +79,6 @@ export const AppForm = ({
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [initialValuesKey]);

-  // Debounce the name value with 200ms delay
-  const [debouncedName] = useDebouncedValue(form.values.name, 200);
-
  const shouldCreateAnother = useRef(false);
  const handleSubmit = (values: FormType) => {
    const redirect = !shouldCreateAnother.current;
@@ -130,29 +125,13 @@ export const AppForm = ({
    }
  };

-  // Auto-select icon based on app name with debounced search
-  const { data: iconsData } = clientApi.icon.findIcons.useQuery(
-    {
-      searchText: debouncedName,
-    },
-    {
-      enabled: debouncedName.length > 3,
-    },
-  );
-
-  useEffect(() => {
-    if (debouncedName && !form.values.iconUrl && iconsData?.icons) {
-      const bestMatch = findBestIconMatch(debouncedName, iconsData.icons);
-      if (bestMatch) {
-        form.setFieldValue("iconUrl", bestMatch);
-      }
-    }
-  }, [debouncedName, iconsData]);
-
  const formFields = (
    <Stack>
      <TextInput {...form.getInputProps("name")} withAsterisk label={t("app.field.name.label")} />
-      <IconPicker {...form.getInputProps("iconUrl")} />
+      <IconPicker
+        {...form.getInputProps("iconUrl")}
+        suggestedSearch={initialValues === undefined ? form.values.name : undefined}
+      />
      <Textarea
        {...form.getInputProps("description")}
        label={t("app.field.description.label")}
@@ -1,30 +0,0 @@
-import type { inferRouterOutputs } from "@trpc/server";
-
-import type { AppRouter } from "@homarr/api";
-
-type RouterOutput = inferRouterOutputs<AppRouter>;
-type IconGroupsOutput = RouterOutput["icon"]["findIcons"]["icons"];
-
-export const findBestIconMatch = (searchTerm: string, iconGroups: IconGroupsOutput): string | null => {
-  const nameLower = searchTerm.toLowerCase();
-  const allIcons = iconGroups.flatMap((group) => group.icons);
-
-  const getIconPriority = (iconUrl: string) => {
-    const fileName = iconUrl.toLowerCase().split("/").pop()?.split(".")[0];
-    if (!fileName) return -1;
-
-    const isSvg = iconUrl.endsWith(".svg");
-    const isExactMatch = fileName === nameLower;
-
-    if (isExactMatch) return isSvg ? 0 : 1;
-    if (fileName.includes(nameLower)) return isSvg ? 2 : 3;
-    return -1;
-  };
-
-  for (let priority = 0; priority <= 3; priority++) {
-    const match = allIcons.find((icon) => getIconPriority(icon.url) === priority);
-    if (match) return match.url;
-  }
-
-  return null;
-};
@@ -54,6 +54,7 @@ import { UmamiIntegration } from "../umami/umami-integration";
 import { UptimeKumaIntegration } from "../uptime-kuma/uptime-kuma-integration";
 import { UnifiControllerIntegration } from "../unifi-controller/unifi-controller-integration";
 import { UnraidIntegration } from "../unraid/unraid-integration";
+import { WudIntegration } from "../wud/wud-integration";
 import type { Integration, IntegrationInput } from "./integration";

 export const createIntegrationAsync = async <TKind extends keyof typeof integrationCreators>(
@@ -133,6 +134,7 @@ export const integrationCreators = {
  beszel: BeszelIntegration,
  bazarr: BazarrIntegration,
  traefik: TraefikIntegration,
+  wud: WudIntegration,
 } satisfies Record<IntegrationKind, IntegrationInstance | [(input: IntegrationInput) => Promise<Integration>]>;

 type IntegrationInstanceOfKind<TKind extends keyof typeof integrationCreators> = {
@@ -134,7 +134,10 @@ export class HomeAssistantIntegration extends Integration implements ISmartHomeI
   */
  private async postAsync(path: `/api/${string}`, body: Record<string, string>) {
    return await fetchWithTrustedCertificatesAsync(this.url(path), {
-      headers: this.getAuthHeaders(),
+      headers: {
+        ...this.getAuthHeaders(),
+        "Content-Type": "application/json",
+      },
      body: JSON.stringify(body),
      method: "POST",
    });
@@ -1,5 +1,6 @@
 // General integrations
 export { ArchiveTeamWarriorIntegration } from "./archive-team-warrior/archive-team-warrior-integration";
+export { WudIntegration } from "./wud/wud-integration";
 export { AdGuardHomeIntegration } from "./adguard-home/adguard-home-integration";
 export { TechnitiumDnsIntegration } from "./technitium/technitium-integration";
 export { AnchorIntegration } from "./anchor/anchor-integration";
@@ -91,6 +92,7 @@ export type {
  ArchiveTeamWarriorItem,
  ArchiveTeamWarriorStatus,
 } from "./archive-team-warrior/archive-team-warrior-types";
+export type { WudStats, WudContainerUpdate } from "./wud/wud-types";

 // Schemas
 export { anchorNotesListInputSchema } from "./anchor/anchor-types";
@@ -85,6 +85,11 @@ export class SynologyClient {
      if (volumesFromV2.length > 0) {
        return volumesFromV2;
      }
+
+      const legacyVolumesFromV2 = this.mapLegacyVolumes(storageV2.vol_info);
+      if (legacyVolumesFromV2.length > 0) {
+        return legacyVolumesFromV2;
+      }
    } catch (error) {
      logger.debug("storage_v2 unavailable, falling back to legacy storage info", {
        integrationId: this.integrationId,
@@ -78,6 +78,7 @@ export const synologyStorageV2VolumeSchema = z

 export const synologyStorageV2DataSchema = z.object({
  volumes: z.array(synologyStorageV2VolumeSchema).optional(),
+  vol_info: z.array(synologyVolumeInfoSchema).optional(),
 });

 export const synologyUtilizationCpuSchema = z.object({
@@ -426,6 +426,60 @@ describe("SynologyIntegration.getSystemInfoAsync", () => {
    expect(result.fileSystem[0]?.deviceName).toBe("volume_1");
  });

+  test("uses vol_info from storage_v2 without falling back to legacy storage", async () => {
+    mockSuccessfulFlow({
+      storageV2: {
+        success: true,
+        data: {
+          vol_info: [
+            {
+              name: "volume_1",
+              used_size: "4000000000",
+              total_size: "10000000000",
+              status: "normal",
+            },
+            {
+              name: "volume_2",
+              used_size: "5000000000",
+              total_size: "20000000000",
+              status: "attention",
+            },
+          ],
+        },
+      },
+    });
+
+    const integration = createIntegration();
+    const result = await integration.getSystemInfoAsync();
+
+    expect(result.fileSystem).toEqual([
+      {
+        deviceName: "volume_1",
+        used: "4000000000",
+        available: "6000000000",
+        percentage: 40,
+      },
+      {
+        deviceName: "volume_2",
+        used: "5000000000",
+        available: "15000000000",
+        percentage: 25,
+      },
+    ]);
+
+    const legacyStorageRequests = mockFetch.mock.calls.filter(([url]) => {
+      const urlString = toUrlString(url);
+
+      return (
+        getApiFromUrl(urlString) === "SYNO.Core.System" &&
+        getMethodFromUrl(urlString) === "info" &&
+        getTypeFromUrl(urlString) === "storage"
+      );
+    });
+
+    expect(legacyStorageRequests).toHaveLength(0);
+  });
+
  test("continues when optional tier-2 calls fail", async () => {
    mockSuccessfulFlow({ skipOptional: true });
    const integration = createIntegration();
@@ -59,10 +59,12 @@ const ws = vi.hoisted(() => {
      }

      const result = responder(payload.method as string, (payload.params as unknown[] | undefined) ?? []);
+      // A responder returning an Error mimics a method the server rejects, e.g. an unsupported filter.
+      const body = result instanceof Error ? { error: { message: result.message } } : { result };
      const envelope =
        payload.jsonrpc === "2.0"
-          ? { jsonrpc: "2.0", id: payload.id, result }
-          : { msg: "result", id: payload.id, result };
+          ? { jsonrpc: "2.0", id: payload.id, ...body }
+          : { msg: "result", id: payload.id, ...body };
      this.respond(JSON.stringify(envelope));
    }

@@ -91,7 +93,10 @@ const ws = vi.hoisted(() => {
  };
 });

+const logs = vi.hoisted(() => ({ debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() }));
+
 vi.mock("ws", () => ({ WebSocket: ws.FakeWebSocket }));
+vi.mock("@homarr/core/infrastructure/logs", () => ({ createLogger: () => logs }));
 vi.mock("@homarr/core/infrastructure/certificates", () => ({
  getAllTrustedCertificatesAsync: vi.fn().mockResolvedValue([]),
  getTrustedCertificateHostnamesAsync: vi.fn().mockResolvedValue([]),
@@ -148,6 +153,14 @@ const happyResponder = (method: string) => {
      ];
    case "pool.query":
      return [{ name: "tank", status: "ONLINE", healthy: true, free: 500, size: 1000, allocated: 500 }];
+    case "pool.dataset.query":
+      return [
+        {
+          id: "tank",
+          used: { parsed: 200 },
+          available: { parsed: 300 },
+        },
+      ];
    case "interface.query":
      return [{ id: "eth0", name: "eth0" }];
    case "reporting.netdata_get_data":
@@ -159,6 +172,11 @@ const happyResponder = (method: string) => {

 const emptyAggregations = () => ({ min: {}, mean: {}, max: {} });

+// `pool.query` reports 500 allocated of a 1000 byte pool, leaving 500 free.
+const physicalFallbackFileSystem = [{ deviceName: "tank", available: "500", used: "500", percentage: 50 }];
+
+const ERROR_MESSAGE_LIMIT = 200;
+
 let integrationCounter = 0;
 const createIntegration = (decryptedSecrets: IntegrationSecret[]) =>
  new TrueNasIntegration({
@@ -180,6 +198,7 @@ describe("TrueNasIntegration", () => {
    ws.constructedUrls.length = 0;
    ws.failures.length = 0;
    ws.setResponder(happyResponder);
+    logs.warn.mockClear();
  });

  test("fetches and maps system info over the JSON-RPC API", async () => {
@@ -191,6 +210,18 @@ describe("TrueNasIntegration", () => {
    // JSON-RPC does not use the legacy "connect" session handshake.
    expect(ws.sentPayloads.some((payload) => payload.msg === "connect")).toBe(false);

+    const datasetPayload = ws.sentPayloads.find((payload) => payload.method === "pool.dataset.query");
+    expect(datasetPayload).toMatchObject({
+      params: [
+        [["id", "in", ["tank"]]],
+        {
+          extra: {
+            properties: ["used", "available"],
+          },
+        },
+      ],
+    });
+
    expect(result).toMatchObject({
      version: "TrueNAS-SCALE-24.10",
      cpuModelName: "Intel Xeon",
@@ -204,12 +235,131 @@ describe("TrueNasIntegration", () => {
      loadAverage: null,
      gpu: [],
      network: { up: 20_000, down: 10_000 },
-      // `available` is the free space left on the pool (free = 500), not its total size.
-      fileSystem: [{ deviceName: "tank", available: "500", used: "500", percentage: 50 }],
+      // `available` and `used` come from the root dataset, not the physical pool.
+      fileSystem: [{ deviceName: "tank", available: "300", used: "200", percentage: 40 }],
      smart: [{ deviceName: "tank", healthy: true, overallStatus: "ONLINE", temperature: null }],
    });
  });

+  test("falls back to physical pool space when the root dataset is not returned", async () => {
+    ws.setResponder((method) => (method === "pool.dataset.query" ? [] : happyResponder(method)));
+    const integration = createIntegration(credentials);
+
+    const result = await integration.getSystemInfoAsync();
+
+    expect(result.fileSystem).toMatchObject(physicalFallbackFileSystem);
+    // Dropping the pool would also hide its health status.
+    expect(result.smart).toMatchObject([{ deviceName: "tank", healthy: true, overallStatus: "ONLINE" }]);
+  });
+
+  test("falls back to physical pool space when the root dataset reports no usable values", async () => {
+    ws.setResponder((method) =>
+      method === "pool.dataset.query"
+        ? [{ id: "tank", used: { parsed: null }, available: null }]
+        : happyResponder(method),
+    );
+    const integration = createIntegration(credentials);
+
+    const result = await integration.getSystemInfoAsync();
+
+    expect(result.fileSystem).toMatchObject(physicalFallbackFileSystem);
+  });
+
+  test("falls back to physical pool space when the root dataset omits the requested properties", async () => {
+    // Datasets that cannot report space, e.g. while locked, come back without `used` and `available`.
+    ws.setResponder((method) =>
+      method === "pool.dataset.query" ? [{ id: "tank", locked: true }] : happyResponder(method),
+    );
+    const integration = createIntegration(credentials);
+
+    const result = await integration.getSystemInfoAsync();
+
+    expect(result.fileSystem).toMatchObject(physicalFallbackFileSystem);
+  });
+
+  test("falls back to physical pool space when the dataset response fails schema validation", async () => {
+    ws.setResponder((method) =>
+      method === "pool.dataset.query" ? { unexpected: "not an array" } : happyResponder(method),
+    );
+    const integration = createIntegration(credentials);
+
+    const result = await integration.getSystemInfoAsync();
+
+    expect(result.fileSystem).toMatchObject(physicalFallbackFileSystem);
+    // A malformed payload must not take the rest of the system info down with it.
+    expect(result).toMatchObject({ cpuTemp: 45, memAvailableInBytes: 6_000_000_000, uptime: 3600 });
+  });
+
+  test("falls back to physical pool space when the dataset query is rejected", async () => {
+    ws.setResponder((method) =>
+      method === "pool.dataset.query"
+        ? new Error("[EINVAL] filters: Value error, Invalid operation: in")
+        : happyResponder(method),
+    );
+    const integration = createIntegration(credentials);
+
+    const result = await integration.getSystemInfoAsync();
+
+    expect(result.fileSystem).toMatchObject(physicalFallbackFileSystem);
+    // A rejected dataset query must not take the rest of the system info down with it.
+    expect(result).toMatchObject({ cpuTemp: 45, memAvailableInBytes: 6_000_000_000, uptime: 3600 });
+  });
+
+  test("logs the truncated rejection reason rather than the generic wrapper message", async () => {
+    // TrueNAS answers a rejected method with its Python traceback, which runs to several kilobytes.
+    ws.setResponder((method) =>
+      method === "pool.dataset.query"
+        ? new Error(`[EINVAL] query-filters ${"x".repeat(5000)}`)
+        : happyResponder(method),
+    );
+    const integration = createIntegration(credentials);
+
+    await integration.getSystemInfoAsync();
+
+    const logged = logs.warn.mock.calls.find(([message]) => String(message).includes("Could not retrieve"));
+    const reason = String((logged?.[1] as { error?: string } | undefined)?.error);
+    // The decorator would otherwise surface only "An unknown error occured while executing Integration method".
+    expect(reason).toContain("[EINVAL] query-filters");
+    expect(reason).toHaveLength(ERROR_MESSAGE_LIMIT + 1); // truncated, plus the ellipsis
+  });
+
+  test("keeps reporting a pool that is unhealthy but has no usable dataset space", async () => {
+    ws.setResponder((method) => {
+      if (method === "pool.query")
+        return [
+          { name: "tank", status: "ONLINE", healthy: true, free: 500, size: 1000, allocated: 500 },
+          { name: "backup", status: "DEGRADED", healthy: false, free: 10, size: 100, allocated: 90 },
+        ];
+      if (method === "pool.dataset.query") return [{ id: "tank", used: { parsed: 200 }, available: { parsed: 300 } }];
+      return happyResponder(method);
+    });
+    const integration = createIntegration(credentials);
+
+    const result = await integration.getSystemInfoAsync();
+
+    expect(result.smart).toMatchObject([
+      { deviceName: "tank", healthy: true, overallStatus: "ONLINE" },
+      { deviceName: "backup", healthy: false, overallStatus: "DEGRADED" },
+    ]);
+    expect(result.fileSystem).toMatchObject([
+      { deviceName: "tank", available: "300", used: "200", percentage: 40 },
+      { deviceName: "backup", available: "10", used: "90", percentage: 90 },
+    ]);
+  });
+
+  test("reports zero usage for an empty root dataset", async () => {
+    ws.setResponder((method) =>
+      method === "pool.dataset.query"
+        ? [{ id: "tank", used: { parsed: 0 }, available: { parsed: 0 } }]
+        : happyResponder(method),
+    );
+    const integration = createIntegration(credentials);
+
+    const result = await integration.getSystemInfoAsync();
+
+    expect(result.fileSystem[0]?.percentage).toBe(0);
+  });
+
  test("authenticates with an API key when one is configured", async () => {
    const integration = createIntegration([{ kind: "apiKey", value: "api-key-123" }]);

@@ -15,6 +15,20 @@ const logger = createLogger({ module: "trueNasIntegration" });

 const NETWORK_MULTIPLIER = 100;

+const ERROR_MESSAGE_LIMIT = 200;
+
+/**
+ * The error decorator replaces a rejected request with a generic message and moves the actionable
+ * reason to `cause`. TrueNAS puts its middleware traceback in there, several kilobytes of it, so the
+ * reason is truncated before it reaches a log line that repeats on every poll.
+ */
+const describeRequestError = (error: unknown) => {
+  const cause = error instanceof Error ? error.cause : undefined;
+  const reason = cause instanceof Error ? cause.message : error instanceof Error ? error.message : String(error);
+
+  return reason.length > ERROR_MESSAGE_LIMIT ? `${reason.slice(0, ERROR_MESSAGE_LIMIT)}…` : reason;
+};
+
 export class TrueNasIntegration extends Integration implements ISystemHealthMonitoringIntegration {
  private client?: TrueNasClient;

@@ -49,9 +63,10 @@ export class TrueNasIntegration extends Integration implements ISystemHealthMoni
      memUsedInBytes,
      fileSystem: datasets.map((dataset) => ({
        deviceName: dataset.name,
-        available: `${dataset.free}`, // free space left on the pool
-        used: `${dataset.allocated}`,
-        percentage: (dataset.allocated / dataset.size) * 100,
+        available: `${dataset.available}`,
+        used: `${dataset.used}`,
+        percentage:
+          dataset.used + dataset.available === 0 ? 0 : (dataset.used / (dataset.used + dataset.available)) * 100,
      })),
      availablePkgUpdates: 0,
      network: {
@@ -107,9 +122,10 @@ export class TrueNasIntegration extends Integration implements ISystemHealthMoni
      .map((pool) => {
        if (pool.allocated !== null && pool.size !== null && pool.free !== null) {
          return {
-            ...pool,
+            name: pool.name,
+            status: pool.status,
+            healthy: pool.healthy,
            allocated: pool.allocated,
-            size: pool.size,
            free: pool.free,
          };
        }
@@ -117,12 +133,76 @@ export class TrueNasIntegration extends Integration implements ISystemHealthMoni
        return null;
      })
      .filter((pool) => pool !== null);
+
    logger.debug("Retrieved pools", {
      url: this.integration.url,
      totalCount: result.length,
      activeCount: activePools.length,
    });
-    return activePools;
+
+    if (activePools.length === 0) return [];
+
+    const usableSpaceByPool = await this.getUsableSpaceByPoolAsync(activePools.map((pool) => pool.name));
+
+    return activePools.map((pool) => {
+      const usableSpace = usableSpaceByPool.get(pool.name);
+      if (!usableSpace) {
+        logger.warn("Falling back to physical pool space, the root dataset reported no usable space", {
+          url: this.integration.url,
+          pool: pool.name,
+        });
+      }
+
+      return {
+        name: pool.name,
+        status: pool.status,
+        healthy: pool.healthy,
+        used: usableSpace?.used ?? pool.allocated,
+        available: usableSpace?.available ?? pool.free,
+      };
+    });
+  }
+
+  /**
+   * Returns the usable space of each pool's root ZFS dataset, keyed by pool name. Unlike the physical
+   * `pool.query` values, these account for RAIDZ parity overhead and dataset limits, matching `zfs list`.
+   * See https://github.com/homarr-labs/homarr/issues/6566
+   *
+   * A pool is left out when its usable space is unavailable, so the caller keeps reporting the pool with
+   * its physical values instead of dropping it, which would also hide its health status:
+   *   - request rejected  → method or `extra.properties` unsupported, or the API key lacks the dataset role
+   *   - response rejected → the payload does not match the expected shape
+   *   - dataset missing   → the pool's root dataset was not returned by the query
+   *   - property absent   → the dataset does not report `used` / `available`, e.g. while locked
+   */
+  private async getUsableSpaceByPoolAsync(poolNames: string[]) {
+    const usableSpaceByPool = new Map<string, { used: number; available: number }>();
+
+    try {
+      const datasets = await this.requestAsync("pool.dataset.query", [
+        [["id", "in", poolNames]],
+        {
+          extra: {
+            properties: ["used", "available"],
+          },
+        },
+      ]);
+
+      for (const dataset of await poolDatasetSchema.parseAsync(datasets)) {
+        const used = dataset.used?.parsed;
+        const available = dataset.available?.parsed;
+        if (typeof used !== "number" || typeof available !== "number") continue;
+
+        usableSpaceByPool.set(dataset.id, { used, available });
+      }
+    } catch (error) {
+      logger.warn("Could not retrieve root dataset space, continuing with physical pool space", {
+        url: this.integration.url,
+        error: describeRequestError(error),
+      });
+    }
+
+    return usableSpaceByPool;
  }

  /**
@@ -263,6 +343,19 @@ const poolSchema = z.array(
  }),
 );

+// Properties are absent or unparsed for datasets that do not report them, e.g. while locked,
+// so they are optional here and the pool falls back to its physical values instead of failing
+// the whole request, which would also drop cpu, memory and network data
+const poolDatasetPropertySchema = z.object({ parsed: z.number().min(0).nullish() }).nullish();
+
+const poolDatasetSchema = z.array(
+  z.object({
+    id: z.string(),
+    used: poolDatasetPropertySchema,
+    available: poolDatasetPropertySchema,
+  }),
+);
+
 const reportingNetDataSchema = z.array(
  z.object({
    name: z.string(),
@@ -37,9 +37,16 @@ export class UnraidIntegration extends Integration implements ISystemHealthMonit
    const systemInfo = await this.getSystemInformationAsync();

    const cpuUtilization = systemInfo.metrics.cpu.cpus.reduce((acc, val) => acc + val.percentTotal, 0);
-    const cpuCount = systemInfo.info.cpu.cores;
+    const cpuCount = systemInfo.metrics.cpu.cpus.length;
+
+    // Each entry in cpus[] is one logical CPU (thread). Dividing the summed per-thread
+    // utilization by the thread count (not physical cores) gives the correct average and
+    // avoids over-reporting on SMT systems. Guard against zero to avoid Infinity/NaN.
+    let cpuUtilizationNormalized = 0;
+    if (cpuCount > 0) {
+      cpuUtilizationNormalized = cpuUtilization / cpuCount;
+    }

-    // We use "info" object instead of the stats since this is the exact amount the kernel sees, which is what Unraid displays.
    const totalMemory = systemInfo.info.memory.layout.reduce((acc, layout) => layout.size + acc, 0);
    const usedMemory = totalMemory * (systemInfo.metrics.memory.percentTotal / 100);
    const uptime = dayjs(systemInfo.info.os.uptime);
@@ -47,7 +54,7 @@ export class UnraidIntegration extends Integration implements ISystemHealthMonit
    return {
      version: systemInfo.info.os.release,
      cpuModelName: systemInfo.info.cpu.brand,
-      cpuUtilization: cpuUtilization / cpuCount,
+      cpuUtilization: cpuUtilizationNormalized,
      memUsedInBytes: usedMemory,
      memAvailableInBytes: totalMemory - usedMemory,
      uptime: dayjs().diff(uptime, "seconds"),
@@ -139,7 +146,7 @@ export class UnraidIntegration extends Integration implements ISystemHealthMonit
          },
          memory {
            layout {
-              size     
+              size
            }
          }
        }
@@ -0,0 +1,269 @@
+// @vitest-environment node
+import { ParseError } from "@homarr/common/server";
+import { Response } from "undici";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+vi.hoisted(() => {
+  process.env.SKIP_ENV_VALIDATION = "true";
+  process.env.SECRET_ENCRYPTION_KEY = "ff3f4f7ce30e870c9630de9e5d244ffa81101a24ed0dfe5f064beb53a7e684f1";
+});
+
+import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
+
+import type { IntegrationTestingInput } from "../../base/integration";
+import { IntegrationParseError } from "../../base/errors/parse/integration-parse-error";
+import type { IntegrationSecret } from "../../base/types";
+import { WudIntegration } from "../wud-integration";
+
+vi.mock("@homarr/core/infrastructure/http", () => ({
+  fetchWithTrustedCertificatesAsync: vi.fn(),
+}));
+
+const TEST_URL = "https://wud.example.com";
+const TEST_USERNAME = "user";
+const TEST_PASSWORD = "p@ss";
+
+const mockFetch = vi.mocked(fetchWithTrustedCertificatesAsync);
+
+const sampleContainersResponse = [
+  {
+    id: "1",
+    name: "homeassistant",
+    displayName: "Home Assistant",
+    updateAvailable: true,
+    link: "https://github.com/home-assistant/core/releases/tag/2024.1.0",
+    image: { tag: { value: "2023.12.0" } },
+    updateKind: { remoteValue: "2024.1.0" },
+  },
+  { id: "2", name: "traefik", updateAvailable: false },
+  {
+    id: "3",
+    name: "grafana",
+    updateAvailable: true,
+    image: { tag: { value: "10.0.0" } },
+    result: { tag: "10.1.0" },
+  },
+];
+
+const sampleUpdates = [
+  {
+    id: "1",
+    name: "Home Assistant",
+    currentVersion: "2023.12.0",
+    newVersion: "2024.1.0",
+    link: "https://github.com/home-assistant/core/releases/tag/2024.1.0",
+  },
+  {
+    id: "3",
+    name: "grafana",
+    currentVersion: "10.0.0",
+    newVersion: "10.1.0",
+    link: null,
+  },
+];
+
+const createIntegration = (decryptedSecrets: IntegrationSecret[] = []) =>
+  new WudIntegration({
+    id: "test-wud",
+    name: "Test WUD",
+    url: TEST_URL,
+    externalUrl: null,
+    decryptedSecrets,
+  });
+
+const createIntegrationWithBasicAuth = () =>
+  createIntegration([
+    { kind: "username", value: TEST_USERNAME },
+    { kind: "password", value: TEST_PASSWORD },
+  ]);
+
+beforeEach(() => {
+  mockFetch.mockReset();
+});
+
+describe("WudIntegration getStatsAsync", () => {
+  test("computes total and available-update counts from the containers list", async () => {
+    mockFetch.mockResolvedValue(
+      new Response(JSON.stringify(sampleContainersResponse), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }) as unknown as Awaited<ReturnType<typeof fetchWithTrustedCertificatesAsync>>,
+    );
+
+    const stats = await createIntegration().getStatsAsync();
+
+    expect(stats).toStrictEqual({ totalContainers: 3, updatesAvailable: 2, updates: sampleUpdates });
+  });
+
+  test("returns zero counts for an empty containers list", async () => {
+    mockFetch.mockResolvedValue(
+      new Response(JSON.stringify([]), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }) as unknown as Awaited<ReturnType<typeof fetchWithTrustedCertificatesAsync>>,
+    );
+
+    const stats = await createIntegration().getStatsAsync();
+
+    expect(stats).toStrictEqual({ totalContainers: 0, updatesAvailable: 0, updates: [] });
+  });
+
+  test("maps container updates using displayName, falling back to result.tag and null link", async () => {
+    mockFetch.mockResolvedValue(
+      new Response(JSON.stringify(sampleContainersResponse), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }) as unknown as Awaited<ReturnType<typeof fetchWithTrustedCertificatesAsync>>,
+    );
+
+    const stats = await createIntegration().getStatsAsync();
+
+    expect(stats.updates).toStrictEqual(sampleUpdates);
+  });
+
+  test("throws ParseError when API response is not valid JSON", async () => {
+    mockFetch.mockResolvedValue(
+      new Response("not-json", {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }) as unknown as Awaited<ReturnType<typeof fetchWithTrustedCertificatesAsync>>,
+    );
+
+    await expect(createIntegration().getStatsAsync()).rejects.toSatisfy((error) => {
+      if (!(error instanceof IntegrationParseError)) return false;
+
+      const cause = error.cause;
+      return cause instanceof ParseError && cause.message.includes("Invalid WUD containers response");
+    });
+  });
+
+  test("throws ParseError when API response does not match schema", async () => {
+    mockFetch.mockResolvedValue(
+      new Response(JSON.stringify({ invalid: true }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }) as unknown as Awaited<ReturnType<typeof fetchWithTrustedCertificatesAsync>>,
+    );
+
+    await expect(createIntegration().getStatsAsync()).rejects.toSatisfy((error) => {
+      if (!(error instanceof IntegrationParseError)) return false;
+
+      const cause = error.cause;
+      return cause instanceof ParseError && cause.message.includes("Invalid WUD containers response");
+    });
+  });
+
+  test("throws when API returns an error", async () => {
+    mockFetch.mockResolvedValue(
+      new Response("Unauthorized", {
+        status: 401,
+        headers: { "content-type": "text/plain" },
+      }) as unknown as Awaited<ReturnType<typeof fetchWithTrustedCertificatesAsync>>,
+    );
+
+    await expect(createIntegration().getStatsAsync()).rejects.toThrow();
+  });
+});
+
+describe("WudIntegration authentication", () => {
+  test("sends no Authorization header when no credentials are configured", async () => {
+    mockFetch.mockResolvedValue(
+      new Response(JSON.stringify(sampleContainersResponse), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }) as unknown as Awaited<ReturnType<typeof fetchWithTrustedCertificatesAsync>>,
+    );
+
+    await createIntegration().getStatsAsync();
+
+    const [, requestInit] = mockFetch.mock.calls[0] ?? [];
+    const headers = (requestInit?.headers ?? {}) as Record<string, string>;
+    expect(headers.Authorization).toBeUndefined();
+  });
+
+  test("sends a Basic auth header when username and password are configured", async () => {
+    mockFetch.mockResolvedValue(
+      new Response(JSON.stringify(sampleContainersResponse), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }) as unknown as Awaited<ReturnType<typeof fetchWithTrustedCertificatesAsync>>,
+    );
+
+    await createIntegrationWithBasicAuth().getStatsAsync();
+
+    const expected = `Basic ${Buffer.from(`${TEST_USERNAME}:${TEST_PASSWORD}`).toString("base64")}`;
+    const [url, requestInit] = mockFetch.mock.calls[0] ?? [];
+    expect(String(url)).toContain("/api/containers");
+    expect(requestInit?.headers).toMatchObject({ Authorization: expected });
+    expect(requestInit?.timeout).toBe(10_000);
+  });
+
+  test("does not send credentials over a non-HTTPS URL", async () => {
+    mockFetch.mockResolvedValue(
+      new Response(JSON.stringify(sampleContainersResponse), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }) as unknown as Awaited<ReturnType<typeof fetchWithTrustedCertificatesAsync>>,
+    );
+
+    const integration = new WudIntegration({
+      id: "test-wud-http",
+      name: "Test WUD HTTP",
+      url: "http://wud.example.com",
+      externalUrl: null,
+      decryptedSecrets: [
+        { kind: "username", value: TEST_USERNAME },
+        { kind: "password", value: TEST_PASSWORD },
+      ],
+    });
+
+    await integration.getStatsAsync();
+
+    const [, requestInit] = mockFetch.mock.calls[0] ?? [];
+    const headers = (requestInit?.headers ?? {}) as Record<string, string>;
+    expect(headers.Authorization).toBeUndefined();
+  });
+});
+
+describe("WudIntegration testing endpoint", () => {
+  type TestingFn = (input: IntegrationTestingInput) => Promise<{ success: boolean }>;
+
+  const invokeTesting = (integration: WudIntegration, input: IntegrationTestingInput) => {
+    const testing = (integration as unknown as { testingAsync: TestingFn }).testingAsync.bind(integration);
+    return testing(input);
+  };
+
+  const makeInput = (response: Response): IntegrationTestingInput =>
+    ({
+      fetchAsync: vi.fn().mockResolvedValue(response),
+    }) as unknown as IntegrationTestingInput;
+
+  test("returns success when /api/app responds 200", async () => {
+    const input = makeInput(new Response(JSON.stringify({ name: "wud", version: "5.0.0" }), { status: 200 }));
+
+    const result = await invokeTesting(createIntegration(), input);
+
+    expect(result.success).toBe(true);
+  });
+
+  test("returns a status-code failure when /api/app responds non-OK", async () => {
+    const input = makeInput(new Response("unauthorized", { status: 401 }));
+
+    const result = await invokeTesting(createIntegration(), input);
+
+    expect(result.success).toBe(false);
+  });
+
+  test("passes the Basic auth header through to fetchAsync when configured", async () => {
+    const response = new Response(JSON.stringify({ name: "wud", version: "5.0.0" }), { status: 200 });
+    const input = makeInput(response);
+
+    await invokeTesting(createIntegrationWithBasicAuth(), input);
+
+    const fetchAsyncMock = vi.mocked(input.fetchAsync);
+    const init = fetchAsyncMock.mock.calls[0]?.[1];
+    const headers = (init?.headers ?? {}) as Record<string, string>;
+    const expected = `Basic ${Buffer.from(`${TEST_USERNAME}:${TEST_PASSWORD}`).toString("base64")}`;
+    expect(headers.Authorization).toBe(expected);
+  });
+});
@@ -0,0 +1,68 @@
+import { Buffer } from "node:buffer";
+
+import { ParseError, ResponseError } from "@homarr/common/server";
+import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
+
+import type { IntegrationTestingInput } from "../base/integration";
+import { Integration } from "../base/integration";
+import { TestConnectionError } from "../base/test-connection/test-connection-error";
+import type { TestingResult } from "../base/test-connection/test-connection-service";
+import type { WudStats } from "./wud-types";
+import { mapWudStats, parseWudContainersResponseAsync } from "./wud-types";
+
+const CONTAINERS_REQUEST_TIMEOUT_MS = 10_000;
+
+export class WudIntegration extends Integration {
+  protected async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
+    const response = await input.fetchAsync(this.url("/api/app"), {
+      headers: this.getAuthHeaders(),
+    });
+
+    if (!response.ok) {
+      return TestConnectionError.StatusResult(response);
+    }
+
+    try {
+      await response.json();
+    } catch (error) {
+      return TestConnectionError.ParseResult(
+        new ParseError("Invalid WUD app response", {
+          cause: error instanceof Error ? error : new Error(String(error)),
+        }),
+      );
+    }
+
+    return { success: true };
+  }
+
+  public async getStatsAsync(): Promise<WudStats> {
+    const response = await fetchWithTrustedCertificatesAsync(this.url("/api/containers"), {
+      headers: this.getAuthHeaders(),
+      timeout: CONTAINERS_REQUEST_TIMEOUT_MS,
+    });
+
+    if (!response.ok) {
+      throw new ResponseError(response);
+    }
+
+    const containers = await parseWudContainersResponseAsync(response);
+
+    return mapWudStats(containers);
+  }
+
+  private getAuthHeaders(): Record<string, string> | undefined {
+    if (!this.hasSecretValue("username") || !this.hasSecretValue("password")) {
+      return undefined;
+    }
+
+    if (this.url("/api/app").protocol !== "https:") {
+      return undefined;
+    }
+
+    const credentials = Buffer.from(`${this.getSecretValue("username")}:${this.getSecretValue("password")}`).toString(
+      "base64",
+    );
+
+    return { Authorization: `Basic ${credentials}` };
+  }
+}
@@ -0,0 +1,81 @@
+import { ParseError } from "@homarr/common/server";
+import { z } from "zod/v4";
+
+const WUD_CONTAINERS_PARSE_ERROR_MESSAGE = "Invalid WUD containers response";
+
+export const wudContainerSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  displayName: z.string().nullable().optional(),
+  updateAvailable: z.boolean(),
+  link: z.string().nullable().optional(),
+  image: z
+    .object({
+      tag: z
+        .object({
+          value: z.string().nullable().optional(),
+        })
+        .optional(),
+    })
+    .optional(),
+  updateKind: z
+    .object({
+      remoteValue: z.string().nullable().optional(),
+    })
+    .optional(),
+  result: z
+    .object({
+      tag: z.string().nullable().optional(),
+    })
+    .optional(),
+});
+
+export const wudContainersResponseSchema = z.array(wudContainerSchema);
+
+export interface WudContainerUpdate {
+  id: string;
+  name: string;
+  currentVersion: string | null;
+  newVersion: string | null;
+  link: string | null;
+}
+
+export interface WudStats {
+  totalContainers: number;
+  updatesAvailable: number;
+  updates: WudContainerUpdate[];
+}
+
+export const parseWudContainersResponseAsync = async (response: {
+  json: () => Promise<unknown>;
+}): Promise<z.infer<typeof wudContainersResponseSchema>> => {
+  let json: unknown;
+  try {
+    json = await response.json();
+  } catch (error) {
+    throw new ParseError(WUD_CONTAINERS_PARSE_ERROR_MESSAGE, {
+      cause: error instanceof Error ? error : new Error(String(error)),
+    });
+  }
+
+  const parseResult = await wudContainersResponseSchema.safeParseAsync(json);
+  if (!parseResult.success) {
+    throw new ParseError(WUD_CONTAINERS_PARSE_ERROR_MESSAGE, { cause: parseResult.error });
+  }
+
+  return parseResult.data;
+};
+
+const mapContainerUpdate = (container: z.infer<typeof wudContainerSchema>): WudContainerUpdate => ({
+  id: container.id,
+  name: container.displayName ?? container.name,
+  currentVersion: container.image?.tag?.value ?? null,
+  newVersion: container.updateKind?.remoteValue ?? container.result?.tag ?? null,
+  link: container.link ?? null,
+});
+
+export const mapWudStats = (containers: z.infer<typeof wudContainersResponseSchema>): WudStats => ({
+  totalContainers: containers.length,
+  updatesAvailable: containers.filter((container) => container.updateAvailable).length,
+  updates: containers.filter((container) => container.updateAvailable).map(mapContainerUpdate),
+});
@@ -0,0 +1,48 @@
+// @vitest-environment node
+
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
+
+import { HomeAssistantIntegration } from "../src";
+
+vi.mock("@homarr/core/infrastructure/http", () => ({
+  fetchWithTrustedCertificatesAsync: vi.fn(),
+}));
+
+const mockFetch = vi.mocked(fetchWithTrustedCertificatesAsync);
+const integration = new HomeAssistantIntegration({
+  id: "home-assistant",
+  name: "Home Assistant",
+  url: "http://home-assistant.local:8123",
+  externalUrl: null,
+  decryptedSecrets: [{ kind: "apiKey", value: "secret" }],
+});
+
+describe("HomeAssistantIntegration actions", () => {
+  beforeEach(() => {
+    mockFetch.mockReset();
+    mockFetch.mockResolvedValue({ ok: true } as never);
+  });
+
+  test.each([
+    ["toggle", () => integration.triggerToggleAsync("light.desk"), "/api/services/homeassistant/toggle", "light.desk"],
+    [
+      "automation",
+      () => integration.triggerAutomationAsync("automation.turn_on_lights"),
+      "/api/services/automation/trigger",
+      "automation.turn_on_lights",
+    ],
+  ])("sends the %s service call as JSON", async (_action, trigger, path, entityId) => {
+    await expect(trigger()).resolves.toBe(true);
+
+    expect(mockFetch).toHaveBeenCalledWith(new URL(`http://home-assistant.local:8123${path}`), {
+      headers: {
+        Authorization: "Bearer secret",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ entity_id: entityId }),
+      method: "POST",
+    });
+  });
+});
@@ -0,0 +1,39 @@
+// @vitest-environment node
+
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+
+import { getServerStatistics, init } from "@immich/sdk";
+import { describe, expect, test, vi } from "vitest";
+
+import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
+
+vi.mock("@homarr/core/infrastructure/certificates", () => ({
+  getAllTrustedCertificatesAsync: vi.fn(async () => []),
+  getTrustedCertificateHostnamesAsync: vi.fn(async () => []),
+}));
+
+describe("real @immich/sdk end-to-end through fetchWithTrustedCertificatesAsync", () => {
+  test("x-api-key set via init() reaches the server", async () => {
+    let receivedXApiKey: string | string[] | undefined;
+    const server = createServer((req, res) => {
+      receivedXApiKey = req.headers["x-api-key"];
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ usage: 1000, photos: 5, videos: 2 }));
+    });
+    await new Promise<void>((resolve) => server.listen(0, resolve));
+    const port = (server.address() as AddressInfo).port;
+
+    init({ baseUrl: `http://127.0.0.1:${port}/api`, apiKey: "sdk-configured-key" });
+    try {
+      const stats = await getServerStatistics({
+        fetch: fetchWithTrustedCertificatesAsync as unknown as typeof fetch,
+      });
+
+      expect(receivedXApiKey).toBe("sdk-configured-key");
+      expect(stats).toMatchObject({ usage: 1000, photos: 5, videos: 2 });
+    } finally {
+      server.close();
+    }
+  });
+});
@@ -6,7 +6,7 @@ import { createIntegrationRequestHandler } from "./lib/integration-request-handl

 export const systemInfoRequestHandler = createIntegrationRequestHandler<
  SystemHealthMonitoring,
-  Exclude<IntegrationKindByCategory<"healthMonitoring">, "proxmox" | "coolify" | "beszel" | "patchmon">,
+  Exclude<IntegrationKindByCategory<"healthMonitoring">, "proxmox" | "coolify" | "beszel" | "patchmon" | "wud">,
  Record<string, never>
 >({
  async requestAsync(integration, _input) {
@@ -18,4 +18,6 @@ export const smartHomeEntityStateRequestHandler = createIntegrationRequestHandle

    return result.data.state;
  },
+  // The widget already polls every 30 seconds and refetches after toggles.
+  cacheTtlMs: 0,
 });
@@ -0,0 +1,11 @@
+import { createIntegrationAsync } from "@homarr/integrations";
+import type { WudStats } from "@homarr/integrations";
+
+import { createIntegrationRequestHandler } from "./lib/integration-request-handler";
+
+export const wudStatsRequestHandler = createIntegrationRequestHandler<WudStats, "wud", Record<string, never>>({
+  async requestAsync(integration) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    return await integrationInstance.getStatsAsync();
+  },
+});
@@ -1018,11 +1018,11 @@
      "releasesProvider": "发布",
      "notifications": "通知",
      "firewall": "防火墙",
-      "timetable": "时刻表",
+      "timetable": "时间表",
      "photoService": "照片",
      "documents": "文档",
      "notes": "笔记",
-      "mediaMonitoring": "监控",
+      "mediaMonitoring": "媒体监控",
      "speedtest": "速度测试",
      "analytics": "分析",
      "vpn": "VPN",
@@ -1310,8 +1310,8 @@
          "newLabel": "新建私钥"
        },
        "slug": {
-          "label": "状态页面标识",
-          "newLabel": "新的状态页面标识"
+          "label": "状态页标识",
+          "newLabel": "新状态页标识"
        }
      }
    },
@@ -1322,7 +1322,7 @@
    },
    "audiobookshelf": {
      "name": "Audiobookshelf",
-      "description": "自托管有声书和播客服务器"
+      "description": "自托管有声读物和播客服务器"
    },
    "navidrome": {
      "name": "Navidrome",
@@ -1330,13 +1330,13 @@
    },
    "uptimeKuma": {
      "name": "Uptime Kuma",
-      "description": "自托管运行时间监控，带有公开状态页",
+      "description": "自托管运行时间监控，支持公开状态页",
      "secret": {
        "slug": {
-          "description": "公开状态页的标识。如果未设置，默认为 \"default\"。"
+          "description": "您公开状态页的标识。如未设置，默认值为“default”。"
        },
        "apiKey": {
-          "description": "用于经过身份验证的 /metrics 访问的可选 API 密钥"
+          "description": "用于访问 /metrics 认证接口的可选 API 密钥"
        }
      }
    },
@@ -1344,9 +1344,13 @@
      "name": "Traefik",
      "description": "云原生反向代理和负载均衡器"
    },
+    "wud": {
+      "name": "What's Up Docker",
+      "description": "监控您哪些 Docker 容器有可用的镜像更新"
+    },
    "paperlessNgx": {
      "name": "Paperless-ngx",
-      "description": "用于归档和组织扫描文档的文档管理系统"
+      "description": "用于归档和整理扫描文档的文档管理系统"
    },
    "patchmon": {
      "name": "PatchMon",
@@ -1398,7 +1402,7 @@
      }
    },
    "noResults": {
-      "title": "未上传媒体"
+      "title": "暂无上传的媒体"
    }
  },
  "common": {
@@ -1437,8 +1441,18 @@
    "here": "这里",
    "iconPicker": {
      "label": "图标 URL",
-      "header": "输入名称或对象来筛选图标… Homarr 将为您搜索 {countIcons} 图标。",
-      "headerLoading": "输入以搜索图标…",
+      "description": "搜索库，粘贴图片URL，或上传文件。",
+      "header": "输入名称或对象来筛选图标… Homarr 将为您搜索 {countIcons} 图标",
+      "headerLoading": "按名称搜索图像",
+      "clear": "清除图像",
+      "uploadImage": "上传图片",
+      "results": "图像搜索结果",
+      "localImages": "你的映像",
+      "svgIcons": "SVG 图标",
+      "otherImages": "其他映像",
+      "urlLoading": "正在检查图片…",
+      "urlReady": "图像已准备好使用",
+      "urlError": "无法加载此图像。请检查URL，然后重试。",
      "noResults": "没有与“{search}”匹配的图标。",
      "error": "无法加载图标。"
    },
@@ -1663,7 +1677,7 @@
        "app": "编辑应用"
      },
      "app": {
-        "propagationNotice": "对此应用的更改将应用于所有面板中使用它的所有位置。"
+        "propagationNotice": "对此应用的更改将应用于所有面板中使用该应用的位置。"
      },
      "advancedOptions": {
        "label": "高级选项",
@@ -1793,6 +1807,38 @@
        }
      }
    },
+    "wud": {
+      "name": "What's Up Docker",
+      "description": "显示有多少个已监控的容器有可用更新。",
+      "title": "What's Up Docker",
+      "monitored": "已监控",
+      "updatesAvailable": "{count, plural, one {# 个更新可用} other {# 个更新可用}}",
+      "updateAvailable": "有可用更新",
+      "openReleaseNotes": "打开发布说明",
+      "option": {
+        "showTitle": {
+          "label": "显示标题"
+        },
+        "showRing": {
+          "label": "显示更新进度环"
+        },
+        "layout": {
+          "label": "布局",
+          "option": {
+            "horizontal": {
+              "label": "水平"
+            },
+            "vertical": {
+              "label": "垂直"
+            }
+          }
+        },
+        "showUpdateList": {
+          "label": "显示容器更新列表",
+          "description": "列出每个有镜像更新可用的已监控容器"
+        }
+      }
+    },
    "dnsHoleSummary": {
      "name": "DNS Hole 摘要",
      "description": "显示 DNS Hole 的摘要",
@@ -2486,7 +2532,7 @@
    },
    "ups": {
      "name": "UPS",
-      "description": "通过 NUT 服务器监控 UPS 设备的状态",
+      "description": "通过 NUT 服务器监控您的 UPS 设备状态",
      "option": {
        "showBattery": {
          "label": "显示电量"
@@ -3784,35 +3830,35 @@
      "option": {
        "showArtists": {
          "label": "显示艺术家",
-          "description": "显示音乐库中艺术家的总数 (Navidrome)"
+          "description": "显示音乐库中的艺术家总数（Navidrome）"
        },
        "showAlbums": {
          "label": "显示专辑",
-          "description": "显示音乐库中专辑的总数 (Navidrome)"
+          "description": "显示音乐库中的专辑总数（Navidrome）"
        },
        "showSongs": {
          "label": "显示歌曲",
-          "description": "显示音乐库中歌曲的总数 (Navidrome)"
+          "description": "显示音乐库中的歌曲总数（Navidrome）"
        },
        "showLibraryCount": {
-          "label": "显示库数量",
-          "description": "显示实例中的库数量 (Audiobookshelf)"
+          "label": "显示媒体库数量",
+          "description": "显示实例中的媒体库数量（Audiobookshelf）"
        },
        "showAudiobooks": {
-          "label": "显示有声书",
-          "description": "显示所有库中的有声书总数 (Audiobookshelf)"
+          "label": "显示有声读物",
+          "description": "显示所有媒体库中的有声读物总数（Audiobookshelf）"
        },
        "showPodcasts": {
          "label": "显示播客",
-          "description": "显示所有库中的播客总数 (Audiobookshelf)"
+          "description": "显示所有媒体库中的播客总数（Audiobookshelf）"
        },
        "showListeningTime": {
-          "label": "显示收听时间",
-          "description": "显示您的总收听时间 (Audiobookshelf)"
+          "label": "显示收听时长",
+          "description": "显示总收听时长（Audiobookshelf）"
        },
        "showActiveSessions": {
          "label": "显示活跃会话",
-          "description": "显示当前活跃的播放会话数量 (Audiobookshelf)"
+          "description": "显示当前活跃播放会话的数量（Audiobookshelf）"
        },
        "compactMode": {
          "label": "紧凑模式",
@@ -3822,8 +3868,8 @@
      "artists": "艺术家",
      "albums": "专辑",
      "songs": "歌曲",
-      "libraryCount": "库",
-      "audiobooks": "有声书",
+      "libraryCount": "媒体库",
+      "audiobooks": "有声读物",
      "podcasts": "播客",
      "listeningTime": "收听时长",
      "activeSessions": "活跃会话",
@@ -3923,10 +3969,10 @@
    },
    "beszelSystemTable": {
      "name": "Beszel 系统（表格）",
-      "description": "所有 Beszel 监控系统的表格视图，具有可排序列和状态指示器",
+      "description": "所有 Beszel 监控系统的表格视图，包含可排序列和状态指示器",
      "option": {
        "statusFilter": {
-          "label": "状态过滤器"
+          "label": "状态筛选"
        },
        "sortBy": {
          "label": "排序方式"
@@ -4057,17 +4103,17 @@
      }
    },
    "beszelAlerts": {
-      "name": "Beszel 警报",
-      "description": "查看 Beszel 警报配置和历史记录",
+      "name": "Beszel 告警",
+      "description": "查看 Beszel 告警配置和历史记录",
      "option": {
        "showHistory": {
-          "label": "显示警报历史"
+          "label": "显示告警历史"
        },
        "maxHistoryItems": {
          "label": "最大历史记录条数"
        }
      },
-      "empty": "未配置警报",
+      "empty": "未配置告警",
      "error": {
        "internalServerError": "无法连接到 Beszel。请检查您的集成设置。"
      },
@@ -4079,15 +4125,15 @@
      }
    },
    "beszelSystemStats": {
-      "name": "Beszel 系统状态",
-      "description": "CPU、内存、磁盘、网络和 Docker 容器指标的时间序列图表",
+      "name": "Beszel 系统统计",
+      "description": "CPU、内存、磁盘、网络和 Docker 容器指标的时序图表",
      "option": {
        "systemId": {
          "label": "系统",
          "description": "选择要显示统计信息的 Beszel 系统"
        },
        "timePeriod": {
-          "label": "时间段"
+          "label": "时间范围"
        },
        "showCpu": {
          "label": "显示 CPU 图表"
@@ -4127,12 +4173,12 @@
      "chart": {
        "cpu": {
          "title": "CPU 使用率",
-          "subtitle": "平均系统 CPU 利用率",
+          "subtitle": "系统整体 CPU 平均使用率",
          "series": "CPU"
        },
        "memory": {
          "title": "内存使用率",
-          "subtitle": "记录时的精确利用率",
+          "subtitle": "记录时间点的精确使用率",
          "series": "已用",
          "cache": "缓存/缓冲区"
        },
@@ -4154,17 +4200,17 @@
        },
        "network": {
          "title": "带宽",
-          "subtitle": "公共接口的网络流量",
-          "sent": "已发送",
+          "subtitle": "公网接口的网络流量",
+          "sent": "发送",
          "recv": "已接收"
        },
        "dockerCpu": {
          "title": "Docker CPU 使用率",
-          "subtitle": "容器的平均 CPU 利用率"
+          "subtitle": "容器的平均 CPU 使用率"
        },
        "dockerMemory": {
          "title": "Docker 内存使用率",
-          "subtitle": "Docker 容器的内存使用"
+          "subtitle": "Docker 容器的内存使用率"
        },
        "dockerNetwork": {
          "title": "Docker 网络 I/O",
@@ -4572,7 +4618,7 @@
            "docker": "Docker",
            "kubernetes": "Kubernetes",
            "logs": "日志",
-            "api": "API",
+            "api": "API 与 MCP",
            "certificates": "证书",
            "tasks": "任务",
            "backup": "备份"
@@ -4690,19 +4736,19 @@
              "firstDayOfWeek": "一周的第一天",
              "accessibility": "无障碍服务",
              "onboardingTours": {
-                "title": "入门指南",
-                "description": "重置入门指南，以便在下次访问管理中心或面板时再次看到它们。",
-                "reset": "重置入门指南",
+                "title": "新手指南",
+                "description": "重置新手指南，以便您下次访问管理区域或面板时再次看到它们。",
+                "reset": "重置新手指南",
                "resetSuccess": {
-                  "title": "指南已重置",
-                  "message": "入门指南将在您下次访问时再次显示"
+                  "title": "新手指南已重置",
+                  "message": "新手指南将在您下次访问时再次显示"
                },
                "status": {
                  "completed": "已完成",
                  "notStarted": "未开始"
                },
                "name": {
-                  "management": "管理中心",
+                  "management": "管理",
                  "dashboard": "面板"
                }
              }
@@ -4829,7 +4875,7 @@
          "analytics": {
            "title": "分析",
            "general": {
-              "title": "发送匿名分析",
+              "title": "协助我们改进 Homarr",
              "text": "这有助于我们了解用户实际使用哪些功能，从而决定将开发精力投入到哪里。我们会收集诸如您拥有多少小组件或集成、Homarr 版本以及使用的数据库类型等信息。仅此而已——不包含个人信息、URL、名称，也不含任何可能识别您本人或您个人配置的内容。"
            }
          },
@@ -5033,84 +5079,84 @@
            "mcp": {
              "label": "AI / MCP",
              "title": "AI 集成",
-              "subtitle": "模型上下文协议 (MCP) 服务器",
-              "description": "将 AI 助手连接到您的 Homarr 实例，通过自然语言控制整个家庭实验室。在 Overseerr 上搜索和请求媒体，管理 Docker 容器，切换 Pi-hole，检查服务器健康状况，控制 Home Assistant 设备等——一切通过您的 AI 助手完成。",
-              "noApiKey": "您需要一个 API 密钥来与 MCP 服务器进行身份验证。",
+              "subtitle": "模型上下文协议（MCP）服务器",
+              "description": "将 AI 助手连接到您的 Homarr 实例，通过自然语言控制您的整个家庭实验室。在 Overseerr 上搜索和请求媒体资源，管理 Docker 容器，切换 Pi-hole，检查服务器健康状态，控制 Home Assistant 设备等——全部通过您的 AI 助手完成。",
+              "noApiKey": "您需要 API 密钥才能通过 MCP 服务器进行认证。",
              "createApiKeyButton": "创建 API 密钥",
              "endpoint": {
                "title": "MCP 端点"
              },
              "authentication": {
                "title": "认证",
-                "intro": "您可以使用 API 密钥或 OAuth 与 MCP 服务器进行身份验证。两种方法授予相同的访问级别。",
+                "intro": "您可以使用 API 密钥或 OAuth 对 MCP 服务器进行认证。两种方法授予的访问权限级别相同。",
                "apiKey": {
-                  "title": "API 密钥 (手动)",
-                  "description": "在 MCP 客户端配置中传递带有完整 API 密钥的 ApiKey 标头。"
+                  "title": "API 密钥（手动）",
+                  "description": "在 MCP 客户端配置中通过 ApiKey 标头传递您的完整 API 密钥。"
                },
                "oauth": {
-                  "title": "OAuth (浏览器登录)",
-                  "description": "支持 OAuth 的客户端（如 Claude Code、opencode 或 Cursor）可以通过打开浏览器窗口进行身份验证。在客户端中运行 auth 命令，在浏览器中登录 Homarr，即可连接——API 密钥会自动创建。",
-                  "hint": "OAuth 令牌在身份验证选项卡中显示为常规 API 密钥。您可以随时撤销它们。"
+                  "title": "OAuth（浏览器登录）",
+                  "description": "支持 OAuth 的客户端（如 Claude Code、opencode 或 Cursor）可通过打开浏览器窗口进行认证。在客户端中运行 auth 命令，在浏览器中登录 Homarr，即可完成连接——API 密钥将自动创建。",
+                  "hint": "OAuth 令牌在“认证”标签页中显示为常规 API 密钥。您可以随时撤销它们。"
                },
-                "permissions": "API 密钥决定了 AI 可用的权限——它与密钥所有者具有相同的访问级别。"
+                "permissions": "PI 密钥决定了 AI 可用的权限——它的访问级别与密钥所有者相同。"
              },
              "clientConfig": {
                "title": "客户端配置",
                "streamableHttp": {
                  "recommended": "推荐",
-                  "title": "可流式 HTTP",
-                  "worksWith": "适用于: Cursor, Claude Desktop, VS Code Copilot, Windsurf, Claude Code",
-                  "addToConfig": "添加到您的 MCP 客户端配置文件：",
-                  "cursor": "{name}: 项目或全局设置中的 {file}",
+                  "title": "可流式传输的 HTTP",
+                  "worksWith": "适用于：Cursor、Claude Desktop、VS Code Copilot、Windsurf、Claude Code",
+                  "addToConfig": "添加到您的 MCP 客户端配置文件中：",
+                  "cursor": "{name}：项目或全局设置中的 {file}",
                  "claudeDesktop": "{name}: {file}",
-                  "claudeCode": "{name}: {file} 或使用 {command}",
-                  "vsCodeCopilot": "{name}: 工作区设置中的 {file}",
+                  "claudeCode": "{name}：{file} 或使用 {command}",
+                  "vsCodeCopilot": "{name}：工作区设置中的 {file}",
                  "replaceHint": "将占位符替换为您在创建时收到的 API 密钥。"
                },
                "stdio": {
-                  "title": "stdio (通过 mcp-remote 桥接的旧客户端)",
-                  "description": "仅支持 stdio 传输的客户端。需要本地安装 {dependency} (Node.js)："
+                  "title": "stdio（通过 mcp-remote 桥接的旧版客户端）",
+                  "description": "适用于仅支持 stdio 传输的客户端。需要本地安装 {dependency}（Node.js）："
                }
              },
              "testConnection": {
                "title": "测试您的连接",
-                "description": "在终端中运行此命令以验证端点是否可达以及 API 密钥是否有效：",
-                "hint": "成功响应将返回 MCP 服务器功能。如果出现错误，请检查 JSON 响应以获取提示。"
+                "description": "在终端中运行以下命令，以验证端点可访问且您的 API 密钥有效：",
+                "hint": "成功响应将返回 MCP 服务器的能力信息。如果看到错误，请检查 JSON 响应中的提示。"
              },
              "availableTools": {
                "title": "可用工具",
-                "description": "{count} 个工具可用。展开类别以查看各个工具及其描述。",
+                "description": "{count} 个工具可用。展开分类可查看各个工具及其描述。",
                "columnType": "类型",
                "columnName": "工具",
                "columnDescription": "描述"
              },
              "troubleshooting": {
-                "title": "故障排除",
+                "title": "故障排查",
                "missingHeader": {
-                  "title": "\"缺少 ApiKey 标头\"",
-                  "description": "您的客户端未发送 {header} 标头。验证 MCP 配置中的 {section} 部分是否正确。某些客户端在配置更改后需要重启。"
+                  "title": "“缺少 ApiKey 标头”",
+                  "description": "您的客户端未发送 {header} 标头。请检查 MCP 配置中的 {section} 部分是否正确。某些客户端在更改配置后需要重启。"
                },
                "invalidFormat": {
-                  "title": "\"无效的 ApiKey 格式\"",
-                  "description": "确保您复制了完整的 API 密钥，而不仅仅是部分。"
+                  "title": "“ApiKey 格式无效”",
+                  "description": "请确保您复制了完整的 API 密钥，而非仅复制了其中一部分。"
                },
                "invalidKey": {
-                  "title": "\"无效的 API 密钥\"",
-                  "description": "找不到密钥 ID 或令牌错误。API 密钥仅在创建时可见一次。如果您丢失了它，请删除旧密钥并创建新密钥。"
+                  "title": "“API 密钥无效”",
+                  "description": "未找到该密钥 ID，或令牌有误。API 密钥仅在创建时可见一次。如已丢失，请删除旧密钥并创建新密钥。"
                },
                "connectionRefused": {
                  "title": "连接被拒绝 / 超时",
-                  "description": "确保 URL 可从您的 AI 客户端访问。如果 Homarr 在反向代理或 Docker 后运行，请使用外部 URL (不是 {localhost})。验证端口是否正确 (默认: Docker 为 7575)。"
+                  "description": "请确保您的 AI 客户端能够访问该 URL。如果 Homarr 运行在反向代理后或 Docker 中，请使用外部 URL（而非 {localhost}）。请确认端口是否正确（Docker 默认端口为 7575）。"
                },
                "toolsNotAppearing": {
-                  "title": "工具未出现",
-                  "description": "某些工具需要配置特定的集成（例如 Docker、Overseerr）。工具列表取决于 Homarr 实例中的可用内容。"
+                  "title": "工具未显示",
+                  "description": "部分工具需要先配置特定的集成（例如 Docker、Overseerr）。工具列表取决于您的 Homarr 实例中可用的功能。"
                }
              },
              "copy": "复制",
              "oneClick": {
                "title": "一键安装",
-                "subtitle": "使用 OAuth — 首次使用时在浏览器中进行身份验证",
+                "subtitle": "使用 OAuth 认证——首次使用时在浏览器中进行身份验证",
                "vsCode": "在 VS Code 中安装",
                "cursor": "在 Cursor 中安装",
                "copyUrl": "复制 MCP URL",
@@ -5123,16 +5169,16 @@
        },
        "backup": {
          "title": "完整数据库备份",
-          "metaTitle": "备份与恢复",
+          "metaTitle": "备份 & 恢复",
          "export": {
            "title": "导出数据库",
-            "description": "下载包含所有设置、用户、面板和加密集成密钥的 SQLite 数据库的完整备份。备份打包为 ZIP 文件，附带加密密钥和元数据。",
-            "button": "下载备份",
+            "description": "下载 SQLite 数据库的完整备份，包含所有设置、用户、面板和加密的集成密钥。备份文件以 ZIP 格式打包，内含加密密钥和元数据。",
+            "button": "备份下载",
            "error": "导出失败",
            "confirm": {
              "title": "敏感数据导出",
-              "warningTitle": "此导出包含您的整个数据库。",
-              "warningBody": "备份包括所有用户、集成密钥（加密）、API 密钥、面板配置和应用数据。将导出的文件安全存储，不要分享。",
+              "warningTitle": "此导出包含您的完整数据库。",
+              "warningBody": "备份包含所有用户、集成密钥（已加密）、API 密钥、面板配置和应用数据。请妥善保管导出的文件，切勿分享。",
              "typePrompt": "输入 \"{phrase}\" 以继续",
              "submit": "导出数据库",
              "cancel": "取消"
@@ -5140,23 +5186,23 @@
          },
          "import": {
            "title": "恢复数据库",
-            "description": "上传先前导出的备份 ZIP 以恢复您的数据库。这将替换您的整个数据库。如果备份是使用不同的加密密钥创建的，密钥将自动重新加密。",
-            "warning": "恢复备份将完全替换您当前的数据库并重启应用程序。此操作无法撤销。",
+            "description": "上传之前导出的备份 ZIP 文件以恢复数据库。此操作将替换整个数据库。如果备份使用的加密密钥不同，密钥将自动重新加密。",
+            "warning": "恢复备份将完全替换当前数据库并重启应用。此操作不可撤销。",
            "dropzone": {
-              "title": "将备份 ZIP 拖到此处或点击浏览",
-              "description": "仅接受 Homarr SQLite 备份的 .zip 文件"
+              "title": "将备份 ZIP 文件拖放到此处，或点击浏览",
+              "description": "仅接受来自 Homarr SQLite 备份的 .zip 文件"
            },
            "changeFile": "更改文件",
            "button": "恢复数据库",
            "success": {
              "title": "恢复完成",
-              "message": "数据库已成功恢复。应用程序正在重启……"
+              "message": "数据库已成功恢复。应用正在重启……"
            },
            "error": "导入失败"
          },
          "preview": {
            "title": "备份内容",
-            "exported": "导出时间：{date}",
+            "exported": "导出于 {date}",
            "loading": "正在分析备份文件……",
            "errorTitle": "预览错误",
            "entity": "实体",
@@ -5172,13 +5218,13 @@
              "search_engine": "搜索引擎"
            },
            "analyzeError": "分析备份文件失败",
-            "invalidMissingMetadata": "无效备份：缺少 metadata.json",
-            "invalidMissingDb": "无效备份：缺少 db.sqlite"
+            "invalidMissingMetadata": "备份无效：缺少 metadata.json 文件",
+            "invalidMissingDb": "备份无效：缺少 db.sqlite 文件"
          },
          "restore": {
            "dropzone": {
-              "title": "将备份 ZIP 拖到此处",
-              "description": "接受 Homarr SQLite 备份的 .zip 文件（最大 256 MB）"
+              "title": "将备份 ZIP 文件拖放到此处",
+              "description": "仅接受来自 Homarr SQLite 备份的 .zip 文件（最大 256 MB）"
            },
            "analyzing": "正在分析备份……",
            "changeFile": "更改文件",
@@ -5187,7 +5233,7 @@
            "analysisError": "分析错误",
            "preview": {
              "title": "备份内容",
-              "exported": "导出时间：{date}",
+              "exported": "导出于 {date}",
              "entity": "实体",
              "count": "数量",
              "boards": "面板",
@@ -5200,43 +5246,43 @@
                "media": "媒体",
                "search_engine": "搜索引擎"
              },
-              "migrationsApplied": "已应用 {count} 个迁移",
-              "migrationsAppliedPlural": "已应用 {count} 个迁移",
-              "migrationsOlderVersion": "此备份来自较旧的 Homarr 版本。已应用 {count} 个架构迁移以使其更新。",
-              "migrationsOlderVersionPlural": "此备份来自较旧的 Homarr 版本。已应用 {count} 个架构迁移以使其更新。",
-              "migrationsUpToDate": "数据库架构已是最新（已应用 {count} 个迁移）",
-              "upToDate": "已更新",
-              "migrationsPending": "{count} 个待处理"
+              "migrationsApplied": "已应用 {count} 项迁移",
+              "migrationsAppliedPlural": "已应用 {count} 项迁移",
+              "migrationsOlderVersion": "此备份来自较旧版本的 Homarr。已应用 {count} 项数据库迁移以将其更新至最新版本。",
+              "migrationsOlderVersionPlural": "此备份来自较旧版本的 Homarr。已应用 {count} 项数据库迁移以将其更新至最新版本。",
+              "migrationsUpToDate": "数据库架构已为最新（已应用 {count} 项迁移）",
+              "upToDate": "已是最新",
+              "migrationsPending": "{count} 项待处理"
            },
            "migration": {
-              "title": "正在应用迁移 ({current}/{total})",
+              "title": "正在应用迁移（{current}/{total}）",
              "migrationLabel": "迁移 {index}"
            },
            "confirm": {
              "title": "破坏性操作",
              "warningTitle": "这将永久替换您的整个数据库。",
-              "warningBody": "所有当前面板、用户、应用、集成、设置和会话都将丢失。此操作无法撤销。应用将在恢复后重启。",
+              "warningBody": "所有现有面板、用户、应用、集成、设置和会话都将丢失。此操作不可撤销。恢复完成后应用将重启。",
              "typePrompt": "输入 \"{phrase}\" 以继续",
              "cancel": "取消",
              "submit": "恢复数据库"
            },
            "progress": {
              "title": "正在恢复数据库……",
-              "extracting": "提取备份存档",
-              "migrating": "应用数据库迁移",
-              "encrypting": "重新加密集成密钥",
-              "swapping": "替换数据库文件",
-              "restarting": "重启服务器"
+              "extracting": "正在解压备份压缩包",
+              "migrating": "正在应用数据库迁移",
+              "encrypting": "正在重新加密集成密钥",
+              "swapping": "正在替换数据库文件",
+              "restarting": "正在重启服务器"
            },
            "complete": {
              "title": "恢复完成",
-              "message": "数据库已成功恢复。服务器正在重启——请几秒钟后刷新页面。"
+              "message": "数据库已成功恢复。服务器正在重启——请稍后刷新页面。"
            },
            "failed": {
              "title": "恢复失败"
            },
-            "invalidMissingMetadata": "无效备份：缺少 metadata.json",
-            "invalidMissingDb": "无效备份：缺少 db.sqlite",
+            "invalidMissingMetadata": "备份无效：缺少 metadata.json 文件",
+            "invalidMissingDb": "备份无效：缺少 db.sqlite 文件",
            "analyzeError": "分析备份失败"
          }
        }
@@ -5918,14 +5964,14 @@
            "title": "偏好设置",
            "children": {
              "detail": {
-                "title": "选择要更改的偏好",
-                "backHint": "按 Backspace 或使用返回按钮返回",
+                "title": "选择要更改的偏好设置",
+                "backHint": "按 Backspace 键或使用返回按钮返回",
                "backAction": "返回"
              }
            },
            "notification": {
              "error": {
-                "message": "无法更新偏好"
+                "message": "无法更新偏好设置"
              }
            },
            "option": {
@@ -5938,11 +5984,11 @@
              },
              "board": {
                "none": "无",
-                "unavailable": "当前选择（不可用）"
+                "unavailable": "当前已选（不可用）"
              },
              "searchEngine": {
                "none": "无",
-                "unavailable": "当前选择（不可用）"
+                "unavailable": "当前已选（不可用）"
              },
              "colorScheme": {
                "label": "配色方案",
@@ -5977,42 +6023,42 @@
                }
              },
              "ddgBangs": {
-                "label": "启用 DuckDuckGo bangs",
+                "label": "启用 DuckDuckGo Bang 快捷搜索",
                "children": {
                  "detail": {
-                    "title": "启用 DuckDuckGo bangs"
+                    "title": "启用 DuckDuckGo Bang 快捷搜索"
                  }
                }
              },
              "firstDayOfWeek": {
-                "label": "一周的第一天",
+                "label": "每周的第一天",
                "children": {
                  "detail": {
-                    "title": "选择一周的第一天"
+                    "title": "选择每周的第一天"
                  }
                }
              },
              "homeBoardId": {
-                "label": "主面板",
+                "label": "默认面板",
                "children": {
                  "detail": {
-                    "title": "选择您的主面板"
+                    "title": "选择您的默认面板"
                  }
                }
              },
              "mobileHomeBoardId": {
-                "label": "移动端主面板",
+                "label": "移动端默认面板",
                "children": {
                  "detail": {
-                    "title": "选择您的移动端主面板"
+                    "title": "选择您的移动端默认面板"
                  }
                }
              },
              "pingIconsEnabled": {
-                "label": "为 ping 使用图标",
+                "label": "使用图标表示 ping 状态",
                "children": {
                  "detail": {
-                    "title": "为 ping 使用图标"
+                    "title": "使用图标表示 ping 状态"
                  }
                }
              },
@@ -6032,16 +6078,16 @@
        }
      },
      "media": {
-        "help": "搜索电影或节目以请求",
+        "help": "搜索要请求的电影或剧集",
        "requestMovie": "请求电影",
        "requestSeries": "请求电视节目",
        "openIn": "在 {kind} 中打开",
        "group": {
-          "title": "电影和节目"
+          "title": "电影和剧集"
        },
        "action": {
          "search": {
-            "label": "搜索电影或节目",
+            "label": "搜索电影或剧集",
            "description": "开始输入以搜索您的媒体请求集成",
            "disabled": {
              "noIntegration": "添加 Overseerr、Jellyseerr 或 Seerr 集成以启用媒体搜索。",
@@ -6456,39 +6502,39 @@
    "manage": {
      "welcome": {
        "title": "欢迎使用 Homarr！",
-        "description": "这是您的控制中心。您可以在此管理面板、应用、集成、用户和服务器设置。让我们浏览每个部分。"
+        "description": "这是您的控制中心。您可以在这里管理面板、应用、集成、用户和服务器设置。让我们逐一了解每个部分。"
      },
      "boardsList": {
        "title": "您的面板",
-        "description": "这里是您的所有面板。每个面板都有自己的布局、背景和访问设置。您可以查看每个面板的创建者以及它是公开的还是私有的。"
+        "description": "这里是您的所有面板。每个面板都有自己的布局、背景和访问设置。您可以查看每个面板的创建者以及它是公开还是私有的。"
      },
      "boardsCreate": {
        "title": "创建面板",
-        "description": "点击此处创建新面板或从以前的 Homarr 安装中导入。每个面板都有自己可共享的 URL。"
+        "description": "点击此处创建新面板，或从之前的 Homarr 安装中导入。每个面板都有独立的可分享链接。"
      },
      "appsList": {
        "title": "您的应用",
-        "description": "这些是您添加的所有应用——指向自托管服务的链接。每个应用都有图标、可选的健康检查和面板上的状态徽章。"
+        "description": "这些是您已添加的所有应用——指向您自托管服务的链接。每个应用都配有图标、可选的健康检查，并在面板上显示状态标记。"
      },
      "appsCreate": {
        "title": "添加应用",
-        "description": "在此注册新服务。为其命名、URL 和图标——它将作为磁贴显示在您的面板上，并带有实时状态监控。"
+        "description": "在此处注册新服务。设置名称、URL 和图标后，它将以磁贴形式出现在您的面板上，并带有实时状态监控。"
      },
      "integrationsList": {
        "title": "您的集成",
-        "description": "这些是连接到 Homarr 的服务——Sonarr、Radarr、Plex、Jellyfin 及 50 多种其他服务。所有凭据在静态时均加密。"
+        "description": "这些是已连接到 Homarr 的服务——Sonarr、Radarr、Plex、Jellyfin 以及 50 多种其他服务。所有凭证均以加密方式存储。"
      },
      "integrationsCreate": {
        "title": "添加集成",
-        "description": "在此连接新服务。选择类型，输入 URL 和 API 密钥——Homarr 在保存前会验证连接。"
+        "description": "在此处连接新服务。选择类型，输入 URL 和 API 密钥——Homarr 会在保存前验证连接。"
      },
      "usersList": {
        "title": "您的用户",
-        "description": "查看所有有访问权限的人员。将用户组织到组中，并控制谁可以查看或编辑每个面板。"
+        "description": "查看所有拥有访问权限的用户。将用户归入不同组别，并控制谁可以查看或编辑每个面板。"
      },
      "usersCreate": {
        "title": "创建用户",
-        "description": "在此添加新用户账户。您也可以使用邀请链接方便地引入。导览到此结束——您已准备就绪！"
+        "description": "在此处添加新用户账号。您也可以使用邀请链接简化入门流程。导览已结束——您已准备就绪！"
      }
    },
    "board": {
@@ -6502,15 +6548,15 @@
      },
      "settings": {
        "title": "面板设置",
-        "description": "更改此面板的名称、列数、背景、颜色以及访问权限。每个面板可以是公开或私有的。"
+        "description": "更改此面板的名称、列数、背景、颜色以及访问权限。每个面板均可设为公开或私有。"
      },
      "switcher": {
        "title": "切换面板",
-        "description": "在面板间跳转。为不同目的创建独立的面板——媒体、网络、按用户或任何您喜欢的。"
+        "description": "在不同面板之间跳转。您可以为不同用途创建独立的面板——媒体、网络、按用户划分，或任何您喜欢的分类。"
      },
      "userMenu": {
        "title": "您的个人资料",
-        "description": "更改您的配色方案、语言、主面板和偏好。您也可以从此处跳转到管理中心。"
+        "description": "更改您的配色方案、语言、默认面板和偏好设置。您也可以从这里跳转到管理区域。"
      }
    }
  }
@@ -1344,6 +1344,10 @@
      "name": "crwdns5753:0crwdne5753:0",
      "description": "crwdns5755:0crwdne5755:0"
    },
+    "wud": {
+      "name": "crwdns6193:0crwdne6193:0",
+      "description": "crwdns6195:0crwdne6195:0"
+    },
    "paperlessNgx": {
      "name": "crwdns5003:0crwdne5003:0",
      "description": "crwdns5005:0crwdne5005:0"
@@ -1437,8 +1441,18 @@
    "here": "crwdns552:0crwdne552:0",
    "iconPicker": {
      "label": "crwdns554:0crwdne554:0",
-      "header": "crwdns556:0{countIcons}crwdne556:0",
-      "headerLoading": "crwdns5681:0crwdne5681:0",
+      "description": "crwdns6225:0crwdne6225:0",
+      "header": "crwdns6227:0{countIcons}crwdne6227:0",
+      "headerLoading": "crwdns6229:0crwdne6229:0",
+      "clear": "crwdns6231:0crwdne6231:0",
+      "uploadImage": "crwdns6233:0crwdne6233:0",
+      "results": "crwdns6235:0crwdne6235:0",
+      "localImages": "crwdns6237:0crwdne6237:0",
+      "svgIcons": "crwdns6239:0crwdne6239:0",
+      "otherImages": "crwdns6241:0crwdne6241:0",
+      "urlLoading": "crwdns6243:0crwdne6243:0",
+      "urlReady": "crwdns6245:0crwdne6245:0",
+      "urlError": "crwdns6247:0crwdne6247:0",
      "noResults": "crwdns5683:0{search}crwdne5683:0",
      "error": "crwdns5685:0crwdne5685:0"
    },
@@ -1793,6 +1807,38 @@
        }
      }
    },
+    "wud": {
+      "name": "crwdns6197:0crwdne6197:0",
+      "description": "crwdns6199:0crwdne6199:0",
+      "title": "crwdns6201:0crwdne6201:0",
+      "monitored": "crwdns6203:0crwdne6203:0",
+      "updatesAvailable": "crwdns6205:0count={count}crwdne6205:0",
+      "updateAvailable": "crwdns6207:0crwdne6207:0",
+      "openReleaseNotes": "crwdns6209:0crwdne6209:0",
+      "option": {
+        "showTitle": {
+          "label": "crwdns6211:0crwdne6211:0"
+        },
+        "showRing": {
+          "label": "crwdns6213:0crwdne6213:0"
+        },
+        "layout": {
+          "label": "crwdns6215:0crwdne6215:0",
+          "option": {
+            "horizontal": {
+              "label": "crwdns6217:0crwdne6217:0"
+            },
+            "vertical": {
+              "label": "crwdns6219:0crwdne6219:0"
+            }
+          }
+        },
+        "showUpdateList": {
+          "label": "crwdns6221:0crwdne6221:0",
+          "description": "crwdns6223:0crwdne6223:0"
+        }
+      }
+    },
    "dnsHoleSummary": {
      "name": "crwdns768:0crwdne768:0",
      "description": "crwdns770:0crwdne770:0",
@@ -1344,6 +1344,10 @@
      "name": "",
      "description": ""
    },
+    "wud": {
+      "name": "Hvad Er Opad Docker",
+      "description": "Overvåg hvilke af dine Docker-containere der er tilgængelige billedopdateringer"
+    },
    "paperlessNgx": {
      "name": "Paperless-ngx",
      "description": "Dokumenthåndteringssystem til arkivering og organisering af scannede dokumenter"
@@ -1437,8 +1441,18 @@
    "here": "her",
    "iconPicker": {
      "label": "Ikon-URL",
-      "header": "Indtast navn eller objekter for at filtrere for ikoner... Homarr vil søge gennem {countIcons} ikoner for dig.",
-      "headerLoading": "",
+      "description": "Søg i biblioteket, indsæt en billed-URL, eller upload en fil.",
+      "header": "Søg efter {countIcons} billeder efter navn",
+      "headerLoading": "Søg billeder efter navn",
+      "clear": "Ryd billede",
+      "uploadImage": "Upload billede",
+      "results": "Billede søgeresultater",
+      "localImages": "Dine billeder",
+      "svgIcons": "SVG ikoner",
+      "otherImages": "Andre billeder",
+      "urlLoading": "Kontrollerer billede…",
+      "urlReady": "Billedet er klar til brug",
+      "urlError": "Dette billede kunne ikke indlæses. Tjek URL'en og prøv igen.",
      "noResults": "",
      "error": ""
    },
@@ -1793,6 +1807,38 @@
        }
      }
    },
+    "wud": {
+      "name": "Hvad Er Opad Docker",
+      "description": "Vis hvor mange overvågede containere der er tilgængelige opdateringer.",
+      "title": "Hvad Er Opad Docker",
+      "monitored": "Overvåget",
+      "updatesAvailable": "{count, plural, one {# opdatering tilgængelig} other {# opdateringer tilgængelige}}",
+      "updateAvailable": "Opdatering tilgængelig",
+      "openReleaseNotes": "Åbn udgivelsesnoter",
+      "option": {
+        "showTitle": {
+          "label": "Vis titel"
+        },
+        "showRing": {
+          "label": "Vis opdateringsring"
+        },
+        "layout": {
+          "label": "Layout",
+          "option": {
+            "horizontal": {
+              "label": "Horisontal"
+            },
+            "vertical": {
+              "label": "Vertikal"
+            }
+          }
+        },
+        "showUpdateList": {
+          "label": "Vis liste over container-opdatering",
+          "description": "Lister hver overvåget beholder, der har en billedopdatering tilgængelig"
+        }
+      }
+    },
    "dnsHoleSummary": {
      "name": "DNS Hole Oversigt",
      "description": "Viser oversigten over dit DNS-hul",
@@ -3047,7 +3093,7 @@
      "option": {
        "albumId": {
          "label": "Album ID",
-          "description": "Dette er et unikt ID som refererer til dit Immich album. Du kan finde dette id ved at åbne et album og kopiere den unikke streng fra URL, for eksempel 'a21aca09-9f05-47dc-b1a1-7b53c547226e'"
+          "description": "Dette er et unikt ID som refererer til dit Immich album. Du kan finde dette id ved at åbne et album og kopiere den unikke streng fra URL, for eksempel 'a21aca09-9f05-47dc-b1a1-7b53c547226e'."
        },
        "rotationIntervalSeconds": {
          "label": "Interval i sekunder",
Author	SHA1	Message	Date
ajnart	bbe13f5d39	fix(ci): use pinned pnpm for releases	2026-09-06 21:02:59 +02:00
Thomas	32a51c1e60	feat: announce Homarr v2 beta (#6793 ) * feat: announce Homarr v2 beta * chore: refine v2 beta announcement * feat: expand v2 beta guidance * chore: refine v2 beta resources * chore: simplify v2 beta modal * chore: improve v2 beta feedback links * fix: keep v2 modal above header * chore: sharpen v2 beta message * fix: clear header for v2 modal	2026-09-06 20:36:04 +02:00
homarr-crowdin[bot]	da32acb4f0	chore(lang): updated translations from crowdin * chore(lang): update translations from crowdin * chore(lang): update translations from crowdin * chore(lang): update translations from crowdin --------- Co-authored-by: Crowdin Homarr <190541745+homarr-crowdin[bot]@users.noreply.github.com>	2026-09-06 01:52:04 +00:00
homarr-update-contributors[bot]	1da13d9bb3	chore: update contributors (#6767 ) Co-authored-by: Homarr Update Contributors <210161987+homarr-update-contributors[bot]@users.noreply.github.com>	2026-09-04 15:58:09 +00:00
homarr-crowdin[bot]	cb0fec088f	chore(lang): updated translations from crowdin * chore(lang): update translations from crowdin * chore(lang): update translations from crowdin --------- Co-authored-by: Crowdin Homarr <190541745+homarr-crowdin[bot]@users.noreply.github.com>	2026-09-03 02:05:21 +00:00
homarr-crowdin[bot]	a2fe8dd461	chore(lang): updated translations from crowdin Co-authored-by: Crowdin Homarr <190541745+homarr-crowdin[bot]@users.noreply.github.com>	2026-09-01 02:36:36 +00:00
homarr-update-contributors[bot]	b6dfcd69ba	chore: update contributors (#6735 ) Co-authored-by: Homarr Update Contributors <210161987+homarr-update-contributors[bot]@users.noreply.github.com>	2026-08-28 21:54:00 +00:00
homarr-crowdin[bot]andThomas	a38b0ef71d	chore(lang): updated translations from crowdin (#6732 ) Co-authored-by: Thomas <thomas@ajnart.fr>	2026-08-28 14:07:42 +02:00
Thomas	2cf3027eeb	Merge pull request #6720 from homarr-labs/docs/update-helm-docs docs(helm): update chart installation page	2026-08-28 08:32:40 +02:00
homarr-releases[bot]	fa18f6fc71	chore: update bug report template (#6724 )	2026-08-28 08:32:03 +02:00
Releases Homarr	331925c197	chore(release): 1.76.2 [skip ci]	2026-08-27 20:09:22 +00:00
Thomas	0e51f745d3	Merge pull request #6723 from homarr-labs/dev chore(release): automatic release v1.76.2	2026-08-27 22:08:05 +02:00
Thomas	d6f720d0e6	Revert "feat(http): set custom User-Agent on outbound integration requests (#6606 )" (#6722 ) This reverts commit `ddbf05524b`.	2026-08-27 22:00:23 +02:00
Thomas	5324bf12d4	fix(startup): use stable internal service addresses (#6721 )	2026-08-27 21:52:54 +02:00
github-actions[bot]	2922a02ecf	docs(helm): update chart installation page	2026-08-27 17:09:27 +00:00
Thomas	87cdcf28e0	fix(mcp): return valid string for void tool results (#6703 )	2026-08-27 11:10:37 +02:00
homarr-releases[bot]	441b181e79	chore: update bug report template (#6716 ) Co-authored-by: Releases Homarr <175486441+homarr-releases[bot]@users.noreply.github.com>	2026-08-27 11:08:43 +02:00
Releases Homarr	eba639b59c	chore(release): 1.76.1 [skip ci]	2026-08-26 16:43:52 +00:00
Thomas Camlong	da36283ad1	chore(release): retrigger release pipeline	2026-08-26 18:30:12 +02:00
Thomas Camlong	c050368782	chore(release): trigger release pipeline	2026-08-26 18:16:26 +02:00
homarr-releases[bot]	82b50f0fd7	chore(release): automatic release v1.76.1	2026-08-26 15:50:55 +00:00
Thomas	a0149d5894	Merge pull request #6673 from homarr-labs/investigate-6672-immich-401	2026-08-22 19:44:03 +02:00
ajnart	8579fcbfc2	test(http,immich): address CodeRabbit review - guarantee server teardown via try/finally in both wire-level tests - add tuple-array HeadersInit coverage to the helper suite	2026-08-22 17:21:38 +02:00
ajnart	b6f3aba23e	test(http,immich): prove User-Agent fix at the wire level Add two regression tests that fail on v1.76.0 and pass with the fix: - wire-level test: a Headers instance (the shape @immich/sdk hands over) must reach the remote server with all headers intact - real-SDK e2e: getServerStatistics through fetchWithTrustedCertificatesAsync against a live local server must deliver x-api-key	2026-08-22 17:16:31 +02:00
ajnart	31e218295d	fix(http): preserve SDK headers when injecting User-Agent The v1.76.0 User-Agent injection object-spread `fetchOptions.headers`, which silently drops all headers when the value is a Headers instance. The Immich SDK passes a Headers object with the merged x-api-key header, so requests lost their API key and returned 401 (issue #6672). Build a real Headers instance instead, keeping case-insensitive user-agent handling.	2026-08-22 17:12:43 +02:00
Thomas	aca3b5d861	fix: correct Unraid CPU, link context menus, and board resizing (#6510 ) Fix Unraid logical CPU averaging, preserve native context menus for app and bookmark widgets in view mode, and prevent scrollbar-width GridStack resize oscillation.	2026-08-22 10:53:26 +02:00
homarr-crowdin[bot]	a7a2f0223a	chore(lang): updated translations from crowdin (#6596 ) Co-authored-by: Crowdin Homarr <190541745+homarr-crowdin[bot]@users.noreply.github.com>	2026-08-22 08:49:51 +02:00
homarr-releases[bot]	7773fdc10b	chore: update bug report template (#6655 )	2026-08-21 22:14:45 +02:00
Thomas	7019a1d0a4	Merge pull request #6656 from homarr-labs/docs/update-helm-docs	2026-08-21 22:14:26 +02:00
github-actions[bot]	2d535caeac	docs(helm): update chart installation page	2026-08-21 17:41:09 +00:00
Releases Homarr	2013fbe80d	chore(release): 1.76.0 [skip ci]	2026-08-21 17:20:50 +00:00
homarr-releases[bot]	219ef58926	chore(release): automatic release v1.76.0	2026-08-21 17:19:40 +00:00
homarr-update-contributors[bot]	97195bc463	chore: update contributors (#6649 ) Co-authored-by: Homarr Update Contributors <210161987+homarr-update-contributors[bot]@users.noreply.github.com>	2026-08-21 12:53:40 +00:00
Danura30082	73a742154e	docs: Proxmox certificate obtention instructions (#6613 )	2026-08-20 18:51:58 +02:00
Afonso Jorge Ramos	993a267e0c	fix(truenas): keep reporting pools without usable dataset space (#6635 )	2026-08-20 15:37:10 +02:00
Thomas	f1c49d1fbf	fix(startup): only chown runtime paths for custom PUID/PGID (#6598 )	2026-08-19 08:29:17 +02:00
Thomas	95c66c61eb	fix(widgets): stop Health Monitoring system tab firing NOT_FOUND when Proxmox is mixed in (#6623 )	2026-08-18 19:56:47 +02:00
Thomas	ec2f8c6c2c	fix(widgets): match OMV disk temperature via normalized partition names (#6615 ) (#6619 ) OMV reports filesystem devices (sda1) without the /dev/ prefix, so the partition-suffix normalization never applied and filesystem-to-SMART matching returned no temperature. Strip partition suffixes from unprefixed sd/vd, nvme and mmcblk names, and use the shared normalized matcher in both the health monitoring and system disks widgets.	2026-08-18 19:39:27 +02:00
Thomas	05ba57c2fa	chore: migrate cursor rules to portable agent skills + mantine MCP guidance * chore: migrate cursor rules to portable agent skills and add mantine MCP guidance Replace Cursor-only .cursor/rules/.mdc with Agent Skills open-standard SKILL.md files in .agents/skills/ (canonical), mirrored to .cursor/skills/ and .claude/skills/ so they work across Claude Code, Cursor, Codex, and OpenCode. Add mantine MCP server guidance to AGENTS.md and un-ignore .agents/skills/ in .gitignore. refactor: single-source agent skills at .agents/skills Cursor, Codex, and OpenCode all read .agents/skills/ natively, so the .cursor/skills/ mirror was redundant. Claude Code reads .claude/skills/, which is now a symlink back to .agents/skills/ so the content lives once. Deletes .cursor/skills/ and converts .claude/skills/ to a symlink. * chore: ship mantine MCP server via project-scoped .mcp.json Declares the keyless @mantine/mcp-server in .mcp.json (Claude Code project-scope standard, committable) and documents MCP server setup and the mantine entry in AGENTS.md. * chore: address coderabbit security-review and markdown lint findings Add explicit security-review guidance before exposing MCP tools and label plain-text code fences to satisfy markdownlint MD040.	2026-08-16 16:27:51 +02:00
Thomas	ddbf05524b	feat(http): set custom User-Agent on outbound integration requests (#6606 ) * feat(http): set custom User-Agent on outbound integration requests Set a default 'User-Agent: Homarr/<version> (+https://homarr.dev)' header on all outbound HTTP requests made via fetchWithTrustedCertificatesAsync, so Homarr's integration traffic is distinguishable in reverse-proxy, WAF, and security-monitoring logs instead of appearing as generic undici. Closes #6604 * refactor(version): centralize Homarr version in @homarr/version package Replace fragile deep-relative 'package.json' imports across the monorepo with a single source of truth: the new @homarr/version leaf package reads the version once from the root package.json and exports it as VERSION. Consumers now import by package name incl. the new User-Agent header in fetchWithTrustedCertificatesAsync (packages/core): - core, api (info router), analytics, request-handler (update checker) This also removes all manually-maintained relative version imports. * fix(http): normalize User-Agent injection with Headers Object-spreading fetchOptions.headers breaks when callers pass a Headers instance (spread yields no entries) or a tuple array (numeric keys), and is case-sensitive. Build a Headers instance and set the default User-Agent only when no case-insensitive User-Agent entry exists, via a shared helper in both fetch paths. Adds unit tests covering record, Headers, tuple-array, and casing variants. * revert(version): undo version refactor and tests, keep single-file change Keep the User-Agent change as a single edit to packages/core/src/infrastructure/http/request.ts. Remove the @homarr/version package, the consumer migrations, and the unit tests.	2026-08-16 16:09:15 +02:00
Thomas	df438b4cd2	Merge pull request #6571 from homarr-labs/feat/fix-home-assistant-actions	2026-08-16 00:23:14 +02:00
Thomas	a1f91eb385	Merge pull request #6567 from homarr-labs/feat/fix-truenas-free-space	2026-08-15 20:20:35 +02:00
Thomas	8d5ffb2dd9	feat(paseo): add worktree install script (#6599 ) * feat(paseo): add worktree install script * feat(paseo): inline worktree setup in paseo.json * feat(paseo): add scripts and teardown to paseo.json * feat(paseo): expand workspace scripts catalog * feat(paseo): reset encryption key in worktree env	2026-08-15 12:29:52 +02:00
Thomas Camlong	56e6b23af6	test(e2e): remove flaky credentials onboarding test	2026-08-15 11:05:06 +02:00
Thomas Camlong	5488bf4d18	fix(truenas): use lowercase in operator for dataset query	2026-08-15 01:33:20 +02:00
homarr-crowdin[bot]	621ea07549	chore(lang): updated translations from crowdin (#6553 )	2026-08-14 20:39:02 +02:00
homarr-update-contributors[bot]	f64c01456b	chore: update contributors (#6588 )	2026-08-14 20:38:42 +02:00
homarr-releases[bot]	56198c3f02	chore: update bug report template (#6591 )	2026-08-14 20:38:26 +02:00
Thomas	ca1bb6f341	Merge pull request #6592 from homarr-labs/docs/update-helm-docs docs(helm): update chart installation page	2026-08-14 20:38:10 +02:00
github-actions[bot]	bf6b6663cd	docs(helm): update chart installation page	2026-08-14 18:25:32 +00:00
Releases Homarr	5c2d86767f	chore(release): 1.75.0 [skip ci]	2026-08-14 17:45:24 +00:00
homarr-releases[bot]	7c75642d4d	chore(release): automatic release v1.75.0	2026-08-14 17:43:56 +00:00
Thomas Camlong	7652eb8c1c	preserve smart home toggle response	2026-08-13 17:04:00 +02:00
Thomas Camlong	e761c10f32	fix Home Assistant widget actions	2026-08-13 16:21:48 +02:00
Thomas	2513e8454f	fix: open user menu instantly (#6568 )	2026-08-13 11:44:10 +02:00
ajnart	f6137b2dcc	fix(truenas): guard empty dataset percentage	2026-08-12 18:24:33 +02:00
ajnart	425dd90871	fix(truenas): report usable dataset space	2026-08-12 18:19:07 +02:00
Thomas	527e911eef	fix(beszel): let Recharts own tooltip lifecycle (#6560 )	2026-08-11 15:35:17 +02:00
Thomas	ff2cdecc86	feat: rewrite image picker (#6556 ) * feat: rewrite image picker * style: auto-fix lint and format * fix: address image picker review * fix: preserve unicode icon searches * test: stabilize custom widget login * fix: suggest image searches only on create	2026-08-11 14:49:52 +02:00
Sven	742bde1d27	fix(synology): support vol_info in storage_v2 responses (#6554 )	2026-08-11 08:59:28 +00:00
homarr-update-contributors[bot]	64febbce12	chore: update integrations list readme (#6551 ) Co-authored-by: Homarr Update Contributors <210161987+homarr-update-contributors[bot]@users.noreply.github.com>	2026-08-10 11:44:39 +00:00
TimonandThomas	98bb1aecf8	feat(integrations): add What's Up Docker (WUD) integration and widget (#6523 ) Co-authored-by: Thomas <thomas@ajnart.fr>	2026-08-10 08:42:23 +00:00